diff --git a/.github/workflows/auto-tag-on-release-pr-merge.yml b/.github/workflows/auto-tag-on-release-pr-merge.yml
index f31d4b835f..3a090b3ebd 100644
--- a/.github/workflows/auto-tag-on-release-pr-merge.yml
+++ b/.github/workflows/auto-tag-on-release-pr-merge.yml
@@ -45,7 +45,7 @@ jobs:
       github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ github.event.pull_request.merge_commit_sha }}
           fetch-depth: 0
diff --git a/.github/workflows/benchmark-harbor.yml b/.github/workflows/benchmark-harbor.yml
index 31efe933c5..6024f00575 100644
--- a/.github/workflows/benchmark-harbor.yml
+++ b/.github/workflows/benchmark-harbor.yml
@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: "3.12"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 453a15de99..60507182d5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -28,7 +28,7 @@ jobs:
       web: ${{ steps.filter.outputs.web }}
       mobile: ${{ steps.filter.outputs.mobile }}
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 2
       - uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
@@ -96,7 +96,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
@@ -117,7 +117,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: rui314/setup-mold@9c9c13bf4c3f1adef0cc596abc155580bcb04444 # v1
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
@@ -139,7 +139,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 2
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
@@ -235,7 +235,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - name: Get pnpm store directory
         id: pnpm-cache
@@ -318,7 +318,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       # Reuse the relay binaries and backend test archive when none of their
       # inputs changed (desktop-only PRs hit this every time). The key covers
@@ -391,7 +391,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - name: Start integration services
         run: |
@@ -580,7 +580,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - name: Install cargo-nextest
         uses: taiki-e/install-action@0fd46367812ee04360509b4169d9f659d6892bb2 # v2.79.15
@@ -692,6 +692,18 @@ jobs:
             --run-ignored ignored-only
         env:
           DATABASE_URL: postgres://buzz:${{ env.BUZZ_TEST_POSTGRES_PASSWORD }}@localhost:5432/buzz
+      - name: Workspace profile (kind:9033) gate tests
+        # Call-site integration for the 9033 authorization gate: open relay
+        # rosterless/steward transitions and the closed-relay admin/owner rule,
+        # against real Postgres. #[ignore]d in the default suite, selected
+        # explicitly here — see handlers::relay_admin::tests.
+        run: |
+          cargo nextest run \
+            --archive-file target/ci/backend-integration-tests.tar.zst \
+            -E 'package(buzz-relay) and test(/handlers::relay_admin::tests/)' \
+            --run-ignored ignored-only
+        env:
+          DATABASE_URL: postgres://buzz:${{ env.BUZZ_TEST_POSTGRES_PASSWORD }}@localhost:5432/buzz
       - name: NIP-ER reminder e2e
         # Feature e2e for NIP-ER (Event Reminders, kind:30300): write-path
         # validation, author-only read filtering, and scheduler delivery against
@@ -732,7 +744,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
@@ -773,7 +785,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 2
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
@@ -808,7 +820,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 2
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
@@ -869,7 +881,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - name: Dependency policy
         run: cargo-deny check
@@ -881,7 +893,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - name: Check for dead API token references in client code
         run: |
           # Fail if dead API token patterns reappear in desktop, mobile, docs, or config.
@@ -910,7 +922,7 @@ jobs:
           - x86_64-unknown-linux-musl
           - aarch64-unknown-linux-musl
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
@@ -947,7 +959,7 @@ jobs:
     env:
       TARGET: x86_64-pc-windows-msvc
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       # MSVC needs windows.h (aws-lc-sys et al.), so this runs on a real Windows
       # runner — hermit, used by the Linux jobs, does not provide MSVC. The
       # toolchain (1.95.0 + clippy via profile = default) comes from the
@@ -1028,7 +1040,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
@@ -1042,6 +1054,7 @@ jobs:
           mkdir -p desktop/src-tauri/binaries
           touch "desktop/src-tauri/binaries/buzz-acp-$TARGET"
           touch "desktop/src-tauri/binaries/buzz-agent-$TARGET"
+          touch "desktop/src-tauri/binaries/buzz-backend-kubernetes-$TARGET"
           touch "desktop/src-tauri/binaries/buzz-dev-mcp-$TARGET"
           touch "desktop/src-tauri/binaries/git-credential-nostr-$TARGET"
           touch "desktop/src-tauri/binaries/buzz-$TARGET"
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 52f21b28bc..564cd74e9d 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -101,7 +101,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -359,7 +359,7 @@ jobs:
             arch: arm64
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
diff --git a/.github/workflows/helm-chart.yml b/.github/workflows/helm-chart.yml
index e3d443d9f3..7118d16708 100644
--- a/.github/workflows/helm-chart.yml
+++ b/.github/workflows/helm-chart.yml
@@ -59,7 +59,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           # On chart-tag rescue dispatch, lint/render the tagged commit that the
           # publish job will package, not whatever `main` is when the dispatch
@@ -119,7 +119,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           fetch-depth: 0
 
@@ -166,7 +166,7 @@ jobs:
       packages: write    # push the chart to GHCR
     steps:
       - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           # On the rescue dispatch, build the tagged commit (github.ref is
           # `main` there); on a tag push, the default ref is already the tag.
diff --git a/.github/workflows/linux-canary.yml b/.github/workflows/linux-canary.yml
index 9806443378..e1625f4ec8 100644
--- a/.github/workflows/linux-canary.yml
+++ b/.github/workflows/linux-canary.yml
@@ -166,11 +166,11 @@ jobs:
 
       - name: Build sidecars
         run: |
-          cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
           ./scripts/bundle-sidecars.sh
 
       - name: Build Linux Tauri app
-        run: cd desktop && pnpm tauri build --ci --bundles deb,appimage --config src-tauri/tauri.canary.conf.json
+        run: cd desktop && pnpm tauri build --ci --bundles deb,appimage --features mesh-llm --config src-tauri/tauri.canary.conf.json
         env:
           CMAKE_POLICY_VERSION_MINIMUM: "3.5"
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 7d5f3fbf40..9da067b74e 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -36,7 +36,7 @@ jobs:
             exit 1
           fi
 
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -64,7 +64,7 @@ jobs:
     env:
       VERSION: ${{ needs.setup.outputs.version }}
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ needs.setup.outputs.source_sha }}
           fetch-depth: 0
@@ -91,7 +91,7 @@ jobs:
 
       - name: Build sidecars
         run: |
-          cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
           ./scripts/bundle-sidecars.sh
 
       # Mesh rev derived from Cargo.lock (no lockstep edit on dep bump); cache key tracks it.
@@ -278,7 +278,7 @@ jobs:
       VERSION: ${{ needs.setup.outputs.version }}
       TARGET: x86_64-apple-darwin
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ needs.setup.outputs.source_sha }}
           fetch-depth: 0
@@ -308,7 +308,7 @@ jobs:
 
       - name: Build sidecars
         run: |
-          cargo build --release --target "$TARGET" -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          cargo build --release --target "$TARGET" -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
           ./scripts/bundle-sidecars.sh "$TARGET"
 
       - name: Build unsigned Tauri app
@@ -495,7 +495,7 @@ jobs:
           apt-get update
           apt-get install -y --no-install-recommends gh
 
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ needs.setup.outputs.source_sha }}
           fetch-depth: 0
@@ -563,7 +563,7 @@ jobs:
 
       - name: Build sidecars
         run: |
-          cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
           ./scripts/bundle-sidecars.sh
 
       - name: Generate release config
@@ -573,7 +573,7 @@ jobs:
           BUZZ_UPDATER_ENDPOINT: https://github.com/block/buzz/releases/download/buzz-desktop-latest/latest.json
 
       - name: Build Linux Tauri app
-        run: cd desktop && pnpm tauri build --verbose --ci --bundles deb,appimage --config src-tauri/tauri.release.conf.json
+        run: cd desktop && pnpm tauri build --verbose --ci --bundles deb,appimage --features mesh-llm --config src-tauri/tauri.release.conf.json
         env:
           BUZZ_UPDATER_PUBLIC_KEY: ${{ secrets.BUZZ_UPDATER_PUBLIC_KEY || secrets.SPROUT_UPDATER_PUBLIC_KEY }}
           BUZZ_UPDATER_ENDPOINT: https://github.com/block/buzz/releases/download/buzz-desktop-latest/latest.json
@@ -666,7 +666,7 @@ jobs:
       VERSION: ${{ needs.setup.outputs.version }}
       TARGET: x86_64-pc-windows-msvc
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ needs.setup.outputs.source_sha }}
           fetch-depth: 0
@@ -795,7 +795,7 @@ jobs:
       VERSION: ${{ needs.setup.outputs.version }}
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           ref: ${{ needs.setup.outputs.source_sha }}
           fetch-depth: 0
diff --git a/.github/workflows/signed-macos-canary.yml b/.github/workflows/signed-macos-canary.yml
index fb0656028a..0a3a513eef 100644
--- a/.github/workflows/signed-macos-canary.yml
+++ b/.github/workflows/signed-macos-canary.yml
@@ -93,7 +93,7 @@ jobs:
 
       - name: Build sidecars
         run: |
-          cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
+          cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli
           ./scripts/bundle-sidecars.sh
 
       # Mesh rev derived from Cargo.lock (no lockstep edit on dep bump); cache key tracks it.
diff --git a/.github/workflows/sprig-image.yml b/.github/workflows/sprig-image.yml
new file mode 100644
index 0000000000..5d5e12ae0c
--- /dev/null
+++ b/.github/workflows/sprig-image.yml
@@ -0,0 +1,233 @@
+name: Sprig image
+
+# Builds and publishes the public agent container image as
+# ghcr.io/block/buzz-sprig — the digest-pinned box the Kubernetes backend
+# deploys agents into (see Dockerfile.sprig and docs/remote-agents.md).
+#
+# Strategy mirrors docker.yml (the relay image): each architecture builds on
+# its native runner, pushes to GHCR by digest, then a merge job stitches the
+# per-arch digests into one multi-arch manifest and attests provenance.
+# No QEMU emulation.
+#
+# Triggers:
+#   - push to main (paths-filtered) → :main + :sha-<7>
+#   - tag sprig-v*                  → semver family (shared with sprig.yml's
+#                                     binary release — one tag versions both)
+#   - pull_request (paths-filtered) → build only, no push
+#   - workflow_dispatch             → manual publish at the current ref
+#
+# NOTE: the first push creates the GHCR package PRIVATE by default. An org
+# admin must flip ghcr.io/block/buzz-sprig to public once (Package settings →
+# Change visibility). Subsequent pushes keep the visibility.
+
+on:
+  push:
+    branches: [main]
+    tags: ["sprig-v[0-9]*"]
+    paths:
+      - "Dockerfile.sprig"
+      - "scripts/sprig-entrypoint.sh"
+      - ".github/workflows/sprig-image.yml"
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "rust-toolchain.toml"
+      - "crates/**"
+  pull_request:
+    paths:
+      - "Dockerfile.sprig"
+      - "scripts/sprig-entrypoint.sh"
+      - ".github/workflows/sprig-image.yml"
+  workflow_dispatch: {}
+
+concurrency:
+  group: sprig-image-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref_type == 'branch' && github.event_name == 'pull_request' }}
+
+permissions: {}
+
+env:
+  # Single source of truth for the image name; override with the
+  # GHCR_SPRIG_IMAGE repo variable (same pattern as docker.yml).
+  IMAGE_NAME: ${{ vars.GHCR_SPRIG_IMAGE != '' && vars.GHCR_SPRIG_IMAGE || 'ghcr.io/block/buzz-sprig' }}
+
+jobs:
+  build:
+    name: Build (${{ matrix.platform }})
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 60
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+      attestations: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-24.04
+            arch: amd64
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+            arch: arm64
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
+        with:
+          # Same OOM cap as docker.yml — Rust compiles blow the 7GB runner
+          # at buildkit's default parallelism of 4.
+          buildkitd-config-inline: |
+            [worker.oci]
+              max-parallelism = 2
+
+      - name: Log in to GHCR
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee  # v4.2.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9  # v6.1.0
+        with:
+          images: ${{ env.IMAGE_NAME }}
+          # match=^sprig-v(.*)$ strips the tag prefix for the semver parser,
+          # exactly as docker.yml does for relay-v. :latest comes from
+          # flavor.latest=auto — stable semver only, never main pushes.
+          tags: |
+            type=ref,event=branch
+            type=sha,prefix=sha-,format=short
+            type=semver,pattern={{version}},match=^sprig-v(.*)$
+            type=semver,pattern={{major}}.{{minor}},match=^sprig-v(.*)$
+          labels: |
+            org.opencontainers.image.title=Buzz Sprig
+            org.opencontainers.image.description=Agent runtime image for Buzz remote agents (buzz-acp multicall + git + curl)
+            org.opencontainers.image.licenses=Apache-2.0
+
+      - name: Build and push by digest
+        id: build
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf  # v7.2.0
+        with:
+          context: .
+          file: ./Dockerfile.sprig
+          platforms: ${{ matrix.platform }}
+          labels: ${{ steps.meta.outputs.labels }}
+          outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=${{ github.event_name != 'pull_request' }}
+          cache-from: |
+            type=registry,ref=${{ env.IMAGE_NAME }}-buildcache:${{ matrix.arch }}
+          cache-to: |
+            ${{ (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) && format('type=registry,ref={0}-buildcache:{1},mode=max,compression=zstd', env.IMAGE_NAME, matrix.arch) || '' }}
+
+      - name: Export digest
+        if: github.event_name != 'pull_request'
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+        run: |
+          mkdir -p /tmp/digests
+          touch "/tmp/digests/${DIGEST#sha256:}"
+
+      - name: Upload digest
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: sprig-digest-${{ matrix.arch }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  merge:
+    name: Merge multi-arch manifest
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-24.04
+    needs: build
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+      attestations: write
+
+    steps:
+      - name: Download per-arch digests
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          path: /tmp/digests
+          pattern: sprig-digest-*
+          merge-multiple: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
+
+      - name: Log in to GHCR
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee  # v4.2.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9  # v6.1.0
+        with:
+          images: ${{ env.IMAGE_NAME }}
+          # Must mirror the build job's tag matrix exactly (see docker.yml).
+          flavor: |
+            latest=auto
+          tags: |
+            type=ref,event=branch
+            type=sha,prefix=sha-,format=short
+            type=semver,pattern={{version}},match=^sprig-v(.*)$
+            type=semver,pattern={{major}}.{{minor}},match=^sprig-v(.*)$
+
+      - name: Create and push manifest list
+        id: manifest
+        working-directory: /tmp/digests
+        env:
+          IMAGE_NAME: ${{ env.IMAGE_NAME }}
+          META_TAGS: ${{ steps.meta.outputs.tags }}
+        run: |
+          set -euo pipefail
+          tags=()
+          while IFS= read -r tag; do
+            [ -n "$tag" ] && tags+=("-t" "$tag")
+          done <<< "$META_TAGS"
+
+          digests=()
+          for digest in *; do
+            digests+=("${IMAGE_NAME}@sha256:${digest}")
+          done
+
+          docker buildx imagetools create "${tags[@]}" "${digests[@]}"
+
+          first_tag=$(echo "$META_TAGS" | head -n1)
+          merged_digest=$(docker buildx imagetools inspect "$first_tag" \
+            --format '{{json .Manifest}}' | jq -r '.digest')
+          echo "digest=${merged_digest}" >> "$GITHUB_OUTPUT"
+
+      - name: Attest provenance for the merged image
+        # Verify with: gh attestation verify oci://ghcr.io/block/buzz-sprig:<tag> --owner block
+        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373  # v4.1.1
+        with:
+          subject-name: ${{ env.IMAGE_NAME }}
+          subject-digest: ${{ steps.manifest.outputs.digest }}
+          push-to-registry: true
+
+      - name: Summary
+        env:
+          IMAGE_NAME: ${{ env.IMAGE_NAME }}
+          DIGEST: ${{ steps.manifest.outputs.digest }}
+        run: |
+          {
+            echo "### Sprig image published"
+            echo '```'
+            echo "${IMAGE_NAME}@${DIGEST}"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/sprig.yml b/.github/workflows/sprig.yml
index b2dab3583f..5e50808b3b 100644
--- a/.github/workflows/sprig.yml
+++ b/.github/workflows/sprig.yml
@@ -42,7 +42,7 @@ jobs:
           - x86_64-unknown-linux-musl
           - aarch64-unknown-linux-musl
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # v1
 
@@ -116,7 +116,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Download all Sprig artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -154,7 +154,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Download all Sprig artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
diff --git a/.release/desktop-candidate.json b/.release/desktop-candidate.json
index 1bf2efb66b..1ba64765ff 100644
--- a/.release/desktop-candidate.json
+++ b/.release/desktop-candidate.json
@@ -1,8 +1,8 @@
 {
   "schema": 1,
-  "version": "0.5.3",
-  "base_sha": "54c8ef30a9bb9c59a4415a8a7ee84c7c5454b48a",
-  "previous_tag": "v0.5.2",
-  "tag": "desktop-v0.5.3",
-  "commit_count": 58
+  "version": "0.5.4",
+  "base_sha": "6de85fe31d781122756aecf954bae7d357a56b9a",
+  "previous_tag": "desktop-v0.5.3",
+  "tag": "desktop-v0.5.4",
+  "commit_count": 40
 }
diff --git a/AGENTS.md b/AGENTS.md
index 7ff0eb4d47..7cd43061b2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,14 +13,14 @@ Buzz spans five repos. This one (`block/buzz`) is the OSS source for the relay,
 | Repo | Purpose |
 |------|---------|
 | [block/buzz](https://github.com/block/buzz) | OSS source — relay, desktop app, mobile app, CLI, agent harness |
-| [squareup/sprout-releases](https://github.com/squareup/sprout-releases) | Buildkite pipeline producing Block-signed macOS + iOS builds with `-block` version suffix |
+| [squareup/buzz-releases](https://github.com/squareup/buzz-releases) | Buildkite pipelines producing Block-signed macOS + iOS builds with `-block` desktop version suffix |
 | [squareup/sprout-oss](https://github.com/squareup/sprout-oss) | CI pipeline building the relay Docker image and pushing to internal ECR |
 | [squareup/block-coder-tf-stacks](https://github.com/squareup/block-coder-tf-stacks) | Terraform + ArgoCD deploying the relay to the staging Kubernetes cluster |
 | [squareup/sprout-backend-blox](https://github.com/squareup/sprout-backend-blox) | Desktop backend provider script connecting Blox workstation agents to the relay |
 
 ```
 block/buzz (source)
-  ├─► sprout-releases    (desktop + mobile builds → Artifactory, GitHub, Mobile Releases)
+  ├─► buzz-releases      (desktop + mobile builds → Artifactory, GitHub, Mobile Releases)
   ├─► sprout-oss         (relay Docker image → ECR)
   │     └─► block-coder-tf-stacks  (Helm chart → ArgoCD → staging cluster)
   └─── sprout-backend-blox         (Blox compute provider for Desktop agent launch)
@@ -145,6 +145,10 @@ first, then implement handling in the relay.
 
 **Channel scoping**: Channels use `h` tags (NIP-29 group tag), not `e` tags.
 Filters and queries must scope to `h` tags when operating within a channel.
+This applies to events *inside* a channel. Addressable events that describe a
+channel carry its id in their `d` tag instead: kind:39000 (metadata),
+kind:39001, kind:39002 (membership). `get_channels` resolves a user's channels
+from the `d` tag of their kind:39002 events, not from `h`.
 
 **Agent-facing operations go in `buzz-cli`**: New agent-facing features belong in `buzz-cli` — add a subcommand there first, then wire the REST/WebSocket call in `client.rs`. `buzz-dev-mcp` (shell + file tools for `buzz-agent`) is separate.
 
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 5c8e263a2a..892082d96c 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -139,7 +139,7 @@ The `kind` integer is the only dispatch switch. The relay routes, stores, and fa
 | 46001–46012 | KIND_WORKFLOW_* | Workflow execution events |
 | 20001 | KIND_PRESENCE_UPDATE | Ephemeral presence heartbeat |
 
-`buzz-core` defines all 81 kinds as `pub const KIND_*: u32` and exports `ALL_KINDS: &[u32]`. Kinds are `u32` (NIP-01 specifies unsigned integer; `u32` covers the full range). Buzz uses both standard Nostr kinds (e.g., kind 7 for reactions) and custom ranges (40000+).
+`buzz-core` defines each event kind as a `pub const u32` and exports the full registry as `ALL_KINDS: &[u32]` (127 kinds at the time of writing); `crates/buzz-core/src/kind.rs` is the source of truth for the current list. Kinds are `u32` (NIP-01 specifies unsigned integer; `u32` covers the full range). Buzz uses both standard Nostr kinds (e.g., kind 7 for reactions) and custom ranges (40000+).
 
 Note: `KIND_AUTH` (22242) is `pub const KIND_AUTH: u32` in `buzz-core/src/kind.rs` and imported by `buzz-relay/src/handlers/event.rs`. `KIND_CANVAS` (40100) is likewise `pub const KIND_CANVAS: u32` in `buzz-core/src/kind.rs`.
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 71a4bbd449..e30941a355 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,55 @@
 # Changelog
 
+## v0.5.4
+
+### Desktop and shared changes
+
+- fix: report agent usage per provider round, not once per turn ([#4545](https://github.com/block/buzz/pull/4545)) ([`09c86c56e52651c017743268fc8ce708bb83b265`](https://github.com/block/buzz/commit/09c86c56e52651c017743268fc8ce708bb83b265))
+- fix(desktop): harden Windows installs against Defender block and orphaned Node ([#4382](https://github.com/block/buzz/pull/4382)) ([`80315ac1a68024c40b61f3a062c9cb6bf7d4efb5`](https://github.com/block/buzz/commit/80315ac1a68024c40b61f3a062c9cb6bf7d4efb5))
+- feat(desktop): improve channel template discovery ([#4549](https://github.com/block/buzz/pull/4549)) ([`c1b88af8d71d1cf6aaca517e92ce9e918cd0e8bd`](https://github.com/block/buzz/commit/c1b88af8d71d1cf6aaca517e92ce9e918cd0e8bd))
+- fix(desktop): save key backups to authorized path ([#4022](https://github.com/block/buzz/pull/4022)) ([`01c80aa9b3eaa569361966877994438ad84a280a`](https://github.com/block/buzz/commit/01c80aa9b3eaa569361966877994438ad84a280a))
+- Add channel activity hover menu ([#3935](https://github.com/block/buzz/pull/3935)) ([`b0c6d6f744e63ac88a1738f0e995680c163e1d13`](https://github.com/block/buzz/commit/b0c6d6f744e63ac88a1738f0e995680c163e1d13))
+- feat(desktop): show saved Run on settings when editing an agent ([#4539](https://github.com/block/buzz/pull/4539)) ([`f865c0054b0a400657126c9321b4d4cb7d9cc746`](https://github.com/block/buzz/commit/f865c0054b0a400657126c9321b4d4cb7d9cc746))
+- fix(desktop): disambiguate provider API key labels and annotate mint key ([#4406](https://github.com/block/buzz/pull/4406)) ([`5e0efb0bb95182f588390b55cc5affa09114c87e`](https://github.com/block/buzz/commit/5e0efb0bb95182f588390b55cc5affa09114c87e))
+- fix(desktop): make OpenAI key re-enterable after first save in card mint dialog ([#4140](https://github.com/block/buzz/pull/4140)) ([`f810a2f49e213d25119f2aa75b5b577655119b74`](https://github.com/block/buzz/commit/f810a2f49e213d25119f2aa75b5b577655119b74))
+- fix(config-bridge): add harness-definition env tier and fix equal-value model override ([#3580](https://github.com/block/buzz/pull/3580)) ([`be95a8a986d02319b27e8fb57aefe59e33a1eb13`](https://github.com/block/buzz/commit/be95a8a986d02319b27e8fb57aefe59e33a1eb13))
+- fix(desktop): stop the create-agent provider config probe from erasing keystrokes ([#4411](https://github.com/block/buzz/pull/4411)) ([`2c0ac2467437b30953a95e00f419143488bcfcc7`](https://github.com/block/buzz/commit/2c0ac2467437b30953a95e00f419143488bcfcc7))
+- feat(acp): deliver system prompt via _meta.systemPrompt for claude-agent-acp ([#4395](https://github.com/block/buzz/pull/4395)) ([`7ff5fc31895efe6265a379d01637c8ee301872e5`](https://github.com/block/buzz/commit/7ff5fc31895efe6265a379d01637c8ee301872e5))
+- fix(security): bump nostr crates for RUSTSEC-2026-0225..0232 + default sprig image to published digest ([#4392](https://github.com/block/buzz/pull/4392)) ([`318fbf896ec335bc7bcb40edafde0b6ebca53428`](https://github.com/block/buzz/commit/318fbf896ec335bc7bcb40edafde0b6ebca53428))
+- fix(desktop): back/forward via keyboard chords, mouse X1/X2 buttons, and swipe gestures ([#3778](https://github.com/block/buzz/pull/3778)) ([`f86cfc7369d4471f8939ed98be6f597b0a4b0bb2`](https://github.com/block/buzz/commit/f86cfc7369d4471f8939ed98be6f597b0a4b0bb2))
+- feat(k8s): Kubernetes backend plugin + desktop deploy path ([#4289](https://github.com/block/buzz/pull/4289)) ([`6530b58a61d4602d0a371100fedf80c5998b1e34`](https://github.com/block/buzz/commit/6530b58a61d4602d0a371100fedf80c5998b1e34))
+- feat(projects): add buzz projects CLI commands (NIP-MP kind:30621) ([#4020](https://github.com/block/buzz/pull/4020)) ([`b7bb15122e8a2053b545dc2210afc167f6c7a626`](https://github.com/block/buzz/commit/b7bb15122e8a2053b545dc2210afc167f6c7a626))
+- fix(desktop): keep thread-open affordance in archived channels ([#4012](https://github.com/block/buzz/pull/4012)) ([`8e81afa431deecd172f1ad6aab6f022f31cd812c`](https://github.com/block/buzz/commit/8e81afa431deecd172f1ad6aab6f022f31cd812c))
+- fix(desktop): point Oh My Pi preset at omp.sh ([#3516](https://github.com/block/buzz/pull/3516)) ([`3ade48d5030a8f7dbb9d3693f171e5544dcd8df1`](https://github.com/block/buzz/commit/3ade48d5030a8f7dbb9d3693f171e5544dcd8df1))
+- fix(mesh): stop restarting a busy or loading shared-compute node ([#3909](https://github.com/block/buzz/pull/3909)) ([`fa1a5b1a797870724f5c7e7e26931861a60f22cb`](https://github.com/block/buzz/commit/fa1a5b1a797870724f5c7e7e26931861a60f22cb))
+- fix(desktop): preserve first huddle speech ([#3962](https://github.com/block/buzz/pull/3962)) ([`45314fc504113aec7c54ae6520cfe5e1562aae40`](https://github.com/block/buzz/commit/45314fc504113aec7c54ae6520cfe5e1562aae40))
+- feat(desktop): Agent Trading Cards — mintable agent-snapshot card PNGs with optional NIP-44 lock ([#3278](https://github.com/block/buzz/pull/3278)) ([`eb049ddf815d48195e1713afe039d28c950d7933`](https://github.com/block/buzz/commit/eb049ddf815d48195e1713afe039d28c950d7933))
+- feat(relay): accept kind:30621 multi-repo projects at ingest ([#3171](https://github.com/block/buzz/pull/3171)) ([`cb9701cd30fb344bf134585634a09007f3155bfb`](https://github.com/block/buzz/commit/cb9701cd30fb344bf134585634a09007f3155bfb))
+
+### Other repository changes
+
+- test(mobile): assert follow boundary semantics ([#4559](https://github.com/block/buzz/pull/4559)) ([`6de85fe31d781122756aecf954bae7d357a56b9a`](https://github.com/block/buzz/commit/6de85fe31d781122756aecf954bae7d357a56b9a))
+- docs(release): align desktop handoff instructions ([#3988](https://github.com/block/buzz/pull/3988)) ([`44fa1e8e3af30d561de981a211ff7a79bfa36493`](https://github.com/block/buzz/commit/44fa1e8e3af30d561de981a211ff7a79bfa36493))
+- Polish mobile composer and messaging UI ([#3918](https://github.com/block/buzz/pull/3918)) ([`857e63c4ddfb76f95ab40bb691e00544413f6b81`](https://github.com/block/buzz/commit/857e63c4ddfb76f95ab40bb691e00544413f6b81))
+- ci(linux): enable mesh-llm feature in Linux release and canary builds ([#4524](https://github.com/block/buzz/pull/4524)) ([`83a285f1b1a0be862d55781fad9c75ec8813886d`](https://github.com/block/buzz/commit/83a285f1b1a0be862d55781fad9c75ec8813886d))
+- fix(mobile): recover and pace live subscriptions ([#3053](https://github.com/block/buzz/pull/3053)) ([`a5dbdf5e61e4c512acd99c219c79c154ddb57295`](https://github.com/block/buzz/commit/a5dbdf5e61e4c512acd99c219c79c154ddb57295))
+- fix(git): allow deleting the default branch ([#4297](https://github.com/block/buzz/pull/4297)) ([`fc598f5f8d70728d11d0712b9fa8e3acc44ea4c3`](https://github.com/block/buzz/commit/fc598f5f8d70728d11d0712b9fa8e3acc44ea4c3))
+- docs: formal spec for remote agents and their management ([#3748](https://github.com/block/buzz/pull/3748)) ([`28ae6cd2174309529305724e455c7ca082f6fe4b`](https://github.com/block/buzz/commit/28ae6cd2174309529305724e455c7ca082f6fe4b))
+- fix(nip-oa): accept raw Nostr tag form in parse_json_array ([#4203](https://github.com/block/buzz/pull/4203)) ([`89bf03c05df795a3575b7abbe648be898ef13388`](https://github.com/block/buzz/commit/89bf03c05df795a3575b7abbe648be898ef13388))
+- perf(relay): serve relay-membership checks from the read replica ([#4124](https://github.com/block/buzz/pull/4124)) ([`ac4fa13b8e4d947071d57deb6918dcf12bf74961`](https://github.com/block/buzz/commit/ac4fa13b8e4d947071d57deb6918dcf12bf74961))
+- chore(deps): bump nostr-relay-pool for RUSTSEC-2026-0224 ([#4139](https://github.com/block/buzz/pull/4139)) ([`9d6726e5b387310975f5809473ce8372f6fde0dc`](https://github.com/block/buzz/commit/9d6726e5b387310975f5809473ce8372f6fde0dc))
+- docs(nostr): document #h requirement for live reaction subscriptions ([#3487](https://github.com/block/buzz/pull/3487)) ([`756dd7f65d6f2995e9188a0ffe54294057f8ef4f`](https://github.com/block/buzz/commit/756dd7f65d6f2995e9188a0ffe54294057f8ef4f))
+- docs(chart): fix ArgoCD example for native OCI sources (full artifact repoURL + path) ([#3426](https://github.com/block/buzz/pull/3426)) ([`36cf932ff0105a4cf574fc687deb4c1cb01bc0d1`](https://github.com/block/buzz/commit/36cf932ff0105a4cf574fc687deb4c1cb01bc0d1))
+- docs(readme): clarify which release asset to download per platform ([#3481](https://github.com/block/buzz/pull/3481)) ([`8d5afb606763fcaffd3af811be2106e41cc7347d`](https://github.com/block/buzz/commit/8d5afb606763fcaffd3af811be2106e41cc7347d))
+- fix(relay): allow open relays to set their NIP-11 workspace icon (kind:9033) ([#3998](https://github.com/block/buzz/pull/3998)) ([`5765fc74b77224f0207ddd4b41736a5ff18d333d`](https://github.com/block/buzz/commit/5765fc74b77224f0207ddd4b41736a5ff18d333d))
+- docs: note that addressable channel events scope by d, not h ([#4103](https://github.com/block/buzz/pull/4103)) ([`3d7712cc36e8da563cb1c121fc58bfc505d38496`](https://github.com/block/buzz/commit/3d7712cc36e8da563cb1c121fc58bfc505d38496))
+- docs: fix stale kind count, quick-start numbering, and empty Further Reading ([#2613](https://github.com/block/buzz/pull/2613)) ([`909a3b2c318b2ec477a3438a998a3b611f5b6d6a`](https://github.com/block/buzz/commit/909a3b2c318b2ec477a3438a998a3b611f5b6d6a))
+- docs: add one-click Railway deploy for a hosted relay ([#2733](https://github.com/block/buzz/pull/2733)) ([`19d57b0d46baa55814ac737041a36d0b405c9f64`](https://github.com/block/buzz/commit/19d57b0d46baa55814ac737041a36d0b405c9f64))
+- fix(buzz-acp): thread cache-read tokens into NIP-AM kind:44200 events ([#3999](https://github.com/block/buzz/pull/3999)) ([`b1b283cd4c7f926e12eeee8ae1f38c7471922b16`](https://github.com/block/buzz/commit/b1b283cd4c7f926e12eeee8ae1f38c7471922b16))
+- fix(release): preserve main in desktop PR body ([#3979](https://github.com/block/buzz/pull/3979)) ([`e5e5bac2a932b2b2e4eb6b559d5545a992c21b96`](https://github.com/block/buzz/commit/e5e5bac2a932b2b2e4eb6b559d5545a992c21b96))
+
+[Compare desktop-v0.5.3...desktop-v0.5.4](https://github.com/block/buzz/compare/desktop-v0.5.3...desktop-v0.5.4)
+
 ## v0.5.3
 
 ### Desktop and shared changes
diff --git a/Cargo.lock b/Cargo.lock
index 9a3f91671d..937ead564a 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -915,6 +915,26 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "buzz-backend-kubernetes"
+version = "0.1.0"
+dependencies = [
+ "chrono",
+ "hex",
+ "http",
+ "http-body-util",
+ "k8s-openapi",
+ "kube",
+ "nostr",
+ "rand 0.10.1",
+ "rustls",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "tokio",
+ "tower",
+]
+
 [[package]]
 name = "buzz-cli"
 version = "0.1.0"
@@ -3643,6 +3663,7 @@ dependencies = [
  "http",
  "hyper",
  "hyper-util",
+ "log",
  "rustls",
  "rustls-native-certs",
  "tokio",
@@ -4303,6 +4324,31 @@ dependencies = [
  "ucd-trie",
 ]
 
+[[package]]
+name = "jsonpath-rust"
+version = "0.7.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c00ae348f9f8fd2d09f82a98ca381c60df9e0820d8d79fce43e649b4dc3128b"
+dependencies = [
+ "pest",
+ "pest_derive",
+ "regex",
+ "serde_json",
+ "thiserror 2.0.18",
+]
+
+[[package]]
+name = "k8s-openapi"
+version = "0.26.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06d9e5e61dd037cdc51da0d7e2b2be10f497478ea7e120d85dad632adb99882b"
+dependencies = [
+ "base64 0.22.1",
+ "chrono",
+ "serde",
+ "serde_json",
+]
+
 [[package]]
 name = "kasuari"
 version = "0.4.12"
@@ -4348,6 +4394,70 @@ version = "0.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e037a2e1d8d5fdbd49b16a4ea09d5d6401c1f29eca5ff29d03d3824dba16256a"
 
+[[package]]
+name = "kube"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48e7bb0b6a46502cc20e4575b6ff401af45cfea150b34ba272a3410b78aa014e"
+dependencies = [
+ "k8s-openapi",
+ "kube-client",
+ "kube-core",
+]
+
+[[package]]
+name = "kube-client"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4987d57a184d2b5294fdad3d7fc7f278899469d21a4da39a8f6ca16426567a36"
+dependencies = [
+ "base64 0.22.1",
+ "bytes",
+ "chrono",
+ "either",
+ "futures",
+ "home",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-rustls",
+ "hyper-timeout",
+ "hyper-util",
+ "jsonpath-rust",
+ "k8s-openapi",
+ "kube-core",
+ "pem",
+ "rustls",
+ "secrecy",
+ "serde",
+ "serde_json",
+ "serde_yaml",
+ "thiserror 2.0.18",
+ "tokio",
+ "tokio-util",
+ "tower",
+ "tower-http",
+ "tracing",
+]
+
+[[package]]
+name = "kube-core"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "914bbb770e7bb721a06e3538c0edd2babed46447d128f7c21caa68747060ee73"
+dependencies = [
+ "chrono",
+ "derive_more",
+ "form_urlencoded",
+ "http",
+ "k8s-openapi",
+ "serde",
+ "serde-value",
+ "serde_json",
+ "thiserror 2.0.18",
+]
+
 [[package]]
 name = "lab"
 version = "0.11.0"
@@ -5699,9 +5809,9 @@ dependencies = [
 
 [[package]]
 name = "nostr"
-version = "0.44.6"
+version = "0.44.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e826dd648489de2c5b293920e20b92932ef820302007c1987c758d4d06eeb2cf"
+checksum = "c7d3d987ea7078dc36947cde532637c472a229426702e4331dd7667325378bd9"
 dependencies = [
  "base64 0.22.1",
  "bech32",
@@ -5743,9 +5853,9 @@ dependencies = [
 
 [[package]]
 name = "nostr-relay-pool"
-version = "0.44.1"
+version = "0.44.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "91b2c039df4f96c4bf7dae52a74fd5516ad6dda83a11c0c69dea91b5255a4f37"
+checksum = "c85c54d6ca9aae4ae2bf19a7663ba9db5f45f783f1d24aff55f006386b8b99a1"
 dependencies = [
  "async-utility",
  "async-wsocket",
@@ -6265,6 +6375,15 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
 
+[[package]]
+name = "ordered-float"
+version = "2.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68f19d67e5a2795c94e73e0bb1cc1a7edeb2e28efd39e2e1c9b7a40c1108b11c"
+dependencies = [
+ "num-traits",
+]
+
 [[package]]
 name = "ordered-float"
 version = "4.6.0"
@@ -6445,6 +6564,16 @@ dependencies = [
  "hmac 0.12.1",
 ]
 
+[[package]]
+name = "pem"
+version = "3.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d30c53c26bc5b31a98cd02d20f25a7c8567146caf63ed593a9d87b2775291be"
+dependencies = [
+ "base64 0.22.1",
+ "serde_core",
+]
+
 [[package]]
 name = "pem-rfc7468"
 version = "1.0.0"
@@ -8170,6 +8299,15 @@ dependencies = [
  "cc",
 ]
 
+[[package]]
+name = "secrecy"
+version = "0.10.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e891af845473308773346dc847b2c23ee78fe442e0472ac50e22a18a93d3ae5a"
+dependencies = [
+ "zeroize",
+]
+
 [[package]]
 name = "secret-service"
 version = "4.0.0"
@@ -8269,6 +8407,16 @@ dependencies = [
  "serde_derive",
 ]
 
+[[package]]
+name = "serde-value"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3a1a3341211875ef120e117ea7fd5228530ae7e7036a779fdc9117be6b3282c"
+dependencies = [
+ "ordered-float 2.10.1",
+ "serde",
+]
+
 [[package]]
 name = "serde_bytes"
 version = "0.11.19"
@@ -9869,6 +10017,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
 dependencies = [
  "async-compression",
+ "base64 0.22.1",
  "bitflags 2.13.0",
  "bytes",
  "futures-core",
diff --git a/Cargo.toml b/Cargo.toml
index 3268cfaf8d..cc1dd0f9df 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -27,6 +27,7 @@ members = [
     "crates/buzz-relay-mesh",
     "crates/buzz-dev-mcp",
     "crates/buzz-voice",
+    "crates/buzz-backend-kubernetes",
     "examples/countdown-bot",
 ]
 exclude = ["desktop/src-tauri"]
@@ -58,6 +59,13 @@ sqlx = { version = "0.9", features = [
 redis        = { version = "1.0", features = ["tokio-comp", "connection-manager", "tokio-rustls-comp"] }
 deadpool-redis = { version = "0.23", features = ["rt_tokio_1"] }
 
+# Kubernetes (buzz-backend-kubernetes provider). No `ring` feature here: the
+# process-level CryptoProvider is installed explicitly at startup, matching
+# buzz-cli/buzz-acp/buzz-admin/buzz-relay/buzz-dev-mcp — see the comment on the
+# crate's own rustls dependency.
+kube = { version = "2.0", default-features = false, features = ["client", "rustls-tls"] }
+k8s-openapi = { version = "0.26", features = ["v1_31"] }
+
 # Nostr
 nostr = { version = "0.44", features = ["nip44", "nip98"] }
 
diff --git a/Dockerfile.sprig b/Dockerfile.sprig
new file mode 100644
index 0000000000..160e0b5662
--- /dev/null
+++ b/Dockerfile.sprig
@@ -0,0 +1,44 @@
+# syntax=docker/dockerfile:1.7
+# Multi-arch is produced by building this file on native amd64 and arm64 runners.
+# Keep both bases pinned to manifest-list digests so either architecture resolves
+# to immutable source bytes.
+FROM rust:1.95-alpine3.22@sha256:064dfc925d68d1a63f4fd2871bd7dc6e6ea56692989a487185855d62885d90aa AS builder
+
+RUN apk add --no-cache \
+      build-base \
+      cmake \
+      git \
+      musl-dev \
+      openssl-dev \
+      openssl-libs-static \
+      perl \
+      pkgconf \
+      protoc
+WORKDIR /build
+COPY . .
+RUN cargo build --locked --profile sprig -p sprig \
+    && strip target/sprig/sprig
+
+FROM alpine:3.22@sha256:14358309a308569c32bdc37e2e0e9694be33a9d99e68afb0f5ff33cc1f695dce
+
+RUN apk add --no-cache bash ca-certificates curl git \
+    && adduser -D -h /home/agent agent \
+    && install -d -o agent -g agent /workspace /home/agent \
+    && git config --system gpg.format x509 \
+    && git config --system gpg.x509.program /usr/local/bin/git-sign-nostr \
+    && git config --system commit.gpgSign true \
+    && git config --system tag.gpgSign true
+
+COPY --from=builder --chmod=0755 /build/target/sprig/sprig /usr/local/bin/sprig
+COPY --chmod=0755 scripts/sprig-entrypoint.sh /usr/local/bin/sprig-entrypoint
+RUN for name in \
+      buzz-acp buzz-agent buzz-dev-mcp rg tree buzz \
+      git-credential-nostr git-sign-nostr; do \
+        ln -s sprig "/usr/local/bin/$name"; \
+    done
+
+ENV HOME=/home/agent \
+    PATH=/usr/local/bin:/usr/local/sbin:/usr/sbin:/usr/bin:/sbin:/bin
+WORKDIR /home/agent
+USER agent
+ENTRYPOINT ["/usr/local/bin/sprig-entrypoint"]
diff --git a/Justfile b/Justfile
index 64a1f36daf..d6e86c8d09 100644
--- a/Justfile
+++ b/Justfile
@@ -155,7 +155,11 @@ _ensure-sidecar-stubs:
     set -euo pipefail
     TARGET=$(rustc -vV | sed -n 's|host: ||p')
     mkdir -p desktop/src-tauri/binaries
-    for bin in buzz-acp buzz-agent buzz-dev-mcp git-credential-nostr buzz; do
+    SIDECARS=(buzz-acp buzz-agent buzz-dev-mcp git-credential-nostr buzz)
+    if [[ "$TARGET" != *windows* ]]; then
+        SIDECARS+=(buzz-backend-kubernetes)
+    fi
+    for bin in "${SIDECARS[@]}"; do
         touch "desktop/src-tauri/binaries/${bin}-${TARGET}"
     done
 
@@ -236,6 +240,9 @@ desktop-release-build target="aarch64-apple-darwin":
     mkdir -p desktop/src-tauri/binaries
     touch "desktop/src-tauri/binaries/buzz-acp-$TARGET"
     touch "desktop/src-tauri/binaries/buzz-agent-$TARGET"
+    if [[ "$TARGET" != *windows* ]]; then
+        touch "desktop/src-tauri/binaries/buzz-backend-kubernetes-$TARGET"
+    fi
     touch "desktop/src-tauri/binaries/buzz-dev-mcp-$TARGET"
     touch "desktop/src-tauri/binaries/git-credential-nostr-$TARGET"
     touch "desktop/src-tauri/binaries/buzz-$TARGET"
@@ -274,6 +281,7 @@ test:
 # Run unit tests only (no infra needed)
 test-unit:
     #!/usr/bin/env bash
+    set -euo pipefail
     if command -v cargo-nextest &>/dev/null; then
         cargo nextest run -p buzz-core -p buzz-auth --lib
         cargo nextest run -p buzz-voice --lib
@@ -293,6 +301,12 @@ test-unit:
         # Gateway unit and black-box HTTP tests are infra-free. Postgres-backed
         # contract/race tests run in the dedicated CI job below.
         cargo nextest run -p buzz-push-gateway
+        # Kubernetes backend provider: the decision layers (state machine, GC
+        # planner, env precedence, naming, wire) are pure functions with a fake
+        # substrate, so they belong in the unit job. Enumerated explicitly
+        # because nothing in CI runs `cargo test --workspace` — workspace
+        # membership alone buys clippy/check, not a single executed test.
+        cargo nextest run -p buzz-backend-kubernetes
     else
         ./scripts/run-tests.sh unit
     fi
@@ -430,7 +444,7 @@ dev *ARGS: bootstrap _ensure-sidecar-stubs _ensure-migrations
             fi
         done
     fi
-    cargo build -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr -p buzz-relay
+    cargo build -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr -p buzz-relay
     if [[ -n "{{mesh}}" ]]; then
         export MESH_LLM_NATIVE_RUNTIME_CACHE_DIR="$(./scripts/ensure-mesh-native-runtime.sh)"
     fi
@@ -477,10 +491,10 @@ desktop-standalone *ARGS: _ensure-sidecar-stubs
     #!/usr/bin/env bash
     set -euo pipefail
     export PATH="{{justfile_directory()}}/bin:$PATH"
-    cargo build -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
+    cargo build -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
     TARGET=$(rustc -vV | sed -n 's|host: ||p')
     TARGET_DIR=$(cargo metadata --format-version 1 --no-deps | node -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).target_directory")
-    for bin in buzz-acp buzz-agent buzz-dev-mcp git-credential-nostr buzz; do
+    for bin in buzz-acp buzz-agent buzz-backend-kubernetes buzz-dev-mcp git-credential-nostr buzz; do
         cp "${TARGET_DIR}/debug/${bin}" "desktop/src-tauri/binaries/${bin}-${TARGET}"
         chmod +x "desktop/src-tauri/binaries/${bin}-${TARGET}"
     done
@@ -506,17 +520,26 @@ staging *ARGS: bootstrap _ensure-sidecar-stubs
     set -euo pipefail
     export PATH="{{justfile_directory()}}/bin:$PATH"
     pnpm install  # unconditional: staging must always start with a clean dep tree
-    cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
+    cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
     FEATURES=()
     if [[ -n "{{mesh}}" ]]; then
         FEATURES=(--features mesh-llm)
         export MESH_LLM_NATIVE_RUNTIME_CACHE_DIR="$(./scripts/ensure-mesh-native-runtime.sh)"
     fi
-    # Replace the 0-byte sidecar stub with the real CLI binary so tauri dev picks it up.
+    # Replace 0-byte sidecar stubs with real binaries so tauri dev picks them up.
+    # buzz: the CLI sidecar. buzz-backend-kubernetes: provider discovery scans the
+    # exe dir for executable buzz-backend-* files, so the non-executable stub that
+    # tauri dev copies next to the exe would hide the provider from "Run on".
     TARGET=$(rustc -vV | sed -n 's|host: ||p')
     TARGET_DIR=$(cargo metadata --format-version 1 --no-deps | node -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).target_directory")
-    cp "${TARGET_DIR}/release/buzz" "desktop/src-tauri/binaries/buzz-${TARGET}"
-    chmod +x "desktop/src-tauri/binaries/buzz-${TARGET}"
+    STAGING_SIDECARS=(buzz)
+    if [[ "$TARGET" != *windows* ]]; then
+        STAGING_SIDECARS+=(buzz-backend-kubernetes)
+    fi
+    for bin in "${STAGING_SIDECARS[@]}"; do
+        cp "${TARGET_DIR}/release/${bin}" "desktop/src-tauri/binaries/${bin}-${TARGET}"
+        chmod +x "desktop/src-tauri/binaries/${bin}-${TARGET}"
+    done
     cd {{desktop_dir}}
     export BUZZ_RELAY_URL="wss://sprout-oss.stage.blox.sqprod.co"
     source ../scripts/instance-env.sh
@@ -533,17 +556,26 @@ production *ARGS: bootstrap _ensure-sidecar-stubs
     set -euo pipefail
     export PATH="{{justfile_directory()}}/bin:$PATH"
     pnpm install  # unconditional: production must always start with a clean dep tree
-    cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
+    cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p buzz-cli -p git-credential-nostr
     FEATURES=()
     if [[ -n "{{mesh}}" ]]; then
         FEATURES=(--features mesh-llm)
         export MESH_LLM_NATIVE_RUNTIME_CACHE_DIR="$(./scripts/ensure-mesh-native-runtime.sh)"
     fi
-    # Replace the 0-byte sidecar stub with the real CLI binary so tauri dev picks it up.
+    # Replace 0-byte sidecar stubs with real binaries so tauri dev picks them up.
+    # buzz: the CLI sidecar. buzz-backend-kubernetes: provider discovery scans the
+    # exe dir for executable buzz-backend-* files, so the non-executable stub that
+    # tauri dev copies next to the exe would hide the provider from "Run on".
     TARGET=$(rustc -vV | sed -n 's|host: ||p')
     TARGET_DIR=$(cargo metadata --format-version 1 --no-deps | node -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).target_directory")
-    cp "${TARGET_DIR}/release/buzz" "desktop/src-tauri/binaries/buzz-${TARGET}"
-    chmod +x "desktop/src-tauri/binaries/buzz-${TARGET}"
+    PRODUCTION_SIDECARS=(buzz)
+    if [[ "$TARGET" != *windows* ]]; then
+        PRODUCTION_SIDECARS+=(buzz-backend-kubernetes)
+    fi
+    for bin in "${PRODUCTION_SIDECARS[@]}"; do
+        cp "${TARGET_DIR}/release/${bin}" "desktop/src-tauri/binaries/${bin}-${TARGET}"
+        chmod +x "desktop/src-tauri/binaries/${bin}-${TARGET}"
+    done
     cd {{desktop_dir}}
     export BUZZ_RELAY_URL="wss://buzz.block.builderlab.xyz"
     source ../scripts/instance-env.sh
diff --git a/NOSTR.md b/NOSTR.md
index 59df31b991..cce70f2f77 100644
--- a/NOSTR.md
+++ b/NOSTR.md
@@ -39,7 +39,7 @@ just relay &                         # relay on :3000
 PGPASSWORD=buzz_dev psql -h localhost -U buzz -d buzz -c \
   "INSERT INTO pubkey_allowlist (pubkey) VALUES (decode('<64-char-hex-pubkey>', 'hex'))"
 
-# 5. Connect any NIP-29 + NIP-42 client to ws://localhost:3000
+# 4. Connect any NIP-29 + NIP-42 client to ws://localhost:3000
 ```
 
 ### What Works
@@ -163,6 +163,10 @@ nak req -k 9 --tag "h=<channel-uuid>" --stream \
 nak event -k 7 -c "+" --tag "h=<channel-uuid>" --tag "e=<message-event-id>" \
   --auth --sec <privkey> ws://localhost:3000
 
+# Subscribe to reactions to channel messages — include #h for live delivery (see note below)
+nak req -k 7 --tag "h=<channel-uuid>" --stream \
+  --auth --sec <privkey> ws://localhost:3000
+
 # Delete a message (#h optional; #e required; must be self-authored)
 nak event -k 5 -c "reason" --tag "h=<channel-uuid>" --tag "e=<message-event-id>" \
   --auth --sec <privkey> ws://localhost:3000
@@ -185,6 +189,14 @@ nak req -k 1059 --tag "p=<your-hex-pubkey>" \
   --auth --sec <privkey> ws://localhost:3000
 ```
 
+> **Note:** The relay derives a reaction's channel from its `#e` target (client `#h` is
+> ignored for channel determination). Reactions to channel-scoped events are therefore
+> channel-scoped. Live fan-out keeps channel-scoped and global subscriptions strictly
+> separate, which means a kinds-only subscription (`{"kinds":[7]}`) receives none of
+> those reactions — subscribe with `{"kinds":[7],"#h":["<channel-uuid>"]}` instead.
+> `#h` matching works whether or not the signed reaction carries an `h` tag: explicit
+> `h` tags are matched directly, and tagless reactions match via their stored channel.
+
 ### Tested Clients (Direct)
 
 | Client | Platform | Evidence | Notes |
@@ -354,3 +366,7 @@ but only admins/owners can set it. Full spec:
 ---
 
 ## Further Reading
+
+- [nostr-protocol/nips](https://github.com/nostr-protocol/nips) — the upstream NIP specifications (NIP-01, NIP-29, NIP-42, and the other NIPs referenced throughout this guide).
+- [`docs/nips/`](docs/nips/) — Buzz's own NIP extension documents.
+- [`ARCHITECTURE.md`](ARCHITECTURE.md) — event kinds, wire protocol, and relay internals.
diff --git a/README.md b/README.md
index 2c58ceecad..56439f00bc 100644
--- a/README.md
+++ b/README.md
@@ -116,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 e729f8b50c..23dacea2ce 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -56,14 +56,15 @@ or mobile GitHub Release.
    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.
+   A trusted repository member, owner, or collaborator must approve that exact
+   candidate head. Any regeneration or push changes the head, invalidates the
+   prior approval, and requires both the checks and 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>`.
+   required checks, and trusted approval on the exact candidate head, then tags
+   the squash commit as `desktop-v<version>`. An admin or ruleset bypass does not
+   authorize desktop tagging.
 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
@@ -184,10 +185,12 @@ Buildkite pipeline accepts only an exact candidate tag.
 
 For mobile, trigger the private
 [Release Mobile pipeline](https://buildkite.com/runway/buzz-mobile-releases) with
-an exact RC tag for the platform build being cut. For desktop, use
-[Release Desktop](https://buildkite.com/runway/sprout-releases). See the
+an exact RC tag for the platform build being cut. For desktop, start
+[Release Desktop](https://buildkite.com/runway/sprout-releases) and enter the
+exact public source tag as `desktop_ref=desktop-v<version>`; a generic
+`v<version>` tag is intentionally rejected. See the
 [buzz-releases README](https://github.com/squareup/buzz-releases#cutting-a-release)
-for the private pipeline contract.
+for the rest of the private pipeline contract.
 
 ---
 
@@ -269,9 +272,9 @@ actor list.
 
 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.
+candidate, reruns CI, and requires a fresh trusted approval on the new exact
+head. The post-merge verifier refuses to tag a squash whose parent differs from
+the recorded candidate base or whose tree differs from the validated PR head.
 
 ### Local `just release-desktop` fails with "must be on main branch"
 Switch to `main` and pull latest before running the release recipe.
diff --git a/VISION_REMOTE_AGENTS.md b/VISION_REMOTE_AGENTS.md
index b02d1bc92d..4b187f355a 100644
--- a/VISION_REMOTE_AGENTS.md
+++ b/VISION_REMOTE_AGENTS.md
@@ -56,7 +56,7 @@ Remote agents solve it from the inside. Because the desktop retains no substrate
 
 **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.
+**Presence can lag the truth, but not for long.** If the substrate kills a body without ceremony, the presence dot can outlive the agent — by seconds if the connection drops cleanly, by at most about three minutes if it doesn't. Presence is a lease the agent renews, not a flag it sets: a dead agent stops renewing and the relay forgets it. A bounded wrong dot, never an indefinite one.
 
 **A running agent finishes on the configuration it started with.** New keys, new models, new settings take effect on the next body. And an instance that never got far enough to run — a body that failed to start — is the substrate operator's residue to clear, with the substrate's own tools. Editing an agent mid-sentence was never on the menu.
 
diff --git a/crates/buzz-acp/src/acp.rs b/crates/buzz-acp/src/acp.rs
index 8a698954a0..700d5e8dcf 100644
--- a/crates/buzz-acp/src/acp.rs
+++ b/crates/buzz-acp/src/acp.rs
@@ -619,29 +619,46 @@ impl AcpClient {
     /// Send `session/new` and return the full response alongside the session ID.
     ///
     /// `cwd` must be an absolute path. `mcp_servers` may be empty.
-    /// `system_prompt` is included in the request when `Some` — agents that
-    /// support the field will use it; others ignore unknown fields per JSON-RPC.
+    ///
+    /// `system_prompt` controls how the prompt text is delivered:
+    ///
+    /// - `None` — no system-prompt field in the request (legacy framing).
+    /// - `Some(SystemPromptTransport::Field(text))` — bare `systemPrompt` field
+    ///   (ACP protocol v2, buzz-agent, goose unused).
+    /// - `Some(SystemPromptTransport::ClaudeMeta(text))` — `_meta.systemPrompt`
+    ///   as `{"append": text}`, keeping claude-agent-acp's native preset intact.
+    ///
     /// `session_title` rides in `_meta.sessionTitle` when `Some`; `_meta` is
     /// omitted entirely otherwise, since adapters may distinguish an absent
-    /// member from a null one.
+    /// member from a null one. When both `ClaudeMeta` and `session_title` are
+    /// present the two `_meta` members are merged into a single object.
+    ///
     /// Callers use [`extract_model_config_options`] and [`extract_model_state`]
     /// to pull model info from the raw result.
     pub async fn session_new_full(
         &mut self,
         cwd: &str,
         mcp_servers: Vec<McpServer>,
-        system_prompt: Option<&str>,
+        system_prompt: Option<SystemPromptTransport<'_>>,
         session_title: Option<&str>,
     ) -> Result<SessionNewResponse, AcpError> {
         let mut params = serde_json::json!({
             "cwd": cwd,
             "mcpServers": mcp_servers,
         });
-        if let Some(sp) = system_prompt {
-            params["systemPrompt"] = serde_json::Value::String(sp.to_owned());
+        match system_prompt {
+            Some(SystemPromptTransport::Field(sp)) => {
+                params["systemPrompt"] = serde_json::Value::String(sp.to_owned());
+            }
+            Some(SystemPromptTransport::ClaudeMeta(sp)) => {
+                // Merge into _meta so sessionTitle (set below) is not clobbered.
+                params["_meta"]["systemPrompt"] = serde_json::json!({ "append": sp });
+            }
+            None => {}
         }
         if let Some(title) = session_title {
-            params["_meta"] = serde_json::json!({ "sessionTitle": title });
+            // Merge — _meta may already carry systemPrompt from ClaudeMeta above.
+            params["_meta"]["sessionTitle"] = serde_json::Value::String(title.to_owned());
         }
         let result = self.send_request("session/new", params).await?;
         let session_id = result["sessionId"]
@@ -663,7 +680,7 @@ impl AcpClient {
         &mut self,
         cwd: &str,
         mcp_servers: Vec<McpServer>,
-        system_prompt: Option<&str>,
+        system_prompt: Option<SystemPromptTransport<'_>>,
         session_title: Option<&str>,
     ) -> Result<String, AcpError> {
         Ok(self
@@ -2038,6 +2055,22 @@ pub struct SessionNewResponse {
     pub raw: serde_json::Value,
 }
 
+/// How to deliver a system prompt on `session/new`.
+///
+/// The two variants match the two mechanisms supported by current adapters:
+///
+/// - **`Field`** — bare `systemPrompt` field (ACP protocol v2, buzz-agent).
+/// - **`ClaudeMeta`** — `_meta.systemPrompt: {"append": text}`, used by
+///   `claude-agent-acp` to append to the adapter's own native system prompt
+///   while keeping its tool-use preset intact.
+#[derive(Debug, Clone, PartialEq)]
+pub enum SystemPromptTransport<'a> {
+    /// Deliver as a bare top-level `systemPrompt` field.
+    Field(&'a str),
+    /// Deliver as `_meta.systemPrompt: {"append": text}`.
+    ClaudeMeta(&'a str),
+}
+
 /// How to switch to a particular model on a session.
 #[derive(Debug, Clone, PartialEq, serde::Serialize)]
 #[serde(tag = "type")]
@@ -3271,7 +3304,12 @@ mod tests {
             .expect("initialize should succeed");
 
         let resp = client
-            .session_new_full("/tmp", vec![], Some("Custom system prompt"), None)
+            .session_new_full(
+                "/tmp",
+                vec![],
+                Some(SystemPromptTransport::Field("Custom system prompt")),
+                None,
+            )
             .await
             .expect("session_new_full should succeed");
 
@@ -3423,6 +3461,87 @@ mod tests {
         );
     }
 
+    // ── claude-agent-acp _meta.systemPrompt transport ─────────────────────
+
+    #[tokio::test]
+    async fn session_new_full_sends_claude_meta_system_prompt_when_claude_meta_transport() {
+        // When ClaudeMeta transport is requested, the prompt must appear as
+        // _meta.systemPrompt: {"append": text} — never as a bare systemPrompt field.
+        let script = r#"
+            read -t 2 _init
+            echo '{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":1,"agentCapabilities":{}}}'
+            read -t 2 REQ
+            echo '{"jsonrpc":"2.0","id":1,"result":{"sessionId":"ses_claude","_receivedRequest":'"$REQ"'}}'
+            sleep 1
+        "#;
+        let mut client = spawn_script(script).await;
+        client
+            .initialize()
+            .await
+            .expect("initialize should succeed");
+
+        let resp = client
+            .session_new_full(
+                "/tmp",
+                vec![],
+                Some(SystemPromptTransport::ClaudeMeta("Be concise")),
+                None,
+            )
+            .await
+            .expect("session_new_full should succeed");
+
+        let received = &resp.raw["_receivedRequest"];
+        assert!(
+            received["params"].get("systemPrompt").is_none(),
+            "bare systemPrompt must not be present for ClaudeMeta transport"
+        );
+        assert_eq!(
+            received["params"]["_meta"]["systemPrompt"]["append"].as_str(),
+            Some("Be concise"),
+            "_meta.systemPrompt.append must carry the prompt text"
+        );
+    }
+
+    #[tokio::test]
+    async fn session_new_full_merges_claude_meta_and_session_title_into_single_meta_object() {
+        // Both ClaudeMeta prompt and session_title must coexist under _meta —
+        // the prompt must not clobber sessionTitle or vice versa.
+        let script = r#"
+            read -t 2 _init
+            echo '{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":1,"agentCapabilities":{}}}'
+            read -t 2 REQ
+            echo '{"jsonrpc":"2.0","id":1,"result":{"sessionId":"ses_merged","_receivedRequest":'"$REQ"'}}'
+            sleep 1
+        "#;
+        let mut client = spawn_script(script).await;
+        client
+            .initialize()
+            .await
+            .expect("initialize should succeed");
+
+        let resp = client
+            .session_new_full(
+                "/tmp",
+                vec![],
+                Some(SystemPromptTransport::ClaudeMeta("Be concise")),
+                Some("Fizz · #buzz-dev"),
+            )
+            .await
+            .expect("session_new_full should succeed");
+
+        let received = &resp.raw["_receivedRequest"];
+        assert_eq!(
+            received["params"]["_meta"]["systemPrompt"]["append"].as_str(),
+            Some("Be concise"),
+            "_meta.systemPrompt.append must be present"
+        );
+        assert_eq!(
+            received["params"]["_meta"]["sessionTitle"].as_str(),
+            Some("Fizz · #buzz-dev"),
+            "_meta.sessionTitle must be present alongside systemPrompt"
+        );
+    }
+
     // ── Goose-native steer scaffold (PR follow-up to #1160) ──────────────
 
     /// Helper: spawn an inert `cat` subprocess so we have a real AcpClient
diff --git a/crates/buzz-acp/src/config.rs b/crates/buzz-acp/src/config.rs
index dab61be30a..35aaec188d 100644
--- a/crates/buzz-acp/src/config.rs
+++ b/crates/buzz-acp/src/config.rs
@@ -474,6 +474,11 @@ pub struct CliArgs {
     #[arg(long, env = "BUZZ_ACP_RELAY_OBSERVER", default_value_t = false)]
     pub relay_observer: bool,
 
+    /// Exit after this many seconds with no dispatched events and no turn in flight.
+    /// 0 disables inactivity self-termination.
+    #[arg(long, env = "BUZZ_ACP_EXIT_AFTER_INACTIVITY", default_value_t = 0)]
+    pub exit_after_inactivity: u64,
+
     /// Connect and subscribe before starting the ACP/LLM subprocess pool.
     #[arg(long, env = "BUZZ_ACP_LAZY_POOL", default_value_t = false)]
     pub lazy_pool: bool,
@@ -550,6 +555,8 @@ pub struct Config {
     pub has_generated_codex_config: bool,
     /// Whether to publish encrypted observer frames through the relay.
     pub relay_observer: bool,
+    /// Seconds without dispatched events before an idle harness exits. 0 = disabled.
+    pub exit_after_inactivity_secs: u64,
     /// Whether ACP/LLM subprocess initialization is deferred until accepted work arrives.
     pub lazy_pool: bool,
     /// Agent owner pubkey (hex). Used for `--respond-to=owner-only` gate.
@@ -1098,6 +1105,7 @@ impl Config {
             persona_env_vars,
             has_generated_codex_config,
             relay_observer: args.relay_observer,
+            exit_after_inactivity_secs: args.exit_after_inactivity,
             lazy_pool: args.lazy_pool,
             agent_owner: args.agent_owner.map(|s| s.trim().to_ascii_lowercase()),
             no_base_prompt: args.no_base_prompt,
@@ -1468,6 +1476,7 @@ mod tests {
             persona_env_vars: vec![],
             has_generated_codex_config: false,
             relay_observer: false,
+            exit_after_inactivity_secs: 0,
             lazy_pool: false,
             agent_owner: None,
             no_base_prompt: false,
@@ -2167,6 +2176,22 @@ channels = "ALL"
         assert!(err.to_string().contains("turn liveness interval must be 0"));
     }
 
+    #[test]
+    fn inactivity_exit_defaults_disabled_and_accepts_cli_value() {
+        let key = "0".repeat(64);
+        let default = CliArgs::parse_from(["buzz-acp", "--private-key", &key]);
+        assert_eq!(default.exit_after_inactivity, 0);
+
+        let configured = CliArgs::parse_from([
+            "buzz-acp",
+            "--private-key",
+            &key,
+            "--exit-after-inactivity",
+            "120",
+        ]);
+        assert_eq!(configured.exit_after_inactivity, 120);
+    }
+
     #[test]
     fn lazy_pool_defaults_off() {
         let key = "0".repeat(64);
diff --git a/crates/buzz-acp/src/lib.rs b/crates/buzz-acp/src/lib.rs
index 403512a322..811253e4ac 100644
--- a/crates/buzz-acp/src/lib.rs
+++ b/crates/buzz-acp/src/lib.rs
@@ -1228,6 +1228,59 @@ impl Drop for RespawnGuard {
 // sync entry point — `std::env::set_var` is only safe before tokio spawns
 // worker threads (Rust 2024 edition safety requirement).
 
+fn inactivity_expired(
+    last_activity: tokio::time::Instant,
+    now: tokio::time::Instant,
+    bound: Duration,
+    turn_in_flight: bool,
+) -> bool {
+    !bound.is_zero() && !turn_in_flight && now.duration_since(last_activity) >= bound
+}
+
+#[cfg(test)]
+mod inactivity_tests {
+    use super::*;
+
+    #[test]
+    fn zero_disables_expiry_and_in_flight_turns_defer_it() {
+        let started = tokio::time::Instant::now();
+        let after_bound = started + Duration::from_secs(61);
+
+        assert!(!inactivity_expired(
+            started,
+            after_bound,
+            Duration::ZERO,
+            false
+        ));
+        assert!(!inactivity_expired(
+            started,
+            after_bound,
+            Duration::from_secs(60),
+            true
+        ));
+        assert!(inactivity_expired(
+            started,
+            after_bound,
+            Duration::from_secs(60),
+            false
+        ));
+    }
+
+    #[test]
+    fn dispatched_activity_restarts_the_inactivity_bound() {
+        let started = tokio::time::Instant::now();
+        let dispatched = started + Duration::from_secs(50);
+        let checked = started + Duration::from_secs(61);
+
+        assert!(!inactivity_expired(
+            dispatched,
+            checked,
+            Duration::from_secs(60),
+            false
+        ));
+    }
+}
+
 pub fn run() -> Result<()> {
     config::propagate_legacy_env_vars();
     tokio_main()
@@ -1601,6 +1654,21 @@ async fn tokio_main() -> Result<()> {
     let mut typing_channels: HashMap<Uuid, ThreadTags> = HashMap::new();
     let mut presence_task: Option<tokio::task::JoinHandle<()>> = None;
 
+    // Independent of pool readiness: a never-mentioned lazy agent must still
+    // self-terminate. The watch interval is capped so small configured bounds
+    // remain reasonably precise without waking long-lived agents frequently.
+    let inactivity_bound = Duration::from_secs(config.exit_after_inactivity_secs);
+    let mut last_activity = tokio::time::Instant::now();
+    let mut inactivity_reaper = if inactivity_bound.is_zero() {
+        None
+    } else {
+        let interval = inactivity_bound.min(Duration::from_secs(30));
+        Some(tokio::time::interval_at(
+            tokio::time::Instant::now() + interval,
+            interval,
+        ))
+    };
+
     // Runs at the TOP of every loop iteration via Instant check — cannot be
     // starved by the biased select. Slot refill spawns background tasks so
     // spawn_and_init never blocks the main loop.
@@ -1774,7 +1842,9 @@ async fn tokio_main() -> Result<()> {
             // called on relay events or pool results, neither of which
             // arrive when the channel is silent.
             if queue.has_flushable_work() {
-                for (channel_id, thread_tags) in dispatch_pending(&mut pool, &mut queue, &ctx) {
+                for (channel_id, thread_tags) in
+                    dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
+                {
                     typing_channels.insert(channel_id, thread_tags);
                 }
             }
@@ -1810,7 +1880,9 @@ async fn tokio_main() -> Result<()> {
         // this, batches requeued during crash recovery sit idle until the
         // next relay event arrives — which can be minutes on quiet channels.
         if respawn_collected {
-            for (channel_id, thread_tags) in dispatch_pending(&mut pool, &mut queue, &ctx) {
+            for (channel_id, thread_tags) in
+                dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
+            {
                 typing_channels.insert(channel_id, thread_tags);
             }
         }
@@ -2258,7 +2330,7 @@ async fn tokio_main() -> Result<()> {
                             }
                             if pool_ready {
                                 for (channel_id, thread_tags) in
-                                    dispatch_pending(&mut pool, &mut queue, &ctx)
+                                    dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
                                 {
                                     typing_channels.insert(channel_id, thread_tags);
                                 }
@@ -2275,6 +2347,27 @@ async fn tokio_main() -> Result<()> {
                     }
                     None
                 }
+                _ = async {
+                    match inactivity_reaper.as_mut() {
+                        Some(timer) => timer.tick().await,
+                        None => std::future::pending().await,
+                    }
+                } => {
+                    let _ = result_rx;
+                    if inactivity_expired(
+                        last_activity,
+                        tokio::time::Instant::now(),
+                        inactivity_bound,
+                        queue.has_in_flight() || heartbeat_in_flight,
+                    ) {
+                        tracing::info!(
+                            inactivity_seconds = config.exit_after_inactivity_secs,
+                            "inactivity bound reached — exiting gracefully"
+                        );
+                        let _ = shutdown_tx.send(());
+                    }
+                    None
+                }
                 _ = async {
                     match heartbeat.as_mut() {
                         Some(hb) => hb.tick().await,
@@ -2287,7 +2380,7 @@ async fn tokio_main() -> Result<()> {
                     } else if queue.has_flushable_work() {
                         tracing::debug!("heartbeat_skipped_events");
                         for (channel_id, thread_tags) in
-                            dispatch_pending(&mut pool, &mut queue, &ctx)
+                            dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
                         {
                             typing_channels.insert(channel_id, thread_tags);
                         }
@@ -2385,7 +2478,9 @@ async fn tokio_main() -> Result<()> {
                 {
                     break;
                 }
-                for (channel_id, thread_tags) in dispatch_pending(&mut pool, &mut queue, &ctx) {
+                for (channel_id, thread_tags) in
+                    dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
+                {
                     typing_channels.insert(channel_id, thread_tags);
                 }
             }
@@ -2408,7 +2503,9 @@ async fn tokio_main() -> Result<()> {
                     tracing::error!("all agents dead — exiting");
                     break;
                 }
-                for (channel_id, thread_tags) in dispatch_pending(&mut pool, &mut queue, &ctx) {
+                for (channel_id, thread_tags) in
+                    dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
+                {
                     typing_channels.insert(channel_id, thread_tags);
                 }
             }
@@ -2550,7 +2647,9 @@ async fn tokio_main() -> Result<()> {
                 // tear down the in-flight task; on its completion the
                 // queue drains. We still try here in case the in-flight
                 // task has already returned.
-                for (channel_id, thread_tags) in dispatch_pending(&mut pool, &mut queue, &ctx) {
+                for (channel_id, thread_tags) in
+                    dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
+                {
                     typing_channels.insert(channel_id, thread_tags);
                 }
             }
@@ -2577,7 +2676,7 @@ async fn tokio_main() -> Result<()> {
                             None,
                         );
                         for (channel_id, thread_tags) in
-                            dispatch_pending(&mut pool, &mut queue, &ctx)
+                            dispatch_pending(&mut pool, &mut queue, &ctx, &mut last_activity)
                         {
                             typing_channels.insert(channel_id, thread_tags);
                         }
@@ -2911,6 +3010,7 @@ fn dispatch_pending(
     pool: &mut AgentPool,
     queue: &mut EventQueue,
     ctx: &Arc<PromptContext>,
+    last_activity: &mut tokio::time::Instant,
 ) -> Vec<(Uuid, ThreadTags)> {
     let mut dispatched_channels = Vec::new();
     loop {
@@ -2990,6 +3090,7 @@ fn dispatch_pending(
             },
         );
         dispatched_channels.push((channel_id, typing_scope));
+        *last_activity = tokio::time::Instant::now();
     }
     tracing::debug!(
         dispatched = dispatched_channels.len(),
@@ -5031,6 +5132,7 @@ mod build_mcp_servers_tests {
             persona_env_vars: vec![],
             has_generated_codex_config: false,
             relay_observer: false,
+            exit_after_inactivity_secs: 0,
             lazy_pool: false,
             agent_owner: None,
             no_base_prompt: false,
@@ -5252,6 +5354,7 @@ mod error_outcome_emission_tests {
             persona_env_vars: vec![],
             has_generated_codex_config: false,
             relay_observer: false,
+            exit_after_inactivity_secs: 0,
             lazy_pool: false,
             agent_owner: None,
             no_base_prompt: false,
diff --git a/crates/buzz-acp/src/pool.rs b/crates/buzz-acp/src/pool.rs
index 158477c0af..64edf68ee2 100644
--- a/crates/buzz-acp/src/pool.rs
+++ b/crates/buzz-acp/src/pool.rs
@@ -32,6 +32,7 @@ use uuid::Uuid;
 use crate::acp::{
     extract_model_config_options, extract_model_state, model_in_catalog,
     resolve_model_switch_method, AcpClient, AcpError, McpServer, ModelSwitchMethod, StopReason,
+    SystemPromptTransport,
 };
 use crate::config::{compose_session_title, DedupMode, PermissionMode};
 use crate::observer;
@@ -171,6 +172,13 @@ pub struct OwnedAgent {
     pub protocol_version: u32,
 }
 
+/// Package name reported by `claude-agent-acp` in its `initialize` response.
+/// Any adapter reporting this name supports `_meta.systemPrompt: {append: ...}`
+/// on `session/new` — the feature landed in v0.6.0 (Oct 2025), before the
+/// `@zed-industries/claude-code-acp` → `@agentclientprotocol/claude-agent-acp`
+/// rename, so the new name is a reliable capability gate.
+const CLAUDE_AGENT_ACP_NAME: &str = "@agentclientprotocol/claude-agent-acp";
+
 fn has_system_prompt_support(
     protocol_version: u32,
     agent_name: &str,
@@ -178,20 +186,25 @@ fn has_system_prompt_support(
 ) -> bool {
     if agent_name == "goose" {
         goose_system_prompt_supported == Some(true)
+    } else if agent_name == CLAUDE_AGENT_ACP_NAME {
+        true
     } else {
         protocol_version >= 2
     }
 }
 
-fn session_new_system_prompt(
+fn session_new_system_prompt<'a>(
     is_goose: bool,
     protocol_version: u32,
-    prompt: Option<&str>,
-) -> Option<&str> {
-    if is_goose || protocol_version < 2 {
+    agent_name: &str,
+    prompt: Option<&'a str>,
+) -> Option<SystemPromptTransport<'a>> {
+    if is_goose || (protocol_version < 2 && agent_name != CLAUDE_AGENT_ACP_NAME) {
         None
+    } else if agent_name == CLAUDE_AGENT_ACP_NAME {
+        prompt.map(SystemPromptTransport::ClaudeMeta)
     } else {
-        prompt
+        prompt.map(SystemPromptTransport::Field)
     }
 }
 
@@ -907,6 +920,7 @@ async fn create_session_and_apply_model(
             session_new_system_prompt(
                 is_goose,
                 agent.protocol_version,
+                &agent.agent_name,
                 combined_system_prompt.as_deref(),
             ),
             session_title.as_deref(),
@@ -3624,7 +3638,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 {
@@ -3642,7 +3660,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)
@@ -3993,18 +4017,48 @@ mod tests {
         assert!(has_system_prompt_support(2, "goose", Some(true)));
         assert!(has_system_prompt_support(1, "goose", Some(true)));
         assert!(has_system_prompt_support(2, "buzz-agent", None));
+        // Goose never receives system prompt via session/new (uses post-hoc method).
         assert_eq!(
-            session_new_system_prompt(true, 2, Some("instructions")),
+            session_new_system_prompt(true, 2, "goose", Some("instructions")),
             None
         );
+        // Protocol-v2 non-goose gets Field transport.
         assert_eq!(
-            session_new_system_prompt(false, 2, Some("instructions")),
-            Some("instructions")
+            session_new_system_prompt(false, 2, "buzz-agent", Some("instructions")),
+            Some(SystemPromptTransport::Field("instructions"))
         );
+        // Protocol-v1 non-goose, non-claude gets None (legacy user-message framing).
         assert_eq!(
-            session_new_system_prompt(false, 1, Some("instructions")),
+            session_new_system_prompt(false, 1, "codex", Some("instructions")),
             None
         );
+        // claude-agent-acp gets ClaudeMeta transport regardless of protocol version.
+        assert_eq!(
+            session_new_system_prompt(false, 1, CLAUDE_AGENT_ACP_NAME, Some("instructions")),
+            Some(SystemPromptTransport::ClaudeMeta("instructions"))
+        );
+        assert_eq!(
+            session_new_system_prompt(true, 1, CLAUDE_AGENT_ACP_NAME, Some("instructions")),
+            None,
+            "goose path must never produce a transport even when agent_name matches"
+        );
+    }
+
+    #[test]
+    fn claude_agent_acp_has_system_prompt_support_regardless_of_protocol_version() {
+        // claude-agent-acp declares protocolVersion:1 but supports _meta.systemPrompt;
+        // has_system_prompt_support must return true so user-message framing is suppressed.
+        assert!(has_system_prompt_support(1, CLAUDE_AGENT_ACP_NAME, None));
+        assert!(has_system_prompt_support(2, CLAUDE_AGENT_ACP_NAME, None));
+    }
+
+    #[test]
+    fn old_zed_adapter_name_falls_through_to_protocol_version_gate() {
+        // The renamed @zed-industries package predates the _meta.systemPrompt support,
+        // so it must not be treated as capable and stays on legacy user-message framing.
+        let old_name = "@zed-industries/claude-code-acp";
+        assert!(!has_system_prompt_support(1, old_name, None));
+        assert!(has_system_prompt_support(2, old_name, None));
     }
 
     #[test]
@@ -6022,10 +6076,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.
@@ -6056,10 +6112,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.
@@ -6091,10 +6149,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.
@@ -6126,10 +6186,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.
@@ -6158,10 +6220,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,
         };
 
@@ -6205,10 +6269,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,
         };
 
@@ -6248,6 +6314,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/queue.rs b/crates/buzz-acp/src/queue.rs
index 029bf86dbf..5c960de202 100644
--- a/crates/buzz-acp/src/queue.rs
+++ b/crates/buzz-acp/src/queue.rs
@@ -646,6 +646,11 @@ impl EventQueue {
         self.in_flight_channels.contains(&channel_id)
     }
 
+    /// Whether any channel currently has a turn in flight.
+    pub fn has_in_flight(&self) -> bool {
+        !self.in_flight_channels.is_empty()
+    }
+
     // ── Goose-native steer withhold (side table) ──────────────────────────
     //
     // While a goose-native `_goose/unstable/session/steer` write is in flight
diff --git a/crates/buzz-acp/src/usage.rs b/crates/buzz-acp/src/usage.rs
index 1629eee935..56b772d12c 100644
--- a/crates/buzz-acp/src/usage.rs
+++ b/crates/buzz-acp/src/usage.rs
@@ -85,12 +85,16 @@ pub(crate) struct UsageUpdatePayload {
     pub context_limit: u64,
     pub accumulated_input_tokens: u64,
     pub accumulated_output_tokens: u64,
-    /// The cache-served subset of `accumulated_input_tokens`. Optional — goose
-    /// does not send it, and buzz-agent only reports a non-zero value when the
-    /// provider returned a cache split, so `0` legitimately means either "no
-    /// cache hits" or "provider reported none".
-    #[serde(default)]
-    pub accumulated_cached_input_tokens: u64,
+    /// The cache-served subset of `accumulated_input_tokens`.
+    ///
+    /// `None` when the harness did not include the field (e.g. goose, which
+    /// never emits it). `Some(0)` when the harness explicitly reported zero
+    /// cache hits. The distinction matters: `None` means "we don't know",
+    /// while `Some(0)` means "provider confirmed no cache was used".
+    ///
+    /// Do NOT use `#[serde(default)]` here — that would collapse the absent
+    /// case into `Some(0)` and destroy provenance in the append-only archive.
+    pub accumulated_cached_input_tokens: Option<u64>,
     pub accumulated_cost: Option<f64>,
     /// Session-cumulative genuine provider total tokens. Optional — only
     /// emitted by buzz-agent when every turn in the session so far supplied a
@@ -125,6 +129,12 @@ struct SessionState {
     /// `None` when the session has never emitted a provider total (Unseen) or
     /// when any prior turn lacked one (poisoned).
     last_total: Option<u64>,
+    /// Cumulative cache-read input tokens at the end of the LAST PUBLISHED turn.
+    /// `None` when the harness has never reported this field (e.g. goose).
+    /// `Some(n)` when at least one payload included the field. Field-local:
+    /// a decrease in this counter taints only the cache-read delta, not
+    /// `delta_reliable` or the input/output deltas.
+    last_cached_input: Option<u64>,
 }
 
 /// Per-turn usage record exposed to `TurnCompletionGuard` for NIP-AM publishing.
@@ -151,6 +161,12 @@ pub struct TurnUsage {
     /// Per-turn cost delta (`current − previous`); `None` when unreliable or
     /// either snapshot is missing.
     pub turn_cost_usd: Option<f64>,
+    /// Per-turn cache-read token delta (`current − previous`); `None` when no
+    /// baseline exists, either snapshot is `None` (harness did not report it),
+    /// or the cumulative counter decreased (field-local taint). Field-local:
+    /// a decrease here never flips `delta_reliable` or invalidates the
+    /// input/output deltas.
+    pub turn_cache_read_tokens: Option<u64>,
     /// Session-cumulative input tokens as reported by goose at end of turn.
     pub cumulative_input_tokens: u64,
     /// Session-cumulative output tokens as reported by goose at end of turn.
@@ -160,6 +176,11 @@ pub struct TurnUsage {
     pub cumulative_total_tokens: Option<u64>,
     /// Session-cumulative estimated cost in USD; `None` if goose did not report it.
     pub cumulative_cost_usd: Option<f64>,
+    /// Session-cumulative cache-read input tokens as reported by buzz-agent.
+    /// `None` when the harness has never reported this field (e.g. goose or
+    /// any harness that omits `accumulatedCachedInputTokens`).
+    /// `Some(0)` when the harness reported zero cache hits.
+    pub cumulative_cache_read_tokens: Option<u64>,
     /// Effective model id for this turn (maps to NIP-AM `model`). `None` if the
     /// harness did not include the model in its usage notification.
     pub model: Option<String>,
@@ -239,6 +260,7 @@ impl UsageTracker {
         let current_output = payload.accumulated_output_tokens;
         let current_cost = payload.accumulated_cost;
         let current_total = payload.accumulated_total_tokens;
+        let current_cached_input = payload.accumulated_cached_input_tokens;
 
         // Determine whether this session is currently in-flight so we know
         // whether to set `pending`. We compute the delta regardless so that
@@ -294,6 +316,21 @@ impl UsageTracker {
             None => None, // no baseline yet
         };
 
+        // Cache-read token delta: field-local — never affects `delta_reliable`
+        // or the input/output deltas. Null when: no baseline exists, either
+        // snapshot is None (harness did not report the field), or the cumulative
+        // counter decreased (harness restart, overflow).
+        // Some(0) is a valid result when both snapshots are Some(0) — it means
+        // the harness confirmed zero cache hits this turn, not that data is absent.
+        let turn_cache_read = match self.sessions.get(session_id) {
+            Some(prev) => match (current_cached_input, prev.last_cached_input) {
+                (Some(cur), Some(p)) if cur >= p => Some(cur - p),
+                (Some(_), Some(_)) => None, // decrease → field-local taint
+                _ => None,                  // either snapshot absent → no delta
+            },
+            None => None, // no baseline yet
+        };
+
         if is_in_flight {
             // In-flight-match: update pending with the latest cumulative values.
             // Baseline is NOT advanced here — it advances only on take().
@@ -305,10 +342,12 @@ impl UsageTracker {
                 turn_output_tokens: turn_output,
                 turn_total_tokens: turn_total,
                 turn_cost_usd: turn_cost,
+                turn_cache_read_tokens: turn_cache_read,
                 cumulative_input_tokens: current_input,
                 cumulative_output_tokens: current_output,
                 cumulative_total_tokens: current_total,
                 cumulative_cost_usd: current_cost,
+                cumulative_cache_read_tokens: current_cached_input,
                 model: payload.model.clone(),
             });
         } else if self.in_flight_session.is_none() {
@@ -327,6 +366,7 @@ impl UsageTracker {
                     last_output: current_output,
                     last_cost: current_cost,
                     last_total: current_total,
+                    last_cached_input: current_cached_input,
                 },
             );
         }
@@ -355,6 +395,7 @@ impl UsageTracker {
                 last_output: record.cumulative_output_tokens,
                 last_cost: record.cumulative_cost_usd,
                 last_total: record.cumulative_total_tokens,
+                last_cached_input: record.cumulative_cache_read_tokens,
             },
         );
         Some(record)
@@ -366,9 +407,9 @@ mod tests {
     use super::*;
 
     /// The camelCase key buzz-agent actually puts on the wire must land on the
-    /// field. A rename mismatch here would deserialize to the serde default of
-    /// 0, and every trial would price as if nothing had ever been cached — the
-    /// exact silent failure this field was added to remove.
+    /// field. A rename mismatch here would deserialize to None, and every trial
+    /// would be treated as "not reported" — the exact silent failure this field
+    /// was added to remove.
     #[test]
     fn cached_input_tokens_deserialize_from_the_wire_key() {
         let p: UsageUpdatePayload = serde_json::from_value(serde_json::json!({
@@ -379,13 +420,14 @@ mod tests {
             "accumulatedCachedInputTokens": 5_033,
         }))
         .expect("payload must deserialize");
-        assert_eq!(p.accumulated_cached_input_tokens, 5_033);
-        assert!(p.accumulated_cached_input_tokens <= p.accumulated_input_tokens);
+        assert_eq!(p.accumulated_cached_input_tokens, Some(5_033));
+        assert!(p.accumulated_cached_input_tokens.unwrap() <= p.accumulated_input_tokens);
     }
 
-    /// goose does not send the field; its payloads must still deserialize.
+    /// goose does not send the field; its payloads must deserialize with None —
+    /// not zero — so that "not reported" is preserved distinct from "reported zero".
     #[test]
-    fn a_payload_without_the_cache_field_defaults_to_zero() {
+    fn a_payload_without_the_cache_field_deserializes_as_none() {
         let p: UsageUpdatePayload = serde_json::from_value(serde_json::json!({
             "used": 500,
             "contextLimit": 200_000,
@@ -393,7 +435,28 @@ mod tests {
             "accumulatedOutputTokens": 100,
         }))
         .expect("payload must deserialize without the cache field");
-        assert_eq!(p.accumulated_cached_input_tokens, 0);
+        assert!(
+            p.accumulated_cached_input_tokens.is_none(),
+            "absent field must be None, not Some(0)"
+        );
+    }
+
+    /// A harness that explicitly reports zero cache hits must produce Some(0),
+    /// not None — so downstream analytics can distinguish "confirmed zero" from
+    /// "not reported".
+    #[test]
+    fn a_payload_with_explicit_zero_cache_field_deserializes_as_some_zero() {
+        let p: UsageUpdatePayload = serde_json::from_value(serde_json::json!({
+            "accumulatedInputTokens": 400,
+            "accumulatedOutputTokens": 100,
+            "accumulatedCachedInputTokens": 0,
+        }))
+        .expect("payload must deserialize with zero cache field");
+        assert_eq!(
+            p.accumulated_cached_input_tokens,
+            Some(0),
+            "explicit zero must be Some(0), not None"
+        );
     }
 
     fn payload(input: u64, output: u64, cost: Option<f64>) -> UsageUpdatePayload {
@@ -402,7 +465,7 @@ mod tests {
             context_limit: 200_000,
             accumulated_input_tokens: input,
             accumulated_output_tokens: output,
-            accumulated_cached_input_tokens: 0,
+            accumulated_cached_input_tokens: None,
             accumulated_cost: cost,
             accumulated_total_tokens: None,
             model: None,
@@ -415,7 +478,7 @@ mod tests {
             context_limit: 0,
             accumulated_input_tokens: input,
             accumulated_output_tokens: output,
-            accumulated_cached_input_tokens: 0,
+            accumulated_cached_input_tokens: None,
             accumulated_cost: cost,
             accumulated_total_tokens: None,
             model: None,
@@ -913,7 +976,7 @@ mod tests {
             context_limit: 200_000,
             accumulated_input_tokens: input,
             accumulated_output_tokens: output,
-            accumulated_cached_input_tokens: 0,
+            accumulated_cached_input_tokens: None,
             accumulated_cost: cost,
             accumulated_total_tokens: None,
             model: model.map(str::to_string),
@@ -977,7 +1040,7 @@ mod tests {
             context_limit: 200_000,
             accumulated_input_tokens: input,
             accumulated_output_tokens: output,
-            accumulated_cached_input_tokens: 0,
+            accumulated_cached_input_tokens: None,
             accumulated_cost: None,
             accumulated_total_tokens: total,
             model: None,
@@ -1132,4 +1195,320 @@ mod tests {
         );
         assert_eq!(usage.cumulative_total_tokens, Some(250));
     }
+
+    // ── cache-read token threading ──────────────────────────────────────────
+
+    fn payload_with_cache(
+        input: u64,
+        output: u64,
+        cached_input: Option<u64>,
+    ) -> UsageUpdatePayload {
+        UsageUpdatePayload {
+            used: input + output,
+            context_limit: 200_000,
+            accumulated_input_tokens: input,
+            accumulated_output_tokens: output,
+            accumulated_cached_input_tokens: cached_input,
+            accumulated_cost: None,
+            accumulated_total_tokens: None,
+            model: None,
+        }
+    }
+
+    #[test]
+    fn cache_read_first_turn_produces_none_turn_delta_and_passes_cumulative_through() {
+        // First turn has no baseline → turn cache delta must be None, but
+        // cumulative_cache_read_tokens must carry the reported value through.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c1");
+        tracker.record("sess-c1", &payload_with_cache(1000, 200, Some(500)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(
+            usage.turn_cache_read_tokens.is_none(),
+            "first turn: no baseline → cache delta must be None"
+        );
+        assert_eq!(
+            usage.cumulative_cache_read_tokens,
+            Some(500),
+            "cumulative cache read passes through on first turn"
+        );
+        assert!(!usage.delta_reliable, "first turn is unreliable");
+    }
+
+    #[test]
+    fn cache_read_second_turn_delta_computed_correctly() {
+        // Second turn: cumulative cached 500 → 1200, delta = 700.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c2");
+        tracker.record("sess-c2", &payload_with_cache(1000, 200, Some(500)));
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-c2");
+        tracker.record("sess-c2", &payload_with_cache(2000, 350, Some(1200)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(usage.delta_reliable);
+        assert_eq!(
+            usage.turn_cache_read_tokens,
+            Some(700),
+            "cache delta = 1200 - 500 = 700"
+        );
+        assert_eq!(
+            usage.cumulative_cache_read_tokens,
+            Some(1200),
+            "cumulative cache passes through"
+        );
+    }
+
+    #[test]
+    fn cache_read_decrease_nulls_turn_cache_but_leaves_delta_reliable() {
+        // Cache counter decrease → cache delta None (field-local taint), but
+        // delta_reliable and input/output deltas are NOT affected.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c3");
+        tracker.record("sess-c3", &payload_with_cache(1000, 200, Some(800)));
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-c3");
+        // Cache counter decreased: 800 → 50.
+        tracker.record("sess-c3", &payload_with_cache(1500, 300, Some(50)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(
+            usage.delta_reliable,
+            "cache decrease must NOT flip delta_reliable — field-local"
+        );
+        assert_eq!(
+            usage.turn_input_tokens,
+            Some(500),
+            "input/output delta unaffected by cache decrease"
+        );
+        assert_eq!(usage.turn_output_tokens, Some(100));
+        assert!(
+            usage.turn_cache_read_tokens.is_none(),
+            "cache counter decrease → turn_cache_read_tokens None (field-local taint)"
+        );
+        assert_eq!(
+            usage.cumulative_cache_read_tokens,
+            Some(50),
+            "cumulative still passes through from payload even on decrease"
+        );
+    }
+
+    #[test]
+    fn cache_read_explicit_zero_payload_after_explicit_zero_baseline_produces_some_zero_delta() {
+        // When both baseline and current are Some(0), turn_cache_read_tokens must
+        // be Some(0) — confirmed zero, not absent.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c4");
+        tracker.record("sess-c4", &payload_with_cache(1000, 200, Some(0)));
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-c4");
+        tracker.record("sess-c4", &payload_with_cache(1500, 300, Some(0)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(usage.delta_reliable);
+        assert_eq!(
+            usage.turn_cache_read_tokens,
+            Some(0),
+            "explicit zero on both sides → Some(0), not None"
+        );
+        assert_eq!(usage.cumulative_cache_read_tokens, Some(0));
+    }
+
+    #[test]
+    fn cache_read_threads_through_setup_notification_baseline() {
+        // A setup notification (before begin_turn) with a nonzero cache count
+        // must update the committed baseline so the first real turn gets a
+        // correct delta from that starting point.
+        let mut tracker = UsageTracker::default();
+
+        // Setup notification: cumulative cache = 300.
+        tracker.record("sess-c5", &payload_with_cache(1000, 200, Some(300)));
+
+        tracker.begin_turn("sess-c5");
+        tracker.record("sess-c5", &payload_with_cache(1500, 350, Some(700)));
+        let usage = tracker.take().expect("pending");
+
+        assert!(usage.delta_reliable, "baseline from setup: reliable");
+        assert_eq!(
+            usage.turn_cache_read_tokens,
+            Some(400),
+            "cache delta from setup baseline: 700 - 300 = 400"
+        );
+        assert_eq!(usage.cumulative_cache_read_tokens, Some(700));
+    }
+
+    #[test]
+    fn cache_read_omitted_field_produces_none_cumulative_and_no_turn_delta() {
+        // A harness that omits accumulatedCachedInputTokens (e.g. goose) must
+        // produce None cumulative_cache_read_tokens — not Some(0) — and the
+        // turn delta must also be None even on the second turn.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c6");
+        // payload() uses None for accumulated_cached_input_tokens.
+        tracker.record("sess-c6", &payload(1000, 200, None));
+        let t1 = tracker.take().expect("turn 1");
+
+        assert!(
+            t1.cumulative_cache_read_tokens.is_none(),
+            "goose-shaped payload: cumulative must be None, not Some(0)"
+        );
+        assert!(
+            t1.turn_cache_read_tokens.is_none(),
+            "first turn always has no turn delta"
+        );
+
+        tracker.begin_turn("sess-c6");
+        tracker.record("sess-c6", &payload(1500, 300, None));
+        let t2 = tracker.take().expect("turn 2");
+
+        assert!(
+            t2.cumulative_cache_read_tokens.is_none(),
+            "continued goose session: cumulative must remain None"
+        );
+        assert!(
+            t2.turn_cache_read_tokens.is_none(),
+            "absent field on both sides → no turn delta invented"
+        );
+        assert!(
+            t2.delta_reliable,
+            "input/output reliability unaffected by absent cache field"
+        );
+    }
+
+    #[test]
+    fn cache_read_baseline_absent_then_present_produces_no_delta() {
+        // If the first turn omits the cache field (baseline stored as None) and
+        // the second turn reports a value, no delta can be computed — we have no
+        // baseline to subtract from. The cumulative value should still pass through.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c7");
+        tracker.record("sess-c7", &payload(1000, 200, None)); // no cache field
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-c7");
+        tracker.record("sess-c7", &payload_with_cache(1500, 300, Some(400)));
+        let usage = tracker.take().expect("turn 2");
+
+        assert!(
+            usage.turn_cache_read_tokens.is_none(),
+            "absent baseline → no turn delta even when current has a value"
+        );
+        assert_eq!(
+            usage.cumulative_cache_read_tokens,
+            Some(400),
+            "cumulative from current payload passes through"
+        );
+        assert!(usage.delta_reliable, "input/output reliability unaffected");
+    }
+
+    #[test]
+    fn cache_read_baseline_present_then_absent_produces_no_delta() {
+        // If the first turn reports the cache field but the second omits it
+        // (harness switched), no delta should be produced and cumulative is None.
+        let mut tracker = UsageTracker::default();
+        tracker.begin_turn("sess-c8");
+        tracker.record("sess-c8", &payload_with_cache(1000, 200, Some(300)));
+        let _ = tracker.take();
+
+        tracker.begin_turn("sess-c8");
+        tracker.record("sess-c8", &payload(1500, 300, None)); // no cache field
+        let usage = tracker.take().expect("turn 2");
+
+        assert!(
+            usage.turn_cache_read_tokens.is_none(),
+            "absent current → no turn delta"
+        );
+        assert!(
+            usage.cumulative_cache_read_tokens.is_none(),
+            "absent field: cumulative must be None"
+        );
+        assert!(usage.delta_reliable, "input/output reliability unaffected");
+    }
+
+    #[test]
+    fn pool_omitted_cache_field_publishes_no_cache_read_tokens_in_kind44200() {
+        // End-to-end: a buzz-agent or goose payload that omits the cache field
+        // must NOT publish cacheReadTokens in the kind:44200 event — neither
+        // in turn nor cumulative counts.
+        //
+        // This is the core acceptance test for Thufir's finding: the old code
+        // would publish cacheReadTokens: 0 for every harness regardless of
+        // whether the field was reported.
+        use crate::pool::build_turn_metric_counts;
+
+        let usage = TurnUsage {
+            session_id: "sess-pool-none".into(),
+            turn_seq: 2,
+            delta_reliable: true,
+            turn_input_tokens: Some(400),
+            turn_output_tokens: Some(100),
+            turn_total_tokens: None,
+            turn_cost_usd: None,
+            turn_cache_read_tokens: None,
+            cumulative_input_tokens: 700,
+            cumulative_output_tokens: 200,
+            cumulative_total_tokens: None,
+            cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: None, // harness did not report the field
+            model: None,
+        };
+
+        let (turn_counts, cumulative_counts) = build_turn_metric_counts(&usage);
+
+        let turn = turn_counts.expect("turn counts must be present (delta reliable)");
+        assert!(
+            turn.cache_read_tokens.is_none(),
+            "omitted cache field: turn cacheReadTokens must be absent from kind:44200"
+        );
+
+        let cumulative = cumulative_counts.expect("cumulative counts always present");
+        assert!(
+            cumulative.cache_read_tokens.is_none(),
+            "omitted cache field: cumulative cacheReadTokens must be absent from kind:44200"
+        );
+    }
+
+    #[test]
+    fn pool_reported_cache_field_publishes_nonzero_cache_read_tokens_in_kind44200() {
+        // End-to-end: a buzz-agent payload with a nonzero cache count must
+        // publish cacheReadTokens in both turn and cumulative counts.
+        use crate::pool::build_turn_metric_counts;
+
+        let usage = TurnUsage {
+            session_id: "sess-pool-some".into(),
+            turn_seq: 2,
+            delta_reliable: true,
+            turn_input_tokens: Some(400),
+            turn_output_tokens: Some(100),
+            turn_total_tokens: None,
+            turn_cost_usd: None,
+            turn_cache_read_tokens: Some(300),
+            cumulative_input_tokens: 700,
+            cumulative_output_tokens: 200,
+            cumulative_total_tokens: None,
+            cumulative_cost_usd: None,
+            cumulative_cache_read_tokens: Some(600),
+            model: None,
+        };
+
+        let (turn_counts, cumulative_counts) = build_turn_metric_counts(&usage);
+
+        let turn = turn_counts.expect("turn counts present");
+        assert_eq!(
+            turn.cache_read_tokens,
+            Some(300),
+            "nonzero turn cache: must appear in kind:44200 turn counts"
+        );
+
+        let cumulative = cumulative_counts.expect("cumulative counts present");
+        assert_eq!(
+            cumulative.cache_read_tokens,
+            Some(600),
+            "nonzero cumulative cache: must appear in kind:44200 cumulative counts"
+        );
+    }
 }
diff --git a/crates/buzz-agent/src/agent.rs b/crates/buzz-agent/src/agent.rs
index 8e14fee195..ff87a33a1a 100644
--- a/crates/buzz-agent/src/agent.rs
+++ b/crates/buzz-agent/src/agent.rs
@@ -13,8 +13,8 @@ use crate::mcp::McpRegistry;
 use crate::mcp::ResultBudget;
 
 use crate::types::{
-    AgentError, ContentBlock, HistoryItem, ProviderStop, StopReason, ToolCall, ToolResult,
-    ToolResultContent, TurnTotalState,
+    AgentError, ContentBlock, HistoryItem, ProviderStop, SessionUsageBaseline, StopReason,
+    ToolCall, ToolResult, ToolResultContent, TurnTotalState,
 };
 use crate::wire::{self, WireSender};
 
@@ -150,9 +150,40 @@ pub struct RunCtx<'a> {
     /// Reset to `Unseen` at turn start in `run()`. Callers must not derive a
     /// total by summing input+output — that is the UI display approximation only.
     pub turn_total_state: &'a mut TurnTotalState,
+    /// Session-cumulative counters as they stood when this turn began. Added to
+    /// the `turn_*` accumulators above to report a cumulative figure mid-turn;
+    /// the session's own copy is only advanced once, after the turn returns.
+    pub usage_baseline: SessionUsageBaseline,
 }
 
 impl RunCtx<'_> {
+    /// Send a session-cumulative `usage_update` reflecting everything observed
+    /// up to and including the most recent LLM response.
+    ///
+    /// The figure is the turn-start baseline plus this turn's running
+    /// accumulators, which is exactly what `session/prompt` will fold into the
+    /// session once the turn returns — so a mid-turn notification and the
+    /// end-of-turn one agree, and a turn that never returns has still reported
+    /// everything but its final in-flight request.
+    async fn emit_usage_update(&self) {
+        let base = self.usage_baseline;
+        let payload = wire::usage_update_payload(
+            base.input_tokens
+                .saturating_add(self.turn_input_tokens.unwrap_or(0)),
+            base.output_tokens
+                .saturating_add(self.turn_output_tokens.unwrap_or(0)),
+            base.cached_input_tokens
+                .saturating_add(self.turn_cached_input_tokens.unwrap_or(0)),
+            base.total_state.merge_session(*self.turn_total_state),
+            self.effective_model,
+        );
+        wire::send(
+            self.wire,
+            wire::goose_session_update(self.session_id, payload),
+        )
+        .await;
+    }
+
     pub async fn run(&mut self, prompt: Vec<ContentBlock>) -> Result<StopReason, AgentError> {
         let user_text = prompt_to_text(prompt)?;
         if user_text.len() > MAX_PROMPT_BYTES {
@@ -299,6 +330,23 @@ impl RunCtx<'_> {
             // this gate rather than representing absent categories as zero.
             if response.input_tokens.is_some() || response.output_tokens.is_some() {
                 *self.turn_total_state = self.turn_total_state.fold(response.total_tokens);
+                // Report what the turn has burned SO FAR, before running the
+                // next round. A turn is many provider round-trips over many
+                // minutes, and until this point the only report was the one
+                // `session/prompt` sends after the turn returns — so a turn
+                // that was cancelled, timed out, or whose process was killed
+                // reported nothing at all, and its tokens (already billed)
+                // existed only in this stack frame. Reporting per round bounds
+                // the loss to the single request in flight.
+                //
+                // Emitting more than one `usage_update` per turn is expected by
+                // the consumer: buzz-acp's UsageTracker advances its committed
+                // baseline only when the turn's metric is published, so every
+                // notification within a turn measures from the same frozen
+                // baseline and the last one seen is the turn's true total.
+                // goose behaves the same way, which is why the tracker was
+                // written to tolerate it.
+                self.emit_usage_update().await;
             }
 
             if !response.reasoning.is_empty() {
diff --git a/crates/buzz-agent/src/lib.rs b/crates/buzz-agent/src/lib.rs
index 0a06187fa6..15eb57e2df 100644
--- a/crates/buzz-agent/src/lib.rs
+++ b/crates/buzz-agent/src/lib.rs
@@ -660,6 +660,7 @@ async fn run_prompt(app: Arc<App>, id: Value, params: Value, wire_tx: WireSender
         effective_model_override,
         run_id,
         mut steer_rx,
+        usage_baseline,
     ) = match acquire_session(&app, &p.session_id).await {
         Ok(v) => v,
         Err(reason) => {
@@ -711,6 +712,7 @@ async fn run_prompt(app: Arc<App>, id: Value, params: Value, wire_tx: WireSender
         turn_output_tokens: &mut turn_output_tokens,
         turn_cached_input_tokens: &mut turn_cached_input_tokens,
         turn_total_state: &mut turn_total_state,
+        usage_baseline,
     };
     let result = ctx.run(p.prompt).await;
     if let Some(s) = app.sessions.lock().await.get_mut(&sid) {
@@ -768,28 +770,16 @@ async fn run_prompt(app: Arc<App>, id: Value, params: Value, wire_tx: WireSender
         if let Some((accumulated_in, accumulated_out, accumulated_cached, accumulated_total)) =
             accumulated
         {
-            // Build the usage_update payload. `accumulatedTotalTokens` is only
-            // included when the cumulative is exactly known — never when Unseen
-            // (no total ever observed) or Unknown (at least one turn lacked a
-            // total). A goose consumer that doesn't recognise the field ignores it.
-            let mut update = serde_json::json!({
-                "sessionUpdate": "usage_update",
-                // used: total tokens as a context-usage proxy;
-                // contextLimit: 0 (buzz-agent has no context limit tracking).
-                "used": accumulated_in.saturating_add(accumulated_out),
-                "contextLimit": 0u64,
-                "accumulatedInputTokens": accumulated_in,
-                "accumulatedOutputTokens": accumulated_out,
-                // A subset of accumulatedInputTokens, not an addition to
-                // it. Extends goose's usage_update shape; a consumer that
-                // does not know the field ignores it and prices exactly as
-                // it did before.
-                "accumulatedCachedInputTokens": accumulated_cached,
-                "model": effective_model_str,
-            });
-            if let crate::types::TurnTotalState::Exact(total) = accumulated_total {
-                update["accumulatedTotalTokens"] = serde_json::json!(total);
-            }
+            // Same builder the run loop uses for its per-round reports, so the
+            // final notification is shape-identical to the ones that preceded
+            // it and a consumer taking the high-water mark lands on this one.
+            let update = wire::usage_update_payload(
+                accumulated_in,
+                accumulated_out,
+                accumulated_cached,
+                accumulated_total,
+                effective_model_str,
+            );
             wire::send(&wire_tx, goose_session_update(&sid, update)).await;
         }
     }
@@ -823,6 +813,7 @@ async fn acquire_session(
         Option<String>,
         String,
         mpsc::UnboundedReceiver<Vec<ContentBlock>>,
+        crate::types::SessionUsageBaseline,
     ),
     &'static str,
 > {
@@ -859,6 +850,17 @@ async fn acquire_session(
         effective_model,
         run_id,
         steer_rx,
+        // Snapshot rather than a handle: the run loop reports cumulative usage
+        // after every LLM round, and taking the sessions lock on each of those
+        // would serialise concurrent sessions behind one another's provider
+        // round-trips. Nothing else advances these counters while this turn
+        // holds `busy`, so the snapshot cannot go stale under it.
+        crate::types::SessionUsageBaseline {
+            input_tokens: s.accumulated_input_tokens,
+            output_tokens: s.accumulated_output_tokens,
+            cached_input_tokens: s.accumulated_cached_input_tokens,
+            total_state: s.accumulated_total_state,
+        },
     ))
 }
 
diff --git a/crates/buzz-agent/src/types.rs b/crates/buzz-agent/src/types.rs
index 343a75bf72..e386421981 100644
--- a/crates/buzz-agent/src/types.rs
+++ b/crates/buzz-agent/src/types.rs
@@ -308,6 +308,30 @@ impl TurnTotalState {
     }
 }
 
+/// The session-cumulative usage counters as of the START of a turn.
+///
+/// Copied out of the session under the lock when a turn begins and handed to
+/// `RunCtx` by value, so the run loop can emit a cumulative `usage_update`
+/// after every LLM round without reaching back into `App.sessions` (which it
+/// holds no handle to, and which is locked by the turn's own bookkeeping at
+/// both ends).
+///
+/// This exists so that usage is durable *during* a turn rather than only after
+/// it. The counters a turn accrues live in the prompt task's stack frame until
+/// the turn returns; a process killed mid-turn takes them with it and the
+/// tokens are billed by the provider but recorded nowhere. That is not
+/// hypothetical — it silently under-reported a long-horizon benchmark's cost by
+/// several-fold, because every phase of a `continue_until_timeout` run is
+/// terminated mid-turn by design.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct SessionUsageBaseline {
+    pub input_tokens: u64,
+    pub output_tokens: u64,
+    /// The cache-served subset of `input_tokens`, not an addition to it.
+    pub cached_input_tokens: u64,
+    pub total_state: TurnTotalState,
+}
+
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum StopReason {
     EndTurn,
diff --git a/crates/buzz-agent/src/wire.rs b/crates/buzz-agent/src/wire.rs
index 7b50e7982a..634fca03af 100644
--- a/crates/buzz-agent/src/wire.rs
+++ b/crates/buzz-agent/src/wire.rs
@@ -148,6 +148,48 @@ pub fn goose_session_update(sid: &str, update: Value) -> Value {
     })
 }
 
+/// Build the `usage_update` payload for a `_goose/unstable/session/update`.
+///
+/// Shared by the two places that report usage — after each LLM round inside a
+/// turn, and once more when the turn completes — so the wire shape cannot drift
+/// between them. A consumer takes the high-water mark per session, so the
+/// mid-turn payloads are supersets of each other and the final one wins; a
+/// divergence in field names or units between the two call sites would instead
+/// show up as tokens silently vanishing, which is the failure this reporting
+/// exists to prevent.
+///
+/// All counts are SESSION-cumulative, matching goose, so buzz-acp's
+/// `UsageTracker` can compute per-turn deltas symmetrically for both agents.
+pub fn usage_update_payload(
+    accumulated_input_tokens: u64,
+    accumulated_output_tokens: u64,
+    accumulated_cached_input_tokens: u64,
+    accumulated_total: crate::types::TurnTotalState,
+    model: &str,
+) -> Value {
+    let mut update = json!({
+        "sessionUpdate": "usage_update",
+        // used: total tokens as a context-usage proxy;
+        // contextLimit: 0 (buzz-agent has no context limit tracking).
+        "used": accumulated_input_tokens.saturating_add(accumulated_output_tokens),
+        "contextLimit": 0u64,
+        "accumulatedInputTokens": accumulated_input_tokens,
+        "accumulatedOutputTokens": accumulated_output_tokens,
+        // A subset of accumulatedInputTokens, not an addition to it. Extends
+        // goose's usage_update shape; a consumer that does not know the field
+        // ignores it and prices exactly as it did before.
+        "accumulatedCachedInputTokens": accumulated_cached_input_tokens,
+        "model": model,
+    });
+    // Only when the cumulative is exactly known — never when Unseen (no total
+    // ever observed) or Unknown (at least one turn lacked a total). A goose
+    // consumer that doesn't recognise the field ignores it.
+    if let Some(total) = accumulated_total.exact_value() {
+        update["accumulatedTotalTokens"] = json!(total);
+    }
+    update
+}
+
 /// A `session/update` notification carrying a `update._meta.goose.<key>` field.
 /// Used to advertise `activeRunId` (so steer-capable clients can target the
 /// in-flight run) and `queuedSteer` (so they can correlate an accepted steer
diff --git a/crates/buzz-agent/tests/fake_llm.rs b/crates/buzz-agent/tests/fake_llm.rs
index f782a9d476..ef6f9d2d80 100644
--- a/crates/buzz-agent/tests/fake_llm.rs
+++ b/crates/buzz-agent/tests/fake_llm.rs
@@ -933,6 +933,135 @@ async fn no_usage_turn_emits_no_usage_notification() {
     h.shutdown().await;
 }
 
+/// Usage must be reported after EVERY provider round, not only once the turn
+/// returns.
+///
+/// A turn is many provider round-trips over many minutes. While the only report
+/// was the one `session/prompt` sends after the turn returns, a turn whose
+/// process was killed mid-flight reported nothing at all: its counters lived in
+/// the prompt task's stack frame, the provider had already billed them, and no
+/// consumer ever saw them. That is not a corner case for a long-horizon
+/// benchmark — every phase of a `continue_until_timeout` run is terminated
+/// mid-turn by design, which under-reported one measured run's cost several-fold.
+///
+/// Two rounds with distinct usage. The assertion that matters is the FIRST
+/// notification: it must carry round 1's counts alone, proving it was sent
+/// before round 2 had returned, so a kill between the rounds would still have
+/// left round 1 on the wire.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn usage_is_reported_after_each_round_not_only_at_turn_end() {
+    let url = spawn_fake_llm(vec![
+        openai_tool_call_with_usage("call_round1", "fake__noop", json!({}), 15, 6),
+        openai_text_with_usage("done", 20, 8),
+    ])
+    .await;
+    let mut h = Harness::spawn(&url).await;
+    let sid = init_session(&mut h).await;
+
+    let p_id = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"go"}]}),
+        )
+        .await;
+
+    let (frames_before, response) = recv_until_with_drain(&mut h, |v| v["id"] == p_id).await;
+    assert_eq!(
+        response["result"]["stopReason"], "end_turn",
+        "turn must complete with end_turn"
+    );
+
+    let usage: Vec<&Value> = frames_before
+        .iter()
+        .filter(|v| is_usage_update(v))
+        .collect();
+    assert!(
+        usage.len() >= 2,
+        "expected a usage_update per round (2 rounds), got {}; frames: {frames_before:#?}",
+        usage.len()
+    );
+
+    // Round 1 alone — emitted while round 2 was still outstanding.
+    assert_eq!(
+        usage[0]["params"]["update"]["accumulatedInputTokens"],
+        json!(15u64),
+        "first notification must carry round 1's input tokens only"
+    );
+    assert_eq!(
+        usage[0]["params"]["update"]["accumulatedOutputTokens"],
+        json!(6u64),
+        "first notification must carry round 1's output tokens only"
+    );
+
+    // The last one is the turn total and is what a high-water-mark consumer keeps.
+    let last = usage[usage.len() - 1];
+    assert_eq!(
+        last["params"]["update"]["accumulatedInputTokens"],
+        json!(35u64),
+        "final notification must carry the turn total 15+20=35"
+    );
+    assert_eq!(
+        last["params"]["update"]["accumulatedOutputTokens"],
+        json!(14u64),
+        "final notification must carry the turn total 6+8=14"
+    );
+
+    h.shutdown().await;
+}
+
+/// A mid-turn report must be SESSION-cumulative, not turn-local.
+///
+/// The baseline handed to the run loop is a snapshot taken when the turn began;
+/// if it were dropped, a consumer taking the high-water mark per session would
+/// see turn 2's first round (a small number) arrive after turn 1's total and
+/// discard it, silently losing turn 2 for any turn that never completed.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn mid_turn_usage_includes_earlier_turns() {
+    let url = spawn_fake_llm(vec![
+        openai_text_with_usage("turn one", 10, 5),
+        openai_tool_call_with_usage("call_t2", "fake__noop", json!({}), 20, 8),
+        openai_text_with_usage("turn two done", 30, 9),
+    ])
+    .await;
+    let mut h = Harness::spawn(&url).await;
+    let sid = init_session(&mut h).await;
+
+    let p1 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"turn 1"}]}),
+        )
+        .await;
+    let (_, _) = recv_until_with_drain(&mut h, |v| v["id"] == p1).await;
+
+    let p2 = h
+        .send(
+            "session/prompt",
+            json!({"sessionId": sid, "prompt": [{"type":"text","text":"turn 2"}]}),
+        )
+        .await;
+    let (frames_before, _) = recv_until_with_drain(&mut h, |v| v["id"] == p2).await;
+
+    let first = frames_before
+        .iter()
+        .find(|v| is_usage_update(v))
+        .unwrap_or_else(|| {
+            panic!("expected a usage_update during turn 2; frames: {frames_before:#?}")
+        });
+    assert_eq!(
+        first["params"]["update"]["accumulatedInputTokens"],
+        json!(30u64),
+        "turn 2 round 1 must report 10 (turn 1) + 20 (this round), not 20"
+    );
+    assert_eq!(
+        first["params"]["update"]["accumulatedOutputTokens"],
+        json!(13u64),
+        "turn 2 round 1 must report 5 (turn 1) + 8 (this round), not 8"
+    );
+
+    h.shutdown().await;
+}
+
 /// When a turn is cancelled AFTER the provider has already returned a response
 /// (so token counts are observed), buzz-agent must still emit the usage
 /// notification before the cancelled `session/prompt` response.
diff --git a/crates/buzz-backend-kubernetes/Cargo.toml b/crates/buzz-backend-kubernetes/Cargo.toml
new file mode 100644
index 0000000000..1cd17030db
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/Cargo.toml
@@ -0,0 +1,36 @@
+[package]
+name = "buzz-backend-kubernetes"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+description = "Kubernetes backend provider for Buzz remote agents (docs/remote-agents.md)"
+
+[[bin]]
+name = "buzz-backend-kubernetes"
+path = "src/main.rs"
+
+[dependencies]
+kube = { workspace = true }
+k8s-openapi = { workspace = true }
+nostr = { workspace = true }
+tokio = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+sha2 = { workspace = true }
+hex = { workspace = true }
+rand = { workspace = true }
+chrono = { workspace = true }
+http = "1"
+http-body-util = "0.1"
+
+# Explicit rustls dep with the ring provider — required to install the
+# process-level CryptoProvider at startup. Without it this binary panics on its
+# first TLS connection to the apiserver: the release build compiles every
+# sidecar in one cargo invocation (.github/workflows/release.yml), which unifies
+# both ring and aws-lc-rs features and leaves rustls unable to auto-select a
+# provider. Same dependency and reason as crates/buzz-cli/Cargo.toml.
+rustls = { version = "0.23", default-features = false, features = ["ring", "std"] }
+
+[dev-dependencies]
+tower = { workspace = true }
diff --git a/crates/buzz-backend-kubernetes/src/classify.rs b/crates/buzz-backend-kubernetes/src/classify.rs
new file mode 100644
index 0000000000..e9cfaba402
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/classify.rs
@@ -0,0 +1,377 @@
+//! The deploy state machine (spec §Deploy State Machine), as a pure function.
+//!
+//! `classify` maps a verified observation plus the desired create intent to
+//! one [`Action`]. It performs no I/O, so every row of the spec's table is a
+//! unit test with no cluster. `reconcile` executes actions and re-enters.
+//!
+//! Two invariants are structural rather than remembered:
+//!
+//! * [`Action::Delete`] carries the [`Fence`] from the exact observation that
+//!   authorized it. There is no way to build a delete without one, so a later
+//!   helper cannot re-read and silently substitute a fresher fence.
+//! * The pull-failure classifier ([`PullFailure`]) reaches only
+//!   [`Action::Report`] and [`Action::Observe`]. It is absent from
+//!   `Action::Delete`'s type, so "reason strings are never deletion
+//!   authority" is enforced by the compiler.
+
+use crate::intent::Fingerprint;
+
+/// The compare-and-delete fence: UID + resourceVersion from the observation
+/// that authorized the deletion. A failed precondition means the object
+/// changed since the read — re-enter, never retry the delete.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Fence {
+    pub uid: String,
+    pub resource_version: String,
+}
+
+/// Why a pod that never started looks permanently broken. Reporting only.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PullFailure {
+    /// Registry auth: a 403/401 `ImagePullBackOff` retries forever without
+    /// ever succeeding, so "the pull retries" is false for this case.
+    Unauthorized,
+    /// The digest or repository does not exist at that registry.
+    ManifestUnknown,
+    /// The image has no variant for the node's architecture.
+    ArchMismatch,
+}
+
+/// The container's startup state, already decoded from pod status. Decoding
+/// happens at the edge so this module stays free of API types.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Startup {
+    /// `state.running` — the harness process is up. This, not pod phase, is
+    /// what "live" means.
+    Started,
+    /// Started once and reached a terminal phase (Succeeded/Failed).
+    Terminated,
+    /// Never started, and self-healing is plausible: unschedulable during
+    /// scale-from-zero, an image pull in progress, a transient
+    /// `CreateContainerConfigError` whose Secret exists.
+    NeverStartedRecoverable,
+    /// Never started, and the provider *verified* the cause — not a reason
+    /// string. Either the referenced Secret is confirmed absent by a
+    /// most-recent read, or the image reference is structurally invalid.
+    NeverStartedProvablyBroken,
+    /// Never started; the pull is failing in a way that will not self-heal.
+    /// Still recoverable in the *never delete* sense — this only changes what
+    /// we report and how long we wait.
+    NeverStartedPullFailing(PullFailure),
+}
+
+/// A pod that passed identity and ownership verification: label-selected,
+/// full-pubkey annotation equal to the derived pubkey, management marker
+/// present. Constructing this type is the verification step's output, so an
+/// unverified object cannot reach `classify` at all.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct VerifiedPod {
+    pub name: String,
+    pub fence: Fence,
+    /// Set once the apiserver accepts a delete. In Kubernetes there is no
+    /// `Terminating` phase — a pod being gracefully deleted stays in phase
+    /// `Running` for its whole grace period — so this must be checked
+    /// *before* startup state or the dying pod reads as the no-op row.
+    pub deletion_marked: bool,
+    pub startup: Startup,
+    /// The `buzz.block.xyz/create-intent` annotation as recorded at create.
+    /// `None` for a pod written before the annotation existed, which counts
+    /// as divergence.
+    pub recorded_intent: Option<Fingerprint>,
+}
+
+/// What the reconciler should do next.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Action {
+    /// Create the pod, then wait for the harness container to start.
+    Create,
+    /// Compare-and-delete, poll for actual disappearance, then re-enter.
+    Delete { name: String, fence: Fence },
+    /// Wait for a deletion already in flight, then re-enter.
+    AwaitDisappearance { name: String },
+    /// Strict no-op: return this `agent_id`, mutate nothing.
+    NoOp { agent_id: String },
+    /// Keep observing until started or the operation deadline expires; on
+    /// expiry report the latest condition. Never deletes, on this call or any
+    /// later one.
+    Observe { name: String },
+    /// Surface an actionable condition immediately rather than burning the
+    /// deadline on a failure that will not self-heal.
+    Report { name: String, failure: PullFailure },
+}
+
+/// Apply the spec's ordered rules to one verified observation.
+///
+/// `desired` is the freshly computed create intent; comparison is always
+/// recorded-annotation vs freshly-computed, never a diff against the live pod
+/// (admission defaulting would make every pod look divergent).
+pub fn classify(observed: Option<&VerifiedPod>, desired: &Fingerprint) -> Action {
+    let Some(pod) = observed else {
+        // Row: no instance → create. First deploy, or after GC.
+        return Action::Create;
+    };
+
+    // Row: deletion-marked, ANY phase. Checked before startup state because
+    // there is no `Terminating` phase to match on — a gracefully deleting pod
+    // reports phase `Running` throughout its grace period, so testing startup
+    // first would mistake it for the live no-op row and return an id that
+    // evaporates.
+    if pod.deletion_marked {
+        return Action::AwaitDisappearance {
+            name: pod.name.clone(),
+        };
+    }
+
+    match &pod.startup {
+        // Row: live and started → strict no-op. Start must never kill a live
+        // agent mid-turn, whatever the fingerprint says.
+        Startup::Started => Action::NoOp {
+            agent_id: pod.name.clone(),
+        },
+
+        // Row: terminated → delete residue, then re-enter to create. This is
+        // the normal restart path — how a user revives a reaped agent.
+        Startup::Terminated => Action::Delete {
+            name: pod.name.clone(),
+            fence: pod.fence.clone(),
+        },
+
+        // Row: never started, provably non-recoverable → fenced replace.
+        // "Provably" means a verified absence or a structural defect, never a
+        // reason string.
+        Startup::NeverStartedProvablyBroken => Action::Delete {
+            name: pod.name.clone(),
+            fence: pod.fence.clone(),
+        },
+
+        // Inside the recoverable row: a pull that will not self-heal is
+        // reported immediately instead of consuming the 600s deadline. This
+        // changes reporting and wait behavior only — no delete authority.
+        Startup::NeverStartedPullFailing(failure) => Action::Report {
+            name: pod.name.clone(),
+            failure: *failure,
+        },
+
+        // Row: never started, recoverable — split on create-intent
+        // divergence. Divergence is evidence of a config change the user is
+        // waiting on, and it is the *only* thing that replaces a
+        // never-started pod. Pod age triggers nothing: any finite age
+        // threshold collides with Cluster Autoscaler's own pod-age delays,
+        // and delete-recreate resets exactly the age it keys on.
+        Startup::NeverStartedRecoverable => {
+            if pod.recorded_intent.as_ref() == Some(desired) {
+                Action::Observe {
+                    name: pod.name.clone(),
+                }
+            } else {
+                Action::Delete {
+                    name: pod.name.clone(),
+                    fence: pod.fence.clone(),
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn fp(seed: &str) -> Fingerprint {
+        Fingerprint::for_test(seed)
+    }
+
+    fn pod(startup: Startup, intent: Option<Fingerprint>) -> VerifiedPod {
+        VerifiedPod {
+            name: "buzz-agent-abc123def456".into(),
+            fence: Fence {
+                uid: "uid-1".into(),
+                resource_version: "rv-1".into(),
+            },
+            deletion_marked: false,
+            startup,
+            recorded_intent: intent,
+        }
+    }
+
+    #[test]
+    fn no_instance_creates() {
+        assert_eq!(classify(None, &fp("a")), Action::Create);
+    }
+
+    #[test]
+    fn started_pod_is_strict_no_op() {
+        let p = pod(Startup::Started, Some(fp("a")));
+        assert_eq!(
+            classify(Some(&p), &fp("a")),
+            Action::NoOp {
+                agent_id: p.name.clone()
+            }
+        );
+    }
+
+    /// The asymmetry the spec states plainly: an edit cannot reach a started
+    /// pod until it exits, but it *can* reach a never-started one — the
+    /// never-started pod is the one the user is editing because it did not
+    /// start.
+    #[test]
+    fn started_pod_no_ops_even_when_intent_diverges() {
+        let p = pod(Startup::Started, Some(fp("old")));
+        assert_eq!(
+            classify(Some(&p), &fp("new")),
+            Action::NoOp {
+                agent_id: p.name.clone()
+            }
+        );
+    }
+
+    /// In Kubernetes a gracefully deleting pod stays in phase `Running`. If
+    /// the deletion mark were checked after startup state, this pod would
+    /// take the no-op row and `deploy` would return an id that evaporates.
+    #[test]
+    fn deletion_mark_beats_every_startup_state() {
+        for startup in [
+            Startup::Started,
+            Startup::Terminated,
+            Startup::NeverStartedRecoverable,
+            Startup::NeverStartedProvablyBroken,
+            Startup::NeverStartedPullFailing(PullFailure::Unauthorized),
+        ] {
+            let mut p = pod(startup.clone(), Some(fp("a")));
+            p.deletion_marked = true;
+            assert_eq!(
+                classify(Some(&p), &fp("a")),
+                Action::AwaitDisappearance {
+                    name: p.name.clone()
+                },
+                "deletion mark ignored for {startup:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn terminated_pod_is_replaced() {
+        let p = pod(Startup::Terminated, Some(fp("a")));
+        assert_eq!(
+            classify(Some(&p), &fp("a")),
+            Action::Delete {
+                name: p.name.clone(),
+                fence: p.fence.clone()
+            }
+        );
+    }
+
+    /// A never-started winner is repairable: pod exists, Secret confirmed
+    /// absent, container never started. A later deploy must delete-recreate
+    /// rather than no-op — the test that pins started-not-phase as the no-op
+    /// criterion.
+    #[test]
+    fn provably_broken_never_started_pod_is_replaced() {
+        let p = pod(Startup::NeverStartedProvablyBroken, Some(fp("a")));
+        assert_eq!(
+            classify(Some(&p), &fp("a")),
+            Action::Delete {
+                name: p.name.clone(),
+                fence: p.fence.clone()
+            }
+        );
+    }
+
+    /// The anti-livelock rule: identical desired intent means *never* delete,
+    /// however long the pod has been pending. Age is not an input to this
+    /// function at all, which is the strongest way to say so.
+    #[test]
+    fn recoverable_with_matching_intent_only_observes() {
+        let p = pod(Startup::NeverStartedRecoverable, Some(fp("same")));
+        assert_eq!(
+            classify(Some(&p), &fp("same")),
+            Action::Observe {
+                name: p.name.clone()
+            }
+        );
+    }
+
+    /// Repeated identical Starts can never delete anything — the same
+    /// classification, arbitrarily many times.
+    #[test]
+    fn repeated_identical_starts_never_delete() {
+        let p = pod(Startup::NeverStartedRecoverable, Some(fp("same")));
+        for _ in 0..100 {
+            assert!(!matches!(
+                classify(Some(&p), &fp("same")),
+                Action::Delete { .. }
+            ));
+        }
+    }
+
+    /// The wedge escape: the user corrected a resource request or image, so
+    /// the never-started pod is built from configuration they have since
+    /// changed. Without this row the edit could never materialize.
+    #[test]
+    fn recoverable_with_divergent_intent_is_replaced() {
+        let p = pod(Startup::NeverStartedRecoverable, Some(fp("old")));
+        assert_eq!(
+            classify(Some(&p), &fp("new")),
+            Action::Delete {
+                name: p.name.clone(),
+                fence: p.fence.clone()
+            }
+        );
+    }
+
+    /// A pod predating the annotation has no recorded intent — that is
+    /// absence, which the spec groups with divergence.
+    #[test]
+    fn missing_recorded_intent_counts_as_divergence() {
+        let p = pod(Startup::NeverStartedRecoverable, None);
+        assert_eq!(
+            classify(Some(&p), &fp("any")),
+            Action::Delete {
+                name: p.name.clone(),
+                fence: p.fence.clone()
+            }
+        );
+    }
+
+    /// Permanent-looking pull failures report immediately instead of burning
+    /// 600s — and, critically, never delete.
+    #[test]
+    fn pull_failures_report_and_never_delete() {
+        for failure in [
+            PullFailure::Unauthorized,
+            PullFailure::ManifestUnknown,
+            PullFailure::ArchMismatch,
+        ] {
+            let p = pod(Startup::NeverStartedPullFailing(failure), Some(fp("a")));
+            // Divergent intent too — still no delete from this arm.
+            for desired in [fp("a"), fp("different")] {
+                assert_eq!(
+                    classify(Some(&p), &desired),
+                    Action::Report {
+                        name: p.name.clone(),
+                        failure
+                    }
+                );
+            }
+        }
+    }
+
+    /// Every delete carries the fence from the observation that authorized
+    /// it. Exhaustive over the delete-producing states, so a future arm that
+    /// forgets is caught here rather than in a cluster.
+    #[test]
+    fn every_delete_carries_the_authorizing_fence() {
+        let states = [
+            (Startup::Terminated, fp("a")),
+            (Startup::NeverStartedProvablyBroken, fp("a")),
+            (Startup::NeverStartedRecoverable, fp("divergent")),
+        ];
+        for (startup, desired) in states {
+            let p = pod(startup, Some(fp("a")));
+            match classify(Some(&p), &desired) {
+                Action::Delete { fence, .. } => assert_eq!(fence, p.fence),
+                other => panic!("expected Delete, got {other:?}"),
+            }
+        }
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/client.rs b/crates/buzz-backend-kubernetes/src/client.rs
new file mode 100644
index 0000000000..0c3bed65b7
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/client.rs
@@ -0,0 +1,182 @@
+//! Cluster auth and client construction (spec §Cluster auth,
+//! `docs/remote-agents.md:985-995`).
+//!
+//! Standard kubeconfig resolution (`$KUBECONFIG` → `~/.kube/config`).
+//! `provider_config` carries `context` and `namespace` only — credentials
+//! never transit config (I2, `:196-198`).
+
+use kube::config::{ExecConfig, KubeConfigOptions, Kubeconfig};
+use kube::{Client, Config};
+use std::path::{Path, PathBuf};
+
+/// Directories prepended to `PATH` before the client is built.
+///
+/// Kubeconfigs at Block near-universally authenticate through `exec`
+/// credential plugins (`aws eks get-token`, `gke-gcloud-auth-plugin`) that
+/// resolve via `PATH` — and this provider inherits a Finder-launched
+/// desktop's minimal `PATH`, which contains none of the places those plugins
+/// install to (`:989-994`).
+const PATH_PREPEND: [&str; 2] = ["/opt/homebrew/bin", "/usr/local/bin"];
+
+/// Compute the new `PATH` value: plugin directories first, inherited entries
+/// after, in order. Pure so the ordering can be tested without mutating the
+/// process's environment.
+fn prepended_path(home: Option<&Path>, existing: &std::ffi::OsStr) -> Option<std::ffi::OsString> {
+    let mut dirs: Vec<PathBuf> = PATH_PREPEND.iter().map(PathBuf::from).collect();
+    if let Some(home) = home {
+        dirs.push(home.join(".local/bin"));
+    }
+    // An empty inherited PATH splits into one empty entry, which POSIX
+    // resolves as the current directory — a place a credential plugin should
+    // never be looked up. Drop empties rather than propagate them.
+    dirs.extend(std::env::split_paths(existing).filter(|p| !p.as_os_str().is_empty()));
+    std::env::join_paths(dirs).ok()
+}
+
+/// Prepend the plugin directories to this process's `PATH`.
+///
+/// Modifies the provider's own environment, which is sound here: one process
+/// per operation, called before any client or task exists, and the child
+/// processes that read it are exactly the credential plugins this exists for.
+fn prepend_plugin_path() {
+    let home = std::env::var_os("HOME");
+    let existing = std::env::var_os("PATH").unwrap_or_default();
+    if let Some(joined) = prepended_path(home.as_ref().map(Path::new), &existing) {
+        std::env::set_var("PATH", joined);
+    }
+}
+
+/// Is `command` runnable — an executable on `PATH`, or an existing path?
+fn resolves_on_path(command: &str) -> bool {
+    if command.contains(std::path::MAIN_SEPARATOR) {
+        return Path::new(command).is_file();
+    }
+    std::env::var_os("PATH")
+        .map(|path| std::env::split_paths(&path).any(|dir| dir.join(command).is_file()))
+        .unwrap_or(false)
+}
+
+/// The exec plugin the selected context authenticates with, if any.
+///
+/// Read from the kubeconfig directly rather than from `Config`, which does not
+/// expose it. A read failure yields `None`: this lookup exists only to improve
+/// an error message, and must never be the thing that fails a deploy.
+fn exec_plugin_for(context: Option<&str>) -> Option<ExecConfig> {
+    let kubeconfig = Kubeconfig::read().ok()?;
+    let context_name = context
+        .map(str::to_string)
+        .or_else(|| kubeconfig.current_context.clone())?;
+    let user_name = kubeconfig
+        .contexts
+        .iter()
+        .find(|c| c.name == context_name)
+        .and_then(|c| c.context.as_ref())
+        .and_then(|c| c.user.clone())?;
+    kubeconfig
+        .auth_infos
+        .iter()
+        .find(|a| a.name == user_name)
+        .and_then(|a| a.auth_info.as_ref())
+        .and_then(|a| a.exec.clone())
+}
+
+/// Turn a client-construction failure into an error a user can act on.
+///
+/// When the context authenticates through an exec plugin that is not on
+/// `PATH`, that is almost always the cause, and the actionable fact is the
+/// plugin's name — not a kube-rs error chain (`:994-995`).
+fn explain(context: Option<&str>, error: &kube::Error) -> String {
+    if let Some(command) = exec_plugin_for(context).and_then(|e| e.command) {
+        if !resolves_on_path(&command) {
+            return format!(
+                "kubeconfig context {} authenticates with the credential plugin \
+                 {command:?}, which is not on PATH. Install it or add its \
+                 directory to PATH, then try again.",
+                context.unwrap_or("(current)")
+            );
+        }
+    }
+    format!(
+        "could not connect to the cluster using kubeconfig context {}: {error}",
+        context.unwrap_or("(current)")
+    )
+}
+
+/// Build a client for the selected context.
+pub async fn connect(context: Option<&str>) -> Result<Client, String> {
+    prepend_plugin_path();
+
+    let options = KubeConfigOptions {
+        context: context.map(str::to_string),
+        ..Default::default()
+    };
+    let config = Config::from_kubeconfig(&options).await.map_err(|e| {
+        // A named context that does not exist is a user typo, and the
+        // kube-rs message for it is already specific.
+        format!(
+            "could not load kubeconfig for context {}: {e}",
+            context.unwrap_or("(current)")
+        )
+    })?;
+
+    Client::try_from(config).map_err(|e| explain(context, &e))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The three plugin directories must end up ahead of the inherited PATH,
+    /// or a Finder-launched desktop never finds `aws`/`gke-gcloud-auth-plugin`.
+    /// Tested on the pure computation: mutating the process PATH here would
+    /// race every other test in the binary.
+    #[test]
+    fn plugin_directories_are_prepended_in_order() {
+        let joined = prepended_path(
+            Some(Path::new("/tmp/fake-home")),
+            std::ffi::OsStr::new("/inherited/bin:/usr/bin"),
+        )
+        .unwrap();
+        let dirs: Vec<PathBuf> = std::env::split_paths(&joined).collect();
+        assert_eq!(
+            dirs,
+            [
+                "/opt/homebrew/bin",
+                "/usr/local/bin",
+                "/tmp/fake-home/.local/bin",
+                "/inherited/bin",
+                "/usr/bin",
+            ]
+            .map(PathBuf::from)
+        );
+    }
+
+    /// No `HOME` is not a failure — the two absolute directories still apply.
+    #[test]
+    fn missing_home_still_prepends_the_absolute_directories() {
+        let joined = prepended_path(None, std::ffi::OsStr::new("/inherited/bin")).unwrap();
+        let dirs: Vec<PathBuf> = std::env::split_paths(&joined).collect();
+        assert_eq!(
+            dirs,
+            ["/opt/homebrew/bin", "/usr/local/bin", "/inherited/bin"].map(PathBuf::from)
+        );
+    }
+
+    /// An empty inherited PATH must not produce an empty entry, which the
+    /// shell and `resolves_on_path` would both read as the cwd.
+    #[test]
+    fn empty_inherited_path_yields_no_empty_entry() {
+        let joined = prepended_path(None, std::ffi::OsStr::new("")).unwrap();
+        let dirs: Vec<PathBuf> = std::env::split_paths(&joined).collect();
+        assert_eq!(
+            dirs,
+            ["/opt/homebrew/bin", "/usr/local/bin"].map(PathBuf::from)
+        );
+    }
+
+    #[test]
+    fn resolves_absolute_paths_directly() {
+        assert!(resolves_on_path("/bin/sh"));
+        assert!(!resolves_on_path("/nonexistent/plugin-binary"));
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/cluster.rs b/crates/buzz-backend-kubernetes/src/cluster.rs
new file mode 100644
index 0000000000..755f41f6c8
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/cluster.rs
@@ -0,0 +1,427 @@
+//! The real [`Substrate`]: kube-rs against a live apiserver.
+//!
+//! Everything that *decides* lives in `classify`/`gc`; this module only
+//! performs I/O and maps apiserver responses onto the trait's vocabulary.
+//! Three mappings here are normative rather than incidental:
+//!
+//! * **409 is discriminated on `Status.reason`, never on the code.** A create
+//!   409 is `AlreadyExists`; a delete 409 from a failed precondition is
+//!   `Conflict`. Branching on `code == 409` conflates a lost create race with
+//!   a stale fence and is the trap the spec names (`:780-794`).
+//! * **Reads leave `resourceVersion` unset**, which is the quorum read. `"0"`
+//!   is the cache read, and a confirmed absence from a cache is proof of
+//!   nothing (`:761-769`).
+//! * **Deletes never set `grace_period_seconds`**, so the object's own 60s
+//!   budget applies. Passing `0` is a force-kill that discards the shutdown
+//!   window the pod declares (`:1185-1189`).
+
+use crate::classify::Fence;
+use crate::reconcile::{CreateOutcome, DeleteOutcome, Substrate};
+use chrono::{DateTime, Utc};
+use k8s_openapi::api::core::v1::{Namespace, Pod, Secret};
+use kube::api::{Api, DeleteParams, GetParams, ListParams, PostParams, Preconditions};
+use kube::core::ErrorResponse;
+use kube::{Client, Resource};
+use std::time::{Duration, Instant};
+
+/// `Status.reason` values we branch on. Spelled once so the two 409 arms are
+/// visibly the same discriminator read two ways.
+///
+/// These are wire strings `apimachinery` chooses, not names this crate picks:
+/// `StatusReasonAlreadyExists`, `StatusReasonConflict`, `StatusReasonNotFound`,
+/// and `StatusReasonForbidden` in `k8s.io/apimachinery/pkg/apis/meta/v1/types.go`.
+/// kube-core types `ErrorResponse::reason` as a bare `String`, so there is no
+/// upstream constant to bind to and the spelling is pinned by test instead.
+const REASON_ALREADY_EXISTS: &str = "AlreadyExists";
+const REASON_CONFLICT: &str = "Conflict";
+const REASON_NOT_FOUND: &str = "NotFound";
+const REASON_FORBIDDEN: &str = "Forbidden";
+
+/// The apiserver-backed substrate for one deploy operation.
+pub struct Cluster {
+    client: Client,
+    namespace: String,
+    /// Start of *this operation*, for the deadline. Monotonic: the 600s budget
+    /// must not move when the wall clock does.
+    started: Instant,
+}
+
+/// The typed API error underneath a `kube::Error`, if it is one.
+fn api_error(error: &kube::Error) -> Option<&ErrorResponse> {
+    match error {
+        kube::Error::Api(response) => Some(response),
+        _ => None,
+    }
+}
+
+/// Does this error carry the given `Status.reason`?
+fn reason_is(error: &kube::Error, reason: &str) -> bool {
+    api_error(error).is_some_and(|e| e.reason == reason)
+}
+
+impl Cluster {
+    pub fn new(client: Client, namespace: &str) -> Self {
+        Self {
+            client,
+            namespace: namespace.to_string(),
+            started: Instant::now(),
+        }
+    }
+
+    fn pods(&self) -> Api<Pod> {
+        Api::namespaced(self.client.clone(), &self.namespace)
+    }
+
+    fn secrets(&self) -> Api<Secret> {
+        Api::namespaced(self.client.clone(), &self.namespace)
+    }
+
+    /// List an object kind through the raw client so the response's HTTP
+    /// `Date` header is reachable.
+    ///
+    /// `Api::list` returns only the decoded body, and the apiserver's clock is
+    /// the *only* clock the orphan-Secret age gate may use — a desktop's local
+    /// clock running fast computes every in-flight Secret as expired
+    /// (`:1321-1335`). So the list goes through `Client::send`, which hands
+    /// back the whole `http::Response`.
+    async fn list_with_date<K>(
+        &self,
+        selector: &str,
+    ) -> Result<(Vec<K>, Option<DateTime<Utc>>), String>
+    where
+        K: Resource<Scope = k8s_openapi::NamespaceResourceScope>
+            + Clone
+            + serde::de::DeserializeOwned
+            + std::fmt::Debug,
+        K::DynamicType: Default,
+    {
+        let dt = K::DynamicType::default();
+        let url = K::url_path(&dt, Some(&self.namespace));
+        // resourceVersion deliberately unset: quorum read.
+        let params = ListParams {
+            label_selector: Some(selector.to_string()),
+            ..Default::default()
+        };
+        let request = kube::core::Request::new(url)
+            .list(&params)
+            .map_err(|e| format!("could not build a list request: {e}"))?;
+        let (parts, body) = request.into_parts();
+        let response = self
+            .client
+            .send(http::Request::from_parts(parts, body.into()))
+            .await
+            .map_err(|e| format!("could not list {}: {e}", K::plural(&dt)))?;
+
+        // Parsed before the body is consumed, and independently of it: a
+        // missing or malformed header is not a list failure, it just means the
+        // orphan sweep has no clock and skips.
+        let server_now = response
+            .headers()
+            .get(http::header::DATE)
+            .and_then(|v| v.to_str().ok())
+            .and_then(|v| DateTime::parse_from_rfc2822(v).ok())
+            .map(|v| v.with_timezone(&Utc));
+
+        let bytes = http_body_util::BodyExt::collect(response.into_body())
+            .await
+            .map_err(|e| format!("could not read the {} list body: {e}", K::plural(&dt)))?
+            .to_bytes();
+        let list: kube::core::ObjectList<K> = serde_json::from_slice(&bytes)
+            .map_err(|e| format!("could not decode the {} list: {e}", K::plural(&dt)))?;
+
+        Ok((list.items, server_now))
+    }
+}
+
+impl Substrate for Cluster {
+    async fn ensure_namespace(&self, namespace: &str) -> Result<(), String> {
+        let api: Api<Namespace> = Api::all(self.client.clone());
+        if api
+            .get_opt(namespace)
+            .await
+            .map_err(|e| format!("could not check whether namespace {namespace} exists: {e}"))?
+            .is_some()
+        {
+            return Ok(());
+        }
+
+        let spec = Namespace {
+            metadata: kube::core::ObjectMeta {
+                name: Some(namespace.to_string()),
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+        match api.create(&PostParams::default(), &spec).await {
+            Ok(_) => Ok(()),
+            // Someone else created it between our check and our create. That
+            // is the desired end state, not a failure.
+            Err(e) if reason_is(&e, REASON_ALREADY_EXISTS) => Ok(()),
+            // Namespace-create is frequently denied on shared clusters. Name
+            // the exact command an operator runs, and never silently fall back
+            // to `default` — deploying an agent into someone else's namespace
+            // is worse than refusing (`:1002-1005`).
+            Err(e) if reason_is(&e, REASON_FORBIDDEN) => Err(format!(
+                "not authorized to create namespace {namespace}. Ask a cluster \
+                 administrator to run `kubectl create namespace {namespace}`, \
+                 then try again."
+            )),
+            Err(e) => Err(format!("could not create namespace {namespace}: {e}")),
+        }
+    }
+
+    async fn list_pods(&self, selector: &str) -> Result<(Vec<Pod>, Option<DateTime<Utc>>), String> {
+        self.list_with_date::<Pod>(selector).await
+    }
+
+    async fn list_secrets(&self, selector: &str) -> Result<Vec<Secret>, String> {
+        Ok(self.list_with_date::<Secret>(selector).await?.0)
+    }
+
+    async fn secret_exists(&self, name: &str) -> Result<bool, String> {
+        // `GetParams::default()` leaves resourceVersion unset — the quorum
+        // read this check requires to be proof of anything.
+        match self.secrets().get_with(name, &GetParams::default()).await {
+            Ok(_) => Ok(true),
+            Err(e) if reason_is(&e, REASON_NOT_FOUND) => Ok(false),
+            Err(e) => Err(format!("could not check whether secret {name} exists: {e}")),
+        }
+    }
+
+    async fn create_secret(&self, secret: &Secret) -> Result<(), String> {
+        let name = secret.metadata.name.clone().unwrap_or_default();
+        self.secrets()
+            .create(&PostParams::default(), secret)
+            .await
+            .map(|_| ())
+            .map_err(|e| format!("could not create secret {name}: {e}"))
+    }
+
+    async fn create_pod(&self, pod: &Pod) -> Result<CreateOutcome, String> {
+        let name = pod.metadata.name.clone().unwrap_or_default();
+        match self.pods().create(&PostParams::default(), pod).await {
+            Ok(_) => Ok(CreateOutcome::Created),
+            // The deterministic name is taken: a concurrent attempt won the
+            // election. Discriminated on the reason — a 409 whose reason is
+            // `Conflict` is a different condition and must not be read as a
+            // lost race.
+            Err(e) if reason_is(&e, REASON_ALREADY_EXISTS) => Ok(CreateOutcome::AlreadyExists),
+            Err(e) => Err(format!("could not create pod {name}: {e}")),
+        }
+    }
+
+    async fn delete_pod(&self, name: &str, fence: &Fence) -> Result<DeleteOutcome, String> {
+        let params = DeleteParams {
+            preconditions: Some(Preconditions {
+                uid: Some(fence.uid.clone()),
+                resource_version: Some(fence.resource_version.clone()),
+            }),
+            // grace_period_seconds deliberately unset: the pod's own 60s
+            // budget applies.
+            ..Default::default()
+        };
+        match self.pods().delete(name, &params).await {
+            Ok(_) => Ok(DeleteOutcome::Accepted),
+            Err(e) if reason_is(&e, REASON_NOT_FOUND) => Ok(DeleteOutcome::NotFound),
+            // The object changed since the observation that authorized this
+            // delete. Same HTTP code as the create race above, different
+            // reason, different meaning.
+            Err(e) if reason_is(&e, REASON_CONFLICT) => Ok(DeleteOutcome::PreconditionFailed),
+            Err(e) => Err(format!("could not delete pod {name}: {e}")),
+        }
+    }
+
+    async fn delete_secret(&self, name: &str) -> Result<(), String> {
+        match self.secrets().delete(name, &DeleteParams::default()).await {
+            Ok(_) => Ok(()),
+            // Already gone is the desired end state.
+            Err(e) if reason_is(&e, REASON_NOT_FOUND) => Ok(()),
+            Err(e) => Err(format!("could not delete secret {name}: {e}")),
+        }
+    }
+
+    async fn get_pod(&self, name: &str) -> Result<Option<Pod>, String> {
+        match self.pods().get_with(name, &GetParams::default()).await {
+            Ok(pod) => Ok(Some(pod)),
+            Err(e) if reason_is(&e, REASON_NOT_FOUND) => Ok(None),
+            Err(e) => Err(format!("could not read pod {name}: {e}")),
+        }
+    }
+
+    async fn sleep(&self, duration: Duration) {
+        tokio::time::sleep(duration).await;
+    }
+
+    fn elapsed(&self) -> Duration {
+        self.started.elapsed()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use http::Response;
+    use kube::client::Body;
+    use std::sync::{Arc, Mutex};
+    use tower::service_fn;
+
+    fn list_response(date: Option<&str>) -> Response<Body> {
+        let mut response = Response::builder().status(200);
+        if let Some(date) = date {
+            response = response.header(http::header::DATE, date);
+        }
+        response
+            .body(Body::from(
+                serde_json::to_vec(&serde_json::json!({
+                    "apiVersion": "v1",
+                    "kind": "PodList",
+                    "metadata": {"resourceVersion": "17"},
+                    "items": [{
+                        "apiVersion": "v1",
+                        "kind": "Pod",
+                        "metadata": {"name": "sprig"},
+                        "spec": {"containers": [{"name": "agent", "image": "example.invalid/sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}]}
+                    }]
+                }))
+                .unwrap(),
+            ))
+            .unwrap()
+    }
+
+    async fn list_through_real_request_path(
+        date: Option<&'static str>,
+    ) -> (Vec<Pod>, Option<DateTime<Utc>>, String) {
+        let observed_uri = Arc::new(Mutex::new(None));
+        let service_uri = Arc::clone(&observed_uri);
+        let service = service_fn(move |request: http::Request<Body>| {
+            let service_uri = Arc::clone(&service_uri);
+            async move {
+                *service_uri.lock().unwrap() = Some(request.uri().to_string());
+                Ok::<_, std::convert::Infallible>(list_response(date))
+            }
+        });
+        let cluster = Cluster::new(Client::new(service, "ignored"), "owned-ns");
+        let result = cluster
+            .list_with_date::<Pod>("app.kubernetes.io/managed-by=buzz-backend-kubernetes")
+            .await
+            .unwrap();
+        let uri = observed_uri.lock().unwrap().take().unwrap();
+        (result.0, result.1, uri)
+    }
+
+    /// Exercise the shipped `Request` + `Client::send` seam. A fake
+    /// reconciler would not prove that kube-rs emits a quorum list request or
+    /// that the apiserver's clock survives body decoding.
+    #[tokio::test]
+    async fn list_with_date_uses_a_quorum_request_and_returns_the_server_clock() {
+        let (pods, server_now, uri) =
+            list_through_real_request_path(Some("Sun, 02 Aug 2026 04:00:00 GMT")).await;
+
+        assert_eq!(pods.len(), 1, "fixture must contain one decoded pod");
+        assert_eq!(pods[0].metadata.name.as_deref(), Some("sprig"));
+        assert!(uri.starts_with("/api/v1/namespaces/owned-ns/pods?"));
+        assert!(
+            uri.contains("labelSelector=app.kubernetes.io%2Fmanaged-by%3Dbuzz-backend-kubernetes")
+        );
+        assert!(
+            !uri.contains("resourceVersion"),
+            "cache read leaked into {uri}"
+        );
+        assert_eq!(
+            server_now.unwrap().to_rfc3339(),
+            "2026-08-02T04:00:00+00:00"
+        );
+    }
+
+    /// Header failure is deliberately not list failure: without a trustworthy
+    /// apiserver clock the orphan sweep skips, but normal reconciliation still
+    /// receives the decoded objects.
+    #[tokio::test]
+    async fn list_with_date_keeps_items_when_the_server_clock_is_unusable() {
+        for date in [Some("not a date"), None] {
+            let (pods, server_now, _) = list_through_real_request_path(date).await;
+            assert_eq!(pods.len(), 1, "fixture must contain one decoded pod");
+            assert!(server_now.is_none(), "unexpected clock for {date:?}");
+        }
+    }
+
+    /// A typed apiserver error, as kube-rs surfaces it.
+    fn api(reason: &str, code: u16) -> kube::Error {
+        kube::Error::Api(ErrorResponse {
+            status: "Failure".into(),
+            message: String::new(),
+            reason: reason.into(),
+            code,
+        })
+    }
+
+    /// The one discriminator the whole file rests on, and the trap the spec
+    /// predicts: "an implementation that branches on the code alone will
+    /// eventually take the adoption path on a failed delete or vice versa"
+    /// (`:788-790`).
+    ///
+    /// Both of these are 409. Reading the *code* makes them identical; reading
+    /// `Status.reason` keeps a lost create race and a stale fence apart. The
+    /// mutation that must fail this test is `e.reason == …` → `e.code == 409`,
+    /// which no other test in the crate would catch — the fakes never produce
+    /// a real `kube::Error`.
+    #[test]
+    fn the_two_409s_are_never_conflated() {
+        let already_exists = api(REASON_ALREADY_EXISTS, 409);
+        let conflict = api(REASON_CONFLICT, 409);
+
+        assert!(reason_is(&already_exists, REASON_ALREADY_EXISTS));
+        assert!(reason_is(&conflict, REASON_CONFLICT));
+        // The cross terms are the whole point.
+        assert!(!reason_is(&already_exists, REASON_CONFLICT));
+        assert!(!reason_is(&conflict, REASON_ALREADY_EXISTS));
+    }
+
+    /// A transport-level failure is not an apiserver verdict. It must fall
+    /// through to the error arm rather than being read as any reason — a
+    /// connection reset silently classified as `NotFound` would report a pod
+    /// as confirmed-absent, which the classifier treats as proof.
+    #[test]
+    fn a_non_api_error_carries_no_reason() {
+        let transport = kube::Error::LinesCodecMaxLineLengthExceeded;
+        assert!(api_error(&transport).is_none());
+        for reason in [
+            REASON_ALREADY_EXISTS,
+            REASON_CONFLICT,
+            REASON_NOT_FOUND,
+            REASON_FORBIDDEN,
+        ] {
+            assert!(!reason_is(&transport, reason), "matched {reason}");
+        }
+    }
+
+    /// `reason` is `#[serde(default)]` in kube-core, so an apiserver that
+    /// omits it yields an empty string. That must match nothing rather than
+    /// matching an empty pattern by accident.
+    #[test]
+    fn an_absent_reason_matches_nothing() {
+        let bare = api("", 409);
+        assert!(!reason_is(&bare, REASON_ALREADY_EXISTS));
+        assert!(!reason_is(&bare, REASON_CONFLICT));
+    }
+
+    /// The consts are the apiserver's spelling, asserted against literals
+    /// rather than against themselves.
+    ///
+    /// Every other test here references the consts symbolically on both sides
+    /// — fixture *and* assertion — which is true for any pair of distinct
+    /// values. That tests the discriminator is self-consistent, not that it is
+    /// correct: swapping the two 409 values inverts `AlreadyExists` and
+    /// `Conflict` at a real apiserver (`:788-790`'s failure, reached by
+    /// editing a string instead of a branch) with every other test still
+    /// green. These are `apimachinery`'s wire strings and kube-core exposes no
+    /// constant for them, so a literal is the only external anchor available.
+    /// Found by Quinn's mutation matrix; M2/M3/M4 survived without it.
+    #[test]
+    fn the_reason_consts_are_the_apiservers_spelling() {
+        assert_eq!(REASON_ALREADY_EXISTS, "AlreadyExists");
+        assert_eq!(REASON_CONFLICT, "Conflict");
+        assert_eq!(REASON_NOT_FOUND, "NotFound");
+        assert_eq!(REASON_FORBIDDEN, "Forbidden");
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/config.rs b/crates/buzz-backend-kubernetes/src/config.rs
new file mode 100644
index 0000000000..4d96735b7b
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/config.rs
@@ -0,0 +1,470 @@
+//! `provider_config` parsing and the `info` config schema
+//! (spec §`provider_config` v1 fields, `docs/remote-agents.md:1384-1389`).
+//!
+//! Nine fields, all optional except `image` (required at parse time; the
+//! schema offers the published sprig image as a prefill default — §Image).
+//! No credential field exists, by I2: cluster auth comes from ambient
+//! kubeconfig resolution and nothing else (`:196-198`).
+
+use crate::image::{self, ImageRef};
+
+/// Resource requests and limits (§Pod shape: 1cpu/2Gi → 2cpu/4Gi, all four
+/// configurable — `cargo build` in an agent workspace makes 500m/1Gi
+/// unrealistic).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Resources {
+    pub cpu_request: String,
+    pub memory_request: String,
+    pub cpu_limit: String,
+    pub memory_limit: String,
+}
+
+impl Default for Resources {
+    fn default() -> Self {
+        Self {
+            cpu_request: "1".into(),
+            memory_request: "2Gi".into(),
+            cpu_limit: "2".into(),
+            memory_limit: "4Gi".into(),
+        }
+    }
+}
+
+/// Default inactivity budget: the I5 opt-in (§Auto-Stop). The config field and
+/// `BUZZ_ACP_EXIT_AFTER_INACTIVITY` are one knob, not two.
+pub const DEFAULT_INACTIVITY_SECONDS: u64 = 7200;
+
+/// Default `image` schema prefill: the published sprig image, in tag+digest
+/// form so the tag stays human-traceable to its git SHA while the digest does
+/// the pinning (§Image — tag-only refs are rejected; `image::parse` drops the
+/// tag on normalization). This is a UI prefill, not a baked fallback: `image`
+/// stays required, an empty value still fails closed, and the value always
+/// arrives explicitly in `provider_config`, so create-intent fingerprints are
+/// unaffected by provider upgrades.
+pub const DEFAULT_IMAGE: &str = "ghcr.io/block/buzz-sprig:sha-6530b58@sha256:17facfc7608d8ddb33bc056c9aaba1098f4ef6abe5655702fbfd7584d1f74d76";
+
+/// Fixed nonzero UID/GID for the agent container (§Pod shape hardening).
+pub const RUN_AS_UID: i64 = 10001;
+pub const RUN_AS_GID: i64 = 10001;
+
+/// Writable workspace root; also `HOME` and the harness's cwd
+/// (§Working directory).
+pub const WORKSPACE_PATH: &str = "/home/agent";
+
+/// `terminationGracePeriodSeconds` — a declared budget, not a derived sum
+/// (§Pod shape). Kubernetes' default 30s would SIGKILL the harness mid-drain.
+pub const TERMINATION_GRACE_SECONDS: i64 = 60;
+
+/// The only restart policy v1 ships. `OnFailure` is double-gated on the
+/// harness exit-code contract *and* a crash-loop classification row the state
+/// machine does not have (`:1121-1139`); until both land the provider refuses
+/// the combination rather than shipping against an undefended convention.
+pub const RESTART_POLICY: &str = "Never";
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderConfig {
+    /// kubeconfig context; `None` uses the current context.
+    pub context: Option<String>,
+    pub namespace: String,
+    pub image: ImageRef,
+    pub resources: Resources,
+    /// `None` when `inactivity_seconds` was 0 — refused in v1, see [`parse`].
+    pub inactivity_seconds: Option<u64>,
+    pub service_account: Option<String>,
+}
+
+/// Read an optional non-empty string field. Rejects non-string scalars rather
+/// than stringifying them, so a mistyped field is named at the boundary.
+fn optional_string(cfg: &serde_json::Value, field: &str) -> Result<Option<String>, String> {
+    match cfg.get(field) {
+        None | Some(serde_json::Value::Null) => Ok(None),
+        Some(serde_json::Value::String(s)) if s.trim().is_empty() => Ok(None),
+        Some(serde_json::Value::String(s)) => Ok(Some(s.trim().to_string())),
+        Some(other) => Err(format!(
+            "provider_config.{field} must be a string, got {other}"
+        )),
+    }
+}
+
+/// Read an optional unsigned integer. The desktop's form omits blank numeric
+/// fields rather than sending `""`, but a hand-crafted payload may send a
+/// numeric string — accept both, refuse anything else.
+fn optional_u64(cfg: &serde_json::Value, field: &str) -> Result<Option<u64>, String> {
+    match cfg.get(field) {
+        None | Some(serde_json::Value::Null) => Ok(None),
+        Some(serde_json::Value::Number(n)) => n.as_u64().map(Some).ok_or_else(|| {
+            format!("provider_config.{field} must be a non-negative integer, got {n}")
+        }),
+        Some(serde_json::Value::String(s)) if s.trim().is_empty() => Ok(None),
+        Some(serde_json::Value::String(s)) => s.trim().parse::<u64>().map(Some).map_err(|_| {
+            format!("provider_config.{field} must be a non-negative integer, got {s:?}")
+        }),
+        Some(other) => Err(format!(
+            "provider_config.{field} must be a non-negative integer, got {other}"
+        )),
+    }
+}
+
+/// A Kubernetes namespace name: RFC 1123 label, ≤63 chars. Validated here so a
+/// typo fails with a named field instead of an apiserver rejection partway
+/// through a deploy.
+fn valid_namespace(name: &str) -> bool {
+    !name.is_empty()
+        && name.len() <= 63
+        && name.starts_with(|c: char| c.is_ascii_lowercase() || c.is_ascii_digit())
+        && name.ends_with(|c: char| c.is_ascii_lowercase() || c.is_ascii_digit())
+        && name
+            .chars()
+            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')
+}
+
+pub fn parse(cfg: &serde_json::Value) -> Result<ProviderConfig, String> {
+    if !cfg.is_object() && !cfg.is_null() {
+        return Err("provider_config must be a JSON object".to_string());
+    }
+
+    let namespace = optional_string(cfg, "namespace")?.ok_or_else(|| {
+        "provider_config.namespace is required: the info schema supplies a \
+         generated default, so an empty value means the form was cleared"
+            .to_string()
+    })?;
+    if !valid_namespace(&namespace) {
+        return Err(format!(
+            "provider_config.namespace {namespace:?} is not a valid Kubernetes \
+             namespace (lowercase alphanumerics and '-', ≤63 characters)"
+        ));
+    }
+
+    let image = image::parse(optional_string(cfg, "image")?.unwrap_or_default().as_str())?;
+
+    let defaults = Resources::default();
+    let resources = Resources {
+        cpu_request: optional_string(cfg, "cpu_request")?.unwrap_or(defaults.cpu_request),
+        memory_request: optional_string(cfg, "memory_request")?.unwrap_or(defaults.memory_request),
+        cpu_limit: optional_string(cfg, "cpu_limit")?.unwrap_or(defaults.cpu_limit),
+        memory_limit: optional_string(cfg, "memory_limit")?.unwrap_or(defaults.memory_limit),
+    };
+
+    // `inactivity_seconds: 0` is a legal, blessed value in the spec (§Auto-Stop)
+    // meaning "no auto-stop" — but it selects `restartPolicy: OnFailure`, which
+    // §Pod shape forbids until the harness exit-code contract is pinned AND the
+    // state machine gains a crash-loop row. Refusing the *combination* is what
+    // the spec asks for; silently downgrading to `Never` would ship an
+    // indefinite agent that dies on its first crash.
+    let inactivity_seconds = match optional_u64(cfg, "inactivity_seconds")? {
+        None => Some(DEFAULT_INACTIVITY_SECONDS),
+        Some(0) => {
+            return Err(
+                "provider_config.inactivity_seconds: 0 (indefinite lifetime) is not \
+                 supported in this version: it requires restartPolicy OnFailure, \
+                 which is gated on the harness exit-code contract. Set a positive \
+                 number of seconds."
+                    .to_string(),
+            )
+        }
+        Some(n) => Some(n),
+    };
+
+    Ok(ProviderConfig {
+        context: optional_string(cfg, "context")?,
+        namespace,
+        image,
+        resources,
+        inactivity_seconds,
+        service_account: optional_string(cfg, "service_account")?,
+    })
+}
+
+/// A fresh `buzz-agents-<rand6>` namespace default.
+///
+/// Computed per `info` call, which is how "random default" is satisfied with
+/// zero UI changes: the schema's `default` prefills the form (§K8s Namespace).
+pub fn generated_namespace() -> String {
+    use rand::RngExt;
+    const ALPHABET: &[u8] = b"abcdefghijklmnopqrstuvwxyz0123456789";
+    let mut rng = rand::rng();
+    let suffix: String = (0..6)
+        .map(|_| ALPHABET[rng.random_range(0..ALPHABET.len())] as char)
+        .collect();
+    format!("buzz-agents-{suffix}")
+}
+
+/// The `config_schema` returned by `info`. Drives the UI form:
+/// `properties[*].default` prefill, scalar coercion, `required` gating
+/// (`:407-411`).
+pub fn config_schema() -> serde_json::Value {
+    let defaults = Resources::default();
+    serde_json::json!({
+        "type": "object",
+        "properties": {
+            "context": {
+                "type": "string",
+                "title": "Kubeconfig context",
+                "description": "Context from your kubeconfig. Leave empty to use the current context."
+            },
+            "namespace": {
+                "type": "string",
+                "title": "Namespace",
+                "description": "Created if it does not exist.",
+                "default": generated_namespace()
+            },
+            "image": {
+                "type": "string",
+                "title": "Agent image",
+                "description": "Digest-pinned image containing the buzz-acp runtime ABI, e.g. ghcr.io/block/buzz-sprig@sha256:<digest>. Tags alone are not accepted: this pod holds the agent's private key.",
+                "default": DEFAULT_IMAGE
+            },
+            "cpu_request": {
+                "type": "string", "title": "CPU request", "default": defaults.cpu_request
+            },
+            "memory_request": {
+                "type": "string", "title": "Memory request", "default": defaults.memory_request
+            },
+            "cpu_limit": {
+                "type": "string", "title": "CPU limit", "default": defaults.cpu_limit
+            },
+            "memory_limit": {
+                "type": "string", "title": "Memory limit", "default": defaults.memory_limit
+            },
+            "inactivity_seconds": {
+                "type": "number",
+                "title": "Stop after inactivity (seconds)",
+                "description": "The agent exits after this long with no work, and can be started again at any time.",
+                "default": DEFAULT_INACTIVITY_SECONDS
+            },
+            "service_account": {
+                "type": "string",
+                "title": "Service account",
+                "description": "Scheduling/RBAC identity only. No API token is mounted."
+            }
+        },
+        "required": ["namespace", "image"]
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn digest_ref() -> String {
+        format!("ghcr.io/block/buzz-sprig@sha256:{}", "a".repeat(64))
+    }
+
+    fn minimal() -> serde_json::Value {
+        serde_json::json!({"namespace": "buzz-agents-abc123", "image": digest_ref()})
+    }
+
+    #[test]
+    fn applies_spec_defaults() {
+        let c = parse(&minimal()).unwrap();
+        assert_eq!(c.resources, Resources::default());
+        assert_eq!(c.resources.cpu_request, "1");
+        assert_eq!(c.resources.memory_request, "2Gi");
+        assert_eq!(c.resources.cpu_limit, "2");
+        assert_eq!(c.resources.memory_limit, "4Gi");
+        assert_eq!(c.inactivity_seconds, Some(DEFAULT_INACTIVITY_SECONDS));
+        assert_eq!(c.context, None);
+        assert_eq!(c.service_account, None);
+    }
+
+    #[test]
+    fn all_four_resources_are_configurable() {
+        let mut cfg = minimal();
+        cfg["cpu_request"] = "500m".into();
+        cfg["memory_request"] = "1Gi".into();
+        cfg["cpu_limit"] = "4".into();
+        cfg["memory_limit"] = "8Gi".into();
+        let c = parse(&cfg).unwrap();
+        assert_eq!(
+            c.resources,
+            Resources {
+                cpu_request: "500m".into(),
+                memory_request: "1Gi".into(),
+                cpu_limit: "4".into(),
+                memory_limit: "8Gi".into(),
+            }
+        );
+    }
+
+    /// The desktop's form omits blank numeric fields; a hand-crafted payload
+    /// may send a numeric string. Both must mean the same thing.
+    #[test]
+    fn inactivity_accepts_number_string_and_omission() {
+        let mut cfg = minimal();
+        cfg["inactivity_seconds"] = serde_json::json!(300);
+        assert_eq!(parse(&cfg).unwrap().inactivity_seconds, Some(300));
+
+        cfg["inactivity_seconds"] = serde_json::json!("300");
+        assert_eq!(parse(&cfg).unwrap().inactivity_seconds, Some(300));
+
+        cfg["inactivity_seconds"] = serde_json::json!("");
+        assert_eq!(
+            parse(&cfg).unwrap().inactivity_seconds,
+            Some(DEFAULT_INACTIVITY_SECONDS)
+        );
+    }
+
+    /// Indefinite lifetime selects `OnFailure`, which is gated. Refuse rather
+    /// than silently downgrade — a downgraded agent dies on its first crash
+    /// while the user believes they asked for indefinite.
+    #[test]
+    fn refuses_indefinite_lifetime() {
+        let mut cfg = minimal();
+        cfg["inactivity_seconds"] = serde_json::json!(0);
+        let err = parse(&cfg).unwrap_err();
+        assert!(err.contains("inactivity_seconds"), "got: {err}");
+        assert!(
+            err.contains("OnFailure"),
+            "error should name the gate: {err}"
+        );
+    }
+
+    #[test]
+    fn rejects_negative_and_non_numeric_inactivity() {
+        for bad in [
+            serde_json::json!(-1),
+            serde_json::json!(1.5),
+            serde_json::json!("soon"),
+            serde_json::json!(true),
+        ] {
+            let mut cfg = minimal();
+            cfg["inactivity_seconds"] = bad.clone();
+            assert!(parse(&cfg).is_err(), "accepted {bad}");
+        }
+    }
+
+    #[test]
+    fn image_is_required_and_must_be_digest_pinned() {
+        let mut cfg = minimal();
+        cfg.as_object_mut().unwrap().remove("image");
+        assert!(parse(&cfg).unwrap_err().contains("provider_config.image"));
+
+        cfg["image"] = "ghcr.io/block/buzz-sprig:latest".into();
+        assert!(parse(&cfg).unwrap_err().contains("digest-pinned"));
+    }
+
+    #[test]
+    fn rejects_invalid_namespace_names() {
+        for bad in [
+            "",
+            "Buzz-Agents",
+            "-leading",
+            "trailing-",
+            "has_underscore",
+            &"n".repeat(64),
+        ] {
+            let mut cfg = minimal();
+            cfg["namespace"] = bad.into();
+            assert!(parse(&cfg).is_err(), "accepted namespace {bad:?}");
+        }
+    }
+
+    /// I2 corollary: there is no config path for cluster credentials, so a
+    /// caller that tries to supply one gets no effect from it. Asserting the
+    /// parsed struct has no such field is the closest a test can get to
+    /// "the type makes it impossible".
+    #[test]
+    fn credential_fields_have_no_effect() {
+        let mut cfg = minimal();
+        cfg["token"] = "hunter2".into();
+        cfg["client_key"] = "hunter2".into();
+        let c = parse(&cfg).unwrap();
+        let rendered = format!("{c:?}");
+        assert!(
+            !rendered.contains("hunter2"),
+            "config absorbed a credential: {rendered}"
+        );
+    }
+
+    #[test]
+    fn mistyped_string_fields_are_named() {
+        let mut cfg = minimal();
+        cfg["namespace"] = serde_json::json!(42);
+        assert!(parse(&cfg)
+            .unwrap_err()
+            .contains("provider_config.namespace"));
+    }
+
+    #[test]
+    fn generated_namespaces_are_fresh_and_valid() {
+        let a = generated_namespace();
+        let b = generated_namespace();
+        assert_ne!(a, b, "namespace default is not random");
+        assert!(valid_namespace(&a), "{a} is not a valid namespace");
+        assert!(a.starts_with("buzz-agents-"));
+        assert_eq!(a.len(), "buzz-agents-".len() + 6);
+    }
+
+    /// The schema's own namespace default must be a value the parser accepts —
+    /// otherwise the UI prefills a form that fails on submit.
+    #[test]
+    fn schema_default_namespace_round_trips_through_parse() {
+        let schema = config_schema();
+        let default = schema["properties"]["namespace"]["default"]
+            .as_str()
+            .unwrap();
+        let cfg = serde_json::json!({"namespace": default, "image": digest_ref()});
+        assert_eq!(parse(&cfg).unwrap().namespace, default);
+    }
+
+    /// Same guarantee for the image prefill: the schema's default must be a
+    /// value `image::parse` accepts, or the UI prefills a form that fails on
+    /// submit. Its tag+digest form normalizes to the tagless canonical form.
+    #[test]
+    fn schema_default_image_round_trips_through_parse() {
+        let schema = config_schema();
+        let default = schema["properties"]["image"]["default"].as_str().unwrap();
+        assert_eq!(default, DEFAULT_IMAGE);
+        let cfg = serde_json::json!({"namespace": "buzz-agents-abc123", "image": default});
+        let parsed = parse(&cfg).unwrap();
+        assert_eq!(
+            parsed.image.as_str(),
+            "ghcr.io/block/buzz-sprig@sha256:17facfc7608d8ddb33bc056c9aaba1098f4ef6abe5655702fbfd7584d1f74d76"
+        );
+    }
+
+    /// Nine fields exactly (§`provider_config` v1 fields). The cap is 20; the
+    /// count is pinned so a field added without a spec change is caught here.
+    #[test]
+    fn schema_declares_exactly_the_nine_v1_fields() {
+        let schema = config_schema();
+        let props = schema["properties"].as_object().unwrap();
+        let mut keys: Vec<&str> = props.keys().map(String::as_str).collect();
+        keys.sort();
+        assert_eq!(
+            keys,
+            [
+                "context",
+                "cpu_limit",
+                "cpu_request",
+                "image",
+                "inactivity_seconds",
+                "memory_limit",
+                "memory_request",
+                "namespace",
+                "service_account"
+            ]
+        );
+        assert_eq!(
+            schema["required"],
+            serde_json::json!(["namespace", "image"])
+        );
+    }
+
+    /// I2's key lint rejects any field whose word-split contains
+    /// secret|password|token|key|credential. A schema field tripping it would
+    /// make every deploy fail validation desktop-side (`:185-198`).
+    #[test]
+    fn no_schema_field_trips_the_i2_key_lint() {
+        const BANNED: [&str; 5] = ["secret", "password", "token", "key", "credential"];
+        let schema = config_schema();
+        for field in schema["properties"].as_object().unwrap().keys() {
+            for word in field.split(['_', '-']) {
+                assert!(
+                    !BANNED.contains(&word),
+                    "field {field:?} contains I2-banned word {word:?}"
+                );
+            }
+        }
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/env.rs b/crates/buzz-backend-kubernetes/src/env.rs
new file mode 100644
index 0000000000..badff621e8
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/env.rs
@@ -0,0 +1,732 @@
+//! Building the pod environment (spec §Launch data, §Entrypoint mapping table).
+//!
+//! The three tiers are resolved *here*, before serialization, because a
+//! Kubernetes Secret's `data` is a flat map with no precedence of its own: if
+//! two tiers supplied the same key, whichever entry landed in the map would
+//! win silently. Resolving in-provider makes later-wins explicit and testable.
+
+use crate::wire::{AgentPayload, LaunchBlock};
+use std::collections::BTreeMap;
+
+/// Keys the authoritative tier owns.
+///
+/// Load-bearing, not documentation: tier 3 *clears* every key on this list
+/// before writing its own values, so a key the authoritative tier has no value
+/// for is **removed** rather than left holding a lower-tier value. Plain
+/// overwrite is not enough — most of these are written conditionally
+/// (`BUZZ_ACP_AGENT_ARGS` only when `launch.args` is non-empty,
+/// `BUZZ_ACP_RESPOND_TO` only when set), and without the clear, a lower tier
+/// could supply the value for exactly the cases the authoritative tier stays
+/// silent on. Clearing is also what the local spawn does: the desktop strips
+/// reserved keys from user env before the authoritative layer is written
+/// (`env_vars.rs:54-57`), so absent-means-absent in both paths.
+const AUTHORITATIVE_KEYS: &[&str] = &[
+    "BUZZ_RELAY_URL",
+    "BUZZ_PRIVATE_KEY",
+    "NOSTR_PRIVATE_KEY",
+    "BUZZ_AUTH_TAG",
+    "BUZZ_ACP_AGENT_OWNER",
+    "BUZZ_ACP_AGENT_COMMAND",
+    "BUZZ_ACP_AGENT_ARGS",
+    "BUZZ_ACP_RESPOND_TO",
+    "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
+    "BUZZ_ACP_MCP_COMMAND",
+    "BUZZ_ACP_EXIT_AFTER_INACTIVITY",
+    START_NONCE_KEY,
+];
+
+/// The attempt's generation, as the harness sees it. Also the Secret's name
+/// suffix — one generation, one identity — so the reconciler restamps this on
+/// every create attempt rather than letting the caller's value persist across
+/// a retry.
+pub const START_NONCE_KEY: &str = "BUZZ_MANAGED_AGENT_START_NONCE";
+
+/// Presence is the only remote liveness signal (I3), so a launch that
+/// suppresses it is non-conforming (L1 item 2) — and unlike a reserved-key
+/// collision, there is no "authoritative value" to overwrite it with. Refuse.
+const FORBIDDEN_KEY: &str = "BUZZ_ACP_NO_PRESENCE";
+
+/// Kubernetes' own cap on the summed value bytes of a Secret
+/// (`MaxSecretSize`, `pkg/apis/core/types.go`). Enforced here so an oversized
+/// env surfaces as a named provider error rather than an apiserver rejection
+/// partway through a deploy.
+const MAX_SECRET_BYTES: usize = 1024 * 1024;
+
+/// A POSIX-shaped env var name: `[A-Za-z_][A-Za-z0-9_]*`.
+///
+/// Kubernetes validates Secret *keys* as `IsConfigMapKey`
+/// (`[-._a-zA-Z0-9]+`), which is looser — `foo.bar` is a legal Secret key.
+/// What the kubelet then does with such a key **changed between versions**:
+/// through 1.29 it filtered invalid env names out of `envFrom` and emitted an
+/// `InvalidEnvironmentVariableNames` warning event
+/// (`pkg/kubelet/kubelet_pods.go:646,654` at v1.29.0); from 1.30 that filter
+/// is gone (KEP-4369) and the key is injected verbatim. The same manifest
+/// would silently drop a variable on one cluster and set it on another, so we
+/// fail closed on the provider side and get one deterministic behavior.
+fn is_posix_env_key(key: &str) -> bool {
+    let mut chars = key.chars();
+    match chars.next() {
+        Some(c) if c == '_' || c.is_ascii_alphabetic() => {}
+        _ => return false,
+    }
+    chars.all(|c| c == '_' || c.is_ascii_alphanumeric())
+}
+
+/// An identity component (L1 item 1) is present only if it is nonempty after
+/// trimming — and the **trimmed form is what gets stored**. The validator and
+/// the writer must never disagree about the value: a guard that accepts
+/// `"  wss://relay  "` and then writes it with the padding intact has only
+/// moved the failure from a loud refusal to a connect error in the harness.
+fn identity_component(value: &str) -> Option<&str> {
+    let trimmed = value.trim();
+    (!trimmed.is_empty()).then_some(trimmed)
+}
+
+/// The harness's `allowlist` gate mode, spelled as the desktop serializes
+/// `RespondTo` (kebab-case) and as `buzz-acp`'s CLI parses it.
+const RESPOND_TO_ALLOWLIST: &str = "allowlist";
+
+/// Every gate mode `buzz-acp` accepts, spelled as its `clap::ValueEnum` parses
+/// them (`config.rs:95-101`, kebab-case via `RespondTo`'s `Display`).
+///
+/// Deliberately the **harness's** four and not the desktop's three: the desktop
+/// rejects `nobody` on purpose (`managed_agents/types.rs:871-880`), but the
+/// harness starts fine with it. This guard exists to cover non-desktop callers,
+/// so inheriting a desktop-only narrowing would refuse a launch that works.
+const RESPOND_TO_MODES: [&str; 4] = ["owner-only", RESPOND_TO_ALLOWLIST, "anyone", "nobody"];
+
+/// Refuse a respond-to gate the harness will reject at config parse.
+///
+/// The local spawn path re-validates this before spawning — "doing it here
+/// means we never spawn a doomed process" (`runtime.rs:378`) — but the deploy
+/// path projects the record's fields straight through. Without this, a gate
+/// the harness refuses becomes a pod that exits 1 at startup; `restartPolicy:
+/// Never` turns that into `Terminated` → `Delete` → recreate, and each cycle
+/// leaves a Secret the in-call path never reaps (only a later deploy's orphan
+/// sweep does, at `ORPHAN_SECRET_MIN_AGE_SECS`). The user-visible ending is
+/// "startup not confirmed", indistinguishable from a slow cluster.
+///
+/// Mirrors `buzz-acp`'s own rules exactly (`config.rs:95-101,996-1004,629-641`),
+/// deliberately including their asymmetry: the allowlist is validated **only**
+/// in allowlist mode, and merely warned about otherwise. Validating it in
+/// every mode would refuse a deploy whose identical local spawn succeeds —
+/// and a stale list is already harmless here, since
+/// `BUZZ_ACP_RESPOND_TO_ALLOWLIST` is an authoritative key that tier 3 clears.
+fn validate_respond_to_gate(respond_to: &str, allowlist: Option<&[String]>) -> Result<(), String> {
+    // Exact, untrimmed: `clap` does not trim, so `" allowlist "` is `rc=2` at
+    // the harness — a parse failure even earlier than the config errors below.
+    if !RESPOND_TO_MODES.contains(&respond_to) {
+        return Err(format!(
+            "deploy refused: respond_to {respond_to:?} is not a mode the \
+             harness accepts (expected one of {}) — the pod would fail to \
+             parse its arguments, be replaced, and leave a Secret behind on \
+             every attempt",
+            RESPOND_TO_MODES.join(", ")
+        ));
+    }
+    if respond_to != RESPOND_TO_ALLOWLIST {
+        return Ok(());
+    }
+    let entries = allowlist.unwrap_or_default();
+    if entries.is_empty() {
+        return Err(format!(
+            "deploy refused: respond_to is {RESPOND_TO_ALLOWLIST:?} but the \
+             allowlist is empty — the harness refuses this at startup, so the \
+             pod would fail, be replaced, and leave a Secret behind on every \
+             attempt"
+        ));
+    }
+    for entry in entries {
+        let trimmed = entry.trim();
+        if trimmed.len() != 64 || !trimmed.chars().all(|c| c.is_ascii_hexdigit()) {
+            return Err(format!(
+                "deploy refused: invalid pubkey in respond_to_allowlist: \
+                 {entry:?} (must be exactly 64 hex characters)"
+            ));
+        }
+    }
+    Ok(())
+}
+
+/// Inputs the provider itself supplies to the authoritative tier.
+pub struct AuthoritativeInputs<'a> {
+    /// The attempt's generation token — also the Secret's name suffix, so the
+    /// lifecycle correlator and the Secret generation are one identity.
+    pub generation: &'a str,
+    /// Resolved from `provider_config.inactivity_seconds`; `None` when the
+    /// indefinite opt-in was chosen (which this version refuses elsewhere).
+    pub inactivity_seconds: Option<u64>,
+}
+
+/// Resolve the full pod environment.
+///
+/// Order is the spec's, and the function body is deliberately three writes in
+/// that order — tier 1, tier 2, tier 3 — so "later wins" is visible rather
+/// than argued.
+pub fn build_env(
+    agent: &AgentPayload,
+    auth: AuthoritativeInputs<'_>,
+) -> Result<BTreeMap<String, String>, String> {
+    let default_launch = LaunchBlock::default();
+    let launch = agent.launch.as_ref().unwrap_or(&default_launch);
+
+    let mut env: BTreeMap<String, String> = BTreeMap::new();
+
+    // Tier 1 — overridable behavior defaults.
+    env.extend(launch.policy_env.clone());
+
+    // Tier 2 — user/layered env. The descriptor already merged
+    // global < persona < agent, so `agent.env_vars` is NOT re-merged on top
+    // (§Launch data tier 2) — doing so would resurrect a layer the desktop
+    // already resolved. When the desktop predates the `launch` block we fall
+    // back to the legacy field, which is the only case it is the truth.
+    if agent.launch.is_some() {
+        env.extend(launch.env.clone());
+    } else {
+        env.extend(agent.env_vars.clone());
+    }
+
+    // Validate what the lower tiers contributed, before the authoritative
+    // tier overwrites any of it. A reserved-key collision is NOT fatal: the
+    // spec's precedence is later-wins, so tier 3 simply overwrites it, which
+    // is exactly what a local spawn does. Only a key that has no
+    // authoritative counterpart to overwrite it — presence suppression — is
+    // a refusal.
+    for key in env.keys() {
+        if !is_posix_env_key(key) {
+            return Err(format!(
+                "env key {key:?} is not a POSIX environment variable name \
+                 ([A-Za-z_][A-Za-z0-9_]*); Kubernetes would treat it \
+                 inconsistently across cluster versions"
+            ));
+        }
+        if key.eq_ignore_ascii_case(FORBIDDEN_KEY) {
+            return Err(format!(
+                "{FORBIDDEN_KEY} must not be set on a remote agent: presence \
+                 is the only signal that a remote agent is alive"
+            ));
+        }
+    }
+
+    // Tier 3 — authoritative. Every key it owns is cleared first, then the
+    // values it has are written, so it wins at a key whether or not it has a
+    // value there (see [`AUTHORITATIVE_KEYS`]).
+    for key in AUTHORITATIVE_KEYS {
+        env.remove(*key);
+    }
+    // Identity comes from top-level payload fields, never from `env_vars`
+    // (§Reserved-key rule). All three components must be nonempty: an agent
+    // that cannot reach a relay is the identityless launch L1 item 1 exists to
+    // prevent, and a blank field would otherwise sail through into the Secret
+    // and produce a pod that starts, fails to connect, and looks like a
+    // network problem.
+    let Some(relay_url) = identity_component(&agent.relay_url) else {
+        return Err("deploy refused: relay_url is empty — the agent would have \
+                    no relay to connect to"
+            .to_string());
+    };
+    env.insert("BUZZ_RELAY_URL".into(), relay_url.to_string());
+    env.insert("BUZZ_PRIVATE_KEY".into(), agent.private_key_nsec.clone());
+    // The git credential/signing helpers read NOSTR_PRIVATE_KEY.
+    env.insert("NOSTR_PRIVATE_KEY".into(), agent.private_key_nsec.clone());
+
+    // Owner: at least one of these must resolve, or the harness cannot match
+    // `!shutdown` and §Stop describes a mechanism that does not work.
+    let auth_tag = agent.auth_tag.as_deref().and_then(identity_component);
+    let owner = launch.owner_pubkey.as_deref().and_then(identity_component);
+    match (auth_tag, owner) {
+        (None, None) => {
+            return Err("deploy refused: neither auth_tag nor launch.owner_pubkey \
+                        resolved — without an owner the agent cannot honor \
+                        !shutdown"
+                .to_string())
+        }
+        (tag, own) => {
+            if let Some(t) = tag {
+                env.insert("BUZZ_AUTH_TAG".into(), t.to_string());
+            }
+            if let Some(o) = own {
+                env.insert("BUZZ_ACP_AGENT_OWNER".into(), o.to_string());
+            }
+        }
+    }
+
+    // The harness and MCP binaries are resolved against the *image's* PATH.
+    // A host path forwarded from the desktop is guaranteed absent in the
+    // container (§Launch data, host-resolved values).
+    if let Some(command) = launch.command.as_deref().filter(|c| !c.is_empty()) {
+        env.insert("BUZZ_ACP_AGENT_COMMAND".into(), command.to_string());
+    }
+    if !launch.args.is_empty() {
+        // Comma-joined because that is what the harness's CLI parser decodes,
+        // and what the desktop's local spawn does. An argument containing a
+        // comma is unrepresentable in both paths; inventing an escaping
+        // scheme here would produce args the harness cannot decode.
+        env.insert("BUZZ_ACP_AGENT_ARGS".into(), launch.args.join(","));
+    }
+    env.insert("BUZZ_ACP_MCP_COMMAND".into(), "buzz-dev-mcp".into());
+
+    if let Some(respond_to) = agent.respond_to.as_deref().filter(|s| !s.is_empty()) {
+        validate_respond_to_gate(respond_to, agent.respond_to_allowlist.as_deref())?;
+        env.insert("BUZZ_ACP_RESPOND_TO".into(), respond_to.to_string());
+    }
+    if let Some(list) = agent
+        .respond_to_allowlist
+        .as_ref()
+        .filter(|l| !l.is_empty())
+    {
+        env.insert("BUZZ_ACP_RESPOND_TO_ALLOWLIST".into(), list.join(","));
+    }
+
+    if let Some(secs) = auth.inactivity_seconds {
+        env.insert("BUZZ_ACP_EXIT_AFTER_INACTIVITY".into(), secs.to_string());
+    }
+    // The generation token doubles as the lifecycle-frame correlator, so pod
+    // logs and observer frames share one identity (§K8s Secrets).
+    env.insert(START_NONCE_KEY.into(), auth.generation.to_string());
+
+    let total: usize = env.values().map(String::len).sum();
+    if total > MAX_SECRET_BYTES {
+        return Err(format!(
+            "agent environment is {total} bytes; Kubernetes caps Secret data \
+             at {MAX_SECRET_BYTES}"
+        ));
+    }
+
+    Ok(env)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn payload_json(extra_agent: serde_json::Value) -> AgentPayload {
+        let mut agent = serde_json::json!({
+            "name": "a",
+            "relay_url": "wss://relay.example",
+            "private_key_nsec": "nsec1example",
+            "auth_tag": "tag-1",
+        });
+        let (serde_json::Value::Object(base), serde_json::Value::Object(extra)) =
+            (&mut agent, extra_agent)
+        else {
+            panic!("expected objects")
+        };
+        base.extend(extra);
+        serde_json::from_value(agent).unwrap()
+    }
+
+    fn build(agent: &AgentPayload) -> Result<BTreeMap<String, String>, String> {
+        build_env(
+            agent,
+            AuthoritativeInputs {
+                generation: "gen0001",
+                inactivity_seconds: Some(7200),
+            },
+        )
+    }
+
+    #[test]
+    fn identity_comes_from_top_level_fields() {
+        let env = build(&payload_json(serde_json::json!({}))).unwrap();
+        assert_eq!(env["BUZZ_RELAY_URL"], "wss://relay.example");
+        assert_eq!(env["BUZZ_PRIVATE_KEY"], "nsec1example");
+        assert_eq!(env["NOSTR_PRIVATE_KEY"], "nsec1example");
+        assert_eq!(env["BUZZ_AUTH_TAG"], "tag-1");
+    }
+
+    /// Wren's amendment, and the spec's later-wins rule: a lower tier that
+    /// spoofs an authoritative key is *overwritten*, not refused. Refusing
+    /// would diverge from the local spawn, where the same env is written
+    /// before the authoritative layer and simply loses.
+    #[test]
+    fn lower_tiers_cannot_spoof_authoritative_values() {
+        let agent = payload_json(serde_json::json!({
+            "launch": {
+                "command": "goose",
+                "policy_env": {
+                    "BUZZ_PRIVATE_KEY": "nsec1attacker",
+                    "BUZZ_MANAGED_AGENT_START_NONCE": "forged",
+                },
+                "env": {
+                    "BUZZ_RELAY_URL": "wss://attacker.example",
+                    "NOSTR_PRIVATE_KEY": "nsec1attacker",
+                    "BUZZ_AUTH_TAG": "forged-tag",
+                    "BUZZ_ACP_AGENT_OWNER": "cafe",
+                    "BUZZ_ACP_AGENT_COMMAND": "/bin/sh",
+                    "BUZZ_ACP_MCP_COMMAND": "/bin/sh",
+                    "BUZZ_ACP_EXIT_AFTER_INACTIVITY": "0",
+                },
+                "owner_pubkey": "beef"
+            }
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["BUZZ_PRIVATE_KEY"], "nsec1example");
+        assert_eq!(env["NOSTR_PRIVATE_KEY"], "nsec1example");
+        assert_eq!(env["BUZZ_RELAY_URL"], "wss://relay.example");
+        assert_eq!(env["BUZZ_AUTH_TAG"], "tag-1");
+        assert_eq!(env["BUZZ_ACP_AGENT_OWNER"], "beef");
+        assert_eq!(env["BUZZ_ACP_AGENT_COMMAND"], "goose");
+        assert_eq!(env["BUZZ_ACP_MCP_COMMAND"], "buzz-dev-mcp");
+        assert_eq!(env["BUZZ_ACP_EXIT_AFTER_INACTIVITY"], "7200");
+        assert_eq!(env["BUZZ_MANAGED_AGENT_START_NONCE"], "gen0001");
+    }
+
+    /// Tier 1 is *overridable* — user env beats policy defaults, matching the
+    /// local spawn, where the user layer is written after them. Getting this
+    /// backwards would make remote agents ignore overrides local agents honor.
+    #[test]
+    fn user_env_overrides_policy_defaults() {
+        let agent = payload_json(serde_json::json!({
+            "launch": {
+                "policy_env": {"GOOSE_MODE": "auto", "BUZZ_ACP_MODEL": "sonnet"},
+                "env": {"GOOSE_MODE": "chat"},
+                "owner_pubkey": "beef"
+            }
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["GOOSE_MODE"], "chat");
+        assert_eq!(env["BUZZ_ACP_MODEL"], "sonnet");
+    }
+
+    /// `launch.env` already contains the merged user env, so re-merging the
+    /// legacy field would undo a layering the desktop already resolved.
+    #[test]
+    fn legacy_env_vars_are_not_remerged_when_launch_present() {
+        let agent = payload_json(serde_json::json!({
+            "env_vars": {"STALE": "yes", "SHARED": "legacy"},
+            "launch": {"env": {"SHARED": "resolved"}, "owner_pubkey": "beef"}
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["SHARED"], "resolved");
+        assert!(!env.contains_key("STALE"), "legacy env_vars re-merged");
+    }
+
+    /// ...but a desktop predating the `launch` block has nothing else to
+    /// offer, so the legacy field is the truth in exactly that case.
+    #[test]
+    fn legacy_env_vars_used_when_launch_absent() {
+        let agent = payload_json(serde_json::json!({"env_vars": {"API": "v"}}));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["API"], "v");
+    }
+
+    #[test]
+    fn refuses_when_no_owner_resolves() {
+        let agent = payload_json(serde_json::json!({"auth_tag": null}));
+        let err = build(&agent).unwrap_err();
+        assert!(err.contains("!shutdown"), "unhelpful error: {err}");
+    }
+
+    /// An empty string is not an owner. Without this the refusal is
+    /// bypassable by a blank field and the pod launches unable to be stopped.
+    #[test]
+    fn empty_owner_fields_count_as_absent() {
+        for blank in ["", "   "] {
+            let agent = payload_json(serde_json::json!({
+                "auth_tag": blank,
+                "launch": {"owner_pubkey": blank}
+            }));
+            assert!(
+                build(&agent).is_err(),
+                "whitespace resolved as an owner: {blank:?}"
+            );
+        }
+    }
+
+    /// The other half of every identity guard: what is *stored*. A validator
+    /// that trims and a writer that doesn't disagree about the value, and the
+    /// padding reaches the harness inside the Secret. Assert on the stored
+    /// string — asserting only that the deploy was accepted passes either way.
+    #[test]
+    fn identity_components_are_stored_trimmed() {
+        let agent = payload_json(serde_json::json!({
+            "relay_url": "  wss://relay.example  ",
+            "auth_tag": "  tag-1  ",
+            "launch": {"owner_pubkey": "  beefcafe  "}
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["BUZZ_RELAY_URL"], "wss://relay.example");
+        assert_eq!(env["BUZZ_AUTH_TAG"], "tag-1");
+        assert_eq!(env["BUZZ_ACP_AGENT_OWNER"], "beefcafe");
+    }
+
+    /// L1 item 1's third identity component. The nsec arm is enforced in
+    /// `naming.rs` and the owner arm above; without this one an agent
+    /// deploys with nothing to connect to — a pod that starts, fails at the
+    /// relay, and reads as a network fault rather than a refused launch.
+    #[test]
+    fn refuses_empty_relay_url() {
+        for blank in ["", "   "] {
+            let agent = payload_json(serde_json::json!({"relay_url": blank}));
+            let err = build(&agent).unwrap_err();
+            assert!(err.contains("relay_url"), "unhelpful error: {err}");
+        }
+    }
+
+    #[test]
+    fn owner_pubkey_alone_is_sufficient() {
+        let agent = payload_json(serde_json::json!({
+            "auth_tag": null,
+            "launch": {"owner_pubkey": "beefcafe"}
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["BUZZ_ACP_AGENT_OWNER"], "beefcafe");
+        assert!(!env.contains_key("BUZZ_AUTH_TAG"));
+    }
+
+    #[test]
+    fn refuses_presence_suppression() {
+        let agent = payload_json(serde_json::json!({
+            "launch": {"env": {"BUZZ_ACP_NO_PRESENCE": "1"}, "owner_pubkey": "beef"}
+        }));
+        let err = build(&agent).unwrap_err();
+        assert!(err.contains("BUZZ_ACP_NO_PRESENCE"), "got: {err}");
+    }
+
+    /// `foo.bar` is a legal Secret key but not a legal env name: pre-1.30
+    /// kubelets drop it, 1.30+ inject it. Refuse rather than behave
+    /// differently depending on the cluster.
+    #[test]
+    fn refuses_non_posix_env_keys() {
+        for bad in ["foo.bar", "foo-bar", "1LEADING", "", "has space"] {
+            let agent = payload_json(serde_json::json!({
+                "launch": {"env": {bad: "v"}, "owner_pubkey": "beef"}
+            }));
+            assert!(build(&agent).is_err(), "accepted non-POSIX key {bad:?}");
+        }
+    }
+
+    #[test]
+    fn args_are_comma_joined_and_omitted_when_empty() {
+        let agent = payload_json(serde_json::json!({
+            "launch": {"command": "goose", "args": ["run", "--no-session"], "owner_pubkey": "b"}
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["BUZZ_ACP_AGENT_ARGS"], "run,--no-session");
+
+        let agent = payload_json(serde_json::json!({
+            "launch": {"command": "goose", "args": [], "owner_pubkey": "b"}
+        }));
+        assert!(!build(&agent).unwrap().contains_key("BUZZ_ACP_AGENT_ARGS"));
+    }
+
+    /// The top-level `model`/`provider` fields are display inputs; their
+    /// environment consequence is per-runtime and arrives already resolved
+    /// inside `launch`. A provider-side mapping is wrong for three of the
+    /// four built-in runtimes.
+    #[test]
+    fn provider_never_maps_model_or_provider_itself() {
+        let agent = payload_json(serde_json::json!({
+            "model": "claude-opus", "provider": "anthropic",
+            "launch": {"owner_pubkey": "beef"}
+        }));
+        let env = build(&agent).unwrap();
+        for key in [
+            "BUZZ_AGENT_PROVIDER",
+            "BUZZ_AGENT_MODEL",
+            "GOOSE_PROVIDER",
+            "GOOSE_MODEL",
+        ] {
+            assert!(!env.contains_key(key), "provider mapped {key} itself");
+        }
+    }
+
+    /// `turn_timeout_seconds` is deprecated and ignored upstream; the local
+    /// spawn does not emit it either.
+    #[test]
+    fn turn_timeout_is_not_mapped() {
+        let agent = payload_json(serde_json::json!({
+            "turn_timeout_seconds": 30, "launch": {"owner_pubkey": "b"}
+        }));
+        let env = build(&agent).unwrap();
+        assert!(!env.keys().any(|k| k.contains("TURN_TIMEOUT")));
+    }
+
+    #[test]
+    fn inactivity_omitted_when_unset() {
+        let agent = payload_json(serde_json::json!({"launch": {"owner_pubkey": "b"}}));
+        let env = build_env(
+            &agent,
+            AuthoritativeInputs {
+                generation: "g",
+                inactivity_seconds: None,
+            },
+        )
+        .unwrap();
+        assert!(!env.contains_key("BUZZ_ACP_EXIT_AFTER_INACTIVITY"));
+    }
+
+    /// Structural guard over the whole authoritative list at once: whatever
+    /// the lower tiers contain, no authoritative key holds a lower-tier value
+    /// — including the conditionally-written ones the authoritative tier has
+    /// nothing to say about, which must be **absent** rather than spoofed.
+    /// This test caught exactly that: `BUZZ_ACP_AGENT_ARGS` is only written
+    /// when `launch.args` is non-empty, so plain later-wins overwrite left the
+    /// spoofed value in place.
+    #[test]
+    fn no_authoritative_key_retains_a_lower_tier_value() {
+        let spoofed: serde_json::Map<String, serde_json::Value> = AUTHORITATIVE_KEYS
+            .iter()
+            .map(|k| ((*k).to_string(), serde_json::json!("SPOOFED")))
+            .collect();
+        // Split across both lower tiers: policy_env and env are separate
+        // insertion points, and a fix that only cleared one would pass a
+        // single-tier test.
+        let agent = payload_json(serde_json::json!({
+            "launch": {
+                "command": "goose",
+                "policy_env": spoofed.clone(),
+                "env": spoofed,
+                "owner_pubkey": "beef"
+            }
+        }));
+        let env = build(&agent).unwrap();
+        for key in AUTHORITATIVE_KEYS {
+            assert_ne!(
+                env.get(*key).map(String::as_str),
+                Some("SPOOFED"),
+                "{key} kept its lower-tier value"
+            );
+        }
+        // The keys the authoritative tier had no value for are gone, not
+        // merely different.
+        for absent in [
+            "BUZZ_ACP_AGENT_ARGS",
+            "BUZZ_ACP_RESPOND_TO",
+            "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
+        ] {
+            assert!(!env.contains_key(absent), "{absent} survived the clear");
+        }
+    }
+
+    /// A 64-hex pubkey, the only allowlist entry shape the harness accepts.
+    fn pubkey(fill: char) -> String {
+        std::iter::repeat_n(fill, 64).collect()
+    }
+
+    /// The gate the harness refuses first (`config.rs:996-1004`). Refusing it
+    /// here is the difference between one error message and an unbounded
+    /// fail-replace loop that leaves a Secret per attempt.
+    #[test]
+    fn allowlist_mode_with_an_empty_list_is_refused() {
+        for empty in [serde_json::json!([]), serde_json::Value::Null] {
+            let agent = payload_json(serde_json::json!({
+                "respond_to": "allowlist",
+                "respond_to_allowlist": empty,
+            }));
+            let err = build(&agent).unwrap_err();
+            assert!(
+                err.contains("the allowlist is empty"),
+                "unexpected error: {err}"
+            );
+        }
+    }
+
+    /// `config.rs:629-641` — each entry must be exactly 64 hex characters.
+    /// The rejects are the distinct ways to miss that: too short, right length
+    /// but not hex, empty, and one character short of valid.
+    #[test]
+    fn an_allowlist_entry_that_is_not_64_hex_is_refused() {
+        for bad in ["abc1234", &"z".repeat(64), "", &pubkey('a')[..63]] {
+            let agent = payload_json(serde_json::json!({
+                "respond_to": "allowlist",
+                "respond_to_allowlist": [pubkey('a'), bad],
+            }));
+            let err = build(&agent).unwrap_err();
+            assert!(
+                err.contains("must be exactly 64 hex characters"),
+                "{bad:?} was accepted; error was: {err}"
+            );
+        }
+    }
+
+    /// The positive control: the guard refuses bad gates, not every gate.
+    /// Without this, a validator that refused unconditionally would pass both
+    /// tests above.
+    #[test]
+    fn a_valid_allowlist_gate_is_accepted_and_comma_joined() {
+        let agent = payload_json(serde_json::json!({
+            "respond_to": "allowlist",
+            "respond_to_allowlist": [pubkey('a'), pubkey('b')],
+        }));
+        let env = build(&agent).unwrap();
+        assert_eq!(env["BUZZ_ACP_RESPOND_TO"], "allowlist");
+        assert_eq!(
+            env["BUZZ_ACP_RESPOND_TO_ALLOWLIST"],
+            format!("{},{}", pubkey('a'), pubkey('b'))
+        );
+    }
+
+    /// The harness validates the allowlist **only** in allowlist mode and
+    /// merely warns otherwise (`config.rs:1005-1010`). A stricter provider
+    /// would refuse a deploy whose identical local spawn succeeds, so this
+    /// pins the asymmetry rather than leaving it to look like an oversight.
+    #[test]
+    fn a_junk_allowlist_is_tolerated_outside_allowlist_mode() {
+        for mode in ["owner-only", "anyone"] {
+            let agent = payload_json(serde_json::json!({
+                "respond_to": mode,
+                "respond_to_allowlist": ["not-a-pubkey"],
+            }));
+            let env = build(&agent)
+                .unwrap_or_else(|e| panic!("{mode} with a stale list must deploy: {e}"));
+            assert_eq!(env["BUZZ_ACP_RESPOND_TO"], mode);
+        }
+    }
+
+    /// `respond_to` is an opaque `String` on the wire but a `clap::ValueEnum`
+    /// at the harness, so an unrecognized mode dies at `rc=2` — before config
+    /// parsing runs at all, earlier than either refusal above. Measured
+    /// against the built binary: `invalid value 'npub1abc' for '--respond-to'`.
+    /// This is the shape our own fixture carried until it was corrected.
+    #[test]
+    fn a_mode_the_harness_cannot_parse_is_refused() {
+        for bad in ["npub1abc", "OWNER-ONLY", "owner_only", "allowlistt", "x"] {
+            let agent = payload_json(serde_json::json!({ "respond_to": bad }));
+            let err = build(&agent).unwrap_err();
+            assert!(
+                err.contains("is not a mode the harness accepts"),
+                "{bad:?} was accepted; error was: {err}"
+            );
+        }
+    }
+
+    /// `clap` does not trim its value-enum input, so a padded mode is `rc=2`
+    /// even though the same string trimmed is valid. Measured: `invalid value
+    /// ' allowlist ' for '--respond-to'`. Trimming here would accept a deploy
+    /// the harness refuses — the exact direction this guard exists to prevent.
+    #[test]
+    fn a_padded_mode_is_refused_because_clap_does_not_trim() {
+        for padded in [" allowlist ", "allowlist ", " owner-only", "\tnobody"] {
+            let agent = payload_json(serde_json::json!({
+                "respond_to": padded,
+                "respond_to_allowlist": [pubkey('a')],
+            }));
+            let err = build(&agent).unwrap_err();
+            assert!(
+                err.contains("is not a mode the harness accepts"),
+                "{padded:?} was accepted; error was: {err}"
+            );
+        }
+    }
+
+    /// Positive control for the mode check, and the reason it validates the
+    /// harness's four rather than the desktop's three: `nobody` is rejected by
+    /// `parse_wire` on purpose (`managed_agents/types.rs:871-880`) but starts
+    /// fine at the harness. A guard mirroring the desktop enum would refuse a
+    /// working launch from a non-desktop caller — the callers this guard is
+    /// for. Without this test, refusing `nobody` would pass everything above.
+    #[test]
+    fn every_mode_the_harness_accepts_is_deployable() {
+        for mode in ["owner-only", "allowlist", "anyone", "nobody"] {
+            let agent = payload_json(serde_json::json!({
+                "respond_to": mode,
+                "respond_to_allowlist": [pubkey('a')],
+            }));
+            let env = build(&agent)
+                .unwrap_or_else(|e| panic!("{mode} is valid at the harness but was refused: {e}"));
+            assert_eq!(env["BUZZ_ACP_RESPOND_TO"], mode);
+        }
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/gc.rs b/crates/buzz-backend-kubernetes/src/gc.rs
new file mode 100644
index 0000000000..2e18825aa4
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/gc.rs
@@ -0,0 +1,368 @@
+//! Preflight garbage collection (spec §K8s GC, `docs/remote-agents.md:1282-1335`).
+//!
+//! GC runs on every deploy, after identity derivation and before the state
+//! transition. It deletes terminated pods (and their referenced Secrets) and
+//! age-eligible orphan Secrets — every one of which must pass the full-pubkey
+//! annotation check *and* carry the management marker. An unmarked object is
+//! never GC'd regardless of its labels.
+//!
+//! The decision layer here is pure. The effectful caller supplies the observed
+//! objects and the apiserver's clock; this module decides what may be deleted.
+
+use crate::naming::AgentIdentity;
+use crate::observe::{referenced_secret, secret_is_ours};
+use chrono::{DateTime, Utc};
+use k8s_openapi::api::core::v1::{Pod, Secret};
+
+/// The deploy operation deadline (spec §Deploy: `timeout: 600s`).
+pub const OPERATION_DEADLINE_SECS: i64 = 600;
+
+/// An unreferenced Secret is GC-eligible only once it is older than **twice**
+/// the deploy deadline. Rationale: Secret-create → pod-create is not atomic
+/// against an independent GC pass, so without the gate a concurrent attempt's
+/// preflight GC can delete a Secret whose pod has not been created yet and
+/// strand that deploy. The age bound makes "unreferenced" mean "provably
+/// abandoned" — any attempt that could still reference it has exceeded its own
+/// deadline (`:1301-1319`).
+pub const ORPHAN_SECRET_MIN_AGE_SECS: i64 = 2 * OPERATION_DEADLINE_SECS;
+
+/// What a GC pass decided to delete. Names only: the caller re-reads each
+/// object's own fence at delete time.
+#[derive(Debug, Default, PartialEq, Eq)]
+pub struct GcPlan {
+    /// Terminated, verified, marker-bearing pods.
+    pub pods: Vec<String>,
+    /// Age-eligible, verified, marker-bearing orphan Secrets.
+    pub secrets: Vec<String>,
+}
+
+/// Plan a GC pass.
+///
+/// `now` is the apiserver's clock — the HTTP `Date` header from the very list
+/// call that produced `secrets`. `None` means the header was absent or
+/// unparseable, in which case **orphan-Secret GC is skipped entirely** rather
+/// than falling back to local time: this provider runs on a user's desktop,
+/// and a local clock fast by more than the margin does not race — it
+/// deterministically computes every in-flight Secret as expired, on every
+/// pass, reopening exactly the interleaving the gate exists to close
+/// (`:1321-1335`). A deferred cleanup is free; a wrong deletion is not.
+///
+/// Terminated-pod GC does not use the clock and is unaffected.
+pub fn plan(
+    identity: &AgentIdentity,
+    pods: &[Pod],
+    secrets: &[Secret],
+    terminated: impl Fn(&Pod) -> bool,
+    now: Option<DateTime<Utc>>,
+) -> GcPlan {
+    // Only pods that pass the full fence participate — in either direction.
+    // An unverified pod is neither deleted nor allowed to protect a Secret:
+    // it cannot be ours, so its `envFrom` cannot reference our generation.
+    let ours: Vec<&Pod> = pods
+        .iter()
+        .filter(|p| {
+            crate::observe::verify(p, identity, crate::classify::Startup::Started).is_some()
+        })
+        .collect();
+
+    let doomed_pods: Vec<&&Pod> = ours.iter().filter(|p| terminated(p)).collect();
+
+    // A Secret referenced by ANY existing pod is protected — deliberately
+    // including not-yet-started pods, whose `envFrom` is exactly as
+    // load-bearing as a running pod's (`:1262-1264`). Pods being GC'd in this
+    // same pass are excluded, so their Secrets go with them.
+    let doomed_names: Vec<&str> = doomed_pods
+        .iter()
+        .filter_map(|p| p.metadata.name.as_deref())
+        .collect();
+    let protected: Vec<String> = ours
+        .iter()
+        .filter(|p| !doomed_names.contains(&p.metadata.name.as_deref().unwrap_or_default()))
+        .filter_map(|p| referenced_secret(p))
+        .collect();
+
+    let mut plan = GcPlan {
+        pods: doomed_names.iter().map(|n| n.to_string()).collect(),
+        secrets: doomed_pods
+            .iter()
+            .filter_map(|p| referenced_secret(p))
+            .collect(),
+    };
+
+    // Orphan sweep: only with a server clock.
+    if let Some(now) = now {
+        for secret in secrets {
+            if !secret_is_ours(secret, identity) {
+                continue;
+            }
+            let Some(name) = secret.metadata.name.as_deref() else {
+                continue;
+            };
+            if protected.contains(&name.to_string()) || plan.secrets.iter().any(|s| s == name) {
+                continue;
+            }
+            let Some(created) = secret.metadata.creation_timestamp.as_ref() else {
+                // No server-assigned timestamp means no age proof. Skip.
+                continue;
+            };
+            if (now - created.0).num_seconds() >= ORPHAN_SECRET_MIN_AGE_SECS {
+                plan.secrets.push(name.to_string());
+            }
+        }
+    }
+
+    plan
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::naming::{ANNOTATION_PUBKEY_FULL, LABEL_MANAGED_BY};
+    use k8s_openapi::api::core::v1::{Container, EnvFromSource, PodSpec, SecretEnvSource};
+    use k8s_openapi::apimachinery::pkg::apis::meta::v1::{ObjectMeta, Time};
+    use std::collections::BTreeMap;
+
+    fn identity() -> AgentIdentity {
+        use nostr::nips::nip19::ToBech32;
+        let keys = nostr::Keys::generate();
+        AgentIdentity::from_nsec(&keys.secret_key().to_bech32().unwrap()).unwrap()
+    }
+
+    fn pod_named(id: &AgentIdentity, name: &str, secret: Option<&str>) -> Pod {
+        Pod {
+            metadata: ObjectMeta {
+                name: Some(name.into()),
+                uid: Some(format!("uid-{name}")),
+                resource_version: Some("1".into()),
+                labels: Some(id.labels()),
+                annotations: Some(
+                    [(
+                        ANNOTATION_PUBKEY_FULL.to_string(),
+                        id.pubkey_hex().to_string(),
+                    )]
+                    .into_iter()
+                    .collect::<BTreeMap<_, _>>(),
+                ),
+                ..Default::default()
+            },
+            spec: secret.map(|s| PodSpec {
+                containers: vec![Container {
+                    name: "agent".into(),
+                    env_from: Some(vec![EnvFromSource {
+                        secret_ref: Some(SecretEnvSource {
+                            name: s.into(),
+                            optional: Some(false),
+                        }),
+                        ..Default::default()
+                    }]),
+                    ..Default::default()
+                }],
+                ..Default::default()
+            }),
+            ..Default::default()
+        }
+    }
+
+    fn secret_named(id: &AgentIdentity, name: &str, age_secs: i64, now: DateTime<Utc>) -> Secret {
+        Secret {
+            metadata: ObjectMeta {
+                name: Some(name.into()),
+                labels: Some(id.labels()),
+                annotations: Some(
+                    [(
+                        ANNOTATION_PUBKEY_FULL.to_string(),
+                        id.pubkey_hex().to_string(),
+                    )]
+                    .into_iter()
+                    .collect::<BTreeMap<_, _>>(),
+                ),
+                creation_timestamp: Some(Time(now - chrono::Duration::seconds(age_secs))),
+                ..Default::default()
+            },
+            ..Default::default()
+        }
+    }
+
+    fn never(_: &Pod) -> bool {
+        false
+    }
+    fn always(_: &Pod) -> bool {
+        true
+    }
+
+    #[test]
+    fn terminated_pods_and_their_secrets_are_collected_together() {
+        let id = identity();
+        let now = Utc::now();
+        let pod = pod_named(&id, "buzz-agent-dead", Some("buzz-agent-dead-gen1"));
+        let plan = plan(&id, &[pod], &[], always, Some(now));
+        assert_eq!(plan.pods, ["buzz-agent-dead"]);
+        assert_eq!(plan.secrets, ["buzz-agent-dead-gen1"]);
+    }
+
+    #[test]
+    fn live_pods_are_never_collected() {
+        let id = identity();
+        let pod = pod_named(&id, "buzz-agent-live", Some("buzz-agent-live-gen1"));
+        let plan = plan(&id, &[pod], &[], never, Some(Utc::now()));
+        assert_eq!(plan, GcPlan::default());
+    }
+
+    /// The auto-repair fence applies to GC identically: an object that lacks
+    /// the marker, or carries a different pubkey, is never touched — however
+    /// well its labels match.
+    #[test]
+    fn unmarked_and_mismatched_objects_are_never_collected() {
+        let id = identity();
+        let other = identity();
+        let now = Utc::now();
+
+        let mut unmarked = pod_named(&id, "look-alike", Some("look-alike-gen1"));
+        let mut labels = id.labels();
+        labels.remove(LABEL_MANAGED_BY);
+        unmarked.metadata.labels = Some(labels);
+
+        let mut foreign = pod_named(&id, "someone-elses", Some("someone-elses-gen1"));
+        foreign.metadata.annotations = Some(
+            [(
+                ANNOTATION_PUBKEY_FULL.to_string(),
+                other.pubkey_hex().to_string(),
+            )]
+            .into_iter()
+            .collect(),
+        );
+
+        let mut unmarked_secret = secret_named(&id, "orphan-unmarked", 100_000, now);
+        unmarked_secret.metadata.labels = Some(BTreeMap::new());
+        let mut foreign_secret = secret_named(&id, "orphan-foreign", 100_000, now);
+        foreign_secret.metadata.annotations = Some(
+            [(
+                ANNOTATION_PUBKEY_FULL.to_string(),
+                other.pubkey_hex().to_string(),
+            )]
+            .into_iter()
+            .collect(),
+        );
+
+        let plan = plan(
+            &id,
+            &[unmarked, foreign],
+            &[unmarked_secret, foreign_secret],
+            always,
+            Some(now),
+        );
+        assert_eq!(
+            plan,
+            GcPlan::default(),
+            "GC touched an object it does not own"
+        );
+    }
+
+    /// The interleaving the age gate exists to close: attempt A creates its
+    /// Secret; concurrent attempt B's preflight GC runs before A creates its
+    /// pod. Without the gate B deletes A's Secret and strands A.
+    #[test]
+    fn young_unreferenced_secrets_are_protected() {
+        let id = identity();
+        let now = Utc::now();
+        let fresh = secret_named(&id, "buzz-agent-x-gen-inflight", 5, now);
+        assert_eq!(
+            plan(&id, &[], &[fresh], never, Some(now)),
+            GcPlan::default()
+        );
+    }
+
+    /// Past twice the deadline, any attempt that could still reference the
+    /// Secret has exceeded its own deadline — so it is provably abandoned.
+    #[test]
+    fn secrets_older_than_twice_the_deadline_are_collected() {
+        let id = identity();
+        let now = Utc::now();
+        let old = secret_named(
+            &id,
+            "buzz-agent-x-gen-abandoned",
+            ORPHAN_SECRET_MIN_AGE_SECS + 1,
+            now,
+        );
+        let plan = plan(&id, &[], &[old], never, Some(now));
+        assert_eq!(plan.secrets, ["buzz-agent-x-gen-abandoned"]);
+    }
+
+    /// The boundary itself, both sides. `>= 1200s` is eligible.
+    #[test]
+    fn age_gate_boundary_is_exact() {
+        let id = identity();
+        let now = Utc::now();
+        let just_under = secret_named(&id, "under", ORPHAN_SECRET_MIN_AGE_SECS - 1, now);
+        let exactly = secret_named(&id, "exact", ORPHAN_SECRET_MIN_AGE_SECS, now);
+        assert!(plan(&id, &[], &[just_under], never, Some(now))
+            .secrets
+            .is_empty());
+        assert_eq!(
+            plan(&id, &[], &[exactly], never, Some(now)).secrets,
+            ["exact"]
+        );
+    }
+
+    /// The same-clock rule. No apiserver `Date` header → skip the orphan
+    /// sweep entirely. A local clock fast by more than the margin would
+    /// silently delete every in-flight Secret on every pass.
+    #[test]
+    fn without_a_server_clock_the_orphan_sweep_is_skipped() {
+        let id = identity();
+        let now = Utc::now();
+        let ancient = secret_named(&id, "buzz-agent-x-gen-ancient", 10_000_000, now);
+        let plan = plan(&id, &[], &[ancient], never, None);
+        assert!(
+            plan.secrets.is_empty(),
+            "orphan swept without a server clock — a fast local clock would delete live Secrets"
+        );
+    }
+
+    /// ...but terminated-pod GC does not consult the clock, so it still runs.
+    #[test]
+    fn terminated_pod_gc_runs_without_a_server_clock() {
+        let id = identity();
+        let pod = pod_named(&id, "buzz-agent-dead", Some("buzz-agent-dead-gen1"));
+        let plan = plan(&id, &[pod], &[], always, None);
+        assert_eq!(plan.pods, ["buzz-agent-dead"]);
+        assert_eq!(plan.secrets, ["buzz-agent-dead-gen1"]);
+    }
+
+    /// "Existing" includes not-yet-started pods: a Secret referenced by a pod
+    /// still pulling its image must not be swept, however old it is.
+    #[test]
+    fn secrets_referenced_by_a_pending_pod_are_protected() {
+        let id = identity();
+        let now = Utc::now();
+        let pending = pod_named(&id, "buzz-agent-pending", Some("buzz-agent-pending-gen1"));
+        let old = secret_named(&id, "buzz-agent-pending-gen1", 10_000_000, now);
+        let plan = plan(&id, &[pending], &[old], never, Some(now));
+        assert!(plan.secrets.is_empty(), "swept a referenced Secret");
+    }
+
+    /// A Secret with no server-assigned creationTimestamp has no age proof,
+    /// so it is skipped rather than assumed old.
+    #[test]
+    fn secrets_without_a_creation_timestamp_are_skipped() {
+        let id = identity();
+        let now = Utc::now();
+        let mut no_timestamp = secret_named(&id, "buzz-agent-x-gen-unknown", 10_000_000, now);
+        no_timestamp.metadata.creation_timestamp = None;
+        assert!(plan(&id, &[], &[no_timestamp], never, Some(now))
+            .secrets
+            .is_empty());
+    }
+
+    /// A Secret belonging to a pod being collected in this same pass goes with
+    /// it, and must not be listed twice.
+    #[test]
+    fn a_collected_pods_secret_is_listed_once() {
+        let id = identity();
+        let now = Utc::now();
+        let dead = pod_named(&id, "buzz-agent-dead", Some("buzz-agent-dead-gen1"));
+        let its_secret = secret_named(&id, "buzz-agent-dead-gen1", 10_000_000, now);
+        let plan = plan(&id, &[dead], &[its_secret], always, Some(now));
+        assert_eq!(plan.secrets, ["buzz-agent-dead-gen1"]);
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/image.rs b/crates/buzz-backend-kubernetes/src/image.rs
new file mode 100644
index 0000000000..409989fda9
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/image.rs
@@ -0,0 +1,184 @@
+//! Image reference validation (spec §Image).
+//!
+//! The object holding this reference runs with an nsec, so the reference must
+//! be **immutable**. Registry tags are mutable pointers — Kubernetes itself
+//! distinguishes them from digests for exactly this reason — so a tag-only
+//! reference is rejected, not just `:latest`.
+//!
+//! There is no parse-time fallback: `image` is required, and its absence
+//! fails closed with a named field. The published `ghcr.io/block/buzz-sprig`
+//! digest is offered only as a schema `default` (a UI prefill the desktop
+//! submits explicitly — see `config::DEFAULT_IMAGE`), so the create-intent
+//! fingerprint never depends on compiled-in provider state.
+
+/// A validated, digest-qualified image reference.
+///
+/// The inner string is always in canonical tagless form `name@sha256:<hex>`:
+/// `name:tag@sha256:…` normalizes by dropping the tag, because the tag is
+/// decorative once a digest pins the content, and leaving it in would make
+/// two references to identical bytes produce different create-intent
+/// fingerprints.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ImageRef(String);
+
+impl ImageRef {
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl std::fmt::Display for ImageRef {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+/// Parse and normalize a user-supplied image reference.
+pub fn parse(raw: &str) -> Result<ImageRef, String> {
+    let reference = raw.trim();
+    if reference.is_empty() {
+        return Err("provider_config.image is required: no image is assumed \
+                    at parse time, so the digest-pinned image to run must be \
+                    given explicitly"
+            .to_string());
+    }
+
+    let mut parts = reference.split('@');
+    let name_and_tag = parts.next().unwrap_or_default();
+    let digest = match (parts.next(), parts.next()) {
+        (Some(d), None) => d,
+        (None, _) => {
+            return Err(format!(
+                "provider_config.image {reference:?} is not digest-pinned: a \
+                 tag is a mutable pointer, and this object runs with the \
+                 agent's private key. Use name@sha256:<64 hex chars>"
+            ))
+        }
+        (Some(_), Some(_)) => {
+            return Err(format!(
+                "provider_config.image {reference:?} contains more than one '@'"
+            ))
+        }
+    };
+
+    let hex = digest.strip_prefix("sha256:").ok_or_else(|| {
+        format!("provider_config.image digest {digest:?} must start with 'sha256:'")
+    })?;
+    // Lowercase only: OCI canonicalizes digest hex, and accepting uppercase
+    // would let two spellings of one digest produce two fingerprints.
+    if hex.len() != 64
+        || !hex
+            .chars()
+            .all(|c| c.is_ascii_digit() || ('a'..='f').contains(&c))
+    {
+        return Err(format!(
+            "provider_config.image digest {digest:?} must be exactly 64 \
+             lowercase hex characters"
+        ));
+    }
+
+    // Drop any tag: `name:tag@sha256:…` and `name@sha256:…` name the same
+    // bytes and must fingerprint identically. Only a *final* colon segment
+    // that isn't a port counts as a tag — `host:5000/name` has no tag.
+    let name = match name_and_tag.rfind(':') {
+        Some(colon) if !name_and_tag[colon + 1..].contains('/') => &name_and_tag[..colon],
+        _ => name_and_tag,
+    };
+    if name.is_empty() {
+        return Err(format!(
+            "provider_config.image {reference:?} has no repository name"
+        ));
+    }
+
+    Ok(ImageRef(format!("{name}@sha256:{hex}")))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn accepts_digest_pinned_reference() {
+        let d = "a".repeat(64);
+        let r = parse(&format!("ghcr.io/block/buzz-sprig@sha256:{d}")).unwrap();
+        assert_eq!(r.as_str(), format!("ghcr.io/block/buzz-sprig@sha256:{d}"));
+    }
+
+    /// The normalization that keeps the fingerprint stable: two spellings of
+    /// the same bytes must produce one reference.
+    #[test]
+    fn strips_tag_from_tag_plus_digest_form() {
+        let d = "b".repeat(64);
+        let tagged = parse(&format!("ghcr.io/block/buzz-sprig:v1.2@sha256:{d}")).unwrap();
+        let plain = parse(&format!("ghcr.io/block/buzz-sprig@sha256:{d}")).unwrap();
+        assert_eq!(tagged, plain);
+    }
+
+    /// A registry port is not a tag. `host:5000/name` must keep its port.
+    #[test]
+    fn registry_port_is_not_mistaken_for_a_tag() {
+        let d = "c".repeat(64);
+        let r = parse(&format!("localhost:5000/buzz-sprig@sha256:{d}")).unwrap();
+        assert_eq!(r.as_str(), format!("localhost:5000/buzz-sprig@sha256:{d}"));
+    }
+
+    #[test]
+    fn port_and_tag_together_drops_only_the_tag() {
+        let d = "d".repeat(64);
+        let r = parse(&format!("localhost:5000/buzz-sprig:dev@sha256:{d}")).unwrap();
+        assert_eq!(r.as_str(), format!("localhost:5000/buzz-sprig@sha256:{d}"));
+    }
+
+    /// Wren's amendment: *every* tag-only reference is rejected, not just
+    /// `:latest`. A `sha-<gitsha>` tag is traceable but still movable.
+    #[test]
+    fn rejects_every_tag_only_reference() {
+        for bad in [
+            "ghcr.io/block/buzz-sprig:latest",
+            "ghcr.io/block/buzz-sprig:v1.2.3",
+            "ghcr.io/block/buzz-sprig:sha-abc1234",
+            "ghcr.io/block/buzz-sprig",
+            "localhost:5000/buzz-sprig",
+        ] {
+            let err = parse(bad).unwrap_err();
+            assert!(err.contains("digest-pinned"), "for {bad:?} got: {err}");
+        }
+    }
+
+    /// Uppercase hex is a second spelling of one digest; accepting it would
+    /// let the same image fingerprint two ways.
+    #[test]
+    fn rejects_uppercase_digest_hex() {
+        let d = "A".repeat(64);
+        assert!(parse(&format!("img@sha256:{d}")).is_err());
+    }
+
+    #[test]
+    fn rejects_malformed_digests() {
+        let short = "a".repeat(63);
+        let long = "a".repeat(65);
+        let ok = "a".repeat(64);
+        for bad in [
+            format!("img@sha256:{short}"),
+            format!("img@sha256:{long}"),
+            format!("img@sha512:{ok}"),
+            format!("img@{ok}"),
+            format!("img@sha256:{}", "g".repeat(64)),
+            format!("img@sha256:{ok}@sha256:{ok}"),
+            format!("@sha256:{ok}"),
+        ] {
+            assert!(parse(&bad).is_err(), "accepted {bad:?}");
+        }
+    }
+
+    /// Parsing has no fallback (the schema default is a UI prefill, not a
+    /// parse-time substitute), so an absent image is an error that names the
+    /// field rather than a silent fallback.
+    #[test]
+    fn empty_reference_names_the_field() {
+        for empty in ["", "   "] {
+            let err = parse(empty).unwrap_err();
+            assert!(err.contains("provider_config.image"), "got: {err}");
+        }
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/intent.rs b/crates/buzz-backend-kubernetes/src/intent.rs
new file mode 100644
index 0000000000..73218f83bf
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/intent.rs
@@ -0,0 +1,309 @@
+//! The create-intent fingerprint (spec §Deploy State Machine, create-intent
+//! fingerprint, `docs/remote-agents.md:796-828`).
+//!
+//! The fingerprint is an unkeyed SHA-256 over a canonical serialization of the
+//! provider's non-secret create-intent template. A plain hash is safe *only*
+//! because of the scope rule: the input covers exactly the provider-controlled
+//! fields that can affect scheduling or container creation, and **never Secret
+//! data or attempt identity**. Hashing low-entropy secrets into a
+//! world-readable annotation would be a dictionary oracle.
+//!
+//! That rule is enforced structurally rather than remembered. [`IntentTemplate`]
+//! is a *pre-binding* type: it has no field that can hold Secret material or a
+//! generation token, so there is no expression that hashes one. The
+//! per-attempt Secret name never appears — the pod's `envFrom` is represented
+//! by the fixed [`SECRET_PLACEHOLDER`], because otherwise every attempt would
+//! diverge from every other by construction.
+//!
+//! Server- and admission-produced output (UID, `resourceVersion`, timestamps,
+//! defaulted fields, the annotation itself) is excluded the same way: the
+//! serializer is only ever handed this template, never a live `Pod`, so the
+//! exclusion is checkable by inspection.
+
+use crate::image::ImageRef;
+use serde::Serialize;
+use sha2::{Digest, Sha256};
+
+/// Stands in for the per-attempt Secret name in the `envFrom` position.
+/// A real generation token here would make every attempt diverge.
+const SECRET_PLACEHOLDER: &str = "<per-attempt-secret>";
+
+/// The recorded/computed create intent: a hex SHA-256 digest.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Fingerprint(String);
+
+impl Fingerprint {
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    /// Read a fingerprint off a pod annotation. Any recorded string is
+    /// accepted verbatim: comparison is equality against a freshly computed
+    /// value, so a malformed annotation simply reads as divergence — which is
+    /// the correct outcome for a pod this provider version did not write.
+    pub fn from_annotation(value: &str) -> Self {
+        Self(value.to_string())
+    }
+
+    #[cfg(test)]
+    pub fn for_test(seed: &str) -> Self {
+        Self(format!("test-{seed}"))
+    }
+}
+
+impl std::fmt::Display for Fingerprint {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+/// The non-secret, pre-binding description of the pod this deploy would
+/// create. Every field is provider-controlled and scheduling-relevant; there
+/// is deliberately no field for env values, Secret data, or the generation.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct IntentTemplate {
+    /// Schema version of the template itself. Bumping it re-fingerprints every
+    /// pod, which is the intended way to roll out a pod-shape change.
+    pub template_version: u32,
+    pub namespace: String,
+    /// Normalized, digest-qualified image reference.
+    pub image: String,
+    pub cpu_request: String,
+    pub memory_request: String,
+    pub cpu_limit: String,
+    pub memory_limit: String,
+    pub service_account: Option<String>,
+    pub restart_policy: &'static str,
+    pub termination_grace_period_seconds: i64,
+    /// Env *keys* only, sorted. Keys are pod-shape (a renamed key changes the
+    /// container's contract); values are Secret material and must not be here.
+    pub env_keys: Vec<String>,
+    /// Fixed placeholder for the per-attempt Secret in `envFrom`.
+    pub env_from_secret: &'static str,
+    pub workspace_mount_path: String,
+    pub run_as_user: i64,
+    pub run_as_group: i64,
+}
+
+/// Current template schema version.
+pub const TEMPLATE_VERSION: u32 = 1;
+
+impl IntentTemplate {
+    /// Compute the fingerprint. `serde_json` on a struct with declared field
+    /// order plus pre-sorted `env_keys` is a canonical serialization: the same
+    /// template always produces the same bytes.
+    pub fn fingerprint(&self) -> Fingerprint {
+        let canonical = serde_json::to_vec(self).expect("intent template is plain data");
+        Fingerprint(hex::encode(Sha256::digest(&canonical)))
+    }
+
+    /// Build from resolved pod-shape inputs. `env_keys` is sorted here rather
+    /// than at the call site so key ordering can never leak into the digest.
+    ///
+    /// The fixed pod-shape constants are read from [`crate::config`] rather
+    /// than passed in: `pod::build_pod` stamps the pod from those same
+    /// constants, so the fingerprint cannot describe a pod shape different
+    /// from the one actually created. Threading them through as arguments
+    /// would make that agreement a thing to test instead of a thing that holds.
+    pub fn new(
+        namespace: &str,
+        image: &ImageRef,
+        resources: &crate::config::Resources,
+        service_account: Option<&str>,
+        env_keys: impl IntoIterator<Item = String>,
+    ) -> Self {
+        let mut env_keys: Vec<String> = env_keys.into_iter().collect();
+        env_keys.sort();
+        Self {
+            template_version: TEMPLATE_VERSION,
+            namespace: namespace.to_string(),
+            image: image.as_str().to_string(),
+            cpu_request: resources.cpu_request.clone(),
+            memory_request: resources.memory_request.clone(),
+            cpu_limit: resources.cpu_limit.clone(),
+            memory_limit: resources.memory_limit.clone(),
+            service_account: service_account.map(str::to_string),
+            restart_policy: crate::config::RESTART_POLICY,
+            termination_grace_period_seconds: crate::config::TERMINATION_GRACE_SECONDS,
+            env_keys,
+            env_from_secret: SECRET_PLACEHOLDER,
+            workspace_mount_path: crate::config::WORKSPACE_PATH.to_string(),
+            run_as_user: crate::config::RUN_AS_UID,
+            run_as_group: crate::config::RUN_AS_GID,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::Resources;
+
+    fn image(byte: char) -> ImageRef {
+        crate::image::parse(&format!(
+            "ghcr.io/block/buzz-sprig@sha256:{}",
+            byte.to_string().repeat(64)
+        ))
+        .unwrap()
+    }
+
+    fn template() -> IntentTemplate {
+        IntentTemplate::new(
+            "buzz-agents",
+            &image('a'),
+            &Resources::default(),
+            None,
+            ["BUZZ_RELAY_URL".to_string(), "GOOSE_MODE".to_string()],
+        )
+    }
+
+    #[test]
+    fn fingerprint_is_deterministic() {
+        assert_eq!(template().fingerprint(), template().fingerprint());
+    }
+
+    #[test]
+    fn fingerprint_is_hex_sha256() {
+        let fp = template().fingerprint();
+        assert_eq!(fp.as_str().len(), 64);
+        assert!(fp.as_str().chars().all(|c| c.is_ascii_hexdigit()));
+    }
+
+    /// Key *order* must not reach the digest, or two identical environments
+    /// built in different orders would look like a config change.
+    #[test]
+    fn env_key_order_does_not_affect_the_digest() {
+        let a = IntentTemplate::new(
+            "ns",
+            &image('a'),
+            &Resources::default(),
+            None,
+            ["A".to_string(), "B".to_string(), "C".to_string()],
+        );
+        let b = IntentTemplate::new(
+            "ns",
+            &image('a'),
+            &Resources::default(),
+            None,
+            ["C".to_string(), "A".to_string(), "B".to_string()],
+        );
+        assert_eq!(a.fingerprint(), b.fingerprint());
+    }
+
+    /// A mutation applied to a fresh template clone, named for its assertion
+    /// message.
+    type Mutation = (&'static str, Box<dyn Fn(&mut IntentTemplate)>);
+
+    /// Every scheduling-relevant knob must move the digest — this is the
+    /// wedge escape (§Deploy State Machine never-started recoverable row).
+    /// Exhaustive by construction: each mutation is applied to a fresh clone.
+    #[test]
+    fn every_scheduling_field_changes_the_digest() {
+        let base = template();
+        let baseline = base.fingerprint();
+
+        let mutations: Vec<Mutation> = vec![
+            (
+                "template_version",
+                Box::new(|t: &mut IntentTemplate| t.template_version += 1),
+            ),
+            (
+                "namespace",
+                Box::new(|t: &mut IntentTemplate| t.namespace = "other".into()),
+            ),
+            (
+                "image",
+                Box::new(|t: &mut IntentTemplate| t.image = image('b').as_str().into()),
+            ),
+            (
+                "cpu_request",
+                Box::new(|t: &mut IntentTemplate| t.cpu_request = "4".into()),
+            ),
+            (
+                "memory_request",
+                Box::new(|t: &mut IntentTemplate| t.memory_request = "8Gi".into()),
+            ),
+            (
+                "cpu_limit",
+                Box::new(|t: &mut IntentTemplate| t.cpu_limit = "8".into()),
+            ),
+            (
+                "memory_limit",
+                Box::new(|t: &mut IntentTemplate| t.memory_limit = "16Gi".into()),
+            ),
+            (
+                "service_account",
+                Box::new(|t: &mut IntentTemplate| t.service_account = Some("sa".into())),
+            ),
+            (
+                "restart_policy",
+                Box::new(|t: &mut IntentTemplate| t.restart_policy = "OnFailure"),
+            ),
+            (
+                "grace_period",
+                Box::new(|t: &mut IntentTemplate| t.termination_grace_period_seconds = 30),
+            ),
+            (
+                "env_keys",
+                Box::new(|t: &mut IntentTemplate| t.env_keys.push("NEW_KEY".into())),
+            ),
+            (
+                "workspace_mount_path",
+                Box::new(|t: &mut IntentTemplate| t.workspace_mount_path = "/w".into()),
+            ),
+            (
+                "run_as_user",
+                Box::new(|t: &mut IntentTemplate| t.run_as_user = 2000),
+            ),
+            (
+                "run_as_group",
+                Box::new(|t: &mut IntentTemplate| t.run_as_group = 2000),
+            ),
+        ];
+
+        for (name, mutate) in mutations {
+            let mut t = base.clone();
+            mutate(&mut t);
+            assert_ne!(
+                t.fingerprint(),
+                baseline,
+                "{name} did not affect the digest"
+            );
+        }
+    }
+
+    /// The scope rule, asserted on the bytes: no Secret value and no
+    /// generation token can appear in the serialization, because the type has
+    /// nowhere to put them. The placeholder is what `envFrom` contributes.
+    #[test]
+    fn serialization_contains_no_secret_material_or_attempt_identity() {
+        let json = serde_json::to_string(&template()).unwrap();
+        for forbidden in ["nsec1", "SPOOFED", "wss://", "gen0001"] {
+            assert!(
+                !json.contains(forbidden),
+                "template leaked {forbidden}: {json}"
+            );
+        }
+        assert!(json.contains(SECRET_PLACEHOLDER));
+    }
+
+    /// Two attempts for the same agent differ only in generation, which is
+    /// absent from the template — so their fingerprints must be equal, or the
+    /// divergence discriminator would fire on every single deploy.
+    #[test]
+    fn attempts_differing_only_by_generation_do_not_diverge() {
+        // There is no generation input to pass; that *is* the property. The
+        // test states it explicitly so a future field addition breaks here.
+        assert_eq!(template().fingerprint(), template().fingerprint());
+        let json = serde_json::to_string(&template()).unwrap();
+        assert_eq!(json.matches(SECRET_PLACEHOLDER).count(), 1);
+    }
+
+    /// A recorded annotation this provider version did not write reads as
+    /// divergence rather than an error.
+    #[test]
+    fn unrecognized_annotation_reads_as_divergence() {
+        let recorded = Fingerprint::from_annotation("not-a-digest");
+        assert_ne!(recorded, template().fingerprint());
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/main.rs b/crates/buzz-backend-kubernetes/src/main.rs
new file mode 100644
index 0000000000..5d521a9d37
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/main.rs
@@ -0,0 +1,199 @@
+//! Kubernetes backend provider for Buzz remote agents
+//! (spec `docs/remote-agents.md`).
+//!
+//! One process per operation: read exactly one JSON request from stdin, write
+//! exactly one JSON response to stdout, exit. The exit code carries exactly
+//! one bit — 0 for a response that was produced, 1 for a failure to produce
+//! one. Everything a caller needs to distinguish is *inside* the response's
+//! `ok` field, because a provider that encoded outcomes in exit codes would
+//! have a second, redundant error channel to keep in sync (§Provider Protocol).
+
+mod classify;
+mod client;
+mod cluster;
+mod config;
+mod env;
+mod gc;
+mod image;
+mod intent;
+mod naming;
+mod observe;
+mod pod;
+mod reconcile;
+mod wire;
+
+use std::io::Read;
+use wire::{Request, Response};
+
+/// The provider a shared-compute agent resolves to. Refused here as the
+/// spec's backstop: a mesh agent runs on the relay's compute, so deploying it
+/// as a pod would create a second, contending consumer of the same agent
+/// identity (`:214-219`).
+const RELAY_MESH_PROVIDER: &str = "relay-mesh";
+
+fn main() {
+    // rustls needs a process-level provider before the first TLS connection.
+    // The release build compiles every sidecar in one cargo invocation, which
+    // unifies the `ring` and `aws-lc-rs` features and leaves rustls unable to
+    // auto-select — so this is an explicit install, not a default.
+    let _ = rustls::crypto::ring::default_provider().install_default();
+
+    let mut input = String::new();
+    if let Err(e) = std::io::stdin().read_to_string(&mut input) {
+        // No request means no request_id and no response contract to honor.
+        // This is the one path that exits nonzero.
+        eprintln!("could not read the request from stdin: {e}");
+        std::process::exit(1);
+    }
+
+    let response = respond(&input);
+    println!(
+        "{}",
+        serde_json::to_string(&response).unwrap_or_else(|e| {
+            // The response types are plain data; this cannot fail in practice,
+            // and a hand-built object is still a conforming response.
+            format!(r#"{{"ok":false,"error":"could not serialize a response: {e}"}}"#)
+        })
+    );
+}
+
+/// Produce the single response for one request. Separated from `main` so the
+/// whole dispatch is testable without a process.
+fn respond(input: &str) -> Response {
+    // Parsed as raw JSON first: the relay-mesh refusal below MUST see the wire
+    // value, and `AgentPayload` deliberately does not carry `provider`.
+    let raw: serde_json::Value = match serde_json::from_str(input) {
+        Ok(value) => value,
+        Err(e) => return Response::error(format!("request is not valid JSON: {e}")),
+    };
+
+    if let Some(refusal) = refuse_relay_mesh(&raw) {
+        return Response::error(refusal);
+    }
+
+    let request: Request = match serde_json::from_value(raw) {
+        Ok(request) => request,
+        Err(e) => return Response::error(format!("could not understand the request: {e}")),
+    };
+
+    match request {
+        Request::Info => Response::info(),
+        Request::Deploy(deploy) => {
+            let runtime = match tokio::runtime::Builder::new_current_thread()
+                .enable_all()
+                .build()
+            {
+                Ok(runtime) => runtime,
+                Err(e) => return Response::error(format!("could not start the runtime: {e}")),
+            };
+            match runtime.block_on(deploy_agent(&deploy)) {
+                Ok(agent_id) => Response::deployed(agent_id),
+                Err(e) => Response::error(e),
+            }
+        }
+    }
+}
+
+/// Refuse a shared-compute agent, reading the **raw wire value**.
+///
+/// Trimmed before comparing: the desktop's own layers disagree about padding
+/// (`relay_mesh.rs:17` and `effective_config/mod.rs:46` trim; the deploy guard
+/// at `agents_deploy.rs:116` did not), and `non_blank` preserves surrounding
+/// whitespace on a non-blank value. A backstop that shares its bypass with the
+/// layer it backs is not a backstop.
+fn refuse_relay_mesh(raw: &serde_json::Value) -> Option<String> {
+    let provider = raw.get("agent")?.get("provider")?.as_str()?;
+    (provider.trim() == RELAY_MESH_PROVIDER).then(|| {
+        "deploy refused: this agent is configured for shared compute \
+         (relay-mesh), which runs on the relay rather than in a pod. \
+         Switch the agent to a local runtime before deploying it to \
+         Kubernetes."
+            .to_string()
+    })
+}
+
+/// Run one deploy to a terminal outcome.
+async fn deploy_agent(request: &wire::DeployRequest) -> Result<String, String> {
+    let cfg = config::parse(&request.provider_config)?;
+    // Identity before any cluster contact: a malformed nsec is a refusal, not
+    // a failed connection (§Deploy State Machine step 0).
+    let identity = naming::AgentIdentity::from_nsec(&request.agent.private_key_nsec)?;
+
+    // One generation for this operation's first attempt; the reconciler mints
+    // its own per attempt and restamps the correlator to match.
+    let env = env::build_env(
+        &request.agent,
+        env::AuthoritativeInputs {
+            generation: &naming::new_generation(),
+            inactivity_seconds: cfg.inactivity_seconds,
+        },
+    )?;
+
+    let client = client::connect(cfg.context.as_deref()).await?;
+    let substrate = cluster::Cluster::new(client, &cfg.namespace);
+    reconcile::deploy(&substrate, &identity, &cfg, env).await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn error_of(response: &Response) -> String {
+        let json = serde_json::to_value(response).unwrap();
+        assert_eq!(json["ok"], false, "expected a refusal: {json}");
+        json["error"].as_str().unwrap().to_string()
+    }
+
+    /// The spec's backstop for the relay-mesh MUST. The desktop refuses first
+    /// (`agents_deploy.rs:116`); this is the layer that owes the obligation.
+    #[test]
+    fn refuses_a_relay_mesh_agent() {
+        let request = r#"{"op":"deploy","agent":{
+            "relay_url":"wss://r","private_key_nsec":"nsec1x","provider":"relay-mesh"},
+            "provider_config":{"namespace":"ns"}}"#;
+        assert!(error_of(&respond(request)).contains("relay-mesh"));
+    }
+
+    /// Padding must not bypass the backstop. Reachable by construction:
+    /// `GlobalConfig.provider` is a bare `Option<String>` with no trim on
+    /// write, and `non_blank` rejects whitespace-only while preserving
+    /// surrounding whitespace on everything else.
+    #[test]
+    fn refuses_a_padded_relay_mesh_agent() {
+        let request = r#"{"op":"deploy","agent":{
+            "relay_url":"wss://r","private_key_nsec":"nsec1x","provider":"  relay-mesh  "},
+            "provider_config":{"namespace":"ns"}}"#;
+        assert!(error_of(&respond(request)).contains("relay-mesh"));
+    }
+
+    /// The refusal must not fire on a normal agent — a guard that refuses
+    /// everything passes its own test and ships a provider that deploys
+    /// nothing.
+    #[test]
+    fn does_not_refuse_a_normal_provider() {
+        let raw: serde_json::Value =
+            serde_json::from_str(r#"{"agent":{"provider":"openai"}}"#).unwrap();
+        assert!(refuse_relay_mesh(&raw).is_none());
+        // …nor when the field is absent entirely, which is the common case:
+        // `AgentPayload` does not carry `provider`.
+        let bare: serde_json::Value = serde_json::from_str(r#"{"agent":{}}"#).unwrap();
+        assert!(refuse_relay_mesh(&bare).is_none());
+    }
+
+    /// Malformed input still produces exactly one conforming response.
+    #[test]
+    fn malformed_input_is_an_in_band_error() {
+        assert!(error_of(&respond("not json")).contains("valid JSON"));
+        assert!(error_of(&respond(r#"{"op":"undeploy"}"#)).contains("understand"));
+    }
+
+    /// `info` answers without touching a cluster — it is what the desktop
+    /// calls to render the config form, before any kubeconfig exists.
+    #[test]
+    fn info_answers_with_the_protocol_version_and_schema() {
+        let json = serde_json::to_value(respond(r#"{"op":"info"}"#)).unwrap();
+        assert_eq!(json["ok"], true);
+        assert_eq!(json["protocol_version"], wire::PROTOCOL_VERSION);
+        assert!(json["config_schema"]["properties"]["namespace"].is_object());
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/naming.rs b/crates/buzz-backend-kubernetes/src/naming.rs
new file mode 100644
index 0000000000..4b9d7ea035
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/naming.rs
@@ -0,0 +1,223 @@
+//! Identity derivation and the object-naming contract (spec §Pod shape).
+//!
+//! Every name, label, and annotation below is derived from the pubkey the
+//! provider decoded itself from `private_key_nsec` — never from a
+//! caller-supplied pubkey (§Deploy State Machine step 0).
+
+use nostr::nips::nip19::FromBech32;
+
+/// `app.kubernetes.io/managed-by` value: the management marker's identity half.
+pub const MANAGED_BY: &str = "buzz-backend-kubernetes";
+
+/// Label key carrying [`MANAGED_BY`].
+pub const LABEL_MANAGED_BY: &str = "app.kubernetes.io/managed-by";
+
+/// Label key carrying [`BINDING_VERSION`] — the marker's schema half.
+pub const LABEL_BINDING_VERSION: &str = "buzz.block.xyz/binding-version";
+
+/// Schema version of the object layout this provider writes. Bumped when the
+/// pod/Secret shape changes in a way a older provider would mis-handle.
+pub const BINDING_VERSION: &str = "1";
+
+/// Label key: truncated pubkey, the reconciliation and GC selector.
+pub const LABEL_AGENT_PUBKEY: &str = "buzz.block.xyz/agent-pubkey";
+
+/// Annotation key: full pubkey. Load-bearing — the truncated label is
+/// collision-*resistant*, this is what makes it safe (§Deploy State Machine
+/// step 1).
+pub const ANNOTATION_PUBKEY_FULL: &str = "buzz.block.xyz/agent-pubkey-full";
+
+/// Annotation key: the recorded create-intent fingerprint.
+pub const ANNOTATION_CREATE_INTENT: &str = "buzz.block.xyz/create-intent";
+
+/// Annotation key: the image reference this generation actually resolved to,
+/// for post-hoc attribution (§Image).
+pub const ANNOTATION_IMAGE: &str = "buzz.block.xyz/image";
+
+/// An agent identity the provider derived itself, plus every name it implies.
+///
+/// Constructing this type is the *only* way to obtain the names — so a
+/// caller-supplied pubkey cannot reach a selector by any path.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AgentIdentity {
+    pubkey_hex: String,
+}
+
+impl AgentIdentity {
+    /// Derive from the payload's `private_key_nsec`.
+    ///
+    /// Accepts bech32 `nsec1…`; a malformed or undecodable key is an
+    /// immediate error, before any substrate read or mutation
+    /// (§Deploy State Machine step 0).
+    pub fn from_nsec(nsec: &str) -> Result<Self, String> {
+        let secret = nostr::SecretKey::from_bech32(nsec.trim())
+            .map_err(|_| "private_key_nsec is not a decodable nsec1 key".to_string())?;
+        let keys = nostr::Keys::new(secret);
+        Ok(Self {
+            pubkey_hex: keys.public_key().to_hex(),
+        })
+    }
+
+    /// Full 64-hex public key — the annotation value and the comparison
+    /// operand for candidate authentication.
+    pub fn pubkey_hex(&self) -> &str {
+        &self.pubkey_hex
+    }
+
+    /// Selector label value: first 32 hex chars (128 bits). A full hex pubkey
+    /// is 64 chars and label values cap at 63, which is why this is truncated
+    /// and why the annotation check is normative rather than decorative.
+    pub fn label_pubkey(&self) -> &str {
+        &self.pubkey_hex[..32]
+    }
+
+    /// Deterministic pod name, also the returned `agent_id`.
+    pub fn pod_name(&self) -> String {
+        format!("buzz-agent-{}", &self.pubkey_hex[..12])
+    }
+
+    /// Per-attempt Secret name. `generation` is a fresh random token per
+    /// create attempt — never reused — which is what makes payload and Secret
+    /// atomic at the pod-spec boundary (§K8s Secrets).
+    pub fn secret_name(&self, generation: &str) -> String {
+        format!("buzz-agent-{}-{}", &self.pubkey_hex[..12], generation)
+    }
+
+    /// Label selector matching this identity's objects *and* our management
+    /// marker. Selecting on the marker as well as the identity means an
+    /// unmarked look-alike never even enters the candidate list.
+    pub fn selector(&self) -> String {
+        format!(
+            "{LABEL_AGENT_PUBKEY}={},{LABEL_MANAGED_BY}={MANAGED_BY}",
+            self.label_pubkey()
+        )
+    }
+
+    /// The label set stamped on every object this provider creates.
+    pub fn labels(&self) -> std::collections::BTreeMap<String, String> {
+        [
+            (
+                LABEL_AGENT_PUBKEY.to_string(),
+                self.label_pubkey().to_string(),
+            ),
+            (LABEL_MANAGED_BY.to_string(), MANAGED_BY.to_string()),
+            (
+                LABEL_BINDING_VERSION.to_string(),
+                BINDING_VERSION.to_string(),
+            ),
+        ]
+        .into_iter()
+        .collect()
+    }
+}
+
+/// A fresh generation token: 8 lowercase hex chars from the OS RNG.
+///
+/// Appears in the Secret name and as `BUZZ_MANAGED_AGENT_START_NONCE`, so the
+/// Secret generation and the harness's lifecycle-frame correlator are one
+/// identity (§Launch data tier 3).
+pub fn new_generation() -> String {
+    use rand::RngExt;
+    let n: u32 = rand::rng().random();
+    format!("{n:08x}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// A fixed test key. Deriving the pubkey (rather than hardcoding both
+    /// halves) is the point: the test exercises the same derivation the
+    /// reconciler depends on.
+    fn identity() -> AgentIdentity {
+        let keys = nostr::Keys::generate();
+        let nsec = {
+            use nostr::nips::nip19::ToBech32;
+            keys.secret_key().to_bech32().unwrap()
+        };
+        let id = AgentIdentity::from_nsec(&nsec).unwrap();
+        assert_eq!(id.pubkey_hex(), keys.public_key().to_hex());
+        id
+    }
+
+    #[test]
+    fn rejects_malformed_nsec() {
+        for bad in ["", "nsec1", "not-a-key", "npub1abc"] {
+            assert!(
+                AgentIdentity::from_nsec(bad).is_err(),
+                "accepted malformed key {bad:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn tolerates_surrounding_whitespace() {
+        let keys = nostr::Keys::generate();
+        use nostr::nips::nip19::ToBech32;
+        let nsec = keys.secret_key().to_bech32().unwrap();
+        let padded = format!("  {nsec}\n");
+        assert_eq!(
+            AgentIdentity::from_nsec(&padded).unwrap().pubkey_hex(),
+            keys.public_key().to_hex()
+        );
+    }
+
+    /// Kubernetes label *values* cap at 63 chars; a full hex pubkey is 64,
+    /// one over. That one-char overflow is the whole reason the selector is
+    /// truncated, so it gets an explicit test.
+    #[test]
+    fn label_value_fits_kubernetes_limit() {
+        let id = identity();
+        assert_eq!(id.pubkey_hex().len(), 64);
+        assert_eq!(id.label_pubkey().len(), 32);
+        assert!(id.label_pubkey().len() <= 63);
+    }
+
+    #[test]
+    fn pod_name_is_deterministic_and_dns_safe() {
+        let id = identity();
+        assert_eq!(id.pod_name(), id.pod_name());
+        assert_eq!(
+            id.pod_name(),
+            format!("buzz-agent-{}", &id.pubkey_hex()[..12])
+        );
+        assert!(id.pod_name().len() <= 253);
+        assert!(id
+            .pod_name()
+            .chars()
+            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-'));
+    }
+
+    /// Two attempts must never share a Secret name — that uniqueness is what
+    /// stops a losing contender from overwriting the winner's identity.
+    #[test]
+    fn secret_names_are_per_attempt() {
+        let id = identity();
+        let a = id.secret_name(&new_generation());
+        let b = id.secret_name(&new_generation());
+        assert_ne!(a, b);
+        assert!(a.starts_with(&id.pod_name()));
+        assert!(a.len() <= 253);
+    }
+
+    #[test]
+    fn selector_requires_the_management_marker() {
+        let id = identity();
+        let sel = id.selector();
+        assert!(sel.contains(&format!("{LABEL_AGENT_PUBKEY}={}", id.label_pubkey())));
+        assert!(sel.contains(&format!("{LABEL_MANAGED_BY}={MANAGED_BY}")));
+    }
+
+    #[test]
+    fn every_created_object_carries_the_marker() {
+        let labels = identity().labels();
+        assert_eq!(
+            labels.get(LABEL_MANAGED_BY).map(String::as_str),
+            Some(MANAGED_BY)
+        );
+        assert_eq!(
+            labels.get(LABEL_BINDING_VERSION).map(String::as_str),
+            Some(BINDING_VERSION)
+        );
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/observe.rs b/crates/buzz-backend-kubernetes/src/observe.rs
new file mode 100644
index 0000000000..1c6c883563
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/observe.rs
@@ -0,0 +1,592 @@
+//! Decoding API objects into verified observations (spec §Deploy State
+//! Machine step 1).
+//!
+//! Pure: `Pod` in, [`VerifiedPod`] out. Keeping the decode here means the
+//! conformance tests drive the *shipped* decoder with real API types rather
+//! than a test-only stand-in, and it keeps `classify.rs` free of API types.
+//!
+//! Verification is the gate, not a filter: [`verify`] returns `None` for any
+//! object whose full-pubkey annotation does not equal the derived pubkey or
+//! that lacks the management marker, so an unverified object cannot reach
+//! classification, deletion, or the returned `agent_id`.
+
+use crate::classify::{Fence, PullFailure, Startup, VerifiedPod};
+use crate::intent::Fingerprint;
+use crate::naming::{
+    AgentIdentity, ANNOTATION_CREATE_INTENT, ANNOTATION_PUBKEY_FULL, BINDING_VERSION,
+    LABEL_BINDING_VERSION, LABEL_MANAGED_BY, MANAGED_BY,
+};
+use k8s_openapi::api::core::v1::{Pod, Secret};
+
+/// Container name the provider creates; status is read from this container.
+pub const CONTAINER_NAME: &str = "agent";
+
+/// The startup state, or a state that cannot be settled without one more read.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum StartupObservation {
+    Resolved(Startup),
+    /// `CreateContainerConfigError` — recoverable *unless* the referenced
+    /// Secret is confirmed absent by a most-recent read. The kubelet's reason
+    /// string is a hint; the provider verifies before treating it as fatal
+    /// (§Deploy State Machine: "provably" means a verified absence, never a
+    /// reason string).
+    ConfigErrorPendingSecretCheck {
+        secret_name: String,
+    },
+}
+
+/// Does this object carry the management marker (§Pod shape)?
+///
+/// Identity labels prove identity; the marker asserts protocol ownership.
+/// Without it an object that merely matches our schema fails closed.
+fn has_marker(labels: Option<&std::collections::BTreeMap<String, String>>) -> bool {
+    let Some(labels) = labels else { return false };
+    labels.get(LABEL_MANAGED_BY).map(String::as_str) == Some(MANAGED_BY)
+        && labels.get(LABEL_BINDING_VERSION).map(String::as_str) == Some(BINDING_VERSION)
+}
+
+/// Does the full-pubkey annotation equal the derived pubkey?
+///
+/// The 32-hex label is collision-*resistant*, not collision-free, which is
+/// why this check is normative rather than decorative (`:1152-1166`).
+fn annotation_matches(
+    annotations: Option<&std::collections::BTreeMap<String, String>>,
+    identity: &AgentIdentity,
+) -> bool {
+    annotations
+        .and_then(|a| a.get(ANNOTATION_PUBKEY_FULL))
+        .map(|v| v == identity.pubkey_hex())
+        .unwrap_or(false)
+}
+
+/// Is this Secret ours and this identity's? The same fence GC applies before
+/// deleting anything.
+pub fn secret_is_ours(secret: &Secret, identity: &AgentIdentity) -> bool {
+    has_marker(secret.metadata.labels.as_ref())
+        && annotation_matches(secret.metadata.annotations.as_ref(), identity)
+}
+
+/// Decode a pod's startup state from its status.
+///
+/// "Started" means `state.running` on our container — not pod phase. A pod can
+/// sit in phase `Running` with a container that never started, and a pod being
+/// gracefully deleted stays in phase `Running` for its whole grace period.
+pub fn decode_startup(pod: &Pod) -> StartupObservation {
+    use StartupObservation::Resolved;
+
+    let status = pod.status.as_ref();
+    let phase = status.and_then(|s| s.phase.as_deref());
+
+    let container = status
+        .and_then(|s| s.container_statuses.as_ref())
+        .and_then(|cs| cs.iter().find(|c| c.name == CONTAINER_NAME));
+
+    if let Some(state) = container.and_then(|c| c.state.as_ref()) {
+        if state.running.is_some() {
+            return Resolved(Startup::Started);
+        }
+        if state.terminated.is_some() {
+            return Resolved(Startup::Terminated);
+        }
+        if let Some(waiting) = state.waiting.as_ref() {
+            let reason = waiting.reason.as_deref().unwrap_or_default();
+            let message = waiting.message.as_deref().unwrap_or_default();
+            return match reason {
+                // Structurally invalid reference: no retry can fix it.
+                "InvalidImageName" => Resolved(Startup::NeverStartedProvablyBroken),
+                "ErrImagePull" | "ImagePullBackOff" => match classify_pull_failure(message) {
+                    Some(failure) => Resolved(Startup::NeverStartedPullFailing(failure)),
+                    None => Resolved(Startup::NeverStartedRecoverable),
+                },
+                "CreateContainerConfigError" => match referenced_secret(pod) {
+                    Some(secret_name) => {
+                        StartupObservation::ConfigErrorPendingSecretCheck { secret_name }
+                    }
+                    None => Resolved(Startup::NeverStartedRecoverable),
+                },
+                _ => Resolved(Startup::NeverStartedRecoverable),
+            };
+        }
+    }
+
+    // No container status yet (unscheduled, image pulling before the kubelet
+    // reports, quota-blocked). A terminal phase without container status still
+    // means the pod is done.
+    match phase {
+        Some("Succeeded") | Some("Failed") => Resolved(Startup::Terminated),
+        _ => Resolved(Startup::NeverStartedRecoverable),
+    }
+}
+
+/// The Secret name this pod's `envFrom` references, if any.
+pub fn referenced_secret(pod: &Pod) -> Option<String> {
+    pod.spec
+        .as_ref()?
+        .containers
+        .iter()
+        .flat_map(|c| c.env_from.iter().flatten())
+        .find_map(|source| source.secret_ref.as_ref().map(|r| r.name.clone()))
+}
+
+/// Classify a pull failure from the kubelet's message.
+///
+/// Reporting only — [`PullFailure`] is structurally excluded from
+/// `Action::Delete`, so a wrong guess here can delay a report but can never
+/// destroy anything. `None` means "no permanent cause recognized", which
+/// leaves the pod on the ordinary observational path.
+fn classify_pull_failure(message: &str) -> Option<PullFailure> {
+    let m = message.to_ascii_lowercase();
+    if m.contains("401")
+        || m.contains("unauthorized")
+        || m.contains("403")
+        || m.contains("denied")
+        || m.contains("authentication required")
+    {
+        return Some(PullFailure::Unauthorized);
+    }
+    if m.contains("manifest unknown")
+        || m.contains("not found")
+        || m.contains("manifest_unknown")
+        || m.contains("repository does not exist")
+    {
+        return Some(PullFailure::ManifestUnknown);
+    }
+    if m.contains("no match for platform") || m.contains("no matching manifest") {
+        return Some(PullFailure::ArchMismatch);
+    }
+    None
+}
+
+/// The redacted, actionable condition text for a pull failure.
+///
+/// Names the registry and the immutable reference — never credentials, and
+/// never the kubelet's raw message, which can echo a registry token.
+pub fn pull_failure_message(failure: PullFailure, image: &str) -> String {
+    let registry = image.split('/').next().unwrap_or(image);
+    match failure {
+        PullFailure::Unauthorized => format!(
+            "the cluster is not authorized to pull {image} from {registry}. \
+             This pull retries indefinitely and will not succeed on its own: \
+             grant the cluster's nodes access to that registry."
+        ),
+        PullFailure::ManifestUnknown => {
+            format!("{registry} has no image at {image}. Check the digest and repository.")
+        }
+        PullFailure::ArchMismatch => format!(
+            "{image} has no variant for the architecture of the nodes it was \
+             scheduled on."
+        ),
+    }
+}
+
+/// The latest actionable condition for a pod that has not started, redacted.
+///
+/// Two sources, deliberately treated differently:
+///
+/// * The container's waiting **reason** is included; its **message** is not.
+///   Waiting messages are kubelet-composed and echo the thing that failed —
+///   for a pull that is the registry request, which can carry credential
+///   material. The reason token alone (`ImagePullBackOff`,
+///   `CreateContainerConfigError`) is the diagnostic; the message adds
+///   exposure, not information the user can act on.
+/// * Pod-condition messages **are** included. They are scheduler- and
+///   kubelet-composed from the pod's own spec and cluster capacity
+///   ("0/3 nodes are available: Insufficient memory"), which is precisely the
+///   actionable half and contains nothing derived from Secret data.
+pub fn condition(pod: &Pod) -> Option<String> {
+    let status = pod.status.as_ref()?;
+
+    if let Some(state) = status
+        .container_statuses
+        .as_ref()
+        .and_then(|cs| cs.iter().find(|c| c.name == CONTAINER_NAME))
+        .and_then(|c| c.state.as_ref())
+    {
+        if let Some(waiting) = state.waiting.as_ref() {
+            if let Some(reason) = waiting.reason.as_deref() {
+                return Some(format!("the container is waiting, reason {reason}"));
+            }
+        }
+        // Exit code and reason only — the terminated `message` is
+        // process-composed output and falls under the same redaction rule as
+        // waiting messages.
+        if let Some(terminated) = state.terminated.as_ref() {
+            return Some(match terminated.reason.as_deref() {
+                Some(reason) => format!(
+                    "the container exited with code {} ({reason})",
+                    terminated.exit_code
+                ),
+                None => format!("the container exited with code {}", terminated.exit_code),
+            });
+        }
+    }
+
+    if let Some((type_, reason, message)) = status.conditions.as_ref().and_then(|cs| {
+        cs.iter().find(|c| c.status == "False").map(|c| {
+            (
+                c.type_.clone(),
+                c.reason.clone().unwrap_or_default(),
+                c.message.clone().unwrap_or_default(),
+            )
+        })
+    }) {
+        let detail = [reason, message]
+            .into_iter()
+            .filter(|s| !s.is_empty())
+            .collect::<Vec<_>>()
+            .join(": ");
+        return Some(if detail.is_empty() {
+            format!("pod condition {type_} is false")
+        } else {
+            format!("pod condition {type_} is false: {detail}")
+        });
+    }
+
+    status.phase.as_deref().map(|p| format!("the pod is {p}"))
+}
+
+/// Verify a label-selected pod and decode it, or reject it.
+///
+/// `startup` is supplied by the caller because settling
+/// `CreateContainerConfigError` needs a most-recent Secret read the pure layer
+/// must not perform.
+pub fn verify(pod: &Pod, identity: &AgentIdentity, startup: Startup) -> Option<VerifiedPod> {
+    if !has_marker(pod.metadata.labels.as_ref()) {
+        return None;
+    }
+    if !annotation_matches(pod.metadata.annotations.as_ref(), identity) {
+        return None;
+    }
+    Some(VerifiedPod {
+        name: pod.metadata.name.clone()?,
+        fence: Fence {
+            uid: pod.metadata.uid.clone()?,
+            resource_version: pod.metadata.resource_version.clone()?,
+        },
+        deletion_marked: pod.metadata.deletion_timestamp.is_some(),
+        startup,
+        recorded_intent: pod
+            .metadata
+            .annotations
+            .as_ref()
+            .and_then(|a| a.get(ANNOTATION_CREATE_INTENT))
+            .map(|v| Fingerprint::from_annotation(v)),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use k8s_openapi::api::core::v1::{
+        ContainerState, ContainerStateRunning, ContainerStateTerminated, ContainerStateWaiting,
+        ContainerStatus, PodStatus,
+    };
+    use k8s_openapi::apimachinery::pkg::apis::meta::v1::{ObjectMeta, Time};
+    use std::collections::BTreeMap;
+
+    fn identity() -> AgentIdentity {
+        use nostr::nips::nip19::ToBech32;
+        let keys = nostr::Keys::generate();
+        AgentIdentity::from_nsec(&keys.secret_key().to_bech32().unwrap()).unwrap()
+    }
+
+    fn base_pod(id: &AgentIdentity) -> Pod {
+        Pod {
+            metadata: ObjectMeta {
+                name: Some(id.pod_name()),
+                uid: Some("uid-1".into()),
+                resource_version: Some("100".into()),
+                labels: Some(id.labels()),
+                annotations: Some(
+                    [(
+                        ANNOTATION_PUBKEY_FULL.to_string(),
+                        id.pubkey_hex().to_string(),
+                    )]
+                    .into_iter()
+                    .collect::<BTreeMap<_, _>>(),
+                ),
+                ..Default::default()
+            },
+            ..Default::default()
+        }
+    }
+
+    fn with_container_state(mut pod: Pod, state: ContainerState) -> Pod {
+        pod.status = Some(PodStatus {
+            phase: Some("Running".into()),
+            container_statuses: Some(vec![ContainerStatus {
+                name: CONTAINER_NAME.into(),
+                state: Some(state),
+                ..Default::default()
+            }]),
+            ..Default::default()
+        });
+        pod
+    }
+
+    fn waiting(reason: &str, message: &str) -> ContainerState {
+        ContainerState {
+            waiting: Some(ContainerStateWaiting {
+                reason: Some(reason.into()),
+                message: Some(message.into()),
+            }),
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn running_container_is_started() {
+        let id = identity();
+        let pod = with_container_state(
+            base_pod(&id),
+            ContainerState {
+                running: Some(ContainerStateRunning::default()),
+                ..Default::default()
+            },
+        );
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::Resolved(Startup::Started)
+        );
+    }
+
+    /// Pod phase is not the criterion. A pod in phase `Running` whose
+    /// container never started must NOT read as started, or the reconciler
+    /// no-ops on a pod that will never serve.
+    #[test]
+    fn phase_running_with_waiting_container_is_not_started() {
+        let id = identity();
+        let pod = with_container_state(base_pod(&id), waiting("ContainerCreating", ""));
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::Resolved(Startup::NeverStartedRecoverable)
+        );
+    }
+
+    #[test]
+    fn terminated_container_is_terminated() {
+        let id = identity();
+        let pod = with_container_state(
+            base_pod(&id),
+            ContainerState {
+                terminated: Some(ContainerStateTerminated {
+                    exit_code: 0,
+                    ..Default::default()
+                }),
+                ..Default::default()
+            },
+        );
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::Resolved(Startup::Terminated)
+        );
+    }
+
+    /// A terminal phase with no container status (evicted before the kubelet
+    /// reported) is still terminated — otherwise the residue is never GC'd.
+    #[test]
+    fn terminal_phase_without_container_status_is_terminated() {
+        let id = identity();
+        for phase in ["Succeeded", "Failed"] {
+            let mut pod = base_pod(&id);
+            pod.status = Some(PodStatus {
+                phase: Some(phase.into()),
+                ..Default::default()
+            });
+            assert_eq!(
+                decode_startup(&pod),
+                StartupObservation::Resolved(Startup::Terminated),
+                "phase {phase}"
+            );
+        }
+    }
+
+    #[test]
+    fn invalid_image_name_is_provably_broken() {
+        let id = identity();
+        let pod = with_container_state(base_pod(&id), waiting("InvalidImageName", "bad ref"));
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::Resolved(Startup::NeverStartedProvablyBroken)
+        );
+    }
+
+    /// Permanent pull failures are recognized from the message; anything
+    /// unrecognized stays on the ordinary observational path rather than
+    /// being guessed at.
+    #[test]
+    fn permanent_pull_failures_are_classified() {
+        let id = identity();
+        let cases = [
+            ("401 Unauthorized", PullFailure::Unauthorized),
+            ("pull access denied", PullFailure::Unauthorized),
+            ("manifest unknown", PullFailure::ManifestUnknown),
+            (
+                "no match for platform in manifest",
+                PullFailure::ArchMismatch,
+            ),
+        ];
+        for (message, expected) in cases {
+            let pod = with_container_state(base_pod(&id), waiting("ErrImagePull", message));
+            assert_eq!(
+                decode_startup(&pod),
+                StartupObservation::Resolved(Startup::NeverStartedPullFailing(expected)),
+                "message {message:?}"
+            );
+        }
+
+        let pod = with_container_state(
+            base_pod(&id),
+            waiting("ImagePullBackOff", "dial tcp: i/o timeout"),
+        );
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::Resolved(Startup::NeverStartedRecoverable),
+            "a transient network failure must not be reported as permanent"
+        );
+    }
+
+    /// The kubelet's reason string is a hint, not proof: a config error defers
+    /// to a most-recent Secret read before anything is called broken.
+    #[test]
+    fn config_error_defers_to_a_secret_read() {
+        let id = identity();
+        let mut pod =
+            with_container_state(base_pod(&id), waiting("CreateContainerConfigError", ""));
+        pod.spec = Some(k8s_openapi::api::core::v1::PodSpec {
+            containers: vec![k8s_openapi::api::core::v1::Container {
+                name: CONTAINER_NAME.into(),
+                env_from: Some(vec![k8s_openapi::api::core::v1::EnvFromSource {
+                    secret_ref: Some(k8s_openapi::api::core::v1::SecretEnvSource {
+                        name: "buzz-agent-abc-gen1".into(),
+                        optional: Some(false),
+                    }),
+                    ..Default::default()
+                }]),
+                ..Default::default()
+            }],
+            ..Default::default()
+        });
+        assert_eq!(
+            decode_startup(&pod),
+            StartupObservation::ConfigErrorPendingSecretCheck {
+                secret_name: "buzz-agent-abc-gen1".into()
+            }
+        );
+    }
+
+    /// The auto-repair fence: an object that matches our schema but lacks the
+    /// marker, or carries someone else's pubkey, is never verified — so it can
+    /// never be no-op'd against, deleted, or returned as an `agent_id`.
+    #[test]
+    fn unmarked_or_mismatched_objects_fail_verification() {
+        let id = identity();
+        let other = identity();
+
+        let mut unmarked = base_pod(&id);
+        unmarked.metadata.labels = Some(BTreeMap::new());
+        assert!(
+            verify(&unmarked, &id, Startup::Started).is_none(),
+            "unmarked pod verified"
+        );
+
+        let mut wrong_version = base_pod(&id);
+        let mut labels = id.labels();
+        labels.insert(LABEL_BINDING_VERSION.to_string(), "999".to_string());
+        wrong_version.metadata.labels = Some(labels);
+        assert!(verify(&wrong_version, &id, Startup::Started).is_none());
+
+        let mut mismatched = base_pod(&id);
+        mismatched.metadata.annotations = Some(
+            [(
+                ANNOTATION_PUBKEY_FULL.to_string(),
+                other.pubkey_hex().to_string(),
+            )]
+            .into_iter()
+            .collect(),
+        );
+        assert!(
+            verify(&mismatched, &id, Startup::Started).is_none(),
+            "collision verified"
+        );
+
+        let mut missing = base_pod(&id);
+        missing.metadata.annotations = Some(BTreeMap::new());
+        assert!(verify(&missing, &id, Startup::Started).is_none());
+
+        assert!(
+            verify(&base_pod(&id), &id, Startup::Started).is_some(),
+            "own pod rejected"
+        );
+    }
+
+    /// The fence must come from the observed object, and the deletion mark
+    /// must be read even though the phase says `Running`.
+    #[test]
+    fn verified_pod_carries_the_fence_and_deletion_mark() {
+        let id = identity();
+        let mut pod = base_pod(&id);
+        pod.metadata.deletion_timestamp = Some(Time(chrono::Utc::now()));
+        let verified = verify(&pod, &id, Startup::Started).unwrap();
+        assert_eq!(verified.fence.uid, "uid-1");
+        assert_eq!(verified.fence.resource_version, "100");
+        assert!(verified.deletion_marked);
+    }
+
+    /// A pod with no recorded intent reads as `None`, which the classifier
+    /// groups with divergence.
+    #[test]
+    fn missing_intent_annotation_decodes_as_none() {
+        let id = identity();
+        assert!(verify(&base_pod(&id), &id, Startup::Started)
+            .unwrap()
+            .recorded_intent
+            .is_none());
+    }
+
+    /// A pull-failure report must name the registry and the immutable
+    /// reference and nothing else — never the kubelet's raw message, which
+    /// can echo a registry token.
+    #[test]
+    fn pull_failure_messages_are_actionable_and_redacted() {
+        let image = format!("ghcr.io/block/buzz-sprig@sha256:{}", "a".repeat(64));
+        for failure in [
+            PullFailure::Unauthorized,
+            PullFailure::ManifestUnknown,
+            PullFailure::ArchMismatch,
+        ] {
+            let msg = pull_failure_message(failure, &image);
+            assert!(msg.contains("ghcr.io"), "{msg}");
+            assert!(msg.contains(&image), "{msg}");
+            for secret in ["Bearer", "password", "nsec1", "token"] {
+                assert!(!msg.contains(secret), "leaked {secret}: {msg}");
+            }
+        }
+    }
+
+    #[test]
+    fn secret_ownership_requires_marker_and_annotation() {
+        let id = identity();
+        let other = identity();
+        let ours = Secret {
+            metadata: ObjectMeta {
+                labels: Some(id.labels()),
+                annotations: Some(
+                    [(
+                        ANNOTATION_PUBKEY_FULL.to_string(),
+                        id.pubkey_hex().to_string(),
+                    )]
+                    .into(),
+                ),
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+        assert!(secret_is_ours(&ours, &id));
+        assert!(!secret_is_ours(&ours, &other));
+
+        let mut unmarked = ours.clone();
+        unmarked.metadata.labels = Some(BTreeMap::new());
+        assert!(!secret_is_ours(&unmarked, &id));
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/pod.rs b/crates/buzz-backend-kubernetes/src/pod.rs
new file mode 100644
index 0000000000..725f98fc7d
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/pod.rs
@@ -0,0 +1,446 @@
+//! Pod and Secret construction (spec §Pod shape, §K8s Secrets).
+//!
+//! The builder is pure: it turns resolved inputs into API objects and performs
+//! no I/O, so every normative field is a unit assertion.
+
+use crate::config::{
+    ProviderConfig, RESTART_POLICY, RUN_AS_GID, RUN_AS_UID, TERMINATION_GRACE_SECONDS,
+    WORKSPACE_PATH,
+};
+use crate::intent::{Fingerprint, IntentTemplate};
+use crate::naming::{
+    AgentIdentity, ANNOTATION_CREATE_INTENT, ANNOTATION_IMAGE, ANNOTATION_PUBKEY_FULL,
+};
+use k8s_openapi::api::core::v1::{
+    Capabilities, Container, EmptyDirVolumeSource, EnvFromSource, Pod, PodSecurityContext, PodSpec,
+    ResourceRequirements, SeccompProfile, Secret, SecretEnvSource, SecurityContext, Volume,
+    VolumeMount,
+};
+use k8s_openapi::apimachinery::pkg::api::resource::Quantity;
+use k8s_openapi::apimachinery::pkg::apis::meta::v1::ObjectMeta;
+use std::collections::BTreeMap;
+
+/// Volume name for the agent's writable workspace.
+const WORKSPACE_VOLUME: &str = "workspace";
+
+/// The container name. Fixed: log and exec tooling addresses it by name.
+const CONTAINER_NAME: &str = "agent";
+
+/// Build the per-attempt Secret holding the resolved environment.
+///
+/// `immutable: true` — the Secret is written once per attempt and never
+/// updated, which is what lets the pod's `envFrom` reference be treated as an
+/// atomic binding to this exact payload (§K8s Secrets).
+pub fn build_secret(
+    identity: &AgentIdentity,
+    namespace: &str,
+    generation: &str,
+    env: BTreeMap<String, String>,
+) -> Secret {
+    Secret {
+        metadata: ObjectMeta {
+            name: Some(identity.secret_name(generation)),
+            namespace: Some(namespace.to_string()),
+            labels: Some(identity.labels()),
+            annotations: Some(
+                [(
+                    ANNOTATION_PUBKEY_FULL.to_string(),
+                    identity.pubkey_hex().to_string(),
+                )]
+                .into_iter()
+                .collect(),
+            ),
+            ..Default::default()
+        },
+        string_data: Some(env),
+        immutable: Some(true),
+        ..Default::default()
+    }
+}
+
+/// Build the pod for one create attempt.
+///
+/// The `fingerprint` is computed from [`intent_template`] over a type that
+/// cannot contain the generation or any Secret value, so it is stable across
+/// attempts of the same configuration.
+pub fn build_pod(
+    identity: &AgentIdentity,
+    cfg: &ProviderConfig,
+    generation: &str,
+    fingerprint: &Fingerprint,
+) -> Pod {
+    let annotations: BTreeMap<String, String> = [
+        (
+            ANNOTATION_PUBKEY_FULL.to_string(),
+            identity.pubkey_hex().to_string(),
+        ),
+        (
+            ANNOTATION_CREATE_INTENT.to_string(),
+            fingerprint.as_str().to_string(),
+        ),
+        (ANNOTATION_IMAGE.to_string(), cfg.image.as_str().to_string()),
+    ]
+    .into_iter()
+    .collect();
+
+    let requests: BTreeMap<String, Quantity> = [
+        (
+            "cpu".to_string(),
+            Quantity(cfg.resources.cpu_request.clone()),
+        ),
+        (
+            "memory".to_string(),
+            Quantity(cfg.resources.memory_request.clone()),
+        ),
+    ]
+    .into_iter()
+    .collect();
+    let limits: BTreeMap<String, Quantity> = [
+        ("cpu".to_string(), Quantity(cfg.resources.cpu_limit.clone())),
+        (
+            "memory".to_string(),
+            Quantity(cfg.resources.memory_limit.clone()),
+        ),
+    ]
+    .into_iter()
+    .collect();
+
+    let container = Container {
+        name: CONTAINER_NAME.to_string(),
+        image: Some(cfg.image.as_str().to_string()),
+        // No `command`/`args`: the image's entrypoint execs the harness as
+        // PID 1 (§Entrypoint). Overriding it here would be how a provider
+        // accidentally puts a shell in front of the signal receiver.
+        env_from: Some(vec![EnvFromSource {
+            secret_ref: Some(SecretEnvSource {
+                name: identity.secret_name(generation),
+                optional: Some(false),
+            }),
+            ..Default::default()
+        }]),
+        resources: Some(ResourceRequirements {
+            requests: Some(requests),
+            limits: Some(limits),
+            ..Default::default()
+        }),
+        volume_mounts: Some(vec![VolumeMount {
+            name: WORKSPACE_VOLUME.to_string(),
+            mount_path: WORKSPACE_PATH.to_string(),
+            ..Default::default()
+        }]),
+        security_context: Some(SecurityContext {
+            allow_privilege_escalation: Some(false),
+            capabilities: Some(Capabilities {
+                drop: Some(vec!["ALL".to_string()]),
+                ..Default::default()
+            }),
+            // `readOnlyRootFilesystem` is deliberately unset: the sprig
+            // toolchain writes outside the workspace mount (§Pod shape).
+            ..Default::default()
+        }),
+        ..Default::default()
+    };
+
+    Pod {
+        metadata: ObjectMeta {
+            name: Some(identity.pod_name()),
+            namespace: Some(cfg.namespace.clone()),
+            labels: Some(identity.labels()),
+            annotations: Some(annotations),
+            ..Default::default()
+        },
+        spec: Some(PodSpec {
+            containers: vec![container],
+            restart_policy: Some(RESTART_POLICY.to_string()),
+            termination_grace_period_seconds: Some(TERMINATION_GRACE_SECONDS),
+            // The agent runs prompted, untrusted code while holding an nsec;
+            // an ambient ServiceAccount token would be an API-stealable
+            // credential it never needs (§Pod shape hardening). Naming a
+            // service account selects a scheduling/RBAC identity and MUST NOT
+            // re-enable token mounting.
+            automount_service_account_token: Some(false),
+            service_account_name: cfg.service_account.clone(),
+            security_context: Some(PodSecurityContext {
+                run_as_non_root: Some(true),
+                run_as_user: Some(RUN_AS_UID),
+                run_as_group: Some(RUN_AS_GID),
+                fs_group: Some(RUN_AS_GID),
+                seccomp_profile: Some(SeccompProfile {
+                    type_: "RuntimeDefault".to_string(),
+                    ..Default::default()
+                }),
+                ..Default::default()
+            }),
+            volumes: Some(vec![Volume {
+                name: WORKSPACE_VOLUME.to_string(),
+                empty_dir: Some(EmptyDirVolumeSource::default()),
+                ..Default::default()
+            }]),
+            ..Default::default()
+        }),
+        ..Default::default()
+    }
+}
+
+/// The create-intent template for this configuration (§Deploy State Machine).
+pub fn intent_template(
+    cfg: &ProviderConfig,
+    env_keys: impl IntoIterator<Item = String>,
+) -> IntentTemplate {
+    IntentTemplate::new(
+        &cfg.namespace,
+        &cfg.image,
+        &cfg.resources,
+        cfg.service_account.as_deref(),
+        env_keys,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config;
+
+    fn identity() -> AgentIdentity {
+        use nostr::nips::nip19::ToBech32;
+        let keys = nostr::Keys::generate();
+        AgentIdentity::from_nsec(&keys.secret_key().to_bech32().unwrap()).unwrap()
+    }
+
+    fn provider_config() -> ProviderConfig {
+        config::parse(&serde_json::json!({
+            "namespace": "buzz-agents-test",
+            "image": format!("ghcr.io/block/buzz-sprig@sha256:{}", "a".repeat(64)),
+        }))
+        .unwrap()
+    }
+
+    fn pod() -> Pod {
+        let cfg = provider_config();
+        build_pod(
+            &identity(),
+            &cfg,
+            "gen00001",
+            &intent_template(&cfg, ["BUZZ_RELAY_URL".to_string()]).fingerprint(),
+        )
+    }
+
+    fn spec(pod: &Pod) -> &PodSpec {
+        pod.spec.as_ref().unwrap()
+    }
+
+    /// Every hardening default from §Pod shape, asserted individually so a
+    /// dropped one names itself.
+    #[test]
+    fn hardening_defaults_are_all_present() {
+        let pod = pod();
+        let spec = spec(&pod);
+        assert_eq!(spec.automount_service_account_token, Some(false));
+
+        let sc = spec
+            .security_context
+            .as_ref()
+            .expect("pod security context");
+        assert_eq!(sc.run_as_non_root, Some(true));
+        assert_eq!(sc.run_as_user, Some(RUN_AS_UID));
+        assert_ne!(sc.run_as_user, Some(0), "root UID");
+        assert_eq!(sc.run_as_group, Some(RUN_AS_GID));
+        assert_eq!(
+            sc.seccomp_profile.as_ref().map(|p| p.type_.as_str()),
+            Some("RuntimeDefault")
+        );
+
+        let csc = spec.containers[0]
+            .security_context
+            .as_ref()
+            .expect("container sc");
+        assert_eq!(csc.allow_privilege_escalation, Some(false));
+        assert_eq!(
+            csc.capabilities.as_ref().and_then(|c| c.drop.clone()),
+            Some(vec!["ALL".to_string()])
+        );
+        assert_ne!(csc.privileged, Some(true));
+    }
+
+    /// The forbidden host-namespace and hostPath escapes, asserted as absence.
+    #[test]
+    fn never_uses_host_namespaces_or_host_paths() {
+        let pod = pod();
+        let spec = spec(&pod);
+        assert!(spec.host_pid.is_none() || spec.host_pid == Some(false));
+        assert!(spec.host_network.is_none() || spec.host_network == Some(false));
+        assert!(spec.host_ipc.is_none() || spec.host_ipc == Some(false));
+        for volume in spec.volumes.as_ref().unwrap() {
+            assert!(
+                volume.host_path.is_none(),
+                "hostPath volume {}",
+                volume.name
+            );
+        }
+    }
+
+    /// `Never` only. `OnFailure` is gated on the harness exit-code contract
+    /// *and* a crash-loop classification row (`:1121-1139`); the config layer
+    /// refuses `inactivity_seconds: 0` so this arm is unreachable, and the
+    /// assertion keeps it that way.
+    #[test]
+    fn restart_policy_is_never() {
+        assert_eq!(spec(&pod()).restart_policy.as_deref(), Some("Never"));
+    }
+
+    /// 60s, not Kubernetes' default 30s — which would SIGKILL the harness
+    /// mid-drain and leave presence stale-online (§Pod shape).
+    #[test]
+    fn declares_the_sixty_second_grace_budget() {
+        assert_eq!(spec(&pod()).termination_grace_period_seconds, Some(60));
+    }
+
+    /// The pod must not override the image's entrypoint: the image execs the
+    /// harness as PID 1, and a `command` here is how a shell ends up in front
+    /// of the signal receiver (§Entrypoint).
+    #[test]
+    fn does_not_override_the_image_entrypoint() {
+        let pod = pod();
+        let container = &spec(&pod).containers[0];
+        assert!(container.command.is_none(), "overrode the entrypoint");
+        assert!(container.args.is_none());
+    }
+
+    #[test]
+    fn workspace_is_an_emptydir_mounted_at_home() {
+        let pod = pod();
+        let spec = spec(&pod);
+        let volume = &spec.volumes.as_ref().unwrap()[0];
+        assert!(volume.empty_dir.is_some());
+        assert!(volume.persistent_volume_claim.is_none());
+        let mount = &spec.containers[0].volume_mounts.as_ref().unwrap()[0];
+        assert_eq!(mount.name, volume.name);
+        assert_eq!(mount.mount_path, WORKSPACE_PATH);
+    }
+
+    #[test]
+    fn resources_carry_the_configured_requests_and_limits() {
+        let mut cfg = provider_config();
+        cfg.resources.cpu_limit = "4".into();
+        let pod = build_pod(&identity(), &cfg, "g", &Fingerprint::from_annotation("f"));
+        let r = spec(&pod).containers[0].resources.as_ref().unwrap();
+        assert_eq!(r.requests.as_ref().unwrap()["cpu"], Quantity("1".into()));
+        assert_eq!(
+            r.requests.as_ref().unwrap()["memory"],
+            Quantity("2Gi".into())
+        );
+        assert_eq!(r.limits.as_ref().unwrap()["cpu"], Quantity("4".into()));
+        assert_eq!(r.limits.as_ref().unwrap()["memory"], Quantity("4Gi".into()));
+    }
+
+    /// `envFrom` must point at this attempt's Secret and must NOT be optional:
+    /// an optional reference starts the container with no identity at all,
+    /// turning a missing-Secret bug into an agent that silently cannot
+    /// authenticate.
+    #[test]
+    fn env_from_references_this_attempts_secret_and_is_required() {
+        let id = identity();
+        let cfg = provider_config();
+        let pod = build_pod(&id, &cfg, "gen00042", &Fingerprint::from_annotation("f"));
+        let source = &spec(&pod).containers[0].env_from.as_ref().unwrap()[0];
+        let secret_ref = source.secret_ref.as_ref().unwrap();
+        assert_eq!(secret_ref.name, id.secret_name("gen00042"));
+        assert_eq!(secret_ref.optional, Some(false));
+        assert!(source.config_map_ref.is_none());
+    }
+
+    /// Identity, ownership marker, and the recorded intent all travel on the
+    /// pod — the GC and reconciliation fences read exactly these.
+    #[test]
+    fn pod_carries_identity_marker_and_recorded_intent() {
+        let id = identity();
+        let cfg = provider_config();
+        let fp = intent_template(&cfg, ["A".to_string()]).fingerprint();
+        let pod = build_pod(&id, &cfg, "g", &fp);
+        let meta = &pod.metadata;
+        assert_eq!(meta.name.as_deref(), Some(id.pod_name().as_str()));
+        assert_eq!(meta.namespace.as_deref(), Some("buzz-agents-test"));
+        assert_eq!(meta.labels.as_ref().unwrap(), &id.labels());
+        let ann = meta.annotations.as_ref().unwrap();
+        assert_eq!(ann[ANNOTATION_PUBKEY_FULL], id.pubkey_hex());
+        assert_eq!(ann[ANNOTATION_CREATE_INTENT], fp.as_str());
+        assert_eq!(ann[ANNOTATION_IMAGE], cfg.image.as_str());
+    }
+
+    /// The Secret is immutable and marker-bearing: immutability is what makes
+    /// the pod's `envFrom` an atomic binding, and the marker is what GC
+    /// requires before it will delete anything.
+    #[test]
+    fn secret_is_immutable_marked_and_holds_the_env() {
+        let id = identity();
+        let env: BTreeMap<String, String> =
+            [("BUZZ_RELAY_URL".to_string(), "wss://r".to_string())].into();
+        let secret = build_secret(&id, "ns", "gen1", env.clone());
+        assert_eq!(secret.immutable, Some(true));
+        assert_eq!(secret.string_data.as_ref().unwrap(), &env);
+        assert_eq!(
+            secret.metadata.name.as_deref(),
+            Some(id.secret_name("gen1").as_str())
+        );
+        assert_eq!(secret.metadata.labels.as_ref().unwrap(), &id.labels());
+        assert_eq!(
+            secret.metadata.annotations.as_ref().unwrap()[ANNOTATION_PUBKEY_FULL],
+            id.pubkey_hex()
+        );
+        // `data` must stay unset — setting both is an apiserver rejection.
+        assert!(secret.data.is_none());
+    }
+
+    /// Naming a service account selects a scheduling identity; it must not
+    /// re-enable token mounting (§Pod shape hardening, `:1221-1225`).
+    #[test]
+    fn service_account_does_not_re_enable_token_mounting() {
+        let mut cfg = provider_config();
+        cfg.service_account = Some("agent-sa".into());
+        let pod = build_pod(&identity(), &cfg, "g", &Fingerprint::from_annotation("f"));
+        assert_eq!(spec(&pod).service_account_name.as_deref(), Some("agent-sa"));
+        assert_eq!(spec(&pod).automount_service_account_token, Some(false));
+    }
+
+    /// The fingerprint recorded on the pod is the one the classifier will
+    /// recompute — pinned end-to-end so a builder change that forgets to feed
+    /// the template a field cannot pass silently.
+    #[test]
+    fn recorded_fingerprint_matches_a_fresh_computation() {
+        let cfg = provider_config();
+        let keys = ["BUZZ_RELAY_URL".to_string(), "GOOSE_MODE".to_string()];
+        let fp = intent_template(&cfg, keys.clone()).fingerprint();
+        let pod = build_pod(&identity(), &cfg, "gen-a", &fp);
+        let recorded = Fingerprint::from_annotation(
+            &pod.metadata.annotations.as_ref().unwrap()[ANNOTATION_CREATE_INTENT],
+        );
+        assert_eq!(recorded, intent_template(&cfg, keys).fingerprint());
+    }
+
+    /// Two attempts differing only in generation must record the *same*
+    /// fingerprint, or the divergence discriminator fires on every deploy and
+    /// the never-started row deletes healthy pending pods.
+    #[test]
+    fn generation_does_not_change_the_recorded_fingerprint() {
+        let cfg = provider_config();
+        let keys = ["BUZZ_RELAY_URL".to_string()];
+        let a = intent_template(&cfg, keys.clone()).fingerprint();
+        let b = intent_template(&cfg, keys).fingerprint();
+        let id = identity();
+        let pod_a = build_pod(&id, &cfg, "gen-1", &a);
+        let pod_b = build_pod(&id, &cfg, "gen-2", &b);
+        let read =
+            |p: &Pod| p.metadata.annotations.as_ref().unwrap()[ANNOTATION_CREATE_INTENT].clone();
+        assert_eq!(read(&pod_a), read(&pod_b));
+        // ...while the Secret they reference differs.
+        let secret_of = |p: &Pod| {
+            spec(p).containers[0].env_from.as_ref().unwrap()[0]
+                .secret_ref
+                .as_ref()
+                .unwrap()
+                .name
+                .clone()
+        };
+        assert_ne!(secret_of(&pod_a), secret_of(&pod_b));
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/reconcile.rs b/crates/buzz-backend-kubernetes/src/reconcile.rs
new file mode 100644
index 0000000000..df2f99789f
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/reconcile.rs
@@ -0,0 +1,1585 @@
+//! The deploy loop: executes [`crate::classify`]'s actions against a substrate
+//! and re-enters (spec §Deploy State Machine).
+//!
+//! The substrate is a trait so the conformance tests drive this exact
+//! reconciler — the shipped code path, not a test-only reimplementation — with
+//! a fake cluster and a fake clock.
+//!
+//! Two shapes are worth naming up front, because they are what keep the loop
+//! terminating:
+//!
+//! * **Success means the harness container started** (`:696-699`). There is no
+//!   "deployed but not confirmed" success: `deploy` returns an `agent_id` or an
+//!   in-band error carrying the latest condition. The wire has no third form.
+//! * **A create-conflict loser never repairs.** It verifies the winner, drops
+//!   its own Secret, and *observes* until the winner starts. Applying the
+//!   divergence row to the pod that just beat it is exactly the ping-pong the
+//!   spec forbids (`:845-850`), and the escape it names is the *next* deploy,
+//!   not this one.
+
+use crate::classify::{self, Action, Fence, Startup, VerifiedPod};
+use crate::config::ProviderConfig;
+use crate::gc;
+use crate::naming::AgentIdentity;
+use crate::observe::{self, StartupObservation};
+use chrono::{DateTime, Utc};
+use k8s_openapi::api::core::v1::{Pod, Secret};
+use std::collections::BTreeMap;
+use std::time::Duration;
+
+/// Outcome of a create against the deterministic pod name.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CreateOutcome {
+    Created,
+    /// 409 with `Status.reason: AlreadyExists` — a concurrent attempt won.
+    /// Discriminated on the typed reason, never on the HTTP code alone: 409 is
+    /// also `Conflict`, which means a failed precondition (`:780-794`).
+    AlreadyExists,
+}
+
+/// Outcome of a fenced delete.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DeleteOutcome {
+    Accepted,
+    /// Already gone. Delete-not-found is success (`:842`).
+    NotFound,
+    /// 409 with `Status.reason: Conflict` — the object changed since the
+    /// observation that authorized this delete. Neither an error nor
+    /// permission to retry: re-enter and classify what exists now
+    /// (`:775-777`).
+    PreconditionFailed,
+}
+
+/// The cluster operations the reconciler needs. Everything here is I/O;
+/// everything that decides is pure and lives in `classify`/`gc`.
+#[allow(async_fn_in_trait)]
+pub trait Substrate {
+    /// Create the namespace if absent. On RBAC denial the error MUST name the
+    /// literal `kubectl create namespace <name>` command and MUST NOT fall
+    /// back to `default` (`:1002-1005`).
+    async fn ensure_namespace(&self, namespace: &str) -> Result<(), String>;
+
+    /// Most-recent read of the pods matching this identity's selector, plus
+    /// the apiserver's clock from the same call's HTTP `Date` header. `None`
+    /// clock means the header was absent or unparseable, which makes the
+    /// orphan-Secret sweep skip (`:1321-1335`).
+    async fn list_pods(&self, selector: &str) -> Result<(Vec<Pod>, Option<DateTime<Utc>>), String>;
+
+    async fn list_secrets(&self, selector: &str) -> Result<Vec<Secret>, String>;
+
+    /// Most-recent existence check (`resourceVersion` explicitly unset, not
+    /// `"0"`): the classifier treats a confirmed absence as proof, so a
+    /// possibly-stale cache read would be proof of nothing (`:761-769`).
+    async fn secret_exists(&self, name: &str) -> Result<bool, String>;
+
+    async fn create_secret(&self, secret: &Secret) -> Result<(), String>;
+
+    async fn create_pod(&self, pod: &Pod) -> Result<CreateOutcome, String>;
+
+    /// Compare-and-delete against the fence from the authorizing observation.
+    /// Uses the object's own grace period — never `grace_period_seconds: 0`,
+    /// which is a force-kill that discards the declared 60s shutdown budget
+    /// (`:1185-1189`).
+    async fn delete_pod(&self, name: &str, fence: &Fence) -> Result<DeleteOutcome, String>;
+
+    /// Best-effort: the Secret may already be gone, which is success.
+    async fn delete_secret(&self, name: &str) -> Result<(), String>;
+
+    /// Read one pod by name, most-recent. `None` is a confirmed absence.
+    async fn get_pod(&self, name: &str) -> Result<Option<Pod>, String>;
+
+    async fn sleep(&self, duration: Duration);
+
+    /// Monotonic elapsed time since the operation began. Fake-clock driven in
+    /// tests; the deadline must not depend on wall-clock adjustments.
+    fn elapsed(&self) -> Duration;
+}
+
+/// Interval between reconciler polls. Short enough that a fast start is
+/// reported promptly, long enough not to hammer the apiserver for 600s.
+const POLL_INTERVAL: Duration = Duration::from_secs(2);
+
+/// The deploy operation deadline (spec §Deploy: `timeout: 600s`).
+const DEADLINE: Duration = Duration::from_secs(gc::OPERATION_DEADLINE_SECS as u64);
+
+/// Settle a pod's startup state, performing the one most-recent Secret read
+/// that `CreateContainerConfigError` requires.
+async fn settle(substrate: &impl Substrate, pod: &Pod) -> Result<Startup, String> {
+    Ok(match observe::decode_startup(pod) {
+        StartupObservation::Resolved(startup) => startup,
+        StartupObservation::ConfigErrorPendingSecretCheck { secret_name } => {
+            // A confirmed absence is proof; anything else stays recoverable,
+            // because the kubelet's reason string alone is not evidence.
+            if substrate.secret_exists(&secret_name).await? {
+                Startup::NeverStartedRecoverable
+            } else {
+                Startup::NeverStartedProvablyBroken
+            }
+        }
+    })
+}
+
+/// Observe the single pod owned by this identity, verified.
+///
+/// `Ok(None)` conflates "absent" with "present but not ours" on purpose *here*
+/// — both mean the classifier has nothing it may act on. The create path
+/// separates them, because only there is the difference actionable.
+async fn observe_pod(
+    substrate: &impl Substrate,
+    identity: &AgentIdentity,
+) -> Result<Option<VerifiedPod>, String> {
+    let Some(pod) = substrate.get_pod(&identity.pod_name()).await? else {
+        return Ok(None);
+    };
+    let startup = settle(substrate, &pod).await?;
+    Ok(observe::verify(&pod, identity, startup))
+}
+
+/// The latest condition to report, read fresh at the moment of reporting.
+///
+/// Reading it here rather than threading it through every loop iteration is
+/// what "the *latest* redacted condition" (`:689`) asks for, and it costs a
+/// read only on the paths that are already failing.
+async fn latest_condition(substrate: &impl Substrate, identity: &AgentIdentity) -> String {
+    match substrate.get_pod(&identity.pod_name()).await {
+        Ok(Some(pod)) => observe::condition(&pod)
+            .unwrap_or_else(|| "no condition reported by the cluster".to_string()),
+        Ok(None) => "the pod no longer exists".to_string(),
+        Err(e) => format!("the pod's condition could not be read: {e}"),
+    }
+}
+
+/// Preflight GC (§K8s GC). Failures are logged and swallowed: GC is hygiene,
+/// and a deploy must not fail because a stale object could not be listed or
+/// removed. A denial that actually blocks this deploy resurfaces at create,
+/// where the message names the operation the user was denied.
+async fn preflight_gc(substrate: &impl Substrate, identity: &AgentIdentity) {
+    if let Err(e) = try_preflight_gc(substrate, identity).await {
+        eprintln!("gc: preflight pass skipped: {e}");
+    }
+}
+
+async fn try_preflight_gc(
+    substrate: &impl Substrate,
+    identity: &AgentIdentity,
+) -> Result<(), String> {
+    let selector = identity.selector();
+    let (pods, server_now) = substrate.list_pods(&selector).await?;
+    let secrets = substrate.list_secrets(&selector).await?;
+
+    let mut terminated: Vec<String> = Vec::new();
+    for pod in &pods {
+        if matches!(settle(substrate, pod).await?, Startup::Terminated) {
+            if let Some(name) = pod.metadata.name.clone() {
+                terminated.push(name);
+            }
+        }
+    }
+
+    let plan = gc::plan(
+        identity,
+        &pods,
+        &secrets,
+        |pod| {
+            pod.metadata
+                .name
+                .as_deref()
+                .map(|n| terminated.iter().any(|t| t == n))
+                .unwrap_or(false)
+        },
+        server_now,
+    );
+
+    for name in &plan.pods {
+        // Re-read to fence the delete against the object we just observed; a
+        // pod that changed since the list is simply skipped this pass.
+        let Some(pod) = substrate.get_pod(name).await? else {
+            continue;
+        };
+        let (Some(uid), Some(rv)) = (
+            pod.metadata.uid.clone(),
+            pod.metadata.resource_version.clone(),
+        ) else {
+            continue;
+        };
+        if !matches!(settle(substrate, &pod).await?, Startup::Terminated) {
+            continue;
+        }
+        let fence = Fence {
+            uid,
+            resource_version: rv,
+        };
+        if let Err(e) = substrate.delete_pod(name, &fence).await {
+            eprintln!("gc: could not delete terminated pod {name}: {e}");
+        }
+    }
+    for name in &plan.secrets {
+        if let Err(e) = substrate.delete_secret(name).await {
+            eprintln!("gc: could not delete secret {name}: {e}");
+        }
+    }
+    Ok(())
+}
+
+/// Wait for a pod to actually disappear.
+///
+/// Mandatory before recreating: `DELETE` returns success while the object
+/// still exists, and the deterministic name stays taken for the whole grace
+/// period (`:1177-1195`).
+async fn await_disappearance(substrate: &impl Substrate, name: &str) -> Result<(), String> {
+    while substrate.elapsed() < DEADLINE {
+        if substrate.get_pod(name).await?.is_none() {
+            return Ok(());
+        }
+        substrate.sleep(POLL_INTERVAL).await;
+    }
+    Err(format!(
+        "timed out after {}s waiting for {name} to finish terminating",
+        DEADLINE.as_secs()
+    ))
+}
+
+/// Is `secret` referenced by any pod that currently exists under this
+/// identity's selector?
+///
+/// Protection deliberately spans *all* our pods, not just the winner: an
+/// `envFrom` reference from a pod still pulling its image is exactly as
+/// load-bearing as one from a running pod (`:1261-1264`).
+async fn secret_is_referenced(
+    substrate: &impl Substrate,
+    identity: &AgentIdentity,
+    secret: &str,
+) -> Result<bool, String> {
+    let (pods, _) = substrate.list_pods(&identity.selector()).await?;
+    Ok(pods
+        .iter()
+        .filter_map(observe::referenced_secret)
+        .any(|name| name == secret))
+}
+
+/// Drop this attempt's own Secret once nothing references it.
+///
+/// Only ever called with a name this process generated, and gated on the
+/// reference check: "never the winner's, never any Secret referenced by an
+/// existing pod" (`:1259-1264`). Failure is logged, not fatal — a leaked
+/// Secret is collected by the age-gated sweep.
+async fn drop_own_secret(substrate: &impl Substrate, identity: &AgentIdentity, secret: &str) {
+    match secret_is_referenced(substrate, identity, secret).await {
+        Ok(false) => {
+            if let Err(e) = substrate.delete_secret(secret).await {
+                eprintln!("could not clean up own unreferenced secret {secret}: {e}");
+            }
+        }
+        Ok(true) => {}
+        Err(e) => eprintln!("could not check whether {secret} is still referenced: {e}"),
+    }
+}
+
+/// Lost the create race: adopt the elected winner.
+///
+/// Observe-only by construction — this function has no delete edge for the
+/// pod. A winner that is terminated or provably broken is reported, not
+/// repaired; the spec's escape is "a *subsequent* deploy that walks in and
+/// observes that never-started divergent winner replaces it normally"
+/// (`:849-850`).
+async fn adopt_winner(
+    substrate: &impl Substrate,
+    identity: &AgentIdentity,
+    own_secret: &str,
+) -> Result<String, String> {
+    let name = identity.pod_name();
+
+    // Verify before adopting. A pod under our deterministic name that fails
+    // the marker/annotation check is not ours to adopt, wait for, or touch —
+    // and it will never become ours, so this is terminal rather than a retry.
+    match substrate.get_pod(&name).await? {
+        None => {}
+        Some(pod) => {
+            let startup = settle(substrate, &pod).await?;
+            if observe::verify(&pod, identity, startup).is_none() {
+                drop_own_secret(substrate, identity, own_secret).await;
+                return Err(format!(
+                    "a pod named {name} already exists in this namespace but is not \
+                     managed by this provider for this agent (it lacks the management \
+                     marker or carries a different agent identity). Remove it, or \
+                     deploy this agent to a different namespace."
+                ));
+            }
+        }
+    }
+
+    drop_own_secret(substrate, identity, own_secret).await;
+
+    // Then wait for the winner exactly as we would wait for our own pod:
+    // success still means the harness container started.
+    loop {
+        if substrate.elapsed() >= DEADLINE {
+            return Err(format!(
+                "startup not confirmed within {}s for {name} (another deploy of this \
+                 agent created it): {}",
+                DEADLINE.as_secs(),
+                latest_condition(substrate, identity).await
+            ));
+        }
+        match observe_pod(substrate, identity).await? {
+            Some(pod) if matches!(pod.startup, Startup::Started) => return Ok(pod.name),
+            Some(pod) if pod.deletion_marked => {
+                return Err(format!(
+                    "{name} was created by another deploy of this agent and is already \
+                     being deleted; try again"
+                ))
+            }
+            Some(pod)
+                if matches!(
+                    pod.startup,
+                    Startup::Terminated | Startup::NeverStartedProvablyBroken
+                ) =>
+            {
+                return Err(format!(
+                    "{name} was created by another deploy of this agent and did not \
+                     start: {}",
+                    latest_condition(substrate, identity).await
+                ))
+            }
+            // Gone again, or still coming up: keep observing under this
+            // operation's deadline.
+            _ => substrate.sleep(POLL_INTERVAL).await,
+        }
+    }
+}
+
+/// Run the deploy state machine to a terminal outcome: the started pod's name,
+/// or an in-band error carrying the latest condition.
+pub async fn deploy(
+    substrate: &impl Substrate,
+    identity: &AgentIdentity,
+    cfg: &ProviderConfig,
+    env: BTreeMap<String, String>,
+) -> Result<String, String> {
+    substrate.ensure_namespace(&cfg.namespace).await?;
+    preflight_gc(substrate, identity).await;
+
+    let desired = crate::pod::intent_template(cfg, env.keys().cloned()).fingerprint();
+
+    // Has THIS call created a pod? Set once its create lands. The replacement
+    // rows below are for residue from a previous life; once this call has made
+    // its own attempt, a replace-classification means that attempt failed —
+    // and startup verification is part of create, so the failure is reported
+    // in-band rather than retried. Without this bound a deterministic startup
+    // failure (the harness starts, rejects its configuration, exits) is
+    // delete-recreated every poll for the whole deadline, minting an immutable
+    // Secret per cycle — measured live at 107 Secrets in one 600s call, every
+    // one younger than the orphan sweep's age gate.
+    let mut created_this_call = false;
+
+    loop {
+        if substrate.elapsed() >= DEADLINE {
+            return Err(format!(
+                "startup not confirmed within {}s for {}: {}",
+                DEADLINE.as_secs(),
+                identity.pod_name(),
+                latest_condition(substrate, identity).await
+            ));
+        }
+
+        let observed = observe_pod(substrate, identity).await?;
+        match classify::classify(observed.as_ref(), &desired) {
+            // The only success edge: the harness container is running.
+            Action::NoOp { agent_id } => return Ok(agent_id),
+
+            // Self-healing states. Never delete, on this call or any later one
+            // — what replaces a never-started pod is a config change, never a
+            // deadline (`:717-729`).
+            Action::Observe { .. } => substrate.sleep(POLL_INTERVAL).await,
+
+            // A pull that will not self-heal: report now rather than spend the
+            // remaining deadline on it. Still no delete authority.
+            Action::Report { name, failure } => {
+                return Err(format!(
+                    "{name} did not start: {}",
+                    observe::pull_failure_message(failure, cfg.image.as_str())
+                ))
+            }
+
+            Action::AwaitDisappearance { name } => await_disappearance(substrate, &name).await?,
+
+            Action::Delete { name, fence } => {
+                // This call already made its own attempt, and that attempt is
+                // what the classification wants replaced: it terminated (the
+                // deterministic startup failure — the harness starts, rejects
+                // its configuration, exits) or was proven broken. Replacing it
+                // here retries the identical configuration against the same
+                // cluster: a hot delete/mint/create cycle every poll for the
+                // whole deadline, an immutable Secret per cycle — measured
+                // live at 107 Secrets in one 600s call, all younger than the
+                // orphan sweep's age gate. Report in-band instead. The residue
+                // is deliberate: the next Start's preflight GC collects the
+                // terminated pod and its referenced Secret together, so retry
+                // is gated on fresh owner intent and litter stays bounded at
+                // one pod + one Secret per press.
+                if created_this_call {
+                    return Err(format!(
+                        "{name} was created by this deploy and did not stay \
+                         running: {}. Not retrying in this call — an immediate \
+                         exit recurs until its cause is fixed. Check the \
+                         agent's configuration and press Start to try again.",
+                        latest_condition(substrate, identity).await
+                    ));
+                }
+                match substrate.delete_pod(&name, &fence).await? {
+                    // Accepted or already gone: both need the disappearance
+                    // poll before the name is free again.
+                    DeleteOutcome::Accepted | DeleteOutcome::NotFound => {
+                        await_disappearance(substrate, &name).await?
+                    }
+                    // The object changed since the observation that authorized
+                    // this delete. Discard the action and re-classify — never
+                    // retry with a fresher fence, which would delete something
+                    // we never examined. Sleep before re-entering: the losing
+                    // race is against another writer, and re-reading at full
+                    // speed is a busy-retry with no better odds than a paced
+                    // one.
+                    DeleteOutcome::PreconditionFailed => substrate.sleep(POLL_INTERVAL).await,
+                }
+            }
+
+            Action::Create => {
+                let generation = crate::naming::new_generation();
+                let secret_name = identity.secret_name(&generation);
+
+                // The generation is minted *per attempt*, and it is two things
+                // at once: the Secret's name suffix and the lifecycle
+                // correlator the harness reports. `build_env` stamped the
+                // caller's generation, so on any attempt after the first the
+                // two would name different generations — pod logs correlating
+                // to a Secret that is not the one mounted. Restamp so there is
+                // exactly one generation per attempt (§K8s Secrets).
+                let mut env = env.clone();
+                env.insert(crate::env::START_NONCE_KEY.to_string(), generation.clone());
+
+                // Secret first: the pod's spec references this exact name, so
+                // payload and Secret are atomic at the pod-spec boundary.
+                let secret = crate::pod::build_secret(identity, &cfg.namespace, &generation, env);
+                substrate.create_secret(&secret).await?;
+
+                let pod = crate::pod::build_pod(identity, cfg, &generation, &desired);
+                match substrate.create_pod(&pod).await? {
+                    // Re-enter rather than wait inline: the next iteration
+                    // observes what we just created and runs the same rows
+                    // every other state runs through. One loop, one table.
+                    //
+                    // Sleep first. A just-created pod cannot already be
+                    // started, so the immediate observation has no outcome but
+                    // "still coming up" — and if it ever came back
+                    // unverifiable, re-entering without advancing the clock
+                    // would hot-spin creates against the apiserver for the
+                    // whole deadline.
+                    CreateOutcome::Created => {
+                        created_this_call = true;
+                        substrate.sleep(POLL_INTERVAL).await
+                    }
+                    CreateOutcome::AlreadyExists => {
+                        return adopt_winner(substrate, identity, &secret_name).await
+                    }
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::Resources;
+    use crate::naming::{ANNOTATION_CREATE_INTENT, ANNOTATION_PUBKEY_FULL, LABEL_MANAGED_BY};
+    use k8s_openapi::api::core::v1::{
+        ContainerState, ContainerStateRunning, ContainerStateTerminated, ContainerStateWaiting,
+        ContainerStatus, PodStatus,
+    };
+    use k8s_openapi::apimachinery::pkg::apis::meta::v1::Time;
+    use std::cell::RefCell;
+    use std::future::Future;
+    use std::pin::pin;
+    use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
+
+    /// Mutates the pod map after a poll, so a test can script a pod that
+    /// starts (or vanishes) partway through an observation loop.
+    type PollHook = Box<dyn Fn(&mut BTreeMap<String, Pod>)>;
+
+    /// A scripted cluster. Single-threaded on purpose: the reconciler is one
+    /// process per operation, and `RefCell` keeps the assertions readable.
+    ///
+    /// This drives the *shipped* `deploy` — the point of the `Substrate` seam.
+    /// Every fake here answers with real `k8s_openapi` objects, so the decode
+    /// and verification layers under test are the ones that run in a cluster.
+    #[derive(Default)]
+    struct Fake {
+        pods: RefCell<BTreeMap<String, Pod>>,
+        secrets: RefCell<Vec<Secret>>,
+        /// Server clock for the GC age gate; `None` models a missing `Date`.
+        server_now: Option<DateTime<Utc>>,
+        /// Elapsed time, advanced only by `sleep` — a fake clock, so a 600s
+        /// deadline test runs instantly and cannot flake on a slow machine.
+        elapsed: RefCell<Duration>,
+        /// Queued create outcomes; the default is `Created`.
+        create_outcomes: RefCell<Vec<CreateOutcome>>,
+        /// Installed when a create loses the race. A winner must be *absent*
+        /// at the observation that decides to create and *present* by the time
+        /// the create lands — pre-seeding it instead makes the loop no-op
+        /// before it ever reaches the create edge.
+        winner: RefCell<Option<Pod>>,
+        /// Every Secret ever created, retained across deletion.
+        created_secrets: RefCell<Vec<Secret>>,
+        /// Queued delete outcomes; the default is `Accepted`.
+        delete_outcomes: RefCell<Vec<DeleteOutcome>>,
+        /// Every mutating call, in order — the anti-mutation assertions read
+        /// this rather than guessing from final state.
+        calls: RefCell<Vec<String>>,
+        /// Applied to the pod map after each poll, so a test can script a pod
+        /// that starts (or vanishes) partway through an observation loop.
+        on_poll: RefCell<Vec<PollHook>>,
+        /// `ensure_namespace` fails with this, if set.
+        namespace_error: Option<String>,
+    }
+
+    impl Fake {
+        fn with_pod(self, pod: Pod) -> Self {
+            self.pods
+                .borrow_mut()
+                .insert(pod.metadata.name.clone().unwrap(), pod);
+            self
+        }
+        fn log(&self, entry: impl Into<String>) {
+            self.calls.borrow_mut().push(entry.into());
+        }
+        fn mutations(&self) -> Vec<String> {
+            self.calls.borrow().clone()
+        }
+    }
+
+    impl Substrate for Fake {
+        async fn ensure_namespace(&self, namespace: &str) -> Result<(), String> {
+            match &self.namespace_error {
+                Some(e) => Err(e.clone()),
+                None => {
+                    self.log(format!("ensure_namespace {namespace}"));
+                    Ok(())
+                }
+            }
+        }
+
+        async fn list_pods(
+            &self,
+            _selector: &str,
+        ) -> Result<(Vec<Pod>, Option<DateTime<Utc>>), String> {
+            Ok((
+                self.pods.borrow().values().cloned().collect(),
+                self.server_now,
+            ))
+        }
+
+        async fn list_secrets(&self, _selector: &str) -> Result<Vec<Secret>, String> {
+            Ok(self.secrets.borrow().clone())
+        }
+
+        async fn secret_exists(&self, name: &str) -> Result<bool, String> {
+            Ok(self
+                .secrets
+                .borrow()
+                .iter()
+                .any(|s| s.metadata.name.as_deref() == Some(name)))
+        }
+
+        async fn create_secret(&self, secret: &Secret) -> Result<(), String> {
+            let name = secret.metadata.name.clone().unwrap();
+            self.log(format!("create_secret {name}"));
+            self.secrets.borrow_mut().push(secret.clone());
+            // Kept even after the Secret is deleted: assertions about what an
+            // attempt *wrote* must not be silently vacuous once cleanup runs.
+            self.created_secrets.borrow_mut().push(secret.clone());
+            Ok(())
+        }
+
+        async fn create_pod(&self, pod: &Pod) -> Result<CreateOutcome, String> {
+            let name = pod.metadata.name.clone().unwrap();
+            self.log(format!("create_pod {name}"));
+            let outcome = if self.create_outcomes.borrow().is_empty() {
+                CreateOutcome::Created
+            } else {
+                self.create_outcomes.borrow_mut().remove(0)
+            };
+            if outcome == CreateOutcome::Created {
+                // The apiserver stamps these on admission; a builder never
+                // carries them. Without them the pod fails `verify`'s fence
+                // extraction and the loop can never see what it just created.
+                let mut pod = pod.clone();
+                pod.metadata.uid = Some(format!("uid-created-{}", self.calls.borrow().len()));
+                pod.metadata.resource_version = Some("1".into());
+                self.pods.borrow_mut().insert(name, pod);
+            } else if let Some(winner) = self.winner.borrow_mut().take() {
+                // The concurrent attempt's pod becomes visible exactly when our
+                // create is rejected — the ordering a real race produces.
+                self.pods.borrow_mut().insert(name, winner);
+            }
+            Ok(outcome)
+        }
+
+        async fn delete_pod(&self, name: &str, fence: &Fence) -> Result<DeleteOutcome, String> {
+            self.log(format!(
+                "delete_pod {name} uid={} rv={}",
+                fence.uid, fence.resource_version
+            ));
+            let outcome = if self.delete_outcomes.borrow().is_empty() {
+                DeleteOutcome::Accepted
+            } else {
+                self.delete_outcomes.borrow_mut().remove(0)
+            };
+            if outcome == DeleteOutcome::Accepted {
+                self.pods.borrow_mut().remove(name);
+            }
+            Ok(outcome)
+        }
+
+        async fn delete_secret(&self, name: &str) -> Result<(), String> {
+            self.log(format!("delete_secret {name}"));
+            self.secrets
+                .borrow_mut()
+                .retain(|s| s.metadata.name.as_deref() != Some(name));
+            Ok(())
+        }
+
+        async fn get_pod(&self, name: &str) -> Result<Option<Pod>, String> {
+            Ok(self.pods.borrow().get(name).cloned())
+        }
+
+        async fn sleep(&self, duration: Duration) {
+            *self.elapsed.borrow_mut() += duration;
+            let hooks = self.on_poll.borrow();
+            let mut pods = self.pods.borrow_mut();
+            for hook in hooks.iter() {
+                hook(&mut pods);
+            }
+        }
+
+        fn elapsed(&self) -> Duration {
+            *self.elapsed.borrow()
+        }
+    }
+
+    fn identity() -> AgentIdentity {
+        use nostr::nips::nip19::ToBech32;
+        let keys = nostr::Keys::generate();
+        AgentIdentity::from_nsec(&keys.secret_key().to_bech32().unwrap()).unwrap()
+    }
+
+    fn config() -> ProviderConfig {
+        ProviderConfig {
+            context: None,
+            namespace: "buzz-agents-test".into(),
+            image: crate::image::parse(&format!(
+                "ghcr.io/block/buzz-sprig@sha256:{}",
+                "a".repeat(64)
+            ))
+            .unwrap(),
+            resources: Resources::default(),
+            inactivity_seconds: Some(7200),
+            service_account: None,
+        }
+    }
+
+    fn env() -> BTreeMap<String, String> {
+        [("BUZZ_RELAY_URL".to_string(), "wss://r".to_string())]
+            .into_iter()
+            .collect()
+    }
+
+    /// A pod exactly as this provider would have created it — same builder the
+    /// reconciler uses, so verification is exercised rather than bypassed.
+    fn our_pod(id: &AgentIdentity, cfg: &ProviderConfig, state: Option<ContainerState>) -> Pod {
+        let fp = crate::pod::intent_template(cfg, env().keys().cloned()).fingerprint();
+        let mut pod = crate::pod::build_pod(id, cfg, "gen-existing", &fp);
+        pod.metadata.uid = Some("uid-1".into());
+        pod.metadata.resource_version = Some("100".into());
+        pod.status = Some(PodStatus {
+            phase: Some("Running".into()),
+            container_statuses: state.map(|s| {
+                vec![ContainerStatus {
+                    name: crate::observe::CONTAINER_NAME.into(),
+                    state: Some(s),
+                    ..Default::default()
+                }]
+            }),
+            ..Default::default()
+        });
+        pod
+    }
+
+    fn running() -> ContainerState {
+        ContainerState {
+            running: Some(ContainerStateRunning::default()),
+            ..Default::default()
+        }
+    }
+
+    fn terminated() -> ContainerState {
+        ContainerState {
+            terminated: Some(ContainerStateTerminated::default()),
+            ..Default::default()
+        }
+    }
+
+    fn waiting(reason: &str) -> ContainerState {
+        ContainerState {
+            waiting: Some(ContainerStateWaiting {
+                reason: Some(reason.into()),
+                message: None,
+            }),
+            ..Default::default()
+        }
+    }
+
+    fn run(fake: &Fake, id: &AgentIdentity, cfg: &ProviderConfig) -> Result<String, String> {
+        block_on(deploy(fake, id, cfg, env()))
+    }
+
+    /// Minimal executor: the fake never yields to a reactor (no timers, no
+    /// I/O — `sleep` just advances a counter), so polling to completion is
+    /// sufficient and avoids pulling a runtime into the unit job.
+    fn block_on<T>(fut: impl Future<Output = T>) -> T {
+        fn noop_waker() -> Waker {
+            fn nop(_: *const ()) {}
+            fn clone(_: *const ()) -> RawWaker {
+                RawWaker::new(std::ptr::null(), &VTABLE)
+            }
+            static VTABLE: RawWakerVTable = RawWakerVTable::new(clone, nop, nop, nop);
+            unsafe { Waker::from_raw(RawWaker::new(std::ptr::null(), &VTABLE)) }
+        }
+
+        let waker = noop_waker();
+        let mut cx = Context::from_waker(&waker);
+        let mut fut = pin!(fut);
+        match fut.as_mut().poll(&mut cx) {
+            Poll::Ready(v) => v,
+            Poll::Pending => panic!("fake substrate future parked — it has no reactor"),
+        }
+    }
+
+    // ---- the state machine's rows, end to end -------------------------------
+
+    /// First deploy: Secret before pod, and the returned id is the pod name.
+    #[test]
+    fn creates_secret_then_pod_and_returns_the_pod_name() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default();
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                if let Some(pod) = pods.get_mut(&name) {
+                    pod.status = Some(PodStatus {
+                        phase: Some("Running".into()),
+                        container_statuses: Some(vec![ContainerStatus {
+                            name: crate::observe::CONTAINER_NAME.into(),
+                            state: Some(running()),
+                            ..Default::default()
+                        }]),
+                        ..Default::default()
+                    });
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+
+        let calls = fake.mutations();
+        let secret_at = calls
+            .iter()
+            .position(|c| c.starts_with("create_secret"))
+            .unwrap();
+        let pod_at = calls
+            .iter()
+            .position(|c| c.starts_with("create_pod"))
+            .unwrap();
+        assert!(
+            secret_at < pod_at,
+            "pod created before its Secret: {calls:?}"
+        );
+    }
+
+    /// The strict no-op row: a started pod returns its id having mutated
+    /// nothing at all. Asserted on the *call log*, not on final state — a
+    /// delete-then-recreate would leave identical final state.
+    #[test]
+    fn started_pod_is_a_zero_mutation_no_op() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(running())));
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert_eq!(
+            fake.mutations(),
+            [format!("ensure_namespace {}", cfg.namespace)],
+            "the no-op row mutated something"
+        );
+    }
+
+    /// ...including when the desired intent has diverged. Edits reach a
+    /// started pod only via the next generation (`:861-865`).
+    #[test]
+    fn started_pod_no_ops_under_divergent_intent() {
+        let id = identity();
+        let cfg = config();
+        let mut pod = our_pod(&id, &cfg, Some(running()));
+        pod.metadata.annotations.as_mut().unwrap().insert(
+            ANNOTATION_CREATE_INTENT.to_string(),
+            "stale-fingerprint".into(),
+        );
+        let fake = Fake::default().with_pod(pod);
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "divergence deleted a started pod"
+        );
+    }
+
+    /// Terminated → fenced delete → disappearance → recreate. The normal
+    /// restart path, and the fence must carry the observed uid/rv.
+    #[test]
+    fn terminated_pod_is_replaced_with_a_fenced_delete() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(terminated())));
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                if let Some(pod) = pods.get_mut(&name) {
+                    if pod
+                        .status
+                        .as_ref()
+                        .and_then(|s| s.container_statuses.as_ref())
+                        .is_none()
+                    {
+                        pod.status = Some(PodStatus {
+                            phase: Some("Running".into()),
+                            container_statuses: Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(running()),
+                                ..Default::default()
+                            }]),
+                            ..Default::default()
+                        });
+                    }
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        let calls = fake.mutations();
+        assert!(
+            calls
+                .iter()
+                .any(|c| c == &format!("delete_pod {} uid=uid-1 rv=100", id.pod_name())),
+            "delete was not fenced to the observed uid+resourceVersion: {calls:?}"
+        );
+        assert!(calls.iter().any(|c| c.starts_with("create_pod")));
+    }
+
+    /// A failed precondition is neither an error nor permission to retry the
+    /// delete: re-enter and classify what exists now (`:775-777`). Here the
+    /// object has become a *started* pod, so the correct outcome is the no-op
+    /// row — never a second delete with a fresher fence.
+    #[test]
+    fn precondition_failure_reclassifies_instead_of_retrying() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(terminated())));
+        fake.delete_outcomes
+            .borrow_mut()
+            .push(DeleteOutcome::PreconditionFailed);
+        // The writer we lost the race to: between our observation and our
+        // delete, the pod under this name became a *started* one with a new
+        // resourceVersion. Installed on the poll that follows the failed
+        // precondition, so the sequence is observe → delete → lose → re-observe.
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            let started = {
+                let mut p = our_pod(&id, &cfg, Some(running()));
+                p.metadata.resource_version = Some("200".into());
+                p
+            };
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                pods.insert(name.clone(), started.clone());
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        let deletes: Vec<_> = fake
+            .mutations()
+            .into_iter()
+            .filter(|c| c.starts_with("delete_pod"))
+            .collect();
+        // Two call sites legitimately target a terminated pod: preflight GC's
+        // sweep (which is the one that loses the precondition here) and the
+        // state machine's terminated row. Both are fenced on their own
+        // observation. What must never happen is a *third* — a retry of the
+        // failed delete — so the invariant is the fence, not the count: every
+        // delete carries rv=100, the version we observed. A retry would carry
+        // the racing writer's rv=200.
+        assert_eq!(deletes.len(), 2, "unexpected delete traffic: {deletes:?}");
+        assert!(
+            deletes.iter().all(|d| d.contains("rv=100")),
+            "retried with a fresher fence: {deletes:?}"
+        );
+    }
+
+    /// The anti-livelock rule, at the loop level: a recoverable pod whose
+    /// intent matches is observed until the deadline and **never** deleted —
+    /// the case that would otherwise reset the pod age Cluster Autoscaler
+    /// keys on (`:689`).
+    #[test]
+    fn recoverable_pod_with_matching_intent_is_never_deleted() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(waiting("Unschedulable"))));
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("startup not confirmed"), "got: {err}");
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "deleted a recoverable pod: {:?}",
+            fake.mutations()
+        );
+        assert!(fake.elapsed() >= DEADLINE, "gave up before the deadline");
+    }
+
+    /// The same pod, provisioned late: the observation loop must *succeed*
+    /// when the autoscaler eventually lands the node, not merely avoid
+    /// deleting.
+    #[test]
+    fn recoverable_pod_that_starts_late_succeeds() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(waiting("Unschedulable"))));
+        let polls = RefCell::new(0);
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                *polls.borrow_mut() += 1;
+                if *polls.borrow() >= 5 {
+                    if let Some(pod) = pods.get_mut(&name) {
+                        pod.status.as_mut().unwrap().container_statuses =
+                            Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(running()),
+                                ..Default::default()
+                            }]);
+                    }
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(fake.elapsed() < DEADLINE);
+    }
+
+    /// A permanent pull failure reports immediately rather than burning the
+    /// deadline — and still never deletes.
+    #[test]
+    fn permanent_pull_failure_reports_without_deleting() {
+        let id = identity();
+        let cfg = config();
+        let mut pod = our_pod(&id, &cfg, None);
+        pod.status = Some(PodStatus {
+            phase: Some("Pending".into()),
+            container_statuses: Some(vec![ContainerStatus {
+                name: crate::observe::CONTAINER_NAME.into(),
+                state: Some(ContainerState {
+                    waiting: Some(ContainerStateWaiting {
+                        reason: Some("ImagePullBackOff".into()),
+                        message: Some("manifest unknown".into()),
+                    }),
+                    ..Default::default()
+                }),
+                ..Default::default()
+            }]),
+            ..Default::default()
+        });
+        let fake = Fake::default().with_pod(pod);
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("no image at"), "got: {err}");
+        assert!(
+            fake.elapsed() < DEADLINE,
+            "burned the deadline on a permanent failure"
+        );
+        assert!(!fake.mutations().iter().any(|c| c.starts_with("delete_pod")));
+    }
+
+    /// The kubelet's pull *message* can echo a registry request; only the
+    /// classified outcome and the image reference reach the user.
+    #[test]
+    fn pull_failure_message_is_not_echoed_verbatim() {
+        let id = identity();
+        let cfg = config();
+        let mut pod = our_pod(&id, &cfg, None);
+        pod.status = Some(PodStatus {
+            phase: Some("Pending".into()),
+            container_statuses: Some(vec![ContainerStatus {
+                name: crate::observe::CONTAINER_NAME.into(),
+                state: Some(ContainerState {
+                    waiting: Some(ContainerStateWaiting {
+                        reason: Some("ErrImagePull".into()),
+                        message: Some(
+                            "unauthorized: authentication required, token=SUPERSECRET".into(),
+                        ),
+                    }),
+                    ..Default::default()
+                }),
+                ..Default::default()
+            }]),
+            ..Default::default()
+        });
+        let fake = Fake::default().with_pod(pod);
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(
+            !err.contains("SUPERSECRET"),
+            "kubelet message echoed: {err}"
+        );
+    }
+
+    /// A pod being gracefully deleted stays in phase `Running` for its whole
+    /// grace period. The reconciler must wait it out and recreate, not return
+    /// an id that evaporates.
+    #[test]
+    fn deletion_marked_pod_is_awaited_then_recreated() {
+        let id = identity();
+        let cfg = config();
+        let mut dying = our_pod(&id, &cfg, Some(running()));
+        dying.metadata.deletion_timestamp = Some(Time(Utc::now()));
+        let fake = Fake::default().with_pod(dying);
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                match pods
+                    .get(&name)
+                    .map(|p| p.metadata.deletion_timestamp.is_some())
+                {
+                    // The grace period elapses: the object disappears.
+                    Some(true) => {
+                        pods.remove(&name);
+                    }
+                    // The replacement we create then starts.
+                    Some(false) => {
+                        let pod = pods.get_mut(&name).unwrap();
+                        pod.status = Some(PodStatus {
+                            phase: Some("Running".into()),
+                            container_statuses: Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(running()),
+                                ..Default::default()
+                            }]),
+                            ..Default::default()
+                        });
+                    }
+                    None => {}
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "deleted a pod that was already terminating"
+        );
+    }
+
+    /// `CreateContainerConfigError` is settled by a most-recent Secret read,
+    /// never by the reason string: Secret present → recoverable (observe).
+    #[test]
+    fn config_error_with_a_present_secret_is_recoverable() {
+        let id = identity();
+        let cfg = config();
+        let pod = our_pod(&id, &cfg, Some(waiting("CreateContainerConfigError")));
+        let referenced = crate::observe::referenced_secret(&pod).unwrap();
+        let fake = Fake::default().with_pod(pod);
+        fake.secrets.borrow_mut().push(crate::pod::build_secret(
+            &id,
+            &cfg.namespace,
+            "gen-existing",
+            env(),
+        ));
+        assert_eq!(referenced, id.secret_name("gen-existing"));
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("startup not confirmed"), "got: {err}");
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "deleted a pod whose Secret exists"
+        );
+    }
+
+    /// ...and Secret confirmed absent → provably broken → fenced replace.
+    #[test]
+    fn config_error_with_a_confirmed_absent_secret_is_replaced() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(
+            &id,
+            &cfg,
+            Some(waiting("CreateContainerConfigError")),
+        ));
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                if let Some(pod) = pods.get_mut(&name) {
+                    if pod
+                        .status
+                        .as_ref()
+                        .and_then(|s| s.container_statuses.as_ref())
+                        .is_none()
+                    {
+                        pod.status = Some(PodStatus {
+                            phase: Some("Running".into()),
+                            container_statuses: Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(running()),
+                                ..Default::default()
+                            }]),
+                            ..Default::default()
+                        });
+                    }
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(fake.mutations().iter().any(|c| c.starts_with("delete_pod")));
+    }
+
+    /// The generation is the Secret's name suffix *and* the lifecycle
+    /// correlator inside it. They must name the same generation, or pod logs
+    /// point at a Secret that was never mounted. The caller stamps one
+    /// generation into the env once; each create attempt mints its own, so
+    /// only a restamp keeps the pair together across a retry.
+    #[test]
+    fn each_attempt_stamps_its_own_generation_into_its_own_secret() {
+        let id = identity();
+        let cfg = config();
+        // First attempt loses the create race and is cleaned up; the operation
+        // then adopts. Two creates, two generations.
+        let fake = Fake::default();
+        *fake.winner.borrow_mut() = Some(our_pod(&id, &cfg, Some(running())));
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+
+        run(&fake, &id, &cfg).unwrap();
+
+        let created = fake.created_secrets.borrow();
+        // Guard the guard: this assertion is over a list that cleanup empties,
+        // so an empty list would make every check below vacuously true.
+        assert_eq!(created.len(), 1, "expected one create attempt");
+        for secret in created.iter() {
+            let name = secret.metadata.name.as_deref().unwrap();
+            let nonce = secret
+                .string_data
+                .as_ref()
+                .and_then(|d| d.get(crate::env::START_NONCE_KEY))
+                .expect("no lifecycle correlator in the Secret");
+            assert!(
+                name.ends_with(nonce.as_str()),
+                "secret {name} carries a correlator for a different generation ({nonce})"
+            );
+        }
+    }
+
+    // ---- bounded replacement ------------------------------------------------
+
+    /// Installs a hook that makes every pod under `name` crash-exit before the
+    /// next poll — a deterministic startup failure (the harness starts, rejects
+    /// its configuration, and exits) as observed live: the container reaches
+    /// `state.terminated` with a nonzero exit code.
+    fn crash_exits_immediately(fake: &Fake, name: String) {
+        fake.on_poll
+            .borrow_mut()
+            .push(Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                if let Some(pod) = pods.get_mut(&name) {
+                    if pod
+                        .status
+                        .as_ref()
+                        .and_then(|s| s.container_statuses.as_ref())
+                        .is_none()
+                    {
+                        pod.status = Some(PodStatus {
+                            phase: Some("Failed".into()),
+                            container_statuses: Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(ContainerState {
+                                    terminated: Some(ContainerStateTerminated {
+                                        exit_code: 1,
+                                        reason: Some("Error".into()),
+                                        ..Default::default()
+                                    }),
+                                    ..Default::default()
+                                }),
+                                ..Default::default()
+                            }]),
+                            ..Default::default()
+                        });
+                    }
+                }
+            }));
+    }
+
+    /// A pod that this call created and that crash-exits deterministically is
+    /// reported in-band after exactly ONE attempt — never hot-replaced until
+    /// the deadline. The live failure this pins: one delete/create cycle every
+    /// ~4s minted 107 immutable Secrets in a single 600s deploy call, all
+    /// younger than the orphan sweep's age gate.
+    #[test]
+    fn a_deterministic_crash_exit_is_reported_not_hot_replaced() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default();
+        crash_exits_immediately(&fake, id.pod_name());
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+
+        let creates = fake
+            .mutations()
+            .iter()
+            .filter(|c| c.starts_with("create_secret"))
+            .count();
+        assert_eq!(
+            creates, 1,
+            "hot replacement loop: {creates} Secrets minted in one deploy call"
+        );
+        assert!(
+            err.contains("exited with code 1"),
+            "error does not carry the exit: {err}"
+        );
+        // The failed attempt is left in place as evidence — no cleanup on the
+        // error path. Its Secret stays referenced by the terminated pod, so
+        // the next deploy's preflight GC collects both together.
+        assert!(
+            !fake
+                .mutations()
+                .iter()
+                .any(|c| c.starts_with("delete_pod") || c.starts_with("delete_secret")),
+            "the failed attempt was cleaned up on the error path: {:?}",
+            fake.mutations()
+        );
+        assert!(
+            fake.elapsed() < DEADLINE,
+            "burned the whole deadline on a deterministic failure"
+        );
+    }
+
+    /// The revive path is untouched: terminated residue from a *previous*
+    /// life is still replaced — the bound is on pods this call created, not
+    /// on the row.
+    #[test]
+    fn pre_existing_terminated_residue_is_still_replaced_once() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(terminated())));
+        crash_exits_immediately(&fake, id.pod_name());
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("exited with code 1"), "got: {err}");
+
+        let calls = fake.mutations();
+        let deletes = calls.iter().filter(|c| c.starts_with("delete_pod")).count();
+        let creates = calls
+            .iter()
+            .filter(|c| c.starts_with("create_secret"))
+            .count();
+        // Exactly one residue delete (the normal restart path) and one fresh
+        // attempt — then report, not another cycle.
+        assert_eq!(deletes, 1, "unexpected delete traffic: {calls:?}");
+        assert_eq!(creates, 1, "unexpected create traffic: {calls:?}");
+    }
+
+    /// Retry is gated on fresh owner intent: the *next* deploy call clears
+    /// the crashed attempt (preflight GC collects the terminated pod and its
+    /// referenced Secret together) and makes exactly one new attempt — total
+    /// litter stays one pod + one Secret however many times Start is pressed.
+    #[test]
+    fn the_next_deploy_collects_the_crashed_attempt_before_its_own_attempt() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default();
+        crash_exits_immediately(&fake, id.pod_name());
+
+        run(&fake, &id, &cfg).unwrap_err();
+        // Second Start: fresh call, fresh clock.
+        *fake.elapsed.borrow_mut() = Duration::ZERO;
+        run(&fake, &id, &cfg).unwrap_err();
+
+        assert_eq!(
+            fake.secrets.borrow().len(),
+            1,
+            "crashed attempts accumulated Secrets across calls"
+        );
+        assert_eq!(fake.pods.borrow().len(), 1, "crashed pods accumulated");
+    }
+
+    // ---- the auto-repair fence ----------------------------------------------
+
+    /// An object under our deterministic name that lacks the management
+    /// marker is not ours. The reconciler must not adopt it, delete it, or
+    /// return its name — it fails closed to the operator (`:1156-1162`).
+    #[test]
+    fn an_unmarked_look_alike_is_never_touched_or_adopted() {
+        let id = identity();
+        let cfg = config();
+        let mut look_alike = our_pod(&id, &cfg, Some(running()));
+        look_alike
+            .metadata
+            .labels
+            .as_mut()
+            .unwrap()
+            .remove(LABEL_MANAGED_BY);
+        let fake = Fake::default();
+        // Our create loses to the object already sitting on the name.
+        *fake.winner.borrow_mut() = Some(look_alike);
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("not managed by this provider"), "got: {err}");
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "deleted an object we do not own"
+        );
+    }
+
+    /// Same fence, other direction: the marker is present but the annotation
+    /// carries a different agent's pubkey. The 32-hex label is
+    /// collision-resistant, not collision-free (`:1152-1155`).
+    #[test]
+    fn a_pubkey_mismatch_is_never_adopted() {
+        let id = identity();
+        let other = identity();
+        let cfg = config();
+        let mut foreign = our_pod(&id, &cfg, Some(running()));
+        foreign.metadata.annotations.as_mut().unwrap().insert(
+            ANNOTATION_PUBKEY_FULL.to_string(),
+            other.pubkey_hex().to_string(),
+        );
+        let fake = Fake::default();
+        *fake.winner.borrow_mut() = Some(foreign);
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("different agent identity"), "got: {err}");
+        assert!(!fake.mutations().iter().any(|c| c.starts_with("delete_pod")));
+    }
+
+    // ---- create-conflict convergence ---------------------------------------
+
+    /// The loser adopts the winner, returns the winner's id, and deletes
+    /// **only its own** Secret — never the winner's (`:1259-1264`).
+    #[test]
+    fn create_loser_adopts_the_winner_and_drops_only_its_own_secret() {
+        let id = identity();
+        let cfg = config();
+        let winner = our_pod(&id, &cfg, Some(running()));
+        let winners_secret = crate::observe::referenced_secret(&winner).unwrap();
+        let fake = Fake::default();
+        *fake.winner.borrow_mut() = Some(winner);
+        fake.secrets.borrow_mut().push(crate::pod::build_secret(
+            &id,
+            &cfg.namespace,
+            "gen-existing",
+            env(),
+        ));
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+
+        let deleted: Vec<_> = fake
+            .mutations()
+            .into_iter()
+            .filter(|c| c.starts_with("delete_secret"))
+            .collect();
+        assert_eq!(
+            deleted.len(),
+            1,
+            "expected exactly our own Secret dropped: {deleted:?}"
+        );
+        assert!(
+            !deleted[0].contains(&winners_secret),
+            "deleted the winner's Secret: {deleted:?}"
+        );
+        assert!(
+            fake.secrets
+                .borrow()
+                .iter()
+                .any(|s| s.metadata.name.as_deref() == Some(winners_secret.as_str())),
+            "the winner's Secret is gone"
+        );
+    }
+
+    /// The loser must not apply the divergence row to the pod that just beat
+    /// it — that is the ping-pong the spec forbids (`:845-850`). A divergent
+    /// *started* winner is adopted as-is.
+    #[test]
+    fn create_loser_does_not_replace_a_divergent_winner() {
+        let id = identity();
+        let cfg = config();
+        let mut winner = our_pod(&id, &cfg, Some(running()));
+        winner.metadata.annotations.as_mut().unwrap().insert(
+            ANNOTATION_CREATE_INTENT.to_string(),
+            "a-different-intent".into(),
+        );
+        let fake = Fake::default();
+        *fake.winner.borrow_mut() = Some(winner);
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(
+            !fake.mutations().iter().any(|c| c.starts_with("delete_pod")),
+            "the create loser deleted the winner"
+        );
+    }
+
+    /// The loser waits for the winner to *start* — adopting a not-yet-started
+    /// winner as success would report an agent that is not running.
+    #[test]
+    fn create_loser_waits_for_the_winner_to_start() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default();
+        *fake.winner.borrow_mut() = Some(our_pod(&id, &cfg, Some(waiting("ContainerCreating"))));
+        fake.create_outcomes
+            .borrow_mut()
+            .push(CreateOutcome::AlreadyExists);
+        let polls = RefCell::new(0);
+        fake.on_poll.borrow_mut().push({
+            let name = id.pod_name();
+            Box::new(move |pods: &mut BTreeMap<String, Pod>| {
+                *polls.borrow_mut() += 1;
+                if *polls.borrow() >= 3 {
+                    if let Some(pod) = pods.get_mut(&name) {
+                        pod.status.as_mut().unwrap().container_statuses =
+                            Some(vec![ContainerStatus {
+                                name: crate::observe::CONTAINER_NAME.into(),
+                                state: Some(running()),
+                                ..Default::default()
+                            }]);
+                    }
+                }
+            })
+        });
+
+        assert_eq!(run(&fake, &id, &cfg).unwrap(), id.pod_name());
+        assert!(fake.elapsed() > Duration::ZERO, "did not wait at all");
+    }
+
+    // ---- deadline and namespace --------------------------------------------
+
+    /// Deadline expiry reports the *latest* condition, not a generic timeout
+    /// (`:699-701`), and triggers no cleanup (`:720-724`).
+    #[test]
+    fn deadline_expiry_reports_the_condition_and_cleans_up_nothing() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake::default().with_pod(our_pod(&id, &cfg, Some(waiting("ContainerCreating"))));
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("ContainerCreating"), "generic timeout: {err}");
+        let calls = fake.mutations();
+        assert!(
+            !calls.iter().any(|c| c.starts_with("delete_")),
+            "deadline expiry triggered cleanup: {calls:?}"
+        );
+    }
+
+    /// An RBAC denial on namespace create fails the deploy with the literal
+    /// command to run, before any Secret is written (`:1002-1005`).
+    #[test]
+    fn namespace_denial_fails_before_writing_any_secret() {
+        let id = identity();
+        let cfg = config();
+        let fake = Fake {
+            namespace_error: Some(format!(
+                "not authorized to create namespaces: run `kubectl create namespace {}`",
+                cfg.namespace
+            )),
+            ..Default::default()
+        };
+
+        let err = run(&fake, &id, &cfg).unwrap_err();
+        assert!(err.contains("kubectl create namespace"), "got: {err}");
+        assert!(
+            fake.mutations().is_empty(),
+            "wrote something after a namespace denial: {:?}",
+            fake.mutations()
+        );
+    }
+
+    /// GC failures are hygiene, not deploy failures: a list the user cannot
+    /// perform must not block a deploy they can.
+    #[test]
+    fn a_gc_failure_does_not_fail_the_deploy() {
+        struct GcDenied(Fake);
+        impl Substrate for GcDenied {
+            async fn ensure_namespace(&self, ns: &str) -> Result<(), String> {
+                self.0.ensure_namespace(ns).await
+            }
+            async fn list_pods(
+                &self,
+                _s: &str,
+            ) -> Result<(Vec<Pod>, Option<DateTime<Utc>>), String> {
+                Err("forbidden: cannot list pods".into())
+            }
+            async fn list_secrets(&self, _s: &str) -> Result<Vec<Secret>, String> {
+                Err("forbidden: cannot list secrets".into())
+            }
+            async fn secret_exists(&self, n: &str) -> Result<bool, String> {
+                self.0.secret_exists(n).await
+            }
+            async fn create_secret(&self, s: &Secret) -> Result<(), String> {
+                self.0.create_secret(s).await
+            }
+            async fn create_pod(&self, p: &Pod) -> Result<CreateOutcome, String> {
+                self.0.create_pod(p).await
+            }
+            async fn delete_pod(&self, n: &str, f: &Fence) -> Result<DeleteOutcome, String> {
+                self.0.delete_pod(n, f).await
+            }
+            async fn delete_secret(&self, n: &str) -> Result<(), String> {
+                self.0.delete_secret(n).await
+            }
+            async fn get_pod(&self, n: &str) -> Result<Option<Pod>, String> {
+                self.0.get_pod(n).await
+            }
+            async fn sleep(&self, d: Duration) {
+                self.0.sleep(d).await
+            }
+            fn elapsed(&self) -> Duration {
+                self.0.elapsed()
+            }
+        }
+
+        let id = identity();
+        let cfg = config();
+        let inner = Fake::default().with_pod(our_pod(&id, &cfg, Some(running())));
+        let fake = GcDenied(inner);
+
+        assert_eq!(
+            block_on(deploy(&fake, &id, &cfg, env())).unwrap(),
+            id.pod_name()
+        );
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/src/wire.rs b/crates/buzz-backend-kubernetes/src/wire.rs
new file mode 100644
index 0000000000..89b78b364d
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/src/wire.rs
@@ -0,0 +1,250 @@
+//! The stdin/stdout JSON protocol (spec §Provider Protocol).
+//!
+//! One process per operation: one JSON object in, one JSON object out.
+//! These types are this provider's view of the contract; the golden fixtures
+//! in `tests/fixtures/provider-wire/` are the arbiter shared with the desktop.
+
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+/// The wire-contract version this provider speaks (spec §Info).
+pub const PROTOCOL_VERSION: u32 = 1;
+
+/// Request envelope. `op` discriminates; unknown ops are an in-band error.
+///
+/// `request_id` is deliberately absent from every variant. The desktop sends
+/// it, but the exchange is one request and one response per process, so there
+/// is nothing to correlate and nothing in the response schema to echo it into
+/// (`:387`, `:416` — neither response shape carries it). Serde ignores it on
+/// the way in, so a caller that sends it is accepted; typing it would only
+/// create a field nothing reads.
+#[derive(Debug, Deserialize)]
+#[serde(tag = "op", rename_all = "lowercase")]
+pub enum Request {
+    Info,
+    Deploy(Box<DeployRequest>),
+}
+
+#[derive(Debug, Deserialize)]
+pub struct DeployRequest {
+    pub agent: AgentPayload,
+    #[serde(default)]
+    pub provider_config: serde_json::Value,
+}
+
+/// The agent payload (spec §Deploy).
+///
+/// Only the fields this binding actually consumes are typed. `name` (display
+/// name), `model`, `provider`, and `turn_timeout_seconds` are deliberately
+/// absent: object names derive from the pubkey, not the display name
+/// (`:1150-1152`), the model/provider pair arrives already resolved inside
+/// `launch`, and the timeout is ignored upstream — typing any of them would
+/// invite a provider-side remap the spec forbids.
+#[derive(Debug, Deserialize)]
+pub struct AgentPayload {
+    pub relay_url: String,
+    pub private_key_nsec: String,
+    #[serde(default)]
+    pub auth_tag: Option<String>,
+    #[serde(default)]
+    pub respond_to: Option<String>,
+    #[serde(default)]
+    pub respond_to_allowlist: Option<Vec<String>>,
+    /// User env, already merged global < persona < agent by the desktop and
+    /// already stripped of reserved keys. Superseded by `launch.env` when
+    /// `launch` is present — a provider MUST NOT re-merge it on top
+    /// (§Launch data, precedence tier 2).
+    #[serde(default)]
+    pub env_vars: BTreeMap<String, String>,
+    /// The desktop-resolved launch contract. Absent only from a desktop
+    /// predating Known Defect 3's fix.
+    #[serde(default)]
+    pub launch: Option<LaunchBlock>,
+}
+
+/// Desktop-resolved launch data (spec §Launch data).
+#[derive(Debug, Default, Deserialize)]
+pub struct LaunchBlock {
+    /// Command *name*, resolved against the image's PATH — never a host path.
+    #[serde(default)]
+    pub command: Option<String>,
+    #[serde(default)]
+    pub args: Vec<String>,
+    /// Layered env: baked → runtime metadata → definition → global → persona
+    /// → agent. Precedence tier 2.
+    #[serde(default)]
+    pub env: BTreeMap<String, String>,
+    /// Overridable behavior defaults. Precedence tier 1 — user env beats
+    /// these, matching the local spawn.
+    #[serde(default)]
+    pub policy_env: BTreeMap<String, String>,
+    /// Resolved workspace owner (hex). The respond-to gate's one
+    /// irreducible input; without it or `auth_tag` the harness cannot match
+    /// `!shutdown`.
+    #[serde(default)]
+    pub owner_pubkey: Option<String>,
+}
+
+/// Response envelope. Serialized flat — `{"ok": true, …}` — because the
+/// desktop reads `ok`, `error`, and `agent_id` off the top level.
+#[derive(Debug, Serialize)]
+#[serde(untagged)]
+pub enum Response {
+    Info(InfoResponse),
+    Deploy(DeployResponse),
+    Error(ErrorResponse),
+}
+
+#[derive(Debug, Serialize)]
+pub struct InfoResponse {
+    pub ok: bool,
+    pub name: &'static str,
+    pub version: &'static str,
+    pub protocol_version: u32,
+    pub description: &'static str,
+    pub config_schema: serde_json::Value,
+}
+
+#[derive(Debug, Serialize)]
+pub struct DeployResponse {
+    pub ok: bool,
+    pub agent_id: String,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ErrorResponse {
+    pub ok: bool,
+    pub error: String,
+}
+
+impl Response {
+    pub fn error(message: impl Into<String>) -> Self {
+        Response::Error(ErrorResponse {
+            ok: false,
+            error: message.into(),
+        })
+    }
+
+    /// The provider's self-description (spec §Info). Pure — no cluster
+    /// contact — because the desktop calls it to render the config form
+    /// before a kubeconfig is known to exist.
+    pub fn info() -> Self {
+        Response::Info(InfoResponse {
+            ok: true,
+            name: "kubernetes",
+            version: env!("CARGO_PKG_VERSION"),
+            protocol_version: PROTOCOL_VERSION,
+            description: "Runs agents as pods in a Kubernetes cluster",
+            config_schema: crate::config::config_schema(),
+        })
+    }
+
+    pub fn deployed(agent_id: impl Into<String>) -> Self {
+        Response::Deploy(DeployResponse {
+            ok: true,
+            agent_id: agent_id.into(),
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_info_request() {
+        let r: Request = serde_json::from_str(r#"{"op":"info","request_id":"abc"}"#).unwrap();
+        assert!(matches!(r, Request::Info));
+    }
+
+    /// The desktop sends `request_id` on every call, but the exchange is 1:1
+    /// per process — a provider that hard-required it would fail a
+    /// conforming-but-minimal caller for no safety gain.
+    #[test]
+    fn request_id_is_optional() {
+        let r: Request = serde_json::from_str(r#"{"op":"info"}"#).unwrap();
+        assert!(matches!(r, Request::Info));
+    }
+
+    #[test]
+    fn rejects_unknown_op() {
+        assert!(serde_json::from_str::<Request>(r#"{"op":"undeploy"}"#).is_err());
+    }
+
+    /// Payload fields this binding does not consume must not break parsing:
+    /// the desktop sends `model`, `provider`, `system_prompt` and more, and a
+    /// provider that rejected them would break on every real deploy.
+    #[test]
+    fn ignores_unconsumed_payload_fields() {
+        let json = r#"{
+            "op":"deploy","request_id":"r1",
+            "agent":{
+                "name":"a","relay_url":"wss://r","private_key_nsec":"nsec1x",
+                "model":"gpt-5","provider":"openai","system_prompt":"hi",
+                "turn_timeout_seconds":30,"parallelism":10,
+                "agent_command":"goose","agent_args":[]
+            },
+            "provider_config":{"namespace":"ns"}
+        }"#;
+        let r: Request = serde_json::from_str(json).unwrap();
+        let Request::Deploy(d) = r else {
+            panic!("wrong op")
+        };
+        assert_eq!(d.agent.relay_url, "wss://r");
+        assert!(d.agent.launch.is_none());
+    }
+
+    #[test]
+    fn parses_launch_block() {
+        let json = r#"{
+            "op":"deploy",
+            "agent":{
+                "relay_url":"wss://r","private_key_nsec":"nsec1x",
+                "launch":{
+                    "command":"goose","args":["run","--x"],
+                    "env":{"GOOSE_MODEL":"m"},
+                    "policy_env":{"GOOSE_MODE":"auto"},
+                    "owner_pubkey":"deadbeef"
+                }
+            }
+        }"#;
+        let Request::Deploy(d) = serde_json::from_str::<Request>(json).unwrap() else {
+            panic!("wrong op")
+        };
+        let l = d.agent.launch.unwrap();
+        assert_eq!(l.command.as_deref(), Some("goose"));
+        assert_eq!(l.args, ["run", "--x"]);
+        assert_eq!(l.env["GOOSE_MODEL"], "m");
+        assert_eq!(l.policy_env["GOOSE_MODE"], "auto");
+        assert_eq!(l.owner_pubkey.as_deref(), Some("deadbeef"));
+    }
+
+    /// A null `owner_pubkey`/`auth_tag` must parse (the refusal is a policy
+    /// decision made later, with a specific message), not fail as a type error.
+    #[test]
+    fn null_owner_fields_parse() {
+        let json = r#"{"op":"deploy","agent":{
+            "relay_url":"wss://r","private_key_nsec":"nsec1x","auth_tag":null,
+            "launch":{"owner_pubkey":null}
+        }}"#;
+        let Request::Deploy(d) = serde_json::from_str::<Request>(json).unwrap() else {
+            panic!("wrong op")
+        };
+        assert!(d.agent.auth_tag.is_none());
+        assert!(d.agent.launch.unwrap().owner_pubkey.is_none());
+    }
+
+    /// The desktop reads `ok`/`error`/`agent_id` off the top level, so the
+    /// enum must serialize flat with no variant tag.
+    #[test]
+    fn responses_serialize_flat() {
+        let v = serde_json::to_value(Response::deployed("buzz-agent-abc")).unwrap();
+        assert_eq!(v["ok"], true);
+        assert_eq!(v["agent_id"], "buzz-agent-abc");
+        assert!(v.get("Deploy").is_none());
+
+        let v = serde_json::to_value(Response::error("boom")).unwrap();
+        assert_eq!(v["ok"], false);
+        assert_eq!(v["error"], "boom");
+    }
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/README.md b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/README.md
new file mode 100644
index 0000000000..56a972f894
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/README.md
@@ -0,0 +1,39 @@
+# Provider wire fixtures
+
+The shared arbiter for the stdin/stdout contract between the desktop
+(`agents_deploy.rs`) and this provider (spec §Provider Protocol).
+
+Each `*.request.json` is a request the desktop can emit; each matching
+`*.response.json` is the exact response this provider produces for it. The
+provider side is asserted by `tests/wire_fixtures.rs`; the desktop side should
+assert that its emitted payloads parse as the corresponding request.
+
+Three rules keep these useful rather than decorative:
+
+* **Requests are recorded, not invented.** A fixture that no caller emits
+  tests a contract nobody has. "Recorded" means *executed and transcribed* —
+  `deploy-full-launch.request.json` is the output of the desktop's real
+  `build_launch_block` → `deploy_payload_json` path, not a shape derived by
+  reading those functions. Deriving it is how this fixture acquired four
+  impossible values at once: a `respond_to` that was a pubkey where the
+  desktop serializes a kebab-case `RespondTo` enum, allowlist and owner
+  values failing `validate_respond_to_allowlist`'s 64-hex rule
+  (`types.rs:897`), an invented `BUZZ_ACP_PARALLELISM` where the emitter
+  writes `BUZZ_ACP_AGENTS` (`runtime.rs:729`), and a `launch.env` key from
+  no layer of `resolve_effective_harness_descriptor`.
+* **The provider cannot police this file, so the desktop must.** Every field
+  above is one this provider is deliberately indifferent to — `respond_to` is
+  an opaque `Option<String>`, the allowlist an opaque `Vec<String>`,
+  `policy_env` an arbitrary map — so `the_full_desktop_payload_is_accepted`
+  passes on invented data exactly as happily as on recorded data. The
+  enforcement is the desktop's whole-object equality test, which *builds* the
+  payload and compares it to this file. A completeness guard (the case-list
+  directory scan in `wire_fixtures.rs`) stops a case from going missing; it
+  cannot tell you a case is false.
+* **Responses are byte-compared after key-sorted re-serialization**, so a
+  field rename or a type change fails here rather than in a desktop that
+  silently reads `undefined`.
+
+`deploy-*` fixtures cover only responses reachable without a cluster —
+refusals and malformed input. A successful deploy needs an apiserver and is
+covered by the conformance suite, not by a static fixture.
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-full-launch.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-full-launch.request.json
new file mode 100644
index 0000000000..28fe6ce90e
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-full-launch.request.json
@@ -0,0 +1,52 @@
+{
+  "op": "deploy",
+  "request_id": "req-6",
+  "agent": {
+    "agent_args": [],
+    "agent_command": "goose",
+    "auth_tag": "tag-1",
+    "env_vars": {
+      "USER_KEY": "user-value"
+    },
+    "idle_timeout_seconds": null,
+    "launch": {
+      "args": [
+        "acp"
+      ],
+      "command": "goose",
+      "env": {
+        "GOOSE_MODEL": "gpt-5",
+        "GOOSE_PROVIDER": "openai",
+        "USER_KEY": "user-value"
+      },
+      "owner_pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "policy_env": {
+        "BUZZ_ACP_AGENTS": "10",
+        "BUZZ_ACP_LAZY_POOL": "true",
+        "BUZZ_ACP_MODEL": "gpt-5",
+        "BUZZ_ACP_RELAY_OBSERVER": "true",
+        "BUZZ_ACP_SESSION_TITLE": "worker",
+        "GOOSE_MODE": "auto"
+      }
+    },
+    "max_turn_duration_seconds": null,
+    "model": "gpt-5",
+    "name": "worker",
+    "parallelism": 10,
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+    "provider": "openai",
+    "relay_url": "wss://relay.example",
+    "respond_to": "allowlist",
+    "respond_to_allowlist": [
+      "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+    ],
+    "system_prompt": null,
+    "turn_timeout_seconds": 300
+  },
+  "provider_config": {
+    "namespace": "buzz-agents-test",
+    "image": "ghcr.io/block/buzz-sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "inactivity_seconds": 3600
+  }
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.request.json
new file mode 100644
index 0000000000..4f56082bbb
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.request.json
@@ -0,0 +1,9 @@
+{
+  "op": "deploy",
+  "request_id": "req-5",
+  "agent": {
+    "relay_url": "wss://relay.example",
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5"
+  },
+  "provider_config": {"namespace": "buzz-agents-test", "image": "ghcr.io/block/buzz-sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.response.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.response.json
new file mode 100644
index 0000000000..c6011b899a
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-no-owner.response.json
@@ -0,0 +1 @@
+{"ok":false,"error":"deploy refused: neither auth_tag nor launch.owner_pubkey resolved — without an owner the agent cannot honor !shutdown"}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.request.json
new file mode 100644
index 0000000000..2160909b8f
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.request.json
@@ -0,0 +1,11 @@
+{
+  "op": "deploy",
+  "request_id": "req-3",
+  "agent": {
+    "relay_url": "wss://relay.example",
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+    "auth_tag": "tag-1",
+    "provider": "  relay-mesh  "
+  },
+  "provider_config": {"namespace": "buzz-agents-test", "image": "ghcr.io/block/buzz-sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.response.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.response.json
new file mode 100644
index 0000000000..0f0c995fd8
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh-padded.response.json
@@ -0,0 +1 @@
+{"ok":false,"error":"deploy refused: this agent is configured for shared compute (relay-mesh), which runs on the relay rather than in a pod. Switch the agent to a local runtime before deploying it to Kubernetes."}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.request.json
new file mode 100644
index 0000000000..71ce9f067e
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.request.json
@@ -0,0 +1,12 @@
+{
+  "op": "deploy",
+  "request_id": "req-2",
+  "agent": {
+    "name": "mesh-agent",
+    "relay_url": "wss://relay.example",
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+    "auth_tag": "tag-1",
+    "provider": "relay-mesh"
+  },
+  "provider_config": {"namespace": "buzz-agents-test", "image": "ghcr.io/block/buzz-sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.response.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.response.json
new file mode 100644
index 0000000000..0f0c995fd8
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-relay-mesh.response.json
@@ -0,0 +1 @@
+{"ok":false,"error":"deploy refused: this agent is configured for shared compute (relay-mesh), which runs on the relay rather than in a pod. Switch the agent to a local runtime before deploying it to Kubernetes."}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.request.json
new file mode 100644
index 0000000000..232d9dcf43
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.request.json
@@ -0,0 +1,10 @@
+{
+  "op": "deploy",
+  "request_id": "req-4",
+  "agent": {
+    "relay_url": "wss://relay.example",
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+    "auth_tag": "tag-1"
+  },
+  "provider_config": {"namespace": "buzz-agents-test", "image": "ghcr.io/block/buzz-sprig:latest"}
+}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.response.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.response.json
new file mode 100644
index 0000000000..e67fa6a47f
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-tag-image.response.json
@@ -0,0 +1 @@
+{"ok":false,"error":"provider_config.image \"ghcr.io/block/buzz-sprig:latest\" is not digest-pinned: a tag is a mutable pointer, and this object runs with the agent's private key. Use name@sha256:<64 hex chars>"}
diff --git a/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/info.request.json b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/info.request.json
new file mode 100644
index 0000000000..db99c86c00
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/info.request.json
@@ -0,0 +1 @@
+{"op":"info","request_id":"req-1"}
diff --git a/crates/buzz-backend-kubernetes/tests/wire_fixtures.rs b/crates/buzz-backend-kubernetes/tests/wire_fixtures.rs
new file mode 100644
index 0000000000..b3049a98ef
--- /dev/null
+++ b/crates/buzz-backend-kubernetes/tests/wire_fixtures.rs
@@ -0,0 +1,222 @@
+//! Golden wire fixtures (spec §Provider Protocol).
+//!
+//! These drive the **built binary** over a real pipe rather than calling an
+//! in-process function: the contract the desktop depends on is
+//! `stdin → one JSON object on stdout → exit code`, and an in-process test
+//! would assert the shape of a value while skipping the three things that
+//! actually break — the process writing nothing, writing two objects, or
+//! signalling the outcome through the exit code.
+
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::process::{Command, Stdio};
+
+fn fixtures() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/provider-wire")
+}
+
+/// Feed one request to the binary; return `(stdout, exit code)`.
+fn run(request: &str) -> (String, i32) {
+    let mut child = Command::new(env!("CARGO_BIN_EXE_buzz-backend-kubernetes"))
+        // A kubeconfig that does not exist, so a fixture that accidentally
+        // reaches the cluster fails loudly here instead of depending on
+        // whatever cluster the developer is pointed at.
+        .env("KUBECONFIG", "/nonexistent/kubeconfig-for-fixture-tests")
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .spawn()
+        .expect("could not run the provider binary");
+    child
+        .stdin
+        .take()
+        .expect("no stdin")
+        .write_all(request.as_bytes())
+        .expect("could not write the request");
+    let out = child.wait_with_output().expect("provider did not exit");
+    (
+        String::from_utf8(out.stdout).expect("stdout was not UTF-8"),
+        out.status.code().unwrap_or(-1),
+    )
+}
+
+fn read(name: &str) -> String {
+    std::fs::read_to_string(fixtures().join(name))
+        .unwrap_or_else(|e| panic!("could not read fixture {name}: {e}"))
+}
+
+/// Every response fixture, byte-compared after key-sorted re-serialization so
+/// a field rename fails here rather than in a desktop reading `undefined`.
+#[test]
+fn responses_match_their_fixtures() {
+    let cases = [
+        "deploy-relay-mesh",
+        "deploy-relay-mesh-padded",
+        "deploy-tag-image",
+        "deploy-no-owner",
+    ];
+    // The list must cover every response fixture on disk. A literal array is
+    // never empty, so `!is_empty()` would assert nothing; what can actually go
+    // wrong is a fixture added to the directory and never added here, which
+    // reads as a passing suite that exercises one case fewer than it appears to.
+    let mut on_disk: Vec<String> = std::fs::read_dir(fixtures())
+        .expect("could not read the fixture directory")
+        .filter_map(|entry| entry.ok()?.file_name().into_string().ok())
+        .filter_map(|name| Some(name.strip_suffix(".response.json")?.to_string()))
+        .collect();
+    on_disk.sort();
+    let mut listed: Vec<String> = cases.iter().map(|c| c.to_string()).collect();
+    listed.sort();
+    assert_eq!(on_disk, listed, "response fixtures and cases disagree");
+
+    for case in cases {
+        let (stdout, code) = run(&read(&format!("{case}.request.json")));
+        assert_eq!(code, 0, "{case}: a produced response must exit 0");
+
+        // Exactly one object, terminated by exactly one newline. Two responses
+        // would leave the desktop's reader holding a second one forever.
+        assert_eq!(
+            stdout.matches('\n').count(),
+            1,
+            "{case}: expected exactly one line, got {stdout:?}"
+        );
+
+        let actual: serde_json::Value =
+            serde_json::from_str(&stdout).unwrap_or_else(|e| panic!("{case}: {e}: {stdout:?}"));
+        let expected: serde_json::Value =
+            serde_json::from_str(&read(&format!("{case}.response.json"))).unwrap();
+        assert_eq!(
+            actual, expected,
+            "{case}: response drifted from its fixture"
+        );
+    }
+}
+
+/// `info` is checked on the fields the desktop reads rather than byte-for-byte:
+/// the namespace default is randomly generated per call (§K8s Namespace), so a
+/// golden copy of it would be a test that fails every run.
+#[test]
+fn info_response_carries_the_contract_fields() {
+    let (stdout, code) = run(&read("info.request.json"));
+    assert_eq!(code, 0);
+    let info: serde_json::Value = serde_json::from_str(&stdout).unwrap();
+    assert_eq!(info["ok"], true);
+    assert_eq!(info["protocol_version"], 1);
+    assert_eq!(info["name"], "kubernetes");
+    let schema = &info["config_schema"];
+    assert_eq!(
+        schema["required"],
+        serde_json::json!(["namespace", "image"])
+    );
+    let default = schema["properties"]["namespace"]["default"]
+        .as_str()
+        .expect("no generated namespace default");
+    assert!(
+        default.starts_with("buzz-agents-"),
+        "unexpected namespace default: {default}"
+    );
+    let image_default = schema["properties"]["image"]["default"]
+        .as_str()
+        .expect("no image default");
+    assert!(
+        image_default.starts_with("ghcr.io/block/buzz-sprig:")
+            && image_default.contains("@sha256:"),
+        "unexpected image default: {image_default}"
+    );
+}
+
+/// The desktop's richest payload must parse. No response fixture: this one
+/// reaches the cluster, so its outcome depends on a kubeconfig. What it
+/// guards is that every field the desktop sends is *accepted* — a payload the
+/// provider rejects at parse time is a deploy that never starts.
+#[test]
+fn the_full_desktop_payload_is_accepted() {
+    let (stdout, code) = run(&read("deploy-full-launch.request.json"));
+    assert_eq!(code, 0);
+    let response: serde_json::Value = serde_json::from_str(&stdout).unwrap();
+    let error = response["error"].as_str().unwrap_or_default();
+    // It fails — there is no cluster — but it must fail at the *connection*,
+    // having accepted every field above it.
+    assert!(
+        error.contains("kubeconfig"),
+        "the full payload was rejected before reaching the cluster: {error}"
+    );
+}
+
+/// Sami's pre-registered respond-to matrix, driven through the built binary.
+///
+/// `build_env` runs at `main.rs:124`, `client::connect` at `:132`, so under a
+/// kubeconfig that cannot exist the error string *is* the ordering assertion:
+/// "kubeconfig" means the gate passed and we reached the cluster, anything
+/// else means we refused before writing a Secret. A test asserting only
+/// `ok: false` would pass on the connection error and prove nothing.
+///
+/// The cases are applied to the real full-launch request so each one differs
+/// from a known-good deploy in exactly the field under test.
+#[test]
+fn the_respond_to_gate_matches_the_harness_acceptance_surface() {
+    let key_a = "a".repeat(64);
+    let padded_upper = format!("  {}  ", "A".repeat(64));
+    // (name, respond_to, allowlist, must reach the cluster)
+    let cases: Vec<(&str, &str, Option<Vec<String>>, bool)> = vec![
+        ("allowlist + []", "allowlist", Some(vec![]), false),
+        ("allowlist + absent", "allowlist", None, false),
+        (
+            "allowlist + junk",
+            "allowlist",
+            Some(vec!["beefcafe".into()]),
+            false,
+        ),
+        ("unparseable mode", "npub1abc", None, false),
+        ("padded mode", " allowlist ", None, false),
+        (
+            "allowlist + two valid",
+            "allowlist",
+            Some(vec![key_a.clone(), "b".repeat(64)]),
+            true,
+        ),
+        (
+            "owner-only + junk list",
+            "owner-only",
+            Some(vec!["beefcafe".into()]),
+            true,
+        ),
+        (
+            "allowlist + padded upper",
+            "allowlist",
+            Some(vec![padded_upper]),
+            true,
+        ),
+        ("nobody", "nobody", None, true),
+        ("anyone", "anyone", None, true),
+    ];
+
+    let base: serde_json::Value =
+        serde_json::from_str(&read("deploy-full-launch.request.json")).unwrap();
+
+    for (name, mode, allowlist, reaches_cluster) in cases {
+        let mut request = base.clone();
+        let agent = &mut request["agent"];
+        agent["respond_to"] = serde_json::json!(mode);
+        agent["respond_to_allowlist"] = match &allowlist {
+            Some(list) => serde_json::json!(list),
+            None => serde_json::Value::Null,
+        };
+
+        let (stdout, code) = run(&request.to_string());
+        assert_eq!(code, 0, "{name}: provider did not exit cleanly");
+        let response: serde_json::Value = serde_json::from_str(&stdout).unwrap();
+        let error = response["error"].as_str().unwrap_or_default();
+        let reached = error.contains("kubeconfig");
+
+        assert_eq!(
+            reached, reaches_cluster,
+            "{name}: expected reaches_cluster={reaches_cluster}, got error: {error}"
+        );
+        if !reaches_cluster {
+            assert!(
+                error.contains("deploy refused"),
+                "{name}: refused, but not by the gate: {error}"
+            );
+        }
+    }
+}
diff --git a/crates/buzz-cli/src/commands/mod.rs b/crates/buzz-cli/src/commands/mod.rs
index 8691590636..1ccc37a702 100644
--- a/crates/buzz-cli/src/commands/mod.rs
+++ b/crates/buzz-cli/src/commands/mod.rs
@@ -12,9 +12,37 @@ pub mod notes;
 pub mod pack;
 pub mod patches;
 pub mod pr;
+pub mod projects;
 pub mod reactions;
 pub mod repos;
 pub mod social;
 pub mod upload;
 pub mod users;
 pub mod workflows;
+
+use crate::{client::normalize_write_response, error::CliError};
+
+/// Parse a relay write-response JSON blob, mapping a duplicate (dominated)
+/// write to [`CliError::Conflict`] with the caller-supplied message.
+///
+/// Used by every command that publishes an NIP-33 addressable event and
+/// needs to tell accepted from duplicate/dominated.
+pub fn parse_write_response(raw: &str, conflict_msg: &str) -> Result<String, CliError> {
+    let response: serde_json::Value = serde_json::from_str(raw)
+        .map_err(|e| CliError::Other(format!("relay response is not JSON: {e} ({raw})")))?;
+    let accepted = response
+        .get("accepted")
+        .and_then(serde_json::Value::as_bool)
+        .unwrap_or(false);
+    let message = response
+        .get("message")
+        .and_then(serde_json::Value::as_str)
+        .unwrap_or("");
+    if !accepted {
+        return Err(CliError::Other(format!("relay rejected event: {message}")));
+    }
+    if message == "duplicate" || message.starts_with("duplicate:") {
+        return Err(CliError::Conflict(conflict_msg.to_string()));
+    }
+    Ok(normalize_write_response(raw))
+}
diff --git a/crates/buzz-cli/src/commands/projects.rs b/crates/buzz-cli/src/commands/projects.rs
new file mode 100644
index 0000000000..e6798dbfc4
--- /dev/null
+++ b/crates/buzz-cli/src/commands/projects.rs
@@ -0,0 +1,1198 @@
+//! `buzz projects` commands — NIP-MP kind:30621 write path.
+//!
+//! All mutations follow a read-modify-write pattern:
+//!   1. Fetch the caller's own live head via `kinds:[30621] + authors:[self] + #d:[slug]`.
+//!   2. Mutate the tag set (strip `auth`, apply change).
+//!   3. Re-validate the full envelope through Layer A before submitting.
+//!   4. Set `created_at = head.created_at + 1` (never wall-clock) to avoid
+//!      overwriting a concurrently advancing head.
+//!
+//! Limitations recorded in this phase:
+//!   - Relay hints are read-preserved but not authored (`--repo` carries
+//!     a coordinate only; existing hinted tags survive RMW unchanged).
+//!   - `delete` targets signer-self only (NIP-OA owner-delete path deferred).
+//!   - Deletion durability against later arrival (watermark follow-up) is
+//!     not in scope.
+
+use buzz_core::kind::KIND_PROJECT;
+use buzz_sdk::{
+    build_delete_addressable, build_project, build_project_with_tags, ProjectMemberCoord,
+    PROJECT_D_MAX_LEN,
+};
+use nostr::{Event, EventBuilder, Tag, Timestamp};
+
+use crate::client::BuzzClient;
+use crate::commands::parse_write_response;
+use crate::error::CliError;
+
+// ── Buzz repo-ID grammar (bare --repo shorthand) ─────────────────────────────
+
+/// Pattern for a Buzz-hosted repo identifier (bare `--repo` shorthand).
+/// `[a-zA-Z0-9._-]{1,64}` — no colons, so guaranteed collision-free with
+/// `30617:<owner>:<d>` full coordinates.
+fn is_bare_repo_id(s: &str) -> bool {
+    !s.is_empty()
+        && s.len() <= 64
+        && s.chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '_' || c == '-')
+}
+
+/// Expand a CLI `--repo` argument into a full `30617:<owner>:<d>` coordinate.
+///
+/// Bare form (`[a-zA-Z0-9._-]{1,64}`): owner defaults to the caller's pubkey.
+/// Full form (`30617:<owner-hex>:<d>`): used verbatim.
+fn expand_repo_coord(s: &str, caller_pubkey: &str) -> Result<ProjectMemberCoord, CliError> {
+    if is_bare_repo_id(s) {
+        // Bare form: expand to full coordinate with caller as owner.
+        let full = format!("30617:{caller_pubkey}:{s}");
+        ProjectMemberCoord::parse_full(&full)
+            .map_err(|e| CliError::Usage(format!("invalid repo coordinate: {e}")))
+    } else {
+        // Full form: must be parseable as a complete coordinate.
+        ProjectMemberCoord::parse_full(s)
+            .map_err(|e| CliError::Usage(format!("invalid repo coordinate: {e}")))
+    }
+}
+
+// ── Head-fetch helper ─────────────────────────────────────────────────────────
+
+fn parse_events(json: &str) -> Result<Vec<Event>, CliError> {
+    serde_json::from_str(json)
+        .map_err(|e| CliError::Other(format!("failed to parse relay response: {e}")))
+}
+
+/// Fetch the caller's own live kind:30621 head for `slug`.
+async fn fetch_own_project(client: &BuzzClient, slug: &str) -> Result<Option<Event>, CliError> {
+    fetch_project(client, slug, None).await
+}
+
+/// Fetch a project head by slug and optional owner pubkey.
+async fn fetch_project(
+    client: &BuzzClient,
+    slug: &str,
+    owner: Option<&str>,
+) -> Result<Option<Event>, CliError> {
+    let pubkey = match owner {
+        Some(pk) => {
+            crate::validate::validate_hex64(pk)?;
+            pk.to_string()
+        }
+        None => client.keys().public_key().to_hex(),
+    };
+    let filter = serde_json::json!({
+        "kinds": [KIND_PROJECT],
+        "authors": [pubkey],
+        "#d": [slug],
+        "limit": 1,
+    });
+    let raw = client.query(&filter).await?;
+    let mut events = parse_events(&raw)?;
+    events.sort_by_key(|e| std::cmp::Reverse(e.created_at));
+    Ok(events.into_iter().next())
+}
+
+// ── Tag helpers ───────────────────────────────────────────────────────────────
+
+fn tag_name(tag: &Tag) -> Option<&str> {
+    tag.as_slice().first().map(String::as_str)
+}
+
+fn tag_value(tag: &Tag) -> Option<&str> {
+    tag.as_slice().get(1).map(String::as_str)
+}
+
+fn make_tag(parts: &[&str]) -> Result<Tag, CliError> {
+    Tag::parse(parts.iter().copied())
+        .map_err(|e| CliError::Other(format!("tag construction failed: {e}")))
+}
+
+// ── Submit helper ─────────────────────────────────────────────────────────────
+
+async fn submit_project(client: &BuzzClient, builder: EventBuilder) -> Result<(), CliError> {
+    let event = client.sign_event(builder)?;
+    let raw = client.submit_event(event).await?;
+    println!(
+        "{}",
+        parse_write_response(&raw, "project changed concurrently; retry")?
+    );
+    Ok(())
+}
+
+// ── Build helpers ─────────────────────────────────────────────────────────────
+
+/// Advance the `created_at` counter off an observed head.
+fn next_timestamp(head: &Event) -> Result<Timestamp, CliError> {
+    head.created_at
+        .as_secs()
+        .checked_add(1)
+        .map(Timestamp::from)
+        .ok_or_else(|| CliError::Other("project timestamp cannot be advanced".into()))
+}
+
+/// Strip `auth` from a tag list and pass the resulting envelope through
+/// Layer A validation. Returns a validated `EventBuilder` at `next_ts`.
+fn rebuild_project(
+    content: &str,
+    tags: Vec<Tag>,
+    next_ts: Timestamp,
+) -> Result<EventBuilder, CliError> {
+    // Strip auth tags.
+    let clean_tags: Vec<Tag> = tags
+        .into_iter()
+        .filter(|t| tag_name(t) != Some("auth"))
+        .collect();
+
+    build_project_with_tags(content, clean_tags)
+        .map_err(|e| CliError::Other(format!("envelope validation failed: {e}")))
+        .map(|b| b.custom_created_at(next_ts))
+}
+
+// ── Command implementations ───────────────────────────────────────────────────
+
+/// `buzz projects create`
+pub async fn cmd_create(
+    client: &BuzzClient,
+    slug: &str,
+    repos: &[String],
+    name: Option<&str>,
+    description: Option<&str>,
+    channel: Option<&str>,
+    visibility: Option<&str>,
+) -> Result<(), CliError> {
+    // ── Local validation (all checks before any .await) ───────────────────
+    validate_project_slug(slug)?;
+
+    let caller_pubkey = client.keys().public_key().to_hex();
+
+    // Expand and validate repo coordinates.
+    let members: Vec<ProjectMemberCoord> = repos
+        .iter()
+        .map(|r| expand_repo_coord(r, &caller_pubkey))
+        .collect::<Result<Vec<_>, _>>()?;
+
+    // Dedupe: preserve first occurrence, reject duplicates with Usage.
+    let mut seen = std::collections::HashSet::new();
+    for m in &members {
+        if !seen.insert(m.coord.clone()) {
+            return Err(CliError::Usage(format!(
+                "duplicate --repo coordinate in this invocation: {:?}",
+                m.coord
+            )));
+        }
+    }
+
+    // Validate optional metadata (early, before any network call).
+    if let Some(ch) = channel {
+        crate::validate::validate_uuid(ch)?;
+    }
+    if let Some(vis) = visibility {
+        validate_visibility(vis)?;
+    }
+    if let Some(n) = name {
+        if n.len() > 256 {
+            return Err(CliError::Usage(format!(
+                "project name must not exceed 256 bytes (got {})",
+                n.len()
+            )));
+        }
+    }
+
+    // ── Network: collision preflight ──────────────────────────────────────
+    if fetch_own_project(client, slug).await?.is_some() {
+        return Err(CliError::Conflict(format!(
+            "project {slug:?} already exists; use 'buzz projects update' to modify it"
+        )));
+    }
+
+    // ── Build via Layer B (enforces all writer policy) ────────────────────
+    let builder = build_project(slug, name, description, &members, channel, visibility)
+        .map_err(|e| CliError::Usage(e.to_string()))?;
+    submit_project(client, builder).await
+}
+
+/// `buzz projects get`
+pub async fn cmd_get(client: &BuzzClient, slug: &str, owner: Option<&str>) -> Result<(), CliError> {
+    validate_project_slug(slug)?;
+    let resp = match fetch_project(client, slug, owner).await? {
+        Some(event) => serde_json::json!({
+            "event_id": event.id.to_hex(),
+            "pubkey": event.pubkey.to_hex(),
+            "created_at": event.created_at.as_secs(),
+            "kind": event.kind.as_u16(),
+            "tags": event.tags.iter().map(|t| t.as_slice().to_vec()).collect::<Vec<_>>(),
+            "content": event.content,
+        }),
+        None => {
+            let owner_desc = owner.unwrap_or("current identity");
+            return Err(CliError::NotFound(format!(
+                "project {slug:?} not found for {owner_desc}"
+            )));
+        }
+    };
+    println!("{resp}");
+    Ok(())
+}
+
+/// `buzz projects list`
+pub async fn cmd_list(
+    client: &BuzzClient,
+    owner: Option<&str>,
+    limit: Option<u32>,
+) -> Result<(), CliError> {
+    let pubkey = match owner {
+        Some(pk) => {
+            crate::validate::validate_hex64(pk)?;
+            pk.to_string()
+        }
+        None => client.keys().public_key().to_hex(),
+    };
+    let mut filter = serde_json::json!({
+        "kinds": [KIND_PROJECT],
+        "authors": [pubkey],
+    });
+    if let Some(n) = limit {
+        filter["limit"] = serde_json::json!(n);
+    }
+    let resp = client.query(&filter).await?;
+    println!("{resp}");
+    Ok(())
+}
+
+/// `buzz projects add-repo`
+pub async fn cmd_add_repo(
+    client: &BuzzClient,
+    slug: &str,
+    repos: &[String],
+) -> Result<(), CliError> {
+    validate_project_slug(slug)?;
+    let caller_pubkey = client.keys().public_key().to_hex();
+
+    // ── Local validation before any .await ────────────────────────────────
+    let new_members: Vec<ProjectMemberCoord> = repos
+        .iter()
+        .map(|r| expand_repo_coord(r, &caller_pubkey))
+        .collect::<Result<Vec<_>, _>>()?;
+
+    // Dedupe within this invocation: first occurrence wins, duplicate → Usage.
+    let mut seen = std::collections::HashSet::new();
+    for m in &new_members {
+        if !seen.insert(m.coord.clone()) {
+            return Err(CliError::Usage(format!(
+                "duplicate --repo coordinate in this invocation: {:?}",
+                m.coord
+            )));
+        }
+    }
+
+    // ── Network: fetch head ───────────────────────────────────────────────
+    let head = fetch_own_project(client, slug)
+        .await?
+        .ok_or_else(|| CliError::NotFound(format!("project {slug:?} not found")))?;
+    let next_ts = next_timestamp(&head)?;
+
+    // Build the new tag set: keep existing tags (including hinted members),
+    // append new members only if not already present (by coordinate).
+    let mut tags: Vec<Tag> = head.tags.iter().cloned().collect();
+    let existing_coords: std::collections::HashSet<String> = head
+        .tags
+        .iter()
+        .filter(|t| tag_name(t) == Some("a"))
+        .filter_map(|t| tag_value(t).map(String::from))
+        .collect();
+    let mut added = 0usize;
+    for m in &new_members {
+        if !existing_coords.contains(m.coord.as_str()) {
+            let parts = m.to_tag_parts();
+            let parts_ref: Vec<&str> = parts.iter().map(String::as_str).collect();
+            tags.push(
+                Tag::parse(parts_ref.iter().copied())
+                    .map_err(|e| CliError::Other(format!("member tag construction failed: {e}")))?,
+            );
+            added += 1;
+        }
+    }
+
+    // All requested coordinates were already present — no change to publish.
+    if added == 0 {
+        return Err(CliError::Conflict(format!(
+            "all requested repositories are already members of project {slug:?}"
+        )));
+    }
+
+    let builder = rebuild_project(&head.content, tags, next_ts)?;
+    submit_project(client, builder).await
+}
+
+/// `buzz projects remove-repo`
+pub async fn cmd_remove_repo(
+    client: &BuzzClient,
+    slug: &str,
+    repos: &[String],
+) -> Result<(), CliError> {
+    validate_project_slug(slug)?;
+    let caller_pubkey = client.keys().public_key().to_hex();
+
+    // ── Local validation before any .await ────────────────────────────────
+    let to_remove: Vec<ProjectMemberCoord> = repos
+        .iter()
+        .map(|r| expand_repo_coord(r, &caller_pubkey))
+        .collect::<Result<Vec<_>, _>>()?;
+
+    // ── Network: fetch head ───────────────────────────────────────────────
+    let head = fetch_own_project(client, slug)
+        .await?
+        .ok_or_else(|| CliError::NotFound(format!("project {slug:?} not found")))?;
+    let next_ts = next_timestamp(&head)?;
+
+    // Verify all requested repos exist in the project.
+    let existing_coords: std::collections::HashSet<String> = head
+        .tags
+        .iter()
+        .filter(|t| tag_name(t) == Some("a"))
+        .filter_map(|t| tag_value(t).map(String::from))
+        .collect();
+    for m in &to_remove {
+        if !existing_coords.contains(m.coord.as_str()) {
+            return Err(CliError::NotFound(format!(
+                "project {slug:?} does not contain member {:?}",
+                m.coord
+            )));
+        }
+    }
+
+    let remove_coords: std::collections::HashSet<&str> =
+        to_remove.iter().map(|m| m.coord.as_str()).collect();
+
+    // Keep all tags except auth and the removed members.
+    let tags: Vec<Tag> = head
+        .tags
+        .iter()
+        .filter(|t| {
+            if tag_name(t) == Some("auth") {
+                return false;
+            }
+            if tag_name(t) == Some("a") {
+                if let Some(coord) = tag_value(t) {
+                    return !remove_coords.contains(coord);
+                }
+            }
+            true
+        })
+        .cloned()
+        .collect();
+
+    // Single rebuild validates the full envelope and strips any remaining auth.
+    let builder = rebuild_project(&head.content, tags, next_ts)?;
+    submit_project(client, builder).await
+}
+
+/// `buzz projects update`
+///
+/// Requires at least one setter or clearer; a no-op call is a usage error.
+#[allow(clippy::too_many_arguments)]
+pub async fn cmd_update(
+    client: &BuzzClient,
+    slug: &str,
+    name: Option<&str>,
+    clear_name: bool,
+    description: Option<&str>,
+    clear_description: bool,
+    channel: Option<&str>,
+    clear_channel: bool,
+    visibility: Option<&str>,
+    clear_visibility: bool,
+) -> Result<(), CliError> {
+    // Guard: at least one mutation required. The clap `ArgGroup` with
+    // `required(true).multiple(true)` enforces this at parse time; this
+    // runtime check is a defense-in-depth safety net for callers that invoke
+    // `cmd_update` directly (e.g. tests and future programmatic callers).
+    let has_mutation = name.is_some()
+        || clear_name
+        || description.is_some()
+        || clear_description
+        || channel.is_some()
+        || clear_channel
+        || visibility.is_some()
+        || clear_visibility;
+    if !has_mutation {
+        return Err(CliError::Usage(
+            "buzz projects update requires at least one of: \
+             --name, --clear-name, --description, --clear-description, \
+             --channel, --clear-channel, --visibility, --clear-visibility"
+                .into(),
+        ));
+    }
+
+    validate_project_slug(slug)?;
+    if let Some(ch) = channel {
+        crate::validate::validate_uuid(ch)?;
+    }
+    if let Some(vis) = visibility {
+        validate_visibility(vis)?;
+    }
+
+    let head = fetch_own_project(client, slug)
+        .await?
+        .ok_or_else(|| CliError::NotFound(format!("project {slug:?} not found")))?;
+    let next_ts = next_timestamp(&head)?;
+
+    // Build the new tag set. For each singleton metadata field:
+    //   - setter present: replace value (strip old, append new)
+    //   - clear flag set: drop the tag
+    //   - neither: keep existing
+    // Non-singleton / non-metadata tags (d, a, unknown) are preserved as-is.
+    let singleton_fields = ["name", "description", "buzz-channel", "buzz-visibility"];
+    let mut tags: Vec<Tag> = head
+        .tags
+        .iter()
+        .filter(|t| {
+            if tag_name(t) == Some("auth") {
+                return false;
+            }
+            // Drop singletons we're replacing or clearing.
+            if let Some(field) = tag_name(t) {
+                if singleton_fields.contains(&field) {
+                    let clear = match field {
+                        "name" => clear_name || name.is_some(),
+                        "description" => clear_description || description.is_some(),
+                        "buzz-channel" => clear_channel || channel.is_some(),
+                        "buzz-visibility" => clear_visibility || visibility.is_some(),
+                        _ => false,
+                    };
+                    return !clear;
+                }
+            }
+            true
+        })
+        .cloned()
+        .collect();
+
+    // Append new singleton values.
+    if let Some(n) = name {
+        tags.push(make_tag(&["name", n])?);
+    }
+    if let Some(d) = description {
+        tags.push(make_tag(&["description", d])?);
+    }
+    if let Some(ch) = channel {
+        tags.push(make_tag(&["buzz-channel", ch])?);
+    }
+    if let Some(vis) = visibility {
+        tags.push(make_tag(&["buzz-visibility", vis])?);
+    }
+
+    let builder = build_project_with_tags(&head.content, tags)
+        .map_err(|e| CliError::Other(format!("envelope validation failed: {e}")))?
+        .custom_created_at(next_ts);
+    submit_project(client, builder).await
+}
+
+/// `buzz projects delete`
+///
+/// Head-based and verified:
+///   1. Fetch own live head — `NotFound` if absent.
+///   2. Build tombstone at `head.created_at + 1`.
+///   3. Submit.
+///   4. Re-query the coordinate; if a newer head survived → `Conflict`.
+pub async fn cmd_delete(client: &BuzzClient, slug: &str) -> Result<(), CliError> {
+    validate_project_slug(slug)?;
+
+    let head = fetch_own_project(client, slug)
+        .await?
+        .ok_or_else(|| CliError::NotFound(format!("project {slug:?} not found")))?;
+    let next_ts = next_timestamp(&head)?;
+
+    let pubkey_hex = client.keys().public_key().to_hex();
+    let tombstone = build_delete_addressable(KIND_PROJECT, &pubkey_hex, slug)
+        .map_err(|e| CliError::Other(format!("failed to build delete event: {e}")))?
+        .custom_created_at(next_ts);
+
+    let event = client.sign_event(tombstone)?;
+    let raw = client.submit_event(event).await?;
+    parse_write_response(&raw, "delete event was dominated; a newer head exists")?;
+
+    // Post-submit verification: re-query to confirm the head is gone.
+    if let Some(survivor) = fetch_own_project(client, slug).await? {
+        // A newer head survived the tombstone.
+        return Err(CliError::Conflict(format!(
+            "project {slug:?} still exists (head at {}); a concurrent write raced the delete",
+            survivor.created_at.as_secs()
+        )));
+    }
+
+    println!("{}", serde_json::json!({ "deleted": slug, "status": "ok" }));
+    Ok(())
+}
+
+// ── Validation helpers ────────────────────────────────────────────────────────
+
+/// Validate a project slug: non-empty, ≤1024 bytes, verbatim.
+/// Does NOT impose the Buzz repo-ID grammar — project slugs are more permissive.
+fn validate_project_slug(slug: &str) -> Result<(), CliError> {
+    if slug.is_empty() {
+        return Err(CliError::Usage("project slug must not be empty".into()));
+    }
+    if slug.len() > PROJECT_D_MAX_LEN {
+        return Err(CliError::Usage(format!(
+            "project slug must not exceed {PROJECT_D_MAX_LEN} bytes (got {})",
+            slug.len()
+        )));
+    }
+    Ok(())
+}
+
+/// Validate a `buzz-visibility` value at the writer level.
+fn validate_visibility(vis: &str) -> Result<(), CliError> {
+    if vis != "listed" && vis != "unlisted" {
+        return Err(CliError::Usage(format!(
+            "visibility must be 'listed' or 'unlisted' (got {vis:?})"
+        )));
+    }
+    Ok(())
+}
+
+// ── Dispatch ──────────────────────────────────────────────────────────────────
+
+pub async fn dispatch(cmd: crate::ProjectsCmd, client: &BuzzClient) -> Result<(), CliError> {
+    use crate::ProjectsCmd;
+    match cmd {
+        ProjectsCmd::Create {
+            slug,
+            repo,
+            name,
+            description,
+            channel,
+            visibility,
+        } => {
+            cmd_create(
+                client,
+                &slug,
+                &repo,
+                name.as_deref(),
+                description.as_deref(),
+                channel.as_deref(),
+                visibility.map(|v| v.as_str()),
+            )
+            .await
+        }
+        ProjectsCmd::Get { slug, owner } => cmd_get(client, &slug, owner.as_deref()).await,
+        ProjectsCmd::List { owner, limit } => cmd_list(client, owner.as_deref(), limit).await,
+        ProjectsCmd::AddRepo { slug, repo } => cmd_add_repo(client, &slug, &repo).await,
+        ProjectsCmd::RemoveRepo { slug, repo } => cmd_remove_repo(client, &slug, &repo).await,
+        ProjectsCmd::Update {
+            slug,
+            name,
+            clear_name,
+            description,
+            clear_description,
+            channel,
+            clear_channel,
+            visibility,
+            clear_visibility,
+        } => {
+            cmd_update(
+                client,
+                &slug,
+                name.as_deref(),
+                clear_name,
+                description.as_deref(),
+                clear_description,
+                channel.as_deref(),
+                clear_channel,
+                visibility.map(|v| v.as_str()),
+                clear_visibility,
+            )
+            .await
+        }
+        ProjectsCmd::Delete { slug } => cmd_delete(client, &slug).await,
+    }
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use buzz_sdk::{validate_project_envelope, PROJECT_MEMBER_CAP};
+    use nostr::Tag;
+
+    use super::*;
+
+    // ── Coordinate expansion ──────────────────────────────────────────────────
+
+    const OWNER_HEX: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+    const OWNER_B_HEX: &str = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+
+    #[test]
+    fn expand_repo_coord_bare_expands_with_caller_pubkey() {
+        let coord = expand_repo_coord("my-repo", OWNER_HEX).unwrap();
+        assert_eq!(coord.coord, format!("30617:{OWNER_HEX}:my-repo"));
+    }
+
+    #[test]
+    fn expand_repo_coord_full_passes_through() {
+        let full = format!("30617:{OWNER_HEX}:some-repo");
+        let coord = expand_repo_coord(&full, OWNER_B_HEX).unwrap();
+        // Owner from the full coord, not the caller.
+        assert_eq!(coord.coord, full);
+    }
+
+    #[test]
+    fn expand_repo_coord_full_cross_owner() {
+        let full = format!("30617:{OWNER_B_HEX}:infra");
+        let coord = expand_repo_coord(&full, OWNER_HEX).unwrap();
+        assert_eq!(coord.coord, full);
+    }
+
+    #[test]
+    fn expand_repo_coord_rejects_uppercase_owner() {
+        let upper = "30617:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA:buzz";
+        assert!(expand_repo_coord(upper, OWNER_HEX).is_err());
+    }
+
+    #[test]
+    fn expand_repo_coord_rejects_coordinate_shaped_bare_value() {
+        // A value with a colon is never a bare id.
+        let not_bare = "30617:something";
+        // parse_full will fail because it's not a valid full coordinate either.
+        assert!(expand_repo_coord(not_bare, OWNER_HEX).is_err());
+    }
+
+    // ── validate_project_slug ─────────────────────────────────────────────────
+
+    #[test]
+    fn validate_project_slug_accepts_normal() {
+        assert!(validate_project_slug("my-project").is_ok());
+        assert!(validate_project_slug("platform:v2").is_ok()); // colons allowed — more permissive than repo-id
+    }
+
+    #[test]
+    fn validate_project_slug_rejects_empty() {
+        assert!(validate_project_slug("").is_err());
+    }
+
+    #[test]
+    fn validate_project_slug_rejects_over_1024() {
+        let long = "a".repeat(1025);
+        assert!(validate_project_slug(&long).is_err());
+    }
+
+    #[test]
+    fn validate_project_slug_accepts_1024() {
+        let at_limit = "a".repeat(1024);
+        assert!(validate_project_slug(&at_limit).is_ok());
+    }
+
+    // ── validate_visibility ───────────────────────────────────────────────────
+
+    #[test]
+    fn validate_visibility_accepts_listed_and_unlisted() {
+        assert!(validate_visibility("listed").is_ok());
+        assert!(validate_visibility("unlisted").is_ok());
+    }
+
+    #[test]
+    fn validate_visibility_rejects_unknown_token() {
+        assert!(validate_visibility("chartreuse").is_err());
+        assert!(validate_visibility("").is_err());
+    }
+
+    // ── is_bare_repo_id ───────────────────────────────────────────────────────
+
+    #[test]
+    fn bare_repo_id_accepts_valid() {
+        assert!(is_bare_repo_id("buzz"));
+        assert!(is_bare_repo_id("my-repo_1.0"));
+    }
+
+    #[test]
+    fn bare_repo_id_rejects_colon() {
+        assert!(!is_bare_repo_id("30617:something"));
+        assert!(!is_bare_repo_id("has:colon"));
+    }
+
+    #[test]
+    fn bare_repo_id_rejects_empty() {
+        assert!(!is_bare_repo_id(""));
+    }
+
+    #[test]
+    fn bare_repo_id_rejects_over_64() {
+        let long = "a".repeat(65);
+        assert!(!is_bare_repo_id(&long));
+    }
+
+    // ── tag helpers ───────────────────────────────────────────────────────────
+
+    fn make_test_tag(parts: &[&str]) -> Tag {
+        Tag::parse(parts.iter().copied()).unwrap()
+    }
+
+    // ── rebuild_project: hinted / unknown tag preservation ───────────────────
+
+    #[test]
+    fn rebuild_project_preserves_hinted_member_tags() {
+        // A member 'a' tag with a relay hint must survive RMW untouched.
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let hint = "wss://relay.example.com";
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            Tag::parse(["a", &coord, hint]).unwrap(),
+        ];
+        let ts = Timestamp::from(1_700_000_001u64);
+        let b = rebuild_project("", tags, ts).unwrap();
+        let ev = b.sign_with_keys(&nostr::Keys::generate()).expect("sign");
+        let a_tag = ev
+            .tags
+            .iter()
+            .find(|t| tag_name(t) == Some("a"))
+            .expect("a tag present");
+        assert_eq!(
+            a_tag.as_slice(),
+            &["a".to_string(), coord, hint.to_string()],
+            "relay hint must survive rebuild"
+        );
+    }
+
+    #[test]
+    fn rebuild_project_preserves_unknown_tags() {
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            make_test_tag(&["future-metadata", "value"]),
+        ];
+        let ts = Timestamp::from(1_700_000_001u64);
+        let b = rebuild_project("", tags, ts).unwrap();
+        let ev = b.sign_with_keys(&nostr::Keys::generate()).expect("sign");
+        assert!(ev
+            .tags
+            .iter()
+            .any(|t| tag_name(t) == Some("future-metadata")));
+    }
+
+    #[test]
+    fn rebuild_project_strips_auth_tag() {
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            make_test_tag(&["auth", &"a".repeat(64), "kind=30617", &"b".repeat(128)]),
+        ];
+        let ts = Timestamp::from(1_700_000_001u64);
+        let b = rebuild_project("", tags, ts).unwrap();
+        let ev = b.sign_with_keys(&nostr::Keys::generate()).expect("sign");
+        assert!(
+            !ev.tags.iter().any(|t| tag_name(t) == Some("auth")),
+            "auth tag must be stripped"
+        );
+    }
+
+    #[test]
+    fn rebuild_project_rejects_over_cap_foreign_head() {
+        // A foreign head with 65 members must fail Layer A on republish.
+        let mut tags = vec![make_test_tag(&["d", "wide"])];
+        for i in 0..=64u32 {
+            let coord = format!("30617:{OWNER_HEX}:repo-{i:02}");
+            tags.push(make_test_tag(&["a", &coord]));
+        }
+        assert_eq!(
+            tags.iter().filter(|t| tag_name(t) == Some("a")).count(),
+            65,
+            "65 a-tags"
+        );
+        let ts = Timestamp::from(1_700_000_001u64);
+        // rebuild_project strips auth, but 65 a-tags still exceeds cap.
+        assert!(
+            rebuild_project("", tags, ts).is_err(),
+            "over-cap foreign head must fail rebuild"
+        );
+    }
+
+    #[test]
+    fn rebuild_project_at_exact_cap_succeeds() {
+        let mut tags = vec![make_test_tag(&["d", "wide"])];
+        for i in 0..PROJECT_MEMBER_CAP {
+            let coord = format!("30617:{OWNER_HEX}:repo-{i:02}");
+            tags.push(make_test_tag(&["a", &coord]));
+        }
+        let ts = Timestamp::from(1_700_000_001u64);
+        assert!(rebuild_project("", tags, ts).is_ok());
+    }
+
+    // ── clear-flag semantics ──────────────────────────────────────────────────
+
+    /// Build a minimal head Event for testing update semantics without the relay.
+    fn make_head_tags(extra: &[Tag]) -> Vec<Tag> {
+        let mut tags = vec![make_test_tag(&["d", "platform"])];
+        tags.extend_from_slice(extra);
+        tags
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    fn apply_update_tags(
+        head_tags: Vec<Tag>,
+        name: Option<&str>,
+        clear_name: bool,
+        description: Option<&str>,
+        clear_description: bool,
+        channel: Option<&str>,
+        clear_channel: bool,
+        visibility: Option<&str>,
+        clear_visibility: bool,
+    ) -> Vec<Tag> {
+        // Replicate the tag-mutation logic from cmd_update (sans relay I/O).
+        let singleton_fields = ["name", "description", "buzz-channel", "buzz-visibility"];
+        let mut tags: Vec<Tag> = head_tags
+            .iter()
+            .filter(|t| {
+                if tag_name(t) == Some("auth") {
+                    return false;
+                }
+                if let Some(field) = tag_name(t) {
+                    if singleton_fields.contains(&field) {
+                        let clear = match field {
+                            "name" => clear_name || name.is_some(),
+                            "description" => clear_description || description.is_some(),
+                            "buzz-channel" => clear_channel || channel.is_some(),
+                            "buzz-visibility" => clear_visibility || visibility.is_some(),
+                            _ => false,
+                        };
+                        return !clear;
+                    }
+                }
+                true
+            })
+            .cloned()
+            .collect();
+        if let Some(n) = name {
+            tags.push(make_test_tag(&["name", n]));
+        }
+        if let Some(d) = description {
+            tags.push(make_test_tag(&["description", d]));
+        }
+        if let Some(ch) = channel {
+            tags.push(make_test_tag(&["buzz-channel", ch]));
+        }
+        if let Some(vis) = visibility {
+            tags.push(make_test_tag(&["buzz-visibility", vis]));
+        }
+        tags
+    }
+
+    #[test]
+    fn update_omission_preserves_existing_field() {
+        let head = make_head_tags(&[make_test_tag(&["name", "Old Name"])]);
+        let result = apply_update_tags(head, None, false, None, false, None, false, None, false);
+        assert!(result.iter().any(|t| tag_value(t) == Some("Old Name")));
+    }
+
+    #[test]
+    fn update_setter_replaces_existing_field() {
+        let head = make_head_tags(&[make_test_tag(&["name", "Old Name"])]);
+        let result = apply_update_tags(
+            head,
+            Some("New Name"),
+            false,
+            None,
+            false,
+            None,
+            false,
+            None,
+            false,
+        );
+        assert!(result.iter().any(|t| tag_value(t) == Some("New Name")));
+        assert!(!result.iter().any(|t| tag_value(t) == Some("Old Name")));
+    }
+
+    #[test]
+    fn update_clear_drops_existing_field() {
+        let head = make_head_tags(&[make_test_tag(&["name", "Old Name"])]);
+        let result = apply_update_tags(head, None, true, None, false, None, false, None, false);
+        assert!(!result.iter().any(|t| tag_name(t) == Some("name")));
+    }
+
+    #[test]
+    fn update_clear_visibility_drops_tag() {
+        let head = make_head_tags(&[make_test_tag(&["buzz-visibility", "unlisted"])]);
+        let result = apply_update_tags(head, None, false, None, false, None, false, None, true);
+        assert!(!result
+            .iter()
+            .any(|t| tag_name(t) == Some("buzz-visibility")));
+    }
+
+    #[test]
+    fn update_exactly_one_singleton_after_replace() {
+        // Start with a buzz-channel; replace with a new one; must have exactly one.
+        let uuid1 = "3580ca9b-47b4-4af9-b22a-1068778f26c6";
+        let uuid2 = "00000000-0000-0000-0000-000000000000";
+        let head = make_head_tags(&[make_test_tag(&["buzz-channel", uuid1])]);
+        let result = apply_update_tags(
+            head,
+            None,
+            false,
+            None,
+            false,
+            Some(uuid2),
+            false,
+            None,
+            false,
+        );
+        let channels: Vec<_> = result
+            .iter()
+            .filter(|t| tag_name(t) == Some("buzz-channel"))
+            .collect();
+        assert_eq!(channels.len(), 1);
+        assert_eq!(tag_value(channels[0]), Some(uuid2));
+    }
+
+    // ── duplicate-member rejection on republish ───────────────────────────────
+
+    #[test]
+    fn duplicate_member_in_foreign_head_fails_rebuild() {
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            make_test_tag(&["a", &coord]),
+            make_test_tag(&["a", &coord]), // duplicate
+        ];
+        let ts = Timestamp::from(1_700_000_001u64);
+        assert!(rebuild_project("", tags, ts).is_err());
+    }
+
+    // ── validate_project_envelope integration ────────────────────────────────
+
+    #[test]
+    fn validate_project_envelope_accepts_hinted_member() {
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            Tag::parse(["a", &coord, "wss://relay.example.com"]).unwrap(),
+        ];
+        assert!(validate_project_envelope(&tags, "").is_ok());
+    }
+
+    #[test]
+    fn validate_project_envelope_rejects_four_element_member() {
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            Tag::parse(["a", &coord, "wss://relay.example.com", "extra"]).unwrap(),
+        ];
+        assert!(validate_project_envelope(&tags, "").is_err());
+    }
+
+    // ── next_timestamp ordering ───────────────────────────────────────────────
+
+    /// `next_timestamp` must return `head.created_at + 1` regardless of the wall
+    /// clock.  NIP-MP Deletion rule: a tombstone older than the live head does
+    /// NOT remove it, so we must advance strictly off the observed head — never
+    /// use wall-clock time, which could be behind a head that was bumped
+    /// multiple times in the same second.
+    #[test]
+    fn next_timestamp_returns_head_plus_one_when_head_is_ahead_of_wall_clock() {
+        // Build a minimal signed event with a created_at far in the future.
+        let keys = nostr::Keys::generate();
+        let far_future_ts = Timestamp::from(9_999_999_999u64); // year 2286
+        let tags = vec![
+            make_test_tag(&["d", "platform"]),
+            make_test_tag(&["a", &format!("30617:{OWNER_HEX}:buzz")]),
+        ];
+        let builder = rebuild_project("", tags, far_future_ts).expect("valid head envelope");
+        let head = builder.sign_with_keys(&keys).expect("sign");
+        // Verify the event actually has our future timestamp.
+        assert_eq!(head.created_at, far_future_ts);
+
+        // next_timestamp must return far_future + 1, not now().
+        let next = next_timestamp(&head).expect("no overflow");
+        assert_eq!(
+            next.as_secs(),
+            far_future_ts.as_secs() + 1,
+            "tombstone must be strictly after head, even when head is far in the future"
+        );
+    }
+
+    // ── empty update guard ────────────────────────────────────────────────────
+
+    /// `cmd_update` with no setters or clearers must return `CliError::Usage`
+    /// before making any network call.  The guard is synchronous (before the
+    /// first `.await`) so we can drive it with a dummy client whose address
+    /// would reject any real connection attempt.
+    #[tokio::test]
+    async fn empty_update_returns_usage_error_before_any_network_call() {
+        let keys = nostr::Keys::generate();
+        // Port 9 is the discard protocol — any real connect will be refused
+        // immediately, but the guard fires before the first await so this
+        // never reaches the network.
+        let client = crate::client::BuzzClient::new("http://127.0.0.1:9".into(), keys, None, None)
+            .expect("client construction");
+
+        let err = cmd_update(
+            &client, "my-slug", None, false, // name / clear_name
+            None, false, // description / clear_description
+            None, false, // channel / clear_channel
+            None, false, // visibility / clear_visibility
+        )
+        .await
+        .expect_err("empty update must fail");
+
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage, got {err:?}"
+        );
+    }
+
+    // ── no-network malformed-input tests ─────────────────────────────────────
+    //
+    // All three cases use port 9 (discard protocol): any real connection is
+    // refused immediately, but local validation fires before the first .await
+    // so the network is never touched.
+
+    fn discard_client() -> crate::client::BuzzClient {
+        let keys = nostr::Keys::generate();
+        crate::client::BuzzClient::new("http://127.0.0.1:9".into(), keys, None, None)
+            .expect("client construction")
+    }
+
+    /// Invalid visibility token must return Usage before touching the relay.
+    #[tokio::test]
+    async fn create_invalid_visibility_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let err = cmd_create(
+            &client,
+            "my-slug",
+            &["buzz".to_string()],
+            None,
+            None,
+            None,
+            Some("chartreuse"),
+        )
+        .await
+        .expect_err("invalid visibility must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for invalid visibility, got {err:?}"
+        );
+    }
+
+    /// A name longer than 256 bytes must return Usage before touching the relay.
+    #[tokio::test]
+    async fn create_overlong_name_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let long_name = "a".repeat(257);
+        let err = cmd_create(
+            &client,
+            "my-slug",
+            &["buzz".to_string()],
+            Some(&long_name),
+            None,
+            None,
+            None,
+        )
+        .await
+        .expect_err("overlong name must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for overlong name, got {err:?}"
+        );
+    }
+
+    /// A malformed --repo coordinate must return Usage before touching the relay.
+    #[tokio::test]
+    async fn create_malformed_repo_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let err = cmd_create(
+            &client,
+            "my-slug",
+            &["nope:bad".to_string()],
+            None,
+            None,
+            None,
+            None,
+        )
+        .await
+        .expect_err("malformed repo must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for malformed repo, got {err:?}"
+        );
+    }
+
+    /// A malformed --repo coordinate on add-repo must return Usage before touching the relay.
+    #[tokio::test]
+    async fn add_repo_malformed_coord_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let err = cmd_add_repo(&client, "my-slug", &["nope:bad".to_string()])
+            .await
+            .expect_err("malformed repo must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for malformed repo on add-repo, got {err:?}"
+        );
+    }
+
+    /// A malformed --repo coordinate on remove-repo must return Usage before touching the relay.
+    #[tokio::test]
+    async fn remove_repo_malformed_coord_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let err = cmd_remove_repo(&client, "my-slug", &["nope:bad".to_string()])
+            .await
+            .expect_err("malformed repo must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for malformed repo on remove-repo, got {err:?}"
+        );
+    }
+
+    // ── duplicate --repo within one invocation ────────────────────────────────
+
+    /// Supplying the same coordinate twice in one create call must return Usage
+    /// (names the duplicate) before any network call.
+    #[tokio::test]
+    async fn create_duplicate_repo_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let err = cmd_create(
+            &client,
+            "my-slug",
+            &[coord.clone(), coord.clone()],
+            None,
+            None,
+            None,
+            None,
+        )
+        .await
+        .expect_err("duplicate repo must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for duplicate repo, got {err:?}"
+        );
+        // Error message must name the duplicate coordinate.
+        assert!(
+            format!("{err}").contains("buzz"),
+            "Usage message must name the duplicate coordinate, got {err:?}"
+        );
+    }
+
+    /// Supplying the same coordinate twice in one add-repo call must return Usage
+    /// (names the duplicate) before any network call.
+    #[tokio::test]
+    async fn add_repo_duplicate_coord_returns_usage_before_any_network_call() {
+        let client = discard_client();
+        let coord = format!("30617:{OWNER_HEX}:buzz");
+        let err = cmd_add_repo(&client, "my-slug", &[coord.clone(), coord.clone()])
+            .await
+            .expect_err("duplicate repo must fail");
+        assert!(
+            matches!(err, CliError::Usage(_)),
+            "expected CliError::Usage for duplicate repo on add-repo, got {err:?}"
+        );
+    }
+
+    // ── create collision guard ────────────────────────────────────────────────
+
+    // The create-collision Conflict path is pinned by the live transcript
+    // (step: duplicate create → Conflict, exit=5). No relay mock is available
+    // for a unit test; the no-network tests above cover all pre-await paths.
+
+    // ── add-repo no-op guard ──────────────────────────────────────────────────
+
+    // The add-repo no-op Conflict path is pinned by the live transcript
+    // (step 7: buzz already present → exit=5). No relay mock is available
+    // for a unit test; the async no-network tests above cover all pre-await paths.
+}
diff --git a/crates/buzz-cli/src/commands/repos.rs b/crates/buzz-cli/src/commands/repos.rs
index 608d495055..15e064d9c3 100644
--- a/crates/buzz-cli/src/commands/repos.rs
+++ b/crates/buzz-cli/src/commands/repos.rs
@@ -4,7 +4,8 @@ use buzz_core::{
 };
 use nostr::{Event, EventBuilder, Tag, Timestamp};
 
-use crate::client::{normalize_write_response, BuzzClient};
+use crate::client::BuzzClient;
+use crate::commands::parse_write_response;
 use crate::error::CliError;
 use crate::validate::validate_repo_id;
 
@@ -186,25 +187,10 @@ fn protection_rules_json(event: &Event) -> Result<serde_json::Value, CliError> {
 }
 
 fn validate_write_response(raw: &str) -> Result<String, CliError> {
-    let response: serde_json::Value = serde_json::from_str(raw)
-        .map_err(|error| CliError::Other(format!("relay response is not JSON: {error} ({raw})")))?;
-    let accepted = response
-        .get("accepted")
-        .and_then(serde_json::Value::as_bool)
-        .unwrap_or(false);
-    let message = response
-        .get("message")
-        .and_then(serde_json::Value::as_str)
-        .unwrap_or("");
-    if !accepted {
-        return Err(CliError::Other(format!("relay rejected event: {message}")));
-    }
-    if message == "duplicate" || message.starts_with("duplicate:") {
-        return Err(CliError::Conflict(
-            "repository changed concurrently; fetch the latest rules and retry".into(),
-        ));
-    }
-    Ok(normalize_write_response(raw))
+    parse_write_response(
+        raw,
+        "repository changed concurrently; fetch the latest rules and retry",
+    )
 }
 
 async fn submit_repo_update(client: &BuzzClient, builder: EventBuilder) -> Result<(), CliError> {
diff --git a/crates/buzz-cli/src/lib.rs b/crates/buzz-cli/src/lib.rs
index 0726406d29..f745e7b280 100644
--- a/crates/buzz-cli/src/lib.rs
+++ b/crates/buzz-cli/src/lib.rs
@@ -212,6 +212,9 @@ enum Cmd {
     /// Announce and discover git repositories (NIP-34)
     #[command(subcommand)]
     Repos(ReposCmd),
+    /// Create and manage multi-repo projects (NIP-MP)
+    #[command(subcommand)]
+    Projects(ProjectsCmd),
     /// Send, get, list, and set status on git patches (NIP-34)
     #[command(subcommand)]
     Patches(PatchesCmd),
@@ -1227,6 +1230,122 @@ pub enum RepoPushRole {
     Member,
 }
 
+/// Visibility of a multi-repo project listing.
+#[derive(Clone, Copy, Debug, clap::ValueEnum)]
+pub enum ProjectVisibility {
+    /// Project appears in public listings (default).
+    Listed,
+    /// Project is hidden from public listings.
+    Unlisted,
+}
+
+impl ProjectVisibility {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            ProjectVisibility::Listed => "listed",
+            ProjectVisibility::Unlisted => "unlisted",
+        }
+    }
+}
+
+#[derive(Subcommand)]
+pub enum ProjectsCmd {
+    /// Create a new multi-repo project (NIP-MP kind:30621)
+    ///
+    /// Requires at least one --repo. Fails with Conflict if the project already exists.
+    Create {
+        /// Project identifier (slug), up to 1024 bytes
+        slug: String,
+        /// Member repository coordinate: bare Buzz repo id (e.g. `buzz`) or full
+        /// `30617:<owner-hex>:<repo-d>` for cross-owner or colon-bearing repo ids.
+        /// At least one --repo is required.
+        #[arg(long = "repo", required = true)]
+        repo: Vec<String>,
+        /// Display name (≤256 bytes)
+        #[arg(long)]
+        name: Option<String>,
+        /// Description (≤2048 bytes)
+        #[arg(long)]
+        description: Option<String>,
+        /// Associated Buzz channel UUID
+        #[arg(long)]
+        channel: Option<String>,
+        /// Visibility: `listed` (default) or `unlisted`
+        #[arg(long)]
+        visibility: Option<ProjectVisibility>,
+    },
+    /// Get a project by slug
+    Get {
+        /// Project slug
+        slug: String,
+        /// Owner pubkey (64-char hex). Defaults to the current identity.
+        #[arg(long)]
+        owner: Option<String>,
+    },
+    /// List projects
+    List {
+        /// Owner pubkey (64-char hex). Defaults to the current identity.
+        #[arg(long)]
+        owner: Option<String>,
+        /// Maximum number of results
+        #[arg(long)]
+        limit: Option<u32>,
+    },
+    /// Add one or more member repositories to a project
+    #[command(name = "add-repo")]
+    AddRepo {
+        /// Project slug
+        slug: String,
+        /// Member repository coordinate (bare id or full `30617:<owner-hex>:<repo-d>`)
+        #[arg(long = "repo", required = true)]
+        repo: Vec<String>,
+    },
+    /// Remove one or more member repositories from a project
+    #[command(name = "remove-repo")]
+    RemoveRepo {
+        /// Project slug
+        slug: String,
+        /// Member repository coordinate to remove (bare id or full `30617:<owner-hex>:<repo-d>`)
+        #[arg(long = "repo", required = true)]
+        repo: Vec<String>,
+    },
+    /// Update project metadata (at least one setter or clearer required)
+    #[command(group = clap::ArgGroup::new("mutation").required(true).multiple(true))]
+    Update {
+        /// Project slug
+        slug: String,
+        /// Set the display name
+        #[arg(long, group = "mutation")]
+        name: Option<String>,
+        /// Remove the display name
+        #[arg(long, group = "mutation", conflicts_with = "name")]
+        clear_name: bool,
+        /// Set the description
+        #[arg(long, group = "mutation")]
+        description: Option<String>,
+        /// Remove the description
+        #[arg(long, group = "mutation", conflicts_with = "description")]
+        clear_description: bool,
+        /// Set the associated Buzz channel UUID
+        #[arg(long, group = "mutation")]
+        channel: Option<String>,
+        /// Remove the associated channel
+        #[arg(long, group = "mutation", conflicts_with = "channel")]
+        clear_channel: bool,
+        /// Set visibility: `listed` or `unlisted`
+        #[arg(long, group = "mutation")]
+        visibility: Option<ProjectVisibility>,
+        /// Remove the visibility tag (absence defaults to `listed`)
+        #[arg(long, group = "mutation", conflicts_with = "visibility")]
+        clear_visibility: bool,
+    },
+    /// Delete a project (head-based tombstone; verified after submit)
+    Delete {
+        /// Project slug
+        slug: String,
+    },
+}
+
 #[derive(Subcommand)]
 pub enum PatchesCmd {
     /// Send a git patch (NIP-34 kind:1617)
@@ -1768,6 +1887,41 @@ pub enum ModerationCmd {
     },
 }
 
+/// Normalize hand-authored `BUZZ_AUTH_TAG` input to strict JSON.
+///
+/// `.env` files and shell exports sometimes carry the tag in the unquoted
+/// shorthand `[auth,<hex>,<conditions>,<hex>]` (quotes dropped by hand).
+/// When the input is not valid JSON but is bracket-delimited, rewrite it as
+/// a JSON array of the comma-separated fields (an empty field `,,` becomes
+/// `""`, matching the canonical form `["auth","hex","","hex"]`).
+///
+/// This is presentation-layer leniency at the configuration edge only: the
+/// output is always fed through the SDK's strict `parse_auth_tag` /
+/// `verify_auth_tag`, which enforce structure, hex, the conditions grammar,
+/// and the BIP-340 signature. Inputs that are already valid JSON — or not
+/// recognizable as the shorthand — are returned unchanged so the strict
+/// parser reports the error on the original bytes.
+fn normalize_auth_tag_input(input: &str) -> String {
+    let trimmed = input.trim();
+    if serde_json::from_str::<serde_json::Value>(trimmed).is_ok() {
+        return trimmed.to_owned();
+    }
+    if trimmed.starts_with('[') && trimmed.ends_with(']') {
+        let fields: Vec<&str> = trimmed[1..trimmed.len() - 1]
+            .split(',')
+            .map(str::trim)
+            .collect();
+        // Only a plausible 4-field auth tag is rewritten; anything else is
+        // passed through untouched for the strict parser to reject with an
+        // error that references the caller's original input.
+        if fields.len() == 4 && !fields.iter().any(|f| f.contains('"')) {
+            // serde_json cannot fail serializing a Vec<&str>.
+            return serde_json::to_string(&fields).expect("string array serializes");
+        }
+    }
+    trimmed.to_owned()
+}
+
 async fn run(cli: Cli) -> Result<(), CliError> {
     let relay_url = client::normalize_relay_url(&cli.relay);
 
@@ -1788,17 +1942,28 @@ async fn run(cli: Cli) -> Result<(), CliError> {
         .map_err(|e| CliError::Key(format!("invalid BUZZ_PRIVATE_KEY: {e}")))?;
 
     // NIP-OA: parse and verify the auth tag if provided.
+    //
+    // `BUZZ_AUTH_TAG` is hand-authored configuration, so the unquoted raw
+    // shorthand `[auth,hex,,hex]` is normalized to JSON here — at this input
+    // edge only. The SDK grammar and the `x-auth-tag` wire format stay strict
+    // JSON; all validation and signature verification happen on the strict
+    // path below, unchanged.
     let (auth_tag, auth_tag_json) = match cli.auth_tag {
-        Some(ref json) if !json.is_empty() => {
-            let tag = buzz_sdk::nip_oa::parse_auth_tag(json)
+        Some(ref input) if !input.is_empty() => {
+            let json = normalize_auth_tag_input(input);
+            let tag = buzz_sdk::nip_oa::parse_auth_tag(&json)
                 .map_err(|e| CliError::Auth(format!("BUZZ_AUTH_TAG is malformed: {e}")))?;
-            buzz_sdk::nip_oa::verify_auth_tag(json, &keys.public_key()).map_err(|e| {
+            buzz_sdk::nip_oa::verify_auth_tag(&json, &keys.public_key()).map_err(|e| {
                 CliError::Auth(format!(
                     "BUZZ_AUTH_TAG verification failed for pubkey {}: {e}",
                     keys.public_key().to_hex()
                 ))
             })?;
-            (Some(tag), Some(json.clone()))
+            // Canonical wire form derives from the parsed-and-verified tag
+            // (same shape as buzz-acp's RestClient), never from raw input.
+            let canonical = serde_json::to_string(tag.as_slice())
+                .map_err(|e| CliError::Auth(format!("BUZZ_AUTH_TAG serialization failed: {e}")))?;
+            (Some(tag), Some(canonical))
         }
         _ => (None, None),
     };
@@ -1819,6 +1984,7 @@ async fn run(cli: Cli) -> Result<(), CliError> {
         Cmd::Social(sub) => commands::social::dispatch(sub, &client).await,
         Cmd::Notes(sub) => commands::notes::dispatch(sub, &client).await,
         Cmd::Repos(sub) => commands::repos::dispatch(sub, &client).await,
+        Cmd::Projects(sub) => commands::projects::dispatch(sub, &client).await,
         Cmd::Patches(sub) => commands::patches::dispatch(sub, &client).await,
         Cmd::Issues(sub) => commands::issues::dispatch(sub, &client).await,
         Cmd::Pr(sub) => commands::pr::dispatch(sub, &client).await,
@@ -1835,6 +2001,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() {
@@ -1883,6 +2094,7 @@ mod tests {
             "pack",
             "patches",
             "pr",
+            "projects",
             "reactions",
             "repos",
             "social",
@@ -2038,6 +2250,18 @@ mod tests {
             names(&cmd, "patches"),
             vec!["get", "list", "send", "status"]
         );
+        assert_eq!(
+            names(&cmd, "projects"),
+            vec![
+                "add-repo",
+                "create",
+                "delete",
+                "get",
+                "list",
+                "remove-repo",
+                "update"
+            ]
+        );
         assert_eq!(
             names(&cmd, "issues"),
             vec!["create", "get", "list", "status"]
@@ -2075,6 +2299,7 @@ mod tests {
             ("pack", 2),
             ("patches", 4),
             ("pr", 5),
+            ("projects", 7),
             ("reactions", 3),
             ("repos", 5),
             ("social", 7),
@@ -2142,4 +2367,111 @@ mod tests {
                 .join("\n")
         );
     }
+
+    // ── projects update mutation group ────────────────────────────────────────
+
+    /// Multiple independent fields must be accepted in the same invocation.
+    #[test]
+    fn projects_update_multi_field_is_accepted() {
+        assert!(
+            Cli::try_parse_from([
+                "buzz",
+                "projects",
+                "update",
+                "my-slug",
+                "--name",
+                "X",
+                "--description",
+                "Y",
+            ])
+            .is_ok(),
+            "--name and --description together must be accepted"
+        );
+    }
+
+    /// A setter for one field and a clearer for a different field must be accepted.
+    #[test]
+    fn projects_update_setter_with_other_clearer_is_accepted() {
+        assert!(
+            Cli::try_parse_from([
+                "buzz",
+                "projects",
+                "update",
+                "my-slug",
+                "--name",
+                "X",
+                "--clear-description",
+            ])
+            .is_ok(),
+            "--name with --clear-description must be accepted"
+        );
+    }
+
+    /// A setter and its own clearer are mutually exclusive — clap must reject this.
+    #[test]
+    fn projects_update_setter_with_own_clearer_is_rejected() {
+        assert!(
+            Cli::try_parse_from([
+                "buzz",
+                "projects",
+                "update",
+                "my-slug",
+                "--name",
+                "X",
+                "--clear-name",
+            ])
+            .is_err(),
+            "--name and --clear-name together must be rejected by clap"
+        );
+    }
+
+    /// Providing no mutation options at all must be rejected by clap (required group).
+    #[test]
+    fn projects_update_no_mutation_is_rejected_by_clap() {
+        // Without credentials, a valid parse would reach authentication and fail
+        // with auth_error — but a clap-level rejection happens before any I/O.
+        // We verify it's a clap error (not just any error) by checking the error
+        // kind is not a runtime/auth failure — Cli::try_parse_from returns Err
+        // immediately for argument violations.
+        assert!(
+            Cli::try_parse_from(["buzz", "projects", "update", "my-slug"]).is_err(),
+            "update with no setters or clearers must be rejected at parse time"
+        );
+    }
+
+    /// An unrecognised visibility token must be rejected by clap before any I/O.
+    #[test]
+    fn projects_create_invalid_visibility_is_rejected_by_clap() {
+        assert!(
+            Cli::try_parse_from([
+                "buzz",
+                "projects",
+                "create",
+                "my-slug",
+                "--repo",
+                "buzz",
+                "--visibility",
+                "chartreuse",
+            ])
+            .is_err(),
+            "--visibility chartreuse must be rejected at parse time"
+        );
+    }
+
+    /// An unrecognised visibility token on update must be rejected by clap before any I/O.
+    #[test]
+    fn projects_update_invalid_visibility_is_rejected_by_clap() {
+        assert!(
+            Cli::try_parse_from([
+                "buzz",
+                "projects",
+                "update",
+                "my-slug",
+                "--visibility",
+                "chartreuse",
+            ])
+            .is_err(),
+            "--visibility chartreuse on update must be rejected at parse time"
+        );
+    }
 }
diff --git a/crates/buzz-db/src/lib.rs b/crates/buzz-db/src/lib.rs
index 245e49bb2d..9b26876747 100644
--- a/crates/buzz-db/src/lib.rs
+++ b/crates/buzz-db/src/lib.rs
@@ -3999,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.
@@ -4096,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
@@ -7408,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 bfc56f82de..402229cdec 100644
--- a/crates/buzz-db/src/relay_members.rs
+++ b/crates/buzz-db/src/relay_members.rs
@@ -29,14 +29,41 @@ pub struct RelayMember {
 
 /// Returns `true` if `pubkey` (64-char hex) is a member of `community`.
 pub async fn is_relay_member(pool: &PgPool, community: CommunityId, pubkey: &str) -> Result<bool> {
+    let mut conn = pool.acquire().await?;
+    is_relay_member_on(&mut conn, community, pubkey).await
+}
+
+/// [`is_relay_member`] on a specific session — the replica-routing path runs
+/// the lookup on the exact reader connection whose heartbeat observation
+/// proved fence coverage.
+pub(crate) async fn is_relay_member_on(
+    conn: &mut sqlx::PgConnection,
+    community: CommunityId,
+    pubkey: &str,
+) -> Result<bool> {
     let row = sqlx::query("SELECT 1 FROM relay_members WHERE community_id = $1 AND pubkey = $2")
         .bind(community.as_uuid())
         .bind(pubkey)
-        .fetch_optional(pool)
+        .fetch_optional(conn)
         .await?;
     Ok(row.is_some())
 }
 
+/// Returns `true` if any member of `community` holds the `admin` or `owner`
+/// role. Open relays don't *enforce* the roster, but startup
+/// (`bootstrap_owner`) and operator provisioning still populate it — this is
+/// how the workspace-profile gate detects whether a steward exists.
+pub async fn has_admin_or_owner(pool: &PgPool, community: CommunityId) -> Result<bool> {
+    let row = sqlx::query(
+        "SELECT 1 FROM relay_members \
+         WHERE community_id = $1 AND role IN ('admin', 'owner') LIMIT 1",
+    )
+    .bind(community.as_uuid())
+    .fetch_optional(pool)
+    .await?;
+    Ok(row.is_some())
+}
+
 /// Returns the relay member record for `pubkey` in `community`, or `None`.
 pub async fn get_relay_member(
     pool: &PgPool,
diff --git a/crates/buzz-relay/src/api/git/cas_publish.rs b/crates/buzz-relay/src/api/git/cas_publish.rs
index c213e2913e..50bb36d818 100644
--- a/crates/buzz-relay/src/api/git/cas_publish.rs
+++ b/crates/buzz-relay/src/api/git/cas_publish.rs
@@ -1370,6 +1370,15 @@ mod tests {
         );
     }
 
+    #[test]
+    fn published_head_moves_to_surviving_branch_after_current_branch_deletion() {
+        let refs = BTreeMap::from([("refs/heads/master".to_string(), "1".repeat(40))]);
+        assert_eq!(
+            resolve_published_head(&refs, "refs/heads/main".to_string(), "refs/heads/main"),
+            "refs/heads/master"
+        );
+    }
+
     #[test]
     fn digest_from_key_strips_prefix() {
         let k = format!("manifests/{}", "a".repeat(64));
diff --git a/crates/buzz-relay/src/api/git/transport.rs b/crates/buzz-relay/src/api/git/transport.rs
index f8e0300277..d3118d8a76 100644
--- a/crates/buzz-relay/src/api/git/transport.rs
+++ b/crates/buzz-relay/src/api/git/transport.rs
@@ -1064,7 +1064,7 @@ pub async fn receive_pack(
         state.config.bind_addr.port()
     );
     let hooks_dir = repo.path().join("hooks").display().to_string();
-    let hook_env = vec![
+    let mut hook_env = vec![
         ("BUZZ_HOOK_URL", hook_url),
         (
             "BUZZ_HOOK_SECRET",
@@ -1077,13 +1077,8 @@ pub async fn receive_pack(
             auth.tenant.community().as_uuid().to_string(),
         ),
         ("BUZZ_PUSHER_PUBKEY", pusher_hex.clone()),
-        // Override any repo-local core.hooksPath setting; defense in
-        // depth even though the hydrated workspace has no inherited
-        // config.
-        ("GIT_CONFIG_COUNT", "1".to_string()),
-        ("GIT_CONFIG_KEY_0", "core.hooksPath".to_string()),
-        ("GIT_CONFIG_VALUE_0", hooks_dir),
     ];
+    hook_env.extend(receive_pack_git_config(hooks_dir));
 
     // Run receive-pack against the tempdir. Returns the *owned* subprocess
     // output (PackOutput) — crucially NOT a Response, so the post-push
@@ -1111,6 +1106,23 @@ pub async fn receive_pack(
     Ok(finalize_push(&state, ctx).await)
 }
 
+/// Per-process git configuration for the hydrated receive-pack workspace.
+fn receive_pack_git_config(hooks_dir: String) -> Vec<(&'static str, String)> {
+    vec![
+        // Override any repo-local core.hooksPath setting; defense in depth
+        // even though the hydrated workspace has no inherited config.
+        ("GIT_CONFIG_COUNT", "2".to_string()),
+        ("GIT_CONFIG_KEY_0", "core.hooksPath".to_string()),
+        ("GIT_CONFIG_VALUE_0", hooks_dir),
+        // A bare repository rejects deletion of its symbolic HEAD branch by
+        // default. Hydrated repositories are ephemeral, and cas_publish
+        // selects a surviving branch for the next manifest HEAD, so allow
+        // receive-pack to apply the deletion before that selection runs.
+        ("GIT_CONFIG_KEY_1", "receive.denyDeleteCurrent".to_string()),
+        ("GIT_CONFIG_VALUE_1", "ignore".to_string()),
+    ]
+}
+
 /// Buffered output of a `git --stateless-rpc` subprocess.
 ///
 /// The handler holds this as an owned value between subprocess completion
@@ -1921,11 +1933,148 @@ mod track_c_tests {
     use buzz_core::CommunityId;
     use nostr::{EventBuilder, Keys, Kind, Tag};
     use std::collections::BTreeMap;
+    use std::io::Write;
+    use std::process::Output;
 
     fn oid_sha1() -> String {
         "cb09a769da1c01f458fa6959d4e8eded38fac8d3".to_string()
     }
 
+    fn run_test_git(cwd: &Path, args: &[&str], extra_env: &[(&str, String)]) -> Output {
+        let mut cmd = std::process::Command::new("git");
+        cmd.current_dir(cwd)
+            .args(args)
+            .env_clear()
+            .env("PATH", std::env::var("PATH").unwrap_or_default())
+            .env("GIT_CONFIG_NOSYSTEM", "1")
+            .env("GIT_CONFIG_GLOBAL", "/dev/null")
+            .env("HOME", "/dev/null");
+        for (key, value) in extra_env {
+            cmd.env(key, value);
+        }
+        cmd.output().expect("run git")
+    }
+
+    fn run_test_receive_pack(repo: &Path, request: &[u8], extra_env: &[(&str, String)]) -> Output {
+        let mut cmd = std::process::Command::new("git");
+        cmd.arg("receive-pack")
+            .arg("--stateless-rpc")
+            .arg(repo)
+            .stdin(std::process::Stdio::piped())
+            .stdout(std::process::Stdio::piped())
+            .stderr(std::process::Stdio::piped())
+            .env_clear()
+            .env("PATH", std::env::var("PATH").unwrap_or_default())
+            .env("GIT_CONFIG_NOSYSTEM", "1")
+            .env("GIT_CONFIG_GLOBAL", "/dev/null")
+            .env("HOME", "/dev/null");
+        for (key, value) in extra_env {
+            cmd.env(key, value);
+        }
+
+        let mut child = cmd.spawn().expect("spawn receive-pack");
+        child
+            .stdin
+            .take()
+            .expect("receive-pack stdin")
+            .write_all(request)
+            .expect("write receive-pack request");
+        child.wait_with_output().expect("wait for receive-pack")
+    }
+
+    fn assert_git_success(output: Output, operation: &str) {
+        assert!(
+            output.status.success(),
+            "{operation} failed: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+    }
+
+    #[test]
+    fn receive_pack_config_allows_deleting_current_branch() {
+        let root = tempfile::TempDir::new().expect("tempdir");
+        let remote = root.path().join("remote.git");
+        let source = root.path().join("source");
+        let remote_arg = remote.to_str().expect("utf-8 remote path");
+        let source_arg = source.to_str().expect("utf-8 source path");
+
+        assert_git_success(
+            run_test_git(
+                root.path(),
+                &["init", "--bare", "--initial-branch=main", remote_arg],
+                &[],
+            ),
+            "initialize bare remote",
+        );
+        assert_git_success(
+            run_test_git(
+                root.path(),
+                &["init", "--initial-branch=main", source_arg],
+                &[],
+            ),
+            "initialize source repository",
+        );
+        assert_git_success(
+            run_test_git(source.as_path(), &["config", "user.name", "Buzz Test"], &[]),
+            "configure user name",
+        );
+        assert_git_success(
+            run_test_git(
+                source.as_path(),
+                &["config", "user.email", "buzz-test@example.com"],
+                &[],
+            ),
+            "configure user email",
+        );
+        std::fs::write(source.join("README.md"), "test\n").expect("write fixture");
+        assert_git_success(
+            run_test_git(source.as_path(), &["add", "README.md"], &[]),
+            "stage fixture",
+        );
+        assert_git_success(
+            run_test_git(source.as_path(), &["commit", "-m", "fixture"], &[]),
+            "commit fixture",
+        );
+        assert_git_success(
+            run_test_git(
+                source.as_path(),
+                &["push", remote_arg, "main:main", "main:master"],
+                &[],
+            ),
+            "seed main and master",
+        );
+
+        let oid_output = run_test_git(remote.as_path(), &["rev-parse", "refs/heads/main"], &[]);
+        assert!(oid_output.status.success());
+        let old_oid = String::from_utf8(oid_output.stdout)
+            .expect("utf-8 oid")
+            .trim()
+            .to_string();
+        let command = format!(
+            "{old_oid} {} refs/heads/main\0report-status\n",
+            "0".repeat(40)
+        );
+        let mut request = format!("{:04x}", command.len() + 4).into_bytes();
+        request.extend_from_slice(command.as_bytes());
+        request.extend_from_slice(b"0000");
+
+        let git_config = receive_pack_git_config(remote.join("hooks").display().to_string());
+        let output = run_test_receive_pack(remote.as_path(), &request, &git_config);
+        assert!(
+            output.status.success(),
+            "receive-pack failed: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+        assert!(
+            !receive_pack_report_rejected(&output.stdout),
+            "receive-pack rejected the deletion: {}",
+            String::from_utf8_lossy(&output.stdout)
+        );
+
+        assert!(!remote.join("refs/heads/main").exists());
+        assert!(remote.join("refs/heads/master").exists());
+    }
+
     /// A gzip-encoded request body is transparently inflated before it
     /// reaches the git subprocess. Git's smart-HTTP client gzips the
     /// upload-pack/receive-pack request body past a size threshold (fires
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-sdk/src/builders.rs b/crates/buzz-sdk/src/builders.rs
index 8cc9c8650a..9a139f0377 100644
--- a/crates/buzz-sdk/src/builders.rs
+++ b/crates/buzz-sdk/src/builders.rs
@@ -11,8 +11,8 @@ use buzz_core::{
         KIND_GIT_STATUS_CLOSED, KIND_GIT_STATUS_DRAFT, KIND_GIT_STATUS_MERGED,
         KIND_GIT_STATUS_OPEN, KIND_IA_ARCHIVE_REQUEST, KIND_IA_UNARCHIVE_REQUEST,
         KIND_MODERATION_BAN, KIND_MODERATION_RESOLVE_REPORT, KIND_MODERATION_TIMEOUT,
-        KIND_MODERATION_UNBAN, KIND_MODERATION_UNTIMEOUT, KIND_PRESENCE_UPDATE, KIND_USER_STATUS,
-        KIND_WORKFLOW_DEF, KIND_WORKFLOW_TRIGGER,
+        KIND_MODERATION_UNBAN, KIND_MODERATION_UNTIMEOUT, KIND_PRESENCE_UPDATE, KIND_PROJECT,
+        KIND_USER_STATUS, KIND_WORKFLOW_DEF, KIND_WORKFLOW_TRIGGER,
     },
     observer::{
         content_looks_like_nip44, OBSERVER_AGENT_TAG, OBSERVER_FRAME_CONTROL, OBSERVER_FRAME_TAG,
@@ -1499,12 +1499,7 @@ pub fn build_workflow_delete(
     author_pubkey: &str,
     workflow_id: Uuid,
 ) -> Result<EventBuilder, SdkError> {
-    let pk = check_pubkey_hex(author_pubkey, "author_pubkey")?;
-    let tags = vec![tag(&[
-        "a",
-        &format!("{}:{pk}:{workflow_id}", KIND_WORKFLOW_DEF),
-    ])?];
-    Ok(EventBuilder::new(Kind::Custom(KIND_DELETION as u16), "").tags(tags))
+    build_delete_addressable(KIND_WORKFLOW_DEF, author_pubkey, &workflow_id.to_string())
 }
 
 /// Build a workflow trigger event (kind 46020).
@@ -1838,6 +1833,364 @@ pub fn build_unarchive_identity_request(
     )
 }
 
+// ─── NIP-MP: Multi-repo projects (kind:30621) ────────────────────────────────
+//
+//  Public surface:
+//  • `validate_project_envelope` — Layer A protocol validator (8 ingest rules)
+//  • `build_project_with_tags`   — Layer A raw builder (content + tags, no canonicalization)
+//  • `ProjectMemberCoord`        — parsed member coordinate + optional relay hint
+//  • `build_project`             — Layer B writer-policy builder
+//  • `build_delete_addressable`  — generic NIP-09 kind:5 coordinate delete
+//
+//  Byte-length bounds from NIP-MP §Relay Processing:
+/// Maximum byte length of a project `d` tag value.
+pub const PROJECT_D_MAX_LEN: usize = 1024;
+/// Maximum byte length of a project `name` tag value.
+pub const PROJECT_NAME_MAX: usize = 256;
+/// Maximum byte length of a project `description` tag value.
+pub const PROJECT_DESCRIPTION_MAX: usize = 2048;
+/// Maximum byte length of a project `buzz-channel` tag value.
+pub const PROJECT_CHANNEL_MAX: usize = 256;
+/// Maximum byte length of a project `buzz-visibility` tag value.
+pub const PROJECT_VISIBILITY_MAX: usize = 256;
+/// Maximum number of `a` member tags per project event (checked before dedup).
+pub const PROJECT_MEMBER_CAP: usize = 64;
+
+/// A validated NIP-MP member `a`-tag coordinate with an optional relay hint.
+///
+/// Equality and `Hash` are by `coord` only (per spec: duplicate detection ignores hint).
+#[derive(Clone, Debug)]
+pub struct ProjectMemberCoord {
+    /// The full `30617:<owner-hex>:<repo-d>` coordinate string.
+    pub coord: String,
+    /// Optional opaque relay hint (third `a`-tag element, never validated by content).
+    pub hint: Option<String>,
+}
+
+impl PartialEq for ProjectMemberCoord {
+    fn eq(&self, other: &Self) -> bool {
+        self.coord == other.coord
+    }
+}
+
+impl Eq for ProjectMemberCoord {}
+
+impl std::hash::Hash for ProjectMemberCoord {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        self.coord.hash(state);
+    }
+}
+
+impl ProjectMemberCoord {
+    /// Parse a full `30617:<owner-hex>:<repo-d>` coordinate string.
+    ///
+    /// Accepts an optional relay hint as the third colon-separated element
+    /// after the split, but the split is always first-two-colons: kind, owner,
+    /// everything-else-as-repo-d.
+    ///
+    /// Rules enforced:
+    /// - Exactly three segments after splitting on the first two colons
+    /// - First segment must be the literal string `"30617"`
+    /// - Second segment must be exactly 64 lowercase hex characters
+    /// - Third segment (repo-d) must be non-empty
+    /// - Uppercase owners are rejected (never normalized)
+    pub fn parse_full(coord: &str) -> Result<Self, SdkError> {
+        // Split on first two colons only: kind:owner:rest
+        let mut parts = coord.splitn(3, ':');
+        let kind_part = parts.next().unwrap_or("");
+        let owner_part = parts.next().unwrap_or("");
+        let rest = parts.next().unwrap_or("");
+
+        if kind_part != "30617" {
+            return Err(SdkError::InvalidInput(format!(
+                "member coordinate must start with '30617:' (got kind {kind_part:?})"
+            )));
+        }
+        if owner_part.len() != 64 || !owner_part.chars().all(|c| c.is_ascii_hexdigit()) {
+            return Err(SdkError::InvalidInput(format!(
+                "member owner must be a 64-character hex pubkey (got {owner_part:?})"
+            )));
+        }
+        // Reject uppercase (spec: lowercase hex required)
+        if owner_part.chars().any(|c| c.is_ascii_uppercase()) {
+            return Err(SdkError::InvalidInput(
+                "member owner hex must be lowercase".into(),
+            ));
+        }
+        if rest.is_empty() {
+            return Err(SdkError::InvalidInput(
+                "member coordinate repo-d must not be empty".into(),
+            ));
+        }
+        Ok(ProjectMemberCoord {
+            coord: format!("30617:{owner_part}:{rest}"),
+            hint: None,
+        })
+    }
+
+    /// Returns the `a`-tag element slice: `[coord]` or `[coord, hint]`.
+    pub fn to_tag_parts(&self) -> Vec<String> {
+        let mut parts = vec!["a".to_string(), self.coord.clone()];
+        if let Some(h) = &self.hint {
+            parts.push(h.clone());
+        }
+        parts
+    }
+}
+
+/// **Layer A**: Validate a complete kind:30621 envelope against the 8 NIP-MP
+/// ingest rules.  This is the single source of protocol truth used by both
+/// `build_project_with_tags` (raw path) and `build_project` (policy path).
+///
+/// Rules enforced (matches relay `buzz-db` ingest logic):
+/// 1. `d` cardinality: exactly one `d` tag.
+/// 2. `d` value: non-empty, ≤1024 bytes.
+/// 3. Member cap: raw count of every `a` tag ≤ 64 (checked **before** per-tag
+///    parsing, matching relay rule order).
+/// 4. Member tag arity: every `a` tag has 2 or 3 elements (no more, no fewer).
+/// 5. Member coordinate grammar: first-two-colons split; kind literal `"30617"`;
+///    owner lowercase 64-hex; repo-d non-empty verbatim.
+/// 6. Member deduplication: coordinate equality only (hint ignored); any
+///    coordinate that appears more than once is a duplicate.
+/// 7. Singleton metadata: each of `name`, `description`, `buzz-channel`,
+///    `buzz-visibility` appears at most once.
+/// 8. Metadata byte lengths: `name` ≤256, `description` ≤2048,
+///    `buzz-channel` ≤256, `buzz-visibility` ≤256.
+pub fn validate_project_envelope(tags: &[Tag], _content: &str) -> Result<(), SdkError> {
+    // --- Rule 1 & 2: d tag ---
+    let d_tags: Vec<&Tag> = tags.iter().filter(|t| tag_name(t) == Some("d")).collect();
+    match d_tags.len() {
+        0 => {
+            return Err(SdkError::InvalidInput(
+                "project must have exactly one 'd' tag (rule: d-cardinality)".into(),
+            ))
+        }
+        1 => {}
+        _ => {
+            return Err(SdkError::InvalidInput(
+                "project must have exactly one 'd' tag (rule: d-cardinality)".into(),
+            ))
+        }
+    }
+    let d_val = tag_value(d_tags[0]).unwrap_or("");
+    if d_val.is_empty() {
+        return Err(SdkError::InvalidInput(
+            "project 'd' tag must not be empty (rule: d-empty)".into(),
+        ));
+    }
+    if d_val.len() > PROJECT_D_MAX_LEN {
+        return Err(SdkError::InvalidInput(format!(
+            "project 'd' tag exceeds {PROJECT_D_MAX_LEN} bytes (rule: d-empty)"
+        )));
+    }
+
+    let a_tags: Vec<&Tag> = tags.iter().filter(|t| tag_name(t) == Some("a")).collect();
+
+    // --- Rule 3: member cap (checked before per-tag parsing, matching relay rule order) ---
+    if a_tags.len() > PROJECT_MEMBER_CAP {
+        return Err(SdkError::InvalidInput(format!(
+            "project exceeds member cap of {PROJECT_MEMBER_CAP} (got {}) (rule: member-cap)",
+            a_tags.len()
+        )));
+    }
+
+    // --- Rule 4: member arity ---
+    for a in &a_tags {
+        let len = a.as_slice().len() - 1; // exclude the "a" name element
+        if !(1..=2).contains(&len) {
+            return Err(SdkError::InvalidInput(format!(
+                "member 'a' tag must have 1 or 2 value elements (got {len}) (rule: member-tag-arity)"
+            )));
+        }
+    }
+
+    // --- Rules 5 & 6: coordinate grammar + deduplication ---
+    let mut seen_coords: std::collections::HashSet<String> = std::collections::HashSet::new();
+    for a in &a_tags {
+        let coord_val = tag_value(a).unwrap_or("");
+        ProjectMemberCoord::parse_full(coord_val).map_err(|e| {
+            SdkError::InvalidInput(format!("{e} (rule: member-coordinate-malformed)"))
+        })?;
+        if !seen_coords.insert(coord_val.to_string()) {
+            return Err(SdkError::InvalidInput(format!(
+                "duplicate member coordinate {coord_val:?} (rule: member-duplicate)"
+            )));
+        }
+    }
+
+    // --- Rules 7 & 8: singleton metadata + byte bounds ---
+    let singleton_fields = [
+        (
+            "name",
+            PROJECT_NAME_MAX,
+            "metadata-cardinality",
+            "metadata-length",
+        ),
+        (
+            "description",
+            PROJECT_DESCRIPTION_MAX,
+            "metadata-cardinality",
+            "metadata-length",
+        ),
+        (
+            "buzz-channel",
+            PROJECT_CHANNEL_MAX,
+            "metadata-cardinality",
+            "metadata-length",
+        ),
+        (
+            "buzz-visibility",
+            PROJECT_VISIBILITY_MAX,
+            "metadata-cardinality",
+            "metadata-length",
+        ),
+    ];
+    for (field, max_bytes, card_rule, len_rule) in singleton_fields {
+        let matches: Vec<&Tag> = tags.iter().filter(|t| tag_name(t) == Some(field)).collect();
+        if matches.len() > 1 {
+            return Err(SdkError::InvalidInput(format!(
+                "project must have at most one '{field}' tag (rule: {card_rule})"
+            )));
+        }
+        if let Some(t) = matches.first() {
+            let val = tag_value(t).unwrap_or("");
+            if val.len() > max_bytes {
+                return Err(SdkError::InvalidInput(format!(
+                    "'{field}' tag exceeds {max_bytes} bytes (rule: {len_rule})"
+                )));
+            }
+        }
+    }
+
+    Ok(())
+}
+
+/// Helper: tag name (first element).
+fn tag_name(tag: &Tag) -> Option<&str> {
+    tag.as_slice().first().map(String::as_str)
+}
+
+/// Helper: tag value (second element).
+fn tag_value(tag: &Tag) -> Option<&str> {
+    tag.as_slice().get(1).map(String::as_str)
+}
+
+/// **Layer A raw builder**: Build a kind:30621 project event from a raw
+/// `content` string and a raw `tags` slice, without any canonicalization.
+///
+/// Validates the entire envelope through `validate_project_envelope` before
+/// accepting it.  The caller is responsible for supplying the correct `d` tag.
+/// This is the path exercised by fixture conformance tests and by read-modify-
+/// write mutations in the CLI.
+pub fn build_project_with_tags(content: &str, tags: Vec<Tag>) -> Result<EventBuilder, SdkError> {
+    validate_project_envelope(&tags, content)?;
+    Ok(EventBuilder::new(Kind::Custom(KIND_PROJECT as u16), content).tags(tags))
+}
+
+/// **Layer B writer-policy builder**: Build a kind:30621 project event with
+/// enforced writer policy:
+/// - The `d` tag is constructed from `slug`; `check_project_slug` rejects
+///   an empty or over-length slug.
+/// - `channel` must be a valid UUID string.
+/// - `visibility` must be `"listed"` or `"unlisted"`.
+/// - Content is always empty.
+/// - Member coordinates are parsed through `ProjectMemberCoord::parse_full`.
+///
+/// The resulting envelope is validated through Layer A before the builder is
+/// returned.
+pub fn build_project(
+    slug: &str,
+    name: Option<&str>,
+    description: Option<&str>,
+    members: &[ProjectMemberCoord],
+    channel: Option<&str>,
+    visibility: Option<&str>,
+) -> Result<EventBuilder, SdkError> {
+    // Slug validation
+    if slug.is_empty() {
+        return Err(SdkError::InvalidInput(
+            "project slug must not be empty".into(),
+        ));
+    }
+    if slug.len() > PROJECT_D_MAX_LEN {
+        return Err(SdkError::InvalidInput(format!(
+            "project slug must not exceed {PROJECT_D_MAX_LEN} bytes (got {})",
+            slug.len()
+        )));
+    }
+
+    // Channel UUID validation
+    if let Some(ch) = channel {
+        uuid::Uuid::parse_str(ch).map_err(|_| {
+            SdkError::InvalidInput(format!("buzz-channel must be a valid UUID (got {ch:?})"))
+        })?;
+    }
+
+    // Visibility enum validation
+    if let Some(vis) = visibility {
+        if vis != "listed" && vis != "unlisted" {
+            return Err(SdkError::InvalidInput(format!(
+                "buzz-visibility must be 'listed' or 'unlisted' (got {vis:?})"
+            )));
+        }
+    }
+
+    let mut tags: Vec<Tag> = Vec::new();
+    tags.push(tag(&["d", slug])?);
+
+    if let Some(n) = name {
+        tags.push(tag(&["name", n])?);
+    }
+    if let Some(d) = description {
+        tags.push(tag(&["description", d])?);
+    }
+    for m in members {
+        let tag_parts = m.to_tag_parts();
+        let parts: Vec<&str> = tag_parts.iter().map(|s| s.as_str()).collect();
+        // Safety: to_tag_parts always produces ["a", coord, ...hint]
+        tags.push(
+            Tag::parse(parts.iter().copied()).map_err(|e| SdkError::InvalidTag(e.to_string()))?,
+        );
+    }
+    if let Some(ch) = channel {
+        tags.push(tag(&["buzz-channel", ch])?);
+    }
+    if let Some(vis) = visibility {
+        tags.push(tag(&["buzz-visibility", vis])?);
+    }
+
+    build_project_with_tags("", tags)
+}
+
+/// **Generic NIP-09 coordinate delete**: Build a kind:5 deletion event with
+/// a single `a`-tag addressing `<kind>:<pubkey>:<d>`.
+///
+/// Validates:
+/// - `kind` is an addressable kind (10000–19999 or 30000–39999).
+/// - `pubkey` is a 64-character lowercase hex string.
+/// - `d` is non-empty.
+///
+/// `build_workflow_delete` delegates to this function.
+pub fn build_delete_addressable(
+    kind: u32,
+    pubkey: &str,
+    d: &str,
+) -> Result<EventBuilder, SdkError> {
+    let is_addressable = (10000..20000).contains(&kind) || (30000..40000).contains(&kind);
+    if !is_addressable {
+        return Err(SdkError::InvalidInput(format!(
+            "kind {kind} is not an addressable kind (must be 10000–19999 or 30000–39999)"
+        )));
+    }
+    let pk = check_pubkey_hex(pubkey, "pubkey")?;
+    if d.is_empty() {
+        return Err(SdkError::InvalidInput("d must not be empty".into()));
+    }
+    let coord = format!("{kind}:{pk}:{d}");
+    let tags = vec![tag(&["a", &coord])?];
+    Ok(EventBuilder::new(Kind::Custom(KIND_DELETION as u16), "").tags(tags))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -3884,4 +4237,280 @@ mod tests {
             .iter()
             .any(|t| t.as_slice().first().map(String::as_str) == Some("replaced-by")));
     }
+
+    // ── NIP-MP cap-before-arity ordering ─────────────────────────────────────
+
+    /// When an envelope exceeds the member cap AND contains a malformed `a` tag,
+    /// the validator must fire `member-cap` (rule 3) — not `member-tag-arity`
+    /// (rule 4).  This matches the relay's ingest ordering and means a client
+    /// sending an oversized list never receives a per-tag parse error.
+    #[test]
+    fn validate_project_envelope_cap_wins_over_arity_when_both_fail() {
+        let owner = "a".repeat(64);
+        // Build 65 well-formed `a` tags — enough to trigger the cap.
+        let mut tags = vec![Tag::parse(["d", "platform"]).unwrap()];
+        for i in 0..65usize {
+            let coord = format!("30617:{owner}:repo-{i}");
+            tags.push(Tag::parse(["a", &coord]).unwrap());
+        }
+        // Also add one malformed tag (four elements) that would fire
+        // member-tag-arity if evaluated before the cap check.
+        let coord_extra = format!("30617:{owner}:repo-extra");
+        tags.push(
+            Tag::parse([
+                "a",
+                &coord_extra,
+                "wss://relay.example.com",
+                "extra-element",
+            ])
+            .unwrap(),
+        );
+
+        let err = validate_project_envelope(&tags, "").unwrap_err();
+        let msg = err.to_string();
+        assert!(
+            msg.contains("member-cap"),
+            "expected member-cap to win, got: {msg}"
+        );
+        assert!(
+            !msg.contains("member-tag-arity"),
+            "arity rule must not fire before cap rule, got: {msg}"
+        );
+    }
+
+    // ── Layer B writer-policy builder ───────────────────────────────────────
+
+    const OWNER64: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+    const VALID_UUID: &str = "3580ca9b-47b4-4af9-b22a-1068778f26c6";
+
+    fn member_coord(repo: &str) -> ProjectMemberCoord {
+        ProjectMemberCoord::parse_full(&format!("30617:{OWNER64}:{repo}")).unwrap()
+    }
+
+    #[test]
+    fn build_project_emitted_envelope_has_correct_shape() {
+        // slug, name, description, channel, visibility, and one member.
+        let m = member_coord("buzz");
+        let ev = sign(
+            build_project(
+                "my-proj",
+                Some("My Project"),
+                Some("A description"),
+                &[m],
+                Some(VALID_UUID),
+                Some("listed"),
+            )
+            .expect("Layer B must accept valid inputs"),
+        );
+
+        // Kind must be 30621.
+        assert_eq!(ev.kind.as_u16(), KIND_PROJECT as u16);
+        // Content must be empty (Layer B policy).
+        assert!(ev.content.is_empty(), "content must be empty");
+
+        let all_tags: Vec<Vec<String>> = ev.tags.iter().map(|t| t.as_slice().to_vec()).collect();
+
+        // d tag must be present exactly once.
+        let d_tags: Vec<_> = all_tags.iter().filter(|t| t[0] == "d").collect();
+        assert_eq!(d_tags.len(), 1);
+        assert_eq!(d_tags[0][1], "my-proj");
+
+        // name, description, buzz-channel, buzz-visibility present.
+        let name_tags: Vec<_> = all_tags.iter().filter(|t| t[0] == "name").collect();
+        assert_eq!(name_tags.len(), 1);
+        assert_eq!(name_tags[0][1], "My Project");
+
+        let desc_tags: Vec<_> = all_tags.iter().filter(|t| t[0] == "description").collect();
+        assert_eq!(desc_tags.len(), 1);
+        assert_eq!(desc_tags[0][1], "A description");
+
+        let ch_tags: Vec<_> = all_tags.iter().filter(|t| t[0] == "buzz-channel").collect();
+        assert_eq!(ch_tags.len(), 1);
+        assert_eq!(ch_tags[0][1], VALID_UUID);
+
+        let vis_tags: Vec<_> = all_tags
+            .iter()
+            .filter(|t| t[0] == "buzz-visibility")
+            .collect();
+        assert_eq!(vis_tags.len(), 1);
+        assert_eq!(vis_tags[0][1], "listed");
+
+        // member a tag.
+        let a_tags: Vec<_> = all_tags.iter().filter(|t| t[0] == "a").collect();
+        assert_eq!(a_tags.len(), 1);
+        assert_eq!(a_tags[0][1], format!("30617:{OWNER64}:buzz"));
+    }
+
+    #[test]
+    fn build_project_optional_fields_absent_when_not_supplied() {
+        let m = member_coord("core");
+        let ev = sign(
+            build_project("my-proj", None, None, &[m], None, None)
+                .expect("minimal build must succeed"),
+        );
+        let names: Vec<_> = ev
+            .tags
+            .iter()
+            .filter(|t| t.as_slice().first().map(|s| s.as_str()) == Some("name"))
+            .collect();
+        assert!(names.is_empty(), "name tag must not be emitted when absent");
+    }
+
+    #[test]
+    fn build_project_rejects_empty_slug() {
+        let m = member_coord("r");
+        let err = build_project("", None, None, &[m], None, None).unwrap_err();
+        assert!(
+            matches!(err, SdkError::InvalidInput(_)),
+            "empty slug must be InvalidInput, got: {err:?}"
+        );
+        assert!(err.to_string().contains("empty"));
+    }
+
+    #[test]
+    fn build_project_rejects_overlong_slug() {
+        let long_slug = "a".repeat(PROJECT_D_MAX_LEN + 1);
+        let m = member_coord("r");
+        let err = build_project(&long_slug, None, None, &[m], None, None).unwrap_err();
+        assert!(matches!(err, SdkError::InvalidInput(_)));
+    }
+
+    #[test]
+    fn build_project_rejects_invalid_channel_uuid() {
+        let m = member_coord("r");
+        let err = build_project("slug", None, None, &[m], Some("not-a-uuid"), None).unwrap_err();
+        assert!(matches!(err, SdkError::InvalidInput(_)));
+        assert!(err.to_string().contains("UUID") || err.to_string().contains("uuid"));
+    }
+
+    #[test]
+    fn build_project_rejects_invalid_visibility_token() {
+        let m = member_coord("r");
+        let err = build_project("slug", None, None, &[m], None, Some("chartreuse")).unwrap_err();
+        assert!(matches!(err, SdkError::InvalidInput(_)));
+        assert!(err.to_string().contains("listed") || err.to_string().contains("unlisted"));
+    }
+
+    #[test]
+    fn build_project_rejects_over_cap_members() {
+        let members: Vec<_> = (0..=PROJECT_MEMBER_CAP)
+            .map(|i| member_coord(&format!("repo-{i}")))
+            .collect();
+        let err = build_project("slug", None, None, &members, None, None).unwrap_err();
+        assert!(matches!(err, SdkError::InvalidInput(_)));
+        assert!(
+            err.to_string().contains("member-cap"),
+            "over-cap must report member-cap, got: {err}"
+        );
+    }
+
+    #[test]
+    fn build_project_rejects_duplicate_members() {
+        let m = member_coord("same");
+        let err = build_project("slug", None, None, &[m.clone(), m], None, None).unwrap_err();
+        assert!(matches!(err, SdkError::InvalidInput(_)));
+        assert!(
+            err.to_string().contains("dedup") || err.to_string().contains("duplicate"),
+            "duplicate member must report dedup, got: {err}"
+        );
+    }
+
+    #[test]
+    fn build_project_content_is_always_empty() {
+        // build_project forces content="" regardless; Layer A also enforces
+        // that the envelope is valid. Any non-empty content would be dropped.
+        // This test pins the Layer B content-forced-empty policy.
+        let m = member_coord("r");
+        let ev = sign(build_project("slug", None, None, &[m], None, None).unwrap());
+        assert!(
+            ev.content.is_empty(),
+            "Layer B must always emit empty content"
+        );
+    }
+
+    // ── NIP-MP conformance fixtures ──────────────────────────────────────────
+    // `build_project_with_tags` directly.  Accept cases must build; reject
+    // cases must fail with an error message containing the expected rule name.
+    // A count assertion guards against silent omissions.
+    //
+    // `include_str!` path is relative to this source file.
+    fn nip_mp_fixture_tags(json_tags: &serde_json::Value) -> Vec<Tag> {
+        json_tags
+            .as_array()
+            .unwrap()
+            .iter()
+            .map(|t| {
+                let parts: Vec<String> = t
+                    .as_array()
+                    .unwrap()
+                    .iter()
+                    .map(|v| v.as_str().unwrap().to_string())
+                    .collect();
+                let parts_ref: Vec<&str> = parts.iter().map(String::as_str).collect();
+                Tag::parse(parts_ref.iter().copied())
+                    .unwrap_or_else(|e| panic!("fixture tag parse error: {e}\n  raw: {t}"))
+            })
+            .collect()
+    }
+
+    #[test]
+    fn nip_mp_fixtures_all_31_cases_exercised() {
+        const FIXTURE_JSON: &str = include_str!("../../../docs/nips/NIP-MP.fixtures.json");
+
+        let data: serde_json::Value =
+            serde_json::from_str(FIXTURE_JSON).expect("fixture JSON must parse");
+        let cases = data["cases"].as_array().expect("cases must be array");
+
+        // Count gate: the spec says "required to test against this one file"
+        // with the exact count as-shipped.
+        assert_eq!(
+            cases.len(),
+            31,
+            "expected 31 fixture cases, got {} — was NIP-MP.fixtures.json edited?",
+            cases.len()
+        );
+
+        let mut accept_count = 0usize;
+        let mut reject_count = 0usize;
+
+        for case in cases {
+            let name = case["name"].as_str().unwrap();
+            let expect = case["expect"].as_str().unwrap();
+            let template = &case["template"];
+            let content = template["content"].as_str().unwrap_or("");
+            let tags = nip_mp_fixture_tags(&template["tags"]);
+
+            match expect {
+                "accept" => {
+                    build_project_with_tags(content, tags).unwrap_or_else(|e| {
+                        panic!("fixture '{name}' (accept) must build successfully, got: {e}")
+                    });
+                    accept_count += 1;
+                }
+                "reject" => {
+                    let reject_rules = case["reject_rules"]
+                        .as_array()
+                        .expect("reject case must have reject_rules")
+                        .iter()
+                        .map(|r| r.as_str().unwrap().to_string())
+                        .collect::<Vec<_>>();
+
+                    let err = build_project_with_tags(content, tags).unwrap_err();
+                    let err_msg = err.to_string();
+
+                    // The error must mention at least one of the expected rules.
+                    let rule_matched = reject_rules.iter().any(|r| err_msg.contains(r.as_str()));
+                    assert!(
+                        rule_matched,
+                        "fixture '{name}' rejected with wrong rule.\n  expected one of: {reject_rules:?}\n  got error: {err_msg}"
+                    );
+                    reject_count += 1;
+                }
+                other => panic!("fixture '{name}' has unknown expect value: {other:?}"),
+            }
+        }
+
+        assert_eq!(accept_count, 11, "expected 11 accept cases");
+        assert_eq!(reject_count, 20, "expected 20 reject cases");
+    }
 }
diff --git a/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 e8145f5468..d0b99c53f6 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -1,7 +1,7 @@
 {
   "name": "buzz",
   "private": true,
-  "version": "0.5.3",
+  "version": "0.5.4",
   "type": "module",
   "scripts": {
     "dev": "vite",
diff --git a/desktop/playwright.config.ts b/desktop/playwright.config.ts
index 7ce7f48389..796fdede1e 100644
--- a/desktop/playwright.config.ts
+++ b/desktop/playwright.config.ts
@@ -41,6 +41,7 @@ export default defineConfig({
         "**/channel-mute.spec.ts",
         "**/channel-star.spec.ts",
         "**/channel-controls.spec.ts",
+        "**/channel-activity-popover.spec.ts",
         "**/active-turn-resilience.spec.ts",
         "**/profile-active-turn.spec.ts",
         "**/config-bridge-screenshots.spec.ts",
@@ -126,12 +127,14 @@ export default defineConfig({
         "**/agent-provider-dropdowns.spec.ts",
         "**/agent-lifecycle-feedback.spec.ts",
         "**/agent-access-warning.spec.ts",
+        "**/edit-agent-run-on.spec.ts",
         "**/inbox-live-update.spec.ts",
         "**/mesh-compute.spec.ts",
         "**/observer-archive-policy.spec.ts",
         "**/harness-management.spec.ts",
         "**/harness-catalog-screenshots.spec.ts",
         "**/inline-custom-harness.spec.ts",
+        "**/where-to-run-config.spec.ts",
         "**/huddle-transcription.spec.ts",
       ],
       use: {
diff --git a/desktop/scripts/build-release-config.mjs b/desktop/scripts/build-release-config.mjs
index 389d18aec5..d1cd8181eb 100644
--- a/desktop/scripts/build-release-config.mjs
+++ b/desktop/scripts/build-release-config.mjs
@@ -52,6 +52,15 @@ const releaseConfig = {
   },
 };
 
+// Tauri applies --config after platform-specific config using RFC 7396.
+// Any externalBin value here would therefore replace the platform sidecar list,
+// while null would silently delete it. This delta must never own that key.
+if (Object.hasOwn(releaseConfig.bundle, "externalBin")) {
+  throw new Error(
+    "Release config must not define bundle.externalBin; sidecars are platform-specific",
+  );
+}
+
 console.log(`Updater enabled -> ${updaterEndpoint}`);
 
 writeFileSync(outputConfigPath, `${JSON.stringify(releaseConfig, null, 2)}\n`);
diff --git a/desktop/src-tauri/Cargo.lock b/desktop/src-tauri/Cargo.lock
index 00d3fba3b5..365c8f712e 100644
--- a/desktop/src-tauri/Cargo.lock
+++ b/desktop/src-tauri/Cargo.lock
@@ -1036,7 +1036,7 @@ dependencies = [
 
 [[package]]
 name = "buzz-desktop"
-version = "0.5.3"
+version = "0.5.4"
 dependencies = [
  "anyhow",
  "arboard",
@@ -1044,6 +1044,7 @@ dependencies = [
  "audioadapter-buffers",
  "axum",
  "base64 0.22.1",
+ "block2",
  "buzz-agent",
  "buzz-core",
  "buzz-media",
@@ -1106,6 +1107,7 @@ dependencies = [
  "tauri-plugin-single-instance",
  "tauri-plugin-updater",
  "tauri-plugin-window-state",
+ "tauri-utils",
  "tempfile",
  "tokio",
  "tokio-tungstenite 0.29.0",
@@ -6122,9 +6124,9 @@ dependencies = [
 
 [[package]]
 name = "nostr"
-version = "0.44.6"
+version = "0.44.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e826dd648489de2c5b293920e20b92932ef820302007c1987c758d4d06eeb2cf"
+checksum = "c7d3d987ea7078dc36947cde532637c472a229426702e4331dd7667325378bd9"
 dependencies = [
  "base64 0.22.1",
  "bech32",
@@ -6166,9 +6168,9 @@ dependencies = [
 
 [[package]]
 name = "nostr-relay-pool"
-version = "0.44.1"
+version = "0.44.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "91b2c039df4f96c4bf7dae52a74fd5516ad6dda83a11c0c69dea91b5255a4f37"
+checksum = "c85c54d6ca9aae4ae2bf19a7663ba9db5f45f783f1d24aff55f006386b8b99a1"
 dependencies = [
  "async-utility",
  "async-wsocket",
diff --git a/desktop/src-tauri/Cargo.toml b/desktop/src-tauri/Cargo.toml
index b80684f955..bf3a4ffe96 100644
--- a/desktop/src-tauri/Cargo.toml
+++ b/desktop/src-tauri/Cargo.toml
@@ -2,7 +2,7 @@
 
 [package]
 name = "buzz-desktop"
-version = "0.5.3"
+version = "0.5.4"
 description = "Buzz desktop app"
 authors = ["you"]
 edition = "2021"
@@ -46,8 +46,9 @@ notify-rust = "4"
 webkit2gtk = { version = "=2.0.2", features = ["v2_22"] }
 
 [target.'cfg(target_os = "macos")'.dependencies]
+block2 = { version = "0.6", default-features = false, features = ["std"] }
 objc2 = { version = "0.6.4", default-features = false }
-objc2-app-kit = { version = "0.3.2", default-features = false, features = ["NSHapticFeedback", "NSMenu", "NSMenuItem", "NSStatusItem"] }
+objc2-app-kit = { version = "0.3.2", default-features = false, features = ["NSEvent", "NSHapticFeedback", "NSMenu", "NSMenuItem", "NSStatusItem", "block2"] }
 objc2-foundation = { version = "0.3.2", default-features = false, features = ["NSProcessInfo", "NSString"] }
 keyring = { version = "3.6.3", default-features = false, features = ["apple-native", "vendored"], optional = true }
 security-framework = { version = "3.7.0", features = ["OSX_10_15"] }
@@ -138,6 +139,7 @@ strip-ansi-escapes = "0.2"
 tracing = "0.1"
 
 [dev-dependencies]
+tauri-utils = "2"
 # `test-util` enables tokio's paused-clock (`start_paused`) so the relay
 # admission gate tests can assert exact wait durations without real sleeps.
 tokio = { version = "1", features = ["test-util"] }
diff --git a/desktop/src-tauri/assets/card_template.png b/desktop/src-tauri/assets/card_template.png
new file mode 100644
index 0000000000..2225d1d442
Binary files /dev/null and b/desktop/src-tauri/assets/card_template.png differ
diff --git a/desktop/src-tauri/src/commands/agent_config.rs b/desktop/src-tauri/src/commands/agent_config.rs
index 5a26f0f645..7aded79599 100644
--- a/desktop/src-tauri/src/commands/agent_config.rs
+++ b/desktop/src-tauri/src/commands/agent_config.rs
@@ -8,14 +8,14 @@ use crate::{
             read_goose_file_config,
             reader::read_config_surface,
             types::{
-                AcpConfigOptionEntry, AcpConfigOptionValue, AcpModelEntry, ConfigOrigin,
-                NormalizedField, RuntimeConfigSurface, SessionConfigCache,
+                AcpConfigOptionEntry, AcpConfigOptionValue, AcpModelEntry, InheritedConfigTiers,
+                RuntimeConfigSurface, SessionConfigCache,
             },
         },
-        current_instance_id, known_acp_runtime, load_managed_agents, load_personas,
-        resolve_effective_prompt_model_provider, save_managed_agents, sync_managed_agent_processes,
+        current_instance_id, is_reserved_env_key, is_well_formed_env_key, known_acp_runtime,
+        load_managed_agents, load_personas, save_managed_agents, sync_managed_agent_processes,
         AgentDefinition, GlobalAgentConfig, KnownAcpRuntime, ManagedAgentRecord,
-        ManagedAgentRuntimeKey,
+        ManagedAgentRuntimeKey, MAX_ENV_VALUE_BYTES,
     },
 };
 
@@ -36,28 +36,86 @@ pub struct RuntimeFileConfigSubset {
     pub satisfied_env_keys: Vec<String>,
 }
 
-/// Resolve the config surface with persona and global default values applied.
+/// Sanitize a raw env map from an inherited tier (persona or global) with the
+/// same rules `merged_user_env` applies at spawn time: reserved keys, malformed
+/// keys, NUL-byte values, and oversize values are stripped silently.
+fn sanitize_inherited_env(
+    raw: &std::collections::BTreeMap<String, String>,
+) -> std::collections::BTreeMap<String, String> {
+    raw.iter()
+        .filter(|(k, v)| {
+            !is_reserved_env_key(k)
+                && is_well_formed_env_key(k)
+                && !v.contains('\0')
+                && v.len() <= MAX_ENV_VALUE_BYTES
+        })
+        .map(|(k, v)| (k.clone(), v.clone()))
+        .collect()
+}
+
+/// Normalize a structured field value: blank/whitespace-only collapses to
+/// `None`, matching `effective_config`'s `non_blank` helper.
+fn non_blank(v: Option<&str>) -> Option<String> {
+    v.filter(|s| !s.trim().is_empty()).map(str::to_owned)
+}
+
+/// Build a sanitized `InheritedConfigTiers` snapshot at the command boundary.
 ///
-/// Linked instances are definition-authoritative: the record's own
-/// system_prompt/model/provider are cleared before applying, so a stale
-/// materialized snapshot can never shadow the persona's current values or a
-/// blank-definition fallthrough to global defaults (mirrors
-/// `effective_config::resolve_linked`). Definition-less instances keep their
-/// own explicit values.
+/// Persona env, global env, and harness definition env are sanitized with
+/// spawn-equivalent rules. Structured fields are normalized (blank → None).
+/// A missing persona (orphaned link) yields empty persona tiers — the panel
+/// still renders from record/global while spawn independently refuses.
+fn build_inherited_tiers(
+    record_persona_id: Option<&str>,
+    record_runtime: Option<&str>,
+    personas: &[AgentDefinition],
+    global: &GlobalAgentConfig,
+) -> InheritedConfigTiers {
+    let persona = record_persona_id.and_then(|pid| personas.iter().find(|p| p.id == pid));
+
+    let persona_env = persona
+        .map(|p| sanitize_inherited_env(&p.env_vars))
+        .unwrap_or_default();
+    let global_env = sanitize_inherited_env(&global.env_vars);
+
+    // Definition env: same resolution as spawn (record.runtime → persona.runtime → "").
+    // Reserved keys stripped; no malformed-key / NUL / oversize check needed because
+    // harness definitions are local admin-authored JSON, not user-provided data — but
+    // we apply `sanitize_inherited_env` for defense-in-depth (same rules as the other tiers).
+    let definition_env = {
+        let runtime_id = record_runtime
+            .or_else(|| persona.and_then(|p| p.runtime.as_deref()))
+            .unwrap_or("");
+        crate::managed_agents::custom_harnesses::lookup_loaded_harness_by_id(runtime_id)
+            .map(|def| sanitize_inherited_env(&def.env))
+            .unwrap_or_default()
+    };
+
+    let persona_model = persona.and_then(|p| non_blank(p.model.as_deref()));
+    let persona_provider = persona.and_then(|p| non_blank(p.provider.as_deref()));
+    let persona_prompt = persona.and_then(|p| non_blank(Some(&p.system_prompt)));
+    let global_model = non_blank(global.model.as_deref());
+    let global_provider = non_blank(global.provider.as_deref());
+
+    InheritedConfigTiers {
+        persona_env,
+        global_env,
+        definition_env,
+        persona_model,
+        persona_provider,
+        persona_prompt,
+        global_model,
+        global_provider,
+    }
+}
+
+/// Resolve the config surface with inherited persona and global tiers applied.
 ///
-/// The pipeline: resolve the linked persona's prompt/model/provider, inject
-/// each into the record only where the record lacks its own value, let
-/// `read_config_surface` tag those injected fields `BuzzExplicit`, then re-tag
-/// exactly the injected fields to `PersonaDefault`.
-///
-/// Global defaults fill in when neither the record nor the linked persona
-/// provides a value. They are re-tagged to `GlobalDefault` so the UI can
-/// display "inherited from global defaults".
-///
-/// The re-tag is triple-gated — a field is re-tagged only when (a) the record
-/// did not already have it (`!had_*`), (b) the surface produced the field, and
-/// (c) the reader tagged it `BuzzExplicit`. A value the user set explicitly in
-/// Buzz keeps `had_* == true` and is never re-tagged.
+/// Persona-linked instances have their system_prompt/model/provider cleared
+/// first (definition-authoritative): stale materialized snapshots can never
+/// shadow live persona values. The reader then resolves each field through its
+/// full candidate list (record env > ACP > persona env > global env > structured
+/// persona/global > config file) via `resolve_with_override`.
 fn resolve_config_surface(
     mut record: ManagedAgentRecord,
     personas: &[AgentDefinition],
@@ -65,146 +123,23 @@ fn resolve_config_surface(
     session_cache: Option<&SessionConfigCache>,
     global: &GlobalAgentConfig,
 ) -> RuntimeConfigSurface {
-    // Linked instances are definition-authoritative (mirrors
-    // `effective_config::resolve_linked`): the record's own
-    // system_prompt/model/provider fields are, at best, a stale materialized
-    // snapshot from the last `apply_persona_snapshot` — never a legitimate
-    // live override, since `update_managed_agent` blocks writing these three
-    // fields for linked instances. Clear them before computing `had_*` below
-    // so a stale byte can never masquerade as BuzzExplicit and suppress
-    // definition/global injection. Env var overrides (set via the advanced
-    // env-vars editor) are untouched — those remain a legitimate
-    // per-instance override regardless of link status.
+    // Linked instances are definition-authoritative: clear stale materialized
+    // model/provider/prompt so they can never masquerade as BuzzExplicit and
+    // shadow definition values. Env var overrides are untouched.
     if record.persona_id.is_some() {
         record.system_prompt = None;
         record.model = None;
         record.provider = None;
     }
 
-    let had_prompt =
-        record.system_prompt.is_some() || record.env_vars.contains_key("BUZZ_ACP_SYSTEM_PROMPT");
-    let had_model = record.model.is_some();
-
-    let provider_env_key = runtime_meta.and_then(|m| m.provider_env_var).unwrap_or("");
-    let had_provider = record.env_vars.contains_key(provider_env_key);
-
-    let (persona_prompt, persona_model, persona_provider) = resolve_effective_prompt_model_provider(
+    let tiers = build_inherited_tiers(
         record.persona_id.as_deref(),
+        record.runtime.as_deref(),
         personas,
-        record.system_prompt.clone(),
-        record.model.clone(),
-        record.provider.clone(),
+        global,
     );
 
-    // Build the baseline the reader overrides a live model against, paired with
-    // its true origin so the secondary is tagged correctly. Two sources:
-    //   - persona-linked, no explicit record model: the persona model is the
-    //     baseline (PersonaDefault).
-    //   - genuine-explicit (record had its own model) that live-switched: the
-    //     record's own model is the baseline (BuzzExplicit). Gated behind
-    //     `model_overridden` so a persona edited mid-life (override flag false)
-    //     never synthesizes a baseline and false-positives an override.
-    // An explicit pick with no live switch has no baseline to override.
-    let model_overridden = session_cache.is_some_and(|c| c.model_overridden);
-    let baseline = if had_model {
-        if model_overridden {
-            record
-                .model
-                .clone()
-                .map(|m| (m, ConfigOrigin::BuzzExplicit))
-        } else {
-            None
-        }
-    } else {
-        // Prefer persona as baseline, fall back to global when persona has none
-        // and the model was overridden mid-session (global-default agent).
-        persona_model
-            .clone()
-            .map(|m| (m, ConfigOrigin::PersonaDefault))
-            .or_else(|| {
-                if model_overridden {
-                    global
-                        .model
-                        .clone()
-                        .map(|m| (m, ConfigOrigin::GlobalDefault))
-                } else {
-                    None
-                }
-            })
-    };
-
-    // Inject resolved persona values into the record where absent.
-    if !had_prompt {
-        if let Some(p) = persona_prompt {
-            record
-                .env_vars
-                .insert("BUZZ_ACP_SYSTEM_PROMPT".to_string(), p);
-        }
-    }
-    if !had_model {
-        record.model = persona_model.clone();
-    }
-    if !had_provider && !provider_env_key.is_empty() {
-        if let Some(prov) = persona_provider {
-            record.env_vars.insert(provider_env_key.to_string(), prov);
-        }
-    }
-
-    // Inject global defaults where neither the record nor the persona had a value.
-    // Track injection so we can re-tag to GlobalDefault after the reader.
-    let inject_global_model = !had_model && record.model.is_none();
-    let inject_global_provider = !had_provider
-        && !provider_env_key.is_empty()
-        && !record.env_vars.contains_key(provider_env_key);
-
-    if inject_global_model {
-        record.model = global.model.clone();
-    }
-    if inject_global_provider {
-        if let Some(ref gprov) = global.provider {
-            record
-                .env_vars
-                .insert(provider_env_key.to_string(), gprov.clone());
-        }
-    }
-
-    let mut surface = read_config_surface(
-        &record,
-        runtime_meta,
-        session_cache,
-        baseline.as_ref().map(|(m, o)| (m.as_str(), o.clone())),
-    );
-
-    // Re-tag persona-sourced fields from BuzzExplicit to PersonaDefault.
-    if !had_prompt {
-        retag_persona_default(&mut surface.normalized.system_prompt);
-    }
-    if !had_model && !inject_global_model {
-        retag_persona_default(&mut surface.normalized.model);
-    }
-    if !had_provider && !provider_env_key.is_empty() && !inject_global_provider {
-        retag_persona_default(&mut surface.normalized.provider);
-    }
-
-    // Re-tag global-sourced fields from BuzzExplicit to GlobalDefault.
-    if inject_global_model {
-        retag_global_default(&mut surface.normalized.model);
-    }
-    if inject_global_provider {
-        retag_global_default(&mut surface.normalized.provider);
-    }
-
-    surface
-}
-
-/// Re-tag a field's origin from `BuzzExplicit` to `PersonaDefault`, leaving any
-/// other origin untouched. No-op when the field is absent.
-fn retag_persona_default(field: &mut Option<NormalizedField>) {
-    if let Some(field) = field {
-        if field.origin == ConfigOrigin::BuzzExplicit {
-            field.origin = ConfigOrigin::PersonaDefault;
-        }
-    }
+    read_config_surface(&record, runtime_meta, session_cache, &tiers)
 }
 
 /// Get the file-layer config for a runtime — used by the Create/Edit/Persona
@@ -327,16 +262,6 @@ pub fn get_baked_build_env() -> Vec<BakedEnvEntry> {
         .collect()
 }
 
-/// Re-tag a field's origin from `BuzzExplicit` to `GlobalDefault`, leaving any
-/// other origin untouched. No-op when the field is absent.
-fn retag_global_default(field: &mut Option<NormalizedField>) {
-    if let Some(field) = field {
-        if field.origin == ConfigOrigin::BuzzExplicit {
-            field.origin = ConfigOrigin::GlobalDefault;
-        }
-    }
-}
-
 /// Get the full config surface for a managed agent.
 ///
 /// Returns normalized + advanced config from all available tiers.
@@ -601,511 +526,5 @@ fn parse_models(raw: Option<&serde_json::Value>) -> (Vec<AcpModelEntry>, Option<
 }
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::managed_agents::{BackendKind, RespondTo};
-
-    fn goose_runtime() -> &'static KnownAcpRuntime {
-        &KnownAcpRuntime {
-            id: "goose",
-            label: "Goose",
-            commands: &["goose"],
-            aliases: &[],
-            avatar_url: "",
-            mcp_command: None,
-            mcp_hooks: false,
-            underlying_cli: None,
-            cli_install_commands: &[],
-            cli_install_commands_windows: &[],
-            adapter_install_commands: &[],
-            cli_install_instructions_url: "",
-            adapter_install_instructions_url: "",
-            cli_install_hint: "",
-            adapter_install_hint: "",
-            skill_dir: None,
-            supports_acp_model_switching: false,
-            model_env_var: Some("GOOSE_MODEL"),
-            provider_env_var: Some("GOOSE_PROVIDER"),
-            provider_locked: false,
-            default_env: &[],
-            config_file_path: Some("~/.config/goose/config.yaml"),
-            config_file_format: Some("yaml"),
-            supports_acp_native_config: true,
-            thinking_env_var: Some("GOOSE_THINKING_EFFORT"),
-            max_tokens_env_var: Some("GOOSE_MAX_TOKENS"),
-            context_limit_env_var: Some("GOOSE_CONTEXT_LIMIT"),
-            required_normalized_fields: &["model", "provider"],
-            login_hint: None,
-            auth_probe_args: None,
-        }
-    }
-
-    fn agent_record() -> ManagedAgentRecord {
-        ManagedAgentRecord {
-            pubkey: "agent".to_string(),
-            name: "Agent".to_string(),
-            persona_id: Some("persona-1".to_string()),
-            private_key_nsec: "".to_string(),
-            auth_tag: None,
-            relay_url: "ws://localhost:3000".to_string(),
-            avatar_url: None,
-            acp_command: "buzz-acp".to_string(),
-            agent_command: "goose".to_string(),
-            agent_args: vec![],
-            mcp_command: "".to_string(),
-            turn_timeout_seconds: 300,
-            idle_timeout_seconds: None,
-            max_turn_duration_seconds: None,
-            parallelism: 1,
-            system_prompt: None,
-            model: None,
-            env_vars: Default::default(),
-            start_on_app_launch: false,
-            auto_restart_on_config_change: true,
-            runtime_pid: None,
-            backend: BackendKind::Local,
-            backend_agent_id: None,
-            provider_binary_path: None,
-            team_id: None,
-            persona_team_dir: None,
-            persona_name_in_team: None,
-            created_at: "".to_string(),
-            updated_at: "".to_string(),
-            last_started_at: None,
-            last_stopped_at: None,
-            last_exit_code: None,
-            last_error: None,
-            last_error_code: None,
-            respond_to: RespondTo::OwnerOnly,
-            respond_to_allowlist: vec![],
-            display_name: None,
-            slug: None,
-            runtime: None,
-            name_pool: Vec::new(),
-            is_builtin: false,
-            is_active: true,
-            shared: false,
-            source_team: None,
-            source_team_persona_slug: None,
-            catalog_source: None,
-            definition_respond_to: None,
-            definition_respond_to_allowlist: Vec::new(),
-            definition_parallelism: None,
-            relay_mesh: None,
-            agent_command_override: None,
-            persona_source_version: None,
-            provider: None,
-        }
-    }
-
-    fn persona_with_model(model: &str) -> AgentDefinition {
-        AgentDefinition {
-            id: "persona-1".to_string(),
-            display_name: "Persona".to_string(),
-            avatar_url: None,
-            system_prompt: "You are a persona.".to_string(),
-            runtime: None,
-            model: Some(model.to_string()),
-            provider: None,
-            name_pool: Vec::new(),
-            is_builtin: false,
-            is_active: true,
-            shared: false,
-            source_team: None,
-            source_team_persona_slug: None,
-            catalog_source: None,
-            env_vars: Default::default(),
-            respond_to: None,
-            respond_to_allowlist: Vec::new(),
-            parallelism: None,
-            created_at: "".to_string(),
-            updated_at: "".to_string(),
-        }
-    }
-
-    /// A post-spawn session cache whose live model is `current_model` and whose
-    /// `model_overridden` flag records whether a `SwitchModel` control signal set
-    /// it (the live-switch signal).
-    fn session_cache(current_model: &str, model_overridden: bool) -> SessionConfigCache {
-        SessionConfigCache {
-            config_options: vec![],
-            available_modes: vec![],
-            available_models: vec![],
-            current_model: Some(current_model.to_string()),
-            model_overridden,
-            goose_native_config: None,
-            captured_at: "".to_string(),
-        }
-    }
-
-    /// Definition-authoritative: a stale materialized `record.model` on a
-    /// linked instance must never outrank (or even be consulted against) the
-    /// linked persona's model. `update_managed_agent` already blocks writing
-    /// model/provider/prompt for linked instances, so a non-`None` value here
-    /// can only be leftover snapshot bytes from before a persona edit — the
-    /// panel must report the persona's current model, tagged `PersonaDefault`,
-    /// not the stale byte as `BuzzExplicit`.
-    #[test]
-    fn linked_stale_record_model_never_outranks_persona_model() {
-        let mut record = agent_record();
-        record.model = Some("stale-explicit-model".to_string());
-        let personas = vec![persona_with_model("persona-model")];
-
-        let surface = resolve_config_surface(
-            record,
-            &personas,
-            Some(goose_runtime()),
-            None,
-            &Default::default(),
-        );
-
-        let model = surface.normalized.model.as_ref().expect("model resolved");
-        assert_eq!(model.value.as_deref(), Some("persona-model"));
-        assert_eq!(model.origin, ConfigOrigin::PersonaDefault);
-    }
-
-    /// Definition-authoritative, blank-definition case: a linked instance
-    /// whose persona has no model of its own must fall through to the global
-    /// default, tagged `GlobalDefault` — mirroring
-    /// `effective_config::resolve_linked`'s `None => global` arm. A stale
-    /// materialized record model must not shadow this fallthrough either.
-    #[test]
-    fn linked_blank_definition_model_falls_through_to_global_default() {
-        let mut record = agent_record();
-        record.model = Some("stale-explicit-model".to_string());
-        let mut persona = persona_with_model("unused");
-        persona.model = None;
-        let personas = vec![persona];
-        let global = crate::managed_agents::GlobalAgentConfig {
-            model: Some("global-model".to_string()),
-            ..Default::default()
-        };
-
-        let surface =
-            resolve_config_surface(record, &personas, Some(goose_runtime()), None, &global);
-
-        let model = surface.normalized.model.as_ref().expect("model resolved");
-        assert_eq!(model.value.as_deref(), Some("global-model"));
-        assert_eq!(model.origin, ConfigOrigin::GlobalDefault);
-    }
-
-    /// A definition-less (no `persona_id`) instance's own explicit model IS
-    /// authoritative — the stale-record clearing above is scoped to linked
-    /// instances only.
-    #[test]
-    fn definition_less_explicit_record_model_keeps_buzz_explicit_origin() {
-        let mut record = agent_record();
-        record.persona_id = None;
-        record.model = Some("explicit-model".to_string());
-        let personas = vec![persona_with_model("persona-model")];
-
-        let surface = resolve_config_surface(
-            record,
-            &personas,
-            Some(goose_runtime()),
-            None,
-            &Default::default(),
-        );
-
-        let model = surface.normalized.model.as_ref().expect("model resolved");
-        assert_eq!(model.value.as_deref(), Some("explicit-model"));
-        assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
-    }
-
-    /// Part A — pending-pick: a genuine-explicit pick X with a divergent live
-    /// model Y but `model_overridden == false` (the live switch is not yet
-    /// applied — a restart is pending) must keep X as the primary and must NOT
-    /// surface Y as an override row. The live `acp_model` does not win. This
-    /// FAILS against a let-live-acp-win variant (one that dropped the
-    /// `model_overridden` gate), so it is not vacuous.
-    #[test]
-    fn pending_pick_keeps_explicit_x_and_does_not_surface_live_y() {
-        let mut record = agent_record();
-        record.persona_id = None;
-        record.model = Some("model-x".to_string());
-        let personas: Vec<AgentDefinition> = vec![];
-        let cache = session_cache("model-y", false);
-
-        let surface = resolve_config_surface(
-            record,
-            &personas,
-            Some(goose_runtime()),
-            Some(&cache),
-            &Default::default(),
-        );
-        let model = surface.normalized.model.expect("model resolved");
-
-        assert_eq!(model.value.as_deref(), Some("model-x"));
-        assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
-        assert_ne!(model.origin, ConfigOrigin::RuntimeOverride);
-        assert_ne!(model.overridden_value.as_deref(), Some("model-y"));
-    }
-
-    /// W2 — genuine-explicit live switch: record.model = X, no persona,
-    /// `model_overridden == true`, live model = Y. The live Y must render as the
-    /// primary with a `RuntimeOverride` origin and X as the secondary tagged
-    /// `BuzzExplicit` (its true source — NOT `PersonaDefault`). FAILS against the
-    /// shipped no-persona early-return, which left X as primary and Y struck.
-    #[test]
-    fn genuine_explicit_live_switch_renders_y_over_x_buzz_explicit_secondary() {
-        let mut record = agent_record();
-        record.persona_id = None;
-        record.model = Some("model-x".to_string());
-        let personas: Vec<AgentDefinition> = vec![];
-        let cache = session_cache("model-y", true);
-
-        let surface = resolve_config_surface(
-            record,
-            &personas,
-            Some(goose_runtime()),
-            Some(&cache),
-            &Default::default(),
-        );
-        let model = surface.normalized.model.expect("model resolved");
-
-        assert_eq!(model.value.as_deref(), Some("model-y"));
-        assert_eq!(model.origin, ConfigOrigin::RuntimeOverride);
-        assert_eq!(model.overridden_value.as_deref(), Some("model-x"));
-        assert_eq!(model.overridden_origin, Some(ConfigOrigin::BuzzExplicit));
-    }
-
-    /// Y==X collision: a genuine-explicit agent live-switches to the SAME value
-    /// it already had. There is no real divergence, so the field must be a clean
-    /// single value with NO secondary row. FAILS against a naive `return base`
-    /// that would leak the `AcpConfigOption` row `build_model_field` populates.
-    #[test]
-    fn genuine_explicit_live_switch_to_same_model_yields_clean_field() {
-        let mut record = agent_record();
-        record.persona_id = None;
-        record.model = Some("model-x".to_string());
-        let personas: Vec<AgentDefinition> = vec![];
-        let cache = session_cache("model-x", true);
-
-        let surface = resolve_config_surface(
-            record,
-            &personas,
-            Some(goose_runtime()),
-            Some(&cache),
-            &Default::default(),
-        );
-        let model = surface.normalized.model.expect("model resolved");
-
-        assert_eq!(model.value.as_deref(), Some("model-x"));
-        assert_eq!(model.overridden_value, None);
-        assert_eq!(model.overridden_origin, None);
-    }
-
-    /// Persona parity (regression): a persona-linked agent with no explicit
-    /// record model that live-switches still renders the persona model as the
-    /// secondary tagged `PersonaDefault` — the typed-baseline change must NOT
-    /// regress the persona arm to a different origin.
-    #[test]
-    fn persona_linked_live_switch_keeps_persona_default_secondary() {
-        let record = agent_record();
-        let personas = vec![persona_with_model("persona-model")];
-        let cache = session_cache("model-y", true);
-
-        let surface = resolve_config_surface(
-            record,
-            &personas,
-            Some(goose_runtime()),
-            Some(&cache),
-            &Default::default(),
-        );
-        let model = surface.normalized.model.expect("model resolved");
-
-        assert_eq!(model.value.as_deref(), Some("model-y"));
-        assert_eq!(model.origin, ConfigOrigin::RuntimeOverride);
-        assert_eq!(model.overridden_value.as_deref(), Some("persona-model"));
-        assert_eq!(model.overridden_origin, Some(ConfigOrigin::PersonaDefault));
-    }
-
-    /// Fix 2 regression: a global-default-only agent (no record model, no
-    /// persona model, but global has a model) that live-switches mid-session
-    /// must render the global model as the secondary tagged `GlobalDefault`.
-    /// Before the fix, `baseline` was `None` in the `!had_model` arm when
-    /// persona has no model, so `read_config_surface` had no secondary to
-    /// surface. Fails against pre-fix code where the baseline arm returned
-    /// `None` when `!had_model && persona_model.is_none() && model_overridden`.
-    #[test]
-    fn global_default_live_switch_renders_global_model_as_secondary_global_default() {
-        // Record has no model, no persona, global provides the model.
-        let mut record = agent_record();
-        record.persona_id = None;
-        // record.model = None (set by agent_record())
-        let personas: Vec<AgentDefinition> = vec![];
-        let cache = session_cache("model-y", true);
-        let global = crate::managed_agents::GlobalAgentConfig {
-            model: Some("global-model".to_string()),
-            ..Default::default()
-        };
-
-        let surface = resolve_config_surface(
-            record,
-            &personas,
-            Some(goose_runtime()),
-            Some(&cache),
-            &global,
-        );
-        let model = surface.normalized.model.expect("model resolved");
-
-        // Live model wins as primary.
-        assert_eq!(model.value.as_deref(), Some("model-y"));
-        assert_eq!(model.origin, ConfigOrigin::RuntimeOverride);
-        // Global model surfaces as secondary, tagged GlobalDefault.
-        assert_eq!(
-            model.overridden_value.as_deref(),
-            Some("global-model"),
-            "global model must be the override baseline secondary"
-        );
-        assert_eq!(
-            model.overridden_origin,
-            Some(ConfigOrigin::GlobalDefault),
-            "override baseline origin must be GlobalDefault, not PersonaDefault or BuzzExplicit"
-        );
-    }
-
-    // ── get_baked_build_env / is_secret_key tests ──────────────────────────
-
-    /// Build a `BakedEnvEntry` vec from a synthetic map, mirroring what
-    /// `get_baked_build_env()` does. Used to test masking without relying on
-    /// compile-time `option_env!` vars (OSS builds have empty `baked_build_env`).
-    fn baked_env_from_map(map: &[(&str, &str)]) -> Vec<BakedEnvEntry> {
-        map.iter()
-            .filter(|(_, v)| !v.is_empty())
-            .map(|(k, v)| {
-                let masked = !super::is_safe_to_reveal(k);
-                BakedEnvEntry {
-                    key: k.to_string(),
-                    value: if masked {
-                        "\u{2022}\u{2022}\u{2022}\u{2022}\u{2022}\u{2022}".to_string()
-                    } else {
-                        v.to_string()
-                    },
-                    masked,
-                }
-            })
-            .collect()
-    }
-
-    #[test]
-    fn baked_env_non_secret_key_shows_real_value() {
-        let entries = baked_env_from_map(&[("BUZZ_AGENT_PROVIDER", "databricks_v2")]);
-        assert_eq!(entries.len(), 1);
-        assert_eq!(entries[0].key, "BUZZ_AGENT_PROVIDER");
-        assert_eq!(entries[0].value, "databricks_v2");
-        assert!(!entries[0].masked);
-    }
-
-    #[test]
-    fn baked_env_api_key_is_masked() {
-        let entries = baked_env_from_map(&[("ANTHROPIC_API_KEY", "sk-secret")]);
-        assert_eq!(entries.len(), 1);
-        assert_eq!(entries[0].value, "••••••");
-        assert!(entries[0].masked);
-    }
-
-    #[test]
-    fn baked_env_token_key_is_masked() {
-        let entries = baked_env_from_map(&[("GITHUB_TOKEN", "ghp_secret")]);
-        assert_eq!(entries.len(), 1);
-        assert!(entries[0].masked);
-    }
-
-    #[test]
-    fn baked_env_secret_key_is_masked() {
-        let entries = baked_env_from_map(&[("MY_DB_SECRET", "s3cr3t")]);
-        assert_eq!(entries.len(), 1);
-        assert!(entries[0].masked);
-    }
-
-    #[test]
-    fn baked_env_password_key_is_masked() {
-        let entries = baked_env_from_map(&[("DB_PASSWORD", "hunter2")]);
-        assert_eq!(entries.len(), 1);
-        assert!(entries[0].masked);
-    }
-
-    #[test]
-    fn baked_env_empty_value_filtered_out() {
-        let entries = baked_env_from_map(&[("BUZZ_AGENT_PROVIDER", "")]);
-        assert!(entries.is_empty());
-    }
-
-    #[test]
-    fn baked_env_mixed_keys_correct_masking() {
-        let entries = baked_env_from_map(&[
-            ("BUZZ_AGENT_PROVIDER", "databricks_v2"),
-            ("BUZZ_AGENT_MODEL", "goose-claude-opus-4-8"),
-            ("DATABRICKS_HOST", "https://example.com"),
-            ("DATABRICKS_TOKEN", "dapi-secret"),
-        ]);
-        assert_eq!(entries.len(), 4);
-
-        let provider = entries
-            .iter()
-            .find(|e| e.key == "BUZZ_AGENT_PROVIDER")
-            .unwrap();
-        assert_eq!(provider.value, "databricks_v2");
-        assert!(!provider.masked);
-
-        let model = entries
-            .iter()
-            .find(|e| e.key == "BUZZ_AGENT_MODEL")
-            .unwrap();
-        assert_eq!(model.value, "goose-claude-opus-4-8");
-        assert!(!model.masked);
-
-        let host = entries.iter().find(|e| e.key == "DATABRICKS_HOST").unwrap();
-        assert_eq!(host.value, "https://example.com");
-        assert!(!host.masked);
-
-        let token = entries
-            .iter()
-            .find(|e| e.key == "DATABRICKS_TOKEN")
-            .unwrap();
-        assert_eq!(token.value, "••••••");
-        assert!(token.masked);
-    }
-
-    #[test]
-    fn baked_env_thinking_effort_is_unmasked() {
-        // BUZZ_AGENT_THINKING_EFFORT is a non-secret enum — must not be masked.
-        let entries = baked_env_from_map(&[("BUZZ_AGENT_THINKING_EFFORT", "medium")]);
-        assert_eq!(entries.len(), 1);
-        let effort = entries
-            .iter()
-            .find(|e| e.key == "BUZZ_AGENT_THINKING_EFFORT")
-            .unwrap();
-        assert_eq!(effort.value, "medium");
-        assert!(!effort.masked);
-    }
-
-    #[test]
-    fn baked_env_allowlist_is_case_insensitive() {
-        // Known-safe keys — case-insensitive match must allow them.
-        assert!(super::is_safe_to_reveal("buzz_agent_provider"));
-        assert!(super::is_safe_to_reveal("BUZZ_AGENT_PROVIDER"));
-        assert!(super::is_safe_to_reveal("buzz_agent_model"));
-        assert!(super::is_safe_to_reveal("BUZZ_AGENT_MODEL"));
-        assert!(super::is_safe_to_reveal("buzz_agent_thinking_effort"));
-        assert!(super::is_safe_to_reveal("BUZZ_AGENT_THINKING_EFFORT"));
-        assert!(super::is_safe_to_reveal("databricks_host"));
-        assert!(super::is_safe_to_reveal("DATABRICKS_HOST"));
-        assert!(super::is_safe_to_reveal("databricks_model"));
-        assert!(super::is_safe_to_reveal("DATABRICKS_MODEL"));
-        // Keys NOT in the allowlist — masked regardless of naming pattern.
-        assert!(!super::is_safe_to_reveal("my_api_key"));
-        assert!(!super::is_safe_to_reveal("GITHUB_TOKEN"));
-        assert!(!super::is_safe_to_reveal("DB_SECRET"));
-        assert!(!super::is_safe_to_reveal("DB_PASSWORD"));
-        // Bare names that old heuristic (contains("_TOKEN") etc.) would have missed.
-        assert!(!super::is_safe_to_reveal("APIKEY"));
-        assert!(!super::is_safe_to_reveal("TOKEN"));
-        assert!(!super::is_safe_to_reveal("SECRET"));
-        assert!(!super::is_safe_to_reveal("PASSWORD"));
-        assert!(!super::is_safe_to_reveal("PRIVATE_KEY"));
-        // Unknown key → masked by default.
-        assert!(!super::is_safe_to_reveal("SOME_UNKNOWN_KEY"));
-    }
-}
+#[path = "agent_config_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/commands/agent_config_tests.rs b/desktop/src-tauri/src/commands/agent_config_tests.rs
new file mode 100644
index 0000000000..f3667cff45
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_config_tests.rs
@@ -0,0 +1,651 @@
+//! Unit tests for `commands/agent_config.rs` (split to keep `agent_config.rs`
+//! under the 1000-line file-size ratchet).
+//!
+//! Included via `#[path = "agent_config_tests.rs"] mod tests;` at the bottom of
+//! `agent_config.rs`, so `use super::*` gives access to all items in that module.
+
+use super::*;
+use crate::managed_agents::config_bridge::types::ConfigOrigin;
+use crate::managed_agents::{BackendKind, RespondTo};
+
+use std::sync::Mutex;
+
+static GOOSE_PATH_ROOT_LOCK: Mutex<()> = Mutex::new(());
+
+/// Run a test body with GOOSE_PATH_ROOT set to a non-existent path so that the
+/// goose config file read returns `None`. Restores the prior value on exit.
+fn with_no_goose_config<T>(body: impl FnOnce() -> T) -> T {
+    let _guard = GOOSE_PATH_ROOT_LOCK
+        .lock()
+        .unwrap_or_else(|err| err.into_inner());
+    let prior = std::env::var_os("GOOSE_PATH_ROOT");
+    std::env::set_var("GOOSE_PATH_ROOT", "/nonexistent-buzz-test-path");
+    let output = body();
+    match prior {
+        Some(value) => std::env::set_var("GOOSE_PATH_ROOT", value),
+        None => std::env::remove_var("GOOSE_PATH_ROOT"),
+    }
+    output
+}
+
+fn goose_runtime() -> &'static KnownAcpRuntime {
+    &KnownAcpRuntime {
+        id: "goose",
+        label: "Goose",
+        commands: &["goose"],
+        aliases: &[],
+        avatar_url: "",
+        mcp_command: None,
+        mcp_hooks: false,
+        underlying_cli: None,
+        cli_install_commands: &[],
+        cli_install_commands_windows: &[],
+        adapter_install_commands: &[],
+        cli_install_instructions_url: "",
+        adapter_install_instructions_url: "",
+        cli_install_hint: "",
+        adapter_install_hint: "",
+        skill_dir: None,
+        supports_acp_model_switching: false,
+        model_env_var: Some("GOOSE_MODEL"),
+        provider_env_var: Some("GOOSE_PROVIDER"),
+        provider_locked: false,
+        default_env: &[],
+        config_file_path: Some("~/.config/goose/config.yaml"),
+        config_file_format: Some("yaml"),
+        supports_acp_native_config: true,
+        thinking_env_var: Some("GOOSE_THINKING_EFFORT"),
+        max_tokens_env_var: Some("GOOSE_MAX_TOKENS"),
+        context_limit_env_var: Some("GOOSE_CONTEXT_LIMIT"),
+        required_normalized_fields: &["model", "provider"],
+        login_hint: None,
+        auth_probe_args: None,
+    }
+}
+
+fn agent_record() -> ManagedAgentRecord {
+    ManagedAgentRecord {
+        pubkey: "agent".to_string(),
+        name: "Agent".to_string(),
+        persona_id: Some("persona-1".to_string()),
+        private_key_nsec: "".to_string(),
+        auth_tag: None,
+        relay_url: "ws://localhost:3000".to_string(),
+        avatar_url: None,
+        acp_command: "buzz-acp".to_string(),
+        agent_command: "goose".to_string(),
+        agent_args: vec![],
+        mcp_command: "".to_string(),
+        turn_timeout_seconds: 300,
+        idle_timeout_seconds: None,
+        max_turn_duration_seconds: None,
+        parallelism: 1,
+        system_prompt: None,
+        model: None,
+        env_vars: Default::default(),
+        start_on_app_launch: false,
+        auto_restart_on_config_change: true,
+        runtime_pid: None,
+        backend: BackendKind::Local,
+        backend_agent_id: None,
+        provider_binary_path: None,
+        team_id: None,
+        persona_team_dir: None,
+        persona_name_in_team: None,
+        created_at: "".to_string(),
+        updated_at: "".to_string(),
+        last_started_at: None,
+        last_stopped_at: None,
+        last_exit_code: None,
+        last_error: None,
+        last_error_code: None,
+        respond_to: RespondTo::OwnerOnly,
+        respond_to_allowlist: vec![],
+        display_name: None,
+        slug: None,
+        runtime: None,
+        name_pool: Vec::new(),
+        is_builtin: false,
+        is_active: true,
+        shared: false,
+        source_team: None,
+        source_team_persona_slug: None,
+        catalog_source: None,
+        definition_respond_to: None,
+        definition_respond_to_allowlist: Vec::new(),
+        definition_parallelism: None,
+        relay_mesh: None,
+        agent_command_override: None,
+        persona_source_version: None,
+        provider: None,
+    }
+}
+
+fn persona_with_model(model: &str) -> AgentDefinition {
+    AgentDefinition {
+        id: "persona-1".to_string(),
+        display_name: "Persona".to_string(),
+        avatar_url: None,
+        system_prompt: "You are a persona.".to_string(),
+        runtime: None,
+        model: Some(model.to_string()),
+        provider: None,
+        name_pool: Vec::new(),
+        is_builtin: false,
+        is_active: true,
+        shared: false,
+        source_team: None,
+        source_team_persona_slug: None,
+        catalog_source: None,
+        env_vars: Default::default(),
+        respond_to: None,
+        respond_to_allowlist: Vec::new(),
+        parallelism: None,
+        created_at: "".to_string(),
+        updated_at: "".to_string(),
+    }
+}
+
+/// A post-spawn session cache whose live model is `current_model` and whose
+/// `model_overridden` flag records whether a `SwitchModel` control signal set
+/// it (the live-switch signal).
+fn session_cache(current_model: &str, model_overridden: bool) -> SessionConfigCache {
+    SessionConfigCache {
+        config_options: vec![],
+        available_modes: vec![],
+        available_models: vec![],
+        current_model: Some(current_model.to_string()),
+        model_overridden,
+        goose_native_config: None,
+        captured_at: "".to_string(),
+    }
+}
+
+/// Definition-authoritative: a stale materialized `record.model` on a
+/// linked instance must never outrank (or even be consulted against) the
+/// linked persona's model. `update_managed_agent` already blocks writing
+/// model/provider/prompt for linked instances, so a non-`None` value here
+/// can only be leftover snapshot bytes from before a persona edit — the
+/// panel must report the persona's current model, tagged `PersonaDefault`,
+/// not the stale byte as `BuzzExplicit`.
+#[test]
+fn linked_stale_record_model_never_outranks_persona_model() {
+    let mut record = agent_record();
+    record.model = Some("stale-explicit-model".to_string());
+    let personas = vec![persona_with_model("persona-model")];
+
+    let surface = resolve_config_surface(
+        record,
+        &personas,
+        Some(goose_runtime()),
+        None,
+        &Default::default(),
+    );
+
+    let model = surface.normalized.model.as_ref().expect("model resolved");
+    assert_eq!(model.value.as_deref(), Some("persona-model"));
+    assert_eq!(model.origin, ConfigOrigin::PersonaDefault);
+}
+
+/// Definition-authoritative, blank-definition case: a linked instance
+/// whose persona has no model of its own must fall through to the global
+/// default, tagged `GlobalDefault` — mirroring
+/// `effective_config::resolve_linked`'s `None => global` arm. A stale
+/// materialized record model must not shadow this fallthrough either.
+#[test]
+fn linked_blank_definition_model_falls_through_to_global_default() {
+    let mut record = agent_record();
+    record.model = Some("stale-explicit-model".to_string());
+    let mut persona = persona_with_model("unused");
+    persona.model = None;
+    let personas = vec![persona];
+    let global = crate::managed_agents::GlobalAgentConfig {
+        model: Some("global-model".to_string()),
+        ..Default::default()
+    };
+
+    let surface = resolve_config_surface(record, &personas, Some(goose_runtime()), None, &global);
+
+    let model = surface.normalized.model.as_ref().expect("model resolved");
+    assert_eq!(model.value.as_deref(), Some("global-model"));
+    assert_eq!(model.origin, ConfigOrigin::GlobalDefault);
+}
+
+/// A definition-less (no `persona_id`) instance's own explicit model IS
+/// authoritative — the stale-record clearing above is scoped to linked
+/// instances only.
+#[test]
+fn definition_less_explicit_record_model_keeps_buzz_explicit_origin() {
+    let mut record = agent_record();
+    record.persona_id = None;
+    record.model = Some("explicit-model".to_string());
+    let personas = vec![persona_with_model("persona-model")];
+
+    let surface = resolve_config_surface(
+        record,
+        &personas,
+        Some(goose_runtime()),
+        None,
+        &Default::default(),
+    );
+
+    let model = surface.normalized.model.as_ref().expect("model resolved");
+    assert_eq!(model.value.as_deref(), Some("explicit-model"));
+    assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
+}
+
+/// Part A — pending-pick: a genuine-explicit pick X with a divergent live
+/// model Y but `model_overridden == false` (the live switch is not yet
+/// applied — a restart is pending) must keep X as the primary and must NOT
+/// surface Y as an override row. The live `acp_model` does not win. This
+/// FAILS against a let-live-acp-win variant (one that dropped the
+/// `model_overridden` gate), so it is not vacuous.
+#[test]
+fn pending_pick_keeps_explicit_x_and_does_not_surface_live_y() {
+    let mut record = agent_record();
+    record.persona_id = None;
+    record.model = Some("model-x".to_string());
+    let personas: Vec<AgentDefinition> = vec![];
+    let cache = session_cache("model-y", false);
+
+    let surface = resolve_config_surface(
+        record,
+        &personas,
+        Some(goose_runtime()),
+        Some(&cache),
+        &Default::default(),
+    );
+    let model = surface.normalized.model.expect("model resolved");
+
+    assert_eq!(model.value.as_deref(), Some("model-x"));
+    assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
+    assert_ne!(model.origin, ConfigOrigin::RuntimeOverride);
+    assert_ne!(model.overridden_value.as_deref(), Some("model-y"));
+}
+
+/// W2 — genuine-explicit live switch: record.model = X, no persona,
+/// `model_overridden == true`, live model = Y. The live Y must render as the
+/// primary with a `RuntimeOverride` origin and X as the secondary tagged
+/// `BuzzExplicit` (its true source — NOT `PersonaDefault`). FAILS against the
+/// shipped no-persona early-return, which left X as primary and Y struck.
+#[test]
+fn genuine_explicit_live_switch_renders_y_over_x_buzz_explicit_secondary() {
+    let mut record = agent_record();
+    record.persona_id = None;
+    record.model = Some("model-x".to_string());
+    let personas: Vec<AgentDefinition> = vec![];
+    let cache = session_cache("model-y", true);
+
+    let surface = resolve_config_surface(
+        record,
+        &personas,
+        Some(goose_runtime()),
+        Some(&cache),
+        &Default::default(),
+    );
+    let model = surface.normalized.model.expect("model resolved");
+
+    assert_eq!(model.value.as_deref(), Some("model-y"));
+    assert_eq!(model.origin, ConfigOrigin::RuntimeOverride);
+    assert_eq!(model.overridden_value.as_deref(), Some("model-x"));
+    assert_eq!(model.overridden_origin, Some(ConfigOrigin::BuzzExplicit));
+}
+
+/// Y==X collision: a genuine-explicit agent live-switches to the SAME value
+/// it already had. There is no real divergence, so the field must be a clean
+/// single value with NO secondary row and origin matching the baseline (not
+/// RuntimeOverride). FAILS against a naive `return base` that would leak the
+/// `AcpConfigOption` row `build_model_field` populates, and against the
+/// prior implementation that stamped `RuntimeOverride` on the equal-value arm.
+///
+/// `with_no_goose_config` suppresses the goose config file read so that the
+/// fall-through to normal resolution cannot pick up a local `~/.config/goose/config.yaml`
+/// model as a spurious secondary — the test is about tier precedence, not the
+/// local developer's goose install.
+#[test]
+fn genuine_explicit_live_switch_to_same_model_yields_clean_field() {
+    let mut record = agent_record();
+    record.persona_id = None;
+    record.model = Some("model-x".to_string());
+    let personas: Vec<AgentDefinition> = vec![];
+    let cache = session_cache("model-x", true);
+
+    let surface = with_no_goose_config(|| {
+        resolve_config_surface(
+            record,
+            &personas,
+            Some(goose_runtime()),
+            Some(&cache),
+            &Default::default(),
+        )
+    });
+    let model = surface.normalized.model.expect("model resolved");
+
+    assert_eq!(model.value.as_deref(), Some("model-x"));
+    // Equal-value switch must NOT stamp RuntimeOverride — baseline origin wins.
+    assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
+    assert_ne!(model.origin, ConfigOrigin::RuntimeOverride);
+    assert_eq!(model.overridden_value, None);
+    assert_eq!(model.overridden_origin, None);
+}
+
+/// Persona parity (regression): a persona-linked agent with no explicit
+/// record model that live-switches still renders the persona model as the
+/// secondary tagged `PersonaDefault` — the typed-baseline change must NOT
+/// regress the persona arm to a different origin.
+#[test]
+fn persona_linked_live_switch_keeps_persona_default_secondary() {
+    let record = agent_record();
+    let personas = vec![persona_with_model("persona-model")];
+    let cache = session_cache("model-y", true);
+
+    let surface = resolve_config_surface(
+        record,
+        &personas,
+        Some(goose_runtime()),
+        Some(&cache),
+        &Default::default(),
+    );
+    let model = surface.normalized.model.expect("model resolved");
+
+    assert_eq!(model.value.as_deref(), Some("model-y"));
+    assert_eq!(model.origin, ConfigOrigin::RuntimeOverride);
+    assert_eq!(model.overridden_value.as_deref(), Some("persona-model"));
+    assert_eq!(model.overridden_origin, Some(ConfigOrigin::PersonaDefault));
+}
+
+/// Fix 2 regression: a global-default-only agent (no record model, no
+/// persona model, but global has a model) that live-switches mid-session
+/// must render the global model as the secondary tagged `GlobalDefault`.
+/// Before the fix, `baseline` was `None` in the `!had_model` arm when
+/// persona has no model, so `read_config_surface` had no secondary to
+/// surface. Fails against pre-fix code where the baseline arm returned
+/// `None` when `!had_model && persona_model.is_none() && model_overridden`.
+#[test]
+fn global_default_live_switch_renders_global_model_as_secondary_global_default() {
+    // Record has no model, no persona, global provides the model.
+    let mut record = agent_record();
+    record.persona_id = None;
+    // record.model = None (set by agent_record())
+    let personas: Vec<AgentDefinition> = vec![];
+    let cache = session_cache("model-y", true);
+    let global = crate::managed_agents::GlobalAgentConfig {
+        model: Some("global-model".to_string()),
+        ..Default::default()
+    };
+
+    let surface = resolve_config_surface(
+        record,
+        &personas,
+        Some(goose_runtime()),
+        Some(&cache),
+        &global,
+    );
+    let model = surface.normalized.model.expect("model resolved");
+
+    // Live model wins as primary.
+    assert_eq!(model.value.as_deref(), Some("model-y"));
+    assert_eq!(model.origin, ConfigOrigin::RuntimeOverride);
+    // Global model surfaces as secondary, tagged GlobalDefault.
+    assert_eq!(
+        model.overridden_value.as_deref(),
+        Some("global-model"),
+        "global model must be the override baseline secondary"
+    );
+    assert_eq!(
+        model.overridden_origin,
+        Some(ConfigOrigin::GlobalDefault),
+        "override baseline origin must be GlobalDefault, not PersonaDefault or BuzzExplicit"
+    );
+}
+
+// ── Snapshot constructor tests (build_inherited_tiers) ──────────────────────
+//
+// These test the sanitized snapshot constructor — the command-boundary
+// function that builds InheritedConfigTiers from raw persona/global data.
+
+/// Orphaned persona link: a record whose persona_id references a non-existent
+/// persona should produce empty persona tiers (not a panic), and the panel
+/// still renders from the record and global tiers.
+#[test]
+fn orphaned_persona_link_yields_empty_persona_tiers() {
+    let mut record = agent_record();
+    record.persona_id = Some("missing-persona".to_string());
+    // No personas in the list — dangling link.
+    let personas: Vec<AgentDefinition> = vec![];
+    let global = crate::managed_agents::GlobalAgentConfig {
+        model: Some("global-model".to_string()),
+        ..Default::default()
+    };
+
+    let tiers = build_inherited_tiers(record.persona_id.as_deref(), None, &personas, &global);
+
+    // Persona tier is empty — the orphan yields no persona inheritance.
+    assert!(tiers.persona_env.is_empty());
+    assert!(tiers.persona_model.is_none());
+    assert!(tiers.persona_provider.is_none());
+    assert!(tiers.persona_prompt.is_none());
+    // Global tiers are unaffected.
+    assert_eq!(tiers.global_model.as_deref(), Some("global-model"));
+}
+
+/// Reserved key in persona env is stripped by sanitization — it must never
+/// reach the reader or the display surface.
+#[test]
+fn reserved_key_in_inherited_persona_env_is_stripped() {
+    let mut persona = persona_with_model("model");
+    // BUZZ_PRIVATE_KEY is a reserved key — must be stripped.
+    persona
+        .env_vars
+        .insert("BUZZ_PRIVATE_KEY".to_string(), "nsec-secret".to_string());
+    // A safe key — must survive.
+    persona
+        .env_vars
+        .insert("GOOSE_MODEL".to_string(), "persona-model".to_string());
+    let personas = vec![persona];
+    let global = crate::managed_agents::GlobalAgentConfig::default();
+
+    let tiers = build_inherited_tiers(Some("persona-1"), None, &personas, &global);
+
+    assert!(
+        !tiers.persona_env.contains_key("BUZZ_PRIVATE_KEY"),
+        "reserved key must be stripped from persona env tier"
+    );
+    assert!(
+        tiers.persona_env.contains_key("GOOSE_MODEL"),
+        "safe key must survive sanitization"
+    );
+}
+
+/// `sanitize_inherited_env` strips reserved keys from a definition-env-shaped
+/// map. This pins the shared sanitization contract for definition_env — the
+/// same function is applied to all three env tiers (persona, global, definition)
+/// at the command boundary.
+#[test]
+fn reserved_key_in_definition_env_shaped_map_is_stripped_by_sanitize() {
+    // Exercise sanitize_inherited_env directly with a definition-env-shaped map.
+    let mut raw = std::collections::BTreeMap::new();
+    raw.insert("BUZZ_PRIVATE_KEY".to_string(), "nsec-secret".to_string());
+    raw.insert("GOOSE_MODEL".to_string(), "harness-model".to_string());
+
+    let sanitized = sanitize_inherited_env(&raw);
+
+    assert!(
+        !sanitized.contains_key("BUZZ_PRIVATE_KEY"),
+        "reserved key must be stripped by sanitize_inherited_env"
+    );
+    assert!(
+        sanitized.contains_key("GOOSE_MODEL"),
+        "safe key must survive sanitize_inherited_env"
+    );
+}
+
+/// Malformed key in global env is stripped by sanitization — keys must be
+/// POSIX-shaped (`[A-Za-z_][A-Za-z0-9_]*`).
+#[test]
+fn malformed_key_in_inherited_global_env_is_stripped() {
+    let mut global = crate::managed_agents::GlobalAgentConfig::default();
+    // Key with an `=` — would bypass env-var security if passed to spawn.
+    global
+        .env_vars
+        .insert("BAD=KEY".to_string(), "value".to_string());
+    // A valid key — must survive.
+    global
+        .env_vars
+        .insert("GOOSE_PROVIDER".to_string(), "anthropic".to_string());
+
+    let tiers = build_inherited_tiers(None, None, &[], &global);
+
+    assert!(
+        !tiers.global_env.contains_key("BAD=KEY"),
+        "malformed key must be stripped from global env tier"
+    );
+    assert!(
+        tiers.global_env.contains_key("GOOSE_PROVIDER"),
+        "valid key must survive sanitization"
+    );
+}
+
+// ── get_baked_build_env / is_secret_key tests ──────────────────────────
+
+/// Build a `BakedEnvEntry` vec from a synthetic map, mirroring what
+/// `get_baked_build_env()` does. Used to test masking without relying on
+/// compile-time `option_env!` vars (OSS builds have empty `baked_build_env`).
+fn baked_env_from_map(map: &[(&str, &str)]) -> Vec<BakedEnvEntry> {
+    map.iter()
+        .filter(|(_, v)| !v.is_empty())
+        .map(|(k, v)| {
+            let masked = !super::is_safe_to_reveal(k);
+            BakedEnvEntry {
+                key: k.to_string(),
+                value: if masked {
+                    "\u{2022}\u{2022}\u{2022}\u{2022}\u{2022}\u{2022}".to_string()
+                } else {
+                    v.to_string()
+                },
+                masked,
+            }
+        })
+        .collect()
+}
+
+#[test]
+fn baked_env_non_secret_key_shows_real_value() {
+    let entries = baked_env_from_map(&[("BUZZ_AGENT_PROVIDER", "databricks_v2")]);
+    assert_eq!(entries.len(), 1);
+    assert_eq!(entries[0].key, "BUZZ_AGENT_PROVIDER");
+    assert_eq!(entries[0].value, "databricks_v2");
+    assert!(!entries[0].masked);
+}
+
+#[test]
+fn baked_env_api_key_is_masked() {
+    let entries = baked_env_from_map(&[("ANTHROPIC_API_KEY", "sk-secret")]);
+    assert_eq!(entries.len(), 1);
+    assert_eq!(entries[0].value, "••••••");
+    assert!(entries[0].masked);
+}
+
+#[test]
+fn baked_env_token_key_is_masked() {
+    let entries = baked_env_from_map(&[("GITHUB_TOKEN", "ghp_secret")]);
+    assert_eq!(entries.len(), 1);
+    assert!(entries[0].masked);
+}
+
+#[test]
+fn baked_env_secret_key_is_masked() {
+    let entries = baked_env_from_map(&[("MY_DB_SECRET", "s3cr3t")]);
+    assert_eq!(entries.len(), 1);
+    assert!(entries[0].masked);
+}
+
+#[test]
+fn baked_env_password_key_is_masked() {
+    let entries = baked_env_from_map(&[("DB_PASSWORD", "hunter2")]);
+    assert_eq!(entries.len(), 1);
+    assert!(entries[0].masked);
+}
+
+#[test]
+fn baked_env_empty_value_filtered_out() {
+    let entries = baked_env_from_map(&[("BUZZ_AGENT_PROVIDER", "")]);
+    assert!(entries.is_empty());
+}
+
+#[test]
+fn baked_env_mixed_keys_correct_masking() {
+    let entries = baked_env_from_map(&[
+        ("BUZZ_AGENT_PROVIDER", "databricks_v2"),
+        ("BUZZ_AGENT_MODEL", "goose-claude-opus-4-8"),
+        ("DATABRICKS_HOST", "https://example.com"),
+        ("DATABRICKS_TOKEN", "dapi-secret"),
+    ]);
+    assert_eq!(entries.len(), 4);
+
+    let provider = entries
+        .iter()
+        .find(|e| e.key == "BUZZ_AGENT_PROVIDER")
+        .unwrap();
+    assert_eq!(provider.value, "databricks_v2");
+    assert!(!provider.masked);
+
+    let model = entries
+        .iter()
+        .find(|e| e.key == "BUZZ_AGENT_MODEL")
+        .unwrap();
+    assert_eq!(model.value, "goose-claude-opus-4-8");
+    assert!(!model.masked);
+
+    let host = entries.iter().find(|e| e.key == "DATABRICKS_HOST").unwrap();
+    assert_eq!(host.value, "https://example.com");
+    assert!(!host.masked);
+
+    let token = entries
+        .iter()
+        .find(|e| e.key == "DATABRICKS_TOKEN")
+        .unwrap();
+    assert_eq!(token.value, "••••••");
+    assert!(token.masked);
+}
+
+#[test]
+fn baked_env_thinking_effort_is_unmasked() {
+    // BUZZ_AGENT_THINKING_EFFORT is a non-secret enum — must not be masked.
+    let entries = baked_env_from_map(&[("BUZZ_AGENT_THINKING_EFFORT", "medium")]);
+    assert_eq!(entries.len(), 1);
+    let effort = entries
+        .iter()
+        .find(|e| e.key == "BUZZ_AGENT_THINKING_EFFORT")
+        .unwrap();
+    assert_eq!(effort.value, "medium");
+    assert!(!effort.masked);
+}
+
+#[test]
+fn baked_env_allowlist_is_case_insensitive() {
+    // Known-safe keys — case-insensitive match must allow them.
+    assert!(super::is_safe_to_reveal("buzz_agent_provider"));
+    assert!(super::is_safe_to_reveal("BUZZ_AGENT_PROVIDER"));
+    assert!(super::is_safe_to_reveal("buzz_agent_model"));
+    assert!(super::is_safe_to_reveal("BUZZ_AGENT_MODEL"));
+    assert!(super::is_safe_to_reveal("buzz_agent_thinking_effort"));
+    assert!(super::is_safe_to_reveal("BUZZ_AGENT_THINKING_EFFORT"));
+    assert!(super::is_safe_to_reveal("databricks_host"));
+    assert!(super::is_safe_to_reveal("DATABRICKS_HOST"));
+    assert!(super::is_safe_to_reveal("databricks_model"));
+    assert!(super::is_safe_to_reveal("DATABRICKS_MODEL"));
+    // Keys NOT in the allowlist — masked regardless of naming pattern.
+    assert!(!super::is_safe_to_reveal("my_api_key"));
+    assert!(!super::is_safe_to_reveal("GITHUB_TOKEN"));
+    assert!(!super::is_safe_to_reveal("DB_SECRET"));
+    assert!(!super::is_safe_to_reveal("DB_PASSWORD"));
+    // Bare names that old heuristic (contains("_TOKEN") etc.) would have missed.
+    assert!(!super::is_safe_to_reveal("APIKEY"));
+    assert!(!super::is_safe_to_reveal("TOKEN"));
+    assert!(!super::is_safe_to_reveal("SECRET"));
+    assert!(!super::is_safe_to_reveal("PASSWORD"));
+    assert!(!super::is_safe_to_reveal("PRIVATE_KEY"));
+    // Unknown key → masked by default.
+    assert!(!super::is_safe_to_reveal("SOME_UNKNOWN_KEY"));
+}
diff --git a/desktop/src-tauri/src/commands/agent_discovery.rs b/desktop/src-tauri/src/commands/agent_discovery.rs
index cbbf4ce351..4abf53ee91 100644
--- a/desktop/src-tauri/src/commands/agent_discovery.rs
+++ b/desktop/src-tauri/src/commands/agent_discovery.rs
@@ -333,10 +333,7 @@ fn install_acp_runtime_blocking(
     // For the codex runtime, "found" is not enough — the resolved binary must also
     // pass the 1.x version gate. An outdated 0.16.x adapter must be overwritten by
     // the new npm install so the CODEX_CONFIG spawn contract works correctly.
-    let adapter_path = runtime
-        .commands
-        .iter()
-        .find_map(|cmd| crate::managed_agents::resolve_command(cmd));
+    let adapter_path = resolve_adapter_path(runtime.commands, runtime.adapter_install_commands);
     let adapter_probe_path = crate::managed_agents::readiness::cli_probe::augmented_path();
     if let Some(cmds) = plan_adapter_install(
         runtime_id,
@@ -1020,7 +1017,7 @@ use install_report::InstallReporter;
 mod managed_node;
 use managed_node::{
     ensure_managed_node_runtime_blocking, managed_node_runtime_supported, managed_npm_command,
-    npm_eacces_hint,
+    npm_eacces_hint, resolve_adapter_path,
 };
 
 #[tauri::command]
@@ -1741,7 +1738,7 @@ mod tests {
     #[test]
     fn test_powershell_command_argv_exact() {
         // Catalog format: body wrapped in one outer double-quote pair (Bash-layer serialization).
-        let body = "irm https://chatgpt.com/codex/install.ps1 | iex";
+        let body = "$ErrorActionPreference='Stop'; $installer=Join-Path $env:TEMP 'buzz-install-codex.ps1'; Invoke-RestMethod https://chatgpt.com/codex/install.ps1 -OutFile $installer; & $installer; exit $LASTEXITCODE";
         let cmd = super::install_powershell_command(&format!(
             r#"powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "{body}""#
         ));
@@ -1771,12 +1768,12 @@ mod tests {
         );
     }
 
-    /// Claude Code catalog command (discovery.rs:107) must dequote to the bare pipeline.
+    /// Claude Code catalog command must dequote to the two-step download-then-execute body.
     #[cfg(windows)]
     #[test]
     fn test_powershell_command_claude_catalog_dequoted() {
         let cmd = super::install_powershell_command(
-            r#"powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://claude.ai/install.ps1 | iex""#,
+            r#"powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "$ErrorActionPreference='Stop'; $installer=Join-Path $env:TEMP 'buzz-install-claude.ps1'; Invoke-RestMethod https://claude.ai/install.ps1 -OutFile $installer; & $installer; exit $LASTEXITCODE""#,
         );
         assert_eq!(
             cmd.get_args()
@@ -1787,22 +1784,22 @@ mod tests {
                 "-ExecutionPolicy",
                 "Bypass",
                 "-Command",
-                "irm https://claude.ai/install.ps1 | iex",
+                "$ErrorActionPreference='Stop'; $installer=Join-Path $env:TEMP 'buzz-install-claude.ps1'; Invoke-RestMethod https://claude.ai/install.ps1 -OutFile $installer; & $installer; exit $LASTEXITCODE",
             ],
             "Claude catalog command must be dequoted correctly"
         );
     }
 
-    /// Goose Windows catalog command (discovery.rs:78) must dequote to a bare pipeline
-    /// with a literal `$env:` prefix — no backslash before the dollar sign.
-    /// This proves the `\$` → `$` escape fix: post-#2750 the spawn is native and
+    /// Goose Windows catalog command must dequote to the two-step download-then-execute body
+    /// with the `$env:CONFIGURE` prefix intact — no backslash before the dollar sign.
+    /// This proves the `\$` → `$` contract: post-#2750 the spawn is native and
     /// PowerShell receives the body verbatim, so a residual `\` would produce
     /// `\$env:CONFIGURE='false'` which is a malformed statement.
     #[cfg(windows)]
     #[test]
     fn test_powershell_command_goose_catalog_dequoted() {
         let cmd = super::install_powershell_command(
-            r#"powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "$env:CONFIGURE='false'; irm https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1 | iex""#,
+            r#"powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "$env:CONFIGURE='false'; $ErrorActionPreference='Stop'; $installer=Join-Path $env:TEMP 'buzz-install-goose.ps1'; Invoke-RestMethod https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1 -OutFile $installer; & $installer; exit $LASTEXITCODE""#,
         );
         assert_eq!(
             cmd.get_args()
@@ -1813,7 +1810,7 @@ mod tests {
                 "-ExecutionPolicy",
                 "Bypass",
                 "-Command",
-                "$env:CONFIGURE='false'; irm https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1 | iex",
+                "$env:CONFIGURE='false'; $ErrorActionPreference='Stop'; $installer=Join-Path $env:TEMP 'buzz-install-goose.ps1'; Invoke-RestMethod https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1 -OutFile $installer; & $installer; exit $LASTEXITCODE",
             ],
             "Goose catalog command must dequote with bare $env: (no backslash before $)"
         );
diff --git a/desktop/src-tauri/src/commands/agent_discovery/managed_node.rs b/desktop/src-tauri/src/commands/agent_discovery/managed_node.rs
index 72108f0291..fbfb068c0e 100644
--- a/desktop/src-tauri/src/commands/agent_discovery/managed_node.rs
+++ b/desktop/src-tauri/src/commands/agent_discovery/managed_node.rs
@@ -102,25 +102,155 @@ fn managed_node_failed_step(stderr: String) -> InstallStepResult {
     }
 }
 
-fn managed_node_runtime_ready() -> bool {
+pub(super) fn managed_node_runtime_ready() -> bool {
     let Some(node) = crate::managed_agents::buzz_managed_node_bin_path() else {
         return false;
     };
     if !node.is_file() {
         return false;
     }
-    let mut cmd = std::process::Command::new(&node);
+    probe_node(&node, MANAGED_NODE_VERSION, Duration::from_secs(3))
+}
+
+/// Run `executable --version` with a bounded deadline and return `true` only
+/// when it exits 0 and its trimmed stdout equals `expected_version`.
+///
+/// Transport: stdout is redirected to a temp file so no exit path can block on
+/// an inherited handle (a descendant retaining a pipe write-end would otherwise
+/// prevent EOF indefinitely).
+///
+/// Cleanup: the child runs in its own process group on Unix (`process_group(0)`)
+/// so an unconditional group SIGKILL on every exit path terminates all
+/// descendants.  On Windows, `terminate_process` issues `taskkill /T /F` for
+/// tree-wide cleanup.  SIGKILL to an already-dead group returns ESRCH (no-op).
+pub(super) fn probe_node(
+    executable: &std::path::Path,
+    expected_version: &str,
+    timeout: Duration,
+) -> bool {
+    let tmp = match tempfile::NamedTempFile::new() {
+        Ok(f) => f,
+        Err(_) => return false,
+    };
+    let out_file = match tmp.reopen() {
+        Ok(f) => f,
+        Err(_) => return false,
+    };
+
+    let mut cmd = std::process::Command::new(executable);
     cmd.arg("--version")
         .stdin(std::process::Stdio::null())
-        .stdout(std::process::Stdio::piped())
+        .stdout(std::process::Stdio::from(out_file))
         .stderr(std::process::Stdio::null());
     crate::util::configure_no_window(&mut cmd);
-    let output = cmd.output();
-    output
-        .ok()
-        .filter(|output| output.status.success())
-        .map(|output| String::from_utf8_lossy(&output.stdout).trim() == MANAGED_NODE_VERSION)
-        .unwrap_or(false)
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::CommandExt;
+        cmd.process_group(0);
+    }
+    let Ok(mut child) = cmd.spawn() else {
+        return false;
+    };
+
+    let deadline = std::time::Instant::now() + timeout;
+    let exit_status = loop {
+        match child.try_wait() {
+            Ok(Some(status)) => break status,
+            Ok(None) => {
+                if std::time::Instant::now() >= deadline {
+                    kill_probe_group(child.id());
+                    let _ = child.wait();
+                    return false;
+                }
+                std::thread::sleep(Duration::from_millis(50));
+            }
+            Err(_) => {
+                kill_probe_group(child.id());
+                let _ = child.wait();
+                return false;
+            }
+        }
+    };
+
+    // Group-kill unconditionally: SIGKILL to a dead group is ESRCH (no-op).
+    kill_probe_group(child.id());
+
+    if !exit_status.success() {
+        return false;
+    }
+
+    let mut output = String::new();
+    if std::io::Read::read_to_string(&mut tmp.as_file(), &mut output).is_err() {
+        return false;
+    }
+    output.trim() == expected_version
+}
+
+/// Kill the probe's process group/tree unconditionally (no TERM grace — this
+/// is a probe, not an agent session).  ESRCH on a dead group is fine.
+fn kill_probe_group(pid: u32) {
+    #[cfg(unix)]
+    unsafe {
+        libc::kill(-(pid as i32), libc::SIGKILL);
+    }
+    #[cfg(windows)]
+    {
+        let _ = crate::managed_agents::terminate_process(pid);
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        let _ = pid;
+    }
+}
+
+/// Returns `true` when the managed Node runtime is absent or no longer executes —
+/// meaning any existing npm adapter shims are broken and must be reinstalled.
+///
+/// This fires when the pinned Node version changes (e.g. v24.11.0 → v24.18.0):
+/// the old dir stays on disk, shims appear installed, but they fail at run time
+/// because the Node binary they reference is gone.  Treating the adapter as
+/// missing forces `ensure_managed_node_runtime_blocking` to re-download Node and
+/// npm to reinstall the shims.
+pub(super) fn managed_node_orphaned() -> bool {
+    managed_node_runtime_supported() && !managed_node_runtime_ready()
+}
+
+/// Returns `true` when an adapter at `resolved` should be invalidated.
+///
+/// Only a Buzz-managed shim (path under `managed_prefix`) with an orphaned
+/// runtime is invalidated; external adapters are always preserved.
+pub(super) fn should_invalidate_adapter(
+    resolved: &std::path::Path,
+    managed_prefix: &std::path::Path,
+    orphaned: bool,
+) -> bool {
+    orphaned && resolved.starts_with(managed_prefix)
+}
+
+/// Resolve the adapter binary path, accounting for the Node-orphan case.
+/// Resolves first; invalidates only managed-prefix shims when Node is orphaned.
+pub(super) fn resolve_adapter_path(
+    commands: &[&str],
+    adapter_install_commands: &[&str],
+) -> Option<std::path::PathBuf> {
+    let resolved = commands
+        .iter()
+        .find_map(|cmd| crate::managed_agents::resolve_command(cmd));
+
+    let needs_managed_npm = adapter_install_commands
+        .iter()
+        .any(|cmd| is_npm_global_install(cmd));
+    if needs_managed_npm {
+        if let (Some(ref path), Some(ref managed_bin)) =
+            (&resolved, crate::managed_agents::buzz_managed_npm_bin_dir())
+        {
+            if should_invalidate_adapter(path, managed_bin, managed_node_orphaned()) {
+                return None;
+            }
+        }
+    }
+
+    resolved
 }
 
 fn managed_node_install_lock() -> &'static Mutex<()> {
@@ -538,211 +668,5 @@ pub(super) fn npm_eacces_hint(stderr: &str, _command: &str) -> Option<String> {
 // ── end managed npm adapter installs ──────────────────────────────────────────
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_npm_eacces_hint_guidance_mentions_buzz_private_dir() {
-        let hint = npm_eacces_hint("EACCES: permission denied", "npm install -g foo").unwrap();
-        assert!(
-            hint.contains("Buzz's private Node tools directory"),
-            "hint: {hint}"
-        );
-    }
-
-    #[test]
-    fn test_rewrite_npm_install_uses_private_prefix() {
-        assert_eq!(
-            rewrite_npm_global_install(
-                "npm install -g @agentclientprotocol/codex-acp",
-                "'/tmp/Buzz Node'"
-            ),
-            "npm install --global --prefix '/tmp/Buzz Node' @agentclientprotocol/codex-acp"
-        );
-    }
-
-    #[test]
-    fn test_rewrite_npm_i_uses_private_prefix() {
-        assert_eq!(
-            rewrite_npm_global_install("npm i -g some-package", "'/tmp/buzz'"),
-            "npm i --global --prefix '/tmp/buzz' some-package"
-        );
-    }
-
-    #[test]
-    fn test_rewrite_npm_uninstall_uses_private_prefix() {
-        assert_eq!(
-            rewrite_npm_global_install("npm uninstall -g @zed-industries/codex-acp", "'/tmp/buzz'"),
-            "npm uninstall --global --prefix '/tmp/buzz' @zed-industries/codex-acp"
-        );
-    }
-
-    #[test]
-    fn test_rewrite_ignores_non_global_command() {
-        assert_eq!(
-            rewrite_npm_global_install("npm install foo", "'/tmp/buzz'"),
-            "npm install foo"
-        );
-    }
-
-    #[test]
-    fn test_shell_quote_escapes_single_quotes() {
-        assert_eq!(
-            shell_quote(std::path::Path::new("/tmp/Buzz's Node")),
-            "'/tmp/Buzz'\\''s Node'"
-        );
-    }
-
-    // ── zip validation tests ──────────────────────────────────────────────────
-
-    /// Build an in-memory zip archive with the supplied entry names and return
-    /// a temporary file containing it (zip::ZipArchive requires Seek).
-    fn make_zip_with_entries(entry_names: &[&str]) -> tempfile::NamedTempFile {
-        let mut buf: Vec<u8> = Vec::new();
-        {
-            let mut writer = zip::ZipWriter::new(std::io::Cursor::new(&mut buf));
-            let opts = zip::write::SimpleFileOptions::default();
-            for name in entry_names {
-                writer.start_file(*name, opts).unwrap();
-            }
-            writer.finish().unwrap();
-        }
-        let mut tmp = tempfile::NamedTempFile::new().unwrap();
-        std::io::Write::write_all(&mut tmp, &buf).unwrap();
-        tmp
-    }
-
-    #[test]
-    fn test_validate_zip_accepts_normal_entries() {
-        let tmp = make_zip_with_entries(&[
-            "node-v24.18.0-win-x64/node.exe",
-            "node-v24.18.0-win-x64/npm.cmd",
-            "node-v24.18.0-win-x64/npm",
-        ]);
-        let file = std::fs::File::open(tmp.path()).unwrap();
-        let archive = zip::ZipArchive::new(file).unwrap();
-        assert!(validate_managed_node_zip_entries(&archive).is_ok());
-    }
-
-    #[test]
-    fn test_validate_zip_rejects_absolute_path() {
-        let tmp = make_zip_with_entries(&["/etc/passwd"]);
-        let file = std::fs::File::open(tmp.path()).unwrap();
-        let archive = zip::ZipArchive::new(file).unwrap();
-        let err = validate_managed_node_zip_entries(&archive).unwrap_err();
-        assert!(
-            err.contains("absolute path"),
-            "expected 'absolute path' in: {err}"
-        );
-    }
-
-    #[test]
-    fn test_validate_zip_rejects_path_traversal() {
-        let tmp = make_zip_with_entries(&["../../../etc/passwd"]);
-        let file = std::fs::File::open(tmp.path()).unwrap();
-        let archive = zip::ZipArchive::new(file).unwrap();
-        let err = validate_managed_node_zip_entries(&archive).unwrap_err();
-        assert!(
-            err.contains("path traversal"),
-            "expected 'path traversal' in: {err}"
-        );
-    }
-
-    #[test]
-    fn test_validate_zip_rejects_backslash_rooted() {
-        // Windows-style absolute path using backslash — must reject on every host.
-        let tmp = make_zip_with_entries(&["\\Windows\\system32\\evil.dll"]);
-        let file = std::fs::File::open(tmp.path()).unwrap();
-        let archive = zip::ZipArchive::new(file).unwrap();
-        let err = validate_managed_node_zip_entries(&archive).unwrap_err();
-        assert!(
-            err.contains("absolute path"),
-            "expected 'absolute path' in: {err}"
-        );
-    }
-
-    #[test]
-    fn test_validate_zip_rejects_drive_prefix() {
-        // Windows drive-letter absolute path — must reject on every host.
-        let tmp = make_zip_with_entries(&["C:\\evil\\payload.exe"]);
-        let file = std::fs::File::open(tmp.path()).unwrap();
-        let archive = zip::ZipArchive::new(file).unwrap();
-        let err = validate_managed_node_zip_entries(&archive).unwrap_err();
-        assert!(
-            err.contains("absolute path"),
-            "expected 'absolute path' in: {err}"
-        );
-    }
-
-    #[test]
-    fn test_validate_zip_rejects_backslash_traversal() {
-        // Path traversal using Windows separator — must reject on every host.
-        let tmp = make_zip_with_entries(&["node-v24.18.0-win-x64\\..\\..\\evil"]);
-        let file = std::fs::File::open(tmp.path()).unwrap();
-        let archive = zip::ZipArchive::new(file).unwrap();
-        let err = validate_managed_node_zip_entries(&archive).unwrap_err();
-        assert!(
-            err.contains("path traversal"),
-            "expected 'path traversal' in: {err}"
-        );
-    }
-
-    // ── verify_node_tree layout tests ─────────────────────────────────────────
-
-    #[test]
-    fn test_verify_node_tree_unix_layout_passes() {
-        let tmp = tempfile::TempDir::new().unwrap();
-        let bin = tmp.path().join("bin");
-        std::fs::create_dir_all(&bin).unwrap();
-        std::fs::write(bin.join("node"), b"").unwrap();
-        std::fs::write(bin.join("npm"), b"").unwrap();
-        // On non-Windows the unix branch is active — this must pass.
-        #[cfg(not(windows))]
-        assert!(verify_node_tree(tmp.path()).is_ok());
-        // On Windows the windows branch is active — unix layout must fail.
-        #[cfg(windows)]
-        assert!(verify_node_tree(tmp.path()).is_err());
-    }
-
-    #[test]
-    fn test_verify_node_tree_unix_layout_missing_npm_fails() {
-        let tmp = tempfile::TempDir::new().unwrap();
-        let bin = tmp.path().join("bin");
-        std::fs::create_dir_all(&bin).unwrap();
-        std::fs::write(bin.join("node"), b"").unwrap();
-        // npm intentionally absent
-        #[cfg(not(windows))]
-        {
-            let err = verify_node_tree(tmp.path()).unwrap_err();
-            assert!(err.contains("bin/npm"), "err: {err}");
-        }
-    }
-
-    #[test]
-    fn test_verify_node_tree_windows_layout_passes() {
-        let tmp = tempfile::TempDir::new().unwrap();
-        std::fs::write(tmp.path().join("node.exe"), b"").unwrap();
-        std::fs::write(tmp.path().join("npm.cmd"), b"").unwrap();
-        std::fs::write(tmp.path().join("npm"), b"").unwrap();
-        // On Windows the windows branch is active — this must pass.
-        #[cfg(windows)]
-        assert!(verify_node_tree(tmp.path()).is_ok());
-        // On non-Windows the unix branch is active — windows-layout root files
-        // don't satisfy bin/node + bin/npm, so this must fail.
-        #[cfg(not(windows))]
-        assert!(verify_node_tree(tmp.path()).is_err());
-    }
-
-    #[test]
-    fn test_verify_node_tree_windows_layout_missing_npm_shim_fails() {
-        let tmp = tempfile::TempDir::new().unwrap();
-        std::fs::write(tmp.path().join("node.exe"), b"").unwrap();
-        std::fs::write(tmp.path().join("npm.cmd"), b"").unwrap();
-        // npm POSIX shim intentionally absent
-        #[cfg(windows)]
-        {
-            let err = verify_node_tree(tmp.path()).unwrap_err();
-            assert!(err.contains("npm"), "err: {err}");
-        }
-    }
-}
+#[path = "managed_node_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/commands/agent_discovery/managed_node_tests.rs b/desktop/src-tauri/src/commands/agent_discovery/managed_node_tests.rs
new file mode 100644
index 0000000000..a8e1d7f4c8
--- /dev/null
+++ b/desktop/src-tauri/src/commands/agent_discovery/managed_node_tests.rs
@@ -0,0 +1,481 @@
+use super::*;
+
+#[test]
+fn test_npm_eacces_hint_guidance_mentions_buzz_private_dir() {
+    let hint = npm_eacces_hint("EACCES: permission denied", "npm install -g foo").unwrap();
+    assert!(
+        hint.contains("Buzz's private Node tools directory"),
+        "hint: {hint}"
+    );
+}
+
+#[test]
+fn test_rewrite_npm_install_uses_private_prefix() {
+    assert_eq!(
+        rewrite_npm_global_install(
+            "npm install -g @agentclientprotocol/codex-acp",
+            "'/tmp/Buzz Node'"
+        ),
+        "npm install --global --prefix '/tmp/Buzz Node' @agentclientprotocol/codex-acp"
+    );
+}
+
+#[test]
+fn test_rewrite_npm_i_uses_private_prefix() {
+    assert_eq!(
+        rewrite_npm_global_install("npm i -g some-package", "'/tmp/buzz'"),
+        "npm i --global --prefix '/tmp/buzz' some-package"
+    );
+}
+
+#[test]
+fn test_rewrite_npm_uninstall_uses_private_prefix() {
+    assert_eq!(
+        rewrite_npm_global_install("npm uninstall -g @zed-industries/codex-acp", "'/tmp/buzz'"),
+        "npm uninstall --global --prefix '/tmp/buzz' @zed-industries/codex-acp"
+    );
+}
+
+#[test]
+fn test_rewrite_ignores_non_global_command() {
+    assert_eq!(
+        rewrite_npm_global_install("npm install foo", "'/tmp/buzz'"),
+        "npm install foo"
+    );
+}
+
+#[test]
+fn test_shell_quote_escapes_single_quotes() {
+    assert_eq!(
+        shell_quote(std::path::Path::new("/tmp/Buzz's Node")),
+        "'/tmp/Buzz'\\''s Node'"
+    );
+}
+
+// ── zip validation tests ──────────────────────────────────────────────────────
+
+/// Build an in-memory zip archive with the supplied entry names and return
+/// a temporary file containing it (zip::ZipArchive requires Seek).
+fn make_zip_with_entries(entry_names: &[&str]) -> tempfile::NamedTempFile {
+    let mut buf: Vec<u8> = Vec::new();
+    {
+        let mut writer = zip::ZipWriter::new(std::io::Cursor::new(&mut buf));
+        let opts = zip::write::SimpleFileOptions::default();
+        for name in entry_names {
+            writer.start_file(*name, opts).unwrap();
+        }
+        writer.finish().unwrap();
+    }
+    let mut tmp = tempfile::NamedTempFile::new().unwrap();
+    std::io::Write::write_all(&mut tmp, &buf).unwrap();
+    tmp
+}
+
+#[test]
+fn test_validate_zip_accepts_normal_entries() {
+    let tmp = make_zip_with_entries(&[
+        "node-v24.18.0-win-x64/node.exe",
+        "node-v24.18.0-win-x64/npm.cmd",
+        "node-v24.18.0-win-x64/npm",
+    ]);
+    let file = std::fs::File::open(tmp.path()).unwrap();
+    let archive = zip::ZipArchive::new(file).unwrap();
+    assert!(validate_managed_node_zip_entries(&archive).is_ok());
+}
+
+#[test]
+fn test_validate_zip_rejects_absolute_path() {
+    let tmp = make_zip_with_entries(&["/etc/passwd"]);
+    let file = std::fs::File::open(tmp.path()).unwrap();
+    let archive = zip::ZipArchive::new(file).unwrap();
+    let err = validate_managed_node_zip_entries(&archive).unwrap_err();
+    assert!(
+        err.contains("absolute path"),
+        "expected 'absolute path' in: {err}"
+    );
+}
+
+#[test]
+fn test_validate_zip_rejects_path_traversal() {
+    let tmp = make_zip_with_entries(&["../../../etc/passwd"]);
+    let file = std::fs::File::open(tmp.path()).unwrap();
+    let archive = zip::ZipArchive::new(file).unwrap();
+    let err = validate_managed_node_zip_entries(&archive).unwrap_err();
+    assert!(
+        err.contains("path traversal"),
+        "expected 'path traversal' in: {err}"
+    );
+}
+
+#[test]
+fn test_validate_zip_rejects_backslash_rooted() {
+    // Windows-style absolute path using backslash — must reject on every host.
+    let tmp = make_zip_with_entries(&["\\Windows\\system32\\evil.dll"]);
+    let file = std::fs::File::open(tmp.path()).unwrap();
+    let archive = zip::ZipArchive::new(file).unwrap();
+    let err = validate_managed_node_zip_entries(&archive).unwrap_err();
+    assert!(
+        err.contains("absolute path"),
+        "expected 'absolute path' in: {err}"
+    );
+}
+
+#[test]
+fn test_validate_zip_rejects_drive_prefix() {
+    // Windows drive-letter absolute path — must reject on every host.
+    let tmp = make_zip_with_entries(&["C:\\evil\\payload.exe"]);
+    let file = std::fs::File::open(tmp.path()).unwrap();
+    let archive = zip::ZipArchive::new(file).unwrap();
+    let err = validate_managed_node_zip_entries(&archive).unwrap_err();
+    assert!(
+        err.contains("absolute path"),
+        "expected 'absolute path' in: {err}"
+    );
+}
+
+#[test]
+fn test_validate_zip_rejects_backslash_traversal() {
+    // Path traversal using Windows separator — must reject on every host.
+    let tmp = make_zip_with_entries(&["node-v24.18.0-win-x64\\..\\..\\evil"]);
+    let file = std::fs::File::open(tmp.path()).unwrap();
+    let archive = zip::ZipArchive::new(file).unwrap();
+    let err = validate_managed_node_zip_entries(&archive).unwrap_err();
+    assert!(
+        err.contains("path traversal"),
+        "expected 'path traversal' in: {err}"
+    );
+}
+
+// ── verify_node_tree layout tests ─────────────────────────────────────────────
+
+#[test]
+fn test_verify_node_tree_unix_layout_passes() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    let bin = tmp.path().join("bin");
+    std::fs::create_dir_all(&bin).unwrap();
+    std::fs::write(bin.join("node"), b"").unwrap();
+    std::fs::write(bin.join("npm"), b"").unwrap();
+    // On non-Windows the unix branch is active — this must pass.
+    #[cfg(not(windows))]
+    assert!(verify_node_tree(tmp.path()).is_ok());
+    // On Windows the windows branch is active — unix layout must fail.
+    #[cfg(windows)]
+    assert!(verify_node_tree(tmp.path()).is_err());
+}
+
+#[test]
+fn test_verify_node_tree_unix_layout_missing_npm_fails() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    let bin = tmp.path().join("bin");
+    std::fs::create_dir_all(&bin).unwrap();
+    std::fs::write(bin.join("node"), b"").unwrap();
+    // npm intentionally absent
+    #[cfg(not(windows))]
+    {
+        let err = verify_node_tree(tmp.path()).unwrap_err();
+        assert!(err.contains("bin/npm"), "err: {err}");
+    }
+}
+
+#[test]
+fn test_verify_node_tree_windows_layout_passes() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    std::fs::write(tmp.path().join("node.exe"), b"").unwrap();
+    std::fs::write(tmp.path().join("npm.cmd"), b"").unwrap();
+    std::fs::write(tmp.path().join("npm"), b"").unwrap();
+    // On Windows the windows branch is active — this must pass.
+    #[cfg(windows)]
+    assert!(verify_node_tree(tmp.path()).is_ok());
+    // On non-Windows the unix branch is active — windows-layout root files
+    // don't satisfy bin/node + bin/npm, so this must fail.
+    #[cfg(not(windows))]
+    assert!(verify_node_tree(tmp.path()).is_err());
+}
+
+#[test]
+fn test_verify_node_tree_windows_layout_missing_npm_shim_fails() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    std::fs::write(tmp.path().join("node.exe"), b"").unwrap();
+    std::fs::write(tmp.path().join("npm.cmd"), b"").unwrap();
+    // npm POSIX shim intentionally absent
+    #[cfg(windows)]
+    {
+        let err = verify_node_tree(tmp.path()).unwrap_err();
+        assert!(err.contains("npm"), "err: {err}");
+    }
+}
+
+// ── should_invalidate_adapter / orphan policy pure unit tests ─────────────────
+
+#[test]
+fn test_should_invalidate_adapter_invalidates_managed_shim_when_orphaned() {
+    let prefix = std::path::Path::new("/managed/npm/bin");
+    let shim = prefix.join("codex-acp");
+    assert!(
+        should_invalidate_adapter(&shim, prefix, true),
+        "managed shim + orphaned runtime must be invalidated"
+    );
+}
+
+#[test]
+fn test_should_invalidate_adapter_keeps_external_adapter_when_orphaned() {
+    let prefix = std::path::Path::new("/managed/npm/bin");
+    let external = std::path::Path::new("/usr/local/bin/codex-acp");
+    assert!(
+        !should_invalidate_adapter(external, prefix, true),
+        "external adapter must not be invalidated even when Node is orphaned"
+    );
+}
+
+#[test]
+fn test_should_invalidate_adapter_keeps_managed_shim_when_node_healthy() {
+    let prefix = std::path::Path::new("/managed/npm/bin");
+    let shim = prefix.join("codex-acp");
+    assert!(
+        !should_invalidate_adapter(&shim, prefix, false),
+        "managed shim must not be invalidated when Node is healthy"
+    );
+}
+
+#[test]
+fn test_resolve_adapter_path_returns_none_when_binary_absent() {
+    let commands: &[&str] = &["nonexistent-buzz-test-binary-xyz"];
+    let adapter_install_commands: &[&str] = &["curl -fsSL https://example.com | bash"];
+    assert!(
+        resolve_adapter_path(commands, adapter_install_commands).is_none(),
+        "must return None when the command is not on PATH"
+    );
+}
+
+// ── probe_node seam regressions ───────────────────────────────────────────────
+//
+// All four scenarios drive probe_node() directly — the same
+// tempfile/deadline/cleanup/status/version path used by managed_node_runtime_ready.
+// Each test CAN fail if production:
+//   - drops process_group(0)          → descendant-holds-stdout assertion (d) fails
+//                                       (tempfile transport still returns promptly;
+//                                        the sleep survives and kill($!,0) returns 0)
+//   - skips group-kill on a path      → hung-binary test exceeds margin
+//   - ignores exit_status.success()   → nonzero-exit test returns true
+//   - skips version comparison        → wrong-version test returns true
+//
+// Script files are written into a TempDir (no open write fd at spawn time)
+// to avoid ETXTBSY on Linux.
+
+/// Scenario 1 — descendant holds stdout write-end, direct child exits immediately.
+///
+/// The script backgrounds a 60-second sleep (inheriting stdout), records both the
+/// script's own PID (`$$`) and the sleep's PID (`$!`) to sidecar files, then exits
+/// with the expected version string.  Four assertions:
+///   (a) bounded return — would hang ~60 s if tempfile transport regressed to pipe;
+///   (b) correct result;
+///   (c) process group dead after return — catches skipped-cleanup-on-success: if
+///       the group-kill is absent but `process_group(0)` is still present, a live
+///       member in the group is detectable;
+///   (d) descendant PID dead after return — catches dropped `process_group(0)`: if
+///       the call is removed the sleep stays in the runner's group (not the probe's),
+///       `kill(-pgid,0)` is vacuously ESRCH, but `kill(desc_pid,0)` returns 0 and
+///       this assertion fails.  This is the canonical mutation for (c).
+#[cfg(unix)]
+#[test]
+fn test_probe_node_descendant_holds_stdout_returns_promptly_and_kills_group() {
+    use std::os::unix::fs::PermissionsExt;
+    let tmp_dir = tempfile::TempDir::new().unwrap();
+    let script = tmp_dir.path().join("probe.sh");
+    let pgid_file = tmp_dir.path().join("pgid");
+    let desc_pid_file = tmp_dir.path().join("desc_pid");
+    let pgid_file_path = pgid_file.to_str().unwrap().to_owned();
+    let desc_pid_file_path = desc_pid_file.to_str().unwrap().to_owned();
+    // Line 1 of script: record the script's own PID (= PGID after process_group(0)).
+    // Line 2: background the sleep and record its PID.
+    // Line 3: emit the expected version and exit so the direct child exits promptly.
+    let script_content = format!(
+        "#!/bin/sh\necho $$ > {pgid_file_path}\n/bin/sleep 60 &\necho $! > {desc_pid_file_path}\necho v24.18.0\nexit 0\n"
+    );
+    std::fs::write(&script, script_content.as_bytes()).unwrap();
+    std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
+
+    let probe_timeout = std::time::Duration::from_secs(3);
+    let t = std::time::Instant::now();
+    let result = probe_node(&script, "v24.18.0", probe_timeout);
+    let elapsed = t.elapsed();
+
+    // Give the group-kill a moment to propagate before checking liveness.
+    std::thread::sleep(std::time::Duration::from_millis(200));
+
+    // (a) bounded return — tempfile transport must not hang on the descendant's
+    //     retained pipe write-end.
+    assert!(
+        elapsed < probe_timeout + std::time::Duration::from_secs(2),
+        "probe_node hung — likely descendant retained pipe write-end: elapsed {elapsed:?}"
+    );
+    // (b) correct result
+    assert!(result, "probe_node must return true for matching version");
+
+    // (c) process group dead — catches skipped-cleanup: if the group-kill on the
+    //     success path is removed while process_group(0) is still present, the
+    //     sleep remains in the probe's group and kill(-pgid,0) returns 0.
+    let pgid_str = std::fs::read_to_string(&pgid_file)
+        .expect("script must have written its PID to the pgid sidecar");
+    let pgid: i32 = pgid_str
+        .trim()
+        .parse()
+        .expect("pgid sidecar must contain a numeric PID");
+    let group_alive = unsafe { libc::kill(-pgid, 0) } == 0;
+    assert!(
+        !group_alive,
+        "process group {pgid} must be dead after probe_node"
+    );
+
+    // (d) descendant PID dead — catches dropped process_group(0): without that
+    //     call the sleep is never in the probe's group, so kill(-pgid,0) is
+    //     vacuously ESRCH while the sleep survives.  Asserting the descendant's
+    //     own PID is dead proves the sleep was actually killed.
+    let desc_pid_str = std::fs::read_to_string(&desc_pid_file)
+        .expect("script must have written the sleep PID to the desc_pid sidecar");
+    let desc_pid: libc::pid_t = desc_pid_str
+        .trim()
+        .parse()
+        .expect("desc_pid sidecar must contain a numeric PID");
+    // Pre-assert cleanup: if the descendant is somehow still alive, kill it so
+    // a failing test does not leave a 60-second sleep in the runner's process group.
+    let desc_alive = unsafe { libc::kill(desc_pid, 0) } == 0;
+    if desc_alive {
+        unsafe { libc::kill(desc_pid, libc::SIGKILL) };
+    }
+    assert!(
+        !desc_alive,
+        "descendant PID {desc_pid} must be dead after probe_node — \
+         if process_group(0) is dropped, the sleep escapes into the runner's group \
+         and is never killed by the group-kill"
+    );
+}
+
+/// Scenario 2 — direct hang: probe_node must traverse the real try_wait
+/// deadline and return false.  Does NOT call kill_probe_group directly.
+///
+/// This test FAILS if the deadline loop in probe_node is broken or if the
+/// timeout/kill path is not exercised (e.g., missing group-kill exits the
+/// loop early via a different mechanism).
+#[cfg(unix)]
+#[test]
+fn test_probe_node_times_out_on_hung_binary() {
+    use std::os::unix::fs::PermissionsExt;
+    let tmp_dir = tempfile::TempDir::new().unwrap();
+    let script = tmp_dir.path().join("hung.sh");
+    std::fs::write(&script, b"#!/bin/sh\n/bin/sleep 30\n").unwrap();
+    std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
+
+    let probe_timeout = std::time::Duration::from_secs(3);
+    let t = std::time::Instant::now();
+    let result = probe_node(&script, "v24.18.0", probe_timeout);
+    let elapsed = t.elapsed();
+
+    assert!(!result, "probe_node must return false for a hung binary");
+    // Must have traversed the deadline (not returned early via a bug).
+    assert!(
+        elapsed >= probe_timeout,
+        "probe_node returned before deadline: {elapsed:?} < {probe_timeout:?}"
+    );
+    // Must not hang past the deadline by more than the poll interval + margin.
+    assert!(
+        elapsed < probe_timeout + std::time::Duration::from_secs(3),
+        "probe_node exceeded deadline by too much: {elapsed:?}"
+    );
+}
+
+/// Scenario 3 — non-zero exit: probe_node must return false even when stdout
+/// contains the expected version string.
+///
+/// This test FAILS if probe_node skips or inverts the exit_status.success() check.
+#[cfg(unix)]
+#[test]
+fn test_probe_node_returns_false_on_nonzero_exit() {
+    use std::os::unix::fs::PermissionsExt;
+    let tmp_dir = tempfile::TempDir::new().unwrap();
+    let script = tmp_dir.path().join("fail.sh");
+    // Prints the expected version string but exits non-zero.
+    std::fs::write(&script, b"#!/bin/sh\necho v24.18.0\nexit 1\n").unwrap();
+    std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
+
+    let result = probe_node(&script, "v24.18.0", std::time::Duration::from_secs(3));
+    assert!(
+        !result,
+        "probe_node must return false when the process exits non-zero"
+    );
+}
+
+/// Scenario 4 — wrong version output: probe_node must return false when stdout
+/// does not match expected_version.
+///
+/// This test FAILS if probe_node skips or incorrectly performs the version comparison.
+#[cfg(unix)]
+#[test]
+fn test_probe_node_returns_false_on_wrong_version_output() {
+    use std::os::unix::fs::PermissionsExt;
+    let tmp_dir = tempfile::TempDir::new().unwrap();
+    let script = tmp_dir.path().join("wrongver.sh");
+    std::fs::write(&script, b"#!/bin/sh\necho v99.0.0\nexit 0\n").unwrap();
+    std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
+
+    let result = probe_node(&script, "v24.18.0", std::time::Duration::from_secs(3));
+    assert!(
+        !result,
+        "probe_node must return false when stdout version does not match expected"
+    );
+}
+
+/// Windows-shaped seam: non-zero exit via .bat file.
+///
+/// Drives the same probe_node path on Windows (terminate_process / taskkill /T /F).
+/// This test FAILS if probe_node ignores exit_status.success() on Windows.
+#[cfg(windows)]
+#[test]
+fn test_probe_node_windows_returns_false_on_nonzero_exit() {
+    let tmp_dir = tempfile::TempDir::new().unwrap();
+    let bat = tmp_dir.path().join("fail.bat");
+    // Prints the expected version but exits non-zero — must still fail.
+    std::fs::write(&bat, b"@echo off\r\necho v24.18.0\r\nexit /b 1\r\n").unwrap();
+
+    let result = probe_node(&bat, "v24.18.0", std::time::Duration::from_secs(3));
+    assert!(
+        !result,
+        "probe_node must return false when the .bat exits non-zero (Windows)"
+    );
+}
+
+/// Windows-shaped seam: wrong version output via .bat file.
+///
+/// This test FAILS if probe_node skips the version comparison on Windows.
+#[cfg(windows)]
+#[test]
+fn test_probe_node_windows_returns_false_on_wrong_version_output() {
+    let tmp_dir = tempfile::TempDir::new().unwrap();
+    let bat = tmp_dir.path().join("wrongver.bat");
+    std::fs::write(&bat, b"@echo off\r\necho v99.0.0\r\nexit /b 0\r\n").unwrap();
+
+    let result = probe_node(&bat, "v24.18.0", std::time::Duration::from_secs(3));
+    assert!(
+        !result,
+        "probe_node must return false when stdout version does not match (Windows)"
+    );
+}
+
+/// Returns false when the node binary path does not exist (fast path, no spawn).
+#[test]
+fn test_managed_node_runtime_ready_returns_false_when_binary_absent() {
+    let Some(node) = crate::managed_agents::buzz_managed_node_bin_path() else {
+        assert!(
+            !managed_node_runtime_ready(),
+            "managed_node_runtime_ready must return false when no path resolves"
+        );
+        return;
+    };
+    if node.is_file() {
+        return;
+    }
+    assert!(
+        !managed_node_runtime_ready(),
+        "managed_node_runtime_ready must return false when the binary file does not exist"
+    );
+}
diff --git a/desktop/src-tauri/src/commands/agents.rs b/desktop/src-tauri/src/commands/agents.rs
index 0758fc3aac..3b114b0474 100644
--- a/desktop/src-tauri/src/commands/agents.rs
+++ b/desktop/src-tauri/src/commands/agents.rs
@@ -1362,7 +1362,7 @@ use deploy::build_deploy_payload;
 #[cfg(test)]
 use deploy::deploy_payload_json;
 #[cfg(test)]
-pub(crate) use deploy::resolve_deploy_model_provider;
+use deploy::{ensure_remote_provider_supported, resolve_deploy_model_provider};
 
 #[path = "agents_profile.rs"]
 mod profile;
diff --git a/desktop/src-tauri/src/commands/agents_deploy.rs b/desktop/src-tauri/src/commands/agents_deploy.rs
index af785711d5..9bb0f6230d 100644
--- a/desktop/src-tauri/src/commands/agents_deploy.rs
+++ b/desktop/src-tauri/src/commands/agents_deploy.rs
@@ -1,6 +1,8 @@
 //! Provider deploy payload construction, split from `agents.rs` (file-size
-//! guard). `build_deploy_payload` gathers live state; `deploy_payload_json`
-//! is the pure serialization half so payload completeness stays testable.
+//! guard). The launch block is derived from the same effective descriptor and
+//! policy helpers as local spawn so remote execution does not reimplement them.
+
+use std::collections::BTreeMap;
 
 use tauri::AppHandle;
 
@@ -13,17 +15,6 @@ use crate::{
 };
 
 /// Resolve the deploy-specific structured model/provider for a managed agent.
-///
-/// Delegates to the single effective-config resolver which enforces
-/// definition-authoritative semantics for linked instances:
-///   - **Linked:** definition → global. Stale record bytes are never consulted.
-///   - **Definition-less:** instance → global.
-///   - **Orphaned:** returns `(None, None)` — spawn is blocked elsewhere.
-///
-/// Both local spawn and deploy now use the same resolver, so they can never
-/// disagree on what model/provider an agent runs with.
-///
-/// Exported `pub(crate)` for unit testing.
 #[cfg(test)]
 pub(crate) fn resolve_deploy_model_provider(
     record: &ManagedAgentRecord,
@@ -36,58 +27,116 @@ pub(crate) fn resolve_deploy_model_provider(
     .unwrap_or((None, None))
 }
 
+/// Serialize the portable launch contract shared with provider-backed agents.
+///
+/// `descriptor.env` is the authoritative six-layer environment. Policy values
+/// are deliberately separate because providers apply them below that layered
+/// environment, preserving the local spawn's power-user override semantics.
+pub(super) fn build_launch_block(
+    record: &ManagedAgentRecord,
+    descriptor: &crate::managed_agents::readiness::EffectiveHarnessDescriptor,
+    teams: &[crate::managed_agents::TeamRecord],
+    effective_prompt: Option<&str>,
+    effective_model: Option<&str>,
+    owner_pubkey: &str,
+) -> serde_json::Value {
+    use crate::managed_agents::{known_acp_runtime, resolve_session_title, SESSION_TITLE_ENV_VAR};
+
+    let runtime = known_acp_runtime(&descriptor.command);
+    let mut policy_env = BTreeMap::new();
+
+    if let Some(runtime) = runtime {
+        policy_env.extend(
+            runtime
+                .default_env
+                .iter()
+                .map(|(key, value)| ((*key).to_string(), (*value).to_string())),
+        );
+        if runtime.mcp_hooks {
+            policy_env.insert("MCP_HOOK_SERVERS".into(), "*".into());
+        }
+    }
+    policy_env.insert("BUZZ_ACP_RELAY_OBSERVER".into(), "true".into());
+    policy_env.insert("BUZZ_ACP_LAZY_POOL".into(), "true".into());
+    policy_env.insert("BUZZ_ACP_AGENTS".into(), record.parallelism.to_string());
+
+    if let Some(value) = effective_prompt {
+        policy_env.insert("BUZZ_ACP_SYSTEM_PROMPT".into(), value.to_string());
+    }
+    if let Some(value) = effective_model {
+        policy_env.insert("BUZZ_ACP_MODEL".into(), value.to_string());
+    }
+    if let Some(value) = record.idle_timeout_seconds {
+        policy_env.insert("BUZZ_ACP_IDLE_TIMEOUT".into(), value.to_string());
+    }
+    if let Some(value) = record.max_turn_duration_seconds {
+        policy_env.insert("BUZZ_ACP_MAX_TURN_DURATION".into(), value.to_string());
+    }
+    if let Some(value) = resolve_session_title(record.display_name.as_deref(), &record.name) {
+        policy_env.insert(SESSION_TITLE_ENV_VAR.into(), value);
+    }
+    if let Some(value) =
+        crate::managed_agents::spawn_hash::effective_team_instructions(record, teams)
+    {
+        policy_env.insert("BUZZ_ACP_TEAM_INSTRUCTIONS".into(), value);
+    }
+
+    serde_json::json!({
+        "command": descriptor.command,
+        "args": descriptor.args,
+        "env": descriptor.env,
+        "policy_env": policy_env,
+        "owner_pubkey": owner_pubkey,
+    })
+}
+
+pub(super) fn ensure_remote_provider_supported(provider: Option<&str>) -> Result<(), String> {
+    if provider.map(str::trim) == Some(crate::managed_agents::RELAY_MESH_PROVIDER_ID) {
+        return Err(
+            "shared-compute agents cannot be deployed remotely because the mesh endpoint is local to the desktop"
+                .to_string(),
+        );
+    }
+    Ok(())
+}
+
 /// Build the standard agent JSON payload for provider deploy calls.
-///
-/// Like local spawn, provider deploy re-reads live persona env vars and
-/// structured model/provider so remote agents receive current credentials
-/// and the same authoritative values that local spawn derives from
-/// `runtime_metadata_env_vars`. The only field still pinned is
-/// `agent_command`/`agent_args` — those were captured at create time.
-/// The only read-time resolution is `relay_url`: a blank pin resolves to
-/// the active workspace relay here, matching the create-path contract.
-///
-/// Fails closed when the private key is unavailable (keyring outage leaves
-/// it empty after hydration): without this guard a provider deploy would
-/// serialize `"private_key_nsec": ""` and launch the agent with no
-/// identity — the same hazard the local spawn path refuses via
-/// `spawn_key_refusal`.
 pub(super) fn build_deploy_payload(
     app: &AppHandle,
     state: &AppState,
     record: &ManagedAgentRecord,
 ) -> Result<serde_json::Value, String> {
-    // Fails closed when the private key is unavailable — same guard as local
-    // spawn. Without this, a keyring outage would serialize `"private_key_nsec": ""`
-    // and launch the agent with no identity.
     if let Some(err) = crate::managed_agents::spawn_key_refusal(record) {
         return Err(err);
     }
 
-    // Merge global + persona + agent env_vars for provider deploy — the same
-    // live-persona-under-overrides semantics as local spawn. Global env vars
-    // are the lowest user-settable layer: global < persona < agent (last-wins
-    // on key collision). Without this, provider-backed agents wouldn't receive
-    // credentials saved on the persona or the agent itself.
-    let global_config = crate::managed_agents::load_global_agent_config(app).unwrap_or_default();
-    let global_env = global_config.env_vars.clone();
-    let persona_env =
-        crate::managed_agents::resolve_persona_env(app, record.persona_id.as_deref())?;
-    // Merge: global < persona (persona wins over global).
-    let global_persona_merged = crate::managed_agents::merged_user_env(&global_env, &persona_env);
-    // Merge: global+persona < agent (agent wins over everything).
-    let merged_env =
-        crate::managed_agents::merged_user_env(&global_persona_merged, &record.env_vars);
-
+    let global = crate::managed_agents::load_global_agent_config(app).unwrap_or_default();
     let personas = load_personas(app).unwrap_or_default();
-    let cfg = crate::managed_agents::effective_config::resolve_effective_config(
-        record,
-        &personas,
-        &global_config,
+    let teams = crate::managed_agents::load_teams(app).unwrap_or_default();
+    let persona_env =
+        crate::managed_agents::live_persona_env(&personas, record.persona_id.as_deref());
+    let global_persona_env = crate::managed_agents::merged_user_env(&global.env_vars, &persona_env);
+    let merged_user_env =
+        crate::managed_agents::merged_user_env(&global_persona_env, &record.env_vars);
+    let effective = crate::managed_agents::effective_config::resolve_effective_config(
+        record, &personas, &global,
     )
     .require_resolved()?;
-    let effective_model = cfg.model.value;
-    let effective_provider = cfg.provider.value;
-    let effective_prompt = cfg.system_prompt.value;
+
+    ensure_remote_provider_supported(effective.provider.value.as_deref())?;
+
+    let descriptor =
+        crate::managed_agents::resolve_effective_harness_descriptor(record, &personas, &global)
+            .map_err(|error| crate::managed_agents::user_facing_harness_error(&error))?;
+    let owner_pubkey = super::workspace_owner_hex(state)?;
+    let launch = build_launch_block(
+        record,
+        &descriptor,
+        &teams,
+        effective.system_prompt.value.as_deref(),
+        effective.model.value.as_deref(),
+        &owner_pubkey,
+    );
 
     Ok(deploy_payload_json(
         record,
@@ -95,23 +144,24 @@ pub(super) fn build_deploy_payload(
             &record.relay_url,
             &relay_ws_url_with_override(state),
         ),
-        effective_model,
-        effective_provider,
-        effective_prompt,
-        merged_env,
+        effective.model.value,
+        effective.provider.value,
+        effective.system_prompt.value,
+        merged_user_env,
+        launch,
     ))
 }
 
-/// Pure serialization half of [`build_deploy_payload`] — every field the
-/// provider harness receives is deliberately listed here, so payload
-/// completeness is testable without an `AppHandle`.
+/// Pure serialization half of [`build_deploy_payload`]. Legacy top-level fields
+/// remain for display/bookkeeping; providers execute the resolved `launch` block.
 pub(super) fn deploy_payload_json(
     record: &ManagedAgentRecord,
     relay_url: String,
     effective_model: Option<String>,
     effective_provider: Option<String>,
     effective_prompt: Option<String>,
-    merged_env: std::collections::BTreeMap<String, String>,
+    merged_env: BTreeMap<String, String>,
+    launch: serde_json::Value,
 ) -> serde_json::Value {
     serde_json::json!({
         "name": &record.name,
@@ -130,5 +180,81 @@ pub(super) fn deploy_payload_json(
         "respond_to": record.respond_to,
         "respond_to_allowlist": &record.respond_to_allowlist,
         "env_vars": merged_env,
+        "launch": launch,
     })
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::managed_agents::{readiness::EffectiveHarnessDescriptor, RespondTo, TeamRecord};
+
+    fn record() -> ManagedAgentRecord {
+        serde_json::from_value(serde_json::json!({
+            "pubkey": "abcd1234",
+            "name": "agent-handle",
+            "display_name": "Agent\u{0000} Name",
+            "private_key_nsec": "nsec1fake",
+            "relay_url": "wss://relay.example",
+            "acp_command": "buzz-acp",
+            "agent_command": "goose",
+            "agent_args": [],
+            "mcp_command": "",
+            "turn_timeout_seconds": 320,
+            "idle_timeout_seconds": 17,
+            "max_turn_duration_seconds": 23,
+            "parallelism": 4,
+            "respond_to": RespondTo::OwnerOnly,
+            "respond_to_allowlist": [],
+            "team_id": "team-1",
+            "created_at": "2026-01-01T00:00:00Z",
+            "updated_at": "2026-01-01T00:00:00Z"
+        }))
+        .unwrap()
+    }
+
+    #[test]
+    fn launch_block_preserves_descriptor_and_spawn_policy() {
+        let record = record();
+        let descriptor = EffectiveHarnessDescriptor {
+            command: "goose".into(),
+            args: vec!["acp".into()],
+            env: BTreeMap::from([
+                ("GOOSE_MODE".into(), "custom".into()),
+                ("SECRET_FROM_PERSONA".into(), "secret".into()),
+            ]),
+        };
+        let teams: Vec<TeamRecord> = serde_json::from_value(serde_json::json!([{
+            "id": "team-1", "name": "Team", "instructions": "Coordinate", "persona_ids": [], "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"
+        }])).unwrap();
+
+        let launch = build_launch_block(
+            &record,
+            &descriptor,
+            &teams,
+            Some("prompt"),
+            Some("model"),
+            "owner-hex",
+        );
+
+        assert_eq!(launch["command"], "goose");
+        assert_eq!(launch["args"], serde_json::json!(["acp"]));
+        assert_eq!(launch["env"]["GOOSE_MODE"], "custom");
+        // policy_env is applied first, so this default remains separate from
+        // the descriptor value that wins in launch.env.
+        assert_eq!(launch["policy_env"]["GOOSE_MODE"], "auto");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_LAZY_POOL"], "true");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_RELAY_OBSERVER"], "true");
+        assert_eq!(
+            launch["policy_env"]["BUZZ_ACP_TEAM_INSTRUCTIONS"],
+            "Coordinate"
+        );
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_SESSION_TITLE"], "Agent Name");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_SYSTEM_PROMPT"], "prompt");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_MODEL"], "model");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_IDLE_TIMEOUT"], "17");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_MAX_TURN_DURATION"], "23");
+        assert_eq!(launch["policy_env"]["BUZZ_ACP_AGENTS"], "4");
+        assert_eq!(launch["owner_pubkey"], "owner-hex");
+    }
+}
diff --git a/desktop/src-tauri/src/commands/agents_tests.rs b/desktop/src-tauri/src/commands/agents_tests.rs
index 03389d1d18..df135298c4 100644
--- a/desktop/src-tauri/src/commands/agents_tests.rs
+++ b/desktop/src-tauri/src/commands/agents_tests.rs
@@ -263,6 +263,19 @@ fn normalize_relay_mesh_trims_and_preserves_valid_config() {
     );
 }
 
+#[test]
+fn deploy_refuses_resolved_relay_mesh_provider_with_padding() {
+    let record = bare_agent_record(Some("p1"), None, None);
+    let personas = vec![persona_record("p1", None, Some("  relay-mesh  "))];
+    let global = crate::managed_agents::GlobalAgentConfig::default();
+
+    let (_, provider) = resolve_deploy_model_provider(&record, &personas, &global);
+    let error = ensure_remote_provider_supported(provider.as_deref())
+        .expect_err("resolved shared-compute provider must not deploy remotely");
+
+    assert!(error.contains("cannot be deployed remotely"), "{error}");
+}
+
 #[test]
 fn created_avatar_prefers_explicit_input() {
     let resolved = resolve_created_avatar_url(
@@ -398,50 +411,93 @@ fn legacy_avatar_empty_when_nothing_resolves() {
 
 // ── Provider deploy payload completeness ─────────────────────────────────────
 
-/// Regression (PR #1667 review, Thufir): the provider deploy payload must
-/// carry every behavioral field the local spawn path applies — a field
-/// missing here silently strips it from provider-backed agents.
+/// The shared provider fixture is the contract arbiter: it must be the exact
+/// richest deploy request produced by the real desktop serializers.
 #[test]
-fn deploy_payload_carries_the_full_behavioral_quad() {
-    let allow = "a".repeat(64);
-    let record: ManagedAgentRecord = serde_json::from_str(&format!(
-        r#"{{
-            "pubkey": "abcd1234",
-            "name": "test-agent",
-            "private_key_nsec": "nsec1fake",
-            "relay_url": "wss://localhost:3000",
-            "acp_command": "buzz-acp",
-            "agent_command": "goose",
-            "agent_args": [],
-            "mcp_command": "",
-            "turn_timeout_seconds": 320,
-            "system_prompt": null,
-            "parallelism": 4,
-            "respond_to": "allowlist",
-            "respond_to_allowlist": ["{allow}"],
-            "created_at": "2026-01-01T00:00:00Z",
-            "updated_at": "2026-01-01T00:00:00Z",
-            "last_started_at": null,
-            "last_stopped_at": null,
-            "last_exit_code": null,
-            "last_error": null
-        }}"#
-    ))
-    .expect("sample record");
-
-    let payload = deploy_payload_json(
+fn deploy_payload_matches_the_shared_full_launch_fixture() {
+    let fixture_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join(
+        "../../crates/buzz-backend-kubernetes/tests/fixtures/provider-wire/deploy-full-launch.request.json",
+    );
+    let fixture: serde_json::Value = serde_json::from_str(
+        &std::fs::read_to_string(&fixture_path)
+            .unwrap_or_else(|error| panic!("read {}: {error}", fixture_path.display())),
+    )
+    .expect("parse shared provider fixture");
+    let record: ManagedAgentRecord = serde_json::from_value(serde_json::json!({
+        "pubkey": "abcd1234",
+        "name": "worker",
+        "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+        "relay_url": "wss://localhost:3000",
+        "auth_tag": "tag-1",
+        "acp_command": "buzz-acp",
+        "agent_command": "goose",
+        "runtime": "goose",
+        "model": "gpt-5",
+        "provider": "openai",
+        "env_vars": {"USER_KEY": "user-value"},
+        "agent_args": [],
+        "mcp_command": "",
+        "turn_timeout_seconds": 300,
+        "system_prompt": null,
+        "idle_timeout_seconds": null,
+        "max_turn_duration_seconds": null,
+        "parallelism": 10,
+        "respond_to": "allowlist",
+        "respond_to_allowlist": ["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"],
+        "created_at": "2026-01-01T00:00:00Z",
+        "updated_at": "2026-01-01T00:00:00Z"
+    }))
+    .expect("fixture source record");
+    let descriptor = crate::managed_agents::resolve_effective_harness_descriptor(
         &record,
-        "wss://relay.example".to_string(),
-        Some("gpt-x".to_string()),
-        Some("openai".to_string()),
+        &[],
+        &crate::managed_agents::GlobalAgentConfig::default(),
+    )
+    .expect("resolve fixture source record descriptor");
+    let launch = super::deploy::build_launch_block(
+        &record,
+        &descriptor,
+        &[],
         None,
-        std::collections::BTreeMap::new(),
+        Some("gpt-5"),
+        "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    );
+    let agent = deploy_payload_json(
+        &record,
+        "wss://relay.example".into(),
+        Some("gpt-5".into()),
+        Some("openai".into()),
+        None,
+        std::collections::BTreeMap::from([("USER_KEY".into(), "user-value".into())]),
+        launch,
     );
 
-    assert_eq!(payload["parallelism"], 4);
-    assert_eq!(payload["respond_to"], "allowlist");
-    assert_eq!(payload["respond_to_allowlist"][0], "a".repeat(64));
-    assert_eq!(payload["model"], "gpt-x");
-    assert_eq!(payload["provider"], "openai");
-    assert_eq!(payload["relay_url"], "wss://relay.example");
+    assert_eq!(
+        agent, fixture["agent"],
+        "desktop payload drifted from the shared provider fixture"
+    );
+}
+
+#[test]
+fn tauri_platform_configs_bundle_kubernetes_only_on_supported_hosts() {
+    use tauri_utils::{config::parse::read_from, platform::Target};
+
+    let config_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+    for (target, expected) in [
+        (Target::MacOS, true),
+        (Target::Linux, true),
+        (Target::Windows, false),
+    ] {
+        let (config, paths) = read_from(target, config_root).expect("read Tauri config");
+        let external_bins = config["bundle"]["externalBin"]
+            .as_array()
+            .expect("bundle.externalBin array");
+        let has_kubernetes = external_bins
+            .iter()
+            .any(|value| value == "binaries/buzz-backend-kubernetes");
+        assert_eq!(
+            has_kubernetes, expected,
+            "unexpected Kubernetes externalBin for {target}; merged {paths:?}"
+        );
+    }
 }
diff --git a/desktop/src-tauri/src/commands/export_util.rs b/desktop/src-tauri/src/commands/export_util.rs
index ded14679c1..e12cbd19e1 100644
--- a/desktop/src-tauri/src/commands/export_util.rs
+++ b/desktop/src-tauri/src/commands/export_util.rs
@@ -35,8 +35,8 @@ pub async fn pick_save_path(
 /// user cancelled the dialog.
 ///
 /// NOT for secrets: the write is plain `std::fs::write` (no atomic commit, no
-/// 0o600). Secret exports go through `pick_save_path` +
-/// `key_backup::write_backup_file`.
+/// 0o600). Secret exports go through `pick_save_path` and a dedicated
+/// secret-file writer such as `key_backup::write_portable_backup_file`.
 pub async fn save_bytes_with_dialog(
     app: &AppHandle,
     suggested_filename: &str,
diff --git a/desktop/src-tauri/src/commands/identity.rs b/desktop/src-tauri/src/commands/identity.rs
index 33ecf3cfca..bddf2e725a 100644
--- a/desktop/src-tauri/src/commands/identity.rs
+++ b/desktop/src-tauri/src/commands/identity.rs
@@ -297,9 +297,10 @@ pub async fn verify_ncryptsec_backup(
 /// Save a portable copy of an `ncryptsec1…` backup to a user-chosen path.
 ///
 /// The input must parse as a structurally valid NIP-49 payload. The dialog is
-/// selection-only; the write uses secret-file semantics (atomic + 0o600).
-/// Never mutates canonical app state. Returns the chosen path, or `None` when
-/// the user cancelled.
+/// selection-only; the write uses the exact save-panel-authorized path with
+/// owner-only permissions, sync, and reread verification. Existing files are
+/// preserved rather than truncated. Never mutates canonical app state. Returns
+/// the chosen path, or `None` when the user cancelled.
 #[tauri::command]
 pub async fn save_ncryptsec_copy(
     ncryptsec: String,
@@ -324,7 +325,7 @@ pub async fn save_ncryptsec_copy(
 
     let dest_for_write = dest.clone();
     tokio::task::spawn_blocking(move || {
-        crate::key_backup::write_backup_file(&dest_for_write, &normalized)
+        crate::key_backup::write_portable_backup_file(&dest_for_write, &normalized)
     })
     .await
     .map_err(|e| format!("spawn_blocking failed: {e}"))??;
diff --git a/desktop/src-tauri/src/commands/media_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..29a5c35e6a
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/card.rs
@@ -0,0 +1,999 @@
+//! `mint_agent_card` / `save_agent_card` Tauri commands — Agent Trading Cards.
+//!
+//! Mints a collectible trading-card PNG for an agent via one OpenAI Responses
+//! API call (designer model + native `image_generation` tool), then embeds the
+//! agent's `buzz_agent_snapshot` manifest through the existing snapshot
+//! encoder so the card IS an importable `.agent.png`.
+//!
+//! Boundary rules (agreed with Wren, buzz-agent-trading-cards thread):
+//! - Snapshot construction/injection reuses `agent_snapshot.rs` — cards
+//!   inherit manifest-v1 behavior, exclusions, and size checks. No card-only
+//!   wire format exists.
+//! - Memory inclusion is opt-in and shares the export flow's semantics: the
+//!   same three levels (`none`/`core`/`everything`), the same owner-gated
+//!   `get_agent_memory` fetch, and a memory source DERIVED from the resolved
+//!   instance (never caller-supplied), so cross-agent memory pairing is
+//!   structurally impossible. The default is `none`; the encoder still
+//!   rejects `none` + entries.
+//! - The 10 MiB `.agent.png` ceiling is enforced on the FINAL bytes (after
+//!   resize + chunk injection) via `validate_snapshot_encode_size`.
+//! - Round-trip verification decodes the final bytes and compares the logical
+//!   manifest before anything is returned to the frontend.
+//! - The API key is resolved through the same env layering the agent runtime
+//!   uses (global config < persona < agent record) and never leaves Rust.
+//!   It is never logged.
+
+use base64::{engine::general_purpose::STANDARD, Engine as _};
+use serde::{Deserialize, Serialize};
+use tauri::{AppHandle, State};
+
+use super::super::export_util::save_bytes_with_dialog;
+use super::snapshot::{
+    memory_entries_from_listing, parse_memory_level, resolve_from_lists,
+    validate_snapshot_encode_size,
+};
+use crate::{
+    app_state::AppState,
+    commands::engrams::get_agent_memory,
+    managed_agents::{
+        agent_snapshot::{
+            build_snapshot, decode_avatar_data_url, decode_snapshot_png, encode_snapshot_png,
+            extract_chunk_payload_png, MemoryLevel,
+        },
+        agent_snapshot_envelope::{
+            decrypt_envelope, encode_locked_snapshot_png, parse_chunk_payload, ChunkPayload,
+        },
+        load_agent_definitions, load_global_agent_config, load_managed_agents, load_personas,
+        save_global_agent_config, validate_global_config,
+    },
+};
+
+/// The Buzz card frame template — Tyler's gold-honeycomb base. Generation
+/// input only: it never participates in the snapshot manifest, PNG chunk,
+/// import decoder, or attachment validation. Embedded at compile time for
+/// deterministic packaging (see `card_template_decodes` test).
+const CARD_TEMPLATE_PNG: &[u8] = include_bytes!("../../../assets/card_template.png");
+
+/// Designer model driving copy + art direction.
+const DESIGNER_MODEL: &str = "gpt-5.6-sol";
+/// Image model invoked natively via the Responses `image_generation` tool.
+const IMAGE_MODEL: &str = "gpt-image-2";
+/// Final card width in pixels (2:3 portrait → 1500x2250).
+const CARD_WIDTH: u32 = 1500;
+/// Longest edge for the real avatar inlined into an unlocked card's manifest.
+/// Kind:0 pictures render small; 512px keeps the doubly-base64-encoded
+/// manifest chunk modest next to the 1500-wide card body.
+const MANIFEST_AVATAR_MAX_DIM: u32 = 512;
+/// Upper bound for a fetched avatar (pre-resize input to the model).
+const MAX_AVATAR_FETCH_BYTES: usize = 10 * 1024 * 1024;
+/// One mint is a single long API call (~2–3 minutes observed).
+const MINT_TIMEOUT_SECS: u64 = 600;
+
+/// Error prefix the frontend matches to route the user to provider settings
+/// instead of showing a raw failure.
+pub(crate) const NO_KEY_ERROR_PREFIX: &str = "NO_OPENAI_KEY:";
+
+/// Wire shape returned by `mint_agent_card`.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MintedCard {
+    /// Final `.agent.png` bytes (chunk-injected, round-trip verified),
+    /// base64-encoded for the IPC boundary.
+    pub card_png_base64: String,
+    /// Suggested filename, e.g. `eva.agent.png`.
+    pub file_name: String,
+    /// Designer commentary emitted alongside the image (may be empty).
+    pub designer_notes: String,
+    /// True when the embedded snapshot is NIP-44-encrypted to the
+    /// (owner, agent) pair — only their nsecs can import this card.
+    pub locked: bool,
+    /// How much memory is embedded in the card's snapshot ("none"/"core"/
+    /// "everything"). The viewer's import disclosure depends on this.
+    pub memory_level: MemoryLevel,
+}
+
+// ── Card archive ──────────────────────────────────────────────────────────────
+
+/// Sidecar metadata for one archived card PNG. Stored as `<stem>.json` next
+/// to `<stem>.agent.png` in the cards dir — two plain files per mint, no
+/// shared index to corrupt. Listing scans sidecars; a card whose PNG is
+/// missing is skipped rather than failing the whole list.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ArchivedCardMeta {
+    /// Unique on-disk PNG file name within the cards dir.
+    pub stored_file_name: String,
+    /// Suggested save-as name, e.g. `eva.agent.png`.
+    pub file_name: String,
+    /// The id the card was minted for (instance pubkey or definition slug).
+    pub agent_id: String,
+    pub agent_name: String,
+    pub designer_notes: String,
+    pub locked: bool,
+    /// Memory embedded in this card's snapshot. Defaults to `None` when the
+    /// sidecar predates the field — every pre-field mint was minted with
+    /// `MemoryLevel::None` (it was structural), so the default is honest.
+    #[serde(default)]
+    pub memory_level: MemoryLevel,
+    /// ISO-8601 mint timestamp.
+    pub minted_at: String,
+    /// Small JPEG preview for gallery grids, base64. Populated by
+    /// `list_agent_cards` from the sidecar thumb file — never stored in the
+    /// JSON sidecar itself.
+    #[serde(default, skip_deserializing)]
+    pub thumb_jpeg_base64: Option<String>,
+}
+
+fn cards_dir(app: &AppHandle) -> Result<std::path::PathBuf, String> {
+    let dir = crate::managed_agents::managed_agents_base_dir(app)?.join("cards");
+    std::fs::create_dir_all(&dir).map_err(|e| format!("failed to create cards dir: {e}"))?;
+    Ok(dir)
+}
+
+/// Persist a freshly minted card to the archive. Failures are surfaced to the
+/// caller (which logs and continues) — an archive write must never fail a
+/// mint the user already paid for.
+fn archive_minted_card(
+    app: &AppHandle,
+    agent_id: &str,
+    agent_name: &str,
+    card: &MintedCard,
+    bytes: &[u8],
+) -> Result<ArchivedCardMeta, String> {
+    let dir = cards_dir(app)?;
+    let stem = format!(
+        "{}-{}",
+        crate::util::slugify(agent_name, "agent", 50),
+        uuid::Uuid::new_v4()
+    );
+    let stored_file_name = format!("{stem}.agent.png");
+    let meta = ArchivedCardMeta {
+        stored_file_name: stored_file_name.clone(),
+        file_name: card.file_name.clone(),
+        agent_id: agent_id.to_string(),
+        agent_name: agent_name.to_string(),
+        designer_notes: card.designer_notes.clone(),
+        locked: card.locked,
+        memory_level: card.memory_level,
+        minted_at: crate::util::now_iso(),
+        thumb_jpeg_base64: None,
+    };
+    // PNG first, sidecar second: a crash between the two leaves an orphaned
+    // PNG (invisible to the list), never a sidecar pointing at nothing.
+    std::fs::write(dir.join(&stored_file_name), bytes)
+        .map_err(|e| format!("failed to write archived card: {e}"))?;
+    let meta_json = serde_json::to_string_pretty(&meta)
+        .map_err(|e| format!("failed to serialize card metadata: {e}"))?;
+    std::fs::write(dir.join(format!("{stem}.json")), meta_json)
+        .map_err(|e| format!("failed to write card metadata: {e}"))?;
+    // Thumb last and best-effort: the gallery grid falls back to lazy
+    // full-card loading for a card whose thumb is missing.
+    if let Ok(thumb) = encode_card_thumb(bytes) {
+        let _ = std::fs::write(dir.join(format!("{stem}.thumb.jpg")), thumb);
+    }
+    Ok(meta)
+}
+
+/// Downscale card PNG bytes to a small JPEG for gallery grids. The full card
+/// is ~1500x2250 PNG (megabytes); shipping that per card over IPC just to
+/// draw a grid tile is waste.
+fn encode_card_thumb(bytes: &[u8]) -> Result<Vec<u8>, String> {
+    const THUMB_WIDTH: u32 = 300;
+    let img = image::load_from_memory(bytes).map_err(|e| format!("thumb decode: {e}"))?;
+    let scale = THUMB_WIDTH as f64 / img.width() as f64;
+    let thumb = img.resize(
+        THUMB_WIDTH,
+        (img.height() as f64 * scale).round().max(1.0) as u32,
+        image::imageops::FilterType::Triangle,
+    );
+    let mut out = Vec::new();
+    // JPEG has no alpha; cards are opaque, so flatten unconditionally.
+    let rgb = image::DynamicImage::ImageRgb8(thumb.to_rgb8());
+    rgb.write_to(
+        &mut std::io::Cursor::new(&mut out),
+        image::ImageFormat::Jpeg,
+    )
+    .map_err(|e| format!("thumb encode: {e}"))?;
+    Ok(out)
+}
+
+/// Reject any archive file name that could escape the cards dir or name a
+/// non-archive file. Archive names are generated by `archive_minted_card`
+/// (slug + UUID), so a strict shape check loses nothing legitimate.
+fn validate_archive_file_name(stored_file_name: &str) -> Result<(), String> {
+    let valid = stored_file_name.ends_with(".agent.png")
+        && !stored_file_name.contains(['/', '\\'])
+        && !stored_file_name.contains("..");
+    if !valid {
+        return Err("Invalid archived card file name.".to_string());
+    }
+    Ok(())
+}
+
+/// List all archived cards, newest first.
+#[tauri::command]
+pub fn list_agent_cards(app: AppHandle) -> Result<Vec<ArchivedCardMeta>, String> {
+    let dir = cards_dir(&app)?;
+    let entries = std::fs::read_dir(&dir).map_err(|e| format!("failed to read cards dir: {e}"))?;
+    let mut cards = Vec::new();
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if path.extension().and_then(|e| e.to_str()) != Some("json") {
+            continue;
+        }
+        let Ok(content) = std::fs::read_to_string(&path) else {
+            continue;
+        };
+        let Ok(meta) = serde_json::from_str::<ArchivedCardMeta>(&content) else {
+            // A malformed sidecar hides one card, never the archive.
+            eprintln!(
+                "buzz-desktop: card-archive: skipping malformed sidecar {}",
+                path.display()
+            );
+            continue;
+        };
+        let mut meta = meta;
+        if validate_archive_file_name(&meta.stored_file_name).is_ok()
+            && dir.join(&meta.stored_file_name).is_file()
+        {
+            // Attach the pre-rendered grid thumb when present (best-effort).
+            if let Some(stem) = path.file_stem().and_then(|s| s.to_str()) {
+                meta.thumb_jpeg_base64 = std::fs::read(dir.join(format!("{stem}.thumb.jpg")))
+                    .ok()
+                    .map(|b| STANDARD.encode(&b));
+            }
+            cards.push(meta);
+        }
+    }
+    // ISO-8601 sorts lexicographically; newest first.
+    cards.sort_by(|a, b| b.minted_at.cmp(&a.minted_at));
+    Ok(cards)
+}
+
+/// Load one archived card's PNG bytes as base64, keyed by its stored file
+/// name (as returned by `list_agent_cards`).
+#[tauri::command]
+pub fn load_agent_card(stored_file_name: String, app: AppHandle) -> Result<String, String> {
+    validate_archive_file_name(&stored_file_name)?;
+    let bytes = std::fs::read(cards_dir(&app)?.join(&stored_file_name))
+        .map_err(|e| format!("failed to read archived card: {e}"))?;
+    Ok(STANDARD.encode(&bytes))
+}
+
+// ── Key resolution ────────────────────────────────────────────────────────────
+
+/// Pure layering: global env < persona env < agent record env, then the
+/// process environment as a development fallback. Returns the first
+/// non-empty value for `key`.
+pub(crate) fn resolve_env_from_layers(
+    key: &str,
+    global_env: &std::collections::BTreeMap<String, String>,
+    persona_env: &std::collections::BTreeMap<String, String>,
+    record_env: &std::collections::BTreeMap<String, String>,
+    process_value: Option<String>,
+) -> Option<String> {
+    for layer in [record_env, persona_env, global_env] {
+        if let Some(v) = layer.get(key) {
+            let v = v.trim();
+            if !v.is_empty() {
+                return Some(v.to_string());
+            }
+        }
+    }
+    process_value.filter(|k| !k.trim().is_empty())
+}
+
+/// Pure classification: same four env inputs as `resolve_env_from_layers`,
+/// returns which layer supplies `OPENAI_API_KEY` (agent > persona > global >
+/// process > none).
+pub(crate) fn resolve_key_layer(
+    global_env: &std::collections::BTreeMap<String, String>,
+    persona_env: &std::collections::BTreeMap<String, String>,
+    record_env: &std::collections::BTreeMap<String, String>,
+    process_value: Option<String>,
+) -> &'static str {
+    let key = "OPENAI_API_KEY";
+    let nonempty = |m: &std::collections::BTreeMap<String, String>| {
+        m.get(key).is_some_and(|v| !v.trim().is_empty())
+    };
+    if nonempty(record_env) {
+        return "agent";
+    }
+    if nonempty(persona_env) {
+        return "persona";
+    }
+    if nonempty(global_env) {
+        return "global";
+    }
+    let proc = process_value.as_deref().unwrap_or("");
+    if !proc.trim().is_empty() {
+        return "process";
+    }
+    "none"
+}
+
+/// The Responses endpoint to post mints to. `OPENAI_BASE_URL` (same env
+/// layering as the key) overrides the default host, supporting endpoints and
+/// proxies that speak the OpenAI Responses shape with Bearer auth. Azure
+/// OpenAI is NOT covered by this override alone — it uses its own URL scheme
+/// and `api-key` auth header, which would need a real driver.
+pub(crate) fn responses_url(base_url: Option<String>) -> String {
+    let base = base_url.unwrap_or_else(|| "https://api.openai.com/v1".to_string());
+    format!("{}/responses", base.trim_end_matches('/'))
+}
+
+// ── Prompt construction ───────────────────────────────────────────────────────
+
+/// Build the designer instructions. Pure so tests can pin the contract:
+/// style-match-the-avatar is DEFAULT behavior; owner directions (art AND
+/// card text) take primacy over those style defaults, but never over the
+/// fixed contract (frame identity, geometry, text fidelity).
+pub(crate) fn build_card_instructions(
+    agent_name: &str,
+    persona_notes: &str,
+    style_notes: &str,
+) -> String {
+    let owner_directions = if style_notes.trim().is_empty() {
+        String::new()
+    } else {
+        format!(
+            "\nOWNER'S DIRECTIONS — these override the default art-style and copy guidance \
+             below wherever they conflict (they cannot change the frame, layout, or \
+             text-fidelity requirements). The owner may direct the art, the card text \
+             (type line, ability, flavor), or both:\n{style_notes}\n"
+        )
+    };
+    format!(
+        r#"You are designing one premium collectible trading card for the Buzz agent "{agent_name}".
+
+Input image 1 is the official Buzz card frame template (gold honeycomb border, dark interior, name banner top, hex badge top-right, text box lower third). Input image 2 is the agent's avatar — study its exact art style: medium, pixel grid if any, palette, shading, background motifs.
+
+Persona notes for the card copy:
+{persona_notes}
+{owner_directions}
+First, write professional trading-card copy at Magic: The Gathering editorial quality:
+- a type line (e.g. "Legendary Agent — Team Lead"),
+- ONE keyworded ability: short bolded ability name + one sentence of crisp rules text written like real MTG rules (present tense, precise, no fluff),
+- ONE italic flavor-text line, evocative and short, the kind that gets quoted.
+Where the owner's directions specify card text, use their wording within the 220-character text-box limit below (edited only for spelling; if their text exceeds the limit, condense it minimally while keeping their words and intent); invent copy only for the parts they left open.
+Keep total text-box copy under 220 characters so it renders cleanly.
+
+Then generate the finished card with the image tool, exactly 1024x1536 portrait:
+- The frame must follow input image 1 faithfully: same gold honeycomb border, same layout, honey drip detail.
+- Default art style: match input image 2's art style EXACTLY — same medium, same pixel density if pixel art, same palette, same background honeycomb-lattice sky. It must look like the same artist drew a larger scene: the character in a confident pose, conjuring glowing golden hexagons. The owner's directions above override any of this default styling where they conflict.
+- Name banner: "{agent_name}" plus the type line beneath it in smaller type.
+- Text box: the ability name in bold, rules text in regular, then the flavor line in italics, cleanly typeset like a real MTG card — professional kerning, no misspellings, hyphenate nothing.
+- Top-right hex badge: one small emblem of your choice, no text.
+Render all text with perfect fidelity."#
+    )
+}
+
+/// Encode raw image bytes as a `data:image/png;base64,` URL, downscaling to
+/// `max_dim` on the longest edge so request payloads stay small.
+fn image_data_url(bytes: &[u8], max_dim: u32) -> Result<String, String> {
+    Ok(format!(
+        "data:image/png;base64,{}",
+        STANDARD.encode(png_bytes_resized(bytes, max_dim)?)
+    ))
+}
+
+/// Re-encode an image as PNG, downscaling so neither side exceeds `max_dim`.
+fn png_bytes_resized(bytes: &[u8], max_dim: u32) -> Result<Vec<u8>, String> {
+    let img = image::load_from_memory(bytes).map_err(|e| format!("Failed to decode image: {e}"))?;
+    let img = if img.width().max(img.height()) > max_dim {
+        img.resize(max_dim, max_dim, image::imageops::FilterType::Lanczos3)
+    } else {
+        img
+    };
+    let mut png = Vec::new();
+    img.write_to(&mut std::io::Cursor::new(&mut png), image::ImageFormat::Png)
+        .map_err(|e| format!("Failed to encode image: {e}"))?;
+    Ok(png)
+}
+
+// ── Response parsing ──────────────────────────────────────────────────────────
+
+/// Extract the generated image (base64) and any designer text from a
+/// Responses API payload. Pure for testability.
+pub(crate) fn extract_card_output(resp: &serde_json::Value) -> Result<(String, String), String> {
+    let output = resp
+        .get("output")
+        .and_then(|o| o.as_array())
+        .ok_or_else(|| "Responses payload has no output array".to_string())?;
+
+    let mut image_b64 = None;
+    let mut notes = Vec::new();
+    for item in output {
+        match item.get("type").and_then(|t| t.as_str()) {
+            Some("image_generation_call") => {
+                if let Some(result) = item.get("result").and_then(|r| r.as_str()) {
+                    image_b64 = Some(result.to_string());
+                }
+            }
+            Some("message") => {
+                if let Some(content) = item.get("content").and_then(|c| c.as_array()) {
+                    for c in content {
+                        if c.get("type").and_then(|t| t.as_str()) == Some("output_text") {
+                            if let Some(text) = c.get("text").and_then(|t| t.as_str()) {
+                                notes.push(text.to_string());
+                            }
+                        }
+                    }
+                }
+            }
+            _ => {}
+        }
+    }
+
+    let image_b64 = image_b64.ok_or_else(|| {
+        let types: Vec<&str> = output
+            .iter()
+            .filter_map(|i| i.get("type").and_then(|t| t.as_str()))
+            .collect();
+        format!("No image in Responses output (item types: {types:?})")
+    })?;
+    Ok((image_b64, notes.join("\n")))
+}
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+
+/// Save an `OPENAI_API_KEY` into the global Agent Defaults env for card
+/// minting — a narrow seam with deliberately different semantics from the
+/// general `set_global_agent_config`:
+///
+/// - **No agent restarts.** The general command stops/restarts every running
+///   local agent whose effective env changes, because agent env is baked at
+///   spawn time. The mint command re-reads the config from disk on every
+///   mint, so minting needs no restart — and a card setup must never disrupt
+///   running agents as a side effect. Agents pick the key up naturally on
+///   their next (re)start.
+/// - **Read-modify-write of the latest on-disk config.** The config is
+///   re-read immediately before the single-key insert + write (under the
+///   managed-agents store lock, which serializes it against the other card
+///   and agent-store commands), so a settings save that landed after this
+///   dialog opened is not clobbered with a stale dialog-open snapshot.
+///   (The general settings editor performs its own whole-config write; as
+///   today, the last writer wins between the two surfaces.)
+///
+/// Standard global-config validation still applies (POSIX key shape,
+/// reserved-key reject, size caps) — this is not a validation bypass.
+#[tauri::command]
+pub fn card_mint_save_openai_key(
+    key: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let key = key.trim().to_string();
+    if key.is_empty() {
+        return Err("API key cannot be empty.".to_string());
+    }
+
+    let _store_guard = state
+        .managed_agents_store_lock
+        .lock()
+        .map_err(|e| e.to_string())?;
+
+    let mut config = load_global_agent_config(&app)?;
+    config.env_vars.insert("OPENAI_API_KEY".to_string(), key);
+    validate_global_config(&config)?;
+    save_global_agent_config(&app, &config)
+}
+
+/// Report which env layer resolves the OpenAI key for a card mint of agent
+/// `id` — same layering as `mint_agent_card`. Delegates to `resolve_key_layer`
+/// for the classification; see that helper for the return-value contract.
+#[tauri::command]
+pub fn card_mint_key_status(
+    id: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<String, String> {
+    let _store_guard = state
+        .managed_agents_store_lock
+        .lock()
+        .map_err(|e| e.to_string())?;
+
+    let instances = load_managed_agents(&app)?;
+    let definitions = load_agent_definitions(&app)?;
+    let (record, _) = resolve_from_lists(&id, &instances, &definitions)?;
+
+    let global = load_global_agent_config(&app).unwrap_or_default();
+    let personas = load_personas(&app).unwrap_or_default();
+    let persona_env = record
+        .persona_id
+        .as_deref()
+        .and_then(|pid| personas.iter().find(|p| p.id == pid))
+        .map(|p| p.env_vars.clone())
+        .unwrap_or_default();
+
+    Ok(resolve_key_layer(
+        &global.env_vars,
+        &persona_env,
+        &record.env_vars,
+        std::env::var("OPENAI_API_KEY").ok(),
+    )
+    .to_string())
+}
+
+/// Mint a trading card for the agent identified by `id` (instance pubkey,
+/// instance slug, or definition slug — same resolution as snapshot export).
+///
+/// When `lock` is true the embedded manifest is NIP-44-encrypted to the
+/// (owner, agent) pair per the locked-envelope contract — this requires a
+/// linked agent instance (the second key endpoint); bare definitions cannot
+/// be locked.
+///
+/// When `memory_level` is `"core"` or `"everything"`, the owner's decrypted
+/// memory for the agent is embedded in the manifest — same levels and fetch
+/// as snapshot export. The memory source is always the resolved instance
+/// itself (derived, never caller-supplied), so it requires a linked instance;
+/// bare definitions can only mint `"none"` (the default).
+///
+/// Returns the final, chunk-injected, round-trip-verified `.agent.png` bytes.
+/// Reroll = call again; the command holds no session state.
+#[tauri::command]
+pub async fn mint_agent_card(
+    id: String,
+    style_notes: Option<String>,
+    lock: Option<bool>,
+    memory_level: Option<String>,
+    app: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<MintedCard, String> {
+    let lock = lock.unwrap_or(false);
+    let memory_level = parse_memory_level(memory_level.as_deref().unwrap_or(""))?;
+    // ── Resolve the record + API key under lock ──────────────────────────────
+    let (mut record, is_definition, api_key, base_url) = {
+        let _store_guard = state
+            .managed_agents_store_lock
+            .lock()
+            .map_err(|e| e.to_string())?;
+
+        let instances = load_managed_agents(&app)?;
+        let definitions = load_agent_definitions(&app)?;
+        let (record, is_definition) =
+            resolve_from_lists(&id, &instances, &definitions).map(|(r, d)| (r.clone(), d))?;
+
+        let global = load_global_agent_config(&app).unwrap_or_default();
+        let personas = load_personas(&app).unwrap_or_default();
+        let persona_env = record
+            .persona_id
+            .as_deref()
+            .and_then(|pid| personas.iter().find(|p| p.id == pid))
+            .map(|p| p.env_vars.clone())
+            .unwrap_or_default();
+
+        let api_key = resolve_env_from_layers(
+            "OPENAI_API_KEY",
+            &global.env_vars,
+            &persona_env,
+            &record.env_vars,
+            std::env::var("OPENAI_API_KEY").ok(),
+        )
+        .ok_or_else(|| {
+            format!(
+                "{NO_KEY_ERROR_PREFIX} No OPENAI_API_KEY found. Add one in the agent's \
+                 environment variables or global agent settings to mint cards."
+            )
+        })?;
+        let base_url = resolve_env_from_layers(
+            "OPENAI_BASE_URL",
+            &global.env_vars,
+            &persona_env,
+            &record.env_vars,
+            std::env::var("OPENAI_BASE_URL").ok(),
+        );
+
+        (record, is_definition, api_key, base_url)
+    };
+
+    // ── Locking needs its two exact key endpoints up front, BEFORE the
+    //    API spend: the owner identity secret and the agent instance pubkey.
+    let lock_keys = if lock {
+        if is_definition {
+            return Err(
+                "Locked cards need a linked agent instance — this persona has never been \
+                 started, so there is no agent key to lock to."
+                    .to_string(),
+            );
+        }
+        let owner_keys = state.signing_keys()?;
+        // Same canonical check the envelope decoder enforces (incl. curve
+        // validation) — a non-point record pubkey must fail BEFORE the API
+        // spend, not at post-mint encryption.
+        let agent_pubkey = crate::managed_agents::agent_snapshot_envelope::parse_canonical_pubkey(
+            "agentPubkey",
+            &record.pubkey,
+        )
+        .map_err(|_| {
+            "Agent record has an invalid pubkey (not a canonical x-only key).".to_string()
+        })?;
+        if owner_keys.public_key() == agent_pubkey {
+            return Err("Cannot lock a card to itself: owner and agent keys match.".to_string());
+        }
+        Some((owner_keys, agent_pubkey))
+    } else {
+        None
+    };
+
+    // ── Memory needs a keyed instance, resolved up front BEFORE the API
+    //    spend — the memory source is always the resolved instance itself
+    //    (derived, never caller-supplied), so cross-agent pairing cannot be
+    //    expressed. A failed fetch fails the mint here, not after payment.
+    let memory_entries = if memory_level == MemoryLevel::None {
+        Vec::new()
+    } else {
+        if is_definition {
+            return Err(
+                "Cards with memory need a linked agent instance — this persona has never \
+                 been started, so there is no agent memory to include."
+                    .to_string(),
+            );
+        }
+        let listing = get_agent_memory(record.pubkey.clone(), app.clone(), state.clone()).await?;
+        memory_entries_from_listing(listing, memory_level)
+    };
+
+    let display_name = record
+        .display_name
+        .clone()
+        .unwrap_or_else(|| record.name.clone());
+
+    // ── Prefer the agent's own kind:0 profile picture ────────────────────────
+    // The record's `avatar_url` is a stale presentation snapshot: with
+    // agent-managed profiles the agent updates its own kind:0 `picture` and
+    // desktop reconciliation is disabled (`agent_settings.rs`), so the relay
+    // profile — not the local record — is the live source of truth for how the
+    // agent looks. Definitions have no keypair and thus no kind:0; they keep
+    // the record's avatar. A relay error fails the mint here, BEFORE the API
+    // spend (same fail-early rule as the key/memory guards above) — minting
+    // with the wrong face wastes the spend it was supposed to protect.
+    if !is_definition {
+        let relay_url = crate::relay::effective_agent_relay_url(
+            &record.relay_url,
+            &crate::relay::relay_ws_url_with_override(&state),
+        );
+        let profile = crate::relay::query_agent_profile(&state, &relay_url, &record.pubkey)
+            .await
+            .map_err(|e| format!("Could not read the agent's profile for its avatar: {e}"))?;
+        record.avatar_url = preferred_avatar_url(
+            profile.and_then(|info| info.picture),
+            record.avatar_url.take(),
+        );
+    }
+
+    // ── Resolve avatar bytes (data URL, else fetch) ──────────────────────────
+    let avatar_bytes = match record.avatar_url.as_deref() {
+        Some(url) if url.starts_with("data:") => decode_avatar_data_url(url)
+            .ok_or_else(|| "Agent avatar data URL could not be decoded.".to_string())?,
+        Some(url) if url.starts_with("http://") || url.starts_with("https://") => {
+            // Relay-hosted avatars (kind:0 pictures under the relay's /media/)
+            // may require Blossom get-auth (`require_media_get_auth`). Mint the
+            // header ONLY for same-origin URLs so the token never leaves the
+            // relay (same contract as `media_download.rs`).
+            let relay_base = crate::relay::relay_api_base_url_with_override(&state);
+            let auth = is_same_origin(url, &relay_base)
+                .then(|| crate::commands::media::mint_media_get_auth(&state, &relay_base))
+                .flatten();
+            fetch_avatar(url, auth.as_deref()).await?
+        }
+        _ => {
+            return Err(
+                "Agent has no avatar image. Set an avatar before minting a card.".to_string(),
+            )
+        }
+    };
+
+    // ── Build the manifest now (with any requested memory) so a broken agent
+    //    fails before we spend minutes on the API call. ───────────────────────
+    let manifest_avatar = manifest_avatar_bytes(
+        lock_keys.is_some(),
+        &avatar_bytes,
+        record.avatar_url.as_deref(),
+    )?;
+    let snapshot = build_snapshot(
+        &record,
+        memory_level,
+        memory_entries,
+        manifest_avatar.as_deref(),
+    );
+
+    // ── One Responses API call ───────────────────────────────────────────────
+    // For locked mints, prove the manifest (including any embedded memory)
+    // fits the NIP-44 plaintext cap BEFORE spending minutes on the API call
+    // (same fail-early rule as the memory guard above).
+    if lock_keys.is_some() {
+        let json_len =
+            crate::managed_agents::agent_snapshot::encode_snapshot_json(&snapshot)?.len();
+        if json_len > buzz_core_pkg::engram::NIP44_PLAINTEXT_MAX {
+            let hint = if memory_level == MemoryLevel::None {
+                "Reduce the avatar size or mint an unlocked card."
+            } else {
+                "Include less memory, reduce the avatar size, or mint an unlocked card."
+            };
+            return Err(format!(
+                "Agent manifest is too large to lock ({json_len} bytes; the encrypted \
+                 format caps at {}). {hint}",
+                buzz_core_pkg::engram::NIP44_PLAINTEXT_MAX
+            ));
+        }
+    }
+    let instructions = build_card_instructions(
+        &display_name,
+        snapshot.definition.system_prompt.as_deref().unwrap_or(""),
+        style_notes.as_deref().unwrap_or(""),
+    );
+    let body = serde_json::json!({
+        "model": DESIGNER_MODEL,
+        "reasoning": {"effort": "high"},
+        "instructions": "You are a senior TCG card designer and MTG rules editor.",
+        "input": [{
+            "role": "user",
+            "content": [
+                {"type": "input_text", "text": instructions},
+                {"type": "input_image", "image_url": image_data_url(CARD_TEMPLATE_PNG, 1024)?},
+                {"type": "input_image", "image_url": image_data_url(&avatar_bytes, 1024)?},
+            ],
+        }],
+        "tools": [{
+            "type": "image_generation",
+            "model": IMAGE_MODEL,
+            "quality": "high",
+            "size": "1024x1536",
+            "output_format": "png",
+        }],
+        "tool_choice": "required",
+    });
+
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(MINT_TIMEOUT_SECS))
+        .build()
+        .map_err(|e| format!("Failed to build HTTP client: {e}"))?;
+    let resp = client
+        .post(responses_url(base_url))
+        .bearer_auth(&api_key)
+        .json(&body)
+        .send()
+        .await
+        .map_err(|e| format!("Card mint request failed: {e}"))?;
+
+    let status = resp.status();
+    let payload: serde_json::Value = resp
+        .json()
+        .await
+        .map_err(|e| format!("Card mint response was not JSON: {e}"))?;
+    if !status.is_success() {
+        // Never echo the request (it embeds nothing secret, but keep the
+        // failure surface small); the OpenAI error body is safe to surface.
+        let detail = payload
+            .get("error")
+            .and_then(|e| e.get("message"))
+            .and_then(|m| m.as_str())
+            .unwrap_or("unknown error");
+        return Err(format!("Card mint failed (HTTP {status}): {detail}"));
+    }
+
+    let (image_b64, designer_notes) = extract_card_output(&payload)?;
+    let raw_card = STANDARD
+        .decode(image_b64.as_bytes())
+        .map_err(|e| format!("Generated image was not valid base64: {e}"))?;
+
+    // ── Resize to 1500-wide, inject chunk via the existing encoder ──────────
+    let card_img = image::load_from_memory(&raw_card)
+        .map_err(|e| format!("Generated image could not be decoded: {e}"))?;
+    let scale = CARD_WIDTH as f64 / card_img.width() as f64;
+    let card_img = card_img.resize(
+        CARD_WIDTH,
+        (card_img.height() as f64 * scale).round() as u32,
+        image::imageops::FilterType::Lanczos3,
+    );
+    let mut card_png = Vec::new();
+    card_img
+        .write_to(
+            &mut std::io::Cursor::new(&mut card_png),
+            image::ImageFormat::Png,
+        )
+        .map_err(|e| format!("Failed to encode card PNG: {e}"))?;
+
+    let final_bytes = match &lock_keys {
+        None => encode_snapshot_png(&snapshot, Some(&card_png))
+            .map_err(|e| format!("Failed to embed agent snapshot in card: {e}"))?,
+        Some((owner_keys, agent_pubkey)) => {
+            encode_locked_snapshot_png(&snapshot, owner_keys, agent_pubkey, Some(&card_png))
+                .map_err(|e| format!("Failed to embed locked agent snapshot in card: {e}"))?
+        }
+    };
+
+    // ── Verify: size ceiling + round-trip on the FINAL bytes ────────────────
+    // Locked cards: extract the actual chunk, parse the envelope, decrypt
+    // with the owner key, then compare the logical manifest (ciphertext is
+    // nondeterministic — never compare bytes).
+    validate_snapshot_encode_size(final_bytes.len(), true)?;
+    let decoded = match &lock_keys {
+        None => decode_snapshot_png(&final_bytes)
+            .map_err(|e| format!("Card failed round-trip verification: {e}"))?,
+        Some((owner_keys, _)) => {
+            let payload = extract_chunk_payload_png(&final_bytes)
+                .map_err(|e| format!("Card failed round-trip verification: {e}"))?;
+            match parse_chunk_payload(&payload)
+                .map_err(|e| format!("Card failed round-trip verification: {e}"))?
+            {
+                ChunkPayload::Locked(envelope) => {
+                    decrypt_envelope(&envelope, owner_keys.secret_key())
+                        .map_err(|e| format!("Card failed round-trip verification: {e}"))?
+                }
+                ChunkPayload::Plain(_) => {
+                    return Err(
+                        "Card round-trip verification failed: expected a locked envelope."
+                            .to_string(),
+                    )
+                }
+            }
+        }
+    };
+    if decoded != snapshot {
+        return Err("Card round-trip verification failed: manifest mismatch.".to_string());
+    }
+
+    let slug = crate::util::slugify(&display_name, "agent", 50);
+    let minted = MintedCard {
+        card_png_base64: STANDARD.encode(&final_bytes),
+        file_name: format!("{slug}.agent.png"),
+        designer_notes,
+        locked: lock_keys.is_some(),
+        memory_level,
+    };
+
+    // Archive best-effort: the mint is already paid for and verified, so a
+    // failed archive write logs and continues — it never fails the mint.
+    if let Err(e) = archive_minted_card(&app, &id, &display_name, &minted, &final_bytes) {
+        eprintln!("buzz-desktop: card-archive: failed to archive minted card: {e}");
+    }
+
+    Ok(minted)
+}
+
+/// The avatar the mint should use: the agent's kind:0 `picture` when one is
+/// published and non-blank, else the local record's `avatar_url`.
+///
+/// Pure so the precedence is unit-testable without a relay: a blank or
+/// whitespace-only `picture` must NOT shadow a real record avatar.
+fn preferred_avatar_url(
+    kind0_picture: Option<String>,
+    record_avatar_url: Option<String>,
+) -> Option<String> {
+    kind0_picture
+        .filter(|p| !p.trim().is_empty())
+        .or(record_avatar_url)
+}
+
+/// The avatar bytes the card manifest should inline.
+///
+/// Unlocked cards must carry the agent's REAL avatar inline: the PNG body is
+/// the generated card artwork, and the importer only adopts the body as the
+/// avatar when the manifest carries no inline bytes (`import.rs`) — without
+/// these bytes an imported agent would wear the card as its face. Downscaled
+/// to [`MANIFEST_AVATAR_MAX_DIM`] so the manifest tEXt chunk stays small.
+///
+/// Locked cards keep the data-URL-only behavior: the whole manifest must fit
+/// the NIP-44 plaintext cap (65 KB), which cannot carry inline pixels, and a
+/// locked envelope never reaches the import body override anyway.
+fn manifest_avatar_bytes(
+    locked: bool,
+    avatar_bytes: &[u8],
+    record_avatar_url: Option<&str>,
+) -> Result<Option<Vec<u8>>, String> {
+    if locked {
+        return Ok(decode_avatar_data_url(record_avatar_url.unwrap_or("")));
+    }
+    png_bytes_resized(avatar_bytes, MANIFEST_AVATAR_MAX_DIM)
+        .map(Some)
+        .map_err(|e| format!("Failed to inline the agent avatar into the card manifest: {e}"))
+}
+
+/// True when `url` shares an origin (scheme, host, port) with `relay_base`.
+///
+/// Gate for attaching the minted media get-auth header — the token must never
+/// be sent to a non-relay origin (same contract as `validate_download_url` in
+/// `media_download.rs`, but non-fatal: a foreign origin just fetches
+/// unauthenticated instead of failing the mint).
+fn is_same_origin(url: &str, relay_base: &str) -> bool {
+    match (url::Url::parse(url), url::Url::parse(relay_base)) {
+        (Ok(u), Ok(b)) => u.origin() == b.origin(),
+        _ => false,
+    }
+}
+
+/// Fetch an avatar over HTTP with a hard size cap.
+///
+/// `auth` is an optional pre-minted Blossom get-auth header value, attached
+/// verbatim — the caller is responsible for only supplying it for
+/// relay-origin URLs. Redirects are not followed when auth is present
+/// (redirect-hop guard, same rule as `media_download.rs`).
+///
+/// The cap bounds network and memory, not just the final buffer: the
+/// Content-Length header is checked before any body bytes are read, and the
+/// body is streamed with a running count so a missing or dishonest header
+/// still cannot exceed the cap (same contract as `media_download.rs`).
+async fn fetch_avatar(url: &str, auth: Option<&str>) -> Result<Vec<u8>, String> {
+    use futures_util::StreamExt;
+
+    let mut builder = reqwest::Client::builder().timeout(std::time::Duration::from_secs(30));
+    if auth.is_some() {
+        // Never let a relay 3xx forward the auth header across origins.
+        builder = builder.redirect(reqwest::redirect::Policy::none());
+    }
+    let client = builder
+        .build()
+        .map_err(|e| format!("Failed to build HTTP client: {e}"))?;
+    let mut req = client.get(url);
+    if let Some(auth) = auth {
+        req = req.header("authorization", auth);
+    }
+    let resp = req
+        .send()
+        .await
+        .map_err(|e| format!("Failed to fetch agent avatar: {e}"))?;
+    if !resp.status().is_success() {
+        return Err(format!("Avatar fetch failed: HTTP {}", resp.status()));
+    }
+
+    if let Some(content_length) = resp.content_length() {
+        if content_length > MAX_AVATAR_FETCH_BYTES as u64 {
+            return Err("Agent avatar is too large to use as card input.".to_string());
+        }
+    }
+
+    let mut bytes = Vec::new();
+    let mut stream = resp.bytes_stream();
+    while let Some(chunk) = stream.next().await {
+        let chunk = chunk.map_err(|e| format!("Failed to read avatar bytes: {e}"))?;
+        append_within_avatar_cap(&mut bytes, &chunk)?;
+    }
+    Ok(bytes)
+}
+
+/// Append a body chunk to the avatar buffer, rejecting before the append if
+/// the total would cross `MAX_AVATAR_FETCH_BYTES`. Split out so the cap
+/// boundary is unit-testable without an HTTP server.
+fn append_within_avatar_cap(buf: &mut Vec<u8>, chunk: &[u8]) -> Result<(), String> {
+    if buf.len() + chunk.len() > MAX_AVATAR_FETCH_BYTES {
+        return Err("Agent avatar is too large to use as card input.".to_string());
+    }
+    buf.extend_from_slice(chunk);
+    Ok(())
+}
+
+/// Save previously minted card bytes to disk via the OS save dialog.
+///
+/// Re-validates the bytes (chunk parses as a plain manifest or a
+/// structurally valid locked envelope, size within the import ceiling) so a
+/// corrupted preview can never be written as a `.agent.png`. No decryption
+/// happens here — the mint already round-trip-verified with the real key.
+#[tauri::command]
+pub async fn save_agent_card(
+    card_png_base64: String,
+    file_name: String,
+    app: AppHandle,
+) -> Result<bool, String> {
+    let bytes = STANDARD
+        .decode(card_png_base64.as_bytes())
+        .map_err(|e| format!("Card bytes were not valid base64: {e}"))?;
+    validate_snapshot_encode_size(bytes.len(), true)?;
+    let payload = extract_chunk_payload_png(&bytes)
+        .map_err(|e| format!("Refusing to save: card failed snapshot validation: {e}"))?;
+    parse_chunk_payload(&payload)
+        .map_err(|e| format!("Refusing to save: card failed snapshot validation: {e}"))?;
+
+    let safe_name = if file_name.ends_with(".agent.png") && !file_name.contains(['/', '\\']) {
+        file_name
+    } else {
+        "card.agent.png".to_string()
+    };
+    save_bytes_with_dialog(&app, &safe_name, "Agent card", &["png"], &bytes).await
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests;
diff --git a/desktop/src-tauri/src/commands/personas/card/tests.rs b/desktop/src-tauri/src/commands/personas/card/tests.rs
new file mode 100644
index 0000000000..407ab44974
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/card/tests.rs
@@ -0,0 +1,399 @@
+//! Unit tests for `card.rs` — split into a child module file so the parent
+//! stays under the 1000-line gate (same layout as `snapshot/tests.rs`).
+
+use super::*;
+use std::collections::BTreeMap;
+
+#[test]
+fn archive_file_name_validation_rejects_escapes() {
+    assert!(validate_archive_file_name("eva-1234.agent.png").is_ok());
+    for bad in [
+        "../escape.agent.png",
+        "sub/dir.agent.png",
+        "sub\\dir.agent.png",
+        "not-a-card.png",
+        "plain.json",
+        "",
+    ] {
+        assert!(
+            validate_archive_file_name(bad).is_err(),
+            "expected rejection: {bad:?}"
+        );
+    }
+}
+
+#[test]
+fn card_template_decodes_with_expected_shape() {
+    // The embedded template is generation input only, but a corrupt or
+    // accidentally swapped asset should fail the build's test gate, not a
+    // user's first mint.
+    let img = image::load_from_memory(CARD_TEMPLATE_PNG).expect("template must decode");
+    // 2:3-ish portrait frame.
+    assert!(img.height() > img.width(), "template must be portrait");
+    assert!(img.width() >= 512, "template unexpectedly small");
+}
+
+#[test]
+fn key_resolution_layering_record_wins() {
+    let mut global = BTreeMap::new();
+    global.insert("OPENAI_API_KEY".to_string(), "global".to_string());
+    let mut persona = BTreeMap::new();
+    persona.insert("OPENAI_API_KEY".to_string(), "persona".to_string());
+    let mut record = BTreeMap::new();
+    record.insert("OPENAI_API_KEY".to_string(), "record".to_string());
+
+    assert_eq!(
+        resolve_env_from_layers("OPENAI_API_KEY", &global, &persona, &record, None).as_deref(),
+        Some("record")
+    );
+    record.clear();
+    assert_eq!(
+        resolve_env_from_layers("OPENAI_API_KEY", &global, &persona, &record, None).as_deref(),
+        Some("persona")
+    );
+    persona.clear();
+    assert_eq!(
+        resolve_env_from_layers("OPENAI_API_KEY", &global, &persona, &record, None).as_deref(),
+        Some("global")
+    );
+    global.clear();
+    assert_eq!(
+        resolve_env_from_layers(
+            "OPENAI_API_KEY",
+            &global,
+            &persona,
+            &record,
+            Some("process".to_string())
+        )
+        .as_deref(),
+        Some("process")
+    );
+    assert!(resolve_env_from_layers("OPENAI_API_KEY", &global, &persona, &record, None).is_none());
+}
+
+/// Prove that `resolve_key_layer` classifies layers in the same precedence
+/// order that `mint_agent_card`/`resolve_env_from_layers` uses, so the dialog
+/// update path is only offered when writing global will actually win.
+#[test]
+fn key_status_layer_matches_mint_resolution_priority() {
+    let key = "OPENAI_API_KEY";
+    let mut global = BTreeMap::new();
+    let mut persona = BTreeMap::new();
+    let mut record = BTreeMap::new();
+
+    // No key anywhere → "none"
+    assert_eq!(resolve_key_layer(&global, &persona, &record, None), "none");
+
+    // Only global → "global" (the only writable layer)
+    global.insert(key.to_string(), "sk-global".to_string());
+    assert_eq!(
+        resolve_key_layer(&global, &persona, &record, None),
+        "global"
+    );
+    // mint resolution also picks global when record and persona are empty
+    assert_eq!(
+        resolve_env_from_layers(key, &global, &persona, &record, None).as_deref(),
+        Some("sk-global")
+    );
+
+    // Persona overrides global → status must report "persona", NOT "global"
+    persona.insert(key.to_string(), "sk-persona".to_string());
+    assert_eq!(
+        resolve_key_layer(&global, &persona, &record, None),
+        "persona"
+    );
+    // mint would use the persona key
+    assert_eq!(
+        resolve_env_from_layers(key, &global, &persona, &record, None).as_deref(),
+        Some("sk-persona")
+    );
+    // Writing to global would NOT change what mint resolves — status correctly
+    // returns "persona" so the dialog shows a read-only redirect instead.
+    let mut global_updated = global.clone();
+    global_updated.insert(key.to_string(), "sk-new-global".to_string());
+    assert_eq!(
+        resolve_env_from_layers(key, &global_updated, &persona, &record, None).as_deref(),
+        Some("sk-persona"),
+        "writing global must not change resolution when persona key exists"
+    );
+
+    // Agent record overrides both → status must report "agent"
+    record.insert(key.to_string(), "sk-agent".to_string());
+    assert_eq!(resolve_key_layer(&global, &persona, &record, None), "agent");
+    assert_eq!(
+        resolve_env_from_layers(key, &global, &persona, &record, None).as_deref(),
+        Some("sk-agent")
+    );
+
+    // Process env is last resort (only when all map layers are empty)
+    let empty = BTreeMap::new();
+    assert_eq!(
+        resolve_key_layer(&empty, &empty, &empty, Some("sk-process".to_string())),
+        "process"
+    );
+
+    // Blank values are skipped — process wins over a whitespace global
+    let mut blank_global = BTreeMap::new();
+    blank_global.insert(key.to_string(), "   ".to_string());
+    assert_eq!(
+        resolve_key_layer(
+            &blank_global,
+            &empty,
+            &empty,
+            Some("sk-process".to_string())
+        ),
+        "process"
+    );
+}
+
+#[test]
+fn key_resolution_skips_blank_values() {
+    let mut record = BTreeMap::new();
+    record.insert("OPENAI_API_KEY".to_string(), "   ".to_string());
+    let mut persona = BTreeMap::new();
+    persona.insert("OPENAI_API_KEY".to_string(), "persona".to_string());
+    assert_eq!(
+        resolve_env_from_layers("OPENAI_API_KEY", &BTreeMap::new(), &persona, &record, None)
+            .as_deref(),
+        Some("persona")
+    );
+}
+
+#[test]
+fn responses_url_default_and_override() {
+    assert_eq!(responses_url(None), "https://api.openai.com/v1/responses");
+    // Trailing slashes must not produce a double-slash path.
+    assert_eq!(
+        responses_url(Some("https://proxy.example/v1/".to_string())),
+        "https://proxy.example/v1/responses"
+    );
+    assert_eq!(
+        responses_url(Some("https://proxy.example/v1".to_string())),
+        "https://proxy.example/v1/responses"
+    );
+}
+
+#[test]
+fn instructions_pin_style_match_default_and_owner_primacy() {
+    let base = build_card_instructions("Eva", "leads the team", "");
+    assert!(base.contains("match input image 2's art style EXACTLY"));
+    assert!(base.contains("\"Eva\""));
+    assert!(!base.contains("OWNER'S DIRECTIONS"));
+
+    let directed = build_card_instructions("Eva", "leads the team", "make it stormy");
+    // Owner directions take primacy over style defaults...
+    assert!(directed.contains("OWNER'S DIRECTIONS"));
+    assert!(directed.contains("make it stormy"));
+    assert!(directed.contains("override the default art-style and copy guidance"));
+    // ...but the fixed contract survives: frame, style anchor (as an
+    // overridable default), and text-fidelity requirements stay present.
+    assert!(directed.contains("match input image 2's art style EXACTLY"));
+    assert!(directed.contains("cannot change the frame, layout, or"));
+    assert!(directed.contains("Render all text with perfect fidelity"));
+    // Card-text direction is an explicitly named capability, and the
+    // owner-wording rule acknowledges the fixed 220-char text-box limit
+    // (no mutually impossible "verbatim" vs "under 220 chars" pair).
+    assert!(directed.contains("card text"));
+    assert!(directed.contains("use their wording within the 220-character text-box limit"));
+}
+
+#[test]
+fn extract_card_output_happy_path_and_missing_image() {
+    let ok = serde_json::json!({
+        "output": [
+            {"type": "reasoning"},
+            {"type": "image_generation_call", "result": "aW1n"},
+            {"type": "message", "content": [
+                {"type": "output_text", "text": "notes here"}
+            ]}
+        ]
+    });
+    let (img, notes) = extract_card_output(&ok).unwrap();
+    assert_eq!(img, "aW1n");
+    assert_eq!(notes, "notes here");
+
+    let missing = serde_json::json!({"output": [{"type": "message", "content": []}]});
+    let err = extract_card_output(&missing).unwrap_err();
+    assert!(err.contains("No image"), "{err}");
+
+    let no_output = serde_json::json!({});
+    assert!(extract_card_output(&no_output).is_err());
+}
+
+#[test]
+fn kind0_picture_wins_over_record_avatar_unless_blank() {
+    let some = |s: &str| Some(s.to_string());
+    // Published picture wins.
+    assert_eq!(
+        preferred_avatar_url(some("https://relay/media/k0.png"), some("data:image/png;x")),
+        some("https://relay/media/k0.png")
+    );
+    // No profile / no picture: record avatar survives.
+    assert_eq!(
+        preferred_avatar_url(None, some("data:image/png;x")),
+        some("data:image/png;x")
+    );
+    // Blank or whitespace picture must not shadow a real avatar.
+    assert_eq!(
+        preferred_avatar_url(some(""), some("data:image/png;x")),
+        some("data:image/png;x")
+    );
+    assert_eq!(
+        preferred_avatar_url(some("  "), some("data:image/png;x")),
+        some("data:image/png;x")
+    );
+    // Nothing anywhere: None (caller surfaces the "no avatar" error).
+    assert_eq!(preferred_avatar_url(None, None), None);
+}
+
+#[test]
+fn unlocked_manifest_inlines_real_avatar_bytes_downscaled() {
+    // 700px source (over MANIFEST_AVATAR_MAX_DIM) in a solid color.
+    let avatar = image::DynamicImage::ImageRgba8(image::RgbaImage::from_pixel(
+        700,
+        700,
+        image::Rgba([9, 120, 33, 255]),
+    ));
+    let mut avatar_png = std::io::Cursor::new(Vec::new());
+    avatar
+        .write_to(&mut avatar_png, image::ImageFormat::Png)
+        .unwrap();
+
+    let inlined = manifest_avatar_bytes(false, avatar_png.get_ref(), None)
+        .unwrap()
+        .expect("unlocked mints must inline the real avatar");
+    let img = image::load_from_memory(&inlined).unwrap();
+    assert_eq!(
+        (img.width(), img.height()),
+        (MANIFEST_AVATAR_MAX_DIM, MANIFEST_AVATAR_MAX_DIM)
+    );
+    assert_eq!(img.to_rgba8().get_pixel(0, 0).0, [9, 120, 33, 255]);
+
+    // Undecodable avatar bytes fail the mint (pre-spend), never silently
+    // produce a card whose import would wear the artwork as a face.
+    assert!(manifest_avatar_bytes(false, b"not a png", None).is_err());
+}
+
+#[test]
+fn locked_manifest_keeps_data_url_only_avatar() {
+    // Locked mints must not inline fetched bytes (NIP-44 cap): only a record
+    // data URL carries over, exactly as before.
+    let unused = [0u8; 4];
+    assert_eq!(
+        manifest_avatar_bytes(true, &unused, Some("data:image/png;base64,aGk="))
+            .unwrap()
+            .as_deref(),
+        Some(b"hi".as_slice())
+    );
+    assert_eq!(
+        manifest_avatar_bytes(true, &unused, Some("https://relay/media/a.png")).unwrap(),
+        None
+    );
+    assert_eq!(manifest_avatar_bytes(true, &unused, None).unwrap(), None);
+}
+
+#[test]
+fn media_get_auth_gate_is_same_origin_only() {
+    // The minted Blossom get-auth header may only travel to the relay's own
+    // origin — scheme, host, and port all count (same contract as
+    // `validate_download_url` in `media_download.rs`).
+    let relay = "https://relay.example.com";
+    assert!(is_same_origin(
+        "https://relay.example.com/media/abc.png",
+        relay
+    ));
+    // Different host, scheme, or port: no auth.
+    assert!(!is_same_origin(
+        "https://evil.example.com/media/abc.png",
+        relay
+    ));
+    assert!(!is_same_origin(
+        "http://relay.example.com/media/abc.png",
+        relay
+    ));
+    assert!(!is_same_origin(
+        "https://relay.example.com:8443/media/abc.png",
+        relay
+    ));
+    // Unparseable inputs fail closed.
+    assert!(!is_same_origin("not a url", relay));
+    assert!(!is_same_origin(
+        "https://relay.example.com/x",
+        "also not a url"
+    ));
+    // Explicit port on both sides matches.
+    assert!(is_same_origin(
+        "http://localhost:3100/media/abc.png",
+        "http://localhost:3100"
+    ));
+}
+
+#[test]
+fn avatar_cap_rejects_before_appending_crossing_chunk() {
+    // The streaming accumulator must reject a chunk that would cross the
+    // cap BEFORE buffering it — this is what bounds memory when
+    // Content-Length is missing or dishonest.
+    let mut buf = vec![0u8; MAX_AVATAR_FETCH_BYTES - 1];
+    assert!(append_within_avatar_cap(&mut buf, &[0u8]).is_ok());
+    assert_eq!(buf.len(), MAX_AVATAR_FETCH_BYTES);
+    // Exactly at the cap: one more byte must fail and not grow the buffer.
+    assert!(append_within_avatar_cap(&mut buf, &[0u8]).is_err());
+    assert_eq!(buf.len(), MAX_AVATAR_FETCH_BYTES);
+
+    // A single oversized chunk is rejected outright.
+    let mut fresh = Vec::new();
+    let oversized = vec![0u8; MAX_AVATAR_FETCH_BYTES + 1];
+    assert!(append_within_avatar_cap(&mut fresh, &oversized).is_err());
+    assert!(fresh.is_empty());
+}
+
+#[test]
+fn save_rejects_plain_png_without_snapshot_chunk() {
+    // A plain PNG (no buzz_agent_snapshot chunk) must not be saveable as
+    // a card. Exercise the same validation the command runs.
+    let img = image::DynamicImage::new_rgba8(4, 4);
+    let mut png = Vec::new();
+    img.write_to(&mut std::io::Cursor::new(&mut png), image::ImageFormat::Png)
+        .unwrap();
+    assert!(decode_snapshot_png(&png).is_err());
+}
+
+#[test]
+fn archived_sidecar_without_memory_level_defaults_to_none() {
+    // Every mint before the memory option existed embedded MemoryLevel::None
+    // structurally, so old sidecars (no memoryLevel field) must deserialize
+    // to None — the gallery's disclosure depends on this being honest.
+    let legacy = r#"{
+        "storedFileName": "eva-1234.agent.png",
+        "fileName": "eva.agent.png",
+        "agentId": "abc",
+        "agentName": "Eva",
+        "designerNotes": "",
+        "locked": false,
+        "mintedAt": "2026-07-28T00:00:00Z"
+    }"#;
+    let meta: ArchivedCardMeta = serde_json::from_str(legacy).unwrap();
+    assert_eq!(meta.memory_level, MemoryLevel::None);
+
+    let with_level = legacy.replace(
+        "\"locked\": false,",
+        "\"locked\": false, \"memoryLevel\": \"everything\",",
+    );
+    let meta: ArchivedCardMeta = serde_json::from_str(&with_level).unwrap();
+    assert_eq!(meta.memory_level, MemoryLevel::Everything);
+}
+
+#[test]
+fn minted_card_serializes_memory_level_snake_case_value() {
+    // The TS layer narrows on the exact wire strings "none"/"core"/
+    // "everything" — pin the serde representation the frontend will see.
+    let minted = MintedCard {
+        card_png_base64: String::new(),
+        file_name: "eva.agent.png".to_string(),
+        designer_notes: String::new(),
+        locked: false,
+        memory_level: MemoryLevel::Core,
+    };
+    let json = serde_json::to_value(&minted).unwrap();
+    assert_eq!(json["memoryLevel"], "core");
+}
diff --git a/desktop/src-tauri/src/commands/personas/mod.rs b/desktop/src-tauri/src/commands/personas/mod.rs
index 66f7296a25..0cd7ad0324 100644
--- a/desktop/src-tauri/src/commands/personas/mod.rs
+++ b/desktop/src-tauri/src/commands/personas/mod.rs
@@ -306,11 +306,14 @@ pub async fn set_persona_active(
 }
 
 pub(crate) const PNG_MAGIC: [u8; 4] = [0x89, 0x50, 0x4E, 0x47];
+mod card;
 mod snapshot;
-pub use snapshot::encode_agent_snapshot_for_send;
-pub use snapshot::export_agent_snapshot;
+pub use card::*;
+#[cfg(test)]
+pub(crate) use snapshot::import::decode_snapshot_from_bytes;
 pub(crate) use snapshot::import::{
-    decode_snapshot_from_bytes, resolve_snapshot_import_behavior, MAX_SNAPSHOT_JSON_BYTES,
+    parse_snapshot_payload_from_bytes, resolve_snapshot_import_behavior, MAX_SNAPSHOT_JSON_BYTES,
     MAX_SNAPSHOT_PNG_BYTES,
 };
 pub use snapshot::{confirm_agent_snapshot_import, preview_agent_snapshot_import};
+pub use snapshot::{encode_agent_snapshot_for_send, export_agent_snapshot};
diff --git a/desktop/src-tauri/src/commands/personas/snapshot.rs b/desktop/src-tauri/src/commands/personas/snapshot.rs
index 583296dac0..e7bd1597e6 100644
--- a/desktop/src-tauri/src/commands/personas/snapshot.rs
+++ b/desktop/src-tauri/src/commands/personas/snapshot.rs
@@ -142,7 +142,7 @@ pub(crate) fn validate_snapshot_encode_size(bytes_len: usize, is_png: bool) -> R
 }
 
 /// Parse a `memory_level` string to `MemoryLevel`.
-fn parse_memory_level(s: &str) -> Result<MemoryLevel, String> {
+pub(crate) fn parse_memory_level(s: &str) -> Result<MemoryLevel, String> {
     match s {
         "none" | "" => Ok(MemoryLevel::None),
         "core" => Ok(MemoryLevel::Core),
@@ -153,6 +153,32 @@ fn parse_memory_level(s: &str) -> Result<MemoryLevel, String> {
     }
 }
 
+/// Flatten an owner-decrypted memory listing into manifest entries for
+/// `memory_level`: `Core` takes the core entry only; `Everything` appends all
+/// `mem/*` entries after it. Pure so both the export and card-mint paths share
+/// (and tests can pin) the level → entries selection.
+pub(crate) fn memory_entries_from_listing(
+    listing: crate::commands::engrams::AgentMemoryListing,
+    memory_level: MemoryLevel,
+) -> Vec<AgentSnapshotMemoryEntry> {
+    let mut entries = Vec::new();
+    if let Some(core) = listing.core {
+        entries.push(AgentSnapshotMemoryEntry {
+            slug: core.slug,
+            body: core.body,
+        });
+    }
+    if memory_level == MemoryLevel::Everything {
+        for mem in listing.memories {
+            entries.push(AgentSnapshotMemoryEntry {
+                slug: mem.slug,
+                body: mem.body,
+            });
+        }
+    }
+    entries
+}
+
 /// Parse a `format` string to a PNG flag.
 fn parse_format_is_png(s: &str) -> Result<bool, String> {
     match s {
@@ -267,22 +293,7 @@ pub(crate) async fn materialize_snapshot_bytes(
     // ── Fetch memory ─────────────────────────────────────────────────────────
     let memory_entries: Vec<AgentSnapshotMemoryEntry> = if let Some(pubkey) = memory_pubkey {
         let listing = get_agent_memory(pubkey, app.clone(), state).await?;
-        let mut entries = Vec::new();
-        if let Some(core) = listing.core {
-            entries.push(AgentSnapshotMemoryEntry {
-                slug: core.slug,
-                body: core.body,
-            });
-        }
-        if memory_level == MemoryLevel::Everything {
-            for mem in listing.memories {
-                entries.push(AgentSnapshotMemoryEntry {
-                    slug: mem.slug,
-                    body: mem.body,
-                });
-            }
-        }
-        entries
+        memory_entries_from_listing(listing, memory_level)
     } else {
         Vec::new()
     };
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/fidelity_tests.rs b/desktop/src-tauri/src/commands/personas/snapshot/fidelity_tests.rs
index 00a1457393..b769d74d7b 100644
--- a/desktop/src-tauri/src/commands/personas/snapshot/fidelity_tests.rs
+++ b/desktop/src-tauri/src/commands/personas/snapshot/fidelity_tests.rs
@@ -208,3 +208,64 @@ fn import_png_placeholder_keeps_manifest_avatar_fallback() {
     assert!(decoded.profile.avatar_data_url.is_none());
     assert_eq!(decoded.profile.avatar_url, snapshot.profile.avatar_url);
 }
+
+/// An unlocked trading card imports the agent's REAL avatar, never the card.
+///
+/// Mint-shaped input: the PNG body is the generated card artwork, while the
+/// manifest inlines the source avatar (`manifest_avatar_bytes` in `card.rs`).
+/// The #3578 body-wins override must not fire when the manifest already
+/// carries inline avatar bytes — otherwise the imported agent publishes the
+/// 1500-wide card as its kind:0 picture.
+#[test]
+fn import_unlocked_card_uses_manifest_avatar_not_card_artwork() {
+    use crate::managed_agents::agent_snapshot::{decode_avatar_data_url, encode_snapshot_png};
+    use base64::{engine::general_purpose::STANDARD, Engine as _};
+
+    // The real avatar: 4×3 solid blue, inlined in the manifest at mint time.
+    let real_avatar = image::DynamicImage::ImageRgba8(image::RgbaImage::from_pixel(
+        4,
+        3,
+        image::Rgba([23, 91, 177, 255]),
+    ));
+    let mut real_avatar_png = std::io::Cursor::new(Vec::new());
+    real_avatar
+        .write_to(&mut real_avatar_png, image::ImageFormat::Png)
+        .unwrap();
+
+    let mut snapshot = make_snapshot(MemoryLevel::None, vec![]);
+    snapshot.profile.avatar_data_url = Some(format!(
+        "data:image/png;base64,{}",
+        STANDARD.encode(real_avatar_png.get_ref())
+    ));
+    snapshot.profile.avatar_url = Some("https://relay.example/media/live-kind0.png".to_string());
+
+    // The card artwork: a distinct 1500×2250 solid red "trading card" as the
+    // PNG body — the exact dimensions the minter encodes for unlocked cards.
+    // Size matters: 2250px exceeds `snapshot_avatar`'s 2048px decode limit,
+    // so reaching the body override here wouldn't just import the wrong
+    // face — it would fail the import outright.
+    let card_art = image::DynamicImage::ImageRgba8(image::RgbaImage::from_pixel(
+        1500,
+        2250,
+        image::Rgba([200, 16, 16, 255]),
+    ));
+    let mut card_png = std::io::Cursor::new(Vec::new());
+    card_art
+        .write_to(&mut card_png, image::ImageFormat::Png)
+        .unwrap();
+    let file_bytes = encode_snapshot_png(&snapshot, Some(card_png.get_ref())).unwrap();
+
+    // Production import decode: the effective avatar must be the real one.
+    let decoded = decode_snapshot_from_bytes(&file_bytes).unwrap();
+    let avatar_bytes =
+        decode_avatar_data_url(decoded.profile.avatar_data_url.as_deref().unwrap()).unwrap();
+    let imported = image::load_from_memory(&avatar_bytes).unwrap();
+    assert_eq!(
+        (imported.width(), imported.height()),
+        (4, 3),
+        "imported avatar must be the source avatar, not the card artwork"
+    );
+    assert_eq!(imported.to_rgba8().get_pixel(0, 0).0, [23, 91, 177, 255]);
+    // The live kind:0 URL fallback survives untouched.
+    assert_eq!(decoded.profile.avatar_url, snapshot.profile.avatar_url);
+}
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/import.rs b/desktop/src-tauri/src/commands/personas/snapshot/import.rs
index eccf8ee601..d7f0323304 100644
--- a/desktop/src-tauri/src/commands/personas/snapshot/import.rs
+++ b/desktop/src-tauri/src/commands/personas/snapshot/import.rs
@@ -13,7 +13,11 @@ use tauri::{AppHandle, Emitter, State};
 use crate::{
     app_state::AppState,
     managed_agents::{
-        agent_snapshot::{decode_snapshot_json, decode_snapshot_png, AgentSnapshot, MemoryLevel},
+        agent_snapshot::{extract_chunk_payload_png, AgentSnapshot, MemoryLevel},
+        agent_snapshot_envelope::{
+            decrypt_envelope, parse_chunk_payload, resolve_unlock_secret, ChunkPayload,
+            LOCKED_CARD_REFUSAL,
+        },
         load_managed_agents, load_personas, save_managed_agents, save_personas, AgentDefinition,
         ManagedAgentRecord, RespondTo,
     },
@@ -72,6 +76,16 @@ pub struct AgentSnapshotImportPreview {
     pub has_source_allowlist: bool,
     /// Number of source allowlist entries.
     pub source_allowlist_count: usize,
+    /// Full source allowlist entries, surfaced before import so hidden access
+    /// configuration is never reduced to a count.
+    pub source_allowlist: Vec<String>,
+    /// Pretty-printed, validated manifest exactly as decoded from the file.
+    /// The UI makes this available before confirmation for full payload review.
+    pub manifest_json: String,
+    /// True when the snapshot came from a locked (encrypted) card that this
+    /// machine successfully unlocked. Cards that cannot be unlocked never
+    /// reach a preview — they fail closed with the locked-card refusal.
+    pub locked: bool,
 }
 
 /// The confirmation request sent from the UI after the user reviews the preview.
@@ -210,50 +224,112 @@ const PNG_MAGIC: [u8; 4] = [0x89, 0x50, 0x4e, 0x47];
 ///
 /// **Size cap:** PNG inputs over 10 MiB and JSON inputs over 5 MiB are rejected
 /// before allocation to avoid avoidable large-input work.
-pub(crate) fn decode_snapshot_from_bytes(
-    file_bytes: &[u8],
-) -> Result<crate::managed_agents::agent_snapshot::AgentSnapshot, String> {
-    if file_bytes.len() >= 4 && file_bytes[..4] == PNG_MAGIC {
+///
+/// **Locked cards:** a structurally valid locked envelope parses successfully
+/// as `ChunkPayload::Locked` — no decryption happens here. Callers that can
+/// unlock go through [`decode_snapshot_for_import`]; callers that only need
+/// transit validation (e.g. `fetch_snapshot_bytes`) accept `Locked` as-is.
+pub(crate) fn parse_snapshot_payload_from_bytes(file_bytes: &[u8]) -> Result<ChunkPayload, String> {
+    let payload: ChunkPayload = if file_bytes.len() >= 4 && file_bytes[..4] == PNG_MAGIC {
         if file_bytes.len() > MAX_SNAPSHOT_PNG_BYTES {
             return Err(format!(
                 "Snapshot file is too large ({} MiB). PNG snapshots must be under 10 MiB.",
                 file_bytes.len() / (1024 * 1024)
             ));
         }
-        let mut snapshot = decode_snapshot_png(file_bytes)?;
+        let chunk_json = extract_chunk_payload_png(file_bytes)?;
+        let mut payload = parse_chunk_payload(&chunk_json)?;
         // The PNG image body is the portable avatar. It deliberately wins over
-        // manifest avatar fields, whose URL may only be reachable by the
-        // sender. A 1×1 export placeholder leaves the manifest fallback intact.
-        if let Some(avatar_data_url) =
-            crate::managed_agents::snapshot_avatar::snapshot_png_avatar_data_url(file_bytes)?
-        {
-            snapshot.profile.avatar_data_url = Some(avatar_data_url);
+        // a manifest avatar *URL*, which may only be reachable by the sender.
+        // A 1×1 export placeholder leaves the manifest fallback intact.
+        // Inline manifest avatar *bytes* are authoritative and never
+        // overridden: trading cards supply the generated card artwork as the
+        // PNG body and carry the agent's real avatar inline — adopting the
+        // body there would import the card as the agent's face.
+        // Locked envelopes stay opaque here — there is no manifest to override
+        // until the unlock path decrypts one.
+        if let ChunkPayload::Plain(snapshot) = &mut payload {
+            if snapshot.profile.avatar_data_url.is_none() {
+                if let Some(avatar_data_url) =
+                    crate::managed_agents::snapshot_avatar::snapshot_png_avatar_data_url(
+                        file_bytes,
+                    )?
+                {
+                    snapshot.profile.avatar_data_url = Some(avatar_data_url);
+                }
+            }
         }
-        if snapshot.memory.level == MemoryLevel::None && !snapshot.memory.entries.is_empty() {
-            return Err(
-                "Snapshot is malformed: memory.level is 'none' but entries are present."
-                    .to_string(),
-            );
+        payload
+    } else {
+        // JSON path — apply size cap before serde allocation.
+        if file_bytes.len() > MAX_SNAPSHOT_JSON_BYTES {
+            return Err(format!(
+                "Snapshot file is too large ({} MiB). JSON snapshots must be under 5 MiB.",
+                file_bytes.len() / (1024 * 1024)
+            ));
         }
-        return Ok(snapshot);
-    }
-    // JSON path — apply size cap before serde allocation.
-    if file_bytes.len() > MAX_SNAPSHOT_JSON_BYTES {
-        return Err(format!(
-            "Snapshot file is too large ({} MiB). JSON snapshots must be under 5 MiB.",
-            file_bytes.len() / (1024 * 1024)
-        ));
-    }
-    let snapshot = decode_snapshot_json(file_bytes)?;
+        parse_chunk_payload(file_bytes)?
+    };
     // Consistency check: none + non-empty entries is always malformed,
-    // regardless of format.  Mirrors the PNG path above so the rule is
-    // enforced at decode time for both formats.
-    if !snapshot.memory.entries.is_empty() && snapshot.memory.level == MemoryLevel::None {
+    // regardless of enclosing format. Enforced at decode time for plain
+    // payloads here, and after decryption for locked ones (see
+    // `enforce_memory_consistency` callers).
+    if let ChunkPayload::Plain(snapshot) = &payload {
+        enforce_memory_consistency(snapshot)?;
+    }
+    Ok(payload)
+}
+
+/// The shared malformed-memory guard: `memory.level == none` with non-empty
+/// entries is always rejected before any write.
+fn enforce_memory_consistency(
+    snapshot: &crate::managed_agents::agent_snapshot::AgentSnapshot,
+) -> Result<(), String> {
+    if snapshot.memory.level == MemoryLevel::None && !snapshot.memory.entries.is_empty() {
         return Err(
             "Snapshot is malformed: memory.level is 'none' but entries are present.".to_string(),
         );
     }
-    Ok(snapshot)
+    Ok(())
+}
+
+/// Decode a plain snapshot from raw bytes, refusing locked cards.
+///
+/// Test-only convenience: production call sites either unlock through
+/// [`decode_snapshot_for_import`] or validate structurally through
+/// [`parse_snapshot_payload_from_bytes`].
+#[cfg(test)]
+pub(crate) fn decode_snapshot_from_bytes(
+    file_bytes: &[u8],
+) -> Result<crate::managed_agents::agent_snapshot::AgentSnapshot, String> {
+    match parse_snapshot_payload_from_bytes(file_bytes)? {
+        ChunkPayload::Plain(snapshot) => Ok(*snapshot),
+        ChunkPayload::Locked(_) => Err(LOCKED_CARD_REFUSAL.to_string()),
+    }
+}
+
+/// Decode a snapshot for import, unlocking locked cards when — and only
+/// when — this machine holds one of the envelope's two exact key endpoints
+/// (the owner identity or the named local agent record).
+///
+/// Returns the decoded manifest and whether it came from a locked envelope.
+/// When neither endpoint exists, fails closed with the locked-card refusal —
+/// never partial plaintext, never crypto details.
+pub(crate) fn decode_snapshot_for_import(
+    file_bytes: &[u8],
+    owner_keys: Option<&nostr::Keys>,
+    records: &[ManagedAgentRecord],
+) -> Result<(crate::managed_agents::agent_snapshot::AgentSnapshot, bool), String> {
+    match parse_snapshot_payload_from_bytes(file_bytes)? {
+        ChunkPayload::Plain(snapshot) => Ok((*snapshot, false)),
+        ChunkPayload::Locked(envelope) => {
+            let secret = resolve_unlock_secret(&envelope, owner_keys, records)
+                .ok_or_else(|| LOCKED_CARD_REFUSAL.to_string())?;
+            let snapshot = decrypt_envelope(&envelope, &secret)?;
+            enforce_memory_consistency(&snapshot)?;
+            Ok((snapshot, true))
+        }
+    }
 }
 
 async fn materialize_import_avatar<F, Fut>(
@@ -283,19 +359,38 @@ where
 /// `.agent.png` file. The format is sniffed from the content, not the
 /// extension, so an incorrectly-named file is handled correctly.
 ///
+/// Locked cards are unlocked here when this machine holds one of the
+/// envelope's two exact key endpoints; a card that cannot be unlocked fails
+/// with the locked-card refusal (shown directly to the user), never a
+/// partial preview. Identity-recovery mode is tolerated: owner keys are
+/// simply unavailable, so only the agent-record endpoint can unlock.
+///
 /// Returns an `AgentSnapshotImportPreview` or a descriptive error. Errors
-/// represent irrecoverable failures (corrupt / unsupported file) and are
-/// shown directly to the user.
+/// represent irrecoverable failures (corrupt / unsupported / locked-to-
+/// someone-else file) and are shown directly to the user.
 #[tauri::command]
 pub async fn preview_agent_snapshot_import(
     file_bytes: Vec<u8>,
     file_name: String,
+    app: AppHandle,
+    state: State<'_, AppState>,
 ) -> Result<AgentSnapshotImportPreview, String> {
+    // Key material + records are gathered up front (cheap, lock-scoped) so
+    // the blocking decode below owns plain data.
+    let owner_keys = state.signing_keys().ok();
+    let records = {
+        let _store_guard = state
+            .managed_agents_store_lock
+            .lock()
+            .map_err(|e| e.to_string())?;
+        load_managed_agents(&app)?
+    };
     tokio::task::spawn_blocking(move || {
         reject_legacy_persona_filename(&file_name)?;
-        let snapshot = decode_snapshot_from_bytes(&file_bytes)?;
+        let (snapshot, locked) =
+            decode_snapshot_for_import(&file_bytes, owner_keys.as_ref(), &records)?;
 
-        Ok(build_agent_snapshot_import_preview(&snapshot))
+        build_agent_snapshot_import_preview(&snapshot, locked)
     })
     .await
     .map_err(|e| format!("spawn_blocking failed: {e}"))?
@@ -303,7 +398,8 @@ pub async fn preview_agent_snapshot_import(
 
 pub(crate) fn build_agent_snapshot_import_preview(
     snapshot: &AgentSnapshot,
-) -> AgentSnapshotImportPreview {
+    locked: bool,
+) -> Result<AgentSnapshotImportPreview, String> {
     let memory_level = match snapshot.memory.level {
         MemoryLevel::None => "none",
         MemoryLevel::Core => "core",
@@ -311,7 +407,11 @@ pub(crate) fn build_agent_snapshot_import_preview(
     }
     .to_string();
 
-    AgentSnapshotImportPreview {
+    let manifest_json = serde_json::to_string_pretty(snapshot)
+        .map_err(|e| format!("failed to render snapshot manifest: {e}"))?;
+    let source_allowlist = snapshot.definition.respond_to_allowlist.clone();
+
+    Ok(AgentSnapshotImportPreview {
         display_name: snapshot.profile.display_name.clone(),
         is_builtin: snapshot.definition.source_is_builtin,
         model: snapshot.definition.model.clone(),
@@ -325,9 +425,12 @@ pub(crate) fn build_agent_snapshot_import_preview(
             .or_else(|| snapshot.profile.avatar_url.clone()),
         memory_level,
         memory_entry_count: snapshot.memory.entries.len(),
-        source_allowlist_count: snapshot.definition.respond_to_allowlist.len(),
-        has_source_allowlist: !snapshot.definition.respond_to_allowlist.is_empty(),
-    }
+        source_allowlist_count: source_allowlist.len(),
+        has_source_allowlist: !source_allowlist.is_empty(),
+        source_allowlist,
+        manifest_json,
+        locked,
+    })
 }
 
 // ── `confirm_agent_snapshot_import` ──────────────────────────────────────────
@@ -355,8 +458,20 @@ pub async fn confirm_agent_snapshot_import(
     app: AppHandle,
     state: State<'_, AppState>,
 ) -> Result<AgentSnapshotImportResult, String> {
-    // ── Phase 1: validate (no I/O) ───────────────────────────────────────────
-    let snapshot = decode_snapshot_from_bytes(&input.file_bytes)?;
+    // ── Phase 1: validate (no writes) ────────────────────────────────────────
+    // Locked cards unlock only via this machine's exact key endpoints;
+    // anything else fails closed here, before key generation.
+    let snapshot = {
+        let owner_keys = state.signing_keys().ok();
+        let records = {
+            let _store_guard = state
+                .managed_agents_store_lock
+                .lock()
+                .map_err(|e| e.to_string())?;
+            load_managed_agents(&app)?
+        };
+        decode_snapshot_for_import(&input.file_bytes, owner_keys.as_ref(), &records)?.0
+    };
 
     let display_name = snapshot.profile.display_name.trim().to_string();
     if display_name.is_empty() {
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/tests.rs b/desktop/src-tauri/src/commands/personas/snapshot/tests.rs
index 4289310280..c453b09a9d 100644
--- a/desktop/src-tauri/src/commands/personas/snapshot/tests.rs
+++ b/desktop/src-tauri/src/commands/personas/snapshot/tests.rs
@@ -564,7 +564,7 @@ fn import_preview_includes_exported_definition_metadata() {
     let bytes = crate::managed_agents::agent_snapshot::encode_snapshot_json(&snapshot).unwrap();
     let decoded = decode_snapshot_from_bytes(&bytes).unwrap();
 
-    let preview = build_agent_snapshot_import_preview(&decoded);
+    let preview = build_agent_snapshot_import_preview(&decoded, false).unwrap();
 
     assert!(preview.is_builtin);
     assert_eq!(preview.model.as_deref(), Some("claude-opus-4-5"));
@@ -949,51 +949,14 @@ fn test_parse_format_is_png_invalid_returns_error() {
 }
 
 // ── Export: validate_snapshot_encode_size ────────────────────────────────────
-//
-// Tests call `validate_snapshot_encode_size` directly so they prove the exact
-// production guard — not a manual reconstruction.  Removing or reversing the
-// check in production code will cause these tests to fail.
 
-/// JSON: boundary-1 passes, boundary is the last legal byte count.
-#[test]
-fn validate_encode_size_json_at_boundary_minus_1_passes() {
-    assert!(super::validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES - 1, false).is_ok());
-}
+#[path = "tests_memory_entries.rs"]
+mod memory_entries;
 
-/// JSON: exactly at the boundary is the last accepted size.
-#[test]
-fn validate_encode_size_json_at_boundary_passes() {
-    assert!(super::validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES, false).is_ok());
-}
+#[path = "tests_encode_size.rs"]
+mod encode_size;
 
-/// JSON: boundary+1 is rejected.
-#[test]
-fn validate_encode_size_json_over_boundary_is_rejected() {
-    let err = super::validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES + 1, false).unwrap_err();
-    assert!(
-        err.contains("size limit"),
-        "error must mention size limit, got: {err}"
-    );
-}
+// ── Import: decode_snapshot_for_import (locked cards) ─────────────────────
 
-/// PNG: boundary-1 passes.
-#[test]
-fn validate_encode_size_png_at_boundary_minus_1_passes() {
-    assert!(super::validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES - 1, true).is_ok());
-}
-
-/// PNG: exactly at the boundary passes.
-#[test]
-fn validate_encode_size_png_at_boundary_passes() {
-    assert!(super::validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES, true).is_ok());
-}
-
-/// PNG: boundary+1 is rejected.
-#[test]
-fn validate_encode_size_png_over_boundary_is_rejected() {
-    let err = super::validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES + 1, true).unwrap_err();
-    assert!(
-        err.contains("size limit"),
-        "error must mention size limit, got: {err}"
-    );
-}
+#[path = "tests_locked.rs"]
+mod locked_import;
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/tests_encode_size.rs b/desktop/src-tauri/src/commands/personas/snapshot/tests_encode_size.rs
new file mode 100644
index 0000000000..36eaa99716
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/snapshot/tests_encode_size.rs
@@ -0,0 +1,55 @@
+//! Export-size guard tests for `validate_snapshot_encode_size`.
+//!
+//! Kept in a sibling file so `snapshot/tests.rs` stays under the
+//! 1000-line gate; `#[path]`-included from there as a child module,
+//! so `super::*` still resolves to the shared test imports.
+//!
+//! Tests call `validate_snapshot_encode_size` directly so they prove the
+//! exact production guard — not a manual reconstruction.  Removing or
+//! reversing the check in production code will cause these tests to fail.
+
+use super::*;
+
+/// JSON: boundary-1 passes, boundary is the last legal byte count.
+#[test]
+fn validate_encode_size_json_at_boundary_minus_1_passes() {
+    assert!(validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES - 1, false).is_ok());
+}
+
+/// JSON: exactly at the boundary is the last accepted size.
+#[test]
+fn validate_encode_size_json_at_boundary_passes() {
+    assert!(validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES, false).is_ok());
+}
+
+/// JSON: boundary+1 is rejected.
+#[test]
+fn validate_encode_size_json_over_boundary_is_rejected() {
+    let err = validate_snapshot_encode_size(MAX_SNAPSHOT_JSON_BYTES + 1, false).unwrap_err();
+    assert!(
+        err.contains("size limit"),
+        "error must mention size limit, got: {err}"
+    );
+}
+
+/// PNG: boundary-1 passes.
+#[test]
+fn validate_encode_size_png_at_boundary_minus_1_passes() {
+    assert!(validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES - 1, true).is_ok());
+}
+
+/// PNG: exactly at the boundary passes.
+#[test]
+fn validate_encode_size_png_at_boundary_passes() {
+    assert!(validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES, true).is_ok());
+}
+
+/// PNG: boundary+1 is rejected.
+#[test]
+fn validate_encode_size_png_over_boundary_is_rejected() {
+    let err = validate_snapshot_encode_size(MAX_SNAPSHOT_PNG_BYTES + 1, true).unwrap_err();
+    assert!(
+        err.contains("size limit"),
+        "error must mention size limit, got: {err}"
+    );
+}
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/tests_locked.rs b/desktop/src-tauri/src/commands/personas/snapshot/tests_locked.rs
new file mode 100644
index 0000000000..296444f78d
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/snapshot/tests_locked.rs
@@ -0,0 +1,129 @@
+//! Locked-card import tests for `decode_snapshot_for_import`.
+//!
+//! Kept in a sibling file so `snapshot/tests.rs` stays under the
+//! 1000-line gate; `#[path]`-included from there as a child module,
+//! so `super::*` still resolves to the shared test helpers.
+
+use super::*;
+use crate::commands::personas::snapshot::import::{
+    decode_snapshot_for_import, parse_snapshot_payload_from_bytes,
+};
+use crate::managed_agents::agent_snapshot_envelope::{
+    encode_locked_snapshot_png, encrypt_snapshot_envelope, ChunkPayload, LOCKED_CARD_REFUSAL,
+};
+
+/// Build a keyed instance record holding real key material, so the
+/// agent-endpoint unlock path resolves exactly as production does.
+fn record_for(agent: &nostr::Keys) -> ManagedAgentRecord {
+    ManagedAgentRecord {
+        pubkey: agent.public_key().to_hex(),
+        slug: None,
+        persona_id: Some("locked-test".to_string()),
+        private_key_nsec: nostr::ToBech32::to_bech32(agent.secret_key()).unwrap(),
+        ..make_definition("")
+    }
+}
+
+fn locked_png(owner: &nostr::Keys, agent: &nostr::Keys) -> (AgentSnapshot, Vec<u8>) {
+    let snapshot = make_snapshot(MemoryLevel::None, vec![]);
+    let png = encode_locked_snapshot_png(&snapshot, owner, &agent.public_key(), None).unwrap();
+    (snapshot, png)
+}
+
+/// Owner identity key unlocks a locked card; `locked` is reported true.
+#[test]
+fn owner_endpoint_unlocks_locked_png() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let (snapshot, png) = locked_png(&owner, &agent);
+    let (decoded, locked) = decode_snapshot_for_import(&png, Some(&owner), &[]).unwrap();
+    assert_eq!(decoded, snapshot);
+    assert!(locked);
+}
+
+/// A local managed-agent record holding the agent nsec unlocks the card
+/// even when the owner identity does not match (e.g. re-import on the
+/// agent's own machine under a different owner identity).
+#[test]
+fn agent_record_endpoint_unlocks_locked_png() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let (snapshot, png) = locked_png(&owner, &agent);
+    let other_identity = nostr::Keys::generate();
+    let records = vec![record_for(&agent)];
+    let (decoded, locked) =
+        decode_snapshot_for_import(&png, Some(&other_identity), &records).unwrap();
+    assert_eq!(decoded, snapshot);
+    assert!(locked);
+}
+
+/// No matching endpoint → only the locked-card refusal, nothing else.
+#[test]
+fn stranger_fails_closed_with_refusal_only() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let (_snapshot, png) = locked_png(&owner, &agent);
+    let stranger = nostr::Keys::generate();
+    let unrelated_record = record_for(&nostr::Keys::generate());
+    let err = decode_snapshot_for_import(&png, Some(&stranger), &[unrelated_record]).unwrap_err();
+    assert_eq!(err, LOCKED_CARD_REFUSAL);
+    // And with no key material at all.
+    let err = decode_snapshot_for_import(&png, None, &[]).unwrap_err();
+    assert_eq!(err, LOCKED_CARD_REFUSAL);
+}
+
+/// Plain snapshots pass through unchanged with `locked == false`, with or
+/// without key material in scope.
+#[test]
+fn plain_snapshot_passes_through_unlocked() {
+    use crate::managed_agents::agent_snapshot::encode_snapshot_png;
+    let snapshot = make_snapshot(MemoryLevel::None, vec![]);
+    let png = encode_snapshot_png(&snapshot, None).unwrap();
+    let owner = nostr::Keys::generate();
+    let (decoded, locked) = decode_snapshot_for_import(&png, Some(&owner), &[]).unwrap();
+    assert_eq!(decoded, snapshot);
+    assert!(!locked);
+    let (decoded, locked) = decode_snapshot_for_import(&png, None, &[]).unwrap();
+    assert_eq!(decoded, snapshot);
+    assert!(!locked);
+}
+
+/// The memory-consistency guard fires AFTER decryption too: a locked
+/// envelope whose plaintext declares level none + non-empty entries is
+/// rejected even for a legitimate endpoint.
+#[test]
+fn decrypted_manifest_memory_consistency_enforced() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let malformed = make_snapshot(
+        MemoryLevel::None,
+        vec![AgentSnapshotMemoryEntry {
+            slug: "core".to_string(),
+            body: "leaked".to_string(),
+        }],
+    );
+    // encrypt_snapshot_envelope does not guard memory consistency (the
+    // PNG encoder does), so this constructs the malicious payload.
+    let envelope = encrypt_snapshot_envelope(&malformed, &owner, &agent.public_key()).unwrap();
+    let json = serde_json::to_vec(&envelope).unwrap();
+    let err = decode_snapshot_for_import(&json, Some(&owner), &[]).unwrap_err();
+    assert!(
+        err.contains("'none' but entries are present"),
+        "post-decrypt consistency guard must fire, got: {err}"
+    );
+}
+
+/// Transit validation (`fetch_snapshot_bytes` path) accepts a locked PNG
+/// without any key material — structural validation only, no decryption.
+#[test]
+fn transit_validation_accepts_locked_png_without_keys() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let (_snapshot, png) = locked_png(&owner, &agent);
+    let payload = parse_snapshot_payload_from_bytes(&png).unwrap();
+    assert!(matches!(payload, ChunkPayload::Locked(_)));
+}
+
+/// The keyless plain decoder refuses locked cards with the refusal.
+#[test]
+fn plain_decoder_refuses_locked_cards() {
+    let (owner, agent) = (nostr::Keys::generate(), nostr::Keys::generate());
+    let (_snapshot, png) = locked_png(&owner, &agent);
+    let err = decode_snapshot_from_bytes(&png).unwrap_err();
+    assert_eq!(err, LOCKED_CARD_REFUSAL);
+}
diff --git a/desktop/src-tauri/src/commands/personas/snapshot/tests_memory_entries.rs b/desktop/src-tauri/src/commands/personas/snapshot/tests_memory_entries.rs
new file mode 100644
index 0000000000..b17efa1ad1
--- /dev/null
+++ b/desktop/src-tauri/src/commands/personas/snapshot/tests_memory_entries.rs
@@ -0,0 +1,55 @@
+//! Tests for `memory_entries_from_listing` — the shared level → entries
+//! selection used by both snapshot export and card minting. Split from
+//! `tests.rs` to keep that file under the 1000-line gate; `#[path]`-included
+//! from there as a child module, so `super::*` resolves to `tests`'s parent
+//! scope re-exports.
+
+use super::*;
+
+fn listing_fixture() -> crate::commands::engrams::AgentMemoryListing {
+    let entry = |slug: &str, body: &str| crate::commands::engrams::EngramEntry {
+        slug: slug.to_string(),
+        body: body.to_string(),
+        event_id: "e".repeat(64),
+        created_at: 1,
+        outgoing_refs: vec![],
+    };
+    crate::commands::engrams::AgentMemoryListing {
+        core: Some(entry("core", "core body")),
+        memories: vec![entry("mem/a", "a body"), entry("mem/b", "b body")],
+        truncated: false,
+        fetched_at: 1,
+    }
+}
+
+#[test]
+fn memory_entries_core_takes_core_only() {
+    let entries = memory_entries_from_listing(listing_fixture(), MemoryLevel::Core);
+    assert_eq!(entries.len(), 1);
+    assert_eq!(entries[0].slug, "core");
+    assert_eq!(entries[0].body, "core body");
+}
+
+#[test]
+fn memory_entries_everything_appends_mem_entries_after_core() {
+    let entries = memory_entries_from_listing(listing_fixture(), MemoryLevel::Everything);
+    assert_eq!(
+        entries.iter().map(|e| e.slug.as_str()).collect::<Vec<_>>(),
+        vec!["core", "mem/a", "mem/b"]
+    );
+}
+
+#[test]
+fn memory_entries_missing_core_still_yields_mem_entries_for_everything() {
+    let mut listing = listing_fixture();
+    listing.core = None;
+    let entries = memory_entries_from_listing(listing, MemoryLevel::Everything);
+    assert_eq!(
+        entries.iter().map(|e| e.slug.as_str()).collect::<Vec<_>>(),
+        vec!["mem/a", "mem/b"]
+    );
+
+    let mut core_only = listing_fixture();
+    core_only.core = None;
+    assert!(memory_entries_from_listing(core_only, MemoryLevel::Core).is_empty());
+}
diff --git a/desktop/src-tauri/src/key_backup.rs b/desktop/src-tauri/src/key_backup.rs
index f97bf95a67..e8fcc8abe4 100644
--- a/desktop/src-tauri/src/key_backup.rs
+++ b/desktop/src-tauri/src/key_backup.rs
@@ -133,9 +133,14 @@ pub fn backup_file_path(data_dir: &std::path::Path) -> std::path::PathBuf {
     data_dir.join(BACKUP_FILE_NAME)
 }
 
-/// Atomically write `ncryptsec` to `path` with owner-only permissions, then
-/// reread and byte-compare. Same crash-safety pattern as
+/// Atomically write the app-managed `ncryptsec` backup with owner-only
+/// permissions, then reread and byte-compare. Same crash-safety pattern as
 /// `app_state::save_key_file`.
+///
+/// Portable exports selected through a native save panel must use
+/// [`write_portable_backup_file`] instead: sandboxed macOS grants access to the
+/// selected path, but not to the sibling temporary file this writer needs.
+#[allow(dead_code)] // Retained for durable app-managed backups; portable exports must not use it.
 pub fn write_backup_file(path: &std::path::Path, ncryptsec: &str) -> Result<(), String> {
     use atomic_write_file::AtomicWriteFile;
     use std::io::Write;
@@ -155,6 +160,56 @@ pub fn write_backup_file(path: &std::path::Path, ncryptsec: &str) -> Result<(),
     file.commit()
         .map_err(|e| format!("commit backup file: {e}"))?;
 
+    verify_backup_file(path, ncryptsec)
+}
+
+/// Write a user-selected portable backup without creating a sibling file.
+///
+/// Native macOS save panels authorize the exact selected path in protected
+/// folders such as Downloads, not an atomic writer's hidden sibling. Opening
+/// with `create_new` uses only that authorized path and also guarantees an
+/// existing backup is never truncated: users must choose a new filename when
+/// the destination already exists. After writing, the file is synced and its
+/// persisted bytes are reread before success is reported.
+pub fn write_portable_backup_file(path: &std::path::Path, ncryptsec: &str) -> Result<(), String> {
+    use std::io::Write;
+
+    let mut options = std::fs::OpenOptions::new();
+    options.write(true).create_new(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        options.mode(0o600);
+    }
+
+    let mut file = options.open(path).map_err(|error| {
+        if error.kind() == std::io::ErrorKind::AlreadyExists {
+            "backup file already exists; choose a new filename so the existing backup stays safe"
+                .to_string()
+        } else {
+            format!("create portable backup file: {error}")
+        }
+    })?;
+
+    let write_result = file
+        .write_all(ncryptsec.as_bytes())
+        .map_err(|e| format!("write portable backup file: {e}"))
+        .and_then(|()| {
+            file.sync_all()
+                .map_err(|e| format!("sync portable backup file: {e}"))
+        });
+    drop(file);
+
+    let result = write_result.and_then(|()| verify_backup_file(path, ncryptsec));
+    if result.is_err() {
+        // This function created the destination exclusively, so cleanup cannot
+        // clobber a backup that existed before the save attempt.
+        let _ = std::fs::remove_file(path);
+    }
+    result
+}
+
+fn verify_backup_file(path: &std::path::Path, ncryptsec: &str) -> Result<(), String> {
     // Reread and byte-compare: only report success for bytes that are
     // actually on disk.
     let on_disk = std::fs::read_to_string(path).map_err(|e| format!("reread backup file: {e}"))?;
diff --git a/desktop/src-tauri/src/key_backup_tests.rs b/desktop/src-tauri/src/key_backup_tests.rs
index b9713201e1..35b486f78d 100644
--- a/desktop/src-tauri/src/key_backup_tests.rs
+++ b/desktop/src-tauri/src/key_backup_tests.rs
@@ -160,6 +160,45 @@ fn write_backup_file_overwrites_atomically() {
     assert_eq!(entries, vec![std::ffi::OsString::from(BACKUP_FILE_NAME)]);
 }
 
+#[test]
+fn write_portable_backup_file_persists_0600_without_a_sibling() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("portable.ncryptsec");
+    write_portable_backup_file(&path, SPEC_NCRYPTSEC).unwrap();
+
+    assert_eq!(std::fs::read_to_string(&path).unwrap(), SPEC_NCRYPTSEC);
+    let entries: Vec<_> = std::fs::read_dir(dir.path())
+        .unwrap()
+        .map(|entry| entry.unwrap().file_name())
+        .collect();
+    assert_eq!(
+        entries,
+        vec![std::ffi::OsString::from("portable.ncryptsec")]
+    );
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let mode = std::fs::metadata(&path).unwrap().permissions().mode();
+        assert_eq!(mode & 0o777, 0o600, "portable backup must be owner-only");
+    }
+}
+
+#[test]
+fn write_portable_backup_file_preserves_an_existing_backup() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("portable.ncryptsec");
+    std::fs::write(&path, "ncryptsec1existing").unwrap();
+
+    let error = write_portable_backup_file(&path, SPEC_NCRYPTSEC).unwrap_err();
+
+    assert!(error.contains("already exists"), "{error}");
+    assert_eq!(
+        std::fs::read_to_string(&path).unwrap(),
+        "ncryptsec1existing"
+    );
+}
+
 #[test]
 fn delete_backup_file_is_idempotent() {
     let dir = tempfile::tempdir().unwrap();
diff --git a/desktop/src-tauri/src/lib.rs b/desktop/src-tauri/src/lib.rs
index 6814008f0d..c4b733e3e0 100644
--- a/desktop/src-tauri/src/lib.rs
+++ b/desktop/src-tauri/src/lib.rs
@@ -65,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};
@@ -851,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,
diff --git a/desktop/src-tauri/src/managed_agents/agent_snapshot.rs b/desktop/src-tauri/src/managed_agents/agent_snapshot.rs
index 16a0d35b23..7c08e7095f 100644
--- a/desktop/src-tauri/src/managed_agents/agent_snapshot.rs
+++ b/desktop/src-tauri/src/managed_agents/agent_snapshot.rs
@@ -306,9 +306,22 @@ pub fn encode_snapshot_png(
         );
     }
 
-    // Manifest → JSON → base64 for the tEXt chunk payload.
+    // Manifest → JSON for the tEXt chunk payload. The payload/PNG composition
+    // is shared with the locked-card encoder in `agent_snapshot_envelope`;
+    // plain cards remain byte-identical to the pre-envelope encoder.
     let json_bytes = encode_snapshot_json(snapshot)?;
-    let chunk_text = STANDARD.encode(&json_bytes);
+    encode_chunk_payload_png(&json_bytes, avatar_bytes)
+}
+
+/// Encode arbitrary chunk-payload JSON (plain manifest or locked envelope)
+/// into a PNG carrying it base64-encoded in the `buzz_agent_snapshot` tEXt
+/// chunk. Shared by the plain encoder above and
+/// `agent_snapshot_envelope::encode_locked_snapshot_png`.
+pub(crate) fn encode_chunk_payload_png(
+    json_bytes: &[u8],
+    avatar_bytes: Option<&[u8]>,
+) -> Result<Vec<u8>, String> {
+    let chunk_text = STANDARD.encode(json_bytes);
 
     // Use the avatar as the PNG image body, transcoding decodable non-PNG
     // avatars. Fall back to a minimal 1×1 transparent placeholder only when
@@ -334,8 +347,11 @@ pub fn encode_snapshot_png(
     Ok(png_bytes)
 }
 
-/// Decode a manifest from a `.agent.png` tEXt chunk.
-pub fn decode_snapshot_png(png_bytes: &[u8]) -> Result<AgentSnapshot, String> {
+/// Extract and base64-decode the raw `buzz_agent_snapshot` chunk payload
+/// (JSON bytes) from a PNG, without interpreting it. The payload may be a
+/// plain manifest or a locked envelope — callers dispatch on the parsed
+/// `format` via `agent_snapshot_envelope::parse_chunk_payload`.
+pub(crate) fn extract_chunk_payload_png(png_bytes: &[u8]) -> Result<Vec<u8>, String> {
     let decoder = Decoder::new(Cursor::new(png_bytes));
     let reader = decoder
         .read_info()
@@ -349,10 +365,18 @@ pub fn decode_snapshot_png(png_bytes: &[u8]) -> Result<AgentSnapshot, String> {
         .map(|c| c.text.as_str())
         .ok_or_else(|| "PNG does not contain a buzz_agent_snapshot tEXt chunk".to_string())?;
 
-    let json_bytes = STANDARD
+    STANDARD
         .decode(chunk_text.trim())
-        .map_err(|e| format!("Invalid base64 in PNG chunk: {e}"))?;
+        .map_err(|e| format!("Invalid base64 in PNG chunk: {e}"))
+}
 
+/// Decode a manifest from a `.agent.png` tEXt chunk.
+///
+/// Plain snapshots only — a locked (encrypted) chunk payload fails here with
+/// the manifest format error. Import paths that must handle locked cards go
+/// through `agent_snapshot_envelope::parse_chunk_payload` instead.
+pub fn decode_snapshot_png(png_bytes: &[u8]) -> Result<AgentSnapshot, String> {
+    let json_bytes = extract_chunk_payload_png(png_bytes)?;
     decode_snapshot_json(&json_bytes)
 }
 
@@ -473,527 +497,5 @@ fn inject_text_chunk(png_bytes: &[u8], keyword: &str, text: &str) -> Result<Vec<
 // ── Tests ─────────────────────────────────────────────────────────────────────
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::managed_agents::types::{BackendKind, ManagedAgentRecord, RespondTo};
-    use std::collections::BTreeMap;
-
-    /// Build a minimal `ManagedAgentRecord` for testing. Only the fields
-    /// relevant to snapshot export are filled; the rest use defaults.
-    fn minimal_record() -> ManagedAgentRecord {
-        ManagedAgentRecord {
-            pubkey: "deadbeef".to_string(),
-            name: "Test Agent".to_string(),
-            display_name: Some("Test Agent Display".to_string()),
-            persona_id: Some("SENTINEL_PERSONA_ID".to_string()), // MUST NOT appear in snapshot
-            team_id: Some("SENTINEL_TEAM_ID".to_string()),       // MUST NOT appear in snapshot
-            private_key_nsec: "nsec1secret".to_string(),         // MUST NOT appear in snapshot
-            auth_tag: Some("auth-tag-secret".to_string()),       // MUST NOT appear in snapshot
-            relay_url: "wss://relay.example.com".to_string(),    // MUST NOT appear in snapshot
-            avatar_url: Some("https://example.com/avatar.png".to_string()),
-            acp_command: "/usr/local/bin/acp".to_string(), // MUST NOT appear in snapshot
-            agent_command: "goose".to_string(),            // MUST NOT appear in snapshot
-            agent_command_override: Some("goose-override".to_string()), // MUST NOT appear
-            agent_args: vec!["--arg".to_string()],         // MUST NOT appear in snapshot
-            mcp_command: "mcp-server".to_string(),         // MUST NOT appear in snapshot
-            turn_timeout_seconds: 120,                     // deprecated, MUST NOT appear
-            idle_timeout_seconds: Some(30),
-            max_turn_duration_seconds: Some(600),
-            parallelism: 2,
-            system_prompt: Some("You are a test agent.".to_string()),
-            model: Some("claude-opus-4".to_string()),
-            provider: Some("anthropic".to_string()),
-            persona_source_version: Some("v1.0".to_string()), // MUST NOT appear
-            env_vars: {
-                let mut m = BTreeMap::new();
-                m.insert("API_KEY".to_string(), "secret123".to_string()); // MUST NOT appear
-                m
-            },
-            start_on_app_launch: true,
-            auto_restart_on_config_change: true,
-            runtime_pid: Some(12345), // MUST NOT appear
-            backend: BackendKind::Provider {
-                // MUST NOT appear — carries a provider secret
-                id: "SENTINEL_BACKEND_ID".to_string(),
-                config: serde_json::json!({"api_key": "SENTINEL_BACKEND_SECRET"}),
-            },
-            backend_agent_id: Some("SENTINEL_BACKEND_AGENT_ID".to_string()), // MUST NOT appear
-            provider_binary_path: Some("/usr/bin/SENTINEL_PROVIDER_BINARY".to_string()), // MUST NOT appear
-            persona_team_dir: Some(std::path::PathBuf::from("SENTINEL_TEAM_DIR")), // MUST NOT appear
-            persona_name_in_team: Some("SENTINEL_NAME_IN_TEAM".to_string()), // MUST NOT appear
-            created_at: "2024-01-01T00:00:00Z".to_string(),
-            updated_at: "2024-01-02T00:00:00Z".to_string(),
-            last_started_at: Some("2024-01-03T00:00:00Z".to_string()), // MUST NOT appear
-            last_stopped_at: None,
-            last_exit_code: Some(0), // MUST NOT appear
-            last_error: Some("SENTINEL_LAST_ERROR".to_string()), // MUST NOT appear
-            last_error_code: Some(42), // MUST NOT appear
-            respond_to: RespondTo::default(),
-            respond_to_allowlist: vec!["pubkey1hex".to_string()],
-            slug: Some("test-agent".to_string()),
-            runtime: Some("goose".to_string()),
-            name_pool: vec!["Alice".to_string(), "Bob".to_string()],
-            is_builtin: false,
-            is_active: true,
-            shared: false,
-            source_team: Some("team-id-123".to_string()), // MUST NOT appear
-            source_team_persona_slug: Some("lep".to_string()), // MUST NOT appear
-            definition_respond_to: Some("allowlist".to_string()),
-            catalog_source: None,
-            definition_respond_to_allowlist: vec!["abc123def".to_string()],
-            definition_parallelism: Some(4),
-            relay_mesh: None,
-        }
-    }
-
-    // ── Round-trip tests ──────────────────────────────────────────────────────
-
-    #[test]
-    fn json_round_trip_config_only() {
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
-        let bytes = encode_snapshot_json(&snapshot).unwrap();
-        let parsed = decode_snapshot_json(&bytes).unwrap();
-        assert_eq!(parsed, snapshot);
-    }
-
-    #[test]
-    fn json_round_trip_with_memory() {
-        let record = minimal_record();
-        let entries = vec![
-            AgentSnapshotMemoryEntry {
-                slug: "core".to_string(),
-                body: "I am a test agent.".to_string(),
-            },
-            AgentSnapshotMemoryEntry {
-                slug: "mem/research".to_string(),
-                body: "Some research notes.".to_string(),
-            },
-        ];
-        let snapshot = build_snapshot(&record, MemoryLevel::Everything, entries, None);
-        let bytes = encode_snapshot_json(&snapshot).unwrap();
-        let parsed = decode_snapshot_json(&bytes).unwrap();
-        assert_eq!(parsed, snapshot);
-    }
-
-    #[test]
-    fn png_round_trip_no_memory() {
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
-        let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
-        let parsed = decode_snapshot_png(&png_bytes).unwrap();
-        assert_eq!(parsed.definition.name, snapshot.definition.name);
-        assert_eq!(parsed.profile.display_name, snapshot.profile.display_name);
-        assert_eq!(parsed.memory.level, MemoryLevel::None);
-    }
-
-    #[test]
-    fn png_round_trip_with_avatar_png() {
-        // Build a minimal PNG avatar.
-        let avatar = make_png_with_text("dummy", "value").unwrap();
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&avatar));
-        // Avatar should be inlined as a data URL.
-        assert!(snapshot
-            .profile
-            .avatar_data_url
-            .as_deref()
-            .unwrap_or("")
-            .starts_with("data:image/png;base64,"));
-
-        let png_bytes = encode_snapshot_png(&snapshot, Some(&avatar)).unwrap();
-        let parsed = decode_snapshot_png(&png_bytes).unwrap();
-        assert_eq!(parsed.definition.name, snapshot.definition.name);
-    }
-
-    #[test]
-    fn png_snapshot_transcodes_jpeg_avatar_into_image_body() {
-        let avatar = image::DynamicImage::ImageRgb8(image::RgbImage::from_pixel(
-            3,
-            2,
-            image::Rgb([0x12, 0x34, 0x56]),
-        ));
-        let mut jpeg_bytes = Vec::new();
-        avatar
-            .write_to(&mut Cursor::new(&mut jpeg_bytes), image::ImageFormat::Jpeg)
-            .unwrap();
-
-        let snapshot = build_snapshot(
-            &minimal_record(),
-            MemoryLevel::None,
-            vec![],
-            Some(&jpeg_bytes),
-        );
-        let png_bytes = encode_snapshot_png(&snapshot, Some(&jpeg_bytes)).unwrap();
-        let decoder = Decoder::new(Cursor::new(png_bytes));
-        let reader = decoder.read_info().unwrap();
-
-        assert_eq!((reader.info().width, reader.info().height), (3, 2));
-    }
-
-    // ── PNG memory parity ─────────────────────────────────────────────────────
-
-    #[test]
-    fn png_round_trip_with_core_memory() {
-        let record = minimal_record();
-        let entries = vec![AgentSnapshotMemoryEntry {
-            slug: "core".to_string(),
-            body: "remember this".to_string(),
-        }];
-        let snapshot = build_snapshot(&record, MemoryLevel::Core, entries, None);
-
-        let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
-        let parsed = decode_snapshot_png(&png_bytes).unwrap();
-
-        assert_eq!(parsed.memory, snapshot.memory);
-    }
-
-    #[test]
-    fn png_round_trip_with_everything_memory() {
-        let record = minimal_record();
-        let entries = vec![
-            AgentSnapshotMemoryEntry {
-                slug: "core".to_string(),
-                body: "remember this".to_string(),
-            },
-            AgentSnapshotMemoryEntry {
-                slug: "mem/notes".to_string(),
-                body: "private notes".to_string(),
-            },
-        ];
-        let snapshot = build_snapshot(&record, MemoryLevel::Everything, entries, None);
-
-        let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
-        let parsed = decode_snapshot_png(&png_bytes).unwrap();
-
-        assert_eq!(parsed.memory, snapshot.memory);
-    }
-
-    #[test]
-    fn png_export_with_no_memory_succeeds() {
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
-        assert!(encode_snapshot_png(&snapshot, None).is_ok());
-    }
-
-    #[test]
-    fn png_export_rejects_none_level_with_nonempty_entries() {
-        // Inconsistent state: level == None but entries is non-empty.
-        // The encoder must reject this to prevent a memory-leak bypass.
-        let record = minimal_record();
-        let entries = vec![AgentSnapshotMemoryEntry {
-            slug: "core".to_string(),
-            body: "leaked memory".to_string(),
-        }];
-        // Build with entries, then override level to None in the struct.
-        let mut snapshot = build_snapshot(&record, MemoryLevel::Core, entries, None);
-        snapshot.memory.level = MemoryLevel::None; // force inconsistency
-        let result = encode_snapshot_png(&snapshot, None);
-        assert!(
-            result.is_err(),
-            "PNG encoder must reject level=None with non-empty entries"
-        );
-        assert!(
-            result
-                .unwrap_err()
-                .contains("memory.level 'none' and non-empty memory entries"),
-            "Error must explain the malformed memory state"
-        );
-    }
-
-    // ── Secret exclusion tests ────────────────────────────────────────────────
-    //
-    // These tests assert that every field in the exclusion list is absent from
-    // the serialized snapshot. We serialize to JSON and assert the key is NOT
-    // present.
-
-    fn snapshot_json_string(record: &ManagedAgentRecord) -> String {
-        let snapshot = build_snapshot(record, MemoryLevel::None, vec![], None);
-        let bytes = encode_snapshot_json(&snapshot).unwrap();
-        String::from_utf8(bytes).unwrap()
-    }
-
-    #[test]
-    fn secret_exclusion_private_key_nsec_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("nsec1secret"),
-            "nsec must not appear in snapshot"
-        );
-        assert!(
-            !json.contains("privateKeyNsec") && !json.contains("private_key_nsec"),
-            "privateKeyNsec field must not appear in snapshot"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_auth_tag_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("auth-tag-secret"),
-            "auth_tag value must not appear in snapshot"
-        );
-        assert!(
-            !json.contains("authTag") && !json.contains("auth_tag"),
-            "authTag field must not appear in snapshot"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_env_vars_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("API_KEY") && !json.contains("secret123"),
-            "env_vars content must not appear in snapshot"
-        );
-        assert!(
-            !json.contains("envVars") && !json.contains("env_vars"),
-            "envVars field must not appear in snapshot"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_relay_url_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("wss://relay.example.com"),
-            "relay_url value must not appear in snapshot"
-        );
-        assert!(
-            !json.contains("relayUrl") && !json.contains("relay_url"),
-            "relayUrl field must not appear in snapshot"
-        );
-    }
-
-    #[test]
-    fn snapshot_omits_removed_mcp_toolsets_config() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("mcpToolsets") && !json.contains("mcp_toolsets"),
-            "removed MCP toolsets config must not re-enter snapshots"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_machine_commands_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        // acp_command / agent_command / agent_command_override / agent_args / mcp_command
-        assert!(
-            !json.contains("/usr/local/bin/acp"),
-            "acp_command path must not appear"
-        );
-        assert!(
-            !json.contains("acpCommand") && !json.contains("acp_command"),
-            "acpCommand field must not appear"
-        );
-        assert!(
-            !json.contains("agentCommand") && !json.contains("agent_command"),
-            "agentCommand field must not appear"
-        );
-        assert!(
-            !json.contains("mcpCommand") && !json.contains("mcp_command"),
-            "mcpCommand field must not appear"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_runtime_state_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("runtimePid") && !json.contains("runtime_pid"),
-            "runtimePid must not appear"
-        );
-        assert!(
-            !json.contains("backendAgentId") && !json.contains("backend_agent_id"),
-            "backendAgentId must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_BACKEND_AGENT_ID"),
-            "backendAgentId value must not appear"
-        );
-        assert!(
-            !json.contains("providerBinaryPath") && !json.contains("provider_binary_path"),
-            "providerBinaryPath must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_PROVIDER_BINARY"),
-            "providerBinaryPath value must not appear"
-        );
-        assert!(
-            !json.contains("lastStartedAt") && !json.contains("last_started_at"),
-            "lastStartedAt must not appear"
-        );
-        assert!(
-            !json.contains("lastExitCode") && !json.contains("last_exit_code"),
-            "lastExitCode must not appear"
-        );
-        // backend blob — neither the type tag nor provider secret must leak.
-        assert!(
-            !json.contains("\"backend\"") && !json.contains("backend"),
-            "backend field must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_BACKEND_ID") && !json.contains("SENTINEL_BACKEND_SECRET"),
-            "backend config values must not appear"
-        );
-        // last_error / last_error_code
-        assert!(
-            !json.contains("lastError") && !json.contains("last_error"),
-            "lastError must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_LAST_ERROR"),
-            "lastError value must not appear"
-        );
-        assert!(
-            !json.contains("lastErrorCode") && !json.contains("last_error_code"),
-            "lastErrorCode must not appear"
-        );
-    }
-
-    #[test]
-    fn secret_exclusion_lineage_ids_absent() {
-        let record = minimal_record();
-        let json = snapshot_json_string(&record);
-        assert!(
-            !json.contains("team-id-123"),
-            "source_team value must not appear"
-        );
-        assert!(
-            !json.contains("sourceTeam") && !json.contains("source_team"),
-            "sourceTeam field must not appear"
-        );
-        assert!(
-            !json.contains("sourceTeamPersonaSlug"),
-            "sourceTeamPersonaSlug must not appear"
-        );
-        assert!(
-            !json.contains("personaSourceVersion") && !json.contains("persona_source_version"),
-            "personaSourceVersion must not appear"
-        );
-        // personaId
-        assert!(
-            !json.contains("personaId") && !json.contains("persona_id"),
-            "personaId field must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_PERSONA_ID"),
-            "personaId value must not appear"
-        );
-        // teamId
-        assert!(
-            !json.contains("teamId") && !json.contains("team_id"),
-            "teamId field must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_TEAM_ID"),
-            "teamId value must not appear"
-        );
-        // personaTeamDir
-        assert!(
-            !json.contains("personaTeamDir") && !json.contains("persona_team_dir"),
-            "personaTeamDir field must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_TEAM_DIR"),
-            "personaTeamDir value must not appear"
-        );
-        // personaNameInTeam
-        assert!(
-            !json.contains("personaNameInTeam") && !json.contains("persona_name_in_team"),
-            "personaNameInTeam field must not appear"
-        );
-        assert!(
-            !json.contains("SENTINEL_NAME_IN_TEAM"),
-            "personaNameInTeam value must not appear"
-        );
-    }
-
-    // ── Definition field presence tests ──────────────────────────────────────
-
-    #[test]
-    fn definition_fields_present_in_snapshot() {
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
-
-        assert_eq!(snapshot.definition.name, "Test Agent Display");
-        assert!(!snapshot.definition.source_is_builtin);
-        assert_eq!(
-            snapshot.definition.system_prompt.as_deref(),
-            Some("You are a test agent.")
-        );
-        assert_eq!(snapshot.definition.runtime.as_deref(), Some("goose"));
-        assert_eq!(snapshot.definition.model.as_deref(), Some("claude-opus-4"));
-        assert_eq!(snapshot.definition.provider.as_deref(), Some("anthropic"));
-        assert_eq!(snapshot.definition.name_pool, vec!["Alice", "Bob"]);
-        // definition_respond_to maps to respond_to in the snapshot definition
-        assert_eq!(snapshot.definition.respond_to.as_deref(), Some("allowlist"));
-        // definition_respond_to_allowlist should be included
-        assert!(!snapshot.definition.respond_to_allowlist.is_empty());
-    }
-
-    #[test]
-    fn profile_fields_present_in_snapshot() {
-        let record = minimal_record();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
-        assert_eq!(snapshot.profile.display_name, "Test Agent Display");
-        // No bytes → should fall back to avatar_url
-        assert_eq!(
-            snapshot.profile.avatar_url.as_deref(),
-            Some("https://example.com/avatar.png")
-        );
-        assert!(snapshot.profile.avatar_data_url.is_none());
-    }
-
-    #[test]
-    fn avatar_inlined_when_under_size_limit() {
-        let record = minimal_record();
-        let small_png = make_png_with_text("k", "v").unwrap();
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&small_png));
-        assert!(snapshot.profile.avatar_data_url.is_some());
-        assert!(snapshot.profile.avatar_url.is_none());
-    }
-
-    #[test]
-    fn avatar_url_fallback_when_over_size_limit() {
-        let mut record = minimal_record();
-        record.avatar_url = Some("https://example.com/big.png".to_string());
-        // Synthesize oversized avatar bytes (> 2 MB) — just a large zeroed vec.
-        let big_bytes = vec![0u8; MAX_AVATAR_INLINE_BYTES + 1];
-        let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&big_bytes));
-        assert!(snapshot.profile.avatar_data_url.is_none());
-        assert_eq!(
-            snapshot.profile.avatar_url.as_deref(),
-            Some("https://example.com/big.png")
-        );
-    }
-
-    // ── Format/version validation ─────────────────────────────────────────────
-
-    #[test]
-    fn invalid_format_discriminator_is_rejected() {
-        let mut snapshot = build_snapshot(&minimal_record(), MemoryLevel::None, vec![], None);
-        snapshot.format = "not-a-buzz-snapshot".to_string();
-        let bytes = serde_json::to_vec(&snapshot).unwrap();
-        let result = decode_snapshot_json(&bytes);
-        assert!(result.is_err());
-        assert!(result.unwrap_err().contains("Unsupported snapshot format"));
-    }
-
-    #[test]
-    fn unsupported_version_is_rejected() {
-        let mut snapshot = build_snapshot(&minimal_record(), MemoryLevel::None, vec![], None);
-        snapshot.version = 99;
-        let bytes = serde_json::to_vec(&snapshot).unwrap();
-        let result = decode_snapshot_json(&bytes);
-        assert!(result.is_err());
-        assert!(result.unwrap_err().contains("Unsupported snapshot version"));
-    }
-}
+#[path = "agent_snapshot_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/managed_agents/agent_snapshot_envelope.rs b/desktop/src-tauri/src/managed_agents/agent_snapshot_envelope.rs
new file mode 100644
index 0000000000..8508c27073
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/agent_snapshot_envelope.rs
@@ -0,0 +1,638 @@
+//! Locked (encrypted) agent-card envelope — NIP-44 v2 over the snapshot manifest.
+//!
+//! A locked card carries the same `buzz_agent_snapshot` tEXt chunk as a plain
+//! card, but the chunk JSON is a typed outer envelope whose ciphertext
+//! decrypts to the ordinary manifest. The NIP-44 v2 conversation key is
+//! symmetric over the (owner, agent) pair, so BOTH the owner's and the
+//! agent's nsec decrypt the card — nobody else's does (NIP-AE's scheme).
+//!
+//! Wire contract (agreed with Wren, buzz-agent-trading-cards thread):
+//! - Plain cards keep today's exact bytes; detection dispatches once on the
+//!   exact `format` discriminator and rejects unknown versions/schemes
+//!   rather than falling through to manifest parsing.
+//! - Key lookup is exact-endpoint only: the owner identity key when its
+//!   pubkey equals `ownerPubkey`, or a hydrated local managed-agent record
+//!   whose record pubkey AND derived-secret pubkey equal `agentPubkey`.
+//!   No trial decryption; anything else fails closed as locked.
+//! - Caps beyond the outer 10 MiB PNG gate: 65,535-byte NIP-44 plaintext
+//!   limit on the serialized manifest BEFORE encryption; envelope JSON and
+//!   ciphertext are capped before serde/base64/decrypt work; decrypted bytes
+//!   are capped before snapshot parsing.
+//! - Decrypt/auth failures return only the locked-card refusal — never
+//!   partial plaintext or crypto details.
+
+use buzz_core_pkg::engram::NIP44_PLAINTEXT_MAX;
+use nostr::nips::nip44::{self, Version};
+use nostr::{Keys, PublicKey, SecretKey};
+use serde::{Deserialize, Serialize};
+
+use super::agent_snapshot::{
+    decode_snapshot_json, encode_chunk_payload_png, encode_snapshot_json, AgentSnapshot,
+    MemoryLevel, FORMAT_DISCRIMINATOR,
+};
+use super::types::ManagedAgentRecord;
+
+/// Discriminator for the locked envelope. Distinct from the plain manifest's
+/// `buzz-agent-snapshot` so detection never guesses.
+pub const LOCKED_FORMAT: &str = "buzz-agent-snapshot-encrypted";
+/// Envelope schema version this module produces and accepts.
+pub const LOCKED_VERSION: u32 = 1;
+/// Encryption scheme identifier this module produces and accepts.
+pub const LOCKED_SCHEME: &str = "nip44-v2";
+
+/// A max-size NIP-44 v2 payload (1 version + 32 nonce + 2 len + 65,536
+/// padded + 32 MAC = 65,603 bytes) base64-encodes to 87,472 chars.
+/// Anything larger is rejected before base64/decrypt work.
+pub const MAX_LOCKED_CIPHERTEXT_BYTES: usize = 90_000;
+/// Envelope JSON = ciphertext + two pubkeys + fixed keys. Rejected before
+/// typed deserialization.
+pub const MAX_LOCKED_ENVELOPE_JSON_BYTES: usize = MAX_LOCKED_CIPHERTEXT_BYTES + 1024;
+
+/// The only error a failed unlock may surface. Deliberately says nothing
+/// about which key was tried or why decryption failed.
+pub const LOCKED_CARD_REFUSAL: &str =
+    "This card is locked to its owner and agent. Only they can import it.";
+
+// ── Envelope types ────────────────────────────────────────────────────────────
+
+/// Typed outer envelope stored (base64 JSON) in the `buzz_agent_snapshot`
+/// chunk of a locked card.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct LockedSnapshotEnvelope {
+    /// Always [`LOCKED_FORMAT`].
+    pub format: String,
+    /// Always [`LOCKED_VERSION`].
+    pub version: u32,
+    pub encryption: LockedEncryption,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct LockedEncryption {
+    /// Always [`LOCKED_SCHEME`].
+    pub scheme: String,
+    /// Owner identity pubkey (64 lowercase hex). Plaintext so a decryptor
+    /// knows which counterparty to pair with.
+    pub owner_pubkey: String,
+    /// Agent instance pubkey (64 lowercase hex).
+    pub agent_pubkey: String,
+    /// NIP-44 v2 ciphertext (base64) of the plain manifest JSON.
+    pub ciphertext: String,
+}
+
+/// Result of parsing a chunk payload: either today's plain manifest or a
+/// validated locked envelope. The plain manifest is boxed because it may
+/// inline a multi-KB avatar data URL, dwarfing the envelope variant.
+#[derive(Debug)]
+pub enum ChunkPayload {
+    Plain(Box<AgentSnapshot>),
+    Locked(LockedSnapshotEnvelope),
+}
+
+/// Minimal probe used to read the `format` discriminator without building a
+/// full JSON tree for large plain manifests.
+#[derive(Deserialize)]
+struct FormatProbe {
+    #[serde(default)]
+    format: Option<String>,
+}
+
+// ── Validation ────────────────────────────────────────────────────────────────
+
+/// Canonical pubkey check: exactly 64 lowercase hex chars that parse as a
+/// valid x-only pubkey. Lowercase is required so string comparisons against
+/// record pubkeys (always `to_hex()` output) stay sound. Curve validation is
+/// explicit: nostr's `PublicKey::from_hex` only decodes 32 bytes and defers
+/// lift-x validation to `xonly()`, so a non-point like `"f" * 64` would
+/// otherwise pass structurally and fail only at decrypt time.
+pub(crate) fn parse_canonical_pubkey(field: &str, value: &str) -> Result<PublicKey, String> {
+    if value.len() != 64
+        || !value
+            .chars()
+            .all(|c| c.is_ascii_digit() || ('a'..='f').contains(&c))
+    {
+        return Err(format!(
+            "Locked card envelope has a malformed {field} (expected 64 lowercase hex chars)."
+        ));
+    }
+    let pubkey = PublicKey::from_hex(value)
+        .map_err(|_| format!("Locked card envelope has an invalid {field}."))?;
+    pubkey
+        .xonly()
+        .map_err(|_| format!("Locked card envelope has an invalid {field} (not a curve point)."))?;
+    Ok(pubkey)
+}
+
+/// Structural validation of a locked envelope: exact version + scheme,
+/// canonical pubkeys, distinct endpoints, bounded ciphertext. Does no
+/// key lookup or crypto.
+pub fn validate_envelope(
+    envelope: &LockedSnapshotEnvelope,
+) -> Result<(PublicKey, PublicKey), String> {
+    if envelope.format != LOCKED_FORMAT {
+        return Err(format!(
+            "Unsupported locked card format: {:?} (expected {LOCKED_FORMAT:?})",
+            envelope.format
+        ));
+    }
+    if envelope.version != LOCKED_VERSION {
+        return Err(format!(
+            "Unsupported locked card envelope version: {} (expected {LOCKED_VERSION})",
+            envelope.version
+        ));
+    }
+    if envelope.encryption.scheme != LOCKED_SCHEME {
+        return Err(format!(
+            "Unsupported locked card encryption scheme: {:?} (expected {LOCKED_SCHEME:?})",
+            envelope.encryption.scheme
+        ));
+    }
+    let owner = parse_canonical_pubkey("ownerPubkey", &envelope.encryption.owner_pubkey)?;
+    let agent = parse_canonical_pubkey("agentPubkey", &envelope.encryption.agent_pubkey)?;
+    if owner == agent {
+        return Err("Locked card envelope owner and agent pubkeys must differ.".to_string());
+    }
+    if envelope.encryption.ciphertext.len() > MAX_LOCKED_CIPHERTEXT_BYTES {
+        return Err("Locked card ciphertext exceeds the maximum size.".to_string());
+    }
+    if envelope.encryption.ciphertext.is_empty() {
+        return Err("Locked card ciphertext is empty.".to_string());
+    }
+    Ok((owner, agent))
+}
+
+// ── Dispatch ──────────────────────────────────────────────────────────────────
+
+/// Parse a raw chunk payload (JSON bytes from `extract_chunk_payload_png` or
+/// an `.agent.json` file) and dispatch on the exact `format` discriminator.
+///
+/// - `buzz-agent-snapshot` → full plain-manifest decode + validation.
+/// - `buzz-agent-snapshot-encrypted` → size caps, typed envelope parse,
+///   structural validation. No decryption happens here.
+/// - anything else (including missing `format`) → error, never a fall-through.
+pub fn parse_chunk_payload(json_bytes: &[u8]) -> Result<ChunkPayload, String> {
+    let probe: FormatProbe =
+        serde_json::from_slice(json_bytes).map_err(|e| format!("Invalid snapshot JSON: {e}"))?;
+    match probe.format.as_deref() {
+        Some(f) if f == FORMAT_DISCRIMINATOR => Ok(ChunkPayload::Plain(Box::new(
+            decode_snapshot_json(json_bytes)?,
+        ))),
+        Some(f) if f == LOCKED_FORMAT => {
+            // Cap the envelope JSON before typed deserialization; a locked
+            // envelope is small by construction (unlike plain manifests,
+            // which may inline a multi-MB avatar).
+            if json_bytes.len() > MAX_LOCKED_ENVELOPE_JSON_BYTES {
+                return Err("Locked card envelope exceeds the maximum size.".to_string());
+            }
+            let envelope: LockedSnapshotEnvelope = serde_json::from_slice(json_bytes)
+                .map_err(|e| format!("Invalid locked card envelope: {e}"))?;
+            validate_envelope(&envelope)?;
+            Ok(ChunkPayload::Locked(envelope))
+        }
+        Some(other) => Err(format!("Unsupported snapshot format: {other:?}")),
+        None => Err("Snapshot payload has no format discriminator.".to_string()),
+    }
+}
+
+// ── Encrypt ───────────────────────────────────────────────────────────────────
+
+/// Encrypt a snapshot manifest into a locked envelope under the NIP-44 v2
+/// conversation key for (owner secret, agent pubkey).
+///
+/// Fails clearly (never silently truncates) when the serialized manifest
+/// exceeds the NIP-44 plaintext limit.
+pub fn encrypt_snapshot_envelope(
+    snapshot: &AgentSnapshot,
+    owner_keys: &Keys,
+    agent_pubkey: &PublicKey,
+) -> Result<LockedSnapshotEnvelope, String> {
+    let json_bytes = encode_snapshot_json(snapshot)?;
+    if json_bytes.len() > NIP44_PLAINTEXT_MAX {
+        return Err(format!(
+            "Agent manifest is too large to lock ({} bytes; the encrypted \
+             format caps at {NIP44_PLAINTEXT_MAX}). Reduce the avatar size \
+             or mint an unlocked card.",
+            json_bytes.len()
+        ));
+    }
+    let plaintext = std::str::from_utf8(&json_bytes)
+        .map_err(|e| format!("Manifest JSON was not UTF-8: {e}"))?;
+    let ciphertext = nip44::encrypt(
+        owner_keys.secret_key(),
+        agent_pubkey,
+        plaintext,
+        Version::V2,
+    )
+    .map_err(|e| format!("Failed to encrypt card manifest: {e}"))?;
+
+    Ok(LockedSnapshotEnvelope {
+        format: LOCKED_FORMAT.to_string(),
+        version: LOCKED_VERSION,
+        encryption: LockedEncryption {
+            scheme: LOCKED_SCHEME.to_string(),
+            owner_pubkey: owner_keys.public_key().to_hex(),
+            agent_pubkey: agent_pubkey.to_hex(),
+            ciphertext,
+        },
+    })
+}
+
+/// Encode a snapshot into a LOCKED `.agent.png`: encrypt the manifest into
+/// the envelope, then compose the PNG through the same chunk encoder plain
+/// cards use. Mirrors `encode_snapshot_png`'s structural memory guard.
+pub fn encode_locked_snapshot_png(
+    snapshot: &AgentSnapshot,
+    owner_keys: &Keys,
+    agent_pubkey: &PublicKey,
+    avatar_bytes: Option<&[u8]>,
+) -> Result<Vec<u8>, String> {
+    if snapshot.memory.level == MemoryLevel::None && !snapshot.memory.entries.is_empty() {
+        return Err(
+            "Cannot write a snapshot with memory.level 'none' and non-empty memory entries."
+                .to_string(),
+        );
+    }
+    let envelope = encrypt_snapshot_envelope(snapshot, owner_keys, agent_pubkey)?;
+    let envelope_json = serde_json::to_vec(&envelope)
+        .map_err(|e| format!("Failed to serialize locked card envelope: {e}"))?;
+    encode_chunk_payload_png(&envelope_json, avatar_bytes)
+}
+
+// ── Decrypt ───────────────────────────────────────────────────────────────────
+
+/// Exact-endpoint key resolution (no trial decryption):
+/// - the owner identity secret, only when its pubkey equals `ownerPubkey`;
+/// - a hydrated local managed-agent record whose record pubkey AND
+///   derived-secret pubkey both equal `agentPubkey`.
+///
+/// Returns `None` when neither exact endpoint exists — callers fail closed
+/// with [`LOCKED_CARD_REFUSAL`].
+pub fn resolve_unlock_secret(
+    envelope: &LockedSnapshotEnvelope,
+    owner_keys: Option<&Keys>,
+    records: &[ManagedAgentRecord],
+) -> Option<SecretKey> {
+    if let Some(keys) = owner_keys {
+        if keys.public_key().to_hex() == envelope.encryption.owner_pubkey {
+            return Some(keys.secret_key().clone());
+        }
+    }
+    let record = records
+        .iter()
+        .find(|r| r.pubkey == envelope.encryption.agent_pubkey)?;
+    let agent_keys = Keys::parse(record.private_key_nsec.trim()).ok()?;
+    if agent_keys.public_key().to_hex() != envelope.encryption.agent_pubkey {
+        return None;
+    }
+    Some(agent_keys.secret_key().clone())
+}
+
+/// Decrypt a validated envelope with `my_secret`, which must be one of the
+/// envelope's two exact endpoints (its derived pubkey selects the
+/// counterparty). Returns the decoded, validated snapshot manifest.
+///
+/// Every auth/crypto failure maps to [`LOCKED_CARD_REFUSAL`] — nothing about
+/// the failure mode leaks. Manifest decode errors after a successful decrypt
+/// are surfaced normally (the caller proved key possession).
+pub fn decrypt_envelope(
+    envelope: &LockedSnapshotEnvelope,
+    my_secret: &SecretKey,
+) -> Result<AgentSnapshot, String> {
+    let (owner_pub, agent_pub) = validate_envelope(envelope)?;
+    let my_pub = Keys::new(my_secret.clone()).public_key();
+    let counterparty = if my_pub == owner_pub {
+        agent_pub
+    } else if my_pub == agent_pub {
+        owner_pub
+    } else {
+        return Err(LOCKED_CARD_REFUSAL.to_string());
+    };
+
+    let plaintext = nip44::decrypt(my_secret, &counterparty, &envelope.encryption.ciphertext)
+        .map_err(|_| LOCKED_CARD_REFUSAL.to_string())?;
+    if plaintext.len() > NIP44_PLAINTEXT_MAX {
+        return Err(LOCKED_CARD_REFUSAL.to_string());
+    }
+    decode_snapshot_json(plaintext.as_bytes())
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::managed_agents::agent_snapshot::{
+        extract_chunk_payload_png, AgentSnapshotDefinition, AgentSnapshotMemory,
+        AgentSnapshotProfile, FORMAT_VERSION,
+    };
+
+    fn sample_snapshot() -> AgentSnapshot {
+        AgentSnapshot {
+            format: FORMAT_DISCRIMINATOR.to_string(),
+            version: FORMAT_VERSION,
+            definition: AgentSnapshotDefinition {
+                name: "Locked Test".to_string(),
+                system_prompt: Some("You are a locked test agent.".to_string()),
+                runtime: None,
+                model: None,
+                provider: None,
+                parallelism: Some(1),
+                respond_to: None,
+                respond_to_allowlist: Vec::new(),
+                name_pool: Vec::new(),
+                idle_timeout_seconds: None,
+                max_turn_duration_seconds: None,
+                source_is_builtin: false,
+            },
+            profile: AgentSnapshotProfile {
+                display_name: "Locked Test".to_string(),
+                about: None,
+                avatar_data_url: None,
+                avatar_url: None,
+            },
+            memory: AgentSnapshotMemory {
+                level: MemoryLevel::None,
+                entries: Vec::new(),
+            },
+        }
+    }
+
+    fn owner_agent_keys() -> (Keys, Keys) {
+        (Keys::generate(), Keys::generate())
+    }
+
+    /// Minimal hydrated record for endpoint-resolution tests. Only the
+    /// pubkey/nsec pair matters here.
+    fn record_with_keys(pubkey: String, private_key_nsec: String) -> ManagedAgentRecord {
+        ManagedAgentRecord {
+            pubkey,
+            name: "Locked Test".to_string(),
+            persona_id: None,
+            private_key_nsec,
+            auth_tag: None,
+            relay_url: "ws://localhost:3000".to_string(),
+            avatar_url: None,
+            acp_command: "buzz-acp".to_string(),
+            agent_command: "goose".to_string(),
+            agent_args: vec![],
+            mcp_command: String::new(),
+            turn_timeout_seconds: 300,
+            idle_timeout_seconds: None,
+            max_turn_duration_seconds: None,
+            parallelism: 1,
+            system_prompt: None,
+            model: None,
+            env_vars: std::collections::BTreeMap::new(),
+            start_on_app_launch: false,
+            auto_restart_on_config_change: true,
+            runtime_pid: None,
+            backend: crate::managed_agents::types::BackendKind::Local,
+            backend_agent_id: None,
+            provider_binary_path: None,
+            team_id: None,
+            persona_team_dir: None,
+            persona_name_in_team: None,
+            created_at: String::new(),
+            updated_at: String::new(),
+            last_started_at: None,
+            last_stopped_at: None,
+            last_exit_code: None,
+            last_error: None,
+            last_error_code: None,
+            respond_to: crate::managed_agents::types::RespondTo::OwnerOnly,
+            respond_to_allowlist: vec![],
+            display_name: None,
+            slug: None,
+            runtime: None,
+            name_pool: Vec::new(),
+            is_builtin: false,
+            is_active: true,
+            shared: false,
+            source_team: None,
+            source_team_persona_slug: None,
+            catalog_source: None,
+            definition_respond_to: None,
+            definition_respond_to_allowlist: Vec::new(),
+            definition_parallelism: None,
+            relay_mesh: None,
+            agent_command_override: None,
+            persona_source_version: None,
+            provider: None,
+        }
+    }
+
+    fn locked_envelope() -> (LockedSnapshotEnvelope, Keys, Keys) {
+        let (owner, agent) = owner_agent_keys();
+        let env =
+            encrypt_snapshot_envelope(&sample_snapshot(), &owner, &agent.public_key()).unwrap();
+        (env, owner, agent)
+    }
+
+    #[test]
+    fn owner_secret_decrypts() {
+        let (env, owner, _agent) = locked_envelope();
+        let decoded = decrypt_envelope(&env, owner.secret_key()).unwrap();
+        assert_eq!(decoded, sample_snapshot());
+    }
+
+    #[test]
+    fn agent_secret_decrypts() {
+        let (env, _owner, agent) = locked_envelope();
+        let decoded = decrypt_envelope(&env, agent.secret_key()).unwrap();
+        assert_eq!(decoded, sample_snapshot());
+    }
+
+    #[test]
+    fn unrelated_key_fails_closed_with_refusal_only() {
+        let (env, _owner, _agent) = locked_envelope();
+        let stranger = Keys::generate();
+        let err = decrypt_envelope(&env, stranger.secret_key()).unwrap_err();
+        assert_eq!(err, LOCKED_CARD_REFUSAL);
+    }
+
+    #[test]
+    fn tampered_ciphertext_fails_with_refusal_only() {
+        let (mut env, owner, _agent) = locked_envelope();
+        // Flip a character mid-ciphertext (keep valid base64 alphabet).
+        let mid = env.encryption.ciphertext.len() / 2;
+        let mut bytes = env.encryption.ciphertext.into_bytes();
+        bytes[mid] = if bytes[mid] == b'A' { b'B' } else { b'A' };
+        env.encryption.ciphertext = String::from_utf8(bytes).unwrap();
+        let err = decrypt_envelope(&env, owner.secret_key()).unwrap_err();
+        assert_eq!(err, LOCKED_CARD_REFUSAL);
+    }
+
+    #[test]
+    fn swapped_pubkeys_fail_closed_at_endpoint_resolution() {
+        let (mut env, owner, agent) = locked_envelope();
+        std::mem::swap(
+            &mut env.encryption.owner_pubkey,
+            &mut env.encryption.agent_pubkey,
+        );
+        // The NIP-44 conversation key is symmetric over the pair, so a swap
+        // cannot grant a stranger anything — but it desyncs the routing
+        // hints, and exact-endpoint resolution fails closed rather than
+        // guessing: the owner identity no longer matches `ownerPubkey`, and
+        // no local record holds the pubkey now in `agentPubkey`.
+        assert!(resolve_unlock_secret(&env, Some(&owner), &[]).is_none());
+        let nsec = nostr::ToBech32::to_bech32(agent.secret_key()).unwrap();
+        let record = record_with_keys(agent.public_key().to_hex(), nsec);
+        assert!(resolve_unlock_secret(&env, None, std::slice::from_ref(&record)).is_none());
+    }
+
+    #[test]
+    fn mislabeled_pubkey_fails_decryption_with_refusal_only() {
+        // Replacing `agentPubkey` with a third party's key makes the owner
+        // derive the wrong conversation key — the NIP-44 MAC fails and only
+        // the refusal surfaces.
+        let (mut env, owner, _agent) = locked_envelope();
+        env.encryption.agent_pubkey = Keys::generate().public_key().to_hex();
+        let err = decrypt_envelope(&env, owner.secret_key()).unwrap_err();
+        assert_eq!(err, LOCKED_CARD_REFUSAL);
+    }
+
+    #[test]
+    fn malformed_pubkeys_rejected_structurally() {
+        let (env, _owner, _agent) = locked_envelope();
+
+        let mut short = env.clone();
+        short.encryption.owner_pubkey = "abc123".to_string();
+        assert!(validate_envelope(&short).unwrap_err().contains("malformed"));
+
+        let mut upper = env.clone();
+        upper.encryption.agent_pubkey = upper.encryption.agent_pubkey.to_uppercase();
+        assert!(validate_envelope(&upper).unwrap_err().contains("malformed"));
+
+        // A 64-hex string that is not a curve point (lift-x fails for
+        // x = p-1... all-f) must be rejected STRUCTURALLY — before any key
+        // lookup or decrypt work — per the wire contract.
+        let mut not_a_point = env.clone();
+        not_a_point.encryption.agent_pubkey = "f".repeat(64);
+        assert!(validate_envelope(&not_a_point)
+            .unwrap_err()
+            .contains("not a curve point"));
+
+        let mut same = env;
+        same.encryption.agent_pubkey = same.encryption.owner_pubkey.clone();
+        assert!(validate_envelope(&same).unwrap_err().contains("differ"));
+    }
+
+    #[test]
+    fn unknown_format_version_scheme_rejected() {
+        let (env, ..) = locked_envelope();
+
+        let mut bad_version = env.clone();
+        bad_version.version = 2;
+        assert!(validate_envelope(&bad_version)
+            .unwrap_err()
+            .contains("version"));
+
+        let mut bad_scheme = env.clone();
+        bad_scheme.encryption.scheme = "nip44-v3".to_string();
+        assert!(validate_envelope(&bad_scheme)
+            .unwrap_err()
+            .contains("scheme"));
+
+        // Unknown top-level format never falls through to manifest parsing.
+        let unknown = serde_json::json!({"format": "buzz-agent-snapshot-v9", "version": 1});
+        let err = parse_chunk_payload(unknown.to_string().as_bytes()).unwrap_err();
+        assert!(err.contains("Unsupported snapshot format"), "{err}");
+
+        let missing = serde_json::json!({"version": 1});
+        let err = parse_chunk_payload(missing.to_string().as_bytes()).unwrap_err();
+        assert!(err.contains("no format discriminator"), "{err}");
+    }
+
+    #[test]
+    fn plaintext_cap_enforced_before_encryption() {
+        let (owner, agent) = owner_agent_keys();
+        let mut snapshot = sample_snapshot();
+        // Inflate the manifest beyond the NIP-44 plaintext limit.
+        snapshot.definition.system_prompt = Some("x".repeat(NIP44_PLAINTEXT_MAX));
+        let err = encrypt_snapshot_envelope(&snapshot, &owner, &agent.public_key()).unwrap_err();
+        assert!(err.contains("too large to lock"), "{err}");
+    }
+
+    #[test]
+    fn ciphertext_and_envelope_caps_enforced_before_crypto() {
+        let (mut env, ..) = locked_envelope();
+        env.encryption.ciphertext = "A".repeat(MAX_LOCKED_CIPHERTEXT_BYTES + 1);
+        assert!(validate_envelope(&env)
+            .unwrap_err()
+            .contains("maximum size"));
+
+        // Oversized envelope JSON is rejected before typed deserialization.
+        let huge = format!(
+            r#"{{"format":"{LOCKED_FORMAT}","version":1,"pad":"{}","encryption":{{}}}}"#,
+            "p".repeat(MAX_LOCKED_ENVELOPE_JSON_BYTES)
+        );
+        let err = parse_chunk_payload(huge.as_bytes()).unwrap_err();
+        assert!(err.contains("maximum size"), "{err}");
+    }
+
+    #[test]
+    fn locked_png_round_trips_through_chunk_and_decrypt() {
+        let (owner, agent) = owner_agent_keys();
+        let snapshot = sample_snapshot();
+        let png = encode_locked_snapshot_png(&snapshot, &owner, &agent.public_key(), None).unwrap();
+
+        let payload = extract_chunk_payload_png(&png).unwrap();
+        let ChunkPayload::Locked(env) = parse_chunk_payload(&payload).unwrap() else {
+            panic!("locked PNG must parse as a locked envelope");
+        };
+        // Both endpoints decrypt to the same logical manifest (compare
+        // manifests, never ciphertext — the NIP-44 nonce is random).
+        assert_eq!(
+            decrypt_envelope(&env, owner.secret_key()).unwrap(),
+            snapshot
+        );
+        assert_eq!(
+            decrypt_envelope(&env, agent.secret_key()).unwrap(),
+            snapshot
+        );
+    }
+
+    #[test]
+    fn plain_manifest_dispatches_to_plain() {
+        let json = encode_snapshot_json(&sample_snapshot()).unwrap();
+        let ChunkPayload::Plain(decoded) = parse_chunk_payload(&json).unwrap() else {
+            panic!("plain manifest must parse as Plain");
+        };
+        assert_eq!(*decoded, sample_snapshot());
+    }
+
+    #[test]
+    fn resolve_unlock_secret_owner_exact_endpoint() {
+        let (env, owner, _agent) = locked_envelope();
+        let secret = resolve_unlock_secret(&env, Some(&owner), &[]).unwrap();
+        assert_eq!(&secret, owner.secret_key());
+
+        // A different identity key is NOT tried.
+        let other = Keys::generate();
+        assert!(resolve_unlock_secret(&env, Some(&other), &[]).is_none());
+        assert!(resolve_unlock_secret(&env, None, &[]).is_none());
+    }
+
+    #[test]
+    fn resolve_unlock_secret_agent_requires_record_and_derived_match() {
+        let (env, _owner, agent) = locked_envelope();
+        let nsec = nostr::ToBech32::to_bech32(agent.secret_key()).unwrap();
+
+        let record = record_with_keys(agent.public_key().to_hex(), nsec);
+        let secret = resolve_unlock_secret(&env, None, std::slice::from_ref(&record)).unwrap();
+        assert_eq!(&secret, agent.secret_key());
+
+        // Record pubkey matches but the stored secret derives a DIFFERENT
+        // pubkey → refused (no trial decryption on mismatched material).
+        let mut forged = record.clone();
+        forged.private_key_nsec =
+            nostr::ToBech32::to_bech32(Keys::generate().secret_key()).unwrap();
+        assert!(resolve_unlock_secret(&env, None, std::slice::from_ref(&forged)).is_none());
+
+        // Record for some other agent → not an endpoint.
+        let mut unrelated = record;
+        unrelated.pubkey = Keys::generate().public_key().to_hex();
+        assert!(resolve_unlock_secret(&env, None, std::slice::from_ref(&unrelated)).is_none());
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/agent_snapshot_tests.rs b/desktop/src-tauri/src/managed_agents/agent_snapshot_tests.rs
new file mode 100644
index 0000000000..b4492418e5
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/agent_snapshot_tests.rs
@@ -0,0 +1,599 @@
+//! Unit tests for `managed_agents/agent_snapshot.rs`.
+//!
+//! Kept in a sibling file so `agent_snapshot.rs` stays under the
+//! 1000-line gate; `#[path]`-included from there.
+
+use super::*;
+use crate::managed_agents::types::{BackendKind, ManagedAgentRecord, RespondTo};
+use std::collections::BTreeMap;
+
+/// Build a minimal `ManagedAgentRecord` for testing. Only the fields
+/// relevant to snapshot export are filled; the rest use defaults.
+fn minimal_record() -> ManagedAgentRecord {
+    ManagedAgentRecord {
+        pubkey: "deadbeef".to_string(),
+        name: "Test Agent".to_string(),
+        display_name: Some("Test Agent Display".to_string()),
+        persona_id: Some("SENTINEL_PERSONA_ID".to_string()), // MUST NOT appear in snapshot
+        team_id: Some("SENTINEL_TEAM_ID".to_string()),       // MUST NOT appear in snapshot
+        private_key_nsec: "nsec1secret".to_string(),         // MUST NOT appear in snapshot
+        auth_tag: Some("auth-tag-secret".to_string()),       // MUST NOT appear in snapshot
+        relay_url: "wss://relay.example.com".to_string(),    // MUST NOT appear in snapshot
+        avatar_url: Some("https://example.com/avatar.png".to_string()),
+        acp_command: "/usr/local/bin/acp".to_string(), // MUST NOT appear in snapshot
+        agent_command: "goose".to_string(),            // MUST NOT appear in snapshot
+        agent_command_override: Some("goose-override".to_string()), // MUST NOT appear
+        agent_args: vec!["--arg".to_string()],         // MUST NOT appear in snapshot
+        mcp_command: "mcp-server".to_string(),         // MUST NOT appear in snapshot
+        turn_timeout_seconds: 120,                     // deprecated, MUST NOT appear
+        idle_timeout_seconds: Some(30),
+        max_turn_duration_seconds: Some(600),
+        parallelism: 2,
+        system_prompt: Some("You are a test agent.".to_string()),
+        model: Some("claude-opus-4".to_string()),
+        provider: Some("anthropic".to_string()),
+        persona_source_version: Some("v1.0".to_string()), // MUST NOT appear
+        env_vars: {
+            let mut m = BTreeMap::new();
+            m.insert("API_KEY".to_string(), "secret123".to_string()); // MUST NOT appear
+            m
+        },
+        start_on_app_launch: true,
+        auto_restart_on_config_change: true,
+        runtime_pid: Some(12345), // MUST NOT appear
+        backend: BackendKind::Provider {
+            // MUST NOT appear — carries a provider secret
+            id: "SENTINEL_BACKEND_ID".to_string(),
+            config: serde_json::json!({"api_key": "SENTINEL_BACKEND_SECRET"}),
+        },
+        backend_agent_id: Some("SENTINEL_BACKEND_AGENT_ID".to_string()), // MUST NOT appear
+        provider_binary_path: Some("/usr/bin/SENTINEL_PROVIDER_BINARY".to_string()), // MUST NOT appear
+        persona_team_dir: Some(std::path::PathBuf::from("SENTINEL_TEAM_DIR")), // MUST NOT appear
+        persona_name_in_team: Some("SENTINEL_NAME_IN_TEAM".to_string()),       // MUST NOT appear
+        created_at: "2024-01-01T00:00:00Z".to_string(),
+        updated_at: "2024-01-02T00:00:00Z".to_string(),
+        last_started_at: Some("2024-01-03T00:00:00Z".to_string()), // MUST NOT appear
+        last_stopped_at: None,
+        last_exit_code: Some(0), // MUST NOT appear
+        last_error: Some("SENTINEL_LAST_ERROR".to_string()), // MUST NOT appear
+        last_error_code: Some(42), // MUST NOT appear
+        respond_to: RespondTo::default(),
+        respond_to_allowlist: vec!["pubkey1hex".to_string()],
+        slug: Some("test-agent".to_string()),
+        runtime: Some("goose".to_string()),
+        name_pool: vec!["Alice".to_string(), "Bob".to_string()],
+        is_builtin: false,
+        is_active: true,
+        shared: false,
+        source_team: Some("team-id-123".to_string()), // MUST NOT appear
+        source_team_persona_slug: Some("lep".to_string()), // MUST NOT appear
+        definition_respond_to: Some("allowlist".to_string()),
+        catalog_source: None,
+        definition_respond_to_allowlist: vec!["abc123def".to_string()],
+        definition_parallelism: Some(4),
+        relay_mesh: None,
+    }
+}
+
+// ── Round-trip tests ──────────────────────────────────────────────────────
+
+#[test]
+fn json_round_trip_config_only() {
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+    let bytes = encode_snapshot_json(&snapshot).unwrap();
+    let parsed = decode_snapshot_json(&bytes).unwrap();
+    assert_eq!(parsed, snapshot);
+}
+
+#[test]
+fn json_round_trip_with_memory() {
+    let record = minimal_record();
+    let entries = vec![
+        AgentSnapshotMemoryEntry {
+            slug: "core".to_string(),
+            body: "I am a test agent.".to_string(),
+        },
+        AgentSnapshotMemoryEntry {
+            slug: "mem/research".to_string(),
+            body: "Some research notes.".to_string(),
+        },
+    ];
+    let snapshot = build_snapshot(&record, MemoryLevel::Everything, entries, None);
+    let bytes = encode_snapshot_json(&snapshot).unwrap();
+    let parsed = decode_snapshot_json(&bytes).unwrap();
+    assert_eq!(parsed, snapshot);
+}
+
+#[test]
+fn png_round_trip_no_memory() {
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+    let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
+    let parsed = decode_snapshot_png(&png_bytes).unwrap();
+    assert_eq!(parsed.definition.name, snapshot.definition.name);
+    assert_eq!(parsed.profile.display_name, snapshot.profile.display_name);
+    assert_eq!(parsed.memory.level, MemoryLevel::None);
+}
+
+#[test]
+fn png_round_trip_with_avatar_png() {
+    // Build a minimal PNG avatar.
+    let avatar = make_png_with_text("dummy", "value").unwrap();
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&avatar));
+    // Avatar should be inlined as a data URL.
+    assert!(snapshot
+        .profile
+        .avatar_data_url
+        .as_deref()
+        .unwrap_or("")
+        .starts_with("data:image/png;base64,"));
+
+    let png_bytes = encode_snapshot_png(&snapshot, Some(&avatar)).unwrap();
+    let parsed = decode_snapshot_png(&png_bytes).unwrap();
+    assert_eq!(parsed.definition.name, snapshot.definition.name);
+}
+
+/// Plain-card byte compatibility: `encode_snapshot_png` was refactored
+/// through the shared `encode_chunk_payload_png` when locked cards were
+/// added. Plain cards must emit byte-identical PNGs to the pre-envelope
+/// encoder. This vector reimplements the legacy encoder body verbatim and
+/// asserts equality on all three composition paths: placeholder (no avatar),
+/// PNG-avatar (where tEXt chunk injection ordering matters), and
+/// JPEG-avatar transcode.
+#[test]
+fn plain_encoder_bytes_identical_to_pre_envelope_encoder() {
+    // Verbatim pre-refactor `encode_snapshot_png` body (post memory guard).
+    fn legacy_encode(
+        snapshot: &AgentSnapshot,
+        avatar_bytes: Option<&[u8]>,
+    ) -> Result<Vec<u8>, String> {
+        let json_bytes = encode_snapshot_json(snapshot)?;
+        let chunk_text = STANDARD.encode(&json_bytes);
+        let png_bytes = match avatar_bytes.filter(|bytes| !bytes.is_empty()) {
+            Some(bytes) => {
+                let encoded_avatar = if bytes.starts_with(b"\x89PNG") {
+                    inject_text_chunk(bytes, PNG_CHUNK_KEYWORD, &chunk_text).or_else(|_| {
+                        transcode_avatar_to_png_with_text(bytes, PNG_CHUNK_KEYWORD, &chunk_text)
+                    })
+                } else {
+                    transcode_avatar_to_png_with_text(bytes, PNG_CHUNK_KEYWORD, &chunk_text)
+                };
+                match encoded_avatar {
+                    Ok(png_bytes) => png_bytes,
+                    Err(_) => make_png_with_text(PNG_CHUNK_KEYWORD, &chunk_text)?,
+                }
+            }
+            None => make_png_with_text(PNG_CHUNK_KEYWORD, &chunk_text)?,
+        };
+        Ok(png_bytes)
+    }
+
+    let record = minimal_record();
+
+    // Placeholder path (no avatar).
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+    assert_eq!(
+        encode_snapshot_png(&snapshot, None).unwrap(),
+        legacy_encode(&snapshot, None).unwrap(),
+        "placeholder-path plain PNG bytes must match the pre-envelope encoder"
+    );
+
+    // PNG-avatar path: chunk injected into the avatar image body.
+    let avatar = make_png_with_text("dummy", "value").unwrap();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&avatar));
+    assert_eq!(
+        encode_snapshot_png(&snapshot, Some(&avatar)).unwrap(),
+        legacy_encode(&snapshot, Some(&avatar)).unwrap(),
+        "avatar-path plain PNG bytes must match the pre-envelope encoder"
+    );
+
+    // JPEG-avatar path: transcode-to-PNG composition.
+    let jpeg_avatar = image::DynamicImage::ImageRgb8(image::RgbImage::from_pixel(
+        4,
+        4,
+        image::Rgb([0x10, 0x20, 0x30]),
+    ));
+    let mut jpeg_bytes = Vec::new();
+    jpeg_avatar
+        .write_to(&mut Cursor::new(&mut jpeg_bytes), image::ImageFormat::Jpeg)
+        .unwrap();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&jpeg_bytes));
+    assert_eq!(
+        encode_snapshot_png(&snapshot, Some(&jpeg_bytes)).unwrap(),
+        legacy_encode(&snapshot, Some(&jpeg_bytes)).unwrap(),
+        "transcode-path plain PNG bytes must match the pre-envelope encoder"
+    );
+}
+
+#[test]
+fn png_snapshot_transcodes_jpeg_avatar_into_image_body() {
+    let avatar = image::DynamicImage::ImageRgb8(image::RgbImage::from_pixel(
+        3,
+        2,
+        image::Rgb([0x12, 0x34, 0x56]),
+    ));
+    let mut jpeg_bytes = Vec::new();
+    avatar
+        .write_to(&mut Cursor::new(&mut jpeg_bytes), image::ImageFormat::Jpeg)
+        .unwrap();
+
+    let snapshot = build_snapshot(
+        &minimal_record(),
+        MemoryLevel::None,
+        vec![],
+        Some(&jpeg_bytes),
+    );
+    let png_bytes = encode_snapshot_png(&snapshot, Some(&jpeg_bytes)).unwrap();
+    let decoder = Decoder::new(Cursor::new(png_bytes));
+    let reader = decoder.read_info().unwrap();
+
+    assert_eq!((reader.info().width, reader.info().height), (3, 2));
+}
+
+// ── PNG memory parity ─────────────────────────────────────────────────────
+
+#[test]
+fn png_round_trip_with_core_memory() {
+    let record = minimal_record();
+    let entries = vec![AgentSnapshotMemoryEntry {
+        slug: "core".to_string(),
+        body: "remember this".to_string(),
+    }];
+    let snapshot = build_snapshot(&record, MemoryLevel::Core, entries, None);
+
+    let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
+    let parsed = decode_snapshot_png(&png_bytes).unwrap();
+
+    assert_eq!(parsed.memory, snapshot.memory);
+}
+
+#[test]
+fn png_round_trip_with_everything_memory() {
+    let record = minimal_record();
+    let entries = vec![
+        AgentSnapshotMemoryEntry {
+            slug: "core".to_string(),
+            body: "remember this".to_string(),
+        },
+        AgentSnapshotMemoryEntry {
+            slug: "mem/notes".to_string(),
+            body: "private notes".to_string(),
+        },
+    ];
+    let snapshot = build_snapshot(&record, MemoryLevel::Everything, entries, None);
+
+    let png_bytes = encode_snapshot_png(&snapshot, None).unwrap();
+    let parsed = decode_snapshot_png(&png_bytes).unwrap();
+
+    assert_eq!(parsed.memory, snapshot.memory);
+}
+
+#[test]
+fn png_export_with_no_memory_succeeds() {
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+    assert!(encode_snapshot_png(&snapshot, None).is_ok());
+}
+
+#[test]
+fn png_export_rejects_none_level_with_nonempty_entries() {
+    // Inconsistent state: level == None but entries is non-empty.
+    // The encoder must reject this to prevent a memory-leak bypass.
+    let record = minimal_record();
+    let entries = vec![AgentSnapshotMemoryEntry {
+        slug: "core".to_string(),
+        body: "leaked memory".to_string(),
+    }];
+    // Build with entries, then override level to None in the struct.
+    let mut snapshot = build_snapshot(&record, MemoryLevel::Core, entries, None);
+    snapshot.memory.level = MemoryLevel::None; // force inconsistency
+    let result = encode_snapshot_png(&snapshot, None);
+    assert!(
+        result.is_err(),
+        "PNG encoder must reject level=None with non-empty entries"
+    );
+    assert!(
+        result
+            .unwrap_err()
+            .contains("memory.level 'none' and non-empty memory entries"),
+        "Error must explain the malformed memory state"
+    );
+}
+
+// ── Secret exclusion tests ────────────────────────────────────────────────
+//
+// These tests assert that every field in the exclusion list is absent from
+// the serialized snapshot. We serialize to JSON and assert the key is NOT
+// present.
+
+fn snapshot_json_string(record: &ManagedAgentRecord) -> String {
+    let snapshot = build_snapshot(record, MemoryLevel::None, vec![], None);
+    let bytes = encode_snapshot_json(&snapshot).unwrap();
+    String::from_utf8(bytes).unwrap()
+}
+
+#[test]
+fn secret_exclusion_private_key_nsec_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("nsec1secret"),
+        "nsec must not appear in snapshot"
+    );
+    assert!(
+        !json.contains("privateKeyNsec") && !json.contains("private_key_nsec"),
+        "privateKeyNsec field must not appear in snapshot"
+    );
+}
+
+#[test]
+fn secret_exclusion_auth_tag_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("auth-tag-secret"),
+        "auth_tag value must not appear in snapshot"
+    );
+    assert!(
+        !json.contains("authTag") && !json.contains("auth_tag"),
+        "authTag field must not appear in snapshot"
+    );
+}
+
+#[test]
+fn secret_exclusion_env_vars_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("API_KEY") && !json.contains("secret123"),
+        "env_vars content must not appear in snapshot"
+    );
+    assert!(
+        !json.contains("envVars") && !json.contains("env_vars"),
+        "envVars field must not appear in snapshot"
+    );
+}
+
+#[test]
+fn secret_exclusion_relay_url_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("wss://relay.example.com"),
+        "relay_url value must not appear in snapshot"
+    );
+    assert!(
+        !json.contains("relayUrl") && !json.contains("relay_url"),
+        "relayUrl field must not appear in snapshot"
+    );
+}
+
+#[test]
+fn snapshot_omits_removed_mcp_toolsets_config() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("mcpToolsets") && !json.contains("mcp_toolsets"),
+        "removed MCP toolsets config must not re-enter snapshots"
+    );
+}
+
+#[test]
+fn secret_exclusion_machine_commands_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    // acp_command / agent_command / agent_command_override / agent_args / mcp_command
+    assert!(
+        !json.contains("/usr/local/bin/acp"),
+        "acp_command path must not appear"
+    );
+    assert!(
+        !json.contains("acpCommand") && !json.contains("acp_command"),
+        "acpCommand field must not appear"
+    );
+    assert!(
+        !json.contains("agentCommand") && !json.contains("agent_command"),
+        "agentCommand field must not appear"
+    );
+    assert!(
+        !json.contains("mcpCommand") && !json.contains("mcp_command"),
+        "mcpCommand field must not appear"
+    );
+}
+
+#[test]
+fn secret_exclusion_runtime_state_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("runtimePid") && !json.contains("runtime_pid"),
+        "runtimePid must not appear"
+    );
+    assert!(
+        !json.contains("backendAgentId") && !json.contains("backend_agent_id"),
+        "backendAgentId must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_BACKEND_AGENT_ID"),
+        "backendAgentId value must not appear"
+    );
+    assert!(
+        !json.contains("providerBinaryPath") && !json.contains("provider_binary_path"),
+        "providerBinaryPath must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_PROVIDER_BINARY"),
+        "providerBinaryPath value must not appear"
+    );
+    assert!(
+        !json.contains("lastStartedAt") && !json.contains("last_started_at"),
+        "lastStartedAt must not appear"
+    );
+    assert!(
+        !json.contains("lastExitCode") && !json.contains("last_exit_code"),
+        "lastExitCode must not appear"
+    );
+    // backend blob — neither the type tag nor provider secret must leak.
+    assert!(
+        !json.contains("\"backend\"") && !json.contains("backend"),
+        "backend field must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_BACKEND_ID") && !json.contains("SENTINEL_BACKEND_SECRET"),
+        "backend config values must not appear"
+    );
+    // last_error / last_error_code
+    assert!(
+        !json.contains("lastError") && !json.contains("last_error"),
+        "lastError must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_LAST_ERROR"),
+        "lastError value must not appear"
+    );
+    assert!(
+        !json.contains("lastErrorCode") && !json.contains("last_error_code"),
+        "lastErrorCode must not appear"
+    );
+}
+
+#[test]
+fn secret_exclusion_lineage_ids_absent() {
+    let record = minimal_record();
+    let json = snapshot_json_string(&record);
+    assert!(
+        !json.contains("team-id-123"),
+        "source_team value must not appear"
+    );
+    assert!(
+        !json.contains("sourceTeam") && !json.contains("source_team"),
+        "sourceTeam field must not appear"
+    );
+    assert!(
+        !json.contains("sourceTeamPersonaSlug"),
+        "sourceTeamPersonaSlug must not appear"
+    );
+    assert!(
+        !json.contains("personaSourceVersion") && !json.contains("persona_source_version"),
+        "personaSourceVersion must not appear"
+    );
+    // personaId
+    assert!(
+        !json.contains("personaId") && !json.contains("persona_id"),
+        "personaId field must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_PERSONA_ID"),
+        "personaId value must not appear"
+    );
+    // teamId
+    assert!(
+        !json.contains("teamId") && !json.contains("team_id"),
+        "teamId field must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_TEAM_ID"),
+        "teamId value must not appear"
+    );
+    // personaTeamDir
+    assert!(
+        !json.contains("personaTeamDir") && !json.contains("persona_team_dir"),
+        "personaTeamDir field must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_TEAM_DIR"),
+        "personaTeamDir value must not appear"
+    );
+    // personaNameInTeam
+    assert!(
+        !json.contains("personaNameInTeam") && !json.contains("persona_name_in_team"),
+        "personaNameInTeam field must not appear"
+    );
+    assert!(
+        !json.contains("SENTINEL_NAME_IN_TEAM"),
+        "personaNameInTeam value must not appear"
+    );
+}
+
+// ── Definition field presence tests ──────────────────────────────────────
+
+#[test]
+fn definition_fields_present_in_snapshot() {
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+
+    assert_eq!(snapshot.definition.name, "Test Agent Display");
+    assert!(!snapshot.definition.source_is_builtin);
+    assert_eq!(
+        snapshot.definition.system_prompt.as_deref(),
+        Some("You are a test agent.")
+    );
+    assert_eq!(snapshot.definition.runtime.as_deref(), Some("goose"));
+    assert_eq!(snapshot.definition.model.as_deref(), Some("claude-opus-4"));
+    assert_eq!(snapshot.definition.provider.as_deref(), Some("anthropic"));
+    assert_eq!(snapshot.definition.name_pool, vec!["Alice", "Bob"]);
+    // definition_respond_to maps to respond_to in the snapshot definition
+    assert_eq!(snapshot.definition.respond_to.as_deref(), Some("allowlist"));
+    // definition_respond_to_allowlist should be included
+    assert!(!snapshot.definition.respond_to_allowlist.is_empty());
+}
+
+#[test]
+fn profile_fields_present_in_snapshot() {
+    let record = minimal_record();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], None);
+    assert_eq!(snapshot.profile.display_name, "Test Agent Display");
+    // No bytes → should fall back to avatar_url
+    assert_eq!(
+        snapshot.profile.avatar_url.as_deref(),
+        Some("https://example.com/avatar.png")
+    );
+    assert!(snapshot.profile.avatar_data_url.is_none());
+}
+
+#[test]
+fn avatar_inlined_when_under_size_limit() {
+    let record = minimal_record();
+    let small_png = make_png_with_text("k", "v").unwrap();
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&small_png));
+    assert!(snapshot.profile.avatar_data_url.is_some());
+    assert!(snapshot.profile.avatar_url.is_none());
+}
+
+#[test]
+fn avatar_url_fallback_when_over_size_limit() {
+    let mut record = minimal_record();
+    record.avatar_url = Some("https://example.com/big.png".to_string());
+    // Synthesize oversized avatar bytes (> 2 MB) — just a large zeroed vec.
+    let big_bytes = vec![0u8; MAX_AVATAR_INLINE_BYTES + 1];
+    let snapshot = build_snapshot(&record, MemoryLevel::None, vec![], Some(&big_bytes));
+    assert!(snapshot.profile.avatar_data_url.is_none());
+    assert_eq!(
+        snapshot.profile.avatar_url.as_deref(),
+        Some("https://example.com/big.png")
+    );
+}
+
+// ── Format/version validation ─────────────────────────────────────────────
+
+#[test]
+fn invalid_format_discriminator_is_rejected() {
+    let mut snapshot = build_snapshot(&minimal_record(), MemoryLevel::None, vec![], None);
+    snapshot.format = "not-a-buzz-snapshot".to_string();
+    let bytes = serde_json::to_vec(&snapshot).unwrap();
+    let result = decode_snapshot_json(&bytes);
+    assert!(result.is_err());
+    assert!(result.unwrap_err().contains("Unsupported snapshot format"));
+}
+
+#[test]
+fn unsupported_version_is_rejected() {
+    let mut snapshot = build_snapshot(&minimal_record(), MemoryLevel::None, vec![], None);
+    snapshot.version = 99;
+    let bytes = serde_json::to_vec(&snapshot).unwrap();
+    let result = decode_snapshot_json(&bytes);
+    assert!(result.is_err());
+    assert!(result.unwrap_err().contains("Unsupported snapshot version"));
+}
diff --git a/desktop/src-tauri/src/managed_agents/backend.rs b/desktop/src-tauri/src/managed_agents/backend.rs
index 5debae41cb..84dd7e99da 100644
--- a/desktop/src-tauri/src/managed_agents/backend.rs
+++ b/desktop/src-tauri/src/managed_agents/backend.rs
@@ -1,3 +1,4 @@
+use sha2::{Digest, Sha256};
 use std::io::{BufReader, Read, Write};
 use std::path::{Path, PathBuf};
 use std::sync::mpsc;
@@ -7,6 +8,61 @@ const STDERR_CAP: usize = 65536;
 /// Provider responses should be small JSON objects. Cap stdout to prevent a
 /// buggy or malicious provider from OOM-ing the desktop process.
 const STDOUT_CAP: usize = 1_048_576; // 1 MB
+const PROVIDER_PROTOCOL_VERSION: u64 = 1;
+
+fn validate_provider_info(info: &serde_json::Value) -> Result<(), String> {
+    let object = info
+        .as_object()
+        .ok_or_else(|| "provider info response must be a JSON object".to_string())?;
+    let actual_version = object
+        .get("protocol_version")
+        .and_then(serde_json::Value::as_u64);
+    if actual_version != Some(PROVIDER_PROTOCOL_VERSION) {
+        return Err(match actual_version {
+            Some(version) => format!(
+                "unsupported provider protocol version {version}; desktop requires {PROVIDER_PROTOCOL_VERSION}"
+            ),
+            None => "provider info response missing integer protocol_version".to_string(),
+        });
+    }
+    if object.get("ok") != Some(&serde_json::Value::Bool(true)) {
+        return Err("provider info response must contain ok: true".to_string());
+    }
+    for field in ["name", "version", "description"] {
+        if object
+            .get(field)
+            .is_none_or(|value| value.as_str().is_none_or(str::is_empty))
+        {
+            return Err(format!(
+                "provider info response missing non-empty string {field}"
+            ));
+        }
+    }
+    if !object
+        .get("config_schema")
+        .is_some_and(serde_json::Value::is_object)
+    {
+        return Err("provider info response missing object config_schema".to_string());
+    }
+
+    const FIELDS: &[&str] = &[
+        "ok",
+        "name",
+        "version",
+        "protocol_version",
+        "description",
+        "config_schema",
+    ];
+    if let Some(field) = object
+        .keys()
+        .find(|field| !FIELDS.contains(&field.as_str()))
+    {
+        return Err(format!(
+            "provider info response contains unknown field {field}"
+        ));
+    }
+    Ok(())
+}
 
 /// Invoke a provider binary: write JSON to stdin, read JSON from stdout.
 ///
@@ -333,23 +389,29 @@ pub(crate) fn redact_secrets_with(s: &str, extras: &[&str]) -> String {
     result
 }
 
-/// Collect string values from `request["agent"]["env_vars"]` (if present)
-/// to feed into [`redact_secrets_with`]. Returns an empty Vec if the
-/// request shape doesn't match, which is fine — falls back to the default
-/// prefix-based scrubbing.
+/// Collect string values from every environment map a deploy request can
+/// carry. Providers may echo any of these values in diagnostics, including
+/// definition/baked values that exist only in the resolved launch block.
 fn env_secrets_from_request(request: &serde_json::Value) -> Vec<String> {
-    request
-        .get("agent")
-        .and_then(|a| a.get("env_vars"))
-        .and_then(|e| e.as_object())
-        .map(|obj| {
-            obj.values()
-                .filter_map(|v| v.as_str())
-                .filter(|s| !s.is_empty())
-                .map(String::from)
-                .collect()
-        })
-        .unwrap_or_default()
+    let agent = request.get("agent");
+    let maps = [
+        agent.and_then(|value| value.get("env_vars")),
+        agent
+            .and_then(|value| value.get("launch"))
+            .and_then(|value| value.get("env")),
+        agent
+            .and_then(|value| value.get("launch"))
+            .and_then(|value| value.get("policy_env")),
+    ];
+
+    maps.into_iter()
+        .flatten()
+        .filter_map(serde_json::Value::as_object)
+        .flat_map(|map| map.values())
+        .filter_map(serde_json::Value::as_str)
+        .filter(|value| !value.is_empty())
+        .map(String::from)
+        .collect()
 }
 
 /// Public-in-crate helper: redact every non-empty value from `env` (plus
@@ -368,22 +430,102 @@ pub(crate) fn redact_env_values_in(
     redact_secrets_with(s, &values)
 }
 
-/// Deploy an agent via provider binary. Returns the provider-assigned agent_id.
-///
-/// `request_id` is included for provider-side logging/correlation but is not
-/// validated in the response — the stdin→stdout exchange is 1:1 per process.
+/// Copy a resolved provider into a private staging directory while hashing
+/// exactly the bytes copied. The staged file becomes non-writable before either
+/// invocation, closing the path replacement and in-place rewrite races.
+fn stage_provider(
+    binary: &Path,
+) -> Result<(tempfile::TempDir, PathBuf, String, std::fs::File), String> {
+    let directory = tempfile::Builder::new()
+        .prefix("buzz-provider-")
+        .tempdir()
+        .map_err(|error| format!("failed to create provider staging directory: {error}"))?;
+    let suffix = if cfg!(windows) { ".exe" } else { "" };
+    let staged_path = directory.path().join(format!("provider{suffix}"));
+    let mut source = std::fs::File::open(binary)
+        .map_err(|error| format!("failed to open provider for staging: {error}"))?;
+    let mut staged = std::fs::OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .open(&staged_path)
+        .map_err(|error| format!("failed to create staged provider: {error}"))?;
+    let mut hasher = Sha256::new();
+    let mut buffer = [0_u8; 64 * 1024];
+    loop {
+        let count = source
+            .read(&mut buffer)
+            .map_err(|error| format!("failed to read provider for staging: {error}"))?;
+        if count == 0 {
+            break;
+        }
+        staged
+            .write_all(&buffer[..count])
+            .map_err(|error| format!("failed to write staged provider: {error}"))?;
+        hasher.update(&buffer[..count]);
+    }
+    staged
+        .sync_all()
+        .map_err(|error| format!("failed to sync staged provider: {error}"))?;
+
+    let mut permissions = staged
+        .metadata()
+        .map_err(|error| format!("failed to inspect staged provider: {error}"))?
+        .permissions();
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        permissions.set_mode(0o500);
+    }
+    #[cfg(not(unix))]
+    permissions.set_readonly(true);
+    std::fs::set_permissions(&staged_path, permissions)
+        .map_err(|error| format!("failed to protect staged provider: {error}"))?;
+    drop(staged);
+
+    #[cfg(windows)]
+    let execution_guard = {
+        use std::os::windows::fs::OpenOptionsExt;
+        std::fs::OpenOptions::new()
+            .read(true)
+            // Permit CreateProcess to read the image while denying replacement,
+            // writes, and deletion until both invocations finish.
+            .share_mode(windows_sys::Win32::Storage::FileSystem::FILE_SHARE_READ)
+            .open(&staged_path)
+    };
+    #[cfg(not(windows))]
+    let execution_guard = std::fs::File::open(&staged_path);
+    let execution_guard = execution_guard
+        .map_err(|error| format!("failed to lock staged provider for execution: {error}"))?;
+    Ok((
+        directory,
+        staged_path,
+        hex::encode(hasher.finalize()),
+        execution_guard,
+    ))
+}
+
+/// Deploy through one immutable staged copy: negotiate protocol v1 before the
+/// secret-bearing request, then invoke deploy on those exact same bytes.
 pub fn provider_deploy(
     binary: &Path,
     agent: &serde_json::Value,
     provider_config: &serde_json::Value,
 ) -> Result<String, String> {
+    let (_directory, staged, _digest, _execution_guard) = stage_provider(binary)?;
+    let info_request = serde_json::json!({
+        "op": "info",
+        "request_id": uuid::Uuid::new_v4().to_string(),
+    });
+    let info = invoke_provider(&staged, &info_request, Duration::from_secs(10))?;
+    validate_provider_info(&info)?;
+
     let request = serde_json::json!({
         "op": "deploy",
         "request_id": uuid::Uuid::new_v4().to_string(),
         "agent": agent,
         "provider_config": provider_config,
     });
-    let resp = invoke_provider(binary, &request, Duration::from_secs(600))?;
+    let resp = invoke_provider(&staged, &request, Duration::from_secs(600))?;
     resp["agent_id"]
         .as_str()
         .map(String::from)
@@ -423,6 +565,24 @@ pub fn validate_provider_config(config: &serde_json::Value) -> Result<(), String
     Ok(())
 }
 
+/// Derive a provider id from the filename Tauri stages at runtime. Tauri
+/// removes its target-triple suffix while copying an external binary, but on
+/// Windows leaves the executable/script extension, which is not part of the
+/// provider id.
+fn provider_id_from_filename(name: &str) -> Option<&str> {
+    let raw = name.strip_prefix("buzz-backend-")?;
+    let id = [".exe", ".bat", ".cmd"]
+        .into_iter()
+        .find_map(|extension| {
+            raw.get(raw.len().saturating_sub(extension.len())..)
+                .filter(|suffix| suffix.eq_ignore_ascii_case(extension))
+                .map(|_| &raw[..raw.len() - extension.len()])
+        })
+        .unwrap_or(raw);
+
+    (!id.is_empty()).then_some(id)
+}
+
 /// Enumerate PATH for buzz-backend-* executables. Returns (id, path) pairs.
 /// Only includes files that are executable. Does NOT execute any binaries.
 ///
@@ -464,10 +624,12 @@ pub fn discover_provider_candidates() -> Vec<(String, PathBuf)> {
         };
         for entry in entries.flatten() {
             let name = entry.file_name().to_string_lossy().to_string();
-            if let Some(id) = name.strip_prefix(prefix) {
-                if !id.is_empty() && !seen.contains(&name) && is_executable(&entry.path()) {
-                    seen.insert(name.clone());
-                    results.push((id.to_string(), entry.path()));
+            if name.starts_with(prefix) {
+                if let Some(id) = provider_id_from_filename(&name) {
+                    if !seen.contains(&name) && is_executable(&entry.path()) {
+                        seen.insert(name.clone());
+                        results.push((id.to_string(), entry.path()));
+                    }
                 }
             }
         }
@@ -538,203 +700,5 @@ pub struct BackendProviderInfo {
 }
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn redact_secrets_replaces_nsec() {
-        let s = "key=nsec1abc123def456 other";
-        let r = redact_secrets(s);
-        assert!(r.contains("[REDACTED]"));
-        assert!(!r.contains("nsec1abc123def456"));
-    }
-
-    #[test]
-    fn redact_secrets_replaces_token() {
-        let s = r#"{"token":"sprt_tok_xyz789"}"#;
-        let r = redact_secrets(s);
-        assert!(r.contains("[REDACTED]"));
-        assert!(!r.contains("sprt_tok_xyz789"));
-    }
-
-    #[test]
-    fn redact_secrets_with_extras_scrubs_user_env_values() {
-        // If a provider echoes back a user-supplied API key in its error
-        // output, the desktop must not surface that secret unredacted via
-        // `last_error`. We scrub the literal values that came from the
-        // request's `agent.env_vars`.
-        let secret = "sk-ant-api03-abc123def456";
-        let stderr = format!("auth failed with key {secret} on host api.anthropic.com");
-        let r = redact_secrets_with(&stderr, &[secret]);
-        assert!(r.contains("[REDACTED]"));
-        assert!(!r.contains(secret));
-    }
-
-    #[test]
-    fn redact_secrets_with_extras_skips_short_values() {
-        // Don't scrub values shorter than 4 chars — too noisy.
-        let r = redact_secrets_with("error code: 42", &["42"]);
-        assert!(r.contains("42"));
-    }
-
-    /// GitHub tokens are recognised by shape, so one that never passed through
-    /// our environment — embedded in a remote URL an installer echoes — is
-    /// still scrubbed. The scan runs to the next whitespace or quote, so the
-    /// rest of the URL goes with it; over-redaction is the safe direction.
-    #[test]
-    fn redact_secrets_with_scrubs_github_token_prefixes() {
-        for token in [
-            "ghp_abcdefghij0123456789",
-            "gho_abcdefghij0123456789",
-            "ghu_abcdefghij0123456789",
-            "ghs_abcdefghij0123456789",
-            "ghr_abcdefghij0123456789",
-            "github_pat_abcdefghij0123456789",
-        ] {
-            let r =
-                redact_secrets_with(&format!("cloning https://{token}@github.com/o/r now"), &[]);
-            assert!(!r.contains(token), "leaked {token}: {r}");
-            assert!(r.contains("[REDACTED]"), "got: {r}");
-            assert!(r.contains("cloning"), "scan must stop at whitespace: {r}");
-            assert!(r.ends_with(" now"), "scan must stop at whitespace: {r}");
-        }
-    }
-
-    #[test]
-    fn redact_secrets_with_extras_terminates_when_value_substring_of_marker() {
-        // Regression: an earlier impl used `while let Some(pos) = find(value)`
-        // which never terminates if the user's env value is a substring of
-        // the replacement marker `[REDACTED]` — each replacement
-        // reintroduces the same text. Now uses `str::replace` (single-pass).
-        for value in ["REDACTED", "EDACTE", "REDA", "ACTED"] {
-            let r = redact_secrets_with(&format!("leak={value}"), &[value]);
-            assert!(r.contains("[REDACTED]"));
-        }
-    }
-
-    #[test]
-    fn redact_secrets_with_extras_handles_overlapping_secrets() {
-        // Longer entries get scrubbed first so the substring "abc12" isn't
-        // matched before "abc123" is consumed.
-        let s = "key1=abc123 key2=abc12";
-        let r = redact_secrets_with(s, &["abc12", "abc123"]);
-        assert!(!r.contains("abc123"));
-        assert!(!r.contains("abc12 "));
-    }
-
-    #[test]
-    fn env_secrets_from_request_extracts_string_values() {
-        let req = serde_json::json!({
-            "op": "deploy",
-            "agent": {
-                "env_vars": {
-                    "ANTHROPIC_API_KEY": "sk-ant-test",
-                    "EMPTY": "",
-                    "NUMERIC": 42,
-                },
-            },
-        });
-        let secrets = env_secrets_from_request(&req);
-        assert!(secrets.iter().any(|v| v == "sk-ant-test"));
-        // Empty and non-string values are filtered out.
-        assert_eq!(secrets.len(), 1);
-    }
-
-    #[test]
-    fn env_secrets_from_request_handles_missing_shape() {
-        assert!(env_secrets_from_request(&serde_json::json!({})).is_empty());
-        assert!(env_secrets_from_request(&serde_json::json!({"agent": {}})).is_empty());
-        assert!(
-            env_secrets_from_request(&serde_json::json!({"agent": {"env_vars": null}})).is_empty()
-        );
-    }
-
-    #[test]
-    fn redact_env_values_in_scrubs_map_values() {
-        let mut env = std::collections::BTreeMap::new();
-        env.insert("ANTHROPIC_API_KEY".to_string(), "sk-ant-real".to_string());
-        env.insert("EMPTY".to_string(), String::new());
-        let stderr = "auth=sk-ant-real failed; other context";
-        let r = redact_env_values_in(stderr, &env);
-        assert!(!r.contains("sk-ant-real"));
-        assert!(r.contains("[REDACTED]"));
-    }
-
-    #[test]
-    fn validate_provider_config_rejects_secret_key() {
-        let cfg = serde_json::json!({"api_key": "val"});
-        assert!(validate_provider_config(&cfg).is_err());
-    }
-
-    #[test]
-    fn validate_provider_config_rejects_nested() {
-        let cfg = serde_json::json!({"region": {"us": "east"}});
-        assert!(validate_provider_config(&cfg).is_err());
-    }
-
-    #[test]
-    fn validate_provider_config_accepts_scalars() {
-        let cfg = serde_json::json!({"region": "us-east-1", "tier": "standard"});
-        assert!(validate_provider_config(&cfg).is_ok());
-    }
-
-    #[test]
-    fn validate_provider_config_allows_key_as_substring() {
-        // "keyboard", "monkey" contain "key" as substring but not as a word segment.
-        let cfg = serde_json::json!({"keyboard_layout": "us", "monkey_wrench": "tight"});
-        assert!(validate_provider_config(&cfg).is_ok());
-    }
-
-    #[test]
-    fn validate_provider_config_rejects_camel_case_secrets() {
-        assert!(validate_provider_config(&serde_json::json!({"apiKey": "val"})).is_err());
-        assert!(validate_provider_config(&serde_json::json!({"accessToken": "val"})).is_err());
-        assert!(validate_provider_config(&serde_json::json!({"clientSecret": "val"})).is_err());
-        // ALL-CAPS variants
-        assert!(validate_provider_config(&serde_json::json!({"apiKEY": "val"})).is_err());
-        assert!(validate_provider_config(&serde_json::json!({"accessTOKEN": "val"})).is_err());
-    }
-
-    #[test]
-    fn split_config_key_handles_all_styles() {
-        assert_eq!(split_config_key("apiKey"), vec!["api", "key"]);
-        assert_eq!(split_config_key("access_token"), vec!["access", "token"]);
-        assert_eq!(split_config_key("keyboard"), vec!["keyboard"]);
-        assert_eq!(split_config_key("client-secret"), vec!["client", "secret"]);
-        // Acronym runs stay together
-        assert_eq!(split_config_key("APIKey"), vec!["api", "key"]);
-        assert_eq!(split_config_key("apiKEY"), vec!["api", "key"]);
-        assert_eq!(split_config_key("accessTOKEN"), vec!["access", "token"]);
-        assert_eq!(split_config_key("MyAPIKey"), vec!["my", "api", "key"]);
-    }
-
-    #[test]
-    fn resolve_provider_binary_rejects_invalid_ids() {
-        // Path traversal
-        assert!(resolve_provider_binary("../evil").is_err());
-        // Empty
-        assert!(resolve_provider_binary("").is_err());
-        // Uppercase
-        assert!(resolve_provider_binary("MyProvider").is_err());
-        // Spaces
-        assert!(resolve_provider_binary("my provider").is_err());
-        // Shell metacharacters
-        assert!(resolve_provider_binary("foo;rm -rf /").is_err());
-        // Valid format but not on PATH — should fail with "not found"
-        assert!(resolve_provider_binary("nonexistent-test-id-12345").is_err());
-    }
-
-    #[test]
-    fn resolve_provider_binary_accepts_valid_id_format() {
-        // Valid ID format should pass validation. If the binary happens to
-        // exist on PATH, Ok is returned; otherwise Err contains "not found"
-        // (not "invalid provider ID"). Either outcome proves validation passed.
-        match resolve_provider_binary("zzz-nonexistent-test-provider") {
-            Ok(_) => {} // unlikely but fine — binary exists
-            Err(e) => assert!(
-                e.contains("not found"),
-                "expected 'not found' error, got: {e}"
-            ),
-        }
-    }
-}
+#[path = "backend_tests.rs"]
+mod tests;
diff --git a/desktop/src-tauri/src/managed_agents/backend_tests.rs b/desktop/src-tauri/src/managed_agents/backend_tests.rs
new file mode 100644
index 0000000000..ce1f81466f
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/backend_tests.rs
@@ -0,0 +1,452 @@
+use super::*;
+
+#[test]
+fn redact_secrets_replaces_nsec() {
+    let s = "key=nsec1abc123def456 other";
+    let r = redact_secrets(s);
+    assert!(r.contains("[REDACTED]"));
+    assert!(!r.contains("nsec1abc123def456"));
+}
+
+#[test]
+fn redact_secrets_replaces_token() {
+    let s = r#"{"token":"sprt_tok_xyz789"}"#;
+    let r = redact_secrets(s);
+    assert!(r.contains("[REDACTED]"));
+    assert!(!r.contains("sprt_tok_xyz789"));
+}
+
+#[test]
+fn redact_secrets_with_extras_scrubs_user_env_values() {
+    // If a provider echoes back a user-supplied API key in its error
+    // output, the desktop must not surface that secret unredacted via
+    // `last_error`. We scrub the literal values that came from the
+    // request's `agent.env_vars`.
+    let secret = "sk-ant-api03-abc123def456";
+    let stderr = format!("auth failed with key {secret} on host api.anthropic.com");
+    let r = redact_secrets_with(&stderr, &[secret]);
+    assert!(r.contains("[REDACTED]"));
+    assert!(!r.contains(secret));
+}
+
+#[test]
+fn redact_secrets_with_extras_skips_short_values() {
+    // Don't scrub values shorter than 4 chars — too noisy.
+    let r = redact_secrets_with("error code: 42", &["42"]);
+    assert!(r.contains("42"));
+}
+
+/// GitHub tokens are recognised by shape, so one that never passed through
+/// our environment — embedded in a remote URL an installer echoes — is
+/// still scrubbed. The scan runs to the next whitespace or quote, so the
+/// rest of the URL goes with it; over-redaction is the safe direction.
+#[test]
+fn redact_secrets_with_scrubs_github_token_prefixes() {
+    for token in [
+        "ghp_abcdefghij0123456789",
+        "gho_abcdefghij0123456789",
+        "ghu_abcdefghij0123456789",
+        "ghs_abcdefghij0123456789",
+        "ghr_abcdefghij0123456789",
+        "github_pat_abcdefghij0123456789",
+    ] {
+        let r = redact_secrets_with(&format!("cloning https://{token}@github.com/o/r now"), &[]);
+        assert!(!r.contains(token), "leaked {token}: {r}");
+        assert!(r.contains("[REDACTED]"), "got: {r}");
+        assert!(r.contains("cloning"), "scan must stop at whitespace: {r}");
+        assert!(r.ends_with(" now"), "scan must stop at whitespace: {r}");
+    }
+}
+
+#[test]
+fn redact_secrets_with_extras_terminates_when_value_substring_of_marker() {
+    // Regression: an earlier impl used `while let Some(pos) = find(value)`
+    // which never terminates if the user's env value is a substring of
+    // the replacement marker `[REDACTED]` — each replacement
+    // reintroduces the same text. Now uses `str::replace` (single-pass).
+    for value in ["REDACTED", "EDACTE", "REDA", "ACTED"] {
+        let r = redact_secrets_with(&format!("leak={value}"), &[value]);
+        assert!(r.contains("[REDACTED]"));
+    }
+}
+
+#[test]
+fn redact_secrets_with_extras_handles_overlapping_secrets() {
+    // Longer entries get scrubbed first so the substring "abc12" isn't
+    // matched before "abc123" is consumed.
+    let s = "key1=abc123 key2=abc12";
+    let r = redact_secrets_with(s, &["abc12", "abc123"]);
+    assert!(!r.contains("abc123"));
+    assert!(!r.contains("abc12 "));
+}
+
+#[test]
+fn env_secrets_from_request_extracts_string_values() {
+    let req = serde_json::json!({
+        "op": "deploy",
+        "agent": {
+            "env_vars": {
+                "ANTHROPIC_API_KEY": "sk-ant-test",
+                "EMPTY": "",
+                "NUMERIC": 42,
+            },
+        },
+    });
+    let secrets = env_secrets_from_request(&req);
+    assert!(secrets.iter().any(|v| v == "sk-ant-test"));
+    // Empty and non-string values are filtered out.
+    assert_eq!(secrets.len(), 1);
+}
+
+#[test]
+fn env_secrets_from_request_handles_missing_shape() {
+    assert!(env_secrets_from_request(&serde_json::json!({})).is_empty());
+    assert!(env_secrets_from_request(&serde_json::json!({"agent": {}})).is_empty());
+    assert!(env_secrets_from_request(&serde_json::json!({"agent": {"env_vars": null}})).is_empty());
+}
+
+#[test]
+fn redact_env_values_in_scrubs_map_values() {
+    let mut env = std::collections::BTreeMap::new();
+    env.insert("ANTHROPIC_API_KEY".to_string(), "sk-ant-real".to_string());
+    env.insert("EMPTY".to_string(), String::new());
+    let stderr = "auth=sk-ant-real failed; other context";
+    let r = redact_env_values_in(stderr, &env);
+    assert!(!r.contains("sk-ant-real"));
+    assert!(r.contains("[REDACTED]"));
+}
+
+#[test]
+fn env_secrets_from_request_includes_resolved_launch_maps() {
+    let req = serde_json::json!({
+        "agent": {
+            "env_vars": {"LEGACY": "legacy-secret"},
+            "launch": {
+                "env": {"PERSONA": "persona-secret"},
+                "policy_env": {"POLICY": "policy-secret"}
+            }
+        }
+    });
+    let secrets = env_secrets_from_request(&req);
+    assert_eq!(secrets.len(), 3);
+    for secret in ["legacy-secret", "persona-secret", "policy-secret"] {
+        assert!(secrets.iter().any(|candidate| candidate == secret));
+    }
+}
+
+#[cfg(unix)]
+fn write_test_provider(path: &Path, body: &str) {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::write(path, format!("#!/bin/sh\nset -eu\n{body}\n")).unwrap();
+    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o700)).unwrap();
+}
+
+#[cfg(unix)]
+#[test]
+fn provider_deploy_negotiates_and_deploys_the_same_staged_bytes() {
+    let directory = tempfile::tempdir().unwrap();
+    let provider = directory.path().join("provider");
+    let log = directory.path().join("invocations");
+    let body = format!(
+        r#"read request
+printf '%s\n' "$0" >> '{}'
+case "$request" in
+  *\"op\":\"info\"*) printf '%s\n' '{{"ok":true,"name":"test","version":"1.0.0","protocol_version":1,"description":"test provider","config_schema":{{}}}}' ;;
+  *\"op\":\"deploy\"*) printf '%s\n' '{{"ok":true,"agent_id":"remote-1"}}' ;;
+esac"#,
+        log.display()
+    );
+    write_test_provider(&provider, &body);
+
+    let id = provider_deploy(&provider, &serde_json::json!({}), &serde_json::json!({}))
+        .expect("staged deploy");
+    assert_eq!(id, "remote-1");
+    let paths: Vec<_> = std::fs::read_to_string(log)
+        .unwrap()
+        .lines()
+        .map(str::to_owned)
+        .collect();
+    assert_eq!(paths.len(), 2);
+    assert_eq!(paths[0], paths[1]);
+    assert_ne!(Path::new(&paths[0]), provider);
+    assert!(
+        !Path::new(&paths[0]).exists(),
+        "staging directory must be deleted"
+    );
+}
+
+#[cfg(unix)]
+fn replacement_provider() -> &'static str {
+    r#"#!/bin/sh
+set -eu
+read request
+case "$request" in
+  *\"op\":\"info\"*) printf '%s\n' '{"ok":true,"name":"replacement","version":"9.9.9","protocol_version":1,"description":"replacement provider","config_schema":{}}' ;;
+  *\"op\":\"deploy\"*) printf '%s\n' '{"ok":true,"agent_id":"replacement-bytes-ran"}' ;;
+esac
+"#
+}
+
+#[cfg(unix)]
+#[test]
+fn provider_deploy_uses_staged_bytes_after_same_inode_source_rewrite() {
+    use std::os::unix::fs::MetadataExt;
+
+    let directory = tempfile::tempdir().unwrap();
+    let provider = directory.path().join("provider");
+    let replacement = directory.path().join("replacement");
+    std::fs::write(&replacement, replacement_provider()).unwrap();
+    let body = format!(
+        r#"read request
+case "$request" in
+  *\"op\":\"info\"*)
+    cat '{}' > '{}'
+    chmod 700 '{}'
+    printf '%s\n' '{{"ok":true,"name":"original","version":"1.0.0","protocol_version":1,"description":"original provider","config_schema":{{}}}}'
+    ;;
+  *\"op\":\"deploy\"*) printf '%s\n' '{{"ok":true,"agent_id":"original-staged-bytes"}}' ;;
+esac"#,
+        replacement.display(),
+        provider.display(),
+        provider.display(),
+    );
+    write_test_provider(&provider, &body);
+    let inode_before = std::fs::metadata(&provider).unwrap().ino();
+
+    let id = provider_deploy(&provider, &serde_json::json!({}), &serde_json::json!({}))
+        .expect("deploy from immutable staged copy");
+
+    assert_eq!(id, "original-staged-bytes");
+    assert_eq!(
+        std::fs::metadata(&provider).unwrap().ino(),
+        inode_before,
+        "test must rewrite the source binary in place"
+    );
+    assert_eq!(
+        std::fs::read_to_string(&provider).unwrap(),
+        replacement_provider(),
+        "source pathname must contain replacement bytes before deploy"
+    );
+}
+
+#[cfg(unix)]
+#[test]
+fn provider_deploy_uses_staged_bytes_after_source_pathname_replacement() {
+    use std::os::unix::fs::{MetadataExt, PermissionsExt};
+
+    let directory = tempfile::tempdir().unwrap();
+    let provider = directory.path().join("provider");
+    let replacement = directory.path().join("replacement");
+    std::fs::write(&replacement, replacement_provider()).unwrap();
+    std::fs::set_permissions(&replacement, std::fs::Permissions::from_mode(0o700)).unwrap();
+    let body = format!(
+        r#"read request
+case "$request" in
+  *\"op\":\"info\"*)
+    mv '{}' '{}'
+    printf '%s\n' '{{"ok":true,"name":"original","version":"1.0.0","protocol_version":1,"description":"original provider","config_schema":{{}}}}'
+    ;;
+  *\"op\":\"deploy\"*) printf '%s\n' '{{"ok":true,"agent_id":"original-staged-bytes"}}' ;;
+esac"#,
+        replacement.display(),
+        provider.display(),
+    );
+    write_test_provider(&provider, &body);
+    let inode_before = std::fs::metadata(&provider).unwrap().ino();
+
+    let id = provider_deploy(&provider, &serde_json::json!({}), &serde_json::json!({}))
+        .expect("deploy from immutable staged copy");
+
+    assert_eq!(id, "original-staged-bytes");
+    assert_ne!(
+        std::fs::metadata(&provider).unwrap().ino(),
+        inode_before,
+        "test must replace the source pathname with a different inode"
+    );
+    assert_eq!(
+        std::fs::read_to_string(&provider).unwrap(),
+        replacement_provider(),
+        "source pathname must contain replacement bytes before deploy"
+    );
+}
+
+#[cfg(unix)]
+#[test]
+fn provider_deploy_refuses_mismatch_before_sending_agent_secret() {
+    let directory = tempfile::tempdir().unwrap();
+    let provider = directory.path().join("provider");
+    let marker = directory.path().join("deploy-received");
+    let body = format!(
+        r#"read request
+case "$request" in
+  *\"op\":\"info\"*) printf '%s\n' '{{"ok":true,"name":"test","version":"2.0.0","protocol_version":2,"description":"test provider","config_schema":{{}}}}' ;;
+  *\"op\":\"deploy\"*) touch '{}'; printf '%s\n' '{{"ok":true,"agent_id":"bad"}}' ;;
+esac"#,
+        marker.display()
+    );
+    write_test_provider(&provider, &body);
+
+    let error = provider_deploy(
+        &provider,
+        &serde_json::json!({"private_key_nsec": "nsec1must-not-cross"}),
+        &serde_json::json!({}),
+    )
+    .unwrap_err();
+    assert!(error.contains("protocol version 2"), "{error}");
+    assert!(!marker.exists());
+    assert!(!error.contains("nsec1must-not-cross"));
+}
+
+#[cfg(unix)]
+#[test]
+fn provider_deploy_requires_an_explicit_integer_protocol_version() {
+    let directory = tempfile::tempdir().unwrap();
+    let provider = directory.path().join("provider");
+    write_test_provider(
+        &provider,
+        r#"read request
+printf '%s\n' '{"ok":true,"version":"1.0.0"}'"#,
+    );
+
+    let error =
+        provider_deploy(&provider, &serde_json::json!({}), &serde_json::json!({})).unwrap_err();
+    assert!(
+        error.contains("missing integer protocol_version"),
+        "{error}"
+    );
+}
+
+#[test]
+fn provider_info_requires_the_complete_flat_wire_shape() {
+    let complete = serde_json::json!({
+        "ok": true,
+        "name": "kubernetes",
+        "version": "1.0.0",
+        "protocol_version": 1,
+        "description": "Kubernetes provider",
+        "config_schema": {}
+    });
+    assert!(validate_provider_info(&complete).is_ok());
+
+    let mut missing = complete.clone();
+    missing.as_object_mut().unwrap().remove("config_schema");
+    assert!(validate_provider_info(&missing)
+        .unwrap_err()
+        .contains("config_schema"));
+
+    let mut nested = complete;
+    nested.as_object_mut().unwrap().insert(
+        "provider".into(),
+        serde_json::json!({"protocol_version": 1}),
+    );
+    assert!(validate_provider_info(&nested)
+        .unwrap_err()
+        .contains("unknown field provider"));
+}
+
+#[test]
+fn validate_provider_config_rejects_secret_key() {
+    let cfg = serde_json::json!({"api_key": "val"});
+    assert!(validate_provider_config(&cfg).is_err());
+}
+
+#[test]
+fn validate_provider_config_rejects_nested() {
+    let cfg = serde_json::json!({"region": {"us": "east"}});
+    assert!(validate_provider_config(&cfg).is_err());
+}
+
+#[test]
+fn validate_provider_config_accepts_scalars() {
+    let cfg = serde_json::json!({"region": "us-east-1", "tier": "standard"});
+    assert!(validate_provider_config(&cfg).is_ok());
+}
+
+#[test]
+fn validate_provider_config_allows_key_as_substring() {
+    // "keyboard", "monkey" contain "key" as substring but not as a word segment.
+    let cfg = serde_json::json!({"keyboard_layout": "us", "monkey_wrench": "tight"});
+    assert!(validate_provider_config(&cfg).is_ok());
+}
+
+#[test]
+fn validate_provider_config_rejects_camel_case_secrets() {
+    assert!(validate_provider_config(&serde_json::json!({"apiKey": "val"})).is_err());
+    assert!(validate_provider_config(&serde_json::json!({"accessToken": "val"})).is_err());
+    assert!(validate_provider_config(&serde_json::json!({"clientSecret": "val"})).is_err());
+    // ALL-CAPS variants
+    assert!(validate_provider_config(&serde_json::json!({"apiKEY": "val"})).is_err());
+    assert!(validate_provider_config(&serde_json::json!({"accessTOKEN": "val"})).is_err());
+}
+
+#[test]
+fn split_config_key_handles_all_styles() {
+    assert_eq!(split_config_key("apiKey"), vec!["api", "key"]);
+    assert_eq!(split_config_key("access_token"), vec!["access", "token"]);
+    assert_eq!(split_config_key("keyboard"), vec!["keyboard"]);
+    assert_eq!(split_config_key("client-secret"), vec!["client", "secret"]);
+    // Acronym runs stay together
+    assert_eq!(split_config_key("APIKey"), vec!["api", "key"]);
+    assert_eq!(split_config_key("apiKEY"), vec!["api", "key"]);
+    assert_eq!(split_config_key("accessTOKEN"), vec!["access", "token"]);
+    assert_eq!(split_config_key("MyAPIKey"), vec!["my", "api", "key"]);
+}
+
+#[test]
+fn provider_filename_strips_the_windows_extension() {
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-kubernetes"),
+        Some("kubernetes")
+    );
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-kubernetes.exe"),
+        Some("kubernetes")
+    );
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-kubernetes.EXE"),
+        Some("kubernetes")
+    );
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-kubernetes.bat"),
+        Some("kubernetes")
+    );
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-kubernetes.CMD"),
+        Some("kubernetes")
+    );
+    assert_eq!(
+        provider_id_from_filename("buzz-backend-my-provider"),
+        Some("my-provider")
+    );
+    assert_eq!(provider_id_from_filename("other"), None);
+}
+
+#[test]
+fn resolve_provider_binary_rejects_invalid_ids() {
+    // Path traversal
+    assert!(resolve_provider_binary("../evil").is_err());
+    // Empty
+    assert!(resolve_provider_binary("").is_err());
+    // Uppercase
+    assert!(resolve_provider_binary("MyProvider").is_err());
+    // Spaces
+    assert!(resolve_provider_binary("my provider").is_err());
+    // Shell metacharacters
+    assert!(resolve_provider_binary("foo;rm -rf /").is_err());
+    // Valid format but not on PATH — should fail with "not found"
+    assert!(resolve_provider_binary("nonexistent-test-id-12345").is_err());
+}
+
+#[test]
+fn resolve_provider_binary_accepts_valid_id_format() {
+    // Valid ID format should pass validation. If the binary happens to
+    // exist on PATH, Ok is returned; otherwise Err contains "not found"
+    // (not "invalid provider ID"). Either outcome proves validation passed.
+    match resolve_provider_binary("zzz-nonexistent-test-provider") {
+        Ok(_) => {} // unlikely but fine — binary exists
+        Err(e) => assert!(
+            e.contains("not found"),
+            "expected 'not found' error, got: {e}"
+        ),
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/config_bridge/reader.rs b/desktop/src-tauri/src/managed_agents/config_bridge/reader.rs
index 372d2cfde1..c51f325cf3 100644
--- a/desktop/src-tauri/src/managed_agents/config_bridge/reader.rs
+++ b/desktop/src-tauri/src/managed_agents/config_bridge/reader.rs
@@ -3,15 +3,17 @@ use crate::managed_agents::types::ManagedAgentRecord;
 
 use super::types::*;
 
-/// Build the full config surface for an agent, merging all four tiers.
+/// Build the full config surface for an agent, merging all tiers.
 ///
-/// Pre-spawn (no session cache): tiers 2a (env vars / record) and 2b (config files).
-/// Post-spawn (session cache present): adds tiers 1a (ACP native) and 1b (ACP configOptions).
+/// Inherited values flow through `tiers` — a sanitized snapshot of the
+/// persona and global tiers assembled at the command boundary. Each field
+/// builder constructs its own candidate list and resolves via
+/// `resolve_with_override`.
 pub(crate) fn read_config_surface(
     record: &ManagedAgentRecord,
     runtime_meta: Option<&KnownAcpRuntime>,
     session_cache: Option<&SessionConfigCache>,
-    baseline: Option<(&str, ConfigOrigin)>,
+    tiers: &InheritedConfigTiers,
 ) -> RuntimeConfigSurface {
     let is_pre_spawn = session_cache.is_none();
 
@@ -27,14 +29,7 @@ pub(crate) fn read_config_surface(
         })
         .unwrap_or_else(|| (RuntimeFileConfig::default(), false));
 
-    // Tier 2a: record-level values (Buzz-explicit).
-    let record_model = record.model.clone();
-    let record_provider = record
-        .env_vars
-        .get(runtime_meta.and_then(|m| m.provider_env_var).unwrap_or(""))
-        .cloned()
-        .or_else(|| record.provider.clone()); // structured provider field as fallback
-
+    // Runtime-specific env var keys.
     let supports_acp_model = runtime_meta.is_some_and(|m| m.supports_acp_model_switching);
     let model_env_var = runtime_meta.and_then(|m| m.model_env_var);
     let provider_env_var = runtime_meta.and_then(|m| m.provider_env_var);
@@ -48,10 +43,6 @@ pub(crate) fn read_config_surface(
     let context_limit_env_var = runtime_meta.and_then(|m| m.context_limit_env_var);
 
     // Tier 1b: ACP configOptions from session cache.
-    // For unstable/switchable agents, current_model comes from the `models`
-    // field. For stable agents that only report model via configOptions
-    // (category="model", current_value), fall back to find_config_option_value
-    // so their current model is surfaced in the panel.
     let acp_model = session_cache.and_then(|c| {
         c.current_model
             .clone()
@@ -59,61 +50,53 @@ pub(crate) fn read_config_surface(
     });
     let acp_mode = session_cache.and_then(|c| find_config_option_value(c, "mode"));
     let acp_effort = session_cache.and_then(|c| find_config_option_value(c, "effort"));
-    let record_effort = thinking_env_var
-        .and_then(|k| record.env_vars.get(k))
-        .cloned();
 
     let model_overridden = session_cache.is_some_and(|c| c.model_overridden);
 
     let normalized = NormalizedConfig {
-        model: Some(apply_runtime_override(
-            build_model_field(
-                &record_model,
-                &file_config.model,
-                &acp_model,
-                model_env_var,
-                supports_acp_model,
-                is_pre_spawn,
-                session_cache,
-                required_fields.contains(&"model"),
-            ),
-            acp_model.as_deref(),
-            baseline,
+        model: Some(build_model_field(
+            record,
+            &file_config.model,
+            &acp_model,
+            model_env_var,
+            supports_acp_model,
+            is_pre_spawn,
+            session_cache,
+            required_fields.contains(&"model"),
             model_overridden,
+            tiers,
         )),
         provider: build_provider_field(
-            &record_provider,
+            record,
             &file_config.provider,
             provider_env_var,
             provider_locked,
             required_fields.contains(&"provider"),
+            tiers,
         ),
         mode: build_mode_field(&file_config.mode, &acp_mode, is_pre_spawn, session_cache),
         thinking_effort: build_thinking_field(
-            &record_effort,
+            record,
             &file_config.thinking_effort,
             &acp_effort,
             thinking_env_var,
             is_pre_spawn,
             session_cache,
+            tiers,
         ),
         max_output_tokens: build_numeric_env_field(
             max_tokens_env_var,
-            &record.env_vars,
+            record,
             &file_config.max_output_tokens,
+            tiers,
         ),
         context_limit: build_numeric_env_field(
             context_limit_env_var,
-            &record.env_vars,
+            record,
             &file_config.context_limit,
+            tiers,
         ),
-        system_prompt: build_system_prompt_field(
-            &record
-                .system_prompt
-                .clone()
-                .or_else(|| record.env_vars.get("BUZZ_ACP_SYSTEM_PROMPT").cloned()),
-            &file_config.system_prompt,
-        ),
+        system_prompt: build_system_prompt_field(record, &file_config.system_prompt, tiers),
     };
 
     // Advanced fields from config file extras.
@@ -130,7 +113,7 @@ pub(crate) fn read_config_surface(
         })
         .collect();
 
-    // Collect the env var keys already covered by normalized fields so we don't double-surface them.
+    // Collect the env var keys already covered by normalized fields.
     let normalized_env_keys: Vec<&str> = [
         model_env_var,
         provider_env_var,
@@ -144,15 +127,13 @@ pub(crate) fn read_config_surface(
     .collect();
 
     // Tier 2a: remaining env vars not covered by normalized fields.
-    // Env var wins over config file for the same key (tier 2a > 2b), so skip
-    // keys already present in file_config.extra.
     let mut advanced = advanced;
     for (k, v) in &record.env_vars {
         if normalized_env_keys.contains(&k.as_str()) {
             continue;
         }
         if file_config.extra.contains_key(k) {
-            continue; // config file already surfaced this key
+            continue;
         }
         advanced.push(ConfigField {
             key: k.clone(),
@@ -178,8 +159,6 @@ pub(crate) fn read_config_surface(
             {
                 ConfigTierStatus::Available
             } else {
-                // Post-spawn without native config data is also Pending — it arrives
-                // asynchronously after the session/new response.
                 ConfigTierStatus::Pending
             }
         } else {
@@ -226,9 +205,27 @@ fn mcp_config_file_path_for_runtime(runtime: &KnownAcpRuntime) -> Option<String>
     }
 }
 
+/// Extract an env-backed candidate value for `env_key` from each tier in
+/// spawn precedence: record env > persona env > global env > definition env.
+/// Returns `[record, persona, global, definition]` — `None` when key is absent.
+fn env_candidates<'a>(
+    env_key: &str,
+    record_env: &'a std::collections::BTreeMap<String, String>,
+    persona_env: &'a std::collections::BTreeMap<String, String>,
+    global_env: &'a std::collections::BTreeMap<String, String>,
+    definition_env: &'a std::collections::BTreeMap<String, String>,
+) -> [Option<&'a str>; 4] {
+    [
+        record_env.get(env_key).map(String::as_str),
+        persona_env.get(env_key).map(String::as_str),
+        global_env.get(env_key).map(String::as_str),
+        definition_env.get(env_key).map(String::as_str),
+    ]
+}
+
 #[allow(clippy::too_many_arguments)]
 fn build_model_field(
-    record_model: &Option<String>,
+    record: &ManagedAgentRecord,
     file_model: &Option<String>,
     acp_model: &Option<String>,
     model_env_var: Option<&str>,
@@ -236,30 +233,109 @@ fn build_model_field(
     is_pre_spawn: bool,
     session_cache: Option<&SessionConfigCache>,
     is_required: bool,
+    model_overridden: bool,
+    tiers: &InheritedConfigTiers,
 ) -> NormalizedField {
-    // Precedence: Buzz-explicit > ACP current > config file
-    let (value, origin) = if let Some(ref m) = record_model {
-        (Some(m.clone()), ConfigOrigin::BuzzExplicit)
-    } else if let Some(ref m) = acp_model {
-        (Some(m.clone()), ConfigOrigin::AcpConfigOption)
-    } else if let Some(ref m) = file_model {
-        (Some(m.clone()), ConfigOrigin::ConfigFile)
-    } else {
-        // No value from any tier. EnvVar is the sentinel origin for "no value
-        // resolved" — there is no dedicated None-origin variant. The panel
-        // renders this as an empty/absent field.
-        (None, ConfigOrigin::EnvVar)
-    };
+    let [rec_env, pers_env, glob_env, def_env] = model_env_var
+        .map(|k| {
+            env_candidates(
+                k,
+                &record.env_vars,
+                &tiers.persona_env,
+                &tiers.global_env,
+                &tiers.definition_env,
+            )
+        })
+        .unwrap_or([None, None, None, None]);
 
-    // The secondary expresses ONLY the static record-vs-file precedence: a
-    // Buzz-explicit model shadowing a config-file model. The live-session
-    // override (acp vs record/persona) is exclusively `apply_runtime_override`'s
-    // job, gated on `model_overridden`. Surfacing `acp_model` here would leak an
-    // override row even when no live switch has been applied.
-    let (overridden_value, overridden_origin) = if record_model.is_some() && file_model.is_some() {
-        (file_model.clone(), Some(ConfigOrigin::ConfigFile))
+    // Structured record model (definition-less only; linked cleared upstream).
+    let struct_record = record.model.as_deref();
+    let struct_persona = tiers.persona_model.as_deref();
+    let struct_global = tiers.global_model.as_deref();
+
+    // Configured candidates in spawn order: record env > persona env > global env >
+    // definition env > struct record > struct persona > struct global > file.
+    // The file entry is always last; everything before it is a "configured" candidate
+    // that gates whether ACP participates as a fallback (see any_configured below).
+    let configured: &[(Option<&str>, ConfigOrigin)] = &[
+        (rec_env, ConfigOrigin::BuzzExplicit),
+        (pers_env, ConfigOrigin::PersonaDefault),
+        (glob_env, ConfigOrigin::GlobalDefault),
+        (def_env, ConfigOrigin::HarnessDefault),
+        (struct_record, ConfigOrigin::BuzzExplicit),
+        (struct_persona, ConfigOrigin::PersonaDefault),
+        (struct_global, ConfigOrigin::GlobalDefault),
+        (file_model.as_deref(), ConfigOrigin::ConfigFile),
+    ];
+    // "Configured" = any non-file candidate. The file entry is always last, so
+    // slicing to len()-1 is equivalent to the old magic `[..6]` and stays correct
+    // if the array ever grows again.
+    let any_configured = configured[..configured.len() - 1]
+        .iter()
+        .any(|(v, _)| v.is_some());
+
+    // When model_overridden is true and ACP is present, ACP is the live winner.
+    // The top configured candidate becomes the secondary (the overridden baseline).
+    // Equal-value case: ACP == baseline → fall through to normal resolution so
+    // the field carries the correct baseline origin rather than RuntimeOverride.
+    if model_overridden {
+        if let Some(acp) = acp_model.as_deref() {
+            let baseline = configured.iter().find(|(v, _)| v.is_some());
+            match baseline {
+                Some((Some(baseline_value), _)) if acp == *baseline_value => {
+                    // Equal-value switch: no real divergence.
+                    // Fall through to the normal resolve path below — it will
+                    // return the same value with its true baseline origin, with
+                    // no secondary row.
+                }
+                Some((Some(baseline_value), baseline_origin)) => {
+                    return NormalizedField {
+                        value: Some(acp.to_string()),
+                        origin: ConfigOrigin::RuntimeOverride,
+                        write_via: model_write_mechanism(
+                            is_pre_spawn,
+                            supports_acp_model,
+                            session_cache,
+                            model_env_var,
+                        ),
+                        overridden_value: Some(baseline_value.to_string()),
+                        overridden_origin: Some(baseline_origin.clone()),
+                        is_required,
+                    };
+                }
+                _ => {
+                    // No configured baseline — ACP is the only source.
+                    return NormalizedField {
+                        value: Some(acp.to_string()),
+                        origin: ConfigOrigin::RuntimeOverride,
+                        write_via: model_write_mechanism(
+                            is_pre_spawn,
+                            supports_acp_model,
+                            session_cache,
+                            model_env_var,
+                        ),
+                        overridden_value: None,
+                        overridden_origin: None,
+                        is_required,
+                    };
+                }
+            }
+        }
+    }
+
+    let (value, origin, overridden_value, overridden_origin) = if !any_configured {
+        // No configured candidate: ACP participates as AcpConfigOption fallback.
+        let full: &[(Option<&str>, ConfigOrigin)] = &[
+            (acp_model.as_deref(), ConfigOrigin::AcpConfigOption),
+            (file_model.as_deref(), ConfigOrigin::ConfigFile),
+        ];
+        resolve_with_override(full).unwrap_or((None, ConfigOrigin::EnvVar, None, None))
     } else {
-        (None, None)
+        // ACP excluded: a configured value is pending and wins over live ACP.
+        match resolve_with_override(configured) {
+            Some(r) => r,
+            None => (None, ConfigOrigin::EnvVar, None, None),
+        }
     };
 
     let write_via = model_write_mechanism(
@@ -280,7 +356,6 @@ fn build_model_field(
 }
 
 /// Resolve how the model field is written back to the runtime.
-/// Prefer ACP `set_config_option`/`set_model` post-spawn, else env-var respawn.
 fn model_write_mechanism(
     is_pre_spawn: bool,
     supports_acp_model: bool,
@@ -301,67 +376,13 @@ fn model_write_mechanism(
     }
 }
 
-/// Re-key the model field as a live runtime override when the harness signals
-/// that a `SwitchModel` control signal set the model (Phase 3c).
-///
-/// The override-active signal is `model_overridden` from the
-/// `session_config_captured` payload — NOT `acp_model != persona_model`, which
-/// would false-positive when a persona model is edited mid-life while the
-/// session is stale on the old model.
-///
-/// `baseline` is the value the live model overrides, paired with its true
-/// origin — `(persona_model, PersonaDefault)` for a persona-linked agent, or
-/// `(record_model, BuzzExplicit)` for a genuine-explicit agent that live-
-/// switched. It is `Some` only when there is such a baseline to override
-/// against; otherwise the field passes through unchanged. Carrying the origin
-/// in the pair (rather than hardcoding it) lets the secondary be tagged by its
-/// real source instead of always reading `PersonaDefault`.
-///
-/// The `acp == baseline_value` short-circuit keeps a live pick of the baseline
-/// model itself from rendering a no-op "override of X with X". It yields a
-/// CLEAN single-value field — `overridden_value`/`overridden_origin` cleared —
-/// rather than passing `base` through, because `build_model_field` already
-/// populates `base`'s secondary with an `AcpConfigOption` row for the
-/// record-model-plus-live-session case; returning `base` would leak that
-/// spurious row. The override preserves the base field's write mechanism — only
-/// the displayed value, origin, and secondary change.
-fn apply_runtime_override(
-    base: NormalizedField,
-    acp_model: Option<&str>,
-    baseline: Option<(&str, ConfigOrigin)>,
-    model_overridden: bool,
-) -> NormalizedField {
-    if !model_overridden {
-        return base;
-    }
-    let (Some(acp), Some((baseline_value, baseline_origin))) = (acp_model, baseline) else {
-        return base;
-    };
-    if acp == baseline_value {
-        // Live pick equals the baseline — no real divergence. Strip any
-        // secondary `build_model_field` may have produced so the panel shows a
-        // single clean value rather than "X overridden by X".
-        return NormalizedField {
-            overridden_value: None,
-            overridden_origin: None,
-            ..base
-        };
-    }
-    NormalizedField {
-        value: Some(acp.to_string()),
-        origin: ConfigOrigin::RuntimeOverride,
-        overridden_value: Some(baseline_value.to_string()),
-        overridden_origin: Some(baseline_origin),
-        ..base
-    }
-}
-
 fn build_provider_field(
-    record_provider: &Option<String>,
+    record: &ManagedAgentRecord,
     file_provider: &Option<String>,
     provider_env_var: Option<&str>,
     provider_locked: bool,
     is_required: bool,
+    tiers: &InheritedConfigTiers,
 ) -> Option<NormalizedField> {
     if provider_locked {
         return Some(NormalizedField {
@@ -374,15 +395,43 @@ fn build_provider_field(
         });
     }
 
-    let tiers: &[(Option<&str>, ConfigOrigin)] = &[
-        (record_provider.as_deref(), ConfigOrigin::BuzzExplicit),
+    let [rec_env, pers_env, glob_env, def_env] = provider_env_var
+        .map(|k| {
+            env_candidates(
+                k,
+                &record.env_vars,
+                &tiers.persona_env,
+                &tiers.global_env,
+                &tiers.definition_env,
+            )
+        })
+        .unwrap_or([None, None, None, None]);
+
+    let struct_record = record.provider.as_deref();
+
+    let tiers_list: &[(Option<&str>, ConfigOrigin)] = &[
+        (rec_env, ConfigOrigin::BuzzExplicit),
+        (pers_env, ConfigOrigin::PersonaDefault),
+        (glob_env, ConfigOrigin::GlobalDefault),
+        (def_env, ConfigOrigin::HarnessDefault),
+        (struct_record, ConfigOrigin::BuzzExplicit),
+        (
+            tiers.persona_provider.as_deref(),
+            ConfigOrigin::PersonaDefault,
+        ),
+        (
+            tiers.global_provider.as_deref(),
+            ConfigOrigin::GlobalDefault,
+        ),
         (file_provider.as_deref(), ConfigOrigin::ConfigFile),
     ];
-    let (value, origin, overridden_value, overridden_origin) = match resolve_with_override(tiers) {
-        Some(resolved) => resolved,
-        None if is_required => (None, ConfigOrigin::EnvVar, None, None),
-        None => return None,
-    };
+
+    let (value, origin, overridden_value, overridden_origin) =
+        match resolve_with_override(tiers_list) {
+            Some(resolved) => resolved,
+            None if is_required => (None, ConfigOrigin::EnvVar, None, None),
+            None => return None,
+        };
 
     let write_via = if let Some(env_key) = provider_env_var {
         ConfigWriteMechanism::RespawnWithEnvVar {
@@ -432,20 +481,38 @@ fn build_mode_field(
     })
 }
 
+#[allow(clippy::too_many_arguments)]
 fn build_thinking_field(
-    record_effort: &Option<String>,
+    record: &ManagedAgentRecord,
     file_effort: &Option<String>,
     acp_effort: &Option<String>,
     thinking_env_var: Option<&str>,
     is_pre_spawn: bool,
     session_cache: Option<&SessionConfigCache>,
+    tiers: &InheritedConfigTiers,
 ) -> Option<NormalizedField> {
-    let tiers: &[(Option<&str>, ConfigOrigin)] = &[
-        (record_effort.as_deref(), ConfigOrigin::BuzzExplicit),
+    // Tier ordering: record env > ACP > persona env > global env > definition env > config file.
+    let [rec_env, pers_env, glob_env, def_env] = thinking_env_var
+        .map(|k| {
+            env_candidates(
+                k,
+                &record.env_vars,
+                &tiers.persona_env,
+                &tiers.global_env,
+                &tiers.definition_env,
+            )
+        })
+        .unwrap_or([None, None, None, None]);
+
+    let tiers_list: &[(Option<&str>, ConfigOrigin)] = &[
+        (rec_env, ConfigOrigin::BuzzExplicit),
         (acp_effort.as_deref(), ConfigOrigin::AcpConfigOption),
+        (pers_env, ConfigOrigin::PersonaDefault),
+        (glob_env, ConfigOrigin::GlobalDefault),
+        (def_env, ConfigOrigin::HarnessDefault),
         (file_effort.as_deref(), ConfigOrigin::ConfigFile),
     ];
-    let (value, origin, overridden_value, overridden_origin) = resolve_with_override(tiers)?;
+    let (value, origin, overridden_value, overridden_origin) = resolve_with_override(tiers_list)?;
 
     let write_via = if !is_pre_spawn && has_config_option(session_cache, "effort") {
         ConfigWriteMechanism::AcpSetConfigOption {
@@ -469,67 +536,105 @@ fn build_thinking_field(
     })
 }
 
-/// Numeric fields (max_output_tokens, context_limit) — env-var tier wins over
-/// config-file tier. When an env var key is given and present in the record's
-/// env_vars map the field is BuzzExplicit + RespawnWithEnvVar; otherwise if the
-/// config file supplied a value it is ConfigFile + ReadOnly; otherwise None.
+/// Numeric fields (max_output_tokens, context_limit).
+/// Tier ordering: record env > persona env > global env > config file.
 fn build_numeric_env_field(
     env_var: Option<&'static str>,
-    record_env: &std::collections::BTreeMap<String, String>,
+    record: &ManagedAgentRecord,
     file_value: &Option<String>,
+    tiers: &InheritedConfigTiers,
 ) -> Option<NormalizedField> {
-    if let Some(key) = env_var {
-        if let Some(v) = record_env.get(key) {
-            return Some(NormalizedField {
-                value: Some(v.clone()),
-                origin: ConfigOrigin::BuzzExplicit,
-                write_via: ConfigWriteMechanism::RespawnWithEnvVar {
-                    env_key: key.to_string(),
-                },
-                overridden_value: file_value.clone(),
-                overridden_origin: file_value.as_ref().map(|_| ConfigOrigin::ConfigFile),
-                is_required: false,
-            });
+    let [rec_env, pers_env, glob_env, def_env] = env_var
+        .map(|k| {
+            env_candidates(
+                k,
+                &record.env_vars,
+                &tiers.persona_env,
+                &tiers.global_env,
+                &tiers.definition_env,
+            )
+        })
+        .unwrap_or([None, None, None, None]);
+
+    let tiers_list: &[(Option<&str>, ConfigOrigin)] = &[
+        (rec_env, ConfigOrigin::BuzzExplicit),
+        (pers_env, ConfigOrigin::PersonaDefault),
+        (glob_env, ConfigOrigin::GlobalDefault),
+        (def_env, ConfigOrigin::HarnessDefault),
+        (file_value.as_deref(), ConfigOrigin::ConfigFile),
+    ];
+
+    let (value, origin, overridden_value, overridden_origin) = resolve_with_override(tiers_list)?;
+
+    let write_via = if let Some(key) = env_var {
+        ConfigWriteMechanism::RespawnWithEnvVar {
+            env_key: key.to_string(),
         }
-    }
-    file_value.as_ref().map(|v| NormalizedField {
-        value: Some(v.clone()),
-        origin: ConfigOrigin::ConfigFile,
-        write_via: ConfigWriteMechanism::ReadOnly,
-        overridden_value: None,
-        overridden_origin: None,
+    } else {
+        ConfigWriteMechanism::ReadOnly
+    };
+
+    Some(NormalizedField {
+        value,
+        origin,
+        write_via,
+        overridden_value,
+        overridden_origin,
         is_required: false,
     })
 }
 
-/// Record/env prompt wins (BuzzExplicit, respawnable); a config-file prompt it
-/// shadows is reported as the overridden secondary. A config-file-only prompt
-/// — no record/env value to shadow it — is surfaced directly (read-only)
-/// instead of being dropped: a prompt that drives the agent should always be
-/// visible somewhere in the panel.
+/// System prompt field.
+///
+/// Tier ordering per v3 plan: record env > persona env > global env >
+/// struct record > struct persona > config file.
+///
+/// Env tiers sit above structured per spawn contract: `descriptor.env` is
+/// written last (after the structured prompt), so env wins on collision.
+/// `GlobalAgentConfig` has no structured system_prompt, so the global tier
+/// is env-only. `BUZZ_ACP_SYSTEM_PROMPT` is not reserved and is therefore
+/// a real global env tier.
 fn build_system_prompt_field(
-    record_prompt: &Option<String>,
+    record: &ManagedAgentRecord,
     file_prompt: &Option<String>,
+    tiers: &InheritedConfigTiers,
 ) -> Option<NormalizedField> {
-    if let Some(v) = record_prompt {
-        return Some(NormalizedField {
-            value: Some(v.clone()),
-            origin: ConfigOrigin::BuzzExplicit,
-            write_via: ConfigWriteMechanism::RespawnWithEnvVar {
-                env_key: "BUZZ_ACP_SYSTEM_PROMPT".to_string(),
-            },
-            overridden_value: file_prompt.clone(),
-            overridden_origin: file_prompt.as_ref().map(|_| ConfigOrigin::ConfigFile),
-            is_required: false,
-        });
-    }
+    const PROMPT_ENV_KEY: &str = "BUZZ_ACP_SYSTEM_PROMPT";
 
-    file_prompt.as_ref().map(|v| NormalizedField {
-        value: Some(v.clone()),
-        origin: ConfigOrigin::ConfigFile,
-        write_via: ConfigWriteMechanism::ReadOnly,
-        overridden_value: None,
-        overridden_origin: None,
+    let [rec_env, pers_env, glob_env, def_env] = env_candidates(
+        PROMPT_ENV_KEY,
+        &record.env_vars,
+        &tiers.persona_env,
+        &tiers.global_env,
+        &tiers.definition_env,
+    );
+
+    // Structured record prompt (definition-less only; linked cleared upstream).
+    let struct_record = record.system_prompt.as_deref();
+
+    let tiers_list: &[(Option<&str>, ConfigOrigin)] = &[
+        (rec_env, ConfigOrigin::BuzzExplicit),       // record env
+        (pers_env, ConfigOrigin::PersonaDefault),    // persona env
+        (glob_env, ConfigOrigin::GlobalDefault),     // global env
+        (def_env, ConfigOrigin::HarnessDefault),     // definition env
+        (struct_record, ConfigOrigin::BuzzExplicit), // struct record
+        (
+            tiers.persona_prompt.as_deref(),
+            ConfigOrigin::PersonaDefault,
+        ), // struct persona
+        (file_prompt.as_deref(), ConfigOrigin::ConfigFile),
+    ];
+
+    let (value, origin, overridden_value, overridden_origin) = resolve_with_override(tiers_list)?;
+
+    Some(NormalizedField {
+        value,
+        origin,
+        write_via: ConfigWriteMechanism::RespawnWithEnvVar {
+            env_key: PROMPT_ENV_KEY.to_string(),
+        },
+        overridden_value,
+        overridden_origin,
         is_required: false,
     })
 }
diff --git a/desktop/src-tauri/src/managed_agents/config_bridge/reader_tests.rs b/desktop/src-tauri/src/managed_agents/config_bridge/reader_tests.rs
index 4ee4ec79c3..153db1bbd8 100644
--- a/desktop/src-tauri/src/managed_agents/config_bridge/reader_tests.rs
+++ b/desktop/src-tauri/src/managed_agents/config_bridge/reader_tests.rs
@@ -120,11 +120,53 @@ fn test_record() -> ManagedAgentRecord {
     }
 }
 
+/// Default empty tiers: no persona or global inheritance.
+fn no_tiers() -> InheritedConfigTiers {
+    InheritedConfigTiers::default()
+}
+
+/// Tiers with only global env set (for AC-1 style tests).
+fn global_env_tiers(key: &str, val: &str) -> InheritedConfigTiers {
+    let mut global_env = BTreeMap::new();
+    global_env.insert(key.to_string(), val.to_string());
+    InheritedConfigTiers {
+        global_env,
+        ..Default::default()
+    }
+}
+
+/// Tiers with only persona env set.
+fn persona_env_tiers(key: &str, val: &str) -> InheritedConfigTiers {
+    let mut persona_env = BTreeMap::new();
+    persona_env.insert(key.to_string(), val.to_string());
+    InheritedConfigTiers {
+        persona_env,
+        ..Default::default()
+    }
+}
+
+/// Tiers with both persona and global env set for the same key.
+fn persona_and_global_env_tiers(
+    key: &str,
+    persona_val: &str,
+    global_val: &str,
+) -> InheritedConfigTiers {
+    let mut persona_env = BTreeMap::new();
+    persona_env.insert(key.to_string(), persona_val.to_string());
+    let mut global_env = BTreeMap::new();
+    global_env.insert(key.to_string(), global_val.to_string());
+    InheritedConfigTiers {
+        persona_env,
+        global_env,
+        ..Default::default()
+    }
+}
+
 #[test]
 fn pre_spawn_surface_reports_pending_acp_tiers() {
     let record = test_record();
     let runtime = test_runtime();
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     assert!(surface.is_pre_spawn);
     assert_eq!(surface.sources.acp_native, ConfigTierStatus::Pending);
@@ -140,7 +182,7 @@ fn surface_reports_mcp_specific_config_path() {
     let record = test_record();
     let runtime = test_runtime();
     let surface = with_goose_path_root(None, || {
-        read_config_surface(&record, Some(runtime), None, None)
+        read_config_surface(&record, Some(runtime), None, &no_tiers())
     });
 
     let path = surface
@@ -159,7 +201,7 @@ fn goose_mcp_config_path_follows_path_root_override() {
     let record = test_record();
     let runtime = test_runtime();
     let surface = with_goose_path_root(Some("/tmp/buzz-goose-root"), || {
-        read_config_surface(&record, Some(runtime), None, None)
+        read_config_surface(&record, Some(runtime), None, &no_tiers())
     });
 
     let expected_path = Path::new("/tmp/buzz-goose-root")
@@ -183,7 +225,7 @@ fn claude_surface_uses_mcp_config_path_not_settings_path() {
         config_file_path: Some("~/.claude/settings.json"),
         ..*test_runtime()
     };
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     assert!(surface
         .sources
@@ -203,7 +245,7 @@ fn record_model_overrides_file_model() {
     record.model = Some("explicit-model".to_string());
     let runtime = test_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
     let model = surface.normalized.model.unwrap();
     assert_eq!(model.value.as_deref(), Some("explicit-model"));
     assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
@@ -216,7 +258,7 @@ fn provider_locked_shows_locked() {
         provider_locked: true,
         ..*test_runtime()
     };
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
     let provider = surface.normalized.provider.unwrap();
     assert_eq!(provider.value.as_deref(), Some("Anthropic (locked)"));
     assert_eq!(provider.origin, ConfigOrigin::HarnessConstraint);
@@ -242,7 +284,7 @@ fn post_spawn_with_model_config_option_uses_acp() {
         captured_at: "".to_string(),
     };
 
-    let surface = read_config_surface(&record, Some(runtime), Some(&cache), None);
+    let surface = read_config_surface(&record, Some(runtime), Some(&cache), &no_tiers());
     assert!(!surface.is_pre_spawn);
     let model = surface.normalized.model.unwrap();
     assert_eq!(model.value.as_deref(), Some("claude-opus-4"));
@@ -266,53 +308,86 @@ fn acp_model_overrides_file_model_with_override_tracking() {
         captured_at: "".to_string(),
     };
 
-    let surface = read_config_surface(&record, Some(runtime), Some(&cache), None);
+    let surface = read_config_surface(&record, Some(runtime), Some(&cache), &no_tiers());
     let model = surface.normalized.model.unwrap();
     assert_eq!(model.value.as_deref(), Some("acp-model"));
     assert_eq!(model.origin, ConfigOrigin::AcpConfigOption);
-    // The goose config file might have a model too — since we can't control
-    // the actual file in a unit test, just verify the override fields are populated
-    // when we manually construct the scenario via build_model_field.
 }
 
-// ── Persona resolution integration tests ────────────────────────────
+// ── Persona / global tier integration tests ──────────────────────────────────
 //
-// These simulate the call-site pattern in agent_config.rs:
-// 1. Inject persona-resolved values into the record (as if absent)
-// 2. Call read_config_surface (reader tags them BuzzExplicit)
-// 3. Re-tag injected fields to PersonaDefault
-//
-// This exercises the same logic path as get_agent_config_surface without
-// requiring Tauri AppHandle/State infrastructure.
+// These exercise the tiers-based candidate resolution for model, provider, and
+// system_prompt via `InheritedConfigTiers` — replacing the old inject+retag
+// simulation tests.
 
 #[test]
-fn persona_model_injection_produces_persona_default_origin() {
-    let mut record = test_record();
-    // Simulate: record has no model, persona provides one.
-    // The call-site injects it before calling the reader.
-    record.model = Some("persona-model".to_string());
+fn persona_model_tier_produces_persona_default_origin() {
+    let record = test_record(); // no record.model
     let runtime = test_runtime();
+    let tiers = InheritedConfigTiers {
+        persona_model: Some("persona-model".to_string()),
+        ..Default::default()
+    };
 
-    let mut surface = read_config_surface(&record, Some(runtime), None, None);
-
-    // Reader sees injected model as BuzzExplicit.
-    let model = surface.normalized.model.as_ref().unwrap();
-    assert_eq!(model.value.as_deref(), Some("persona-model"));
-    assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
-
-    // Call-site re-tags (simulating had_model == false).
-    if let Some(ref mut field) = surface.normalized.model {
-        if field.origin == ConfigOrigin::BuzzExplicit {
-            field.origin = ConfigOrigin::PersonaDefault;
-        }
-    }
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
 
     let model = surface.normalized.model.unwrap();
     assert_eq!(model.value.as_deref(), Some("persona-model"));
     assert_eq!(model.origin, ConfigOrigin::PersonaDefault);
 }
 
-// ── Runtime override (Phase 3c) ──────────────────────────────────────
+#[test]
+fn global_model_tier_produces_global_default_origin() {
+    let record = test_record();
+    let runtime = test_runtime();
+    let tiers = InheritedConfigTiers {
+        global_model: Some("global-model".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let model = surface.normalized.model.unwrap();
+    assert_eq!(model.value.as_deref(), Some("global-model"));
+    assert_eq!(model.origin, ConfigOrigin::GlobalDefault);
+}
+
+#[test]
+fn persona_provider_tier_produces_persona_default_origin() {
+    let record = test_record();
+    let runtime = test_runtime();
+    let tiers = InheritedConfigTiers {
+        persona_provider: Some("anthropic".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let provider = surface.normalized.provider.unwrap();
+    assert_eq!(provider.value.as_deref(), Some("anthropic"));
+    assert_eq!(provider.origin, ConfigOrigin::PersonaDefault);
+}
+
+#[test]
+fn persona_prompt_tier_produces_persona_default_origin() {
+    let record = test_record();
+    let runtime = test_runtime();
+    let tiers = InheritedConfigTiers {
+        persona_prompt: Some("You are a helpful assistant.".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let prompt = surface.normalized.system_prompt.unwrap();
+    assert_eq!(
+        prompt.value.as_deref(),
+        Some("You are a helpful assistant.")
+    );
+    assert_eq!(prompt.origin, ConfigOrigin::PersonaDefault);
+}
+
+// ── Runtime override (model_overridden gate) ──────────────────────────────────
 //
 // A live ModelPicker switch is signalled by `model_overridden: true` in the
 // `session_config_captured` payload. The reader keys the override-active
@@ -321,7 +396,7 @@ fn persona_model_injection_produces_persona_default_origin() {
 
 #[test]
 fn runtime_override_wins_display_when_model_overridden_is_true() {
-    // Persona-linked agent (record.model == None); persona == "persona-model".
+    // Persona-linked agent (record.model == None); persona model via tiers.
     // A live switch pushed "live-model" to the session and set model_overridden.
     let record = test_record();
     let runtime = test_runtime();
@@ -334,29 +409,27 @@ fn runtime_override_wins_display_when_model_overridden_is_true() {
         goose_native_config: None,
         captured_at: "".to_string(),
     };
+    let tiers = InheritedConfigTiers {
+        persona_model: Some("persona-model".to_string()),
+        ..Default::default()
+    };
 
-    let surface = read_config_surface(
-        &record,
-        Some(runtime),
-        Some(&cache),
-        Some(("persona-model", ConfigOrigin::PersonaDefault)),
-    );
+    let surface = read_config_surface(&record, Some(runtime), Some(&cache), &tiers);
     let model = surface.normalized.model.unwrap();
 
     // Override wins the display value with a runtime-override origin.
     assert_eq!(model.value.as_deref(), Some("live-model"));
     assert_eq!(model.origin, ConfigOrigin::RuntimeOverride);
-    // Persona is the secondary value (not struck through — the UI keys off
-    // the RuntimeOverride origin to suppress strikethrough).
+    // Persona is the secondary value.
     assert_eq!(model.overridden_value.as_deref(), Some("persona-model"));
     assert_eq!(model.overridden_origin, Some(ConfigOrigin::PersonaDefault));
 }
 
 #[test]
 fn no_runtime_override_when_model_overridden_is_false() {
-    // At spawn the session's current_model == persona model (BUZZ_ACP_MODEL
-    // is set to the persona model) and model_overridden is false. No override;
-    // the field falls through to normal precedence.
+    // At spawn the session's current_model == persona model and
+    // model_overridden is false. No override; field falls through to normal
+    // precedence.
     let record = test_record();
     let runtime = test_runtime();
     let cache = SessionConfigCache {
@@ -368,17 +441,15 @@ fn no_runtime_override_when_model_overridden_is_false() {
         goose_native_config: None,
         captured_at: "".to_string(),
     };
+    let tiers = InheritedConfigTiers {
+        persona_model: Some("persona-model".to_string()),
+        ..Default::default()
+    };
 
-    let surface = read_config_surface(
-        &record,
-        Some(runtime),
-        Some(&cache),
-        Some(("persona-model", ConfigOrigin::PersonaDefault)),
-    );
+    let surface = read_config_surface(&record, Some(runtime), Some(&cache), &tiers);
     let model = surface.normalized.model.unwrap();
 
-    // model_overridden is false => the override branch is not taken: origin
-    // is the normal precedence result, never RuntimeOverride.
+    // model_overridden is false => the override branch is not taken.
     assert_ne!(model.origin, ConfigOrigin::RuntimeOverride);
     assert_eq!(model.value.as_deref(), Some("persona-model"));
     assert_ne!(model.overridden_origin, Some(ConfigOrigin::PersonaDefault));
@@ -402,106 +473,51 @@ fn no_false_positive_override_when_persona_edited_mid_life() {
         goose_native_config: None,
         captured_at: "".to_string(),
     };
+    let tiers = InheritedConfigTiers {
+        persona_model: Some("new-persona-model".to_string()),
+        ..Default::default()
+    };
 
-    let surface = read_config_surface(
-        &record,
-        Some(runtime),
-        Some(&cache),
-        Some(("new-persona-model", ConfigOrigin::PersonaDefault)),
-    );
+    let surface = read_config_surface(&record, Some(runtime), Some(&cache), &tiers);
     let model = surface.normalized.model.unwrap();
 
     // model_overridden is false => no RuntimeOverride, even though
     // acp_model != persona_model. The old divergence-based signal would
-    // have false-positived here. The persona is never surfaced as the
-    // overridden secondary (that marker is exclusive to a real override).
+    // have false-positived here.
     assert_ne!(model.origin, ConfigOrigin::RuntimeOverride);
     assert_ne!(model.overridden_origin, Some(ConfigOrigin::PersonaDefault));
 }
 
-#[test]
-fn persona_provider_injection_produces_persona_default_origin() {
-    let mut record = test_record();
-    // Simulate: record has no provider env var, persona provides one.
-    // The call-site injects it as GOOSE_PROVIDER before calling the reader.
-    record
-        .env_vars
-        .insert("GOOSE_PROVIDER".to_string(), "anthropic".to_string());
-    let runtime = test_runtime();
-
-    let mut surface = read_config_surface(&record, Some(runtime), None, None);
-
-    // Reader sees injected provider as BuzzExplicit.
-    let provider = surface.normalized.provider.as_ref().unwrap();
-    assert_eq!(provider.value.as_deref(), Some("anthropic"));
-    assert_eq!(provider.origin, ConfigOrigin::BuzzExplicit);
-
-    // Call-site re-tags (simulating had_provider == false).
-    if let Some(ref mut field) = surface.normalized.provider {
-        if field.origin == ConfigOrigin::BuzzExplicit {
-            field.origin = ConfigOrigin::PersonaDefault;
-        }
-    }
-
-    let provider = surface.normalized.provider.unwrap();
-    assert_eq!(provider.value.as_deref(), Some("anthropic"));
-    assert_eq!(provider.origin, ConfigOrigin::PersonaDefault);
-}
+// ── system_prompt builder unit tests ─────────────────────────────────────────
 
 #[test]
-fn persona_system_prompt_injection_produces_persona_default_origin() {
-    let mut record = test_record();
-    // Simulate: record has no system_prompt, persona provides one via env var.
-    // The call-site injects it as BUZZ_ACP_SYSTEM_PROMPT before calling the reader.
-    record.env_vars.insert(
-        "BUZZ_ACP_SYSTEM_PROMPT".to_string(),
-        "You are a helpful assistant.".to_string(),
-    );
-    let runtime = test_runtime();
-
-    let mut surface = read_config_surface(&record, Some(runtime), None, None);
-
-    // Reader sees injected prompt as BuzzExplicit.
-    let prompt = surface.normalized.system_prompt.as_ref().unwrap();
-    assert_eq!(
-        prompt.value.as_deref(),
-        Some("You are a helpful assistant.")
-    );
-    assert_eq!(prompt.origin, ConfigOrigin::BuzzExplicit);
-
-    // Call-site re-tags (simulating had_prompt == false).
-    if let Some(ref mut field) = surface.normalized.system_prompt {
-        if field.origin == ConfigOrigin::BuzzExplicit {
-            field.origin = ConfigOrigin::PersonaDefault;
-        }
-    }
-
-    let prompt = surface.normalized.system_prompt.unwrap();
-    assert_eq!(
-        prompt.value.as_deref(),
-        Some("You are a helpful assistant.")
-    );
-    assert_eq!(prompt.origin, ConfigOrigin::PersonaDefault);
-}
-
-#[test]
-fn config_file_only_system_prompt_surfaces_as_read_only_config_file_field() {
-    // Record/env has no prompt; the config file does. It must NOT be
-    // dropped — it should surface with ConfigFile origin, read-only.
-    let field = build_system_prompt_field(&None, &Some("File-driven prompt.".to_string())).unwrap();
+fn config_file_only_system_prompt_surfaces_as_config_file_origin() {
+    // Record/env has no prompt; the config file does. Must surface with
+    // ConfigFile origin. Write mechanism is always RespawnWithEnvVar for
+    // system_prompt — the UI writes back via BUZZ_ACP_SYSTEM_PROMPT.
+    let record = test_record();
+    let field = build_system_prompt_field(
+        &record,
+        &Some("File-driven prompt.".to_string()),
+        &no_tiers(),
+    )
+    .unwrap();
     assert_eq!(field.value.as_deref(), Some("File-driven prompt."));
     assert_eq!(field.origin, ConfigOrigin::ConfigFile);
-    assert!(matches!(field.write_via, ConfigWriteMechanism::ReadOnly));
+    assert!(matches!(
+        field.write_via,
+        ConfigWriteMechanism::RespawnWithEnvVar { ref env_key }
+            if env_key == "BUZZ_ACP_SYSTEM_PROMPT"
+    ));
     assert!(field.overridden_value.is_none());
 }
 
 #[test]
 fn record_system_prompt_shadows_config_file_prompt_as_secondary() {
-    let field = build_system_prompt_field(
-        &Some("Record prompt.".to_string()),
-        &Some("File prompt.".to_string()),
-    )
-    .unwrap();
+    let mut record = test_record();
+    record.system_prompt = Some("Record prompt.".to_string());
+    let field =
+        build_system_prompt_field(&record, &Some("File prompt.".to_string()), &no_tiers()).unwrap();
     assert_eq!(field.value.as_deref(), Some("Record prompt."));
     assert_eq!(field.origin, ConfigOrigin::BuzzExplicit);
     assert_eq!(field.overridden_value.as_deref(), Some("File prompt."));
@@ -510,19 +526,19 @@ fn record_system_prompt_shadows_config_file_prompt_as_secondary() {
 
 #[test]
 fn no_system_prompt_from_any_tier_yields_none() {
-    assert!(build_system_prompt_field(&None, &None).is_none());
+    let record = test_record();
+    assert!(build_system_prompt_field(&record, &None, &no_tiers()).is_none());
 }
 
 #[test]
 fn explicit_record_model_not_retagged_when_already_present() {
     let mut record = test_record();
-    // Record already has its own model — persona resolution should NOT re-tag.
+    // Record already has its own model — origin stays BuzzExplicit.
     record.model = Some("explicit-model".to_string());
     let runtime = test_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
-    // had_model == true, so no re-tagging occurs. Origin stays BuzzExplicit.
     let model = surface.normalized.model.unwrap();
     assert_eq!(model.value.as_deref(), Some("explicit-model"));
     assert_eq!(model.origin, ConfigOrigin::BuzzExplicit);
@@ -544,7 +560,7 @@ fn extra_env_vars_appear_in_advanced_as_buzz_explicit() {
         .insert("SPROUT_ACP_MEMORY".to_string(), "mem-value".to_string());
     let runtime = test_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     let advanced_keys: Vec<&str> = surface.advanced.iter().map(|f| f.key.as_str()).collect();
     assert!(
@@ -575,21 +591,15 @@ fn extra_env_vars_appear_in_advanced_as_buzz_explicit() {
 
 #[test]
 fn extra_env_var_skipped_when_already_in_file_config_extra() {
-    // If a key is in both record.env_vars and file_config.extra, the config
-    // file entry wins (it was already added to advanced). The env var must
-    // not produce a second entry.
-    //
-    // We can't inject into file_config.extra directly in a unit test (it
-    // comes from disk), so we verify the dedup logic via the normalized-key
-    // path: GOOSE_THINKING_EFFORT is a normalized key and must not appear
-    // in advanced even if set in env_vars.
+    // If a key is normalized, it must not appear in advanced even if set
+    // in env_vars.
     let mut record = test_record();
     record
         .env_vars
         .insert("GOOSE_THINKING_EFFORT".to_string(), "high".to_string());
     let runtime = test_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     let advanced_keys: Vec<&str> = surface.advanced.iter().map(|f| f.key.as_str()).collect();
     assert!(
@@ -598,7 +608,7 @@ fn extra_env_var_skipped_when_already_in_file_config_extra() {
     );
 }
 
-// ── buzz-agent normalized env-var field tests ───────────────────────────────
+// ── buzz-agent normalized env-var field tests ─────────────────────────────────
 //
 // buzz-agent uses env vars (not a config file) for max_output_tokens and
 // context_limit. build_numeric_env_field must surface these as BuzzExplicit
@@ -649,7 +659,7 @@ fn buzz_agent_max_output_tokens_from_env_is_buzz_explicit() {
     );
     let runtime = buzz_agent_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     let field = surface.normalized.max_output_tokens.unwrap();
     assert_eq!(field.value.as_deref(), Some("8192"));
@@ -670,7 +680,7 @@ fn buzz_agent_context_limit_from_env_is_buzz_explicit() {
     );
     let runtime = buzz_agent_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     let field = surface.normalized.context_limit.unwrap();
     assert_eq!(field.value.as_deref(), Some("100000"));
@@ -688,7 +698,7 @@ fn buzz_agent_max_tokens_absent_when_no_env_var_or_file() {
     let record = test_record();
     let runtime = buzz_agent_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     assert!(
         surface.normalized.max_output_tokens.is_none(),
@@ -713,7 +723,7 @@ fn buzz_agent_max_tokens_env_var_not_double_surfaced_in_advanced() {
     );
     let runtime = buzz_agent_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     let advanced_keys: Vec<&str> = surface.advanced.iter().map(|f| f.key.as_str()).collect();
     assert!(
@@ -734,7 +744,7 @@ fn buzz_agent_thinking_effort_from_env_is_buzz_explicit() {
         .insert("BUZZ_AGENT_THINKING_EFFORT".to_string(), "high".to_string());
     let runtime = buzz_agent_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     let field = surface.normalized.thinking_effort.unwrap();
     assert_eq!(field.value.as_deref(), Some("high"));
@@ -755,7 +765,7 @@ fn buzz_agent_thinking_effort_env_var_not_double_surfaced_in_advanced() {
     );
     let runtime = buzz_agent_runtime();
 
-    let surface = read_config_surface(&record, Some(runtime), None, None);
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
 
     let advanced_keys: Vec<&str> = surface.advanced.iter().map(|f| f.key.as_str()).collect();
     assert!(
@@ -764,10 +774,20 @@ fn buzz_agent_thinking_effort_env_var_not_double_surfaced_in_advanced() {
     );
 }
 
+// ── provider builder unit tests ───────────────────────────────────────────────
+
 #[test]
 fn missing_required_provider_still_returns_dropdown_field() {
-    let provider = build_provider_field(&None, &None, Some("GOOSE_PROVIDER"), false, true)
-        .expect("required provider field should be surfaced even when empty");
+    let record = test_record();
+    let provider = build_provider_field(
+        &record,
+        &None,
+        Some("GOOSE_PROVIDER"),
+        false,
+        true,
+        &no_tiers(),
+    )
+    .expect("required provider field should be surfaced even when empty");
 
     assert_eq!(provider.value, None);
     assert_eq!(provider.origin, ConfigOrigin::EnvVar);
@@ -776,5 +796,156 @@ fn missing_required_provider_still_returns_dropdown_field() {
 
 #[test]
 fn missing_optional_provider_stays_hidden() {
-    assert!(build_provider_field(&None, &None, Some("GOOSE_PROVIDER"), false, false).is_none());
+    let record = test_record();
+    assert!(build_provider_field(
+        &record,
+        &None,
+        Some("GOOSE_PROVIDER"),
+        false,
+        false,
+        &no_tiers()
+    )
+    .is_none());
 }
+
+// ── thinking_effort persona/global tier tests (AC-1..5) ──────────────────────
+//
+// The plan's acceptance criteria for effort tier resolution.
+// Tier ordering: record env > ACP > persona env > global env > config file.
+
+fn buzz_agent_rt() -> &'static KnownAcpRuntime {
+    crate::managed_agents::discovery::known_acp_runtime_exact("buzz-agent")
+        .expect("buzz-agent must be in catalog")
+}
+
+/// AC-1: no record effort, global env has effort → GlobalDefault.
+/// Real-world case: global-agent-config has BUZZ_AGENT_THINKING_EFFORT=high,
+/// per-agent record has no env_vars → effort must surface with GlobalDefault origin.
+#[test]
+fn global_effort_surfaces_as_global_default_when_record_has_none() {
+    let record = test_record();
+    let runtime = buzz_agent_rt();
+    let tiers = global_env_tiers("BUZZ_AGENT_THINKING_EFFORT", "high");
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let effort = surface
+        .normalized
+        .thinking_effort
+        .expect("effort must surface from global tier");
+    assert_eq!(effort.value.as_deref(), Some("high"));
+    assert_eq!(effort.origin, ConfigOrigin::GlobalDefault);
+}
+
+/// AC-2: persona env has effort, global also has effort → PersonaDefault wins, shadows global.
+#[test]
+fn persona_effort_shadows_global_and_tags_persona_default() {
+    let record = test_record();
+    let runtime = buzz_agent_rt();
+    let tiers = persona_and_global_env_tiers("BUZZ_AGENT_THINKING_EFFORT", "medium", "high");
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let effort = surface
+        .normalized
+        .thinking_effort
+        .expect("effort must surface from persona tier");
+    assert_eq!(effort.value.as_deref(), Some("medium"));
+    assert_eq!(effort.origin, ConfigOrigin::PersonaDefault);
+    // global is the overridden baseline
+    assert_eq!(effort.overridden_value.as_deref(), Some("high"));
+    assert_eq!(effort.overridden_origin, Some(ConfigOrigin::GlobalDefault));
+}
+
+/// AC-3: record-level effort wins over persona and global, stays BuzzExplicit.
+#[test]
+fn record_effort_outranks_persona_and_global_keeps_buzz_explicit() {
+    let mut record = test_record();
+    record.env_vars.insert(
+        "BUZZ_AGENT_THINKING_EFFORT".to_string(),
+        "xhigh".to_string(),
+    );
+    let runtime = buzz_agent_rt();
+    let tiers = persona_and_global_env_tiers("BUZZ_AGENT_THINKING_EFFORT", "medium", "high");
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let effort = surface
+        .normalized
+        .thinking_effort
+        .expect("effort must surface from record tier");
+    assert_eq!(effort.value.as_deref(), Some("xhigh"));
+    assert_eq!(effort.origin, ConfigOrigin::BuzzExplicit);
+}
+
+/// AC-4: no effort from any tier → thinking_effort field is absent.
+#[test]
+fn no_effort_anywhere_yields_no_thinking_effort_field() {
+    let record = test_record();
+    let runtime = buzz_agent_rt();
+
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
+
+    assert!(
+        surface.normalized.thinking_effort.is_none(),
+        "thinking_effort must be None when no tier has a value"
+    );
+}
+
+/// AC-5 (conflicting-ACP): inherited effort set (global=high) + live ACP effort=low
+/// → ACP wins as primary (AcpConfigOption), global is the overridden secondary.
+#[test]
+fn acp_effort_wins_over_inherited_global_effort_as_secondary() {
+    let record = test_record();
+    let runtime = buzz_agent_rt();
+    let cache = SessionConfigCache {
+        config_options: vec![AcpConfigOptionEntry {
+            config_id: "effort".to_string(),
+            category: Some("effort".to_string()),
+            display_name: Some("Effort".to_string()),
+            current_value: Some("low".to_string()),
+            options: vec![],
+        }],
+        available_modes: vec![],
+        available_models: vec![],
+        current_model: None,
+        model_overridden: false,
+        goose_native_config: None,
+        captured_at: "".to_string(),
+    };
+    let tiers = global_env_tiers("BUZZ_AGENT_THINKING_EFFORT", "high");
+
+    let surface = read_config_surface(&record, Some(runtime), Some(&cache), &tiers);
+
+    let effort = surface
+        .normalized
+        .thinking_effort
+        .expect("effort must surface from ACP tier");
+    // Live ACP value wins.
+    assert_eq!(effort.value.as_deref(), Some("low"));
+    assert_eq!(effort.origin, ConfigOrigin::AcpConfigOption);
+    // Global is surfaced as the overridden baseline.
+    assert_eq!(effort.overridden_value.as_deref(), Some("high"));
+    assert_eq!(effort.overridden_origin, Some(ConfigOrigin::GlobalDefault));
+}
+
+// ── Numerics inheritance tests ────────────────────────────────────────────────
+//
+// max_output_tokens and context_limit gain persona/global tiers.
+
+#[test]
+fn numeric_max_tokens_inherits_from_global_env() {
+    let record = test_record();
+    let runtime = buzz_agent_runtime();
+    let tiers = global_env_tiers("BUZZ_AGENT_MAX_OUTPUT_TOKENS", "16384");
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let field = surface.normalized.max_output_tokens.unwrap();
+    assert_eq!(field.value.as_deref(), Some("16384"));
+    assert_eq!(field.origin, ConfigOrigin::GlobalDefault);
+}
+
+// ── Extended tests (split file to respect line-count ratchet) ────────────────
+#[path = "reader_tests_ext.rs"]
+mod ext;
diff --git a/desktop/src-tauri/src/managed_agents/config_bridge/reader_tests_ext.rs b/desktop/src-tauri/src/managed_agents/config_bridge/reader_tests_ext.rs
new file mode 100644
index 0000000000..8613124f25
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/config_bridge/reader_tests_ext.rs
@@ -0,0 +1,258 @@
+//! Additional tests for `config_bridge/reader.rs` — split out to keep
+//! `reader_tests.rs` under the 1000-line file-size ratchet.
+//!
+//! Included as `mod ext` inside `reader_tests.rs`, so `use super::*` gives
+//! access to all helpers and types from that module.
+
+use super::*;
+
+// ── Numerics inheritance tests ────────────────────────────────────────────────
+//
+// max_output_tokens and context_limit gain persona/global tiers.
+
+#[test]
+fn numeric_context_limit_inherits_from_persona_env() {
+    let record = test_record();
+    let runtime = buzz_agent_runtime();
+    let tiers = persona_env_tiers("BUZZ_AGENT_MAX_CONTEXT_TOKENS", "200000");
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let field = surface.normalized.context_limit.unwrap();
+    assert_eq!(field.value.as_deref(), Some("200000"));
+    assert_eq!(field.origin, ConfigOrigin::PersonaDefault);
+}
+
+#[test]
+fn record_max_tokens_overrides_global_env_with_secondary() {
+    let mut record = test_record();
+    record.env_vars.insert(
+        "BUZZ_AGENT_MAX_OUTPUT_TOKENS".to_string(),
+        "8192".to_string(),
+    );
+    let runtime = buzz_agent_runtime();
+    let tiers = global_env_tiers("BUZZ_AGENT_MAX_OUTPUT_TOKENS", "16384");
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let field = surface.normalized.max_output_tokens.unwrap();
+    assert_eq!(field.value.as_deref(), Some("8192"));
+    assert_eq!(field.origin, ConfigOrigin::BuzzExplicit);
+    // Global value is the overridden secondary.
+    assert_eq!(field.overridden_value.as_deref(), Some("16384"));
+    assert_eq!(field.overridden_origin, Some(ConfigOrigin::GlobalDefault));
+}
+
+// ── Env-vs-structured collision tests (plan v3, Phase 2) ─────────────────────
+
+/// Collision test 1: persona structured prompt + global env BUZZ_ACP_SYSTEM_PROMPT
+/// → global env wins (env block sits entirely above structured).
+#[test]
+fn global_env_prompt_wins_over_persona_structured_prompt() {
+    let record = test_record();
+    let runtime = test_runtime();
+    let tiers = InheritedConfigTiers {
+        global_env: {
+            let mut m = BTreeMap::new();
+            m.insert(
+                "BUZZ_ACP_SYSTEM_PROMPT".to_string(),
+                "global-env-prompt".to_string(),
+            );
+            m
+        },
+        persona_prompt: Some("persona-structured-prompt".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let prompt = surface.normalized.system_prompt.unwrap();
+    assert_eq!(prompt.value.as_deref(), Some("global-env-prompt"));
+    assert_eq!(prompt.origin, ConfigOrigin::GlobalDefault);
+}
+
+/// Collision test 2: structured persona/record model + higher user-env value at
+/// the runtime's model key → env value wins.
+#[test]
+fn persona_env_model_wins_over_persona_structured_model() {
+    let record = test_record(); // no record.model
+    let runtime = test_runtime(); // GOOSE_MODEL
+    let tiers = InheritedConfigTiers {
+        persona_env: {
+            let mut m = BTreeMap::new();
+            m.insert("GOOSE_MODEL".to_string(), "env-model".to_string());
+            m
+        },
+        persona_model: Some("struct-persona-model".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let model = surface.normalized.model.unwrap();
+    // persona env outranks persona struct because env candidates precede struct
+    assert_eq!(model.value.as_deref(), Some("env-model"));
+    assert_eq!(model.origin, ConfigOrigin::PersonaDefault);
+}
+
+/// Collision test 3: no env representation → structured persona/record/global
+/// fallback and provenance remain intact.
+#[test]
+fn structured_fallback_intact_when_no_env_representation() {
+    let record = test_record(); // no record.model, no env vars
+    let runtime = test_runtime();
+    let tiers = InheritedConfigTiers {
+        persona_model: Some("struct-persona-model".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let model = surface.normalized.model.unwrap();
+    assert_eq!(model.value.as_deref(), Some("struct-persona-model"));
+    assert_eq!(model.origin, ConfigOrigin::PersonaDefault);
+}
+
+// ── Post-sanitization fallthrough test ───────────────────────────────────────
+//
+// Sanitization itself happens at the command boundary in `build_inherited_tiers`
+// (a value with a NUL byte or an oversize value is dropped from the tier) and is
+// pinned by the tests in `commands/agent_config_tests.rs`. The reader only ever
+// sees the sanitized result, so what it must guarantee is the downstream half:
+// a key stripped from one tier falls through to the next.
+
+/// A key absent from the global env tier — the shape the reader sees after the
+/// command boundary strips an invalid value — falls through to the persona tier.
+#[test]
+fn post_sanitization_empty_global_env_falls_through_to_persona_tier() {
+    let record = test_record();
+    let runtime = buzz_agent_rt();
+    // No global env (stripped); persona provides the valid fallback.
+    let tiers = persona_env_tiers("BUZZ_AGENT_THINKING_EFFORT", "medium");
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    // Persona value surfaces instead of the stripped global value.
+    let effort = surface.normalized.thinking_effort.unwrap();
+    assert_eq!(effort.value.as_deref(), Some("medium"));
+    assert_eq!(effort.origin, ConfigOrigin::PersonaDefault);
+}
+
+// ── Pass-3 prompt collision test ─────────────────────────────────────────────
+//
+// From Thufir's pass-3 verdict MINOR clarification (promoted to required):
+// definition-less record with both structured and env prompt — env wins.
+
+/// Pass-3 clarification: record.system_prompt = A + record env
+/// BUZZ_ACP_SYSTEM_PROMPT = B → B wins as BuzzExplicit.
+/// The env block sits above the struct block per v3 candidate-preparation
+/// contract; current reader semantics (struct before env) would be wrong.
+#[test]
+fn record_env_prompt_wins_over_record_struct_prompt_as_buzz_explicit() {
+    let mut record = test_record();
+    record.system_prompt = Some("struct-prompt-A".to_string());
+    record.env_vars.insert(
+        "BUZZ_ACP_SYSTEM_PROMPT".to_string(),
+        "env-prompt-B".to_string(),
+    );
+    let runtime = test_runtime();
+
+    let surface = read_config_surface(&record, Some(runtime), None, &no_tiers());
+
+    let prompt = surface.normalized.system_prompt.unwrap();
+    assert_eq!(prompt.value.as_deref(), Some("env-prompt-B"));
+    assert_eq!(prompt.origin, ConfigOrigin::BuzzExplicit);
+    // Struct prompt is the secondary.
+    assert_eq!(prompt.overridden_value.as_deref(), Some("struct-prompt-A"));
+    assert_eq!(prompt.overridden_origin, Some(ConfigOrigin::BuzzExplicit));
+}
+
+// ── Definition env tier tests (Layer 2b) ─────────────────────────────────────
+//
+// The harness definition's `env` block sits below global env and above
+// structured values in spawn's precedence (Layer 2b). These tests exercise
+// the reader's mapping of that tier to `HarnessDefault` origin.
+
+/// Definition env wins over structured persona model when no user-env or
+/// global-env candidate is present.
+#[test]
+fn definition_env_beats_structured_persona_model() {
+    let record = test_record(); // no record.model, no record.env_vars
+    let runtime = test_runtime(); // model_env_var = "GOOSE_MODEL"
+    let tiers = InheritedConfigTiers {
+        definition_env: {
+            let mut m = BTreeMap::new();
+            m.insert("GOOSE_MODEL".to_string(), "harness-model".to_string());
+            m
+        },
+        persona_model: Some("persona-struct-model".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let model = surface.normalized.model.unwrap();
+    assert_eq!(model.value.as_deref(), Some("harness-model"));
+    assert_eq!(model.origin, ConfigOrigin::HarnessDefault);
+    // Structured persona model is the overridden secondary.
+    assert_eq!(
+        model.overridden_value.as_deref(),
+        Some("persona-struct-model")
+    );
+    assert_eq!(model.overridden_origin, Some(ConfigOrigin::PersonaDefault));
+}
+
+/// Global env beats definition env — user-settable tiers always win over the
+/// harness author's defaults.
+#[test]
+fn global_env_beats_definition_env() {
+    let record = test_record();
+    let runtime = test_runtime(); // model_env_var = "GOOSE_MODEL"
+    let tiers = InheritedConfigTiers {
+        global_env: {
+            let mut m = BTreeMap::new();
+            m.insert("GOOSE_MODEL".to_string(), "global-model".to_string());
+            m
+        },
+        definition_env: {
+            let mut m = BTreeMap::new();
+            m.insert("GOOSE_MODEL".to_string(), "harness-model".to_string());
+            m
+        },
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let model = surface.normalized.model.unwrap();
+    assert_eq!(model.value.as_deref(), Some("global-model"));
+    assert_eq!(model.origin, ConfigOrigin::GlobalDefault);
+    // Harness default is the overridden secondary.
+    assert_eq!(model.overridden_value.as_deref(), Some("harness-model"));
+    assert_eq!(model.overridden_origin, Some(ConfigOrigin::HarnessDefault));
+}
+
+/// A reserved key in the definition env is stripped by sanitization and must
+/// not reach the reader. This test exercises the reader's contract (a key
+/// absent from the tier falls through) — sanitization itself is pinned in
+/// the `agent_config_tests.rs` constructor tests.
+#[test]
+fn reserved_key_absent_from_definition_env_falls_through() {
+    let record = test_record();
+    let runtime = test_runtime(); // model_env_var = "GOOSE_MODEL"
+                                  // definition_env contains only an unrelated key — the env map here is what
+                                  // the command boundary would produce after stripping a reserved key; the
+                                  // reader must fall through to the next tier (persona structured model).
+    let tiers = InheritedConfigTiers {
+        definition_env: BTreeMap::new(), // stripped — nothing survives
+        persona_model: Some("persona-struct-model".to_string()),
+        ..Default::default()
+    };
+
+    let surface = read_config_surface(&record, Some(runtime), None, &tiers);
+
+    let model = surface.normalized.model.unwrap();
+    // Falls through to persona structured model.
+    assert_eq!(model.value.as_deref(), Some("persona-struct-model"));
+    assert_eq!(model.origin, ConfigOrigin::PersonaDefault);
+}
diff --git a/desktop/src-tauri/src/managed_agents/config_bridge/types.rs b/desktop/src-tauri/src/managed_agents/config_bridge/types.rs
index 15ccb718e7..6ca2592538 100644
--- a/desktop/src-tauri/src/managed_agents/config_bridge/types.rs
+++ b/desktop/src-tauri/src/managed_agents/config_bridge/types.rs
@@ -2,6 +2,41 @@ use std::collections::BTreeMap;
 
 use serde::{Deserialize, Serialize};
 
+/// Sanitized inherited config tiers passed to the reader.
+///
+/// Built at the `agent_config` command boundary with spawn-equivalent
+/// sanitization: reserved, malformed, NUL-value, and oversize-value env keys
+/// are stripped (matching `merged_user_env`). Structured fields are
+/// normalized: blank/whitespace-only values collapse to `None`.
+///
+/// Orphaned persona links (persona_id references a missing persona) produce
+/// an empty persona env tier and `None` for all structured persona fields —
+/// the panel still renders from record/global. This diverges deliberately from
+/// spawn's `OrphanedInstance` refusal, which is a spawn-safety property the
+/// display surface does not need to enforce.
+#[derive(Debug, Clone, Default)]
+pub struct InheritedConfigTiers {
+    /// Sanitized env vars from the linked persona definition.
+    pub persona_env: BTreeMap<String, String>,
+    /// Sanitized env vars from the global agent config.
+    pub global_env: BTreeMap<String, String>,
+    /// Sanitized env vars from the resolved harness definition (`HarnessDefinition::env`).
+    /// Sits below global env and above structured values, matching spawn Layer 2b.
+    /// Empty for preset harnesses (all shipped presets have `env: {}`); only
+    /// user-authored custom harness JSONs with a non-empty `env` block contribute here.
+    pub definition_env: BTreeMap<String, String>,
+    /// Structured model from the linked persona (non-blank only).
+    pub persona_model: Option<String>,
+    /// Structured provider from the linked persona (non-blank only).
+    pub persona_provider: Option<String>,
+    /// Structured system_prompt from the linked persona (non-blank only).
+    pub persona_prompt: Option<String>,
+    /// Structured model from global config (non-blank only).
+    pub global_model: Option<String>,
+    /// Structured provider from global config (non-blank only).
+    pub global_provider: Option<String>,
+}
+
 /// Where a config value came from — determines precedence and UI annotations.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -17,14 +52,12 @@ pub enum ConfigOrigin {
     /// Read from harness config file on disk (tier 2b, lowest precedence).
     ConfigFile,
     /// Value inherited from persona defaults.
-    /// Populated by the `get_agent_config_surface` call site: persona values are
-    /// resolved before calling the reader, then the surface is post-processed to
-    /// re-tag injected fields from `BuzzExplicit` to `PersonaDefault`.
+    /// Populated when a persona's env var or structured field wins for this
+    /// field in the reader's candidate resolution.
     PersonaDefault,
     /// Value inherited from global agent configuration defaults.
     /// The lowest user-settable layer — active when neither the agent record nor
-    /// the linked persona specifies a value. Re-tagged from `BuzzExplicit` by the
-    /// `resolve_config_surface` call site, analogously to `PersonaDefault`.
+    /// the linked persona specifies a value.
     GlobalDefault,
     /// Live runtime model override applied via the ModelPicker (Phase 3).
     /// The ACP session's current model diverges from the persona model because
@@ -35,6 +68,11 @@ pub enum ConfigOrigin {
     /// env var. E.g. Claude Code only supports Anthropic as a provider; the
     /// "locked" display is synthesized by the config bridge, not read from disk.
     HarnessConstraint,
+    /// Value comes from a custom harness definition's `env` block.
+    /// Sits below global env and above structured persona/global values,
+    /// matching spawn Layer 2b. Only reachable for user-authored custom harness
+    /// JSONs with a non-empty `env` block; preset harnesses always have empty env.
+    HarnessDefault,
 }
 
 /// How a config field can be written back to the runtime.
diff --git a/desktop/src-tauri/src/managed_agents/discovery.rs b/desktop/src-tauri/src/managed_agents/discovery.rs
index 8d1b8a5013..248625ce93 100644
--- a/desktop/src-tauri/src/managed_agents/discovery.rs
+++ b/desktop/src-tauri/src/managed_agents/discovery.rs
@@ -9,10 +9,10 @@ use crate::managed_agents::{
     AcpAvailabilityStatus, AcpRuntimeCatalogEntry, AuthStatus, CommandAvailabilityInfo,
     HarnessSource,
 };
-
 mod presets;
 mod runtime_metadata;
-
+#[macro_use]
+mod windows_install;
 use presets::{preset_catalog_entry, PRESET_HARNESSES};
 pub(crate) use presets::{preset_harness_definitions, preset_harness_ids};
 pub(crate) use runtime_metadata::KnownAcpRuntime;
@@ -85,7 +85,7 @@ const KNOWN_ACP_RUNTIMES: &[KnownAcpRuntime] = &[
         cli_install_commands: &["curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash"],
         // Goose's stable release currently publishes only the Unix installer;
         // its official Windows instructions intentionally point at this main-branch script.
-        cli_install_commands_windows: &["powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"$env:CONFIGURE='false'; irm https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1 | iex\""],
+        cli_install_commands_windows: &[windows_install_command!("goose", "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1", "$env:CONFIGURE='false'; ")],
         adapter_install_commands: &[],
         cli_install_instructions_url: "https://goose-docs.ai/docs/getting-started/installation/",
         adapter_install_instructions_url: "",
@@ -117,7 +117,7 @@ const KNOWN_ACP_RUNTIMES: &[KnownAcpRuntime] = &[
         mcp_hooks: false,
         underlying_cli: Some("claude"),
         cli_install_commands: &["curl -fsSL https://claude.ai/install.sh | bash"],
-        cli_install_commands_windows: &["powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"irm https://claude.ai/install.ps1 | iex\""],
+        cli_install_commands_windows: &[windows_install_command!("claude", "https://claude.ai/install.ps1")],
         adapter_install_commands: &["npm install -g @agentclientprotocol/claude-agent-acp"],
         cli_install_instructions_url: "https://code.claude.com/docs/en/getting-started",
         adapter_install_instructions_url: "https://github.com/agentclientprotocol/claude-agent-acp",
@@ -149,7 +149,7 @@ const KNOWN_ACP_RUNTIMES: &[KnownAcpRuntime] = &[
         mcp_hooks: false,
         underlying_cli: Some("codex"),
         cli_install_commands: &["curl -fsSL https://chatgpt.com/codex/install.sh | sh"],
-        cli_install_commands_windows: &["powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"irm https://chatgpt.com/codex/install.ps1 | iex\""],
+        cli_install_commands_windows: &[windows_install_command!("codex", "https://chatgpt.com/codex/install.ps1")],
         adapter_install_commands: &["npm install -g @agentclientprotocol/codex-acp"],
         cli_install_instructions_url: "https://developers.openai.com/codex/cli/",
         adapter_install_instructions_url: "https://github.com/agentclientprotocol/codex-acp",
diff --git a/desktop/src-tauri/src/managed_agents/discovery/presets.rs b/desktop/src-tauri/src/managed_agents/discovery/presets.rs
index 72c4657dc7..3622b21c4a 100644
--- a/desktop/src-tauri/src/managed_agents/discovery/presets.rs
+++ b/desktop/src-tauri/src/managed_agents/discovery/presets.rs
@@ -106,7 +106,7 @@ pub(super) const PRESET_HARNESSES: &[PresetHarness] = &[
         label: "Oh My Pi",
         command: "omp",
         args: &["acp"],
-        install_instructions_url: "https://github.com/can1357/oh-my-pi",
+        install_instructions_url: "https://omp.sh/",
         install_hint: "Buzz talks to Oh My Pi through its CLI's ACP mode (omp acp).",
         underlying_cli: None,
     },
diff --git a/desktop/src-tauri/src/managed_agents/discovery/windows_install.rs b/desktop/src-tauri/src/managed_agents/discovery/windows_install.rs
new file mode 100644
index 0000000000..09e27a62be
--- /dev/null
+++ b/desktop/src-tauri/src/managed_agents/discovery/windows_install.rs
@@ -0,0 +1,225 @@
+//! Defender-safe construction of the Windows PowerShell CLI install commands.
+//!
+//! # Why the shape matters
+//!
+//! Windows Defender's ML classifier flags the bare `irm <url> | iex` command
+//! line as `Trojan:Win32/Commando.A!ml` — piping a downloaded string straight
+//! into `Invoke-Expression` is a textbook dropper signature, so the *command
+//! line itself* is scored, independent of what the URL actually serves. The
+//! spawn is denied before PowerShell runs, surfacing as
+//! `failed to spawn shell: Access is denied. (os error 5)`, and the block is
+//! sticky: Defender's "Allow" button does not clear it.
+//!
+//! [`windows_install_command!`] emits the two-step form instead — download the
+//! vendor script to a file, then execute the file — which does not match that
+//! signature. All three runtimes use it, not only the one observed failing:
+//! Goose and Claude escaped by scoring under the classifier threshold, which is
+//! luck rather than design, and the threshold is not ours to depend on.
+//!
+//! # Why one macro instead of three literals
+//!
+//! The catalog needs `&'static str`, so the commands must be built at compile
+//! time from literals. Emitting them from a single macro means the security
+//! shape is defined once and cannot drift between runtimes as URLs change —
+//! a per-runtime literal would let one entry silently regress to `iex`.
+//!
+//! # Exit-code fidelity
+//!
+//! [#2892](https://github.com/block/buzz/pull/2892) established that an install
+//! step must not report success when the download failed. Two pieces preserve
+//! that here, and both are load-bearing:
+//!
+//! - `$ErrorActionPreference='Stop'` makes a failed `Invoke-RestMethod`
+//!   terminate the whole command. Without it a failed download falls through to
+//!   `& $installer` on a path that does not exist, and PowerShell exits **0** —
+//!   the exact masking #2892 removed, in a new dress. `Stop` also prevents
+//!   executing a *stale* installer left in `$env:TEMP` by an earlier run.
+//! - `exit $LASTEXITCODE` propagates the vendor script's own exit code. Without
+//!   it PowerShell reports its own status and a vendor failure of `3` flattens
+//!   to `1`, losing the distinction the retry logic reads.
+//!
+//! Verified against `pwsh` over a local HTTP server: vendor exit 3 surfaces as
+//! 3, vendor exit 0 as 0, a 404 and an unresolvable host as non-zero, and a
+//! planted stale installer is never executed. The old `irm | iex` shape
+//! produces identical codes for all four, so this is not a behavior change.
+//!
+//! # Quoting contract
+//!
+//! The emitted body is wrapped in one double-quote pair, which
+//! `install_powershell_command` strips before handing the body to PowerShell.
+//! The body therefore uses **only single quotes** internally; a double quote
+//! would terminate that pair early and truncate the command.
+
+/// Build the Windows CLI install command for one runtime.
+///
+/// `slug` names the downloaded script (`buzz-install-<slug>.ps1`) so concurrent
+/// installs of different runtimes cannot overwrite each other's file. The
+/// optional third argument carries a runtime's env prefix (Goose's
+/// `$env:CONFIGURE='false'; `) and must end with `; `.
+///
+/// See the module docs for why each fragment is present.
+macro_rules! windows_install_command {
+    ($slug:literal, $url:literal) => {
+        windows_install_command!($slug, $url, "")
+    };
+    ($slug:literal, $url:literal, $env_prefix:literal) => {
+        concat!(
+            "powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"",
+            $env_prefix,
+            "$ErrorActionPreference='Stop'; ",
+            "$installer=Join-Path $env:TEMP 'buzz-install-",
+            $slug,
+            ".ps1'; ",
+            "Invoke-RestMethod ",
+            $url,
+            " -OutFile $installer; ",
+            "& $installer; ",
+            "exit $LASTEXITCODE\"",
+        )
+    };
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::managed_agents::known_acp_runtime_exact;
+
+    /// Every runtime that ships a Windows install command. `cli_install_commands_windows`
+    /// is read directly rather than through `cli_install_commands_for_os()` so these
+    /// assertions cover the Windows strings while running on the Linux CI host.
+    fn windows_install_commands() -> Vec<(&'static str, &'static str)> {
+        ["goose", "claude", "codex"]
+            .into_iter()
+            .flat_map(|id| {
+                known_acp_runtime_exact(id)
+                    .expect("runtime must exist in the catalog")
+                    .cli_install_commands_windows
+                    .iter()
+                    .map(move |command| (id, *command))
+            })
+            .collect()
+    }
+
+    /// The whole point of the change: no runtime may carry the flagged
+    /// download-and-execute-in-one-line signature.
+    #[test]
+    fn test_no_windows_install_command_pipes_a_download_into_iex() {
+        for (id, command) in windows_install_commands() {
+            assert!(
+                !command.contains("| iex"),
+                "{id}: `irm | iex` is the shape Defender flags as Trojan:Win32/Commando.A!ml; \
+                 download to a file and execute the file instead. Got: {command}"
+            );
+            assert!(
+                !command.contains("Invoke-Expression"),
+                "{id}: Invoke-Expression on downloaded content carries the same signature. \
+                 Got: {command}"
+            );
+        }
+    }
+
+    /// All three runtimes must be hardened, not just the one observed failing.
+    /// Goose and Claude escaped only by scoring under the classifier threshold.
+    #[test]
+    fn test_every_windows_install_command_downloads_to_a_file_then_executes_it() {
+        let commands = windows_install_commands();
+        assert_eq!(
+            commands.len(),
+            3,
+            "expected exactly one Windows install command for each of goose, claude, codex"
+        );
+        for (id, command) in commands {
+            assert!(
+                command.contains("-OutFile $installer"),
+                "{id}: must download the vendor script to a file. Got: {command}"
+            );
+            assert!(
+                command.contains("& $installer"),
+                "{id}: must execute the downloaded file. Got: {command}"
+            );
+            assert!(
+                command.contains(&format!("buzz-install-{id}.ps1")),
+                "{id}: script name must be runtime-specific so concurrent installs of \
+                 different runtimes cannot overwrite each other. Got: {command}"
+            );
+        }
+    }
+
+    /// Guards the #2892 regression: without `Stop`, a failed download falls
+    /// through to a missing file and PowerShell exits 0, reporting a failed
+    /// install as a success. Without `exit $LASTEXITCODE`, the vendor's own
+    /// exit code is replaced by PowerShell's.
+    #[test]
+    fn test_every_windows_install_command_preserves_failure_exit_codes() {
+        for (id, command) in windows_install_commands() {
+            assert!(
+                command.contains("$ErrorActionPreference='Stop'"),
+                "{id}: a failed download must abort instead of running a missing or stale \
+                 installer and exiting 0 (see #2892). Got: {command}"
+            );
+            assert!(
+                command.contains("exit $LASTEXITCODE"),
+                "{id}: the vendor script's exit code must propagate. Got: {command}"
+            );
+        }
+    }
+
+    /// `install_powershell_command` strips exactly one outer double-quote pair.
+    /// An inner double quote would close that pair early and truncate the body.
+    #[test]
+    fn test_every_windows_install_command_quotes_the_body_exactly_once() {
+        for (id, command) in windows_install_commands() {
+            let body = command
+                .split_once(" -Command ")
+                .map(|(_, body)| body)
+                .unwrap_or_else(|| panic!("{id}: command must pass a -Command body: {command}"));
+            assert!(
+                body.starts_with('"') && body.ends_with('"'),
+                "{id}: body must be wrapped in one double-quote pair. Got: {body}"
+            );
+            assert_eq!(
+                body.matches('"').count(),
+                2,
+                "{id}: body must contain no inner double quotes — one would terminate the \
+                 outer pair early and truncate the command. Got: {body}"
+            );
+        }
+    }
+
+    /// Goose's installer reads `CONFIGURE` to stay non-interactive; losing the
+    /// prefix hangs the install waiting on input that never comes.
+    #[test]
+    fn test_goose_windows_install_command_keeps_its_env_prefix() {
+        let goose = known_acp_runtime_exact("goose").unwrap();
+        let command = goose.cli_install_commands_windows[0];
+        assert!(
+            command.contains("$env:CONFIGURE='false'"),
+            "goose must stay non-interactive. Got: {command}"
+        );
+        assert!(
+            command.find("$env:CONFIGURE='false'").unwrap()
+                < command.find("Invoke-RestMethod").unwrap(),
+            "the env prefix must be set before the installer runs. Got: {command}"
+        );
+    }
+
+    /// The vendor URLs are the payload; pin them so a refactor of the shared
+    /// shape cannot silently retarget a download.
+    #[test]
+    fn test_windows_install_commands_target_the_official_vendor_urls() {
+        for (id, expected) in [
+            (
+                "goose",
+                "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1",
+            ),
+            ("claude", "https://claude.ai/install.ps1"),
+            ("codex", "https://chatgpt.com/codex/install.ps1"),
+        ] {
+            let runtime = known_acp_runtime_exact(id).unwrap();
+            let command = runtime.cli_install_commands_windows[0];
+            assert!(
+                command.contains(&format!("Invoke-RestMethod {expected} -OutFile")),
+                "{id}: must download from {expected}. Got: {command}"
+            );
+        }
+    }
+}
diff --git a/desktop/src-tauri/src/managed_agents/env_vars.rs b/desktop/src-tauri/src/managed_agents/env_vars.rs
index 592a5cbbd9..1653371e7f 100644
--- a/desktop/src-tauri/src/managed_agents/env_vars.rs
+++ b/desktop/src-tauri/src/managed_agents/env_vars.rs
@@ -77,6 +77,10 @@ pub(crate) const RESERVED_ENV_KEYS: &[&str] = &[
     "BUZZ_ACP_RESPOND_TO",
     "BUZZ_ACP_RESPOND_TO_ALLOWLIST",
     "BUZZ_ACP_AGENT_OWNER",
+    // Remote lifetime/presence policy: user env must not disable the
+    // desktop/provider-owned bounds while the saved record still promises them.
+    "BUZZ_ACP_EXIT_AFTER_INACTIVITY",
+    "BUZZ_ACP_NO_PRESENCE",
     // Readiness handoff: desktop is the ONLY readiness source. A saved or
     // ambient env var must not be able to forge setup mode (NotReady) on a
     // Ready agent or suppress it (empty/stale payload) on a NotReady one.
@@ -307,28 +311,5 @@ pub(crate) fn live_persona_env(
         .unwrap_or_default()
 }
 
-/// Resolve live env_vars for a linked persona, loading personas from disk.
-///
-/// Returns the persona's `env_vars` map if a persona_id is provided and found;
-/// returns an empty map if no persona is linked. Errors if the linked persona
-/// is missing. Used by the provider deploy path, which has no pre-loaded
-/// persona slice.
-pub(crate) fn resolve_persona_env(
-    app: &tauri::AppHandle,
-    persona_id: Option<&str>,
-) -> Result<std::collections::BTreeMap<String, String>, String> {
-    let Some(pid) = persona_id else {
-        return Ok(std::collections::BTreeMap::new());
-    };
-    let personas = super::load_personas(app).map_err(|e| {
-        format!("failed to load personas while resolving env for persona `{pid}`: {e}")
-    })?;
-    let persona = personas
-        .into_iter()
-        .find(|p| p.id == pid)
-        .ok_or_else(|| format!("persona `{pid}` not found while resolving env"))?;
-    Ok(persona.env_vars)
-}
-
 #[cfg(test)]
 mod tests;
diff --git a/desktop/src-tauri/src/managed_agents/env_vars/tests.rs b/desktop/src-tauri/src/managed_agents/env_vars/tests.rs
index cf57b12546..534c2e0835 100644
--- a/desktop/src-tauri/src/managed_agents/env_vars/tests.rs
+++ b/desktop/src-tauri/src/managed_agents/env_vars/tests.rs
@@ -158,6 +158,15 @@ fn reserved_keys_include_respond_to_gate() {
     }
 }
 
+#[test]
+fn reserved_keys_include_remote_lifetime_policy() {
+    for key in ["BUZZ_ACP_EXIT_AFTER_INACTIVITY", "BUZZ_ACP_NO_PRESENCE"] {
+        assert!(is_reserved_env_key(key), "{key} should be reserved");
+        let agent = map(&[(key, "0")]);
+        assert!(merged_user_env(&BTreeMap::new(), &agent).is_empty());
+    }
+}
+
 #[test]
 fn reserved_keys_include_code_execution_surface() {
     // The agent/MCP command + args are what Buzz actually exec's.
diff --git a/desktop/src-tauri/src/managed_agents/mod.rs b/desktop/src-tauri/src/managed_agents/mod.rs
index be9b07cf11..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/runtime.rs b/desktop/src-tauri/src/managed_agents/runtime.rs
index 37927961ed..3173126b90 100644
--- a/desktop/src-tauri/src/managed_agents/runtime.rs
+++ b/desktop/src-tauri/src/managed_agents/runtime.rs
@@ -22,8 +22,7 @@ pub(crate) use path::should_use_inherited;
 
 mod metadata;
 pub(crate) use metadata::{
-    resolve_effective_prompt_model_provider, resolve_session_title, runtime_metadata_env_vars,
-    SESSION_TITLE_ENV_VAR,
+    resolve_session_title, runtime_metadata_env_vars, SESSION_TITLE_ENV_VAR,
 };
 
 mod stop;
diff --git a/desktop/src-tauri/src/managed_agents/runtime/metadata.rs b/desktop/src-tauri/src/managed_agents/runtime/metadata.rs
index 288ce06b0a..96ac73e347 100644
--- a/desktop/src-tauri/src/managed_agents/runtime/metadata.rs
+++ b/desktop/src-tauri/src/managed_agents/runtime/metadata.rs
@@ -57,32 +57,6 @@ pub(crate) fn resolve_session_title(display_name: Option<&str>, name: &str) -> O
         .find(|value| !value.is_empty())
 }
 
-/// Resolve effective prompt/model/provider using definition-authoritative
-/// semantics for linked instances.
-///
-/// Used by `agent_config.rs` to inject persona defaults into the config surface
-/// before running the reader.
-pub(crate) fn resolve_effective_prompt_model_provider(
-    persona_id: Option<&str>,
-    personas: &[crate::managed_agents::types::AgentDefinition],
-    record_prompt: Option<String>,
-    record_model: Option<String>,
-    record_provider: Option<String>,
-) -> (Option<String>, Option<String>, Option<String>) {
-    match persona_id.and_then(|pid| personas.iter().find(|p| p.id == pid)) {
-        Some(p) => {
-            fn non_blank(v: Option<&str>) -> Option<String> {
-                v.filter(|s| !s.trim().is_empty()).map(str::to_owned)
-            }
-            let prompt = non_blank(Some(&p.system_prompt));
-            let model = non_blank(p.model.as_deref());
-            let provider = non_blank(p.provider.as_deref());
-            (prompt, model, provider)
-        }
-        None => (record_prompt, record_model, record_provider),
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::resolve_session_title;
diff --git a/desktop/src-tauri/src/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/mouse_nav.rs b/desktop/src-tauri/src/mouse_nav.rs
new file mode 100644
index 0000000000..cd729f7304
--- /dev/null
+++ b/desktop/src-tauri/src/mouse_nav.rs
@@ -0,0 +1,142 @@
+//! Native macOS handler for back/forward navigation inputs (mouse X1/X2
+//! buttons and horizontal swipe gestures).
+//!
+//! WKWebView never delivers these inputs to the web content layer, so a DOM
+//! listener can't see them (Safari itself handles them natively in the app
+//! layer, not in the page). This module installs an NSEvent local monitor
+//! and emits a `mouse-nav` Tauri event that `useBackForwardControls` acts on
+//! in the frontend. Two event shapes map to navigation:
+//!
+//! - `otherMouseUp` with button 3/4 — mice whose X1/X2 buttons reach the app
+//!   as plain mouse buttons.
+//! - `swipe` with a horizontal delta — AppKit's page-swipe gesture
+//!   (`swipeWithEvent:`): `deltaX > 0` is back, `deltaX < 0` is forward.
+//!   Sent by mouse drivers that synthesize a page-swipe gesture for the
+//!   back/forward buttons instead of button-3/4 events (the hardware this
+//!   was verified on). Stock Apple trackpad and Magic Mouse swipes arrive
+//!   as phased scroll-wheel events instead, which this module does not
+//!   handle — that path (`ScrollWheel` + `trackSwipeEventWithOptions:`,
+//!   which also needs scroll-edge detection) is a follow-up.
+//!
+//! Compiled macOS-only (via `tray_menu`). Non-macOS X1/X2 behavior is left
+//! to the underlying webview.
+
+/// Maps an `otherMouseUp` button number to a navigation direction.
+/// Buttons 3 and 4 are X1 (back) and X2 (forward).
+fn direction_for_button(button: isize) -> Option<&'static str> {
+    match button {
+        3 => Some("back"),
+        4 => Some("forward"),
+        _ => None,
+    }
+}
+
+/// Maps a swipe gesture's horizontal delta to a navigation direction,
+/// following the AppKit `swipeWithEvent:` convention: positive is back,
+/// negative is forward. A swipe arrives as a begin/end pair and only the
+/// end event carries the direction, so `deltaX == 0` maps to `None`.
+fn direction_for_swipe(delta_x: f64) -> Option<&'static str> {
+    if delta_x > 0.0 {
+        Some("back")
+    } else if delta_x < 0.0 {
+        Some("forward")
+    } else {
+        None
+    }
+}
+
+pub fn init<R: tauri::Runtime>(app_handle: &tauri::AppHandle<R>) {
+    use block2::RcBlock;
+    use objc2_app_kit::{NSEvent, NSEventMask, NSEventType};
+    use tauri::Emitter;
+
+    let app = app_handle.clone();
+    let block = RcBlock::new(move |event: std::ptr::NonNull<NSEvent>| -> *mut NSEvent {
+        // SAFETY: the monitor hands us a valid NSEvent for the matched mask.
+        let ev = unsafe { event.as_ref() };
+
+        match ev.r#type() {
+            NSEventType::OtherMouseUp => {
+                if let Some(direction) = direction_for_button(ev.buttonNumber()) {
+                    // Emit to the main window explicitly instead of
+                    // broadcasting (`emit`) so navigation stays scoped if
+                    // multi-window ever lands. "main" is the default label
+                    // for the single configured window (see deep_link.rs).
+                    let _ = app.emit_to("main", "mouse-nav", direction);
+                    // Swallow the release: nothing downstream should also act
+                    // on it. The matching press deliberately passes through:
+                    // WKWebView never delivers X1/X2 to the page, so the
+                    // unmatched down is inert, and swallowing presses risks
+                    // interfering with AppKit behaviors keyed off mouse-down.
+                    return std::ptr::null_mut();
+                }
+            }
+            NSEventType::Swipe => {
+                if let Some(direction) = direction_for_swipe(ev.deltaX()) {
+                    let _ = app.emit_to("main", "mouse-nav", direction);
+                }
+                // Pass swipes through: nothing else navigates on them, and
+                // swallowing mid-gesture events could confuse AppKit's
+                // gesture tracking.
+            }
+            _ => {}
+        }
+
+        event.as_ptr()
+    });
+
+    // SAFETY: the block returns either null or the pointer it was given, both
+    // valid per the monitor contract. The returned monitor token is
+    // deliberately leaked: the monitor must live for the whole app lifetime.
+    let monitor = unsafe {
+        NSEvent::addLocalMonitorForEventsMatchingMask_handler(
+            NSEventMask::OtherMouseUp | NSEventMask::Swipe,
+            &block,
+        )
+    };
+
+    if let Some(monitor) = monitor {
+        std::mem::forget(monitor);
+    } else {
+        eprintln!("buzz-desktop: mouse-nav: failed to install NSEvent monitor");
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn button_3_is_back() {
+        assert_eq!(direction_for_button(3), Some("back"));
+    }
+
+    #[test]
+    fn button_4_is_forward() {
+        assert_eq!(direction_for_button(4), Some("forward"));
+    }
+
+    #[test]
+    fn other_buttons_do_not_navigate() {
+        for button in [0, 1, 2, 5, -1] {
+            assert_eq!(direction_for_button(button), None);
+        }
+    }
+
+    #[test]
+    fn positive_swipe_delta_is_back() {
+        assert_eq!(direction_for_swipe(1.0), Some("back"));
+        assert_eq!(direction_for_swipe(0.5), Some("back"));
+    }
+
+    #[test]
+    fn negative_swipe_delta_is_forward() {
+        assert_eq!(direction_for_swipe(-1.0), Some("forward"));
+        assert_eq!(direction_for_swipe(-0.5), Some("forward"));
+    }
+
+    #[test]
+    fn zero_delta_swipe_begin_event_is_ignored() {
+        assert_eq!(direction_for_swipe(0.0), None);
+    }
+}
diff --git a/desktop/src-tauri/src/tray_menu.rs b/desktop/src-tauri/src/tray_menu.rs
index d733cd1f13..6dcef0ecf7 100644
--- a/desktop/src-tauri/src/tray_menu.rs
+++ b/desktop/src-tauri/src/tray_menu.rs
@@ -3,6 +3,11 @@
 //! The webview owns the live agent-turn state. It sends the small display
 //! projection here so the native menu can remain useful while Buzz is hidden.
 
+// Mouse back/forward (X1/X2 buttons and swipe) is also macOS-only native I/O;
+// group it here so both platform-layer init paths share one call site in lib.rs.
+#[path = "mouse_nav.rs"]
+pub(crate) mod mouse_nav;
+
 use std::{
     sync::{Mutex, OnceLock},
     time::{Duration, Instant},
@@ -488,6 +493,7 @@ pub fn init<R: Runtime>(app: &AppHandle<R>) -> tauri::Result<()> {
     if let Err(error) = apply_activity_presentation(&tray, activities, recent_activities) {
         eprintln!("buzz-desktop: failed to apply tray menu presentation: {error}");
     }
+    mouse_nav::init(app);
     Ok(())
 }
 
diff --git a/desktop/src-tauri/tauri.conf.json b/desktop/src-tauri/tauri.conf.json
index 1ff8bd20ef..4bda55fd09 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.3",
+  "version": "0.5.4",
   "identifier": "xyz.block.buzz.app",
   "build": {
     "beforeDevCommand": {
@@ -55,6 +55,7 @@
     "externalBin": [
       "binaries/buzz-acp",
       "binaries/buzz-agent",
+      "binaries/buzz-backend-kubernetes",
       "binaries/buzz-dev-mcp",
       "binaries/git-credential-nostr",
       "binaries/buzz"
diff --git a/desktop/src-tauri/tauri.windows.conf.json b/desktop/src-tauri/tauri.windows.conf.json
new file mode 100644
index 0000000000..abf09b5bfd
--- /dev/null
+++ b/desktop/src-tauri/tauri.windows.conf.json
@@ -0,0 +1,11 @@
+{
+  "bundle": {
+    "externalBin": [
+      "binaries/buzz-acp",
+      "binaries/buzz-agent",
+      "binaries/buzz-dev-mcp",
+      "binaries/git-credential-nostr",
+      "binaries/buzz"
+    ]
+  }
+}
diff --git a/desktop/src/app/AppShell.helpers.test.mjs b/desktop/src/app/AppShell.helpers.test.mjs
index 73505d1798..fa06232923 100644
--- a/desktop/src/app/AppShell.helpers.test.mjs
+++ b/desktop/src/app/AppShell.helpers.test.mjs
@@ -1,7 +1,10 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import { shouldBounceForChannelNotification } from "./AppShell.helpers.ts";
+import {
+  markAllReadSources,
+  shouldBounceForChannelNotification,
+} from "./AppShell.helpers.ts";
 
 test("shouldBounceForChannelNotification_allowsTopLevelChannelMessages", () => {
   assert.equal(shouldBounceForChannelNotification([["h", "channel"]]), true);
@@ -27,3 +30,43 @@ test("shouldBounceForChannelNotification_allowsBroadcastReplies", () => {
     true,
   );
 });
+
+test("markAllReadSources clears Inbox overrides and active thread activity", () => {
+  const calls = [];
+
+  markAllReadSources({
+    activeChannelId: "active-channel",
+    channelActivityItems: [
+      { channelId: "another-channel", createdAt: 100 },
+      { channelId: "active-channel", createdAt: 200 },
+      { channelId: "active-channel", createdAt: 300 },
+    ],
+    unreadFeedItemIds: new Set(["first-inbox-item", "second-inbox-item"]),
+    undoUnreadFeedItem: (itemId) => calls.push(`inbox:${itemId}`),
+    markAllChannelReadMarkers: () => calls.push("channels"),
+    markActiveChannelRead: (channelId, createdAt) =>
+      calls.push(`active:${channelId}:${createdAt}`),
+  });
+
+  assert.deepEqual(calls, [
+    "inbox:first-inbox-item",
+    "inbox:second-inbox-item",
+    "channels",
+    "active:active-channel:300",
+  ]);
+});
+
+test("markAllReadSources skips the active marker without projected activity", () => {
+  const calls = [];
+
+  markAllReadSources({
+    activeChannelId: "active-channel",
+    channelActivityItems: [],
+    unreadFeedItemIds: new Set(),
+    undoUnreadFeedItem: () => calls.push("inbox"),
+    markAllChannelReadMarkers: () => calls.push("channels"),
+    markActiveChannelRead: () => calls.push("active"),
+  });
+
+  assert.deepEqual(calls, ["channels"]);
+});
diff --git a/desktop/src/app/AppShell.helpers.ts b/desktop/src/app/AppShell.helpers.ts
index b0ce894931..dd6b9195e8 100644
--- a/desktop/src/app/AppShell.helpers.ts
+++ b/desktop/src/app/AppShell.helpers.ts
@@ -86,6 +86,41 @@ export function shouldBounceForChannelNotification(tags: string[][]): boolean {
   return !isThreadReply(tags);
 }
 
+export function markAllReadSources({
+  activeChannelId,
+  channelActivityItems,
+  markAllChannelReadMarkers,
+  markActiveChannelRead,
+  undoUnreadFeedItem,
+  unreadFeedItemIds,
+}: {
+  activeChannelId: string | null;
+  channelActivityItems: ReadonlyArray<{
+    channelId: string | null;
+    createdAt: number;
+  }>;
+  markAllChannelReadMarkers: () => void;
+  markActiveChannelRead: (channelId: string, createdAt: number) => void;
+  undoUnreadFeedItem: (itemId: string) => void;
+  unreadFeedItemIds: ReadonlySet<string>;
+}) {
+  for (const itemId of unreadFeedItemIds) {
+    undoUnreadFeedItem(itemId);
+  }
+  markAllChannelReadMarkers();
+
+  if (!activeChannelId) return;
+
+  let latestActivityAt: number | null = null;
+  for (const item of channelActivityItems) {
+    if (item.channelId !== activeChannelId) continue;
+    latestActivityAt = Math.max(latestActivityAt ?? 0, item.createdAt);
+  }
+  if (latestActivityAt !== null) {
+    markActiveChannelRead(activeChannelId, latestActivityAt);
+  }
+}
+
 export function toSearchHit(
   target: DesktopNotificationTarget,
 ): SearchHit | null {
diff --git a/desktop/src/app/AppShell.tsx b/desktop/src/app/AppShell.tsx
index 4eb0a42bbe..46e06b2f9f 100644
--- a/desktop/src/app/AppShell.tsx
+++ b/desktop/src/app/AppShell.tsx
@@ -1,7 +1,7 @@
 import * as React from "react";
 import { useQueryClient } from "@tanstack/react-query";
 import { Outlet, useLocation } from "@tanstack/react-router";
-import { deriveShellRoute } from "@/app/AppShell.helpers";
+import { deriveShellRoute, markAllReadSources } from "@/app/AppShell.helpers";
 import { AppShellProvider } from "@/app/AppShellContext";
 import * as BuzzTheme from "@/app/BuzzThemeSurfaces";
 import { AppShellOverlays } from "@/app/AppShellOverlays";
@@ -15,7 +15,7 @@ import { useMarkAsReadShortcuts } from "@/app/useMarkAsReadShortcuts";
 import { useSettingsShortcuts } from "@/app/useSettingsShortcuts";
 import { useAppShellDesktopNotifications } from "@/app/useAppShellDesktopNotifications";
 import { useAppShellLifecycleEffects } from "@/app/useAppShellLifecycleEffects";
-import { useThreadActivityFeedItems } from "@/app/useThreadActivityFeedItems";
+import { useChannelActivityProjection } from "@/app/useChannelActivityProjection";
 import { useTauriWindowDrag } from "@/app/useTauriWindowDrag";
 import { useWebviewZoomShortcuts } from "@/app/useWebviewZoomShortcuts";
 import {
@@ -26,7 +26,6 @@ import {
   useOpenDmMutation,
 } from "@/features/channels/hooks";
 import { useUnreadChannels } from "@/features/channels/useUnreadChannels";
-import { msgContextKey } from "@/features/channels/readState/readStateFormat";
 import { useMembershipNotifications } from "@/features/channels/useMembershipNotifications";
 import { useFeedItemState } from "@/features/home/useFeedItemState";
 import { useThreadFollows } from "@/features/messages/lib/useThreadFollows";
@@ -324,10 +323,12 @@ export function AppShell() {
   } = useThreadFollows(identityQuery.data?.pubkey);
 
   const {
-    markAllChannelsRead,
+    markAllChannelsRead: markAllChannelReadMarkers,
     markChannelRead,
     markChannelUnread,
+    clearChannelUnreadSource,
     unreadChannelIds,
+    topLevelUnreadChannelIds,
     unreadChannelCounts,
     highPriorityUnreadChannelIds,
     unreadChannelNotificationCount,
@@ -338,6 +339,7 @@ export function AppShell() {
     participatedRootIds,
     authoredRootIds,
     mentionedRootIds,
+    recordThreadInteraction,
     threadActivityItems,
     mutedRootIds,
     muteThread,
@@ -356,55 +358,45 @@ export function AppShell() {
     followedRootIds,
   });
 
-  const getThreadReadAt = React.useCallback(
-    (rootId: string, channelId?: string | null) => {
-      const threadReadAt = getOwnReadAt(`thread:${rootId}`);
-      if (!channelId) {
-        return threadReadAt;
-      }
-
-      const channelReadAt = getChannelReadAt(channelId);
-      if (threadReadAt === null) {
-        return channelReadAt;
-      }
-      if (channelReadAt === null) {
-        return threadReadAt;
-      }
-      return Math.max(threadReadAt, channelReadAt);
-    },
-    [getChannelReadAt, getOwnReadAt],
-  );
-
-  const markThreadRead = React.useCallback(
-    (rootId: string, timestamp: number) => {
-      markChannelRead(
-        `thread:${rootId}`,
-        new Date(timestamp * 1_000).toISOString(),
-      );
-    },
-    [markChannelRead],
-  );
-
-  // Per-message read frontier (LP4 v3): effective(msg:<id>) folds through the
-  // channel, so a channel-read clears messages older than the top-level frontier.
-  const getMessageReadAt = React.useCallback(
-    (messageId: string) => getChannelReadAt(msgContextKey(messageId)),
-    [getChannelReadAt],
-  );
-  const markMessageRead = React.useCallback(
-    (messageId: string, timestamp: number) =>
-      markChannelRead(
-        msgContextKey(messageId),
-        new Date(timestamp * 1_000).toISOString(),
-      ),
-    [markChannelRead],
-  );
-  const threadActivityFeedItems = useThreadActivityFeedItems(
+  const {
+    getThreadReadAt,
+    markThreadRead,
+    getMessageReadAt,
+    getChannelActivityItemReadAt,
+    markMessageRead,
+    threadActivityFeedItems,
+    locallyUnreadFeedItems,
+    unreadThreadFeedItems,
+    unreadThreadChannelIds,
+  } = useChannelActivityProjection({
+    channels,
+    feed: homeFeedQuery.data?.feed,
+    unreadFeedItemIds: feedItemState.unreadSet,
+    getChannelReadAt,
+    getOwnReadAt,
+    markChannelRead,
+    readStateVersion,
     threadActivityItems,
     mutedRootIds,
-    channels,
-  );
-
+  });
+  const markAllChannelsRead = React.useCallback(() => {
+    markAllReadSources({
+      activeChannelId: activeChannel?.id ?? null,
+      channelActivityItems: unreadThreadFeedItems,
+      markAllChannelReadMarkers,
+      markActiveChannelRead: (channelId, createdAt) =>
+        markChannelRead(channelId, new Date(createdAt * 1_000).toISOString()),
+      undoUnreadFeedItem: feedItemState.undoUnread,
+      unreadFeedItemIds: feedItemState.unreadSet,
+    });
+  }, [
+    activeChannel?.id,
+    feedItemState.undoUnread,
+    feedItemState.unreadSet,
+    markAllChannelReadMarkers,
+    markChannelRead,
+    unreadThreadFeedItems,
+  ]);
   // Badge count consumes the shared NIP-RS read-state from useUnreadChannels.
   const { homeBadgeCount, homeBadgeCountExcludingHighPriority } =
     useHomeFeedNotificationState(
@@ -709,6 +701,7 @@ export function AppShell() {
             markAllChannelsRead,
             markChannelRead,
             markChannelUnread,
+            clearChannelUnreadSource,
             openBrowseChannels: handleOpenBrowseChannels,
             openCreateChannel: handleOpenCreateChannel,
             openChannelManagement: (channelId?: string) => {
@@ -721,6 +714,7 @@ export function AppShell() {
             getThreadReadAt,
             markThreadRead,
             getMessageReadAt,
+            getChannelActivityItemReadAt,
             markMessageRead,
             readStateVersion,
             setContextParentResolver,
@@ -728,9 +722,15 @@ export function AppShell() {
             unfollowThread: handleUnfollowThread,
             isFollowingThread,
             isNotifiedForThread,
+            recordThreadInteraction,
             isThreadMuted: (rootId) => mutedRootIds.has(rootId),
             threadActivityItems,
             threadActivityFeedItems,
+            locallyUnreadFeedItems,
+            unreadThreadFeedItems,
+            unreadThreadChannelIds,
+            topLevelUnreadChannelIds,
+            hasSidebarUnreadProjections: true,
             feedItemState,
             onOpenSettings: handleOpenSettings,
           }}
diff --git a/desktop/src/app/AppShellContext.tsx b/desktop/src/app/AppShellContext.tsx
index 4a64de0cb2..b909436178 100644
--- a/desktop/src/app/AppShellContext.tsx
+++ b/desktop/src/app/AppShellContext.tsx
@@ -1,4 +1,5 @@
 import * as React from "react";
+import type { ForcedUnreadSource } from "@/features/channels/forcedUnreadStore";
 import type { ContextParentResolver } from "@/features/channels/readState/readStateManager";
 import type { ThreadActivityItem } from "@/features/channels/useUnreadChannels";
 import type { FeedItemState } from "@/features/home/useFeedItemState";
@@ -12,9 +13,16 @@ type AppShellContextValue = {
   markChannelRead: (
     channelId: string,
     readAt: string | null | undefined,
-    options?: { topLevelOnly?: boolean },
+    options?: {
+      preserveForcedUnread?: boolean;
+      topLevelOnly?: boolean;
+    },
+  ) => void;
+  markChannelUnread: (channelId: string, source?: ForcedUnreadSource) => void;
+  clearChannelUnreadSource: (
+    channelId: string,
+    source: ForcedUnreadSource,
   ) => void;
-  markChannelUnread: (channelId: string) => void;
   openBrowseChannels: () => void;
   openCreateChannel: () => void;
   openChannelManagement: (channelId?: string) => void;
@@ -31,6 +39,11 @@ type AppShellContextValue = {
   // read. Uses `msg:<id>` context keys folded through the active channel by the
   // parent resolver (LP4 v3 per-message badge model).
   getMessageReadAt: (messageId: string) => number | null;
+  // Read frontier for a channel-activity item, scoped to that item's own
+  // message and channel rather than the currently mounted channel resolver.
+  getChannelActivityItemReadAt: (
+    item: Pick<FeedItem, "channelId" | "id">,
+  ) => number | null;
   // Advance a single message's read marker to the given unix-seconds timestamp.
   markMessageRead: (messageId: string, timestamp: number) => void;
   // Bump-counter that invalidates whenever the read marker changes. Include
@@ -43,9 +56,25 @@ type AppShellContextValue = {
   unfollowThread: (rootId: string) => void;
   isFollowingThread: (rootId: string) => boolean;
   isNotifiedForThread: (rootId: string) => boolean;
+  recordThreadInteraction: (rootId: string) => void;
   isThreadMuted: (rootId: string) => boolean;
   threadActivityItems: ThreadActivityItem[];
   threadActivityFeedItems: FeedItem[];
+  // Home-feed items explicitly reopened from Inbox. Kept separate from live
+  // thread activity so older rows can be projected into channel hover cards
+  // without duplicating the Home feed itself.
+  locallyUnreadFeedItems: FeedItem[];
+  // Thread rows that remain unread until their own message/thread marker is
+  // advanced. Unlike the broad channel unread set, this includes the active
+  // channel so simply landing in it does not hide the wayfinding signal.
+  unreadThreadFeedItems: FeedItem[];
+  unreadThreadChannelIds: ReadonlySet<string>;
+  // Ordinary unread channel-level activity. Sidebar rows use this for text
+  // emphasis only; thread activity owns the dot.
+  topLevelUnreadChannelIds: ReadonlySet<string>;
+  // Lets isolated component tests retain the legacy hasUnread fallback while
+  // the mounted shell uses the split projections above.
+  hasSidebarUnreadProjections: boolean;
   feedItemState: FeedItemState;
   // Open the Settings panel at the given section. Available on all surfaces
   // that render under AppShell (channel, home, projects, pulse, agents).
@@ -57,6 +86,7 @@ const AppShellContext = React.createContext<AppShellContextValue>({
   markAllChannelsRead: () => {},
   markChannelRead: () => {},
   markChannelUnread: () => {},
+  clearChannelUnreadSource: () => {},
   openBrowseChannels: () => {},
   openCreateChannel: () => {},
   openChannelManagement: () => {},
@@ -64,6 +94,7 @@ const AppShellContext = React.createContext<AppShellContextValue>({
   getThreadReadAt: () => null,
   markThreadRead: () => {},
   getMessageReadAt: () => null,
+  getChannelActivityItemReadAt: () => null,
   markMessageRead: () => {},
   readStateVersion: 0,
   setContextParentResolver: () => {},
@@ -71,9 +102,15 @@ const AppShellContext = React.createContext<AppShellContextValue>({
   unfollowThread: () => {},
   isFollowingThread: () => false,
   isNotifiedForThread: () => false,
+  recordThreadInteraction: () => {},
   isThreadMuted: () => false,
   threadActivityItems: [],
   threadActivityFeedItems: [],
+  locallyUnreadFeedItems: [],
+  unreadThreadFeedItems: [],
+  unreadThreadChannelIds: EMPTY_SET,
+  topLevelUnreadChannelIds: EMPTY_SET,
+  hasSidebarUnreadProjections: false,
   feedItemState: {
     doneSet: EMPTY_SET,
     markDone: () => {},
diff --git a/desktop/src/app/navigation/backForwardChords.test.mjs b/desktop/src/app/navigation/backForwardChords.test.mjs
new file mode 100644
index 0000000000..cb60203d04
--- /dev/null
+++ b/desktop/src/app/navigation/backForwardChords.test.mjs
@@ -0,0 +1,139 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { matchBackForwardChord } from "./backForwardChords.ts";
+
+function chord(overrides = {}) {
+  return {
+    altKey: false,
+    code: "",
+    ctrlKey: false,
+    key: "",
+    metaKey: false,
+    shiftKey: false,
+    ...overrides,
+  };
+}
+
+// ── macOS: ⌘[ / ⌘] ───────────────────────────────────────────────────────────
+
+test("mac: ⌘[ matches back", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ key: "[", metaKey: true }), true),
+    "back",
+  );
+});
+
+test("mac: ⌘] matches forward", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ key: "]", metaKey: true }), true),
+    "forward",
+  );
+});
+
+test("mac: matches by code for non-US layouts", () => {
+  assert.equal(
+    matchBackForwardChord(
+      chord({ code: "BracketLeft", key: "Dead", metaKey: true }),
+      true,
+    ),
+    "back",
+  );
+  assert.equal(
+    matchBackForwardChord(
+      chord({ code: "BracketRight", key: "Dead", metaKey: true }),
+      true,
+    ),
+    "forward",
+  );
+});
+
+test("mac: requires meta", () => {
+  assert.equal(matchBackForwardChord(chord({ key: "[" }), true), null);
+});
+
+test("mac: rejects extra modifiers", () => {
+  for (const extra of [
+    { altKey: true },
+    { ctrlKey: true },
+    { shiftKey: true },
+  ]) {
+    assert.equal(
+      matchBackForwardChord(chord({ key: "[", metaKey: true, ...extra }), true),
+      null,
+    );
+  }
+});
+
+test("mac: Alt+arrows do not match (that is the win/linux chord)", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ altKey: true, key: "ArrowLeft" }), true),
+    null,
+  );
+});
+
+test("mac: ⌘←/⌘→ never match — they are line start/end in text editing", () => {
+  // Deliberately unbound: editable targets must keep receiving ⌘←/⌘→ so
+  // line-start/line-end editing still works. Only ⌘[ / ⌘] navigate.
+  assert.equal(
+    matchBackForwardChord(chord({ key: "ArrowLeft", metaKey: true }), true),
+    null,
+  );
+  assert.equal(
+    matchBackForwardChord(chord({ key: "ArrowRight", metaKey: true }), true),
+    null,
+  );
+});
+
+// ── Windows/Linux: Alt+← / Alt+→ ─────────────────────────────────────────────
+
+test("win/linux: Alt+ArrowLeft matches back", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ altKey: true, key: "ArrowLeft" }), false),
+    "back",
+  );
+});
+
+test("win/linux: Alt+ArrowRight matches forward", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ altKey: true, key: "ArrowRight" }), false),
+    "forward",
+  );
+});
+
+test("win/linux: requires alt", () => {
+  assert.equal(matchBackForwardChord(chord({ key: "ArrowLeft" }), false), null);
+});
+
+test("win/linux: rejects extra modifiers", () => {
+  for (const extra of [
+    { ctrlKey: true },
+    { metaKey: true },
+    { shiftKey: true },
+  ]) {
+    assert.equal(
+      matchBackForwardChord(
+        chord({ altKey: true, key: "ArrowLeft", ...extra }),
+        false,
+      ),
+      null,
+    );
+  }
+});
+
+test("win/linux: ⌘[ does not match (that is the mac chord)", () => {
+  assert.equal(
+    matchBackForwardChord(chord({ key: "[", metaKey: true }), false),
+    null,
+  );
+});
+
+// ── Non-chord keys never match ────────────────────────────────────────────────
+
+test("plain bracket / arrow keys without the platform modifier never match", () => {
+  for (const isMac of [true, false]) {
+    for (const key of ["[", "]", "ArrowLeft", "ArrowRight", "a", "Enter"]) {
+      assert.equal(matchBackForwardChord(chord({ key }), isMac), null);
+    }
+  }
+});
diff --git a/desktop/src/app/navigation/backForwardChords.ts b/desktop/src/app/navigation/backForwardChords.ts
new file mode 100644
index 0000000000..ac81f52ea7
--- /dev/null
+++ b/desktop/src/app/navigation/backForwardChords.ts
@@ -0,0 +1,51 @@
+/**
+ * Global back/forward navigation chords.
+ *
+ * macOS: ⌘[ / ⌘] — matching Safari, Chrome, Finder, and Slack.
+ * Windows/Linux: Alt+← / Alt+→ — matching browsers and Slack.
+ *
+ * Kept pure (no DOM access) so chord matching can be unit tested; the
+ * window listener wiring lives in `useBackForwardControls`.
+ */
+
+export type BackForwardDirection = "back" | "forward";
+
+export type BackForwardChordEvent = Pick<
+  KeyboardEvent,
+  "altKey" | "code" | "ctrlKey" | "key" | "metaKey" | "shiftKey"
+>;
+
+export function matchBackForwardChord(
+  event: BackForwardChordEvent,
+  isMac: boolean,
+): BackForwardDirection | null {
+  if (isMac) {
+    if (!event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) {
+      return null;
+    }
+
+    if (event.key === "[" || event.code === "BracketLeft") {
+      return "back";
+    }
+
+    if (event.key === "]" || event.code === "BracketRight") {
+      return "forward";
+    }
+
+    return null;
+  }
+
+  if (!event.altKey || event.metaKey || event.ctrlKey || event.shiftKey) {
+    return null;
+  }
+
+  if (event.key === "ArrowLeft") {
+    return "back";
+  }
+
+  if (event.key === "ArrowRight") {
+    return "forward";
+  }
+
+  return null;
+}
diff --git a/desktop/src/app/navigation/useBackForwardControls.ts b/desktop/src/app/navigation/useBackForwardControls.ts
index 7f7d84f6d7..e5513247d5 100644
--- a/desktop/src/app/navigation/useBackForwardControls.ts
+++ b/desktop/src/app/navigation/useBackForwardControls.ts
@@ -4,7 +4,10 @@ import {
   useRouter,
   useRouterState,
 } from "@tanstack/react-router";
+import { isTauri } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
 
+import { matchBackForwardChord } from "@/app/navigation/backForwardChords";
 import { isMacPlatform } from "@/shared/lib/platform";
 import { trimMapToSize } from "@/shared/lib/trimMapToSize";
 
@@ -14,19 +17,6 @@ type RouterHistoryState = {
   key?: string;
 };
 
-function isEditableTarget(target: EventTarget | null): boolean {
-  if (!(target instanceof HTMLElement)) {
-    return false;
-  }
-
-  return (
-    target.isContentEditable ||
-    target.closest(
-      'input, textarea, select, [contenteditable=""], [contenteditable="true"]',
-    ) !== null
-  );
-}
-
 export function useBackForwardControls() {
   const router = useRouter();
   const canGoBack = useCanGoBack();
@@ -81,46 +71,38 @@ export function useBackForwardControls() {
   }, [canGoForward, router.history]);
 
   const handleKeyDown = React.useEffectEvent((event: KeyboardEvent) => {
-    if (isEditableTarget(event.target)) {
-      return;
-    }
+    // Note: the chords deliberately fire even when focus is inside an
+    // editable element. The composer autofocuses on every channel switch
+    // (`useComposerAutofocus`), so in steady state focus almost always
+    // lives in a contenteditable — an editable-target guard here made the
+    // shortcuts effectively dead (#3775). Safe because neither ⌘[ / ⌘]
+    // (macOS) nor Alt+←/→ (Windows/Linux) carry text-editing semantics,
+    // and the TipTap editor binds no conflicting shortcuts.
+    const direction = matchBackForwardChord(event, isMacPlatform());
 
-    const isMac = isMacPlatform();
-    const isBackShortcut = isMac
-      ? event.metaKey &&
-        !event.ctrlKey &&
-        !event.altKey &&
-        !event.shiftKey &&
-        (event.key === "[" || event.code === "BracketLeft")
-      : event.altKey &&
-        !event.metaKey &&
-        !event.ctrlKey &&
-        !event.shiftKey &&
-        event.key === "ArrowLeft";
-    const isForwardShortcut = isMac
-      ? event.metaKey &&
-        !event.ctrlKey &&
-        !event.altKey &&
-        !event.shiftKey &&
-        (event.key === "]" || event.code === "BracketRight")
-      : event.altKey &&
-        !event.metaKey &&
-        !event.ctrlKey &&
-        !event.shiftKey &&
-        event.key === "ArrowRight";
-
-    if (isBackShortcut) {
+    if (direction === "back") {
       event.preventDefault();
       goBack();
       return;
     }
 
-    if (isForwardShortcut) {
+    if (direction === "forward") {
       event.preventDefault();
       goForward();
     }
   });
 
+  const handleMouseNav = React.useEffectEvent((direction: string) => {
+    if (direction === "back") {
+      goBack();
+      return;
+    }
+
+    if (direction === "forward") {
+      goForward();
+    }
+  });
+
   React.useEffect(() => {
     window.addEventListener("keydown", handleKeyDown);
     return () => {
@@ -128,6 +110,23 @@ export function useBackForwardControls() {
     };
   }, []);
 
+  // macOS: WKWebView never delivers X1/X2 button events or horizontal
+  // swipe gestures to the DOM, so the native layer catches them
+  // (`mouse_nav.rs`) and forwards them as a Tauri event.
+  React.useEffect(() => {
+    if (!isTauri()) {
+      return;
+    }
+
+    const unlistenPromise = listen<string>("mouse-nav", (event) => {
+      handleMouseNav(event.payload);
+    });
+
+    return () => {
+      void unlistenPromise.then((unlisten) => unlisten());
+    };
+  }, []);
+
   return {
     canGoBack,
     canGoForward,
diff --git a/desktop/src/app/useChannelActivityProjection.test.mjs b/desktop/src/app/useChannelActivityProjection.test.mjs
new file mode 100644
index 0000000000..6b54f32246
--- /dev/null
+++ b/desktop/src/app/useChannelActivityProjection.test.mjs
@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { resolveChannelActivityFeedItemReadAt } from "./useChannelActivityProjection.ts";
+
+test("channel activity read state folds the item's own message and channel markers", () => {
+  const markers = new Map([
+    ["msg:reply-general", 100],
+    ["general", 200],
+    ["random", 500],
+  ]);
+
+  assert.equal(
+    resolveChannelActivityFeedItemReadAt(
+      { id: "reply-general", channelId: "general" },
+      (contextId) => markers.get(contextId) ?? null,
+    ),
+    200,
+  );
+});
+
+test("channel activity read state honors a channel marker without a message marker", () => {
+  assert.equal(
+    resolveChannelActivityFeedItemReadAt(
+      { id: "reply-general", channelId: "general" },
+      (contextId) => (contextId === "general" ? 300 : null),
+    ),
+    300,
+  );
+});
diff --git a/desktop/src/app/useChannelActivityProjection.ts b/desktop/src/app/useChannelActivityProjection.ts
new file mode 100644
index 0000000000..b1961318ce
--- /dev/null
+++ b/desktop/src/app/useChannelActivityProjection.ts
@@ -0,0 +1,145 @@
+import * as React from "react";
+
+import { useThreadActivityFeedItems } from "@/app/useThreadActivityFeedItems";
+import {
+  maxReadAt,
+  msgContextKey,
+} from "@/features/channels/readState/readStateFormat";
+import type { ThreadActivityItem } from "@/features/channels/useUnreadChannels";
+import { isThreadReply } from "@/features/messages/lib/threading";
+import type { Channel, FeedItem, HomeFeed } from "@/shared/api/types";
+
+type ReadTimestamp = (contextKey: string) => number | null;
+type MarkChannelRead = (
+  contextKey: string,
+  readAt: string | null | undefined,
+  options?: { topLevelOnly?: boolean },
+) => void;
+
+type UseChannelActivityProjectionOptions = {
+  channels: Channel[];
+  feed: HomeFeed | undefined;
+  unreadFeedItemIds: ReadonlySet<string>;
+  getChannelReadAt: ReadTimestamp;
+  getOwnReadAt: ReadTimestamp;
+  markChannelRead: MarkChannelRead;
+  readStateVersion: number;
+  threadActivityItems: ThreadActivityItem[];
+  mutedRootIds: ReadonlySet<string>;
+};
+
+export function resolveChannelActivityFeedItemReadAt(
+  item: Pick<FeedItem, "channelId" | "id">,
+  getOwnReadAt: ReadTimestamp,
+): number | null {
+  return maxReadAt(
+    getOwnReadAt(msgContextKey(item.id)),
+    item.channelId ? getOwnReadAt(item.channelId) : null,
+  );
+}
+
+export function useChannelActivityProjection({
+  channels,
+  feed,
+  unreadFeedItemIds,
+  getChannelReadAt,
+  getOwnReadAt,
+  markChannelRead,
+  readStateVersion,
+  threadActivityItems,
+  mutedRootIds,
+}: UseChannelActivityProjectionOptions) {
+  const getThreadReadAt = React.useCallback(
+    (rootId: string, channelId?: string | null) => {
+      const threadReadAt = getOwnReadAt(`thread:${rootId}`);
+      if (!channelId) return threadReadAt;
+
+      const channelReadAt = getChannelReadAt(channelId);
+      if (threadReadAt === null) return channelReadAt;
+      if (channelReadAt === null) return threadReadAt;
+      return Math.max(threadReadAt, channelReadAt);
+    },
+    [getChannelReadAt, getOwnReadAt],
+  );
+  const markThreadRead = React.useCallback(
+    (rootId: string, timestamp: number) =>
+      markChannelRead(
+        `thread:${rootId}`,
+        new Date(timestamp * 1_000).toISOString(),
+      ),
+    [markChannelRead],
+  );
+  const getMessageReadAt = React.useCallback(
+    (messageId: string) => getChannelReadAt(msgContextKey(messageId)),
+    [getChannelReadAt],
+  );
+  const getChannelActivityItemReadAt = React.useCallback(
+    (item: Pick<FeedItem, "channelId" | "id">) =>
+      resolveChannelActivityFeedItemReadAt(item, getOwnReadAt),
+    [getOwnReadAt],
+  );
+  const markMessageRead = React.useCallback(
+    (messageId: string, timestamp: number) =>
+      markChannelRead(
+        msgContextKey(messageId),
+        new Date(timestamp * 1_000).toISOString(),
+      ),
+    [markChannelRead],
+  );
+  const threadActivityFeedItems = useThreadActivityFeedItems(
+    threadActivityItems,
+    mutedRootIds,
+    channels,
+  );
+  const locallyUnreadFeedItems = React.useMemo(() => {
+    if (!feed || unreadFeedItemIds.size === 0) return [];
+    return [
+      ...feed.mentions,
+      ...feed.needsAction,
+      ...feed.activity,
+      ...feed.agentActivity,
+    ].filter((item) => unreadFeedItemIds.has(item.id));
+  }, [feed, unreadFeedItemIds]);
+  const unreadThreadFeedItems = React.useMemo(() => {
+    void readStateVersion;
+    const candidatesById = new Map<string, FeedItem>(
+      threadActivityFeedItems.map((item) => [item.id, item]),
+    );
+    for (const item of locallyUnreadFeedItems)
+      candidatesById.set(item.id, item);
+
+    return [...candidatesById.values()].filter(
+      (item) =>
+        isThreadReply(item.tags) &&
+        (unreadFeedItemIds.has(item.id) ||
+          item.createdAt > (getChannelActivityItemReadAt(item) ?? 0)),
+    );
+  }, [
+    getChannelActivityItemReadAt,
+    locallyUnreadFeedItems,
+    readStateVersion,
+    threadActivityFeedItems,
+    unreadFeedItemIds,
+  ]);
+  const unreadThreadChannelIds = React.useMemo(
+    () =>
+      new Set(
+        unreadThreadFeedItems.flatMap((item) =>
+          item.channelId ? [item.channelId] : [],
+        ),
+      ) as ReadonlySet<string>,
+    [unreadThreadFeedItems],
+  );
+
+  return {
+    getThreadReadAt,
+    markThreadRead,
+    getMessageReadAt,
+    getChannelActivityItemReadAt,
+    markMessageRead,
+    threadActivityFeedItems,
+    locallyUnreadFeedItems,
+    unreadThreadFeedItems,
+    unreadThreadChannelIds,
+  };
+}
diff --git a/desktop/src/features/agents/cardMintStore.test.mjs b/desktop/src/features/agents/cardMintStore.test.mjs
new file mode 100644
index 0000000000..6c2f4522ab
--- /dev/null
+++ b/desktop/src/features/agents/cardMintStore.test.mjs
@@ -0,0 +1,219 @@
+import assert from "node:assert/strict";
+import { beforeEach, describe, it } from "node:test";
+
+// cardMintStore drives the non-blocking mint flow: the dialog dispatches a
+// job and closes; the composer chip, completion toast, and viewer all read
+// this store. These tests exercise the job lifecycle with an injected mintFn
+// (never the real Tauri command).
+//
+// The store imports sonner (toast); calling toast outside a mounted <Toaster>
+// only queues, so no DOM is required.
+
+import {
+  dismissCardMintJob,
+  getCardGalleryOpen,
+  getCardMintJobs,
+  getCardViewerState,
+  closeCardViewer,
+  openCardViewer,
+  resetCardMintStore,
+  runCardMintJob,
+  setCardGalleryOpen,
+  subscribeCardMintStore,
+  viewMintedCardJob,
+} from "./cardMintStore.ts";
+
+const CARD = {
+  cardPngBase64: "aGVsbG8=",
+  fileName: "eva.agent.png",
+  designerNotes: "notes",
+  locked: false,
+  memoryLevel: "none",
+};
+
+const INPUT = { agentId: "agent-1", agentName: "Eva" };
+
+describe("cardMintStore", () => {
+  beforeEach(() => {
+    resetCardMintStore();
+  });
+
+  it("forwards the mint input — including memoryLevel — to mintFn", async () => {
+    const seen = [];
+    await runCardMintJob(
+      { ...INPUT, styleNotes: "stormy", lock: true, memoryLevel: "core" },
+      (...args) => {
+        seen.push(args);
+        return Promise.resolve({ ...CARD, memoryLevel: "core" });
+      },
+    );
+    assert.deepEqual(seen, [["agent-1", "stormy", true, "core"]]);
+
+    // Omitted memoryLevel stays undefined so Rust applies its "none" default.
+    await runCardMintJob(INPUT, (...args) => {
+      seen.push(args);
+      return Promise.resolve(CARD);
+    });
+    assert.deepEqual(seen[1], ["agent-1", undefined, undefined, undefined]);
+  });
+
+  it("tracks a successful mint through minting → done", async () => {
+    let resolveMint;
+    const pending = new Promise((resolve) => {
+      resolveMint = resolve;
+    });
+    const run = runCardMintJob(INPUT, () => pending);
+
+    let jobs = getCardMintJobs();
+    assert.equal(jobs.length, 1);
+    assert.equal(jobs[0].phase, "minting");
+    assert.equal(jobs[0].input.agentName, "Eva");
+    assert.equal(jobs[0].card, null);
+
+    resolveMint(CARD);
+    await run;
+
+    jobs = getCardMintJobs();
+    assert.equal(jobs.length, 1);
+    assert.equal(jobs[0].phase, "done");
+    assert.deepEqual(jobs[0].card, CARD);
+    assert.equal(jobs[0].error, null);
+  });
+
+  it("records the error message on a failed mint", async () => {
+    await runCardMintJob(INPUT, () => Promise.reject(new Error("boom")));
+    const jobs = getCardMintJobs();
+    assert.equal(jobs.length, 1);
+    assert.equal(jobs[0].phase, "error");
+    assert.equal(jobs[0].error, "boom");
+    assert.equal(jobs[0].card, null);
+  });
+
+  it("strips the NO_OPENAI_KEY wire prefix from mint errors", async () => {
+    await runCardMintJob(INPUT, () =>
+      Promise.reject(new Error("NO_OPENAI_KEY: No OPENAI_API_KEY found.")),
+    );
+    assert.equal(getCardMintJobs()[0].error, "No OPENAI_API_KEY found.");
+  });
+
+  it("replaces a 401 HTTP error with an actionable update-key message", async () => {
+    await runCardMintJob(INPUT, () =>
+      Promise.reject(
+        new Error(
+          "Card mint failed (HTTP 401 Unauthorized): Incorrect API key provided: sk-proj-***",
+        ),
+      ),
+    );
+    const { error } = getCardMintJobs()[0];
+    assert.ok(
+      error?.includes("invalid or expired"),
+      `expected 'invalid or expired' in: ${error}`,
+    );
+    assert.ok(
+      error?.includes("Update API key"),
+      `expected 'Update API key' in: ${error}`,
+    );
+  });
+
+  it("replaces an 'Incorrect API key' error without an HTTP status code", async () => {
+    await runCardMintJob(INPUT, () =>
+      Promise.reject(new Error("Incorrect API key provided: sk-proj-***")),
+    );
+    const { error } = getCardMintJobs()[0];
+    assert.ok(
+      error?.includes("invalid or expired"),
+      `expected 'invalid or expired' in: ${error}`,
+    );
+  });
+
+  it("does not apply the 401 branch to generic non-auth errors", async () => {
+    await runCardMintJob(INPUT, () =>
+      Promise.reject(new Error("Connection timeout")),
+    );
+    assert.equal(getCardMintJobs()[0].error, "Connection timeout");
+  });
+
+  it("does not rewrite avatar fetch 401 as an API key error", async () => {
+    // Avatar fetch failures have a different error prefix — rewriting them
+    // would send the user down a path that cannot fix the avatar failure.
+    const avatarError = "Avatar fetch failed: HTTP 401 Unauthorized";
+    await runCardMintJob(INPUT, () => Promise.reject(new Error(avatarError)));
+    assert.equal(
+      getCardMintJobs()[0].error,
+      avatarError,
+      "avatar 401 must pass through unchanged",
+    );
+  });
+
+  it("viewMintedCardJob moves a done job into the viewer and clears the chip", async () => {
+    await runCardMintJob(INPUT, () => Promise.resolve(CARD));
+    const jobId = getCardMintJobs()[0].jobId;
+
+    viewMintedCardJob(jobId);
+
+    assert.equal(getCardMintJobs().length, 0);
+    const viewer = getCardViewerState();
+    assert.ok(viewer);
+    assert.equal(viewer.agentName, "Eva");
+    assert.deepEqual(viewer.card, CARD);
+    // Fresh mints keep their input so the viewer can reroll.
+    assert.deepEqual(viewer.remint, INPUT);
+  });
+
+  it("viewMintedCardJob ignores jobs that are still minting", () => {
+    let resolveMint;
+    void runCardMintJob(
+      INPUT,
+      () => new Promise((resolve) => (resolveMint = resolve)),
+    );
+    const jobId = getCardMintJobs()[0].jobId;
+
+    viewMintedCardJob(jobId);
+
+    assert.equal(getCardMintJobs().length, 1);
+    assert.equal(getCardViewerState(), null);
+    resolveMint(CARD); // avoid a dangling promise
+  });
+
+  it("dismissCardMintJob removes only the named job", async () => {
+    await runCardMintJob(INPUT, () => Promise.reject(new Error("a")));
+    await runCardMintJob({ agentId: "agent-2", agentName: "Wren" }, () =>
+      Promise.reject(new Error("b")),
+    );
+    const [first, second] = getCardMintJobs();
+
+    dismissCardMintJob(first.jobId);
+
+    const jobs = getCardMintJobs();
+    assert.equal(jobs.length, 1);
+    assert.equal(jobs[0].jobId, second.jobId);
+  });
+
+  it("openCardViewer/closeCardViewer manage archive views without remint", () => {
+    openCardViewer({ card: CARD, agentName: "Eva", remint: null });
+    assert.equal(getCardViewerState()?.remint, null);
+    closeCardViewer();
+    assert.equal(getCardViewerState(), null);
+  });
+
+  it("gallery open flag toggles and notifies subscribers", () => {
+    let notified = 0;
+    const unsubscribe = subscribeCardMintStore(() => {
+      notified += 1;
+    });
+    setCardGalleryOpen(true);
+    assert.equal(getCardGalleryOpen(), true);
+    setCardGalleryOpen(true); // no-op must not notify
+    setCardGalleryOpen(false);
+    assert.equal(getCardGalleryOpen(), false);
+    assert.equal(notified, 2);
+    unsubscribe();
+  });
+
+  it("concurrent jobs keep distinct snapshots (referential updates)", async () => {
+    const before = getCardMintJobs();
+    await runCardMintJob(INPUT, () => Promise.resolve(CARD));
+    const after = getCardMintJobs();
+    assert.notEqual(before, after, "snapshot identity must change on update");
+  });
+});
diff --git a/desktop/src/features/agents/cardMintStore.ts b/desktop/src/features/agents/cardMintStore.ts
new file mode 100644
index 0000000000..c38bf393cc
--- /dev/null
+++ b/desktop/src/features/agents/cardMintStore.ts
@@ -0,0 +1,236 @@
+import * as React from "react";
+import { toast } from "sonner";
+
+import {
+  mintAgentCard,
+  NO_OPENAI_KEY_PREFIX,
+  type MintedAgentCard,
+  type SnapshotMemoryLevel,
+} from "@/shared/api/tauriPersonas";
+
+/**
+ * Module store for agent-card mints (`useSyncExternalStore` pattern, same as
+ * `avatarPresentationStore`).
+ *
+ * A mint is one stateless ~2–3 minute Rust call. Owning the in-flight promise
+ * here — instead of inside the mint dialog — is what makes the dialog
+ * non-blocking: it dispatches and closes, the composer activity rail shows a
+ * live "Minting card…" chip, and completion lands as a clickable toast plus a
+ * persistent "card ready" chip, none of which need the dialog mounted.
+ */
+
+/** Everything needed to run (or re-run) one mint. */
+export type CardMintInput = {
+  agentId: string;
+  agentName: string;
+  styleNotes?: string;
+  lock?: boolean;
+  /** Memory to embed in the card's snapshot. Omitted = "none". */
+  memoryLevel?: SnapshotMemoryLevel;
+};
+
+export type CardMintJob = {
+  jobId: string;
+  input: CardMintInput;
+  phase: "minting" | "done" | "error";
+  /** Populated when phase is "done". */
+  card: MintedAgentCard | null;
+  /** Populated when phase is "error". */
+  error: string | null;
+  startedAt: number;
+};
+
+/** Card content shown by the global viewer dialog. */
+export type CardViewerState = {
+  card: MintedAgentCard;
+  agentName: string;
+  /**
+   * Present when the card can be rerolled (fresh mints carry their input;
+   * archive views do not — the original style notes are gone).
+   */
+  remint: CardMintInput | null;
+  /**
+   * Monotonic per-open sequence, assigned by the store. The viewer keys its
+   * content on this so switching cards remounts (resetting recipients/menu
+   * state) — card bytes can't serve as the key because every card PNG shares
+   * the same header prefix and dimensions.
+   */
+  viewerSeq: number;
+};
+
+let jobs: CardMintJob[] = [];
+let viewer: CardViewerState | null = null;
+let galleryOpen = false;
+const listeners = new Set<() => void>();
+let nextJobId = 1;
+let nextViewerSeq = 1;
+
+function emitChange(): void {
+  for (const listener of listeners) listener();
+}
+
+function updateJob(jobId: string, patch: Partial<CardMintJob>): void {
+  jobs = jobs.map((job) => (job.jobId === jobId ? { ...job, ...patch } : job));
+  emitChange();
+}
+
+/**
+ * Run one mint as a background job. `mintFn` is injectable for tests; the
+ * public `startCardMint` binds the real Tauri command.
+ */
+export async function runCardMintJob(
+  input: CardMintInput,
+  mintFn: (
+    id: string,
+    styleNotes?: string,
+    lock?: boolean,
+    memoryLevel?: SnapshotMemoryLevel,
+  ) => Promise<MintedAgentCard>,
+): Promise<void> {
+  const jobId = `card-mint-${nextJobId++}`;
+  jobs = [
+    ...jobs,
+    {
+      jobId,
+      input,
+      phase: "minting",
+      card: null,
+      error: null,
+      startedAt: Date.now(),
+    },
+  ];
+  emitChange();
+
+  try {
+    const card = await mintFn(
+      input.agentId,
+      input.styleNotes,
+      input.lock,
+      input.memoryLevel,
+    );
+    updateJob(jobId, { phase: "done", card });
+    toast.success(`${input.agentName}'s card is ready`, {
+      action: {
+        label: "View card",
+        onClick: () => viewMintedCardJob(jobId),
+      },
+      duration: 10_000,
+    });
+  } catch (error) {
+    let message = error instanceof Error ? error.message : "Card mint failed.";
+    if (message.startsWith(NO_OPENAI_KEY_PREFIX)) {
+      // The dialog pre-checks the key, so this only happens when the key was
+      // removed between dialog-open and mint. The dialog's key-setup panel is
+      // long gone — surface a plain instruction instead of the wire prefix.
+      message = message.slice(NO_OPENAI_KEY_PREFIX.length).trim();
+    } else if (
+      message.startsWith("Card mint failed (HTTP 401 ") ||
+      message.includes("Incorrect API key")
+    ) {
+      // The saved OpenAI key is invalid or expired. Only match the OpenAI-call
+      // envelope prefix and the specific Incorrect-API-key message to avoid
+      // rewriting unrelated 401s (e.g. "Avatar fetch failed: HTTP 401 …").
+      message =
+        'The OpenAI API key is invalid or expired. Open the mint dialog and use "Update API key" to replace it.';
+    }
+    updateJob(jobId, { phase: "error", error: message });
+    toast.error(`Minting ${input.agentName}'s card failed`, {
+      description: message,
+    });
+  }
+}
+
+/** Start a mint in the background. Fire-and-forget; state flows via the store. */
+export function startCardMint(input: CardMintInput): void {
+  void runCardMintJob(input, mintAgentCard);
+}
+
+/** Open the finished card of a job in the viewer and clear its rail chip. */
+export function viewMintedCardJob(jobId: string): void {
+  const job = jobs.find((candidate) => candidate.jobId === jobId);
+  if (job?.phase !== "done" || !job.card) return;
+  viewer = {
+    card: job.card,
+    agentName: job.input.agentName,
+    remint: job.input,
+    viewerSeq: nextViewerSeq++,
+  };
+  jobs = jobs.filter((candidate) => candidate.jobId !== jobId);
+  emitChange();
+}
+
+/** Remove a job chip (used for error dismissal). */
+export function dismissCardMintJob(jobId: string): void {
+  const next = jobs.filter((candidate) => candidate.jobId !== jobId);
+  if (next.length === jobs.length) return;
+  jobs = next;
+  emitChange();
+}
+
+/** Open the viewer on an arbitrary card (e.g. one loaded from the archive). */
+export function openCardViewer(
+  state: Omit<CardViewerState, "viewerSeq">,
+): void {
+  viewer = { ...state, viewerSeq: nextViewerSeq++ };
+  emitChange();
+}
+
+export function closeCardViewer(): void {
+  if (!viewer) return;
+  viewer = null;
+  emitChange();
+}
+
+export function setCardGalleryOpen(open: boolean): void {
+  if (galleryOpen === open) return;
+  galleryOpen = open;
+  emitChange();
+}
+
+export function resetCardMintStore(): void {
+  jobs = [];
+  viewer = null;
+  galleryOpen = false;
+  emitChange();
+}
+
+export function getCardMintJobs(): CardMintJob[] {
+  return jobs;
+}
+
+export function getCardViewerState(): CardViewerState | null {
+  return viewer;
+}
+
+export function getCardGalleryOpen(): boolean {
+  return galleryOpen;
+}
+
+export function subscribeCardMintStore(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function useCardMintJobs(): CardMintJob[] {
+  return React.useSyncExternalStore(
+    subscribeCardMintStore,
+    getCardMintJobs,
+    getCardMintJobs,
+  );
+}
+
+export function useCardViewerState(): CardViewerState | null {
+  return React.useSyncExternalStore(
+    subscribeCardMintStore,
+    getCardViewerState,
+    getCardViewerState,
+  );
+}
+
+export function useCardGalleryOpen(): boolean {
+  return React.useSyncExternalStore(
+    subscribeCardMintStore,
+    getCardGalleryOpen,
+    getCardGalleryOpen,
+  );
+}
diff --git a/desktop/src/features/agents/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/ui/AgentCardMintDialog.test.mjs b/desktop/src/features/agents/ui/AgentCardMintDialog.test.mjs
new file mode 100644
index 0000000000..ff3efaec92
--- /dev/null
+++ b/desktop/src/features/agents/ui/AgentCardMintDialog.test.mjs
@@ -0,0 +1,257 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+// Tests for the key-panel visibility derivations that AgentCardMintDialog
+// imports from cardMintKeyUtils. These tests exercise the exact production
+// module — changes to any exported function will cause failures here.
+
+import {
+  isReadOnlyLayer,
+  isWritableLayer,
+  keyPanelTitle,
+  showCancelButton,
+  showKeyPanel,
+  showKeyStatusRow,
+  showReadOnlyRow,
+} from "./cardMintKeyUtils.ts";
+
+describe("cardMintKeyUtils — key panel derivations", () => {
+  // ── isWritableLayer ────────────────────────────────────────────────────────
+
+  it("isWritableLayer_none_true", () => {
+    assert.equal(isWritableLayer("none"), true);
+  });
+
+  it("isWritableLayer_global_true", () => {
+    assert.equal(isWritableLayer("global"), true);
+  });
+
+  it("isWritableLayer_agent_false", () => {
+    assert.equal(isWritableLayer("agent"), false);
+  });
+
+  it("isWritableLayer_persona_false", () => {
+    assert.equal(isWritableLayer("persona"), false);
+  });
+
+  it("isWritableLayer_process_false", () => {
+    assert.equal(isWritableLayer("process"), false);
+  });
+
+  it("isWritableLayer_undefined_false", () => {
+    // Unknown (pending/error) — don't offer a write path
+    assert.equal(isWritableLayer(undefined), false);
+  });
+
+  // ── isReadOnlyLayer ────────────────────────────────────────────────────────
+
+  it("isReadOnlyLayer_agent_true", () => {
+    assert.equal(isReadOnlyLayer("agent"), true);
+  });
+
+  it("isReadOnlyLayer_persona_true", () => {
+    assert.equal(isReadOnlyLayer("persona"), true);
+  });
+
+  it("isReadOnlyLayer_process_true", () => {
+    assert.equal(isReadOnlyLayer("process"), true);
+  });
+
+  it("isReadOnlyLayer_global_false", () => {
+    assert.equal(isReadOnlyLayer("global"), false);
+  });
+
+  it("isReadOnlyLayer_none_false", () => {
+    assert.equal(isReadOnlyLayer("none"), false);
+  });
+
+  it("isReadOnlyLayer_undefined_false", () => {
+    assert.equal(isReadOnlyLayer(undefined), false);
+  });
+
+  // ── showKeyPanel ───────────────────────────────────────────────────────────
+  // Key panel replaces the mint form ONLY for first-time setup (none) or
+  // user-initiated editing (editingKey). Read-only layers do NOT replace the
+  // mint form — they show an inline status row instead.
+
+  it("showKeyPanel_none_notEditing_shows", () => {
+    // First-time user: key not set → show setup panel
+    assert.equal(showKeyPanel("none", false), true);
+  });
+
+  it("showKeyPanel_global_notEditing_hides", () => {
+    // Normal state: key in global defaults, not editing → show mint form
+    assert.equal(showKeyPanel("global", false), false);
+  });
+
+  it("showKeyPanel_global_editing_shows", () => {
+    // User clicked Update → show the update panel
+    assert.equal(showKeyPanel("global", true), true);
+  });
+
+  it("showKeyPanel_agent_notEditing_hides", () => {
+    // Read-only layer: mint form stays visible; inline row shown instead
+    assert.equal(showKeyPanel("agent", false), false);
+  });
+
+  it("showKeyPanel_persona_notEditing_hides", () => {
+    assert.equal(showKeyPanel("persona", false), false);
+  });
+
+  it("showKeyPanel_process_notEditing_hides", () => {
+    assert.equal(showKeyPanel("process", false), false);
+  });
+
+  it("showKeyPanel_agent_editing_shows", () => {
+    // User clicked Why? on a read-only row → show the redirect panel
+    assert.equal(showKeyPanel("agent", true), true);
+  });
+
+  it("showKeyPanel_persona_editing_shows", () => {
+    assert.equal(showKeyPanel("persona", true), true);
+  });
+
+  it("showKeyPanel_process_editing_shows", () => {
+    assert.equal(showKeyPanel("process", true), true);
+  });
+
+  it("showKeyPanel_undefined_notEditing_hides", () => {
+    // Query pending/error → show mint form (fail-open, no panel claim)
+    assert.equal(showKeyPanel(undefined, false), false);
+  });
+
+  // ── showCancelButton ───────────────────────────────────────────────────────
+
+  it("showCancelButton_global_editing_shows", () => {
+    // Update mode for a global key: Cancel returns to the mint form
+    assert.equal(showCancelButton("global", true), true);
+  });
+
+  it("showCancelButton_none_editing_hides", () => {
+    // First-time setup: no cancel (no mint form to return to)
+    assert.equal(showCancelButton("none", true), false);
+  });
+
+  it("showCancelButton_global_notEditing_hides", () => {
+    assert.equal(showCancelButton("global", false), false);
+  });
+
+  it("showCancelButton_agent_editing_shows", () => {
+    // Read-only layer + user clicked Why?: Cancel returns to the mint form
+    assert.equal(showCancelButton("agent", true), true);
+  });
+
+  it("showCancelButton_persona_editing_shows", () => {
+    assert.equal(showCancelButton("persona", true), true);
+  });
+
+  it("showCancelButton_process_editing_shows", () => {
+    assert.equal(showCancelButton("process", true), true);
+  });
+
+  // ── showKeyStatusRow ───────────────────────────────────────────────────────
+
+  it("showKeyStatusRow_global_notEditing_shows", () => {
+    // Confirmed writable key: show "Using your saved OpenAI key · Update"
+    assert.equal(showKeyStatusRow("global", false), true);
+  });
+
+  it("showKeyStatusRow_global_editing_hides", () => {
+    // In update panel: status row is redundant while editing
+    assert.equal(showKeyStatusRow("global", true), false);
+  });
+
+  it("showKeyStatusRow_none_notEditing_hides", () => {
+    // No key: show setup panel, not status row
+    assert.equal(showKeyStatusRow("none", false), false);
+  });
+
+  it("showKeyStatusRow_agent_notEditing_hides", () => {
+    // Read-only layer: use showReadOnlyRow instead
+    assert.equal(showKeyStatusRow("agent", false), false);
+  });
+
+  it("showKeyStatusRow_undefined_notEditing_hides", () => {
+    // Query pending/error: do not assert key existence
+    assert.equal(showKeyStatusRow(undefined, false), false);
+  });
+
+  // ── showReadOnlyRow ────────────────────────────────────────────────────────
+  // Inline provenance row on the mint form for keys the dialog cannot update.
+
+  it("showReadOnlyRow_agent_notEditing_shows", () => {
+    assert.equal(showReadOnlyRow("agent", false), true);
+  });
+
+  it("showReadOnlyRow_persona_notEditing_shows", () => {
+    assert.equal(showReadOnlyRow("persona", false), true);
+  });
+
+  it("showReadOnlyRow_process_notEditing_shows", () => {
+    assert.equal(showReadOnlyRow("process", false), true);
+  });
+
+  it("showReadOnlyRow_agent_editing_hides", () => {
+    // User clicked Why? → redirect panel shown; row hidden
+    assert.equal(showReadOnlyRow("agent", true), false);
+  });
+
+  it("showReadOnlyRow_global_notEditing_hides", () => {
+    // Global key uses showKeyStatusRow instead
+    assert.equal(showReadOnlyRow("global", false), false);
+  });
+
+  it("showReadOnlyRow_none_hides", () => {
+    assert.equal(showReadOnlyRow("none", false), false);
+  });
+
+  it("showReadOnlyRow_undefined_hides", () => {
+    assert.equal(showReadOnlyRow(undefined, false), false);
+  });
+
+  // ── Mint-reachability invariant ────────────────────────────────────────────
+  // The mint form (and Mint button) must be reachable whenever a key resolves.
+  // showKeyPanel returns true only for setup (none) or user-initiated edit.
+
+  it("mintReachable_global_noEdit", () => {
+    assert.equal(showKeyPanel("global", false), false);
+  });
+
+  it("mintReachable_agent_noEdit", () => {
+    assert.equal(showKeyPanel("agent", false), false);
+  });
+
+  it("mintReachable_persona_noEdit", () => {
+    assert.equal(showKeyPanel("persona", false), false);
+  });
+
+  it("mintReachable_process_noEdit", () => {
+    assert.equal(showKeyPanel("process", false), false);
+  });
+
+  it("mintBlocked_none_noEdit", () => {
+    // Only when no key is set at all does the panel gate minting
+    assert.equal(showKeyPanel("none", false), true);
+  });
+
+  // ── keyPanelTitle ──────────────────────────────────────────────────────────
+
+  it("keyPanelTitle_none_firstTimeSetup", () => {
+    assert.equal(
+      keyPanelTitle("none", false),
+      "One-time setup: OpenAI API key",
+    );
+  });
+
+  it("keyPanelTitle_global_editing_update", () => {
+    assert.equal(keyPanelTitle("global", true), "Update OpenAI API key");
+  });
+
+  it("keyPanelTitle_agent_readOnly", () => {
+    assert.equal(keyPanelTitle("agent", false), "OpenAI API key");
+  });
+
+  it("keyPanelTitle_persona_readOnly", () => {
+    assert.equal(keyPanelTitle("persona", true), "OpenAI API key");
+  });
+});
diff --git a/desktop/src/features/agents/ui/AgentCardMintDialog.tsx b/desktop/src/features/agents/ui/AgentCardMintDialog.tsx
new file mode 100644
index 0000000000..b2bffc00df
--- /dev/null
+++ b/desktop/src/features/agents/ui/AgentCardMintDialog.tsx
@@ -0,0 +1,463 @@
+import * as React from "react";
+import {
+  AlertCircle,
+  Brain,
+  ExternalLink,
+  GalleryVerticalEnd,
+  KeyRound,
+  Lock,
+  Sparkles,
+} from "lucide-react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { openUrl } from "@tauri-apps/plugin-opener";
+import { toast } from "sonner";
+
+import {
+  setCardGalleryOpen,
+  startCardMint,
+} from "@/features/agents/cardMintStore";
+import { globalAgentConfigQueryKey } from "@/features/agents/useGlobalAgentConfig";
+import {
+  cardMintKeyStatus,
+  cardMintSaveOpenaiKey,
+  type CardMintKeyLayer,
+  type SnapshotMemoryLevel,
+} from "@/shared/api/tauriPersonas";
+import { Button } from "@/shared/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/shared/ui/dialog";
+import { Input } from "@/shared/ui/input";
+import { Switch } from "@/shared/ui/switch";
+import { Textarea } from "@/shared/ui/textarea";
+import { SnapshotOptionMenu } from "./SnapshotOptionMenu";
+import {
+  isReadOnlyLayer,
+  keyPanelTitle,
+  showCancelButton,
+  showKeyPanel,
+  showKeyStatusRow,
+  showReadOnlyRow,
+} from "./cardMintKeyUtils";
+
+const OPENAI_KEYS_URL = "https://platform.openai.com/api-keys";
+
+/** Same three levels as snapshot export; "Agent only" is the safe default. */
+const MEMORY_LEVELS: { value: SnapshotMemoryLevel; label: string }[] = [
+  { value: "none", label: "Agent only" },
+  { value: "core", label: "Agent + core memory" },
+  { value: "everything", label: "Agent + all memories" },
+];
+
+/**
+ * The free alternative, as an action: ordinary snapshot export shares the
+ * same importable agent without card art or API spend. Rendered in both the
+ * key-setup panel and the normal pre-mint form (the cost disclosure and its
+ * escape hatch must be visible BEFORE any spend, not only during onboarding).
+ */
+function FreeSharePathRow({
+  disabled,
+  onExportInstead,
+}: {
+  disabled: boolean;
+  onExportInstead?: () => void;
+}) {
+  return (
+    <div
+      className="flex items-center justify-between gap-3"
+      data-testid="agent-card-free-path"
+    >
+      <p className="text-xs text-muted-foreground">
+        Don’t want to spend money? Ordinary export shares the same importable
+        agent — free, just without the card art.
+      </p>
+      {onExportInstead ? (
+        <Button
+          className="shrink-0"
+          data-testid="agent-card-export-instead"
+          disabled={disabled}
+          onClick={onExportInstead}
+          size="sm"
+          variant="outline"
+        >
+          Share without card art
+        </Button>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * Mint-a-trading-card dialog — the pre-mint half only: key setup (when
+ * needed) → optional style notes → "Mint card". Minting itself runs as a
+ * background job in `cardMintStore`: this dialog dispatches and closes, the
+ * composer activity rail shows live status, and the finished card opens in
+ * the global `AgentCardViewerDialog` (preview, reroll, save, share).
+ *
+ * The saved PNG carries the agent's `buzz_agent_snapshot` chunk, so sharing
+ * the card shares an importable agent (fresh identity, never secrets; memory
+ * only when the owner opts in below — plaintext unless the card is locked).
+ * All snapshot construction and verification happens in Rust.
+ */
+export function AgentCardMintDialog({
+  agentId,
+  agentName,
+  canLock,
+  onExportInstead,
+  onOpenChange,
+}: {
+  /** Instance pubkey or definition slug — same resolution as snapshot export. */
+  agentId: string;
+  agentName: string;
+  /**
+   * True when the agent has a linked instance (a keypair to lock to).
+   * Locking is disabled — with an explanation — for bare definitions.
+   */
+  canLock: boolean;
+  /**
+   * Free alternative: close this dialog and open the ordinary snapshot
+   * export flow (no API spend). Omitted = the action is not rendered.
+   */
+  onExportInstead?: () => void;
+  onOpenChange: (open: boolean) => void;
+}) {
+  const [styleNotes, setStyleNotes] = React.useState("");
+  const [lockCard, setLockCard] = React.useState(false);
+  const [memoryLevel, setMemoryLevel] =
+    React.useState<SnapshotMemoryLevel>("none");
+  const [keyDraft, setKeyDraft] = React.useState("");
+  const [editingKey, setEditingKey] = React.useState(false);
+
+  const queryClient = useQueryClient();
+
+  const effectiveLock = canLock && lockCard;
+  // Embedded memory is plaintext in an unlocked card — and unlocked cards
+  // are meant to be shared. A locked card encrypts the whole manifest to the
+  // (owner, agent) pair, so the plaintext warning would be false there.
+  const showMemoryWarning = memoryLevel !== "none" && !effectiveLock;
+
+  // Whether a key already resolves through the agent's env layering, and from
+  // which layer. While unknown (loading/error) we treat as if no verified key
+  // exists — mint still works fail-open, but we don't assert a key is present.
+  const keyStatusQuery = useQuery({
+    queryKey: ["cardMintKeyStatus", agentId],
+    queryFn: () => cardMintKeyStatus(agentId),
+  });
+  const keyLayer: CardMintKeyLayer | undefined = keyStatusQuery.data;
+  // True when the key resolves from a layer this dialog cannot update.
+  const keyIsReadOnly = isReadOnlyLayer(keyLayer);
+
+  // Save the pasted key into the global Agent Defaults env — the same single
+  // source of truth every agent inherits. Narrow Rust seam: validated
+  // single-key merge, never restarts running agents (the mint re-reads
+  // config per call, so no restart is needed for minting).
+  const saveKeyMutation = useMutation({
+    mutationFn: (key: string) => cardMintSaveOpenaiKey(key),
+    onSuccess: () => {
+      // The key now lives in global defaults — update the cached layer so the
+      // status row shows correctly without waiting for a refetch.
+      queryClient.setQueryData<CardMintKeyLayer>(
+        ["cardMintKeyStatus", agentId],
+        "global",
+      );
+      // The Agent Defaults editor caches the whole config — refetch it so a
+      // later-opened settings view shows the key we just wrote.
+      void queryClient.invalidateQueries({
+        queryKey: globalAgentConfigQueryKey,
+      });
+      setKeyDraft("");
+      setEditingKey(false);
+      toast.success(
+        "API key saved to your agent defaults. Running agents pick it up on their next restart.",
+      );
+    },
+    onError: (error) =>
+      toast.error(typeof error === "string" ? error : "Couldn't save the key."),
+  });
+
+  function beginMint() {
+    // Dispatch to the background store and close: the composer rail shows
+    // "Minting card…" and the completion toast opens the viewer.
+    startCardMint({
+      agentId,
+      agentName,
+      styleNotes: styleNotes.trim() || undefined,
+      lock: effectiveLock,
+      memoryLevel: canLock ? memoryLevel : "none",
+    });
+    onOpenChange(false);
+  }
+
+  return (
+    <Dialog onOpenChange={onOpenChange} open>
+      <DialogContent className="max-w-md" data-testid="agent-card-mint-dialog">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Sparkles className="h-4 w-4" />
+            {`Create ${agentName}'s card`}
+          </DialogTitle>
+          <DialogDescription>
+            Mint a collectible trading card that doubles as a shareable,
+            importable copy of this agent.
+          </DialogDescription>
+        </DialogHeader>
+
+        {showKeyPanel(keyLayer, editingKey) ? (
+          <div
+            className="flex flex-col gap-4"
+            data-testid="agent-card-key-setup"
+          >
+            <div className="flex flex-col gap-2 rounded-md border border-border p-3">
+              <span className="flex items-center gap-1.5 text-sm font-medium">
+                <KeyRound className="h-3.5 w-3.5" />
+                {keyPanelTitle(keyLayer, editingKey)}
+              </span>
+              {keyIsReadOnly ? (
+                // Key resolves from a layer the dialog cannot write to — show
+                // a read-only redirect instead of an input that would be
+                // shadowed by the higher-priority layer.
+                <p
+                  className="text-xs text-muted-foreground"
+                  data-testid="agent-card-key-readonly"
+                >
+                  {keyLayer === "agent"
+                    ? "This agent's OpenAI key is set in its own agent settings — update it there."
+                    : keyLayer === "persona"
+                      ? "This agent's OpenAI key comes from its linked persona settings — update it there."
+                      : "This agent's OpenAI key is set in the process environment — update it in your shell or launch config."}
+                </p>
+              ) : (
+                <>
+                  <p className="text-xs text-muted-foreground">
+                    Minting a card costs money — it generates the art and card
+                    text through the OpenAI API with your key (typically well
+                    under a dollar per mint, billed by OpenAI). The key is saved
+                    as <code className="font-mono">OPENAI_API_KEY</code> in your
+                    agent defaults env — that's the row to update in Settings if
+                    you ever need to change it there.
+                  </p>
+                  <Button
+                    className="w-fit px-0 text-xs"
+                    data-testid="agent-card-key-link"
+                    onClick={() =>
+                      void openUrl(OPENAI_KEYS_URL).catch(() => {
+                        toast.error("Failed to open link");
+                      })
+                    }
+                    size="sm"
+                    variant="link"
+                  >
+                    <ExternalLink className="mr-1 h-3 w-3" />
+                    Get a key at platform.openai.com
+                  </Button>
+                  <Input
+                    autoFocus
+                    data-testid="agent-card-key-input"
+                    disabled={saveKeyMutation.isPending}
+                    onChange={(e) => setKeyDraft(e.target.value)}
+                    placeholder="sk-…"
+                    type="password"
+                    value={keyDraft}
+                  />
+                </>
+              )}
+            </div>
+            <FreeSharePathRow
+              disabled={saveKeyMutation.isPending}
+              onExportInstead={onExportInstead}
+            />
+            <div className="flex justify-end gap-2">
+              {showCancelButton(keyLayer, editingKey) ? (
+                <Button
+                  data-testid="agent-card-key-cancel"
+                  disabled={saveKeyMutation.isPending}
+                  onClick={() => {
+                    setKeyDraft("");
+                    setEditingKey(false);
+                  }}
+                  variant="outline"
+                >
+                  Cancel
+                </Button>
+              ) : null}
+              {!keyIsReadOnly ? (
+                <Button
+                  data-testid="agent-card-key-save"
+                  disabled={
+                    saveKeyMutation.isPending || keyDraft.trim().length === 0
+                  }
+                  onClick={() => saveKeyMutation.mutate(keyDraft.trim())}
+                >
+                  <KeyRound className="mr-2 h-4 w-4" />
+                  {saveKeyMutation.isPending
+                    ? "Saving…"
+                    : "Save key & continue"}
+                </Button>
+              ) : null}
+            </div>
+          </div>
+        ) : (
+          <div className="flex flex-col gap-4">
+            <div className="flex flex-col gap-1.5">
+              <Textarea
+                onChange={(e) => setStyleNotes(e.target.value)}
+                placeholder="Optional style notes for the art and card text"
+                rows={3}
+                value={styleNotes}
+              />
+              <p className="text-xs text-muted-foreground">
+                E.g. art “stormy night, lightning motif” or ability “Verify —
+                scry 2”. Your directions take priority; anything you leave open
+                is designed for you.
+              </p>
+            </div>
+            <div className="flex items-center justify-between gap-3 rounded-md border border-border p-3">
+              <div className="flex flex-col gap-0.5">
+                <span className="flex items-center gap-1.5 text-sm font-medium">
+                  <Brain className="h-3.5 w-3.5" />
+                  Memories
+                </span>
+                <span className="text-xs text-muted-foreground">
+                  {canLock
+                    ? "Choose how much memory the embedded agent carries."
+                    : "Including memory needs a linked agent instance — start this agent once to enable it."}
+                </span>
+              </div>
+              {canLock ? (
+                <SnapshotOptionMenu
+                  ariaLabel="Memories"
+                  className="font-medium text-foreground"
+                  onValueChange={(value) =>
+                    setMemoryLevel(value as SnapshotMemoryLevel)
+                  }
+                  options={MEMORY_LEVELS}
+                  testId="agent-card-memory-trigger"
+                  value={memoryLevel}
+                />
+              ) : (
+                <span
+                  className="inline-flex h-8 w-auto shrink-0 items-center justify-end px-2 text-sm font-medium"
+                  data-testid="agent-card-memory-value"
+                >
+                  Agent only
+                </span>
+              )}
+            </div>
+            {showMemoryWarning ? (
+              <div
+                className="flex items-start gap-2 rounded-md border border-amber-500/30 bg-amber-500/10 px-3 py-2 text-sm text-amber-700 dark:text-amber-400"
+                data-testid="agent-card-memory-warning"
+              >
+                <AlertCircle className="mt-0.5 h-4 w-4 shrink-0" />
+                <p>
+                  Memory is stored as <strong>plaintext</strong> in the card,
+                  readable by anyone who has the PNG — and cards are made for
+                  sharing. Lock the card or only share it with people you trust.
+                </p>
+              </div>
+            ) : null}
+            <div className="flex items-start justify-between gap-3 rounded-md border border-border p-3">
+              <div className="flex flex-col gap-0.5">
+                <span className="flex items-center gap-1.5 text-sm font-medium">
+                  <Lock className="h-3.5 w-3.5" />
+                  Lock card
+                </span>
+                <span className="text-xs text-muted-foreground">
+                  {canLock
+                    ? "Encrypt the embedded agent so only you and this agent can import it. Anyone else sees just the image."
+                    : "Locking needs a linked agent instance — start this agent once to enable it."}
+                </span>
+              </div>
+              <Switch
+                checked={canLock && lockCard}
+                data-testid="agent-card-lock-toggle"
+                disabled={!canLock}
+                onCheckedChange={setLockCard}
+              />
+            </div>
+            {showKeyStatusRow(keyLayer, editingKey) ? (
+              <div
+                className="flex items-center gap-1 text-xs text-muted-foreground"
+                data-testid="agent-card-key-status"
+              >
+                <KeyRound className="h-3 w-3 shrink-0" />
+                <span>Using your saved OpenAI key</span>
+                <span aria-hidden>·</span>
+                <Button
+                  className="h-auto p-0 text-xs"
+                  data-testid="agent-card-update-key"
+                  onClick={() => setEditingKey(true)}
+                  size="sm"
+                  variant="link"
+                >
+                  Update
+                </Button>
+              </div>
+            ) : null}
+            {showReadOnlyRow(keyLayer, editingKey) ? (
+              <div
+                className="flex items-center gap-1 text-xs text-muted-foreground"
+                data-testid="agent-card-key-readonly-row"
+              >
+                <KeyRound className="h-3 w-3 shrink-0" />
+                <span>
+                  {keyLayer === "agent"
+                    ? "OpenAI key from agent settings"
+                    : keyLayer === "persona"
+                      ? "OpenAI key from persona settings"
+                      : "OpenAI key from environment"}
+                </span>
+                <span aria-hidden>·</span>
+                <Button
+                  className="h-auto p-0 text-xs"
+                  data-testid="agent-card-key-why"
+                  onClick={() => setEditingKey(true)}
+                  size="sm"
+                  variant="link"
+                >
+                  Why?
+                </Button>
+              </div>
+            ) : null}
+            <p
+              className="text-xs text-muted-foreground"
+              data-testid="agent-card-cost-note"
+            >
+              Minting calls the OpenAI API with your key and costs money —
+              typically well under a dollar per mint, billed by OpenAI. It runs
+              in the background (takes a few minutes); you can keep using Buzz
+              while it works.
+            </p>
+            <FreeSharePathRow
+              disabled={false}
+              onExportInstead={onExportInstead}
+            />
+            <div className="flex items-center justify-between gap-2">
+              <Button
+                className="px-0 text-xs"
+                data-testid="agent-card-open-gallery"
+                onClick={() => {
+                  onOpenChange(false);
+                  setCardGalleryOpen(true);
+                }}
+                size="sm"
+                variant="link"
+              >
+                <GalleryVerticalEnd className="mr-1 h-3 w-3" />
+                View minted cards
+              </Button>
+              <Button onClick={beginMint} data-testid="agent-card-mint">
+                <Sparkles className="mr-2 h-4 w-4" />
+                Mint card
+              </Button>
+            </div>
+          </div>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/desktop/src/features/agents/ui/AgentCardViewerDialog.tsx b/desktop/src/features/agents/ui/AgentCardViewerDialog.tsx
new file mode 100644
index 0000000000..c2422466e4
--- /dev/null
+++ b/desktop/src/features/agents/ui/AgentCardViewerDialog.tsx
@@ -0,0 +1,369 @@
+import * as React from "react";
+import { Download, Lock, RefreshCw, Send, Sparkles } from "lucide-react";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { toast } from "sonner";
+
+import {
+  closeCardViewer,
+  openCardViewer,
+  setCardGalleryOpen,
+  startCardMint,
+  useCardGalleryOpen,
+  useCardViewerState,
+  type CardMintInput,
+} from "@/features/agents/cardMintStore";
+import { agentCardGalleryViewState } from "@/features/agents/lib/agentCardGalleryState";
+import {
+  useOpenDmMutation,
+  useUpsertCachedChannel,
+} from "@/features/channels/hooks";
+import {
+  listAgentCards,
+  loadAgentCard,
+  saveAgentCard,
+  type ArchivedAgentCard,
+  type MintedAgentCard,
+} from "@/shared/api/tauriPersonas";
+import type { UserSearchResult } from "@/shared/api/types";
+import { Button } from "@/shared/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/shared/ui/dialog";
+import {
+  MediaContextMenu,
+  type MediaContextMenuPosition,
+  useDismissMediaContextMenu,
+} from "@/shared/ui/markdown/MediaContextMenu";
+
+import { PersonaShareRecipients } from "./PersonaShareRecipients";
+import { useSnapshotSendController } from "./useSnapshotSendController";
+
+/** Decode base64 card bytes into the number[] shape the upload path expects. */
+function cardBytesFromBase64(b64: string): number[] {
+  return Array.from(atob(b64), (char) => char.charCodeAt(0));
+}
+
+/**
+ * Global card surfaces, mounted once in `AppShell` next to the other global
+ * dialogs and driven by `cardMintStore`: the finished-card viewer plus the
+ * previous-mints gallery.
+ */
+export function AgentCardDialogs() {
+  return (
+    <>
+      <AgentCardViewerDialog />
+      <AgentCardGalleryDialog />
+    </>
+  );
+}
+
+/**
+ * Global viewer for a finished agent trading card — the post-mint half of the
+ * old blocking mint dialog, now openable from anywhere (completion toast,
+ * composer "card ready" chip, or the previous-cards gallery). Mounted once in
+ * `AppShell` next to the other global dialogs and driven by `cardMintStore`.
+ *
+ * The card image carries the same right-click download menu inline channel
+ * images have (`MediaContextMenu`), but routed through `save_agent_card`:
+ * `download_image` only accepts relay `/media/` URLs, and this card exists
+ * only as local base64.
+ */
+export function AgentCardViewerDialog() {
+  const state = useCardViewerState();
+
+  // Keyed remount resets recipients/menu state when a different card opens.
+  if (!state) return null;
+  return (
+    <AgentCardViewerContent
+      key={state.viewerSeq}
+      agentName={state.agentName}
+      card={state.card}
+      remint={state.remint}
+    />
+  );
+}
+
+function AgentCardViewerContent({
+  agentName,
+  card,
+  remint,
+}: {
+  agentName: string;
+  card: MintedAgentCard;
+  remint: CardMintInput | null;
+}) {
+  const [recipients, setRecipients] = React.useState<UserSearchResult[]>([]);
+  const [menu, setMenu] = React.useState<MediaContextMenuPosition | null>(null);
+  const closeMenu = React.useCallback(() => setMenu(null), []);
+  useDismissMediaContextMenu(Boolean(menu), closeMenu);
+
+  const sendController = useSnapshotSendController(true);
+  const openDmMutation = useOpenDmMutation();
+  const upsertCachedChannel = useUpsertCachedChannel();
+
+  const saveMutation = useMutation({
+    mutationFn: () => saveAgentCard(card.cardPngBase64, card.fileName),
+    onSuccess: (saved) => {
+      if (saved) {
+        toast.success(
+          `Saved ${agentName}'s card. Share it — the card IS the agent.`,
+        );
+      }
+    },
+    onError: (error: Error) => toast.error(error.message),
+  });
+
+  const isSending =
+    sendController.state.phase !== "idle" &&
+    sendController.state.phase !== "done" &&
+    sendController.state.phase !== "error";
+  const isBusy = saveMutation.isPending || isSending;
+
+  async function sendToRecipients() {
+    if (recipients.length === 0) return;
+    const sent = await sendController.beginSend(
+      async () => ({
+        fileBytes: cardBytesFromBase64(card.cardPngBase64),
+        fileName: card.fileName,
+      }),
+      async () => {
+        const directMessage = await openDmMutation.mutateAsync({
+          pubkeys: recipients.map((recipient) => recipient.pubkey),
+        });
+        await upsertCachedChannel(directMessage);
+        return directMessage.id;
+      },
+      agentName,
+    );
+    if (sent) {
+      toast.success(`Sent ${agentName}'s card.`);
+      closeCardViewer();
+    } else if (sent === false) {
+      toast.error("Couldn’t send the card. Try again.");
+    }
+  }
+
+  return (
+    <Dialog onOpenChange={(open) => !open && closeCardViewer()} open>
+      <DialogContent
+        className="max-w-md"
+        data-testid="agent-card-viewer-dialog"
+      >
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Sparkles className="h-4 w-4" />
+            {`${agentName}'s card`}
+          </DialogTitle>
+          <DialogDescription>
+            {card.locked
+              ? "This card is locked: only you and the agent can import it. Anyone else sees just the image."
+              : card.memoryLevel === "none"
+                ? "The card carries the agent — anyone who imports this PNG gets a working copy (config only, fresh identity, no memories)."
+                : `The card carries the agent — anyone who imports this PNG gets a working copy (fresh identity) including its ${card.memoryLevel === "core" ? "core memory" : "memories"}, stored as plaintext.`}
+          </DialogDescription>
+        </DialogHeader>
+        <div className="flex flex-col gap-4">
+          <img
+            alt={`${agentName} trading card`}
+            className="mx-auto max-h-[28rem] rounded-lg border shadow-lg"
+            data-testid="agent-card-preview"
+            onContextMenu={(event) => {
+              event.preventDefault();
+              setMenu({ x: event.clientX, y: event.clientY });
+            }}
+            src={`data:image/png;base64,${card.cardPngBase64}`}
+          />
+          {menu ? (
+            <MediaContextMenu
+              dataAttributes={["data-agent-card-context-menu"]}
+              items={[
+                {
+                  label: "Download card",
+                  onSelect: () => {
+                    closeMenu();
+                    saveMutation.mutate();
+                  },
+                },
+              ]}
+              position={menu}
+            />
+          ) : null}
+          <PersonaShareRecipients
+            disabled={isBusy || !sendController.isDmSafetyReady}
+            excludedPubkeys={
+              sendController.relaySelfPubkey
+                ? [sendController.relaySelfPubkey]
+                : []
+            }
+            onSelectionChange={setRecipients}
+            open
+            selectedUsers={recipients}
+            testIdPrefix="agent-card-share"
+          />
+          <div className="flex justify-end gap-2">
+            {remint ? (
+              <Button
+                disabled={isBusy}
+                data-testid="agent-card-reroll"
+                onClick={() => {
+                  // Reroll = a fresh background mint with the same input; the
+                  // viewer closes and the composer chip takes over.
+                  startCardMint(remint);
+                  closeCardViewer();
+                }}
+                variant="outline"
+              >
+                <RefreshCw className="mr-2 h-4 w-4" />
+                Reroll
+              </Button>
+            ) : null}
+            <Button
+              disabled={isBusy}
+              onClick={() => saveMutation.mutate()}
+              data-testid="agent-card-save"
+              variant={recipients.length > 0 ? "outline" : "default"}
+            >
+              <Download className="mr-2 h-4 w-4" />
+              Save card
+            </Button>
+            {recipients.length > 0 ? (
+              <Button
+                disabled={isBusy}
+                onClick={() => void sendToRecipients()}
+                data-testid="agent-card-send"
+              >
+                <Send className="mr-2 h-4 w-4" />
+                {isSending ? "Sending…" : "Send"}
+              </Button>
+            ) : null}
+          </div>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+/**
+ * Gallery of all previously minted cards, newest first. Every successful mint
+ * is archived to the app data dir by Rust; clicking a tile loads the full PNG
+ * and opens it in the viewer (save/share, no reroll — the original style
+ * notes are not retained).
+ */
+export function AgentCardGalleryDialog() {
+  const open = useCardGalleryOpen();
+  if (!open) return null;
+  return <AgentCardGalleryContent />;
+}
+
+function AgentCardGalleryContent() {
+  const cardsQuery = useQuery({
+    queryKey: ["agentCardArchive"],
+    queryFn: listAgentCards,
+  });
+
+  const openMutation = useMutation({
+    mutationFn: async (entry: ArchivedAgentCard) => {
+      const cardPngBase64 = await loadAgentCard(entry.storedFileName);
+      return { entry, cardPngBase64 };
+    },
+    onSuccess: ({ entry, cardPngBase64 }) => {
+      setCardGalleryOpen(false);
+      openCardViewer({
+        agentName: entry.agentName,
+        card: {
+          cardPngBase64,
+          fileName: entry.fileName,
+          designerNotes: entry.designerNotes,
+          locked: entry.locked,
+          memoryLevel: entry.memoryLevel,
+        },
+        remint: null,
+      });
+    },
+    onError: (error: Error) => toast.error(error.message),
+  });
+
+  const cards = cardsQuery.data ?? [];
+  const viewState = agentCardGalleryViewState(cardsQuery);
+
+  return (
+    <Dialog onOpenChange={(open) => setCardGalleryOpen(open)} open>
+      <DialogContent
+        className="max-w-lg"
+        data-testid="agent-card-gallery-dialog"
+      >
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Sparkles className="h-4 w-4" />
+            Minted cards
+          </DialogTitle>
+          <DialogDescription>
+            Every card you’ve minted, newest first. Click one to view, save, or
+            share it.
+          </DialogDescription>
+        </DialogHeader>
+        {viewState.kind === "loading" ? (
+          <p className="py-8 text-center text-sm text-muted-foreground">
+            Loading cards…
+          </p>
+        ) : viewState.kind === "error" ? (
+          <div
+            className="flex flex-col items-center gap-3 py-8"
+            data-testid="agent-card-gallery-error"
+            role="alert"
+          >
+            <p className="text-center text-sm text-destructive">
+              Couldn’t load your minted cards: {viewState.message}
+            </p>
+            <Button
+              disabled={cardsQuery.isFetching}
+              onClick={() => void cardsQuery.refetch()}
+              size="sm"
+              variant="outline"
+            >
+              <RefreshCw className="mr-2 h-4 w-4" />
+              {cardsQuery.isFetching ? "Retrying…" : "Retry"}
+            </Button>
+          </div>
+        ) : viewState.kind === "empty" ? (
+          <p className="py-8 text-center text-sm text-muted-foreground">
+            No cards yet — mint one from an agent’s profile.
+          </p>
+        ) : (
+          <div className="grid max-h-[60vh] grid-cols-3 gap-3 overflow-y-auto pr-1">
+            {cards.map((entry) => (
+              <button
+                className="group flex flex-col gap-1.5 text-left"
+                data-testid="agent-card-gallery-item"
+                disabled={openMutation.isPending}
+                key={entry.storedFileName}
+                onClick={() => openMutation.mutate(entry)}
+                type="button"
+              >
+                {entry.thumbJpegBase64 ? (
+                  <img
+                    alt={`${entry.agentName} trading card`}
+                    className="aspect-2/3 w-full rounded-lg border object-cover shadow-sm transition-transform group-hover:scale-[1.02]"
+                    src={`data:image/jpeg;base64,${entry.thumbJpegBase64}`}
+                  />
+                ) : (
+                  <div className="flex aspect-2/3 w-full items-center justify-center rounded-lg border bg-muted/40">
+                    <Sparkles className="h-6 w-6 text-muted-foreground" />
+                  </div>
+                )}
+                <span className="flex items-center gap-1 truncate text-xs text-muted-foreground">
+                  {entry.locked ? <Lock className="h-3 w-3 shrink-0" /> : null}
+                  <span className="truncate">{entry.agentName}</span>
+                </span>
+              </button>
+            ))}
+          </div>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/desktop/src/features/agents/ui/AgentConfigFields.tsx b/desktop/src/features/agents/ui/AgentConfigFields.tsx
index 9f5e21085c..5ddc9cc20b 100644
--- a/desktop/src/features/agents/ui/AgentConfigFields.tsx
+++ b/desktop/src/features/agents/ui/AgentConfigFields.tsx
@@ -32,9 +32,11 @@ import {
 import {
   AUTO_PROVIDER_DROPDOWN_VALUE,
   BLOCK_BUILD_HIDDEN_PROVIDER_IDS,
+  CARD_MINT_KEY_ANNOTATIONS,
   CUSTOM_PROVIDER_DROPDOWN_VALUE,
   getPersonaProviderOptions,
   getProviderApiKeyEnvVar,
+  getProviderApiKeyLabel,
   runtimeSupportsLlmProviderSelection,
 } from "@/features/agents/ui/agentConfigOptions";
 import {
@@ -55,6 +57,7 @@ import {
 } from "@/features/agents/ui/buzzAgentModelTuningFields";
 import { SettingsOptionGroup } from "@/features/settings/ui/SettingsOptionGroup";
 import { AdvancedRequiredBadge } from "./AdvancedRequiredBadge";
+import { CardMintKeyCue } from "./CardMintKeyCue";
 import { getGlobalAgentCredentialState } from "./globalAgentCredentialState";
 
 export const EMPTY_GLOBAL_CONFIG: GlobalAgentConfig = {
@@ -75,7 +78,6 @@ const PROGRESSIVE_FIELDS_TRANSITION = {
   duration: 0.22,
   ease: [0.23, 1, 0.32, 1],
 } as const;
-
 type AgentConfigDisclosure =
   | "full"
   | "onboarding-essential"
@@ -86,13 +88,9 @@ type AgentConfigDisclosure =
 // - auto-select a valid model when the provider changes
 // - keep the model select usable during discovery
 // - preserve credential env vars across provider switches (the abandoned
-//   provider's key stays in env_vars — visible/deletable under Advanced —
-//   so flipping back never loses a typed key; spawned agents may therefore
-//   see credentials for providers they don't use)
+//   provider's key stays in env_vars — visible/deletable under Advanced)
 // - require a provider before model/effort are editable (no saveable
-//   invalid state — design principle #4). Note: legacy configs saved with
-//   a model but no provider are cleared by the pre-existing orphan-model
-//   effect on next edit — deliberate data healing, documented in PR.
+//   invalid state — design principle #4)
 const autoSelectModelOnProviderChange = true;
 const disableModelSelectDuringDiscovery = false;
 const preserveCredentialEnvVarsOnProviderChange = true;
@@ -748,6 +746,7 @@ export function AgentConfigFields({
         <div className={blockClassName}>
           <PersonaProviderApiKeyField
             disabled={false}
+            envVarName={apiKeyEnvVar}
             inheritedLabel={
               apiKeyFileSatisfied
                 ? "Set in runtime config"
@@ -755,11 +754,7 @@ export function AgentConfigFields({
             }
             isInherited={apiKeyInherited}
             isRequired={!apiKeyInherited && apiKeyValue.length === 0}
-            label={
-              effectiveProvider === "anthropic"
-                ? "Anthropic API Key"
-                : "OpenAI API Key"
-            }
+            label={getProviderApiKeyLabel(effectiveProvider) ?? "API Key"}
             onValueChange={(value) =>
               onConfigChange({
                 ...config,
@@ -872,6 +867,7 @@ export function AgentConfigFields({
 
       {showAdvancedFields ? (
         <div className={cn(blockClassName, "space-y-3")}>
+          <CardMintKeyCue envVars={config.env_vars} />
           <button
             aria-expanded={advancedOpen}
             className={cn(
@@ -915,6 +911,7 @@ export function AgentConfigFields({
                     hiddenKeys={apiKeyEnvVar ? [apiKeyEnvVar] : []}
                     inheritedRows={bakedGenericRows}
                     inheritedRowsLabel="build"
+                    keyAnnotations={CARD_MINT_KEY_ANNOTATIONS}
                     label="Environment variables"
                     onChange={handleEnvVarsChange}
                     requiredKeys={advancedRequiredEnvKeys}
@@ -933,6 +930,7 @@ export function AgentConfigFields({
               hiddenKeys={apiKeyEnvVar ? [apiKeyEnvVar] : []}
               inheritedRows={bakedGenericRows}
               inheritedRowsLabel="build"
+              keyAnnotations={CARD_MINT_KEY_ANNOTATIONS}
               label="Environment variables"
               onChange={handleEnvVarsChange}
               requiredKeys={advancedRequiredEnvKeys}
diff --git a/desktop/src/features/agents/ui/AgentConfigPanel.tsx b/desktop/src/features/agents/ui/AgentConfigPanel.tsx
index 3236b4d808..67c544257c 100644
--- a/desktop/src/features/agents/ui/AgentConfigPanel.tsx
+++ b/desktop/src/features/agents/ui/AgentConfigPanel.tsx
@@ -137,6 +137,8 @@ function provenanceSentence(
       return "From ACP session";
     case "globalDefault":
       return "Inherited from global defaults";
+    case "harnessDefault":
+      return "Inherited from harness definition";
   }
 }
 
diff --git a/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx b/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx
index 5425131448..1916b57069 100644
--- a/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx
+++ b/desktop/src/features/agents/ui/AgentDefinitionDialog.tsx
@@ -32,6 +32,7 @@ import {
   personaBehaviorDraftValid,
 } from "./personaBehaviorDraft";
 import {
+  ADVANCED_FIELDS_MOTION_TRANSITION,
   AUTO_MODEL_DROPDOWN_VALUE,
   AUTO_PROVIDER_DROPDOWN_VALUE,
   BLOCK_BUILD_HIDDEN_PROVIDER_IDS,
@@ -42,6 +43,7 @@ import {
   getDefaultPersonaRuntime,
   getPersonaModelOptions,
   getPersonaProviderOptions,
+  getProviderApiKeyLabel,
   getRuntimePersonaModelOptions,
   NO_RUNTIME_DROPDOWN_VALUE,
   runtimeSupportsLlmProviderSelection,
@@ -117,11 +119,6 @@ export type AgentDefinitionSubmitOptions = {
   publishCatalogUpdates: boolean;
 };
 
-const ADVANCED_FIELDS_MOTION_TRANSITION = {
-  duration: 0.18,
-  ease: [0.23, 1, 0.32, 1],
-} as const;
-
 export function AgentDefinitionDialog({
   open,
   title,
@@ -907,14 +904,11 @@ export function AgentDefinitionDialog({
               topLevelSecretEnvVar ? (
                 <PersonaProviderApiKeyField
                   disabled={isPending}
+                  envVarName={topLevelSecretEnvVar}
                   isInherited={apiKeyIsInherited}
                   inheritedLabel={apiKeyInheritedLabel}
                   isRequired={apiKeyIsRequired}
-                  label={
-                    effectiveProvider === "anthropic"
-                      ? "Anthropic API key"
-                      : "OpenAI API key"
-                  }
+                  label={getProviderApiKeyLabel(effectiveProvider) ?? "API key"}
                   onValueChange={(next) => {
                     setEnvVars((prev) => ({
                       ...prev,
diff --git a/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx b/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx
index 79d1e9a790..d717d773e8 100644
--- a/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx
+++ b/desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx
@@ -26,6 +26,7 @@ import { Input } from "@/shared/ui/input";
 import { setManagedAgentAutoRestart } from "@/shared/api/tauriManagedAgents";
 import { EditAgentAdvancedFields } from "./EditAgentAdvancedFields";
 import {
+  ADVANCED_FIELDS_MOTION_TRANSITION,
   AUTO_PROVIDER_DROPDOWN_VALUE,
   BLOCK_BUILD_HIDDEN_PROVIDER_IDS,
   CUSTOM_PROVIDER_DROPDOWN_VALUE,
@@ -65,6 +66,7 @@ import { AgentCreationPreview } from "./AgentCreationPreview";
 import type { EnvVarsValue } from "./EnvVarsEditor";
 import { useRequiredCredentialState } from "./useRequiredCredentialState";
 import { CreateAgentRespondToField } from "./RespondToField";
+import { RunOnSummarySection } from "./RunOnSummarySection";
 import { PersonaDropdownField } from "./PersonaDropdownField";
 import {
   MODEL_DISCOVERY_LOADING_VALUE,
@@ -75,7 +77,10 @@ import {
   getBakedModelInheritLabel,
   getBakedProviderInheritLabel,
 } from "./bakedEnvHelpers";
-import { getProviderApiKeyEnvVar } from "./agentConfigOptions";
+import {
+  getProviderApiKeyEnvVar,
+  getProviderApiKeyLabel,
+} from "./agentConfigOptions";
 import { useAgentDialogDefaults } from "./useAgentDialogDefaults";
 import { AgentAiDefaultsNotice } from "./AgentAiDefaults";
 import { AgentDefaultsDialog } from "./AgentDefaultsDialog";
@@ -90,11 +95,6 @@ import {
   usePendingHarnessSelection,
 } from "./addCustomHarness";
 
-const ADVANCED_FIELDS_MOTION_TRANSITION = {
-  duration: 0.18,
-  ease: [0.23, 1, 0.32, 1],
-} as const;
-
 export function AgentInstanceEditDialog({
   agent,
   initialFocus,
@@ -946,6 +946,8 @@ export function AgentInstanceEditDialog({
               variant="persona"
             />
 
+            <RunOnSummarySection backend={agent.backend} />
+
             {/* Provider (runtime) */}
             <div className="space-y-1.5">
               <label
@@ -1061,14 +1063,11 @@ export function AgentInstanceEditDialog({
             {llmProviderFieldVisible && topLevelSecretEnvVar ? (
               <PersonaProviderApiKeyField
                 disabled={updateMutation.isPending}
+                envVarName={topLevelSecretEnvVar}
                 isInherited={apiKeyIsInherited}
                 inheritedLabel={apiKeyInheritedLabel}
                 isRequired={apiKeyIsRequired}
-                label={
-                  effectiveProvider === "anthropic"
-                    ? "Anthropic API Key"
-                    : "OpenAI API Key"
-                }
+                label={getProviderApiKeyLabel(effectiveProvider) ?? "API Key"}
                 onValueChange={(next) => {
                   setEnvVars((prev) => ({
                     ...prev,
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/CardMintKeyCue.tsx b/desktop/src/features/agents/ui/CardMintKeyCue.tsx
new file mode 100644
index 0000000000..5239c9e66c
--- /dev/null
+++ b/desktop/src/features/agents/ui/CardMintKeyCue.tsx
@@ -0,0 +1,29 @@
+/**
+ * Always-visible cue shown in Agent Defaults when a global `OPENAI_API_KEY`
+ * row exists (nonblank).  The Advanced section is collapsed by default, so
+ * the `keyAnnotations` hint on that row is invisible until the user opens it
+ * — this cue bridges the gap by surfacing the information at the decision
+ * point.
+ *
+ * Renders nothing when `OPENAI_API_KEY` is absent or blank.
+ */
+export function CardMintKeyCue({
+  envVars,
+}: {
+  envVars: Record<string, string>;
+}) {
+  const isSet =
+    "OPENAI_API_KEY" in envVars &&
+    (envVars.OPENAI_API_KEY ?? "").trim().length > 0;
+  if (!isSet) return null;
+
+  return (
+    <p
+      className="text-xs text-muted-foreground"
+      data-testid="card-mint-key-cue"
+    >
+      Card-minting key <span className="font-mono">OPENAI_API_KEY</span> is set
+      under Advanced → Environment variables.
+    </p>
+  );
+}
diff --git a/desktop/src/features/agents/ui/EditAgentAdvancedFields.tsx b/desktop/src/features/agents/ui/EditAgentAdvancedFields.tsx
index 8412792a2c..c8e21cd6fa 100644
--- a/desktop/src/features/agents/ui/EditAgentAdvancedFields.tsx
+++ b/desktop/src/features/agents/ui/EditAgentAdvancedFields.tsx
@@ -3,6 +3,7 @@ import { Input } from "@/shared/ui/input";
 import { Textarea } from "@/shared/ui/textarea";
 import { EnvVarsEditor, type EnvVarsValue } from "./EnvVarsEditor";
 import {
+  CARD_MINT_KEY_ANNOTATIONS,
   PERSONA_FIELD_CONTROL_CLASS,
   PERSONA_FIELD_SHELL_CLASS,
   PERSONA_LABEL_OPTIONAL_CLASS,
@@ -247,6 +248,7 @@ export function EditAgentAdvancedFields({
         helperText="Per-agent env vars. Override the template's vars on collision."
         inheritedFrom={inheritedEnvVars}
         inheritedLabel="template / global defaults"
+        keyAnnotations={CARD_MINT_KEY_ANNOTATIONS}
         onChange={onEnvVarsChange}
         requiredKeys={requiredEnvKeys}
         value={envVars}
diff --git a/desktop/src/features/agents/ui/EnvVarsEditor.test.mjs b/desktop/src/features/agents/ui/EnvVarsEditor.test.mjs
index b726851f69..6578428d7d 100644
--- a/desktop/src/features/agents/ui/EnvVarsEditor.test.mjs
+++ b/desktop/src/features/agents/ui/EnvVarsEditor.test.mjs
@@ -523,3 +523,97 @@ test("getBakedProviderInheritLabel_empty_options_falls_back_to_raw_id", () => {
     "empty options table must fall back to raw id",
   );
 });
+
+// ── keyAnnotations — annotation lookup invariants ─────────────────────────────
+//
+// `keyAnnotations` is a pass-through prop: the renderer does `keyAnnotations?.[key]`.
+// The invariant worth pinning is that the prop contract is respected at the
+// data level — an annotation for one key does NOT bleed into another key.
+// (Rendering itself is trivially conditional; no logic to extract.)
+
+test("keyAnnotations_present_key_has_annotation", () => {
+  const annotations = {
+    OPENAI_API_KEY: "Used for minting agent trading cards",
+  };
+  assert.equal(
+    annotations.OPENAI_API_KEY,
+    "Used for minting agent trading cards",
+  );
+});
+
+test("keyAnnotations_absent_key_is_undefined", () => {
+  const annotations = {
+    OPENAI_API_KEY: "Used for minting agent trading cards",
+  };
+  assert.equal(annotations.ANTHROPIC_API_KEY, undefined);
+});
+
+test("keyAnnotations_empty_map_has_no_annotations", () => {
+  const annotations = {};
+  assert.equal(annotations.OPENAI_API_KEY, undefined);
+});
+
+test("keyAnnotations_only_matching_key_gets_annotation", () => {
+  // Verifies the per-key lookup is not accidentally global.
+  const annotations = { OPENAI_API_KEY: "card minting" };
+  const keys = ["OPENAI_API_KEY", "ANTHROPIC_API_KEY", "FOO"];
+  const results = keys.map((k) => annotations[k] ?? null);
+  assert.deepEqual(results, ["card minting", null, null]);
+});
+
+// ── keyAnnotations render — annotation appears only on matching row ─────────
+//
+// renderToStaticMarkup exercises the real JSX path:
+//   {keyAnnotations?.[row.key] ? <p ...>{annotation}</p> : null}
+// This confirms the prop is plumbed through to the DOM correctly and that
+// annotation text is scoped to its matching row.
+
+import React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { EnvVarsEditor } from "./EnvVarsEditor.tsx";
+
+test("keyAnnotations_annotation_present_only_on_matching_row", () => {
+  const annotations = {
+    OPENAI_API_KEY: "Used for minting agent trading cards",
+  };
+  const html = renderToStaticMarkup(
+    React.createElement(EnvVarsEditor, {
+      disabled: false,
+      fileSatisfiedKeys: [],
+      hiddenKeys: [],
+      keyAnnotations: annotations,
+      onChange: () => {},
+      requiredKeys: [],
+      value: { OPENAI_API_KEY: "sk-placeholder", ANTHROPIC_API_KEY: "sk-ant" },
+    }),
+  );
+  assert.ok(
+    html.includes("Used for minting agent trading cards"),
+    "annotation must appear in rendered output for OPENAI_API_KEY row",
+  );
+  // The annotation must not bleed to other rows — check that it appears only once.
+  const count = (html.match(/Used for minting agent trading cards/g) ?? [])
+    .length;
+  assert.equal(count, 1, "annotation must appear exactly once");
+});
+
+test("keyAnnotations_annotation_absent_for_non_matching_rows", () => {
+  const annotations = {
+    OPENAI_API_KEY: "Used for minting agent trading cards",
+  };
+  const html = renderToStaticMarkup(
+    React.createElement(EnvVarsEditor, {
+      disabled: false,
+      fileSatisfiedKeys: [],
+      hiddenKeys: [],
+      keyAnnotations: annotations,
+      onChange: () => {},
+      requiredKeys: [],
+      value: { ANTHROPIC_API_KEY: "sk-ant", MY_VAR: "foo" },
+    }),
+  );
+  assert.ok(
+    !html.includes("Used for minting agent trading cards"),
+    "annotation must not appear when its key is not in the env map",
+  );
+});
diff --git a/desktop/src/features/agents/ui/EnvVarsEditor.tsx b/desktop/src/features/agents/ui/EnvVarsEditor.tsx
index 18bbf68337..91e5b07622 100644
--- a/desktop/src/features/agents/ui/EnvVarsEditor.tsx
+++ b/desktop/src/features/agents/ui/EnvVarsEditor.tsx
@@ -165,6 +165,14 @@ type EnvVarsEditorProps = {
   inheritedRows?: readonly InheritedEnvRow[];
   /** Label for the inherited-row tag (e.g. "build"). Defaults to "build". */
   inheritedRowsLabel?: string;
+  /**
+   * Optional muted one-line annotation for specific env var keys. Rendered
+   * below any row whose key appears in this map — required rows, user rows,
+   * and user rows whose key is typed mid-edit. Intended for contextual hints
+   * like `{ OPENAI_API_KEY: "Used for minting agent trading cards" }` that
+   * help users distinguish two keys with similar names.
+   */
+  keyAnnotations?: Readonly<Record<string, string>>;
 };
 
 type Row = { id: string; key: string; value: string };
@@ -191,6 +199,7 @@ export function EnvVarsEditor({
   focusKey,
   inheritedRows = [],
   inheritedRowsLabel = "build",
+  keyAnnotations,
 }: EnvVarsEditorProps) {
   // Keys that render as their own special rows (required amber rows or
   // file-satisfied read-only rows). These must NEVER enter `rows` state —
@@ -406,6 +415,14 @@ export function EnvVarsEditor({
                   </p>
                 );
               })()}
+              {keyAnnotations?.[key] ? (
+                <p
+                  className="ml-1 text-xs text-muted-foreground"
+                  data-testid="env-vars-key-annotation"
+                >
+                  {keyAnnotations[key]}
+                </p>
+              ) : null}
             </div>
           );
         })}
@@ -596,6 +613,14 @@ export function EnvVarsEditor({
                   </p>
                 );
               })()}
+              {row.key.length > 0 && keyAnnotations?.[row.key] ? (
+                <p
+                  className="ml-1 text-xs text-muted-foreground"
+                  data-testid="env-vars-key-annotation"
+                >
+                  {keyAnnotations[row.key]}
+                </p>
+              ) : null}
             </div>
           );
         })}
diff --git a/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx b/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx
index 99cf3e97a8..01485dd9eb 100644
--- a/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx
+++ b/desktop/src/features/agents/ui/PersonaAdvancedFields.tsx
@@ -6,6 +6,7 @@ import type { PersonaBehaviorDraft } from "./personaBehaviorDraft";
 import { isBuzzAgentRuntime } from "./buzzAgentConfig";
 import { BuzzAgentModelTuningFields } from "./buzzAgentModelTuningFields";
 import {
+  CARD_MINT_KEY_ANNOTATIONS,
   PERSONA_FIELD_CONTROL_CLASS,
   PERSONA_FIELD_SHELL_CLASS,
   PERSONA_LABEL_OPTIONAL_CLASS,
@@ -142,6 +143,7 @@ export function PersonaAdvancedFields({
         disabled={disabled}
         fileSatisfiedKeys={fileSatisfiedEnvKeys}
         hiddenKeys={hiddenEnvKeys}
+        keyAnnotations={CARD_MINT_KEY_ANNOTATIONS}
         onChange={onEnvVarsChange}
         requiredKeys={requiredEnvKeys}
         value={envVars}
diff --git a/desktop/src/features/agents/ui/PersonaProviderApiKeyField.test.mjs b/desktop/src/features/agents/ui/PersonaProviderApiKeyField.test.mjs
new file mode 100644
index 0000000000..62a6ff416c
--- /dev/null
+++ b/desktop/src/features/agents/ui/PersonaProviderApiKeyField.test.mjs
@@ -0,0 +1,170 @@
+/**
+ * Behavioral tests for PersonaProviderApiKeyField.
+ *
+ * Tests the rendering invariants that matter for the disambiguation story:
+ * - semantic label is present in the rendered output
+ * - envVarName hint is rendered when the prop is present
+ * - hint id is wired to the input via aria-describedby
+ * - hint is absent when envVarName is omitted
+ * - two simultaneous instances produce unique IDs (no duplicate-ID collision
+ *   in the nested AgentInstanceEditDialog + AgentDefaultsDialog path)
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+
+import { PersonaProviderApiKeyField } from "./PersonaProviderApiKeyField.tsx";
+
+function makeProps(overrides = {}) {
+  return {
+    disabled: false,
+    isInherited: false,
+    inheritedLabel: "Set in global defaults",
+    isRequired: false,
+    label: "OpenAI Runtime API Key",
+    onValueChange: () => {},
+    value: "",
+    ...overrides,
+  };
+}
+
+/** Extract the value of the first attribute matching `name="..."` in html. */
+function extractAttr(html, attrName) {
+  const re = new RegExp(`${attrName}="([^"]+)"`);
+  const m = re.exec(html);
+  return m ? m[1] : null;
+}
+
+/** Extract ALL values of an attribute from html, in document order. */
+function extractAllAttrs(html, attrName) {
+  const re = new RegExp(`${attrName}="([^"]+)"`, "g");
+  return Array.from(html.matchAll(re), (m) => m[1]);
+}
+
+test("PersonaProviderApiKeyField_renders_semantic_label", () => {
+  const html = renderToStaticMarkup(
+    React.createElement(PersonaProviderApiKeyField, makeProps()),
+  );
+  assert.ok(
+    html.includes("OpenAI Runtime API Key"),
+    "semantic label must appear in rendered output",
+  );
+});
+
+test("PersonaProviderApiKeyField_renders_env_var_hint_when_envVarName_present", () => {
+  const html = renderToStaticMarkup(
+    React.createElement(
+      PersonaProviderApiKeyField,
+      makeProps({ envVarName: "OPENAI_COMPAT_API_KEY" }),
+    ),
+  );
+  assert.ok(
+    html.includes("OPENAI_COMPAT_API_KEY"),
+    "env-var hint must appear when envVarName is provided",
+  );
+});
+
+test("PersonaProviderApiKeyField_wires_hint_id_via_aria_describedby", () => {
+  const html = renderToStaticMarkup(
+    React.createElement(
+      PersonaProviderApiKeyField,
+      makeProps({ envVarName: "OPENAI_COMPAT_API_KEY" }),
+    ),
+  );
+  // Extract the dynamically-generated hint id from the rendered paragraph.
+  const hintId = extractAttr(html, "id");
+  assert.ok(hintId, "hint paragraph must have an id");
+  assert.ok(
+    hintId.startsWith("persona-provider-api-key-hint-"),
+    `hint id must follow the expected prefix, got: ${hintId}`,
+  );
+  // The input's aria-describedby must point at the same id.
+  const describedBy = extractAttr(html, "aria-describedby");
+  assert.equal(
+    describedBy,
+    hintId,
+    "input aria-describedby must reference the hint's id",
+  );
+});
+
+test("PersonaProviderApiKeyField_omits_hint_when_envVarName_absent", () => {
+  const html = renderToStaticMarkup(
+    React.createElement(PersonaProviderApiKeyField, makeProps()),
+  );
+  assert.ok(
+    !html.includes("aria-describedby"),
+    "no aria-describedby when envVarName is omitted",
+  );
+  assert.ok(
+    !html.includes("persona-provider-api-key-hint"),
+    "hint id must not appear when envVarName is omitted",
+  );
+});
+
+test("PersonaProviderApiKeyField_two_instances_have_unique_ids_and_each_aria_describedby_resolves_to_own_hint", () => {
+  // Render BOTH instances in a single renderToStaticMarkup call — this
+  // mirrors the real nested-dialog DOM where AgentInstanceEditDialog's
+  // credential field and the nested AgentDefaultsDialog's field are
+  // simultaneously mounted under the same React root. A shared root is what
+  // makes React.useId() guarantee uniqueness; two separate renderToStaticMarkup
+  // calls each reset the counter and would produce the same ID.
+  const combined = renderToStaticMarkup(
+    React.createElement(
+      React.Fragment,
+      null,
+      React.createElement(
+        PersonaProviderApiKeyField,
+        makeProps({
+          label: "Anthropic API Key",
+          envVarName: "ANTHROPIC_API_KEY",
+        }),
+      ),
+      React.createElement(
+        PersonaProviderApiKeyField,
+        makeProps({
+          label: "OpenAI Runtime API Key",
+          envVarName: "OPENAI_COMPAT_API_KEY",
+        }),
+      ),
+    ),
+  );
+
+  // Two hint paragraph ids must be present and distinct.
+  const allHintIds = extractAllAttrs(combined, "id").filter((id) =>
+    id.startsWith("persona-provider-api-key-hint-"),
+  );
+  assert.equal(allHintIds.length, 2, "exactly two hint ids must be present");
+  const [hintIdA, hintIdB] = allHintIds;
+  assert.notEqual(hintIdA, hintIdB, "two instances must not share a hint id");
+
+  // Each input's aria-describedby must match its own hint id (same order).
+  const allDescribedBy = extractAllAttrs(combined, "aria-describedby");
+  assert.equal(
+    allDescribedBy.length,
+    2,
+    "exactly two aria-describedby attributes must be present",
+  );
+  assert.equal(
+    allDescribedBy[0],
+    hintIdA,
+    "instance A: aria-describedby must reference instance A's own hint",
+  );
+  assert.equal(
+    allDescribedBy[1],
+    hintIdB,
+    "instance B: aria-describedby must reference instance B's own hint",
+  );
+
+  // Confirm each instance names its own env var in the rendered output.
+  assert.ok(
+    combined.includes("ANTHROPIC_API_KEY"),
+    "combined output must name ANTHROPIC_API_KEY",
+  );
+  assert.ok(
+    combined.includes("OPENAI_COMPAT_API_KEY"),
+    "combined output must name OPENAI_COMPAT_API_KEY",
+  );
+});
diff --git a/desktop/src/features/agents/ui/PersonaProviderApiKeyField.tsx b/desktop/src/features/agents/ui/PersonaProviderApiKeyField.tsx
index 17f9e2e826..2be1f1c28d 100644
--- a/desktop/src/features/agents/ui/PersonaProviderApiKeyField.tsx
+++ b/desktop/src/features/agents/ui/PersonaProviderApiKeyField.tsx
@@ -25,6 +25,7 @@ import {
  */
 export function PersonaProviderApiKeyField({
   disabled,
+  envVarName,
   isInherited,
   inheritedLabel,
   isRequired,
@@ -33,6 +34,13 @@ export function PersonaProviderApiKeyField({
   value,
 }: {
   disabled: boolean;
+  /**
+   * The backing environment variable name, e.g. `OPENAI_COMPAT_API_KEY`.
+   * Rendered as a monospace hint beneath the label so users can distinguish
+   * this field from other keys with similar names (e.g. `OPENAI_API_KEY`).
+   * When present, the input's `aria-describedby` points at the hint element.
+   */
+  envVarName?: string;
   /** True when the key is satisfied by an inherited layer. */
   isInherited: boolean;
   /** Human-readable source of the inherited value. */
@@ -46,13 +54,22 @@ export function PersonaProviderApiKeyField({
   value: string;
 }) {
   const [showValue, setShowValue] = React.useState(false);
-  const inputId = "persona-provider-api-key";
+  const uid = React.useId();
+  const inputId = `persona-provider-api-key-${uid}`;
+  const hintId = envVarName
+    ? `persona-provider-api-key-hint-${uid}`
+    : undefined;
 
   return (
     <div className="space-y-1.5">
       <RequiredFieldLabel htmlFor={inputId} isRequired={isRequired}>
         {label}
       </RequiredFieldLabel>
+      {envVarName ? (
+        <p className="text-xs text-muted-foreground font-mono" id={hintId}>
+          {envVarName}
+        </p>
+      ) : null}
       <div
         className={cn(
           "flex min-h-11 items-center gap-2 px-3",
@@ -60,6 +77,7 @@ export function PersonaProviderApiKeyField({
         )}
       >
         <Input
+          aria-describedby={hintId}
           autoComplete="off"
           className={cn(
             "h-8 flex-1 px-0 py-0 leading-6",
diff --git a/desktop/src/features/agents/ui/ProviderConfigFields.test.mjs b/desktop/src/features/agents/ui/ProviderConfigFields.test.mjs
new file mode 100644
index 0000000000..0dfd80d444
--- /dev/null
+++ b/desktop/src/features/agents/ui/ProviderConfigFields.test.mjs
@@ -0,0 +1,31 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { coerceConfigValues } from "./ProviderConfigFields.tsx";
+
+const schema = {
+  properties: {
+    inactivity_seconds: { type: "integer" },
+    threshold: { type: "number" },
+    label: { type: "string" },
+  },
+};
+
+describe("coerceConfigValues", () => {
+  it("omits cleared numeric fields without losing explicit zero", () => {
+    assert.deepEqual(
+      coerceConfigValues(
+        { inactivity_seconds: "", threshold: "0", label: "" },
+        schema,
+      ),
+      { threshold: 0, label: "" },
+    );
+  });
+
+  it("preserves nonempty invalid numeric input for provider validation", () => {
+    assert.deepEqual(
+      coerceConfigValues({ inactivity_seconds: "not-a-number" }, schema),
+      { inactivity_seconds: "not-a-number" },
+    );
+  });
+});
diff --git a/desktop/src/features/agents/ui/ProviderConfigFields.tsx b/desktop/src/features/agents/ui/ProviderConfigFields.tsx
index e922dd9c1a..031b0b7277 100644
--- a/desktop/src/features/agents/ui/ProviderConfigFields.tsx
+++ b/desktop/src/features/agents/ui/ProviderConfigFields.tsx
@@ -14,7 +14,8 @@ export function coerceConfigValues(
   for (const [key, value] of Object.entries(config)) {
     const prop = properties[key] as Record<string, unknown> | undefined;
     const schemaType = prop?.type;
-    if ((schemaType === "integer" || schemaType === "number") && value !== "") {
+    if (schemaType === "integer" || schemaType === "number") {
+      if (value === "") continue;
       const num = Number(value);
       result[key] = Number.isNaN(num) ? value : num;
     } else if (schemaType === "boolean") {
diff --git a/desktop/src/features/agents/ui/RunOnSummarySection.tsx b/desktop/src/features/agents/ui/RunOnSummarySection.tsx
new file mode 100644
index 0000000000..d3d2f30381
--- /dev/null
+++ b/desktop/src/features/agents/ui/RunOnSummarySection.tsx
@@ -0,0 +1,73 @@
+import type { ManagedAgentBackend } from "@/shared/api/types";
+
+import { summarizeRunOn } from "./runOnSummary";
+
+/**
+ * Read-only "Run on" summary for the edit-agent dialog.
+ *
+ * Read-only on purpose: `UpdateManagedAgentRequest` has no backend field —
+ * where an agent runs is fixed at creation (a provider-backed agent's
+ * deployment holds its private key; there is no migrate operation). This
+ * section shows the *saved* provider config from the record, without probing
+ * the provider binary: an edit dialog must not do executable work as a side
+ * effect, and a live probe would show today's schema defaults instead of
+ * what this agent actually deployed with.
+ *
+ * Named "Run on" (matching the create flow) rather than "Provider" because
+ * this dialog already uses "Provider" for the ACP harness selector.
+ */
+export function RunOnSummarySection({
+  backend,
+}: {
+  backend: ManagedAgentBackend;
+}) {
+  const summary = summarizeRunOn(backend);
+
+  return (
+    <div className="space-y-1.5" data-testid="edit-agent-run-on">
+      <span className="text-sm font-medium text-foreground">Run on</span>
+      {summary.location === "local" ? (
+        <p
+          className="text-sm text-muted-foreground"
+          data-testid="edit-agent-run-on-location"
+        >
+          This computer
+        </p>
+      ) : (
+        <div className="space-y-2 rounded-2xl border border-border bg-muted/30 px-4 py-3">
+          <p
+            className="text-sm font-medium"
+            data-testid="edit-agent-run-on-location"
+          >
+            {summary.providerId}
+          </p>
+          {summary.rows.length > 0 ? (
+            <dl className="space-y-1">
+              {summary.rows.map((row) => (
+                <div
+                  className="flex flex-wrap items-baseline gap-x-3 gap-y-0.5"
+                  data-testid={`edit-agent-run-on-${row.key}`}
+                  key={row.key}
+                >
+                  <dt className="text-xs text-muted-foreground">{row.label}</dt>
+                  <dd className="min-w-0 break-all font-mono text-xs text-foreground">
+                    {row.value}
+                  </dd>
+                </div>
+              ))}
+            </dl>
+          ) : (
+            <p className="text-xs text-muted-foreground">
+              No saved settings — the provider applies its defaults.
+            </p>
+          )}
+        </div>
+      )}
+      <p className="text-xs text-muted-foreground">
+        These are the settings saved when the agent was created. Where an agent
+        runs can&apos;t be changed afterwards — create a new agent to run
+        somewhere else.
+      </p>
+    </div>
+  );
+}
diff --git a/desktop/src/features/agents/ui/WhereToRunSection.tsx b/desktop/src/features/agents/ui/WhereToRunSection.tsx
index f068eceec8..ee9ec37132 100644
--- a/desktop/src/features/agents/ui/WhereToRunSection.tsx
+++ b/desktop/src/features/agents/ui/WhereToRunSection.tsx
@@ -5,7 +5,11 @@ import { useBackendProvidersQuery } from "@/features/agents/hooks";
 import { probeBackendProvider } from "@/shared/api/tauri";
 
 import { ProviderConfigFields } from "./ProviderConfigFields";
-import { emptyWhereToRunDraft, type WhereToRunDraft } from "./whereToRunIntent";
+import {
+  applyProbeResult,
+  emptyWhereToRunDraft,
+  type WhereToRunDraft,
+} from "./whereToRunIntent";
 
 /** Optional remote-backend selector. Buzz shared compute is an LLM provider, not a run destination. */
 export function WhereToRunSection({
@@ -26,32 +30,37 @@ export function WhereToRunSection({
     [backendProviders, draft.runOn],
   );
 
+  // Latest-state seam for probe resolution: an Effect Event always sees the
+  // draft as it is *now*. Without this, the probe promise closes over the
+  // draft from probe start, and anything typed while the probe was in flight
+  // gets thrown away when it resolves (a second, subtler Typewriter Eraser).
+  const applyProbe = React.useEffectEvent(
+    (result: Awaited<ReturnType<typeof probeBackendProvider>>) => {
+      onDraftChange(applyProbeResult(draft, result));
+    },
+  );
+
+  // Probe once per provider *selection*, keyed on the provider's stable
+  // path — never on the draft. Depending on the draft made every keystroke
+  // refire the probe, and each resolution reset providerConfig to schema
+  // defaults, which erased what the user was typing (the Typewriter Eraser)
+  // and spawned the provider binary in a loop for as long as the dialog was
+  // open. Keying on the path (not the provider object) also keeps a
+  // providers-query refresh from reprobing an unchanged selection.
+  const selectedBinaryPath = isProviderMode
+    ? (selectedBackendProvider?.binaryPath ?? null)
+    : null;
   React.useEffect(() => {
-    if (!isProviderMode || !selectedBackendProvider) {
+    if (!selectedBinaryPath) {
       setProbeError(null);
       return;
     }
     let cancelled = false;
     setProbeError(null);
-    void probeBackendProvider(selectedBackendProvider.binaryPath)
+    void probeBackendProvider(selectedBinaryPath)
       .then((result) => {
         if (cancelled) return;
-        const defaults: Record<string, string> = {};
-        const properties =
-          (result.config_schema as Record<string, unknown> | undefined)
-            ?.properties ?? {};
-        for (const [key, property] of Object.entries(properties) as [
-          string,
-          Record<string, unknown>,
-        ][]) {
-          if (property.default != null)
-            defaults[key] = String(property.default);
-        }
-        onDraftChange({
-          ...draft,
-          probedProvider: result,
-          providerConfig: defaults,
-        });
+        applyProbe(result);
       })
       .catch((error: unknown) => {
         if (!cancelled) {
@@ -61,7 +70,7 @@ export function WhereToRunSection({
     return () => {
       cancelled = true;
     };
-  }, [draft, isProviderMode, onDraftChange, selectedBackendProvider]);
+  }, [selectedBinaryPath]);
 
   if (backendProviders.length === 0) return null;
 
diff --git a/desktop/src/features/agents/ui/agentConfigOptions.test.mjs b/desktop/src/features/agents/ui/agentConfigOptions.test.mjs
index d0690cefc3..eb24d88084 100644
--- a/desktop/src/features/agents/ui/agentConfigOptions.test.mjs
+++ b/desktop/src/features/agents/ui/agentConfigOptions.test.mjs
@@ -5,6 +5,7 @@ import {
   getDefaultPersonaRuntime,
   getPersonaModelOptions,
   getPersonaProviderOptions,
+  getProviderApiKeyLabel,
   resetConfigForHarnessChange,
   runtimeSupportsLlmProviderSelection,
 } from "./agentConfigOptions.tsx";
@@ -246,3 +247,50 @@ test("formatModelDiscoveryErrorStatus returns a non-null status for runtime unav
     assert.ok(typeof status?.tone === "string", "status has a tone");
   }
 });
+
+// ── getProviderApiKeyLabel — provider-accurate credential field labels ────────
+//
+// Each provider with a secretEnvVar must have a distinct label. The helper
+// is the single source of truth used by all three credential field surfaces;
+// if it regresses the field labels diverge silently and the OpenRouter / compat
+// mislabeling recurs.
+
+test("getProviderApiKeyLabel_anthropic_returns_anthropic_label", () => {
+  assert.equal(getProviderApiKeyLabel("anthropic"), "Anthropic API Key");
+});
+
+test("getProviderApiKeyLabel_openai_returns_openai_runtime_label", () => {
+  assert.equal(getProviderApiKeyLabel("openai"), "OpenAI Runtime API Key");
+});
+
+test("getProviderApiKeyLabel_openai_compat_returns_distinct_label", () => {
+  // openai and openai-compat must have distinct labels — both use
+  // OPENAI_COMPAT_API_KEY but carry different semantic identities.
+  assert.equal(
+    getProviderApiKeyLabel("openai-compat"),
+    "OpenAI-compatible Runtime API Key",
+  );
+});
+
+test("getProviderApiKeyLabel_openrouter_returns_openrouter_label", () => {
+  // Key fix: OpenRouter was mislabeled "OpenAI API Key" before this change.
+  assert.equal(getProviderApiKeyLabel("openrouter"), "OpenRouter API Key");
+});
+
+test("getProviderApiKeyLabel_databricks_returns_null", () => {
+  // Databricks uses OAuth PKCE — no typed-secret label.
+  assert.equal(getProviderApiKeyLabel("databricks"), null);
+});
+
+test("getProviderApiKeyLabel_databricks_v2_returns_null", () => {
+  assert.equal(getProviderApiKeyLabel("databricks_v2"), null);
+});
+
+test("getProviderApiKeyLabel_unknown_provider_returns_null", () => {
+  assert.equal(getProviderApiKeyLabel("some-unknown-provider"), null);
+});
+
+test("getProviderApiKeyLabel_provider_id_trimmed_and_lowercased", () => {
+  // Mirrors getProviderApiKeyEnvVar normalisation behaviour.
+  assert.equal(getProviderApiKeyLabel(" Anthropic "), "Anthropic API Key");
+});
diff --git a/desktop/src/features/agents/ui/agentConfigOptions.tsx b/desktop/src/features/agents/ui/agentConfigOptions.tsx
index d51c970f29..5c515a0507 100644
--- a/desktop/src/features/agents/ui/agentConfigOptions.tsx
+++ b/desktop/src/features/agents/ui/agentConfigOptions.tsx
@@ -30,6 +30,12 @@ export const PERSONA_FIELD_CONTROL_CLASS =
 export const PERSONA_LABEL_OPTIONAL_CLASS =
   "ml-1 text-xs font-normal text-muted-foreground/50";
 
+/** Shared advanced-fields expand/collapse easing for the agent dialogs. */
+export const ADVANCED_FIELDS_MOTION_TRANSITION = {
+  duration: 0.18,
+  ease: [0.23, 1, 0.32, 1],
+} as const;
+
 export const AUTO_MODEL_DROPDOWN_VALUE = "__auto_model__";
 export const CUSTOM_MODEL_DROPDOWN_VALUE = "__custom_model__";
 export const AUTO_PROVIDER_DROPDOWN_VALUE = "__auto_provider__";
@@ -63,19 +69,30 @@ export type PersonaDropdownOption = {
  *
  * `requiredEnvKeys`: keys that must be present in the agent's effective env for
  *   the provider to work (surfaced as amber required rows in EnvVarsEditor).
- * `secretEnvVar`: the one env key that holds a user-typed secret (API key).
- *   Only set for providers where the credential is a plaintext secret the user
- *   pastes in. Cleared automatically when the user switches away from the
- *   provider. Databricks uses OAuth PKCE (no typed secret), so it has no
- *   secretEnvVar.
+ * `secretEnvVar` + `apiKeyLabel`: paired — either both are present or neither
+ *   is. `secretEnvVar` is the env key holding the user-typed secret; clearing
+ *   it when the user switches providers ensures no orphaned credentials remain.
+ *   Databricks uses OAuth PKCE (no typed secret), so it carries neither field.
+ *   `apiKeyLabel` is the human-readable label shown in the credential field;
+ *   derived by `getProviderApiKeyLabel` — single source of truth for all UI
+ *   surfaces so they never drift.
  *
  * Mirrors the Rust `readiness::buzz_agent_requirements` /
  * `readiness::goose_requirements` logic — keep in sync.
  */
-export type ProviderCredentialConfig = {
-  requiredEnvKeys: readonly string[];
-  secretEnvVar?: string;
-};
+export type ProviderCredentialConfig =
+  | {
+      requiredEnvKeys: readonly string[];
+      secretEnvVar?: undefined;
+      apiKeyLabel?: undefined;
+    }
+  | {
+      requiredEnvKeys: readonly string[];
+      /** The env key holding the user-typed API secret. */
+      secretEnvVar: string;
+      /** Display label for the credential input field, e.g. "Anthropic API Key". */
+      apiKeyLabel: string;
+    };
 
 /**
  * Unified provider credential config table.  Single source of truth for both
@@ -87,20 +104,23 @@ const PROVIDER_CREDENTIAL_CONFIG: Partial<
   anthropic: {
     requiredEnvKeys: ["ANTHROPIC_API_KEY"],
     secretEnvVar: "ANTHROPIC_API_KEY",
+    apiKeyLabel: "Anthropic API Key",
   },
   openai: {
     requiredEnvKeys: ["OPENAI_COMPAT_API_KEY"],
     secretEnvVar: "OPENAI_COMPAT_API_KEY",
+    apiKeyLabel: "OpenAI Runtime API Key",
   },
   "openai-compat": {
     requiredEnvKeys: ["OPENAI_COMPAT_API_KEY"],
     secretEnvVar: "OPENAI_COMPAT_API_KEY",
+    apiKeyLabel: "OpenAI-compatible Runtime API Key",
   },
   databricks: {
     // DATABRICKS_TOKEN is NOT required — OAuth PKCE is the normal path.
     requiredEnvKeys: ["DATABRICKS_HOST"],
-    // No secretEnvVar: DATABRICKS_HOST is a URL, not a secret credential, and
-    // is not cleared on provider switch (unlike API keys).
+    // No secretEnvVar / apiKeyLabel: DATABRICKS_HOST is a URL, not a secret
+    // credential, and is not cleared on provider switch (unlike API keys).
   },
   databricks_v2: {
     // DATABRICKS_TOKEN is NOT required — OAuth PKCE is the normal path.
@@ -113,6 +133,7 @@ const PROVIDER_CREDENTIAL_CONFIG: Partial<
   openrouter: {
     requiredEnvKeys: ["OPENROUTER_API_KEY"],
     secretEnvVar: "OPENROUTER_API_KEY",
+    apiKeyLabel: "OpenRouter API Key",
   },
 };
 
@@ -402,6 +423,31 @@ export function getProviderApiKeyEnvVar(providerId: string): string | null {
   );
 }
 
+/**
+ * Returns the display label for the provider's API key field, if any.
+ * Derived from PROVIDER_CREDENTIAL_CONFIG.apiKeyLabel — single source of truth
+ * for all credential field labels so every surface stays in sync.
+ *
+ * Returns null when the provider has no typed-secret credential (e.g.,
+ * Databricks, which uses OAuth PKCE).
+ */
+export function getProviderApiKeyLabel(providerId: string): string | null {
+  return (
+    PROVIDER_CREDENTIAL_CONFIG[providerId.trim().toLowerCase()]?.apiKeyLabel ??
+    null
+  );
+}
+
+/**
+ * Muted contextual hint for the `OPENAI_API_KEY` row in env editors.
+ * Pass as `keyAnnotations` to every `EnvVarsEditor` that may surface this key
+ * (Agent Defaults, agent edit dialog, persona definition dialog).  Exported
+ * so the constant is defined once and never duplicated across surfaces.
+ */
+export const CARD_MINT_KEY_ANNOTATIONS: Readonly<Record<string, string>> = {
+  OPENAI_API_KEY: "Used for minting agent trading cards",
+};
+
 export function shouldClearKnownModelForSelectionScope({
   model,
   provider,
diff --git a/desktop/src/features/agents/ui/agentSessionTranscript.test.mjs b/desktop/src/features/agents/ui/agentSessionTranscript.test.mjs
index cc6f0467d6..b4a139eb0e 100644
--- a/desktop/src/features/agents/ui/agentSessionTranscript.test.mjs
+++ b/desktop/src/features/agents/ui/agentSessionTranscript.test.mjs
@@ -1879,3 +1879,201 @@ test("buildTranscript five-section system prompt card is standalone with all sec
     "prompt context must NOT contain system-prompt sections (Base/System/Team Instructions/Core Memory/Channel Canvas)",
   );
 });
+
+// --- claude-agent-acp _meta.systemPrompt.append transport ---
+
+test("buildTranscript session/new via _meta.systemPrompt.append produces identical standalone card as bare systemPrompt field", () => {
+  // claude-agent-acp delivers the system prompt at _meta.systemPrompt.append
+  // instead of the bare systemPrompt field. The observer must extract it and
+  // build the identical standalone card (same five sections, same acpSource,
+  // same turnId: null, same placement before the first turn).
+  const CH = "55555555-5555-5555-5555-555555555555";
+  const SYSTEM_PROMPT = [
+    "[Base]",
+    "You are a helpful assistant.",
+    "",
+    "[System]",
+    "Custom persona.",
+    "",
+    "---",
+    "# Team Instructions",
+    "Always tag on handoff.",
+    "",
+    "[Agent Memory \u2014 core]",
+    "I am Duncan.",
+    "",
+    "[Channel Canvas]",
+    "Canvas revision (event ID): a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
+    "Last modified: 2026-07-01T10:00:00Z",
+    "Fetch current content with: buzz canvas get --channel 55555555-5555-5555-5555-555555555555",
+  ].join("\n");
+
+  const makeEvents = (params) => [
+    {
+      seq: 1,
+      timestamp: "2026-07-01T10:00:00.000Z",
+      kind: "turn_started",
+      agentIndex: 0,
+      channelId: CH,
+      sessionId: null,
+      turnId: "turn-1",
+      payload: { source: "channel", triggeringEventIds: [] },
+    },
+    {
+      seq: 2,
+      timestamp: "2026-07-01T10:00:00.100Z",
+      kind: "acp_write",
+      agentIndex: 0,
+      channelId: CH,
+      sessionId: null,
+      turnId: "turn-1",
+      payload: { jsonrpc: "2.0", id: 1, method: "session/new", params },
+    },
+    {
+      seq: 3,
+      timestamp: "2026-07-01T10:00:00.200Z",
+      kind: "session_resolved",
+      agentIndex: 0,
+      channelId: CH,
+      sessionId: "sess-cc",
+      turnId: "turn-1",
+      payload: { sessionId: "sess-cc", isNewSession: true },
+    },
+    {
+      seq: 4,
+      timestamp: "2026-07-01T10:00:01.000Z",
+      kind: "acp_write",
+      agentIndex: 0,
+      channelId: CH,
+      sessionId: "sess-cc",
+      turnId: "turn-1",
+      payload: {
+        jsonrpc: "2.0",
+        id: 2,
+        method: "session/prompt",
+        params: {
+          sessionId: "sess-cc",
+          prompt: [
+            {
+              type: "text",
+              text: `[Buzz event: @mention]\nEvent ID: ${"a".repeat(64)}\nFrom: x (hex: ${"b".repeat(64)})\nContent: hello`,
+            },
+            { type: "text", text: "[Thread context]\nPrior messages here." },
+          ],
+        },
+      },
+    },
+  ];
+
+  // Build transcript from the claude-agent-acp _meta transport.
+  const metaEvents = makeEvents({
+    _meta: { systemPrompt: { append: SYSTEM_PROMPT } },
+  });
+  const metaRaw = buildTranscript(metaEvents);
+  const metaBlocks = buildTranscriptDisplayBlocks(metaRaw);
+  const metaFlat = flattenDisplayBlocks(metaBlocks);
+
+  // Also build from the standard bare-field transport for comparison.
+  const fieldEvents = makeEvents({ systemPrompt: SYSTEM_PROMPT });
+  const fieldRaw = buildTranscript(fieldEvents);
+  const fieldBlocks = buildTranscriptDisplayBlocks(fieldRaw);
+
+  // (a) Both produce exactly one standalone system-prompt single block.
+  const metaSPBlocks = metaBlocks.filter(
+    (b) => b.kind === "single" && b.item?.acpSource === "session/new",
+  );
+  const fieldSPBlocks = fieldBlocks.filter(
+    (b) => b.kind === "single" && b.item?.acpSource === "session/new",
+  );
+  assert.equal(
+    metaSPBlocks.length,
+    1,
+    "_meta: exactly one standalone system-prompt block",
+  );
+  assert.equal(
+    fieldSPBlocks.length,
+    1,
+    "field: exactly one standalone system-prompt block",
+  );
+
+  // (b) Both carry the same five ordered sections.
+  const EXPECTED_TITLES = [
+    "Base",
+    "System",
+    "Team Instructions",
+    "Core Memory",
+    "Channel Canvas",
+  ];
+  const metaTitles = (metaSPBlocks[0].item?.sections ?? []).map((s) => s.title);
+  const fieldTitles = (fieldSPBlocks[0].item?.sections ?? []).map(
+    (s) => s.title,
+  );
+  assert.deepEqual(
+    metaTitles,
+    EXPECTED_TITLES,
+    "_meta: five sections in order",
+  );
+  assert.deepEqual(
+    fieldTitles,
+    EXPECTED_TITLES,
+    "field: five sections in order",
+  );
+
+  // (c) System prompt appears before Prompt context in both display orders.
+  const metaSPIdx = metaFlat.findIndex((i) => i.title === "System prompt");
+  const metaPCIdx = metaFlat.findIndex((i) => i.title === "Prompt context");
+  assert.ok(metaSPIdx !== -1, "_meta: System prompt item present");
+  assert.ok(metaPCIdx !== -1, "_meta: Prompt context item present");
+  assert.ok(
+    metaSPIdx < metaPCIdx,
+    `_meta: System prompt (${metaSPIdx}) must precede Prompt context (${metaPCIdx})`,
+  );
+
+  // (d) The _meta item has turnId: null (standalone, not in a turn bucket).
+  const metaSPRawIdx = metaRaw.findIndex((i) => i.title === "System prompt");
+  assert.equal(
+    metaRaw[metaSPRawIdx]?.turnId ?? null,
+    null,
+    "_meta: system-prompt item must have turnId=null",
+  );
+});
+
+test("buildTranscript session/new bare systemPrompt field takes precedence over _meta.systemPrompt.append", () => {
+  // When both transports are present (non-standard but must not regress),
+  // the standard bare field must win — a reversed ?? would silently use the
+  // wrong text and the card body would differ from the wire source of truth.
+  const CH = "66666666-6666-6666-6666-666666666666";
+  const events = [
+    {
+      seq: 1,
+      timestamp: "2026-07-01T10:00:00.000Z",
+      kind: "acp_write",
+      agentIndex: 0,
+      channelId: CH,
+      sessionId: "sess-both",
+      turnId: "turn-1",
+      payload: {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "session/new",
+        params: {
+          systemPrompt: "[Base]\nWinner.",
+          _meta: { systemPrompt: { append: "[Base]\nLoser." } },
+        },
+      },
+    },
+  ];
+
+  const rawItems = buildTranscript(events);
+  const spItem = rawItems.find((i) => i.title === "System prompt");
+  assert.ok(spItem, "System prompt item must be present");
+  const bodies = (spItem.sections ?? []).map((s) => s.body).join("|");
+  assert.ok(
+    bodies.includes("Winner"),
+    "bare systemPrompt must win over _meta.systemPrompt.append",
+  );
+  assert.ok(
+    !bodies.includes("Loser"),
+    "_meta.systemPrompt.append must not appear when bare field is present",
+  );
+});
diff --git a/desktop/src/features/agents/ui/agentSessionTranscript.ts b/desktop/src/features/agents/ui/agentSessionTranscript.ts
index 962290c6ca..e371bf5fc3 100644
--- a/desktop/src/features/agents/ui/agentSessionTranscript.ts
+++ b/desktop/src/features/agents/ui/agentSessionTranscript.ts
@@ -872,14 +872,14 @@ export function processTranscriptEvent(
     } else if (event.kind === "acp_write" && method === "session/new") {
       // The base + persona prompts ride session/new's systemPrompt, framed by
       // the harness as [Base]/[System]/[Agent Memory — core]/[Channel Canvas].
-      // Each session/new event is keyed by (seq, timestamp) — the same dedup
-      // pair used by observerRelayStore — so distinct sessions each retain
-      // their own system-prompt card even across archive rebuilds where two
-      // processes may emit the same seq. turnId: null keeps it out of turn
-      // buckets; acpSource "session/new" lets the display grouper place it
-      // as a standalone card before the session's first turn.
+      // claude-agent-acp uses _meta.systemPrompt.append instead; both paths
+      // produce the same standalone card (turnId: null, acpSource "session/new");
+      // the bare field takes precedence when both are present.
       const params = asRecord(payload.params);
-      const systemPrompt = asString(params.systemPrompt);
+      const metaPrompt = asString(
+        asRecord(asRecord(params._meta).systemPrompt).append,
+      );
+      const systemPrompt = asString(params.systemPrompt) ?? metaPrompt;
       if (systemPrompt) {
         const sections = parseSystemPromptSections(systemPrompt);
         if (sections.length > 0) {
diff --git a/desktop/src/features/agents/ui/agentSnapshotImportDialog.test.mjs b/desktop/src/features/agents/ui/agentSnapshotImportDialog.test.mjs
index 3ddaf19724..a02bb5a825 100644
--- a/desktop/src/features/agents/ui/agentSnapshotImportDialog.test.mjs
+++ b/desktop/src/features/agents/ui/agentSnapshotImportDialog.test.mjs
@@ -9,7 +9,7 @@ import test from "node:test";
 // memoryErrors strings are carried through to a bounded list element with the
 // correct data-testid. No DOM or test renderer is needed.
 
-import { ResultBody } from "./AgentSnapshotImportDialog.tsx";
+import { PreviewBody, ResultBody } from "./AgentSnapshotImportDialog.tsx";
 
 /**
  * Walk a React element tree (breadth-first) and collect all elements that
@@ -71,6 +71,68 @@ function makeResult(overrides = {}) {
   };
 }
 
+function makePreview(overrides = {}) {
+  return {
+    displayName: "TestBot",
+    systemPrompt: "Inspect every boundary before changing code.",
+    avatarUrl: null,
+    memoryLevel: "none",
+    memoryEntryCount: 0,
+    hasSourceAllowlist: true,
+    sourceAllowlistCount: 2,
+    sourceAllowlist: ["a".repeat(64), "b".repeat(64)],
+    manifestJson: '{\n  "format": "buzz-agent-snapshot"\n}',
+    locked: false,
+    ...overrides,
+  };
+}
+
+// ── preview transparency ──────────────────────────────────────────────────────
+
+test("preview_body_discloses_prompt_allowlist_and_full_manifest", () => {
+  const preview = makePreview();
+  const element = PreviewBody({
+    preview,
+    hasMemory: false,
+    memoryLevelLabel: "none",
+    keepAllowlist: false,
+    onKeepAllowlistChange: () => {},
+  });
+  const allText = collectText(element).join(" ");
+
+  assert.ok(allText.includes(preview.systemPrompt));
+  for (const pubkey of preview.sourceAllowlist) {
+    assert.ok(allText.includes(pubkey), `missing allowlist pubkey ${pubkey}`);
+  }
+  assert.ok(allText.includes(preview.manifestJson));
+  assert.equal(
+    findAll(
+      element,
+      (n) => n.props?.["data-testid"] === "agent-snapshot-import-manifest",
+    ).length,
+    1,
+  );
+});
+
+// ── locked-card provenance notice ─────────────────────────────────────────────
+
+test("preview_body_shows_locked_notice_only_for_locked_cards", () => {
+  const lockedNotice = (locked) =>
+    findAll(
+      PreviewBody({
+        preview: makePreview({ locked }),
+        hasMemory: false,
+        memoryLevelLabel: "none",
+        keepAllowlist: false,
+        onKeepAllowlistChange: () => {},
+      }),
+      (n) => n.props?.["data-testid"] === "agent-snapshot-import-locked-notice",
+    );
+
+  assert.equal(lockedNotice(true).length, 1);
+  assert.equal(lockedNotice(false).length, 0);
+});
+
 // ── memory errors detail list ─────────────────────────────────────────────────
 
 test("result_body_renders_memory_errors_list_with_test_id", () => {
diff --git a/desktop/src/features/agents/ui/cardMintKeyUtils.ts b/desktop/src/features/agents/ui/cardMintKeyUtils.ts
new file mode 100644
index 0000000000..4364267e60
--- /dev/null
+++ b/desktop/src/features/agents/ui/cardMintKeyUtils.ts
@@ -0,0 +1,75 @@
+import type { CardMintKeyLayer } from "@/shared/api/tauriPersonas";
+
+/**
+ * Pure derivations for the key-setup panel visibility in `AgentCardMintDialog`.
+ *
+ * Extracted so that: (a) the component imports and uses the exact same logic
+ * as the tests verify, and (b) changes to panel conditions are caught by
+ * test failures rather than silently diverging.
+ */
+
+/** Whether the key panel should be shown (setup or user-initiated update only). */
+export function showKeyPanel(
+  keyLayer: CardMintKeyLayer | undefined,
+  editingKey: boolean,
+): boolean {
+  return keyLayer === "none" || editingKey;
+}
+
+/**
+ * Whether the resolved layer is writable from the dialog.
+ * Only `"global"` (and unset/`"none"`) can be updated via the dialog seam.
+ */
+export function isWritableLayer(
+  keyLayer: CardMintKeyLayer | undefined,
+): boolean {
+  return keyLayer === "global" || keyLayer === "none";
+}
+
+/**
+ * Whether the resolved layer cannot be updated from the dialog (key would be
+ * shadowed by the higher-priority layer even if global were updated).
+ */
+export function isReadOnlyLayer(
+  keyLayer: CardMintKeyLayer | undefined,
+): boolean {
+  return (
+    keyLayer === "agent" || keyLayer === "persona" || keyLayer === "process"
+  );
+}
+
+/** Whether the "Cancel" button should be shown (update mode only, with a mint form to return to). */
+export function showCancelButton(
+  keyLayer: CardMintKeyLayer | undefined,
+  editingKey: boolean,
+): boolean {
+  return editingKey && keyLayer !== "none";
+}
+
+/** Whether the "Using your saved OpenAI key · Update" status row should be shown. */
+export function showKeyStatusRow(
+  keyLayer: CardMintKeyLayer | undefined,
+  editingKey: boolean,
+): boolean {
+  return keyLayer === "global" && !editingKey;
+}
+
+/** Whether the read-only provenance row should be shown on the mint form. */
+export function showReadOnlyRow(
+  keyLayer: CardMintKeyLayer | undefined,
+  editingKey: boolean,
+): boolean {
+  return isReadOnlyLayer(keyLayer) && !editingKey;
+}
+
+/** The header title for the key-setup panel. */
+export function keyPanelTitle(
+  keyLayer: CardMintKeyLayer | undefined,
+  editingKey: boolean,
+): string {
+  if (isReadOnlyLayer(keyLayer)) return "OpenAI API key";
+  if (keyLayer === "none") return "One-time setup: OpenAI API key";
+  return editingKey
+    ? "Update OpenAI API key"
+    : "One-time setup: OpenAI API key";
+}
diff --git a/desktop/src/features/agents/ui/personaModelDiscoveryStatus.test.mjs b/desktop/src/features/agents/ui/personaModelDiscoveryStatus.test.mjs
index 23d79aaf7f..548c9ccc0a 100644
--- a/desktop/src/features/agents/ui/personaModelDiscoveryStatus.test.mjs
+++ b/desktop/src/features/agents/ui/personaModelDiscoveryStatus.test.mjs
@@ -21,7 +21,8 @@ test("model discovery status names missing OpenAI-compatible credentials", () =>
   );
 
   assert.equal(status?.tone, "warning");
-  assert.match(status?.message ?? "", /OpenAI API key/);
+  assert.match(status?.message ?? "", /OpenAI runtime API key/);
+  assert.match(status?.message ?? "", /OPENAI_COMPAT_API_KEY/);
   assert.match(status?.message ?? "", /OpenAI models/);
 });
 
diff --git a/desktop/src/features/agents/ui/personaModelDiscoveryStatus.ts b/desktop/src/features/agents/ui/personaModelDiscoveryStatus.ts
index c6991fdd01..b943f6455c 100644
--- a/desktop/src/features/agents/ui/personaModelDiscoveryStatus.ts
+++ b/desktop/src/features/agents/ui/personaModelDiscoveryStatus.ts
@@ -110,7 +110,8 @@ export function formatModelDiscoveryErrorStatus(
 
   if (message.includes("OPENAI_COMPAT_API_KEY required")) {
     return {
-      message: "Enter an OpenAI API key to load OpenAI models.",
+      message:
+        "Enter an OpenAI runtime API key (OPENAI_COMPAT_API_KEY) to load OpenAI models.",
       tone: "warning",
     };
   }
diff --git a/desktop/src/features/agents/ui/runOnSummary.test.mjs b/desktop/src/features/agents/ui/runOnSummary.test.mjs
new file mode 100644
index 0000000000..137ce5481a
--- /dev/null
+++ b/desktop/src/features/agents/ui/runOnSummary.test.mjs
@@ -0,0 +1,171 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { humanizeConfigKey, summarizeRunOn } from "./runOnSummary.ts";
+
+test("local backend summarizes to the local location with no rows", () => {
+  assert.deepEqual(summarizeRunOn({ type: "local" }), { location: "local" });
+});
+
+test("provider backend carries the provider id", () => {
+  const summary = summarizeRunOn({
+    type: "provider",
+    id: "kubernetes",
+    config: {},
+  });
+  assert.equal(summary.location, "provider");
+  assert.equal(summary.providerId, "kubernetes");
+  assert.deepEqual(summary.rows, []);
+});
+
+test("a saved kubernetes config renders labeled scalar rows", () => {
+  const summary = summarizeRunOn({
+    type: "provider",
+    id: "kubernetes",
+    config: {
+      namespace: "buzz-agents-x7k2mp",
+      image: "ghcr.io/block/buzz-sprig@sha256:17facfc7",
+      cpu_request: "1",
+      inactivity_seconds: 7200,
+    },
+  });
+  assert.equal(summary.location, "provider");
+  const byKey = Object.fromEntries(summary.rows.map((r) => [r.key, r]));
+  assert.equal(byKey.namespace.label, "Namespace");
+  assert.equal(byKey.namespace.value, "buzz-agents-x7k2mp");
+  assert.equal(byKey.cpu_request.label, "CPU request");
+  assert.equal(byKey.cpu_request.value, "1");
+  assert.equal(byKey.inactivity_seconds.label, "Inactivity seconds");
+  assert.equal(byKey.inactivity_seconds.value, "7200");
+  assert.equal(byKey.image.value, "ghcr.io/block/buzz-sprig@sha256:17facfc7");
+  assert.ok(summary.rows.every((r) => r.redacted === false));
+});
+
+test("rows follow the provider-schema preferred order, spillover alphabetical", () => {
+  const summary = summarizeRunOn({
+    type: "provider",
+    id: "kubernetes",
+    config: {
+      // Deliberately shuffled persisted order.
+      memory_limit: "1Gi",
+      zeta_extra: "z",
+      namespace: "n",
+      cpu_limit: "1",
+      alpha_extra: "a",
+      image: "i",
+      inactivity_seconds: 7200,
+      cpu_request: "1",
+      context: "c",
+      memory_request: "1Gi",
+    },
+  });
+  assert.deepEqual(
+    summary.rows.map((r) => r.key),
+    [
+      "context",
+      "namespace",
+      "image",
+      "cpu_request",
+      "memory_request",
+      "cpu_limit",
+      "memory_limit",
+      "inactivity_seconds",
+      "alpha_extra",
+      "zeta_extra",
+    ],
+  );
+});
+
+test("null, empty-string, boolean, and number values all display honestly", () => {
+  const summary = summarizeRunOn({
+    type: "provider",
+    id: "p",
+    config: { a_null: null, b_empty: "", c_flag: true, d_num: 0, e_off: false },
+  });
+  const values = Object.fromEntries(summary.rows.map((r) => [r.key, r.value]));
+  assert.equal(values.a_null, "Not set");
+  assert.equal(values.b_empty, "Not set");
+  assert.equal(values.c_flag, "true");
+  // Falsy-but-present values must never read as missing: coerceConfigValues
+  // emits real numbers/booleans, so `value || fallback` would lie about 0/false.
+  assert.equal(values.d_num, "0");
+  assert.equal(values.e_off, "false");
+});
+
+test("every row value is a string — objects must never reach React children", () => {
+  // React throws on an object child, taking down the whole edit dialog.
+  // A hand-edited managed-agents.json with nested config is exactly the
+  // record the create-time scalar gate never saw.
+  const summary = summarizeRunOn({
+    type: "provider",
+    id: "p",
+    config: {
+      resources: { limits: { cpu: "2" } },
+      flag: true,
+      count: 3,
+      name: "x",
+      missing: null,
+    },
+  });
+  for (const row of summary.rows) {
+    assert.equal(typeof row.value, "string", `${row.key} is not a string`);
+  }
+});
+
+test("arrays and objects are summarized, never serialized", () => {
+  const summary = summarizeRunOn({
+    type: "provider",
+    id: "p",
+    config: {
+      tolerations: [{ key: "gpu" }, { key: "spot" }],
+      node_selector: { disktype: "ssd" },
+    },
+  });
+  const values = Object.fromEntries(summary.rows.map((r) => [r.key, r.value]));
+  assert.equal(values.tolerations, "List (2 items)");
+  assert.equal(values.node_selector, "Structured value");
+  // The nested content must not leak through.
+  assert.ok(!JSON.stringify(values).includes("ssd"));
+});
+
+test("secret-shaped keys are redacted, fail-safe for unknown providers", () => {
+  const summary = summarizeRunOn({
+    type: "provider",
+    id: "future-provider",
+    config: {
+      api_token: "abc123",
+      registry_password: "hunter2",
+      clientSecret: "s3cr3t",
+      authHeader: "Bearer xyz",
+      privateKey: "nsec1...",
+      namespace: "safe-to-show",
+    },
+  });
+  const byKey = Object.fromEntries(summary.rows.map((r) => [r.key, r]));
+  for (const key of [
+    "api_token",
+    "registry_password",
+    "clientSecret",
+    "authHeader",
+    "privateKey",
+  ]) {
+    assert.equal(byKey[key].redacted, true, `${key} must be redacted`);
+    assert.equal(byKey[key].value, "••••••••");
+  }
+  assert.equal(byKey.namespace.redacted, false);
+  assert.equal(byKey.namespace.value, "safe-to-show");
+  // Raw secret bytes must be absent from the whole summary.
+  const dump = JSON.stringify(summary);
+  for (const secret of ["abc123", "hunter2", "s3cr3t", "Bearer xyz", "nsec1"]) {
+    assert.ok(!dump.includes(secret), `${secret} leaked`);
+  }
+});
+
+test("humanizeConfigKey handles snake_case, camelCase, and acronyms", () => {
+  assert.equal(humanizeConfigKey("cpu_request"), "CPU request");
+  assert.equal(humanizeConfigKey("memory_limit"), "Memory limit");
+  assert.equal(humanizeConfigKey("serviceAccount"), "Service account");
+  assert.equal(humanizeConfigKey("image"), "Image");
+  assert.equal(humanizeConfigKey("api_url"), "API URL");
+  assert.equal(humanizeConfigKey(""), "");
+});
diff --git a/desktop/src/features/agents/ui/runOnSummary.ts b/desktop/src/features/agents/ui/runOnSummary.ts
new file mode 100644
index 0000000000..f37155481a
--- /dev/null
+++ b/desktop/src/features/agents/ui/runOnSummary.ts
@@ -0,0 +1,156 @@
+import type { ManagedAgentBackend } from "@/shared/api/types";
+
+/**
+ * A single saved provider-config row, ready to render.
+ *
+ * `value` is always a display string: scalars are stringified, `null` becomes
+ * an explicit "Not set", and anything non-scalar (array/object) is summarized
+ * rather than dumped — a generic "render every value" helper must not become
+ * a disclosure surface for config shapes we have never seen.
+ */
+export type RunOnConfigRow = {
+  key: string;
+  label: string;
+  value: string;
+  /** True when the key looks secret-shaped and the value was replaced. */
+  redacted: boolean;
+};
+
+export type RunOnSummary =
+  | { location: "local" }
+  | { location: "provider"; providerId: string; rows: RunOnConfigRow[] };
+
+/**
+ * Words that mark a key's value as unrenderable, checked against the same
+ * word-split the create-time gate uses (`validate_provider_config`,
+ * src-tauri managed_agents/backend.rs) so there is one definition of
+ * "looks like a secret", not two that drift. That gate already rejects
+ * secret-shaped keys on the only non-test write path to `agent.backend` —
+ * this display-side redaction is screenshot hygiene, not the missing
+ * credential fix: a value that is fine in `managed-agents.json` on the
+ * owner's own disk is not fine in a dialog that gets screenshotted into a
+ * channel or PR body, and hand-edited records never met the gate at all.
+ * The first five words mirror the Rust list; the rest are display-only
+ * extras (redacting more than create rejects fails safe).
+ */
+const SECRET_WORDS = new Set([
+  "secret",
+  "password",
+  "token",
+  "key",
+  "credential",
+  "passphrase",
+  "auth",
+  "nsec",
+]);
+
+const REDACTED_PLACEHOLDER = "••••••••";
+
+/** Acronyms that read wrong in sentence case ("Cpu request"). */
+const LABEL_ACRONYMS = new Set(["cpu", "id", "url", "api"]);
+
+/**
+ * Split a config key into lowercase words on `_`, `-`, `.`, and camelCase
+ * boundaries, keeping acronym runs together ("APIKey" → ["api", "key"]).
+ * Mirrors `split_config_key` in managed_agents/backend.rs — one split feeds
+ * both labels and redaction, and word matching (not substring) is what
+ * keeps "keyboard" from being treated as a key.
+ */
+function splitConfigKey(key: string): string[] {
+  return key
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .split(/[_\s.-]+/)
+    .filter((word) => word.length > 0)
+    .map((word) => word.toLowerCase());
+}
+
+/**
+ * Humanize a stored config key: `cpu_request` → "CPU request". Labels come
+ * from the saved keys, not a live provider probe — probing during edit is
+ * executable work whose schema (titles, generated defaults) reflects the
+ * plugin *today*, not what this agent was deployed with. See PR #4411 for
+ * why dialogs must not re-probe as a side effect.
+ */
+export function humanizeConfigKey(key: string): string {
+  const words = splitConfigKey(key);
+  if (words.length === 0) return key;
+  return words
+    .map((word, index) => {
+      if (LABEL_ACRONYMS.has(word)) return word.toUpperCase();
+      if (index === 0) return word.charAt(0).toUpperCase() + word.slice(1);
+      return word;
+    })
+    .join(" ");
+}
+
+function displayValue(value: unknown): string {
+  if (value === null || value === undefined) return "Not set";
+  if (typeof value === "string") return value.length > 0 ? value : "Not set";
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  // Arrays/objects: summarize, never serialize. A nested structure could
+  // carry values its own keys would have redacted.
+  return Array.isArray(value)
+    ? `List (${value.length} items)`
+    : "Structured value";
+}
+
+/**
+ * Preferred display order, traced from the Kubernetes provider schema
+ * (crates/buzz-backend-kubernetes/src/config.rs): locate the deployment
+ * first (context → namespace), then what runs (image), then the
+ * request/limit pairs kept adjacent, then lifecycle/identity. Keys not
+ * listed here (other providers, future fields) spill over alphabetically
+ * after the known ones, so ordering stays deterministic for every record.
+ */
+const PREFERRED_KEY_ORDER = [
+  "context",
+  "namespace",
+  "image",
+  "cpu_request",
+  "memory_request",
+  "cpu_limit",
+  "memory_limit",
+  "inactivity_seconds",
+  "service_account",
+];
+
+function compareKeys(a: string, b: string): number {
+  const ia = PREFERRED_KEY_ORDER.indexOf(a);
+  const ib = PREFERRED_KEY_ORDER.indexOf(b);
+  if (ia !== -1 && ib !== -1) return ia - ib;
+  if (ia !== -1) return -1;
+  if (ib !== -1) return 1;
+  return a.localeCompare(b);
+}
+
+/**
+ * Project a `ManagedAgentBackend` into renderable rows. These are the
+ * *saved* settings — the config recorded when the agent was created — not
+ * the provider's effective settings: optional fields a record omits are
+ * defaulted by the provider at deploy time, and synthesizing today's plugin
+ * defaults here could show values that drifted from what actually deployed.
+ * (`backendAgentId` is deliberately not shown: it is deploy-time runtime
+ * state written on start, not saved creation intent, and this section's
+ * contract is the latter.) Rows follow the preferred key order with
+ * alphabetical spillover, so rendering is deterministic regardless of the
+ * JSON key order a given record happened to persist.
+ */
+export function summarizeRunOn(backend: ManagedAgentBackend): RunOnSummary {
+  if (backend.type === "local") return { location: "local" };
+  const rows = Object.entries(backend.config ?? {})
+    .sort(([a], [b]) => compareKeys(a, b))
+    .map(([key, value]): RunOnConfigRow => {
+      const redacted = splitConfigKey(key).some((word) =>
+        SECRET_WORDS.has(word),
+      );
+      return {
+        key,
+        label: humanizeConfigKey(key),
+        value: redacted ? REDACTED_PLACEHOLDER : displayValue(value),
+        redacted,
+      };
+    });
+  return { location: "provider", providerId: backend.id, rows };
+}
diff --git a/desktop/src/features/agents/ui/whereToRunIntent.test.mjs b/desktop/src/features/agents/ui/whereToRunIntent.test.mjs
index 500e9019f2..262d55d998 100644
--- a/desktop/src/features/agents/ui/whereToRunIntent.test.mjs
+++ b/desktop/src/features/agents/ui/whereToRunIntent.test.mjs
@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import {
+  applyProbeResult,
   canSubmitWhereToRun,
   emptyWhereToRunDraft,
   providerConfigComplete,
@@ -59,3 +60,72 @@ test("provider draft resolves with coerced config values", () => {
     config: { region: "us", size: 3 },
   });
 });
+
+// ── applyProbeResult: probe resolution must merge, not overwrite ─────────────
+//
+// Pins the seam that fixed the "Typewriter Eraser" (agent-create dialog's
+// provider config fields losing keystrokes): a probe resolution prefills
+// schema defaults *beneath* the user's in-flight config, never over it. The
+// effect in WhereToRunSection keys probing on the provider's binary path, so
+// the only probe writes that reach providerConfig are the ones pinned here.
+
+const probeWithDefaults = {
+  ok: true,
+  config_schema: {
+    properties: {
+      context: { type: "string", title: "Kubeconfig context" },
+      namespace: { type: "string", default: "buzz-agents-x1y2z3" },
+      inactivity_seconds: { type: "number", default: 1800 },
+    },
+    required: ["namespace"],
+  },
+};
+
+const unprobedDraft = {
+  ...emptyWhereToRunDraft,
+  runOn: "kubernetes",
+};
+
+test("probe resolution prefills schema defaults on a fresh draft", () => {
+  const next = applyProbeResult(unprobedDraft, probeWithDefaults);
+  assert.equal(next.probedProvider, probeWithDefaults);
+  assert.deepEqual(next.providerConfig, {
+    namespace: "buzz-agents-x1y2z3",
+    inactivity_seconds: "1800",
+  });
+});
+
+test("probe resolution keeps user-typed values over schema defaults", () => {
+  const typed = {
+    ...unprobedDraft,
+    providerConfig: { context: "prod-us-west", namespace: "my-ns" },
+  };
+  const next = applyProbeResult(typed, probeWithDefaults);
+  assert.deepEqual(next.providerConfig, {
+    context: "prod-us-west",
+    namespace: "my-ns",
+    inactivity_seconds: "1800",
+  });
+});
+
+test("probe resolution keeps a user-cleared field cleared", () => {
+  // "" is a deliberate user state — coerceConfigValues drops empty numerics
+  // and required-gating treats "" as incomplete; the probe must not undo it.
+  const cleared = { ...unprobedDraft, providerConfig: { namespace: "" } };
+  const next = applyProbeResult(cleared, probeWithDefaults);
+  assert.equal(next.providerConfig.namespace, "");
+});
+
+test("a schema-less probe result records the probe without touching config", () => {
+  const typed = { ...unprobedDraft, providerConfig: { context: "abc" } };
+  const next = applyProbeResult(typed, { ok: true });
+  assert.deepEqual(next.providerConfig, { context: "abc" });
+  assert.deepEqual(next.probedProvider, { ok: true });
+});
+
+test("probe resolution preserves unrelated draft fields", () => {
+  assert.equal(
+    applyProbeResult(unprobedDraft, probeWithDefaults).runOn,
+    "kubernetes",
+  );
+});
diff --git a/desktop/src/features/agents/ui/whereToRunIntent.ts b/desktop/src/features/agents/ui/whereToRunIntent.ts
index fcb3e82b7e..9aa9248e75 100644
--- a/desktop/src/features/agents/ui/whereToRunIntent.ts
+++ b/desktop/src/features/agents/ui/whereToRunIntent.ts
@@ -15,6 +15,35 @@ export const emptyWhereToRunDraft: WhereToRunDraft = {
   probedProvider: null,
 };
 
+/**
+ * Fold a completed probe into the draft the user has *now* — not the draft
+ * that existed when the probe started. Schema defaults prefill only the keys
+ * the user has not touched: anything already in `providerConfig` (typed while
+ * the probe was in flight) wins over the default. Overwriting instead of
+ * merging is the "Typewriter Eraser" bug — every probe resolution silently
+ * erased in-flight keystrokes.
+ */
+export function applyProbeResult(
+  current: WhereToRunDraft,
+  result: BackendProviderProbeResult,
+): WhereToRunDraft {
+  const defaults: Record<string, string> = {};
+  const properties =
+    (result.config_schema as Record<string, unknown> | undefined)?.properties ??
+    {};
+  for (const [key, property] of Object.entries(properties) as [
+    string,
+    Record<string, unknown>,
+  ][]) {
+    if (property.default != null) defaults[key] = String(property.default);
+  }
+  return {
+    ...current,
+    probedProvider: result,
+    providerConfig: { ...defaults, ...current.providerConfig },
+  };
+}
+
 export function providerConfigComplete(draft: WhereToRunDraft): boolean {
   if (draft.runOn === "local") return true;
   if (!draft.probedProvider) return false;
diff --git a/desktop/src/features/channels/forcedUnreadStore.test.mjs b/desktop/src/features/channels/forcedUnreadStore.test.mjs
new file mode 100644
index 0000000000..cea1c3babe
--- /dev/null
+++ b/desktop/src/features/channels/forcedUnreadStore.test.mjs
@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  addForcedUnreadSource,
+  forcedUnreadMarker,
+  removeForcedUnreadSource,
+} from "./forcedUnreadStore.ts";
+
+test("adding an Inbox owner preserves an existing manual force", () => {
+  const entry = addForcedUnreadSource(null, 120, "inbox");
+
+  assert.deepEqual(entry, {
+    markerAtWhenForced: null,
+    sources: ["manual", "inbox"],
+  });
+});
+
+test("clearing Inbox ownership leaves a manual force intact", () => {
+  const entry = {
+    markerAtWhenForced: 120,
+    sources: ["manual", "inbox"],
+  };
+
+  assert.deepEqual(removeForcedUnreadSource(entry, "inbox"), {
+    markerAtWhenForced: 120,
+    sources: ["manual"],
+  });
+});
+
+test("clearing manual ownership leaves an Inbox force intact", () => {
+  const entry = {
+    markerAtWhenForced: 120,
+    sources: ["manual", "inbox"],
+  };
+
+  assert.deepEqual(removeForcedUnreadSource(entry, "manual"), {
+    markerAtWhenForced: 120,
+    sources: ["inbox"],
+  });
+});
+
+test("clearing the only force owner removes the entry", () => {
+  const entry = {
+    markerAtWhenForced: 120,
+    sources: ["inbox"],
+  };
+
+  assert.equal(removeForcedUnreadSource(entry, "inbox"), undefined);
+});
+
+test("legacy persisted entries retain their read-marker baseline", () => {
+  assert.equal(forcedUnreadMarker(120), 120);
+  assert.equal(forcedUnreadMarker(null), null);
+});
diff --git a/desktop/src/features/channels/forcedUnreadStore.ts b/desktop/src/features/channels/forcedUnreadStore.ts
index c6a6fd0758..c4c25dcecb 100644
--- a/desktop/src/features/channels/forcedUnreadStore.ts
+++ b/desktop/src/features/channels/forcedUnreadStore.ts
@@ -1,14 +1,17 @@
+import * as React from "react";
+
 /**
- * Per-pubkey localStorage record store for channels manually marked unread via
- * right-click → "mark unread". Keyed by channelId (not thread-root). Persisted
- * so the sidebar badge survives reload and the rail observer can read it for
- * inactive communities.
+ * Per-pubkey localStorage record store for channels forced unread by manual or
+ * Inbox actions. Keyed by channelId (not thread-root). Persisted so the sidebar
+ * badge survives reload and the rail observer can read it for inactive
+ * communities.
  *
  * Each entry stores the channel's own NIP-RS read marker (unix seconds) at the
- * moment mark-unread was invoked, or null if no marker existed yet. The rail
- * observer gates the forced-unread OR on this baseline: if the observed synced
- * read marker has since advanced past markerAtWhenForced, the cross-device read
- * wins and the dot is not lit.
+ * moment the first force was added, or null if no marker existed yet, plus the
+ * sources that currently own the force. The rail observer gates the
+ * forced-unread OR on this baseline: if the observed synced read marker has
+ * since advanced past markerAtWhenForced, the cross-device read wins and the
+ * dot is not lit.
  *
  * On identity change, the in-memory map is swapped to the current pubkey's
  * persisted data. Old pubkey data is NOT wiped from localStorage.
@@ -17,8 +20,58 @@
  * a retrograde "unread" state. localStorage is best-effort (per-device).
  */
 
-/** channelId → NIP-RS read marker (unix seconds) at force-time, or null */
-export type ForcedUnreadMap = Record<string, number | null>;
+export type ForcedUnreadSource = "inbox" | "manual";
+export type ForcedUnreadEntry =
+  | number
+  | null
+  | {
+      markerAtWhenForced: number | null;
+      sources: ForcedUnreadSource[];
+    };
+/** channelId → forced-unread entry. Numbers/null are the legacy v1 shape. */
+export type ForcedUnreadMap = Record<string, ForcedUnreadEntry>;
+
+function entrySources(entry: ForcedUnreadEntry): ForcedUnreadSource[] {
+  return typeof entry === "object" && entry !== null
+    ? entry.sources
+    : ["manual"];
+}
+
+export function forcedUnreadMarker(entry: ForcedUnreadEntry): number | null {
+  return typeof entry === "object" && entry !== null
+    ? entry.markerAtWhenForced
+    : entry;
+}
+
+export function addForcedUnreadSource(
+  entry: ForcedUnreadEntry | undefined,
+  markerAtWhenForced: number | null,
+  source: ForcedUnreadSource,
+): ForcedUnreadEntry {
+  if (entry !== undefined && entrySources(entry).includes(source)) return entry;
+  return {
+    markerAtWhenForced:
+      entry === undefined ? markerAtWhenForced : forcedUnreadMarker(entry),
+    sources: [
+      ...new Set([...(entry === undefined ? [] : entrySources(entry)), source]),
+    ],
+  };
+}
+
+export function removeForcedUnreadSource(
+  entry: ForcedUnreadEntry,
+  source: ForcedUnreadSource,
+): ForcedUnreadEntry | undefined {
+  const sources = entrySources(entry);
+  if (!sources.includes(source)) return entry;
+  const remainingSources = sources.filter((candidate) => candidate !== source);
+  return remainingSources.length > 0
+    ? {
+        markerAtWhenForced: forcedUnreadMarker(entry),
+        sources: remainingSources,
+      }
+    : undefined;
+}
 
 const STORAGE_PREFIX = "buzz-forced-unread.v1";
 const storageKey = (pubkey: string) => `${STORAGE_PREFIX}:${pubkey}`;
@@ -37,8 +90,27 @@ export const forcedUnreadStore = {
         return {};
       const result: ForcedUnreadMap = {};
       for (const [k, v] of Object.entries(parsed)) {
-        if (typeof k === "string" && (v === null || typeof v === "number")) {
-          result[k] = v as number | null;
+        if (typeof k !== "string") continue;
+        if (v === null || typeof v === "number") {
+          result[k] = v;
+          continue;
+        }
+        if (
+          typeof v === "object" &&
+          v !== null &&
+          "markerAtWhenForced" in v &&
+          (v.markerAtWhenForced === null ||
+            typeof v.markerAtWhenForced === "number") &&
+          "sources" in v &&
+          Array.isArray(v.sources)
+        ) {
+          const sources = v.sources.filter(
+            (source: unknown): source is ForcedUnreadSource =>
+              source === "inbox" || source === "manual",
+          );
+          if (sources.length > 0) {
+            result[k] = { markerAtWhenForced: v.markerAtWhenForced, sources };
+          }
         }
       }
       return result;
@@ -54,3 +126,44 @@ export const forcedUnreadStore = {
     }
   },
 };
+
+export function useForcedUnreadActions(
+  forcedUnreadRef: React.MutableRefObject<ForcedUnreadMap>,
+  getOwnTimestamp: (channelId: string) => number | null,
+  pubkey: string | undefined,
+  onChange: () => void,
+) {
+  const persist = React.useCallback(() => {
+    if (pubkey) forcedUnreadStore.write(pubkey, forcedUnreadRef.current);
+    onChange();
+  }, [forcedUnreadRef, onChange, pubkey]);
+  const markChannelUnread = React.useCallback(
+    (channelId: string, source: ForcedUnreadSource = "manual") => {
+      const current = Object.hasOwn(forcedUnreadRef.current, channelId)
+        ? forcedUnreadRef.current[channelId]
+        : undefined;
+      const next = addForcedUnreadSource(
+        current,
+        getOwnTimestamp(channelId),
+        source,
+      );
+      if (next === current) return;
+      forcedUnreadRef.current[channelId] = next;
+      persist();
+    },
+    [forcedUnreadRef, getOwnTimestamp, persist],
+  );
+  const clearChannelUnreadSource = React.useCallback(
+    (channelId: string, source: ForcedUnreadSource) => {
+      if (!Object.hasOwn(forcedUnreadRef.current, channelId)) return;
+      const current = forcedUnreadRef.current[channelId];
+      const next = removeForcedUnreadSource(current, source);
+      if (next === current) return;
+      if (next === undefined) delete forcedUnreadRef.current[channelId];
+      else forcedUnreadRef.current[channelId] = next;
+      persist();
+    },
+    [forcedUnreadRef, persist],
+  );
+  return { clearChannelUnreadSource, markChannelUnread };
+}
diff --git a/desktop/src/features/channels/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/ChannelPane.tsx b/desktop/src/features/channels/ui/ChannelPane.tsx
index 70877875f7..770c45e445 100644
--- a/desktop/src/features/channels/ui/ChannelPane.tsx
+++ b/desktop/src/features/channels/ui/ChannelPane.tsx
@@ -36,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 {
@@ -408,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
@@ -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}
diff --git a/desktop/src/features/channels/ui/ChannelScreen.tsx b/desktop/src/features/channels/ui/ChannelScreen.tsx
index b4d33b4776..3e3b6c9c8f 100644
--- a/desktop/src/features/channels/ui/ChannelScreen.tsx
+++ b/desktop/src/features/channels/ui/ChannelScreen.tsx
@@ -80,6 +80,7 @@ import { useMessageProfiles } from "./useMessageProfiles";
 import { useChannelPanelHistoryState } from "./useChannelPanelHistoryState";
 import { useChannelProfilePanel } from "./useChannelProfilePanel";
 import { useChannelRouteTarget } from "./useChannelRouteTarget";
+import { useChannelOpenReadState } from "./useChannelOpenReadState";
 import { useChannelUnreadState } from "./useChannelUnreadState";
 import type { ChannelScreenProps } from "./ChannelScreen.types";
 const HEADER_ACTIONS_COMPACT_BREAKPOINT_PX = 760,
@@ -99,7 +100,7 @@ export function ChannelScreen({
   const { goHome } = useAppNavigation();
   const { activeCommunity } = useCommunities();
   const {
-    markChannelRead,
+    clearChannelUnreadSource,
     markChannelUnread,
     getChannelReadAt,
     getMessageReadAt,
@@ -112,6 +113,7 @@ export function ChannelScreen({
     unfollowThread,
     isFollowingThread,
     isNotifiedForThread,
+    recordThreadInteraction,
     isThreadMuted,
     readStateVersion,
   } = useAppShell();
@@ -207,12 +209,11 @@ export function ChannelScreen({
   const activeReadAt = latestActiveMessage
     ? new Date(latestActiveMessage.created_at * 1_000).toISOString()
     : null;
-  React.useEffect(() => {
-    if (!activeChannelId || activeChannel?.isMember === false) {
-      return;
-    }
-    markChannelRead(activeChannelId, activeReadAt, { topLevelOnly: true });
-  }, [activeChannel?.isMember, activeChannelId, activeReadAt, markChannelRead]);
+  useChannelOpenReadState(
+    activeChannelId,
+    activeChannel?.isMember,
+    activeReadAt,
+  );
   React.useEffect(() => {
     if (!activeChannelId) {
       setContextParentResolver(null);
@@ -262,7 +263,6 @@ export function ChannelScreen({
     resolvedMessages,
     threadReplyEvents,
   );
-
   const messageEventProfilePubkeys = useMessageEventProfilePubkeys(
     resolvedMessages,
     threadReplyEvents,
@@ -472,6 +472,7 @@ export function ChannelScreen({
     threadReplyTargetId,
     expandedThreadReplyIds,
     openThreadMessages: threadPanelData.visibleReplies,
+    clearChannelUnreadSource,
     getChannelReadAt,
     getMessageReadAt,
     markChannelUnread,
@@ -484,8 +485,7 @@ 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.
+  // Event id awaiting the empty-edit deletion confirmation.
   const [emptyDeleteId, setEmptyDeleteId] = React.useState<string | null>(null);
   const {
     handleCancelEdit,
@@ -508,6 +508,7 @@ export function ChannelScreen({
     getFirstReplyIdForMessage,
     getReplyDescendantIdsForMessage,
     markRevealedRepliesRead,
+    recordThreadInteraction,
     openThreadHeadId: effectiveOpenThreadHeadId,
     onOptimisticOpenThreadHeadIdChange: setOptimisticOpenThreadHeadId,
     onRequestEmptyEditDelete: setEmptyDeleteId,
@@ -688,7 +689,6 @@ export function ChannelScreen({
     threadReplyTargetId,
     threadReplyTargetMessage,
   });
-
   const hasAuxiliaryPanel = Boolean(
     effectiveOpenThreadHeadId ||
       openAgentSessionPubkey ||
diff --git a/desktop/src/features/channels/ui/ChannelTypeSettings.tsx b/desktop/src/features/channels/ui/ChannelTypeSettings.tsx
index 1ff11d2104..6883f4cad1 100644
--- a/desktop/src/features/channels/ui/ChannelTypeSettings.tsx
+++ b/desktop/src/features/channels/ui/ChannelTypeSettings.tsx
@@ -34,6 +34,7 @@ const CHANNEL_TYPE_RESIZE_TRANSITION = {
 
 export function ChannelTypeSettings({
   disabled,
+  label = "Channel type",
   onOpenChange,
   onTemporaryChange,
   onTtlSecondsChange,
@@ -43,6 +44,7 @@ export function ChannelTypeSettings({
   ttlSeconds,
 }: {
   disabled?: boolean;
+  label?: string;
   onOpenChange?: (open: boolean) => void;
   onTemporaryChange: (temporary: boolean) => void;
   onTtlSecondsChange: (ttlSeconds: number) => void;
@@ -77,9 +79,7 @@ export function ChannelTypeSettings({
         className="flex items-center justify-between gap-3 px-3 py-3"
         data-testid={`${testIdPrefix}-channel-type-row`}
       >
-        <span className="text-sm font-medium text-foreground">
-          Channel type
-        </span>
+        <span className="text-sm font-medium text-foreground">{label}</span>
         <ChannelTypePicker
           align="end"
           className="-mr-2.5"
diff --git a/desktop/src/features/channels/ui/useChannelOpenReadState.test.mjs b/desktop/src/features/channels/ui/useChannelOpenReadState.test.mjs
new file mode 100644
index 0000000000..4f54d8b309
--- /dev/null
+++ b/desktop/src/features/channels/ui/useChannelOpenReadState.test.mjs
@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { getTopLevelInboxUnreadOverrideIds } from "./useChannelOpenReadState.ts";
+
+test("opening a channel clears only its top-level Inbox overrides", () => {
+  assert.deepEqual(
+    getTopLevelInboxUnreadOverrideIds(
+      [
+        { id: "top-level", channelId: "general", tags: [] },
+        {
+          id: "thread-reply",
+          channelId: "general",
+          tags: [
+            ["e", "root", "", "root"],
+            ["e", "parent", "", "reply"],
+          ],
+        },
+        { id: "other-channel", channelId: "random", tags: [] },
+      ],
+      "general",
+    ),
+    ["top-level"],
+  );
+});
diff --git a/desktop/src/features/channels/ui/useChannelOpenReadState.ts b/desktop/src/features/channels/ui/useChannelOpenReadState.ts
new file mode 100644
index 0000000000..ff927c00bb
--- /dev/null
+++ b/desktop/src/features/channels/ui/useChannelOpenReadState.ts
@@ -0,0 +1,45 @@
+import * as React from "react";
+
+import { useAppShell } from "@/app/AppShellContext";
+import { isThreadReply } from "@/features/messages/lib/threading";
+import type { FeedItem } from "@/shared/api/types";
+
+/**
+ * Inbox overrides for top-level rows are consumed by opening the channel.
+ * Thread-reply overrides intentionally remain until their thread is read.
+ */
+export function getTopLevelInboxUnreadOverrideIds(
+  items: FeedItem[],
+  channelId: string,
+): string[] {
+  return items.flatMap((item) =>
+    item.channelId === channelId && !isThreadReply(item.tags) ? [item.id] : [],
+  );
+}
+
+export function useChannelOpenReadState(
+  activeChannelId: string | null,
+  isChannelMember: boolean | undefined,
+  activeReadAt: string | null,
+) {
+  const { feedItemState, locallyUnreadFeedItems, markChannelRead } =
+    useAppShell();
+
+  React.useEffect(() => {
+    if (!activeChannelId || isChannelMember === false) return;
+    for (const itemId of getTopLevelInboxUnreadOverrideIds(
+      locallyUnreadFeedItems,
+      activeChannelId,
+    )) {
+      feedItemState.undoUnread(itemId);
+    }
+    markChannelRead(activeChannelId, activeReadAt, { topLevelOnly: true });
+  }, [
+    activeChannelId,
+    activeReadAt,
+    feedItemState.undoUnread,
+    isChannelMember,
+    locallyUnreadFeedItems,
+    markChannelRead,
+  ]);
+}
diff --git a/desktop/src/features/channels/ui/useChannelUnreadState.ts b/desktop/src/features/channels/ui/useChannelUnreadState.ts
index dc24023555..884aa02d8e 100644
--- a/desktop/src/features/channels/ui/useChannelUnreadState.ts
+++ b/desktop/src/features/channels/ui/useChannelUnreadState.ts
@@ -1,5 +1,6 @@
 import * as React from "react";
 
+import type { ForcedUnreadSource } from "@/features/channels/forcedUnreadStore";
 import {
   buildCreatedAtByMessageId,
   buildDirectReplyIdsByParentId,
@@ -36,6 +37,10 @@ type UseChannelUnreadStateOptions = {
   openThreadMessages?: MainTimelineEntry[];
   getChannelReadAt: (channelId: string) => number | null;
   getMessageReadAt: (messageId: string) => number | null;
+  clearChannelUnreadSource: (
+    channelId: string,
+    source: ForcedUnreadSource,
+  ) => void;
   markChannelUnread: (channelId: string) => void;
   markMessageRead: (messageId: string, timestamp: number) => void;
   isThreadMuted: (rootId: string) => boolean;
@@ -64,6 +69,7 @@ export function useChannelUnreadState({
   openThreadMessages,
   getChannelReadAt,
   getMessageReadAt,
+  clearChannelUnreadSource,
   markChannelUnread,
   markMessageRead,
   isThreadMuted,
@@ -452,16 +458,26 @@ export function useChannelUnreadState({
         const createdAt = createdAtByMessageId.get(id);
         if (createdAt !== undefined) markMessageRead(id, createdAt);
       }
+      if (activeChannelId && forcedUnreadMsgRef.current.size === 0) {
+        clearChannelUnreadSource(activeChannelId, "manual");
+      }
       forceUnreadRender();
     },
-    [createdAtByMessageId, getReplyDescendantIdsForMessage, markMessageRead],
+    [
+      activeChannelId,
+      clearChannelUnreadSource,
+      createdAtByMessageId,
+      getReplyDescendantIdsForMessage,
+      markMessageRead,
+    ],
   );
 
   // Mark a message and its whole subtree UNREAD (LP4 v3 menu action). Markers
   // are monotonic and cannot move backward, so this writes NO marker: it adds
   // the ids to the session-local forced-unread overlay the badge predicates OR
-  // in. Cleared on channel-leave; does not survive reload (symmetric with the
-  // shipped channel mark-unread).
+  // in. It also forces the channel-level unread projection so leaving the
+  // channel restores its bold sidebar emphasis. The per-message overlay is
+  // cleared on channel-leave; the channel-level force survives until reopen.
   const handleMarkMessageUnread = React.useCallback(
     (messageId: string) => {
       for (const id of [
@@ -470,9 +486,12 @@ export function useChannelUnreadState({
       ]) {
         forcedUnreadMsgRef.current.add(id);
       }
+      if (activeChannelId) {
+        markChannelUnread(activeChannelId);
+      }
       forceUnreadRender();
     },
-    [getReplyDescendantIdsForMessage],
+    [activeChannelId, getReplyDescendantIdsForMessage, markChannelUnread],
   );
 
   return {
diff --git a/desktop/src/features/channels/unreadChannelCounts.ts b/desktop/src/features/channels/unreadChannelCounts.ts
index cb33c62975..aae9c5096e 100644
--- a/desktop/src/features/channels/unreadChannelCounts.ts
+++ b/desktop/src/features/channels/unreadChannelCounts.ts
@@ -78,6 +78,19 @@ export function countUnreadObservedEvents(
   return count;
 }
 
+export function hasUnreadTopLevelObservedEvent(
+  eventsById: ReadonlyMap<string, ObservedUnreadEvent> | undefined,
+  getReadAt: (event: ObservedUnreadEvent) => number | null,
+): boolean {
+  if (!eventsById) return false;
+  for (const event of eventsById.values()) {
+    if (event.rootId !== null) continue;
+    const readAt = getReadAt(event);
+    if (readAt === null || event.createdAt > readAt) return true;
+  }
+  return false;
+}
+
 export function countUnreadBadgeObservedEvents(
   eventsById: ReadonlyMap<string, ObservedUnreadEvent> | undefined,
   getReadAt: (event: ObservedUnreadEvent) => number | null,
diff --git a/desktop/src/features/channels/unreadReadMarker.test.mjs b/desktop/src/features/channels/unreadReadMarker.test.mjs
index 6ea0916413..660d4f5c61 100644
--- a/desktop/src/features/channels/unreadReadMarker.test.mjs
+++ b/desktop/src/features/channels/unreadReadMarker.test.mjs
@@ -7,6 +7,7 @@ import {
   countUnreadBadgeObservedEvents,
   countUnreadHighPriorityObservedEvents,
   countUnreadObservedEvents,
+  hasUnreadTopLevelObservedEvent,
   observedUnreadEventReadAt,
   recordObservedUnreadEvent,
 } from "./unreadChannelCounts.ts";
@@ -368,6 +369,30 @@ test("countUnreadObservedEvents_topLevelUsesChannelMarker", () => {
   assert.equal(countUnreadObservedEvents(events, readAtFor(300, new Map())), 1);
 });
 
+test("hasUnreadTopLevelObservedEvent_ignoresUnreadThreadReplies", () => {
+  const events = new Map([
+    ["top-old", observed("top-old", 250)],
+    ["thread-new", observed("thread-new", 500, "root-1")],
+  ]);
+
+  assert.equal(
+    hasUnreadTopLevelObservedEvent(events, readAtFor(300, new Map())),
+    false,
+  );
+});
+
+test("hasUnreadTopLevelObservedEvent_detectsUnreadTopLevelMessage", () => {
+  const events = new Map([
+    ["top-new", observed("top-new", 350)],
+    ["thread-new", observed("thread-new", 500, "root-1")],
+  ]);
+
+  assert.equal(
+    hasUnreadTopLevelObservedEvent(events, readAtFor(300, new Map())),
+    true,
+  );
+});
+
 test("countUnreadBadgeObservedEvents_skipsBoldOnlyGeneralChannelItems", () => {
   const events = new Map([
     ["plain", observed("plain", 500, null, false, false)],
diff --git a/desktop/src/features/channels/useChannelPaneHandlers.ts b/desktop/src/features/channels/useChannelPaneHandlers.ts
index 53170257a4..a619f595f9 100644
--- a/desktop/src/features/channels/useChannelPaneHandlers.ts
+++ b/desktop/src/features/channels/useChannelPaneHandlers.ts
@@ -7,6 +7,7 @@ import type {
   useToggleReactionMutation,
 } from "@/features/messages/hooks";
 import { resolveThreadReplyTarget } from "@/features/messages/hooks";
+import type { TimelineMessage } from "@/features/messages/types";
 
 /**
  * Stable callback references for ChannelPane so that keystroke-driven
@@ -24,6 +25,7 @@ export function useChannelPaneHandlers({
   getFirstReplyIdForMessage,
   getReplyDescendantIdsForMessage,
   markRevealedRepliesRead,
+  recordThreadInteraction,
   onOptimisticOpenThreadHeadIdChange,
   onRequestEmptyEditDelete,
   openThreadHeadId,
@@ -43,6 +45,7 @@ export function useChannelPaneHandlers({
   getFirstReplyIdForMessage: (messageId: string) => string | null;
   getReplyDescendantIdsForMessage: (messageId: string) => string[];
   markRevealedRepliesRead: (messageId: string) => void;
+  recordThreadInteraction: (rootId: string) => void;
   onOptimisticOpenThreadHeadIdChange: React.Dispatch<
     React.SetStateAction<string | null | undefined>
   >;
@@ -344,14 +347,21 @@ export function useChannelPaneHandlers({
   );
 
   const handleToggleReaction = React.useCallback(
-    async (message: { id: string }, emoji: string, remove: boolean) => {
+    async (
+      message: Pick<TimelineMessage, "id" | "rootId">,
+      emoji: string,
+      remove: boolean,
+    ) => {
       await toggleMutateRef.current({
         emoji,
         eventId: message.id,
         remove,
       });
+      if (!remove) {
+        recordThreadInteraction(message.rootId ?? message.id);
+      }
     },
-    [],
+    [recordThreadInteraction],
   );
 
   return {
diff --git a/desktop/src/features/channels/useUnreadChannels.ts b/desktop/src/features/channels/useUnreadChannels.ts
index a2376f9b7b..256077d64c 100644
--- a/desktop/src/features/channels/useUnreadChannels.ts
+++ b/desktop/src/features/channels/useUnreadChannels.ts
@@ -9,8 +9,8 @@ import {
   countUnreadBadgeObservedEvents,
   countUnreadHighPriorityObservedEvents,
   countUnreadObservedEvents,
+  hasUnreadTopLevelObservedEvent,
   makeObservedUnreadEvent,
-  mapsEqual,
   observedUnreadEventReadAt,
   recordObservedUnreadEvent,
   type ObservedUnreadEvent,
@@ -20,6 +20,7 @@ import { makeRootIdStore } from "@/features/channels/unreadRootIdStore";
 import {
   forcedUnreadStore,
   type ForcedUnreadMap,
+  useForcedUnreadActions,
 } from "@/features/channels/forcedUnreadStore";
 import {
   getThreadReference,
@@ -33,6 +34,7 @@ import {
 import type { RelayClient } from "@/shared/api/relayClientSession";
 import type { Channel, RelayEvent } from "@/shared/api/types";
 import { CHANNEL_MESSAGE_EVENT_KINDS } from "@/shared/constants/kinds";
+import { useStableMap, useStableSet } from "@/shared/hooks/useStableReference";
 import { normalizeRelayUrl } from "@/features/profile/lib/selfProfileStorage";
 import { DM_NOTIFIABLE_EVENT_KINDS } from "./isDmNotifiableKind";
 import {
@@ -125,14 +127,6 @@ export function resolveObservedUnreadRootId(tags: string[][]): string | null {
   return isBroadcastReply(tags) ? null : getThreadReference(tags).rootId;
 }
 
-function setsEqual(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
-  if (a.size !== b.size) return false;
-  for (const item of a) {
-    if (!b.has(item)) return false;
-  }
-  return true;
-}
-
 export function useUnreadChannels(
   channels: Channel[],
   activeChannel: Channel | null,
@@ -310,9 +304,18 @@ export function useUnreadChannels(
     (
       channelId: string,
       readAt: string | null | undefined,
-      { topLevelOnly = false }: { topLevelOnly?: boolean } = {},
+      {
+        preserveForcedUnread = false,
+        topLevelOnly = false,
+      }: {
+        preserveForcedUnread?: boolean;
+        topLevelOnly?: boolean;
+      } = {},
     ) => {
-      if (Object.hasOwn(forcedUnreadRef.current, channelId)) {
+      if (
+        !preserveForcedUnread &&
+        Object.hasOwn(forcedUnreadRef.current, channelId)
+      ) {
         delete forcedUnreadRef.current[channelId];
         if (pubkey) {
           forcedUnreadStore.write(pubkey, forcedUnreadRef.current);
@@ -342,22 +345,13 @@ export function useUnreadChannels(
     [markContextRead, pubkey],
   );
 
-  // Manually mark a channel unread (e.g., right-click → "mark unread"). Persists
-  // the current NIP-RS read marker as baseline to localStorage so the rail
-  // observer can detect when a cross-device read has since covered the force.
-  // NIP-RS markers are monotonic, so we do not publish a lower timestamp.
-  const markChannelUnread = React.useCallback(
-    (channelId: string) => {
-      if (!Object.hasOwn(forcedUnreadRef.current, channelId)) {
-        forcedUnreadRef.current[channelId] = getOwnTimestamp(channelId);
-        if (pubkey) {
-          forcedUnreadStore.write(pubkey, forcedUnreadRef.current);
-        }
-        bumpLatestVersion();
-      }
-    },
-    [getOwnTimestamp, pubkey],
-  );
+  const { clearChannelUnreadSource, markChannelUnread } =
+    useForcedUnreadActions(
+      forcedUnreadRef,
+      getOwnTimestamp,
+      pubkey,
+      bumpLatestVersion,
+    );
 
   // Record the thread root of an EXTERNAL message that @-mentioned the user.
   // Keyed on the thread root so the badge gate trips for a mention recipient
@@ -477,6 +471,22 @@ export function useUnreadChannels(
     [normalizedPubkey],
   );
 
+  const recordThreadInteraction = React.useCallback(
+    (rootId: string) => {
+      const normalizedRootId = rootId.trim();
+      if (!normalizedRootId) return;
+      const target = participatedRootIdsRef.current;
+      const sizeBefore = target.size;
+      target.add(normalizedRootId);
+      if (target.size === sizeBefore) return;
+      if (normalizedPubkey !== null) {
+        participationStore.write(normalizedPubkey, target);
+      }
+      bumpMembershipVersion();
+    },
+    [normalizedPubkey],
+  );
+
   const handleThreadReplyNotification = React.useCallback(
     (channelId: string, event: RelayEvent) => {
       // Guard: don't merge into a ref whose scope has drifted from the current
@@ -830,6 +840,7 @@ export function useUnreadChannels(
       if (!isReadStateReady) {
         return {
           unreadChannelIds: new Set<string>(),
+          topLevelUnreadChannelIds: new Set<string>(),
           highPriorityUnreadChannelIds: new Set<string>(),
           unreadChannelCounts: new Map<string, number>(),
           unreadChannelNotificationCount: 0,
@@ -837,6 +848,7 @@ export function useUnreadChannels(
       }
 
       const unread = new Set<string>();
+      const topLevelUnread = new Set<string>();
       const highPriority = new Set<string>();
       const counts = new Map<string, number>();
       let unreadChannelNotificationCount = 0;
@@ -844,15 +856,10 @@ export function useUnreadChannels(
       for (const channel of channels) {
         if (channel.id === activeChannelId) continue;
 
-        if (Object.hasOwn(forcedUnreadRef.current, channel.id)) {
-          // Forced-unread is dot tier only — not high-priority.
-          unread.add(channel.id);
-          counts.set(channel.id, 1);
-          unreadChannelNotificationCount += 1;
-          continue;
-        }
-
-        if (latestByChannelRef.current.get(channel.id) === undefined) continue;
+        const isForcedUnread = Object.hasOwn(
+          forcedUnreadRef.current,
+          channel.id,
+        );
 
         const observedEvents = observedUnreadEventsByChannelRef.current.get(
           channel.id,
@@ -866,13 +873,25 @@ export function useUnreadChannels(
             (messageId) => getOwnTimestamp(`msg:${messageId}`),
           );
 
-        const unreadCount = countUnreadObservedEvents(
-          observedEvents,
-          readAtForObservedEvent,
-        );
-        if (unreadCount === 0) continue;
+        const unreadCount =
+          latestByChannelRef.current.get(channel.id) === undefined
+            ? 0
+            : countUnreadObservedEvents(observedEvents, readAtForObservedEvent);
+        if (unreadCount === 0) {
+          if (!isForcedUnread) continue;
+          unread.add(channel.id);
+          topLevelUnread.add(channel.id);
+          counts.set(channel.id, 1);
+          unreadChannelNotificationCount += 1;
+          continue;
+        }
 
         unread.add(channel.id);
+        if (
+          hasUnreadTopLevelObservedEvent(observedEvents, readAtForObservedEvent)
+        ) {
+          topLevelUnread.add(channel.id);
+        }
         const badgeCount = countUnreadBadgeObservedEvents(
           observedEvents,
           readAtForObservedEvent,
@@ -900,6 +919,7 @@ export function useUnreadChannels(
 
       return {
         unreadChannelIds: unread,
+        topLevelUnreadChannelIds: topLevelUnread,
         highPriorityUnreadChannelIds: highPriority,
         unreadChannelCounts: counts,
         unreadChannelNotificationCount,
@@ -914,37 +934,14 @@ export function useUnreadChannels(
       readStateVersion,
     ]);
 
-  // Stabilize Set references: only replace when contents actually change,
-  // so downstream memos don't re-run on every render when sets are equal.
-  const prevUnreadRef = React.useRef<ReadonlySet<string>>(new Set());
-  const prevHighPriorityRef = React.useRef<ReadonlySet<string>>(new Set());
-  const prevUnreadCountsRef = React.useRef<ReadonlyMap<string, number>>(
-    new Map(),
+  const unreadChannelIds = useStableSet(rawUnread.unreadChannelIds);
+  const topLevelUnreadChannelIds = useStableSet(
+    rawUnread.topLevelUnreadChannelIds,
   );
-
-  const unreadChannelIds = setsEqual(
-    rawUnread.unreadChannelIds,
-    prevUnreadRef.current,
-  )
-    ? prevUnreadRef.current
-    : rawUnread.unreadChannelIds;
-  prevUnreadRef.current = unreadChannelIds;
-
-  const highPriorityUnreadChannelIds = setsEqual(
+  const highPriorityUnreadChannelIds = useStableSet(
     rawUnread.highPriorityUnreadChannelIds,
-    prevHighPriorityRef.current,
-  )
-    ? prevHighPriorityRef.current
-    : rawUnread.highPriorityUnreadChannelIds;
-  prevHighPriorityRef.current = highPriorityUnreadChannelIds;
-
-  const unreadChannelCounts = mapsEqual(
-    rawUnread.unreadChannelCounts,
-    prevUnreadCountsRef.current,
-  )
-    ? prevUnreadCountsRef.current
-    : rawUnread.unreadChannelCounts;
-  prevUnreadCountsRef.current = unreadChannelCounts;
+  );
+  const unreadChannelCounts = useStableMap(rawUnread.unreadChannelCounts);
   const unreadChannelNotificationCount =
     rawUnread.unreadChannelNotificationCount;
 
@@ -992,12 +989,14 @@ export function useUnreadChannels(
 
   return {
     unreadChannelIds,
+    topLevelUnreadChannelIds,
     unreadChannelCounts,
     highPriorityUnreadChannelIds,
     unreadChannelNotificationCount,
     markAllChannelsRead,
     markChannelRead,
     markChannelUnread,
+    clearChannelUnreadSource,
     // Exposed so other surfaces (e.g. Home) can project per-item read state
     // off the same NIP-RS read marker without instantiating a second
     // ReadStateManager. readStateVersion is the invalidation signal callers
@@ -1009,6 +1008,7 @@ export function useUnreadChannels(
     participatedRootIds,
     authoredRootIds,
     mentionedRootIds,
+    recordThreadInteraction,
     threadActivityItems: projectActivityForScope(
       threadActivityScopeRef.current,
       currentActivityScope,
diff --git a/desktop/src/features/communities/communityUnreadObserver.ts b/desktop/src/features/communities/communityUnreadObserver.ts
index 5bc3298413..e729831eac 100644
--- a/desktop/src/features/communities/communityUnreadObserver.ts
+++ b/desktop/src/features/communities/communityUnreadObserver.ts
@@ -1,5 +1,6 @@
 import { makeRootIdStore } from "@/features/channels/unreadRootIdStore";
 import {
+  forcedUnreadMarker,
   forcedUnreadStore,
   type ForcedUnreadMap,
 } from "@/features/channels/forcedUnreadStore";
@@ -238,7 +239,9 @@ export async function fetchCommunityUnread(args: {
     // runs while the community is active, so the store may not be pruned for
     // inactive communities).
     if (!hasUnread && Object.hasOwn(forcedUnreadMap, channel.id)) {
-      const markerAtWhenForced = forcedUnreadMap[channel.id];
+      const markerAtWhenForced = forcedUnreadMarker(
+        forcedUnreadMap[channel.id],
+      );
       if (
         readAt === null ||
         (markerAtWhenForced !== null && readAt <= markerAtWhenForced)
diff --git a/desktop/src/features/home/ui/HomeView.tsx b/desktop/src/features/home/ui/HomeView.tsx
index 0f7c851643..e415f8d3a8 100644
--- a/desktop/src/features/home/ui/HomeView.tsx
+++ b/desktop/src/features/home/ui/HomeView.tsx
@@ -234,13 +234,16 @@ export function HomeView({
     inboxListWidthPx,
   } = useResizableInboxListWidth();
   const {
+    clearChannelUnreadSource,
     getChannelReadAt,
     getThreadReadAt,
     getMessageReadAt,
     feedItemState,
     markChannelRead,
+    markChannelUnread,
     markMessageRead,
     markThreadRead,
+    recordThreadInteraction,
     readStateVersion,
   } = useAppShell();
   const { doneSet, markDone, markUnread, undoDone, undoUnread, unreadSet } =
@@ -383,7 +386,9 @@ export function HomeView({
       readStateVersion,
       localDoneSet: doneSet,
       localUnreadSet: unreadSet,
+      clearChannelUnreadSource,
       markChannelRead,
+      markChannelUnread,
       markMessageRead,
       markThreadRead,
       markDoneLocal: markDone,
@@ -861,6 +866,13 @@ export function HomeView({
                         eventId: message.id,
                         remove,
                       });
+                      if (!remove) {
+                        recordThreadInteraction(
+                          selectedItem?.conversationId ??
+                            message.rootId ??
+                            message.id,
+                        );
+                      }
                       await threadContext.refreshReactions();
                       await channelMessagesQuery.refetch();
                       onRefresh();
diff --git a/desktop/src/features/home/useHomeInboxReadState.test.mjs b/desktop/src/features/home/useHomeInboxReadState.test.mjs
index 4af181379a..77caecad0f 100644
--- a/desktop/src/features/home/useHomeInboxReadState.test.mjs
+++ b/desktop/src/features/home/useHomeInboxReadState.test.mjs
@@ -4,6 +4,7 @@ import test from "node:test";
 import {
   getGroupedChannelReadTimestamp,
   getGroupedInboxItemIds,
+  hasRemainingChannelUnreadOverride,
   hasGroupedUnreadOverride,
   resolveInboxItemReadAt,
 } from "./useHomeInboxReadState.ts";
@@ -125,6 +126,47 @@ test("grouped unread override matches any item represented by the row", () => {
   );
 });
 
+test("remaining channel unread override ignores the row being cleared", () => {
+  const firstReply = feedItem({
+    id: "first-reply",
+    createdAt: 200,
+    tags: [
+      ["h", CHANNEL_ID],
+      ["e", "first-root", "", "root"],
+      ["e", "first-parent", "", "reply"],
+    ],
+  });
+  const secondReply = feedItem({
+    id: "second-reply",
+    createdAt: 300,
+    tags: [
+      ["h", CHANNEL_ID],
+      ["e", "second-root", "", "root"],
+      ["e", "second-parent", "", "reply"],
+    ],
+  });
+  const items = [inboxItem([firstReply]), inboxItem([secondReply])];
+
+  assert.equal(
+    hasRemainingChannelUnreadOverride(
+      items,
+      new Set(["first-reply", "second-reply"]),
+      CHANNEL_ID,
+      new Set(["first-reply"]),
+    ),
+    true,
+  );
+  assert.equal(
+    hasRemainingChannelUnreadOverride(
+      items,
+      new Set(["first-reply"]),
+      CHANNEL_ID,
+      new Set(["first-reply"]),
+    ),
+    false,
+  );
+});
+
 test("thread inbox row without a marker ignores local done fallback", () => {
   const replyItem = feedItem({
     id: "reply-event",
diff --git a/desktop/src/features/home/useHomeInboxReadState.ts b/desktop/src/features/home/useHomeInboxReadState.ts
index 624e72a0f5..24d536e730 100644
--- a/desktop/src/features/home/useHomeInboxReadState.ts
+++ b/desktop/src/features/home/useHomeInboxReadState.ts
@@ -1,5 +1,6 @@
 import * as React from "react";
 
+import type { ForcedUnreadSource } from "@/features/channels/forcedUnreadStore";
 import type { InboxItem } from "@/features/home/lib/inbox";
 import {
   getThreadReference,
@@ -25,6 +26,17 @@ type UseHomeInboxReadStateOptions = {
   markChannelRead: (
     channelId: string,
     readAt: string | null | undefined,
+    options?: {
+      preserveForcedUnread?: boolean;
+      topLevelOnly?: boolean;
+    },
+  ) => void;
+  /** Force a channel's unread indicator without rolling back its NIP-RS marker. */
+  markChannelUnread: (channelId: string, source?: ForcedUnreadSource) => void;
+  /** Remove only the named owner of a channel's forced-unread indicator. */
+  clearChannelUnreadSource: (
+    channelId: string,
+    source: ForcedUnreadSource,
   ) => void;
   /** Advance the thread read marker to the given unix-seconds timestamp. */
   markThreadRead: (rootId: string, timestamp: number) => void;
@@ -32,7 +44,7 @@ type UseHomeInboxReadStateOptions = {
   markMessageRead: (messageId: string, timestamp: number) => void;
   /** Local fallback: mark a non-channel item done. */
   markDoneLocal: (id: string) => void;
-  /** Local inbox row override: mark an item unread without touching the channel. */
+  /** Local inbox row override: mark an item unread alongside its channel emphasis. */
   markUnreadLocal: (id: string) => void;
   /** Local fallback: undo a non-channel item done. */
   undoDoneLocal: (id: string) => void;
@@ -83,6 +95,21 @@ export function hasGroupedUnreadOverride(
   return getGroupedInboxItemIds(item).some((id) => localUnreadSet.has(id));
 }
 
+export function hasRemainingChannelUnreadOverride(
+  items: InboxItem[],
+  localUnreadSet: ReadonlySet<string>,
+  channelId: string,
+  clearedItemIds: ReadonlySet<string>,
+): boolean {
+  return items.some(
+    (candidate) =>
+      candidate.item.channelId === channelId &&
+      getGroupedInboxItemIds(candidate).some(
+        (id) => localUnreadSet.has(id) && !clearedItemIds.has(id),
+      ),
+  );
+}
+
 export function resolveInboxItemReadAt(
   item: InboxItem,
   options: {
@@ -114,8 +141,8 @@ export function resolveInboxItemReadAt(
  * "Mark as read" on channel-backed items is routed through `markChannelRead`;
  * thread rows advance the same per-message markers as the channel thread
  * panel, plus the aggregate `thread:<root>` marker for compatibility. "Mark
- * unread" is item-local: it only reopens the specific inbox row and must not
- * light up the channel.
+ * unread" keeps its per-item local override and also restores the source
+ * channel's forced-unread indicator so channel surfaces agree with Inbox.
  */
 export function useHomeInboxReadState({
   items,
@@ -126,6 +153,8 @@ export function useHomeInboxReadState({
   localDoneSet,
   localUnreadSet = EMPTY_ITEM_SET,
   markChannelRead,
+  markChannelUnread,
+  clearChannelUnreadSource,
   markThreadRead,
   markMessageRead,
   markDoneLocal,
@@ -182,9 +211,22 @@ export function useHomeInboxReadState({
     (itemId: string) => {
       const item = itemById.get(itemId);
       const localUnreadIds = item ? getGroupedInboxItemIds(item) : [itemId];
+      const clearedItemIds = new Set(localUnreadIds);
       for (const id of localUnreadIds) {
         undoUnreadLocal(id);
       }
+      const channelId = item?.item.channelId ?? null;
+      if (
+        channelId &&
+        !hasRemainingChannelUnreadOverride(
+          items,
+          localUnreadSet,
+          channelId,
+          clearedItemIds,
+        )
+      ) {
+        clearChannelUnreadSource(channelId, "inbox");
+      }
       const threadRootId = item ? getInboxThreadRootId(item) : null;
       if (item && threadRootId) {
         const markedReplyIds = new Set<string>();
@@ -201,16 +243,17 @@ export function useHomeInboxReadState({
           markChannelRead(
             groupedChannelRead.channelId,
             new Date(groupedChannelRead.timestamp * 1_000).toISOString(),
+            { preserveForcedUnread: true, topLevelOnly: true },
           );
         }
         return;
       }
 
-      const channelId = item?.item.channelId ?? null;
       if (item && channelId) {
         markChannelRead(
           channelId,
           new Date(item.latestActivityAt * 1_000).toISOString(),
+          { preserveForcedUnread: true },
         );
         return;
       }
@@ -218,6 +261,9 @@ export function useHomeInboxReadState({
     },
     [
       itemById,
+      items,
+      clearChannelUnreadSource,
+      localUnreadSet,
       markChannelRead,
       markDoneLocal,
       markMessageRead,
@@ -230,8 +276,17 @@ export function useHomeInboxReadState({
     (itemId: string) => {
       undoDoneLocal(itemId);
       markUnreadLocal(itemId);
+      const item = itemById.get(itemId);
+      const channelId = item?.item.channelId ?? null;
+      // The Inbox override owns the durable thread dot, while the channel force
+      // restores timeline-level emphasis after the user leaves the channel.
+      // Opening the channel clears the bolding but leaves the thread dot until
+      // the thread itself is opened or marked read.
+      if (channelId && item) {
+        markChannelUnread(channelId, "inbox");
+      }
     },
-    [markUnreadLocal, undoDoneLocal],
+    [itemById, markChannelUnread, markUnreadLocal, undoDoneLocal],
   );
 
   return { effectiveDoneSet, markItemRead, markItemUnread };
diff --git a/desktop/src/features/huddle/lib/ttsLiveMessages.test.mjs b/desktop/src/features/huddle/lib/ttsLiveMessages.test.mjs
index 3cd95eb3df..8bacceff9c 100644
--- a/desktop/src/features/huddle/lib/ttsLiveMessages.test.mjs
+++ b/desktop/src/features/huddle/lib/ttsLiveMessages.test.mjs
@@ -3,7 +3,7 @@ import test from "node:test";
 
 import {
   classifySpeakableAgentText,
-  createInitialMembershipGate,
+  createInitialTtsReadinessGate,
   createLatestStateGate,
   createOrderedSpeaker,
   routeLiveAgentText,
@@ -221,27 +221,51 @@ test("a live TTS state event supersedes a delayed bootstrap result", () => {
   assert.deepEqual(applied, [false]);
 });
 
-test("buffers initial live events until membership resolves in order", () => {
+test("buffers initial live events until membership and TTS state resolve", () => {
   const delivered = [];
-  const gate = createInitialMembershipGate((event) => delivered.push(event));
+  const gate = createInitialTtsReadinessGate((event) => delivered.push(event));
   gate.push("first");
   gate.push("second");
   assert.deepEqual(delivered, []);
-  gate.succeed();
+  gate.markMembershipKnown();
+  assert.deepEqual(delivered, []);
+  gate.markTtsStateKnown();
   gate.push("third");
   assert.deepEqual(delivered, ["first", "second", "third"]);
 });
 
-test("drops the initial buffer fail-closed when membership lookup fails", () => {
+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 = createInitialMembershipGate(
+  const gate = createInitialTtsReadinessGate(
     (event) => delivered.push(event),
-    (event) => dropped.push(event),
+    (event, reason) => dropped.push({ event, reason }),
   );
   gate.push("unverified");
-  gate.fail();
+  gate.fail("tts_state_unavailable");
   gate.push("after-failure");
   assert.deepEqual(delivered, ["after-failure"]);
-  assert.deepEqual(dropped, ["unverified"]);
+  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
index b809afee2c..5a5a29afa5 100644
--- a/desktop/src/features/huddle/lib/ttsLiveMessages.ts
+++ b/desktop/src/features/huddle/lib/ttsLiveMessages.ts
@@ -152,34 +152,49 @@ export function createLatestStateGate<T>(apply: (value: T) => void): {
   };
 }
 
-/** Hold live events until the first authoritative agent-membership lookup. */
-export function createInitialMembershipGate<T>(
+/** Hold live events until initial membership and TTS state are both known. */
+export function createInitialTtsReadinessGate<T>(
   deliver: (event: T) => void,
-  drop: (event: T) => void = () => {},
+  drop: (
+    event: T,
+    reason: "membership_unavailable" | "tts_state_unavailable",
+  ) => void = () => {},
 ): {
   push: (event: T) => void;
-  succeed: () => void;
-  fail: () => 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);
     },
-    succeed() {
-      if (settled) return;
-      settled = true;
-      const buffered = pending;
-      pending = [];
-      for (const event of buffered) deliver(event);
+    markMembershipKnown() {
+      membershipKnown = true;
+      releaseIfReady();
     },
-    fail() {
+    markTtsStateKnown() {
+      ttsStateKnown = true;
+      releaseIfReady();
+    },
+    fail(reason) {
+      if (settled) return;
       settled = true;
       const dropped = pending;
       pending = [];
-      for (const event of dropped) drop(event);
+      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 c77b2cfab7..64fb96efcd 100644
--- a/desktop/src/features/huddle/lib/useTtsSubscription.ts
+++ b/desktop/src/features/huddle/lib/useTtsSubscription.ts
@@ -5,7 +5,7 @@ import * as React from "react";
 import { buildHuddleTtsLiveFilter } from "@/shared/api/relayChannelFilters";
 import { relayClient } from "@/shared/api/relayClient";
 import {
-  createInitialMembershipGate,
+  createInitialTtsReadinessGate,
   createLatestStateGate,
   createOrderedSpeaker,
   routeLiveAgentText,
@@ -114,11 +114,11 @@ export function useTtsSubscription(
         );
       }
     };
-    const initialMembershipGate = createInitialMembershipGate(
+    const initialReadinessGate = createInitialTtsReadinessGate(
       deliver,
-      ({ routeId }) => {
+      ({ routeId }, reason) => {
         console.debug(
-          `[huddle] tts stage=eligibility status=rejected reason=membership_unavailable route_id=${routeId}`,
+          `[huddle] tts stage=eligibility status=rejected reason=${reason} route_id=${routeId}`,
         );
       },
     );
@@ -131,7 +131,7 @@ export function useTtsSubscription(
         for (const pk of pubkeys) agentPubkeys.add(pk);
         agentsLoaded = true;
         if (initial) {
-          initialMembershipGate.succeed();
+          initialReadinessGate.markMembershipKnown();
         }
       } catch (e) {
         // Fail-closed on ALL failures, including refresh after prior success.
@@ -140,7 +140,7 @@ export function useTtsSubscription(
         agentPubkeys.clear();
         agentsLoaded = false;
         if (initial) {
-          initialMembershipGate.fail();
+          initialReadinessGate.fail("membership_unavailable");
         }
         console.error("[huddle] Failed to load agent pubkeys:", e);
       }
@@ -159,6 +159,7 @@ export function useTtsSubscription(
         if (!disposed) {
           ttsStateKnown = true;
           speakInOrder.setEnabled(state.tts_enabled);
+          initialReadinessGate.markTtsStateKnown();
         }
       },
     );
@@ -177,11 +178,14 @@ export function useTtsSubscription(
             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);
       });
 
@@ -204,15 +208,15 @@ export function useTtsSubscription(
           if (oldest !== undefined) seenEventIds.delete(oldest);
         }
 
-        // Preserve arrival order while the initial authoritative membership
-        // lookup is pending. A failed lookup clears this buffer fail-closed.
+        // 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}`,
           );
         }
-        initialMembershipGate.push({ event, routeId });
+        initialReadinessGate.push({ event, routeId });
       })
       .then((dispose) => {
         if (disposed) {
diff --git a/desktop/src/features/messages/ui/MessageRow.tsx b/desktop/src/features/messages/ui/MessageRow.tsx
index 688b5d5f0d..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:
diff --git a/desktop/src/features/messages/ui/MessageThreadPanel.tsx b/desktop/src/features/messages/ui/MessageThreadPanel.tsx
index 6234af22d1..85a6f6b930 100644
--- a/desktop/src/features/messages/ui/MessageThreadPanel.tsx
+++ b/desktop/src/features/messages/ui/MessageThreadPanel.tsx
@@ -755,6 +755,7 @@ export function MessageThreadPanel({
                         onMarkUnread={onMarkUnread}
                         onMarkRead={onMarkRead}
                         onReply={onSelectReplyTarget}
+                        onOpenThread={onExpandReplies}
                         onToggleReaction={onToggleReaction}
                         profiles={profiles}
                         showDepthGuides={shouldShowThreadBranchGuides}
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/TimelineMessageList.tsx b/desktop/src/features/messages/ui/TimelineMessageList.tsx
index b724d995eb..89183d0856 100644
--- a/desktop/src/features/messages/ui/TimelineMessageList.tsx
+++ b/desktop/src/features/messages/ui/TimelineMessageList.tsx
@@ -77,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,
@@ -142,6 +143,7 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
   onMarkUnread,
   onMarkRead,
   onReply,
+  onOpenThread,
   isSendingVideoReviewComment = false,
   onSendVideoReviewComment,
   onToggleReaction,
@@ -255,6 +257,7 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
               onMarkRead={onMarkRead}
               onMarkUnread={onMarkUnread}
               onReply={onReply}
+              onOpenThread={onOpenThread}
               onToggleReaction={onToggleReaction}
               profiles={profiles}
               searchActiveMessageId={searchActiveMessageId}
@@ -286,6 +289,7 @@ export const TimelineMessageList = React.memo(function TimelineMessageList({
       onMarkRead,
       onMarkUnread,
       onReply,
+      onOpenThread,
       onToggleReaction,
       profiles,
       ownerProfiles,
@@ -699,6 +703,7 @@ type MessageRowItemProps = Pick<
   | "onMarkUnread"
   | "onMarkRead"
   | "onReply"
+  | "onOpenThread"
   | "onToggleReaction"
   | "profiles"
   | "searchActiveMessageId"
@@ -737,6 +742,7 @@ function MessageRowItem({
   onMarkUnread,
   onMarkRead,
   onReply,
+  onOpenThread,
   onToggleReaction,
   profiles,
   searchActiveMessageId,
@@ -755,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
@@ -790,6 +796,7 @@ function MessageRowItem({
           onMarkUnread={onMarkUnread}
           onToggleReaction={onToggleReaction}
           onReply={onReply}
+          onOpenThread={onOpenThread}
           onUnfollowThread={
             unfollowThreadById
               ? () => unfollowThreadById(message.id)
@@ -802,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}
@@ -839,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/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/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/ui/ChannelTemplatesSettingsCard.tsx b/desktop/src/features/settings/ui/ChannelTemplatesSettingsCard.tsx
index 82680ae5a8..3b7da93df2 100644
--- a/desktop/src/features/settings/ui/ChannelTemplatesSettingsCard.tsx
+++ b/desktop/src/features/settings/ui/ChannelTemplatesSettingsCard.tsx
@@ -276,14 +276,16 @@ function TemplateRow({
   );
 }
 
-function TemplateFormDialog({
+export function TemplateFormDialog({
   template,
   open,
   onOpenChange,
+  onCreated,
 }: {
   template: ChannelTemplate | null;
   open: boolean;
   onOpenChange: (open: boolean) => void;
+  onCreated?: (template: ChannelTemplate) => void;
 }) {
   const isEditing = template !== null;
   const createMutation = useCreateChannelTemplateMutation();
@@ -388,8 +390,9 @@ function TemplateFormDialog({
       };
 
       createMutation.mutate(input, {
-        onSuccess: () => {
+        onSuccess: (created) => {
           toast.success(`Created "${trimmedName}"`);
+          onCreated?.(created);
           onOpenChange(false);
         },
         onError: (error) => {
diff --git a/desktop/src/features/settings/ui/SettingsPanels.tsx b/desktop/src/features/settings/ui/SettingsPanels.tsx
index 5c997efbc4..162150e7c6 100644
--- a/desktop/src/features/settings/ui/SettingsPanels.tsx
+++ b/desktop/src/features/settings/ui/SettingsPanels.tsx
@@ -189,7 +189,7 @@ export const settingsSections: SettingsSectionDescriptor[] = [
   },
   {
     value: "channel-templates",
-    label: "Templates",
+    label: "Channel templates",
     icon: LayoutTemplate,
     featureGate: "channel-templates",
   },
diff --git a/desktop/src/features/settings/ui/SettingsView.tsx b/desktop/src/features/settings/ui/SettingsView.tsx
index 8613880571..991029dca7 100644
--- a/desktop/src/features/settings/ui/SettingsView.tsx
+++ b/desktop/src/features/settings/ui/SettingsView.tsx
@@ -62,11 +62,12 @@ const settingsNavGroups: Array<{
       "shortcuts",
       "custom-emoji",
       "local-archive",
+      "channel-templates",
     ],
   },
   {
     label: "Communities",
-    sections: ["hosted-communities", "channel-templates", "community-members"],
+    sections: ["hosted-communities", "community-members"],
   },
   {
     label: "App",
diff --git a/desktop/src/features/sidebar/lib/useActiveWorkingChannelsById.ts b/desktop/src/features/sidebar/lib/useActiveWorkingChannelsById.ts
index 37a3c86656..9b4c3c7804 100644
--- a/desktop/src/features/sidebar/lib/useActiveWorkingChannelsById.ts
+++ b/desktop/src/features/sidebar/lib/useActiveWorkingChannelsById.ts
@@ -2,7 +2,10 @@ import * as React from "react";
 
 import type { ActiveChannelTurnSummary } from "@/features/agents/activeAgentTurnsStore";
 import { useWorkingChannels } from "@/features/agents/agentWorkingSignal";
-import { useManagedAgentsQuery } from "@/features/agents/hooks";
+import {
+  useManagedAgentsQuery,
+  useRelayAgentsQuery,
+} from "@/features/agents/hooks";
 import { normalizePubkey } from "@/shared/lib/pubkey";
 
 export function resolveActiveWorkingChannelNames(
@@ -27,10 +30,15 @@ export function useActiveWorkingChannelsById(): ReadonlyMap<
   ActiveChannelTurnSummary
 > {
   const managedAgentsQuery = useManagedAgentsQuery();
+  const relayAgentsQuery = useRelayAgentsQuery();
   const managedAgents = React.useMemo(
     () => managedAgentsQuery.data ?? [],
     [managedAgentsQuery.data],
   );
+  const namedAgents = React.useMemo(
+    () => [...(relayAgentsQuery.data ?? []), ...managedAgents],
+    [managedAgents, relayAgentsQuery.data],
+  );
 
   // Unified working signal: observer-derived turns primary, bot typing as
   // fallback — so the sidebar badge appears even for agents whose observer
@@ -42,11 +50,11 @@ export function useActiveWorkingChannelsById(): ReadonlyMap<
         activeWorkingChannels.map((summary) => {
           const resolvedSummary = resolveActiveWorkingChannelNames(
             summary,
-            managedAgents,
+            namedAgents,
           );
           return [resolvedSummary.channelId, resolvedSummary];
         }),
       ),
-    [activeWorkingChannels, managedAgents],
+    [activeWorkingChannels, namedAgents],
   );
 }
diff --git a/desktop/src/features/sidebar/lib/useCreateChannelForm.ts b/desktop/src/features/sidebar/lib/useCreateChannelForm.ts
index b227c0ae32..af03b9e4dd 100644
--- a/desktop/src/features/sidebar/lib/useCreateChannelForm.ts
+++ b/desktop/src/features/sidebar/lib/useCreateChannelForm.ts
@@ -46,6 +46,7 @@ export type CreateChannelFormState = {
   errorMessage: string | null;
   selectedTemplateId: string | null;
   handleTemplateChange: (templateId: string) => void;
+  handleTemplateCreated: (template: ChannelTemplate) => void;
   templates: ChannelTemplate[];
   nameInputRef: React.RefObject<HTMLInputElement | null>;
   isCreating: boolean;
@@ -120,6 +121,13 @@ export function useCreateChannelForm({
     return () => globalThis.clearTimeout(timerId);
   }, [active, autoFocusName, initialName]);
 
+  const applyTemplate = React.useCallback((template: ChannelTemplate) => {
+    setSelectedTemplateId(template.id);
+    setDescription(template.description ?? "");
+    if (!visibilityTouchedRef.current) setVisibility(template.visibility);
+    setErrorMessage(null);
+  }, []);
+
   const handleTemplateChange = React.useCallback(
     (templateId: string) => {
       if (!templateId) {
@@ -135,12 +143,9 @@ export function useCreateChannelForm({
       );
       if (!template) return;
 
-      setSelectedTemplateId(templateId);
-      setDescription(template.description ?? "");
-      if (!visibilityTouchedRef.current) setVisibility(template.visibility);
-      setErrorMessage(null);
+      applyTemplate(template);
     },
-    [templates],
+    [applyTemplate, templates],
   );
 
   const handleSubmit = React.useCallback(
@@ -211,6 +216,7 @@ export function useCreateChannelForm({
     errorMessage,
     selectedTemplateId,
     handleTemplateChange,
+    handleTemplateCreated: applyTemplate,
     templates,
     nameInputRef,
     isCreating,
diff --git a/desktop/src/features/sidebar/ui/ChannelActivityPopover.tsx b/desktop/src/features/sidebar/ui/ChannelActivityPopover.tsx
new file mode 100644
index 0000000000..1e50ef72ee
--- /dev/null
+++ b/desktop/src/features/sidebar/ui/ChannelActivityPopover.tsx
@@ -0,0 +1,448 @@
+import * as React from "react";
+import { Clock, Loader2, MailOpen } from "lucide-react";
+
+import { useAppShell } from "@/app/AppShellContext";
+import { useAppNavigation } from "@/app/navigation/useAppNavigation";
+import type { ActiveChannelTurnSummary } from "@/features/agents/activeAgentTurnsStore";
+import { formatElapsed } from "@/features/agents/ui/agentSessionUtils";
+import { useOpenAgentActivity } from "@/features/agents/useOpenAgentActivity";
+import { buildInboxItems, type InboxItem } from "@/features/home/lib/inbox";
+import { getGroupedInboxItemIds } from "@/features/home/useHomeInboxReadState";
+import { useUsersBatchQuery } from "@/features/profile/hooks";
+import type { UserProfileLookup } from "@/features/profile/lib/identity";
+import { useRemindLater } from "@/features/reminders/ui/RemindMeLaterProvider";
+import { useIdentityQuery } from "@/shared/api/hooks";
+import type { Channel, FeedItem, HomeFeedResponse } from "@/shared/api/types";
+import { normalizePubkey, truncatePubkey } from "@/shared/lib/pubkey";
+import { useNow } from "@/shared/lib/useNow";
+import { Markdown } from "@/shared/ui/markdown";
+import { Popover, PopoverAnchor, PopoverContent } from "@/shared/ui/popover";
+import { UserAvatar } from "@/shared/ui/UserAvatar";
+
+const HOVER_OPEN_DELAY_MS = 250;
+const HOVER_CLOSE_DELAY_MS = 180;
+
+function buildChannelActivityFeed(items: FeedItem[]): HomeFeedResponse {
+  return {
+    feed: {
+      mentions: items.filter((item) => item.category === "mention"),
+      needsAction: items.filter((item) => item.category === "needs_action"),
+      activity: items.filter(
+        (item) =>
+          item.category !== "mention" &&
+          item.category !== "needs_action" &&
+          item.category !== "agent_activity",
+      ),
+      agentActivity: items.filter((item) => item.category === "agent_activity"),
+    },
+    meta: {
+      since: 0,
+      total: items.length,
+      generatedAt: 0,
+    },
+  };
+}
+
+function RowActionButton({
+  children,
+  label,
+  onClick,
+}: {
+  children: React.ReactNode;
+  label: string;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      aria-label={label}
+      className="inline-flex size-7 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-background/80 hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring [&>svg]:size-4"
+      onClick={(event) => {
+        event.preventDefault();
+        event.stopPropagation();
+        onClick();
+      }}
+      title={label}
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}
+
+function ThreadPreviewRow({
+  item,
+  onMarkRead,
+  onOpen,
+  onRemindLater,
+}: {
+  item: InboxItem;
+  onMarkRead: () => void;
+  onOpen: () => void;
+  onRemindLater: () => void;
+}) {
+  return (
+    <div
+      className="group/activity-row relative border-t border-border/50 first:border-t-0"
+      data-testid={`channel-activity-item-${item.conversationId}`}
+    >
+      <button
+        aria-label={`Open thread from ${item.senderLabel}`}
+        className="absolute inset-0 z-0 w-full text-left"
+        onClick={onOpen}
+        type="button"
+      />
+      <div className="pointer-events-none relative z-10 flex min-w-0 items-start gap-2.5 px-3 py-3 transition-colors group-hover/activity-row:bg-muted/50 group-focus-within/activity-row:bg-muted/50">
+        <UserAvatar
+          avatarUrl={item.avatarUrl}
+          className="h-9 w-9 shrink-0"
+          displayName={item.senderLabel}
+          size="md"
+        />
+        <div className="min-w-0 flex-1">
+          <div className="flex min-w-0 items-start gap-2">
+            <span className="min-w-0 flex-1 truncate text-sm font-semibold leading-4 text-foreground">
+              {item.senderLabel}
+            </span>
+            <span className="shrink-0 text-xs leading-4 text-muted-foreground/70 transition-opacity group-hover/activity-row:opacity-0 group-focus-within/activity-row:opacity-0">
+              {item.timestampLabel}
+            </span>
+          </div>
+          <div className="mt-0.5 flex items-center gap-1.5 text-xs leading-4 text-muted-foreground">
+            <span>Thread</span>
+            {item.unreadCount > 1 ? (
+              <>
+                <span aria-hidden="true">·</span>
+                <span>{item.unreadCount} unread</span>
+              </>
+            ) : null}
+          </div>
+          <Markdown
+            className="inbox-preview-markdown mt-1.5 line-clamp-2 text-sm font-medium leading-5 text-foreground"
+            content={item.preview}
+            interactive={false}
+            mentionNames={item.mentionNames}
+          />
+        </div>
+      </div>
+      <div className="pointer-events-none absolute right-2 top-2 z-20 flex items-center gap-0.5 rounded-full bg-muted/95 p-0.5 opacity-0 shadow-xs transition-opacity group-hover/activity-row:pointer-events-auto group-hover/activity-row:opacity-100 group-focus-within/activity-row:pointer-events-auto group-focus-within/activity-row:opacity-100">
+        <RowActionButton label="Mark as read" onClick={onMarkRead}>
+          <MailOpen />
+        </RowActionButton>
+        <RowActionButton label="Remind me later" onClick={onRemindLater}>
+          <Clock />
+        </RowActionButton>
+      </div>
+    </div>
+  );
+}
+
+function WorkingAgentRow({
+  avatarUrl,
+  elapsed,
+  name,
+  onOpen,
+  pubkey,
+}: {
+  avatarUrl: string | null;
+  elapsed: string;
+  name: string;
+  onOpen: () => void;
+  pubkey: string;
+}) {
+  return (
+    <button
+      className="flex w-full min-w-0 items-start gap-2.5 border-t border-border/50 px-3 py-3 text-left transition-colors first:border-t-0 hover:bg-muted/50 focus-visible:bg-muted/50 focus-visible:outline-hidden"
+      data-testid={`channel-activity-agent-${pubkey}`}
+      onClick={onOpen}
+      type="button"
+    >
+      <UserAvatar
+        avatarUrl={avatarUrl}
+        className="h-9 w-9 shrink-0"
+        displayName={name}
+        size="md"
+      />
+      <div className="min-w-0 flex-1">
+        <div className="flex min-w-0 items-start gap-2">
+          <span className="min-w-0 flex-1 truncate text-sm font-semibold leading-4 text-foreground">
+            {name}
+          </span>
+          <span className="shrink-0 text-xs leading-4 text-muted-foreground/70">
+            {elapsed}
+          </span>
+        </div>
+        <span className="mt-0.5 flex items-center gap-1.5 text-xs leading-4 text-muted-foreground">
+          <Loader2 className="h-3.5 w-3.5 animate-spin text-primary/70" />
+          Working
+        </span>
+      </div>
+    </button>
+  );
+}
+
+function WorkingAgentRows({
+  activeWorking,
+  channelId,
+  onOpen,
+  profiles,
+}: {
+  activeWorking: ActiveChannelTurnSummary;
+  channelId: string;
+  onOpen: (pubkey: string, channelId: string) => void;
+  profiles?: UserProfileLookup;
+}) {
+  const now = useNow(1000);
+  const elapsed = formatElapsed(now - activeWorking.anchorAt);
+  const alignedAgentNames =
+    activeWorking.agentNames?.length === activeWorking.agentPubkeys.length
+      ? activeWorking.agentNames
+      : null;
+
+  return activeWorking.agentPubkeys.map((pubkey, index) => {
+    const profile = profiles?.[normalizePubkey(pubkey)];
+    const name =
+      profile?.displayName?.trim() ||
+      alignedAgentNames?.[index] ||
+      `Agent ${truncatePubkey(pubkey)}`;
+    return (
+      <WorkingAgentRow
+        avatarUrl={profile?.avatarUrl ?? null}
+        elapsed={elapsed}
+        key={pubkey}
+        name={name}
+        onOpen={() => onOpen(pubkey, channelId)}
+        pubkey={pubkey}
+      />
+    );
+  });
+}
+
+export function ChannelActivityPopover({
+  activeWorking,
+  channel,
+  children,
+}: {
+  activeWorking?: ActiveChannelTurnSummary;
+  channel: Channel;
+  children: React.ReactNode;
+}) {
+  const [open, setOpen] = React.useState(false);
+  const hoverTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(
+    null,
+  );
+  const {
+    clearChannelUnreadSource,
+    getChannelActivityItemReadAt,
+    locallyUnreadFeedItems,
+    markMessageRead,
+    markThreadRead,
+    unreadThreadFeedItems,
+    feedItemState,
+  } = useAppShell();
+  const { undoUnread } = feedItemState;
+  const identityQuery = useIdentityQuery();
+  const { goChannel } = useAppNavigation();
+  const { openAgentActivity } = useOpenAgentActivity();
+  const { openReminder } = useRemindLater();
+
+  const unreadChannelFeedItems = React.useMemo(() => {
+    return unreadThreadFeedItems.filter(
+      (item) => item.channelId === channel.id,
+    );
+  }, [channel.id, unreadThreadFeedItems]);
+  const profilePubkeys = React.useMemo(
+    () => [
+      ...new Set([
+        ...unreadChannelFeedItems.map((item) => item.pubkey),
+        ...(activeWorking?.agentPubkeys ?? []),
+      ]),
+    ],
+    [activeWorking?.agentPubkeys, unreadChannelFeedItems],
+  );
+  const profilesQuery = useUsersBatchQuery(open ? profilePubkeys : [], {
+    enabled: open,
+  });
+  const profiles = profilesQuery.data?.profiles;
+  const activityReadAtByMessageId = React.useMemo(
+    () =>
+      new Map(
+        unreadChannelFeedItems.map((item) => [
+          item.id,
+          getChannelActivityItemReadAt(item),
+        ]),
+      ),
+    [getChannelActivityItemReadAt, unreadChannelFeedItems],
+  );
+  const activityItems = React.useMemo(() => {
+    if (!open) return [];
+    return buildInboxItems({
+      channels: [channel],
+      currentPubkey: identityQuery.data?.pubkey,
+      feed: buildChannelActivityFeed(unreadChannelFeedItems),
+      getMessageReadAt: (messageId) =>
+        activityReadAtByMessageId.get(messageId) ?? null,
+      profiles,
+    });
+  }, [
+    channel,
+    activityReadAtByMessageId,
+    identityQuery.data?.pubkey,
+    open,
+    profiles,
+    unreadChannelFeedItems,
+  ]);
+  const hasContent =
+    unreadChannelFeedItems.length > 0 ||
+    (activeWorking?.agentPubkeys.length ?? 0) > 0;
+
+  const clearHoverTimer = React.useCallback(() => {
+    if (hoverTimerRef.current !== null) {
+      clearTimeout(hoverTimerRef.current);
+      hoverTimerRef.current = null;
+    }
+  }, []);
+  const openWithDelay = React.useCallback(() => {
+    if (!hasContent) return;
+    clearHoverTimer();
+    hoverTimerRef.current = setTimeout(() => {
+      setOpen(true);
+    }, HOVER_OPEN_DELAY_MS);
+  }, [clearHoverTimer, hasContent]);
+  const openImmediately = React.useCallback(() => {
+    if (!hasContent) return;
+    clearHoverTimer();
+    setOpen(true);
+  }, [clearHoverTimer, hasContent]);
+  const closeWithDelay = React.useCallback(() => {
+    clearHoverTimer();
+    hoverTimerRef.current = setTimeout(() => {
+      setOpen(false);
+    }, HOVER_CLOSE_DELAY_MS);
+  }, [clearHoverTimer]);
+  const keepOpen = React.useCallback(() => {
+    clearHoverTimer();
+  }, [clearHoverTimer]);
+
+  React.useEffect(() => () => clearHoverTimer(), [clearHoverTimer]);
+  React.useEffect(() => {
+    if (!hasContent) {
+      setOpen(false);
+    }
+  }, [hasContent]);
+
+  const clearUnreadOverride = React.useCallback(
+    (item: InboxItem) => {
+      const clearedItemIds = new Set(getGroupedInboxItemIds(item));
+      for (const itemId of clearedItemIds) {
+        undoUnread(itemId);
+      }
+      const channelId = item.item.channelId ?? null;
+      const hasAnotherChannelOverride = locallyUnreadFeedItems.some(
+        (feedItem) =>
+          feedItem.channelId === channelId && !clearedItemIds.has(feedItem.id),
+      );
+      if (channelId && !hasAnotherChannelOverride) {
+        clearChannelUnreadSource(channelId, "inbox");
+      }
+    },
+    [clearChannelUnreadSource, locallyUnreadFeedItems, undoUnread],
+  );
+
+  const handleMarkRead = React.useCallback(
+    (item: InboxItem) => {
+      clearUnreadOverride(item);
+      for (const reply of item.groupItems) {
+        markMessageRead(reply.id, reply.createdAt);
+      }
+      markThreadRead(item.conversationId, item.latestActivityAt);
+    },
+    [clearUnreadOverride, markMessageRead, markThreadRead],
+  );
+
+  if (!hasContent) {
+    return children;
+  }
+
+  return (
+    <Popover onOpenChange={setOpen} open={open}>
+      <PopoverAnchor asChild>
+        {/* biome-ignore lint/a11y/noStaticElementInteractions: hover/focus events bubble from the nested channel button while this wrapper supplies the popover anchor box. */}
+        <div
+          className="w-full min-w-0"
+          onBlur={closeWithDelay}
+          onContextMenu={() => setOpen(false)}
+          onFocus={openImmediately}
+          onMouseEnter={openWithDelay}
+          onMouseLeave={closeWithDelay}
+        >
+          {children}
+        </div>
+      </PopoverAnchor>
+      <PopoverContent
+        align="start"
+        className="w-96 overflow-hidden p-0"
+        data-testid={`channel-activity-popover-${channel.name}`}
+        onFocusCapture={keepOpen}
+        onMouseEnter={keepOpen}
+        onMouseLeave={closeWithDelay}
+        onOpenAutoFocus={(event) => event.preventDefault()}
+        side="right"
+        sideOffset={8}
+      >
+        <section
+          aria-label="Channel activity"
+          className="flex max-h-96 min-h-0 flex-col overflow-hidden"
+        >
+          <h3
+            className="relative z-20 shrink-0 border-b border-border/70 bg-background/95 px-3 py-2 text-sm font-semibold text-foreground backdrop-blur-md supports-[backdrop-filter]:bg-background/90"
+            data-testid="channel-activity-header"
+          >
+            Channel activity
+          </h3>
+          <div
+            className="buzz-channel-activity-scrollbar min-h-0 overflow-y-auto overscroll-contain"
+            data-testid="channel-activity-scroll"
+          >
+            {activeWorking?.agentPubkeys.length ? (
+              <WorkingAgentRows
+                activeWorking={activeWorking}
+                channelId={channel.id}
+                onOpen={(pubkey, channelId) => {
+                  setOpen(false);
+                  openAgentActivity(pubkey, { channelId });
+                }}
+                profiles={profiles}
+              />
+            ) : null}
+            {activityItems.length > 0
+              ? activityItems.map((item) => (
+                  <ThreadPreviewRow
+                    item={item}
+                    key={item.conversationId}
+                    onMarkRead={() => handleMarkRead(item)}
+                    onOpen={() => {
+                      clearUnreadOverride(item);
+                      setOpen(false);
+                      void goChannel(channel.id, {
+                        messageId: item.id,
+                        threadRootId: item.conversationId,
+                      });
+                    }}
+                    onRemindLater={() => {
+                      setOpen(false);
+                      openReminder({
+                        authorPubkey: item.item.pubkey,
+                        channelId: channel.id,
+                        eventId: item.id,
+                        preview: item.preview.slice(0, 100),
+                      });
+                    }}
+                  />
+                ))
+              : null}
+          </div>
+        </section>
+      </PopoverContent>
+    </Popover>
+  );
+}
diff --git a/desktop/src/features/sidebar/ui/ChannelContextMenu.tsx b/desktop/src/features/sidebar/ui/ChannelContextMenu.tsx
index 76cae3ed38..78f3929f19 100644
--- a/desktop/src/features/sidebar/ui/ChannelContextMenu.tsx
+++ b/desktop/src/features/sidebar/ui/ChannelContextMenu.tsx
@@ -15,6 +15,7 @@ import {
   TriangleAlert,
 } from "lucide-react";
 
+import { useAppShell } from "@/app/AppShellContext";
 import {
   useArchiveChannelMutation,
   useChannelMembersQuery,
@@ -178,6 +179,22 @@ export function ChannelContextMenuItems({
   onDeleteChannel?: (channel: Channel) => void;
   onLeaveChannel?: (channel: Channel) => void;
 }) {
+  const {
+    feedItemState,
+    hasSidebarUnreadProjections,
+    locallyUnreadFeedItems,
+    unreadThreadChannelIds,
+  } = useAppShell();
+  const channelUnreadOverrideIds = locallyUnreadFeedItems.flatMap((item) =>
+    item.channelId === channel.id && feedItemState.unreadSet.has(item.id)
+      ? [item.id]
+      : [],
+  );
+  const hasProjectedUnread =
+    hasUnread ||
+    (channel.channelType !== "dm" &&
+      hasSidebarUnreadProjections &&
+      unreadThreadChannelIds.has(channel.id));
   const canLoadOwnerActions =
     channel.channelType !== "dm" && Boolean(onDeleteChannel);
   const membersQuery = useChannelMembersQuery(channel.id, canLoadOwnerActions);
@@ -204,7 +221,7 @@ export function ChannelContextMenuItems({
       canDeleteChannel,
   );
   const showStar = Boolean(onStarChannel && onUnstarChannel);
-  const showReadToggle = hasUnread
+  const showReadToggle = hasProjectedUnread
     ? Boolean(onMarkChannelRead)
     : Boolean(onMarkChannelUnread);
   const showMuteToggle = Boolean(onMuteChannel && onUnmuteChannel);
@@ -230,12 +247,15 @@ export function ChannelContextMenuItems({
         />
       ) : null}
       {showReadToggle ? <ContextMenuSeparator /> : null}
-      {hasUnread && onMarkChannelRead ? (
+      {hasProjectedUnread && onMarkChannelRead ? (
         <ContextMenuItem
           onSelect={() =>
-            deferMenuAction(() =>
-              onMarkChannelRead(channel.id, channel.lastMessageAt),
-            )
+            deferMenuAction(() => {
+              for (const itemId of channelUnreadOverrideIds) {
+                feedItemState.undoUnread(itemId);
+              }
+              onMarkChannelRead(channel.id, channel.lastMessageAt);
+            })
           }
         >
           <ContextMenuIconSlot>
@@ -243,7 +263,7 @@ export function ChannelContextMenuItems({
           </ContextMenuIconSlot>
           <span>Mark as read</span>
         </ContextMenuItem>
-      ) : !hasUnread && onMarkChannelUnread ? (
+      ) : !hasProjectedUnread && onMarkChannelUnread ? (
         <ContextMenuItem
           onSelect={() =>
             deferMenuAction(() => onMarkChannelUnread(channel.id))
diff --git a/desktop/src/features/sidebar/ui/CreateChannelFormFields.tsx b/desktop/src/features/sidebar/ui/CreateChannelFormFields.tsx
index 5fadf2a10a..01f5af478e 100644
--- a/desktop/src/features/sidebar/ui/CreateChannelFormFields.tsx
+++ b/desktop/src/features/sidebar/ui/CreateChannelFormFields.tsx
@@ -1,13 +1,16 @@
-import { ChevronDown } from "lucide-react";
+import { ChevronDown, Plus } from "lucide-react";
+import * as React from "react";
 
-import type { ChannelTemplate } from "@/shared/api/types";
+import { TemplateFormDialog } from "@/features/settings/ui/ChannelTemplatesSettingsCard";
 import { cn } from "@/shared/lib/cn";
 import { Button } from "@/shared/ui/button";
 import {
   DropdownMenu,
   DropdownMenuContent,
+  DropdownMenuItem,
   DropdownMenuRadioGroup,
   DropdownMenuRadioItem,
+  DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "@/shared/ui/dropdown-menu";
 import { Input } from "@/shared/ui/input";
@@ -39,9 +42,27 @@ export function CreateChannelFormFields({
   form: CreateChannelFormState;
 }) {
   const { channelKind, kindLabel, isCreating } = form;
+  const [isCreateTemplateOpen, setIsCreateTemplateOpen] = React.useState(false);
   const selectedTemplate = form.templates.find(
     (template) => template.id === form.selectedTemplateId,
   );
+  const selectedTemplatePersonaCount =
+    selectedTemplate?.agents.personas.length ?? 0;
+  const selectedTemplateTeamCount = selectedTemplate?.agents.teams.length ?? 0;
+  const selectedTemplateSummary = selectedTemplate
+    ? [
+        form.visibility === "private" ? "Private" : "Open",
+        selectedTemplate.canvasTemplate ? "Canvas included" : null,
+        selectedTemplatePersonaCount > 0
+          ? `${selectedTemplatePersonaCount} ${selectedTemplatePersonaCount === 1 ? "agent" : "agents"}`
+          : null,
+        selectedTemplateTeamCount > 0
+          ? `${selectedTemplateTeamCount} ${selectedTemplateTeamCount === 1 ? "team" : "teams"}`
+          : null,
+      ]
+        .filter(Boolean)
+        .join(" · ")
+    : null;
 
   return (
     <div className="space-y-5">
@@ -107,6 +128,7 @@ export function CreateChannelFormFields({
 
       <ChannelTypeSettings
         disabled={isCreating}
+        label="Type"
         onOpenChange={form.setTypePopoverOpen}
         onTemporaryChange={form.setEphemeral}
         onTtlSecondsChange={form.setTtlSeconds}
@@ -116,63 +138,6 @@ export function CreateChannelFormFields({
         ttlSeconds={form.ttlSeconds}
       />
 
-      {form.templates.length > 0 ? (
-        <div
-          className={cn(
-            "flex min-h-12 items-center justify-between gap-4 rounded-xl border border-input bg-background px-3 py-3",
-            isCreating && "opacity-50",
-          )}
-        >
-          <span className="text-sm font-medium text-foreground">
-            Template
-            <span className={CREATE_LABEL_OPTIONAL_CLASS}>Optional</span>
-          </span>
-          <DropdownMenu modal={false}>
-            <DropdownMenuTrigger asChild>
-              <Button
-                aria-label={`Template: ${selectedTemplate?.name ?? "No template"}`}
-                className="-mr-2.5 ml-auto h-9 min-w-0 max-w-[60%] justify-end px-2.5 text-right text-sm font-medium text-foreground hover:bg-muted/50"
-                data-testid="create-channel-template"
-                disabled={isCreating}
-                id="create-channel-template"
-                type="button"
-                variant="ghost"
-              >
-                <span className="truncate text-right">
-                  {selectedTemplate?.name ?? "No template"}
-                </span>
-                <ChevronDown className="size-4 shrink-0 text-muted-foreground/70" />
-              </Button>
-            </DropdownMenuTrigger>
-            <DropdownMenuContent
-              align="end"
-              onCloseAutoFocus={(event) => event.preventDefault()}
-              style={{
-                minWidth: "var(--radix-dropdown-menu-trigger-width)",
-              }}
-            >
-              <DropdownMenuRadioGroup
-                onValueChange={(templateId) =>
-                  form.handleTemplateChange(
-                    templateId === NO_TEMPLATE_VALUE ? "" : templateId,
-                  )
-                }
-                value={form.selectedTemplateId ?? NO_TEMPLATE_VALUE}
-              >
-                <DropdownMenuRadioItem value={NO_TEMPLATE_VALUE}>
-                  No template
-                </DropdownMenuRadioItem>
-                {form.templates.map((template: ChannelTemplate) => (
-                  <DropdownMenuRadioItem key={template.id} value={template.id}>
-                    {template.name}
-                  </DropdownMenuRadioItem>
-                ))}
-              </DropdownMenuRadioGroup>
-            </DropdownMenuContent>
-          </DropdownMenu>
-        </div>
-      ) : null}
-
       <ChannelPermissionsSettings
         disabled={isCreating}
         onVisibilityChange={form.setVisibility}
@@ -180,6 +145,81 @@ export function CreateChannelFormFields({
         visibility={form.visibility}
       />
 
+      <div
+        className={cn(
+          "flex min-h-12 items-center justify-between gap-4 rounded-xl border border-input bg-background px-3 py-3",
+          isCreating && "opacity-50",
+        )}
+        data-testid="create-channel-template-container"
+      >
+        <span className="text-sm font-medium text-foreground">
+          Template
+          <span className={CREATE_LABEL_OPTIONAL_CLASS}>Optional</span>
+        </span>
+        <DropdownMenu modal={false}>
+          <DropdownMenuTrigger asChild>
+            <Button
+              aria-label={`Template: ${selectedTemplate?.name ?? "None"}`}
+              className="-mr-2.5 ml-auto h-9 min-w-0 max-w-[60%] justify-end px-2.5 text-right text-sm font-medium text-foreground hover:bg-muted/50"
+              data-testid="create-channel-template"
+              disabled={isCreating}
+              id="create-channel-template"
+              type="button"
+              variant="ghost"
+            >
+              <span className="truncate text-right">
+                {selectedTemplate?.name ?? "None"}
+              </span>
+              <ChevronDown className="size-4 shrink-0 text-muted-foreground/70" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent
+            align="end"
+            onCloseAutoFocus={(event) => event.preventDefault()}
+            style={{
+              minWidth: "var(--radix-dropdown-menu-trigger-width)",
+            }}
+          >
+            <DropdownMenuRadioGroup
+              onValueChange={(templateId) =>
+                form.handleTemplateChange(
+                  templateId === NO_TEMPLATE_VALUE ? "" : templateId,
+                )
+              }
+              value={form.selectedTemplateId ?? NO_TEMPLATE_VALUE}
+            >
+              <DropdownMenuRadioItem value={NO_TEMPLATE_VALUE}>
+                None
+              </DropdownMenuRadioItem>
+              {form.templates.map((template) => (
+                <DropdownMenuRadioItem key={template.id} value={template.id}>
+                  {template.name}
+                </DropdownMenuRadioItem>
+              ))}
+            </DropdownMenuRadioGroup>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem onSelect={() => setIsCreateTemplateOpen(true)}>
+              <Plus className="size-4" />
+              Create new channel template…
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+        <TemplateFormDialog
+          onCreated={form.handleTemplateCreated}
+          onOpenChange={setIsCreateTemplateOpen}
+          open={isCreateTemplateOpen}
+          template={null}
+        />
+      </div>
+      {selectedTemplateSummary ? (
+        <p
+          className="-mt-3 px-3 text-xs text-muted-foreground"
+          data-testid="create-channel-template-summary"
+        >
+          {selectedTemplateSummary}
+        </p>
+      ) : null}
+
       {form.errorMessage ? (
         <p className="text-sm text-destructive">{form.errorMessage}</p>
       ) : null}
diff --git a/desktop/src/features/sidebar/ui/SidebarSection.tsx b/desktop/src/features/sidebar/ui/SidebarSection.tsx
index 3e39c60a6d..797e907ba1 100644
--- a/desktop/src/features/sidebar/ui/SidebarSection.tsx
+++ b/desktop/src/features/sidebar/ui/SidebarSection.tsx
@@ -36,6 +36,8 @@ import {
   SidebarMenuButton,
   SidebarMenuItem,
 } from "@/shared/ui/sidebar";
+import { ChannelActivityPopover } from "@/features/sidebar/ui/ChannelActivityPopover";
+import { useAppShell } from "@/app/AppShellContext";
 
 const SECTION_LABEL_BUTTON_CLASS =
   "group/section-label flex w-fit max-w-[calc(100%-3rem)] cursor-pointer appearance-none items-center gap-1 text-left transition-colors hover:text-sidebar-foreground focus-visible:text-sidebar-foreground";
@@ -138,7 +140,8 @@ function ChannelWorkingBadge({
   return (
     <span
       className={cn(
-        "hidden max-w-32 shrink-0 truncate rounded-full px-1.5 py-0.5 text-2xs font-medium leading-none tabular-nums motion-safe:animate-pulse group-data-[collapsible=icon]:hidden sm:inline-flex",
+        "max-w-32 shrink-0 truncate rounded-full px-1.5 py-0.5 text-2xs font-medium leading-none tabular-nums motion-safe:animate-pulse group-data-[collapsible=icon]:hidden",
+        "hidden sm:inline-flex",
         isActive
           ? "bg-sidebar-active-foreground/20 text-sidebar-active-foreground"
           : "bg-primary/10 text-primary",
@@ -250,7 +253,6 @@ export function ChannelMenuButton({
   label,
   isActive,
   hasUnread,
-  unreadCount = 0,
   activeWorking,
   isMuted,
   dmParticipants,
@@ -270,17 +272,37 @@ export function ChannelMenuButton({
 }) {
   const resolvedLabel = label ?? channel.name;
   const ephemeralDisplay = getEphemeralChannelDisplay(channel);
+  const {
+    hasSidebarUnreadProjections,
+    topLevelUnreadChannelIds,
+    unreadThreadChannelIds,
+  } = useAppShell();
+  const hasTopLevelUnread =
+    channel.channelType === "dm"
+      ? hasUnread
+      : hasSidebarUnreadProjections
+        ? topLevelUnreadChannelIds.has(channel.id)
+        : hasUnread;
+  const hasThreadUnread =
+    channel.channelType !== "dm" &&
+    (hasSidebarUnreadProjections
+      ? unreadThreadChannelIds.has(channel.id)
+      : hasUnread);
 
-  return (
+  const button = (
     <SidebarMenuButton
       className={cn(
         isActive
           ? "group-hover/menu-item:bg-sidebar-active group-hover/menu-item:text-sidebar-active-foreground"
           : "group-hover/menu-item:bg-sidebar-accent group-hover/menu-item:text-sidebar-accent-foreground",
         !isActive &&
-          hasUnread &&
+          hasTopLevelUnread &&
           "font-semibold text-sidebar-foreground hover:text-sidebar-foreground",
-        !isActive && isMuted && !hasUnread && "opacity-50",
+        !isActive &&
+          isMuted &&
+          !hasTopLevelUnread &&
+          !hasThreadUnread &&
+          "opacity-50",
       )}
       data-channel-id={channel.id}
       data-testid={`channel-${channel.name}`}
@@ -321,19 +343,21 @@ export function ChannelMenuButton({
           )}
         />
       ) : null}
-      {hasUnread && !isActive && channel.channelType !== "dm" ? (
-        unreadCount > 0 ? (
-          <UnreadCountBadge
-            channelName={channel.name}
-            className="ml-auto"
-            count={unreadCount}
-          />
-        ) : (
-          <UnreadDotBadge channelName={channel.name} className="ml-auto" />
-        )
+      {hasThreadUnread ? (
+        <UnreadDotBadge channelName={channel.name} className="ml-auto" />
       ) : null}
     </SidebarMenuButton>
   );
+
+  if (!activeWorking && !hasThreadUnread) {
+    return button;
+  }
+
+  return (
+    <ChannelActivityPopover activeWorking={activeWorking} channel={channel}>
+      {button}
+    </ChannelActivityPopover>
+  );
 }
 
 export function SidebarSection({
diff --git a/desktop/src/shared/api/tauriPersonas.ts b/desktop/src/shared/api/tauriPersonas.ts
index 66e07f5e88..3cd9734ae2 100644
--- a/desktop/src/shared/api/tauriPersonas.ts
+++ b/desktop/src/shared/api/tauriPersonas.ts
@@ -240,6 +240,129 @@ export async function encodeAgentSnapshotForSend(
   });
 }
 
+// ── Agent trading cards ───────────────────────────────────────────────────────
+
+/** Result of `mint_agent_card`. */
+export type MintedAgentCard = {
+  /** Final `.agent.png` bytes (chunk-injected, verified), base64-encoded. */
+  cardPngBase64: string;
+  /** Suggested filename, e.g. `eva.agent.png`. */
+  fileName: string;
+  /** Designer commentary emitted alongside the image (may be empty). */
+  designerNotes: string;
+  /** True when the embedded manifest is encrypted to the (owner, agent) pair. */
+  locked: boolean;
+  /** How much memory is embedded in the card's snapshot. */
+  memoryLevel: SnapshotMemoryLevel;
+};
+
+/** Error prefix Rust returns when no OpenAI key is configured. */
+export const NO_OPENAI_KEY_PREFIX = "NO_OPENAI_KEY:";
+
+/**
+ * Which env layer resolves the OpenAI key for a card mint of this agent.
+ *
+ * - `"none"` — no key configured anywhere; show the first-time setup panel.
+ * - `"global"` — key comes from global Agent Defaults env; writable from the
+ *   dialog via `cardMintSaveOpenaiKey`.
+ * - `"persona"` — key is set on the linked persona; cannot be updated from
+ *   the mint dialog (would be shadowed by the higher-priority layer).
+ * - `"agent"` — key is set directly on the agent record; same restriction.
+ * - `"process"` — key comes from the process environment (dev fallback);
+ *   same restriction.
+ */
+export type CardMintKeyLayer =
+  | "none"
+  | "global"
+  | "persona"
+  | "agent"
+  | "process";
+
+/**
+ * Report which env layer resolves the OpenAI key for a card mint of this agent
+ * (same layering as the mint itself). Returns a layer discriminant — never the
+ * key value itself. Use to decide whether to show a writable key input (none /
+ * global) or a read-only redirect (persona / agent / process).
+ */
+export async function cardMintKeyStatus(id: string): Promise<CardMintKeyLayer> {
+  return invokeTauri<CardMintKeyLayer>("card_mint_key_status", { id });
+}
+
+/**
+ * Save an OPENAI_API_KEY into the global Agent Defaults env for card minting.
+ *
+ * Narrow seam: validated read-modify-write of the single key against the
+ * latest on-disk config. Unlike the general set_global_agent_config, this
+ * NEVER restarts running agents — the mint re-reads config per call, and a
+ * card setup must not disrupt unrelated agents.
+ */
+export async function cardMintSaveOpenaiKey(key: string): Promise<void> {
+  return invokeTauri<void>("card_mint_save_openai_key", { key });
+}
+
+/**
+ * Mint a trading card for an agent. One long API call (~2–3 minutes).
+ * Reroll = call again; the backend holds no session state.
+ *
+ * When `lock` is true, the embedded manifest is NIP-44-encrypted to the
+ * (owner, agent) pair: only those two keys can import the card. Requires a
+ * linked agent instance.
+ *
+ * `memoryLevel` (default `"none"`) embeds the owner's decrypted memory in
+ * the card's snapshot — same levels as snapshot export. Levels other than
+ * `"none"` require a linked agent instance; Rust derives the memory source
+ * from the resolved instance itself.
+ */
+export async function mintAgentCard(
+  id: string,
+  styleNotes?: string,
+  lock?: boolean,
+  memoryLevel?: SnapshotMemoryLevel,
+): Promise<MintedAgentCard> {
+  return invokeTauri<MintedAgentCard>("mint_agent_card", {
+    id,
+    styleNotes: styleNotes || null,
+    lock: lock ?? null,
+    memoryLevel: memoryLevel ?? null,
+  });
+}
+
+/** Save minted card bytes to disk via the OS save dialog. */
+export async function saveAgentCard(
+  cardPngBase64: string,
+  fileName: string,
+): Promise<boolean> {
+  return invokeTauri<boolean>("save_agent_card", { cardPngBase64, fileName });
+}
+
+/** One archived (previously minted) card, as listed by `list_agent_cards`. */
+export type ArchivedAgentCard = {
+  /** On-disk archive key — pass to `loadAgentCard`. */
+  storedFileName: string;
+  /** Suggested save-as name, e.g. `eva.agent.png`. */
+  fileName: string;
+  agentId: string;
+  agentName: string;
+  designerNotes: string;
+  locked: boolean;
+  /** Memory embedded in the card's snapshot ("none" for pre-field archives). */
+  memoryLevel: SnapshotMemoryLevel;
+  /** ISO-8601 mint timestamp. */
+  mintedAt: string;
+  /** Small JPEG grid preview, base64 (absent if the thumb write failed). */
+  thumbJpegBase64: string | null;
+};
+
+/** List all archived cards, newest first. */
+export async function listAgentCards(): Promise<ArchivedAgentCard[]> {
+  return invokeTauri<ArchivedAgentCard[]>("list_agent_cards");
+}
+
+/** Load one archived card's full PNG bytes (base64) by its archive key. */
+export async function loadAgentCard(storedFileName: string): Promise<string> {
+  return invokeTauri<string>("load_agent_card", { storedFileName });
+}
+
 // ── Snapshot import ───────────────────────────────────────────────────────────
 
 /** Preview returned by `preview_agent_snapshot_import` before any write. */
@@ -258,6 +381,16 @@ export type AgentSnapshotImportPreview = {
   /** True when the snapshot's respond_to_allowlist is non-empty. */
   hasSourceAllowlist: boolean;
   sourceAllowlistCount: number;
+  /** Full source pubkeys shown before import, not only their count. */
+  sourceAllowlist: string[];
+  /** Validated, pretty-printed manifest for full payload disclosure. */
+  manifestJson: string;
+  /**
+   * True when the snapshot came from a locked (encrypted) card this machine
+   * unlocked. Cards that cannot be unlocked fail with a refusal error and
+   * never reach a preview.
+   */
+  locked: boolean;
 };
 
 /** Confirmation sent to `confirm_agent_snapshot_import`. */
diff --git a/desktop/src/shared/api/types.ts b/desktop/src/shared/api/types.ts
index 3f07e9ad9a..d0e8ee0047 100644
--- a/desktop/src/shared/api/types.ts
+++ b/desktop/src/shared/api/types.ts
@@ -602,7 +602,6 @@ export type AgentModelInfo = {
 };
 
 // ── Config bridge types ──────────────────────────────────────────────────────
-
 export type ConfigOrigin =
   | "buzzExplicit"
   | "acpNativeRead"
@@ -612,7 +611,8 @@ export type ConfigOrigin =
   | "personaDefault"
   | "globalDefault"
   | "runtimeOverride"
-  | "harnessConstraint";
+  | "harnessConstraint"
+  | "harnessDefault";
 
 export type ConfigWriteMechanism =
   | { type: "respawnWithEnvVar"; envKey: string }
diff --git a/desktop/src/shared/styles/globals/scrollbars.css b/desktop/src/shared/styles/globals/scrollbars.css
index 4614967745..3d6fa15402 100644
--- a/desktop/src/shared/styles/globals/scrollbars.css
+++ b/desktop/src/shared/styles/globals/scrollbars.css
@@ -33,6 +33,27 @@
   );
 }
 
+/* Channel activity keeps its chrome outside the scrolling surface. The slim,
+ * low-contrast thumb belongs only to the activity list beneath the header. */
+.buzz-channel-activity-scrollbar {
+  scrollbar-gutter: stable;
+}
+
+.buzz-channel-activity-scrollbar::-webkit-scrollbar {
+  width: 8px;
+}
+
+.buzz-channel-activity-scrollbar::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.buzz-channel-activity-scrollbar::-webkit-scrollbar-thumb {
+  background-clip: content-box;
+  background-color: hsl(var(--foreground) / 0.15);
+  border: 2px solid transparent;
+  border-radius: 999px;
+}
+
 /*
  * Main-content scroll areas that have sticky blurred chrome inside them.
  * Native overlay scrollbars paint UNDER composited descendants
diff --git a/desktop/src/testing/e2eBridge.ts b/desktop/src/testing/e2eBridge.ts
index 818144415a..03d37ed72e 100644
--- a/desktop/src/testing/e2eBridge.ts
+++ b/desktop/src/testing/e2eBridge.ts
@@ -507,6 +507,11 @@ type E2eConfig = {
      * returning a catalog.
      */
     discoverAgentModelsError?: string;
+    // Backend provider mocks for the create-agent "Run on" section. See
+    // tests/helpers/bridge.ts:MockBridgeOptions for semantics.
+    backendProviders?: Array<{ id: string; binaryPath: string }>;
+    backendProviderProbeResult?: Record<string, unknown>;
+    backendProviderProbeDelayMs?: number;
   };
   relayHttpUrl?: string;
   relayWsUrl?: string;
@@ -11064,9 +11069,22 @@ export function maybeInstallE2eTauriMocks() {
           activeConfig,
         );
       case "discover_backend_providers":
-        return [];
-      case "probe_backend_provider":
-        return { ok: false, error: "mock: no providers available" };
+        return activeConfig?.mock?.backendProviders ?? [];
+      case "probe_backend_provider": {
+        const probeDelayMs =
+          activeConfig?.mock?.backendProviderProbeDelayMs ?? 0;
+        if (probeDelayMs > 0) {
+          await new Promise((resolve) =>
+            window.setTimeout(resolve, probeDelayMs),
+          );
+        }
+        return (
+          activeConfig?.mock?.backendProviderProbeResult ?? {
+            ok: false,
+            error: "mock: no providers available",
+          }
+        );
+      }
       case "discover_managed_agent_prereqs":
         return handleDiscoverManagedAgentPrereqs(
           payload as Parameters<typeof handleDiscoverManagedAgentPrereqs>[0],
@@ -11183,6 +11201,50 @@ export function maybeInstallE2eTauriMocks() {
           created_at: template.createdAt,
           updated_at: template.updatedAt,
         }));
+      case "create_channel_template": {
+        const { input } = payload as {
+          input: {
+            name: string;
+            description?: string;
+            channelType?: "stream" | "forum";
+            visibility?: "open" | "private";
+            canvasTemplate?: string;
+            agents?: ChannelTemplate["agents"];
+          };
+        };
+        const timestamp = new Date().toISOString();
+        const created: ChannelTemplate = {
+          id: `template-${Date.now()}`,
+          name: input.name,
+          description: input.description ?? null,
+          channelType: input.channelType ?? "stream",
+          visibility: input.visibility ?? "open",
+          canvasTemplate: input.canvasTemplate ?? null,
+          agents: input.agents ?? { personas: [], teams: [] },
+          isBuiltin: false,
+          createdAt: timestamp,
+          updatedAt: timestamp,
+        };
+        if (activeConfig) {
+          activeConfig.mock ??= {};
+          activeConfig.mock.channelTemplates = [
+            ...(activeConfig.mock.channelTemplates ?? []),
+            created,
+          ];
+        }
+        return {
+          id: created.id,
+          name: created.name,
+          description: created.description,
+          channel_type: created.channelType,
+          visibility: created.visibility,
+          canvas_template: created.canvasTemplate,
+          agents: created.agents,
+          is_builtin: created.isBuiltin,
+          created_at: created.createdAt,
+          updated_at: created.updatedAt,
+        };
+      }
       case "create_team":
         return handleCreateTeam(
           payload as Parameters<typeof handleCreateTeam>[0],
@@ -11282,6 +11344,9 @@ export function maybeInstallE2eTauriMocks() {
           memoryEntryCount: 0,
           hasSourceAllowlist: false,
           sourceAllowlistCount: 0,
+          sourceAllowlist: [],
+          manifestJson: "{}",
+          locked: false,
         };
       }
       case "confirm_agent_snapshot_import": {
@@ -11825,10 +11890,19 @@ export function maybeInstallE2eTauriMocks() {
       case "download_image":
       case "save_png_data_url":
       case "download_file":
+      case "save_agent_card":
         // The save dialog can't run headlessly; report a successful save so the
         // FileCard / image-menu click handlers resolve. Specs assert the
         // command was invoked via `__BUZZ_E2E_COMMANDS__`, not the dialog.
         return true;
+      case "card_mint_key_status":
+        // Cards: pretend a key is configured in global defaults so the mint
+        // form renders and the key-status row is shown.
+        return "global";
+      case "list_agent_cards":
+        // Cards archive starts empty in E2E; specs exercising the gallery
+        // can extend this with a seeded config knob when needed.
+        return [];
       case "copy_image_to_clipboard":
         return;
       case "copy_text_to_clipboard":
diff --git a/desktop/tests/e2e/badge.spec.ts b/desktop/tests/e2e/badge.spec.ts
index 0dfdfb549a..ae40eda61a 100644
--- a/desktop/tests/e2e/badge.spec.ts
+++ b/desktop/tests/e2e/badge.spec.ts
@@ -105,11 +105,11 @@ test("regular message bolds inactive channel without numeric badge", async ({
     "600",
   );
   await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
-  await expect(page.getByTestId("channel-unread-dot-random")).toBeVisible();
+  await expect(page.getByTestId("channel-unread-dot-random")).toHaveCount(0);
   await waitForBadgeState(page, withDotOnlyBadge(baselineBadge));
 });
 
-test("numeric badge increments for @mention in inactive channel", async ({
+test("top-level @mention bolds the channel without a row badge", async ({
   page,
 }) => {
   await page.goto("/");
@@ -134,7 +134,11 @@ test("numeric badge increments for @mention in inactive channel", async ({
     },
   );
 
-  await expect(page.getByTestId("channel-unread-random")).toBeVisible();
+  await expect(page.getByTestId("channel-random")).toHaveCSS(
+    "font-weight",
+    "600",
+  );
+  await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
   await expect(page.getByTestId("channel-unread-dot-random")).toHaveCount(0);
   await waitForBadgeState(page, withAdditionalBadgeCount(baselineBadge, 1));
 });
@@ -158,7 +162,7 @@ test("numeric badge increments for DM message", async ({ page }) => {
   await waitForBadgeState(page, withAdditionalBadgeCount(baselineBadge, 1));
 });
 
-test("numeric badge increments for interested thread reply in inactive channel", async ({
+test("interested thread reply shows the channel thread dot", async ({
   page,
 }) => {
   await page.goto("/");
@@ -190,11 +194,12 @@ test("numeric badge increments for interested thread reply in inactive channel",
     { parentEventId: rootEventId, pubkey: TEST_IDENTITIES.alice.pubkey },
   );
 
-  await expect(page.getByTestId("channel-unread-random")).toBeVisible();
+  await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
+  await expect(page.getByTestId("channel-unread-dot-random")).toBeVisible();
   await waitForBadgeState(page, withAdditionalBadgeCount(baselineBadge, 1));
 });
 
-test("numeric badge increments for broadcast reply in inactive channel", async ({
+test("broadcast reply bolds the channel without a thread dot", async ({
   page,
 }) => {
   await page.goto("/");
@@ -219,7 +224,12 @@ test("numeric badge increments for broadcast reply in inactive channel", async (
     { pubkey: TEST_IDENTITIES.alice.pubkey },
   );
 
-  await expect(page.getByTestId("channel-unread-random")).toBeVisible();
+  await expect(page.getByTestId("channel-random")).toHaveCSS(
+    "font-weight",
+    "600",
+  );
+  await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
+  await expect(page.getByTestId("channel-unread-dot-random")).toHaveCount(0);
   await waitForBadgeState(page, withAdditionalBadgeCount(baselineBadge, 1));
 });
 
@@ -265,9 +275,7 @@ test("mark-as-read via context menu clears channel unread indicator", async ({
   await waitForBadgeState(page, baselineBadge);
 });
 
-test("mark-as-unread via context menu increments numeric badge", async ({
-  page,
-}) => {
+test("mark-as-unread via context menu bolds the channel", async ({ page }) => {
   await page.goto("/");
   await page.getByTestId("channel-general").click();
   await expect(page.getByTestId("chat-title")).toHaveText("general");
@@ -278,10 +286,55 @@ test("mark-as-unread via context menu increments numeric badge", async ({
   await page.getByTestId("channel-random").click({ button: "right" });
   await page.getByText("Mark unread").click();
 
-  await expect(page.getByTestId("channel-unread-random")).toBeVisible();
+  await expect(page.getByTestId("channel-random")).toHaveCSS(
+    "font-weight",
+    "600",
+  );
+  await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
+  await expect(page.getByTestId("channel-unread-dot-random")).toHaveCount(0);
   await waitForBadgeState(page, withAdditionalBadgeCount(baselineBadge, 1));
 });
 
+test("marking a message unread bolds its channel after leaving", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page.getByTestId("channel-random").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("random");
+  await waitForMockLiveSubscription(page, "random");
+
+  const message = await page.evaluate(
+    ({ pubkey }) =>
+      window.__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+        channelName: "random",
+        content: "Keep this channel message unread",
+        kind: 40002,
+        pubkey,
+      }),
+    { pubkey: TEST_IDENTITIES.alice.pubkey },
+  );
+  if (!message) {
+    throw new Error("Mock message emitter is unavailable");
+  }
+
+  const messageRow = page
+    .getByTestId("message-row")
+    .filter({ hasText: "Keep this channel message unread" });
+  await expect(messageRow).toBeVisible();
+  await messageRow.hover();
+  await page.getByTestId(`more-actions-${message.id}`).click();
+  const toggle = page.getByTestId(`mark-read-toggle-${message.id}`);
+  await expect(toggle).toHaveText("Mark unread");
+  await toggle.click();
+
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("channel-random")).toHaveCSS(
+    "font-weight",
+    "600",
+  );
+  await expect(page.getByTestId("channel-unread-dot-random")).toHaveCount(0);
+});
+
 test("remote read-state rollback is ignored while local mark-unread still increments badge", async ({
   page,
 }) => {
@@ -379,11 +432,15 @@ test("remote read-state rollback is ignored while local mark-unread still increm
 
   await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
 
-  // Local mark-unread remains an in-session affordance and should still show
-  // the dot immediately without publishing a lower read timestamp.
+  // Local mark-unread remains an in-session affordance and should still bold
+  // the channel immediately without publishing a lower read timestamp.
   await page.getByTestId("channel-random").click({ button: "right" });
   await page.getByText("Mark unread").click();
-  await expect(page.getByTestId("channel-unread-random")).toBeVisible();
+  await expect(page.getByTestId("channel-random")).toHaveCSS(
+    "font-weight",
+    "600",
+  );
+  await expect(page.getByTestId("channel-unread-random")).toHaveCount(0);
   await waitForBadgeState(page, withAdditionalBadgeCount(baselineBadge, 1));
 
   // Step 3: remote advance clears the local forced-unread dot.
diff --git a/desktop/tests/e2e/channel-activity-popover.spec.ts b/desktop/tests/e2e/channel-activity-popover.spec.ts
new file mode 100644
index 0000000000..f91f1b41de
--- /dev/null
+++ b/desktop/tests/e2e/channel-activity-popover.spec.ts
@@ -0,0 +1,795 @@
+import { expect, test, type Page } from "@playwright/test";
+
+import { waitForAnimations } from "../helpers/animations";
+import { installMockBridge, TEST_IDENTITIES } from "../helpers/bridge";
+
+const SELF_PUBKEY = "deadbeef".repeat(8);
+const CHANNEL_GENERAL = "9a1657ac-f7aa-5db0-b632-d8bbeb6dfb50";
+const AGENT_PUBKEY = TEST_IDENTITIES.charlie.pubkey;
+
+type MockMessageEvent = {
+  id: string;
+  created_at: number;
+  pubkey: string;
+};
+
+type MockInboxFeedItem = {
+  content: string;
+  id: string;
+  tags: string[][];
+};
+
+async function waitForMockLiveSubscription(page: Page, channelName: string) {
+  await expect
+    .poll(() =>
+      page.evaluate(
+        (name) =>
+          (
+            window as Window & {
+              __BUZZ_E2E_HAS_MOCK_LIVE_SUBSCRIPTION__?: (input: {
+                channelName: string;
+              }) => boolean;
+            }
+          ).__BUZZ_E2E_HAS_MOCK_LIVE_SUBSCRIPTION__?.({
+            channelName: name,
+          }) ?? false,
+        channelName,
+      ),
+    )
+    .toBe(true);
+}
+
+async function emitMockMessage(
+  page: Page,
+  content: string,
+  options: {
+    parentEventId?: string;
+    pubkey: string;
+    createdAt: number;
+    mentionPubkeys?: string[];
+  },
+): Promise<MockMessageEvent> {
+  const event = await page.evaluate(
+    ({ body, parentEventId, pubkey, createdAt, mentionPubkeys }) =>
+      (
+        window as Window & {
+          __BUZZ_E2E_EMIT_MOCK_MESSAGE__?: (input: {
+            channelName: string;
+            content: string;
+            parentEventId?: string;
+            pubkey: string;
+            createdAt: number;
+            mentionPubkeys?: string[];
+          }) => MockMessageEvent;
+        }
+      ).__BUZZ_E2E_EMIT_MOCK_MESSAGE__?.({
+        channelName: "general",
+        content: body,
+        parentEventId,
+        pubkey,
+        createdAt,
+        mentionPubkeys,
+      }),
+    {
+      body: content,
+      parentEventId: options.parentEventId,
+      pubkey: options.pubkey,
+      createdAt: options.createdAt,
+      mentionPubkeys: options.mentionPubkeys,
+    },
+  );
+  if (!event) {
+    throw new Error("Mock message emitter is unavailable");
+  }
+  return event;
+}
+
+async function pushMockInboxFeedItems(page: Page, items: MockInboxFeedItem[]) {
+  await page.waitForFunction(
+    () =>
+      typeof (window as Window & { __BUZZ_E2E_PUSH_MOCK_FEED_ITEM__?: unknown })
+        .__BUZZ_E2E_PUSH_MOCK_FEED_ITEM__ === "function",
+  );
+  await page.evaluate(
+    ({ channelId, feedItems, senderPubkey }) => {
+      const pushFeedItem = (
+        window as Window & {
+          __BUZZ_E2E_PUSH_MOCK_FEED_ITEM__?: (item: {
+            category: "mention";
+            channel_id: string;
+            channel_name: string;
+            channel_type: "stream";
+            content: string;
+            created_at: number;
+            id: string;
+            kind: number;
+            pubkey: string;
+            tags: string[][];
+          }) => void;
+        }
+      ).__BUZZ_E2E_PUSH_MOCK_FEED_ITEM__;
+      if (!pushFeedItem) {
+        throw new Error("Mock feed injection helper is unavailable");
+      }
+      const createdAt = Math.floor(Date.now() / 1_000) - 300;
+      for (const item of feedItems) {
+        pushFeedItem({
+          category: "mention",
+          channel_id: channelId,
+          channel_name: "general",
+          channel_type: "stream",
+          content: item.content,
+          created_at: createdAt,
+          id: item.id,
+          kind: 9,
+          pubkey: senderPubkey,
+          tags: item.tags,
+        });
+      }
+    },
+    {
+      channelId: CHANNEL_GENERAL,
+      feedItems: items,
+      senderPubkey: TEST_IDENTITIES.alice.pubkey,
+    },
+  );
+}
+
+async function getForcedUnreadSources(page: Page): Promise<string[]> {
+  return page.evaluate(
+    ({ channelId, pubkey }) => {
+      const raw = window.localStorage.getItem(
+        `buzz-forced-unread.v1:${pubkey}`,
+      );
+      if (!raw) return [];
+      const entry = JSON.parse(raw)?.[channelId];
+      if (entry === undefined) return [];
+      return typeof entry === "object" && entry !== null
+        ? (entry.sources ?? [])
+        : ["manual"];
+    },
+    { channelId: CHANNEL_GENERAL, pubkey: SELF_PUBKEY },
+  );
+}
+
+async function seedChannelActivity(
+  page: Page,
+  {
+    extraThreadCount = 0,
+    includeAgent = true,
+  }: { extraThreadCount?: number; includeAgent?: boolean } = {},
+) {
+  await page.goto("/");
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+  await waitForMockLiveSubscription(page, "general");
+
+  const ownRoot = await emitMockMessage(
+    page,
+    "How should the handoff work for longer agent tasks?",
+    {
+      pubkey: SELF_PUBKEY,
+      createdAt: Math.floor(Date.now() / 1000) - 20,
+    },
+  );
+  const extraRoots = await Promise.all(
+    Array.from({ length: extraThreadCount }, (_, index) =>
+      emitMockMessage(page, `Overflow preview thread ${index + 1}`, {
+        pubkey: SELF_PUBKEY,
+        createdAt: Math.floor(Date.now() / 1000) - 19 + index,
+      }),
+    ),
+  );
+
+  await page.getByTestId("channel-random").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("random");
+
+  const unreadAt = Math.floor(Date.now() / 1000) + 60;
+  await emitMockMessage(
+    page,
+    "I tightened the empty state and added the direct thread link.",
+    {
+      parentEventId: "mock-general-welcome",
+      pubkey: TEST_IDENTITIES.alice.pubkey,
+      createdAt: unreadAt,
+      mentionPubkeys: [SELF_PUBKEY],
+    },
+  );
+  await emitMockMessage(
+    page,
+    "The updated interaction keeps context visible without opening the channel first.",
+    {
+      parentEventId: ownRoot.id,
+      pubkey: TEST_IDENTITIES.bob.pubkey,
+      createdAt: unreadAt + 1,
+    },
+  );
+  await Promise.all(
+    extraRoots.map((root, index) =>
+      emitMockMessage(
+        page,
+        `A new reply in overflow preview thread ${index + 1}`,
+        {
+          parentEventId: root.id,
+          pubkey: TEST_IDENTITIES.alice.pubkey,
+          createdAt: unreadAt + 2 + index,
+        },
+      ),
+    ),
+  );
+
+  if (includeAgent) {
+    await page.waitForFunction(
+      () =>
+        typeof (window as Window & { __BUZZ_E2E_SEED_ACTIVE_TURNS__?: unknown })
+          .__BUZZ_E2E_SEED_ACTIVE_TURNS__ === "function",
+    );
+    await page.evaluate(
+      ({ agentPubkey, channelId }) => {
+        (
+          window as Window & {
+            __BUZZ_E2E_SEED_ACTIVE_TURNS__?: (input: {
+              agentPubkey: string;
+              channelId: string;
+              turnId: string;
+            }) => void;
+          }
+        ).__BUZZ_E2E_SEED_ACTIVE_TURNS__?.({
+          agentPubkey,
+          channelId,
+          turnId: "channel-hover-preview",
+        });
+      },
+      { agentPubkey: AGENT_PUBKEY, channelId: CHANNEL_GENERAL },
+    );
+  }
+
+  await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
+  if (includeAgent) {
+    await expect(page.getByTestId("channel-working-general")).toBeVisible();
+  }
+}
+
+async function openActivityPopover(page: Page) {
+  await page.getByTestId("channel-general").hover();
+  const popover = page.getByTestId("channel-activity-popover-general");
+  await expect(popover).toBeVisible();
+  return popover;
+}
+
+test.describe("channel activity hover preview", () => {
+  test.beforeEach(async ({ page }) => {
+    await installMockBridge(page, {
+      managedAgents: [
+        {
+          pubkey: AGENT_PUBKEY,
+          name: "Charlie",
+          status: "running",
+          channelNames: ["general"],
+        },
+      ],
+    });
+  });
+
+  test("shows unread channel activity and working agents, then opens the selected thread", async ({
+    page,
+  }) => {
+    await seedChannelActivity(page, { extraThreadCount: 5 });
+    const popover = await openActivityPopover(page);
+
+    const heading = popover.getByRole("heading", {
+      name: "Channel activity",
+    });
+    await expect(heading).toBeVisible();
+    await expect(heading).toHaveCSS("backdrop-filter", /blur/);
+    const activityScroll = popover.getByTestId("channel-activity-scroll");
+    await expect(activityScroll).toHaveCSS("overflow-y", "auto");
+    await expect(activityScroll.getByRole("heading")).toHaveCount(0);
+    await expect
+      .poll(() =>
+        activityScroll.evaluate(
+          (element) => element.scrollHeight > element.clientHeight,
+        ),
+      )
+      .toBe(true);
+    await waitForAnimations(page);
+    const headingY = (await heading.boundingBox())?.y;
+    const scrollY = (await activityScroll.boundingBox())?.y;
+    const headingBottom = await heading.evaluate(
+      (element) => element.getBoundingClientRect().bottom,
+    );
+    expect(scrollY).toBeGreaterThanOrEqual(headingBottom - 1);
+    await activityScroll.evaluate((element) => {
+      element.scrollTop = element.scrollHeight;
+    });
+    await expect
+      .poll(() => activityScroll.evaluate((element) => element.scrollTop))
+      .toBeGreaterThan(0);
+    const scrolledHeadingY = (await heading.boundingBox())?.y;
+    expect(headingY).toBeDefined();
+    expect(scrolledHeadingY).toBeDefined();
+    expect(Math.abs((scrolledHeadingY ?? 0) - (headingY ?? 0))).toBeLessThan(
+      0.5,
+    );
+    await activityScroll.evaluate((element) => {
+      element.scrollTop = 0;
+    });
+    await expect
+      .poll(() =>
+        activityScroll.evaluate(
+          (element) =>
+            getComputedStyle(element, "::-webkit-scrollbar-thumb")
+              .backgroundColor,
+        ),
+      )
+      .toMatch(/0\.15\)/);
+    await expect(popover.getByTestId(/^channel-activity-item-/)).toHaveCount(7);
+    await expect(popover).toContainText(
+      "I tightened the empty state and added the direct thread link.",
+    );
+    await expect(popover.getByRole("heading")).toHaveCount(1);
+    await expect(
+      popover.getByTestId(`channel-activity-agent-${AGENT_PUBKEY}`),
+    ).toContainText("Charlie");
+    await expect(
+      popover.getByTestId(`channel-activity-agent-${AGENT_PUBKEY}`),
+    ).toContainText("Working");
+    const orderedRows = popover.locator(
+      '[data-testid^="channel-activity-agent-"], [data-testid^="channel-activity-item-"]',
+    );
+    await expect(orderedRows.first()).toHaveAttribute(
+      "data-testid",
+      `channel-activity-agent-${AGENT_PUBKEY}`,
+    );
+
+    await waitForAnimations(page);
+    await page.screenshot({
+      clip: { x: 0, y: 80, width: 720, height: 640 },
+      path: "test-results/channel-activity-hover/channel-activity-popover.png",
+    });
+
+    const targetRow = popover
+      .getByTestId(/^channel-activity-item-/)
+      .filter({ hasText: "direct thread link" });
+    await targetRow.getByRole("button", { name: /Open thread/ }).click();
+
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    const threadPanel = page.getByTestId("message-thread-panel");
+    await expect(threadPanel).toBeVisible();
+    await expect(threadPanel).toContainText("direct thread link");
+  });
+
+  test("removes the dot and preview after the final activity is read", async ({
+    page,
+  }) => {
+    await seedChannelActivity(page, { includeAgent: false });
+    const popover = await openActivityPopover(page);
+    await expect(popover.getByTestId(/^channel-activity-item-/)).toHaveCount(2);
+
+    for (let remaining = 1; remaining >= 0; remaining -= 1) {
+      const row = popover.getByTestId(/^channel-activity-item-/).first();
+      await row.hover();
+      await row.getByRole("button", { name: "Mark as read" }).click();
+      await expect(popover.getByTestId(/^channel-activity-item-/)).toHaveCount(
+        remaining,
+      );
+    }
+
+    await expect(page.getByTestId("channel-unread-dot-general")).toHaveCount(0);
+    await expect(
+      page.getByTestId("channel-activity-popover-general"),
+    ).toHaveCount(0);
+  });
+
+  test("groups multiple unread replies against the previewed channel", async ({
+    page,
+  }) => {
+    await seedChannelActivity(page, { includeAgent: false });
+    await emitMockMessage(
+      page,
+      "A second unread reply should stay grouped with this thread.",
+      {
+        parentEventId: "mock-general-welcome",
+        pubkey: TEST_IDENTITIES.bob.pubkey,
+        createdAt: Math.floor(Date.now() / 1_000) + 120,
+        mentionPubkeys: [SELF_PUBKEY],
+      },
+    );
+
+    const popover = await openActivityPopover(page);
+    const groupedRow = popover
+      .getByTestId(/^channel-activity-item-/)
+      .filter({ hasText: "direct thread link" });
+    await expect(groupedRow).toContainText("2 unread");
+  });
+
+  test("marks projected thread activity read from the active channel menu", async ({
+    page,
+  }) => {
+    await seedChannelActivity(page, { includeAgent: false });
+    await page.getByTestId("channel-general").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
+
+    await page.getByTestId("channel-general").click({ button: "right" });
+    await expect(
+      page.getByRole("menuitem", { name: "Mark as read" }),
+    ).toBeVisible();
+    await expect(
+      page.getByRole("menuitem", { name: "Mark unread" }),
+    ).toHaveCount(0);
+    await page.getByRole("menuitem", { name: "Mark as read" }).click();
+
+    await expect(page.getByTestId("channel-unread-dot-general")).toHaveCount(0);
+  });
+
+  test("marks projected thread activity read in the active channel with Shift+Escape", async ({
+    page,
+  }) => {
+    await seedChannelActivity(page, { includeAgent: false });
+    await page.getByTestId("channel-general").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
+
+    const shortcutHandled = await page.evaluate(() => {
+      const event = new KeyboardEvent("keydown", {
+        bubbles: true,
+        cancelable: true,
+        key: "Escape",
+        shiftKey: true,
+      });
+      window.dispatchEvent(event);
+      return event.defaultPrevented;
+    });
+    expect(shortcutHandled).toBe(true);
+
+    await expect(page.getByTestId("channel-unread-dot-general")).toHaveCount(0);
+    await page.getByTestId("channel-general").hover();
+    await expect(
+      page.getByTestId("channel-activity-popover-general"),
+    ).toHaveCount(0);
+  });
+
+  test("supports row actions and opens an agent's scoped activity", async ({
+    page,
+  }) => {
+    await seedChannelActivity(page);
+    let popover = await openActivityPopover(page);
+    const initialRows = popover.getByTestId(/^channel-activity-item-/);
+    await expect(initialRows).toHaveCount(2);
+
+    const firstRow = initialRows.first();
+    await firstRow.hover();
+    await firstRow.getByRole("button", { name: "Mark as read" }).click();
+    await expect(popover.getByTestId(/^channel-activity-item-/)).toHaveCount(1);
+
+    const remainingRow = popover.getByTestId(/^channel-activity-item-/).first();
+    await remainingRow.hover();
+    await remainingRow.getByRole("button", { name: "Remind me later" }).click();
+    await expect(
+      page.getByRole("dialog").getByText("Remind me later"),
+    ).toBeVisible();
+    await page.getByRole("button", { name: "Cancel" }).click();
+
+    popover = await openActivityPopover(page);
+    await popover.getByTestId(`channel-activity-agent-${AGENT_PUBKEY}`).click();
+
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await expect(page.getByTestId("agent-session-agent-name")).toContainText(
+      "Charlie",
+    );
+    await expect(page.getByTestId("agent-session-scope-label")).toContainText(
+      "#general",
+    );
+  });
+
+  test("keeps multiple Inbox threads visible after opening their channel", async ({
+    page,
+  }) => {
+    const inboxItemIds = [
+      "older-inbox-thread-for-hover",
+      "second-inbox-thread-for-hover",
+    ];
+    await page.goto("/");
+    await page.getByTestId("channel-general").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await page.getByRole("button", { name: "Inbox", exact: true }).click();
+    await expect(page.getByTestId("home-inbox-list")).toBeVisible();
+    await pushMockInboxFeedItems(
+      page,
+      inboxItemIds.map((id, index) => ({
+        content:
+          index === 0
+            ? "Older Inbox thread reopened for hover testing."
+            : "A second Inbox thread reopened for hover testing.",
+        id,
+        tags: [
+          ["h", CHANNEL_GENERAL],
+          [
+            "e",
+            index === 0
+              ? "older-inbox-thread-root"
+              : "second-inbox-thread-root",
+            "",
+            "root",
+          ],
+          [
+            "e",
+            index === 0
+              ? "older-inbox-thread-parent"
+              : "second-inbox-thread-parent",
+            "",
+            "reply",
+          ],
+          ["p", TEST_IDENTITIES.tyler.pubkey],
+        ],
+      })),
+    );
+
+    for (const itemId of inboxItemIds) {
+      const inboxRow = page.getByTestId(`home-inbox-item-${itemId}`);
+      await expect(inboxRow).toBeVisible();
+      await inboxRow.hover();
+      await inboxRow.getByRole("button", { name: "Mark as read" }).click();
+      await inboxRow.hover();
+      await inboxRow.getByRole("button", { name: "Mark unread" }).click();
+    }
+
+    await expect(page.getByTestId("channel-general")).toHaveCSS(
+      "font-weight",
+      "600",
+    );
+    for (const [index, itemId] of inboxItemIds.entries()) {
+      const inboxRow = page.getByTestId(`home-inbox-item-${itemId}`);
+      await inboxRow.hover();
+      await inboxRow.getByRole("button", { name: "Mark as read" }).click();
+      if (index === 0) {
+        await expect(page.getByTestId("channel-general")).toHaveCSS(
+          "font-weight",
+          "600",
+        );
+      }
+    }
+    await expect(page.getByTestId("channel-general")).not.toHaveCSS(
+      "font-weight",
+      "600",
+    );
+    for (const itemId of inboxItemIds) {
+      const inboxRow = page.getByTestId(`home-inbox-item-${itemId}`);
+      await inboxRow.hover();
+      await inboxRow.getByRole("button", { name: "Mark unread" }).click();
+    }
+
+    await expect(page.getByTestId("channel-general")).toHaveCSS(
+      "font-weight",
+      "600",
+    );
+    await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
+    await page.getByTestId("channel-general").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
+    await page.mouse.move(900, 680);
+    let popover = await openActivityPopover(page);
+    await expect(popover.getByTestId(/^channel-activity-item-/)).toHaveCount(2);
+    await expect(popover).toContainText("Older Inbox thread reopened");
+    await expect(popover).toContainText("A second Inbox thread reopened");
+    await expect(popover.getByText("Thread", { exact: true })).toHaveCount(2);
+
+    await popover
+      .getByTestId(/^channel-activity-item-/)
+      .filter({ hasText: "Older Inbox thread reopened" })
+      .getByRole("button", { name: /Open thread/ })
+      .click();
+    await expect(popover).toBeHidden();
+    await page.mouse.move(900, 680);
+    popover = await openActivityPopover(page);
+    await expect(popover.getByTestId(/^channel-activity-item-/)).toHaveCount(1);
+    await expect(popover).not.toContainText("Older Inbox thread reopened");
+    await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
+    await expect(page.getByTestId("channel-general")).toHaveCSS(
+      "font-weight",
+      "600",
+    );
+
+    await page.mouse.move(900, 680);
+    await expect(popover).toBeHidden();
+    await page.getByRole("button", { name: "Inbox", exact: true }).click();
+    const topLevelItemId = "top-level-inbox-item-for-channel-read";
+    await pushMockInboxFeedItems(page, [
+      {
+        content: "Top-level Inbox item reopened for channel read testing.",
+        id: topLevelItemId,
+        tags: [
+          ["h", CHANNEL_GENERAL],
+          ["p", TEST_IDENTITIES.tyler.pubkey],
+        ],
+      },
+    ]);
+    const topLevelInboxRow = page.getByTestId(
+      `home-inbox-item-${topLevelItemId}`,
+    );
+    await expect(topLevelInboxRow).toBeVisible();
+    await topLevelInboxRow.hover();
+    await topLevelInboxRow.getByRole("button", { name: "Mark unread" }).click();
+    await page.getByTestId("channel-general").click({ button: "right" });
+    await page.getByRole("menuitem", { name: "Mark as read" }).click();
+    await topLevelInboxRow.hover();
+    await expect(
+      topLevelInboxRow.getByRole("button", { name: "Mark unread" }),
+    ).toBeVisible();
+    await expect(page.getByTestId("channel-unread-dot-general")).toHaveCount(0);
+    await page.getByTestId("channel-general").hover();
+    await expect(
+      page.getByTestId("channel-activity-popover-general"),
+    ).toHaveCount(0);
+    await page.getByTestId("channel-random").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("random");
+    await expect(page.getByTestId("channel-general")).not.toHaveCSS(
+      "font-weight",
+      "600",
+    );
+  });
+
+  test("reading a grouped Inbox thread preserves an unrelated manual unread", async ({
+    page,
+  }) => {
+    await page.goto("/");
+    await page.getByTestId("channel-general").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await waitForMockLiveSubscription(page, "general");
+
+    const manualUnreadMessage = await emitMockMessage(
+      page,
+      "Keep this separate timeline message unread.",
+      {
+        pubkey: TEST_IDENTITIES.bob.pubkey,
+        createdAt: Math.floor(Date.now() / 1_000),
+      },
+    );
+    const manualUnreadRow = page
+      .getByTestId("message-row")
+      .filter({ hasText: "Keep this separate timeline message unread." });
+    await manualUnreadRow.hover();
+    await page.getByTestId(`more-actions-${manualUnreadMessage.id}`).click();
+    await page
+      .getByTestId(`mark-read-toggle-${manualUnreadMessage.id}`)
+      .click();
+
+    await page.getByRole("button", { name: "Inbox", exact: true }).click();
+    const groupedRootId = "grouped-inbox-root-preserve-manual";
+    const groupedReplyId = "grouped-inbox-reply-preserve-manual";
+    await pushMockInboxFeedItems(page, [
+      {
+        content: "Grouped Inbox root for manual unread preservation.",
+        id: groupedRootId,
+        tags: [
+          ["h", CHANNEL_GENERAL],
+          ["p", TEST_IDENTITIES.tyler.pubkey],
+        ],
+      },
+      {
+        content: "Grouped Inbox reply marked read independently.",
+        id: groupedReplyId,
+        tags: [
+          ["h", CHANNEL_GENERAL],
+          ["e", groupedRootId, "", "root"],
+          ["e", groupedRootId, "", "reply"],
+          ["p", TEST_IDENTITIES.tyler.pubkey],
+        ],
+      },
+    ]);
+    const groupedInboxRow = page.getByTestId(
+      `home-inbox-item-${groupedReplyId}`,
+    );
+    await expect(groupedInboxRow).toBeVisible();
+    await groupedInboxRow.hover();
+    await groupedInboxRow.getByRole("button", { name: "Mark as read" }).click();
+
+    await page.getByTestId("channel-random").click();
+    await expect(page.getByTestId("channel-general")).toHaveCSS(
+      "font-weight",
+      "600",
+    );
+  });
+
+  test("preserves Inbox ownership while another top-level row remains unread", async ({
+    page,
+  }) => {
+    await page.goto("/");
+    await page.getByTestId("channel-general").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await page.getByRole("button", { name: "Inbox", exact: true }).click();
+    const topLevelItemIds = [
+      "first-top-level-inbox-owner",
+      "second-top-level-inbox-owner",
+    ];
+    await pushMockInboxFeedItems(
+      page,
+      topLevelItemIds.map((id, index) => ({
+        content: `Top-level Inbox owner ${index + 1}.`,
+        id,
+        tags: [
+          ["h", CHANNEL_GENERAL],
+          ["p", TEST_IDENTITIES.tyler.pubkey],
+        ],
+      })),
+    );
+    for (const itemId of topLevelItemIds) {
+      const inboxRow = page.getByTestId(`home-inbox-item-${itemId}`);
+      await expect(inboxRow).toBeVisible();
+      await inboxRow.hover();
+      await inboxRow.getByRole("button", { name: "Mark unread" }).click();
+    }
+    await expect(page.getByTestId("channel-general")).toHaveCSS(
+      "font-weight",
+      "600",
+    );
+    await expect.poll(() => getForcedUnreadSources(page)).toEqual(["inbox"]);
+
+    await page.getByRole("button", { name: "Inbox", exact: true }).click();
+    for (const [index, itemId] of topLevelItemIds.entries()) {
+      const inboxRow = page.getByTestId(`home-inbox-item-${itemId}`);
+      await inboxRow.hover();
+      await inboxRow.getByRole("button", { name: "Mark as read" }).click();
+      if (index === 0) {
+        await expect(page.getByTestId("channel-general")).toHaveCSS(
+          "font-weight",
+          "600",
+        );
+        await expect
+          .poll(() => getForcedUnreadSources(page))
+          .toEqual(["inbox"]);
+      }
+    }
+    await expect.poll(() => getForcedUnreadSources(page)).toEqual([]);
+  });
+
+  test("surfaces future replies after the user reacts to a thread root", async ({
+    page,
+  }) => {
+    await page.goto("/");
+    await page.getByTestId("channel-general").click();
+    await expect(page.getByTestId("chat-title")).toHaveText("general");
+    await waitForMockLiveSubscription(page, "general");
+
+    const root = await emitMockMessage(
+      page,
+      "Reacting here means I care about future replies.",
+      {
+        pubkey: TEST_IDENTITIES.alice.pubkey,
+        createdAt: Math.floor(Date.now() / 1_000) - 20,
+      },
+    );
+    const rootRow = page
+      .getByTestId("message-row")
+      .filter({ hasText: "Reacting here means I care" });
+    await expect(rootRow).toBeVisible();
+    await rootRow.hover();
+    const actionBar = page.getByTestId(`message-action-bar-${root.id}`);
+    await expect(actionBar).toBeVisible();
+    await actionBar
+      .getByRole("button", { name: /^React with / })
+      .first()
+      .click();
+    await expect(
+      rootRow.getByRole("button", { name: /^Toggle .* reaction$/ }),
+    ).toBeVisible();
+
+    await page.getByTestId("channel-random").click();
+    await emitMockMessage(
+      page,
+      "This follow-up appears because the root was reacted to.",
+      {
+        parentEventId: root.id,
+        pubkey: TEST_IDENTITIES.bob.pubkey,
+        createdAt: Math.floor(Date.now() / 1_000) + 60,
+      },
+    );
+
+    await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
+    const popover = await openActivityPopover(page);
+    await expect(popover).toContainText(
+      "This follow-up appears because the root was reacted to.",
+    );
+  });
+});
diff --git a/desktop/tests/e2e/channel-mute.spec.ts b/desktop/tests/e2e/channel-mute.spec.ts
index a710ca245f..23602f486a 100644
--- a/desktop/tests/e2e/channel-mute.spec.ts
+++ b/desktop/tests/e2e/channel-mute.spec.ts
@@ -85,7 +85,7 @@ test.describe("channel muting", () => {
     await expect(engRow.locator("svg.lucide-bell-off")).toHaveCount(1);
   });
 
-  test("03 — muted channel with @mention shows unread dot", async ({
+  test("03 — muted channel with a top-level @mention is emphasized", async ({
     page,
   }) => {
     await seedMuteState(page, ENGINEERING_CHANNEL_ID);
@@ -123,7 +123,13 @@ test.describe("channel muting", () => {
       },
     );
 
-    await expect(page.getByTestId("channel-unread-engineering")).toBeVisible();
+    await expect(page.getByTestId("channel-engineering")).toHaveCSS(
+      "font-weight",
+      "600",
+    );
+    await expect(
+      page.getByTestId("channel-unread-dot-engineering"),
+    ).toHaveCount(0);
   });
 
   test("04 — context menu shows Unmute channel when muted", async ({
diff --git a/desktop/tests/e2e/channels.spec.ts b/desktop/tests/e2e/channels.spec.ts
index 9da4022420..e9c5b42638 100644
--- a/desktop/tests/e2e/channels.spec.ts
+++ b/desktop/tests/e2e/channels.spec.ts
@@ -1336,8 +1336,26 @@ test("create channel template selector matches the lifecycle controls", async ({
         description: "Coordinate a new project from planning through launch.",
         channelType: "stream",
         visibility: "private",
-        canvasTemplate: null,
-        agents: { personas: [], teams: [] },
+        canvasTemplate: "# {channel.name}\n\nKickoff notes",
+        agents: {
+          personas: [
+            {
+              personaId: "planner",
+              runtime: null,
+              model: null,
+              role: null,
+              backend: null,
+            },
+          ],
+          teams: [
+            {
+              teamId: "research-team",
+              runtime: null,
+              model: null,
+              backend: null,
+            },
+          ],
+        },
         isBuiltin: false,
         createdAt: "2026-07-23T00:00:00Z",
         updatedAt: "2026-07-23T00:00:00Z",
@@ -1350,17 +1368,74 @@ test("create channel template selector matches the lifecycle controls", async ({
 
   const templateControl = page.getByTestId("create-channel-template");
   await expect(templateControl).toHaveRole("button");
-  await expect(templateControl).toHaveText("No template");
+  await expect(templateControl).toHaveText("None");
   await templateControl.click();
+  await expect(
+    page.getByRole("menuitem", { name: "Create new channel template…" }),
+  ).toBeVisible();
   await page.getByRole("menuitemradio", { name: "Project kickoff" }).click();
 
   await expect(templateControl).toHaveText("Project kickoff");
+  await expect(page.getByTestId("create-channel-template-summary")).toHaveText(
+    "Private · Canvas included · 1 agent · 1 team",
+  );
   await expect(page.getByTestId("create-channel-description")).toHaveValue(
     "Coordinate a new project from planning through launch.",
   );
   await expect(page.getByTestId("create-channel-permissions")).toContainText(
     "Private",
   );
+  await page.getByTestId("create-channel-permissions").click();
+  await page.getByTestId("create-channel-permissions-option-open").click();
+  await expect(page.getByTestId("create-channel-template-summary")).toHaveText(
+    "Open · Canvas included · 1 agent · 1 team",
+  );
+});
+
+test("create channel exposes templates when the library is empty", async ({
+  page,
+}) => {
+  await installMockBridge(page, { channelTemplates: [] });
+  await page.goto("/");
+  await openCreateChannelDialog(page);
+
+  const typeContainer = page.getByTestId(
+    "create-channel-channel-type-container",
+  );
+  const visibilityContainer = page.getByTestId(
+    "create-channel-permissions-container",
+  );
+  const templateContainer = page.getByTestId(
+    "create-channel-template-container",
+  );
+  await expect(templateContainer).toContainText("TemplateOptional");
+  const typeBox = await typeContainer.boundingBox();
+  const visibilityBox = await visibilityContainer.boundingBox();
+  const templateBox = await templateContainer.boundingBox();
+  expect(typeBox).not.toBeNull();
+  expect(visibilityBox).not.toBeNull();
+  expect(templateBox).not.toBeNull();
+  expect(typeBox?.y ?? 0).toBeLessThan(visibilityBox?.y ?? 0);
+  expect(visibilityBox?.y ?? 0).toBeLessThan(templateBox?.y ?? 0);
+
+  const templateControl = page.getByTestId("create-channel-template");
+  await expect(templateControl).toHaveText("None");
+  await templateControl.click();
+  await page
+    .getByRole("menuitem", { name: "Create new channel template…" })
+    .click();
+
+  await expect(
+    page.getByText("Create template", { exact: true }),
+  ).toBeVisible();
+  await page.locator("#template-name").fill("Weekly planning");
+  await page.locator("#template-description").fill("Plan the next week.");
+  await page.getByRole("button", { name: "Create", exact: true }).click();
+
+  await expect(templateControl).toHaveText("Weekly planning");
+  await expect(page.getByTestId("create-channel-description")).toHaveValue(
+    "Plan the next week.",
+  );
 });
 
 test("create ephemeral stream shows sidebar and header affordances", async ({
diff --git a/desktop/tests/e2e/edit-agent-run-on.spec.ts b/desktop/tests/e2e/edit-agent-run-on.spec.ts
new file mode 100644
index 0000000000..569c735eec
--- /dev/null
+++ b/desktop/tests/e2e/edit-agent-run-on.spec.ts
@@ -0,0 +1,212 @@
+import { expect, test } from "@playwright/test";
+
+import { waitForAnimations } from "../helpers/animations";
+import { installMockBridge, TEST_IDENTITIES } from "../helpers/bridge";
+
+const SHOTS = "test-results/edit-agent-run-on";
+
+/**
+ * The exact persisted shape of a real kubernetes agent created through the
+ * app ("Loni" in managed-agents.json, traced by Sami in review): eight keys,
+ * `inactivity_seconds` a JSON number, everything else strings, and the
+ * optional `service_account` ABSENT — no schema default means the create
+ * flow never seeds it, so honest fixtures omit it too.
+ */
+const KUBERNETES_CONFIG = {
+  context: "docker-desktop",
+  cpu_limit: "1",
+  cpu_request: "1",
+  image:
+    "ghcr.io/block/buzz-sprig:sha-6530b58@sha256:17facfc7608d8ddb33bc056c9aaba1098f4ef6abe5655702fbfd7584d1f74d76",
+  inactivity_seconds: 7200,
+  memory_limit: "1Gi",
+  memory_request: "1Gi",
+  namespace: "buzz-agents-gfq7aq",
+};
+
+async function openEditDialog(
+  page: import("@playwright/test").Page,
+  agentName: string,
+) {
+  await page.goto("/");
+  await page.getByTestId("open-agents-view").click();
+  await page
+    .getByRole("button", { name: `${agentName} agent profile` })
+    .click();
+  await page.getByTestId("user-profile-edit-agent").click();
+  await expect(page.getByTestId("edit-agent-dialog")).toBeVisible();
+}
+
+test("editing a kubernetes agent shows its saved run-on settings", async ({
+  page,
+}) => {
+  const agent = TEST_IDENTITIES.charlie;
+  await installMockBridge(page, {
+    managedAgents: [
+      {
+        pubkey: agent.pubkey,
+        name: "Remote Helper",
+        status: "running",
+        channelNames: ["general"],
+        respondTo: "owner-only",
+        backend: {
+          type: "provider",
+          id: "kubernetes",
+          config: KUBERNETES_CONFIG,
+        },
+      },
+    ],
+  });
+  await openEditDialog(page, "Remote Helper");
+
+  const runOn = page.getByTestId("edit-agent-run-on");
+  await expect(runOn).toBeVisible();
+  await expect(runOn.getByTestId("edit-agent-run-on-location")).toHaveText(
+    "kubernetes",
+  );
+
+  // Every saved field renders as a labeled row with its stored value.
+  await expect(runOn.getByTestId("edit-agent-run-on-namespace")).toContainText(
+    "buzz-agents-gfq7aq",
+  );
+  await expect(runOn.getByTestId("edit-agent-run-on-context")).toContainText(
+    "docker-desktop",
+  );
+  await expect(runOn.getByTestId("edit-agent-run-on-image")).toContainText(
+    "ghcr.io/block/buzz-sprig",
+  );
+  await expect(
+    runOn.getByTestId("edit-agent-run-on-cpu_request"),
+  ).toContainText("CPU request");
+  await expect(
+    runOn.getByTestId("edit-agent-run-on-inactivity_seconds"),
+  ).toContainText("7200");
+  // Real records omit the optional service_account (no schema default): the
+  // section must show only what was saved, never synthesize a row for it.
+  await expect(
+    runOn.getByTestId("edit-agent-run-on-service_account"),
+  ).toHaveCount(0);
+
+  // The section explains immutability instead of pretending to be a form.
+  await expect(runOn).toContainText("can't be changed afterwards");
+
+  await runOn.scrollIntoViewIfNeeded();
+  await waitForAnimations(page);
+  await page
+    .getByTestId("edit-agent-dialog")
+    .screenshot({ path: `${SHOTS}/kubernetes-run-on.png` });
+});
+
+test("editing a local agent names this computer, with no config rows", async ({
+  page,
+}) => {
+  const agent = TEST_IDENTITIES.tyler;
+  await installMockBridge(page, {
+    managedAgents: [
+      {
+        pubkey: agent.pubkey,
+        name: "Local Helper",
+        status: "stopped",
+        channelNames: ["general"],
+        respondTo: "owner-only",
+        backend: { type: "local" },
+      },
+    ],
+  });
+  await openEditDialog(page, "Local Helper");
+
+  const runOn = page.getByTestId("edit-agent-run-on");
+  await expect(runOn.getByTestId("edit-agent-run-on-location")).toHaveText(
+    "This computer",
+  );
+  await expect(runOn.getByTestId("edit-agent-run-on-namespace")).toHaveCount(0);
+
+  await runOn.scrollIntoViewIfNeeded();
+  await waitForAnimations(page);
+  await page
+    .getByTestId("edit-agent-dialog")
+    .screenshot({ path: `${SHOTS}/local-run-on.png` });
+});
+
+test("a blox agent's single saved field renders with a humanized label", async ({
+  page,
+}) => {
+  // The other real provider shape on developer machines: blox records
+  // persist exactly one key, exercising provider-generic humanization.
+  const agent = TEST_IDENTITIES.bob;
+  await installMockBridge(page, {
+    managedAgents: [
+      {
+        pubkey: agent.pubkey,
+        name: "Blox Helper",
+        status: "running",
+        channelNames: ["general"],
+        respondTo: "owner-only",
+        backend: {
+          type: "provider",
+          id: "blox",
+          config: { workstation_name: "tlongwell-sprout-home" },
+        },
+      },
+    ],
+  });
+  await openEditDialog(page, "Blox Helper");
+
+  const runOn = page.getByTestId("edit-agent-run-on");
+  await expect(runOn.getByTestId("edit-agent-run-on-location")).toHaveText(
+    "blox",
+  );
+  const row = runOn.getByTestId("edit-agent-run-on-workstation_name");
+  await expect(row).toContainText("Workstation name");
+  await expect(row).toContainText("tlongwell-sprout-home");
+
+  await runOn.scrollIntoViewIfNeeded();
+  await waitForAnimations(page);
+  await page
+    .getByTestId("edit-agent-dialog")
+    .screenshot({ path: `${SHOTS}/blox-run-on.png` });
+});
+
+test("secret-shaped keys from an untrusted provider render redacted", async ({
+  page,
+}) => {
+  const agent = TEST_IDENTITIES.charlie;
+  await installMockBridge(page, {
+    managedAgents: [
+      {
+        pubkey: agent.pubkey,
+        name: "Future Provider Agent",
+        status: "running",
+        channelNames: ["general"],
+        respondTo: "owner-only",
+        backend: {
+          type: "provider",
+          id: "some-future-provider",
+          config: {
+            endpoint: "https://provider.example",
+            api_token: "tok-do-not-show",
+          },
+        },
+      },
+    ],
+  });
+  await openEditDialog(page, "Future Provider Agent");
+
+  const runOn = page.getByTestId("edit-agent-run-on");
+  await expect(runOn.getByTestId("edit-agent-run-on-endpoint")).toContainText(
+    "https://provider.example",
+  );
+  const tokenRow = runOn.getByTestId("edit-agent-run-on-api_token");
+  await expect(tokenRow).toContainText("••••••••");
+  await expect(tokenRow).not.toContainText("tok-do-not-show");
+  // The raw secret must not appear anywhere in the dialog.
+  await expect(page.getByTestId("edit-agent-dialog")).not.toContainText(
+    "tok-do-not-show",
+  );
+
+  await runOn.scrollIntoViewIfNeeded();
+  await waitForAnimations(page);
+  await page
+    .getByTestId("edit-agent-dialog")
+    .screenshot({ path: `${SHOTS}/redacted-run-on.png` });
+});
diff --git a/desktop/tests/e2e/global-agent-config-screenshots.spec.ts b/desktop/tests/e2e/global-agent-config-screenshots.spec.ts
index 7ec1daa236..4c72b72f75 100644
--- a/desktop/tests/e2e/global-agent-config-screenshots.spec.ts
+++ b/desktop/tests/e2e/global-agent-config-screenshots.spec.ts
@@ -980,4 +980,44 @@ test.describe("global agent config screenshots", () => {
       path: `${SHOTS}/11-edit-runtime-less-provider-required-save-blocked.png`,
     });
   });
+
+  // Will's exact stuck path: databricks_v2 global provider + saved global
+  // OPENAI_API_KEY.  The cue must be visible without opening Advanced; once
+  // Advanced is opened the annotation must appear on the matching row.
+  test("card-mint-key-cue-visible-and-annotation-in-advanced", async ({
+    page,
+  }) => {
+    await installMockBridge(page, {
+      globalAgentConfig: {
+        provider: "databricks_v2",
+        model: null,
+        preferred_runtime: "buzz-agent",
+        env_vars: { OPENAI_API_KEY: "sk-placeholder" },
+      },
+    });
+
+    await openAiDefaultsSettings(page);
+
+    const card = page.getByTestId("settings-global-agent-config");
+
+    // The cue must be visible without the user opening Advanced.
+    await expect(card.getByTestId("card-mint-key-cue")).toBeVisible();
+    await expect(card.getByTestId("card-mint-key-cue")).toContainText(
+      "OPENAI_API_KEY",
+    );
+    await expect(card.getByTestId("card-mint-key-cue")).toContainText(
+      "Advanced → Environment variables",
+    );
+
+    // Advanced is collapsed at this point.
+    const advancedToggle = card.getByTestId("global-agent-advanced-toggle");
+    await expect(advancedToggle).toHaveAttribute("aria-expanded", "false");
+
+    // Open Advanced — the OPENAI_API_KEY row's annotation must be visible.
+    await advancedToggle.click();
+    await expect(advancedToggle).toHaveAttribute("aria-expanded", "true");
+    await expect(
+      card.getByText("Used for minting agent trading cards"),
+    ).toBeVisible();
+  });
 });
diff --git a/desktop/tests/e2e/navigation.spec.ts b/desktop/tests/e2e/navigation.spec.ts
index f7a96cd568..18db55a50a 100644
--- a/desktop/tests/e2e/navigation.spec.ts
+++ b/desktop/tests/e2e/navigation.spec.ts
@@ -48,6 +48,37 @@ test("global back and forward move across channel routes", async ({ page }) => {
   await expect(page.getByTestId("chat-title")).toHaveText("random");
 });
 
+test("back/forward keyboard chords work while the composer has focus", async ({
+  page,
+}) => {
+  const backChord = process.platform === "darwin" ? "Meta+[" : "Alt+ArrowLeft";
+  const forwardChord =
+    process.platform === "darwin" ? "Meta+]" : "Alt+ArrowRight";
+
+  await page.goto("/");
+
+  await page.getByTestId("channel-general").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  await page.getByTestId("channel-random").click();
+  await expect(page.getByTestId("chat-title")).toHaveText("random");
+
+  // The composer autofocuses on channel switch; make the regression
+  // condition explicit by clicking into it. The chords must still fire
+  // from inside the contenteditable (#3775).
+  await page.getByTestId("message-input").click();
+  await expect(page.getByTestId("message-input")).toBeFocused();
+
+  await page.keyboard.press(backChord);
+  await expect(page.getByTestId("chat-title")).toHaveText("general");
+
+  await page.keyboard.press(forwardChord);
+  await expect(page.getByTestId("chat-title")).toHaveText("random");
+
+  // preventDefault kept the chord out of the editor — no stray characters.
+  await expect(page.getByTestId("message-input")).toHaveText("");
+});
+
 // FIXME: the forum post "Back to posts" header renders under the fixed top
 // chrome drag region, which intercepts the click. Pre-existing breakage —
 // this spec file was never registered in playwright.config.ts until now.
diff --git a/desktop/tests/e2e/persona-env-vars.spec.ts b/desktop/tests/e2e/persona-env-vars.spec.ts
index 1e9b077a82..60a8e888b2 100644
--- a/desktop/tests/e2e/persona-env-vars.spec.ts
+++ b/desktop/tests/e2e/persona-env-vars.spec.ts
@@ -329,7 +329,7 @@ test("persona model options follow the selected LLM provider", async ({
 
   await selectDropdownOption(page, llmProvider, "OpenAI");
   const dialog = page.getByRole("dialog");
-  await expect(dialog.getByLabel("OpenAI API Key")).toBeVisible();
+  await expect(dialog.getByLabel("OpenAI Runtime API Key")).toBeVisible();
   await expect(
     dialog.getByRole("button", { name: "Advanced", exact: true }),
   ).toHaveAttribute("aria-expanded", "false");
@@ -343,7 +343,7 @@ test("persona model options follow the selected LLM provider", async ({
 
   await selectDropdownOption(page, llmProvider, "Anthropic");
   await expect(dialog.getByLabel("Anthropic API Key")).toBeVisible();
-  await expect(dialog.getByLabel("OpenAI API Key")).not.toBeVisible();
+  await expect(dialog.getByLabel("OpenAI Runtime API Key")).not.toBeVisible();
   await expect(model).toBeVisible();
 
   // Switch back to inherited defaults — per-agent provider, credential, and
diff --git a/desktop/tests/e2e/profile.spec.ts b/desktop/tests/e2e/profile.spec.ts
index 3b71ff9dd8..eefdef1fdd 100644
--- a/desktop/tests/e2e/profile.spec.ts
+++ b/desktop/tests/e2e/profile.spec.ts
@@ -1139,6 +1139,13 @@ test("renders settings in the app shell with a back button", async ({
   await expect(page.getByTestId("settings-back-to-app")).toBeVisible();
   await expect(page.getByPlaceholder("Search everything")).toHaveCount(0);
   await expect(page.getByText("Personal", { exact: true })).toBeVisible();
+  const personalGroup = page
+    .getByTestId("settings-nav-channel-templates")
+    .locator("xpath=ancestor::*[@data-sidebar='group']");
+  await expect(personalGroup).toContainText("Personal");
+  await expect(
+    page.getByTestId("settings-nav-channel-templates"),
+  ).toContainText("Channel templates");
   await expect(page.getByTestId("settings-nav-profile")).toHaveAttribute(
     "aria-pressed",
     "true",
diff --git a/desktop/tests/e2e/thread-unread.spec.ts b/desktop/tests/e2e/thread-unread.spec.ts
index 586ca3dd12..f4f45d3319 100644
--- a/desktop/tests/e2e/thread-unread.spec.ts
+++ b/desktop/tests/e2e/thread-unread.spec.ts
@@ -711,7 +711,7 @@ test.describe("thread unread indicator", () => {
     await expect(badge).toContainText("3");
   });
 
-  // Thread-only replies now also light the channel sidebar badge. Viewing the
+  // Thread-only replies now also light the channel sidebar dot. Viewing the
   // channel should leave unopened thread replies unread until the thread is read.
   test("11-thread-reply-lights-sidebar-badge-after-channel-view", async ({
     page,
@@ -748,15 +748,15 @@ test.describe("thread unread indicator", () => {
     await expect(page.getByTestId("chat-title")).toHaveText("general");
 
     // The crux: leave general. The unopened thread reply should still keep a
-    // numeric channel sidebar badge until the thread itself is read.
+    // channel sidebar dot until the thread itself is read.
     await page.getByTestId("channel-random").click();
     await expect(page.getByTestId("chat-title")).toHaveText("random");
-    await expect(page.getByTestId("channel-unread-general")).toBeVisible();
+    await expect(page.getByTestId("channel-unread-dot-general")).toBeVisible();
   });
 
   // Regression guard for the all-replies window: when the loaded window holds
   // ONLY thread replies (the top-level root has scrolled past the history
-  // limit), thread-only activity should still light the channel sidebar badge.
+  // limit), thread-only activity should still light the channel sidebar dot.
   //
   // The `all-replies` fixture carries a far-future `lastMessageAt` (standing in
   // for the backend's reply-inclusive MAX) with no top-level message in its
@@ -768,8 +768,7 @@ test.describe("thread unread indicator", () => {
     // Emit ONE reply whose parent root is NOT in the window (orphan parent id),
     // so the loaded window is all-replies: no top-level message exists for
     // `latestActiveMessage` to find. The reply mentions the current user so it
-    // clears the notify gate and creates Inbox activity without lighting the
-    // channel sidebar dot.
+    // clears the notify gate and creates Inbox thread activity.
     await page.getByTestId("channel-general").click();
     await expect(page.getByTestId("chat-title")).toHaveText("general");
     await waitForMockLiveSubscription(page, "all-replies");
@@ -779,17 +778,21 @@ test.describe("thread unread indicator", () => {
       mentionPubkeys: [SELF_PUBKEY],
       createdAt: unreadTimestamp(),
     });
-    await expect(page.getByTestId("channel-unread-all-replies")).toHaveCount(0);
+    await expect(
+      page.getByTestId("channel-unread-dot-all-replies"),
+    ).toBeVisible();
 
     // View all-replies while the reply is unread.
     await page.getByTestId("channel-all-replies").click();
     await expect(page.getByTestId("chat-title")).toHaveText("all-replies");
 
     // The crux: leave the channel. Its unopened thread reply should still keep
-    // a numeric channel sidebar badge until the thread itself is read.
+    // a channel sidebar dot until the thread itself is read.
     await page.getByTestId("channel-general").click();
     await expect(page.getByTestId("chat-title")).toHaveText("general");
-    await expect(page.getByTestId("channel-unread-all-replies")).toBeVisible();
+    await expect(
+      page.getByTestId("channel-unread-dot-all-replies"),
+    ).toBeVisible();
   });
 
   // Regression guard for BUG-2 (clear-on-read): opening an unread thread marks
diff --git a/desktop/tests/e2e/unread-pill.spec.ts b/desktop/tests/e2e/unread-pill.spec.ts
index 63f42d12ac..88169d9636 100644
--- a/desktop/tests/e2e/unread-pill.spec.ts
+++ b/desktop/tests/e2e/unread-pill.spec.ts
@@ -198,9 +198,12 @@ test.describe("unread pill & divider", () => {
     await page.getByTestId("channel-random").click();
     await expect(page.getByTestId("chat-title")).toHaveText("random");
 
-    // The unread indicator only renders on inactive channels, so it appears
-    // once general is no longer the active channel.
-    await expect(page.getByTestId("channel-unread-general")).toBeVisible();
+    // Forced channel unread uses channel-name emphasis, not the thread dot.
+    await expect(page.getByTestId("channel-general")).toHaveCSS(
+      "font-weight",
+      "600",
+    );
+    await expect(page.getByTestId("channel-unread-dot-general")).toHaveCount(0);
 
     await page.getByTestId("channel-general").click();
     await expect(page.getByTestId("chat-title")).toHaveText("general");
diff --git a/desktop/tests/e2e/where-to-run-config.spec.ts b/desktop/tests/e2e/where-to-run-config.spec.ts
new file mode 100644
index 0000000000..869e9b2138
--- /dev/null
+++ b/desktop/tests/e2e/where-to-run-config.spec.ts
@@ -0,0 +1,154 @@
+/**
+ * E2E spec for the create-agent "Run on" provider config fields.
+ *
+ * Pins the fix for the "Typewriter Eraser": WhereToRunSection's probe effect
+ * used to depend on the whole draft, so every keystroke re-probed the
+ * provider and every probe resolution reset providerConfig to schema
+ * defaults — typing into a defaultless field (the k8s "Kubeconfig context")
+ * looked completely dead, and the provider binary respawned in a loop.
+ *
+ * Covers:
+ *  - typing into a defaultless provider field sticks, and the provider is
+ *    probed exactly once for the selection (not once per keystroke)
+ *  - the config form is gated on probe resolution (no half-rendered form),
+ *    and defaults prefill exactly once when a slow probe lands
+ *  - switching provider → local → provider re-probes and resets cleanly
+ *
+ * The stale-closure merge on probe resolution (defaults beneath in-flight
+ * typing) is unreachable through this UI because the fields render only
+ * after the probe resolves; it is pinned at the unit level in
+ * whereToRunIntent.test.mjs (applyProbeResult).
+ */
+import { expect, test } from "@playwright/test";
+
+import { installMockBridge } from "../helpers/bridge";
+
+type Page = import("@playwright/test").Page;
+
+const PROVIDER = {
+  id: "kubernetes",
+  binaryPath: "/mock/buzz-backend-kubernetes",
+};
+
+const PROBE_RESULT = {
+  ok: true,
+  name: "kubernetes",
+  version: "0.0.0-mock",
+  config_schema: {
+    type: "object",
+    properties: {
+      context: {
+        type: "string",
+        title: "Kubeconfig context",
+        description: "Context from your kubeconfig.",
+      },
+      namespace: {
+        type: "string",
+        title: "Namespace",
+        default: "buzz-agents-mock01",
+      },
+    },
+    required: ["namespace"],
+  },
+};
+
+async function probeInvocations(page: Page): Promise<number> {
+  return page.evaluate(
+    () =>
+      (
+        window as Window & { __BUZZ_E2E_COMMANDS__?: string[] }
+      ).__BUZZ_E2E_COMMANDS__?.filter(
+        (command) => command === "probe_backend_provider",
+      ).length ?? 0,
+  );
+}
+
+/** Open the create-agent dialog and select the mocked provider in "Run on". */
+async function openCreateDialogOnProvider(page: Page) {
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("open-agents-view").click();
+  await page.getByTestId("new-agent-card").click();
+  await page.getByRole("menuitem", { name: "Create agent" }).click();
+  const dialog = page.getByTestId("persona-dialog");
+  await expect(dialog).toBeVisible({ timeout: 10_000 });
+  await dialog.locator("#agent-run-on").selectOption(PROVIDER.id);
+  return dialog;
+}
+
+test("typing into a defaultless provider field sticks and probes only once", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    backendProviders: [PROVIDER],
+    backendProviderProbeResult: PROBE_RESULT,
+  });
+  const dialog = await openCreateDialogOnProvider(page);
+
+  const contextField = dialog.locator("#provider-cfg-context");
+  await expect(contextField).toBeVisible({ timeout: 10_000 });
+  // Defaults prefilled from the schema; context has none.
+  await expect(dialog.locator("#provider-cfg-namespace")).toHaveValue(
+    "buzz-agents-mock01",
+  );
+  await expect(contextField).toHaveValue("");
+
+  await contextField.pressSequentially("prod-us-west", { delay: 20 });
+  await expect(contextField).toHaveValue("prod-us-west");
+
+  // One selection, one probe — keystrokes must not refire it.
+  expect(await probeInvocations(page)).toBe(1);
+});
+
+test("config fields render only after a slow probe resolves, with defaults", async ({
+  page,
+}) => {
+  // The fields are gated on the probe result (draft.probedProvider), which is
+  // what makes mid-flight typing unreachable through the UI — the stale-probe
+  // merge seam (applyProbeResult) is pinned at the unit level instead. This
+  // spec holds the gate: no half-rendered form before the probe lands, and
+  // defaults appear exactly once when it does.
+  await installMockBridge(page, {
+    backendProviders: [PROVIDER],
+    backendProviderProbeResult: PROBE_RESULT,
+    backendProviderProbeDelayMs: 1_000,
+  });
+  const dialog = await openCreateDialogOnProvider(page);
+
+  // Pre-resolution: the security warning is up, the form is not.
+  await expect(dialog.getByText("will receive your agent")).toBeVisible();
+  await expect(dialog.locator("#provider-cfg-context")).toHaveCount(0);
+
+  // Post-resolution: fields render with schema defaults prefilled.
+  await expect(dialog.locator("#provider-cfg-context")).toBeVisible({
+    timeout: 10_000,
+  });
+  await expect(dialog.locator("#provider-cfg-namespace")).toHaveValue(
+    "buzz-agents-mock01",
+  );
+  expect(await probeInvocations(page)).toBe(1);
+});
+
+test("provider → local → provider re-probes and resets the config", async ({
+  page,
+}) => {
+  await installMockBridge(page, {
+    backendProviders: [PROVIDER],
+    backendProviderProbeResult: PROBE_RESULT,
+  });
+  const dialog = await openCreateDialogOnProvider(page);
+
+  const contextField = dialog.locator("#provider-cfg-context");
+  await expect(contextField).toBeVisible({ timeout: 10_000 });
+  await contextField.fill("stale-value");
+
+  await dialog.locator("#agent-run-on").selectOption("local");
+  await expect(contextField).toHaveCount(0);
+
+  await dialog.locator("#agent-run-on").selectOption(PROVIDER.id);
+  await expect(dialog.locator("#provider-cfg-context")).toBeVisible({
+    timeout: 10_000,
+  });
+  // Fresh selection = fresh draft: the stale value must not leak back.
+  await expect(dialog.locator("#provider-cfg-context")).toHaveValue("");
+  expect(await probeInvocations(page)).toBe(2);
+});
diff --git a/desktop/tests/helpers/bridge.ts b/desktop/tests/helpers/bridge.ts
index 8a9ab2be11..345e1ee4d7 100644
--- a/desktop/tests/helpers/bridge.ts
+++ b/desktop/tests/helpers/bridge.ts
@@ -524,6 +524,25 @@ type MockBridgeOptions = {
    * returning a catalog. Exercises the discovery-failure UI path.
    */
   discoverAgentModelsError?: string;
+  /**
+   * Providers returned by `discover_backend_providers`. Defaults to `[]`
+   * (the "Run on" section stays hidden). Setting this renders the remote
+   * backend selector in the create-agent dialog.
+   */
+  backendProviders?: Array<{ id: string; binaryPath: string }>;
+  /**
+   * Result returned by `probe_backend_provider`. Defaults to
+   * `{ ok: false, error: "mock: no providers available" }`.
+   */
+  backendProviderProbeResult?: Record<string, unknown>;
+  /**
+   * Delay (ms) applied to `probe_backend_provider` so a spec can assert the
+   * pre-resolution state (config fields stay probe-gated until the result
+   * lands). Typing while a probe is in flight is unreachable through the UI
+   * for the same reason; that merge path is pinned at the unit level
+   * (`applyProbeResult` in whereToRunIntent.test.mjs).
+   */
+  backendProviderProbeDelayMs?: number;
 };
 
 type BridgeOptions = {
diff --git a/docs/remote-agents.md b/docs/remote-agents.md
new file mode 100644
index 0000000000..48ce85f5e5
--- /dev/null
+++ b/docs/remote-agents.md
@@ -0,0 +1,1770 @@
+# Remote Agents and Their Management: A Formal Specification
+
+`draft`
+
+## Abstract
+
+This document specifies the protocol by which Buzz Desktop delegates the
+execution of a managed agent to a **remote substrate** — any compute
+environment other than the local machine — through a **backend provider
+binary**, and specifies the lifecycle contract every provider and every
+remotely-run agent must satisfy. It covers three layers:
+
+1. **The provider protocol** — a zero-registration plugin contract between the
+   desktop and any executable named `buzz-backend-<id>`: discovery, the `info`
+   and `deploy` operations, payload schema, and the security obligations on
+   both sides of that boundary.
+2. **The remote lifecycle model** — how a remote agent is started, observed,
+   stopped, and reaped, given the deliberate design constraint that **the
+   desktop holds no management channel to the remote process**. Relay
+   presence is the sole status signal; shutdown is a relay message; liveness
+   bounds are enforced by the agent harness itself, not by the desktop.
+3. **The Kubernetes binding** — the first conforming provider,
+   `buzz-backend-kubernetes`, which realizes the contract as a bare Pod
+   running the `sprig` image.
+
+We state five invariants — **identity fail-closed**, **no secrets in
+configuration**, **presence-is-status**, **at-most-one-live-instance**, and
+**intentional-termination-is-final** — and argue each from the protocol
+rules.
+
+A scoping note that governs the whole document: the desktop is **one
+launcher among many**. What makes a process a live Buzz agent is a keypair,
+a NIP-OA auth tag, and a relay URL, handed as environment to the `buzz-acp`
+harness; anything that can set that environment and exec the harness — a
+bash script, a systemd unit, a CI job, or this document's provider protocol
+— is a conforming launcher. §Launchers states which obligations bind whom.
+
+As with the git
+specification (`git-on-object-storage.md`), naming the trust boundary is part
+of the claim: a provider binary is arbitrary code that is handed an agent's
+private key, and this document states exactly which properties hold *despite*
+that, which hold only if the provider is honest, and which are explicitly the
+user's acceptance.
+
+## Scope and Non-Goals
+
+This specification defines **management-plane behavior**: how agents get to a
+substrate, how their state is observed, and how their lifetime is bounded. It
+deliberately does **not** specify:
+
+- **Agent conversational behavior.** What the agent does with events is
+  governed by the ACP harness (`buzz-acp`) and the NIPs it implements
+  (NIP-OA, NIP-AE, NIP-AA, …), unchanged by where the harness runs.
+- **Malicious-provider containment.** A provider binary receives the agent's
+  `nsec` by design — that is its job. The protocol *bounds the desktop's
+  exposure* (discovery-only resolution, output caps, secret redaction,
+  anti-secret config validation, an explicit UI trust warning) but cannot make
+  a hostile provider safe. Choosing to run a provider is a trust decision the
+  UI surfaces to the user; this document does not claim otherwise.
+- **Substrate security.** Kubernetes RBAC, namespace isolation, and secret
+  encryption at rest are cluster-operator concerns. The Kubernetes binding
+  states its residual exposure (§K8s Secrets) rather than claiming isolation
+  it does not provide.
+- **Liveness of the substrate.** That a pod schedules, that an image pulls,
+  that a cluster is reachable — empirical, not formal. The protocol specifies
+  only how such failures are *reported* (structured error, redacted,
+  fail-closed).
+
+## System Model
+
+Five principals:
+
+- **Desktop** `D` — the Buzz Desktop app. Holds the agent's identity (nsec in
+  the OS keyring), its configuration record, and the only UI. Trusted.
+- **Provider** `P` — an executable `buzz-backend-<id>` on `D`'s machine.
+  Invoked one process per operation: JSON request on stdin, JSON response on
+  stdout, exit code carrying one bit (zero = output trustworthy, nonzero =
+  failure regardless of stdout — §Invocation). **Untrusted by `D`** for everything except
+  the job it is explicitly given (deploying the agent, which requires the
+  key). All of `P`'s output is treated as hostile (§Provider Output).
+- **Substrate** `S` — the remote compute environment `P` deploys into (a
+  Kubernetes cluster for the binding in this document). Opaque to `D`;
+  `D` never talks to `S`.
+- **Agent** `A` — a `buzz-acp` harness process (plus the ACP agent under it)
+  running on `S`, holding the nsec it was given, connected to the relay.
+- **Relay** `R` — the Buzz relay. The *only* channel that connects `D` to a
+  running `A`. Everything `D` knows about a live remote agent, it learns
+  from `R`.
+
+The defining constraint, stated as a design axiom:
+
+- **(M1) No management channel.** After a successful `deploy`, `D` holds no
+  **persistent management session** to `A` on `S`, and the desktop↔provider
+  protocol contains **no substrate API**: no status query, no exec, no log
+  fetch, no kill. All post-deploy observation and control flows through `R`:
+  status is relay presence (kind:20001), stop is a relay message
+  (`!shutdown`), and reconfiguration is a future re-deploy. The reduction M1
+  buys is **protocol surface, not credential absence**: ambient substrate
+  credentials may well exist on `D`'s machine (the Kubernetes binding uses
+  the user's kubeconfig by design), and `D` can always re-invoke `P`. What
+  M1 guarantees is that nothing in *this protocol* — its persisted records,
+  its wire operations, its stored `backend_agent_id` — constitutes or
+  requires a channel to the substrate. The price is the staleness bounds in
+  §Presence.
+
+An agent's identity is a Nostr keypair. The **agent record** on `D` carries:
+`name`, `relay_url`, the nsec (keyring-hydrated), the NIP-OA `auth` tag
+attesting owner authorization, `agent_command`/`agent_args` (the ACP agent the
+harness spawns — `goose`, `claude-agent-acp`, `codex-acp`, `buzz-agent`, or
+any user-supplied command: this is the **configurable harness** requirement),
+effective `system_prompt`/`model`/`provider`, timeout and parallelism knobs,
+the `respond_to` gate, merged `env_vars`, and a `backend` discriminator:
+`Local` or `Provider { id, config }`.
+
+### Launchers {#launchers}
+
+The five principals above describe the **provider-managed** launch path.
+That path is not the definition of a remote agent, and this section states
+the actual layering, because the obligations in this document do not all
+bind at the same layer. Three contracts, nested:
+
+1. **The agent/harness contract — binds every launcher.** A live Buzz agent
+   is a `buzz-acp` process holding a keypair, a NIP-OA auth tag (or resolved
+   owner pubkey), and a relay URL, delivered as environment. The relay
+   authenticates the keypair and the auth tag — never the launcher. At this
+   layer live: fail-closed identity (I1's property, enforced wherever the
+   env is assembled), presence publication (I3), owner-verified `!shutdown`,
+   and **intentional clean exit is terminal to automatic supervisor
+   restart** (I5). A bash script that exports `BUZZ_PRIVATE_KEY`,
+   `BUZZ_RELAY_URL`, `BUZZ_AUTH_TAG` and execs the harness is a conforming
+   launcher at this layer — today, with no code change.
+2. **The provider/deployer contract — binds provider-managed launches
+   only.** The two operations (`info`/`deploy`), the reconciliation loop,
+   and at-most-one-live-instance *per deploy scope* (I4). Hand-launched
+   agents sit outside it by construction: a launcher that bypasses the
+   provider protocol takes on the uniqueness discipline itself, exactly as
+   the cross-scope boundary in I4 already states. The protocol cannot and
+   does not promise a global singleton across unrelated launchers of the
+   same nsec.
+3. **The binding policy — per substrate.** Fingerprints, fenced deletes and
+   409 discrimination, restart-policy selection, the default idle bound,
+   and the grace budget are Kubernetes-binding policy (§The Kubernetes
+   Binding). A different substrate (the systemd/SSH deployer of PR #3449 is
+   the live example) conforms to layers 1–2 and writes its own layer 3; it
+   is not "non-conforming" for lacking pods.
+
+The desktop is therefore one launcher among many, and the provider protocol
+is the *desktop's* door to substrates, not the only door. §Conformance
+carries one checklist per layer.
+
+## Invariants
+
+The protocol maintains five invariants. Each is stated with the mechanism
+that enforces it and the boundary beyond which it does not hold.
+
+A design obligation governs the whole list: **the complexity budget is
+spent in this document, not in the code**. Every guarantee here was chosen
+because its enforcing mechanism is one small, boring thing — a refusal at
+payload construction (I1), a key-shape validator (I2), an ephemeral event
+the agent already publishes (I3), a deterministic name plus one annotation
+compare (I4), a timer that fires an existing shutdown channel (I5). The
+same rule holds below: the deploy state machine is one loop over seven
+ordered rows; the Secret scheme is "unique name, write first, reference
+exactly"; GC is one label-select with two filters (annotation, same-clock
+age). Where
+a richer property would have demanded machinery — Leases, controllers,
+ownerReferences, a management channel — the spec either found a
+name-and-timestamp argument that makes the machinery unnecessary or
+dropped the property and said so (§Non-Goals, M1). A conforming
+implementation that is not small is evidence of a spec bug; report it as
+one.
+
+- **(I1) Identity fail-closed.** No agent is ever launched with an empty or
+  missing private key: whatever assembles the harness environment — desktop,
+  provider, bash script — MUST refuse rather than launch identityless
+  (§Launchers, layer 1). In the provider path this is enforced at payload
+  construction: if keyring hydration left the nsec empty,
+  `build_deploy_payload` refuses (mirroring local spawn's
+  `spawn_key_refusal`), so no deploy request is ever emitted with an empty
+  key. Boundary: a provider that *discards* the key and launches an
+  identityless pod is a broken provider; the payload rule governs what `D`
+  sends, not what `P` does with it — which is why the property also binds
+  at `P`'s env assembly and at every non-provider launcher.
+
+- **(I2) No secrets in configuration.** `provider_config` — the persisted,
+  schema-rendered, UI-visible settings object — MUST NOT carry secrets.
+  Enforced by validation: flat object, scalar values only, ≤20 fields, ≤64KB,
+  and any key whose word-split contains `secret|password|token|key|credential`
+  is rejected. The match is against key *names*, so it is a lint with false
+  positives: a field like `ssh_key_path` holds a path, not a credential,
+  and is refused anyway — a provider author hitting this MUST rename the
+  field (e.g. `identity_file`), not weaken the validator; the rule's job is
+  making "put the secret in config" fail closed, and cheap false positives
+  are the accepted price. Secrets flow exclusively inside the `deploy` payload
+  (`private_key_nsec`, `auth_tag`, `env_vars`), which is never persisted by
+  `D` and never rendered. Corollary for providers: cluster credentials MUST
+  come from ambient substrate config (e.g. kubeconfig resolution), never from
+  `provider_config`.
+
+- **(I3) Presence is the status.** `D` derives a remote agent's live state
+  exclusively from relay presence events self-signed by the agent key:
+  `online`/`away`/`offline` (kind:20001, ephemeral, WS-published). The
+  deployment axis (`deployed`/`not_deployed`, from the stored
+  `backend_agent_id`) is bookkeeping, not liveness. Staleness bound: presence
+  can be wrong for the window between an abnormal agent death (SIGKILL, node
+  loss) and the relay's presence expiry — **180 seconds**
+  (`PRESENCE_TTL_SECS`, `buzz-pubsub/src/presence.rs:16`; the vision's
+  "a bounded wrong dot, never an indefinite one"), the accepted
+  cost of M1. The specific number is a relay-wide constant, not a
+  remote-agent choice: #3783 raised it from 90s to keep a three-heartbeat
+  expiry window after the desktop heartbeat moved to 60s. What I3 promises
+  is that the window is *bounded*, not its width.
+  The Kubernetes binding minimizes the *avoidable* part of that window by
+  sizing the termination grace period to the harness's full graceful-shutdown
+  path (§K8s Grace). Two consequences the bound imposes: (a) the harness's
+  presence-suppression knob, `BUZZ_ACP_NO_PRESENCE`, MUST join
+  `RESERVED_ENV_KEYS` — locally the knob is cosmetic (the process and UI
+  remain visible), but remotely M1 makes presence the *only* signal, so an
+  unreserved user env var would convert "wrong for ≤180s" into "wrong
+  indefinitely" and silently disarm the one bound in print; (b) presence is
+  scoped to a **community**: the relay derives community from its host, so
+  the deploy-time `relay_url` binds the body to one community for its whole
+  life, and a workspace observing through a different community sees the
+  agent offline while a deploy against it correctly no-ops — a known UX
+  boundary (the cross-scope boundary I4 admits, seen from the status side),
+  stated here so the two honest-but-conflicting readouts are diagnosable.
+
+- **(I4) At most one live instance per agent key per deployment scope.**
+  Within one provider's deployment scope (for Kubernetes: one namespace),
+  there is never more than one Running instance of a given agent pubkey.
+  Enforced by the deploy reconciliation loop (§Deploy State Machine):
+  deploy is keyed on the derived pubkey, a live instance maps to strict
+  no-op, and — because two deploys can race — create/delete conflicts MUST
+  converge (re-read and return the winner) rather than fail; deterministic
+  instance naming makes the substrate itself reject a second live instance.
+  Boundary: the protocol cannot prevent the same nsec being
+  deployed to two different scopes (two namespaces, two clusters, or remote
+  + local simultaneously) — the relay tolerates multiple connections per key,
+  and preventing this would require the global registry M1 forbids. Deploying
+  one key twice is user error with confusing-but-safe results (both instances
+  answer), not a safety violation.
+
+- **(I5) Intentional termination is final.** A remote agent **stops when
+  told, stays down when it stops, and is never silently resurrected**: an
+  instance whose harness is live terminates on owner `!shutdown` or when a
+  configured inactivity bound expires, and no supervisor restarts an
+  instance that exited *intentionally*. "Final" means **terminal to
+  automatic supervisor restart** — the owner may always issue a fresh
+  Start; that is resurrection working as designed, not a violation.
+
+  **Lifetime is owner policy, not law.** The inactivity bound is the
+  harness's opt-in self-stop (§Auto-Stop, default disabled). An owner may
+  always choose **no inactivity bound** — declaring an indefinitely-lived
+  agent. How that choice is expressed is per-binding: the Kubernetes
+  binding opts in with a 2h schema default because a pod is metered
+  compute with nobody watching it, and spells "no bound" as its
+  `inactivity_seconds: 0` field (§Pod shape); a hand launcher simply never
+  sets the reaper env. Either way it is
+  a legitimate, explicit choice, not a conformance failure: the invariant
+  was never "every instance terminates" (a continuously active agent is
+  intentionally unbounded — that is the product); it is "termination, once
+  intended, sticks".
+
+  **Restart policy follows lifetime policy.** The distinction that makes
+  indefinite agents safe is *intent vs accident*: dying on purpose
+  (`!shutdown`, inactivity reap) is final; dying by accident (node
+  eviction, OOM) may restart the body — same key, same agent, the
+  resurrection story working *for* the owner. Stated launcher-neutrally:
+  **if a supervisor exists, its restart policy MAY revive an abnormal
+  death and MUST NOT revive an intentional clean exit.** A launcher with
+  no supervisor at all — a hand-launched process on a VPS — satisfies
+  this vacuously: nothing restarts anything. How bounded vs indefinite
+  lifetime maps onto a concrete supervisor policy is binding policy
+  ([L3]), realized and documented by each binding — this binding's
+  mapping lives in §Pod shape; a systemd binding's in its unit
+  directives. Any revive-on-abnormal-death policy carries a universal
+  precondition: the supervisor can distinguish intent from accident only
+  if the harness formally promises *clean exit = exit code 0* on every
+  intentional path and nonzero otherwise, pinned by test. At `28ae6cd21`
+  that property is emergent, not defended (Known Defect 6);
+  restart-on-failure before the pinned contract is how a refactor
+  silently converts every clean stop into a restart loop with no failing
+  test. Ordering is normative: exit-code contract first,
+  restart-on-failure second — the identical seam in every supervisor that
+  offers the distinction. An always-restart policy remains non-conforming
+  at any layer: it resurrects after a *clean* exit, defeating
+  `!shutdown`.
+
+  Enforcement: the self-stop lives *inside the harness* (the only place
+  that can see activity, per M1) (§Auto-Stop), and each binding makes it
+  effective on its substrate by requiring that harness exit terminates
+  the substrate's unit of execution (this binding's realization — the
+  harness as the container's signal-receiving process — is §Pod shape,
+  [L3]) and that any supervisor's restart policy respects intent as
+  above.
+  Boundaries: (a) the guarantee is conditional on a live harness event
+  loop — a wedged process that cannot run its reaper timer cannot reap
+  itself, and M1 means nothing else will (the mitigation is the substrate
+  operator's, e.g. a namespace-level TTL policy, out of scope per
+  §Non-Goals); (b) restart policy prevents resurrection, it does not prove
+  process exit; (c) I5 bounds *agent* lifetime, not substrate residue —
+  residue (in this binding, a Completed pod object) persists for
+  forensics until the next deploy's GC (§K8s GC).
+
+## Provider Protocol
+
+### Discovery
+
+`D` scans, in order: the directory containing the desktop executable, every
+entry of `PATH`, and `~/.local/bin`, for executables named
+`buzz-backend-<id>`. The suffix after the prefix is the provider id and MUST
+match `[a-z0-9][a-z0-9_-]*`. On Windows, an `.exe`/`.bat`/`.cmd` extension
+MUST be stripped before the id is derived (see §Known Defects — as of
+`28ae6cd21` it is not, so Windows providers probe but cannot deploy). First
+hit per filename wins. Discovery executes nothing.
+
+**Shadowing and invalid candidates are diagnosable, not silent.** First-hit
+wins is the right selection rule (it is kubectl's), but kubectl also warns
+when a later-PATH plugin is shadowed, and Docker's CLI reports invalid
+plugin candidates with reasons. Discovery MUST retain, and the UI and
+deploy-time errors MUST be able to surface: the selected binary's full
+path, any shadowed candidates for the same id (later-PATH duplicates), and
+candidates rejected for malformed names. A deploy error that names which
+binary ran answers the first question a user with two copies of
+`buzz-backend-kubernetes` will ask. (At `28ae6cd21` discovery records only
+the winning path — a desktop change alongside Known Defect 3's.)
+
+**Resolution rule.** Every subsequent operation resolves the provider id
+against the *current* discovery set. A stored binary path on an agent record
+is a cache, revalidated against both the current candidates and the recorded
+id before every use. A record edit can therefore never redirect an operation
+to a binary discovery would not have found.
+
+**Pre-secret negotiation gate (normative).** Declaring `protocol_version`
+is worthless if nothing checks it before the nsec crosses the trust
+boundary — and at `28ae6cd21` nothing does: `provider_deploy` invokes
+`deploy` directly, so a stale UI-time probe (or a binary replaced on PATH
+since that probe) can receive `private_key_nsec` unchecked (Known Defect
+5). The deploy path MUST: resolve the provider id **once**; copy the
+resolved candidate into a desktop-owned, private, non-writable **staging
+file**, computing its digest during the copy; invoke `info` **on the
+staged artifact**; validate an explicit, supported `protocol_version`
+(§Info — absence is an error); invoke `deploy` on the **same staged
+artifact**; delete it afterward. Staged bytes are what "same executable
+identity" means here: the nsec goes to the exact bytes that answered
+`info`. Path-plus-metadata comparison (dev/inode, size, mtime) is NOT an
+acceptable substitute for this guarantee — unchanged metadata can miss an
+in-place content rewrite, and a pathname can be swapped between the check
+and the moment `Command` opens it, which is precisely the
+check-then-exec race the gate exists to close. A UI-time probe result
+MUST NOT satisfy this gate. If a platform makes staged execution
+impossible for some provider (e.g. an executable that only runs from its
+install location due to relative dependencies or signing constraints),
+the implementation MUST NOT silently fall back to metadata and still
+claim this gate: it degrades explicitly to *accidental-replacement
+detection* (path + file-identity compare), surfaces that weaker level in
+the deploy diagnostics, and the spec text for that platform carries the
+narrower claim. Remembered digest-based approval (Terraform-lock style)
+is a stronger follow-up, not a v1 requirement.
+
+### Invocation
+
+One process per operation. `D` spawns `P` with cwd = the agent workdir,
+writes exactly one JSON object to stdin, closes stdin. `P` writes exactly one
+JSON object to stdout and exits. Requirements on `D` (all implemented):
+
+- Bounded reads: stdout capped (1MB), stderr capped (64KB), no `read_to_end`
+  on pipes a daemonizing child could hold open; deadline polling with
+  `try_wait`.
+- **Non-zero exit is failure even if stdout parsed.** Partial output from a
+  crashed operation is never trusted.
+- `{"ok": false, "error": …}` is the in-band failure form.
+- **Environment**: `P` inherits `D`'s environment. On macOS a GUI launch
+  means launchd's minimal PATH; providers whose substrate credentials invoke
+  helper binaries (kubeconfig `exec` plugins) MUST self-augment their PATH
+  (§K8s Auth) rather than assume a login shell.
+
+### Provider Output Is Untrusted
+
+Everything `P` emits — stderr, error strings, the response object — is
+scrubbed before storage or display: every value from the request's
+`env_vars` (longest-first, length ≥4) and every `nsec1…`/`sprt_tok_…` token
+is redacted. Rationale: `P` legitimately holds secrets during deploy; `P`
+echoing them (in a stack trace, a kubectl error, a debug line) must not
+propagate them into `D`'s persisted `last_error` or logs.
+
+### `info`
+
+```
+request:  {"op": "info", "request_id": "<uuid>"}
+response: {"ok": true, "name": str, "version": str,
+           "protocol_version": int, "description": str,
+           "config_schema": <JSON Schema>}
+timeout:  10s
+```
+
+`version` is the provider's *software* version — useful in error reports,
+useless for compatibility. `protocol_version` (this document: `1`) is the
+wire-contract version, following the pattern Docker's CLI plugins
+(`SchemaVersion`) and HashiCorp go-plugin (negotiated protocol version) both
+converged on: the desktop rejects a provider whose `protocol_version` it
+does not speak, with an error naming both versions and the binary path,
+instead of failing later inside a half-understood `deploy`. A missing
+`protocol_version` is an **error, not a presumed `1`**: there is no
+deployed provider population to grandfather, and a gate that infers
+compatibility for exactly the class of binary that never declared any
+defeats its own pre-secret guarantee (§Discovery). Fail closed — it is
+also simpler: no migration clock, no "major cycle" to define.
+
+`config_schema` drives the UI form: `properties[*].default` prefill,
+string/number/boolean coercion, `required` gating. A provider MAY compute
+defaults freshly per call (the Kubernetes binding generates a random
+namespace default this way — §K8s Namespace). The schema's fields are
+subject to I2 validation when the user's values come back in `deploy`.
+
+### `deploy`
+
+```
+request:  {"op": "deploy", "request_id": "<uuid>",
+           "agent": <payload>, "provider_config": {…}}
+response: {"ok": true, "agent_id": str}
+timeout:  600s
+```
+
+The agent payload (field list per
+`commands/agents_deploy.rs: deploy_payload_json` at `28ae6cd21`; the
+`launch` block is a normative addition not yet emitted — Known Defect 3):
+
+| field | meaning |
+|---|---|
+| `name` | display name |
+| `relay_url` | concrete WS URL (workspace fallback materialized — the remote side has no workspace notion) |
+| `private_key_nsec` | **the identity** (I1: never empty) |
+| `auth_tag` | NIP-OA owner attestation |
+| `agent_command`, `agent_args` | the ACP agent under the harness (configurable-harness support). At `28ae6cd21` these are raw record bytes — see Known Defect 3: the normative source is the resolved descriptor in `launch` |
+| `system_prompt`, `model`, `provider` | effective values, live-persona-first resolution |
+| `turn_timeout_seconds`, `idle_timeout_seconds`, `max_turn_duration_seconds` | harness timeout knobs |
+| `parallelism` | concurrent-turn bound |
+| `respond_to`, `respond_to_allowlist` | inbound author gate |
+| `env_vars` | merged user env: global < persona < agent |
+| `launch` | **normative addition** (§Launch data): the desktop-resolved launch contract — `command` (name, not path), normalized `args`, layered `env`, overridable `policy_env`, and `owner_pubkey` |
+
+**Reserved-key rule (normative for providers).** `D` strips
+`BUZZ_PRIVATE_KEY`, `NOSTR_PRIVATE_KEY`, `BUZZ_AUTH_TAG`, `BUZZ_RELAY_URL`,
+and the other reserved keys from `env_vars` before merge. A provider MUST
+construct the agent environment's identity variables from the **top-level**
+payload fields (`private_key_nsec` → `BUZZ_PRIVATE_KEY`/`NOSTR_PRIVATE_KEY`,
+`auth_tag` → `BUZZ_AUTH_TAG`, `relay_url` → `BUZZ_RELAY_URL`); reading
+`env_vars` for them yields an identityless agent. A related hardening `D`
+performs is part of the contract's rationale: env keys are validated as
+POSIX-shaped names before merge, because a key like `BUZZ_AUTH_TAG=x`
+smuggled through `Command::env` would bypass the reserved-key strip
+entirely. A provider materializing `env_vars` into a substrate object
+(e.g. a Kubernetes Secret) MUST likewise never let a user-supplied key
+collide with or reconstruct a reserved key.
+
+`agent_id` is `P`'s stable handle for the deployment (the Kubernetes binding
+returns the pod name). `D` stores it as `backend_agent_id`; its presence is
+the `deployed` axis of I3.
+
+**There is no `undeploy` op in v1.** Deletion of a remote agent from `D`
+orphans the substrate objects; the UI therefore requires an explicit
+`force_remote_delete` confirmation, and the binding's GC + I5 bound the
+orphan's cost (the agent self-stops; the pod residue is reaped on the next
+deploy of the same key, or manually).
+
+### Launch data (`launch`) {#launch-data}
+
+Reproducing the local spawn's launch semantics requires state only the
+desktop can resolve: the runtime-metadata table (`model_env_var`,
+`provider_env_var`, `provider_locked`, `default_env` —
+`discovery.rs:75-207`), the six-layer env resolution, harness-definition
+command/args fallback, team instructions, session title, the respond-to
+gate's legacy owner fallback, and the mesh rewrite. A provider MUST NOT
+reimplement that derivation — it would be a second copy of desktop runtime
+discovery, drifting from the first. Instead the payload carries a typed
+`launch` block that `D` resolves with **the same code paths as local
+spawn**, and the provider applies it mechanically.
+
+```
+"launch": {
+  "command":      str,          // command NAME (e.g. "goose"), never a host path
+  "args":         [str],        // normalized args, definition fallback applied
+  "env":          {str: str},   // layered env: baked → runtime metadata →
+                                // definition → global → persona → agent
+                                // (resolve_effective_harness_descriptor)
+  "policy_env":   {str: str},   // overridable behavior defaults (tier 1, below):
+                                // runtime default_env (e.g. GOOSE_MODE=auto),
+                                // BUZZ_ACP_RELAY_OBSERVER, BUZZ_ACP_LAZY_POOL=true,
+                                // BUZZ_ACP_SESSION_TITLE (resolved),
+                                // BUZZ_ACP_TEAM_INSTRUCTIONS, BUZZ_ACP_MODEL,
+                                // MCP_HOOK_SERVERS=* (mcp_hooks runtimes only)
+  "owner_pubkey": str | null    // resolved workspace owner (hex) — legacy
+                                // BUZZ_ACP_AGENT_OWNER fallback, non-secret
+}
+```
+
+`launch.command`/`launch.args` come from
+`resolve_effective_harness_descriptor` (`readiness.rs:125`) — the same
+resolver local spawn uses — which fixes two silent divergences the raw
+record fields carry: a persona-derived `agent_command` is a blank record
+byte, and definition-provided `agent_args` are lost when the instance's own
+args are empty. `launch.env` is that descriptor's layered env, which is
+where per-runtime model/provider injection lives (`GOOSE_MODEL`/
+`GOOSE_PROVIDER` for goose; nothing for `provider_locked` runtimes like
+Claude; `BUZZ_AGENT_MODEL`/`BUZZ_AGENT_PROVIDER` for buzz-agent). A fixed
+`provider → BUZZ_AGENT_PROVIDER` mapping is wrong for three of the four
+built-in runtimes and is why this block exists.
+
+**What `policy_env` carries — and deliberately does not.** Its irreducible
+wire fields are exactly three scalars plus the metadata-derived defaults —
+plus the four record-derived behavior knobs that would otherwise be
+mis-tiered (below):
+
+- `BUZZ_ACP_TEAM_INSTRUCTIONS` — the only truly non-reconstructible policy
+  value: `effective_team_instructions` (`spawn_hash.rs:41-52`) needs the
+  desktop's `TeamRecord` store, which no pod can reach.
+- `BUZZ_ACP_SESSION_TITLE` — sent **resolved** (`resolve_session_title`,
+  `runtime/metadata.rs:45`), not as its `display_name`/`name` inputs. The
+  resolution strips control characters, and that property transfers: an
+  interior NUL fails a local spawn at the env boundary, and would make the
+  Kubernetes apiserver reject the whole pod spec — a rename must degrade,
+  not turn into a deploy failure.
+- `owner_pubkey` (block-level, not env) — the respond-to gate is otherwise
+  fully reconstructible from payload fields (`build_respond_to_env`,
+  `runtime.rs:380-421`); this is its one irreducible input.
+- Runtime `default_env` (e.g. `GOOSE_MODE=auto`) — computed **from the
+  runtime metadata table only, unconditionally**. The local spawn applies
+  each default only `if std::env::var(key).is_err()` (`runtime.rs:733-737`)
+  — a test of the *desktop's own* ambient environment. That makes "the
+  resolved local env" not a pure function of the record; serializing it
+  verbatim would bake a host accident into the pod. Launch data MUST be
+  computed from record + config alone.
+- `BUZZ_ACP_LAZY_POOL=true` — a **deliberate pick, not a transcription**:
+  the two local paths disagree (manual Start is eager, `runtime.rs:1001`;
+  launch restore is lazy, `restore.rs:333`, precisely to avoid "N idle
+  brains on every launch"). Remote pods take the lazy arm: an idle LLM pool
+  in a cluster is billable waste with no user watching it warm up.
+- `MCP_HOOK_SERVERS=*` when the resolved runtime has `mcp_hooks`
+  (`runtime.rs:594-598`; buzz-agent only at `28ae6cd21`) — gates the
+  `_Stop`/`_PostCompact` hook tools.
+- `BUZZ_ACP_SYSTEM_PROMPT`, `BUZZ_ACP_IDLE_TIMEOUT`,
+  `BUZZ_ACP_MAX_TURN_DURATION`, `BUZZ_ACP_AGENTS` — resolved by the desktop
+  from the record's `system_prompt` / `idle_timeout_seconds` /
+  `max_turn_duration_seconds` / `parallelism` (each omitted when null,
+  matching the local spawn's conditional emission). 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.
+
+**One create attempt per call (normative).** The replacement rows above —
+terminated, never-started provably broken, never-started divergent — exist
+to clear residue from a *previous* life. Once a deploy call has created its
+own pod, a classification that would replace that pod means the attempt this
+call just made has already failed: the harness started, rejected its
+configuration, and exited (the deterministic startup failure), or the pod
+was proven broken. Re-running the identical create against the same cluster
+inside the same call cannot produce a different outcome; what it produces is
+a hot delete/mint/create cycle every poll interval for the whole operation
+deadline, one immutable Secret per cycle (measured live: 107 Secrets in a
+single 600s call), every one younger than §K8s GC's orphan age gate — a
+bounded-call resource DoS and nsec-bearing-Secret amplifier. A binding MUST
+NOT delete-recreate a pod created by the same deploy call: it MUST return
+the in-band error carrying the latest condition (for a terminated container,
+the exit code and reason — never the terminated `message`, which is
+process-composed output under the same redaction rule as pull messages).
+The failed attempt's pod and Secret are deliberately left in place: the pod
+is terminated, so the *next* Start's preflight GC collects the pod and its
+referenced Secret together before that call's own single attempt — retry is
+thereby gated on fresh owner intent, and litter is bounded at one pod plus
+one Secret per press, not per poll. This bounds attempts, not observation:
+the recoverable rows still observe a slow startup for the full deadline, and
+residue from previous lives is still replaced exactly once on the way to
+this call's attempt.
+
+**Destructive decisions come from views you control — reads and writes
+both (normative).** This is one rule with three instances, stated once so
+nobody optimizes an instance away. §K8s GC's same-clock rule is the time
+instance. The other two live here:
+
+- *Reads*: every read whose result can authorize a deletion — the
+  Secret-absence confirmation above, and the candidate list the GC pass
+  filters — MUST use most-recent semantics (`resourceVersion` **unset**,
+  a quorum read). `resourceVersion: "0"` is served from the watch cache,
+  which the Kubernetes API contract explicitly allows to be much older
+  than anything the client has already observed; a stale
+  Secret-absence read would delete a pod whose Secret exists and whose
+  container was about to start — the GC race again, arriving through read
+  consistency instead of a clock.
+- *Writes*: a fresh read is necessary but not sufficient — the kubelet can
+  start the container between observation and delete. Every DELETE
+  authorized by a classification MUST carry `preconditions.uid` **and**
+  `preconditions.resourceVersion` from that exact observation
+  (`metav1.Preconditions` supports both), making the edge a
+  compare-and-delete. A failed precondition is neither an error nor
+  permission to retry the delete: re-enter from step 1 and classify the
+  object that exists now. The full-pubkey annotation check remains — the
+  precondition pins *when*, the annotation pins *whose*.
+
+**The 409 discriminator is `Status.reason`, never the status code
+(normative).** Two rules in this section require *opposite* actions on
+the same HTTP status: a failed delete precondition and a create-conflict
+are **both 409** (`NewConflict` and `NewAlreadyExists` each carry
+`Code: http.StatusConflict` — `apimachinery/pkg/api/errors/errors.go`).
+The discriminator is the Kubernetes API `Status.reason` field:
+`Conflict` → abandon the delete and re-enter from step 1;
+`AlreadyExists` on create → the convergence rule below (clean up only the
+losing attempt's Secret, re-read, adopt the winner). An implementation
+that branches on the code alone will eventually take the adoption path on
+a failed delete or vice versa. This does not contradict the
+reason-strings warning above: API `Status.reason` is a machine-readable
+contract token defined by `metav1.Status`; *container waiting* reasons
+are kubelet-produced strings with no such contract — the spec distrusts
+the latter, not the former.
+
+**Create-intent fingerprint (normative).** The divergence discriminator
+in the never-started rows is a recorded annotation,
+`buzz.block.xyz/create-intent`, written at pod create — the same shape as
+the image-reference and pubkey annotations the pod already carries. Its
+value is an **unkeyed SHA-256** over a canonical serialization of the
+provider's **non-secret create-intent template**, computed *before* the
+create call. The scope rule that makes a plain hash safe: the input
+covers exactly the provider-controlled fields that can affect scheduling
+or container creation — resolved image reference, resource
+requests/limits, service account, PodSpec command/args, volumes/mounts,
+security context, and the provider's other pod-shape knobs — and **never
+Secret data or attempt identity**. Secret *values* cannot cause the
+never-started wedge this discriminator exists to clear (scheduling reads
+pod fields, not Secret values; a bad launch value produces a started
+container that fails at the relay — a different row), so hashing them
+buys nothing and a plain hash over low-entropy secrets published in a
+world-readable annotation would be a dictionary oracle; excluding them
+removes the oracle and with it any need for an HMAC key or nsec-derived
+key material. Two normalization requirements, or every attempt diverges
+by construction: the per-attempt Secret *name* in `envFrom` MUST be
+replaced by a fixed placeholder (or the pre-binding template serialized
+instead of the concrete PodSpec), and API metadata / server- and
+admission-produced output (UID, `resourceVersion`, timestamps, defaulted
+fields, the fingerprint annotation itself) is excluded structurally —
+the serializer never sees it, an invariant checkable by inspection.
+Comparison is always recorded-annotation vs freshly-computed intent,
+**never** a diff against the live pod spec: admission defaulting and
+mutation would make every pod look divergent, which is why the
+fingerprint is computed pre-create. A missing referenced Secret stays
+handled by the most-recent absence check (the non-recoverable row), not
+by fingerprint divergence; and divergence authorizes deletion only
+through the never-started recoverable row — a started pod is strict
+no-op whatever its fingerprint says.
+
+**No-op means zero mutation.** The live-instance row MUST NOT replace or
+patch the Secret, patch metadata, or delete anything belonging to the
+observed live generation. Configuration and environment edits apply only to
+the *next* fresh generation (see the documented consequence below).
+
+**Conflicts converge, never fail.** Two provider processes can concurrently
+observe "no instance" or "terminated" — the deterministic instance name
+prevents two live instances, but one caller loses the race. The provider
+MUST treat create-conflict (already exists) by re-reading and, if the winner
+is an annotation-verified live instance, returning it as the no-op row
+would — cleaning up only its own losing attempt's residue, never the
+winner's (the Kubernetes binding makes this concrete via per-attempt Secret
+names, §K8s Secrets); it MUST treat delete-not-found as success; and it
+MUST loop until a
+stable outcome or the operation deadline (600s) expires. One deliberate
+asymmetry: the **create loser does not apply the fingerprint-divergence
+row to the pod that just beat it**, even when the winner's fingerprint
+differs from its own intent — it adopts or reconciles the elected winner.
+Two contenders with different payloads would otherwise ping-pong deletes
+through the conflict path. A *subsequent* deploy that walks in and
+observes that never-started divergent winner replaces it normally.
+Without this rule,
+"two deploys return an `agent_id`" (the idempotency claim below) is false
+under concurrency.
+
+**Documented consequence.** Because live → no-op, configuration edits to a
+running remote agent do not take effect until it next exits (unlike local
+agents, which re-resolve on every spawn). This is an accepted v1 tradeoff;
+a deliberate "recycle" affordance (stop-then-start) is the v2 path to
+immediate application. [DECISION E, ruled: per-binding policy — this
+binding keeps no-op; the universal property is that no sequence of Starts
+yields two live instances in one scope.] Note the asymmetry is deliberate and points the
+right way: an edit *cannot* reach a started pod until it exits, but it
+*can* reach a never-started one immediately (fingerprint divergence) —
+the never-started pod is the one the user is editing *because* it did not
+start.
+
+Idempotency in the protocol sense: any number of concurrent or sequential
+`deploy`s with the same payload converge to one live instance, and every
+non-erroring call returns an `agent_id` naming it; no sequence of `deploy`s
+can yield two live instances in one scope.
+
+### Stop and Delete
+
+- **Stop** is not a provider operation. `D` publishes `!shutdown` mentioning
+  the agent on `R`; the harness verifies the sender is the owner and exits
+  through its graceful path: agent-pool shutdown, drain of in-flight turns,
+  publish presence `offline`, close relay connection. **The spec does not
+  derive an upper bound for this path from its segment timeouts, because
+  review proved that arithmetic wrong twice**: the visible constants (30s
+  drain, 2s presence, 5s relay close) omit terms that are *variable*, not
+  constant — at `28ae6cd21` the post-drain reap segment
+  (late-arriving reap `lib.rs:2664`, idle-slot reap loop `:2670`, respawn
+  drain `:2684-2688`) runs *outside* the 30s drain timeout (opened at
+  `:2636`, closed at `:2657`) and serially awaits a 5s post-SIGKILL wait
+  per occupied pool slot (`acp.rs:436`). **That segment alone can reach
+  `30 + 5×parallelism + 7` — ~87s at the desktop's default parallelism
+  of 10** (`DEFAULT_AGENT_PARALLELISM`, `types.rs:814`; lowered from 24 by
+  #3038), ~197s at the harness cap of 32 (`config.rs:293`) — already
+  exceeding a 60s grace. And it is a *lower* bound on the tail, not the
+  worst case: the same path runs earlier segments before the prompt drain
+  even opens — a separate 30s wake-task drain (`:2612`) followed by
+  serial shutdown of any awakened pools (`:2620-2624`), whose per-slot
+  `acp.shutdown()` loop (`:3747-3751`) has no timeout of its own. The
+  total tail is not bounded by today's segment timeouts at all.
+  The requirement is therefore stated as a budget, not a sum (Known
+  Defect 7): **the harness MUST bound its total shutdown tail — every
+  post-signal segment, including per-slot reaping — under one shared
+  deadline no greater than the declared grace budget**, and the budget
+  MUST include a **reserved finalization slice** held back for presence
+  `offline` publish and relay close, **no smaller than those finalizers'
+  declared bounds — currently 2s + 5s = 7s** — which child cleanup may
+  never consume: child reaping degrades first (skip remaining per-slot
+  waits, force-kill), because a shared deadline without the reservation
+  can legally spend all 60s reaping children and hit SIGKILL before the
+  one action the grace period exists to protect. The binding declares the
+  budget (§K8s Grace: 60s); anyone re-deriving "~37s" from the segment
+  constants is reading numbers without their variables. The desktop's
+  local stop command rejects remote agents.
+- **Delete** with a live `backend_agent_id` requires `force_remote_delete:
+  true` from the UI's orphan-warning confirmation — a buggy IPC caller
+  cannot silently orphan substrate objects.
+
+### Auto-Stop (Inactivity Self-Termination)
+
+I5's enforcement point. A new harness knob:
+
+```
+--exit-after-inactivity <secs>   /   BUZZ_ACP_EXIT_AFTER_INACTIVITY
+```
+
+- **Default 0 = disabled.** The flag ships in the harness every *local*
+  agent also runs; a reaper bug must not be able to kill a laptop agent.
+  Remote providers opt in (the Kubernetes binding's `inactivity_seconds`
+  config field, schema default 7200 = 2h, feeds this env var directly).
+  **`inactivity_seconds: 0` is likewise a legal, blessed value meaning "no
+  inactivity bound"** — the explicit opt-in to an indefinitely-lived agent
+  (I5's lifetime-is-policy rule); it is not a misconfiguration and MUST NOT
+  be rejected by provider-side validation.
+- **"Inactivity" is defined as**: no events dispatched to the agent and no
+  turns in flight. Raw relay traffic does not count — an agent lurking in a
+  busy channel it never answers is exactly the waste this bounds.
+- **Mechanism**: on expiry of the bound, the harness fires the same shutdown
+  channel `!shutdown` uses — so inactivity exit gets in-flight drain,
+  presence→offline, and graceful relay close identically to an owner stop.
+  **The expiry check MUST NOT depend on pool readiness.** This is a design
+  constraint learned by inspection, not a transcription: the harness's
+  existing 30s maintenance tick is gated on `pool_ready` (`lib.rs:1743`),
+  which under `lazy_pool` starts false (`:1320`) and flips true only on a
+  wake (`:2570`) — and wakes require pending work (`pool_lifecycle.rs:42`).
+  A reaper riding that tick composes with the mandated
+  `BUZZ_ACP_LAZY_POOL=true` (§Launch data) into a deadlock in I5's single
+  most important case: a never-mentioned lazy pod never runs the tick, so
+  the idle agent the reaper exists to kill is exactly the one it can never
+  evaluate. The reaper therefore runs on its own timer, independent of pool
+  state (an idle-pool check needs no pool). Check granularity makes the
+  effective bound `t ∈ [T, T+interval)`, immaterial at T=7200.
+- **Reserved keys**: `BUZZ_ACP_EXIT_AFTER_INACTIVITY` MUST join
+  `RESERVED_ENV_KEYS` (`env_vars.rs`) when it lands — it is tier-3
+  authoritative (§Launch data), and without reservation a user env var
+  could disable the reaper and reopen unbounded lifetime through the front
+  door. `BUZZ_ACP_NO_PRESENCE` (`config.rs:378`) MUST join in the same
+  change, for the same shape of reason at I3 instead of I5: unreserved, it
+  lets user env silently defeat the 180s presence bound (I3). One knob
+  guards "knows when to leave", the other "you can see that it left";
+  both are promises users must not be able to un-make by typo.
+- Distinctness note: this is a **fourth** timeout concept, deliberately named
+  away from the existing three (`--idle-timeout` = per-turn ACP wire silence,
+  900s; `turn_timeout`; `max_turn_duration` = 7200s — numerically equal to
+  the default inactivity bound and semantically unrelated). Sharing a flag or
+  env name with any of them is how the bug ships.
+
+The harness exiting MUST terminate the substrate's unit of execution, and —
+equally load-bearing — the substrate's termination signal MUST reach the
+harness process itself; any wrapper MUST forward it. A wrapper that runs
+the harness as a child without forwarding signals silently voids both I5's
+substrate half *and* the graceful-shutdown budget: the termination signal
+lands on the wrapper, the harness never learns to shut down, and the
+force-kill leaves presence stale-online — exactly the staleness window the
+grace period exists to close. This binding's realization — the harness as
+the container's signal-receiving process (PID 1 or the signal target) — is
+§K8s Entrypoint's `exec` rule and §Pod shape ([L3], L1 item 3 for the
+universal form).
+With the supervisor policy that matches the lifetime policy (this
+binding's [L3] mapping — bounded → `Never`, indefinite → `OnFailure`
+after both prerequisites, §Pod shape; the universal rule is I5's),
+harness exit completes the pod on every intentional path — turning
+agent-level I5 into substrate-level I5.
+
+## The Kubernetes Binding (`buzz-backend-kubernetes`)
+
+The first conforming provider: a Rust crate in `block/buzz`, distributed as a
+standalone binary. Everything above is the contract; this section is its
+realization.
+
+### Cluster auth {#k8s-auth}
+
+Standard kubeconfig resolution (`$KUBECONFIG` → `~/.kube/config`) via
+`kube-rs`. `provider_config` carries **`context`** and **`namespace`** only
+(I2: credentials never transit config). Because kubeconfigs at Block
+near-universally use `exec` credential plugins (`aws eks get-token`,
+`gke-gcloud-auth-plugin`) that resolve via PATH, and the provider inherits a
+Finder-launched desktop's minimal PATH, the provider MUST prepend
+`/opt/homebrew/bin`, `/usr/local/bin`, and `~/.local/bin` to its own PATH
+before building the client, and on exec-plugin failure MUST name the missing
+plugin binary in the error rather than surfacing a kube-rs stack.
+
+### Namespace {#k8s-namespace}
+
+One stable namespace per user-visible choice; the provider emits a freshly
+generated `buzz-agents-<rand6>` as the `namespace` field's schema *default*
+on every `info` call, so the UI prefills a visible, editable random name with
+zero UI changes ("random default" satisfied at the schema layer). If the
+namespace does not exist the provider attempts to create it; on RBAC denial
+it MUST fail with the literal `kubectl create namespace <name>` command to
+run — it MUST NOT fall back to `default`.
+
+### Image
+
+`ghcr.io/block/buzz-sprig`: Alpine base + `bash` (required by the dev-MCP
+shell tool) + `git` + CA certificates + the static musl `sprig` multicall
+binary with its personality links (`buzz-acp`, `buzz-agent`, `buzz-dev-mcp`,
+`rg`, `tree`, `buzz`, `git-credential-nostr`, `git-sign-nostr`) + a baked
+system gitconfig wiring the nostr signing and credential helpers. The baked
+credential-helper config MUST be scoped to the relay's git URL — mirroring
+the local spawn's `credential.<relay-url>/git.helper` scoping — never a
+global `credential.helper`: a global nostr helper would answer for every
+remote, including github.com. ~15–25MB;
+not FROM-scratch (bash and git preclude it). Sprig-only: alternate-harness
+dependencies (node for Claude Code / Codex) come via the `image` override
+field, not a fatter default. Tagging follows the relay image's matrix —
+`sha-<short>` on main, semver on `sprig-v*` tags (the sprig tarball's
+`+git.<sha>` version string is not a legal Docker tag). **The default image
+reference MUST be pinned by digest, not tag**: the provider bakes, at
+compile time, the multi-arch manifest digest of the image built from its
+own commit and defaults `image` to
+`ghcr.io/block/buzz-sprig@sha256:<that-digest>` — a `sha-<git-sha>` *tag*
+is traceable but still movable (registry tags are mutable pointers;
+Kubernetes distinguishes movable tags from immutable digests for exactly
+this reason), and the object holding it runs with an nsec. The provider
+records the reference it used in a pod annotation, and rejects `:latest`.
+User `image` overrides accept tag, digest, or full custom registry
+reference — visibly the user's trust decision, with the resolved image ID
+recorded in the same annotation for post-hoc attribution.
+**An image override MUST contain the runtime ABI** — the `buzz-acp`
+entrypoint and everything §Entrypoint and launch ABI requires — not merely
+alternate-harness dependencies. A conforming custom image is "buzz-sprig
+plus your tools", never "your tools instead".
+
+### Entrypoint and launch ABI {#k8s-entrypoint}
+
+Two conforming implementations must produce interchangeable pods, so the
+launch contract is normative.
+
+**Entrypoint.** The container runs the harness as its signal-receiving
+process. Sprig is a multicall binary with no supervisor personality —
+nothing reaps children or forwards signals — so the entrypoint MUST end in
+`exec`:
+
+```bash
+#!/bin/bash
+set -e
+# nest scaffolding, if DECISION A lands, goes here
+exec buzz-acp   # exec, not a call — buzz-acp must be PID 1
+```
+
+`bash -c "setup && buzz-acp"` (no `exec`) is non-conforming: bash becomes
+PID 1, and a PID-1 bash with no trap never delivers SIGTERM to the harness
+(PID 1 receives kernel-level default-handler signal immunity), so the pod
+rides out the entire grace period and is SIGKILLed with presence still
+online — voiding I5's substrate half and the very staleness window
+`terminationGracePeriodSeconds: 60` was sized to close. The entrypoint
+shape and the grace period are one requirement, not two.
+
+**Payload → environment mapping.** The provider builds the pod environment
+(via the per-agent Secret, §K8s Secrets) by applying the §Launch data
+three-tier precedence — `launch.policy_env` (overridable defaults), then
+`launch.env` (user/layered), then the authoritative tier from top-level
+fields per the reserved-key rule. Only the
+non-`launch` scalars and the substrate-forced re-derivations are mapped
+individually:
+
+| source | env var |
+|---|---|
+| `relay_url` | `BUZZ_RELAY_URL` |
+| `private_key_nsec` | `BUZZ_PRIVATE_KEY` and `NOSTR_PRIVATE_KEY` (the git helpers read the latter) |
+| `auth_tag` | `BUZZ_AUTH_TAG` (omitted when null; then `launch.owner_pubkey` → `BUZZ_ACP_AGENT_OWNER` is REQUIRED — §Launch data owner rule) |
+| `launch.command` | `BUZZ_ACP_AGENT_COMMAND` — the *name*, resolved against the image's own PATH; never a forwarded host path |
+| `launch.args` | `BUZZ_ACP_AGENT_ARGS`, comma-joined |
+| `launch.env`, `launch.policy_env` | verbatim, at their precedence tiers |
+| generation token (§K8s Secrets) | `BUZZ_MANAGED_AGENT_START_NONCE` — the lifecycle-frame correlator and the Secret generation are one identity (§Launch data tier 3) |
+| `system_prompt`, `idle_timeout_seconds`, `max_turn_duration_seconds`, `parallelism` | **not mapped by the provider** — the desktop resolves these into `launch.policy_env` (`BUZZ_ACP_SYSTEM_PROMPT`, `BUZZ_ACP_IDLE_TIMEOUT`, `BUZZ_ACP_MAX_TURN_DURATION`, `BUZZ_ACP_AGENTS`), 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 `28ae6cd21`,
+  and earlier untimed segments precede it — the total is not bounded by
+  today's segment timeouts), so no fixed grace can be proven
+  sufficient by adding segment timeouts. The two halves of the requirement:
+  the binding *declares* the budget here, and the harness *enforces* it —
+  one shared deadline across the entire post-signal path, with a reserved
+  finalization slice (≥ the finalizers' declared bounds, currently 7s) for
+  presence `offline` and relay close, child cleanup
+  degrading first (§Stop, Known Defect 7). Until the harness enforcement
+  lands, 60s is an operational margin that the tail can exceed.
+- **Hardening defaults (normative).** The workload is a prompted coding
+  agent running repository and tool code while holding an nsec; the pod MUST
+  NOT hand it ambient cluster credentials or kernel privilege on top:
+  `automountServiceAccountToken: false` (Kubernetes mounts a ServiceAccount
+  token unless told otherwise — an API-stealable credential the agent never
+  needs), `runAsNonRoot: true` with a fixed nonzero UID/GID,
+  `allowPrivilegeEscalation: false`, capabilities drop-all,
+  `seccompProfile.type: RuntimeDefault`; never privileged, `hostPID`,
+  `hostNetwork`, or `hostPath`. `readOnlyRootFilesystem` is *not* required
+  in v1 — the sprig toolchain writes outside the workspace mount — but is a
+  named candidate once the image's write surface is mapped. The
+  `service_account` config field selects an identity for scheduling/RBAC
+  purposes only; it MUST NOT silently re-enable token mounting — API-token
+  access, if ever wanted, is a separate explicit opt-in, not a side effect
+  of naming an SA.
+- **Resources**: requests 1 cpu / 2Gi, limits 2 cpu / 4Gi, all four
+  configurable (`cargo build` in an agent workspace makes 500m/1Gi requests
+  unrealistic).
+- **Workspace**: `emptyDir`. Checkouts and scratch die with the pod; agent
+  memory is relay-persisted (NIP-AE) and unaffected. PVC support is a
+  deferred knob. [DECISION A — how remote pods get the nest workspace
+  (AGENTS.md etc.) that local agents get from the desktop's `ensure_nest`;
+  current recommendation is a desktop-stated protocol field, not
+  image-side scaffolding — §Open Decisions.]
+
+### Secrets {#k8s-secrets}
+
+Per-agent `Secret` containing the identity variables (built from top-level
+payload fields per the reserved-key rule) plus `env_vars`; consumed via
+`envFrom`.
+
+**Secret creation is per-attempt, immutable, and uniquely named**
+(`buzz-agent-<first-12-hex>-<gen>`, §Pod shape). The rationale is a
+concurrency race a deterministic shared Secret name cannot survive: two
+concurrent deploys carrying *different* payloads would both write the shared
+Secret, the loser's write could land last, and the winner's pod —
+deterministic name, winner's spec — would resolve the **loser's**
+identity/config through `envFrom`. The losing caller would have mutated the
+winning generation despite strict no-op. Unique names close this: each
+create attempt writes its own Secret first, then attempts the deterministic
+pod create with a spec referencing exactly that Secret. Pod creation elects
+the winner; payload and Secret are atomic at the pod-spec boundary, with no
+Lease or CAS machinery.
+
+Lifecycle rules that follow:
+
+- **Winner**: pod + its referenced Secret live together; GC deletes them
+  together.
+- **Losing contender** (create-conflict): annotation-verify the winning pod,
+  return its `agent_id` per the convergence rule, and delete **only its own
+  now-unreferenced Secret** — never the winner's, never any Secret
+  referenced by an *existing* pod. "Existing" deliberately includes
+  not-yet-started pods: an `envFrom` reference from a pod still pulling its
+  image is exactly as load-bearing as one from a running pod.
+- **Live no-op arm**: no Secret is written at all (zero mutation).
+- **GC**: also deletes annotation-verified **orphan Secrets** — those whose
+  generation token no existing pod references — covering contenders that
+  crashed between Secret create and their conflict cleanup. But only when
+  **age-eligible**: see the normative age gate in §K8s GC — "unreferenced"
+  is not "orphaned" while a concurrent attempt may still be between its
+  Secret create and its pod create.
+
+Fresh configuration therefore materializes exactly when a fresh generation
+does. Residual exposure, stated: any principal with
+pod-exec or secret-read in the namespace can read the nsec. This is the
+substrate-security boundary from §Non-Goals — the namespace is the isolation
+unit, and users deploying to shared namespaces accept its ambient RBAC. The
+in-pod narrowing that sprig's dev-MCP shim performs (strips the key from its
+own env, re-materializes as a 0600 keyfile for the git helpers) limits
+accidental leakage into subprocess environments, not hostile cluster access.
+
+### Garbage collection {#k8s-gc}
+
+A **generation** is one pod-create attempt and the uniquely-named Secret it
+references; the Secret's generation token is the generation's identity, and
+the *current* generation is the one referenced by the existing pod's
+`envFrom`.
+
+GC is a **preflight reconciliation pass**, not a post-deploy afterthought:
+on every deploy, after identity derivation and before the state transition,
+the provider deletes terminated pods (and their referenced Secrets) that
+match the pubkey label, **pass the full-pubkey annotation check, and carry
+the management marker** (§Pod shape; the auto-repair fence applies to GC
+identically), plus
+annotation-verified, marker-bearing orphan Secrets whose generation token
+no existing pod
+references (§K8s Secrets). It never touches the current generation.
+Mismatched annotations are never GC'd (§Deploy State Machine step 1), and
+an unmarked object is never GC'd regardless of its labels.
+
+**Orphan-Secret age gate (normative).** An unreferenced Secret is
+GC-eligible only when its server-assigned `creationTimestamp` is older than
+**twice the deploy operation deadline** (2 × 600s). Rationale — without the
+gate, GC composes with per-attempt Secrets into a legal interleaving that
+strands a deploy: attempt A creates Secret A; concurrent attempt B runs its
+preflight GC *before A creates its pod*, sees Secret A unreferenced, and
+deletes it as an "orphan"; A's pod is then accepted referencing a missing
+Secret and sits in `CreateContainerConfigError` until a later deploy
+repairs it by delete-recreate (§Deploy State Machine never-started rows) —
+a stranded deploy either way. Unique Secret
+names made payload↔Secret atomic *at the pod-spec boundary*, but
+Secret-create→pod-create is not atomic against an independent GC pass —
+the standard controller lesson that observations may be stale and
+reconciliation must tolerate in-flight peers. The age bound makes
+"unreferenced" mean "provably abandoned": any attempt that could still
+reference the Secret has exceeded its own deadline. A losing contender's
+immediate cleanup of **its own** Secret is exempt — ownership, not age, is
+its safety argument. (A Lease per agent identity would also close this
+race; the age gate achieves the same with no extra machinery.)
+
+**Same-clock rule (normative).** The age comparison has two operands and
+both MUST come from the apiserver's clock. `creationTimestamp` is
+server-assigned; the comparison instant MUST be derived from the HTTP
+`Date` response header on the very list/get call the GC pass performs
+(RFC 9110 §6.6.1 — origin-server message-origination time), never from the
+provider's local `now()`. The provider runs on a user's desktop, and a
+local clock fast by more than the margin doesn't *race* — it
+deterministically computes every in-flight Secret as expired and deletes
+them all, silently, on every pass, reopening exactly the interleaving the
+gate exists to close. With both operands from one clock, skew cancels.
+(`kube`'s `Client::send` returns the raw `http::Response` with headers, so
+this costs one header read, not a departure from the typed API.) If the
+`Date` header is absent or unparseable, the provider MUST **skip
+orphan-Secret GC for that pass** — never fall back to local time. A
+deferred cleanup is free; a wrong deletion is not.
+
+**Alternative considered — `ownerReferences`, omitted in v1.** Kubernetes'
+native GC (a Secret owned by its attempt's Pod is deleted when the owner is
+verified absent) cannot *replace* the age gate: an ownerReference needs the
+owner's UID, which exists only after pod create, so primary reliance on it
+would flip the ordering to Pod-first-then-Secret. The reason that flip
+loses is **diagnostics, not repairability**: a never-started winner is
+recoverable (the kubelet retries a config-failed container indefinitely,
+and the amended no-op rule lets a later deploy delete-and-recreate it with
+its own payload), but Pod-first routes *every healthy deploy* through
+`CreateContainerConfigError` — the exact condition the startup classifier
+treats as an actionable failure signal — so the classifier could no longer
+believe that reason without waiting out the deadline, on every deploy.
+That trades away normative diagnostics for a cleanup the age gate already
+provides. A *supplementary* post-create attachment (patch the Secret with
+the winning pod's UID; Secret metadata stays patchable when `immutable` and
+`data` are untouched) is sound but adds no required property: the pre-pod
+crash window still needs the age-gated sweep as backstop, so v1 omits it
+under the complexity budget. Any future implementation that adds it MUST
+set `blockOwnerDeletion: false` explicitly (true requires `update` on
+`pods/finalizers` — an RBAC verb nothing else here needs — and a Secret
+should never delay its pod's deletion), MUST keep owner and dependent in
+the same namespace (a cross-namespace owner is treated as *absent*, turning
+the safety net into an immediate-delete instruction), and MUST treat
+attachment failure as non-fatal cleanup, never a deploy error.
+
+Running GC first
+gives concurrency and Secret ownership one unambiguous order: reconcile
+always observes a world with at most one candidate generation *older than
+the gate*. Completed
+pods from the *current* generation are left in place — their logs are the
+only forensics M1 permits. That forensic window is deliberately fragile:
+next-deploy GC, node loss, or namespace deletion erases it, and M1 means
+there is no log operation to reach for. **Cluster-native log shipping is
+therefore a production prerequisite, not an optional nicety** — the
+ephemeral-runner lesson: disposable generations still need durable
+diagnostics, forwarded off the pod by the cluster operator's stack. The
+binding's contribution is correlation, not transport: the pod carries the
+full-pubkey annotation, the generation token (doubling as
+`BUZZ_MANAGED_AGENT_START_NONCE`, so lifecycle frames and pod logs share a
+correlator), the provider version, and the resolved image reference
+(§Image) — enough to attribute any shipped log line to an exact identity,
+generation, and binary, with no secret in any of it. GC on next-deploy
+also self-heals the missing
+`undeploy`: delete-then-recreate converges, and a deleted-forever agent's
+residue is one Completed pod that never restarts (I5) plus one Secret,
+removable with `kubectl delete`.
+
+### `provider_config` v1 fields
+
+`context`, `namespace`, `image`, `cpu_request`, `memory_request`,
+`cpu_limit`, `memory_limit`, `inactivity_seconds`, `service_account` —
+9 of the 20-field validation cap. Node selectors, tolerations, and PVCs are
+deliberately baked out of v1 to preserve budget.
+
+### Distribution
+
+Its own release workflow (macOS arm64/x64 + Linux musl; the sprig workflow's
+ubuntu × musl matrix cannot produce the laptop-side binary), artifacts
+attached to releases, installed to `~/.local/bin` (already on the discovery
+path). v1 ships no Windows binary [DECISION B]; desktop bundling into the
+.app (discovery already prepends the bundle dir) is deferred [DECISION D].
+
+## Conformance
+
+Obligations are split by layer per §Launchers: the **[L1] agent/harness
+contract** binds every launcher; the **[L2] provider/deployer contract**
+binds provider-managed launches; the **[L3] binding policy** here is the
+Kubernetes binding's own. A non-provider launcher (bash script, systemd
+unit) owes only the L1 items; a provider on a different substrate owes
+L1 + L2 and writes its own L3 realization of the generic L3 property.
+
+### [L1] Launcher conformance — every launcher
+
+A launcher — desktop, provider-deployed pod, systemd unit, bash script —
+is conforming iff:
+
+1. It launches the harness with a **valid, nonempty identity**: a
+   parseable private key, a relay URL, and an auth tag or resolved owner
+   pubkey — refusing to launch rather than launching identityless (I1's
+   property, enforced wherever the env is assembled).
+2. It does not suppress the harness's promises on a remote agent:
+   presence stays enabled (`BUZZ_ACP_NO_PRESENCE` never set — remotely,
+   presence is the only signal, I3), and the inactivity knob
+   (`BUZZ_ACP_EXIT_AFTER_INACTIVITY`) carries the owner's *deliberate*
+   lifetime policy, never an accidental passthrough of user env (I5; the
+   reserved-key rule is the provider path's realization of this).
+3. The substrate's **termination signal reaches the harness process**,
+   with enough grace for its full graceful shutdown before force-kill (I3
+   staleness minimization). "Allows" is not enough — a wrapper that
+   swallows the signal conforms to nothing.
+4. Intentional termination (owner `!shutdown`, inactivity reap) exits
+   through the harness's graceful path under the **pinned clean-exit
+   contract** (intentional exit ⇒ exit code 0 — Known Defect 6 until the
+   contract lands).
+5. Any supervisor the launcher configures **never restarts an intentional
+   clean exit** (I5). `Restart=always` and equivalents are non-conforming
+   at this layer no matter what the substrate calls them.
+
+### [L2] Provider conformance — provider-managed launches
+
+A provider is conforming iff, in addition to deploying only L1-conforming
+invocations:
+
+1. `info` and `deploy` implement the wire contract (§Provider
+   Protocol), including one-JSON-in/one-JSON-out and in-band
+   `{"ok": false}` errors. **Exit codes carry exactly one bit** — zero =
+   the operation's output is trustworthy, nonzero = failure regardless of
+   stdout (§Invocation's rule restated from the provider's side): a
+   provider MUST exit nonzero on any crash path and MUST NOT encode
+   structured meaning in nonzero values, because `D` discards partial
+   output rather than interpreting codes.
+2. It never requests or accepts credentials through
+   `provider_config` (I2).
+3. It builds agent identity env from top-level payload fields, never
+   from `env_vars` (reserved-key rule), applies §Launch data mechanically —
+   three-tier precedence, host-resolved re-derivation, no re-merge of
+   legacy `env_vars`, no provider-side model/provider mapping — and refuses
+   a deploy that resolves neither `auth_tag` nor `launch.owner_pubkey`, or
+   whose provider is `relay-mesh`.
+4. `deploy` implements the reconciliation loop (I4), stated
+   substrate-neutrally: identity derived from the nsec before any
+   mutation; candidates verified by **full-identity evidence** before any
+   action; live (= **started**: the harness process confirmed running, not
+   merely the body accepted) → strict no-op (zero mutation); never-started
+   states classified by evidence, not by substrate status strings
+   (provably-broken → fenced replace; recoverable + same recorded create
+   intent → observe, never delete, on this call or any later one;
+   recoverable + divergent intent → fenced replace); every read that can
+   authorize a destruction uses most-recent semantics; every destructive
+   write is **fenced to the exact observation that authorized it**
+   (compare-and-delete — the write fails if the object changed since the
+   read) and touches only objects carrying the provider's **management
+   marker** (the auto-repair fence, §Deploy State Machine);
+   same-status-code conflicts discriminated by a **machine-readable
+   conflict discriminator**, never the status code alone; success only on
+   confirmed harness start; conflicts converge by re-entry;
+   delete-of-absent is success.
+5. It emits no secret material in any output (belt to `D`'s
+   redaction suspenders).
+6. **Generic L3 obligation:** its binding *documents* how it realizes each
+   L2 term on its substrate, and how the owner's lifetime policy (bounded
+   vs indefinite) and clean-exit restart behavior are realized there —
+   stating the properties in its own vocabulary, not skipping them.
+
+### [L3] Kubernetes binding conformance — this binding
+
+The realization the two lists above require, in this binding's vocabulary:
+
+1. Each L2 item-4 term maps to the mechanism in §Deploy State Machine:
+   full-pubkey annotation for identity evidence, container `state.running`
+   for "started", `resourceVersion`-unset quorum reads for most-recent
+   semantics, UID+`resourceVersion` delete preconditions for fencing,
+   `Status.reason` as the 409 discriminator, and the
+   `app.kubernetes.io/managed-by` + binding-version labels as the
+   management marker.
+2. The deployed invocation realizes the lifetime policy the owner chose
+   (I5) through this binding's `inactivity_seconds` field: `> 0` →
+   a working inactivity bound and `restartPolicy: Never`; `0` (the
+   blessed indefinite opt-in) → no bound and `restartPolicy: OnFailure`,
+   **only after both prerequisites land** — the pinned exit-code contract
+   (I5 ordering rule) *and* the crash-loop classification row (§Pod
+   shape); until then the provider MUST refuse the combination.
+3. The harness is the deployed container's **signal-receiving process**
+   (PID 1 or the target of the pod's termination signal — §K8s
+   Entrypoint's `exec` rule), and `terminationGracePeriodSeconds` carries
+   the declared grace budget (§Pod shape).
+
+Conformance is testable without mechanization: a fake-provider harness can
+exercise L2 items 1–3 and 5 over the wire contract — including the pre-secret
+negotiation gate (§Discovery): an incompatible **or absent**
+`protocol_version` MUST be rejected before any request carrying
+`private_key_nsec` is sent; a **same-inode content rewrite** of the
+resolved binary after resolution MUST NOT reach the deploy invocation
+(the staged artifact still carries the bytes that answered `info`); and a
+**pathname swap after validation** — the resolved path re-pointed at a
+different file between the gate's checks and process spawn — likewise
+MUST NOT redirect the nsec (both cases are exactly what path+metadata
+comparison misses) — and an envtest/kind suite
+can drive L2 item 4's reconciler against a real apiserver — concurrent
+deploys, a deletion-marked pod, terminal restart, an annotation-mismatch
+collision, and SIGTERM→presence-offline for the L3 items. Three families of
+cases are mandatory because they were the review-found failure modes:
+**startup discrimination** (slow-but-valid scheduling → poll-then-succeed;
+`Unschedulable` during scale-from-zero → observed until the autoscaler
+provisions capacity, then success — never delete, **including when
+provisioning completes only after the 600s deadline**: the original pod
+identity and `creationTimestamp` survive the expired call and become the
+no-op winner on a later deploy, the case that pins the anti-livelock rule;
+a label-and-annotation-matching object **without the management marker** →
+never deleted, never GC'd, reported (the auto-repair fence under test);
+referenced Secret *confirmed absent* → preconditioned delete-recreate or
+actionable error, never silent success or no-op; a **never-started winner
+is repairable** — pod exists, Secret absent, container never started: a
+later deploy MUST delete-and-recreate rather than no-op, the test that pins
+started-not-phase as the no-op criterion; and the **classification→DELETE
+race** — the container transitions to running between the classifying read
+and the delete: the UID+resourceVersion precondition MUST fail and the
+live agent MUST be preserved) and the **GC/attempt interleaving** (attempt B's
+preflight GC running between attempt A's Secret create and pod create MUST
+NOT delete Secret A — the §K8s GC age gate under test; provider death after
+Secret create → the age gate protects, then a later GC reaps; and a
+**provider local clock fast beyond the margin** MUST NOT delete an
+in-flight Secret — cheap with a fake clock, and the same-clock rule's
+skip-on-absent-`Date` arm is exercised by stripping the header). A third
+family pins the **divergence discriminator and the 409 split**: a failed
+delete precondition (code 409, reason `Conflict`) → re-read and
+re-classify, never the create-conflict cleanup/adoption path; a create
+conflict (code 409, reason `AlreadyExists`) → loser-Secret cleanup and
+winner adoption, never treated as a failed delete; identical desired
+intent + permanently-Pending pod → no delete across arbitrarily many
+Starts, regardless of age; a resource/image correction against a
+never-started pod → fingerprint differs, preconditioned
+delete-and-recreate (the wedge-escape case); same user config but the
+provider's **baked default image digest** changed (provider upgrade)
+against a never-started pod → divergence, replace (the second intent
+source — the only escape from a bad-default-image wedge); the same correction against
+a **started** pod → strict zero-mutation no-op; admission
+defaulting/mutating the live pod → no false divergence (the comparison
+uses the recorded annotation); the fingerprint serializer property,
+asserted structurally — changing only Secret *values* or the generated
+Secret *name* leaves the fingerprint unchanged, changing any
+fingerprinted pod-create field changes it (equivalently: the serializer
+has no access to Secret data or attempt identity); and the
+conflict-path asymmetry — two no-instance contenders with different
+payloads: the create loser adopts the elected winner rather than
+deleting it for divergence, while a subsequent deploy observing that
+never-started divergent winner replaces it. A model checker is
+the wrong tool here: the failure modes found in review were wrong
+*abstractions of Kubernetes* (a nonexistent `Terminating` phase, non-atomic
+delete, phase-as-readiness, non-atomic Secret→pod against GC), which a
+hand-written model would have reproduced convincingly.
+
+## Known Defects (at `28ae6cd21`)
+
+**Citation pin:** every `file:line` reference in this document was verified
+against `28ae6cd21` — the commit at which this spec merged to `main`.
+References are to that tree; a later commit may offset them.
+
+Desktop- and harness-side, discovered during this design:
+
+1. **Windows discovery id pollution**: the `.exe` suffix survives into the
+   provider id, which then fails id validation at deploy — dropdown-visible,
+   probe-fine, deploy-broken. Fix is a suffix strip in discovery. (v1
+   provider scope is macOS+Linux regardless — [DECISION B].)
+2. **Provider env inheritance**: `invoke_provider` passes the desktop's
+   environment through unmodified; combined with launchd's minimal PATH this
+   breaks kubeconfig exec plugins. Mitigated provider-side (§K8s Auth);
+   a desktop-side PATH augmentation would fix the class.
+3. **Deploy payload bypasses the launch resolver** (the prerequisite this
+   spec names for §Launch data — a desktop code change, not spec text).
+   At `28ae6cd21`, `deploy_payload_json` serializes raw record bytes and a
+   three-layer `merged_user_env` where the local spawn uses
+   `resolve_effective_harness_descriptor`'s six-layer resolution. Concrete
+   consequences, each verified in review: (a) no per-runtime model/provider
+   env — a remote goose agent silently ignores the user's model choice, and
+   `provider_locked` runtimes would receive vars the desktop deliberately
+   withholds; (b) persona-derived `agent_command` and definition-provided
+   `agent_args` serialize as blank/empty — a different command line than the
+   identical local agent; (c) no `owner_pubkey` — a null-`auth_tag` agent
+   cannot match `!shutdown` (it *answers* it), stranding §Stop; (d) spawn
+   policy (`BUZZ_ACP_RELAY_OBSERVER`, runtime `default_env` such as
+   `GOOSE_MODE=auto`, team instructions, session title, lazy-pool selection)
+   is absent — remote pods run different observer/approval semantics
+   (`BUZZ_ACP_DEDUP`/`BUZZ_ACP_MULTIPLE_EVENT_HANDLING` are *not* on this
+   list: the local writes match the harness defaults, §Launch data); (e) a
+   mesh-provider agent deploys pointed at a loopback URL that cannot exist
+   in the pod instead of being refused. Until `deploy_payload_json` emits
+   the `launch` block, no provider can conform to §Launch data, and the
+   current payload MUST be treated as insufficient for a
+   semantics-preserving remote launch. **Security follow-through:** once
+   secrets can arrive via `launch.env`, desktop redaction MUST collect
+   candidate values from `launch.env` (and `launch.policy_env`) as well as
+   legacy `agent.env_vars` — at `28ae6cd21`, `env_secrets_from_request`
+   reads only `agent.env_vars` (`backend.rs`), leaving a
+   definition/persona-layer secret outside the literal-value scrub.
+   Conformance: a provider that echoes a launch-only secret into an error
+   must come back redacted.
+4. **The I5 reaper does not exist, and its natural home is a trap**
+   (harness code prerequisite). `BUZZ_ACP_EXIT_AFTER_INACTIVITY` appears
+   nowhere in the harness at `28ae6cd21`; §Auto-Stop is a design, not a
+   description. Worse, the obvious attachment point — the existing 30s
+   maintenance tick — is gated on `pool_ready` (`lib.rs:1743`), which under
+   `lazy_pool` only becomes true when work arrives, so a never-mentioned
+   lazy pod would never evaluate the bound: I5 dead in its most important
+   case (§Auto-Stop mechanism rule). The implementation MUST run the expiry
+   check on a pool-independent timer and MUST add the env var to
+   `RESERVED_ENV_KEYS` in the same change.
+5. **The deploy path never checks `protocol_version`** (desktop code
+   prerequisite). `provider_deploy` (`backend.rs`) sends the nsec-bearing
+   `deploy` request without any preceding `info` on the same resolved
+   executable; §Discovery's pre-secret negotiation gate is a design, not a
+   description, until the deploy command performs
+   resolve-once → stage-and-digest → `info` → explicit-version check →
+   `deploy`, both invocations running the staged bytes.
+6. **The clean-exit contract is emergent, not defended** (harness code
+   prerequisite; gates `OnFailure`). At `28ae6cd21`: the graceful path
+   returns `Ok(())` (`lib.rs:2723`), and owner `!shutdown` (`:2045`),
+   Ctrl-C (`:1635`), and
+   SIGTERM (`:1644`) all route into the same shutdown channel — so clean
+   stops exit 0 *today*, but no distinguished exit code exists and no test
+   pins "intentional exit ⇒ 0"; every `process::exit(1)` in the crate is a
+   startup failure. Until a
+   pinned, tested exit-code contract lands, no supervisor restart policy
+   (`restartPolicy: OnFailure`, systemd `Restart=on-failure`) may be
+   deployed against the harness: a refactor returning `Err` from a drain
+   timeout would silently convert every clean stop into a restart loop —
+   I5 defeated with no failing test (I5 ordering rule).
+7. **The shutdown tail overruns the declared grace budget at default
+   config** (harness code prerequisite). At `28ae6cd21`: the post-drain
+   reap segment
+   (`lib.rs:2664-2688`) runs *after* the 30s drain timeout closes
+   (`:2636,:2657`) and serially awaits a 5s post-SIGKILL wait per occupied
+   slot (`acp.rs:436`) — that segment alone reaches ~87s at the desktop's
+   default parallelism of 10 (`types.rs:814`; #3038 lowered it from 24),
+   ~197s at the harness cap of 32 (`config.rs:293`), against the binding's
+   60s grace; and it is not the whole tail — the wake-task drain
+   (`:2612`) and awakened-pool shutdown (`:2620-2624`, per-slot loop
+   `:3747-3751`, no timeout) precede it (§Stop), so the total is
+   unbounded by today's segment timeouts. The fix is one shared deadline
+   across the entire post-signal
+   path with a reserved finalization slice (≥ the finalizers' declared
+   bounds, currently 2s presence + 5s relay close = 7s) for presence
+   `offline` and
+   relay close, child cleanup degrading first (§Stop); natural home is the
+   same harness change as the I5 reaper (defect 4).
+8. **Cleared numeric config fields ship as strings** (desktop code
+   prerequisite, raised by blessing `0`). `coerceConfigValues`
+   (`desktop/src/features/agents/ui/ProviderConfigFields.tsx:6` at
+   `28ae6cd21`) skips numeric coercion when the value is `""`, so a
+   *cleared* numeric field reaches the provider as a JSON string instead
+   of a number. Blessing `inactivity_seconds: 0` makes clearing that
+   field a legitimate user action, so the empty-string arm now sits on a
+   documented path: the provider receives `""` where the schema says
+   integer, and "0 MUST NOT be rejected" cannot protect a value that
+   never parses as 0. Fix is desktop-side (map cleared numeric →
+   omit-or-default, never `""`); provider-side, a non-numeric value for a
+   numeric field is an in-band error, not a silent default.
+
+## Implementation Correspondence
+
+| spec concept | code |
+|---|---|
+| Discovery, resolution rule | `desktop/src-tauri/src/managed_agents/backend.rs` (`discover_provider_candidates`, `resolve_provider_binary`) |
+| Invocation, output caps, exit rule | `backend.rs` (`invoke_provider`) |
+| Pre-secret negotiation gate | *to be added*: `backend.rs` deploy path — resolve-once → stage-and-digest → `info` → explicit-version check → `deploy` on the staged bytes (Known Defect 5) |
+| Redaction | `backend.rs` (`redact_secrets_with`) |
+| I2 validation | `backend.rs` (`validate_provider_config`) |
+| I1 refusal, payload | `desktop/src-tauri/src/commands/agents_deploy.rs` |
+| Launch resolver (shared with local spawn) | `desktop/src-tauri/src/managed_agents/readiness.rs` (`resolve_effective_harness_descriptor`); `launch` block emission *to be added* to `agents_deploy.rs` (Known Defect 3) |
+| Mesh rewrite (why relay-mesh is non-deployable) | `desktop/src-tauri/src/managed_agents/relay_mesh.rs`; create-time rejection in `commands/agents.rs` (`normalize_relay_mesh`) |
+| Reserved-key strip | `desktop/src-tauri/src/managed_agents/env_vars.rs` (`RESERVED_ENV_KEYS`) |
+| Unconditional deploy on Start | `desktop/src-tauri/src/commands/agents.rs` (`start_managed_agent`) |
+| Presence publish / offline-on-exit | `crates/buzz-acp/src/lib.rs` (`publish_presence`, shutdown path) |
+| `!shutdown` owner check | `crates/buzz-acp/src/lib.rs` (main loop) |
+| Graceful shutdown path (budget enforcement *to be added* — Known Defect 7) | `crates/buzz-acp/src/lib.rs` (pool shutdown, then drain / reap / presence / relay close) |
+| Clean-exit exit-code contract | *to be added*: `crates/buzz-acp` distinguished exit codes + pinning test (Known Defect 6; gates `OnFailure`) |
+| Auto-stop flag | *to be added*: `crates/buzz-acp/src/config.rs` + a pool-independent timer (NOT the `pool_ready`-gated maintenance tick — Known Defect 4) + `RESERVED_ENV_KEYS` entry |
+| Kubernetes binding | *to be added*: `crates/buzz-backend-kubernetes` |
+| Sprig image | *to be added*: `Dockerfile.sprig` + workflow |
+
+## Open Decisions
+
+Marked `[DECISION]` inline; consolidated:
+
+- **A. Nest scaffolding** — should the image entrypoint scaffold the agent
+  workspace (AGENTS.md, RESEARCH/, …) that the desktop's `ensure_nest`
+  provides locally? Recommendation (revised): **workspace becomes a
+  protocol field the desktop states**, not an image-baked behavior — the
+  desktop resolves the nest content it would have written locally and
+  carries it in the launch data, so every substrate materializes the same
+  workspace from the same source of truth and the image stays
+  scaffold-free. An image-side template crate was the earlier
+  recommendation; it loses because it forks the nest definition into a
+  second implementation that drifts from `ensure_nest`.
+- **B. Windows scope** — fix the `.exe` discovery bug in the desktop now;
+  ship Windows provider binaries only on demand. Recommended as stated.
+- **C. Config budget** — the 9-field v1 set above. Recommended as stated.
+- **D. Desktop bundling** — `~/.local/bin` install only for v1. Recommended
+  as stated.
+- **E. Running-pod semantics** — no-op (recommended, both reviewers) vs
+  forcible recycle on Start. Ruled: **per-binding policy**, with one
+  universal property every binding must preserve — no sequence of Starts
+  yields two live instances in one scope (I4). The Kubernetes binding
+  keeps strict no-op in v1; a recycle affordance, if a binding adds one,
+  is stop-then-start, never delete-under-a-live-agent.
+- **F. Mesh deployability** — the spec refuses relay-mesh agents
+  pre-mutation in v1 (§Launch data: the transport is desktop loopback;
+  serializing it fails identically but invisibly). Reviewer consensus is
+  refusal; ratification requested because it makes a visible product cut
+  (shared-compute agents are local-only until an in-image mesh client
+  exists).
+- **G. Remote override semantics** — the spec keeps local semantics: user
+  env continues to beat Buzz behavior defaults remotely (three-tier
+  precedence, §Launch data), because the alternative is a quiet behavior
+  fork between local and remote spawns of the same record. Flagged because
+  it is a policy statement about what power users may do to remote pods.
+- **H. Startup budget** — with deploy success now requiring container start
+  (§Deploy State Machine), the 600s operation deadline is the de facto
+  cold-pull / scale-from-zero budget. The spec fixes the semantics
+  narrowly: the deadline bounds how long one Start waits synchronously —
+  never when anything is destroyed (recoverable startup is observational
+  across calls, so a cluster whose autoscaler `new-pod-scale-up-delay`
+  exceeds 600s degrades to "Start reports unconfirmed, a later Start
+  adopts the now-running pod", not a livelock). The remaining SLO ruling
+  is UX-only: is ten minutes of synchronous waiting the right ceiling for
+  the intended cluster class?
+- **I. Never-started escape hatch** — the create-intent fingerprint
+  (§Deploy State Machine) lets a config *change* replace a never-started
+  pod, closing the config wedge. Ruled on the vision-consistency half:
+  Start-time auto-repair of never-started bodies is legitimate, **fenced
+  to Buzz-authored, positively identified residue** (§Deploy State Machine
+  auto-repair rule) — the vision's "never-started body is operator
+  residue" line gains that qualifier rather than being waived. The
+  remaining product question: does v1 owe users an explicit in-product
+  "clear this stuck deployment" affordance for a never-started pod whose
+  config they have *not* changed (a genuinely slow or broken cluster)?
+  Both reviewers agree on the mechanism; this is the remaining product
+  question layered on top of it.
+
+## Summary
+
+Remote agents extend Buzz's managed-agent model across a deliberately thin
+boundary: one untrusted binary, two JSON operations, and a relay. The
+desktop's obligations end at a well-formed, fail-closed deploy payload; the
+provider's obligations are convergence and honesty about state; the agent's
+obligation is to honor its owner's lifetime choice — bounded by default,
+indefinite by declaration, and in either case final when told to stop.
+Everything else — status, control,
+memory — was already on the relay, which is why the design holds: the relay
+was the management plane all along, and the desktop was only ever one of
+its doors.
diff --git a/mobile/ios/Runner/InlinePhotoPicker.swift b/mobile/ios/Runner/InlinePhotoPicker.swift
index 05a576323f..4126734779 100644
--- a/mobile/ios/Runner/InlinePhotoPicker.swift
+++ b/mobile/ios/Runner/InlinePhotoPicker.swift
@@ -3,14 +3,6 @@ import PhotosUI
 import UIKit
 import UniformTypeIdentifiers
 
-enum EmbeddedPhotoPickerLayout {
-  static func applyPreferredScale(_ zoomIn: () -> Void) {
-    UIView.performWithoutAnimation {
-      zoomIn()
-    }
-  }
-}
-
 final class InlinePhotoPickerFactory: NSObject, FlutterPlatformViewFactory {
   private let messenger: FlutterBinaryMessenger
   private weak var parentViewController: UIViewController?
@@ -130,9 +122,6 @@ final class InlinePhotoPickerPlatformView: NSObject, FlutterPlatformView {
     }
     pickerViewController = picker
     containerView.layoutIfNeeded()
-    EmbeddedPhotoPickerLayout.applyPreferredScale {
-      picker.zoomIn()
-    }
   }
 
   private func exportPickerResult(_ result: PHPickerResult) async throws -> String {
diff --git a/mobile/ios/Runner/NativeAttachmentPopover.swift b/mobile/ios/Runner/NativeAttachmentPopover.swift
index f2f6c01df8..cc29de9cb3 100644
--- a/mobile/ios/Runner/NativeAttachmentPopover.swift
+++ b/mobile/ios/Runner/NativeAttachmentPopover.swift
@@ -17,8 +17,6 @@ final class NativeAttachmentPopoverViewController:
     case camera
   }
 
-  private typealias ContentPreparation = (@escaping () -> Void) -> Void
-
   private let channel: FlutterMethodChannel
   private let expandedWidth: CGFloat
   private let maximumMenuHeight: CGFloat
@@ -85,17 +83,29 @@ final class NativeAttachmentPopoverViewController:
   override func viewDidLoad() {
     super.viewDidLoad()
     view.backgroundColor = .clear
-    view.layer.cornerRadius = 22
+    view.layer.cornerRadius = NativeAttachmentPopoverStyle.cornerRadius
     view.layer.cornerCurve = .continuous
-    view.clipsToBounds = true
+    view.layer.borderColor = UIColor.black.withAlphaComponent(0.04).cgColor
+    view.layer.borderWidth = NativeAttachmentPopoverStyle.borderWidth
+    view.layer.shadowColor = UIColor.black.cgColor
+    view.layer.shadowOpacity = NativeAttachmentPopoverStyle.shadowOpacity
+    view.layer.shadowRadius = NativeAttachmentPopoverStyle.shadowRadius
+    view.layer.shadowOffset = NativeAttachmentPopoverStyle.shadowOffset
+    view.clipsToBounds = false
 
     let glassEffect = UIGlassEffect(style: .regular)
     glassEffect.isInteractive = true
     let glassView = UIVisualEffectView(effect: glassEffect)
     glassView.translatesAutoresizingMaskIntoConstraints = false
+    glassView.layer.cornerRadius = NativeAttachmentPopoverStyle.cornerRadius
+    glassView.layer.cornerCurve = .continuous
+    glassView.clipsToBounds = true
     view.addSubview(glassView)
 
     contentHost.translatesAutoresizingMaskIntoConstraints = false
+    contentHost.layer.cornerRadius = NativeAttachmentPopoverStyle.cornerRadius
+    contentHost.layer.cornerCurve = .continuous
+    contentHost.clipsToBounds = true
     view.addSubview(contentHost)
     NSLayoutConstraint.activate([
       glassView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
@@ -114,6 +124,11 @@ final class NativeAttachmentPopoverViewController:
 
   override func viewDidLayoutSubviews() {
     super.viewDidLayoutSubviews()
+    view.layer.shadowPath =
+      UIBezierPath(
+        roundedRect: view.bounds,
+        cornerRadius: NativeAttachmentPopoverStyle.cornerRadius
+      ).cgPath
     cameraPreviewLayer?.frame = cameraPreviewView?.bounds ?? .zero
   }
 
@@ -198,21 +213,21 @@ final class NativeAttachmentPopoverViewController:
       makeNativeAttachmentMenuButton(
         title: "Camera",
         symbol: "camera",
-        action: UIAction { [weak self] _ in self?.showCamera() }
+        action: { [weak self] in self?.showCamera() }
       )
     )
     stack.addArrangedSubview(
       makeNativeAttachmentMenuButton(
         title: "Photos",
         symbol: "photo.on.rectangle.angled",
-        action: UIAction { [weak self] _ in self?.showPhotos() }
+        action: { [weak self] in self?.showPhotos() }
       )
     )
     stack.addArrangedSubview(
       makeNativeAttachmentMenuButton(
         title: "Video",
         symbol: "video",
-        action: UIAction { [weak self] _ in
+        action: { [weak self] in
           self?.finish(method: "pickVideo")
         }
       )
@@ -221,7 +236,7 @@ final class NativeAttachmentPopoverViewController:
       makeNativeAttachmentMenuButton(
         title: "Files",
         symbol: "doc",
-        action: UIAction { [weak self] _ in
+        action: { [weak self] in
           self?.finish(method: "pickFiles")
         }
       )
@@ -280,14 +295,14 @@ final class NativeAttachmentPopoverViewController:
       title: nil,
       symbol: "chevron.left",
       accessibilityLabel: "Back to attachment options",
-      action: UIAction { [weak self] _ in self?.showMenu() }
+      action: { [weak self] in self?.showMenu() }
     )
     let actionButton = makeGlassControl(
       title: "All Photos",
       symbol: nil,
       accessibilityLabel: "All Photos",
       prominent: true,
-      action: UIAction { [weak self] _ in self?.performPhotoAction() }
+      action: { [weak self] in self?.performPhotoAction() }
     )
     photoActionButton = actionButton
     addBottomControls(
@@ -296,27 +311,7 @@ final class NativeAttachmentPopoverViewController:
       trailing: actionButton
     )
 
-    transition(
-      to: .photos,
-      content: container,
-      preparation: { [weak picker] reveal in
-        guard let picker else {
-          reveal()
-          return
-        }
-        // PHPicker ignores scale changes while its remote grid is still
-        // adapting to the compact menu bounds. Give it one main-loop turn at
-        // the final popover size, apply the scale offscreen, then reveal it.
-        DispatchQueue.main.async {
-          picker.view.layoutIfNeeded()
-          EmbeddedPhotoPickerLayout.applyPreferredScale {
-            picker.zoomIn()
-            picker.view.layoutIfNeeded()
-          }
-          DispatchQueue.main.async(execute: reveal)
-        }
-      }
-    )
+    transition(to: .photos, content: container)
   }
 
   private func showCamera() {
@@ -353,7 +348,7 @@ final class NativeAttachmentPopoverViewController:
       title: nil,
       symbol: "chevron.left",
       accessibilityLabel: "Back to attachment options",
-      action: UIAction { [weak self] _ in self?.showMenu() }
+      action: { [weak self] in self?.showMenu() }
     )
     let captureButton = makeCameraCaptureButton()
     cameraCaptureButton = captureButton
@@ -415,7 +410,6 @@ final class NativeAttachmentPopoverViewController:
   private func transition(
     to nextSurface: Surface,
     content nextView: UIView,
-    preparation: ContentPreparation? = nil,
     completion: (() -> Void)? = nil
   ) {
     let previousView = visibleContentView
@@ -485,11 +479,7 @@ final class NativeAttachmentPopoverViewController:
         }
       }
 
-      if let preparation {
-        preparation(reveal)
-      } else {
-        reveal()
-      }
+      reveal()
     }
   }
 
@@ -498,7 +488,7 @@ final class NativeAttachmentPopoverViewController:
     symbol: String?,
     accessibilityLabel: String,
     prominent: Bool = false,
-    action: UIAction
+    action: @escaping () -> Void
   ) -> UIButton {
     var configuration =
       prominent
@@ -513,20 +503,37 @@ final class NativeAttachmentPopoverViewController:
     }
     configuration.imagePadding = 8
     configuration.baseForegroundColor = .white
+    configuration.titleTextAttributesTransformer =
+      UIConfigurationTextAttributesTransformer { attributes in
+        var interAttributes = attributes
+        interAttributes.font = NativeAttachmentMenuTypography.font(
+          forTextStyle: .body
+        )
+        return interAttributes
+      }
     configuration.contentInsets = NSDirectionalEdgeInsets(
       top: 11,
       leading: 15,
       bottom: 11,
       trailing: 15
     )
-    let button = UIButton(configuration: configuration, primaryAction: action)
+    let button = UIButton(
+      configuration: configuration,
+      primaryAction: UIAction { _ in
+        UISelectionFeedbackGenerator().selectionChanged()
+        action()
+      }
+    )
     button.accessibilityLabel = accessibilityLabel
     return button
   }
 
   private func makeCameraCaptureButton() -> UIButton {
     let button = UIButton(
-      primaryAction: UIAction { [weak self] _ in self?.capturePhoto() }
+      primaryAction: UIAction { [weak self] _ in
+        UISelectionFeedbackGenerator().selectionChanged()
+        self?.capturePhoto()
+      }
     )
     button.accessibilityLabel = "Take photo"
     button.translatesAutoresizingMaskIntoConstraints = false
diff --git a/mobile/ios/Runner/NativeAttachmentPopoverCoordinator.swift b/mobile/ios/Runner/NativeAttachmentPopoverCoordinator.swift
index 73559d7c2b..f59db1f84c 100644
--- a/mobile/ios/Runner/NativeAttachmentPopoverCoordinator.swift
+++ b/mobile/ios/Runner/NativeAttachmentPopoverCoordinator.swift
@@ -1,3 +1,4 @@
+import CoreText
 import Flutter
 import UIKit
 
@@ -276,7 +277,7 @@ enum NativeAttachmentMenuLayout {
   static func itemHeight(
     compatibleWith traitCollection: UITraitCollection
   ) -> CGFloat {
-    let labelHeight = UIFont.preferredFont(
+    let labelHeight = NativeAttachmentMenuTypography.font(
       forTextStyle: labelTextStyle,
       compatibleWith: traitCollection
     ).lineHeight
@@ -313,12 +314,71 @@ enum NativeAttachmentMenuLayout {
   }
 }
 
+enum NativeAttachmentMenuTypography {
+  static let interPostScriptName = "InterVariable"
+
+  private static let registeredInter: Bool = {
+    let fontURL = Bundle.main.bundleURL
+      .appendingPathComponent("Frameworks")
+      .appendingPathComponent("App.framework")
+      .appendingPathComponent("flutter_assets")
+      .appendingPathComponent("assets")
+      .appendingPathComponent("fonts")
+      .appendingPathComponent("InterVariable.ttf")
+    guard FileManager.default.fileExists(atPath: fontURL.path) else {
+      return false
+    }
+    return CTFontManagerRegisterFontsForURL(
+      fontURL as CFURL,
+      .process,
+      nil
+    )
+  }()
+
+  static func font(
+    forTextStyle textStyle: UIFont.TextStyle,
+    compatibleWith traitCollection: UITraitCollection? = nil
+  ) -> UIFont {
+    _ = registeredInter
+    let scaledPointSize = UIFontMetrics(forTextStyle: textStyle).scaledValue(
+      for: 20,
+      compatibleWith: traitCollection
+    )
+    let preferredFont = UIFont.preferredFont(
+      forTextStyle: textStyle,
+      compatibleWith: traitCollection
+    )
+    guard
+      let interFont = UIFont(
+        name: interPostScriptName,
+        size: scaledPointSize
+      )
+    else {
+      return preferredFont
+    }
+    return interFont
+  }
+}
+
+enum NativeAttachmentPopoverStyle {
+  static let cornerRadius: CGFloat = 20
+  static let shadowOpacity: Float = 0.18
+  static let shadowRadius: CGFloat = 12
+  static let shadowOffset = CGSize(width: 0, height: 6)
+  static let borderWidth: CGFloat = 1
+}
+
 func makeNativeAttachmentMenuButton(
   title: String,
   symbol: String,
-  action: UIAction
+  action: @escaping () -> Void
 ) -> UIButton {
-  let button = UIButton(primaryAction: action)
+  let button = UIButton(
+    primaryAction: UIAction { _ in
+      UISelectionFeedbackGenerator().selectionChanged()
+      action()
+    }
+  )
   button.accessibilityLabel = title
 
   let symbolConfiguration = UIImage.SymbolConfiguration(
@@ -338,7 +398,7 @@ func makeNativeAttachmentMenuButton(
   let titleLabel = UILabel()
   titleLabel.text = title
   titleLabel.textColor = .label
-  titleLabel.font = .preferredFont(
+  titleLabel.font = NativeAttachmentMenuTypography.font(
     forTextStyle: NativeAttachmentMenuLayout.labelTextStyle
   )
   titleLabel.adjustsFontForContentSizeCategory = true
diff --git a/mobile/ios/RunnerTests/RunnerTests.swift b/mobile/ios/RunnerTests/RunnerTests.swift
index c5333cfdf2..8374ca77b6 100644
--- a/mobile/ios/RunnerTests/RunnerTests.swift
+++ b/mobile/ios/RunnerTests/RunnerTests.swift
@@ -127,19 +127,6 @@ class RunnerTests: XCTestCase {
     )
   }
 
-  func testEmbeddedPhotoPickerAppliesOneZoomInStepWithoutAnimation() {
-    var zoomInCalls = 0
-    var animationsWereEnabled = true
-
-    EmbeddedPhotoPickerLayout.applyPreferredScale {
-      zoomInCalls += 1
-      animationsWereEnabled = UIView.areAnimationsEnabled
-    }
-
-    XCTAssertEqual(zoomInCalls, 1)
-    XCTAssertFalse(animationsWereEnabled)
-  }
-
   func testNativeAttachmentMenuUsesRoomyRowsAndInsets() {
     let traits = UITraitCollection(preferredContentSizeCategory: .large)
     let size = NativeAttachmentMenuLayout.size(compatibleWith: traits)
@@ -155,6 +142,28 @@ class RunnerTests: XCTestCase {
     XCTAssertEqual(NativeAttachmentMenuLayout.labelTextStyle, .title3)
   }
 
+  func testNativeAttachmentMenuUsesInterAndSharedPopoverChrome() {
+    let font = NativeAttachmentMenuTypography.font(
+      forTextStyle: NativeAttachmentMenuLayout.labelTextStyle
+    )
+    var didSelect = false
+    let button = makeNativeAttachmentMenuButton(
+      title: "Photos",
+      symbol: "photo",
+      action: { didSelect = true }
+    )
+    let titleLabel = button.subviews.compactMap { $0 as? UILabel }.first
+
+    XCTAssertTrue(font.fontName.hasPrefix("Inter"))
+    XCTAssertTrue(titleLabel?.font.fontName.hasPrefix("Inter") == true)
+    XCTAssertEqual(NativeAttachmentPopoverStyle.cornerRadius, 20)
+    XCTAssertEqual(NativeAttachmentPopoverStyle.borderWidth, 1)
+    XCTAssertEqual(NativeAttachmentPopoverStyle.shadowOpacity, 0.18)
+
+    button.sendActions(for: .primaryActionTriggered)
+    XCTAssertTrue(didSelect)
+  }
+
   func testNativeAttachmentMenuGrowsAndScrollsForAccessibilityText() {
     let traits = UITraitCollection(
       preferredContentSizeCategory: .accessibilityExtraExtraExtraLarge
diff --git a/mobile/lib/features/activity/activity_page.dart b/mobile/lib/features/activity/activity_page.dart
index aecef6329c..5b4cebfa97 100644
--- a/mobile/lib/features/activity/activity_page.dart
+++ b/mobile/lib/features/activity/activity_page.dart
@@ -37,6 +37,18 @@ part 'activity_page/inbox_row.dart';
 part 'activity_page/lists.dart';
 part 'activity_page/status_views.dart';
 
+EdgeInsets _activityScrollPadding(
+  BuildContext context, {
+  double horizontal = 0,
+  double top = Grid.xxs,
+  double bottom = Grid.xxs,
+}) => EdgeInsets.fromLTRB(
+  horizontal,
+  top,
+  horizontal,
+  MediaQuery.paddingOf(context).bottom + bottom,
+);
+
 /// Conversation-oriented Activity inbox.
 ///
 /// Matches desktop's Home inbox item design and semantics (see
@@ -264,7 +276,7 @@ class ActivityPage extends HookConsumerWidget {
       body = RefreshIndicator(
         onRefresh: refresh,
         child: ListView.builder(
-          padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
+          padding: _activityScrollPadding(context),
           itemCount: visibleItems.length,
           itemBuilder: (context, index) {
             final item = visibleItems[index];
@@ -318,7 +330,9 @@ class ActivityPage extends HookConsumerWidget {
         ],
       ),
       body: SafeArea(
+        key: const ValueKey('activity-content-safe-area'),
         top: false,
+        bottom: false,
         child: Padding(
           padding: EdgeInsets.only(
             top: frostedAppBarHeight(context, titleStyle: headerTitleStyle),
diff --git a/mobile/lib/features/activity/activity_page/header_actions.dart b/mobile/lib/features/activity/activity_page/header_actions.dart
index 56592e2e69..39bb29e7a3 100644
--- a/mobile/lib/features/activity/activity_page/header_actions.dart
+++ b/mobile/lib/features/activity/activity_page/header_actions.dart
@@ -39,15 +39,6 @@ class _FilterMenuButton extends StatelessWidget {
             alignment: AnchoredPopoverAlignment.start,
             offset: const Offset(0, Grid.half),
             menuPadding: const EdgeInsets.symmetric(vertical: Grid.half),
-            color: context.colors.surface.withValues(alpha: 0.98),
-            elevation: 8,
-            shadowColor: context.colors.shadow.withValues(alpha: 0.18),
-            shape: RoundedRectangleBorder(
-              borderRadius: BorderRadius.circular(Radii.card),
-              side: BorderSide(
-                color: context.colors.outlineVariant.withValues(alpha: 0.45),
-              ),
-            ),
             surfaceKey: const ValueKey('activity-filter-popover'),
             items: [
               for (final entry in _filterLabels.entries)
@@ -183,13 +174,6 @@ class _InboxOptionsButton extends StatelessWidget {
             context: buttonContext,
             width: 216,
             alignment: AnchoredPopoverAlignment.end,
-            color: context.colors.surface,
-            elevation: 4,
-            shadowColor: context.colors.shadow.withValues(alpha: 0.18),
-            shape: RoundedRectangleBorder(
-              borderRadius: BorderRadius.circular(Radii.md),
-              side: BorderSide(color: context.colors.outline),
-            ),
             surfaceKey: const ValueKey('activity-options-popover'),
             items: [
               PopupMenuItem(
diff --git a/mobile/lib/features/activity/activity_page/lists.dart b/mobile/lib/features/activity/activity_page/lists.dart
index 37311c9287..9df193fe96 100644
--- a/mobile/lib/features/activity/activity_page/lists.dart
+++ b/mobile/lib/features/activity/activity_page/lists.dart
@@ -36,7 +36,7 @@ class _RemindersList extends ConsumerWidget {
     return RefreshIndicator(
       onRefresh: onRefresh,
       child: ListView.builder(
-        padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
+        padding: _activityScrollPadding(context),
         itemCount: reminders.length,
         itemBuilder: (context, index) {
           final reminder = reminders[index];
@@ -97,7 +97,7 @@ class _DraftsList extends StatelessWidget {
     }
 
     return ListView.builder(
-      padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
+      padding: _activityScrollPadding(context),
       itemCount: drafts.length,
       itemBuilder: (context, index) {
         final draft = drafts[index];
diff --git a/mobile/lib/features/activity/activity_page/status_views.dart b/mobile/lib/features/activity/activity_page/status_views.dart
index 11115d9dc8..442634849c 100644
--- a/mobile/lib/features/activity/activity_page/status_views.dart
+++ b/mobile/lib/features/activity/activity_page/status_views.dart
@@ -6,7 +6,12 @@ class _LoadingSkeleton extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     return ListView.separated(
-      padding: const EdgeInsets.all(Grid.gutter),
+      padding: _activityScrollPadding(
+        context,
+        horizontal: Grid.gutter,
+        top: Grid.gutter,
+        bottom: Grid.gutter,
+      ),
       itemCount: 8,
       separatorBuilder: (_, _) => const SizedBox(height: Grid.xs),
       itemBuilder: (context, _) => Row(
diff --git a/mobile/lib/features/channels/channel_detail_page.dart b/mobile/lib/features/channels/channel_detail_page.dart
index 044342d101..f1efb1557f 100644
--- a/mobile/lib/features/channels/channel_detail_page.dart
+++ b/mobile/lib/features/channels/channel_detail_page.dart
@@ -1,5 +1,6 @@
 import 'dart:async';
 import 'dart:math' show min;
+import 'dart:ui';
 
 import 'package:flutter/material.dart';
 import 'package:flutter/rendering.dart' show ScrollDirection;
@@ -32,6 +33,7 @@ import 'channel_typing_provider.dart';
 import 'channel_typing_indicator.dart';
 import 'channels_provider.dart';
 import 'compose_bar.dart';
+import 'composer_dock_size_reporter.dart';
 import 'date_formatters.dart';
 import 'day_divider.dart';
 import 'dm_channel_labels.dart';
@@ -125,6 +127,7 @@ class ChannelDetailPage extends HookConsumerWidget {
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
+    final composerDockHeight = useState(0.0);
     final detailsAsync = ref.watch(channelDetailsProvider(channel.id));
     final channelsAsync = ref.watch(channelsProvider);
     final messagesState = ref.watch(channelMessagesProvider(channel.id));
@@ -156,6 +159,10 @@ class ChannelDetailPage extends HookConsumerWidget {
         channel;
     final resolvedChannel =
         detailsAsync.whenData(baseChannel.mergeDetails).value ?? baseChannel;
+    final showsComposer =
+        !resolvedChannel.isForum &&
+        resolvedChannel.isMember &&
+        !resolvedChannel.isArchived;
     final messagesNotifier = ref.read(
       channelMessagesProvider(channel.id).notifier,
     );
@@ -188,6 +195,11 @@ class ChannelDetailPage extends HookConsumerWidget {
       messagesState: messagesState,
     );
 
+    useEffect(() {
+      final session = ref.read(relaySessionProvider.notifier);
+      return session.registerVisibleChannel(channel.id);
+    }, [channel.id]);
+
     // Preload channel member profiles so @mentions resolve correctly.
     useEffect(() {
       _preloadMembers(ref, channel.id);
@@ -288,122 +300,162 @@ class ChannelDetailPage extends HookConsumerWidget {
             ),
         ],
       ),
-      body: Column(
+      body: Stack(
+        fit: StackFit.expand,
         children: [
-          Expanded(
-            child: resolvedChannel.isForum
-                ? Stack(
-                    fit: StackFit.expand,
-                    children: [
-                      ForumPostsView(
-                        channel: resolvedChannel,
-                        currentPubkey: currentPubkey,
-                      ),
-                      if (showConnectionSkeleton.value)
-                        Positioned(
-                          top:
-                              frostedAppBarHeight(
+          Column(
+            children: [
+              Expanded(
+                child: resolvedChannel.isForum
+                    ? Stack(
+                        fit: StackFit.expand,
+                        children: [
+                          ForumPostsView(
+                            channel: resolvedChannel,
+                            currentPubkey: currentPubkey,
+                          ),
+                          if (showConnectionSkeleton.value)
+                            Positioned(
+                              top:
+                                  frostedAppBarHeight(
+                                    context,
+                                    titleContentHeight:
+                                        appBarTitleContentHeight,
+                                  ) +
+                                  Grid.xs,
+                              left: Grid.gutter,
+                              right: Grid.gutter,
+                              child: _ForumConnectionSkeleton(
+                                status: sessionStatus,
+                              ),
+                            ),
+                        ],
+                      )
+                    : SkeletonReveal(
+                        loading:
+                            showInitialConnectionSkeleton ||
+                            showConnectionSkeleton.value ||
+                            messagesState.isLoading,
+                        shimmerEnabled:
+                            sessionStatus != SessionStatus.disconnected,
+                        skeleton: _MessageTimelineSkeleton(
+                          appBarTitleContentHeight: appBarTitleContentHeight,
+                          status: sessionStatus,
+                        ),
+                        content: messagesState.when(
+                          loading: SizedBox.shrink,
+                          error: (e, _) => Padding(
+                            padding: EdgeInsets.only(
+                              top: frostedAppBarHeight(
                                 context,
                                 titleContentHeight: appBarTitleContentHeight,
-                              ) +
-                              Grid.xs,
-                          left: Grid.gutter,
-                          right: Grid.gutter,
-                          child: _ForumConnectionSkeleton(
-                            status: sessionStatus,
-                          ),
-                        ),
-                    ],
-                  )
-                : SkeletonReveal(
-                    loading:
-                        showInitialConnectionSkeleton ||
-                        showConnectionSkeleton.value ||
-                        messagesState.isLoading,
-                    shimmerEnabled: sessionStatus != SessionStatus.disconnected,
-                    skeleton: _MessageTimelineSkeleton(
-                      appBarTitleContentHeight: appBarTitleContentHeight,
-                      status: sessionStatus,
-                    ),
-                    content: messagesState.when(
-                      loading: SizedBox.shrink,
-                      error: (e, _) => Padding(
-                        padding: EdgeInsets.only(
-                          top: frostedAppBarHeight(
-                            context,
-                            titleContentHeight: appBarTitleContentHeight,
-                          ),
-                        ),
-                        child: Center(
-                          child: Text(
-                            'Failed to load messages',
-                            style: context.textTheme.bodyMedium?.copyWith(
-                              color: context.colors.error,
+                              ),
+                            ),
+                            child: Center(
+                              child: Text(
+                                'Failed to load messages',
+                                style: context.textTheme.bodyMedium?.copyWith(
+                                  color: context.colors.error,
+                                ),
+                              ),
                             ),
                           ),
+                          data: (events) {
+                            final messages = formatTimeline(
+                              events,
+                              currentPubkey: currentPubkey,
+                            );
+                            final summaries = ref
+                                .read(
+                                  channelMessagesProvider(channel.id).notifier,
+                                )
+                                .threadSummaries;
+                            final entries = buildMainTimelineEntries(
+                              messages,
+                              relaySummaries: summaries,
+                            );
+                            return _MessageList(
+                              entries: entries,
+                              allMessages: messages,
+                              initialMessageId: initialMessageId,
+                              initialThreadRootId: initialThreadRootId,
+                              channelId: channel.id,
+                              currentPubkey: currentPubkey,
+                              isMember: resolvedChannel.isMember,
+                              isArchived: resolvedChannel.isArchived,
+                              appBarTitleContentHeight:
+                                  appBarTitleContentHeight,
+                              composerBottomInset: showsComposer
+                                  ? composerDockHeight.value
+                                  : 0,
+                            );
+                          },
                         ),
                       ),
-                      data: (events) {
-                        final messages = formatTimeline(
-                          events,
-                          currentPubkey: currentPubkey,
-                        );
-                        final summaries = ref
-                            .read(channelMessagesProvider(channel.id).notifier)
-                            .threadSummaries;
-                        final entries = buildMainTimelineEntries(
-                          messages,
-                          relaySummaries: summaries,
-                        );
-                        return _MessageList(
-                          entries: entries,
-                          allMessages: messages,
-                          initialMessageId: initialMessageId,
-                          initialThreadRootId: initialThreadRootId,
-                          channelId: channel.id,
-                          currentPubkey: currentPubkey,
-                          isMember: resolvedChannel.isMember,
-                          isArchived: resolvedChannel.isArchived,
-                          appBarTitleContentHeight: appBarTitleContentHeight,
-                        );
-                      },
-                    ),
-                  ),
+              ),
+              if (!resolvedChannel.isForum &&
+                  (!resolvedChannel.isMember ||
+                      resolvedChannel.isArchived)) ...[
+                AnimatedSize(
+                  duration: MediaQuery.disableAnimationsOf(context)
+                      ? Duration.zero
+                      : const Duration(milliseconds: 180),
+                  curve: Curves.easeOutCubic,
+                  alignment: Alignment.bottomCenter,
+                  child: typingEntries.isEmpty
+                      ? const SizedBox.shrink()
+                      : ChannelTypingIndicator(entries: typingEntries),
+                ),
+                if (!resolvedChannel.isDm)
+                  _ReadOnlyNotice(channel: resolvedChannel),
+              ],
+            ],
           ),
-          if (!resolvedChannel.isForum)
-            AnimatedSize(
-              duration: MediaQuery.disableAnimationsOf(context)
-                  ? Duration.zero
-                  : const Duration(milliseconds: 180),
-              curve: Curves.easeOutCubic,
+          if (showsComposer)
+            Align(
               alignment: Alignment.bottomCenter,
-              child: typingEntries.isEmpty
-                  ? const SizedBox.shrink()
-                  : ChannelTypingIndicator(entries: typingEntries),
+              child: ComposerDockSizeReporter(
+                key: const ValueKey('channel-composer-dock'),
+                onHeightChanged: (height) {
+                  if ((composerDockHeight.value - height).abs() < 0.5) return;
+                  composerDockHeight.value = height;
+                },
+                child: Column(
+                  mainAxisSize: MainAxisSize.min,
+                  children: [
+                    AnimatedSize(
+                      duration: MediaQuery.disableAnimationsOf(context)
+                          ? Duration.zero
+                          : const Duration(milliseconds: 180),
+                      curve: Curves.easeOutCubic,
+                      alignment: Alignment.bottomCenter,
+                      child: typingEntries.isEmpty
+                          ? const SizedBox.shrink()
+                          : ChannelTypingIndicator(entries: typingEntries),
+                    ),
+                    ComposeBar(
+                      channelId: channel.id,
+                      channelName: resolvedChannel.isDm
+                          ? ''
+                          : resolvedChannel.name,
+                      onSend:
+                          (
+                            content,
+                            mentionPubkeys, {
+                            mediaTags = const <List<String>>[],
+                          }) => ref
+                              .read(sendMessageProvider)
+                              .call(
+                                channelId: channel.id,
+                                content: content,
+                                mentionPubkeys: mentionPubkeys,
+                                mediaTags: mediaTags,
+                              ),
+                    ),
+                  ],
+                ),
+              ),
             ),
-          if (!resolvedChannel.isForum &&
-              resolvedChannel.isMember &&
-              !resolvedChannel.isArchived)
-            ComposeBar(
-              channelId: channel.id,
-              channelName: resolvedChannel.isDm ? '' : resolvedChannel.name,
-              onSend:
-                  (
-                    content,
-                    mentionPubkeys, {
-                    mediaTags = const <List<String>>[],
-                  }) => ref
-                      .read(sendMessageProvider)
-                      .call(
-                        channelId: channel.id,
-                        content: content,
-                        mentionPubkeys: mentionPubkeys,
-                        mediaTags: mediaTags,
-                      ),
-            )
-          else if (!resolvedChannel.isDm &&
-              (!resolvedChannel.isMember || resolvedChannel.isArchived))
-            _ReadOnlyNotice(channel: resolvedChannel),
         ],
       ),
     );
diff --git a/mobile/lib/features/channels/channel_detail_page/message_list.dart b/mobile/lib/features/channels/channel_detail_page/message_list.dart
index eacba5856e..ac73a5076e 100644
--- a/mobile/lib/features/channels/channel_detail_page/message_list.dart
+++ b/mobile/lib/features/channels/channel_detail_page/message_list.dart
@@ -10,6 +10,7 @@ class _MessageList extends HookConsumerWidget {
   final bool isMember;
   final bool isArchived;
   final double appBarTitleContentHeight;
+  final double composerBottomInset;
 
   const _MessageList({
     required this.entries,
@@ -21,6 +22,7 @@ class _MessageList extends HookConsumerWidget {
     required this.isMember,
     required this.isArchived,
     required this.appBarTitleContentHeight,
+    required this.composerBottomInset,
   });
 
   @override
@@ -259,7 +261,7 @@ class _MessageList extends HookConsumerWidget {
                   context,
                   titleContentHeight: appBarTitleContentHeight,
                 ),
-                bottom: 0,
+                bottom: composerBottomInset,
               ),
               itemCount: displayEntries.length + (isLoadingOlder.value ? 1 : 0),
               itemBuilder: (context, index) {
@@ -356,21 +358,11 @@ class _MessageList extends HookConsumerWidget {
           Positioned(
             left: 0,
             right: 0,
-            bottom: Grid.xs,
+            bottom: composerBottomInset + Grid.xs,
             child: Center(
-              child: FilledButton.icon(
+              child: _JumpToLatestButton(
                 key: const ValueKey('channel-jump-to-latest'),
                 onPressed: scrollToLatest,
-                style: FilledButton.styleFrom(
-                  backgroundColor: context.colors.primaryContainer,
-                  foregroundColor: context.colors.onPrimaryContainer,
-                  padding: const EdgeInsets.symmetric(
-                    horizontal: Grid.gutter,
-                    vertical: Grid.xxs,
-                  ),
-                ),
-                icon: const Icon(LucideIcons.arrowDown, size: 16),
-                label: const Text('Latest'),
               ),
             ),
           ),
@@ -378,3 +370,64 @@ class _MessageList extends HookConsumerWidget {
     );
   }
 }
+
+class _JumpToLatestButton extends StatelessWidget {
+  final VoidCallback onPressed;
+
+  const _JumpToLatestButton({required this.onPressed, super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    final borderRadius = BorderRadius.circular(Radii.full);
+    return Semantics(
+      button: true,
+      child: ClipRRect(
+        borderRadius: borderRadius,
+        child: BackdropFilter(
+          filter: ImageFilter.blur(sigmaX: 20, sigmaY: 20),
+          child: Container(
+            key: const ValueKey('channel-jump-to-latest-surface'),
+            decoration: BoxDecoration(
+              color: context.colors.surface.withValues(alpha: 0.5),
+              borderRadius: borderRadius,
+              border: Border.all(
+                color: Colors.black.withValues(alpha: 0.04),
+                width: 1,
+              ),
+            ),
+            child: Material(
+              type: MaterialType.transparency,
+              child: InkWell(
+                onTap: onPressed,
+                borderRadius: borderRadius,
+                child: Padding(
+                  padding: const EdgeInsets.symmetric(
+                    horizontal: Grid.gutter,
+                    vertical: Grid.xxs,
+                  ),
+                  child: Row(
+                    mainAxisSize: MainAxisSize.min,
+                    children: [
+                      Icon(
+                        LucideIcons.arrowDown,
+                        size: 16,
+                        color: context.colors.onSurface,
+                      ),
+                      const SizedBox(width: Grid.half),
+                      Text(
+                        'Latest',
+                        style: context.textTheme.labelLarge?.copyWith(
+                          color: context.colors.onSurface,
+                        ),
+                      ),
+                    ],
+                  ),
+                ),
+              ),
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/channel_detail_page/system_rows.dart b/mobile/lib/features/channels/channel_detail_page/system_rows.dart
index 0372690e1e..e22a31684e 100644
--- a/mobile/lib/features/channels/channel_detail_page/system_rows.dart
+++ b/mobile/lib/features/channels/channel_detail_page/system_rows.dart
@@ -27,12 +27,18 @@ class _SystemMessageRow extends ConsumerWidget {
     final userCache = ref.watch(userCacheProvider);
     final sourceMessages = groupedMessages ?? [message];
     final groupedMembership = _membershipDisplayEvent(sourceMessages);
-    final channelCreator = systemEvent.type == SystemEventType.channelCreated
-        ? systemEvent.actorPubkey?.trim()
-        : null;
+    final messageStyleAction = switch (systemEvent.type) {
+      SystemEventType.channelCreated => 'created this channel',
+      SystemEventType.huddleStarted => 'started a huddle',
+      SystemEventType.huddleEnded => 'ended the huddle',
+      _ => null,
+    };
+    final messageStyleActor = messageStyleAction == null
+        ? null
+        : systemEvent.actorPubkey?.trim();
     final usesMessageStyleLayout =
         groupedMembership != null ||
-        (channelCreator != null && channelCreator.isNotEmpty);
+        (messageStyleActor != null && messageStyleActor.isNotEmpty);
 
     String resolveLabel(String? pubkey) {
       if (pubkey == null) return 'Someone';
@@ -102,13 +108,15 @@ class _SystemMessageRow extends ConsumerWidget {
                   resolveLabel: resolveLabel,
                   userCache: userCache,
                 )
-              else if (channelCreator != null && channelCreator.isNotEmpty)
+              else if (messageStyleActor != null &&
+                  messageStyleActor.isNotEmpty &&
+                  messageStyleAction != null)
                 _MessageStyleSystemMessageContent(
-                  displayPubkey: channelCreator,
+                  displayPubkey: messageStyleActor,
                   createdAt: message.createdAt,
                   resolveLabel: resolveLabel,
                   userCache: userCache,
-                  actionSpans: const [TextSpan(text: 'created this channel')],
+                  actionSpans: [TextSpan(text: messageStyleAction)],
                 )
               else
                 Row(
diff --git a/mobile/lib/features/channels/channel_typing_indicator.dart b/mobile/lib/features/channels/channel_typing_indicator.dart
index d021b9e287..0543f13b06 100644
--- a/mobile/lib/features/channels/channel_typing_indicator.dart
+++ b/mobile/lib/features/channels/channel_typing_indicator.dart
@@ -1,4 +1,5 @@
 import 'package:flutter/material.dart';
+import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
 
 import '../../shared/theme/theme.dart';
@@ -72,13 +73,11 @@ class ChannelTypingIndicator extends ConsumerWidget {
             ),
             const SizedBox(width: Grid.xxs),
             Flexible(
-              child: Text(
+              child: _TypingTextShimmer(
                 text,
                 style: context.textTheme.labelSmall?.copyWith(
-                  color: context.colors.primary,
-                  fontStyle: FontStyle.italic,
+                  color: context.colors.onSurfaceVariant,
                 ),
-                overflow: TextOverflow.ellipsis,
               ),
             ),
           ],
@@ -87,3 +86,62 @@ class ChannelTypingIndicator extends ConsumerWidget {
     );
   }
 }
+
+class _TypingTextShimmer extends HookWidget {
+  final String text;
+  final TextStyle? style;
+
+  const _TypingTextShimmer(this.text, {this.style});
+
+  @override
+  Widget build(BuildContext context) {
+    final animation = useAnimationController(
+      duration: const Duration(milliseconds: 2600),
+    );
+    final reducedMotion = MediaQuery.disableAnimationsOf(context);
+    final baseColor = style?.color ?? context.colors.onSurfaceVariant;
+    final highlightColor =
+        Color.lerp(context.colors.surface, baseColor, 0.4) ?? baseColor;
+
+    useEffect(() {
+      if (reducedMotion) {
+        animation
+          ..stop()
+          ..value = 0;
+      } else {
+        animation.repeat();
+      }
+      return animation.stop;
+    }, [animation, reducedMotion]);
+
+    final label = Text(text, style: style, overflow: TextOverflow.ellipsis);
+    if (reducedMotion) return label;
+
+    return RepaintBoundary(
+      child: AnimatedBuilder(
+        animation: animation,
+        child: label,
+        builder: (context, child) {
+          final center = 1.5 - (animation.value * 3);
+          return ShaderMask(
+            key: const ValueKey('channel-typing-shimmer'),
+            blendMode: BlendMode.srcIn,
+            shaderCallback: (bounds) => LinearGradient(
+              begin: Alignment(center - 1, 0),
+              end: Alignment(center + 1, 0),
+              colors: [
+                baseColor,
+                baseColor,
+                highlightColor,
+                baseColor,
+                baseColor,
+              ],
+              stops: const [0, 0.34, 0.5, 0.66, 1],
+            ).createShader(bounds),
+            child: child,
+          );
+        },
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/channels_page/sections.dart b/mobile/lib/features/channels/channels_page/sections.dart
index f9fe5453d7..febe16e996 100644
--- a/mobile/lib/features/channels/channels_page/sections.dart
+++ b/mobile/lib/features/channels/channels_page/sections.dart
@@ -1,5 +1,7 @@
 part of '../channels_page.dart';
 
+const _sectionMenuItemPadding = EdgeInsets.fromLTRB(Grid.xs, 0, Grid.twelve, 0);
+
 class _CustomChannelSection extends StatelessWidget {
   final ChannelSection section;
   final List<Channel> channels;
@@ -178,32 +180,42 @@ class _CustomSectionHeader extends ConsumerWidget {
                     context: buttonContext,
                     width: 216,
                     alignment: AnchoredPopoverAlignment.end,
-                    color: context.colors.surface,
-                    elevation: 4,
-                    shadowColor: context.colors.shadow.withValues(alpha: 0.18),
-                    shape: RoundedRectangleBorder(
-                      borderRadius: BorderRadius.circular(Radii.md),
-                      side: BorderSide(color: context.colors.outline),
-                    ),
                     surfaceKey: ValueKey('section-popover-${section.id}'),
                     items: [
                       const PopupMenuItem(
                         value: 'rename',
-                        child: Text('Rename'),
+                        padding: _sectionMenuItemPadding,
+                        child: _SectionMenuItemContent(
+                          icon: LucideIcons.pencil,
+                          label: 'Rename section',
+                        ),
                       ),
                       PopupMenuItem(
                         value: 'move_up',
                         enabled: !isFirst,
-                        child: const Text('Move Up'),
+                        padding: _sectionMenuItemPadding,
+                        child: const _SectionMenuItemContent(
+                          icon: LucideIcons.arrowUp,
+                          label: 'Move up',
+                        ),
                       ),
                       PopupMenuItem(
                         value: 'move_down',
                         enabled: !isLast,
-                        child: const Text('Move Down'),
+                        padding: _sectionMenuItemPadding,
+                        child: const _SectionMenuItemContent(
+                          icon: LucideIcons.arrowDown,
+                          label: 'Move down',
+                        ),
                       ),
-                      const PopupMenuItem(
+                      PopupMenuItem(
                         value: 'delete',
-                        child: Text('Delete'),
+                        padding: _sectionMenuItemPadding,
+                        child: _SectionMenuItemContent(
+                          icon: LucideIcons.trash2,
+                          label: 'Delete section',
+                          color: context.colors.error,
+                        ),
                       ),
                     ],
                   );
@@ -229,6 +241,36 @@ class _CustomSectionHeader extends ConsumerWidget {
   }
 }
 
+class _SectionMenuItemContent extends StatelessWidget {
+  final IconData icon;
+  final String label;
+  final Color? color;
+
+  const _SectionMenuItemContent({
+    required this.icon,
+    required this.label,
+    this.color,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return Row(
+      children: [
+        Icon(icon, size: 16, color: color),
+        const SizedBox(width: Grid.xxs),
+        Flexible(
+          child: Text(
+            label,
+            maxLines: 1,
+            overflow: TextOverflow.ellipsis,
+            style: color == null ? null : TextStyle(color: color),
+          ),
+        ),
+      ],
+    );
+  }
+}
+
 CustomEmoji? _resolveCustomEmoji(String icon, List<CustomEmoji> palette) {
   if (!icon.startsWith(':') || !icon.endsWith(':')) return null;
   final shortcode = normalizeShortcode(icon);
diff --git a/mobile/lib/features/channels/channels_provider.dart b/mobile/lib/features/channels/channels_provider.dart
index 614ab054c3..c0525a0b29 100644
--- a/mobile/lib/features/channels/channels_provider.dart
+++ b/mobile/lib/features/channels/channels_provider.dart
@@ -35,8 +35,12 @@ const _authoredRootIdsPrefix = 'buzz-thread-authored.v1';
 class ChannelsNotifier extends AsyncNotifier<List<Channel>> {
   static const _backstopInterval = Duration(seconds: 60);
 
-  final List<void Function()> _unsubscribers = [];
+  final Map<String, void Function()> _unsubscribersByChannel = {};
+  Future<void> _liveSubscriptionQueue = Future.value();
+  List<Channel> _desiredLiveChannels = const [];
+  Set<String> _desiredLiveChannelIds = const {};
   int _subscriptionVersion = 0;
+  String? _subscriptionRelayBaseUrl;
   Timer? _backstopTimer;
   final Map<String, int> _latestObservedByChannel = {};
   final Map<String, Map<String, ObservedUnreadEvent>>
@@ -147,7 +151,10 @@ class ChannelsNotifier extends AsyncNotifier<List<Channel>> {
         .whereType<String>()
         .toSet()
         .toList();
-    if (channelIds.isEmpty) return const [];
+    if (channelIds.isEmpty) {
+      if (subscribeLive) await _subscribeLive(const []);
+      return const [];
+    }
 
     // Step 2: pull channel metadata in one batched filter.
     final metas = await session.fetchHistory(
@@ -423,50 +430,114 @@ class ChannelsNotifier extends AsyncNotifier<List<Channel>> {
   /// Subscribe per-channel to live events (requires `#h` tag for relay
   /// channel-scoped fan-out). Also starts a 60s WS backstop poll to detect
   /// newly created channels we don't yet have subscriptions for.
-  Future<void> _subscribeLive(List<Channel> channels) async {
-    _clearLiveSubscriptions();
-    final subscriptionVersion = _subscriptionVersion;
-    if (ref.read(relaySessionProvider).status != SessionStatus.connected) {
-      return;
-    }
-
-    final session = ref.read(relaySessionProvider.notifier);
+  Future<void> _subscribeLive(List<Channel> channels) {
     final channelIds = {
       for (final channel in channels)
         if (channel.isMember && !channel.isArchived) channel.id,
     };
+    final relayBaseUrl = ref.read(relayConfigProvider).baseUrl;
+    _desiredLiveChannels = channels;
+    _desiredLiveChannelIds = channelIds;
+    final subscriptionVersion = ++_subscriptionVersion;
 
-    final subscriptions = await Future.wait(
-      channelIds.map((channelId) async {
-        try {
-          return await session.subscribe(
-            NostrFilter(
-              kinds: EventKind.channelEventKinds,
-              tags: {
-                '#h': [channelId],
-              },
-              limit: 0,
-            ),
-            _handleLiveEvent,
-          );
-        } catch (error) {
-          debugPrint(
-            '[ChannelsNotifier] live subscription failed for $channelId: $error',
-          );
-          return null;
-        }
-      }),
+    final sync = _liveSubscriptionQueue.then(
+      (_) =>
+          _syncLiveSubscriptions(relayBaseUrl, subscriptionVersion, channels),
     );
+    _liveSubscriptionQueue = sync.catchError((Object error, StackTrace stack) {
+      debugPrint(
+        '[ChannelsNotifier] live subscription sync failed: $error\n$stack',
+      );
+    });
+    return sync;
+  }
 
-    if (subscriptionVersion != _subscriptionVersion ||
-        ref.read(relaySessionProvider).status != SessionStatus.connected) {
-      for (final unsubscribe in subscriptions.whereType<void Function()>()) {
-        unsubscribe();
-      }
+  Future<void> _syncLiveSubscriptions(
+    String relayBaseUrl,
+    int subscriptionVersion,
+    List<Channel> channels,
+  ) async {
+    if (ref.read(relaySessionProvider).status != SessionStatus.connected) {
       return;
     }
 
-    _unsubscribers.addAll(subscriptions.whereType<void Function()>());
+    if (subscriptionVersion != _subscriptionVersion) {
+      await _syncLiveSubscriptions(
+        ref.read(relayConfigProvider).baseUrl,
+        _subscriptionVersion,
+        _desiredLiveChannels,
+      );
+      return;
+    }
+
+    if (_subscriptionRelayBaseUrl != relayBaseUrl) {
+      for (final unsubscribe in _unsubscribersByChannel.values) {
+        unsubscribe();
+      }
+      _unsubscribersByChannel.clear();
+      _subscriptionRelayBaseUrl = relayBaseUrl;
+    }
+    if (ref.read(relayConfigProvider).baseUrl != relayBaseUrl) {
+      return;
+    }
+    final session = ref.read(relaySessionProvider.notifier);
+    final channelIds = _desiredLiveChannelIds;
+
+    for (final entry in _unsubscribersByChannel.entries.toList()) {
+      if (channelIds.contains(entry.key)) continue;
+      _unsubscribersByChannel.remove(entry.key);
+      entry.value();
+    }
+
+    for (final channelId in channelIds) {
+      if (ref.read(relaySessionProvider).status != SessionStatus.connected) {
+        return;
+      }
+      if (_unsubscribersByChannel.containsKey(channelId)) continue;
+      try {
+        final unsubscribe = await session.subscribe(
+          NostrFilter(
+            kinds: EventKind.channelEventKinds,
+            tags: {
+              '#h': [channelId],
+            },
+            limit: 0,
+          ),
+          _handleLiveEvent,
+        );
+        if (ref.read(relaySessionProvider).status != SessionStatus.connected ||
+            !_desiredLiveChannelIds.contains(channelId) ||
+            ref.read(relayConfigProvider).baseUrl != relayBaseUrl ||
+            _subscriptionRelayBaseUrl != relayBaseUrl) {
+          unsubscribe();
+          return;
+        }
+        final replaced = _unsubscribersByChannel[channelId];
+        if (replaced != null) {
+          unsubscribe();
+          continue;
+        }
+        _unsubscribersByChannel[channelId] = unsubscribe;
+      } catch (error) {
+        debugPrint(
+          '[ChannelsNotifier] live subscription failed for $channelId: $error',
+        );
+      }
+    }
+
+    if (ref.read(relaySessionProvider).status != SessionStatus.connected) {
+      return;
+    }
+
+    if (subscriptionVersion != _subscriptionVersion) {
+      final desiredChannelIds = _desiredLiveChannelIds;
+      for (final entry in _unsubscribersByChannel.entries.toList()) {
+        if (desiredChannelIds.contains(entry.key)) continue;
+        _unsubscribersByChannel.remove(entry.key);
+        entry.value();
+      }
+      return;
+    }
 
     unawaited(_catchUpUnreadEvents(channels));
 
@@ -734,10 +805,13 @@ class ChannelsNotifier extends AsyncNotifier<List<Channel>> {
 
   void _clearLiveSubscriptions() {
     _subscriptionVersion++;
-    for (final unsubscribe in _unsubscribers) {
+    _desiredLiveChannels = const [];
+    _desiredLiveChannelIds = const {};
+    for (final unsubscribe in _unsubscribersByChannel.values) {
       unsubscribe();
     }
-    _unsubscribers.clear();
+    _unsubscribersByChannel.clear();
+    _subscriptionRelayBaseUrl = null;
     _backstopTimer?.cancel();
     _backstopTimer = null;
   }
diff --git a/mobile/lib/features/channels/compose_bar.dart b/mobile/lib/features/channels/compose_bar.dart
index 7560f998f3..fe0d5cf5d4 100644
--- a/mobile/lib/features/channels/compose_bar.dart
+++ b/mobile/lib/features/channels/compose_bar.dart
@@ -1,6 +1,7 @@
 import 'dart:async';
 import 'dart:collection';
 import 'dart:math' as math;
+import 'dart:ui' show FlutterView;
 
 import 'package:camera/camera.dart' as camera;
 import 'package:flutter/foundation.dart';
@@ -19,8 +20,10 @@ import '../../shared/mentions/agent_identity_provider.dart';
 import '../../shared/relay/relay.dart';
 import '../../shared/theme/theme.dart';
 import '../../shared/widgets/avatar_image.dart';
+import '../../shared/widgets/anchored_popover_menu.dart';
 import '../../shared/widgets/buzz_loading_indicator.dart';
 import '../../shared/widgets/keyboard_dismiss_on_drag.dart';
+import '../../shared/widgets/mobile_tab_footer_backdrop.dart';
 import '../profile/user_cache_provider.dart';
 import '../profile/user_profile.dart';
 import '../../shared/custom_emoji/custom_emoji.dart';
@@ -48,6 +51,7 @@ part 'compose_bar/ios_attachment_popover.dart';
 part 'compose_bar/camera_preview.dart';
 part 'compose_bar/send_button.dart';
 part 'compose_bar/layout.dart';
+part 'compose_bar/dock.dart';
 
 const _maxConcurrentImageUploads = 3;
 
@@ -84,6 +88,7 @@ class ComposeBar extends HookConsumerWidget {
   @override
   Widget build(BuildContext context, WidgetRef ref) {
     final controller = useMemoized(_MarkdownEditingController.new);
+    useListenable(controller);
     useEffect(() => controller.dispose, [controller]);
 
     // Restore and persist unsent text as a local draft so the Activity
@@ -126,7 +131,13 @@ class ComposeBar extends HookConsumerWidget {
       return () => controller.removeListener(persistDraft);
     }, [controller, draftKey, draftIdentity]);
     final focusNode = useFocusNode();
+    useEffect(
+      () =>
+          () => _dismissComposerKeyboard(focusNode),
+      [focusNode],
+    );
     final isComposerExpanded = useState(false);
+    final isEmojiPickerOpen = useState(false);
     final attachmentSurface = useState(_AttachmentSurface.closed);
     final iosAttachmentPopover = useMemoized(
       _IOSAttachmentPopoverController.new,
@@ -144,6 +155,7 @@ class ComposeBar extends HookConsumerWidget {
     final clipboardHasImage = useState(false);
     final hasAttachments = attachments.value.isNotEmpty;
     final hasPendingUploads = uploadingCount.value > 0;
+    final canSend = controller.text.trim().isNotEmpty || hasAttachments;
     final customEmoji = ref.watch(customEmojiListProvider);
     final reducedMotion = MediaQuery.disableAnimationsOf(context);
     final composerExpansionController = useAnimationController(
@@ -155,6 +167,42 @@ class ComposeBar extends HookConsumerWidget {
         .clamp(0.0, 1.0)
         .toDouble();
 
+    void collapseComposer() {
+      if (!isComposerExpanded.value) return;
+      showFormatting.value = false;
+      isComposerExpanded.value = false;
+    }
+
+    // A focus loss covers deliberate dismiss gestures. The metrics observer
+    // also catches the system back/swipe dismissal path, where the platform can
+    // hide the keyboard while Flutter keeps the TextField focused.
+    useEffect(() {
+      void collapseWhenUnfocused() {
+        if (!focusNode.hasFocus && !isEmojiPickerOpen.value) {
+          collapseComposer();
+        }
+      }
+
+      focusNode.addListener(collapseWhenUnfocused);
+      return () => focusNode.removeListener(collapseWhenUnfocused);
+    }, [focusNode]);
+
+    final appView = View.of(context);
+    useEffect(() {
+      final observer = _ComposerKeyboardMetricsObserver(
+        view: appView,
+        onKeyboardHidden: () {
+          collapseComposer();
+          // Android Back and iOS dismissal gestures can hide the keyboard
+          // without changing Flutter focus. Clear it as well so reopening the
+          // compact capsule establishes a new text-input connection.
+          focusNode.unfocus();
+        },
+      );
+      WidgetsBinding.instance.addObserver(observer);
+      return () => WidgetsBinding.instance.removeObserver(observer);
+    }, [appView, focusNode]);
+
     final resolvedHint =
         hintText ??
         (channelName.isNotEmpty ? 'Message #$channelName' : 'Message\u2026');
@@ -167,8 +215,8 @@ class ComposeBar extends HookConsumerWidget {
         composerExpansionController.animateWith(
           SpringSimulation(
             SpringDescription.withDurationAndBounce(
-              duration: const Duration(milliseconds: 280),
-              bounce: 0.16,
+              duration: const Duration(milliseconds: 220),
+              bounce: 0.08,
             ),
             composerExpansionController.value,
             target,
@@ -887,64 +935,16 @@ class ComposeBar extends HookConsumerWidget {
 
     // Suggestions and attachments live in the overlay so showing them cannot
     // reflow the composer. Both stay anchored just above the capsule.
-    return Padding(
-      padding: EdgeInsets.only(
-        left: Grid.twelve,
-        right: Grid.twelve,
-        bottom: MediaQuery.viewPaddingOf(context).bottom + Grid.xxs,
-      ),
-      child: OverlayPortal.overlayChildLayoutBuilder(
+    final composerWidthFactor = 0.85 + 0.15 * composerExpansionProgress;
+    return _ComposerDockFrame(
+      widthFactor: composerWidthFactor,
+      child: _ComposerOverlayPortal(
         controller: suggestionOverlayController,
-        overlayChildBuilder: (context, layoutInfo) {
-          final composerOrigin = MatrixUtils.transformPoint(
-            layoutInfo.childPaintTransform,
-            Offset.zero,
-          );
-          return ValueListenableBuilder<_AttachmentSurface>(
-            valueListenable: attachmentSurface,
-            builder: (context, surface, _) {
-              final surfaceDuration = reducedMotion
-                  ? Duration.zero
-                  : Duration(
-                      milliseconds:
-                          surface == _AttachmentSurface.camera ||
-                              surface == _AttachmentSurface.photos
-                          ? 320
-                          : 250,
-                    );
-              final expandedSurfaceCoversComposer =
-                  surface == _AttachmentSurface.camera ||
-                  surface == _AttachmentSurface.photos;
-              final overlayAnchorY =
-                  composerOrigin.dy +
-                  (expandedSurfaceCoversComposer
-                      ? layoutInfo.childSize.height + Grid.twelve
-                      : 0);
-              return AnimatedPositioned(
-                duration: surfaceDuration,
-                curve:
-                    surface == _AttachmentSurface.camera ||
-                        surface == _AttachmentSurface.photos
-                    ? const Cubic(0.34, 1.25, 0.64, 1)
-                    : const Cubic(0.22, 1, 0.36, 1),
-                left: composerOrigin.dx,
-                bottom: layoutInfo.overlaySize.height - overlayAnchorY,
-                width: layoutInfo.childSize.width,
-                child: ClipRect(
-                  child: Padding(
-                    padding: const EdgeInsets.only(bottom: Grid.xxs),
-                    child: surface == _AttachmentSurface.closed
-                        ? _SuggestionPanelMotion(
-                            duration: surfaceDuration,
-                            alignment: Alignment.bottomLeft,
-                            child: buildOverlayPanel(surface),
-                          )
-                        : buildOverlayPanel(surface),
-                  ),
-                ),
-              );
-            },
-          );
+        attachmentSurface: attachmentSurface,
+        reducedMotion: reducedMotion,
+        buildOverlayPanel: buildOverlayPanel,
+        onDismissAttachmentSurface: () {
+          attachmentSurface.value = _AttachmentSurface.closed;
         },
         child: _ComposeBarLayout(
           attachments: attachments.value,
@@ -977,12 +977,18 @@ class ComposeBar extends HookConsumerWidget {
           },
           onEmoji: () {
             attachmentSurface.value = _AttachmentSurface.closed;
-            showEmojiPicker(context: context, onSelect: insertEmoji);
+            isEmojiPickerOpen.value = true;
+            _showComposerEmojiPicker(context, insertEmoji, () {
+              if (!context.mounted) return;
+              isEmojiPickerOpen.value = false;
+              focusNode.requestFocus();
+            });
           },
           onOpenFormatting: () {
             attachmentSurface.value = _AttachmentSurface.closed;
             showFormatting.value = true;
           },
+          canSend: canSend,
           hasPendingUploads: hasPendingUploads,
           isSending: isSending.value,
         ),
diff --git a/mobile/lib/features/channels/compose_bar/attachments.dart b/mobile/lib/features/channels/compose_bar/attachments.dart
index 7c53ae1098..eee4d222ac 100644
--- a/mobile/lib/features/channels/compose_bar/attachments.dart
+++ b/mobile/lib/features/channels/compose_bar/attachments.dart
@@ -177,7 +177,7 @@ class _AttachmentSurfacePanel extends HookWidget {
         final height =
             menuLayout.height +
             ((expandedHeight - menuLayout.height) * sizeProgress);
-        final baseColor = context.colors.surfaceContainerHighest;
+        final baseColor = appPopoverColor(context);
         final expandedColor =
             visibleExpandedSurface == _AttachmentSurface.camera
             ? Colors.black
@@ -189,57 +189,51 @@ class _AttachmentSurfacePanel extends HookWidget {
           child: SizedBox(
             width: width,
             height: height,
-            child: DecoratedBox(
-              decoration: BoxDecoration(
-                color: Color.lerp(baseColor, expandedColor, sizeProgress),
-                borderRadius: BorderRadius.circular(Radii.dialog),
-                border: Border.all(
-                  color: Colors.black.withValues(alpha: 0.04),
-                  width: 1,
-                ),
-              ),
-              child: ClipRRect(
-                borderRadius: BorderRadius.circular(Radii.dialog),
-                child: Material(
-                  type: MaterialType.transparency,
-                  child: Stack(
-                    clipBehavior: Clip.hardEdge,
-                    children: [
-                      Positioned(
-                        left: 0,
-                        top: 0,
-                        width: _attachmentMenuWidth,
-                        height: menuLayout.height,
-                        child: IgnorePointer(
-                          ignoring: surface != _AttachmentSurface.menu,
-                          child: Opacity(
-                            opacity: menuOpacity,
-                            child: _AttachmentMenu(
-                              layout: menuLayout,
-                              onCamera: onCamera,
-                              onPhotos: onPhotos,
-                              onVideo: onVideo,
-                              onFiles: onFiles,
-                            ),
-                          ),
+            child: Material(
+              key: const ValueKey('attachment-surface-popover'),
+              type: MaterialType.card,
+              color: Color.lerp(baseColor, expandedColor, sizeProgress),
+              surfaceTintColor: Colors.transparent,
+              elevation: appPopoverElevation,
+              shadowColor: appPopoverShadowColor(context),
+              shape: appPopoverShape(context),
+              clipBehavior: Clip.antiAlias,
+              child: Stack(
+                clipBehavior: Clip.hardEdge,
+                children: [
+                  Positioned(
+                    left: 0,
+                    top: 0,
+                    width: _attachmentMenuWidth,
+                    height: menuLayout.height,
+                    child: IgnorePointer(
+                      ignoring: surface != _AttachmentSurface.menu,
+                      child: Opacity(
+                        opacity: menuOpacity,
+                        child: _AttachmentMenu(
+                          layout: menuLayout,
+                          onCamera: onCamera,
+                          onPhotos: onPhotos,
+                          onVideo: onVideo,
+                          onFiles: onFiles,
                         ),
                       ),
-                      Positioned(
-                        left: 0,
-                        top: 0,
-                        width: expandedWidth,
-                        height: expandedHeight,
-                        child: IgnorePointer(
-                          ignoring: !isExpanded,
-                          child: Opacity(
-                            opacity: expandedOpacity,
-                            child: expandedContent,
-                          ),
-                        ),
-                      ),
-                    ],
+                    ),
                   ),
-                ),
+                  Positioned(
+                    left: 0,
+                    top: 0,
+                    width: expandedWidth,
+                    height: expandedHeight,
+                    child: IgnorePointer(
+                      ignoring: !isExpanded,
+                      child: Opacity(
+                        opacity: expandedOpacity,
+                        child: expandedContent,
+                      ),
+                    ),
+                  ),
+                ],
               ),
             ),
           ),
@@ -308,7 +302,7 @@ class _AttachmentTrigger extends StatelessWidget {
             _AttachmentSurface.camera ||
             _AttachmentSurface.photos => 'Back to attachment options',
           },
-          onPressed: () => onTap(context),
+          onPressed: () => _runComposerAction(() => onTap(context)),
           padding: EdgeInsets.zero,
           visualDensity: VisualDensity.compact,
           icon: AnimatedRotation(
@@ -417,7 +411,7 @@ class _AttachmentMenuItem extends StatelessWidget {
       child: Tooltip(
         message: label,
         child: InkWell(
-          onTap: onTap,
+          onTap: () => _runComposerAction(onTap),
           child: Padding(
             padding: const EdgeInsets.symmetric(horizontal: Grid.xxs),
             child: Row(
@@ -617,7 +611,8 @@ class _AttachmentStrip extends StatelessWidget {
                     width: 24,
                     height: 24,
                     child: IconButton(
-                      onPressed: () => onRemove(attachment.url),
+                      onPressed: () =>
+                          _runComposerAction(() => onRemove(attachment.url)),
                       tooltip: 'Remove attachment',
                       visualDensity: VisualDensity.compact,
                       style: IconButton.styleFrom(
diff --git a/mobile/lib/features/channels/compose_bar/camera_preview.dart b/mobile/lib/features/channels/compose_bar/camera_preview.dart
index e51c2d16aa..1a06534d6e 100644
--- a/mobile/lib/features/channels/compose_bar/camera_preview.dart
+++ b/mobile/lib/features/channels/compose_bar/camera_preview.dart
@@ -252,7 +252,7 @@ class _CameraCaptureButton extends StatelessWidget {
       button: true,
       label: 'Take photo',
       child: GestureDetector(
-        onTap: isPressed ? null : onTap,
+        onTap: isPressed ? null : () => _runComposerAction(onTap),
         child: AnimatedScale(
           scale: isPressed ? 0.92 : 1,
           duration: duration,
@@ -290,7 +290,7 @@ class _CameraCloseButton extends StatelessWidget {
     return SizedBox.square(
       dimension: emphasized ? _cameraBackSize : 36,
       child: IconButton(
-        onPressed: onTap,
+        onPressed: () => _runComposerAction(onTap),
         tooltip: 'Back to attachment options',
         padding: EdgeInsets.zero,
         style: IconButton.styleFrom(
diff --git a/mobile/lib/features/channels/compose_bar/dock.dart b/mobile/lib/features/channels/compose_bar/dock.dart
new file mode 100644
index 0000000000..f19fe19e46
--- /dev/null
+++ b/mobile/lib/features/channels/compose_bar/dock.dart
@@ -0,0 +1,144 @@
+part of '../compose_bar.dart';
+
+class _ComposerDockFrame extends StatelessWidget {
+  final double widthFactor;
+  final Widget child;
+
+  const _ComposerDockFrame({required this.widthFactor, required this.child});
+
+  @override
+  Widget build(BuildContext context) {
+    final backdropHeight = mobileTabFooterBackdropHeight(context);
+    return Stack(
+      clipBehavior: Clip.none,
+      children: [
+        Positioned(
+          key: const ValueKey('composer-footer-gradient'),
+          left: 0,
+          right: 0,
+          bottom: 0,
+          height: backdropHeight,
+          child: IgnorePointer(
+            child: MobileTabFooterBackdrop(height: backdropHeight),
+          ),
+        ),
+        Padding(
+          padding: EdgeInsets.only(
+            left: Grid.twelve,
+            right: Grid.twelve,
+            bottom: MediaQuery.viewPaddingOf(context).bottom + Grid.xxs,
+          ),
+          child: Align(
+            alignment: Alignment.bottomCenter,
+            child: FractionallySizedBox(
+              key: const ValueKey('composer-width-transition'),
+              widthFactor: widthFactor,
+              child: child,
+            ),
+          ),
+        ),
+      ],
+    );
+  }
+}
+
+class _ComposerOverlayPortal extends StatelessWidget {
+  final OverlayPortalController controller;
+  final ValueListenable<_AttachmentSurface> attachmentSurface;
+  final bool reducedMotion;
+  final Widget Function(_AttachmentSurface surface) buildOverlayPanel;
+  final VoidCallback onDismissAttachmentSurface;
+  final Widget child;
+
+  const _ComposerOverlayPortal({
+    required this.controller,
+    required this.attachmentSurface,
+    required this.reducedMotion,
+    required this.buildOverlayPanel,
+    required this.onDismissAttachmentSurface,
+    required this.child,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return OverlayPortal.overlayChildLayoutBuilder(
+      controller: controller,
+      overlayChildBuilder: (context, layoutInfo) {
+        final composerOrigin = MatrixUtils.transformPoint(
+          layoutInfo.childPaintTransform,
+          Offset.zero,
+        );
+        return ValueListenableBuilder<_AttachmentSurface>(
+          valueListenable: attachmentSurface,
+          builder: (context, surface, _) {
+            final surfaceDuration = reducedMotion
+                ? Duration.zero
+                : Duration(
+                    milliseconds:
+                        surface == _AttachmentSurface.camera ||
+                            surface == _AttachmentSurface.photos
+                        ? 320
+                        : 250,
+                  );
+            final expandedSurfaceCoversComposer =
+                surface == _AttachmentSurface.camera ||
+                surface == _AttachmentSurface.photos;
+            final surfaceLeft = expandedSurfaceCoversComposer
+                ? Grid.twelve
+                : composerOrigin.dx;
+            final surfaceWidth = expandedSurfaceCoversComposer
+                ? layoutInfo.overlaySize.width - (Grid.twelve * 2)
+                : layoutInfo.childSize.width;
+            final overlayAnchorY =
+                composerOrigin.dy +
+                (expandedSurfaceCoversComposer
+                    ? layoutInfo.childSize.height + Grid.twelve
+                    : 0);
+            return Stack(
+              children: [
+                if (surface != _AttachmentSurface.closed)
+                  Positioned(
+                    left: 0,
+                    top: 0,
+                    right: 0,
+                    height: composerOrigin.dy,
+                    child: ExcludeSemantics(
+                      child: GestureDetector(
+                        key: const ValueKey('attachment-dismiss-barrier'),
+                        behavior: HitTestBehavior.opaque,
+                        onTap: onDismissAttachmentSurface,
+                      ),
+                    ),
+                  ),
+                AnimatedPositioned(
+                  duration: surfaceDuration,
+                  curve:
+                      surface == _AttachmentSurface.camera ||
+                          surface == _AttachmentSurface.photos
+                      ? const Cubic(0.34, 1.25, 0.64, 1)
+                      : const Cubic(0.22, 1, 0.36, 1),
+                  left: surfaceLeft,
+                  bottom: layoutInfo.overlaySize.height - overlayAnchorY,
+                  width: surfaceWidth,
+                  child: ClipRect(
+                    child: Padding(
+                      padding: const EdgeInsets.only(bottom: Grid.xxs),
+                      child: surface == _AttachmentSurface.closed
+                          ? _SuggestionPanelMotion(
+                              duration: surfaceDuration,
+                              alignment: Alignment.bottomLeft,
+                              child: buildOverlayPanel(surface),
+                            )
+                          : buildOverlayPanel(surface),
+                    ),
+                  ),
+                ),
+              ],
+            );
+          },
+        );
+      },
+      child: child,
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/compose_bar/formatting_toolbar.dart b/mobile/lib/features/channels/compose_bar/formatting_toolbar.dart
index c9089a99cb..c6dc65a8fa 100644
--- a/mobile/lib/features/channels/compose_bar/formatting_toolbar.dart
+++ b/mobile/lib/features/channels/compose_bar/formatting_toolbar.dart
@@ -58,7 +58,7 @@ class _FormatButton extends StatelessWidget {
       message: tooltip,
       child: InkWell(
         borderRadius: BorderRadius.circular(Radii.sm),
-        onTap: onTap,
+        onTap: () => _runComposerAction(onTap),
         child: Padding(
           padding: const EdgeInsets.all(Grid.xxs),
           child: Icon(icon, size: 18, color: context.colors.primary),
@@ -80,7 +80,7 @@ class _ComposeAction extends StatelessWidget {
       width: 36,
       height: 36,
       child: IconButton(
-        onPressed: onTap,
+        onPressed: () => _runComposerAction(onTap),
         icon: Icon(icon, size: 20, color: context.colors.onSurfaceVariant),
         padding: EdgeInsets.zero,
         visualDensity: VisualDensity.compact,
diff --git a/mobile/lib/features/channels/compose_bar/helpers.dart b/mobile/lib/features/channels/compose_bar/helpers.dart
index 145d28fb44..c09815538a 100644
--- a/mobile/lib/features/channels/compose_bar/helpers.dart
+++ b/mobile/lib/features/channels/compose_bar/helpers.dart
@@ -1,6 +1,47 @@
 part of '../compose_bar.dart';
 
 const _typingThrottleMs = 3000;
+
+class _ComposerKeyboardMetricsObserver with WidgetsBindingObserver {
+  final FlutterView view;
+  final VoidCallback onKeyboardHidden;
+  bool _wasVisible;
+
+  _ComposerKeyboardMetricsObserver({
+    required this.view,
+    required this.onKeyboardHidden,
+  }) : _wasVisible = view.viewInsets.bottom > 0;
+
+  @override
+  void didChangeMetrics() {
+    final isVisible = view.viewInsets.bottom > 0;
+    if (_wasVisible && !isVisible) onKeyboardHidden();
+    _wasVisible = isVisible;
+  }
+}
+
+void _runComposerAction(VoidCallback action) {
+  unawaited(HapticFeedback.selectionClick());
+  action();
+}
+
+void _showComposerEmojiPicker(
+  BuildContext context,
+  ValueChanged<String> onSelect,
+  VoidCallback onDismiss,
+) {
+  showEmojiPicker(
+    context: context,
+    onSelect: (emoji) => _runComposerAction(() => onSelect(emoji)),
+    onDismiss: onDismiss,
+  );
+}
+
+void _dismissComposerKeyboard(FocusNode focusNode) {
+  focusNode.unfocus();
+  unawaited(SystemChannels.textInput.invokeMethod<void>('TextInput.hide'));
+}
+
 const _pastedImageMimeTypes = <String>[
   'image/jpeg',
   'image/jpg',
diff --git a/mobile/lib/features/channels/compose_bar/ios_photo_picker.dart b/mobile/lib/features/channels/compose_bar/ios_photo_picker.dart
index 039b5160a3..ade2bec94e 100644
--- a/mobile/lib/features/channels/compose_bar/ios_photo_picker.dart
+++ b/mobile/lib/features/channels/compose_bar/ios_photo_picker.dart
@@ -146,7 +146,9 @@ class _IOSInlinePhotoPicker extends HookWidget {
                 ),
                 child: IconButton(
                   key: const ValueKey('ios-inline-photo-picker-back'),
-                  onPressed: isProcessing.value ? null : onBack,
+                  onPressed: isProcessing.value
+                      ? null
+                      : () => _runComposerAction(onBack),
                   tooltip: 'Back to attachment options',
                   icon: const Icon(
                     LucideIcons.chevronLeft,
@@ -164,11 +166,12 @@ class _IOSInlinePhotoPicker extends HookWidget {
               child: FilledButton(
                 key: const ValueKey('ios-inline-photo-picker-select'),
                 onPressed: canSelect
-                    ? submitSelection
+                    ? () =>
+                          _runComposerAction(() => unawaited(submitSelection()))
                     : selectedCount.value == 0 &&
                           !isPreparingSelection.value &&
                           !isProcessing.value
-                    ? openAllPhotos
+                    ? () => _runComposerAction(() => unawaited(openAllPhotos()))
                     : null,
                 style: FilledButton.styleFrom(
                   backgroundColor: Colors.black.withValues(alpha: 0.76),
diff --git a/mobile/lib/features/channels/compose_bar/layout.dart b/mobile/lib/features/channels/compose_bar/layout.dart
index 31b930e36d..e0adb9621c 100644
--- a/mobile/lib/features/channels/compose_bar/layout.dart
+++ b/mobile/lib/features/channels/compose_bar/layout.dart
@@ -25,6 +25,7 @@ class _ComposeBarLayout extends StatelessWidget {
   final VoidCallback onChannel;
   final VoidCallback onEmoji;
   final VoidCallback onOpenFormatting;
+  final bool canSend;
   final bool hasPendingUploads;
   final bool isSending;
 
@@ -53,6 +54,7 @@ class _ComposeBarLayout extends StatelessWidget {
     required this.onChannel,
     required this.onEmoji,
     required this.onOpenFormatting,
+    required this.canSend,
     required this.hasPendingUploads,
     required this.isSending,
   });
@@ -63,10 +65,17 @@ class _ComposeBarLayout extends StatelessWidget {
   }
 
   Widget _buildBar(BuildContext context) {
+    final trimmedDraft = controller.text.trim();
+    final collapsedText = trimmedDraft.isEmpty
+        ? resolvedHint
+        : trimmedDraft.replaceAll(RegExp(r'\s+'), ' ');
+    final composerRadius =
+        Radii.dialog + Grid.quarter * (1 - expansionProgress);
     return Container(
+      key: const ValueKey('composer-surface'),
       decoration: BoxDecoration(
         color: context.colors.surfaceContainerHighest,
-        borderRadius: BorderRadius.circular(Radii.dialog),
+        borderRadius: BorderRadius.circular(composerRadius),
         border: Border.all(
           color: Colors.black.withValues(alpha: 0.04),
           width: 1,
@@ -142,7 +151,7 @@ class _ComposeBarLayout extends StatelessWidget {
                     label: resolvedHint,
                     child: GestureDetector(
                       behavior: HitTestBehavior.opaque,
-                      onTap: onExpand,
+                      onTap: () => _runComposerAction(onExpand),
                       child: Padding(
                         padding: const EdgeInsets.symmetric(
                           vertical: Grid.half,
@@ -150,9 +159,13 @@ class _ComposeBarLayout extends StatelessWidget {
                         child: Align(
                           alignment: Alignment.centerLeft,
                           child: Text(
-                            resolvedHint,
+                            collapsedText,
+                            maxLines: 1,
+                            overflow: TextOverflow.ellipsis,
                             style: context.textTheme.bodyLarge?.copyWith(
-                              color: context.colors.onSurfaceVariant,
+                              color: trimmedDraft.isEmpty
+                                  ? context.colors.onSurfaceVariant
+                                  : context.colors.onSurface,
                             ),
                           ),
                         ),
@@ -160,6 +173,12 @@ class _ComposeBarLayout extends StatelessWidget {
                     ),
                   ),
                 ),
+                const SizedBox(width: Grid.xxs),
+                _SendButton(
+                  isDisabled: !canSend || hasPendingUploads,
+                  isSending: isSending,
+                  onTap: onSend,
+                ),
               ],
             ),
           ClipRect(
@@ -167,7 +186,7 @@ class _ComposeBarLayout extends StatelessWidget {
               alignment: Alignment.topCenter,
               heightFactor: expansionValue,
               child: IgnorePointer(
-                ignoring: expansionValue < 0.98,
+                ignoring: !isExpanded,
                 child: Opacity(
                   opacity: expansionProgress,
                   child: Transform.translate(
@@ -225,7 +244,8 @@ class _ComposeBarLayout extends StatelessWidget {
                                           ),
                                           const Spacer(),
                                           _SendButton(
-                                            isDisabled: hasPendingUploads,
+                                            isDisabled:
+                                                !canSend || hasPendingUploads,
                                             isSending: isSending,
                                             onTap: onSend,
                                           ),
diff --git a/mobile/lib/features/channels/compose_bar/photo_gallery_picker.dart b/mobile/lib/features/channels/compose_bar/photo_gallery_picker.dart
index 8b19b74aa2..5985874065 100644
--- a/mobile/lib/features/channels/compose_bar/photo_gallery_picker.dart
+++ b/mobile/lib/features/channels/compose_bar/photo_gallery_picker.dart
@@ -136,7 +136,7 @@ class _RecentPhotoGalleryPicker extends HookConsumerWidget {
             photo: photo,
             selectionIndex: selectionIndex,
             reducedMotion: reducedMotion,
-            onTap: () => togglePhoto(photo),
+            onTap: () => _runComposerAction(() => togglePhoto(photo)),
           );
         },
       );
@@ -154,7 +154,9 @@ class _RecentPhotoGalleryPicker extends HookConsumerWidget {
               children: [
                 IconButton(
                   key: const ValueKey('photo-gallery-back'),
-                  onPressed: isResolving.value ? null : onBack,
+                  onPressed: isResolving.value
+                      ? null
+                      : () => _runComposerAction(onBack),
                   tooltip: 'Back to attachment options',
                   visualDensity: VisualDensity.compact,
                   icon: const Icon(LucideIcons.arrowLeft, size: 20),
@@ -212,7 +214,11 @@ class _RecentPhotoGalleryPicker extends HookConsumerWidget {
             child: selectedCount == 0
                 ? OutlinedButton.icon(
                     key: const ValueKey('photo-gallery-action'),
-                    onPressed: isResolving.value ? null : choosePhotos,
+                    onPressed: isResolving.value
+                        ? null
+                        : () => _runComposerAction(
+                            () => unawaited(choosePhotos()),
+                          ),
                     icon: isResolving.value
                         ? BuzzLoadingIndicator(
                             size: 22,
@@ -224,7 +230,11 @@ class _RecentPhotoGalleryPicker extends HookConsumerWidget {
                   )
                 : FilledButton.icon(
                     key: const ValueKey('photo-gallery-action'),
-                    onPressed: isResolving.value ? null : choosePhotos,
+                    onPressed: isResolving.value
+                        ? null
+                        : () => _runComposerAction(
+                            () => unawaited(choosePhotos()),
+                          ),
                     icon: isResolving.value
                         ? const BuzzLoadingIndicator(
                             size: 22,
diff --git a/mobile/lib/features/channels/compose_bar/send_button.dart b/mobile/lib/features/channels/compose_bar/send_button.dart
index 54060ae948..bbe9d2aaca 100644
--- a/mobile/lib/features/channels/compose_bar/send_button.dart
+++ b/mobile/lib/features/channels/compose_bar/send_button.dart
@@ -17,7 +17,9 @@ class _SendButton extends StatelessWidget {
       width: 36,
       height: 36,
       child: IconButton(
-        onPressed: (isSending || isDisabled) ? null : onTap,
+        onPressed: (isSending || isDisabled)
+            ? null
+            : () => _runComposerAction(onTap),
         style: IconButton.styleFrom(
           backgroundColor: context.colors.primary,
           disabledBackgroundColor: context.colors.primary.withValues(
diff --git a/mobile/lib/features/channels/compose_bar/suggestions.dart b/mobile/lib/features/channels/compose_bar/suggestions.dart
index ed97284d46..7b8e7c175b 100644
--- a/mobile/lib/features/channels/compose_bar/suggestions.dart
+++ b/mobile/lib/features/channels/compose_bar/suggestions.dart
@@ -111,54 +111,55 @@ class _MentionSuggestions extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    return Container(
-      constraints: const BoxConstraints(maxHeight: 240),
+    return Material(
+      key: const ValueKey('mention-suggestions-popover'),
+      type: MaterialType.card,
+      color: appPopoverColor(context),
+      surfaceTintColor: Colors.transparent,
+      elevation: appPopoverElevation,
+      shadowColor: appPopoverShadowColor(context),
+      shape: appPopoverShape(context),
       clipBehavior: Clip.hardEdge,
-      decoration: BoxDecoration(
-        color: context.colors.surfaceContainerHighest,
-        borderRadius: BorderRadius.circular(Radii.dialog),
-        border: Border.all(
-          color: Colors.black.withValues(alpha: 0.04),
-          width: 1,
-        ),
-      ),
-      child: ListView.separated(
-        shrinkWrap: true,
-        padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
-        itemCount: suggestions.length,
-        separatorBuilder: (_, _) => const SizedBox.shrink(),
-        itemBuilder: (context, index) {
-          final candidate = suggestions[index];
-          final name = candidate.label;
-          final avatarUrl =
-              candidate.avatarUrl ?? userCache[candidate.pubkey]?.avatarUrl;
+      child: ConstrainedBox(
+        constraints: const BoxConstraints(maxHeight: 240),
+        child: ListView.separated(
+          shrinkWrap: true,
+          padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
+          itemCount: suggestions.length,
+          separatorBuilder: (_, _) => const SizedBox.shrink(),
+          itemBuilder: (context, index) {
+            final candidate = suggestions[index];
+            final name = candidate.label;
+            final avatarUrl =
+                candidate.avatarUrl ?? userCache[candidate.pubkey]?.avatarUrl;
 
-          return ListTile(
-            dense: true,
-            visualDensity: VisualDensity.compact,
-            leading: AvatarImage(
-              imageUrl: avatarUrl,
-              radius: 18,
-              backgroundColor: context.colors.primaryContainer,
-              fallback: Text(
-                name[0].toUpperCase(),
-                style: context.textTheme.labelMedium?.copyWith(
-                  color: context.colors.onPrimaryContainer,
-                  fontWeight: FontWeight.w600,
+            return ListTile(
+              dense: true,
+              visualDensity: VisualDensity.compact,
+              leading: AvatarImage(
+                imageUrl: avatarUrl,
+                radius: 18,
+                backgroundColor: context.colors.primaryContainer,
+                fallback: Text(
+                  name[0].toUpperCase(),
+                  style: context.textTheme.labelMedium?.copyWith(
+                    color: context.colors.onPrimaryContainer,
+                    fontWeight: FontWeight.w600,
+                  ),
                 ),
               ),
-            ),
-            title: Text(name, style: context.textTheme.titleSmall),
-            subtitle: _MentionSuggestionInfo.build(
-              context,
-              candidate: candidate,
-              currentPubkey: currentPubkey,
-              isDmChannel: isDmChannel,
-              userCache: userCache,
-            ),
-            onTap: () => onSelect(candidate),
-          );
-        },
+              title: Text(name, style: context.textTheme.titleSmall),
+              subtitle: _MentionSuggestionInfo.build(
+                context,
+                candidate: candidate,
+                currentPubkey: currentPubkey,
+                isDmChannel: isDmChannel,
+                userCache: userCache,
+              ),
+              onTap: () => _runComposerAction(() => onSelect(candidate)),
+            );
+          },
+        ),
       ),
     );
   }
@@ -261,40 +262,41 @@ class _ChannelSuggestions extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    return Container(
-      constraints: const BoxConstraints(maxHeight: 240),
+    return Material(
+      key: const ValueKey('channel-suggestions-popover'),
+      type: MaterialType.card,
+      color: appPopoverColor(context),
+      surfaceTintColor: Colors.transparent,
+      elevation: appPopoverElevation,
+      shadowColor: appPopoverShadowColor(context),
+      shape: appPopoverShape(context),
       clipBehavior: Clip.hardEdge,
-      decoration: BoxDecoration(
-        color: context.colors.surfaceContainerHighest,
-        borderRadius: BorderRadius.circular(Radii.dialog),
-        border: Border.all(
-          color: Colors.black.withValues(alpha: 0.04),
-          width: 1,
-        ),
-      ),
-      child: ListView.separated(
-        shrinkWrap: true,
-        padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
-        itemCount: suggestions.length,
-        separatorBuilder: (_, _) => const SizedBox.shrink(),
-        itemBuilder: (context, index) {
-          final channel = suggestions[index];
-          return ListTile(
-            dense: true,
-            visualDensity: VisualDensity.compact,
-            horizontalTitleGap: 0,
-            leading: SizedBox.square(
-              dimension: 36,
-              child: Icon(
-                LucideIcons.hash,
-                size: 20,
-                color: context.colors.onSurfaceVariant,
+      child: ConstrainedBox(
+        constraints: const BoxConstraints(maxHeight: 240),
+        child: ListView.separated(
+          shrinkWrap: true,
+          padding: const EdgeInsets.symmetric(vertical: Grid.xxs),
+          itemCount: suggestions.length,
+          separatorBuilder: (_, _) => const SizedBox.shrink(),
+          itemBuilder: (context, index) {
+            final channel = suggestions[index];
+            return ListTile(
+              dense: true,
+              visualDensity: VisualDensity.compact,
+              horizontalTitleGap: 0,
+              leading: SizedBox.square(
+                dimension: 36,
+                child: Icon(
+                  LucideIcons.hash,
+                  size: 20,
+                  color: context.colors.onSurfaceVariant,
+                ),
               ),
-            ),
-            title: Text(channel.name, style: context.textTheme.bodyLarge),
-            onTap: () => onSelect(channel),
-          );
-        },
+              title: Text(channel.name, style: context.textTheme.bodyLarge),
+              onTap: () => _runComposerAction(() => onSelect(channel)),
+            );
+          },
+        ),
       ),
     );
   }
diff --git a/mobile/lib/features/channels/composer_dock_size_reporter.dart b/mobile/lib/features/channels/composer_dock_size_reporter.dart
new file mode 100644
index 0000000000..38730729b3
--- /dev/null
+++ b/mobile/lib/features/channels/composer_dock_size_reporter.dart
@@ -0,0 +1,50 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_hooks/flutter_hooks.dart';
+
+/// Reports the laid-out height of a floating composer dock.
+///
+/// Message timelines use that height as scroll padding while still painting
+/// beneath the dock, which lets the dock's fade reveal real timeline content.
+class ComposerDockSizeReporter extends HookWidget {
+  final ValueChanged<double> onHeightChanged;
+  final Widget child;
+
+  const ComposerDockSizeReporter({
+    super.key,
+    required this.onHeightChanged,
+    required this.child,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final sizeKey = useMemoized(GlobalKey.new);
+    final lastHeight = useRef<double?>(null);
+
+    void reportHeight() {
+      WidgetsBinding.instance.addPostFrameCallback((_) {
+        final renderObject = sizeKey.currentContext?.findRenderObject();
+        if (renderObject is! RenderBox || !renderObject.hasSize) return;
+        final height = renderObject.size.height;
+        final previous = lastHeight.value;
+        if (previous != null && (previous - height).abs() < 0.5) return;
+        lastHeight.value = height;
+        onHeightChanged(height);
+      });
+    }
+
+    useEffect(() {
+      reportHeight();
+      return null;
+    }, const []);
+
+    return NotificationListener<SizeChangedLayoutNotification>(
+      onNotification: (_) {
+        reportHeight();
+        return true;
+      },
+      child: SizeChangedLayoutNotifier(
+        child: KeyedSubtree(key: sizeKey, child: child),
+      ),
+    );
+  }
+}
diff --git a/mobile/lib/features/channels/emoji_picker.dart b/mobile/lib/features/channels/emoji_picker.dart
index 10292cfa28..e3cd0f8eab 100644
--- a/mobile/lib/features/channels/emoji_picker.dart
+++ b/mobile/lib/features/channels/emoji_picker.dart
@@ -9,6 +9,7 @@ import '../../shared/custom_emoji/custom_emoji_render.dart';
 import '../../shared/emoji/emoji_data.dart';
 import '../../shared/emoji/emoji_data_provider.dart';
 import '../../shared/emoji/emoji_search.dart';
+import '../../shared/emoji/native_emoji_glyph.dart';
 import '../../shared/theme/theme.dart';
 import 'recent_emoji_provider.dart';
 
@@ -30,6 +31,7 @@ const _sheetHeightFactor = 0.62;
 void showEmojiPicker({
   required BuildContext context,
   required void Function(String emoji) onSelect,
+  VoidCallback? onDismiss,
 }) {
   showModalBottomSheet<void>(
     context: context,
@@ -42,7 +44,7 @@ void showEmojiPicker({
         onSelect(emoji);
       },
     ),
-  );
+  ).whenComplete(onDismiss ?? () {});
 }
 
 class EmojiPickerSheet extends HookConsumerWidget {
diff --git a/mobile/lib/features/channels/emoji_picker/emoji_grid.dart b/mobile/lib/features/channels/emoji_picker/emoji_grid.dart
index 2ebe631edd..354a31e44c 100644
--- a/mobile/lib/features/channels/emoji_picker/emoji_grid.dart
+++ b/mobile/lib/features/channels/emoji_picker/emoji_grid.dart
@@ -99,10 +99,7 @@ class _EmojiTile extends StatelessWidget {
         button: true,
         label: entry.name,
         child: Center(
-          child: Text(
-            entry.native,
-            style: const TextStyle(fontSize: _emojiGlyphSize),
-          ),
+          child: NativeEmojiGlyph(emoji: entry.native, size: _emojiGlyphSize),
         ),
       ),
     );
diff --git a/mobile/lib/features/channels/message_actions.dart b/mobile/lib/features/channels/message_actions.dart
index 519d25898c..df04800022 100644
--- a/mobile/lib/features/channels/message_actions.dart
+++ b/mobile/lib/features/channels/message_actions.dart
@@ -17,6 +17,7 @@ import '../../shared/theme/theme.dart';
 import '../../shared/custom_emoji/custom_emoji.dart';
 import '../../shared/custom_emoji/custom_emoji_provider.dart';
 import '../../shared/custom_emoji/custom_emoji_render.dart';
+import '../../shared/emoji/native_emoji_glyph.dart';
 import '../../shared/widgets/sheet_divider.dart';
 import '../../shared/reminders/remind_me_later_sheet.dart';
 import '../../shared/reminders/reminder_service.dart';
@@ -689,7 +690,7 @@ class _QuickReactionGlyph extends StatelessWidget {
         );
       }
     }
-    return Text(value, style: const TextStyle(fontSize: 24));
+    return NativeEmojiGlyph(emoji: value, size: 24);
   }
 }
 
diff --git a/mobile/lib/features/channels/reaction_row.dart b/mobile/lib/features/channels/reaction_row.dart
index a9511c587d..9d01b5c8e7 100644
--- a/mobile/lib/features/channels/reaction_row.dart
+++ b/mobile/lib/features/channels/reaction_row.dart
@@ -8,6 +8,7 @@ import '../../shared/widgets/avatar_image.dart';
 import '../../shared/custom_emoji/custom_emoji_render.dart';
 import '../../shared/emoji/emoji_burst.dart';
 import '../../shared/emoji/emoji_data_provider.dart';
+import '../../shared/emoji/native_emoji_glyph.dart';
 import '../../shared/emoji/positive_emoji.dart';
 import '../profile/user_cache_provider.dart';
 import '../profile/user_profile.dart';
@@ -303,7 +304,7 @@ class _ReactionEmoji extends StatelessWidget {
   Widget build(BuildContext context) {
     final emojiUrl = reaction.emojiUrl;
     if (emojiUrl == null || emojiUrl.isEmpty) {
-      return Text(reaction.emoji, style: TextStyle(fontSize: size));
+      return NativeEmojiGlyph(emoji: reaction.emoji, size: size);
     }
     final shortcode = reaction.emoji.substring(1, reaction.emoji.length - 1);
     return CustomEmojiImage(shortcode: shortcode, url: emojiUrl, size: size);
diff --git a/mobile/lib/features/channels/thread_detail_page.dart b/mobile/lib/features/channels/thread_detail_page.dart
index 810861aa00..53be4488b2 100644
--- a/mobile/lib/features/channels/thread_detail_page.dart
+++ b/mobile/lib/features/channels/thread_detail_page.dart
@@ -20,6 +20,7 @@ import 'channel_typing_indicator.dart';
 import 'thread_replies_provider.dart';
 import 'channels_provider.dart';
 import 'compose_bar.dart';
+import 'composer_dock_size_reporter.dart';
 import 'date_formatters.dart';
 import 'day_divider.dart';
 import '../profile/user_profile_sheet.dart';
@@ -58,6 +59,7 @@ class ThreadDetailPage extends HookConsumerWidget {
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
+    final composerDockHeight = useState(0.0);
     // Relay thread queries are keyed by the outermost root, even when this
     // page displays a nested branch. Query that root, then select this head's
     // direct children from the returned subtree below.
@@ -113,11 +115,35 @@ class ThreadDetailPage extends HookConsumerWidget {
     final itemScrollController = useMemoized(ItemScrollController.new);
     final itemPositionsListener = useMemoized(ItemPositionsListener.create);
     final didJumpToInitialMessage = useRef(false);
+    final followsThreadTail = useRef(false);
+    final pendingTailAlignment = useRef<double?>(null);
+    final tailRealignmentQueued = useRef(false);
 
     // Item 0 is the thread head; reply `i` lives at `i + 1`.
     const headIndex = 0;
     int indexForReply(int chronologicalIndex) => chronologicalIndex + 1;
 
+    bool threadTailIsVisible() {
+      final lastIndex = replies.isEmpty
+          ? headIndex
+          : indexForReply(replies.length - 1);
+      return itemPositionsListener.itemPositions.value.any(
+        (position) =>
+            position.index == lastIndex && position.itemTrailingEdge <= 1.001,
+      );
+    }
+
+    useEffect(() {
+      void onPositionsChanged() {
+        if (threadTailIsVisible()) followsThreadTail.value = true;
+      }
+
+      itemPositionsListener.itemPositions.addListener(onPositionsChanged);
+      return () => itemPositionsListener.itemPositions.removeListener(
+        onPositionsChanged,
+      );
+    }, [itemPositionsListener, replies.length]);
+
     useEffect(() {
       final messageId = initialMessageId;
       // Wait for the authoritative thread query before consuming the one-shot
@@ -134,6 +160,11 @@ class ThreadDetailPage extends HookConsumerWidget {
       if (targetIndex == null || didJumpToInitialMessage.value) return null;
       WidgetsBinding.instance.addPostFrameCallback((_) {
         if (!context.mounted || !itemScrollController.isAttached) return;
+        // The provisional route snapshot can make the linked reply look like
+        // the tail. This authoritative deep-link jump intentionally leaves
+        // the user at an older item, so it must opt out of follow-tail first.
+        followsThreadTail.value = false;
+        pendingTailAlignment.value = null;
         itemScrollController.jumpTo(index: targetIndex, alignment: 0.35);
         didJumpToInitialMessage.value = true;
       });
@@ -227,6 +258,74 @@ class ThreadDetailPage extends HookConsumerWidget {
     // itself a root message its rootId is null, so fall back to its own id.
     final effectiveRootId = threadHead.rootId ?? threadHead.id;
 
+    void updateComposerDockHeight(double height) {
+      final previousHeight = composerDockHeight.value;
+      final heightDelta = height - previousHeight;
+      if (heightDelta.abs() < 0.5) return;
+
+      final shouldFollowTail = followsThreadTail.value || threadTailIsVisible();
+      if (shouldFollowTail) followsThreadTail.value = true;
+      composerDockHeight.value = height;
+      if (heightDelta <= 0 || !shouldFollowTail) {
+        pendingTailAlignment.value = null;
+        return;
+      }
+      final lastIndex = replies.isEmpty
+          ? headIndex
+          : indexForReply(replies.length - 1);
+      final lastPosition = itemPositionsListener.itemPositions.value
+          .where((position) => position.index == lastIndex)
+          .firstOrNull;
+      if (lastPosition == null) return;
+      final targetAlignment =
+          (pendingTailAlignment.value ?? lastPosition.itemLeadingEdge) -
+          (heightDelta / MediaQuery.sizeOf(context).height);
+      pendingTailAlignment.value = targetAlignment;
+
+      WidgetsBinding.instance.addPostFrameCallback((_) {
+        if (!context.mounted || !itemScrollController.isAttached) return;
+        itemScrollController.jumpTo(
+          index: lastIndex,
+          alignment: targetAlignment,
+        );
+      });
+    }
+
+    // Composer size changes and keyboard metrics changes are independent:
+    // the dock grows first, then the Scaffold's viewport shrinks once the
+    // keyboard appears. Re-align after that latter layout pass too, but only
+    // while the user was already following the thread tail.
+    void realignThreadTailAfterMetricsChange() {
+      final shouldFollowTail = followsThreadTail.value || threadTailIsVisible();
+      if (!shouldFollowTail || tailRealignmentQueued.value) return;
+      followsThreadTail.value = true;
+      tailRealignmentQueued.value = true;
+      WidgetsBinding.instance.addPostFrameCallback((_) {
+        tailRealignmentQueued.value = false;
+        if (!context.mounted ||
+            !itemScrollController.isAttached ||
+            !followsThreadTail.value) {
+          return;
+        }
+        final lastIndex = replies.isEmpty
+            ? headIndex
+            : indexForReply(replies.length - 1);
+        itemScrollController.scrollTo(
+          index: lastIndex,
+          duration: const Duration(milliseconds: 220),
+          curve: Curves.easeOutCubic,
+        );
+      });
+    }
+
+    useEffect(() {
+      final observer = _ThreadTailMetricsObserver(
+        onMetricsChanged: realignThreadTailAfterMetricsChange,
+      );
+      WidgetsBinding.instance.addObserver(observer);
+      return () => WidgetsBinding.instance.removeObserver(observer);
+    }, [itemScrollController, replies.length]);
+
     // Channel names for message content rendering.
     final channelsAsync = ref.watch(channelsProvider);
     final channelNamesMap = <String, String>{};
@@ -241,176 +340,213 @@ class ThreadDetailPage extends HookConsumerWidget {
         title: Text('Thread'),
         titleStyle: channelTitleTextStyle,
       ),
-      body: Column(
+      body: Stack(
+        fit: StackFit.expand,
         children: [
-          Expanded(
-            child: KeyboardDismissOnDrag(
-              child: ScrollablePositionedList.builder(
-                key: const ValueKey('thread-message-list'),
-                itemScrollController: itemScrollController,
-                itemPositionsListener: itemPositionsListener,
-                // Top-anchored, head first, replies flowing down — matching
-                // desktop's thread panel. The old reversed list bottom-anchored
-                // the content, which jammed the head against the composer
-                // whenever a thread had only a handful of replies.
-                padding: EdgeInsets.only(
-                  left: Grid.gutter,
-                  right: Grid.gutter,
-                  top: frostedAppBarHeight(context),
-                  bottom: Grid.xs,
-                ),
-                itemCount: replies.length + 1, // +1 for thread head
-                itemBuilder: (context, index) {
-                  if (index == headIndex) {
-                    if (liveDeletionHidesHead) {
-                      return const Padding(
-                        key: ValueKey('thread-message-deleted'),
-                        padding: EdgeInsets.only(bottom: Grid.xs),
-                        child: Text('This message was deleted'),
-                      );
-                    }
-                    return Padding(
-                      key: ValueKey('thread-message-group-${liveHead.id}'),
-                      padding: const EdgeInsets.only(bottom: Grid.xs),
-                      child: Column(
-                        crossAxisAlignment: CrossAxisAlignment.start,
-                        children: [
-                          DayDivider(
-                            label: formatDayHeading(liveHead.createdAt),
-                          ),
-                          _ThreadMessage(
-                            message: liveHead,
-                            channelNames: channelNamesMap,
-                            channelId: channelId,
-                            currentPubkey: currentPubkey,
-                            showAuthor: true,
-                            isHighlighted: liveHead.id == initialMessageId,
-                            allMessages: allMsgs,
-                            isMember: isMember,
-                            isArchived: isArchived,
-                            isThreadHead: true,
-                          ),
-                          Padding(
-                            padding: const EdgeInsets.symmetric(
-                              vertical: Grid.xxs,
-                            ),
-                            child: Row(
-                              children: [
-                                Text(
-                                  '${replies.length} ${replies.length == 1 ? 'reply' : 'replies'}',
-                                  style: context.textTheme.labelMedium
-                                      ?.copyWith(
-                                        color: context.colors.onSurfaceVariant,
-                                        fontWeight: FontWeight.w600,
-                                      ),
-                                ),
-                                const SizedBox(width: Grid.xxs),
-                                Expanded(
-                                  child: Divider(
-                                    color: context.colors.outlineVariant,
-                                  ),
-                                ),
-                              ],
-                            ),
-                          ),
-                        ],
-                      ),
-                    );
-                  }
-
-                  // Chronological list: index 1 = oldest reply.
-                  final chronIdx = index - 1;
-                  final reply = replies[chronIdx];
-                  final prevReply = chronIdx > 0 ? replies[chronIdx - 1] : null;
-                  final previousMessage = prevReply ?? liveHead;
-                  final showDayDivider = !isSameDay(
-                    previousMessage.createdAt,
-                    reply.createdAt,
-                  );
-                  final showAuthor =
-                      prevReply == null ||
-                      showDayDivider ||
-                      prevReply.pubkey.toLowerCase() !=
-                          reply.pubkey.toLowerCase() ||
-                      (reply.createdAt - prevReply.createdAt) > 300;
-
-                  // Check if this reply itself has children (nested thread).
-                  final nestedChildren = childrenByParent[reply.id];
-                  final nestedSummary =
-                      nestedChildren != null && nestedChildren.isNotEmpty
-                      ? _buildNestedSummary(reply.id, nestedChildren)
-                      : null;
-
-                  return Padding(
-                    key: ValueKey('thread-message-group-${reply.id}'),
-                    // Tail spacing comes from the list's own bottom padding now
-                    // that the list runs top-down; the reversed list used to
-                    // need it here because item 0 sat against the composer.
-                    padding: EdgeInsets.zero,
-                    child: Column(
-                      crossAxisAlignment: CrossAxisAlignment.start,
-                      children: [
-                        if (showDayDivider)
-                          DayDivider(label: formatDayHeading(reply.createdAt)),
-                        _ThreadMessage(
-                          message: reply,
-                          channelNames: channelNamesMap,
-                          channelId: channelId,
-                          currentPubkey: currentPubkey,
-                          showAuthor: showAuthor,
-                          isHighlighted: reply.id == initialMessageId,
-                          allMessages: allMsgs,
-                          isMember: isMember,
-                          isArchived: isArchived,
-                        ),
-                        if (nestedSummary != null)
-                          _NestedThreadSummaryRow(
-                            summary: nestedSummary,
-                            replyMessage: reply,
-                            allMessages: allMsgs,
-                            channelId: channelId,
-                            currentPubkey: currentPubkey,
-                            isMember: isMember,
-                            isArchived: isArchived,
-                          ),
-                      ],
+          Column(
+            children: [
+              Expanded(
+                child: KeyboardDismissOnDrag(
+                  onUserScrollStart: () {
+                    followsThreadTail.value = false;
+                    pendingTailAlignment.value = null;
+                  },
+                  child: ScrollablePositionedList.builder(
+                    key: const ValueKey('thread-message-list'),
+                    itemScrollController: itemScrollController,
+                    itemPositionsListener: itemPositionsListener,
+                    // Top-anchored, head first, replies flowing down — matching
+                    // desktop's thread panel. The old reversed list bottom-anchored
+                    // the content, which jammed the head against the composer
+                    // whenever a thread had only a handful of replies.
+                    padding: EdgeInsets.only(
+                      left: Grid.gutter,
+                      right: Grid.gutter,
+                      top: frostedAppBarHeight(context),
+                      bottom: Grid.xs + composerDockHeight.value,
                     ),
-                  );
-                },
+                    itemCount: replies.length + 1, // +1 for thread head
+                    itemBuilder: (context, index) {
+                      if (index == headIndex) {
+                        if (liveDeletionHidesHead) {
+                          return const Padding(
+                            key: ValueKey('thread-message-deleted'),
+                            padding: EdgeInsets.only(bottom: Grid.xs),
+                            child: Text('This message was deleted'),
+                          );
+                        }
+                        return Padding(
+                          key: ValueKey('thread-message-group-${liveHead.id}'),
+                          padding: const EdgeInsets.only(bottom: Grid.xs),
+                          child: Column(
+                            crossAxisAlignment: CrossAxisAlignment.start,
+                            children: [
+                              DayDivider(
+                                label: formatDayHeading(liveHead.createdAt),
+                              ),
+                              _ThreadMessage(
+                                message: liveHead,
+                                channelNames: channelNamesMap,
+                                channelId: channelId,
+                                currentPubkey: currentPubkey,
+                                showAuthor: true,
+                                isHighlighted: liveHead.id == initialMessageId,
+                                allMessages: allMsgs,
+                                isMember: isMember,
+                                isArchived: isArchived,
+                                isThreadHead: true,
+                              ),
+                              Padding(
+                                padding: const EdgeInsets.symmetric(
+                                  vertical: Grid.xxs,
+                                ),
+                                child: Row(
+                                  children: [
+                                    Text(
+                                      '${replies.length} ${replies.length == 1 ? 'reply' : 'replies'}',
+                                      style: context.textTheme.labelMedium
+                                          ?.copyWith(
+                                            color:
+                                                context.colors.onSurfaceVariant,
+                                            fontWeight: FontWeight.w600,
+                                          ),
+                                    ),
+                                    const SizedBox(width: Grid.xxs),
+                                    Expanded(
+                                      child: Divider(
+                                        color: context.colors.outlineVariant,
+                                      ),
+                                    ),
+                                  ],
+                                ),
+                              ),
+                            ],
+                          ),
+                        );
+                      }
+
+                      // Chronological list: index 1 = oldest reply.
+                      final chronIdx = index - 1;
+                      final reply = replies[chronIdx];
+                      final prevReply = chronIdx > 0
+                          ? replies[chronIdx - 1]
+                          : null;
+                      final previousMessage = prevReply ?? liveHead;
+                      final showDayDivider = !isSameDay(
+                        previousMessage.createdAt,
+                        reply.createdAt,
+                      );
+                      final showAuthor =
+                          prevReply == null ||
+                          showDayDivider ||
+                          prevReply.pubkey.toLowerCase() !=
+                              reply.pubkey.toLowerCase() ||
+                          (reply.createdAt - prevReply.createdAt) > 300;
+
+                      // Check if this reply itself has children (nested thread).
+                      final nestedChildren = childrenByParent[reply.id];
+                      final nestedSummary =
+                          nestedChildren != null && nestedChildren.isNotEmpty
+                          ? _buildNestedSummary(reply.id, nestedChildren)
+                          : null;
+
+                      return Padding(
+                        key: ValueKey('thread-message-group-${reply.id}'),
+                        // Tail spacing comes from the list's own bottom padding now
+                        // that the list runs top-down; the reversed list used to
+                        // need it here because item 0 sat against the composer.
+                        padding: EdgeInsets.zero,
+                        child: Column(
+                          crossAxisAlignment: CrossAxisAlignment.start,
+                          children: [
+                            if (showDayDivider)
+                              DayDivider(
+                                label: formatDayHeading(reply.createdAt),
+                              ),
+                            _ThreadMessage(
+                              message: reply,
+                              channelNames: channelNamesMap,
+                              channelId: channelId,
+                              currentPubkey: currentPubkey,
+                              showAuthor: showAuthor,
+                              isHighlighted: reply.id == initialMessageId,
+                              allMessages: allMsgs,
+                              isMember: isMember,
+                              isArchived: isArchived,
+                            ),
+                            if (nestedSummary != null)
+                              _NestedThreadSummaryRow(
+                                summary: nestedSummary,
+                                replyMessage: reply,
+                                allMessages: allMsgs,
+                                channelId: channelId,
+                                currentPubkey: currentPubkey,
+                                isMember: isMember,
+                                isArchived: isArchived,
+                              ),
+                          ],
+                        ),
+                      );
+                    },
+                  ),
+                ),
               ),
-            ),
-          ),
-          AnimatedSize(
-            duration: MediaQuery.disableAnimationsOf(context)
-                ? Duration.zero
-                : const Duration(milliseconds: 180),
-            curve: Curves.easeOutCubic,
-            alignment: Alignment.bottomCenter,
-            child: threadTyping.isEmpty
-                ? const SizedBox.shrink()
-                : ChannelTypingIndicator(entries: threadTyping),
+              if (!isMember || isArchived)
+                AnimatedSize(
+                  duration: MediaQuery.disableAnimationsOf(context)
+                      ? Duration.zero
+                      : const Duration(milliseconds: 180),
+                  curve: Curves.easeOutCubic,
+                  alignment: Alignment.bottomCenter,
+                  child: threadTyping.isEmpty
+                      ? const SizedBox.shrink()
+                      : ChannelTypingIndicator(entries: threadTyping),
+                ),
+            ],
           ),
           if (isMember && !isArchived)
-            ComposeBar(
-              channelId: channelId,
-              hintText: 'Reply in thread\u2026',
-              threadHeadId: threadHead.id,
-              rootId: effectiveRootId,
-              onSend:
-                  (
-                    content,
-                    mentionPubkeys, {
-                    mediaTags = const <List<String>>[],
-                  }) => ref
-                      .read(sendMessageProvider)
-                      .call(
-                        channelId: channelId,
-                        content: content,
-                        mentionPubkeys: mentionPubkeys,
-                        parentEventId: threadHead.id,
-                        rootEventId: effectiveRootId,
-                        mediaTags: mediaTags,
-                      ),
+            Align(
+              alignment: Alignment.bottomCenter,
+              child: ComposerDockSizeReporter(
+                key: const ValueKey('thread-composer-dock'),
+                onHeightChanged: updateComposerDockHeight,
+                child: Column(
+                  mainAxisSize: MainAxisSize.min,
+                  children: [
+                    AnimatedSize(
+                      duration: MediaQuery.disableAnimationsOf(context)
+                          ? Duration.zero
+                          : const Duration(milliseconds: 180),
+                      curve: Curves.easeOutCubic,
+                      alignment: Alignment.bottomCenter,
+                      child: threadTyping.isEmpty
+                          ? const SizedBox.shrink()
+                          : ChannelTypingIndicator(entries: threadTyping),
+                    ),
+                    ComposeBar(
+                      channelId: channelId,
+                      hintText: 'Reply in thread\u2026',
+                      threadHeadId: threadHead.id,
+                      rootId: effectiveRootId,
+                      onSend:
+                          (
+                            content,
+                            mentionPubkeys, {
+                            mediaTags = const <List<String>>[],
+                          }) => ref
+                              .read(sendMessageProvider)
+                              .call(
+                                channelId: channelId,
+                                content: content,
+                                mentionPubkeys: mentionPubkeys,
+                                parentEventId: threadHead.id,
+                                rootEventId: effectiveRootId,
+                                mediaTags: mediaTags,
+                              ),
+                    ),
+                  ],
+                ),
+              ),
             ),
         ],
       ),
@@ -566,6 +702,15 @@ class _NestedThreadSummaryRow extends ConsumerWidget {
   }
 }
 
+class _ThreadTailMetricsObserver with WidgetsBindingObserver {
+  final VoidCallback onMetricsChanged;
+
+  _ThreadTailMetricsObserver({required this.onMetricsChanged});
+
+  @override
+  void didChangeMetrics() => onMetricsChanged();
+}
+
 class _ThreadMessage extends ConsumerWidget {
   final TimelineMessage message;
   final Map<String, String> channelNames;
diff --git a/mobile/lib/shared/emoji/native_emoji_glyph.dart b/mobile/lib/shared/emoji/native_emoji_glyph.dart
new file mode 100644
index 0000000000..7831c1b32b
--- /dev/null
+++ b/mobile/lib/shared/emoji/native_emoji_glyph.dart
@@ -0,0 +1,22 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+
+/// A standalone system emoji whose visual centre matches its surrounding UI.
+///
+/// Apple's emoji glyphs sit slightly low inside Flutter's text box. Keep the
+/// layout box unchanged and lift only the painted glyph on iOS; Android's
+/// system emoji metrics are already visually centred.
+class NativeEmojiGlyph extends StatelessWidget {
+  final String emoji;
+  final double size;
+
+  const NativeEmojiGlyph({super.key, required this.emoji, required this.size});
+
+  @override
+  Widget build(BuildContext context) {
+    final glyph = Text(emoji, style: TextStyle(fontSize: size));
+    if (defaultTargetPlatform != TargetPlatform.iOS) return glyph;
+
+    return Transform.translate(offset: const Offset(0, -1), child: glyph);
+  }
+}
diff --git a/mobile/lib/shared/relay/relay.dart b/mobile/lib/shared/relay/relay.dart
index bc11325414..dd153fc928 100644
--- a/mobile/lib/shared/relay/relay.dart
+++ b/mobile/lib/shared/relay/relay.dart
@@ -5,8 +5,10 @@ export 'media_image.dart';
 export 'media_upload.dart';
 export 'nostr_filters.dart';
 export 'nostr_models.dart';
+export 'relay_closed_policy.dart';
 export 'relay_client.dart';
 export 'relay_provider.dart';
+export 'relay_rate_limit_gate.dart';
 export 'relay_session.dart';
 export 'relay_socket.dart';
 export 'signed_event_relay.dart';
diff --git a/mobile/lib/shared/relay/relay_closed_policy.dart b/mobile/lib/shared/relay/relay_closed_policy.dart
new file mode 100644
index 0000000000..d39084b189
--- /dev/null
+++ b/mobile/lib/shared/relay/relay_closed_policy.dart
@@ -0,0 +1,39 @@
+/// Recovery policy for a relay `CLOSED` subscription message.
+enum RelayClosedClass {
+  /// A transient failure that may recover when the same REQ is retried.
+  retryable,
+
+  /// Relay back-pressure that must also arm the shared request gate.
+  rateLimited,
+
+  /// An authorization, access, or filter failure that cannot recover unchanged.
+  terminal,
+}
+
+/// Classifies whether a relay `CLOSED` message should be retried.
+RelayClosedClass classifyRelayClosed(String message) {
+  final normalized = message.trim().toLowerCase();
+  if (normalized.startsWith('rate-limited:')) {
+    return RelayClosedClass.rateLimited;
+  }
+  if (normalized.startsWith('restricted:') ||
+      normalized.startsWith('auth-required:') ||
+      normalized.startsWith('blocked:') ||
+      normalized.startsWith('invalid:') ||
+      normalized.startsWith('pow:') ||
+      normalized.startsWith('duplicate:') ||
+      normalized.startsWith('unsupported:') ||
+      normalized.startsWith('error: mixed search') ||
+      normalized.startsWith('error: too many subscriptions')) {
+    return RelayClosedClass.terminal;
+  }
+  return RelayClosedClass.retryable;
+}
+
+final _rateLimitRetryPattern = RegExp(r'retry in (\d+)s', caseSensitive: false);
+
+/// Parses the relay's canonical `retry in Ns` hint, when present.
+int? parseRateLimitRetrySeconds(String message) {
+  final match = _rateLimitRetryPattern.firstMatch(message);
+  return match == null ? null : int.tryParse(match.group(1)!);
+}
diff --git a/mobile/lib/shared/relay/relay_rate_limit_gate.dart b/mobile/lib/shared/relay/relay_rate_limit_gate.dart
new file mode 100644
index 0000000000..6164013936
--- /dev/null
+++ b/mobile/lib/shared/relay/relay_rate_limit_gate.dart
@@ -0,0 +1,80 @@
+import 'dart:async';
+import 'dart:math';
+
+/// Creates a timer used by [RelayRateLimitGate].
+typedef RelayTimerFactory =
+    Timer Function(Duration duration, void Function() callback);
+
+/// Session-owned gate that pauses relay requests after back-pressure.
+class RelayRateLimitGate {
+  /// Default gate duration when the relay omits a positive retry hint.
+  static const defaultRetrySeconds = 10;
+
+  /// Longest retry hint accepted from a relay response.
+  static const maxRetrySeconds = 300;
+
+  RelayRateLimitGate({
+    DateTime Function()? now,
+    RelayTimerFactory timerFactory = Timer.new,
+  }) : _now = now ?? DateTime.now,
+       _timerFactory = timerFactory;
+
+  final DateTime Function() _now;
+  final RelayTimerFactory _timerFactory;
+  DateTime? _expiresAt;
+  Timer? _timer;
+  Completer<void>? _completer;
+
+  /// Whether a rate-limit window is currently active.
+  bool get isActive {
+    final expiresAt = _expiresAt;
+    return expiresAt != null && _now().isBefore(expiresAt);
+  }
+
+  /// Activates or extends the gate without shrinking an existing window.
+  void activate(int? retryInSeconds) {
+    final seconds = retryInSeconds != null && retryInSeconds > 0
+        ? min(retryInSeconds, maxRetrySeconds)
+        : defaultRetrySeconds;
+    final duration = Duration(seconds: seconds);
+    final newExpiry = _now().add(duration);
+    final currentExpiry = _expiresAt;
+    if (currentExpiry != null && !newExpiry.isAfter(currentExpiry)) return;
+
+    _expiresAt = newExpiry;
+    _timer?.cancel();
+    _completer ??= Completer<void>();
+    _timer = _timerFactory(duration, _expire);
+  }
+
+  /// Resolves when the active rate-limit window expires.
+  Future<void> wait() {
+    if (!isActive) return Future.value();
+    return _completer!.future;
+  }
+
+  /// Milliseconds remaining in the active window, or zero when inactive.
+  int remainingMs() {
+    final expiresAt = _expiresAt;
+    if (expiresAt == null) return 0;
+    return max(0, expiresAt.difference(_now()).inMilliseconds);
+  }
+
+  /// Clears the gate and releases all current waiters.
+  void reset() {
+    _timer?.cancel();
+    _timer = null;
+    _expiresAt = null;
+    final completer = _completer;
+    _completer = null;
+    if (completer != null && !completer.isCompleted) completer.complete();
+  }
+
+  void _expire() {
+    _timer = null;
+    _expiresAt = null;
+    final completer = _completer;
+    _completer = null;
+    if (completer != null && !completer.isCompleted) completer.complete();
+  }
+}
diff --git a/mobile/lib/shared/relay/relay_session.dart b/mobile/lib/shared/relay/relay_session.dart
index d34c5405e8..1c5c305b4c 100644
--- a/mobile/lib/shared/relay/relay_session.dart
+++ b/mobile/lib/shared/relay/relay_session.dart
@@ -13,7 +13,9 @@ import 'package:hooks_riverpod/hooks_riverpod.dart';
 import '../auth/auth.dart';
 import 'nostr_models.dart';
 import 'relay_client.dart';
+import 'relay_closed_policy.dart';
 import 'relay_provider.dart';
+import 'relay_rate_limit_gate.dart';
 import 'relay_socket.dart';
 
 enum SessionStatus { disconnected, connecting, connected, reconnecting }
@@ -40,6 +42,8 @@ class _LiveSubscription {
   final void Function(String message)? onClosed;
   Completer<void>? readyCompleter;
   int? lastSeenCreatedAt;
+  int closedRetryAttempt = 0;
+  Timer? closedRetryTimer;
 
   _LiveSubscription({
     required this.filter,
@@ -49,6 +53,13 @@ class _LiveSubscription {
   });
 }
 
+class _ClosedRetry {
+  final _LiveSubscription subscription;
+  final int generation;
+
+  _ClosedRetry({required this.subscription, required this.generation});
+}
+
 class _PendingEvent {
   final Completer<NostrEvent> completer;
   final Timer timeout;
@@ -78,33 +89,53 @@ class RelaySessionNotifier extends Notifier<SessionState> {
   RelaySessionNotifier({
     http.Client? httpClient,
     RelaySocketFactory socketFactory = RelaySocket.new,
+    DateTime Function()? now,
+    RelayRateLimitGate? rateLimitGate,
+    RelayTimerFactory retryTimerFactory = Timer.new,
+    Future<void> Function(Duration) replayDelay = Future.delayed,
   }) : _httpClient = httpClient,
-       _socketFactory = socketFactory;
+       _socketFactory = socketFactory,
+       _now = now ?? DateTime.now,
+       _rateLimitGate = rateLimitGate ?? RelayRateLimitGate(),
+       _retryTimerFactory = retryTimerFactory,
+       _replayDelay = replayDelay;
 
   final http.Client? _httpClient;
   final RelaySocketFactory _socketFactory;
+  final DateTime Function() _now;
+  final RelayRateLimitGate _rateLimitGate;
+  final RelayTimerFactory _retryTimerFactory;
+  final Future<void> Function(Duration) _replayDelay;
 
   static const _baseReconnectDelayMs = 1000;
   static const _maxReconnectDelayMs = 30000;
   static const _eventBatchMs = 16;
   static const _reconnectReplaySkewSeconds = 5;
+  static const _replayBatchSize = 8;
+  static const _replayInterBatchDelay = Duration(milliseconds: 50);
   static const _maxRecentDeliveryKeys = 5000;
+  static const _backgroundGraceDuration = Duration(seconds: 5);
 
   RelaySocket? _socket;
   final Map<String, _HistorySubscription> _historySubscriptions = {};
   final Map<String, _LiveSubscription> _liveSubscriptions = {};
+  final Map<String, _ClosedRetry> _pendingClosedRetries = {};
   final Map<String, _PendingEvent> _pendingEvents = {};
   final List<_BufferedEvent> _eventBuffer = [];
   final Set<String> _recentDeliveryKeys = {};
   Timer? _reconnectTimer;
   Timer? _flushTimer;
   Timer? _backgroundGraceTimer;
+  DateTime? _backgroundedAt;
   int _reconnectDelayMs = _baseReconnectDelayMs;
   int _subIdCounter = 0;
   bool _disposed = false;
   bool _paused = false;
   bool _hasConnectedOnce = false;
   int _connectionGeneration = 0;
+  final Map<Object, String> _visibleChannelsByOwner = {};
+  bool _socketConnected = false;
+  bool _closedRetryReplayScheduled = false;
 
   @override
   SessionState build() {
@@ -158,6 +189,7 @@ class RelaySessionNotifier extends Notifier<SessionState> {
           if (shouldCloseClient) client.close();
         });
     if (response.statusCode < 200 || response.statusCode >= 300) {
+      _activateRateLimitGateFromHttpError(response.body);
       throw RelayException(response.statusCode, response.body);
     }
     final decoded = jsonDecode(response.body);
@@ -178,12 +210,30 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     }
   }
 
+  void _activateRateLimitGateFromHttpError(String body) {
+    final dynamic decoded;
+    try {
+      decoded = jsonDecode(body);
+    } on FormatException {
+      return;
+    }
+    if (decoded is! Map<String, dynamic>) return;
+    final message = decoded['error'];
+    if (message is! String ||
+        classifyRelayClosed(message) != RelayClosedClass.rateLimited) {
+      return;
+    }
+    _rateLimitGate.activate(parseRateLimitRetrySeconds(message));
+  }
+
   /// Fetch historical events matching [filter]. Sends REQ, collects events
   /// until EOSE, then resolves. One-shot subscription.
   Future<List<NostrEvent>> fetchHistory(
     NostrFilter filter, {
     Duration timeout = const Duration(seconds: 8),
-  }) {
+  }) async {
+    if (_rateLimitGate.isActive) await _rateLimitGate.wait();
+    if (_disposed) throw StateError('Relay session is disposed');
     final subId = _nextSubId('h');
     final completer = Completer<List<NostrEvent>>();
 
@@ -214,6 +264,7 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     void Function(NostrEvent) onEvent, {
     void Function(String message)? onClosed,
   }) async {
+    if (_disposed) throw StateError('Relay session is disposed');
     final subId = _nextSubId('l');
     final readyCompleter = Completer<void>();
 
@@ -285,11 +336,35 @@ class RelaySessionNotifier extends Notifier<SessionState> {
   void debugFlushEventBuffer() => _flushEventBuffer();
 
   @visibleForTesting
-  void debugHandleConnected() => _handleConnected(_connectionGeneration);
+  Future<void> debugHandleConnected() =>
+      _handleConnected(_connectionGeneration);
 
   @visibleForTesting
-  void debugHandleDisconnected([Object? error]) =>
-      _handleDisconnected(_connectionGeneration, error);
+  Future<void> debugReplayLiveSubscriptions() =>
+      _replayLiveSubscriptions(_connectionGeneration);
+
+  @visibleForTesting
+  void debugDispose() => _dispose();
+
+  @visibleForTesting
+  void debugSupersedeConnection() => _connectionGeneration++;
+
+  @visibleForTesting
+  void debugHandleDisconnected([Object? error]) {
+    _socketConnected = false;
+    _handleDisconnected(_connectionGeneration, error);
+  }
+
+  @visibleForTesting
+  void debugResetClosedRetriesForDisconnect() {
+    _socketConnected = false;
+    _resetAllClosedRetries();
+  }
+
+  @visibleForTesting
+  void debugSetSessionStatus(SessionStatus status) {
+    _socketConnected = status == SessionStatus.connected;
+  }
 
   @visibleForTesting
   void debugPauseNow() => _pauseNow();
@@ -302,11 +377,20 @@ class RelaySessionNotifier extends Notifier<SessionState> {
   void debugAttachSocketForTest(RelaySocket socket) {
     _socket?.dispose();
     _socket = socket;
-    state = const SessionState(status: SessionStatus.connected);
+    _socketConnected = true;
+  }
+
+  /// Registers a visible channel and returns an owner-scoped release callback.
+  /// The most recently registered owner is prioritized during reconnect replay.
+  void Function() registerVisibleChannel(String channelId) {
+    final owner = Object();
+    _visibleChannelsByOwner[owner] = channelId;
+    return () => _visibleChannelsByOwner.remove(owner);
   }
 
   /// Force a reconnect (e.g., returning from background).
   Future<void> reconnect() async {
+    _socketConnected = false;
     await _socket?.disconnect();
     _reconnectDelayMs = _baseReconnectDelayMs;
     final config = ref.read(relayConfigProvider);
@@ -315,12 +399,14 @@ class RelaySessionNotifier extends Notifier<SessionState> {
 
   /// Called by the app lifecycle provider when the app goes to background.
   void onAppPaused() {
+    _backgroundedAt = _now();
     _backgroundGraceTimer?.cancel();
-    _backgroundGraceTimer = Timer(const Duration(seconds: 5), _pauseNow);
+    _backgroundGraceTimer = Timer(_backgroundGraceDuration, _pauseNow);
   }
 
   void _pauseNow() {
     _paused = true;
+    _socketConnected = false;
     _reconnectTimer?.cancel();
     _cancelAllHistory(Exception('App moved to background'));
     _rejectAllPending(Exception('App moved to background'));
@@ -331,12 +417,18 @@ class RelaySessionNotifier extends Notifier<SessionState> {
   /// Called by the app lifecycle provider when the app returns to foreground.
   void onAppResumed() {
     _paused = false;
+    final backgroundedAt = _backgroundedAt;
+    _backgroundedAt = null;
     _backgroundGraceTimer?.cancel();
     _backgroundGraceTimer = null;
 
-    // If still connected, nothing to do — the socket survived the background
-    // grace window.
-    if (state.status == SessionStatus.connected) return;
+    final backgroundedLongEnoughToRequireReconnect =
+        backgroundedAt != null &&
+        _now().difference(backgroundedAt) >= _backgroundGraceDuration;
+    if (!backgroundedLongEnoughToRequireReconnect &&
+        state.status == SessionStatus.connected) {
+      return;
+    }
 
     // Cancel any in-flight reconnect backoff timer so we reconnect immediately
     // instead of waiting for the (possibly large) exponential delay.
@@ -372,18 +464,21 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     await socket.connect();
   }
 
-  void _handleConnected(int generation) {
+  Future<void> _handleConnected(int generation) async {
     if (_disposed || generation != _connectionGeneration) return;
+    _socketConnected = true;
     _hasConnectedOnce = true;
     _reconnectDelayMs = _baseReconnectDelayMs;
     state = const SessionState(status: SessionStatus.connected);
-    _replayLiveSubscriptions();
+    await _replayLiveSubscriptions(generation);
   }
 
   void _handleDisconnected(int generation, Object? error) {
     if (_disposed || generation != _connectionGeneration) return;
+    _socketConnected = false;
     _cancelAllHistory(error);
     _rejectAllPending(error);
+    _resetAllClosedRetries();
     _eventBuffer.clear();
     _flushTimer?.cancel();
     _flushTimer = null;
@@ -413,17 +508,82 @@ class RelaySessionNotifier extends Notifier<SessionState> {
 
   /// Replay all live subscriptions after a reconnect, with a time skew to
   /// catch events that occurred during the disconnect.
-  void _replayLiveSubscriptions() {
-    for (final entry in _liveSubscriptions.entries) {
-      final sub = entry.value;
-      final since = sub.lastSeenCreatedAt != null
-          ? sub.lastSeenCreatedAt! - _reconnectReplaySkewSeconds
-          : null;
-      final filter = since != null
-          ? sub.filter.copyWithSince(since)
-          : sub.filter;
-      _sendReq(entry.key, filter);
+  Future<void> _replayLiveSubscriptions(int generation) async {
+    if (_rateLimitGate.isActive) await _rateLimitGate.wait();
+    if (!_isActiveConnection(generation)) return;
+
+    final entries = _liveSubscriptions.entries.toList();
+    final visibleChannelId = _visibleChannelsByOwner.isEmpty
+        ? null
+        : _visibleChannelsByOwner.values.last;
+    if (visibleChannelId != null) {
+      entries.sort((left, right) {
+        final leftVisible =
+            left.value.filter.tags['#h']?.contains(visibleChannelId) ?? false;
+        final rightVisible =
+            right.value.filter.tags['#h']?.contains(visibleChannelId) ?? false;
+        if (leftVisible == rightVisible) return 0;
+        return leftVisible ? -1 : 1;
+      });
     }
+
+    await _sendReplayBatches(entries, generation);
+  }
+
+  Future<void> _replayPendingClosedRetries(int generation) async {
+    if (!_isActiveConnection(generation)) return;
+    final entries = _pendingClosedRetries.entries
+        .where((entry) => entry.value.generation == generation)
+        .map(
+          (entry) => MapEntry<String, _LiveSubscription>(
+            entry.key,
+            entry.value.subscription,
+          ),
+        )
+        .toList();
+    await _sendReplayBatches(entries, generation, pendingClosedRetries: true);
+  }
+
+  Future<void> _sendReplayBatches(
+    List<MapEntry<String, _LiveSubscription>> entries,
+    int generation, {
+    bool pendingClosedRetries = false,
+  }) async {
+    for (var i = 0; i < entries.length; i += _replayBatchSize) {
+      if (_rateLimitGate.isActive) await _rateLimitGate.wait();
+      if (!_isActiveConnection(generation)) return;
+      final batch = entries.sublist(
+        i,
+        min(i + _replayBatchSize, entries.length),
+      );
+      for (final entry in batch) {
+        if (_liveSubscriptions[entry.key] != entry.value) continue;
+        if (pendingClosedRetries) {
+          final pendingRetry = _pendingClosedRetries[entry.key];
+          if (pendingRetry?.subscription != entry.value ||
+              pendingRetry?.generation != generation) {
+            continue;
+          }
+          _pendingClosedRetries.remove(entry.key);
+        }
+        _sendReq(entry.key, _replayFilter(entry.value));
+      }
+      if (i + _replayBatchSize < entries.length) {
+        await _replayDelay(_replayInterBatchDelay);
+      }
+    }
+  }
+
+  bool _isActiveConnection(int generation) =>
+      !_disposed && generation == _connectionGeneration;
+
+  NostrFilter _replayFilter(_LiveSubscription subscription) {
+    final since = subscription.lastSeenCreatedAt;
+    return since == null
+        ? subscription.filter
+        : subscription.filter.copyWithSince(
+            max(0, since - _reconnectReplaySkewSeconds),
+          );
   }
 
   void _handleMessage(List<dynamic> data) {
@@ -458,6 +618,7 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     // Live subscriptions get batched.
     final liveSub = _liveSubscriptions[subId];
     if (liveSub != null) {
+      _resetClosedRetry(liveSub);
       // Track last seen timestamp for reconnect replay.
       if (liveSub.lastSeenCreatedAt == null ||
           event.createdAt > liveSub.lastSeenCreatedAt!) {
@@ -485,6 +646,9 @@ class RelaySessionNotifier extends Notifier<SessionState> {
 
     // Live subscription: signal ready.
     final liveSub = _liveSubscriptions[subId];
+    if (liveSub != null) {
+      _resetClosedRetry(liveSub);
+    }
     if (liveSub != null &&
         liveSub.readyCompleter != null &&
         !liveSub.readyCompleter!.isCompleted) {
@@ -504,9 +668,13 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     final message = data.length >= 3 && data[2] is String
         ? data[2] as String
         : 'subscription closed by relay';
+    final closedClass = classifyRelayClosed(message);
 
     final historySub = _historySubscriptions.remove(subId);
     if (historySub != null) {
+      if (closedClass == RelayClosedClass.rateLimited) {
+        _rateLimitGate.activate(parseRateLimitRetrySeconds(message));
+      }
       historySub.timeout.cancel();
       if (!historySub.completer.isCompleted) {
         historySub.completer.completeError(Exception(message));
@@ -514,17 +682,87 @@ class RelaySessionNotifier extends Notifier<SessionState> {
       return;
     }
 
-    final liveSub = _liveSubscriptions.remove(subId);
+    final liveSub = _liveSubscriptions[subId];
     if (liveSub == null) return;
-    _recentDeliveryKeys.removeWhere((key) => key.startsWith('$subId:'));
-
     final readyCompleter = liveSub.readyCompleter;
-    if (readyCompleter != null && !readyCompleter.isCompleted) {
-      readyCompleter.completeError(Exception(message));
+    if (closedClass == RelayClosedClass.terminal) {
+      if (readyCompleter != null && !readyCompleter.isCompleted) {
+        readyCompleter.completeError(Exception(message));
+      }
+      liveSub.onClosed?.call(message);
+      _removeLiveSubscription(subId, liveSub);
       return;
     }
+    if (readyCompleter != null && !readyCompleter.isCompleted) {
+      readyCompleter.complete();
+      liveSub.readyCompleter = null;
+    }
+    if (liveSub.closedRetryTimer != null) return;
 
-    liveSub.onClosed?.call(message);
+    final attempt = liveSub.closedRetryAttempt;
+    final backoffMs = attempt >= 5
+        ? _maxReconnectDelayMs
+        : _baseReconnectDelayMs * (1 << attempt);
+    var delayMs = backoffMs;
+    if (closedClass == RelayClosedClass.rateLimited) {
+      final retrySeconds = parseRateLimitRetrySeconds(message);
+      _rateLimitGate.activate(retrySeconds);
+      final fallbackMs =
+          (retrySeconds != null && retrySeconds > 0
+              ? min(retrySeconds, RelayRateLimitGate.maxRetrySeconds)
+              : RelayRateLimitGate.defaultRetrySeconds) *
+          1000;
+      delayMs = max(
+        backoffMs,
+        _rateLimitGate.remainingMs() == 0
+            ? fallbackMs
+            : _rateLimitGate.remainingMs(),
+      );
+    }
+
+    liveSub.closedRetryAttempt = attempt + 1;
+    final retryGeneration = _connectionGeneration;
+    liveSub.closedRetryTimer = _retryTimerFactory(
+      Duration(milliseconds: delayMs),
+      () async {
+        liveSub.closedRetryTimer = null;
+        if (!_isActiveConnection(retryGeneration) ||
+            _liveSubscriptions[subId] != liveSub) {
+          return;
+        }
+        if (_rateLimitGate.isActive) await _rateLimitGate.wait();
+        if (!_isActiveConnection(retryGeneration) ||
+            _liveSubscriptions[subId] != liveSub ||
+            !_socketConnected) {
+          return;
+        }
+        _pendingClosedRetries[subId] = _ClosedRetry(
+          subscription: liveSub,
+          generation: retryGeneration,
+        );
+        _scheduleClosedRetryReplay(retryGeneration);
+      },
+    );
+  }
+
+  void _scheduleClosedRetryReplay(int generation) {
+    if (_closedRetryReplayScheduled) return;
+    _closedRetryReplayScheduled = true;
+    scheduleMicrotask(() async {
+      try {
+        await _replayPendingClosedRetries(generation);
+      } finally {
+        _closedRetryReplayScheduled = false;
+        _pendingClosedRetries.removeWhere(
+          (_, retry) => retry.generation != _connectionGeneration,
+        );
+        if (_pendingClosedRetries.values.any(
+          (retry) => retry.generation == _connectionGeneration,
+        )) {
+          _scheduleClosedRetryReplay(_connectionGeneration);
+        }
+      }
+    });
   }
 
   void _handleOk(List<dynamic> data) {
@@ -619,11 +857,43 @@ class RelaySessionNotifier extends Notifier<SessionState> {
   }
 
   void _unsubscribe(String subId) {
-    _liveSubscriptions.remove(subId);
-    _recentDeliveryKeys.removeWhere((key) => key.startsWith('$subId:'));
+    final subscription = _liveSubscriptions[subId];
+    if (subscription != null) {
+      _removeLiveSubscription(subId, subscription);
+    }
     _sendClose(subId);
   }
 
+  void _removeLiveSubscription(String subId, _LiveSubscription subscription) {
+    if (_liveSubscriptions[subId] != subscription) return;
+    _liveSubscriptions.remove(subId);
+    _pendingClosedRetries.remove(subId);
+    subscription.closedRetryTimer?.cancel();
+    subscription.closedRetryTimer = null;
+    _recentDeliveryKeys.removeWhere((key) => key.startsWith('$subId:'));
+  }
+
+  void _resetClosedRetry(_LiveSubscription subscription) {
+    subscription.closedRetryAttempt = 0;
+    subscription.closedRetryTimer?.cancel();
+    subscription.closedRetryTimer = null;
+  }
+
+  void _cancelAllClosedRetries() {
+    _pendingClosedRetries.clear();
+    for (final subscription in _liveSubscriptions.values) {
+      subscription.closedRetryTimer?.cancel();
+      subscription.closedRetryTimer = null;
+    }
+  }
+
+  void _resetAllClosedRetries() {
+    _pendingClosedRetries.clear();
+    for (final subscription in _liveSubscriptions.values) {
+      _resetClosedRetry(subscription);
+    }
+  }
+
   void _cancelAllHistory(Object? error) {
     for (final entry in _historySubscriptions.values) {
       entry.timeout.cancel();
@@ -650,8 +920,19 @@ class RelaySessionNotifier extends Notifier<SessionState> {
     _reconnectTimer?.cancel();
     _flushTimer?.cancel();
     _backgroundGraceTimer?.cancel();
+    _backgroundedAt = null;
+    _cancelAllClosedRetries();
+    _rateLimitGate.reset();
+    _visibleChannelsByOwner.clear();
+    _socketConnected = false;
     _cancelAllHistory(null);
     _rejectAllPending(null);
+    final subscriptions = _liveSubscriptions.values.toList();
+    _liveSubscriptions.clear();
+    for (final subscription in subscriptions) {
+      subscription.closedRetryTimer?.cancel();
+      subscription.closedRetryTimer = null;
+    }
     _recentDeliveryKeys.clear();
     _socket?.dispose();
     _socket = null;
diff --git a/mobile/lib/shared/relay/relay_socket.dart b/mobile/lib/shared/relay/relay_socket.dart
index 267b030391..5b23279e81 100644
--- a/mobile/lib/shared/relay/relay_socket.dart
+++ b/mobile/lib/shared/relay/relay_socket.dart
@@ -3,6 +3,7 @@ import 'dart:convert';
 
 import 'package:flutter/foundation.dart';
 import 'package:nostr/nostr.dart' as nostr;
+import 'package:web_socket_channel/io.dart';
 import 'package:web_socket_channel/web_socket_channel.dart';
 
 import 'nostr_models.dart';
@@ -30,6 +31,12 @@ Exception classifyRelayAuthFailure(String message) {
 }
 
 class RelaySocket {
+  /// Interval for sending a ping and awaiting its pong before disconnecting.
+  static const pingInterval = Duration(seconds: 30);
+
+  @visibleForTesting
+  static Duration debugPingInterval = pingInterval;
+
   final String _wsUrl;
   final String? _nsec;
   final void Function(List<dynamic> message) _onMessage;
@@ -63,7 +70,10 @@ class RelaySocket {
     _state = SocketState.connecting;
 
     try {
-      _channel = WebSocketChannel.connect(Uri.parse(_wsUrl));
+      _channel = IOWebSocketChannel.connect(
+        Uri.parse(_wsUrl),
+        pingInterval: debugPingInterval,
+      );
       await _channel!.ready;
     } catch (e) {
       _state = SocketState.disconnected;
diff --git a/mobile/lib/shared/theme/app_theme.dart b/mobile/lib/shared/theme/app_theme.dart
index f8000d79e2..1407357062 100644
--- a/mobile/lib/shared/theme/app_theme.dart
+++ b/mobile/lib/shared/theme/app_theme.dart
@@ -16,6 +16,7 @@ class Radii {
   static const double md = 8.0;
   static const double sm = 6.0;
   static const double card = 12.0; // grouped settings cards
+  static const double popover = 20.0;
   static const double dialog = 24.0; // desktop uses rounded-3xl for dialogs
 
   /// Fully rounds pills, circles, and other capsule shapes.
@@ -277,13 +278,22 @@ class AppTheme {
         labelPadding: EdgeInsets.zero,
       ),
 
-      // Popups/menus: desktop uses rounded-md (8px)
+      // Popups/menus share the elevated 20px mobile popover treatment.
       popupMenuTheme: PopupMenuThemeData(
-        color: scheme.surface,
-        elevation: 4,
+        color: scheme.surface.withValues(alpha: 0.98),
+        elevation: 8,
+        shadowColor: scheme.shadow.withValues(alpha: 0.18),
+        surfaceTintColor: Colors.transparent,
+        textStyle: textTheme.labelLarge?.copyWith(color: scheme.onSurface),
+        labelTextStyle: WidgetStatePropertyAll(
+          textTheme.labelLarge?.copyWith(color: scheme.onSurface),
+        ),
         shape: RoundedRectangleBorder(
-          borderRadius: BorderRadius.circular(Radii.md),
-          side: BorderSide(color: scheme.outline),
+          borderRadius: BorderRadius.circular(Radii.popover),
+          side: BorderSide(
+            color: Colors.black.withValues(alpha: 0.04),
+            width: 1,
+          ),
         ),
       ),
 
diff --git a/mobile/lib/shared/theme/message_typography.dart b/mobile/lib/shared/theme/message_typography.dart
index 1073626390..5a5d2c2c6e 100644
--- a/mobile/lib/shared/theme/message_typography.dart
+++ b/mobile/lib/shared/theme/message_typography.dart
@@ -88,8 +88,14 @@ const contentListBodyTextStyle = TextStyle(
 /// Timestamps in compact content lists.
 const contentListTimestampTextStyle = messageMetadataTextStyle;
 
-/// Filter chip labels use the compact 15sp type ramp.
-const filterChipTextStyle = messageMetadataTextStyle;
+/// Filter chip labels use a tighter 15sp Inter treatment.
+const filterChipTextStyle = TextStyle(
+  fontFamily: _fontFamily,
+  fontSize: 15,
+  fontWeight: FontWeight.w400,
+  height: 1,
+  letterSpacing: 0,
+);
 
 /// Search fields use the primary 15sp body treatment.
 const searchInputTextStyle = messageBodyTextStyle;
diff --git a/mobile/lib/shared/widgets/anchored_popover_menu.dart b/mobile/lib/shared/widgets/anchored_popover_menu.dart
index 46b50b6b00..7188e021f9 100644
--- a/mobile/lib/shared/widgets/anchored_popover_menu.dart
+++ b/mobile/lib/shared/widgets/anchored_popover_menu.dart
@@ -9,6 +9,24 @@ const _popoverEnterDuration = Duration(milliseconds: 150);
 const _popoverExitDuration = Duration(milliseconds: 110);
 const _popoverStartScale = 0.96;
 
+/// Elevation shared by anchored menus and composer popover surfaces.
+const appPopoverElevation = 8.0;
+
+/// Returns the translucent surface color shared by app popovers.
+Color appPopoverColor(BuildContext context) =>
+    context.colors.surface.withValues(alpha: 0.98);
+
+/// Returns the shadow color shared by app popovers.
+Color appPopoverShadowColor(BuildContext context) =>
+    context.colors.shadow.withValues(alpha: 0.18);
+
+/// Returns the 20px shape and composer-matching hairline shared by popovers.
+RoundedRectangleBorder appPopoverShape(BuildContext context) =>
+    RoundedRectangleBorder(
+      borderRadius: BorderRadius.circular(Radii.popover),
+      side: BorderSide(color: Colors.black.withValues(alpha: 0.04), width: 1),
+    );
+
 /// The horizontal edge a popover aligns to on its triggering control.
 enum AnchoredPopoverAlignment {
   /// Aligns the popover's leading edge with the trigger's leading edge.
@@ -25,10 +43,10 @@ Future<T?> showAnchoredPopover<T>({
   required List<PopupMenuEntry<T>> items,
   required double width,
   required AnchoredPopoverAlignment alignment,
-  required Color color,
-  required ShapeBorder shape,
-  required double elevation,
-  required Color shadowColor,
+  Color? color,
+  ShapeBorder? shape,
+  double elevation = appPopoverElevation,
+  Color? shadowColor,
   Offset offset = Offset.zero,
   EdgeInsetsGeometry menuPadding = EdgeInsets.zero,
   Clip clipBehavior = Clip.antiAlias,
@@ -56,10 +74,10 @@ Future<T?> showAnchoredPopover<T>({
       width: width,
       alignment: alignment,
       offset: offset,
-      color: color,
-      shape: shape,
+      color: color ?? appPopoverColor(context),
+      shape: shape ?? appPopoverShape(context),
       elevation: elevation,
-      shadowColor: shadowColor,
+      shadowColor: shadowColor ?? appPopoverShadowColor(context),
       menuPadding: menuPadding,
       clipBehavior: clipBehavior,
       surfaceKey: surfaceKey,
diff --git a/mobile/lib/shared/widgets/filter_chip_bar.dart b/mobile/lib/shared/widgets/filter_chip_bar.dart
index 1fe55712a5..628267c167 100644
--- a/mobile/lib/shared/widgets/filter_chip_bar.dart
+++ b/mobile/lib/shared/widgets/filter_chip_bar.dart
@@ -129,15 +129,23 @@ class FilterChipBar<T> extends StatelessWidget {
             textAlign: fillWidth ? TextAlign.center : TextAlign.start,
             style: labelStyle,
           );
+    final centeredLabel = Align(
+      alignment: Alignment.center,
+      widthFactor: fillWidth ? null : 1,
+      heightFactor: 1,
+      child: label,
+    );
     final chip = FilterChip(
       selected: isSelected,
       showCheckmark: false,
+      shape: RoundedRectangleBorder(
+        borderRadius: BorderRadius.circular(Radii.lg),
+      ),
+      side: BorderSide.none,
       label: fillWidth
-          ? SizedBox(
-              width: double.infinity,
-              child: Center(child: label),
-            )
-          : label,
+          ? SizedBox(width: double.infinity, child: centeredLabel)
+          : centeredLabel,
+      labelPadding: EdgeInsets.zero,
       onSelected: (_) => onSelected(item.id),
       padding: EdgeInsets.symmetric(
         horizontal: fillWidth ? Grid.quarter : Grid.twelve,
diff --git a/mobile/lib/shared/widgets/keyboard_dismiss_on_drag.dart b/mobile/lib/shared/widgets/keyboard_dismiss_on_drag.dart
index f562b9f83a..93371bdd0b 100644
--- a/mobile/lib/shared/widgets/keyboard_dismiss_on_drag.dart
+++ b/mobile/lib/shared/widgets/keyboard_dismiss_on_drag.dart
@@ -27,8 +27,13 @@ const keyboardDismissDragThreshold = 48.0;
 /// `WindowInsetsAnimationController`).
 class KeyboardDismissOnDrag extends HookWidget {
   final Widget child;
+  final VoidCallback? onUserScrollStart;
 
-  const KeyboardDismissOnDrag({super.key, required this.child});
+  const KeyboardDismissOnDrag({
+    super.key,
+    this.onUserScrollStart,
+    required this.child,
+  });
 
   @override
   Widget build(BuildContext context) {
@@ -37,8 +42,12 @@ class KeyboardDismissOnDrag extends HookWidget {
     final downwardTravel = useRef(0.0);
 
     bool handle(ScrollNotification notification) {
-      if (notification is ScrollStartNotification ||
-          notification is ScrollEndNotification) {
+      if (notification is ScrollStartNotification) {
+        if (notification.dragDetails != null) onUserScrollStart?.call();
+        downwardTravel.value = 0;
+        return false;
+      }
+      if (notification is ScrollEndNotification) {
         downwardTravel.value = 0;
         return false;
       }
diff --git a/mobile/lib/shared/widgets/mobile_tab_footer_backdrop.dart b/mobile/lib/shared/widgets/mobile_tab_footer_backdrop.dart
index 687880acb1..d972b8184f 100644
--- a/mobile/lib/shared/widgets/mobile_tab_footer_backdrop.dart
+++ b/mobile/lib/shared/widgets/mobile_tab_footer_backdrop.dart
@@ -16,6 +16,27 @@ double mobileTabFooterBackdropHeight(BuildContext context) =>
     Grid.xl +
     Grid.gutter;
 
+/// Builds the shared transparent-to-surface footer fade.
+///
+/// Kept separate from [MobileTabFooterBackdrop] so floating controls such as
+/// the channel composer can paint the exact same fade behind their own content.
+LinearGradient mobileTabFooterBackdropGradient(
+  BuildContext context, {
+  List<double> stops = const [0, 0.5, 1],
+  List<double> opacities = const [0, 0.75, 1],
+}) {
+  assert(stops.length == opacities.length);
+  final surface = context.colors.surface;
+  return LinearGradient(
+    begin: Alignment.topCenter,
+    end: Alignment.bottomCenter,
+    stops: stops,
+    colors: [
+      for (final opacity in opacities) surface.withValues(alpha: opacity),
+    ],
+  );
+}
+
 /// Shared fade behind the floating mobile tab bar.
 class MobileTabFooterBackdrop extends StatelessWidget {
   /// Vertical extent of the backdrop in logical pixels.
@@ -39,20 +60,15 @@ class MobileTabFooterBackdrop extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    final surface = context.colors.surface;
     return SizedBox(
       height: height,
       width: double.infinity,
       child: DecoratedBox(
         decoration: BoxDecoration(
-          gradient: LinearGradient(
-            begin: Alignment.topCenter,
-            end: Alignment.bottomCenter,
+          gradient: mobileTabFooterBackdropGradient(
+            context,
             stops: stops,
-            colors: [
-              for (final opacity in opacities)
-                surface.withValues(alpha: opacity),
-            ],
+            opacities: opacities,
           ),
         ),
       ),
diff --git a/mobile/pubspec.lock b/mobile/pubspec.lock
index 05ccc2ea0f..6287e4c86c 100644
--- a/mobile/pubspec.lock
+++ b/mobile/pubspec.lock
@@ -274,7 +274,7 @@ packages:
     source: hosted
     version: "0.3.5+2"
   crypto:
-    dependency: transitive
+    dependency: "direct dev"
     description:
       name: crypto
       sha256: c8ea0233063ba03258fbcf2ca4d6dadfefe14f02fab57702265467a19f27fadf
diff --git a/mobile/pubspec.yaml b/mobile/pubspec.yaml
index 42b7935582..41d2a0aeb8 100644
--- a/mobile/pubspec.yaml
+++ b/mobile/pubspec.yaml
@@ -47,6 +47,7 @@ dev_dependencies:
   flutter_test:
     sdk: flutter
   flutter_lints: ^6.0.0
+  crypto: ^3.0.7
   custom_lint: ^0.8.0
   riverpod_lint: ^3.1.0
   mocktail: ^1.0.4
diff --git a/mobile/test/features/activity/activity_page_test.dart b/mobile/test/features/activity/activity_page_test.dart
index a0293455f2..aecb3303fc 100644
--- a/mobile/test/features/activity/activity_page_test.dart
+++ b/mobile/test/features/activity/activity_page_test.dart
@@ -13,6 +13,7 @@ import 'package:buzz/features/channels/read_state/read_state_provider.dart';
 import 'package:buzz/features/profile/user_cache_provider.dart';
 import 'package:buzz/features/profile/user_profile.dart';
 import 'package:buzz/shared/theme/theme.dart';
+import 'package:buzz/shared/widgets/anchored_popover_menu.dart';
 import 'package:buzz/shared/widgets/frosted_app_bar.dart';
 import 'package:buzz/shared/widgets/avatar_image.dart';
 import 'package:flutter/material.dart';
@@ -111,6 +112,7 @@ void main() {
     Map<String, int> readContexts = const {},
     List<Channel>? channels,
     TextScaler? textScaler,
+    EdgeInsets mediaPadding = EdgeInsets.zero,
   }) async {
     SharedPreferences.setMockInitialValues({});
     final prefs = await SharedPreferences.getInstance();
@@ -133,12 +135,12 @@ void main() {
       ],
       child: MaterialApp(
         theme: AppTheme.light(),
-        builder: textScaler == null
-            ? null
-            : (context, child) => MediaQuery(
-                data: MediaQuery.of(context).copyWith(textScaler: textScaler),
-                child: child!,
-              ),
+        builder: (context, child) => MediaQuery(
+          data: MediaQuery.of(
+            context,
+          ).copyWith(textScaler: textScaler, padding: mediaPadding),
+          child: child!,
+        ),
         home: const ActivityPage(),
       ),
     );
@@ -182,16 +184,22 @@ void main() {
     expect(find.byTooltip('Back'), findsNothing);
   });
 
-  testWidgets('keeps bottom clearance for the floating tab bar', (
+  testWidgets('keeps footer clearance inside the scrollable content', (
     tester,
   ) async {
-    await tester.pumpWidget(await buildTestable());
+    await tester.pumpWidget(
+      await buildTestable(mediaPadding: const EdgeInsets.only(bottom: 88)),
+    );
     await tester.pumpAndSettle();
 
-    final safeAreas = tester.widgetList<SafeArea>(find.byType(SafeArea));
-    expect(safeAreas, hasLength(1));
-    expect(safeAreas.single.top, isFalse);
-    expect(safeAreas.single.bottom, isTrue);
+    final safeArea = tester.widget<SafeArea>(
+      find.byKey(const ValueKey('activity-content-safe-area')),
+    );
+    expect(safeArea.top, isFalse);
+    expect(safeArea.bottom, isFalse);
+
+    final list = tester.widget<ListView>(find.byType(ListView));
+    expect(list.padding, const EdgeInsets.fromLTRB(0, Grid.xxs, 0, 96));
   });
 
   testWidgets('shows error view with retry button', (tester) async {
@@ -253,7 +261,13 @@ void main() {
 
     final material = tester.widget<Material>(surface);
     final shape = material.shape! as RoundedRectangleBorder;
-    expect(shape.borderRadius, BorderRadius.circular(Radii.card));
+    expect(shape.borderRadius, BorderRadius.circular(Radii.popover));
+    expect(shape.side.color, Colors.black.withValues(alpha: 0.04));
+    expect(material.elevation, appPopoverElevation);
+    expect(
+      material.shadowColor,
+      appPopoverShadowColor(tester.element(surface)),
+    );
     expect(material.surfaceTintColor, Colors.transparent);
     expect(material.clipBehavior, Clip.antiAlias);
 
@@ -275,7 +289,11 @@ void main() {
     final optionsSurface = find.byKey(
       const ValueKey('activity-options-popover'),
     );
+    final optionsMaterial = tester.widget<Material>(optionsSurface);
+    final optionsShape = optionsMaterial.shape! as RoundedRectangleBorder;
     expect(tester.getSize(optionsSurface).width, 216);
+    expect(optionsShape.borderRadius, BorderRadius.circular(Radii.popover));
+    expect(optionsMaterial.elevation, appPopoverElevation);
     expect(
       tester
           .widget<ScaleTransition>(
diff --git a/mobile/test/features/channels/channel_detail_page_test.dart b/mobile/test/features/channels/channel_detail_page_test.dart
index 899394de23..7f8d0774c3 100644
--- a/mobile/test/features/channels/channel_detail_page_test.dart
+++ b/mobile/test/features/channels/channel_detail_page_test.dart
@@ -85,6 +85,25 @@ NostrEvent _systemMsg({
   sig: '',
 );
 
+NostrEvent _huddleMsg({
+  required String id,
+  required int kind,
+  String pubkey = 'alice',
+  int createdAt = 1000,
+}) => NostrEvent(
+  id: id,
+  pubkey: pubkey,
+  createdAt: createdAt,
+  kind: kind,
+  tags: [
+    ['h', _channelId],
+  ],
+  content: jsonEncode({
+    'ephemeral_channel_id': '8d764100-fd8f-44cf-9c98-6d8fbd739b8c',
+  }),
+  sig: '',
+);
+
 NostrEvent _reaction({
   required String id,
   required String targetId,
@@ -158,6 +177,7 @@ Widget _buildTestable({
   Map<String, List<NostrEvent>> threadReplies = const {},
   Map<String, Future<List<NostrEvent>>> pendingThreadReplies = const {},
   TextScaler textScaler = TextScaler.noScaling,
+  bool disableAnimations = false,
   RelaySessionNotifier? relaySessionNotifier,
 }) {
   final resolvedChannel = channel ?? _testChannel;
@@ -216,7 +236,10 @@ Widget _buildTestable({
     child: MaterialApp(
       theme: AppTheme.light(),
       builder: (context, child) => MediaQuery(
-        data: MediaQuery.of(context).copyWith(textScaler: textScaler),
+        data: MediaQuery.of(context).copyWith(
+          textScaler: textScaler,
+          disableAnimations: disableAnimations,
+        ),
         child: child!,
       ),
       navigatorObservers: navigatorObservers,
@@ -229,6 +252,55 @@ Widget _buildTestable({
   );
 }
 
+Widget _buildNavigationTestable({
+  required Channel channelA,
+  required Channel channelB,
+  required RelaySessionNotifier relaySession,
+}) {
+  return ProviderScope(
+    overrides: [
+      relaySessionProvider.overrideWith(() => relaySession),
+      channelMessagesProvider(
+        channelA.id,
+      ).overrideWith(() => _FakeMessagesNotifier([], channelId: channelA.id)),
+      channelMessagesProvider(
+        channelB.id,
+      ).overrideWith(() => _FakeMessagesNotifier([], channelId: channelB.id)),
+      channelTypingProvider(
+        channelA.id,
+      ).overrideWith(() => _FakeTypingNotifier([], channelId: channelA.id)),
+      channelTypingProvider(
+        channelB.id,
+      ).overrideWith(() => _FakeTypingNotifier([], channelId: channelB.id)),
+      channelDetailsProvider(
+        channelA.id,
+      ).overrideWith((ref) async => ChannelDetails.fromChannel(channelA)),
+      channelDetailsProvider(
+        channelB.id,
+      ).overrideWith((ref) async => ChannelDetails.fromChannel(channelB)),
+      channelMembersProvider(
+        channelA.id,
+      ).overrideWith((ref) async => const <ChannelMember>[]),
+      channelMembersProvider(
+        channelB.id,
+      ).overrideWith((ref) async => const <ChannelMember>[]),
+      userCacheProvider.overrideWith(() => _FakeUserCacheNotifier({})),
+      profileProvider.overrideWith(() => _FakeProfileNotifier()),
+      channelsProvider.overrideWith(
+        () => _FakeChannelsNotifier([channelA, channelB]),
+      ),
+      relayClientProvider.overrideWithValue(
+        RelayClient(baseUrl: 'http://localhost:3000'),
+      ),
+      savedPrefsProvider.overrideWithValue(_testPrefs),
+    ],
+    child: MaterialApp(
+      theme: AppTheme.light(),
+      home: ChannelDetailPage(channel: channelA),
+    ),
+  );
+}
+
 /// Finder that searches for text within RichText spans. [find.text] only
 /// matches the top-level text property; this also searches nested TextSpans.
 Finder findRichText(String text) {
@@ -262,6 +334,103 @@ void main() {
   });
 
   group('ChannelDetailPage', () {
+    testWidgets(
+      'restores the previous channel replay priority after a nested pop',
+      (tester) async {
+        final channelA = _channel(id: 'channel-a', name: 'channel A');
+        final channelB = _channel(id: 'channel-b', name: 'channel B');
+        final socket = _RecordingRelaySocket();
+        final relaySession = RelaySessionNotifier();
+        relaySession.debugAttachSocketForTest(socket);
+
+        final subscribeB = relaySession.subscribe(
+          _filterForChannel(channelB.id),
+          (_) {},
+        );
+        relaySession.debugHandleMessage(['EOSE', 'l-1']);
+        await subscribeB;
+        final subscribeA = relaySession.subscribe(
+          _filterForChannel(channelA.id),
+          (_) {},
+        );
+        relaySession.debugHandleMessage(['EOSE', 'l-2']);
+        await subscribeA;
+
+        await tester.pumpWidget(
+          _buildNavigationTestable(
+            channelA: channelA,
+            channelB: channelB,
+            relaySession: relaySession,
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        final navigator = Navigator.of(
+          tester.element(find.byType(ChannelDetailPage)),
+        );
+        navigator.push(
+          MaterialPageRoute<void>(
+            builder: (_) => ChannelDetailPage(channel: channelB),
+          ),
+        );
+        await tester.pumpAndSettle();
+        navigator.pop();
+        await tester.pumpAndSettle();
+
+        socket.messages.clear();
+        await relaySession.debugReplayLiveSubscriptions();
+
+        expect(_replayedChannelIds(socket), [channelA.id, channelB.id]);
+      },
+    );
+
+    testWidgets(
+      'keeps replacement channel replay priority after old route disposal',
+      (tester) async {
+        final channelA = _channel(id: 'channel-a', name: 'channel A');
+        final channelB = _channel(id: 'channel-b', name: 'channel B');
+        final socket = _RecordingRelaySocket();
+        final relaySession = RelaySessionNotifier();
+        relaySession.debugAttachSocketForTest(socket);
+
+        final subscribeA = relaySession.subscribe(
+          _filterForChannel(channelA.id),
+          (_) {},
+        );
+        relaySession.debugHandleMessage(['EOSE', 'l-1']);
+        await subscribeA;
+        final subscribeB = relaySession.subscribe(
+          _filterForChannel(channelB.id),
+          (_) {},
+        );
+        relaySession.debugHandleMessage(['EOSE', 'l-2']);
+        await subscribeB;
+
+        await tester.pumpWidget(
+          _buildNavigationTestable(
+            channelA: channelA,
+            channelB: channelB,
+            relaySession: relaySession,
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        Navigator.of(
+          tester.element(find.byType(ChannelDetailPage)),
+        ).pushReplacement(
+          MaterialPageRoute<void>(
+            builder: (_) => ChannelDetailPage(channel: channelB),
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        socket.messages.clear();
+        await relaySession.debugReplayLiveSubscriptions();
+
+        expect(_replayedChannelIds(socket), [channelB.id, channelA.id]);
+      },
+    );
+
     testWidgets('debounces same-slot reconnect skeletons before revealing', (
       tester,
     ) async {
@@ -583,6 +752,53 @@ void main() {
       );
     });
 
+    testWidgets('clears the composer inset when membership is revoked', (
+      tester,
+    ) async {
+      final channelsNotifier = _FakeChannelsNotifier([_testChannel]);
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [
+            _textMsg(
+              id: 'msg1',
+              pubkey: 'alice',
+              content: 'Hello',
+              createdAt: 1000,
+            ),
+          ],
+          channelsNotifier: channelsNotifier,
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      final messageListFinder = find.byKey(
+        const ValueKey('channel-message-list'),
+      );
+      expect(
+        tester
+            .widget<ScrollablePositionedList>(messageListFinder)
+            .padding!
+            .bottom,
+        greaterThan(0),
+      );
+      expect(
+        find.byKey(const ValueKey('channel-composer-dock')),
+        findsOneWidget,
+      );
+
+      channelsNotifier.setChannels([_testChannel.copyWith(isMember: false)]);
+      await tester.pumpAndSettle();
+
+      expect(find.byKey(const ValueKey('channel-composer-dock')), findsNothing);
+      expect(
+        tester
+            .widget<ScrollablePositionedList>(messageListFinder)
+            .padding!
+            .bottom,
+        0,
+      );
+    });
+
     testWidgets('updates detail page state after joining a channel', (
       tester,
     ) async {
@@ -740,7 +956,15 @@ void main() {
       final messageList = tester.widget<ScrollablePositionedList>(
         find.byKey(const ValueKey('channel-message-list')),
       );
-      expect(messageList.padding!.bottom, 0);
+      final composerDock = find.byKey(const ValueKey('channel-composer-dock'));
+      final composerDockHeight = tester.getSize(composerDock).height;
+      expect(messageList.padding!.bottom, composerDockHeight);
+      expect(
+        tester
+            .getBottomLeft(find.byKey(const ValueKey('channel-message-list')))
+            .dy,
+        greaterThan(tester.getTopLeft(composerDock).dy),
+      );
       final newestMessageGroup = tester.widget<Padding>(
         find.byKey(const ValueKey('channel-message-group-msg2')),
       );
@@ -969,6 +1193,26 @@ void main() {
         find.byKey(const ValueKey('channel-jump-to-latest')),
         findsOneWidget,
       );
+      final latestSurface = tester.widget<Container>(
+        find.byKey(const ValueKey('channel-jump-to-latest-surface')),
+      );
+      final latestDecoration = latestSurface.decoration! as BoxDecoration;
+      expect(latestDecoration.borderRadius, BorderRadius.circular(Radii.full));
+      expect(
+        latestDecoration.color,
+        AppTheme.light().colorScheme.surface.withValues(alpha: 0.5),
+      );
+      expect(
+        (latestDecoration.border! as Border).top.color,
+        Colors.black.withValues(alpha: 0.04),
+      );
+      expect(
+        find.descendant(
+          of: find.byKey(const ValueKey('channel-jump-to-latest')),
+          matching: find.byType(BackdropFilter),
+        ),
+        findsOneWidget,
+      );
 
       messagesNotifier.setMessages([
         ...initialMessages,
@@ -1050,7 +1294,20 @@ void main() {
         ]);
         await tester.pumpAndSettle();
 
-        expect(findRichText('Newest live update'), findsNothing);
+        // Cache-extent mounting varies by platform, so assert the reversed
+        // list's semantic boundary rather than whether item 0 is mounted.
+        final positions = tester
+            .widget<ScrollablePositionedList>(messageList)
+            .itemPositionsNotifier!
+            .itemPositions
+            .value;
+        expect(
+          positions.any(
+            (position) =>
+                position.index == 0 && position.itemLeadingEdge.abs() < 0.01,
+          ),
+          isFalse,
+        );
         expect(
           find.byKey(const ValueKey('channel-jump-to-latest')),
           findsOneWidget,
@@ -1300,6 +1557,31 @@ void main() {
       );
     });
 
+    testWidgets('renders a huddle event like a regular message row', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [_huddleMsg(id: 'huddle-1', kind: EventKind.huddleStarted)],
+          users: {
+            'alice': const UserProfile(pubkey: 'alice', displayName: 'Alice'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      expect(find.text('Alice'), findsOneWidget);
+      expect(findRichText('started a huddle'), findsOneWidget);
+      expect(
+        tester.getSize(find.byType(CircleAvatar)),
+        const Size.square(messageAvatarSize),
+      );
+      expect(
+        find.byKey(const ValueKey('system-message-timestamp-alice')),
+        findsOneWidget,
+      );
+    });
+
     testWidgets('renders member_joined (self-join) system event', (
       tester,
     ) async {
@@ -1865,7 +2147,8 @@ void main() {
           },
         ),
       );
-      await tester.pumpAndSettle();
+      await tester.pump();
+      await tester.pump(const Duration(milliseconds: 200));
 
       expect(find.text('Alice is typing…'), findsOneWidget);
 
@@ -1884,7 +2167,15 @@ void main() {
       expect(decoration.border, isA<Border>());
       expect(
         tester.widget<Text>(find.text('Alice is typing…')).style?.color,
-        AppTheme.light().colorScheme.primary,
+        AppTheme.light().colorScheme.onSurfaceVariant,
+      );
+      expect(
+        tester.widget<Text>(find.text('Alice is typing…')).style?.fontStyle,
+        isNot(FontStyle.italic),
+      );
+      expect(
+        find.byKey(const ValueKey('channel-typing-shimmer')),
+        findsOneWidget,
       );
       expect(tester.widget<SmallAvatar>(find.byType(SmallAvatar)).size, 24);
     });
@@ -1909,7 +2200,8 @@ void main() {
           },
         ),
       );
-      await tester.pumpAndSettle();
+      await tester.pump();
+      await tester.pump(const Duration(milliseconds: 200));
 
       expect(find.text('Alice and Bob are typing…'), findsOneWidget);
     });
@@ -1939,10 +2231,39 @@ void main() {
           },
         ),
       );
-      await tester.pumpAndSettle();
+      await tester.pump();
+      await tester.pump(const Duration(milliseconds: 200));
 
       expect(find.text('Alice and 2 others are typing…'), findsOneWidget);
     });
+
+    testWidgets('keeps typing text static when motion is reduced', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [],
+          typing: [
+            TypingEntry(
+              pubkey: 'alice',
+              expiresAtMs: DateTime.now().millisecondsSinceEpoch + 8000,
+            ),
+          ],
+          users: {
+            'alice': const UserProfile(pubkey: 'alice', displayName: 'Alice'),
+          },
+          disableAnimations: true,
+        ),
+      );
+      await tester.pump();
+      await tester.pump();
+
+      expect(find.text('Alice is typing…'), findsOneWidget);
+      expect(
+        find.byKey(const ValueKey('channel-typing-shimmer')),
+        findsNothing,
+      );
+    });
   });
 
   group('Compose bar', () {
@@ -1953,7 +2274,7 @@ void main() {
       await tester.pumpAndSettle();
 
       expect(find.byType(TextField), findsNothing);
-      expect(find.byIcon(LucideIcons.arrowUp).hitTestable(), findsNothing);
+      expect(find.byIcon(LucideIcons.arrowUp).hitTestable(), findsOneWidget);
 
       await tester.tap(find.text('Message #general'));
       await tester.pumpAndSettle();
@@ -2334,7 +2655,10 @@ void main() {
         find.byKey(const ValueKey('thread-message-list')),
       );
       expect(threadList.reverse, isFalse);
-      expect(threadList.padding!.bottom, Grid.xs);
+      final threadComposerDockHeight = tester
+          .getSize(find.byKey(const ValueKey('thread-composer-dock')))
+          .height;
+      expect(threadList.padding!.bottom, Grid.xs + threadComposerDockHeight);
       final newestThreadGroup = tester.widget<Padding>(
         find.byKey(const ValueKey('thread-message-group-reply-next-day')),
       );
@@ -2361,6 +2685,96 @@ void main() {
       expect(oldestReplyY, lessThan(newestReplyY));
     });
 
+    testWidgets('thread keeps its tail above a growing composer dock', (
+      tester,
+    ) async {
+      tester.view.physicalSize = const Size(400, 800);
+      tester.view.devicePixelRatio = 1;
+      addTearDown(tester.view.resetPhysicalSize);
+      addTearDown(tester.view.resetDevicePixelRatio);
+
+      final rootEvent = _textMsg(
+        id: 'thread-root',
+        pubkey: 'alice',
+        content: 'Thread root',
+        createdAt: 1000,
+      );
+      final replies = [
+        for (var i = 0; i < 20; i++)
+          _textMsg(
+            id: 'reply-$i',
+            pubkey: 'bob',
+            content: 'Reply $i',
+            createdAt: 1100 + i,
+            extraTags: const [
+              ['e', 'thread-root', '', 'reply'],
+            ],
+          ),
+      ];
+
+      await tester.pumpWidget(
+        _buildTestable(
+          messages: [rootEvent],
+          threadReplies: {'thread-root': replies},
+          users: const {
+            'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+            'bob': UserProfile(pubkey: 'bob', displayName: 'Bob'),
+          },
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      final threadHead = formatTimeline([rootEvent]).single;
+      Navigator.of(tester.element(find.byType(ChannelDetailPage))).push(
+        MaterialPageRoute<void>(
+          builder: (_) => ThreadDetailPage(
+            threadHead: threadHead,
+            allMessages: [threadHead],
+            channelId: _channelId,
+            currentPubkey: 'self',
+            isMember: true,
+            isArchived: false,
+            initialMessageId: 'reply-19',
+          ),
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      final dock = find.byKey(const ValueKey('thread-composer-dock'));
+      final latestReply = find.byKey(
+        const ValueKey('thread-message-group-reply-19'),
+      );
+      final composerSurface = find.byKey(const ValueKey('composer-surface'));
+      final compactDockHeight = tester.getSize(dock).height;
+      expect(latestReply, findsOneWidget);
+      expect(
+        tester.getBottomLeft(latestReply).dy,
+        lessThanOrEqualTo(tester.getTopLeft(composerSurface).dy),
+      );
+
+      await tester.tap(find.text('Reply in thread…').hitTestable());
+      await tester.pumpAndSettle();
+
+      expect(tester.getSize(dock).height, greaterThan(compactDockHeight));
+      expect(latestReply, findsOneWidget);
+      expect(
+        tester.getBottomLeft(latestReply).dy,
+        lessThanOrEqualTo(tester.getTopLeft(composerSurface).dy),
+      );
+
+      // The dock size change above is separate from the later Scaffold
+      // viewport resize caused by the keyboard. Keep following the tail after
+      // that metrics change too.
+      tester.view.viewInsets = const FakeViewPadding(bottom: 300);
+      addTearDown(tester.view.reset);
+      await tester.pumpAndSettle();
+
+      expect(
+        tester.getBottomLeft(latestReply).dy,
+        lessThanOrEqualTo(tester.getTopLeft(composerSurface).dy),
+      );
+    });
+
     testWidgets(
       'initial thread hydration keeps the head visible instead of following the tail',
       (tester) async {
@@ -2429,6 +2843,81 @@ void main() {
       },
     );
 
+    testWidgets(
+      'deep-linking an older reply does not resume tail following on keyboard resize',
+      (tester) async {
+        tester.view.physicalSize = const Size(400, 800);
+        tester.view.devicePixelRatio = 1;
+        addTearDown(tester.view.resetPhysicalSize);
+        addTearDown(tester.view.resetDevicePixelRatio);
+        addTearDown(tester.view.reset);
+
+        final rootEvent = _textMsg(
+          id: 'thread-root',
+          pubkey: 'alice',
+          content: 'Thread root',
+          createdAt: 1000,
+        );
+        final replies = [
+          for (var i = 0; i < 30; i++)
+            _textMsg(
+              id: 'reply-$i',
+              pubkey: 'bob',
+              content: 'Reply $i',
+              createdAt: 1100 + i,
+              extraTags: const [
+                ['e', 'thread-root', '', 'reply'],
+              ],
+            ),
+        ];
+        final completer = Completer<List<NostrEvent>>();
+
+        await tester.pumpWidget(
+          _buildTestable(
+            messages: [rootEvent],
+            pendingThreadReplies: {'thread-root': completer.future},
+            users: const {
+              'alice': UserProfile(pubkey: 'alice', displayName: 'Alice'),
+              'bob': UserProfile(pubkey: 'bob', displayName: 'Bob'),
+            },
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        final threadHead = formatTimeline([rootEvent]).single;
+        final provisionalTarget = formatTimeline([replies[5]]).single;
+        Navigator.of(tester.element(find.byType(ChannelDetailPage))).push(
+          MaterialPageRoute<void>(
+            builder: (_) => ThreadDetailPage(
+              threadHead: threadHead,
+              allMessages: [threadHead, provisionalTarget],
+              channelId: _channelId,
+              currentPubkey: 'self',
+              isMember: true,
+              isArchived: false,
+              initialMessageId: 'reply-5',
+            ),
+          ),
+        );
+        await tester.pumpAndSettle();
+
+        completer.complete(replies);
+        await tester.pumpAndSettle();
+
+        final target = find.byKey(
+          const ValueKey('thread-message-group-reply-5'),
+        );
+        expect(target, findsOneWidget);
+
+        await tester.tap(find.text('Reply in thread…').hitTestable());
+        await tester.pumpAndSettle();
+        tester.view.viewInsets = const FakeViewPadding(bottom: 300);
+        await tester.pumpAndSettle();
+
+        expect(target, findsOneWidget);
+      },
+    );
+
     testWidgets('a reaction landing while the thread is open shows up there', (
       tester,
     ) async {
@@ -2664,9 +3153,12 @@ class _FakeMessagesNotifier extends ChannelMessagesNotifier {
   List<NostrEvent> _messages;
   bool _hasLoadedMessages;
 
-  _FakeMessagesNotifier(this._messages, {bool hasLoadedMessages = true})
-    : _hasLoadedMessages = hasLoadedMessages,
-      super(_channelId);
+  _FakeMessagesNotifier(
+    this._messages, {
+    String channelId = _channelId,
+    bool hasLoadedMessages = true,
+  }) : _hasLoadedMessages = hasLoadedMessages,
+       super(channelId);
 
   @override
   AsyncValue<List<NostrEvent>> build() => AsyncData(_messages);
@@ -2713,7 +3205,8 @@ class _ReconnectingRelaySession extends RelaySessionNotifier {
 
 class _FakeTypingNotifier extends ChannelTypingNotifier {
   final List<TypingEntry> _entries;
-  _FakeTypingNotifier(this._entries) : super(_channelId);
+  _FakeTypingNotifier(this._entries, {String channelId = _channelId})
+    : super(channelId);
 
   @override
   List<TypingEntry> build() => _entries;
@@ -2794,6 +3287,42 @@ class _FakeChannelActions extends ChannelActions {
   }
 }
 
+class _RecordingRelaySocket extends RelaySocket {
+  _RecordingRelaySocket()
+    : super(
+        wsUrl: 'wss://relay.example',
+        nsec: null,
+        onMessage: (_) {},
+        onConnected: () {},
+        onDisconnected: (_) {},
+      );
+
+  final List<List<dynamic>> messages = [];
+
+  @override
+  void send(List<dynamic> payload) => messages.add(payload);
+
+  @override
+  void dispose() {}
+}
+
+NostrFilter _filterForChannel(String channelId) => NostrFilter(
+  kinds: EventKind.channelEventKinds,
+  tags: {
+    '#h': [channelId],
+  },
+  limit: 0,
+);
+
+List<String> _replayedChannelIds(_RecordingRelaySocket socket) => socket
+    .messages
+    .where((message) => message.first == 'REQ')
+    .map(
+      (message) =>
+          ((message[2] as Map<String, dynamic>)['#h'] as List).single as String,
+    )
+    .toList();
+
 class _TestNavigatorObserver extends NavigatorObserver {
   int pushCount = 0;
 
diff --git a/mobile/test/features/channels/channels_page_test.dart b/mobile/test/features/channels/channels_page_test.dart
index 991db3b5cd..56032a5dbf 100644
--- a/mobile/test/features/channels/channels_page_test.dart
+++ b/mobile/test/features/channels/channels_page_test.dart
@@ -200,6 +200,80 @@ void main() {
     expect(tester.takeException(), isNull);
   });
 
+  testWidgets('section menu matches desktop labels, icons, and inset', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      buildTestable(
+        overrides: [
+          channelsProvider.overrideWith(() => _FakeNotifier(testChannels)),
+          channelSectionsProvider.overrideWith(
+            () => _FakeChannelSectionsNotifier(
+              const ChannelSectionStore(
+                sections: [
+                  ChannelSection(id: 'section-1', name: 'Design', order: 0),
+                ],
+              ),
+            ),
+          ),
+        ],
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    await tester.tap(find.byKey(const Key('section-menu-section-1')));
+    await tester.pumpAndSettle();
+
+    final popover = find.byKey(const Key('section-popover-section-1'));
+    expect(popover, findsOneWidget);
+    for (final label in [
+      'Rename section',
+      'Move up',
+      'Move down',
+      'Delete section',
+    ]) {
+      expect(
+        find.descendant(of: popover, matching: find.text(label)),
+        findsOne,
+      );
+    }
+    for (final icon in [
+      LucideIcons.pencil,
+      LucideIcons.arrowUp,
+      LucideIcons.arrowDown,
+      LucideIcons.trash2,
+    ]) {
+      expect(
+        find.descendant(of: popover, matching: find.byIcon(icon)),
+        findsOne,
+      );
+    }
+
+    final menuItems = tester.widgetList<PopupMenuItem<String>>(
+      find.descendant(
+        of: popover,
+        matching: find.byWidgetPredicate(
+          (widget) => widget is PopupMenuItem<String>,
+        ),
+      ),
+    );
+    expect(menuItems, hasLength(4));
+    for (final item in menuItems) {
+      expect(
+        item.padding,
+        const EdgeInsets.fromLTRB(Grid.xs, 0, Grid.twelve, 0),
+      );
+    }
+
+    final error = Theme.of(tester.element(popover)).colorScheme.error;
+    final deleteText = tester.widget<Text>(find.text('Delete section'));
+    final deleteIcon = tester.widget<Icon>(
+      find.descendant(of: popover, matching: find.byIcon(LucideIcons.trash2)),
+    );
+    expect(deleteText.style?.color, error);
+    expect(deleteIcon.color, error);
+  });
+
   testWidgets('aligns the top, section, row, and skeleton label columns', (
     tester,
   ) async {
diff --git a/mobile/test/features/channels/channels_provider_test.dart b/mobile/test/features/channels/channels_provider_test.dart
index 79be7a66f7..c128b9be5a 100644
--- a/mobile/test/features/channels/channels_provider_test.dart
+++ b/mobile/test/features/channels/channels_provider_test.dart
@@ -1,3 +1,5 @@
+import 'dart:async';
+
 import 'package:flutter/widgets.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:hooks_riverpod/hooks_riverpod.dart';
@@ -52,6 +54,174 @@ void main() {
     },
   );
 
+  test(
+    'refreshing an unchanged channel set issues zero new live REQs',
+    () async {
+      final session = _FakeRelaySession(
+        memberships: [
+          _membership(_channelA, myPk),
+          _membership(_channelB, myPk),
+        ],
+        metadata: [
+          _meta(id: _channelA, name: 'general'),
+          _meta(id: _channelB, name: 'random'),
+        ],
+      );
+      final container = _buildContainer(session: session);
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      final initialSubscribeCount = session.totalSubscribeCount;
+
+      await container.read(channelsProvider.notifier).refresh();
+
+      expect(session.totalSubscribeCount, initialSubscribeCount);
+      expect(session.unsubscribeCount, 0);
+      expect(session.subscribeFilters, hasLength(2));
+    },
+  );
+
+  test(
+    'live subscription diff only removes and adds changed channels',
+    () async {
+      final session = _FakeRelaySession(
+        memberships: [
+          _membership(_channelA, myPk),
+          _membership(_channelB, myPk),
+        ],
+        metadata: [
+          _meta(id: _channelA, name: 'general'),
+          _meta(id: _channelB, name: 'random'),
+        ],
+      );
+      final container = _buildContainer(session: session);
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      session.memberships = [
+        _membership(_channelB, myPk),
+        _membership(_channelD, myPk),
+      ];
+      session.metadata = [
+        _meta(id: _channelB, name: 'random'),
+        _meta(id: _channelD, name: 'support'),
+      ];
+
+      await container.read(channelsProvider.notifier).refresh();
+
+      expect(session.totalSubscribeCount, 3);
+      expect(session.unsubscribeCount, 1);
+      expect(
+        session.subscribeFilters
+            .map((filter) => filter.tags['#h']!.single)
+            .toSet(),
+        {_channelB, _channelD},
+      );
+    },
+  );
+
+  test(
+    'empty channel refresh removes every retained live subscription',
+    () async {
+      final session = _FakeRelaySession(
+        memberships: [
+          _membership(_channelA, myPk),
+          _membership(_channelB, myPk),
+        ],
+        metadata: [
+          _meta(id: _channelA, name: 'general'),
+          _meta(id: _channelB, name: 'random'),
+        ],
+      );
+      final container = _buildContainer(session: session);
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      session.memberships = [];
+      session.metadata = [];
+
+      await container.read(channelsProvider.notifier).refresh();
+
+      expect(session.activeChannels, isEmpty);
+      expect(session.activeSubscriptionCount, 0);
+      expect(session.unsubscribeCount, 2);
+    },
+  );
+
+  test(
+    'overlapping refreshes retain one live subscription per desired channel',
+    () async {
+      final session = _FakeRelaySession(
+        memberships: [
+          _membership(_channelA, myPk),
+          _membership(_channelB, myPk),
+        ],
+        metadata: [
+          _meta(id: _channelA, name: 'general'),
+          _meta(id: _channelB, name: 'random'),
+        ],
+      );
+      final container = _buildContainer(session: session);
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      session.pauseNextSubscribe();
+      session.memberships = [
+        _membership(_channelA, myPk),
+        _membership(_channelB, myPk),
+        _membership(_channelD, myPk),
+      ];
+      session.metadata = [
+        _meta(id: _channelA, name: 'general'),
+        _meta(id: _channelB, name: 'random'),
+        _meta(id: _channelD, name: 'support'),
+      ];
+
+      final firstRefresh = container.read(channelsProvider.notifier).refresh();
+      await session.nextSubscribeStarted;
+      final secondRefresh = container.read(channelsProvider.notifier).refresh();
+      session.resumePausedSubscribe();
+      await Future.wait([firstRefresh, secondRefresh]);
+
+      expect(session.activeChannels, {_channelA, _channelB, _channelD});
+      expect(session.activeSubscriptionCount, 3);
+    },
+  );
+
+  test(
+    'community switch replaces retained live subscriptions on the new relay',
+    () async {
+      final session = _FakeRelaySession(
+        memberships: [_membership(_channelA, myPk)],
+        metadata: [_meta(id: _channelA, name: 'general')],
+      );
+      final container = _buildContainer(session: session);
+      addTearDown(container.dispose);
+
+      await container.read(channelsProvider.future);
+      expect(session.activeChannels, {_channelA});
+
+      session.setStatus(SessionStatus.disconnected);
+      session.memberships = [_membership(_channelB, myPk)];
+      session.metadata = [_meta(id: _channelB, name: 'random')];
+      container
+          .read(relayConfigProvider.notifier)
+          .update(baseUrl: 'https://new-community.example');
+      await Future<void>.delayed(Duration.zero);
+      session.setStatus(SessionStatus.connected);
+      await container.read(channelsProvider.future);
+      await _waitUntil(
+        () =>
+            session.activeChannels.length == 1 &&
+            session.activeChannels.contains(_channelB),
+      );
+
+      expect(session.activeChannels, {_channelB});
+      expect(session.activeSubscriptionCount, 1);
+      expect(session.unsubscribeCount, 1);
+    },
+  );
+
   test('live channel events update channel lastMessageAt', () async {
     final session = _FakeRelaySession(
       memberships: [_membership(_channelA, myPk)],
@@ -423,6 +593,14 @@ ProviderContainer _buildContainer({required _FakeRelaySession session}) {
   );
 }
 
+Future<void> _waitUntil(bool Function() predicate) async {
+  for (var i = 0; i < 100; i++) {
+    if (predicate()) return;
+    await Future<void>.delayed(Duration.zero);
+  }
+  fail('Timed out waiting for asynchronous provider work');
+}
+
 /// Fake [RelaySessionNotifier] that returns canned events from [fetchHistory]
 /// and records subscribe calls.
 class _FakeRelaySession extends RelaySessionNotifier {
@@ -440,8 +618,40 @@ class _FakeRelaySession extends RelaySessionNotifier {
 
   final List<NostrFilter> historyFilters = [];
   final List<NostrFilter> subscribeFilters = [];
-  final List<void Function(NostrEvent)> _listeners = [];
+  final Map<int, (NostrFilter, void Function(NostrEvent))> _subscriptions = {};
+  int _nextSubscriptionKey = 0;
+  Completer<void>? _pausedSubscribe;
+  Completer<void>? _subscribeStarted;
   int unsubscribeCount = 0;
+  int totalSubscribeCount = 0;
+
+  Set<String> get activeChannels => {
+    for (final (filter, _) in _subscriptions.values) ?filter.tags['#h']?.single,
+  };
+
+  int get activeSubscriptionCount => _subscriptions.length;
+
+  Future<void> get nextSubscribeStarted async {
+    final started = _subscribeStarted;
+    if (started == null) {
+      throw StateError('No paused subscription is pending');
+    }
+    await started.future;
+  }
+
+  void pauseNextSubscribe() {
+    if (_pausedSubscribe != null) {
+      throw StateError('A subscription is already paused');
+    }
+    _pausedSubscribe = Completer<void>();
+    _subscribeStarted = Completer<void>();
+  }
+
+  void resumePausedSubscribe() {
+    final paused = _pausedSubscribe;
+    if (paused == null) throw StateError('No subscription is paused');
+    paused.complete();
+  }
 
   @override
   SessionState build() => const SessionState(status: SessionStatus.connected);
@@ -483,12 +693,22 @@ class _FakeRelaySession extends RelaySessionNotifier {
     void Function(NostrEvent) onEvent, {
     void Function(String message)? onClosed,
   }) async {
+    totalSubscribeCount++;
     subscribeFilters.add(filter);
-    _listeners.add(onEvent);
+    final paused = _pausedSubscribe;
+    if (paused != null) {
+      _subscribeStarted!.complete();
+      await paused.future;
+      _pausedSubscribe = null;
+      _subscribeStarted = null;
+    }
+    final subscriptionKey = ++_nextSubscriptionKey;
+    _subscriptions[subscriptionKey] = (filter, onEvent);
     return () {
+      final subscription = _subscriptions.remove(subscriptionKey);
+      if (subscription == null) return;
       unsubscribeCount++;
-      subscribeFilters.remove(filter);
-      _listeners.remove(onEvent);
+      subscribeFilters.remove(subscription.$1);
     };
   }
 
@@ -498,7 +718,7 @@ class _FakeRelaySession extends RelaySessionNotifier {
 
   /// Emit a live event to all subscribers.
   void emit(NostrEvent event) {
-    for (final listener in List.of(_listeners)) {
+    for (final (_, listener) in List.of(_subscriptions.values)) {
       listener(event);
     }
   }
diff --git a/mobile/test/features/channels/compose_bar_test.dart b/mobile/test/features/channels/compose_bar_test.dart
index 919d4039eb..7dd2c2b608 100644
--- a/mobile/test/features/channels/compose_bar_test.dart
+++ b/mobile/test/features/channels/compose_bar_test.dart
@@ -23,6 +23,8 @@ import 'package:buzz/shared/custom_emoji/custom_emoji_provider.dart';
 import 'package:buzz/shared/mentions/agent_identity_provider.dart';
 import 'package:buzz/shared/relay/relay.dart';
 import 'package:buzz/shared/theme/theme.dart';
+import 'package:buzz/shared/widgets/anchored_popover_menu.dart';
+import 'package:buzz/shared/widgets/mobile_tab_footer_backdrop.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 
 final _pngBytes = Uint8List.fromList([
@@ -392,6 +394,152 @@ void main() {
   });
 
   group('ComposeBar', () {
+    testWidgets('starts compact and grows to the full-width composer', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildComposeBar(
+          uploadService: _testUploadService(nostr.Keys.generate().nsec),
+          onSend:
+              (
+                content,
+                mentionPubkeys, {
+                mediaTags = const <List<String>>[],
+              }) async {},
+        ),
+      );
+
+      expect(find.byType(TextField), findsNothing);
+      expect(find.byTooltip('Add attachment').hitTestable(), findsOneWidget);
+      expect(find.byIcon(LucideIcons.arrowUp).hitTestable(), findsOneWidget);
+      expect(find.byKey(const ValueKey('composer-footer-gradient')), findsOne);
+      final composerBackdrop = find.descendant(
+        of: find.byKey(const ValueKey('composer-footer-gradient')),
+        matching: find.byType(MobileTabFooterBackdrop),
+      );
+      expect(composerBackdrop, findsOneWidget);
+      expect(
+        tester.getSize(composerBackdrop).height,
+        mobileTabFooterBackdropHeight(tester.element(composerBackdrop)),
+      );
+      final compactDecoration =
+          tester
+                  .widget<Container>(
+                    find.byKey(const ValueKey('composer-surface')),
+                  )
+                  .decoration
+              as BoxDecoration;
+      expect(
+        compactDecoration.borderRadius,
+        BorderRadius.circular(Radii.dialog + Grid.quarter),
+      );
+      final compactWidth = tester
+          .getSize(find.byKey(const ValueKey('composer-width-transition')))
+          .width;
+
+      await _expandComposer(tester);
+
+      final expandedWidth = tester
+          .getSize(find.byKey(const ValueKey('composer-width-transition')))
+          .width;
+      final expandedDecoration =
+          tester
+                  .widget<Container>(
+                    find.byKey(const ValueKey('composer-surface')),
+                  )
+                  .decoration
+              as BoxDecoration;
+      expect(compactWidth, closeTo(expandedWidth * 0.85, 0.5));
+      expect(
+        expandedDecoration.borderRadius,
+        BorderRadius.circular(Radii.dialog),
+      );
+      expect(find.byType(TextField), findsOneWidget);
+      expect(find.byIcon(LucideIcons.atSign), findsOneWidget);
+      expect(find.byIcon(LucideIcons.hash), findsOneWidget);
+      expect(find.byIcon(LucideIcons.smilePlus), findsOneWidget);
+      expect(find.byIcon(LucideIcons.aLargeSmall), findsOneWidget);
+    });
+
+    testWidgets('returns to the compact capsule when the keyboard drops', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildComposeBar(
+          uploadService: _testUploadService(nostr.Keys.generate().nsec),
+          onSend:
+              (
+                content,
+                mentionPubkeys, {
+                mediaTags = const <List<String>>[],
+              }) async {},
+        ),
+      );
+      await _expandComposer(tester);
+      final focusNode = tester
+          .widget<TextField>(find.byType(TextField))
+          .focusNode!;
+      expect(focusNode.hasFocus, isTrue);
+      tester.view.viewInsets = const FakeViewPadding(bottom: 300);
+      addTearDown(tester.view.reset);
+      await tester.pump();
+
+      tester.view.viewInsets = FakeViewPadding.zero;
+      await tester.pumpAndSettle();
+
+      expect(find.byType(TextField), findsNothing);
+      expect(focusNode.hasFocus, isFalse);
+      final compactDecoration =
+          tester
+                  .widget<Container>(
+                    find.byKey(const ValueKey('composer-surface')),
+                  )
+                  .decoration
+              as BoxDecoration;
+      expect(
+        compactDecoration.borderRadius,
+        BorderRadius.circular(Radii.dialog + Grid.quarter),
+      );
+
+      await tester.tap(find.text('Message\u2026'));
+      await tester.pumpAndSettle();
+      expect(find.byType(TextField), findsOneWidget);
+      expect(
+        tester.widget<TextField>(find.byType(TextField)).focusNode!.hasFocus,
+        isTrue,
+      );
+    });
+
+    testWidgets('attachment control responds while the composer is expanding', (
+      tester,
+    ) async {
+      final previousPlatform = debugDefaultTargetPlatformOverride;
+      debugDefaultTargetPlatformOverride = TargetPlatform.android;
+      try {
+        await tester.pumpWidget(
+          _buildComposeBar(
+            uploadService: _testUploadService(nostr.Keys.generate().nsec),
+            onSend:
+                (
+                  content,
+                  mentionPubkeys, {
+                  mediaTags = const <List<String>>[],
+                }) async {},
+          ),
+        );
+
+        await tester.tap(find.text('Message\u2026'));
+        await tester.pump();
+        await tester.pump(const Duration(milliseconds: 80));
+        await tester.tap(find.byTooltip('Add attachment').hitTestable());
+        await tester.pumpAndSettle();
+
+        expect(find.byKey(const ValueKey('attachment-menu')), findsOneWidget);
+      } finally {
+        debugDefaultTargetPlatformOverride = previousPlatform;
+      }
+    });
+
     testWidgets('mounted composer does not carry draft text across an in-place '
         'identity switch', (tester) async {
       final keysA = nostr.Keys.generate();
@@ -492,6 +640,94 @@ void main() {
 
       expect(textField.controller!.text, 'hello :meow:world');
       expect(textField.controller!.selection.baseOffset, 12);
+      expect(find.byType(TextField), findsOneWidget);
+      expect(textField.focusNode!.hasFocus, isTrue);
+    });
+
+    testWidgets('composer controls use selection haptics', (tester) async {
+      final hapticCalls = <MethodCall>[];
+      TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+          .setMockMethodCallHandler(SystemChannels.platform, (call) async {
+            if (call.method == 'HapticFeedback.vibrate') {
+              hapticCalls.add(call);
+            }
+            return null;
+          });
+      addTearDown(
+        () => TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+            .setMockMethodCallHandler(SystemChannels.platform, null),
+      );
+
+      await tester.pumpWidget(
+        _buildComposeBar(
+          uploadService: _testUploadService(nostr.Keys.generate().nsec),
+          onSend:
+              (
+                content,
+                mentionPubkeys, {
+                mediaTags = const <List<String>>[],
+              }) async {},
+        ),
+      );
+      await _expandComposer(tester);
+      hapticCalls.clear();
+
+      await tester.tap(find.byIcon(LucideIcons.atSign));
+      tester.widget<TextField>(find.byType(TextField)).controller!.clear();
+      await tester.pump();
+      await tester.tap(find.byIcon(LucideIcons.hash));
+      await tester.pump();
+      await tester.tap(find.byIcon(LucideIcons.aLargeSmall));
+      await tester.pumpAndSettle();
+      await tester.tap(find.byIcon(LucideIcons.bold));
+      await tester.pump();
+      await tester.tap(find.byTooltip('Close formatting'));
+      await tester.pumpAndSettle();
+      await tester.tap(find.byTooltip('Add attachment'));
+      await tester.pumpAndSettle();
+
+      expect(hapticCalls, hasLength(6));
+      expect(
+        hapticCalls.every(
+          (call) => call.arguments == 'HapticFeedbackType.selectionClick',
+        ),
+        isTrue,
+      );
+    });
+
+    testWidgets('composer suggestions use the shared popover treatment', (
+      tester,
+    ) async {
+      await tester.pumpWidget(
+        _buildComposeBar(
+          uploadService: _testUploadService(nostr.Keys.generate().nsec),
+          channels: [_makeChannel(name: 'general', channelType: 'stream')],
+          onSend:
+              (
+                content,
+                mentionPubkeys, {
+                mediaTags = const <List<String>>[],
+              }) async {},
+        ),
+      );
+      await _expandComposer(tester);
+      await tester.tap(find.byIcon(LucideIcons.hash));
+      await tester.pumpAndSettle();
+
+      final surface = find.byKey(const ValueKey('channel-suggestions-popover'));
+      final material = tester.widget<Material>(surface);
+      final shape = material.shape! as RoundedRectangleBorder;
+      expect(shape.borderRadius, BorderRadius.circular(Radii.popover));
+      expect(shape.side.color, Colors.black.withValues(alpha: 0.04));
+      expect(material.elevation, appPopoverElevation);
+      expect(
+        material.shadowColor,
+        appPopoverShadowColor(tester.element(surface)),
+      );
+      expect(
+        tester.widget<Text>(find.text('general')).style?.fontFamily,
+        'Inter',
+      );
     });
 
     testWidgets('native All Photos picker failures show an error', (
@@ -595,6 +831,60 @@ void main() {
       }
     });
 
+    testWidgets('leaving a focused composer dismisses the native keyboard', (
+      tester,
+    ) async {
+      final previousPlatform = debugDefaultTargetPlatformOverride;
+      debugDefaultTargetPlatformOverride = TargetPlatform.iOS;
+      var dismissCalls = 0;
+      _setMockNativeAttachmentPopoverHandler((call) async {
+        switch (call.method) {
+          case 'isSupported':
+          case 'present':
+            return true;
+          case 'dismiss':
+            dismissCalls += 1;
+            return null;
+        }
+        return null;
+      });
+
+      try {
+        await tester.pumpWidget(
+          _buildComposeBar(
+            uploadService: _testUploadService(nostr.Keys.generate().nsec),
+            onSend:
+                (
+                  content,
+                  mentionPubkeys, {
+                  mediaTags = const <List<String>>[],
+                }) async {},
+          ),
+        );
+
+        await _expandComposer(tester);
+        final focusNode = tester
+            .widget<TextField>(find.byType(TextField))
+            .focusNode!;
+        expect(focusNode.hasFocus, isTrue);
+
+        await tester.tap(find.byTooltip('Add attachment').hitTestable());
+        await tester.pumpAndSettle();
+        expect(focusNode.hasFocus, isTrue);
+
+        await tester.pumpWidget(const SizedBox.shrink());
+        await tester.pumpAndSettle();
+
+        expect(focusNode.hasFocus, isFalse);
+        expect(dismissCalls, 1);
+      } finally {
+        await _sendNativeAttachmentPopoverCall(tester, 'dismissed');
+        await tester.pumpWidget(const SizedBox.shrink());
+        _setMockNativeAttachmentPopoverHandler(null);
+        debugDefaultTargetPlatformOverride = previousPlatform;
+      }
+    });
+
     testWidgets(
       'unsupported iOS attachment popover unfocuses before fallback menu',
       (tester) async {
@@ -1191,6 +1481,10 @@ void main() {
         ),
       );
 
+      final compactComposerWidth = tester
+          .getSize(find.byKey(const ValueKey('composer-width-transition')))
+          .width;
+
       await _openAttachmentMenu(tester);
       await tester.tap(find.text('Photos'));
       await tester.pumpAndSettle();
@@ -1201,6 +1495,12 @@ void main() {
       );
       expect(find.byTooltip('Back to attachment options'), findsWidgets);
       expect(find.text('All photos'), findsOneWidget);
+      expect(
+        tester
+            .getSize(find.byKey(const ValueKey('attachment-surface-popover')))
+            .width,
+        closeTo(compactComposerWidth / 0.85, 0.5),
+      );
 
       await tester.tap(find.byKey(const ValueKey('recent-photo-two')));
       await tester.pumpAndSettle();
@@ -1265,12 +1565,22 @@ void main() {
       await _openAttachmentMenu(tester);
 
       final menu = find.byKey(const ValueKey('attachment-menu'));
+      final surface = find.byKey(const ValueKey('attachment-surface-popover'));
       final rows = [
         for (final label in ['camera', 'photos', 'video', 'files'])
           find.byKey(ValueKey('attachment-menu-item-$label')),
       ];
       final menuRect = tester.getRect(menu);
 
+      final material = tester.widget<Material>(surface);
+      final shape = material.shape! as RoundedRectangleBorder;
+      expect(shape.borderRadius, BorderRadius.circular(Radii.popover));
+      expect(shape.side.color, Colors.black.withValues(alpha: 0.04));
+      expect(material.elevation, appPopoverElevation);
+      expect(
+        material.shadowColor,
+        appPopoverShadowColor(tester.element(surface)),
+      );
       expect(menuRect.size, const Size(216, 264));
       for (final row in rows) {
         expect(tester.getSize(row).height, 52);
@@ -1280,6 +1590,7 @@ void main() {
       for (final label in ['Camera', 'Photos', 'Video', 'Files']) {
         final text = tester.widget<Text>(find.text(label));
         expect(text.style?.fontSize, 20);
+        expect(text.style?.fontFamily, 'Inter');
       }
       final icons = [
         for (final label in ['camera', 'photos', 'video', 'files'])
@@ -1319,6 +1630,48 @@ void main() {
       }
     });
 
+    testWidgets('tapping outside dismisses the Android attachment menu', (
+      tester,
+    ) async {
+      final previousPlatform = debugDefaultTargetPlatformOverride;
+      debugDefaultTargetPlatformOverride = TargetPlatform.android;
+      try {
+        await tester.pumpWidget(
+          _buildComposeBar(
+            uploadService: _testUploadService(nostr.Keys.generate().nsec),
+            onSend:
+                (
+                  content,
+                  mentionPubkeys, {
+                  mediaTags = const <List<String>>[],
+                }) async {},
+          ),
+        );
+
+        await _openAttachmentMenu(tester);
+        expect(find.byKey(const ValueKey('attachment-menu')), findsOneWidget);
+        expect(
+          find.byKey(const ValueKey('attachment-dismiss-barrier')),
+          findsOneWidget,
+        );
+
+        await tester.tapAt(const Offset(24, 24));
+        await tester.pumpAndSettle();
+
+        expect(find.byKey(const ValueKey('attachment-menu')), findsNothing);
+        expect(
+          find.byKey(const ValueKey('attachment-dismiss-barrier')),
+          findsNothing,
+        );
+        expect(
+          find.byKey(const ValueKey('attachment-trigger-closed')).hitTestable(),
+          findsOneWidget,
+        );
+      } finally {
+        debugDefaultTargetPlatformOverride = previousPlatform;
+      }
+    });
+
     testWidgets(
       'attachment menu grows rows and scrolls for accessibility text',
       (tester) async {
@@ -1376,6 +1729,9 @@ void main() {
                 }) async {},
           ),
         );
+        final compactComposerWidth = tester
+            .getSize(find.byKey(const ValueKey('composer-width-transition')))
+            .width;
 
         await _openAttachmentMenu(tester);
         await tester.tap(find.text('Camera'));
@@ -1397,6 +1753,12 @@ void main() {
           find.byKey(const ValueKey('camera-initialization-ready')),
           findsOneWidget,
         );
+        expect(
+          tester
+              .getSize(find.byKey(const ValueKey('attachment-surface-popover')))
+              .width,
+          closeTo(compactComposerWidth / 0.85, 0.5),
+        );
       } finally {
         debugDefaultTargetPlatformOverride = previousPlatform;
       }
diff --git a/mobile/test/shared/emoji/native_emoji_glyph_test.dart b/mobile/test/shared/emoji/native_emoji_glyph_test.dart
new file mode 100644
index 0000000000..435423905f
--- /dev/null
+++ b/mobile/test/shared/emoji/native_emoji_glyph_test.dart
@@ -0,0 +1,37 @@
+import 'package:buzz/shared/emoji/native_emoji_glyph.dart';
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('lifts the glyph one logical pixel on iOS', (tester) async {
+    debugDefaultTargetPlatformOverride = TargetPlatform.iOS;
+    try {
+      await tester.pumpWidget(
+        const MaterialApp(
+          home: Center(child: NativeEmojiGlyph(emoji: '🔥', size: 24)),
+        ),
+      );
+
+      final transform = tester.widget<Transform>(find.byType(Transform));
+      expect(transform.transform.getTranslation().y, -1);
+    } finally {
+      debugDefaultTargetPlatformOverride = null;
+    }
+  });
+
+  testWidgets('keeps the glyph unshifted on Android', (tester) async {
+    debugDefaultTargetPlatformOverride = TargetPlatform.android;
+    try {
+      await tester.pumpWidget(
+        const MaterialApp(
+          home: Center(child: NativeEmojiGlyph(emoji: '🔥', size: 24)),
+        ),
+      );
+
+      expect(find.byType(Transform), findsNothing);
+    } finally {
+      debugDefaultTargetPlatformOverride = null;
+    }
+  });
+}
diff --git a/mobile/test/shared/relay/relay_closed_policy_test.dart b/mobile/test/shared/relay/relay_closed_policy_test.dart
new file mode 100644
index 0000000000..ff78ea89ef
--- /dev/null
+++ b/mobile/test/shared/relay/relay_closed_policy_test.dart
@@ -0,0 +1,45 @@
+import 'package:buzz/shared/relay/relay.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  group('classifyRelayClosed', () {
+    const cases = {
+      'rate-limited: quota exceeded; retry in 4s': RelayClosedClass.rateLimited,
+      'rate-limited: too many concurrent requests':
+          RelayClosedClass.rateLimited,
+      'restricted: access revoked': RelayClosedClass.terminal,
+      'auth-required: verification failed': RelayClosedClass.terminal,
+      'blocked: community policy': RelayClosedClass.terminal,
+      'invalid: malformed filter': RelayClosedClass.terminal,
+      'pow: insufficient work': RelayClosedClass.terminal,
+      'duplicate: subscription already exists': RelayClosedClass.terminal,
+      'unsupported: filter extension': RelayClosedClass.terminal,
+      'error: mixed search and channel filter': RelayClosedClass.terminal,
+      'error: too many subscriptions': RelayClosedClass.terminal,
+      'error: relay temporarily unavailable': RelayClosedClass.retryable,
+      'subscription closed by relay': RelayClosedClass.retryable,
+    };
+
+    for (final entry in cases.entries) {
+      test(entry.key, () {
+        expect(classifyRelayClosed(entry.key), entry.value);
+      });
+    }
+  });
+
+  test('parseRateLimitRetrySeconds handles canonical and absent hints', () {
+    expect(
+      parseRateLimitRetrySeconds('rate-limited: quota exceeded; retry in 17s'),
+      17,
+    );
+    expect(parseRateLimitRetrySeconds('RETRY IN 2S'), 2);
+    expect(parseRateLimitRetrySeconds('retry in 0s'), 0);
+    expect(parseRateLimitRetrySeconds('retry in 999999s'), 999999);
+    final oversizedHint = List.filled(1000, '9').join();
+    expect(parseRateLimitRetrySeconds('retry in ${oversizedHint}s'), isNull);
+    expect(
+      parseRateLimitRetrySeconds('rate-limited: too many concurrent requests'),
+      isNull,
+    );
+  });
+}
diff --git a/mobile/test/shared/relay/relay_rate_limit_gate_test.dart b/mobile/test/shared/relay/relay_rate_limit_gate_test.dart
new file mode 100644
index 0000000000..811d439572
--- /dev/null
+++ b/mobile/test/shared/relay/relay_rate_limit_gate_test.dart
@@ -0,0 +1,118 @@
+import 'dart:async';
+
+import 'package:buzz/shared/relay/relay.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  test('uses the default for absent and non-positive hints', () {
+    var now = DateTime.utc(2026);
+    final timers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => now,
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+
+    gate.activate(null);
+    expect(gate.remainingMs(), 10000);
+    expect(timers.single.duration, const Duration(seconds: 10));
+
+    now = now.add(const Duration(seconds: 11));
+    gate.activate(0);
+    expect(timers.last.duration, const Duration(seconds: 10));
+  });
+
+  test('clamps large hints to five minutes', () {
+    final timers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime.utc(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+
+    gate.activate(999999);
+
+    expect(timers.single.duration, const Duration(seconds: 300));
+    expect(gate.remainingMs(), 300000);
+  });
+
+  test('overlapping activations only extend the active window', () async {
+    var now = DateTime.utc(2026);
+    final timers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => now,
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+
+    gate.activate(30);
+    final wait = gate.wait();
+    final firstTimer = timers.single;
+
+    now = now.add(const Duration(seconds: 5));
+    gate.activate(10);
+    expect(timers, hasLength(1));
+    expect(gate.remainingMs(), 25000);
+
+    gate.activate(40);
+    expect(timers, hasLength(2));
+    expect(firstTimer.isActive, isFalse);
+    expect(gate.remainingMs(), 40000);
+
+    timers.last.fire();
+    await wait;
+    expect(gate.isActive, isFalse);
+    expect(gate.remainingMs(), 0);
+  });
+
+  test('reset releases waiters and cancels the active timer', () async {
+    final timers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+
+    gate.activate(20);
+    final wait = gate.wait();
+    gate.reset();
+
+    await wait;
+    expect(timers.single.isActive, isFalse);
+    expect(gate.isActive, isFalse);
+  });
+}
+
+class _ManualTimer implements Timer {
+  _ManualTimer(this.duration, this._callback);
+
+  final Duration duration;
+  final void Function() _callback;
+  bool _active = true;
+
+  void fire() {
+    if (!_active) return;
+    _active = false;
+    _callback();
+  }
+
+  @override
+  void cancel() => _active = false;
+
+  @override
+  bool get isActive => _active;
+
+  @override
+  int get tick => _active ? 0 : 1;
+}
diff --git a/mobile/test/shared/relay/relay_session_test.dart b/mobile/test/shared/relay/relay_session_test.dart
index 4647c05e07..826e234400 100644
--- a/mobile/test/shared/relay/relay_session_test.dart
+++ b/mobile/test/shared/relay/relay_session_test.dart
@@ -105,6 +105,178 @@ void main() {
     );
   });
 
+  test('queryRelay arms the rate-limit gate from a 429 retry hint', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    const body = '{"error":"rate-limited: quota exceeded; retry in 4s"}';
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async => http.Response(body, 429)),
+    );
+    addTearDown(harness.container.dispose);
+
+    await expectLater(
+      harness.session.queryRelay(const []),
+      throwsA(
+        isA<RelayException>()
+            .having((error) => error.statusCode, 'statusCode', 429)
+            .having((error) => error.body, 'body', body),
+      ),
+    );
+
+    expect(gateTimers.single.duration, const Duration(seconds: 4));
+    expect(gate.isActive, isTrue);
+  });
+
+  test('queryRelay uses the default gate for a 503 without a hint', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    const body = '{"error":"rate-limited: shared admission unavailable"}';
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async => http.Response(body, 503)),
+    );
+    addTearDown(harness.container.dispose);
+
+    await expectLater(
+      harness.session.queryRelay(const []),
+      throwsA(
+        isA<RelayException>()
+            .having((error) => error.statusCode, 'statusCode', 503)
+            .having((error) => error.body, 'body', body),
+      ),
+    );
+
+    expect(gateTimers.single.duration, const Duration(seconds: 10));
+    expect(gate.isActive, isTrue);
+  });
+
+  test('queryRelay does not arm the gate for a non-rate-limit error', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    const body = '{"error":"not found"}';
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async => http.Response(body, 404)),
+    );
+    addTearDown(harness.container.dispose);
+
+    await expectLater(
+      harness.session.queryRelay(const []),
+      throwsA(
+        isA<RelayException>()
+            .having((error) => error.statusCode, 'statusCode', 404)
+            .having((error) => error.body, 'body', body),
+      ),
+    );
+
+    expect(gateTimers, isEmpty);
+    expect(gate.isActive, isFalse);
+  });
+
+  test('queryRelay preserves an error with an unrecognized body', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    const body = 'upstream unavailable';
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async => http.Response(body, 503)),
+    );
+    addTearDown(harness.container.dispose);
+
+    await expectLater(
+      harness.session.queryRelay(const []),
+      throwsA(
+        isA<RelayException>()
+            .having((error) => error.statusCode, 'statusCode', 503)
+            .having((error) => error.body, 'body', body),
+      ),
+    );
+
+    expect(gateTimers, isEmpty);
+    expect(gate.isActive, isFalse);
+  });
+
+  test('queryRelay success does not arm the rate-limit gate', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async => http.Response('[]', 200)),
+    );
+    addTearDown(harness.container.dispose);
+
+    expect(await harness.session.queryRelay(const []), isEmpty);
+    expect(gateTimers, isEmpty);
+    expect(gate.isActive, isFalse);
+  });
+
+  test('queryRelay does not wait for an active rate-limit gate', () async {
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: _ManualTimer.new,
+    );
+    var requestCount = 0;
+    final harness = _queryHarness(
+      gate: gate,
+      client: http_testing.MockClient((_) async {
+        requestCount++;
+        return http.Response('[]', 200);
+      }),
+    );
+    addTearDown(harness.container.dispose);
+    // Let the provider's build/dispose churn settle before arming: reading the
+    // notifier registers `ref.onDispose(_dispose)`, and `_dispose` resets the
+    // shared gate. Arming before that settles leaves the gate disarmed by the
+    // time the request runs, which makes this row pass for the wrong reason.
+    await pumpEventQueue();
+    gate.activate(4);
+    expect(gate.isActive, isTrue);
+
+    final query = harness.session.queryRelay(const []);
+    await Future<void>.delayed(Duration.zero);
+
+    expect(requestCount, 1);
+    expect(await query, isEmpty);
+    // Still armed: the read must neither wait on the gate nor clear it.
+    expect(gate.isActive, isTrue);
+  });
+
   test(
     'history timeout rejects instead of returning partial empty data',
     () async {
@@ -260,6 +432,120 @@ void main() {
     expect(session.state.status, SessionStatus.disconnected);
   });
 
+  test(
+    'resume reconnects a stale connected session after a long pause',
+    () async {
+      final sockets = <_ControlledRelaySocket>[];
+      final keychain = nostr.Keys.generate();
+      var now = DateTime(2026, 8, 2, 12);
+      final session = RelaySessionNotifier(
+        now: () => now,
+        socketFactory:
+            ({
+              required wsUrl,
+              required nsec,
+              required onMessage,
+              required onConnected,
+              required onDisconnected,
+            }) {
+              final socket = _ControlledRelaySocket(
+                wsUrl: wsUrl,
+                nsec: nsec,
+                onMessage: onMessage,
+                onConnected: onConnected,
+                onDisconnected: onDisconnected,
+              );
+              sockets.add(socket);
+              return socket;
+            },
+      );
+      final container = ProviderContainer(
+        overrides: [
+          relaySessionProvider.overrideWith(() => session),
+          relayConfigProvider.overrideWith(
+            () => _FakeRelayConfigNotifier(
+              baseUrl: 'https://relay.example',
+              nsec: keychain.nsec,
+            ),
+          ),
+          authProvider.overrideWith(() => _AuthenticatedAuthNotifier()),
+        ],
+      );
+      addTearDown(container.dispose);
+      await container.read(authProvider.future);
+      final subscription = container.listen(relaySessionProvider, (_, _) {});
+      addTearDown(subscription.close);
+      await Future<void>.delayed(Duration.zero);
+      sockets.single.connectSuccessfully();
+
+      session.onAppPaused();
+      now = now.add(const Duration(minutes: 5));
+      session.onAppResumed();
+      await Future<void>.delayed(Duration.zero);
+
+      expect(sockets, hasLength(2));
+      expect(sockets.first.disposeCalls, 1);
+      expect(session.state.status, SessionStatus.reconnecting);
+    },
+  );
+
+  test(
+    'resume keeps a connected session within the background grace period',
+    () async {
+      final sockets = <_ControlledRelaySocket>[];
+      final keychain = nostr.Keys.generate();
+      var now = DateTime(2026, 8, 2, 12);
+      final session = RelaySessionNotifier(
+        now: () => now,
+        socketFactory:
+            ({
+              required wsUrl,
+              required nsec,
+              required onMessage,
+              required onConnected,
+              required onDisconnected,
+            }) {
+              final socket = _ControlledRelaySocket(
+                wsUrl: wsUrl,
+                nsec: nsec,
+                onMessage: onMessage,
+                onConnected: onConnected,
+                onDisconnected: onDisconnected,
+              );
+              sockets.add(socket);
+              return socket;
+            },
+      );
+      final container = ProviderContainer(
+        overrides: [
+          relaySessionProvider.overrideWith(() => session),
+          relayConfigProvider.overrideWith(
+            () => _FakeRelayConfigNotifier(
+              baseUrl: 'https://relay.example',
+              nsec: keychain.nsec,
+            ),
+          ),
+          authProvider.overrideWith(() => _AuthenticatedAuthNotifier()),
+        ],
+      );
+      addTearDown(container.dispose);
+      await container.read(authProvider.future);
+      final subscription = container.listen(relaySessionProvider, (_, _) {});
+      addTearDown(subscription.close);
+      await Future<void>.delayed(Duration.zero);
+      sockets.single.connectSuccessfully();
+
+      session.onAppPaused();
+      now = now.add(const Duration(seconds: 4));
+      session.onAppResumed();
+      await Future<void>.delayed(Duration.zero);
+
+      expect(sockets, hasLength(1));
+      expect(sockets.single.disposeCalls, 0);
+      expect(session.state.status, SessionStatus.connected);
+    },
+  );
+
   test('delivers the same live event to each matching subscription', () async {
     final session = RelaySessionNotifier();
     final firstEvents = <NostrEvent>[];
@@ -328,7 +614,7 @@ void main() {
     unsubscribe();
   });
 
-  test('live subscribe fails when relay closes before ready', () async {
+  test('terminal CLOSED fails a live subscribe before ready', () async {
     final session = RelaySessionNotifier();
     const filter = NostrFilter(kinds: [EventKind.agentObserverFrame], limit: 0);
 
@@ -352,32 +638,601 @@ void main() {
   });
 
   test(
-    'live onClosed callback runs when relay closes an open subscription',
+    'retryable CLOSED before EOSE retains and retries the live sub',
     () async {
-      final session = RelaySessionNotifier();
-      final closedMessages = <String>[];
-      const filter = NostrFilter(
-        kinds: [EventKind.agentObserverFrame],
-        limit: 0,
+      final timers = <_ManualTimer>[];
+      final socket = _RecordingRelaySocket();
+      final session = RelaySessionNotifier(
+        retryTimerFactory: (duration, callback) {
+          final timer = _ManualTimer(duration, callback);
+          timers.add(timer);
+          return timer;
+        },
       );
+      session.debugAttachSocketForTest(socket);
 
-      final subscribe = session.subscribe(
-        filter,
-        (_) {},
-        onClosed: closedMessages.add,
-      );
-      session.debugHandleMessage(['EOSE', 'l-1']);
+      final subscribe = session.subscribe(_channelFilter, (_) {});
+      session.debugHandleMessage(['CLOSED', 'l-1', 'error: relay overloaded']);
       final unsubscribe = await subscribe;
-      session.debugHandleMessage([
-        'CLOSED',
-        'l-1',
-        'restricted: no longer valid',
-      ]);
 
-      expect(closedMessages, ['restricted: no longer valid']);
+      expect(timers.single.duration, const Duration(seconds: 1));
+      timers.single.fire();
+      await Future<void>.delayed(Duration.zero);
+
+      expect(_reqs(socket).where((req) => req[1] == 'l-1'), hasLength(2));
       unsubscribe();
     },
   );
+
+  test('CLOSED retries back off and reset after EOSE', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 1));
+    timers.last.fire();
+    await Future<void>.delayed(Duration.zero);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 2));
+
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 1));
+    unsubscribe();
+  });
+
+  test('CLOSED retry backoff saturates before a high-attempt shift', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+
+    for (var attempt = 0; attempt < 100; attempt++) {
+      session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+      expect(
+        timers.last.duration,
+        attempt >= 5
+            ? const Duration(seconds: 30)
+            : Duration(seconds: 1 << attempt),
+      );
+      timers.last.fire();
+      await Future<void>.delayed(Duration.zero);
+    }
+
+    unsubscribe();
+  });
+
+  test('CLOSED retries reset after a delivered event', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    timers.last.fire();
+    await Future<void>.delayed(Duration.zero);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 2));
+
+    session.debugHandleMessage([
+      'EVENT',
+      'l-1',
+      _event(createdAt: 30).toJson(),
+    ]);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 1));
+    unsubscribe();
+  });
+
+  test('CLOSED retries reset after disconnect and reconnect', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    timers.last.fire();
+    await Future<void>.delayed(Duration.zero);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 2));
+
+    session.debugResetClosedRetriesForDisconnect();
+    expect(timers.last.isActive, isFalse);
+    session.debugSetSessionStatus(SessionStatus.connected);
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    expect(timers.last.duration, const Duration(seconds: 1));
+    unsubscribe();
+  });
+
+  test('a CLOSED retry timer does not send while disconnected', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+    final requestCount = _reqs(socket).length;
+
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    session.debugSetSessionStatus(SessionStatus.reconnecting);
+    timers.single.fire();
+    await Future<void>.delayed(Duration.zero);
+
+    expect(_reqs(socket), hasLength(requestCount));
+    unsubscribe();
+  });
+
+  test('terminal CLOSED removes a live sub without retrying it', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    await subscribe;
+
+    session.debugHandleMessage(['CLOSED', 'l-1', 'restricted: access revoked']);
+    await session.debugReplayLiveSubscriptions();
+
+    expect(timers, isEmpty);
+    expect(_reqs(socket).where((req) => req[1] == 'l-1'), hasLength(1));
+  });
+
+  test('unsubscribe and dispose cancel CLOSED retry timers', () async {
+    final timers = <_ManualTimer>[];
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        timers.add(timer);
+        return timer;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+
+    final firstSubscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await firstSubscribe;
+    session.debugHandleMessage(['CLOSED', 'l-1', 'error: transient']);
+    final unsubscribeTimer = timers.last;
+    unsubscribe();
+    expect(unsubscribeTimer.isActive, isFalse);
+
+    final secondSubscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-2']);
+    await secondSubscribe;
+    session.debugHandleMessage(['CLOSED', 'l-2', 'error: transient']);
+    final disposeTimer = timers.last;
+    session.debugDispose();
+    expect(disposeTimer.isActive, isFalse);
+  });
+
+  test('rate-limited live CLOSED honours the gate floor', () async {
+    final retryTimers = <_ManualTimer>[];
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    final session = RelaySessionNotifier(
+      rateLimitGate: gate,
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        retryTimers.add(timer);
+        return timer;
+      },
+    );
+    final socket = _RecordingRelaySocket();
+    session.debugAttachSocketForTest(socket);
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+
+    session.debugHandleMessage([
+      'CLOSED',
+      'l-1',
+      'rate-limited: quota exceeded; retry in 4s',
+    ]);
+
+    expect(
+      retryTimers.single.duration.inMilliseconds,
+      inInclusiveRange(3990, 4000),
+    );
+    expect(gateTimers.single.duration, const Duration(seconds: 4));
+    unsubscribe();
+  });
+
+  test(
+    'rate-limited CLOSED retry does not survive a superseded connection',
+    () async {
+      final retryTimers = <_ManualTimer>[];
+      final gateTimers = <_ManualTimer>[];
+      final gate = RelayRateLimitGate(
+        now: () => DateTime(2026),
+        timerFactory: (duration, callback) {
+          final timer = _ManualTimer(duration, callback);
+          gateTimers.add(timer);
+          return timer;
+        },
+      );
+      final socket = _RecordingRelaySocket();
+      final session = RelaySessionNotifier(
+        rateLimitGate: gate,
+        retryTimerFactory: (duration, callback) {
+          final timer = _ManualTimer(duration, callback);
+          retryTimers.add(timer);
+          return timer;
+        },
+      );
+      session.debugAttachSocketForTest(socket);
+      final subscribe = session.subscribe(_channelFilter, (_) {});
+      session.debugHandleMessage(['EOSE', 'l-1']);
+      final unsubscribe = await subscribe;
+      socket.messages.clear();
+
+      session.debugHandleMessage([
+        'CLOSED',
+        'l-1',
+        'rate-limited: quota exceeded; retry in 4s',
+      ]);
+      retryTimers.single.fire();
+      await Future<void>.delayed(Duration.zero);
+      expect(_reqs(socket), isEmpty);
+
+      session.debugSupersedeConnection();
+      final replacementReplay = session.debugReplayLiveSubscriptions();
+      await Future<void>.delayed(Duration.zero);
+      gateTimers.single.fire();
+      await replacementReplay;
+      await Future<void>.delayed(Duration.zero);
+
+      expect(_reqs(socket).where((req) => req[1] == 'l-1'), hasLength(1));
+      unsubscribe();
+    },
+  );
+
+  test('simultaneous rate-limited CLOSED retries are replay-paced', () async {
+    final retryTimers = <_ManualTimer>[];
+    final gateTimers = <_ManualTimer>[];
+    final replayDelays = <Duration>[];
+    final replayDelayCompleters = <Completer<void>>[];
+    final gate = RelayRateLimitGate(
+      now: () => DateTime(2026),
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      rateLimitGate: gate,
+      retryTimerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        retryTimers.add(timer);
+        return timer;
+      },
+      replayDelay: (duration) {
+        replayDelays.add(duration);
+        final completer = Completer<void>();
+        replayDelayCompleters.add(completer);
+        return completer.future;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+
+    for (var i = 0; i < 30; i++) {
+      final subscribe = session.subscribe(
+        _filterForChannel('channel-$i'),
+        (_) {},
+      );
+      session.debugHandleMessage(['EOSE', 'l-${i + 1}']);
+      await subscribe;
+    }
+    socket.messages.clear();
+
+    for (var i = 0; i < 30; i++) {
+      session.debugHandleMessage([
+        'CLOSED',
+        'l-${i + 1}',
+        'rate-limited: quota exceeded; retry in 4s',
+      ]);
+    }
+    for (final timer in retryTimers) {
+      timer.fire();
+    }
+    await Future<void>.delayed(Duration.zero);
+    expect(_reqs(socket), isEmpty);
+
+    gateTimers.single.fire();
+    await Future<void>.delayed(Duration.zero);
+    expect(_reqs(socket), hasLength(8));
+    expect(replayDelays, [const Duration(milliseconds: 50)]);
+
+    for (final expectedCount in [16, 24, 30]) {
+      replayDelayCompleters.last.complete();
+      await Future<void>.delayed(Duration.zero);
+      expect(_reqs(socket), hasLength(expectedCount));
+    }
+    expect(replayDelays, [
+      const Duration(milliseconds: 50),
+      const Duration(milliseconds: 50),
+      const Duration(milliseconds: 50),
+    ]);
+    session.debugDispose();
+  });
+
+  test('active rate-limit gate does not delay a new live subscribe', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(rateLimitGate: gate);
+    session.debugAttachSocketForTest(socket);
+    gate.activate(4);
+
+    final subscribe = session.subscribe(_channelFilter, (_) {});
+
+    expect(_reqs(socket), hasLength(1));
+    expect(gateTimers.single.duration, const Duration(seconds: 4));
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+    unsubscribe();
+    session.debugDispose();
+  });
+
+  test('rate-limited history CLOSED gates the next REQ', () async {
+    final gateTimers = <_ManualTimer>[];
+    final gate = RelayRateLimitGate(
+      timerFactory: (duration, callback) {
+        final timer = _ManualTimer(duration, callback);
+        gateTimers.add(timer);
+        return timer;
+      },
+    );
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(rateLimitGate: gate);
+    session.debugAttachSocketForTest(socket);
+
+    final first = session.fetchHistory(_channelFilter);
+    session.debugHandleMessage([
+      'CLOSED',
+      'h-1',
+      'rate-limited: quota exceeded; retry in 4s',
+    ]);
+    await expectLater(first, throwsException);
+
+    final second = session.fetchHistory(_channelFilter);
+    await Future<void>.delayed(Duration.zero);
+    expect(_reqs(socket), hasLength(1));
+    expect(gateTimers.single.duration, const Duration(seconds: 4));
+
+    gateTimers.single.fire();
+    await Future<void>.delayed(Duration.zero);
+    expect(_reqs(socket), hasLength(2));
+    session.debugHandleMessage(['EOSE', 'h-2']);
+    await second;
+  });
+
+  test(
+    'visible channel owners restore and ignore out-of-order release',
+    () async {
+      final socket = _RecordingRelaySocket();
+      final session = RelaySessionNotifier();
+      session.debugAttachSocketForTest(socket);
+      const channelIds = ['channel-a', 'channel-b', 'channel-c'];
+
+      for (var i = 0; i < channelIds.length; i++) {
+        final subscribe = session.subscribe(
+          _filterForChannel(channelIds[i]),
+          (_) {},
+        );
+        session.debugHandleMessage(['EOSE', 'l-${i + 1}']);
+        await subscribe;
+      }
+
+      final releaseA = session.registerVisibleChannel('channel-a');
+      final releaseB = session.registerVisibleChannel('channel-b');
+      final releaseC = session.registerVisibleChannel('channel-c');
+      releaseB();
+      socket.messages.clear();
+      await session.debugReplayLiveSubscriptions();
+      expect(_replayedChannelIds(socket).first, 'channel-c');
+
+      releaseC();
+      socket.messages.clear();
+      await session.debugReplayLiveSubscriptions();
+      expect(_replayedChannelIds(socket).first, 'channel-a');
+
+      releaseB();
+      releaseA();
+    },
+  );
+
+  test('replay is visible-first and batched eight at a time', () async {
+    final replayDelays = <Duration>[];
+    final replayDelayCompleter = Completer<void>();
+    final socket = _RecordingRelaySocket();
+    final session = RelaySessionNotifier(
+      replayDelay: (duration) {
+        replayDelays.add(duration);
+        return replayDelayCompleter.future;
+      },
+    );
+    session.debugAttachSocketForTest(socket);
+
+    for (var i = 0; i < 9; i++) {
+      final channelId = i == 8 ? _visibleChannelId : 'channel-$i';
+      final subscribe = session.subscribe(_filterForChannel(channelId), (_) {});
+      session.debugHandleMessage(['EOSE', 'l-${i + 1}']);
+      await subscribe;
+    }
+    socket.messages.clear();
+    final releaseVisibleChannel = session.registerVisibleChannel(
+      _visibleChannelId,
+    );
+
+    final replay = session.debugReplayLiveSubscriptions();
+    await Future<void>.delayed(Duration.zero);
+
+    final firstBatch = _reqs(socket);
+    expect(firstBatch, hasLength(8));
+    expect((firstBatch.first[2] as Map<String, dynamic>)['#h'], [
+      _visibleChannelId,
+    ]);
+    expect(replayDelays, [const Duration(milliseconds: 50)]);
+
+    replayDelayCompleter.complete();
+    await replay;
+    expect(_reqs(socket), hasLength(9));
+    releaseVisibleChannel();
+  });
+
+  test(
+    'replay generation guard bails after a connection is superseded',
+    () async {
+      final replayDelayCompleter = Completer<void>();
+      final socket = _RecordingRelaySocket();
+      final session = RelaySessionNotifier(
+        replayDelay: (_) => replayDelayCompleter.future,
+      );
+      session.debugAttachSocketForTest(socket);
+
+      for (var i = 0; i < 9; i++) {
+        final subscribe = session.subscribe(
+          _filterForChannel('channel-$i'),
+          (_) {},
+        );
+        session.debugHandleMessage(['EOSE', 'l-${i + 1}']);
+        await subscribe;
+      }
+      socket.messages.clear();
+
+      final replay = session.debugReplayLiveSubscriptions();
+      await Future<void>.delayed(Duration.zero);
+      expect(_reqs(socket), hasLength(8));
+
+      session.debugSupersedeConnection();
+      replayDelayCompleter.complete();
+      await replay;
+
+      expect(_reqs(socket), hasLength(8));
+    },
+  );
+
+  test('live onClosed callback runs only for a terminal CLOSED', () async {
+    final session = RelaySessionNotifier();
+    final closedMessages = <String>[];
+    const filter = NostrFilter(kinds: [EventKind.agentObserverFrame], limit: 0);
+
+    final subscribe = session.subscribe(
+      filter,
+      (_) {},
+      onClosed: closedMessages.add,
+    );
+    session.debugHandleMessage(['EOSE', 'l-1']);
+    final unsubscribe = await subscribe;
+    session.debugHandleMessage([
+      'CLOSED',
+      'l-1',
+      'error: temporarily unavailable',
+    ]);
+    expect(closedMessages, isEmpty);
+    session.debugHandleMessage([
+      'CLOSED',
+      'l-1',
+      'restricted: no longer valid',
+    ]);
+
+    expect(closedMessages, ['restricted: no longer valid']);
+    unsubscribe();
+  });
+}
+
+class _QueryHarness {
+  final ProviderContainer container;
+  final RelaySessionNotifier session;
+
+  _QueryHarness({required this.container, required this.session});
+}
+
+_QueryHarness _queryHarness({
+  required RelayRateLimitGate gate,
+  required http.Client client,
+}) {
+  final session = RelaySessionNotifier(httpClient: client, rateLimitGate: gate);
+  final container = ProviderContainer(
+    overrides: [
+      relaySessionProvider.overrideWith(() => session),
+      relayConfigProvider.overrideWith(
+        () => _FakeRelayConfigNotifier(
+          baseUrl: 'https://relay.example',
+          nsec: nostr.Keys.generate().nsec,
+        ),
+      ),
+    ],
+  );
+  container.read(relaySessionProvider);
+  return _QueryHarness(container: container, session: session);
 }
 
 class _FakeAuthNotifier extends AuthNotifier {
@@ -402,6 +1257,7 @@ class _AuthenticatedAuthNotifier extends AuthNotifier {
 class _ControlledRelaySocket extends RelaySocket {
   final void Function() _connected;
   final void Function(Object? error) _disconnected;
+  int disposeCalls = 0;
 
   _ControlledRelaySocket({
     required super.wsUrl,
@@ -416,7 +1272,9 @@ class _ControlledRelaySocket extends RelaySocket {
   Future<void> connect() async {}
 
   @override
-  void dispose() {}
+  void dispose() {
+    disposeCalls++;
+  }
 
   void connectSuccessfully() => _connected();
 
@@ -437,11 +1295,11 @@ class _FakeRelayConfigNotifier extends RelayConfigNotifier {
   RelayConfig build() => RelayConfig(baseUrl: _baseUrl, nsec: _nsec);
 }
 
-NostrEvent _event() {
-  return const NostrEvent(
+NostrEvent _event({int createdAt = 20}) {
+  return NostrEvent(
     id: 'event-1',
     pubkey: 'alice',
-    createdAt: 20,
+    createdAt: createdAt,
     kind: EventKind.streamMessageV2,
     tags: [
       ['h', _channelId],
@@ -450,3 +1308,72 @@ NostrEvent _event() {
     sig: 'sig',
   );
 }
+
+const _visibleChannelId = '99999999-9999-4999-8999-999999999999';
+const _channelFilter = NostrFilter(
+  kinds: EventKind.channelEventKinds,
+  tags: {
+    '#h': [_channelId],
+  },
+  limit: 0,
+);
+
+NostrFilter _filterForChannel(String channelId) => NostrFilter(
+  kinds: EventKind.channelEventKinds,
+  tags: {
+    '#h': [channelId],
+  },
+  limit: 0,
+);
+
+List<String> _replayedChannelIds(_RecordingRelaySocket socket) => _reqs(socket)
+    .map(
+      (message) =>
+          ((message[2] as Map<String, dynamic>)['#h'] as List).single as String,
+    )
+    .toList();
+
+List<List<dynamic>> _reqs(_RecordingRelaySocket socket) =>
+    socket.messages.where((message) => message.first == 'REQ').toList();
+
+class _RecordingRelaySocket extends RelaySocket {
+  _RecordingRelaySocket()
+    : super(
+        wsUrl: 'wss://relay.example',
+        nsec: null,
+        onMessage: (_) {},
+        onConnected: () {},
+        onDisconnected: (_) {},
+      );
+
+  final List<List<dynamic>> messages = [];
+
+  @override
+  void send(List<dynamic> payload) => messages.add(payload);
+
+  @override
+  void dispose() {}
+}
+
+class _ManualTimer implements Timer {
+  _ManualTimer(this.duration, this._callback);
+
+  final Duration duration;
+  final void Function() _callback;
+  bool _active = true;
+
+  void fire() {
+    if (!_active) return;
+    _active = false;
+    _callback();
+  }
+
+  @override
+  void cancel() => _active = false;
+
+  @override
+  bool get isActive => _active;
+
+  @override
+  int get tick => _active ? 0 : 1;
+}
diff --git a/mobile/test/shared/relay/relay_socket_liveness_test.dart b/mobile/test/shared/relay/relay_socket_liveness_test.dart
new file mode 100644
index 0000000000..835ebc2b61
--- /dev/null
+++ b/mobile/test/shared/relay/relay_socket_liveness_test.dart
@@ -0,0 +1,111 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:buzz/shared/relay/relay_socket.dart';
+import 'package:crypto/crypto.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+/// A server that completes the WS handshake then never speaks again: no pongs,
+/// no close frame. Only a client-side ping timeout can notice.
+Future<ServerSocket> _silentAfterHandshakeServer() async {
+  final server = await ServerSocket.bind(InternetAddress.loopbackIPv4, 0);
+  server.listen((client) {
+    client.listen(
+      (data) {
+        final match = RegExp(
+          r'Sec-WebSocket-Key: (.*)\r\n',
+          caseSensitive: false,
+        ).firstMatch(String.fromCharCodes(data));
+        if (match == null) return;
+        final accept = base64.encode(
+          sha1
+              .convert(
+                utf8.encode(
+                  '${match.group(1)!.trim()}258EAFA5-E914-47DA-95CA-C5AB0DC85B11',
+                ),
+              )
+              .bytes,
+        );
+        client.write(
+          'HTTP/1.1 101 Switching Protocols\r\n'
+          'Upgrade: websocket\r\nConnection: Upgrade\r\n'
+          'Sec-WebSocket-Accept: $accept\r\n\r\n',
+        );
+      },
+      onError: (_) {},
+      onDone: () {},
+    );
+  });
+  return server;
+}
+
+void main() {
+  const testPingInterval = Duration(milliseconds: 150);
+
+  setUp(() {
+    RelaySocket.debugPingInterval = testPingInterval;
+  });
+
+  tearDown(() {
+    RelaySocket.debugPingInterval = RelaySocket.pingInterval;
+  });
+
+  test('detects a peer that stops answering pings', () async {
+    final server = await _silentAfterHandshakeServer();
+
+    final disconnected = Completer<Object?>();
+    final socket = RelaySocket(
+      wsUrl: 'ws://127.0.0.1:${server.port}',
+      nsec: null,
+      onMessage: (_) {},
+      onConnected: () {},
+      onDisconnected: (error) {
+        if (!disconnected.isCompleted) disconnected.complete(error);
+      },
+    );
+    unawaited(socket.connect());
+
+    var detected = true;
+    try {
+      await disconnected.future.timeout(testPingInterval * 4);
+    } on TimeoutException {
+      detected = false;
+    }
+
+    expect(
+      detected,
+      isTrue,
+      reason:
+          'RelaySocket must surface an unanswered ping through onDisconnected',
+    );
+
+    socket.dispose();
+    await server.close();
+  });
+
+  test('keeps an idle but healthy peer connected', () async {
+    final server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
+    server.transform(WebSocketTransformer()).listen((ws) {
+      // A healthy relay answers pings without sending application data.
+      ws.listen((_) {}, onError: (_) {}, onDone: () {});
+    });
+
+    var tornDown = false;
+    final socket = RelaySocket(
+      wsUrl: 'ws://127.0.0.1:${server.port}',
+      nsec: null,
+      onMessage: (_) {},
+      onConnected: () {},
+      onDisconnected: (_) => tornDown = true,
+    );
+    unawaited(socket.connect());
+
+    await Future<void>.delayed(testPingInterval * 4);
+
+    expect(tornDown, isFalse);
+
+    await socket.disconnect();
+    await server.close(force: true);
+  });
+}
diff --git a/mobile/test/shared/theme/app_theme_test.dart b/mobile/test/shared/theme/app_theme_test.dart
index 6231befc69..f038c6d974 100644
--- a/mobile/test/shared/theme/app_theme_test.dart
+++ b/mobile/test/shared/theme/app_theme_test.dart
@@ -7,4 +7,21 @@ void main() {
     expect(AppTheme.light().splashFactory, NoSplash.splashFactory);
     expect(AppTheme.dark().splashFactory, NoSplash.splashFactory);
   });
+
+  test('uses Inter and the shared elevated popover treatment', () {
+    final theme = AppTheme.light();
+    final popupTheme = theme.popupMenuTheme;
+    final shape = popupTheme.shape! as RoundedRectangleBorder;
+    final side = shape.side;
+
+    expect(popupTheme.textStyle?.fontFamily, 'Inter');
+    expect(popupTheme.elevation, 8);
+    expect(
+      popupTheme.shadowColor,
+      theme.colorScheme.shadow.withValues(alpha: 0.18),
+    );
+    expect(shape.borderRadius, BorderRadius.circular(Radii.popover));
+    expect(side.color, Colors.black.withValues(alpha: 0.04));
+    expect(side.width, 1);
+  });
 }
diff --git a/mobile/test/shared/theme/message_typography_test.dart b/mobile/test/shared/theme/message_typography_test.dart
index 169bcc0200..c5bec55556 100644
--- a/mobile/test/shared/theme/message_typography_test.dart
+++ b/mobile/test/shared/theme/message_typography_test.dart
@@ -130,6 +130,13 @@ void main() {
       lineHeight: 17,
       letterSpacing: 0,
     );
+    expectStyle(
+      filterChipTextStyle,
+      fontSize: 15,
+      fontWeight: FontWeight.w400,
+      lineHeight: 15,
+      letterSpacing: 0,
+    );
   });
 
   test('message and activity avatars use their surface sizes', () {
diff --git a/mobile/test/shared/widgets/filter_chip_bar_test.dart b/mobile/test/shared/widgets/filter_chip_bar_test.dart
index 6f651624b6..72040e5d86 100644
--- a/mobile/test/shared/widgets/filter_chip_bar_test.dart
+++ b/mobile/test/shared/widgets/filter_chip_bar_test.dart
@@ -39,10 +39,57 @@ void main() {
     final unselectedLabel = tester.widget<Text>(find.text('Following'));
     expect(selectedLabel.style?.fontSize, filterChipTextStyle.fontSize);
     expect(selectedLabel.style?.height, filterChipTextStyle.height);
+    expect(selectedLabel.style?.fontFamily, 'Inter');
     expect(selectedLabel.style?.fontWeight, FontWeight.w500);
     expect(unselectedLabel.style?.fontSize, filterChipTextStyle.fontSize);
     expect(unselectedLabel.style?.height, filterChipTextStyle.height);
     expect(unselectedLabel.style?.fontWeight, FontWeight.w400);
+    final chip = tester.widget<FilterChip>(
+      find.widgetWithText(FilterChip, 'Everyone'),
+    );
+    final shape = chip.shape! as RoundedRectangleBorder;
+    expect(shape.borderRadius, BorderRadius.circular(Radii.lg));
+    expect(chip.labelPadding, EdgeInsets.zero);
+  });
+
+  testWidgets('search labels are vertically centered in their chips', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      MaterialApp(
+        theme: AppTheme.light(),
+        home: Scaffold(
+          body: SizedBox(
+            width: 390,
+            child: FilterChipBar<int>(
+              expandItems: true,
+              visualDensity: const VisualDensity(horizontal: -2),
+              chipVerticalPadding: Grid.xxs,
+              barVerticalPadding: Grid.twelve,
+              selected: 0,
+              onSelected: (_) {},
+              items: const [
+                FilterChipItem(id: 0, label: 'All'),
+                FilterChipItem(id: 1, label: 'Messages'),
+                FilterChipItem(id: 2, label: 'Channels'),
+                FilterChipItem(id: 3, label: 'People'),
+              ],
+            ),
+          ),
+        ),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    for (final label in ['All', 'Messages', 'Channels', 'People']) {
+      final text = find.text(label);
+      final chip = find.ancestor(of: text, matching: find.byType(RawChip));
+      expect(chip, findsOneWidget);
+      expect(
+        tester.getCenter(text).dy,
+        closeTo(tester.getCenter(chip).dy, 0.01),
+      );
+    }
   });
 
   testWidgets('expanded chips preserve large accessible text scaling', (
@@ -81,7 +128,10 @@ void main() {
       ),
       findsNothing,
     );
-    expect(tester.getSize(find.text('Messages')).height, greaterThan(32));
+    expect(
+      tester.getSize(find.text('Messages')).height,
+      greaterThanOrEqualTo(30),
+    );
     expect(tester.takeException(), isNull);
   });
 }
diff --git a/mobile/test/shared/widgets/keyboard_dismiss_on_drag_test.dart b/mobile/test/shared/widgets/keyboard_dismiss_on_drag_test.dart
index ae03f55c16..19424b7c82 100644
--- a/mobile/test/shared/widgets/keyboard_dismiss_on_drag_test.dart
+++ b/mobile/test/shared/widgets/keyboard_dismiss_on_drag_test.dart
@@ -4,7 +4,10 @@ import 'package:flutter_test/flutter_test.dart';
 
 /// A focused field inside a `Scaffold` body, which is the only arrangement
 /// either message list ever runs in.
-Widget _testable({required FocusNode focusNode}) {
+Widget _testable({
+  required FocusNode focusNode,
+  VoidCallback? onUserScrollStart,
+}) {
   return MaterialApp(
     home: Scaffold(
       body: Column(
@@ -12,6 +15,7 @@ Widget _testable({required FocusNode focusNode}) {
           TextField(focusNode: focusNode),
           Expanded(
             child: KeyboardDismissOnDrag(
+              onUserScrollStart: onUserScrollStart,
               child: ListView(
                 children: [
                   for (var i = 0; i < 40; i++)
@@ -104,6 +108,23 @@ void main() {
       expect(focusNode.hasFocus, isTrue);
     });
 
+    testWidgets('reports a user-started scroll', (tester) async {
+      final focusNode = FocusNode();
+      addTearDown(focusNode.dispose);
+      var userScrollStarts = 0;
+      await tester.pumpWidget(
+        _testable(
+          focusNode: focusNode,
+          onUserScrollStart: () => userScrollStarts += 1,
+        ),
+      );
+
+      await tester.drag(find.text('row 3'), const Offset(0, -100));
+      await tester.pumpAndSettle();
+
+      expect(userScrollStarts, 1);
+    });
+
     testWidgets('an upward drag never dismisses, however far it goes', (
       tester,
     ) async {
diff --git a/mobile/test/shared/widgets/mobile_tab_footer_backdrop_test.dart b/mobile/test/shared/widgets/mobile_tab_footer_backdrop_test.dart
index 9e54177d61..e13d17a65e 100644
--- a/mobile/test/shared/widgets/mobile_tab_footer_backdrop_test.dart
+++ b/mobile/test/shared/widgets/mobile_tab_footer_backdrop_test.dart
@@ -3,6 +3,28 @@ import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
 
 void main() {
+  testWidgets('shared gradient fades from transparent to the page surface', (
+    tester,
+  ) async {
+    LinearGradient? gradient;
+
+    await tester.pumpWidget(
+      MaterialApp(
+        home: Builder(
+          builder: (context) {
+            gradient = mobileTabFooterBackdropGradient(context);
+            return const SizedBox();
+          },
+        ),
+      ),
+    );
+
+    expect(gradient?.stops, [0, 0.5, 1]);
+    expect(gradient?.colors.first.a, 0);
+    expect(gradient?.colors[1].a, 0.75);
+    expect(gradient?.colors.last.a, 1);
+  });
+
   testWidgets('uses the logical bottom safe-area inset', (tester) async {
     double? height;
 
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/bundle-sidecars.sh b/scripts/bundle-sidecars.sh
index 07de477405..8ea5fe2bbe 100755
--- a/scripts/bundle-sidecars.sh
+++ b/scripts/bundle-sidecars.sh
@@ -4,6 +4,12 @@ set -euo pipefail
 SIDECARS=(buzz-acp buzz-agent buzz-dev-mcp git-credential-nostr buzz)
 HOST=$(rustc -vV | sed -n 's|host: ||p')
 TARGET=${1:-$HOST}
+if [[ "$TARGET" != *windows* ]]; then
+    SIDECARS+=(buzz-backend-kubernetes)
+    BUILD_HINT="cargo build --release -p buzz-acp -p buzz-agent -p buzz-backend-kubernetes -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli"
+else
+    BUILD_HINT="cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli"
+fi
 BINARIES_DIR="desktop/src-tauri/binaries"
 
 # When --target is passed explicitly to cargo (even if it matches the host),
@@ -29,7 +35,7 @@ for bin in "${SIDECARS[@]}"; do
 done
 if [[ ${#missing[@]} -gt 0 ]]; then
     echo "Error: missing release binaries in $SRC_DIR: ${missing[*]}" >&2
-    echo "Run 'cargo build --release -p buzz-acp -p buzz-agent -p buzz-dev-mcp -p git-credential-nostr -p buzz-cli' first." >&2
+    echo "Run '$BUILD_HINT' first." >&2
     exit 1
 fi
 
diff --git a/scripts/run-tests.sh b/scripts/run-tests.sh
index 2e7e944482..0e5946ca18 100755
--- a/scripts/run-tests.sh
+++ b/scripts/run-tests.sh
@@ -106,6 +106,12 @@ run_unit_tests() {
 
   run_test_step "buzz-push-gateway tests" \
     cargo test -p buzz-push-gateway -- --nocapture
+
+  # Kubernetes backend provider: pure decision layers driven by a fake
+  # substrate, no cluster. Mirrors the nextest path in `just test-unit` —
+  # the two lists must stay in step or the fallback silently covers less.
+  run_test_step "buzz-backend-kubernetes tests" \
+    cargo test -p buzz-backend-kubernetes -- --nocapture
 }
 
 # ---- DB / integration tests (infra required) --------------------------------
diff --git a/scripts/sprig-entrypoint.sh b/scripts/sprig-entrypoint.sh
new file mode 100755
index 0000000000..16abf7bc51
--- /dev/null
+++ b/scripts/sprig-entrypoint.sh
@@ -0,0 +1,16 @@
+#!/bin/bash
+set -euo pipefail
+
+# Match desktop's URL-scoped git credential configuration without installing a
+# helper globally (which would make it answer for unrelated remotes).
+if [[ -n "${BUZZ_RELAY_URL:-}" ]]; then
+    relay_http_url="${BUZZ_RELAY_URL/#ws:/http:}"
+    relay_http_url="${relay_http_url/#wss:/https:}"
+    relay_http_url="${relay_http_url%/}"
+    git config --global "credential.${relay_http_url}/git.helper" \
+        /usr/local/bin/git-credential-nostr
+    git config --global "credential.${relay_http_url}/git.useHttpPath" true
+fi
+
+# The harness must receive Kubernetes' termination signal directly.
+exec buzz-acp "$@"
diff --git a/scripts/test-k8s-provider-release.sh b/scripts/test-k8s-provider-release.sh
new file mode 100755
index 0000000000..40c78e2688
--- /dev/null
+++ b/scripts/test-k8s-provider-release.sh
@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Reproduce the desktop release's multi-package build shape, then prove the
+# Kubernetes provider reports an unreachable cluster in-band rather than
+# panicking when rustls has multiple compiled crypto providers available.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+TARGET_DIR="${CARGO_TARGET_DIR:-$ROOT/target}"
+PROVIDER_BINARY="$TARGET_DIR/release/buzz-backend-kubernetes"
+
+CARGO="${CARGO:-cargo}"
+"$CARGO" build --release \
+  -p buzz-acp \
+  -p buzz-agent \
+  -p buzz-dev-mcp \
+  -p git-credential-nostr \
+  -p buzz-cli \
+  -p buzz-backend-kubernetes
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+cat >"$TMP/kubeconfig" <<'YAML'
+apiVersion: v1
+kind: Config
+clusters:
+  - name: unreachable
+    cluster:
+      server: http://127.0.0.1:9
+contexts:
+  - name: unreachable
+    context:
+      cluster: unreachable
+      user: none
+current-context: unreachable
+users:
+  - name: none
+    user: {}
+YAML
+
+cat >"$TMP/request.json" <<'JSON'
+{
+  "op": "deploy",
+  "agent": {
+    "relay_url": "wss://relay.example",
+    "private_key_nsec": "nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5",
+    "auth_tag": "owner",
+    "launch": {"command": "goose", "args": [], "env": {}, "policy_env": {}}
+  },
+  "provider_config": {
+    "context": "unreachable",
+    "namespace": "never-created",
+    "image": "example.invalid/sprig@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "inactivity_seconds": 60
+  }
+}
+JSON
+
+set +e
+KUBECONFIG="$TMP/kubeconfig" \
+  "$PROVIDER_BINARY" \
+  <"$TMP/request.json" >"$TMP/stdout" 2>"$TMP/stderr"
+status=$?
+set -e
+
+[[ "$status" == 0 ]] || {
+  echo "provider exited $status instead of returning an in-band failure" >&2
+  cat "$TMP/stderr" >&2
+  exit 1
+}
+[[ "$(wc -l <"$TMP/stdout" | tr -d ' ')" == 1 ]]
+jq -e '.ok == false and (.error | type == "string" and length > 0)' "$TMP/stdout" >/dev/null
+if rg -i 'panic|crypto provider|no process-level' "$TMP/stdout" "$TMP/stderr"; then
+  echo "provider emitted a panic/crypto-provider failure" >&2
+  exit 1
+fi
+printf 'PASS: release-shaped provider returned one in-band unreachable-cluster failure\n'
diff --git a/scripts/test-k8s-sprig-image-live.sh b/scripts/test-k8s-sprig-image-live.sh
new file mode 100755
index 0000000000..ec9f259053
--- /dev/null
+++ b/scripts/test-k8s-sprig-image-live.sh
@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# Prove that a cluster can resolve and start the exact digest-qualified Sprig
+# image that will be passed to the Kubernetes provider. This is intentionally a
+# separate preflight: a Docker image existing in the host daemon does not imply
+# that the kubelet's container runtime can resolve the same name and digest.
+set -euo pipefail
+
+: "${BUZZ_K8S_TEST_CONTEXT:?set the explicit disposable/local kubectl context}"
+: "${BUZZ_SPRIG_IMAGE:?set an immutable image reference (name@sha256:<64 hex>)}"
+
+if [[ ! "$BUZZ_SPRIG_IMAGE" =~ ^[^[:space:]@]+@sha256:[0-9a-fA-F]{64}$ ]]; then
+    echo "error: BUZZ_SPRIG_IMAGE must be name@sha256:<64 hex>" >&2
+    exit 2
+fi
+
+CONTEXT="$BUZZ_K8S_TEST_CONTEXT"
+IMAGE="$BUZZ_SPRIG_IMAGE"
+PULL_POLICY="${BUZZ_K8S_TEST_PULL_POLICY:-IfNotPresent}"
+case "$PULL_POLICY" in
+    Always|IfNotPresent|Never) ;;
+    *) echo "error: invalid BUZZ_K8S_TEST_PULL_POLICY: $PULL_POLICY" >&2; exit 2 ;;
+esac
+
+MANAGED_BY="buzz-backend-kubernetes"
+BINDING_VERSION="v1"
+NAMESPACE="buzz-k8s-sprig-$(date +%s)-$RANDOM"
+CREATED=0
+
+cleanup() {
+    (( CREATED == 1 )) || return 0
+    local managed binding foreign
+    managed="$(kubectl --context "$CONTEXT" get namespace "$NAMESPACE" \
+        -o jsonpath='{.metadata.labels.app\.kubernetes\.io/managed-by}' 2>/dev/null || true)"
+    binding="$(kubectl --context "$CONTEXT" get namespace "$NAMESPACE" \
+        -o jsonpath='{.metadata.labels.buzz\.block\.xyz/binding-version}' 2>/dev/null || true)"
+    if [[ "$managed" != "$MANAGED_BY" || "$binding" != "$BINDING_VERSION" ]]; then
+        echo "REFUSING cleanup: namespace ownership markers changed: $NAMESPACE" >&2
+        return 1
+    fi
+    foreign="$(kubectl --context "$CONTEXT" --namespace "$NAMESPACE" get pods -o json \
+        | jq '[.items[] | select(.metadata.labels["app.kubernetes.io/managed-by"] != "buzz-backend-kubernetes" or .metadata.labels["buzz.block.xyz/binding-version"] != "v1")] | length')"
+    if [[ "$foreign" != 0 ]]; then
+        echo "REFUSING cleanup: namespace contains an unowned pod: $NAMESPACE" >&2
+        return 1
+    fi
+    kubectl --context "$CONTEXT" delete namespace "$NAMESPACE" --wait=true
+}
+trap cleanup EXIT
+
+# Fail before mutation if the named context is absent or inaccessible. Print the
+# cluster identity so evidence cannot be mistaken for a different kubeconfig.
+kubectl config get-contexts "$CONTEXT" >/dev/null
+SERVER="$(kubectl config view --minify --context "$CONTEXT" -o jsonpath='{.clusters[0].cluster.server}')"
+kubectl --context "$CONTEXT" get nodes -o name >/dev/null
+printf 'context=%s\nserver=%s\nimage=%s\npull_policy=%s\nnamespace=%s\n' \
+    "$CONTEXT" "$SERVER" "$IMAGE" "$PULL_POLICY" "$NAMESPACE"
+
+kubectl --context "$CONTEXT" create namespace "$NAMESPACE"
+CREATED=1
+kubectl --context "$CONTEXT" label namespace "$NAMESPACE" \
+    "app.kubernetes.io/managed-by=$MANAGED_BY" \
+    "buzz.block.xyz/binding-version=$BINDING_VERSION"
+
+cat <<YAML | kubectl --context "$CONTEXT" --namespace "$NAMESPACE" apply -f -
+apiVersion: v1
+kind: Pod
+metadata:
+  name: digest-resolution-probe
+  labels:
+    app.kubernetes.io/managed-by: $MANAGED_BY
+    buzz.block.xyz/binding-version: $BINDING_VERSION
+spec:
+  restartPolicy: Never
+  containers:
+    - name: probe
+      image: $IMAGE
+      imagePullPolicy: $PULL_POLICY
+      command: [/bin/bash, -ceu]
+      args:
+        - 'test "\$(readlink /usr/local/bin/buzz-acp)" = sprig; echo DIGEST_ABI_OK'
+YAML
+
+if ! kubectl --context "$CONTEXT" --namespace "$NAMESPACE" wait \
+    --for=jsonpath='{.status.phase}'=Succeeded pod/digest-resolution-probe --timeout=120s; then
+    kubectl --context "$CONTEXT" --namespace "$NAMESPACE" describe pod digest-resolution-probe >&2 || true
+    exit 1
+fi
+
+kubectl --context "$CONTEXT" --namespace "$NAMESPACE" logs digest-resolution-probe
+IMAGE_ID="$(kubectl --context "$CONTEXT" --namespace "$NAMESPACE" get pod digest-resolution-probe \
+    -o jsonpath='{.status.containerStatuses[0].imageID}')"
+RESOLVED_SPEC="$(kubectl --context "$CONTEXT" --namespace "$NAMESPACE" get pod digest-resolution-probe \
+    -o jsonpath='{.spec.containers[0].image}')"
+[[ "$RESOLVED_SPEC" == "$IMAGE" ]]
+[[ -n "$IMAGE_ID" ]]
+printf 'resolved_spec=%s\nimage_id=%s\nPASS: exact digest-qualified Sprig reference started\n' \
+    "$RESOLVED_SPEC" "$IMAGE_ID"
diff --git a/scripts/test-sprig-image.sh b/scripts/test-sprig-image.sh
new file mode 100755
index 0000000000..4ca42fdb4d
--- /dev/null
+++ b/scripts/test-sprig-image.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+IMAGE="${1:-buzz-sprig:contract-test}"
+if [[ "${SKIP_BUILD:-0}" != 1 ]]; then
+    docker build --file Dockerfile.sprig --tag "$IMAGE" .
+fi
+
+assert_run() {
+    docker run --rm --entrypoint /bin/bash "$IMAGE" -ceu "$1"
+}
+
+assert_run '
+  command -v bash git update-ca-certificates >/dev/null
+  test "$(readlink /usr/local/bin/buzz-acp)" = sprig
+  for name in buzz-agent buzz-dev-mcp rg tree buzz git-credential-nostr git-sign-nostr; do
+    test "$(readlink "/usr/local/bin/$name")" = sprig
+  done
+  test "$(git config --system gpg.x509.program)" = /usr/local/bin/git-sign-nostr
+  ! git config --system --get-all credential.helper
+  test "$HOME" = /home/agent
+  test "$(pwd)" = /home/agent
+'
+
+assert_run '
+  grep -Eq "^[[:space:]]*exec buzz-acp" /usr/local/bin/sprig-entrypoint
+  ! grep -Eq "^[[:space:]]*(buzz-acp|bash -c .*buzz-acp)" /usr/local/bin/sprig-entrypoint
+'
+
+docker run --rm --entrypoint /bin/bash \
+  -e BUZZ_RELAY_URL=wss://relay.example.test/ "$IMAGE" -ceu '
+    /usr/local/bin/sprig-entrypoint --help >/dev/null 2>&1 & pid=$!
+    for _ in 1 2 3 4 5; do
+      git config --global --get credential.https://relay.example.test/git.helper >/dev/null 2>&1 && break
+      sleep 0.1
+    done
+    test "$(git config --global --get credential.https://relay.example.test/git.helper)" = /usr/local/bin/git-credential-nostr
+    test "$(git config --global --get credential.https://relay.example.test/git.useHttpPath)" = true
+    ! git config --global --get-all credential.helper
+    wait "$pid" || true
+  '
+
+echo "PASS: Sprig image runtime contract ($IMAGE)"