diff --git a/.github/actions/setup-macos/action.yml b/.github/actions/setup-macos/action.yml
index b8fd67438..9aa794515 100644
--- a/.github/actions/setup-macos/action.yml
+++ b/.github/actions/setup-macos/action.yml
@@ -1,34 +1,38 @@
 name: Setup macOS build deps
-description: Install + cache mise tools and Ghostty build outputs
+description: Install + cache mise tools and ThirdParty build outputs (Ghostty, zmx)
+
+inputs:
+  disable-tools:
+    description: Comma-separated mise tools to skip, so CI installs only what it needs.
+    default: spm:swiftlang/swift-format,npm:create-dmg
 
 runs:
   using: composite
   steps:
-    # The bundled zig (0.15.2) self-hosted linker can't link the macOS 26.4+ SDK
-    # (ziglang/zig#31272), which breaks `make build-ghostty-xcframework`. Pin to the
-    # newest installed Xcode <= 26.3, whose SDK zig can link.
-    - name: Select Xcode <= 26.3
+    # Job-wide so every later mise call (install, plus auto-install during the
+    # build steps under MISE_YES) skips the unneeded tools, not just this step.
+    - name: Limit mise to the tools CI needs
+      shell: bash
+      run: echo "MISE_DISABLE_TOOLS=${{ inputs.disable-tools }}" >> "$GITHUB_ENV"
+    # The bundled zig 0.15.2 linker can't link the macOS 26.4+ SDK (ziglang/zig#31658).
+    # Reuse the shared selector so CI and local agree on the Zig-linkable Xcode.
+    - name: Select a Zig-linkable Xcode
       shell: bash
       run: |
         set -euo pipefail
-        selected=""
-        for app in /Applications/Xcode_26.3*.app /Applications/Xcode_26.2*.app \
-          /Applications/Xcode_26.1*.app /Applications/Xcode_26.0*.app; do
-          if [ -d "$app" ]; then selected="$app"; break; fi
-        done
-        if [ -z "$selected" ]; then
-          echo "No Xcode <= 26.3 found on runner; available:" >&2
-          ls -d /Applications/Xcode_*.app >&2 || true
-          exit 1
-        fi
-        sudo xcode-select -s "$selected/Contents/Developer"
+        developer_dir="$(./scripts/select-developer-dir.sh)"
+        sudo xcode-select -s "$developer_dir"
         xcodebuild -version
     - uses: jdx/mise-action@v4
       with:
         version: 2026.3.0
         cache: true
+    # Tuist auth (OIDC) only works on the canonical upstream repo, which is the
+    # one linked in the Tuist dashboard. Skip it on forks and on cross-fork PRs
+    # (external contributors can't access the OIDC trust) — `tuist generate`
+    # works fine without auth; auth only buys the Tuist remote cache.
     - name: Authenticate with Tuist
-      if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
+      if: ${{ github.repository == 'supabitapp/supacode' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) }}
       shell: bash
       run: mise exec -- tuist auth login
     - name: Xcode cache key
@@ -36,21 +40,35 @@ runs:
       run: |
         XCODE_VERSION="$(xcodebuild -version | tr '\n' '-' | sed 's/[^A-Za-z0-9._-]/_/g; s/-$//')"
         printf '%s\n' "XCODE_VERSION=$XCODE_VERSION" >> "$GITHUB_ENV"
-    - name: Ghostty cache key
+    - name: ThirdParty cache keys
       shell: bash
       run: |
         set -euo pipefail
-        GHOSTTY_SHA="$(git -C ThirdParty/ghostty rev-parse HEAD)"
-        printf '%s\n' "GHOSTTY_SHA=$GHOSTTY_SHA" >> "$GITHUB_ENV"
+        printf '%s\n' "GHOSTTY_SHA=$(git -C ThirdParty/ghostty rev-parse HEAD)" >> "$GITHUB_ENV"
+        printf '%s\n' "ZMX_SHA=$(git -C ThirdParty/zmx rev-parse HEAD)" >> "$GITHUB_ENV"
+    # Key on only the inputs that change the built artifact (submodule SHA, build
+    # script, zig version, patches) so unrelated action/project edits don't evict it.
     - name: Ghostty cache
       id: ghostty_cache
       uses: actions/cache@v5
       with:
         path: .build/ghostty
-        key: ${{ runner.os }}-${{ runner.arch }}-xcode-${{ env.XCODE_VERSION }}-ghostty-v2-${{ env.GHOSTTY_SHA }}-${{ hashFiles('.github/actions/setup-macos/action.yml', 'Project.swift', 'scripts/build-ghostty.sh', 'mise.toml', '.gitmodules') }}
+        key: ${{ runner.os }}-${{ runner.arch }}-xcode-${{ env.XCODE_VERSION }}-ghostty-v3-${{ env.GHOSTTY_SHA }}-${{ hashFiles('scripts/build-ghostty.sh', 'mise.toml', '.gitmodules', 'patches/*.patch') }}
     - name: Build ghostty
       if: steps.ghostty_cache.outputs.cache-hit != 'true'
       shell: bash
       run: |
         set -euo pipefail
         make build-ghostty-xcframework
+    - name: zmx cache
+      id: zmx_cache
+      uses: actions/cache@v5
+      with:
+        path: .build/zmx
+        key: ${{ runner.os }}-${{ runner.arch }}-xcode-${{ env.XCODE_VERSION }}-zmx-v1-${{ env.ZMX_SHA }}-${{ hashFiles('scripts/build-zmx.sh', 'mise.toml', '.gitmodules') }}
+    - name: Build zmx
+      if: steps.zmx_cache.outputs.cache-hit != 'true'
+      shell: bash
+      run: |
+        set -euo pipefail
+        make build-zmx
diff --git a/.github/workflows/test.yml b/.github/workflows/ci.yml
similarity index 82%
rename from .github/workflows/test.yml
rename to .github/workflows/ci.yml
index f15d62dee..91cea384e 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/ci.yml
@@ -1,9 +1,6 @@
-name: test
+name: ci
 
 on:
-  push:
-    branches:
-      - main
   pull_request:
     branches:
       - main
@@ -27,5 +24,8 @@ jobs:
           submodules: recursive
       - uses: ./.github/actions/setup-macos
       - run: make lint
+      - run: make inspect-dependencies
       - run: make build-app
+        env:
+          XCODEBUILD_FLAGS: -showBuildTimingSummary
       - run: make test
diff --git a/.github/workflows/fork-build.yml b/.github/workflows/fork-build.yml
new file mode 100644
index 000000000..cfb833e46
--- /dev/null
+++ b/.github/workflows/fork-build.yml
@@ -0,0 +1,36 @@
+name: fork-build
+
+# Build the Debug app on feature branches and upload it as an artifact so a
+# fork (where local builds are impossible) can download and install a testable
+# build. No tests, no signing — just a runnable .app.zip per commit.
+on:
+  push:
+    branches:
+      - "feat/**"
+      - "fix/**"
+      - "exp/**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: macos-26
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      MISE_HTTP_TIMEOUT: 120
+      MISE_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+      - uses: ./.github/actions/setup-macos
+      - run: make package-app
+      - uses: actions/upload-artifact@v6
+        with:
+          name: supacode-${{ github.sha }}
+          path: build/supacode.app.zip
+          if-no-files-found: error
diff --git a/.github/workflows/inspect-dependencies.yml b/.github/workflows/inspect-dependencies.yml
deleted file mode 100644
index 1310a39ef..000000000
--- a/.github/workflows/inspect-dependencies.yml
+++ /dev/null
@@ -1,29 +0,0 @@
-name: inspect-dependencies
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  inspect-dependencies:
-    runs-on: macos-26
-    permissions:
-      contents: read
-      id-token: write
-    env:
-      MISE_HTTP_TIMEOUT: 120
-      MISE_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          submodules: recursive
-      - uses: ./.github/actions/setup-macos
-      - run: make inspect-dependencies
diff --git a/.github/workflows/release-tip.yml b/.github/workflows/main.yml
similarity index 56%
rename from .github/workflows/release-tip.yml
rename to .github/workflows/main.yml
index 2b81f4d79..f17c00321 100644
--- a/.github/workflows/release-tip.yml
+++ b/.github/workflows/main.yml
@@ -1,4 +1,4 @@
-name: Release Tip
+name: main
 
 on:
   push:
@@ -6,13 +6,55 @@ on:
 
   workflow_dispatch: {}
 
+# Never cancel in flight: this pipeline also cuts stable releases. Newer pushes queue.
 concurrency:
   group: ${{ github.workflow }}
-  cancel-in-progress: true
+  cancel-in-progress: false
 
 jobs:
+  # Warm the binary cache upstream so test and build consume it on the same commit.
+  warm:
+    runs-on: macos-26
+    strategy:
+      matrix:
+        configuration: [Debug, Release]
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      MISE_HTTP_TIMEOUT: 120
+      MISE_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+      - uses: ./.github/actions/setup-macos
+      - run: make warm-cache
+        env:
+          TUIST_CACHE_CONFIGURATION: ${{ matrix.configuration }}
+
+  test:
+    runs-on: macos-26
+    needs: [warm]
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      MISE_HTTP_TIMEOUT: 120
+      MISE_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+      - uses: ./.github/actions/setup-macos
+      - run: make lint
+      - run: make inspect-dependencies
+      - run: make build-app
+        env:
+          XCODEBUILD_FLAGS: -showBuildTimingSummary
+      - run: make test
+
   check:
-    if: github.event_name == 'workflow_dispatch' || github.ref_name == 'main'
     runs-on: ubuntu-latest
     outputs:
       should_skip: ${{ steps.check.outputs.should_skip }}
@@ -33,7 +75,7 @@ jobs:
 
   build:
     runs-on: macos-26
-    needs: [check]
+    needs: [check, warm]
     if: needs.check.outputs.should_skip != 'true'
     permissions:
       contents: read
@@ -55,7 +97,9 @@ jobs:
         with:
           submodules: recursive
       - uses: ./.github/actions/setup-macos
-      - name: Prepare tip overrides
+        with:
+          disable-tools: spm:swiftlang/swift-format
+      - name: Prepare build overrides
         env:
           SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
           POSTHOG_API_KEY: ${{ secrets.POSTHOG_API_KEY }}
@@ -65,19 +109,17 @@ jobs:
           : "${SENTRY_DSN:?secret SENTRY_DSN is not set}"
           : "${POSTHOG_API_KEY:?secret POSTHOG_API_KEY is not set}"
           : "${POSTHOG_HOST:?secret POSTHOG_HOST is not set}"
-          BASE=$(awk -F' = ' '/^CURRENT_PROJECT_VERSION = [0-9]+$/{print $2; exit}' Configurations/Project.xcconfig)
-          OFFSET=${{ github.run_number }}
-          if [ "$OFFSET" -gt 999 ]; then
-            echo "::error::Tip run_number ($OFFSET) exceeds 999. Bump CURRENT_PROJECT_VERSION before the next tip release."
-            exit 1
-          fi
-          BUILD_NUMBER=$((BASE * 1000 + OFFSET))
+          # Epoch build number: monotonic, computed once here so the single binary reused by tip and stable carries one version.
+          BUILD_NUMBER=$(date +%s)
           mkdir -p build
+          # xcconfig treats // as a comment, which truncates URL values (https://… → https:).
+          # Break every // with $() (evaluates to empty) so the parser never sees a literal //.
+          xcconfig_escape() { printf '%s' "$1" | sed 's#//#/$()/#g'; }
           cat > build/ReleaseOverrides.xcconfig <<EOF
           CURRENT_PROJECT_VERSION = $BUILD_NUMBER
-          SENTRY_DSN = $SENTRY_DSN
-          POSTHOG_API_KEY = $POSTHOG_API_KEY
-          POSTHOG_HOST = $POSTHOG_HOST
+          SENTRY_DSN = $(xcconfig_escape "$SENTRY_DSN")
+          POSTHOG_API_KEY = $(xcconfig_escape "$POSTHOG_API_KEY")
+          POSTHOG_HOST = $(xcconfig_escape "$POSTHOG_HOST")
           EOF
           echo "BUILD_NUMBER=$BUILD_NUMBER" >> "$GITHUB_ENV"
           echo "XCODE_XCCONFIG_FILE=$PWD/build/ReleaseOverrides.xcconfig" >> "$GITHUB_ENV"
@@ -122,6 +164,28 @@ jobs:
           </plist>
           EOF
           make export-archive
+      - name: Verify embedded telemetry config
+        env:
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          POSTHOG_API_KEY: ${{ secrets.POSTHOG_API_KEY }}
+          POSTHOG_HOST: ${{ secrets.POSTHOG_HOST }}
+        run: |
+          set -euo pipefail
+          APP_PATH="$(find build/export -name "supacode.app" -maxdepth 3 -print -quit)"
+          PLIST="$APP_PATH/Contents/Info.plist"
+          assert_eq() {
+            local key="$1" expected="$2"
+            local actual
+            actual="$(/usr/libexec/PlistBuddy -c "Print :$key" "$PLIST")"
+            if [ "$actual" != "$expected" ]; then
+              echo "::error::$key embedded as '$actual' but expected '$expected' (xcconfig // truncation?)"
+              exit 1
+            fi
+            echo "$key OK"
+          }
+          assert_eq SentryDSN "$SENTRY_DSN"
+          assert_eq PostHogAPIKey "$POSTHOG_API_KEY"
+          assert_eq PostHogHost "$POSTHOG_HOST"
       - name: Re-sign frameworks
         run: |
           set -ex
@@ -230,6 +294,39 @@ jobs:
             build/appcast.xml
             build/*.delta
 
+  # Gated on build so a stable release is only detected when the binary exists.
+  # The matching tag (pushed via --follow-tags) marks this exact commit as vX.Y.Z.
+  detect:
+    runs-on: ubuntu-latest
+    needs: [build]
+    permissions:
+      contents: read
+    outputs:
+      release_tag: ${{ steps.detect.outputs.release_tag }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - id: detect
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          VERSION=$(awk -F' = ' '/^MARKETING_VERSION = /{gsub(/\r/,"",$2); print $2; exit}' Configurations/Project.xcconfig)
+          TAG="v$VERSION"
+          RELEASE_TAG=""
+          if [ "$(git rev-list -n 1 "$TAG" 2>/dev/null || true)" = "${{ github.sha }}" ]; then
+            # Idempotency: skip if this release was already published (re-run safety).
+            ASSET_COUNT=$(gh release view "$TAG" -R "${{ github.repository }}" --json assets --jq '.assets | length' 2>/dev/null || echo "0")
+            if [ "$ASSET_COUNT" -eq 0 ]; then
+              RELEASE_TAG="$TAG"
+            else
+              echo "$TAG already has $ASSET_COUNT assets, skipping stable publish"
+            fi
+          fi
+          echo "release_tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
+
   tag:
     runs-on: ubuntu-latest
     needs: [check, build]
@@ -265,13 +362,120 @@ jobs:
           SENTRY_PROJECT: supacode
         run: sentry-cli debug-files upload --include-sources dsyms
 
+  # Stable release: reuses the SAME notarized binaries build produced (no second
+  # archive or notarization) and publishes them with auto-generated notes.
+  publish-stable:
+    runs-on: macos-26
+    needs: [build, detect]
+    if: ${{ needs.detect.outputs.release_tag != '' }}
+    permissions:
+      contents: write
+    env:
+      GH_TOKEN: ${{ github.token }}
+      SPARKLE_PRIVATE_KEY: ${{ secrets.SPARKLE_PRIVATE_KEY }}
+      RELEASE_REPO: ${{ github.repository }}
+      TAG: ${{ needs.detect.outputs.release_tag }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - uses: actions/download-artifact@v7
+        with:
+          name: build-artifacts
+          path: build
+      - name: Drop the tip appcast/deltas from the shared artifact
+        run: rm -f build/appcast.xml build/*.delta
+      - name: Generate release notes
+        run: |
+          set -euo pipefail
+          PREV=$(gh release list --exclude-drafts --exclude-pre-releases -R "$RELEASE_REPO" --json tagName --jq '.[0].tagName' 2>/dev/null || echo "")
+          if [ -n "$PREV" ] && [ "$PREV" != "$TAG" ]; then
+            gh api "repos/$RELEASE_REPO/releases/generate-notes" -f tag_name="$TAG" -f previous_tag_name="$PREV" --jq '.body' > build/release-notes.md
+          else
+            gh api "repos/$RELEASE_REPO/releases/generate-notes" -f tag_name="$TAG" --jq '.body' > build/release-notes.md
+          fi
+          # Prepend the tag's headline ahead of "## What's Changed". Gate on an
+          # annotated tag, else a lightweight tag reads the commit subject.
+          HEADLINE=""
+          if [ "$(git cat-file -t "$TAG" 2>/dev/null)" = tag ]; then
+            # Strip any signature defensively; these notes also feed the Sparkle appcast.
+            HEADLINE=$(git tag -l --format='%(contents:subject)%0a%0a%(contents:body)' "$TAG" | sed '/-----BEGIN .*SIGNATURE-----/,$d')
+          fi
+          # Prepend only a well-formed headline: a `## ` subject with a non-empty body.
+          SUBJECT=$(printf '%s\n' "$HEADLINE" | sed -n '1p')
+          BODY=$(printf '%s\n' "$HEADLINE" | sed '1,2d')
+          case "$SUBJECT" in
+            '## '*)
+              if [ -n "$(printf '%s' "$BODY" | tr -d '[:space:]')" ]; then
+                { printf '%s\n\n' "$HEADLINE"; cat build/release-notes.md; } > build/release-notes.md.new
+                mv build/release-notes.md.new build/release-notes.md
+              fi
+              ;;
+          esac
+      - name: Generate appcast with history and deltas
+        run: |
+          set -euo pipefail
+          MAX_DELTAS=10
+          NOTES_FILE=build/release-notes.md
+          STAGING=$(mktemp -d)
+          ARCHIVE=build/supacode.app.zip
+          ARCHIVE_BASE=$(basename "$ARCHIVE")
+          ARCHIVE_BASE="${ARCHIVE_BASE%.zip}"
+          cp "$ARCHIVE" "$STAGING/"
+          cp "$NOTES_FILE" "$STAGING/$ARCHIVE_BASE.md"
+
+          curl -fsSL "https://supacode.sh/download/latest/appcast.xml" -o "$STAGING/appcast.xml" || true
+
+          SEEN_VERSIONS=""
+          for i in $(seq 1 $MAX_DELTAS); do
+            PREV_TAG=$(gh release list --limit $i --exclude-drafts --exclude-pre-releases -R "$RELEASE_REPO" --json tagName --jq ".[$((i-1))].tagName" 2>/dev/null || true)
+            if [ -n "$PREV_TAG" ] && [ "$PREV_TAG" != "$TAG" ]; then
+              gh release download "$PREV_TAG" -p "supacode.app.zip" -O "$STAGING/supacode-$PREV_TAG.app.zip" -R "$RELEASE_REPO" 2>/dev/null || true
+              if [ -f "$STAGING/supacode-$PREV_TAG.app.zip" ]; then
+                BUNDLE_VERSION=$(unzip -p "$STAGING/supacode-$PREV_TAG.app.zip" "supacode.app/Contents/Info.plist" 2>/dev/null | /usr/libexec/PlistBuddy -c "Print :CFBundleShortVersionString" /dev/stdin 2>/dev/null || echo "")
+                if [ -n "$BUNDLE_VERSION" ] && echo "$SEEN_VERSIONS" | grep -q "^$BUNDLE_VERSION$"; then
+                  rm -f "$STAGING/supacode-$PREV_TAG.app.zip"
+                else
+                  [ -n "$BUNDLE_VERSION" ] && SEEN_VERSIONS="$SEEN_VERSIONS$BUNDLE_VERSION"$'\n'
+                  gh release view "$PREV_TAG" -R "$RELEASE_REPO" --json body --jq '.body' > "$STAGING/supacode-$PREV_TAG.app.md" 2>/dev/null || true
+                fi
+              fi
+            fi
+          done
+
+          printf "%s" "$SPARKLE_PRIVATE_KEY" | tr -d '\r\n\t ' | ./bins/generate_appcast --download-url-prefix "https://supacode.sh/download/$TAG/" --full-release-notes-url "https://github.com/supabitapp/supacode/releases" --embed-release-notes --maximum-versions $MAX_DELTAS --maximum-deltas $MAX_DELTAS --delta-compression lzma --ed-key-file - "$STAGING"
+          cp "$STAGING/appcast.xml" build/appcast.xml
+          find "$STAGING" -name "*.delta" -exec cp {} build/ \; 2>/dev/null || true
+      - name: Generate checksums
+        run: |
+          set -euo pipefail
+          DELTA_FILES=$(find build -name "*.delta" -type f | sort | tr '\n' ' ' || true)
+          python3 scripts/generate_release_checksums.py "$TAG" build/checksums.json build/supacode.dmg build/supacode.app.zip $DELTA_FILES
+      - name: Create release and upload assets
+        run: |
+          set -euo pipefail
+          gh release create "$TAG" --title "$TAG" --notes-file build/release-notes.md --target "${{ github.sha }}" -R "$RELEASE_REPO" 2>/dev/null || \
+          gh release edit "$TAG" --target "${{ github.sha }}" -R "$RELEASE_REPO"
+          DELTA_FILES=$(find build -name "*.delta" -type f 2>/dev/null | tr '\n' ' ' || true)
+          gh release upload "$TAG" build/supacode.app.zip build/supacode.dmg build/appcast.xml build/checksums.json $DELTA_FILES --clobber -R "$RELEASE_REPO"
+      - name: Verify download URLs
+        run: |
+          set -euo pipefail
+          curl -fsSL "https://supacode.sh/download/$TAG/checksums.json" -o /dev/null
+          curl -fsSL "https://supacode.sh/download/$TAG/supacode.app.zip" -o /dev/null
+          curl -fsSL "https://supacode.sh/download/$TAG/supacode.dmg" -o /dev/null
+
+  # Ordered after publish-stable so the tip item merges into any freshly cut release. Tolerates a skip
+  # (non-release commits) but blocks on its failure, so the tip merge never runs against a half-published release.
   publish:
     runs-on: ubuntu-latest
-    needs: [check, build, tag]
-    if: needs.check.outputs.should_skip != 'true'
+    needs: [check, build, tag, publish-stable]
+    if: ${{ !cancelled() && needs.check.outputs.should_skip != 'true' && needs.build.result == 'success' && needs.tag.result == 'success' && (needs.publish-stable.result == 'success' || needs.publish-stable.result == 'skipped') }}
     permissions:
       contents: write
     steps:
+      - uses: actions/checkout@v6
       - uses: actions/download-artifact@v7
         with:
           name: build-artifacts
@@ -290,7 +494,8 @@ jobs:
           done
 
           DELTA_FILES=$(find build -name "*.delta" -type f 2>/dev/null | tr '\n' ' ' || true)
-          gh release upload tip build/supacode.dmg build/supacode.app.zip build/appcast.xml $DELTA_FILES --clobber -R "${{ github.repository }}"
+          python3 scripts/generate_release_checksums.py tip build/checksums.json build/supacode.dmg build/supacode.app.zip $DELTA_FILES
+          gh release upload tip build/supacode.dmg build/supacode.app.zip build/appcast.xml build/checksums.json $DELTA_FILES --clobber -R "${{ github.repository }}"
 
           # Store current build as history asset for future delta generation
           MAX_DELTAS=10
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
deleted file mode 100644
index a81f6692f..000000000
--- a/.github/workflows/release.yml
+++ /dev/null
@@ -1,286 +0,0 @@
-name: Release
-
-on:
-  release:
-    types: [published]
-
-concurrency:
-  group: release
-  cancel-in-progress: false
-
-jobs:
-  check:
-    runs-on: ubuntu-latest
-    outputs:
-      should_skip: ${{ steps.check.outputs.should_skip }}
-    steps:
-      - name: Check if release already has artifacts
-        id: check
-        env:
-          GH_TOKEN: ${{ github.token }}
-          TAG: ${{ github.event.release.tag_name }}
-        run: |
-          ASSETS=$(gh release view "$TAG" -R "${{ github.repository }}" --json assets --jq '.assets | length')
-          if [ "$ASSETS" -gt 0 ]; then
-            echo "Release $TAG already has $ASSETS assets, skipping"
-            echo "should_skip=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "should_skip=false" >> "$GITHUB_OUTPUT"
-          fi
-
-  build:
-    runs-on: macos-26
-    needs: [check]
-    if: needs.check.outputs.should_skip != 'true'
-    permissions:
-      contents: read
-      id-token: write
-    env:
-      MISE_HTTP_TIMEOUT: 120
-      MISE_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      DEVELOPER_ID_CERT_P12: ${{ secrets.DEVELOPER_ID_CERT_P12 }}
-      DEVELOPER_ID_CERT_PASSWORD: ${{ secrets.DEVELOPER_ID_CERT_PASSWORD }}
-      DEVELOPER_ID_IDENTITY: ${{ secrets.DEVELOPER_ID_IDENTITY }}
-      KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }}
-      APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-      APPLE_NOTARIZATION_ISSUER: ${{ secrets.APPLE_NOTARIZATION_ISSUER }}
-      APPLE_NOTARIZATION_KEY_ID: ${{ secrets.APPLE_NOTARIZATION_KEY_ID }}
-      APPLE_NOTARIZATION_KEY: ${{ secrets.APPLE_NOTARIZATION_KEY }}
-      SPARKLE_PRIVATE_KEY: ${{ secrets.SPARKLE_PRIVATE_KEY }}
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          submodules: recursive
-      - uses: ./.github/actions/setup-macos
-      - run: echo "TAG=${{ github.event.release.tag_name }}" >> "$GITHUB_ENV"
-      - name: Prepare release overrides
-        env:
-          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
-          POSTHOG_API_KEY: ${{ secrets.POSTHOG_API_KEY }}
-          POSTHOG_HOST: ${{ secrets.POSTHOG_HOST }}
-        run: |
-          set -euo pipefail
-          : "${SENTRY_DSN:?secret SENTRY_DSN is not set}"
-          : "${POSTHOG_API_KEY:?secret POSTHOG_API_KEY is not set}"
-          : "${POSTHOG_HOST:?secret POSTHOG_HOST is not set}"
-          BASE=$(awk -F' = ' '/^CURRENT_PROJECT_VERSION = [0-9]+$/{print $2; exit}' Configurations/Project.xcconfig)
-          BUILD_NUMBER=$((BASE * 1000))
-          mkdir -p build
-          cat > build/ReleaseOverrides.xcconfig <<EOF
-          CURRENT_PROJECT_VERSION = $BUILD_NUMBER
-          SENTRY_DSN = $SENTRY_DSN
-          POSTHOG_API_KEY = $POSTHOG_API_KEY
-          POSTHOG_HOST = $POSTHOG_HOST
-          EOF
-          echo "XCODE_XCCONFIG_FILE=$PWD/build/ReleaseOverrides.xcconfig" >> "$GITHUB_ENV"
-      - name: Setup keychain
-        run: |
-          echo "$DEVELOPER_ID_CERT_P12" | base64 --decode > build-cert.p12
-          security create-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
-          security set-keychain-settings -t 3600 -u build.keychain
-          security unlock-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
-          security import build-cert.p12 -k build.keychain -P "$DEVELOPER_ID_CERT_PASSWORD" -T /usr/bin/codesign -T /usr/bin/security -T /usr/bin/xcodebuild > /dev/null
-          security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$KEYCHAIN_PASSWORD" build.keychain > /dev/null
-          security list-keychains -d user -s build.keychain $(security list-keychains -d user | tr -d '"')
-          security default-keychain -s build.keychain
-          DEVELOPER_ID_IDENTITY_SHA=$(security find-identity -v -p codesigning build.keychain | grep "Developer ID Application" | head -1 | awk '{print $2}')
-          if [ -z "$DEVELOPER_ID_IDENTITY_SHA" ]; then
-            echo "::error::Developer ID Application identity not found in keychain"
-            exit 1
-          fi
-          echo "DEVELOPER_ID_IDENTITY_SHA=$DEVELOPER_ID_IDENTITY_SHA" >> "$GITHUB_ENV"
-      - name: Archive workspace
-        run: make archive
-      - name: Upload dSYMs
-        uses: actions/upload-artifact@v6
-        with:
-          name: dsyms
-          path: build/supacode.xcarchive/dSYMs
-      - run: |
-          cat > build/ExportOptions.plist <<EOF
-          <?xml version="1.0" encoding="UTF-8"?>
-          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-          <plist version="1.0">
-          <dict>
-            <key>method</key>
-            <string>developer-id</string>
-            <key>signingStyle</key>
-            <string>manual</string>
-            <key>signingCertificate</key>
-          <string>$DEVELOPER_ID_IDENTITY</string>
-            <key>teamID</key>
-            <string>$APPLE_TEAM_ID</string>
-          </dict>
-          </plist>
-          EOF
-          make export-archive
-      - name: Re-sign frameworks
-        run: |
-          set -ex
-          APP_PATH="$(find build/export -name "supacode.app" -maxdepth 3 -print -quit)"
-          SPARKLE="$APP_PATH/Contents/Frameworks/Sparkle.framework/Versions/B"
-          bash ./.github/scripts/resign_exported_app.sh build/export
-
-          codesign -d --entitlements - "$APP_PATH/Contents/MacOS/supacode" 2>&1 | tee /tmp/supacode-entitlements.txt
-          grep -q "com.apple.security.device.audio-input" /tmp/supacode-entitlements.txt
-
-          codesign -dv --verbose=4 "$APP_PATH" 2>&1 | grep -E "Authority=Developer ID Application|Timestamp="
-          codesign -dv --verbose=4 "$APP_PATH/Contents/MacOS/supacode" 2>&1 | grep -E "Authority=Developer ID Application|Timestamp="
-          codesign -dv --verbose=4 "$SPARKLE/Updater.app/Contents/MacOS/Updater" 2>&1 | grep -E "Authority=Developer ID Application|Timestamp="
-          codesign -dv --verbose=4 "$SPARKLE/XPCServices/Installer.xpc/Contents/MacOS/Installer" 2>&1 | grep -E "Authority=Developer ID Application|Timestamp="
-          codesign -dv --verbose=4 "$SPARKLE/XPCServices/Downloader.xpc/Contents/MacOS/Downloader" 2>&1 | grep -E "Authority=Developer ID Application|Timestamp="
-          echo "Signature verified successfully"
-      - name: Store notarization credentials
-        run: |
-          echo "$APPLE_NOTARIZATION_KEY" > notarization_key.p8
-          xcrun notarytool store-credentials "notarytool-profile" \
-            --key notarization_key.p8 \
-            --key-id "$APPLE_NOTARIZATION_KEY_ID" \
-            --issuer "$APPLE_NOTARIZATION_ISSUER"
-          rm notarization_key.p8
-      - name: Build DMG
-        run: |
-          APP_PATH="$(find build/export -name "supacode.app" -maxdepth 3 -print -quit)"
-
-          mise exec -- create-dmg "$APP_PATH" build/ \
-            --overwrite \
-            --dmg-title="Supacode" \
-            --identity="$DEVELOPER_ID_IDENTITY_SHA"
-
-          DMG_OUTPUT=$(find build -name "*.dmg" -maxdepth 1 | head -1)
-          if [ "$DMG_OUTPUT" != "build/supacode.dmg" ]; then
-            mv "$DMG_OUTPUT" build/supacode.dmg
-          fi
-      - name: Notarize and staple
-        run: |
-          set -euo pipefail
-          APP_PATH="$(find build/export -name "supacode.app" -maxdepth 3 -print -quit)"
-          NOTARY_RESULT_PATH=build/notarytool-submit.json
-          NOTARY_LOG_PATH=build/notarytool-log.json
-          NOTARY_STATUS=""
-          NOTARY_ID=""
-          for attempt in 1 2 3; do
-            echo "Notarization attempt $attempt..."
-            submit_exit=0
-            if ! xcrun notarytool submit build/supacode.dmg \
-              --keychain-profile "notarytool-profile" \
-              --wait \
-              --output-format json > "$NOTARY_RESULT_PATH"; then
-              submit_exit=$?
-            fi
-            NOTARY_STATUS="$(jq -r '.status // empty' "$NOTARY_RESULT_PATH" 2>/dev/null || true)"
-            NOTARY_ID="$(jq -r '.id // empty' "$NOTARY_RESULT_PATH" 2>/dev/null || true)"
-            cat "$NOTARY_RESULT_PATH" || true
-            if [ "$submit_exit" -eq 0 ] && [ "$NOTARY_STATUS" = "Accepted" ]; then
-              break
-            fi
-            if [ -n "$NOTARY_ID" ]; then
-              xcrun notarytool log "$NOTARY_ID" --keychain-profile "notarytool-profile" > "$NOTARY_LOG_PATH" || true
-              cat "$NOTARY_LOG_PATH" || true
-            fi
-            echo "Attempt $attempt failed, retrying in 30s..."
-            sleep 30
-          done
-          if [ "$NOTARY_STATUS" != "Accepted" ]; then
-            echo "::error::Notarization failed with status '$NOTARY_STATUS'"
-            exit 1
-          fi
-          xcrun stapler staple build/supacode.dmg
-          xcrun stapler staple "$APP_PATH"
-          ditto -c -k --sequesterRsrc --keepParent "$APP_PATH" build/supacode.app.zip
-          VERSION=$(/usr/libexec/PlistBuddy -c "Print :CFBundleShortVersionString" "$APP_PATH/Contents/Info.plist")
-          echo "VERSION=$VERSION" >> "$GITHUB_ENV"
-      - name: Fetch release notes
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          gh release view "$TAG" --json body --jq '.body' > build/release-notes.md
-      - name: Generate appcast with history and deltas
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          set -euo pipefail
-          MAX_DELTAS=10
-          NOTES_FILE=build/release-notes.md
-          STAGING=$(mktemp -d)
-          ARCHIVE=build/supacode.app.zip
-          ARCHIVE_BASE=$(basename "$ARCHIVE")
-          ARCHIVE_BASE="${ARCHIVE_BASE%.zip}"
-          cp "$ARCHIVE" "$STAGING/"
-          cp "$NOTES_FILE" "$STAGING/$ARCHIVE_BASE.md"
-
-          curl -fsSL "https://supacode.sh/download/latest/appcast.xml" -o "$STAGING/appcast.xml" || true
-
-          RELEASE_REPO="supabitapp/supacode"
-          SEEN_VERSIONS=""
-          for i in $(seq 1 $MAX_DELTAS); do
-            PREV_TAG=$(gh release list --limit $i --exclude-drafts --exclude-pre-releases -R "$RELEASE_REPO" --json tagName --jq ".[$((i-1))].tagName" 2>/dev/null || true)
-            if [ -n "$PREV_TAG" ] && [ "$PREV_TAG" != "$TAG" ]; then
-              echo "Downloading $PREV_TAG for delta generation..."
-              gh release download "$PREV_TAG" -p "supacode.app.zip" -O "$STAGING/supacode-$PREV_TAG.app.zip" -R "$RELEASE_REPO" 2>/dev/null || true
-              if [ -f "$STAGING/supacode-$PREV_TAG.app.zip" ]; then
-                BUNDLE_VERSION=$(unzip -p "$STAGING/supacode-$PREV_TAG.app.zip" "supacode.app/Contents/Info.plist" 2>/dev/null | /usr/libexec/PlistBuddy -c "Print :CFBundleShortVersionString" /dev/stdin 2>/dev/null || echo "")
-                if [ -n "$BUNDLE_VERSION" ] && echo "$SEEN_VERSIONS" | grep -q "^$BUNDLE_VERSION$"; then
-                  echo "Skipping $PREV_TAG (duplicate bundle version $BUNDLE_VERSION)"
-                  rm -f "$STAGING/supacode-$PREV_TAG.app.zip"
-                else
-                  [ -n "$BUNDLE_VERSION" ] && SEEN_VERSIONS="$SEEN_VERSIONS$BUNDLE_VERSION"$'\n'
-                  gh release view "$PREV_TAG" -R "$RELEASE_REPO" --json body --jq '.body' > "$STAGING/supacode-$PREV_TAG.app.md" 2>/dev/null || true
-                fi
-              fi
-            fi
-          done
-
-          printf "%s" "$SPARKLE_PRIVATE_KEY" | tr -d '\r\n\t ' | ./bins/generate_appcast --download-url-prefix "https://supacode.sh/download/$TAG/" --full-release-notes-url "https://github.com/supabitapp/supacode/releases" --embed-release-notes --maximum-versions $MAX_DELTAS --maximum-deltas $MAX_DELTAS --delta-compression lzma --ed-key-file - "$STAGING"
-          cp "$STAGING/appcast.xml" build/appcast.xml
-          find "$STAGING" -name "*.delta" -exec cp {} build/ \; 2>/dev/null || true
-      - uses: actions/upload-artifact@v6
-        with:
-          name: build-artifacts
-          path: |
-            build/supacode.app.zip
-            build/supacode.dmg
-            build/appcast.xml
-            build/*.delta
-
-  sentry-dsym:
-    runs-on: ubuntu-latest
-    needs: [check, build]
-    if: needs.check.outputs.should_skip != 'true'
-    steps:
-      - name: Install sentry-cli
-        run: curl -sL https://sentry.io/get-cli/ | sh
-      - uses: actions/download-artifact@v7
-        with:
-          name: dsyms
-          path: dsyms
-      - name: Upload dSYMs to Sentry
-        env:
-          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
-          SENTRY_ORG: supabit
-          SENTRY_PROJECT: supacode
-        run: sentry-cli debug-files upload --include-sources dsyms
-
-  publish:
-    runs-on: ubuntu-latest
-    needs: [check, build]
-    if: needs.check.outputs.should_skip != 'true'
-    permissions:
-      contents: write
-    env:
-      RELEASE_REPO: supabitapp/supacode
-    steps:
-      - run: echo "TAG=${{ github.event.release.tag_name }}" >> "$GITHUB_ENV"
-      - uses: actions/download-artifact@v7
-        with:
-          name: build-artifacts
-          path: build
-      - run: |
-          DELTA_FILES=$(find build -name "*.delta" -type f 2>/dev/null | tr '\n' ' ' || true)
-          gh release upload "$TAG" build/supacode.app.zip build/supacode.dmg build/appcast.xml $DELTA_FILES --clobber -R "$RELEASE_REPO"
-        env:
-          GH_TOKEN: ${{ github.token }}
-      - run: |
-          set -euo pipefail
-          curl -fsSL "https://supacode.sh/download/$TAG/supacode.app.zip" -o /dev/null
-          curl -fsSL "https://supacode.sh/download/$TAG/supacode.dmg" -o /dev/null
diff --git a/.github/workflows/warm-cache.yml b/.github/workflows/warm-cache.yml
deleted file mode 100644
index 374c37def..000000000
--- a/.github/workflows/warm-cache.yml
+++ /dev/null
@@ -1,26 +0,0 @@
-name: warm-cache
-
-on:
-  push:
-    branches:
-      - main
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  warm-cache-debug:
-    runs-on: macos-26
-    permissions:
-      contents: read
-      id-token: write
-    env:
-      MISE_HTTP_TIMEOUT: 120
-      MISE_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          submodules: recursive
-      - uses: ./.github/actions/setup-macos
-      - run: make warm-cache
diff --git a/.gitignore b/.gitignore
index 4a5148706..61a5a0cb7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,9 @@
 ## User settings
 xcuserdata/
 
+## Local build output (xcodebuild -derivedDataPath build).
+build/
+
 ## Obj-C/Swift specific
 *.hmap
 
diff --git a/AGENTS.md b/AGENTS.md
index ec09b2092..ddf02bb3e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,7 @@
 ## Build Commands
 
 ```bash
+make doctor                      # Diagnose build prerequisites (run this first on a new machine)
 make build-ghostty-xcframework  # Rebuild GhosttyKit from Zig source (requires mise)
 make build-app                   # Build macOS app (Debug) via xcodebuild
 make run-app                     # Build and launch Debug app
@@ -21,7 +22,23 @@ xcodebuild test -project supacode.xcodeproj -scheme supacode -destination "platf
   CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY="" -skipMacroValidation
 ```
 
-Requires [mise](https://mise.jdx.dev/) for zig, swiftlint, and xcsift tooling.
+Requires [mise](https://mise.jdx.dev/) for zig, swiftlint, swift-format, xcbeautify, and xcsift tooling. Run `mise install` once to fetch the pinned versions.
+
+## Building on macOS 26.4+ (Tahoe)
+
+On macOS 26.4+ the GhosttyKit build fails to link with a wall of `undefined symbol: _malloc, _free, _sigaction, …` in `build_zcu.o`. **The fix is to build against Xcode 26.3, not the toolchain version.**
+
+**Run `make doctor` first** — it verifies every prerequisite below (mise on PATH, submodules, a Zig-linkable Xcode, license/first-launch, Metal Toolchain, pinned mise tools) and prints the exact command to fix each failure. The build targets also run it automatically as a quiet preflight (skipped on CI, or set `SUPACODE_SKIP_PREFLIGHT=1` to skip it locally). First-time setup, in order:
+
+1. **mise on PATH.** `make` targets call `mise exec`, but mise installs at `~/.local/bin/mise`, which non-login shells don't pick up. Activate it: `echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc` (or add `~/.local/bin` to `PATH`), then `mise install`.
+2. **Submodules.** `git submodule update --init --recursive` (ghostty, zmx, git-wt).
+3. **Xcode 26.3.** The pinned Zig (`0.15.2`, required exactly by ghostty's `build.zig` `requireZig`, and it uses 0.15.2-only stdlib APIs, so bumping Zig is not an option) cannot link the macOS 26.4+ SDK: that SDK's `usr/lib/libSystem.tbd` dropped the plain `arm64-macos` target (keeping only `arm64e-macos`), and Zig 0.15.2's linker won't match — [ziglang/zig#31658](https://github.com/ziglang/zig/issues/31658), fixed only in Zig 0.16+. Install [Xcode 26.3](https://developer.apple.com/download/all/?q=Xcode%2026.3), which ships the macOS 26.2 SDK whose `.tbd` still has `arm64-macos`. **You do not need to `sudo xcode-select -s` it globally** — keep your newer Xcode as the default for other projects. The build auto-detects a Zig-linkable Xcode via `scripts/select-developer-dir.sh` and pins `DEVELOPER_DIR` for just that build (override with `DEVELOPER_DIR=… make build-app` if you want a specific one).
+4. **License + first launch.** A freshly installed Xcode 26.3 must complete these before `DEVELOPER_DIR` works (we observed `DEVELOPER_DIR` alone is insufficient until then): `sudo DEVELOPER_DIR=/Applications/Xcode_26.3.app/Contents/Developer xcodebuild -license accept` and `… -runFirstLaunch`.
+5. **Metal Toolchain.** A fresh Xcode 26.3 ships it uninstalled, and ghostty compiles Metal shaders → `cannot execute tool 'metal' due to missing Metal Toolchain`. Install it into that Xcode (target it explicitly so it lands in 26.3, not whatever is globally selected): `sudo DEVELOPER_DIR=/Applications/Xcode_26.3.app/Contents/Developer xcodebuild -downloadComponent MetalToolchain`.
+
+**Verification quirk:** check the SDK *version*, not just the `arm64-macos` slice. macOS 26.4+ SDKs still list `arm64-macos` in `libSystem.tbd` yet Zig 0.15.2 cannot link them, so grepping that string gives false positives (it accepts Xcode 26.5). `scripts/select-developer-dir.sh` gates on `xcrun --sdk macosx --show-sdk-version` being `<= 26.3` instead. Use the `--sdk macosx` form, not bare `xcrun --show-sdk-version`, which can resolve to the CommandLineTools SDK and mislead you.
+
+**Why no `patches/` entry:** the link failure is in Zig's own self-hosted linker (`build_zcu.o`, the build runner itself), not in ghostty source, so the `patches/*.patch` mechanism — which only patches the ghostty submodule working tree — cannot fix it; and ghostty pins Zig to exactly 0.15.2, so bumping Zig is out. The older-SDK + auto-`DEVELOPER_DIR` approach is the long-term fix until ghostty supports Zig 0.16+.
 
 ## Architecture
 
@@ -112,6 +129,7 @@ Reducer ← .repositories(.worktreeInfoEvent(Event)) ← AsyncStream<Event>
 ### Formatting & Linting
 
 - 2-space indentation, 120 character line length (enforced by `.swift-format.json`)
+- `make format` runs the mise-pinned `swift-format` (`spm:swiftlang/swift-format` in `mise.toml`), NOT the Xcode toolchain's built-in `swift format`. The pin keeps formatting reproducible across contributors' Xcodes — an unpinned toolchain formatter rewrites the whole tree (e.g. Swift call-site trailing commas) and produces spurious churn. Bump the pin in lockstep with the Swift toolchain (tag `60X.x` ↔ Swift 6.X).
 - Trailing commas are mandatory (enforced by `.swiftlint.yml`)
 - SwiftLint runs in strict mode; never disable lint rules without permission
 - Custom SwiftLint rule: `store_state_mutation_in_views` — do not mutate `store.*` directly in view files; send actions instead
@@ -181,5 +199,5 @@ Reducer ← .repositories(.worktreeInfoEvent(Event)) ← AsyncStream<Event>
 
 ## Submodules
 
-- `ThirdParty/ghostty` (`https://github.com/ghostty-org/ghostty`): Source dependency used to build `Frameworks/GhosttyKit.xcframework` and terminal resources.
+- `ThirdParty/ghostty` (`https://github.com/ghostty-org/ghostty`): Source dependency used to build `Frameworks/GhosttyKit.xcframework` and terminal resources. The pin tracks upstream; local changes live as out-of-tree patches in `patches/*.patch`, applied to the working tree by `scripts/build-ghostty.sh` before `zig build` and reverted on exit (the pin is never moved, no fork). On a ghostty bump a patch may stop applying and the build fails loudly: refresh the patch, and prefer upstreaming it to retire the carry cost. Run one ghostty build at a time (the apply/revert shares the submodule working tree).
 - `Resources/git-wt` (`https://github.com/khoi/git-wt.git`): Bundled `wt` CLI used by Supacode Git worktree flows at runtime.
diff --git a/Configurations/Project.xcconfig b/Configurations/Project.xcconfig
index 673e9d9af..a91124f13 100644
--- a/Configurations/Project.xcconfig
+++ b/Configurations/Project.xcconfig
@@ -1,5 +1,5 @@
-MARKETING_VERSION = 0.10.1
-CURRENT_PROJECT_VERSION = 141
+MARKETING_VERSION = 0.10.4
+CURRENT_PROJECT_VERSION = 144
 POSTHOG_API_KEY =
 POSTHOG_HOST =
 SENTRY_DSN =
diff --git a/Makefile b/Makefile
index 78c6c58be..9d44b1a14 100644
--- a/Makefile
+++ b/Makefile
@@ -16,19 +16,29 @@ TUIST_GENERATION_STAMP_DIR := $(CURRENT_MAKEFILE_DIR)/.build/.tuist-generated-st
 TUIST_INSTALL_STAMP := $(TUIST_GENERATION_STAMP_DIR)/.installed
 TUIST_DEVELOPMENT_GENERATION_STAMP := $(TUIST_GENERATION_STAMP_DIR)/development
 TUIST_SOURCE_GENERATION_STAMP := $(TUIST_GENERATION_STAMP_DIR)/none
-TUIST_SOURCE_RELEASE_GENERATION_STAMP := $(TUIST_GENERATION_STAMP_DIR)/none-release
+TUIST_RELEASE_GENERATION_STAMP := $(TUIST_GENERATION_STAMP_DIR)/development-release
 TUIST_GENERATION_INPUTS := Project.swift Workspace.swift Tuist.swift Tuist/Package.swift $(wildcard Tuist/Package.resolved) $(PROJECT_CONFIG_PATH) mise.toml scripts/build-ghostty.sh scripts/build-zmx.sh
 TUIST_GENERATE_CACHE_PROFILE ?= development
 TUIST_CACHE_CONFIGURATION ?= Debug
 VERSION ?=
 BUILD ?=
+TITLE ?=
+BODY ?=
+# Export so headline markdown reaches the script without a shell re-parse of quotes/backticks.
+export VERSION BUILD TITLE BODY
 XCODEBUILD_FLAGS ?=
+SUPACODE_SKIP_PREFLIGHT ?=
+
+# Export a Zig-linkable Xcode per build recipe (no global xcode-select -s). Plain
+# assignment so a missing Xcode aborts the recipe under -e.
+SELECT_DEVELOPER_DIR = DEVELOPER_DIR="$$(./scripts/select-developer-dir.sh)"; export DEVELOPER_DIR
 
 .DEFAULT_GOAL := help
-.PHONY: build-ghostty-xcframework build-zmx generate-project generate-project-sources inspect-dependencies warm-cache build-app run-app install-dev-build archive export-archive format lint check test bump-version bump-and-release log-stream
+.PHONY: doctor preflight build-ghostty-xcframework build-zmx generate-project generate-project-sources inspect-dependencies warm-cache build-app package-app run-app install-dev-build archive export-archive format lint check test bump-version bump-and-release log-stream
 
 ifdef CI
 TUIST_INSTALL_FLAGS := --force-resolved-versions
+SUPACODE_SKIP_PREFLIGHT := 1
 else
 TUIST_INSTALL_FLAGS :=
 endif
@@ -42,7 +52,7 @@ generate-project: $(TUIST_GENERATION_STAMP_DIR)/$(TUIST_GENERATE_CACHE_PROFILE)
 
 generate-project-sources: $(TUIST_SOURCE_GENERATION_STAMP) # Resolve packages and generate a source-only Xcode workspace
 
-$(TUIST_INSTALL_STAMP): $(TUIST_GENERATION_INPUTS)
+$(TUIST_INSTALL_STAMP): $(TUIST_GENERATION_INPUTS) | preflight
 	mkdir -p "$(TUIST_GENERATION_STAMP_DIR)"
 	mise exec -- tuist install $(TUIST_INSTALL_FLAGS)
 	touch "$@"
@@ -58,7 +68,8 @@ $(TUIST_GENERATION_STAMP_DIR)/%: $(TUIST_GENERATION_INPUTS) $(TUIST_INSTALL_STAM
 	mise exec -- tuist generate --no-open --cache-profile "$*"
 	touch "$@"
 
-$(TUIST_SOURCE_RELEASE_GENERATION_STAMP): $(TUIST_GENERATION_INPUTS) $(TUIST_INSTALL_STAMP)
+# Consumes the warmed Release binary cache, so archive compiles only the app shell.
+$(TUIST_RELEASE_GENERATION_STAMP): $(TUIST_GENERATION_INPUTS) $(TUIST_INSTALL_STAMP)
 	mkdir -p "$(TUIST_GENERATION_STAMP_DIR)"
 	find "$(TUIST_GENERATION_STAMP_DIR)" -mindepth 1 -maxdepth 1 ! -name '.installed' -delete
 	rm -rf supacode.xcodeproj supacode.xcworkspace
@@ -66,13 +77,22 @@ $(TUIST_SOURCE_RELEASE_GENERATION_STAMP): $(TUIST_GENERATION_INPUTS) $(TUIST_INS
 		[ -e "$$path" ] || continue; \
 		rm -rf "$$path"; \
 	done
-	mise exec -- tuist generate --no-open --cache-profile none --configuration Release
+	mise exec -- tuist generate --no-open --cache-profile development --configuration Release
 	touch "$@"
 
-build-ghostty-xcframework: # Build ghostty framework
+doctor: # Diagnose build prerequisites and print the fix for each failure
+	@./scripts/doctor.sh
+
+# Order-only preflight on the install stamp, so every build flow fails fast with
+# doctor's actionable message before tuist / xcodebuild / zig run. Never forces a
+# rebuild. Skipped when SUPACODE_SKIP_PREFLIGHT is set (CI sets it above).
+preflight:
+	@[ -n "$(SUPACODE_SKIP_PREFLIGHT)" ] || ./scripts/doctor.sh --quiet
+
+build-ghostty-xcframework: | preflight # Build ghostty framework
 	./scripts/build-ghostty.sh
 
-build-zmx: # Build bundled zmx binary from ThirdParty/zmx submodule
+build-zmx: | preflight # Build bundled zmx binary from ThirdParty/zmx submodule
 	./scripts/build-zmx.sh
 
 inspect-dependencies: $(TUIST_INSTALL_STAMP) # Check for implicit Tuist dependencies
@@ -82,17 +102,31 @@ warm-cache: $(TUIST_INSTALL_STAMP) # Warm the full Tuist cacheable graph
 	mise exec -- tuist cache warm --configuration $(TUIST_CACHE_CONFIGURATION)
 
 build-app: $(TUIST_DEVELOPMENT_GENERATION_STAMP) # Build the macOS app (Debug)
-	bash -o pipefail -c 'xcodebuild -workspace "$(PROJECT_WORKSPACE)" -scheme "$(APP_SCHEME)" -configuration Debug build -skipMacroValidation 2>&1 | mise exec -- xcbeautify --disable-logging'
+	$(SELECT_DEVELOPER_DIR); \
+	bash -o pipefail -c 'xcodebuild -workspace "$(PROJECT_WORKSPACE)" -scheme "$(APP_SCHEME)" -configuration Debug build -skipMacroValidation $(XCODEBUILD_FLAGS) 2>&1 | { mise exec -- xcbeautify --disable-logging || cat; }'
 
-run-app: build-app # Build then launch (Debug) with log streaming
+package-app: build-app # Zip the Debug build to build/supacode.app.zip (for CI artifacts)
+	@mkdir -p build
 	@settings="$$(xcodebuild -workspace "$(PROJECT_WORKSPACE)" -scheme "$(APP_SCHEME)" -configuration Debug -showBuildSettings -json 2>/dev/null)"; \
 	build_dir="$$(echo "$$settings" | jq -r '.[0].buildSettings.BUILT_PRODUCTS_DIR')"; \
 	product="$$(echo "$$settings" | jq -r '.[0].buildSettings.FULL_PRODUCT_NAME')"; \
+	src="$$build_dir/$$product"; \
+	if [ ! -d "$$src" ]; then echo "app not found: $$src"; exit 1; fi; \
+	rm -f build/supacode.app.zip; \
+	ditto -c -k --sequesterRsrc --keepParent "$$src" build/supacode.app.zip; \
+	echo "packaged build/supacode.app.zip"
+
+run-app: build-app # Build then launch (Debug) with log streaming
+	@$(SELECT_DEVELOPER_DIR); \
+	settings="$$(xcodebuild -workspace "$(PROJECT_WORKSPACE)" -scheme "$(APP_SCHEME)" -configuration Debug -showBuildSettings -json 2>/dev/null)"; \
+	build_dir="$$(echo "$$settings" | jq -r '.[0].buildSettings.BUILT_PRODUCTS_DIR')"; \
+	product="$$(echo "$$settings" | jq -r '.[0].buildSettings.FULL_PRODUCT_NAME')"; \
 	exec_name="$$(echo "$$settings" | jq -r '.[0].buildSettings.EXECUTABLE_NAME')"; \
 	"$$build_dir/$$product/Contents/MacOS/$$exec_name"
 
 install-dev-build: build-app # install dev build to /Applications
-	@settings="$$(xcodebuild -workspace "$(PROJECT_WORKSPACE)" -scheme "$(APP_SCHEME)" -configuration Debug -showBuildSettings -json 2>/dev/null)"; \
+	@$(SELECT_DEVELOPER_DIR); \
+	settings="$$(xcodebuild -workspace "$(PROJECT_WORKSPACE)" -scheme "$(APP_SCHEME)" -configuration Debug -showBuildSettings -json 2>/dev/null)"; \
 	build_dir="$$(echo "$$settings" | jq -r '.[0].buildSettings.BUILT_PRODUCTS_DIR')"; \
 	product="$$(echo "$$settings" | jq -r '.[0].buildSettings.FULL_PRODUCT_NAME')"; \
 	src="$$build_dir/$$product"; \
@@ -106,22 +140,25 @@ install-dev-build: build-app # install dev build to /Applications
 	ditto "$$src" "$$dst"; \
 	echo "installed $$dst"
 
-archive: $(TUIST_SOURCE_RELEASE_GENERATION_STAMP) # Archive Release build for distribution
+archive: $(TUIST_RELEASE_GENERATION_STAMP) # Archive Release build for distribution
 	mkdir -p build
-	bash -o pipefail -c 'xcodebuild -workspace "$(PROJECT_WORKSPACE)" -scheme "$(APP_SCHEME)" -configuration Release -destination "generic/platform=macOS" -archivePath build/supacode.xcarchive archive CODE_SIGN_STYLE=Manual DEVELOPMENT_TEAM="$$APPLE_TEAM_ID" CODE_SIGN_IDENTITY="$$DEVELOPER_ID_IDENTITY_SHA" OTHER_CODE_SIGN_FLAGS="--timestamp" -skipMacroValidation $(XCODEBUILD_FLAGS) 2>&1 | mise exec -- xcbeautify --quiet --disable-logging'
+	$(SELECT_DEVELOPER_DIR); \
+	bash -o pipefail -c 'xcodebuild -workspace "$(PROJECT_WORKSPACE)" -scheme "$(APP_SCHEME)" -configuration Release -destination "generic/platform=macOS" -archivePath build/supacode.xcarchive archive CODE_SIGN_STYLE=Manual DEVELOPMENT_TEAM="$$APPLE_TEAM_ID" CODE_SIGN_IDENTITY="$$DEVELOPER_ID_IDENTITY_SHA" OTHER_CODE_SIGN_FLAGS="--timestamp" -skipMacroValidation $(XCODEBUILD_FLAGS) 2>&1 | { mise exec -- xcbeautify --quiet --disable-logging || cat; }'
 
 export-archive: # Export xarchive
-	bash -o pipefail -c 'xcodebuild -exportArchive -archivePath build/supacode.xcarchive -exportPath build/export -exportOptionsPlist build/ExportOptions.plist 2>&1 | mise exec -- xcbeautify --quiet --disable-logging'
+	$(SELECT_DEVELOPER_DIR); \
+	bash -o pipefail -c 'xcodebuild -exportArchive -archivePath build/supacode.xcarchive -exportPath build/export -exportOptionsPlist build/ExportOptions.plist 2>&1 | { mise exec -- xcbeautify --quiet --disable-logging || cat; }'
 
 test: $(TUIST_DEVELOPMENT_GENERATION_STAMP) # Run all tests
-	@if [ -t 1 ]; then \
-		bash -o pipefail -c 'xcodebuild test -workspace "$(PROJECT_WORKSPACE)" -scheme "$(APP_SCHEME)" -destination "platform=macOS" CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY="" -skipMacroValidation -parallel-testing-enabled NO 2>&1 | mise exec -- xcbeautify --disable-logging'; \
+	@$(SELECT_DEVELOPER_DIR); \
+	if [ -t 1 ]; then \
+		bash -o pipefail -c 'xcodebuild test -workspace "$(PROJECT_WORKSPACE)" -scheme "$(APP_SCHEME)" -destination "platform=macOS" CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY="" -skipMacroValidation -parallel-testing-enabled NO 2>&1 | { mise exec -- xcbeautify --disable-logging || cat; }'; \
 	else \
 		xcodebuild test -workspace "$(PROJECT_WORKSPACE)" -scheme "$(APP_SCHEME)" -destination "platform=macOS" CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY="" -skipMacroValidation -parallel-testing-enabled NO; \
 	fi
 
-format: # Format code with swift format (local only).
-	swift format -p --in-place --recursive --configuration ./.swift-format.json supacode supacode-cli supacodeTests SupacodeSettingsShared SupacodeSettingsFeature
+format: # Format code with swift-format (mise-pinned for reproducibility).
+	mise exec -- swift-format --parallel --in-place --recursive --configuration ./.swift-format.json supacode supacode-cli supacodeTests SupacodeSettingsShared SupacodeSettingsFeature
 
 lint: # Lint code with swiftlint
 	mise exec -- swiftlint lint --quiet --config .swiftlint.yml
@@ -131,58 +168,9 @@ check: format lint # Format and lint
 log-stream: # Stream logs from the app via log stream
 	log stream --predicate 'subsystem == "app.supabit.supacode"' --style compact --color always
 
-bump-version: # Bump app version (usage: make bump-version [VERSION=x.x.x] [BUILD=123])
-	@if [ -z "$(VERSION)" ]; then \
-		current="$$(/usr/bin/awk -F' = ' '/^MARKETING_VERSION = [0-9.]+$$/{print $$2; exit}' "$(PROJECT_CONFIG_PATH)")"; \
-		if [ -z "$$current" ]; then \
-			echo "error: MARKETING_VERSION not found"; \
-			exit 1; \
-		fi; \
-		major="$$(echo "$$current" | cut -d. -f1)"; \
-		minor="$$(echo "$$current" | cut -d. -f2)"; \
-		patch="$$(echo "$$current" | cut -d. -f3)"; \
-		version="$$major.$$minor.$$((patch + 1))"; \
-	else \
-		if ! echo "$(VERSION)" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$$'; then \
-			echo "error: VERSION must be in x.x.x format"; \
-			exit 1; \
-		fi; \
-		version="$(VERSION)"; \
-	fi; \
-	if [ -z "$(BUILD)" ]; then \
-		build="$$(/usr/bin/awk -F' = ' '/^CURRENT_PROJECT_VERSION = [0-9]+$$/{print $$2; exit}' "$(PROJECT_CONFIG_PATH)")"; \
-		if [ -z "$$build" ]; then \
-			echo "error: CURRENT_PROJECT_VERSION not found"; \
-			exit 1; \
-		fi; \
-		build="$$((build + 1))"; \
-	else \
-		if ! echo "$(BUILD)" | grep -qE '^[0-9]+$$'; then \
-			echo "error: BUILD must be an integer"; \
-			exit 1; \
-		fi; \
-		build="$(BUILD)"; \
-	fi; \
-	sed -i '' "s/^MARKETING_VERSION = [0-9.]*/MARKETING_VERSION = $$version/g" \
-		"$(PROJECT_CONFIG_PATH)"; \
-	sed -i '' "s/^CURRENT_PROJECT_VERSION = [0-9]*/CURRENT_PROJECT_VERSION = $$build/g" \
-		"$(PROJECT_CONFIG_PATH)"; \
-	git add "$(PROJECT_CONFIG_PATH)"; \
-	git commit -S -m "bump v$$version"; \
-	git tag -s "v$$version" -m "v$$version"; \
-	echo "version bumped to $$version (build $$build), tagged v$$version"
-
-bump-and-release: bump-version # Bump version and push tags to trigger release
+bump-version: # Bump app version (usage: make bump-version VERSION=x.y.z [BUILD=123] [TITLE=… BODY=…])
+	@./scripts/bump-version.sh
+
+# main.yml detects the tag at HEAD and cuts the release, prepending its headline.
+bump-and-release: bump-version # Bump version and push tags to trigger the release (usage: make bump-and-release VERSION=x.y.z [TITLE=… BODY=…])
 	git push --follow-tags
-	@tag="$$(git describe --tags --abbrev=0)"; \
-	repo="$$(gh repo view --json nameWithOwner -q .nameWithOwner)"; \
-	prev="$$(gh release view --json tagName -q .tagName 2>/dev/null || echo '')"; \
-	tmp="$$(mktemp)"; \
-	if [ -n "$$prev" ]; then \
-		gh api "repos/$$repo/releases/generate-notes" -f tag_name="$$tag" -f previous_tag_name="$$prev" --jq '.body' > "$$tmp"; \
-	else \
-		gh api "repos/$$repo/releases/generate-notes" -f tag_name="$$tag" --jq '.body' > "$$tmp"; \
-	fi; \
-	$${EDITOR:-vim} "$$tmp"; \
-	gh release create "$$tag" --notes-file "$$tmp"; \
-	rm -f "$$tmp"
diff --git a/README.md b/README.md
index e61930a1e..46642d805 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,23 @@ Native terminal coding agents command center.
 ## Requirements
 
 - macOS 26.0+
-- [mise](https://mise.jdx.dev/) (for dependencies)
+- [mise](https://mise.jdx.dev/) (for dependencies) — add `~/.local/bin` to your `PATH`
+- **Xcode 26.3** if you are on macOS 26.4+ — see below
+- git submodules: `git submodule update --init --recursive`
+
+### Building on macOS 26.4+ (Tahoe)
+
+The GhosttyKit build uses a pinned Zig (`0.15.2`, required exactly by ghostty) whose linker can't link the macOS 26.4+ SDK — that SDK dropped the `arm64-macos` slice from `libSystem.tbd` ([ziglang/zig#31658](https://github.com/ziglang/zig/issues/31658)), so the build fails with a wall of `undefined symbol` errors. Install [Xcode 26.3](https://developer.apple.com/download/all/?q=Xcode%2026.3) (it ships the macOS 26.2 SDK, which still has `arm64-macos`). You **don't** need to switch it globally — the build auto-detects a Zig-linkable Xcode and pins it for just that build, so a newer Xcode can stay your default. After installing it once:
+
+```bash
+# accept the license and finish first launch (required before the build can use it)
+sudo DEVELOPER_DIR=/Applications/Xcode_26.3.app/Contents/Developer xcodebuild -license accept
+sudo DEVELOPER_DIR=/Applications/Xcode_26.3.app/Contents/Developer xcodebuild -runFirstLaunch
+# install the Metal Toolchain into that Xcode (ghostty compiles Metal shaders; a fresh Xcode ships it uninstalled)
+sudo DEVELOPER_DIR=/Applications/Xcode_26.3.app/Contents/Developer xcodebuild -downloadComponent MetalToolchain
+```
+
+See [AGENTS.md](AGENTS.md) for the full rationale.
 
 ## Building
 
@@ -25,11 +41,14 @@ make mac-warm-cache
 ```
 
 ```bash
+make doctor                      # Diagnose build prerequisites and print fixes
 make build-ghostty-xcframework   # Build GhosttyKit from Zig source
 make build-app                   # Build macOS app (Debug)
 make run-app                     # Build and launch
 ```
 
+`make doctor` checks every prerequisite (mise, submodules, a Zig-linkable Xcode, the Metal Toolchain, pinned tools) and prints the exact fix for anything missing. The build targets run it automatically as a quiet preflight.
+
 ## Development
 
 ```bash
diff --git a/SupacodeSettingsFeature/Models/SettingsRepositorySummary.swift b/SupacodeSettingsFeature/Models/SettingsRepositorySummary.swift
index f488c8fe8..aa3e06952 100644
--- a/SupacodeSettingsFeature/Models/SettingsRepositorySummary.swift
+++ b/SupacodeSettingsFeature/Models/SettingsRepositorySummary.swift
@@ -1,17 +1,33 @@
 import Foundation
+import SupacodeSettingsShared
 
 public struct SettingsRepositorySummary: Equatable, Hashable, Sendable {
   public var id: String
   public var name: String
   public var isGitRepository: Bool
+  /// The SSH host the repository lives on, `nil` for local. Carried (rather than
+  /// a bare bool) so the per-repo settings key can brand remote repos by host.
+  public var host: RemoteHost?
+  /// The repository's real root URL, used to key its per-repo settings. For a
+  /// local repo this equals `URL(fileURLWithPath: id)`; for a remote repo `id`
+  /// is a `remote:` key (not a path), so the bare remote path must be passed in
+  /// explicitly so the settings key matches the worktree's `repositoryRootURL`.
+  public var rootURL: URL
 
-  public var rootURL: URL {
-    URL(fileURLWithPath: id).standardizedFileURL
-  }
+  /// Lives on an SSH host. Partitions the settings sidebar into Local / Remote.
+  public var isRemote: Bool { host != nil }
 
-  public init(id: String, name: String, isGitRepository: Bool = true) {
+  public init(
+    id: String,
+    name: String,
+    isGitRepository: Bool = true,
+    host: RemoteHost? = nil,
+    rootURL: URL? = nil
+  ) {
     self.id = id
     self.name = name
     self.isGitRepository = isGitRepository
+    self.host = host
+    self.rootURL = (rootURL ?? URL(fileURLWithPath: id)).standardizedFileURL
   }
 }
diff --git a/SupacodeSettingsFeature/Reducer/RepositorySettingsFeature.swift b/SupacodeSettingsFeature/Reducer/RepositorySettingsFeature.swift
index 2ffcfa2e7..c4341c480 100644
--- a/SupacodeSettingsFeature/Reducer/RepositorySettingsFeature.swift
+++ b/SupacodeSettingsFeature/Reducer/RepositorySettingsFeature.swift
@@ -8,6 +8,7 @@ public struct RepositorySettingsFeature {
   @ObservableState
   public struct State: Equatable {
     public var rootURL: URL
+    public var host: RemoteHost?
     public var isGitRepository: Bool
     public var settings: RepositorySettings
     public var globalDefaultWorktreeBaseDirectoryPath: String?
@@ -32,6 +33,7 @@ public struct RepositorySettingsFeature {
 
     public init(
       rootURL: URL,
+      host: RemoteHost? = nil,
       isGitRepository: Bool = true,
       settings: RepositorySettings,
       globalDefaultWorktreeBaseDirectoryPath: String? = nil,
@@ -44,6 +46,7 @@ public struct RepositorySettingsFeature {
       isBranchDataLoaded: Bool = false
     ) {
       self.rootURL = rootURL
+      self.host = host
       self.isGitRepository = isGitRepository
       self.settings = settings
       self.globalDefaultWorktreeBaseDirectoryPath = globalDefaultWorktreeBaseDirectoryPath
@@ -82,7 +85,7 @@ public struct RepositorySettingsFeature {
 
   @CasePathable
   public enum Delegate: Equatable {
-    case settingsChanged(URL)
+    case settingsChanged(URL, host: RemoteHost?)
   }
 
   @Dependency(RepositorySettingsGitClient.self) private var gitClient
@@ -96,7 +99,7 @@ public struct RepositorySettingsFeature {
       case .task:
         let rootURL = state.rootURL
         let isGitRepository = state.isGitRepository
-        @Shared(.repositorySettings(rootURL)) var repositorySettings
+        @Shared(.repositorySettings(rootURL, host: state.host)) var repositorySettings
         @Shared(.settingsFile) var settingsFile
         let settings = repositorySettings
         let global = settingsFile.global
@@ -175,9 +178,10 @@ public struct RepositorySettingsFeature {
         state.isBareRepository = isBareRepository
         guard updatedSettings != settings else { return .none }
         let rootURL = state.rootURL
-        @Shared(.repositorySettings(rootURL)) var repositorySettings
+        let host = state.host
+        @Shared(.repositorySettings(rootURL, host: host)) var repositorySettings
         $repositorySettings.withLock { $0 = updatedSettings }
-        return .send(.delegate(.settingsChanged(rootURL)))
+        return .send(.delegate(.settingsChanged(rootURL, host: host)))
 
       case .branchDataLoaded(let branches, let defaultBaseRef):
         state.defaultWorktreeBaseRef = defaultBaseRef
@@ -244,13 +248,14 @@ public struct RepositorySettingsFeature {
   /// Persists the current settings and notifies the delegate.
   private func persistAndNotify(state: inout State) -> Effect<Action> {
     let rootURL = state.rootURL
+    let host = state.host
     var normalizedSettings = state.settings
     normalizedSettings.worktreeBaseDirectoryPath = SupacodePaths.normalizedWorktreeBaseDirectoryPath(
       normalizedSettings.worktreeBaseDirectoryPath,
       repositoryRootURL: rootURL
     )
-    @Shared(.repositorySettings(rootURL)) var repositorySettings
+    @Shared(.repositorySettings(rootURL, host: host)) var repositorySettings
     $repositorySettings.withLock { $0 = normalizedSettings }
-    return .send(.delegate(.settingsChanged(rootURL)))
+    return .send(.delegate(.settingsChanged(rootURL, host: host)))
   }
 }
diff --git a/SupacodeSettingsFeature/Reducer/SettingsFeature.swift b/SupacodeSettingsFeature/Reducer/SettingsFeature.swift
index 2dcebacd0..502fcc07b 100644
--- a/SupacodeSettingsFeature/Reducer/SettingsFeature.swift
+++ b/SupacodeSettingsFeature/Reducer/SettingsFeature.swift
@@ -255,9 +255,7 @@ public struct SettingsFeature {
           var updatedSettings = settings
           updatedSettings.defaultEditorID = normalizedDefaultEditorID
           updatedSettings.defaultWorktreeBaseDirectoryPath = normalizedWorktreeBaseDirPath
-          normalizedSettings = updatedSettings
-          @Shared(.settingsFile) var settingsFile
-          $settingsFile.withLock { $0.global = normalizedSettings }
+          normalizedSettings = persistGlobalSettings(updatedSettings)
         }
         state.appearanceMode = normalizedSettings.appearanceMode
         state.defaultEditorID = normalizedSettings.defaultEditorID
@@ -580,15 +578,22 @@ public struct SettingsFeature {
   }
 
   private func persist(_ state: State) -> Effect<Action> {
-    let settings = state.globalSettings
-    @Shared(.settingsFile) var settingsFile
-    $settingsFile.withLock { $0.global = settings }
+    let settings = persistGlobalSettings(state.globalSettings)
     if settings.analyticsEnabled {
       analyticsClient.capture("settings_changed", nil)
     }
     return .send(.delegate(.settingsChanged(settings)))
   }
 
+  @discardableResult
+  private func persistGlobalSettings(_ settings: GlobalSettings) -> GlobalSettings {
+    @Shared(.settingsFile) var settingsFile
+    $settingsFile.withLock {
+      $0.global = settings
+    }
+    return settings
+  }
+
   private func synchronizeRepositorySelection(for state: inout State) {
     guard let selection = state.selection else {
       state.repositorySettings = nil
@@ -603,10 +608,15 @@ public struct SettingsFeature {
       state.repositorySettings = nil
       return
     }
-    if state.repositorySettings?.rootURL != summary.rootURL {
-      @Shared(.repositorySettings(summary.rootURL)) var repositorySettings
+    // Compare on host too: two remote hosts at the same path share a `rootURL`
+    // but are distinct repositories, so a path-only check would keep stale state.
+    if state.repositorySettings?.rootURL != summary.rootURL
+      || state.repositorySettings?.host != summary.host
+    {
+      @Shared(.repositorySettings(summary.rootURL, host: summary.host)) var repositorySettings
       state.repositorySettings = RepositorySettingsFeature.State(
         rootURL: summary.rootURL,
+        host: summary.host,
         isGitRepository: summary.isGitRepository,
         settings: repositorySettings
       )
diff --git a/SupacodeSettingsShared/App/AppShortcuts.swift b/SupacodeSettingsShared/App/AppShortcuts.swift
index 0ed4ce5c3..a621d2726 100644
--- a/SupacodeSettingsShared/App/AppShortcuts.swift
+++ b/SupacodeSettingsShared/App/AppShortcuts.swift
@@ -5,14 +5,14 @@ import SwiftUI
 
 // Compile-time checkable shortcut identifier.
 public nonisolated enum AppShortcutID: Codable, Hashable, Sendable, CodingKeyRepresentable {
-  case commandPalette, openSettings, checkForUpdates, showMainWindow
+  case commandPalette, worktreeSwitcher, openSettings, checkForUpdates, showMainWindow
   case toggleLeftSidebar, revealInSidebar
   case newWorktree, refreshWorktrees, archivedWorktrees, archiveWorktree
   case deleteWorktree, confirmWorktreeAction
   case selectNextWorktree, selectPreviousWorktree
   case worktreeHistoryBack, worktreeHistoryForward
   case selectWorktree(Int)
-  case openWorktree, revealInFinder, openRepository, openPullRequest, copyPath
+  case openWorktree, revealInFinder, openRepository, addRemoteRepository, openPullRequest, copyPath
   case runScript, stopRunScript
   case jumpToLatestUnread
 
@@ -36,6 +36,7 @@ public nonisolated enum AppShortcutID: Codable, Hashable, Sendable, CodingKeyRep
   private var stableKey: String {
     switch self {
     case .commandPalette: "commandPalette"
+    case .worktreeSwitcher: "worktreeSwitcher"
     case .openSettings: "openSettings"
     case .checkForUpdates: "checkForUpdates"
     case .showMainWindow: "showMainWindow"
@@ -55,6 +56,7 @@ public nonisolated enum AppShortcutID: Codable, Hashable, Sendable, CodingKeyRep
     case .openWorktree: "openWorktree"
     case .revealInFinder: "revealInFinder"
     case .openRepository: "openRepository"
+    case .addRemoteRepository: "addRemoteRepository"
     case .openPullRequest: "openPullRequest"
     case .copyPath: "copyPath"
     case .runScript: "runScript"
@@ -65,6 +67,7 @@ public nonisolated enum AppShortcutID: Codable, Hashable, Sendable, CodingKeyRep
 
   private static let stableKeyMap: [String: AppShortcutID] = [
     "commandPalette": .commandPalette,
+    "worktreeSwitcher": .worktreeSwitcher,
     "openSettings": .openSettings,
     "checkForUpdates": .checkForUpdates,
     "showMainWindow": .showMainWindow,
@@ -84,6 +87,7 @@ public nonisolated enum AppShortcutID: Codable, Hashable, Sendable, CodingKeyRep
     "openFinder": .openWorktree,
     "revealInFinder": .revealInFinder,
     "openRepository": .openRepository,
+    "addRemoteRepository": .addRemoteRepository,
     "openPullRequest": .openPullRequest,
     "copyPath": .copyPath,
     "runScript": .runScript,
@@ -106,6 +110,7 @@ public nonisolated enum AppShortcutID: Codable, Hashable, Sendable, CodingKeyRep
   public var displayName: String {
     switch self {
     case .commandPalette: "Command Palette"
+    case .worktreeSwitcher: "Go to Worktree"
     case .openSettings: "Open Settings"
     case .checkForUpdates: "Check For Updates"
     case .showMainWindow: "Show Main Window"
@@ -125,6 +130,7 @@ public nonisolated enum AppShortcutID: Codable, Hashable, Sendable, CodingKeyRep
     case .openWorktree: "Open Worktree"
     case .revealInFinder: "Reveal in Finder"
     case .openRepository: "Open Repository or Folder"
+    case .addRemoteRepository: "Add Remote Repository or Folder"
     case .openPullRequest: "Open Pull Request"
     case .copyPath: "Copy Path"
     case .runScript: "Run Script"
@@ -265,31 +271,13 @@ public struct AppShortcutGroup: Identifiable {
 // MARK: - Registry.
 
 public enum AppShortcuts {
-  private struct TabSelectionBinding {
-    let unicode: String
-    let physical: String
-    let tabIndex: Int
-  }
-
-  private static let tabSelectionBindings: [TabSelectionBinding] = [
-    TabSelectionBinding(unicode: "1", physical: "digit_1", tabIndex: 1),
-    TabSelectionBinding(unicode: "2", physical: "digit_2", tabIndex: 2),
-    TabSelectionBinding(unicode: "3", physical: "digit_3", tabIndex: 3),
-    TabSelectionBinding(unicode: "4", physical: "digit_4", tabIndex: 4),
-    TabSelectionBinding(unicode: "5", physical: "digit_5", tabIndex: 5),
-    TabSelectionBinding(unicode: "6", physical: "digit_6", tabIndex: 6),
-    TabSelectionBinding(unicode: "7", physical: "digit_7", tabIndex: 7),
-    TabSelectionBinding(unicode: "8", physical: "digit_8", tabIndex: 8),
-    TabSelectionBinding(unicode: "9", physical: "digit_9", tabIndex: 9),
-    TabSelectionBinding(unicode: "0", physical: "digit_0", tabIndex: 10),
-  ]
-
   // MARK: - Shortcut definitions.
 
-  public static let commandPalette = AppShortcut(id: .commandPalette, key: "p", modifiers: .command)
+  public static let commandPalette = AppShortcut(id: .commandPalette, key: "p", modifiers: [.command, .shift])
+  public static let worktreeSwitcher = AppShortcut(id: .worktreeSwitcher, key: "p", modifiers: .command)
   public static let openSettings = AppShortcut(id: .openSettings, key: ",", modifiers: .command)
   public static let checkForUpdates = AppShortcut(id: .checkForUpdates, key: "u", modifiers: .command)
-  public static let showMainWindow = AppShortcut(id: .showMainWindow, key: "0", modifiers: .command)
+  public static let showMainWindow = AppShortcut(id: .showMainWindow, key: "0", modifiers: [.command, .shift])
 
   public static let toggleLeftSidebar = AppShortcut(id: .toggleLeftSidebar, key: "[", modifiers: .command)
   public static let revealInSidebar = AppShortcut(id: .revealInSidebar, key: "e", modifiers: [.command, .shift])
@@ -335,11 +323,13 @@ public enum AppShortcuts {
   public static let selectWorktree7 = AppShortcut(id: .selectWorktree(7), key: "7", modifiers: [.control])
   public static let selectWorktree8 = AppShortcut(id: .selectWorktree(8), key: "8", modifiers: [.control])
   public static let selectWorktree9 = AppShortcut(id: .selectWorktree(9), key: "9", modifiers: [.control])
-  public static let selectWorktree0 = AppShortcut(id: .selectWorktree(0), key: "0", modifiers: [.control])
 
   public static let openWorktree = AppShortcut(id: .openWorktree, key: "o", modifiers: .command)
   public static let revealInFinder = AppShortcut(id: .revealInFinder, key: "r", modifiers: [.command, .option])
   public static let openRepository = AppShortcut(id: .openRepository, key: "o", modifiers: [.command, .shift])
+  public static let addRemoteRepository = AppShortcut(
+    id: .addRemoteRepository, key: "k", modifiers: [.command, .shift]
+  )
   public static let openPullRequest = AppShortcut(id: .openPullRequest, key: "g", modifiers: [.command, .control])
   public static let copyPath = AppShortcut(id: .copyPath, key: "c", modifiers: [.command, .shift])
   public static let runScript = AppShortcut(id: .runScript, key: "r", modifiers: .command)
@@ -350,7 +340,7 @@ public enum AppShortcuts {
 
   public static let worktreeSelection: [AppShortcut] = [
     selectWorktree1, selectWorktree2, selectWorktree3, selectWorktree4, selectWorktree5,
-    selectWorktree6, selectWorktree7, selectWorktree8, selectWorktree9, selectWorktree0,
+    selectWorktree6, selectWorktree7, selectWorktree8, selectWorktree9,
   ]
 
   public static func worktreeSelectionShortcutDisplay(
@@ -378,7 +368,7 @@ public enum AppShortcuts {
   public static let groups: [AppShortcutGroup] = [
     AppShortcutGroup(
       category: .general,
-      shortcuts: [commandPalette, openSettings, checkForUpdates, showMainWindow]
+      shortcuts: [worktreeSwitcher, commandPalette, openSettings, checkForUpdates, showMainWindow]
     ),
     AppShortcutGroup(category: .sidebar, shortcuts: [toggleLeftSidebar, revealInSidebar]),
     AppShortcutGroup(
@@ -393,8 +383,8 @@ public enum AppShortcuts {
     AppShortcutGroup(
       category: .actions,
       shortcuts: [
-        openWorktree, revealInFinder, openRepository, openPullRequest, copyPath, runScript, stopRunScript,
-        jumpToLatestUnread,
+        openWorktree, revealInFinder, openRepository, addRemoteRepository, openPullRequest,
+        copyPath, runScript, stopRunScript, jumpToLatestUnread,
       ]
     ),
   ]
@@ -405,11 +395,28 @@ public enum AppShortcuts {
 
   // MARK: - Tab selection Ghostty bindings.
 
-  public static let tabSelectionGhosttyKeybindArguments: [String] = tabSelectionBindings.flatMap { binding in
-    [
-      "--keybind=ctrl+\(binding.unicode)=goto_tab:\(binding.tabIndex)",
-      "--keybind=ctrl+\(binding.physical)=goto_tab:\(binding.tabIndex)",
-    ]
+  // Ghostty `goto_tab` bindings for worktree selection, derived from the user's
+  // effective shortcuts instead of a fixed list. A disabled shortcut produces no
+  // binding, so its chord (e.g. ⌃6) reaches the terminal instead of being captured.
+  // A remapped shortcut moves the binding to the chosen key. The physical `digit_N`
+  // variant is emitted only while the binding stays the default Control+digit, so
+  // non-US keyboard layouts keep working.
+  public static func tabSelectionGhosttyKeybindArguments(
+    from overrides: [AppShortcutID: AppShortcutOverride]
+  ) -> [String] {
+    worktreeSelection.flatMap { shortcut -> [String] in
+      guard case .selectWorktree(let slot) = shortcut.id,
+        let effective = shortcut.effective(from: overrides)
+      else {
+        return []
+      }
+      let tabIndex = slot == 0 ? 10 : slot
+      var arguments = ["--keybind=\(effective.ghosttyKeybind)=goto_tab:\(tabIndex)"]
+      if effective.ghosttyKeybind == "ctrl+\(slot)" {
+        arguments.append("--keybind=ctrl+digit_\(slot)=goto_tab:\(tabIndex)")
+      }
+      return arguments
+    }
   }
 
   // MARK: - Ghostty CLI arguments.
@@ -420,7 +427,7 @@ public enum AppShortcuts {
 
   public static func ghosttyCLIKeybindArguments(from overrides: [AppShortcutID: AppShortcutOverride]) -> [String] {
     let effectiveShortcuts = all.compactMap { $0.effective(from: overrides) }
-    return effectiveShortcuts.map(\.ghosttyUnbindArgument) + tabSelectionGhosttyKeybindArguments
+    return effectiveShortcuts.map(\.ghosttyUnbindArgument) + tabSelectionGhosttyKeybindArguments(from: overrides)
   }
 
   // MARK: - Conflict detection.
diff --git a/SupacodeSettingsShared/BusinessLogic/AgentHookSettingsCommand.swift b/SupacodeSettingsShared/BusinessLogic/AgentHookSettingsCommand.swift
index e3fb815f9..e49c44289 100644
--- a/SupacodeSettingsShared/BusinessLogic/AgentHookSettingsCommand.swift
+++ b/SupacodeSettingsShared/BusinessLogic/AgentHookSettingsCommand.swift
@@ -13,7 +13,7 @@ nonisolated enum HookEvent: String {
 
 nonisolated enum AgentHookSettingsCommand {
   /// Sentinel comment appended to every Supacode-installed hook command.
-  /// `AgentHookCommandOwnership` uses this — and ONLY this — to identify
+  /// `AgentHookCommandOwnership` uses this (and ONLY this) to identify
   /// managed commands. `SUPACODE_SOCKET_PATH` is documented public API
   /// (CLI skill env table, Pi extension example, deeplink reference), so
   /// matching on the env-var name alone would silently strip user-authored
@@ -22,7 +22,7 @@ nonisolated enum AgentHookSettingsCommand {
 
   /// Documented public env var. Used as ONE half of the legacy CLI-shim
   /// fingerprint (paired with `supacode integration event`); never matched
-  /// alone — user-authored hooks reference it legitimately.
+  /// alone. User-authored hooks reference it legitimately.
   static let socketPathEnvVar = "SUPACODE_SOCKET_PATH"
 
   /// Markers present in legacy Supacode hook commands (pre-socket).
@@ -43,22 +43,11 @@ nonisolated enum AgentHookSettingsCommand {
     + #" && [ -n "${SUPACODE_TAB_ID:-}" ]"#
     + #" && [ -n "${SUPACODE_SURFACE_ID:-}" ]"#
 
-  private static let ids =
-    "$SUPACODE_WORKTREE_ID $SUPACODE_TAB_ID $SUPACODE_SURFACE_ID"
-
-  /// Both stdout AND stderr go to /dev/null — Codex parses hook stdout as
-  /// structured JSON and would reject the socket ack otherwise.
-  private static func managed(_ pipeline: String) -> String {
-    "\(envCheck) && \(pipeline) >/dev/null 2>&1 || true \(ownershipMarker)"
-  }
-
-  /// Builds a single shell command that fires every `event` envelope and
-  /// optionally forwards stdin as a notification, all under one envCheck
-  /// guard with one sentinel. Stdin is consumed once via `payload=$(cat)`
-  /// so the same payload can be relayed after the fixed envelopes. The
-  /// precondition rejects a no-op invocation because the empty-empty
-  /// fallthrough would otherwise emit `{ ; }` (shell syntax error masked
-  /// by `|| true`).
+  /// Composes the OSC 3008 hook command: one guard, then (once that passes) the
+  /// tty resolve plus a presence emit per event and/or a notify emit, all in a
+  /// single brace group whose output is suppressed. Guarding first keeps the
+  /// command truly inert outside Supacode (no `ps` runs when the surface id is
+  /// unset). The precondition rejects a no-op invocation that would emit nothing.
   static func compositeCommand(
     events: [HookEvent],
     forwardStdinAsNotification: Bool,
@@ -68,43 +57,16 @@ nonisolated enum AgentHookSettingsCommand {
       !events.isEmpty || forwardStdinAsNotification,
       "compositeCommand needs at least one side-effect (events or stdin forward).",
     )
-    if events.count == 1, !forwardStdinAsNotification {
-      return managed(envelopePipeline(event: events[0], agent: agent))
-    }
-    if events.isEmpty, forwardStdinAsNotification {
-      return managed(notifyPipeline(agent: agent, payloadExpr: nil))
-    }
-    var steps: [String] = []
-    if forwardStdinAsNotification { steps.append("payload=$(cat)") }
-    for event in events {
-      steps.append(envelopePipeline(event: event, agent: agent))
-    }
-    if forwardStdinAsNotification {
-      steps.append(notifyPipeline(agent: agent, payloadExpr: #""$payload""#))
-    }
-    return managed("{ \(steps.joined(separator: "; ")); }")
-  }
-
-  private static func envelopePipeline(event: HookEvent, agent: SkillAgent) -> String {
-    let envelope =
-      #"{\"event\":\"\#(event.rawValue)\","#
-      + #"\"v\":1,\"agent\":\"\#(agent.rawValue)\","#
-      + #"\"surface_id\":\"$SUPACODE_SURFACE_ID\",\"pid\":$PPID}"#
-    return #"printf '%s' "\#(envelope)" | /usr/bin/nc -U -w1 "$SUPACODE_SOCKET_PATH""#
+    var steps: [String] = [AgentPresenceOSC.ttyResolveSnippet]
+    steps += events.map { AgentPresenceOSC.emitShell(event: $0, agent: agent) }
+    if forwardStdinAsNotification { steps.append(AgentPresenceOSC.emitNotifyShell(agent: agent)) }
+    return "\(oscGuardExpr) && { \(steps.joined(separator: "; ")); } >/dev/null 2>&1 || true \(ownershipMarker)"
   }
 
-  /// `payloadExpr == nil` → forward stdin live via `cat`. Non-nil → relay
-  /// a previously-stashed shell expression (so the composite path can
-  /// consume stdin once and reuse it after event envelopes).
-  private static func notifyPipeline(agent: SkillAgent, payloadExpr: String?) -> String {
-    let body: String
-    if let payloadExpr {
-      body = #"printf '%s' \#(payloadExpr)"#
-    } else {
-      body = "cat"
-    }
-    return
-      #"{ printf '%s \#(agent.rawValue)\n' "\#(ids)"; \#(body); }"#
-      + #" | /usr/bin/nc -U -w1 "$SUPACODE_SOCKET_PATH""#
+  /// Guard for the OSC command: a surface id present (the no-op-outside-Supacode
+  /// gate). Fires both locally and over SSH; the pid suffix inside the presence
+  /// emit is what's gated on the socket path, not the emission itself.
+  private static var oscGuardExpr: String {
+    #"[ -n "${\#(AgentPresenceOSC.surfaceEnvVar):-}" ]"#
   }
 }
diff --git a/SupacodeSettingsShared/BusinessLogic/AgentIntegrationFactory.swift b/SupacodeSettingsShared/BusinessLogic/AgentIntegrationFactory.swift
index de55e7328..175635672 100644
--- a/SupacodeSettingsShared/BusinessLogic/AgentIntegrationFactory.swift
+++ b/SupacodeSettingsShared/BusinessLogic/AgentIntegrationFactory.swift
@@ -12,8 +12,10 @@ nonisolated enum AgentIntegrationFactory {
     switch agent {
     case .claude: claude(homeDirectoryURL: homeDirectoryURL, fileManager: fileManager)
     case .codex: codex(homeDirectoryURL: homeDirectoryURL, fileManager: fileManager)
+    case .copilot: copilot(homeDirectoryURL: homeDirectoryURL, fileManager: fileManager)
     case .kiro: kiro(homeDirectoryURL: homeDirectoryURL, fileManager: fileManager)
     case .pi: pi(homeDirectoryURL: homeDirectoryURL, fileManager: fileManager)
+    case .opencode: opencode(homeDirectoryURL: homeDirectoryURL, fileManager: fileManager)
     }
   }
 
@@ -91,6 +93,42 @@ nonisolated enum AgentIntegrationFactory {
     )
   }
 
+  private static func opencode(homeDirectoryURL: URL, fileManager: FileManager) -> AgentIntegration {
+    let installer = OpenCodePluginInstaller(
+      homeDirectoryURL: homeDirectoryURL, fileManager: fileManager)
+    let skill = CLISkillInstaller()
+    return AgentIntegration(
+      agent: .opencode,
+      components: [
+        AgentIntegration.Component(
+          kind: .unifiedHooks,
+          state: { installer.installState() },
+          install: { try installer.install() },
+          uninstall: { try installer.uninstall() }
+        ),
+        skillComponent(agent: .opencode, installer: skill),
+      ]
+    )
+  }
+
+  private static func copilot(homeDirectoryURL: URL, fileManager: FileManager) -> AgentIntegration {
+    let installer = CopilotHooksInstaller(
+      homeDirectoryURL: homeDirectoryURL, fileManager: fileManager)
+    let skill = CLISkillInstaller()
+    return AgentIntegration(
+      agent: .copilot,
+      components: [
+        AgentIntegration.Component(
+          kind: .unifiedHooks,
+          state: { installer.installState() },
+          install: { try installer.install() },
+          uninstall: { try installer.uninstall() }
+        ),
+        skillComponent(agent: .copilot, installer: skill),
+      ]
+    )
+  }
+
   private static func skillComponent(
     agent: SkillAgent, installer: CLISkillInstaller
   ) -> AgentIntegration.Component {
diff --git a/SupacodeSettingsShared/BusinessLogic/AgentPresenceOSC.swift b/SupacodeSettingsShared/BusinessLogic/AgentPresenceOSC.swift
new file mode 100644
index 000000000..689ce1984
--- /dev/null
+++ b/SupacodeSettingsShared/BusinessLogic/AgentPresenceOSC.swift
@@ -0,0 +1,262 @@
+import Foundation
+
+/// OSC 3008 (UAPI hierarchical context signal) wire format that carries the
+/// agent-presence event lifecycle over the terminal stream, so the badge tracks
+/// state over SSH where the local Unix socket can't be reached. The sequence is
+/// inert in any terminal that doesn't handle OSC 3008 (no toast, no side effect).
+///
+/// Emit shape: `OSC 3008 ; <action>=<agent> ; event=<event>[ ; pid=<pid>] ST`.
+/// libghostty splits that into `id = <agent>` (the context id, up to the first
+/// `;`) and `metadata = "event=<event>[;pid=<pid>]"`, which is what `parse`
+/// receives. `parse` derives the event solely from the `event=` field and ignores
+/// the start/end action byte.
+/// - attribution is by the receiving surface, so no surface id is carried;
+/// - `event` is the `HookEvent` rawValue;
+/// - `pid` is the agent's LOCAL process id, present only when the hook ran on the
+///   same host (gated on `SUPACODE_SOCKET_PATH`); it feeds the app's liveness
+///   sweep so a crashed local agent is reaped. Omitted over SSH.
+///
+/// The same transport also carries the rich notification leg
+/// (`kind=notify;title=<base64>;body=<base64>`); the emitter extracts the display
+/// title/body so the wire stays small and the app carries no agent-specific JSON
+/// shape. Presence and notify are disjoint metadata shapes.
+///
+/// Signals are unauthenticated: anything that can write to the terminal can emit
+/// one, and the worst case is a spurious badge or notification (text is
+/// control-char-sanitized and length-capped app-side). Emission is gated on
+/// `SUPACODE_SURFACE_ID` so it no-ops outside a Supacode surface.
+///
+/// Single source of truth for both the emit side (the agent hook) and the parse
+/// side (the app), so the field names can't drift.
+public nonisolated enum AgentPresenceOSC {
+  /// Env var present only on Supacode surfaces, so its presence is the
+  /// no-op-outside-Supacode emit gate.
+  public static let surfaceEnvVar = "SUPACODE_SURFACE_ID"
+
+  static let eventField = "event"
+  static let pidField = "pid"
+  static let kindField = "kind"
+  static let titleField = "title"
+  static let bodyField = "body"
+  static let notifyKind = "notify"
+
+  /// Notify body source keys, in display precedence. Used by the shell extractor
+  /// (`emitNotifyShell`); the Pi extension sends its body directly.
+  public static let notifyBodyKeys = ["message", "last_assistant_message", "assistant_response"]
+
+  /// Emit-side byte caps. Keep the notify metadata under libghostty's 2048-byte
+  /// OSC buffer, over which the whole sequence is discarded (not truncated).
+  static let notifyBodyByteBudget = 1000
+  static let notifyTitleByteBudget = 160
+
+  /// A parsed presence signal.
+  public struct Signal: Equatable, Sendable {
+    /// Context id, i.e. the agent rawValue.
+    public let agent: String
+    /// A known HookEvent rawValue. Parse rejects unknown values; stored as
+    /// String so wire concerns don't leak into the enum.
+    public let eventRawValue: String
+    /// The agent's LOCAL process id. The emit gates it on `SUPACODE_SOCKET_PATH`
+    /// so a local hook carries it and a remote one omits it; a forged positive
+    /// pid at worst pins a live-looking badge until surface close.
+    public let pid: pid_t?
+  }
+
+  /// Parse the OSC 3008 context id + raw key=value metadata (as surfaced by
+  /// libghostty) into a `Signal`. Returns nil for anything that isn't a
+  /// well-formed presence signal with a known event.
+  public static func parse(id: String, metadata: String) -> Signal? {
+    guard !id.isEmpty else { return nil }
+    guard let fields = parseFields(metadata) else { return nil }
+    guard
+      let rawEvent = fields[Substring(eventField)],
+      HookEvent(rawValue: String(rawEvent)) != nil
+    else { return nil }
+    return Signal(
+      agent: id,
+      eventRawValue: String(rawEvent),
+      pid: parsePid(fields[Substring(pidField)]),
+    )
+  }
+
+  /// Parse the optional `pid=` field. Rejects non-numeric and non-positive
+  /// values: a 0 / negative pid would let `kill(_:0)` match the caller's process
+  /// group and pin a permanent badge in the liveness sweep.
+  private static func parsePid(_ raw: Substring?) -> pid_t? {
+    guard let raw, let value = pid_t(raw), value > 0 else { return nil }
+    return value
+  }
+
+  /// True when the metadata carries `kind=notify`. Cheap routing check (presence
+  /// vs notify) that inspects the `kind` field, not a raw substring, so a base64
+  /// `body` value that happens to contain "kind=notify" can't misroute.
+  public static func isNotifyMetadata(_ metadata: String) -> Bool {
+    parseFields(metadata)?[Substring(kindField)] == Substring(notifyKind)
+  }
+
+  /// Split the OSC 3008 raw metadata into its `key=value` fields. Standard base64
+  /// values are framing-safe here: their alphabet (A-Za-z0-9+/=) has no `;`, and
+  /// the value keeps everything after the FIRST `=` (`firstIndex(of:)`), so base64
+  /// `=` padding survives intact.
+  ///
+  /// Duplicate `event` / `kind` keys are rejected: a repeated key would otherwise
+  /// pin perceived state to the last occurrence, which a splice into the wire
+  /// could exploit to flip `event=` or inject `kind=notify`. All other duplicate
+  /// keys keep the historical last-write-wins behavior.
+  public static func parseFields(_ metadata: String) -> [Substring: Substring]? {
+    var fields: [Substring: Substring] = [:]
+    for pair in metadata.split(separator: ";", omittingEmptySubsequences: true) {
+      guard let equalsIndex = pair.firstIndex(of: "=") else { continue }
+      let key = pair[..<equalsIndex]
+      if fields[key] != nil, Self.dedupedFields.contains(key) {
+        return nil
+      }
+      fields[key] = pair[pair.index(after: equalsIndex)...]
+    }
+    return fields
+  }
+
+  private static let dedupedFields: Set<Substring> = [
+    Substring(eventField), Substring(kindField),
+  ]
+
+  /// A parsed notification signal with already-decoded display text.
+  public struct NotifySignal: Equatable, Sendable {
+    public let agent: String
+    /// Both nil-on-empty; the caller falls back to the agent name for a missing
+    /// title and shows a title-only toast for a missing body.
+    public let title: String?
+    public let body: String?
+    /// Raw base64 byte count of the body field on the wire, before decode. A
+    /// non-zero count alongside a nil `body` means a truncation the shed loop
+    /// couldn't recover, so the caller can log the silent-failure case.
+    public let wireBodyByteCount: Int
+  }
+
+  /// Parse `kind=notify;title=<base64>;body=<base64>`. Requires the notify kind;
+  /// title/body are optional.
+  public static func parseNotify(id: String, metadata: String) -> NotifySignal? {
+    guard !id.isEmpty else { return nil }
+    guard let fields = parseFields(metadata) else { return nil }
+    guard fields[Substring(kindField)] == Substring(notifyKind) else { return nil }
+    return NotifySignal(
+      agent: id,
+      title: decodedNotifyField(fields[Substring(titleField)]),
+      body: decodedNotifyField(fields[Substring(bodyField)]),
+      wireBodyByteCount: fields[Substring(bodyField)]?.utf8.count ?? 0,
+    )
+  }
+
+  private static func decodedNotifyField(_ raw: Substring?) -> String? {
+    guard let raw, let text = decodeNotifyValue(String(raw)), !text.isEmpty else { return nil }
+    return text
+  }
+
+  /// Reverse one base64 notify field back to display text. A field byte-capped at
+  /// emit can end mid-escape or mid-UTF8, so trailing bytes are shed until the
+  /// quoted value parses as a JSON string (`JSONDecoder` rejects both an invalid
+  /// UTF-8 tail and a dangling escape). nil only on non-base64 input; an
+  /// undecodable-but-base64 field collapses to "" (treated as absent, not a
+  /// parse failure).
+  static func decodeNotifyValue(_ base64: String) -> String? {
+    guard var data = Data(base64Encoded: base64) else { return nil }
+    let quote = Data([0x22])
+    let decoder = JSONDecoder()
+    // 12 = full `\uXXXX\uXXXX` surrogate-pair length; covers any mid-pair cut (worst dangling tail is 11 bytes).
+    for _ in 0...min(12, data.count) {
+      if let text = try? decoder.decode(String.self, from: quote + data + quote) {
+        return text
+      }
+      if data.isEmpty { break }
+      data.removeLast()
+    }
+    return ""
+  }
+
+  /// The OSC 3008 action for an event: session_end ends a context, everything
+  /// else starts / updates one. The app keys off `event=` in the metadata, not
+  /// this action, so it is descriptive rather than load-bearing.
+  static func action(for event: HookEvent) -> String {
+    event == .sessionEnd ? "end" : "start"
+  }
+
+  /// The `key=value` metadata a PRESENCE signal carries (everything after the
+  /// context id). `parse` recovers the event from this exact shape. `pidSuffix`
+  /// is appended verbatim (e.g. `;pid=123`) so the emit can splice in a
+  /// shell-built, conditionally-empty suffix. See `notifyMetadata` for the
+  /// notify counterpart.
+  static func metadata(event: HookEvent, pidSuffix: String = "") -> String {
+    "\(eventField)=\(event.rawValue)\(pidSuffix)"
+  }
+
+  /// Shell that resolves `$__tty` to a writable terminal device for the OSC emits.
+  /// Agents run hooks without a controlling terminal (`/dev/tty` open fails), so
+  /// the hook recovers the terminal its parent agent is attached to via
+  /// `ps -o tty=`. `ps` reports a bare name (`ttys039` on macOS, `pts/5` on
+  /// Linux), so a `/dev/` prefix is added; a parent with no tty (`??`) falls back
+  /// to `/dev/tty` for the rare context that does have a controlling terminal.
+  static let ttyResolveSnippet =
+    #"__tty=$(ps -o tty= -p "$PPID" 2>/dev/null | tr -d '[:space:]'); "#
+    + #"case "$__tty" in *[0-9]*) __tty="/dev/${__tty#/dev/}";; *) __tty="/dev/tty";; esac"#
+
+  /// Shell `printf` that emits the OSC 3008 presence sequence for `event`. Written
+  /// to the `$__tty` device resolved by `ttyResolveSnippet` so it reaches the
+  /// terminal even though the hook has no controlling terminal and captured
+  /// stdout. The caller guards emission on `SUPACODE_SURFACE_ID` and runs
+  /// `ttyResolveSnippet` first.
+  ///
+  /// The pid suffix is gated on `SUPACODE_SOCKET_PATH` (set only on the local
+  /// host) so a local hook carries `$PPID` and a remote one omits it; a forged
+  /// positive pid at worst pins a live-looking badge until surface close. The
+  /// suffix is built in shell and filled into a trailing `%s`, empty when remote.
+  static func emitShell(event: HookEvent, agent: SkillAgent) -> String {
+    // Trailing %s for the shell-built, conditionally-empty pid suffix.
+    let meta = metadata(event: event, pidSuffix: "%s")
+    let payload = #"\033]3008;\#(action(for: event))=\#(agent.rawValue);\#(meta)\033\\"#
+    return #"__sp=""; [ -n "${SUPACODE_SOCKET_PATH:-}" ] && __sp=";\#(pidField)=$PPID"; "#
+      + #"printf '\#(payload)' "$__sp" > "$__tty""#
+  }
+
+  /// The `key=value` metadata a notify signal carries; `title` / `body` are base64.
+  static func notifyMetadata(title: String, body: String) -> String {
+    "\(kindField)=\(notifyKind);\(titleField)=\(title);\(bodyField)=\(body)"
+  }
+
+  /// Portable awk that extracts one JSON string value from the agent's hook JSON
+  /// on stdin. `keys` is a comma-separated precedence list (first non-empty wins);
+  /// the raw escaped value is copied verbatim up to the first unescaped `"` and
+  /// capped to `budget` (a mid-escape cut is tolerated by `decodeNotifyValue`).
+  /// Matches the first `"key":` occurrence, assuming a flat top-level payload.
+  /// No `RS`/`\x` tricks and no single quote, so it is portable and shell-safe.
+  /// The caller runs it under `LC_ALL=C` so `length`/`substr` are byte-based
+  /// (gawk in a UTF-8 locale would otherwise count characters and overshoot 2048).
+  /// Best-effort by design: a body nested inside an object (e.g. the key appears
+  /// in an inner object before the top-level one) is not extracted correctly. The
+  /// agents we target emit flat payloads; the structured Pi extension path is the
+  /// canonical one when a nested shape is needed.
+  static let notifyExtractAwk =
+    #"function ws(c){return c==" "||c=="\t"||c=="\n"||c=="\r"}"#
+    + #"function fv(s,key,  p,i,n,c,o,e){p="\""key"\"";i=index(s,p);if(i==0)return "";"#
+    + #"i+=length(p);n=length(s);while(i<=n){if(ws(substr(s,i,1)))i++;else break}"#
+    + #"if(substr(s,i,1)!=":")return "";i++;while(i<=n){if(ws(substr(s,i,1)))i++;else break}"#
+    + #"if(substr(s,i,1)!="\"")return "";i++;o="";e=0;while(i<=n){c=substr(s,i,1);"#
+    + #"if(e){o=o c;e=0;i++;continue}if(c=="\\"){o=o c;e=1;i++;continue}if(c=="\"")break;o=o c;i++}return o}"#
+    + #"{d=d $0}END{n=split(keys,ks,",");v="";for(j=1;j<=n;j++){v=fv(d,ks[j]);if(v!="")break}"#
+    + #"if(length(v)>budget+0)v=substr(v,1,budget+0);printf "%s",v}"#
+
+  /// Reads the hook JSON from stdin once, extracts a bounded title/body via a
+  /// portable `awk` pass (no `jq`/`python`, so it works over SSH), base64s each,
+  /// and emits the OSC 3008 notify. Sending only the display fields keeps the wire
+  /// under libghostty's 2048-byte OSC ceiling. Locked to STANDARD base64.
+  /// `readsStdin: false` skips the `__in=$(cat)` capture when the caller already set `$__in`.
+  static func emitNotifyShell(agent: SkillAgent, readsStdin: Bool = true) -> String {
+    let payload = #"\033]3008;start=\#(agent.rawValue);\#(notifyMetadata(title: "%s", body: "%s"))\033\\"#
+    let bodyKeys = notifyBodyKeys.joined(separator: ",")
+    return (readsStdin ? #"__in=$(cat); "# : "")
+      + #"__t=$(printf '%s' "$__in" | LC_ALL=C awk -v keys="\#(titleField)" "#
+      + #"-v budget=\#(notifyTitleByteBudget) '\#(notifyExtractAwk)' | base64 | tr -d '\n'); "#
+      + #"__b=$(printf '%s' "$__in" | LC_ALL=C awk -v keys="\#(bodyKeys)" "#
+      + #"-v budget=\#(notifyBodyByteBudget) '\#(notifyExtractAwk)' | base64 | tr -d '\n'); "#
+      + #"printf '\#(payload)' "$__t" "$__b" > "$__tty""#
+  }
+}
diff --git a/SupacodeSettingsShared/BusinessLogic/CLISkillContent.swift b/SupacodeSettingsShared/BusinessLogic/CLISkillContent.swift
index 1a54580d9..e7e89090b 100644
--- a/SupacodeSettingsShared/BusinessLogic/CLISkillContent.swift
+++ b/SupacodeSettingsShared/BusinessLogic/CLISkillContent.swift
@@ -365,4 +365,66 @@ nonisolated enum CLISkillContent {
     Flags: `-w` (worktree), `-t` (tab), `-s` (surface), `-r` (repo), `-c` (script UUID for `worktree run`/`stop`), `-i` (input), `-d` (direction), `-n` (new ID).
     Env var defaults only target your own shell session. Pass explicit IDs for created resources.
     """
+  // MARK: - OpenCode.
+
+  // OpenCode uses SKILL.md with YAML frontmatter (same structure as Kiro).
+  static let opencodeSkillMd = """
+    ---
+    name: \(skillName)
+    description: \(description)
+    ---
+
+    # Supacode CLI
+
+    Control Supacode from the terminal. The `supacode` command is available in all Supacode terminal sessions.
+
+    ## CRITICAL: ID Tracking
+
+    **NEVER call `supacode tab new` or `supacode surface split` without capturing
+    the output.** They print the new UUID to stdout. Without it you cannot target
+    the resource afterward.
+
+    **NEVER omit `-t`/`-s` when targeting a created resource.** The env vars point
+    to your own shell, not to anything you created.
+
+    For new tabs, surface ID = tab ID.
+
+    ### Correct:
+
+    ```sh
+    TAB_ID=$(supacode tab new -i "npm start")
+    SPLIT_ID=$(supacode surface split -t "$TAB_ID" -s "$TAB_ID" -d v -i "npm test")
+    supacode surface close -t "$TAB_ID" -s "$SPLIT_ID"
+    supacode tab close -t "$TAB_ID"
+    ```
+
+    ### WRONG:
+
+    ```sh
+    supacode tab new -i "npm start"           # BAD: not captured
+    supacode surface split -d v -i "test"     # BAD: missing -t/-s, targets your shell
+    ```
+
+    ## Commands
+
+    - `supacode worktree [list [-f]|focus|run [-c]|stop [-c]|script list|archive|unarchive|delete|pin|unpin] [-w <id>]`
+    - `supacode tab [list [-w] [-f]|focus|new|close] [-w <id>] [-t <id>] [-i <cmd>] [-n <uuid>]`
+    - `supacode surface [list [-w] [-t] [-f]|focus|split|close] [-w <id>] [-t <id>] [-s <id>] [-i <cmd>] [-d h|v] [-n <uuid>]`
+    - `supacode repo [list | open <path> | worktree-new [-r <id>] [--branch] [--base] [--fetch] [--name] [--location]]`
+    - `supacode settings [<section>]`
+    - `supacode socket`
+
+    `list` outputs one ID per line (percent-encoded for worktrees/repos, UUIDs for tabs/surfaces).
+    `worktree script list` outputs tab-separated `<uuid>\\t<kind>\\t<displayName>` rows; running scripts are ANSI-underlined.
+    Use these IDs directly as `-w`, `-t`, `-s`, `-r`, `-c` flag values.
+
+    Flags: `-w` (worktree), `-t` (tab), `-s` (surface), `-r` (repo), `-c` (script UUID for `worktree run`/`stop`), `-i` (input), `-d` (direction), `-n` (new ID).
+    Env var defaults only target your own shell session. Pass explicit IDs for created resources.
+    """
+
+  // MARK: - Copilot.
+
+  // Generic CLI doc, same as OpenCode's (content is agent-agnostic).
+  static let copilotSkillMd = opencodeSkillMd
+
 }
diff --git a/SupacodeSettingsShared/BusinessLogic/CLISkillInstaller.swift b/SupacodeSettingsShared/BusinessLogic/CLISkillInstaller.swift
index 6d81a5f70..eb128b863 100644
--- a/SupacodeSettingsShared/BusinessLogic/CLISkillInstaller.swift
+++ b/SupacodeSettingsShared/BusinessLogic/CLISkillInstaller.swift
@@ -48,8 +48,10 @@ nonisolated struct CLISkillInstaller {
     switch agent {
     case .claude: CLISkillContent.claudeSkill
     case .codex: CLISkillContent.codexSkillMd
+    case .copilot: CLISkillContent.copilotSkillMd
     case .kiro: CLISkillContent.kiroSkillMd
     case .pi: CLISkillContent.piSkillMd
+    case .opencode: CLISkillContent.opencodeSkillMd
     }
   }
 }
diff --git a/SupacodeSettingsShared/BusinessLogic/CopilotHookSettings.swift b/SupacodeSettingsShared/BusinessLogic/CopilotHookSettings.swift
new file mode 100644
index 000000000..74fdd92c5
--- /dev/null
+++ b/SupacodeSettingsShared/BusinessLogic/CopilotHookSettings.swift
@@ -0,0 +1,62 @@
+import Foundation
+
+/// Builds `~/.copilot/hooks/supacode.json`. Copilot auto-loads every JSON file
+/// there, so Supacode owns its own file (like Pi/OpenCode) and emits the shared
+/// OSC 3008 presence signals from per-event `bash` hooks.
+nonisolated enum CopilotHookSettings {
+  static let fileName = "supacode.json"
+
+  /// Sentinel marking the file as Supacode-managed; install/uninstall key off it.
+  static let ownershipMarker = AgentHookSettingsCommand.ownershipMarker
+
+  /// Deterministic, so `installState` can detect drift by a byte-for-byte compare.
+  /// Throws rather than returning a sentinel: an empty string would be written as a
+  /// valid-looking but marker-less file the installer could no longer recognize.
+  static func source() throws -> String {
+    let encoder = JSONEncoder()
+    encoder.outputFormatting = [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes]
+    let data = try encoder.encode(Payload())
+    guard let string = String(data: data, encoding: .utf8) else {
+      throw CopilotHooksInstallerError.encodingFailed
+    }
+    return string
+  }
+
+  private static func command(for events: [HookEvent], notify: Bool = false) -> String {
+    AgentHookSettingsCommand.compositeCommand(
+      events: events, forwardStdinAsNotification: notify, agent: .copilot)
+  }
+
+  /// Branches on the payload (so it hand-composes the OSC pieces rather than using
+  /// `compositeCommand`): permission / elicitation prompts flip to awaitingInput +
+  /// alert; other notification types no-op since `agentStop` owns the done-alert.
+  private static var notificationCommand: String {
+    let surfaceGuard = #"[ -n "${\#(AgentPresenceOSC.surfaceEnvVar):-}" ]"#
+    let needsYou =
+      #"\#(AgentPresenceOSC.ttyResolveSnippet); "#
+      + AgentPresenceOSC.emitShell(event: .awaitingInput, agent: .copilot) + "; "
+      + AgentPresenceOSC.emitNotifyShell(agent: .copilot, readsStdin: false)
+    let steps =
+      #"__in=$(cat); case "$__in" in *permission_prompt*|*elicitation_dialog*) \#(needsYou) ;; esac"#
+    return #"\#(surfaceGuard) && { \#(steps); } >/dev/null 2>&1 || true \#(ownershipMarker)"#
+  }
+
+  private struct Payload: Encodable {
+    let version = 1
+    let hooks: [String: [Hook]] = [
+      "sessionStart": [Hook(bash: CopilotHookSettings.command(for: [.sessionStart]), timeoutSec: 5)],
+      "userPromptSubmitted": [Hook(bash: CopilotHookSettings.command(for: [.busy]), timeoutSec: 10)],
+      "preToolUse": [Hook(bash: CopilotHookSettings.command(for: [.busy]), timeoutSec: 5)],
+      "postToolUse": [Hook(bash: CopilotHookSettings.command(for: [.busy]), timeoutSec: 5)],
+      "agentStop": [Hook(bash: CopilotHookSettings.command(for: [.idle], notify: true), timeoutSec: 10)],
+      "sessionEnd": [Hook(bash: CopilotHookSettings.command(for: [.sessionEnd]), timeoutSec: 5)],
+      "notification": [Hook(bash: CopilotHookSettings.notificationCommand, timeoutSec: 10)],
+    ]
+  }
+
+  private struct Hook: Encodable {
+    let type = "command"
+    let bash: String
+    let timeoutSec: Int
+  }
+}
diff --git a/SupacodeSettingsShared/BusinessLogic/CopilotHooksInstaller.swift b/SupacodeSettingsShared/BusinessLogic/CopilotHooksInstaller.swift
new file mode 100644
index 000000000..c06ab6c84
--- /dev/null
+++ b/SupacodeSettingsShared/BusinessLogic/CopilotHooksInstaller.swift
@@ -0,0 +1,81 @@
+import Foundation
+
+private nonisolated let copilotInstallerLogger = SupaLogger("Settings")
+
+/// Writes / removes Supacode's own `~/.copilot/hooks/supacode.json`. The hooks
+/// dir is shared with the user's files, so only `supacode.json` is ever touched.
+nonisolated struct CopilotHooksInstaller {
+  let homeDirectoryURL: URL
+  let fileManager: FileManager
+
+  init(
+    homeDirectoryURL: URL = FileManager.default.homeDirectoryForCurrentUser,
+    fileManager: FileManager = .default
+  ) {
+    self.homeDirectoryURL = homeDirectoryURL
+    self.fileManager = fileManager
+  }
+
+  /// Marker present but content differs → `.outdated`; no marker → `.notInstalled`
+  /// (so auto-update never overwrites a user file that shares the name).
+  func installState() -> ComponentInstallState {
+    guard let contents = try? String(contentsOf: hookFileURL, encoding: .utf8) else {
+      return .notInstalled
+    }
+    if let source = try? CopilotHookSettings.source(), contents == source { return .installed }
+    return contents.contains(CopilotHookSettings.ownershipMarker) ? .outdated : .notInstalled
+  }
+
+  func install() throws {
+    let path = hookFileURL.path(percentEncoded: false)
+    if fileManager.fileExists(atPath: path) {
+      let contents = try String(contentsOf: hookFileURL, encoding: .utf8)
+      guard contents.contains(CopilotHookSettings.ownershipMarker) else {
+        throw CopilotHooksInstallerError.fileNotManaged
+      }
+    }
+    try fileManager.createDirectory(at: hooksDirectoryURL, withIntermediateDirectories: true)
+    try CopilotHookSettings.source().write(to: hookFileURL, atomically: true, encoding: .utf8)
+    copilotInstallerLogger.info("Installed Copilot hooks at \(path)")
+  }
+
+  func uninstall() throws {
+    let path = hookFileURL.path(percentEncoded: false)
+    guard fileManager.fileExists(atPath: path) else { return }
+    // Never remove a user file that merely shares the name.
+    let contents = try String(contentsOf: hookFileURL, encoding: .utf8)
+    guard contents.contains(CopilotHookSettings.ownershipMarker) else {
+      throw CopilotHooksInstallerError.fileNotManaged
+    }
+    try fileManager.removeItem(at: hookFileURL)
+    copilotInstallerLogger.info("Uninstalled Copilot hooks from \(path)")
+  }
+
+  var hookFileURL: URL {
+    hooksDirectoryURL.appending(path: CopilotHookSettings.fileName, directoryHint: .notDirectory)
+  }
+
+  private var hooksDirectoryURL: URL {
+    Self.hooksDirectoryURL(homeDirectoryURL: homeDirectoryURL)
+  }
+
+  static func hooksDirectoryURL(homeDirectoryURL: URL) -> URL {
+    homeDirectoryURL
+      .appending(path: ".copilot", directoryHint: .isDirectory)
+      .appending(path: "hooks", directoryHint: .isDirectory)
+  }
+}
+
+nonisolated enum CopilotHooksInstallerError: Error, Equatable, LocalizedError {
+  case fileNotManaged
+  case encodingFailed
+
+  var errorDescription: String? {
+    switch self {
+    case .fileNotManaged:
+      "The Copilot hook file at ~/.copilot/hooks/supacode.json is not managed by Supacode."
+    case .encodingFailed:
+      "Failed to encode the Copilot hook payload."
+    }
+  }
+}
diff --git a/SupacodeSettingsShared/BusinessLogic/KiroSettingsInstaller.swift b/SupacodeSettingsShared/BusinessLogic/KiroSettingsInstaller.swift
index de5ff8d17..7b97456b0 100644
--- a/SupacodeSettingsShared/BusinessLogic/KiroSettingsInstaller.swift
+++ b/SupacodeSettingsShared/BusinessLogic/KiroSettingsInstaller.swift
@@ -14,9 +14,9 @@ nonisolated struct KiroSettingsInstaller {
   /// defaults in `ensureDefaultAgentConfig` may no longer match upstream and would
   /// silently override a legitimately different config — gate on this prefix to
   /// fail loudly instead.
-  static let supportedVersionPrefix = "1."
+  static let supportedVersionPrefix = "2."
 
-  /// Maximum time to wait on `kiro --version`. A misconfigured login shell (e.g.
+  /// Maximum time to wait on `kiro-cli --version`. A misconfigured login shell (e.g.
   /// an rc file blocking on stdin) can hang the child indefinitely; when that
   /// happens we terminate the process so `waitUntilExit` cannot pin the
   /// cooperative pool thread.
@@ -28,19 +28,19 @@ nonisolated struct KiroSettingsInstaller {
 
   init(
     homeDirectoryURL: URL = FileManager.default.homeDirectoryForCurrentUser,
-    fileManager: FileManager = .default
+    fileManager: FileManager = .default,
   ) {
     self.init(
       homeDirectoryURL: homeDirectoryURL,
       fileManager: fileManager,
-      runKiroVersionCommand: Self.runKiroVersionCommand
+      runKiroVersionCommand: Self.runKiroVersionCommand,
     )
   }
 
   init(
     homeDirectoryURL: URL = FileManager.default.homeDirectoryForCurrentUser,
     fileManager: FileManager = .default,
-    runKiroVersionCommand: @escaping @Sendable () async throws -> CommandResult
+    runKiroVersionCommand: @escaping @Sendable () async throws -> CommandResult,
   ) {
     self.homeDirectoryURL = homeDirectoryURL
     self.fileManager = fileManager
@@ -68,14 +68,14 @@ nonisolated struct KiroSettingsInstaller {
     try await ensureDefaultAgentConfig()
     try fileInstaller.install(
       settingsURL: settingsURL,
-      hookEntriesByEvent: try KiroHookSettings.hooksByEvent()
+      hookEntriesByEvent: try KiroHookSettings.hooksByEvent(),
     )
   }
 
   func uninstallAllHooks() throws {
     try fileInstaller.uninstall(
       settingsURL: settingsURL,
-      hookEntriesByEvent: try KiroHookSettings.hooksByEvent()
+      hookEntriesByEvent: try KiroHookSettings.hooksByEvent(),
     )
   }
 
@@ -90,7 +90,7 @@ nonisolated struct KiroSettingsInstaller {
     try await validateSupportedKiroVersion()
     try fileManager.createDirectory(
       at: settingsURL.deletingLastPathComponent(),
-      withIntermediateDirectories: true
+      withIntermediateDirectories: true,
     )
     let defaultConfig: [String: JSONValue] = [
       "name": .string("kiro_default"),
@@ -186,7 +186,7 @@ nonisolated struct KiroSettingsInstaller {
   static func runKiroVersionCommand() async throws -> CommandResult {
     let process = Process()
     process.executableURL = CodexSettingsInstaller.loginShellURL()
-    process.arguments = ["-l", "-c", "kiro --version"]
+    process.arguments = ["-l", "-c", "kiro-cli --version"]
     let outputPipe = Pipe()
     let errorPipe = Pipe()
     process.standardOutput = outputPipe
@@ -197,7 +197,7 @@ nonisolated struct KiroSettingsInstaller {
       try? await Task.sleep(nanoseconds: versionCommandTimeoutSeconds * 1_000_000_000)
       if process.isRunning {
         kiroVersionLogger.warning(
-          "kiro --version exceeded \(versionCommandTimeoutSeconds)s; terminating.")
+          "kiro-cli --version exceeded \(versionCommandTimeoutSeconds)s; terminating.")
         process.terminate()
       }
     }
@@ -217,7 +217,7 @@ nonisolated struct KiroSettingsInstaller {
     return .init(
       status: process.terminationStatus,
       standardOutput: standardOutput,
-      standardError: standardError.trimmingCharacters(in: .whitespacesAndNewlines)
+      standardError: standardError.trimmingCharacters(in: .whitespacesAndNewlines),
     )
   }
 
@@ -257,8 +257,8 @@ nonisolated struct KiroSettingsInstaller {
         invalidEventHooks: { KiroSettingsInstallerError.invalidEventHooks($0) },
         invalidHooksObject: { KiroSettingsInstallerError.invalidHooksObject },
         invalidJSON: { KiroSettingsInstallerError.invalidJSON($0) },
-        invalidRootObject: { KiroSettingsInstallerError.invalidRootObject }
-      )
+        invalidRootObject: { KiroSettingsInstallerError.invalidRootObject },
+      ),
     )
   }
 }
diff --git a/SupacodeSettingsShared/BusinessLogic/OpenCodePluginContent.swift b/SupacodeSettingsShared/BusinessLogic/OpenCodePluginContent.swift
new file mode 100644
index 000000000..66e78cf66
--- /dev/null
+++ b/SupacodeSettingsShared/BusinessLogic/OpenCodePluginContent.swift
@@ -0,0 +1,90 @@
+import Foundation
+
+/// Source for the OpenCode plugin that bridges OpenCode's plugin events to
+/// Supacode's OSC 3008 agent-presence protocol.
+///
+/// OpenCode does NOT consume a Claude-style declarative `hooks` block in its
+/// config (`opencode.json`). Its extensibility surface is JS/TS plugins
+/// auto-loaded from `~/.config/opencode/plugins/`. So instead of writing a
+/// settings file, Supacode installs a small plugin that runs the exact same
+/// guarded shell command every other agent's hooks run — keeping the OSC
+/// template, surface guard, tty resolve, and pid-liveness suffix single-sourced
+/// in `AgentHookSettingsCommand`.
+nonisolated enum OpenCodePluginContent {
+  /// File name written under `~/.config/opencode/plugins/`.
+  static let pluginFileName = "supacode-presence.js"
+
+  /// Marker that identifies a Supacode-managed plugin file. The composite
+  /// command embeds `AgentHookSettingsCommand.ownershipMarker` verbatim, so the
+  /// generated source always contains it — uninstall keys off this so it never
+  /// deletes a user file that merely shares the name.
+  static let ownershipMarker = AgentHookSettingsCommand.ownershipMarker
+
+  /// Deterministic plugin source (no timestamps), so `installState` can detect
+  /// a byte-for-byte match vs. an older Supacode version's plugin (`.outdated`).
+  static func source() -> String {
+    """
+    // \(ownershipMarker)
+    //
+    // Generated by Supacode — do not edit. Bridges OpenCode plugin events to
+    // Supacode's OSC 3008 agent-presence protocol by running the same guarded
+    // shell command Supacode installs for every other agent. The command checks
+    // SUPACODE_SURFACE_ID first, so it is inert outside a Supacode surface and
+    // safe to keep installed anywhere.
+    //
+    // Presence only: OpenCode's session.idle event carries no assistant text
+    // (unlike Claude Code's Stop hook stdin), so the system-notification leg is
+    // intentionally omitted rather than fed a fabricated body.
+    export const SupacodePresence = async ({ $ }) => {
+      const emit = (command) => $`sh -c ${command}`.quiet().nothrow()
+
+      // Agent is now present in this surface.
+      await emit(\(jsString(command(for: [.sessionStart]))))
+
+      return {
+        // Agent (and its surface presence) is going away.
+        dispose: async () => {
+          await emit(\(jsString(command(for: [.sessionEnd, .idle]))))
+        },
+        // Tool-level activity shimmer: a tool started / finished.
+        "tool.execute.before": async () => {
+          await emit(\(jsString(command(for: [.busy]))))
+        },
+        "tool.execute.after": async () => {
+          await emit(\(jsString(command(for: [.idle]))))
+        },
+        // A permission prompt is the "needs you" state.
+        "permission.ask": async () => {
+          await emit(\(jsString(command(for: [.awaitingInput]))))
+        },
+        event: async ({ event }) => {
+          if (event.type === "session.idle") {
+            await emit(\(jsString(command(for: [.idle]))))
+          } else if (event.type === "permission.replied") {
+            await emit(\(jsString(command(for: [.busy]))))
+          }
+        },
+      }
+    }
+    """
+  }
+
+  private static func command(for events: [HookEvent]) -> String {
+    AgentHookSettingsCommand.compositeCommand(
+      events: events, forwardStdinAsNotification: false, agent: .opencode)
+  }
+
+  /// JSON-encoding a `String` yields a valid double-quoted JavaScript string
+  /// literal: it escapes `"`, `\`, and control characters, and the composite
+  /// command contains no newlines. `$` and backticks are literal inside a
+  /// double-quoted JS string, so no extra escaping is needed.
+  private static func jsString(_ value: String) -> String {
+    guard
+      let data = try? JSONEncoder().encode(value),
+      let literal = String(data: data, encoding: .utf8)
+    else {
+      return "\"\""
+    }
+    return literal
+  }
+}
diff --git a/SupacodeSettingsShared/BusinessLogic/OpenCodePluginInstaller.swift b/SupacodeSettingsShared/BusinessLogic/OpenCodePluginInstaller.swift
new file mode 100644
index 000000000..a02cdeb75
--- /dev/null
+++ b/SupacodeSettingsShared/BusinessLogic/OpenCodePluginInstaller.swift
@@ -0,0 +1,65 @@
+import Foundation
+
+/// Installs (and removes) the Supacode presence plugin for OpenCode.
+///
+/// Unlike the Claude/Kiro JSON-merge installers, OpenCode loads plugins as
+/// files from `~/.config/opencode/plugins/`, so this mirrors `CLISkillInstaller`
+/// (write / remove a single owned file) rather than `ClaudeSettingsInstaller`
+/// (prune-append into a shared JSON object). There is no foreign config to
+/// preserve and no schema to satisfy.
+nonisolated struct OpenCodePluginInstaller {
+  let homeDirectoryURL: URL
+  let fileManager: FileManager
+
+  init(
+    homeDirectoryURL: URL = FileManager.default.homeDirectoryForCurrentUser,
+    fileManager: FileManager = .default
+  ) {
+    self.homeDirectoryURL = homeDirectoryURL
+    self.fileManager = fileManager
+  }
+
+  /// `.installed` only on a byte-for-byte match, so an older Supacode version's
+  /// plugin reports `.outdated` and the next install upgrades it in place. A
+  /// file Supacode does NOT own (no ownership marker) reports `.notInstalled`,
+  /// not `.outdated`, so auto-update never silently overwrites a user plugin
+  /// that happens to share the name — symmetric with `uninstall`.
+  func installState() -> ComponentInstallState {
+    guard let contents = try? String(contentsOf: pluginFileURL, encoding: .utf8) else {
+      return .notInstalled
+    }
+    if contents == OpenCodePluginContent.source() { return .installed }
+    return contents.contains(OpenCodePluginContent.ownershipMarker) ? .outdated : .notInstalled
+  }
+
+  func install() throws {
+    try fileManager.createDirectory(at: pluginDirectoryURL, withIntermediateDirectories: true)
+    try OpenCodePluginContent.source().write(to: pluginFileURL, atomically: true, encoding: .utf8)
+  }
+
+  func uninstall() throws {
+    // Only remove a file Supacode owns — never clobber a user plugin that
+    // happens to share the name.
+    guard let contents = try? String(contentsOf: pluginFileURL, encoding: .utf8),
+      contents.contains(OpenCodePluginContent.ownershipMarker)
+    else {
+      return
+    }
+    try fileManager.removeItem(at: pluginFileURL)
+  }
+
+  var pluginFileURL: URL {
+    pluginDirectoryURL.appendingPathComponent(OpenCodePluginContent.pluginFileName, isDirectory: false)
+  }
+
+  private var pluginDirectoryURL: URL {
+    Self.pluginDirectoryURL(homeDirectoryURL: homeDirectoryURL)
+  }
+
+  static func pluginDirectoryURL(homeDirectoryURL: URL) -> URL {
+    homeDirectoryURL
+      .appendingPathComponent(".config", isDirectory: true)
+      .appendingPathComponent("opencode", isDirectory: true)
+      .appendingPathComponent("plugins", isDirectory: true)
+  }
+}
diff --git a/SupacodeSettingsShared/BusinessLogic/PiExtensionContent.swift b/SupacodeSettingsShared/BusinessLogic/PiExtensionContent.swift
index 690e3c1ae..b68ddf578 100644
--- a/SupacodeSettingsShared/BusinessLogic/PiExtensionContent.swift
+++ b/SupacodeSettingsShared/BusinessLogic/PiExtensionContent.swift
@@ -11,111 +11,123 @@ nonisolated enum PiExtensionContent {
   static let indexTs = """
     \(ownershipMarker)
     /**
-     * Supacode ↔ Pi integration extension.
+     * Supacode + Pi integration extension.
      *
-     * Reports agent lifecycle hooks back to Supacode via the Unix domain socket
-     * it injects into every managed terminal session, matching the semantics of
-     * the existing Claude and Codex hook integrations.
+     * Reports agent lifecycle and notifications to Supacode by emitting OSC 3008
+     * escape sequences to the controlling terminal. The sequences are inert in any
+     * terminal that does not handle OSC 3008, and reach Supacode over SSH too (no
+     * local socket needed), matching the Claude / Codex / Kiro hook integrations.
      *
-     * Required env vars (injected automatically by Supacode):
-     *   SUPACODE_SOCKET_PATH  — path to the Unix domain socket
-     *   SUPACODE_WORKTREE_ID  — worktree identifier
-     *   SUPACODE_TAB_ID       — tab UUID
-     *   SUPACODE_SURFACE_ID   — terminal surface UUID
+     * Required env var (injected automatically by Supacode on every surface):
+     *   SUPACODE_SURFACE_ID  present only on a Supacode surface; absence is the
+     *                        no-op gate. Signals are unauthenticated.
+     * Optional:
+     *   SUPACODE_SOCKET_PATH  present only on the local host; gates the local pid
+     *                         so the app's liveness sweep can reap a crashed agent.
      *
      * Hook event mapping:
-     *   extension load      → session_start  (agent presence badge)
-     *   Pi agent_start      → busy           (UserPromptSubmit equivalent)
-     *   Pi agent_end        → idle           (Stop equivalent — resets activity)
-     *                       → notification with last_assistant_message
-     *   Pi session_shutdown → session_end    (SessionEnd equivalent)
-     *                       → idle           (defensive activity reset)
+     *   extension load      -> session_start  (agent presence badge)
+     *   Pi agent_start      -> busy
+     *   Pi agent_end        -> idle + notification with last_assistant_message
+     *   Pi session_shutdown -> session_end + idle (defensive activity reset)
      */
 
     import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-    import { createConnection } from "node:net";
+    import { openSync, writeSync, closeSync } from "node:fs";
 
-    interface SupacodeEnv {
-      socketPath: string;
-      worktreeId: string;
-      tabId: string;
-      surfaceId: string;
-    }
-
-    interface HookPayload {
-      hook_event_name: string;
+    interface NotifyContent {
       title?: string;
-      message?: string;
-      last_assistant_message?: string;
+      body?: string;
     }
 
-    function readSupacodeEnv(): SupacodeEnv | null {
-      const socketPath = process.env["SUPACODE_SOCKET_PATH"];
-      const worktreeId = process.env["SUPACODE_WORKTREE_ID"];
-      const tabId = process.env["SUPACODE_TAB_ID"];
-      const surfaceId = process.env["SUPACODE_SURFACE_ID"];
+    const AGENT = "pi";
 
-      if (!socketPath || !worktreeId || !tabId || !surfaceId) return null;
-      return { socketPath, worktreeId, tabId, surfaceId };
+    let lastWarnedAt = 0;
+    const WARN_INTERVAL_MS = 60_000;
+
+    function isSupacodeSurface(): boolean {
+      const id = process.env["SUPACODE_SURFACE_ID"];
+      return !!id && id.length > 0;
+    }
+
+    /**
+     * The agent's local process id as an OSC pid suffix, but only on the local
+     * host (SUPACODE_SOCKET_PATH is set). A remote pid over SSH would be
+     * meaningless to the app's liveness sweep, so it is omitted there.
+     */
+    function localPidSuffix(): string {
+      return process.env["SUPACODE_SOCKET_PATH"] ? `;pid=${process.pid}` : "";
     }
 
     /**
-     * Sends raw bytes to a Unix domain socket and closes the connection.
-     * Times out after 1 s (Pi serializes hook callbacks, so a stalled
-     * delivery would stall the agent) and swallows all errors —
-     * hook delivery is best-effort.
+     * Writes an OSC sequence to the controlling terminal. The extension runs
+     * inside the Pi TUI process, which owns the terminal, so /dev/tty resolves.
+     * Best-effort, but a systematically-failing tty is logged at most once per
+     * `WARN_INTERVAL_MS` to stderr so a broken write path is distinguishable
+     * from "not a Supacode surface" without spamming the log on every emit.
      */
-    function sendToSocket(socketPath: string, data: Buffer): Promise<void> {
-      return new Promise<void>((resolve) => {
-        let settled = false;
-        const done = () => {
-          if (!settled) {
-            settled = true;
-            resolve();
+    function writeToTerminal(sequence: string): void {
+      try {
+        const fd = openSync("/dev/tty", "w");
+        try {
+          // Loop until the full byte length lands: a short write would leave a
+          // half OSC 3008 with no ST (ESC\\) and corrupt the terminal parser.
+          const bytes = Buffer.from(sequence, "utf8");
+          let offset = 0;
+          while (offset < bytes.length) {
+            try {
+              const written = writeSync(fd, bytes, offset, bytes.length - offset);
+              if (written <= 0) {
+                throw new Error(`short write (${offset}/${bytes.length} bytes)`);
+              }
+              offset += written;
+            } catch (writeErr) {
+              // Retry interrupted / non-blocking transient errors; abort on anything else.
+              const code = (writeErr as NodeJS.ErrnoException).code;
+              if (code === "EINTR" || code === "EAGAIN") continue;
+              throw writeErr;
+            }
           }
-        };
-
-        const client = createConnection({ path: socketPath });
-        const timer = setTimeout(() => {
-          client.destroy();
-          done();
-        }, 1000);
-
-        client.on("connect", () => {
-          client.write(data, () => {
-            client.end();
-            clearTimeout(timer);
-            done();
-          });
-        });
-
-        client.on("error", () => {
-          clearTimeout(timer);
-          done();
-        });
-      });
+        } finally {
+          closeSync(fd);
+        }
+      } catch (err) {
+        const now = Date.now();
+        if (now - lastWarnedAt > WARN_INTERVAL_MS) {
+          lastWarnedAt = now;
+          const e = err as NodeJS.ErrnoException;
+          const code = e.code ?? "";
+          const errno = e.errno ?? "";
+          const message = e.message ?? String(err);
+          process.stderr.write(
+            `supacode: OSC emit failed: code=${code} errno=${errno} message=${message}\\n`,
+          );
+        }
+      }
     }
 
-    function sendNotification(env: SupacodeEnv, payload: HookPayload): Promise<void> {
-      const header = `${env.worktreeId} ${env.tabId} ${env.surfaceId} pi\\n`;
-      const body = JSON.stringify(payload) + "\\n";
-      return sendToSocket(env.socketPath, Buffer.from(header + body, "utf8"));
+    function emitPresence(event: string): void {
+      const action = event === "session_end" ? "end" : "start";
+      const meta = `event=${event}${localPidSuffix()}`;
+      writeToTerminal(`\\x1b]3008;${action}=${AGENT};${meta}\\x1b\\\\`);
     }
 
-    /**
-     * Sends a hook event (session lifecycle or per-turn activity) using
-     * the same JSON envelope every other agent emits.
-     */
-    function sendEvent(env: SupacodeEnv, eventName: string): Promise<void> {
-      const envelope = {
-        event: eventName,
-        v: 1,
-        agent: "pi",
-        surface_id: env.surfaceId,
-        pid: process.pid,
-      };
-      const body = JSON.stringify(envelope) + "\\n";
-      return sendToSocket(env.socketPath, Buffer.from(body, "utf8"));
+    // JSON-escape (minus the surrounding quotes) so the wire matches the shell
+    // awk path, byte-cap to the same budget, then base64. App-side
+    // decodeNotifyValue reverses both and tolerates a mid-escape cut.
+    function notifyField(value: string, budget: number): string {
+      const escaped = JSON.stringify(value).slice(1, -1);
+      const buf = Buffer.from(escaped, "utf8");
+      const capped = buf.length > budget ? buf.subarray(0, budget) : buf;
+      return capped.toString("base64");
+    }
+
+    function emitNotification(content: NotifyContent): void {
+      const meta =
+        `kind=notify` +
+        `;title=${notifyField(content.title ?? "", \(AgentPresenceOSC.notifyTitleByteBudget))}` +
+        `;body=${notifyField(content.body ?? "", \(AgentPresenceOSC.notifyBodyByteBudget))}`;
+      writeToTerminal(`\\x1b]3008;start=${AGENT};${meta}\\x1b\\\\`);
     }
 
     function lastAssistantText(ctx: { sessionManager: { getEntries(): any[] } }): string | undefined {
@@ -140,34 +152,27 @@ nonisolated enum PiExtensionContent {
     }
 
     export default function (pi: ExtensionAPI) {
-      const env = readSupacodeEnv();
-
-      // Not running under Supacode — skip lifecycle hooks.
-      if (!env) return;
+      // Not running under Supacode, or not a Supacode surface: stay inert.
+      if (!isSupacodeSurface()) return;
 
       // Extension load = agent process running. Pi has no equivalent of
       // Claude's SessionStart hook, so we fire it ourselves.
-      void sendEvent(env, "session_start");
+      emitPresence("session_start");
 
-      pi.on("agent_start", async (_event, _ctx) => {
-        await sendEvent(env, "busy");
+      pi.on("agent_start", (_event, _ctx) => {
+        emitPresence("busy");
       });
 
-      pi.on("agent_end", async (_event, ctx) => {
+      pi.on("agent_end", (_event, ctx) => {
         // Atomic state-set: `idle` overwrites whatever was running on the
-        // Supacode side — turn-level Stop equivalent.
-        await sendEvent(env, "idle");
-
-        const lastMessage = lastAssistantText(ctx);
-        await sendNotification(env, {
-          hook_event_name: "Stop",
-          last_assistant_message: lastMessage,
-        });
+        // Supacode side (turn-level Stop equivalent).
+        emitPresence("idle");
+        emitNotification({ body: lastAssistantText(ctx) });
       });
 
-      pi.on("session_shutdown", async (_event, _ctx) => {
-        await sendEvent(env, "session_end");
-        await sendEvent(env, "idle");
+      pi.on("session_shutdown", (_event, _ctx) => {
+        emitPresence("session_end");
+        emitPresence("idle");
       });
     }
     """
diff --git a/SupacodeSettingsShared/BusinessLogic/RepositoryLocalSettingsPersistence.swift b/SupacodeSettingsShared/BusinessLogic/RepositoryLocalSettingsPersistence.swift
index 9d0796450..17e113fc9 100644
--- a/SupacodeSettingsShared/BusinessLogic/RepositoryLocalSettingsPersistence.swift
+++ b/SupacodeSettingsShared/BusinessLogic/RepositoryLocalSettingsPersistence.swift
@@ -18,6 +18,10 @@ nonisolated enum RepositoryLocalSettingsStorageKey: DependencyKey {
   static var liveValue: RepositoryLocalSettingsStorage {
     RepositoryLocalSettingsStorage(
       load: { try Data(contentsOf: $0) },
+      // Do not follow symlinks here: this writes `<repoRoot>/supacode.json`, whose
+      // contents come from a possibly-untrusted cloned repository. A symlink there
+      // could point at any user-writable file, so the atomic write must replace the
+      // link in the repo rather than write through it (an arbitrary-overwrite path).
       save: { data, url in
         let directory = url.deletingLastPathComponent()
         try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
diff --git a/SupacodeSettingsShared/BusinessLogic/RepositoryPersistenceKeys.swift b/SupacodeSettingsShared/BusinessLogic/RepositoryPersistenceKeys.swift
index 97d0a31fe..c8c90ce94 100644
--- a/SupacodeSettingsShared/BusinessLogic/RepositoryPersistenceKeys.swift
+++ b/SupacodeSettingsShared/BusinessLogic/RepositoryPersistenceKeys.swift
@@ -48,6 +48,69 @@ public nonisolated struct RepositoryRootsKey: SharedKey {
   }
 }
 
+public nonisolated struct RemoteRepositoryRootsKeyID: Hashable, Sendable {
+  public init() {}
+}
+
+/// Persists the self-descriptive remote repository ids. Kept apart from the
+/// local-path `RepositoryPathNormalizer` (which would mangle a `user@host/path`
+/// authority through `URL(fileURLWithPath:)`); remote ids only need a trim +
+/// order-preserving dedupe.
+public nonisolated struct RemoteRepositoryRootsKey: SharedKey {
+  public init() {}
+
+  public var id: RemoteRepositoryRootsKeyID {
+    RemoteRepositoryRootsKeyID()
+  }
+
+  static func normalize(_ ids: [String]) -> [String] {
+    var seen = Set<String>()
+    var normalized: [String] = []
+    normalized.reserveCapacity(ids.count)
+    for id in ids {
+      let trimmed = id.trimmingCharacters(in: .whitespacesAndNewlines)
+      guard !trimmed.isEmpty, seen.insert(trimmed).inserted else { continue }
+      normalized.append(trimmed)
+    }
+    return normalized
+  }
+
+  public func load(
+    context _: LoadContext<[String]>,
+    continuation: LoadContinuation<[String]>
+  ) {
+    @Shared(.settingsFile) var settingsFile: SettingsFile
+    let roots = $settingsFile.withLock { settings in
+      let normalized = Self.normalize(settings.remoteRepositoryRoots)
+      if normalized != settings.remoteRepositoryRoots {
+        settings.remoteRepositoryRoots = normalized
+      }
+      return normalized
+    }
+    continuation.resume(returning: roots)
+  }
+
+  public func subscribe(
+    context _: LoadContext<[String]>,
+    subscriber _: SharedSubscriber<[String]>
+  ) -> SharedSubscription {
+    SharedSubscription {}
+  }
+
+  public func save(
+    _ value: [String],
+    context _: SaveContext,
+    continuation: SaveContinuation
+  ) {
+    @Shared(.settingsFile) var settingsFile: SettingsFile
+    let normalized = Self.normalize(value)
+    $settingsFile.withLock {
+      $0.remoteRepositoryRoots = normalized
+    }
+    continuation.resume()
+  }
+}
+
 public nonisolated struct PinnedWorktreeIDsKeyID: Hashable, Sendable {
   public init() {}
 }
@@ -100,6 +163,12 @@ nonisolated extension SharedReaderKey where Self == RepositoryRootsKey.Default {
   }
 }
 
+nonisolated extension SharedReaderKey where Self == RemoteRepositoryRootsKey.Default {
+  public static var remoteRepositoryRoots: Self {
+    Self[RemoteRepositoryRootsKey(), default: []]
+  }
+}
+
 nonisolated extension SharedReaderKey where Self == PinnedWorktreeIDsKey.Default {
   public static var pinnedWorktreeIDs: Self {
     Self[PinnedWorktreeIDsKey(), default: []]
@@ -116,6 +185,11 @@ public nonisolated enum RepositoryPathNormalizer {
   public static func normalize(_ path: String) -> String? {
     let trimmed = path.trimmingCharacters(in: .whitespacesAndNewlines)
     guard !trimmed.isEmpty else { return nil }
+    // A remote id (`[user@]host[:port]<path>`) is not a filesystem path; routing
+    // it through `URL(fileURLWithPath:)` would prepend the cwd and mangle it. A
+    // local id is always an absolute path, so the leading slash is the
+    // discriminator: only those get filesystem standardization.
+    guard trimmed.hasPrefix("/") else { return trimmed }
     return URL(fileURLWithPath: trimmed)
       .standardizedFileURL
       .path(percentEncoded: false)
@@ -140,11 +214,7 @@ public nonisolated enum RepositoryPathNormalizer {
     var normalized: [String: Date] = [:]
     normalized.reserveCapacity(dictionary.count)
     for (key, value) in dictionary {
-      let trimmed = key.trimmingCharacters(in: .whitespacesAndNewlines)
-      guard !trimmed.isEmpty else { continue }
-      let resolved = URL(fileURLWithPath: trimmed)
-        .standardizedFileURL
-        .path(percentEncoded: false)
+      guard let resolved = normalize(key) else { continue }
       // On collision, keep the more recent (greater) date.
       if let existing = normalized[resolved], existing > value {
         continue
diff --git a/SupacodeSettingsShared/BusinessLogic/RepositorySettingsKey.swift b/SupacodeSettingsShared/BusinessLogic/RepositorySettingsKey.swift
index 6fadb94e2..173cd92f0 100644
--- a/SupacodeSettingsShared/BusinessLogic/RepositorySettingsKey.swift
+++ b/SupacodeSettingsShared/BusinessLogic/RepositorySettingsKey.swift
@@ -13,10 +13,19 @@ public nonisolated struct RepositorySettingsKeyID: Hashable, Sendable {
 public nonisolated struct RepositorySettingsKey: SharedKey {
   public let repositoryID: String
   public let rootURL: URL
+  public let host: RemoteHost?
 
-  public init(rootURL: URL) {
+  public init(rootURL: URL, host: RemoteHost? = nil) {
     self.rootURL = rootURL.standardizedFileURL
-    repositoryID = self.rootURL.path(percentEncoded: false)
+    self.host = host
+    if let host {
+      // Brand remote keys with the host (matching `RepositoryLocation.id`) so
+      // two hosts at the same path can't share settings, and so a local repo
+      // at that path keeps its own bare-path key.
+      repositoryID = host.authority + self.rootURL.path(percentEncoded: false)
+    } else {
+      repositoryID = self.rootURL.path(percentEncoded: false)
+    }
   }
 
   public var id: RepositorySettingsKeyID {
@@ -27,18 +36,22 @@ public nonisolated struct RepositorySettingsKey: SharedKey {
     context: LoadContext<RepositorySettings>,
     continuation: LoadContinuation<RepositorySettings>
   ) {
-    @Dependency(\.repositoryLocalSettingsStorage) var repositoryLocalSettingsStorage
-    let repositorySettingsURL = SupacodePaths.repositorySettingsURL(for: rootURL)
-    if let localData = try? repositoryLocalSettingsStorage.load(repositorySettingsURL) {
-      let decoder = JSONDecoder()
-      if let settings = try? decoder.decode(RepositorySettings.self, from: localData) {
-        continuation.resume(returning: settings)
-        return
+    // Remote repos never own a local `supacode.json`; the synthetic `rootURL`
+    // points at the remote path, which must not be read off the local disk.
+    if host == nil {
+      @Dependency(\.repositoryLocalSettingsStorage) var repositoryLocalSettingsStorage
+      let repositorySettingsURL = SupacodePaths.repositorySettingsURL(for: rootURL)
+      if let localData = try? repositoryLocalSettingsStorage.load(repositorySettingsURL) {
+        let decoder = JSONDecoder()
+        if let settings = try? decoder.decode(RepositorySettings.self, from: localData) {
+          continuation.resume(returning: settings)
+          return
+        }
+        let path = repositorySettingsURL.path(percentEncoded: false)
+        SupaLogger("Settings").warning(
+          "Unable to decode repository settings at \(path); falling back to global settings."
+        )
       }
-      let path = repositorySettingsURL.path(percentEncoded: false)
-      SupaLogger("Settings").warning(
-        "Unable to decode repository settings at \(path); falling back to global settings."
-      )
     }
 
     @Shared(.settingsFile) var settingsFile: SettingsFile
@@ -65,19 +78,22 @@ public nonisolated struct RepositorySettingsKey: SharedKey {
     context _: SaveContext,
     continuation: SaveContinuation
   ) {
-    @Dependency(\.repositoryLocalSettingsStorage) var repositoryLocalSettingsStorage
-    let repositorySettingsURL = SupacodePaths.repositorySettingsURL(for: rootURL)
-    if (try? repositoryLocalSettingsStorage.load(repositorySettingsURL)) != nil {
-      do {
-        let encoder = JSONEncoder()
-        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
-        let data = try encoder.encode(value)
-        try repositoryLocalSettingsStorage.save(data, repositorySettingsURL)
-        continuation.resume()
-      } catch {
-        continuation.resume(throwing: error)
+    // Mirror `load`: only a local repo may persist to an on-disk `supacode.json`.
+    if host == nil {
+      @Dependency(\.repositoryLocalSettingsStorage) var repositoryLocalSettingsStorage
+      let repositorySettingsURL = SupacodePaths.repositorySettingsURL(for: rootURL)
+      if (try? repositoryLocalSettingsStorage.load(repositorySettingsURL)) != nil {
+        do {
+          let encoder = JSONEncoder()
+          encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+          let data = try encoder.encode(value)
+          try repositoryLocalSettingsStorage.save(data, repositorySettingsURL)
+          continuation.resume()
+        } catch {
+          continuation.resume(throwing: error)
+        }
+        return
       }
-      return
     }
 
     @Shared(.settingsFile) var settingsFile: SettingsFile
@@ -88,7 +104,7 @@ public nonisolated struct RepositorySettingsKey: SharedKey {
   }
 }
 nonisolated extension SharedReaderKey where Self == RepositorySettingsKey.Default {
-  public static func repositorySettings(_ rootURL: URL) -> Self {
-    Self[RepositorySettingsKey(rootURL: rootURL), default: .default]
+  public static func repositorySettings(_ rootURL: URL, host: RemoteHost? = nil) -> Self {
+    Self[RepositorySettingsKey(rootURL: rootURL, host: host), default: .default]
   }
 }
diff --git a/SupacodeSettingsShared/BusinessLogic/SettingsFilePersistence.swift b/SupacodeSettingsShared/BusinessLogic/SettingsFilePersistence.swift
index 81c111c7a..2787f4d46 100644
--- a/SupacodeSettingsShared/BusinessLogic/SettingsFilePersistence.swift
+++ b/SupacodeSettingsShared/BusinessLogic/SettingsFilePersistence.swift
@@ -19,11 +19,7 @@ public nonisolated enum SettingsFileStorageKey: DependencyKey {
   public static var liveValue: SettingsFileStorage {
     SettingsFileStorage(
       load: { try Data(contentsOf: $0) },
-      save: { data, url in
-        let directory = url.deletingLastPathComponent()
-        try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
-        try data.write(to: url, options: [.atomic])
-      }
+      save: { data, url in try SymlinkPreservingFileWriter.write(data, to: url) }
     )
   }
   public static var previewValue: SettingsFileStorage { .inMemory() }
@@ -58,10 +54,6 @@ extension SettingsFileStorage {
   }
 }
 
-nonisolated enum SettingsFileStorageError: Error {
-  case missing
-}
-
 nonisolated final class InMemorySettingsFileStorage: @unchecked Sendable {
   private let lock = NSLock()
   private var dataByURL: [URL: Data] = [:]
@@ -70,7 +62,9 @@ nonisolated final class InMemorySettingsFileStorage: @unchecked Sendable {
     lock.lock()
     defer { lock.unlock() }
     guard let data = dataByURL[url] else {
-      throw SettingsFileStorageError.missing
+      // Mirror real-disk semantics so callers that distinguish "file absent"
+      // (fresh start) from a read failure see the same `fileReadNoSuchFile`.
+      throw CocoaError(.fileReadNoSuchFile)
     }
     return data
   }
diff --git a/SupacodeSettingsShared/BusinessLogic/SymlinkPreservingFileWriter.swift b/SupacodeSettingsShared/BusinessLogic/SymlinkPreservingFileWriter.swift
new file mode 100644
index 000000000..1b3552494
--- /dev/null
+++ b/SupacodeSettingsShared/BusinessLogic/SymlinkPreservingFileWriter.swift
@@ -0,0 +1,85 @@
+import Foundation
+
+public nonisolated enum SymlinkPreservingFileWriterError: Error, Equatable {
+  /// The destination resolves through a symlink cycle, so there is no real file
+  /// to write without clobbering one of the links.
+  case symbolicLinkCycle(URL)
+  /// The chain exceeds the kernel's symlink-resolution limit, so the loader
+  /// could never follow it; refuse rather than write a file it can't read back.
+  case symbolicLinkChainTooDeep(URL)
+}
+
+/// Atomic file writes that survive a symlinked destination. When the target is a
+/// symlink (e.g. a `~/.supacode/settings.json` linked into a dotfiles repo), the
+/// write follows the link to its real file so the temp+rename replaces the
+/// target, leaving the link intact, instead of overwriting the link with a
+/// regular file.
+public nonisolated enum SymlinkPreservingFileWriter {
+  /// Atomically writes `data` to `url`, following a symlink at `url` so the link
+  /// is preserved. Creates the destination's own parent directory when missing,
+  /// but never a symlink target's parent (a link into a missing directory fails
+  /// the write rather than fabricating a phantom tree there).
+  public static func write(_ data: Data, to url: URL) throws {
+    let target = try resolvedTarget(for: url)
+    try FileManager.default.createDirectory(
+      at: url.deletingLastPathComponent(),
+      withIntermediateDirectories: true
+    )
+    // The atomic temp+rename happens in the target's directory, so a symlink at
+    // `url` is written through and preserved instead of replaced.
+    try data.write(to: target, options: [.atomic])
+  }
+
+  /// Moves the file at `url` aside to `destination`, preserving a symlink at
+  /// `url` by relocating the link's resolved target so the link survives (left
+  /// dangling for the next `write` to recreate). Falls back to moving the link
+  /// itself when it can't be resolved to a real target (a cycle or an over-deep
+  /// chain), where there is nothing else to relocate.
+  public static func moveAside(at url: URL, to destination: URL) throws {
+    let source: URL
+    do {
+      source = try resolvedTarget(for: url)
+    } catch is SymlinkPreservingFileWriterError {
+      source = url
+    }
+    try FileManager.default.moveItem(at: source, to: destination)
+  }
+
+  /// macOS resolves at most MAXSYMLINKS (32) links before ELOOP, so a deeper
+  /// chain is one the loader's `Data(contentsOf:)` could never read back.
+  private static let maxFollowedSymbolicLinks = 32
+
+  /// Follows a symlink chain at `url` to its final real file. Returns `url`
+  /// unchanged when it is not a symlink (including a not-yet-created file).
+  /// Relative link targets resolve against the link's real directory so a link
+  /// under a symlinked parent still lands on the file the kernel would. Throws
+  /// on a cycle or an over-deep chain rather than silently overwriting a link in
+  /// the loop, and surfaces a real read error rather than misreading an
+  /// unreadable link as a plain file (which would clobber it).
+  private static func resolvedTarget(for url: URL) throws -> URL {
+    let fileManager = FileManager.default
+    var current = url
+    var visited: Set<String> = []
+    while true {
+      let isSymbolicLink: Bool
+      do {
+        isSymbolicLink = try current.resourceValues(forKeys: [.isSymbolicLinkKey]).isSymbolicLink ?? false
+      } catch CocoaError.fileReadNoSuchFile {
+        return current
+      }
+      guard isSymbolicLink else { return current }
+      let linkPath = current.path(percentEncoded: false)
+      guard visited.insert(linkPath).inserted else {
+        throw SymlinkPreservingFileWriterError.symbolicLinkCycle(url)
+      }
+      guard visited.count <= Self.maxFollowedSymbolicLinks else {
+        throw SymlinkPreservingFileWriterError.symbolicLinkChainTooDeep(url)
+      }
+      let destination = try fileManager.destinationOfSymbolicLink(atPath: linkPath)
+      // A relative target resolves against the link's real directory; an absolute one ignores the base.
+      let base =
+        destination.hasPrefix("/") ? nil : current.deletingLastPathComponent().resolvingSymlinksInPath()
+      current = URL(filePath: destination, directoryHint: .notDirectory, relativeTo: base).standardizedFileURL
+    }
+  }
+}
diff --git a/SupacodeSettingsShared/Clients/Shell/ShellClient+SSH.swift b/SupacodeSettingsShared/Clients/Shell/ShellClient+SSH.swift
new file mode 100644
index 000000000..4ce31352e
--- /dev/null
+++ b/SupacodeSettingsShared/Clients/Shell/ShellClient+SSH.swift
@@ -0,0 +1,61 @@
+import Foundation
+
+extension ShellClient {
+  /// Host-aware transport: a `ShellClient` that runs every command on `host`
+  /// over SSH instead of locally, by rewriting each call into an `ssh <host>
+  /// <remoteCommand>` invocation (the working directory becomes a remote `cd`)
+  /// and delegating to `base` (defaults to `.live`; tests inject a recorder).
+  /// This is the single chokepoint that makes the rest of the stack remote. ssh
+  /// already runs the remote command through the user's login shell, so the
+  /// `runLogin*` entries must not re-wrap it and route to the plain `base.run*`.
+  /// `extraOptions` injects per-call `ssh -o` flags (e.g. the non-interactive
+  /// background-probe profile) on top of the shared multiplexing options.
+  public static func ssh(
+    host: RemoteHost,
+    base: ShellClient = .live,
+    extraOptions: [String] = []
+  ) -> ShellClient {
+    ShellClient(
+      run: { executableURL, arguments, currentDirectoryURL in
+        let invocation = SSHCommand.invocation(
+          host: host,
+          executable: executableURL.path(percentEncoded: false),
+          arguments: arguments,
+          workingDirectory: currentDirectoryURL,
+          extraOptions: extraOptions
+        )
+        return try await base.run(invocation.executableURL, invocation.arguments, nil)
+      },
+      runLoginImpl: { executableURL, arguments, currentDirectoryURL, _ in
+        let invocation = SSHCommand.invocation(
+          host: host,
+          executable: executableURL.path(percentEncoded: false),
+          arguments: arguments,
+          workingDirectory: currentDirectoryURL,
+          extraOptions: extraOptions
+        )
+        return try await base.run(invocation.executableURL, invocation.arguments, nil)
+      },
+      runStream: { executableURL, arguments, currentDirectoryURL in
+        let invocation = SSHCommand.invocation(
+          host: host,
+          executable: executableURL.path(percentEncoded: false),
+          arguments: arguments,
+          workingDirectory: currentDirectoryURL,
+          extraOptions: extraOptions
+        )
+        return base.runStream(invocation.executableURL, invocation.arguments, nil)
+      },
+      runLoginStreamImpl: { executableURL, arguments, currentDirectoryURL, _ in
+        let invocation = SSHCommand.invocation(
+          host: host,
+          executable: executableURL.path(percentEncoded: false),
+          arguments: arguments,
+          workingDirectory: currentDirectoryURL,
+          extraOptions: extraOptions
+        )
+        return base.runStream(invocation.executableURL, invocation.arguments, nil)
+      }
+    )
+  }
+}
diff --git a/SupacodeSettingsShared/Clients/Shell/ShellClient.swift b/SupacodeSettingsShared/Clients/Shell/ShellClient.swift
index 8a3cbcda6..0a7f1e898 100644
--- a/SupacodeSettingsShared/Clients/Shell/ShellClient.swift
+++ b/SupacodeSettingsShared/Clients/Shell/ShellClient.swift
@@ -78,8 +78,8 @@ extension ShellClient: DependencyKey {
       )
     },
     runLoginImpl: { executableURL, arguments, currentDirectoryURL, log in
-      let shellURL = URL(fileURLWithPath: defaultShellPath())
-      let execCommand = shellExecCommand(for: shellURL)
+      let (shellURL, execCommand) = ShellClient.loginShellInvocation(
+        userShell: URL(fileURLWithPath: defaultShellPath()))
       let shellArguments =
         ["-l", "-c", execCommand, "--", executableURL.path(percentEncoded: false)] + arguments
       if log {
@@ -102,8 +102,8 @@ extension ShellClient: DependencyKey {
       )
     },
     runLoginStreamImpl: { executableURL, arguments, currentDirectoryURL, log in
-      let shellURL = URL(fileURLWithPath: defaultShellPath())
-      let execCommand = shellExecCommand(for: shellURL)
+      let (shellURL, execCommand) = ShellClient.loginShellInvocation(
+        userShell: URL(fileURLWithPath: defaultShellPath()))
       let shellArguments =
         ["-l", "-c", execCommand, "--", executableURL.path(percentEncoded: false)] + arguments
       if log {
@@ -184,6 +184,21 @@ nonisolated private func runProcessStream(
       let command = ([executableURL.path(percentEncoded: false)] + arguments).joined(separator: " ")
       do {
         try process.run()
+        // Terminate the child only when the consuming task is cancelled (e.g. a
+        // remote load probe timing out); on normal completion the process already
+        // exited, so signalling its pid would risk a reused pid. Without this the
+        // `waitUntilExit()` below blocks its thread forever on a stalled ssh
+        // connection and no timeout can fire. SIGTERM first, then SIGKILL after a
+        // short grace so an ssh that ignores SIGTERM can't keep the task hung.
+        let pid = process.processIdentifier
+        continuation.onTermination = { @Sendable termination in
+          guard case .cancelled = termination, pid > 0 else { return }
+          kill(pid, SIGTERM)
+          Task.detached {
+            try? await Task.sleep(for: .seconds(2))
+            if kill(pid, 0) == 0 { kill(pid, SIGKILL) }
+          }
+        }
         let stdoutTask = Task.detached {
           for await line in lineStream(from: outputHandle) {
             await outputAccumulator.append(line, source: .stdout)
@@ -250,14 +265,41 @@ nonisolated private func collectOutput(
   return finalOutput
 }
 
-nonisolated private func shellExecCommand(for shellURL: URL) -> String {
-  switch shellURL.lastPathComponent {
-  case "fish":
-    return "test -f ~/.config/fish/config.fish; and source ~/.config/fish/config.fish >/dev/null 2>&1; exec $argv"
-  case "bash":
-    return "[ -f ~/.bashrc ] && . ~/.bashrc >/dev/null 2>&1; exec \"$@\""
-  default:
-    return "[ -f ~/.zshrc ] && . ~/.zshrc >/dev/null 2>&1; exec \"$@\""
+extension ShellClient {
+  /// Builds the `(shell, -c command)` pair for a one-shot login-shell command.
+  /// We only drive shells we have a correct rc snippet for — zsh, bash, fish.
+  /// Anything else (nushell, sh/dash/ksh, pwsh, …) falls back to /bin/zsh, which
+  /// can actually parse the snippet, so the command runs instead of failing
+  /// (issue #100). The interactive terminal still uses the user's real shell.
+  nonisolated static func loginShellInvocation(userShell: URL) -> (shell: URL, command: String) {
+    let drivable: Set<String> = ["zsh", "bash", "fish"]
+    let shell =
+      drivable.contains(userShell.lastPathComponent)
+      ? userShell : URL(fileURLWithPath: "/bin/zsh")
+    let command: String
+    switch shell.lastPathComponent {
+    case "fish":
+      command = "test -f ~/.config/fish/config.fish; and source ~/.config/fish/config.fish >/dev/null 2>&1; exec $argv"
+    case "bash":
+      command = posixLoginCommand(rcFile: "~/.bashrc")
+    default:
+      command = posixLoginCommand(rcFile: "~/.zshrc")
+    }
+    return (shell, command)
+  }
+
+  /// Builds the zsh/bash one-shot command: capture the positional parameters, clear them, then source
+  /// the rc file and exec from the saved array. Sourcing shares `$@` with the caller, so an rc that
+  /// resets the positionals (e.g. `set --`) would otherwise wipe the command before `exec` (#441).
+  /// Clearing `$@` with `set --` before sourcing also keeps the target command out of the rc's view:
+  /// a dual-mode script dispatching on `$1` (e.g. `fzf-git.sh`) would otherwise see the probe's
+  /// arguments, hit its own `exit`, and kill the probe shell before `exec` ran (#477). The exec reads
+  /// from the saved array, so clearing the live positionals is safe.
+  nonisolated private static func posixLoginCommand(rcFile: String) -> String {
+    let capture = "__supacode_login_argv=(\"$@\")"
+    let clear = "set --"
+    let source = "[ -f \(rcFile) ] && . \(rcFile) >/dev/null 2>&1"
+    return "\(capture); \(clear); \(source); exec \"${__supacode_login_argv[@]}\""
   }
 }
 
diff --git a/SupacodeSettingsShared/Domain/OpenWorktreeAction.swift b/SupacodeSettingsShared/Domain/OpenWorktreeAction.swift
index ee4956639..6253aef3f 100644
--- a/SupacodeSettingsShared/Domain/OpenWorktreeAction.swift
+++ b/SupacodeSettingsShared/Domain/OpenWorktreeAction.swift
@@ -1,5 +1,45 @@
 import AppKit
 
+public enum OpenTarget: Equatable, Sendable {
+  case workingDirectory
+  case url(URL)
+  case search(String, excludeDirectories: String? = nil, maxDepth: Int = 3)
+
+  public static let `default`: Self = .workingDirectory
+}
+
+public enum OpenBehavior: Equatable, Sendable {
+  public struct WorkspaceConfiguration: Equatable, Sendable {
+    public var createsNewApplicationInstance: Bool
+    public var arguments: [Argument]
+
+    public init(
+      createsNewApplicationInstance: Bool = false,
+      arguments: [Argument] = []
+    ) {
+      self.createsNewApplicationInstance = createsNewApplicationInstance
+      self.arguments = arguments
+    }
+  }
+
+  public enum ProcessExecutable: Equatable, Sendable {
+    case path(String)
+    case appRelativePath(String)
+  }
+
+  public enum Argument: Equatable, Sendable {
+    case literal(String)
+    case appPath
+    case targetPath
+    case targetURL
+  }
+
+  case workspace(configuration: WorkspaceConfiguration? = nil)
+  case process(ProcessExecutable, args: [Argument])
+
+  public static let `default`: Self = .workspace(configuration: nil)
+}
+
 public enum OpenWorktreeAction: CaseIterable, Identifiable {
   public enum MenuIcon {
     case app(NSImage)
@@ -17,8 +57,11 @@ public enum OpenWorktreeAction: CaseIterable, Identifiable {
   case gitkraken
   case gitup
   case ghostty
+  case goland
   case intellij
+  case intellijEAP
   case kitty
+  case nova
   case pycharm
   case rubymine
   case rustrover
@@ -35,6 +78,7 @@ public enum OpenWorktreeAction: CaseIterable, Identifiable {
   case windsurf
   case xcode
   case zed
+  case zedPreview
 
   public var id: String { title }
 
@@ -50,8 +94,11 @@ public enum OpenWorktreeAction: CaseIterable, Identifiable {
     case .gitkraken: "GitKraken"
     case .gitup: "GitUp"
     case .ghostty: "Ghostty"
+    case .goland: "GoLand"
     case .intellij: "IntelliJ IDEA"
+    case .intellijEAP: "IntelliJ IDEA EAP"
     case .kitty: "Kitty"
+    case .nova: "Nova"
     case .pycharm: "PyCharm"
     case .rubymine: "RubyMine"
     case .rustrover: "RustRover"
@@ -69,6 +116,7 @@ public enum OpenWorktreeAction: CaseIterable, Identifiable {
     case .xcode: "Xcode"
     case .fork: "Fork"
     case .zed: "Zed"
+    case .zedPreview: "Zed Preview"
     }
   }
 
@@ -77,9 +125,9 @@ public enum OpenWorktreeAction: CaseIterable, Identifiable {
     case .finder: "Finder"
     case .editor: "$EDITOR"
     case .alacritty, .androidStudio, .antigravity, .cursor, .fork, .githubDesktop, .gitkraken,
-      .gitup, .ghostty, .intellij, .kitty, .pycharm, .rubymine, .rustrover, .smartgit,
-      .sourcetree, .sublimeMerge, .terminal, .vscode, .vscodeInsiders, .vscodium, .warp,
-      .webstorm, .wezterm, .windsurf, .xcode, .zed:
+      .gitup, .ghostty, .goland, .intellij, .intellijEAP, .kitty, .nova, .pycharm, .rubymine,
+      .rustrover, .smartgit, .sourcetree, .sublimeMerge, .terminal, .vscode, .vscodeInsiders,
+      .vscodium, .warp, .webstorm, .wezterm, .windsurf, .xcode, .zed, .zedPreview:
       title
     }
   }
@@ -100,9 +148,9 @@ public enum OpenWorktreeAction: CaseIterable, Identifiable {
     case .finder, .editor:
       return true
     case .alacritty, .androidStudio, .antigravity, .cursor, .fork, .githubDesktop, .gitkraken,
-      .gitup, .ghostty, .intellij, .kitty, .pycharm, .rubymine, .rustrover, .smartgit,
-      .sourcetree, .sublimeMerge, .terminal, .vscode, .vscodeInsiders, .vscodium, .warp,
-      .webstorm, .wezterm, .windsurf, .xcode, .zed:
+      .gitup, .ghostty, .goland, .intellij, .intellijEAP, .kitty, .nova, .pycharm, .rubymine,
+      .rustrover, .smartgit, .sourcetree, .sublimeMerge, .terminal, .vscode, .vscodeInsiders,
+      .vscodium, .warp, .webstorm, .wezterm, .windsurf, .xcode, .zed, .zedPreview:
       return NSWorkspace.shared.urlForApplication(withBundleIdentifier: bundleIdentifier) != nil
     }
   }
@@ -120,8 +168,11 @@ public enum OpenWorktreeAction: CaseIterable, Identifiable {
     case .gitkraken: "gitkraken"
     case .gitup: "gitup"
     case .ghostty: "ghostty"
+    case .goland: "goland"
     case .intellij: "intellij"
+    case .intellijEAP: "intellijEAP"
     case .kitty: "kitty"
+    case .nova: "nova"
     case .pycharm: "pycharm"
     case .rubymine: "rubymine"
     case .rustrover: "rustrover"
@@ -138,6 +189,7 @@ public enum OpenWorktreeAction: CaseIterable, Identifiable {
     case .windsurf: "windsurf"
     case .xcode: "xcode"
     case .zed: "zed"
+    case .zedPreview: "zed-preview"
     }
   }
 
@@ -154,8 +206,11 @@ public enum OpenWorktreeAction: CaseIterable, Identifiable {
     case .gitkraken: "com.axosoft.gitkraken"
     case .gitup: "co.gitup.mac"
     case .ghostty: "com.mitchellh.ghostty"
+    case .goland: "com.jetbrains.goland"
     case .intellij: "com.jetbrains.intellij"
+    case .intellijEAP: "com.jetbrains.intellij-EAP"
     case .kitty: "net.kovidgoyal.kitty"
+    case .nova: "com.panic.Nova"
     case .pycharm: "com.jetbrains.pycharm"
     case .rubymine: "com.jetbrains.rubymine"
     case .rustrover: "com.jetbrains.rustrover"
@@ -172,6 +227,50 @@ public enum OpenWorktreeAction: CaseIterable, Identifiable {
     case .windsurf: "com.exafunction.windsurf"
     case .xcode: "com.apple.dt.Xcode"
     case .zed: "dev.zed.Zed"
+    case .zedPreview: "dev.zed.Zed-Preview"
+    }
+  }
+
+  public var openTargets: [OpenTarget] {
+    switch self {
+    case .xcode:
+      [
+        .search(#"\.xcworkspace$"#, excludeDirectories: Self.xcodeSearchExcludedDirectories),
+        .search(#"\.xcodeproj$"#, excludeDirectories: Self.xcodeSearchExcludedDirectories),
+        .default,
+      ]
+    case .alacritty, .androidStudio, .antigravity, .cursor, .editor, .finder, .fork, .githubDesktop,
+      .gitkraken, .gitup, .ghostty, .goland, .intellij, .intellijEAP, .kitty, .nova, .pycharm,
+      .rubymine, .rustrover, .smartgit, .sourcetree, .sublimeMerge, .terminal, .vscode,
+      .vscodeInsiders, .vscodium, .warp, .webstorm, .wezterm, .windsurf, .zed, .zedPreview:
+      [.default]
+    }
+  }
+
+  public var openBehaviors: [OpenBehavior] {
+    switch self {
+    case .androidStudio, .goland, .intellij, .intellijEAP, .webstorm, .pycharm, .rubymine, .rustrover:
+      [
+        .workspace(
+          configuration:
+            .init(
+              createsNewApplicationInstance: true,
+              arguments: [.targetPath]
+            )
+        )
+      ]
+    case .zed, .zedPreview:
+      [
+        .process(
+          .appRelativePath("Contents/MacOS/cli"),
+          args: [.targetPath]
+        ),
+        .default,
+      ]
+    case .alacritty, .antigravity, .cursor, .editor, .finder, .fork, .githubDesktop, .gitkraken, .gitup,
+      .ghostty, .kitty, .nova, .smartgit, .sourcetree, .sublimeMerge, .terminal, .vscode, .vscodeInsiders,
+      .vscodium, .warp, .wezterm, .windsurf, .xcode:
+      [.default]
     }
   }
 
@@ -180,16 +279,20 @@ public enum OpenWorktreeAction: CaseIterable, Identifiable {
   public static let editorPriority: [OpenWorktreeAction] = [
     .cursor,
     .zed,
+    .zedPreview,
     .vscode,
     .windsurf,
     .vscodeInsiders,
     .vscodium,
     .androidStudio,
+    .goland,
     .intellij,
+    .intellijEAP,
     .webstorm,
     .pycharm,
     .rubymine,
     .rustrover,
+    .nova,
     .antigravity,
   ]
   public static let terminalPriority: [OpenWorktreeAction] = [
@@ -255,4 +358,11 @@ public enum OpenWorktreeAction: CaseIterable, Identifiable {
   public static func preferredDefault() -> OpenWorktreeAction {
     defaultPriority.first(where: \.isInstalled) ?? .finder
   }
+
+  private static let xcodeSearchExcludedDirectories =
+    #"(^|/)("#
+    + #"\.build|\.dart_tool|\.expo|\.expo-shared|\.git|\.gradle|\.pnpm-store"#
+    + #"|\.swiftpm|\.symlinks|\.yarn|Carthage|DerivedData|Pods|build|node_modules"#
+    + #"|[^/]+\.xcodeproj|[^/]+\.xcworkspace"#
+    + #")(/|$)"#
 }
diff --git a/SupacodeSettingsShared/Models/RemoteHost.swift b/SupacodeSettingsShared/Models/RemoteHost.swift
new file mode 100644
index 000000000..70f48daa6
--- /dev/null
+++ b/SupacodeSettingsShared/Models/RemoteHost.swift
@@ -0,0 +1,103 @@
+import Foundation
+
+/// Describes an SSH destination a worktree can live on. A `nil` `RemoteHost`
+/// everywhere means "local": the unchanged Process-on-this-machine path.
+///
+/// `alias` is whatever `ssh` itself accepts as a host: a `~/.ssh/config` alias
+/// or a bare hostname. `username` / `port` are optional overrides for callers
+/// that don't want to encode them in ssh config.
+public nonisolated struct RemoteHost: Codable, Hashable, Sendable {
+  public var alias: String
+  public var username: String?
+  public var port: Int?
+
+  public init(
+    alias: String,
+    username: String? = nil,
+    port: Int? = nil
+  ) {
+    self.alias = alias
+    self.username = username
+    self.port = port
+  }
+
+  /// Inverse of `authority`: parse `[user@]host[:port]` back into a host. A
+  /// bracketed IPv6 host keeps its colons inside the brackets. `nil` if host empty.
+  public init?(authority: String) {
+    let trimmed = authority.trimmingCharacters(in: .whitespaces)
+    guard !trimmed.isEmpty else { return nil }
+    let user: String?
+    let hostPort: Substring
+    if let atIndex = trimmed.lastIndex(of: "@") {
+      user = String(trimmed[..<atIndex])
+      hostPort = trimmed[trimmed.index(after: atIndex)...]
+    } else {
+      user = nil
+      hostPort = trimmed[...]
+    }
+    guard !hostPort.isEmpty else { return nil }
+    let host: String
+    let port: Int?
+    if hostPort.hasPrefix("["), let close = hostPort.firstIndex(of: "]") {
+      host = String(hostPort[hostPort.index(after: hostPort.startIndex)..<close])
+      let after = hostPort[hostPort.index(after: close)...]
+      port = after.hasPrefix(":") ? Int(after.dropFirst()) : nil
+    } else if let colon = hostPort.lastIndex(of: ":"),
+      let parsed = Int(hostPort[hostPort.index(after: colon)...])
+    {
+      host = String(hostPort[..<colon])
+      port = parsed
+    } else {
+      host = String(hostPort)
+      port = nil
+    }
+    guard !host.isEmpty else { return nil }
+    self.init(alias: host, username: (user?.isEmpty ?? true) ? nil : user, port: port)
+  }
+
+  /// The `user@host` (or bare `host`) token passed to `ssh`. The host is left
+  /// bare even for an IPv6 literal, since the ssh CLI wants `user@::1`, not the
+  /// bracketed URL form.
+  public var sshDestination: String {
+    if let username, !username.isEmpty {
+      return "\(username)@\(alias)"
+    }
+    return alias
+  }
+
+  /// `[user@]host` with an IPv6 literal host bracketed, so a following `:port`
+  /// is unambiguous. Backs the id-bearing `authority` / `displayAuthority`, which
+  /// must round-trip through `init?(authority:)`; `sshDestination` stays bare for
+  /// the ssh CLI.
+  private var bracketedDestination: String {
+    let host = alias.contains(":") ? "[\(alias)]" : alias
+    if let username, !username.isEmpty {
+      return "\(username)@\(host)"
+    }
+    return host
+  }
+
+  /// Friendly `[user@]host[:port]` for display: username only when the user set
+  /// it, port only when non-default (not 22). The id-bearing `authority` always
+  /// includes the port; this is the human-facing variant.
+  public var displayAuthority: String {
+    guard let port, port != 22 else { return bracketedDestination }
+    return "\(bracketedDestination):\(port)"
+  }
+
+  /// `[user@]host[:port]` token used to brand remote ids and settings keys.
+  /// Always folds in the port (unlike `displayAuthority`), so two hosts that
+  /// differ only by port get distinct ids. Always shell/url safe.
+  public var authority: String {
+    guard let port else { return bracketedDestination }
+    return "\(bracketedDestination):\(port)"
+  }
+
+  /// Extra `ssh` option arguments derived from the host (currently just the
+  /// port). Always shell-safe tokens, so callers can splice them into a
+  /// command line without quoting.
+  public var sshOptionArguments: [String] {
+    guard let port else { return [] }
+    return ["-p", String(port)]
+  }
+}
diff --git a/SupacodeSettingsShared/Models/ScriptDefinition.swift b/SupacodeSettingsShared/Models/ScriptDefinition.swift
index c5531a2a8..57c36bb9f 100644
--- a/SupacodeSettingsShared/Models/ScriptDefinition.swift
+++ b/SupacodeSettingsShared/Models/ScriptDefinition.swift
@@ -65,6 +65,14 @@ public nonisolated struct ScriptDefinition: Identifiable, Codable, Equatable, Ha
   }
 }
 
+/// Where a `ScriptDefinition` is owned. Repo scripts shadow globals on ID
+/// collisions (see `merged`), so a definition resolves to `.repo` whenever
+/// it lives in the repository's settings, otherwise `.global`.
+public enum ScriptScope: String, Codable, Hashable, Sendable {
+  case repo
+  case global
+}
+
 // MARK: - Collection helpers
 
 extension [ScriptDefinition] {
diff --git a/SupacodeSettingsShared/Models/SettingsFile.swift b/SupacodeSettingsShared/Models/SettingsFile.swift
index 0d711b499..fe77b83c9 100644
--- a/SupacodeSettingsShared/Models/SettingsFile.swift
+++ b/SupacodeSettingsShared/Models/SettingsFile.swift
@@ -2,12 +2,14 @@ public nonisolated struct SettingsFile: Codable, Equatable, Sendable {
   public var global: GlobalSettings
   public var repositories: [String: RepositorySettings]
   public var repositoryRoots: [String]
+  public var remoteRepositoryRoots: [String]
   public var pinnedWorktreeIDs: [String]
 
   enum CodingKeys: String, CodingKey {
     case global
     case repositories
     case repositoryRoots
+    case remoteRepositoryRoots
     case pinnedWorktreeIDs
   }
 
@@ -15,6 +17,7 @@ public nonisolated struct SettingsFile: Codable, Equatable, Sendable {
     global: .default,
     repositories: [:],
     repositoryRoots: [],
+    remoteRepositoryRoots: [],
     pinnedWorktreeIDs: []
   )
 
@@ -22,11 +25,13 @@ public nonisolated struct SettingsFile: Codable, Equatable, Sendable {
     global: GlobalSettings = .default,
     repositories: [String: RepositorySettings] = [:],
     repositoryRoots: [String] = [],
+    remoteRepositoryRoots: [String] = [],
     pinnedWorktreeIDs: [String] = []
   ) {
     self.global = global
     self.repositories = repositories
     self.repositoryRoots = repositoryRoots
+    self.remoteRepositoryRoots = remoteRepositoryRoots
     self.pinnedWorktreeIDs = pinnedWorktreeIDs
   }
 
@@ -37,6 +42,8 @@ public nonisolated struct SettingsFile: Codable, Equatable, Sendable {
       try container.decodeIfPresent([String: RepositorySettings].self, forKey: .repositories)
       ?? [:]
     repositoryRoots = try container.decodeIfPresent([String].self, forKey: .repositoryRoots) ?? []
+    remoteRepositoryRoots =
+      try container.decodeIfPresent([String].self, forKey: .remoteRepositoryRoots) ?? []
     pinnedWorktreeIDs = try container.decodeIfPresent([String].self, forKey: .pinnedWorktreeIDs) ?? []
   }
 
@@ -45,6 +52,7 @@ public nonisolated struct SettingsFile: Codable, Equatable, Sendable {
     try container.encode(global, forKey: .global)
     try container.encode(repositories, forKey: .repositories)
     try container.encode(repositoryRoots, forKey: .repositoryRoots)
+    try container.encode(remoteRepositoryRoots, forKey: .remoteRepositoryRoots)
     try container.encode(pinnedWorktreeIDs, forKey: .pinnedWorktreeIDs)
   }
 }
diff --git a/SupacodeSettingsShared/Models/SkillAgent.swift b/SupacodeSettingsShared/Models/SkillAgent.swift
index d0ff60a65..137a62648 100644
--- a/SupacodeSettingsShared/Models/SkillAgent.swift
+++ b/SupacodeSettingsShared/Models/SkillAgent.swift
@@ -1,17 +1,21 @@
 public nonisolated enum SkillAgent: String, Equatable, Sendable, CaseIterable, Codable {
   case claude
   case codex
+  case copilot
   case kiro
+  case opencode
   // swiftlint:disable:next identifier_name
   case pi
 
   /// Path under the user's home where the agent stores its config
-  /// (e.g. `.claude`, `.codex`, `.kiro`, `.pi/agent`).
+  /// (e.g. `.claude`, `.codex`, `.kiro`, `.pi/agent`, `.config/opencode`).
   public var configDirectoryName: String {
     switch self {
     case .claude: ".claude"
     case .codex: ".codex"
+    case .copilot: ".copilot"
     case .kiro: ".kiro"
+    case .opencode: ".config/opencode"
     case .pi: ".pi/agent"
     }
   }
@@ -21,7 +25,9 @@ public nonisolated enum SkillAgent: String, Equatable, Sendable, CaseIterable, C
     switch self {
     case .claude: "Claude Code"
     case .codex: "Codex"
+    case .copilot: "Copilot CLI"
     case .kiro: "Kiro"
+    case .opencode: "OpenCode"
     case .pi: "Pi"
     }
   }
@@ -31,7 +37,9 @@ public nonisolated enum SkillAgent: String, Equatable, Sendable, CaseIterable, C
     switch self {
     case .claude: "claude-code-mark"
     case .codex: "codex-mark"
+    case .copilot: "copilot-mark"
     case .kiro: "kiro-mark"
+    case .opencode: "opencode-mark"
     case .pi: "pi-mark"
     }
   }
diff --git a/SupacodeSettingsShared/Support/SSHCommand.swift b/SupacodeSettingsShared/Support/SSHCommand.swift
new file mode 100644
index 000000000..e4051e5f8
--- /dev/null
+++ b/SupacodeSettingsShared/Support/SSHCommand.swift
@@ -0,0 +1,186 @@
+import Foundation
+
+/// Pure, stateless builders for the `ssh` command lines Supacode issues against
+/// a `RemoteHost`. Two consumers, two shapes:
+///
+///   - `invocation(...)` returns an argv for `Process` / `ShellClient`: ssh
+///     receives the remote command as a single argument, so only the *remote*
+///     shell re-parses it (one quoting level, applied in `remoteCommand`).
+///   - `commandLine(...)` returns a single string for a parent `/bin/sh -c`
+///     (Ghostty's surface command), so the remote command must additionally be
+///     quoted for the *local* shell (two quoting levels).
+///
+/// Every invocation shares `controlOptions` so N git calls plus the terminal
+/// reuse one multiplexed SSH connection: one auth / FIDO touch, and no
+/// per-call TCP+handshake round trip that would otherwise make a many-worktree
+/// sidebar crawl.
+public nonisolated enum SSHCommand {
+  public static let sshExecutablePath = "/usr/bin/ssh"
+
+  /// `%C` is ssh's hash of (local host, remote host, port, user): stable per
+  /// connection and short, keeping the control socket well under the
+  /// `sockaddr_un.sun_path` limit. ssh expands both `~` and `%C` itself.
+  public static let defaultControlPath = "~/.ssh/supacode-%C"
+
+  /// SSH connection-multiplexing options. `auto` opens a master if none exists
+  /// and reuses it otherwise; `ControlPersist` keeps it warm briefly after the
+  /// last client so a burst of git calls shares one connection.
+  public static func controlOptions(controlPath: String = defaultControlPath) -> [String] {
+    [
+      "-o", "ControlMaster=auto",
+      "-o", "ControlPath=\(controlPath)",
+      "-o", "ControlPersist=10m",
+    ]
+  }
+
+  /// Options for a non-interactive background probe (e.g. resolving a remote
+  /// repository at launch). `BatchMode` so it fails fast instead of blocking on
+  /// a password / host-key prompt; `ConnectTimeout` bounds the TCP+handshake;
+  /// `ServerAlive*` aborts a connection that stalls mid-command (~10s). A live
+  /// ControlMaster (an open terminal) bypasses auth, so the common case is fast.
+  public static let backgroundProbeOptions: [String] = [
+    "-o", "BatchMode=yes",
+    "-o", "ConnectTimeout=10",
+    "-o", "ServerAliveInterval=5",
+    "-o", "ServerAliveCountMax=2",
+  ]
+
+  /// POSIX single-quote a token so a parent shell passes it through literally.
+  public static func shellQuote(_ value: String) -> String {
+    "'" + value.replacing("'", with: "'\\''") + "'"
+  }
+
+  /// The command string the *remote* shell runs for a local
+  /// `(executable, arguments, workingDirectory)` invocation. A working
+  /// directory becomes `cd -- <dir> && exec ...` so the remote process starts
+  /// in the worktree and replaces the shell (signals / exit status map
+  /// straight through).
+  public static func remoteCommand(
+    executable: String,
+    arguments: [String],
+    workingDirectory: URL?
+  ) -> String {
+    let invocation = ([executable] + arguments).map(shellQuote).joined(separator: " ")
+    guard let workingDirectory else {
+      return invocation
+    }
+    let directory = shellQuote(workingDirectory.path(percentEncoded: false))
+    return "cd -- \(directory) && exec \(invocation)"
+  }
+
+  /// Wrap a remote command so it runs under a **login** shell. ssh's default
+  /// `$SHELL -c <cmd>` is non-interactive *and* non-login, so on macOS it only
+  /// inherits `~/.zshenv`'s bare PATH (`/usr/bin:/bin:/usr/sbin:/sbin`), so
+  /// Homebrew's `/opt/homebrew/bin` (where remote `zmx` / `git` / the `wt` shim
+  /// live) is NOT on it and the remote command fails with `command not found`.
+  /// A login shell reads `/etc/zprofile` (path_helper) + `~/.zprofile`
+  /// (`brew shellenv`), restoring the full PATH. `$SHELL` is expanded by ssh's
+  /// own outer shell; `exec` replaces it so signals / exit status pass through.
+  public static func loginShellWrapped(_ remoteScript: String) -> String {
+    "exec \"$SHELL\" -l -c " + shellQuote(remoteScript)
+  }
+
+  /// Login-shell-wrapped remote command that also forwards positional arguments
+  /// (`$0`, `$1`, …) to the `-c` script, so an arbitrary payload (e.g. a user
+  /// script) rides as `$1` instead of being concatenated into the script text.
+  /// `exec [env NAME=…] "$SHELL" -l -c '<script>' <arg0> <arg1> …`.
+  ///
+  /// `environment` is applied via an `env` prefix so the login shell inherits
+  /// the vars *before* it sources its profile (a plain `export` inside the `-c`
+  /// script would run only after the profile had already loaded).
+  public static func loginShellWrapped(
+    _ remoteScript: String,
+    positionalArguments: [String],
+    environment: [String: String] = [:]
+  ) -> String {
+    var line = "exec " + environmentPrefix(environment) + "\"$SHELL\" -l -c " + shellQuote(remoteScript)
+    for argument in positionalArguments {
+      line += " " + shellQuote(argument)
+    }
+    return line
+  }
+
+  /// An `env NAME='value' …` prefix (sorted, each value shell-quoted) or `""`
+  /// when there is nothing to set. Names are fixed identifiers so they stay
+  /// unquoted; values are quoted, so the prefix can't inject extra tokens.
+  private static func environmentPrefix(_ environment: [String: String]) -> String {
+    guard !environment.isEmpty else { return "" }
+    let assignments =
+      environment
+      .sorted { $0.key < $1.key }
+      .map { "\($0.key)=\(shellQuote($0.value))" }
+      .joined(separator: " ")
+    return "env \(assignments) "
+  }
+
+  /// Full local `ssh` argv for `Process` / `ShellClient`. The remote command is
+  /// a single argument; ssh hands it to the remote login shell verbatim.
+  public static func invocation(
+    host: RemoteHost,
+    executable: String,
+    arguments: [String],
+    workingDirectory: URL?,
+    allocateTTY: Bool = false,
+    controlPath: String = defaultControlPath,
+    extraOptions: [String] = []
+  ) -> (executableURL: URL, arguments: [String]) {
+    var sshArguments = controlOptions(controlPath: controlPath)
+    sshArguments += extraOptions
+    if allocateTTY {
+      sshArguments.append("-tt")
+    }
+    sshArguments += host.sshOptionArguments
+    sshArguments.append(host.sshDestination)
+    sshArguments.append(
+      loginShellWrapped(
+        remoteCommand(executable: executable, arguments: arguments, workingDirectory: workingDirectory)
+      )
+    )
+    return (URL(fileURLWithPath: sshExecutablePath), sshArguments)
+  }
+
+  /// Full `ssh` line as a single string for a parent `/bin/sh -c` (Ghostty's
+  /// surface command). The fixed option tokens are shell-safe and stay
+  /// unquoted (so ssh still expands `~` / `%C` in `ControlPath`); the
+  /// login-shell-wrapped remote command is quoted for the local shell.
+  public static func commandLine(
+    host: RemoteHost,
+    remoteCommand: String,
+    allocateTTY: Bool = true,
+    controlPath: String = defaultControlPath
+  ) -> String {
+    var tokens = [sshExecutablePath]
+    tokens += controlOptions(controlPath: controlPath)
+    if allocateTTY {
+      tokens.append("-tt")
+    }
+    tokens += host.sshOptionArguments
+    tokens.append(host.sshDestination)
+    tokens.append(shellQuote(loginShellWrapped(remoteCommand)))
+    return tokens.joined(separator: " ")
+  }
+
+  /// `commandLine` variant that forwards positional arguments to the remote
+  /// login-shell `-c` script, for callers that pass an arbitrary payload as
+  /// `$1` (e.g. a blocking script's user command).
+  public static func commandLine(
+    host: RemoteHost,
+    remoteScript: String,
+    positionalArguments: [String],
+    environment: [String: String] = [:],
+    allocateTTY: Bool = true,
+    controlPath: String = defaultControlPath
+  ) -> String {
+    var tokens = [sshExecutablePath]
+    tokens += controlOptions(controlPath: controlPath)
+    if allocateTTY {
+      tokens.append("-tt")
+    }
+    tokens += host.sshOptionArguments
+    tokens.append(host.sshDestination)
+    tokens.append(
+      shellQuote(
+        loginShellWrapped(remoteScript, positionalArguments: positionalArguments, environment: environment)))
+    return tokens.joined(separator: " ")
+  }
+}
diff --git a/SupacodeSettingsShared/Support/SupaLogger.swift b/SupacodeSettingsShared/Support/SupaLogger.swift
index 8a97d3827..3d00385c9 100644
--- a/SupacodeSettingsShared/Support/SupaLogger.swift
+++ b/SupacodeSettingsShared/Support/SupaLogger.swift
@@ -36,4 +36,12 @@ public nonisolated struct SupaLogger: Sendable {
       logger.warning("\(message, privacy: .public)")
     #endif
   }
+
+  public func error(_ message: String) {
+    #if DEBUG
+      print("[\(category)] \(message)")
+    #else
+      logger.error("\(message, privacy: .public)")
+    #endif
+  }
 }
diff --git a/docs/remote-ssh-setup.md b/docs/remote-ssh-setup.md
new file mode 100644
index 000000000..ba42d15c9
--- /dev/null
+++ b/docs/remote-ssh-setup.md
@@ -0,0 +1,261 @@
+# Remote SSH Host: Build & Bootstrap
+
+This document captures the verified steps to get this fork building green from a
+clean checkout, plus the design notes for the remote-SSH-host feature
+(`feat/remote-ssh-host`).
+
+## 1. Toolchain bootstrap
+
+The build is driven by **Tuist** (project generation) + **mise** (tool version
+pinning) + **zig** (builds GhosttyKit and the bundled `zmx` binary from source).
+Pinned versions live in `mise.toml`:
+
+| tool      | version  |
+|-----------|----------|
+| tuist     | 4.180.0  |
+| zig       | 0.15.2   |
+| swiftlint | latest   |
+| xcsift    | latest   |
+
+Verified on macOS 26 (Tahoe), Xcode 26.2, Apple Silicon.
+
+### Steps (clean checkout → green build)
+
+```bash
+# 1. Install mise (tool manager). Not pre-installed; required by the Makefile,
+#    which shells every tool through `mise exec -- <tool>`.
+brew install mise
+
+# 2. Trust the repo config and install the pinned toolchain.
+mise trust
+mise install
+# Gotcha: the zmx submodule ships its OWN mise.toml that must also be trusted,
+# otherwise `make build-zmx` fails with "Config files ... are not trusted":
+mise trust ThirdParty/zmx/mise.toml
+
+# 3. Initialize submodules (the build scripts auto-init ghostty/zmx on demand,
+#    but doing it up front is explicit and also pulls Resources/git-wt):
+git submodule update --init --recursive
+
+# 4. Install xcbeautify (log formatter the Makefile pipes xcodebuild through).
+#    It is NOT listed in mise.toml, so on a clean machine `make build-app`
+#    fails with: mise ERROR "xcbeautify" couldn't exec process.
+brew install xcbeautify
+
+# 5. Build native dependencies, generate the project, build the app.
+make build-ghostty-xcframework   # zig → .build/ghostty/GhosttyKit.xcframework (slow, cached by fingerprint)
+make build-zmx                    # zig → .build/zmx/bin/zmx (universal: x86_64 + arm64)
+make generate-project             # tuist generate → supacode.xcworkspace
+make build-app                    # xcodebuild Debug → "Build Succeeded"
+make run-app                      # launch the Debug build
+```
+
+`make build-app` already depends on the generation stamp, and the Tuist project
+has build phases that invoke `build-ghostty.sh` / `build-zmx.sh`, so once the
+native deps are cached a plain `make build-app` is enough on subsequent runs.
+
+### Reusing an existing zig 0.15.2
+
+If `~/.ttf-toolchain/zig-aarch64-macos-0.15.2/zig` already exists you can reuse
+it, but note that this fork's GhosttyKit build fingerprints on the **pinned
+submodule commit** (`ThirdParty/ghostty`), so a prebuilt xcframework from a
+*different* ghostty checkout is not reused: `mise install`'s own zig 0.15.2 is
+the simplest path.
+
+### Known gotchas (summary)
+
+- `mise` is not pre-installed; the Makefile assumes it.
+- The `ThirdParty/zmx` submodule has a nested `mise.toml` that needs a separate
+  `mise trust`.
+- `xcbeautify` is referenced by the Makefile but absent from `mise.toml`;
+  install it via brew.
+- GitHub API rate limits (HTTP 403) during `mise install` only affect optional
+  build-time deps (`zls`, `bats`) pulled in by the zmx build; they retry/resolve
+  and don't block the app build.
+
+## 2. Remote SSH host: design (Phase A)
+
+Goal: a worktree can live on a **remote host**; its git/worktree operations and
+its terminal (zmx) run remotely over SSH, while libghostty renders locally. No
+file sync, just terminal + git. The single chokepoint is the transport: make
+`ShellClient` host-aware, and the rest of `GitClient` follows.
+
+### Pieces
+
+1. **`RemoteHost`** (`SupacodeSettingsShared/Models/RemoteHost.swift`): value
+   type describing an SSH destination: `alias`, optional `username`, `port`, and
+   a remote `worktreeBasePath`. `nil` host everywhere means "local" (unchanged
+   behavior).
+
+2. **`SSHCommand`** (`SupacodeSettingsShared/Support/SSHCommand.swift`): pure,
+   stateless builders:
+   - `controlOptions`: SSH `ControlMaster=auto` multiplexing so N git calls +
+     the terminal share one connection (one auth / FIDO touch, no per-call RTT
+     storm).
+   - `remoteCommand(executable:arguments:workingDirectory:)`: the string the
+     remote shell runs; working directory becomes `cd -- <dir> && exec ...`.
+   - `invocation(...)`: full local `ssh` argv for `Process`/`ShellClient`.
+   - `commandLine(...)`: full `ssh` line as a single string for a parent
+     `/bin/sh -c` (Ghostty's surface command), TTY allocated.
+
+3. **`ShellClient.ssh(host:base:)`**: wraps an inner `ShellClient` so every
+   `run` / `runStream` / `runLogin*` transforms `(exe, args, cwd)` into an
+   `ssh <host> <remoteCommand>` invocation. This is the load-bearing chokepoint:
+   `GitClient(shell: .ssh(host:))` makes all git/`wt` paths run remotely.
+
+4. **`GitClientDependency.ssh(host:)`**: same closures as `liveValue` but every
+   `GitClient` is constructed with the ssh-flavored shell.
+
+5. **Terminal launch**: `ZmxAttach.buildRemoteCommand(host:sessionID:userCommand:)`
+   produces `ssh -tt <host> zmx attach supa-<uuid> [/bin/sh -c '<cmd>']`. When a
+   worktree carries a `host`, `WorktreeTerminalState.createSurface` passes this
+   as the surface command and `workingDirectory: nil` (the path is remote).
+
+### Out of scope for Phase A (follow-ups)
+
+- Real-host SSH connectivity + libghostty rendering verification (needs a FIDO
+  touch and human eyes, validated manually, not in CI/tests).
+- Host selection UI + persistence; `RemoteHost` plumbing through `Repository` /
+  persisted layouts.
+- `Worktree.id` is `workingDirectory.path`; across hosts paths can collide, so
+  ids must be host-keyed (`<host>:<path>`) with a persistence migration before
+  remote and local worktrees coexist.
+- The bundled `wt` binary path is local; remote worktree creation assumes `git`
+  (and the `wt` shim) are available on the remote `$PATH`.
+- File watching: the local kqueue HEAD watcher can't cross SSH; replace with a
+  debounced `git rev-parse HEAD` poll for remote worktrees.
+
+## 3. Remote SSH host: sidebar UI (Phase B, first slice)
+
+Phase B makes remote worktrees usable from the GUI: you can add an SSH host
+through the sidebar, and remote repos are visually separated from local ones.
+
+### Pieces
+
+1. **`RemoteRepositoryConfig`** (`SupacodeSettingsShared/Models`): a persisted
+   `(host, remotePath, displayName)`. Stored in
+   **`GlobalSettings.remoteRepositories`** (mirrors `globalScripts`), so it
+   survives relaunch and never touches the local `repositoryRoots` list.
+
+2. **`Repository.host`**: non-nil marks a remote repository. Each remote config
+   is materialized at load (`RepositoriesFeature.synthesizeRemoteRepositories`)
+   into a **folder-kind** `Repository` whose single synthetic worktree carries
+   the host. Folder-kind = no git shell-outs against the (locally unreachable)
+   remote path; selection + terminal reuse the folder machinery, and the
+   terminal goes SSH because `Worktree.host != nil` (Phase A). Remote repo /
+   worktree ids are **host-keyed** (`remote:<dest>:<path>`) so they never
+   collide with a local path, and the local-only `buildRepositorySections` loop
+   (keyed off `rootURL.path`) never accidentally renders them.
+
+3. **Load merge**: `loadRepositoriesData` appends the synthesized remote repos
+   on *every* load path (initial, reload, open, removal), reading the configs
+   through `@Shared(.settingsFile)`. `state.repositoryRoots` stays local-only, so
+   reload never tries to stat a remote path; `reconcileSidebarItems` /
+   `reconcileSidebarState` iterate `state.repositories` (which includes remote),
+   so remote rows + seeded sidebar sections come for free.
+
+4. **Sidebar partition**: `SidebarStructure` gains `RepositoryLocality` and a
+   `.partitionHeader(kind:)` section. `buildRepositorySections` emits local repo
+   sections, then (only when remote repos exist) a `Local` header, the locals,
+   a `Remote` header, and the remote folder sections. A purely-local sidebar is
+   visually unchanged.
+
+5. **Add entry**: the sidebar's `Add…` toolbar button is now a menu:
+   *Repository or Folder…* (the existing local `NSOpenPanel`) and
+   *Remote Repository…* → `AddRemoteRepositorySheet` (ssh host / user / port /
+   remote path / name). Submit dispatches `.addRemoteRepository(config)`, which
+   appends to `GlobalSettings.remoteRepositories` and reloads.
+
+6. **Remote terminal cwd**: for a remote worktree, the surface command defaults
+   to `cd <remotePath> 2>/dev/null; exec "$SHELL" -l` so a freshly created zmx
+   session lands in the project directory.
+
+### How to verify in the GUI
+
+1. Make sure the remote host has `zmx` on its `$PATH` (see §2 layer 2).
+2. In Supacode: sidebar toolbar **Add… → Remote Repository…**, enter an ssh
+   host (e.g. `devbox`) and an absolute remote path, Add.
+3. The repo appears under a **Remote** section header. Select it → a terminal
+   opens over `ssh -tt <host> zmx attach …`, lands in the remote dir, and
+   renders locally. (First connection may require a FIDO touch.)
+
+### Phase B known limitations / follow-ups
+
+- Remote repo/worktree ids embed `host:path` but the path is not otherwise
+  host-namespaced in `folderWorktreeID`; two hosts at the same path, or a remote
+  path equal to a local repo path, are not supported (documented edge).
+- A `~`-relative remote path round-trips through `URL(fileURLWithPath:)`, so the
+  `cd` may miss (the `2>/dev/null` fallback keeps the shell usable). Prefer an
+  absolute remote path for now.
+- No remote-repo removal UI yet (the `.removeRemoteRepository` action exists);
+  no per-remote customization, no remote git worktree discovery/creation.
+- `isGitRepository` / `rootDirectoryExists` still probe the local filesystem;
+  remote repos are folder-kind so they don't hit that path.
+
+## 4. Unified add-repo entry + remote agent-hook channel
+
+### Unified "add repository" entry points
+
+Adding a remote repo used to be reachable only from the sidebar toolbar menu.
+It now mirrors the local "Open Repository or Folder" flow across all three entry
+points, all routed through reducer state so they can be presented from anywhere:
+
+- New action `RepositoriesFeature.setAddRemoteRepositoryPresented(Bool)` drives
+  `State.isAddRemoteRepositoryPresented`; `SidebarView` binds the
+  `AddRemoteRepositorySheet` to it.
+- **Command palette**: `Add Remote Repository`
+  (`CommandPaletteItem.Kind.addRemoteRepository` →
+  `Delegate.addRemoteRepository`), routed in `AppFeature` to
+  `setAddRemoteRepositoryPresented(true)`.
+- **Empty state**: a secondary `Add Remote Repository…` link next to
+  `Open Repository or Folder…`.
+- **Sidebar toolbar**: the existing `Add… → Remote Repository…` button now
+  dispatches the action instead of toggling a local `@State`.
+
+### Remote agent presence via in-band OSC (awaiting-input badge over SSH)
+
+The orange "awaiting input" badge is driven by a coding agent's hook. Locally it
+writes a JSON envelope to the **local** Unix socket `$SUPACODE_SOCKET_PATH`
+(`AgentHookSocketServer`), keyed by `$SUPACODE_SURFACE_ID`. A Unix socket isn't
+reachable across SSH, so for a remote surface the badge never lit.
+
+Rather than tunnel the socket (the earlier, ControlMaster-fragile `ssh -R`
+attempt), presence now also rides the terminal data stream as an **OSC 9**
+sequence, the same channel that already carries everything else over
+`zmx → ssh -tt → libghostty`. zmx forwards OSC verbatim (it only rewrites OSC
+133;A), and an OSC arrives on a specific surface's stream, so it needs no
+out-of-band socket and no `surface_id` plumbing. Flow:
+
+1. The hook command (`AgentHookSettingsCommand.compositeCommand`) emits, per
+   event, `printf '\033]9;supacode-presence;v1;<agent>;<event>\a' >/dev/tty`
+   in addition to the local socket envelope. It's guarded by
+   `SUPACODE_SURFACE_ID` alone (independent of the socket guard, so it fires on a
+   remote host with no `SUPACODE_SOCKET_PATH`), and writes to `/dev/tty`: the
+   zmx PTY slave (zmx uses `forkpty`), bypassing the hook's `>/dev/null` stdout
+   (which Codex parses as JSON). The shared definition lives in
+   `AgentPresenceOSC` (sentinel + parser).
+2. libghostty surfaces the OSC as a desktop notification;
+   `GhosttySurfaceBridge` intercepts the sentinel (`parsePresenceSignal`), routes
+   it to `onPresenceSignal` (suppressing the user-facing notification), and
+   `WorktreeTerminalState` synthesizes an `AgentHookEvent` (`pid: nil`, surface
+   from the receiving `view.id`) through the same debounced
+   `WorktreeTerminalManager.dispatchHookEvent` path as the socket.
+3. `AgentPresenceFeature` lazily creates a pid-less record for OSC-origin events
+   (the liveness sweep skips empty-pid records; they clear on pid-less
+   `session_end` or surface close), so local pid-bearing behavior is unchanged.
+
+The remote attach command (`ZmxAttach.buildRemoteCommand`) only needs to export
+`SUPACODE_SURFACE_ID` so the OSC fires; no reverse socket, no remote
+`SUPACODE_SOCKET_PATH`.
+
+**Prerequisites / notes (verify on a real host):**
+
+- **Both machines run Supacode**, so the agent hook (now OSC-emitting) is
+  installed on the remote via its own `ClaudeSettingsInstaller`/Codex config.
+  Updating Supacode on the remote rewrites its hook (`.outdated` → reinstall).
+- Real-host SSH + libghostty OSC rendering are verified manually (FIDO touch),
+  not in CI. Unit tests cover the command construction (`AgentHookCommandTests`),
+  OSC parse/routing (`GhosttySurfaceBridgeTests`), and the pid-less presence path
+  (`AgentPresenceFeatureTests`).
+- If a hook ever runs without a controlling tty, the `/dev/tty` write fails
+  harmlessly (`|| true`); locally the socket still delivers presence.
diff --git a/mise.toml b/mise.toml
index b7e6b2ecc..97f4fa346 100644
--- a/mise.toml
+++ b/mise.toml
@@ -1,6 +1,11 @@
 [tools]
 tuist = "4.180.0"
 zig = "0.15.2"
-swiftlint = "latest"
+swiftlint = "0.64.0"
+xcbeautify = "3.2.1"
+# swift-format pinned so `make format` is reproducible across contributors'
+# Xcodes (the toolchain's built-in `swift format` drifts per Xcode). Tag tracks
+# the Swift toolchain: 602.x ↔ Swift 6.2.
+"spm:swiftlang/swift-format" = "602.0.0"
 "github:ldomaradzki/xcsift" = "latest"
 "npm:create-dmg" = "latest"
diff --git a/patches/ghostty-command-wrapper.patch b/patches/ghostty-command-wrapper.patch
new file mode 100644
index 000000000..1a499f87d
--- /dev/null
+++ b/patches/ghostty-command-wrapper.patch
@@ -0,0 +1,149 @@
+diff --git a/include/ghostty.h b/include/ghostty.h
+index 3c4002abc..362fb232d 100644
+--- a/include/ghostty.h
++++ b/include/ghostty.h
+@@ -455,6 +455,9 @@ typedef struct {
+   const char* initial_input;
+   bool wait_after_command;
+   ghostty_surface_context_e context;
++  const char* const* command_wrapper;
++  size_t command_wrapper_count;
++  bool disable_shell_integration;
+ } ghostty_surface_config_s;
+ 
+ typedef struct {
+diff --git a/src/Surface.zig b/src/Surface.zig
+index c8055cfee..def042ba0 100644
+--- a/src/Surface.zig
++++ b/src/Surface.zig
+@@ -635,6 +635,7 @@ pub fn init(
+         // Initialize our IO backend
+         var io_exec = try termio.Exec.init(alloc, .{
+             .command = command,
++            .command_wrapper = config.@"command-wrapper",
+             .env = env,
+             .env_override = config.env,
+             .shell_integration = config.@"shell-integration",
+diff --git a/src/apprt/embedded.zig b/src/apprt/embedded.zig
+index 0d5a4f8da..ba385db02 100644
+--- a/src/apprt/embedded.zig
++++ b/src/apprt/embedded.zig
+@@ -460,6 +460,19 @@ pub const Surface = struct {
+ 
+         /// Context for the new surface
+         context: apprt.surface.NewSurfaceContext = .window,
++
++        /// A wrapper command (argv) prepended to the final resolved command.
++        /// See the `command-wrapper` config docs. Each element is a NUL
++        /// terminated argument; `command_wrapper_count` is the element count.
++        /// When null/empty, no wrapper is applied.
++        command_wrapper: ?[*]const [*:0]const u8 = null,
++        command_wrapper_count: usize = 0,
++
++        /// Force `shell-integration = none` for this surface only, regardless of
++        /// the global config. For surfaces that run a self-managing command
++        /// (e.g. a script runner that emits its own OSC sequences) and must not
++        /// have Ghostty's integration injected into the shell.
++        disable_shell_integration: bool = false,
+     };
+ 
+     pub fn init(self: *Surface, app: *App, opts: Options) !void {
+@@ -534,6 +547,25 @@ pub const Surface = struct {
+             }
+         }
+ 
++        // If we have a command wrapper from the options then we set it. This
++        // is always a direct (already-tokenized) command so paths with spaces
++        // survive without shell re-splitting.
++        if (opts.command_wrapper) |c_wrapper| {
++            if (opts.command_wrapper_count > 0) {
++                const alloc = config.arenaAlloc();
++                const argv = try alloc.alloc([:0]const u8, opts.command_wrapper_count);
++                for (c_wrapper[0..opts.command_wrapper_count], 0..) |arg, i| {
++                    argv[i] = try alloc.dupeZ(u8, std.mem.sliceTo(arg, 0));
++                }
++                config.@"command-wrapper" = .{ .direct = argv };
++            }
++        }
++
++        // Opt this surface out of shell integration regardless of global config.
++        if (opts.disable_shell_integration) {
++            config.@"shell-integration" = .none;
++        }
++
+         // Apply any environment variables that were requested.
+         if (opts.env_var_count > 0) {
+             const alloc = config.arenaAlloc();
+diff --git a/src/config/Config.zig b/src/config/Config.zig
+index 13f78eea6..fb13433e5 100644
+--- a/src/config/Config.zig
++++ b/src/config/Config.zig
+@@ -1197,6 +1197,22 @@ command: ?Command = null,
+ ///     manually.
+ @"initial-command": ?Command = null,
+ 
++/// A wrapper command that is prepended to the final command Ghostty would
++/// otherwise execute, after shell resolution, shell integration, and (on
++/// macOS) the `login(1)` wrapping have all been applied. The wrapper's
++/// arguments are placed before the resolved argv, so the resolved command
++/// runs as a child of the wrapper.
++///
++/// This exists so an embedder can run the shell under a supervisor such as a
++/// session-persistence multiplexer while keeping Ghostty's normal shell
++/// resolution and shell integration fully intact. Without this, an embedder
++/// would have to replace `command` with the wrapper, which loses the user's
++/// configured `command`, shell detection, and integration.
++///
++/// Specified like `command`, e.g. `direct:zmx attach my-session`. Use the
++/// `direct:` prefix to avoid a `/bin/sh -c` roundtrip for the wrapper.
++@"command-wrapper": ?Command = null,
++
+ /// Controls when command finished notifications are sent. There are
+ /// three options:
+ ///
+diff --git a/src/termio/Exec.zig b/src/termio/Exec.zig
+index 0f35b5787..06aff655f 100644
+--- a/src/termio/Exec.zig
++++ b/src/termio/Exec.zig
+@@ -559,6 +559,7 @@ pub const ThreadData = struct {
+ 
+ pub const Config = struct {
+     command: ?configpkg.Command = null,
++    command_wrapper: ?configpkg.Command = null,
+     env: EnvMap,
+     env_override: configpkg.RepeatableStringMap = .{},
+     shell_integration: configpkg.Config.ShellIntegration = .detect,
+@@ -815,7 +816,7 @@ const Subprocess = struct {
+         }
+ 
+         // Build our args list
+-        const args: []const [:0]const u8 = execCommand(
++        const base_args: []const [:0]const u8 = execCommand(
+             alloc,
+             shell_command,
+             internal_os.passwd,
+@@ -840,6 +841,24 @@ const Subprocess = struct {
+             error.SystemError => return err,
+         };
+ 
++        // If a command wrapper is configured, prepend its arguments to the
++        // resolved command so the resolved argv (including the macOS login(1)
++        // wrapping and any shell integration) runs as a child of the wrapper.
++        const args: []const [:0]const u8 = if (cfg.command_wrapper) |wrapper| wrap: {
++            var list: std.ArrayList([:0]const u8) = try .initCapacity(
++                alloc,
++                base_args.len + 4,
++            );
++            defer list.deinit(alloc);
++
++            var it = try wrapper.argIterator(alloc);
++            defer it.deinit();
++            while (it.next()) |arg| try list.append(alloc, try alloc.dupeZ(u8, arg));
++
++            try list.appendSlice(alloc, base_args);
++            break :wrap try list.toOwnedSlice(alloc);
++        } else base_args;
++
+         // We have to copy the cwd because there is no guarantee that
+         // pointers in full_config remain valid.
+         const cwd: ?[:0]u8 = if (cfg.working_directory) |cwd|
diff --git a/patches/ghostty-osc3008-context-signal.patch b/patches/ghostty-osc3008-context-signal.patch
new file mode 100644
index 000000000..4f126025f
--- /dev/null
+++ b/patches/ghostty-osc3008-context-signal.patch
@@ -0,0 +1,290 @@
+diff --git a/include/ghostty.h b/include/ghostty.h
+index 3c4002abc..626c96876 100644
+--- a/include/ghostty.h
++++ b/include/ghostty.h
+@@ -641,6 +641,13 @@ typedef struct {
+   const char* body;
+ } ghostty_action_desktop_notification_s;
+ 
++// apprt.action.ContextSignal.C
++typedef struct {
++  uint8_t action;  // 0 = start, 1 = end
++  const char* id;
++  const char* metadata;
++} ghostty_action_context_signal_s;
++
+ // apprt.action.SetTitle.C
+ typedef struct {
+   const char* title;
+@@ -926,6 +933,7 @@ typedef enum {
+   GHOSTTY_ACTION_SEARCH_SELECTED,
+   GHOSTTY_ACTION_READONLY,
+   GHOSTTY_ACTION_COPY_TITLE_TO_CLIPBOARD,
++  GHOSTTY_ACTION_CONTEXT_SIGNAL,
+ } ghostty_action_tag_e;
+ 
+ typedef union {
+@@ -942,6 +950,7 @@ typedef union {
+   ghostty_action_scrollbar_s scrollbar;
+   ghostty_action_inspector_e inspector;
+   ghostty_action_desktop_notification_s desktop_notification;
++  ghostty_action_context_signal_s context_signal;
+   ghostty_action_set_title_s set_title;
+   ghostty_action_set_title_s set_tab_title;
+   ghostty_action_prompt_title_e prompt_title;
+diff --git a/src/Surface.zig b/src/Surface.zig
+index c8055cfee..be18a3b6a 100644
+--- a/src/Surface.zig
++++ b/src/Surface.zig
+@@ -1073,6 +1073,16 @@ pub fn handleMessage(self: *Surface, msg: Message) !void {
+             try self.showDesktopNotification(title, body);
+         },
+ 
++        .context_signal => |signal| {
++            const id = std.mem.sliceTo(&signal.id, 0);
++            const metadata = std.mem.sliceTo(&signal.metadata, 0);
++            _ = try self.rt_app.performAction(
++                .{ .surface = self },
++                .context_signal,
++                .{ .action = signal.action, .id = id, .metadata = metadata },
++            );
++        },
++
+         .renderer_health => |health| self.updateRendererHealth(health),
+ 
+         .scrollbar => |scrollbar| self.updateScrollbar(scrollbar),
+diff --git a/src/apprt/action.zig b/src/apprt/action.zig
+index f6865af83..e7180a2d2 100644
+--- a/src/apprt/action.zig
++++ b/src/apprt/action.zig
+@@ -343,6 +343,10 @@ pub const Action = union(Key) {
+     /// otherwise the terminal-set title.
+     copy_title_to_clipboard,
+ 
++    /// OSC 3008 hierarchical context signal (UAPI spec). A program inside the
++    /// terminal signalled a context change.
++    context_signal: ContextSignal,
++
+     /// Sync with: ghostty_action_tag_e
+     pub const Key = enum(c_int) {
+         quit,
+@@ -410,6 +414,7 @@ pub const Action = union(Key) {
+         search_selected,
+         readonly,
+         copy_title_to_clipboard,
++        context_signal,
+ 
+         test "ghostty.h Action.Key" {
+             try lib.checkGhosttyHEnum(Key, "GHOSTTY_ACTION_");
+@@ -771,6 +776,28 @@ pub const DesktopNotification = struct {
+     }
+ };
+ 
++pub const ContextSignal = struct {
++    /// 0 = start, 1 = end.
++    action: u8,
++    id: [:0]const u8,
++    metadata: [:0]const u8,
++
++    // Sync with: ghostty_action_context_signal_s
++    pub const C = extern struct {
++        action: u8,
++        id: [*:0]const u8,
++        metadata: [*:0]const u8,
++    };
++
++    pub fn cval(self: ContextSignal) C {
++        return .{
++            .action = self.action,
++            .id = self.id.ptr,
++            .metadata = self.metadata.ptr,
++        };
++    }
++};
++
+ pub const KeySequence = union(enum) {
+     trigger: input.Trigger,
+     end,
+diff --git a/src/apprt/surface.zig b/src/apprt/surface.zig
+index 3cb0016fa..296e70bc9 100644
+--- a/src/apprt/surface.zig
++++ b/src/apprt/surface.zig
+@@ -60,6 +60,20 @@ pub const Message = union(enum) {
+         body: [255:0]u8,
+     },
+ 
++    /// OSC 3008 hierarchical context signal (UAPI spec).
++    context_signal: struct {
++        /// The signalled action: 0 = start, 1 = end.
++        action: u8,
++
++        /// Context identifier (1-64 chars per spec).
++        id: [64:0]u8,
++
++        /// Raw semicolon-separated key=value metadata, truncated to 2047 bytes
++        /// (may split a field; see handleContextSignal). Sized to carry a
++        /// base64-encoded notification payload, not just the tiny presence fields.
++        metadata: [2047:0]u8,
++    },
++
+     /// Health status change for the renderer.
+     renderer_health: renderer.Health,
+ 
+diff --git a/src/terminal/stream.zig b/src/terminal/stream.zig
+index 9771334f9..4187bcbfb 100644
+--- a/src/terminal/stream.zig
++++ b/src/terminal/stream.zig
+@@ -125,6 +125,7 @@ pub const Action = union(Key) {
+     kitty_color_report: kitty.color.OSC,
+     color_operation: ColorOperation,
+     semantic_prompt: SemanticPrompt,
++    context_signal: ContextSignal,
+ 
+     pub const Key = lib.Enum(
+         lib.target,
+@@ -222,6 +223,7 @@ pub const Action = union(Key) {
+             "kitty_color_report",
+             "color_operation",
+             "semantic_prompt",
++            "context_signal",
+         },
+     );
+ 
+@@ -348,6 +350,26 @@ pub const Action = union(Key) {
+         }
+     };
+ 
++    pub const ContextSignal = struct {
++        action: u8,
++        id: []const u8,
++        metadata: []const u8,
++
++        pub const C = extern struct {
++            action: u8,
++            id: lib.String,
++            metadata: lib.String,
++        };
++
++        pub fn cval(self: ContextSignal) ContextSignal.C {
++            return .{
++                .action = self.action,
++                .id = .init(self.id),
++                .metadata = .init(self.metadata),
++            };
++        }
++    };
++
+     pub const StartHyperlink = struct {
+         uri: []const u8,
+         id: ?[]const u8,
+@@ -2047,6 +2069,21 @@ pub fn Stream(comptime H: type) type {
+                     self.handler.vt(.progress_report, v);
+                 },
+ 
++                .context_signal => |v| {
++                    // The u8 wire value is a locked C ABI; pin the enum mapping so a
++                    // future ghostty bump that reorders Action fails loudly here
++                    // instead of silently renumbering every consumer.
++                    comptime {
++                        std.debug.assert(@intFromEnum(@TypeOf(v.action).start) == 0);
++                        std.debug.assert(@intFromEnum(@TypeOf(v.action).end) == 1);
++                    }
++                    self.handler.vt(.context_signal, .{
++                        .action = @intFromEnum(v.action),
++                        .id = v.id,
++                        .metadata = v.metadata,
++                    });
++                },
++
+                 .conemu_sleep,
+                 .conemu_show_message_box,
+                 .conemu_change_tab_title,
+@@ -2058,7 +2095,6 @@ pub fn Stream(comptime H: type) type {
+                 .conemu_run_process,
+                 .kitty_text_sizing,
+                 .kitty_clipboard_protocol,
+-                .context_signal,
+                 => {
+                     log.debug("unimplemented OSC callback: {}", .{cmd});
+                 },
+diff --git a/src/terminal/stream_terminal.zig b/src/terminal/stream_terminal.zig
+index 8e0f91110..93712be0d 100644
+--- a/src/terminal/stream_terminal.zig
++++ b/src/terminal/stream_terminal.zig
+@@ -259,6 +259,7 @@ pub const Handler = struct {
+             // Have no terminal-modifying effect
+             .report_pwd,
+             .show_desktop_notification,
++            .context_signal,
+             .progress_report,
+             .clipboard_contents,
+             .title_push,
+diff --git a/src/termio/stream_handler.zig b/src/termio/stream_handler.zig
+index fb3a6b3ff..08084ca69 100644
+--- a/src/termio/stream_handler.zig
++++ b/src/termio/stream_handler.zig
+@@ -327,6 +327,7 @@ pub const StreamHandler = struct {
+             .window_title => try self.windowTitle(value.title),
+             .report_pwd => try self.reportPwd(value.url),
+             .show_desktop_notification => try self.showDesktopNotification(value.title, value.body),
++            .context_signal => try self.handleContextSignal(value.action, value.id, value.metadata),
+             .progress_report => self.progressReport(value),
+             .start_hyperlink => try self.startHyperlink(value.uri, value.id),
+             .clipboard_contents => try self.clipboardContents(value.kind, value.data),
+@@ -1447,6 +1448,41 @@ pub const StreamHandler = struct {
+         self.surfaceMessageWriter(message);
+     }
+ 
++    fn handleContextSignal(
++        self: *StreamHandler,
++        action: u8,
++        id: []const u8,
++        metadata: []const u8,
++    ) !void {
++        var message = apprt.surface.Message{ .context_signal = undefined };
++
++        message.context_signal.action = action;
++
++        // id is spec-bounded to 64 (max_context_id_len) by the parser; the clamp
++        // is defense-in-depth and is not expected to fire. Warn symmetrically
++        // with the metadata path so a future spec-cap raise doesn't hide an
++        // id-truncation regression.
++        if (id.len > message.context_signal.id.len) {
++            log.warn("OSC 3008: context_signal id truncated from {d} to {d} bytes", .{
++                id.len, message.context_signal.id.len,
++            });
++        }
++        const id_len = @min(id.len, message.context_signal.id.len);
++        @memcpy(message.context_signal.id[0..id_len], id[0..id_len]);
++        message.context_signal.id[id_len] = 0;
++
++        if (metadata.len > message.context_signal.metadata.len) {
++            log.warn("OSC 3008: context_signal metadata truncated from {d} to {d} bytes", .{
++                metadata.len, message.context_signal.metadata.len,
++            });
++        }
++        const metadata_len = @min(metadata.len, message.context_signal.metadata.len);
++        @memcpy(message.context_signal.metadata[0..metadata_len], metadata[0..metadata_len]);
++        message.context_signal.metadata[metadata_len] = 0;
++
++        self.surfaceMessageWriter(message);
++    }
++
+     /// Send a report to the pty.
+     pub fn sendSizeReport(self: *StreamHandler, style: terminal.SizeReportStyle) void {
+         switch (style) {
+diff --git a/src/terminal/osc.zig b/src/terminal/osc.zig
+index 36cfd7f82..f610bf4e2 100644
+--- a/src/terminal/osc.zig
++++ b/src/terminal/osc.zig
+@@ -583,7 +583,9 @@ pub const Parser = struct {
+             },
+ 
+             .@"3008" => switch (c) {
+-                ';' => self.captureTrailing(.fixed),
++                // Supacode: allocating (like OSC 52) so an over-2048 notify keeps its
++                // title/earlier fields instead of being discarded whole (body may drop).
++                ';' => self.captureTrailing(.allocating),
+                 else => self.state = .invalid,
+             },
+ 
diff --git a/patches/surface-font-size-getter.patch b/patches/surface-font-size-getter.patch
new file mode 100644
index 000000000..6382b296e
--- /dev/null
+++ b/patches/surface-font-size-getter.patch
@@ -0,0 +1,31 @@
+diff --git a/include/ghostty.h b/include/ghostty.h
+index 3c4002abc..a0227b97b 100644
+--- a/include/ghostty.h
++++ b/include/ghostty.h
+@@ -1082,6 +1082,7 @@ void ghostty_surface_free(ghostty_surface_t);
+ void* ghostty_surface_userdata(ghostty_surface_t);
+ ghostty_app_t ghostty_surface_app(ghostty_surface_t);
+ ghostty_surface_config_s ghostty_surface_inherited_config(ghostty_surface_t, ghostty_surface_context_e);
++float ghostty_surface_font_size(ghostty_surface_t);
+ void ghostty_surface_update_config(ghostty_surface_t, ghostty_config_t);
+ bool ghostty_surface_needs_confirm_quit(ghostty_surface_t);
+ bool ghostty_surface_process_exited(ghostty_surface_t);
+diff --git a/src/apprt/embedded.zig b/src/apprt/embedded.zig
+index 0d5a4f8da..1def0339a 100644
+--- a/src/apprt/embedded.zig
++++ b/src/apprt/embedded.zig
+@@ -1577,6 +1577,14 @@ pub const CAPI = struct {
+         return surface.newSurfaceOptions(source);
+     }
+ 
++    /// The surface's manually-zoomed font size in points, or 0 when it is at the
++    /// configured default (never zoomed, or reset). Mirrors the "0 means default"
++    /// config convention and allocates nothing, unlike inherited config.
++    export fn ghostty_surface_font_size(surface: *Surface) f32 {
++        if (!surface.core_surface.font_size_adjusted) return 0;
++        return surface.core_surface.font_size.points;
++    }
++
+     /// Update the configuration to the provided config for only this surface.
+     export fn ghostty_surface_update_config(
+         surface: *Surface,
diff --git a/scripts/build-ghostty.sh b/scripts/build-ghostty.sh
index d667ad476..ece7f9447 100755
--- a/scripts/build-ghostty.sh
+++ b/scripts/build-ghostty.sh
@@ -5,6 +5,12 @@ script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 script_path="${script_dir}/$(basename "${BASH_SOURCE[0]}")"
 srcroot="${SRCROOT:-$(cd "${script_dir}/.." && pwd)}"
 repo_root="${srcroot}"
+
+# Pin a Zig-linkable Xcode for `zig build`'s SDK lookups (see select-developer-dir.sh).
+# Always delegate so an inherited DEVELOPER_DIR is validated, not trusted blindly.
+# Plain assignment, separate export, so a selector failure aborts under set -e.
+DEVELOPER_DIR="$("${script_dir}/select-developer-dir.sh")"
+export DEVELOPER_DIR
 ghostty_dir="${srcroot}/ThirdParty/ghostty"
 ghostty_submodule_path="${ghostty_dir#"${repo_root}/"}"
 ghostty_build_root="${srcroot}/.build/ghostty"
@@ -16,6 +22,9 @@ ghostty_legacy_share_path="${ghostty_legacy_prefix_path}/share"
 xcframework_path="${ghostty_build_root}/GhosttyKit.xcframework"
 ghostty_resources_path="${ghostty_build_root}/share/ghostty"
 ghostty_terminfo_path="${ghostty_build_root}/share/terminfo"
+# Out-of-tree patches applied to the pinned ghostty submodule at build time.
+# The submodule pointer stays on upstream; we never fork or commit into it.
+ghostty_patches_dir="${srcroot}/patches"
 
 print_fingerprint() {
   (
@@ -56,8 +65,91 @@ ensure_ghostty_checkout() {
   fi
 }
 
+# Apply our out-of-tree patches to the submodule working tree. Idempotent: a
+# patch that already applies in reverse is treated as present. Fails loudly if
+# a patch no longer applies (e.g. after an upstream bump) so it's never silently
+# skipped. The submodule's committed SHA is untouched; `revert_ghostty_patches`
+# restores a pristine working tree on exit.
+# Repo-relative paths a patch touches. Parses the patch itself, not the tree, so
+# it works even when the working tree is dirty.
+ghostty_patch_files() {
+  git -C "${ghostty_dir}" apply --numstat "$1" 2>/dev/null | awk '{ print $3 }'
+}
+
+# Reset just the files a patch touches back to the pinned SHA. Reads the file
+# list line by line (bash 3.2 compatible) so a path with spaces stays intact.
+reset_ghostty_patch_files() {
+  local f
+  local files=()
+  while IFS= read -r f; do
+    [ -n "${f}" ] && files+=("${f}")
+  done < <(ghostty_patch_files "$1")
+  [ "${#files[@]}" -eq 0 ] || git -C "${ghostty_dir}" checkout -- "${files[@]}" 2>/dev/null || true
+}
+
+apply_ghostty_patches() {
+  [ -d "${ghostty_patches_dir}" ] || return 0
+  local patch
+  for patch in "${ghostty_patches_dir}"/*.patch; do
+    [ -e "${patch}" ] || continue
+    if git -C "${ghostty_dir}" apply --reverse --check "${patch}" 2>/dev/null; then
+      continue # already fully applied
+    fi
+    if ! git -C "${ghostty_dir}" apply --check "${patch}" 2>/dev/null; then
+      # Neither pristine nor cleanly applied: most likely a prior build was killed
+      # (SIGKILL / power loss) mid-apply and left the patched files dirty. Reset
+      # just those files to the pinned SHA and retry before blaming an upstream bump.
+      reset_ghostty_patch_files "${patch}"
+      if ! git -C "${ghostty_dir}" apply --check "${patch}" 2>/dev/null; then
+        echo "error: ${patch} does not apply cleanly to ${ghostty_submodule_path}." >&2
+        echo "       The submodule may have been bumped (refresh the patch), or a" >&2
+        echo "       previous build left it dirty: git -C ${ghostty_submodule_path} checkout . && retry." >&2
+        exit 1
+      fi
+    fi
+    git -C "${ghostty_dir}" apply "${patch}"
+  done
+}
+
+revert_ghostty_patches() {
+  [ -d "${ghostty_patches_dir}" ] || return 0
+  local patch
+  for patch in "${ghostty_patches_dir}"/*.patch; do
+    [ -e "${patch}" ] || continue
+    # Prefer a clean reverse-apply; fall back to resetting just the patched files.
+    # The fallback also guards against `set -e` aborting the trap mid-revert if the
+    # reverse-apply fails (e.g. a partially-applied tree).
+    if git -C "${ghostty_dir}" apply --reverse --check "${patch}" 2>/dev/null; then
+      git -C "${ghostty_dir}" apply --reverse "${patch}" 2>/dev/null || reset_ghostty_patch_files "${patch}"
+    else
+      reset_ghostty_patch_files "${patch}"
+    fi
+  done
+}
+
 ensure_ghostty_checkout
 
+# Patch the pinned submodule in place for this build only, restoring it on exit
+# so `git status` stays clean and the pin is never disturbed. Applied before the
+# fingerprint so patched source is reflected in the rebuild trigger.
+#
+# Revert on signals too (not just EXIT): a cancelled Xcode build or Ctrl-C sends
+# SIGINT/SIGTERM, which would otherwise skip the EXIT trap and leave the tree
+# patched (dirty status + poisoned fingerprint). On signal we revert, clear the
+# traps to avoid a double revert, and exit with the conventional 128+signal code.
+revert_and_signal_exit() {
+  revert_ghostty_patches
+  trap - EXIT INT TERM
+  case "$1" in
+    TERM) exit 143 ;;
+    *) exit 130 ;;
+  esac
+}
+trap revert_ghostty_patches EXIT
+trap 'revert_and_signal_exit INT' INT
+trap 'revert_and_signal_exit TERM' TERM
+apply_ghostty_patches
+
 if [ "${1:-}" = "--print-fingerprint" ]; then
   print_fingerprint
   exit 0
diff --git a/scripts/build-zmx.sh b/scripts/build-zmx.sh
index 98fe52bb4..64b437d4d 100755
--- a/scripts/build-zmx.sh
+++ b/scripts/build-zmx.sh
@@ -4,6 +4,12 @@ set -euo pipefail
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 script_path="${script_dir}/$(basename "${BASH_SOURCE[0]}")"
 srcroot="${SRCROOT:-$(cd "${script_dir}/.." && pwd)}"
+
+# Pin a Zig-linkable Xcode for `zig build`'s SDK lookups (see select-developer-dir.sh).
+# Always delegate so an inherited DEVELOPER_DIR is validated, not trusted blindly.
+# Plain assignment, separate export, so a selector failure aborts under set -e.
+DEVELOPER_DIR="$("${script_dir}/select-developer-dir.sh")"
+export DEVELOPER_DIR
 repo_root="${srcroot}"
 zmx_dir="${srcroot}/ThirdParty/zmx"
 zmx_submodule_path="${zmx_dir#"${repo_root}/"}"
diff --git a/scripts/bump-version.sh b/scripts/bump-version.sh
new file mode 100755
index 000000000..b7a211039
--- /dev/null
+++ b/scripts/bump-version.sh
@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# Bumps the version and signs the release-triggering tag. A version is required;
+# minor/major bumps require a `## title\n\nbody` headline that rides the tag and
+# CI prepends to the auto-generated notes.
+#
+# Usage: VERSION=x.y.z [BUILD=n] [TITLE=… [BODY=…]] scripts/bump-version.sh
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "${script_dir}/.." && pwd)"
+config_path="${repo_root}/Configurations/Project.xcconfig"
+
+VERSION="${VERSION:-}"
+BUILD="${BUILD:-}"
+TITLE="${TITLE:-}"
+BODY="${BODY:-}"
+
+current="$(/usr/bin/awk -F' = ' '/^MARKETING_VERSION = [0-9.]+$/{print $2; exit}' "$config_path")"
+[ -n "$current" ] || { echo "error: MARKETING_VERSION not found in $config_path" >&2; exit 1; }
+cur_major="${current%%.*}"
+cur_rest="${current#*.}"
+cur_minor="${cur_rest%%.*}"
+cur_patch="${cur_rest#*.}"
+
+# Require a version; suggest the next ones and bail before mutating.
+if [ -z "$VERSION" ]; then
+  {
+    echo "error: a version is required."
+    echo
+    echo "current: $current"
+    echo "  patch  ->  make bump-and-release VERSION=${cur_major}.${cur_minor}.$((cur_patch + 1))"
+    echo "  minor  ->  make bump-and-release VERSION=${cur_major}.$((cur_minor + 1)).0"
+    echo "  major  ->  make bump-and-release VERSION=$((cur_major + 1)).0.0"
+    echo
+    echo "re-run with one of the above."
+  } >&2
+  exit 1
+fi
+
+if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+  echo "error: VERSION must be in x.y.z format" >&2
+  exit 1
+fi
+
+# Reject a downgrade or no-op: CI cuts the release from the tag at HEAD.
+if [ "$(printf '%s\n%s\n' "$current" "$VERSION" | sort -V | tail -1)" = "$current" ]; then
+  echo "error: VERSION ($VERSION) must be greater than the current version ($current)" >&2
+  exit 1
+fi
+
+# Require the config clean: the commit takes the whole file, so unrelated edits would ride into the release.
+if ! git -C "$repo_root" diff --quiet -- "$config_path" || ! git -C "$repo_root" diff --cached --quiet -- "$config_path"; then
+  echo "error: $config_path has uncommitted changes; commit or stash them first." >&2
+  exit 1
+fi
+
+new_major="${VERSION%%.*}"
+new_rest="${VERSION#*.}"
+new_minor="${new_rest%%.*}"
+
+# Same major.minor is a patch; anything else is a feature release needing a headline.
+is_bugfix=0
+[ "$new_major" = "$cur_major" ] && [ "$new_minor" = "$cur_minor" ] && is_bugfix=1
+if [ "$new_major" != "$cur_major" ]; then kind=major; else kind=minor; fi
+
+tag_msg_file="$(mktemp)"
+trap 'rm -f "$tag_msg_file"' EXIT
+
+# Capture the headline before mutating, so an invalid one aborts with the tree clean.
+has_headline=0
+if [ -n "$TITLE" ] && [ -n "$BODY" ]; then
+  printf '## %s\n\n%s\n' "$TITLE" "$BODY" > "$tag_msg_file"
+  has_headline=1
+elif [ "$is_bugfix" -eq 0 ] || [ -n "$TITLE" ]; then
+  # Author in $EDITOR when interactive; a headline we can't complete is an error, not a silent drop.
+  if [ -t 0 ] && [ -t 1 ]; then
+    printf '## %s\n\n' "$TITLE" > "$tag_msg_file"
+    "${EDITOR:-vi}" "$tag_msg_file"
+    has_headline=1
+  elif [ "$is_bugfix" -eq 0 ]; then
+    echo "error: $VERSION is a $kind release and requires a headline." >&2
+    echo "       pass TITLE=… BODY=…, or run interactively to author it in \$EDITOR." >&2
+    exit 1
+  else
+    echo "error: TITLE was set without BODY and there is no TTY to author the rest." >&2
+    echo "       pass BODY=… too, or run interactively to author it in \$EDITOR." >&2
+    exit 1
+  fi
+fi
+
+# Enforce git's subject/body split: '## title', blank line, body. Without the blank
+# line git folds the body into the subject and CI drops it.
+if [ "$has_headline" -eq 1 ]; then
+  title_line="$(/usr/bin/awk 'NR==1{print; exit}' "$tag_msg_file")"
+  second_line="$(/usr/bin/awk 'NR==2{print; exit}' "$tag_msg_file")"
+  title="${title_line#\#\# }"
+  title_text="$(printf '%s' "$title" | tr -d '[:space:]')"
+  second_text="$(printf '%s' "$second_line" | tr -d '[:space:]')"
+  body_text="$(/usr/bin/awk 'NR>2 && NF' "$tag_msg_file" | tr -d '[:space:]')"
+  if [ "$title" = "$title_line" ] || [ -z "$title_text" ] || [ -n "$second_text" ] || [ -z "$body_text" ]; then
+    if [ "$is_bugfix" -eq 0 ]; then
+      echo "error: a $kind release requires a headline: '## title', a blank line, then a non-empty body." >&2
+      exit 1
+    fi
+    has_headline=0
+  fi
+fi
+
+# Resolve the build number (auto-increment when unset).
+if [ -z "$BUILD" ]; then
+  build="$(/usr/bin/awk -F' = ' '/^CURRENT_PROJECT_VERSION = [0-9]+$/{print $2; exit}' "$config_path")"
+  [ -n "$build" ] || { echo "error: CURRENT_PROJECT_VERSION not found" >&2; exit 1; }
+  build="$((build + 1))"
+elif ! echo "$BUILD" | grep -qE '^[0-9]+$'; then
+  echo "error: BUILD must be an integer" >&2
+  exit 1
+else
+  build="$BUILD"
+fi
+
+sed -i '' "s/^MARKETING_VERSION = [0-9.]*/MARKETING_VERSION = $VERSION/g" "$config_path"
+sed -i '' "s/^CURRENT_PROJECT_VERSION = [0-9]*/CURRENT_PROJECT_VERSION = $build/g" "$config_path"
+
+# sed exits 0 on no match; assert the rewrite landed.
+grep -qx "MARKETING_VERSION = $VERSION" "$config_path" || { echo "error: failed to write MARKETING_VERSION" >&2; exit 1; }
+grep -qx "CURRENT_PROJECT_VERSION = $build" "$config_path" || { echo "error: failed to write CURRENT_PROJECT_VERSION" >&2; exit 1; }
+
+# Commit only the config so unrelated staged changes stay out of the release.
+git -C "$repo_root" commit -S -m "bump v$VERSION" -o -- "$config_path"
+# verbatim cleanup keeps the `## ` heading; default cleanup would strip it as a comment.
+if [ "$has_headline" -eq 1 ]; then
+  # Trailing newline keeps the appended signature on its own line, else it folds into the subject and leaks into the notes.
+  [ -n "$(tail -c1 "$tag_msg_file")" ] && printf '\n' >> "$tag_msg_file"
+  git -C "$repo_root" tag -s --cleanup=verbatim -F "$tag_msg_file" "v$VERSION"
+else
+  git -C "$repo_root" tag -s -m "v$VERSION" "v$VERSION"
+fi
+echo "version bumped to $VERSION (build $build), tagged v$VERSION"
+if [ "$has_headline" -eq 1 ]; then
+  echo "release headline attached to tag v$VERSION"
+fi
diff --git a/scripts/doctor.sh b/scripts/doctor.sh
new file mode 100755
index 000000000..7a7083e2f
--- /dev/null
+++ b/scripts/doctor.sh
@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Verifies the build prerequisites on macOS 26.4+ and prints the fix for each
+# failure, instead of a 200-line Zig linker dump.
+#
+# Usage: scripts/doctor.sh [--quiet]   (--quiet prints only failures). Exit 1 on any.
+set -uo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "${script_dir}/.." && pwd)"
+
+quiet=0
+[ "${1:-}" = "--quiet" ] && quiet=1
+
+failures=0
+
+# Fall back to the absolute path; mise is often missing from non-login shells.
+mise_bin="mise"
+command -v mise >/dev/null 2>&1 || mise_bin="${HOME}/.local/bin/mise"
+has_mise() { command -v "${mise_bin}" >/dev/null 2>&1 || [ -x "${mise_bin}" ]; }
+
+pass() { [ "${quiet}" -eq 1 ] || printf '  \033[32m✓\033[0m %s\n' "$1"; }
+fail() {
+  failures=$((failures + 1))
+  printf '  \033[31m✗\033[0m %s\n' "$1" >&2
+  printf '      fix: %s\n' "$2" >&2
+}
+
+[ "${quiet}" -eq 1 ] || printf '\033[1msupacode doctor\033[0m\n'
+
+# 1. mise on PATH
+if command -v mise >/dev/null 2>&1; then
+  pass "mise on PATH"
+elif [ -x "${HOME}/.local/bin/mise" ]; then
+  fail "mise installed but not on PATH (~/.local/bin/mise)" \
+    "echo 'eval \"\$(~/.local/bin/mise activate zsh)\"' >> ~/.zshrc && exec zsh"
+else
+  fail "mise not installed" "curl https://mise.run | sh"
+fi
+
+# 2. submodules
+missing_sub=()
+[ -f "${repo_root}/ThirdParty/ghostty/build.zig" ] || missing_sub+=("ThirdParty/ghostty")
+[ -f "${repo_root}/ThirdParty/zmx/build.zig" ] || missing_sub+=("ThirdParty/zmx")
+[ -f "${repo_root}/Resources/git-wt/wt" ] || missing_sub+=("Resources/git-wt")
+if [ "${#missing_sub[@]}" -eq 0 ]; then
+  pass "git submodules initialized"
+else
+  fail "git submodules missing: ${missing_sub[*]}" "git submodule update --init --recursive"
+fi
+
+# 3. Zig-linkable Xcode
+developer_dir="$("${script_dir}/select-developer-dir.sh" 2>/dev/null)" || developer_dir=""
+if [ -n "${developer_dir}" ]; then
+  sdk="$(DEVELOPER_DIR="${developer_dir}" xcrun --sdk macosx --show-sdk-path 2>/dev/null)"
+  pass "Zig-linkable Xcode: ${developer_dir} ($(basename "${sdk:-unknown}"))"
+else
+  fail "no Zig-linkable Xcode: macOS 26.4+ SDK dropped arm64-macos (ziglang/zig#31658)" \
+    "install Xcode 26.3 (ships the macOS 26.2 SDK): https://developer.apple.com/download/all/?q=Xcode%2026.3"
+fi
+
+# 4 and 5 need an Xcode to point at.
+if [ -n "${developer_dir}" ]; then
+  # 4. license / first launch
+  if DEVELOPER_DIR="${developer_dir}" xcodebuild -checkFirstLaunchStatus >/dev/null 2>&1; then
+    pass "Xcode license accepted & first launch complete"
+  else
+    fail "Xcode needs license / first launch (DEVELOPER_DIR alone won't work until done)" \
+      "sudo DEVELOPER_DIR=${developer_dir} xcodebuild -license accept && sudo DEVELOPER_DIR=${developer_dir} xcodebuild -runFirstLaunch"
+  fi
+
+  # 5. Metal Toolchain
+  if DEVELOPER_DIR="${developer_dir}" xcrun metal --version >/dev/null 2>&1; then
+    pass "Metal Toolchain installed"
+  else
+    fail "Metal Toolchain missing (ghostty compiles Metal shaders)" \
+      "sudo DEVELOPER_DIR=${developer_dir} xcodebuild -downloadComponent MetalToolchain"
+  fi
+fi
+
+# 6. pinned mise tools
+if has_mise; then
+  missing_tools=()
+  for tool in zig tuist swiftlint xcbeautify swift-format; do
+    "${mise_bin}" which "${tool}" >/dev/null 2>&1 || missing_tools+=("${tool}")
+  done
+  if [ "${#missing_tools[@]}" -eq 0 ]; then
+    pass "mise tools installed (zig, tuist, swiftlint, xcbeautify, swift-format)"
+  else
+    fail "mise tools missing: ${missing_tools[*]}" "mise install"
+  fi
+fi
+
+if [ "${failures}" -gt 0 ]; then
+  printf '\n\033[31m%d check(s) failed.\033[0m Fix the above, then re-run `make doctor`.\n' "${failures}" >&2
+  exit 1
+fi
+[ "${quiet}" -eq 1 ] || printf '\n\033[32mAll checks passed.\033[0m\n'
+exit 0
diff --git a/scripts/generate_release_checksums.py b/scripts/generate_release_checksums.py
new file mode 100644
index 000000000..1eaddb6d0
--- /dev/null
+++ b/scripts/generate_release_checksums.py
@@ -0,0 +1,37 @@
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+
+def sha256(path):
+    digest = hashlib.sha256()
+    with path.open("rb") as file:
+        for chunk in iter(lambda: file.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def main():
+    if len(sys.argv) < 4:
+        raise SystemExit("usage: generate_release_checksums.py TAG OUTPUT ASSET...")
+
+    tag = sys.argv[1]
+    output = Path(sys.argv[2])
+    assets = {}
+    asset_paths = sorted({Path(path) for path in sys.argv[3:]}, key=lambda path: path.name)
+
+    for asset in asset_paths:
+        if not asset.is_file():
+            continue
+        assets[asset.name] = {
+            "sha256": sha256(asset),
+            "size": asset.stat().st_size,
+        }
+
+    manifest = {"assets": assets, "tag": tag}
+    output.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/select-developer-dir.sh b/scripts/select-developer-dir.sh
new file mode 100755
index 000000000..a3f6b4107
--- /dev/null
+++ b/scripts/select-developer-dir.sh
@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Prints the Developer dir of an Xcode whose macOS SDK the pinned Zig (0.15.2) can
+# link. Shared by the build scripts, the Makefile, and `make doctor`. Exit 1 with
+# an actionable message when none is installed.
+set -euo pipefail
+
+# Linkable when the dir is a full Xcode whose macOS SDK predates the zig-breaking
+# change. macOS 26.4+ SDKs can't link with Zig 0.15.2 (ziglang/zig#31658, fixed in
+# 0.16+) even though their libSystem.tbd may still list arm64-macos, so gate on the
+# SDK version, not that string (which is present on broken SDKs too).
+is_zig_linkable() {
+  local dir="$1" ver
+  [ -d "$dir" ] || return 1
+  # Require a full Xcode, not CommandLineTools (no xcodebuild).
+  [ -x "${dir}/usr/bin/xcodebuild" ] || return 1
+  ver="$(DEVELOPER_DIR="$dir" xcrun --sdk macosx --show-sdk-version 2>/dev/null)" || return 1
+  [ -n "$ver" ] || return 1
+  # Reject SDKs newer than 26.3 (the 26.4+ break); sort -V keeps 26.10 above 26.3.
+  [ "$(printf '%s\n26.3\n' "$ver" | sort -V | tail -1)" = "26.3" ]
+}
+
+# Honor an explicit DEVELOPER_DIR when it is itself linkable.
+if [ -n "${DEVELOPER_DIR:-}" ] && is_zig_linkable "${DEVELOPER_DIR}"; then
+  printf '%s\n' "${DEVELOPER_DIR}"
+  exit 0
+fi
+
+candidates=()
+# Known-good versioned Xcodes first (newest <= 26.3, underscore and hyphen
+# naming), so a machine whose default is a newer non-linkable Xcode (CI on 26.5)
+# still finds a linkable one instead of stopping at the default.
+for app in \
+  /Applications/Xcode_26.3*.app /Applications/Xcode-26.3*.app \
+  /Applications/Xcode_26.2*.app /Applications/Xcode-26.2*.app \
+  /Applications/Xcode_26.1*.app /Applications/Xcode-26.1*.app \
+  /Applications/Xcode_26.0*.app /Applications/Xcode-26.0*.app; do
+  [ -d "${app}" ] && candidates+=("${app}/Contents/Developer")
+done
+# Then the currently-selected and unversioned default, covering a linkable Xcode
+# at a non-standard path.
+if current="$(xcode-select -p 2>/dev/null)" && [ -n "${current}" ]; then
+  candidates+=("${current}")
+fi
+[ -d /Applications/Xcode.app ] && candidates+=("/Applications/Xcode.app/Contents/Developer")
+
+# Guard the empty case: bash 3.2 errors on `"${arr[@]}"` under `set -u`.
+for dir in ${candidates[@]+"${candidates[@]}"}; do
+  if is_zig_linkable "${dir}"; then
+    printf '%s\n' "${dir}"
+    exit 0
+  fi
+done
+
+cat >&2 <<'EOF'
+error: no Zig-linkable Xcode found.
+
+  The pinned Zig (0.15.2, required exactly by ghostty) cannot link the macOS
+  26.4+ SDK: it dropped the arm64-macos slice from libSystem.tbd (ziglang/zig
+  #31658, fixed only in Zig 0.16+). Install Xcode 26.3, which ships the macOS
+  26.2 SDK whose .tbd still has arm64-macos:
+
+    https://developer.apple.com/download/all/?q=Xcode%2026.3
+
+  Then accept its license and finish first launch (DEVELOPER_DIR alone is not
+  enough until this completes):
+
+    sudo DEVELOPER_DIR=/Applications/Xcode_26.3.app/Contents/Developer xcodebuild -license accept
+    sudo DEVELOPER_DIR=/Applications/Xcode_26.3.app/Contents/Developer xcodebuild -runFirstLaunch
+
+  No global `xcode-select -s` is needed. The build picks it up automatically.
+EOF
+exit 1
diff --git a/scripts/smoke-zmx-crash-recovery.sh b/scripts/smoke-zmx-crash-recovery.sh
new file mode 100755
index 000000000..788ba6b24
--- /dev/null
+++ b/scripts/smoke-zmx-crash-recovery.sh
@@ -0,0 +1,307 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="${SRCROOT:-$(cd "${script_dir}/.." && pwd)}"
+
+app_path="${SUPACODE_APP_PATH:-${repo_root}/build/supacode/Build/Products/Debug/supacode.app}"
+cli_path="${SUPACODE_CLI:-${app_path}/Contents/Resources/bin/supacode}"
+zmx_path="${ZMX:-${app_path}/Contents/Resources/zmx/zmx}"
+target_repo="${repo_root}"
+worktree_id=""
+created_tab_id=""
+surface_id=""
+session_id=""
+timeout_seconds="${SUPACODE_SMOKE_TIMEOUT:-12}"
+settle_seconds="${SUPACODE_SMOKE_SETTLE_SECONDS:-2}"
+keep_tab=false
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/smoke-zmx-crash-recovery.sh [--repo PATH] [--worktree ID] [--timeout SECONDS] [--settle SECONDS] [--keep-tab]
+
+Creates a zmx-backed Supacode tab, forcibly detaches the zmx client process,
+and verifies the same tab/surface/session survives. This exercises the regression
+where an unexpected zmx client exit used to close the Supacode tab and kill the session.
+
+Options:
+  --repo PATH       Repo path to open before selecting the focused worktree. Defaults to this repo.
+  --worktree ID     Existing worktree ID to target. Skips $SUPACODE_WORKTREE_ID and `supacode repo open`.
+  --timeout SECONDS Polling timeout for each async app observation. Defaults to 12.
+  --settle SECONDS  Require the recovered tab to stay alive for this long before PASS. Defaults to 2.
+  --keep-tab        Leave the created tab open after the smoke test.
+
+Environment overrides:
+  SUPACODE_WORKTREE_ID Existing worktree ID to target when --worktree is omitted.
+  SUPACODE_APP_PATH Path to the .app under test.
+  SUPACODE_CLI      Path to the supacode CLI under test.
+  SUPACODE_SMOKE_SETTLE_SECONDS Stable-survival duration after detach. Defaults to 2.
+  ZMX               Path to the zmx binary used for `zmx ls`.
+EOF
+}
+
+fail() {
+  echo "error: $*" >&2
+  exit 1
+}
+
+note() {
+  printf '==> %s\n' "$*"
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --repo)
+      [ "$#" -ge 2 ] || fail "--repo requires a path"
+      target_repo="$2"
+      shift 2
+      ;;
+    --worktree)
+      [ "$#" -ge 2 ] || fail "--worktree requires an ID"
+      worktree_id="$2"
+      shift 2
+      ;;
+    --timeout)
+      [ "$#" -ge 2 ] || fail "--timeout requires a number of seconds"
+      timeout_seconds="$2"
+      shift 2
+      ;;
+    --settle)
+      [ "$#" -ge 2 ] || fail "--settle requires a number of seconds"
+      settle_seconds="$2"
+      shift 2
+      ;;
+    --keep-tab)
+      keep_tab=true
+      shift
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    *)
+      target_repo="$1"
+      shift
+      ;;
+  esac
+done
+
+case "${timeout_seconds}" in
+  '' | *[!0-9]*)
+    fail "--timeout must be a positive integer"
+    ;;
+esac
+
+[ "${timeout_seconds}" -gt 0 ] || fail "--timeout must be greater than zero"
+case "${settle_seconds}" in
+  '' | *[!0-9]*)
+    fail "--settle must be a non-negative integer"
+    ;;
+esac
+
+[ -x "${cli_path}" ] || fail "missing executable CLI at ${cli_path}. Run: make build-app"
+[ -x "${zmx_path}" ] || fail "missing executable zmx at ${zmx_path}. Run: make build-app"
+
+target_repo="$(cd "${target_repo}" && pwd)"
+
+normalize_list_lines() {
+  awk '
+    {
+      escape = sprintf("%c", 27)
+      gsub(escape "\\[[0-9;]*[[:alpha:]]", "")
+      sub(/^[*] /, "")
+      if (NF) {
+        print
+      }
+    }
+  '
+}
+
+first_list_id() {
+  normalize_list_lines | awk 'NF { print; exit }'
+}
+
+list_ids() {
+  normalize_list_lines
+}
+
+cleanup() {
+  status=$?
+  if [ "${keep_tab}" = false ] && [ -n "${created_tab_id}" ] && [ -n "${worktree_id}" ]; then
+    if [ "${status}" -eq 0 ]; then
+      note "Closing smoke-test tab ${created_tab_id}; pass --keep-tab to inspect it manually."
+    fi
+    "${cli_path}" tab close --worktree "${worktree_id}" --tab "${created_tab_id}" >/dev/null 2>&1 || true
+  fi
+  exit "${status}"
+}
+trap cleanup EXIT
+
+wait_for() {
+  description="$1"
+  shift
+
+  deadline=$(($(date +%s) + timeout_seconds))
+  while true; do
+    if "$@"; then
+      return 0
+    fi
+    if [ "$(date +%s)" -ge "${deadline}" ]; then
+      fail "timed out waiting for ${description}"
+    fi
+    sleep 0.2
+  done
+}
+
+run_dispatch_allow_timeout() {
+  local description output status
+  description="$1"
+  shift
+
+  set +e
+  output="$("$@" 2>&1)"
+  status=$?
+  set -e
+
+  if [ "${status}" -eq 0 ]; then
+    return 0
+  fi
+
+  if printf '%s\n' "${output}" | grep -F -q "Timed out waiting for response from Supacode."; then
+    note "${description} did not answer within the CLI socket timeout; continuing to poll app state."
+    return 0
+  fi
+
+  printf '%s\n' "${output}" >&2
+  return "${status}"
+}
+
+capture_socket_count() {
+  socket_output="$("${cli_path}" socket 2>/dev/null)" || return 1
+  socket_count="$(printf '%s\n' "${socket_output}" | awk 'NF { count++ } END { print count + 0 }')"
+  [ "${socket_count}" -gt 0 ]
+}
+
+capture_env_worktree() {
+  [ -n "${SUPACODE_WORKTREE_ID:-}" ] || return 1
+  worktree_id="${SUPACODE_WORKTREE_ID}"
+  "${cli_path}" tab list --worktree "${worktree_id}" >/dev/null 2>&1
+}
+
+capture_focused_worktree() {
+  output="$("${cli_path}" worktree list --focused 2>/dev/null)" || return 1
+  worktree_id="$(printf '%s\n' "${output}" | first_list_id)"
+  [ -n "${worktree_id}" ]
+  "${cli_path}" tab list --worktree "${worktree_id}" >/dev/null 2>&1
+}
+
+tab_exists() {
+  output="$("${cli_path}" tab list --worktree "${worktree_id}" 2>/dev/null)" || return 1
+  printf '%s\n' "${output}" | list_ids | grep -F -q "${created_tab_id}"
+}
+
+session_exists() {
+  "${zmx_path}" ls 2>/dev/null | grep -F -q "${session_id}"
+}
+
+capture_session_clients() {
+  session_clients="$(
+    "${zmx_path}" ls 2>/dev/null | awk -v session="${session_id}" '
+      index($0, "name=" session) {
+        for (i = 1; i <= NF; i++) {
+          if ($i ~ /^clients=/) {
+            sub(/^clients=/, "", $i)
+            print $i
+            exit
+          }
+        }
+      }
+    '
+  )"
+  case "${session_clients}" in
+    '' | *[!0-9]*)
+      return 1
+      ;;
+  esac
+  [ "${session_clients}" -gt 0 ]
+}
+
+surface_still_exists() {
+  output="$("${cli_path}" surface list --worktree "${worktree_id}" --tab "${created_tab_id}" 2>/dev/null)" || return 1
+  printf '%s\n' "${output}" | first_list_id | grep -F -q "${surface_id}"
+}
+
+recovered_state_exists() {
+  tab_exists
+  surface_still_exists
+  session_exists
+  capture_session_clients
+}
+
+recovered_state_stays_alive() {
+  deadline=$(($(date +%s) + settle_seconds))
+  while [ "$(date +%s)" -lt "${deadline}" ]; do
+    recovered_state_exists || return 1
+    sleep 0.2
+  done
+}
+
+detach_session_clients() {
+  ZMX_SESSION="${session_id}" "${zmx_path}" detach >/dev/null
+}
+
+note "Using app: ${app_path}"
+note "Using CLI: ${cli_path}"
+note "Using zmx: ${zmx_path}"
+
+if ! capture_socket_count; then
+  note "No Supacode socket found; launching debug app by path."
+  /usr/bin/open "${app_path}"
+  wait_for "Supacode socket" capture_socket_count
+fi
+
+if [ "${socket_count}" -gt 1 ] && [ -z "${SUPACODE_SOCKET_PATH:-}" ]; then
+  fail "multiple Supacode sockets found. Run from the target Supacode terminal or set SUPACODE_SOCKET_PATH."
+fi
+
+if [ -z "${worktree_id}" ]; then
+  if capture_env_worktree; then
+    note "Using SUPACODE_WORKTREE_ID: ${worktree_id}"
+  else
+    note "Opening repo: ${target_repo}"
+    run_dispatch_allow_timeout "repo open" "${cli_path}" repo open "${target_repo}"
+    wait_for "focused worktree after repo open" capture_focused_worktree
+  fi
+else
+  note "Using supplied worktree: ${worktree_id}"
+fi
+
+created_tab_id="$(uuidgen)"
+note "Creating tab ${created_tab_id} in worktree ${worktree_id}"
+run_dispatch_allow_timeout "tab new" "${cli_path}" tab new --worktree "${worktree_id}" --id "${created_tab_id}"
+wait_for "created tab ${created_tab_id}" tab_exists
+
+surface_id="${created_tab_id}"
+session_id="supa-$(printf '%s' "${surface_id}" | tr '[:upper:]' '[:lower:]')"
+note "Surface: ${surface_id}"
+note "Expected zmx session: ${session_id}"
+wait_for "zmx session ${session_id}" session_exists
+wait_for "zmx attached client for ${session_id}" capture_session_clients
+
+note "Detaching zmx client for ${session_id}"
+# This intentionally detaches only the client. Do not replace with `zmx kill`,
+# which removes the backing session and should still close the surface.
+detach_session_clients
+
+wait_for "surface ${surface_id} to survive forced zmx attach exit" surface_still_exists
+wait_for "zmx session ${session_id} to remain alive" session_exists
+wait_for "reattached zmx client for ${session_id}" capture_session_clients
+if [ "${settle_seconds}" -gt 0 ]; then
+  note "Verifying recovered tab stays alive for ${settle_seconds}s"
+  wait_for "recovered tab to stay alive for ${settle_seconds}s" recovered_state_stays_alive
+fi
+
+note "PASS: surface ${surface_id} and session ${session_id} survived the forced zmx client detach."
+if [ "${keep_tab}" = true ]; then
+  note "Left tab ${created_tab_id} open because --keep-tab was supplied."
+fi
diff --git a/supacode/App/CommandKeyObserver.swift b/supacode/App/CommandKeyObserver.swift
index d91518e22..074a35a23 100644
--- a/supacode/App/CommandKeyObserver.swift
+++ b/supacode/App/CommandKeyObserver.swift
@@ -1,23 +1,20 @@
 import AppKit
 import SwiftUI
 
+/// Tracks whether the user is currently holding ⌘ or ⌃ so the UI can surface shortcut hints.
 @MainActor
 @Observable
 final class CommandKeyObserver {
-  private static let holdDelay: Duration = .milliseconds(300)
-
   var isPressed: Bool
   private var monitor: Any?
   private var didBecomeActiveObserver: NSObjectProtocol?
   private var didResignActiveObserver: NSObjectProtocol?
-  private var holdTask: Task<Void, Never>?
 
   init() {
     isPressed = false
     monitor = nil
     didBecomeActiveObserver = nil
     didResignActiveObserver = nil
-    holdTask = nil
     configureObservers()
   }
 
@@ -54,17 +51,7 @@ final class CommandKeyObserver {
   }
 
   private func handleCommandKeyChange(isDown: Bool) {
-    holdTask?.cancel()
-    holdTask = nil
-
-    if isDown {
-      holdTask = Task {
-        try? await ContinuousClock().sleep(for: Self.holdDelay)
-        guard !Task.isCancelled else { return }
-        isPressed = true
-      }
-    } else {
-      isPressed = false
-    }
+    // Flip immediately; consumers fade the visual change in/out themselves.
+    isPressed = isDown
   }
 }
diff --git a/supacode/App/ContentView.swift b/supacode/App/ContentView.swift
index 038d0c793..c6c92b3d2 100644
--- a/supacode/App/ContentView.swift
+++ b/supacode/App/ContentView.swift
@@ -85,6 +85,14 @@ struct ContentView: View {
     ) { customizationStore in
       RepositoryCustomizationView(store: customizationStore)
     }
+    .sheet(
+      item: $repositoriesStore.scope(
+        state: \.worktreeCustomization,
+        action: \.worktreeCustomization
+      )
+    ) { customizationStore in
+      WorktreeCustomizationView(store: customizationStore)
+    }
     .sheet(
       item: $repositoriesStore.scope(
         state: \.renameBranchPrompt,
@@ -145,7 +153,8 @@ private struct CommandPaletteOverlayHost: View {
     #endif
     return CommandPaletteOverlayView(
       store: store.scope(state: \.commandPalette, action: \.commandPalette),
-      items: CommandPaletteFeature.commandPaletteItems(
+      items: CommandPaletteFeature.items(
+        in: store.commandPalette.mode,
         from: repositoriesStore.state,
         ghosttyCommands: ghosttyShortcuts.commandPaletteEntries,
         scripts: store.allScripts,
diff --git a/supacode/App/SidebarBottomCardView.swift b/supacode/App/SidebarBottomCardView.swift
index e6edd5ca3..5e002d055 100644
--- a/supacode/App/SidebarBottomCardView.swift
+++ b/supacode/App/SidebarBottomCardView.swift
@@ -5,10 +5,11 @@ import SwiftUI
 /// Mutually-exclusive host for the pinned sidebar bottom card. Priority order:
 /// 1. Coding-agent updates available / initial install prompt
 ///    (`CodingAgentsSidebarCardView`).
-/// 2. Terminal persistence onboarding prompt (`TerminalPersistenceOnboardingCardView`).
-/// 3. Highlight Relevant onboarding prompt (`HighlightRelevantOnboardingCardView`).
-/// 4. Nested-worktrees onboarding prompt (`NestedWorktreesOnboardingCardView`).
-/// 5. Nothing.
+/// 2. Remote repositories Beta announcement (`RemoteRepositoriesBetaCardView`).
+/// 3. Terminal persistence onboarding prompt (`TerminalPersistenceOnboardingCardView`).
+/// 4. Highlight Relevant onboarding prompt (`HighlightRelevantOnboardingCardView`).
+/// 5. Nested-worktrees onboarding prompt (`NestedWorktreesOnboardingCardView`).
+/// 6. Nothing.
 ///
 /// Owns the `@Shared(.appStorage)` reads as stored properties so SwiftUI
 /// observes them at this layer and re-renders when the user dismisses a
@@ -32,6 +33,8 @@ struct SidebarBottomCardView: View {
   private var highlightDismissedAt: Date = .distantPast
   @Shared(.appStorage("terminalPersistenceOnboardingDismissedAt"))
   private var terminalPersistenceDismissedAt: Date = .distantPast
+  @Shared(.appStorage("remoteRepositoriesBetaOnboardingDismissedAt"))
+  private var remoteRepositoriesBetaDismissedAt: Date = .distantPast
 
   var body: some View {
     let agentMode = CodingAgentsSidebarCardView.resolveMode(
@@ -40,6 +43,9 @@ struct SidebarBottomCardView: View {
     let terminalPersistenceMode = TerminalPersistenceOnboardingCardView.resolveMode(
       dismissedAt: terminalPersistenceDismissedAt
     )
+    let remoteRepositoriesBetaMode = RemoteRepositoriesBetaCardView.resolveMode(
+      dismissedAt: remoteRepositoriesBetaDismissedAt
+    )
     let highlightMode = HighlightRelevantOnboardingCardView.resolveMode(
       groupPinnedRows: groupPinnedRows,
       groupActiveRows: groupActiveRows,
@@ -51,6 +57,7 @@ struct SidebarBottomCardView: View {
     )
     let resolved = Slot.resolve(
       agentMode: agentMode,
+      remoteRepositoriesBetaMode: remoteRepositoriesBetaMode,
       terminalPersistenceMode: terminalPersistenceMode,
       highlightMode: highlightMode,
       onboardingMode: onboardingMode
@@ -62,6 +69,9 @@ struct SidebarBottomCardView: View {
       case .agent(let mode):
         CodingAgentsSidebarCardView(store: store, mode: mode)
           .transition(Slot.transition)
+      case .remoteRepositoriesBeta:
+        RemoteRepositoriesBetaCardView()
+          .transition(Slot.transition)
       case .terminalPersistenceOnboarding:
         TerminalPersistenceOnboardingCardView()
           .transition(Slot.transition)
@@ -87,6 +97,7 @@ struct SidebarBottomCardView: View {
   enum Slot: Equatable {
     case none
     case agent(CodingAgentsSidebarCardView.Mode)
+    case remoteRepositoriesBeta
     case terminalPersistenceOnboarding
     case highlightRelevantOnboarding
     case nestedWorktreesOnboarding
@@ -95,6 +106,7 @@ struct SidebarBottomCardView: View {
 
     static func resolve(
       agentMode: CodingAgentsSidebarCardView.Mode,
+      remoteRepositoriesBetaMode: RemoteRepositoriesBetaCardView.Mode,
       terminalPersistenceMode: TerminalPersistenceOnboardingCardView.Mode,
       highlightMode: HighlightRelevantOnboardingCardView.Mode,
       onboardingMode: NestedWorktreesOnboardingCardView.Mode
@@ -103,9 +115,9 @@ struct SidebarBottomCardView: View {
       case .updatesAvailable, .promptInstall: return .agent(agentMode)
       case .hidden: break
       }
-      // `terminalPersistenceOnboarding` (zmx) is the newest card and pre-empts
-      // the older highlight / nested-worktrees prompts even when those would
-      // also be visible. Insert future cards at the top of this fall-through.
+      // Newest card wins. `remoteRepositoriesBeta` is the most recent and
+      // pre-empts the older prompts; insert future cards at the top here.
+      if remoteRepositoriesBetaMode == .visible { return .remoteRepositoriesBeta }
       if terminalPersistenceMode == .visible { return .terminalPersistenceOnboarding }
       if highlightMode == .visible { return .highlightRelevantOnboarding }
       return onboardingMode == .visible ? .nestedWorktreesOnboarding : .none
@@ -123,6 +135,7 @@ struct SidebarBottomCardView: View {
         "agent:updates:" + agents.map { String(describing: $0) }.sorted().joined(separator: ",")
       case .agent(.promptInstall): "agent:promptInstall"
       case .agent(.hidden): "agent:hidden"
+      case .remoteRepositoriesBeta: "remoteRepositoriesBeta:visible"
       case .terminalPersistenceOnboarding: "terminalPersistence:visible"
       case .highlightRelevantOnboarding: "highlightRelevant:visible"
       case .nestedWorktreesOnboarding: "nestedWorktrees:visible"
diff --git a/supacode/App/WindowTitle.swift b/supacode/App/WindowTitle.swift
index 0d019ac51..665f56c32 100644
--- a/supacode/App/WindowTitle.swift
+++ b/supacode/App/WindowTitle.swift
@@ -31,10 +31,16 @@ enum WindowTitle {
         terminalManager: terminalManager
       )
     case .failedRepository(let repositoryID):
-      let url = URL(fileURLWithPath: repositoryID).standardizedFileURL
+      // A failed remote keeps a placeholder repository whose `name` is the
+      // resolved display name; its id is a `user@host` authority, not a local
+      // path, so deriving a name from a file URL would be garbage. Fall back to
+      // the file-URL leaf only for a local failure with no placeholder.
+      let fallback =
+        repositories.repositories[id: repositoryID]?.name
+        ?? Repository.name(for: URL(fileURLWithPath: repositoryID.rawValue).standardizedFileURL)
       let name = repoDisplayName(
         repositoryID: repositoryID,
-        fallback: Repository.name(for: url),
+        fallback: fallback,
         repositories: repositories
       )
       return format(repo: name, tab: "Unavailable")
diff --git a/supacode/App/supacodeApp.swift b/supacode/App/supacodeApp.swift
index af7eb2e20..d8c37230f 100644
--- a/supacode/App/supacodeApp.swift
+++ b/supacode/App/supacodeApp.swift
@@ -51,10 +51,16 @@ final class SupacodeAppDelegate: NSObject, NSApplicationDelegate {
   private var bufferedDeeplinkURLs: [URL] = []
 
   func applicationWillTerminate(_ notification: Notification) {
-    // Embed agent records so badges survive relaunch (agents only emit
-    // session_start once per process lifetime).
+    // Drop the queued debounce timers; an already-started async flush has no
+    // cancellation checkpoint and still completes, but the writer's lock plus the
+    // atomic temp+rename keep this terminal write from tearing. The on-quit save
+    // embeds agent records so badges survive relaunch (agents only emit
+    // session_start once per process lifetime), and a second concurrent instance
+    // overwriting the file is an accepted dev-only last-writer-wins window.
+    terminalManager?.cancelPendingLayoutSaves()
     let agentsBySurface = appStore?.state.agentPresence.agentsBySurface() ?? [:]
     terminalManager?.saveAllLayoutSnapshots(agentsBySurface: agentsBySurface)
+    terminalManager?.rememberSelectedWorktreeZoomOnQuit()
   }
 
   func applicationDidFinishLaunching(_ notification: Notification) {
@@ -134,7 +140,17 @@ struct SupacodeApp: App {
     // re-upgrade path can't double-migrate, while a prior
     // half-finished migration that left a `schemaVersion == 0` file
     // still gets retried.
-    SidebarPersistenceMigrator.migrateIfNeeded()
+    // Snapshot settings.json + sidebar.json before any migration or @Shared hydration
+    // can rewrite them, so a botched migration or downgrade is recoverable by hand.
+    SidebarPersistenceMigrator.backupBeforeRemoteIdentityMigration()
+    // Capture the retired `global.remoteRepositories` before any migration can
+    // re-encode settings and drop the field. An unreadable settings.json skips
+    // both passes this launch (a save would strip it first); they retry next launch.
+    let capturedLegacyRemotes = SidebarPersistenceMigrator.captureLegacyRemoteRoots()
+    if capturedLegacyRemotes != .unreadable {
+      SidebarPersistenceMigrator.migrateIfNeeded()
+      SidebarPersistenceMigrator.migrateRemoteIdentityIfNeeded(capturedLegacy: capturedLegacyRemotes)
+    }
     @Shared(.settingsFile) var settingsFile
     let initialSettings = settingsFile.global
     let infoDictionary = Bundle.main.infoDictionary ?? [:]
@@ -168,6 +184,11 @@ struct SupacodeApp: App {
     _store = State(initialValue: appStore)
     appDelegate.appStore = appStore
     appDelegate.terminalManager = terminalManager
+    // Source live agent badge records for incremental layout captures; the [:]
+    // default would clobber badges that share a surface key on every save.
+    terminalManager.currentAgentsBySurface = { [weak appStore] in
+      appStore?.state.agentPresence.agentsBySurface() ?? [:]
+    }
     Self.configureSocketHandlers(terminalManager: terminalManager, store: appStore)
   }
 
@@ -178,15 +199,15 @@ struct SupacodeApp: App {
       @Shared(.layouts) var layouts: [String: TerminalLayoutSnapshot] = [:]
       $layouts.withLock { dict in
         if let snapshot {
-          dict[worktreeID] = snapshot
+          dict[worktreeID.rawValue] = snapshot
         } else {
-          dict.removeValue(forKey: worktreeID)
+          dict.removeValue(forKey: worktreeID.rawValue)
         }
       }
     }
     terminalManager.loadLayoutSnapshot = { worktreeID in
       @SharedReader(.layouts) var layouts: [String: TerminalLayoutSnapshot] = [:]
-      return layouts[worktreeID]
+      return layouts[worktreeID.rawValue]
     }
     return terminalManager
   }
@@ -316,13 +337,14 @@ struct SupacodeApp: App {
     switch resource {
     case "repos":
       let data = repos.map {
-        ["id": $0.id.addingPercentEncoding(withAllowedCharacters: pctSet) ?? $0.id]
+        ["id": $0.id.rawValue.addingPercentEncoding(withAllowedCharacters: pctSet) ?? $0.id.rawValue]
       }
       AgentHookSocketServer.sendQueryResponse(clientFD: clientFD, data: data)
     case "worktrees":
       let data = repos.flatMap { repo in
         repo.worktrees.map { worktree in
-          let encodedID = worktree.id.addingPercentEncoding(withAllowedCharacters: pctSet) ?? worktree.id
+          let encodedID =
+            worktree.id.rawValue.addingPercentEncoding(withAllowedCharacters: pctSet) ?? worktree.id.rawValue
           var entry = ["id": encodedID]
           if worktree.id == selectedWorktreeID { entry["focused"] = "1" }
           return entry
@@ -338,7 +360,7 @@ struct SupacodeApp: App {
       let tabs = terminalManager.listTabs(worktreeID: worktreeID)
       if tabs == nil {
         let decoded = worktreeID.removingPercentEncoding ?? worktreeID
-        let worktreeExists = repos.contains { $0.worktrees.contains { $0.id == decoded } }
+        let worktreeExists = repos.contains { $0.worktrees.contains { $0.id.rawValue == decoded } }
         guard worktreeExists else {
           AgentHookSocketServer.sendCommandResponse(
             clientFD: clientFD, ok: false, error: "Worktree not found: \(worktreeID)")
@@ -369,14 +391,14 @@ struct SupacodeApp: App {
       // accept both forms — matching the deeplink reducer's resolveWorktreeID.
       let allWorktrees = repos.flatMap(\.worktrees)
       let worktree =
-        allWorktrees.first(where: { $0.id == decoded })
-        ?? allWorktrees.first(where: { $0.id == decoded + "/" })
+        allWorktrees.first(where: { $0.id.rawValue == decoded })
+        ?? allWorktrees.first(where: { $0.id.rawValue == decoded + "/" })
       guard let worktree else {
         AgentHookSocketServer.sendCommandResponse(
           clientFD: clientFD, ok: false, error: "Worktree not found: \(worktreeID)")
         return
       }
-      @SharedReader(.repositorySettings(worktree.repositoryRootURL)) var settings
+      @SharedReader(.repositorySettings(worktree.repositoryRootURL, host: worktree.host)) var settings
       @SharedReader(.settingsFile) var settingsFile
       let runningIDs: Set<UUID> =
         store.repositories.sidebarItems[id: worktree.id]
@@ -420,8 +442,13 @@ struct SupacodeApp: App {
       TerminalCommands(ghosttyShortcuts: ghosttyShortcuts)
       WindowCommands(ghosttyShortcuts: ghosttyShortcuts)
       CommandGroup(after: .textEditing) {
+        Button("Go to Worktree") {
+          store.send(.commandPalette(.presentInMode(.worktreeSwitcher)))
+        }
+        .appKeyboardShortcut(AppShortcuts.worktreeSwitcher.effective(from: store.settings.shortcutOverrides))
+        .help("Switch between worktrees, sorted by most recently used")
         Button("Command Palette") {
-          store.send(.commandPalette(.togglePresented))
+          store.send(.commandPalette(.presentInMode(.commands)))
         }
         .appKeyboardShortcut(AppShortcuts.commandPalette.effective(from: store.settings.shortcutOverrides))
         .help("Command Palette")
diff --git a/supacode/Assets.xcassets/copilot-mark.imageset/Contents.json b/supacode/Assets.xcassets/copilot-mark.imageset/Contents.json
new file mode 100644
index 000000000..bdfd93225
--- /dev/null
+++ b/supacode/Assets.xcassets/copilot-mark.imageset/Contents.json
@@ -0,0 +1,16 @@
+{
+  "images" : [
+    {
+      "filename" : "copilot-mark.svg",
+      "idiom" : "universal"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  },
+  "properties" : {
+    "preserves-vector-representation" : true,
+    "template-rendering-intent" : "template"
+  }
+}
diff --git a/supacode/Assets.xcassets/copilot-mark.imageset/copilot-mark.svg b/supacode/Assets.xcassets/copilot-mark.imageset/copilot-mark.svg
new file mode 100644
index 000000000..e73c2830e
--- /dev/null
+++ b/supacode/Assets.xcassets/copilot-mark.imageset/copilot-mark.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" shape-rendering="geometricPrecision" text-rendering="geometricPrecision" image-rendering="optimizeQuality" fill-rule="evenodd" clip-rule="evenodd" viewBox="0 0 512 415.997"><path fill="#fff" fill-rule="nonzero" d="M181.33 266.141c0-11.496 9.32-20.817 20.818-20.817 11.498 0 20.819 9.321 20.819 20.817v38.373c0 11.497-9.321 20.818-20.819 20.818-11.497 0-20.818-9.32-20.818-20.818v-38.373zM512 246.391v57.384c-.02 7.411-3.696 14.638-9.67 19.011-70.565 51.655-157.636 93.211-246.33 93.211-98.138 0-196.378-56.542-246.329-93.209-5.975-4.374-9.65-11.6-9.671-19.012v-57.384l15.583-21.085c8.336-11.312 20.757-14.31 33.98-14.31 4.987-56.952 16.793-97.603 45.023-127.353C155.194 5.77 226.56 0 256 0c29.44 0 100.806 5.77 154.555 62.722 28.19 29.75 40.036 70.4 45.025 127.353 13.263 0 25.602 2.936 33.958 14.31l15.583 21.127c4.476 6.077 6.878 13.345 6.878 20.88l.001-.001zm-97.665-26.074c-.677-13.058-11.293-18.19-22.339-21.824-11.64 7.308-25.848 10.183-39.459 10.183-14.454 0-41.432-3.47-63.872-25.869-5.667-5.625-9.527-14.454-12.155-24.247l-.544-.001h-.546c-6.098 0-13.098.349-20.55 1.089-2.628 9.793-6.51 18.622-12.155 24.247-22.4 22.4-49.418 25.87-63.872 25.87-13.612 0-27.86-2.856-39.501-10.184-11.005 3.612-21.558 8.827-22.277 21.824-1.17 24.554-1.272 49.109-1.375 73.644-.04 12.318-.082 24.658-.288 36.975.062 7.166 4.374 13.818 10.882 16.774 52.97 24.124 103.045 36.278 149.136 36.278 46.01 0 96.085-12.154 149.013-36.278 6.508-2.956 10.84-9.608 10.881-16.774.637-36.831.124-73.808-1.642-110.619l.043.001-19.38-1.089zm-306.814-51.348c8.643 8.623 24.966 14.392 42.56 14.392 13.448 0 39.03-2.874 60.156-24.329 9.28-8.951 15.05-31.35 14.413-54.078-.657-18.231-5.769-33.28-13.448-39.665-8.315-7.371-27.203-10.574-48.33-8.644-22.399 2.237-41.267 9.587-50.875 19.833-20.797 22.728-16.323 80.316-4.476 92.491zm130.556-56.008c.637 3.51.965 7.35 1.273 11.517 0 2.875 0 5.77-.308 8.952 6.406-.636 11.847-.636 16.959-.636s10.552 0 16.958.636c-.328-3.182-.328-6.077-.328-8.952.328-4.167.656-8.007 1.294-11.517-6.735-.637-12.812-.965-17.924-.965s-11.21.328-17.924.965zm49.274-8.008c-.637 22.728 5.133 45.128 14.413 54.08 21.105 21.454 46.708 24.328 60.154 24.328 17.596 0 33.918-5.769 42.561-14.392 11.847-12.175 16.322-69.764-4.476-92.491-9.608-10.246-28.476-17.595-50.875-19.833-21.127-1.93-40.015 1.273-48.33 8.644-7.678 6.385-12.79 21.434-13.447 39.665v-.001zm21.455 140.371c-11.477 0-20.798 9.321-20.798 20.817v38.373c0 11.497 9.32 20.818 20.798 20.818 11.497 0 20.818-9.32 20.818-20.818v-38.373c0-11.496-9.32-20.817-20.818-20.817z"/></svg>
\ No newline at end of file
diff --git a/supacode/Assets.xcassets/opencode-mark.imageset/Contents.json b/supacode/Assets.xcassets/opencode-mark.imageset/Contents.json
new file mode 100644
index 000000000..0ea98124c
--- /dev/null
+++ b/supacode/Assets.xcassets/opencode-mark.imageset/Contents.json
@@ -0,0 +1,16 @@
+{
+  "images" : [
+    {
+      "filename" : "opencode-mark.svg",
+      "idiom" : "universal"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  },
+  "properties" : {
+    "preserves-vector-representation" : true,
+    "template-rendering-intent" : "template"
+  }
+}
diff --git a/supacode/Assets.xcassets/opencode-mark.imageset/opencode-mark.svg b/supacode/Assets.xcassets/opencode-mark.imageset/opencode-mark.svg
new file mode 100644
index 000000000..d1e3aa6e0
--- /dev/null
+++ b/supacode/Assets.xcassets/opencode-mark.imageset/opencode-mark.svg
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="512" height="512" viewBox="0 0 512 512" xmlns="http://www.w3.org/2000/svg">
+    <g id="Group">
+        <path id="Path-copy" fill="#211e1e" fill-opacity="0.25" stroke="none" d="M 359 409.600006 L 154 409.600006 L 154 204.799988 L 359 204.799988 L 359 409.600006 Z"/>
+        <path id="Path" fill="#211e1e" stroke="none" d="M 358.399994 102.399994 L 153.600006 102.399994 L 153.600006 409.600006 L 358.399994 409.600006 L 358.399994 102.399994 Z M 460.799988 512 L 51.200001 512 L 51.200001 0 L 460.799988 0 L 460.799988 512 Z"/>
+    </g>
+</svg>
diff --git a/supacode/Clients/Deeplink/DeeplinkClient.swift b/supacode/Clients/Deeplink/DeeplinkClient.swift
index 143413081..f72a037ad 100644
--- a/supacode/Clients/Deeplink/DeeplinkClient.swift
+++ b/supacode/Clients/Deeplink/DeeplinkClient.swift
@@ -53,11 +53,12 @@ private nonisolated enum DeeplinkParser {
       // settings/repo/<encoded-repo-id>[/scripts] → open repository settings.
       if pathSegments.first == "repo" {
         guard pathSegments.count >= 2,
-          let repositoryID = pathSegments[1].removingPercentEncoding, !repositoryID.isEmpty
+          let rawRepositoryID = pathSegments[1].removingPercentEncoding, !rawRepositoryID.isEmpty
         else {
           logger.warning("Settings repo deeplink missing or invalid repository ID.")
           return nil
         }
+        let repositoryID = RepositoryID(rawRepositoryID)
         if pathSegments.count >= 3 {
           guard pathSegments[2] == "scripts" else {
             logger.warning("Unrecognized settings repo subsection: \(pathSegments[2]).")
@@ -100,7 +101,7 @@ private nonisolated enum DeeplinkParser {
     }
     // Normalize trailing slashes so that IDs with and without a trailing
     // slash resolve to the same worktree.
-    let worktreeID = rawWorktreeID.hasSuffix("/") ? String(rawWorktreeID.dropLast()) : rawWorktreeID
+    let worktreeID = WorktreeID(rawWorktreeID.hasSuffix("/") ? String(rawWorktreeID.dropLast()) : rawWorktreeID)
     guard pathSegments.count >= 2 else {
       return .worktree(id: worktreeID, action: .select)
     }
@@ -267,10 +268,11 @@ private nonisolated enum DeeplinkParser {
       return .repoOpen(path: URL(fileURLWithPath: pathValue))
     }
 
-    guard let repositoryID = first.removingPercentEncoding, !repositoryID.isEmpty else {
+    guard let rawRepositoryID = first.removingPercentEncoding, !rawRepositoryID.isEmpty else {
       logger.warning("Failed to percent-decode repository ID")
       return nil
     }
+    let repositoryID = RepositoryID(rawRepositoryID)
     guard pathSegments.count >= 3,
       pathSegments[1] == "worktree",
       pathSegments[2] == "new"
diff --git a/supacode/Clients/Git/GitClient.swift b/supacode/Clients/Git/GitClient.swift
index c8a4aadf4..e7c25ccb9 100644
--- a/supacode/Clients/Git/GitClient.swift
+++ b/supacode/Clients/Git/GitClient.swift
@@ -15,6 +15,7 @@ enum GitOperation: String {
   case branchRefs = "branch_refs"
   case defaultRemoteBranchRef = "default_remote_branch_ref"
   case localHeadRef = "local_head_ref"
+  case symbolicHeadRef = "symbolic_head_ref"
   case ignoredFileCount = "ignored_file_count"
   case untrackedFileCount = "untracked_file_count"
   case branchDelete = "branch_delete"
@@ -113,7 +114,6 @@ struct GitClient {
       let isAttached = !entry.branch.isEmpty
       let name = isAttached ? entry.branch : worktreeURL.lastPathComponent
       let detail = Self.relativePath(from: repositoryRootURL, to: worktreeURL)
-      let id = worktreeURL.path(percentEncoded: false)
       let resourceValues = try? worktreeURL.resourceValues(forKeys: [
         .creationDateKey, .contentModificationDateKey,
       ])
@@ -121,11 +121,10 @@ struct GitClient {
       let sortDate = createdAt ?? .distantPast
       return WorktreeSortEntry(
         worktree: Worktree(
-          id: id,
+          location: .local(workingDirectory: worktreeURL, repositoryRoot: repositoryRootURL),
+          kind: .git,
           name: name,
           detail: detail,
-          workingDirectory: worktreeURL,
-          repositoryRootURL: repositoryRootURL,
           createdAt: createdAt,
           isMissing: isMissing,
           isAttached: isAttached
@@ -145,6 +144,88 @@ struct GitClient {
       .map(\.worktree)
   }
 
+  /// Worktrees via standard `git worktree list --porcelain`. Used for remote
+  /// (SSH) repositories where the bundled `wt` shim isn't available; the only
+  /// requirement is `git` on the remote PATH. Returns the same `Worktree`
+  /// shape as `worktrees(for:)`; the caller injects `host` / host-keyed ids.
+  /// Remote paths can't be stat'd locally, so `isMissing` is always false and
+  /// there's no creation-date sort (git's listing order is kept, main first).
+  nonisolated func gitWorktrees(for repoRoot: URL) async throws -> [Worktree] {
+    let repositoryRootURL = repoRoot.standardizedFileURL
+    let output = try await runGit(
+      operation: .worktreeList,
+      arguments: ["-C", repositoryRootURL.path(percentEncoded: false), "worktree", "list", "--porcelain"]
+    )
+    return Self.parseWorktreePorcelain(output, repositoryRootURL: repositoryRootURL)
+  }
+
+  /// Parse `git worktree list --porcelain`: blank-line-separated blocks of
+  /// `worktree <path>` / `HEAD <sha>` / `branch refs/heads/<name>` (or
+  /// `detached`); a `bare` block for the bare root is skipped.
+  nonisolated static func parseWorktreePorcelain(
+    _ output: String,
+    repositoryRootURL: URL
+  ) -> [Worktree] {
+    var worktrees: [Worktree] = []
+    for block in output.components(separatedBy: "\n\n") {
+      var path: String?
+      var branch: String?
+      var isBare = false
+      var isDetached = false
+      for rawLine in block.split(whereSeparator: \.isNewline) {
+        let line = String(rawLine).trimmingCharacters(in: .whitespaces)
+        if line.hasPrefix("worktree ") {
+          path = String(line.dropFirst("worktree ".count))
+        } else if line.hasPrefix("branch ") {
+          let ref = String(line.dropFirst("branch ".count))
+          let headsPrefix = "refs/heads/"
+          branch = ref.hasPrefix(headsPrefix) ? String(ref.dropFirst(headsPrefix.count)) : ref
+        } else if line == "bare" {
+          isBare = true
+        } else if line == "detached" {
+          isDetached = true
+        }
+      }
+      guard let path, !path.isEmpty, !isBare else { continue }
+      let worktreeURL = URL(fileURLWithPath: path).standardizedFileURL
+      let isAttached = (branch != nil) && !isDetached
+      let name = isAttached ? (branch ?? worktreeURL.lastPathComponent) : worktreeURL.lastPathComponent
+      worktrees.append(
+        Worktree(
+          location: .local(workingDirectory: worktreeURL, repositoryRoot: repositoryRootURL),
+          kind: .git,
+          name: name,
+          detail: relativePath(from: repositoryRootURL, to: worktreeURL),
+          createdAt: nil,
+          isMissing: false,
+          isAttached: isAttached
+        )
+      )
+    }
+    return worktrees
+  }
+
+  /// Create a worktree via standard `git worktree add` (for remote repos where
+  /// the bundled `wt` shim isn't available). Creates a new branch `name` at
+  /// `worktreePath` from `baseRef` (omitted → current HEAD). Throws
+  /// `GitClientError` on failure (collision, bad ref, missing parent dir).
+  /// Callers typically reload to re-list over ssh rather than build a worktree
+  /// model from this directly.
+  nonisolated func createGitWorktree(
+    in repoRoot: URL,
+    name: String,
+    baseRef: String,
+    worktreePath: URL
+  ) async throws {
+    let rootPath = repoRoot.standardizedFileURL.path(percentEncoded: false)
+    let wtPath = worktreePath.standardizedFileURL.path(percentEncoded: false)
+    var arguments = ["-C", rootPath, "worktree", "add", wtPath, "-b", name]
+    if !baseRef.isEmpty {
+      arguments.append(baseRef)
+    }
+    _ = try await runGit(operation: .worktreeCreate, arguments: arguments)
+  }
+
   // Backfill-only: never drop Supacode-owned locks here. Supacode-initiated
   // `removeWorktree` is the sole release path.
   nonisolated func reconcileSupacodeLocks(for repoRoot: URL) async {
@@ -523,17 +604,15 @@ struct GitClient {
                 }
                 let worktreeURL = URL(fileURLWithPath: pathLine).standardizedFileURL
                 let detail = Self.relativePath(from: repositoryRootURL, to: worktreeURL)
-                let id = worktreeURL.path(percentEncoded: false)
                 let resourceValues = try? worktreeURL.resourceValues(forKeys: [
                   .creationDateKey, .contentModificationDateKey,
                 ])
                 let createdAt = resourceValues?.creationDate ?? resourceValues?.contentModificationDate
                 let worktree = Worktree(
-                  id: id,
+                  location: .local(workingDirectory: worktreeURL, repositoryRoot: repositoryRootURL),
+                  kind: .git,
                   name: name,
                   detail: detail,
-                  workingDirectory: worktreeURL,
-                  repositoryRootURL: repositoryRootURL,
                   createdAt: createdAt
                 )
                 if let adminDir = Self.adminDirectory(forWorktreeAt: worktreeURL) {
@@ -590,34 +669,23 @@ struct GitClient {
     return arguments
   }
 
-  nonisolated func branchName(for worktreeURL: URL) async -> String? {
-    let headURL = await MainActor.run {
-      GitWorktreeHeadResolver.headURL(
-        for: worktreeURL,
-        fileManager: .default
-      )
-    }
-    guard let headURL else {
-      return nil
-    }
+  /// Resolve the current branch via `git rev-parse --abbrev-ref HEAD` so it
+  /// works over any transport (local or SSH). Returns the short branch name,
+  /// `"HEAD"` for a detached head, or `nil` on error (not a repo / unreachable
+  /// host). Replaces the former local-HEAD-file read, which couldn't resolve a
+  /// remote worktree's branch.
+  nonisolated func symbolicHeadBranch(at worktreeURL: URL) async -> String? {
+    let path = worktreeURL.path(percentEncoded: false)
     guard
-      let line = try? String(contentsOf: headURL, encoding: .utf8)
-        .split(whereSeparator: \.isNewline)
-        .first
+      let output = try? await runGit(
+        operation: .symbolicHeadRef,
+        arguments: ["-C", path, "rev-parse", "--abbrev-ref", "HEAD"]
+      )
     else {
       return nil
     }
-    let trimmed = line.trimmingCharacters(in: .whitespacesAndNewlines)
-    let refPrefix = "ref:"
-    if trimmed.hasPrefix(refPrefix) {
-      let ref = trimmed.dropFirst(refPrefix.count).trimmingCharacters(in: .whitespaces)
-      let headsPrefix = "refs/heads/"
-      if ref.hasPrefix(headsPrefix) {
-        return String(ref.dropFirst(headsPrefix.count))
-      }
-      return String(ref)
-    }
-    return "HEAD"
+    let trimmed = output.trimmingCharacters(in: .whitespacesAndNewlines)
+    return trimmed.isEmpty ? nil : trimmed
   }
 
   nonisolated func lineChanges(at worktreeURL: URL) async -> (added: Int, removed: Int)? {
@@ -691,17 +759,38 @@ struct GitClient {
 
   nonisolated func removeWorktree(_ worktree: Worktree, deleteBranch: Bool) async throws -> URL {
     let rootPath = worktree.repositoryRootURL.path(percentEncoded: false)
-    let worktreeURL = worktree.workingDirectory.standardizedFileURL
-    let worktreePath = worktreeURL.path(percentEncoded: false)
-    await releaseSupacodeLock(forWorktreeAt: worktreeURL, repoRoot: worktree.repositoryRootURL)
-    let relocatedURL = Self.relocateWorktreeDirectory(worktreeURL)
+    // `worktreePath` feeds the git command, which runs over `shell` (ssh for a
+    // remote worktree), so it's the display path for either kind.
+    let worktreePath = worktree.workingDirectory.standardizedFileURL.path(percentEncoded: false)
+    // The lock release / relocate / trash steps are *local* filesystem work, so
+    // they run only when a local URL exists. A remote worktree's
+    // `localWorkingDirectory` is nil, so a coincidental local path at the same
+    // absolute path can never be touched: `git worktree remove --force --force`
+    // on the host is the removal there.
+    let relocatedURL: URL?
+    if let localWorktreeURL = worktree.localWorkingDirectory?.standardizedFileURL {
+      await releaseSupacodeLock(forWorktreeAt: localWorktreeURL, repoRoot: worktree.repositoryRootURL)
+      relocatedURL = Self.relocateWorktreeDirectory(localWorktreeURL)
+    } else {
+      relocatedURL = nil
+    }
     // Prune is silent on still-locked entries; the --force --force
     // remove below is the actual guarantee.
     _ = try? await runGit(
       operation: .worktreePrune,
       arguments: ["-C", rootPath, "worktree", "prune", "--expire=now"]
     )
-    await runGitWorktreeRemove(rootPath: rootPath, worktreePath: worktreePath)
+    do {
+      try await runGitWorktreeRemove(rootPath: rootPath, worktreePath: worktreePath)
+    } catch {
+      // A local worktree's directory was already relocated to the trash above,
+      // so failing the git bookkeeping is non-fatal. A remote worktree has no
+      // such fallback: the host remove is the only deletion, so surface the
+      // failure unless git reports the entry was already gone.
+      if worktree.localWorkingDirectory == nil, !Self.isWorktreeAlreadyRemoved(error) {
+        throw error
+      }
+    }
     if deleteBranch, !worktree.name.isEmpty {
       // Don't leak the relocated trash dir below if the branch lookup throws.
       let names = (try? await localBranchNames(for: worktree.repositoryRootURL)) ?? []
@@ -854,11 +943,11 @@ struct GitClient {
   nonisolated private func runGitWorktreeRemove(
     rootPath: String,
     worktreePath: String
-  ) async {
+  ) async throws {
     // Double `--force` overrides both "dirty worktree" and "locked
     // worktree" so an orphan whose lock survived an unlock attempt
     // still gets cleaned up.
-    _ = try? await runGit(
+    _ = try await runGit(
       operation: .worktreeRemove,
       arguments: [
         "-C",
@@ -872,6 +961,19 @@ struct GitClient {
     )
   }
 
+  /// True when `git worktree remove` failed only because the entry was already
+  /// gone, so a remote removal with no local fallback can treat it as success.
+  nonisolated private static func isWorktreeAlreadyRemoved(_ error: Error) -> Bool {
+    guard let gitError = error as? GitClientError,
+      case .commandFailed(_, let message) = gitError
+    else {
+      return false
+    }
+    let lowered = message.lowercased()
+    return lowered.contains("is not a working tree")
+      || lowered.contains("no such file or directory")
+  }
+
   // Scan-fallback handles orphan rows whose `<worktree>/.git` pointer file
   // is unreadable; path comparison is symlink-resolved to match git's form.
   nonisolated private func releaseSupacodeLock(
diff --git a/supacode/Clients/Github/GithubCLIClient.swift b/supacode/Clients/Github/GithubCLIClient.swift
index b32878b92..e761b68bd 100644
--- a/supacode/Clients/Github/GithubCLIClient.swift
+++ b/supacode/Clients/Github/GithubCLIClient.swift
@@ -8,7 +8,7 @@ struct GithubAuthStatus: Equatable, Sendable {
   let host: String
 }
 
-private struct GithubAuthStatusResponse: Sendable {
+struct GithubAuthStatusResponse: Sendable {
   let hosts: [String: [GithubAuthAccount]]
 
   struct GithubAuthAccount: Sendable {
@@ -41,6 +41,148 @@ extension GithubAuthStatusResponse.GithubAuthAccount: Decodable {
   }
 }
 
+// A login shell sources `.zprofile` / `.zlogin` before `gh` runs, so a banner or version-manager
+// line can prepend to captured stdout and corrupt the JSON.
+enum GithubCLIOutput {
+  // No JSON found at all: the likely cause is shell startup output polluting stdout.
+  nonisolated static let noPayloadMessage =
+    "Could not read GitHub CLI output. Your shell startup files may be printing extra output to stdout."
+
+  // Valid JSON was found but failed to decode: the likely cause is an incompatible gh version.
+  nonisolated static let undecodableMessage =
+    "Could not parse GitHub CLI output. The installed GitHub CLI version may be incompatible."
+
+  nonisolated private static let logger = SupaLogger("GithubCLI")
+
+  // Every balanced top-level JSON value ({...} or [...]) in `output`, in source order. An opener that
+  // never balances (a stray brace from shell noise) is skipped, so leading noise cannot swallow a real
+  // payload that follows.
+  nonisolated static func balancedJSONSpans(in output: String) -> [Substring] {
+    var spans: [Substring] = []
+    var searchStart = output.startIndex
+    while let start = output[searchStart...].firstIndex(where: { $0 == "{" || $0 == "[" }) {
+      let opener = output[start]
+      let closer: Character = opener == "{" ? "}" : "]"
+      var depth = 0
+      var inString = false
+      var escaped = false
+      var matchedEnd: String.Index?
+      var index = start
+      scan: while index < output.endIndex {
+        let character = output[index]
+        switch character {
+        case _ where inString && escaped:
+          escaped = false
+        case "\\" where inString:
+          escaped = true
+        case "\"" where inString:
+          inString = false
+        case _ where inString:
+          break
+        case "\"":
+          inString = true
+        case opener:
+          depth += 1
+        case closer:
+          depth -= 1
+          guard depth == 0 else { break }
+          matchedEnd = output.index(after: index)
+          break scan
+        default:
+          break
+        }
+        index = output.index(after: index)
+      }
+      guard let end = matchedEnd else {
+        // Unbalanced opener (stray bracket in noise): skip it and keep scanning.
+        searchStart = output.index(after: start)
+        continue
+      }
+      spans.append(output[start..<end])
+      searchStart = end
+    }
+    return spans
+  }
+
+  // Decodes the JSON payload from possibly noisy gh stdout, surfacing a readable error (with the raw
+  // output logged) instead of an opaque DecodingError. Throws when no payload is found at all.
+  nonisolated static func decode<T: Decodable>(
+    _ type: T.Type,
+    from output: String,
+    decoder: JSONDecoder = JSONDecoder()
+  ) throws -> T {
+    guard let value = try decodeIfPresent(T.self, from: output, decoder: decoder) else {
+      logDecodeFailure(output)
+      throw GithubCLIError.commandFailed(noPayloadMessage)
+    }
+    return value
+  }
+
+  // Returns nil when `output` carries no JSON payload at all (e.g. `gh run list` with no runs), and
+  // throws only when a payload is present but cannot be decoded. gh prints its JSON after any leading
+  // shell noise, so the last decodable span wins.
+  nonisolated static func decodeIfPresent<T: Decodable>(
+    _ type: T.Type,
+    from output: String,
+    decoder: JSONDecoder = JSONDecoder()
+  ) throws -> T? {
+    let spans = balancedJSONSpans(in: output)
+    guard !spans.isEmpty else {
+      return nil
+    }
+    var lastDecodingError: Error?
+    var sawValidJSON = false
+    for span in spans.reversed() {
+      let data = Data(span.utf8)
+      do {
+        return try decoder.decode(T.self, from: data)
+      } catch {
+        lastDecodingError = error
+        if (try? JSONSerialization.jsonObject(with: data)) != nil {
+          sawValidJSON = true
+        }
+      }
+    }
+    let detail = lastDecodingError.map { "\($0)" } ?? "unknown"
+    logger.error("Failed to decode GitHub CLI JSON output: \(snapshot(of: output)) error=\(detail)")
+    // Valid JSON that failed to decode points at gh schema drift; otherwise the brackets were noise.
+    throw GithubCLIError.commandFailed(sawValidJSON ? undecodableMessage : noPayloadMessage)
+  }
+
+  // Logs a length-capped snapshot of the offending output so the user can retrieve it from the log
+  // stream without flooding it with a large banner.
+  nonisolated static func logDecodeFailure(_ output: String) {
+    logger.error("Failed to read GitHub CLI JSON output: \(snapshot(of: output))")
+  }
+
+  // Caps the logged output so a large banner does not flood the log stream.
+  nonisolated private static func snapshot(of output: String) -> String {
+    let limit = 500
+    let prefix = output.prefix(limit)
+    return prefix.endIndex == output.endIndex ? String(prefix) : "\(prefix)… (truncated)"
+  }
+}
+
+enum GithubAuthStatusParsing {
+  // `hosts` is an unordered dictionary, so prefer github.com and otherwise sort the keys: the result
+  // is deterministic even when more than one host has an active account.
+  nonisolated static func activeAccount(
+    in response: GithubAuthStatusResponse
+  ) -> (host: String, login: String)? {
+    let orderedHosts = response.hosts.keys.sorted { lhs, rhs in
+      if lhs == "github.com" { return true }
+      if rhs == "github.com" { return false }
+      return lhs < rhs
+    }
+    for host in orderedHosts {
+      if let active = response.hosts[host]?.first(where: { $0.active }) {
+        return (host, active.login)
+      }
+    }
+    return nil
+  }
+}
+
 struct GithubCLIClient: Sendable {
   var defaultBranch: @Sendable (URL) async throws -> String
   var latestRun: @Sendable (URL, String) async throws -> GithubWorkflowRun?
@@ -193,10 +335,9 @@ nonisolated private func defaultBranchFetcher(
       arguments: ["repo", "view", "--json", "defaultBranchRef"],
       repoRoot: repoRoot
     )
-    let data = Data(output.utf8)
     let decoder = JSONDecoder()
     decoder.dateDecodingStrategy = .iso8601
-    let response = try decoder.decode(GithubRepoViewResponse.self, from: data)
+    let response = try GithubCLIOutput.decode(GithubRepoViewResponse.self, from: output, decoder: decoder)
     return response.defaultBranchRef.name
   }
 }
@@ -221,14 +362,11 @@ nonisolated private func latestRunFetcher(
       ],
       repoRoot: repoRoot
     )
-    if output.isEmpty {
-      return nil
-    }
-    let data = Data(output.utf8)
     let decoder = JSONDecoder()
     decoder.dateDecodingStrategy = .iso8601
-    let runs = try decoder.decode([GithubWorkflowRun].self, from: data)
-    return runs.first
+    // nil payload means no runs; a present-but-undecodable payload still throws.
+    let runs = try GithubCLIOutput.decodeIfPresent([GithubWorkflowRun].self, from: output, decoder: decoder)
+    return runs?.first
   }
 }
 
@@ -247,33 +385,36 @@ nonisolated private func resolveRemoteInfoFetcher(
   resolver: GithubCLIExecutableResolver
 ) -> @Sendable (URL) async -> GithubRemoteInfo? {
   { repoRoot in
+    let output: String
     do {
-      let output = try await runGh(
+      output = try await runGh(
         shell: shell,
         resolver: resolver,
         arguments: ["repo", "view", "--json", "owner,name,url"],
         repoRoot: repoRoot
       )
-      let trimmed = output.trimmingCharacters(in: .whitespacesAndNewlines)
-      guard !trimmed.isEmpty else {
-        return nil
-      }
-      let response = try JSONDecoder().decode(
+    } catch {
+      return nil
+    }
+    // nil contract: decodeIfPresent tolerates leading shell noise and logs a present-but-undecodable
+    // payload before throwing, which `try?` collapses back to nil.
+    guard
+      let response = try? GithubCLIOutput.decodeIfPresent(
         GithubRepoViewRemoteInfoResponse.self,
-        from: Data(trimmed.utf8)
-      )
-      let host = hostFromRepoViewURL(response.url) ?? "github.com"
-      guard !response.owner.login.isEmpty, !response.name.isEmpty else {
-        return nil
-      }
-      return GithubRemoteInfo(
-        host: host,
-        owner: response.owner.login,
-        repo: response.name
+        from: output
       )
-    } catch {
+    else {
+      return nil
+    }
+    let host = hostFromRepoViewURL(response.url) ?? "github.com"
+    guard !response.owner.login.isEmpty, !response.name.isEmpty else {
       return nil
     }
+    return GithubRemoteInfo(
+      host: host,
+      owner: response.owner.login,
+      repo: response.name
+    )
   }
 }
 
@@ -460,14 +601,11 @@ nonisolated private func authStatusFetcher(
       arguments: ["auth", "status", "--json", "hosts"],
       repoRoot: nil
     )
-    let data = Data(output.utf8)
-    let response = try decodeAuthStatusResponse(from: data)
-    guard let (host, accounts) = response.hosts.first,
-      let activeAccount = accounts.first(where: { $0.active })
-    else {
+    let response = try GithubCLIOutput.decode(GithubAuthStatusResponse.self, from: output)
+    guard let active = GithubAuthStatusParsing.activeAccount(in: response) else {
       return nil
     }
-    return GithubAuthStatus(username: activeAccount.login, host: host)
+    return GithubAuthStatus(username: active.login, host: active.host)
   }
 }
 
@@ -617,10 +755,13 @@ nonisolated private func fetchPullRequestsChunk(
     return (chunkIndex, [:])
   }
 
-  let data = Data(result.output.utf8)
   let decoder = JSONDecoder()
   decoder.dateDecodingStrategy = .iso8601
-  let response = try decoder.decode(GithubGraphQLPullRequestResponse.self, from: data)
+  let response = try GithubCLIOutput.decode(
+    GithubGraphQLPullRequestResponse.self,
+    from: result.output,
+    decoder: decoder
+  )
   let prsByBranch = response.pullRequestsByBranch(
     aliasMap: result.aliasMap,
     owner: request.owner,
@@ -792,7 +933,3 @@ nonisolated private func shouldRetryGhExecution(after error: Error) -> Bool {
   }
   return false
 }
-
-nonisolated private func decodeAuthStatusResponse(from data: Data) throws -> GithubAuthStatusResponse {
-  try JSONDecoder().decode(GithubAuthStatusResponse.self, from: data)
-}
diff --git a/supacode/Clients/Repositories/GitClientDependency.swift b/supacode/Clients/Repositories/GitClientDependency.swift
index 3b7cec048..4aaefd4ef 100644
--- a/supacode/Clients/Repositories/GitClientDependency.swift
+++ b/supacode/Clients/Repositories/GitClientDependency.swift
@@ -54,64 +54,78 @@ struct GitClientDependency: Sendable {
 }
 
 extension GitClientDependency: DependencyKey {
-  static let liveValue = GitClientDependency(
-    repoRoot: { try await GitClient().repoRoot(for: $0) },
-    isGitRepository: { Repository.isGitRepository(at: $0) },
-    rootDirectoryExists: { url in
-      var isDirectory: ObjCBool = false
-      let exists = FileManager.default.fileExists(
-        atPath: url.standardizedFileURL.path(percentEncoded: false),
-        isDirectory: &isDirectory
-      )
-      return exists && isDirectory.boolValue
-    },
-    worktrees: { try await GitClient().worktrees(for: $0) },
-    reconcileSupacodeLocks: { await GitClient().reconcileSupacodeLocks(for: $0) },
-    localBranchNames: { try await GitClient().localBranchNames(for: $0) },
-    renameBranch: { oldName, newName, repoRoot in
-      try await GitClient().renameBranch(from: oldName, to: newName, for: repoRoot)
-    },
-    isValidBranchName: { branchName, repoRoot in
-      await GitClient().isValidBranchName(branchName, for: repoRoot)
-    },
-    branchInventory: { try await GitClient().branchInventory(for: $0, remoteNames: $1) },
-    defaultRemoteBranchRef: { try await GitClient().defaultRemoteBranchRef(for: $0) },
-    automaticWorktreeBaseRef: { await GitClient().automaticWorktreeBaseRef(for: $0) },
-    ignoredFileCount: { try await GitClient().ignoredFileCount(for: $0) },
-    untrackedFileCount: { try await GitClient().untrackedFileCount(for: $0) },
-    createWorktree: { name, repoRoot, baseDirectory, copyIgnored, copyUntracked, baseRef in
-      try await GitClient().createWorktree(
-        named: name,
-        in: repoRoot,
-        baseDirectory: baseDirectory,
-        copyFiles: (ignored: copyIgnored, untracked: copyUntracked),
-        baseRef: baseRef
-      )
-    },
-    createWorktreeStream: { name, repoRoot, baseDirectory, copyIgnored, copyUntracked, baseRef, directoryOverride in
-      GitClient().createWorktreeStream(
-        named: name,
-        in: repoRoot,
-        baseDirectory: baseDirectory,
-        copyFiles: (ignored: copyIgnored, untracked: copyUntracked),
-        baseRef: baseRef,
-        directoryOverride: directoryOverride
-      )
-    },
-    removeWorktree: { worktree, deleteBranch in
-      try await GitClient().removeWorktree(worktree, deleteBranch: deleteBranch)
-    },
-    isBareRepository: { repoRoot in
-      try await GitClient().isBareRepository(for: repoRoot)
-    },
-    branchName: { await GitClient().branchName(for: $0) },
-    lineChanges: { await GitClient().lineChanges(at: $0) },
-    remoteNames: { try await GitClient().remoteNames(for: $0) },
-    fetchRemote: { remote, repoRoot in try await GitClient().fetchRemote(remote, for: repoRoot) },
-    remoteInfo: { repositoryRoot in
-      await GitClient().remoteInfo(for: repositoryRoot)
-    }
-  )
+  static let liveValue = make(shell: .live)
+
+  /// Remote flavor: every `git` / `wt` shell-out runs on `host` over SSH.
+  /// `isGitRepository` / `rootDirectoryExists` still probe the *local*
+  /// filesystem, which is unreachable for remote paths, so these stay local-only
+  /// probes the remote load path never relies on.
+  static func ssh(host: RemoteHost) -> GitClientDependency {
+    make(shell: .ssh(host: host))
+  }
+
+  /// Single source of truth for the dependency's closures, parameterized on the
+  /// transport so the local and SSH flavors can't drift.
+  private static func make(shell: ShellClient) -> GitClientDependency {
+    GitClientDependency(
+      repoRoot: { try await GitClient(shell: shell).repoRoot(for: $0) },
+      isGitRepository: { Repository.isGitRepository(at: $0) },
+      rootDirectoryExists: { url in
+        var isDirectory: ObjCBool = false
+        let exists = FileManager.default.fileExists(
+          atPath: url.standardizedFileURL.path(percentEncoded: false),
+          isDirectory: &isDirectory
+        )
+        return exists && isDirectory.boolValue
+      },
+      worktrees: { try await GitClient(shell: shell).worktrees(for: $0) },
+      reconcileSupacodeLocks: { await GitClient(shell: shell).reconcileSupacodeLocks(for: $0) },
+      localBranchNames: { try await GitClient(shell: shell).localBranchNames(for: $0) },
+      renameBranch: { oldName, newName, repoRoot in
+        try await GitClient(shell: shell).renameBranch(from: oldName, to: newName, for: repoRoot)
+      },
+      isValidBranchName: { branchName, repoRoot in
+        await GitClient(shell: shell).isValidBranchName(branchName, for: repoRoot)
+      },
+      branchInventory: { try await GitClient(shell: shell).branchInventory(for: $0, remoteNames: $1) },
+      defaultRemoteBranchRef: { try await GitClient(shell: shell).defaultRemoteBranchRef(for: $0) },
+      automaticWorktreeBaseRef: { await GitClient(shell: shell).automaticWorktreeBaseRef(for: $0) },
+      ignoredFileCount: { try await GitClient(shell: shell).ignoredFileCount(for: $0) },
+      untrackedFileCount: { try await GitClient(shell: shell).untrackedFileCount(for: $0) },
+      createWorktree: { name, repoRoot, baseDirectory, copyIgnored, copyUntracked, baseRef in
+        try await GitClient(shell: shell).createWorktree(
+          named: name,
+          in: repoRoot,
+          baseDirectory: baseDirectory,
+          copyFiles: (ignored: copyIgnored, untracked: copyUntracked),
+          baseRef: baseRef
+        )
+      },
+      createWorktreeStream: { name, repoRoot, baseDirectory, copyIgnored, copyUntracked, baseRef, directoryOverride in
+        GitClient(shell: shell).createWorktreeStream(
+          named: name,
+          in: repoRoot,
+          baseDirectory: baseDirectory,
+          copyFiles: (ignored: copyIgnored, untracked: copyUntracked),
+          baseRef: baseRef,
+          directoryOverride: directoryOverride
+        )
+      },
+      removeWorktree: { worktree, deleteBranch in
+        try await GitClient(shell: shell).removeWorktree(worktree, deleteBranch: deleteBranch)
+      },
+      isBareRepository: { repoRoot in
+        try await GitClient(shell: shell).isBareRepository(for: repoRoot)
+      },
+      branchName: { await GitClient(shell: shell).symbolicHeadBranch(at: $0) },
+      lineChanges: { await GitClient(shell: shell).lineChanges(at: $0) },
+      remoteNames: { try await GitClient(shell: shell).remoteNames(for: $0) },
+      fetchRemote: { remote, repoRoot in try await GitClient(shell: shell).fetchRemote(remote, for: repoRoot) },
+      remoteInfo: { repositoryRoot in
+        await GitClient(shell: shell).remoteInfo(for: repositoryRoot)
+      }
+    )
+  }
   // Tests default to "git repository" classification so existing
   // fixtures that mock `gitClient.worktrees` without creating real
   // `.git` directories on disk keep exercising the git code path.
diff --git a/supacode/Clients/Terminal/TerminalClient.swift b/supacode/Clients/Terminal/TerminalClient.swift
index 49fe49626..b6bef35f2 100644
--- a/supacode/Clients/Terminal/TerminalClient.swift
+++ b/supacode/Clients/Terminal/TerminalClient.swift
@@ -55,7 +55,7 @@ struct TerminalClient {
     case destroyTab(Worktree, tabID: TerminalTabID)
     case destroySurface(Worktree, tabID: TerminalTabID, surfaceID: UUID)
     case beginTabRename(Worktree, tabID: TerminalTabID? = nil)
-    case prune(Set<Worktree.ID>)
+    case prune(keeping: Set<Worktree.ID>, protectingRepositoryIDs: Set<Repository.ID>)
     case setNotificationsEnabled(Bool)
     case setSelectedWorktreeID(Worktree.ID?)
     case refreshTabBarVisibility
diff --git a/supacode/Clients/Workspace/WorkspaceClient.swift b/supacode/Clients/Workspace/WorkspaceClient.swift
index 317c1e310..745bc5d05 100644
--- a/supacode/Clients/Workspace/WorkspaceClient.swift
+++ b/supacode/Clients/Workspace/WorkspaceClient.swift
@@ -13,7 +13,7 @@ struct WorkspaceClient {
 
 extension WorkspaceClient: DependencyKey {
   static let liveValue = WorkspaceClient { action, worktree, onError in
-    performOpenWorktreeAction(action: action, worktree: worktree, onError: onError)
+    WorktreeOpener.perform(action: action, worktree: worktree, onError: onError)
   }
 
   static let testValue = WorkspaceClient { _, _, _ in }
@@ -26,71 +26,343 @@ extension DependencyValues {
   }
 }
 
-private func performOpenWorktreeAction(
-  action: OpenWorktreeAction,
-  worktree: Worktree,
-  onError: @escaping @MainActor @Sendable (OpenActionError) -> Void
-) {
-  let actionTitle = action.title
-  switch action {
-  case .editor:
-    return
-  case .finder:
-    NSWorkspace.shared.activateFileViewerSelecting([worktree.workingDirectory])
-  case .androidStudio, .intellij, .webstorm, .pycharm, .rubymine, .rustrover:
-    guard let appURL = NSWorkspace.shared.urlForApplication(withBundleIdentifier: action.bundleIdentifier) else {
+@MainActor
+enum WorktreeOpener {
+  static func perform(
+    action: OpenWorktreeAction,
+    worktree: Worktree,
+    onError: @escaping @MainActor @Sendable (OpenActionError) -> Void
+  ) {
+    guard action != .editor else {
+      return
+    }
+    guard let targetURL = WorkspaceOpenResolver.resolveFirstTarget(for: action.openTargets, worktree: worktree) else {
       onError(
         OpenActionError(
-          title: "\(action.title) not found",
-          message: "Install \(action.title) to open this worktree."
+          title: "Unable to open in \(action.title)",
+          message: "No matching target was found for this worktree."
         )
       )
       return
     }
-    let configuration = NSWorkspace.OpenConfiguration()
-    configuration.createsNewApplicationInstance = true
-    configuration.arguments = [worktree.workingDirectory.path]
-    NSWorkspace.shared.openApplication(at: appURL, configuration: configuration) { _, error in
-      guard let error else {
-        return
-      }
-      Task { @MainActor in
-        onError(
-          OpenActionError(
-            title: "Unable to open in \(actionTitle)",
-            message: error.localizedDescription
-          )
-        )
-      }
+    guard action != .finder else {
+      NSWorkspace.shared.activateFileViewerSelecting([targetURL])
+      return
     }
-  case .alacritty, .antigravity, .cursor, .fork, .githubDesktop, .gitkraken, .gitup, .ghostty,
-    .kitty, .smartgit, .sourcetree, .sublimeMerge, .terminal, .vscode, .vscodeInsiders,
-    .vscodium, .warp, .wezterm, .windsurf, .xcode, .zed:
     guard let appURL = NSWorkspace.shared.urlForApplication(withBundleIdentifier: action.bundleIdentifier) else {
-      onError(
-        OpenActionError(
-          title: "\(action.title) not found",
-          message: "Install \(action.title) to open this worktree."
+      onError(.appNotFound(action))
+      return
+    }
+    for behavior in action.openBehaviors {
+      switch behavior {
+      case .workspace(let configuration):
+        openWithWorkspace(
+          action: action,
+          configuration: configuration,
+          appURL: appURL,
+          targetURL: targetURL,
+          onError: onError
         )
+        return
+      case .process(let executable, let args):
+        switch openWithProcess(executable: executable, args: args, appURL: appURL, targetURL: targetURL) {
+        case .launched:
+          return
+        case .unavailable:
+          continue
+        case .failed(let error):
+          onError(.openFailed(action, error))
+          return
+        }
+      }
+    }
+    onError(
+      OpenActionError(
+        title: "Unable to open in \(action.title)",
+        message: "No supported open behavior was available for this worktree."
+      )
+    )
+  }
+
+  private enum BehaviorOpenResult {
+    case launched
+    case unavailable
+    case failed(Error)
+  }
+
+  private static func openWithWorkspace(
+    action: OpenWorktreeAction,
+    configuration: OpenBehavior.WorkspaceConfiguration?,
+    appURL: URL,
+    targetURL: URL,
+    onError: @escaping @MainActor @Sendable (OpenActionError) -> Void
+  ) {
+    let workspaceConfiguration = workspaceOpenConfiguration(
+      configuration,
+      appURL: appURL,
+      targetURL: targetURL
+    )
+    guard configuration?.arguments.isEmpty == false else {
+      openTargetWithWorkspace(
+        action: action,
+        configuration: workspaceConfiguration,
+        appURL: appURL,
+        targetURL: targetURL,
+        onError: onError
       )
       return
     }
+    NSWorkspace.shared.openApplication(at: appURL, configuration: workspaceConfiguration) { _, error in
+      guard let error else {
+        return
+      }
+      Task { @MainActor in
+        onError(.openFailed(action, error))
+      }
+    }
+  }
+
+  private static func openTargetWithWorkspace(
+    action: OpenWorktreeAction,
+    configuration: NSWorkspace.OpenConfiguration,
+    appURL: URL,
+    targetURL: URL,
+    onError: @escaping @MainActor @Sendable (OpenActionError) -> Void
+  ) {
     NSWorkspace.shared.open(
-      [worktree.workingDirectory],
+      [targetURL],
       withApplicationAt: appURL,
-      configuration: .init()
+      configuration: configuration
     ) { _, error in
       guard let error else {
         return
       }
       Task { @MainActor in
-        onError(
-          OpenActionError(
-            title: "Unable to open in \(actionTitle)",
-            message: error.localizedDescription
-          )
+        onError(.openFailed(action, error))
+      }
+    }
+  }
+
+  private static func openWithProcess(
+    executable: OpenBehavior.ProcessExecutable,
+    args: [OpenBehavior.Argument],
+    appURL: URL,
+    targetURL: URL
+  ) -> BehaviorOpenResult {
+    guard let invocation = processInvocation(executable: executable, appURL: appURL) else {
+      return .unavailable
+    }
+    let process = Process()
+    process.executableURL = invocation.executableURL
+    process.arguments =
+      invocation.argumentPrefix + args.map { resolvedOpenArgument($0, appURL: appURL, targetURL: targetURL) }
+    do {
+      try process.run()
+      return .launched
+    } catch {
+      return .failed(error)
+    }
+  }
+
+  static func processInvocation(
+    executable: OpenBehavior.ProcessExecutable,
+    appURL: URL,
+    fileManager: FileManager = .default
+  ) -> (executableURL: URL, argumentPrefix: [String])? {
+    switch executable {
+    case .appRelativePath(let relativePath):
+      let executableURL = appRelativeURL(appURL: appURL, relativePath: relativePath)
+      guard fileManager.fileExists(atPath: executableURL.path(percentEncoded: false)) else {
+        return nil
+      }
+      return (executableURL, [])
+    case .path(let path):
+      if path.hasPrefix("/") {
+        return (URL(fileURLWithPath: path), [])
+      }
+      return (URL(fileURLWithPath: "/usr/bin/env"), [path])
+    }
+  }
+
+  private static func appRelativeURL(appURL: URL, relativePath: String) -> URL {
+    relativePath.split(separator: "/", omittingEmptySubsequences: true).reduce(appURL) { url, component in
+      url.appending(path: String(component))
+    }
+  }
+
+  private static func workspaceOpenConfiguration(
+    _ configuration: OpenBehavior.WorkspaceConfiguration?,
+    appURL: URL,
+    targetURL: URL
+  ) -> NSWorkspace.OpenConfiguration {
+    let workspaceConfiguration = NSWorkspace.OpenConfiguration()
+    guard let configuration else {
+      return workspaceConfiguration
+    }
+    workspaceConfiguration.createsNewApplicationInstance = configuration.createsNewApplicationInstance
+    workspaceConfiguration.arguments = configuration.arguments.map {
+      resolvedOpenArgument($0, appURL: appURL, targetURL: targetURL)
+    }
+    return workspaceConfiguration
+  }
+
+  private static func resolvedOpenArgument(
+    _ argument: OpenBehavior.Argument,
+    appURL: URL,
+    targetURL: URL
+  ) -> String {
+    switch argument {
+    case .literal(let value):
+      value
+    case .appPath:
+      appURL.path(percentEncoded: false)
+    case .targetPath:
+      targetURL.path(percentEncoded: false)
+    case .targetURL:
+      targetURL.absoluteString
+    }
+  }
+}
+
+extension OpenActionError {
+  static func appNotFound(_ action: OpenWorktreeAction) -> OpenActionError {
+    OpenActionError(
+      title: "\(action.title) not found",
+      message: "Install \(action.title) to open this worktree."
+    )
+  }
+
+  static func openFailed(_ action: OpenWorktreeAction, _ error: Error) -> OpenActionError {
+    OpenActionError(
+      title: "Unable to open in \(action.title)",
+      message: error.localizedDescription
+    )
+  }
+}
+
+enum WorkspaceOpenResolver {
+  static func resolveFirstTarget(
+    for targets: [OpenTarget],
+    worktree: Worktree,
+    fileManager: FileManager = .default
+  ) -> URL? {
+    for target in targets {
+      if let resolved = resolve(target, worktree: worktree, fileManager: fileManager) {
+        return resolved
+      }
+    }
+    return nil
+  }
+
+  private static func resolve(
+    _ target: OpenTarget,
+    worktree: Worktree,
+    fileManager: FileManager
+  ) -> URL? {
+    switch target {
+    case .workingDirectory:
+      worktree.workingDirectory
+    case .url(let url):
+      url
+    case .search(let pattern, let excludeDirectories, let maxDepth):
+      search(
+        in: worktree.workingDirectory,
+        matching: pattern,
+        excludeDirectories: excludeDirectories,
+        maxDepth: maxDepth,
+        fileManager: fileManager
+      )
+    }
+  }
+
+  private static func search(
+    in rootURL: URL,
+    matching pattern: String,
+    excludeDirectories: String?,
+    maxDepth: Int,
+    fileManager: FileManager
+  ) -> URL? {
+    guard let targetRegex = try? Regex(pattern) else {
+      return nil
+    }
+    let excludeRegex = excludeDirectories.flatMap { try? Regex($0) }
+    guard maxDepth > 0 else {
+      return nil
+    }
+    var directories = [SearchDirectory(url: rootURL, relativePath: "")]
+    for depth in 1...maxDepth {
+      let entries = directories.flatMap { directory in
+        searchEntries(
+          in: directory,
+          fileManager: fileManager
         )
       }
+      .sorted { lhs, rhs in
+        lhs.relativePath.localizedCaseInsensitiveCompare(rhs.relativePath) == .orderedAscending
+      }
+
+      for entry in entries where matches(targetRegex, in: entry.relativePath) {
+        return entry.url
+      }
+
+      directories = entries.compactMap { entry in
+        guard depth < maxDepth, entry.isDirectory, !entry.isPackage else {
+          return nil
+        }
+        if let excludeRegex, matches(excludeRegex, in: entry.relativePath) {
+          return nil
+        }
+        return SearchDirectory(url: entry.url, relativePath: entry.relativePath)
+      }
+    }
+    return nil
+  }
+
+  private struct SearchDirectory {
+    let url: URL
+    let relativePath: String
+  }
+
+  private struct SearchEntry {
+    let url: URL
+    let relativePath: String
+    let isDirectory: Bool
+    let isPackage: Bool
+  }
+
+  private static func searchEntries(
+    in directory: SearchDirectory,
+    fileManager: FileManager
+  ) -> [SearchEntry] {
+    guard
+      let childURLs = try? fileManager.contentsOfDirectory(
+        at: directory.url,
+        includingPropertiesForKeys: [.isDirectoryKey, .isPackageKey],
+        options: [.skipsHiddenFiles]
+      )
+    else {
+      return []
+    }
+    return childURLs.map { childURL in
+      let relativePath = childRelativePath(directory: directory, childURL: childURL)
+      let resourceValues = try? childURL.resourceValues(forKeys: [.isDirectoryKey, .isPackageKey])
+      return SearchEntry(
+        url: childURL,
+        relativePath: relativePath,
+        isDirectory: resourceValues?.isDirectory ?? false,
+        isPackage: resourceValues?.isPackage ?? false
+      )
+    }
+  }
+
+  private static func matches(_ regex: Regex<AnyRegexOutput>, in value: String) -> Bool {
+    value.firstMatch(of: regex) != nil
+  }
+
+  private static func childRelativePath(directory: SearchDirectory, childURL: URL) -> String {
+    guard !directory.relativePath.isEmpty else {
+      return childURL.lastPathComponent
     }
+    return directory.relativePath + "/" + childURL.lastPathComponent
   }
 }
diff --git a/supacode/Clients/Zmx/ZmxClient.swift b/supacode/Clients/Zmx/ZmxClient.swift
index 2b4a3d6fd..1004cd335 100644
--- a/supacode/Clients/Zmx/ZmxClient.swift
+++ b/supacode/Clients/Zmx/ZmxClient.swift
@@ -23,16 +23,14 @@ struct ZmxClient: Sendable {
   /// Use for kill paths against sessions persisted from earlier launches: probe
   /// bypass only means "don't wrap a new session", not "don't kill an old one".
   var isBundled: @Sendable () -> Bool
-  /// Wrap a surface command in `zmx attach <session-id>`. Pure; no side effects.
-  /// Returns nil when zmx is unbundled, so callers fall through to the raw `command`.
-  var wrapCommand: @Sendable (_ sessionID: String, _ userCommand: String?) -> String?
   /// Tear down a session. No-op on missing. Bounded by a 5-second timeout so a
   /// stuck daemon can't hold the close path indefinitely.
   var killSession: @Sendable (_ sessionID: String) async -> Void
-  /// Returns all live Supacode session names (`supa-<uuid>`) the daemon currently
-  /// hosts. Empty when zmx is unbundled or the daemon is unreachable. Used at
-  /// launch to reap sessions whose owning surface no longer exists.
-  var listSessions: @Sendable () async -> [String]
+  /// Returns each live Supacode session with its attached-client count, or nil
+  /// when the probe failed/timed out. nil means UNKNOWN (never reap); `[]` means
+  /// a successful empty listing. A `clients` of nil marks a session whose count
+  /// is unknown (err/status line), which the reaper must also spare.
+  var listSessionsWithClients: @Sendable () async -> [ZmxSessionListParser.Entry]?
 }
 
 /// Cached probe result so we log the bypass reason exactly once per process
@@ -191,24 +189,14 @@ extension ZmxClient {
     return ZmxClient(
       executableURL: resolveExecutable,
       isBundled: { bundledExecutable() != nil },
-      wrapCommand: { sessionID, userCommand in
-        guard let executable = resolveExecutable() else { return nil }
-        return ZmxAttach.buildCommand(
-          executablePath: executable.path(percentEncoded: false),
-          sessionID: sessionID,
-          userCommand: userCommand
-        )
-      },
       killSession: { sessionID in
         _ = await runZmx(["kill", sessionID])
       },
-      listSessions: {
-        guard let stdout = await runZmx(["ls", "--short"], captureStdout: true) else { return [] }
-        return
-          stdout
-          .split(whereSeparator: \.isNewline)
-          .map { $0.trimmingCharacters(in: .whitespaces) }
-          .filter { $0.hasPrefix(ZmxSessionID.prefix) && !$0.isEmpty }
+      listSessionsWithClients: {
+        // nil from runZmx is the UNKNOWN signal (spawn error / timeout / non-zero
+        // exit); preserve it so the reaper never kills against a failed probe.
+        guard let stdout = await runZmx(["ls"], captureStdout: true) else { return nil }
+        return ZmxSessionListParser.parse(stdout)
       }
     )
   }()
@@ -216,9 +204,8 @@ extension ZmxClient {
   nonisolated static let noop = ZmxClient(
     executableURL: { nil },
     isBundled: { false },
-    wrapCommand: { _, _ in nil },
     killSession: { _ in },
-    listSessions: { [] }
+    listSessionsWithClients: { [] }
   )
 }
 
@@ -234,6 +221,45 @@ extension DependencyValues {
   }
 }
 
+/// Pure parser for zmx's full (`ls`, non-`--short`) tab-delimited listing.
+/// Each line is `[→ |  ]name=<name>\tk=v\t...`; a healthy session carries
+/// `clients=<n>`, an unreachable one carries `err=`/`status=` (no count).
+nonisolated enum ZmxSessionListParser {
+  struct Entry: Equatable, Sendable {
+    var name: String
+    /// nil when the count is unknown (err/status line); the reaper spares these.
+    var clients: Int?
+  }
+
+  static func parse(_ stdout: String) -> [Entry] {
+    stdout
+      .split(whereSeparator: \.isNewline)
+      .compactMap { line -> Entry? in
+        // Strip the current-session arrow / leading indent before tokenizing.
+        var trimmed = Substring(line)
+        if trimmed.hasPrefix("→ ") {
+          trimmed = trimmed.dropFirst(2)
+        }
+        // Non-current sessions are indented with a literal leading space run.
+        while trimmed.first?.isWhitespace == true {
+          trimmed = trimmed.dropFirst()
+        }
+        let fields = trimmed.split(separator: "\t")
+        var values: [Substring: Substring] = [:]
+        for field in fields {
+          guard let separator = field.firstIndex(of: "=") else { continue }
+          let key = field[field.startIndex..<separator]
+          let value = field[field.index(after: separator)...]
+          values[key] = value
+        }
+        guard let name = values["name"], name.hasPrefix(ZmxSessionID.prefix) else { return nil }
+        // Absent `clients=` (err/status line) maps to nil = unknown, not zero.
+        let clients = values["clients"].flatMap { Int($0) }
+        return Entry(name: String(name), clients: clients)
+      }
+  }
+}
+
 /// Pure session-ID helpers. zmx's macOS socket-path budget is ~46 chars (sun_path
 /// is 104, default socket dir is ~58); `supa-<UUID>` lands at 41, leaving
 /// headroom for a longer custom `ZMX_DIR`.
@@ -311,8 +337,86 @@ nonisolated enum ZmxAttach {
     return "\(attach) /bin/sh -c \(shellQuote(command))"
   }
 
+  /// Argv that launches an interactive surface under zmx, passed to Ghostty as a
+  /// `command-wrapper` (prepended to the resolved shell argv). Each element is a
+  /// separate arg, so no shell quoting is needed even when the path has spaces.
+  static func buildWrapperArgv(executablePath: String, sessionID: String) -> [String] {
+    [executablePath, "attach", sessionID]
+  }
+
+  /// Resolves how a surface launches under zmx, given the budget-gated executable
+  /// path (nil when zmx is unbundled or over budget). Interactive surfaces
+  /// (`command == nil`) keep a nil command and get an argv `command-wrapper`, so
+  /// Ghostty resolves + integrates the real shell and zmx wraps the result.
+  /// Explicit commands (scripts) get a `/bin/sh -c` wrapped command string and no
+  /// wrapper. A nil `executablePath` falls through to the raw command with no zmx.
+  static func resolveLaunch(
+    executablePath: String?,
+    sessionID: String,
+    command: String?
+  ) -> (command: String?, commandWrapper: [String]) {
+    // A blank command is "no command" (interactive); normalize so an empty
+    // string can't slip into the script path and launch a bare shell uninteg.
+    let command = command.flatMap { $0.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ? nil : $0 }
+    guard let executablePath else { return (command, []) }
+    if command == nil {
+      return (nil, buildWrapperArgv(executablePath: executablePath, sessionID: sessionID))
+    }
+    return (buildCommand(executablePath: executablePath, sessionID: sessionID, userCommand: command), [])
+  }
+
   static func shellQuote(_ value: String) -> String {
     let escaped = value.replacing("'", with: "'\\''")
     return "'\(escaped)'"
   }
+
+  /// Remote surface command: a *local* zmx session whose child process is the
+  /// SSH connection to `host`. Session persistence (detach / reattach) lives on
+  /// the client; the remote just runs a plain login shell, so nothing has to be
+  /// installed on the host. `localZmxExecutablePath` is the budget-gated bundle
+  /// path (nil when zmx is unbundled or over budget), in which case the surface
+  /// is the bare ssh line with no persistence. The ssh line is single-quoted by
+  /// `buildCommand` for the local zmx-wrapping `/bin/sh -c`; its own inner
+  /// quoting (from `SSHCommand.commandLine`) survives that outer level.
+  static func buildRemoteCommand(
+    host: RemoteHost,
+    localZmxExecutablePath: String?,
+    sessionID: String,
+    userCommand: String?,
+    surfaceID: UUID
+  ) -> String {
+    let sshLine = SSHCommand.commandLine(
+      host: host,
+      remoteCommand: remoteShellCommand(userCommand: userCommand, surfaceID: surfaceID)
+    )
+    guard let localZmxExecutablePath else { return sshLine }
+    return buildCommand(executablePath: localZmxExecutablePath, sessionID: sessionID, userCommand: sshLine)
+  }
+
+  /// The command the *remote* shell runs over SSH: exports the surface id (so the
+  /// agent hook's in-band presence OSC is gated to a Supacode surface, see
+  /// `AgentPresenceOSC.emitShell`), prints the beta banner once at connection,
+  /// then runs the user command, or a login shell when there is none. No zmx on
+  /// the remote: persistence is the local zmx wrapping the whole ssh line. The
+  /// awaiting-input signal rides the terminal stream (OSC 3008), not a socket, so
+  /// no reverse forward / remote `SUPACODE_SOCKET_PATH` is needed (the pid suffix
+  /// is dropped over SSH).
+  static func remoteShellCommand(
+    userCommand: String?,
+    surfaceID: UUID
+  ) -> String {
+    let prelude = "export SUPACODE_SURFACE_ID=\(shellQuote(surfaceID.uuidString)); " + betaBanner
+    guard let command = userCommand?.trimmingCharacters(in: .whitespacesAndNewlines), !command.isEmpty else {
+      return prelude + "exec \"$SHELL\" -l"
+    }
+    return prelude + command
+  }
+
+  /// Dim banner printed at the top of a remote surface on connection, matching
+  /// the blocking-script read-only banner style. Remote surfaces are in beta and
+  /// some local-only features (Unix-socket agent hooks, worktree HEAD watching)
+  /// are unavailable, so the user gets an up-front heads-up. The session persists
+  /// across reattach, so this only prints on the first connect.
+  static let betaBanner =
+    #"printf '\033[2m── Remote Supacode surfaces are in beta and may have reduced functionality. ──\033[0m\r\n'; "#
 }
diff --git a/supacode/Commands/WorktreeCommands.swift b/supacode/Commands/WorktreeCommands.swift
index 71ed2a681..d1d5ee553 100644
--- a/supacode/Commands/WorktreeCommands.swift
+++ b/supacode/Commands/WorktreeCommands.swift
@@ -194,13 +194,19 @@ private struct WorktreeFileMenu: Commands {
     #endif
     let overrides = store.worktreeMenuSnapshot.shortcutOverrides
     let openRepo = AppShortcuts.openRepository.effective(from: overrides)
+    let addRemoteRepo = AppShortcuts.addRemoteRepository.effective(from: overrides)
     let confirm = AppShortcuts.confirmWorktreeAction.effective(from: overrides)
     CommandGroup(replacing: .newItem) {
-      Button("Add Repository or Folder...", systemImage: "folder.badge.plus") {
+      Button("Add Local Repository or Folder...", systemImage: "folder.badge.plus") {
         store.send(.repositories(.setOpenPanelPresented(true)))
       }
       .appKeyboardShortcut(openRepo)
-      .help("Add Repository or Folder (\(openRepo?.display ?? "none"))")
+      .help("Add a local repository or folder (\(openRepo?.display ?? "none"))")
+      Button("Add Remote Repository or Folder...", systemImage: "wifi") {
+        store.send(.repositories(.requestAddRemoteRepository))
+      }
+      .appKeyboardShortcut(addRemoteRepo)
+      .help("Add a repository or folder on an SSH host (\(addRemoteRepo?.display ?? "none"))")
       Button("Confirm Action") {
         confirmWorktreeAction?()
       }
diff --git a/supacode/Domain/PendingWorktree.swift b/supacode/Domain/PendingWorktree.swift
index 89683ae6c..0efa30358 100644
--- a/supacode/Domain/PendingWorktree.swift
+++ b/supacode/Domain/PendingWorktree.swift
@@ -1,7 +1,31 @@
 import Foundation
+import SupacodeSettingsShared
 
 struct PendingWorktree: Identifiable, Hashable {
-  let id: String
+  /// Sidebar customization that travels with the in-flight creation. Reconcile
+  /// reads this when materializing the pending row so a user-typed title /
+  /// color is visible while the worktree is being created; on success the
+  /// reducer copies it into the bucketed `SidebarState.Item` before the next
+  /// reconcile, on failure it's dropped with the row.
+  struct Customization: Hashable {
+    let title: String?
+    let color: RepositoryColor?
+  }
+
+  let id: Worktree.ID
   let repositoryID: Repository.ID
   var progress: WorktreeCreationProgress
+  var customization: Customization?
+
+  init(
+    id: Worktree.ID,
+    repositoryID: Repository.ID,
+    progress: WorktreeCreationProgress,
+    customization: Customization? = nil
+  ) {
+    self.id = id
+    self.repositoryID = repositoryID
+    self.progress = progress
+    self.customization = customization
+  }
 }
diff --git a/supacode/Domain/Repository.swift b/supacode/Domain/Repository.swift
index 92e1ac0f4..8ba94c8c5 100644
--- a/supacode/Domain/Repository.swift
+++ b/supacode/Domain/Repository.swift
@@ -2,29 +2,74 @@ import Foundation
 import IdentifiedCollections
 import SupacodeSettingsShared
 
-struct Repository: Identifiable, Hashable, Sendable {
-  let id: String
-  let rootURL: URL
+nonisolated struct Repository: Identifiable, Hashable, Sendable {
+  /// Where the repository lives (local URL or remote host + path). The single
+  /// source of truth for local-vs-remote: `id`, `host`, `rootURL`, and the
+  /// FileManager-safe `localRootURL` all derive from it.
+  let location: RepositoryLocation
+  /// Git repo vs plain directory. Flips freely on reload when the root is
+  /// (un)initialized as a git repo; persistence is unchanged.
+  let kind: RepositoryKind
   let name: String
   let worktrees: IdentifiedArrayOf<Worktree>
-  // Runtime classification — `false` means the rootURL is a plain
-  // directory (no `.git` / `.bare`) and the repository is treated as
-  // a non-git folder. Persistence is unchanged; this flips freely on
-  // reload when the directory is (un)initialized as a git repo.
-  let isGitRepository: Bool
 
+  /// Branded id derived from the location (local: absolute path; remote:
+  /// `<user@host:port><path>`). Stored so legacy/test call sites can pass it
+  /// explicitly, but production construction always derives it.
+  let id: RepositoryID
+
+  /// SSH host this repository lives on, or `nil` for a local repository.
+  var host: RemoteHost? { location.host }
+
+  var isGitRepository: Bool { kind == .git }
+
+  /// Display / settings-key URL. For a remote repo this is a synthetic
+  /// `file://` over the remote path; never hand it to FileManager.
+  var rootURL: URL { location.displayURL }
+
+  /// The on-disk URL for a local repository, `nil` for a remote one. Use this
+  /// for any FileManager work so a remote path can't be touched by accident.
+  var localRootURL: URL? { location.localRootURL }
+
+  /// Designated initializer: id is derived from the location.
+  init(
+    location: RepositoryLocation,
+    kind: RepositoryKind,
+    name: String,
+    worktrees: IdentifiedArrayOf<Worktree>
+  ) {
+    self.location = location
+    self.kind = kind
+    self.name = name
+    self.worktrees = worktrees
+    self.id = location.id
+  }
+
+  /// Back-compat initializer: builds the location from `rootURL` + `host`.
+  /// Kept so existing call sites (and tests) compile while the model migrates.
   init(
-    id: String,
+    id: RepositoryID,
     rootURL: URL,
     name: String,
     worktrees: IdentifiedArrayOf<Worktree>,
-    isGitRepository: Bool = true
+    isGitRepository: Bool = true,
+    host: RemoteHost? = nil
   ) {
-    self.id = id
-    self.rootURL = rootURL
+    if let host {
+      self.location = .remote(host, path: rootURL.path(percentEncoded: false))
+    } else {
+      self.location = .local(rootURL)
+    }
+    self.kind = isGitRepository ? .git : .folder
     self.name = name
     self.worktrees = worktrees
-    self.isGitRepository = isGitRepository
+    self.id = id
+  }
+
+  /// Copy preserving `location` and `kind`, swapping only the worktree set, so a
+  /// remote repo's host and kind survive an in-state worktree mutation.
+  func withWorktrees(_ worktrees: IdentifiedArrayOf<Worktree>) -> Repository {
+    Repository(location: location, kind: kind, name: name, worktrees: worktrees)
   }
 
   var initials: String {
@@ -72,37 +117,12 @@ struct Repository: Identifiable, Hashable, Sendable {
       && fileManager.fileExists(atPath: refsPath)
   }
 
-  /// Prefix on folder-synthetic worktree ids. Single source of truth
-  /// so reducer call sites that need to recover the repo id from a
-  /// folder worktree id (see `repositoryID(fromFolderWorktreeID:)`)
-  /// stay in sync with the constructor below.
-  nonisolated static let folderWorktreeIDPrefix = "folder:"
-
-  /// Stable synthetic worktree id for folder repositories. Keeps the
-  /// existing `SidebarSelection.worktree(id)` + terminal-manager
-  /// plumbing unchanged — folders reuse the same selection path.
+  /// Synthetic worktree id for a local folder repository: the repo root path.
+  /// Equals the owning repo id, so it round-trips back via `RepositoryID(_:)`;
+  /// it can't collide with a git worktree because a path is git or folder, never
+  /// both at once.
   nonisolated static func folderWorktreeID(for rootURL: URL) -> Worktree.ID {
-    folderWorktreeIDPrefix + rootURL.standardizedFileURL.path(percentEncoded: false)
-  }
-
-  /// Round-trip for `folderWorktreeID(for:)`: recover the owning
-  /// `Repository.ID` (the standardized path) from a folder-synthetic
-  /// worktree id. Returns `nil` for non-folder ids so callers can
-  /// distinguish "this isn't a folder worktree" from "this is a
-  /// folder worktree without a known repo."
-  nonisolated static func repositoryID(
-    fromFolderWorktreeID worktreeID: Worktree.ID
-  ) -> Repository.ID? {
-    guard worktreeID.hasPrefix(folderWorktreeIDPrefix) else { return nil }
-    return String(worktreeID.dropFirst(folderWorktreeIDPrefix.count))
-  }
-
-  /// Whether `worktreeID` is a folder-synthetic worktree id (as
-  /// produced by `folderWorktreeID(for:)`). Cheaper than calling
-  /// `repositoryID(fromFolderWorktreeID:)` when the caller only
-  /// wants the discrimination.
-  nonisolated static func isFolderWorktreeID(_ worktreeID: Worktree.ID) -> Bool {
-    worktreeID.hasPrefix(folderWorktreeIDPrefix)
+    WorktreeID(RepositoryLocation.local(rootURL.standardizedFileURL).id.rawValue)
   }
 
   /// Shared trim + fallback for the sidebar header and the highlight-row tag.
diff --git a/supacode/Domain/RepositoryIdentity.swift b/supacode/Domain/RepositoryIdentity.swift
new file mode 100644
index 000000000..3bf4b5880
--- /dev/null
+++ b/supacode/Domain/RepositoryIdentity.swift
@@ -0,0 +1,198 @@
+import Foundation
+import SupacodeSettingsShared
+
+/// Branded identifier for a `Repository`. A thin wrapper over the persisted
+/// string id so a repository id can never be passed where a worktree id (or a
+/// bare path) is expected. Encodes as a single string, so `OrderedDictionary`
+/// keys and `sidebar.json` keep their existing on-disk shape.
+nonisolated struct RepositoryID: Hashable, Sendable, Codable, CustomStringConvertible {
+  let rawValue: String
+
+  init(_ rawValue: String) { self.rawValue = rawValue }
+
+  var description: String { rawValue }
+
+  init(from decoder: any Decoder) throws {
+    self.rawValue = try decoder.singleValueContainer().decode(String.self)
+  }
+  func encode(to encoder: any Encoder) throws {
+    var container = encoder.singleValueContainer()
+    try container.encode(rawValue)
+  }
+}
+
+/// Branded identifier for a `Worktree` (and the sidebar row keyed off it).
+/// Same string-backed shape as `RepositoryID`; the two are compiler-distinct so
+/// a repo id and a worktree id can't be confused at a call site.
+nonisolated struct WorktreeID: Hashable, Sendable, Codable, CustomStringConvertible {
+  let rawValue: String
+
+  init(_ rawValue: String) { self.rawValue = rawValue }
+
+  var description: String { rawValue }
+
+  init(from decoder: any Decoder) throws {
+    self.rawValue = try decoder.singleValueContainer().decode(String.self)
+  }
+  func encode(to encoder: any Encoder) throws {
+    var container = encoder.singleValueContainer()
+    try container.encode(rawValue)
+  }
+}
+
+/// Whether a repository (and its worktrees) is a real git repo or a plain
+/// directory tracked as a folder. Replaces the standalone `isGitRepository`
+/// flag so git-vs-folder is one explicit value rather than a bool that can
+/// drift from the rest of the model.
+nonisolated enum RepositoryKind: Hashable, Sendable {
+  case git
+  case folder
+}
+
+/// Where a repository physically lives. The single home for the local-vs-remote
+/// distinction: a local repo carries a real filesystem `URL`, a remote repo
+/// carries its `RemoteHost` plus an absolute path string. There is no way to
+/// pull a local `URL` out of a remote location (`localRootURL` is `nil`), so a
+/// FileManager call can never be aimed at a remote path by accident.
+nonisolated enum RepositoryLocation: Hashable, Sendable {
+  case local(URL)
+  case remote(RemoteHost, path: String)
+
+  var host: RemoteHost? {
+    switch self {
+    case .local: nil
+    case .remote(let host, _): host
+    }
+  }
+
+  /// The filesystem URL for a local repo, `nil` for a remote one. Use this for
+  /// any FileManager / on-disk work so remote paths are structurally excluded.
+  var localRootURL: URL? {
+    switch self {
+    case .local(let url): url
+    case .remote: nil
+    }
+  }
+
+  /// A URL suitable only for display and for the `@Shared(.repositorySettings)`
+  /// key. For a remote repo this is a synthetic `file://` URL over the remote
+  /// path; never hand it to FileManager (use `localRootURL`).
+  var displayURL: URL {
+    switch self {
+    case .local(let url): url
+    case .remote(_, let path): URL(fileURLWithPath: path)
+    }
+  }
+
+  var path: String {
+    switch self {
+    case .local(let url): url.path(percentEncoded: false)
+    case .remote(_, let path): path
+    }
+  }
+
+  /// The branded id derived from the location. Local repos keep their bare
+  /// absolute path; remote repos use the self-descriptive
+  /// `<user@host:port><absolutePath>` form. The two never collide: a local id
+  /// is always an absolute path (leading `/`), a remote authority never starts
+  /// with `/`.
+  var id: RepositoryID {
+    switch self {
+    case .local(let url): RepositoryID(url.path(percentEncoded: false))
+    case .remote(let host, let path): RepositoryID(host.authority + path)
+    }
+  }
+
+  /// Trailing-slash-trimmed remote path, kept stable so a cosmetic edit doesn't
+  /// churn the derived id.
+  static func normalizedRemotePath(_ path: String) -> String {
+    var trimmed = Substring(path.trimmingCharacters(in: .whitespaces))
+    while trimmed.count > 1, trimmed.hasSuffix("/") {
+      trimmed = trimmed.dropLast()
+    }
+    return String(trimmed)
+  }
+
+  /// Parse a persisted repository id back into a location. A leading `/` is a
+  /// local absolute path; anything else is a remote `[user@]host[:port]<path>`
+  /// authority. Returns `nil` for a remote id whose authority can't be parsed.
+  static func parse(persistedID: String) -> RepositoryLocation? {
+    if persistedID.hasPrefix("/") {
+      return .local(URL(fileURLWithPath: persistedID))
+    }
+    guard let slash = persistedID.firstIndex(of: "/") else { return nil }
+    let authority = String(persistedID[..<slash])
+    let path = String(persistedID[slash...])
+    guard let host = RemoteHost(authority: authority) else { return nil }
+    return .remote(host, path: path)
+  }
+}
+
+/// Where a worktree physically lives. Carries both the worktree's working
+/// directory and its repository root, bound to a single host, so a worktree
+/// can never mix a local working dir with a remote root (or two hosts). Mirrors
+/// `RepositoryLocation`'s `local*` accessors for the same FileManager safety.
+nonisolated enum WorktreeLocation: Hashable, Sendable {
+  case local(workingDirectory: URL, repositoryRoot: URL)
+  case remote(RemoteHost, workingDirectory: String, repositoryRoot: String)
+
+  var host: RemoteHost? {
+    switch self {
+    case .local: nil
+    case .remote(let host, _, _): host
+    }
+  }
+
+  /// The working directory as a filesystem URL for a local worktree, `nil` for
+  /// a remote one.
+  var localWorkingDirectory: URL? {
+    switch self {
+    case .local(let workingDirectory, _): workingDirectory
+    case .remote: nil
+    }
+  }
+
+  /// Display / env-var URL for the working directory. Synthetic `file://` for
+  /// remote; never hand to FileManager.
+  var workingDirectory: URL {
+    switch self {
+    case .local(let workingDirectory, _): workingDirectory
+    case .remote(_, let workingDirectory, _): URL(fileURLWithPath: workingDirectory)
+    }
+  }
+
+  var repositoryRootURL: URL {
+    switch self {
+    case .local(_, let repositoryRoot): repositoryRoot
+    case .remote(_, _, let repositoryRoot): URL(fileURLWithPath: repositoryRoot)
+    }
+  }
+
+  var workingDirectoryPath: String {
+    switch self {
+    case .local(let workingDirectory, _): workingDirectory.path(percentEncoded: false)
+    case .remote(_, let workingDirectory, _): workingDirectory
+    }
+  }
+
+  /// The owning repository's location (same host, repository-root path).
+  var repositoryLocation: RepositoryLocation {
+    switch self {
+    case .local(_, let repositoryRoot): .local(repositoryRoot)
+    case .remote(let host, _, let repositoryRoot): .remote(host, path: repositoryRoot)
+    }
+  }
+
+  /// The branded worktree id derived from the location. Independent of
+  /// git-vs-folder: a folder synthetic and a git main worktree at the same path
+  /// share the id (they're mutually exclusive per path at any moment), and
+  /// `Worktree.kind` carries the runtime classification.
+  var id: WorktreeID {
+    switch self {
+    case .local(let workingDirectory, _):
+      return WorktreeID(workingDirectory.path(percentEncoded: false))
+    case .remote(let host, let workingDirectory, _):
+      return WorktreeID(host.authority + workingDirectory)
+    }
+  }
+}
diff --git a/supacode/Domain/SidebarBranchNesting.swift b/supacode/Domain/SidebarBranchNesting.swift
index 9a3ccd1b7..cf8d5fc42 100644
--- a/supacode/Domain/SidebarBranchNesting.swift
+++ b/supacode/Domain/SidebarBranchNesting.swift
@@ -99,8 +99,8 @@ enum SidebarBranchNesting {
     // by the caller when grouping is off and is restored verbatim once the user
     // toggles grouping back off.
     let sortedIDs = itemIDs.sorted { lhs, rhs in
-      let lhsKey = branchNames[lhs] ?? lhs
-      let rhsKey = branchNames[rhs] ?? rhs
+      let lhsKey = branchNames[lhs] ?? lhs.rawValue
+      let rhsKey = branchNames[rhs] ?? rhs.rawValue
       return lhsKey.localizedCaseInsensitiveCompare(rhsKey) == .orderedAscending
     }
 
diff --git a/supacode/Domain/Worktree.swift b/supacode/Domain/Worktree.swift
index 778b32a1b..863f812b4 100644
--- a/supacode/Domain/Worktree.swift
+++ b/supacode/Domain/Worktree.swift
@@ -1,11 +1,21 @@
 import Foundation
+import SupacodeSettingsShared
 
-struct Worktree: Identifiable, Hashable, Sendable {
-  let id: String
+nonisolated struct Worktree: Identifiable, Hashable, Sendable {
+  /// Branded id derived from the location (local: working-dir path; remote:
+  /// `<user@host:port><path>`). Independent of git-vs-folder, which is a runtime
+  /// classification carried in `kind`, not baked into the id. Stored so
+  /// legacy/test call sites can pass it explicitly; production derives it.
+  let id: WorktreeID
+  /// Where the worktree lives. Single source of truth for `host`,
+  /// `workingDirectory`, `repositoryRootURL`, and the FileManager-safe
+  /// `localWorkingDirectory`.
+  let location: WorktreeLocation
+  /// Git worktree vs folder synthetic. Runtime classification (a directory can
+  /// be (un)initialized as a git repo), so it lives here, not in the id.
+  let kind: RepositoryKind
   let name: String
   let detail: String
-  let workingDirectory: URL
-  let repositoryRootURL: URL
   let createdAt: Date?
   /// The admin entry exists but the working dir is gone on disk.
   /// Drives the orphan UI (warning icon, gated open actions).
@@ -15,24 +25,86 @@ struct Worktree: Identifiable, Hashable, Sendable {
   /// that has no real ref to operate on.
   let isAttached: Bool
 
+  /// SSH host this worktree lives on, or `nil` for a local worktree.
+  var host: RemoteHost? { location.host }
+
+  /// Display / env-var working-directory URL. For a remote worktree this is a
+  /// synthetic `file://` over the remote path; never hand it to FileManager.
+  var workingDirectory: URL { location.workingDirectory }
+  var repositoryRootURL: URL { location.repositoryRootURL }
+
+  /// The on-disk working directory for a local worktree, `nil` for a remote
+  /// one. Use this for any FileManager work.
+  var localWorkingDirectory: URL? { location.localWorkingDirectory }
+
+  /// Whether this is a folder-synthetic worktree.
+  var isFolder: Bool { kind == .folder }
+
+  /// Designated initializer: id is derived from the location.
   nonisolated init(
-    id: String,
+    location: WorktreeLocation,
+    kind: RepositoryKind,
+    name: String,
+    detail: String,
+    createdAt: Date? = nil,
+    isMissing: Bool = false,
+    isAttached: Bool = true
+  ) {
+    self.location = location
+    self.kind = kind
+    self.name = name
+    self.detail = detail
+    self.createdAt = createdAt
+    self.isMissing = isMissing
+    self.isAttached = isAttached
+    self.id = location.id
+  }
+
+  /// Back-compat initializer: builds the location from `workingDirectory` +
+  /// `repositoryRootURL` + `host`. Kept so existing call sites (and tests)
+  /// compile while the model migrates.
+  nonisolated init(
+    id: WorktreeID,
+    kind: RepositoryKind,
     name: String,
     detail: String,
     workingDirectory: URL,
     repositoryRootURL: URL,
     createdAt: Date? = nil,
     isMissing: Bool = false,
-    isAttached: Bool = true
+    isAttached: Bool = true,
+    host: RemoteHost? = nil
   ) {
-    self.id = id
+    if let host {
+      self.location = .remote(
+        host,
+        workingDirectory: workingDirectory.path(percentEncoded: false),
+        repositoryRoot: repositoryRootURL.path(percentEncoded: false)
+      )
+    } else {
+      self.location = .local(workingDirectory: workingDirectory, repositoryRoot: repositoryRootURL)
+    }
+    self.kind = kind
     self.name = name
     self.detail = detail
-    self.workingDirectory = workingDirectory
-    self.repositoryRootURL = repositoryRootURL
     self.createdAt = createdAt
     self.isMissing = isMissing
     self.isAttached = isAttached
+    self.id = id
+  }
+
+  /// Copy with a new display name, preserving `location` (and thus host and id)
+  /// and every other field, so renaming a remote worktree can't strip its host.
+  func renamed(_ newName: String) -> Worktree {
+    Worktree(
+      location: location,
+      kind: kind,
+      name: newName,
+      detail: detail,
+      createdAt: createdAt,
+      isMissing: isMissing,
+      isAttached: isAttached
+    )
   }
 }
 
diff --git a/supacode/Features/AgentPresence/Reducer/AgentPresenceFeature.swift b/supacode/Features/AgentPresence/Reducer/AgentPresenceFeature.swift
index fc0870527..f9e68c6bf 100644
--- a/supacode/Features/AgentPresence/Reducer/AgentPresenceFeature.swift
+++ b/supacode/Features/AgentPresence/Reducer/AgentPresenceFeature.swift
@@ -4,8 +4,6 @@ import Foundation
 import Sharing
 import SupacodeSettingsShared
 
-private let presenceLogger = SupaLogger("AgentPresence")
-
 @Reducer
 struct AgentPresenceFeature {
   /// Activity state per (surface, agent). Set atomically by the wire events
@@ -34,6 +32,11 @@ struct AgentPresenceFeature {
 
   nonisolated struct PresenceRecord: Equatable, Sendable {
     var activity: Activity = .idle
+    /// Local pids attributed to this record. Empty means the OSC presence was
+    /// emitted without a local pid (SSH attach); `pids.isEmpty` is the
+    /// discriminator for the pid-less lifecycle branches below. Every event
+    /// arrives over OSC now, so there is no "socket-owned" record to defend
+    /// against.
     var pids: Set<pid_t>
   }
 
@@ -71,7 +74,8 @@ struct AgentPresenceFeature {
   @ObservableState
   struct State: Equatable {
     /// Per-(surface, agent) record. Pids drive the liveness sweep and record
-    /// disposal. All bridges require a pid in the envelope.
+    /// disposal. Socket bridges carry a pid; the OSC-over-SSH transport seeds
+    /// pid-less records that the sweep skips.
     var records: [PresenceKey: PresenceRecord] = [:]
     /// Per-surface agent presence. A surface can host multiple agents (rare,
     /// but possible if e.g. Claude spawns Codex). Order not guaranteed; sort before display.
@@ -161,40 +165,68 @@ struct AgentPresenceFeature {
     let key = PresenceKey(agent: agent, surfaceID: event.surfaceID)
     switch event.eventName {
     case .sessionStart:
-      guard let pid = event.pid else { return [] }
-      var record = state.records[key] ?? PresenceRecord(pids: [])
-      let inserted = record.pids.insert(pid).inserted
-      state.records[key] = record
+      // A pid is the local-hook source (OSC presence carries `pid=$PPID` only on
+      // the local host); a missing pid is the OSC-over-SSH source, which attributes
+      // by the receiving surface and has no local pid to track.
+      if let pid = event.pid {
+        var record = state.records[key] ?? PresenceRecord(pids: [])
+        let inserted = record.pids.insert(pid).inserted
+        state.records[key] = record
+        rebuildPresence(forSurface: event.surfaceID, in: &state)
+        return inserted ? [event.surfaceID] : []
+      }
+      // Pid-less OSC seed: don't clobber a record that already carries a pid.
+      guard state.records[key] == nil else { return [] }
+      state.records[key] = PresenceRecord(pids: [])
       rebuildPresence(forSurface: event.surfaceID, in: &state)
-      return inserted ? [event.surfaceID] : []
+      return [event.surfaceID]
     case .sessionEnd:
-      guard let pid = event.pid, var record = state.records[key] else { return [] }
-      let removed = record.pids.remove(pid) != nil
-      if record.pids.isEmpty {
-        state.records.removeValue(forKey: key)
-      } else {
-        state.records[key] = record
+      if let pid = event.pid {
+        guard var record = state.records[key] else { return [] }
+        let removed = record.pids.remove(pid) != nil
+        if record.pids.isEmpty {
+          state.records.removeValue(forKey: key)
+        } else {
+          state.records[key] = record
+        }
+        rebuildPresence(forSurface: event.surfaceID, in: &state)
+        return removed ? [event.surfaceID] : []
       }
+      // Pid-less (OSC over SSH): only tear down a pid-less record; never one
+      // that carries a tracked local pid the liveness sweep still owns.
+      guard let record = state.records[key], record.pids.isEmpty else { return [] }
+      state.records.removeValue(forKey: key)
       rebuildPresence(forSurface: event.surfaceID, in: &state)
-      return removed ? [event.surfaceID] : []
+      return [event.surfaceID]
     case .busy:
-      return setActivity(.busy, for: key, in: &state) ? [event.surfaceID] : []
+      return applyActivity(.busy, event: event, key: key, into: &state) ? [event.surfaceID] : []
     case .awaitingInput:
-      return setActivity(.awaitingInput, for: key, in: &state) ? [event.surfaceID] : []
+      return applyActivity(.awaitingInput, event: event, key: key, into: &state) ? [event.surfaceID] : []
     case .idle:
-      return setActivity(.idle, for: key, in: &state) ? [event.surfaceID] : []
+      return applyActivity(.idle, event: event, key: key, into: &state) ? [event.surfaceID] : []
     case .notification, .none:
       return []
     }
   }
 
-  /// No-op on identical activity so repeated same-event hook bursts (e.g. consecutive
-  /// PreToolUse) don't churn observers; the busy/idle flip itself is a real transition,
-  /// debounced upstream. Returns true when the record actually flipped.
-  private static func setActivity(_ activity: Activity, for key: PresenceKey, in state: inout State) -> Bool {
-    guard var record = state.records[key], record.activity != activity else { return false }
-    record.activity = activity
-    state.records[key] = record
+  /// Auto-seed only on the OSC path (pid == nil), and only when the activity
+  /// would actually carry a badge: SSH attach can land on `busy` /
+  /// `awaiting_input` with no prior `session_start`, but an `idle` arriving
+  /// after the `session_end` + `idle` composite shutdown emit must NOT
+  /// re-create the record. A pid-less idle re-seed would be skipped by the
+  /// liveness sweep and pinned until surface close.
+  private static func applyActivity(
+    _ activity: Activity, event: AgentHookEvent, key: PresenceKey, into state: inout State
+  ) -> Bool {
+    if var record = state.records[key] {
+      guard record.activity != activity else { return false }
+      record.activity = activity
+      state.records[key] = record
+      return true
+    }
+    guard event.pid == nil, activity != .idle else { return false }
+    state.records[key] = PresenceRecord(activity: activity, pids: [])
+    rebuildPresence(forSurface: event.surfaceID, in: &state)
     return true
   }
 
@@ -258,6 +290,8 @@ struct AgentPresenceFeature {
       for (surfaceID, records) in layout.allAgentRecords() {
         for record in records {
           guard let agent = SkillAgent(rawValue: record.agent) else { continue }
+          // Pid-less OSC records aren't restore-durable: they persist with no
+          // pid, so they drop here and re-seed on the next OSC event post-relaunch.
           let pids = Set(record.pids.filter { $0 > 0 })
           guard !pids.isEmpty else { continue }
           let activity = Activity(rawValue: record.activity) ?? .idle
@@ -283,6 +317,7 @@ struct AgentPresenceFeature {
     var dirtySurfaces: Set<UUID> = []
     for (key, record) in records {
       if state.records[key] != nil { continue }
+      // Restored records always have alive pids (pid-less OSC records are dropped in stageRestore).
       state.records[key] = PresenceRecord(activity: record.activity, pids: record.alivePids)
       dirtySurfaces.insert(key.surfaceID)
     }
diff --git a/supacode/Features/AgentPresence/Views/AgentBadgeView.swift b/supacode/Features/AgentPresence/Views/AgentBadgeView.swift
index f960d4568..3eec8d294 100644
--- a/supacode/Features/AgentPresence/Views/AgentBadgeView.swift
+++ b/supacode/Features/AgentPresence/Views/AgentBadgeView.swift
@@ -30,7 +30,7 @@ struct AgentBadgeView: View {
       .accessibilityLabel(agent.displayName)
       .padding(size * 0.18)
       .frame(width: size, height: size)
-      .foregroundStyle(.primary)
+      .foregroundStyle(resolvedScheme == .dark ? .white : .black)
       .background(.bar.shadow(Self.dropShadow), in: .circle)
       .overlay(Circle().strokeBorder(.separator, lineWidth: pixelLength))
       .environment(\.colorScheme, resolvedScheme)
diff --git a/supacode/Features/App/Reducer/AppFeature.swift b/supacode/Features/App/Reducer/AppFeature.swift
index 858ffb324..d573433a4 100644
--- a/supacode/Features/App/Reducer/AppFeature.swift
+++ b/supacode/Features/App/Reducer/AppFeature.swift
@@ -277,7 +277,7 @@ struct AppFeature {
         state.repositories.$sidebar.withLock { sidebar in
           sidebar.focusedWorktreeID = lastFocusedWorktreeID
         }
-        @Shared(.repositorySettings(rootURL)) var repositorySettings
+        @Shared(.repositorySettings(rootURL, host: worktree.host)) var repositorySettings
         let settings = repositorySettings
         return .merge(
           .run { _ in
@@ -324,22 +324,35 @@ struct AppFeature {
               .repositoriesChanged(
                 repositories.map {
                   SettingsRepositorySummary(
-                    id: $0.id,
+                    id: $0.id.rawValue,
                     name: $0.name,
-                    isGitRepository: $0.isGitRepository
+                    isGitRepository: $0.isGitRepository,
+                    host: $0.host,
+                    rootURL: $0.rootURL
                   )
                 }
               )
             )
           ),
           .send(.commandPalette(.pruneRecency(recencyIDs))),
-          .run { [allowed] _ in
-            await terminalClient.send(.prune(allowed))
-          },
           .run { _ in
             await worktreeInfoWatcher.send(.setWorktrees(worktrees))
           },
         ])
+        // Don't prune terminal state while remote repos are still resolving:
+        // their placeholders have no rows yet, so pruning would delete restored
+        // remote layouts and kill their zmx sessions before resolution lands.
+        if state.repositories.resolvingRemoteRepositoryIDs.isEmpty {
+          // Failed/loading repos have no worktree rows yet, so shield their restored zmx sessions from prune.
+          let protectedRepositoryIDs = Set(state.repositories.loadFailuresByID.keys)
+          effects.append(
+            .run { [allowed, protectedRepositoryIDs] _ in
+              await terminalClient.send(
+                .prune(keeping: allowed, protectingRepositoryIDs: protectedRepositoryIDs)
+              )
+            }
+          )
+        }
         // Drain layout-seeded surfaces (including any that piled up from prior
         // reconciles before this delegate fired) so restored presence records
         // light up rows born on this tick.
@@ -374,7 +387,7 @@ struct AppFeature {
         // the scripts page which is the only settings surface that
         // applies to them.
         let section: SettingsSection =
-          repository.isGitRepository ? .repository(repositoryID) : .repositoryScripts(repositoryID)
+          repository.isGitRepository ? .repository(repositoryID.rawValue) : .repositoryScripts(repositoryID.rawValue)
         return .send(.settings(.setSelection(section)))
 
       case .repositories(.delegate(.runBlockingScript(let worktree, _, let kind, let script))):
@@ -405,7 +418,7 @@ struct AppFeature {
         state.globalScripts = settings.globalScripts
         if let selectedWorktree = state.repositories.worktree(for: state.repositories.selectedWorktreeID) {
           let rootURL = selectedWorktree.repositoryRootURL
-          @Shared(.repositorySettings(rootURL)) var repositorySettings
+          @Shared(.repositorySettings(rootURL, host: selectedWorktree.host)) var repositorySettings
           state.openActionSelection = OpenWorktreeAction.fromSettingsID(
             repositorySettings.openActionID,
             defaultEditorID: settings.defaultEditorID
@@ -477,7 +490,7 @@ struct AppFeature {
         }
         let rootURL = worktree.repositoryRootURL
         let actionID = action.settingsID
-        @Shared(.repositorySettings(rootURL)) var repositorySettings
+        @Shared(.repositorySettings(rootURL, host: worktree.host)) var repositorySettings
         $repositorySettings.withLock { $0.openActionID = actionID }
         return .none
 
@@ -619,7 +632,9 @@ struct AppFeature {
           if state.repoScripts.isEmpty, !state.globalScripts.isEmpty {
             return .send(.settings(.setSelection(.scripts)))
           }
-          let repositoryID = worktree.repositoryRootURL.path(percentEncoded: false)
+          let repositoryID =
+            state.repositories.repositoryID(containing: worktree.id)?.rawValue
+            ?? worktree.repositoryRootURL.path(percentEncoded: false)
           return .send(.settings(.setSelection(.repositoryScripts(repositoryID))))
         }
         return .send(.runNamedScript(definition))
@@ -644,7 +659,9 @@ struct AppFeature {
           if isGlobal {
             return .send(.settings(.setSelection(.scripts)))
           }
-          let repositoryID = worktree.repositoryRootURL.path(percentEncoded: false)
+          let repositoryID =
+            state.repositories.repositoryID(containing: worktree.id)?.rawValue
+            ?? worktree.repositoryRootURL.path(percentEncoded: false)
           return .send(.settings(.setSelection(.repositoryScripts(repositoryID))))
         }
         analyticsClient.capture("script_run", ["kind": definition.kind.rawValue])
@@ -742,14 +759,15 @@ struct AppFeature {
           await terminalClient.send(.endSearch(worktree))
         }
 
-      case .settings(.repositorySettings(.delegate(.settingsChanged(let rootURL)))):
+      case .settings(.repositorySettings(.delegate(.settingsChanged(let rootURL, let host)))):
         guard let selectedWorktree = state.repositories.worktree(for: state.repositories.selectedWorktreeID),
-          selectedWorktree.repositoryRootURL == rootURL
+          selectedWorktree.repositoryRootURL == rootURL,
+          selectedWorktree.host == host
         else {
           return .none
         }
         let worktreeID = selectedWorktree.id
-        @Shared(.repositorySettings(rootURL)) var repositorySettings
+        @Shared(.repositorySettings(rootURL, host: host)) var repositorySettings
         return .send(.worktreeSettingsLoaded(repositorySettings, worktreeID: worktreeID))
 
       case .worktreeSettingsLoaded(let settings, let worktreeID):
@@ -893,7 +911,21 @@ struct AppFeature {
         return .none
 
       case .commandPalette(.delegate(.selectWorktree(let worktreeID))):
-        return .send(.repositories(.selectWorktree(worktreeID)))
+        // Always-focused-terminal: palette completion lands focus in the
+        // chosen worktree's terminal, matching the menu/deeplink paths
+        // that already passed focusTerminal: true.
+        return .send(.repositories(.selectWorktree(worktreeID, focusTerminal: true)))
+
+      case .commandPalette(.delegate(.dismissedWithoutSelection)):
+        // Always-focused-terminal invariant. Cancellation paths (Esc, outside
+        // tap, programmatic close) don't carry a destination; refocus the
+        // current worktree's terminal so the cursor never lingers nowhere.
+        guard let worktreeID = state.repositories.selectedWorktreeID,
+          state.repositories.sidebarItems[id: worktreeID] != nil
+        else { return .none }
+        return .send(
+          .repositories(.sidebarItems(.element(id: worktreeID, action: .focusTerminalRequested)))
+        )
 
       case .commandPalette(.delegate(.checkForUpdates)):
         return .send(.updates(.checkForUpdates))
@@ -907,6 +939,9 @@ struct AppFeature {
       case .commandPalette(.delegate(.openRepository)):
         return .send(.repositories(.setOpenPanelPresented(true)))
 
+      case .commandPalette(.delegate(.addRemoteRepository)):
+        return .send(.repositories(.requestAddRemoteRepository))
+
       case .commandPalette(.delegate(.removeWorktree(let worktreeID, let repositoryID))):
         return .send(
           .repositories(
@@ -1240,6 +1275,13 @@ struct AppFeature {
       appLogger.info("Ignoring open of missing worktree \(worktree.id) from \(source.rawValue)")
       return .none
     }
+    // Open / Reveal target local Finder / editors; a remote SSH path can't be
+    // reached, so reject it here regardless of the entry point (UI gates this
+    // too, but a hotkey can still reach the reducer).
+    if worktree.host != nil {
+      appLogger.info("Ignoring open of remote worktree \(worktree.id) from \(source.rawValue)")
+      return .none
+    }
     analyticsClient.capture("worktree_opened", ["action": action.settingsID, "source": source.rawValue])
     guard action == .editor else {
       return .run { send in
@@ -1343,7 +1385,7 @@ struct AppFeature {
       // Folders have no general settings pane — send them to the
       // scripts page (the only settings surface that applies).
       let section: SettingsSection =
-        repository.isGitRepository ? .repository(repositoryID) : .repositoryScripts(repositoryID)
+        repository.isGitRepository ? .repository(repositoryID.rawValue) : .repositoryScripts(repositoryID.rawValue)
       return .send(.settings(.setSelection(section)))
     case .settingsRepoScripts(let repositoryID):
       guard state.repositories.repositories[id: repositoryID] != nil else {
@@ -1351,7 +1393,7 @@ struct AppFeature {
         state.alert = repositoryNotFoundAlert()
         return .none
       }
-      return .send(.settings(.setSelection(.repositoryScripts(repositoryID))))
+      return .send(.settings(.setSelection(.repositoryScripts(repositoryID.rawValue))))
     }
   }
 
@@ -1706,7 +1748,7 @@ struct AppFeature {
   /// Resolves a script by ID across the worktree's repo scripts and the user's globals.
   /// Repo entries win when both buckets carry the same ID.
   private func resolveScript(scriptID: UUID, in worktree: Worktree) -> ScriptDefinition? {
-    @SharedReader(.repositorySettings(worktree.repositoryRootURL)) var repositorySettings
+    @SharedReader(.repositorySettings(worktree.repositoryRootURL, host: worktree.host)) var repositorySettings
     @SharedReader(.settingsFile) var settingsFile
     let merged: [ScriptDefinition] = .merged(
       repo: repositorySettings.scripts,
@@ -1797,7 +1839,7 @@ struct AppFeature {
       // reasonable default disposition for folders.
       return .send(.repositories(.requestDeleteSidebarItems([target])))
     }
-    let worktreeName = state.repositories.worktree(for: worktreeID)?.name ?? worktreeID
+    let worktreeName = state.repositories.worktree(for: worktreeID)?.name ?? worktreeID.rawValue
     guard bypassConfirmation else {
       return presentDeeplinkConfirmation(
         worktreeID: worktreeID,
@@ -2062,7 +2104,7 @@ struct AppFeature {
     state: State
   ) -> Worktree.ID {
     guard state.repositories.worktree(for: rawID) == nil else { return rawID }
-    let alternate = rawID + "/"
+    let alternate = WorktreeID(rawID.rawValue + "/")
     guard state.repositories.worktree(for: alternate) != nil else { return rawID }
     return alternate
   }
@@ -2093,7 +2135,7 @@ struct AppFeature {
   private func surfaceDeeplinkURL(worktreeID: Worktree.ID, surfaceID: UUID) -> URL? {
     let percentEncodingSet = CharacterSet.urlPathAllowed.subtracting(.init(charactersIn: "/"))
     let encodedWorktreeID =
-      worktreeID.addingPercentEncoding(withAllowedCharacters: percentEncodingSet) ?? worktreeID
+      worktreeID.rawValue.addingPercentEncoding(withAllowedCharacters: percentEncodingSet) ?? worktreeID.rawValue
     guard let tabID = terminalClient.tabID(worktreeID, surfaceID) else {
       notificationsLogger.debug(
         "Surface \(surfaceID) is no longer attached to a tab in \(worktreeID); "
diff --git a/supacode/Features/CommandPalette/CommandPaletteItem.swift b/supacode/Features/CommandPalette/CommandPaletteItem.swift
index b5adb9c9b..1bf13ca61 100644
--- a/supacode/Features/CommandPalette/CommandPaletteItem.swift
+++ b/supacode/Features/CommandPalette/CommandPaletteItem.swift
@@ -10,24 +10,33 @@ struct CommandPaletteItem: Identifiable, Equatable {
   let subtitle: String?
   let kind: Kind
   let priorityTier: Int
+  /// `true` for the worktree-switcher row that represents the worktree the
+  /// user is already in. The switcher still renders it (so you can see
+  /// where you are), but the overlay skips it for the default selection so
+  /// ⌘P then Enter lands on the previous worktree instead of being a
+  /// no-op. Always `false` outside the worktree switcher.
+  let isCurrentWorktree: Bool
 
   init(
     id: String,
     title: String,
     subtitle: String?,
     kind: Kind,
-    priorityTier: Int = defaultPriorityTier
+    priorityTier: Int = defaultPriorityTier,
+    isCurrentWorktree: Bool = false
   ) {
     self.id = id
     self.title = title
     self.subtitle = subtitle
     self.kind = kind
     self.priorityTier = priorityTier
+    self.isCurrentWorktree = isCurrentWorktree
   }
 
   enum Kind: Equatable {
     case checkForUpdates
     case openRepository
+    case addRemoteRepository
     case worktreeSelect(Worktree.ID)
     case openSettings
     case newWorktree
@@ -54,8 +63,8 @@ struct CommandPaletteItem: Identifiable, Equatable {
 
   var isGlobal: Bool {
     switch kind {
-    case .checkForUpdates, .openRepository, .openSettings, .newWorktree, .viewArchivedWorktrees,
-      .refreshWorktrees:
+    case .checkForUpdates, .openRepository, .addRemoteRepository, .openSettings, .newWorktree,
+      .viewArchivedWorktrees, .refreshWorktrees:
       true
     case .ghosttyCommand:
       false
@@ -83,8 +92,8 @@ struct CommandPaletteItem: Identifiable, Equatable {
 
   var isRootAction: Bool {
     switch kind {
-    case .checkForUpdates, .openRepository, .openSettings, .newWorktree, .viewArchivedWorktrees,
-      .refreshWorktrees:
+    case .checkForUpdates, .openRepository, .addRemoteRepository, .openSettings, .newWorktree,
+      .viewArchivedWorktrees, .refreshWorktrees:
       true
     case .ghosttyCommand:
       false
@@ -120,7 +129,8 @@ struct CommandPaletteItem: Identifiable, Equatable {
     case .refreshWorktrees: AppShortcuts.refreshWorktrees
     case .ghosttyCommand: nil
     case .openPullRequest: AppShortcuts.openPullRequest
-    case .markPullRequestReady,
+    case .addRemoteRepository,
+      .markPullRequestReady,
       .mergePullRequest,
       .closePullRequest,
       .copyFailingJobURL,
diff --git a/supacode/Features/CommandPalette/Reducer/CommandPaletteFeature.swift b/supacode/Features/CommandPalette/Reducer/CommandPaletteFeature.swift
index f4cf29a93..9155ef5d7 100644
--- a/supacode/Features/CommandPalette/Reducer/CommandPaletteFeature.swift
+++ b/supacode/Features/CommandPalette/Reducer/CommandPaletteFeature.swift
@@ -6,9 +6,21 @@ import SupacodeSettingsShared
 
 @Reducer
 struct CommandPaletteFeature {
+  /// Two narrow surfaces sharing one palette UI. `.commands` is the
+  /// historical full palette (worktrees, scripts, ghostty actions, PR
+  /// actions, settings); `.worktreeSwitcher` shows only worktrees, sorted
+  /// by `RepositoriesFeature.State.worktreeMRU`. Mode lives in State so
+  /// the items builder, the view, and the dismiss handler all read the
+  /// same source of truth.
+  enum PaletteMode: Equatable, Sendable {
+    case commands
+    case worktreeSwitcher
+  }
+
   @ObservableState
   struct State: Equatable {
     var isPresented = false
+    var mode: PaletteMode = .commands
     var query = ""
     var selectedIndex: Int?
     var recencyByItemID: [CommandPaletteItem.ID: TimeInterval] = [:]
@@ -23,9 +35,14 @@ struct CommandPaletteFeature {
     case binding(BindingAction<State>)
     case setPresented(Bool)
     case togglePresented
+    /// Open the palette in a specific mode. No-op if already presented in
+    /// the same mode; switches mode and refreshes selection if already
+    /// presented in a different mode. Wired to the Cmd+P / Cmd+Shift+P
+    /// menu items in `supacodeApp.swift`.
+    case presentInMode(PaletteMode)
     case activateItem(CommandPaletteItem)
-    case updateSelection(itemsCount: Int)
-    case resetSelection(itemsCount: Int)
+    case updateSelection(itemsCount: Int, defaultIndex: Int)
+    case resetSelection(itemsCount: Int, defaultIndex: Int)
     case moveSelection(SelectionMove, itemsCount: Int)
     case pruneRecency([CommandPaletteItem.ID])
     case delegate(Delegate)
@@ -38,6 +55,7 @@ struct CommandPaletteFeature {
     case openSettings
     case newWorktree
     case openRepository
+    case addRemoteRepository
     case removeWorktree(Worktree.ID, Repository.ID)
     case archiveWorktree(Worktree.ID, Repository.ID)
     case renameBranch(Worktree.ID, Repository.ID)
@@ -54,6 +72,11 @@ struct CommandPaletteFeature {
     case openFailingCheckDetails(Worktree.ID)
     case runScript(ScriptDefinition)
     case stopScript(UUID, name: String)
+    /// Palette closed without the user activating an item (Esc, outside
+    /// tap, programmatic dismiss). AppFeature uses this to refocus the
+    /// current worktree's terminal — the "terminal is the default
+    /// focus" invariant.
+    case dismissedWithoutSelection
     #if DEBUG
       case debugTestToast(RepositoriesFeature.StatusToast)
     #endif
@@ -69,6 +92,7 @@ struct CommandPaletteFeature {
         return .none
 
       case .setPresented(let isPresented):
+        let wasPresented = state.isPresented
         state.isPresented = isPresented
         if isPresented {
           loadRecency(into: &state)
@@ -76,17 +100,39 @@ struct CommandPaletteFeature {
         } else {
           state.query = ""
           state.selectedIndex = nil
+          state.mode = .commands
+        }
+        if wasPresented, !isPresented {
+          return .send(.delegate(.dismissedWithoutSelection))
         }
         return .none
 
       case .togglePresented:
+        let wasPresented = state.isPresented
         state.isPresented.toggle()
         if state.isPresented {
+          state.mode = .commands
           loadRecency(into: &state)
           state.selectedIndex = nil
         } else {
           state.query = ""
           state.selectedIndex = nil
+          state.mode = .commands
+        }
+        if wasPresented, !state.isPresented {
+          return .send(.delegate(.dismissedWithoutSelection))
+        }
+        return .none
+
+      case .presentInMode(let mode):
+        let wasPresented = state.isPresented
+        let modeChanged = state.mode != mode
+        state.isPresented = true
+        state.mode = mode
+        if !wasPresented || modeChanged {
+          loadRecency(into: &state)
+          state.query = ""
+          state.selectedIndex = nil
         }
         return .none
 
@@ -94,11 +140,14 @@ struct CommandPaletteFeature {
         state.isPresented = false
         state.query = ""
         state.selectedIndex = nil
+        state.mode = .commands
         state.recencyByItemID[item.id] = now.timeIntervalSince1970
         saveRecency(state.recencyByItemID)
+        // No `.dismissedWithoutSelection` here: every activation delegate
+        // resolves to a destination that owns its own focus transition.
         return .send(.delegate(delegateAction(for: item.kind)))
 
-      case .updateSelection(let itemsCount):
+      case .updateSelection(let itemsCount, let defaultIndex):
         if itemsCount == 0 {
           state.selectedIndex = nil
           return .none
@@ -106,12 +155,12 @@ struct CommandPaletteFeature {
         if let selectedIndex = state.selectedIndex, selectedIndex >= itemsCount {
           state.selectedIndex = itemsCount - 1
         } else if state.selectedIndex == nil {
-          state.selectedIndex = 0
+          state.selectedIndex = min(max(defaultIndex, 0), itemsCount - 1)
         }
         return .none
 
-      case .resetSelection(let itemsCount):
-        state.selectedIndex = itemsCount == 0 ? nil : 0
+      case .resetSelection(let itemsCount, let defaultIndex):
+        state.selectedIndex = itemsCount == 0 ? nil : min(max(defaultIndex, 0), itemsCount - 1)
         return .none
 
       case .moveSelection(let direction, let itemsCount):
@@ -153,26 +202,31 @@ struct CommandPaletteFeature {
   static func filterItems(
     items: [CommandPaletteItem],
     query: String,
+    mode: PaletteMode = .commands,
     recencyByID: [CommandPaletteItem.ID: TimeInterval] = [:],
     now: Date = .now
   ) -> [CommandPaletteItem] {
     let trimmed = query.trimmingCharacters(in: .whitespacesAndNewlines)
-    let globalItems = items.filter(\.isGlobal)
     guard !trimmed.isEmpty else {
-      let visibleItems = globalItems.filter { !$0.isRootAction }
-      return prioritizeItems(items: visibleItems, recencyByID: recencyByID, now: now)
+      switch mode {
+      case .commands:
+        // The empty-query commands palette shows only the non-root global
+        // actions; worktrees, scripts, and PR actions surface once you type.
+        let visibleItems = items.filter { $0.isGlobal && !$0.isRootAction }
+        return prioritizeItems(items: visibleItems, recencyByID: recencyByID, now: now)
+      case .worktreeSwitcher:
+        // The switcher is a navigation surface: every worktree row is visible
+        // with no query, already ordered MRU-first via `priorityTier`.
+        return prioritizeItems(items: items, recencyByID: recencyByID, now: now)
+      }
     }
     let scorer = CommandPaletteFuzzyScorer(query: trimmed, recencyByID: recencyByID, now: now)
     return scorer.rankedItems(from: items)
   }
 
-  static func commandPaletteItems(
-    from repositories: RepositoriesFeature.State,
-    ghosttyCommands: [GhosttyCommand] = [],
-    scripts: [ScriptDefinition] = [],
-    runningScriptIDs: Set<UUID> = []
-  ) -> [CommandPaletteItem] {
-    var items: [CommandPaletteItem] = [
+  /// The always-present global actions, shown regardless of selection.
+  static func globalActionItems() -> [CommandPaletteItem] {
+    [
       CommandPaletteItem(
         id: CommandPaletteItemID.globalCheckForUpdates,
         title: "Check for Updates",
@@ -191,6 +245,12 @@ struct CommandPaletteFeature {
         subtitle: nil,
         kind: .openRepository
       ),
+      CommandPaletteItem(
+        id: CommandPaletteItemID.globalAddRemoteRepository,
+        title: "Add Remote Repository",
+        subtitle: nil,
+        kind: .addRemoteRepository
+      ),
       CommandPaletteItem(
         id: CommandPaletteItemID.globalNewWorktree,
         title: "New Worktree",
@@ -210,6 +270,15 @@ struct CommandPaletteFeature {
         kind: .viewArchivedWorktrees
       ),
     ]
+  }
+
+  static func commandPaletteItems(
+    from repositories: RepositoriesFeature.State,
+    ghosttyCommands: [GhosttyCommand] = [],
+    scripts: [ScriptDefinition] = [],
+    runningScriptIDs: Set<UUID> = []
+  ) -> [CommandPaletteItem] {
+    var items = globalActionItems()
     if repositories.selectedWorktreeID != nil {
       items.append(contentsOf: ghosttyCommandItems(ghosttyCommands))
       items.append(contentsOf: scriptItems(scripts: scripts, runningScriptIDs: runningScriptIDs))
@@ -230,41 +299,15 @@ struct CommandPaletteFeature {
     #if DEBUG
       items.append(contentsOf: debugToastItems())
     #endif
-    if let selectedWorktreeID = repositories.selectedWorktreeID,
-      let selectedRow = repositories.sidebarItems[id: selectedWorktreeID],
-      let selectedRepositoryID = repositories.repositoryID(containing: selectedWorktreeID),
-      let selectedWorktree = repositories.worktree(for: selectedWorktreeID),
-      !selectedRow.isFolder,
-      !selectedRow.name.isEmpty,
-      selectedRow.lifecycle == .idle,
-      selectedWorktree.isAttached,
-      !selectedWorktree.isMissing
-    {
-      let repositoryName = Repository.sidebarDisplayName(
-        custom: repositories.sidebar.sections[selectedRepositoryID]?.title,
-        fallback: repositories.repositoryName(for: selectedRepositoryID) ?? "Repository"
-      )
-      items.append(
-        CommandPaletteItem(
-          id: CommandPaletteItemID.renameBranch(selectedWorktreeID),
-          title: "Rename Branch",
-          subtitle: "\(repositoryName) · \(selectedRow.name)",
-          kind: .renameBranch(selectedWorktreeID, selectedRepositoryID)
-        )
-      )
+    if let renameBranchItem = renameBranchItem(from: repositories) {
+      items.append(renameBranchItem)
     }
     for row in repositories.orderedSidebarItems() {
       guard row.lifecycle == .idle else { continue }
-      let repositoryName = repositories.repositoryName(for: row.repositoryID) ?? "Repository"
-      // Folder rows only have a synthetic "main" worktree whose name
-      // matches the repository, so the usual `repo / worktree`
-      // format would render as `Foo / Foo`. Use the repository name
-      // alone for folders.
-      let title = row.isFolder ? repositoryName : "\(repositoryName) / \(row.name)"
       items.append(
         CommandPaletteItem(
           id: CommandPaletteItemID.worktreeSelect(row.id),
-          title: title,
+          title: worktreeRowTitle(for: row, in: repositories),
           subtitle: nil,
           kind: .worktreeSelect(row.id)
         )
@@ -273,6 +316,36 @@ struct CommandPaletteFeature {
     return items
   }
 
+  /// The "Rename Branch" action for the selected git worktree, or `nil` when the
+  /// selection isn't an idle, attached, non-folder worktree that can be renamed.
+  static func renameBranchItem(from repositories: RepositoriesFeature.State) -> CommandPaletteItem? {
+    guard let selectedWorktreeID = repositories.selectedWorktreeID,
+      let selectedRow = repositories.sidebarItems[id: selectedWorktreeID],
+      let selectedRepositoryID = repositories.repositoryID(containing: selectedWorktreeID),
+      let selectedWorktree = repositories.worktree(for: selectedWorktreeID),
+      !selectedRow.isFolder,
+      !selectedRow.name.isEmpty,
+      selectedRow.lifecycle == .idle,
+      selectedWorktree.isAttached,
+      !selectedWorktree.isMissing
+    else {
+      return nil
+    }
+    let repositoryName = Repository.sidebarDisplayName(
+      custom: repositories.sidebar.sections[selectedRepositoryID]?.title,
+      fallback: repositories.repositoryName(for: selectedRepositoryID) ?? "Repository"
+    )
+    let worktreeDisplayName =
+      SidebarDisplayName.resolved(custom: selectedRow.customTitle, fallback: selectedRow.name)
+      ?? selectedRow.name
+    return CommandPaletteItem(
+      id: CommandPaletteItemID.renameBranch(selectedWorktreeID),
+      title: "Rename Branch",
+      subtitle: "\(repositoryName) · \(worktreeDisplayName)",
+      kind: .renameBranch(selectedWorktreeID, selectedRepositoryID)
+    )
+  }
+
   static func recencyRetentionIDs(
     from repositories: IdentifiedArrayOf<Repository>,
     scripts: [ScriptDefinition] = []
@@ -291,6 +364,98 @@ struct CommandPaletteFeature {
     }
     return ids
   }
+
+  /// Mode-aware item dispatch. The palette overlay calls this once per
+  /// re-render; the mode comes from `State.mode` and the per-mode
+  /// builders own all selection / ranking / subtitle decisions.
+  static func items(
+    in mode: PaletteMode,
+    from repositories: RepositoriesFeature.State,
+    ghosttyCommands: [GhosttyCommand] = [],
+    scripts: [ScriptDefinition] = [],
+    runningScriptIDs: Set<UUID> = []
+  ) -> [CommandPaletteItem] {
+    switch mode {
+    case .commands:
+      return commandPaletteItems(
+        from: repositories,
+        ghosttyCommands: ghosttyCommands,
+        scripts: scripts,
+        runningScriptIDs: runningScriptIDs
+      )
+    case .worktreeSwitcher:
+      return worktreeSwitcherItems(from: repositories)
+    }
+  }
+
+  /// Worktree switcher items. Order: `worktreeMRU` entries first in recency
+  /// order (most-recent-first), then any remaining idle worktree in sidebar
+  /// order. `priorityTier` carries the ordinal so `prioritizeItems` keeps MRU
+  /// order with an empty query; the fuzzy scorer — matching the combined
+  /// `repo / worktree` title, so a query hits either the project name or the
+  /// worktree name — takes over once the user types.
+  ///
+  /// The current worktree (`selectedWorktreeID`, normally the `worktreeMRU`
+  /// head) is rendered so you can see where you are, but it carries
+  /// `isCurrentWorktree` so the overlay skips it for the default selection —
+  /// ⌘P then Enter lands on the previous worktree (Cmd+Tab style) instead of
+  /// being a no-op.
+  static func worktreeSwitcherItems(
+    from repositories: RepositoriesFeature.State
+  ) -> [CommandPaletteItem] {
+    let mruRank: [Worktree.ID: Int] = Dictionary(
+      repositories.worktreeMRU.enumerated().map { ($1, $0) },
+      uniquingKeysWith: { first, _ in first }
+    )
+    let currentWorktreeID = repositories.selectedWorktreeID
+    let idleRows = repositories.orderedSidebarItems().filter { $0.lifecycle == .idle }
+    let ordered =
+      idleRows.enumerated().sorted { lhs, rhs in
+        switch (mruRank[lhs.element.id], mruRank[rhs.element.id]) {
+        case let (lhsRank?, rhsRank?): return lhsRank < rhsRank
+        case (_?, nil): return true
+        case (nil, _?): return false
+        case (nil, nil): return lhs.offset < rhs.offset
+        }
+      }
+      .map(\.element)
+
+    return ordered.enumerated().map { index, row in
+      let repositoryName = repositories.repositoryName(for: row.repositoryID) ?? "Repository"
+      // Worktree name is the prominent title; the repo rides as a quieter
+      // subtitle so the two read as a hierarchy instead of one `repo / wt`
+      // blur. The fuzzy scorer matches title AND subtitle, so a query still
+      // hits either the worktree name or the project name. Folder rows have a
+      // synthetic "main" worktree whose name matches the repo, so they show
+      // the repo name alone with no redundant subtitle.
+      let title = row.isFolder ? repositoryName : row.name
+      let subtitle = row.isFolder ? nil : repositoryName
+      return CommandPaletteItem(
+        id: CommandPaletteItemID.worktreeSelect(row.id),
+        title: title,
+        subtitle: subtitle,
+        kind: .worktreeSelect(row.id),
+        priorityTier: index,
+        isCurrentWorktree: row.id == currentWorktreeID
+      )
+    }
+  }
+
+  /// `repo / worktree` row title used by the commands palette (⌘⇧P), where
+  /// worktree rows sit in one flat list alongside actions. Folder rows only
+  /// have a synthetic "main" worktree whose name matches the repository, so
+  /// they render as the repository name alone to avoid a `Foo / Foo` label.
+  static func worktreeRowTitle(
+    for row: SidebarItemFeature.State,
+    in repositories: RepositoriesFeature.State
+  ) -> String {
+    let repositoryName = Repository.sidebarDisplayName(
+      custom: repositories.sidebar.sections[row.repositoryID]?.title,
+      fallback: repositories.repositoryName(for: row.repositoryID) ?? "Repository"
+    )
+    let worktreeDisplayName = SidebarDisplayName.resolved(custom: row.customTitle, fallback: row.name) ?? row.name
+    return row.isFolder ? repositoryName : "\(repositoryName) / \(worktreeDisplayName)"
+  }
 }
 
 private func pullRequestItems(
@@ -465,6 +630,7 @@ private enum CommandPaletteItemID {
   static let globalCheckForUpdates = "global.check-for-updates"
   static let globalOpenSettings = "global.open-settings"
   static let globalOpenRepository = "global.open-repository"
+  static let globalAddRemoteRepository = "global.add-remote-repository"
   static let globalNewWorktree = "global.new-worktree"
   static let globalRefreshWorktrees = "global.refresh-worktrees"
   static let globalViewArchivedWorktrees = "global.view-archived-worktrees"
@@ -474,6 +640,7 @@ private enum CommandPaletteItemID {
       globalCheckForUpdates,
       globalOpenSettings,
       globalOpenRepository,
+      globalAddRemoteRepository,
       globalNewWorktree,
       globalRefreshWorktrees,
       globalViewArchivedWorktrees,
@@ -590,6 +757,8 @@ private func delegateAction(for kind: CommandPaletteItem.Kind) -> CommandPalette
     return .newWorktree
   case .openRepository:
     return .openRepository
+  case .addRemoteRepository:
+    return .addRemoteRepository
   case .removeWorktree(let worktreeID, let repositoryID):
     return .removeWorktree(worktreeID, repositoryID)
   case .archiveWorktree(let worktreeID, let repositoryID):
@@ -611,10 +780,8 @@ private func delegateAction(for kind: CommandPaletteItem.Kind) -> CommandPalette
     .rerunFailedJobs,
     .openFailingCheckDetails:
     return pullRequestDelegateAction(for: kind)!
-  case .runScript(let definition):
-    return .runScript(definition)
-  case .stopScript(let scriptID, let name):
-    return .stopScript(scriptID, name: name)
+  case .runScript, .stopScript:
+    return scriptDelegateAction(for: kind)!
   #if DEBUG
     case .debugTestToast(let toast):
       return .debugTestToast(toast)
@@ -622,6 +789,19 @@ private func delegateAction(for kind: CommandPaletteItem.Kind) -> CommandPalette
   }
 }
 
+private func scriptDelegateAction(
+  for kind: CommandPaletteItem.Kind
+) -> CommandPaletteFeature.Delegate? {
+  switch kind {
+  case .runScript(let definition):
+    return .runScript(definition)
+  case .stopScript(let scriptID, let name):
+    return .stopScript(scriptID, name: name)
+  default:
+    return nil
+  }
+}
+
 private func pullRequestDelegateAction(
   for kind: CommandPaletteItem.Kind
 ) -> CommandPaletteFeature.Delegate? {
@@ -647,6 +827,7 @@ private func pullRequestDelegateAction(
     .openSettings,
     .newWorktree,
     .openRepository,
+    .addRemoteRepository,
     .removeWorktree,
     .archiveWorktree,
     .renameBranch,
diff --git a/supacode/Features/CommandPalette/Views/CommandPaletteOverlayView.swift b/supacode/Features/CommandPalette/Views/CommandPaletteOverlayView.swift
index 912ba7399..f276c4507 100644
--- a/supacode/Features/CommandPalette/Views/CommandPaletteOverlayView.swift
+++ b/supacode/Features/CommandPalette/Views/CommandPaletteOverlayView.swift
@@ -35,6 +35,7 @@ struct CommandPaletteOverlayView: View {
                 query: $store.query,
                 selectedIndex: $store.selectedIndex,
                 items: filteredItems,
+                placeholder: queryPlaceholder,
                 hoveredID: $hoveredID,
                 isQueryFocused: _isQueryFocused,
                 onEvent: { event in
@@ -95,11 +96,37 @@ struct CommandPaletteOverlayView: View {
   }
 
   private func updateSelection(rows: [CommandPaletteItem]) {
-    store.send(.updateSelection(itemsCount: rows.count))
+    store.send(.updateSelection(itemsCount: rows.count, defaultIndex: defaultSelectionIndex(rows: rows)))
   }
 
   private func resetSelection(rows: [CommandPaletteItem]) {
-    store.send(.resetSelection(itemsCount: rows.count))
+    store.send(.resetSelection(itemsCount: rows.count, defaultIndex: defaultSelectionIndex(rows: rows)))
+  }
+
+  /// Query-field placeholder, matched to the active surface. The worktree
+  /// switcher (⌘P) only navigates to worktrees, so it must not promise
+  /// "actions"; the full command palette (⌘⇧P) keeps the actions-and-branches
+  /// wording.
+  private var queryPlaceholder: String {
+    switch store.mode {
+    case .worktreeSwitcher:
+      return "Go to worktree…"
+    case .commands:
+      return "Search for actions or branches…"
+    }
+  }
+
+  /// Where the cursor lands when there's no prior selection. Normally the
+  /// top row, but the worktree switcher skips its own current-worktree row
+  /// (rendered at index 0 with an empty query) so ⌘P then Enter switches
+  /// to the previous worktree instead of being a no-op. Once the user types,
+  /// the fuzzy-ranked top match wins again.
+  private func defaultSelectionIndex(rows: [CommandPaletteItem]) -> Int {
+    let trimmedQuery = store.query.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard trimmedQuery.isEmpty, rows.count > 1, rows.first?.isCurrentWorktree == true else {
+      return 0
+    }
+    return 1
   }
 
   private func moveSelection(_ direction: MoveCommandDirection, rows: [CommandPaletteItem]) {
@@ -140,6 +167,7 @@ struct CommandPaletteOverlayView: View {
     let updatedItems = CommandPaletteFeature.filterItems(
       items: items,
       query: store.query,
+      mode: store.mode,
       recencyByID: store.recencyByItemID,
       now: now
     )
@@ -154,6 +182,7 @@ private struct CommandPaletteCard: View {
   @Binding var query: String
   @Binding var selectedIndex: Int?
   let items: [CommandPaletteItem]
+  let placeholder: String
   @Binding var hoveredID: CommandPaletteItem.ID?
   let isQueryFocused: FocusState<Bool>
   let onEvent: (CommandPaletteKeyboardEvent) -> Void
@@ -165,7 +194,7 @@ private struct CommandPaletteCard: View {
 
   var body: some View {
     VStack(alignment: .leading, spacing: 0) {
-      CommandPaletteQuery(query: $query, isTextFieldFocused: isQueryFocused) { event in
+      CommandPaletteQuery(query: $query, placeholder: placeholder, isTextFieldFocused: isQueryFocused) { event in
         onEvent(event)
       }
 
@@ -213,15 +242,18 @@ private struct CommandPaletteQuery: View {
   static let fieldHeight: CGFloat = 48
 
   @Binding var query: String
+  let placeholder: String
   var onEvent: ((CommandPaletteKeyboardEvent) -> Void)?
   @FocusState private var isTextFieldFocused: Bool
 
   init(
     query: Binding<String>,
+    placeholder: String,
     isTextFieldFocused: FocusState<Bool>,
     onEvent: ((CommandPaletteKeyboardEvent) -> Void)? = nil
   ) {
     _query = query
+    self.placeholder = placeholder
     self.onEvent = onEvent
     _isTextFieldFocused = isTextFieldFocused
   }
@@ -262,7 +294,7 @@ private struct CommandPaletteQuery: View {
       .frame(width: 0, height: 0)
       .accessibilityHidden(true)
 
-      TextField("Search for actions or branches...", text: $query)
+      TextField(placeholder, text: $query)
         .padding()
         .font(.title3.weight(.light))
         .frame(height: Self.fieldHeight)
@@ -336,7 +368,8 @@ private struct CommandPaletteRowView: View {
 
   private var badge: String? {
     switch row.kind {
-    case .checkForUpdates, .openRepository, .openSettings, .newWorktree, .viewArchivedWorktrees,
+    case .checkForUpdates, .openRepository, .addRemoteRepository, .openSettings, .newWorktree,
+      .viewArchivedWorktrees,
       .refreshWorktrees,
       .ghosttyCommand,
       .openPullRequest, .markPullRequestReady, .mergePullRequest, .closePullRequest, .copyFailingJobURL,
@@ -366,6 +399,8 @@ private struct CommandPaletteRowView: View {
       return "arrow.down.circle"
     case .openRepository:
       return "folder"
+    case .addRemoteRepository:
+      return "wifi"
     case .openSettings:
       return "gearshape"
     case .newWorktree:
@@ -413,7 +448,8 @@ private struct CommandPaletteRowView: View {
 
   private var emphasis: Bool {
     switch row.kind {
-    case .checkForUpdates, .openRepository, .openSettings, .newWorktree, .viewArchivedWorktrees,
+    case .checkForUpdates, .openRepository, .addRemoteRepository, .openSettings, .newWorktree,
+      .viewArchivedWorktrees,
       .refreshWorktrees,
       .ghosttyCommand,
       .openPullRequest, .markPullRequestReady, .mergePullRequest, .closePullRequest, .copyFailingJobURL,
@@ -510,6 +546,8 @@ private struct CommandPaletteRowView: View {
       base = "Check for Updates"
     case .openRepository:
       base = "Open Repository or Folder"
+    case .addRemoteRepository:
+      base = "Add Remote Repository"
     case .openSettings:
       base = "Open Settings"
     case .newWorktree:
diff --git a/supacode/Features/Repositories/BusinessLogic/SidebarPersistenceKey.swift b/supacode/Features/Repositories/BusinessLogic/SidebarPersistenceKey.swift
index b440d9cf7..0196d5a99 100644
--- a/supacode/Features/Repositories/BusinessLogic/SidebarPersistenceKey.swift
+++ b/supacode/Features/Repositories/BusinessLogic/SidebarPersistenceKey.swift
@@ -102,7 +102,7 @@ nonisolated struct SidebarKey: SharedKey {
         directoryHint: .notDirectory
       )
     do {
-      try fileManager.moveItem(at: url, to: destination)
+      try SymlinkPreservingFileWriter.moveAside(at: url, to: destination)
     } catch {
       Self.logger.warning(
         """
@@ -134,6 +134,12 @@ nonisolated struct SidebarKey: SharedKey {
       try storage.save(data, url)
       continuation.resume()
     } catch {
+      // The Sharing save path does not surface this to the UI, so log it:
+      // a symlinked sidebar.json into a cycle or missing dir would otherwise
+      // fail every save silently.
+      Self.logger.error(
+        "Failed to persist sidebar state to \(url.path(percentEncoded: false)): \(error)"
+      )
       continuation.resume(throwing: error)
     }
   }
diff --git a/supacode/Features/Repositories/BusinessLogic/SidebarPersistenceMigrator.swift b/supacode/Features/Repositories/BusinessLogic/SidebarPersistenceMigrator.swift
index d19321896..e8542e3f5 100644
--- a/supacode/Features/Repositories/BusinessLogic/SidebarPersistenceMigrator.swift
+++ b/supacode/Features/Repositories/BusinessLogic/SidebarPersistenceMigrator.swift
@@ -123,7 +123,7 @@ enum SidebarPersistenceMigrator {
 
     @Dependency(\.date.now) var now
     let legacyRoots = RepositoryPathNormalizer.normalize(settingsFile.repositoryRoots)
-    let legacyPinnedSet = Set(RepositoryPathNormalizer.normalize(settingsFile.pinnedWorktreeIDs))
+    let legacyPinnedSet = Set(RepositoryPathNormalizer.normalize(settingsFile.pinnedWorktreeIDs).map { WorktreeID($0) })
     // Merge the pre-#214 ID list into the dated dictionary view
     // BEFORE the fold pass so both sources land in the same
     // `SidebarState.archived` bucket in one shot. `Date.now` matches
@@ -165,7 +165,7 @@ enum SidebarPersistenceMigrator {
     applyCollapsedFlags(into: &state, legacyCollapsed: legacyCollapsed)
     foldArchived(into: &state, legacyArchived: mergedArchived, rootCandidates: candidates)
 
-    state.focusedWorktreeID = legacyFocus.flatMap(RepositoryPathNormalizer.normalize)
+    state.focusedWorktreeID = legacyFocus.flatMap(RepositoryPathNormalizer.normalize).map { WorktreeID($0) }
 
     guard persist(state: state, to: sidebarURL) else {
       return
@@ -202,7 +202,7 @@ enum SidebarPersistenceMigrator {
       Migrated sidebar state: \(state.sections.count) section(s), \
       \(legacyPinnedSet.count) pinned worktree(s), \
       \(mergedArchived.count) archived worktree(s), \
-      focus=\(state.focusedWorktreeID ?? "nil").
+      focus=\(state.focusedWorktreeID?.rawValue ?? "nil").
       """
     )
   }
@@ -301,8 +301,11 @@ enum SidebarPersistenceMigrator {
     legacyPinnedSet: Set<Worktree.ID>
   ) {
     // Canonical baseline: every known root, in settings order.
-    for root in legacyRoots where state.sections[root] == nil {
-      state.sections[root] = .init()
+    for root in legacyRoots {
+      let id = RepositoryID(root)
+      if state.sections[id] == nil {
+        state.sections[id] = .init()
+      }
     }
     // Override layer: `legacyOrder` wins — pull matching roots to
     // the top in the order the user curated. Roots present in
@@ -311,9 +314,10 @@ enum SidebarPersistenceMigrator {
     var reordered: OrderedDictionary<Repository.ID, SidebarState.Section> = [:]
     var seen: Set<Repository.ID> = []
     for raw in legacyOrder {
-      guard let id = RepositoryPathNormalizer.normalize(raw) else {
+      guard let normalized = RepositoryPathNormalizer.normalize(raw) else {
         continue
       }
+      let id = RepositoryID(normalized)
       guard seen.insert(id).inserted else {
         continue
       }
@@ -325,13 +329,15 @@ enum SidebarPersistenceMigrator {
     state.sections = reordered
 
     for (rawRepoID, worktreeIDs) in legacyWorktreeOrder {
-      guard let repoID = RepositoryPathNormalizer.normalize(rawRepoID) else {
+      guard let normalizedRepoID = RepositoryPathNormalizer.normalize(rawRepoID) else {
         continue
       }
+      let repoID = RepositoryID(normalizedRepoID)
       for rawWorktreeID in worktreeIDs {
-        guard let worktreeID = RepositoryPathNormalizer.normalize(rawWorktreeID) else {
+        guard let normalizedWorktreeID = RepositoryPathNormalizer.normalize(rawWorktreeID) else {
           continue
         }
+        let worktreeID = WorktreeID(normalizedWorktreeID)
         let bucketID: SidebarState.BucketID =
           legacyPinnedSet.contains(worktreeID) ? .pinned : .unpinned
         state.insert(worktree: worktreeID, in: repoID, bucket: bucketID)
@@ -382,9 +388,10 @@ enum SidebarPersistenceMigrator {
     legacyCollapsed: [String]
   ) {
     for raw in legacyCollapsed {
-      guard let id = RepositoryPathNormalizer.normalize(raw) else {
+      guard let normalized = RepositoryPathNormalizer.normalize(raw) else {
         continue
       }
+      let id = RepositoryID(normalized)
       var section = state.sections[id] ?? .init()
       section.collapsed = true
       state.sections[id] = section
@@ -403,9 +410,10 @@ enum SidebarPersistenceMigrator {
   ) {
     var unplacedArchivedIDs: [Worktree.ID] = []
     for (rawArchivedID, archivedAt) in legacyArchived {
-      guard let archivedWorktreeID = RepositoryPathNormalizer.normalize(rawArchivedID) else {
+      guard let normalizedArchivedID = RepositoryPathNormalizer.normalize(rawArchivedID) else {
         continue
       }
+      let archivedWorktreeID = WorktreeID(normalizedArchivedID)
       let owningRepoID =
         state.sections.first(where: { _, section in
           section.buckets.values.contains(where: { $0.items[archivedWorktreeID] != nil })
@@ -459,6 +467,263 @@ enum SidebarPersistenceMigrator {
     }
   }
 
+  // MARK: - Remote-identity migration (schema v1 -> v2).
+
+  /// Target sidebar schema for the remote-identity refactor.
+  private static let remoteIdentitySchemaVersion = 2
+
+  /// Decode-only view of the retired `global.remoteRepositories` array. The
+  /// stored property is gone from `GlobalSettings`, so the legacy entries are
+  /// read straight from the raw `settings.json`; `id` / `displayName` are dropped.
+  private nonisolated struct LegacyRemoteRepositoriesFile: Decodable {
+    var remoteRepositories: [LegacyRemoteRepository]?
+
+    enum RootKeys: String, CodingKey { case global }
+    enum GlobalKeys: String, CodingKey { case remoteRepositories }
+
+    init(from decoder: any Decoder) throws {
+      let root = try decoder.container(keyedBy: RootKeys.self)
+      guard root.contains(.global) else {
+        remoteRepositories = nil
+        return
+      }
+      let global = try root.nestedContainer(keyedBy: GlobalKeys.self, forKey: .global)
+      // Per-element lossy so one malformed entry doesn't strand every other remote
+      // repo on this one-shot drain.
+      remoteRepositories = global.decodeLossyArrayIfPresent(forKey: .remoteRepositories)
+    }
+  }
+
+  private nonisolated struct LegacyRemoteRepository: Decodable, Sendable {
+    var host: RemoteHost
+    var remotePath: String
+  }
+
+  /// Outcome of reading the retired `global.remoteRepositories` from the raw
+  /// `settings.json` before any settings save can drop the field.
+  enum LegacyRemoteCapture: Equatable {
+    /// Nothing to migrate: `settings.json` is absent or decoded with no legacy
+    /// remotes.
+    case none
+    /// Self-descriptive ids derived from the legacy configs, ready to drain.
+    case roots([String])
+    /// `settings.json` is present but unreadable / undecodable. A transient
+    /// error, NOT "no data": the caller must abort and retry next launch so a
+    /// later save can't strip the field before it is drained.
+    case unreadable
+  }
+
+  /// Read and derive the retired remote ids from the raw `settings.json`. MUST
+  /// run before `migrateIfNeeded` (or any settings save): the first save drops
+  /// `remoteRepositories`, so it's only recoverable off disk until then.
+  static func captureLegacyRemoteRoots(
+    fileExists: (URL) -> Bool = { url in
+      FileManager.default.fileExists(atPath: url.path(percentEncoded: false))
+    },
+    readFile: (URL) -> Data? = { url in
+      try? Data(contentsOf: url)
+    }
+  ) -> LegacyRemoteCapture {
+    guard fileExists(SupacodePaths.settingsURL) else { return .none }
+    guard let data = readFile(SupacodePaths.settingsURL),
+      let legacy = try? JSONDecoder().decode(LegacyRemoteRepositoriesFile.self, from: data)
+    else {
+      return .unreadable
+    }
+    guard let configs = legacy.remoteRepositories, !configs.isEmpty else { return .none }
+    return .roots(
+      configs.map { config in
+        RepositoryLocation.remote(
+          config.host, path: RepositoryLocation.normalizedRemotePath(config.remotePath)
+        ).id.rawValue
+      }
+    )
+  }
+
+  /// Suffix for the one-shot pre-migration snapshot.
+  static let preMigrationBackupSuffix = ".pre-remote-id-migration.bak"
+
+  /// Snapshot `settings.json` + `sidebar.json` (raw) once before any migration or
+  /// `@Shared(.settingsFile)` hydration can rewrite them, so a botched migration or
+  /// a downgrade is recoverable by hand. No-op once migrated or a snapshot exists.
+  @MainActor
+  static func backupBeforeRemoteIdentityMigration(
+    fileExists: (URL) -> Bool = { url in
+      FileManager.default.fileExists(atPath: url.path(percentEncoded: false))
+    },
+    readFile: (URL) -> Data? = { url in
+      try? Data(contentsOf: url)
+    }
+  ) {
+    let sidebarURL = SupacodePaths.sidebarURL
+    // Already migrated: nothing pre-migration left to snapshot. An unreadable /
+    // absent sidebar is treated as "pending" so the snapshot still runs.
+    if let data = readFile(sidebarURL),
+      let sidebar = try? JSONDecoder().decode(SidebarState.self, from: data),
+      sidebar.schemaVersion >= remoteIdentitySchemaVersion
+    {
+      return
+    }
+    @Dependency(\.settingsFileStorage) var storage
+    for url in [SupacodePaths.settingsURL, sidebarURL] {
+      let backupURL = url.deletingLastPathComponent()
+        .appendingPathComponent(url.lastPathComponent + preMigrationBackupSuffix)
+      // Snapshot once: never overwrite an existing snapshot with post-migration data.
+      guard !fileExists(backupURL), let data = readFile(url) else { continue }
+      do {
+        try storage.save(data, backupURL)
+      } catch {
+        logger.warning("Failed to write pre-migration backup \(backupURL.lastPathComponent): \(error)")
+      }
+    }
+  }
+
+  /// One-shot migration for the remote-identity refactor. Drains the legacy
+  /// remotes captured by `captureLegacyRemoteRoots` into `remoteRepositoryRoots`,
+  /// then strips the retired `remote://` / `folder:` prefixes from every
+  /// persisted id (`repositories` keys, `pinnedWorktreeIDs`, and `sidebar.json`).
+  /// Gated on the sidebar `schemaVersion`; once it reaches `2` this is a no-op.
+  /// Runs after `migrateIfNeeded` so the v0 -> v1 build has already landed.
+  @MainActor
+  static func migrateRemoteIdentityIfNeeded(
+    capturedLegacy: LegacyRemoteCapture,
+    fileExists: (URL) -> Bool = { url in
+      FileManager.default.fileExists(atPath: url.path(percentEncoded: false))
+    },
+    readFile: (URL) -> Data? = { url in
+      try? Data(contentsOf: url)
+    }
+  ) {
+    // Couldn't read settings.json this launch: don't stamp the schema (which
+    // would gate the migration out forever) before the legacy field is drained.
+    if capturedLegacy == .unreadable { return }
+
+    // Drain before any sidebar gate: the captured remotes live only in the
+    // soon-stripped settings.json. Idempotent; capture returns `.none` once saved.
+    if case .roots(let ids) = capturedLegacy {
+      @Shared(.remoteRepositoryRoots) var remoteRepositoryRoots
+      $remoteRepositoryRoots.withLock { roots in
+        for id in ids where !roots.contains(id) {
+          roots.append(id)
+        }
+      }
+    }
+
+    let sidebarURL = SupacodePaths.sidebarURL
+    let sidebarPresent = fileExists(sidebarURL)
+    let sidebarData = sidebarPresent ? readFile(sidebarURL) : nil
+    // Present but unreadable / undecodable: overwriting with empty would drop the
+    // layout and stamp the schema so it never retries. Only a truly absent file proceeds.
+    if sidebarPresent, sidebarData == nil { return }
+    let existing = sidebarData.flatMap { try? JSONDecoder().decode(SidebarState.self, from: $0) }
+    if sidebarData != nil, existing == nil { return }
+    guard (existing?.schemaVersion ?? 0) < remoteIdentitySchemaVersion else { return }
+
+    @Shared(.settingsFile) var settingsFile
+    $settingsFile.withLock { settings in
+      // Re-key per-repo settings (color / custom name) and any leftover pins off
+      // the retired prefixes so they keep matching the live ids.
+      var rekeyedRepositories: [String: RepositorySettings] = [:]
+      for (key, value) in settings.repositories {
+        let migrated = stripLegacyIDPrefixes(key)
+        if rekeyedRepositories[migrated] == nil {
+          rekeyedRepositories[migrated] = value
+        }
+      }
+      settings.repositories = rekeyedRepositories
+      settings.pinnedWorktreeIDs = settings.pinnedWorktreeIDs.map(stripLegacyIDPrefixes)
+    }
+
+    // A present-but-unreadable layouts.json would orphan its keys; bail so the
+    // whole pass retries next launch rather than stamping the schema past it.
+    guard rekeyLegacyLayouts(fileExists: fileExists, readFile: readFile) else { return }
+
+    var state = existing ?? SidebarState()
+    rekeyToRemoteIdentitySchema(&state)
+    guard persist(state: state, to: sidebarURL) else { return }
+    logger.info("Migrated remote/folder ids to schema v\(remoteIdentitySchemaVersion).")
+  }
+
+  /// Re-key `layouts.json` (terminal snapshots keyed by worktree id) off the retired
+  /// prefixes so remote/folder tabs still restore. Returns `false` when a present file
+  /// can't be read/written, so the caller bails and retries. Written directly because
+  /// `LayoutsKey.save` is a no-op.
+  @MainActor
+  private static func rekeyLegacyLayouts(fileExists: (URL) -> Bool, readFile: (URL) -> Data?) -> Bool {
+    let layoutsURL = SupacodePaths.layoutsURL
+    guard fileExists(layoutsURL) else { return true }
+    guard let data = readFile(layoutsURL),
+      let layouts = try? JSONDecoder().decode([String: TerminalLayoutSnapshot].self, from: data)
+    else {
+      logger.warning("Layout re-key deferred: layouts.json present but unreadable.")
+      return false
+    }
+    var rekeyed: [String: TerminalLayoutSnapshot] = [:]
+    var changed = false
+    for (key, value) in layouts {
+      let migrated = stripLegacyIDPrefixes(key)
+      if migrated != key { changed = true }
+      if rekeyed[migrated] == nil { rekeyed[migrated] = value }
+    }
+    guard changed else { return true }
+    do {
+      @Dependency(\.settingsFileStorage) var storage
+      let encoder = JSONEncoder()
+      encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+      try storage.save(try encoder.encode(rekeyed), layoutsURL)
+      return true
+    } catch {
+      logger.warning("Layout re-key deferred: failed to write layouts.json: \(error)")
+      return false
+    }
+  }
+
+  /// Strip the retired `folder:` then `remote://` prefixes from an id. Composed
+  /// folder-remote ids (`folder:remote://…`) collapse in one pass.
+  static func stripLegacyIDPrefixes(_ id: String) -> String {
+    var result = id
+    if result.hasPrefix("folder:") {
+      result = String(result.dropFirst("folder:".count))
+    }
+    if result.hasPrefix("remote://") {
+      result = String(result.dropFirst("remote://".count))
+    }
+    return result
+  }
+
+  /// Rewrite every persisted id in `state` off the retired prefixes and stamp
+  /// the remote-identity schema version. Section keys (repo ids) and item keys
+  /// (worktree ids) both pass through `stripLegacyIDPrefixes`; collisions keep
+  /// the first entry (a folder synthetic and a git worktree can't legitimately
+  /// share a bucket).
+  private static func rekeyToRemoteIdentitySchema(_ state: inout SidebarState) {
+    var rekeyedSections: OrderedDictionary<Repository.ID, SidebarState.Section> = [:]
+    for (repoID, section) in state.sections {
+      var rekeyedSection = section
+      var rekeyedBuckets: OrderedDictionary<SidebarState.BucketID, SidebarState.Bucket> = [:]
+      for (bucketID, bucket) in section.buckets {
+        var rekeyedItems: OrderedDictionary<Worktree.ID, SidebarState.Item> = [:]
+        for (worktreeID, item) in bucket.items {
+          let migrated = WorktreeID(stripLegacyIDPrefixes(worktreeID.rawValue))
+          if rekeyedItems[migrated] == nil {
+            rekeyedItems[migrated] = item
+          }
+        }
+        var rekeyedBucket = bucket
+        rekeyedBucket.items = rekeyedItems
+        rekeyedBuckets[bucketID] = rekeyedBucket
+      }
+      rekeyedSection.buckets = rekeyedBuckets
+      let migratedRepoID = RepositoryID(stripLegacyIDPrefixes(repoID.rawValue))
+      if rekeyedSections[migratedRepoID] == nil {
+        rekeyedSections[migratedRepoID] = rekeyedSection
+      }
+    }
+    state.sections = rekeyedSections
+    state.focusedWorktreeID = state.focusedWorktreeID.map { WorktreeID(stripLegacyIDPrefixes($0.rawValue)) }
+    state.schemaVersion = remoteIdentitySchemaVersion
+  }
+
   /// Pool of (candidate-prefix → owning-root) pairs used by the
   /// longest-prefix resolver. Covers every filesystem location a
   /// worktree may sit under:
@@ -569,13 +834,13 @@ enum SidebarPersistenceMigrator {
       // directory; the trailing slash guards against a spurious
       // match where one candidate is a non-directory prefix of
       // another (e.g. "/tmp/rep" vs "/tmp/repo").
-      guard worktreeID.hasPrefix(candidateWithLeadingSlash + "/") else {
+      guard worktreeID.rawValue.hasPrefix(candidateWithLeadingSlash + "/") else {
         continue
       }
       if candidateWithLeadingSlash.count > (bestMatch?.length ?? 0) {
         bestMatch = (owningRoot, candidateWithLeadingSlash.count)
       }
     }
-    return bestMatch?.owningRoot
+    return bestMatch.map { RepositoryID($0.owningRoot) }
   }
 }
diff --git a/supacode/Features/Repositories/BusinessLogic/SidebarState.swift b/supacode/Features/Repositories/BusinessLogic/SidebarState.swift
index e3737318c..708855088 100644
--- a/supacode/Features/Repositories/BusinessLogic/SidebarState.swift
+++ b/supacode/Features/Repositories/BusinessLogic/SidebarState.swift
@@ -185,6 +185,44 @@ nonisolated struct SidebarState: Equatable, Sendable, Codable {
     /// item leaves `.archived`, so the field is a reliable "is this
     /// currently archived?" signal without a bucket check.
     var archivedAt: Date?
+    /// Optional user-supplied display title that overrides the
+    /// worktree's branch / folder name in the sidebar row. `nil` (or
+    /// whitespace-only after trim) means "use the default name".
+    var title: String?
+    /// Optional user-supplied tint applied to the sidebar row title.
+    /// `nil` means "default styling".
+    var color: RepositoryColor?
+
+    private enum CodingKeys: String, CodingKey {
+      case archivedAt
+      case title
+      case color
+    }
+
+    init(archivedAt: Date? = nil, title: String? = nil, color: RepositoryColor? = nil) {
+      self.archivedAt = archivedAt
+      self.title = title
+      self.color = color
+    }
+
+    init(from decoder: any Decoder) throws {
+      let container = try decoder.container(keyedBy: CodingKeys.self)
+      self.archivedAt = try container.decodeIfPresent(Date.self, forKey: .archivedAt)
+      self.title = try container.decodeIfPresent(String.self, forKey: .title)
+      // Use `try?` so a malformed hex color (introduced by a downgrade
+      // that doesn't understand `.custom`, hand-edit, etc.) drops just
+      // this field rather than killing the row's entire entry.
+      self.color = (try? container.decodeIfPresent(RepositoryColor.self, forKey: .color)) ?? nil
+    }
+
+    func encode(to encoder: any Encoder) throws {
+      var container = encoder.container(keyedBy: CodingKeys.self)
+      try container.encodeIfPresent(archivedAt, forKey: .archivedAt)
+      // Customization fields are only emitted when set so the file
+      // stays clean for worktrees the user never touched.
+      try container.encodeIfPresent(title, forKey: .title)
+      try container.encodeIfPresent(color, forKey: .color)
+    }
   }
 
   /// Flat reference to an archived worktree: the owning repo, the
@@ -295,6 +333,48 @@ nonisolated extension SidebarState {
     sections[repositoryID] = section
   }
 
+  /// Merge a user-supplied title / color into whatever bucket already holds the row, falling back
+  /// to `.unpinned` when the row hasn't been seeded yet. Pre-existing non-nil fields on the
+  /// bucketed Item win, so a re-seed never clobbers a manual customization. Used by the
+  /// post-create and discovered-worktree seed sites so a persisted `.pinned` Item never gets
+  /// manufactured into a phantom double-bucket row.
+  mutating func mergeCustomization(
+    title: String?,
+    color: RepositoryColor?,
+    worktree worktreeID: Worktree.ID,
+    in repositoryID: Repository.ID
+  ) {
+    let destinationBucket = currentBucket(of: worktreeID, in: repositoryID) ?? .unpinned
+    var section = sections[repositoryID] ?? .init()
+    var bucket = section.buckets[destinationBucket] ?? .init()
+    var item = bucket.items[worktreeID] ?? .init()
+    if item.title == nil { item.title = title }
+    if item.color == nil { item.color = color }
+    bucket.items[worktreeID] = item
+    section.buckets[destinationBucket] = bucket
+    sections[repositoryID] = section
+  }
+
+  /// Overwrite a row's user-supplied title / color, falling back to `.unpinned` when the row
+  /// hasn't been seeded yet. Unlike `mergeCustomization`, the incoming values always win, since
+  /// this represents an explicit user save intent that must not be silently absorbed.
+  mutating func setCustomization(
+    title: String?,
+    color: RepositoryColor?,
+    worktree worktreeID: Worktree.ID,
+    in repositoryID: Repository.ID
+  ) {
+    let destinationBucket = currentBucket(of: worktreeID, in: repositoryID) ?? .unpinned
+    var section = sections[repositoryID] ?? .init()
+    var bucket = section.buckets[destinationBucket] ?? .init()
+    var item = bucket.items[worktreeID] ?? .init()
+    item.title = title
+    item.color = color
+    bucket.items[worktreeID] = item
+    section.buckets[destinationBucket] = bucket
+    sections[repositoryID] = section
+  }
+
   /// Archive `worktreeID`: drop from `from`, insert into `.archived`
   /// at the tail with the given timestamp. Materialises the section
   /// and the archived bucket when missing so a late-arriving
@@ -307,9 +387,12 @@ nonisolated extension SidebarState {
     at timestamp: Date
   ) {
     var section = sections[repositoryID] ?? .init()
-    section.buckets[from]?.items.removeValue(forKey: worktreeID)
+    // Carry the source-bucket Item forward so user-set title / color survive
+    // archive; fall back to a fresh Item when the source bucket didn't hold it.
+    var carried = section.buckets[from]?.items.removeValue(forKey: worktreeID) ?? .init()
+    carried.archivedAt = timestamp
     var archived = section.buckets[.archived] ?? .init()
-    archived.items[worktreeID] = .init(archivedAt: timestamp)
+    archived.items[worktreeID] = carried
     section.buckets[.archived] = archived
     sections[repositoryID] = section
   }
@@ -334,15 +417,39 @@ nonisolated extension SidebarState {
 
   /// Remove `worktreeID` from every bucket of `repositoryID`. Used
   /// by the delete flow (the worktree is going away entirely, so
-  /// we don't need to know which bucket currently owns it). O(1)
-  /// — exactly three bucket subscripts, no scan.
-  mutating func removeAnywhere(worktree worktreeID: Worktree.ID, in repositoryID: Repository.ID) {
+  /// we don't need to know which bucket currently owns it) and by
+  /// pin / unpin (which collapse any pre-existing multi-bucket state
+  /// before reinserting). Returns the first found Item in
+  /// `preferring` order so callers that reinsert (pin / unpin) can
+  /// carry user-set `title` / `color` forward; pass the logical
+  /// source bucket first (e.g. `.pinned` for unpin) so a corrupted
+  /// double-bucket pre-state preserves the live row's payload rather
+  /// than a stale sibling's. Default order matches the typical
+  /// "where would a curated row live" search. O(1): exactly three
+  /// bucket subscripts, no scan.
+  @discardableResult
+  mutating func removeAnywhere(
+    worktree worktreeID: Worktree.ID,
+    in repositoryID: Repository.ID,
+    preferring: [BucketID] = [.unpinned, .pinned, .archived]
+  ) -> Item? {
     guard sections[repositoryID] != nil else {
-      return
+      return nil
+    }
+    // Remove from every bucket (the "removeAnywhere" contract); the
+    // `preferring` order only determines which carried Item we
+    // return. Buckets outside `preferring` are still purged but
+    // their payload is discarded.
+    var removed: [BucketID: Item] = [:]
+    for bucketID in [BucketID.pinned, .unpinned, .archived] {
+      if let item = sections[repositoryID]?.buckets[bucketID]?.items.removeValue(forKey: worktreeID) {
+        removed[bucketID] = item
+      }
     }
-    sections[repositoryID]?.buckets[.pinned]?.items.removeValue(forKey: worktreeID)
-    sections[repositoryID]?.buckets[.unpinned]?.items.removeValue(forKey: worktreeID)
-    sections[repositoryID]?.buckets[.archived]?.items.removeValue(forKey: worktreeID)
+    for bucketID in preferring {
+      if let item = removed[bucketID] { return item }
+    }
+    return nil
   }
 
   /// Reorder `bucketID`'s items in `repositoryID` to exactly
diff --git a/supacode/Features/Repositories/BusinessLogic/SidebarStructure.swift b/supacode/Features/Repositories/BusinessLogic/SidebarStructure.swift
index c73aa8551..041b98f20 100644
--- a/supacode/Features/Repositories/BusinessLogic/SidebarStructure.swift
+++ b/supacode/Features/Repositories/BusinessLogic/SidebarStructure.swift
@@ -160,6 +160,33 @@ struct SidebarItemGroup: Identifiable, Equatable, Sendable {
   }
 }
 
+/// Per-repo tally of rows hoisted into the highlight sections, surfaced as a
+/// muted summary line at the bottom of the repo section so a hoisted row stays
+/// discoverable from its origin repo without rendering a duplicate. `revealTarget`
+/// is the row a click scrolls to: the repo's first pinned hoist, else its first
+/// active hoist.
+struct SidebarHoistSummary: Equatable, Sendable {
+  let pinnedCount: Int
+  let activeCount: Int
+  let revealTarget: Worktree.ID
+
+  /// Nil when neither bucket has a row, so a `(0, 0)` summary is unrepresentable.
+  init?(pinnedCount: Int, activeCount: Int, revealTarget: Worktree.ID) {
+    guard pinnedCount > 0 || activeCount > 0 else { return nil }
+    self.pinnedCount = pinnedCount
+    self.activeCount = activeCount
+    self.revealTarget = revealTarget
+  }
+
+  /// Spoken VoiceOver form, pinned before active, omitting a zero bucket.
+  var label: String {
+    var parts: [String] = []
+    if pinnedCount > 0 { parts.append("+\(pinnedCount) \(SidebarStructure.HighlightKind.pinned.summaryNoun)") }
+    if activeCount > 0 { parts.append("+\(activeCount) \(SidebarStructure.HighlightKind.active.summaryNoun)") }
+    return parts.joined(separator: ", ")
+  }
+}
+
 /// Single source of truth for what the sidebar List renders. The reducer
 /// builds it once per `recomputeSidebarStructure()` and caches it on
 /// `RepositoriesFeature.State.sidebarStructure`; the view walks `sections`
@@ -175,6 +202,14 @@ struct SidebarStructure: Equatable, Sendable {
       case .active: "Active"
       }
     }
+
+    /// Lowercase noun used in the per-repo hoist summary line.
+    var summaryNoun: String {
+      switch self {
+      case .pinned: "pinned"
+      case .active: "active"
+      }
+    }
   }
 
   enum Section: Equatable, Sendable, Identifiable {
@@ -185,7 +220,8 @@ struct SidebarStructure: Equatable, Sendable {
       repositoryID: Repository.ID,
       rootURL: URL,
       customTitle: String?,
-      color: RepositoryColor?
+      color: RepositoryColor?,
+      isRemote: Bool
     )
     case placeholder
 
@@ -194,7 +230,7 @@ struct SidebarStructure: Equatable, Sendable {
       case .highlight(let kind, _): .highlight(kind)
       case .repository(let repositoryID, _): .repository(repositoryID)
       case .folder(let repositoryID, _): .folder(repositoryID)
-      case .failedRepository(let repositoryID, _, _, _): .failedRepository(repositoryID)
+      case .failedRepository(let repositoryID, _, _, _, _): .failedRepository(repositoryID)
       case .placeholder: .placeholder
       }
     }
@@ -222,6 +258,9 @@ struct SidebarStructure: Equatable, Sendable {
   /// subtitle on highlight rows. Built only for repos that contributed at
   /// least one row to the highlight sections.
   var repositoryHighlightByID: [Repository.ID: SidebarHighlightRepoTag]
+  /// Per-repo hoisted-row tally; git repos only, built only for repos that
+  /// contributed at least one highlight row.
+  var hoistSummaryByRepositoryID: [Repository.ID: SidebarHoistSummary]
   /// Outer-ForEach data ordering for repository sections. The view uses
   /// this to translate `.onMove` flat offsets into the index space the
   /// `.repositoriesMoved` reducer action expects.
@@ -233,6 +272,7 @@ struct SidebarStructure: Equatable, Sendable {
     hotkeySlots: [],
     slotByID: [:],
     repositoryHighlightByID: [:],
+    hoistSummaryByRepositoryID: [:],
     reorderableRepositoryIDs: []
   )
 
@@ -245,6 +285,7 @@ struct SidebarStructure: Equatable, Sendable {
     hotkeySlots: [],
     slotByID: [:],
     repositoryHighlightByID: [:],
+    hoistSummaryByRepositoryID: [:],
     reorderableRepositoryIDs: []
   )
 }
@@ -312,7 +353,7 @@ extension SidebarItemFeature.Action {
     case .pullRequestChanged:
       return .selectedWorktreeSlice
     case .diffStatsChanged, .pullRequestQueryStarted,
-      .shortcutHintChanged, .dragSessionChanged,
+      .dragSessionChanged,
       .focusTerminalRequested, .focusTerminalConsumed:
       return []
     }
@@ -342,7 +383,7 @@ extension RepositoriesFeature.Action {
     // Bulk repository / worktree set changes that touch all caches.
     case .repositoriesLoaded, .openRepositoriesFinished,
       .repositoryRemovalCompleted, .repositoriesRemoved,
-      .removeFailedRepository,
+      .removeFailedRepository, .remoteRepositoryResolved,
       .archiveWorktreeApply, .unarchiveWorktree,
       .deleteWorktreeApply, .worktreeDeleted,
       .createWorktreeInRepository, .createRandomWorktreeInRepository,
@@ -356,6 +397,11 @@ extension RepositoriesFeature.Action {
     case .worktreeInfoEvent:
       return []
 
+    // Pure effect launcher: spawns the async SSH resolution, mutates no state.
+    // The per-repo `.remoteRepositoryResolved` results recompute the caches.
+    case .resolveRemoteRepositories:
+      return []
+
     // `worktreeBranchNameLoaded` mutates `worktree.name` via `updateWorktreeName`,
     // which feeds `computeToolbarNotificationGroups()` (notification group title).
     // Without `.toolbarNotificationGroups` the popover would show the old name
@@ -385,19 +431,29 @@ extension RepositoriesFeature.Action {
     case .repositoryCustomization:
       return []
 
-    // Branch rename updates the worktree.name shown in the sidebar row and
-    // the notification group title, mirroring `.worktreeBranchNameLoaded`.
+    // Worktree customization save mutates the bucketed Item's title / color, picked up via
+    // per-row `customTitle` / `customTint` mirror (highlight tags + notification group name).
+    case .worktreeCustomization(.presented(.delegate(.save))):
+      return .all
+    case .worktreeCustomization:
+      return []
+
+    // Branch rename updates the worktree.name shown in the sidebar row and notification group.
     case .renameBranchPrompt(.presented(.delegate(.renamed))):
       return .all
     case .renameBranchPrompt:
       return []
 
     // Everything else is UI / effects / transient state, no cache touched.
-    case .task, .setOpenPanelPresented, .loadPersistedRepositories,
+    case .task, .setOpenPanelPresented,
+      .requestAddRemoteRepository, .requestEditRemoteRepository, .remoteConnectionForm,
+      .loadPersistedRepositories,
+      .removeRemoteRepository,
       .refreshWorktrees, .reloadRepositories,
       .setSidebarSelectedWorktreeIDs,
       .openRepositories,
-      .revealSelectedWorktreeInSidebar, .consumePendingSidebarReveal,
+      .revealSelectedWorktreeInSidebar, .revealHoistedWorktreeInSidebar,
+      .consumePendingSidebarReveal,
       .createRandomWorktree,
       .promptedWorktreeCreationDataLoaded, .promptedWorktreeBranchesLoaded,
       .startPromptedWorktreeCreation,
@@ -419,6 +475,7 @@ extension RepositoriesFeature.Action {
       .showToast, .dismissToast,
       .delayedPullRequestRefresh,
       .openRepositorySettings, .requestCustomizeRepository,
+      .requestCustomizeWorktree,
       .requestRenameBranch,
       .contextMenuOpenWorktree,
       .worktreeCreationPrompt,
@@ -486,6 +543,7 @@ extension RepositoriesFeature.State {
         hotkeySlots: [],
         slotByID: [:],
         repositoryHighlightByID: [:],
+        hoistSummaryByRepositoryID: [:],
         reorderableRepositoryIDs: []
       )
     }
@@ -509,15 +567,18 @@ extension RepositoriesFeature.State {
       sections: sections
     )
 
+    let highlightProjections = computeRepositoryHighlightProjections(
+      pinnedHoisted: hoists.pinned,
+      activeHoisted: hoists.active
+    )
+
     return SidebarStructure(
       sections: sections,
       hoistedRowIDs: hoists.hoistedSet,
       hotkeySlots: hotkey.slots,
       slotByID: hotkey.slotByID,
-      repositoryHighlightByID: computeRepositoryHighlightTags(
-        pinnedHoisted: hoists.pinned,
-        activeHoisted: hoists.active
-      ),
+      repositoryHighlightByID: highlightProjections.tags,
+      hoistSummaryByRepositoryID: highlightProjections.summaries,
       reorderableRepositoryIDs: repoSections.reorderableRepositoryIDs
     )
   }
@@ -575,31 +636,59 @@ extension RepositoriesFeature.State {
       grouping: pendingWorktrees,
       by: \.repositoryID
     ).mapValues { Set($0.map(\.id)) }
+    // Failed local repos have no `repositories[id:]` entry, so resolve their
+    // root from the persisted `repositoryRoots` instead.
+    let localRootsByID: [Repository.ID: URL] = Dictionary(
+      uniqueKeysWithValues: repositoryRoots.map {
+        (RepositoryID($0.standardizedFileURL.path(percentEncoded: false)), $0.standardizedFileURL)
+      }
+    )
 
-    for rootURL in orderedRepositoryRoots() {
-      let repositoryID = rootURL.standardizedFileURL.path(percentEncoded: false)
+    // Local and remote repositories share one flat, reorderable order driven by
+    // `orderedRepositoryIDs()` (local roots and host-keyed remote ids honoring
+    // the persisted sidebar order). Remote repos are no longer pinned below the
+    // local ones: the user can interleave local and remote rows by drag.
+    // `reorderableRepositoryIDs` mirrors `orderedRepositoryIDs()` 1:1 (even ids
+    // with no rendered section, e.g. a still-loading root or a hoisted folder)
+    // so the offset-based `.repositoriesMoved` move maps cleanly back.
+    for repositoryID in orderedRepositoryIDs() {
+      reorderableRepositoryIDs.append(repositoryID)
+      let repository = repositories[id: repositoryID]
+      let isRemote = repository?.host != nil
+
+      // A disconnected remote keeps a placeholder repository (so it isn't
+      // pruned) plus a load failure; render it like a missing local folder.
       if loadFailuresByID[repositoryID] != nil {
+        guard let rootURL = localRootsByID[repositoryID] ?? repository?.rootURL else { continue }
         let sectionEntry = sidebar.sections[repositoryID]
+        // A folder's custom name / color live on its synthetic folder-worktree
+        // item (the row is a worktree row), not the section, so fall back to it.
+        let folderItem = sectionEntry?.folderWorktreeItem(for: repositoryID)
         sections.append(
           .failedRepository(
             repositoryID: repositoryID,
             rootURL: rootURL,
-            customTitle: sectionEntry?.title,
-            color: sectionEntry?.color
+            customTitle: sectionEntry?.title ?? folderItem?.title,
+            color: sectionEntry?.color ?? folderItem?.color,
+            isRemote: isRemote
           )
         )
-        reorderableRepositoryIDs.append(repositoryID)
         continue
       }
-      guard let repository = repositories[id: repositoryID] else { continue }
-      reorderableRepositoryIDs.append(repositoryID)
+
+      guard let repository else { continue }
+
       if !repository.isGitRepository {
-        let folderRowID = Repository.folderWorktreeID(for: repository.rootURL)
-        if !hoisted.contains(folderRowID) {
-          sections.append(.folder(repositoryID: repositoryID, rowID: folderRowID))
-        }
+        // Local folder rows key off the path-derived synthetic id; a remote
+        // folder uses its synthetic worktree's own host-keyed id so it never
+        // collides with a local folder at the same path.
+        let folderRowID =
+          isRemote ? repository.worktrees.first?.id : Repository.folderWorktreeID(for: repository.rootURL)
+        guard let folderRowID, !hoisted.contains(folderRowID) else { continue }
+        sections.append(.folder(repositoryID: repositoryID, rowID: folderRowID))
         continue
       }
+
       let groups = SidebarItemGroup.computeSlots(
         in: self,
         repositoryID: repositoryID,
@@ -609,7 +698,11 @@ extension RepositoriesFeature.State {
       )
       sections.append(.repository(repositoryID: repositoryID, groups: groups))
     }
-    return RepositorySectionsBuild(sections: sections, reorderableRepositoryIDs: reorderableRepositoryIDs)
+
+    return RepositorySectionsBuild(
+      sections: sections,
+      reorderableRepositoryIDs: reorderableRepositoryIDs
+    )
   }
 
   /// Hotkey assignment output for a single structure pass.
@@ -640,32 +733,65 @@ extension RepositoriesFeature.State {
     return HotkeyOrdering(slots: hotkeyWorktreeSlots(for: order), slotByID: slotByID)
   }
 
-  private func computeRepositoryHighlightTags(
+  /// Per-repo highlight projections derived in a single walk of the hoisted
+  /// arrays.
+  private struct HighlightProjections {
+    var tags: [Repository.ID: SidebarHighlightRepoTag]
+    var summaries: [Repository.ID: SidebarHoistSummary]
+  }
+
+  /// Resolve the highlight tags (every contributing repo) and the hoist
+  /// summaries (git repos only) in one pass. Walks the ordered arrays, not
+  /// `hoistedSet`, so `revealTarget` is deterministic: a repo's first pinned
+  /// hoist, else its first active.
+  private func computeRepositoryHighlightProjections(
     pinnedHoisted: [Worktree.ID],
     activeHoisted: [Worktree.ID]
-  ) -> [Repository.ID: SidebarHighlightRepoTag] {
-    guard !pinnedHoisted.isEmpty || !activeHoisted.isEmpty else { return [:] }
+  ) -> HighlightProjections {
+    guard !pinnedHoisted.isEmpty || !activeHoisted.isEmpty else {
+      return HighlightProjections(tags: [:], summaries: [:])
+    }
+
     var contributingRepoIDs: Set<Repository.ID> = []
+    var pinnedCounts: [Repository.ID: Int] = [:]
+    var activeCounts: [Repository.ID: Int] = [:]
+    var firstPinned: [Repository.ID: Worktree.ID] = [:]
+    var firstActive: [Repository.ID: Worktree.ID] = [:]
+
     for id in pinnedHoisted {
-      if let repoID = sidebarItems[id: id]?.repositoryID {
-        contributingRepoIDs.insert(repoID)
-      }
+      guard let repoID = sidebarItems[id: id]?.repositoryID else { continue }
+      contributingRepoIDs.insert(repoID)
+      pinnedCounts[repoID, default: 0] += 1
+      if firstPinned[repoID] == nil { firstPinned[repoID] = id }
     }
     for id in activeHoisted {
-      if let repoID = sidebarItems[id: id]?.repositoryID {
-        contributingRepoIDs.insert(repoID)
-      }
+      guard let repoID = sidebarItems[id: id]?.repositoryID else { continue }
+      contributingRepoIDs.insert(repoID)
+      activeCounts[repoID, default: 0] += 1
+      if firstActive[repoID] == nil { firstActive[repoID] = id }
     }
+
+    // Output is keyed by repo id, so build order is irrelevant.
     var tags: [Repository.ID: SidebarHighlightRepoTag] = [:]
+    var summaries: [Repository.ID: SidebarHoistSummary] = [:]
     for repoID in contributingRepoIDs {
       guard let repository = repositories[id: repoID] else { continue }
       let section = sidebar.sections[repoID]
       tags[repoID] = SidebarHighlightRepoTag(
         repoName: Repository.sidebarDisplayName(custom: section?.title, fallback: repository.name),
-        repoColor: section?.color
+        repoColor: section?.color,
+        hostInfo: repository.host?.displayAuthority
       )
+      guard repository.isGitRepository, let revealTarget = firstPinned[repoID] ?? firstActive[repoID] else {
+        continue
+      }
+      summaries[repoID] = SidebarHoistSummary(
+        pinnedCount: pinnedCounts[repoID] ?? 0,
+        activeCount: activeCounts[repoID] ?? 0,
+        revealTarget: revealTarget
+      )  // Non-nil: `revealTarget` exists only when a bucket contributed a row.
     }
-    return tags
+    return HighlightProjections(tags: tags, summaries: summaries)
   }
 
   /// Walk the freshly-built sections to extract visible per-repo row IDs in
@@ -833,8 +959,8 @@ extension SidebarItemGroup {
     in state: RepositoriesFeature.State
   ) -> [SidebarItemID] {
     ids.sorted { lhs, rhs in
-      let lhsName = state.sidebarItems[id: lhs]?.branchName ?? lhs
-      let rhsName = state.sidebarItems[id: rhs]?.branchName ?? rhs
+      let lhsName = state.sidebarItems[id: lhs]?.branchName ?? lhs.rawValue
+      let rhsName = state.sidebarItems[id: rhs]?.branchName ?? rhs.rawValue
       return lhsName.localizedCaseInsensitiveCompare(rhsName) == .orderedAscending
     }
   }
@@ -877,3 +1003,12 @@ extension SidebarItemGroup {
     return (translatedOffsets, translatedDestination)
   }
 }
+
+extension SidebarState.Section {
+  /// A folder repo's custom title / color live on its synthetic folder-worktree
+  /// item (the row is a worktree row), keyed by the repo id string.
+  fileprivate func folderWorktreeItem(for repositoryID: Repository.ID) -> SidebarState.Item? {
+    let folderID = WorktreeID(repositoryID.rawValue)
+    return buckets[.pinned]?.items[folderID] ?? buckets[.unpinned]?.items[folderID]
+  }
+}
diff --git a/supacode/Features/Repositories/BusinessLogic/WorktreeInfoWatcherManager.swift b/supacode/Features/Repositories/BusinessLogic/WorktreeInfoWatcherManager.swift
index 2613c2506..4526292aa 100644
--- a/supacode/Features/Repositories/BusinessLogic/WorktreeInfoWatcherManager.swift
+++ b/supacode/Features/Repositories/BusinessLogic/WorktreeInfoWatcherManager.swift
@@ -1,9 +1,18 @@
 import Darwin
 import Dispatch
 import Foundation
+import SupacodeSettingsShared
+
+private let watcherLogger = SupaLogger("WorktreeInfoWatcher")
 
 @MainActor
 final class WorktreeInfoWatcherManager {
+  /// Hard cap on the live event buffer. These events are refresh signals (not
+  /// coalescable state), so the stream is capped rather than deduped: a wedged
+  /// consumer drops the oldest signals instead of letting the buffer grow
+  /// without bound.
+  static let eventBufferCap = 2048
+
   private struct HeadWatcher {
     let headURL: URL
     let source: DispatchSourceFileSystemObject
@@ -36,8 +45,17 @@ final class WorktreeInfoWatcherManager {
   private let pullRequestSelectionRefreshCooldown: Duration
   private let refreshTiming: RefreshTiming
   private let sleep: @Sendable (Duration) async throws -> Void
+  /// Resolves a remote worktree's current branch over SSH. Injected so tests
+  /// can drive the poll loop without a real connection (real-host SSH is
+  /// verified separately). Returns `nil` for a local worktree or on error.
+  private let pollRemoteBranch: @Sendable (Worktree) async -> String?
   private var worktrees: [Worktree.ID: Worktree] = [:]
   private var headWatchers: [Worktree.ID: HeadWatcher] = [:]
+  /// Remote worktrees can't kqueue their `.git/HEAD` (it lives on another
+  /// host), so they poll `git rev-parse` over SSH on the same focused /
+  /// unfocused cadence as line-changes / PR refresh.
+  private var remoteHeadPollTasks: [Worktree.ID: RefreshTask] = [:]
+  private var lastKnownRemoteBranch: [Worktree.ID: String] = [:]
   private var branchDebounceTasks: [Worktree.ID: Task<Void, Never>] = [:]
   private var filesDebounceTasks: [Worktree.ID: Task<Void, Never>] = [:]
   private var restartTasks: [Worktree.ID: Task<Void, Never>] = [:]
@@ -55,7 +73,11 @@ final class WorktreeInfoWatcherManager {
     unfocusedInterval: Duration = .seconds(60),
     filesChangedDebounceInterval: Duration = .seconds(5),
     pullRequestSelectionRefreshCooldown: Duration = .seconds(5),
-    clock: C = ContinuousClock()
+    clock: C = ContinuousClock(),
+    pollRemoteBranch: @escaping @Sendable (Worktree) async -> String? = { worktree in
+      guard let host = worktree.host else { return nil }
+      return await GitClient(shell: .ssh(host: host)).symbolicHeadBranch(at: worktree.workingDirectory)
+    }
   ) {
     refreshTiming = RefreshTiming(focused: focusedInterval, unfocused: unfocusedInterval)
     self.filesChangedDebounceInterval = filesChangedDebounceInterval
@@ -63,6 +85,7 @@ final class WorktreeInfoWatcherManager {
     self.sleep = { duration in
       try await clock.sleep(for: duration)
     }
+    self.pollRemoteBranch = pollRemoteBranch
   }
 
   func handleCommand(_ command: WorktreeInfoWatcherClient.Command) {
@@ -80,7 +103,10 @@ final class WorktreeInfoWatcherManager {
 
   func eventStream() -> AsyncStream<WorktreeInfoWatcherClient.Event> {
     eventContinuation?.finish()
-    let (stream, continuation) = AsyncStream.makeStream(of: WorktreeInfoWatcherClient.Event.self)
+    let (stream, continuation) = AsyncStream.makeStream(
+      of: WorktreeInfoWatcherClient.Event.self,
+      bufferingPolicy: .bufferingNewest(Self.eventBufferCap)
+    )
     eventContinuation = continuation
     return stream
   }
@@ -138,9 +164,15 @@ final class WorktreeInfoWatcherManager {
     let nextRepository = worktreeID.flatMap { worktrees[$0]?.repositoryRootURL }
     if let previousWorktreeID {
       updateLineChangeSchedule(worktreeID: previousWorktreeID, immediate: false)
+      if let worktree = worktrees[previousWorktreeID] {
+        configureRemoteHeadPoll(for: worktree)
+      }
     }
     if let worktreeID {
       updateLineChangeSchedule(worktreeID: worktreeID, immediate: true)
+      if let worktree = worktrees[worktreeID] {
+        configureRemoteHeadPoll(for: worktree)
+      }
     }
     if let previousRepository, previousRepository == nextRepository {
       updatePullRequestSchedule(
@@ -161,6 +193,13 @@ final class WorktreeInfoWatcherManager {
   }
 
   private func configureWatcher(for worktree: Worktree) {
+    // Remote worktrees live on another host; their HEAD can't be kqueue'd, so
+    // route them to the SSH poll loop and skip the local head-file resolver
+    // (which would return nil for a non-local path and silently drop the row).
+    if worktree.host != nil {
+      configureRemoteHeadPoll(for: worktree)
+      return
+    }
     guard
       let headURL = GitWorktreeHeadResolver.headURL(
         for: worktree.workingDirectory,
@@ -273,6 +312,57 @@ final class WorktreeInfoWatcherManager {
     scheduleBranchChanged(worktreeID: worktreeID)
   }
 
+  /// (Re)start the SSH HEAD poll for a remote worktree at the focused /
+  /// unfocused cadence. No-op for a local worktree, and idempotent when the
+  /// interval is unchanged so a selection change that doesn't flip focus won't
+  /// restart the loop. The loop polls immediately, then on the interval.
+  private func configureRemoteHeadPoll(for worktree: Worktree) {
+    guard worktree.host != nil else {
+      return
+    }
+    let worktreeID = worktree.id
+    let interval = worktreeID == selectedWorktreeID ? refreshTiming.focused : refreshTiming.unfocused
+    if let existing = remoteHeadPollTasks[worktreeID], existing.interval == interval {
+      return
+    }
+    remoteHeadPollTasks[worktreeID]?.task.cancel()
+    let sleep = self.sleep
+    let pollRemoteBranch = self.pollRemoteBranch
+    let task = Task { [weak self, sleep, pollRemoteBranch] in
+      while !Task.isCancelled {
+        guard let worktree = await MainActor.run(body: { self?.worktrees[worktreeID] }) else {
+          break
+        }
+        let branch = await pollRemoteBranch(worktree)
+        await MainActor.run {
+          self?.handleRemoteBranch(worktreeID: worktreeID, branch: branch)
+        }
+        do {
+          try await sleep(interval)
+        } catch {
+          break
+        }
+      }
+    }
+    remoteHeadPollTasks[worktreeID] = RefreshTask(interval: interval, task: task)
+  }
+
+  private func handleRemoteBranch(worktreeID: Worktree.ID, branch: String?) {
+    guard let branch, lastKnownRemoteBranch[worktreeID] != branch else {
+      return
+    }
+    lastKnownRemoteBranch[worktreeID] = branch
+    // Reuse the kqueue debounce + `.branchChanged` emit so downstream behavior
+    // is identical. The first non-nil observation also emits, populating the
+    // row's branch from the live remote HEAD.
+    scheduleBranchChanged(worktreeID: worktreeID)
+  }
+
+  private func stopRemoteHeadPoll(for worktreeID: Worktree.ID) {
+    remoteHeadPollTasks.removeValue(forKey: worktreeID)?.task.cancel()
+    lastKnownRemoteBranch.removeValue(forKey: worktreeID)
+  }
+
   private func stopHeadWatcher(for worktreeID: Worktree.ID) {
     if let watcher = headWatchers.removeValue(forKey: worktreeID) {
       watcher.source.cancel()
@@ -281,6 +371,7 @@ final class WorktreeInfoWatcherManager {
 
   private func stopWatcher(for worktreeID: Worktree.ID) {
     stopHeadWatcher(for: worktreeID)
+    stopRemoteHeadPoll(for: worktreeID)
     branchDebounceTasks.removeValue(forKey: worktreeID)?.cancel()
     filesDebounceTasks.removeValue(forKey: worktreeID)?.cancel()
     restartTasks.removeValue(forKey: worktreeID)?.cancel()
@@ -306,12 +397,17 @@ final class WorktreeInfoWatcherManager {
     for task in lineChangeTasks.values {
       task.task.cancel()
     }
+    for task in remoteHeadPollTasks.values {
+      task.task.cancel()
+    }
     headWatchers.removeAll()
     branchDebounceTasks.removeAll()
     filesDebounceTasks.removeAll()
     restartTasks.removeAll()
     pullRequestTasks.removeAll()
     lineChangeTasks.removeAll()
+    remoteHeadPollTasks.removeAll()
+    lastKnownRemoteBranch.removeAll()
     deferredLineChangeIDs.removeAll()
     hasCompletedInitialWorktreeLoad = false
     cancelAllPullRequestSelectionCooldownTasks()
@@ -383,7 +479,7 @@ final class WorktreeInfoWatcherManager {
       .values
       .filter { $0.repositoryRootURL == repositoryRootURL }
       .map(\.id)
-      .sorted()
+      .sorted { $0.rawValue < $1.rawValue }
   }
 
   private func emitPullRequestRefresh(repositoryRootURL: URL) {
@@ -441,6 +537,9 @@ final class WorktreeInfoWatcherManager {
         do {
           try await sleep(request.interval)
         } catch {
+          if !(error is CancellationError) {
+            watcherLogger.error("Worktree refresh loop for \(worktreeID) ended: \(error).")
+          }
           break
         }
         guard !Task.isCancelled else {
@@ -460,7 +559,23 @@ final class WorktreeInfoWatcherManager {
     {
       return
     }
-    eventContinuation?.yield(event)
+    let result = eventContinuation?.yield(event)
+    if case .dropped(let shed)? = result {
+      let cap = Self.eventBufferCap
+      watcherLogger.error(
+        "Worktree info event buffer full (cap \(cap)); shed oldest refresh signal: \(Self.label(for: shed)).")
+    }
+  }
+
+  /// Compact identity for a backpressure-drop log. Strips the pull-request
+  /// refresh's worktree-id list to a count so a drop storm can't flood the log;
+  /// the single-id signals carry small payloads and describe themselves.
+  private static func label(for event: WorktreeInfoWatcherClient.Event) -> String {
+    switch event {
+    case .repositoryPullRequestRefresh(let rootURL, let worktreeIDs):
+      "repositoryPullRequestRefresh(\(rootURL.lastPathComponent), \(worktreeIDs.count) worktrees)"
+    default: String(describing: event)
+    }
   }
 
   private func cancelPullRequestSelectionCooldown(for repositoryRootURL: URL) {
diff --git a/supacode/Features/Repositories/Models/ToolbarNotificationGroup.swift b/supacode/Features/Repositories/Models/ToolbarNotificationGroup.swift
index 4ac274908..4419bfbd2 100644
--- a/supacode/Features/Repositories/Models/ToolbarNotificationGroup.swift
+++ b/supacode/Features/Repositories/Models/ToolbarNotificationGroup.swift
@@ -35,7 +35,17 @@ extension RepositoriesFeature.State {
     let repositoriesByID = Dictionary(uniqueKeysWithValues: repositories.map { ($0.id, $0) })
     var groups: [ToolbarNotificationRepositoryGroup] = []
 
-    for repositoryID in orderedRepositoryIDs() {
+    // `orderedRepositoryIDs()` is local-only (keyed off `repositoryRoots`); append
+    // remote repositories (host-keyed ids) so their worktree notifications also
+    // surface in the toolbar bell. Mirrors the sidebar grouping in
+    // `RepositoriesFeature+Sidebar`.
+    var orderedIDs = orderedRepositoryIDs()
+    let coveredIDs = Set(orderedIDs)
+    for repository in repositories where repository.host != nil && !coveredIDs.contains(repository.id) {
+      orderedIDs.append(repository.id)
+    }
+
+    for repositoryID in orderedIDs {
       guard let repository = repositoriesByID[repositoryID] else {
         continue
       }
@@ -47,7 +57,7 @@ extension RepositoriesFeature.State {
           }
           return ToolbarNotificationWorktreeGroup(
             id: worktree.id,
-            name: worktree.name,
+            name: row.resolvedSidebarTitle ?? worktree.name,
             notifications: Array(row.notifications),
             hasUnseenNotifications: row.hasUnseenNotifications
           )
diff --git a/supacode/Features/Repositories/Reducer/RemoteConnectionFormFeature.swift b/supacode/Features/Repositories/Reducer/RemoteConnectionFormFeature.swift
new file mode 100644
index 000000000..57aa054b0
--- /dev/null
+++ b/supacode/Features/Repositories/Reducer/RemoteConnectionFormFeature.swift
@@ -0,0 +1,125 @@
+import ComposableArchitecture
+import Foundation
+import SupacodeSettingsShared
+
+/// Add / edit form for a remote (SSH) repository connection. Validation (ssh
+/// reachability + `~` expansion to an absolute path) runs in-feature so an
+/// error surfaces in the sheet footer and the sheet stays open on failure,
+/// mirroring the worktree-creation prompt. The display name is intentionally
+/// absent: a remote repo is renamed through Customize Appearance like any other.
+@Reducer
+struct RemoteConnectionFormFeature {
+  @ObservableState
+  struct State: Equatable {
+    enum Mode: Equatable {
+      case add
+      /// Editing an existing remote, keyed by its self-descriptive repository id.
+      /// The original id is kept so the parent can replace it and drop stale
+      /// per-repo customization when a host/path change re-keys the repo.
+      case edit(originalRepositoryID: Repository.ID)
+    }
+
+    var mode: Mode
+    var server: String
+    var port: String
+    var username: String
+    var remotePath: String
+    var validationMessage: String?
+    var isValidating = false
+
+    init(
+      mode: Mode = .add,
+      server: String = "",
+      port: String = "",
+      username: String = "",
+      remotePath: String = ""
+    ) {
+      self.mode = mode
+      self.server = server
+      self.port = port
+      self.username = username
+      self.remotePath = remotePath
+    }
+
+    /// Seed an edit form from an existing remote host + path.
+    static func editing(host: RemoteHost, remotePath: String, repositoryID: Repository.ID) -> State {
+      State(
+        mode: .edit(originalRepositoryID: repositoryID),
+        server: host.alias,
+        port: host.port.map(String.init) ?? "",
+        username: host.username ?? "",
+        remotePath: remotePath
+      )
+    }
+
+    var trimmedServer: String { server.trimmingCharacters(in: .whitespacesAndNewlines) }
+    var trimmedPath: String { remotePath.trimmingCharacters(in: .whitespacesAndNewlines) }
+    var isEditing: Bool { if case .edit = mode { true } else { false } }
+    var canSubmit: Bool { !trimmedServer.isEmpty && !trimmedPath.isEmpty && !isValidating }
+
+    func makeHost() -> RemoteHost {
+      let trimmedUser = username.trimmingCharacters(in: .whitespacesAndNewlines)
+      let trimmedPort = port.trimmingCharacters(in: .whitespacesAndNewlines)
+      return RemoteHost(
+        alias: trimmedServer,
+        username: trimmedUser.isEmpty ? nil : trimmedUser,
+        port: Int(trimmedPort)
+      )
+    }
+  }
+
+  enum Action: BindableAction {
+    case binding(BindingAction<State>)
+    case submitButtonTapped
+    case cancelButtonTapped
+    /// `nil` absolute path means the host was unreachable or the path is missing.
+    case resolutionFinished(absolutePath: String?)
+    case delegate(Delegate)
+
+    enum Delegate: Equatable {
+      /// A validated host + resolved absolute path; the parent derives the id,
+      /// persists it (add or replace), and dismisses.
+      case save(host: RemoteHost, remotePath: String)
+      case cancel
+    }
+  }
+
+  var body: some Reducer<State, Action> {
+    BindingReducer()
+    Reduce { state, action in
+      switch action {
+      case .binding:
+        // Any edit clears the last failure so a stale message doesn't linger.
+        state.validationMessage = nil
+        return .none
+
+      case .cancelButtonTapped:
+        return .send(.delegate(.cancel))
+
+      case .submitButtonTapped:
+        guard state.canSubmit else { return .none }
+        state.isValidating = true
+        state.validationMessage = nil
+        let host = state.makeHost()
+        let path = state.trimmedPath
+        return .run { send in
+          let absolute = await RepositoriesFeature.resolveRemotePath(path, host: host)
+          await send(.resolutionFinished(absolutePath: absolute))
+        }
+
+      case .resolutionFinished(let absolutePath):
+        state.isValidating = false
+        guard let absolutePath else {
+          state.validationMessage =
+            "Couldn't reach \(state.makeHost().sshDestination) or find \(state.trimmedPath). "
+            + "Check the server, port, user, and path."
+          return .none
+        }
+        return .send(.delegate(.save(host: state.makeHost(), remotePath: absolutePath)))
+
+      case .delegate:
+        return .none
+      }
+    }
+  }
+}
diff --git a/supacode/Features/Repositories/Reducer/RenameBranchFeature.swift b/supacode/Features/Repositories/Reducer/RenameBranchFeature.swift
index 6312f1501..a250961ea 100644
--- a/supacode/Features/Repositories/Reducer/RenameBranchFeature.swift
+++ b/supacode/Features/Repositories/Reducer/RenameBranchFeature.swift
@@ -9,6 +9,7 @@ struct RenameBranchFeature {
     let worktreeID: Worktree.ID
     let repositoryID: Repository.ID
     let repositoryRootURL: URL
+    let host: RemoteHost?
     let currentName: String
     var newName: String
     var isSubmitting = false
@@ -20,11 +21,13 @@ struct RenameBranchFeature {
       worktreeID: Worktree.ID,
       repositoryID: Repository.ID,
       repositoryRootURL: URL,
+      host: RemoteHost?,
       currentName: String
     ) {
       self.worktreeID = worktreeID
       self.repositoryID = repositoryID
       self.repositoryRootURL = repositoryRootURL
+      self.host = host
       self.currentName = currentName
       self.newName = currentName
     }
@@ -79,6 +82,7 @@ struct RenameBranchFeature {
         let repoRoot = state.repositoryRootURL
         let worktreeID = state.worktreeID
         let repositoryID = state.repositoryID
+        let gitClient = state.host.map { GitClientDependency.ssh(host: $0) } ?? gitClient
         state.isSubmitting = true
         state.validationMessage = nil
         return .run { send in
diff --git a/supacode/Features/Repositories/Reducer/RepositoriesFeature+Remote.swift b/supacode/Features/Repositories/Reducer/RepositoriesFeature+Remote.swift
new file mode 100644
index 000000000..2aabd3900
--- /dev/null
+++ b/supacode/Features/Repositories/Reducer/RepositoriesFeature+Remote.swift
@@ -0,0 +1,631 @@
+import ComposableArchitecture
+import Foundation
+import IdentifiedCollections
+import Sharing
+import SupacodeSettingsShared
+
+extension RepositoriesFeature {
+  /// Dedicated reducer for the add / edit remote-connection form. Lives apart
+  /// from the main `body` switch so the form's `ifLet` child reducer runs
+  /// before the delegate handler nils the presented state, and so `body` stays
+  /// under the Swift type-checker's complexity limit (mirrors
+  /// `worktreeCustomizationReducer`).
+  static var remoteConnectionFormReducer: some Reducer<State, Action> {
+    Reduce { state, action in
+      switch action {
+      case .requestAddRemoteRepository:
+        state.remoteConnectionForm = RemoteConnectionFormFeature.State(mode: .add)
+        return .none
+
+      case .requestEditRemoteRepository(let repositoryID):
+        presentRemoteConnectionEditForm(repositoryID, state: &state)
+        return .none
+
+      case .remoteConnectionForm(.presented(.delegate(.cancel))):
+        state.remoteConnectionForm = nil
+        return .none
+
+      case .remoteConnectionForm(.presented(.delegate(.save(let host, let remotePath)))):
+        return saveRemoteConnection(host: host, remotePath: remotePath, state: &state)
+
+      default:
+        return .none
+      }
+    }
+  }
+
+  /// Self-descriptive Repository.ID for a remote host + path:
+  /// `<user@host:port><path>`. Never collides with a local id (an absolute
+  /// filesystem path starting with `/`) nor with another host at the same path.
+  /// This string is also the persisted `remoteRepositoryRoots` entry.
+  nonisolated static func remoteRepositoryID(host: RemoteHost, remotePath: String) -> Repository.ID {
+    RepositoryLocation.remote(host, path: RepositoryLocation.normalizedRemotePath(remotePath)).id
+  }
+
+  /// Sidebar title for a remote repo: the remote path's last component, falling
+  /// back to the host alias when the path has no leaf.
+  nonisolated static func remoteRepositoryName(host: RemoteHost, remotePath: String) -> String {
+    // `split` omits empty subsequences, so a non-nil leaf is never empty.
+    let leaf = RepositoryLocation.normalizedRemotePath(remotePath).split(separator: "/").last.map(String.init)
+    return leaf ?? host.alias
+  }
+
+  /// Host-keyed git worktree id `<user@host:port><remotePath>` so worktrees at
+  /// the same path on different hosts (or matching a local path) never collide.
+  nonisolated static func remoteWorktreeID(host: RemoteHost, worktreePath: String) -> Worktree.ID {
+    WorktreeID(host.authority + worktreePath)
+  }
+
+  /// The persisted remote-repository ids. Read through `@Shared` so every load
+  /// path (initial, reload, open, removal) sees the same source of truth.
+  static func persistedRemoteRepositoryRoots() -> [String] {
+    @Shared(.remoteRepositoryRoots) var remoteRepositoryRoots
+    return remoteRepositoryRoots
+  }
+
+  /// Parse a persisted remote id into its host + path, or `nil` when it isn't a
+  /// parseable remote authority.
+  nonisolated static func parseRemoteRoot(_ id: String) -> (host: RemoteHost, remotePath: String)? {
+    guard case .remote(let host, let path) = RepositoryLocation.parse(persistedID: id) else { return nil }
+    return (host, path)
+  }
+
+  /// An empty placeholder for a remote repository, rendered immediately while
+  /// the real listing resolves asynchronously over SSH (and when the host is
+  /// unreachable). Carries the host so selection / terminal attach still work.
+  nonisolated static func remotePlaceholderRepository(
+    host: RemoteHost,
+    remotePath: String,
+    repoID: Repository.ID
+  ) -> Repository {
+    Repository(
+      id: repoID,
+      rootURL: URL(fileURLWithPath: remotePath),
+      name: remoteRepositoryName(host: host, remotePath: remotePath),
+      worktrees: [],
+      isGitRepository: true,
+      host: host
+    )
+  }
+
+  /// Wall-clock bound for resolving one remote config. The ssh probe profile
+  /// fails fast for an unreachable host, but a reachable host whose command
+  /// stalls (a stale ControlMaster, a wedged remote shell) would otherwise hang;
+  /// this hard timeout flips such a row to "can't reach".
+  static let remoteLoadTimeout: Duration = .seconds(10)
+
+  /// Loads one remote config over SSH, bounded by `remoteLoadTimeout`. On a
+  /// failure or timeout it returns a placeholder repository (kept so the entry
+  /// is never pruned) paired with a `LoadFailure`, so the sidebar renders a
+  /// "can't reach" row like a missing local folder. The timeout cancels the
+  /// in-flight ssh (which terminates the process), so a stalled host can't keep
+  /// the row spinning forever.
+  nonisolated static func loadRemoteRepository(
+    host: RemoteHost,
+    remotePath: String,
+    repoID: Repository.ID,
+    shell: ShellClient? = nil
+  ) async -> (repository: Repository, failure: LoadFailure?) {
+    enum Outcome: Sendable {
+      case resolved(Repository, LoadFailure?)
+      case timedOut
+    }
+    let outcome = await withTaskGroup(of: Outcome.self) { group in
+      group.addTask {
+        let loaded = await resolveRemoteRepository(host: host, remotePath: remotePath, repoID: repoID, shell: shell)
+        return .resolved(loaded.repository, loaded.failure)
+      }
+      group.addTask {
+        try? await Task.sleep(for: remoteLoadTimeout)
+        return .timedOut
+      }
+      let first = await group.next() ?? .timedOut
+      group.cancelAll()
+      return first
+    }
+    switch outcome {
+    case .resolved(let repository, let failure):
+      return (repository, failure)
+    case .timedOut:
+      repositoriesLogger.warning("loadRemoteRepository: timed out reaching \(host.sshDestination)")
+      let failure = LoadFailure(
+        rootID: repoID,
+        message:
+          "Can't reach \(host.sshDestination). The repository will reappear when the host is reachable."
+      )
+      return (remotePlaceholderRepository(host: host, remotePath: remotePath, repoID: repoID), failure)
+    }
+  }
+
+  /// The actual SSH resolution behind `loadRemoteRepository`'s timeout. Runs the
+  /// non-interactive background-probe profile (`BatchMode` + `ConnectTimeout` +
+  /// `ServerAlive*`); any failure becomes a placeholder + `LoadFailure`.
+  nonisolated private static func resolveRemoteRepository(
+    host: RemoteHost,
+    remotePath: String,
+    repoID: Repository.ID,
+    shell: ShellClient? = nil
+  ) async -> (repository: Repository, failure: LoadFailure?) {
+    let rootURL = URL(fileURLWithPath: remotePath)
+    let shell = shell ?? .ssh(host: host, extraOptions: SSHCommand.backgroundProbeOptions)
+    let client = GitClient(shell: shell)
+
+    // A populated worktree listing is the unambiguous git case; skip the extra
+    // probe round trip for it (the common case).
+    var listingThrew = false
+    do {
+      let loaded = try await client.gitWorktrees(for: rootURL)
+      if !loaded.isEmpty {
+        let worktrees = loaded.map { remoteWorktree(from: $0, host: host) }
+        // A duplicate path signals a corrupt repo; keep the placeholder and
+        // surface a failure instead of trapping `IdentifiedArray(uniqueElements:)`.
+        if let duplicate = firstDuplicateWorktreeID(in: worktrees) {
+          let failure = LoadFailure(
+            rootID: repoID,
+            message: duplicateWorktreePathMessage(path: duplicate.rawValue)
+          )
+          return (remotePlaceholderRepository(host: host, remotePath: remotePath, repoID: repoID), failure)
+        }
+        let repository = Repository(
+          id: repoID,
+          rootURL: rootURL,
+          name: remoteRepositoryName(host: host, remotePath: remotePath),
+          worktrees: IdentifiedArray(uniqueElements: worktrees),
+          isGitRepository: true,
+          host: host
+        )
+        return (repository, nil)
+      }
+    } catch {
+      listingThrew = true
+      repositoriesLogger.warning(
+        "remote git worktree listing failed for \(host):\(rootURL.path(percentEncoded: false)): "
+          + error.localizedDescription
+      )
+    }
+
+    // Empty or failed listing: classify so a plain directory renders as a folder
+    // and an unreachable host renders as a placeholder rather than a fake repo.
+    switch await classifyRemotePath(remotePath, shell: shell) {
+    case .folder:
+      return (remoteFolderRepository(host: host, remotePath: remotePath, repoID: repoID), nil)
+    case .git where listingThrew:
+      // It's a git repo, but the worktree listing threw: collapsing to a single
+      // synthetic main would silently hide the repo's other worktrees. Surface a
+      // failure and keep the placeholder so the next reload re-lists in full.
+      let failure = LoadFailure(
+        rootID: repoID,
+        message:
+          "Connected to \(host.sshDestination) but couldn't list worktrees for "
+          + "\(remotePath). Supacode will retry."
+      )
+      return (remotePlaceholderRepository(host: host, remotePath: remotePath, repoID: repoID), failure)
+    case .git:
+      // Listing succeeded but was empty: a single synthetic main is the best
+      // representation of a git repo with nothing else to show.
+      let repository = Repository(
+        id: repoID,
+        rootURL: rootURL,
+        name: remoteRepositoryName(host: host, remotePath: remotePath),
+        worktrees: IdentifiedArray(uniqueElements: [remoteMainWorktree(host: host, remotePath: remotePath)]),
+        isGitRepository: true,
+        host: host
+      )
+      return (repository, nil)
+    case .missing:
+      // Host answered, but the configured path is gone: report the path (not a
+      // misleading "can't reach the host") and keep the placeholder.
+      let failure = LoadFailure(
+        rootID: repoID,
+        message:
+          "\(remotePath) was not found on \(host.sshDestination). "
+          + "The repository will reappear when the path exists."
+      )
+      return (remotePlaceholderRepository(host: host, remotePath: remotePath, repoID: repoID), failure)
+    case .unknown:
+      // Unreachable host / ambiguous probe: keep an empty placeholder (so the
+      // config isn't pruned and removal / edit still resolve it) and record a
+      // load failure so the sidebar shows a "can't reach" row.
+      let failure = LoadFailure(
+        rootID: repoID,
+        message:
+          "Can't reach \(host.sshDestination). The repository will reappear when the host is reachable."
+      )
+      return (remotePlaceholderRepository(host: host, remotePath: remotePath, repoID: repoID), failure)
+    }
+  }
+
+  /// How long the add / edit form waits for the ssh reachability probe before
+  /// giving up. Generous enough for a first connect plus interactive auth (a
+  /// hardware-key touch), tight enough that an unreachable host fails the form
+  /// instead of spinning indefinitely.
+  static let remoteResolveTimeout: Duration = .seconds(15)
+
+  /// The last non-empty line of `output`. A login shell sources dotfiles before
+  /// running the probe, so any banner they print precedes the command output;
+  /// the real result is the final line.
+  nonisolated static func lastNonEmptyLine(of output: String) -> String {
+    output
+      .split(whereSeparator: \.isNewline)
+      .last { !$0.trimmingCharacters(in: .whitespaces).isEmpty }
+      .map { $0.trimmingCharacters(in: .whitespaces) } ?? ""
+  }
+
+  /// Resolve a typed remote path to an absolute, canonical path on the host,
+  /// expanding a leading `~`. Returns nil when the host is unreachable, the
+  /// probe times out, or the path does not exist, so the caller can reject the
+  /// add. The path travels as a positional argument (not interpolated into the
+  /// script), so spaces and shell metacharacters are safe; only the intended
+  /// leading `~` expands.
+  static func resolveRemotePath(
+    _ path: String,
+    host: RemoteHost,
+    shell: ShellClient? = nil,
+    timeout: Duration = remoteResolveTimeout
+  ) async -> String? {
+    let trimmed = path.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard !trimmed.isEmpty else { return nil }
+    let shell = shell ?? .ssh(host: host)
+    let script = """
+      case "$1" in
+        "~") target=$HOME ;;
+        "~/"*) target=$HOME/${1#"~/"} ;;
+        *) target=$1 ;;
+      esac
+      cd -- "$target" 2>/dev/null && pwd -P
+      """
+
+    enum Outcome {
+      case resolved(String)
+      case failed
+      case timedOut
+    }
+    return await withTaskGroup(of: Outcome.self) { group in
+      group.addTask {
+        do {
+          let output = try await shell.run(URL(fileURLWithPath: "/bin/sh"), ["-c", script, "sh", trimmed], nil)
+          let resolved = lastNonEmptyLine(of: output.stdout)
+          return resolved.isEmpty ? .failed : .resolved(resolved)
+        } catch {
+          // Unreachable host vs failed `cd` is indistinguishable here; log so
+          // the form's failure has a breadcrumb.
+          repositoriesLogger.warning(
+            "resolveRemotePath: shell failed for \(host.sshDestination): \(error)"
+          )
+          return .failed
+        }
+      }
+      group.addTask {
+        try? await Task.sleep(for: timeout)
+        return .timedOut
+      }
+      defer { group.cancelAll() }
+      guard let first = await group.next() else { return nil }
+      switch first {
+      case .resolved(let resolved):
+        return resolved
+      case .failed:
+        return nil
+      case .timedOut:
+        repositoriesLogger.warning(
+          "resolveRemotePath: timed out reaching \(host.sshDestination) after \(timeout)"
+        )
+        return nil
+      }
+    }
+  }
+
+  /// Whether a remote path is a git work tree, a plain directory, reachable but
+  /// absent, or indeterminate. `.missing` (host answered, path gone) is kept
+  /// distinct from `.unknown` (host unreachable / probe ambiguous) so the caller
+  /// can report an accurate failure instead of a blanket "can't reach".
+  enum RemotePathKind: Equatable, Sendable {
+    case git
+    case folder
+    case missing
+    case unknown
+  }
+
+  /// Classify a remote path over ssh in a single round trip so a non-git
+  /// directory can render as a folder. `.missing` when the host answers but the
+  /// path is gone; `.unknown` when the host is unreachable or the probe is
+  /// ambiguous, so the caller can keep the git fallback rather than mislabel a
+  /// transient failure.
+  nonisolated static func classifyRemotePath(
+    _ remotePath: String,
+    shell: ShellClient
+  ) async -> RemotePathKind {
+    let quoted = "'" + remotePath.replacing("'", with: "'\\''") + "'"
+    let script =
+      "if [ ! -d \(quoted) ]; then echo supacode-nodir; "
+      + "elif git -C \(quoted) rev-parse --is-inside-work-tree >/dev/null 2>&1; then echo supacode-git; "
+      + "else echo supacode-folder; fi"
+    guard let output = try? await shell.run(URL(fileURLWithPath: "/bin/sh"), ["-c", script], nil) else {
+      return .unknown
+    }
+    let trimmedStdout = lastNonEmptyLine(of: output.stdout)
+    switch trimmedStdout {
+    case "supacode-git": return .git
+    case "supacode-folder": return .folder
+    case "supacode-nodir": return .missing
+    default:
+      repositoriesLogger.warning("classifyRemotePath: unexpected probe stdout: " + trimmedStdout)
+      return .unknown
+    }
+  }
+
+  /// Folder counterpart to a git remote repository: a single synthetic worktree
+  /// at the root carrying the host so the terminal still attaches over ssh.
+  /// `isGitRepository: false` routes it to the sidebar's folder row. The worktree
+  /// id is host-keyed (the same `remoteWorktreeID` scheme as remote git
+  /// worktrees), so a remote `~` never collides with a local `~` folder.
+  nonisolated static func remoteFolderRepository(
+    host: RemoteHost,
+    remotePath: String,
+    repoID: Repository.ID
+  ) -> Repository {
+    let folder = Worktree(
+      location: .remote(
+        host, workingDirectory: remotePath, repositoryRoot: remotePath),
+      kind: .folder,
+      name: remoteRepositoryName(host: host, remotePath: remotePath),
+      detail: host.sshDestination,
+      isAttached: false
+    )
+    return Repository(
+      location: .remote(host, path: remotePath),
+      kind: .folder,
+      name: remoteRepositoryName(host: host, remotePath: remotePath),
+      worktrees: IdentifiedArray(uniqueElements: [folder])
+    )
+  }
+
+  /// Re-key a worktree parsed from the remote `git worktree list` with the host
+  /// and a host-keyed id, preserving everything else.
+  nonisolated static func remoteWorktree(from base: Worktree, host: RemoteHost) -> Worktree {
+    Worktree(
+      id: remoteWorktreeID(host: host, worktreePath: base.workingDirectory.path(percentEncoded: false)),
+      kind: base.kind,
+      name: base.name,
+      detail: base.detail,
+      workingDirectory: base.workingDirectory,
+      repositoryRootURL: base.repositoryRootURL,
+      createdAt: base.createdAt,
+      isMissing: base.isMissing,
+      isAttached: base.isAttached,
+      host: host
+    )
+  }
+
+  /// Synthetic main worktree used when the remote git listing is unavailable.
+  /// `workingDirectory == repositoryRootURL` so it classifies as the git main.
+  nonisolated static func remoteMainWorktree(host: RemoteHost, remotePath: String) -> Worktree {
+    let rootURL = URL(fileURLWithPath: remotePath)
+    return Worktree(
+      id: remoteWorktreeID(host: host, worktreePath: remotePath),
+      kind: .git,
+      name: remoteRepositoryName(host: host, remotePath: remotePath),
+      detail: host.sshDestination,
+      workingDirectory: rootURL,
+      repositoryRootURL: rootURL,
+      isAttached: false,
+      host: host
+    )
+  }
+
+  /// Remote worktree creation: pick a name (excluding remote branches), run
+  /// `git worktree add` over ssh, then reload to re-list. Bypasses the local
+  /// pending/stream flow but honors the prompt's name + base-ref choices. The
+  /// base ref is resolved the same way as local (`baseRefSource` → explicit /
+  /// repo setting, falling back to the remote's automatic base ref), and the
+  /// new worktree lands beside the repo root (`<parent>/<name>`), so no parent
+  /// dir needs to be created first.
+  func remoteCreateWorktree(
+    repository: Repository,
+    nameSource: WorktreeCreationNameSource,
+    baseRefSource: WorktreeCreationBaseRefSource,
+    fetchOrigin: Bool,
+    placement: WorktreePlacementOverride?
+  ) -> Effect<Action> {
+    guard let host = repository.host else { return .none }
+    let repoRoot = repository.rootURL
+    @Shared(.repositorySettings(repoRoot, host: host)) var remoteRepositorySettings
+    let selectedBaseRef = remoteRepositorySettings.worktreeBaseRef
+    let existingNames = Set(repository.worktrees.map { $0.name.lowercased() })
+    return .run { send in
+      let client = GitClient(shell: .ssh(host: host))
+      let remoteBranches = (try? await client.localBranchNames(for: repoRoot)) ?? []
+      let existing = existingNames.union(remoteBranches)
+      let name: String
+      switch nameSource {
+      case .random:
+        let generated = await MainActor.run { WorktreeNameGenerator.nextName(excluding: existing) }
+        guard let generated else {
+          await send(
+            .presentAlert(
+              title: "No available worktree names",
+              message: "All default adjective-animal names are already in use. "
+                + "Delete a worktree or rename a branch, then try again."
+            )
+          )
+          return
+        }
+        name = generated
+      case .explicit(let explicit):
+        let trimmed = explicit.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty, !trimmed.contains(where: \.isWhitespace) else {
+          await send(
+            .presentAlert(
+              title: "Branch name invalid",
+              message: "Enter a branch name without spaces to create a worktree."
+            )
+          )
+          return
+        }
+        name = trimmed
+      }
+      // Parent directory precedence: the prompt's explicit override, then the
+      // remote host's Supacode settings (per-repo, then global), then the
+      // local-style default (alongside the repo root on the host). The leaf is
+      // the prompt's worktree-name override, falling back to the branch name.
+      let parentDirectory = await Self.remoteWorktreeParentDirectory(
+        host: host, repoRoot: repoRoot, placementPath: placement?.path)
+      let leaf = Self.remoteWorktreeLeaf(nameOverride: placement?.name, branchName: name)
+      let worktreePath = parentDirectory.appending(path: leaf, directoryHint: .isDirectory)
+      let baseRef = await Self.resolveRemoteBaseRef(
+        baseRefSource: baseRefSource, selectedBaseRef: selectedBaseRef, client: client, repoRoot: repoRoot)
+      await Self.fetchRemoteForBaseRefIfNeeded(
+        fetchOrigin: fetchOrigin, baseRef: baseRef, client: client, repoRoot: repoRoot)
+      do {
+        try await client.createGitWorktree(in: repoRoot, name: name, baseRef: baseRef, worktreePath: worktreePath)
+        await send(.loadPersistedRepositories)
+      } catch {
+        await send(.presentAlert(title: "Unable to create worktree", message: error.localizedDescription))
+      }
+    }
+  }
+
+  /// Leaf folder name for a remote worktree: the prompt's worktree-name override
+  /// when it's a valid single path component, otherwise the branch name.
+  nonisolated static func remoteWorktreeLeaf(nameOverride: String?, branchName: String) -> String {
+    let trimmed = (nameOverride ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+    guard !trimmed.isEmpty, WorktreePlacementOverride.nameValidationError(trimmed) == nil else {
+      return branchName
+    }
+    return trimmed
+  }
+
+  /// Parent directory for a new remote worktree. Precedence: the prompt's
+  /// explicit parent override, then the remote host's Supacode per-repo
+  /// `worktreeBaseDirectoryPath`, then the remote global default (joined with the
+  /// repo's directory name), then the local-style default of placing the
+  /// worktree alongside the repo root on the host.
+  static func remoteWorktreeParentDirectory(
+    host: RemoteHost,
+    repoRoot: URL,
+    placementPath: String?,
+    shell: ShellClient? = nil
+  ) async -> URL {
+    if let placementPath {
+      let trimmed = placementPath.trimmingCharacters(in: .whitespacesAndNewlines)
+      if !trimmed.isEmpty {
+        return URL(filePath: trimmed, directoryHint: .isDirectory)
+      }
+    }
+    let bases = await readRemoteWorktreeBaseDirectories(host: host, repoRoot: repoRoot, shell: shell)
+    if let perRepo = bases.perRepo?.trimmingCharacters(in: .whitespacesAndNewlines), !perRepo.isEmpty {
+      return URL(filePath: perRepo, directoryHint: .isDirectory)
+    }
+    if let global = bases.global?.trimmingCharacters(in: .whitespacesAndNewlines), !global.isEmpty {
+      return URL(filePath: global, directoryHint: .isDirectory)
+        .appending(path: repoRoot.lastPathComponent, directoryHint: .isDirectory)
+    }
+    return repoRoot.deletingLastPathComponent()
+  }
+
+  /// Read the remote host's worktree base directories over ssh: the per-repo
+  /// value from `<repoRoot>/supacode.json` and the global default from
+  /// `~/.supacode/settings.json`. Returns `(nil, nil)` when the host is
+  /// unreachable or neither file is present.
+  static func readRemoteWorktreeBaseDirectories(
+    host: RemoteHost,
+    repoRoot: URL,
+    shell: ShellClient? = nil
+  ) async -> (perRepo: String?, global: String?) {
+    let shell = shell ?? .ssh(host: host)
+    let repoSettingsPath = repoRoot.appending(path: "supacode.json").path(percentEncoded: false)
+    let quotedRepoSettings = "'" + repoSettingsPath.replacing("'", with: "'\\''") + "'"
+    // `|| true` keeps a missing file a clean empty section rather than a non-zero exit.
+    let script =
+      "echo '===SUPACODE-REPO==='; cat \(quotedRepoSettings) 2>/dev/null || true; "
+      + #"echo '===SUPACODE-GLOBAL==='; cat "$HOME/.supacode/settings.json" 2>/dev/null || true"#
+    guard
+      let output = try? await shell.run(URL(fileURLWithPath: "/bin/sh"), ["-c", script], nil)
+    else {
+      return (nil, nil)
+    }
+    return parseRemoteWorktreeBaseDirectories(output.stdout)
+  }
+
+  /// Pure split + decode of `readRemoteWorktreeBaseDirectories`'s output: the
+  /// per-repo `RepositorySettings` block and the global `SettingsFile` block,
+  /// separated by the marker lines.
+  nonisolated static func parseRemoteWorktreeBaseDirectories(
+    _ output: String
+  ) -> (perRepo: String?, global: String?) {
+    guard
+      let repoMarker = output.range(of: "===SUPACODE-REPO==="),
+      let globalMarker = output.range(of: "===SUPACODE-GLOBAL===")
+    else {
+      return (nil, nil)
+    }
+    let repoJSON = String(output[repoMarker.upperBound..<globalMarker.lowerBound])
+    let globalJSON = String(output[globalMarker.upperBound...])
+    let perRepo = decode(RepositorySettings.self, from: repoJSON)?.worktreeBaseDirectoryPath
+    let global = decode(SettingsFile.self, from: globalJSON)?.global.defaultWorktreeBaseDirectoryPath
+    return (perRepo, global)
+  }
+
+  nonisolated private static func decode<T: Decodable>(_ type: T.Type, from json: String) -> T? {
+    let data = Data(json.utf8)
+    guard !data.isEmpty else { return nil }
+    return try? JSONDecoder().decode(type, from: data)
+  }
+
+  /// Resolve the base ref for a remote worktree the same way the local path does
+  /// (`baseRefSource` → explicit / repo setting, falling back to the remote's
+  /// automatic base ref), defaulting to `HEAD` when nothing resolves so
+  /// `git worktree add` always has a concrete committish.
+  static func resolveRemoteBaseRef(
+    baseRefSource: WorktreeCreationBaseRefSource,
+    selectedBaseRef: String?,
+    client: GitClient,
+    repoRoot: URL
+  ) async -> String {
+    let resolved: String
+    switch baseRefSource {
+    case .repositorySetting:
+      if let selectedBaseRef, !selectedBaseRef.isEmpty {
+        resolved = selectedBaseRef
+      } else {
+        resolved = await client.automaticWorktreeBaseRef(for: repoRoot) ?? ""
+      }
+    case .explicit(let explicit):
+      if let explicit, !explicit.isEmpty {
+        resolved = explicit
+      } else {
+        resolved = await client.automaticWorktreeBaseRef(for: repoRoot) ?? ""
+      }
+    }
+    return resolved.isEmpty ? "HEAD" : resolved
+  }
+
+  /// Mirror the local `fetchOriginBeforeWorktreeCreation` behavior over ssh: when
+  /// enabled, list the remote's remotes, match the one the base ref points at
+  /// (`<remote>/…`), and `git fetch` it on the host before `git worktree add` so
+  /// the new worktree branches from up-to-date refs. Best-effort and non-fatal:
+  /// a fetch failure (offline remote, auth) is logged and creation proceeds, same
+  /// as local. A base ref with no remote prefix (e.g. a local branch or `HEAD`)
+  /// matches nothing and skips the fetch.
+  static func fetchRemoteForBaseRefIfNeeded(
+    fetchOrigin: Bool,
+    baseRef: String,
+    client: GitClient,
+    repoRoot: URL
+  ) async {
+    guard fetchOrigin else { return }
+    let remotes = (try? await client.remoteNames(for: repoRoot)) ?? []
+    guard let matchedRemote = GitReferenceQueries.remotePrefixMatch(ref: baseRef, remoteNames: remotes)?.remote
+    else {
+      return
+    }
+    do {
+      try await client.fetchRemote(matchedRemote, for: repoRoot)
+    } catch {
+      repositoriesLogger.warning(
+        "remote git fetch \(matchedRemote) failed for \(repoRoot.path(percentEncoded: false)): "
+          + error.localizedDescription
+      )
+    }
+  }
+}
diff --git a/supacode/Features/Repositories/Reducer/RepositoriesFeature+Removal.swift b/supacode/Features/Repositories/Reducer/RepositoriesFeature+Removal.swift
index 6ea80b46d..c56ff0749 100644
--- a/supacode/Features/Repositories/Reducer/RepositoriesFeature+Removal.swift
+++ b/supacode/Features/Repositories/Reducer/RepositoriesFeature+Removal.swift
@@ -172,16 +172,15 @@ extension RepositoriesFeature {
   /// (`removingRepositoryIDs`) rather than `state.repositories`,
   /// so a concurrent reload / `.removeFailedRepository` race that
   /// pruned the live repo mid-script can't orphan the batch.
-  /// Folder worktrees follow the `"folder:" + repoID` convention
-  /// (see `Repository.folderWorktreeID(for:)`). Round-trip back to
-  /// the repo id via `Repository.repositoryID(fromFolderWorktreeID:)`
-  /// so the prefix literal lives in exactly one place.
+  /// A folder repo's synthetic worktree id is its repo root path,
+  /// which equals the repo id, so the recovery is a direct rewrap;
+  /// the `disposition.isFolder` gate confirms this is a folder removal.
   func signalFolderRemovalFailure(
     worktreeID: Worktree.ID,
     state: inout State
   ) -> Effect<Action> {
-    guard let repositoryID = Repository.repositoryID(fromFolderWorktreeID: worktreeID),
-      state.removingRepositoryIDs[repositoryID]?.disposition.isFolder == true
+    let repositoryID = RepositoryID(worktreeID.rawValue)
+    guard state.removingRepositoryIDs[repositoryID]?.disposition.isFolder == true
     else { return .none }
     return .send(
       .repositoryRemovalCompleted(
@@ -220,8 +219,8 @@ extension RepositoriesFeature {
       if let resolved = namesByRepositoryID[id], !resolved.isEmpty {
         return resolved
       }
-      let fallback = URL(fileURLWithPath: id).lastPathComponent
-      return fallback.isEmpty ? id : fallback
+      let fallback = URL(fileURLWithPath: id.rawValue).lastPathComponent
+      return fallback.isEmpty ? id.rawValue : fallback
     }
     let count = failureMessagesByRepositoryID.count
     if count == 1, let (id, message) = failureMessagesByRepositoryID.first {
@@ -288,7 +287,7 @@ extension RepositoriesFeature {
     repositoryID: Repository.ID,
     state: State
   ) -> AlertState<Alert> {
-    let fallback = Repository.name(for: URL(fileURLWithPath: repositoryID).standardizedFileURL)
+    let fallback = Repository.name(for: URL(fileURLWithPath: repositoryID.rawValue).standardizedFileURL)
     let name = Repository.sidebarDisplayName(
       custom: state.sidebar.sections[repositoryID]?.title,
       fallback: fallback
diff --git a/supacode/Features/Repositories/Reducer/RepositoriesFeature+Sidebar.swift b/supacode/Features/Repositories/Reducer/RepositoriesFeature+Sidebar.swift
index 1c6557209..568127b8c 100644
--- a/supacode/Features/Repositories/Reducer/RepositoriesFeature+Sidebar.swift
+++ b/supacode/Features/Repositories/Reducer/RepositoriesFeature+Sidebar.swift
@@ -43,14 +43,15 @@ extension RepositoriesFeature {
             isMainWorktree: isMain,
             isPinned: isPinned,
             hasMergedBadge: false,
-            isMissing: worktree.isMissing
+            isMissing: worktree.isMissing,
+            host: worktree.host
           )
         // Seed (or re-seed) only until the row's first live projection lands.
         // The `!hasTerminalProjection` half lets a layout that wasn't present
         // at the row's first reconcile still seed when it shows up; the same
         // gate prevents stale UUIDs from being re-injected after the user
         // closes every tab (which emits an empty projection).
-        if !item.hasTerminalProjection, item.surfaceIDs.isEmpty, let snapshot = layouts[id] {
+        if !item.hasTerminalProjection, item.surfaceIDs.isEmpty, let snapshot = layouts[id.rawValue] {
           let ids = snapshot.allSurfaceIDs
           if !ids.isEmpty {
             item.surfaceIDs = ids
@@ -64,6 +65,12 @@ extension RepositoriesFeature {
         item.isMainWorktree = isMain
         item.isPinned = isPinned
         item.isMissing = worktree.isMissing
+        // Mirror per-worktree customization from `@Shared(.sidebar)`. Reading
+        // through the currently-owning bucket survives pin / unpin / archive
+        // transitions because the bucket-flow `move` carries the `Item` over.
+        let customization = storedCustomization(for: id, in: repository.id, sidebar: state.sidebar)
+        item.customTitle = customization.title
+        item.customTint = customization.color
         // Clear the PR query branch when the worktree was renamed.
         if let existing, existing.branchName != worktree.name {
           item.pullRequestBranchAtQueryTime = nil
@@ -95,10 +102,13 @@ extension RepositoriesFeature {
             repositoryAccent: nil,
             isMainWorktree: false,
             isPinned: false,
-            hasMergedBadge: false
+            hasMergedBadge: false,
+            host: repository.host
           )
         item.name = pendingName
         item.branchName = pendingName
+        item.customTitle = pending.customization?.title
+        item.customTint = pending.customization?.color
         item.lifecycle =
           state.removingRepositoryIDs[pending.repositoryID] != nil
           ? .deleting
@@ -126,11 +136,36 @@ extension RepositoriesFeature {
     }
   }
 
+  /// User-set title / color for `worktreeID`, read through whichever bucket
+  /// currently owns the row so the lookup survives pin / unpin / archive moves.
+  /// Both fields are `nil` when the row isn't bucketed yet.
+  private static func storedCustomization(
+    for worktreeID: Worktree.ID,
+    in repositoryID: Repository.ID,
+    sidebar: SidebarState
+  ) -> (title: String?, color: RepositoryColor?) {
+    guard let bucketID = sidebar.currentBucket(of: worktreeID, in: repositoryID),
+      let storedItem = sidebar.sections[repositoryID]?.buckets[bucketID]?.items[worktreeID]
+    else {
+      return (nil, nil)
+    }
+    return (storedItem.title, storedItem.color)
+  }
+
   /// Pair with `reconcileSidebarItems`; recomputes `state.sidebarGrouping`.
   static func rebuildSidebarGrouping(_ state: inout State) {
     var buckets: OrderedDictionary<Repository.ID, SidebarGrouping.BucketGrouping> = [:]
 
-    for repositoryID in state.orderedRepositoryIDs() {
+    // `orderedRepositoryIDs()` already appends remote repos; this loop is a
+    // defensive backstop for any it might miss, so every repo gets a grouping
+    // bucket for `computeSlots`. Lookup is by id, so order here doesn't affect
+    // rendering.
+    var orderedIDs = state.orderedRepositoryIDs()
+    let coveredIDs = Set(orderedIDs)
+    for repository in state.repositories where repository.host != nil && !coveredIDs.contains(repository.id) {
+      orderedIDs.append(repository.id)
+    }
+    for repositoryID in orderedIDs {
       guard let repository = state.repositories[id: repositoryID] else { continue }
       var bucket = SidebarGrouping.BucketGrouping()
       var pinned: [SidebarItemID] = []
diff --git a/supacode/Features/Repositories/Reducer/RepositoriesFeature+WorktreeCustomization.swift b/supacode/Features/Repositories/Reducer/RepositoriesFeature+WorktreeCustomization.swift
new file mode 100644
index 000000000..044a4bf29
--- /dev/null
+++ b/supacode/Features/Repositories/Reducer/RepositoriesFeature+WorktreeCustomization.swift
@@ -0,0 +1,70 @@
+import ComposableArchitecture
+import Foundation
+import OrderedCollections
+import SupacodeSettingsShared
+
+extension RepositoriesFeature {
+  /// Dedicated reducer for the per-worktree customization flow. Lives in its own file so the main
+  /// `body` switch stays under the Swift type-checker's complexity limit.
+  static var worktreeCustomizationReducer: some Reducer<State, Action> {
+    Reduce { state, action in
+      switch action {
+      case .requestCustomizeWorktree(let worktreeID, let repositoryID):
+        guard let repository = state.repositories[id: repositoryID],
+          let worktree = repository.worktrees.first(where: { $0.id == worktreeID })
+        else {
+          repositoriesLogger.warning(
+            "requestCustomizeWorktree dropped: unknown wt=\(worktreeID) repo=\(repositoryID)"
+          )
+          return .none
+        }
+        // Git main worktree is repository-level (use requestCustomizeRepository instead). The
+        // folder synthetic worktree IS the row, so we allow it through.
+        if repository.isGitRepository, state.isMainWorktree(worktree) {
+          repositoriesLogger.warning(
+            "requestCustomizeWorktree dropped: git main worktree is repository-level wt=\(worktreeID)"
+          )
+          return .none
+        }
+        let bucket = state.sidebar.currentBucket(of: worktreeID, in: repositoryID)
+        let storedItem = bucket.flatMap {
+          state.sidebar.sections[repositoryID]?.buckets[$0]?.items[worktreeID]
+        }
+        // For folder synthetic worktrees, default name = repository name (what the row shows when
+        // no override). For git worktrees, default name = branch name.
+        let defaultName = repository.isGitRepository ? worktree.name : repository.name
+        state.worktreeCustomization = WorktreeCustomizationFeature.State(
+          worktreeID: worktreeID,
+          repositoryID: repositoryID,
+          defaultName: defaultName,
+          title: storedItem?.title ?? "",
+          color: storedItem?.color
+        )
+        return .none
+
+      case .worktreeCustomization(.presented(.delegate(.cancel))):
+        state.worktreeCustomization = nil
+        return .none
+
+      case .worktreeCustomization(
+        .presented(.delegate(.save(let worktreeID, let repositoryID, let title, let color)))
+      ):
+        // Always overwrite (user save intent); falls back to `.unpinned` when the row hasn't been
+        // seeded into a bucket yet (folder synthetic before first reconcile, deeplink/palette).
+        state.$sidebar.withLock { sidebar in
+          sidebar.setCustomization(title: title, color: color, worktree: worktreeID, in: repositoryID)
+        }
+        syncSidebar(&state)
+        state.worktreeCustomization = nil
+        return .none
+
+      case .worktreeCustomization(.dismiss):
+        state.worktreeCustomization = nil
+        return .none
+
+      default:
+        return .none
+      }
+    }
+  }
+}
diff --git a/supacode/Features/Repositories/Reducer/RepositoriesFeature.swift b/supacode/Features/Repositories/Reducer/RepositoriesFeature.swift
index 9b9d02621..a8f85a3c6 100644
--- a/supacode/Features/Repositories/Reducer/RepositoriesFeature.swift
+++ b/supacode/Features/Repositories/Reducer/RepositoriesFeature.swift
@@ -15,6 +15,7 @@ private enum CancelID {
   static let githubIntegrationRecovery = "repositories.githubIntegrationRecovery"
   static let worktreePromptLoad = "repositories.worktreePromptLoad"
   static let worktreePromptValidation = "repositories.worktreePromptValidation"
+  static let resolveRemoteRepositories = "repositories.resolveRemoteRepositories"
   static func delayedPRRefresh(_ worktreeID: Worktree.ID) -> String {
     "repositories.delayedPRRefresh.\(worktreeID)"
   }
@@ -87,10 +88,21 @@ struct RepositoriesFeature {
     var repositories: IdentifiedArrayOf<Repository> = []
     var repositoryRoots: [URL] = []
     var loadFailuresByID: [Repository.ID: String] = [:]
+    /// Remote repositories whose SSH listing is still resolving (shown with a
+    /// loading spinner). Cleared per repo as each `.remoteRepositoryResolved`
+    /// lands; a repo here with no `loadFailuresByID` entry is "loading", one
+    /// with a failure is "can't reach".
+    var resolvingRemoteRepositoryIDs: Set<Repository.ID> = []
     var selection: SidebarSelection?
     var isOpenPanelPresented = false
     var isInitialLoadComplete = false
     var pendingWorktrees: [PendingWorktree] = []
+    /// In-flight customization payloads, keyed by `(repositoryID, branchName)`
+    /// so the New Worktree prompt's `submit` delegate can hand title / color
+    /// off without bloating four action signatures in the creation chain.
+    /// Drained when the `PendingWorktree` materialises in `createWorktreeInRepository`,
+    /// or on a prompt cancel / dismiss.
+    var pendingCreationCustomizations: [Repository.ID: [String: PendingWorktree.Customization]] = [:]
     /// In-flight repo-level removals keyed by repository id. Each record
     /// carries the disposition (only `.gitRepositoryUnlink` / `.folderUnlink`
     /// / `.folderTrash`) and the id of the owning batch aggregator that
@@ -136,6 +148,13 @@ struct RepositoriesFeature {
     /// system-driven cleanup promotions.
     var worktreeHistoryBackStack: [Worktree.ID] = []
     var worktreeHistoryForwardStack: [Worktree.ID] = []
+    /// Worktree MRU stack — most-recent-first, deduped. Updated whenever a
+    /// concrete worktree selection lands (both the `setSingleWorktreeSelection`
+    /// hotkey/palette path and the `reduceSelectionChangedEffect` sidebar path);
+    /// the selected worktree moves to the head. Drives the ⌘P worktree switcher
+    /// sort, so ⌘P then Enter is a Cmd+Tab-style toggle between the two most
+    /// recent worktrees. Session-only; not persisted.
+    var worktreeMRU: [Worktree.ID] = []
     /// Single source of truth for all user-curated sidebar state —
     /// section order / collapse / pin / unpin / archive / focused
     /// worktree — persisted to `~/.supacode/sidebar.json`. Replaces
@@ -166,7 +185,9 @@ struct RepositoriesFeature {
     var toolbarNotificationGroupsCache: [ToolbarNotificationRepositoryGroup] = []
     @Presents var worktreeCreationPrompt: WorktreeCreationPromptFeature.State?
     @Presents var repositoryCustomization: RepositoryCustomizationFeature.State?
+    @Presents var worktreeCustomization: WorktreeCustomizationFeature.State?
     @Presents var renameBranchPrompt: RenameBranchFeature.State?
+    @Presents var remoteConnectionForm: RemoteConnectionFormFeature.State?
     @Presents var alert: AlertState<Alert>?
 
     // MARK: - Sidebar items (per-row TCA collection).
@@ -242,6 +263,14 @@ struct RepositoriesFeature {
     /// the view reads to assign ⌃1..⌃0 hotkeys).
     case sidebarNestByBranchChanged
     case setOpenPanelPresented(Bool)
+    case requestAddRemoteRepository
+    case requestEditRemoteRepository(Repository.ID)
+    case remoteConnectionForm(PresentationAction<RemoteConnectionFormFeature.Action>)
+    case removeRemoteRepository(Repository.ID)
+    /// Kick off async SSH resolution of every persisted remote config; streams
+    /// one `.remoteRepositoryResolved` per repo as each finishes.
+    case resolveRemoteRepositories
+    case remoteRepositoryResolved(repositoryID: Repository.ID, repository: Repository, failureMessage: String?)
     case loadPersistedRepositories
     case refreshWorktrees
     case reloadRepositories(animated: Bool)
@@ -270,6 +299,7 @@ struct RepositoriesFeature {
     case worktreeHistoryBack
     case worktreeHistoryForward
     case revealSelectedWorktreeInSidebar
+    case revealHoistedWorktreeInSidebar(Worktree.ID)
     case consumePendingSidebarReveal(Int)
     case createRandomWorktree
     case createRandomWorktreeInRepository(Repository.ID)
@@ -394,10 +424,12 @@ struct RepositoriesFeature {
     case delayedPullRequestRefresh(Worktree.ID)
     case openRepositorySettings(Repository.ID)
     case requestCustomizeRepository(Repository.ID)
+    case requestCustomizeWorktree(Worktree.ID, Repository.ID)
     case requestRenameBranch(Worktree.ID, Repository.ID)
     case contextMenuOpenWorktree(Worktree.ID, OpenWorktreeAction)
     case worktreeCreationPrompt(PresentationAction<WorktreeCreationPromptFeature.Action>)
     case repositoryCustomization(PresentationAction<RepositoryCustomizationFeature.Action>)
+    case worktreeCustomization(PresentationAction<WorktreeCustomizationFeature.Action>)
     case renameBranchPrompt(PresentationAction<RenameBranchFeature.Action>)
     case alert(PresentationAction<Alert>)
     case delegate(Delegate)
@@ -467,204 +499,306 @@ struct RepositoriesFeature {
   @Dependency(\.date.now) private var now
   @Dependency(\.uuid) private var uuid
 
-  var body: some Reducer<State, Action> {
+  /// Host-aware git client: the SSH flavor for a remote worktree (so branch /
+  /// diff lookups run on the host), the injected local client otherwise.
+  private func gitClient(for worktree: Worktree) -> GitClientDependency {
+    guard let host = worktree.host else {
+      return gitClient
+    }
+    return .ssh(host: host)
+  }
+
+  /// Host-aware git client for a repository: the SSH flavor for a remote repo
+  /// (so branch availability / inventory lookups run on the host), the injected
+  /// local client otherwise.
+  private func gitClient(for repository: Repository) -> GitClientDependency {
+    guard let host = repository.host else {
+      return gitClient
+    }
+    return .ssh(host: host)
+  }
+
+  /// Present the connection form seeded from the existing remote for `repositoryID`.
+  /// The id is self-descriptive, so it parses straight back into host + path; a
+  /// failed / disconnected remote (which has no loaded `Repository`) is still
+  /// editable.
+  static func presentRemoteConnectionEditForm(_ repositoryID: Repository.ID, state: inout State) {
+    guard let (host, remotePath) = Self.parseRemoteRoot(repositoryID.rawValue) else { return }
+    state.remoteConnectionForm = RemoteConnectionFormFeature.State.editing(
+      host: host, remotePath: remotePath, repositoryID: repositoryID)
+  }
+
+  /// Persist a validated remote connection (add or replace), dropping the
+  /// now-orphaned per-repo customization when a host/path edit re-keys the id,
+  /// then dismiss the form and reload.
+  static func saveRemoteConnection(host: RemoteHost, remotePath: String, state: inout State) -> Effect<Action> {
+    let originalRepositoryID: Repository.ID?
+    if case .edit(let editedID) = state.remoteConnectionForm?.mode {
+      originalRepositoryID = editedID
+    } else {
+      originalRepositoryID = nil
+    }
+    let newID = Self.remoteRepositoryID(host: host, remotePath: remotePath)
+    @Shared(.remoteRepositoryRoots) var remoteRepositoryRoots
+    $remoteRepositoryRoots.withLock { roots in
+      // Replace the edited entry in place; for an add, dedupe on the derived id
+      // (host authority + port + path) so a second identical connection isn't a
+      // duplicate row while a port-distinct one stays separate.
+      if let originalRepositoryID, let index = roots.firstIndex(of: originalRepositoryID.rawValue) {
+        roots[index] = newID.rawValue
+      } else if !roots.contains(newID.rawValue) {
+        roots.append(newID.rawValue)
+      }
+    }
+    if let originalRepositoryID, originalRepositoryID != newID {
+      state.$sidebar.withLock { $0.sections[originalRepositoryID] = nil }
+    }
+    state.remoteConnectionForm = nil
+    // Full reload so the remote repo materializes even with no local roots.
+    return .send(.loadPersistedRepositories)
+  }
+
+  /// Removal / delete / unpin + repo-removal handlers, peeled out of `body` so each `Reduce`
+  /// closure stays under the Swift type-checker's complexity limit (mirrors
+  /// `remoteConnectionFormReducer`). Runs after the main `Reduce`, before the post-reduce hook.
+  var worktreeArchiveReducer: some Reducer<State, Action> {
     Reduce { state, action in
       switch action {
-      case .task:
-        // `sidebar` is already hydrated from `sidebar.json` (loaded
-        // synchronously by the SharedKey when State is constructed),
-        // so `.task` has no persistence fan-out left — it just flags
-        // the focus restore and kicks off the repository load.
-        state.shouldRestoreLastFocusedWorktree = state.sidebar.focusedWorktreeID != nil
-        return .send(.loadPersistedRepositories)
-
-      case .sidebarGroupingTogglesChanged:
-        // The post-reduce hook below picks up the toggle state and rebuilds.
-        // Auto-dismiss the highlight onboarding card when both toggles end up
-        // off; the `SidebarCommands` menu setters fire the same dismiss so
-        // toggling while the sidebar column is collapsed is also covered.
-        @Shared(.sidebarGroupPinnedRows) var groupPinned
-        @Shared(.sidebarGroupActiveRows) var groupActive
-        if !groupPinned, !groupActive {
-          @Shared(.appStorage("highlightRelevantOnboardingDismissedAt"))
-          var dismissedAt: Date = .distantPast
-          if !HighlightRelevantOnboardingCardView.isDismissed(at: dismissedAt) {
-            $dismissedAt.withLock { $0 = now }
+      case .requestArchiveWorktree(let worktreeID, let repositoryID):
+        if state.removingRepositoryIDs[repositoryID] != nil {
+          return .none
+        }
+        guard let repository = state.repositories[id: repositoryID],
+          let worktree = repository.worktrees[id: worktreeID]
+        else {
+          return .none
+        }
+        // Folder repos have a synthesized main-worktree; archive
+        // targets it via `isMainWorktree` geometry. Surface the
+        // `folderIncompatibleAlert` feedback the deeplink layer
+        // already shows so hotkeys don't silently no-op.
+        if !repository.isGitRepository {
+          state.alert = folderIncompatibleAlert(action: .archive)
+          return .none
+        }
+        if state.isMainWorktree(worktree) {
+          return .none
+        }
+        let lifecycle = state.sidebarItems[id: worktree.id]?.lifecycle
+        if lifecycle == .deleting || lifecycle == .deletingScript {
+          return .none
+        }
+        if lifecycle == .archiving {
+          return .none
+        }
+        if state.isWorktreeArchived(worktree.id) {
+          return .none
+        }
+        if state.isWorktreeMerged(worktree) {
+          return .send(.archiveWorktreeConfirmed(worktree.id, repository.id))
+        }
+        @Shared(.settingsFile) var settingsFile
+        let archivedDisplay =
+          AppShortcuts.archivedWorktrees
+          .effective(from: settingsFile.global.shortcutOverrides)?.display ?? "none"
+        let alertWorktreeName =
+          SidebarDisplayName.resolved(
+            custom: state.sidebarItems[id: worktree.id]?.customTitle,
+            fallback: worktree.name
+          ) ?? worktree.name
+        state.alert = AlertState {
+          TextState("Archive worktree?")
+        } actions: {
+          ButtonState(role: .destructive, action: .confirmArchiveWorktree(worktree.id, repository.id)) {
+            TextState("Archive worktree")
+          }
+          ButtonState(role: .cancel) {
+            TextState("Cancel")
           }
+        } message: {
+          TextState(
+            "You can find \(alertWorktreeName) later in Menu Bar > Worktrees > Archived Worktrees (\(archivedDisplay))."
+          )
         }
         return .none
 
-      case .sidebarNestByBranchChanged:
-        // No-op handler: the post-reduce hook reads `sidebarNestWorktreesByBranch`
-        // and rebuilds `sidebarStructure` so the alphabetical per-bucket sort
-        // lands in `slotByID` / `hotkeySlots`.
-        return .none
-
-      case .setOpenPanelPresented(let isPresented):
-        state.isOpenPanelPresented = isPresented
-        return .none
-
-      case .loadPersistedRepositories:
-        state.alert = nil
-        state.isRefreshingWorktrees = false
-        return .run { send in
-          let loadedPaths = await repositoryPersistence.loadRoots()
-          let rootPaths = RepositoryPathNormalizer.normalize(loadedPaths)
-          let roots = rootPaths.map { URL(fileURLWithPath: $0) }
-          let (repositories, failures) = await loadRepositoriesData(roots)
-          await send(
-            .repositoriesLoaded(
-              repositories,
-              failures: failures,
-              roots: roots,
-              animated: false
-            )
+      case .requestArchiveWorktrees(let targets):
+        var validTargets: [ArchiveWorktreeTarget] = []
+        var seenWorktreeIDs: Set<Worktree.ID> = []
+        for target in targets {
+          guard seenWorktreeIDs.insert(target.worktreeID).inserted else { continue }
+          if state.removingRepositoryIDs[target.repositoryID] != nil {
+            continue
+          }
+          guard let repository = state.repositories[id: target.repositoryID],
+            let worktree = repository.worktrees[id: target.worktreeID]
+          else {
+            continue
+          }
+          let lifecycle = state.sidebarItems[id: worktree.id]?.lifecycle ?? .idle
+          if state.isMainWorktree(worktree)
+            || lifecycle != .idle
+            || state.isWorktreeArchived(worktree.id)
+          {
+            continue
+          }
+          validTargets.append(target)
+        }
+        guard !validTargets.isEmpty else {
+          return .none
+        }
+        if validTargets.count == 1, let target = validTargets.first {
+          return .send(.requestArchiveWorktree(target.worktreeID, target.repositoryID))
+        }
+        let count = validTargets.count
+        @Shared(.settingsFile) var settingsFile
+        let archivedDisplay =
+          AppShortcuts.archivedWorktrees
+          .effective(from: settingsFile.global.shortcutOverrides)?.display ?? "none"
+        state.alert = AlertState {
+          TextState("Archive \(count) worktrees?")
+        } actions: {
+          ButtonState(role: .destructive, action: .confirmArchiveWorktrees(validTargets)) {
+            TextState("Archive \(count) worktrees")
+          }
+          ButtonState(role: .cancel) {
+            TextState("Cancel")
+          }
+        } message: {
+          TextState(
+            "You can find them later in Menu Bar > Worktrees > Archived Worktrees (\(archivedDisplay))."
           )
         }
-        .cancellable(id: CancelID.load, cancelInFlight: true)
+        return .none
 
-      case .refreshWorktrees:
-        state.isRefreshingWorktrees = true
-        return .send(.reloadRepositories(animated: false))
+      case .alert(.presented(.confirmArchiveWorktree(let worktreeID, let repositoryID))):
+        return .send(.archiveWorktreeConfirmed(worktreeID, repositoryID))
 
-      case .reloadRepositories(let animated):
-        // Deliberately NOT clearing `state.alert` here —
-        // `.reloadRepositories` is a data-layer refresh and fires
-        // from both user intents (refresh hotkey) and downstream of
-        // delete/archive flows. Wiping a just-set terminal alert
-        // (e.g. the consolidated trash-failure alert the aggregator
-        // set before firing `.repositoriesRemoved` → `.repositoriesLoaded`
-        // → `.autoDeleteExpiredArchivedWorktrees`) was the source
-        // of an observable "failure alert vanishes on the same
-        // tick" bug. Confirmation-style alerts are already cleared
-        // by their own confirm handlers upstream of this action.
-        let roots = state.repositoryRoots
-        guard !roots.isEmpty else {
-          state.isRefreshingWorktrees = false
+      case .alert(.presented(.confirmArchiveWorktrees(let targets))):
+        return .merge(
+          targets.map { target in
+            .send(.archiveWorktreeConfirmed(target.worktreeID, target.repositoryID))
+          }
+        )
+
+      case .scriptCompleted(let worktreeID, let scriptID, let kind, let exitCode, let tabId):
+        guard state.sidebarItems[id: worktreeID]?.runningScripts[id: scriptID] != nil else {
+          repositoriesLogger.debug("Ignoring scriptCompleted for \(worktreeID)/\(scriptID): not tracked")
           return .none
         }
-        return loadRepositories(roots, animated: animated)
-
-      case .repositoriesLoaded(let repositories, let failures, let roots, let animated):
-        state.isRefreshingWorktrees = false
-        let previousSelection = state.selectedWorktreeID
-        let previousSelectedWorktree = state.worktree(for: previousSelection)
-        let incomingRepositories = IdentifiedArray(uniqueElements: repositories)
-        let repositoriesChanged = incomingRepositories != state.repositories
-        _ = applyRepositories(
-          repositories,
-          roots: roots,
-          shouldPruneArchivedWorktreeIDs: failures.isEmpty,
-          state: &state,
-          animated: animated
-        )
-        state.repositoryRoots = roots
-        state.isInitialLoadComplete = true
-        state.loadFailuresByID = Dictionary(
-          uniqueKeysWithValues: failures.map { ($0.rootID, $0.message) }
+        let stopEffect: Effect<Action> = .send(
+          .sidebarItems(.element(id: worktreeID, action: .runningScriptStopped(id: scriptID)))
         )
-        state.dropStaleFailedRepositorySelection()
-        let selectedWorktree = state.worktree(for: state.selectedWorktreeID)
-        let selectionChanged = state.hasSelectionChanged(
-          previousSelectionID: previousSelection,
-          previousSelectedWorktree: previousSelectedWorktree,
-          selectedWorktreeID: state.selectedWorktreeID,
-          selectedWorktree: selectedWorktree,
+        guard let exitCode, exitCode != 0 else { return stopEffect }
+        state.alert = blockingScriptFailureAlert(
+          kind: kind,
+          exitCode: exitCode,
+          worktreeID: worktreeID,
+          tabId: tabId,
+          state: state
         )
-        var allEffects: [Effect<Action>] = []
-        if repositoriesChanged {
-          allEffects.append(.send(.delegate(.repositoriesChanged(state.repositories))))
+        return stopEffect
+
+      case .archiveWorktreeConfirmed(let worktreeID, let repositoryID):
+        guard let repository = state.repositories[id: repositoryID],
+          let worktree = repository.worktrees[id: worktreeID]
+        else {
+          return .none
         }
-        if selectionChanged {
-          allEffects.append(.send(.delegate(.selectedWorktreeChanged(selectedWorktree))))
+        if state.isWorktreeArchived(worktreeID)
+          || state.sidebarItems[id: worktreeID]?.lifecycle == .archiving
+        {
+          state.alert = nil
+          return .none
         }
-        // The sidebar reconciler (`reconcileSidebarState`) already
-        // flushed any sidebar mutations through `$sidebar.withLock`,
-        // so no per-slice save effects are needed here — the SharedKey
-        // writes `sidebar.json` atomically.
-        if state.autoDeleteArchivedWorktreesAfterDays != nil {
-          allEffects.append(.send(.autoDeleteExpiredArchivedWorktrees))
+        state.alert = nil
+        @Shared(.repositorySettings(worktree.repositoryRootURL, host: worktree.host)) var repositorySettings
+        let script = repositorySettings.archiveScript
+        let trimmed = script.trimmingCharacters(in: .whitespacesAndNewlines)
+        // Orphan rows have no working dir to run a script in; skip
+        // straight to the apply step so the cleanup still completes.
+        if trimmed.isEmpty || worktree.isMissing {
+          return .send(.archiveWorktreeApply(worktreeID, repositoryID))
         }
-        return .merge(allEffects)
+        return .merge(
+          state.setRowLifecycleEffect(worktreeID, .archiving),
+          .send(
+            .delegate(.runBlockingScript(worktree, repositoryID: repositoryID, kind: .archive, script: script))
+          )
+        )
 
-      case .openRepositories(let urls):
-        analyticsClient.capture("repository_added", ["count": urls.count])
-        state.alert = nil
-        return .run { send in
-          let loadedPaths = await repositoryPersistence.loadRoots()
-          let existingRootPaths = RepositoryPathNormalizer.normalize(loadedPaths)
-          var resolvedRoots: [URL] = []
-          var invalidRoots: [String] = []
-          for url in urls {
-            do {
-              let root = try await gitClient.repoRoot(url)
-              resolvedRoots.append(root)
-            } catch {
-              // `gitClient.repoRoot` throws for non-git paths, but
-              // also for transient `wt` / subprocess failures. To
-              // avoid silently reclassifying a git repo as a folder
-              // on transient errors, double-check via the injected
-              // `gitClient.isGitRepository` — if the path actually
-              // has `.git`, surface the original error as an invalid
-              // root. Non-git readable directories are accepted as
-              // folder-kind repositories.
-              let standardized = url.standardizedFileURL
-              var isDirectory: ObjCBool = false
-              let exists = FileManager.default.fileExists(
-                atPath: standardized.path(percentEncoded: false),
-                isDirectory: &isDirectory
-              )
-              if exists, isDirectory.boolValue,
-                await !gitClient.isGitRepository(standardized)
-              {
-                resolvedRoots.append(standardized)
-              } else {
-                invalidRoots.append(url.path(percentEncoded: false))
-              }
-            }
-          }
-          let resolvedRootPaths = RepositoryPathNormalizer.normalize(
-            resolvedRoots.map { $0.path(percentEncoded: false) }
-          )
-          let mergedPaths = RepositoryPathNormalizer.normalize(existingRootPaths + resolvedRootPaths)
-          let mergedRoots = mergedPaths.map { URL(fileURLWithPath: $0) }
-          await repositoryPersistence.saveRoots(mergedPaths)
-          let (repositories, failures) = await loadRepositoriesData(mergedRoots)
-          await send(
-            .openRepositoriesFinished(
-              repositories,
-              failures: failures,
-              invalidRoots: invalidRoots,
-              roots: mergedRoots
+      case .archiveScriptCompleted(let worktreeID, let exitCode, let tabId):
+        guard state.sidebarItems[id: worktreeID]?.lifecycle == .archiving else {
+          repositoriesLogger.debug("Ignoring archiveScriptCompleted for \(worktreeID): not archiving")
+          return .none
+        }
+        let resetLifecycle = state.setRowLifecycleEffect(worktreeID, .idle)
+        switch exitCode {
+        case 0:
+          guard let repositoryID = state.repositoryID(containing: worktreeID) else {
+            repositoriesLogger.warning(
+              "Archive script succeeded but repository not found for worktree \(worktreeID)"
+            )
+            state.alert = messageAlert(
+              title: "Archive failed",
+              message: "The archive script completed successfully, but the worktree could not be found."
+                + " It may have been removed."
             )
+            return resetLifecycle
+          }
+          return .merge(resetLifecycle, .send(.archiveWorktreeApply(worktreeID, repositoryID)))
+        case nil:
+          repositoriesLogger.debug("Archive script cancelled or tab closed for worktree \(worktreeID)")
+          return resetLifecycle
+        case let code?:
+          state.alert = blockingScriptFailureAlert(
+            kind: .archive, exitCode: code, worktreeID: worktreeID, tabId: tabId, state: state
           )
+          return resetLifecycle
         }
-        .cancellable(id: CancelID.load, cancelInFlight: true)
 
-      case .openRepositoriesFinished(let repositories, let failures, let invalidRoots, let roots):
-        state.isRefreshingWorktrees = false
-        let previousSelection = state.selectedWorktreeID
-        let previousSelectedWorktree = state.worktree(for: previousSelection)
-        _ = applyRepositories(
-          repositories,
-          roots: roots,
-          shouldPruneArchivedWorktreeIDs: failures.isEmpty,
-          state: &state,
-          animated: false
-        )
-        state.repositoryRoots = roots
-        state.isInitialLoadComplete = true
-        state.loadFailuresByID = Dictionary(
-          uniqueKeysWithValues: failures.map { ($0.rootID, $0.message) }
-        )
-        state.dropStaleFailedRepositorySelection()
-        if !invalidRoots.isEmpty {
-          let message = invalidRoots.map { "Supacode couldn't read \($0)." }.joined(separator: "\n")
+      case .archiveWorktreeApply(let worktreeID, let repositoryID):
+        guard let repository = state.repositories[id: repositoryID],
+          let worktree = repository.worktrees[id: worktreeID]
+        else {
+          repositoriesLogger.warning(
+            "archiveWorktreeApply: worktree \(worktreeID) not found in repository \(repositoryID)"
+          )
           state.alert = messageAlert(
-            title: "Some items couldn't be opened",
-            message: message
+            title: "Archive failed",
+            message: "The worktree could not be found. It may have already been removed."
           )
+          return .none
+        }
+        if state.isWorktreeArchived(worktreeID) {
+          state.alert = nil
+          return .none
+        }
+        let previousSelection = state.selectedWorktreeID
+        let previousSelectedWorktree = state.worktree(for: previousSelection)
+        let selectionWasRemoved = state.selectedWorktreeID == worktree.id
+        let nextSelection =
+          selectionWasRemoved
+          ? state.nextWorktreeID(afterRemoving: worktree, in: repository)
+          : nil
+        withAnimation {
+          state.alert = nil
+          // Drop the item from its current pinned/unpinned bucket
+          // and insert into `.archived` with the timestamp. The
+          // seed pass in `reconcileSidebarState` guarantees every
+          // live non-main worktree lives in either `.pinned` or
+          // `.unpinned` before this runs.
+          state.$sidebar.withLock { sidebar in
+            let from = sidebar.currentBucket(of: worktreeID, in: repositoryID) ?? .unpinned
+            sidebar.archive(worktree: worktreeID, in: repositoryID, from: from, at: now)
+          }
+          if selectionWasRemoved {
+            let nextWorktreeID = nextSelection ?? state.firstAvailableWorktreeID(in: repositoryID)
+            state.selection = nextWorktreeID.map(SidebarSelection.worktree)
+          }
+          Self.syncSidebar(&state)
         }
+        let repositories = state.repositories
         let selectedWorktree = state.worktree(for: state.selectedWorktreeID)
         let selectionChanged = state.hasSelectionChanged(
           previousSelectionID: previousSelection,
@@ -672,451 +806,919 @@ struct RepositoriesFeature {
           selectedWorktreeID: state.selectedWorktreeID,
           selectedWorktree: selectedWorktree,
         )
-        var allEffects: [Effect<Action>] = [
-          .send(.delegate(.repositoriesChanged(state.repositories)))
+        var effects: [Effect<Action>] = [
+          .send(.delegate(.repositoriesChanged(repositories)))
         ]
         if selectionChanged {
-          allEffects.append(.send(.delegate(.selectedWorktreeChanged(selectedWorktree))))
-        }
-        // See `.repositoriesLoaded` above for why no per-slice save
-        // effects run here — sidebar mutations already flushed.
-        if state.autoDeleteArchivedWorktreesAfterDays != nil {
-          allEffects.append(.send(.autoDeleteExpiredArchivedWorktrees))
+          effects.append(.send(.delegate(.selectedWorktreeChanged(selectedWorktree))))
         }
-        return .merge(allEffects)
-
-      case .selectionChanged(let selections, let focusTerminal):
-        return state.reduceSelectionChangedEffect(
-          selections: selections,
-          focusTerminal: focusTerminal,
-        )
+        return .merge(effects)
 
-      case .repositoryExpansionChanged(let repositoryID, let isExpanded):
-        state.$sidebar.withLock { sidebar in
-          // Writing the explicit bit (true / false) instead of
-          // adding/removing from a set lets future default-flip
-          // logic distinguish "user expanded" from "never touched".
-          sidebar.sections[repositoryID, default: .init()].collapsed = !isExpanded
+      case .unarchiveWorktree(let worktreeID):
+        guard let repositoryID = state.repositoryID(containing: worktreeID),
+          state.sidebar.sections[repositoryID]?.buckets[.archived]?.items[worktreeID] != nil
+        else {
+          return .none
         }
-        return .none
-
-      case .branchNestExpansionChanged(let repositoryID, let bucketID, let prefix, let isExpanded):
-        // Only `.pinned` / `.unpinned` render nested rows; `.archived` has no
-        // chevron and would just bloat `sidebar.json` with dead entries. Also
-        // refuse to materialize a phantom section for an unknown repo: the
-        // chevron is unreachable without an existing section, so anything
-        // hitting this path with a missing repository is stale UI / deeplink
-        // noise rather than a legitimate intent.
-        guard bucketID != .archived, state.sidebar.sections[repositoryID] != nil else { return .none }
-        state.$sidebar.withLock { sidebar in
-          guard var section = sidebar.sections[repositoryID] else { return }
-          var bucket = section.buckets[bucketID] ?? .init()
-          if isExpanded {
-            bucket.collapsedBranchPrefixes.remove(prefix)
-          } else {
-            bucket.collapsedBranchPrefixes.insert(prefix)
+        withAnimation {
+          state.$sidebar.withLock { sidebar in
+            sidebar.unarchive(worktree: worktreeID, in: repositoryID)
           }
-          section.buckets[bucketID] = bucket
-          sidebar.sections[repositoryID] = section
-        }
-        return .none
-
-      case .selectArchivedWorktrees:
-        state.selection = .archivedWorktrees
-        state.sidebarSelectedWorktreeIDs = []
-        return .send(.delegate(.selectedWorktreeChanged(nil)))
-
-      case .setSidebarSelectedWorktreeIDs(let worktreeIDs):
-        let validWorktreeIDs = state.selectableWorktreeIDs
-        var nextWorktreeIDs = worktreeIDs.intersection(validWorktreeIDs)
-        if let selectedWorktreeID = state.selectedWorktreeID, validWorktreeIDs.contains(selectedWorktreeID) {
-          nextWorktreeIDs.insert(selectedWorktreeID)
+          Self.syncSidebar(&state)
         }
-        state.sidebarSelectedWorktreeIDs = nextWorktreeIDs
-        return .none
+        let repositories = state.repositories
+        return .send(.delegate(.repositoriesChanged(repositories)))
 
-      case .selectWorktree(let worktreeID, let focusTerminal):
-        state.setSingleWorktreeSelection(worktreeID)
-        let selectedWorktree = state.worktree(for: worktreeID)
-        var effects: [Effect<Action>] = [
-          .send(.delegate(.selectedWorktreeChanged(selectedWorktree)))
-        ]
-        if focusTerminal, let worktreeID, state.sidebarItems[id: worktreeID] != nil {
-          effects.append(
-            .send(.sidebarItems(.element(id: worktreeID, action: .focusTerminalRequested)))
-          )
+      case .requestDeleteSidebarItems(let targets):
+        // Kind discriminator: folders skip the main-worktree guard
+        // (their synthetic worktree IS main). Mixed kind selections
+        // get rejected, the context menu already blocks mixed
+        // bulk, so this only trips if a hotkey somehow routes a
+        // heterogeneous selection here.
+        var validTargets: [DeleteWorktreeTarget] = []
+        var validKinds: Set<SidebarItemFeature.State.Kind> = []
+        var seenWorktreeIDs: Set<Worktree.ID> = []
+        var rejectedMainWorktreeCount = 0
+        for target in targets {
+          guard seenWorktreeIDs.insert(target.worktreeID).inserted,
+            state.removingRepositoryIDs[target.repositoryID] == nil,
+            let repository = state.repositories[id: target.repositoryID],
+            let worktree = repository.worktrees[id: target.worktreeID]
+          else { continue }
+          let lifecycle = state.sidebarItems[id: worktree.id]?.lifecycle ?? .idle
+          guard lifecycle == .idle else { continue }
+          if repository.isGitRepository {
+            if state.isMainWorktree(worktree) {
+              rejectedMainWorktreeCount += 1
+              continue
+            }
+            validKinds.insert(.gitWorktree)
+          } else {
+            validKinds.insert(.folder)
+          }
+          validTargets.append(target)
         }
-        return .merge(effects)
-
-      case .selectWorktreeAtHotkeySlot(let index):
-        // Snapshot-driven menu items capture only the slot index, so the
-        // current `hotkeySlots` lookup happens here at action time. Out-of-range
-        // slots beep so the user gets feedback that the shortcut hit nothing.
-        let slots = state.sidebarStructure.hotkeySlots
-        guard slots.indices.contains(index) else {
-          return .run { _ in NSSound.beep() }
+        guard !validTargets.isEmpty, validKinds.count == 1 else {
+          // Single-target main-worktree rejection: surface the same
+          // "Delete not allowed" feedback the deeplink path already
+          // shows, so palette / hotkey / context-menu entries behave
+          // consistently instead of silently no-opping.
+          if targets.count == 1, validTargets.isEmpty, rejectedMainWorktreeCount == 1 {
+            state.alert = messageAlert(
+              title: "Delete not allowed",
+              message: "Deleting the main worktree is not allowed."
+            )
+          }
+          return .none
         }
-        return .send(.selectWorktree(slots[index].id))
-
-      case .selectNextWorktree:
-        guard let id = state.worktreeID(byOffset: 1) else {
-          return .run { _ in NSSound.beep() }
+        let count = validTargets.count
+        if validKinds == [.folder] {
+          let folders = validTargets.compactMap { state.repositories[id: $0.repositoryID] }
+          let namesList = folders.map(\.name)
+            .sorted(by: { $0.localizedCaseInsensitiveCompare($1) == .orderedAscending })
+            .joined(separator: ", ")
+          let title = count == 1 ? "Remove folder?" : "Remove \(count) folders?"
+          let messageSubject = count == 1 ? folders.first?.name ?? "this folder" : namesList
+          let stayOnDiskCopy =
+            count == 1
+            ? "managing the folder (it stays on disk)"
+            : "managing the folders (they stay on disk)"
+          let trashCopy =
+            count == 1 ? "move the folder to the Trash" : "move them to the Trash"
+          state.alert = AlertState {
+            TextState(title)
+          } actions: {
+            ButtonState(
+              action: .confirmDeleteSidebarItems(validTargets, disposition: .folderUnlink)
+            ) {
+              TextState("Remove from Supacode")
+            }
+            ButtonState(
+              role: .destructive,
+              action: .confirmDeleteSidebarItems(validTargets, disposition: .folderTrash)
+            ) {
+              TextState("Delete from disk")
+            }
+            ButtonState(role: .cancel) {
+              TextState("Cancel")
+            }
+          } message: {
+            TextState(
+              "Remove \(messageSubject)? Choose \"Remove from Supacode\" to stop "
+                + stayOnDiskCopy
+                + ", or \"Delete from disk\" to " + trashCopy + "."
+            )
+          }
+          return .none
         }
-        return .send(.selectWorktree(id))
-
-      case .selectPreviousWorktree:
-        guard let id = state.worktreeID(byOffset: -1) else {
-          return .run { _ in NSSound.beep() }
+        @Shared(.settingsFile) var settingsFile
+        let deleteBranchOnDeleteWorktree = settingsFile.global.deleteBranchOnDeleteWorktree
+        let allMissing = validTargets.allSatisfy { target in
+          state.repositories[id: target.repositoryID]?.worktrees[id: target.worktreeID]?.isMissing
+            == true
         }
-        return .send(.selectWorktree(id))
-
-      case .worktreeHistoryBack:
-        return state.navigateWorktreeHistoryEffect(direction: .back)
-
-      case .worktreeHistoryForward:
-        return state.navigateWorktreeHistoryEffect(direction: .forward)
-
-      case .revealSelectedWorktreeInSidebar:
-        guard let worktreeID = state.selectedWorktreeID,
-          let repositoryID = state.repositoryID(containing: worktreeID)
-        else { return .none }
-        // Resolve outside the lock to keep the critical section short.
-        let branchName = state.sidebarItems[id: worktreeID]?.branchName
-        let containingBucket = state.sidebar.currentBucket(of: worktreeID, in: repositoryID)
-        state.$sidebar.withLock { sidebar in
-          sidebar.sections[repositoryID, default: .init()].collapsed = false
-          // Uncollapse any ancestor branch prefix so a reveal / deeplink to
-          // `feature/tools/api` doesn't leave the row hidden inside a
-          // collapsed `feature/tools` group header.
-          guard let branchName, let bucketID = containingBucket, bucketID != .archived else { return }
-          let ancestors = Set(SidebarBranchNesting.ancestorPrefixes(of: branchName))
-          guard !ancestors.isEmpty,
-            var bucket = sidebar.sections[repositoryID]?.buckets[bucketID]
-          else { return }
-          let next = bucket.collapsedBranchPrefixes.subtracting(ancestors)
-          guard next != bucket.collapsedBranchPrefixes else { return }
-          bucket.collapsedBranchPrefixes = next
-          sidebar.sections[repositoryID]?.buckets[bucketID] = bucket
+        let title = count == 1 ? "Delete worktree?" : "Delete \(count) worktrees?"
+        let buttonLabel = count == 1 ? "Delete worktree" : "Delete \(count) worktrees"
+        let message: String =
+          switch (count, deleteBranchOnDeleteWorktree, allMissing) {
+          case (1, _, true): "Removes the orphan worktree entry from this repository."
+          case (_, _, true): "Removes \(count) orphan worktree entries from this repository."
+          case (1, true, false): "This deletes the worktree directory and its local branch."
+          case (1, false, false): "This deletes the worktree directory but keeps the local branch."
+          case (_, true, false):
+            "This deletes \(count) worktree directories and their local branches."
+          case (_, false, false):
+            "This deletes \(count) worktree directories but keeps their local branches."
+          }
+        state.alert = AlertState {
+          TextState(title)
+        } actions: {
+          ButtonState(
+            role: .destructive,
+            action: .confirmDeleteSidebarItems(validTargets, disposition: .gitWorktreeDelete)
+          ) {
+            TextState(buttonLabel)
+          }
+          ButtonState(role: .cancel) {
+            TextState("Cancel")
+          }
+        } message: {
+          TextState(message)
         }
-        state.nextPendingSidebarRevealID += 1
-        state.pendingSidebarReveal = .init(id: state.nextPendingSidebarRevealID, worktreeID: worktreeID)
-        return .none
-
-      case .consumePendingSidebarReveal(let pendingSidebarRevealID):
-        guard state.pendingSidebarReveal?.id == pendingSidebarRevealID else { return .none }
-        state.pendingSidebarReveal = nil
         return .none
 
-      case .createRandomWorktree:
-        guard let repository = state.repositoryForWorktreeCreation else {
-          let message: String
-          if state.repositories.isEmpty {
-            message = "Open a repository to create a worktree."
-          } else if state.selectedWorktreeID == nil && state.repositories.count > 1 {
-            message = "Select a worktree to choose which repository to use."
+      case .alert(.presented(.confirmDeleteSidebarItems(let targets, let disposition))):
+        // Kind-and-disposition mapping: folders carry the
+        // disposition into `removingRepositoryIDs` so
+        // `.deleteScriptCompleted` can route by stored choice later.
+        // Git worktrees run the standard per-worktree pipeline and
+        // don't record a repo-level disposition. Kind / disposition
+        // mismatches are impossible under the current alert surface
+        // and a caller bypassing those guards is a bug, so flag it via
+        // `reportIssue` instead of dropping silently.
+        state.alert = nil
+        var validTargets: [DeleteWorktreeTarget] = []
+        var folderBatchIDs: Set<Repository.ID> = []
+        for target in targets {
+          guard let repository = state.repositories[id: target.repositoryID],
+            state.removingRepositoryIDs[target.repositoryID] == nil
+          else { continue }
+          if repository.isGitRepository {
+            guard disposition == .gitWorktreeDelete else {
+              reportIssue(
+                """
+                confirmDeleteSidebarItems: received \(disposition) for git worktree \
+                \(target.worktreeID): git targets only support .gitWorktreeDelete. \
+                Dropping target.
+                """
+              )
+              continue
+            }
           } else {
-            message = "Unable to resolve a repository for the new worktree."
+            guard disposition.isFolder else {
+              reportIssue(
+                """
+                confirmDeleteSidebarItems: received \(disposition) for folder \
+                \(target.repositoryID): folder targets only support .folderUnlink / \
+                .folderTrash. Dropping target.
+                """
+              )
+              continue
+            }
+            folderBatchIDs.insert(target.repositoryID)
           }
-          state.alert = messageAlert(title: "Unable to create worktree", message: message)
-          return .none
+          validTargets.append(target)
         }
-        return .send(.createRandomWorktreeInRepository(repository.id))
+        guard !validTargets.isEmpty else { return .none }
+        if !folderBatchIDs.isEmpty {
+          // All folder targets in this batch share the same
+          // disposition (the alert only ever produces one), so one
+          // record shape per repo keeps disposition + batch id in
+          // lockstep.
+          let batchID = uuid()
+          for repositoryID in folderBatchIDs {
+            state.removingRepositoryIDs[repositoryID] = RepositoryRemovalRecord(
+              disposition: disposition, batchID: batchID
+            )
+          }
+          Self.syncSidebar(&state)
+          state.activeRemovalBatches[batchID] =
+            ActiveRemovalBatch(id: batchID, pending: folderBatchIDs)
+        }
+        return .merge(
+          validTargets.map {
+            .send(.deleteSidebarItemConfirmed($0.worktreeID, $0.repositoryID))
+          }
+        )
 
-      case .createRandomWorktreeInRepository(let repositoryID):
-        guard let repository = state.repositories[id: repositoryID] else {
-          state.alert = messageAlert(
-            title: "Unable to create worktree",
-            message: "Unable to resolve a repository for the new worktree."
+      default:
+        return .none
+      }
+    }
+  }
+
+  /// Delete / remove worktree + repository handlers, split from `worktreeArchiveReducer` so each
+  /// `Reduce` closure stays well under the type-checker's complexity limit.
+  var worktreeRemovalReducer: some Reducer<State, Action> {
+    Reduce { state, action in
+      switch action {
+      case .deleteSidebarItemConfirmed(let worktreeID, let repositoryID):
+        guard let repository = state.repositories[id: repositoryID],
+          let worktree = repository.worktrees[id: worktreeID]
+        else {
+          repositoriesLogger.debug(
+            "deleteSidebarItemConfirmed: worktree \(worktreeID) not found in repository \(repositoryID)."
           )
           return .none
         }
-        // Worktree creation needs a git repository. Folder-kind entries
-        // surface the same menu / hotkey / deeplink path, so reject
-        // them up front with a clear alert instead of letting the
-        // request fall into `gitClient.createWorktreeStream` and fail
-        // with a raw subprocess error.
-        if !repository.isGitRepository {
-          state.alert = messageAlert(
-            title: "Unable to create worktree",
-            message: "Worktrees are only supported for git repositories."
-          )
+        // Lifecycle re-entry guard: only the first tap proceeds; rapid repeats no-op
+        // so the aggregator batch isn't double-drained.
+        let confirmedLifecycle = state.sidebarItems[id: worktree.id]?.lifecycle ?? .idle
+        if confirmedLifecycle == .archiving
+          || confirmedLifecycle == .deleting
+          || confirmedLifecycle == .deletingScript
+        {
           return .none
         }
-        if state.removingRepositoryIDs[repository.id] != nil {
-          state.alert = messageAlert(
-            title: "Unable to create worktree",
-            message: "This repository is being removed."
+        // F4: folder targets only arrive here after the alert's
+        // confirm handler seeded a `RepositoryRemovalRecord`. If a
+        // future caller short-circuits to this action without going
+        // through `.requestDeleteSidebarItems` → confirm, the
+        // aggregator would never drain. Flag the invariant breach
+        // loudly (tests fail, release warns) and bail out early so
+        // we don't fall through to the git-worktree delete path for
+        // a folder.
+        if !repository.isGitRepository,
+          state.removingRepositoryIDs[repository.id] == nil
+        {
+          reportIssue(
+            """
+            deleteSidebarItemConfirmed: folder \(repository.id) missing seeded removal \
+            record. Callers must go through .requestDeleteSidebarItems → \
+            .confirmDeleteSidebarItems so the batch aggregator is set up.
+            """
           )
           return .none
         }
-        @Shared(.settingsFile) var settingsFile
-        if !settingsFile.global.promptForWorktreeCreation {
-          return .merge(
-            .cancel(id: CancelID.worktreePromptLoad),
-            .send(
-              .createWorktreeInRepository(
-                repositoryID: repository.id,
-                nameSource: .random,
-                baseRefSource: .repositorySetting,
-                fetchOrigin: settingsFile.global.fetchOriginBeforeWorktreeCreation
-              )
-            )
-          )
-        }
-        @Shared(.repositorySettings(repository.rootURL)) var repositorySettings
-        let selectedBaseRef = repositorySettings.worktreeBaseRef
-        let gitClient = gitClient
-        let rootURL = repository.rootURL
-        // Resolve the cheap quick-picks (auto ref + matching local
-        // branch) and present the prompt right away, then load the
-        // full local / remote branch lists in the background so the
-        // dialog never blocks on `git for-each-ref`.
-        return .run { send in
-          let automaticBaseRef = await gitClient.automaticWorktreeBaseRef(rootURL) ?? "HEAD"
-          guard !Task.isCancelled else {
-            return
-          }
-          let remoteNames = (try? await gitClient.remoteNames(rootURL)) ?? []
-          let defaultBranch = GitReferenceQueries.localBranchName(
-            fromRemoteRef: automaticBaseRef,
-            remoteNames: remoteNames
-          )
-          guard !Task.isCancelled else {
-            return
-          }
-          await send(
-            .promptedWorktreeCreationDataLoaded(
-              repositoryID: repositoryID,
-              automaticBaseRef: automaticBaseRef,
-              defaultBranch: defaultBranch,
-              remoteNames: remoteNames,
-              selectedBaseRef: selectedBaseRef
+        // NOTE: we do NOT clear `state.alert` here.
+        //   - Alert-confirmed path: `.confirmDeleteSidebarItems`
+        //     already cleared its own confirm alert at entry.
+        //   - Auto-delete / merged-sweep path: this action fires
+        //     programmatically; an unconditional clear here would
+        //     wipe unrelated alerts, specifically the consolidated
+        //     trash-failure alert just set by the batch aggregator.
+        //   - Deeplink path: same, the caller decides alert state.
+        @Shared(.repositorySettings(worktree.repositoryRootURL, host: worktree.host)) var repositorySettings
+        let script = repositorySettings.deleteScript
+        let trimmed = script.trimmingCharacters(in: .whitespacesAndNewlines)
+        // Only folder-row intents (`.folderUnlink` / `.folderTrash`)
+        // route through the folder-removal success branch.
+        // `.gitRepositoryUnlink` is a concurrent git-repo section
+        // removal that has no bearing on this worktree's delete flow.
+        // `nil` is a git worktree delete (no repo-level intent).
+        let folderIntent: DeleteDisposition? = {
+          guard let record = state.removingRepositoryIDs[repository.id],
+            record.disposition.isFolder
+          else { return nil }
+          return record.disposition
+        }()
+        // Orphan rows have no working dir to run a script in; skip the
+        // script and apply the delete directly so the cleanup completes.
+        if trimmed.isEmpty || worktree.isMissing {
+          if let folderIntent {
+            // Empty script: finish the folder flow immediately,
+            // trashing the directory first if the user asked for it.
+            let selectionWasRemoved = state.selectedWorktreeID == worktreeID
+            let trashURL = folderIntent == .folderTrash ? repository.rootURL : nil
+            return .merge(
+              state.setRowLifecycleEffect(worktree.id, .deleting),
+              folderRemovalEffect(
+                repositoryID: repository.id,
+                selectionWasRemoved: selectionWasRemoved,
+                diskDeletionURL: trashURL
+              )
             )
-          )
-          let inventory =
-            (try? await gitClient.branchInventory(rootURL, remoteNames)) ?? GitBranchInventory()
-          guard !Task.isCancelled else {
-            return
           }
-          await send(
-            .promptedWorktreeBranchesLoaded(repositoryID: repositoryID, inventory: inventory)
-          )
-        }
-        .cancellable(id: CancelID.worktreePromptLoad, cancelInFlight: true)
-
-      case .promptedWorktreeCreationDataLoaded(
-        let repositoryID,
-        let automaticBaseRef,
-        let defaultBranch,
-        let remoteNames,
-        let selectedBaseRef
-      ):
-        guard let repository = state.repositories[id: repositoryID] else {
-          return .none
+          return .send(.deleteWorktreeApply(worktreeID, repositoryID))
         }
-        @Shared(.settingsFile) var promptSettingsFile
-        @Shared(.repositorySettings(repository.rootURL)) var promptRepositorySettings
-        let defaultWorktreeBaseDirectory = SupacodePaths.worktreeBaseDirectory(
-          for: repository.rootURL,
-          globalDefaultPath: promptSettingsFile.global.defaultWorktreeBaseDirectoryPath,
-          repositoryOverridePath: promptRepositorySettings.worktreeBaseDirectoryPath
-        )
-        .path(percentEncoded: false)
-        state.worktreeCreationPrompt = WorktreeCreationPromptFeature.State(
-          repositoryID: repository.id,
-          repositoryRootURL: repository.rootURL,
-          repositoryName: repository.name,
-          automaticBaseRef: automaticBaseRef,
-          defaultBranch: defaultBranch,
-          remoteNames: remoteNames,
-          branchMenu: nil,
-          branchName: "",
-          selectedBaseRef: selectedBaseRef,
-          fetchOrigin: promptSettingsFile.global.fetchOriginBeforeWorktreeCreation,
-          defaultWorktreeBaseDirectory: defaultWorktreeBaseDirectory,
-          validationMessage: nil
+        return .merge(
+          state.setRowLifecycleEffect(worktree.id, .deletingScript),
+          .send(
+            .delegate(.runBlockingScript(worktree, repositoryID: repositoryID, kind: .delete, script: script))
+          )
         )
-        return .none
 
-      case .promptedWorktreeBranchesLoaded(let repositoryID, let inventory):
-        guard var prompt = state.worktreeCreationPrompt, prompt.repositoryID == repositoryID else {
+      case .deleteScriptCompleted(let worktreeID, let exitCode, let tabId):
+        guard state.sidebarItems[id: worktreeID]?.lifecycle == .deletingScript else {
+          repositoriesLogger.debug(
+            "Ignoring deleteScriptCompleted for \(worktreeID): not running a delete script."
+          )
           return .none
         }
-        // Drop the default-branch quick pick if no local branch of that name
-        // actually exists (e.g. a fresh clone with only `origin/main`), so it
-        // can't submit a missing ref. Guard on a non-empty inventory so a
-        // failed load doesn't hide a valid quick pick.
-        if !inventory.isEmpty, let defaultBranch = prompt.defaultBranch,
-          !inventory.localBranches.contains(defaultBranch)
-        {
-          prompt.defaultBranch = nil
-        }
-        prompt.branchMenu = BaseRefBranchMenu(
-          inventory: inventory,
-          hoistedLocalBranch: prompt.defaultBranch
-        )
-        // A persisted base ref (from repository settings) can point at a branch
-        // that no longer exists. Fall back to Auto so the prompt doesn't show an
-        // invisible selection and submit a dead ref to `git worktree add`. Only
-        // reconcile against a non-empty inventory so a failed load doesn't wipe a
-        // still-valid ref.
-        if let selectedBaseRef = prompt.selectedBaseRef, !inventory.isEmpty,
-          selectedBaseRef != prompt.automaticBaseRef,
-          !inventory.contains(ref: selectedBaseRef)
-        {
-          prompt.selectedBaseRef = nil
+        let resetLifecycle = state.setRowLifecycleEffect(worktreeID, .idle)
+        // Route by recorded intent, not live classification: a
+        // `git init` mid-script would otherwise flip the check and
+        // lose folder intent. Kind divergence is treated as an
+        // explicit error so the user can decide what to do.
+        let owningRepo = state.repositories.first(where: {
+          $0.worktrees.contains(where: { $0.id == worktreeID })
+        })
+        // Only a folder-row intent (`.folderUnlink` / `.folderTrash`)
+        // routes this completion into repo-level removal.
+        // `.gitRepositoryUnlink` is a concurrent git-repo remove
+        // running independently; it shouldn't hijack the
+        // worktree-delete pipeline. `nil` means plain git worktree
+        // delete.
+        let folderIntent: DeleteDisposition? =
+          owningRepo
+          .flatMap { state.removingRepositoryIDs[$0.id] }
+          .flatMap { $0.disposition.isFolder ? $0.disposition : nil }
+        let followupEffect: Effect<Action>
+        switch exitCode {
+        case 0:
+          if let folderIntent, let owningRepo {
+            if owningRepo.isGitRepository {
+              // Kind flipped between confirmation and completion. Bail out
+              // rather than silently picking a path.
+              state.alert = messageAlert(
+                title: "Folder is now a git repository",
+                message: "Supacode stopped the removal because \(owningRepo.name) became a git "
+                  + "repository while the delete script was running. Review it and try again."
+              )
+              followupEffect = signalFolderRemovalFailure(worktreeID: worktreeID, state: &state)
+            } else {
+              let selectionWasRemoved = state.selectedWorktreeID == worktreeID
+              let trashURL = folderIntent == .folderTrash ? owningRepo.rootURL : nil
+              followupEffect = folderRemovalEffect(
+                repositoryID: owningRepo.id,
+                selectionWasRemoved: selectionWasRemoved,
+                diskDeletionURL: trashURL
+              )
+            }
+          } else if let repositoryID = state.repositoryID(containing: worktreeID) {
+            followupEffect = .send(.deleteWorktreeApply(worktreeID, repositoryID))
+          } else if state.removingRepositoryIDs[RepositoryID(worktreeID.rawValue)]?.disposition.isFolder
+            == true
+          {
+            // Synthetic folder id + open folder record: drain the aggregator
+            // so siblings don't hang. Only surface the alert when no folder
+            // record exists.
+            repositoriesLogger.warning(
+              "Delete script succeeded but repository vanished for folder worktree "
+                + "\(worktreeID); draining batch as failure."
+            )
+            followupEffect = signalFolderRemovalFailure(worktreeID: worktreeID, state: &state)
+          } else {
+            repositoriesLogger.warning(
+              "Delete script succeeded but repository not found for worktree \(worktreeID)"
+            )
+            state.alert = messageAlert(
+              title: "Delete failed",
+              message: "The delete script completed successfully, but the worktree could not be found."
+                + " It may have been removed."
+            )
+            followupEffect = .none
+          }
+        case nil:
+          // User closed the script tab.
+          repositoriesLogger.debug(
+            "Delete script cancelled or tab closed for worktree \(worktreeID).")
+          followupEffect = signalFolderRemovalFailure(worktreeID: worktreeID, state: &state)
+        case let code?:
+          // Script failed. Show the standard failure alert AND for folder
+          // removals signal the aggregator so bulk batches don't hang.
+          // Git worktree delete has no batch.
+          state.alert = blockingScriptFailureAlert(
+            kind: .delete, exitCode: code, worktreeID: worktreeID, tabId: tabId, state: state
+          )
+          followupEffect = signalFolderRemovalFailure(worktreeID: worktreeID, state: &state)
         }
-        state.worktreeCreationPrompt = prompt
-        return .none
-
-      case .worktreeCreationPrompt(.presented(.delegate(.cancel))):
-        state.worktreeCreationPrompt = nil
-        return .merge(
-          .cancel(id: CancelID.worktreePromptLoad),
-          .cancel(id: CancelID.worktreePromptValidation)
-        )
+        return .merge(resetLifecycle, followupEffect)
 
-      case .worktreeCreationPrompt(
-        .presented(
-          .delegate(
-            .submit(let repositoryID, let branchName, let baseRef, let fetchOrigin, let placement)
-          )
-        )
-      ):
-        return .send(
-          .startPromptedWorktreeCreation(
-            repositoryID: repositoryID,
-            branchName: branchName,
-            baseRef: baseRef,
-            fetchOrigin: fetchOrigin,
-            placement: placement
+      case .deleteWorktreeApply(let worktreeID, let repositoryID):
+        guard let repository = state.repositories[id: repositoryID],
+          let worktree = repository.worktrees[id: worktreeID]
+        else {
+          repositoriesLogger.warning(
+            "deleteWorktreeApply: worktree \(worktreeID) not found in repository \(repositoryID)"
           )
-        )
-
-      case .startPromptedWorktreeCreation(
-        let repositoryID,
-        let branchName,
-        let baseRef,
-        let fetchOrigin,
-        let placement
-      ):
-        guard let repository = state.repositories[id: repositoryID] else {
-          state.worktreeCreationPrompt = nil
           state.alert = messageAlert(
-            title: "Unable to create worktree",
-            message: "Unable to resolve a repository for the new worktree."
+            title: "Delete failed",
+            message: "The worktree could not be found. It may have already been removed."
           )
           return .none
         }
-        state.worktreeCreationPrompt?.validationMessage = nil
-        state.worktreeCreationPrompt?.isValidating = true
-        let normalizedBranchName = branchName.lowercased()
-        if repository.worktrees.contains(where: { $0.name.lowercased() == normalizedBranchName }) {
-          state.worktreeCreationPrompt?.isValidating = false
-          state.worktreeCreationPrompt?.validationMessage = "Branch name already exists."
-          return .none
-        }
-        let gitClient = gitClient
-        let rootURL = repository.rootURL
-        return .run { send in
-          let localBranchNames = (try? await gitClient.localBranchNames(rootURL)) ?? []
-          let duplicateMessage =
-            localBranchNames.contains(normalizedBranchName)
-            ? "Branch name already exists."
-            : nil
-          await send(
-            .promptedWorktreeCreationChecked(
-              repositoryID: repositoryID,
-              branchName: branchName,
-              baseRef: baseRef,
-              fetchOrigin: fetchOrigin,
-              placement: placement,
-              duplicateMessage: duplicateMessage
-            )
-          )
-        }
-        .cancellable(id: CancelID.worktreePromptValidation, cancelInFlight: true)
+        let selectionWasRemoved = state.selectedWorktreeID == worktree.id
+        let nextSelection =
+          selectionWasRemoved
+          ? state.nextWorktreeID(afterRemoving: worktree, in: repository)
+          : nil
+        @Shared(.settingsFile) var settingsFile
+        let deleteBranchOnDeleteWorktree = settingsFile.global.deleteBranchOnDeleteWorktree
+        // Host-aware: a remote worktree is removed via `git worktree remove`
+        // over ssh on the host, not against the local checkout.
+        let deleteClient = gitClient(for: worktree)
+        return .merge(
+          state.setRowLifecycleEffect(worktree.id, .deleting),
+          .run { send in
+            do {
+              _ = try await deleteClient.removeWorktree(
+                worktree,
+                deleteBranchOnDeleteWorktree
+              )
+              await send(
+                .worktreeDeleted(
+                  worktree.id,
+                  repositoryID: repository.id,
+                  selectionWasRemoved: selectionWasRemoved,
+                  nextSelection: nextSelection
+                )
+              )
+            } catch {
+              await send(.deleteWorktreeFailed(error.localizedDescription, worktreeID: worktree.id))
+            }
+          }
+        )
 
-      case .promptedWorktreeCreationChecked(
+      case .worktreeDeleted(
+        let worktreeID,
         let repositoryID,
-        let branchName,
-        let baseRef,
-        let fetchOrigin,
-        let placement,
-        let duplicateMessage
+        _,
+        let nextSelection
       ):
-        guard let prompt = state.worktreeCreationPrompt, prompt.repositoryID == repositoryID else {
-          return .none
+        analyticsClient.capture("worktree_deleted", nil)
+        let previousSelection = state.selectedWorktreeID
+        let previousSelectedWorktree = state.worktree(for: previousSelection)
+        withAnimation(.easeOut(duration: 0.2)) {
+          state.pendingWorktrees.removeAll { $0.id == worktreeID }
+          state.resetRowLifecycleSyncBeforeReconcile(itemID: worktreeID)
+          // Drop the worktree from every bucket in its section. The worktree is
+          // going away entirely so its current bucket doesn't matter.
+          state.$sidebar.withLock { sidebar in
+            sidebar.removeAnywhere(worktree: worktreeID, in: repositoryID)
+          }
+          _ = state.removeWorktree(worktreeID, repositoryID: repositoryID)
+          let selectionNeedsUpdate = state.selection == .worktree(worktreeID)
+          if selectionNeedsUpdate {
+            let nextWorktreeID = nextSelection ?? state.firstAvailableWorktreeID(in: repositoryID)
+            state.selection = nextWorktreeID.map(SidebarSelection.worktree)
+          }
+          Self.syncSidebar(&state)
         }
-        state.worktreeCreationPrompt?.isValidating = false
-        if let duplicateMessage {
-          state.worktreeCreationPrompt?.validationMessage = duplicateMessage
-          return .none
+        let roots = state.repositories.map(\.rootURL)
+        let repositories = state.repositories
+        let selectedWorktree = state.worktree(for: state.selectedWorktreeID)
+        let selectionChanged = state.hasSelectionChanged(
+          previousSelectionID: previousSelection,
+          previousSelectedWorktree: previousSelectedWorktree,
+          selectedWorktreeID: state.selectedWorktreeID,
+          selectedWorktree: selectedWorktree,
+        )
+        var immediateEffects: [Effect<Action>] = [
+          .send(.delegate(.repositoriesChanged(repositories)))
+        ]
+        if selectionChanged {
+          immediateEffects.append(.send(.delegate(.selectedWorktreeChanged(selectedWorktree))))
         }
-        state.worktreeCreationPrompt = nil
-        return .send(
-          .createWorktreeInRepository(
-            repositoryID: repositoryID,
-            nameSource: .explicit(branchName),
-            baseRefSource: .explicit(baseRef),
-            fetchOrigin: fetchOrigin,
-            placement: placement
-          )
+        let followupEffects: [Effect<Action>] = [
+          roots.isEmpty ? .none : .send(.reloadRepositories(animated: true))
+        ]
+        return .concatenate(
+          .merge(immediateEffects),
+          .merge(followupEffects)
         )
 
-      case .createWorktreeInRepository(
-        let repositoryID,
-        let nameSource,
-        let baseRefSource,
-        let fetchOrigin,
-        let placement
-      ):
-        guard let repository = state.repositories[id: repositoryID] else {
-          state.alert = messageAlert(
-            title: "Unable to create worktree",
-            message: "Unable to resolve a repository for the new worktree."
-          )
-          return .none
+      case .repositoriesMoved(let offsets, let destination):
+        var ordered = state.orderedRepositoryIDs()
+        guard !offsets.isEmpty, ordered.indices.contains(offsets.min() ?? 0),
+          destination <= ordered.count
+        else { return .none }
+        ordered.move(fromOffsets: offsets, toOffset: destination)
+        withAnimation(.snappy(duration: 0.2)) {
+          state.$sidebar.withLock { sidebar in
+            var reordered: OrderedDictionary<Repository.ID, SidebarState.Section> = [:]
+            for id in ordered {
+              reordered[id] = sidebar.sections[id] ?? .init()
+            }
+            // Sections for repos still loading / not yet seen are
+            // reliably absent from `ordered`; append them in their
+            // original relative order so a live-row reorder doesn't
+            // silently reshuffle curation on them.
+            for (id, section) in sidebar.sections where reordered[id] == nil {
+              reordered[id] = section
+            }
+            sidebar.sections = reordered
+          }
         }
-        // Guard against folder-kind entries arriving here via
-        // deeplink / palette paths that bypass
-        // `.createRandomWorktreeInRepository`.
-        if !repository.isGitRepository {
-          state.alert = messageAlert(
-            title: "Unable to create worktree",
-            message: "Worktrees are only supported for git repositories."
+        return .none
+
+      case .pinnedWorktreesMoved(let repositoryID, let offsets, let destination):
+        guard let repository = state.repositories[id: repositoryID] else { return .none }
+        let currentPinned = state.orderedPinnedWorktreeIDs(in: repository)
+        guard currentPinned.count > 1 else { return .none }
+        var reordered = currentPinned
+        reordered.move(fromOffsets: offsets, toOffset: destination)
+        withAnimation(.snappy(duration: 0.2)) {
+          state.$sidebar.withLock { sidebar in
+            sidebar.reorder(bucket: .pinned, in: repositoryID, to: reordered)
+          }
+          RepositoriesFeature.syncSidebar(&state)
+        }
+        return .none
+
+      case .unpinnedWorktreesMoved(let repositoryID, let offsets, let destination):
+        guard let repository = state.repositories[id: repositoryID] else { return .none }
+        let currentUnpinned = state.orderedUnpinnedWorktreeIDs(in: repository)
+        guard currentUnpinned.count > 1 else { return .none }
+        var reordered = currentUnpinned
+        reordered.move(fromOffsets: offsets, toOffset: destination)
+        withAnimation(.snappy(duration: 0.2)) {
+          state.$sidebar.withLock { sidebar in
+            sidebar.reorder(bucket: .unpinned, in: repositoryID, to: reordered)
+          }
+          RepositoriesFeature.syncSidebar(&state)
+        }
+        return .none
+
+      case .deleteWorktreeFailed(let message, let worktreeID):
+        state.alert = messageAlert(title: "Unable to delete worktree", message: message)
+        guard state.sidebarItems[id: worktreeID]?.lifecycle == .deleting else { return .none }
+        return state.setRowLifecycleEffect(worktreeID, .idle)
+
+      case .requestDeleteRepository(let repositoryID):
+        // Remote repos aren't on disk locally, so removing one just drops its
+        // persisted config + reloads; the remote files are untouched. No
+        // local-removal confirmation flow.
+        if state.repositories[id: repositoryID]?.host != nil {
+          return .send(.removeRemoteRepository(repositoryID))
+        }
+        state.alert = confirmationAlertForRepositoryRemoval(repositoryID: repositoryID, state: state)
+        return .none
+
+      case .requestRemoveFailedRepository(let repositoryID):
+        state.alert = confirmationAlertForFailedRepositoryRemoval(
+          repositoryID: repositoryID, state: state
+        )
+        return .none
+
+      case .removeFailedRepository(let repositoryID):
+        state.loadFailuresByID.removeValue(forKey: repositoryID)
+        state.repositoryRoots.removeAll {
+          RepositoryID($0.standardizedFileURL.path(percentEncoded: false)) == repositoryID
+        }
+        // Drop persisted customization so re-adding the same path doesn't
+        // silently restore the old title/color, matching the healthy-repo path.
+        state.$sidebar.withLock { sidebar in
+          _ = sidebar.sections.removeValue(forKey: repositoryID)
+        }
+        state.dropStaleFailedRepositorySelection()
+        return .run { send in
+          let loadedPaths = await repositoryPersistence.loadRoots()
+          var seen: Set<String> = []
+          let rootPaths = loadedPaths.filter { seen.insert($0).inserted }
+          let remaining = rootPaths.filter { $0 != repositoryID.rawValue }
+          await repositoryPersistence.saveRoots(remaining)
+          await repositoryPersistence.pruneRepositoryConfigs([repositoryID.rawValue])
+          let roots = remaining.map { URL(fileURLWithPath: $0) }
+          let (repositories, failures) = await loadRepositoriesData(roots)
+          await send(
+            .repositoriesLoaded(
+              repositories,
+              failures: failures,
+              roots: roots,
+              animated: true
+            )
           )
+        }
+        .cancellable(id: CancelID.load, cancelInFlight: true)
+
+      case .alert(.presented(.confirmRemoveFailedRepository(let repositoryID))):
+        state.alert = nil
+        return .send(.removeFailedRepository(repositoryID))
+
+      case .alert(.presented(.confirmDeleteRepository(let repositoryID))):
+        guard let repository = state.repositories[id: repositoryID] else {
           return .none
         }
         if state.removingRepositoryIDs[repository.id] != nil {
-          state.alert = messageAlert(
-            title: "Unable to create worktree",
-            message: "This repository is being removed."
-          )
           return .none
         }
-        let previousSelection = state.selectedWorktreeID
-        let pendingID = "pending:\(uuid().uuidString)"
-        @Shared(.settingsFile) var settingsFile
-        @Shared(.repositorySettings(repository.rootURL)) var repositorySettings
-        let globalDefaultWorktreeBaseDirectoryPath = settingsFile.global.defaultWorktreeBaseDirectoryPath
-        let worktreeBaseDirectory = SupacodePaths.worktreeBaseDirectory(
-          for: repository.rootURL,
-          globalDefaultPath: globalDefaultWorktreeBaseDirectoryPath,
-          repositoryOverridePath: repositorySettings.worktreeBaseDirectoryPath
+        state.alert = nil
+        // Section-level removal: Supacode never nukes a git repo's
+        // on-disk state. No script runs; signal completion
+        // immediately and let the aggregator (batch of 1) emit the
+        // terminal.
+        let selectionWasRemoved =
+          state.selectedWorktreeID.map { id in
+            repository.worktrees.contains(where: { $0.id == id })
+          } ?? false
+        let batchID = uuid()
+        state.removingRepositoryIDs[repository.id] = RepositoryRemovalRecord(
+          disposition: .gitRepositoryUnlink, batchID: batchID
         )
-        let selectedBaseRef = repositorySettings.worktreeBaseRef
-        let globalSettings = settingsFile.global
-        let copyIgnoredOnWorktreeCreate =
-          repositorySettings.copyIgnoredOnWorktreeCreate ?? globalSettings.copyIgnoredOnWorktreeCreate
+        Self.syncSidebar(&state)
+        state.activeRemovalBatches[batchID] =
+          ActiveRemovalBatch(id: batchID, pending: [repository.id])
+        return .send(
+          .repositoryRemovalCompleted(
+            repository.id, outcome: .success, selectionWasRemoved: selectionWasRemoved))
+
+      case .repositoryRemovalCompleted(
+        let repositoryID, let outcome, let selectionWasRemoved):
+        // Aggregator entry point. Every repo-level removal
+        // (successful or not) drains through here so bulk batches
+        // fire a single terminal `.repositoriesRemoved` after the
+        // last target reports in. `.failure` outcomes keep the
+        // batch progressing past failures without removing the
+        // repo from state.
+        guard let record = state.removingRepositoryIDs[repositoryID],
+          var batch = state.activeRemovalBatches[record.batchID]
+        else {
+          // Orphaned completion: every sender seeds the record +
+          // batch before signalling, so arriving here means a bug
+          // (e.g. future caller skipped setup). Surface it loudly
+          // via `reportIssue` so tests fail and release builds emit
+          // a warning, and defensively clean up any state the
+          // absent terminal would otherwise leave hanging.
+          reportIssue(
+            """
+            repositoryRemovalCompleted: no active batch for \(repositoryID). \
+            This indicates an invariant violation: every confirm handler \
+            must seed a batch before per-target work fires.
+            """
+          )
+          state.removingRepositoryIDs[repositoryID] = nil
+          // Narrow the cleanup to the folder-synthetic worktree id so a future
+          // caller passing a git repo id here can't disturb sibling-worktree state.
+          let orphanFolderWorktreeID = Repository.folderWorktreeID(
+            for: URL(fileURLWithPath: repositoryID.rawValue)
+          )
+          switch outcome {
+          case .success:
+            return .send(
+              .repositoriesRemoved([repositoryID], selectionWasRemoved: selectionWasRemoved))
+          case .failureSilent:
+            return state.clearFolderRowLifecycleEffect(orphanFolderWorktreeID)
+          case .failureWithMessage(let message):
+            state.alert = messageAlert(
+              title: "Delete from disk failed", message: message
+            )
+            return state.clearFolderRowLifecycleEffect(orphanFolderWorktreeID)
+          }
+        }
+        let batchID = record.batchID
+        batch.pending.remove(repositoryID)
+        batch.selectionWasRemoved = batch.selectionWasRemoved || selectionWasRemoved
+        // Failure cleanup is scoped to the folder-synthetic worktree id because only
+        // folder dispositions reach a failure completion. Git repo unlink hardcodes success.
+        let folderWorktreeIDForFailure: Worktree.ID? =
+          record.disposition.isFolder
+          ? Repository.folderWorktreeID(for: URL(fileURLWithPath: repositoryID.rawValue))
+          : nil
+        var rowEffects: [Effect<Action>] = []
+        switch outcome {
+        case .success:
+          batch.succeeded.append(repositoryID)
+        // `.repositoriesRemoved` clears `removingRepositoryIDs`
+        // for the successful targets as part of the terminal,
+        // leave the record in place so the UI keeps showing the
+        // "removing" indicator until then.
+        case .failureSilent:
+          state.removingRepositoryIDs[repositoryID] = nil
+          if let folderWorktreeIDForFailure {
+            rowEffects.append(state.clearFolderRowLifecycleEffect(folderWorktreeIDForFailure))
+          }
+          batch.hasSilentFailure = true
+        case .failureWithMessage(let message):
+          state.removingRepositoryIDs[repositoryID] = nil
+          if let folderWorktreeIDForFailure {
+            rowEffects.append(state.clearFolderRowLifecycleEffect(folderWorktreeIDForFailure))
+          }
+          batch.failureMessagesByRepositoryID[repositoryID] = message
+        }
+        if batch.pending.isEmpty {
+          state.activeRemovalBatches[batchID] = nil
+          // Consolidated failure alert: when any target in the
+          // batch reported a `.failureWithMessage`, surface one
+          // alert listing them. Avoids parallel `.presentAlert`
+          // races where the last trash failure overwrites the
+          // others.
+          //
+          // When a `.failureSilent` target in the same batch has
+          // already set `state.alert` directly (blocking-script
+          // failure / user cancel / kind-flip), preserve the
+          // caller's alert and log the trash failures instead of
+          // clobbering. macOS only shows one alert at a time, and
+          // the script-failure alert carries actionable context
+          // (the "View Terminal" button) that the consolidated
+          // trash alert does not.
+          if !batch.failureMessagesByRepositoryID.isEmpty {
+            if batch.hasSilentFailure {
+              for (id, message) in batch.failureMessagesByRepositoryID {
+                let name = state.repositories[id: id]?.name ?? id.rawValue
+                repositoriesLogger.warning(
+                  "Trash failure for \(name) (\(id)) suppressed "
+                    + "(silent-failure alert already showing for sibling target): \(message)"
+                )
+              }
+            } else {
+              // Resolve names NOW (while `state.repositories`
+              // still has every batch member) so the alert stays
+              // user-recognizable even if the downstream
+              // `.repositoriesRemoved` → `.repositoriesLoaded`
+              // reloads prune an entry before the alert is read.
+              var namesByRepositoryID: [Repository.ID: String] = [:]
+              for id in batch.failureMessagesByRepositoryID.keys {
+                if let name = state.repositories[id: id]?.name {
+                  namesByRepositoryID[id] = name
+                }
+              }
+              state.alert = consolidatedTrashFailureAlert(
+                failureMessagesByRepositoryID: batch.failureMessagesByRepositoryID,
+                namesByRepositoryID: namesByRepositoryID
+              )
+            }
+          }
+          guard !batch.succeeded.isEmpty else {
+            return .merge(rowEffects)
+          }
+          rowEffects.append(
+            .send(
+              .repositoriesRemoved(
+                batch.succeeded, selectionWasRemoved: batch.selectionWasRemoved))
+          )
+          return .merge(rowEffects)
+        }
+        state.activeRemovalBatches[batchID] = batch
+        return .merge(rowEffects)
+
+      case .repositoriesRemoved(let repositoryIDs, let selectionWasRemoved):
+        // Bulk terminal: mutates `repositories` / `repositoryRoots`
+        // synchronously, emits one `.repositoriesLoaded` for
+        // reconciliation and a single cancellable persistence save.
+        // Firing once per batch (instead of once per target) removes
+        // the reload race.
+        guard !repositoryIDs.isEmpty else { return .none }
+        let idSet = Set(repositoryIDs)
+        for id in repositoryIDs {
+          let kind = (state.repositories[id: id]?.isGitRepository ?? true) ? "git" : "folder"
+          analyticsClient.capture("repository_removed", ["kind": kind])
+          state.removingRepositoryIDs[id] = nil
+        }
+        state.resetRowLifecycleSyncBeforeReconcile(inRepositories: idSet)
+        if selectionWasRemoved {
+          state.selection = nil
+          state.shouldSelectFirstAfterReload = true
+        }
+        // Drop sidebar sections for explicitly-removed repos before
+        // reconcile fires. `preserveOrphanSections` keeps customized
+        // tombstones across transient drops (filesystem flutter), but
+        // an explicit "Remove Repository" must not silently restore
+        // the user's old title / color when the same path is re-added
+        // later.
+        state.$sidebar.withLock { sidebar in
+          for id in repositoryIDs {
+            sidebar.sections.removeValue(forKey: id)
+          }
+        }
+        let selectedWorktree = state.worktree(for: state.selectedWorktreeID)
+        let remainingRepositories = Array(state.repositories.filter { !idSet.contains($0.id) })
+        let remainingRoots = state.repositoryRoots.filter {
+          !idSet.contains(RepositoryID($0.standardizedFileURL.path(percentEncoded: false)))
+        }
+        let remainingFailures = state.loadFailuresByID
+          .filter { !idSet.contains($0.key) }
+          .map { LoadFailure(rootID: $0.key, message: $0.value) }
+        let pathsToPersist = remainingRoots.map {
+          $0.standardizedFileURL.path(percentEncoded: false)
+        }
+        let removedIDs = Array(idSet)
+        return .merge(
+          .send(.delegate(.selectedWorktreeChanged(selectedWorktree))),
+          .send(
+            .repositoriesLoaded(
+              remainingRepositories,
+              failures: remainingFailures,
+              roots: remainingRoots,
+              animated: true
+            )
+          ),
+          .run { _ in
+            // `saveRoots` replaces the `repositoryRoots` array with
+            // the pruned list; `pruneRepositoryConfigs` drops the
+            // `repositories` dict entries (scripts / run config /
+            // open action) for repos that just left. Without the
+            // second step those entries pile up forever,
+            // especially visible for folder repos that users add +
+            // remove while exploring.
+            await repositoryPersistence.saveRoots(pathsToPersist)
+            await repositoryPersistence.pruneRepositoryConfigs(removedIDs.map(\.rawValue))
+          }
+          .cancellable(id: CancelID.persistRoots, cancelInFlight: true)
+        )
+      default:
+        return .none
+      }
+    }
+  }
+
+  /// `createWorktreeInRepository` is the single heaviest action arm; it lives in its own reducer
+  /// so `body` stays under the Swift type-checker's complexity limit.
+  var worktreeCreateInRepoReducer: some Reducer<State, Action> {
+    Reduce { state, action in
+      switch action {
+      case .createWorktreeInRepository(
+        let repositoryID,
+        let nameSource,
+        let baseRefSource,
+        let fetchOrigin,
+        let placement
+      ):
+        // Pull the parked branch name so every rejection arm can drain its (repo, branch) entry
+        // through the same helper — keeps the dict from leaking when a creation is rejected via
+        // any of the three guards below.
+        let rejectedBranchName: String? = if case .explicit(let name) = nameSource { name } else { nil }
+        guard let repository = state.repositories[id: repositoryID] else {
+          state.alert = messageAlert(
+            title: "Unable to create worktree",
+            message: "Unable to resolve a repository for the new worktree."
+          )
+          if let rejectedBranchName {
+            state.dropPendingCustomization(repositoryID: repositoryID, branchName: rejectedBranchName)
+          }
+          return .none
+        }
+        // Guard against folder-kind entries arriving here via deeplink / palette paths that bypass
+        // `.createRandomWorktreeInRepository`.
+        if !repository.isGitRepository {
+          state.alert = messageAlert(
+            title: "Unable to create worktree",
+            message: "Worktrees are only supported for git repositories."
+          )
+          if let rejectedBranchName {
+            state.dropPendingCustomization(repositoryID: repository.id, branchName: rejectedBranchName)
+          }
+          return .none
+        }
+        // Remote repos create worktrees over ssh via `git worktree add`, then
+        // reload to re-list. This bypasses the local pending/stream flow below,
+        // but honors the same name + base-ref choices from the prompt.
+        if repository.host != nil {
+          return remoteCreateWorktree(
+            repository: repository,
+            nameSource: nameSource,
+            baseRefSource: baseRefSource,
+            fetchOrigin: fetchOrigin,
+            placement: placement
+          )
+        }
+        if state.removingRepositoryIDs[repository.id] != nil {
+          state.alert = messageAlert(
+            title: "Unable to create worktree",
+            message: "This repository is being removed."
+          )
+          // Creation is being rejected; drop just the in-flight (repo, branch) entry so other
+          // concurrent customizations for this repo aren't wiped out.
+          if let rejectedBranchName {
+            state.dropPendingCustomization(repositoryID: repository.id, branchName: rejectedBranchName)
+          }
+          return .none
+        }
+        let previousSelection = state.selectedWorktreeID
+        let pendingID = WorktreeID("pending:\(uuid().uuidString)")
+        @Shared(.settingsFile) var settingsFile
+        @Shared(.repositorySettings(repository.rootURL, host: repository.host)) var repositorySettings
+        let globalDefaultWorktreeBaseDirectoryPath = settingsFile.global.defaultWorktreeBaseDirectoryPath
+        let worktreeBaseDirectory = SupacodePaths.worktreeBaseDirectory(
+          for: repository.rootURL,
+          globalDefaultPath: globalDefaultWorktreeBaseDirectoryPath,
+          repositoryOverridePath: repositorySettings.worktreeBaseDirectoryPath
+        )
+        let selectedBaseRef = repositorySettings.worktreeBaseRef
+        let globalSettings = settingsFile.global
+        let copyIgnoredOnWorktreeCreate =
+          repositorySettings.copyIgnoredOnWorktreeCreate ?? globalSettings.copyIgnoredOnWorktreeCreate
         let copyUntrackedOnWorktreeCreate =
           repositorySettings.copyUntrackedOnWorktreeCreate ?? globalSettings.copyUntrackedOnWorktreeCreate
         let initialWorktreeName: String? = if case .explicit(let name) = nameSource { name } else { nil }
+        // Pull any customization the New Worktree prompt parked for this
+        // (repo, branch) and attach it to the pending row so reconcile
+        // can render the user-typed title / color while git creates the
+        // worktree. Drop the dict entry to avoid leaks if the same name
+        // is used in a later run.
+        let pendingCustomization: PendingWorktree.Customization?
+        if let initialWorktreeName {
+          pendingCustomization = state.pendingCreationCustomizations[repository.id]?[initialWorktreeName]
+          state.dropPendingCustomization(repositoryID: repository.id, branchName: initialWorktreeName)
+        } else {
+          pendingCustomization = nil
+        }
         state.pendingWorktrees.append(
           PendingWorktree(
             id: pendingID,
             repositoryID: repository.id,
-            progress: WorktreeCreationProgress(stage: .loadingLocalBranches, worktreeName: initialWorktreeName)
+            progress: WorktreeCreationProgress(stage: .loadingLocalBranches, worktreeName: initialWorktreeName),
+            customization: pendingCustomization
           )
         )
         Self.syncSidebar(&state)
@@ -1422,1130 +2024,599 @@ struct RepositoriesFeature {
             )
           }
         }
-
-      case .worktreeCreationPrompt(.dismiss):
-        state.worktreeCreationPrompt = nil
-        return .merge(
-          .cancel(id: CancelID.worktreePromptLoad),
-          .cancel(id: CancelID.worktreePromptValidation)
-        )
-
-      case .worktreeCreationPrompt:
+      default:
         return .none
+      }
+    }
+  }
 
-      case .pendingWorktreeProgressUpdated(let id, let progress):
-        guard state.updatePendingWorktreeProgress(id, progress: progress) else { return .none }
-        Self.syncSidebar(&state)
-        return .none
-
-      case .createRandomWorktreeSucceeded(
-        let worktree,
-        let repositoryID,
-        let pendingID
-      ):
-        analyticsClient.capture("worktree_created", nil)
-        state.removePendingWorktree(pendingID)
-        if state.selection == .worktree(pendingID) {
-          // History was already recorded when the pending row was
-          // selected (real → pending). Treat the swap into the real
-          // worktree id as a continuation of that same navigation
-          // so the back stack ends with the real id, not the
-          // throwaway pending id.
-          state.setSingleWorktreeSelection(worktree.id, recordHistory: false)
-        }
-        state.insertWorktree(worktree, repositoryID: repositoryID)
-        Self.syncSidebar(&state)
-        // Synchronous so the detail body never observes a brief `.idle` window
-        // between the real-worktree swap and the setup-script path.
-        state.sidebarItems[id: worktree.id]?.lifecycle = .pending
-        return .merge(
-          .send(.sidebarItems(.element(id: worktree.id, action: .focusTerminalRequested))),
-          .send(.reloadRepositories(animated: false)),
-          .send(.delegate(.repositoriesChanged(state.repositories))),
-          .send(.delegate(.selectedWorktreeChanged(state.worktree(for: state.selectedWorktreeID)))),
-          .send(.delegate(.worktreeCreated(worktree)))
-        )
-
-      case .createRandomWorktreeFailed(
-        let title,
-        let message,
-        let pendingID,
-        let previousSelection,
-        let repositoryID,
-        let name,
-        let baseDirectory
-      ):
-        let previousSelectedWorktree = state.worktree(for: previousSelection)
-        state.removePendingWorktree(pendingID)
-        state.restoreSelection(previousSelection, pendingID: pendingID)
-        let cleanup = state.cleanupFailedWorktree(
-          repositoryID: repositoryID,
-          name: name,
-          baseDirectory: baseDirectory,
-        )
-        state.alert = messageAlert(title: title, message: message)
-        let selectedWorktree = state.worktree(for: state.selectedWorktreeID)
-        let selectionChanged = state.hasSelectionChanged(
-          previousSelectionID: previousSelection,
-          previousSelectedWorktree: previousSelectedWorktree,
-          selectedWorktreeID: state.selectedWorktreeID,
-          selectedWorktree: selectedWorktree,
-        )
-        var effects: [Effect<Action>] = []
-        if cleanup.didRemoveWorktree {
-          effects.append(.send(.delegate(.repositoriesChanged(state.repositories))))
-        }
-        if selectionChanged {
-          effects.append(.send(.delegate(.selectedWorktreeChanged(selectedWorktree))))
-        }
-        // Sidebar-state mutations in `cleanupWorktreeState` already
-        // went through `$sidebar.withLock`, so no per-slice save
-        // effects are needed here.
-        if let cleanupWorktree = cleanup.worktree {
-          effects.append(
-            .run { send in
-              _ = try? await gitClient.removeWorktree(cleanupWorktree, true)
-              await send(.reloadRepositories(animated: true))
-            }
-          )
-        }
-        return .merge(effects)
-
-      case .consumeSetupScript(let id):
-        guard state.sidebarItems[id: id]?.lifecycle == .pending else { return .none }
-        return .send(.sidebarItems(.element(id: id, action: .lifecycleChanged(.idle))))
-
-      case .consumeTerminalFocus(let id):
-        return .send(.sidebarItems(.element(id: id, action: .focusTerminalConsumed)))
-
-      case .requestArchiveWorktree(let worktreeID, let repositoryID):
-        if state.removingRepositoryIDs[repositoryID] != nil {
-          return .none
-        }
-        guard let repository = state.repositories[id: repositoryID],
-          let worktree = repository.worktrees[id: worktreeID]
+  /// GitHub availability + pull-request + worktree-info-loaded handlers, split from `body` so each
+  /// `Reduce` closure stays under the type-checker's complexity limit.
+  var githubIntegrationReducer: some Reducer<State, Action> {
+    Reduce { state, action in
+      switch action {
+      case .refreshGithubIntegrationAvailability:
+        guard state.githubIntegrationAvailability != .checking,
+          state.githubIntegrationAvailability != .disabled
         else {
           return .none
         }
-        // Folder repos have a synthesized main-worktree; archive
-        // targets it via `isMainWorktree` geometry. Surface the
-        // `folderIncompatibleAlert` feedback the deeplink layer
-        // already shows so hotkeys don't silently no-op.
-        if !repository.isGitRepository {
-          state.alert = folderIncompatibleAlert(action: .archive)
-          return .none
-        }
-        if state.isMainWorktree(worktree) {
-          return .none
-        }
-        let lifecycle = state.sidebarItems[id: worktree.id]?.lifecycle
-        if lifecycle == .deleting || lifecycle == .deletingScript {
-          return .none
-        }
-        if lifecycle == .archiving {
-          return .none
-        }
-        if state.isWorktreeArchived(worktree.id) {
-          return .none
-        }
-        if state.isWorktreeMerged(worktree) {
-          return .send(.archiveWorktreeConfirmed(worktree.id, repository.id))
-        }
-        @Shared(.settingsFile) var settingsFile
-        let archivedDisplay =
-          AppShortcuts.archivedWorktrees
-          .effective(from: settingsFile.global.shortcutOverrides)?.display ?? "none"
-        state.alert = AlertState {
-          TextState("Archive worktree?")
-        } actions: {
-          ButtonState(role: .destructive, action: .confirmArchiveWorktree(worktree.id, repository.id)) {
-            TextState("Archive worktree")
-          }
-          ButtonState(role: .cancel) {
-            TextState("Cancel")
-          }
-        } message: {
-          TextState(
-            "You can find \(worktree.name) later in Menu Bar > Worktrees > Archived Worktrees (\(archivedDisplay))."
-          )
+        state.githubIntegrationAvailability = .checking
+        let githubIntegration = githubIntegration
+        return .run { send in
+          let isAvailable = await githubIntegration.isAvailable()
+          await send(.githubIntegrationAvailabilityUpdated(isAvailable))
         }
-        return .none
+        .cancellable(id: CancelID.githubIntegrationAvailability, cancelInFlight: true)
 
-      case .requestArchiveWorktrees(let targets):
-        var validTargets: [ArchiveWorktreeTarget] = []
-        var seenWorktreeIDs: Set<Worktree.ID> = []
-        for target in targets {
-          guard seenWorktreeIDs.insert(target.worktreeID).inserted else { continue }
-          if state.removingRepositoryIDs[target.repositoryID] != nil {
-            continue
-          }
-          guard let repository = state.repositories[id: target.repositoryID],
-            let worktree = repository.worktrees[id: target.worktreeID]
-          else {
-            continue
-          }
-          let lifecycle = state.sidebarItems[id: worktree.id]?.lifecycle ?? .idle
-          if state.isMainWorktree(worktree)
-            || lifecycle != .idle
-            || state.isWorktreeArchived(worktree.id)
-          {
-            continue
-          }
-          validTargets.append(target)
-        }
-        guard !validTargets.isEmpty else {
+      case .githubIntegrationAvailabilityUpdated(let isAvailable):
+        guard state.githubIntegrationAvailability != .disabled else {
           return .none
         }
-        if validTargets.count == 1, let target = validTargets.first {
-          return .send(.requestArchiveWorktree(target.worktreeID, target.repositoryID))
-        }
-        let count = validTargets.count
-        @Shared(.settingsFile) var settingsFile
-        let archivedDisplay =
-          AppShortcuts.archivedWorktrees
-          .effective(from: settingsFile.global.shortcutOverrides)?.display ?? "none"
-        state.alert = AlertState {
-          TextState("Archive \(count) worktrees?")
-        } actions: {
-          ButtonState(role: .destructive, action: .confirmArchiveWorktrees(validTargets)) {
-            TextState("Archive \(count) worktrees")
+        state.githubIntegrationAvailability = isAvailable ? .available : .unavailable
+        guard isAvailable else {
+          for (repositoryID, queued) in state.queuedPullRequestRefreshByRepositoryID {
+            state.pendingPullRequestRefreshByRepositoryID.queuePullRequestRefresh(
+              repositoryID: repositoryID,
+              repositoryRootURL: queued.repositoryRootURL,
+              worktreeIDs: queued.worktreeIDs,
+            )
           }
-          ButtonState(role: .cancel) {
-            TextState("Cancel")
+          state.queuedPullRequestRefreshByRepositoryID.removeAll()
+          state.inFlightPullRequestRefreshRepositoryIDs.removeAll()
+          state.inFlightPullRequestBranchSnapshotsByRepositoryID.removeAll()
+          return .run { send in
+            while !Task.isCancelled {
+              try? await ContinuousClock().sleep(for: githubIntegrationRecoveryInterval)
+              guard !Task.isCancelled else {
+                return
+              }
+              await send(.refreshGithubIntegrationAvailability)
+            }
           }
-        } message: {
-          TextState(
-            "You can find them later in Menu Bar > Worktrees > Archived Worktrees (\(archivedDisplay))."
-          )
+          .cancellable(id: CancelID.githubIntegrationRecovery, cancelInFlight: true)
         }
-        return .none
-
-      case .alert(.presented(.confirmArchiveWorktree(let worktreeID, let repositoryID))):
-        return .send(.archiveWorktreeConfirmed(worktreeID, repositoryID))
-
-      case .alert(.presented(.confirmArchiveWorktrees(let targets))):
+        let pendingRefreshes = state.pendingPullRequestRefreshByRepositoryID.values.sorted {
+          $0.repositoryRootURL.path(percentEncoded: false)
+            < $1.repositoryRootURL.path(percentEncoded: false)
+        }
+        state.pendingPullRequestRefreshByRepositoryID.removeAll()
         return .merge(
-          targets.map { target in
-            .send(.archiveWorktreeConfirmed(target.worktreeID, target.repositoryID))
-          }
+          .cancel(id: CancelID.githubIntegrationRecovery),
+          .merge(
+            pendingRefreshes.map { pending in
+              .send(
+                .worktreeInfoEvent(
+                  .repositoryPullRequestRefresh(
+                    repositoryRootURL: pending.repositoryRootURL,
+                    worktreeIDs: pending.worktreeIDs
+                  )
+                )
+              )
+            }
+          )
         )
 
-      case .scriptCompleted(let worktreeID, let scriptID, let kind, let exitCode, let tabId):
-        guard state.sidebarItems[id: worktreeID]?.runningScripts[id: scriptID] != nil else {
-          repositoriesLogger.debug("Ignoring scriptCompleted for \(worktreeID)/\(scriptID): not tracked")
+      case .repositoryPullRequestRefreshCompleted(let repositoryID):
+        state.inFlightPullRequestRefreshRepositoryIDs.remove(repositoryID)
+        state.inFlightPullRequestBranchSnapshotsByRepositoryID.removeValue(forKey: repositoryID)
+        guard state.githubIntegrationAvailability == .available,
+          let pending = state.queuedPullRequestRefreshByRepositoryID.removeValue(
+            forKey: repositoryID
+          )
+        else {
           return .none
         }
-        let stopEffect: Effect<Action> = .send(
-          .sidebarItems(.element(id: worktreeID, action: .runningScriptStopped(id: scriptID)))
+        return .send(
+          .worktreeInfoEvent(
+            .repositoryPullRequestRefresh(
+              repositoryRootURL: pending.repositoryRootURL,
+              worktreeIDs: pending.worktreeIDs
+            )
+          )
         )
-        guard let exitCode, exitCode != 0 else { return stopEffect }
-        state.alert = blockingScriptFailureAlert(
-          kind: kind,
-          exitCode: exitCode,
-          worktreeID: worktreeID,
-          tabId: tabId,
-          state: state
-        )
-        return stopEffect
 
-      case .archiveWorktreeConfirmed(let worktreeID, let repositoryID):
-        guard let repository = state.repositories[id: repositoryID],
-          let worktree = repository.worktrees[id: worktreeID]
-        else {
-          return .none
-        }
-        if state.isWorktreeArchived(worktreeID)
-          || state.sidebarItems[id: worktreeID]?.lifecycle == .archiving
-        {
-          state.alert = nil
-          return .none
-        }
-        state.alert = nil
-        @Shared(.repositorySettings(worktree.repositoryRootURL)) var repositorySettings
-        let script = repositorySettings.archiveScript
-        let trimmed = script.trimmingCharacters(in: .whitespacesAndNewlines)
-        // Orphan rows have no working dir to run a script in; skip
-        // straight to the apply step so the cleanup still completes.
-        if trimmed.isEmpty || worktree.isMissing {
-          return .send(.archiveWorktreeApply(worktreeID, repositoryID))
-        }
-        return .merge(
-          state.setRowLifecycleEffect(worktreeID, .archiving),
-          .send(
-            .delegate(.runBlockingScript(worktree, repositoryID: repositoryID, kind: .archive, script: script))
-          )
+      case .worktreeBranchNameLoaded(let worktreeID, let name):
+        state.updateWorktreeName(worktreeID, name: name)
+        Self.syncSidebar(&state)
+        return .none
+
+      case .worktreeLineChangesLoaded(let worktreeID, let added, let removed):
+        return state.updateWorktreeLineChangesEffect(
+          worktreeID: worktreeID,
+          added: added,
+          removed: removed,
         )
 
-      case .archiveScriptCompleted(let worktreeID, let exitCode, let tabId):
-        guard state.sidebarItems[id: worktreeID]?.lifecycle == .archiving else {
-          repositoriesLogger.debug("Ignoring archiveScriptCompleted for \(worktreeID): not archiving")
+      case .repositoryPullRequestsLoaded(let repositoryID, let pullRequestsByWorktreeID):
+        guard let repository = state.repositories[id: repositoryID] else {
           return .none
         }
-        let resetLifecycle = state.setRowLifecycleEffect(worktreeID, .idle)
-        switch exitCode {
-        case 0:
-          guard let repositoryID = state.repositoryID(containing: worktreeID) else {
-            repositoriesLogger.warning(
-              "Archive script succeeded but repository not found for worktree \(worktreeID)"
-            )
-            state.alert = messageAlert(
-              title: "Archive failed",
-              message: "The archive script completed successfully, but the worktree could not be found."
-                + " It may have been removed."
-            )
-            return resetLifecycle
+        let branchSnapshot = state.inFlightPullRequestBranchSnapshotsByRepositoryID[repositoryID] ?? [:]
+        var archiveWorktreeIDs: [Worktree.ID] = []
+        var deleteWorktreeIDs: [Worktree.ID] = []
+        var rowEffects: [Effect<Action>] = []
+        // Queried-but-missing worktrees must still clear their row watermark.
+        let dispatchIDs = Set(branchSnapshot.keys).union(pullRequestsByWorktreeID.keys)
+        for worktreeID in dispatchIDs.sorted(by: { $0.rawValue < $1.rawValue }) {
+          guard let worktree = repository.worktrees[id: worktreeID] else {
+            continue
           }
-          return .merge(resetLifecycle, .send(.archiveWorktreeApply(worktreeID, repositoryID)))
-        case nil:
-          repositoriesLogger.debug("Archive script cancelled or tab closed for worktree \(worktreeID)")
-          return resetLifecycle
-        case let code?:
-          state.alert = blockingScriptFailureAlert(
-            kind: .archive, exitCode: code, worktreeID: worktreeID, tabId: tabId, state: state
-          )
-          return resetLifecycle
-        }
-
-      case .archiveWorktreeApply(let worktreeID, let repositoryID):
-        guard let repository = state.repositories[id: repositoryID],
-          let worktree = repository.worktrees[id: worktreeID]
-        else {
-          repositoriesLogger.warning(
-            "archiveWorktreeApply: worktree \(worktreeID) not found in repository \(repositoryID)"
-          )
-          state.alert = messageAlert(
-            title: "Archive failed",
-            message: "The worktree could not be found. It may have already been removed."
+          let pullRequest = pullRequestsByWorktreeID[worktreeID] ?? nil
+          let previousPullRequest = state.sidebarItems[id: worktreeID]?.pullRequest
+          let previousMerged = previousPullRequest?.state == "MERGED"
+          let nextMerged = pullRequest?.state == "MERGED"
+          // Dispatch unconditionally so an identical-PR result still clears the row's watermark.
+          rowEffects.append(
+            state.updateWorktreePullRequestEffect(
+              worktreeID: worktreeID,
+              pullRequest: pullRequest,
+              branchAtQueryTime: branchSnapshot[worktreeID],
+            )
           )
-          return .none
-        }
-        if state.isWorktreeArchived(worktreeID) {
-          state.alert = nil
-          return .none
-        }
-        let previousSelection = state.selectedWorktreeID
-        let previousSelectedWorktree = state.worktree(for: previousSelection)
-        let selectionWasRemoved = state.selectedWorktreeID == worktree.id
-        let nextSelection =
-          selectionWasRemoved
-          ? state.nextWorktreeID(afterRemoving: worktree, in: repository)
-          : nil
-        withAnimation {
-          state.alert = nil
-          // Drop the item from its current pinned/unpinned bucket
-          // and insert into `.archived` with the timestamp. The
-          // seed pass in `reconcileSidebarState` guarantees every
-          // live non-main worktree lives in either `.pinned` or
-          // `.unpinned` before this runs.
-          state.$sidebar.withLock { sidebar in
-            let from = sidebar.currentBucket(of: worktreeID, in: repositoryID) ?? .unpinned
-            sidebar.archive(worktree: worktreeID, in: repositoryID, from: from, at: now)
-          }
-          if selectionWasRemoved {
-            let nextWorktreeID = nextSelection ?? state.firstAvailableWorktreeID(in: repositoryID)
-            state.selection = nextWorktreeID.map(SidebarSelection.worktree)
+          let mergedLifecycle = state.sidebarItems[id: worktreeID]?.lifecycle ?? .idle
+          if let mergedAction = state.mergedWorktreeAction,
+            !previousMerged,
+            nextMerged,
+            !state.isMainWorktree(worktree),
+            !state.isWorktreeArchived(worktreeID),
+            mergedLifecycle != .deleting,
+            mergedLifecycle != .deletingScript
+          {
+            switch mergedAction {
+            case .archive:
+              archiveWorktreeIDs.append(worktreeID)
+            case .delete:
+              deleteWorktreeIDs.append(worktreeID)
+            }
           }
-          Self.syncSidebar(&state)
         }
-        let repositories = state.repositories
-        let selectedWorktree = state.worktree(for: state.selectedWorktreeID)
-        let selectionChanged = state.hasSelectionChanged(
-          previousSelectionID: previousSelection,
-          previousSelectedWorktree: previousSelectedWorktree,
-          selectedWorktreeID: state.selectedWorktreeID,
-          selectedWorktree: selectedWorktree,
-        )
-        var effects: [Effect<Action>] = [
-          .send(.delegate(.repositoriesChanged(repositories)))
-        ]
-        if selectionChanged {
-          effects.append(.send(.delegate(.selectedWorktreeChanged(selectedWorktree))))
+        let effects: [Effect<Action>] =
+          rowEffects
+          + archiveWorktreeIDs.map { .send(.archiveWorktreeConfirmed($0, repositoryID)) }
+          + deleteWorktreeIDs.map { .send(.deleteSidebarItemConfirmed($0, repositoryID)) }
+        guard !effects.isEmpty else {
+          return .none
         }
         return .merge(effects)
 
-      case .unarchiveWorktree(let worktreeID):
-        guard let repositoryID = state.repositoryID(containing: worktreeID),
-          state.sidebar.sections[repositoryID]?.buckets[.archived]?.items[worktreeID] != nil
+      case .pullRequestAction(let worktreeID, let action):
+        guard let worktree = state.worktree(for: worktreeID),
+          let repositoryID = state.repositoryID(containing: worktreeID),
+          let repository = state.repositories[id: repositoryID],
+          let pullRequest = state.sidebarItems[id: worktreeID]?.pullRequest
         else {
-          return .none
+          return .send(
+            .presentAlert(
+              title: "Pull request not available",
+              message: "Supacode could not find a pull request for this worktree."
+            )
+          )
         }
-        withAnimation {
-          state.$sidebar.withLock { sidebar in
-            sidebar.unarchive(worktree: worktreeID, in: repositoryID)
+        let repoRoot = worktree.repositoryRootURL
+        let repoHost = worktree.host
+        let worktreeRoot = worktree.workingDirectory
+        let pullRequestRefresh = WorktreeInfoWatcherClient.Event.repositoryPullRequestRefresh(
+          repositoryRootURL: repoRoot,
+          worktreeIDs: repository.worktrees.map(\.id)
+        )
+        let branchName = pullRequest.headRefName ?? worktree.name
+        let failingCheckDetailsURL = (pullRequest.statusCheckRollup?.checks ?? []).first {
+          $0.checkState == .failure && $0.detailsUrl != nil
+        }?.detailsUrl
+        switch action {
+        case .openOnGithub:
+          guard let url = URL(string: pullRequest.url) else {
+            return .send(
+              .presentAlert(
+                title: "Invalid pull request URL",
+                message: "Supacode could not open the pull request URL."
+              )
+            )
           }
-          Self.syncSidebar(&state)
-        }
-        let repositories = state.repositories
-        return .send(.delegate(.repositoriesChanged(repositories)))
-
-      case .requestDeleteSidebarItems(let targets):
-        // Kind discriminator: folders skip the main-worktree guard
-        // (their synthetic worktree IS main). Mixed kind selections
-        // get rejected — the context menu already blocks mixed
-        // bulk, so this only trips if a hotkey somehow routes a
-        // heterogeneous selection here.
-        var validTargets: [DeleteWorktreeTarget] = []
-        var validKinds: Set<SidebarItemFeature.State.Kind> = []
-        var seenWorktreeIDs: Set<Worktree.ID> = []
-        var rejectedMainWorktreeCount = 0
-        for target in targets {
-          guard seenWorktreeIDs.insert(target.worktreeID).inserted,
-            state.removingRepositoryIDs[target.repositoryID] == nil,
-            let repository = state.repositories[id: target.repositoryID],
-            let worktree = repository.worktrees[id: target.worktreeID]
-          else { continue }
-          let lifecycle = state.sidebarItems[id: worktree.id]?.lifecycle ?? .idle
-          guard lifecycle == .idle else { continue }
-          if repository.isGitRepository {
-            if state.isMainWorktree(worktree) {
-              rejectedMainWorktreeCount += 1
-              continue
-            }
-            validKinds.insert(.gitWorktree)
-          } else {
-            validKinds.insert(.folder)
+          return .run { @MainActor _ in
+            NSWorkspace.shared.open(url)
           }
-          validTargets.append(target)
-        }
-        guard !validTargets.isEmpty, validKinds.count == 1 else {
-          // Single-target main-worktree rejection: surface the same
-          // "Delete not allowed" feedback the deeplink path already
-          // shows, so palette / hotkey / context-menu entries behave
-          // consistently instead of silently no-opping.
-          if targets.count == 1, validTargets.isEmpty, rejectedMainWorktreeCount == 1 {
-            state.alert = messageAlert(
-              title: "Delete not allowed",
-              message: "Deleting the main worktree is not allowed."
+
+        case .copyFailingJobURL:
+          guard let failingCheckDetailsURL, !failingCheckDetailsURL.isEmpty else {
+            return .send(
+              .presentAlert(
+                title: "Failing check not found",
+                message: "Supacode could not find a failing check URL."
+              )
             )
           }
-          return .none
-        }
-        let count = validTargets.count
-        if validKinds == [.folder] {
-          let folders = validTargets.compactMap { state.repositories[id: $0.repositoryID] }
-          let namesList = folders.map(\.name)
-            .sorted(by: { $0.localizedCaseInsensitiveCompare($1) == .orderedAscending })
-            .joined(separator: ", ")
-          let title = count == 1 ? "Remove folder?" : "Remove \(count) folders?"
-          let messageSubject = count == 1 ? folders.first?.name ?? "this folder" : namesList
-          let stayOnDiskCopy =
-            count == 1
-            ? "managing the folder (it stays on disk)"
-            : "managing the folders (they stay on disk)"
-          let trashCopy =
-            count == 1 ? "move the folder to the Trash" : "move them to the Trash"
-          state.alert = AlertState {
-            TextState(title)
-          } actions: {
-            ButtonState(
-              action: .confirmDeleteSidebarItems(validTargets, disposition: .folderUnlink)
-            ) {
-              TextState("Remove from Supacode")
-            }
-            ButtonState(
-              role: .destructive,
-              action: .confirmDeleteSidebarItems(validTargets, disposition: .folderTrash)
-            ) {
-              TextState("Delete from disk")
-            }
-            ButtonState(role: .cancel) {
-              TextState("Cancel")
+          return .run { send in
+            await MainActor.run {
+              NSPasteboard.general.clearContents()
+              NSPasteboard.general.setString(failingCheckDetailsURL, forType: .string)
             }
-          } message: {
-            TextState(
-              "Remove \(messageSubject)? Choose \"Remove from Supacode\" to stop "
-                + stayOnDiskCopy
-                + ", or \"Delete from disk\" to " + trashCopy + "."
-            )
-          }
-          return .none
-        }
-        @Shared(.settingsFile) var settingsFile
-        let deleteBranchOnDeleteWorktree = settingsFile.global.deleteBranchOnDeleteWorktree
-        let allMissing = validTargets.allSatisfy { target in
-          state.repositories[id: target.repositoryID]?.worktrees[id: target.worktreeID]?.isMissing
-            == true
-        }
-        let title = count == 1 ? "Delete worktree?" : "Delete \(count) worktrees?"
-        let buttonLabel = count == 1 ? "Delete worktree" : "Delete \(count) worktrees"
-        let message: String =
-          switch (count, deleteBranchOnDeleteWorktree, allMissing) {
-          case (1, _, true): "Removes the orphan worktree entry from this repository."
-          case (_, _, true): "Removes \(count) orphan worktree entries from this repository."
-          case (1, true, false): "This deletes the worktree directory and its local branch."
-          case (1, false, false): "This deletes the worktree directory but keeps the local branch."
-          case (_, true, false):
-            "This deletes \(count) worktree directories and their local branches."
-          case (_, false, false):
-            "This deletes \(count) worktree directories but keeps their local branches."
+            await send(.showToast(.success("Failing job URL copied")))
           }
-        state.alert = AlertState {
-          TextState(title)
-        } actions: {
-          ButtonState(
-            role: .destructive,
-            action: .confirmDeleteSidebarItems(validTargets, disposition: .gitWorktreeDelete)
-          ) {
-            TextState(buttonLabel)
+
+        case .openFailingCheckDetails:
+          guard let failingCheckDetailsURL, let url = URL(string: failingCheckDetailsURL) else {
+            return .send(
+              .presentAlert(
+                title: "Failing check not found",
+                message: "Supacode could not find a failing check with details."
+              )
+            )
           }
-          ButtonState(role: .cancel) {
-            TextState("Cancel")
+          return .run { @MainActor _ in
+            NSWorkspace.shared.open(url)
           }
-        } message: {
-          TextState(message)
-        }
-        return .none
 
-      case .alert(.presented(.confirmDeleteSidebarItems(let targets, let disposition))):
-        // Kind-and-disposition mapping: folders carry the
-        // disposition into `removingRepositoryIDs` so
-        // `.deleteScriptCompleted` can route by stored choice later.
-        // Git worktrees run the standard per-worktree pipeline and
-        // don't record a repo-level disposition. Kind / disposition
-        // mismatches are impossible under the current alert surface
-        // and a caller bypassing those guards is a bug — flag it via
-        // `reportIssue` instead of dropping silently.
-        state.alert = nil
-        var validTargets: [DeleteWorktreeTarget] = []
-        var folderBatchIDs: Set<Repository.ID> = []
-        for target in targets {
-          guard let repository = state.repositories[id: target.repositoryID],
-            state.removingRepositoryIDs[target.repositoryID] == nil
-          else { continue }
-          if repository.isGitRepository {
-            guard disposition == .gitWorktreeDelete else {
-              reportIssue(
-                """
-                confirmDeleteSidebarItems: received \(disposition) for git worktree \
-                \(target.worktreeID) — git targets only support .gitWorktreeDelete. \
-                Dropping target.
-                """
+        case .markReadyForReview:
+          let githubCLI = githubCLI
+          let gitClient = gitClient
+          let githubIntegration = githubIntegration
+          return .run { send in
+            guard await githubIntegration.isAvailable() else {
+              await send(
+                .presentAlert(
+                  title: "GitHub integration unavailable",
+                  message: "Enable GitHub integration to mark a pull request as ready."
+                )
               )
-              continue
+              return
             }
-          } else {
-            guard disposition.isFolder else {
-              reportIssue(
-                """
-                confirmDeleteSidebarItems: received \(disposition) for folder \
-                \(target.repositoryID) — folder targets only support .folderUnlink / \
-                .folderTrash. Dropping target.
-                """
+            let remote = await resolveRemoteInfo(
+              repositoryRootURL: repoRoot,
+              githubCLI: githubCLI,
+              gitClient: gitClient
+            )
+            await send(.showToast(.inProgress("Marking PR ready…")))
+            do {
+              try await githubCLI.markPullRequestReady(worktreeRoot, remote, pullRequest.number)
+              await send(.showToast(.success("Pull request marked ready")))
+              await send(.delayedPullRequestRefresh(worktreeID))
+            } catch {
+              await send(.dismissToast)
+              await send(
+                .presentAlert(
+                  title: "Failed to mark pull request ready",
+                  message: error.localizedDescription
+                )
               )
-              continue
             }
-            folderBatchIDs.insert(target.repositoryID)
           }
-          validTargets.append(target)
-        }
-        guard !validTargets.isEmpty else { return .none }
-        if !folderBatchIDs.isEmpty {
-          // All folder targets in this batch share the same
-          // disposition (the alert only ever produces one), so one
-          // record shape per repo keeps disposition + batch id in
-          // lockstep.
-          let batchID = uuid()
-          for repositoryID in folderBatchIDs {
-            state.removingRepositoryIDs[repositoryID] = RepositoryRemovalRecord(
-              disposition: disposition, batchID: batchID
+
+        case .merge:
+          let githubCLI = githubCLI
+          let gitClient = gitClient
+          let githubIntegration = githubIntegration
+          return .run { send in
+            guard await githubIntegration.isAvailable() else {
+              await send(
+                .presentAlert(
+                  title: "GitHub integration unavailable",
+                  message: "Enable GitHub integration to merge a pull request."
+                )
+              )
+              return
+            }
+            @Shared(.repositorySettings(repoRoot, host: repoHost)) var repositorySettings
+            @Shared(.settingsFile) var settingsFile
+            let strategy =
+              repositorySettings.pullRequestMergeStrategy ?? settingsFile.global.pullRequestMergeStrategy
+            let remote = await resolveRemoteInfo(
+              repositoryRootURL: repoRoot,
+              githubCLI: githubCLI,
+              gitClient: gitClient
             )
+            await send(.showToast(.inProgress("Merging pull request…")))
+            do {
+              try await githubCLI.mergePullRequest(worktreeRoot, remote, pullRequest.number, strategy)
+              await send(.showToast(.success("Pull request merged")))
+              await send(.worktreeInfoEvent(pullRequestRefresh))
+              await send(.delayedPullRequestRefresh(worktreeID))
+            } catch {
+              await send(.dismissToast)
+              await send(
+                .presentAlert(
+                  title: "Failed to merge pull request",
+                  message: error.localizedDescription
+                )
+              )
+            }
           }
-          Self.syncSidebar(&state)
-          state.activeRemovalBatches[batchID] =
-            ActiveRemovalBatch(id: batchID, pending: folderBatchIDs)
-        }
-        return .merge(
-          validTargets.map {
-            .send(.deleteSidebarItemConfirmed($0.worktreeID, $0.repositoryID))
+
+        case .close:
+          let githubCLI = githubCLI
+          let gitClient = gitClient
+          let githubIntegration = githubIntegration
+          return .run { send in
+            guard await githubIntegration.isAvailable() else {
+              await send(
+                .presentAlert(
+                  title: "GitHub integration unavailable",
+                  message: "Enable GitHub integration to close a pull request."
+                )
+              )
+              return
+            }
+            let remote = await resolveRemoteInfo(
+              repositoryRootURL: repoRoot,
+              githubCLI: githubCLI,
+              gitClient: gitClient
+            )
+            await send(.showToast(.inProgress("Closing pull request…")))
+            do {
+              try await githubCLI.closePullRequest(worktreeRoot, remote, pullRequest.number)
+              await send(.showToast(.success("Pull request closed")))
+              await send(.worktreeInfoEvent(pullRequestRefresh))
+              await send(.delayedPullRequestRefresh(worktreeID))
+            } catch {
+              await send(.dismissToast)
+              await send(
+                .presentAlert(
+                  title: "Failed to close pull request",
+                  message: error.localizedDescription
+                )
+              )
+            }
           }
-        )
 
-      case .deleteSidebarItemConfirmed(let worktreeID, let repositoryID):
-        guard let repository = state.repositories[id: repositoryID],
-          let worktree = repository.worktrees[id: worktreeID]
-        else {
-          repositoriesLogger.debug(
-            "deleteSidebarItemConfirmed: worktree \(worktreeID) not found in repository \(repositoryID)."
-          )
-          return .none
-        }
-        // Lifecycle re-entry guard: only the first tap proceeds; rapid repeats no-op
-        // so the aggregator batch isn't double-drained.
-        let confirmedLifecycle = state.sidebarItems[id: worktree.id]?.lifecycle ?? .idle
-        if confirmedLifecycle == .archiving
-          || confirmedLifecycle == .deleting
-          || confirmedLifecycle == .deletingScript
-        {
-          return .none
-        }
-        // F4: folder targets only arrive here after the alert's
-        // confirm handler seeded a `RepositoryRemovalRecord`. If a
-        // future caller short-circuits to this action without going
-        // through `.requestDeleteSidebarItems` → confirm, the
-        // aggregator would never drain. Flag the invariant breach
-        // loudly (tests fail, release warns) and bail out early so
-        // we don't fall through to the git-worktree delete path for
-        // a folder.
-        if !repository.isGitRepository,
-          state.removingRepositoryIDs[repository.id] == nil
-        {
-          reportIssue(
-            """
-            deleteSidebarItemConfirmed: folder \(repository.id) missing seeded removal \
-            record. Callers must go through .requestDeleteSidebarItems → \
-            .confirmDeleteSidebarItems so the batch aggregator is set up.
-            """
-          )
-          return .none
-        }
-        // NOTE: we do NOT clear `state.alert` here.
-        //   - Alert-confirmed path: `.confirmDeleteSidebarItems`
-        //     already cleared its own confirm alert at entry.
-        //   - Auto-delete / merged-sweep path: this action fires
-        //     programmatically; an unconditional clear here would
-        //     wipe unrelated alerts — specifically the consolidated
-        //     trash-failure alert just set by the batch aggregator.
-        //   - Deeplink path: same — the caller decides alert state.
-        @Shared(.repositorySettings(worktree.repositoryRootURL)) var repositorySettings
-        let script = repositorySettings.deleteScript
-        let trimmed = script.trimmingCharacters(in: .whitespacesAndNewlines)
-        // Only folder-row intents (`.folderUnlink` / `.folderTrash`)
-        // route through the folder-removal success branch.
-        // `.gitRepositoryUnlink` is a concurrent git-repo section
-        // removal that has no bearing on this worktree's delete flow.
-        // `nil` is a git worktree delete (no repo-level intent).
-        let folderIntent: DeleteDisposition? = {
-          guard let record = state.removingRepositoryIDs[repository.id],
-            record.disposition.isFolder
-          else { return nil }
-          return record.disposition
-        }()
-        // Orphan rows have no working dir to run a script in; skip the
-        // script and apply the delete directly so the cleanup completes.
-        if trimmed.isEmpty || worktree.isMissing {
-          if let folderIntent {
-            // Empty script: finish the folder flow immediately,
-            // trashing the directory first if the user asked for it.
-            let selectionWasRemoved = state.selectedWorktreeID == worktreeID
-            let trashURL = folderIntent == .folderTrash ? repository.rootURL : nil
-            return .merge(
-              state.setRowLifecycleEffect(worktree.id, .deleting),
-              folderRemovalEffect(
-                repositoryID: repository.id,
-                selectionWasRemoved: selectionWasRemoved,
-                diskDeletionURL: trashURL
-              )
-            )
-          }
-          return .send(.deleteWorktreeApply(worktreeID, repositoryID))
-        }
-        return .merge(
-          state.setRowLifecycleEffect(worktree.id, .deletingScript),
-          .send(
-            .delegate(.runBlockingScript(worktree, repositoryID: repositoryID, kind: .delete, script: script))
-          )
-        )
-
-      case .deleteScriptCompleted(let worktreeID, let exitCode, let tabId):
-        guard state.sidebarItems[id: worktreeID]?.lifecycle == .deletingScript else {
-          repositoriesLogger.debug(
-            "Ignoring deleteScriptCompleted for \(worktreeID): not running a delete script."
-          )
-          return .none
-        }
-        let resetLifecycle = state.setRowLifecycleEffect(worktreeID, .idle)
-        // Route by recorded intent, not live classification — a
-        // `git init` mid-script would otherwise flip the check and
-        // lose folder intent. Kind divergence is treated as an
-        // explicit error so the user can decide what to do.
-        let owningRepo = state.repositories.first(where: {
-          $0.worktrees.contains(where: { $0.id == worktreeID })
-        })
-        // Only a folder-row intent (`.folderUnlink` / `.folderTrash`)
-        // routes this completion into repo-level removal.
-        // `.gitRepositoryUnlink` is a concurrent git-repo remove
-        // running independently; it shouldn't hijack the
-        // worktree-delete pipeline. `nil` means plain git worktree
-        // delete.
-        let folderIntent: DeleteDisposition? =
-          owningRepo
-          .flatMap { state.removingRepositoryIDs[$0.id] }
-          .flatMap { $0.disposition.isFolder ? $0.disposition : nil }
-        let followupEffect: Effect<Action>
-        switch exitCode {
-        case 0:
-          if let folderIntent, let owningRepo {
-            if owningRepo.isGitRepository {
-              // Kind flipped between confirmation and completion. Bail out
-              // rather than silently picking a path.
-              state.alert = messageAlert(
-                title: "Folder is now a git repository",
-                message: "Supacode stopped the removal because \(owningRepo.name) became a git "
-                  + "repository while the delete script was running. Review it and try again."
+        case .copyCiFailureLogs:
+          let githubCLI = githubCLI
+          let githubIntegration = githubIntegration
+          return .run { send in
+            guard await githubIntegration.isAvailable() else {
+              await send(
+                .presentAlert(
+                  title: "GitHub integration unavailable",
+                  message: "Enable GitHub integration to copy CI failure logs."
+                )
               )
-              followupEffect = signalFolderRemovalFailure(worktreeID: worktreeID, state: &state)
-            } else {
-              let selectionWasRemoved = state.selectedWorktreeID == worktreeID
-              let trashURL = folderIntent == .folderTrash ? owningRepo.rootURL : nil
-              followupEffect = folderRemovalEffect(
-                repositoryID: owningRepo.id,
-                selectionWasRemoved: selectionWasRemoved,
-                diskDeletionURL: trashURL
+              return
+            }
+            guard !branchName.isEmpty else {
+              await send(
+                .presentAlert(
+                  title: "Branch name unavailable",
+                  message: "Supacode could not determine the pull request branch."
+                )
               )
+              return
             }
-          } else if let repositoryID = state.repositoryID(containing: worktreeID) {
-            followupEffect = .send(.deleteWorktreeApply(worktreeID, repositoryID))
-          } else if let syntheticRepoID = Repository.repositoryID(
-            fromFolderWorktreeID: worktreeID
-          ), state.removingRepositoryIDs[syntheticRepoID]?.disposition.isFolder == true {
-            // Synthetic folder id + open folder record: drain the aggregator
-            // so siblings don't hang. Only surface the alert when no folder
-            // record exists.
-            repositoriesLogger.warning(
-              "Delete script succeeded but repository vanished for folder worktree "
-                + "\(worktreeID); draining batch as failure."
-            )
-            followupEffect = signalFolderRemovalFailure(worktreeID: worktreeID, state: &state)
-          } else {
-            repositoriesLogger.warning(
-              "Delete script succeeded but repository not found for worktree \(worktreeID)"
-            )
-            state.alert = messageAlert(
-              title: "Delete failed",
-              message: "The delete script completed successfully, but the worktree could not be found."
-                + " It may have been removed."
-            )
-            followupEffect = .none
-          }
-        case nil:
-          // User closed the script tab.
-          repositoriesLogger.debug(
-            "Delete script cancelled or tab closed for worktree \(worktreeID).")
-          followupEffect = signalFolderRemovalFailure(worktreeID: worktreeID, state: &state)
-        case let code?:
-          // Script failed. Show the standard failure alert AND for folder
-          // removals signal the aggregator so bulk batches don't hang.
-          // Git worktree delete has no batch.
-          state.alert = blockingScriptFailureAlert(
-            kind: .delete, exitCode: code, worktreeID: worktreeID, tabId: tabId, state: state
-          )
-          followupEffect = signalFolderRemovalFailure(worktreeID: worktreeID, state: &state)
-        }
-        return .merge(resetLifecycle, followupEffect)
-
-      case .deleteWorktreeApply(let worktreeID, let repositoryID):
-        guard let repository = state.repositories[id: repositoryID],
-          let worktree = repository.worktrees[id: worktreeID]
-        else {
-          repositoriesLogger.warning(
-            "deleteWorktreeApply: worktree \(worktreeID) not found in repository \(repositoryID)"
-          )
-          state.alert = messageAlert(
-            title: "Delete failed",
-            message: "The worktree could not be found. It may have already been removed."
-          )
-          return .none
-        }
-        let selectionWasRemoved = state.selectedWorktreeID == worktree.id
-        let nextSelection =
-          selectionWasRemoved
-          ? state.nextWorktreeID(afterRemoving: worktree, in: repository)
-          : nil
-        @Shared(.settingsFile) var settingsFile
-        let deleteBranchOnDeleteWorktree = settingsFile.global.deleteBranchOnDeleteWorktree
-        return .merge(
-          state.setRowLifecycleEffect(worktree.id, .deleting),
-          .run { send in
+            await send(.showToast(.inProgress("Fetching CI logs…")))
             do {
-              _ = try await gitClient.removeWorktree(
-                worktree,
-                deleteBranchOnDeleteWorktree
-              )
+              guard let run = try await githubCLI.latestRun(worktreeRoot, branchName) else {
+                await send(.dismissToast)
+                await send(
+                  .presentAlert(
+                    title: "No workflow runs found",
+                    message: "Supacode could not find any workflow runs for this branch."
+                  )
+                )
+                return
+              }
+              guard run.conclusion?.lowercased() == "failure" else {
+                await send(.dismissToast)
+                await send(
+                  .presentAlert(
+                    title: "No failing workflow run",
+                    message: "Supacode could not find a failing workflow run to copy logs from."
+                  )
+                )
+                return
+              }
+              let failedLogs = try await githubCLI.failedRunLogs(worktreeRoot, run.databaseId)
+              let logs =
+                if failedLogs.isEmpty {
+                  try await githubCLI.runLogs(worktreeRoot, run.databaseId)
+                } else {
+                  failedLogs
+                }
+              guard !logs.isEmpty else {
+                await send(.dismissToast)
+                await send(
+                  .presentAlert(
+                    title: "No CI logs available",
+                    message: "The workflow run failed but produced no logs."
+                  )
+                )
+                return
+              }
+              await MainActor.run {
+                NSPasteboard.general.clearContents()
+                NSPasteboard.general.setString(logs, forType: .string)
+              }
+              await send(.showToast(.success("CI failure logs copied")))
+            } catch {
+              await send(.dismissToast)
               await send(
-                .worktreeDeleted(
-                  worktree.id,
-                  repositoryID: repository.id,
-                  selectionWasRemoved: selectionWasRemoved,
-                  nextSelection: nextSelection
+                .presentAlert(
+                  title: "Failed to copy CI failure logs",
+                  message: error.localizedDescription
                 )
               )
-            } catch {
-              await send(.deleteWorktreeFailed(error.localizedDescription, worktreeID: worktree.id))
             }
           }
-        )
 
-      case .worktreeDeleted(
-        let worktreeID,
-        let repositoryID,
-        _,
-        let nextSelection
-      ):
-        analyticsClient.capture("worktree_deleted", nil)
-        let previousSelection = state.selectedWorktreeID
-        let previousSelectedWorktree = state.worktree(for: previousSelection)
-        withAnimation(.easeOut(duration: 0.2)) {
-          state.pendingWorktrees.removeAll { $0.id == worktreeID }
-          state.resetRowLifecycleSyncBeforeReconcile(itemID: worktreeID)
-          // Drop the worktree from every bucket in its section. The worktree is
-          // going away entirely so its current bucket doesn't matter.
-          state.$sidebar.withLock { sidebar in
-            sidebar.removeAnywhere(worktree: worktreeID, in: repositoryID)
-          }
-          _ = state.removeWorktree(worktreeID, repositoryID: repositoryID)
-          let selectionNeedsUpdate = state.selection == .worktree(worktreeID)
-          if selectionNeedsUpdate {
-            let nextWorktreeID = nextSelection ?? state.firstAvailableWorktreeID(in: repositoryID)
-            state.selection = nextWorktreeID.map(SidebarSelection.worktree)
+        case .rerunFailedJobs:
+          let githubCLI = githubCLI
+          let githubIntegration = githubIntegration
+          return .run { send in
+            guard await githubIntegration.isAvailable() else {
+              await send(
+                .presentAlert(
+                  title: "GitHub integration unavailable",
+                  message: "Enable GitHub integration to re-run failed jobs."
+                )
+              )
+              return
+            }
+            guard !branchName.isEmpty else {
+              await send(
+                .presentAlert(
+                  title: "Branch name unavailable",
+                  message: "Supacode could not determine the pull request branch."
+                )
+              )
+              return
+            }
+            await send(.showToast(.inProgress("Re-running failed jobs…")))
+            do {
+              guard let run = try await githubCLI.latestRun(worktreeRoot, branchName) else {
+                await send(.dismissToast)
+                await send(
+                  .presentAlert(
+                    title: "No workflow runs found",
+                    message: "Supacode could not find any workflow runs for this branch."
+                  )
+                )
+                return
+              }
+              guard run.conclusion?.lowercased() == "failure" else {
+                await send(.dismissToast)
+                await send(
+                  .presentAlert(
+                    title: "No failing workflow run",
+                    message: "Supacode could not find a failing workflow run to re-run."
+                  )
+                )
+                return
+              }
+              try await githubCLI.rerunFailedJobs(worktreeRoot, run.databaseId)
+              await send(.showToast(.success("Failed jobs re-run started")))
+              await send(.delayedPullRequestRefresh(worktreeID))
+            } catch {
+              await send(.dismissToast)
+              await send(
+                .presentAlert(
+                  title: "Failed to re-run failed jobs",
+                  message: error.localizedDescription
+                )
+              )
+            }
           }
-          Self.syncSidebar(&state)
         }
-        let roots = state.repositories.map(\.rootURL)
-        let repositories = state.repositories
-        let selectedWorktree = state.worktree(for: state.selectedWorktreeID)
-        let selectionChanged = state.hasSelectionChanged(
-          previousSelectionID: previousSelection,
-          previousSelectedWorktree: previousSelectedWorktree,
-          selectedWorktreeID: state.selectedWorktreeID,
-          selectedWorktree: selectedWorktree,
-        )
-        var immediateEffects: [Effect<Action>] = [
-          .send(.delegate(.repositoriesChanged(repositories)))
-        ]
-        if selectionChanged {
-          immediateEffects.append(.send(.delegate(.selectedWorktreeChanged(selectedWorktree))))
+
+      case .setGithubIntegrationEnabled(let isEnabled):
+        if isEnabled {
+          state.githubIntegrationAvailability = .unknown
+          state.pendingPullRequestRefreshByRepositoryID.removeAll()
+          state.queuedPullRequestRefreshByRepositoryID.removeAll()
+          state.inFlightPullRequestRefreshRepositoryIDs.removeAll()
+          state.inFlightPullRequestBranchSnapshotsByRepositoryID.removeAll()
+          return .merge(
+            .cancel(id: CancelID.githubIntegrationRecovery),
+            .send(.refreshGithubIntegrationAvailability)
+          )
         }
-        let followupEffects: [Effect<Action>] = [
-          roots.isEmpty ? .none : .send(.reloadRepositories(animated: true))
-        ]
-        return .concatenate(
-          .merge(immediateEffects),
-          .merge(followupEffects)
+        state.githubIntegrationAvailability = .disabled
+        state.pendingPullRequestRefreshByRepositoryID.removeAll()
+        state.queuedPullRequestRefreshByRepositoryID.removeAll()
+        state.inFlightPullRequestRefreshRepositoryIDs.removeAll()
+        state.inFlightPullRequestBranchSnapshotsByRepositoryID.removeAll()
+        let worktreeIDs = state.sidebarItems.compactMap { $0.pullRequest != nil ? $0.id : nil }
+        var clearEffects: [Effect<Action>] = []
+        for worktreeID in worktreeIDs {
+          clearEffects.append(
+            state.updateWorktreePullRequestEffect(
+              worktreeID: worktreeID,
+              pullRequest: nil,
+            )
+          )
+        }
+        return .merge(
+          clearEffects + [
+            .cancel(id: CancelID.githubIntegrationAvailability),
+            .cancel(id: CancelID.githubIntegrationRecovery),
+          ]
         )
 
-      case .repositoriesMoved(let offsets, let destination):
-        var ordered = state.orderedRepositoryIDs()
-        guard !offsets.isEmpty, ordered.indices.contains(offsets.min() ?? 0),
-          destination <= ordered.count
-        else { return .none }
-        ordered.move(fromOffsets: offsets, toOffset: destination)
-        withAnimation(.snappy(duration: 0.2)) {
-          state.$sidebar.withLock { sidebar in
-            var reordered: OrderedDictionary<Repository.ID, SidebarState.Section> = [:]
-            for id in ordered {
-              reordered[id] = sidebar.sections[id] ?? .init()
-            }
-            // Sections for repos still loading / not yet seen are
-            // reliably absent from `ordered`; append them in their
-            // original relative order so a live-row reorder doesn't
-            // silently reshuffle curation on them.
-            for (id, section) in sidebar.sections where reordered[id] == nil {
-              reordered[id] = section
-            }
-            sidebar.sections = reordered
-          }
-        }
+      case .setMergedWorktreeAction(let action):
+        state.mergedWorktreeAction = action
         return .none
 
-      case .pinnedWorktreesMoved(let repositoryID, let offsets, let destination):
-        guard let repository = state.repositories[id: repositoryID] else { return .none }
-        let currentPinned = state.orderedPinnedWorktreeIDs(in: repository)
-        guard currentPinned.count > 1 else { return .none }
-        var reordered = currentPinned
-        reordered.move(fromOffsets: offsets, toOffset: destination)
-        withAnimation(.snappy(duration: 0.2)) {
+      case .setAutoDeleteArchivedWorktreesAfterDays(let days):
+        state.autoDeleteArchivedWorktreesAfterDays = days
+        guard days != nil else { return .none }
+        return .send(.autoDeleteExpiredArchivedWorktrees)
+
+      case .autoDeleteExpiredArchivedWorktrees:
+        guard let period = state.autoDeleteArchivedWorktreesAfterDays else { return .none }
+        let cutoff = now.addingTimeInterval(-Double(period.rawValue) * secondsPerDay)
+        var targets: [(Worktree.ID, Repository.ID)] = []
+        // Folder-synthetic archived entries can't be produced by
+        // any current user path (context-menu / shortcut / deeplink
+        // all reject folder archives). If one leaks into persisted
+        // state: a bug in a future archive path, a migration
+        // regression, or hand-edited sidebar.json, so we both flag
+        // the invariant breach AND purge the stray entry from
+        // `sidebar.archivedWorktrees`, so the next reload doesn't
+        // re-fire `reportIssue` forever.
+        var strayFolderArchives: [(Worktree.ID, Repository.ID)] = []
+        for archived in state.sidebar.archivedWorktrees
+        where state.repositories[id: archived.repositoryID]?.kind == .folder {
+          strayFolderArchives.append((archived.worktreeID, archived.repositoryID))
+        }
+        if !strayFolderArchives.isEmpty {
+          for (worktreeID, _) in strayFolderArchives {
+            reportIssue(
+              """
+              Auto-delete encountered folder-synthetic archived worktree \(worktreeID): \
+              folders are not archivable. Purging the stray entry.
+              """
+            )
+          }
           state.$sidebar.withLock { sidebar in
-            sidebar.reorder(bucket: .pinned, in: repositoryID, to: reordered)
+            for (worktreeID, repositoryID) in strayFolderArchives {
+              sidebar.remove(worktree: worktreeID, in: repositoryID, from: .archived)
+            }
           }
-          RepositoriesFeature.syncSidebar(&state)
         }
-        return .none
-
-      case .unpinnedWorktreesMoved(let repositoryID, let offsets, let destination):
-        guard let repository = state.repositories[id: repositoryID] else { return .none }
-        let currentUnpinned = state.orderedUnpinnedWorktreeIDs(in: repository)
-        guard currentUnpinned.count > 1 else { return .none }
-        var reordered = currentUnpinned
-        reordered.move(fromOffsets: offsets, toOffset: destination)
-        withAnimation(.snappy(duration: 0.2)) {
-          state.$sidebar.withLock { sidebar in
-            sidebar.reorder(bucket: .unpinned, in: repositoryID, to: reordered)
+        for archived in state.sidebar.archivedWorktrees {
+          let worktreeID = archived.worktreeID
+          guard archived.archivedAt <= cutoff else { continue }
+          if state.repositories[id: archived.repositoryID]?.kind == .folder {
+            // Already purged above, defensive skip.
+            continue
           }
-          RepositoriesFeature.syncSidebar(&state)
+          let autoDeleteLifecycle = state.sidebarItems[id: worktreeID]?.lifecycle ?? .idle
+          guard autoDeleteLifecycle == .idle else { continue }
+          guard let repository = state.repositories.first(where: { $0.worktrees[id: worktreeID] != nil }),
+            let worktree = repository.worktrees[id: worktreeID]
+          else {
+            repositoriesLogger.debug(
+              "Auto-delete skipping expired worktree \(worktreeID): not found in loaded repositories."
+            )
+            continue
+          }
+          guard !state.isMainWorktree(worktree) else {
+            repositoriesLogger.debug(
+              "Auto-delete skipping expired worktree \(worktreeID): main worktree cannot be deleted."
+            )
+            continue
+          }
+          targets.append((worktreeID, repository.id))
         }
-        return .none
-
-      case .deleteWorktreeFailed(let message, let worktreeID):
-        state.alert = messageAlert(title: "Unable to delete worktree", message: message)
-        guard state.sidebarItems[id: worktreeID]?.lifecycle == .deleting else { return .none }
-        return state.setRowLifecycleEffect(worktreeID, .idle)
+        guard !targets.isEmpty else { return .none }
+        repositoriesLogger.info("Auto-deleting \(targets.count) expired archived worktree(s).")
+        return .merge(
+          targets.map { worktreeID, repositoryID in
+            .send(.deleteSidebarItemConfirmed(worktreeID, repositoryID))
+          }
+        )
 
-      case .requestDeleteRepository(let repositoryID):
-        state.alert = confirmationAlertForRepositoryRemoval(repositoryID: repositoryID, state: state)
+      case .setMoveNotifiedWorktreeToTop(let isEnabled):
+        state.moveNotifiedWorktreeToTop = isEnabled
         return .none
-
-      case .requestRemoveFailedRepository(let repositoryID):
-        state.alert = confirmationAlertForFailedRepositoryRemoval(
-          repositoryID: repositoryID, state: state
-        )
+      default:
         return .none
+      }
+    }
+  }
 
-      case .removeFailedRepository(let repositoryID):
-        state.loadFailuresByID.removeValue(forKey: repositoryID)
-        state.repositoryRoots.removeAll {
-          $0.standardizedFileURL.path(percentEncoded: false) == repositoryID
-        }
-        // Drop persisted customization so re-adding the same path doesn't
-        // silently restore the old title/color, matching the healthy-repo path.
-        state.$sidebar.withLock { sidebar in
-          sidebar.sections.removeValue(forKey: repositoryID)
-        }
-        state.dropStaleFailedRepositorySelection()
-        return .run { send in
-          let loadedPaths = await repositoryPersistence.loadRoots()
-          var seen: Set<String> = []
-          let rootPaths = loadedPaths.filter { seen.insert($0).inserted }
-          let remaining = rootPaths.filter { $0 != repositoryID }
-          await repositoryPersistence.saveRoots(remaining)
-          await repositoryPersistence.pruneRepositoryConfigs([repositoryID])
-          let roots = remaining.map { URL(fileURLWithPath: $0) }
-          let (repositories, failures) = await loadRepositoriesData(roots)
-          await send(
-            .repositoriesLoaded(
-              repositories,
-              failures: failures,
-              roots: roots,
-              animated: true
-            )
-          )
-        }
-        .cancellable(id: CancelID.load, cancelInFlight: true)
-
-      case .alert(.presented(.confirmRemoveFailedRepository(let repositoryID))):
-        state.alert = nil
-        return .send(.removeFailedRepository(repositoryID))
-
-      case .alert(.presented(.confirmDeleteRepository(let repositoryID))):
-        guard let repository = state.repositories[id: repositoryID] else {
-          return .none
-        }
-        if state.removingRepositoryIDs[repository.id] != nil {
-          return .none
-        }
-        state.alert = nil
-        // Section-level removal — Supacode never nukes a git repo's
-        // on-disk state. No script runs; signal completion
-        // immediately and let the aggregator (batch of 1) emit the
-        // terminal.
-        let selectionWasRemoved =
-          state.selectedWorktreeID.map { id in
-            repository.worktrees.contains(where: { $0.id == id })
-          } ?? false
-        let batchID = uuid()
-        state.removingRepositoryIDs[repository.id] = RepositoryRemovalRecord(
-          disposition: .gitRepositoryUnlink, batchID: batchID
-        )
-        Self.syncSidebar(&state)
-        state.activeRemovalBatches[batchID] =
-          ActiveRemovalBatch(id: batchID, pending: [repository.id])
-        return .send(
-          .repositoryRemovalCompleted(
-            repository.id, outcome: .success, selectionWasRemoved: selectionWasRemoved))
-
-      case .repositoryRemovalCompleted(
-        let repositoryID, let outcome, let selectionWasRemoved):
-        // Aggregator entry point. Every repo-level removal
-        // (successful or not) drains through here so bulk batches
-        // fire a single terminal `.repositoriesRemoved` after the
-        // last target reports in. `.failure` outcomes keep the
-        // batch progressing past failures without removing the
-        // repo from state.
-        guard let record = state.removingRepositoryIDs[repositoryID],
-          var batch = state.activeRemovalBatches[record.batchID]
-        else {
-          // Orphaned completion — every sender seeds the record +
-          // batch before signalling, so arriving here means a bug
-          // (e.g. future caller skipped setup). Surface it loudly
-          // via `reportIssue` so tests fail and release builds emit
-          // a warning, and defensively clean up any state the
-          // absent terminal would otherwise leave hanging.
-          reportIssue(
-            """
-            repositoryRemovalCompleted: no active batch for \(repositoryID). \
-            This indicates an invariant violation — every confirm handler \
-            must seed a batch before per-target work fires.
-            """
-          )
-          state.removingRepositoryIDs[repositoryID] = nil
-          // Narrow the cleanup to the folder-synthetic worktree id so a future
-          // caller passing a git repo id here can't disturb sibling-worktree state.
-          let orphanFolderWorktreeID = Repository.folderWorktreeID(
-            for: URL(fileURLWithPath: repositoryID)
-          )
-          switch outcome {
-          case .success:
-            return .send(
-              .repositoriesRemoved([repositoryID], selectionWasRemoved: selectionWasRemoved))
-          case .failureSilent:
-            return state.clearFolderRowLifecycleEffect(orphanFolderWorktreeID)
-          case .failureWithMessage(let message):
-            state.alert = messageAlert(
-              title: "Delete from disk failed", message: message
-            )
-            return state.clearFolderRowLifecycleEffect(orphanFolderWorktreeID)
-          }
-        }
-        let batchID = record.batchID
-        batch.pending.remove(repositoryID)
-        batch.selectionWasRemoved = batch.selectionWasRemoved || selectionWasRemoved
-        // Failure cleanup is scoped to the folder-synthetic worktree id because only
-        // folder dispositions reach a failure completion. Git repo unlink hardcodes success.
-        let folderWorktreeIDForFailure: Worktree.ID? =
-          record.disposition.isFolder
-          ? Repository.folderWorktreeID(for: URL(fileURLWithPath: repositoryID))
-          : nil
-        var rowEffects: [Effect<Action>] = []
-        switch outcome {
-        case .success:
-          batch.succeeded.append(repositoryID)
-        // `.repositoriesRemoved` clears `removingRepositoryIDs`
-        // for the successful targets as part of the terminal —
-        // leave the record in place so the UI keeps showing the
-        // "removing" indicator until then.
-        case .failureSilent:
-          state.removingRepositoryIDs[repositoryID] = nil
-          if let folderWorktreeIDForFailure {
-            rowEffects.append(state.clearFolderRowLifecycleEffect(folderWorktreeIDForFailure))
-          }
-          batch.hasSilentFailure = true
-        case .failureWithMessage(let message):
-          state.removingRepositoryIDs[repositoryID] = nil
-          if let folderWorktreeIDForFailure {
-            rowEffects.append(state.clearFolderRowLifecycleEffect(folderWorktreeIDForFailure))
-          }
-          batch.failureMessagesByRepositoryID[repositoryID] = message
-        }
-        if batch.pending.isEmpty {
-          state.activeRemovalBatches[batchID] = nil
-          // Consolidated failure alert — when any target in the
-          // batch reported a `.failureWithMessage`, surface one
-          // alert listing them. Avoids parallel `.presentAlert`
-          // races where the last trash failure overwrites the
-          // others.
-          //
-          // When a `.failureSilent` target in the same batch has
-          // already set `state.alert` directly (blocking-script
-          // failure / user cancel / kind-flip), preserve the
-          // caller's alert and log the trash failures instead of
-          // clobbering. macOS only shows one alert at a time, and
-          // the script-failure alert carries actionable context
-          // (the "View Terminal" button) that the consolidated
-          // trash alert does not.
-          if !batch.failureMessagesByRepositoryID.isEmpty {
-            if batch.hasSilentFailure {
-              for (id, message) in batch.failureMessagesByRepositoryID {
-                let name = state.repositories[id: id]?.name ?? id
-                repositoriesLogger.warning(
-                  "Trash failure for \(name) (\(id)) suppressed "
-                    + "(silent-failure alert already showing for sibling target): \(message)"
-                )
-              }
-            } else {
-              // Resolve names NOW (while `state.repositories`
-              // still has every batch member) so the alert stays
-              // user-recognizable even if the downstream
-              // `.repositoriesRemoved` → `.repositoriesLoaded`
-              // reloads prune an entry before the alert is read.
-              var namesByRepositoryID: [Repository.ID: String] = [:]
-              for id in batch.failureMessagesByRepositoryID.keys {
-                if let name = state.repositories[id: id]?.name {
-                  namesByRepositoryID[id] = name
-                }
-              }
-              state.alert = consolidatedTrashFailureAlert(
-                failureMessagesByRepositoryID: batch.failureMessagesByRepositoryID,
-                namesByRepositoryID: namesByRepositoryID
-              )
-            }
-          }
-          guard !batch.succeeded.isEmpty else {
-            return .merge(rowEffects)
-          }
-          rowEffects.append(
-            .send(
-              .repositoriesRemoved(
-                batch.succeeded, selectionWasRemoved: batch.selectionWasRemoved))
-          )
-          return .merge(rowEffects)
-        }
-        state.activeRemovalBatches[batchID] = batch
-        return .merge(rowEffects)
-
-      case .repositoriesRemoved(let repositoryIDs, let selectionWasRemoved):
-        // Bulk terminal: mutates `repositories` / `repositoryRoots`
-        // synchronously, emits one `.repositoriesLoaded` for
-        // reconciliation and a single cancellable persistence save.
-        // Firing once per batch (instead of once per target) removes
-        // the reload race.
-        guard !repositoryIDs.isEmpty else { return .none }
-        let idSet = Set(repositoryIDs)
-        for id in repositoryIDs {
-          let kind = (state.repositories[id: id]?.isGitRepository ?? true) ? "git" : "folder"
-          analyticsClient.capture("repository_removed", ["kind": kind])
-          state.removingRepositoryIDs[id] = nil
-        }
-        state.resetRowLifecycleSyncBeforeReconcile(inRepositories: idSet)
-        if selectionWasRemoved {
-          state.selection = nil
-          state.shouldSelectFirstAfterReload = true
-        }
-        // Drop sidebar sections for explicitly-removed repos before
-        // reconcile fires. `preserveOrphanSections` keeps customized
-        // tombstones across transient drops (filesystem flutter), but
-        // an explicit "Remove Repository" must not silently restore
-        // the user's old title / color when the same path is re-added
-        // later.
-        state.$sidebar.withLock { sidebar in
-          for id in repositoryIDs {
-            sidebar.sections.removeValue(forKey: id)
-          }
-        }
-        let selectedWorktree = state.worktree(for: state.selectedWorktreeID)
-        let remainingRepositories = Array(state.repositories.filter { !idSet.contains($0.id) })
-        let remainingRoots = state.repositoryRoots.filter {
-          !idSet.contains($0.standardizedFileURL.path(percentEncoded: false))
-        }
-        let remainingFailures = state.loadFailuresByID
-          .filter { !idSet.contains($0.key) }
-          .map { LoadFailure(rootID: $0.key, message: $0.value) }
-        let pathsToPersist = remainingRoots.map {
-          $0.standardizedFileURL.path(percentEncoded: false)
-        }
-        let removedIDs = Array(idSet)
-        return .merge(
-          .send(.delegate(.selectedWorktreeChanged(selectedWorktree))),
-          .send(
-            .repositoriesLoaded(
-              remainingRepositories,
-              failures: remainingFailures,
-              roots: remainingRoots,
-              animated: true
-            )
-          ),
-          .run { _ in
-            // `saveRoots` replaces the `repositoryRoots` array with
-            // the pruned list; `pruneRepositoryConfigs` drops the
-            // `repositories` dict entries (scripts / run config /
-            // open action) for repos that just left. Without the
-            // second step those entries pile up forever —
-            // especially visible for folder repos that users add +
-            // remove while exploring.
-            await repositoryPersistence.saveRoots(pathsToPersist)
-            await repositoryPersistence.pruneRepositoryConfigs(removedIDs)
-          }
-          .cancellable(id: CancelID.persistRoots, cancelInFlight: true)
-        )
-
+  /// Pin / unpin / toast / notification / worktree-info-event handlers, split from `body` to keep
+  /// its `Reduce` closure under the type-checker's complexity limit.
+  var worktreeNotificationReducer: some Reducer<State, Action> {
+    Reduce { state, action in
+      switch action {
       case .pinWorktree(let worktreeID):
         // Git "main" worktrees never appear in any sidebar bucket (the
         // seed pass skips them), so pinning one is a no-op. Folder
@@ -2572,11 +2643,22 @@ struct RepositoriesFeature {
           // invariant against pre-states that have the row in `.pinned` and
           // `.unpinned` simultaneously (hand-edit, migrator race) and also
           // handles the not-bucketed case (folders before first reconcile).
-          sidebar.removeAnywhere(worktree: worktreeID, in: repositoryID)
+          // The carried Item preserves user-set `title` / `color` across
+          // the bucket move. Prefer the logical source (`.unpinned`) so a
+          // corrupted double-bucket pre-state surfaces the live unpinned
+          // row's payload, not a stale `.pinned` sibling.
+          var carried =
+            sidebar.removeAnywhere(
+              worktree: worktreeID,
+              in: repositoryID,
+              preferring: [.unpinned, .pinned, .archived]
+            ) ?? .init()
+          carried.archivedAt = nil
           sidebar.insert(
             worktree: worktreeID,
             in: repositoryID,
             bucket: .pinned,
+            item: carried,
             position: 0
           )
         }
@@ -2596,12 +2678,22 @@ struct RepositoriesFeature {
         analyticsClient.capture("worktree_unpinned", nil)
         state.$sidebar.withLock { sidebar in
           // Same invariant as `pinWorktree`: collapse any pre-existing
-          // bucket placement into a single `.unpinned` entry.
-          sidebar.removeAnywhere(worktree: worktreeID, in: repositoryID)
+          // bucket placement into a single `.unpinned` entry, carrying
+          // the Item forward so `title` / `color` survive unpin. Prefer
+          // `.pinned` so a corrupted double-bucket pre-state surfaces
+          // the live pinned row's payload over a stale unpinned sibling.
+          var carried =
+            sidebar.removeAnywhere(
+              worktree: worktreeID,
+              in: repositoryID,
+              preferring: [.pinned, .unpinned, .archived]
+            ) ?? .init()
+          carried.archivedAt = nil
           sidebar.insert(
             worktree: worktreeID,
             in: repositoryID,
             bucket: .unpinned,
+            item: carried,
             position: 0
           )
         }
@@ -2665,7 +2757,7 @@ struct RepositoriesFeature {
         if state.moveNotifiedWorktreeToTop, !state.isMainWorktree(worktree), !state.isWorktreePinned(worktree) {
           let reordered = state.reorderedUnpinnedWorktreeIDs(for: worktreeID, in: repository)
           // Only reorder when the bumped worktree currently lives in
-          // (or is about to land in) the unpinned bucket — pinned
+          // (or is about to land in) the unpinned bucket, pinned
           // rows live in `.pinned` and should not be perturbed by
           // notification arrivals on a sibling.
           let currentUnpinned = Array(
@@ -2689,7 +2781,7 @@ struct RepositoriesFeature {
             return .none
           }
           let worktreeURL = worktree.workingDirectory
-          let gitClient = gitClient
+          let gitClient = gitClient(for: worktree)
           return .run { send in
             if let name = await gitClient.branchName(worktreeURL) {
               await send(.worktreeBranchNameLoaded(worktreeID: worktreeID, name: name))
@@ -2700,7 +2792,7 @@ struct RepositoriesFeature {
             return .none
           }
           let worktreeURL = worktree.workingDirectory
-          let gitClient = gitClient
+          let gitClient = gitClient(for: worktree)
           return .run { send in
             if let changes = await gitClient.lineChanges(worktreeURL) {
               await send(
@@ -2719,6 +2811,11 @@ struct RepositoriesFeature {
           else {
             return .none
           }
+          // PR refresh runs `gh` against the local repo; a remote-only repo has
+          // no local checkout to serve it. Skip (gh-over-ssh is out of scope).
+          guard state.repositories[id: repositoryID]?.host == nil else {
+            return .none
+          }
           var seen = Set<String>()
           let branches =
             worktrees
@@ -2789,576 +2886,894 @@ struct RepositoriesFeature {
             return .none
           }
         }
+      default:
+        return .none
+      }
+    }
+  }
 
-      case .refreshGithubIntegrationAvailability:
-        guard state.githubIntegrationAvailability != .checking,
-          state.githubIntegrationAvailability != .disabled
-        else {
-          return .none
-        }
-        state.githubIntegrationAvailability = .checking
-        let githubIntegration = githubIntegration
-        return .run { send in
-          let isAvailable = await githubIntegration.isAvailable()
-          await send(.githubIntegrationAvailabilityUpdated(isAvailable))
-        }
-        .cancellable(id: CancelID.githubIntegrationAvailability, cancelInFlight: true)
-
-      case .githubIntegrationAvailabilityUpdated(let isAvailable):
-        guard state.githubIntegrationAvailability != .disabled else {
-          return .none
-        }
-        state.githubIntegrationAvailability = isAvailable ? .available : .unavailable
-        guard isAvailable else {
-          for (repositoryID, queued) in state.queuedPullRequestRefreshByRepositoryID {
-            state.pendingPullRequestRefreshByRepositoryID.queuePullRequestRefresh(
-              repositoryID: repositoryID,
-              repositoryRootURL: queued.repositoryRootURL,
-              worktreeIDs: queued.worktreeIDs,
-            )
-          }
-          state.queuedPullRequestRefreshByRepositoryID.removeAll()
-          state.inFlightPullRequestRefreshRepositoryIDs.removeAll()
-          state.inFlightPullRequestBranchSnapshotsByRepositoryID.removeAll()
-          return .run { send in
-            while !Task.isCancelled {
-              try? await ContinuousClock().sleep(for: githubIntegrationRecoveryInterval)
-              guard !Task.isCancelled else {
-                return
-              }
-              await send(.refreshGithubIntegrationAvailability)
-            }
+  var body: some Reducer<State, Action> {
+    Reduce { state, action in
+      switch action {
+      case .task:
+        // `sidebar` is already hydrated from `sidebar.json` (loaded
+        // synchronously by the SharedKey when State is constructed),
+        // so `.task` has no persistence fan-out left, it just flags
+        // the focus restore and kicks off the repository load.
+        state.shouldRestoreLastFocusedWorktree = state.sidebar.focusedWorktreeID != nil
+        return .send(.loadPersistedRepositories)
+
+      case .sidebarGroupingTogglesChanged:
+        // The post-reduce hook below picks up the toggle state and rebuilds.
+        // Auto-dismiss the highlight onboarding card when both toggles end up
+        // off; the `SidebarCommands` menu setters fire the same dismiss so
+        // toggling while the sidebar column is collapsed is also covered.
+        @Shared(.sidebarGroupPinnedRows) var groupPinned
+        @Shared(.sidebarGroupActiveRows) var groupActive
+        if !groupPinned, !groupActive {
+          @Shared(.appStorage("highlightRelevantOnboardingDismissedAt"))
+          var dismissedAt: Date = .distantPast
+          if !HighlightRelevantOnboardingCardView.isDismissed(at: dismissedAt) {
+            $dismissedAt.withLock { $0 = now }
           }
-          .cancellable(id: CancelID.githubIntegrationRecovery, cancelInFlight: true)
-        }
-        let pendingRefreshes = state.pendingPullRequestRefreshByRepositoryID.values.sorted {
-          $0.repositoryRootURL.path(percentEncoded: false)
-            < $1.repositoryRootURL.path(percentEncoded: false)
         }
-        state.pendingPullRequestRefreshByRepositoryID.removeAll()
-        return .merge(
-          .cancel(id: CancelID.githubIntegrationRecovery),
-          .merge(
-            pendingRefreshes.map { pending in
-              .send(
-                .worktreeInfoEvent(
-                  .repositoryPullRequestRefresh(
-                    repositoryRootURL: pending.repositoryRootURL,
-                    worktreeIDs: pending.worktreeIDs
-                  )
-                )
-              )
-            }
-          )
-        )
+        return .none
 
-      case .repositoryPullRequestRefreshCompleted(let repositoryID):
-        state.inFlightPullRequestRefreshRepositoryIDs.remove(repositoryID)
-        state.inFlightPullRequestBranchSnapshotsByRepositoryID.removeValue(forKey: repositoryID)
-        guard state.githubIntegrationAvailability == .available,
-          let pending = state.queuedPullRequestRefreshByRepositoryID.removeValue(
-            forKey: repositoryID
-          )
-        else {
-          return .none
-        }
-        return .send(
-          .worktreeInfoEvent(
-            .repositoryPullRequestRefresh(
-              repositoryRootURL: pending.repositoryRootURL,
-              worktreeIDs: pending.worktreeIDs
-            )
-          )
-        )
+      case .sidebarNestByBranchChanged:
+        // No-op handler: the post-reduce hook reads `sidebarNestWorktreesByBranch`
+        // and rebuilds `sidebarStructure` so the alphabetical per-bucket sort
+        // lands in `slotByID` / `hotkeySlots`.
+        return .none
 
-      case .worktreeBranchNameLoaded(let worktreeID, let name):
-        state.updateWorktreeName(worktreeID, name: name)
-        Self.syncSidebar(&state)
+      case .setOpenPanelPresented(let isPresented):
+        state.isOpenPanelPresented = isPresented
         return .none
 
-      case .worktreeLineChangesLoaded(let worktreeID, let added, let removed):
-        return state.updateWorktreeLineChangesEffect(
-          worktreeID: worktreeID,
-          added: added,
-          removed: removed,
-        )
+      case .requestAddRemoteRepository, .requestEditRemoteRepository, .remoteConnectionForm:
+        // Handled by `remoteConnectionFormReducer` so the form's child reducer
+        // runs before the delegate handler nils the presented state.
+        return .none
 
-      case .repositoryPullRequestsLoaded(let repositoryID, let pullRequestsByWorktreeID):
-        guard let repository = state.repositories[id: repositoryID] else {
-          return .none
+      case .removeRemoteRepository(let repositoryID):
+        @Shared(.remoteRepositoryRoots) var remoteRepositoryRoots
+        $remoteRepositoryRoots.withLock { roots in
+          roots.removeAll { $0 == repositoryID.rawValue }
         }
-        let branchSnapshot = state.inFlightPullRequestBranchSnapshotsByRepositoryID[repositoryID] ?? [:]
-        var archiveWorktreeIDs: [Worktree.ID] = []
-        var deleteWorktreeIDs: [Worktree.ID] = []
-        var rowEffects: [Effect<Action>] = []
-        // Queried-but-missing worktrees must still clear their row watermark.
-        let dispatchIDs = Set(branchSnapshot.keys).union(pullRequestsByWorktreeID.keys)
-        for worktreeID in dispatchIDs.sorted() {
-          guard let worktree = repository.worktrees[id: worktreeID] else {
-            continue
-          }
-          let pullRequest = pullRequestsByWorktreeID[worktreeID] ?? nil
-          let previousPullRequest = state.sidebarItems[id: worktreeID]?.pullRequest
-          let previousMerged = previousPullRequest?.state == "MERGED"
-          let nextMerged = pullRequest?.state == "MERGED"
-          // Dispatch unconditionally so an identical-PR result still clears the row's watermark.
-          rowEffects.append(
-            state.updateWorktreePullRequestEffect(
-              worktreeID: worktreeID,
-              pullRequest: pullRequest,
-              branchAtQueryTime: branchSnapshot[worktreeID],
+        // Drop persisted customization so re-adding the same host/path doesn't
+        // silently restore the old title/color, matching the other removal paths.
+        state.$sidebar.withLock { _ = $0.sections.removeValue(forKey: repositoryID) }
+        return .send(.loadPersistedRepositories)
+
+      case .loadPersistedRepositories:
+        state.alert = nil
+        state.isRefreshingWorktrees = false
+        return .run { send in
+          let loadedPaths = await repositoryPersistence.loadRoots()
+          let rootPaths = RepositoryPathNormalizer.normalize(loadedPaths)
+          let roots = rootPaths.map { URL(fileURLWithPath: $0) }
+          let (repositories, failures) = await loadRepositoriesData(roots)
+          await send(
+            .repositoriesLoaded(
+              repositories,
+              failures: failures,
+              roots: roots,
+              animated: false
             )
           )
-          let mergedLifecycle = state.sidebarItems[id: worktreeID]?.lifecycle ?? .idle
-          if let mergedAction = state.mergedWorktreeAction,
-            !previousMerged,
-            nextMerged,
-            !state.isMainWorktree(worktree),
-            !state.isWorktreeArchived(worktreeID),
-            mergedLifecycle != .deleting,
-            mergedLifecycle != .deletingScript
-          {
-            switch mergedAction {
-            case .archive:
-              archiveWorktreeIDs.append(worktreeID)
-            case .delete:
-              deleteWorktreeIDs.append(worktreeID)
+        }
+        .cancellable(id: CancelID.load, cancelInFlight: true)
+
+      case .refreshWorktrees:
+        state.isRefreshingWorktrees = true
+        return .send(.reloadRepositories(animated: false))
+
+      case .reloadRepositories(let animated):
+        // Deliberately NOT clearing `state.alert` here,
+        // `.reloadRepositories` is a data-layer refresh and fires
+        // from both user intents (refresh hotkey) and downstream of
+        // delete/archive flows. Wiping a just-set terminal alert
+        // (e.g. the consolidated trash-failure alert the aggregator
+        // set before firing `.repositoriesRemoved` → `.repositoriesLoaded`
+        // → `.autoDeleteExpiredArchivedWorktrees`) was the source
+        // of an observable "failure alert vanishes on the same
+        // tick" bug. Confirmation-style alerts are already cleared
+        // by their own confirm handlers upstream of this action.
+        let roots = state.repositoryRoots
+        // A remote-only setup has no local roots, but the load path still
+        // appends persisted remote configs, so a refresh must run for it.
+        guard !roots.isEmpty || !Self.persistedRemoteRepositoryRoots().isEmpty else {
+          state.isRefreshingWorktrees = false
+          return .none
+        }
+        return loadRepositories(roots, animated: animated)
+
+      case .repositoriesLoaded(let repositories, let failures, let roots, let animated):
+        state.isRefreshingWorktrees = false
+        let previousSelection = state.selectedWorktreeID
+        let previousSelectedWorktree = state.worktree(for: previousSelection)
+        let mergedRemote = Self.mergePersistedRemoteRepositories(into: repositories, existingState: state)
+        let mergedRepositories = mergedRemote.repositories
+        let incomingRepositories = IdentifiedArray(uniqueElements: mergedRepositories)
+        let repositoriesChanged = incomingRepositories != state.repositories
+        _ = applyRepositories(
+          mergedRepositories,
+          roots: roots,
+          // Don't prune archived worktree ids while remotes are still resolving:
+          // their worktrees aren't in the roster yet.
+          shouldPruneArchivedWorktreeIDs: failures.isEmpty && mergedRemote.resolvingIDs.isEmpty,
+          state: &state,
+          animated: animated
+        )
+        state.repositoryRoots = roots
+        state.isInitialLoadComplete = true
+        state.resolvingRemoteRepositoryIDs = mergedRemote.resolvingIDs
+        // Local failures only; remote failures arrive via `.remoteRepositoryResolved`.
+        state.loadFailuresByID = Dictionary(
+          uniqueKeysWithValues: failures.map { ($0.rootID, $0.message) }
+        )
+        state.dropStaleFailedRepositorySelection()
+        let selectedWorktree = state.worktree(for: state.selectedWorktreeID)
+        let selectionChanged = state.hasSelectionChanged(
+          previousSelectionID: previousSelection,
+          previousSelectedWorktree: previousSelectedWorktree,
+          selectedWorktreeID: state.selectedWorktreeID,
+          selectedWorktree: selectedWorktree,
+        )
+        var allEffects: [Effect<Action>] = []
+        if repositoriesChanged {
+          allEffects.append(.send(.delegate(.repositoriesChanged(state.repositories))))
+        }
+        if selectionChanged {
+          allEffects.append(.send(.delegate(.selectedWorktreeChanged(selectedWorktree))))
+        }
+        // The sidebar reconciler (`reconcileSidebarState`) already
+        // flushed any sidebar mutations through `$sidebar.withLock`,
+        // so no per-slice save effects are needed here, the SharedKey
+        // writes `sidebar.json` atomically.
+        if state.autoDeleteArchivedWorktreesAfterDays != nil {
+          allEffects.append(.send(.autoDeleteExpiredArchivedWorktrees))
+        }
+        // Re-probe remotes on every reload so refreshes re-list them.
+        if mergedRemote.repositories.contains(where: { $0.host != nil }) {
+          allEffects.append(.send(.resolveRemoteRepositories))
+        }
+        return .merge(allEffects)
+
+      case .resolveRemoteRepositories:
+        let roots = Self.persistedRemoteRepositoryRoots()
+        guard !roots.isEmpty else { return .none }
+        return .run { send in
+          // Resolve concurrently so one slow host doesn't gate the others; each
+          // streams its own result. The background-probe ssh profile bounds a
+          // dead host, so a stuck connection never spins forever.
+          await withTaskGroup(of: Void.self) { group in
+            var seen: Set<Repository.ID> = []
+            for root in roots {
+              guard let (host, remotePath) = Self.parseRemoteRoot(root) else {
+                repositoriesLogger.warning("Skipping unparseable persisted remote id: \(root).")
+                continue
+              }
+              let repoID = Self.remoteRepositoryID(host: host, remotePath: remotePath)
+              guard seen.insert(repoID).inserted else { continue }
+              group.addTask {
+                let loaded = await Self.loadRemoteRepository(host: host, remotePath: remotePath, repoID: repoID)
+                await send(
+                  .remoteRepositoryResolved(
+                    repositoryID: repoID,
+                    repository: loaded.repository,
+                    failureMessage: loaded.failure?.message
+                  )
+                )
+              }
             }
           }
         }
-        let effects: [Effect<Action>] =
-          rowEffects
-          + archiveWorktreeIDs.map { .send(.archiveWorktreeConfirmed($0, repositoryID)) }
-          + deleteWorktreeIDs.map { .send(.deleteSidebarItemConfirmed($0, repositoryID)) }
-        guard !effects.isEmpty else {
+        .cancellable(id: CancelID.resolveRemoteRepositories, cancelInFlight: true)
+
+      case .remoteRepositoryResolved(let repositoryID, let repository, let failureMessage):
+        let wasResolving = state.resolvingRemoteRepositoryIDs.remove(repositoryID) != nil
+        // Drop a result whose config was removed or re-keyed mid-probe.
+        guard let existing = state.repositories[id: repositoryID] else { return .none }
+        // A superseded probe must not downgrade a resolved remote to a placeholder.
+        if !wasResolving, repository.worktrees.isEmpty, !existing.worktrees.isEmpty {
+          repositoriesLogger.debug("Ignoring stale remote resolution for \(repositoryID).")
           return .none
         }
-        return .merge(effects)
-
-      case .pullRequestAction(let worktreeID, let action):
-        guard let worktree = state.worktree(for: worktreeID),
-          let repositoryID = state.repositoryID(containing: worktreeID),
-          let repository = state.repositories[id: repositoryID],
-          let pullRequest = state.sidebarItems[id: worktreeID]?.pullRequest
-        else {
-          return .send(
-            .presentAlert(
-              title: "Pull request not available",
-              message: "Supacode could not find a pull request for this worktree."
-            )
-          )
+        if let failureMessage {
+          state.loadFailuresByID[repositoryID] = failureMessage
+        } else {
+          state.loadFailuresByID[repositoryID] = nil
         }
-        let repoRoot = worktree.repositoryRootURL
-        let worktreeRoot = worktree.workingDirectory
-        let pullRequestRefresh = WorktreeInfoWatcherClient.Event.repositoryPullRequestRefresh(
-          repositoryRootURL: repoRoot,
-          worktreeIDs: repository.worktrees.map(\.id)
+        let didChange = existing != repository
+        state.repositories[id: repositoryID] = repository
+        // Reconcile the updated repo's worktrees into the sidebar (seeds buckets
+        // / items) exactly as a bulk load would.
+        _ = applyRepositories(
+          Array(state.repositories),
+          roots: state.repositoryRoots,
+          shouldPruneArchivedWorktreeIDs: false,
+          state: &state,
+          animated: true
         )
-        let branchName = pullRequest.headRefName ?? worktree.name
-        let failingCheckDetailsURL = (pullRequest.statusCheckRollup?.checks ?? []).first {
-          $0.checkState == .failure && $0.detailsUrl != nil
-        }?.detailsUrl
-        switch action {
-        case .openOnGithub:
-          guard let url = URL(string: pullRequest.url) else {
-            return .send(
-              .presentAlert(
-                title: "Invalid pull request URL",
-                message: "Supacode could not open the pull request URL."
-              )
-            )
-          }
-          return .run { @MainActor _ in
-            NSWorkspace.shared.open(url)
-          }
-
-        case .copyFailingJobURL:
-          guard let failingCheckDetailsURL, !failingCheckDetailsURL.isEmpty else {
-            return .send(
-              .presentAlert(
-                title: "Failing check not found",
-                message: "Supacode could not find a failing check URL."
-              )
-            )
-          }
-          return .run { send in
-            await MainActor.run {
-              NSPasteboard.general.clearContents()
-              NSPasteboard.general.setString(failingCheckDetailsURL, forType: .string)
-            }
-            await send(.showToast(.success("Failing job URL copied")))
-          }
-
-        case .openFailingCheckDetails:
-          guard let failingCheckDetailsURL, let url = URL(string: failingCheckDetailsURL) else {
-            return .send(
-              .presentAlert(
-                title: "Failing check not found",
-                message: "Supacode could not find a failing check with details."
-              )
-            )
-          }
-          return .run { @MainActor _ in
-            NSWorkspace.shared.open(url)
-          }
+        // Clear a selected "can't reach" row once the remote resolves.
+        state.dropStaleFailedRepositorySelection()
+        // A placeholder to resolved transition changes the worktree roster, so
+        // tell downstream consumers (terminal prune, settings summaries); without
+        // this a restored remote surface stays pruned until the next full reload.
+        return didChange ? .send(.delegate(.repositoriesChanged(state.repositories))) : .none
 
-        case .markReadyForReview:
-          let githubCLI = githubCLI
-          let gitClient = gitClient
-          let githubIntegration = githubIntegration
-          return .run { send in
-            guard await githubIntegration.isAvailable() else {
-              await send(
-                .presentAlert(
-                  title: "GitHub integration unavailable",
-                  message: "Enable GitHub integration to mark a pull request as ready."
-                )
-              )
-              return
-            }
-            let remote = await resolveRemoteInfo(
-              repositoryRootURL: repoRoot,
-              githubCLI: githubCLI,
-              gitClient: gitClient
-            )
-            await send(.showToast(.inProgress("Marking PR ready…")))
+      case .openRepositories(let urls):
+        analyticsClient.capture("repository_added", ["count": urls.count])
+        state.alert = nil
+        return .run { send in
+          let loadedPaths = await repositoryPersistence.loadRoots()
+          let existingRootPaths = RepositoryPathNormalizer.normalize(loadedPaths)
+          var resolvedRoots: [URL] = []
+          var invalidRoots: [String] = []
+          for url in urls {
             do {
-              try await githubCLI.markPullRequestReady(worktreeRoot, remote, pullRequest.number)
-              await send(.showToast(.success("Pull request marked ready")))
-              await send(.delayedPullRequestRefresh(worktreeID))
+              let root = try await gitClient.repoRoot(url)
+              resolvedRoots.append(root)
             } catch {
-              await send(.dismissToast)
-              await send(
-                .presentAlert(
-                  title: "Failed to mark pull request ready",
-                  message: error.localizedDescription
-                )
+              // `gitClient.repoRoot` throws for non-git paths, but
+              // also for transient `wt` / subprocess failures. To
+              // avoid silently reclassifying a git repo as a folder
+              // on transient errors, double-check via the injected
+              // `gitClient.isGitRepository`: if the path actually
+              // has `.git`, surface the original error as an invalid
+              // root. Non-git readable directories are accepted as
+              // folder-kind repositories.
+              let standardized = url.standardizedFileURL
+              var isDirectory: ObjCBool = false
+              let exists = FileManager.default.fileExists(
+                atPath: standardized.path(percentEncoded: false),
+                isDirectory: &isDirectory
               )
+              if exists, isDirectory.boolValue,
+                await !gitClient.isGitRepository(standardized)
+              {
+                resolvedRoots.append(standardized)
+              } else {
+                invalidRoots.append(url.path(percentEncoded: false))
+              }
             }
           }
-
-        case .merge:
-          let githubCLI = githubCLI
-          let gitClient = gitClient
-          let githubIntegration = githubIntegration
-          return .run { send in
-            guard await githubIntegration.isAvailable() else {
-              await send(
-                .presentAlert(
-                  title: "GitHub integration unavailable",
-                  message: "Enable GitHub integration to merge a pull request."
-                )
-              )
-              return
-            }
-            @Shared(.repositorySettings(repoRoot)) var repositorySettings
-            @Shared(.settingsFile) var settingsFile
-            let strategy =
-              repositorySettings.pullRequestMergeStrategy ?? settingsFile.global.pullRequestMergeStrategy
-            let remote = await resolveRemoteInfo(
-              repositoryRootURL: repoRoot,
-              githubCLI: githubCLI,
-              gitClient: gitClient
+          let resolvedRootPaths = RepositoryPathNormalizer.normalize(
+            resolvedRoots.map { $0.path(percentEncoded: false) }
+          )
+          let mergedPaths = RepositoryPathNormalizer.normalize(existingRootPaths + resolvedRootPaths)
+          let mergedRoots = mergedPaths.map { URL(fileURLWithPath: $0) }
+          await repositoryPersistence.saveRoots(mergedPaths)
+          let (repositories, failures) = await loadRepositoriesData(mergedRoots)
+          await send(
+            .openRepositoriesFinished(
+              repositories,
+              failures: failures,
+              invalidRoots: invalidRoots,
+              roots: mergedRoots
             )
-            await send(.showToast(.inProgress("Merging pull request…")))
-            do {
-              try await githubCLI.mergePullRequest(worktreeRoot, remote, pullRequest.number, strategy)
-              await send(.showToast(.success("Pull request merged")))
-              await send(.worktreeInfoEvent(pullRequestRefresh))
-              await send(.delayedPullRequestRefresh(worktreeID))
-            } catch {
-              await send(.dismissToast)
-              await send(
-                .presentAlert(
-                  title: "Failed to merge pull request",
-                  message: error.localizedDescription
-                )
-              )
-            }
-          }
+          )
+        }
+        .cancellable(id: CancelID.load, cancelInFlight: true)
 
-        case .close:
-          let githubCLI = githubCLI
-          let gitClient = gitClient
-          let githubIntegration = githubIntegration
-          return .run { send in
-            guard await githubIntegration.isAvailable() else {
-              await send(
-                .presentAlert(
-                  title: "GitHub integration unavailable",
-                  message: "Enable GitHub integration to close a pull request."
-                )
-              )
-              return
-            }
-            let remote = await resolveRemoteInfo(
-              repositoryRootURL: repoRoot,
-              githubCLI: githubCLI,
-              gitClient: gitClient
-            )
-            await send(.showToast(.inProgress("Closing pull request…")))
-            do {
-              try await githubCLI.closePullRequest(worktreeRoot, remote, pullRequest.number)
-              await send(.showToast(.success("Pull request closed")))
-              await send(.worktreeInfoEvent(pullRequestRefresh))
-              await send(.delayedPullRequestRefresh(worktreeID))
-            } catch {
-              await send(.dismissToast)
-              await send(
-                .presentAlert(
-                  title: "Failed to close pull request",
-                  message: error.localizedDescription
-                )
-              )
-            }
+      case .openRepositoriesFinished(let repositories, let failures, let invalidRoots, let roots):
+        state.isRefreshingWorktrees = false
+        let previousSelection = state.selectedWorktreeID
+        let previousSelectedWorktree = state.worktree(for: previousSelection)
+        let mergedRemote = Self.mergePersistedRemoteRepositories(into: repositories, existingState: state)
+        _ = applyRepositories(
+          mergedRemote.repositories,
+          roots: roots,
+          shouldPruneArchivedWorktreeIDs: failures.isEmpty && mergedRemote.resolvingIDs.isEmpty,
+          state: &state,
+          animated: false
+        )
+        state.repositoryRoots = roots
+        state.isInitialLoadComplete = true
+        state.resolvingRemoteRepositoryIDs = mergedRemote.resolvingIDs
+        state.loadFailuresByID = Dictionary(
+          uniqueKeysWithValues: failures.map { ($0.rootID, $0.message) }
+        )
+        state.dropStaleFailedRepositorySelection()
+        if !invalidRoots.isEmpty {
+          let message = invalidRoots.map { "Supacode couldn't read \($0)." }.joined(separator: "\n")
+          state.alert = messageAlert(
+            title: "Some items couldn't be opened",
+            message: message
+          )
+        }
+        let selectedWorktree = state.worktree(for: state.selectedWorktreeID)
+        let selectionChanged = state.hasSelectionChanged(
+          previousSelectionID: previousSelection,
+          previousSelectedWorktree: previousSelectedWorktree,
+          selectedWorktreeID: state.selectedWorktreeID,
+          selectedWorktree: selectedWorktree,
+        )
+        var allEffects: [Effect<Action>] = [
+          .send(.delegate(.repositoriesChanged(state.repositories)))
+        ]
+        if selectionChanged {
+          allEffects.append(.send(.delegate(.selectedWorktreeChanged(selectedWorktree))))
+        }
+        // See `.repositoriesLoaded` above for why no per-slice save
+        // effects run here; sidebar mutations already flushed.
+        if state.autoDeleteArchivedWorktreesAfterDays != nil {
+          allEffects.append(.send(.autoDeleteExpiredArchivedWorktrees))
+        }
+        // Adding a local repo resolves only new placeholders; reload refreshes resolved remotes.
+        if !mergedRemote.resolvingIDs.isEmpty {
+          allEffects.append(.send(.resolveRemoteRepositories))
+        }
+        return .merge(allEffects)
+
+      case .selectionChanged(let selections, let focusTerminal):
+        return state.reduceSelectionChangedEffect(
+          selections: selections,
+          focusTerminal: focusTerminal,
+        )
+
+      case .repositoryExpansionChanged(let repositoryID, let isExpanded):
+        state.$sidebar.withLock { sidebar in
+          // Writing the explicit bit (true / false) instead of
+          // adding/removing from a set lets future default-flip
+          // logic distinguish "user expanded" from "never touched".
+          sidebar.sections[repositoryID, default: .init()].collapsed = !isExpanded
+        }
+        return .none
+
+      case .branchNestExpansionChanged(let repositoryID, let bucketID, let prefix, let isExpanded):
+        // Only `.pinned` / `.unpinned` render nested rows; `.archived` has no
+        // chevron and would just bloat `sidebar.json` with dead entries. Also
+        // refuse to materialize a phantom section for an unknown repo: the
+        // chevron is unreachable without an existing section, so anything
+        // hitting this path with a missing repository is stale UI / deeplink
+        // noise rather than a legitimate intent.
+        guard bucketID != .archived, state.sidebar.sections[repositoryID] != nil else { return .none }
+        state.$sidebar.withLock { sidebar in
+          guard var section = sidebar.sections[repositoryID] else { return }
+          var bucket = section.buckets[bucketID] ?? .init()
+          if isExpanded {
+            bucket.collapsedBranchPrefixes.remove(prefix)
+          } else {
+            bucket.collapsedBranchPrefixes.insert(prefix)
           }
+          section.buckets[bucketID] = bucket
+          sidebar.sections[repositoryID] = section
+        }
+        return .none
 
-        case .copyCiFailureLogs:
-          let githubCLI = githubCLI
-          let githubIntegration = githubIntegration
-          return .run { send in
-            guard await githubIntegration.isAvailable() else {
-              await send(
-                .presentAlert(
-                  title: "GitHub integration unavailable",
-                  message: "Enable GitHub integration to copy CI failure logs."
-                )
-              )
-              return
-            }
-            guard !branchName.isEmpty else {
-              await send(
-                .presentAlert(
-                  title: "Branch name unavailable",
-                  message: "Supacode could not determine the pull request branch."
-                )
-              )
-              return
-            }
-            await send(.showToast(.inProgress("Fetching CI logs…")))
-            do {
-              guard let run = try await githubCLI.latestRun(worktreeRoot, branchName) else {
-                await send(.dismissToast)
-                await send(
-                  .presentAlert(
-                    title: "No workflow runs found",
-                    message: "Supacode could not find any workflow runs for this branch."
-                  )
-                )
-                return
-              }
-              guard run.conclusion?.lowercased() == "failure" else {
-                await send(.dismissToast)
-                await send(
-                  .presentAlert(
-                    title: "No failing workflow run",
-                    message: "Supacode could not find a failing workflow run to copy logs from."
-                  )
-                )
-                return
-              }
-              let failedLogs = try await githubCLI.failedRunLogs(worktreeRoot, run.databaseId)
-              let logs =
-                if failedLogs.isEmpty {
-                  try await githubCLI.runLogs(worktreeRoot, run.databaseId)
-                } else {
-                  failedLogs
-                }
-              guard !logs.isEmpty else {
-                await send(.dismissToast)
-                await send(
-                  .presentAlert(
-                    title: "No CI logs available",
-                    message: "The workflow run failed but produced no logs."
-                  )
-                )
-                return
-              }
-              await MainActor.run {
-                NSPasteboard.general.clearContents()
-                NSPasteboard.general.setString(logs, forType: .string)
-              }
-              await send(.showToast(.success("CI failure logs copied")))
-            } catch {
-              await send(.dismissToast)
-              await send(
-                .presentAlert(
-                  title: "Failed to copy CI failure logs",
-                  message: error.localizedDescription
-                )
-              )
-            }
+      case .selectArchivedWorktrees:
+        state.selection = .archivedWorktrees
+        state.sidebarSelectedWorktreeIDs = []
+        return .send(.delegate(.selectedWorktreeChanged(nil)))
+
+      case .setSidebarSelectedWorktreeIDs(let worktreeIDs):
+        let validWorktreeIDs = state.selectableWorktreeIDs
+        var nextWorktreeIDs = worktreeIDs.intersection(validWorktreeIDs)
+        if let selectedWorktreeID = state.selectedWorktreeID, validWorktreeIDs.contains(selectedWorktreeID) {
+          nextWorktreeIDs.insert(selectedWorktreeID)
+        }
+        state.sidebarSelectedWorktreeIDs = nextWorktreeIDs
+        return .none
+
+      case .selectWorktree(let worktreeID, let focusTerminal):
+        state.setSingleWorktreeSelection(worktreeID)
+        let selectedWorktree = state.worktree(for: worktreeID)
+        var effects: [Effect<Action>] = [
+          .send(.delegate(.selectedWorktreeChanged(selectedWorktree)))
+        ]
+        if focusTerminal, let worktreeID, state.sidebarItems[id: worktreeID] != nil {
+          effects.append(
+            .send(.sidebarItems(.element(id: worktreeID, action: .focusTerminalRequested)))
+          )
+        }
+        return .merge(effects)
+
+      case .selectWorktreeAtHotkeySlot(let index):
+        // Snapshot-driven menu items capture only the slot index, so the
+        // current `hotkeySlots` lookup happens here at action time. Out-of-range
+        // slots beep so the user gets feedback that the shortcut hit nothing.
+        let slots = state.sidebarStructure.hotkeySlots
+        guard slots.indices.contains(index) else {
+          return .run { _ in NSSound.beep() }
+        }
+        return .send(.selectWorktree(slots[index].id, focusTerminal: true))
+
+      case .selectNextWorktree:
+        guard let id = state.worktreeID(byOffset: 1) else {
+          return .run { _ in NSSound.beep() }
+        }
+        return .send(.selectWorktree(id, focusTerminal: true))
+
+      case .selectPreviousWorktree:
+        guard let id = state.worktreeID(byOffset: -1) else {
+          return .run { _ in NSSound.beep() }
+        }
+        return .send(.selectWorktree(id, focusTerminal: true))
+
+      case .worktreeHistoryBack:
+        return state.navigateWorktreeHistoryEffect(direction: .back)
+
+      case .worktreeHistoryForward:
+        return state.navigateWorktreeHistoryEffect(direction: .forward)
+
+      case .revealSelectedWorktreeInSidebar:
+        guard let worktreeID = state.selectedWorktreeID,
+          let repositoryID = state.repositoryID(containing: worktreeID)
+        else { return .none }
+        // Resolve outside the lock to keep the critical section short.
+        let branchName = state.sidebarItems[id: worktreeID]?.branchName
+        let containingBucket = state.sidebar.currentBucket(of: worktreeID, in: repositoryID)
+        state.$sidebar.withLock { sidebar in
+          sidebar.sections[repositoryID, default: .init()].collapsed = false
+          // Uncollapse any ancestor branch prefix so a reveal / deeplink to
+          // `feature/tools/api` doesn't leave the row hidden inside a
+          // collapsed `feature/tools` group header.
+          guard let branchName, let bucketID = containingBucket, bucketID != .archived else { return }
+          let ancestors = Set(SidebarBranchNesting.ancestorPrefixes(of: branchName))
+          guard !ancestors.isEmpty,
+            var bucket = sidebar.sections[repositoryID]?.buckets[bucketID]
+          else { return }
+          let next = bucket.collapsedBranchPrefixes.subtracting(ancestors)
+          guard next != bucket.collapsedBranchPrefixes else { return }
+          bucket.collapsedBranchPrefixes = next
+          sidebar.sections[repositoryID]?.buckets[bucketID] = bucket
+        }
+        state.nextPendingSidebarRevealID += 1
+        state.pendingSidebarReveal = .init(id: state.nextPendingSidebarRevealID, worktreeID: worktreeID)
+        return .none
+
+      case .revealHoistedWorktreeInSidebar(let worktreeID):
+        // The target lives in a highlight section, which is never collapsed,
+        // so no section / branch-prefix uncollapse is needed.
+        state.nextPendingSidebarRevealID += 1
+        state.pendingSidebarReveal = .init(id: state.nextPendingSidebarRevealID, worktreeID: worktreeID)
+        return .none
+
+      case .consumePendingSidebarReveal(let pendingSidebarRevealID):
+        guard state.pendingSidebarReveal?.id == pendingSidebarRevealID else { return .none }
+        state.pendingSidebarReveal = nil
+        return .none
+
+      case .createRandomWorktree:
+        guard let repository = state.repositoryForWorktreeCreation else {
+          let message: String
+          if state.repositories.isEmpty {
+            message = "Open a repository to create a worktree."
+          } else if state.selectedWorktreeID == nil && state.repositories.count > 1 {
+            message = "Select a worktree to choose which repository to use."
+          } else {
+            message = "Unable to resolve a repository for the new worktree."
           }
+          state.alert = messageAlert(title: "Unable to create worktree", message: message)
+          return .none
+        }
+        return .send(.createRandomWorktreeInRepository(repository.id))
 
-        case .rerunFailedJobs:
-          let githubCLI = githubCLI
-          let githubIntegration = githubIntegration
-          return .run { send in
-            guard await githubIntegration.isAvailable() else {
-              await send(
-                .presentAlert(
-                  title: "GitHub integration unavailable",
-                  message: "Enable GitHub integration to re-run failed jobs."
-                )
-              )
-              return
-            }
-            guard !branchName.isEmpty else {
-              await send(
-                .presentAlert(
-                  title: "Branch name unavailable",
-                  message: "Supacode could not determine the pull request branch."
-                )
-              )
-              return
-            }
-            await send(.showToast(.inProgress("Re-running failed jobs…")))
-            do {
-              guard let run = try await githubCLI.latestRun(worktreeRoot, branchName) else {
-                await send(.dismissToast)
-                await send(
-                  .presentAlert(
-                    title: "No workflow runs found",
-                    message: "Supacode could not find any workflow runs for this branch."
-                  )
-                )
-                return
-              }
-              guard run.conclusion?.lowercased() == "failure" else {
-                await send(.dismissToast)
-                await send(
-                  .presentAlert(
-                    title: "No failing workflow run",
-                    message: "Supacode could not find a failing workflow run to re-run."
-                  )
-                )
-                return
-              }
-              try await githubCLI.rerunFailedJobs(worktreeRoot, run.databaseId)
-              await send(.showToast(.success("Failed jobs re-run started")))
-              await send(.delayedPullRequestRefresh(worktreeID))
-            } catch {
-              await send(.dismissToast)
-              await send(
-                .presentAlert(
-                  title: "Failed to re-run failed jobs",
-                  message: error.localizedDescription
-                )
+      case .createRandomWorktreeInRepository(let repositoryID):
+        guard let repository = state.repositories[id: repositoryID] else {
+          state.alert = messageAlert(
+            title: "Unable to create worktree",
+            message: "Unable to resolve a repository for the new worktree."
+          )
+          return .none
+        }
+        // Worktree creation needs a git repository. Folder-kind entries
+        // surface the same menu / hotkey / deeplink path, so reject
+        // them up front with a clear alert instead of letting the
+        // request fall into `gitClient.createWorktreeStream` and fail
+        // with a raw subprocess error.
+        if !repository.isGitRepository {
+          state.alert = messageAlert(
+            title: "Unable to create worktree",
+            message: "Worktrees are only supported for git repositories."
+          )
+          return .none
+        }
+        if state.removingRepositoryIDs[repository.id] != nil {
+          state.alert = messageAlert(
+            title: "Unable to create worktree",
+            message: "This repository is being removed."
+          )
+          return .none
+        }
+        @Shared(.settingsFile) var settingsFile
+        if !settingsFile.global.promptForWorktreeCreation {
+          return .merge(
+            .cancel(id: CancelID.worktreePromptLoad),
+            .send(
+              .createWorktreeInRepository(
+                repositoryID: repository.id,
+                nameSource: .random,
+                baseRefSource: .repositorySetting,
+                fetchOrigin: settingsFile.global.fetchOriginBeforeWorktreeCreation
               )
-            }
+            )
+          )
+        }
+        @Shared(.repositorySettings(repository.rootURL, host: repository.host)) var repositorySettings
+        let selectedBaseRef = repositorySettings.worktreeBaseRef
+        // Remote repos load the prompt's branch lists over ssh (host-aware
+        // client); local uses the injected client. The dialog loads these in
+        // the background, so the ssh round-trips (multiplexed over the warm
+        // ControlMaster) don't block presentation.
+        let gitClient = gitClient(for: repository)
+        let rootURL = repository.rootURL
+        // Resolve the cheap quick-picks (auto ref + matching local
+        // branch) and present the prompt right away, then load the
+        // full local / remote branch lists in the background so the
+        // dialog never blocks on `git for-each-ref`.
+        return .run { send in
+          let automaticBaseRef = await gitClient.automaticWorktreeBaseRef(rootURL) ?? "HEAD"
+          guard !Task.isCancelled else {
+            return
+          }
+          let remoteNames = (try? await gitClient.remoteNames(rootURL)) ?? []
+          let defaultBranch = GitReferenceQueries.localBranchName(
+            fromRemoteRef: automaticBaseRef,
+            remoteNames: remoteNames
+          )
+          guard !Task.isCancelled else {
+            return
+          }
+          await send(
+            .promptedWorktreeCreationDataLoaded(
+              repositoryID: repositoryID,
+              automaticBaseRef: automaticBaseRef,
+              defaultBranch: defaultBranch,
+              remoteNames: remoteNames,
+              selectedBaseRef: selectedBaseRef
+            )
+          )
+          let inventory =
+            (try? await gitClient.branchInventory(rootURL, remoteNames)) ?? GitBranchInventory()
+          guard !Task.isCancelled else {
+            return
           }
+          await send(
+            .promptedWorktreeBranchesLoaded(repositoryID: repositoryID, inventory: inventory)
+          )
         }
+        .cancellable(id: CancelID.worktreePromptLoad, cancelInFlight: true)
 
-      case .setGithubIntegrationEnabled(let isEnabled):
-        if isEnabled {
-          state.githubIntegrationAvailability = .unknown
-          state.pendingPullRequestRefreshByRepositoryID.removeAll()
-          state.queuedPullRequestRefreshByRepositoryID.removeAll()
-          state.inFlightPullRequestRefreshRepositoryIDs.removeAll()
-          state.inFlightPullRequestBranchSnapshotsByRepositoryID.removeAll()
-          return .merge(
-            .cancel(id: CancelID.githubIntegrationRecovery),
-            .send(.refreshGithubIntegrationAvailability)
+      case .promptedWorktreeCreationDataLoaded(
+        let repositoryID,
+        let automaticBaseRef,
+        let defaultBranch,
+        let remoteNames,
+        let selectedBaseRef
+      ):
+        guard let repository = state.repositories[id: repositoryID] else {
+          return .none
+        }
+        @Shared(.settingsFile) var promptSettingsFile
+        @Shared(.repositorySettings(repository.rootURL, host: repository.host)) var promptRepositorySettings
+        let defaultWorktreeBaseDirectory = SupacodePaths.worktreeBaseDirectory(
+          for: repository.rootURL,
+          globalDefaultPath: promptSettingsFile.global.defaultWorktreeBaseDirectoryPath,
+          repositoryOverridePath: promptRepositorySettings.worktreeBaseDirectoryPath
+        )
+        .path(percentEncoded: false)
+        state.worktreeCreationPrompt = WorktreeCreationPromptFeature.State(
+          repositoryID: repository.id,
+          repositoryRootURL: repository.rootURL,
+          repositoryName: repository.name,
+          automaticBaseRef: automaticBaseRef,
+          defaultBranch: defaultBranch,
+          remoteNames: remoteNames,
+          branchMenu: nil,
+          branchName: "",
+          selectedBaseRef: selectedBaseRef,
+          fetchOrigin: promptSettingsFile.global.fetchOriginBeforeWorktreeCreation,
+          defaultWorktreeBaseDirectory: defaultWorktreeBaseDirectory,
+          validationMessage: nil
+        )
+        return .none
+
+      case .promptedWorktreeBranchesLoaded(let repositoryID, let inventory):
+        guard var prompt = state.worktreeCreationPrompt, prompt.repositoryID == repositoryID else {
+          return .none
+        }
+        // Drop the default-branch quick pick if no local branch of that name
+        // actually exists (e.g. a fresh clone with only `origin/main`), so it
+        // can't submit a missing ref. Guard on a non-empty inventory so a
+        // failed load doesn't hide a valid quick pick.
+        if !inventory.isEmpty, let defaultBranch = prompt.defaultBranch,
+          !inventory.localBranches.contains(defaultBranch)
+        {
+          prompt.defaultBranch = nil
+        }
+        prompt.branchMenu = BaseRefBranchMenu(
+          inventory: inventory,
+          hoistedLocalBranch: prompt.defaultBranch
+        )
+        // A persisted base ref (from repository settings) can point at a branch
+        // that no longer exists. Fall back to Auto so the prompt doesn't show an
+        // invisible selection and submit a dead ref to `git worktree add`. Only
+        // reconcile against a non-empty inventory so a failed load doesn't wipe a
+        // still-valid ref.
+        if let selectedBaseRef = prompt.selectedBaseRef, !inventory.isEmpty,
+          selectedBaseRef != prompt.automaticBaseRef,
+          !inventory.contains(ref: selectedBaseRef)
+        {
+          prompt.selectedBaseRef = nil
+        }
+        state.worktreeCreationPrompt = prompt
+        return .none
+
+      case .worktreeCreationPrompt(.presented(.delegate(.cancel))):
+        if let repositoryID = state.worktreeCreationPrompt?.repositoryID {
+          state.dropPendingCustomization(repositoryID: repositoryID)
+        }
+        state.worktreeCreationPrompt = nil
+        return .merge(
+          .cancel(id: CancelID.worktreePromptLoad),
+          .cancel(id: CancelID.worktreePromptValidation)
+        )
+
+      case .worktreeCreationPrompt(
+        .presented(
+          .delegate(
+            .submit(
+              let repositoryID,
+              let branchName,
+              let baseRef,
+              let fetchOrigin,
+              let placement,
+              let title,
+              let color
+            )
           )
+        )
+      ):
+        // Overwrite (or clear) any stale entry for the same (repo, branch) so a user who typed a
+        // title, hit a validation error, blanked the field, and re-submitted doesn't keep the
+        // dropped value alive.
+        if title != nil || color != nil {
+          state.pendingCreationCustomizations[repositoryID, default: [:]][branchName] =
+            PendingWorktree.Customization(title: title, color: color)
+        } else {
+          state.dropPendingCustomization(repositoryID: repositoryID, branchName: branchName)
         }
-        state.githubIntegrationAvailability = .disabled
-        state.pendingPullRequestRefreshByRepositoryID.removeAll()
-        state.queuedPullRequestRefreshByRepositoryID.removeAll()
-        state.inFlightPullRequestRefreshRepositoryIDs.removeAll()
-        state.inFlightPullRequestBranchSnapshotsByRepositoryID.removeAll()
-        let worktreeIDs = state.sidebarItems.compactMap { $0.pullRequest != nil ? $0.id : nil }
-        var clearEffects: [Effect<Action>] = []
-        for worktreeID in worktreeIDs {
-          clearEffects.append(
-            state.updateWorktreePullRequestEffect(
-              worktreeID: worktreeID,
-              pullRequest: nil,
+        return .send(
+          .startPromptedWorktreeCreation(
+            repositoryID: repositoryID,
+            branchName: branchName,
+            baseRef: baseRef,
+            fetchOrigin: fetchOrigin,
+            placement: placement
+          )
+        )
+
+      case .startPromptedWorktreeCreation(
+        let repositoryID,
+        let branchName,
+        let baseRef,
+        let fetchOrigin,
+        let placement
+      ):
+        guard let repository = state.repositories[id: repositoryID] else {
+          state.worktreeCreationPrompt = nil
+          state.alert = messageAlert(
+            title: "Unable to create worktree",
+            message: "Unable to resolve a repository for the new worktree."
+          )
+          // Drain the just-stashed customization so a later retry with the same name doesn't pick
+          // up the orphaned entry.
+          state.dropPendingCustomization(repositoryID: repositoryID, branchName: branchName)
+          return .none
+        }
+        state.worktreeCreationPrompt?.validationMessage = nil
+        state.worktreeCreationPrompt?.isValidating = true
+        let normalizedBranchName = branchName.lowercased()
+        if repository.worktrees.contains(where: { $0.name.lowercased() == normalizedBranchName }) {
+          state.worktreeCreationPrompt?.isValidating = false
+          state.worktreeCreationPrompt?.validationMessage = "Branch name already exists."
+          // Synchronous duplicate rejection. Drop the stashed customization so it can't be
+          // re-applied if the user retries with a different branch name.
+          state.dropPendingCustomization(repositoryID: repositoryID, branchName: branchName)
+          return .none
+        }
+        let gitClient = gitClient(for: repository)
+        let rootURL = repository.rootURL
+        return .run { send in
+          let localBranchNames = (try? await gitClient.localBranchNames(rootURL)) ?? []
+          let duplicateMessage =
+            localBranchNames.contains(normalizedBranchName)
+            ? "Branch name already exists."
+            : nil
+          await send(
+            .promptedWorktreeCreationChecked(
+              repositoryID: repositoryID,
+              branchName: branchName,
+              baseRef: baseRef,
+              fetchOrigin: fetchOrigin,
+              placement: placement,
+              duplicateMessage: duplicateMessage
             )
           )
         }
+        .cancellable(id: CancelID.worktreePromptValidation, cancelInFlight: true)
+
+      case .promptedWorktreeCreationChecked(
+        let repositoryID,
+        let branchName,
+        let baseRef,
+        let fetchOrigin,
+        let placement,
+        let duplicateMessage
+      ):
+        guard let prompt = state.worktreeCreationPrompt, prompt.repositoryID == repositoryID else {
+          return .none
+        }
+        state.worktreeCreationPrompt?.isValidating = false
+        if let duplicateMessage {
+          state.worktreeCreationPrompt?.validationMessage = duplicateMessage
+          // Async-validation duplicate rejection. Same drop reasoning as the sync path.
+          state.dropPendingCustomization(repositoryID: repositoryID, branchName: branchName)
+          return .none
+        }
+        state.worktreeCreationPrompt = nil
+        return .send(
+          .createWorktreeInRepository(
+            repositoryID: repositoryID,
+            nameSource: .explicit(branchName),
+            baseRefSource: .explicit(baseRef),
+            fetchOrigin: fetchOrigin,
+            placement: placement
+          )
+        )
+
+      case .createWorktreeInRepository:
+        // Real handling lives in `worktreeCreateInRepoReducer` (combined below) to keep
+        // `body` under the type-checker's complexity limit.
+        return .none
+
+      case .worktreeCreationPrompt(.dismiss):
+        // Don't drain `pendingCreationCustomizations` here: `.dismiss` also fires on the success
+        // path (when the reducer nils the prompt after validation passes) and the in-flight
+        // creation still needs the customization. Only `.cancel` is an explicit user back-out.
+        state.worktreeCreationPrompt = nil
         return .merge(
-          clearEffects + [
-            .cancel(id: CancelID.githubIntegrationAvailability),
-            .cancel(id: CancelID.githubIntegrationRecovery),
-          ]
+          .cancel(id: CancelID.worktreePromptLoad),
+          .cancel(id: CancelID.worktreePromptValidation)
         )
 
-      case .setMergedWorktreeAction(let action):
-        state.mergedWorktreeAction = action
+      case .worktreeCreationPrompt:
         return .none
 
-      case .setAutoDeleteArchivedWorktreesAfterDays(let days):
-        state.autoDeleteArchivedWorktreesAfterDays = days
-        guard days != nil else { return .none }
-        return .send(.autoDeleteExpiredArchivedWorktrees)
+      case .pendingWorktreeProgressUpdated(let id, let progress):
+        guard state.updatePendingWorktreeProgress(id, progress: progress) else { return .none }
+        Self.syncSidebar(&state)
+        return .none
 
-      case .autoDeleteExpiredArchivedWorktrees:
-        guard let period = state.autoDeleteArchivedWorktreesAfterDays else { return .none }
-        let cutoff = now.addingTimeInterval(-Double(period.rawValue) * secondsPerDay)
-        var targets: [(Worktree.ID, Repository.ID)] = []
-        // Folder-synthetic archived entries can't be produced by
-        // any current user path (context-menu / shortcut / deeplink
-        // all reject folder archives). If one leaks into persisted
-        // state — a bug in a future archive path, a migration
-        // regression, or hand-edited sidebar.json — we both flag
-        // the invariant breach AND purge the stray entry from
-        // `sidebar.archivedWorktrees`, so the next reload doesn't
-        // re-fire `reportIssue` forever.
-        var strayFolderArchives: [(Worktree.ID, Repository.ID)] = []
-        for archived in state.sidebar.archivedWorktrees
-        where Repository.isFolderWorktreeID(archived.worktreeID) {
-          strayFolderArchives.append((archived.worktreeID, archived.repositoryID))
+      case .createRandomWorktreeSucceeded(
+        let worktree,
+        let repositoryID,
+        let pendingID
+      ):
+        analyticsClient.capture("worktree_created", nil)
+        // Capture the pending row's customization BEFORE the pending drops,
+        // then forward it to the bucketed Item so reconcile renders the
+        // user-typed title / color from the very first paint after the
+        // pending row swaps to the real worktree.
+        let carriedCustomization = state.pendingWorktrees.first(where: { $0.id == pendingID })?.customization
+        state.removePendingWorktree(pendingID)
+        if state.selection == .worktree(pendingID) {
+          // History was already recorded when the pending row was
+          // selected (real → pending). Treat the swap into the real
+          // worktree id as a continuation of that same navigation
+          // so the back stack ends with the real id, not the
+          // throwaway pending id.
+          state.setSingleWorktreeSelection(worktree.id, recordHistory: false)
         }
-        if !strayFolderArchives.isEmpty {
-          for (worktreeID, _) in strayFolderArchives {
-            reportIssue(
-              """
-              Auto-delete encountered folder-synthetic archived worktree \(worktreeID) — \
-              folders are not archivable. Purging the stray entry.
-              """
-            )
-          }
+        state.insertWorktree(worktree, repositoryID: repositoryID)
+        if let carriedCustomization, carriedCustomization.title != nil || carriedCustomization.color != nil {
+          // Seed customization into whatever bucket currently holds the row (falls back to
+          // `.unpinned` for a brand-new worktree). The bucket probe avoids manufacturing a
+          // phantom double-bucket entry against a persisted `.pinned` Item.
           state.$sidebar.withLock { sidebar in
-            for (worktreeID, repositoryID) in strayFolderArchives {
-              sidebar.remove(worktree: worktreeID, in: repositoryID, from: .archived)
-            }
-          }
-        }
-        for archived in state.sidebar.archivedWorktrees {
-          let worktreeID = archived.worktreeID
-          guard archived.archivedAt <= cutoff else { continue }
-          if Repository.isFolderWorktreeID(worktreeID) {
-            // Already purged above — defensive skip.
-            continue
-          }
-          let autoDeleteLifecycle = state.sidebarItems[id: worktreeID]?.lifecycle ?? .idle
-          guard autoDeleteLifecycle == .idle else { continue }
-          guard let repository = state.repositories.first(where: { $0.worktrees[id: worktreeID] != nil }),
-            let worktree = repository.worktrees[id: worktreeID]
-          else {
-            repositoriesLogger.debug(
-              "Auto-delete skipping expired worktree \(worktreeID): not found in loaded repositories."
+            sidebar.mergeCustomization(
+              title: carriedCustomization.title,
+              color: carriedCustomization.color,
+              worktree: worktree.id,
+              in: repositoryID
             )
-            continue
-          }
-          guard !state.isMainWorktree(worktree) else {
-            repositoriesLogger.debug(
-              "Auto-delete skipping expired worktree \(worktreeID): main worktree cannot be deleted."
-            )
-            continue
           }
-          targets.append((worktreeID, repository.id))
         }
-        guard !targets.isEmpty else { return .none }
-        repositoriesLogger.info("Auto-deleting \(targets.count) expired archived worktree(s).")
+        Self.syncSidebar(&state)
+        // Synchronous so the detail body never observes a brief `.idle` window
+        // between the real-worktree swap and the setup-script path.
+        state.sidebarItems[id: worktree.id]?.lifecycle = .pending
         return .merge(
-          targets.map { worktreeID, repositoryID in
-            .send(.deleteSidebarItemConfirmed(worktreeID, repositoryID))
-          }
+          .send(.sidebarItems(.element(id: worktree.id, action: .focusTerminalRequested))),
+          .send(.reloadRepositories(animated: false)),
+          .send(.delegate(.repositoriesChanged(state.repositories))),
+          .send(.delegate(.selectedWorktreeChanged(state.worktree(for: state.selectedWorktreeID)))),
+          .send(.delegate(.worktreeCreated(worktree)))
         )
 
-      case .setMoveNotifiedWorktreeToTop(let isEnabled):
-        state.moveNotifiedWorktreeToTop = isEnabled
+      case .createRandomWorktreeFailed(
+        let title,
+        let message,
+        let pendingID,
+        let previousSelection,
+        let repositoryID,
+        let name,
+        let baseDirectory
+      ):
+        let previousSelectedWorktree = state.worktree(for: previousSelection)
+        state.removePendingWorktree(pendingID)
+        state.restoreSelection(previousSelection, pendingID: pendingID)
+        let cleanup = state.cleanupFailedWorktree(
+          repositoryID: repositoryID,
+          name: name,
+          baseDirectory: baseDirectory,
+        )
+        state.alert = messageAlert(title: title, message: message)
+        let selectedWorktree = state.worktree(for: state.selectedWorktreeID)
+        let selectionChanged = state.hasSelectionChanged(
+          previousSelectionID: previousSelection,
+          previousSelectedWorktree: previousSelectedWorktree,
+          selectedWorktreeID: state.selectedWorktreeID,
+          selectedWorktree: selectedWorktree,
+        )
+        var effects: [Effect<Action>] = []
+        if cleanup.didRemoveWorktree {
+          effects.append(.send(.delegate(.repositoriesChanged(state.repositories))))
+        }
+        if selectionChanged {
+          effects.append(.send(.delegate(.selectedWorktreeChanged(selectedWorktree))))
+        }
+        // Sidebar-state mutations in `cleanupWorktreeState` already
+        // went through `$sidebar.withLock`, so no per-slice save
+        // effects are needed here.
+        if let cleanupWorktree = cleanup.worktree {
+          let cleanupClient = gitClient(for: cleanupWorktree)
+          effects.append(
+            .run { send in
+              _ = try? await cleanupClient.removeWorktree(cleanupWorktree, true)
+              await send(.reloadRepositories(animated: true))
+            }
+          )
+        }
+        return .merge(effects)
+
+      case .consumeSetupScript(let id):
+        guard state.sidebarItems[id: id]?.lifecycle == .pending else { return .none }
+        return .send(.sidebarItems(.element(id: id, action: .lifecycleChanged(.idle))))
+
+      case .consumeTerminalFocus(let id):
+        return .send(.sidebarItems(.element(id: id, action: .focusTerminalConsumed)))
+
+      case .requestArchiveWorktree, .requestArchiveWorktrees, .scriptCompleted, .archiveWorktreeConfirmed,
+        .archiveScriptCompleted, .archiveWorktreeApply, .unarchiveWorktree, .requestDeleteSidebarItems:
+        // Real handling lives in `worktreeRemovalReducer` (combined below) so `body` stays under the
+        // type-checker's complexity limit; the `.alert(.presented(.confirm…))` arms there are matched
+        // here by the trailing `.alert` catch-all returning `.none`.
+        return .none
+
+      case .deleteSidebarItemConfirmed, .deleteScriptCompleted, .deleteWorktreeApply, .worktreeDeleted,
+        .repositoriesMoved, .pinnedWorktreesMoved, .unpinnedWorktreesMoved, .deleteWorktreeFailed,
+        .requestDeleteRepository, .requestRemoveFailedRepository, .removeFailedRepository,
+        .repositoryRemovalCompleted, .repositoriesRemoved:
+        // Real handling lives in `worktreeRemovalReducer` (combined below) so `body` stays under
+        // the type-checker's complexity limit. The two `.alert(.presented(.confirm…))` arms in that
+        // reducer are matched here by the trailing `.alert` catch-all returning `.none`.
+        return .none
+
+      case .pinWorktree, .unpinWorktree, .presentAlert, .showToast, .dismissToast, .delayedPullRequestRefresh,
+        .worktreeNotificationReceived, .worktreeInfoEvent:
+        // Real handling lives in `worktreeNotificationReducer` (combined below) to keep `body`
+        // under the type-checker's complexity limit.
+        return .none
+
+      case .refreshGithubIntegrationAvailability, .githubIntegrationAvailabilityUpdated,
+        .repositoryPullRequestRefreshCompleted, .worktreeBranchNameLoaded, .worktreeLineChangesLoaded,
+        .repositoryPullRequestsLoaded, .pullRequestAction, .setGithubIntegrationEnabled, .setMergedWorktreeAction,
+        .setAutoDeleteArchivedWorktreesAfterDays, .autoDeleteExpiredArchivedWorktrees, .setMoveNotifiedWorktreeToTop:
+        // Real handling lives in `githubIntegrationReducer` (combined below) to keep `body`
+        // under the type-checker's complexity limit.
         return .none
 
       case .openRepositorySettings(let repositoryID):
@@ -3406,6 +3821,12 @@ struct RepositoriesFeature {
       case .repositoryCustomization:
         return .none
 
+      case .requestCustomizeWorktree,
+        .worktreeCustomization:
+        // Handled by `WorktreeCustomizationParentReducer` below; main switch is at type-checker
+        // capacity, so the customization arms are split out into a dedicated reducer.
+        return .none
+
       case .requestRenameBranch(let worktreeID, let repositoryID):
         guard let repository = state.repositories[id: repositoryID],
           repository.isGitRepository,
@@ -3423,6 +3844,7 @@ struct RepositoriesFeature {
           worktreeID: worktreeID,
           repositoryID: repositoryID,
           repositoryRootURL: repository.rootURL,
+          host: worktree.host,
           currentName: worktree.name
         )
         return .none
@@ -3485,6 +3907,10 @@ struct RepositoriesFeature {
         return .none
       }
     }
+    // These presentation `ifLet`s hang off the main `Reduce` so each child runs before the
+    // parent handles its `.delegate` / `.dismiss` and nils the state. The `.worktreeCustomization`
+    // ifLet sits on `worktreeCustomizationReducer` below (same child-first ordering, but kept off
+    // the main `Reduce` so the `body` expression stays within the type-checker's complexity limit).
     .forEach(\.sidebarItems, action: \.sidebarItems) {
       SidebarItemFeature()
     }
@@ -3497,6 +3923,23 @@ struct RepositoriesFeature {
     .ifLet(\.$renameBranchPrompt, action: \.renameBranchPrompt) {
       RenameBranchFeature()
     }
+    Self.worktreeCustomizationReducer
+      .ifLet(\.$worktreeCustomization, action: \.worktreeCustomization) {
+        WorktreeCustomizationFeature()
+      }
+    // Dedicated reducer + chained `ifLet` so the form's child reducer runs
+    // before the delegate handler nils the presented state (mirrors the
+    // worktree-customization pattern, and keeps `body` under the type-checker
+    // complexity limit).
+    Self.remoteConnectionFormReducer
+      .ifLet(\.$remoteConnectionForm, action: \.remoteConnectionForm) {
+        RemoteConnectionFormFeature()
+      }
+    worktreeArchiveReducer
+    worktreeRemovalReducer
+    worktreeCreateInRepoReducer
+    worktreeNotificationReducer
+    githubIntegrationReducer
     // Targeted post-reduce hook: only the actions that demonstrably touch
     // structure inputs trigger a recompute. The Equatable diff inside the
     // helper suppresses no-op rebuilds at the SwiftUI layer. Gated on
@@ -3577,6 +4020,85 @@ struct RepositoriesFeature {
     .cancellable(id: CancelID.load, cancelInFlight: true)
   }
 
+  private static func mergePersistedRemoteRepositories(
+    into repositories: [Repository],
+    existingState state: State
+  ) -> RemoteRepositoryMergeResult {
+    // Parse persisted remote ids once into (repoID, host, path), dropping any
+    // that don't parse as a remote authority.
+    let remoteRoots: [ParsedRemoteRoot] =
+      persistedRemoteRepositoryRoots().compactMap { root in
+        guard let (host, remotePath) = parseRemoteRoot(root) else {
+          repositoriesLogger.warning("Skipping unparseable persisted remote id: \(root).")
+          return nil
+        }
+        return ParsedRemoteRoot(
+          repoID: remoteRepositoryID(host: host, remotePath: remotePath), host: host, remotePath: remotePath)
+      }
+    var persistedRemoteIDs: Set<Repository.ID> = []
+    for root in remoteRoots {
+      persistedRemoteIDs.insert(root.repoID)
+    }
+
+    var mergedRepositories: [Repository] = []
+    var indexesByID: [Repository.ID: Int] = [:]
+    for repository in repositories {
+      if repository.host != nil, !persistedRemoteIDs.contains(repository.id) {
+        continue
+      }
+      guard indexesByID[repository.id] == nil else { continue }
+      indexesByID[repository.id] = mergedRepositories.count
+      mergedRepositories.append(repository)
+    }
+
+    guard !remoteRoots.isEmpty else {
+      return RemoteRepositoryMergeResult(
+        repositories: mergedRepositories,
+        resolvingIDs: []
+      )
+    }
+
+    var resolvingIDs: Set<Repository.ID> = []
+    var seenRemoteIDs: Set<Repository.ID> = []
+    for root in remoteRoots {
+      let repoID = root.repoID
+      // Two ids can collide (e.g. an edit made them match); keep the first so
+      // the IdentifiedArray below can't trap.
+      guard seenRemoteIDs.insert(repoID).inserted else { continue }
+      if let index = indexesByID[repoID] {
+        if mergedRepositories[index].worktrees.isEmpty {
+          resolvingIDs.insert(repoID)
+        }
+        continue
+      }
+      if let existing = state.repositories[id: repoID], !existing.worktrees.isEmpty {
+        indexesByID[repoID] = mergedRepositories.count
+        mergedRepositories.append(existing)
+      } else {
+        indexesByID[repoID] = mergedRepositories.count
+        mergedRepositories.append(
+          remotePlaceholderRepository(host: root.host, remotePath: root.remotePath, repoID: repoID))
+        resolvingIDs.insert(repoID)
+      }
+    }
+    return RemoteRepositoryMergeResult(
+      repositories: mergedRepositories,
+      resolvingIDs: resolvingIDs
+    )
+  }
+
+  private struct RemoteRepositoryMergeResult: Sendable {
+    let repositories: [Repository]
+    let resolvingIDs: Set<Repository.ID>
+  }
+
+  /// A persisted remote root parsed into its derived repo id, host, and path.
+  private struct ParsedRemoteRoot {
+    let repoID: Repository.ID
+    let host: RemoteHost
+    let remotePath: String
+  }
+
   private struct WorktreesFetchResult: Sendable {
     let root: URL
     let isGitRepository: Bool
@@ -3584,66 +4106,86 @@ struct RepositoriesFeature {
     let errorMessage: String?
   }
 
+  /// The id (working-directory path) of the first worktree that repeats one
+  /// already seen, or `nil` when every id is unique. A non-nil result signals a
+  /// corrupt repo, since a healthy repository never repeats a path.
+  nonisolated static func firstDuplicateWorktreeID(in worktrees: [Worktree]) -> Worktree.ID? {
+    var seen: Set<Worktree.ID> = []
+    return worktrees.first(where: { !seen.insert($0.id).inserted })?.id
+  }
+
+  /// Failure-row copy for a repository whose worktree listing names the same
+  /// path more than once.
+  nonisolated static func duplicateWorktreePathMessage(path: String) -> String {
+    "This repository lists more than one worktree at the same path (\(path)). "
+      + "Its git configuration may be corrupt (for example a stale core.worktree). "
+      + "Repair the repository and reopen it."
+  }
+
+  /// Fetch and classify one root's worktree listing for the loader. Static +
+  /// `gitClient`-passed so it runs off-main inside the load task group.
+  nonisolated private static func worktreesFetchResult(
+    for root: URL,
+    gitClient: GitClientDependency
+  ) async -> WorktreesFetchResult {
+    // Check existence first so a removed / unmounted root surfaces a failure
+    // row instead of being synthesized as an empty folder (a missing path makes
+    // `gitClient.isGitRepository` return `false`, hiding the real problem).
+    // Routed through the dependency so fake `/tmp/...` test paths can override
+    // it.
+    let exists = await gitClient.rootDirectoryExists(root)
+    guard exists else {
+      return WorktreesFetchResult(
+        root: root,
+        isGitRepository: false,
+        worktrees: nil,
+        errorMessage:
+          "Directory not found at \(root.standardizedFileURL.path(percentEncoded: false)). "
+          + "It may have been moved or deleted."
+      )
+    }
+    // Classify through the git client so tests can override without touching the
+    // filesystem.
+    let isGit = await gitClient.isGitRepository(root)
+    guard isGit else {
+      return WorktreesFetchResult(root: root, isGitRepository: false, worktrees: [], errorMessage: nil)
+    }
+    do {
+      let worktrees = try await gitClient.worktrees(root)
+      // A duplicate path means the repo's git config is corrupt (e.g. a stale
+      // `core.worktree`). Refuse it and surface a failure rather than guess
+      // which of the colliding entries is real.
+      if let duplicate = firstDuplicateWorktreeID(in: worktrees) {
+        return WorktreesFetchResult(
+          root: root,
+          isGitRepository: true,
+          worktrees: nil,
+          errorMessage: duplicateWorktreePathMessage(path: duplicate.rawValue)
+        )
+      }
+      return WorktreesFetchResult(root: root, isGitRepository: true, worktrees: worktrees, errorMessage: nil)
+    } catch {
+      return WorktreesFetchResult(
+        root: root,
+        isGitRepository: true,
+        worktrees: nil,
+        errorMessage: error.localizedDescription
+      )
+    }
+  }
+
   private func loadRepositoriesData(_ roots: [URL]) async -> ([Repository], [LoadFailure]) {
     let fetchResults = await withTaskGroup(of: WorktreesFetchResult.self) { group in
       for root in roots {
         let gitClient = self.gitClient
         group.addTask {
-          // Directory-existence check first — if the root is gone
-          // (user trashed it from Finder while Supacode was
-          // running, external tooling removed it, the volume is
-          // unmounted), surface a load failure so the sidebar
-          // shows the error row. Otherwise `gitClient.isGitRepository`
-          // returns `false` for the missing path and the loader
-          // silently synthesizes an empty folder repository, which
-          // hides the real problem from the user. Routed through
-          // the dependency so tests with fake `/tmp/...` paths
-          // don't trip the check — they override it explicitly.
-          let exists = await gitClient.rootDirectoryExists(root)
-          guard exists else {
-            return WorktreesFetchResult(
-              root: root,
-              isGitRepository: false,
-              worktrees: nil,
-              errorMessage:
-                "Directory not found at \(root.standardizedFileURL.path(percentEncoded: false)). "
-                + "It may have been moved or deleted."
-            )
-          }
-          // Classify through the git client so tests can override
-          // without touching the filesystem — non-git folders skip
-          // the worktrees subprocess entirely.
-          let isGit = await gitClient.isGitRepository(root)
-          guard isGit else {
-            return WorktreesFetchResult(
-              root: root,
-              isGitRepository: false,
-              worktrees: [],
-              errorMessage: nil
-            )
-          }
-          do {
-            let worktrees = try await gitClient.worktrees(root)
-            return WorktreesFetchResult(
-              root: root,
-              isGitRepository: true,
-              worktrees: worktrees,
-              errorMessage: nil
-            )
-          } catch {
-            return WorktreesFetchResult(
-              root: root,
-              isGitRepository: true,
-              worktrees: nil,
-              errorMessage: error.localizedDescription
-            )
-          }
+          await Self.worktreesFetchResult(for: root, gitClient: gitClient)
         }
       }
 
       var resultsByRootID: [Repository.ID: WorktreesFetchResult] = [:]
       for await result in group {
-        let rootID = result.root.standardizedFileURL.path(percentEncoded: false)
+        let rootID = RepositoryID(result.root.standardizedFileURL.path(percentEncoded: false))
         resultsByRootID[rootID] = result
       }
       return resultsByRootID
@@ -3653,7 +4195,7 @@ struct RepositoriesFeature {
     var failures: [LoadFailure] = []
     for root in roots {
       let normalizedRoot = root.standardizedFileURL
-      let rootID = normalizedRoot.path(percentEncoded: false)
+      let rootID = RepositoryID(normalizedRoot.path(percentEncoded: false))
       guard let result = fetchResults[rootID] else { continue }
       let name = Repository.name(for: normalizedRoot)
       if result.isGitRepository {
@@ -3688,6 +4230,7 @@ struct RepositoriesFeature {
         // working without new entity types.
         let synthetic = Worktree(
           id: Repository.folderWorktreeID(for: normalizedRoot),
+          kind: .folder,
           name: name,
           detail: "",
           workingDirectory: normalizedRoot,
@@ -3704,37 +4247,129 @@ struct RepositoriesFeature {
         loaded.append(repository)
       }
     }
+    // Remote repositories are NOT resolved here: that SSH work runs
+    // asynchronously after the load (`.resolveRemoteRepositories`) so an
+    // unreachable host never blocks the initial sidebar. The `.repositoriesLoaded`
+    // handler merges in their placeholders and triggers resolution.
     return (loaded, failures)
   }
 
-  private func applyRepositories(
-    _ repositories: [Repository],
-    roots: [URL],
-    shouldPruneArchivedWorktreeIDs: Bool,
-    state: inout State,
-    animated: Bool
-  ) -> ApplyRepositoriesResult {
+  /// Customization transfer record produced by `prunedPendingWorktrees` and
+  /// consumed by `seedCustomizationForDiscoveredWorktree`. A struct rather
+  /// than a tuple so the two helpers can pass the payload around without
+  /// tripping the `large_tuple` lint.
+  private struct PendingCustomizationTransfer {
+    let repositoryID: Repository.ID
+    let worktreeName: String
+    let customization: PendingWorktree.Customization
+  }
+
+  /// Filter `state.pendingWorktrees` against a freshly-loaded roster. Pending
+  /// rows whose `worktreeName` matches a newly-discovered worktree are pruned
+  /// and (when customized) hand their title / color to the caller for
+  /// transfer onto the bucketed Item. Pending rows without a final name fall
+  /// back to a count-based drop so the random-name path keeps its old shape.
+  private func prunedPendingWorktrees(
+    state: State,
+    repositories: [Repository],
+    repositoryIDs: Set<Repository.ID>
+  ) -> ([PendingWorktree], [PendingCustomizationTransfer]) {
     let previousCounts = Dictionary(
       uniqueKeysWithValues: state.repositories.map { ($0.id, $0.worktrees.count) }
     )
-    let repositoryIDs = Set(repositories.map(\.id))
-    let newCounts = Dictionary(
-      uniqueKeysWithValues: repositories.map { ($0.id, $0.worktrees.count) }
-    )
+    let newCounts = Dictionary(uniqueKeysWithValues: repositories.map { ($0.id, $0.worktrees.count) })
     var addedCounts: [Repository.ID: Int] = [:]
     for (id, newCount) in newCounts {
-      let oldCount = previousCounts[id] ?? 0
-      let added = newCount - oldCount
-      if added > 0 {
-        addedCounts[id] = added
+      let added = newCount - (previousCounts[id] ?? 0)
+      if added > 0 { addedCounts[id] = added }
+    }
+    var remainingDiscoveredNamesByRepo: [Repository.ID: Set<String>] = [:]
+    for repository in repositories {
+      let previousNames = Set(state.repositories[id: repository.id]?.worktrees.map(\.name) ?? [])
+      let added = Set(repository.worktrees.map(\.name)).subtracting(previousNames)
+      if !added.isEmpty { remainingDiscoveredNamesByRepo[repository.id] = added }
+    }
+    var transfers: [PendingCustomizationTransfer] = []
+    // Pass 1: consume name matches up front. This drains the discovered-name
+    // set AND the count budget so the count-based fallback in pass 2 only
+    // fires for the leftover budget, never for a discovered name that a
+    // later pending row was going to match.
+    var droppedPendingIDs: Set<Worktree.ID> = []
+    for pending in state.pendingWorktrees {
+      guard repositoryIDs.contains(pending.repositoryID),
+        let pendingName = pending.progress.worktreeName,
+        remainingDiscoveredNamesByRepo[pending.repositoryID]?.contains(pendingName) == true
+      else { continue }
+      remainingDiscoveredNamesByRepo[pending.repositoryID]?.remove(pendingName)
+      if let customization = pending.customization,
+        customization.title != nil || customization.color != nil
+      {
+        transfers.append(
+          PendingCustomizationTransfer(
+            repositoryID: pending.repositoryID,
+            worktreeName: pendingName,
+            customization: customization,
+          )
+        )
       }
+      addedCounts[pending.repositoryID, default: 0] = max(0, (addedCounts[pending.repositoryID] ?? 0) - 1)
+      droppedPendingIDs.insert(pending.id)
     }
-    let filteredPendingWorktrees = state.pendingWorktrees.filter { pending in
+    // Pass 2: count-based drop for the unnamed remainder. Named pending rows
+    // only drop via pass 1's exact name match; otherwise concurrent creations
+    // can prune the wrong row when only a sibling worktree appears.
+    let filtered = state.pendingWorktrees.filter { pending in
       guard repositoryIDs.contains(pending.repositoryID) else { return false }
+      if droppedPendingIDs.contains(pending.id) { return false }
+      if pending.progress.worktreeName != nil { return true }
       guard let remaining = addedCounts[pending.repositoryID], remaining > 0 else { return true }
       addedCounts[pending.repositoryID] = remaining - 1
       return false
     }
+    return (filtered, transfers)
+  }
+
+  /// Write each transferred pending customization onto the bucketed Item for
+  /// the matching newly-discovered worktree. Skips fields the user has
+  /// already set via Customize Worktree… so the bucketed Item stays
+  /// authoritative once non-nil.
+  private func seedCustomizationForDiscoveredWorktree(
+    transfers: [PendingCustomizationTransfer],
+    repositories: [Repository],
+    state: inout State
+  ) {
+    guard !transfers.isEmpty else { return }
+    state.$sidebar.withLock { sidebar in
+      for transfer in transfers {
+        guard
+          let worktreeID = repositories.first(where: { $0.id == transfer.repositoryID })?
+            .worktrees.first(where: { $0.name == transfer.worktreeName })?.id
+        else { continue }
+        sidebar.mergeCustomization(
+          title: transfer.customization.title,
+          color: transfer.customization.color,
+          worktree: worktreeID,
+          in: transfer.repositoryID
+        )
+      }
+    }
+  }
+
+  private func applyRepositories(
+    _ repositories: [Repository],
+    roots: [URL],
+    shouldPruneArchivedWorktreeIDs: Bool,
+    state: inout State,
+    animated: Bool
+  ) -> ApplyRepositoriesResult {
+    let repositoryIDs = Set(repositories.map(\.id))
+    let (filteredPendingWorktrees, customizationTransfers) =
+      prunedPendingWorktrees(state: state, repositories: repositories, repositoryIDs: repositoryIDs)
+    seedCustomizationForDiscoveredWorktree(
+      transfers: customizationTransfers,
+      repositories: repositories,
+      state: &state,
+    )
     let availableWorktreeIDs = Set(repositories.flatMap { $0.worktrees.map(\.id) })
     let (filteredRemovingRepositoryIDs, filteredActiveRemovalBatches) =
       prunedRemovalTrackers(state: state, availableRepoIDs: repositoryIDs)
@@ -4111,7 +4746,7 @@ extension RepositoriesFeature.State {
   func orderedRepositoryRoots() -> [URL] {
     let rootsByID = Dictionary(
       uniqueKeysWithValues: repositoryRoots.map {
-        ($0.standardizedFileURL.path(percentEncoded: false), $0.standardizedFileURL)
+        (RepositoryID($0.standardizedFileURL.path(percentEncoded: false)), $0.standardizedFileURL)
       }
     )
     var ordered: [URL] = []
@@ -4122,19 +4757,38 @@ extension RepositoriesFeature.State {
       }
     }
     for rootURL in repositoryRoots {
-      let id = rootURL.standardizedFileURL.path(percentEncoded: false)
+      let id = RepositoryID(rootURL.standardizedFileURL.path(percentEncoded: false))
       if seen.insert(id).inserted {
         ordered.append(rootURL.standardizedFileURL)
       }
     }
     if ordered.isEmpty {
-      ordered = repositories.map(\.rootURL)
+      // Local only: a remote repo's `rootURL` is a remote path whose `.path`
+      // doesn't match its `remote:` id, so it must not leak in as a bogus id.
+      ordered = repositories.filter { $0.host == nil }.map(\.rootURL)
     }
     return ordered
   }
 
+  /// Every repository id in sidebar order. The persisted `sidebar.sections`
+  /// order wins, so a drag sticks across recompute and reload; anything not yet
+  /// placed falls back to load order. Local roots and host-keyed remote ids are
+  /// treated alike: remote ids aren't in `repositoryRoots`, so the
+  /// `repositories` pass is what surfaces them.
   func orderedRepositoryIDs() -> [Repository.ID] {
-    orderedRepositoryRoots().map { $0.standardizedFileURL.path(percentEncoded: false) }
+    let rootIDs = repositoryRoots.map {
+      RepositoryID($0.standardizedFileURL.path(percentEncoded: false))
+    }
+    var ordered: [Repository.ID] = []
+    var seen: Set<Repository.ID> = []
+    for id in sidebar.sections.keys where repositories[id: id] != nil || rootIDs.contains(id) {
+      if seen.insert(id).inserted { ordered.append(id) }
+    }
+    for id in rootIDs where seen.insert(id).inserted { ordered.append(id) }
+    for repository in repositories where seen.insert(repository.id).inserted {
+      ordered.append(repository.id)
+    }
+    return ordered
   }
 
   func repositoryID(for worktreeID: Worktree.ID?) -> Repository.ID? {
@@ -4410,11 +5064,15 @@ extension RepositoriesFeature.State {
     let nameByRepoID = Dictionary(uniqueKeysWithValues: repositories.map { ($0.id, $0.name) })
     return ids.compactMap { id in
       guard let item = sidebarItems[id: id] else { return nil }
+      let repositoryName = Repository.sidebarDisplayName(
+        custom: sidebar.sections[item.repositoryID]?.title,
+        fallback: nameByRepoID[item.repositoryID] ?? ""
+      )
       return HotkeyWorktreeSlot(
         id: item.id,
-        name: item.name,
+        name: SidebarDisplayName.resolved(custom: item.customTitle, fallback: item.name) ?? item.name,
         repositoryID: item.repositoryID,
-        repositoryName: nameByRepoID[item.repositoryID] ?? ""
+        repositoryName: repositoryName
       )
     }
   }
@@ -4428,15 +5086,30 @@ struct FailedWorktreeCleanup {
 }
 
 extension RepositoriesFeature.State {
-  mutating func removePendingWorktree(_ id: String) {
+  mutating func removePendingWorktree(_ id: Worktree.ID) {
     guard pendingWorktrees.contains(where: { $0.id == id }) else { return }
     pendingWorktrees.removeAll { $0.id == id }
     RepositoriesFeature.syncSidebar(&self)
   }
 
+  /// Single source of truth for draining the in-flight customization parked by the New Worktree
+  /// prompt's `submit` delegate. `branchName == nil` drains every entry for the repo (used by the
+  /// removing-repo guard and prompt cancel); a non-nil `branchName` drains just that (repo, branch)
+  /// pair so concurrent creations don't lose unrelated customizations.
+  mutating func dropPendingCustomization(repositoryID: Repository.ID, branchName: String? = nil) {
+    if let branchName {
+      pendingCreationCustomizations[repositoryID]?.removeValue(forKey: branchName)
+    } else {
+      pendingCreationCustomizations.removeValue(forKey: repositoryID)
+    }
+    if pendingCreationCustomizations[repositoryID]?.isEmpty == true {
+      pendingCreationCustomizations.removeValue(forKey: repositoryID)
+    }
+  }
+
   @discardableResult
   mutating func updatePendingWorktreeProgress(
-    _ id: String,
+    _ id: Worktree.ID,
     progress: WorktreeCreationProgress
   ) -> Bool {
     guard let index = pendingWorktrees.firstIndex(where: { $0.id == id }) else { return false }
@@ -4450,12 +5123,7 @@ extension RepositoriesFeature.State {
     if repository.worktrees[id: worktree.id] != nil { return }
     var worktrees = repository.worktrees
     worktrees.insert(worktree, at: 0)
-    repositories[index] = Repository(
-      id: repository.id,
-      rootURL: repository.rootURL,
-      name: repository.name,
-      worktrees: worktrees,
-    )
+    repositories[index] = repository.withWorktrees(worktrees)
   }
 
   @discardableResult
@@ -4465,12 +5133,7 @@ extension RepositoriesFeature.State {
     guard repository.worktrees[id: worktreeID] != nil else { return false }
     var worktrees = repository.worktrees
     worktrees.remove(id: worktreeID)
-    repositories[index] = Repository(
-      id: repository.id,
-      rootURL: repository.rootURL,
-      name: repository.name,
-      worktrees: worktrees,
-    )
+    repositories[index] = repository.withWorktrees(worktrees)
     return true
   }
 
@@ -4482,7 +5145,7 @@ extension RepositoriesFeature.State {
     guard let name, !name.isEmpty else {
       return FailedWorktreeCleanup(didRemoveWorktree: false, worktree: nil)
     }
-    let repositoryRootURL = URL(fileURLWithPath: repositoryID).standardizedFileURL
+    let repositoryRootURL = URL(fileURLWithPath: repositoryID.rawValue).standardizedFileURL
     let normalizedBaseDirectory = baseDirectory.standardizedFileURL
     let worktreeURL =
       normalizedBaseDirectory
@@ -4491,11 +5154,12 @@ extension RepositoriesFeature.State {
     guard worktreeURL.isInside(baseDirectory: normalizedBaseDirectory) else {
       return FailedWorktreeCleanup(didRemoveWorktree: false, worktree: nil)
     }
-    let worktreeID = worktreeURL.path(percentEncoded: false)
+    let worktreeID = WorktreeID(worktreeURL.path(percentEncoded: false))
     let worktree =
       repositories[id: repositoryID]?.worktrees[id: worktreeID]
       ?? Worktree(
         id: worktreeID,
+        kind: .git,
         name: name,
         detail: "",
         workingDirectory: worktreeURL,
@@ -4598,22 +5262,8 @@ extension RepositoriesFeature.State {
       let worktree = repository.worktrees[worktreeIndex]
       guard worktree.name != name else { return }
       var worktrees = repository.worktrees
-      worktrees[id: worktreeID] = Worktree(
-        id: worktree.id,
-        name: name,
-        detail: worktree.detail,
-        workingDirectory: worktree.workingDirectory,
-        repositoryRootURL: worktree.repositoryRootURL,
-        createdAt: worktree.createdAt,
-        isMissing: worktree.isMissing,
-        isAttached: worktree.isAttached,
-      )
-      repositories[index] = Repository(
-        id: repository.id,
-        rootURL: repository.rootURL,
-        name: repository.name,
-        worktrees: worktrees,
-      )
+      worktrees[id: worktreeID] = worktree.renamed(name)
+      repositories[index] = repository.withWorktrees(worktrees)
       return
     }
   }
@@ -4730,6 +5380,19 @@ extension RepositoriesFeature.State {
     if recordHistory {
       recordWorktreeHistoryTransition(from: previousID, to: worktreeID)
     }
+    if let worktreeID {
+      recordWorktreeMRU(worktreeID: worktreeID)
+    }
+  }
+
+  /// Hoists the selected worktree to the head of `worktreeMRU`. Called from
+  /// every concrete worktree selection — selection-clearing (nil) paths are
+  /// no-ops so a "select nothing" transition can't poison the MRU head.
+  mutating func recordWorktreeMRU(worktreeID: Worktree.ID) {
+    if let existingIndex = worktreeMRU.firstIndex(of: worktreeID) {
+      worktreeMRU.remove(at: existingIndex)
+    }
+    worktreeMRU.insert(worktreeID, at: 0)
   }
 
   /// Records a fresh worktree navigation: pushes the previous selection onto
@@ -4769,7 +5432,15 @@ extension RepositoriesFeature.State {
         }
       }
       setSingleWorktreeSelection(candidate, recordHistory: false)
-      return .send(.delegate(.selectedWorktreeChanged(worktree(for: candidate))))
+      var effects: [Effect<RepositoriesFeature.Action>] = [
+        .send(.delegate(.selectedWorktreeChanged(worktree(for: candidate))))
+      ]
+      if sidebarItems[id: candidate] != nil {
+        effects.append(
+          .send(.sidebarItems(.element(id: candidate, action: .focusTerminalRequested)))
+        )
+      }
+      return .merge(effects)
     }
   }
 
@@ -4823,6 +5494,13 @@ extension RepositoriesFeature.State {
     selection = nextSelectedWorktreeID.map(SidebarSelection.worktree)
     sidebarSelectedWorktreeIDs = nextSidebarSelectedWorktreeIDs
     recordWorktreeHistoryTransition(from: previousSelection, to: nextSelectedWorktreeID)
+    // Sidebar selection bypasses `setSingleWorktreeSelection`, so record the
+    // worktree MRU here too — otherwise clicking a worktree (the dominant nav
+    // path) never updates `worktreeMRU`, and the ⌘P switcher can't put the
+    // worktree you actually had open at the top.
+    if let nextSelectedWorktreeID {
+      recordWorktreeMRU(worktreeID: nextSelectedWorktreeID)
+    }
     var effects: [Effect<RepositoriesFeature.Action>] = []
     if focusTerminal,
       let nextSelectedWorktreeID,
@@ -4902,7 +5580,8 @@ extension RepositoriesFeature.State {
     // curation if we overwrote `sidebar.json` from here.
     if roots.isEmpty, repositories.isEmpty { return }
 
-    let rootIDs: Set<Repository.ID> = Set(roots.map { $0.standardizedFileURL.path(percentEncoded: false) })
+    let rootIDs: Set<Repository.ID> = Set(
+      roots.map { RepositoryID($0.standardizedFileURL.path(percentEncoded: false)) })
     let localIDs = Set(repositories.map(\.id))
     let availableRepoIDs = localIDs.union(rootIDs)
     let repositoriesByID = Dictionary(uniqueKeysWithValues: repositories.map { ($0.id, $0) })
@@ -4920,6 +5599,10 @@ extension RepositoriesFeature.State {
       let mainID =
         repository.isGitRepository ? repository.worktrees.first(where: { isMainWorktree($0) })?.id : nil
       let worktreeIDs = Set(repository.worktrees.map(\.id))
+      // A disconnected remote is an empty placeholder (resolved remotes always have
+      // >=1 worktree); skip its prune so a pin survives the disconnect.
+      let isUnresolvedRemotePlaceholder = repository.host != nil && repository.worktrees.isEmpty
+      let pruneAgainstRoster = pruneLivenessAgainstRoster && !isUnresolvedRemotePlaceholder
       var copy = section
       var seenInCuratedBuckets: Set<Worktree.ID> = []
       for (bucketID, bucket) in copy.buckets {
@@ -4927,7 +5610,7 @@ extension RepositoriesFeature.State {
         var prunedItems: OrderedDictionary<Worktree.ID, SidebarState.Item> = [:]
         for (worktreeID, item) in bucket.items {
           if let mainID, worktreeID == mainID { continue }
-          if pruneLivenessAgainstRoster, !worktreeIDs.contains(worktreeID) { continue }
+          if pruneAgainstRoster, !worktreeIDs.contains(worktreeID) { continue }
           prunedItems[worktreeID] = item
           seenInCuratedBuckets.insert(worktreeID)
         }
@@ -4948,7 +5631,11 @@ extension RepositoriesFeature.State {
         unpinned.items[worktree.id] = .init()
         copy.buckets[.unpinned] = unpinned
       }
-      Self.pruneCollapsedBranchPrefixes(in: &copy, worktrees: repository.worktrees)
+      // Same carve-out: a disconnected remote's empty roster would otherwise drop
+      // every stored branch-collapse prefix.
+      if !isUnresolvedRemotePlaceholder {
+        Self.pruneCollapsedBranchPrefixes(in: &copy, worktrees: repository.worktrees)
+      }
       rebuilt[repoID] = copy
     }
 
diff --git a/supacode/Features/Repositories/Reducer/RepositoryCustomizationFeature.swift b/supacode/Features/Repositories/Reducer/RepositoryCustomizationFeature.swift
index 893c66f33..351d32c08 100644
--- a/supacode/Features/Repositories/Reducer/RepositoryCustomizationFeature.swift
+++ b/supacode/Features/Repositories/Reducer/RepositoryCustomizationFeature.swift
@@ -37,7 +37,8 @@ struct RepositoryCustomizationFeature {
 
       case .saveButtonTapped:
         let trimmed = state.title.trimmingCharacters(in: .whitespacesAndNewlines)
-        let resolvedTitle = trimmed.isEmpty || trimmed == state.defaultName ? nil : trimmed
+        // Preserve verbatim; typing the default name locks it in as an override.
+        let resolvedTitle = trimmed.isEmpty ? nil : trimmed
         return .send(
           .delegate(
             .save(
diff --git a/supacode/Features/Repositories/Reducer/SidebarItemFeature.swift b/supacode/Features/Repositories/Reducer/SidebarItemFeature.swift
index 98428943c..28e5687af 100644
--- a/supacode/Features/Repositories/Reducer/SidebarItemFeature.swift
+++ b/supacode/Features/Repositories/Reducer/SidebarItemFeature.swift
@@ -50,6 +50,20 @@ struct SidebarItemFeature {
     var hasMergedBadge: Bool
     /// Mirror of `Worktree.isMissing`; drives the orphan row UI.
     var isMissing: Bool = false
+    /// Mirror of `Worktree.host`: `nil` for a local item, otherwise the SSH host
+    /// (carrying `<user>@<host>:<port>` via `sshDestination`). Together with
+    /// `kind` this is the unified local/remote + git/folder discriminator every
+    /// consumer branches on (icon, scripts, worktree creation, settings).
+    var host: RemoteHost?
+
+    /// Whether this item lives on a remote SSH host.
+    var isRemote: Bool { host != nil }
+    /// Mirror of `SidebarState.Item.title`; reconcile fans this in from
+    /// `@Shared(.sidebar)`. `nil` or whitespace-only means fall back to `name`.
+    var customTitle: String?
+    /// Mirror of `SidebarState.Item.color`; reconcile fans this in from
+    /// `@Shared(.sidebar)`. `nil` means default styling.
+    var customTint: RepositoryColor?
 
     var lifecycle: Lifecycle = .idle
 
@@ -103,7 +117,6 @@ struct SidebarItemFeature {
     var isTaskRunning: Bool { isProgressBusy || hasAgentActivity }
 
     var isDragging: Bool = false
-    var shortcutHint: String?
     /// One-shot focus token: set when a selection arrives with `focusTerminal: true`.
     var shouldFocusTerminal: Bool = false
   }
@@ -117,7 +130,6 @@ struct SidebarItemFeature {
     case runningScriptStopped(id: UUID)
     case agentSnapshotChanged([AgentPresenceFeature.AgentInstance], hasActivity: Bool)
     case terminalProjectionChanged(WorktreeRowProjection)
-    case shortcutHintChanged(String?)
     case dragSessionChanged(isDragging: Bool)
     case focusTerminalRequested
     case focusTerminalConsumed
@@ -186,11 +198,6 @@ struct SidebarItemFeature {
         if state.notifications != projection.notifications { state.notifications = projection.notifications }
         return .none
 
-      case .shortcutHintChanged(let hint):
-        guard state.shortcutHint != hint else { return .none }
-        state.shortcutHint = hint
-        return .none
-
       case .dragSessionChanged(let isDragging):
         guard state.isDragging != isDragging else { return .none }
         state.isDragging = isDragging
@@ -216,9 +223,15 @@ extension SidebarItemFeature.State {
   /// then the subtitle's last path component, then `branchName`.
   var sidebarDisplayName: String? {
     SidebarDisplayName.compute(
-      isMainWorktree: isMainWorktree, id: id, subtitle: subtitle, branchName: branchName
+      isMainWorktree: isMainWorktree, id: id, subtitle: subtitle, branchName: branchName,
     )
   }
+  /// Final string the row should render: user override (trimmed) when set,
+  /// else `sidebarDisplayName`. Centralised so sidebar / archive / detail
+  /// views stay in lock-step on the empty / whitespace fallback rule.
+  var resolvedSidebarTitle: String? {
+    SidebarDisplayName.resolved(custom: customTitle, fallback: sidebarDisplayName)
+  }
   var accent: WorktreeAccent { WorktreeAccent.derive(isMainWorktree: isMainWorktree, isPinned: isPinned) }
   /// True iff any tracked agent on this row is awaiting user input.
   /// Drives the Active section's classification ("agent awaiting input").
@@ -233,11 +246,11 @@ enum SidebarDisplayName {
     isMainWorktree: Bool,
     id: SidebarItemID,
     subtitle: String?,
-    branchName: String
+    branchName: String,
   ) -> String? {
     guard !isMainWorktree else { return nil }
-    if id.contains("/") {
-      let pathName = URL(fileURLWithPath: id).lastPathComponent
+    if id.rawValue.contains("/") {
+      let pathName = URL(fileURLWithPath: id.rawValue).lastPathComponent
       if !pathName.isEmpty { return pathName }
     }
     if let subtitle, !subtitle.isEmpty, subtitle != "." {
@@ -246,6 +259,15 @@ enum SidebarDisplayName {
     }
     return branchName
   }
+
+  /// Returns `custom` when set (after trim), otherwise `fallback`. Shared so
+  /// the sidebar, archive, and detail views can't drift on the empty /
+  /// whitespace fallback rule for user-overridden titles.
+  static func resolved(custom: String?, fallback: String?) -> String? {
+    let trimmed = custom?.trimmingCharacters(in: .whitespacesAndNewlines)
+    if let trimmed, !trimmed.isEmpty { return trimmed }
+    return fallback
+  }
 }
 
 extension SidebarItemFeature.State.Lifecycle {
@@ -278,6 +300,8 @@ struct SelectedWorktreeSlice: Equatable, Sendable {
   let subtitle: String?
   let isMainWorktree: Bool
   let isPinned: Bool
+  let customTitle: String?
+  let customTint: RepositoryColor?
   let lifecycle: SidebarItemFeature.State.Lifecycle
   let pullRequest: GithubPullRequest?
   let runningScripts: IdentifiedArrayOf<SidebarItemFeature.State.RunningScript>
@@ -291,6 +315,8 @@ struct SelectedWorktreeSlice: Equatable, Sendable {
     self.subtitle = row.subtitle
     self.isMainWorktree = row.isMainWorktree
     self.isPinned = row.isPinned
+    self.customTitle = row.customTitle
+    self.customTint = row.customTint
     self.lifecycle = row.lifecycle
     self.pullRequest = row.pullRequest
     self.runningScripts = row.runningScripts
@@ -298,10 +324,14 @@ struct SelectedWorktreeSlice: Equatable, Sendable {
 
   var sidebarDisplayName: String? {
     SidebarDisplayName.compute(
-      isMainWorktree: isMainWorktree, id: id, subtitle: subtitle, branchName: branchName
+      isMainWorktree: isMainWorktree, id: id, subtitle: subtitle, branchName: branchName,
     )
   }
 
+  var resolvedSidebarTitle: String? {
+    SidebarDisplayName.resolved(custom: customTitle, fallback: sidebarDisplayName)
+  }
+
   var accent: WorktreeAccent { WorktreeAccent.derive(isMainWorktree: isMainWorktree, isPinned: isPinned) }
 
   var isFolder: Bool { kind == .folder }
diff --git a/supacode/Features/Repositories/Reducer/WorktreeCreationPromptFeature.swift b/supacode/Features/Repositories/Reducer/WorktreeCreationPromptFeature.swift
index 5af03c9b3..02d0b30bc 100644
--- a/supacode/Features/Repositories/Reducer/WorktreeCreationPromptFeature.swift
+++ b/supacode/Features/Repositories/Reducer/WorktreeCreationPromptFeature.swift
@@ -31,8 +31,14 @@ struct WorktreeCreationPromptFeature {
     var worktreePathOverride: String = ""
     /// Disclosure state for the advanced placement section. Collapsed by default.
     var showAdvancedOptions: Bool = false
+    /// Disclosure state for the title / color appearance section. Collapsed by default.
+    var showAppearanceOptions: Bool = false
     var validationMessage: String?
     var isValidating = false
+    /// Optional sidebar customization captured by the new Title / Color
+    /// section; transferred to `PendingWorktree.customization` on submit.
+    var title: String = ""
+    var color: RepositoryColor?
 
     /// Default leaf folder name shown as the name-override placeholder.
     var worktreeNamePlaceholder: String {
@@ -100,7 +106,9 @@ struct WorktreeCreationPromptFeature {
       branchName: String,
       baseRef: String?,
       fetchOrigin: Bool,
-      placement: WorktreePlacementOverride
+      placement: WorktreePlacementOverride,
+      title: String?,
+      color: RepositoryColor?
     )
   }
 
@@ -137,6 +145,12 @@ struct WorktreeCreationPromptFeature {
         }
         state.validationMessage = nil
         let pathOverride = state.worktreePathOverride.trimmingCharacters(in: .whitespacesAndNewlines)
+        // Preserve the user's typed title verbatim, even when it equals the
+        // branch name. The render is identical (no override → fall back to
+        // branch name) but the round-trip into the Customize sheet relies
+        // on the value surviving.
+        let trimmedTitle = state.title.trimmingCharacters(in: .whitespacesAndNewlines)
+        let resolvedTitle = trimmedTitle.isEmpty ? nil : trimmedTitle
         return .send(
           .delegate(
             .submit(
@@ -148,7 +162,9 @@ struct WorktreeCreationPromptFeature {
               placement: WorktreePlacementOverride(
                 name: nameOverride.isEmpty ? nil : nameOverride,
                 path: pathOverride.isEmpty ? nil : pathOverride
-              )
+              ),
+              title: resolvedTitle,
+              color: state.color
             )
           )
         )
diff --git a/supacode/Features/Repositories/Reducer/WorktreeCustomizationFeature.swift b/supacode/Features/Repositories/Reducer/WorktreeCustomizationFeature.swift
new file mode 100644
index 000000000..6e1ee534f
--- /dev/null
+++ b/supacode/Features/Repositories/Reducer/WorktreeCustomizationFeature.swift
@@ -0,0 +1,65 @@
+import ComposableArchitecture
+import Foundation
+import SupacodeSettingsShared
+
+@Reducer
+struct WorktreeCustomizationFeature {
+  @ObservableState
+  struct State: Equatable {
+    let worktreeID: Worktree.ID
+    let repositoryID: Repository.ID
+    let defaultName: String
+    var title: String
+    var color: RepositoryColor?
+  }
+
+  enum Action: BindableAction, Equatable {
+    case binding(BindingAction<State>)
+    case cancelButtonTapped
+    case saveButtonTapped
+    case delegate(Delegate)
+  }
+
+  @CasePathable
+  enum Delegate: Equatable {
+    case cancel
+    case save(
+      worktreeID: Worktree.ID,
+      repositoryID: Repository.ID,
+      title: String?,
+      color: RepositoryColor?,
+    )
+  }
+
+  var body: some Reducer<State, Action> {
+    BindingReducer()
+    Reduce { state, action in
+      switch action {
+      case .binding:
+        return .none
+
+      case .cancelButtonTapped:
+        return .send(.delegate(.cancel))
+
+      case .saveButtonTapped:
+        let trimmed = state.title.trimmingCharacters(in: .whitespacesAndNewlines)
+        // Preserve the user's input verbatim; typing the default name "locks in" the current name
+        // as a real override rather than silently collapsing to nil.
+        let resolvedTitle = trimmed.isEmpty ? nil : trimmed
+        return .send(
+          .delegate(
+            .save(
+              worktreeID: state.worktreeID,
+              repositoryID: state.repositoryID,
+              title: resolvedTitle,
+              color: state.color,
+            )
+          )
+        )
+
+      case .delegate:
+        return .none
+      }
+    }
+  }
+}
diff --git a/supacode/Features/Repositories/Views/ArchivedWorktreeRowView.swift b/supacode/Features/Repositories/Views/ArchivedWorktreeRowView.swift
index f6c8638a9..6a5515c14 100644
--- a/supacode/Features/Repositories/Views/ArchivedWorktreeRowView.swift
+++ b/supacode/Features/Repositories/Views/ArchivedWorktreeRowView.swift
@@ -5,8 +5,13 @@ import SwiftUI
 struct ArchivedWorktreeRowView: View {
   let worktree: Worktree
   let pullRequest: GithubPullRequest?
+  let customTitle: String?
+  let customTint: RepositoryColor?
   let onUnarchive: () -> Void
   let onDelete: () -> Void
+  // The system paints selected rows with white-on-blue chrome; the custom tint must yield so the
+  // selected row stays readable (matches `SidebarItemView.TitleView`).
+  @Environment(\.backgroundProminence) private var backgroundProminence
 
   var body: some View {
     let display = WorktreePullRequestDisplay(
@@ -15,6 +20,11 @@ struct ArchivedWorktreeRowView: View {
     )
     let deleteShortcut = KeyboardShortcut(.delete, modifiers: [.command, .shift]).display
     let bodyFontAscender = NSFont.preferredFont(forTextStyle: .body).ascender
+    // User override wins; fall back to the branch / folder name on whitespace
+    // or nil. Centralised so archive / sidebar / detail can't drift.
+    let displayName =
+      SidebarDisplayName.resolved(custom: customTitle, fallback: worktree.name)
+      ?? worktree.name
     VStack(alignment: .leading, spacing: 2) {
       HStack(alignment: .firstTextBaseline, spacing: 8) {
         Image(systemName: "archivebox")
@@ -25,9 +35,14 @@ struct ArchivedWorktreeRowView: View {
           .alignmentGuide(.firstTextBaseline) { _ in
             bodyFontAscender
           }
-        Text(worktree.name)
+        let titleText = Text(displayName)
           .font(.body)
           .lineLimit(1)
+        if let customTint, backgroundProminence != .increased {
+          titleText.foregroundStyle(customTint.color)
+        } else {
+          titleText
+        }
         Spacer(minLength: 8)
         HStack(spacing: 8) {
           Button {
diff --git a/supacode/Features/Repositories/Views/ArchivedWorktreesDetailView.swift b/supacode/Features/Repositories/Views/ArchivedWorktreesDetailView.swift
index 356adff31..e497a75ec 100644
--- a/supacode/Features/Repositories/Views/ArchivedWorktreesDetailView.swift
+++ b/supacode/Features/Repositories/Views/ArchivedWorktreesDetailView.swift
@@ -43,6 +43,8 @@ struct ArchivedWorktreesDetailView: View {
                 ArchivedWorktreeRowView(
                   worktree: worktree,
                   pullRequest: store.state.sidebarItems[id: worktree.id]?.pullRequest,
+                  customTitle: store.state.sidebarItems[id: worktree.id]?.customTitle,
+                  customTint: store.state.sidebarItems[id: worktree.id]?.customTint,
                   onUnarchive: {
                     store.send(.unarchiveWorktree(worktree.id))
                   },
diff --git a/supacode/Features/Repositories/Views/EmptyStateView.swift b/supacode/Features/Repositories/Views/EmptyStateView.swift
index 806d76688..d67108d25 100644
--- a/supacode/Features/Repositories/Views/EmptyStateView.swift
+++ b/supacode/Features/Repositories/Views/EmptyStateView.swift
@@ -31,6 +31,11 @@ struct EmptyStateView: View {
       }
       .appKeyboardShortcut(openRepo)
       .help("Open Repository or Folder (\(openRepo?.display ?? "none"))")
+      Button("Add Remote Repository…") {
+        store.send(.requestAddRemoteRepository)
+      }
+      .buttonStyle(.link)
+      .help("Add a repository or folder on an SSH host")
     }
     .multilineTextAlignment(.center)
     .frame(maxWidth: .infinity, maxHeight: .infinity)
diff --git a/supacode/Features/Repositories/Views/OpenWorktreeActionMenuLabelView.swift b/supacode/Features/Repositories/Views/OpenWorktreeActionMenuLabelView.swift
index f3c143f3d..da8d2f8c8 100644
--- a/supacode/Features/Repositories/Views/OpenWorktreeActionMenuLabelView.swift
+++ b/supacode/Features/Repositories/Views/OpenWorktreeActionMenuLabelView.swift
@@ -4,7 +4,6 @@ import SwiftUI
 
 struct OpenWorktreeActionMenuLabelView: View {
   let action: OpenWorktreeAction
-  let shortcutHint: String?
 
   private func resizedIcon(_ image: NSImage, size: CGSize) -> NSImage {
     let newImage = NSImage(size: size)
@@ -21,11 +20,7 @@ struct OpenWorktreeActionMenuLabelView: View {
 
   var body: some View {
     Label {
-      if let shortcutHint {
-        Text(shortcutHint)
-      } else {
-        Text(action.labelTitle)
-      }
+      Text(action.labelTitle)
     } icon: {
       if let icon = action.menuIcon {
         switch icon {
diff --git a/supacode/Features/Repositories/Views/PullRequestStatusButton.swift b/supacode/Features/Repositories/Views/PullRequestStatusButton.swift
index 801f4997d..68337411d 100644
--- a/supacode/Features/Repositories/Views/PullRequestStatusButton.swift
+++ b/supacode/Features/Repositories/Views/PullRequestStatusButton.swift
@@ -1,16 +1,7 @@
-import Sharing
-import SupacodeSettingsShared
 import SwiftUI
 
 struct PullRequestStatusButton: View {
   let model: PullRequestStatusModel
-  @Environment(CommandKeyObserver.self) private var commandKeyObserver
-  @Shared(.settingsFile) private var settingsFile
-
-  private var openPRDisplay: String {
-    let effective = AppShortcuts.openPullRequest.effective(from: settingsFile.global.shortcutOverrides)
-    return effective?.display ?? ""
-  }
 
   var body: some View {
     PullRequestChecksPopoverButton(pullRequest: model.pullRequest) {
@@ -26,16 +17,9 @@ struct PullRequestStatusButton: View {
           PullRequestChecksRingView(breakdown: breakdown)
         }
         if let detailText = model.detailText {
-          Text(
-            commandKeyObserver.isPressed
-              ? "Open on GitHub \(openPRDisplay)" : detailText
-          )
-          .lineLimit(1)
-        } else if commandKeyObserver.isPressed {
-          Text("Open on GitHub \(openPRDisplay)")
+          Text(detailText)
             .lineLimit(1)
-        }
-        if model.detailText == nil, !commandKeyObserver.isPressed {
+        } else {
           Text(model.title)
             .lineLimit(1)
         }
diff --git a/supacode/Features/Repositories/Views/RemoteConnectionFormView.swift b/supacode/Features/Repositories/Views/RemoteConnectionFormView.swift
new file mode 100644
index 000000000..42ce71a04
--- /dev/null
+++ b/supacode/Features/Repositories/Views/RemoteConnectionFormView.swift
@@ -0,0 +1,69 @@
+import ComposableArchitecture
+import SupacodeSettingsShared
+import SwiftUI
+
+/// Add / edit form for a remote (SSH) repository connection. Mirrors the New
+/// Worktree prompt: a grouped form with a title/subtitle header, a bottom
+/// button bar, and validation surfaced in the section footer (the sheet stays
+/// open on a failed connect rather than dismissing). Renaming is handled
+/// through Customize Appearance, so there is no display-name field.
+struct RemoteConnectionFormView: View {
+  @Bindable var store: StoreOf<RemoteConnectionFormFeature>
+
+  var body: some View {
+    Form {
+      Section {
+        TextField("Server", text: $store.server)
+          .help("An ~/.ssh/config alias or a hostname Supacode will pass to ssh")
+        LabeledContent {
+          TextField("Port", text: $store.port).labelsHidden()
+        } label: {
+          Text("Port")
+          Text("Defaults to 22.")
+        }
+        LabeledContent {
+          TextField("User", text: $store.username).labelsHidden()
+        } label: {
+          Text("User")
+          Text("Defaults to your SSH config.")
+        }
+        LabeledContent {
+          TextField("Path", text: $store.remotePath).labelsHidden()
+        } label: {
+          Text("Path")
+          Text("`~` will be expanded at creation time.")
+        }
+      } header: {
+        // `NavigationStack` with title and subtitle is bugged inside
+        // sheets in macOS 26.*, and this is a nice enough fallback.
+        Text(store.isEditing ? "Edit Connection" : "Connect to Remote Host")
+        Text("Open a repository or folder on another machine over SSH.")
+      } footer: {
+        if let message = store.validationMessage, !message.isEmpty {
+          Text(message).foregroundStyle(.red)
+        }
+      }
+      .headerProminence(.increased)
+    }
+    .formStyle(.grouped)
+    .scrollBounceBehavior(.basedOnSize)
+    .safeAreaInset(edge: .bottom, spacing: 0) {
+      HStack {
+        if store.isValidating {
+          ProgressView().controlSize(.small)
+        }
+        Spacer()
+        Button("Cancel", role: .cancel) { store.send(.cancelButtonTapped) }
+          .keyboardShortcut(.cancelAction)
+          .help("Cancel (Esc)")
+        Button(store.isEditing ? "Save" : "Add") { store.send(.submitButtonTapped) }
+          .keyboardShortcut(.defaultAction)
+          .disabled(!store.canSubmit)
+          .help(store.isEditing ? "Save the connection" : "Add this remote repository to the sidebar")
+      }
+      .padding(.horizontal, 20)
+      .padding(.bottom, 20)
+    }
+    .frame(minWidth: 420)
+  }
+}
diff --git a/supacode/Features/Repositories/Views/RemoteRepositoriesBetaCardView.swift b/supacode/Features/Repositories/Views/RemoteRepositoriesBetaCardView.swift
new file mode 100644
index 000000000..97d9590e5
--- /dev/null
+++ b/supacode/Features/Repositories/Views/RemoteRepositoriesBetaCardView.swift
@@ -0,0 +1,82 @@
+import Sharing
+import SwiftUI
+
+/// Bottom-of-sidebar card announcing the remote SSH repositories feature, marked
+/// Beta. Pure FYI: no toggle, no opt-in. Visible until the user dismisses past
+/// the relevance cutoff. The priority host (`SidebarBottomCardView`) owns the
+/// AppStorage read so SwiftUI re-renders at that layer on dismiss.
+struct RemoteRepositoriesBetaCardView: View {
+  /// Bump on each material content change. Users who dismissed before this date
+  /// see the prompt again. Anchored to ship day at 00:00 UTC, the earliest
+  /// instant any local timezone reaches the ship-day calendar date, so a
+  /// dismiss-on-launch-day satisfies `dismissedAt >= relevantSince`.
+  static let cardRelevantSinceDate = Date(timeIntervalSince1970: 1_781_222_400)  // 2026-06-12 00:00 UTC.
+
+  static func isDismissed(at dismissedAt: Date) -> Bool {
+    SidebarCardRelevance.isDismissed(at: dismissedAt, relevantSince: cardRelevantSinceDate)
+  }
+
+  static func resolveMode(dismissedAt: Date) -> Mode {
+    Self.isDismissed(at: dismissedAt) ? .hidden : .visible
+  }
+
+  var body: some View {
+    RemoteRepositoriesBetaCardBody()
+  }
+
+  enum Mode: Equatable {
+    case hidden
+    case visible
+  }
+}
+
+private struct RemoteRepositoriesBetaCardBody: View {
+  @Shared(.appStorage("remoteRepositoriesBetaOnboardingDismissedAt"))
+  private var dismissedAt: Date = .distantPast
+
+  var body: some View {
+    SidebarCard(
+      onDismiss: { $dismissedAt.withLock { $0 = .now } },
+      content: {
+        VStack(alignment: .leading, spacing: 4) {
+          HStack(spacing: 6) {
+            Text("Remote repositories")
+              .font(.subheadline)
+              .fontWeight(.semibold)
+            BetaBadge()
+          }
+          Text(description)
+            .font(.caption)
+            .foregroundStyle(.secondary)
+        }
+      },
+      header: {
+        Image(systemName: "wifi")
+          .font(.title2)
+          .foregroundStyle(.teal)
+          .accessibilityHidden(true)
+      }
+    )
+  }
+
+  private var description: LocalizedStringKey {
+    """
+    Add a repository over SSH. Its git, agents, scripts, and terminal run on the \
+    host while Supacode renders locally.
+    """
+  }
+}
+
+/// Compact tinted "Beta" pill.
+private struct BetaBadge: View {
+  var body: some View {
+    Text("Beta")
+      .font(.caption2)
+      .fontWeight(.semibold)
+      .foregroundStyle(.teal)
+      .padding(.horizontal, 6)
+      .padding(.vertical, 2)
+      .background(.teal.opacity(0.15), in: .capsule)
+      .accessibilityLabel("Beta")
+  }
+}
diff --git a/supacode/Features/Repositories/Views/RepoSectionHeaderView.swift b/supacode/Features/Repositories/Views/RepoSectionHeaderView.swift
index d6c837a46..852cc01d1 100644
--- a/supacode/Features/Repositories/Views/RepoSectionHeaderView.swift
+++ b/supacode/Features/Repositories/Views/RepoSectionHeaderView.swift
@@ -6,6 +6,11 @@ struct RepoSectionHeaderView: View {
   let customTitle: String?
   let color: RepositoryColor?
   let isRemoving: Bool
+  /// `[user@]host[:port]` when the repository lives on an SSH host, else nil;
+  /// surfaces a `wifi` glyph beside the title, full value shown on hover.
+  var hostInfo: String?
+  /// Remote repository whose SSH listing is still resolving; shows a spinner.
+  var isResolving: Bool = false
 
   private var displayName: String {
     Repository.sidebarDisplayName(custom: customTitle, fallback: name)
@@ -13,11 +18,24 @@ struct RepoSectionHeaderView: View {
 
   var body: some View {
     HStack {
-      Text(displayName).foregroundStyle(color?.color ?? .secondary)
+      HStack(spacing: 4) {
+        Text(displayName).foregroundStyle(color?.color ?? .secondary)
+        if let hostInfo {
+          Image(systemName: "wifi")
+            .imageScale(.small)
+            .foregroundStyle(.secondary)
+            .help(hostInfo)
+            .accessibilityLabel("Remote host \(hostInfo)")
+        }
+      }
       if isRemoving {
         ProgressView()
           .controlSize(.small)
           .accessibilityLabel("Removing repository")
+      } else if isResolving {
+        ProgressView()
+          .controlSize(.mini)
+          .accessibilityLabel("Connecting to remote")
       }
     }
   }
diff --git a/supacode/Features/Repositories/Views/RepositoryCustomizationView.swift b/supacode/Features/Repositories/Views/RepositoryCustomizationView.swift
index b9d08dc8b..cc0a69d46 100644
--- a/supacode/Features/Repositories/Views/RepositoryCustomizationView.swift
+++ b/supacode/Features/Repositories/Views/RepositoryCustomizationView.swift
@@ -19,7 +19,7 @@ struct RepositoryCustomizationView: View {
           ColorSwatchRow(color: $store.color)
         }
       } header: {
-        Text("Customize Repository")
+        Text("Customize Appearance")
         Text("Override the sidebar title and tint for `\(store.defaultName)`.")
       }
       .headerProminence(.increased)
diff --git a/supacode/Features/Repositories/Views/SidebarHighlightSectionsView.swift b/supacode/Features/Repositories/Views/SidebarHighlightSectionsView.swift
index b258d90bf..072c8054a 100644
--- a/supacode/Features/Repositories/Views/SidebarHighlightSectionsView.swift
+++ b/supacode/Features/Repositories/Views/SidebarHighlightSectionsView.swift
@@ -39,7 +39,7 @@ struct SidebarHighlightSection: View {
 }
 
 extension SidebarStructure.HighlightKind {
-  fileprivate var indicatorColor: Color {
+  var indicatorColor: Color {
     switch self {
     case .pinned: .orange
     case .active: .blue
@@ -47,7 +47,9 @@ extension SidebarStructure.HighlightKind {
   }
 }
 
-private struct SidebarHighlightHeaderDot: View {
+/// Colored dot shown after a highlight section title and reused after each
+/// bucket label in the per-repo hoist summary line.
+struct SidebarHighlightHeaderDot: View {
   let color: Color
   @Environment(\.pixelLength) private var pixelLength
 
diff --git a/supacode/Features/Repositories/Views/SidebarItemView.swift b/supacode/Features/Repositories/Views/SidebarItemView.swift
index 107923156..80904305b 100644
--- a/supacode/Features/Repositories/Views/SidebarItemView.swift
+++ b/supacode/Features/Repositories/Views/SidebarItemView.swift
@@ -15,6 +15,9 @@ enum SidebarNestLayout {
 struct SidebarHighlightRepoTag: Equatable, Hashable, Sendable {
   let repoName: String
   let repoColor: RepositoryColor?
+  /// `[user@]host[:port]` when the repo is remote, else nil; shown as `· host`
+  /// plus a `wifi` glyph in the subtitle.
+  let hostInfo: String?
 }
 
 struct SidebarItemView: View {
@@ -42,7 +45,9 @@ struct SidebarItemView: View {
       isPinned: store.isPinned,
       hideSubtitle: hideSubtitle,
       hideSubtitleOnMatch: hideSubtitleOnMatch,
-      highlightSubtitle: highlightSubtitle
+      highlightSubtitle: highlightSubtitle,
+      customTitle: store.customTitle,
+      customTint: store.customTint
     )
 
     Label {
@@ -51,6 +56,7 @@ struct SidebarItemView: View {
           name: resolved.name,
           subtitle: resolved.subtitle,
           accent: resolved.accent,
+          customTint: store.customTint,
           isLifecycleBusy: store.lifecycle.isBusy,
           isTaskRunning: store.isTaskRunning
         )
@@ -65,6 +71,7 @@ struct SidebarItemView: View {
     } icon: {
       IconView(
         isFolder: store.kind == .folder,
+        isRemote: store.isRemote,
         isMissing: store.isMissing,
         branchName: store.branchName,
         pullRequest: store.pullRequest,
@@ -84,10 +91,10 @@ struct ResolvedRowDisplay: Equatable {
     case none
     /// Standard per-repo subtitle. Rendered in the row's accent color.
     case plain(String)
-    /// Highlight-section subtitle: `repo · trail`. `repo` paints with
-    /// `repoColor`, `trail` with the row's accent. `trail == nil` collapses
-    /// to just the repo name.
-    case highlight(repo: String, repoColor: RepositoryColor?, trail: String?)
+    /// Highlight-section subtitle: `repo · host · trail`. `repo` paints with
+    /// `repoColor`, `trail` with the row's accent; `hostInfo` (when set) inserts
+    /// `· host` plus a `wifi` glyph. `trail == nil` collapses to just the repo.
+    case highlight(repo: String, repoColor: RepositoryColor?, trail: String?, hostInfo: String?)
   }
 
   let name: String
@@ -102,30 +109,38 @@ struct ResolvedRowDisplay: Equatable {
     isPinned: Bool,
     hideSubtitle: Bool,
     hideSubtitleOnMatch: Bool,
-    highlightSubtitle: SidebarHighlightRepoTag? = nil
+    highlightSubtitle: SidebarHighlightRepoTag? = nil,
+    customTitle: String? = nil,
+    customTint: RepositoryColor? = nil
   ) {
     self.accent =
       if isMainWorktree { .main } else if isPinned { .pinned } else { .default }
 
+    // User override (trimmed) takes precedence over derived names.
+    let resolvedCustom = SidebarDisplayName.resolved(custom: customTitle, fallback: nil)
+    let hasCustomTitle = resolvedCustom != nil
+
     if kind == .folder {
-      self.name = branchName
-      // Folder rows ARE the repo, so a repo prefix would just repeat the title.
+      self.name = resolvedCustom ?? branchName
+      // Folder rows ARE the repo; a remote folder's `wifi` glyph rides the title
+      // line (via `TitleView`), so there's no subtitle.
       self.subtitle = .none
       return
     }
 
     let resolvedWorktreeName = worktreeName ?? "Default"
     let effectiveWorktreeName = resolvedWorktreeName.isEmpty ? branchName : resolvedWorktreeName
-    self.name = branchName
+    self.name = resolvedCustom ?? branchName
 
     let branchLastComponent = branchName.split(separator: "/").last.map(String.init) ?? branchName
     let isMatch = effectiveWorktreeName == branchLastComponent
+    // Once a user types a custom title, they've lost the visual cue that the auto-derived name was
+    // providing, so we always render the subtitle even when it would otherwise collapse on match.
+    let shouldHideOnMatch = hideSubtitleOnMatch && !hasCustomTitle && isMatch
 
     if let highlightSubtitle {
-      // Hide-on-match drop mirrors the per-repo subtitle path so a row
-      // doesn't change its disambiguation policy across hoisting.
       let trail: String?
-      if hideSubtitleOnMatch && isMatch {
+      if shouldHideOnMatch {
         trail = nil
       } else if isMainWorktree {
         trail = "Default"
@@ -137,12 +152,13 @@ struct ResolvedRowDisplay: Equatable {
       self.subtitle = .highlight(
         repo: highlightSubtitle.repoName,
         repoColor: highlightSubtitle.repoColor,
-        trail: trail
+        trail: trail,
+        hostInfo: highlightSubtitle.hostInfo
       )
       return
     }
 
-    if hideSubtitle || (hideSubtitleOnMatch && isMatch) {
+    if hideSubtitle || shouldHideOnMatch {
       self.subtitle = .none
     } else {
       self.subtitle = .plain(effectiveWorktreeName)
@@ -235,6 +251,8 @@ private struct TitleView: View, Equatable {
   let name: String
   let subtitle: ResolvedRowDisplay.Subtitle
   let accent: WorktreeAccent
+  /// User-supplied row tint. When set, paints the title; otherwise the title uses the default.
+  let customTint: RepositoryColor?
   let isLifecycleBusy: Bool
   let isTaskRunning: Bool
   // `==` ignores @Environment; SwiftUI tracks env changes separately.
@@ -244,6 +262,7 @@ private struct TitleView: View, Equatable {
     lhs.name == rhs.name
       && lhs.subtitle == rhs.subtitle
       && lhs.accent == rhs.accent
+      && lhs.customTint == rhs.customTint
       && lhs.isLifecycleBusy == rhs.isLifecycleBusy
       && lhs.isTaskRunning == rhs.isTaskRunning
   }
@@ -253,10 +272,14 @@ private struct TitleView: View, Equatable {
     let isEmphasized = backgroundProminence == .increased
     let accentStyle = accent.shapeStyle(emphasized: isEmphasized)
     VStack(alignment: .leading, spacing: 0) {
-      Text(name)
+      let titleText = Text(name)
         .font(.body)
         .lineLimit(1)
-        .shimmer(isActive: isBusy)
+      if let customTint, !isEmphasized {
+        titleText.foregroundStyle(customTint.color).shimmer(isActive: isBusy)
+      } else {
+        titleText.shimmer(isActive: isBusy)
+      }
       switch subtitle {
       case .none:
         EmptyView()
@@ -265,18 +288,26 @@ private struct TitleView: View, Equatable {
           .font(.footnote)
           .foregroundStyle(accentStyle)
           .lineLimit(1)
-      case .highlight(let repo, let repoColor, let trail):
+      case .highlight(let repo, let repoColor, let trail, let hostInfo):
         let repoStyle: AnyShapeStyle =
           isEmphasized
           ? AnyShapeStyle(.secondary)
           : repoColor.map { AnyShapeStyle($0.color) } ?? AnyShapeStyle(.secondary)
-        // `.layoutPriority(1)` on the repo makes the trail yield first under
-        // a narrow sidebar so the colored repo tag survives truncation.
+        // `.layoutPriority(1)` on the repo / host makes the trail yield first under a narrow sidebar.
         HStack(spacing: 0) {
           Text(repo)
             .foregroundStyle(repoStyle)
             .lineLimit(1)
             .layoutPriority(1)
+          if let hostInfo {
+            Image(systemName: "wifi")
+              .imageScale(.small)
+              .foregroundStyle(.secondary)
+              .help(hostInfo)
+              .accessibilityLabel("Remote host \(hostInfo)")
+              .padding(.leading, 3)
+              .layoutPriority(1)
+          }
           if let trail {
             Text(" · ")
               .foregroundStyle(.secondary)
@@ -296,6 +327,7 @@ private struct TitleView: View, Equatable {
 
 private struct IconView: View {
   let isFolder: Bool
+  let isRemote: Bool
   let isMissing: Bool
   let branchName: String
   let pullRequest: GithubPullRequest?
@@ -309,6 +341,7 @@ private struct IconView: View {
     )
     IconContent(
       isFolder: isFolder,
+      isRemote: isRemote,
       isMissing: isMissing,
       icon: SidebarPullRequestIcon.resolve(display.pullRequest),
       checkBadgeState: resolveCheckBadgeState(display.pullRequest),
@@ -336,6 +369,7 @@ enum IconRowState: Equatable {
 
 private struct IconContent: View, Equatable {
   let isFolder: Bool
+  let isRemote: Bool
   let isMissing: Bool
   let icon: SidebarPullRequestIcon
   let checkBadgeState: SidebarCheckBadgeState?
@@ -345,6 +379,7 @@ private struct IconContent: View, Equatable {
 
   static func == (lhs: Self, rhs: Self) -> Bool {
     lhs.isFolder == rhs.isFolder
+      && lhs.isRemote == rhs.isRemote
       && lhs.isMissing == rhs.isMissing
       && lhs.icon == rhs.icon
       && lhs.checkBadgeState == rhs.checkBadgeState
@@ -438,26 +473,32 @@ private struct TrailingView: View {
   let showsPullRequestInfo: Bool
 
   var body: some View {
-    if let shortcutHint {
-      Text(shortcutHint)
-        .font(.caption)
-        .foregroundStyle(.secondary)
-    } else {
-      let display = WorktreePullRequestDisplay(
-        worktreeName: store.branchName,
-        pullRequest: showsPullRequestInfo ? store.pullRequest : nil,
-      )
-      let prText = display.pullRequestBadgeStyle?.text
-      let agents = store.agents
-      let scriptColors = store.runningScripts.map(\.tint)
-      let showsNotificationIndicator = store.hasUnseenNotifications
-      let notifications = Array(store.notifications)
-      let added = store.addedLines ?? 0
-      let removed = store.removedLines ?? 0
-      let hasStats = added + removed > 0
-      let hasStatus = !scriptColors.isEmpty || showsNotificationIndicator
-
+    let hasHint = shortcutHint != nil
+    let display = WorktreePullRequestDisplay(
+      worktreeName: store.branchName,
+      pullRequest: showsPullRequestInfo ? store.pullRequest : nil,
+    )
+    let prText = display.pullRequestBadgeStyle?.text
+    let agents = store.agents
+    let scriptColors = store.runningScripts.map(\.tint)
+    let showsNotificationIndicator = store.hasUnseenNotifications
+    let notifications = Array(store.notifications)
+    let added = store.addedLines ?? 0
+    let removed = store.removedLines ?? 0
+    let hasStats = added + removed > 0
+    let hasStatus = !scriptColors.isEmpty || showsNotificationIndicator
+
+    // Cross-fade via opacity so flipping ⌘ doesn't snap the row.
+    ZStack(alignment: .trailing) {
       HStack(spacing: 6) {
+        if store.kind == .folder, let host = store.host {
+          Image(systemName: "wifi")
+            .imageScale(.small)
+            .font(.subheadline)
+            .foregroundStyle(.secondary)
+            .help(host.displayAuthority)
+            .accessibilityLabel("Remote host \(host.displayAuthority)")
+        }
         if hasStats {
           DiffStatsContent(addedLines: added, removedLines: removed)
             .equatable()
@@ -481,7 +522,15 @@ private struct TrailingView: View {
       }
       // Title takes the squeeze under narrow widths, not the counters.
       .fixedSize(horizontal: true, vertical: false)
+      .opacity(hasHint ? 0 : 1)
+      .allowsHitTesting(!hasHint)
+
+      Text(shortcutHint ?? "")
+        .font(.caption)
+        .foregroundStyle(.secondary)
+        .opacity(hasHint ? 1 : 0)
     }
+    .animation(.easeInOut(duration: TerminalTabBarMetrics.fadeAnimationDuration), value: hasHint)
   }
 }
 
diff --git a/supacode/Features/Repositories/Views/SidebarItemsView.swift b/supacode/Features/Repositories/Views/SidebarItemsView.swift
index c317ed27a..4af19d641 100644
--- a/supacode/Features/Repositories/Views/SidebarItemsView.swift
+++ b/supacode/Features/Repositories/Views/SidebarItemsView.swift
@@ -635,37 +635,16 @@ private struct SidebarItemContextMenu: View {
     let deleteShortcut = AppShortcuts.deleteWorktree.effective(from: overrides)
     let isAllFoldersBulk = isAllFoldersBulk
 
+    // Open actions resolve local paths through Finder / editors, which can't
+    // reach a remote SSH host, so they're disabled (but still shown, matching
+    // the toolbar and menu bar) for a remote row.
     if !isBulkSelection, !worktree.isMissing {
       openActions(overrides: overrides)
+        .disabled(worktree.host != nil)
       Divider()
     }
 
-    // Folder synthetic rows pass `isMainWorktree` by geometry but are
-    // pinnable; git "main" rows still aren't.
-    let pinnableRows = contextRows.filter { !$0.isMainWorktree || $0.isFolder }
-    if !pinnableRows.isEmpty {
-      let allPinned = pinnableRows.allSatisfy(\.isPinned)
-      let allFolders = pinnableRows.allSatisfy(\.isFolder)
-      // Folder-only selection reads "Pin Folder" / "Pin Folders"; mixed or
-      // git-only fall back to "Worktree" so the label stays accurate.
-      let noun = allFolders ? "Folder" : "Worktree"
-      if allPinned {
-        let label = isBulkSelection ? "Unpin \(noun)s" : "Unpin \(noun)"
-        Button(label, systemImage: "pin.slash") {
-          for pinnableRow in pinnableRows {
-            togglePin(for: pinnableRow.id, isPinned: true)
-          }
-        }
-      } else {
-        let label = isBulkSelection ? "Pin \(noun)s" : "Pin \(noun)"
-        Button(label, systemImage: "pin") {
-          for pinnableRow in pinnableRows where !pinnableRow.isPinned {
-            togglePin(for: pinnableRow.id, isPinned: false)
-          }
-        }
-      }
-      Divider()
-    }
+    pinActions(contextRows: contextRows, isBulkSelection: isBulkSelection)
 
     if !isBulkSelection {
       Button("Copy as Pathname", systemImage: "doc.on.doc") {
@@ -691,15 +670,57 @@ private struct SidebarItemContextMenu: View {
       }
       Divider()
       if rowIsFolder {
+        // Folder rows render through SidebarItemRow, which reads customization from the per-row
+        // bucket Item. Route through the same worktree path so the folder row picks up the title
+        // / color the user picks (section.title would only tint a folder-section header, but
+        // folder sections render with an empty header).
+        Button("Customize Appearance…", systemImage: "paintbrush") {
+          store.send(.requestCustomizeWorktree(rowID, repositoryID))
+        }
+        .help("Set a custom title or color")
         // Folder rows have no section ellipsis menu, so Settings lives here.
         Button("Folder Settings…", systemImage: "gear") {
           store.send(.openRepositorySettings(repositoryID))
         }
         .help("Open folder settings")
+        // Remote folders have no section header either, so the connection editor
+        // (offered on a git remote's section menu) lives here for them.
+        if worktree.host != nil {
+          Button("Edit Connection…", systemImage: "wifi") {
+            store.send(.requestEditRemoteRepository(repositoryID))
+          }
+          .help("Edit the SSH server, port, user, or path")
+        }
+        Divider()
+      } else if let row = contextRows.first,
+        !row.isMainWorktree,
+        !row.lifecycle.isPending
+      {
+        Button("Customize Appearance…", systemImage: "paintbrush") {
+          store.send(.requestCustomizeWorktree(rowID, repositoryID))
+        }
+        .help("Set a custom title or color")
         Divider()
       }
     }
 
+    archiveAndDeleteActions(
+      contextRows: contextRows,
+      isBulkSelection: isBulkSelection,
+      isAllFoldersBulk: isAllFoldersBulk,
+      archiveShortcut: archiveShortcut,
+      deleteShortcut: deleteShortcut
+    )
+  }
+
+  @ViewBuilder
+  private func archiveAndDeleteActions(
+    contextRows: [SidebarItemFeature.State],
+    isBulkSelection: Bool,
+    isAllFoldersBulk: Bool,
+    archiveShortcut: AppShortcut?,
+    deleteShortcut: AppShortcut?
+  ) -> some View {
     let archiveTargets =
       contextRows
       .filter { !$0.isMainWorktree && $0.lifecycle == .idle }
@@ -727,7 +748,16 @@ private struct SidebarItemContextMenu: View {
       }
       .appKeyboardShortcut(archiveShortcut)
     }
-    if !deleteTargets.isEmpty {
+    if !isBulkSelection, rowIsFolder, worktree.host != nil {
+      // A remote folder is the remote repository; its row has no section header,
+      // so removal lives here and must drop the config (the local delete
+      // pipeline only prunes local roots and would leave the config to reappear).
+      Button("Remove Remote Repository…", systemImage: "trash", role: .destructive) {
+        store.send(.requestDeleteRepository(repositoryID))
+      }
+      .help("Remove this remote repository (remote files are untouched)")
+      .appKeyboardShortcut(deleteShortcut)
+    } else if !deleteTargets.isEmpty {
       let deleteLabel =
         isBulkSelection
         ? (isAllFoldersBulk ? "Remove Folders…" : "Delete Worktrees…")
@@ -739,6 +769,38 @@ private struct SidebarItemContextMenu: View {
     }
   }
 
+  @ViewBuilder
+  private func pinActions(contextRows: [SidebarItemFeature.State], isBulkSelection: Bool) -> some View {
+    // Folder synthetic rows pass `isMainWorktree` by geometry but are pinnable; git "main" still
+    // aren't. Pending rows can't pin (reducer would no-op on the unresolved ID).
+    let pinnableRows = contextRows.filter {
+      (!$0.isMainWorktree || $0.isFolder) && !$0.lifecycle.isPending
+    }
+    if !pinnableRows.isEmpty {
+      let allPinned = pinnableRows.allSatisfy(\.isPinned)
+      let allFolders = pinnableRows.allSatisfy(\.isFolder)
+      // Folder-only selection reads "Pin Folder" / "Pin Folders"; mixed or
+      // git-only fall back to "Worktree" so the label stays accurate.
+      let noun = allFolders ? "Folder" : "Worktree"
+      if allPinned {
+        let label = isBulkSelection ? "Unpin \(noun)s" : "Unpin \(noun)"
+        Button(label, systemImage: "pin.slash") {
+          for pinnableRow in pinnableRows {
+            togglePin(for: pinnableRow.id, isPinned: true)
+          }
+        }
+      } else {
+        let label = isBulkSelection ? "Pin \(noun)s" : "Pin \(noun)"
+        Button(label, systemImage: "pin") {
+          for pinnableRow in pinnableRows where !pinnableRow.isPinned {
+            togglePin(for: pinnableRow.id, isPinned: false)
+          }
+        }
+      }
+      Divider()
+    }
+  }
+
   @ViewBuilder
   private func openActions(overrides: [AppShortcutID: AppShortcutOverride]) -> some View {
     let availableActions = OpenWorktreeAction.availableCases.filter { $0 != .finder }
@@ -760,7 +822,7 @@ private struct SidebarItemContextMenu: View {
         Button {
           store.send(.contextMenuOpenWorktree(worktree.id, action))
         } label: {
-          OpenWorktreeActionMenuLabelView(action: action, shortcutHint: nil)
+          OpenWorktreeActionMenuLabelView(action: action)
         }
         .help("Open with \(action.labelTitle)")
       }
diff --git a/supacode/Features/Repositories/Views/SidebarListView.swift b/supacode/Features/Repositories/Views/SidebarListView.swift
index fdbba4d20..469356bf7 100644
--- a/supacode/Features/Repositories/Views/SidebarListView.swift
+++ b/supacode/Features/Repositories/Views/SidebarListView.swift
@@ -27,7 +27,7 @@ struct SidebarListView: View {
       get: { currentSelections },
       set: { newValue in
         guard newValue != currentSelections else { return }
-        store.send(.selectionChanged(newValue))
+        store.send(.selectionChanged(newValue, focusTerminal: true))
       }
     )
     let pendingSidebarReveal = state.pendingSidebarReveal
@@ -140,7 +140,7 @@ struct SidebarListView: View {
       switch section {
       case .repository(let repositoryID, _),
         .folder(let repositoryID, _),
-        .failedRepository(let repositoryID, _, _, _):
+        .failedRepository(let repositoryID, _, _, _, _):
         if let repoIndex = repoIDs.firstIndex(of: repositoryID) {
           repoOffsets.insert(repoIndex)
         }
@@ -158,7 +158,7 @@ struct SidebarListView: View {
       switch section {
       case .repository(let repositoryID, _),
         .folder(let repositoryID, _),
-        .failedRepository(let repositoryID, _, _, _):
+        .failedRepository(let repositoryID, _, _, _, _):
         repoDestination = repoIDs.firstIndex(of: repositoryID) ?? repoIDs.count
       case .highlight, .placeholder:
         // Dropping above the highlight prefix collapses to "before the first repo".
@@ -212,12 +212,13 @@ private struct SidebarSectionDispatcher: View {
         shortcutHintByID: shortcutHintByID
       )
       .moveDisabled(true)
-    case .failedRepository(let repositoryID, let rootURL, let customTitle, let color):
+    case .failedRepository(let repositoryID, let rootURL, let customTitle, let color, let isRemote):
       SidebarFailedRepositorySection(
         repositoryID: repositoryID,
         rootURL: rootURL,
         customTitle: customTitle,
         color: color,
+        isRemote: isRemote,
         store: store
       )
     case .folder(let repositoryID, let rowID):
@@ -242,6 +243,7 @@ private struct SidebarSectionDispatcher: View {
         SidebarGitRepositorySection(
           repository: repository,
           groups: groups,
+          hoistSummary: structure.hoistSummaryByRepositoryID[repositoryID],
           shortcutHintByID: shortcutHintByID,
           selectedWorktreeIDs: selectedWorktreeIDs,
           store: store,
@@ -255,12 +257,16 @@ private struct SidebarSectionDispatcher: View {
 private struct SidebarGitRepositorySection: View {
   let repository: Repository
   let groups: [SidebarItemGroup]
+  /// Non-nil when one or more of this repo's rows were hoisted into the
+  /// highlight sections; rendered as a muted summary line under the rows.
+  let hoistSummary: SidebarHoistSummary?
   let shortcutHintByID: [Worktree.ID: String]
   let selectedWorktreeIDs: Set<Worktree.ID>
   @Bindable var store: StoreOf<RepositoriesFeature>
   let terminalManager: WorktreeTerminalManager
   var body: some View {
     let isRemovingRepository = store.state.isRemovingRepository(repository)
+    let isResolvingRemote = store.state.resolvingRemoteRepositoryIDs.contains(repository.id)
     let section = store.state.sidebar.sections[repository.id]
     Section(isExpanded: repositoryExpansionBinding) {
       SidebarItemsView(
@@ -271,18 +277,28 @@ private struct SidebarGitRepositorySection: View {
         store: store,
         terminalManager: terminalManager
       )
+      if let hoistSummary {
+        SidebarHoistSummaryRow(
+          repositoryName: Repository.sidebarDisplayName(custom: section?.title, fallback: repository.name),
+          summary: hoistSummary,
+          store: store
+        )
+      }
     } header: {
       RepoSectionHeaderView(
         name: repository.name,
         customTitle: section?.title,
         color: section?.color,
-        isRemoving: isRemovingRepository
+        isRemoving: isRemovingRepository,
+        hostInfo: repository.host?.displayAuthority,
+        isResolving: isResolvingRemote
       )
     }
     .sectionActions {
       SidebarSectionActionsView(
         repositoryID: repository.id,
         isRemovingRepository: isRemovingRepository,
+        isRemote: repository.host != nil,
         store: store
       )
     }
@@ -298,27 +314,95 @@ private struct SidebarGitRepositorySection: View {
   }
 }
 
+/// Muted, unselectable line under a repo's rows summarizing how many were
+/// hoisted into the Pinned / Active sections, with a click that scrolls up to
+/// them. Carries no `.tag`, so it stays out of selection and arrow-key
+/// navigation; lives inside the `Section` body so it folds away when the repo
+/// section is collapsed.
+private struct SidebarHoistSummaryRow: View {
+  let repositoryName: String
+  let summary: SidebarHoistSummary
+  let store: StoreOf<RepositoriesFeature>
+
+  var body: some View {
+    Button {
+      store.send(.revealHoistedWorktreeInSidebar(summary.revealTarget))
+    } label: {
+      HStack(spacing: 8) {
+        if summary.pinnedCount > 0 {
+          SidebarHoistSummarySegment(kind: .pinned, count: summary.pinnedCount)
+        }
+        if summary.activeCount > 0 {
+          SidebarHoistSummarySegment(kind: .active, count: summary.activeCount)
+        }
+        Spacer(minLength: 0)
+      }
+      .font(.caption)
+      .foregroundStyle(.secondary)
+      .lineLimit(1)
+      .contentShape(.interaction, .rect)
+    }
+    .buttonStyle(.plain)
+    .listRowInsets(.leading, 0)
+    .listRowInsets(.trailing, 4)
+    .listRowInsets(.vertical, 4)
+    .moveDisabled(true)
+    .help("Show \(repositoryName)'s pinned and active worktrees")
+    .accessibilityLabel("\(summary.label) above. Scroll to them.")
+  }
+}
+
+/// One bucket of the hoist summary: its count followed by the same colored dot
+/// the matching highlight section header shows.
+private struct SidebarHoistSummarySegment: View {
+  let kind: SidebarStructure.HighlightKind
+  let count: Int
+
+  var body: some View {
+    HStack(spacing: 4) {
+      Text("+\(count) \(kind.summaryNoun)")
+      SidebarHighlightHeaderDot(color: kind.indicatorColor)
+    }
+  }
+}
+
 private struct SidebarSectionActionsView: View {
   let repositoryID: Repository.ID
   let isRemovingRepository: Bool
+  /// Remote (SSH) repositories hide the local-only "Repository Settings…" and
+  /// route Remove to `removeRemoteRepository` (drops the config; remote files
+  /// untouched). Worktree creation (`+`) works for remote repos too.
+  var isRemote: Bool = false
   let store: StoreOf<RepositoriesFeature>
 
   var body: some View {
     Menu {
-      Button("Customize Repository…", systemImage: "paintbrush") {
+      Button("Customize Appearance…", systemImage: "paintbrush") {
         store.send(.requestCustomizeRepository(repositoryID))
       }
-      .help("Customize sidebar title and color")
+      .help("Set a custom title or color")
       .disabled(isRemovingRepository)
-      Button("Repository Settings…", systemImage: "gear") {
-        store.send(.openRepositorySettings(repositoryID))
+      if isRemote {
+        Button("Edit Connection…", systemImage: "wifi") {
+          store.send(.requestEditRemoteRepository(repositoryID))
+        }
+        .help("Edit the SSH server, port, user, or path")
+        .disabled(isRemovingRepository)
+      } else {
+        Button("Repository Settings…", systemImage: "gear") {
+          store.send(.openRepositorySettings(repositoryID))
+        }
+        .help("Repository Settings")
       }
-      .help("Repository Settings")
       Divider()
-      Button("Remove Repository…", systemImage: "folder.badge.minus", role: .destructive) {
+      Button(
+        isRemote ? "Remove Remote Repository…" : "Remove Repository…",
+        systemImage: "folder.badge.minus",
+        role: .destructive
+      ) {
         store.send(.requestDeleteRepository(repositoryID))
       }
-      .help("Remove Repository")
+      .help(isRemote ? "Remove this remote repository (remote files are untouched)" : "Remove Repository")
       .disabled(isRemovingRepository)
     } label: {
       Image(systemName: "ellipsis")
@@ -349,8 +433,15 @@ private struct SidebarFailedRepositorySection: View {
   let rootURL: URL
   let customTitle: String?
   let color: RepositoryColor?
+  /// A disconnected SSH repo: route Remove to the remote config store and offer
+  /// "Edit Connection…" to fix a bad host/path, rather than the local-roots flow.
+  let isRemote: Bool
   let store: StoreOf<RepositoriesFeature>
 
+  private func removeFailedRepository() {
+    store.send(isRemote ? .requestDeleteRepository(repositoryID) : .requestRemoveFailedRepository(repositoryID))
+  }
+
   var body: some View {
     let standardizedRootURL = rootURL.standardizedFileURL
     let fallbackName = Repository.name(for: standardizedRootURL)
@@ -360,7 +451,7 @@ private struct SidebarFailedRepositorySection: View {
       FailedRepositoryRow(
         name: displayName,
         path: path,
-        removeRepository: { store.send(.requestRemoveFailedRepository(repositoryID)) }
+        removeRepository: removeFailedRepository
       )
       .tag(SidebarSelection.failedRepository(repositoryID))
       .moveDisabled(true)
@@ -369,16 +460,31 @@ private struct SidebarFailedRepositorySection: View {
         name: fallbackName,
         customTitle: customTitle,
         color: color,
-        isRemoving: false
+        isRemoving: false,
+        hostInfo: store.state.repositories[id: repositoryID]?.host?.displayAuthority
       )
     }
     .sectionActions {
       // No `+`: the repo isn't loadable, so worktree create is meaningless.
       Menu {
-        Button("Remove Repository…", systemImage: "folder.badge.minus", role: .destructive) {
-          store.send(.requestRemoveFailedRepository(repositoryID))
+        if isRemote {
+          Button("Edit Connection…", systemImage: "wifi") {
+            store.send(.requestEditRemoteRepository(repositoryID))
+          }
+          .help("Edit the SSH server, port, user, or path")
+        }
+        Button(
+          isRemote ? "Remove Remote Repository…" : "Remove Repository…",
+          systemImage: "folder.badge.minus",
+          role: .destructive
+        ) {
+          removeFailedRepository()
         }
-        .help("Remove this repository from Supacode. Files on disk are untouched.")
+        .help(
+          isRemote
+            ? "Remove this remote repository (remote files are untouched)"
+            : "Remove this repository from Supacode. Files on disk are untouched."
+        )
       } label: {
         Image(systemName: "ellipsis")
           .accessibilityLabel("Options")
diff --git a/supacode/Features/Repositories/Views/SidebarView.swift b/supacode/Features/Repositories/Views/SidebarView.swift
index b5311da3b..a2fae7aa6 100644
--- a/supacode/Features/Repositories/Views/SidebarView.swift
+++ b/supacode/Features/Repositories/Views/SidebarView.swift
@@ -38,8 +38,19 @@ struct SidebarView: View {
     )
     .toolbar {
       ToolbarItem(placement: .primaryAction) {
-        Button {
-          store.send(.setOpenPanelPresented(true))
+        Menu {
+          Button {
+            store.send(.setOpenPanelPresented(true))
+          } label: {
+            Label("Local Repository or Folder…", systemImage: "laptopcomputer")
+          }
+          .help("Add a local repository or folder (\(openRepo?.display ?? "none"))")
+          Button {
+            store.send(.requestAddRemoteRepository)
+          } label: {
+            Label("Remote Repository or Folder…", systemImage: "wifi")
+          }
+          .help("Add a repository or folder on an SSH host")
         } label: {
           Label {
             Text("Add…")
@@ -49,10 +60,14 @@ struct SidebarView: View {
               .accessibilityHidden(true)
           }
         }
+        .menuIndicator(.hidden)
         .labelStyle(.iconOnly)
-        .help("Add Repository or Folder (\(openRepo?.display ?? "none"))")
+        .help("Add Repository, Folder, or Remote")
       }
     }
+    .sheet(item: $store.scope(state: \.remoteConnectionForm, action: \.remoteConnectionForm)) { formStore in
+      RemoteConnectionFormView(store: formStore)
+    }
     .focusedSceneAction(
       \.confirmWorktreeAction,
       enabled: confirmAlert != nil,
diff --git a/supacode/Features/Repositories/Views/ToolbarStatusView.swift b/supacode/Features/Repositories/Views/ToolbarStatusView.swift
index 432e1772b..a85d70c41 100644
--- a/supacode/Features/Repositories/Views/ToolbarStatusView.swift
+++ b/supacode/Features/Repositories/Views/ToolbarStatusView.swift
@@ -50,7 +50,7 @@ private struct MotivationalStatusView: View {
           .foregroundStyle(style.color)
           .font(.callout)
           .accessibilityHidden(true)
-        Text("\(context.date, format: .dateTime.hour().minute()) – Open Command Palette (⌘P)")
+        Text("\(context.date, format: .dateTime.hour().minute()) – Open Command Palette (⌘⇧P)")
           .font(.footnote)
           .monospaced()
           .foregroundStyle(.secondary)
diff --git a/supacode/Features/Repositories/Views/WorktreeCreationPromptView.swift b/supacode/Features/Repositories/Views/WorktreeCreationPromptView.swift
index 9586cc5be..99e634dd7 100644
--- a/supacode/Features/Repositories/Views/WorktreeCreationPromptView.swift
+++ b/supacode/Features/Repositories/Views/WorktreeCreationPromptView.swift
@@ -1,4 +1,6 @@
 import ComposableArchitecture
+import SupacodeSettingsFeature
+import SupacodeSettingsShared
 import SwiftUI
 
 struct WorktreeCreationPromptView: View {
@@ -35,6 +37,8 @@ struct WorktreeCreationPromptView: View {
         .disabled(store.isSelectedBaseRefLocal)
       }
 
+      WorktreeAppearanceSection(store: store)
+
       WorktreeOptionsSection(store: store)
     }
     .formStyle(.grouped)
@@ -63,6 +67,20 @@ struct WorktreeCreationPromptView: View {
     }
     .frame(minWidth: 420)
     .task { isBranchFieldFocused = true }
+    .dismissSystemColorPanelOnDisappear()
+  }
+}
+
+private struct WorktreeAppearanceSection: View {
+  @Bindable var store: StoreOf<WorktreeCreationPromptFeature>
+
+  var body: some View {
+    Section("Appearance", isExpanded: $store.showAppearanceOptions) {
+      TextField("Title", text: $store.title, prompt: Text(store.worktreeNamePlaceholder))
+      LabeledContent("Color") {
+        ColorSwatchRow(color: $store.color)
+      }
+    }
   }
 }
 
diff --git a/supacode/Features/Repositories/Views/WorktreeCustomizationView.swift b/supacode/Features/Repositories/Views/WorktreeCustomizationView.swift
new file mode 100644
index 000000000..a86b3b6a9
--- /dev/null
+++ b/supacode/Features/Repositories/Views/WorktreeCustomizationView.swift
@@ -0,0 +1,50 @@
+import ComposableArchitecture
+import SupacodeSettingsFeature
+import SupacodeSettingsShared
+import SwiftUI
+
+struct WorktreeCustomizationView: View {
+  @Bindable var store: StoreOf<WorktreeCustomizationFeature>
+  @FocusState private var isTitleFocused: Bool
+
+  var body: some View {
+    Form {
+      Section {
+        TextField("Title", text: $store.title, prompt: Text(store.defaultName))
+          .focused($isTitleFocused)
+          .onSubmit {
+            store.send(.saveButtonTapped)
+          }
+        LabeledContent("Color") {
+          ColorSwatchRow(color: $store.color)
+        }
+      } header: {
+        Text("Customize Appearance")
+        Text("Override the sidebar title and tint for `\(store.defaultName)`.")
+      }
+      .headerProminence(.increased)
+    }
+    .formStyle(.grouped)
+    .scrollBounceBehavior(.basedOnSize)
+    .safeAreaInset(edge: .bottom, spacing: 0) {
+      HStack {
+        Spacer()
+        Button("Cancel") {
+          store.send(.cancelButtonTapped)
+        }
+        .keyboardShortcut(.cancelAction)
+        .help("Cancel (Esc)")
+        Button("Save") {
+          store.send(.saveButtonTapped)
+        }
+        .keyboardShortcut(.defaultAction)
+        .help("Save (↩)")
+      }
+      .padding(.horizontal, 20)
+      .padding(.bottom, 20)
+    }
+    .frame(minWidth: 420)
+    .task { isTitleFocused = true }
+    .dismissSystemColorPanelOnDisappear()
+  }
+}
diff --git a/supacode/Features/Repositories/Views/WorktreeDetailTitleView.swift b/supacode/Features/Repositories/Views/WorktreeDetailTitleView.swift
index a5ccb6887..3500a6f1f 100644
--- a/supacode/Features/Repositories/Views/WorktreeDetailTitleView.swift
+++ b/supacode/Features/Repositories/Views/WorktreeDetailTitleView.swift
@@ -9,15 +9,23 @@ import SwiftUI
 
 enum WorktreeToolbarTitleContent: Hashable, Sendable {
   case git(GitPayload)
-  case folder(name: String)
+  case folder(name: String, tint: RepositoryColor?, hostInfo: String?)
 
   struct GitPayload: Hashable, Sendable {
+    /// Text rendered as the top-line headline. May be the literal branch name or the user's custom
+    /// title override; never used for accessibility ("Branch X") since custom titles aren't refs.
+    let displayTitle: String
+    /// Actual git ref name. Used by accessibility so screen readers announce the real branch.
     let branchName: String
     let repositoryName: String
     let repositoryColor: RepositoryColor?
     let worktreeSubtitle: String?
+    let worktreeTint: RepositoryColor?
     let accent: WorktreeAccent
     let rootURL: URL
+    /// `[user@]host[:port]` when the repository lives on an SSH host, else nil;
+    /// rendered as `· host` plus a `wifi` glyph in the subtitle.
+    let hostInfo: String?
   }
 }
 
@@ -77,29 +85,50 @@ private struct WorktreeToolbarTitleBody: View {
       .frame(width: 24, height: 24)
       VStack(alignment: .leading, spacing: 0) {
         switch content {
-        case .folder(let name):
-          Text(name)
-            .font(.callout.weight(.semibold))
-            .lineLimit(1)
-            .truncationMode(.middle)
+        case .folder(let name, let tint, let hostInfo):
+          HStack(spacing: 4) {
+            Text(name)
+              .font(.callout.weight(.semibold))
+              .foregroundStyle(tint?.color ?? .primary)
+              .lineLimit(1)
+              .truncationMode(.middle)
+            if let hostInfo {
+              Image(systemName: "wifi")
+                .imageScale(.small)
+                .foregroundStyle(.secondary)
+                .help(hostInfo)
+                .accessibilityHidden(true)
+            }
+          }
         case .git(let payload):
-          Text(payload.branchName)
+          Text(payload.displayTitle)
             .font(.callout.weight(.semibold))
+            .foregroundStyle(payload.worktreeTint?.color ?? .primary)
             .lineLimit(1)
             .truncationMode(.middle)
           let repoText = Text(payload.repositoryName)
             .foregroundStyle(payload.repositoryColor?.color ?? .secondary)
-          let line: Text =
-            if let worktreeSubtitle = payload.worktreeSubtitle {
-              repoText
-                + Text(" · ").foregroundStyle(.secondary)
-                + Text(worktreeSubtitle).foregroundStyle(payload.accent.shapeStyle(emphasized: false))
-            } else {
-              repoText
+          let accentStyle = AnyShapeStyle(payload.accent.shapeStyle(emphasized: false))
+          let trail: Text? = payload.worktreeSubtitle.map { worktreeSubtitle in
+            Text(" · ").foregroundStyle(.secondary)
+              + Text(worktreeSubtitle).foregroundStyle(accentStyle)
+          }
+          HStack(spacing: 0) {
+            repoText
+            if let hostInfo = payload.hostInfo {
+              Image(systemName: "wifi")
+                .imageScale(.small)
+                .foregroundStyle(.secondary)
+                .help(hostInfo)
+                .accessibilityHidden(true)
+                .padding(.leading, 3)
             }
-          line
-            .font(.footnote)
-            .lineLimit(1)
+            if let trail {
+              trail
+            }
+          }
+          .font(.footnote)
+          .lineLimit(1)
         }
       }
     }
@@ -110,7 +139,7 @@ private struct WorktreeToolbarTitleBody: View {
 
   private var accessibilityLabel: String {
     switch content {
-    case .folder(let name):
+    case .folder(let name, _, _):
       return "Folder \(name)"
     case .git(let payload):
       let suffix = payload.worktreeSubtitle.map { ", worktree \($0)" } ?? ""
@@ -165,12 +194,15 @@ enum GitHubOwnerAvatar {
       WorktreeToolbarTitleBody(
         content: .git(
           .init(
+            displayTitle: "sbertix/319-toolbar-details",
             branchName: "sbertix/319-toolbar-details",
             repositoryName: "supacode",
             repositoryColor: .blue,
             worktreeSubtitle: "319-toolbar-details",
+            worktreeTint: nil,
             accent: .pinned,
-            rootURL: supacodeRepoRoot
+            rootURL: supacodeRepoRoot,
+            hostInfo: nil
           )
         )
       )
@@ -184,12 +216,15 @@ enum GitHubOwnerAvatar {
       WorktreeToolbarTitleBody(
         content: .git(
           .init(
+            displayTitle: "main",
             branchName: "main",
             repositoryName: "supacode",
             repositoryColor: .blue,
             worktreeSubtitle: "Default",
+            worktreeTint: nil,
             accent: .main,
-            rootURL: URL(fileURLWithPath: "/tmp/preview")
+            rootURL: URL(fileURLWithPath: "/tmp/preview"),
+            hostInfo: nil
           )
         )
       )
@@ -200,7 +235,7 @@ enum GitHubOwnerAvatar {
 #Preview("Folder") {
   Text("").toolbar {
     ToolbarItem {
-      WorktreeToolbarTitleBody(content: .folder(name: "Documents"))
+      WorktreeToolbarTitleBody(content: .folder(name: "Documents", tint: nil, hostInfo: nil))
     }
   }.frame(width: 600, height: 600)
 }
diff --git a/supacode/Features/Repositories/Views/WorktreeDetailView.swift b/supacode/Features/Repositories/Views/WorktreeDetailView.swift
index d7c9d6d4a..c00adb6c1 100644
--- a/supacode/Features/Repositories/Views/WorktreeDetailView.swift
+++ b/supacode/Features/Repositories/Views/WorktreeDetailView.swift
@@ -13,7 +13,6 @@ import SwiftUI
 struct WorktreeDetailView: View {
   @Bindable var store: StoreOf<AppFeature>
   let terminalManager: WorktreeTerminalManager
-  @Environment(CommandKeyObserver.self) private var commandKeyObserver
   @Shared(.appStorage("worktreeRowHideSubtitleOnMatch")) private var hideSubtitleOnMatch = true
   @Shared(.settingsFile) private var settingsFile: SettingsFile
 
@@ -86,9 +85,9 @@ struct WorktreeDetailView: View {
           titleContent: titleContent,
           rootURL: selectedWorktree.repositoryRootURL,
           kind: toolbarKind(for: selectedWorktree, selectedRow: selectedRow),
+          isRemote: selectedWorktree.host != nil,
           statusToast: repositories.statusToast,
           openActionSelection: openActionSelection,
-          showExtras: commandKeyObserver.isPressed,
           repoScripts: repoScripts,
           globalScripts: globalScripts,
           runningScriptIDs: runningScriptIDs,
@@ -122,11 +121,15 @@ struct WorktreeDetailView: View {
       }
     }
     let hasRunningRunScript = state.hasRunningRunScript
+    // Open / Reveal in Finder reach local paths only; the terminal and search
+    // commands stay enabled for a remote worktree (they work over SSH).
+    let canOpenLocally = hasActiveWorktree && selectedWorktree?.host == nil
     let resolvedSelection: OpenWorktreeAction? =
-      hasActiveWorktree ? OpenWorktreeAction.availableSelection(store.openActionSelection) : nil
+      canOpenLocally ? OpenWorktreeAction.availableSelection(store.openActionSelection) : nil
     return applyFocusedActions(
       content: content,
       hasActiveWorktree: hasActiveWorktree,
+      canOpenLocally: canOpenLocally,
       hasRunningRunScript: hasRunningRunScript,
       resolvedSelection: resolvedSelection
     )
@@ -262,14 +265,15 @@ struct WorktreeDetailView: View {
   private func applyFocusedActions<Content: View>(
     content: Content,
     hasActiveWorktree: Bool,
+    canOpenLocally: Bool,
     hasRunningRunScript: Bool,
     resolvedSelection: OpenWorktreeAction?
   ) -> some View {
     content
-      .focusedSceneAction(\.openSelectedWorktreeAction, enabled: hasActiveWorktree) {
+      .focusedSceneAction(\.openSelectedWorktreeAction, enabled: canOpenLocally) {
         store.send(.openSelectedWorktree)
       }
-      .focusedSceneAction(\.revealInFinderAction, enabled: hasActiveWorktree) {
+      .focusedSceneAction(\.revealInFinderAction, enabled: canOpenLocally) {
         store.send(.revealInFinder)
       }
       .focusedSceneValue(\.openActionSelection, resolvedSelection)
@@ -381,9 +385,11 @@ struct WorktreeDetailView: View {
     let titleContent: WorktreeToolbarTitleContent
     let rootURL: URL
     let kind: Kind
+    // Open actions reach local paths only, so the toolbar Open menu is hidden
+    // for a remote worktree.
+    let isRemote: Bool
     let statusToast: RepositoriesFeature.StatusToast?
     let openActionSelection: OpenWorktreeAction
-    let showExtras: Bool
     let repoScripts: [ScriptDefinition]
     let globalScripts: [ScriptDefinition]
     let runningScriptIDs: Set<UUID>
@@ -483,10 +489,8 @@ struct WorktreeDetailView: View {
       ToolbarSpacer(.flexible)
 
       ToolbarItem {
-        openMenu(
-          openActionSelection: toolbarState.openActionSelection,
-          showExtras: toolbarState.showExtras
-        )
+        openMenu(openActionSelection: toolbarState.openActionSelection)
+          .disabled(toolbarState.isRemote)
       }
       ToolbarSpacer(.fixed)
 
@@ -507,7 +511,7 @@ struct WorktreeDetailView: View {
     }
 
     @ViewBuilder
-    private func openMenu(openActionSelection: OpenWorktreeAction, showExtras: Bool) -> some View {
+    private func openMenu(openActionSelection: OpenWorktreeAction) -> some View {
       let availableActions = OpenWorktreeAction.availableCases.filter { $0 != .finder }
       let resolved = OpenWorktreeAction.availableSelection(openActionSelection)
       let primarySelection = resolved == .finder ? availableActions.first : resolved
@@ -519,7 +523,7 @@ struct WorktreeDetailView: View {
               onOpenActionSelectionChanged(action)
               onOpenWorktree(action)
             } label: {
-              OpenWorktreeActionMenuLabelView(action: action, shortcutHint: nil)
+              OpenWorktreeActionMenuLabelView(action: action)
             }
             .buttonStyle(.plain)
             .help(openActionHelpText(for: action, isDefault: isDefault))
@@ -528,14 +532,11 @@ struct WorktreeDetailView: View {
           Button {
             onRevealInFinder()
           } label: {
-            OpenWorktreeActionMenuLabelView(action: .finder, shortcutHint: nil)
+            OpenWorktreeActionMenuLabelView(action: .finder)
           }
-          .help("Reveal in Finder (\(resolveShortcutDisplay(for: AppShortcuts.revealInFinder)))")
+          .help("Reveal in Finder (\(WorktreeDetailView.resolveShortcutDisplay(for: AppShortcuts.revealInFinder)))")
         } label: {
-          OpenWorktreeActionMenuLabelView(
-            action: primarySelection,
-            shortcutHint: showExtras ? resolveShortcutDisplay(for: AppShortcuts.openWorktree, fallback: "") : nil
-          )
+          OpenWorktreeActionMenuLabelView(action: primarySelection)
         } primaryAction: {
           onOpenWorktree(primarySelection)
         }
@@ -545,7 +546,7 @@ struct WorktreeDetailView: View {
 
     private func openActionHelpText(for action: OpenWorktreeAction, isDefault: Bool) -> String {
       guard isDefault else { return action.title }
-      return "\(action.title) (\(resolveShortcutDisplay(for: AppShortcuts.openWorktree)))"
+      return "\(action.title) (\(WorktreeDetailView.resolveShortcutDisplay(for: AppShortcuts.openWorktree)))"
     }
   }
 
@@ -558,12 +559,14 @@ struct WorktreeDetailView: View {
     let repositoryID = selectedRow?.repositoryID
     let repository = repositoryID.flatMap { repositories.repositories[id: $0] }
     let section = repositoryID.flatMap { repositories.sidebar.sections[$0] }
-    let customTitle = section?.title?.trimmingCharacters(in: .whitespacesAndNewlines)
     let defaultName = repository?.name ?? selectedWorktree.repositoryRootURL.lastPathComponent
-    let repositoryName = customTitle.flatMap { $0.isEmpty ? nil : $0 } ?? defaultName
+    let repositoryName = SidebarDisplayName.resolved(custom: section?.title, fallback: defaultName) ?? defaultName
 
     if selectedRow?.isFolder == true {
-      return .folder(name: repositoryName)
+      // Folders use the per-row custom title (matches the sidebar's folder title position).
+      let folderName =
+        SidebarDisplayName.resolved(custom: selectedRow?.customTitle, fallback: repositoryName) ?? repositoryName
+      return .folder(name: folderName, tint: selectedRow?.customTint, hostInfo: repository?.host?.displayAuthority)
     }
 
     let worktreeSubtitle: String? = {
@@ -576,6 +579,8 @@ struct WorktreeDetailView: View {
       {
         return nil
       }
+      // Subtitle stays on the auto-derived disambiguator (sidebarDisplayName) so the chrome shows
+      // identity context even when the user picked a custom title for the row.
       let worktreeName = selectedRow.sidebarDisplayName ?? "Default"
       let branchName = selectedWorktree.name
       let branchLastComponent = branchName.split(separator: "/").last.map(String.init) ?? branchName
@@ -583,14 +588,26 @@ struct WorktreeDetailView: View {
       return worktreeName
     }()
 
+    // Top text mirrors the sidebar title: custom override if set, else the literal branch name.
+    // `branchName` stays on the real ref so VoiceOver announces "Branch <real-branch>" instead of
+    // the user-typed override (which isn't a ref).
+    let displayTitle =
+      SidebarDisplayName.resolved(
+        custom: selectedRow?.customTitle,
+        fallback: selectedWorktree.name
+      ) ?? selectedWorktree.name
+
     return .git(
       .init(
+        displayTitle: displayTitle,
         branchName: selectedWorktree.name,
         repositoryName: repositoryName,
         repositoryColor: section?.color,
         worktreeSubtitle: worktreeSubtitle,
+        worktreeTint: selectedRow?.customTint,
         accent: selectedRow?.accent ?? .default,
-        rootURL: selectedWorktree.repositoryRootURL
+        rootURL: selectedWorktree.repositoryRootURL,
+        hostInfo: repository?.host?.displayAuthority
       )
     )
   }
@@ -652,6 +669,12 @@ struct WorktreeDetailView: View {
     }
     return nil
   }
+
+  static func resolveShortcutDisplay(for shortcut: AppShortcut, fallback: String = "none") -> String {
+    @Shared(.settingsFile) var settingsFile
+    let display = shortcut.effective(from: settingsFile.global.shortcutOverrides)?.display ?? fallback
+    return display.isEmpty ? fallback : display
+  }
 }
 
 // MARK: - Detail placeholder.
@@ -662,7 +685,7 @@ private struct FailedRepositoryDetailView: View {
   let requestRemove: () -> Void
 
   var body: some View {
-    let path = URL(fileURLWithPath: repositoryID).standardizedFileURL.path(percentEncoded: false)
+    let path = URL(fileURLWithPath: repositoryID.rawValue).standardizedFileURL.path(percentEncoded: false)
     ContentUnavailableView {
       Label("Repository unavailable", systemImage: "exclamationmark.triangle.fill")
         .foregroundStyle(.pink)
@@ -796,7 +819,7 @@ private struct ToolbarPlaceholderContent: ToolbarContent {
       HStack(spacing: 8) {
         Image(systemName: "sun.max.fill")
           .font(.callout)
-        Text("00:00 – Open Command Palette (⌘P)")
+        Text("00:00 – Open Command Palette (⌘⇧P)")
           .font(.footnote)
           .monospaced()
       }
@@ -846,13 +869,6 @@ private struct MultiSelectedWorktreeSummary: Identifiable {
   let repositoryName: String?
 }
 
-/// Resolves a shortcut's display string from the user's settings.
-private func resolveShortcutDisplay(for shortcut: AppShortcut, fallback: String = "none") -> String {
-  @Shared(.settingsFile) var settingsFile
-  let display = shortcut.effective(from: settingsFile.global.shortcutOverrides)?.display ?? fallback
-  return display.isEmpty ? fallback : display
-}
-
 private struct MultiSelectedWorktreesDetailView: View {
   let rows: [MultiSelectedWorktreeSummary]
 
@@ -977,7 +993,6 @@ private struct ScriptMenu: View {
   let onStopRunScripts: () -> Void
   let onManageRepoScripts: () -> Void
   let onManageGlobalScripts: () -> Void
-  @Environment(CommandKeyObserver.self) private var commandKeyObserver
 
   private var primaryScript: ScriptDefinition? {
     toolbarState.primaryScript
@@ -1051,7 +1066,7 @@ private struct ScriptMenu: View {
 
   private func scriptButtonHelp(script: ScriptDefinition, isRunning: Bool, hasCommand: Bool) -> String {
     if isRunning { return "Stop \(script.displayName)." }
-    if !hasCommand { return "\"\(script.displayName)\" has no command — configure it in Settings." }
+    if !hasCommand { return "\"\(script.displayName)\" has no command. Configure it in Settings." }
     return "Run \(script.displayName)."
   }
 
@@ -1059,13 +1074,8 @@ private struct ScriptMenu: View {
   private func scriptLabel(hasRunning: Bool) -> some View {
     let icon = hasRunning ? "stop" : (primaryScript?.resolvedSystemImage ?? "play")
     let label = hasRunning ? "Stop" : (primaryScript?.displayName ?? "Run")
-    let shortcut = hasRunning ? AppShortcuts.stopRunScript : AppShortcuts.runScript
     Label {
-      Text(
-        commandKeyObserver.isPressed
-          ? resolveShortcutDisplay(for: shortcut, fallback: label)
-          : label
-      )
+      Text(label)
     } icon: {
       Image(systemName: icon)
         .accessibilityHidden(true)
@@ -1086,32 +1096,31 @@ private struct ScriptMenu: View {
 @MainActor
 private struct WorktreeToolbarPreview: View {
   private let toolbarState: WorktreeDetailView.WorktreeToolbarState
-  private let commandKeyObserver: CommandKeyObserver
 
   init() {
     toolbarState = WorktreeDetailView.WorktreeToolbarState(
       titleContent: .git(
         .init(
+          displayTitle: "feature/toolbar-preview",
           branchName: "feature/toolbar-preview",
           repositoryName: "supacode",
           repositoryColor: .blue,
           worktreeSubtitle: "toolbar-preview",
+          worktreeTint: nil,
           accent: .pinned,
-          rootURL: URL(fileURLWithPath: "/tmp/preview")
+          rootURL: URL(fileURLWithPath: "/tmp/preview"),
+          hostInfo: nil
         )
       ),
       rootURL: URL(fileURLWithPath: "/tmp/preview"),
       kind: .git(pullRequest: nil),
+      isRemote: false,
       statusToast: nil,
       openActionSelection: .finder,
-      showExtras: false,
       repoScripts: [ScriptDefinition(kind: .run, command: "npm run dev")],
       globalScripts: [],
       runningScriptIDs: [],
     )
-    let observer = CommandKeyObserver()
-    observer.isPressed = false
-    commandKeyObserver = observer
   }
 
   var body: some View {
@@ -1136,7 +1145,6 @@ private struct WorktreeToolbarPreview: View {
         onManageGlobalScripts: {}
       )
     }
-    .environment(commandKeyObserver)
     .frame(width: 900, height: 160)
   }
 }
diff --git a/supacode/Features/Settings/Views/DeveloperSettingsView.swift b/supacode/Features/Settings/Views/DeveloperSettingsView.swift
index a8d4b46b3..f851733e8 100644
--- a/supacode/Features/Settings/Views/DeveloperSettingsView.swift
+++ b/supacode/Features/Settings/Views/DeveloperSettingsView.swift
@@ -180,7 +180,9 @@ extension SkillAgent {
       Hooks in `~/.codex/hooks.json` and skill in `~/.codex/skills/`. After installing, trust the hooks in Codex; \
       the badge appears once you send the first message.
       """
+    case .copilot: "Hooks in `~/.copilot/hooks/supacode.json` and skill in `~/.copilot/skills/`."
     case .kiro: "Hooks in `~/.kiro/agents/` and skill in `~/.kiro/skills/`."
+    case .opencode: "Plugin in `~/.config/opencode/plugins/` and skill in `~/.config/opencode/skills/`."
     case .pi: "Extension in `~/.pi/agent/extensions/` and skill in `~/.pi/agent/skills/`."
     }
   }
diff --git a/supacode/Features/Settings/Views/SettingsView.swift b/supacode/Features/Settings/Views/SettingsView.swift
index 28d02854d..7a8af9417 100644
--- a/supacode/Features/Settings/Views/SettingsView.swift
+++ b/supacode/Features/Settings/Views/SettingsView.swift
@@ -73,6 +73,52 @@ private struct RepositoryDisclosureLabel: View {
   }
 }
 
+/// One repository row in the settings sidebar. Git repos get a General /
+/// Scripts disclosure; folder repos go straight to Scripts. Shared by the
+/// Local and Remote sections so the two render identically.
+private struct SettingsRepositoryRow: View {
+  let repository: SettingsRepositorySummary
+  @Bindable var settingsStore: StoreOf<SettingsFeature>
+  @Binding var expandedRepositories: Set<String>
+
+  var body: some View {
+    if repository.isGitRepository {
+      let isExpanded = Binding(
+        get: { expandedRepositories.contains(repository.id) },
+        set: { expanded in
+          if expanded {
+            expandedRepositories.insert(repository.id)
+          } else {
+            expandedRepositories.remove(repository.id)
+          }
+        }
+      )
+      DisclosureGroup(isExpanded: isExpanded) {
+        Label("General", systemImage: "gearshape")
+          .tag(SettingsSection.repository(repository.id))
+        Label("Scripts", systemImage: "terminal")
+          .tag(SettingsSection.repositoryScripts(repository.id))
+      } label: {
+        RepositoryDisclosureLabel(
+          repository: repository,
+          settingsStore: settingsStore,
+          isExpanded: isExpanded
+        )
+      }
+    } else {
+      // Folder entries go straight to the scripts page; no general
+      // disclosure row since the git settings don't apply. Selection is
+      // expressed via the row tag so selecting it updates the selection.
+      RepositoryLabel(
+        name: repository.name,
+        rootURL: repository.rootURL,
+        isGitRepository: false
+      )
+      .tag(SettingsSection.repositoryScripts(repository.id))
+    }
+  }
+}
+
 /// Sidebar content for the settings split view.
 private struct SettingsSidebarView: View {
   @Bindable var settingsStore: StoreOf<SettingsFeature>
@@ -97,42 +143,27 @@ private struct SettingsSidebarView: View {
       Label("Updates", systemImage: "arrow.down.circle")
         .tag(SettingsSection.updates)
 
-      Section("Repositories") {
-        ForEach(settingsStore.repositorySummaries, id: \.id) { repository in
-          if repository.isGitRepository {
-            let isExpanded = Binding(
-              get: { expandedRepositories.contains(repository.id) },
-              set: { expanded in
-                if expanded {
-                  expandedRepositories.insert(repository.id)
-                } else {
-                  expandedRepositories.remove(repository.id)
-                }
-              }
+      let localRepositories = settingsStore.repositorySummaries.filter { !$0.isRemote }
+      let remoteRepositories = settingsStore.repositorySummaries.filter(\.isRemote)
+      if !localRepositories.isEmpty {
+        Section("Local") {
+          ForEach(localRepositories, id: \.id) { repository in
+            SettingsRepositoryRow(
+              repository: repository,
+              settingsStore: settingsStore,
+              expandedRepositories: $expandedRepositories
             )
-            DisclosureGroup(isExpanded: isExpanded) {
-              Label("General", systemImage: "gearshape")
-                .tag(SettingsSection.repository(repository.id))
-              Label("Scripts", systemImage: "terminal")
-                .tag(SettingsSection.repositoryScripts(repository.id))
-            } label: {
-              RepositoryDisclosureLabel(
-                repository: repository,
-                settingsStore: settingsStore,
-                isExpanded: isExpanded
-              )
-            }
-          } else {
-            // Folder entries go straight to the scripts page — no
-            // general / disclosure row since the git settings don't
-            // apply. Selection is expressed via the row tag so
-            // selecting it updates `settingsStore.selection`.
-            RepositoryLabel(
-              name: repository.name,
-              rootURL: repository.rootURL,
-              isGitRepository: false
+          }
+        }
+      }
+      if !remoteRepositories.isEmpty {
+        Section("Remote") {
+          ForEach(remoteRepositories, id: \.id) { repository in
+            SettingsRepositoryRow(
+              repository: repository,
+              settingsStore: settingsStore,
+              expandedRepositories: $expandedRepositories
             )
-            .tag(SettingsSection.repositoryScripts(repository.id))
           }
         }
       }
diff --git a/supacode/Features/Terminal/BusinessLogic/BlockingScriptRunner.swift b/supacode/Features/Terminal/BusinessLogic/BlockingScriptRunner.swift
index 9bb5fb4f4..7fe986b21 100644
--- a/supacode/Features/Terminal/BusinessLogic/BlockingScriptRunner.swift
+++ b/supacode/Features/Terminal/BusinessLogic/BlockingScriptRunner.swift
@@ -1,4 +1,5 @@
 import Foundation
+import SupacodeSettingsShared
 
 /// Pure helpers for the blocking-script wrapper: temp-dir layout, shell-script
 /// generation, and shell single-quote escaping.
@@ -112,4 +113,64 @@ enum BlockingScriptRunner {
   static func shellSingleQuoted(_ value: String) -> String {
     "'\(value.replacing("'", with: "'\"'\"'"))'"
   }
+
+  /// Full local surface command for a blocking script on a *remote* worktree:
+  /// an `ssh -tt <host> …` line (no local zmx wrapping, so it dies with the
+  /// app like a local blocking script) that runs the same OSC 133 framing on
+  /// the host. The user script rides as `$1`, so arbitrary script text needs no
+  /// remote temp file. Returns nil for an empty script.
+  static func remoteCommand(
+    host: RemoteHost,
+    script: String,
+    remoteWorktreePath: String,
+    environment: [String: String] = [:]
+  ) -> String? {
+    let trimmed = script.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard !trimmed.isEmpty else { return nil }
+    return SSHCommand.commandLine(
+      host: host,
+      remoteScript: remoteRunnerScript(remoteWorktreePath: remoteWorktreePath),
+      positionalArguments: ["supacode-blocking", trimmed],
+      environment: environment
+    )
+  }
+
+  /// The script the *remote* login shell runs for a blocking script. Mirrors
+  /// `runnerScript` (OSC 133 begin/end framing, read-only `tail -f /dev/null`
+  /// on completion) but runs on the host: it `cd`s into the remote worktree,
+  /// prints the remote beta banner, and runs the user script (`$1`) as a login
+  /// shell child so a `exit` in the script can't skip the completion emit.
+  ///
+  /// Blocking-script marker env vars are applied by the caller via the
+  /// `SSHCommand` `env` prefix so the login shell inherits them before sourcing
+  /// its profile, not exported here (which would run after the profile loads).
+  static func remoteRunnerScript(remoteWorktreePath: String) -> String {
+    let trimmedPath = remoteWorktreePath.trimmingCharacters(in: .whitespacesAndNewlines)
+    // Abort on a failed `cd` so a blocking script (user / delete / archive)
+    // never runs in the login shell's `$HOME` when the worktree directory was
+    // removed or renamed on the host after it was loaded.
+    let cdLine =
+      (trimmedPath.isEmpty || trimmedPath == "/")
+      ? ""
+      : "if ! cd -- \(shellSingleQuoted(trimmedPath)) 2>/dev/null; then "
+        + "printf '\\r\\n\\033[2m── Could not enter the worktree directory; script not run. ──\\033[0m\\r\\n'; "
+        + "SUPACODE_EXIT=1; exit 1; fi\n"
+    return """
+      set -u
+      SUPACODE_EXIT=127
+      trap 'printf "\\033]133;D;%d\\007" "$SUPACODE_EXIT"' EXIT
+      trap 'exit 127' INT TERM HUP QUIT PIPE
+      printf '\\033]133;C\\007'
+      \(ZmxAttach.betaBanner)
+      \(cdLine)"$SHELL" -l -c "$1"
+      SUPACODE_EXIT=$?
+      trap - EXIT
+      printf '\\033]133;D;%d\\007' "$SUPACODE_EXIT"
+      if [ -t 0 ]; then
+        printf '\\r\\n\\033[2m── Script finished (exit code: %d). Tab is read-only. ──\\033[0m\\r\\n' "$SUPACODE_EXIT"
+        exec tail -f /dev/null
+      fi
+      exit "$SUPACODE_EXIT"
+      """
+  }
 }
diff --git a/supacode/Features/Terminal/BusinessLogic/LayoutsIncrementalWriter.swift b/supacode/Features/Terminal/BusinessLogic/LayoutsIncrementalWriter.swift
new file mode 100644
index 000000000..c87e6a43f
--- /dev/null
+++ b/supacode/Features/Terminal/BusinessLogic/LayoutsIncrementalWriter.swift
@@ -0,0 +1,145 @@
+import Dependencies
+import Foundation
+import SupacodeSettingsShared
+
+/// Serialized off-main writer for incremental layout persistence. Every flush
+/// re-reads `layouts.json` from disk, splices in only the per-worktree keys it
+/// carries, then writes the whole dict back through the atomic temp+rename
+/// `settingsFileStorage.save`. Being an actor makes the read-modify-write a
+/// FIFO critical section: a positive snapshot and a delete tombstone for the
+/// same key can't interleave, and concurrent keys from separate flushes both
+/// survive (last-writer-wins per key, not whole-dict).
+///
+/// There is no flock / NSFileCoordinator: a second Supacode instance writing
+/// the same file concurrently is a dev-only scenario and accepted as
+/// last-writer-wins. The in-memory `@Shared(.layouts)` dict stays the source of
+/// truth on main; this actor only owns the encode + disk merge.
+actor LayoutsIncrementalWriter {
+  /// One per-worktree change to splice into the on-disk dict. `.delete` is an
+  /// explicit tombstone: absence from a flush means "leave the disk key alone",
+  /// so a pruned worktree must be carried as `.delete`, never as omission.
+  enum Change: Sendable {
+    case snapshot(TerminalLayoutSnapshot)
+    case delete
+  }
+
+  private static let logger = SupaLogger("Layouts")
+  private let storage: SettingsFileStorage
+  private let url: URL
+  /// Guards the read-modify-write so the off-actor `flushSync` (on-quit) and the
+  /// actor-routed flush/delete paths mutually exclude. The actor still owns FIFO
+  /// ordering of the live path; this only prevents a lost update against the
+  /// single off-actor entrant.
+  private let writeLock = NSLock()
+
+  init(
+    storage: SettingsFileStorage,
+    url: URL = SupacodePaths.layoutsURL
+  ) {
+    self.storage = storage
+    self.url = url
+  }
+
+  /// Re-reads the on-disk dict, applies `changes`, and writes the result.
+  /// Keys not present in `changes` are preserved from disk untouched.
+  func flush(_ changes: [String: Change]) {
+    applyAndWrite(changes)
+  }
+
+  /// Synchronous variant for the on-quit terminal write, where the run loop is
+  /// tearing down and there's no chance to await the actor. The atomic temp+rename
+  /// `storage.save` makes the off-actor write safe as the process's final flush.
+  nonisolated func flushSync(_ changes: [String: Change]) {
+    applyAndWrite(changes)
+  }
+
+  private nonisolated func applyAndWrite(_ changes: [String: Change]) {
+    guard !changes.isEmpty else { return }
+    writeLock.lock()
+    defer { writeLock.unlock() }
+    guard var dict = readFromDisk() else {
+      // Abort rather than splice our keys into an empty dict and clobber every other worktree's layout.
+      Self.logger.error(
+        "Aborting incremental layout flush: on-disk layouts failed to decode; preserving file for recovery.")
+      return
+    }
+    let original = dict
+    for (key, change) in changes {
+      switch change {
+      case .snapshot(let snapshot):
+        dict[key] = snapshot
+      case .delete:
+        dict.removeValue(forKey: key)
+      }
+    }
+    // Skip the write when the splice is a no-op. onTabProjectionChanged fires on
+    // notification / focus / zoom deltas that aren't part of the snapshot, so an
+    // agent tool-call storm would otherwise churn the file with identical bytes.
+    guard dict != original else { return }
+    write(dict)
+  }
+
+  /// Returns the on-disk dict, `[:]` when the file is absent (fresh start) or
+  /// when corrupt bytes were rotated aside, or `nil` on a present-but-unreadable
+  /// file (transient/permission error) so the caller aborts rather than clobbers it.
+  private nonisolated func readFromDisk() -> [String: TerminalLayoutSnapshot]? {
+    let data: Data
+    do {
+      data = try storage.load(url)
+    } catch {
+      // Only an absent file is a fresh start; a present-but-unreadable file must abort so we don't clobber siblings.
+      guard Self.isFileAbsent(error) else {
+        Self.logger.error("Failed to read layouts during incremental merge: \(error)")
+        return nil
+      }
+      return [:]
+    }
+    do {
+      return try JSONDecoder().decode([String: TerminalLayoutSnapshot].self, from: data)
+    } catch {
+      // Corrupt bytes: rotate aside and start fresh rather than refuse to save
+      // forever. Mirrors SidebarPersistenceKey; the bytes are kept for recovery.
+      Self.logger.error("Failed to decode layouts during incremental merge: \(error)")
+      Self.renameCorruptFile(at: url)
+      return [:]
+    }
+  }
+
+  /// True only when the read failed because the file does not exist.
+  private static func isFileAbsent(_ error: Error) -> Bool {
+    if let cocoa = error as? CocoaError, cocoa.code == .fileReadNoSuchFile { return true }
+    if let posix = error as? POSIXError, posix.code == .ENOENT { return true }
+    return false
+  }
+
+  /// Moves a corrupt `layouts.json` aside to `layouts.json.corrupt-<ISO8601>` so
+  /// the next save starts fresh instead of aborting forever. The storage dep only
+  /// exposes load/save, so the rename goes through FileManager; a missing or
+  /// already-renamed file returns quietly and the caller proceeds to the fresh dict.
+  private nonisolated static func renameCorruptFile(at url: URL) {
+    let fileManager = FileManager.default
+    guard fileManager.fileExists(atPath: url.path(percentEncoded: false)) else { return }
+    let formatter = ISO8601DateFormatter()
+    formatter.formatOptions = [.withInternetDateTime]
+    let timestamp = formatter.string(from: Date()).replacing(":", with: "-")
+    let destination = url.deletingLastPathComponent()
+      .appending(path: "\(url.lastPathComponent).corrupt-\(timestamp)", directoryHint: .notDirectory)
+    do {
+      try SymlinkPreservingFileWriter.moveAside(at: url, to: destination)
+    } catch {
+      Self.logger.warning(
+        "Failed to rename corrupt layouts file to \(destination.lastPathComponent): \(error).")
+    }
+  }
+
+  private nonisolated func write(_ dict: [String: TerminalLayoutSnapshot]) {
+    do {
+      let encoder = JSONEncoder()
+      encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+      let data = try encoder.encode(dict)
+      try storage.save(data, url)
+    } catch {
+      Self.logger.warning("Failed to write incremental layouts: \(error)")
+    }
+  }
+}
diff --git a/supacode/Features/Terminal/BusinessLogic/LayoutsPersistenceKey.swift b/supacode/Features/Terminal/BusinessLogic/LayoutsPersistenceKey.swift
index 764c8285b..15f38dce5 100644
--- a/supacode/Features/Terminal/BusinessLogic/LayoutsPersistenceKey.swift
+++ b/supacode/Features/Terminal/BusinessLogic/LayoutsPersistenceKey.swift
@@ -42,20 +42,14 @@ nonisolated struct LayoutsKey: SharedKey {
   }
 
   func save(
-    _ value: [String: TerminalLayoutSnapshot],
+    _: [String: TerminalLayoutSnapshot],
     context _: SaveContext,
     continuation: SaveContinuation
   ) {
-    @Dependency(\.settingsFileStorage) var storage
-    do {
-      let encoder = JSONEncoder()
-      encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
-      let data = try encoder.encode(value)
-      try storage.save(data, SupacodePaths.layoutsURL)
-      continuation.resume()
-    } catch {
-      continuation.resume(throwing: error)
-    }
+    // No-op: `LayoutsIncrementalWriter` is the sole disk writer for `layouts.json`.
+    // `@Shared(.layouts)` stays the in-memory source of truth; persisting here too
+    // would race the actor's per-key merge with a whole-dict last-writer-wins clobber.
+    continuation.resume()
   }
 }
 
diff --git a/supacode/Features/Terminal/BusinessLogic/WorktreeTerminalManager.swift b/supacode/Features/Terminal/BusinessLogic/WorktreeTerminalManager.swift
index 74a669727..41cc35004 100644
--- a/supacode/Features/Terminal/BusinessLogic/WorktreeTerminalManager.swift
+++ b/supacode/Features/Terminal/BusinessLogic/WorktreeTerminalManager.swift
@@ -24,12 +24,43 @@ final class WorktreeTerminalManager {
   private var lastEmittedProjections: [Worktree.ID: WorktreeRowProjection] = [:]
   private var eventContinuation: AsyncStream<TerminalClient.Event>.Continuation?
   private var pendingEvents: [TerminalClient.Event] = []
+  /// Latest-wins events deduped by identity: drops a value equal to the
+  /// immediately-previous one per key (a burst of distinct values still passes),
+  /// so per-tab projection / progress / task-status / focus repeats don't flood
+  /// the stream. Cleared on resubscribe and purged on tab / worktree teardown.
+  private var lastEmittedCoalescable: [CoalesceKey: TerminalClient.Event] = [:]
+  /// Hard cap on the live event buffer. Source coalescing keeps it near-empty in
+  /// practice; this backstops a wedged consumer so memory stays bounded instead
+  /// of growing without limit.
+  static let eventBufferCap = 2048
+  /// Cap for lifecycle events buffered before the first subscriber attaches.
+  /// Coalescable state collapses per key and doesn't count, so this only bounds
+  /// one-shot events; the sole consumer attaches at launch, well under the cap.
+  static let pendingEventCap = 1024
   @ObservationIgnored
   private var pendingIdleHookEvents: [IdleDebounceKey: Task<Void, Never>] = [:]
   @ObservationIgnored
   private let hookEventSleep: @Sendable (Duration) async throws -> Void
   @ObservationIgnored @Dependency(\.zmxClient) private var zmxClient
   @ObservationIgnored @Dependency(\.analyticsClient) private var analyticsClient
+  /// Serialized off-main writer that merges per-worktree layout changes into
+  /// `layouts.json` without clobbering keys it isn't carrying. Built from the
+  /// dependency context at init so async flushes use the same storage the test
+  /// or app configured, not whatever context happens to be current at flush.
+  @ObservationIgnored private let layoutsWriter: LayoutsIncrementalWriter
+  /// Per-worktree debounce timers for incremental layout saves.
+  @ObservationIgnored private var layoutDirtyTasks: [Worktree.ID: Task<Void, Never>] = [:]
+  /// Per-worktree in-flight positive flush Tasks. A delete awaits the live one
+  /// for its key so `.delete` always lands on the writer after the `.snapshot`,
+  /// preventing a stale positive flush from resurrecting a pruned worktree.
+  @ObservationIgnored private var layoutFlushTasks: [Worktree.ID: Task<Void, Never>] = [:]
+  /// Sleeps the incremental-save debounce window; injected so tests drive it.
+  @ObservationIgnored private let layoutDebounceSleep: @Sendable (Duration) async throws -> Void
+  /// Debounce window before an incremental layout snapshot is flushed.
+  private static let layoutDebounceDuration: Duration = .seconds(1)
+  /// Reads the freshest `agentsBySurface` at flush time so incremental captures
+  /// embed live badge records instead of the empty default.
+  var currentAgentsBySurface: (() -> [UUID: [TerminalLayoutSnapshot.SurfaceAgentRecord]])?
   /// Holds `.idle` long enough to collapse PostToolUse/PreToolUse busy/idle alternation
   /// into a sustained busy; stays sub-perceptible for the badge clearing at end-of-session.
   private static let idleHookDebounceDuration: Duration = .milliseconds(400)
@@ -39,6 +70,50 @@ final class WorktreeTerminalManager {
     let agent: SkillAgent
   }
 
+  /// Identity for a latest-wins event. Two events sharing a key carry the same
+  /// piece of state, so an identical repeat is a no-op and is dropped.
+  private enum CoalesceKey: Hashable {
+    case worktreeProjection(Worktree.ID)
+    case tabProjection(TerminalTabID)
+    case tabProgress(TerminalTabID)
+    case taskStatus(Worktree.ID)
+    case focus(Worktree.ID)
+    case notificationIndicator
+    case hasAnySurface
+  }
+
+  /// Non-nil for state events that are safe to coalesce by identity. Lifecycle /
+  /// one-shot events (tab create / close / remove, notifications, script
+  /// completion, command-palette, teardown) return nil and are never dropped.
+  private static func coalesceKey(for event: TerminalClient.Event) -> CoalesceKey? {
+    switch event {
+    case .worktreeProjectionChanged(let worktreeID, _): .worktreeProjection(worktreeID)
+    case .tabProjectionChanged(_, let projection): .tabProjection(projection.tabID)
+    case .tabProgressDisplayChanged(_, let tabID, _): .tabProgress(tabID)
+    case .taskStatusChanged(let worktreeID, _): .taskStatus(worktreeID)
+    case .focusChanged(let worktreeID, _): .focus(worktreeID)
+    case .notificationIndicatorChanged: .notificationIndicator
+    case .terminalHasAnySurfaceChanged: .hasAnySurface
+    default: nil
+    }
+  }
+
+  /// Compact identity for a backpressure-drop log. Strips the payload-heavy
+  /// cases (projections / notification bodies) to their key ids so a drop storm
+  /// can't flood the log; the rest carry small payloads and describe themselves.
+  private static func label(for event: TerminalClient.Event) -> String {
+    switch event {
+    case .worktreeProjectionChanged(let worktreeID, _): "worktreeProjectionChanged(\(worktreeID))"
+    case .tabProjectionChanged(let worktreeID, let projection):
+      "tabProjectionChanged(\(worktreeID), tab: \(projection.tabID))"
+    case .tabProgressDisplayChanged(let worktreeID, let tabID, _):
+      "tabProgressDisplayChanged(\(worktreeID), tab: \(tabID))"
+    case .notificationReceived(let worktreeID, let surfaceID, _, _):
+      "notificationReceived(\(worktreeID), surface: \(surfaceID))"
+    default: String(describing: event)
+    }
+  }
+
   var selectedWorktreeID: Worktree.ID?
   var saveLayoutSnapshot: ((Worktree.ID, TerminalLayoutSnapshot?) -> Void)?
   var loadLayoutSnapshot: ((Worktree.ID) -> TerminalLayoutSnapshot?)?
@@ -54,6 +129,9 @@ final class WorktreeTerminalManager {
   ) {
     self.runtime = runtime
     self.hookEventSleep = { duration in try await clock.sleep(for: duration) }
+    self.layoutDebounceSleep = { duration in try await clock.sleep(for: duration) }
+    @Dependency(\.settingsFileStorage) var settingsFileStorage
+    self.layoutsWriter = LayoutsIncrementalWriter(storage: settingsFileStorage)
     let resolvedServer = socketServer ?? AgentHookSocketServer()
     guard resolvedServer.socketPath != nil else {
       self.socketServer = nil
@@ -66,21 +144,11 @@ final class WorktreeTerminalManager {
 
   isolated deinit {
     for task in pendingIdleHookEvents.values { task.cancel() }
+    for task in layoutDirtyTasks.values { task.cancel() }
+    for task in layoutFlushTasks.values { task.cancel() }
   }
 
   private func configureSocketServer(_ server: AgentHookSocketServer) {
-    server.onNotification = { [weak self] worktreeID, _, surfaceID, notification in
-      guard let self else { return }
-      guard self.settingsFile.global.richAgentNotificationsEnabled else { return }
-      let decoded = worktreeID.removingPercentEncoding ?? worktreeID
-      guard let state = self.states[decoded] else {
-        terminalLogger.debug("Dropped hook notification for unknown worktree \(decoded)")
-        return
-      }
-      let title = notification.title ?? notification.agent
-      let body = notification.body ?? ""
-      state.appendHookNotification(title: title, body: body, surfaceID: surfaceID)
-    }
     server.onCommand = { [weak self] deeplinkURL, clientFD in
       guard let handler = self?.onDeeplinkCommand else {
         AgentHookSocketServer.sendCommandResponse(clientFD: clientFD, ok: false, error: "Not ready.")
@@ -95,18 +163,10 @@ final class WorktreeTerminalManager {
       }
       handler(resource, params, clientFD)
     }
-    // Always record; the badges toggle gates DISPLAY in
-    // `AgentPresenceFeature.State.agents(forSurface:badgesEnabled:)`.
-    // Gating recording too would drop session_start events fired while
-    // the toggle was off, so flipping it back on later wouldn't restore
-    // badges for already-running agents.
-    server.onEvent = { [weak self] event in
-      self?.dispatchHookEvent(event)
-    }
   }
 
   /// Holds `.idle` for a debounce window so PostToolUse / PreToolUse storms don't flap downstream UI.
-  /// Lives at the socket boundary so the debounce applies before the event lands in TCA.
+  /// Applies the idle debounce before the OSC-sourced event lands in TCA.
   private func dispatchHookEvent(_ event: AgentHookEvent) {
     guard let agent = SkillAgent(rawValue: event.agent) else {
       applyHookEvent(event)
@@ -141,11 +201,18 @@ final class WorktreeTerminalManager {
     emit(.agentHookEventReceived(event))
   }
 
+  #if DEBUG
+    /// Count of idle-hook debounce tasks still scheduled (test-only). A clock-awoken
+    /// resume removes its key only after it emits, so a non-zero count means a
+    /// pending idle event has not yet landed in the stream.
+    var pendingIdleHookCountForTesting: Int { pendingIdleHookEvents.count }
+  #endif
+
   // MARK: - CLI queries.
 
   func listTabs(worktreeID: String) -> [[String: String]]? {
     let decoded = worktreeID.removingPercentEncoding ?? worktreeID
-    guard let state = states[decoded] else { return nil }
+    guard let state = states[WorktreeID(decoded)] else { return nil }
     let selectedTabID = state.tabManager.selectedTabId
     return state.tabManager.tabs.map { tab in
       var entry = ["id": tab.id.rawValue.uuidString]
@@ -156,7 +223,7 @@ final class WorktreeTerminalManager {
 
   func listSurfaces(worktreeID: String, tabID: String) -> [[String: String]]? {
     let decoded = worktreeID.removingPercentEncoding ?? worktreeID
-    guard let state = states[decoded],
+    guard let state = states[WorktreeID(decoded)],
       let tabUUID = UUID(uuidString: tabID)
     else { return nil }
     let terminalTabID = TerminalTabID(rawValue: tabUUID)
@@ -288,8 +355,8 @@ final class WorktreeTerminalManager {
 
   private func handleManagementCommand(_ command: TerminalClient.Command) {
     switch command {
-    case .prune(let ids):
-      prune(keeping: ids)
+    case .prune(let ids, let protectedRepositoryIDs):
+      prune(keeping: ids, protectingRepositoryIDs: protectedRepositoryIDs)
     case .setNotificationsEnabled(let enabled):
       setNotificationsEnabled(enabled)
     case .refreshTabBarVisibility:
@@ -299,11 +366,12 @@ final class WorktreeTerminalManager {
     case .setSelectedWorktreeID(let id):
       guard id != selectedWorktreeID else { return }
       if let previousID = selectedWorktreeID, let previousState = states[previousID] {
+        previousState.rememberFocusedZoom()
         previousState.setAllSurfacesOccluded()
-        saveLayoutSnapshot?(previousID, previousState.captureLayoutSnapshot())
+        markLayoutDirty(worktreeID: previousID)
       }
       selectedWorktreeID = id
-      terminalLogger.info("Selected worktree \(id ?? "nil")")
+      terminalLogger.info("Selected worktree \(id?.rawValue ?? "nil")")
     case .createTab, .createTabWithInput, .ensureInitialTab, .stopRunScript, .stopScript,
       .runBlockingScript, .closeFocusedTab, .closeFocusedSurface, .performBindingAction,
       .performBindingActionOnSurface, .startSearch, .searchSelection, .navigateSearchNext,
@@ -315,17 +383,27 @@ final class WorktreeTerminalManager {
 
   func eventStream() -> AsyncStream<TerminalClient.Event> {
     eventContinuation?.finish()
-    let (stream, continuation) = AsyncStream.makeStream(of: TerminalClient.Event.self)
+    let (stream, continuation) = AsyncStream.makeStream(
+      of: TerminalClient.Event.self,
+      bufferingPolicy: .bufferingNewest(Self.eventBufferCap)
+    )
     eventContinuation = continuation
     lastNotificationIndicatorCount = nil
+    // Reset dedup state before replaying so the replay re-seeds both caches; a
+    // fresh subscriber then has the latest value recorded for every key.
+    lastEmittedProjections.removeAll()
+    lastEmittedCoalescable.removeAll()
     if !pendingEvents.isEmpty {
       let bufferedEvents = pendingEvents
       pendingEvents.removeAll()
       for event in bufferedEvents {
+        // Re-emitted fresh below, so drop the buffered copy.
         if case .notificationIndicatorChanged = event {
           continue
         }
-        continuation.yield(event)
+        // Route through emit() (not a raw yield) so a coalescable buffered event
+        // seeds lastEmittedCoalescable and the first identical live event dedups.
+        emit(event)
       }
     }
     emitNotificationIndicatorCountIfNeeded()
@@ -335,19 +413,16 @@ final class WorktreeTerminalManager {
     // Seed each worktree's projection so rows attached after the stream start
     // pick up the current snapshot (otherwise they'd stay default until the
     // next mutation).
-    lastEmittedProjections.removeAll()
     for id in states.keys { emitProjection(for: id) }
     // Replay per-tab projections / stripe-progress displays for the same reason:
     // a new subscriber needs the existing `terminalTabs[id:]` rows seeded so
     // tab-bar leaves don't render empty until the next per-tab mutation.
     for (worktreeID, state) in states {
       for projection in state.currentTabProjections() {
-        continuation.yield(.tabProjectionChanged(worktreeID: worktreeID, projection))
+        emit(.tabProjectionChanged(worktreeID: worktreeID, projection))
       }
       for (tabID, display) in state.currentTabProgressDisplays() {
-        continuation.yield(
-          .tabProgressDisplayChanged(worktreeID: worktreeID, tabID: tabID, display: display)
-        )
+        emit(.tabProgressDisplayChanged(worktreeID: worktreeID, tabID: tabID, display: display))
       }
     }
     return stream
@@ -390,6 +465,10 @@ final class WorktreeTerminalManager {
     state.onSurfacesClosed = { [weak self] ids in
       self?.emit(.surfacesClosed(ids))
     }
+    // OSC-sourced presence events go through the existing idle-debounce funnel.
+    state.onAgentHookEvent = { [weak self] event in
+      self?.dispatchHookEvent(event)
+    }
     state.onNotificationReceived = { [weak self] surfaceID, title, body in
       self?.emit(
         .notificationReceived(
@@ -408,10 +487,15 @@ final class WorktreeTerminalManager {
     state.onTabCreated = { [weak self] in
       self?.emit(.tabCreated(worktreeID: worktree.id))
       self?.emitProjection(for: worktree.id)
+      self?.markLayoutDirty(worktreeID: worktree.id)
     }
     state.onTabClosed = { [weak self] in
       self?.emit(.tabClosed(worktreeID: worktree.id))
       self?.emitProjection(for: worktree.id)
+      self?.markLayoutDirty(worktreeID: worktree.id)
+    }
+    state.onTabRenamed = { [weak self] in
+      self?.markLayoutDirty(worktreeID: worktree.id)
     }
     state.onFocusChanged = { [weak self] surfaceID in
       self?.emit(.focusChanged(worktreeID: worktree.id, surfaceID: surfaceID))
@@ -431,9 +515,11 @@ final class WorktreeTerminalManager {
     }
     state.onTabProjectionChanged = { [weak self] projection in
       self?.emit(.tabProjectionChanged(worktreeID: worktree.id, projection))
+      self?.markLayoutDirty(worktreeID: worktree.id)
     }
     state.onTabRemoved = { [weak self] tabID in
       self?.emit(.tabRemoved(worktreeID: worktree.id, tabID: tabID))
+      self?.markLayoutDirty(worktreeID: worktree.id)
     }
     state.onTabProgressDisplayChanged = { [weak self] tabID, display in
       self?.emit(.tabProgressDisplayChanged(worktreeID: worktree.id, tabID: tabID, display: display))
@@ -452,7 +538,7 @@ final class WorktreeTerminalManager {
     let state = state(for: worktree) { runSetupScriptIfNew }
     let setupScript: String?
     if state.needsSetupScript() {
-      @SharedReader(.repositorySettings(worktree.repositoryRootURL))
+      @SharedReader(.repositorySettings(worktree.repositoryRootURL, host: worktree.host))
       var settings = RepositorySettings.default
       setupScript = settings.setupScript
     } else {
@@ -473,9 +559,15 @@ final class WorktreeTerminalManager {
     return state.closeFocusedSurface()
   }
 
-  func prune(keeping worktreeIDs: Set<Worktree.ID>) {
+  func prune(
+    keeping worktreeIDs: Set<Worktree.ID>,
+    protectingRepositoryIDs protectedRepositoryIDs: Set<Repository.ID> = []
+  ) {
+    let shouldKeep: (Worktree.ID, WorktreeTerminalState) -> Bool = { id, state in
+      worktreeIDs.contains(id) || protectedRepositoryIDs.contains(state.repositoryID)
+    }
     var removed: [(Worktree.ID, WorktreeTerminalState)] = []
-    for (id, state) in states where !worktreeIDs.contains(id) {
+    for (id, state) in states where !shouldKeep(id, state) {
       removed.append((id, state))
     }
     let prunedSurfaceIDs = Set(removed.flatMap { _, state in state.allSurfaceIDs })
@@ -484,8 +576,10 @@ final class WorktreeTerminalManager {
     }
     for (id, state) in removed {
       // Clear instead of resaving: archived / deleted worktrees should leave
-      // no trace in `layouts.json`.
-      saveLayoutSnapshot?(id, nil)
+      // no trace in `layouts.json`. The explicit delete bypasses the debounce
+      // and cancels any queued positive save so a pruned worktree can't be
+      // resurrected by an in-flight snapshot.
+      deleteLayoutSnapshot(worktreeID: id)
       state.closeAllSurfaces()
       // Signals the reducer to drop any orphan `terminalTabs` entries and
       // recently-removed-tab records for this worktree so a same-session
@@ -495,14 +589,81 @@ final class WorktreeTerminalManager {
     if !removed.isEmpty {
       terminalLogger.info("Pruned \(removed.count) terminal state(s)")
     }
-    states = states.filter { worktreeIDs.contains($0.key) }
+    states = states.filter { shouldKeep($0.key, $0.value) }
     cancelPendingIdleHooks(forSurfaceIDs: prunedSurfaceIDs)
-    for (id, _) in removed { lastEmittedProjections.removeValue(forKey: id) }
+    for (id, _) in removed { invalidateCaches(forPrunedWorktree: id) }
     emitNotificationIndicatorCountIfNeeded()
     emitHasAnyTerminalSurfaceIfNeeded()
     killZmxSessions(prunedSessionIDs)
   }
 
+  /// Schedules a debounced incremental layout save for `worktreeID`. Coalesces
+  /// a burst of mutations into one write; the snapshot is captured at fire time
+  /// (freshest tree + agent records), mutated into the in-memory `@Shared` dict
+  /// on main, then merged into `layouts.json` off main.
+  func markLayoutDirty(worktreeID: Worktree.ID) {
+    layoutDirtyTasks[worktreeID]?.cancel()
+    layoutDirtyTasks[worktreeID] = Task { [weak self, layoutDebounceSleep] in
+      try? await layoutDebounceSleep(Self.layoutDebounceDuration)
+      guard !Task.isCancelled else { return }
+      self?.flushLayoutSnapshot(worktreeID: worktreeID)
+    }
+  }
+
+  /// Fires after the debounce window: captures the freshest snapshot for
+  /// `worktreeID`, updates the in-memory `@Shared` dict on main, then queues the
+  /// off-main per-key merge. Its only caller is `markLayoutDirty`.
+  private func flushLayoutSnapshot(worktreeID: Worktree.ID) {
+    layoutDirtyTasks[worktreeID] = nil
+    guard let state = states[worktreeID] else { return }
+    let agents = currentAgentsBySurface?() ?? [:]
+    // A nil snapshot (no remaining tabs) clears the key rather than persisting
+    // an empty layout, matching the on-disk "no trace" semantics for emptiness.
+    let snapshot = state.captureLayoutSnapshot(agentsBySurface: agents)
+    saveLayoutSnapshot?(worktreeID, snapshot)
+    let change: LayoutsIncrementalWriter.Change = snapshot.map { .snapshot($0) } ?? .delete
+    let writer = layoutsWriter
+    let task = Task { [weak self] in
+      await writer.flush([worktreeID.rawValue: change])
+      self?.layoutFlushTasks[worktreeID] = nil
+    }
+    layoutFlushTasks[worktreeID] = task
+  }
+
+  /// Removes `worktreeID` from disk immediately, bypassing the debounce and
+  /// cancelling any queued positive save so a stale snapshot can't resurrect a
+  /// removed worktree. Awaits any in-flight positive flush for the key first so
+  /// the `.delete` always reaches the writer after the `.snapshot`.
+  private func deleteLayoutSnapshot(worktreeID: Worktree.ID) {
+    layoutDirtyTasks[worktreeID]?.cancel()
+    layoutDirtyTasks[worktreeID] = nil
+    saveLayoutSnapshot?(worktreeID, nil)
+    let inflightFlush = layoutFlushTasks[worktreeID]
+    let writer = layoutsWriter
+    // We await inflightFlush so the .delete lands after any in-flight positive
+    // flush; prune also drops the id from states synchronously before any later
+    // saveAllLayoutSnapshots, so no positive snapshot is re-emitted.
+    let task = Task { [weak self] in
+      await inflightFlush?.value
+      await writer.flush([worktreeID.rawValue: .delete])
+      self?.layoutFlushTasks[worktreeID] = nil
+    }
+    layoutFlushTasks[worktreeID] = task
+  }
+
+  /// Cancels every queued incremental save. Called before the on-quit
+  /// synchronous flush becomes the terminal write.
+  func cancelPendingLayoutSaves() {
+    for task in layoutDirtyTasks.values { task.cancel() }
+    layoutDirtyTasks.removeAll()
+    // Best-effort cancel: an already-started flush has no cancellation
+    // checkpoint in `applyAndWrite`, so it runs to completion. The writer's lock
+    // plus the atomic temp+rename keep the on-quit write from tearing; the worst
+    // case is a stale-but-valid key set on the next launch, never a corrupt file.
+    for task in layoutFlushTasks.values { task.cancel() }
+    layoutFlushTasks.removeAll()
+  }
+
   /// Tears down persistent zmx sessions for worktrees that just left the keep set.
   /// Parallel kill so a single stuck daemon doesn't pin the executor for
   /// `subprocessTimeout * N` (the bound is now one timeout regardless of N).
@@ -567,18 +728,33 @@ final class WorktreeTerminalManager {
   /// would survive forever.
   func terminateAllSessions() async {
     let trackedSurfaceIDs = states.values.flatMap(\.allSurfaceIDs)
-    let trackedSessionIDs = trackedSurfaceIDs.map(ZmxSessionID.make(surfaceID:))
+    let trackedSessionIDs = Set(trackedSurfaceIDs.map(ZmxSessionID.make(surfaceID:)))
     for state in states.values {
       state.closeAllSurfaces()
     }
     emitHasAnyTerminalSurfaceIfNeeded()
-    let liveSessions = await zmxClient.listSessions()
-    let allSessions = Array(Set(trackedSessionIDs).union(liveSessions))
+    // This instance's tracked sessions are always killed. The orphan subset
+    // (live and untracked) is attach-aware: spared when a client is attached or
+    // the count is unknown, so a concurrently-running instance keeps its
+    // sessions. Orphan reaping is therefore eventually consistent: the last
+    // instance to quit with no live clients sweeps what remains.
+    let liveSessions = await zmxClient.listSessionsWithClients()
+    let orphanSessions: [String]
+    if let liveSessions {
+      orphanSessions = liveSessions.filter { entry in
+        !trackedSessionIDs.contains(entry.name) && entry.clients == 0
+      }
+      .map(\.name)
+    } else {
+      // nil = UNKNOWN probe; still force-kill tracked, but skip the orphan sweep.
+      terminalLogger.info("Skipping quit-time orphan sweep: zmx session probe unavailable")
+      orphanSessions = []
+    }
+    let allSessions = Array(trackedSessionIDs.union(orphanSessions))
     guard !allSessions.isEmpty else { return }
-    let orphanCount = Set(allSessions).subtracting(trackedSessionIDs).count
     analyticsClient.capture(
       "terminal_persistence_session_killed",
-      ["reason": "user_quit", "count": allSessions.count, "orphan_count": orphanCount]
+      ["reason": "user_quit", "count": allSessions.count, "orphan_count": orphanSessions.count]
     )
     let client = zmxClient
     await withTaskGroup(of: Void.self) { group in
@@ -589,11 +765,22 @@ final class WorktreeTerminalManager {
   }
 
   /// Reaps `supa-*` sessions zmx hosts that no persisted layout claims;
-  /// catches orphans from crashes / force-quits.
+  /// catches orphans from crashes / force-quits. Attach-aware: a session with
+  /// a live client (another Supacode instance or a manual `zmx attach`) is
+  /// spared, and a failed probe reaps nothing.
   func reapOrphanSessions(knownSurfaceIDs: Set<UUID>) async {
-    let liveSessions = await zmxClient.listSessions()
+    guard let liveSessions = await zmxClient.listSessionsWithClients() else {
+      // nil = UNKNOWN (probe failed / timed out); never reap on no signal.
+      terminalLogger.info("Skipping orphan reap: zmx session probe unavailable")
+      return
+    }
     let knownSessionIDs = Set(knownSurfaceIDs.map(ZmxSessionID.make(surfaceID:)))
-    let orphans = Set(liveSessions).subtracting(knownSessionIDs)
+    // Only reap orphans we positively know have zero attached clients; spare
+    // clients>0 (in use) and clients==nil (unknown count).
+    let orphans = liveSessions.filter { entry in
+      !knownSessionIDs.contains(entry.name) && entry.clients == 0
+    }
+    .map(\.name)
     guard !orphans.isEmpty else { return }
     terminalLogger.info("Reaping \(orphans.count) orphan zmx session(s)")
     analyticsClient.capture(
@@ -672,9 +859,22 @@ final class WorktreeTerminalManager {
       assertionFailure("saveLayoutSnapshot closure not configured.")
       return
     }
+    // The actor is the sole disk writer (`LayoutsKey.save` is a no-op), so the
+    // on-quit terminal write goes through `flushSync` while still updating the
+    // in-memory `@Shared` dict via `saveLayoutSnapshot` for any live readers.
+    var changes: [String: LayoutsIncrementalWriter.Change] = [:]
     for (id, state) in states {
-      saveLayoutSnapshot(id, state.captureLayoutSnapshot(agentsBySurface: agentsBySurface))
+      let snapshot = state.captureLayoutSnapshot(agentsBySurface: agentsBySurface)
+      saveLayoutSnapshot(id, snapshot)
+      changes[id.rawValue] = snapshot.map { .snapshot($0) } ?? .delete
     }
+    layoutsWriter.flushSync(changes)
+  }
+
+  /// Capture the selected worktree's zoom at quit (no switch fires then).
+  func rememberSelectedWorktreeZoomOnQuit() {
+    guard let selectedWorktreeID, let state = states[selectedWorktreeID] else { return }
+    state.rememberFocusedZoom()
   }
 
   func surfaceBackgroundColorScheme() -> ColorScheme {
@@ -689,10 +889,69 @@ final class WorktreeTerminalManager {
 
   private func emit(_ event: TerminalClient.Event) {
     guard let eventContinuation else {
+      bufferPendingEvent(event)
+      return
+    }
+    if let key = Self.coalesceKey(for: event) {
+      guard lastEmittedCoalescable[key] != event else { return }
+      lastEmittedCoalescable[key] = event
+    }
+    // During prune this fires first and clears the coalesce keys; invalidateCaches
+    // then runs second only to clear the worktree-keyed lastEmittedProjections.
+    for key in Self.invalidatedCoalesceKeys(by: event) {
+      lastEmittedCoalescable.removeValue(forKey: key)
+    }
+    let result = eventContinuation.yield(event)
+    if case .dropped(let shed) = result {
+      terminalLogger.error(
+        "Terminal event buffer full (cap \(Self.eventBufferCap)); shed oldest buffered event: \(Self.label(for: shed))."
+      )
+    }
+  }
+
+  /// Buffers an event emitted before a subscriber attaches. Coalescable state
+  /// keeps only its latest value per key; lifecycle events accumulate up to a
+  /// cap, dropping the oldest so the pre-subscription buffer stays bounded.
+  private func bufferPendingEvent(_ event: TerminalClient.Event) {
+    if let key = Self.coalesceKey(for: event) {
+      pendingEvents.removeAll { Self.coalesceKey(for: $0) == key }
       pendingEvents.append(event)
       return
     }
-    eventContinuation.yield(event)
+    // Mirror the live-path teardown purge so a buffered projection for a
+    // torn-down id can't replay ahead of its teardown on resubscribe.
+    let invalidated = Set(Self.invalidatedCoalesceKeys(by: event))
+    if !invalidated.isEmpty {
+      pendingEvents.removeAll { Self.coalesceKey(for: $0).map(invalidated.contains) ?? false }
+    }
+    if pendingEvents.count >= Self.pendingEventCap {
+      let dropped = pendingEvents.removeFirst()
+      terminalLogger.error(
+        "Pending terminal event buffer full (cap \(Self.pendingEventCap)); dropped oldest: \(Self.label(for: dropped))."
+      )
+    }
+    pendingEvents.append(event)
+  }
+
+  /// Coalesce keys a teardown event invalidates. A coalesced value for a removed
+  /// tab / worktree must not linger: a same-id reuse (snapshot restore reuses
+  /// persisted tab UUIDs) would otherwise be wrongly deduped and dropped.
+  private static func invalidatedCoalesceKeys(by event: TerminalClient.Event) -> [CoalesceKey] {
+    switch event {
+    case .tabRemoved(_, let tabID): [.tabProjection(tabID), .tabProgress(tabID)]
+    case .worktreeStateTornDown(let worktreeID):
+      [.worktreeProjection(worktreeID), .taskStatus(worktreeID), .focus(worktreeID)]
+    default: []
+    }
+  }
+
+  /// Clears the worktree-keyed lastEmittedProjections during prune; emit's purge has
+  /// already cleared the coalesce keys, which this re-clears as a guard against drift.
+  private func invalidateCaches(forPrunedWorktree id: Worktree.ID) {
+    lastEmittedProjections.removeValue(forKey: id)
+    for key in Self.invalidatedCoalesceKeys(by: .worktreeStateTornDown(worktreeID: id)) {
+      lastEmittedCoalescable.removeValue(forKey: key)
+    }
   }
 
   private func emitNotificationIndicatorCountIfNeeded() {
diff --git a/supacode/Features/Terminal/Models/BlockingScriptKind.swift b/supacode/Features/Terminal/Models/BlockingScriptKind.swift
index edb8630ea..1a49d49e8 100644
--- a/supacode/Features/Terminal/Models/BlockingScriptKind.swift
+++ b/supacode/Features/Terminal/Models/BlockingScriptKind.swift
@@ -55,6 +55,24 @@ enum BlockingScriptKind: Sendable {
     case .archive, .delete: false
     }
   }
+
+  /// Surface env vars that let the user's shell profile detect a blocking-script
+  /// tab and skip its interactive init (prompt, plugins, banners). `scope` is
+  /// resolved by the caller and only emitted for user-defined scripts.
+  func surfaceEnvironmentVariables(scope: ScriptScope?) -> [String: String] {
+    var env = ["SUPACODE_BLOCKING_SCRIPT": "1"]
+    switch self {
+    case .script(let definition):
+      env["SUPACODE_SCRIPT_ID"] = definition.id.uuidString
+      env["SUPACODE_SCRIPT_KIND"] = definition.kind.rawValue
+      if let scope { env["SUPACODE_SCRIPT_SCOPE"] = scope.rawValue }
+    case .archive:
+      env["SUPACODE_SCRIPT_KIND"] = "archive"
+    case .delete:
+      env["SUPACODE_SCRIPT_KIND"] = "delete"
+    }
+    return env
+  }
 }
 
 // MARK: - Hashable / Equatable
diff --git a/supacode/Features/Terminal/Models/WorktreeTerminalState.swift b/supacode/Features/Terminal/Models/WorktreeTerminalState.swift
index 79988c656..8552921d1 100644
--- a/supacode/Features/Terminal/Models/WorktreeTerminalState.swift
+++ b/supacode/Features/Terminal/Models/WorktreeTerminalState.swift
@@ -22,19 +22,23 @@ struct WorktreeTabProjection: Equatable, Sendable {
   let activeSurfaceID: UUID?
   let unseenNotificationCount: Int
   let isSplitZoomed: Bool
+  /// Per-tab repaint epoch, bumped on same-UUID surface replacement so the view rebuilds.
+  let surfaceGeneration: Int
 
   init(
     tabID: TerminalTabID,
     surfaceIDs: [UUID],
     activeSurfaceID: UUID?,
     unseenNotificationCount: Int,
-    isSplitZoomed: Bool = false
+    isSplitZoomed: Bool = false,
+    surfaceGeneration: Int = 0,
   ) {
     self.tabID = tabID
     self.surfaceIDs = surfaceIDs
     self.activeSurfaceID = activeSurfaceID
     self.unseenNotificationCount = unseenNotificationCount
     self.isSplitZoomed = isSplitZoomed
+    self.surfaceGeneration = surfaceGeneration
   }
 }
 
@@ -46,6 +50,11 @@ final class WorktreeTerminalState {
     let isFocused: Bool
   }
 
+  private struct SurfaceLaunchMetadata {
+    let usesZmx: Bool
+    let context: ghostty_surface_context_e
+  }
+
   let tabManager: TerminalTabManager
   private let runtime: GhosttyRuntime
   @ObservationIgnored private let splitPreserveZoomOnNavigation: () -> Bool
@@ -57,6 +66,11 @@ final class WorktreeTerminalState {
   // `surfaceStates` / `WorktreeTabProjection` to keep agent storms cold.
   private var trees: [TerminalTabID: SplitTree<GhosttySurfaceView>] = [:]
   @ObservationIgnored private var surfaces: [UUID: GhosttySurfaceView] = [:]
+  // `usesZmx` + `context` retained per surface so an unexpected zmx exit can recreate it on reattach.
+  @ObservationIgnored private var surfaceLaunchMetadata: [UUID: SurfaceLaunchMetadata] = [:]
+  // Surfaces the user explicitly closed, so an unexpected zmx exit isn't mistaken for one and reattached.
+  @ObservationIgnored private var pendingExplicitSurfaceCloseIDs: Set<UUID> = []
+  @ObservationIgnored private var surfaceGenerationByTab: [TerminalTabID: Int] = [:]
   @ObservationIgnored private var focusedSurfaceIdByTab: [TerminalTabID: UUID] = [:]
   /// Per-tab projection cache. `WorktreeTerminalState` recomputes from `trees`
   /// / `notifications` / `focusedSurfaceIdByTab`, compares to the cached value,
@@ -92,7 +106,41 @@ final class WorktreeTerminalState {
   @ObservationIgnored @Dependency(\.date.now) private var now
   @ObservationIgnored @Dependency(\.zmxClient) private var zmxClient
   @ObservationIgnored @Dependency(\.analyticsClient) private var analyticsClient
-  private var recentHookBySurfaceID: [UUID: (text: String, recordedAt: Date)] = [:]
+  @ObservationIgnored @Dependency(\.continuousClock) private var clock
+  /// When a custom (hook / OSC 3008) notification last committed per surface.
+  /// Stored as a monotonic instant so the suppression window and the OSC-9 hold
+  /// share one clock source and can't desync on an NTP step / manual clock change.
+  private var lastCustomNotificationAt: [UUID: any InstantProtocol<Duration>] = [:]
+  /// Agent OSC 9 notifications held to see if a custom notification supersedes them.
+  private var pendingAgentOSCNotifications: [UUID: Task<Void, Never>] = [:]
+  /// How long after a custom notification the agent's own OSC 9 is suppressed.
+  /// Split from `oscHoldWindow` so tuning the suppression side cannot silently
+  /// change the hold side.
+  private static let oscSuppressionAfterCustom: TimeInterval = 0.5
+  /// How long the agent's own OSC 9 is held before firing, waiting for a custom
+  /// notification to supersede it. Covers the socket-vs-inline-stream arrival skew.
+  private static let oscHoldWindow: TimeInterval = 0.5
+  /// Monotonic gap between two instants from the same clock. Opens the existentials
+  /// so the suppression window can compare instants of the type-erased clock.
+  private static func elapsed(
+    from start: any InstantProtocol<Duration>,
+    to end: any InstantProtocol<Duration>
+  ) -> Duration {
+    func gap<I: InstantProtocol>(_ start: I, _ end: any InstantProtocol<Duration>) -> Duration
+    where I.Duration == Duration {
+      guard let end = end as? I else {
+        // Fail OPEN: a type mismatch must not pin the dedupe window true forever.
+        assertionFailure("clock instant type mismatch")
+        return .seconds(Self.oscSuppressionAfterCustom + 1)
+      }
+      return start.duration(to: end)
+    }
+    return gap(start, end)
+  }
+  #if DEBUG
+    var debugCustomNotificationTimestampCount: Int { lastCustomNotificationAt.count }
+    var debugPendingOSCCount: Int { pendingAgentOSCNotifications.count }
+  #endif
   var hasUnseenNotification: Bool {
     notifications.contains { !$0.isRead }
   }
@@ -117,16 +165,14 @@ final class WorktreeTerminalState {
     notifications.filter { !$0.isRead }.sorted { $0.createdAt > $1.createdAt }
   }
 
-  #if DEBUG
-    var debugRecentHookCount: Int {
-      recentHookBySurfaceID.count
-    }
-  #endif
   var isSelected: () -> Bool = { false }
   var onNotificationReceived: ((UUID, String, String) -> Void)?
   var onNotificationIndicatorChanged: (() -> Void)?
   var onTabCreated: (() -> Void)?
   var onTabClosed: (() -> Void)?
+  /// Fires when the user renames a tab. Manager forwards to the layout-persist
+  /// sink so a custom title survives relaunch without waiting for quit.
+  var onTabRenamed: (() -> Void)?
   var onFocusChanged: ((UUID) -> Void)?
   var onTaskStatusChanged: ((WorktreeTaskStatus) -> Void)?
   var onBlockingScriptCompleted: ((BlockingScriptKind, Int?, TerminalTabID?) -> Void)?
@@ -134,6 +180,9 @@ final class WorktreeTerminalState {
   var onSetupScriptConsumed: (() -> Void)?
   /// Forwarded to the manager so it can emit a `surfacesClosed` event into TCA.
   var onSurfacesClosed: ((Set<UUID>) -> Void)?
+  /// Forwarded to the manager's `dispatchHookEvent` so an OSC-sourced presence
+  /// event joins the same funnel as the socket path (idle-debounce, badge).
+  var onAgentHookEvent: ((AgentHookEvent) -> Void)?
   /// Fires when a tab's per-tab projection (surfaces / focus / unseen count)
   /// drifts. Manager forwards into `TerminalTabFeature.State` via
   /// `tabProjectionChanged` so the leaf observes a per-tab store.
@@ -159,7 +208,7 @@ final class WorktreeTerminalState {
     self.tabManager = TerminalTabManager()
     _repositorySettings = SharedReader(
       wrappedValue: RepositorySettings.default,
-      .repositorySettings(worktree.repositoryRootURL)
+      .repositorySettings(worktree.repositoryRootURL, host: worktree.host)
     )
     // Pre-hide the tab bar before the first tab is created to
     // avoid a visible flash. updateShouldHideTabBar() handles
@@ -322,14 +371,37 @@ final class WorktreeTerminalState {
 
   @discardableResult
   func runBlockingScript(kind: BlockingScriptKind, _ script: String) -> TerminalTabID? {
-    let launch: BlockingScriptRunner.LaunchArtifacts
-    do {
-      guard let prepared = try blockingScriptLaunch(script) else { return nil }
-      launch = prepared
-    } catch {
-      blockingScriptLogger.warning("Failed to prepare \(kind.tabTitle) for worktree \(worktree.id): \(error)")
-      onBlockingScriptCompleted?(kind, 1, nil)
-      return nil
+    // Resolve the surface command per host. A remote worktree runs the same
+    // OSC 133 framing on the host over ssh (no local temp files, no zmx wrap),
+    // so the script executes on the remote and not on a same-path local dir.
+    let command: String
+    let initialInput: String?
+    let launchDirectory: URL?
+    if let host = worktree.host {
+      guard
+        let remote = BlockingScriptRunner.remoteCommand(
+          host: host,
+          script: script,
+          remoteWorktreePath: worktree.workingDirectory.path(percentEncoded: false),
+          environment: blockingScriptEnvironment(for: kind)
+        )
+      else { return nil }
+      command = remote
+      initialInput = nil
+      launchDirectory = nil
+    } else {
+      let launch: BlockingScriptRunner.LaunchArtifacts
+      do {
+        guard let prepared = try blockingScriptLaunch(script) else { return nil }
+        launch = prepared
+      } catch {
+        blockingScriptLogger.warning("Failed to prepare \(kind.tabTitle) for worktree \(worktree.id): \(error)")
+        onBlockingScriptCompleted?(kind, 1, nil)
+        return nil
+      }
+      command = defaultShellPath()
+      initialInput = launch.commandInput
+      launchDirectory = launch.directoryURL
     }
     // Close any previous tab of the same kind (active or lingering
     // from a completed/cancelled run). Clear tracking state first
@@ -347,24 +419,28 @@ final class WorktreeTerminalState {
         icon: kind.tabIcon,
         isTitleLocked: true,
         tintColor: kind.tabColor,
-        command: defaultShellPath(),
-        initialInput: launch.commandInput,
+        command: command,
+        initialInput: initialInput,
         focusing: true,
         inheritingFromSurfaceId: currentFocusedSurfaceId(),
         context: GHOSTTY_SURFACE_CONTEXT_TAB,
         tabID: nil,
         isBlockingScript: true,
+        blockingScriptKind: kind,
         bypassZmx: true,
       )
     )
     guard let tabId else {
-      cleanupBlockingScriptLaunchDirectory(at: launch.directoryURL)
+      if let launchDirectory {
+        cleanupBlockingScriptLaunchDirectory(at: launchDirectory)
+      }
       blockingScriptLogger.warning("Failed to create \(kind.tabTitle) tab for worktree \(worktree.id)")
       onBlockingScriptCompleted?(kind, 1, nil)
       return nil
     }
-    blockingScripts[tabId] = kind
-    blockingScriptLaunchDirectories[tabId] = launch.directoryURL
+    if let launchDirectory {
+      blockingScriptLaunchDirectories[tabId] = launchDirectory
+    }
     lastBlockingScriptTabByKind[kind] = tabId
     tabManager.updateDirty(tabId, isDirty: true)
     emitTaskStatusIfChanged()
@@ -387,6 +463,9 @@ final class WorktreeTerminalState {
     /// Marks the tab as a blocking-script tab so the no-split / no-rename
     /// / readonly-after-completion guardrails apply.
     var isBlockingScript: Bool = false
+    /// The blocking-script kind, recorded into `blockingScripts` before the
+    /// surface is built so `surfaceEnvironment` can emit its env markers.
+    var blockingScriptKind: BlockingScriptKind?
     /// Skip zmx session wrapping for transactional surfaces (blocking setup/archive/delete scripts)
     /// that must die with the app rather than survive.
     var bypassZmx: Bool = false
@@ -401,6 +480,11 @@ final class WorktreeTerminalState {
       isBlockingScript: creation.isBlockingScript,
       id: creation.tabID,
     )
+    // Record the kind before the surface is built so `surfaceEnvironment`
+    // can read it when emitting the blocking-script env markers.
+    if let blockingScriptKind = creation.blockingScriptKind {
+      blockingScripts[tabId] = blockingScriptKind
+    }
     // When a tab ID is explicitly provided, use it as the initial surface ID
     // so the CLI can reference the surface immediately after creation.
     let tree = splitTree(
@@ -445,6 +529,17 @@ final class WorktreeTerminalState {
     trees.values.flatMap { $0.leaves().map(\.id) }
   }
 
+  // Standardized to match `loadFailuresByID` keys (built from `standardizedFileURL.path`)
+  // so prune protection lines up.
+  var repositoryID: Repository.ID {
+    switch worktree.location.repositoryLocation {
+    case .local(let url):
+      RepositoryID(url.standardizedFileURL.path(percentEncoded: false))
+    case .remote:
+      worktree.location.repositoryLocation.id
+    }
+  }
+
   /// O(1) emptiness check that skips the split-tree walk in `allSurfaceIDs`.
   var hasAnySurface: Bool { !surfaces.isEmpty }
 
@@ -568,7 +663,7 @@ final class WorktreeTerminalState {
     else {
       return false
     }
-    surface.performBindingAction("close_surface")
+    requestExplicitSurfaceClose(surface)
     return true
   }
 
@@ -579,10 +674,14 @@ final class WorktreeTerminalState {
         "closeSurface: surface \(surfaceID) not found. Known: \(surfaces.keys.map(\.uuidString))")
       return false
     }
-    surface.performBindingAction("close_surface")
+    requestExplicitSurfaceClose(surface)
     return true
   }
 
+  private func requestExplicitSurfaceClose(_ surface: GhosttySurfaceView) {
+    performBindingAction("close_surface", on: surface)
+  }
+
   @discardableResult
   func performBindingActionOnFocusedSurface(_ action: String) -> Bool {
     guard let tabId = tabManager.selectedTabId,
@@ -591,17 +690,24 @@ final class WorktreeTerminalState {
     else {
       return false
     }
-    surface.performBindingAction(action)
+    performBindingAction(action, on: surface)
     return true
   }
 
   @discardableResult
   func performBindingAction(_ action: String, onSurfaceID surfaceID: UUID) -> Bool {
     guard let surface = surfaces[surfaceID] else { return false }
-    surface.performBindingAction(action)
+    performBindingAction(action, on: surface)
     return true
   }
 
+  private func performBindingAction(_ action: String, on surface: GhosttySurfaceView) {
+    if action == "close_surface" {
+      pendingExplicitSurfaceCloseIDs.insert(surface.id)
+    }
+    surface.performBindingAction(action)
+  }
+
   @discardableResult
   func navigateSearchOnFocusedSurface(_ direction: GhosttySearchDirection) -> Bool {
     guard let tabId = tabManager.selectedTabId,
@@ -638,6 +744,14 @@ final class WorktreeTerminalState {
     onTabClosed?()
   }
 
+  /// User-initiated rename. Routes through the manager so the new title (or its
+  /// removal on an empty commit) persists incrementally, unlike the restore path
+  /// which seeds `setCustomTitle` directly from a snapshot.
+  func renameTab(_ tabId: TerminalTabID, title: String) {
+    tabManager.setCustomTitle(tabId, title: title)
+    onTabRenamed?()
+  }
+
   func closeOtherTabs(keeping tabId: TerminalTabID) {
     let ids = tabManager.tabs.map(\.id).filter { $0 != tabId }
     for id in ids {
@@ -726,7 +840,7 @@ final class WorktreeTerminalState {
         terminalStateLogger.warning(
           "performSplitAction: failed to insert split for surface \(surfaceID) in tab \(tabId.rawValue): \(error)")
         newSurface.closeSurface()
-        surfaces.removeValue(forKey: newSurface.id)
+        discardSurfaceBookkeeping(for: newSurface.id)
         return false
       }
 
@@ -824,13 +938,17 @@ final class WorktreeTerminalState {
   }
 
   func closeAllSurfaces() {
-    let closingSurfaceIDs = Array(surfaces.keys)
-    for surface in surfaces.values {
+    let closingSurfaces = Array(surfaces.values)
+    let closingSurfaceIDs = closingSurfaces.map(\.id)
+    for surface in closingSurfaces {
       surface.closeSurface()
     }
+    for surfaceID in closingSurfaceIDs {
+      discardSurfaceBookkeeping(for: surfaceID)
+    }
     cleanupBlockingScriptLaunchDirectories()
-    surfaces.removeAll()
     trees.removeAll()
+    surfaceGenerationByTab.removeAll()
     focusedSurfaceIdByTab.removeAll()
     onSurfacesClosed?(Set(closingSurfaceIDs))
     let pendingKinds = Set(blockingScripts.values)
@@ -863,17 +981,15 @@ final class WorktreeTerminalState {
   }
 
   func markAllNotificationsRead() {
-    let previousHasUnseen = hasUnseenNotification
     for index in notifications.indices {
       notifications[index].isRead = true
     }
     clearAllSurfaceUnseenFlags()
     emitAllTabProjections()
-    emitNotificationIndicatorIfNeeded(previousHasUnseen: previousHasUnseen)
+    emitNotificationStateChanged()
   }
 
   func markNotificationsRead(forSurfaceID surfaceID: UUID) {
-    let previousHasUnseen = hasUnseenNotification
     for index in notifications.indices where notifications[index].surfaceID == surfaceID {
       notifications[index].isRead = true
     }
@@ -881,12 +997,11 @@ final class WorktreeTerminalState {
     if let tabId = tabID(containing: surfaceID) {
       emitTabProjection(for: tabId)
     }
-    emitNotificationIndicatorIfNeeded(previousHasUnseen: previousHasUnseen)
+    emitNotificationStateChanged()
   }
 
   /// Marks a single notification as read, leaving others untouched.
   func markNotificationRead(id: WorktreeTerminalNotification.ID) {
-    let previousHasUnseen = hasUnseenNotification
     guard let index = notifications.firstIndex(where: { $0.id == id }) else { return }
     guard !notifications[index].isRead else { return }
     let surfaceID = notifications[index].surfaceID
@@ -895,11 +1010,10 @@ final class WorktreeTerminalState {
     if let tabId = tabID(containing: surfaceID) {
       emitTabProjection(for: tabId)
     }
-    emitNotificationIndicatorIfNeeded(previousHasUnseen: previousHasUnseen)
+    emitNotificationStateChanged()
   }
 
   func dismissNotification(_ notificationID: WorktreeTerminalNotification.ID) {
-    let previousHasUnseen = hasUnseenNotification
     let affectedSurface = notifications.first(where: { $0.id == notificationID })?.surfaceID
     notifications.removeAll { $0.id == notificationID }
     if let affectedSurface {
@@ -908,15 +1022,14 @@ final class WorktreeTerminalState {
         emitTabProjection(for: tabId)
       }
     }
-    emitNotificationIndicatorIfNeeded(previousHasUnseen: previousHasUnseen)
+    emitNotificationStateChanged()
   }
 
   func dismissAllNotifications() {
-    let previousHasUnseen = hasUnseenNotification
     notifications.removeAll()
     clearAllSurfaceUnseenFlags()
     emitAllTabProjections()
-    emitNotificationIndicatorIfNeeded(previousHasUnseen: previousHasUnseen)
+    emitNotificationStateChanged()
   }
 
   /// Recomputes the surface's unseen flag through the canonical predicate so a
@@ -1161,7 +1274,7 @@ final class WorktreeTerminalState {
     } catch {
       layoutLogger.warning("Failed to restore split for tab \(tabId.rawValue): \(error)")
       newSurface.closeSurface()
-      surfaces.removeValue(forKey: newSurface.id)
+      discardSurfaceBookkeeping(for: newSurface.id)
       return nil
     }
   }
@@ -1277,12 +1390,17 @@ final class WorktreeTerminalState {
     let repoPath = worktree.repositoryRootURL.path(percentEncoded: false)
     env["SUPACODE_REPO_ID"] = percentEncode(repoPath, allowedCharacters: percentEncodingSet, label: "SUPACODE_REPO_ID")
     env["SUPACODE_WORKTREE_ID"] = percentEncode(
-      worktree.id, allowedCharacters: percentEncodingSet, label: "SUPACODE_WORKTREE_ID")
+      worktree.id.rawValue, allowedCharacters: percentEncodingSet, label: "SUPACODE_WORKTREE_ID")
     env["SUPACODE_TAB_ID"] = tabId.rawValue.uuidString
     env["SUPACODE_SURFACE_ID"] = surfaceID.uuidString
     if let socketPath {
       env["SUPACODE_SOCKET_PATH"] = socketPath
     }
+    // Mark blocking-script surfaces so the user's shell profile can skip its
+    // interactive init (prompt, plugins, banners) for these transient tabs.
+    if let blockingScriptKind = blockingScripts[tabId] {
+      env.merge(blockingScriptEnvironment(for: blockingScriptKind)) { _, new in new }
+    }
     // Lock ZMX_DIR to the value the app's probe used so the shell can't
     // re-export a different value from .zshrc / .zprofile and silently
     // overflow `sockaddr_un.sun_path` past the probe's check.
@@ -1299,6 +1417,25 @@ final class WorktreeTerminalState {
     return env
   }
 
+  /// Blocking-script marker env vars for a kind, with scope resolved against
+  /// this worktree's settings. Shared by the local surface environment and the
+  /// remote runner export so both hosts expose the same signal.
+  private func blockingScriptEnvironment(for kind: BlockingScriptKind) -> [String: String] {
+    let scope = kind.scriptDefinitionID.flatMap(scriptScope(forDefinitionID:))
+    return kind.surfaceEnvironmentVariables(scope: scope)
+  }
+
+  /// Resolves whether a user-defined script is repo- or global-owned, mirroring
+  /// the repo-wins merge: an ID present in repo settings is `.repo`, otherwise
+  /// `.global`. Returns `nil` for a script that resolves to neither (e.g. a
+  /// since-deleted deeplink target).
+  private func scriptScope(forDefinitionID id: UUID) -> ScriptScope? {
+    if repositorySettings.scripts.contains(where: { $0.id == id }) { return .repo }
+    @Shared(.settingsFile) var settingsFile
+    if settingsFile.global.globalScripts.contains(where: { $0.id == id }) { return .global }
+    return nil
+  }
+
   private func percentEncode(_ value: String, allowedCharacters: CharacterSet, label: String) -> String {
     guard let encoded = value.addingPercentEncoding(withAllowedCharacters: allowedCharacters) else {
       terminalStateLogger.warning(
@@ -1316,11 +1453,12 @@ final class WorktreeTerminalState {
     inheritingFromSurfaceId: UUID?,
     context: ghostty_surface_context_e,
     surfaceID: UUID? = nil,
-    bypassZmx: Bool = false
+    bypassZmx: Bool = false,
+    replacingExistingSurfaceID: Bool = false,
   ) -> GhosttySurfaceView {
     let resolvedID: UUID
     if let requested = surfaceID {
-      if surfaces[requested] != nil {
+      if surfaces[requested] != nil, !replacingExistingSurfaceID {
         terminalStateLogger.warning("Duplicate surface ID \(requested), generating a new one.")
         resolvedID = UUID()
       } else {
@@ -1332,24 +1470,36 @@ final class WorktreeTerminalState {
     let surfaceID = resolvedID
     terminalStateLogger.info("createSurface: resolved=\(surfaceID)")
     let inherited = inheritedSurfaceConfig(fromSurfaceId: inheritingFromSurfaceId, context: context)
-    let (resolvedCommand, resolvedInitialInput) = resolveZmxWrapping(
+    let launch = resolveLaunch(
       surfaceID: surfaceID,
       command: command,
       initialInput: initialInput,
-      bypassZmx: bypassZmx
+      bypassZmx: bypassZmx,
     )
+    // Remote worktrees have no local working directory: the surface command is
+    // an `ssh …` line (see `resolveLaunch`) and the cwd lives on the
+    // remote, so leave `working_directory` nil and let the remote shell `cd`.
+    let resolvedWorkingDirectory: URL? =
+      worktree.host == nil
+      ? (workingDirectoryOverride ?? inherited.workingDirectory ?? worktree.workingDirectory)
+      : nil
     let view = GhosttySurfaceView(
       id: surfaceID,
       runtime: runtime,
-      workingDirectory: workingDirectoryOverride ?? inherited.workingDirectory ?? worktree.workingDirectory,
-      command: resolvedCommand,
-      initialInput: resolvedInitialInput,
+      workingDirectory: resolvedWorkingDirectory,
+      command: launch.command,
+      initialInput: launch.initialInput,
       environmentVariables: surfaceEnvironment(tabId: tabId, surfaceID: surfaceID),
-      fontSize: inherited.fontSize,
+      commandWrapper: launch.commandWrapper,
+      // Blocking-script runners (bypassZmx) emit their own OSC 133/7 and must
+      // not get Ghostty's shell integration injected into the host shell.
+      disableShellIntegration: bypassZmx,
+      fontSize: inherited.fontSize ?? rememberedZoomFontSize,
       context: context
     )
-    wireSurfaceCallbacks(view: view, tabId: tabId, surfaceID: surfaceID)
+    wireSurfaceCallbacks(view: view, tabId: tabId)
     surfaces[view.id] = view
+    surfaceLaunchMetadata[view.id] = SurfaceLaunchMetadata(usesZmx: launch.usesZmx, context: context)
     surfaceStates[view.id] = WorktreeSurfaceState()
     return view
   }
@@ -1359,55 +1509,81 @@ final class WorktreeTerminalState {
   /// weak view]` so the count adds up fast.
   private func wireSurfaceCallbacks(
     view: GhosttySurfaceView,
-    tabId: TerminalTabID,
-    surfaceID: UUID
+    tabId: TerminalTabID
+  ) {
+    wireSurfaceTabCallbacks(view: view, tabId: tabId)
+    wireSurfaceLifecycleCallbacks(view: view, tabId: tabId)
+  }
+
+  /// Tab / title / split callbacks. Split from `wireSurfaceLifecycleCallbacks`
+  /// so each stays under swiftlint's cyclomatic-complexity cap.
+  private func wireSurfaceTabCallbacks(
+    view: GhosttySurfaceView,
+    tabId: TerminalTabID
   ) {
     view.bridge.onTitleChange = { [weak self, weak view] title in
       guard let self, let view else { return }
+      guard self.isLiveSurface(view) else { return }
       if self.focusedSurfaceIdByTab[tabId] == view.id {
         self.tabManager.updateTitle(tabId, title: title)
       }
     }
-    view.bridge.onPromptTitle = { [weak self] in
-      self?.tabManager.beginTabRename(tabId)
+    view.bridge.onPromptTitle = { [weak self, weak view] in
+      guard let self, let view, self.isLiveSurface(view) else { return }
+      self.tabManager.beginTabRename(tabId)
     }
     view.bridge.onSplitAction = { [weak self, weak view] action in
       guard let self, let view else { return false }
+      guard self.isLiveSurface(view) else { return false }
       return self.performSplitAction(action, for: view.id)
     }
     view.bridge.onNewTab = { [weak self, weak view] in
       guard let self, let view else { return false }
+      guard self.isLiveSurface(view) else { return false }
       return self.createTab(inheritingFromSurfaceId: view.id) != nil
     }
-    view.bridge.onCloseTab = { [weak self] _ in
-      guard let self else { return false }
+    view.bridge.onCloseTab = { [weak self, weak view] _ in
+      guard let self, let view, self.isLiveSurface(view) else { return false }
       self.closeTab(tabId)
       return true
     }
-    view.bridge.onGotoTab = { [weak self] target in
-      guard let self else { return false }
+    view.bridge.onGotoTab = { [weak self, weak view] target in
+      guard let self, let view, self.isLiveSurface(view) else { return false }
       return self.handleGotoTabRequest(target)
     }
-    view.bridge.onCommandPaletteToggle = { [weak self] in
-      guard let self else { return false }
+    view.bridge.onCommandPaletteToggle = { [weak self, weak view] in
+      guard let self, let view, self.isLiveSurface(view) else { return false }
       self.onCommandPaletteToggle?()
       return true
     }
-    view.bridge.onProgressReport = { [weak self] _ in
-      guard let self else { return }
+  }
+
+  /// Progress / exit / notification / focus callbacks.
+  private func wireSurfaceLifecycleCallbacks(
+    view: GhosttySurfaceView,
+    tabId: TerminalTabID
+  ) {
+    view.bridge.onProgressReport = { [weak self, weak view] _ in
+      guard let self, let view, self.isLiveSurface(view) else { return }
       self.updateRunningState(for: tabId)
     }
-    view.bridge.onCommandFinished = { [weak self] exitCode in
-      guard let self else { return }
+    view.bridge.onCommandFinished = { [weak self, weak view] exitCode in
+      guard let self, let view, self.isLiveSurface(view) else { return }
       self.handleBlockingScriptCommandFinished(tabId: tabId, exitCode: exitCode)
     }
-    view.bridge.onChildExited = { [weak self] exitCode in
-      guard let self else { return }
+    view.bridge.onChildExited = { [weak self, weak view] exitCode in
+      guard let self, let view, self.isLiveSurface(view) else { return }
       self.handleBlockingScriptChildExited(tabId: tabId, exitCode: exitCode)
     }
     view.bridge.onDesktopNotification = { [weak self, weak view] title, body in
       guard let self, let view else { return }
-      self.appendNotification(title: title, body: body, surfaceID: view.id)
+      guard self.isLiveSurface(view) else { return }
+      self.handleAgentOSCNotification(title: title, body: body, surfaceID: view.id)
+    }
+    view.bridge.onContextSignal = { [weak self, weak view] _, id, metadata in
+      guard let self, let view else { return }
+      guard self.isLiveSurface(view) else { return }
+      self.handleContextSignal(surfaceID: view.id, id: id, metadata: metadata)
     }
     view.bridge.onCloseRequest = { [weak self, weak view] processAlive in
       guard let self, let view else { return }
@@ -1415,33 +1591,248 @@ final class WorktreeTerminalState {
     }
     view.onFocusChange = { [weak self, weak view] focused in
       guard let self, let view, focused else { return }
+      guard self.isLiveSurface(view) else { return }
       self.recordActiveSurface(view, in: tabId)
       self.emitTaskStatusIfChanged()
     }
-    view.shouldClaimFocus = { [weak self] in
-      guard let self else { return false }
-      return self.focusedSurfaceIdByTab[tabId] == surfaceID
+    view.shouldClaimFocus = { [weak self, weak view] in
+      guard let self, let view, self.isLiveSurface(view) else { return false }
+      return self.focusedSurfaceIdByTab[tabId] == view.id
+    }
+  }
+
+  // Identity, not key presence: a reattached surface keeps its UUID, so stale closures from the old view must no-op.
+  private func isLiveSurface(_ view: GhosttySurfaceView) -> Bool {
+    surfaces[view.id] === view
+  }
+
+  /// Routes an OSC 3008 context signal to the presence or notify handler.
+  private func handleContextSignal(surfaceID: UUID, id: String, metadata: String) {
+    // Route by notify INTENT, not by parse success, so a malformed notify logs as
+    // a notify drop rather than silently falling through to the presence handler.
+    if AgentPresenceOSC.isNotifyMetadata(metadata) {
+      handleNotifySignal(surfaceID: surfaceID, id: id, metadata: metadata)
+    } else {
+      handlePresenceSignal(surfaceID: surfaceID, id: id, metadata: metadata)
     }
   }
 
-  /// Wraps the surface command in `zmx attach <session-id>` so the underlying shell
-  /// survives app quit. `initialInput` is always passed through; zmx itself is
-  /// authoritative for attach-vs-create, so we never gate setup-script firing on
-  /// a stale snapshot of daemon state.
-  private func resolveZmxWrapping(
+  /// Verify an OSC 3008 presence signal against the receiving surface's nonce,
+  /// then synthesize an `AgentHookEvent` and forward it to the manager. Attribution
+  /// is by the receiving surface, so the wire never carries a surface id that could
+  /// spoof another worktree's badge; a pid rides along only for local hooks.
+  private func handlePresenceSignal(surfaceID: UUID, id: String, metadata: String) {
+    switch Self.presenceEvent(
+      id: id,
+      metadata: metadata,
+      surfaceID: surfaceID,
+      surfaceExists: surfaces[surfaceID] != nil
+    ) {
+    case .success(let event):
+      onAgentHookEvent?(event)
+    case .failure(.parseFailed):
+      // Malformed metadata on a live surface is probe-shaped; warn (mirrors notify).
+      terminalStateLogger.warning("Dropped malformed OSC presence signal for surface \(surfaceID).")
+    case .failure(.unknownSurface):
+      terminalStateLogger.debug("Dropped OSC presence signal for surface \(surfaceID).")
+    }
+  }
+
+  /// Typed reasons a presence signal was dropped, so the single call site can pick a
+  /// log severity per cause (warn for malformed, debug otherwise).
+  enum PresenceDrop: Error, Equatable {
+    case unknownSurface
+    case parseFailed
+  }
+
+  /// Pure decision for an OSC presence signal: returns an `AgentHookEvent`
+  /// attributed to the RECEIVING surface when the surface is known and the metadata
+  /// is well-formed; otherwise a typed `PresenceDrop` so the caller can log per
+  /// cause. The wire never carries a surface id (so a payload can't spoof another
+  /// worktree). The parser rejects a non-positive pid before it could reach the
+  /// liveness sweep; a forged positive pid at worst pins a live-looking badge.
+  nonisolated static func presenceEvent(
+    id: String,
+    metadata: String,
+    surfaceID: UUID,
+    surfaceExists: Bool
+  ) -> Result<AgentHookEvent, PresenceDrop> {
+    guard surfaceExists else { return .failure(.unknownSurface) }
+    guard let signal = AgentPresenceOSC.parse(id: id, metadata: metadata) else {
+      return .failure(.parseFailed)
+    }
+    return .success(
+      AgentHookEvent(
+        agent: signal.agent, event: signal.eventRawValue, surfaceID: surfaceID, pid: signal.pid))
+  }
+
+  /// Parse an OSC 3008 notify signal for the receiving surface, then sanitize and
+  /// display it. Gated by the rich-notifications setting.
+  private func handleNotifySignal(surfaceID: UUID, id: String, metadata: String) {
+    switch Self.notification(
+      id: id,
+      metadata: metadata,
+      surfaceExists: surfaces[surfaceID] != nil
+    ) {
+    case .success(let resolved):
+      // Gate AFTER parse so the setting can't be probed via drop-rate signals.
+      @Shared(.settingsFile) var settingsFile
+      guard settingsFile.global.richAgentNotificationsEnabled else {
+        terminalStateLogger.debug("Dropped OSC notify; rich notifications disabled.")
+        return
+      }
+      // A body present on the wire but decoded empty means a truncation, an
+      // escape-cut the shed loop couldn't recover, or a non-base64 (probe / forged)
+      // field: keep it out of silent-failure territory by logging, even though we
+      // still show the title-only toast.
+      if resolved.body.isEmpty, resolved.wireBodyByteCount > 0 {
+        let wireBytes = resolved.wireBodyByteCount
+        terminalStateLogger.warning(
+          "OSC notify body present on wire (\(wireBytes) b64 bytes) but decoded empty, dropped: surface \(surfaceID)."
+        )
+      }
+      appendHookNotification(title: resolved.title, body: resolved.body, surfaceID: surfaceID)
+    case .failure(.parseFailed):
+      // parseNotify only fails on a non-notify / empty id (not a truncated body,
+      // which decodes to an empty field, logged in the success arm above).
+      terminalStateLogger.warning(
+        "Dropped malformed OSC notify (metadata bytes: \(metadata.utf8.count)) for surface \(surfaceID).")
+    case .failure(.unknownSurface), .failure(.empty):
+      terminalStateLogger.debug("Dropped OSC notify signal for surface \(surfaceID).")
+    }
+  }
+
+  /// Typed reasons a notify signal was dropped, so the single call site can pick a
+  /// log severity per cause (warn for malformed, debug otherwise).
+  enum NotifyDrop: Error {
+    case unknownSurface
+    case parseFailed
+    case empty
+  }
+
+  /// A parsed + sanitized notify ready for display, plus the raw wire body byte
+  /// count so the call site can log a truncated-to-empty body.
+  struct ResolvedNotification: Equatable {
+    let title: String
+    let body: String
+    let wireBodyByteCount: Int
+  }
+
+  /// Pure parse decision for an OSC notify signal. Title/body are bounded and
+  /// stripped of control characters since anything on the terminal can emit one.
+  /// Title falls back to the agent name; body may be empty.
+  nonisolated static func notification(
+    id: String,
+    metadata: String,
+    surfaceExists: Bool
+  ) -> Result<ResolvedNotification, NotifyDrop> {
+    guard surfaceExists else { return .failure(.unknownSurface) }
+    guard let notify = AgentPresenceOSC.parseNotify(id: id, metadata: metadata) else {
+      return .failure(.parseFailed)
+    }
+    // Second-line defense behind the emit-side caps (notifyTitleByteBudget /
+    // notifyBodyByteBudget): these are scalar counts, not bytes, and the wire is
+    // already bounded, so they only bite on a hand-crafted oversized payload.
+    let title = sanitizeNotificationText(notify.title ?? notify.agent, max: 200)
+    let body = sanitizeNotificationText(notify.body ?? "", max: 1000)
+    guard !(title.isEmpty && body.isEmpty) else { return .failure(.empty) }
+    return .success(ResolvedNotification(title: title, body: body, wireBodyByteCount: notify.wireBodyByteCount))
+  }
+
+  /// Bound length and neutralize control characters in attacker-influenceable
+  /// notification text. Newline / tab / carriage return collapse to a space;
+  /// other C0 controls and DEL are dropped (defends against escape-sequence
+  /// injection into the toast). Length is capped in unicode scalars.
+  nonisolated static func sanitizeNotificationText(_ text: String, max: Int) -> String {
+    var scalars = String.UnicodeScalarView()
+    for scalar in text.unicodeScalars {
+      if scalars.count >= max { break }
+      switch scalar.value {
+      case 0x0A, 0x09, 0x0D:
+        scalars.append(" ")
+      case 0x00...0x1F, 0x7F:
+        continue
+      default:
+        scalars.append(scalar)
+      }
+    }
+    return String(scalars).trimmingCharacters(in: .whitespaces)
+  }
+
+  struct ResolvedLaunch {
+    var command: String?
+    var initialInput: String?
+    var commandWrapper: [String]
+    var usesZmx: Bool
+  }
+
+  /// Routes a surface through zmx so the underlying shell survives app quit.
+  ///
+  /// Interactive surfaces (no explicit `command`) keep `command` nil and inject
+  /// `zmx attach <id>` as a Ghostty `command-wrapper`, so Ghostty resolves and
+  /// integrates the user's real shell exactly as it would without zmx, with zmx
+  /// wrapping the whole resolved (login + integrated) argv.
+  ///
+  /// Explicit commands (scripts) instead wrap the command string itself, since
+  /// they don't want shell resolution / integration. `initialInput` is always
+  /// passed through; zmx is authoritative for attach-vs-create.
+  private func resolveLaunch(
     surfaceID: UUID,
     command: String?,
     initialInput: String?,
     bypassZmx: Bool
-  ) -> (command: String?, initialInput: String?) {
+  ) -> ResolvedLaunch {
     if bypassZmx {
-      return (command, initialInput)
+      return ResolvedLaunch(command: command, initialInput: initialInput, commandWrapper: [], usesZmx: false)
     }
     let sessionID = ZmxSessionID.make(surfaceID: surfaceID)
-    guard let wrapped = zmxClient.wrapCommand(sessionID, command) else {
-      return (command, initialInput)
+    let zmxExecutablePath = zmxClient.executableURL()?.path(percentEncoded: false)
+    // Remote worktree: a *local* zmx session wraps the SSH connection, so zmx
+    // only needs to exist on the client. The remote runs a plain login shell
+    // (no zmx installed there). The surface command is always the wrapped ssh
+    // line (no command-wrapper, since Ghostty wraps the local argv, not the ssh
+    // line). When the caller has no explicit command, default to
+    // cd-into-the-remote-dir so a freshly created session lands in the project.
+    if let host = worktree.host {
+      let userCommand =
+        command
+        ?? Self.remoteDefaultShellCommand(remotePath: worktree.workingDirectory.path(percentEncoded: false))
+      return ResolvedLaunch(
+        command: ZmxAttach.buildRemoteCommand(
+          host: host,
+          localZmxExecutablePath: zmxExecutablePath,
+          sessionID: sessionID,
+          userCommand: userCommand,
+          surfaceID: surfaceID,
+        ),
+        initialInput: initialInput,
+        commandWrapper: [],
+        usesZmx: zmxExecutablePath != nil,
+      )
     }
-    return (wrapped, initialInput)
+    let resolved = ZmxAttach.resolveLaunch(
+      executablePath: zmxExecutablePath,
+      sessionID: sessionID,
+      command: command,
+    )
+    return ResolvedLaunch(
+      command: resolved.command,
+      initialInput: initialInput,
+      commandWrapper: resolved.commandWrapper,
+      usesZmx: zmxExecutablePath != nil,
+    )
+  }
+
+  /// Default command for a remote worktree surface with no explicit command:
+  /// `cd` into the remote project dir, then exec a login shell. The `cd` failure
+  /// is swallowed so a stale path still drops the user into a usable shell. Nil
+  /// for an empty/root path so we just attach the default shell. The path is
+  /// single-quoted for the remote shell (which re-parses the attach string).
+  static func remoteDefaultShellCommand(remotePath: String) -> String? {
+    let trimmed = remotePath.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard !trimmed.isEmpty, trimmed != "/" else { return nil }
+    let quoted = "'" + trimmed.replacing("'", with: "'\\''") + "'"
+    return "cd \(quoted) 2>/dev/null; exec \"$SHELL\" -l"
   }
 
   private struct InheritedSurfaceConfig: Equatable {
@@ -1472,6 +1863,28 @@ final class WorktreeTerminalState {
     return InheritedSurfaceConfig(workingDirectory: workingDirectory, fontSize: fontSize)
   }
 
+  private static let rememberedZoomFontSizeKey = "terminalRememberedFontSize"
+
+  /// Seed for a sourceless surface, gated on `window-inherit-font-size`.
+  private var rememberedZoomFontSize: Float32? {
+    guard runtime.windowInheritsFontSize() else { return nil }
+    @Shared(.appStorage(Self.rememberedZoomFontSizeKey)) var stored: Double = 0
+    return stored > 0 ? Float32(stored) : nil
+  }
+
+  /// Sample and persist the focused surface's zoom (worktree switch, quit).
+  func rememberFocusedZoom() {
+    guard let id = currentFocusedSurfaceId(), let surface = surfaces[id]?.surface else { return }
+    persistZoomFontSize(ghostty_surface_font_size(surface))
+  }
+
+  /// 0 clears a prior zoom, matching Ghostty dropping the override on reset.
+  private func persistZoomFontSize(_ size: Float32) {
+    guard runtime.windowInheritsFontSize() else { return }
+    @Shared(.appStorage(Self.rememberedZoomFontSizeKey)) var stored: Double = 0
+    $stored.withLock { $0 = Double(max(size, 0)) }
+  }
+
   private func currentFocusedSurfaceId() -> UUID? {
     guard let selectedTabId = tabManager.selectedTabId else { return nil }
     return focusedSurfaceIdByTab[selectedTabId]
@@ -1528,30 +1941,60 @@ final class WorktreeTerminalState {
     return trees[tabId]?.visibleLeaves().first?.id
   }
 
-  /// Appends a notification from an agent hook on a specific surface.
+  /// Appends a notification from a custom (hook / OSC 3008) source. Records the
+  /// time so the agent's own OSC 9 for the same event is deduped, and cancels any
+  /// OSC 9 currently held for this surface (the expanded one supersedes it).
   func appendHookNotification(title: String, body: String, surfaceID: UUID) {
     guard surfaces[surfaceID] != nil else {
       terminalStateLogger.debug("Dropped hook notification for unknown surface \(surfaceID) in worktree \(worktree.id)")
       return
     }
-    // Record for deduplication against later OSC 9 notifications.
-    if let normalized = Self.normalizedText("\(title) \(body)") {
-      recentHookBySurfaceID[surfaceID] = (text: normalized, recordedAt: now)
+    lastCustomNotificationAt[surfaceID] = clock.now
+    if let superseded = pendingAgentOSCNotifications.removeValue(forKey: surfaceID) {
+      superseded.cancel()
+      terminalStateLogger.debug(
+        "Dropped held agent OSC 9 for surface \(surfaceID) in worktree \(worktree.id): superseded by hook notification"
+      )
     }
-    appendNotification(title: title, body: body, surfaceID: surfaceID, fromHook: true)
+    appendNotification(title: title, body: body, surfaceID: surfaceID)
   }
 
-  private func appendNotification(
-    title: String,
-    body: String,
-    surfaceID: UUID,
-    fromHook: Bool = false
-  ) {
+  /// The agent's own OSC 9 desktop notification, a summary of the expanded custom
+  /// notification we ship. Deduped: dropped if a custom notification just
+  /// committed for this surface (hook-first); otherwise held briefly and dropped
+  /// if a custom one supersedes it during the hold (OSC-9-first), else shown.
+  private func handleAgentOSCNotification(title: String, body: String, surfaceID: UUID) {
+    if let last = lastCustomNotificationAt[surfaceID],
+      Self.elapsed(from: last, to: clock.now) <= .seconds(Self.oscSuppressionAfterCustom)
+    {
+      terminalStateLogger.debug(
+        "Dropped agent OSC 9 for surface \(surfaceID) in \(worktree.id): custom notification within dedupe window"
+      )
+      return
+    }
+    let clock = clock
+    pendingAgentOSCNotifications.removeValue(forKey: surfaceID)?.cancel()
+    pendingAgentOSCNotifications[surfaceID] = Task { [weak self] in
+      do {
+        try await clock.sleep(for: .seconds(Self.oscHoldWindow))
+      } catch is CancellationError {
+        return
+      } catch {
+        terminalStateLogger.error("OSC 9 hold sleep failed: \(error)")
+        return
+      }
+      guard !Task.isCancelled, let self else { return }
+      self.pendingAgentOSCNotifications.removeValue(forKey: surfaceID)
+      guard self.surfaces[surfaceID] != nil else { return }
+      self.appendNotification(title: title, body: body, surfaceID: surfaceID)
+    }
+  }
+
+  private func appendNotification(title: String, body: String, surfaceID: UUID) {
     let trimmedTitle = title.trimmingCharacters(in: .whitespacesAndNewlines)
     let trimmedBody = body.trimmingCharacters(in: .whitespacesAndNewlines)
     guard !(trimmedTitle.isEmpty && trimmedBody.isEmpty) else { return }
     if notificationsEnabled {
-      let previousHasUnseen = hasUnseenNotification
       let isRead = isSelected() && isFocusedSurface(surfaceID)
       notifications.insert(
         WorktreeTerminalNotification(
@@ -1567,57 +2010,28 @@ final class WorktreeTerminalState {
       if let tabId = tabID(containing: surfaceID) {
         emitTabProjection(for: tabId)
       }
-      emitNotificationIndicatorIfNeeded(previousHasUnseen: previousHasUnseen)
-    }
-    // Suppress OSC 9 system notifications that duplicate a recent hook notification.
-    if !fromHook, shouldSuppressDesktopNotification(title: trimmedTitle, body: trimmedBody, surfaceID: surfaceID) {
-      return
+      emitNotificationStateChanged()
     }
     onNotificationReceived?(surfaceID, trimmedTitle, trimmedBody)
   }
 
-  // MARK: - Notification deduplication (matches supaterm's approach).
-
-  private static let notificationCoalescingWindow: TimeInterval = 2
-
-  private static let genericCompletionTexts: Set<String> = [
-    "agent turn complete",
-    "task complete",
-    "turn complete",
-  ]
-
-  private func shouldSuppressDesktopNotification(title: String, body: String, surfaceID: UUID) -> Bool {
-    guard
-      let terminalText = Self.normalizedText("\(title) \(body)"),
-      let recent = recentHookBySurfaceID[surfaceID],
-      now.timeIntervalSince(recent.recordedAt) <= Self.notificationCoalescingWindow
-    else {
-      return false
-    }
-    if terminalText == recent.text { return true }
-    if recent.text.hasPrefix(terminalText) { return true }
-    if Self.genericCompletionTexts.contains(terminalText) { return true }
-    return false
-  }
-
-  private static func normalizedText(_ value: String) -> String? {
-    let collapsed =
-      value
-      .split(whereSeparator: \.isWhitespace)
-      .joined(separator: " ")
-      .lowercased()
-      .trimmingCharacters(in: .punctuationCharacters)
-    return collapsed.isEmpty ? nil : collapsed
-  }
-
   /// Detaches one surface from the local bookkeeping. The zmx session is NOT
   /// killed here; callers route the kill through `killZmxSessions(forSurfaceIDs:)`
   /// so a single multi-pane close emits one `count=N` analytics event + one
   /// `withTaskGroup` instead of N events and N detached Tasks.
-  private func cleanupSurfaceState(for surfaceID: UUID) {
-    recentHookBySurfaceID.removeValue(forKey: surfaceID)
+  /// Also cancels any held agent OSC 9 and forgets the last-custom-notification
+  /// instant so a future surface ID can't reuse stale dedupe state.
+  private func discardSurfaceBookkeeping(for surfaceID: UUID) {
+    pendingAgentOSCNotifications.removeValue(forKey: surfaceID)?.cancel()
+    lastCustomNotificationAt.removeValue(forKey: surfaceID)
     surfaces.removeValue(forKey: surfaceID)
+    surfaceLaunchMetadata.removeValue(forKey: surfaceID)
+    pendingExplicitSurfaceCloseIDs.remove(surfaceID)
     surfaceStates.removeValue(forKey: surfaceID)
+  }
+
+  private func cleanupSurfaceState(for surfaceID: UUID) {
+    discardSurfaceBookkeeping(for: surfaceID)
     onSurfacesClosed?([surfaceID])
   }
 
@@ -1644,6 +2058,7 @@ final class WorktreeTerminalState {
 
   private func removeTree(for tabId: TerminalTabID) {
     guard let tree = trees.removeValue(forKey: tabId) else { return }
+    surfaceGenerationByTab.removeValue(forKey: tabId)
     let leafIDs = tree.leaves().map(\.id)
     for surface in tree.leaves() {
       surface.closeSurface()
@@ -1741,10 +2156,13 @@ final class WorktreeTerminalState {
     onFocusChanged?(surfaceID)
   }
 
-  private func emitNotificationIndicatorIfNeeded(previousHasUnseen: Bool) {
-    if previousHasUnseen != hasUnseenNotification {
-      onNotificationIndicatorChanged?()
-    }
+  /// `currentProjection()` already includes the full list and per-item `isRead`,
+  /// so the sidebar/popover must re-sync on every mutation, not just when
+  /// `hasUnseenNotification` flips. Gating here broke dismiss / mark-read of
+  /// already-read notifications (#385). Downstream emits self-dedupe, so keep
+  /// this ungated.
+  private func emitNotificationStateChanged() {
+    onNotificationIndicatorChanged?()
   }
 
   private func syncFocusIfNeeded() {
@@ -1785,6 +2203,7 @@ final class WorktreeTerminalState {
   /// not fire the callback.
   private func emitTabProjection(for tabId: TerminalTabID) {
     guard let tree = trees[tabId] else {
+      surfaceGenerationByTab.removeValue(forKey: tabId)
       if lastTabProjections.removeValue(forKey: tabId) != nil {
         onTabRemoved?(tabId)
       }
@@ -1802,7 +2221,8 @@ final class WorktreeTerminalState {
       surfaceIDs: surfaceIDs,
       activeSurfaceID: focusedSurfaceIdByTab[tabId],
       unseenNotificationCount: unseenCount,
-      isSplitZoomed: tree.zoomed != nil
+      isSplitZoomed: tree.zoomed != nil,
+      surfaceGeneration: surfaceGenerationByTab[tabId, default: 0],
     )
     guard lastTabProjections[tabId] != projection else { return }
     lastTabProjections[tabId] = projection
@@ -1893,17 +2313,126 @@ final class WorktreeTerminalState {
   }
 
   private func handleCloseRequest(for view: GhosttySurfaceView, processAlive _: Bool) {
-    guard surfaces[view.id] != nil else { return }
+    guard surfaces[view.id] === view else { return }
+    let isExplicitClose = pendingExplicitSurfaceCloseIDs.remove(view.id) != nil
+    if shouldHandleAsUnexpectedZmxClose(
+      surfaceID: view.id,
+      isExplicitClose: isExplicitClose
+    ) {
+      handleUnexpectedZmxClose(for: view)
+      return
+    }
+    closeSurfaceAndUpdateTabs(view, killZmxSession: true)
+  }
+
+  private func shouldHandleAsUnexpectedZmxClose(
+    surfaceID: UUID,
+    isExplicitClose: Bool
+  ) -> Bool {
+    guard !isExplicitClose else { return false }
+    return surfaceLaunchMetadata[surfaceID]?.usesZmx == true
+  }
+
+  private func handleUnexpectedZmxClose(for view: GhosttySurfaceView) {
+    let surfaceID = view.id
+    let sessionID = ZmxSessionID.make(surfaceID: surfaceID)
+    let client = zmxClient
+    Task { @MainActor [weak self, weak view] in
+      let sessions = await client.listSessionsWithClients()
+      guard let self, let view, self.surfaces[surfaceID] === view else { return }
+      guard let sessions else {
+        terminalStateLogger.info(
+          "Closing unexpectedly exited zmx surface \(surfaceID) without killing session: probe failed."
+        )
+        self.closeSurfaceAndUpdateTabs(view, killZmxSession: false)
+        return
+      }
+      guard let session = sessions.first(where: { $0.name == sessionID }) else {
+        self.closeSurfaceAndUpdateTabs(view, killZmxSession: true)
+        return
+      }
+      // Reattach only an idle session we positively own (0 clients). A session
+      // with another attached client (clients > 0) or an unknown count (nil) must
+      // never be destroyed, matching the orphan reaper's spare-on-in-use rule.
+      guard let clients = session.clients, clients == 0 else {
+        self.closeSurfaceAndUpdateTabs(view, killZmxSession: false)
+        return
+      }
+      if !self.replaceUnexpectedZmxSurface(view) {
+        self.closeSurfaceAndUpdateTabs(view, killZmxSession: false)
+      }
+    }
+  }
+
+  @discardableResult
+  private func replaceUnexpectedZmxSurface(_ view: GhosttySurfaceView) -> Bool {
+    guard let metadata = surfaceLaunchMetadata[view.id], metadata.usesZmx else { return false }
+    guard zmxClient.executableURL() != nil else {
+      terminalStateLogger.info(
+        "Cannot replace unexpectedly exited zmx surface \(view.id): zmx executable unavailable."
+      )
+      return false
+    }
+    guard let tabId = tabID(containing: view.id), let tree = trees[tabId], let node = tree.find(id: view.id) else {
+      return false
+    }
+    let previousState = surfaceStates[view.id]
+    let replacement = createSurface(
+      tabId: tabId,
+      initialInput: nil,
+      inheritingFromSurfaceId: view.id,
+      context: metadata.context,
+      surfaceID: view.id,
+      bypassZmx: false,
+      replacingExistingSurfaceID: true,
+    )
+    if let previousState {
+      surfaceStates[view.id] = previousState
+    }
+    surfaceLaunchMetadata[view.id] = metadata
+    do {
+      let newTree = try tree.replacing(node: node, with: .leaf(view: replacement))
+      view.closeSurface()
+      bumpSurfaceGeneration(for: tabId)
+      updateTree(newTree, for: tabId)
+      updateRunningState(for: tabId)
+      if focusedSurfaceIdByTab[tabId] == view.id {
+        focusSurface(replacement, in: tabId)
+      }
+      terminalStateLogger.info("Reattached unexpectedly exited zmx surface \(view.id).")
+      return true
+    } catch {
+      terminalStateLogger.warning("Failed to replace unexpectedly exited zmx surface \(view.id): \(error).")
+      replacement.closeSurface()
+      discardSurfaceBookkeeping(for: replacement.id)
+      surfaces[view.id] = view
+      if let previousState {
+        surfaceStates[view.id] = previousState
+      }
+      surfaceLaunchMetadata[view.id] = metadata
+      return false
+    }
+  }
+
+  private func bumpSurfaceGeneration(for tabId: TerminalTabID) {
+    surfaceGenerationByTab[tabId, default: 0] += 1
+  }
+
+  private func closeSurfaceAndUpdateTabs(_ view: GhosttySurfaceView, killZmxSession: Bool) {
     guard let tabId = tabID(containing: view.id), let tree = trees[tabId] else {
       view.closeSurface()
       cleanupSurfaceState(for: view.id)
-      killZmxSessions(forSurfaceIDs: [view.id])
+      if killZmxSession {
+        killZmxSessions(forSurfaceIDs: [view.id])
+      }
       return
     }
     guard let node = tree.find(id: view.id) else {
       view.closeSurface()
       cleanupSurfaceState(for: view.id)
-      killZmxSessions(forSurfaceIDs: [view.id])
+      if killZmxSession {
+        killZmxSessions(forSurfaceIDs: [view.id])
+      }
       return
     }
     let nextSurface =
@@ -1913,7 +2442,9 @@ final class WorktreeTerminalState {
     let newTree = tree.removing(node)
     view.closeSurface()
     cleanupSurfaceState(for: view.id)
-    killZmxSessions(forSurfaceIDs: [view.id])
+    if killZmxSession {
+      killZmxSessions(forSurfaceIDs: [view.id])
+    }
     if newTree.isEmpty {
       trees.removeValue(forKey: tabId)
       focusedSurfaceIdByTab.removeValue(forKey: tabId)
@@ -1930,6 +2461,10 @@ final class WorktreeTerminalState {
         }
       }
       emitTaskStatusIfChanged()
+      // Closing the last surface via `close_surface` removes the tab here but
+      // skips the `closeTab` projection path; emit one so `onTabRemoved` fires
+      // and the layout persistence sink observes the tab going away.
+      emitTabProjection(for: tabId)
       return
     }
     updateTree(newTree, for: tabId)
@@ -2012,7 +2547,7 @@ final class WorktreeTerminalState {
     /// Test-only seam for bulk-assigning the notifications log. Fans
     /// `emitAllTabProjections()` so `lastTabProjections` stays in sync with
     /// the raw log; production code must go through the per-event helpers
-    /// (`appendNotification`, `markNotificationsRead`, etc.) which already
+    /// (`appendHookNotification`, `markNotificationsRead`, etc.) which already
     /// emit. Gated `#if DEBUG` so release builds genuinely can't reach the
     /// projection-bypass path.
     func setNotificationsForTesting(_ list: [WorktreeTerminalNotification]) {
@@ -2030,5 +2565,6 @@ final class WorktreeTerminalState {
     func installSurfaceStateForTesting(_ state: WorktreeSurfaceState, forSurfaceID surfaceID: UUID) {
       surfaceStates[surfaceID] = state
     }
+
   #endif
 }
diff --git a/supacode/Features/Terminal/Reducer/TerminalTabFeature.swift b/supacode/Features/Terminal/Reducer/TerminalTabFeature.swift
index 60e39488a..408f9c32b 100644
--- a/supacode/Features/Terminal/Reducer/TerminalTabFeature.swift
+++ b/supacode/Features/Terminal/Reducer/TerminalTabFeature.swift
@@ -26,6 +26,8 @@ struct TerminalTabFeature {
     /// True when the tab's split tree has a zoomed pane. The tab-bar leaf swaps
     /// its close button for a dismiss-zoom button while this is set.
     var isSplitZoomed: Bool = false
+    /// Monotonic invalidation token for same-UUID surface view replacement.
+    var surfaceGeneration = 0
     /// Per-tab agent snapshot pushed by `AppFeature.agentPresenceFanOutEffect`.
     /// Leaf reads `state.agents` instead of iterating worktree-wide presence on
     /// every storm tick.
@@ -58,6 +60,9 @@ struct TerminalTabFeature {
         if state.isSplitZoomed != projection.isSplitZoomed {
           state.isSplitZoomed = projection.isSplitZoomed
         }
+        if state.surfaceGeneration != projection.surfaceGeneration {
+          state.surfaceGeneration = projection.surfaceGeneration
+        }
         return .none
 
       case .agentSnapshotChanged(let agents):
diff --git a/supacode/Features/Terminal/TabBar/TerminalTabBarMetrics.swift b/supacode/Features/Terminal/TabBar/TerminalTabBarMetrics.swift
index 6dc9f08d8..47fda2c94 100644
--- a/supacode/Features/Terminal/TabBar/TerminalTabBarMetrics.swift
+++ b/supacode/Features/Terminal/TabBar/TerminalTabBarMetrics.swift
@@ -10,11 +10,14 @@ enum TerminalTabBarMetrics {
   static let tabSpacing: CGFloat = 0
   static let tabHorizontalPadding: CGFloat = 12
   static let contentSpacing: CGFloat = 6
-  static let contentTrailingSpacing: CGFloat = 4
+  static let contentTrailingSpacing: CGFloat = 0
   static let activeIndicatorHeight: CGFloat = 2
   static let activeTabOffset: CGFloat = 0.5
   static let activeTabBottomPadding: CGFloat = 1
   static let closeButtonSize: CGFloat = 16
+  // Fixed trailing slot so the cmd badge can fade in without shifting other content.
+  // Sized for the longest `⌘N` badge plus a small margin; widen if shortcut overrides can render longer hints.
+  static let trailingSlotWidth: CGFloat = 24
   static let dirtyIndicatorSize: CGFloat = 8
   static let overflowShadowWidth: CGFloat = 24
   static let dropIndicatorWidth: CGFloat = 2
diff --git a/supacode/Features/Terminal/TabBar/Views/TerminalTabBarTrailingAccessories.swift b/supacode/Features/Terminal/TabBar/Views/TerminalTabBarTrailingAccessories.swift
index 804e41565..f2309a758 100644
--- a/supacode/Features/Terminal/TabBar/Views/TerminalTabBarTrailingAccessories.swift
+++ b/supacode/Features/Terminal/TabBar/Views/TerminalTabBarTrailingAccessories.swift
@@ -31,25 +31,15 @@ private struct TerminalTabBarAccessoryButton: View {
 
   @Environment(GhosttyShortcutManager.self)
   private var ghosttyShortcuts
-  @Environment(CommandKeyObserver.self)
-  private var commandKeyObserver
 
   var body: some View {
     let shortcut = ghosttyShortcuts.display(for: shortcutBinding)
 
     Button(action: action) {
-      if commandKeyObserver.isPressed {
-        HStack(spacing: TerminalTabBarMetrics.contentSpacing) {
-          Text(title)
-            .font(.caption)
-          if let shortcut {
-            ShortcutHintView(text: shortcut, color: TerminalTabBarColors.inactiveText)
-          }
-        }
-      } else {
-        Label(title, systemImage: systemImage)
-          .labelStyle(.iconOnly)
-      }
+      Label(title, systemImage: systemImage)
+        .labelStyle(.iconOnly)
+        .frame(minWidth: TerminalTabBarMetrics.barHeight, minHeight: TerminalTabBarMetrics.barHeight)
+        .contentShape(.rect)
     }
     .buttonStyle(.plain)
     .foregroundStyle(.secondary)
@@ -69,8 +59,6 @@ private struct TerminalTabBarSplitMenu: View {
 
   @Environment(GhosttyShortcutManager.self)
   private var ghosttyShortcuts
-  @Environment(CommandKeyObserver.self)
-  private var commandKeyObserver
 
   var body: some View {
     let primaryShortcut = ghosttyShortcuts.display(for: primary.ghosttyBinding)
@@ -85,18 +73,10 @@ private struct TerminalTabBarSplitMenu: View {
       }
       .ghosttyKeyboardShortcut(secondary.ghosttyBinding, in: ghosttyShortcuts)
     } label: {
-      if commandKeyObserver.isPressed {
-        HStack(spacing: TerminalTabBarMetrics.contentSpacing) {
-          Text(primary.title)
-            .font(.caption)
-          if let primaryShortcut {
-            ShortcutHintView(text: primaryShortcut, color: TerminalTabBarColors.inactiveText)
-          }
-        }
-      } else {
-        Label(primary.title, systemImage: primary.systemImage)
-          .labelStyle(.iconOnly)
-      }
+      Label(primary.title, systemImage: primary.systemImage)
+        .labelStyle(.iconOnly)
+        .frame(minWidth: TerminalTabBarMetrics.barHeight, minHeight: TerminalTabBarMetrics.barHeight)
+        .contentShape(.rect)
     } primaryAction: {
       split(primary)
     }
diff --git a/supacode/Features/Terminal/TabBar/Views/TerminalTabLabelView.swift b/supacode/Features/Terminal/TabBar/Views/TerminalTabLabelView.swift
index 7a2a145a0..d60f20abf 100644
--- a/supacode/Features/Terminal/TabBar/Views/TerminalTabLabelView.swift
+++ b/supacode/Features/Terminal/TabBar/Views/TerminalTabLabelView.swift
@@ -7,8 +7,6 @@ struct TerminalTabLabelView: View {
   let isActive: Bool
   let isHoveringTab: Bool
   let isHoveringClose: Bool
-  let shortcutHint: String?
-  let showsShortcutHint: Bool
   /// Per-tab scoped store. The badge subview observes `state.agents` here
   /// instead of iterating worktree-wide presence, so an agent storm on tab B
   /// doesn't invalidate tab A's label body.
@@ -34,7 +32,7 @@ struct TerminalTabLabelView: View {
     .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .leading)
     .contentShape(.rect)
     .padding(.horizontal, TerminalTabBarMetrics.tabHorizontalPadding)
-    .padding(.trailing, TerminalTabBarMetrics.closeButtonSize + TerminalTabBarMetrics.contentSpacing)
+    .padding(.trailing, TerminalTabBarMetrics.trailingSlotWidth + TerminalTabBarMetrics.contentSpacing)
   }
 }
 
diff --git a/supacode/Features/Terminal/TabBar/Views/TerminalTabView.swift b/supacode/Features/Terminal/TabBar/Views/TerminalTabView.swift
index 4068feab1..a8e32089b 100644
--- a/supacode/Features/Terminal/TabBar/Views/TerminalTabView.swift
+++ b/supacode/Features/Terminal/TabBar/Views/TerminalTabView.swift
@@ -40,8 +40,6 @@ struct TerminalTabView: View {
           isActive: isActive,
           isHoveringTab: isHovering,
           isHoveringClose: isHoveringClose,
-          shortcutHint: shortcutHint,
-          showsShortcutHint: showsShortcutHint,
           tabStore: tabStore,
         )
       }
@@ -60,9 +58,11 @@ struct TerminalTabView: View {
       .allowsHitTesting(!isEditing)
       .opacity(isEditing ? 0 : 1)
 
-      // Trailing slot priority: zoom-dismiss > close (on hover) > ⌘ hint > lock > dot.
-      // The lock subsumes the dot so a bell on a frozen tab doesn't contest the lock signal.
-      ZStack {
+      // Fixed 24pt trailing slot. Lock and notification dot are mutually exclusive;
+      // the hint, close, and zoom-dismiss buttons cross-fade via opacity. Close/zoom
+      // suppress lock/dot via the `suppress:` parameter when hovering, dragging,
+      // hint-showing, or split-zoomed.
+      ZStack(alignment: .trailing) {
         if tab.isBlockingScriptCompleted {
           TerminalTabLockIndicator(
             suppress: isHovering || isHoveringClose || isDragging || isShowingHint || isSplitZoomed
@@ -73,13 +73,15 @@ struct TerminalTabView: View {
             suppress: isHovering || isHoveringClose || isDragging || isShowingHint || isSplitZoomed
           )
         }
-        if isShowingHint, let shortcutHint {
+        if let shortcutHint {
           Text(shortcutHint)
             .font(.caption)
             // Explicit `.regular` because the tab bar lacks the sidebar's List/vibrancy
             // context, where `.font(.caption)` would otherwise render heavier.
             .fontWeight(.regular)
             .foregroundStyle(.secondary)
+            .opacity(isShowingHint ? 1 : 0)
+            .animation(.easeInOut(duration: TerminalTabBarMetrics.fadeAnimationDuration), value: isShowingHint)
         }
         if isSplitZoomed {
           TerminalTabExitSplitZoomButton(
@@ -99,6 +101,7 @@ struct TerminalTabView: View {
           )
         }
       }
+      .frame(width: TerminalTabBarMetrics.trailingSlotWidth, height: TerminalTabBarMetrics.closeButtonSize)
       .animation(.easeInOut(duration: TerminalTabBarMetrics.hoverAnimationDuration), value: isHovering)
       .padding(.trailing, TerminalTabBarMetrics.tabHorizontalPadding)
       .opacity(isEditing ? 0 : 1)
@@ -115,7 +118,7 @@ struct TerminalTabView: View {
           .padding(.horizontal, TerminalTabBarMetrics.tabHorizontalPadding)
           .padding(
             .trailing,
-            TerminalTabBarMetrics.closeButtonSize + TerminalTabBarMetrics.contentSpacing
+            TerminalTabBarMetrics.trailingSlotWidth + TerminalTabBarMetrics.contentSpacing
           )
           .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .leading)
           .onSubmit { onEndRename() }
@@ -236,15 +239,11 @@ struct TerminalTabView: View {
     return "⌘\(number)"
   }
 
-  private var showsShortcutHint: Bool {
-    commandKeyObserver.isPressed && shortcutHint != nil
-  }
-
   /// True when the cmd-pressed hotkey hint should occupy the trailing slot.
   /// Hover wins: when the user is over the tab the close button takes the
   /// slot regardless of whether ⌘ is also pressed.
   private var isShowingHint: Bool {
-    showsShortcutHint && !isHovering && !isDragging
+    commandKeyObserver.isPressed && shortcutHint != nil && !isHovering && !isDragging
   }
 
   /// State-aware accessibility value for VoiceOver. Restores the OSC-9 progress
diff --git a/supacode/Features/Terminal/Views/WorktreeTerminalTabsView.swift b/supacode/Features/Terminal/Views/WorktreeTerminalTabsView.swift
index 5bb94f67e..e020e05ed 100644
--- a/supacode/Features/Terminal/Views/WorktreeTerminalTabsView.swift
+++ b/supacode/Features/Terminal/Views/WorktreeTerminalTabsView.swift
@@ -52,7 +52,7 @@ struct WorktreeTerminalTabsView: View {
             state.dismissSplitZoom(for: tabId)
           },
           renameTab: { tabId, newTitle in
-            state.tabManager.setCustomTitle(tabId, title: newTitle)
+            state.renameTab(tabId, title: newTitle)
           },
         )
         .transition(.move(edge: .top).combined(with: .opacity))
@@ -126,6 +126,8 @@ private struct TerminalSplitTreePane: View {
     let projection = terminalsStore.terminalTabs[id: tabId]
     let _ = projection?.surfaceIDs
     let _ = projection?.activeSurfaceID
+    // Touch generation so SwiftUI rebuilds the tree when a same-UUID surface view is swapped under it.
+    let _ = projection?.surfaceGeneration
     TerminalSplitTreeAXContainer(
       tree: terminalState.splitTree(for: tabId),
       terminalState: terminalState,
diff --git a/supacode/Infrastructure/AgentHookSocketServer.swift b/supacode/Infrastructure/AgentHookSocketServer.swift
index 2eeb80b64..71da74d69 100644
--- a/supacode/Infrastructure/AgentHookSocketServer.swift
+++ b/supacode/Infrastructure/AgentHookSocketServer.swift
@@ -4,34 +4,25 @@ import SupacodeSettingsShared
 
 private nonisolated let socketLogger = SupaLogger("AgentHookSocket")
 
-/// Lightweight Unix domain socket server that receives messages from
-/// agent hooks (via `nc -U`) and the Supacode CLI tool.
+/// Lightweight Unix domain socket server for the Supacode CLI control protocol.
 ///
-/// Four message formats are supported:
-/// - **Notification** (legacy text proto): `<worktreeID> <tabID> <surfaceID> <agent>\n<JSON payload>\n`.
-///   The agent field defaults to `"unknown"` when absent. Kept until rich
-///   notifications migrate to the JSON envelope.
-/// - **Command**: JSON object with a `"deeplink"` key wrapping a `supacode://` URL.
-/// - **Query**: JSON object with a `"query"` key and optional parameters.
-/// - **Hook event**: JSON object with a top-level `"event"` string, designed to
-///   be extended without changing the wire format. Drives presence and
-///   activity. See `AgentHookEvent` for the field shape and `EventName` for
-///   known events.
+/// Two message formats are supported, both JSON objects:
+/// - **Command**: a `"deeplink"` key wrapping a `supacode://` URL.
+/// - **Query**: a `"query"` key and optional parameters.
+///
+/// Agent presence and notifications no longer travel over the socket. Hooks emit
+/// them as OSC 3008 to the terminal (see `AgentPresenceOSC`), which also works
+/// over SSH where this socket can't be reached; the socket carries only the CLI
+/// control protocol.
 @MainActor
 final class AgentHookSocketServer {
   private(set) var socketPath: String?
 
   private var listenTask: Task<Void, Never>?
-  /// (worktreeID, tabID, surfaceID, notification).
-  var onNotification: ((String, UUID, UUID, AgentHookNotification) -> Void)?
   /// Deeplink URL received from the CLI. Second parameter is the client FD for response.
   var onCommand: ((URL, Int32) -> Void)?
   /// Query received from the CLI. Parameters: resource name, extra params, client FD for response.
   var onQuery: ((String, [String: String], Int32) -> Void)?
-  /// Hook event from an agent bridge (the JSON envelope hook commands write
-  /// directly to the socket). Fire-and-forget — the server has already acked
-  /// the client by the time this fires, so handlers must not block.
-  var onEvent: ((AgentHookEvent) -> Void)?
 
   init() {
     let uid = getuid()
@@ -118,8 +109,6 @@ final class AgentHookSocketServer {
 
         await MainActor.run { [weak self] in
           switch message {
-          case .notification(let worktreeID, let tabID, let surfaceID, let notification):
-            self?.onNotification?(worktreeID, tabID, surfaceID, notification)
           case .command(let deeplinkURL, let clientFD):
             guard let self, let handler = self.onCommand else {
               Self.sendCommandResponse(clientFD: clientFD, ok: false, error: "Not ready.")
@@ -132,8 +121,6 @@ final class AgentHookSocketServer {
               return
             }
             handler(resource, params, clientFD)
-          case .event(let event):
-            self?.onEvent?(event)
           }
         }
       }
@@ -213,15 +200,10 @@ final class AgentHookSocketServer {
   private nonisolated static let maxPayloadSize = 65_536
 
   nonisolated enum Message: Sendable {
-    case notification(
-      worktreeID: String, tabID: UUID, surfaceID: UUID, notification: AgentHookNotification)
     /// CLI command with the client FD kept open for writing a response.
     case command(deeplinkURL: URL, clientFD: Int32)
     /// CLI query with the client FD kept open for writing data back.
     case query(resource: String, params: [String: String], clientFD: Int32)
-    /// Hook event from an agent bridge. Acked before dispatch, so the FD is
-    /// already closed by the time the handler runs.
-    case event(AgentHookEvent)
   }
 
   /// Writes a JSON response with data to a client and closes the FD.
@@ -294,20 +276,12 @@ final class AgentHookSocketServer {
       return nil
     }
 
-    // For command/query messages, keep the FD open for the response.
-    // For event messages, ack immediately and close — handlers must not
-    // block agent hook execution waiting for app state.
+    // Command/query messages keep the FD open so the handler can write a response.
     switch message {
     case .command(let url, _):
       return .command(deeplinkURL: url, clientFD: clientFD)
     case .query(let resource, let params, _):
       return .query(resource: resource, params: params, clientFD: clientFD)
-    case .event:
-      sendCommandResponse(clientFD: clientFD, ok: true)
-      return message
-    default:
-      close(clientFD)
-      return message
     }
   }
 
@@ -340,102 +314,25 @@ final class AgentHookSocketServer {
 
   nonisolated static func parse(data: Data) -> Message? {
     guard let rawString = String(data: data, encoding: .utf8) else {
-      socketLogger.warning("Dropped non-UTF8 hook payload (\(data.count) bytes)")
+      socketLogger.warning("Dropped non-UTF8 CLI payload (\(data.count) bytes)")
       return nil
     }
-
     let raw = rawString.trimmingCharacters(in: .whitespacesAndNewlines)
     guard !raw.isEmpty else {
-      socketLogger.debug("Dropped empty hook payload")
+      socketLogger.debug("Dropped empty CLI payload")
       return nil
     }
-
-    // JSON object starting with `{` → CLI message (event, query, or command).
-    if raw.hasPrefix("{") {
-      return parseJSONMessage(data: data)
-    }
-
-    // Notification (legacy text proto): `worktreeID tabID surfaceID agent\n<JSON payload>`.
-    // Activity events flow through the JSON envelope path above.
-    let lines = raw.split(separator: "\n", omittingEmptySubsequences: false)
-    let headerParts = lines[0].split(separator: " ", maxSplits: 3)
-    guard
-      headerParts.count >= 3,
-      let tabID = UUID(uuidString: String(headerParts[1])),
-      let surfaceID = UUID(uuidString: String(headerParts[2]))
-    else {
-      socketLogger.warning("Malformed header: \(lines[0])")
-      return nil
-    }
-
-    let worktreeID = String(headerParts[0])
-
-    // Notification: 4th header field is the agent name; remaining lines are JSON.
-    // Agent is a raw string intentionally — left open for custom agents since
-    // the socket is already listening and anyone can send messages.
-    guard lines.count > 1 else {
-      socketLogger.warning("Single-line text payload no longer supported: \(lines[0])")
-      return nil
-    }
-    let agent = headerParts.count >= 4 ? String(headerParts[3]) : "unknown"
-    let jsonPayload = lines.dropFirst().joined(separator: "\n")
-
-    guard let jsonData = jsonPayload.data(using: .utf8) else {
-      socketLogger.warning("Invalid notification payload encoding")
+    // The CLI control protocol is always a JSON object (command or query).
+    guard raw.hasPrefix("{") else {
+      socketLogger.debug("Dropped non-JSON socket payload")
       return nil
     }
-
-    guard let notification = parseNotification(agent: agent, data: jsonData) else {
-      return nil
-    }
-    return .notification(
-      worktreeID: worktreeID,
-      tabID: tabID,
-      surfaceID: surfaceID,
-      notification: notification
-    )
-  }
-
-  private nonisolated static func parseNotification(
-    agent: String,
-    data: Data
-  ) -> AgentHookNotification? {
-    guard let payload = try? JSONDecoder().decode(AgentHookPayload.self, from: data) else {
-      let preview = String(data: data.prefix(200), encoding: .utf8) ?? "<non-UTF8>"
-      socketLogger.warning("Failed to decode \(agent) notification payload: \(preview)")
-      return nil
-    }
-
-    if payload.body == nil {
-      socketLogger.warning(
-        "All body fields nil in \(agent) \(payload.hookEventName ?? "unknown") notification")
-    }
-    return AgentHookNotification(
-      agent: agent,
-      event: payload.hookEventName ?? "unknown",
-      title: payload.title,
-      body: payload.body
-    )
+    return parseJSONMessage(data: data)
   }
 
-  /// Parses a JSON message into an event, query, or command. The placeholder
+  /// Parses a CLI JSON message into a query or command. The placeholder
   /// `clientFD` of `-1` is replaced with the real FD in `acceptAndParse`.
-  ///
-  /// Discriminator precedence: a top-level `"event"` string routes to the
-  /// hook-event parser exclusively — an event-shaped payload never falls
-  /// through to query/command parsing, so a malformed event produces a single
-  /// clear warning instead of two misleading ones.
   private nonisolated static func parseJSONMessage(data: Data) -> Message? {
-    let probe = try? JSONDecoder().decode(EventDiscriminatorProbe.self, from: data)
-    if let event = probe?.event, !event.isEmpty {
-      do {
-        let parsed = try JSONDecoder().decode(AgentHookEvent.self, from: data)
-        return .event(parsed)
-      } catch {
-        socketLogger.warning("Hook event payload failed to decode: \(error)")
-        return nil
-      }
-    }
     guard let request = SocketCommandRequest(data: data) else {
       socketLogger.warning("Failed to decode CLI message payload")
       return nil
@@ -453,27 +350,14 @@ final class AgentHookSocketServer {
   }
 }
 
-/// Probe used to detect the `event` discriminator without paying for a full
-/// envelope decode. Decoding this is cheap — the JSON parser walks until it
-/// finds the field and ignores the rest.
-private nonisolated struct EventDiscriminatorProbe: Decodable {
-  let event: String?
-}
-
-/// Parsed notification from a coding agent hook event.
-nonisolated struct AgentHookNotification: Equatable, Sendable {
-  let agent: String
-  let event: String
-  let title: String?
-  let body: String?
-}
-
-/// JSON envelope for hook events sent by the agent bridge.
-/// `surface_id` is the only required scope field — tab and worktree are
-/// derived app-side from the current terminal topology so a moved/split
-/// surface never carries stale attribution.
+/// An agent presence/activity event. Built by the OSC ingest from a verified
+/// presence signal (memberwise init, attributed to the receiving surface), and
+/// also `Decodable` from the legacy JSON envelope shape below for test
+/// construction. `surface_id` is the only scope field; tab and worktree are
+/// derived app-side from the current terminal topology so a moved/split surface
+/// never carries stale attribution.
 ///
-/// Wire shape:
+/// JSON shape (the Decodable contract):
 /// ```json
 /// {
 ///   "event": "session_start",   // discriminator + event name (required)
@@ -486,8 +370,8 @@ nonisolated struct AgentHookNotification: Equatable, Sendable {
 /// }
 /// ```
 nonisolated struct AgentHookEvent: Equatable, Sendable, Decodable {
-  /// Known event names. Stored as raw `String` on the wire so unknown events
-  /// from a newer bridge / older app don't drop — handlers can ignore them.
+  /// Known event names. Stored as raw `String` so an unknown event from a newer
+  /// emitter / older app doesn't drop; handlers can ignore them.
   enum EventName: String, Sendable {
     case sessionStart = "session_start"
     case sessionEnd = "session_end"
@@ -504,7 +388,7 @@ nonisolated struct AgentHookEvent: Equatable, Sendable, Decodable {
   let pid: pid_t?
   let timestamp: Date?
   /// Event-specific payload preserved as opaque JSON. Handlers decode with
-  /// their own typed shape via `decodeData(_:)` — keeps this layer decoupled
+  /// their own typed shape via `decodeData(_:)`, keeping this layer decoupled
   /// from per-event payload schemas.
   let data: JSONValue?
 
@@ -513,7 +397,7 @@ nonisolated struct AgentHookEvent: Equatable, Sendable, Decodable {
 
   /// Decode the per-event `data` payload into a concrete type. Returns nil
   /// when `data` is missing. Returns nil and logs a warning when `data` is
-  /// present but fails to decode against `T` — silent nil there would make a
+  /// present but fails to decode against `T`; silent nil there would make a
   /// shape mismatch invisible to handlers.
   func decodeData<T: Decodable>(_ type: T.Type = T.self) -> T? {
     guard let data else { return nil }
@@ -545,7 +429,7 @@ nonisolated struct AgentHookEvent: Equatable, Sendable, Decodable {
     self.agent = try container.decodeIfPresent(String.self, forKey: .agent) ?? "unknown"
     self.version = try container.decodeIfPresent(Int.self, forKey: .version) ?? 1
     if let rawPid = try container.decodeIfPresent(Int.self, forKey: .pid) {
-      // Reject 0 and negatives — `kill(0, 0)` succeeds for the caller's
+      // Reject 0 and negatives: `kill(0, 0)` succeeds for the caller's
       // process group and `kill(-N, 0)` for group N, both of which would
       // pin a permanent badge in the liveness sweep on a buggy hook (e.g.
       // `pid:$$` from a subshell that recycled).
@@ -566,6 +450,34 @@ nonisolated struct AgentHookEvent: Equatable, Sendable, Decodable {
     self.data = try container.decodeIfPresent(JSONValue.self, forKey: .data)
   }
 
+  /// Memberwise init for synthesizing events from sources other than the JSON
+  /// wire. The OSC presence path uses it: attribution is by the receiving
+  /// surface and there is no remote pid, so `pid` defaults to nil.
+  init(
+    version: Int = 1,
+    agent: String,
+    event: String,
+    surfaceID: UUID,
+    pid: pid_t? = nil,
+    timestamp: Date? = nil,
+    data: JSONValue? = nil
+  ) {
+    self.version = version
+    self.agent = agent
+    self.event = event
+    self.surfaceID = surfaceID
+    // Mirror the Decodable validation: a non-positive pid would let `kill(0/-N, 0)`
+    // match the caller's process group and pin a permanent badge.
+    if let pid, pid <= 0 {
+      socketLogger.warning("Clamped non-positive pid \(pid) to nil in AgentHookEvent(agent: \(agent)).")
+      self.pid = nil
+    } else {
+      self.pid = pid
+    }
+    self.timestamp = timestamp
+    self.data = data
+  }
+
   private static func decodeUUID(
     from container: KeyedDecodingContainer<CodingKeys>,
     forKey key: CodingKeys
@@ -580,51 +492,6 @@ nonisolated struct AgentHookEvent: Equatable, Sendable, Decodable {
   }
 }
 
-/// Raw JSON payload from a coding agent hook event. The `body` is decoded from
-/// whichever agent-specific field is present: Claude uses `message`, Codex uses
-/// `last_assistant_message`, Kiro uses `assistant_response`. Precedence favors
-/// `message` so unknown agents that speak the Claude shape keep working.
-private nonisolated struct AgentHookPayload: Decodable {
-  let hookEventName: String?
-  let title: String?
-  let body: String?
-
-  private enum CodingKeys: String, CodingKey {
-    case hookEventName = "hook_event_name"
-    case title
-    case message
-    case lastAssistantMessage = "last_assistant_message"
-    case assistantResponse = "assistant_response"
-  }
-
-  init(from decoder: Decoder) throws {
-    let container = try decoder.container(keyedBy: CodingKeys.self)
-    hookEventName = try container.decodeIfPresent(String.self, forKey: .hookEventName)
-    title = try container.decodeIfPresent(String.self, forKey: .title)
-    // Tolerate per-field decode errors (e.g. `"message": 42`) so a single
-    // malformed field does not drop the whole notification — fall through
-    // to the next candidate instead.
-    let candidates = [CodingKeys.message, .lastAssistantMessage, .assistantResponse]
-      .map { key in Self.decodeOptionalString(container, forKey: key) }
-    // Skip empty strings too: Claude occasionally emits `"message": ""`, in
-    // which case Codex's `last_assistant_message` / Kiro's `assistant_response`
-    // still hold the useful body.
-    body = candidates.compactMap { $0 }.first { !$0.isEmpty }
-  }
-
-  private static func decodeOptionalString(
-    _ container: KeyedDecodingContainer<CodingKeys>,
-    forKey key: CodingKeys
-  ) -> String? {
-    do {
-      return try container.decodeIfPresent(String.self, forKey: key)
-    } catch {
-      socketLogger.warning("Failed to decode hook payload field \(key.rawValue): \(error)")
-      return nil
-    }
-  }
-}
-
 /// Parsed CLI request payload: either a deeplink command or a query with params.
 private nonisolated enum SocketCommandRequest {
   case command(deeplink: String, params: [String: String])
diff --git a/supacode/Infrastructure/Ghostty/GhosttyRuntime.swift b/supacode/Infrastructure/Ghostty/GhosttyRuntime.swift
index 5f0e670d0..b211fe90f 100644
--- a/supacode/Infrastructure/Ghostty/GhosttyRuntime.swift
+++ b/supacode/Infrastructure/Ghostty/GhosttyRuntime.swift
@@ -542,20 +542,43 @@ final class GhosttyRuntime {
   /// the window's tint is the only visual layer; the user's intended value is
   /// captured separately in `loadConfig` for window-level use.
   ///
-  /// `shell-integration = none` short-circuits Ghostty's `setupBash` call
-  /// before it can prepend `--posix` to the surface command (#356); zmx
-  /// rejects `--posix` as an unknown arg and the surface fails to launch.
+  /// Shell integration is intentionally left untouched (no `shell-integration`
+  /// override): surfaces run the real shell with zmx injected as a Ghostty
+  /// `command-wrapper`, so Ghostty resolves and integrates the shell exactly as
+  /// it would without zmx, honoring the user's `command` / `shell-integration`.
   internal static let bundledOverridesString = """
     window-padding-x = 14
     window-padding-y = 12,0
     background-opacity = 0
-    shell-integration = none
     """
 
+  /// Reports Supacode in `TERM_PROGRAM` so programs detect the real host
+  /// terminal (issue #440); loaded after the user config so it wins. The version
+  /// is always emitted because Ghostty's `env` map can override a key but not
+  /// clear its seeded version, so a blank value falls back to a placeholder.
+  internal static func terminalProgramOverrides(version: String?) -> String {
+    // Trim like Ghostty's `env` parser, which strips whitespace then drops a
+    // now-empty value, leaving its seeded version.
+    let trimmed = version?.trimmingCharacters(in: .whitespacesAndNewlines)
+    let resolved = trimmed.flatMap { $0.isEmpty ? nil : $0 } ?? "unknown"
+    return """
+      env = TERM_PROGRAM=supacode
+      env = TERM_PROGRAM_VERSION=\(resolved)
+      """
+  }
+
+  private static var appVersion: String? {
+    let info = Bundle.main.infoDictionary
+    let candidates = [info?["CFBundleShortVersionString"], info?["CFBundleVersion"]]
+    return candidates.lazy.compactMap { $0 as? String }.first { !$0.isEmpty }
+  }
+
   private static func loadBundledOverrides(into config: ghostty_config_t) {
     let tempURL = FileManager.default.temporaryDirectory.appendingPathComponent("supacode-defaults.conf")
+    let contents = [bundledOverridesString, terminalProgramOverrides(version: appVersion)]
+      .joined(separator: "\n")
     do {
-      try bundledOverridesString.write(to: tempURL, atomically: true, encoding: .utf8)
+      try contents.write(to: tempURL, atomically: true, encoding: .utf8)
     } catch {
       logger.warning("Failed to write bundled defaults: \(error.localizedDescription)")
       return
@@ -638,6 +661,15 @@ final class GhosttyRuntime {
     return value & (1 << 0) != 0
   }
 
+  /// Whether new surfaces inherit the spawning surface's font size; defaults on.
+  func windowInheritsFontSize() -> Bool {
+    guard let config else { return true }
+    var value: CUnsignedInt = 0
+    let key = "window-inherit-font-size"
+    guard ghostty_config_get(config, &value, key, UInt(key.count)) else { return true }
+    return value & (1 << 0) != 0
+  }
+
   // The user's intended opacity, applied at the window level. The Ghostty
   // surface itself is forced to `background-opacity = 0` so the tint
   // doesn't double up.
diff --git a/supacode/Infrastructure/Ghostty/GhosttySurfaceBridge.swift b/supacode/Infrastructure/Ghostty/GhosttySurfaceBridge.swift
index 34e0311df..80821f63d 100644
--- a/supacode/Infrastructure/Ghostty/GhosttySurfaceBridge.swift
+++ b/supacode/Infrastructure/Ghostty/GhosttySurfaceBridge.swift
@@ -3,6 +3,8 @@ import Foundation
 import GhosttyKit
 import SupacodeSettingsShared
 
+private let terminalStateLogger = SupaLogger("Terminal")
+
 enum GhosttyOpenURLKind: Equatable {
   case unknown
   case text
@@ -62,7 +64,13 @@ final class GhosttySurfaceBridge {
   // blockingScripts dict in the handlers.
   var onCommandFinished: ((Int?) -> Void)?
   var onChildExited: ((UInt32) -> Void)?
+  // The agent's own OSC 9 desktop notification. Deduped against our richer custom
+  // notification one layer up.
   var onDesktopNotification: ((String, String) -> Void)?
+  // OSC 3008 context signal: (action 0=start/1=end, context id, raw key=value
+  // metadata). Forwarded raw; the per-surface capability token carried in the
+  // metadata is verified one layer up where the surface's nonce lives.
+  var onContextSignal: ((UInt8, String, String) -> Void)?
 
   // Coalesce OSC-9 progress: a flush task applies the latest value at the
   // throttle cadence while it moves, and a slow stale-watch clears a bar whose
@@ -103,6 +111,7 @@ final class GhosttySurfaceBridge {
     if let handled = handleAppAction(action) { return handled }
     if let handled = handleSplitAction(action) { return handled }
     if handleTitleAndPath(action) { return false }
+    if handleContextSignal(action) { return false }
     if handleCommandStatus(action) { return false }
     if handleMouseAndLink(action) {
       return action.tag == GHOSTTY_ACTION_OPEN_URL
@@ -286,6 +295,17 @@ final class GhosttySurfaceBridge {
     }
   }
 
+  private func handleContextSignal(_ action: ghostty_action_s) -> Bool {
+    guard action.tag == GHOSTTY_ACTION_CONTEXT_SIGNAL else { return false }
+    let signal = action.action.context_signal
+    guard let id = string(from: signal.id), let metadata = string(from: signal.metadata) else {
+      terminalStateLogger.warning("OSC 3008 context signal arrived with null id or metadata")
+      return true
+    }
+    onContextSignal?(signal.action, id, metadata)
+    return true
+  }
+
   private func handleCommandStatus(_ action: ghostty_action_s) -> Bool {
     switch action.tag {
     case GHOSTTY_ACTION_PROGRESS_REPORT:
diff --git a/supacode/Infrastructure/Ghostty/GhosttySurfaceView.swift b/supacode/Infrastructure/Ghostty/GhosttySurfaceView.swift
index 46e7d42ef..2f18f4f5a 100644
--- a/supacode/Infrastructure/Ghostty/GhosttySurfaceView.swift
+++ b/supacode/Infrastructure/Ghostty/GhosttySurfaceView.swift
@@ -77,6 +77,13 @@ final class GhosttySurfaceView: NSView, Identifiable {
   private let commandCString: UnsafeMutablePointer<CChar>?
   private let initialInputCString: UnsafeMutablePointer<CChar>?
   private let environmentVariables: [String: String]
+  /// Argv prepended to Ghostty's resolved command (e.g. `zmx attach <id>`), so
+  /// the real shell runs as a child of the wrapper. Empty means no wrapper.
+  private let commandWrapper: [String]
+  /// Forces `shell-integration = none` for this surface only. Used by
+  /// self-managing surfaces (blocking-script runners) that emit their own OSC
+  /// sequences and must not have Ghostty's integration injected.
+  private let disableShellIntegration: Bool
   private let fontSize: Float32
   private let context: ghostty_surface_context_e
   private var trackingArea: NSTrackingArea?
@@ -198,6 +205,8 @@ final class GhosttySurfaceView: NSView, Identifiable {
     command: String? = nil,
     initialInput: String? = nil,
     environmentVariables: [String: String] = [:],
+    commandWrapper: [String] = [],
+    disableShellIntegration: Bool = false,
     fontSize: Float32? = nil,
     context: ghostty_surface_context_e
   ) {
@@ -207,6 +216,8 @@ final class GhosttySurfaceView: NSView, Identifiable {
     self.fontSize = fontSize ?? 0
     self.context = context
     self.environmentVariables = environmentVariables
+    self.commandWrapper = commandWrapper
+    self.disableShellIntegration = disableShellIntegration
     if let workingDirectory {
       let path = Self.normalizedWorkingDirectoryPath(
         workingDirectory.path(percentEncoded: false)
@@ -414,7 +425,7 @@ final class GhosttySurfaceView: NSView, Identifiable {
   override func viewDidChangeEffectiveAppearance() {
     super.viewDidChangeEffectiveAppearance()
     // Re-resolve `NSColor.windowBackgroundColor` (and any dynamic fallback) under
-    // the new appearance — `withAlphaComponent` flattens dynamic colors, so the
+    // the new appearance. `withAlphaComponent` flattens dynamic colors, so the
     // transparent branch otherwise freezes at whatever scheme was current at first paint.
     applyWindowBackgroundAppearance()
   }
@@ -977,6 +988,7 @@ final class GhosttySurfaceView: NSView, Identifiable {
     config.command = commandCString.map { UnsafePointer($0) }
     config.initial_input = initialInputCString.map { UnsafePointer($0) }
     config.context = context
+    config.disable_shell_integration = disableShellIntegration
     // Ghostty copies env vars into its arena allocator, so
     // the C strings only need to live through this call.
     var envVars = environmentVariables.map { key, value in
@@ -991,12 +1003,27 @@ final class GhosttySurfaceView: NSView, Identifiable {
         free(.init(mutating: envVar.value))
       }
     }
-    envVars.withUnsafeMutableBufferPointer { buffer in
-      if let baseAddress = buffer.baseAddress {
+    // Wrapper argv C strings must also outlive the surface_new call.
+    var wrapperCStrings: [UnsafePointer<CChar>?] = commandWrapper.map { arg in
+      UnsafePointer(arg.withCString { strdup($0)! })
+    }
+    defer {
+      for ptr in wrapperCStrings {
+        free(UnsafeMutablePointer(mutating: ptr))
+      }
+    }
+    envVars.withUnsafeMutableBufferPointer { envBuffer in
+      if let baseAddress = envBuffer.baseAddress, !envBuffer.isEmpty {
         config.env_vars = baseAddress
-        config.env_var_count = buffer.count
+        config.env_var_count = envBuffer.count
+      }
+      wrapperCStrings.withUnsafeBufferPointer { wrapperBuffer in
+        if let baseAddress = wrapperBuffer.baseAddress, !wrapperBuffer.isEmpty {
+          config.command_wrapper = baseAddress
+          config.command_wrapper_count = wrapperBuffer.count
+        }
+        surface = ghostty_surface_new(app, &config)
       }
-      surface = ghostty_surface_new(app, &config)
     }
     bridge.surface = surface
     lastOcclusion = nil
@@ -1071,20 +1098,21 @@ final class GhosttySurfaceView: NSView, Identifiable {
     guard let surface else { return false }
     // `focused` is a cached flag updated via `becomeFirstResponder` /
     // `resignFirstResponder`, but AppKit calls `performKeyEquivalent`
-    // on every view in the window — including this one when the
+    // on every view in the window, including this one when the
     // sidebar `List` has been clicked but didn't formally demote us
     // out of the responder chain. Gate strictly on AppKit's current
     // answer so a click on the sidebar lets ⌘⌫ reach the main menu.
     guard focused, window?.firstResponder === self else { return false }
 
     if let bindingFlags = bindingFlags(for: event, surface: surface) {
-      // Only forward to the main menu when the event actually matches one of our registered
-      // menu items. `NSMenu.performKeyEquivalent` can otherwise intercept Ghostty-only
-      // shortcuts (e.g. `⌘⇧,` → reload_config) via AppKit's built-in menu matching quirks.
+      // Forward to the menu only when the chord resolves to an app-owned item, so Ghostty-only
+      // shortcuts like `⌘⇧,` aren't eaten by AppKit's menu-matching quirks. A chord with no
+      // forwardable item (e.g. `⌘⌥H` Hide Others vs a `goto_split` binding) falls through to
+      // Ghostty so the terminal binding wins.
       if shouldAttemptMenu(for: bindingFlags),
         let menu = NSApp.mainMenu,
-        Self.mainMenuHasMatchingItem(for: event, in: menu),
-        menu.performKeyEquivalent(with: event)
+        let item = Self.forwardableMenuItem(for: event, in: menu),
+        Self.dispatchForwardableChord(item, for: event, in: menu)
       {
         return true
       }
@@ -1276,29 +1304,81 @@ final class GhosttySurfaceView: NSView, Identifiable {
     performBindingAction("prompt_surface_title")
   }
 
-  /// Recursively walks the main menu looking for any item whose key equivalent and
-  /// modifier mask match `event` exactly. We require an exact modifier match so that a
-  /// shortcut like `⌘,` (Settings) doesn't eat `⌘⇧,` (Ghostty's `reload_config`).
-  ///
-  /// An uppercase `keyEquivalent` encodes shift implicitly (AppKit convention), so we
-  /// fold that into the item's effective mask before comparing.
-  private static func mainMenuHasMatchingItem(for event: NSEvent, in menu: NSMenu) -> Bool {
+  /// macOS app/window-management actions the user cannot remap from Settings → Shortcuts.
+  /// We skip these when matching so a colliding terminal binding wins instead of firing both.
+  static let systemManagedMenuActions: Set<Selector> = [
+    #selector(NSApplication.hide(_:)),
+    #selector(NSApplication.hideOtherApplications(_:)),
+    #selector(NSApplication.unhideAllApplications(_:)),
+    #selector(NSWindow.performMiniaturize(_:)),
+    #selector(NSWindow.performZoom(_:)),
+    #selector(NSWindow.toggleFullScreen(_:)),
+    #selector(NSApplication.arrangeInFront(_:)),
+  ]
+
+  /// True when `item` triggers one of `systemManagedMenuActions`.
+  static func isSystemManagedMenuItem(_ item: NSMenuItem) -> Bool {
+    guard let action = item.action else { return false }
+    return systemManagedMenuActions.contains(action)
+  }
+
+  /// True when `item`'s key equivalent and modifier mask match `event` exactly. An exact
+  /// modifier match keeps a shortcut like `⌘,` (Settings) from eating `⌘⇧,` (Ghostty's
+  /// `reload_config`). An uppercase `keyEquivalent` encodes shift implicitly (AppKit
+  /// convention), so we fold that into the item's effective mask before comparing.
+  static func menuItem(_ item: NSMenuItem, matches event: NSEvent) -> Bool {
+    guard !item.keyEquivalent.isEmpty else { return false }
     guard let characters = event.charactersIgnoringModifiers?.lowercased(), !characters.isEmpty else { return false }
+    let itemKey = item.keyEquivalent
+    guard itemKey.lowercased() == characters else { return false }
     let shortcutMask: NSEvent.ModifierFlags = [.shift, .control, .option, .command]
-    let eventModifiers = event.modifierFlags.intersection(shortcutMask)
+    var itemMask = item.keyEquivalentModifierMask.intersection(shortcutMask)
+    if itemKey != itemKey.lowercased() { itemMask.insert(.shift) }
+    return itemMask == event.modifierFlags.intersection(shortcutMask)
+  }
+
+  /// Recursively walks the main menu for the first app-owned item matching `event`, returning
+  /// it so the caller knows the chord resolves to an app shortcut worth forwarding. Non-remappable
+  /// macOS built-ins are skipped so a terminal binding wins over them instead of being suppressed.
+  static func forwardableMenuItem(for event: NSEvent, in menu: NSMenu) -> NSMenuItem? {
     for item in menu.items {
-      if let submenu = item.submenu, mainMenuHasMatchingItem(for: event, in: submenu) { return true }
-      guard !item.keyEquivalent.isEmpty else { continue }
-      let itemKey = item.keyEquivalent
-      guard itemKey.lowercased() == characters else { continue }
-      var itemMask = item.keyEquivalentModifierMask.intersection(shortcutMask)
-      if itemKey != itemKey.lowercased() { itemMask.insert(.shift) }
-      guard itemMask == eventModifiers else { continue }
-      return true
+      if let submenu = item.submenu, let match = forwardableMenuItem(for: event, in: submenu) { return match }
+      guard menuItem(item, matches: event), !isSystemManagedMenuItem(item) else { continue }
+      return item
+    }
+    return nil
+  }
+
+  /// True when `event`'s chord also matches a non-remappable macOS built-in (Hide, Minimize, ...),
+  /// even when an app-owned item shares the same chord (e.g. a custom `close_surface` on `⌘M`).
+  static func menuHasSystemManagedConflict(for event: NSEvent, in menu: NSMenu) -> Bool {
+    for item in menu.items {
+      if let submenu = item.submenu, menuHasSystemManagedConflict(for: event, in: submenu) { return true }
+      if isSystemManagedMenuItem(item), menuItem(item, matches: event) { return true }
     }
     return false
   }
 
+  /// Dispatches the resolved app-owned `item` for `event`. When the chord also matches a
+  /// non-remappable built-in, fires `item` directly so the built-in can't fire too and the app
+  /// action's own side effects still run (e.g. `close_surface`'s explicit-close bookkeeping, which
+  /// a fall-through to Ghostty would skip and so reattach a zmx surface instead of closing it).
+  /// Otherwise uses the native key-equivalent path, which drives SwiftUI command items like `⌘W`.
+  static func dispatchForwardableChord(_ item: NSMenuItem, for event: NSEvent, in menu: NSMenu) -> Bool {
+    guard menuHasSystemManagedConflict(for: event, in: menu) else { return menu.performKeyEquivalent(with: event) }
+    return performMenuItem(item)
+  }
+
+  /// Fires `item`'s action through the responder chain so only that item runs, never a built-in
+  /// that shares the chord. `NSApp.sendAction` is the same dispatch the native key-equivalent path
+  /// ends in, so SwiftUI command items fire without `update()` rebuilding and detaching the menu.
+  /// Returns false when the item is disabled or unhandled so the caller falls back to Ghostty.
+  @discardableResult
+  static func performMenuItem(_ item: NSMenuItem) -> Bool {
+    guard item.isEnabled, let action = item.action else { return false }
+    return NSApp.sendAction(action, to: item.target, from: item)
+  }
+
   private func shouldAttemptMenu(for flags: ghostty_binding_flags_e) -> Bool {
     if bridge.state.keySequenceActive == true { return false }
     if bridge.state.keyTableDepth > 0 { return false }
diff --git a/supacode/Support/ShortcutHintView.swift b/supacode/Support/ShortcutHintView.swift
deleted file mode 100644
index ee4860383..000000000
--- a/supacode/Support/ShortcutHintView.swift
+++ /dev/null
@@ -1,12 +0,0 @@
-import SwiftUI
-
-struct ShortcutHintView: View {
-  let text: String
-  let color: Color
-
-  var body: some View {
-    Text(text)
-      .font(.caption2)
-      .foregroundStyle(color)
-  }
-}
diff --git a/supacodeTests/AgentBusyStateTests.swift b/supacodeTests/AgentBusyStateTests.swift
index 5699c77e2..bbb0f9ff5 100644
--- a/supacodeTests/AgentBusyStateTests.swift
+++ b/supacodeTests/AgentBusyStateTests.swift
@@ -106,6 +106,7 @@ struct AgentBusyStateTests {
   @Test(.dependencies) func hookNotificationRecordedForDedup() {
     withDependencies {
       $0.date = .constant(Date(timeIntervalSince1970: 1000))
+      $0.continuousClock = ImmediateClock()
     } operation: {
       let fixture = makeStateWithSurface()
 
@@ -120,132 +121,140 @@ struct AgentBusyStateTests {
     }
   }
 
-  @Test(.dependencies) func oscNotificationSuppressedWithinWindow() {
+  @Test(.dependencies) func agentOSCSuppressedWhenCustomFiredFirst() {
     withDependencies {
       $0.date = .constant(Date(timeIntervalSince1970: 1000))
+      $0.continuousClock = ImmediateClock()
     } operation: {
       let fixture = makeStateWithSurface()
-      var systemNotificationCount = 0
-      fixture.state.onNotificationReceived = { _, _, _ in
-        systemNotificationCount += 1
-      }
-
-      // Hook notification fires system notification.
-      fixture.state.appendHookNotification(
-        title: "Done",
-        body: "Task complete",
-        surfaceID: fixture.surface.id,
-      )
-      #expect(systemNotificationCount == 1)
+      var systemCount = 0
+      fixture.state.onNotificationReceived = { _, _, _ in systemCount += 1 }
 
-      // OSC 9 with identical text within the 2s window (via bridge callback).
-      fixture.surface.bridge.onDesktopNotification?("Done", "Task complete")
+      // Hook-first: our expanded custom notification fires.
+      fixture.state.appendHookNotification(title: "Done", body: "Expanded detail", surfaceID: fixture.surface.id)
+      #expect(systemCount == 1)
 
-      // The system notification should be suppressed (still 1).
-      #expect(systemNotificationCount == 1)
-      // But the in-app notification is still recorded.
-      #expect(fixture.state.notifications.count == 2)
+      // The agent's own OSC 9 summary for the same surface is dropped immediately.
+      fixture.surface.bridge.onDesktopNotification?("Done", "summary")
+      #expect(systemCount == 1)
+      #expect(fixture.state.notifications.count == 1)
+      #expect(fixture.state.debugPendingOSCCount == 0)
     }
   }
 
-  @Test(.dependencies) func oscNotificationNotSuppressedAfterWindow() {
-    let baseDate = Date(timeIntervalSince1970: 1000)
-    let currentDate = LockIsolated(baseDate)
-
-    withDependencies {
-      $0.date = .init { currentDate.value }
+  @Test(.dependencies) func agentOSCNotSuppressedAfterWindow() async {
+    let clock = TestClock()
+    await withDependencies {
+      $0.date = .constant(Date(timeIntervalSince1970: 1000))
+      $0.continuousClock = clock
     } operation: {
       let fixture = makeStateWithSurface()
-      var systemNotificationCount = 0
-      fixture.state.onNotificationReceived = { _, _, _ in
-        systemNotificationCount += 1
-      }
-
-      // Hook notification at t=1000.
-      fixture.state.appendHookNotification(
-        title: "Done",
-        body: "All complete",
-        surfaceID: fixture.surface.id,
-      )
-      #expect(systemNotificationCount == 1)
-
-      // OSC 9 at t=1003 (beyond the 2s window).
-      currentDate.setValue(baseDate.addingTimeInterval(3))
-      fixture.surface.bridge.onDesktopNotification?("Done", "All complete")
-
-      // Not suppressed — fires system notification.
-      #expect(systemNotificationCount == 2)
+      var systemCount = 0
+      fixture.state.onNotificationReceived = { _, _, _ in systemCount += 1 }
+
+      // Custom notification fires, then the suppression window fully elapses.
+      fixture.state.appendHookNotification(title: "Done", body: "Expanded detail", surfaceID: fixture.surface.id)
+      #expect(systemCount == 1)
+      await clock.advance(by: .seconds(0.6))
+
+      // The OSC 9 now lands outside the window, so it is held instead of dropped.
+      fixture.surface.bridge.onDesktopNotification?("Done", "summary")
+      await Task.megaYield()
+      #expect(systemCount == 1)
+      #expect(fixture.state.debugPendingOSCCount == 1)
+
+      // After its own hold it shows.
+      await clock.advance(by: .seconds(0.5))
+      await Task.megaYield()
+      #expect(systemCount == 2)
     }
   }
 
-  @Test(.dependencies) func genericCompletionTextSuppressedWithinWindow() {
-    withDependencies {
+  @Test(.dependencies) func agentOSCDroppedWhenCustomSupersedesDuringHold() async {
+    let clock = TestClock()
+    await withDependencies {
       $0.date = .constant(Date(timeIntervalSince1970: 1000))
+      $0.continuousClock = clock
     } operation: {
       let fixture = makeStateWithSurface()
-      var systemNotificationCount = 0
-      fixture.state.onNotificationReceived = { _, _, _ in
-        systemNotificationCount += 1
-      }
+      var systemCount = 0
+      fixture.state.onNotificationReceived = { _, _, _ in systemCount += 1 }
+
+      // OSC-9-first: the agent's summary arrives and is held.
+      fixture.surface.bridge.onDesktopNotification?("Done", "summary")
+      await Task.megaYield()
+      #expect(systemCount == 0)
+      #expect(fixture.state.debugPendingOSCCount == 1)
+
+      // Our expanded custom notification lands during the hold: it shows and the
+      // held OSC 9 is dropped.
+      fixture.state.appendHookNotification(title: "Done", body: "Expanded detail", surfaceID: fixture.surface.id)
+      #expect(systemCount == 1)
+      #expect(fixture.state.debugPendingOSCCount == 0)
+
+      await clock.advance(by: .seconds(0.5))
+      await Task.megaYield()
+      #expect(systemCount == 1)
+    }
+  }
 
-      // Hook notification with specific text.
-      fixture.state.appendHookNotification(
-        title: "Claude",
-        body: "Refactored the module",
-        surfaceID: fixture.surface.id,
-      )
-      #expect(systemNotificationCount == 1)
+  @Test(.dependencies) func agentOSCShownAfterHoldWithoutCustom() async {
+    let clock = TestClock()
+    await withDependencies {
+      $0.date = .constant(Date(timeIntervalSince1970: 1000))
+      $0.continuousClock = clock
+    } operation: {
+      let fixture = makeStateWithSurface()
+      var systemCount = 0
+      fixture.state.onNotificationReceived = { _, _, _ in systemCount += 1 }
 
-      // OSC 9 with generic "Task Complete" text.
-      fixture.surface.bridge.onDesktopNotification?("Task Complete", "")
+      fixture.surface.bridge.onDesktopNotification?("Agent", "standalone")
+      await Task.megaYield()
+      #expect(systemCount == 0)
 
-      // Generic completion text is suppressed.
-      #expect(systemNotificationCount == 1)
+      // No custom notification superseded it, so after the hold it shows.
+      await clock.advance(by: .seconds(0.5))
+      await Task.megaYield()
+      #expect(systemCount == 1)
     }
   }
 
-  @Test(.dependencies) func closingTabCleansRecentHookEntries() {
-    withDependencies {
+  @Test(.dependencies) func closingSurfaceCancelsHeldOSC() async {
+    let clock = TestClock()
+    await withDependencies {
       $0.date = .constant(Date(timeIntervalSince1970: 1000))
+      $0.continuousClock = clock
     } operation: {
       let fixture = makeStateWithSurface()
-
-      fixture.state.appendHookNotification(
-        title: "Done",
-        body: "All complete",
-        surfaceID: fixture.surface.id,
-      )
-      #expect(fixture.state.debugRecentHookCount == 1)
+      var systemCount = 0
+      fixture.state.onNotificationReceived = { _, _, _ in systemCount += 1 }
+      // No prior custom notification, so the OSC 9 is held (not suppressed).
+      fixture.surface.bridge.onDesktopNotification?("Agent", "held")
+      await Task.megaYield()
+      #expect(fixture.state.debugPendingOSCCount == 1)
 
       fixture.state.closeTab(fixture.tabId)
+      #expect(fixture.state.debugPendingOSCCount == 0)
 
-      #expect(fixture.state.debugRecentHookCount == 0)
+      // Advancing past the hold window proves the cancelled OSC never fires late.
+      await clock.advance(by: .seconds(0.5))
+      await Task.megaYield()
+      #expect(systemCount == 0)
+      #expect(fixture.state.notifications.count == 0)
     }
   }
 
-  @Test(.dependencies) func closingSurfaceCleansRecentHookEntries() {
+  @Test(.dependencies) func closingSurfaceClearsCustomNotificationTimestamp() {
     withDependencies {
       $0.date = .constant(Date(timeIntervalSince1970: 1000))
+      $0.continuousClock = ImmediateClock()
     } operation: {
       let fixture = makeStateWithSurface()
-      #expect(fixture.state.performSplitAction(.newSplit(direction: .right), for: fixture.surface.id))
-
-      let leaves = fixture.state.splitTree(for: fixture.tabId).leaves()
-      guard let splitSurface = leaves.first(where: { $0.id != fixture.surface.id }) else {
-        Issue.record("Expected split surface")
-        return
-      }
+      fixture.state.appendHookNotification(title: "Done", body: "x", surfaceID: fixture.surface.id)
+      #expect(fixture.state.debugCustomNotificationTimestampCount == 1)
 
-      fixture.state.appendHookNotification(
-        title: "Done",
-        body: "All complete",
-        surfaceID: splitSurface.id,
-      )
-      #expect(fixture.state.debugRecentHookCount == 1)
-
-      splitSurface.bridge.onCloseRequest?(false)
-
-      #expect(fixture.state.debugRecentHookCount == 0)
+      fixture.state.closeTab(fixture.tabId)
+      #expect(fixture.state.debugCustomNotificationTimestampCount == 0)
     }
   }
 
@@ -300,7 +309,7 @@ struct AgentBusyStateTests {
         "surface_id": "\(surfaceID.uuidString)"\(pidLine)
       }
       """
-    guard case .event(let event) = AgentHookSocketServer.parse(data: Data(json.utf8)) else {
+    guard let event = try? JSONDecoder().decode(AgentHookEvent.self, from: Data(json.utf8)) else {
       preconditionFailure("Failed to parse test event")
     }
     return event
diff --git a/supacodeTests/AgentHookCommandTests.swift b/supacodeTests/AgentHookCommandTests.swift
index e54d21e43..c34c6e40c 100644
--- a/supacodeTests/AgentHookCommandTests.swift
+++ b/supacodeTests/AgentHookCommandTests.swift
@@ -7,16 +7,16 @@ import Testing
 struct AgentHookCommandTests {
   // MARK: - Command generation.
 
-  @Test func compositeEnvelopeContainsEventName() {
+  @Test func compositeBusyCarriesOSCBusyEvent() {
     let command = AgentHookSettingsCommand.compositeCommand(
       events: [.busy], forwardStdinAsNotification: false, agent: .claude)
-    #expect(command.contains(#"\"event\":\"busy\""#))
+    #expect(command.contains("event=busy"))
   }
 
-  @Test func compositeIdleEnvelopeContainsIdle() {
+  @Test func compositeIdleCarriesOSCIdleEvent() {
     let command = AgentHookSettingsCommand.compositeCommand(
       events: [.idle], forwardStdinAsNotification: false, agent: .claude)
-    #expect(command.contains(#"\"event\":\"idle\""#))
+    #expect(command.contains("event=idle"))
   }
 
   // MARK: - Claude canonical hook map.
@@ -28,8 +28,8 @@ struct AgentHookCommandTests {
     let postToolUse = try #require(groups["PostToolUse"])
     let commands = Self.commandStrings(in: postToolUse)
     #expect(!commands.isEmpty)
-    #expect(commands.allSatisfy { $0.contains(#"\"event\":\"idle\""#) })
-    #expect(commands.allSatisfy { !$0.contains(#"\"event\":\"busy\""#) })
+    #expect(commands.allSatisfy { $0.contains("event=idle") })
+    #expect(commands.allSatisfy { !$0.contains("event=busy") })
   }
 
   @Test func claudePreToolUseOrdersAwaitingAfterBusy() throws {
@@ -44,12 +44,12 @@ struct AgentHookCommandTests {
     let first = try #require(preToolUse.first)
     #expect(first.objectValue?["matcher"]?.stringValue == "")
     let firstCommand = try #require(Self.commandStrings(in: [first]).first)
-    #expect(firstCommand.contains(#"\"event\":\"busy\""#))
+    #expect(firstCommand.contains("event=busy"))
 
     let second = try #require(preToolUse.last)
     #expect(second.objectValue?["matcher"]?.stringValue == "AskUserQuestion|ExitPlanMode")
     let secondCommand = try #require(Self.commandStrings(in: [second]).first)
-    #expect(secondCommand.contains(#"\"event\":\"awaiting_input\""#))
+    #expect(secondCommand.contains("event=awaiting_input"))
   }
 
   private static func commandStrings(in groups: [JSONValue]) -> [String] {
@@ -60,13 +60,17 @@ struct AgentHookCommandTests {
     }
   }
 
-  @Test func compositeChecksAllFourEnvVars() {
+  @Test func compositeGuardsOnSurfaceOnly() {
+    // OSC is the only transport now, and signals are unauthenticated: the guard
+    // is just the surface id (the no-op-outside-Supacode gate). The token and the
+    // worktree / tab ids the socket envelope carried are gone.
     let command = AgentHookSettingsCommand.compositeCommand(
       events: [.busy], forwardStdinAsNotification: false, agent: .claude)
-    #expect(command.contains("SUPACODE_SOCKET_PATH"))
-    #expect(command.contains("SUPACODE_WORKTREE_ID"))
-    #expect(command.contains("SUPACODE_TAB_ID"))
     #expect(command.contains("SUPACODE_SURFACE_ID"))
+    #expect(!command.contains("SUPACODE_OSC_TOKEN"))
+    #expect(!command.contains("token="))
+    #expect(!command.contains("SUPACODE_WORKTREE_ID"))
+    #expect(!command.contains("SUPACODE_TAB_ID"))
   }
 
   @Test func compositeSuppressesErrorsAndCarriesSentinel() {
@@ -82,11 +86,15 @@ struct AgentHookCommandTests {
     #expect(command.contains("claude"))
   }
 
-  @Test func compositeNotifyIncludesAllThreeIDs() {
-    let command = AgentHookSettingsCommand.compositeCommand(events: [], forwardStdinAsNotification: true, agent: .codex)
-    #expect(command.contains("$SUPACODE_WORKTREE_ID"))
-    #expect(command.contains("$SUPACODE_TAB_ID"))
-    #expect(command.contains("$SUPACODE_SURFACE_ID"))
+  @Test func notifyDoesNotReferenceWorktreeOrTabIDs() {
+    // The notify leg used to prefix a `worktree tab surface agent` header for
+    // the socket text proto. The OSC notify carries only base64 title/body, so
+    // those ids must be gone; only the surface-id gate remains.
+    let command = AgentHookSettingsCommand.compositeCommand(
+      events: [], forwardStdinAsNotification: true, agent: .codex)
+    #expect(!command.contains("SUPACODE_WORKTREE_ID"))
+    #expect(!command.contains("SUPACODE_TAB_ID"))
+    #expect(command.contains("SUPACODE_SURFACE_ID"))
   }
 
   // MARK: - Command ownership.
@@ -135,10 +143,8 @@ struct AgentHookCommandTests {
   }
 
   @Test func userAuthoredHookFollowingDocumentedSocketPatternIsNotOwned() {
-    // The CLI skill env table and Pi extension docs tell users to write
-    // hooks against `SUPACODE_SOCKET_PATH` via `/usr/bin/nc -U`. A
-    // user-authored hook following that exact pattern but lacking the
-    // sentinel marker must NOT be classified as legacy — otherwise
+    // A user-authored hook that talks to the socket via `/usr/bin/nc -U` but
+    // lacks the sentinel marker must NOT be classified as legacy. Otherwise
     // install would silently strip it on the next run.
     let userHook =
       #"[ -n "$SUPACODE_SOCKET_PATH" ] && echo "x" | /usr/bin/nc -U -w1 "$SUPACODE_SOCKET_PATH" || true"#
@@ -163,7 +169,7 @@ struct AgentHookCommandTests {
     // direct-nc era) shelled out to `supacode integration event`.
     // Strip-on-update must still recognise it as Supacode-managed,
     // otherwise the canonical hook is appended on top instead of
-    // replacing it — producing duplicate SessionStart hooks.
+    // replacing it, producing duplicate SessionStart hooks.
     let legacy =
       #"[ -n "${SUPACODE_SOCKET_PATH:-}" ] && supacode integration event session_start"#
       + #" --agent claude --pid "$PPID" 2>/dev/null || true"#
@@ -172,11 +178,10 @@ struct AgentHookCommandTests {
   }
 
   @Test func managedCommandSilencesStdoutAndStderr() {
-    // Codex parses SessionStart hook stdout as structured JSON output
-    // and rejects anything that doesn't match its hook output schema —
-    // so the `{"ok":true}` ack the socket server writes back through
-    // `nc` would fail the run. Hook commands must redirect both
-    // streams to /dev/null.
+    // Codex parses SessionStart hook stdout as structured JSON output and
+    // rejects anything that doesn't match its hook output schema, so the OSC
+    // escape bytes must never leak onto stdout. Hook commands redirect both
+    // streams to /dev/null (the OSC itself goes straight to /dev/tty).
     let busy = AgentHookSettingsCommand.compositeCommand(
       events: [.busy], forwardStdinAsNotification: false, agent: .claude)
     let session = AgentHookSettingsCommand.compositeCommand(
@@ -187,12 +192,16 @@ struct AgentHookCommandTests {
 
   // MARK: - Shared constants consistency.
 
-  @Test func socketPathEnvVarPresentInGeneratedCommands() {
-    let busy = AgentHookSettingsCommand.compositeCommand(
+  @Test func socketPathGatesThePresencePidSuffixOnly() {
+    // `SUPACODE_SOCKET_PATH` survives in the command solely as the local-host
+    // gate for the pid suffix on presence; the notify-only command (no pid)
+    // never references it.
+    let presence = AgentHookSettingsCommand.compositeCommand(
       events: [.busy], forwardStdinAsNotification: false, agent: .claude)
-    let notify = AgentHookSettingsCommand.compositeCommand(events: [], forwardStdinAsNotification: true, agent: .claude)
-    #expect(busy.contains(AgentHookSettingsCommand.socketPathEnvVar))
-    #expect(notify.contains(AgentHookSettingsCommand.socketPathEnvVar))
+    let notifyOnly = AgentHookSettingsCommand.compositeCommand(
+      events: [], forwardStdinAsNotification: true, agent: .claude)
+    #expect(presence.contains(AgentHookSettingsCommand.socketPathEnvVar))
+    #expect(!notifyOnly.contains(AgentHookSettingsCommand.socketPathEnvVar))
   }
 
   // MARK: - compositeCommand branches.
@@ -201,29 +210,31 @@ struct AgentHookCommandTests {
     let composite = AgentHookSettingsCommand.compositeCommand(
       events: [.sessionEnd, .idle], forwardStdinAsNotification: false, agent: .claude
     )
-    #expect(composite.contains(#"\"event\":\"session_end\""#))
-    #expect(composite.contains(#"\"event\":\"idle\""#))
-    #expect(composite.contains("{ printf"))
-    #expect(composite.contains("; }"))
-    // Order matters: session_end envelope is emitted before idle so the
-    // socket server sees the lifecycle close-out before the activity reset.
-    let sessionEndIdx = composite.range(of: "session_end")?.lowerBound
-    let idleIdx = composite.range(of: #"\"event\":\"idle\""#)?.lowerBound
+    #expect(composite.contains("event=session_end"))
+    #expect(composite.contains("event=idle"))
+    // Both presence emits live inside one guarded brace group (opened by the tty
+    // resolve) that closes before the error-suppression tail.
+    #expect(composite.contains("&& { __tty="))
+    #expect(composite.contains("; } >/dev/null 2>&1 || true"))
+    // Order matters: the session_end presence is emitted before idle so the app
+    // sees the lifecycle close-out before the activity reset.
+    let sessionEndIdx = composite.range(of: "event=session_end")?.lowerBound
+    let idleIdx = composite.range(of: "event=idle")?.lowerBound
     if let sessionEndIdx, let idleIdx {
       #expect(sessionEndIdx < idleIdx)
     }
   }
 
-  @Test func compositeEventsPlusNotifyStashesStdinBeforeEmittingEnvelopes() {
+  @Test func compositeEventsPlusNotifyEmitsPresenceBeforeNotify() {
     let composite = AgentHookSettingsCommand.compositeCommand(
       events: [.idle], forwardStdinAsNotification: true, agent: .claude
     )
-    #expect(composite.contains("payload=$(cat)"))
-    #expect(composite.contains(#"printf '%s' "$payload""#))
-    let stashIdx = composite.range(of: "payload=$(cat)")?.lowerBound
-    let envelopeIdx = composite.range(of: #"\"event\":\"idle\""#)?.lowerBound
-    if let stashIdx, let envelopeIdx {
-      #expect(stashIdx < envelopeIdx)
+    #expect(composite.contains("event=idle"))
+    #expect(composite.contains("kind=notify"))
+    let presenceIdx = composite.range(of: "event=idle")?.lowerBound
+    let notifyIdx = composite.range(of: "kind=notify")?.lowerBound
+    if let presenceIdx, let notifyIdx {
+      #expect(presenceIdx < notifyIdx)
     }
   }
 
@@ -239,186 +250,391 @@ struct AgentHookCommandTests {
     let composite = AgentHookSettingsCommand.compositeCommand(
       events: [.busy], forwardStdinAsNotification: false, agent: .claude
     )
-    let expected =
-      #"[ -n "${SUPACODE_SOCKET_PATH:-}" ] && [ -n "${SUPACODE_WORKTREE_ID:-}" ] "#
-      + #"&& [ -n "${SUPACODE_TAB_ID:-}" ] && [ -n "${SUPACODE_SURFACE_ID:-}" ] && "#
-      + #"printf '%s' "{\"event\":\"busy\",\"v\":1,\"agent\":\"claude\","#
-      + #"\"surface_id\":\"$SUPACODE_SURFACE_ID\",\"pid\":$PPID}" "#
-      + #"| /usr/bin/nc -U -w1 "$SUPACODE_SOCKET_PATH" >/dev/null 2>&1 || true # supacode-managed-hook"#
+    let expected = Self.snapshotClaudeBusy
     #expect(composite == expected)
   }
 
-  @Test func compositeByteSnapshot_claudeStopIdleAndNotify() {
+  @Test func compositeByteSnapshot_claudeIdleAndNotify() {
     let composite = AgentHookSettingsCommand.compositeCommand(
       events: [.idle], forwardStdinAsNotification: true, agent: .claude
     )
-    let expected =
-      #"[ -n "${SUPACODE_SOCKET_PATH:-}" ] && [ -n "${SUPACODE_WORKTREE_ID:-}" ] "#
-      + #"&& [ -n "${SUPACODE_TAB_ID:-}" ] && [ -n "${SUPACODE_SURFACE_ID:-}" ] && "#
-      + #"{ payload=$(cat); "#
-      + #"printf '%s' "{\"event\":\"idle\",\"v\":1,\"agent\":\"claude\","#
-      + #"\"surface_id\":\"$SUPACODE_SURFACE_ID\",\"pid\":$PPID}" "#
-      + #"| /usr/bin/nc -U -w1 "$SUPACODE_SOCKET_PATH"; "#
-      + #"{ printf '%s claude\n' "$SUPACODE_WORKTREE_ID $SUPACODE_TAB_ID $SUPACODE_SURFACE_ID"; "#
-      + #"printf '%s' "$payload"; } "#
-      + #"| /usr/bin/nc -U -w1 "$SUPACODE_SOCKET_PATH"; } >/dev/null 2>&1 || true # supacode-managed-hook"#
-    #expect(composite == expected)
+    #expect(composite == Self.snapshotClaudeIdleAndNotify)
   }
 
   @Test func compositeByteSnapshot_claudeSessionEndAndIdle() {
-    // Multi-event branch with no stdin forward. Covers the brace-grouped
-    // shape used by Claude `SessionEnd`. Without this, a refactor of the
-    // multi-event template silently flips every existing install to
-    // `.outdated` and auto-update rewrites every settings.json.
     let composite = AgentHookSettingsCommand.compositeCommand(
       events: [.sessionEnd, .idle], forwardStdinAsNotification: false, agent: .claude
     )
-    let expected =
-      #"[ -n "${SUPACODE_SOCKET_PATH:-}" ] && [ -n "${SUPACODE_WORKTREE_ID:-}" ] "#
-      + #"&& [ -n "${SUPACODE_TAB_ID:-}" ] && [ -n "${SUPACODE_SURFACE_ID:-}" ] && "#
-      + #"{ printf '%s' "{\"event\":\"session_end\",\"v\":1,\"agent\":\"claude\","#
-      + #"\"surface_id\":\"$SUPACODE_SURFACE_ID\",\"pid\":$PPID}" "#
-      + #"| /usr/bin/nc -U -w1 "$SUPACODE_SOCKET_PATH"; "#
-      + #"printf '%s' "{\"event\":\"idle\",\"v\":1,\"agent\":\"claude\","#
-      + #"\"surface_id\":\"$SUPACODE_SURFACE_ID\",\"pid\":$PPID}" "#
-      + #"| /usr/bin/nc -U -w1 "$SUPACODE_SOCKET_PATH"; } >/dev/null 2>&1 || true # supacode-managed-hook"#
-    #expect(composite == expected)
+    #expect(composite == Self.snapshotClaudeSessionEndAndIdle)
   }
 
-  @Test func compositeByteSnapshot_codexStopIdleAndNotify() {
-    // Per-agent templating parity. A refactor of `\(agent.rawValue)` in
-    // the envelope or notify pipeline could regress Codex/Kiro without
-    // tripping the Claude snapshots.
+  @Test func compositeByteSnapshot_codexIdleAndNotify() {
     let composite = AgentHookSettingsCommand.compositeCommand(
       events: [.idle], forwardStdinAsNotification: true, agent: .codex
     )
-    let expected =
-      #"[ -n "${SUPACODE_SOCKET_PATH:-}" ] && [ -n "${SUPACODE_WORKTREE_ID:-}" ] "#
-      + #"&& [ -n "${SUPACODE_TAB_ID:-}" ] && [ -n "${SUPACODE_SURFACE_ID:-}" ] && "#
-      + #"{ payload=$(cat); "#
-      + #"printf '%s' "{\"event\":\"idle\",\"v\":1,\"agent\":\"codex\","#
-      + #"\"surface_id\":\"$SUPACODE_SURFACE_ID\",\"pid\":$PPID}" "#
-      + #"| /usr/bin/nc -U -w1 "$SUPACODE_SOCKET_PATH"; "#
-      + #"{ printf '%s codex\n' "$SUPACODE_WORKTREE_ID $SUPACODE_TAB_ID $SUPACODE_SURFACE_ID"; "#
-      + #"printf '%s' "$payload"; } "#
-      + #"| /usr/bin/nc -U -w1 "$SUPACODE_SOCKET_PATH"; } >/dev/null 2>&1 || true # supacode-managed-hook"#
-    #expect(composite == expected)
+    #expect(composite == Self.snapshotCodexIdleAndNotify)
   }
 
-  @Test func compositeByteSnapshot_kiroStopIdleAndNotify() {
+  @Test func compositeByteSnapshot_kiroIdleAndNotify() {
     let composite = AgentHookSettingsCommand.compositeCommand(
       events: [.idle], forwardStdinAsNotification: true, agent: .kiro
     )
+    #expect(composite == Self.snapshotKiroIdleAndNotify)
+  }
+
+  @Test func compositeByteSnapshot_opencodeSessionEndAndIdle() {
+    // The plugin's `dispose` hook emits session_end + idle; lock its shape.
+    let composite = AgentHookSettingsCommand.compositeCommand(
+      events: [.sessionEnd, .idle], forwardStdinAsNotification: false, agent: .opencode
+    )
+    #expect(composite == Self.snapshotOpencodeSessionEndAndIdle)
+  }
+
+  @Test func compositeByteSnapshot_opencodeBusy() {
+    let composite = AgentHookSettingsCommand.compositeCommand(
+      events: [.busy], forwardStdinAsNotification: false, agent: .opencode
+    )
+    #expect(composite == Self.snapshotOpencodeBusy)
+  }
+
+  /// Cross-check against a fully-inlined literal so a refactor that drifts both
+  /// the production code AND the `presence` / `guardAndTTY` helpers cannot
+  /// pass byte-stability. The other snapshots compose from helpers that mirror
+  /// the production code structure, so they only catch drift if exactly one
+  /// side moves.
+  @Test func compositeByteSnapshot_claudeBusy_inlineLiteral() {
+    let composite = AgentHookSettingsCommand.compositeCommand(
+      events: [.busy], forwardStdinAsNotification: false, agent: .claude
+    )
     let expected =
-      #"[ -n "${SUPACODE_SOCKET_PATH:-}" ] && [ -n "${SUPACODE_WORKTREE_ID:-}" ] "#
-      + #"&& [ -n "${SUPACODE_TAB_ID:-}" ] && [ -n "${SUPACODE_SURFACE_ID:-}" ] && "#
-      + #"{ payload=$(cat); "#
-      + #"printf '%s' "{\"event\":\"idle\",\"v\":1,\"agent\":\"kiro\","#
-      + #"\"surface_id\":\"$SUPACODE_SURFACE_ID\",\"pid\":$PPID}" "#
-      + #"| /usr/bin/nc -U -w1 "$SUPACODE_SOCKET_PATH"; "#
-      + #"{ printf '%s kiro\n' "$SUPACODE_WORKTREE_ID $SUPACODE_TAB_ID $SUPACODE_SURFACE_ID"; "#
-      + #"printf '%s' "$payload"; } "#
-      + #"| /usr/bin/nc -U -w1 "$SUPACODE_SOCKET_PATH"; } >/dev/null 2>&1 || true # supacode-managed-hook"#
+      #"[ -n "${SUPACODE_SURFACE_ID:-}" ] && { "#
+      + #"__tty=$(ps -o tty= -p "$PPID" 2>/dev/null | tr -d '[:space:]'); "#
+      + #"case "$__tty" in *[0-9]*) __tty="/dev/${__tty#/dev/}";; *) __tty="/dev/tty";; esac; "#
+      + #"__sp=""; [ -n "${SUPACODE_SOCKET_PATH:-}" ] && __sp=";pid=$PPID"; "#
+      + #"printf '\033]3008;start=claude;event=busy%s\033\\' "$__sp" > "$__tty"; "#
+      + #"} >/dev/null 2>&1 || true # supacode-managed-hook"#
     #expect(composite == expected)
   }
 
-  // MARK: - Envelope round-trip.
+  // MARK: - OSC presence emission.
+
+  @Test func compositeEmitsOSCPresenceGuardedBySurface() {
+    let command = AgentHookSettingsCommand.compositeCommand(
+      events: [.busy], forwardStdinAsNotification: false, agent: .claude)
+    // OSC is the sole transport, gated only by the surface id (no-op outside
+    // Supacode). It fires local and remote alike, and carries no token.
+    #expect(command.contains("]3008;start=claude;event=busy"))
+    #expect(command.contains(#"[ -n "${SUPACODE_SURFACE_ID:-}" ]"#))
+    #expect(!command.contains("token="))
+    #expect(command.contains(#"> "$__tty""#))
+    #expect(command.contains("ps -o tty="))
+    #expect(!command.contains(#"[ -z "${SUPACODE_SOCKET_PATH:-}" ]"#))
+  }
+
+  @Test func sessionStartComposesOSCPresenceForClaudeAndCodex() {
+    for agent in [SkillAgent.claude, .codex, .opencode] {
+      let command = AgentHookSettingsCommand.compositeCommand(
+        events: [.sessionStart], forwardStdinAsNotification: false, agent: agent)
+      #expect(command.contains("]3008;start=\(agent.rawValue);event=session_start"))
+    }
+  }
+
+  @Test func sessionEndUsesOSCEndAction() {
+    let command = AgentHookSettingsCommand.compositeCommand(
+      events: [.sessionEnd, .idle], forwardStdinAsNotification: false, agent: .claude)
+    #expect(command.contains("]3008;end=claude;event=session_end"))
+  }
+
+  @Test func awaitingInputComposesOSCPresence() {
+    // awaiting_input is the badge-critical "needs you" state; assert it rides OSC too.
+    let command = AgentHookSettingsCommand.compositeCommand(
+      events: [.awaitingInput], forwardStdinAsNotification: false, agent: .claude)
+    #expect(command.contains("]3008;start=claude;event=awaiting_input"))
+  }
+
+  @Test func notifyOnlyComposesNotifyOSCButNoPresenceOSC() {
+    // Notify-only (no events) emits the notify OSC but no presence OSC.
+    let command = AgentHookSettingsCommand.compositeCommand(
+      events: [], forwardStdinAsNotification: true, agent: .claude)
+    #expect(command.contains("]3008;start=claude;kind=notify;"))
+    #expect(!command.contains(";event="))
+  }
+
+  @Test func notifyComposesOSCNotify() {
+    let command = AgentHookSettingsCommand.compositeCommand(
+      events: [.idle], forwardStdinAsNotification: true, agent: .claude)
+    #expect(command.contains("]3008;start=claude;kind=notify;title=%s;body=%s"))
+    #expect(command.contains("base64 | tr -d"))
+  }
+
+  @Test func eventOnlyCommandEmitsNoOSCNotify() {
+    let command = AgentHookSettingsCommand.compositeCommand(
+      events: [.busy], forwardStdinAsNotification: false, agent: .claude)
+    #expect(!command.contains("kind=notify"))
+  }
+
+  // MARK: - Runtime behaviour (real shell).
 
-  /// Executes the command in a real shell with all required env vars set
-  /// and a fake `nc` on PATH that captures stdin to a file. Verifies the
-  /// JSON the hook produced is parseable by the same code that consumes
-  /// it on the socket — a regression guard against future Swift changes
-  /// that subtly break the envelope template.
-  @Test func compositeEnvelopeProducesParseableJSON() throws {
+  @Test func presenceCarriesLocalPidButNotRemote() throws {
+    // The pid suffix is the local/remote discriminator: present when
+    // SUPACODE_SOCKET_PATH is set (local host), absent over SSH. A regression
+    // that always or never emitted it would silently break the liveness sweep.
+    let base: [String: String] = ["SUPACODE_SURFACE_ID": UUID().uuidString]
+    let command = AgentHookSettingsCommand.compositeCommand(
+      events: [.busy], forwardStdinAsNotification: false, agent: .claude)
+
+    // Local (socket present): the presence OSC carries a positive pid.
+    let local = try runHookCommandCapturingTTY(
+      command, env: base.merging(["SUPACODE_SOCKET_PATH": "/tmp/sock-\(UUID().uuidString)"]) { $1 })
+    let localSignal = try #require(Self.parsePresence(fromTTY: local))
+    #expect(localSignal.eventRawValue == "busy")
+    #expect((localSignal.pid ?? 0) > 0)
+
+    // Remote (socket absent): the presence OSC lands but carries no pid.
+    let remote = try runHookCommandCapturingTTY(command, env: base)
+    let remoteSignal = try #require(Self.parsePresence(fromTTY: remote))
+    #expect(remoteSignal.eventRawValue == "busy")
+    #expect(remoteSignal.pid == nil)
+  }
+
+  @Test func notifyExtractsBodyFromStdinThroughAwk() throws {
+    // End-to-end: the real shell hook runs the awk extractor over Claude's stdin
+    // JSON and the resulting OSC parses back with the body intact.
+    let json = #"{"hook_event_name":"Stop","message":"hi there"}"#
+    let base: [String: String] = ["SUPACODE_SURFACE_ID": UUID().uuidString]
+    let command = AgentHookSettingsCommand.compositeCommand(
+      events: [], forwardStdinAsNotification: true, agent: .claude)
+    let tty = try runHookCommandCapturingTTY(command, env: base, stdin: json)
+    let signal = try #require(Self.parseNotify(fromTTY: tty))
+    #expect(signal.body == "hi there")
+  }
+
+  @Test func notifyAwkPreservesEscapedQuotesNewlinesAndUnicode() throws {
+    // The awk extractor must copy the escaped JSON value verbatim so embedded
+    // quotes / newlines / unicode survive the round-trip, and pick the body via
+    // the precedence list (here `last_assistant_message`, with `message` empty).
+    let json =
+      #"{"hook_event_name":"Stop","title":"Done","message":"","last_assistant_message":"line \"one\"\nDONE ✓"}"#
+    let base: [String: String] = ["SUPACODE_SURFACE_ID": UUID().uuidString]
+    let command = AgentHookSettingsCommand.compositeCommand(
+      events: [.idle], forwardStdinAsNotification: true, agent: .claude)
+    let tty = try runHookCommandCapturingTTY(command, env: base, stdin: json)
+    #expect(tty.contains("]3008;start=claude;event=idle"))
+    let signal = try #require(Self.parseNotify(fromTTY: tty))
+    #expect(signal.title == "Done")
+    #expect(signal.body == "line \"one\"\nDONE ✓")
+  }
+
+  @Test(arguments: [
+    // message wins over the fallbacks.
+    (#"{"message":"primary","last_assistant_message":"secondary","assistant_response":"tertiary"}"#, "primary"),
+    // The awk is not type-aware: empty / null / numeric `message` falls through only
+    // because `fv` requires an opening `"` after the colon and finds none.
+    (#"{"message":"","last_assistant_message":"fallback"}"#, "fallback"),
+    (#"{"message":null,"last_assistant_message":"fallback"}"#, "fallback"),
+    (#"{"message":42,"assistant_response":"kiro body"}"#, "kiro body"),
+    (#"{"assistant_response":"kiro body"}"#, "kiro body"),
+  ])
+  func notifyAwkResolvesBodyByPrecedence(json: String, expectedBody: String) throws {
+    let base: [String: String] = ["SUPACODE_SURFACE_ID": UUID().uuidString]
+    let command = AgentHookSettingsCommand.compositeCommand(
+      events: [], forwardStdinAsNotification: true, agent: .claude)
+    let tty = try runHookCommandCapturingTTY(command, env: base, stdin: json)
+    let signal = try #require(Self.parseNotify(fromTTY: tty))
+    #expect(signal.body == expectedBody)
+  }
+
+  @Test func notifyByteCapFiresAndWireStaysUnderOSCCeiling() throws {
+    // Drive a body past notifyBodyByteBudget through the REAL awk and assert the
+    // emitted metadata stays under libghostty's 2048-byte OSC ceiling (the headline
+    // guarantee) and the decoded body is a sane truncated prefix. Exercises the
+    // `length(v)>budget` branch and the LC_ALL=C byte cap end to end.
+    let bodyText = String(repeating: "a", count: 4000)
+    let json = #"{"hook_event_name":"Stop","message":"\#(bodyText)"}"#
+    let base: [String: String] = ["SUPACODE_SURFACE_ID": UUID().uuidString]
+    let command = AgentHookSettingsCommand.compositeCommand(
+      events: [], forwardStdinAsNotification: true, agent: .claude)
+    let tty = try runHookCommandCapturingTTY(command, env: base, stdin: json)
+    // Metadata is everything after `]3008;` up to ST; assert it is under the cap.
+    let marker = try #require(tty.range(of: "]3008;"))
+    let afterMarker = tty[marker.upperBound...]
+    let stRange = try #require(afterMarker.range(of: "\u{1b}\\"))
+    #expect(afterMarker[..<stRange.lowerBound].utf8.count < 2048)
+    let signal = try #require(Self.parseNotify(fromTTY: tty))
+    #expect(signal.body?.isEmpty == false)
+    #expect(signal.body?.allSatisfy { $0 == "a" } == true)
+  }
+
+  @Test func notifyMultibyteBodyCapDecodesToCleanPrefix() throws {
+    // A multibyte (non-ASCII) body driven past the byte budget is the realistic
+    // silent-drop risk for non-English agent output: LC_ALL=C makes the awk cap
+    // byte-based, so it can sever a 3-byte codepoint mid-sequence. The shed loop
+    // in decodeNotifyValue must recover a clean prefix, not corrupt to U+FFFD or
+    // drop the whole body. "日" is 3 bytes, so 2000 of them blow past the 1000-byte
+    // budget and the cap lands mid-codepoint.
+    let bodyText = String(repeating: "日", count: 2000)
+    let json = #"{"hook_event_name":"Stop","message":"\#(bodyText)"}"#
+    let base: [String: String] = ["SUPACODE_SURFACE_ID": UUID().uuidString]
+    let command = AgentHookSettingsCommand.compositeCommand(
+      events: [], forwardStdinAsNotification: true, agent: .claude)
+    let tty = try runHookCommandCapturingTTY(command, env: base, stdin: json)
+    let signal = try #require(Self.parseNotify(fromTTY: tty))
+    #expect(signal.body?.isEmpty == false)
+    // Every surviving character is a whole "日": no partial codepoint, no U+FFFD.
+    #expect(signal.body?.allSatisfy { $0 == "日" } == true)
+  }
+
+  @Test func notifyAwkIgnoresKeyTextEscapedInsideAnEarlierValue() throws {
+    // The awk matches the first `"message":` occurrence. An earlier value that
+    // mentions the key can only do so with escaped quotes (valid JSON), so the
+    // `"message"` token (quote-key-quote) never matches inside it: the real
+    // top-level field still wins. Pins that JSON escaping protects flat extraction.
+    let json = #"{"title":"see \"message\": here","message":"real body"}"#
+    let base: [String: String] = ["SUPACODE_SURFACE_ID": UUID().uuidString]
+    let command = AgentHookSettingsCommand.compositeCommand(
+      events: [], forwardStdinAsNotification: true, agent: .claude)
+    let tty = try runHookCommandCapturingTTY(command, env: base, stdin: json)
+    let signal = try #require(Self.parseNotify(fromTTY: tty))
+    #expect(signal.title == #"see "message": here"#)
+    #expect(signal.body == "real body")
+  }
+
+  @Test func emitsNothingOutsideSupacode() throws {
+    // No SUPACODE_SURFACE_ID = not a Supacode surface: the guard short-circuits
+    // and the command writes nothing to the tty (the inert-outside-Supacode
+    // contract).
+    let command = AgentHookSettingsCommand.compositeCommand(
+      events: [.busy], forwardStdinAsNotification: true, agent: .claude)
+    let tty = try runHookCommandCapturingTTY(command, env: [:], stdin: "{}")
+    #expect(tty.isEmpty)
+  }
+
+  // MARK: - OSC presence round-trip.
+
+  @Test func presenceOSCRoundTripsThroughParser() throws {
+    // The shell-produced OSC must parse back into a well-formed, pid-bearing
+    // signal. A guard against a template change that subtly breaks the wire.
     let surfaceID = UUID()
-    let agentPid: pid_t = getpid()
-    let captured = try runHookCommandCapturingStdin(
+    let captured = try runHookCommandCapturingTTY(
       AgentHookSettingsCommand.compositeCommand(
         events: [.sessionStart], forwardStdinAsNotification: false, agent: .claude),
       env: [
-        "SUPACODE_SOCKET_PATH": "/tmp/supacode-roundtrip-\(UUID().uuidString)",
-        "SUPACODE_WORKTREE_ID": "/some/worktree",
-        "SUPACODE_TAB_ID": UUID().uuidString,
         "SUPACODE_SURFACE_ID": surfaceID.uuidString,
-      ]
-    )
-    guard case .event(let parsed) = AgentHookSocketServer.parse(data: captured) else {
-      Issue.record("Expected parser to recognise envelope; got nil/non-event from \(captured.count) bytes")
-      return
-    }
-    #expect(parsed.eventName == .sessionStart)
-    #expect(parsed.agent == "claude")
-    #expect(parsed.surfaceID == surfaceID)
-    // PPID inside the shell is whatever spawned it (Process), not the
-    // test's pid — so just check it's positive and decodes cleanly.
-    #expect((parsed.pid ?? 0) > 0)
-  }
-
-  /// Composite shell roundtrip for `forwardStdinAsNotification: true`:
-  /// pipes representative Claude `Stop` JSON through the `idle + notify`
-  /// composite, captures both `nc -U` writes, and asserts the parser
-  /// recognises the first as an idle event and the second as a notification.
-  @Test func compositeIdleAndNotifyProducesParseableEventThenNotification() throws {
-    let surfaceID = UUID()
-    let stopPayload =
-      #"{"stop_hook_active":false,"hook_event_name":"Stop","last_assistant_message":"Done."}"#
-    let captures = try runHookCommandCapturingMultipleStdin(
-      AgentHookSettingsCommand.compositeCommand(
-        events: [.idle], forwardStdinAsNotification: true, agent: .claude
-      ),
-      stdin: stopPayload,
-      env: [
         "SUPACODE_SOCKET_PATH": "/tmp/supacode-rt-\(UUID().uuidString)",
-        "SUPACODE_WORKTREE_ID": "/some/worktree",
-        "SUPACODE_TAB_ID": UUID().uuidString,
-        "SUPACODE_SURFACE_ID": surfaceID.uuidString,
       ]
     )
-    #expect(captures.count == 2)
-    guard captures.count == 2 else { return }
-    guard case .event(let event) = AgentHookSocketServer.parse(data: captures[0]) else {
-      Issue.record("Expected first capture to be an idle event envelope")
-      return
-    }
-    #expect(event.eventName == .idle)
-    #expect(event.surfaceID == surfaceID)
+    let signal = try #require(Self.parsePresence(fromTTY: captured))
+    #expect(signal.agent == "claude")
+    #expect(signal.eventRawValue == "session_start")
+    // PPID inside the shell is whatever spawned it (Process), not the test's
+    // pid, so just check it decoded as positive.
+    #expect((signal.pid ?? 0) > 0)
+  }
+
+  /// Reconstructs libghostty's OSC 3008 split from a captured tty stream: the
+  /// first `verb=id` field becomes the context id, the rest is the metadata
+  /// `parse` consumes. Returns the parsed signal.
+  private static func parsePresence(fromTTY tty: String) -> AgentPresenceOSC.Signal? {
+    guard let marker = tty.range(of: "]3008;") else { return nil }
+    let afterMarker = tty[marker.upperBound...]
+    guard let stRange = afterMarker.range(of: "\u{1b}\\") else { return nil }
+    let body = afterMarker[..<stRange.lowerBound]
+    guard let firstSemi = body.firstIndex(of: ";") else { return nil }
+    let firstField = body[..<firstSemi]
+    let metadata = String(body[body.index(after: firstSemi)...])
+    guard let equals = firstField.firstIndex(of: "=") else { return nil }
+    let id = String(firstField[firstField.index(after: equals)...])
+    return AgentPresenceOSC.parse(id: id, metadata: metadata)
+  }
+
+  /// Same split as `parsePresence`, but targets the notify OSC (which may follow a
+  /// presence OSC in the same tty stream) by anchoring on its `kind=notify`.
+  private static func parseNotify(fromTTY tty: String) -> AgentPresenceOSC.NotifySignal? {
+    guard let kindRange = tty.range(of: "kind=notify") else { return nil }
     guard
-      case .notification(_, _, let notifSurfaceID, let notification) = AgentHookSocketServer.parse(data: captures[1])
-    else {
-      Issue.record("Expected second capture to be a notification (header + payload)")
-      return
-    }
-    #expect(notification.agent == "claude")
-    #expect(notifSurfaceID == surfaceID)
-    // The notification body decodes from `last_assistant_message`, confirming
-    // `$(cat)` preserved the payload across the brace-grouped pipeline.
-    #expect(notification.body == "Done.")
-  }
-
-  /// Multi-nc variant of `runHookCommandCapturingStdin`. The stub appends
-  /// each invocation's stdin to a single file separated by a sentinel
-  /// line, then we split on the sentinel to return one `Data` per `nc`.
-  private func runHookCommandCapturingMultipleStdin(
-    _ command: String, stdin: String, env: [String: String]
-  ) throws -> [Data] {
+      let marker = tty.range(
+        of: "]3008;", options: .backwards, range: tty.startIndex..<kindRange.lowerBound)
+    else { return nil }
+    let afterMarker = tty[marker.upperBound...]
+    guard let stRange = afterMarker.range(of: "\u{1b}\\") else { return nil }
+    let body = afterMarker[..<stRange.lowerBound]
+    guard let firstSemi = body.firstIndex(of: ";") else { return nil }
+    let firstField = body[..<firstSemi]
+    let metadata = String(body[body.index(after: firstSemi)...])
+    guard let equals = firstField.firstIndex(of: "=") else { return nil }
+    let id = String(firstField[firstField.index(after: equals)...])
+    return AgentPresenceOSC.parseNotify(id: id, metadata: metadata)
+  }
+
+  // Shared head: surface-id guard, then (inside one brace group) resolve $__tty
+  // from the parent agent's controlling terminal since the hook has none of its own.
+  private static let guardAndTTY =
+    #"[ -n "${SUPACODE_SURFACE_ID:-}" ] && { "#
+    + #"__tty=$(ps -o tty= -p "$PPID" 2>/dev/null | tr -d '[:space:]'); "#
+    + #"case "$__tty" in *[0-9]*) __tty="/dev/${__tty#/dev/}";; *) __tty="/dev/tty";; esac; "#
+  private static let suppressTail = #"} >/dev/null 2>&1 || true # supacode-managed-hook"#
+
+  private static func presence(_ action: String, _ agent: String, _ event: String) -> String {
+    #"__sp=""; [ -n "${SUPACODE_SOCKET_PATH:-}" ] && __sp=";pid=$PPID"; "#
+      + #"printf '\033]3008;\#(action)=\#(agent);event=\#(event)%s\033\\' "$__sp" > "$__tty"; "#
+  }
+
+  private static func notify(_ agent: String) -> String {
+    let bodyKeys = AgentPresenceOSC.notifyBodyKeys.joined(separator: ",")
+    let awk = AgentPresenceOSC.notifyExtractAwk
+    return #"__in=$(cat); "#
+      + #"__t=$(printf '%s' "$__in" | LC_ALL=C awk -v keys="\#(AgentPresenceOSC.titleField)" "#
+      + #"-v budget=\#(AgentPresenceOSC.notifyTitleByteBudget) '\#(awk)' | base64 | tr -d '\n'); "#
+      + #"__b=$(printf '%s' "$__in" | LC_ALL=C awk -v keys="\#(bodyKeys)" "#
+      + #"-v budget=\#(AgentPresenceOSC.notifyBodyByteBudget) '\#(awk)' | base64 | tr -d '\n'); "#
+      + #"printf '\033]3008;start=\#(agent);kind=notify;title=%s;body=%s\033\\' "$__t" "$__b" > "$__tty"; "#
+  }
+
+  static let snapshotClaudeBusy =
+    guardAndTTY + presence("start", "claude", "busy") + suppressTail
+
+  static let snapshotClaudeIdleAndNotify =
+    guardAndTTY + presence("start", "claude", "idle") + notify("claude") + suppressTail
+
+  static let snapshotClaudeSessionEndAndIdle =
+    guardAndTTY + presence("end", "claude", "session_end") + presence("start", "claude", "idle") + suppressTail
+
+  static let snapshotCodexIdleAndNotify =
+    guardAndTTY + presence("start", "codex", "idle") + notify("codex") + suppressTail
+
+  static let snapshotKiroIdleAndNotify =
+    guardAndTTY + presence("start", "kiro", "idle") + notify("kiro") + suppressTail
+
+  static let snapshotOpencodeBusy =
+    guardAndTTY + presence("start", "opencode", "busy") + suppressTail
+
+  static let snapshotOpencodeSessionEndAndIdle =
+    guardAndTTY + presence("end", "opencode", "session_end") + presence("start", "opencode", "idle") + suppressTail
+
+  /// Runs `command` with `/dev/tty` (the OSC sink) redirected to a capture file,
+  /// optionally feeding `stdin`, and returns the text written to the fake tty.
+  private func runHookCommandCapturingTTY(
+    _ command: String, env: [String: String], stdin: String = ""
+  ) throws -> String {
     let workDir = URL(fileURLWithPath: NSTemporaryDirectory())
-      .appendingPathComponent("supacode-hook-multi-\(UUID().uuidString)", isDirectory: true)
+      .appendingPathComponent("supacode-hook-tty-\(UUID().uuidString)", isDirectory: true)
     try FileManager.default.createDirectory(at: workDir, withIntermediateDirectories: true)
     defer { try? FileManager.default.removeItem(at: workDir) }
-    let stubBin = workDir.appendingPathComponent("bin", isDirectory: true)
-    try FileManager.default.createDirectory(at: stubBin, withIntermediateDirectories: true)
-    let stubNC = stubBin.appendingPathComponent("nc")
-    let captureFile = workDir.appendingPathComponent("capture")
-    let boundary = "---NC-CAPTURE-BOUNDARY---"
-    try "#!/bin/sh\ncat >> '\(captureFile.path)'\nprintf '\\n\(boundary)\\n' >> '\(captureFile.path)'\n"
-      .write(to: stubNC, atomically: true, encoding: .utf8)
-    try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: stubNC.path)
-    let patched = command.replacing("/usr/bin/nc", with: stubNC.path)
+    let captureFile = workDir.appendingPathComponent("tty")
+    FileManager.default.createFile(atPath: captureFile.path, contents: nil)
+    // Append (`>>`) not truncate: a real /dev/tty streams, so multiple OSC writes
+    // (presence + notify) must both land. A plain `> file` would have the second
+    // printf clobber the first.
+    let patched = command.replacing(#"> "$__tty""#, with: ">> \(captureFile.path)")
 
     let process = Process()
     process.executableURL = URL(fileURLWithPath: "/bin/zsh")
     process.arguments = ["-c", patched]
     var environment = ProcessInfo.processInfo.environment
+    // The host may already export Supacode-surface vars (tests can run inside a
+    // Supacode surface); clear them so every absent-variable assertion is genuine.
+    environment.removeValue(forKey: "SUPACODE_SOCKET_PATH")
+    environment.removeValue(forKey: "SUPACODE_SURFACE_ID")
     for (key, value) in env { environment[key] = value }
     process.environment = environment
     let stdinPipe = Pipe()
@@ -427,47 +643,6 @@ struct AgentHookCommandTests {
     stdinPipe.fileHandleForWriting.write(Data(stdin.utf8))
     try? stdinPipe.fileHandleForWriting.close()
     process.waitUntilExit()
-
-    let raw = (try? Data(contentsOf: captureFile)) ?? Data()
-    guard let text = String(data: raw, encoding: .utf8) else { return [] }
-    return text.components(separatedBy: "\n\(boundary)\n")
-      .dropLast()  // trailing element after the last boundary is empty.
-      .map { Data($0.utf8) }
-  }
-
-  /// Run `command` via `/bin/zsh -c`, with a stub `nc` on PATH that
-  /// dumps its stdin to a temp file. Returns the captured stdin bytes.
-  private func runHookCommandCapturingStdin(
-    _ command: String, env: [String: String]
-  ) throws -> Data {
-    let workDir = URL(fileURLWithPath: NSTemporaryDirectory())
-      .appendingPathComponent("supacode-hook-rt-\(UUID().uuidString)", isDirectory: true)
-    try FileManager.default.createDirectory(at: workDir, withIntermediateDirectories: true)
-    defer { try? FileManager.default.removeItem(at: workDir) }
-
-    // Stub nc that ignores its args (e.g. `-U -w1 <socket>`) and writes
-    // stdin to ./capture so we can read the JSON the hook produced.
-    let stubBin = workDir.appendingPathComponent("bin", isDirectory: true)
-    try FileManager.default.createDirectory(at: stubBin, withIntermediateDirectories: true)
-    let stubNC = stubBin.appendingPathComponent("nc")
-    let captureFile = workDir.appendingPathComponent("capture")
-    try "#!/bin/sh\ncat > '\(captureFile.path)'\n".write(to: stubNC, atomically: true, encoding: .utf8)
-    try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: stubNC.path)
-
-    // The hook hard-codes `/usr/bin/nc`, so symlink that path target
-    // into a private prefix. We cheat by patching the command string
-    // for this test to call the stub instead.
-    let patched = command.replacing("/usr/bin/nc", with: stubNC.path)
-
-    let process = Process()
-    process.executableURL = URL(fileURLWithPath: "/bin/zsh")
-    process.arguments = ["-c", patched]
-    var environment = ProcessInfo.processInfo.environment
-    for (key, value) in env { environment[key] = value }
-    process.environment = environment
-    try process.run()
-    process.waitUntilExit()
-
-    return (try? Data(contentsOf: captureFile)) ?? Data()
+    return (try? String(contentsOf: captureFile, encoding: .utf8)) ?? ""
   }
 }
diff --git a/supacodeTests/AgentHookSocketServerTests.swift b/supacodeTests/AgentHookSocketServerTests.swift
index 72c76d340..e8f690171 100644
--- a/supacodeTests/AgentHookSocketServerTests.swift
+++ b/supacodeTests/AgentHookSocketServerTests.swift
@@ -6,199 +6,21 @@ import Testing
 
 @MainActor
 struct AgentHookSocketServerTests {
-  // MARK: - Legacy single-line text payload (no longer parsed).
+  // MARK: - CLI protocol framing.
 
-  @Test func singleLineTextPayloadIsRejected() {
-    // The text-protocol busy message (`worktreeID tabID surfaceID 0|1`)
-    // was retired in favor of the JSON envelope. Any single-line text
-    // header now returns nil — exercises the new guard in `parse`.
+  @Test func nonJSONPayloadIsRejected() {
+    // The socket carries only the CLI control protocol (JSON command / query).
+    // Anything that is not a JSON object is dropped.
     let raw = "wt \(UUID().uuidString) \(UUID().uuidString) 1"
     #expect(AgentHookSocketServer.parse(data: Data(raw.utf8)) == nil)
   }
 
-  // MARK: - Notification message parsing.
-
-  @Test func parsesValidNotificationWithPayload() {
-    let tabID = UUID()
-    let surfaceID = UUID()
-    let payload = #"{"hook_event_name":"Stop","title":"Done","message":"All tasks complete"}"#
-    let raw = "wt \(tabID.uuidString) \(surfaceID.uuidString) claude\n\(payload)"
-    let message = AgentHookSocketServer.parse(data: Data(raw.utf8))
-
-    guard case .notification(_, let tID, let sID, let notification) = message else {
-      Issue.record("Expected notification message, got \(String(describing: message))")
-      return
-    }
-    #expect(tID == tabID)
-    #expect(sID == surfaceID)
-    #expect(notification.agent == "claude")
-    #expect(notification.event == "Stop")
-    #expect(notification.title == "Done")
-    #expect(notification.body == "All tasks complete")
-  }
-
-  @Test func parsesNotificationWithLastAssistantMessageFallback() {
-    let tabID = UUID()
-    let surfaceID = UUID()
-    let payload = #"{"hook_event_name":"Stop","last_assistant_message":"fallback body"}"#
-    let raw = "wt \(tabID.uuidString) \(surfaceID.uuidString) codex\n\(payload)"
-    let message = AgentHookSocketServer.parse(data: Data(raw.utf8))
-
-    guard case .notification(_, _, _, let notification) = message else {
-      Issue.record("Expected notification message")
-      return
-    }
-    #expect(notification.agent == "codex")
-    #expect(notification.body == "fallback body")
-  }
-
-  @Test func parsesNotificationWithAssistantResponseFallback() {
-    let tabID = UUID()
-    let surfaceID = UUID()
-    let payload = #"{"hook_event_name":"stop","assistant_response":"kiro body"}"#
-    let raw = "wt \(tabID.uuidString) \(surfaceID.uuidString) kiro\n\(payload)"
-    let message = AgentHookSocketServer.parse(data: Data(raw.utf8))
-
-    guard case .notification(_, _, _, let notification) = message else {
-      Issue.record("Expected notification message")
-      return
-    }
-    #expect(notification.agent == "kiro")
-    #expect(notification.body == "kiro body")
-  }
-
-  @Test func lastAssistantMessageTakesPrecedenceOverAssistantResponse() {
-    let tabID = UUID()
-    let surfaceID = UUID()
-    let payload = """
-      {"hook_event_name":"Stop","last_assistant_message":"codex body","assistant_response":"kiro body"}
-      """
-    let raw = "wt \(tabID.uuidString) \(surfaceID.uuidString) codex\n\(payload)"
-    let message = AgentHookSocketServer.parse(data: Data(raw.utf8))
-
-    guard case .notification(_, _, _, let notification) = message else {
-      Issue.record("Expected notification message")
-      return
-    }
-    #expect(notification.body == "codex body")
-  }
-
-  @Test func messageFieldTakesPrecedenceOverAllFallbacks() {
-    let tabID = UUID()
-    let surfaceID = UUID()
-    let payload =
-      #"{"hook_event_name":"Stop","message":"primary","#
-      + #""last_assistant_message":"secondary","assistant_response":"tertiary"}"#
-    let raw = "wt \(tabID.uuidString) \(surfaceID.uuidString) claude\n\(payload)"
-    let message = AgentHookSocketServer.parse(data: Data(raw.utf8))
-
-    guard case .notification(_, _, _, let notification) = message else {
-      Issue.record("Expected notification message")
-      return
-    }
-    #expect(notification.body == "primary")
-  }
-
-  @Test func nullMessageFieldFallsThroughToLastAssistantMessage() {
-    let tabID = UUID()
-    let surfaceID = UUID()
-    let payload = #"{"hook_event_name":"Stop","message":null,"last_assistant_message":"fallback"}"#
-    let raw = "wt \(tabID.uuidString) \(surfaceID.uuidString) codex\n\(payload)"
-    let message = AgentHookSocketServer.parse(data: Data(raw.utf8))
-
-    guard case .notification(_, _, _, let notification) = message else {
-      Issue.record("Expected notification message")
-      return
-    }
-    #expect(notification.body == "fallback")
-  }
-
-  @Test func emptyStringMessageFieldFallsThroughToFallback() {
-    let tabID = UUID()
-    let surfaceID = UUID()
-    let payload =
-      #"{"hook_event_name":"Stop","message":"","last_assistant_message":"real body"}"#
-    let raw = "wt \(tabID.uuidString) \(surfaceID.uuidString) codex\n\(payload)"
-    let message = AgentHookSocketServer.parse(data: Data(raw.utf8))
-
-    guard case .notification(_, _, _, let notification) = message else {
-      Issue.record("Expected notification message")
-      return
-    }
-    #expect(notification.body == "real body")
-  }
-
-  @Test func typeMismatchOnMessageFieldFallsThroughToFallback() {
-    let tabID = UUID()
-    let surfaceID = UUID()
-    // Claude-shape with an unexpectedly numeric message: decoder must
-    // tolerate the mismatch and fall through to assistant_response.
-    let payload =
-      #"{"hook_event_name":"stop","message":42,"assistant_response":"kiro body"}"#
-    let raw = "wt \(tabID.uuidString) \(surfaceID.uuidString) kiro\n\(payload)"
-    let message = AgentHookSocketServer.parse(data: Data(raw.utf8))
-
-    guard case .notification(_, _, _, let notification) = message else {
-      Issue.record("Expected notification message")
-      return
-    }
-    #expect(notification.body == "kiro body")
-  }
-
-  @Test func invalidJSONPayloadDropsNotification() {
-    let tabID = UUID()
-    let surfaceID = UUID()
-    let raw = "wt \(tabID.uuidString) \(surfaceID.uuidString) claude\nnot json at all"
-    let message = AgentHookSocketServer.parse(data: Data(raw.utf8))
-
-    #expect(message == nil)
-  }
-
-  // MARK: - Malformed messages.
-
-  @Test func malformedHeaderWithFewerThanThreeFieldsReturnsNil() {
-    let message = AgentHookSocketServer.parse(data: Data("wt only-two-fields".utf8))
-    #expect(message == nil)
-  }
-
-  @Test func invalidTabIDReturnsNil() {
-    let surfaceID = UUID()
-    let raw = "wt not-a-uuid \(surfaceID.uuidString) claude\n{\"hook_event_name\":\"Stop\"}"
-    let message = AgentHookSocketServer.parse(data: Data(raw.utf8))
-    #expect(message == nil)
-  }
-
-  @Test func invalidSurfaceIDReturnsNil() {
-    let tabID = UUID()
-    let raw = "wt \(tabID.uuidString) not-a-uuid claude\n{\"hook_event_name\":\"Stop\"}"
-    let message = AgentHookSocketServer.parse(data: Data(raw.utf8))
-    #expect(message == nil)
-  }
-
   @Test func emptyInputReturnsNil() {
-    let message = AgentHookSocketServer.parse(data: Data())
-    #expect(message == nil)
+    #expect(AgentHookSocketServer.parse(data: Data()) == nil)
   }
 
   @Test func whitespaceOnlyInputReturnsNil() {
-    let message = AgentHookSocketServer.parse(data: Data("   \n  \n  ".utf8))
-    #expect(message == nil)
-  }
-
-  // MARK: - Agent name defaults.
-
-  @Test func missingAgentNameDefaultsToUnknown() {
-    let tabID = UUID()
-    let surfaceID = UUID()
-    // Only 3 header fields + a second line → notification with no agent.
-    let raw = "wt \(tabID.uuidString) \(surfaceID.uuidString)\n{\"hook_event_name\":\"Stop\"}"
-    let message = AgentHookSocketServer.parse(data: Data(raw.utf8))
-
-    guard case .notification(_, _, _, let notification) = message else {
-      Issue.record("Expected notification message")
-      return
-    }
-    #expect(notification.agent == "unknown")
+    #expect(AgentHookSocketServer.parse(data: Data("   \n  \n  ".utf8)) == nil)
   }
 
   // MARK: - CLI command message parsing.
@@ -217,14 +39,12 @@ struct AgentHookSocketServerTests {
 
   @Test func rejectsCommandWithInvalidScheme() {
     let json = #"{"deeplink":"https://example.com"}"#
-    let message = AgentHookSocketServer.parse(data: Data(json.utf8))
-    #expect(message == nil)
+    #expect(AgentHookSocketServer.parse(data: Data(json.utf8)) == nil)
   }
 
   @Test func rejectsCommandWithMalformedJSON() {
     let json = #"{"not_deeplink":"supacode://test"}"#
-    let message = AgentHookSocketServer.parse(data: Data(json.utf8))
-    #expect(message == nil)
+    #expect(AgentHookSocketServer.parse(data: Data(json.utf8)) == nil)
   }
 
   // MARK: - Query message parsing.
@@ -266,8 +86,7 @@ struct AgentHookSocketServerTests {
 
   @Test func rejectsJSONWithNeitherQueryNorDeeplink() {
     let json = #"{"foo":"bar"}"#
-    let message = AgentHookSocketServer.parse(data: Data(json.utf8))
-    #expect(message == nil)
+    #expect(AgentHookSocketServer.parse(data: Data(json.utf8)) == nil)
   }
 
   // MARK: - readPayload.
@@ -277,13 +96,15 @@ struct AgentHookSocketServerTests {
       errno = EIO
       return -1
     }
-
     #expect(payload == nil)
   }
 
-  // MARK: - Hook event JSON envelope.
+  // MARK: - AgentHookEvent decoding.
+
+  // `AgentHookEvent` is the in-app event type the OSC ingest synthesizes; it is
+  // also `Decodable` from this JSON shape for test construction.
 
-  @Test func parsesValidHookEventWithRequiredFieldsOnly() {
+  @Test func decodesEventWithRequiredFieldsOnly() throws {
     let surfaceID = UUID()
     let json = """
       {
@@ -293,12 +114,7 @@ struct AgentHookSocketServerTests {
         "surface_id": "\(surfaceID.uuidString)"
       }
       """
-    let message = AgentHookSocketServer.parse(data: Data(json.utf8))
-
-    guard case .event(let event) = message else {
-      Issue.record("Expected event message, got \(String(describing: message))")
-      return
-    }
+    let event = try JSONDecoder().decode(AgentHookEvent.self, from: Data(json.utf8))
     #expect(event.event == "session_start")
     #expect(event.eventName == .sessionStart)
     #expect(event.agent == "claude")
@@ -307,7 +123,7 @@ struct AgentHookSocketServerTests {
     #expect(event.data == nil)
   }
 
-  @Test func parsesHookEventWithPidTimestampAndOpaqueData() {
+  @Test func decodesEventWithPidTimestampAndOpaqueData() throws {
     let surfaceID = UUID()
     let json = """
       {
@@ -320,12 +136,7 @@ struct AgentHookSocketServerTests {
         "data": {"title": "Done", "message": "All good"}
       }
       """
-    let message = AgentHookSocketServer.parse(data: Data(json.utf8))
-
-    guard case .event(let event) = message else {
-      Issue.record("Expected event message")
-      return
-    }
+    let event = try JSONDecoder().decode(AgentHookEvent.self, from: Data(json.utf8))
     #expect(event.pid == 12345)
     #expect(event.timestamp != nil)
 
@@ -333,11 +144,10 @@ struct AgentHookSocketServerTests {
       let title: String
       let message: String
     }
-    let decoded = event.decodeData(NotificationPayload.self)
-    #expect(decoded == NotificationPayload(title: "Done", message: "All good"))
+    #expect(event.decodeData(NotificationPayload.self) == NotificationPayload(title: "Done", message: "All good"))
   }
 
-  @Test func unknownEventNameKeepsRawStringButHasNilEventName() {
+  @Test func unknownEventNameKeepsRawStringButHasNilEventName() throws {
     let surfaceID = UUID()
     let json = """
       {
@@ -347,59 +157,24 @@ struct AgentHookSocketServerTests {
         "surface_id": "\(surfaceID.uuidString)"
       }
       """
-    let message = AgentHookSocketServer.parse(data: Data(json.utf8))
-
-    guard case .event(let event) = message else {
-      Issue.record("Expected event message")
-      return
-    }
+    let event = try JSONDecoder().decode(AgentHookEvent.self, from: Data(json.utf8))
     #expect(event.event == "future_event_we_dont_know_yet")
     #expect(event.eventName == nil)
   }
 
-  @Test func hookEventMissingSurfaceIDReturnsNil() {
-    let json = """
-      {
-        "event": "session_start",
-        "agent": "claude"
-      }
-      """
-    #expect(AgentHookSocketServer.parse(data: Data(json.utf8)) == nil)
+  @Test func eventMissingSurfaceIDFailsToDecode() {
+    let json = #"{"event":"session_start","agent":"claude"}"#
+    #expect((try? JSONDecoder().decode(AgentHookEvent.self, from: Data(json.utf8))) == nil)
   }
 
-  @Test func hookEventWithMalformedSurfaceUUIDReturnsNil() {
-    let json = """
-      {
-        "event": "session_start",
-        "agent": "claude",
-        "surface_id": "not-a-uuid"
-      }
-      """
-    #expect(AgentHookSocketServer.parse(data: Data(json.utf8)) == nil)
-  }
-
-  @Test func eventDiscriminatorTakesPrecedenceOverDeeplinkInSamePayload() {
-    let surfaceID = UUID()
-    let json = """
-      {
-        "event": "session_start",
-        "agent": "claude",
-        "surface_id": "\(surfaceID.uuidString)",
-        "deeplink": "supacode://worktree/test"
-      }
-      """
-    let message = AgentHookSocketServer.parse(data: Data(json.utf8))
-
-    guard case .event = message else {
-      Issue.record("Expected event message, got \(String(describing: message))")
-      return
-    }
+  @Test func eventWithMalformedSurfaceUUIDFailsToDecode() {
+    let json = #"{"event":"session_start","agent":"claude","surface_id":"not-a-uuid"}"#
+    #expect((try? JSONDecoder().decode(AgentHookEvent.self, from: Data(json.utf8))) == nil)
   }
 
-  @Test func hookEventRejectsNonPositivePid() {
-    // `kill(0, 0)` succeeds for the caller's process group and `kill(-N, 0)`
-    // for group N, so a pid <= 0 in a session_start would pin a permanent
-    // badge in the liveness sweep. Decoder rejects them outright.
+  @Test func eventRejectsNonPositivePid() {
+    // `kill(0, 0)` succeeds for the caller's process group and `kill(-N, 0)` for
+    // group N, so a pid <= 0 would pin a permanent badge in the liveness sweep.
     for badPid in ["0", "-1", "-12345"] {
       let json = """
         {
@@ -410,9 +185,8 @@ struct AgentHookSocketServerTests {
         }
         """
       #expect(
-        AgentHookSocketServer.parse(data: Data(json.utf8)) == nil,
-        "Expected nil for pid=\(badPid)"
-      )
+        (try? JSONDecoder().decode(AgentHookEvent.self, from: Data(json.utf8))) == nil,
+        "Expected nil for pid=\(badPid)")
     }
   }
 }
diff --git a/supacodeTests/AgentPresence+TestHelpers.swift b/supacodeTests/AgentPresence+TestHelpers.swift
index 0e7e634f1..533727607 100644
--- a/supacodeTests/AgentPresence+TestHelpers.swift
+++ b/supacodeTests/AgentPresence+TestHelpers.swift
@@ -3,20 +3,29 @@ import Foundation
 
 @testable import supacode
 
-/// Test-only harness around an `AgentPresenceFeature.State`. Drains the
-/// manager's event stream and routes `agentHookEventReceived` /
+/// Test-only harness around an `AgentPresenceFeature.State`. A background task
+/// drains the manager's event stream and routes `agentHookEventReceived` /
 /// `surfacesClosed` events into the reducer so callers can drive the manager
-/// via `server.onEvent(...)` and then await `harness.drain()` to settle
-/// presence on the same loop tick.
+/// via `state.onAgentHookEvent(...)` and then await `harness.drain()` to settle
+/// presence before asserting.
 @MainActor
 final class PresenceTestHarness {
   var state = AgentPresenceFeature.State()
   private let reducer = AgentPresenceFeature()
-  private var continuation: AsyncStream<TerminalClient.Event>.Continuation?
   private var stream: AsyncStream<TerminalClient.Event>?
   private var consumeTask: Task<Void, Never>?
+  private weak var manager: WorktreeTerminalManager?
+  /// Bumped each time the consume task reduces a stream event.
+  private var processedCount = 0
+  /// Bumped each time the consume task is about to wait for the next event, i.e.
+  /// it has drained everything buffered so far.
+  private var parkCount = 0
 
   func send(_ action: AgentPresenceFeature.Action) {
+    reduce(action)
+  }
+
+  private func reduce(_ action: AgentPresenceFeature.Action) {
     _ = reducer.reduce(into: &state, action: action)
   }
 
@@ -29,33 +38,61 @@ final class PresenceTestHarness {
     send(.livenessSweepResult(snapshot: snapshot, alive: alive))
   }
 
-  /// Pumps any events buffered on the manager's stream into the reducer and
-  /// returns. Tests call this after `server.onEvent(...)` so presence state
-  /// settles before assertions.
+  /// Settles presence after `state.onAgentHookEvent(...)` / `clock.advance(...)`. Each
+  /// pass runs `megaYield` (flushing the consume task plus any clock-awoken
+  /// manager emit, e.g. an idle debounce resuming after `clock.advance`) and
+  /// returns once the consumer has parked again with no reduction in the final
+  /// pass, i.e. it observed and drained everything this call produced. The cap
+  /// keeps a genuinely quiet stream from looping forever.
   func drain() async {
-    // Yield repeatedly so the consume task drains every buffered event before
-    // returning to the test thread.
-    for _ in 0..<16 { await Task.yield() }
+    guard consumeTask != nil else { return }
+    var settled = 0
+    for _ in 0..<64 {
+      let parksBefore = parkCount
+      let processedBefore = processedCount
+      // Each megaYield spawns `count` detached tasks. A clock-awoken producer
+      // (e.g. an idle debounce resuming after `clock.advance`) needs enough
+      // yields within a single pass to resume, emit, and let the consumer
+      // reduce before we sample quiescence; too few and a busy suite schedules
+      // the resume after the sample, so we conclude "idle" before the idle
+      // event lands. 1000 keeps the per-call cost two orders below the legacy
+      // 10_000 while staying robust under contention.
+      await Task.megaYield(count: 1000)
+      // Quiescent when the consumer is parked, nothing processed this pass, and
+      // no idle-hook debounce is still scheduled. The last clause closes the
+      // race where `clock.advance` returned but the awoken idle task hasn't yet
+      // emitted: its key lingers in the manager until it does, so a pending
+      // count keeps draining instead of concluding "idle" too early.
+      let consumerIdle = parkCount == parksBefore && processedCount == processedBefore
+      let noPendingIdle = (manager?.pendingIdleHookCountForTesting ?? 0) == 0
+      settled = consumerIdle && noPendingIdle ? settled + 1 : 0
+      if settled >= 2 { return }
+    }
   }
 
   func attach(to manager: WorktreeTerminalManager) {
+    self.manager = manager
     let stream = manager.eventStream()
     self.stream = stream
     consumeTask?.cancel()
     consumeTask = Task {
-      for await event in stream {
+      var iterator = stream.makeAsyncIterator()
+      while true {
+        self.parkCount += 1
+        guard let event = await iterator.next() else { return }
         switch event {
         case .agentHookEventReceived(let payload):
-          self.send(.hookEventReceived(payload))
+          self.reduce(.hookEventReceived(payload))
         case .surfacesClosed(let ids):
           if ids.count == 1, let id = ids.first {
-            self.send(.surfaceClosed(id))
+            self.reduce(.surfaceClosed(id))
           } else {
-            self.send(.surfacesClosed(ids))
+            self.reduce(.surfacesClosed(ids))
           }
         default:
           continue
         }
+        self.processedCount += 1
       }
     }
   }
diff --git a/supacodeTests/AgentPresenceFeatureTests.swift b/supacodeTests/AgentPresenceFeatureTests.swift
index d5889dfa2..9024d9ef0 100644
--- a/supacodeTests/AgentPresenceFeatureTests.swift
+++ b/supacodeTests/AgentPresenceFeatureTests.swift
@@ -21,16 +21,60 @@ struct AgentPresenceFeatureTests {
     #expect(harness.state.agents(forSurface: surfaceID, badgesEnabled: true) == Set([.claude]))
   }
 
-  @Test func sessionStartWithoutPidIsIgnored() {
-    // Every bridge today (Claude/Codex/Kiro hooks, Pi extension) sends a
-    // pid in the envelope. A pid-less event is treated as malformed:
-    // accepting it would create a record the liveness sweep can't reap.
+  @Test func sessionStartWithoutPidSeedsPidlessRecord() {
+    // The OSC-over-SSH transport attributes by the receiving surface and has no
+    // remote pid, so a pid-less session_start is a valid signal: it seeds a
+    // record so the badge lights at launch. The record carries no pid, so the
+    // kill(2) sweep skips it; teardown is via session_end or surface close.
     var harness = Harness()
     let surfaceID = UUID()
 
     harness.send(.hookEventReceived(makeEvent(.sessionStart, agent: .claude, surfaceID: surfaceID)))
 
-    #expect(harness.state.agents(forSurface: surfaceID, badgesEnabled: true).isEmpty)
+    #expect(harness.state.agents(forSurface: surfaceID, badgesEnabled: true) == Set([.claude]))
+    let key = AgentPresenceFeature.PresenceKey(agent: .claude, surfaceID: surfaceID)
+    #expect(harness.state.records[key]?.pids.isEmpty == true)
+  }
+
+  @Test func awaitingInputWithoutPidLazilyCreatesAwaitingRecord() {
+    // A remote agent's awaiting-input OSC arrives with no pid and possibly no
+    // prior session_start; it must still light the badge.
+    var harness = Harness()
+    let surfaceID = UUID()
+
+    harness.send(.hookEventReceived(makeEvent(.awaitingInput, agent: .claude, surfaceID: surfaceID)))
+
+    let instances = harness.state.agents(across: [surfaceID], badgesEnabled: true)
+    #expect(instances.count == 1)
+    #expect(instances.first?.awaitingInput == true)
+  }
+
+  @Test func pidlessActivityIsIdempotent() {
+    var harness = Harness()
+    let surfaceID = UUID()
+
+    harness.send(.hookEventReceived(makeEvent(.awaitingInput, agent: .claude, surfaceID: surfaceID)))
+    harness.send(.hookEventReceived(makeEvent(.awaitingInput, agent: .claude, surfaceID: surfaceID)))
+
+    #expect(harness.state.records.count == 1)
+    #expect(harness.state.agents(across: [surfaceID], badgesEnabled: true).first?.awaitingInput == true)
+  }
+
+  @Test func pidlessSessionEndClearsOnlyPidlessRecord() {
+    var harness = Harness()
+    let pidlessSurface = UUID()
+    let pidSurface = UUID()
+    let pid = getpid()
+
+    harness.send(.hookEventReceived(makeEvent(.awaitingInput, agent: .claude, surfaceID: pidlessSurface)))
+    harness.send(.hookEventReceived(makeEvent(.sessionStart, agent: .claude, surfaceID: pidSurface, pid: pid)))
+
+    // Pid-less session_end clears the pid-less (OSC-origin) record...
+    harness.send(.hookEventReceived(makeEvent(.sessionEnd, agent: .claude, surfaceID: pidlessSurface)))
+    #expect(harness.state.agents(forSurface: pidlessSurface, badgesEnabled: true).isEmpty)
+    // ...but never a local pid-bearing record.
+    harness.send(.hookEventReceived(makeEvent(.sessionEnd, agent: .claude, surfaceID: pidSurface)))
+    #expect(harness.state.agents(forSurface: pidSurface, badgesEnabled: true) == Set([.claude]))
   }
 
   @Test func sessionEndRemovesAgentForSurface() {
@@ -98,7 +142,7 @@ struct AgentPresenceFeatureTests {
         "surface_id": "\(surfaceID.uuidString)"
       }
       """
-    guard case .event(let parsed) = AgentHookSocketServer.parse(data: Data(json.utf8)) else {
+    guard let parsed = try? JSONDecoder().decode(AgentHookEvent.self, from: Data(json.utf8)) else {
       Issue.record("Expected event")
       return
     }
@@ -119,6 +163,155 @@ struct AgentPresenceFeatureTests {
     #expect(harness.state.agents(forSurface: surfaceID, badgesEnabled: true).isEmpty)
   }
 
+  // MARK: - OSC (pid-less) presence.
+
+  @Test func pidlessBusyWithoutSessionStartAutoSeeds() {
+    // Over SSH the user may attach to a surface whose agent is already running,
+    // so the first OSC seen is `busy`, not `session_start`. The pid-less path
+    // must auto-seed a record so the badge lights regardless of arrival order.
+    var harness = Harness()
+    let surfaceID = UUID()
+
+    harness.send(.hookEventReceived(makeEvent(.busy, agent: .claude, surfaceID: surfaceID)))
+
+    let claude = harness.state.agents(across: [surfaceID], badgesEnabled: true).first { $0.agent == .claude }
+    #expect(claude?.activity == .busy)
+    #expect(harness.state.hasActivity(in: [surfaceID]) == true)
+  }
+
+  @Test func pidlessSessionEndRemovesPidlessRecord() {
+    var harness = Harness()
+    let surfaceID = UUID()
+
+    harness.send(.hookEventReceived(makeEvent(.sessionStart, agent: .claude, surfaceID: surfaceID)))
+    harness.send(.hookEventReceived(makeEvent(.sessionEnd, agent: .claude, surfaceID: surfaceID)))
+
+    #expect(harness.state.agents(forSurface: surfaceID, badgesEnabled: true).isEmpty)
+  }
+
+  @Test func pidlessRecordSurvivesSweepThatReapsCoLocatedDeadPid() {
+    // A pid-less (OSC) record must survive the sweep even while a co-located dead
+    // pid-bearing record is reaped: the sweep only targets records with pids.
+    var harness = Harness()
+    let surfaceID = UUID()
+    let deadPid = makeDeadPid()
+
+    harness.send(.hookEventReceived(makeEvent(.sessionStart, agent: .claude, surfaceID: surfaceID)))
+    harness.send(.hookEventReceived(makeEvent(.busy, agent: .claude, surfaceID: surfaceID)))
+    harness.send(.hookEventReceived(makeEvent(.sessionStart, agent: .codex, surfaceID: surfaceID, pid: deadPid)))
+
+    harness.livenessSweep()
+
+    #expect(harness.state.agents(forSurface: surfaceID, badgesEnabled: true) == Set([.claude]))
+    let claudeKey = AgentPresenceFeature.PresenceKey(agent: .claude, surfaceID: surfaceID)
+    #expect(harness.state.records[claudeKey]?.activity == .busy)
+  }
+
+  @Test func pidBearingActivityWithoutPresenceDoesNotSeed() {
+    // Auto-seed is pid-less-only. A pid-bearing awaiting_input / idle
+    // with no session_start must still be dropped, like busyWithoutPresenceIsDropped.
+    var harness = Harness()
+    let surfaceID = UUID()
+
+    harness.send(.hookEventReceived(makeEvent(.awaitingInput, agent: .claude, surfaceID: surfaceID, pid: getpid())))
+    harness.send(.hookEventReceived(makeEvent(.idle, agent: .codex, surfaceID: surfaceID, pid: getpid())))
+
+    #expect(harness.state.agents(forSurface: surfaceID, badgesEnabled: true).isEmpty)
+  }
+
+  @Test func pidlessSessionEndTearsDownRegardlessOfActivity() {
+    // Teardown keys on record.pids.isEmpty, not the activity flip: an OSC record
+    // that went busy then idle must still be removed by session_end.
+    var harness = Harness()
+    let surfaceID = UUID()
+
+    harness.send(.hookEventReceived(makeEvent(.sessionStart, agent: .claude, surfaceID: surfaceID)))
+    harness.send(.hookEventReceived(makeEvent(.busy, agent: .claude, surfaceID: surfaceID)))
+    harness.send(.hookEventReceived(makeEvent(.idle, agent: .claude, surfaceID: surfaceID)))
+    harness.send(.hookEventReceived(makeEvent(.sessionEnd, agent: .claude, surfaceID: surfaceID)))
+
+    #expect(harness.state.agents(forSurface: surfaceID, badgesEnabled: true).isEmpty)
+  }
+
+  @Test func pidBearingRecordSurvivesPidlessSessionEnd() {
+    // Pid-bearing wins: a pid-less (OSC over SSH) session_end must never tear
+    // down a record that still carries a tracked local pid for the same
+    // surface/agent.
+    var harness = Harness()
+    let surfaceID = UUID()
+    let pid = getpid()
+
+    harness.send(.hookEventReceived(makeEvent(.sessionStart, agent: .claude, surfaceID: surfaceID, pid: pid)))
+    harness.send(.hookEventReceived(makeEvent(.sessionEnd, agent: .claude, surfaceID: surfaceID)))
+
+    #expect(harness.state.agents(forSurface: surfaceID, badgesEnabled: true) == Set([.claude]))
+  }
+
+  @Test func pidlessSessionStartDoesNotClobberPidBearingRecord() {
+    // Pid-bearing wins on seed too: a pid-less OSC session_start arriving after
+    // the local hook has registered a pid must not reset the record.
+    var harness = Harness()
+    let surfaceID = UUID()
+    let pid = getpid()
+
+    harness.send(.hookEventReceived(makeEvent(.sessionStart, agent: .claude, surfaceID: surfaceID, pid: pid)))
+    harness.send(.hookEventReceived(makeEvent(.sessionStart, agent: .claude, surfaceID: surfaceID)))
+
+    let key = AgentPresenceFeature.PresenceKey(agent: .claude, surfaceID: surfaceID)
+    #expect(harness.state.records[key]?.pids == [pid])
+  }
+
+  @Test func pidlessSessionStartUpgradedByPidSessionStartCarriesPid() {
+    // OSC pid-less arrives first (SSH attach), then the local hook lands with a
+    // pid: the existing pid-less record must be upgraded in place so the sweep
+    // can reap it.
+    var harness = Harness()
+    let surfaceID = UUID()
+    let pid: pid_t = 1234
+
+    harness.send(.hookEventReceived(makeEvent(.sessionStart, agent: .claude, surfaceID: surfaceID)))
+    harness.send(.hookEventReceived(makeEvent(.sessionStart, agent: .claude, surfaceID: surfaceID, pid: pid)))
+
+    let key = AgentPresenceFeature.PresenceKey(agent: .claude, surfaceID: surfaceID)
+    #expect(harness.state.records[key]?.pids == [pid])
+  }
+
+  @Test func pidlessSessionEndFollowedByIdleDoesNotReseedRecord() {
+    // Both Claude's SessionEnd hook and the Pi `session_shutdown` extension emit
+    // a `session_end` + `idle` composite. After the pid-less session_end clears
+    // the record, the debounced idle must NOT auto-seed a new pid-less record:
+    // the sweep can never reap such a record (no pid to check) and no further
+    // session_end follows, so the badge would stay until surface close.
+    var harness = Harness()
+    let surfaceID = UUID()
+
+    harness.send(.hookEventReceived(makeEvent(.sessionStart, agent: .claude, surfaceID: surfaceID)))
+    harness.send(.hookEventReceived(makeEvent(.busy, agent: .claude, surfaceID: surfaceID)))
+    harness.send(.hookEventReceived(makeEvent(.sessionEnd, agent: .claude, surfaceID: surfaceID)))
+    harness.send(.hookEventReceived(makeEvent(.idle, agent: .claude, surfaceID: surfaceID)))
+
+    #expect(harness.state.agents(forSurface: surfaceID, badgesEnabled: true).isEmpty)
+    let key = AgentPresenceFeature.PresenceKey(agent: .claude, surfaceID: surfaceID)
+    #expect(harness.state.records[key] == nil)
+  }
+
+  @Test func pidUpgradedRecordIsReapedByMatchingPidSessionEnd() {
+    // Pid-less seed (SSH attach) followed by a pid-bearing session_start that
+    // upgrades the record. The matching pid-bearing session_end must remove the
+    // record entirely; otherwise the badge sticks once the pid set goes empty.
+    var harness = Harness()
+    let surfaceID = UUID()
+    let pid: pid_t = 1234
+
+    harness.send(.hookEventReceived(makeEvent(.sessionStart, agent: .claude, surfaceID: surfaceID)))
+    harness.send(.hookEventReceived(makeEvent(.sessionStart, agent: .claude, surfaceID: surfaceID, pid: pid)))
+    harness.send(.hookEventReceived(makeEvent(.sessionEnd, agent: .claude, surfaceID: surfaceID, pid: pid)))
+
+    #expect(harness.state.agents(forSurface: surfaceID, badgesEnabled: true).isEmpty)
+    let key = AgentPresenceFeature.PresenceKey(agent: .claude, surfaceID: surfaceID)
+    #expect(harness.state.records[key] == nil)
+  }
+
   // MARK: - Liveness.
 
   @Test func livenessSweepEvictsRecordsForDeadPid() {
@@ -668,7 +861,7 @@ struct AgentPresenceFeatureTests {
         "surface_id": "\(surfaceID.uuidString)"\(pidLine)
       }
       """
-    guard case .event(let event) = AgentHookSocketServer.parse(data: Data(json.utf8)) else {
+    guard let event = try? JSONDecoder().decode(AgentHookEvent.self, from: Data(json.utf8)) else {
       preconditionFailure("Failed to parse test event")
     }
     return event
diff --git a/supacodeTests/AgentPresenceOSCTests.swift b/supacodeTests/AgentPresenceOSCTests.swift
new file mode 100644
index 000000000..9e09d771d
--- /dev/null
+++ b/supacodeTests/AgentPresenceOSCTests.swift
@@ -0,0 +1,382 @@
+import Foundation
+import Testing
+
+@testable import SupacodeSettingsShared
+@testable import supacode
+
+struct AgentPresenceOSCTests {
+  // MARK: - parse.
+
+  @Test func parsesValidSignal() {
+    let signal = AgentPresenceOSC.parse(id: "claude", metadata: "event=busy")
+    #expect(signal?.agent == "claude")
+    #expect(signal?.eventRawValue == "busy")
+  }
+
+  @Test func rejectsEmptyId() {
+    #expect(AgentPresenceOSC.parse(id: "", metadata: "event=busy") == nil)
+  }
+
+  @Test func rejectsMissingEvent() {
+    #expect(AgentPresenceOSC.parse(id: "claude", metadata: "pid=5") == nil)
+  }
+
+  @Test func rejectsUnknownEvent() {
+    #expect(AgentPresenceOSC.parse(id: "claude", metadata: "event=not_a_real_event") == nil)
+  }
+
+  @Test func ignoresUnknownFieldsAndOrdering() {
+    // A leftover `token=` from an older emitter is just an unknown field now: ignored.
+    let signal = AgentPresenceOSC.parse(id: "codex", metadata: "extra=1;token=zzz;event=session_start")
+    #expect(signal?.eventRawValue == "session_start")
+    #expect(signal?.agent == "codex")
+  }
+
+  @Test func skipsBareSegmentWithoutEquals() {
+    // A segment with no '=' (a stray sentinel byte) is skipped, not fatal.
+    let signal = AgentPresenceOSC.parse(id: "claude", metadata: "garbage;event=idle")
+    #expect(signal?.eventRawValue == "idle")
+  }
+
+  // MARK: - emit / parse round-trip.
+
+  @Test func emitMetadataRoundTripsThroughParse() {
+    for event in [HookEvent.sessionStart, .sessionEnd, .busy, .awaitingInput, .idle] {
+      let metadata = AgentPresenceOSC.metadata(event: event)
+      let signal = AgentPresenceOSC.parse(id: "claude", metadata: metadata)
+      #expect(signal?.eventRawValue == event.rawValue)
+    }
+  }
+
+  // MARK: - pid field (local-host liveness).
+
+  @Test func parsesPositivePidField() {
+    let signal = AgentPresenceOSC.parse(id: "claude", metadata: "event=busy;pid=4321")
+    #expect(signal?.pid == 4321)
+  }
+
+  @Test func absentPidParsesAsNil() {
+    let signal = AgentPresenceOSC.parse(id: "claude", metadata: "event=busy")
+    #expect(signal?.eventRawValue == "busy")
+    #expect(signal?.pid == nil)
+  }
+
+  @Test func rejectsNonPositiveAndGarbagePid() {
+    // 0 / negatives would let `kill(_:0)` match the caller's process group and
+    // pin a permanent badge; a non-numeric pid is dropped, not fatal.
+    for raw in ["0", "-7", "abc", ""] {
+      let signal = AgentPresenceOSC.parse(id: "claude", metadata: "event=busy;pid=\(raw)")
+      #expect(signal?.eventRawValue == "busy")
+      #expect(signal?.pid == nil)
+    }
+  }
+
+  @Test func rejectsPidThatOverflowsPidT() {
+    // Defense in depth against a future change from `pid_t(raw)` to `Int(raw)`:
+    // a value beyond pid_t's range must drop, not wrap.
+    let signal = AgentPresenceOSC.parse(id: "claude", metadata: "event=busy;pid=99999999999999")
+    #expect(signal?.pid == nil)
+  }
+
+  @Test func metadataPidSuffixRoundTripsThroughParse() {
+    let metadata = AgentPresenceOSC.metadata(event: .busy, pidSuffix: ";pid=99")
+    let signal = AgentPresenceOSC.parse(id: "claude", metadata: metadata)
+    #expect(signal?.pid == 99)
+  }
+
+  @Test func presenceEventThreadsLocalPid() {
+    let metadata = AgentPresenceOSC.metadata(event: .busy, pidSuffix: ";pid=4242")
+    let result = WorktreeTerminalState.presenceEvent(
+      id: "claude", metadata: metadata, surfaceID: UUID(), surfaceExists: true)
+    #expect((try? result.get())?.pid == 4242)
+  }
+
+  @Test func actionMapsSessionEndToEndElseStart() {
+    #expect(AgentPresenceOSC.action(for: .sessionEnd) == "end")
+    for event in [HookEvent.sessionStart, .busy, .awaitingInput, .idle] {
+      #expect(AgentPresenceOSC.action(for: event) == "start")
+    }
+  }
+
+  // MARK: - presenceEvent (attribution to receiving surface).
+
+  @Test func presenceEventAttributesToReceivingSurface() {
+    let surfaceID = UUID()
+    let metadata = AgentPresenceOSC.metadata(event: .busy)
+    let result = WorktreeTerminalState.presenceEvent(
+      id: "claude", metadata: metadata, surfaceID: surfaceID, surfaceExists: true)
+    let event = try? result.get()
+    #expect(event?.surfaceID == surfaceID)
+    #expect(event?.agent == "claude")
+    #expect(event?.event == "busy")
+    #expect(event?.pid == nil)
+  }
+
+  @Test func presenceEventDropsUnknownSurface() {
+    let metadata = AgentPresenceOSC.metadata(event: .busy)
+    let result = WorktreeTerminalState.presenceEvent(
+      id: "claude", metadata: metadata, surfaceID: UUID(), surfaceExists: false)
+    #expect(result == .failure(.unknownSurface))
+  }
+
+  @Test func presenceEventDropsMalformedMetadata() {
+    let result = WorktreeTerminalState.presenceEvent(
+      id: "claude", metadata: "event=nope", surfaceID: UUID(), surfaceExists: true)
+    #expect(result == .failure(.parseFailed))
+  }
+
+  // MARK: - AgentHookEvent synthesis.
+
+  @Test func synthesizedHookEventDefaultsToPidlessAndKeepsSurface() {
+    let surfaceID = UUID()
+    let event = AgentHookEvent(agent: "claude", event: "busy", surfaceID: surfaceID)
+    #expect(event.pid == nil)
+    #expect(event.surfaceID == surfaceID)
+    #expect(event.agent == "claude")
+    #expect(event.event == "busy")
+    #expect(event.version == 1)
+  }
+
+  // MARK: - parseNotify.
+
+  /// base64 of the JSON-escaped content of `text`, matching the wire the emitter
+  /// ships (`awk`-extracted escaped value / Pi's `JSON.stringify(...).slice(1,-1)`).
+  private static func field(_ text: String) -> String {
+    guard let json = try? JSONEncoder().encode(text) else { return "" }
+    // `json` is `"..."`; drop the surrounding quote bytes, keep the escaped content.
+    return Data(json.dropFirst().dropLast()).base64EncodedString()
+  }
+
+  private static func notifyMeta(title: String? = nil, body: String? = nil) -> String {
+    AgentPresenceOSC.notifyMetadata(title: title.map(field) ?? "", body: body.map(field) ?? "")
+  }
+
+  @Test func parsesValidNotify() {
+    let signal = AgentPresenceOSC.parseNotify(id: "claude", metadata: Self.notifyMeta(body: "hi"))
+    #expect(signal?.agent == "claude")
+    #expect(signal?.title == nil)
+    #expect(signal?.body == "hi")
+  }
+
+  @Test func parsesNotifyWithTitleAndBody() {
+    let signal = AgentPresenceOSC.parseNotify(
+      id: "claude", metadata: Self.notifyMeta(title: "Done", body: "all good"))
+    #expect(signal?.title == "Done")
+    #expect(signal?.body == "all good")
+  }
+
+  @Test func decodesEscapedQuotesNewlinesAndUnicode() {
+    let signal = AgentPresenceOSC.parseNotify(
+      id: "claude", metadata: Self.notifyMeta(body: "line \"one\"\nDONE ✓"))
+    #expect(signal?.body == "line \"one\"\nDONE ✓")
+  }
+
+  @Test func rejectsNotifyWithoutKind() {
+    #expect(AgentPresenceOSC.parseNotify(id: "claude", metadata: "body=\(Self.field("x"))") == nil)
+  }
+
+  @Test func notifyWithoutBodyParsesAsTitleOnly() {
+    // Body is optional: a missing body yields a title-only signal (macOS shows a
+    // body-less toast), not a dropped notify.
+    let signal = AgentPresenceOSC.parseNotify(id: "claude", metadata: Self.notifyMeta(title: "Heads up"))
+    #expect(signal?.title == "Heads up")
+    #expect(signal?.body == nil)
+  }
+
+  @Test func rejectsNotifyWithEmptyId() {
+    #expect(AgentPresenceOSC.parseNotify(id: "", metadata: Self.notifyMeta(body: "x")) == nil)
+  }
+
+  @Test func invalidBase64FieldDecodesToNil() {
+    let signal = AgentPresenceOSC.parseNotify(id: "claude", metadata: "kind=notify;body=!!notb64")
+    #expect(signal?.body == nil)
+  }
+
+  @Test func decodeToleratesTrailingPartialEscapeFromEmitCut() {
+    // A body byte-capped mid-`\"` leaves a dangling backslash; decoding must shed
+    // it and preview the rest rather than dropping the notify (the >2048 truncate
+    // path relies on this).
+    let escaped = #"say \"#  // ends with a lone backslash (a cut `\"`)
+    let signal = AgentPresenceOSC.parseNotify(
+      id: "claude", metadata: "kind=notify;body=\(Data(escaped.utf8).base64EncodedString())")
+    #expect(signal?.body == "say ")
+  }
+
+  @Test func decodeShedsCutSurrogatePairEscapeToPreview() {
+    // A body cut mid surrogate-pair escape (`\uD83D\uDE0` is 11 dangling bytes)
+    // must shed back to the recoverable prefix, not drop the whole body to empty.
+    let escaped = #"done \uD83D\uDE0"#
+    let signal = AgentPresenceOSC.parseNotify(
+      id: "claude", metadata: "kind=notify;body=\(Data(escaped.utf8).base64EncodedString())")
+    // The recoverable prefix survives (not dropped to empty); exact trailing
+    // depends on Foundation's lone-surrogate handling, so assert the prefix.
+    #expect(signal?.body?.hasPrefix("done") == true)
+  }
+
+  @Test func base64TruncatedBodyDecodesToNilTitleOnly() {
+    // A mid-base64 cut (length not a multiple of 4, the ghostty .allocating path)
+    // is not decodable: the body drops and the toast falls back to the title.
+    let valid = Data("hello world body".utf8).base64EncodedString()
+    let cut = String(valid.dropLast())  // break base64 alignment
+    let signal = AgentPresenceOSC.parseNotify(
+      id: "claude", metadata: "kind=notify;title=\(Self.field("Done"));body=\(cut)")
+    #expect(signal?.title == "Done")
+    #expect(signal?.body == nil)
+  }
+
+  @Test func notifyMetadataRoundTripsThroughParseNotify() {
+    let metadata = Self.notifyMeta(title: "T", body: "round trip")
+    let signal = AgentPresenceOSC.parseNotify(id: "codex", metadata: metadata)
+    #expect(signal?.title == "T")
+    #expect(signal?.body == "round trip")
+  }
+
+  @Test func presenceParseRejectsNotifyMetadata() {
+    // Presence and notify are disjoint: a notify payload must not parse as presence.
+    #expect(AgentPresenceOSC.parse(id: "claude", metadata: Self.notifyMeta(body: "x")) == nil)
+  }
+
+  // MARK: - notification (parse + sanitize).
+
+  @Test func notificationExtractsBody() {
+    let resolved = WorktreeTerminalState.notification(
+      id: "claude", metadata: Self.notifyMeta(body: "all done"), surfaceExists: true)
+    guard case .success(let value) = resolved else {
+      Issue.record("expected success, got \(resolved)")
+      return
+    }
+    #expect(value.body == "all done")
+  }
+
+  @Test func notificationDropsUnknownSurface() {
+    let result = WorktreeTerminalState.notification(
+      id: "claude", metadata: Self.notifyMeta(body: "x"), surfaceExists: false)
+    if case .failure(.unknownSurface) = result {} else { Issue.record("expected unknownSurface, got \(result)") }
+  }
+
+  @Test func notificationDropsClosedSurfaceWithoutWarning() {
+    // A signal targeting a closed surface is benign, not malformed: the call site
+    // routes `.unknownSurface` to `.debug`, never `.warning`. Asserting the exact
+    // failure case locks that mapping in since `parseFailed` is the only
+    // warn-level branch.
+    let result = WorktreeTerminalState.notification(
+      id: "claude", metadata: Self.notifyMeta(body: "x"), surfaceExists: false)
+    guard case .failure(let drop) = result else {
+      Issue.record("expected failure, got \(result)")
+      return
+    }
+    if case .unknownSurface = drop {
+    } else {
+      Issue.record("expected unknownSurface, got \(drop)")
+    }
+    if case .parseFailed = drop { Issue.record("unknown surface must not log as a malformed warning") }
+  }
+
+  @Test func notificationFallsBackToAgentTitleWhenAbsent() {
+    let resolved = WorktreeTerminalState.notification(
+      id: "codex", metadata: Self.notifyMeta(body: "body only"), surfaceExists: true)
+    guard case .success(let value) = resolved else {
+      Issue.record("expected success, got \(resolved)")
+      return
+    }
+    #expect(value.title == "codex")
+  }
+
+  @Test func notificationShowsTitleOnlyToastWhenBodyAbsent() {
+    // A turn-complete notify with no body still fires, showing just the title.
+    let resolved = WorktreeTerminalState.notification(
+      id: "claude", metadata: Self.notifyMeta(), surfaceExists: true)
+    guard case .success(let value) = resolved else {
+      Issue.record("expected success, got \(resolved)")
+      return
+    }
+    #expect(value.title == "claude")
+    #expect(value.body.isEmpty)
+  }
+
+  @Test func notificationDropsPayloadThatSanitizesEmpty() {
+    // Body of only control / whitespace and no usable title sanitizes to empty,
+    // so the toast is suppressed rather than shown blank.
+    let result = WorktreeTerminalState.notification(
+      id: " ", metadata: Self.notifyMeta(body: "\n"), surfaceExists: true)
+    if case .failure(.empty) = result {} else { Issue.record("expected empty, got \(result)") }
+  }
+
+  @Test func sanitizeStripsControlCharsAndCollapsesNewlines() {
+    let dirty = "a\u{1B}[31mred\u{07}\nline"
+    #expect(WorktreeTerminalState.sanitizeNotificationText(dirty, max: 1000) == "a[31mred line")
+  }
+
+  @Test func sanitizeCapsToMaxScalars() {
+    let long = String(repeating: "x", count: 500)
+    #expect(WorktreeTerminalState.sanitizeNotificationText(long, max: 100).count == 100)
+  }
+
+  @Test func notificationStripsEmbeddedOSCSequenceFromBody() {
+    // A notify body that smuggles a nested OSC 3008 presence sequence must not
+    // forward the ESC or the framing bytes to the toast: the C0 strip is the
+    // only line of defense between an attacker-controlled message and the
+    // terminal's own escape parser. The ESC bytes ride in via JSON's six-char
+    // unicode escape (raw 0x1B is illegal in a JSON string); the C0 strip
+    // must drop both the opening ESC and the trailing ST ESC before the
+    // toast sees them.
+    let body = "before\u{1B}]3008;start=evil;event=busy\u{1B}\\after"
+    let resolved = WorktreeTerminalState.notification(
+      id: "claude", metadata: Self.notifyMeta(body: body), surfaceExists: true)
+    guard case .success(let value) = resolved else {
+      Issue.record("expected success, got \(resolved)")
+      return
+    }
+    // No ESC byte may reach the toast, no matter where it sat in the payload.
+    #expect(!value.body.unicodeScalars.contains { $0.value == 0x1B })
+    // Printable framing bytes survive (they are not C0); the load-bearing
+    // assertion is that the ESC is gone, so a downstream renderer cannot
+    // re-trigger an escape parser.
+    #expect(value.body == #"before]3008;start=evil;event=busy\after"#)
+    // The standalone sanitize entry point pins the same contract directly.
+    let dirty = "before\u{1B}]3008;start=evil;event=busy\u{1B}\\after"
+    #expect(
+      WorktreeTerminalState.sanitizeNotificationText(dirty, max: 1000)
+        == #"before]3008;start=evil;event=busy\after"#)
+  }
+
+  // MARK: - large payload (metadata cap headroom).
+
+  @Test func largeNotifyPayloadNearMetadataCapRoundTripsEndToEnd() {
+    // A near-cap body must survive parseNotify + notification(...) end to end and
+    // stay under the 2048-byte OSC cap so a real terminal does not truncate.
+    let bodyText = String(repeating: "y", count: 1400)
+    let metadata = Self.notifyMeta(title: "Big", body: bodyText)
+    #expect(metadata.utf8.count < 2048)
+
+    let signal = AgentPresenceOSC.parseNotify(id: "codex", metadata: metadata)
+    #expect(signal?.body == bodyText)
+
+    let resolved = WorktreeTerminalState.notification(
+      id: "codex", metadata: metadata, surfaceExists: true)
+    guard case .success(let value) = resolved else {
+      Issue.record("expected success, got \(resolved)")
+      return
+    }
+    #expect(value.title == "Big")
+    // Body is sanitized + capped at 1000 scalars (see WorktreeTerminalState.notification).
+    #expect(value.body.count == 1000)
+    #expect(value.body.allSatisfy { $0 == "y" })
+  }
+
+  // MARK: - emitNotifyShell stdin capture.
+
+  @Test func emitNotifyShellCapturesStdinByDefault() {
+    let shell = AgentPresenceOSC.emitNotifyShell(agent: .copilot)
+    #expect(shell.hasPrefix("__in=$(cat); "))
+    #expect(shell.contains("start=copilot"))
+  }
+
+  @Test func emitNotifyShellSkipsStdinCaptureWhenCallerOwnsIt() {
+    // The notification hook reads `$__in` once itself, so the notify leg must
+    // not re-run `$(cat)` (stdin is already drained).
+    let shell = AgentPresenceOSC.emitNotifyShell(agent: .copilot, readsStdin: false)
+    #expect(!shell.contains("$(cat)"))
+    #expect(shell.contains("start=copilot"))
+  }
+}
diff --git a/supacodeTests/AppFeatureArchivedSelectionTests.swift b/supacodeTests/AppFeatureArchivedSelectionTests.swift
index 4d04f4698..05b40badc 100644
--- a/supacodeTests/AppFeatureArchivedSelectionTests.swift
+++ b/supacodeTests/AppFeatureArchivedSelectionTests.swift
@@ -22,7 +22,7 @@ struct AppFeatureArchivedSelectionTests {
       repositoryRootURL: rootURL
     )
     let repository = Repository(
-      id: rootURL.path(percentEncoded: false),
+      id: RepositoryID(rootURL.path(percentEncoded: false)),
       rootURL: rootURL,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [worktree])
@@ -70,7 +70,7 @@ struct AppFeatureArchivedSelectionTests {
       repositoryRootURL: rootURL
     )
     let repository = Repository(
-      id: rootURL.path(percentEncoded: false),
+      id: RepositoryID(rootURL.path(percentEncoded: false)),
       rootURL: rootURL,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [activeWorktree, archivedWorktree])
@@ -119,7 +119,36 @@ struct AppFeatureArchivedSelectionTests {
 
     #expect(
       sentCommands.value == [
-        .prune([activeWorktree.id])
+        .prune(keeping: [activeWorktree.id], protectingRepositoryIDs: [])
+      ]
+    )
+  }
+
+  @Test(.dependencies) func repositoriesChangedProtectsFailedRepositoriesDuringTerminalPrune() async {
+    var repositoriesState = RepositoriesFeature.State()
+    let failedRepositoryID = RepositoryID("/tmp/repo")
+    repositoriesState.loadFailuresByID = [failedRepositoryID: "boom"]
+    let appState = AppFeature.State(
+      repositories: repositoriesState,
+      settings: SettingsFeature.State()
+    )
+    let sentCommands = LockIsolated<[TerminalClient.Command]>([])
+    let store = TestStore(initialState: appState) {
+      AppFeature()
+    } withDependencies: {
+      $0.terminalClient.send = { command in
+        sentCommands.withValue { $0.append(command) }
+      }
+      $0.worktreeInfoWatcher.send = { _ in }
+    }
+    store.exhaustivity = .off
+
+    await store.send(.repositories(.delegate(.repositoriesChanged([]))))
+    await store.finish()
+
+    #expect(
+      sentCommands.value == [
+        .prune(keeping: [], protectingRepositoryIDs: [failedRepositoryID])
       ]
     )
   }
@@ -134,7 +163,7 @@ struct AppFeatureArchivedSelectionTests {
       repositoryRootURL: rootURL
     )
     let repository = Repository(
-      id: rootURL.path(percentEncoded: false),
+      id: RepositoryID(rootURL.path(percentEncoded: false)),
       rootURL: rootURL,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [worktree])
diff --git a/supacodeTests/AppFeatureCommandPaletteTests.swift b/supacodeTests/AppFeatureCommandPaletteTests.swift
index 25f589b21..a47f3fee3 100644
--- a/supacodeTests/AppFeatureCommandPaletteTests.swift
+++ b/supacodeTests/AppFeatureCommandPaletteTests.swift
@@ -484,6 +484,7 @@ struct AppFeatureCommandPaletteTests {
         worktreeID: worktree.id,
         repositoryID: repository.id,
         repositoryRootURL: repository.rootURL,
+        host: nil,
         currentName: "feature/old"
       )
     }
@@ -493,7 +494,7 @@ struct AppFeatureCommandPaletteTests {
 
 private func makeWorktree(id: String, name: String, repoRoot: String = "/tmp/repo") -> Worktree {
   Worktree(
-    id: id,
+    id: WorktreeID(id),
     name: name,
     detail: "detail",
     workingDirectory: URL(fileURLWithPath: id),
@@ -503,7 +504,7 @@ private func makeWorktree(id: String, name: String, repoRoot: String = "/tmp/rep
 
 private func makeRepository(id: String, worktrees: [Worktree]) -> Repository {
   Repository(
-    id: id,
+    id: RepositoryID(id),
     rootURL: URL(fileURLWithPath: id),
     name: "repo",
     worktrees: IdentifiedArray(uniqueElements: worktrees)
diff --git a/supacodeTests/AppFeatureDeeplinkTests.swift b/supacodeTests/AppFeatureDeeplinkTests.swift
index 5d119df4f..30e43890b 100644
--- a/supacodeTests/AppFeatureDeeplinkTests.swift
+++ b/supacodeTests/AppFeatureDeeplinkTests.swift
@@ -209,13 +209,14 @@ struct AppFeatureDeeplinkTests {
     let folderURL = URL(fileURLWithPath: folderRoot)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: Repository.name(for: folderURL),
       detail: "",
       workingDirectory: folderURL,
       repositoryRootURL: folderURL
     )
     let folderRepo = Repository(
-      id: folderRoot,
+      id: RepositoryID(folderRoot),
       rootURL: folderURL,
       name: Repository.name(for: folderURL),
       worktrees: [folderWorktree],
@@ -995,13 +996,14 @@ struct AppFeatureDeeplinkTests {
     let folderURL = URL(fileURLWithPath: folderRoot)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: Repository.name(for: folderURL),
       detail: "",
       workingDirectory: folderURL,
       repositoryRootURL: folderURL
     )
     let folderRepo = Repository(
-      id: folderRoot,
+      id: RepositoryID(folderRoot),
       rootURL: folderURL,
       name: Repository.name(for: folderURL),
       worktrees: [folderWorktree],
@@ -1021,7 +1023,7 @@ struct AppFeatureDeeplinkTests {
     }
     store.exhaustivity = .off
 
-    await store.send(.deeplink(.settingsRepoScripts(repositoryID: folderRoot)))
+    await store.send(.deeplink(.settingsRepoScripts(repositoryID: RepositoryID(folderRoot))))
     await store.receive(\.settings.setSelection)
   }
 
@@ -1397,7 +1399,7 @@ struct AppFeatureDeeplinkTests {
     }
     store.exhaustivity = .off
 
-    let encoded = worktree.id.addingPercentEncoding(withAllowedCharacters: .alphanumerics)!
+    let encoded = worktree.id.rawValue.addingPercentEncoding(withAllowedCharacters: .alphanumerics)!
     let url = URL(string: "supacode://worktree/\(encoded)")!
     await store.send(.deeplinkReceived(url))
     await store.receive(\.deeplink)
@@ -1982,7 +1984,7 @@ struct AppFeatureDeeplinkTests {
     name: String = "wt-1"
   ) -> Worktree {
     Worktree(
-      id: id,
+      id: WorktreeID(id),
       name: name,
       detail: "detail",
       workingDirectory: URL(fileURLWithPath: id),
diff --git a/supacodeTests/AppFeatureDefaultEditorTests.swift b/supacodeTests/AppFeatureDefaultEditorTests.swift
index 04db027a9..99afebc84 100644
--- a/supacodeTests/AppFeatureDefaultEditorTests.swift
+++ b/supacodeTests/AppFeatureDefaultEditorTests.swift
@@ -147,11 +147,44 @@ struct AppFeatureDefaultEditorTests {
     #expect(watcherCommands.value == [.setSelectedWorktreeID(worktree.id)])
   }
 
+  @Test(.dependencies) func openAndRevealAreNoOpsForRemoteWorktree() async {
+    let config = TestRemoteRepo(
+      host: RemoteHost(alias: "devbox"),
+      remotePath: "/home/me/proj",
+      displayName: "proj"
+    )
+    let worktree = RepositoriesFeature.remoteMainWorktree(config: config)
+    let repository = Repository(
+      id: RepositoriesFeature.remoteRepositoryID(for: config),
+      rootURL: URL(fileURLWithPath: config.normalizedRemotePath),
+      name: config.resolvedDisplayName,
+      worktrees: IdentifiedArray(uniqueElements: [worktree]),
+      isGitRepository: true,
+      host: config.host
+    )
+    var repositoriesState = RepositoriesFeature.State()
+    repositoriesState.repositories = [repository]
+    repositoriesState.selection = .worktree(worktree.id)
+
+    let store = TestStore(
+      initialState: AppFeature.State(repositories: repositoriesState, settings: SettingsFeature.State())
+    ) {
+      AppFeature()
+    }
+
+    // A remote path can't be reached by Finder / an editor, so both routes
+    // return before spawning any workspace effect: exhaustive sends with no
+    // trailing closure and a clean `finish()` prove the no-op.
+    await store.send(.openWorktree(.finder))
+    await store.send(.revealInFinder)
+    await store.finish()
+  }
+
   private func makeWorktree() -> Worktree {
     let repositoryRootURL = URL(fileURLWithPath: "/tmp/repo-\(UUID().uuidString)")
     let worktreeURL = repositoryRootURL.appending(path: "wt-1")
     return Worktree(
-      id: worktreeURL.path(percentEncoded: false),
+      id: WorktreeID(worktreeURL.path(percentEncoded: false)),
       name: "wt-1",
       detail: "detail",
       workingDirectory: worktreeURL,
@@ -161,7 +194,7 @@ struct AppFeatureDefaultEditorTests {
 
   private func makeRepositoriesState(worktree: Worktree) -> RepositoriesFeature.State {
     let repository = Repository(
-      id: worktree.repositoryRootURL.path(percentEncoded: false),
+      id: RepositoryID(worktree.repositoryRootURL.path(percentEncoded: false)),
       rootURL: worktree.repositoryRootURL,
       name: "repo",
       worktrees: [worktree]
diff --git a/supacodeTests/AppFeatureJumpToLatestUnreadTests.swift b/supacodeTests/AppFeatureJumpToLatestUnreadTests.swift
index ff78ae597..bbee0c10d 100644
--- a/supacodeTests/AppFeatureJumpToLatestUnreadTests.swift
+++ b/supacodeTests/AppFeatureJumpToLatestUnreadTests.swift
@@ -81,7 +81,7 @@ struct AppFeatureJumpToLatestUnreadTests {
     let store = makeStore(worktree: worktree) {
       $0.terminalClient.latestUnreadNotification = {
         NotificationLocation(
-          worktreeID: missingID,
+          worktreeID: WorktreeID(missingID),
           tabID: TerminalTabID(rawValue: UUID()),
           surfaceID: UUID(),
           notificationID: UUID(),
@@ -105,7 +105,7 @@ struct AppFeatureJumpToLatestUnreadTests {
     name: String = "wt-1"
   ) -> Worktree {
     Worktree(
-      id: id,
+      id: WorktreeID(id),
       name: name,
       detail: "detail",
       workingDirectory: URL(fileURLWithPath: id),
diff --git a/supacodeTests/AppFeatureOpenWorktreeTests.swift b/supacodeTests/AppFeatureOpenWorktreeTests.swift
index 4a4cd6c78..81d71493c 100644
--- a/supacodeTests/AppFeatureOpenWorktreeTests.swift
+++ b/supacodeTests/AppFeatureOpenWorktreeTests.swift
@@ -171,7 +171,7 @@ struct AppFeatureOpenWorktreeTests {
     let repositoryRootURL = URL(fileURLWithPath: "/tmp/repo-\(UUID().uuidString)")
     let worktreeURL = repositoryRootURL.appending(path: "wt-1")
     return Worktree(
-      id: worktreeURL.path(percentEncoded: false),
+      id: WorktreeID(worktreeURL.path(percentEncoded: false)),
       name: "wt-1",
       detail: "detail",
       workingDirectory: worktreeURL,
@@ -181,7 +181,7 @@ struct AppFeatureOpenWorktreeTests {
 
   private func makeRepositoriesState(worktree: Worktree) -> RepositoriesFeature.State {
     let repository = Repository(
-      id: worktree.repositoryRootURL.path(percentEncoded: false),
+      id: RepositoryID(worktree.repositoryRootURL.path(percentEncoded: false)),
       rootURL: worktree.repositoryRootURL,
       name: "repo",
       worktrees: [worktree]
diff --git a/supacodeTests/AppFeatureSettingsChangedTests.swift b/supacodeTests/AppFeatureSettingsChangedTests.swift
index d5e07866b..42b5d5020 100644
--- a/supacodeTests/AppFeatureSettingsChangedTests.swift
+++ b/supacodeTests/AppFeatureSettingsChangedTests.swift
@@ -46,7 +46,7 @@ struct AppFeatureSettingsChangedTests {
       repositoryRootURL: rootURL
     )
     let repository = Repository(
-      id: rootURL.path(percentEncoded: false),
+      id: RepositoryID(rootURL.path(percentEncoded: false)),
       rootURL: rootURL,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [worktree])
diff --git a/supacodeTests/AppFeatureSettingsSelectionTests.swift b/supacodeTests/AppFeatureSettingsSelectionTests.swift
index 37983ec14..814d1a004 100644
--- a/supacodeTests/AppFeatureSettingsSelectionTests.swift
+++ b/supacodeTests/AppFeatureSettingsSelectionTests.swift
@@ -27,7 +27,49 @@ struct AppFeatureSettingsSelectionTests {
     await store.send(.repositories(.delegate(.repositoriesChanged([repository]))))
     await store.receive(\.settings.repositoriesChanged) {
       $0.settings.repositorySummaries = [
-        SettingsRepositorySummary(id: repository.id, name: repository.name)
+        SettingsRepositorySummary(id: repository.id.rawValue, name: repository.name)
+      ]
+    }
+    await store.receive(\.commandPalette.pruneRecency)
+  }
+
+  /// A remote repo's id is a `remote:` key, not a path, so the summary must
+  /// carry the real remote root URL, otherwise the settings pane keys per-repo
+  /// settings off a bogus URL and the worktree never sees its scripts.
+  @Test func repositoriesChangedForwardsRemoteSummaryWithRealRootURL() async {
+    let config = TestRemoteRepo(
+      host: RemoteHost(alias: "devbox"),
+      remotePath: "/home/me/proj",
+      displayName: "proj"
+    )
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: config)
+    let remote = Repository(
+      id: repoID,
+      rootURL: URL(fileURLWithPath: "/home/me/proj"),
+      name: "proj",
+      worktrees: [],
+      isGitRepository: true,
+      host: config.host
+    )
+    let store = TestStore(
+      initialState: AppFeature.State(
+        repositories: RepositoriesFeature.State(reconciledRepositories: [remote]),
+        settings: SettingsFeature.State()
+      )
+    ) {
+      AppFeature()
+    }
+
+    await store.send(.repositories(.delegate(.repositoriesChanged([remote]))))
+    await store.receive(\.settings.repositoriesChanged) {
+      $0.settings.repositorySummaries = [
+        SettingsRepositorySummary(
+          id: repoID.rawValue,
+          name: "proj",
+          isGitRepository: true,
+          host: config.host,
+          rootURL: URL(fileURLWithPath: "/home/me/proj")
+        )
       ]
     }
     await store.receive(\.commandPalette.pruneRecency)
diff --git a/supacodeTests/AppShortcutsTests.swift b/supacodeTests/AppShortcutsTests.swift
index 9b29b57de..e67adcabe 100644
--- a/supacodeTests/AppShortcutsTests.swift
+++ b/supacodeTests/AppShortcutsTests.swift
@@ -31,7 +31,7 @@ struct AppShortcutsTests {
   @Test func worktreeSelectionUsesControlNumberShortcuts() {
     expectNoDifference(
       AppShortcuts.worktreeSelection.map(\.display),
-      ["⌃1", "⌃2", "⌃3", "⌃4", "⌃5", "⌃6", "⌃7", "⌃8", "⌃9", "⌃0"]
+      ["⌃1", "⌃2", "⌃3", "⌃4", "⌃5", "⌃6", "⌃7", "⌃8", "⌃9"]
     )
 
     for shortcut in AppShortcuts.worktreeSelection {
@@ -41,7 +41,7 @@ struct AppShortcutsTests {
 
   @Test func tabSelectionGhosttyKeybindArgumentsMatchExpected() {
     expectNoDifference(
-      AppShortcuts.tabSelectionGhosttyKeybindArguments,
+      AppShortcuts.tabSelectionGhosttyKeybindArguments(from: [:]),
       [
         "--keybind=ctrl+1=goto_tab:1",
         "--keybind=ctrl+digit_1=goto_tab:1",
@@ -61,8 +61,6 @@ struct AppShortcutsTests {
         "--keybind=ctrl+digit_8=goto_tab:8",
         "--keybind=ctrl+9=goto_tab:9",
         "--keybind=ctrl+digit_9=goto_tab:9",
-        "--keybind=ctrl+0=goto_tab:10",
-        "--keybind=ctrl+digit_0=goto_tab:10",
       ]
     )
   }
@@ -74,7 +72,7 @@ struct AppShortcutsTests {
       #expect(arguments.contains(shortcut.ghosttyUnbindArgument))
     }
 
-    for argument in AppShortcuts.tabSelectionGhosttyKeybindArguments {
+    for argument in AppShortcuts.tabSelectionGhosttyKeybindArguments(from: [:]) {
       #expect(arguments.contains(argument))
     }
 
@@ -83,6 +81,44 @@ struct AppShortcutsTests {
     }
   }
 
+  // MARK: - Tab selection honors overrides.
+
+  @Test func tabSelectionOmitsDisabledWorktreeSelection() {
+    let arguments = AppShortcuts.tabSelectionGhosttyKeybindArguments(
+      from: [.selectWorktree(6): .disabled]
+    )
+    // The disabled slot contributes no goto_tab binding, so ⌃6 reaches the terminal.
+    #expect(arguments.contains("--keybind=ctrl+6=goto_tab:6") == false)
+    #expect(arguments.contains("--keybind=ctrl+digit_6=goto_tab:6") == false)
+    // Other slots are unaffected.
+    #expect(arguments.contains("--keybind=ctrl+5=goto_tab:5"))
+  }
+
+  @Test func tabSelectionFollowsRemappedWorktreeSelection() {
+    let override = AppShortcutOverride(keyCode: UInt16(kVK_ANSI_J), modifiers: [.command])
+    let arguments = AppShortcuts.tabSelectionGhosttyKeybindArguments(
+      from: [.selectWorktree(1): override]
+    )
+    // The goto_tab binding moves to the remapped chord; the default ⌃1 is released.
+    #expect(arguments.contains("--keybind=super+j=goto_tab:1"))
+    #expect(arguments.contains("--keybind=ctrl+1=goto_tab:1") == false)
+    #expect(arguments.contains("--keybind=ctrl+digit_1=goto_tab:1") == false)
+  }
+
+  @Test func ghosttyCLIArgumentsReleaseDisabledWorktreeChordToTerminal() {
+    let arguments = AppShortcuts.ghosttyCLIKeybindArguments(from: [.selectWorktree(6): .disabled])
+    // Neither a goto_tab binding nor an unbind remains, so ⌃6 is delivered to the terminal.
+    #expect(arguments.contains { $0.hasPrefix("--keybind=ctrl+6=") } == false)
+    #expect(arguments.contains(AppShortcuts.selectWorktree6.ghosttyUnbindArgument) == false)
+  }
+
+  @Test func ghosttyCLIArgumentsMoveRemappedWorktreeChord() {
+    let override = AppShortcutOverride(keyCode: UInt16(kVK_ANSI_J), modifiers: [.command])
+    let arguments = AppShortcuts.ghosttyCLIKeybindArguments(from: [.selectWorktree(1): override])
+    #expect(arguments.contains("--keybind=super+j=goto_tab:1"))
+    #expect(arguments.contains { $0.hasPrefix("--keybind=ctrl+1=") } == false)
+  }
+
   // MARK: - Shortcut identity.
 
   @Test func allShortcutsHaveUniqueIDs() {
@@ -95,7 +131,8 @@ struct AppShortcutsTests {
     #expect(AppShortcuts.openPullRequest.displayName == "Open Pull Request")
     #expect(AppShortcuts.toggleLeftSidebar.displayName == "Toggle Left Sidebar")
     #expect(AppShortcuts.selectWorktree1.displayName == "Select Worktree 1")
-    #expect(AppShortcuts.selectWorktree0.displayName == "Select Worktree 10")
+    #expect(AppShortcuts.selectWorktree9.displayName == "Select Worktree 9")
+    #expect(AppShortcutID.selectWorktree(0).displayName == "Select Worktree 10")
   }
 
   // MARK: - Effective shortcut resolution.
@@ -153,17 +190,17 @@ struct AppShortcutsTests {
   // MARK: - Active worktree selection slots.
 
   @Test func activeSlotsIncludeAllWhenNoOverrideAndRowsMatch() {
-    let slots = AppShortcuts.activeWorktreeSelectionSlots(overrides: [:], orderedRowsCount: 10)
-    #expect(slots.map(\.index) == [0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
+    let slots = AppShortcuts.activeWorktreeSelectionSlots(overrides: [:], orderedRowsCount: 9)
+    #expect(slots.map(\.index) == [0, 1, 2, 3, 4, 5, 6, 7, 8])
     expectNoDifference(slots.map(\.shortcut.display), AppShortcuts.worktreeSelection.map(\.display))
   }
 
   @Test func activeSlotsDropDisabledOverridePreservingOtherIndices() {
     let slots = AppShortcuts.activeWorktreeSelectionSlots(
       overrides: [.selectWorktree(6): .disabled],
-      orderedRowsCount: 10
+      orderedRowsCount: 9
     )
-    #expect(slots.map(\.index) == [0, 1, 2, 3, 4, 6, 7, 8, 9])
+    #expect(slots.map(\.index) == [0, 1, 2, 3, 4, 6, 7, 8])
     #expect(slots.allSatisfy { $0.index != 5 })
   }
 
diff --git a/supacodeTests/BrandedIDTestSupport.swift b/supacodeTests/BrandedIDTestSupport.swift
new file mode 100644
index 000000000..46a8c6130
--- /dev/null
+++ b/supacodeTests/BrandedIDTestSupport.swift
@@ -0,0 +1,23 @@
+@testable import supacode
+
+// String-literal + Comparable ergonomics for the branded id types, scoped to the
+// test target. The app target deliberately omits these conformances: on the
+// branded structs they add overload candidates that push `RepositoriesFeature`'s
+// reducer closures over the Swift type-checker's complexity limit. Tests don't
+// have that closure, so they can keep writing `id: "…"` and sorting ids.
+
+extension RepositoryID: @retroactive ExpressibleByStringLiteral {
+  public init(stringLiteral value: String) { self.init(value) }
+}
+
+extension WorktreeID: @retroactive ExpressibleByStringLiteral {
+  public init(stringLiteral value: String) { self.init(value) }
+}
+
+extension RepositoryID: @retroactive Comparable {
+  public static func < (lhs: Self, rhs: Self) -> Bool { lhs.rawValue < rhs.rawValue }
+}
+
+extension WorktreeID: @retroactive Comparable {
+  public static func < (lhs: Self, rhs: Self) -> Bool { lhs.rawValue < rhs.rawValue }
+}
diff --git a/supacodeTests/CodingAgentsSidebarCardModeTests.swift b/supacodeTests/CodingAgentsSidebarCardModeTests.swift
index 665aee866..58735a24a 100644
--- a/supacodeTests/CodingAgentsSidebarCardModeTests.swift
+++ b/supacodeTests/CodingAgentsSidebarCardModeTests.swift
@@ -9,7 +9,9 @@ struct CodingAgentsSidebarCardModeTests {
     let states: [SkillAgent: AgentIntegrationRowState] = [
       .claude: .ready(.installed),
       .codex: .ready(.outdated),
+      .copilot: .ready(.notInstalled),
       .kiro: .ready(.outdated),
+      .opencode: .ready(.notInstalled),
       .pi: .ready(.notInstalled),
     ]
     let mode = CodingAgentsSidebarCardView.mode(for: states, dismissed: false, autoUpdateEnabled: false)
@@ -24,7 +26,9 @@ struct CodingAgentsSidebarCardModeTests {
     let states: [SkillAgent: AgentIntegrationRowState] = [
       .claude: .ready(.outdated),
       .codex: .ready(.installed),
+      .copilot: .ready(.installed),
       .kiro: .ready(.installed),
+      .opencode: .ready(.installed),
       .pi: .ready(.installed),
     ]
     let mode = CodingAgentsSidebarCardView.mode(for: states, dismissed: true, autoUpdateEnabled: false)
@@ -35,7 +39,9 @@ struct CodingAgentsSidebarCardModeTests {
     let states: [SkillAgent: AgentIntegrationRowState] = [
       .claude: .ready(.installed),
       .codex: .ready(.notInstalled),
+      .copilot: .ready(.notInstalled),
       .kiro: .ready(.notInstalled),
+      .opencode: .ready(.notInstalled),
       .pi: .ready(.notInstalled),
     ]
     #expect(CodingAgentsSidebarCardView.mode(for: states, dismissed: false, autoUpdateEnabled: false) == .hidden)
@@ -45,7 +51,9 @@ struct CodingAgentsSidebarCardModeTests {
     let states: [SkillAgent: AgentIntegrationRowState] = [
       .claude: .ready(.notInstalled),
       .codex: .ready(.notInstalled),
+      .copilot: .ready(.notInstalled),
       .kiro: .ready(.notInstalled),
+      .opencode: .ready(.notInstalled),
       .pi: .ready(.notInstalled),
     ]
     #expect(CodingAgentsSidebarCardView.mode(for: states, dismissed: true, autoUpdateEnabled: false) == .hidden)
@@ -55,7 +63,9 @@ struct CodingAgentsSidebarCardModeTests {
     let states: [SkillAgent: AgentIntegrationRowState] = [
       .claude: .ready(.notInstalled),
       .codex: .ready(.notInstalled),
+      .copilot: .ready(.notInstalled),
       .kiro: .ready(.notInstalled),
+      .opencode: .ready(.notInstalled),
       .pi: .ready(.notInstalled),
     ]
     #expect(CodingAgentsSidebarCardView.mode(for: states, dismissed: false, autoUpdateEnabled: false) == .promptInstall)
@@ -65,7 +75,9 @@ struct CodingAgentsSidebarCardModeTests {
     let states: [SkillAgent: AgentIntegrationRowState] = [
       .claude: .ready(.notInstalled),
       .codex: .checking,
+      .copilot: .ready(.notInstalled),
       .kiro: .ready(.notInstalled),
+      .opencode: .ready(.notInstalled),
       .pi: .ready(.notInstalled),
     ]
     #expect(CodingAgentsSidebarCardView.mode(for: states, dismissed: false, autoUpdateEnabled: false) == .hidden)
@@ -77,7 +89,9 @@ struct CodingAgentsSidebarCardModeTests {
     let states: [SkillAgent: AgentIntegrationRowState] = [
       .claude: .ready(.notInstalled),
       .codex: .installing,
+      .copilot: .ready(.notInstalled),
       .kiro: .ready(.notInstalled),
+      .opencode: .ready(.notInstalled),
       .pi: .ready(.notInstalled),
     ]
     #expect(CodingAgentsSidebarCardView.mode(for: states, dismissed: false, autoUpdateEnabled: false) == .hidden)
@@ -89,7 +103,9 @@ struct CodingAgentsSidebarCardModeTests {
     let states: [SkillAgent: AgentIntegrationRowState] = [
       .claude: .ready(.installed),
       .codex: .uninstalling,
+      .copilot: .ready(.notInstalled),
       .kiro: .ready(.notInstalled),
+      .opencode: .ready(.notInstalled),
       .pi: .ready(.notInstalled),
     ]
     #expect(CodingAgentsSidebarCardView.mode(for: states, dismissed: false, autoUpdateEnabled: false) == .hidden)
@@ -102,7 +118,9 @@ struct CodingAgentsSidebarCardModeTests {
     let states: [SkillAgent: AgentIntegrationRowState] = [
       .claude: .ready(.notInstalled),
       .codex: .failed("boom"),
+      .copilot: .ready(.notInstalled),
       .kiro: .ready(.notInstalled),
+      .opencode: .ready(.notInstalled),
       .pi: .ready(.notInstalled),
     ]
     #expect(CodingAgentsSidebarCardView.mode(for: states, dismissed: false, autoUpdateEnabled: false) == .promptInstall)
@@ -115,7 +133,9 @@ struct CodingAgentsSidebarCardModeTests {
     let outdated: [SkillAgent: AgentIntegrationRowState] = [
       .claude: .ready(.outdated),
       .codex: .ready(.installed),
+      .copilot: .ready(.installed),
       .kiro: .ready(.installed),
+      .opencode: .ready(.installed),
       .pi: .ready(.installed),
     ]
     #expect(
@@ -125,7 +145,9 @@ struct CodingAgentsSidebarCardModeTests {
     let untouched: [SkillAgent: AgentIntegrationRowState] = [
       .claude: .ready(.notInstalled),
       .codex: .ready(.notInstalled),
+      .copilot: .ready(.notInstalled),
       .kiro: .ready(.notInstalled),
+      .opencode: .ready(.notInstalled),
       .pi: .ready(.notInstalled),
     ]
     #expect(
diff --git a/supacodeTests/CommandPaletteFeatureTests.swift b/supacodeTests/CommandPaletteFeatureTests.swift
index ec7b44d7b..8f2b022de 100644
--- a/supacodeTests/CommandPaletteFeatureTests.swift
+++ b/supacodeTests/CommandPaletteFeatureTests.swift
@@ -17,6 +17,7 @@ struct CommandPaletteFeatureTests {
       "global.check-for-updates",
       "global.open-settings",
       "global.open-repository",
+      "global.add-remote-repository",
       "global.new-worktree",
       "global.refresh-worktrees",
       "global.view-archived-worktrees",
@@ -43,7 +44,7 @@ struct CommandPaletteFeatureTests {
     state.sidebarItems[id: deleting.id]?.lifecycle = .deleting
     state.pendingWorktrees = [
       PendingWorktree(
-        id: "\(rootPath)/wt-pending",
+        id: WorktreeID("\(rootPath)/wt-pending"),
         repositoryID: repository.id,
         progress: WorktreeCreationProgress(
           stage: .creatingWorktree,
@@ -59,7 +60,7 @@ struct CommandPaletteFeatureTests {
     let items = CommandPaletteFeature.commandPaletteItems(from: state)
     let ids = items.map(\.id)
     #expect(ids.contains("worktree.\(keep.id).select"))
-    #expect(ids.contains { $0.contains(deleting.id) } == false)
+    #expect(ids.contains { $0.contains(deleting.id.rawValue) } == false)
     #expect(ids.contains { $0.contains("wt-pending") } == false)
   }
 
@@ -129,7 +130,7 @@ struct CommandPaletteFeatureTests {
     let rootPath = "/tmp/repo-rename-detached"
     let main = makeWorktree(id: rootPath, name: "main", repoRoot: rootPath)
     let detached = Worktree(
-      id: "\(rootPath)/dt",
+      id: WorktreeID("\(rootPath)/dt"),
       name: "dt",
       detail: "dt",
       workingDirectory: URL(fileURLWithPath: "\(rootPath)/dt"),
@@ -1062,6 +1063,55 @@ struct CommandPaletteFeatureTests {
     await store.receive(.delegate(.ghosttyCommand("goto_split:right")))
   }
 
+  @Test func updateSelection_usesDefaultIndexWhenNoSelection() async {
+    let store = TestStore(initialState: CommandPaletteFeature.State()) {
+      CommandPaletteFeature()
+    }
+
+    // The project switcher hands a defaultIndex of 1 to skip its own
+    // current-project row; with no prior selection the cursor lands there.
+    await store.send(.updateSelection(itemsCount: 3, defaultIndex: 1)) {
+      $0.selectedIndex = 1
+    }
+  }
+
+  @Test func updateSelection_clampsDefaultIndexToLastRow() async {
+    let store = TestStore(initialState: CommandPaletteFeature.State()) {
+      CommandPaletteFeature()
+    }
+
+    // A defaultIndex past the end (e.g. a stale switcher list shrank to one
+    // row) clamps to the last valid index rather than overrunning.
+    await store.send(.updateSelection(itemsCount: 1, defaultIndex: 1)) {
+      $0.selectedIndex = 0
+    }
+  }
+
+  @Test func updateSelection_keepsExistingSelectionOverDefault() async {
+    var state = CommandPaletteFeature.State()
+    state.selectedIndex = 0
+    let store = TestStore(initialState: state) {
+      CommandPaletteFeature()
+    }
+
+    // An in-bounds existing selection wins; defaultIndex only seeds a nil
+    // selection so arrow-key navigation isn't yanked back on every refresh.
+    await store.send(.updateSelection(itemsCount: 3, defaultIndex: 1))
+  }
+
+  @Test func resetSelection_usesDefaultIndex() async {
+    var state = CommandPaletteFeature.State()
+    state.selectedIndex = 2
+    let store = TestStore(initialState: state) {
+      CommandPaletteFeature()
+    }
+
+    // resetSelection (fired on query change) snaps straight to defaultIndex.
+    await store.send(.resetSelection(itemsCount: 3, defaultIndex: 1)) {
+      $0.selectedIndex = 1
+    }
+  }
+
   // MARK: - Script items.
 
   @Test func commandPaletteItems_includesRunItemsForConfiguredScripts() {
@@ -1149,6 +1199,179 @@ struct CommandPaletteFeatureTests {
     #expect(ids.contains("script.\(definition.id).run"))
     #expect(ids.contains("script.\(definition.id).stop"))
   }
+
+  @Test func worktreeSwitcherItems_emptyWhenNoWorktrees() {
+    let items = CommandPaletteFeature.worktreeSwitcherItems(from: RepositoriesFeature.State())
+    #expect(items.isEmpty)
+  }
+
+  @Test func worktreeSwitcherItems_sortsByMRUThenSidebarOrderAndMarksCurrent() {
+    let wtA = makeWorktree(id: "/tmp/repo-a/wt", name: "wt", repoRoot: "/tmp/repo-a")
+    let wtB = makeWorktree(id: "/tmp/repo-b/wt", name: "wt", repoRoot: "/tmp/repo-b")
+    let wtC = makeWorktree(id: "/tmp/repo-c/wt", name: "wt", repoRoot: "/tmp/repo-c")
+    let repoA = makeRepository(rootPath: "/tmp/repo-a", name: "Alpha", worktrees: [wtA])
+    let repoB = makeRepository(rootPath: "/tmp/repo-b", name: "Bravo", worktrees: [wtB])
+    let repoC = makeRepository(rootPath: "/tmp/repo-c", name: "Charlie", worktrees: [wtC])
+    var state = RepositoriesFeature.State(reconciledRepositories: [repoA, repoB, repoC])
+
+    // MRU = [wtA, wtC] after select C then select A. The current worktree
+    // (wtA, the MRU head) is rendered first but flagged isCurrentWorktree so
+    // the overlay skips it for the default selection.
+    state.setSingleWorktreeSelection(wtC.id)
+    state.setSingleWorktreeSelection(wtA.id)
+
+    let items = CommandPaletteFeature.worktreeSwitcherItems(from: state)
+
+    // MRU head (A), then prior MRU (C), then the worktree never visited (B),
+    // which trails in sidebar order.
+    #expect(items.map(\.id) == [
+      "worktree.\(wtA.id).select",
+      "worktree.\(wtC.id).select",
+      "worktree.\(wtB.id).select",
+    ])
+    // priorityTier mirrors visible order so an empty-query prioritizeItems()
+    // pass preserves the MRU ranking even though item-level recency is empty.
+    #expect(items.map(\.priorityTier) == [0, 1, 2])
+    // Only the current worktree (A) carries the skip-for-default flag.
+    #expect(items.map(\.isCurrentWorktree) == [true, false, false])
+  }
+
+  @Test func worktreeSwitcherItems_listsEveryWorktreeAcrossRepos() {
+    // The whole point of the rework: multi-worktree repos surface every
+    // worktree, not a single per-repo entry. wt1/wt2 share repoA.
+    let wt1 = makeWorktree(id: "/tmp/repo-a/wt-1", name: "feature/one", repoRoot: "/tmp/repo-a")
+    let wt2 = makeWorktree(id: "/tmp/repo-a/wt-2", name: "feature/two", repoRoot: "/tmp/repo-a")
+    let wt3 = makeWorktree(id: "/tmp/repo-b/wt", name: "main", repoRoot: "/tmp/repo-b")
+    let repoA = makeRepository(rootPath: "/tmp/repo-a", name: "Alpha", worktrees: [wt1, wt2])
+    let repoB = makeRepository(rootPath: "/tmp/repo-b", name: "Bravo", worktrees: [wt3])
+    let state = RepositoriesFeature.State(reconciledRepositories: [repoA, repoB])
+
+    let items = CommandPaletteFeature.worktreeSwitcherItems(from: state)
+
+    #expect(Set(items.map(\.id)) == [
+      "worktree.\(wt1.id).select",
+      "worktree.\(wt2.id).select",
+      "worktree.\(wt3.id).select",
+    ])
+  }
+
+  @Test func worktreeSwitcherItems_titleIsWorktreeWithRepoSubtitle() {
+    let wtFeat = makeWorktree(id: "/tmp/repo/feat", name: "feature/x", repoRoot: "/tmp/repo")
+    let repo = makeRepository(rootPath: "/tmp/repo", name: "Repo", worktrees: [wtFeat])
+    let state = RepositoriesFeature.State(reconciledRepositories: [repo])
+
+    let items = CommandPaletteFeature.worktreeSwitcherItems(from: state)
+    // Worktree name is the prominent title; repo is the secondary subtitle so
+    // the two read as a hierarchy. The fuzzy scorer matches both, so a query
+    // still hits either the worktree name or the project name.
+    #expect(items.first?.title == "feature/x")
+    #expect(items.first?.subtitle == "Repo")
+  }
+
+  @Test func items_dispatchByMode() {
+    let wtMain = makeWorktree(id: "/tmp/repo/main", name: "main", repoRoot: "/tmp/repo")
+    let wtOther = makeWorktree(id: "/tmp/other/wt", name: "wt", repoRoot: "/tmp/other")
+    let repo = makeRepository(rootPath: "/tmp/repo", name: "Repo", worktrees: [wtMain])
+    let other = makeRepository(rootPath: "/tmp/other", name: "Other", worktrees: [wtOther])
+    var state = RepositoriesFeature.State(reconciledRepositories: [repo, other])
+    // wtOther is current; wtMain is the previous worktree the switcher surfaces.
+    state.setSingleWorktreeSelection(wtMain.id)
+    state.setSingleWorktreeSelection(wtOther.id)
+
+    let commands = CommandPaletteFeature.items(in: .commands, from: state)
+    let switcher = CommandPaletteFeature.items(in: .worktreeSwitcher, from: state)
+
+    // .commands surfaces the existing palette items (globals, worktree
+    // selects, etc.).
+    #expect(commands.contains { $0.id.hasPrefix("global.") })
+    #expect(commands.contains { $0.id == "worktree.\(wtMain.id).select" })
+
+    // .worktreeSwitcher is worktree-only, MRU-ordered. The current worktree
+    // (wtOther) leads, flagged so the overlay skips it for the default
+    // selection; the prior worktree (wtMain) follows.
+    #expect(switcher.allSatisfy { $0.id.hasPrefix("worktree.") && $0.id.hasSuffix(".select") })
+    #expect(switcher == [
+      CommandPaletteItem(
+        id: "worktree.\(wtOther.id).select",
+        title: "wt",
+        subtitle: "Other",
+        kind: .worktreeSelect(wtOther.id),
+        priorityTier: 0,
+        isCurrentWorktree: true
+      ),
+      CommandPaletteItem(
+        id: "worktree.\(wtMain.id).select",
+        title: "main",
+        subtitle: "Repo",
+        kind: .worktreeSelect(wtMain.id),
+        priorityTier: 1
+      ),
+    ])
+  }
+
+  @Test func presentInMode_setsModeAndPresentsTheView() async {
+    let store = TestStore(initialState: CommandPaletteFeature.State()) {
+      CommandPaletteFeature()
+    }
+
+    await store.send(.presentInMode(.worktreeSwitcher)) {
+      $0.isPresented = true
+      $0.mode = .worktreeSwitcher
+    }
+  }
+
+  @Test func setPresented_falseFromPresentedEmitsDismissedDelegate() async {
+    let store = TestStore(
+      initialState: CommandPaletteFeature.State(isPresented: true, mode: .worktreeSwitcher)
+    ) {
+      CommandPaletteFeature()
+    }
+
+    await store.send(.setPresented(false)) {
+      $0.isPresented = false
+      $0.mode = .commands
+    }
+    await store.receive(\.delegate.dismissedWithoutSelection)
+  }
+
+  @Test func setPresented_falseFromNotPresentedDoesNotEmitDelegate() async {
+    let store = TestStore(initialState: CommandPaletteFeature.State()) {
+      CommandPaletteFeature()
+    }
+    await store.send(.setPresented(false))
+  }
+
+  @Test func togglePresented_dismissEmitsDelegate() async {
+    let store = TestStore(initialState: CommandPaletteFeature.State(isPresented: true)) {
+      CommandPaletteFeature()
+    }
+
+    await store.send(.togglePresented) {
+      $0.isPresented = false
+    }
+    await store.receive(\.delegate.dismissedWithoutSelection)
+  }
+
+  @Test func activateItem_doesNotEmitDismissedDelegate() async {
+    let store = TestStore(initialState: CommandPaletteFeature.State(isPresented: true)) {
+      CommandPaletteFeature()
+    } withDependencies: {
+      $0.date.now = Date(timeIntervalSince1970: 0)
+    }
+
+    let item = CommandPaletteItem(
+      id: "global.open-settings",
+      title: "Open Settings",
+      subtitle: nil,
+      kind: .openSettings
+    )
+    await store.send(.activateItem(item)) {
+      $0.isPresented = false
+      $0.recencyByItemID[item.id] = 0
+    }
+    // The activation delegate carries the focus — no dismissal echo.
+    await store.receive(\.delegate.openSettings)
+  }
 }
 
 private func makeWorktree(
@@ -1159,7 +1382,7 @@ private func makeWorktree(
   workingDirectory: String? = nil
 ) -> Worktree {
   Worktree(
-    id: id,
+    id: WorktreeID(id),
     name: name,
     detail: detail,
     workingDirectory: URL(fileURLWithPath: workingDirectory ?? id),
@@ -1174,7 +1397,7 @@ private func makeRepository(
 ) -> Repository {
   let rootURL = URL(fileURLWithPath: rootPath)
   return Repository(
-    id: rootURL.path(percentEncoded: false),
+    id: RepositoryID(rootURL.path(percentEncoded: false)),
     rootURL: rootURL,
     name: name,
     worktrees: IdentifiedArray(uniqueElements: worktrees)
diff --git a/supacodeTests/CopilotHooksInstallerTests.swift b/supacodeTests/CopilotHooksInstallerTests.swift
new file mode 100644
index 000000000..c996d605f
--- /dev/null
+++ b/supacodeTests/CopilotHooksInstallerTests.swift
@@ -0,0 +1,240 @@
+import Foundation
+import Testing
+
+@testable import SupacodeSettingsShared
+@testable import supacode
+
+struct CopilotHooksInstallerTests {
+  private let fileManager = FileManager.default
+
+  // MARK: - Ordering.
+
+  /// `allCases` drives the agent order in Settings and the sidebar card, so it
+  /// must stay alphabetical by raw value; a new case appended at the end regresses it.
+  @Test func allCasesStayAlphabeticalByRawValue() {
+    let raws = SkillAgent.allCases.map(\.rawValue)
+    #expect(raws == raws.sorted())
+  }
+
+  private func makeTempHomeURL() -> URL {
+    URL(fileURLWithPath: NSTemporaryDirectory())
+      .appendingPathComponent("supacode-copilot-hooks-\(UUID().uuidString)", isDirectory: true)
+  }
+
+  // MARK: - Install / uninstall.
+
+  @Test func installWritesHookFileWhenMissing() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = CopilotHooksInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try installer.install()
+
+    #expect(fileManager.fileExists(atPath: installer.hookFileURL.path))
+    let contents = try String(contentsOf: installer.hookFileURL, encoding: .utf8)
+    #expect(try contents == CopilotHookSettings.source())
+  }
+
+  @Test func installIsIdempotent() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = CopilotHooksInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try installer.install()
+    let first = try Data(contentsOf: installer.hookFileURL)
+    try installer.install()
+    let second = try Data(contentsOf: installer.hookFileURL)
+
+    #expect(first == second)
+  }
+
+  @Test func installThrowsForUnownedFileWithSameName() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = CopilotHooksInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try fileManager.createDirectory(
+      at: installer.hookFileURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+    let userFile = #"{ "version": 1, "hooks": { "stop": [] } }"#
+    try userFile.write(to: installer.hookFileURL, atomically: true, encoding: .utf8)
+
+    #expect(throws: CopilotHooksInstallerError.fileNotManaged) {
+      try installer.install()
+    }
+    let after = try String(contentsOf: installer.hookFileURL, encoding: .utf8)
+    #expect(after == userFile)
+  }
+
+  @Test func uninstallRemovesOwnedFile() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = CopilotHooksInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try installer.install()
+    try installer.uninstall()
+
+    #expect(!fileManager.fileExists(atPath: installer.hookFileURL.path))
+    #expect(installer.installState() == .notInstalled)
+  }
+
+  @Test func uninstallThrowsForUnownedFileWithSameName() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = CopilotHooksInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try fileManager.createDirectory(
+      at: installer.hookFileURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+    let userFile = #"{ "version": 1, "hooks": { "stop": [] } }"#
+    try userFile.write(to: installer.hookFileURL, atomically: true, encoding: .utf8)
+
+    #expect(throws: CopilotHooksInstallerError.fileNotManaged) {
+      try installer.uninstall()
+    }
+    let after = try String(contentsOf: installer.hookFileURL, encoding: .utf8)
+    #expect(after == userFile)
+  }
+
+  @Test func uninstallIsNoOpWhenMissing() {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = CopilotHooksInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    #expect(throws: Never.self) {
+      try installer.uninstall()
+    }
+  }
+
+  @Test func installAndUninstallPreserveSiblingUserHooks() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = CopilotHooksInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    let hooksDir = installer.hookFileURL.deletingLastPathComponent()
+    try fileManager.createDirectory(at: hooksDir, withIntermediateDirectories: true)
+    let siblingURL = hooksDir.appending(path: "my-hooks.json", directoryHint: .notDirectory)
+    let sibling = #"{ "version": 1, "hooks": { "preToolUse": [] } }"#
+    try sibling.write(to: siblingURL, atomically: true, encoding: .utf8)
+
+    try installer.install()
+    try installer.uninstall()
+
+    #expect(!fileManager.fileExists(atPath: installer.hookFileURL.path))
+    #expect(fileManager.fileExists(atPath: siblingURL.path))
+    #expect(try String(contentsOf: siblingURL, encoding: .utf8) == sibling)
+  }
+
+  // MARK: - Install state.
+
+  @Test func installStateNotInstalledBeforeInstall() {
+    let homeURL = makeTempHomeURL()
+    let installer = CopilotHooksInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    #expect(installer.installState() == .notInstalled)
+  }
+
+  @Test func installStateInstalledAfterInstall() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = CopilotHooksInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try installer.install()
+    #expect(installer.installState() == .installed)
+  }
+
+  @Test func installStateOutdatedWhenContentDiffers() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = CopilotHooksInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try fileManager.createDirectory(
+      at: installer.hookFileURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+    // A stale Supacode file: carries the ownership marker but differs.
+    try #"{ "hooks": { "stop": [ { "bash": "old \#(CopilotHookSettings.ownershipMarker)" } ] } }"#
+      .write(to: installer.hookFileURL, atomically: true, encoding: .utf8)
+
+    #expect(installer.installState() == .outdated)
+  }
+
+  @Test func installStateNotInstalledForUnownedFileWithSameName() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = CopilotHooksInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try fileManager.createDirectory(
+      at: installer.hookFileURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+    // Unowned file must report `.notInstalled`, not `.outdated` (auto-update would overwrite it).
+    try #"{ "version": 1, "hooks": { "stop": [] } }"#
+      .write(to: installer.hookFileURL, atomically: true, encoding: .utf8)
+
+    #expect(installer.installState() == .notInstalled)
+  }
+
+  @Test func hookFilePointsToExpectedPath() {
+    let homeURL = URL(fileURLWithPath: "/Users/test")
+    let installer = CopilotHooksInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    #expect(installer.hookFileURL.path == "/Users/test/.copilot/hooks/supacode.json")
+  }
+
+  // MARK: - Generated source.
+
+  @Test func sourceIsValidJSONWithVersionAndEvents() throws {
+    let data = Data(try CopilotHookSettings.source().utf8)
+    let root = try #require(try JSONSerialization.jsonObject(with: data) as? [String: Any])
+    #expect(root["version"] as? Int == 1)
+    let hooks = try #require(root["hooks"] as? [String: Any])
+    #expect(
+      Set(hooks.keys) == [
+        "sessionStart", "userPromptSubmitted", "preToolUse", "postToolUse",
+        "agentStop", "sessionEnd", "notification",
+      ])
+  }
+
+  @Test func sourceCarriesOwnershipMarker() throws {
+    #expect(try CopilotHookSettings.source().contains(CopilotHookSettings.ownershipMarker))
+  }
+
+  @Test func sourceEmbedsCopilotScopedOSCForEveryState() throws {
+    let source = try CopilotHookSettings.source()
+    #expect(source.contains("start=copilot;event=session_start"))
+    #expect(source.contains("start=copilot;event=busy"))
+    #expect(source.contains("start=copilot;event=idle"))
+    #expect(source.contains("end=copilot;event=session_end"))
+  }
+
+  @Test func sourceForwardsNotificationsAndFlagsAwaitingInput() throws {
+    let source = try CopilotHookSettings.source()
+    #expect(source.contains("kind=notify"))
+    #expect(source.contains("start=copilot;event=awaiting_input"))
+    #expect(source.contains("permission_prompt"))
+    #expect(source.contains("elicitation_dialog"))
+  }
+
+  /// Guards the hand-composed notification shell: the awaiting-input + notify
+  /// legs must stay gated behind the permission / elicitation `case` branch so
+  /// other notification types stay no-ops (a widened glob would alert on every
+  /// notification).
+  @Test func notificationCommandGatesAwaitingInputBehindPromptCase() throws {
+    let data = Data(try CopilotHookSettings.source().utf8)
+    let root = try #require(try JSONSerialization.jsonObject(with: data) as? [String: Any])
+    let hooks = try #require(root["hooks"] as? [String: [[String: Any]]])
+    let bash = try #require(hooks["notification"]?.first?["bash"] as? String)
+
+    let caseStart = try #require(bash.range(of: "case \"$__in\" in *permission_prompt*|*elicitation_dialog*)"))
+    // Backwards: `ttyResolveSnippet` nests its own `case … esac`, so the outer one is last.
+    let caseEnd = try #require(bash.range(of: "esac", options: .backwards))
+    let branch = bash[caseStart.upperBound..<caseEnd.lowerBound]
+    #expect(branch.contains("event=awaiting_input"))
+    #expect(branch.contains("kind=notify"))
+  }
+
+  @Test func installStateNotInstalledForNonUTF8File() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = CopilotHooksInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try fileManager.createDirectory(
+      at: installer.hookFileURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+    try Data([0xFF, 0xFE, 0xFD]).write(to: installer.hookFileURL)
+
+    #expect(installer.installState() == .notInstalled)
+  }
+}
diff --git a/supacodeTests/GhosttyRuntimeBundledOverridesTests.swift b/supacodeTests/GhosttyRuntimeBundledOverridesTests.swift
index b0d6ac56a..4afb90912 100644
--- a/supacodeTests/GhosttyRuntimeBundledOverridesTests.swift
+++ b/supacodeTests/GhosttyRuntimeBundledOverridesTests.swift
@@ -5,12 +5,12 @@ import Testing
 
 @MainActor
 struct GhosttyRuntimeBundledOverridesTests {
-  /// `shell-integration = none` is the actual #356 fix; it must stay in the
-  /// bundled overrides so Ghostty's `setupBash` is unreachable and `--posix`
-  /// can never be prepended to the surface command. A future refactor that
-  /// drops this line reintroduces the crash.
-  @Test func bundledOverridesDisableShellIntegration() {
-    #expect(GhosttyRuntime.bundledOverridesString.contains("shell-integration = none"))
+  /// Shell integration must NOT be disabled in the bundled overrides: surfaces
+  /// run the real shell with zmx injected as a `command-wrapper`, so Ghostty
+  /// integrates the shell exactly as without zmx. Forcing `none` here would
+  /// regress OSC 7 cwd reporting (the whole point of the wrapper approach).
+  @Test func bundledOverridesDoNotTouchShellIntegration() {
+    #expect(!GhosttyRuntime.bundledOverridesString.contains("shell-integration"))
   }
 
   /// Each line in the heredoc is parsed as a Ghostty `key = value` directive
@@ -25,4 +25,37 @@ struct GhosttyRuntimeBundledOverridesTests {
       #expect(line.contains("="), "Override line missing `=`: \(line)")
     }
   }
+
+  /// `TERM_PROGRAM` reports Supacode with its version (issue #440).
+  @Test func terminalProgramOverridesIdentifySupacode() {
+    let overrides = GhosttyRuntime.terminalProgramOverrides(version: "1.2.3")
+    #expect(overrides.contains("env = TERM_PROGRAM=supacode"))
+    #expect(overrides.contains("env = TERM_PROGRAM_VERSION=1.2.3"))
+  }
+
+  /// A missing or blank version still emits a placeholder, never Ghostty's.
+  @Test func terminalProgramOverridesFallBackWhenVersionUnavailable() {
+    for version: String? in [nil, "", "   "] {
+      let overrides = GhosttyRuntime.terminalProgramOverrides(version: version)
+      #expect(overrides.contains("env = TERM_PROGRAM=supacode"))
+      #expect(overrides.contains("env = TERM_PROGRAM_VERSION=unknown"))
+    }
+  }
+
+  /// Surrounding whitespace is trimmed from the emitted version.
+  @Test func terminalProgramOverridesTrimVersionWhitespace() {
+    let overrides = GhosttyRuntime.terminalProgramOverrides(version: " 1.2.3 ")
+    #expect(overrides.contains("env = TERM_PROGRAM_VERSION=1.2.3"))
+  }
+
+  @Test func terminalProgramOverridesAreKeyValueDirectives() {
+    let lines = GhosttyRuntime.terminalProgramOverrides(version: "9.9.9")
+      .split(whereSeparator: \.isNewline)
+      .map { $0.trimmingCharacters(in: .whitespaces) }
+      .filter { !$0.isEmpty }
+    #expect(!lines.isEmpty)
+    for line in lines {
+      #expect(line.contains("="), "Override line missing `=`: \(line)")
+    }
+  }
 }
diff --git a/supacodeTests/GhosttySurfaceBridgeTests.swift b/supacodeTests/GhosttySurfaceBridgeTests.swift
index 528e229b3..478297c94 100644
--- a/supacodeTests/GhosttySurfaceBridgeTests.swift
+++ b/supacodeTests/GhosttySurfaceBridgeTests.swift
@@ -3,6 +3,7 @@ import Foundation
 import GhosttyKit
 import Testing
 
+@testable import SupacodeSettingsShared
 @testable import supacode
 
 // Serialized: the coalescing tests drive a TestClock with two concurrent
@@ -87,7 +88,7 @@ struct GhosttySurfaceBridgeTests {
 
   @Test func desktopNotificationEmitsCallback() {
     let bridge = GhosttySurfaceBridge()
-    var received: (String, String)?
+    var received: (title: String, body: String)?
     bridge.onDesktopNotification = { title, body in
       received = (title, body)
     }
@@ -106,8 +107,71 @@ struct GhosttySurfaceBridgeTests {
       }
     }
 
-    #expect(received?.0 == "Title")
-    #expect(received?.1 == "Body")
+    #expect(received?.title == "Title")
+    #expect(received?.body == "Body")
+  }
+
+  @Test func contextSignalEmitsCallback() {
+    let bridge = GhosttySurfaceBridge()
+    var receivedAction: UInt8?
+    var receivedID: String?
+    var receivedMetadata: String?
+    bridge.onContextSignal = { action, id, metadata in
+      receivedAction = action
+      receivedID = id
+      receivedMetadata = metadata
+    }
+
+    var action = ghostty_action_s()
+    action.tag = GHOSTTY_ACTION_CONTEXT_SIGNAL
+    let target = ghostty_target_s()
+
+    "claude".withCString { idPtr in
+      "event=busy".withCString { metaPtr in
+        action.action.context_signal = ghostty_action_context_signal_s(
+          action: 0,
+          id: idPtr,
+          metadata: metaPtr
+        )
+        _ = bridge.handleAction(target: target, action: action)
+      }
+    }
+
+    #expect(receivedAction == 0)
+    #expect(receivedID == "claude")
+    #expect(receivedMetadata == "event=busy")
+  }
+
+  @Test func contextSignalDropsNullIDOrMetadata() {
+    let bridge = GhosttySurfaceBridge()
+    var invoked = false
+    bridge.onContextSignal = { _, _, _ in invoked = true }
+
+    var action = ghostty_action_s()
+    action.tag = GHOSTTY_ACTION_CONTEXT_SIGNAL
+    let target = ghostty_target_s()
+
+    // Null id with valid metadata.
+    "event=busy".withCString { metaPtr in
+      action.action.context_signal = ghostty_action_context_signal_s(
+        action: 0,
+        id: nil,
+        metadata: metaPtr
+      )
+      _ = bridge.handleAction(target: target, action: action)
+    }
+    #expect(invoked == false)
+
+    // Valid id with null metadata.
+    "claude".withCString { idPtr in
+      action.action.context_signal = ghostty_action_context_signal_s(
+        action: 0,
+        id: idPtr,
+        metadata: nil
+      )
+      _ = bridge.handleAction(target: target, action: action)
+    }
+    #expect(invoked == false)
   }
 
   @Test func coalescesBurstOfProgressReports() async {
diff --git a/supacodeTests/GhosttySurfaceViewTests.swift b/supacodeTests/GhosttySurfaceViewTests.swift
index 18755a42f..09e09526d 100644
--- a/supacodeTests/GhosttySurfaceViewTests.swift
+++ b/supacodeTests/GhosttySurfaceViewTests.swift
@@ -79,6 +79,240 @@ struct GhosttySurfaceViewTests {
     #expect(suppression.isExpired(at: 11.1))
   }
 
+  private static func keyEvent(
+    chars: String,
+    ignoringModifiers: String,
+    modifiers: NSEvent.ModifierFlags
+  ) -> NSEvent {
+    NSEvent.keyEvent(
+      with: .keyDown,
+      location: .zero,
+      modifierFlags: modifiers,
+      timestamp: 0,
+      windowNumber: 0,
+      context: nil,
+      characters: chars,
+      charactersIgnoringModifiers: ignoringModifiers,
+      isARepeat: false,
+      keyCode: 4
+    )!
+  }
+
+  private static func item(action: Selector?, keyEquivalent: String, mask: NSEvent.ModifierFlags) -> NSMenuItem {
+    let item = NSMenuItem(title: "Item", action: action, keyEquivalent: keyEquivalent)
+    item.keyEquivalentModifierMask = mask
+    return item
+  }
+
+  private static func menu(action: Selector?, keyEquivalent: String, mask: NSEvent.ModifierFlags) -> NSMenu {
+    let menu = NSMenu()
+    menu.addItem(item(action: action, keyEquivalent: keyEquivalent, mask: mask))
+    return menu
+  }
+
+  /// The `⌥⌘H` chord that collides with the Hide Others built-in.
+  private static func optionCommandH() -> NSEvent {
+    keyEvent(chars: "˙", ignoringModifiers: "h", modifiers: [.command, .option])
+  }
+
+  /// The Hide Others built-in item bound to `⌥⌘H`.
+  private static func hideOthersItem() -> NSMenuItem {
+    item(
+      action: #selector(NSApplication.hideOtherApplications(_:)),
+      keyEquivalent: "h",
+      mask: [.command, .option]
+    )
+  }
+
+  @Test func forwardableMenuItemSkipsHideOthersBuiltIn() {
+    let menu = Self.menu(
+      action: #selector(NSApplication.hideOtherApplications(_:)),
+      keyEquivalent: "h",
+      mask: [.command, .option]
+    )
+
+    #expect(GhosttySurfaceView.forwardableMenuItem(for: Self.optionCommandH(), in: menu) == nil)
+  }
+
+  @Test func forwardableMenuItemKeepsAppOwnedItem() {
+    let menu = Self.menu(action: Selector(("appOwnedAction:")), keyEquivalent: "h", mask: [.command, .option])
+
+    #expect(GhosttySurfaceView.forwardableMenuItem(for: Self.optionCommandH(), in: menu) != nil)
+  }
+
+  @Test func forwardableMenuItemSkipsHideBuiltIn() {
+    let event = Self.keyEvent(chars: "h", ignoringModifiers: "h", modifiers: [.command])
+    let menu = Self.menu(action: #selector(NSApplication.hide(_:)), keyEquivalent: "h", mask: [.command])
+
+    #expect(GhosttySurfaceView.forwardableMenuItem(for: event, in: menu) == nil)
+  }
+
+  @Test func forwardableMenuItemHonorsImplicitShiftForAppOwnedItem() {
+    let event = Self.keyEvent(chars: "A", ignoringModifiers: "a", modifiers: [.command, .shift])
+    let menu = Self.menu(action: Selector(("appOwnedAction:")), keyEquivalent: "A", mask: [.command])
+
+    #expect(GhosttySurfaceView.forwardableMenuItem(for: event, in: menu) != nil)
+  }
+
+  @Test func forwardableMenuItemRecursesIntoSubmenusAndSkipsBuiltIns() {
+    let builtInSubmenu = NSMenu()
+    builtInSubmenu.addItem(Self.hideOthersItem())
+    let builtInRoot = NSMenu()
+    builtInRoot.addItem(withTitle: "App", action: nil, keyEquivalent: "").submenu = builtInSubmenu
+    #expect(GhosttySurfaceView.forwardableMenuItem(for: Self.optionCommandH(), in: builtInRoot) == nil)
+
+    let appSubmenu = NSMenu()
+    appSubmenu.addItem(Self.item(action: Selector(("appOwnedAction:")), keyEquivalent: "h", mask: [.command, .option]))
+    let appRoot = NSMenu()
+    appRoot.addItem(withTitle: "App", action: nil, keyEquivalent: "").submenu = appSubmenu
+    #expect(GhosttySurfaceView.forwardableMenuItem(for: Self.optionCommandH(), in: appRoot) != nil)
+  }
+
+  @Test func forwardableMenuItemResolvesAppOwnedItemSharingChordWithBuiltIn() {
+    let menu = NSMenu()
+    menu.addItem(Self.hideOthersItem())
+    let appOwned = Self.item(action: Selector(("appOwnedAction:")), keyEquivalent: "h", mask: [.command, .option])
+    menu.addItem(appOwned)
+
+    // The built-in is listed first, so this pins that we dispatch the app-owned item, never Hide Others.
+    #expect(GhosttySurfaceView.forwardableMenuItem(for: Self.optionCommandH(), in: menu) === appOwned)
+  }
+
+  @Test func forwardableMenuItemIgnoresBuiltInWithNonMatchingMask() {
+    let event = Self.keyEvent(chars: "h", ignoringModifiers: "h", modifiers: [.command])
+    let menu = NSMenu()
+    menu.addItem(Self.hideOthersItem())
+    let appOwned = Self.item(action: Selector(("appOwnedAction:")), keyEquivalent: "h", mask: [.command])
+    menu.addItem(appOwned)
+
+    #expect(GhosttySurfaceView.forwardableMenuItem(for: event, in: menu) === appOwned)
+  }
+
+  @Test func menuHasSystemManagedConflictDetectsBuiltInSharingChord() {
+    // A custom `close_surface` remapped onto ⌘M collides with Minimize, so the chord must
+    // stay with Ghostty instead of forwarding (which could fire Minimize).
+    let event = Self.keyEvent(chars: "m", ignoringModifiers: "m", modifiers: [.command])
+    let menu = NSMenu()
+    menu.addItem(Self.item(action: Selector(("appOwnedAction:")), keyEquivalent: "m", mask: [.command]))
+    menu.addItem(Self.item(action: #selector(NSWindow.performMiniaturize(_:)), keyEquivalent: "m", mask: [.command]))
+
+    #expect(GhosttySurfaceView.menuHasSystemManagedConflict(for: event, in: menu))
+  }
+
+  @Test func menuHasSystemManagedConflictIgnoresAppOwnedOnlyChord() {
+    let event = Self.keyEvent(chars: "w", ignoringModifiers: "w", modifiers: [.command])
+    let menu = Self.menu(action: Selector(("appOwnedAction:")), keyEquivalent: "w", mask: [.command])
+
+    #expect(!GhosttySurfaceView.menuHasSystemManagedConflict(for: event, in: menu))
+  }
+
+  @Test func menuHasSystemManagedConflictRecursesIntoSubmenus() {
+    let submenu = NSMenu()
+    submenu.addItem(Self.hideOthersItem())
+    let root = NSMenu()
+    root.addItem(withTitle: "App", action: nil, keyEquivalent: "").submenu = submenu
+
+    #expect(GhosttySurfaceView.menuHasSystemManagedConflict(for: Self.optionCommandH(), in: root))
+  }
+
+  @Test func menuItemMatchesExactCommandChord() {
+    let event = Self.keyEvent(chars: "w", ignoringModifiers: "w", modifiers: [.command])
+    let item = Self.item(action: Selector(("appOwnedAction:")), keyEquivalent: "w", mask: [.command])
+
+    #expect(GhosttySurfaceView.menuItem(item, matches: event))
+  }
+
+  @Test func menuItemRejectsSupersetModifierChord() {
+    // `⌘,` (Settings) must not match `⌘⇧,` (Ghostty's reload_config).
+    let event = Self.keyEvent(chars: ",", ignoringModifiers: ",", modifiers: [.command, .shift])
+    let item = Self.item(action: Selector(("appOwnedAction:")), keyEquivalent: ",", mask: [.command])
+
+    #expect(!GhosttySurfaceView.menuItem(item, matches: event))
+  }
+
+  @Test func menuItemRejectsEmptyKeyEquivalent() {
+    let event = Self.keyEvent(chars: "w", ignoringModifiers: "w", modifiers: [.command])
+    let item = Self.item(action: Selector(("appOwnedAction:")), keyEquivalent: "", mask: [.command])
+
+    #expect(!GhosttySurfaceView.menuItem(item, matches: event))
+  }
+
+  @Test func menuItemHonorsImplicitShiftBothDirections() {
+    // An uppercase `keyEquivalent` encodes shift: it matches ⌘⇧A but not plain ⌘a.
+    let shiftEvent = Self.keyEvent(chars: "A", ignoringModifiers: "a", modifiers: [.command, .shift])
+    let plainEvent = Self.keyEvent(chars: "a", ignoringModifiers: "a", modifiers: [.command])
+    let item = Self.item(action: Selector(("appOwnedAction:")), keyEquivalent: "A", mask: [.command])
+
+    #expect(GhosttySurfaceView.menuItem(item, matches: shiftEvent))
+    #expect(!GhosttySurfaceView.menuItem(item, matches: plainEvent))
+  }
+
+  private final class MenuActionTarget: NSObject {
+    var fired = false
+    @objc func fire(_ sender: Any?) { fired = true }
+  }
+
+  @Test func performMenuItemDispatchesEnabledItem() {
+    let target = MenuActionTarget()
+    let item = NSMenuItem(title: "Go", action: #selector(MenuActionTarget.fire(_:)), keyEquivalent: "")
+    item.target = target
+    item.isEnabled = true
+
+    #expect(GhosttySurfaceView.performMenuItem(item))
+    #expect(target.fired)
+  }
+
+  @Test func performMenuItemRejectsDisabledItem() {
+    let target = MenuActionTarget()
+    let item = NSMenuItem(title: "Off", action: #selector(MenuActionTarget.fire(_:)), keyEquivalent: "")
+    item.target = target
+    item.isEnabled = false
+
+    #expect(!GhosttySurfaceView.performMenuItem(item))
+    #expect(!target.fired)
+  }
+
+  @Test func performMenuItemRejectsItemWithoutAction() {
+    let item = NSMenuItem(title: "Inert", action: nil, keyEquivalent: "")
+    item.isEnabled = true
+
+    #expect(!GhosttySurfaceView.performMenuItem(item))
+  }
+
+  @Test func dispatchForwardableChordFiresResolvedItemDirectlyOnConflict() {
+    // A custom `close_surface` on ⌘M shares the chord with Minimize: dispatch must fire the resolved
+    // app item directly (so its explicit-close action runs) instead of the native path, which could
+    // fire Minimize.
+    let target = MenuActionTarget()
+    let event = Self.keyEvent(chars: "m", ignoringModifiers: "m", modifiers: [.command])
+    let menu = NSMenu()
+    menu.autoenablesItems = false
+    let appItem = NSMenuItem(title: "Close", action: #selector(MenuActionTarget.fire(_:)), keyEquivalent: "m")
+    appItem.keyEquivalentModifierMask = [.command]
+    appItem.target = target
+    appItem.isEnabled = true
+    menu.addItem(appItem)
+    menu.addItem(Self.item(action: #selector(NSWindow.performMiniaturize(_:)), keyEquivalent: "m", mask: [.command]))
+
+    #expect(GhosttySurfaceView.dispatchForwardableChord(appItem, for: event, in: menu))
+    #expect(target.fired)
+  }
+
+  @Test func isSystemManagedMenuItemClassifiesActions() {
+    let hideOthers = NSMenuItem(
+      title: "Hide Others",
+      action: #selector(NSApplication.hideOtherApplications(_:)),
+      keyEquivalent: ""
+    )
+    #expect(GhosttySurfaceView.isSystemManagedMenuItem(hideOthers))
+
+    let appOwned = NSMenuItem(title: "Custom", action: Selector(("appOwnedAction:")), keyEquivalent: "")
+    #expect(!GhosttySurfaceView.isSystemManagedMenuItem(appOwned))
+
+    let noAction = NSMenuItem(title: "Inert", action: nil, keyEquivalent: "")
+    #expect(!GhosttySurfaceView.isSystemManagedMenuItem(noAction))
+  }
+
   @Test func reportedSurfaceSizeUsesScrollContentWidth() {
     #expect(
       GhosttySurfaceScrollView.reportedSurfaceSize(
diff --git a/supacodeTests/GitClientRemoteSSHTests.swift b/supacodeTests/GitClientRemoteSSHTests.swift
new file mode 100644
index 000000000..94c22f878
--- /dev/null
+++ b/supacodeTests/GitClientRemoteSSHTests.swift
@@ -0,0 +1,290 @@
+import Foundation
+import Testing
+
+@testable import SupacodeSettingsShared
+@testable import supacode
+
+/// Asserts that a `GitClient` built on `ShellClient.ssh(host:)` rewrites a
+/// worktree-create shell-out into the expected `ssh <host> <remoteCommand>`
+/// wire invocation. The recorder stands in for the local `ssh` process so the
+/// concatenation is checked without a real connection.
+struct GitClientRemoteSSHTests {
+  @Test func createWorktreeStreamOverSSHWrapsTheWtInvocation() async throws {
+    let recorder = GitShellInvocationRecorder()
+    let base = ShellClient(
+      run: { _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) },
+      runLoginImpl: { _, _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) },
+      runStream: { executableURL, arguments, currentDirectoryURL in
+        recorder.record(
+          executableURL: executableURL,
+          arguments: arguments,
+          currentDirectoryURL: currentDirectoryURL
+        )
+        return AsyncThrowingStream { continuation in
+          continuation.yield(.line(ShellStreamLine(source: .stdout, text: "/tmp/repo/swift-otter")))
+          continuation.yield(.finished(ShellOutput(stdout: "/tmp/repo/swift-otter", stderr: "", exitCode: 0)))
+          continuation.finish()
+        }
+      },
+      runLoginStreamImpl: { _, _, _, _ in
+        AsyncThrowingStream { continuation in
+          continuation.yield(.finished(ShellOutput(stdout: "", stderr: "", exitCode: 0)))
+          continuation.finish()
+        }
+      }
+    )
+    let client = GitClient(shell: .ssh(host: RemoteHost(alias: "devbox"), base: base))
+
+    for try await _ in client.createWorktreeStream(
+      named: "swift-otter",
+      in: URL(fileURLWithPath: "/tmp/repo"),
+      baseDirectory: URL(fileURLWithPath: "/tmp/repo/.worktrees"),
+      copyFiles: (ignored: false, untracked: false),
+      baseRef: "origin/main"
+    ) {}
+
+    let snapshot = recorder.snapshot()
+    // The transport spawns `ssh`, not the local tool, and drops the cwd (the
+    // working directory becomes a remote `cd` inside the remote command).
+    #expect(snapshot.executableURL == URL(fileURLWithPath: "/usr/bin/ssh"))
+    #expect(snapshot.currentDirectoryURL == nil)
+
+    // Fixed multiplexing options + destination precede the single remote-command arg.
+    #expect(
+      Array(snapshot.arguments.prefix(7)) == [
+        "-o", "ControlMaster=auto",
+        "-o", "ControlPath=~/.ssh/supacode-%C",
+        "-o", "ControlPersist=10m",
+        "devbox",
+      ]
+    )
+    #expect(snapshot.arguments.count == 8)
+
+    // The single remote arg is login-shell wrapped (so Homebrew's PATH is on
+    // the remote); the payload carries `cd -- <repoRoot> && exec … <wt> …`.
+    // The wrapping re-quotes the inner single-quotes, so assert on bare tokens.
+    let wrapped = snapshot.arguments[7]
+    #expect(wrapped.hasPrefix("exec \"$SHELL\" -l -c "))
+    #expect(wrapped.contains("cd -- "))
+    #expect(wrapped.contains("/tmp/repo"))
+    #expect(wrapped.contains("LANG=C"))
+    #expect(wrapped.contains("--base-dir"))
+    #expect(wrapped.contains("/tmp/repo/.worktrees"))
+    #expect(wrapped.contains("sw"))
+    #expect(wrapped.contains("--from"))
+    #expect(wrapped.contains("origin/main"))
+    #expect(wrapped.contains("swift-otter"))
+  }
+
+  @Test func createGitWorktreeOverSSHRunsWorktreeAdd() async throws {
+    let recorder = GitShellInvocationRecorder()
+    let base = ShellClient(
+      run: { exe, args, cwd in
+        recorder.record(executableURL: exe, arguments: args, currentDirectoryURL: cwd)
+        return ShellOutput(stdout: "", stderr: "", exitCode: 0)
+      },
+      runLoginImpl: { _, _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) }
+    )
+    let client = GitClient(shell: .ssh(host: RemoteHost(alias: "devbox"), base: base))
+
+    try await client.createGitWorktree(
+      in: URL(fileURLWithPath: "/repo"),
+      name: "swift-otter",
+      baseRef: "HEAD",
+      worktreePath: URL(fileURLWithPath: "/swift-otter")
+    )
+
+    let snapshot = recorder.snapshot()
+    #expect(snapshot.executableURL == URL(fileURLWithPath: "/usr/bin/ssh"))
+    let wrapped = snapshot.arguments.last ?? ""
+    #expect(wrapped.hasPrefix("exec \"$SHELL\" -l -c "))
+    #expect(wrapped.contains("git"))
+    #expect(wrapped.contains("worktree"))
+    #expect(wrapped.contains("add"))
+    #expect(wrapped.contains("-b"))
+    #expect(wrapped.contains("swift-otter"))
+    #expect(wrapped.contains("/swift-otter"))
+    #expect(wrapped.contains("HEAD"))
+  }
+
+  @Test func removeWorktreeOverSSHRunsForcedWorktreeRemoveOnHost() async throws {
+    let recorder = GitShellInvocationRecorder()
+    let base = ShellClient(
+      run: { exe, args, cwd in
+        recorder.record(executableURL: exe, arguments: args, currentDirectoryURL: cwd)
+        return ShellOutput(stdout: "", stderr: "", exitCode: 0)
+      },
+      runLoginImpl: { _, _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) }
+    )
+    let host = RemoteHost(alias: "devbox")
+    let client = GitClient(shell: .ssh(host: host, base: base))
+    let worktree = Worktree(
+      id: "devbox:/repo/wt",
+      name: "wt",
+      detail: "",
+      workingDirectory: URL(fileURLWithPath: "/repo/wt"),
+      repositoryRootURL: URL(fileURLWithPath: "/repo"),
+      host: host
+    )
+
+    _ = try await client.removeWorktree(worktree, deleteBranch: false)
+
+    // The removal runs `git worktree remove --force --force <path>` on the host,
+    // not against the local checkout.
+    let snapshot = recorder.snapshot()
+    #expect(snapshot.executableURL == URL(fileURLWithPath: "/usr/bin/ssh"))
+    let wrapped = snapshot.arguments.last ?? ""
+    #expect(wrapped.contains("worktree"))
+    #expect(wrapped.contains("remove"))
+    #expect(wrapped.contains("--force"))
+    #expect(wrapped.contains("/repo/wt"))
+  }
+
+  @Test func removeWorktreeOverSSHThrowsWhenHostRemoveFails() async throws {
+    // The host remove is the only deletion for a remote worktree (no local
+    // trash fallback), so a failure must surface instead of reporting success
+    // and orphaning the worktree on the host.
+    let host = RemoteHost(alias: "devbox")
+    let base = ShellClient(
+      run: { _, _, _ in
+        throw ShellClientError(
+          command: "ssh",
+          stdout: "",
+          stderr: "ssh: connect to host devbox port 22: Connection refused",
+          exitCode: 255
+        )
+      },
+      runLoginImpl: { _, _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) }
+    )
+    let client = GitClient(shell: .ssh(host: host, base: base))
+    let worktree = Worktree(
+      id: "devbox:/repo/wt",
+      name: "wt",
+      detail: "",
+      workingDirectory: URL(fileURLWithPath: "/repo/wt"),
+      repositoryRootURL: URL(fileURLWithPath: "/repo"),
+      host: host
+    )
+
+    await #expect(throws: (any Error).self) {
+      _ = try await client.removeWorktree(worktree, deleteBranch: false)
+    }
+  }
+
+  @Test func removeWorktreeOverSSHTreatsAlreadyGoneAsSuccess() async throws {
+    // An entry already removed on the host is idempotent success, not a failure.
+    let host = RemoteHost(alias: "devbox")
+    let base = ShellClient(
+      run: { _, _, _ in
+        throw ShellClientError(
+          command: "ssh",
+          stdout: "",
+          stderr: "fatal: '/repo/wt' is not a working tree",
+          exitCode: 128
+        )
+      },
+      runLoginImpl: { _, _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) }
+    )
+    let client = GitClient(shell: .ssh(host: host, base: base))
+    let worktree = Worktree(
+      id: "devbox:/repo/wt",
+      name: "wt",
+      detail: "",
+      workingDirectory: URL(fileURLWithPath: "/repo/wt"),
+      repositoryRootURL: URL(fileURLWithPath: "/repo"),
+      host: host
+    )
+
+    let removed = try await client.removeWorktree(worktree, deleteBranch: false)
+    #expect(removed == URL(fileURLWithPath: "/repo/wt"))
+  }
+
+  @Test func removeWorktreeLeavesLocalFilesystemUntouchedForRemote() async throws {
+    // The core invariant the branded location model exists to guarantee: a
+    // remote worktree removal never touches a local directory that happens to
+    // sit at the same absolute path.
+    let fileManager = FileManager.default
+    let localDirectory =
+      fileManager.temporaryDirectory
+      .appending(path: "supacode-remote-remove-\(UUID().uuidString)", directoryHint: .isDirectory)
+    try fileManager.createDirectory(at: localDirectory, withIntermediateDirectories: true)
+    defer { try? fileManager.removeItem(at: localDirectory) }
+
+    let host = RemoteHost(alias: "devbox")
+    let base = ShellClient(
+      run: { _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) },
+      runLoginImpl: { _, _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) }
+    )
+    let client = GitClient(shell: .ssh(host: host, base: base))
+    let worktree = Worktree(
+      id: WorktreeID("devbox:\(localDirectory.path(percentEncoded: false))"),
+      name: "wt",
+      detail: "",
+      workingDirectory: localDirectory,
+      repositoryRootURL: URL(fileURLWithPath: "/repo"),
+      host: host
+    )
+
+    _ = try await client.removeWorktree(worktree, deleteBranch: false)
+
+    // Relocate-to-trash *moves* the directory, so it still existing in place is
+    // proof the local filesystem path was never touched.
+    #expect(fileManager.fileExists(atPath: localDirectory.path(percentEncoded: false)))
+  }
+
+  @Test func parseWorktreePorcelainParsesBranchDetachedAndSkipsBare() {
+    let output = """
+      bare
+
+      worktree /repo
+      HEAD aaa
+      branch refs/heads/main
+
+      worktree /repo/wt-feature
+      HEAD bbb
+      branch refs/heads/feature
+
+      worktree /repo/wt-detached
+      HEAD ccc
+      detached
+      """
+    let worktrees = GitClient.parseWorktreePorcelain(output, repositoryRootURL: URL(fileURLWithPath: "/repo"))
+    // The leading `bare` block is skipped.
+    #expect(worktrees.count == 3)
+    #expect(worktrees[0].name == "main")
+    #expect(worktrees[0].isAttached)
+    #expect(worktrees[1].name == "feature")
+    #expect(worktrees[1].id == "/repo/wt-feature")
+    // Detached worktree: not attached, name falls back to the dir leaf.
+    #expect(worktrees[2].isAttached == false)
+    #expect(worktrees[2].name == "wt-detached")
+    // Remote paths aren't stat'd locally.
+    #expect(worktrees.allSatisfy { !$0.isMissing })
+  }
+
+  @Test func gitWorktreesOverSSHRunsPorcelainListAndParses() async throws {
+    let recorder = GitShellInvocationRecorder()
+    let base = ShellClient(
+      run: { exe, args, cwd in
+        recorder.record(executableURL: exe, arguments: args, currentDirectoryURL: cwd)
+        return ShellOutput(stdout: "worktree /repo\nHEAD abc\nbranch refs/heads/main\n", stderr: "", exitCode: 0)
+      },
+      runLoginImpl: { _, _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) }
+    )
+    let client = GitClient(shell: .ssh(host: RemoteHost(alias: "devbox"), base: base))
+
+    let worktrees = try await client.gitWorktrees(for: URL(fileURLWithPath: "/repo"))
+    #expect(worktrees.count == 1)
+    #expect(worktrees[0].name == "main")
+
+    // The wire command is `ssh devbox 'exec "$SHELL" -l -c …git worktree list --porcelain…'`.
+    let snapshot = recorder.snapshot()
+    #expect(snapshot.executableURL == URL(fileURLWithPath: "/usr/bin/ssh"))
+    let wrapped = snapshot.arguments.last ?? ""
+    #expect(wrapped.hasPrefix("exec \"$SHELL\" -l -c "))
+    #expect(wrapped.contains("git"))
+    #expect(wrapped.contains("worktree"))
+    #expect(wrapped.contains("list"))
+    #expect(wrapped.contains("--porcelain"))
+  }
+}
diff --git a/supacodeTests/GitClientSupacodeLockTests.swift b/supacodeTests/GitClientSupacodeLockTests.swift
index ead440877..af9dea988 100644
--- a/supacodeTests/GitClientSupacodeLockTests.swift
+++ b/supacodeTests/GitClientSupacodeLockTests.swift
@@ -90,7 +90,7 @@ struct GitClientSupacodeLockTests {
     let adminDir = fixture.adminDirectory(for: "feature-remove")
     GitClient.writeSupacodeLock(at: adminDir)
     let worktree = Worktree(
-      id: worktreeURL.path(percentEncoded: false),
+      id: WorktreeID(worktreeURL.path(percentEncoded: false)),
       name: "feature-remove",
       detail: "feature-remove",
       workingDirectory: worktreeURL,
@@ -111,7 +111,7 @@ struct GitClientSupacodeLockTests {
     GitClient.writeSupacodeLock(at: adminDir)
     try FileManager.default.removeItem(at: worktreeURL)
     let worktree = Worktree(
-      id: worktreeURL.path(percentEncoded: false),
+      id: WorktreeID(worktreeURL.path(percentEncoded: false)),
       name: "feature-orphan-delete",
       detail: "feature-orphan-delete",
       workingDirectory: worktreeURL,
@@ -133,7 +133,7 @@ struct GitClientSupacodeLockTests {
     GitClient.writeSupacodeLock(at: adminDir)
     try FileManager.default.removeItem(at: worktreeURL)
     let worktree = Worktree(
-      id: worktreeURL.path(percentEncoded: false),
+      id: WorktreeID(worktreeURL.path(percentEncoded: false)),
       name: "feature-orphan-branch",
       detail: "feature-orphan-branch",
       workingDirectory: worktreeURL,
diff --git a/supacodeTests/GitClientWorktreeDiscoveryTests.swift b/supacodeTests/GitClientWorktreeDiscoveryTests.swift
index e2a0b2b04..ac775b702 100644
--- a/supacodeTests/GitClientWorktreeDiscoveryTests.swift
+++ b/supacodeTests/GitClientWorktreeDiscoveryTests.swift
@@ -173,9 +173,9 @@ struct GitClientWorktreeDiscoveryTests {
     let worktrees = try await client.worktrees(for: repoURL)
     let byID = Dictionary(uniqueKeysWithValues: worktrees.map { ($0.id, $0) })
 
-    #expect(byID[repoPath]?.isMissing == false)
-    #expect(byID[livePath]?.isMissing == false)
-    #expect(byID[missingPath]?.isMissing == true)
+    #expect(byID[WorktreeID(repoPath)]?.isMissing == false)
+    #expect(byID[WorktreeID(livePath)]?.isMissing == false)
+    #expect(byID[WorktreeID(missingPath)]?.isMissing == true)
   }
 
   @Test func repoRootFallsBackToLoginShellWhenDirectExecutionCannotResolveGit() async throws {
diff --git a/supacodeTests/GithubCLIClientTests.swift b/supacodeTests/GithubCLIClientTests.swift
index de5973792..051448fa2 100644
--- a/supacodeTests/GithubCLIClientTests.swift
+++ b/supacodeTests/GithubCLIClientTests.swift
@@ -543,6 +543,297 @@ struct GithubCLIClientTests {
     #expect(snapshot.ghCallCount == 2)
     #expect(snapshot.loginCallCount == 2)
   }
+
+  // MARK: - Noisy login-shell output (#377)
+
+  // A ShellClient that resolves `gh` via `which` and returns `stdout` for every gh invocation.
+  static func ghShell(stdout: String) -> ShellClient {
+    ShellClient(
+      run: { executableURL, _, _ in
+        executableURL.lastPathComponent == "which"
+          ? ShellOutput(stdout: "/usr/bin/gh", stderr: "", exitCode: 0)
+          : ShellOutput(stdout: "", stderr: "", exitCode: 0)
+      },
+      runLoginImpl: { executableURL, _, _, _ in
+        guard executableURL.lastPathComponent == "gh" else {
+          return ShellOutput(stdout: "", stderr: "", exitCode: 0)
+        }
+        return ShellOutput(stdout: stdout, stderr: "", exitCode: 0)
+      }
+    )
+  }
+
+  @Test func balancedSpansReturnsCleanObjectUnchanged() {
+    #expect(GithubCLIOutput.balancedJSONSpans(in: #"{"a":1}"#).map(String.init) == [#"{"a":1}"#])
+  }
+
+  @Test func balancedSpansStripBannerBeforeObject() {
+    let noisy = "fastfetch banner line\nanother line\n" + #"{"hosts":{}}"#
+    #expect(GithubCLIOutput.balancedJSONSpans(in: noisy).map(String.init) == [#"{"hosts":{}}"#])
+  }
+
+  @Test func balancedSpansStripBannerBeforeArray() {
+    let noisy = "nvm: now using node v20\n" + #"[{"x":1},{"y":2}]"#
+    #expect(GithubCLIOutput.balancedJSONSpans(in: noisy).map(String.init) == [#"[{"x":1},{"y":2}]"#])
+  }
+
+  @Test func balancedSpansDropTrailingNoise() {
+    #expect(GithubCLIOutput.balancedJSONSpans(in: "{\"a\":1}\nshell goodbye").map(String.init) == [#"{"a":1}"#])
+  }
+
+  @Test func balancedSpansIgnoreBracesInsideStrings() {
+    #expect(GithubCLIOutput.balancedJSONSpans(in: #"{"a":"}]"}"#).map(String.init) == [#"{"a":"}]"}"#])
+  }
+
+  @Test func balancedSpansIgnoreEscapedQuoteInsideString() {
+    // The escaped quote keeps the scanner in-string, so the brace before it is not a premature close.
+    #expect(GithubCLIOutput.balancedJSONSpans(in: #"{"a":"}\""}"#).map(String.init) == [#"{"a":"}\""}"#])
+  }
+
+  @Test func balancedSpansReturnBothTopLevelObjectsInOrder() {
+    let input = #"{"a":1}"# + "\n" + #"{"b":2}"#
+    #expect(GithubCLIOutput.balancedJSONSpans(in: input).map(String.init) == [#"{"a":1}"#, #"{"b":2}"#])
+  }
+
+  @Test func balancedSpansSkipUnbalancedOpener() {
+    // A stray brace from a verbose login shell must not swallow the real trailing payload.
+    let noisy = "chpwd () {\n" + #"[{"databaseId":7}]"#
+    #expect(GithubCLIOutput.balancedJSONSpans(in: noisy).map(String.init) == [#"[{"databaseId":7}]"#])
+  }
+
+  @Test func balancedSpansReturnEmptyForPureNoise() {
+    #expect(GithubCLIOutput.balancedJSONSpans(in: "no json here at all").isEmpty)
+  }
+
+  @Test func balancedSpansReturnEmptyForEmptyInput() {
+    #expect(GithubCLIOutput.balancedJSONSpans(in: "   \n  ").isEmpty)
+  }
+
+  @Test func balancedSpansReturnEmptyForUnterminatedPayload() {
+    #expect(GithubCLIOutput.balancedJSONSpans(in: #"{"a":1"#).isEmpty)
+  }
+
+  private struct SingleKeyPayload: Decodable, Equatable {
+    let value: Int
+  }
+
+  @Test func decodeSkipsBracketBearingBannerBeforeObject() throws {
+    let noisy = "warn [deprecated]\n" + #"{"value":1}"#
+    let decoded = try GithubCLIOutput.decode(SingleKeyPayload.self, from: noisy)
+    #expect(decoded == SingleKeyPayload(value: 1))
+  }
+
+  @Test func decodeSkipsVersionManagerBannerBeforeObject() throws {
+    let noisy = "[nvm] using node v20\n" + #"{"hosts":{}}"#
+    let decoded = try GithubCLIOutput.decode(GithubAuthStatusResponse.self, from: noisy)
+    #expect(decoded.hosts.isEmpty)
+  }
+
+  @Test func activeAccountScansAllHostsForActiveAccount() {
+    let response = GithubAuthStatusResponse(hosts: [
+      "ghe.acme.com": [.init(active: false, login: "work")],
+      "github.com": [.init(active: true, login: "sbertix")],
+    ])
+
+    let active = GithubAuthStatusParsing.activeAccount(in: response)
+
+    #expect(active?.host == "github.com")
+    #expect(active?.login == "sbertix")
+  }
+
+  @Test func activeAccountReturnsNilWhenNoAccountActive() {
+    let response = GithubAuthStatusResponse(hosts: [
+      "github.com": [.init(active: false, login: "sbertix")]
+    ])
+
+    #expect(GithubAuthStatusParsing.activeAccount(in: response) == nil)
+  }
+
+  @Test func activeAccountPrefersGithubComWhenMultipleHostsActive() {
+    let response = GithubAuthStatusResponse(hosts: [
+      "ghe.acme.com": [.init(active: true, login: "work")],
+      "github.com": [.init(active: true, login: "sbertix")],
+    ])
+
+    let active = GithubAuthStatusParsing.activeAccount(in: response)
+
+    #expect(active?.host == "github.com")
+    #expect(active?.login == "sbertix")
+  }
+
+  @Test func activeAccountSortsHostsWhenGithubComAbsent() {
+    let response = GithubAuthStatusResponse(hosts: [
+      "z.example.com": [.init(active: true, login: "zed")],
+      "a.example.com": [.init(active: true, login: "ann")],
+    ])
+
+    let active = GithubAuthStatusParsing.activeAccount(in: response)
+
+    #expect(active?.host == "a.example.com")
+    #expect(active?.login == "ann")
+  }
+
+  @Test func authStatusSucceedsDespiteBannerPollutedStdout() async throws {
+    let stdout =
+      "╭─ fastfetch ─╮\n│ os macOS    │\n╰─────────────╯\n"
+      + #"{"hosts":{"github.com":[{"state":"success","active":true,"host":"github.com","login":"sbertix"}]}}"#
+    let client = GithubCLIClient.live(shell: Self.ghShell(stdout: stdout))
+
+    let status = try await client.authStatus()
+
+    #expect(status == GithubAuthStatus(username: "sbertix", host: "github.com"))
+  }
+
+  @Test func authStatusReportsActiveAccountOnNonFirstHost() async throws {
+    let stdout = #"""
+      {"hosts":{"ghe.acme.com":[{"active":false,"login":"work"}],"github.com":[{"active":true,"login":"sbertix"}]}}
+      """#
+    let client = GithubCLIClient.live(shell: Self.ghShell(stdout: stdout))
+
+    let status = try await client.authStatus()
+
+    #expect(status == GithubAuthStatus(username: "sbertix", host: "github.com"))
+  }
+
+  @Test func authStatusThrowsCommandFailedOnNonJsonOutput() async {
+    let client = GithubCLIClient.live(shell: Self.ghShell(stdout: "command not found: gh"))
+
+    do {
+      _ = try await client.authStatus()
+      Issue.record("Expected authStatus to throw")
+    } catch GithubCLIError.commandFailed(let message) {
+      // No JSON payload -> the shell-pollution hypothesis, not a raw error.
+      #expect(message == GithubCLIOutput.noPayloadMessage)
+    } catch {
+      Issue.record("Unexpected error type: \(error.localizedDescription)")
+    }
+  }
+
+  @Test func authStatusThrowsUndecodableMessageWhenPayloadParsesButSchemaDiffers() async {
+    let client = GithubCLIClient.live(shell: Self.ghShell(stdout: #"{"unexpected":true}"#))
+
+    do {
+      _ = try await client.authStatus()
+      Issue.record("Expected authStatus to throw")
+    } catch GithubCLIError.commandFailed(let message) {
+      // Found JSON but it failed to decode -> the version-incompatibility hypothesis.
+      #expect(message == GithubCLIOutput.undecodableMessage)
+    } catch {
+      Issue.record("Unexpected error type: \(error.localizedDescription)")
+    }
+  }
+
+  @Test func resolveRemoteInfoSucceedsDespiteBannerPollutedStdout() async {
+    let stdout =
+      "loading shell profile…\n"
+      + #"{"name":"upstream-repo","owner":{"login":"upstream-org"},"#
+      + #""url":"https://github.com/upstream-org/upstream-repo"}"#
+    let client = GithubCLIClient.live(shell: Self.ghShell(stdout: stdout))
+
+    let info = await client.resolveRemoteInfo(URL(fileURLWithPath: "/tmp/repo"))
+
+    #expect(info == GithubRemoteInfo(host: "github.com", owner: "upstream-org", repo: "upstream-repo"))
+  }
+
+  @Test func defaultBranchSucceedsDespiteBannerPollutedStdout() async throws {
+    let stdout = "conda activate base\n" + #"{"defaultBranchRef":{"name":"main"}}"#
+    let client = GithubCLIClient.live(shell: Self.ghShell(stdout: stdout))
+
+    let branch = try await client.defaultBranch(URL(fileURLWithPath: "/tmp/repo"))
+
+    #expect(branch == "main")
+  }
+
+  @Test func defaultBranchThrowsCommandFailedOnNonJsonOutput() async {
+    let client = GithubCLIClient.live(shell: Self.ghShell(stdout: "not a repo"))
+
+    do {
+      _ = try await client.defaultBranch(URL(fileURLWithPath: "/tmp/repo"))
+      Issue.record("Expected defaultBranch to throw")
+    } catch GithubCLIError.commandFailed {
+      // Expected.
+    } catch {
+      Issue.record("Unexpected error type: \(error.localizedDescription)")
+    }
+  }
+
+  @Test func latestRunSucceedsDespiteBannerPollutedArray() async throws {
+    let stdout =
+      "pyenv: version 3.12\n"
+      + #"[{"databaseId":7,"workflowName":"CI","name":"CI","displayTitle":"Fix","#
+      + #""status":"completed","conclusion":"success","#
+      + #""createdAt":"2026-05-01T00:00:00Z","updatedAt":"2026-05-01T00:00:00Z"}]"#
+    let client = GithubCLIClient.live(shell: Self.ghShell(stdout: stdout))
+
+    let run = try await client.latestRun(URL(fileURLWithPath: "/tmp/repo"), "main")
+
+    #expect(run?.databaseId == 7)
+    #expect(run?.conclusion == "success")
+  }
+
+  @Test func latestRunReturnsNilForEmptyOutput() async throws {
+    let client = GithubCLIClient.live(shell: Self.ghShell(stdout: ""))
+
+    let run = try await client.latestRun(URL(fileURLWithPath: "/tmp/repo"), "main")
+
+    #expect(run == nil)
+  }
+
+  @Test func latestRunReturnsNilForBannerWithNoRuns() async throws {
+    // Banner-only stdout with no JSON payload means no runs, not a parse failure.
+    let client = GithubCLIClient.live(shell: Self.ghShell(stdout: "shell banner with no json"))
+
+    let run = try await client.latestRun(URL(fileURLWithPath: "/tmp/repo"), "main")
+
+    #expect(run == nil)
+  }
+
+  @Test func latestRunThrowsCommandFailedOnPresentButUndecodablePayload() async {
+    let client = GithubCLIClient.live(shell: Self.ghShell(stdout: #"[{"databaseId":"not-an-int"}]"#))
+
+    do {
+      _ = try await client.latestRun(URL(fileURLWithPath: "/tmp/repo"), "main")
+      Issue.record("Expected latestRun to throw on a present-but-undecodable payload")
+    } catch GithubCLIError.commandFailed {
+      // Expected: a JSON payload that fails to decode is a real parse failure.
+    } catch {
+      Issue.record("Unexpected error type: \(error.localizedDescription)")
+    }
+  }
+
+  @Test func latestRunSkipsStrayBraceBannerBeforeRunArray() async throws {
+    // A stray unbalanced brace (e.g. a `set -x` trace) must not swallow the real run array.
+    let stdout = "+ chpwd () {\n" + #"[{"databaseId":11,"status":"completed"}]"#
+    let client = GithubCLIClient.live(shell: Self.ghShell(stdout: stdout))
+
+    let run = try await client.latestRun(URL(fileURLWithPath: "/tmp/repo"), "main")
+
+    #expect(run?.databaseId == 11)
+  }
+
+  @Test func latestRunPrefersRealArrayOverLeadingEmptyArrayBanner() async throws {
+    // A leading `[]` from shell noise must not shadow the real run list that follows.
+    let stdout = "[]\n" + #"[{"databaseId":9,"status":"completed","conclusion":"success"}]"#
+    let client = GithubCLIClient.live(shell: Self.ghShell(stdout: stdout))
+
+    let run = try await client.latestRun(URL(fileURLWithPath: "/tmp/repo"), "main")
+
+    #expect(run?.databaseId == 9)
+  }
+
+  @Test func authStatusReportsPollutionForBracketNoiseWithoutValidJson() async {
+    // Brackets that are not valid JSON (e.g. `[INFO]` log prefixes) are shell noise, not schema drift.
+    let client = GithubCLIClient.live(shell: Self.ghShell(stdout: "[INFO] starting up\n[WARN] no config"))
+
+    do {
+      _ = try await client.authStatus()
+      Issue.record("Expected authStatus to throw")
+    } catch GithubCLIError.commandFailed(let message) {
+      #expect(message == GithubCLIOutput.noPayloadMessage)
+    } catch {
+      Issue.record("Unexpected error type: \(error.localizedDescription)")
+    }
+  }
 }
 
 nonisolated private func graphQLResponse(for arguments: [String]) -> String {
diff --git a/supacodeTests/KiroSettingsInstallerTests.swift b/supacodeTests/KiroSettingsInstallerTests.swift
index 7cdf9e51f..e7c3290c3 100644
--- a/supacodeTests/KiroSettingsInstallerTests.swift
+++ b/supacodeTests/KiroSettingsInstallerTests.swift
@@ -14,9 +14,9 @@ struct KiroSettingsInstallerTests {
 
   private func makeInstaller(
     homeURL: URL,
-    versionOutput: String = "kiro 1.0.0",
+    versionOutput: String = "kiro-cli 2.0.0",
     versionStatus: Int32 = 0,
-    versionError: Error? = nil
+    versionError: Error? = nil,
   ) -> KiroSettingsInstaller {
     KiroSettingsInstaller(
       homeDirectoryURL: homeURL,
@@ -168,8 +168,8 @@ struct KiroSettingsInstallerTests {
     let homeURL = makeTempHomeURL()
     defer { try? fileManager.removeItem(at: homeURL) }
 
-    let installer = makeInstaller(homeURL: homeURL, versionOutput: "kiro 2.0.0")
-    await #expect(throws: KiroSettingsInstallerError.unsupportedKiroVersion("2.0.0")) {
+    let installer = makeInstaller(homeURL: homeURL, versionOutput: "kiro-cli 3.0.0")
+    await #expect(throws: KiroSettingsInstallerError.unsupportedKiroVersion("3.0.0")) {
       try await installer.installAllHooks()
     }
   }
@@ -206,9 +206,9 @@ struct KiroSettingsInstallerTests {
     let homeURL = makeTempHomeURL()
     defer { try? fileManager.removeItem(at: homeURL) }
 
-    let installer = makeInstaller(homeURL: homeURL, versionOutput: "kiro 10.0.0")
+    let installer = makeInstaller(homeURL: homeURL, versionOutput: "kiro-cli 20.0.0")
     await #expect(
-      throws: KiroSettingsInstallerError.unsupportedKiroVersion("10.0.0")
+      throws: KiroSettingsInstallerError.unsupportedKiroVersion("20.0.0")
     ) {
       try await installer.installAllHooks()
     }
@@ -219,14 +219,14 @@ struct KiroSettingsInstallerTests {
     defer { try? fileManager.removeItem(at: homeURL) }
 
     // Login shells can print their own banners to stderr; parsing must prefer
-    // stdout so a stderr "Python 3.11" banner does not reject valid Kiro 1.x.
+    // stdout so a stderr "Python 3.11" banner does not reject valid Kiro 2.x.
     let installer = KiroSettingsInstaller(
       homeDirectoryURL: homeURL,
       fileManager: fileManager,
       runKiroVersionCommand: {
         .init(
           status: 0,
-          standardOutput: "kiro 1.2.3\n",
+          standardOutput: "kiro-cli 2.5.0\n",
           standardError: "Python 3.11.0 (banner)",
         )
       },
@@ -256,6 +256,7 @@ struct KiroSettingsInstallerTests {
   }
 
   @Test func extractVersionHandlesCommonFormats() {
+    #expect(KiroSettingsInstaller.extractVersion(from: "kiro-cli 2.5.0") == "2.5.0")
     #expect(KiroSettingsInstaller.extractVersion(from: "kiro 1.2.3") == "1.2.3")
     #expect(KiroSettingsInstaller.extractVersion(from: "Kiro CLI v1.0.0 (build abcd)") == "1.0.0")
     #expect(KiroSettingsInstaller.extractVersion(from: "1.4") == "1.4")
diff --git a/supacodeTests/LayoutsIncrementalWriterTests.swift b/supacodeTests/LayoutsIncrementalWriterTests.swift
new file mode 100644
index 000000000..333f11821
--- /dev/null
+++ b/supacodeTests/LayoutsIncrementalWriterTests.swift
@@ -0,0 +1,138 @@
+import Dependencies
+import Foundation
+import SupacodeSettingsShared
+import Testing
+
+@testable import supacode
+
+@MainActor
+struct LayoutsIncrementalWriterTests {
+  private func snapshot(dir: String) -> TerminalLayoutSnapshot {
+    TerminalLayoutSnapshot(
+      tabs: [
+        TerminalLayoutSnapshot.TabSnapshot(
+          id: nil,
+          title: "Terminal 1",
+          customTitle: nil,
+          icon: nil,
+          tintColor: nil,
+          layout: .leaf(
+            TerminalLayoutSnapshot.SurfaceSnapshot(id: nil, workingDirectory: dir)
+          ),
+          focusedLeafIndex: 0
+        )
+      ],
+      selectedTabIndex: 0
+    )
+  }
+
+  private func readDict(_ storage: SettingsFileStorage, _ url: URL) -> [String: TerminalLayoutSnapshot] {
+    guard let data = try? storage.load(url) else { return [:] }
+    return (try? JSONDecoder().decode([String: TerminalLayoutSnapshot].self, from: data)) ?? [:]
+  }
+
+  @Test func separateFlushesBothSurvive() async {
+    let storage = SettingsFileStorage.inMemory()
+    let url = SupacodePaths.layoutsURL
+    let writer = LayoutsIncrementalWriter(storage: storage, url: url)
+
+    await writer.flush(["w1": .snapshot(snapshot(dir: "/w1"))])
+    await writer.flush(["w2": .snapshot(snapshot(dir: "/w2"))])
+
+    let dict = readDict(storage, url)
+    #expect(Set(dict.keys) == ["w1", "w2"])
+  }
+
+  @Test func deleteRemovesOnlyTargetKey() async {
+    let storage = SettingsFileStorage.inMemory()
+    let url = SupacodePaths.layoutsURL
+    let writer = LayoutsIncrementalWriter(storage: storage, url: url)
+
+    await writer.flush([
+      "w1": .snapshot(snapshot(dir: "/w1")),
+      "w2": .snapshot(snapshot(dir: "/w2")),
+    ])
+    await writer.flush(["w1": .delete])
+
+    let dict = readDict(storage, url)
+    #expect(Set(dict.keys) == ["w2"])
+  }
+
+  @Test func snapshotOverwritesSameKeyButPreservesOthers() async {
+    let storage = SettingsFileStorage.inMemory()
+    let url = SupacodePaths.layoutsURL
+    let writer = LayoutsIncrementalWriter(storage: storage, url: url)
+
+    await writer.flush([
+      "w1": .snapshot(snapshot(dir: "/old")),
+      "w2": .snapshot(snapshot(dir: "/w2")),
+    ])
+    await writer.flush(["w1": .snapshot(snapshot(dir: "/new"))])
+
+    let dict = readDict(storage, url)
+    #expect(dict["w2"] != nil)
+    let leaf = dict["w1"]?.tabs.first?.layout
+    if case .leaf(let surface) = leaf {
+      #expect(surface.workingDirectory == "/new")
+    } else {
+      Issue.record("Expected a leaf layout for w1")
+    }
+  }
+
+  @Test func identicalReflushSkipsTheWrite() async {
+    let inner = SettingsFileStorage.inMemory()
+    let url = SupacodePaths.layoutsURL
+    let saveCount = LockIsolated(0)
+    let storage = SettingsFileStorage(
+      load: { try inner.load($0) },
+      save: { data, target in
+        if target == url { saveCount.withValue { $0 += 1 } }
+        try inner.save(data, target)
+      }
+    )
+    let writer = LayoutsIncrementalWriter(storage: storage, url: url)
+
+    await writer.flush(["w1": .snapshot(snapshot(dir: "/w1"))])
+    // Re-splicing the same snapshot is a no-op; the second flush must not write.
+    await writer.flush(["w1": .snapshot(snapshot(dir: "/w1"))])
+
+    #expect(saveCount.value == 1)
+    #expect(Set(readDict(storage, url).keys) == ["w1"])
+  }
+
+  @Test func corruptFileIsRotatedAsideAndPersistenceRecovers() async throws {
+    let dir = URL(fileURLWithPath: NSTemporaryDirectory())
+      .appending(path: "LayoutsWriterCorrupt-\(UUID().uuidString)", directoryHint: .isDirectory)
+    try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+    defer { try? FileManager.default.removeItem(at: dir) }
+    let url = dir.appending(path: "layouts.json", directoryHint: .notDirectory)
+    // Seed garbage so the decode fails on the next merge read.
+    try Data("not json".utf8).write(to: url)
+
+    let storage = SettingsFileStorage(
+      load: { try Data(contentsOf: $0) },
+      save: { data, target in try data.write(to: target, options: .atomic) }
+    )
+    let writer = LayoutsIncrementalWriter(storage: storage, url: url)
+    await writer.flush(["w1": .snapshot(snapshot(dir: "/w1"))])
+
+    // Self-healed: the new key persisted instead of the flush aborting forever.
+    #expect(readDict(storage, url)["w1"] != nil)
+    // The corrupt bytes were preserved under a rotated name, not overwritten.
+    let rotated = try FileManager.default
+      .contentsOfDirectory(atPath: dir.path(percentEncoded: false))
+      .filter { $0.hasPrefix("layouts.json.corrupt-") }
+    #expect(rotated.count == 1)
+  }
+
+  @Test func emptyChangesIsNoOp() async {
+    let storage = SettingsFileStorage.inMemory()
+    let url = SupacodePaths.layoutsURL
+    let writer = LayoutsIncrementalWriter(storage: storage, url: url)
+
+    await writer.flush(["w1": .snapshot(snapshot(dir: "/w1"))])
+    await writer.flush([:])
+
+    #expect(Set(readDict(storage, url).keys) == ["w1"])
+  }
+}
diff --git a/supacodeTests/OpenCodePluginInstallerTests.swift b/supacodeTests/OpenCodePluginInstallerTests.swift
new file mode 100644
index 000000000..a7819a7c7
--- /dev/null
+++ b/supacodeTests/OpenCodePluginInstallerTests.swift
@@ -0,0 +1,158 @@
+import Foundation
+import Testing
+
+@testable import SupacodeSettingsShared
+@testable import supacode
+
+struct OpenCodePluginInstallerTests {
+  private let fileManager = FileManager.default
+
+  private func makeTempHomeURL() -> URL {
+    URL(fileURLWithPath: NSTemporaryDirectory())
+      .appendingPathComponent("supacode-opencode-plugin-\(UUID().uuidString)", isDirectory: true)
+  }
+
+  @Test func installWritesPluginFileWhenMissing() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = OpenCodePluginInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try installer.install()
+
+    #expect(fileManager.fileExists(atPath: installer.pluginFileURL.path))
+    let contents = try String(contentsOf: installer.pluginFileURL, encoding: .utf8)
+    #expect(contents == OpenCodePluginContent.source())
+  }
+
+  @Test func installIsIdempotent() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = OpenCodePluginInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try installer.install()
+    let first = try Data(contentsOf: installer.pluginFileURL)
+    try installer.install()
+    let second = try Data(contentsOf: installer.pluginFileURL)
+
+    #expect(first == second)
+  }
+
+  @Test func installStateNotInstalledBeforeInstall() {
+    let homeURL = makeTempHomeURL()
+    let installer = OpenCodePluginInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    #expect(installer.installState() == .notInstalled)
+  }
+
+  @Test func installStateInstalledAfterInstall() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = OpenCodePluginInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try installer.install()
+    #expect(installer.installState() == .installed)
+  }
+
+  @Test func installStateOutdatedWhenContentDiffers() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = OpenCodePluginInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try fileManager.createDirectory(
+      at: installer.pluginFileURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+    // A stale Supacode plugin (carries the ownership marker but differs).
+    try "// \(OpenCodePluginContent.ownershipMarker)\n// old shape"
+      .write(to: installer.pluginFileURL, atomically: true, encoding: .utf8)
+
+    #expect(installer.installState() == .outdated)
+  }
+
+  @Test func installStateNotInstalledForUnownedFileWithSameName() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = OpenCodePluginInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try fileManager.createDirectory(
+      at: installer.pluginFileURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+    // A user's own plugin at the same path must NOT report `.outdated` (which
+    // auto-update would overwrite) — it isn't Supacode's to manage.
+    try "export const NotSupacode = async () => ({})\n"
+      .write(to: installer.pluginFileURL, atomically: true, encoding: .utf8)
+
+    #expect(installer.installState() == .notInstalled)
+  }
+
+  @Test func uninstallRemovesOwnedPlugin() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = OpenCodePluginInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try installer.install()
+    try installer.uninstall()
+
+    #expect(!fileManager.fileExists(atPath: installer.pluginFileURL.path))
+    #expect(installer.installState() == .notInstalled)
+  }
+
+  @Test func uninstallPreservesUnownedFileWithSameName() throws {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = OpenCodePluginInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    try fileManager.createDirectory(
+      at: installer.pluginFileURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+    let userPlugin = "export const NotSupacode = async () => ({})\n"
+    try userPlugin.write(to: installer.pluginFileURL, atomically: true, encoding: .utf8)
+
+    try installer.uninstall()
+
+    let after = try String(contentsOf: installer.pluginFileURL, encoding: .utf8)
+    #expect(after == userPlugin)
+  }
+
+  @Test func uninstallIsNoOpWhenMissing() {
+    let homeURL = makeTempHomeURL()
+    defer { try? fileManager.removeItem(at: homeURL) }
+
+    let installer = OpenCodePluginInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    #expect(throws: Never.self) {
+      try installer.uninstall()
+    }
+  }
+
+  @Test func pluginFilePointsToExpectedPath() {
+    let homeURL = URL(fileURLWithPath: "/Users/test")
+    let installer = OpenCodePluginInstaller(homeDirectoryURL: homeURL, fileManager: fileManager)
+    #expect(installer.pluginFileURL.path == "/Users/test/.config/opencode/plugins/supacode-presence.js")
+  }
+
+  // MARK: - Generated source.
+
+  @Test func sourceCarriesOwnershipMarker() {
+    #expect(OpenCodePluginContent.source().contains(OpenCodePluginContent.ownershipMarker))
+  }
+
+  @Test func sourceWiresEveryPresenceTrigger() {
+    let source = OpenCodePluginContent.source()
+    // The verified OpenCode hook/event surface this plugin subscribes to.
+    for trigger in ["dispose", "tool.execute.before", "tool.execute.after", "permission.ask"] {
+      #expect(source.contains(trigger))
+    }
+    #expect(source.contains("session.idle"))
+    #expect(source.contains("permission.replied"))
+  }
+
+  @Test func sourceEmbedsOpenCodeScopedOSCForEveryState() {
+    let source = OpenCodePluginContent.source()
+    #expect(source.contains("start=opencode;event=session_start"))
+    #expect(source.contains("start=opencode;event=busy"))
+    #expect(source.contains("start=opencode;event=idle"))
+    #expect(source.contains("start=opencode;event=awaiting_input"))
+    #expect(source.contains("end=opencode;event=session_end"))
+  }
+
+  @Test func sourceDoesNotForwardNotifications() {
+    // OpenCode's session.idle event has no assistant text; the notify leg is
+    // intentionally omitted, so no notify OSC should appear in the plugin.
+    #expect(!OpenCodePluginContent.source().contains("kind=notify"))
+  }
+}
diff --git a/supacodeTests/OpenWorktreeActionTests.swift b/supacodeTests/OpenWorktreeActionTests.swift
index 698a90612..1fcc5aeb4 100644
--- a/supacodeTests/OpenWorktreeActionTests.swift
+++ b/supacodeTests/OpenWorktreeActionTests.swift
@@ -1,3 +1,4 @@
+import Foundation
 import Testing
 
 @testable import SupacodeSettingsShared
@@ -9,9 +10,11 @@ struct OpenWorktreeActionTests {
 
     #expect(settingsIDs.contains("android-studio"))
     #expect(settingsIDs.contains("antigravity"))
+    #expect(settingsIDs.contains("goland"))
     #expect(settingsIDs.contains("intellij"))
     #expect(settingsIDs.contains("rubymine"))
     #expect(settingsIDs.contains("rustrover"))
+    #expect(settingsIDs.contains("nova"))
     #expect(settingsIDs.contains("vscode-insiders"))
     #expect(settingsIDs.contains("warp"))
     #expect(settingsIDs.contains("webstorm"))
@@ -20,7 +23,9 @@ struct OpenWorktreeActionTests {
 
   @Test func jetBrainsIDEsHaveCorrectBundleIdentifiers() {
     #expect(OpenWorktreeAction.androidStudio.bundleIdentifier == "com.google.android.studio")
+    #expect(OpenWorktreeAction.goland.bundleIdentifier == "com.jetbrains.goland")
     #expect(OpenWorktreeAction.intellij.bundleIdentifier == "com.jetbrains.intellij")
+    #expect(OpenWorktreeAction.intellijEAP.bundleIdentifier == "com.jetbrains.intellij-EAP")
     #expect(OpenWorktreeAction.webstorm.bundleIdentifier == "com.jetbrains.WebStorm")
     #expect(OpenWorktreeAction.pycharm.bundleIdentifier == "com.jetbrains.pycharm")
     #expect(OpenWorktreeAction.rubymine.bundleIdentifier == "com.jetbrains.rubymine")
@@ -30,10 +35,275 @@ struct OpenWorktreeActionTests {
   @Test func jetBrainsIDEsAreInEditorPriority() {
     let editors = OpenWorktreeAction.editorPriority
     #expect(editors.contains(.androidStudio))
+    #expect(editors.contains(.goland))
     #expect(editors.contains(.intellij))
     #expect(editors.contains(.webstorm))
     #expect(editors.contains(.pycharm))
     #expect(editors.contains(.rubymine))
     #expect(editors.contains(.rustrover))
   }
+
+  @Test func novaIsConfiguredAsEditor() {
+    #expect(OpenWorktreeAction.nova.title == "Nova")
+    #expect(OpenWorktreeAction.nova.settingsID == "nova")
+    #expect(OpenWorktreeAction.nova.bundleIdentifier == "com.panic.Nova")
+    #expect(OpenWorktreeAction.nova.openTargets == [.default])
+    #expect(OpenWorktreeAction.nova.openBehaviors == [.default])
+    #expect(OpenWorktreeAction.editorPriority.contains(.nova))
+  }
+
+  @Test func xcodeOpenTargetsSearchWorkspaceThenProjectThenWorkingDirectory() {
+    let targets = OpenWorktreeAction.xcode.openTargets
+
+    #expect(targets.count == 3)
+    guard case .search(let workspacePattern, let workspaceExclusions, let workspaceMaxDepth) = targets[0] else {
+      #expect(Bool(false), "Xcode should search for workspaces first.")
+      return
+    }
+    guard case .search(let projectPattern, let projectExclusions, let projectMaxDepth) = targets[1] else {
+      #expect(Bool(false), "Xcode should search for projects second.")
+      return
+    }
+    #expect(workspacePattern == #"\.xcworkspace$"#)
+    for excludedDirectory in [
+      #"\.build"#,
+      #"\.dart_tool"#,
+      #"\.expo"#,
+      #"\.expo-shared"#,
+      #"\.git"#,
+      #"\.gradle"#,
+      #"\.pnpm-store"#,
+      #"\.swiftpm"#,
+      #"\.symlinks"#,
+      #"\.yarn"#,
+      "Carthage",
+      "DerivedData",
+      "Pods",
+      "build",
+      "node_modules",
+      #"\.xcodeproj"#,
+      #"\.xcworkspace"#,
+    ] {
+      #expect(workspaceExclusions?.contains(excludedDirectory) == true)
+    }
+    #expect(workspaceMaxDepth == 3)
+    #expect(projectPattern == #"\.xcodeproj$"#)
+    #expect(projectExclusions == workspaceExclusions)
+    #expect(projectMaxDepth == workspaceMaxDepth)
+    #expect(targets[2] == .default)
+    #expect(OpenTarget.default == .workingDirectory)
+  }
+
+  @Test func jetBrainsIDEsUseConfiguredWorkspaceOpenBehavior() {
+    for action in [
+      OpenWorktreeAction.androidStudio,
+      .goland,
+      .intellij,
+      .webstorm,
+      .pycharm,
+      .rubymine,
+      .rustrover,
+    ] {
+      guard action.openBehaviors.count == 1,
+        case .workspace(let configuration) = action.openBehaviors[0],
+        let configuration
+      else {
+        #expect(Bool(false), "\(action.title) should use workspace opening.")
+        continue
+      }
+      #expect(configuration.createsNewApplicationInstance)
+      #expect(configuration.arguments == [.targetPath])
+    }
+  }
+
+  @Test func zedUsesBundledCLIThenWorkspaceOpenBehavior() {
+    let behaviors = OpenWorktreeAction.zed.openBehaviors
+
+    #expect(behaviors.count == 2)
+    #expect(
+      behaviors.first
+        == .process(
+          .appRelativePath("Contents/MacOS/cli"),
+          args: [.targetPath]
+        )
+    )
+    #expect(behaviors.last == .default)
+    #expect(OpenBehavior.default == .workspace(configuration: nil))
+  }
+
+  @Test func zedPreviewUsesPreviewBundleIdentifierAndMirrorsZedOpenBehavior() {
+    #expect(OpenWorktreeAction.zedPreview.bundleIdentifier == "dev.zed.Zed-Preview")
+    #expect(OpenWorktreeAction.zedPreview.settingsID == "zed-preview")
+    #expect(OpenWorktreeAction.zedPreview.title == "Zed Preview")
+    #expect(OpenWorktreeAction.zedPreview.openBehaviors == OpenWorktreeAction.zed.openBehaviors)
+  }
+
+  @Test func zedPreviewIsAnEditorListedAfterZed() {
+    let editors = OpenWorktreeAction.editorPriority
+    #expect(editors.contains(.zedPreview))
+
+    guard let zedIndex = editors.firstIndex(of: .zed),
+      let previewIndex = editors.firstIndex(of: .zedPreview)
+    else {
+      #expect(Bool(false), "Both Zed channels should be in editor priority.")
+      return
+    }
+    #expect(previewIndex == zedIndex + 1)
+    #expect(OpenWorktreeAction.menuOrder.map(\.settingsID).contains("zed-preview"))
+  }
+
+  @MainActor
+  @Test func appRelativeProcessExecutableResolvesOnlyWhenPresent() throws {
+    let rootURL = try Self.makeTemporaryDirectory()
+    defer { try? FileManager.default.removeItem(at: rootURL) }
+    let appURL = rootURL.appending(path: "Zed.app")
+    let cliURL = appURL.appending(path: "Contents/MacOS/cli")
+    try FileManager.default.createDirectory(
+      at: cliURL.deletingLastPathComponent(),
+      withIntermediateDirectories: true
+    )
+    #expect(FileManager.default.createFile(atPath: cliURL.path(percentEncoded: false), contents: Data()))
+
+    let present = WorktreeOpener.processInvocation(
+      executable: .appRelativePath("Contents/MacOS/cli"),
+      appURL: appURL
+    )
+    let missing = WorktreeOpener.processInvocation(
+      executable: .appRelativePath("Contents/MacOS/missing"),
+      appURL: appURL
+    )
+
+    #expect(Self.standardizedPath(present?.executableURL) == Self.standardizedPath(cliURL))
+    #expect(present?.argumentPrefix == [])
+    #expect(missing == nil)
+  }
+
+  @MainActor
+  @Test func worktreeOpenerNoopsEditorAction() {
+    var errors: [OpenActionError] = []
+
+    WorktreeOpener.perform(
+      action: .editor,
+      worktree: Self.makeWorktree(at: URL(filePath: "/tmp/repo")),
+      onError: { errors.append($0) }
+    )
+
+    #expect(errors.isEmpty)
+  }
+
+  @Test func resolverSkipsExcludedSearchDirectoriesAndFallsBackToNextTarget() throws {
+    let rootURL = try Self.makeTemporaryDirectory()
+    defer { try? FileManager.default.removeItem(at: rootURL) }
+    try FileManager.default.createDirectory(
+      at: rootURL.appending(path: "Pods/Generated.xcworkspace"),
+      withIntermediateDirectories: true
+    )
+    let projectURL = rootURL.appending(path: "Supacode.xcodeproj")
+    try FileManager.default.createDirectory(at: projectURL, withIntermediateDirectories: true)
+
+    let resolved = WorkspaceOpenResolver.resolveFirstTarget(
+      for: [
+        .search(#"\.xcworkspace$"#, excludeDirectories: #"(^|/)Pods(/|$)"#),
+        .search(#"\.xcodeproj$"#, excludeDirectories: nil),
+        .workingDirectory,
+      ],
+      worktree: Self.makeWorktree(at: rootURL)
+    )
+
+    #expect(Self.standardizedPath(resolved) == Self.standardizedPath(projectURL))
+  }
+
+  @Test func xcodeResolverDoesNotDescendIntoProjectPackages() throws {
+    let rootURL = try Self.makeTemporaryDirectory()
+    defer { try? FileManager.default.removeItem(at: rootURL) }
+    let projectURL = rootURL.appending(path: "Supacode.xcodeproj")
+    try FileManager.default.createDirectory(
+      at: projectURL.appending(path: "project.xcworkspace"),
+      withIntermediateDirectories: true
+    )
+
+    let resolved = WorkspaceOpenResolver.resolveFirstTarget(
+      for: OpenWorktreeAction.xcode.openTargets,
+      worktree: Self.makeWorktree(at: rootURL)
+    )
+
+    #expect(Self.standardizedPath(resolved) == Self.standardizedPath(projectURL))
+  }
+
+  @Test func xcodeResolverStillReturnsTopLevelWorkspacePackages() throws {
+    let rootURL = try Self.makeTemporaryDirectory()
+    defer { try? FileManager.default.removeItem(at: rootURL) }
+    let workspaceURL = rootURL.appending(path: "Supacode.xcworkspace")
+    try FileManager.default.createDirectory(at: workspaceURL, withIntermediateDirectories: true)
+    try FileManager.default.createDirectory(
+      at: rootURL.appending(path: "Supacode.xcodeproj/project.xcworkspace"),
+      withIntermediateDirectories: true
+    )
+
+    let resolved = WorkspaceOpenResolver.resolveFirstTarget(
+      for: OpenWorktreeAction.xcode.openTargets,
+      worktree: Self.makeWorktree(at: rootURL)
+    )
+
+    #expect(Self.standardizedPath(resolved) == Self.standardizedPath(workspaceURL))
+  }
+
+  @Test func resolverOnlyUsesWorkingDirectoryWhenItIsAnExplicitFallback() throws {
+    let rootURL = try Self.makeTemporaryDirectory()
+    defer { try? FileManager.default.removeItem(at: rootURL) }
+    let worktree = Self.makeWorktree(at: rootURL)
+
+    let searchOnly = WorkspaceOpenResolver.resolveFirstTarget(
+      for: [.search(#"\.xcworkspace$"#, excludeDirectories: nil)],
+      worktree: worktree
+    )
+    let withExplicitFallback = WorkspaceOpenResolver.resolveFirstTarget(
+      for: [.search(#"\.xcworkspace$"#, excludeDirectories: nil), .workingDirectory],
+      worktree: worktree
+    )
+
+    #expect(searchOnly == nil)
+    #expect(Self.standardizedPath(withExplicitFallback) == Self.standardizedPath(rootURL))
+  }
+
+  @Test func resolverHonorsSearchMaxDepth() throws {
+    let rootURL = try Self.makeTemporaryDirectory()
+    defer { try? FileManager.default.removeItem(at: rootURL) }
+    let deepProjectURL = rootURL.appending(path: "Examples/macOS/App/Supacode.xcodeproj")
+    try FileManager.default.createDirectory(at: deepProjectURL, withIntermediateDirectories: true)
+
+    let defaultDepth = WorkspaceOpenResolver.resolveFirstTarget(
+      for: [.search(#"\.xcodeproj$"#)],
+      worktree: Self.makeWorktree(at: rootURL)
+    )
+    let deeperDepth = WorkspaceOpenResolver.resolveFirstTarget(
+      for: [.search(#"\.xcodeproj$"#, maxDepth: 4)],
+      worktree: Self.makeWorktree(at: rootURL)
+    )
+
+    #expect(defaultDepth == nil)
+    #expect(Self.standardizedPath(deeperDepth) == Self.standardizedPath(deepProjectURL))
+  }
+
+  private static func makeTemporaryDirectory() throws -> URL {
+    let url = FileManager.default.temporaryDirectory.appending(
+      path: "supacode-open-target-\(UUID().uuidString)"
+    )
+    try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
+    return url
+  }
+
+  private static func makeWorktree(at rootURL: URL) -> Worktree {
+    Worktree(
+      id: WorktreeID(rootURL.path(percentEncoded: false)),
+      name: rootURL.lastPathComponent,
+      detail: "detail",
+      workingDirectory: rootURL,
+      repositoryRootURL: rootURL
+    )
+  }
+
+  private static func standardizedPath(_ url: URL?) -> String? {
+    url?.standardizedFileURL.path(percentEncoded: false)
+  }
 }
diff --git a/supacodeTests/RemoteRepositorySidebarTests.swift b/supacodeTests/RemoteRepositorySidebarTests.swift
new file mode 100644
index 000000000..040e8b0ff
--- /dev/null
+++ b/supacodeTests/RemoteRepositorySidebarTests.swift
@@ -0,0 +1,1642 @@
+import ComposableArchitecture
+import DependenciesTestSupport
+import Foundation
+import IdentifiedCollections
+import OrderedCollections
+import Testing
+
+@testable import SupacodeSettingsShared
+@testable import supacode
+
+/// Test-only convenience mirroring the dissolved `RemoteRepositoryConfig`: a
+/// remote host + path with the derived helpers the old type exposed. Production
+/// stores remotes as self-descriptive id strings in `remoteRepositoryRoots`.
+struct TestRemoteRepo {
+  var host: RemoteHost
+  var remotePath: String
+
+  init(host: RemoteHost, remotePath: String, displayName: String = "") {
+    self.host = host
+    self.remotePath = remotePath
+  }
+
+  var normalizedRemotePath: String { RepositoryLocation.normalizedRemotePath(remotePath) }
+  var resolvedDisplayName: String { RepositoriesFeature.remoteRepositoryName(host: host, remotePath: remotePath) }
+  var id: Repository.ID { RepositoriesFeature.remoteRepositoryID(host: host, remotePath: remotePath) }
+}
+
+extension RepositoriesFeature {
+  static func remoteRepositoryID(for config: TestRemoteRepo) -> Repository.ID {
+    remoteRepositoryID(host: config.host, remotePath: config.remotePath)
+  }
+
+  static func remoteMainWorktree(config: TestRemoteRepo) -> Worktree {
+    remoteMainWorktree(host: config.host, remotePath: config.remotePath)
+  }
+
+  static func remoteFolderRepository(config: TestRemoteRepo, repoID: Repository.ID) -> Repository {
+    remoteFolderRepository(host: config.host, remotePath: config.remotePath, repoID: repoID)
+  }
+
+  static func remotePlaceholderRepository(config: TestRemoteRepo, repoID: Repository.ID) -> Repository {
+    remotePlaceholderRepository(host: config.host, remotePath: config.remotePath, repoID: repoID)
+  }
+
+  static func loadRemoteRepository(
+    _ config: TestRemoteRepo,
+    repoID: Repository.ID,
+    shell: ShellClient? = nil
+  ) async -> (repository: Repository, failure: LoadFailure?) {
+    await loadRemoteRepository(host: config.host, remotePath: config.remotePath, repoID: repoID, shell: shell)
+  }
+}
+
+struct RemoteRepositoryHelpersTests {
+  @Test func remoteRepositoryNameFallsBackToRemoteLeaf() {
+    #expect(
+      RepositoriesFeature.remoteRepositoryName(host: RemoteHost(alias: "devbox"), remotePath: "/home/me/proj") == "proj"
+    )
+    #expect(RepositoriesFeature.remoteRepositoryName(host: RemoteHost(alias: "devbox"), remotePath: "/") == "devbox")
+  }
+
+  @Test func remoteRepositoryIDIsHostKeyed() {
+    let id = RepositoriesFeature.remoteRepositoryID(host: RemoteHost(alias: "devbox"), remotePath: "/tmp/repo")
+    #expect(id == "devbox/tmp/repo")
+    // Never collides with a local repository id (an absolute filesystem path).
+    #expect(id != "/tmp/repo")
+  }
+
+  @Test func remoteWorktreeIDIsHostKeyed() {
+    let id = RepositoriesFeature.remoteWorktreeID(host: RemoteHost(alias: "devbox"), worktreePath: "/tmp/repo/wt")
+    #expect(id == "devbox/tmp/repo/wt")
+  }
+
+  @Test func remoteWorktreeInjectsHostAndHostKeyedID() {
+    let host = RemoteHost(alias: "devbox", username: "alice")
+    let base = Worktree(
+      id: "/home/alice/proj/feature",
+      name: "feature",
+      detail: "feature",
+      workingDirectory: URL(fileURLWithPath: "/home/alice/proj/feature"),
+      repositoryRootURL: URL(fileURLWithPath: "/home/alice/proj")
+    )
+    let rekeyed = RepositoriesFeature.remoteWorktree(from: base, host: host)
+    #expect(rekeyed.host?.sshDestination == "alice@devbox")
+    #expect(rekeyed.id == "alice@devbox/home/alice/proj/feature")
+    #expect(rekeyed.name == "feature")
+    #expect(rekeyed.workingDirectory == base.workingDirectory)
+  }
+
+  @Test func remoteMainWorktreeIsGitMainWithHost() {
+    let main = RepositoriesFeature.remoteMainWorktree(host: RemoteHost(alias: "devbox"), remotePath: "/home/me/proj")
+    #expect(main.host?.sshDestination == "devbox")
+    // workingDirectory == repositoryRootURL → classifies as the git main worktree.
+    #expect(main.workingDirectory == main.repositoryRootURL)
+    #expect(main.id == "devbox/home/me/proj")
+  }
+}
+
+@MainActor
+struct RemoteSidebarMergedListTests {
+  private func localRepository() -> Repository {
+    let root = URL(fileURLWithPath: "/tmp/localrepo")
+    let main = Worktree(
+      id: WorktreeID(root.path(percentEncoded: false)),
+      name: "main",
+      detail: "",
+      workingDirectory: root,
+      repositoryRootURL: root
+    )
+    return Repository(
+      id: RepositoryID(root.path(percentEncoded: false)),
+      rootURL: root,
+      name: "localrepo",
+      worktrees: IdentifiedArray(uniqueElements: [main])
+    )
+  }
+
+  private func remoteRepository(config: TestRemoteRepo) -> Repository {
+    Repository(
+      id: RepositoriesFeature.remoteRepositoryID(for: config),
+      rootURL: URL(fileURLWithPath: config.normalizedRemotePath),
+      name: config.resolvedDisplayName,
+      worktrees: IdentifiedArray(uniqueElements: [RepositoriesFeature.remoteMainWorktree(config: config)]),
+      isGitRepository: true,
+      host: config.host
+    )
+  }
+
+  private func makeState(repositories: [Repository]) -> RepositoriesFeature.State {
+    var state = RepositoriesFeature.State(reconciledRepositories: repositories)
+    state.isInitialLoadComplete = true
+    return state
+  }
+
+  @Test func remoteRepoRendersInlineAfterLocalWithoutPartitionHeaders() {
+    let config = TestRemoteRepo(
+      host: RemoteHost(alias: "devbox"),
+      remotePath: "/home/me/proj",
+      displayName: "proj"
+    )
+    let local = localRepository()
+    let state = makeState(repositories: [local, remoteRepository(config: config)])
+
+    let structure = state.computeSidebarStructure(groupPinned: false, groupActive: false)
+
+    // Every section is a real repository section: no synthetic divider rows.
+    let repoIDs: [Repository.ID] = structure.sections.compactMap { section in
+      if case .repository(let repositoryID, _) = section { return repositoryID }
+      return nil
+    }
+    #expect(repoIDs.count == structure.sections.count)
+
+    // Local repo precedes the remote repo in the merged, flat list.
+    let remoteRepoID = RepositoriesFeature.remoteRepositoryID(for: config)
+    #expect(repoIDs == [local.id, remoteRepoID])
+
+    // The remote repo's tag is flagged remote so the subtitle / header can mark it.
+    // (No row is hoisted here, so `repositoryHighlightByID` is empty; the inline
+    // section header reads `repository.host != nil` directly.)
+    #expect(state.repositories[id: remoteRepoID]?.host != nil)
+  }
+
+  @Test func orderedRepositoryIDsIncludesRemoteRepos() {
+    let config = TestRemoteRepo(
+      host: RemoteHost(alias: "devbox"),
+      remotePath: "/home/me/proj",
+      displayName: "proj"
+    )
+    let local = localRepository()
+    let state = makeState(repositories: [local, remoteRepository(config: config)])
+    let ids = state.orderedRepositoryIDs()
+    // Remote repos (host-keyed ids, not local roots) must appear so the pinned
+    // hoist, hotkeys, and arrow-nav can see remote rows.
+    #expect(ids.contains(local.id))
+    #expect(ids.contains(RepositoriesFeature.remoteRepositoryID(for: config)))
+  }
+
+  @Test func remoteRepositoriesAreReorderable() {
+    let config = TestRemoteRepo(
+      host: RemoteHost(alias: "devbox"),
+      remotePath: "/home/me/proj",
+      displayName: "proj"
+    )
+    let local = localRepository()
+    let remote = remoteRepository(config: config)
+    let state = makeState(repositories: [local, remote])
+
+    let structure = state.computeSidebarStructure(groupPinned: false, groupActive: false)
+
+    // A remote repo is a first-class drag target, not pinned below the locals.
+    #expect(structure.reorderableRepositoryIDs.contains(remote.id))
+    // `reorderableRepositoryIDs` mirrors `orderedRepositoryIDs()` 1:1 so the
+    // offset-based `.repositoriesMoved` maps cleanly.
+    #expect(structure.reorderableRepositoryIDs == state.orderedRepositoryIDs())
+  }
+
+  @Test func persistedSidebarOrderInterleavesRemoteAndLocal() {
+    let config = TestRemoteRepo(
+      host: RemoteHost(alias: "devbox"),
+      remotePath: "/home/me/proj",
+      displayName: "proj"
+    )
+    let local = localRepository()
+    let remote = remoteRepository(config: config)
+    var state = makeState(repositories: [local, remote])
+    // Simulate a drag that placed the remote repo above the local one.
+    state.$sidebar.withLock { sidebar in
+      var sections: OrderedDictionary<Repository.ID, SidebarState.Section> = [:]
+      sections[remote.id] = .init()
+      sections[local.id] = .init()
+      sidebar.sections = sections
+    }
+
+    #expect(state.orderedRepositoryIDs() == [remote.id, local.id])
+
+    let structure = state.computeSidebarStructure(groupPinned: false, groupActive: false)
+    let repoIDs: [Repository.ID] = structure.sections.compactMap { section in
+      if case .repository(let repositoryID, _) = section { return repositoryID }
+      return nil
+    }
+    #expect(repoIDs == [remote.id, local.id])
+  }
+
+  @Test func repositoriesMovedReordersRemoteAboveLocal() async {
+    let config = TestRemoteRepo(
+      host: RemoteHost(alias: "devbox"),
+      remotePath: "/home/me/proj",
+      displayName: "proj"
+    )
+    let local = localRepository()
+    let remote = remoteRepository(config: config)
+    let state = makeState(repositories: [local, remote])
+    // Default order before any drag: local then remote.
+    #expect(state.orderedRepositoryIDs() == [local.id, remote.id])
+
+    let store = TestStore(initialState: state) {
+      RepositoriesFeature()
+    } withDependencies: {
+      $0.sidebarStructureAutoRecompute = false
+    }
+    // The move rewrites the persisted `sidebar.sections` order plus derived
+    // caches; this test only asserts the resulting repository order.
+    store.exhaustivity = .off
+
+    // Drag the remote repo (index 1) to the top.
+    await store.send(.repositoriesMoved([1], 0))
+    #expect(store.state.orderedRepositoryIDs() == [remote.id, local.id])
+    let sectionOrder = Array(store.state.sidebar.sections.keys)
+    #expect(sectionOrder == [remote.id, local.id])
+  }
+
+  @Test func localOnlySidebarRendersFlatRepositorySections() {
+    let local = localRepository()
+    let state = makeState(repositories: [local])
+
+    let structure = state.computeSidebarStructure(groupPinned: false, groupActive: false)
+    let repoIDs: [Repository.ID] = structure.sections.compactMap { section in
+      if case .repository(let repositoryID, _) = section { return repositoryID }
+      return nil
+    }
+    #expect(repoIDs == [local.id])
+  }
+
+  @Test func nonGitRemoteRendersAsFolderSection() {
+    let config = TestRemoteRepo(
+      host: RemoteHost(alias: "devbox"),
+      remotePath: "/home/me/docs",
+      displayName: "docs"
+    )
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: config)
+    let folderRepo = RepositoriesFeature.remoteFolderRepository(config: config, repoID: repoID)
+    let state = makeState(repositories: [folderRepo])
+
+    let structure = state.computeSidebarStructure(groupPinned: false, groupActive: false)
+    // A remote folder's synthetic worktree id is its host-keyed repo id; git-vs-folder
+    // is carried by `Worktree.kind`, so it never collides with a local folder at the same path.
+    let folderRowID = WorktreeID(repoID.rawValue)
+    let rendersFolder = structure.sections.contains { section in
+      if case .folder(let id, let rowID) = section { return id == repoID && rowID == folderRowID }
+      return false
+    }
+    #expect(rendersFolder)
+    // Never a git repository section for a non-git remote path.
+    let rendersRepository = structure.sections.contains { section in
+      if case .repository = section { return true }
+      return false
+    }
+    #expect(!rendersRepository)
+  }
+
+  @Test func disconnectedRemoteRendersAsFailedPlaceholderNotPruned() {
+    let config = TestRemoteRepo(
+      host: RemoteHost(alias: "devbox"),
+      remotePath: "/home/me/proj",
+      displayName: "proj"
+    )
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: config)
+    // The loader keeps an empty placeholder repository for an unreachable host.
+    let placeholder = Repository(
+      id: repoID,
+      rootURL: URL(fileURLWithPath: "/home/me/proj"),
+      name: "proj",
+      worktrees: [],
+      isGitRepository: true,
+      host: config.host
+    )
+    var state = makeState(repositories: [placeholder])
+    state.loadFailuresByID[repoID] = "Can't reach devbox."
+
+    let structure = state.computeSidebarStructure(groupPinned: false, groupActive: false)
+    let rendersFailedRemote = structure.sections.contains { section in
+      if case .failedRepository(let id, _, _, _, let isRemote) = section { return id == repoID && isRemote }
+      return false
+    }
+    #expect(rendersFailedRemote)
+    // It is not pruned, and not rendered as a normal repository / folder section.
+    let rendersRepository = structure.sections.contains { section in
+      if case .repository = section { return true }
+      return false
+    }
+    #expect(!rendersRepository)
+  }
+}
+
+/// A disconnected remote keeps an empty placeholder in the roster; reconcile
+/// must not read that as "worktrees gone" and prune the user's curation.
+@MainActor
+struct RemoteDisconnectCurationTests {
+  private func makeState(repositories: [Repository]) -> RepositoriesFeature.State {
+    var state = RepositoriesFeature.State(reconciledRepositories: repositories)
+    state.isInitialLoadComplete = true
+    return state
+  }
+
+  @Test func disconnectPreservesRemoteGitPinAndCustomization() {
+    let config = TestRemoteRepo(host: RemoteHost(alias: "devbox"), remotePath: "/home/me/proj")
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: config)
+    let pinnedID = RepositoriesFeature.remoteWorktreeID(host: config.host, worktreePath: "/home/me/proj-feature")
+    // The loader builds an empty placeholder for an unreachable host.
+    let placeholder = RepositoriesFeature.remotePlaceholderRepository(config: config, repoID: repoID)
+    var state = makeState(repositories: [placeholder])
+    state.$sidebar.withLock { sidebar in
+      sidebar.sections[repoID] = .init(
+        buckets: [.pinned: .init(items: [pinnedID: .init()])],
+        title: "Custom",
+        color: .red
+      )
+    }
+
+    // A non-initial reload while still disconnected (the destructive prune is on).
+    state.reconcileSidebarState(roots: [], pruneLivenessAgainstRoster: true)
+
+    #expect(state.sidebar.sections[repoID]?.buckets[.pinned]?.items[pinnedID] != nil)
+    #expect(state.sidebar.sections[repoID]?.title == "Custom")
+    #expect(state.sidebar.sections[repoID]?.color == .red)
+  }
+
+  @Test func disconnectPreservesRemoteFolderPin() {
+    let config = TestRemoteRepo(host: RemoteHost(alias: "devbox"), remotePath: "/home/me/notes")
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: config)
+    // A folder's pinnable unit is its synthetic worktree, host-keyed off its path.
+    let folderWorktreeID = RepositoriesFeature.remoteWorktreeID(host: config.host, worktreePath: "/home/me/notes")
+    let placeholder = RepositoriesFeature.remotePlaceholderRepository(config: config, repoID: repoID)
+    var state = makeState(repositories: [placeholder])
+    state.$sidebar.withLock { sidebar in
+      sidebar.sections[repoID] = .init(buckets: [.pinned: .init(items: [folderWorktreeID: .init()])])
+    }
+
+    state.reconcileSidebarState(roots: [], pruneLivenessAgainstRoster: true)
+
+    #expect(state.sidebar.sections[repoID]?.buckets[.pinned]?.items[folderWorktreeID] != nil)
+  }
+
+  @Test func resolvedRemoteStillPrunesStaleCuration() {
+    // A reachable remote with a real roster must keep pruning vanished worktrees,
+    // so the disconnect carve-out doesn't leak stale pins once the host is back.
+    let config = TestRemoteRepo(host: RemoteHost(alias: "devbox"), remotePath: "/home/me/proj")
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: config)
+    let liveID = RepositoriesFeature.remoteWorktreeID(host: config.host, worktreePath: "/home/me/proj")
+    let staleID = RepositoriesFeature.remoteWorktreeID(host: config.host, worktreePath: "/home/me/proj-gone")
+    let resolved = Repository(
+      id: repoID,
+      rootURL: URL(fileURLWithPath: "/home/me/proj"),
+      name: "proj",
+      worktrees: [RepositoriesFeature.remoteMainWorktree(config: config)],
+      isGitRepository: true,
+      host: config.host
+    )
+    var state = makeState(repositories: [resolved])
+    state.$sidebar.withLock { sidebar in
+      sidebar.sections[repoID] = .init(buckets: [.pinned: .init(items: [liveID: .init(), staleID: .init()])])
+    }
+
+    state.reconcileSidebarState(roots: [], pruneLivenessAgainstRoster: true)
+
+    #expect(state.sidebar.sections[repoID]?.buckets[.pinned]?.items[staleID] == nil)
+  }
+
+  @Test func disconnectPreservesCollapsedBranchPrefixes() {
+    let config = TestRemoteRepo(host: RemoteHost(alias: "devbox"), remotePath: "/home/me/proj")
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: config)
+    let placeholder = RepositoriesFeature.remotePlaceholderRepository(config: config, repoID: repoID)
+    var state = makeState(repositories: [placeholder])
+    state.$sidebar.withLock { sidebar in
+      sidebar.sections[repoID] = .init(buckets: [.unpinned: .init(collapsedBranchPrefixes: ["feature"])])
+    }
+
+    state.reconcileSidebarState(roots: [], pruneLivenessAgainstRoster: true)
+
+    // The empty placeholder roster must not wipe the user's branch-collapse state.
+    #expect(state.sidebar.sections[repoID]?.buckets[.unpinned]?.collapsedBranchPrefixes == ["feature"])
+  }
+
+  @Test func disconnectedRemoteFolderErrorRowKeepsFolderCustomization() {
+    let config = TestRemoteRepo(host: RemoteHost(alias: "devbox"), remotePath: "/home/me/notes")
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: config)
+    // A folder's custom name / color live on the synthetic folder-worktree item.
+    let folderWorktreeID = RepositoriesFeature.remoteWorktreeID(host: config.host, worktreePath: "/home/me/notes")
+    let placeholder = RepositoriesFeature.remotePlaceholderRepository(config: config, repoID: repoID)
+    var state = makeState(repositories: [placeholder])
+    state.$sidebar.withLock { sidebar in
+      sidebar.sections[repoID] = .init(
+        buckets: [.unpinned: .init(items: [folderWorktreeID: .init(title: "My Notes", color: .teal)])]
+      )
+    }
+    state.loadFailuresByID[repoID] = "Can't reach devbox."
+
+    let structure = state.computeSidebarStructure(groupPinned: false, groupActive: false)
+    let failed = structure.sections.compactMap { section -> (String?, RepositoryColor?)? in
+      guard case .failedRepository(let id, _, let title, let color, _) = section, id == repoID else { return nil }
+      return (title, color)
+    }.first
+    // The "can't reach" header surfaces the folder's custom name / color, like the live row.
+    #expect(failed?.0 == "My Notes")
+    #expect(failed?.1 == .teal)
+  }
+}
+
+@MainActor
+struct RemoteDefaultShellCommandTests {
+  @Test func buildsCdIntoRemotePathThenExecLoginShell() {
+    #expect(
+      WorktreeTerminalState.remoteDefaultShellCommand(remotePath: "/home/me/proj")
+        == "cd '/home/me/proj' 2>/dev/null; exec \"$SHELL\" -l"
+    )
+  }
+
+  @Test func escapesSingleQuotesInRemotePath() {
+    #expect(
+      WorktreeTerminalState.remoteDefaultShellCommand(remotePath: "/home/o'brien/proj")
+        == "cd '/home/o'\\''brien/proj' 2>/dev/null; exec \"$SHELL\" -l"
+    )
+  }
+
+  @Test func nilForRootOrEmptyPath() {
+    #expect(WorktreeTerminalState.remoteDefaultShellCommand(remotePath: "/") == nil)
+    #expect(WorktreeTerminalState.remoteDefaultShellCommand(remotePath: "   ") == nil)
+  }
+}
+
+@MainActor
+struct RemoteWorktreeInfoTests {
+  private func remoteRepository(config: TestRemoteRepo) -> (Repository, Worktree) {
+    let worktree = RepositoriesFeature.remoteMainWorktree(config: config)
+    let repository = Repository(
+      id: RepositoriesFeature.remoteRepositoryID(for: config),
+      rootURL: URL(fileURLWithPath: config.normalizedRemotePath),
+      name: config.resolvedDisplayName,
+      worktrees: IdentifiedArray(uniqueElements: [worktree]),
+      isGitRepository: true,
+      host: config.host
+    )
+    return (repository, worktree)
+  }
+
+  /// PR refresh runs `gh` against a local checkout, which a remote-only repo
+  /// doesn't have, so the reducer must short-circuit to `.none`.
+  @Test func pullRequestRefreshSkippedForRemoteRepository() async {
+    let config = TestRemoteRepo(
+      host: RemoteHost(alias: "devbox"),
+      remotePath: "/home/me/proj",
+      displayName: "proj"
+    )
+    let (repository, worktree) = remoteRepository(config: config)
+    var state = RepositoriesFeature.State(reconciledRepositories: [repository])
+    state.isInitialLoadComplete = true
+
+    let store = TestStore(initialState: state) {
+      RepositoriesFeature()
+    } withDependencies: {
+      $0.sidebarStructureAutoRecompute = false
+    }
+
+    // No state change and no effects: the host guard returns before any `gh`
+    // work, so an exhaustive TestStore send with no trailing closure passes.
+    await store.send(
+      .worktreeInfoEvent(
+        .repositoryPullRequestRefresh(repositoryRootURL: repository.rootURL, worktreeIDs: [worktree.id])
+      )
+    )
+  }
+
+  /// The remote-add flow presents a reducer-driven form (so errors can surface
+  /// inline); cancelling dismisses it.
+  @Test func requestAddRemoteRepositoryPresentsFormAndCancelDismisses() async {
+    let store = TestStore(initialState: RepositoriesFeature.State()) {
+      RepositoriesFeature()
+    } withDependencies: {
+      $0.sidebarStructureAutoRecompute = false
+    }
+
+    await store.send(.requestAddRemoteRepository) {
+      $0.remoteConnectionForm = RemoteConnectionFormFeature.State(mode: .add)
+    }
+    await store.send(.remoteConnectionForm(.presented(.delegate(.cancel)))) {
+      $0.remoteConnectionForm = nil
+    }
+  }
+}
+
+@MainActor
+struct RemoteConnectionFormFeatureTests {
+  @Test func bindingClearsStaleValidationMessage() async {
+    var initial = RemoteConnectionFormFeature.State(mode: .add, server: "devbox")
+    initial.validationMessage = "stale"
+    let store = TestStore(initialState: initial) { RemoteConnectionFormFeature() }
+    await store.send(.binding(.set(\.remotePath, "~/proj"))) {
+      $0.remotePath = "~/proj"
+      $0.validationMessage = nil
+    }
+  }
+
+  @Test func failedResolutionShowsFooterMessageAndStaysOpen() async {
+    var initial = RemoteConnectionFormFeature.State(mode: .add, server: "devbox", remotePath: "~/proj")
+    initial.isValidating = true
+    let store = TestStore(initialState: initial) { RemoteConnectionFormFeature() }
+    await store.send(.resolutionFinished(absolutePath: nil)) {
+      $0.isValidating = false
+      $0.validationMessage =
+        "Couldn't reach devbox or find ~/proj. Check the server, port, user, and path."
+    }
+  }
+
+  @Test func successfulResolutionDelegatesSaveWithAbsolutePath() async {
+    var initial = RemoteConnectionFormFeature.State(mode: .add, server: "devbox", remotePath: "~/proj")
+    initial.isValidating = true
+    let store = TestStore(initialState: initial) { RemoteConnectionFormFeature() }
+    await store.send(.resolutionFinished(absolutePath: "/home/me/proj")) {
+      $0.isValidating = false
+    }
+    await store.receive(\.delegate)
+  }
+
+  @Test func cancelDelegatesCancel() async {
+    let store = TestStore(initialState: RemoteConnectionFormFeature.State(mode: .add)) {
+      RemoteConnectionFormFeature()
+    }
+    await store.send(.cancelButtonTapped)
+    await store.receive(\.delegate)
+  }
+}
+
+/// `saveRemoteConnection` is the load-bearing persist path the form delegates
+/// into: add (append + dedup), edit (replace by id), and host/path re-key (drop
+/// the orphaned per-repo customization). The form-feature tests stop at the
+/// delegate; these drive `.remoteConnectionForm(.presented(.delegate(.save)))`
+/// against the real `RepositoriesFeature` reducer to cover the persist itself.
+@MainActor
+struct SaveRemoteConnectionTests {
+  /// Run `body` with the settings-file dependencies pinned to a per-test
+  /// in-memory storage so the reducer's `@Shared(.settingsFile)` mutations and
+  /// the test body's reads resolve the same key (the key captures
+  /// `settingsFileURL` at construction). The `.dependencies` trait isolates
+  /// shared state per test.
+  private func withRemoteStore(
+    _ body: (TestStoreOf<RepositoriesFeature>) async -> Void
+  ) async {
+    let storage = SettingsTestStorage()
+    let settingsFileURL = URL(fileURLWithPath: "/tmp/supacode-remote-save-\(UUID().uuidString).json")
+    await withDependencies {
+      $0.settingsFileStorage = storage.storage
+      $0.settingsFileURL = settingsFileURL
+      $0.sidebarStructureAutoRecompute = false
+    } operation: {
+      let store = TestStore(initialState: RepositoriesFeature.State()) {
+        RepositoriesFeature()
+      }
+      // The save handler reloads; we only assert the synchronous persist, so let
+      // the reducer ignore everything past the `save` send.
+      store.exhaustivity = .off
+      await body(store)
+    }
+  }
+
+  private func remoteRepositories() -> [TestRemoteRepo] {
+    @Shared(.remoteRepositoryRoots) var remoteRepositoryRoots
+    return remoteRepositoryRoots.compactMap { id in
+      guard let (host, path) = RepositoriesFeature.parseRemoteRoot(id) else { return nil }
+      return TestRemoteRepo(host: host, remotePath: path)
+    }
+  }
+
+  @Test(.dependencies) func addAppendsNewConfig() async {
+    await withRemoteStore { store in
+      let config = TestRemoteRepo(
+        host: RemoteHost(alias: "devbox"),
+        remotePath: "/home/me/proj",
+        displayName: ""
+      )
+
+      await store.send(.requestAddRemoteRepository) {
+        $0.remoteConnectionForm = RemoteConnectionFormFeature.State(mode: .add)
+      }
+      await store.send(
+        .remoteConnectionForm(.presented(.delegate(.save(host: config.host, remotePath: config.remotePath)))))
+      await store.finish()
+
+      let configs = remoteRepositories()
+      #expect(configs.map(\.id) == [config.id])
+      #expect(configs.first?.normalizedRemotePath == "/home/me/proj")
+    }
+  }
+
+  @Test(.dependencies) func editReplacesConfigByIDInPlace() async {
+    await withRemoteStore { store in
+      let original = TestRemoteRepo(
+        host: RemoteHost(alias: "devbox"),
+        remotePath: "/home/me/proj",
+        displayName: "old"
+      )
+      let originalRepositoryID = RepositoriesFeature.remoteRepositoryID(for: original)
+
+      @Shared(.settingsFile) var settingsFile
+      $settingsFile.withLock { $0.remoteRepositoryRoots = [original.id.rawValue] }
+
+      // Same host/path (so the id is unchanged) but a new display name.
+      let edited = TestRemoteRepo(
+        host: RemoteHost(alias: "devbox"),
+        remotePath: "/home/me/proj",
+        displayName: "new"
+      )
+
+      await store.send(.requestEditRemoteRepository(originalRepositoryID)) {
+        $0.remoteConnectionForm = RemoteConnectionFormFeature.State.editing(
+          host: original.host, remotePath: original.remotePath, repositoryID: originalRepositoryID)
+      }
+      await store.send(
+        .remoteConnectionForm(.presented(.delegate(.save(host: edited.host, remotePath: edited.remotePath)))))
+      await store.finish()
+
+      let configs = remoteRepositories()
+      // Same host/path means the same derived id: replaced in place, still one entry.
+      #expect(configs.count == 1)
+      #expect(configs.first?.id == original.id)
+    }
+  }
+
+  @Test(.dependencies) func editReKeyingHostOrPathDropsOrphanedCustomization() async {
+    await withRemoteStore { store in
+      let original = TestRemoteRepo(
+        host: RemoteHost(alias: "devbox"),
+        remotePath: "/home/me/proj",
+        displayName: ""
+      )
+      let originalRepositoryID = RepositoriesFeature.remoteRepositoryID(for: original)
+
+      @Shared(.settingsFile) var settingsFile
+      $settingsFile.withLock { $0.remoteRepositoryRoots = [original.id.rawValue] }
+      // Seed per-repo customization under the original id; the re-key must drop it.
+      @Shared(.sidebar) var sidebar
+      $sidebar.withLock {
+        $0.sections[originalRepositoryID, default: .init()].title = "Custom Title"
+      }
+      #expect(store.state.sidebar.sections[originalRepositoryID] != nil)
+
+      // Re-key by editing the path; the derived id changes.
+      let edited = TestRemoteRepo(
+        host: RemoteHost(alias: "devbox"),
+        remotePath: "/home/me/other",
+        displayName: ""
+      )
+      #expect(RepositoriesFeature.remoteRepositoryID(for: edited) != originalRepositoryID)
+
+      await store.send(.requestEditRemoteRepository(originalRepositoryID)) {
+        $0.remoteConnectionForm = RemoteConnectionFormFeature.State.editing(
+          host: original.host, remotePath: original.remotePath, repositoryID: originalRepositoryID)
+      }
+      await store.send(
+        .remoteConnectionForm(.presented(.delegate(.save(host: edited.host, remotePath: edited.remotePath)))))
+      await store.finish()
+
+      // The orphaned customization under the old id is dropped.
+      #expect(store.state.sidebar.sections[originalRepositoryID] == nil)
+      // The replaced config persists at the new path.
+      #expect(remoteRepositories().first?.normalizedRemotePath == "/home/me/other")
+    }
+  }
+
+  @Test(.dependencies) func addOfDuplicateHostAndPathIsDeduped() async {
+    await withRemoteStore { store in
+      let existing = TestRemoteRepo(
+        host: RemoteHost(alias: "devbox"),
+        remotePath: "/home/me/proj",
+        displayName: ""
+      )
+
+      @Shared(.settingsFile) var settingsFile
+      $settingsFile.withLock { $0.remoteRepositoryRoots = [existing.id.rawValue] }
+
+      // Same host + path but with a trailing slash: it normalizes to the same
+      // derived id, so the add must dedupe instead of appending a second entry.
+      let duplicate = TestRemoteRepo(
+        host: RemoteHost(alias: "devbox"),
+        remotePath: "/home/me/proj/",
+        displayName: "dupe"
+      )
+      #expect(duplicate.id == existing.id)
+
+      await store.send(.requestAddRemoteRepository) {
+        $0.remoteConnectionForm = RemoteConnectionFormFeature.State(mode: .add)
+      }
+      await store.send(
+        .remoteConnectionForm(.presented(.delegate(.save(host: duplicate.host, remotePath: duplicate.remotePath)))))
+      await store.finish()
+
+      let configs = remoteRepositories()
+      #expect(configs.count == 1)
+      #expect(configs.first?.id == existing.id)
+    }
+  }
+
+  @Test(.dependencies) func addOfPortDistinctConnectionAppendsSeparately() async {
+    await withRemoteStore { store in
+      let existing = TestRemoteRepo(
+        host: RemoteHost(alias: "devbox", port: 22),
+        remotePath: "/home/me/proj",
+        displayName: ""
+      )
+
+      @Shared(.settingsFile) var settingsFile
+      $settingsFile.withLock { $0.remoteRepositoryRoots = [existing.id.rawValue] }
+
+      // Same host alias and path, different SSH port: a distinct repository id,
+      // so it must be kept rather than deduped against the port-22 connection.
+      let otherPort = TestRemoteRepo(
+        host: RemoteHost(alias: "devbox", port: 2222),
+        remotePath: "/home/me/proj",
+        displayName: ""
+      )
+      #expect(
+        RepositoriesFeature.remoteRepositoryID(for: otherPort)
+          != RepositoriesFeature.remoteRepositoryID(for: existing)
+      )
+
+      await store.send(.requestAddRemoteRepository) {
+        $0.remoteConnectionForm = RemoteConnectionFormFeature.State(mode: .add)
+      }
+      await store.send(
+        .remoteConnectionForm(.presented(.delegate(.save(host: otherPort.host, remotePath: otherPort.remotePath)))))
+      await store.finish()
+
+      #expect(remoteRepositories().count == 2)
+    }
+  }
+
+  @Test(.dependencies) func removeRemoteRepositoryDropsMatchingConfigAndCustomization() async {
+    await withRemoteStore { store in
+      let target = TestRemoteRepo(
+        host: RemoteHost(alias: "devbox"),
+        remotePath: "/home/me/proj",
+        displayName: ""
+      )
+      let other = TestRemoteRepo(
+        host: RemoteHost(alias: "devbox"),
+        remotePath: "/home/me/other",
+        displayName: ""
+      )
+      let targetID = RepositoriesFeature.remoteRepositoryID(for: target)
+
+      @Shared(.settingsFile) var settingsFile
+      $settingsFile.withLock { $0.remoteRepositoryRoots = [target.id.rawValue, other.id.rawValue] }
+      @Shared(.sidebar) var sidebar
+      $sidebar.withLock { $0.sections[targetID, default: .init()].title = "Custom Title" }
+
+      await store.send(.removeRemoteRepository(targetID))
+      await store.finish()
+
+      let configs = remoteRepositories()
+      // Only the matching config is dropped; the sibling survives.
+      #expect(configs.count == 1)
+      #expect(configs.first?.id == other.id)
+      // The orphaned per-repo customization is dropped with it.
+      #expect(store.state.sidebar.sections[targetID] == nil)
+    }
+  }
+}
+
+struct RemotePathClassificationTests {
+  private func stubShell(stdout: String) -> ShellClient {
+    ShellClient(
+      run: { _, _, _ in ShellOutput(stdout: stdout, stderr: "", exitCode: 0) },
+      runLoginImpl: { _, _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) }
+    )
+  }
+
+  private func throwingShell() -> ShellClient {
+    ShellClient(
+      run: { _, _, _ in throw ShellClientError(command: "probe", stdout: "", stderr: "", exitCode: 1) },
+      runLoginImpl: { _, _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) }
+    )
+  }
+
+  /// Routes the `git worktree list` call and the classify probe to separate
+  /// stubs so resolution branches can be exercised independently.
+  private func routingShell(worktreeList: Result<String, Error>, classifyStdout: String) -> ShellClient {
+    ShellClient(
+      run: { _, args, _ in
+        if args.contains("worktree") {
+          switch worktreeList {
+          case .success(let stdout): return ShellOutput(stdout: stdout, stderr: "", exitCode: 0)
+          case .failure(let error): throw error
+          }
+        }
+        return ShellOutput(stdout: classifyStdout, stderr: "", exitCode: 0)
+      },
+      runLoginImpl: { _, _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) }
+    )
+  }
+
+  private func resolveConfig(path: String = "/srv/repo") -> TestRemoteRepo {
+    TestRemoteRepo(host: RemoteHost(alias: "devbox"), remotePath: path, displayName: "repo")
+  }
+
+  @Test func listingThrowOnGitRepoSurfacesFailureInsteadOfFakeMain() async {
+    let config = resolveConfig()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: config)
+    // The listing fails transiently while the host stays reachable (classify
+    // still resolves `.git`): we must not collapse to a single fake main.
+    let shell = routingShell(
+      worktreeList: .failure(ShellClientError(command: "git", stdout: "", stderr: "", exitCode: 1)),
+      classifyStdout: "supacode-git"
+    )
+    let loaded = await RepositoriesFeature.loadRemoteRepository(config, repoID: repoID, shell: shell)
+    #expect(loaded.repository.worktrees.isEmpty)
+    #expect(loaded.failure?.message.contains("couldn't list worktrees") == true)
+  }
+
+  @Test func duplicateWorktreePathsSurfacesFailureInsteadOfTrapping() async {
+    let config = resolveConfig()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: config)
+    // A corrupt remote repo (e.g. a stale `core.worktree`) can list the same
+    // path twice; refuse it rather than trap `IdentifiedArray(uniqueElements:)`.
+    let listing = """
+      worktree /srv/repo
+      HEAD 1111111111111111111111111111111111111111
+      branch refs/heads/main
+
+      worktree /srv/repo/feature
+      HEAD 2222222222222222222222222222222222222222
+      branch refs/heads/feature
+
+      worktree /srv/repo/feature
+      HEAD 3333333333333333333333333333333333333333
+      branch refs/heads/other
+      """
+    let shell = routingShell(worktreeList: .success(listing), classifyStdout: "supacode-git")
+    let loaded = await RepositoriesFeature.loadRemoteRepository(config, repoID: repoID, shell: shell)
+    #expect(loaded.repository.worktrees.isEmpty)
+    // Pin the placeholder branch (a folder fallback is also empty-worktrees).
+    #expect(loaded.repository.host != nil)
+    #expect(loaded.failure?.message.contains("more than one worktree at the same path") == true)
+    // The surfaced path is the host-keyed worktree id, not the bare remote path.
+    #expect(loaded.failure?.message.contains("devbox/srv/repo") == true)
+  }
+
+  @Test func emptyListingOnGitRepoFallsBackToSyntheticMain() async {
+    let config = resolveConfig()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: config)
+    // A clean but empty listing is genuine: a single synthetic main is correct.
+    let shell = routingShell(worktreeList: .success(""), classifyStdout: "supacode-git")
+    let loaded = await RepositoriesFeature.loadRemoteRepository(config, repoID: repoID, shell: shell)
+    #expect(loaded.failure == nil)
+    #expect(loaded.repository.worktrees.count == 1)
+    #expect(loaded.repository.worktrees.first?.id == RepositoriesFeature.remoteMainWorktree(config: config).id)
+  }
+
+  @Test func missingPathSurfacesPathNotFoundRatherThanCantReach() async {
+    let config = resolveConfig(path: "/srv/gone")
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: config)
+    let shell = routingShell(
+      worktreeList: .failure(ShellClientError(command: "git", stdout: "", stderr: "", exitCode: 1)),
+      classifyStdout: "supacode-nodir"
+    )
+    let loaded = await RepositoriesFeature.loadRemoteRepository(config, repoID: repoID, shell: shell)
+    #expect(loaded.repository.worktrees.isEmpty)
+    #expect(loaded.failure?.message.contains("was not found") == true)
+    #expect(loaded.failure?.message.contains("Can't reach") == false)
+  }
+
+  @Test func gitWorkTreeClassifiesAsGit() async {
+    let kind = await RepositoriesFeature.classifyRemotePath("/p", shell: stubShell(stdout: "supacode-git"))
+    #expect(kind == .git)
+  }
+
+  @Test func plainDirectoryClassifiesAsFolder() async {
+    let kind = await RepositoriesFeature.classifyRemotePath("/p", shell: stubShell(stdout: "supacode-folder"))
+    #expect(kind == .folder)
+  }
+
+  @Test func missingDirClassifiesAsMissingAndShellErrorAsUnknown() async {
+    // A reachable host with an absent path is `.missing`, not `.unknown`, so the
+    // failure can name the path instead of blaming the connection.
+    #expect(await RepositoriesFeature.classifyRemotePath("/p", shell: stubShell(stdout: "supacode-nodir")) == .missing)
+    #expect(await RepositoriesFeature.classifyRemotePath("/p", shell: throwingShell()) == .unknown)
+  }
+
+  @Test func resolveRemotePathReturnsRemoteCanonicalPath() async {
+    let host = RemoteHost(alias: "devbox")
+    let resolved = await RepositoriesFeature.resolveRemotePath(
+      "~/proj", host: host, shell: stubShell(stdout: "/home/me/proj\n"))
+    #expect(resolved == "/home/me/proj")
+  }
+
+  @Test func resolveRemotePathRejectsBlankAndUnreachable() async {
+    let host = RemoteHost(alias: "devbox")
+    #expect(await RepositoriesFeature.resolveRemotePath("  ", host: host, shell: stubShell(stdout: "/x")) == nil)
+    #expect(await RepositoriesFeature.resolveRemotePath("~/proj", host: host, shell: stubShell(stdout: "")) == nil)
+    #expect(await RepositoriesFeature.resolveRemotePath("~/proj", host: host, shell: throwingShell()) == nil)
+  }
+
+  @Test func resolveRemotePathIgnoresLoginShellBanner() async {
+    let host = RemoteHost(alias: "devbox")
+    // A login shell prints dotfile chatter before the probe's `pwd -P` output;
+    // the resolved path is the last line, not the banner.
+    let resolved = await RepositoriesFeature.resolveRemotePath(
+      "~/proj", host: host, shell: stubShell(stdout: "Welcome to devbox!\nmotd line 2\n/home/me/proj\n"))
+    #expect(resolved == "/home/me/proj")
+  }
+
+  @Test func classifyRemotePathIgnoresLoginShellBanner() async {
+    let kind = await RepositoriesFeature.classifyRemotePath(
+      "/p", shell: stubShell(stdout: "Welcome to devbox!\nsupacode-git\n"))
+    #expect(kind == .git)
+  }
+
+  @Test func resolveRemotePathTimesOutOnAHangingProbe() async {
+    let host = RemoteHost(alias: "devbox")
+    // A shell that never returns in time stands in for an unreachable host that
+    // accepts the connection but stalls; the timeout must reject it.
+    let hanging = ShellClient(
+      run: { _, _, _ in
+        try await Task.sleep(for: .seconds(5))
+        return ShellOutput(stdout: "/home/me/proj", stderr: "", exitCode: 0)
+      },
+      runLoginImpl: { _, _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) }
+    )
+    let resolved = await RepositoriesFeature.resolveRemotePath(
+      "~/proj", host: host, shell: hanging, timeout: .milliseconds(50))
+    #expect(resolved == nil)
+  }
+
+  @Test func parseRemoteWorktreeBaseDirectoriesExtractsPerRepoAndGlobal() throws {
+    var repoSettings = RepositorySettings.default
+    repoSettings.worktreeBaseDirectoryPath = "/srv/wt"
+    var global = GlobalSettings.default
+    global.defaultWorktreeBaseDirectoryPath = "/srv/global"
+    let repoJSON = try #require(String(bytes: try JSONEncoder().encode(repoSettings), encoding: .utf8))
+    let globalJSON = try #require(
+      String(bytes: try JSONEncoder().encode(SettingsFile(global: global)), encoding: .utf8))
+    let output = "===SUPACODE-REPO===\n\(repoJSON)\n===SUPACODE-GLOBAL===\n\(globalJSON)"
+    let result = RepositoriesFeature.parseRemoteWorktreeBaseDirectories(output)
+    #expect(result.perRepo == "/srv/wt")
+    #expect(result.global == "/srv/global")
+  }
+
+  @Test func parseRemoteWorktreeBaseDirectoriesEmptyForMissingFiles() {
+    let result = RepositoriesFeature.parseRemoteWorktreeBaseDirectories(
+      "===SUPACODE-REPO===\n===SUPACODE-GLOBAL===\n")
+    #expect(result.perRepo == nil)
+    #expect(result.global == nil)
+  }
+
+  @Test func remoteWorktreeLeafPrefersValidOverrideElseBranch() {
+    #expect(RepositoriesFeature.remoteWorktreeLeaf(nameOverride: "custom", branchName: "feature/x") == "custom")
+    #expect(RepositoriesFeature.remoteWorktreeLeaf(nameOverride: "  ", branchName: "feature/x") == "feature/x")
+    // A slash override would escape the parent, so fall back to the branch name.
+    #expect(RepositoriesFeature.remoteWorktreeLeaf(nameOverride: "a/b", branchName: "feat") == "feat")
+  }
+
+  @Test func remoteFolderRepositoryIsNonGitFolderCarryingHost() {
+    let config = TestRemoteRepo(
+      host: RemoteHost(alias: "devbox"),
+      remotePath: "/home/me/docs",
+      displayName: ""
+    )
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: config)
+    let repo = RepositoriesFeature.remoteFolderRepository(config: config, repoID: repoID)
+
+    #expect(repo.isGitRepository == false)
+    #expect(repo.host?.sshDestination == "devbox")
+    #expect(repo.worktrees.count == 1)
+    let folder = repo.worktrees.elements.first
+    // The folder synthetic shares the host-keyed repo id; `Worktree.kind` carries the
+    // folder classification, so it round-trips to the repo and never collides with a local folder.
+    #expect(folder?.id == WorktreeID(repoID.rawValue))
+    #expect(folder?.kind == .folder)
+    #expect(folder?.host?.sshDestination == "devbox")
+    #expect(folder?.workingDirectory == URL(fileURLWithPath: "/home/me/docs"))
+  }
+}
+
+/// `remoteWorktreeParentDirectory` resolves a new remote worktree's parent via a
+/// 4-tier precedence chain (explicit override > per-repo > global+repoName >
+/// repoRoot parent). It takes an injectable shell so the per-repo / global tiers
+/// can be driven from a stubbed `cat` output without touching a real host. A
+/// reorder or a dropped `.appending(path:)` on the global branch would silently
+/// mis-place worktrees with no coverage; these pin the contract.
+@MainActor
+struct RemoteWorktreeParentDirectoryTests {
+  /// Stub shell whose `cat` emits the marker-separated per-repo + global blocks
+  /// that `readRemoteWorktreeBaseDirectories` parses. Passing `nil` for either
+  /// path leaves that section empty (a missing remote file).
+  private func basesShell(perRepo: String?, global: String?) throws -> ShellClient {
+    var repoSettings = RepositorySettings.default
+    repoSettings.worktreeBaseDirectoryPath = perRepo ?? ""
+    var globalSettings = GlobalSettings.default
+    globalSettings.defaultWorktreeBaseDirectoryPath = global ?? ""
+    let repoJSON = try #require(String(bytes: try JSONEncoder().encode(repoSettings), encoding: .utf8))
+    let globalJSON = try #require(
+      String(bytes: try JSONEncoder().encode(SettingsFile(global: globalSettings)), encoding: .utf8))
+    let output = "===SUPACODE-REPO===\n\(repoJSON)\n===SUPACODE-GLOBAL===\n\(globalJSON)"
+    return ShellClient(
+      run: { _, _, _ in ShellOutput(stdout: output, stderr: "", exitCode: 0) },
+      runLoginImpl: { _, _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) }
+    )
+  }
+
+  private let host = RemoteHost(alias: "devbox")
+  private let repoRoot = URL(fileURLWithPath: "/home/me/proj")
+
+  @Test func explicitPlacementPathWinsAndShortCircuits() async throws {
+    // Even with per-repo + global configured, the explicit override wins and the
+    // shell is never consulted.
+    let parent = await RepositoriesFeature.remoteWorktreeParentDirectory(
+      host: host,
+      repoRoot: repoRoot,
+      placementPath: "/explicit/parent",
+      shell: try basesShell(perRepo: "/srv/wt", global: "/srv/global")
+    )
+    #expect(parent == URL(filePath: "/explicit/parent", directoryHint: .isDirectory))
+  }
+
+  @Test func blankExplicitPlacementFallsThroughToPerRepo() async throws {
+    // A whitespace-only override is not a placement; precedence continues.
+    let parent = await RepositoriesFeature.remoteWorktreeParentDirectory(
+      host: host,
+      repoRoot: repoRoot,
+      placementPath: "   ",
+      shell: try basesShell(perRepo: "/srv/wt", global: "/srv/global")
+    )
+    #expect(parent == URL(filePath: "/srv/wt", directoryHint: .isDirectory))
+  }
+
+  @Test func perRepoWinsOverGlobal() async throws {
+    let parent = await RepositoriesFeature.remoteWorktreeParentDirectory(
+      host: host,
+      repoRoot: repoRoot,
+      placementPath: nil,
+      shell: try basesShell(perRepo: "/srv/wt", global: "/srv/global")
+    )
+    #expect(parent == URL(filePath: "/srv/wt", directoryHint: .isDirectory))
+  }
+
+  @Test func globalAppendsRepoRootLastPathComponent() async throws {
+    // The global default is a shared base; the repo's directory name is appended
+    // so worktrees for different repos don't collide under it.
+    let parent = await RepositoriesFeature.remoteWorktreeParentDirectory(
+      host: host,
+      repoRoot: repoRoot,
+      placementPath: nil,
+      shell: try basesShell(perRepo: nil, global: "/srv/global")
+    )
+    #expect(
+      parent
+        == URL(filePath: "/srv/global", directoryHint: .isDirectory)
+        .appending(path: "proj", directoryHint: .isDirectory)
+    )
+  }
+
+  @Test func allEmptyFallsBackToRepoRootParent() async throws {
+    let parent = await RepositoriesFeature.remoteWorktreeParentDirectory(
+      host: host,
+      repoRoot: repoRoot,
+      placementPath: nil,
+      shell: try basesShell(perRepo: nil, global: nil)
+    )
+    #expect(parent == repoRoot.deletingLastPathComponent())
+  }
+}
+
+@MainActor
+struct RemoteWorktreeBaseRefTests {
+  private func emptyRemoteClient() -> GitClient {
+    let base = ShellClient(
+      run: { _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) },
+      runLoginImpl: { _, _, _, _ in ShellOutput(stdout: "", stderr: "", exitCode: 0) }
+    )
+    return GitClient(shell: .ssh(host: RemoteHost(alias: "devbox"), base: base))
+  }
+
+  @Test func explicitBaseRefIsUsedVerbatim() async {
+    let ref = await RepositoriesFeature.resolveRemoteBaseRef(
+      baseRefSource: .explicit("origin/dev"),
+      selectedBaseRef: nil,
+      client: emptyRemoteClient(),
+      repoRoot: URL(fileURLWithPath: "/repo")
+    )
+    #expect(ref == "origin/dev")
+  }
+
+  @Test func repositorySettingBaseRefIsUsed() async {
+    let ref = await RepositoriesFeature.resolveRemoteBaseRef(
+      baseRefSource: .repositorySetting,
+      selectedBaseRef: "main",
+      client: emptyRemoteClient(),
+      repoRoot: URL(fileURLWithPath: "/repo")
+    )
+    #expect(ref == "main")
+  }
+
+  @Test func delegatesToRemoteAutomaticBaseRefWhenNoExplicitSelection() async {
+    // No explicit ref / repo setting → delegate to the remote's automatic base
+    // ref (mirrors local), not a hardcoded HEAD.
+    let repoRoot = URL(fileURLWithPath: "/repo")
+    let client = emptyRemoteClient()
+    let expected = await client.automaticWorktreeBaseRef(for: repoRoot) ?? "HEAD"
+    let ref = await RepositoriesFeature.resolveRemoteBaseRef(
+      baseRefSource: .repositorySetting,
+      selectedBaseRef: "",
+      client: client,
+      repoRoot: repoRoot
+    )
+    #expect(ref == expected)
+    #expect(!ref.isEmpty)
+  }
+}
+
+/// Remote worktree creation honors `fetchOriginBeforeWorktreeCreation` the same
+/// way local does: when enabled and the base ref carries a `<remote>/` prefix,
+/// a `git fetch <remote>` is issued over ssh before `git worktree add`. The
+/// recorder stands in for the local `ssh` process; `git remote` returns a single
+/// `origin` so prefix matching resolves.
+@MainActor
+struct RemoteFetchOriginTests {
+  private func recordingRemoteClient(_ recorder: GitShellInvocationRecorder) -> GitClient {
+    let base = ShellClient(
+      run: { exe, args, cwd in
+        recorder.record(executableURL: exe, arguments: args, currentDirectoryURL: cwd)
+        return ShellOutput(stdout: "origin\n", stderr: "", exitCode: 0)
+      },
+      runLoginImpl: { _, _, _, _ in ShellOutput(stdout: "origin\n", stderr: "", exitCode: 0) }
+    )
+    return GitClient(shell: .ssh(host: RemoteHost(alias: "devbox"), base: base))
+  }
+
+  @Test func fetchesMatchingRemoteWhenEnabled() async {
+    let recorder = GitShellInvocationRecorder()
+    await RepositoriesFeature.fetchRemoteForBaseRefIfNeeded(
+      fetchOrigin: true,
+      baseRef: "origin/main",
+      client: recordingRemoteClient(recorder),
+      repoRoot: URL(fileURLWithPath: "/repo")
+    )
+    // Last ssh invocation is the fetch (it follows `git remote`).
+    let wrapped = recorder.snapshot().arguments.last ?? ""
+    #expect(wrapped.contains("fetch"))
+    #expect(wrapped.contains("origin"))
+  }
+
+  @Test func skipsFetchWhenBaseRefHasNoRemotePrefix() async {
+    let recorder = GitShellInvocationRecorder()
+    await RepositoriesFeature.fetchRemoteForBaseRefIfNeeded(
+      fetchOrigin: true,
+      baseRef: "main",
+      client: recordingRemoteClient(recorder),
+      repoRoot: URL(fileURLWithPath: "/repo")
+    )
+    // Only `git remote` ran (to list); no fetch since `main` has no `<remote>/` prefix.
+    let wrapped = recorder.snapshot().arguments.last ?? ""
+    #expect(wrapped.contains("remote"))
+    #expect(!wrapped.contains("fetch"))
+  }
+
+  @Test func skipsEverythingWhenDisabled() async {
+    let recorder = GitShellInvocationRecorder()
+    await RepositoriesFeature.fetchRemoteForBaseRefIfNeeded(
+      fetchOrigin: false,
+      baseRef: "origin/main",
+      client: recordingRemoteClient(recorder),
+      repoRoot: URL(fileURLWithPath: "/repo")
+    )
+    // The guard returns before listing remotes, so no ssh call is made at all.
+    #expect(recorder.snapshot().executableURL == nil)
+  }
+}
+
+/// In-state worktree mutations must not strip a remote repository's host or kind
+/// via a back-compat reconstruction, or a transient window would treat a remote
+/// repo as local.
+@MainActor
+struct RemoteRepositoryStateMutationTests {
+  private let host = RemoteHost(alias: "devbox", username: "me")
+
+  private func remoteWorktree(path: String, name: String) -> Worktree {
+    Worktree(
+      location: .remote(host, workingDirectory: path, repositoryRoot: "/srv/repo"),
+      kind: .git,
+      name: name,
+      detail: ""
+    )
+  }
+
+  private func makeState(worktrees: [Worktree]) -> (RepositoriesFeature.State, Repository.ID) {
+    let repo = Repository(
+      location: .remote(host, path: "/srv/repo"),
+      kind: .git,
+      name: "repo",
+      worktrees: IdentifiedArray(uniqueElements: worktrees)
+    )
+    var state = RepositoriesFeature.State()
+    state.repositories = [repo]
+    return (state, repo.id)
+  }
+
+  @Test func insertWorktreePreservesRemoteHostAndKind() {
+    let (initialState, repoID) = makeState(worktrees: [remoteWorktree(path: "/srv/repo", name: "main")])
+    var state = initialState
+    let added = remoteWorktree(path: "/srv/repo/feature", name: "feature")
+    state.insertWorktree(added, repositoryID: repoID)
+
+    let stored = state.repositories[id: repoID]
+    #expect(stored?.host == host)
+    #expect(stored?.isGitRepository == true)
+    #expect(stored?.worktrees[id: added.id]?.host == host)
+  }
+
+  @Test func removeWorktreePreservesRemoteHostAndKind() {
+    let feature = remoteWorktree(path: "/srv/repo/feature", name: "feature")
+    let (initialState, repoID) = makeState(worktrees: [remoteWorktree(path: "/srv/repo", name: "main"), feature])
+    var state = initialState
+    _ = state.removeWorktree(feature.id, repositoryID: repoID)
+
+    let stored = state.repositories[id: repoID]
+    #expect(stored?.host == host)
+    #expect(stored?.isGitRepository == true)
+    #expect(stored?.worktrees[id: feature.id] == nil)
+  }
+
+  @Test func renameWorktreePreservesRemoteHostKindAndID() {
+    let feature = remoteWorktree(path: "/srv/repo/feature", name: "feature")
+    let (initialState, repoID) = makeState(worktrees: [remoteWorktree(path: "/srv/repo", name: "main"), feature])
+    var state = initialState
+    state.updateWorktreeName(feature.id, name: "renamed")
+
+    let stored = state.repositories[id: repoID]
+    #expect(stored?.host == host)
+    #expect(stored?.isGitRepository == true)
+    let renamed = stored?.worktrees[id: feature.id]
+    #expect(renamed?.name == "renamed")
+    #expect(renamed?.host == host)
+    #expect(renamed?.id == feature.id)
+  }
+}
+
+/// Async remote resolution: the initial load renders placeholders (marked
+/// resolving) and `.remoteRepositoryResolved` flips each to loaded or "can't
+/// reach" without blocking the sidebar.
+@MainActor
+struct RemoteRepositoryResolutionTests {
+  private let host = RemoteHost(alias: "devbox")
+
+  private func config() -> TestRemoteRepo {
+    TestRemoteRepo(host: host, remotePath: "/srv/repo", displayName: "")
+  }
+
+  private func localRepository() -> Repository {
+    let root = URL(fileURLWithPath: "/tmp/localrepo")
+    let main = Worktree(
+      id: WorktreeID(root.path(percentEncoded: false)),
+      name: "main",
+      detail: "",
+      workingDirectory: root,
+      repositoryRootURL: root
+    )
+    return Repository(
+      id: RepositoryID(root.path(percentEncoded: false)),
+      rootURL: root,
+      name: "localrepo",
+      worktrees: IdentifiedArray(uniqueElements: [main])
+    )
+  }
+
+  private func resolvedRepository(repoID: Repository.ID) -> Repository {
+    let main = Worktree(
+      location: .remote(host, workingDirectory: "/srv/repo", repositoryRoot: "/srv/repo"),
+      kind: .git,
+      name: "main",
+      detail: ""
+    )
+    return Repository(
+      location: .remote(host, path: "/srv/repo"),
+      kind: .git,
+      name: "repo",
+      worktrees: IdentifiedArray(uniqueElements: [main])
+    )
+  }
+
+  private func placeholderState(repoID: Repository.ID, config: TestRemoteRepo) -> RepositoriesFeature.State {
+    var state = RepositoriesFeature.State()
+    state.isInitialLoadComplete = true
+    state.repositories = [RepositoriesFeature.remotePlaceholderRepository(config: config, repoID: repoID)]
+    state.resolvingRemoteRepositoryIDs = [repoID]
+    return state
+  }
+
+  private func withStore(
+    _ state: RepositoriesFeature.State,
+    _ body: (TestStoreOf<RepositoriesFeature>) async -> Void
+  ) async {
+    let storage = SettingsTestStorage()
+    await withDependencies {
+      $0.settingsFileStorage = storage.storage
+      $0.settingsFileURL = URL(fileURLWithPath: "/tmp/supacode-remote-resolve-\(UUID().uuidString).json")
+      $0.sidebarStructureAutoRecompute = false
+    } operation: {
+      let store = TestStore(initialState: state) { RepositoriesFeature() }
+      store.exhaustivity = .off
+      await body(store)
+    }
+  }
+
+  private func withExhaustiveStore(
+    _ state: RepositoriesFeature.State,
+    _ body: (TestStoreOf<RepositoriesFeature>) async -> Void
+  ) async {
+    let storage = SettingsTestStorage()
+    await withDependencies {
+      $0.settingsFileStorage = storage.storage
+      $0.settingsFileURL = URL(fileURLWithPath: "/tmp/supacode-remote-resolve-\(UUID().uuidString).json")
+      $0.sidebarStructureAutoRecompute = false
+    } operation: {
+      let store = TestStore(initialState: state) { RepositoriesFeature() }
+      await body(store)
+    }
+  }
+
+  @Test(.dependencies) func resolvedRemoteReplacesPlaceholderAndClearsResolving() async {
+    let cfg = config()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: cfg)
+    await withStore(placeholderState(repoID: repoID, config: cfg)) { store in
+      await store.send(
+        .remoteRepositoryResolved(
+          repositoryID: repoID,
+          repository: resolvedRepository(repoID: repoID),
+          failureMessage: nil
+        )
+      )
+      await store.finish()
+      #expect(store.state.repositories[id: repoID]?.worktrees.isEmpty == false)
+      #expect(store.state.resolvingRemoteRepositoryIDs.contains(repoID) == false)
+      #expect(store.state.loadFailuresByID[repoID] == nil)
+    }
+  }
+
+  @Test(.dependencies) func unreachableRemoteRecordsLoadFailureAndKeepsPlaceholder() async {
+    let cfg = config()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: cfg)
+    await withStore(placeholderState(repoID: repoID, config: cfg)) { store in
+      await store.send(
+        .remoteRepositoryResolved(
+          repositoryID: repoID,
+          repository: RepositoriesFeature.remotePlaceholderRepository(config: cfg, repoID: repoID),
+          failureMessage: "Can't reach devbox."
+        )
+      )
+      await store.finish()
+      #expect(store.state.repositories[id: repoID]?.worktrees.isEmpty == true)
+      #expect(store.state.resolvingRemoteRepositoryIDs.contains(repoID) == false)
+      #expect(store.state.loadFailuresByID[repoID] == "Can't reach devbox.")
+    }
+  }
+
+  @Test(.dependencies) func staleRemoteResolutionDoesNotReplaceNonResolvingRemote() async {
+    let cfg = config()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: cfg)
+    let resolved = resolvedRepository(repoID: repoID)
+    var state = RepositoriesFeature.State()
+    state.isInitialLoadComplete = true
+    state.repositories = [resolved]
+    await withExhaustiveStore(state) { store in
+      await store.send(
+        .remoteRepositoryResolved(
+          repositoryID: repoID,
+          repository: RepositoriesFeature.remotePlaceholderRepository(config: cfg, repoID: repoID),
+          failureMessage: "Can't reach devbox."
+        )
+      )
+      await store.finish()
+      #expect(store.state.repositories[id: repoID] == resolved)
+      #expect(store.state.loadFailuresByID[repoID] == nil)
+      #expect(store.state.resolvingRemoteRepositoryIDs.contains(repoID) == false)
+    }
+  }
+
+  @Test(.dependencies) func freshSuccessSurvivesLateStaleFailureInSameIdRace() async {
+    let cfg = config()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: cfg)
+    await withStore(placeholderState(repoID: repoID, config: cfg)) { store in
+      // The fresh probe wins first and resolves the placeholder.
+      await store.send(
+        .remoteRepositoryResolved(
+          repositoryID: repoID,
+          repository: resolvedRepository(repoID: repoID),
+          failureMessage: nil
+        )
+      )
+      // A superseded "can't reach" lands late; it must not drop the resolved remote.
+      await store.send(
+        .remoteRepositoryResolved(
+          repositoryID: repoID,
+          repository: RepositoriesFeature.remotePlaceholderRepository(config: cfg, repoID: repoID),
+          failureMessage: "Can't reach devbox."
+        )
+      )
+      await store.finish()
+      #expect(store.state.repositories[id: repoID]?.worktrees.isEmpty == false)
+      #expect(store.state.loadFailuresByID[repoID] == nil)
+      #expect(store.state.resolvingRemoteRepositoryIDs.contains(repoID) == false)
+    }
+  }
+
+  @Test(.dependencies) func staleFailureThenFreshSuccessResolvesRemote() async {
+    let cfg = config()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: cfg)
+    await withStore(placeholderState(repoID: repoID, config: cfg)) { store in
+      // An early probe fails while resolving: the placeholder records the failure.
+      await store.send(
+        .remoteRepositoryResolved(
+          repositoryID: repoID,
+          repository: RepositoriesFeature.remotePlaceholderRepository(config: cfg, repoID: repoID),
+          failureMessage: "Can't reach devbox."
+        )
+      )
+      #expect(store.state.loadFailuresByID[repoID] == "Can't reach devbox.")
+      // The guard only blocks empty-over-non-empty, so a later success still resolves.
+      await store.send(
+        .remoteRepositoryResolved(
+          repositoryID: repoID,
+          repository: resolvedRepository(repoID: repoID),
+          failureMessage: nil
+        )
+      )
+      await store.finish()
+      #expect(store.state.repositories[id: repoID]?.worktrees.isEmpty == false)
+      #expect(store.state.loadFailuresByID[repoID] == nil)
+      #expect(store.state.resolvingRemoteRepositoryIDs.contains(repoID) == false)
+    }
+  }
+
+  @Test(.dependencies) func previouslyFailedRemoteIsRetriedOnNextLoad() async {
+    let cfg = config()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: cfg)
+    var state = RepositoriesFeature.State()
+    state.isInitialLoadComplete = true
+    state.repositories = [RepositoriesFeature.remotePlaceholderRepository(config: cfg, repoID: repoID)]
+    state.loadFailuresByID = [repoID: "Can't reach devbox."]
+    await withStore(state) { store in
+      @Shared(.settingsFile) var settingsFile
+      $settingsFile.withLock { $0.remoteRepositoryRoots = [cfg.id.rawValue] }
+
+      await store.send(.repositoriesLoaded([], failures: [], roots: [], animated: false))
+      // An unreachable remote keeps its empty placeholder, so the next load retries it.
+      #expect(store.state.resolvingRemoteRepositoryIDs.contains(repoID))
+      await store.finish()
+    }
+  }
+
+  @Test(.dependencies) func repositoriesLoadedSeedsPlaceholderAndMarksResolving() async {
+    let cfg = config()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: cfg)
+    var state = RepositoriesFeature.State()
+    await withStore(state) { store in
+      @Shared(.settingsFile) var settingsFile
+      $settingsFile.withLock { $0.remoteRepositoryRoots = [cfg.id.rawValue] }
+
+      await store.send(.repositoriesLoaded([], failures: [], roots: [], animated: false))
+      // The remote shows up immediately as a resolving placeholder, before SSH.
+      #expect(store.state.repositories[id: repoID]?.worktrees.isEmpty == true)
+      #expect(store.state.resolvingRemoteRepositoryIDs.contains(repoID))
+      #expect(store.state.loadFailuresByID[repoID] == nil)
+      // Drain the background resolution effect (probe fails fast for a fake host).
+      await store.finish()
+    }
+    _ = state
+  }
+
+  @Test(.dependencies) func repositoriesLoadedReprobesResolvedRemoteWithoutDropping() async {
+    let cfg = config()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: cfg)
+    let resolved = resolvedRepository(repoID: repoID)
+    var state = RepositoriesFeature.State()
+    state.isInitialLoadComplete = true
+    state.repositories = [resolved]
+    state.reconcileSidebarForTesting()
+    await withStore(state) { store in
+      @Shared(.settingsFile) var settingsFile
+      $settingsFile.withLock { $0.remoteRepositoryRoots = [cfg.id.rawValue] }
+
+      await store.send(.repositoriesLoaded([], failures: [], roots: [], animated: false))
+      // A reload re-probes without marking the remote resolving, so the row stays put.
+      #expect(store.state.repositories[id: repoID] == resolved)
+      #expect(store.state.resolvingRemoteRepositoryIDs.contains(repoID) == false)
+      // The fake host probe fails fast; the guard keeps the resolved repo.
+      await store.finish()
+      #expect(store.state.repositories[id: repoID] == resolved)
+      #expect(store.state.loadFailuresByID[repoID] == nil)
+    }
+  }
+
+  @Test(.dependencies) func openRepositoriesFinishedDoesNotResolveAlreadyResolvedRemote() async {
+    let cfg = config()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: cfg)
+    let local = localRepository()
+    let resolved = resolvedRepository(repoID: repoID)
+    var state = RepositoriesFeature.State()
+    state.isInitialLoadComplete = true
+    state.repositories = [resolved]
+    state.reconcileSidebarForTesting()
+    await withExhaustiveStore(state) { store in
+      @Shared(.settingsFile) var settingsFile
+      $settingsFile.withLock { $0.remoteRepositoryRoots = [cfg.id.rawValue] }
+
+      await store.send(
+        .openRepositoriesFinished([local], failures: [], invalidRoots: [], roots: [local.rootURL])
+      ) {
+        $0.repositories = [local, resolved]
+        $0.repositoryRoots = [local.rootURL]
+        $0.reconcileSidebarState(roots: [local.rootURL], pruneLivenessAgainstRoster: true)
+        RepositoriesFeature.syncSidebar(&$0)
+      }
+      await store.receive(\.delegate.repositoriesChanged)
+      await store.finish()
+      #expect(store.state.resolvingRemoteRepositoryIDs.contains(repoID) == false)
+    }
+  }
+
+  @Test(.dependencies) func openRepositoriesFinishedPreservesResolvedRemoteRepository() async {
+    let cfg = config()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: cfg)
+    let local = localRepository()
+    var state = RepositoriesFeature.State()
+    state.isInitialLoadComplete = true
+    state.repositories = [resolvedRepository(repoID: repoID)]
+    await withStore(state) { store in
+      @Shared(.settingsFile) var settingsFile
+      $settingsFile.withLock { $0.remoteRepositoryRoots = [cfg.id.rawValue] }
+
+      await store.send(
+        .openRepositoriesFinished([local], failures: [], invalidRoots: [], roots: [local.rootURL])
+      )
+
+      #expect(store.state.repositories[id: local.id] != nil)
+      #expect(store.state.repositories[id: repoID]?.worktrees.isEmpty == false)
+      #expect(store.state.resolvingRemoteRepositoryIDs.contains(repoID) == false)
+      await store.finish()
+    }
+  }
+
+  @Test(.dependencies) func repositoriesLoadedDedupesIncomingRemoteRepository() async {
+    let cfg = config()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: cfg)
+    let local = localRepository()
+    let remote = resolvedRepository(repoID: repoID)
+    var state = RepositoriesFeature.State()
+    state.isInitialLoadComplete = true
+    state.repositories = [remote]
+    await withStore(state) { store in
+      @Shared(.settingsFile) var settingsFile
+      $settingsFile.withLock { $0.remoteRepositoryRoots = [cfg.id.rawValue] }
+
+      await store.send(
+        .repositoriesLoaded([local, remote], failures: [], roots: [local.rootURL], animated: false)
+      )
+
+      let ids = store.state.repositories.map(\.id)
+      #expect(ids.filter { $0 == repoID }.count == 1)
+      #expect(ids.contains(local.id))
+      await store.finish()
+    }
+  }
+
+  @Test(.dependencies) func resolvedRemoteIgnoredWhenRepoAbsent() async {
+    let cfg = config()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: cfg)
+    // The config was removed (or re-keyed) mid-flight: marked resolving, no repo.
+    var state = RepositoriesFeature.State()
+    state.resolvingRemoteRepositoryIDs = [repoID]
+    await withStore(state) { store in
+      await store.send(
+        .remoteRepositoryResolved(
+          repositoryID: repoID,
+          repository: resolvedRepository(repoID: repoID),
+          failureMessage: nil
+        )
+      )
+      await store.finish()
+      // A late result for a gone repo is dropped, but the resolving flag clears.
+      #expect(store.state.repositories[id: repoID] == nil)
+      #expect(store.state.loadFailuresByID[repoID] == nil)
+      #expect(store.state.resolvingRemoteRepositoryIDs.contains(repoID) == false)
+    }
+  }
+
+  @Test(.dependencies) func reloadReusesResolvedRemoteWithoutRespinning() async {
+    let cfg = config()
+    let repoID = RepositoriesFeature.remoteRepositoryID(for: cfg)
+    var state = RepositoriesFeature.State()
+    state.isInitialLoadComplete = true
+    state.repositories = [resolvedRepository(repoID: repoID)]
+    await withStore(state) { store in
+      @Shared(.settingsFile) var settingsFile
+      $settingsFile.withLock { $0.remoteRepositoryRoots = [cfg.id.rawValue] }
+
+      await store.send(.repositoriesLoaded([], failures: [], roots: [], animated: false))
+      // The already-resolved remote keeps its worktrees and is not re-spun.
+      #expect(store.state.repositories[id: repoID]?.worktrees.isEmpty == false)
+      #expect(store.state.resolvingRemoteRepositoryIDs.contains(repoID) == false)
+      await store.finish()
+    }
+    _ = state
+  }
+}
diff --git a/supacodeTests/RemoteSSHCommandTests.swift b/supacodeTests/RemoteSSHCommandTests.swift
new file mode 100644
index 000000000..f7db0439a
--- /dev/null
+++ b/supacodeTests/RemoteSSHCommandTests.swift
@@ -0,0 +1,260 @@
+import Foundation
+import Testing
+
+@testable import SupacodeSettingsShared
+@testable import supacode
+
+struct RemoteHostTests {
+  @Test func bareAliasHasNoUserOrPortOptions() {
+    let host = RemoteHost(alias: "devbox")
+    #expect(host.sshDestination == "devbox")
+    #expect(host.sshOptionArguments.isEmpty)
+  }
+
+  @Test func usernameAndPortProjectIntoDestinationAndOptions() {
+    let host = RemoteHost(alias: "box", username: "alice", port: 2222)
+    #expect(host.sshDestination == "alice@box")
+    #expect(host.sshOptionArguments == ["-p", "2222"])
+  }
+
+  @Test func emptyUsernameFallsBackToBareAlias() {
+    let host = RemoteHost(alias: "box", username: "")
+    #expect(host.sshDestination == "box")
+  }
+}
+
+struct SSHCommandTests {
+  @Test func shellQuoteWrapsAndEscapesSingleQuotes() {
+    #expect(SSHCommand.shellQuote("echo hi") == "'echo hi'")
+    #expect(SSHCommand.shellQuote("echo 'hi'") == "'echo '\\''hi'\\'''")
+  }
+
+  @Test func remoteCommandWithoutWorkingDirectoryQuotesEachToken() {
+    let command = SSHCommand.remoteCommand(
+      executable: "git",
+      arguments: ["status", "--short"],
+      workingDirectory: nil
+    )
+    #expect(command == "'git' 'status' '--short'")
+  }
+
+  @Test func remoteCommandWithWorkingDirectoryPrependsCdAndExec() {
+    let command = SSHCommand.remoteCommand(
+      executable: "/usr/bin/env",
+      arguments: ["git", "status"],
+      workingDirectory: URL(fileURLWithPath: "/tmp/repo")
+    )
+    #expect(command == "cd -- '/tmp/repo' && exec '/usr/bin/env' 'git' 'status'")
+  }
+
+  @Test func loginShellWrappedExecsLoginShellWithQuotedScript() {
+    #expect(SSHCommand.loginShellWrapped("zmx attach s") == "exec \"$SHELL\" -l -c 'zmx attach s'")
+    #expect(SSHCommand.loginShellWrapped("echo 'hi'") == "exec \"$SHELL\" -l -c 'echo '\\''hi'\\'''")
+  }
+
+  @Test func loginShellWrappedQuotesEachPositionalArgumentSeparately() {
+    // A payload containing a single quote and a space must ride as a quoted positional arg,
+    // never interpolated into the script text.
+    #expect(
+      SSHCommand.loginShellWrapped("$0 \"$@\"", positionalArguments: ["claude", "it's a test"])
+        == "exec \"$SHELL\" -l -c '$0 \"$@\"' 'claude' 'it'\\''s a test'"
+    )
+  }
+
+  @Test func loginShellWrappedPrefixesEnvironmentBeforeLoginShell() {
+    // Sorted, each value quoted; the `env` prefix sets the vars before `$SHELL`
+    // so the login shell inherits them before sourcing its profile.
+    #expect(
+      SSHCommand.loginShellWrapped(
+        "$0 \"$@\"",
+        positionalArguments: ["claude"],
+        environment: ["SUPACODE_SCRIPT_KIND": "run", "SUPACODE_BLOCKING_SCRIPT": "1"]
+      ) == "exec env SUPACODE_BLOCKING_SCRIPT='1' SUPACODE_SCRIPT_KIND='run' \"$SHELL\" -l -c '$0 \"$@\"' 'claude'"
+    )
+  }
+
+  @Test func loginShellWrappedWithEmptyEnvironmentHasNoEnvPrefix() {
+    #expect(
+      SSHCommand.loginShellWrapped("$0", positionalArguments: ["x"], environment: [:])
+        == "exec \"$SHELL\" -l -c '$0' 'x'"
+    )
+  }
+
+  @Test func invocationWrapsRemoteCommandInLoginShellAfterMultiplexingOptions() {
+    let result = SSHCommand.invocation(
+      host: RemoteHost(alias: "devbox"),
+      executable: "/usr/bin/env",
+      arguments: ["git", "-C", "/tmp/repo", "status"],
+      workingDirectory: URL(fileURLWithPath: "/tmp/repo")
+    )
+    #expect(result.executableURL == URL(fileURLWithPath: "/usr/bin/ssh"))
+    let expectedScript = SSHCommand.remoteCommand(
+      executable: "/usr/bin/env",
+      arguments: ["git", "-C", "/tmp/repo", "status"],
+      workingDirectory: URL(fileURLWithPath: "/tmp/repo")
+    )
+    #expect(
+      result.arguments == [
+        "-o", "ControlMaster=auto",
+        "-o", "ControlPath=~/.ssh/supacode-%C",
+        "-o", "ControlPersist=10m",
+        "devbox",
+        SSHCommand.loginShellWrapped(expectedScript),
+      ]
+    )
+    // The wrapped arg actually carries the git invocation under a login shell.
+    #expect(result.arguments.last?.hasPrefix("exec \"$SHELL\" -l -c ") == true)
+    #expect(result.arguments.last?.contains("git") == true)
+  }
+
+  @Test func invocationAllocatesTTYAndForwardsPortWhenRequested() {
+    let result = SSHCommand.invocation(
+      host: RemoteHost(alias: "box", username: "alice", port: 2222),
+      executable: "zmx",
+      arguments: ["ls"],
+      workingDirectory: nil,
+      allocateTTY: true
+    )
+    #expect(
+      result.arguments == [
+        "-o", "ControlMaster=auto",
+        "-o", "ControlPath=~/.ssh/supacode-%C",
+        "-o", "ControlPersist=10m",
+        "-tt",
+        "-p", "2222",
+        "alice@box",
+        SSHCommand.loginShellWrapped("'zmx' 'ls'"),
+      ]
+    )
+  }
+
+  @Test func commandLineWrapsRemoteCommandInLoginShellQuotedForLocalShell() {
+    let line = SSHCommand.commandLine(
+      host: RemoteHost(alias: "devbox"),
+      remoteCommand: "zmx attach supa-x"
+    )
+    let expectedTail = SSHCommand.shellQuote(SSHCommand.loginShellWrapped("zmx attach supa-x"))
+    #expect(
+      line
+        == "/usr/bin/ssh -o ControlMaster=auto -o ControlPath=~/.ssh/supacode-%C -o ControlPersist=10m -tt devbox "
+        + expectedTail
+    )
+  }
+
+  @Test func commandLineForwardsPositionalArgumentsQuotedForLocalShell() {
+    // A payload containing a single quote and a space rides as a positional arg, double-quoted
+    // for the local shell on top of the inner per-arg quoting.
+    let line = SSHCommand.commandLine(
+      host: RemoteHost(alias: "devbox"),
+      remoteScript: "$0 \"$@\"",
+      positionalArguments: ["claude", "it's a test"]
+    )
+    let expectedTail = SSHCommand.shellQuote(
+      SSHCommand.loginShellWrapped("$0 \"$@\"", positionalArguments: ["claude", "it's a test"])
+    )
+    #expect(
+      line
+        == "/usr/bin/ssh -o ControlMaster=auto -o ControlPath=~/.ssh/supacode-%C -o ControlPersist=10m -tt devbox "
+        + expectedTail
+    )
+  }
+}
+
+struct ZmxAttachRemoteTests {
+  private let surfaceID = UUID(uuidString: "00000000-0000-0000-0000-0000000000AB")!
+  // Surface-id export plus the beta banner, the fixed prefix of every remote command.
+  private var surfacePrelude: String {
+    "export SUPACODE_SURFACE_ID='\(surfaceID.uuidString)'; " + ZmxAttach.betaBanner
+  }
+  private let localZmx = "/Applications/Supacode.app/Contents/MacOS/zmx"
+
+  @Test func remoteShellCommandWithoutUserCommandExportsSurfaceThenExecsLoginShell() {
+    #expect(
+      ZmxAttach.remoteShellCommand(userCommand: nil, surfaceID: surfaceID)
+        == surfacePrelude + "exec \"$SHELL\" -l"
+    )
+  }
+
+  @Test func remoteShellCommandIgnoresWhitespaceUserCommand() {
+    #expect(
+      ZmxAttach.remoteShellCommand(userCommand: "  \n", surfaceID: surfaceID)
+        == surfacePrelude + "exec \"$SHELL\" -l"
+    )
+  }
+
+  @Test func remoteShellCommandRunsUserCommandDirectly() {
+    // No zmx on the remote: the command runs straight under the remote login shell.
+    #expect(
+      ZmxAttach.remoteShellCommand(userCommand: "claude --resume", surfaceID: surfaceID)
+        == surfacePrelude + "claude --resume"
+    )
+  }
+
+  @Test func remoteShellCommandPrintsBetaBannerAtConnection() {
+    let command = ZmxAttach.remoteShellCommand(userCommand: nil, surfaceID: surfaceID)
+    #expect(command.contains("beta"))
+    // Banner precedes the shell so it lands at the top on connect.
+    let bannerIndex = command.range(of: "beta")?.lowerBound
+    let shellIndex = command.range(of: "exec ")?.lowerBound
+    #expect(bannerIndex != nil && shellIndex != nil && bannerIndex! < shellIndex!)
+  }
+
+  @Test func buildRemoteCommandWrapsSSHInLocalZmxWithoutReverseForward() {
+    let host = RemoteHost(alias: "devbox")
+    let sshLine = SSHCommand.commandLine(
+      host: host,
+      remoteCommand: ZmxAttach.remoteShellCommand(userCommand: nil, surfaceID: surfaceID)
+    )
+    let command = ZmxAttach.buildRemoteCommand(
+      host: host,
+      localZmxExecutablePath: localZmx,
+      sessionID: "supa-deadbeef",
+      userCommand: nil,
+      surfaceID: surfaceID
+    )
+    // Local zmx owns the session; its child process is the whole ssh line.
+    #expect(
+      command
+        == ZmxAttach.buildCommand(executablePath: localZmx, sessionID: "supa-deadbeef", userCommand: sshLine)
+    )
+    #expect(command.contains("attach supa-deadbeef"))
+    #expect(command.contains(localZmx))
+    #expect(command.contains("SUPACODE_SURFACE_ID="))
+    // The remote never runs zmx.
+    #expect(!command.contains("zmx attach"))
+    // Presence rides the OSC stream now, with no reverse socket / remote socket path.
+    #expect(!command.contains("-R "))
+    #expect(!command.contains("SUPACODE_SOCKET_PATH"))
+  }
+
+  @Test func buildRemoteCommandFallsBackToBareSSHWhenLocalZmxUnavailable() {
+    let host = RemoteHost(alias: "devbox")
+    let command = ZmxAttach.buildRemoteCommand(
+      host: host,
+      localZmxExecutablePath: nil,
+      sessionID: "supa-x",
+      userCommand: nil,
+      surfaceID: surfaceID
+    )
+    #expect(
+      command
+        == SSHCommand.commandLine(
+          host: host,
+          remoteCommand: ZmxAttach.remoteShellCommand(userCommand: nil, surfaceID: surfaceID)
+        )
+    )
+    #expect(!command.contains("attach "))
+  }
+
+  @Test func buildRemoteCommandForwardsUsernameAndPort() {
+    let host = RemoteHost(alias: "box", username: "alice", port: 2222)
+    let command = ZmxAttach.buildRemoteCommand(
+      host: host,
+      localZmxExecutablePath: localZmx,
+      sessionID: "supa-x",
+      userCommand: nil,
+      surfaceID: surfaceID
+    )
+    #expect(command.contains("-p 2222 alice@box "))
+  }
+}
diff --git a/supacodeTests/RenameBranchFeatureTests.swift b/supacodeTests/RenameBranchFeatureTests.swift
index b31fab263..f5d493532 100644
--- a/supacodeTests/RenameBranchFeatureTests.swift
+++ b/supacodeTests/RenameBranchFeatureTests.swift
@@ -17,6 +17,7 @@ struct RenameBranchFeatureTests {
       worktreeID: "/tmp/rename-repo/feature-old",
       repositoryID: "/tmp/rename-repo",
       repositoryRootURL: repoRoot,
+      host: nil,
       currentName: currentName
     )
     if let newName {
diff --git a/supacodeTests/RepositoriesFeatureCustomizationTests.swift b/supacodeTests/RepositoriesFeatureCustomizationTests.swift
index fd0c346ef..78239c609 100644
--- a/supacodeTests/RepositoriesFeatureCustomizationTests.swift
+++ b/supacodeTests/RepositoriesFeatureCustomizationTests.swift
@@ -11,21 +11,21 @@ import Testing
 @MainActor
 @Suite(.serialized)
 struct RepositoriesFeatureCustomizationTests {
-  private let repoID = "/tmp/customize-repo"
+  private let repoID: RepositoryID = "/tmp/customize-repo"
 
   private func makeInitialState(
     isGitRepository: Bool = true,
   ) -> RepositoriesFeature.State {
     let worktree = Worktree(
-      id: "\(repoID)/main",
+      id: WorktreeID("\(repoID)/main"),
       name: "main",
       detail: "detail",
-      workingDirectory: URL(fileURLWithPath: repoID),
-      repositoryRootURL: URL(fileURLWithPath: repoID),
+      workingDirectory: URL(fileURLWithPath: repoID.rawValue),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue),
     )
     let repository = Repository(
       id: repoID,
-      rootURL: URL(fileURLWithPath: repoID),
+      rootURL: URL(fileURLWithPath: repoID.rawValue),
       name: "customize-repo",
       worktrees: IdentifiedArray(uniqueElements: [worktree]),
       isGitRepository: isGitRepository,
diff --git a/supacodeTests/RepositoriesFeatureRenameBranchTests.swift b/supacodeTests/RepositoriesFeatureRenameBranchTests.swift
index 64629176f..8d48d993a 100644
--- a/supacodeTests/RepositoriesFeatureRenameBranchTests.swift
+++ b/supacodeTests/RepositoriesFeatureRenameBranchTests.swift
@@ -11,7 +11,7 @@ import Testing
 @MainActor
 @Suite(.serialized)
 struct RepositoriesFeatureRenameBranchTests {
-  private let repoID = "/tmp/rename-repo"
+  private let repoID: RepositoryID = "/tmp/rename-repo"
 
   private func makeInitialState(
     worktreeName: String = "feature/old",
@@ -20,25 +20,25 @@ struct RepositoriesFeatureRenameBranchTests {
     isAttached: Bool = true
   ) -> RepositoriesFeature.State {
     let mainWorktree = Worktree(
-      id: "\(repoID)/main",
+      id: WorktreeID("\(repoID)/main"),
       name: "main",
       detail: "main",
-      workingDirectory: URL(fileURLWithPath: repoID),
-      repositoryRootURL: URL(fileURLWithPath: repoID),
+      workingDirectory: URL(fileURLWithPath: repoID.rawValue),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue),
       isMissing: false
     )
     let worktree = Worktree(
-      id: "\(repoID)/feature-old",
+      id: WorktreeID("\(repoID)/feature-old"),
       name: worktreeName,
       detail: "feature-old",
       workingDirectory: URL(fileURLWithPath: "\(repoID)/feature-old"),
-      repositoryRootURL: URL(fileURLWithPath: repoID),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue),
       isMissing: isMissing,
       isAttached: isAttached
     )
     let repository = Repository(
       id: repoID,
-      rootURL: URL(fileURLWithPath: repoID),
+      rootURL: URL(fileURLWithPath: repoID.rawValue),
       name: "rename-repo",
       worktrees: IdentifiedArray(uniqueElements: [mainWorktree, worktree]),
       isGitRepository: isGitRepository
@@ -55,39 +55,83 @@ struct RepositoriesFeatureRenameBranchTests {
       RepositoriesFeature()
     }
 
-    await store.send(.requestRenameBranch("\(repoID)/feature-old", repoID)) {
+    await store.send(.requestRenameBranch(WorktreeID("\(repoID)/feature-old"), repoID)) {
       $0.renameBranchPrompt = RenameBranchFeature.State(
-        worktreeID: "\(self.repoID)/feature-old",
+        worktreeID: WorktreeID("\(self.repoID)/feature-old"),
         repositoryID: self.repoID,
-        repositoryRootURL: URL(fileURLWithPath: self.repoID),
+        repositoryRootURL: URL(fileURLWithPath: self.repoID.rawValue),
+        host: nil,
         currentName: "feature/old"
       )
     }
   }
 
+  @Test func requestRenameBranchSeedsHostForRemoteWorktree() async {
+    let config = TestRemoteRepo(
+      host: RemoteHost(alias: "devbox"),
+      remotePath: "/home/me/proj",
+      displayName: "proj"
+    )
+    let remoteRepoID = RepositoriesFeature.remoteRepositoryID(for: config)
+    let main = RepositoriesFeature.remoteMainWorktree(config: config)
+    // An attached (renameable) remote worktree, unlike the detached main.
+    let feature = Worktree(
+      id: RepositoriesFeature.remoteWorktreeID(host: config.host, worktreePath: "/home/me/proj/feature"),
+      name: "feature",
+      detail: config.host.sshDestination,
+      workingDirectory: URL(fileURLWithPath: "/home/me/proj/feature"),
+      repositoryRootURL: URL(fileURLWithPath: config.normalizedRemotePath),
+      isAttached: true,
+      host: config.host
+    )
+    let repository = Repository(
+      id: remoteRepoID,
+      rootURL: URL(fileURLWithPath: config.normalizedRemotePath),
+      name: config.resolvedDisplayName,
+      worktrees: IdentifiedArray(uniqueElements: [main, feature]),
+      isGitRepository: true,
+      host: config.host
+    )
+    var initial = RepositoriesFeature.State()
+    initial.repositories = IdentifiedArray(uniqueElements: [repository])
+    initial.reconcileSidebarForTesting()
+
+    let store = TestStore(initialState: initial) {
+      RepositoriesFeature()
+    }
+    store.exhaustivity = .off
+
+    // The prompt must carry the host so validation / availability / rename run
+    // on the SSH host, not the local machine.
+    await store.send(.requestRenameBranch(feature.id, remoteRepoID))
+    #expect(store.state.renameBranchPrompt?.host == config.host)
+    #expect(store.state.renameBranchPrompt?.worktreeID == feature.id)
+  }
+
   @Test func requestRenameBranchNoOpsForFolderRepo() async {
     let store = TestStore(initialState: makeInitialState(isGitRepository: false)) {
       RepositoriesFeature()
     }
-    await store.send(.requestRenameBranch("\(repoID)/feature-old", repoID))
+    await store.send(.requestRenameBranch(WorktreeID("\(repoID)/feature-old"), repoID))
   }
 
   @Test func requestRenameBranchNoOpsForMissingWorktree() async {
     let store = TestStore(initialState: makeInitialState(isMissing: true)) {
       RepositoriesFeature()
     }
-    await store.send(.requestRenameBranch("\(repoID)/feature-old", repoID))
+    await store.send(.requestRenameBranch(WorktreeID("\(repoID)/feature-old"), repoID))
   }
 
   @Test func requestRenameBranchSeedsPromptForMainWorktree() async {
     let store = TestStore(initialState: makeInitialState()) {
       RepositoriesFeature()
     }
-    await store.send(.requestRenameBranch("\(repoID)/main", repoID)) {
+    await store.send(.requestRenameBranch(WorktreeID("\(repoID)/main"), repoID)) {
       $0.renameBranchPrompt = RenameBranchFeature.State(
-        worktreeID: "\(self.repoID)/main",
+        worktreeID: WorktreeID("\(self.repoID)/main"),
         repositoryID: self.repoID,
-        repositoryRootURL: URL(fileURLWithPath: self.repoID),
+        repositoryRootURL: URL(fileURLWithPath: self.repoID.rawValue),
+        host: nil,
         currentName: "main"
       )
     }
@@ -96,9 +140,10 @@ struct RepositoriesFeatureRenameBranchTests {
   @Test func renamedDelegateUpdatesWorktreeAndDispatchesScopedPullRequestRefresh() async {
     var initial = makeInitialState()
     initial.renameBranchPrompt = RenameBranchFeature.State(
-      worktreeID: "\(repoID)/feature-old",
+      worktreeID: WorktreeID("\(repoID)/feature-old"),
       repositoryID: repoID,
-      repositoryRootURL: URL(fileURLWithPath: repoID),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue),
+      host: nil,
       currentName: "feature/old"
     )
     let store = TestStore(initialState: initial) {
@@ -111,7 +156,7 @@ struct RepositoriesFeatureRenameBranchTests {
         .presented(
           .delegate(
             .renamed(
-              worktreeID: "\(repoID)/feature-old",
+              worktreeID: WorktreeID("\(repoID)/feature-old"),
               repositoryID: repoID,
               newName: "feature/new"
             )
@@ -120,7 +165,7 @@ struct RepositoriesFeatureRenameBranchTests {
       )
     ) {
       $0.renameBranchPrompt = nil
-      $0.updateWorktreeName("\(self.repoID)/feature-old", name: "feature/new")
+      $0.updateWorktreeName(WorktreeID("\(self.repoID)/feature-old"), name: "feature/new")
     }
 
     await store.receive(\.worktreeInfoEvent)
@@ -129,18 +174,19 @@ struct RepositoriesFeatureRenameBranchTests {
     // sidebar item and the structure cache, not just the underlying Worktree.
     #expect(
       store.state.repositories[id: repoID]?
-        .worktrees[id: "\(repoID)/feature-old"]?.name == "feature/new"
+        .worktrees[id: WorktreeID("\(repoID)/feature-old")]?.name == "feature/new"
     )
-    #expect(store.state.sidebarItems[id: "\(repoID)/feature-old"]?.name == "feature/new")
-    #expect(store.state.sidebarItems[id: "\(repoID)/feature-old"]?.branchName == "feature/new")
+    #expect(store.state.sidebarItems[id: WorktreeID("\(repoID)/feature-old")]?.name == "feature/new")
+    #expect(store.state.sidebarItems[id: WorktreeID("\(repoID)/feature-old")]?.branchName == "feature/new")
   }
 
   @Test func lifecyclePendingDoesNotCloseRenameSheet() async {
     var initial = makeInitialState()
     initial.renameBranchPrompt = RenameBranchFeature.State(
-      worktreeID: "\(repoID)/feature-old",
+      worktreeID: WorktreeID("\(repoID)/feature-old"),
       repositoryID: repoID,
-      repositoryRootURL: URL(fileURLWithPath: repoID),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue),
+      host: nil,
       currentName: "feature/old"
     )
     let store = TestStore(initialState: initial) {
@@ -150,7 +196,7 @@ struct RepositoriesFeatureRenameBranchTests {
 
     await store.send(
       .sidebarItems(
-        .element(id: "\(repoID)/feature-old", action: .lifecycleChanged(.pending))
+        .element(id: WorktreeID("\(repoID)/feature-old"), action: .lifecycleChanged(.pending))
       )
     )
     #expect(store.state.renameBranchPrompt != nil)
@@ -160,31 +206,32 @@ struct RepositoriesFeatureRenameBranchTests {
     let store = TestStore(initialState: makeInitialState(isAttached: false)) {
       RepositoriesFeature()
     }
-    await store.send(.requestRenameBranch("\(repoID)/feature-old", repoID))
+    await store.send(.requestRenameBranch(WorktreeID("\(repoID)/feature-old"), repoID))
   }
 
   @Test func requestRenameBranchNoOpsForNonexistentRepository() async {
     let store = TestStore(initialState: makeInitialState()) {
       RepositoriesFeature()
     }
-    await store.send(.requestRenameBranch("\(repoID)/feature-old", "/does/not/exist"))
+    await store.send(.requestRenameBranch(WorktreeID("\(repoID)/feature-old"), "/does/not/exist"))
   }
 
   @Test func requestRenameBranchNoOpsWhenRowIsNotIdle() async {
     var initial = makeInitialState()
-    initial.sidebarItems[id: "\(repoID)/feature-old"]?.lifecycle = .archiving
+    initial.sidebarItems[id: WorktreeID("\(repoID)/feature-old")]?.lifecycle = .archiving
     let store = TestStore(initialState: initial) {
       RepositoriesFeature()
     }
-    await store.send(.requestRenameBranch("\(repoID)/feature-old", repoID))
+    await store.send(.requestRenameBranch(WorktreeID("\(repoID)/feature-old"), repoID))
   }
 
   @Test func lifecycleFlipClosesRenameSheet() async {
     var initial = makeInitialState()
     initial.renameBranchPrompt = RenameBranchFeature.State(
-      worktreeID: "\(repoID)/feature-old",
+      worktreeID: WorktreeID("\(repoID)/feature-old"),
       repositoryID: repoID,
-      repositoryRootURL: URL(fileURLWithPath: repoID),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue),
+      host: nil,
       currentName: "feature/old"
     )
     let store = TestStore(initialState: initial) {
@@ -194,7 +241,7 @@ struct RepositoriesFeatureRenameBranchTests {
 
     await store.send(
       .sidebarItems(
-        .element(id: "\(repoID)/feature-old", action: .lifecycleChanged(.archiving))
+        .element(id: WorktreeID("\(repoID)/feature-old"), action: .lifecycleChanged(.archiving))
       )
     ) {
       $0.renameBranchPrompt = nil
@@ -204,9 +251,10 @@ struct RepositoriesFeatureRenameBranchTests {
   @Test func cancelDelegateClearsPresentedState() async {
     var initial = makeInitialState()
     initial.renameBranchPrompt = RenameBranchFeature.State(
-      worktreeID: "\(repoID)/feature-old",
+      worktreeID: WorktreeID("\(repoID)/feature-old"),
       repositoryID: repoID,
-      repositoryRootURL: URL(fileURLWithPath: repoID),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue),
+      host: nil,
       currentName: "feature/old"
     )
     let store = TestStore(initialState: initial) {
diff --git a/supacodeTests/RepositoriesFeatureSidebarTests.swift b/supacodeTests/RepositoriesFeatureSidebarTests.swift
index 35a57b37b..529e0dbf5 100644
--- a/supacodeTests/RepositoriesFeatureSidebarTests.swift
+++ b/supacodeTests/RepositoriesFeatureSidebarTests.swift
@@ -12,19 +12,19 @@ import Testing
 @MainActor
 struct RepositoriesFeatureSidebarTests {
   @Test func reconcileClearsPullRequestWatermarkOnBranchRename() {
-    let worktreeID = "/tmp/repo/wt-feature"
-    let repoID = "/tmp/repo/"
+    let worktreeID: Worktree.ID = "/tmp/repo/wt-feature"
+    let repoID: Repository.ID = "/tmp/repo/"
     let original = Worktree(
       id: worktreeID,
       name: "feature",
       detail: "",
-      workingDirectory: URL(fileURLWithPath: worktreeID),
-      repositoryRootURL: URL(fileURLWithPath: repoID)
+      workingDirectory: URL(fileURLWithPath: worktreeID.rawValue),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue)
     )
     var state = makeState(
       repository: Repository(
         id: repoID,
-        rootURL: URL(fileURLWithPath: repoID),
+        rootURL: URL(fileURLWithPath: repoID.rawValue),
         name: "repo",
         worktrees: IdentifiedArray(uniqueElements: [original])
       ))
@@ -35,12 +35,12 @@ struct RepositoriesFeatureSidebarTests {
       id: worktreeID,
       name: "feature-renamed",
       detail: "",
-      workingDirectory: URL(fileURLWithPath: worktreeID),
-      repositoryRootURL: URL(fileURLWithPath: repoID)
+      workingDirectory: URL(fileURLWithPath: worktreeID.rawValue),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue)
     )
     state.repositories[id: repoID] = Repository(
       id: repoID,
-      rootURL: URL(fileURLWithPath: repoID),
+      rootURL: URL(fileURLWithPath: repoID.rawValue),
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [renamed])
     )
@@ -51,19 +51,19 @@ struct RepositoriesFeatureSidebarTests {
   }
 
   @Test func runningScriptsSurviveReconcile() {
-    let worktreeID = "/tmp/repo/wt-feature"
-    let repoID = "/tmp/repo/"
+    let worktreeID: Worktree.ID = "/tmp/repo/wt-feature"
+    let repoID: Repository.ID = "/tmp/repo/"
     let worktree = Worktree(
       id: worktreeID,
       name: "feature",
       detail: "",
-      workingDirectory: URL(fileURLWithPath: worktreeID),
-      repositoryRootURL: URL(fileURLWithPath: repoID)
+      workingDirectory: URL(fileURLWithPath: worktreeID.rawValue),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue)
     )
     var state = makeState(
       repository: Repository(
         id: repoID,
-        rootURL: URL(fileURLWithPath: repoID),
+        rootURL: URL(fileURLWithPath: repoID.rawValue),
         name: "repo",
         worktrees: IdentifiedArray(uniqueElements: [worktree])
       ))
@@ -89,19 +89,19 @@ struct RepositoriesFeatureSidebarTests {
   }
 
   @Test func inFlightRowSurvivesTransientRosterDrop() {
-    let worktreeID = "/tmp/repo/wt-feature"
-    let repoID = "/tmp/repo/"
+    let worktreeID: Worktree.ID = "/tmp/repo/wt-feature"
+    let repoID: Repository.ID = "/tmp/repo/"
     let worktree = Worktree(
       id: worktreeID,
       name: "feature",
       detail: "",
-      workingDirectory: URL(fileURLWithPath: worktreeID),
-      repositoryRootURL: URL(fileURLWithPath: repoID)
+      workingDirectory: URL(fileURLWithPath: worktreeID.rawValue),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue)
     )
     var state = makeState(
       repository: Repository(
         id: repoID,
-        rootURL: URL(fileURLWithPath: repoID),
+        rootURL: URL(fileURLWithPath: repoID.rawValue),
         name: "repo",
         worktrees: IdentifiedArray(uniqueElements: [worktree])
       ))
@@ -113,7 +113,7 @@ struct RepositoriesFeatureSidebarTests {
     // worktree from the live roster mid-flight).
     state.repositories[id: repoID] = Repository(
       id: repoID,
-      rootURL: URL(fileURLWithPath: repoID),
+      rootURL: URL(fileURLWithPath: repoID.rawValue),
       name: "repo",
       worktrees: []
     )
@@ -126,7 +126,7 @@ struct RepositoriesFeatureSidebarTests {
     // Roster restores the worktree.
     state.repositories[id: repoID] = Repository(
       id: repoID,
-      rootURL: URL(fileURLWithPath: repoID),
+      rootURL: URL(fileURLWithPath: repoID.rawValue),
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [worktree])
     )
@@ -138,18 +138,18 @@ struct RepositoriesFeatureSidebarTests {
   }
 
   @Test func pullRequestsLoadedClearsWatermarkOnIdenticalPullRequest() async {
-    let repoID = "/tmp/repo"
-    let worktreeID = "/tmp/repo/wt-feature"
+    let repoID: Repository.ID = "/tmp/repo"
+    let worktreeID: Worktree.ID = "/tmp/repo/wt-feature"
     let worktree = Worktree(
       id: worktreeID,
       name: "feature",
       detail: "",
-      workingDirectory: URL(fileURLWithPath: worktreeID),
-      repositoryRootURL: URL(fileURLWithPath: repoID)
+      workingDirectory: URL(fileURLWithPath: worktreeID.rawValue),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue)
     )
     let repository = Repository(
       id: repoID,
-      rootURL: URL(fileURLWithPath: repoID),
+      rootURL: URL(fileURLWithPath: repoID.rawValue),
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [worktree])
     )
@@ -198,18 +198,18 @@ struct RepositoriesFeatureSidebarTests {
     // Worktree was included in the request snapshot but absent from the response
     // (e.g. branch deleted upstream); the row must still receive
     // `pullRequestChanged` so its watermark clears and the next refresh is eligible.
-    let repoID = "/tmp/repo"
-    let worktreeID = "/tmp/repo/wt-feature"
+    let repoID: Repository.ID = "/tmp/repo"
+    let worktreeID: Worktree.ID = "/tmp/repo/wt-feature"
     let worktree = Worktree(
       id: worktreeID,
       name: "feature",
       detail: "",
-      workingDirectory: URL(fileURLWithPath: worktreeID),
-      repositoryRootURL: URL(fileURLWithPath: repoID)
+      workingDirectory: URL(fileURLWithPath: worktreeID.rawValue),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue)
     )
     let repository = Repository(
       id: repoID,
-      rootURL: URL(fileURLWithPath: repoID),
+      rootURL: URL(fileURLWithPath: repoID.rawValue),
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [worktree])
     )
@@ -232,8 +232,8 @@ struct RepositoriesFeatureSidebarTests {
   }
 
   @Test(.dependencies) func reconcileSeedsSurfaceIDsFromPersistedLayout() throws {
-    let worktreeID = "/tmp/repo/wt-feature"
-    let repoID = "/tmp/repo/"
+    let worktreeID: Worktree.ID = "/tmp/repo/wt-feature"
+    let repoID: Repository.ID = "/tmp/repo/"
     let surfaceA = UUID()
     let surfaceB = UUID()
     let layout = TerminalLayoutSnapshot(
@@ -258,7 +258,7 @@ struct RepositoriesFeatureSidebarTests {
       selectedTabIndex: 0
     )
     let storage = InMemorySettingsFileStorage()
-    let payload = try JSONEncoder().encode([worktreeID: layout])
+    let payload = try JSONEncoder().encode([worktreeID.rawValue: layout])
     try storage.save(payload, SupacodePaths.layoutsURL)
 
     try withDependencies {
@@ -272,15 +272,15 @@ struct RepositoriesFeatureSidebarTests {
         id: worktreeID,
         name: "feature",
         detail: "",
-        workingDirectory: URL(fileURLWithPath: worktreeID),
-        repositoryRootURL: URL(fileURLWithPath: repoID)
+        workingDirectory: URL(fileURLWithPath: worktreeID.rawValue),
+        repositoryRootURL: URL(fileURLWithPath: repoID.rawValue)
       )
       var state = RepositoriesFeature.State()
       state.repositories = IdentifiedArray(
         uniqueElements: [
           Repository(
             id: repoID,
-            rootURL: URL(fileURLWithPath: repoID),
+            rootURL: URL(fileURLWithPath: repoID.rawValue),
             name: "repo",
             worktrees: IdentifiedArray(uniqueElements: [worktree])
           )
@@ -315,7 +315,7 @@ struct RepositoriesFeatureSidebarTests {
       selectedTabIndex: 0
     )
     let storage = InMemorySettingsFileStorage()
-    let payload = try JSONEncoder().encode([folderID: layout])
+    let payload = try JSONEncoder().encode([folderID.rawValue: layout])
     try storage.save(payload, SupacodePaths.layoutsURL)
 
     try withDependencies {
@@ -326,7 +326,7 @@ struct RepositoriesFeatureSidebarTests {
       $0.defaultAppStorage = .inMemory
     } operation: {
       let folderRepository = Repository(
-        id: rootURL.path(percentEncoded: false) + "/",
+        id: RepositoryID(rootURL.path(percentEncoded: false) + "/"),
         rootURL: rootURL,
         name: "folder",
         worktrees: IdentifiedArray(
@@ -352,8 +352,8 @@ struct RepositoriesFeatureSidebarTests {
   }
 
   @Test(.dependencies) func reconcileDoesNotOverwriteExistingSurfaceIDsWithStaleLayout() throws {
-    let worktreeID = "/tmp/repo/wt-feature"
-    let repoID = "/tmp/repo/"
+    let worktreeID: Worktree.ID = "/tmp/repo/wt-feature"
+    let repoID: Repository.ID = "/tmp/repo/"
     let liveSurface = UUID()
     let staleSurface = UUID()
     let staleLayout = TerminalLayoutSnapshot(
@@ -371,7 +371,7 @@ struct RepositoriesFeatureSidebarTests {
       selectedTabIndex: 0
     )
     let storage = InMemorySettingsFileStorage()
-    try storage.save(try JSONEncoder().encode([worktreeID: staleLayout]), SupacodePaths.layoutsURL)
+    try storage.save(try JSONEncoder().encode([worktreeID.rawValue: staleLayout]), SupacodePaths.layoutsURL)
 
     try withDependencies {
       $0.settingsFileStorage = SettingsFileStorage(
@@ -384,15 +384,15 @@ struct RepositoriesFeatureSidebarTests {
         id: worktreeID,
         name: "feature",
         detail: "",
-        workingDirectory: URL(fileURLWithPath: worktreeID),
-        repositoryRootURL: URL(fileURLWithPath: repoID)
+        workingDirectory: URL(fileURLWithPath: worktreeID.rawValue),
+        repositoryRootURL: URL(fileURLWithPath: repoID.rawValue)
       )
       var state = RepositoriesFeature.State()
       state.repositories = IdentifiedArray(
         uniqueElements: [
           Repository(
             id: repoID,
-            rootURL: URL(fileURLWithPath: repoID),
+            rootURL: URL(fileURLWithPath: repoID.rawValue),
             name: "repo",
             worktrees: IdentifiedArray(uniqueElements: [worktree])
           )
@@ -412,8 +412,8 @@ struct RepositoriesFeatureSidebarTests {
   }
 
   @Test(.dependencies) func reconcileDoesNotReSeedAfterUserClosedEveryTab() throws {
-    let worktreeID = "/tmp/repo/wt-feature"
-    let repoID = "/tmp/repo/"
+    let worktreeID: Worktree.ID = "/tmp/repo/wt-feature"
+    let repoID: Repository.ID = "/tmp/repo/"
     let staleSurface = UUID()
     let staleLayout = TerminalLayoutSnapshot(
       tabs: [
@@ -430,7 +430,7 @@ struct RepositoriesFeatureSidebarTests {
       selectedTabIndex: 0
     )
     let storage = InMemorySettingsFileStorage()
-    try storage.save(try JSONEncoder().encode([worktreeID: staleLayout]), SupacodePaths.layoutsURL)
+    try storage.save(try JSONEncoder().encode([worktreeID.rawValue: staleLayout]), SupacodePaths.layoutsURL)
 
     try withDependencies {
       $0.settingsFileStorage = SettingsFileStorage(
@@ -443,15 +443,15 @@ struct RepositoriesFeatureSidebarTests {
         id: worktreeID,
         name: "feature",
         detail: "",
-        workingDirectory: URL(fileURLWithPath: worktreeID),
-        repositoryRootURL: URL(fileURLWithPath: repoID)
+        workingDirectory: URL(fileURLWithPath: worktreeID.rawValue),
+        repositoryRootURL: URL(fileURLWithPath: repoID.rawValue)
       )
       var state = RepositoriesFeature.State()
       state.repositories = IdentifiedArray(
         uniqueElements: [
           Repository(
             id: repoID,
-            rootURL: URL(fileURLWithPath: repoID),
+            rootURL: URL(fileURLWithPath: repoID.rawValue),
             name: "repo",
             worktrees: IdentifiedArray(uniqueElements: [worktree])
           )
@@ -487,12 +487,12 @@ struct RepositoriesFeatureSidebarTests {
   // MARK: - branchNestExpansionChanged
 
   @Test func branchNestExpansionChangedInsertsPrefix() async {
-    let repoID = "/tmp/repo/"
+    let repoID: Repository.ID = "/tmp/repo/"
     let store = TestStore(
       initialState: makeState(
         repository: Repository(
           id: repoID,
-          rootURL: URL(fileURLWithPath: repoID),
+          rootURL: URL(fileURLWithPath: repoID.rawValue),
           name: "repo",
           worktrees: []
         )
@@ -516,11 +516,11 @@ struct RepositoriesFeatureSidebarTests {
   }
 
   @Test func branchNestExpansionChangedRemovesPrefix() async {
-    let repoID = "/tmp/repo/"
+    let repoID: Repository.ID = "/tmp/repo/"
     var initialState = makeState(
       repository: Repository(
         id: repoID,
-        rootURL: URL(fileURLWithPath: repoID),
+        rootURL: URL(fileURLWithPath: repoID.rawValue),
         name: "repo",
         worktrees: []
       )
@@ -553,11 +553,11 @@ struct RepositoriesFeatureSidebarTests {
     // The toggle is read-only AppStorage outside the reducer; this test guards the
     // related invariant that the only sidebar mutation that exists touches the field
     // additively, never clearing the set on unrelated transitions.
-    let repoID = "/tmp/repo/"
+    let repoID: Repository.ID = "/tmp/repo/"
     var initialState = makeState(
       repository: Repository(
         id: repoID,
-        rootURL: URL(fileURLWithPath: repoID),
+        rootURL: URL(fileURLWithPath: repoID.rawValue),
         name: "repo",
         worktrees: []
       )
@@ -596,12 +596,12 @@ struct RepositoriesFeatureSidebarTests {
   @Test func branchNestExpansionChangedRejectsArchivedBucket() async {
     // `.archived` never renders nested rows; the action must refuse to write
     // collapse state into a bucket that has no chevron to drive it.
-    let repoID = "/tmp/repo/"
+    let repoID: Repository.ID = "/tmp/repo/"
     let store = TestStore(
       initialState: makeState(
         repository: Repository(
           id: repoID,
-          rootURL: URL(fileURLWithPath: repoID),
+          rootURL: URL(fileURLWithPath: repoID.rawValue),
           name: "repo",
           worktrees: []
         )
@@ -626,13 +626,13 @@ struct RepositoriesFeatureSidebarTests {
     // hitting this path for an unknown repo is stale UI / deeplink noise.
     // Writing through anyway would materialize a phantom section in
     // `sidebar.json` that nothing else cleans up.
-    let knownRepoID = "/tmp/repo/"
-    let unknownRepoID = "/tmp/other/"
+    let knownRepoID: Repository.ID = "/tmp/repo/"
+    let unknownRepoID: Repository.ID = "/tmp/other/"
     let store = TestStore(
       initialState: makeState(
         repository: Repository(
           id: knownRepoID,
-          rootURL: URL(fileURLWithPath: knownRepoID),
+          rootURL: URL(fileURLWithPath: knownRepoID.rawValue),
           name: "repo",
           worktrees: []
         )
@@ -653,12 +653,12 @@ struct RepositoriesFeatureSidebarTests {
   }
 
   @Test func branchNestExpansionPinnedAndUnpinnedAreIndependent() async {
-    let repoID = "/tmp/repo/"
+    let repoID: Repository.ID = "/tmp/repo/"
     let store = TestStore(
       initialState: makeState(
         repository: Repository(
           id: repoID,
-          rootURL: URL(fileURLWithPath: repoID),
+          rootURL: URL(fileURLWithPath: repoID.rawValue),
           name: "repo",
           worktrees: []
         )
diff --git a/supacodeTests/RepositoriesFeatureTests.swift b/supacodeTests/RepositoriesFeatureTests.swift
index d926f1f43..5ffd15fc7 100644
--- a/supacodeTests/RepositoriesFeatureTests.swift
+++ b/supacodeTests/RepositoriesFeatureTests.swift
@@ -85,7 +85,7 @@ struct RepositoriesFeatureTests {
     // finally dropped.
     let repoRoot = "/tmp/repo"
     let mainWorktree = Worktree(
-      id: repoRoot,
+      id: WorktreeID(repoRoot),
       name: "main",
       detail: "detail",
       workingDirectory: URL(fileURLWithPath: repoRoot),
@@ -106,7 +106,7 @@ struct RepositoriesFeatureTests {
     initialState.repositoryRoots = [mainOnlyRepository.rootURL]
     initialState.isInitialLoadComplete = false
     initialState.$sidebar.withLock { sidebar in
-      sidebar.sections[repoRoot] = .init(
+      sidebar.sections[RepositoryID(repoRoot)] = .init(
         buckets: [.pinned: .init(items: [featureWorktree.id: .init()])]
       )
     }
@@ -128,7 +128,7 @@ struct RepositoriesFeatureTests {
       $0.reconcileSidebarForTesting()
     }
     #expect(
-      store.state.sidebar.sections[repoRoot]?.buckets[.pinned]?.items[featureWorktree.id] != nil
+      store.state.sidebar.sections[RepositoryID(repoRoot)]?.buckets[.pinned]?.items[featureWorktree.id] != nil
     )
 
     // Second tick with `isInitialLoadComplete == true`: the
@@ -145,12 +145,12 @@ struct RepositoriesFeatureTests {
       )
     ) {
       $0.$sidebar.withLock { sidebar in
-        sidebar.sections[repoRoot] = .init(buckets: [.pinned: .init(items: [:])])
+        sidebar.sections[RepositoryID(repoRoot)] = .init(buckets: [.pinned: .init(items: [:])])
       }
       $0.reconcileSidebarForTesting()
     }
     #expect(
-      store.state.sidebar.sections[repoRoot]?.buckets[.pinned]?.items[featureWorktree.id] == nil
+      store.state.sidebar.sections[RepositoryID(repoRoot)]?.buckets[.pinned]?.items[featureWorktree.id] == nil
     )
   }
 
@@ -164,6 +164,7 @@ struct RepositoriesFeatureTests {
     await store.send(.selectWorktree(worktree.id)) {
       $0.selection = .worktree(worktree.id)
       $0.sidebarSelectedWorktreeIDs = [worktree.id]
+      $0.worktreeMRU = [worktree.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
@@ -185,6 +186,7 @@ struct RepositoriesFeatureTests {
       $0.selection = .worktree(wt2.id)
       $0.sidebarSelectedWorktreeIDs = [wt2.id]
       $0.worktreeHistoryBackStack = [wt1.id]
+      $0.worktreeMRU = [wt2.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
@@ -247,6 +249,7 @@ struct RepositoriesFeatureTests {
       $0.selection = .worktree(wt2.id)
       $0.sidebarSelectedWorktreeIDs = [wt2.id, wt3.id]
       $0.worktreeHistoryBackStack = [wt1.id]
+      $0.worktreeMRU = [wt2.id]
       $0.sidebarItems[id: wt2.id]?.shouldFocusTerminal = true
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
@@ -341,6 +344,7 @@ struct RepositoriesFeatureTests {
       $0.selection = .worktree(wt2.id)
       $0.sidebarSelectedWorktreeIDs = [wt2.id]
       $0.worktreeHistoryBackStack = [wt1.id]
+      $0.worktreeMRU = [wt2.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
@@ -363,6 +367,7 @@ struct RepositoriesFeatureTests {
     ) {
       $0.selection = .worktree(wt1.id)
       $0.sidebarSelectedWorktreeIDs = [wt1.id, wt2.id]
+      $0.worktreeMRU = [wt1.id]
     }
     #expect(store.state.sidebarItems.allSatisfy { !$0.shouldFocusTerminal })
   }
@@ -485,7 +490,10 @@ struct RepositoriesFeatureTests {
     }
 
     // Re-selecting the same worktree should not fire delegate or insert pending focus.
-    await store.send(.selectionChanged([.worktree(wt1.id)], focusTerminal: true))
+    // The selection itself is unchanged, but it still records as most-recently-used.
+    await store.send(.selectionChanged([.worktree(wt1.id)], focusTerminal: true)) {
+      $0.worktreeMRU = [wt1.id]
+    }
     #expect(store.state.sidebarItems.allSatisfy { !$0.shouldFocusTerminal })
   }
 
@@ -535,7 +543,9 @@ struct RepositoriesFeatureTests {
     }
 
     // Valid ID kept, unknown ID silently dropped.
-    await store.send(.selectionChanged([.worktree(wt1.id), .worktree("/tmp/unknown")]))
+    await store.send(.selectionChanged([.worktree(wt1.id), .worktree("/tmp/unknown")])) {
+      $0.worktreeMRU = [wt1.id]
+    }
     #expect(store.state.sidebarSelectedWorktreeIDs == [wt1.id])
   }
 
@@ -633,6 +643,21 @@ struct RepositoriesFeatureTests {
     }
   }
 
+  @Test func revealHoistedWorktreeInSidebarRevealsTheGivenWorktree() async {
+    let worktree = makeWorktree(id: "/tmp/repo/wt", name: "wt")
+    let repository = makeRepository(id: "/tmp/repo", worktrees: [worktree])
+    let store = TestStore(initialState: makeState(repositories: [repository])) {
+      RepositoriesFeature()
+    }
+
+    // No selection and no uncollapse: the target lives in a highlight section,
+    // and the action reveals the id it is handed directly.
+    await store.send(.revealHoistedWorktreeInSidebar(worktree.id)) {
+      $0.nextPendingSidebarRevealID = 1
+      $0.pendingSidebarReveal = .init(id: 1, worktreeID: worktree.id)
+    }
+  }
+
   @Test func consumePendingSidebarRevealClearsMatchingRequest() async {
     let worktree = makeWorktree(id: "/tmp/repo/wt", name: "wt")
     let repository = makeRepository(id: "/tmp/repo", worktrees: [worktree])
@@ -949,7 +974,9 @@ struct RepositoriesFeatureTests {
               branchName: "feature/new",
               baseRef: nil,
               fetchOrigin: true,
-              placement: WorktreePlacementOverride(name: nil, path: nil)
+              placement: WorktreePlacementOverride(name: nil, path: nil),
+              title: nil,
+              color: nil
             )
           )
         )
@@ -1181,7 +1208,7 @@ struct RepositoriesFeatureTests {
     let repoRoot = "/tmp/repo"
     let mainWorktree = makeWorktree(id: repoRoot, name: "main", repoRoot: repoRoot)
     let repository = makeRepository(id: repoRoot, worktrees: [mainWorktree])
-    let pendingID = "pending:00000000-0000-0000-0000-000000000001"
+    let pendingID: Worktree.ID = "pending:00000000-0000-0000-0000-000000000001"
     let validationClock = TestClock()
     let store = TestStore(initialState: makeState(repositories: [repository])) {
       RepositoriesFeature()
@@ -1224,6 +1251,7 @@ struct RepositoriesFeatureTests {
       ]
       $0.selection = SidebarSelection.worktree(pendingID)
       $0.sidebarSelectedWorktreeIDs = [pendingID]
+      $0.worktreeMRU = [pendingID]
       $0.reconcileSidebarForTesting()
     }
 
@@ -1898,7 +1926,7 @@ struct RepositoriesFeatureTests {
       id: repoRoot,
       worktrees: [makeWorktree(id: repoRoot, name: "main", repoRoot: repoRoot)]
     )
-    let pendingID = "pending:test"
+    let pendingID: Worktree.ID = "pending:test"
     var state = makeState(repositories: [repository])
     state.selection = .worktree(pendingID)
     state.pendingWorktrees = [
@@ -1935,7 +1963,7 @@ struct RepositoriesFeatureTests {
     let repoRoot = "/tmp/repo"
     let mainWorktree = makeWorktree(id: repoRoot, name: "main", repoRoot: repoRoot)
     let repository = makeRepository(id: repoRoot, worktrees: [mainWorktree])
-    let pendingID = "pending:test"
+    let pendingID: Worktree.ID = "pending:test"
     var state = makeState(repositories: [repository])
     state.pendingWorktrees = [
       PendingWorktree(
@@ -1952,6 +1980,7 @@ struct RepositoriesFeatureTests {
     await store.send(.selectionChanged([.worktree(pendingID)])) {
       $0.selection = .worktree(pendingID)
       $0.sidebarSelectedWorktreeIDs = [pendingID]
+      $0.worktreeMRU = [pendingID]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     // `worktree(for:)` doesn't surface pending entries; the delegate fires nil
@@ -1966,7 +1995,7 @@ struct RepositoriesFeatureTests {
     let repoRoot = "/tmp/repo"
     let mainWorktree = makeWorktree(id: repoRoot, name: "main", repoRoot: repoRoot)
     let repository = makeRepository(id: repoRoot, worktrees: [mainWorktree])
-    let pendingID = "pending:test"
+    let pendingID: Worktree.ID = "pending:test"
     var state = makeState(repositories: [repository])
     state.pendingWorktrees = [
       PendingWorktree(
@@ -1988,7 +2017,7 @@ struct RepositoriesFeatureTests {
   @Test func pendingProgressUpdateIsIgnoredAfterCreateFailureRemovesPendingWorktree() async {
     let repoRoot = "/tmp/repo"
     let repository = makeRepository(id: repoRoot, worktrees: [makeWorktree(id: repoRoot, name: "main")])
-    let pendingID = "pending:test"
+    let pendingID: Worktree.ID = "pending:test"
     var state = makeState(repositories: [repository])
     state.selection = .worktree(pendingID)
     state.pendingWorktrees = [
@@ -2210,11 +2239,12 @@ struct RepositoriesFeatureTests {
     let folderURL = URL(fileURLWithPath: folderRoot)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: Repository.name(for: folderURL), detail: "",
       workingDirectory: folderURL, repositoryRootURL: folderURL
     )
     let folderRepo = Repository(
-      id: folderRoot, rootURL: folderURL, name: Repository.name(for: folderURL),
+      id: RepositoryID(folderRoot), rootURL: folderURL, name: Repository.name(for: folderURL),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
       isGitRepository: false
     )
@@ -2431,11 +2461,12 @@ struct RepositoriesFeatureTests {
     let folderURL = URL(fileURLWithPath: folderRoot)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: Repository.name(for: folderURL), detail: "",
       workingDirectory: folderURL, repositoryRootURL: folderURL
     )
     let folderRepo = Repository(
-      id: folderRoot, rootURL: folderURL, name: Repository.name(for: folderURL),
+      id: RepositoryID(folderRoot), rootURL: folderURL, name: Repository.name(for: folderURL),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
       isGitRepository: false
     )
@@ -3372,7 +3403,7 @@ struct RepositoriesFeatureTests {
     state.sidebarItems.append(
       SidebarItemFeature.State(
         id: "/tmp/repo/gone",
-        repositoryID: repoRoot,
+        repositoryID: RepositoryID(repoRoot),
         kind: .gitWorktree,
         name: "gone",
         branchName: "gone",
@@ -3714,7 +3745,7 @@ struct RepositoriesFeatureTests {
     state.pendingWorktrees = [
       PendingWorktree(
         id: "/tmp/repo/wip",
-        repositoryID: repoRoot,
+        repositoryID: RepositoryID(repoRoot),
         progress: WorktreeCreationProgress(stage: .choosingWorktreeName)
       )
     ]
@@ -3723,12 +3754,12 @@ struct RepositoriesFeatureTests {
     // Pending row renders before non-pending unpinned, so the bucket must too. Otherwise
     // Cmd+N hint and target diverge while a worktree is creating.
     expectNoDifference(
-      state.orderedSidebarItemIDs(includingRepositoryIDs: [repoRoot]),
-      [repoRoot, "/tmp/repo/wip", "/tmp/repo/feature"]
+      state.orderedSidebarItemIDs(includingRepositoryIDs: [RepositoryID(repoRoot)]),
+      [WorktreeID(repoRoot), "/tmp/repo/wip", "/tmp/repo/feature"]
     )
 
     // ID flavor and heavy flavor must agree for every filter the render path can pass.
-    for filter: Set<Repository.ID> in [[repoRoot], [other.id], [repoRoot, other.id], []] {
+    for filter: Set<Repository.ID> in [[RepositoryID(repoRoot)], [other.id], [RepositoryID(repoRoot), other.id], []] {
       expectNoDifference(
         state.orderedSidebarItemIDs(includingRepositoryIDs: filter),
         state.orderedSidebarItems(includingRepositoryIDs: filter).map(\.id)
@@ -3798,14 +3829,14 @@ struct RepositoriesFeatureTests {
     state.pendingWorktrees = [
       PendingWorktree(
         id: "/tmp/repo/wip",
-        repositoryID: repoRoot,
+        repositoryID: RepositoryID(repoRoot),
         progress: WorktreeCreationProgress(stage: .choosingWorktreeName)
       )
     ]
     state.reconcileSidebarForTesting()
 
     expectNoDifference(
-      state.orderedSidebarItemIDs(includingRepositoryIDs: [repoRoot]),
+      state.orderedSidebarItemIDs(includingRepositoryIDs: [RepositoryID(repoRoot)]),
       ["/tmp/repo", "/tmp/repo/wip", "/tmp/repo/feature-a", "/tmp/repo/feature-b"]
     )
   }
@@ -3839,14 +3870,14 @@ struct RepositoriesFeatureTests {
     var state = makeState(repositories: [makeRepository(id: repoRoot, worktrees: [main, alpha, bravo])])
     // Pin bravo so it hoists to the Pinned section at the top.
     state.$sidebar.withLock { sidebar in
-      var section = sidebar.sections[repoRoot] ?? .init()
+      var section = sidebar.sections[RepositoryID(repoRoot)] ?? .init()
       var pinnedBucket = section.buckets[.pinned] ?? .init()
       pinnedBucket.items[bravo.id] = .init()
       section.buckets[.pinned] = pinnedBucket
       var unpinnedBucket = section.buckets[.unpinned] ?? .init()
       unpinnedBucket.items.removeValue(forKey: bravo.id)
       section.buckets[.unpinned] = unpinnedBucket
-      sidebar.sections[repoRoot] = section
+      sidebar.sections[RepositoryID(repoRoot)] = section
     }
     state.reconcileSidebarForTesting()
 
@@ -3872,8 +3903,8 @@ struct RepositoriesFeatureTests {
     expectNoDifference(
       state.orderedRepositoryRoots().map { $0.path(percentEncoded: false) },
       [
-        repoB.id,
-        repoA.id,
+        repoB.id.rawValue,
+        repoA.id.rawValue,
       ]
     )
   }
@@ -3915,7 +3946,7 @@ struct RepositoriesFeatureTests {
     )
     var state = makeState(repositories: [repository])
     state.$sidebar.withLock { sidebar in
-      sidebar.sections[repoRoot] = .init(
+      sidebar.sections[RepositoryID(repoRoot)] = .init(
         buckets: [
           .unpinned: .init(
             items: [worktree1.id: .init(), worktree2.id: .init(), worktree3.id: .init()]
@@ -3928,11 +3959,11 @@ struct RepositoriesFeatureTests {
       RepositoriesFeature()
     }
 
-    await store.send(.unpinnedWorktreesMoved(repositoryID: repoRoot, IndexSet(integer: 0), 3)) {
+    await store.send(.unpinnedWorktreesMoved(repositoryID: RepositoryID(repoRoot), IndexSet(integer: 0), 3)) {
       $0.$sidebar.withLock { sidebar in
         sidebar.reorder(
           bucket: .unpinned,
-          in: repoRoot,
+          in: RepositoryID(repoRoot),
           to: [worktree2.id, worktree3.id, worktree1.id]
         )
       }
@@ -3950,12 +3981,12 @@ struct RepositoriesFeatureTests {
     let repositoryB = makeRepository(id: repoB, worktrees: [worktreeB1])
     var state = makeState(repositories: [repositoryA, repositoryB])
     state.$sidebar.withLock { sidebar in
-      sidebar.sections[repoA] = .init(
+      sidebar.sections[RepositoryID(repoA)] = .init(
         buckets: [
           .pinned: .init(items: [worktreeA1.id: .init(), worktreeA2.id: .init()])
         ]
       )
-      sidebar.sections[repoB] = .init(
+      sidebar.sections[RepositoryID(repoB)] = .init(
         buckets: [.pinned: .init(items: [worktreeB1.id: .init()])]
       )
     }
@@ -3964,9 +3995,9 @@ struct RepositoriesFeatureTests {
       RepositoriesFeature()
     }
 
-    await store.send(.pinnedWorktreesMoved(repositoryID: repoA, IndexSet(integer: 1), 0)) {
+    await store.send(.pinnedWorktreesMoved(repositoryID: RepositoryID(repoA), IndexSet(integer: 1), 0)) {
       $0.$sidebar.withLock { sidebar in
-        sidebar.reorder(bucket: .pinned, in: repoA, to: [worktreeA2.id, worktreeA1.id])
+        sidebar.reorder(bucket: .pinned, in: RepositoryID(repoA), to: [worktreeA2.id, worktreeA1.id])
       }
       RepositoriesFeature.syncSidebar(&$0)
     }
@@ -4004,7 +4035,7 @@ struct RepositoriesFeatureTests {
     let repository = makeRepository(id: repoRoot, worktrees: [worktree1, worktree2])
     var initialState = makeState(repositories: [repository])
     initialState.$sidebar.withLock { sidebar in
-      sidebar.sections[repoRoot] = .init(
+      sidebar.sections[RepositoryID(repoRoot)] = .init(
         buckets: [
           .unpinned: .init(items: [worktree1.id: .init(), worktree2.id: .init()])
         ]
@@ -4032,7 +4063,7 @@ struct RepositoriesFeatureTests {
     await store.receive(\.delegate.repositoriesChanged)
     expectNoDifference(
       Array(
-        store.state.sidebar.sections[repoRoot]?.buckets[.unpinned]?.items.keys ?? []
+        store.state.sidebar.sections[RepositoryID(repoRoot)]?.buckets[.unpinned]?.items.keys ?? []
       ),
       [worktree1.id, worktree2.id]
     )
@@ -4232,7 +4263,7 @@ struct RepositoriesFeatureTests {
     let repository = makeRepository(id: repoRoot, worktrees: [existingWorktree])
     let newWorktree = makeWorktree(id: "/tmp/repo/wt-new", name: "new", repoRoot: repoRoot)
     let updatedRepository = makeRepository(id: repoRoot, worktrees: [newWorktree, existingWorktree])
-    let pendingID = "pending:\(UUID().uuidString)"
+    let pendingID = WorktreeID("pending:\(UUID().uuidString)")
     var initialState = makeState(repositories: [repository])
     initialState.pendingWorktrees = [
       PendingWorktree(
@@ -4259,6 +4290,7 @@ struct RepositoriesFeatureTests {
       $0.pendingWorktrees = []
       $0.selection = .worktree(newWorktree.id)
       $0.sidebarSelectedWorktreeIDs = [newWorktree.id]
+      $0.worktreeMRU = [newWorktree.id]
       $0.repositories = [updatedRepository]
       RepositoriesFeature.syncSidebar(&$0)
       $0.sidebarItems[id: newWorktree.id]?.lifecycle = .pending
@@ -5597,9 +5629,13 @@ struct RepositoriesFeatureTests {
       $0.selection = .worktree(wt1.id)
       $0.sidebarSelectedWorktreeIDs = [wt1.id]
       $0.worktreeHistoryBackStack = [wt2.id]
+      $0.worktreeMRU = [wt1.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
+    await store.receive(\.sidebarItems[id: wt1.id].focusTerminalRequested) {
+      $0.sidebarItems[id: wt1.id]?.shouldFocusTerminal = true
+    }
   }
 
   @Test func selectPreviousWorktreeWrapsBackward() async {
@@ -5618,9 +5654,13 @@ struct RepositoriesFeatureTests {
       $0.selection = .worktree(wt2.id)
       $0.sidebarSelectedWorktreeIDs = [wt2.id]
       $0.worktreeHistoryBackStack = [wt1.id]
+      $0.worktreeMRU = [wt2.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
+    await store.receive(\.sidebarItems[id: wt2.id].focusTerminalRequested) {
+      $0.sidebarItems[id: wt2.id]?.shouldFocusTerminal = true
+    }
   }
 
   @Test func selectNextWorktreeWithNoSelectionSelectsFirst() async {
@@ -5637,9 +5677,13 @@ struct RepositoriesFeatureTests {
     await store.receive(\.selectWorktree) {
       $0.selection = .worktree(wt1.id)
       $0.sidebarSelectedWorktreeIDs = [wt1.id]
+      $0.worktreeMRU = [wt1.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
+    await store.receive(\.sidebarItems[id: wt1.id].focusTerminalRequested) {
+      $0.sidebarItems[id: wt1.id]?.shouldFocusTerminal = true
+    }
   }
 
   @Test func selectNextWorktreeCollapsesSidebarSelectionToSingleWorktree() async {
@@ -5660,9 +5704,13 @@ struct RepositoriesFeatureTests {
       $0.selection = .worktree(wt2.id)
       $0.sidebarSelectedWorktreeIDs = [wt2.id]
       $0.worktreeHistoryBackStack = [wt1.id]
+      $0.worktreeMRU = [wt2.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
+    await store.receive(\.sidebarItems[id: wt2.id].focusTerminalRequested) {
+      $0.sidebarItems[id: wt2.id]?.shouldFocusTerminal = true
+    }
   }
 
   @Test func selectPreviousWorktreeWithNoSelectionSelectsLast() async {
@@ -5679,9 +5727,13 @@ struct RepositoriesFeatureTests {
     await store.receive(\.selectWorktree) {
       $0.selection = .worktree(wt2.id)
       $0.sidebarSelectedWorktreeIDs = [wt2.id]
+      $0.worktreeMRU = [wt2.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
+    await store.receive(\.sidebarItems[id: wt2.id].focusTerminalRequested) {
+      $0.sidebarItems[id: wt2.id]?.shouldFocusTerminal = true
+    }
   }
 
   @Test func selectNextWorktreeFollowsSidebarOrderNotRawWorktreeList() async {
@@ -5696,7 +5748,7 @@ struct RepositoriesFeatureTests {
     // becomes [bugfix (hoist), main, feature]. Arrow nav from main lands on
     // feature, not on bugfix's per-repo bucket position.
     state.$sidebar.withLock { sidebar in
-      sidebar.sections[repoRoot] = .init(buckets: [.pinned: .init(items: [bugfix.id: .init()])])
+      sidebar.sections[RepositoryID(repoRoot)] = .init(buckets: [.pinned: .init(items: [bugfix.id: .init()])])
     }
     state.reconcileSidebarForTesting()
     let store = TestStore(initialState: state) {
@@ -5708,9 +5760,13 @@ struct RepositoriesFeatureTests {
       $0.selection = .worktree(feature.id)
       $0.sidebarSelectedWorktreeIDs = [feature.id]
       $0.worktreeHistoryBackStack = [main.id]
+      $0.worktreeMRU = [feature.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
+    await store.receive(\.sidebarItems[id: feature.id].focusTerminalRequested) {
+      $0.sidebarItems[id: feature.id]?.shouldFocusTerminal = true
+    }
   }
 
   @Test func selectNextWorktreeWithEmptyRowsIsNoOp() async {
@@ -5735,9 +5791,13 @@ struct RepositoriesFeatureTests {
     await store.receive(\.selectWorktree) {
       $0.selection = .worktree(worktree.id)
       $0.sidebarSelectedWorktreeIDs = [worktree.id]
+      $0.worktreeMRU = [worktree.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
+    await store.receive(\.sidebarItems[id: worktree.id].focusTerminalRequested) {
+      $0.sidebarItems[id: worktree.id]?.shouldFocusTerminal = true
+    }
   }
 
   @Test func selectNextWorktreeSkipsCollapsedRepository() async {
@@ -5762,9 +5822,13 @@ struct RepositoriesFeatureTests {
       $0.selection = .worktree(wt3.id)
       $0.sidebarSelectedWorktreeIDs = [wt3.id]
       $0.worktreeHistoryBackStack = [wt1.id]
+      $0.worktreeMRU = [wt3.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
+    await store.receive(\.sidebarItems[id: wt3.id].focusTerminalRequested) {
+      $0.sidebarItems[id: wt3.id]?.shouldFocusTerminal = true
+    }
   }
 
   @Test func selectPreviousWorktreeSkipsCollapsedRepository() async {
@@ -5789,9 +5853,13 @@ struct RepositoriesFeatureTests {
       $0.selection = .worktree(wt1.id)
       $0.sidebarSelectedWorktreeIDs = [wt1.id]
       $0.worktreeHistoryBackStack = [wt3.id]
+      $0.worktreeMRU = [wt1.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
+    await store.receive(\.sidebarItems[id: wt1.id].focusTerminalRequested) {
+      $0.sidebarItems[id: wt1.id]?.shouldFocusTerminal = true
+    }
   }
 
   @Test func selectNextWorktreeAllCollapsedIsNoOp() async {
@@ -5848,9 +5916,13 @@ struct RepositoriesFeatureTests {
       $0.selection = .worktree(wt1.id)
       $0.sidebarSelectedWorktreeIDs = [wt1.id]
       $0.worktreeHistoryBackStack = [wt3.id]
+      $0.worktreeMRU = [wt1.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
+    await store.receive(\.sidebarItems[id: wt1.id].focusTerminalRequested) {
+      $0.sidebarItems[id: wt1.id]?.shouldFocusTerminal = true
+    }
   }
 
   // MARK: - Worktree History Back/Forward.
@@ -5872,6 +5944,7 @@ struct RepositoriesFeatureTests {
       $0.sidebarSelectedWorktreeIDs = [wt2.id]
       $0.worktreeHistoryBackStack = [wt1.id]
       $0.worktreeHistoryForwardStack = []
+      $0.worktreeMRU = [wt2.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
@@ -5888,7 +5961,9 @@ struct RepositoriesFeatureTests {
       RepositoriesFeature()
     }
 
-    await store.send(.selectWorktree(wt1.id))
+    await store.send(.selectWorktree(wt1.id)) {
+      $0.worktreeMRU = [wt1.id]
+    }
     await store.receive(\.delegate.selectedWorktreeChanged)
   }
 
@@ -5909,9 +5984,13 @@ struct RepositoriesFeatureTests {
       $0.sidebarSelectedWorktreeIDs = [wt1.id]
       $0.worktreeHistoryBackStack = []
       $0.worktreeHistoryForwardStack = [wt2.id]
+      $0.worktreeMRU = [wt1.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
+    await store.receive(\.sidebarItems[id: wt1.id].focusTerminalRequested) {
+      $0.sidebarItems[id: wt1.id]?.shouldFocusTerminal = true
+    }
   }
 
   @Test func worktreeHistoryForwardPopsNextAndPushesCurrentToBack() async {
@@ -5931,9 +6010,13 @@ struct RepositoriesFeatureTests {
       $0.sidebarSelectedWorktreeIDs = [wt2.id]
       $0.worktreeHistoryBackStack = [wt1.id]
       $0.worktreeHistoryForwardStack = []
+      $0.worktreeMRU = [wt2.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
+    await store.receive(\.sidebarItems[id: wt2.id].focusTerminalRequested) {
+      $0.sidebarItems[id: wt2.id]?.shouldFocusTerminal = true
+    }
   }
 
   @Test func worktreeHistoryBackWithEmptyStackIsNoOp() async {
@@ -5982,9 +6065,13 @@ struct RepositoriesFeatureTests {
       $0.sidebarSelectedWorktreeIDs = [wt1.id]
       $0.worktreeHistoryBackStack = []
       $0.worktreeHistoryForwardStack = [wt3.id]
+      $0.worktreeMRU = [wt1.id]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
+    await store.receive(\.sidebarItems[id: wt1.id].focusTerminalRequested) {
+      $0.sidebarItems[id: wt1.id]?.shouldFocusTerminal = true
+    }
   }
 
   @Test func worktreeHistoryBackWithOnlyStaleEntriesIsNoOp() async {
@@ -6016,7 +6103,7 @@ struct RepositoriesFeatureTests {
     let mainWorktree = makeWorktree(id: "/tmp/repo/wt-main", name: "main", repoRoot: repoRoot)
     let newWorktree = makeWorktree(id: "/tmp/repo/wt-new", name: "new", repoRoot: repoRoot)
     let updatedRepository = makeRepository(id: repoRoot, worktrees: [newWorktree, mainWorktree])
-    let pendingID = "pending:\(UUID().uuidString)"
+    let pendingID = WorktreeID("pending:\(UUID().uuidString)")
     let repository = makeRepository(id: repoRoot, worktrees: [mainWorktree])
     var initialState = makeState(repositories: [repository])
     initialState.pendingWorktrees = [
@@ -6047,6 +6134,7 @@ struct RepositoriesFeatureTests {
       $0.pendingWorktrees = []
       $0.selection = .worktree(newWorktree.id)
       $0.sidebarSelectedWorktreeIDs = [newWorktree.id]
+      $0.worktreeMRU = [newWorktree.id]
       $0.repositories = [updatedRepository]
       RepositoriesFeature.syncSidebar(&$0)
       $0.sidebarItems[id: newWorktree.id]?.lifecycle = .pending
@@ -6076,7 +6164,7 @@ struct RepositoriesFeatureTests {
     // the user's expectation that the failed create was a no-op.
     let repoRoot = "/tmp/repo"
     let mainWorktree = makeWorktree(id: repoRoot, name: "main", repoRoot: repoRoot)
-    let pendingID = "pending:\(UUID().uuidString)"
+    let pendingID = WorktreeID("pending:\(UUID().uuidString)")
     let repository = makeRepository(id: repoRoot, worktrees: [mainWorktree])
     var initialState = makeState(repositories: [repository])
     initialState.pendingWorktrees = [
@@ -6247,6 +6335,7 @@ struct RepositoriesFeatureTests {
       $0.sidebarSelectedWorktreeIDs = [target]
       // Oldest entry is dropped when we exceed the 50-item cap.
       $0.worktreeHistoryBackStack = (2..<51).map { worktrees[$0].id } + [worktrees[0].id]
+      $0.worktreeMRU = [target]
       $0.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
     }
     await store.receive(\.delegate.selectedWorktreeChanged)
@@ -6258,14 +6347,14 @@ struct RepositoriesFeatureTests {
     let repoID = "/tmp/missing-repo"
     var state = RepositoriesFeature.State()
     state.repositoryRoots = [URL(fileURLWithPath: repoID)]
-    state.loadFailuresByID = [repoID: "Not found"]
+    state.loadFailuresByID = [RepositoryID(repoID): "Not found"]
     let store = TestStore(initialState: state) {
       RepositoriesFeature()
     }
     let expectedAlert = AlertState<RepositoriesFeature.Alert> {
       TextState("Remove missing-repo?")
     } actions: {
-      ButtonState(role: .destructive, action: .confirmRemoveFailedRepository(repoID)) {
+      ButtonState(role: .destructive, action: .confirmRemoveFailedRepository(RepositoryID(repoID))) {
         TextState("Remove Repository")
       }
       ButtonState(role: .cancel) {
@@ -6274,7 +6363,7 @@ struct RepositoriesFeatureTests {
     } message: {
       TextState("Removes the repository from Supacode. Nothing on disk is changed.")
     }
-    await store.send(.requestRemoveFailedRepository(repoID)) {
+    await store.send(.requestRemoveFailedRepository(RepositoryID(repoID))) {
       $0.alert = expectedAlert
     }
   }
@@ -6309,7 +6398,7 @@ struct RepositoriesFeatureTests {
     createdAt: Date? = nil
   ) -> Worktree {
     Worktree(
-      id: id,
+      id: WorktreeID(id),
       name: name,
       detail: "detail",
       workingDirectory: URL(fileURLWithPath: id),
@@ -6350,7 +6439,7 @@ struct RepositoriesFeatureTests {
     worktrees: [Worktree]
   ) -> Repository {
     Repository(
-      id: id,
+      id: RepositoryID(id),
       rootURL: URL(fileURLWithPath: id),
       name: name,
       worktrees: IdentifiedArray(uniqueElements: worktrees)
@@ -6412,7 +6501,7 @@ struct RepositoriesFeatureTests {
     isMainWorktree: Bool = false
   ) -> SidebarItemFeature.State {
     SidebarItemFeature.State(
-      id: id,
+      id: WorktreeID(id),
       repositoryID: repositoryID,
       kind: kind,
       name: name,
@@ -6456,7 +6545,7 @@ struct RepositoriesFeatureTests {
   }
 
   @Test func makeToolbarTitleContentForFolderUsesFolderName() {
-    let folderID = "folder:/tmp/Documents"
+    let folderID = "/tmp/Documents"
     let folderRow = makeSidebarItem(
       id: folderID,
       name: "Documents",
@@ -6475,7 +6564,7 @@ struct RepositoriesFeatureTests {
       hideSubtitleOnMatch: true
     )
 
-    guard case .folder(let name) = content else {
+    guard case .folder(let name, _, _) = content else {
       Issue.record("Expected .folder content, got \(content)")
       return
     }
@@ -6864,6 +6953,7 @@ struct RepositoriesFeatureTests {
     await store.send(.loadPersistedRepositories)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: rootURL),
+      kind: .folder,
       name: Repository.name(for: rootURL),
       detail: "",
       workingDirectory: rootURL,
@@ -6871,7 +6961,7 @@ struct RepositoriesFeatureTests {
       isAttached: false
     )
     let folderRepo = Repository(
-      id: repoRoot,
+      id: RepositoryID(repoRoot),
       rootURL: rootURL,
       name: Repository.name(for: rootURL),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
@@ -6917,7 +7007,56 @@ struct RepositoriesFeatureTests {
       $0.repositoryRoots = [URL(fileURLWithPath: repoRoot)]
       $0.isInitialLoadComplete = true
       $0.loadFailuresByID = [
-        repoRoot: "Directory not found at \(repoRoot). It may have been moved or deleted."
+        RepositoryID(repoRoot): "Directory not found at \(repoRoot). It may have been moved or deleted."
+      ]
+      $0.reconcileSidebarForTesting()
+    }
+    await store.finish()
+  }
+
+  @Test func firstDuplicateWorktreeIDFindsRepeatedPath() {
+    let main = makeWorktree(id: "/r/main", name: "main", repoRoot: "/r")
+    let feature = makeWorktree(id: "/r/feature", name: "feature", repoRoot: "/r")
+    let collision = makeWorktree(id: "/r/feature", name: "other", repoRoot: "/r")
+
+    #expect(RepositoriesFeature.firstDuplicateWorktreeID(in: []) == nil)
+    #expect(RepositoriesFeature.firstDuplicateWorktreeID(in: [main]) == nil)
+    #expect(RepositoriesFeature.firstDuplicateWorktreeID(in: [main, feature]) == nil)
+    #expect(RepositoriesFeature.firstDuplicateWorktreeID(in: [main, feature, collision]) == WorktreeID("/r/feature"))
+    // The first-seen entry is not itself the duplicate; the repeat is.
+    #expect(RepositoriesFeature.firstDuplicateWorktreeID(in: [feature, collision]) == WorktreeID("/r/feature"))
+  }
+
+  @Test func loadPersistedRepositoriesRefusesRepoWithDuplicateWorktreePaths() async {
+    // A corrupt repo (e.g. a stale `core.worktree` redirect) can make the
+    // worktree listing report the same path twice. Rather than crash building an
+    // `IdentifiedArray` of duplicate ids (or silently guess which entry is real),
+    // the loader refuses the repo and routes it through the failure row.
+    let repoRoot = "/tmp/\(UUID().uuidString)-corrupt-git"
+    let duplicatePath = "\(repoRoot)/feature"
+    let first = makeWorktree(id: duplicatePath, name: "main", repoRoot: repoRoot)
+    let second = makeWorktree(id: duplicatePath, name: "feature", repoRoot: repoRoot)
+
+    // Pin the user-facing copy and that it threads the colliding path.
+    let message = RepositoriesFeature.duplicateWorktreePathMessage(path: duplicatePath)
+    #expect(message.contains("more than one worktree at the same path"))
+    #expect(message.contains(duplicatePath))
+
+    let store = TestStore(initialState: RepositoriesFeature.State()) {
+      RepositoriesFeature()
+    } withDependencies: {
+      $0.repositoryPersistence.loadRoots = { [repoRoot] }
+      $0.gitClient.isGitRepository = { _ in true }
+      $0.gitClient.worktrees = { _ in [first, second] }
+    }
+
+    await store.send(.loadPersistedRepositories)
+    await store.receive(\.repositoriesLoaded) {
+      $0.repositories = []
+      $0.repositoryRoots = [URL(fileURLWithPath: repoRoot)]
+      $0.isInitialLoadComplete = true
+      $0.loadFailuresByID = [
+        RepositoryID(repoRoot): RepositoriesFeature.duplicateWorktreePathMessage(path: duplicatePath)
       ]
       $0.reconcileSidebarForTesting()
     }
@@ -6944,7 +7083,7 @@ struct RepositoriesFeatureTests {
     await store.receive(\.repositoriesLoaded) {
       $0.repositories = [
         Repository(
-          id: gitRoot,
+          id: RepositoryID(gitRoot),
           rootURL: URL(fileURLWithPath: gitRoot),
           name: URL(fileURLWithPath: gitRoot).lastPathComponent,
           worktrees: [gitWorktree],
@@ -6954,6 +7093,7 @@ struct RepositoriesFeatureTests {
           let url = URL(fileURLWithPath: folderRoot)
           let synthetic = Worktree(
             id: Repository.folderWorktreeID(for: url),
+            kind: .folder,
             name: Repository.name(for: url),
             detail: "",
             workingDirectory: url,
@@ -6961,7 +7101,7 @@ struct RepositoriesFeatureTests {
             isAttached: false
           )
           return Repository(
-            id: folderRoot,
+            id: RepositoryID(folderRoot),
             rootURL: url,
             name: Repository.name(for: url),
             worktrees: [synthetic],
@@ -7007,6 +7147,7 @@ struct RepositoriesFeatureTests {
 
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: standardizedURL),
+      kind: .folder,
       name: Repository.name(for: standardizedURL),
       detail: "",
       workingDirectory: standardizedURL,
@@ -7014,7 +7155,7 @@ struct RepositoriesFeatureTests {
       isAttached: false
     )
     let folderRepo = Repository(
-      id: rootID,
+      id: RepositoryID(rootID),
       rootURL: standardizedURL,
       name: Repository.name(for: standardizedURL),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
@@ -7044,6 +7185,7 @@ struct RepositoriesFeatureTests {
     let folderURL = URL(fileURLWithPath: "/tmp/folder")
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: "folder",
       detail: "",
       workingDirectory: folderURL,
@@ -7075,13 +7217,14 @@ struct RepositoriesFeatureTests {
     let folderURL = URL(fileURLWithPath: folderRoot)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: Repository.name(for: folderURL),
       detail: "",
       workingDirectory: folderURL,
       repositoryRootURL: folderURL
     )
     let folderRepo = Repository(
-      id: folderRoot,
+      id: RepositoryID(folderRoot),
       rootURL: folderURL,
       name: Repository.name(for: folderURL),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
@@ -7160,13 +7303,14 @@ struct RepositoriesFeatureTests {
     let folderURL = URL(fileURLWithPath: folderRoot)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: Repository.name(for: folderURL),
       detail: "",
       workingDirectory: folderURL,
       repositoryRootURL: folderURL
     )
     let folderRepo = Repository(
-      id: folderRoot,
+      id: RepositoryID(folderRoot),
       rootURL: folderURL,
       name: Repository.name(for: folderURL),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
@@ -7219,13 +7363,14 @@ struct RepositoriesFeatureTests {
     let folderURL = URL(fileURLWithPath: folderRoot)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: Repository.name(for: folderURL),
       detail: "",
       workingDirectory: folderURL,
       repositoryRootURL: folderURL
     )
     let folderRepo = Repository(
-      id: folderRoot,
+      id: RepositoryID(folderRoot),
       rootURL: folderURL,
       name: Repository.name(for: folderURL),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
@@ -7282,13 +7427,14 @@ struct RepositoriesFeatureTests {
     let folderURL = URL(fileURLWithPath: folderRoot)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: Repository.name(for: folderURL),
       detail: "",
       workingDirectory: folderURL,
       repositoryRootURL: folderURL
     )
     let folderRepo = Repository(
-      id: folderRoot,
+      id: RepositoryID(folderRoot),
       rootURL: folderURL,
       name: Repository.name(for: folderURL),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
@@ -7318,13 +7464,14 @@ struct RepositoriesFeatureTests {
     let folderURL = URL(fileURLWithPath: folderRoot)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: Repository.name(for: folderURL),
       detail: "",
       workingDirectory: folderURL,
       repositoryRootURL: folderURL
     )
     let folderRepo = Repository(
-      id: folderRoot,
+      id: RepositoryID(folderRoot),
       rootURL: folderURL,
       name: Repository.name(for: folderURL),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
@@ -7366,13 +7513,14 @@ struct RepositoriesFeatureTests {
     let folderURL = URL(fileURLWithPath: folderRoot)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: Repository.name(for: folderURL),
       detail: "",
       workingDirectory: folderURL,
       repositoryRootURL: folderURL
     )
     let flippedRepo = Repository(
-      id: folderRoot,
+      id: RepositoryID(folderRoot),
       rootURL: folderURL,
       name: Repository.name(for: folderURL),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
@@ -7416,13 +7564,14 @@ struct RepositoriesFeatureTests {
     let folderURL = URL(fileURLWithPath: folderRoot)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: Repository.name(for: folderURL),
       detail: "",
       workingDirectory: folderURL,
       repositoryRootURL: folderURL
     )
     let folderRepo = Repository(
-      id: folderRoot,
+      id: RepositoryID(folderRoot),
       rootURL: folderURL,
       name: Repository.name(for: folderURL),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
@@ -7467,13 +7616,14 @@ struct RepositoriesFeatureTests {
     let folderURL = URL(fileURLWithPath: folderRoot)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: Repository.name(for: folderURL),
       detail: "",
       workingDirectory: folderURL,
       repositoryRootURL: folderURL
     )
     let folderRepo = Repository(
-      id: folderRoot,
+      id: RepositoryID(folderRoot),
       rootURL: folderURL,
       name: Repository.name(for: folderURL),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
@@ -7518,13 +7668,14 @@ struct RepositoriesFeatureTests {
     let rootID = standardized.path(percentEncoded: false)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: standardized),
+      kind: .folder,
       name: Repository.name(for: standardized),
       detail: "",
       workingDirectory: standardized,
       repositoryRootURL: standardized
     )
     let folderRepo = Repository(
-      id: rootID,
+      id: RepositoryID(rootID),
       rootURL: standardized,
       name: Repository.name(for: standardized),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
@@ -7594,11 +7745,12 @@ struct RepositoriesFeatureTests {
     let rootID = missingURL.standardizedFileURL.path(percentEncoded: false)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: missingURL),
+      kind: .folder,
       name: Repository.name(for: missingURL), detail: "",
       workingDirectory: missingURL, repositoryRootURL: missingURL
     )
     let folderRepo = Repository(
-      id: rootID, rootURL: missingURL, name: Repository.name(for: missingURL),
+      id: RepositoryID(rootID), rootURL: missingURL, name: Repository.name(for: missingURL),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
       isGitRepository: false
     )
@@ -7666,11 +7818,12 @@ struct RepositoriesFeatureTests {
     func makeFolderRepo(url: URL, id: String) -> (Worktree, Repository) {
       let worktree = Worktree(
         id: Repository.folderWorktreeID(for: url),
+        kind: .folder,
         name: Repository.name(for: url), detail: "",
         workingDirectory: url, repositoryRootURL: url
       )
       let repo = Repository(
-        id: id, rootURL: url, name: Repository.name(for: url),
+        id: RepositoryID(id), rootURL: url, name: Repository.name(for: url),
         worktrees: IdentifiedArray(uniqueElements: [worktree]),
         isGitRepository: false
       )
@@ -7738,21 +7891,21 @@ struct RepositoriesFeatureTests {
     let gitRoot = "/tmp/alert-clobber-\(UUID().uuidString)-repo"
     let gitURL = URL(fileURLWithPath: gitRoot)
     let worktree = Worktree(
-      id: "\(gitRoot)/wt-1",
+      id: WorktreeID("\(gitRoot)/wt-1"),
       name: "wt-1",
       detail: "",
       workingDirectory: URL(fileURLWithPath: "\(gitRoot)/wt-1"),
       repositoryRootURL: gitURL
     )
     let mainWorktree = Worktree(
-      id: gitRoot,
+      id: WorktreeID(gitRoot),
       name: "repo",
       detail: "",
       workingDirectory: gitURL,
       repositoryRootURL: gitURL
     )
     let gitRepo = Repository(
-      id: gitRoot, rootURL: gitURL, name: "repo",
+      id: RepositoryID(gitRoot), rootURL: gitURL, name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [mainWorktree, worktree]),
       isGitRepository: true
     )
@@ -7825,7 +7978,7 @@ struct RepositoriesFeatureTests {
     state.sidebarItems.append(
       SidebarItemFeature.State(
         id: folderWorktreeID,
-        repositoryID: folderRoot,
+        repositoryID: RepositoryID(folderRoot),
         kind: .folder,
         name: "vanished",
         branchName: "vanished",
@@ -7838,7 +7991,7 @@ struct RepositoriesFeatureTests {
       )
     )
     state.sidebarItems[id: folderWorktreeID]?.lifecycle = .deletingScript
-    let batchID = state.seedRemovalBatch(pending: [folderRoot: .folderUnlink])
+    let batchID = state.seedRemovalBatch(pending: [RepositoryID(folderRoot): .folderUnlink])
 
     let store = TestStore(initialState: state) {
       RepositoriesFeature()
@@ -7858,7 +8011,7 @@ struct RepositoriesFeatureTests {
     await store.skipReceivedActions()
 
     #expect(
-      store.state.removingRepositoryIDs[folderRoot] == nil,
+      store.state.removingRepositoryIDs[RepositoryID(folderRoot)] == nil,
       "record must drain even when owning repo vanished mid-script"
     )
     #expect(
@@ -7884,13 +8037,14 @@ struct RepositoriesFeatureTests {
     func makeFolderRepo(url: URL, id: String) -> (Worktree, Repository) {
       let worktree = Worktree(
         id: Repository.folderWorktreeID(for: url),
+        kind: .folder,
         name: Repository.name(for: url),
         detail: "",
         workingDirectory: url,
         repositoryRootURL: url
       )
       let repo = Repository(
-        id: id, rootURL: url, name: Repository.name(for: url),
+        id: RepositoryID(id), rootURL: url, name: Repository.name(for: url),
         worktrees: IdentifiedArray(uniqueElements: [worktree]), isGitRepository: false)
       return (worktree, repo)
     }
@@ -7946,21 +8100,23 @@ struct RepositoriesFeatureTests {
     let idB = urlB.path(percentEncoded: false)
     let worktreeA = Worktree(
       id: Repository.folderWorktreeID(for: urlA),
+      kind: .folder,
       name: Repository.name(for: urlA), detail: "",
       workingDirectory: urlA, repositoryRootURL: urlA
     )
     let folderA = Repository(
-      id: idA, rootURL: urlA, name: Repository.name(for: urlA),
+      id: RepositoryID(idA), rootURL: urlA, name: Repository.name(for: urlA),
       worktrees: IdentifiedArray(uniqueElements: [worktreeA]),
       isGitRepository: false
     )
     let worktreeB = Worktree(
       id: Repository.folderWorktreeID(for: urlB),
+      kind: .folder,
       name: Repository.name(for: urlB), detail: "",
       workingDirectory: urlB, repositoryRootURL: urlB
     )
     let folderB = Repository(
-      id: idB, rootURL: urlB, name: Repository.name(for: urlB),
+      id: RepositoryID(idB), rootURL: urlB, name: Repository.name(for: urlB),
       worktrees: IdentifiedArray(uniqueElements: [worktreeB]),
       isGitRepository: false
     )
@@ -8002,7 +8158,7 @@ struct RepositoriesFeatureTests {
       prunedIDs.value.flatMap { $0 } == [idA],
       "pruneRepositoryConfigs must drop the removed repo's config entry"
     )
-    #expect(store.state.repositories.map(\.id) == [idB])
+    #expect(store.state.repositories.map(\.id) == [RepositoryID(idB)])
     #expect(store.state.repositoryRoots.map { $0.path(percentEncoded: false) } == [idB])
   }
 
@@ -8019,6 +8175,7 @@ struct RepositoriesFeatureTests {
     let urlB = URL(fileURLWithPath: rootB)
     let worktreeA = Worktree(
       id: Repository.folderWorktreeID(for: urlA),
+      kind: .folder,
       name: Repository.name(for: urlA),
       detail: "",
       workingDirectory: urlA,
@@ -8026,20 +8183,21 @@ struct RepositoriesFeatureTests {
     )
     let worktreeB = Worktree(
       id: Repository.folderWorktreeID(for: urlB),
+      kind: .folder,
       name: Repository.name(for: urlB),
       detail: "",
       workingDirectory: urlB,
       repositoryRootURL: urlB
     )
     let folderA = Repository(
-      id: rootA,
+      id: RepositoryID(rootA),
       rootURL: urlA,
       name: Repository.name(for: urlA),
       worktrees: IdentifiedArray(uniqueElements: [worktreeA]),
       isGitRepository: false
     )
     let folderB = Repository(
-      id: rootB,
+      id: RepositoryID(rootB),
       rootURL: urlB,
       name: Repository.name(for: urlB),
       worktrees: IdentifiedArray(uniqueElements: [worktreeB]),
@@ -8095,21 +8253,21 @@ struct RepositoriesFeatureTests {
     let gitRoot = "/tmp/\(UUID().uuidString)-git"
     let gitURL = URL(fileURLWithPath: gitRoot)
     let gitMain = Worktree(
-      id: "\(gitRoot)/main",
+      id: WorktreeID("\(gitRoot)/main"),
       name: "main",
       detail: "",
       workingDirectory: gitURL,
       repositoryRootURL: gitURL
     )
     let gitFeature = Worktree(
-      id: "\(gitRoot)/feature",
+      id: WorktreeID("\(gitRoot)/feature"),
       name: "feature",
       detail: "",
       workingDirectory: gitURL.appending(path: "feature"),
       repositoryRootURL: gitURL
     )
     let gitRepo = Repository(
-      id: gitRoot,
+      id: RepositoryID(gitRoot),
       rootURL: gitURL,
       name: "git-repo",
       worktrees: IdentifiedArray(uniqueElements: [gitMain, gitFeature]),
@@ -8119,13 +8277,14 @@ struct RepositoriesFeatureTests {
     let folderURL = URL(fileURLWithPath: folderRoot)
     let folderMain = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: Repository.name(for: folderURL),
       detail: "",
       workingDirectory: folderURL,
       repositoryRootURL: folderURL
     )
     let folderRepo = Repository(
-      id: folderRoot,
+      id: RepositoryID(folderRoot),
       rootURL: folderURL,
       name: Repository.name(for: folderURL),
       worktrees: IdentifiedArray(uniqueElements: [folderMain]),
@@ -8167,7 +8326,7 @@ struct RepositoriesFeatureTests {
     let featureWorktree = makeWorktree(
       id: "\(repoRoot)/feature", name: "feature", repoRoot: repoRoot)
     let gitRepo = Repository(
-      id: repoRoot,
+      id: RepositoryID(repoRoot),
       rootURL: repoURL,
       name: URL(fileURLWithPath: repoRoot).lastPathComponent,
       worktrees: IdentifiedArray(uniqueElements: [mainWorktree, featureWorktree]),
@@ -8214,13 +8373,14 @@ struct RepositoriesFeatureTests {
     let folderURL = URL(fileURLWithPath: folderRoot)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: Repository.name(for: folderURL),
       detail: "",
       workingDirectory: folderURL,
       repositoryRootURL: folderURL
     )
     let folderRepo = Repository(
-      id: folderRoot,
+      id: RepositoryID(folderRoot),
       rootURL: folderURL,
       name: Repository.name(for: folderURL),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
@@ -8260,24 +8420,25 @@ struct RepositoriesFeatureTests {
     let folderURL = URL(fileURLWithPath: folderRoot)
     let folderWorktree = Worktree(
       id: Repository.folderWorktreeID(for: folderURL),
+      kind: .folder,
       name: Repository.name(for: folderURL),
       detail: "",
       workingDirectory: folderURL,
       repositoryRootURL: folderURL
     )
     let folderRepo = Repository(
-      id: folderRoot, rootURL: folderURL, name: Repository.name(for: folderURL),
+      id: RepositoryID(folderRoot), rootURL: folderURL, name: Repository.name(for: folderURL),
       worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
       isGitRepository: false
     )
     let gitRoot = "/tmp/\(UUID().uuidString)-repo"
     let gitURL = URL(fileURLWithPath: gitRoot)
     let gitMain = Worktree(
-      id: gitRoot, name: Repository.name(for: gitURL), detail: "",
+      id: WorktreeID(gitRoot), name: Repository.name(for: gitURL), detail: "",
       workingDirectory: gitURL, repositoryRootURL: gitURL
     )
     let gitRepo = Repository(
-      id: gitRoot, rootURL: gitURL, name: Repository.name(for: gitURL),
+      id: RepositoryID(gitRoot), rootURL: gitURL, name: Repository.name(for: gitURL),
       worktrees: IdentifiedArray(uniqueElements: [gitMain]),
       isGitRepository: true
     )
@@ -8335,11 +8496,12 @@ struct RepositoriesFeatureTests {
       let folderURL = URL(fileURLWithPath: folderRoot)
       let folderWorktree = Worktree(
         id: Repository.folderWorktreeID(for: folderURL),
+        kind: .folder,
         name: Repository.name(for: folderURL), detail: "",
         workingDirectory: folderURL, repositoryRootURL: folderURL
       )
       let folderRepo = Repository(
-        id: folderRoot, rootURL: folderURL, name: Repository.name(for: folderURL),
+        id: RepositoryID(folderRoot), rootURL: folderURL, name: Repository.name(for: folderURL),
         worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
         isGitRepository: false
       )
@@ -8390,11 +8552,12 @@ struct RepositoriesFeatureTests {
       let folderURL = URL(fileURLWithPath: folderRoot)
       let folderWorktree = Worktree(
         id: Repository.folderWorktreeID(for: folderURL),
+        kind: .folder,
         name: Repository.name(for: folderURL), detail: "",
         workingDirectory: folderURL, repositoryRootURL: folderURL
       )
       let folderRepo = Repository(
-        id: folderRoot, rootURL: folderURL, name: Repository.name(for: folderURL),
+        id: RepositoryID(folderRoot), rootURL: folderURL, name: Repository.name(for: folderURL),
         worktrees: IdentifiedArray(uniqueElements: [folderWorktree]),
         isGitRepository: false
       )
diff --git a/supacodeTests/RepositoriesFeatureWorktreeMRUTests.swift b/supacodeTests/RepositoriesFeatureWorktreeMRUTests.swift
new file mode 100644
index 000000000..71d5a49ff
--- /dev/null
+++ b/supacodeTests/RepositoriesFeatureWorktreeMRUTests.swift
@@ -0,0 +1,125 @@
+import ComposableArchitecture
+import Foundation
+import IdentifiedCollections
+import SupacodeSettingsShared
+import Testing
+
+@testable import supacode
+
+@MainActor
+struct RepositoriesFeatureWorktreeMRUTests {
+  @Test func setSingleWorktreeSelection_pushesWorktreeOntoMRU() {
+    let worktree = makeWorktree(id: "/tmp/repo-a/wt", name: "wt", repoRoot: "/tmp/repo-a")
+    let repository = makeRepository(rootPath: "/tmp/repo-a", name: "A", worktrees: [worktree])
+    var state = RepositoriesFeature.State(reconciledRepositories: [repository])
+
+    state.setSingleWorktreeSelection(worktree.id)
+
+    #expect(state.worktreeMRU == [worktree.id])
+  }
+
+  @Test func setSingleWorktreeSelection_dedupesWorktreeInMRUOnRepeat() {
+    let wt1 = makeWorktree(id: "/tmp/repo-a/wt-1", name: "wt-1", repoRoot: "/tmp/repo-a")
+    let wt2 = makeWorktree(id: "/tmp/repo-a/wt-2", name: "wt-2", repoRoot: "/tmp/repo-a")
+    let repo = makeRepository(rootPath: "/tmp/repo-a", name: "A", worktrees: [wt1, wt2])
+    var state = RepositoriesFeature.State(reconciledRepositories: [repo])
+
+    state.setSingleWorktreeSelection(wt1.id)
+    state.setSingleWorktreeSelection(wt2.id)
+    state.setSingleWorktreeSelection(wt1.id)
+
+    // Re-selecting wt1 hoists it back to the head without duplicating it.
+    #expect(state.worktreeMRU == [wt1.id, wt2.id])
+  }
+
+  @Test func setSingleWorktreeSelection_movesPriorWorktreeBehindLatest() {
+    // The Cmd+Tab toggle invariant: the two most-recent worktrees swap
+    // positions as you bounce between them, across repositories.
+    let wtA = makeWorktree(id: "/tmp/repo-a/wt", name: "wt", repoRoot: "/tmp/repo-a")
+    let wtB = makeWorktree(id: "/tmp/repo-b/wt", name: "wt", repoRoot: "/tmp/repo-b")
+    let repoA = makeRepository(rootPath: "/tmp/repo-a", name: "A", worktrees: [wtA])
+    let repoB = makeRepository(rootPath: "/tmp/repo-b", name: "B", worktrees: [wtB])
+    var state = RepositoriesFeature.State(reconciledRepositories: [repoA, repoB])
+
+    state.setSingleWorktreeSelection(wtA.id)
+    state.setSingleWorktreeSelection(wtB.id)
+    state.setSingleWorktreeSelection(wtA.id)
+
+    #expect(state.worktreeMRU == [wtA.id, wtB.id])
+  }
+
+  @Test func setSingleWorktreeSelection_nilDoesNotPolluteMRU() {
+    let wtA = makeWorktree(id: "/tmp/repo-a/wt", name: "wt", repoRoot: "/tmp/repo-a")
+    let repoA = makeRepository(rootPath: "/tmp/repo-a", name: "A", worktrees: [wtA])
+    var state = RepositoriesFeature.State(reconciledRepositories: [repoA])
+
+    state.setSingleWorktreeSelection(wtA.id)
+    state.setSingleWorktreeSelection(nil)
+
+    // Clearing the selection must leave the MRU head pointing at the
+    // worktree the user just stepped out of, not at "nothing." Otherwise
+    // a programmatic deselect (e.g. archive flow) would wipe the very
+    // recency signal ⌘P relies on.
+    #expect(state.worktreeMRU == [wtA.id])
+  }
+
+  @Test func sidebarSelectionChange_recordsWorktreeMRU() {
+    // The dominant interaction — clicking a worktree in the sidebar — routes
+    // through `.selectionChanged` / `reduceSelectionChangedEffect`, NOT
+    // `setSingleWorktreeSelection`. If MRU recording only lives in the latter,
+    // sidebar navigation never updates `worktreeMRU`, and the ⌘P switcher
+    // can't put the worktree the user actually had open at the top. This pins
+    // that bug.
+    let wt1 = makeWorktree(id: "/tmp/repo-a/wt-1", name: "wt-1", repoRoot: "/tmp/repo-a")
+    let wt2 = makeWorktree(id: "/tmp/repo-a/wt-2", name: "wt-2", repoRoot: "/tmp/repo-a")
+    let repoA = makeRepository(rootPath: "/tmp/repo-a", name: "A", worktrees: [wt1, wt2])
+    var state = RepositoriesFeature.State(reconciledRepositories: [repoA])
+
+    // Simulate a sidebar click landing on the *second* worktree.
+    _ = state.reduceSelectionChangedEffect(selections: [.worktree(wt2.id)], focusTerminal: false)
+
+    #expect(state.worktreeMRU == [wt2.id])
+  }
+
+  @Test func sidebarSelectionChange_movesPriorWorktreeBehindLatest() {
+    let wtA = makeWorktree(id: "/tmp/repo-a/wt", name: "wt", repoRoot: "/tmp/repo-a")
+    let wtB = makeWorktree(id: "/tmp/repo-b/wt", name: "wt", repoRoot: "/tmp/repo-b")
+    let repoA = makeRepository(rootPath: "/tmp/repo-a", name: "A", worktrees: [wtA])
+    let repoB = makeRepository(rootPath: "/tmp/repo-b", name: "B", worktrees: [wtB])
+    var state = RepositoriesFeature.State(reconciledRepositories: [repoA, repoB])
+
+    _ = state.reduceSelectionChangedEffect(selections: [.worktree(wtA.id)], focusTerminal: false)
+    _ = state.reduceSelectionChangedEffect(selections: [.worktree(wtB.id)], focusTerminal: false)
+    _ = state.reduceSelectionChangedEffect(selections: [.worktree(wtA.id)], focusTerminal: false)
+
+    #expect(state.worktreeMRU == [wtA.id, wtB.id])
+  }
+}
+
+private func makeWorktree(
+  id: String,
+  name: String,
+  repoRoot: String
+) -> Worktree {
+  Worktree(
+    id: id,
+    name: name,
+    detail: "detail",
+    workingDirectory: URL(fileURLWithPath: id),
+    repositoryRootURL: URL(fileURLWithPath: repoRoot)
+  )
+}
+
+private func makeRepository(
+  rootPath: String,
+  name: String,
+  worktrees: [Worktree]
+) -> Repository {
+  let rootURL = URL(fileURLWithPath: rootPath)
+  return Repository(
+    id: rootURL.path(percentEncoded: false),
+    rootURL: rootURL,
+    name: name,
+    worktrees: IdentifiedArray(uniqueElements: worktrees)
+  )
+}
diff --git a/supacodeTests/RepositoriesSidebarTestHelpers.swift b/supacodeTests/RepositoriesSidebarTestHelpers.swift
index 84e1c79a5..9ef5a2637 100644
--- a/supacodeTests/RepositoriesSidebarTestHelpers.swift
+++ b/supacodeTests/RepositoriesSidebarTestHelpers.swift
@@ -36,7 +36,9 @@ extension RepositoriesFeature.State {
   init(reconciledRepositories repositories: [Repository]) {
     self.init()
     self.repositories = IdentifiedArray(uniqueElements: repositories)
-    self.repositoryRoots = repositories.map(\.rootURL)
+    // Remote repos persist via the connections store, never `repositoryRoots`;
+    // only local roots belong here, matching production.
+    self.repositoryRoots = repositories.filter { $0.host == nil }.map(\.rootURL)
     reconcileSidebarForTesting()
   }
 
diff --git a/supacodeTests/RepositoryCustomizationFeatureTests.swift b/supacodeTests/RepositoryCustomizationFeatureTests.swift
index cccbab010..ae1c0a153 100644
--- a/supacodeTests/RepositoryCustomizationFeatureTests.swift
+++ b/supacodeTests/RepositoryCustomizationFeatureTests.swift
@@ -32,8 +32,8 @@ struct RepositoryCustomizationFeatureTests {
       ))
   }
 
-  @Test func saveDropsTitleWhenEmptyOrMatchesDefault() async {
-    let store = TestStore(initialState: makeState(title: "  repo  ")) {
+  @Test func saveDropsTitleOnlyWhenEmptyAfterTrim() async {
+    let store = TestStore(initialState: makeState(title: "   ")) {
       RepositoryCustomizationFeature()
     }
 
@@ -43,6 +43,18 @@ struct RepositoryCustomizationFeatureTests {
     )
   }
 
+  @Test func savePreservesTitleEvenWhenItMatchesDefault() async {
+    // Typing the default name locks it in as an explicit override (doesn't collapse to nil).
+    let store = TestStore(initialState: makeState(title: "repo")) {
+      RepositoryCustomizationFeature()
+    }
+
+    await store.send(.saveButtonTapped)
+    await store.receive(
+      .delegate(.save(repositoryID: "/tmp/repo", title: "repo", color: nil)),
+    )
+  }
+
   @Test func cancelDelegatesCancel() async {
     let store = TestStore(initialState: makeState()) {
       RepositoryCustomizationFeature()
diff --git a/supacodeTests/RepositoryIdentityTests.swift b/supacodeTests/RepositoryIdentityTests.swift
new file mode 100644
index 000000000..b0120b9b5
--- /dev/null
+++ b/supacodeTests/RepositoryIdentityTests.swift
@@ -0,0 +1,219 @@
+import Foundation
+import Testing
+
+@testable import SupacodeSettingsShared
+@testable import supacode
+
+extension Worktree {
+  /// Test convenience: a git worktree without the explicit `kind` the production
+  /// initializers now require. Folder tests pass `kind: .folder` directly.
+  init(
+    id: WorktreeID,
+    name: String,
+    detail: String,
+    workingDirectory: URL,
+    repositoryRootURL: URL,
+    createdAt: Date? = nil,
+    isMissing: Bool = false,
+    isAttached: Bool = true,
+    host: RemoteHost? = nil
+  ) {
+    self.init(
+      id: id,
+      kind: .git,
+      name: name,
+      detail: detail,
+      workingDirectory: workingDirectory,
+      repositoryRootURL: repositoryRootURL,
+      createdAt: createdAt,
+      isMissing: isMissing,
+      isAttached: isAttached,
+      host: host
+    )
+  }
+}
+
+struct RepositoryIdentityTests {
+  // MARK: - Branded id codable shape
+
+  @Test func repositoryIDEncodesAsBareString() throws {
+    let id = RepositoryID("/Users/me/repo/")
+    let data = try JSONEncoder().encode(id)
+    #expect(String(bytes: data, encoding: .utf8) == "\"\\/Users\\/me\\/repo\\/\"")
+    #expect(try JSONDecoder().decode(RepositoryID.self, from: data) == id)
+  }
+
+  @Test func worktreeIDEncodesAsBareString() throws {
+    let id = WorktreeID("/Users/me/repo/wt")
+    let data = try JSONEncoder().encode(id)
+    #expect(try JSONDecoder().decode(WorktreeID.self, from: data) == id)
+  }
+
+  @Test func stringLiteralBridges() {
+    let repo: RepositoryID = "/tmp/x/"
+    let worktree: WorktreeID = "/tmp/x/wt"
+    #expect(repo.rawValue == "/tmp/x/")
+    #expect(worktree.rawValue == "/tmp/x/wt")
+  }
+
+  // MARK: - RemoteHost.authority
+
+  @Test func authorityFoldsInUserAndPort() {
+    #expect(RemoteHost(alias: "box").authority == "box")
+    #expect(RemoteHost(alias: "box", username: "me").authority == "me@box")
+    #expect(RemoteHost(alias: "box", username: "me", port: 2222).authority == "me@box:2222")
+    #expect(RemoteHost(alias: "box", port: 2222).authority == "box:2222")
+  }
+
+  @Test func displayAuthorityDropsDefaultPortAndUnsetUser() {
+    #expect(RemoteHost(alias: "box").displayAuthority == "box")
+    #expect(RemoteHost(alias: "box", username: "me").displayAuthority == "me@box")
+    // Default port 22 is dropped (unlike `authority`); a non-default port shows.
+    #expect(RemoteHost(alias: "box", port: 22).displayAuthority == "box")
+    #expect(RemoteHost(alias: "box", port: 2222).displayAuthority == "box:2222")
+    #expect(RemoteHost(alias: "box", username: "me", port: 2222).displayAuthority == "me@box:2222")
+  }
+
+  // MARK: - RepositoryLocation
+
+  @Test func localLocationDerivesPathIDAndExposesLocalURL() {
+    let url = URL(fileURLWithPath: "/Users/me/repo", isDirectory: true)
+    let location = RepositoryLocation.local(url)
+    #expect(location.host == nil)
+    #expect(location.localRootURL == url)
+    #expect(location.id == RepositoryID("/Users/me/repo/"))
+  }
+
+  @Test func remoteLocationBrandsHostAndHidesLocalURL() {
+    let host = RemoteHost(alias: "box", username: "me", port: 2222)
+    let location = RepositoryLocation.remote(host, path: "/srv/repo")
+    #expect(location.host == host)
+    // The danger this whole refactor removes: a remote location yields no local URL.
+    #expect(location.localRootURL == nil)
+    #expect(location.id == RepositoryID("me@box:2222/srv/repo"))
+    #expect(location.path == "/srv/repo")
+  }
+
+  @Test func remoteWithoutPortOmitsPort() {
+    let host = RemoteHost(alias: "box")
+    #expect(RepositoryLocation.remote(host, path: "/srv/repo").id == RepositoryID("box/srv/repo"))
+  }
+
+  // MARK: - RemoteHost authority round-trip
+
+  @Test func authorityParsesBackToHost() {
+    for host in [
+      RemoteHost(alias: "box"),
+      RemoteHost(alias: "box", username: "me"),
+      RemoteHost(alias: "box", port: 2222),
+      RemoteHost(alias: "box", username: "me", port: 2222),
+      // IPv6 literals must round-trip too: `authority` brackets the host so the
+      // `:port` (and the colons in the address) stay unambiguous.
+      RemoteHost(alias: "fe80::1"),
+      RemoteHost(alias: "fe80::1", port: 2222),
+      RemoteHost(alias: "::1", username: "me", port: 22),
+    ] {
+      #expect(RemoteHost(authority: host.authority) == host)
+    }
+  }
+
+  @Test func remoteIDRoundTripsForEveryHostShape() {
+    for host in [
+      RemoteHost(alias: "box"),
+      RemoteHost(alias: "box", username: "me", port: 2222),
+      RemoteHost(alias: "fe80::1"),
+      RemoteHost(alias: "fe80::1", username: "me", port: 2222),
+    ] {
+      let location = RepositoryLocation.remote(host, path: "/srv/repo")
+      #expect(RepositoryLocation.parse(persistedID: location.id.rawValue) == location)
+    }
+  }
+
+  @Test func authorityParserHandlesBracketedIPv6() {
+    let host = RemoteHost(authority: "me@[fe80::1]:2222")
+    #expect(host == RemoteHost(alias: "fe80::1", username: "me", port: 2222))
+  }
+
+  @Test func authorityParserRejectsEmptyHost() {
+    #expect(RemoteHost(authority: "") == nil)
+    #expect(RemoteHost(authority: "me@") == nil)
+  }
+
+  // MARK: - RepositoryLocation persisted-id parsing
+
+  @Test func parsesLocalAndRemotePersistedIDs() {
+    #expect(RepositoryLocation.parse(persistedID: "/Users/me/repo") == .local(URL(fileURLWithPath: "/Users/me/repo")))
+    #expect(
+      RepositoryLocation.parse(persistedID: "me@box:2222/srv/repo")
+        == .remote(RemoteHost(alias: "box", username: "me", port: 2222), path: "/srv/repo"))
+    #expect(
+      RepositoryLocation.parse(persistedID: "box/srv/repo")
+        == .remote(RemoteHost(alias: "box"), path: "/srv/repo"))
+  }
+
+  @Test func remoteIDRoundTripsThroughParse() {
+    let host = RemoteHost(alias: "box", username: "me", port: 2222)
+    let id = RepositoryLocation.remote(host, path: "/srv/repo").id
+    #expect(RepositoryLocation.parse(persistedID: id.rawValue) == .remote(host, path: "/srv/repo"))
+  }
+
+  @Test func normalizedRemotePathTrimsTrailingSlashes() {
+    #expect(RepositoryLocation.normalizedRemotePath("/srv/repo/") == "/srv/repo")
+    #expect(RepositoryLocation.normalizedRemotePath("  /srv/repo  ") == "/srv/repo")
+    #expect(RepositoryLocation.normalizedRemotePath("/") == "/")
+  }
+
+  // MARK: - WorktreeLocation id derivation
+
+  @Test func localGitWorktreeIDIsBarePath() {
+    let location = WorktreeLocation.local(
+      workingDirectory: URL(fileURLWithPath: "/repo/wt"),
+      repositoryRoot: URL(fileURLWithPath: "/repo")
+    )
+    #expect(location.id == WorktreeID("/repo/wt"))
+    #expect(location.localWorkingDirectory == URL(fileURLWithPath: "/repo/wt"))
+  }
+
+  @Test func remoteGitWorktreeIDBrandsHost() {
+    let host = RemoteHost(alias: "box", port: 22)
+    let location = WorktreeLocation.remote(host, workingDirectory: "/repo/wt", repositoryRoot: "/repo")
+    #expect(location.id == WorktreeID("box:22/repo/wt"))
+    #expect(location.localWorkingDirectory == nil)
+    #expect(location.host == host)
+  }
+
+  // MARK: - Folder synthetic id (kind lives on Worktree, not the id)
+
+  @Test func localFolderWorktreeIDIsTheRepositoryPath() {
+    let repoURL = URL(fileURLWithPath: "/Users/me/notes", isDirectory: true)
+    // The folder synthetic shares the path-derived id with its repo; git-vs-folder
+    // is carried by `Worktree.kind`, not baked into the id.
+    let id = Repository.folderWorktreeID(for: repoURL)
+    #expect(id == WorktreeID("/Users/me/notes/"))
+    #expect(id.rawValue == RepositoryLocation.local(repoURL).id.rawValue)
+  }
+
+  @Test func worktreeKindDrivesIsFolder() {
+    let location = WorktreeLocation.local(
+      workingDirectory: URL(fileURLWithPath: "/repo"),
+      repositoryRoot: URL(fileURLWithPath: "/repo")
+    )
+    let folder = Worktree(location: location, kind: .folder, name: "repo", detail: "")
+    let git = Worktree(location: location, kind: .git, name: "repo", detail: "")
+    #expect(folder.isFolder)
+    #expect(!git.isFolder)
+    // Same location yields the same id regardless of kind.
+    #expect(folder.id == git.id)
+  }
+
+  @Test func worktreeLocationExposesOwningRepositoryLocation() {
+    let host = RemoteHost(alias: "box")
+    let remote = WorktreeLocation.remote(host, workingDirectory: "/repo/wt", repositoryRoot: "/repo")
+    #expect(remote.repositoryLocation.id == RepositoryID("box/repo"))
+    let local = WorktreeLocation.local(
+      workingDirectory: URL(fileURLWithPath: "/repo/wt"),
+      repositoryRoot: URL(fileURLWithPath: "/repo", isDirectory: true)
+    )
+    #expect(local.repositoryLocation.id == RepositoryID("/repo/"))
+  }
+}
diff --git a/supacodeTests/RepositoryPersistenceClientTests.swift b/supacodeTests/RepositoryPersistenceClientTests.swift
index ba8b3b986..87f809b75 100644
--- a/supacodeTests/RepositoryPersistenceClientTests.swift
+++ b/supacodeTests/RepositoryPersistenceClientTests.swift
@@ -8,6 +8,18 @@ import Testing
 @testable import supacode
 
 struct RepositoryPersistenceClientTests {
+  // MARK: - normalize (shape-aware)
+
+  @Test func normalizeStandardizesLocalPathsButPassesRemoteIdsVerbatim() {
+    // Local ids (absolute paths) are filesystem-standardized as before.
+    #expect(RepositoryPathNormalizer.normalize("/tmp/repo/../repo") == "/tmp/repo")
+    // Remote ids (`[user@]host[:port]<path>`) must NOT hit `URL(fileURLWithPath:)`,
+    // which would prepend the cwd and mangle them; they pass through trimmed.
+    #expect(RepositoryPathNormalizer.normalize("me@box:2222/srv/repo") == "me@box:2222/srv/repo")
+    #expect(RepositoryPathNormalizer.normalize("  box/srv/repo  ") == "box/srv/repo")
+    #expect(RepositoryPathNormalizer.normalize("   ") == nil)
+  }
+
   // MARK: - normalizeDictionaryKeys
 
   @Test func normalizeDictionaryKeysResolvesPaths() {
diff --git a/supacodeTests/RepositorySettingsKeyTests.swift b/supacodeTests/RepositorySettingsKeyTests.swift
index 5a56220cb..56c63d8d9 100644
--- a/supacodeTests/RepositorySettingsKeyTests.swift
+++ b/supacodeTests/RepositorySettingsKeyTests.swift
@@ -320,6 +320,103 @@ struct RepositorySettingsKeyTests {
     #expect(localStorage.data(at: localURL) == nil)
   }
 
+  // MARK: - Remote keying
+
+  @Test(.dependencies) func remoteKeyBrandsByHostSoSamePathDoesNotCollide() throws {
+    let storage = SettingsTestStorage()
+    let path = "/srv/repo"
+    let rootURL = URL(fileURLWithPath: path)
+    let hostA = RemoteHost(alias: "box-a")
+    let hostB = RemoteHost(alias: "box-b")
+
+    var settingsA = RepositorySettings.default
+    settingsA.setupScript = "echo a"
+    var settingsB = RepositorySettings.default
+    settingsB.setupScript = "echo b"
+
+    withDependencies {
+      $0.settingsFileStorage = storage.storage
+    } operation: {
+      @Shared(.repositorySettings(rootURL, host: hostA)) var forHostA: RepositorySettings
+      $forHostA.withLock { $0 = settingsA }
+      @Shared(.repositorySettings(rootURL, host: hostB)) var forHostB: RepositorySettings
+      $forHostB.withLock { $0 = settingsB }
+    }
+
+    let saved: SettingsFile = withDependencies {
+      $0.settingsFileStorage = storage.storage
+    } operation: {
+      @Shared(.settingsFile) var settings: SettingsFile
+      return settings
+    }
+
+    #expect(saved.repositories["box-a/srv/repo"] == settingsA)
+    #expect(saved.repositories["box-b/srv/repo"] == settingsB)
+    // The bare path key (a local repo at the same path) stays untouched.
+    #expect(saved.repositories[path] == nil)
+  }
+
+  @Test(.dependencies) func remoteRepoIgnoresLocalSupacodeJSONOnLoad() throws {
+    let globalStorage = SettingsTestStorage()
+    let localStorage = RepositoryLocalSettingsTestStorage()
+    let path = "/srv/repo"
+    let rootURL = URL(fileURLWithPath: path)
+    let host = RemoteHost(alias: "box")
+
+    // A local supacode.json physically present at the same path must never be
+    // read for a remote repo (it would belong to a different local checkout).
+    var localSettings = RepositorySettings.default
+    localSettings.setupScript = "echo local-bleed"
+    try localStorage.save(encode(localSettings), at: SupacodePaths.repositorySettingsURL(for: rootURL))
+
+    let loaded = withDependencies {
+      $0.settingsFileStorage = globalStorage.storage
+      $0.repositoryLocalSettingsStorage = localStorage.storage
+    } operation: {
+      @Shared(.repositorySettings(rootURL, host: host)) var repositorySettings: RepositorySettings
+      return repositorySettings
+    }
+
+    #expect(loaded == RepositorySettings.default)
+  }
+
+  @Test(.dependencies) func remoteRepoNeverWritesLocalSupacodeJSON() throws {
+    let globalStorage = SettingsTestStorage()
+    let localStorage = RepositoryLocalSettingsTestStorage()
+    let path = "/srv/repo"
+    let rootURL = URL(fileURLWithPath: path)
+    let host = RemoteHost(alias: "box")
+    let localURL = SupacodePaths.repositorySettingsURL(for: rootURL)
+
+    // Even with a pre-existing local file at the path, a remote save must route
+    // to the global settings file (keyed by branded id), not the local disk.
+    try localStorage.save(encode(.default), at: localURL)
+
+    var updated = RepositorySettings.default
+    updated.setupScript = "echo remote"
+
+    withDependencies {
+      $0.settingsFileStorage = globalStorage.storage
+      $0.repositoryLocalSettingsStorage = localStorage.storage
+    } operation: {
+      @Shared(.repositorySettings(rootURL, host: host)) var repositorySettings: RepositorySettings
+      $repositorySettings.withLock { $0 = updated }
+    }
+
+    let localData = try #require(localStorage.data(at: localURL))
+    let localDecoded = try JSONDecoder().decode(RepositorySettings.self, from: localData)
+    #expect(localDecoded == .default)
+
+    let globalSaved: SettingsFile = withDependencies {
+      $0.settingsFileStorage = globalStorage.storage
+      $0.repositoryLocalSettingsStorage = localStorage.storage
+    } operation: {
+      @Shared(.settingsFile) var settings: SettingsFile
+      return settings
+    }
+    #expect(globalSaved.repositories["box/srv/repo"] == updated)
+  }
+
   private func encode(_ settings: RepositorySettings) throws -> Data {
     let encoder = JSONEncoder()
     encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
diff --git a/supacodeTests/ResolvedRowDisplayTests.swift b/supacodeTests/ResolvedRowDisplayTests.swift
index 86c76cb92..3fff5863f 100644
--- a/supacodeTests/ResolvedRowDisplayTests.swift
+++ b/supacodeTests/ResolvedRowDisplayTests.swift
@@ -30,7 +30,7 @@ struct ResolvedRowDisplayTests {
       isPinned: true,
       hideSubtitle: false,
       hideSubtitleOnMatch: false,
-      highlightSubtitle: SidebarHighlightRepoTag(repoName: "Notes", repoColor: nil)
+      highlightSubtitle: SidebarHighlightRepoTag(repoName: "Notes", repoColor: nil, hostInfo: nil)
     )
     #expect(resolved.subtitle == .none)
   }
@@ -100,9 +100,9 @@ struct ResolvedRowDisplayTests {
       isPinned: false,
       hideSubtitle: false,
       hideSubtitleOnMatch: true,
-      highlightSubtitle: SidebarHighlightRepoTag(repoName: "supacode", repoColor: .blue)
+      highlightSubtitle: SidebarHighlightRepoTag(repoName: "supacode", repoColor: .blue, hostInfo: nil)
     )
-    guard case .highlight(let repo, let color, let trail) = resolved.subtitle else {
+    guard case .highlight(let repo, let color, let trail, _) = resolved.subtitle else {
       Issue.record("Expected .highlight subtitle for main worktree")
       return
     }
@@ -120,9 +120,9 @@ struct ResolvedRowDisplayTests {
       isPinned: true,
       hideSubtitle: false,
       hideSubtitleOnMatch: true,
-      highlightSubtitle: SidebarHighlightRepoTag(repoName: "supacode", repoColor: nil)
+      highlightSubtitle: SidebarHighlightRepoTag(repoName: "supacode", repoColor: nil, hostInfo: nil)
     )
-    guard case .highlight(_, _, let trail) = resolved.subtitle else {
+    guard case .highlight(_, _, let trail, _) = resolved.subtitle else {
       Issue.record("Expected .highlight subtitle")
       return
     }
@@ -138,9 +138,9 @@ struct ResolvedRowDisplayTests {
       isPinned: true,
       hideSubtitle: false,
       hideSubtitleOnMatch: false,
-      highlightSubtitle: SidebarHighlightRepoTag(repoName: "supacode", repoColor: nil)
+      highlightSubtitle: SidebarHighlightRepoTag(repoName: "supacode", repoColor: nil, hostInfo: nil)
     )
-    guard case .highlight(_, _, let trail) = resolved.subtitle else {
+    guard case .highlight(_, _, let trail, _) = resolved.subtitle else {
       Issue.record("Expected .highlight subtitle")
       return
     }
@@ -156,9 +156,9 @@ struct ResolvedRowDisplayTests {
       isPinned: false,
       hideSubtitle: false,
       hideSubtitleOnMatch: true,
-      highlightSubtitle: SidebarHighlightRepoTag(repoName: "supacode", repoColor: nil)
+      highlightSubtitle: SidebarHighlightRepoTag(repoName: "supacode", repoColor: nil, hostInfo: nil)
     )
-    guard case .highlight(_, _, let trail) = resolved.subtitle else {
+    guard case .highlight(_, _, let trail, _) = resolved.subtitle else {
       Issue.record("Expected .highlight subtitle")
       return
     }
@@ -174,9 +174,9 @@ struct ResolvedRowDisplayTests {
       isPinned: false,
       hideSubtitle: false,
       hideSubtitleOnMatch: true,
-      highlightSubtitle: SidebarHighlightRepoTag(repoName: "supacode", repoColor: nil)
+      highlightSubtitle: SidebarHighlightRepoTag(repoName: "supacode", repoColor: nil, hostInfo: nil)
     )
-    guard case .highlight(_, _, let trail) = resolved.subtitle else {
+    guard case .highlight(_, _, let trail, _) = resolved.subtitle else {
       Issue.record("Expected .highlight subtitle")
       return
     }
@@ -203,10 +203,10 @@ struct ResolvedRowDisplayTests {
       isPinned: true,
       hideSubtitle: false,
       hideSubtitleOnMatch: true,
-      highlightSubtitle: SidebarHighlightRepoTag(repoName: "supacode", repoColor: nil)
+      highlightSubtitle: SidebarHighlightRepoTag(repoName: "supacode", repoColor: nil, hostInfo: nil)
     )
     #expect(plain.subtitle == .none)
-    if case .highlight(_, _, let trail) = highlight.subtitle {
+    if case .highlight(_, _, let trail, _) = highlight.subtitle {
       #expect(trail == nil)
     } else {
       Issue.record("Expected .highlight subtitle for the hoisted path")
diff --git a/supacodeTests/SelectedWorktreeSliceCacheTests.swift b/supacodeTests/SelectedWorktreeSliceCacheTests.swift
index 62eaf4bd1..46a1436c5 100644
--- a/supacodeTests/SelectedWorktreeSliceCacheTests.swift
+++ b/supacodeTests/SelectedWorktreeSliceCacheTests.swift
@@ -106,7 +106,7 @@ struct SelectedWorktreeSliceCacheTests {
 
   private func makeWorktree(id: String, repoRoot: String) -> Worktree {
     Worktree(
-      id: id,
+      id: WorktreeID(id),
       name: "wt",
       detail: "detail",
       workingDirectory: URL(fileURLWithPath: id),
@@ -116,7 +116,7 @@ struct SelectedWorktreeSliceCacheTests {
 
   private func makeRepository(id: String, worktrees: [Worktree]) -> Repository {
     Repository(
-      id: id,
+      id: RepositoryID(id),
       rootURL: URL(fileURLWithPath: id),
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: worktrees)
diff --git a/supacodeTests/SettingsFeatureTests.swift b/supacodeTests/SettingsFeatureTests.swift
index b1c21489c..3cc13c1b3 100644
--- a/supacodeTests/SettingsFeatureTests.swift
+++ b/supacodeTests/SettingsFeatureTests.swift
@@ -134,6 +134,48 @@ struct SettingsFeatureTests {
     #expect(settingsFile.global.systemNotificationsEnabled == true)
   }
 
+  @Test(.dependencies) func settingsPersistDoesNotTouchRemoteRepositoryRoots() async {
+    let remote = TestRemoteRepo(host: RemoteHost(alias: "devbox"), remotePath: "/home/me/proj")
+    @Shared(.settingsFile) var settingsFile
+    $settingsFile.withLock { $0.remoteRepositoryRoots = [remote.id.rawValue] }
+
+    let store = TestStore(initialState: SettingsFeature.State()) {
+      SettingsFeature()
+    }
+
+    await store.send(.binding(.set(\.appearanceMode, .light))) {
+      $0.appearanceMode = .light
+    }
+    await store.receive(\.delegate.settingsChanged)
+
+    #expect(settingsFile.global.appearanceMode == .light)
+    #expect(settingsFile.remoteRepositoryRoots == [remote.id.rawValue])
+  }
+
+  @Test(.dependencies) func settingsLoadedNormalizationDoesNotTouchRemoteRepositoryRoots() async {
+    let remote = TestRemoteRepo(host: RemoteHost(alias: "devbox"), remotePath: "/home/me/proj")
+    @Shared(.settingsFile) var settingsFile
+    $settingsFile.withLock { $0.remoteRepositoryRoots = [remote.id.rawValue] }
+
+    var loaded = GlobalSettings.default
+    loaded.defaultWorktreeBaseDirectoryPath = " ~/worktrees "
+    let expectedPath = FileManager.default.homeDirectoryForCurrentUser
+      .appending(path: "worktrees", directoryHint: .isDirectory)
+      .standardizedFileURL
+      .path(percentEncoded: false)
+    let store = TestStore(initialState: SettingsFeature.State()) {
+      SettingsFeature()
+    }
+
+    await store.send(.settingsLoaded(loaded)) {
+      $0.defaultWorktreeBaseDirectoryPath = expectedPath
+    }
+    await store.receive(\.delegate.settingsChanged)
+
+    #expect(settingsFile.global.defaultWorktreeBaseDirectoryPath == expectedPath)
+    #expect(settingsFile.remoteRepositoryRoots == [remote.id.rawValue])
+  }
+
   @Test(.dependencies) func selectionBuildsRepositorySettingsFromRepositorySummary() async {
     let summary = SettingsRepositorySummary(id: "/tmp/repo", name: "Repo")
     let store = TestStore(initialState: SettingsFeature.State()) {
diff --git a/supacodeTests/ShellClientLoginShellTests.swift b/supacodeTests/ShellClientLoginShellTests.swift
new file mode 100644
index 000000000..2e0779cb2
--- /dev/null
+++ b/supacodeTests/ShellClientLoginShellTests.swift
@@ -0,0 +1,80 @@
+import Foundation
+import Testing
+
+@testable import SupacodeSettingsShared
+
+struct ShellClientLoginShellTests {
+  @Test func supportedShellsRunAsThemselves() {
+    for path in ["/bin/zsh", "/bin/bash", "/opt/homebrew/bin/fish"] {
+      let result = ShellClient.loginShellInvocation(userShell: URL(fileURLWithPath: path))
+      #expect(result.shell.path == path)
+    }
+  }
+
+  @Test func fishKeepsItsOwnSnippet() {
+    let result = ShellClient.loginShellInvocation(userShell: URL(fileURLWithPath: "/opt/homebrew/bin/fish"))
+    #expect(result.shell.lastPathComponent == "fish")
+    #expect(result.command.contains("exec $argv"))
+    // fish scopes argv across source, so it must NOT get the zsh/bash capture (which isn't valid fish).
+    #expect(!result.command.contains("__supacode_login_argv"))
+  }
+
+  @Test func bashSourcesBashrc() {
+    let result = ShellClient.loginShellInvocation(userShell: URL(fileURLWithPath: "/bin/bash"))
+    #expect(result.command.contains("~/.bashrc"))
+    #expect(result.command.contains("exec \"${__supacode_login_argv[@]}\""))
+  }
+
+  /// Regression for #100: any shell we don't have a correct rc snippet for must
+  /// fall back to /bin/zsh, which can parse it — instead of stranding the user
+  /// with a bogus "not a git repository". Includes sh/dash/ksh, since sourcing
+  /// `~/.zshrc` under them is a parse error (the original review catch).
+  @Test func unsupportedShellsFallBackToZsh() {
+    let shells = [
+      "/run/current-system/sw/bin/nu", "/usr/bin/pwsh", "/opt/elvish", "/usr/bin/xonsh", "/bin/csh",
+      "/bin/sh", "/usr/local/bin/dash", "/usr/bin/ksh",
+    ]
+    for path in shells {
+      let result = ShellClient.loginShellInvocation(userShell: URL(fileURLWithPath: path))
+      #expect(result.shell.path == "/bin/zsh")
+      #expect(result.command.contains("exec \"${__supacode_login_argv[@]}\""))
+    }
+  }
+
+  /// Regression for #441: the zsh/bash snippet must capture the positional parameters into the
+  /// saved array BEFORE sourcing the rc file. Sourcing shares `$@` with the caller, so an rc that
+  /// runs `set --` would otherwise wipe the command (`/usr/bin/which gh`) before `exec`.
+  @Test func zshAndBashCaptureArgsBeforeSourcingRc() {
+    for path in ["/bin/zsh", "/bin/bash"] {
+      let command = ShellClient.loginShellInvocation(userShell: URL(fileURLWithPath: path)).command
+      guard let captureRange = command.range(of: "__supacode_login_argv=(\"$@\")"),
+        let sourceRange = command.range(of: "~/.")
+      else {
+        Issue.record("\(path) snippet missing capture or source: \(command)")
+        continue
+      }
+      #expect(captureRange.lowerBound < sourceRange.lowerBound)
+      #expect(command.contains("exec \"${__supacode_login_argv[@]}\""))
+    }
+  }
+
+  /// Regression for #477: after capturing the positional parameters, the zsh/bash snippet must clear
+  /// them (`set --`) BEFORE sourcing the rc file. The positionals otherwise leak into the rc, so a
+  /// dual-mode script dispatching on `$1` (e.g. `fzf-git.sh`) sees the probe's `/usr/bin/which gh`,
+  /// hits its own `exit`, and kills the probe shell before `gh` is ever resolved.
+  @Test func zshAndBashClearPositionalsBeforeSourcingRc() {
+    for path in ["/bin/zsh", "/bin/bash"] {
+      let command = ShellClient.loginShellInvocation(userShell: URL(fileURLWithPath: path)).command
+      guard let captureRange = command.range(of: "__supacode_login_argv=(\"$@\")"),
+        let clearRange = command.range(of: "set --"),
+        let sourceRange = command.range(of: "~/.")
+      else {
+        Issue.record("\(path) snippet missing capture, clear, or source: \(command)")
+        continue
+      }
+      #expect(captureRange.lowerBound < clearRange.lowerBound)
+      #expect(clearRange.lowerBound < sourceRange.lowerBound)
+      #expect(command.contains("exec \"${__supacode_login_argv[@]}\""))
+    }
+  }
+}
diff --git a/supacodeTests/SidebarBottomCardTests.swift b/supacodeTests/SidebarBottomCardTests.swift
index bc492304e..3f2c81c72 100644
--- a/supacodeTests/SidebarBottomCardTests.swift
+++ b/supacodeTests/SidebarBottomCardTests.swift
@@ -9,6 +9,7 @@ struct SidebarBottomCardTests {
   @Test func agentUpdatesWinOverEverything() {
     let resolved = SidebarBottomCardView.Slot.resolve(
       agentMode: .updatesAvailable([.claude]),
+      remoteRepositoriesBetaMode: .visible,
       terminalPersistenceMode: .visible,
       highlightMode: .visible,
       onboardingMode: .visible
@@ -19,6 +20,7 @@ struct SidebarBottomCardTests {
   @Test func agentPromptWinsOverEverything() {
     let resolved = SidebarBottomCardView.Slot.resolve(
       agentMode: .promptInstall,
+      remoteRepositoriesBetaMode: .visible,
       terminalPersistenceMode: .visible,
       highlightMode: .visible,
       onboardingMode: .visible
@@ -26,9 +28,21 @@ struct SidebarBottomCardTests {
     #expect(resolved == .agent(.promptInstall))
   }
 
+  @Test func remoteRepositoriesBetaWinsOverOlderOnboarding() {
+    let resolved = SidebarBottomCardView.Slot.resolve(
+      agentMode: .hidden,
+      remoteRepositoriesBetaMode: .visible,
+      terminalPersistenceMode: .visible,
+      highlightMode: .visible,
+      onboardingMode: .visible
+    )
+    #expect(resolved == .remoteRepositoriesBeta)
+  }
+
   @Test func terminalPersistenceWinsOverHighlightAndNested() {
     let resolved = SidebarBottomCardView.Slot.resolve(
       agentMode: .hidden,
+      remoteRepositoriesBetaMode: .hidden,
       terminalPersistenceMode: .visible,
       highlightMode: .visible,
       onboardingMode: .visible
@@ -39,6 +53,7 @@ struct SidebarBottomCardTests {
   @Test func highlightWinsOverNestedOnboarding() {
     let resolved = SidebarBottomCardView.Slot.resolve(
       agentMode: .hidden,
+      remoteRepositoriesBetaMode: .hidden,
       terminalPersistenceMode: .hidden,
       highlightMode: .visible,
       onboardingMode: .visible
@@ -49,6 +64,7 @@ struct SidebarBottomCardTests {
   @Test func nestedOnboardingShowsWhenHigherPriorityDismissed() {
     let resolved = SidebarBottomCardView.Slot.resolve(
       agentMode: .hidden,
+      remoteRepositoriesBetaMode: .hidden,
       terminalPersistenceMode: .hidden,
       highlightMode: .hidden,
       onboardingMode: .visible
@@ -59,6 +75,7 @@ struct SidebarBottomCardTests {
   @Test func noneWhenAllHidden() {
     let resolved = SidebarBottomCardView.Slot.resolve(
       agentMode: .hidden,
+      remoteRepositoriesBetaMode: .hidden,
       terminalPersistenceMode: .hidden,
       highlightMode: .hidden,
       onboardingMode: .hidden
@@ -72,6 +89,12 @@ struct SidebarBottomCardTests {
     )
   }
 
+  @Test func remoteRepositoriesBetaTransitionTokenIsStable() {
+    #expect(
+      SidebarBottomCardView.Slot.remoteRepositoriesBeta.transitionToken == "remoteRepositoriesBeta:visible"
+    )
+  }
+
   @Test func agentVariantStableAcrossSkillAgentOrder() {
     let lhs = SidebarBottomCardView.Slot.agent(.updatesAvailable([.claude, .codex])).transitionToken
     let rhs = SidebarBottomCardView.Slot.agent(.updatesAvailable([.codex, .claude])).transitionToken
diff --git a/supacodeTests/SidebarHighlightOrderingTests.swift b/supacodeTests/SidebarHighlightOrderingTests.swift
index ab59cc687..79ba67411 100644
--- a/supacodeTests/SidebarHighlightOrderingTests.swift
+++ b/supacodeTests/SidebarHighlightOrderingTests.swift
@@ -9,7 +9,7 @@ struct SidebarHighlightOrderingTests {
     branch: String,
     classification: SidebarActiveClassification? = nil
   ) -> SidebarHighlightOrdering.Candidate {
-    .init(id: id, branchName: branch, classification: classification)
+    .init(id: WorktreeID(id), branchName: branch, classification: classification)
   }
 
   @Test func activeDropsUnclassifiedRows() {
diff --git a/supacodeTests/SidebarItemFeatureTests.swift b/supacodeTests/SidebarItemFeatureTests.swift
index 32c7222a4..4d8e35da8 100644
--- a/supacodeTests/SidebarItemFeatureTests.swift
+++ b/supacodeTests/SidebarItemFeatureTests.swift
@@ -274,15 +274,10 @@ struct SidebarItemFeatureTests {
 
   // MARK: - UI-scalar guards.
 
-  @Test func shortcutHintAndDragSessionGuardsSkipNoOps() async {
+  @Test func dragSessionGuardSkipsNoOps() async {
     let store = TestStore(initialState: makeState(name: "feature")) {
       SidebarItemFeature()
     }
-    await store.send(.shortcutHintChanged("⌘1")) {
-      $0.shortcutHint = "⌘1"
-    }
-    // Same hint: no-op.
-    await store.send(.shortcutHintChanged("⌘1"))
     await store.send(.dragSessionChanged(isDragging: true)) {
       $0.isDragging = true
     }
@@ -294,7 +289,7 @@ struct SidebarItemFeatureTests {
 
   private func makeState(name: String) -> SidebarItemFeature.State {
     SidebarItemFeature.State(
-      id: "/tmp/repo/wt-\(name)",
+      id: SidebarItemID("/tmp/repo/wt-\(name)"),
       repositoryID: "/tmp/repo",
       kind: .gitWorktree,
       name: name,
diff --git a/supacodeTests/SidebarPersistenceMigratorTests.swift b/supacodeTests/SidebarPersistenceMigratorTests.swift
index 5c91c93e6..5bb528ac7 100644
--- a/supacodeTests/SidebarPersistenceMigratorTests.swift
+++ b/supacodeTests/SidebarPersistenceMigratorTests.swift
@@ -94,8 +94,8 @@ struct SidebarPersistenceMigratorTests {
       let data = try storage.load(SupacodePaths.sidebarURL)
       let migrated = try JSONDecoder().decode(SidebarState.self, from: data)
 
-      let repoA = "/tmp/repo-a"
-      let repoB = "/tmp/repo-b"
+      let repoA: Repository.ID = "/tmp/repo-a"
+      let repoB: Repository.ID = "/tmp/repo-b"
       // Sections preserve the legacy repo-order.
       #expect(Array(migrated.sections.keys) == [repoA, repoB])
       // repo-b is collapsed; repo-a is not.
@@ -160,10 +160,10 @@ struct SidebarPersistenceMigratorTests {
     // both sides — route the raw paths through
     // `RepositoryPathNormalizer.normalize(_:)` first so the test
     // pins the canonical-in/canonical-out contract end to end.
-    let worktreeID = RepositoryPathNormalizer.normalize("/tmp/outer/inner/wt-1")!
+    let worktreeID = WorktreeID(RepositoryPathNormalizer.normalize("/tmp/outer/inner/wt-1")!)
     let outer = RepositoryPathNormalizer.normalize(["/tmp/outer", "/tmp/outer/inner"])
     let reversed = RepositoryPathNormalizer.normalize(["/tmp/outer/inner", "/tmp/outer"])
-    let expected = RepositoryPathNormalizer.normalize("/tmp/outer/inner")!
+    let expected = RepositoryID(RepositoryPathNormalizer.normalize("/tmp/outer/inner")!)
     for roots in [outer, reversed] {
       let candidates = roots.map { (candidate: $0, owningRoot: $0) }
       let resolved = SidebarPersistenceMigrator.repositoryID(
@@ -179,7 +179,7 @@ struct SidebarPersistenceMigratorTests {
     // parent directory — the trailing-slash guard must reject
     // this match. Pre-normalise both sides to match the new
     // canonical-input contract of `repositoryID(...)`.
-    let worktreeID = RepositoryPathNormalizer.normalize("/tmp/repo/wt-1")!
+    let worktreeID = WorktreeID(RepositoryPathNormalizer.normalize("/tmp/repo/wt-1")!)
     let roots = RepositoryPathNormalizer.normalize(["/tmp/rep"])
     let candidates = roots.map { (candidate: $0, owningRoot: $0) }
     let resolved = SidebarPersistenceMigrator.repositoryID(
@@ -199,14 +199,14 @@ struct SidebarPersistenceMigratorTests {
     // `owningRoot` as-is once a candidate matches — live callers
     // always pass the canonical `Repository.ID` there, so echoing
     // it unchanged keeps downstream section-key lookups honest.
-    let worktreeID = RepositoryPathNormalizer.normalize("/tmp/repo-a/wt-1")!
+    let worktreeID = WorktreeID(RepositoryPathNormalizer.normalize("/tmp/repo-a/wt-1")!)
     let roots = RepositoryPathNormalizer.normalize(["/tmp/repo-a/"])
     let candidates = roots.map { (candidate: $0, owningRoot: $0) }
     let resolved = SidebarPersistenceMigrator.repositoryID(
       owningWorktreeID: worktreeID,
       amongLegacyRoots: candidates
     )
-    #expect(resolved == roots.first)
+    #expect(resolved == roots.first.map(RepositoryID.init))
   }
 
   @Test func normalizerRejectsEmptyAndWhitespaceAndCollapsesDotComponents() {
@@ -582,15 +582,15 @@ struct SidebarPersistenceMigratorTests {
       // Section keyed on the canonical repo ID, and the pinned
       // worktree lives in that section's `.pinned` bucket under
       // its own canonical key.
-      #expect(Array(migrated.sections.keys) == [canonicalRoot])
-      let pinnedItems = migrated.sections[canonicalRoot]?.buckets[.pinned]?.items
-      #expect(pinnedItems?[canonicalWorktree] != nil)
+      #expect(Array(migrated.sections.keys) == [RepositoryID(canonicalRoot)])
+      let pinnedItems = migrated.sections[RepositoryID(canonicalRoot)]?.buckets[.pinned]?.items
+      #expect(pinnedItems?[WorktreeID(canonicalWorktree)] != nil)
       // Non-canonical spellings must NOT leak into the migrated
       // state — otherwise string comparisons against live
       // `Repository.ID` / `Worktree.ID` would drift depending on
       // which code path inserted the row.
-      #expect(migrated.sections[nonCanonicalRoot] == nil)
-      #expect(pinnedItems?[nonCanonicalWorktree] == nil)
+      #expect(migrated.sections[RepositoryID(nonCanonicalRoot)] == nil)
+      #expect(pinnedItems?[WorktreeID(nonCanonicalWorktree)] == nil)
     }
   }
 
@@ -603,9 +603,9 @@ struct SidebarPersistenceMigratorTests {
     // owning root so prefix-matching places the pin correctly.
     let storage = InMemorySettingsFileStorage()
     let rootURL = URL(fileURLWithPath: "/Developer/X/foo", isDirectory: true)
-    let owningRootID = RepositoryPathNormalizer.normalize(
-      rootURL.path(percentEncoded: false)
-    )!
+    let owningRootID = RepositoryID(
+      RepositoryPathNormalizer.normalize(rootURL.path(percentEncoded: false))!
+    )
     // Pin lives under the default convention base — derive the
     // exact path from `SupacodePaths` so the expectation matches
     // whatever `worktreeBaseDirectory(...)` produces at runtime.
@@ -619,7 +619,7 @@ struct SidebarPersistenceMigratorTests {
       .appending(path: "sbertix", directoryHint: .isDirectory)
       .appending(path: "branch-a", directoryHint: .isDirectory)
       .path(percentEncoded: false)
-    let canonicalPinnedID = RepositoryPathNormalizer.normalize(pinnedPath)!
+    let canonicalPinnedID = WorktreeID(RepositoryPathNormalizer.normalize(pinnedPath)!)
 
     try withDependencies {
       $0.settingsFileStorage = SettingsFileStorage(
@@ -656,9 +656,9 @@ struct SidebarPersistenceMigratorTests {
     // root.
     let storage = InMemorySettingsFileStorage()
     let rootURL = URL(fileURLWithPath: "/Developer/X/foo", isDirectory: true)
-    let owningRootID = RepositoryPathNormalizer.normalize(
-      rootURL.path(percentEncoded: false)
-    )!
+    let owningRootID = RepositoryID(
+      RepositoryPathNormalizer.normalize(rootURL.path(percentEncoded: false))!
+    )
     let globalBase = "/tmp/shared-worktrees"
     let overrideBase = SupacodePaths.worktreeBaseDirectory(
       for: rootURL,
@@ -669,7 +669,7 @@ struct SidebarPersistenceMigratorTests {
       overrideBase
       .appending(path: "branch-a", directoryHint: .isDirectory)
       .path(percentEncoded: false)
-    let canonicalPinnedID = RepositoryPathNormalizer.normalize(pinnedPath)!
+    let canonicalPinnedID = WorktreeID(RepositoryPathNormalizer.normalize(pinnedPath)!)
 
     try withDependencies {
       $0.settingsFileStorage = SettingsFileStorage(
@@ -708,14 +708,14 @@ struct SidebarPersistenceMigratorTests {
     let storage = InMemorySettingsFileStorage()
     let localSettingsStorage = RepositoryLocalSettingsTestStorage()
     let rootURL = URL(fileURLWithPath: "/Developer/X/foo", isDirectory: true)
-    let owningRootID = RepositoryPathNormalizer.normalize(
-      rootURL.path(percentEncoded: false)
-    )!
+    let owningRootID = RepositoryID(
+      RepositoryPathNormalizer.normalize(rootURL.path(percentEncoded: false))!
+    )
     let overrideBase = "/Volumes/External/worktrees"
     let pinnedPath = URL(fileURLWithPath: overrideBase, isDirectory: true)
       .appending(path: "branch-a", directoryHint: .isDirectory)
       .path(percentEncoded: false)
-    let canonicalPinnedID = RepositoryPathNormalizer.normalize(pinnedPath)!
+    let canonicalPinnedID = WorktreeID(RepositoryPathNormalizer.normalize(pinnedPath)!)
 
     // Seed the per-repo `supacode.json` via the injected storage
     // so the migrator's synchronous load succeeds.
@@ -762,9 +762,9 @@ struct SidebarPersistenceMigratorTests {
     // `.archived` on the settings root it belongs to.
     let storage = InMemorySettingsFileStorage()
     let rootURL = URL(fileURLWithPath: "/Developer/X/foo", isDirectory: true)
-    let owningRootID = RepositoryPathNormalizer.normalize(
-      rootURL.path(percentEncoded: false)
-    )!
+    let owningRootID = RepositoryID(
+      RepositoryPathNormalizer.normalize(rootURL.path(percentEncoded: false))!
+    )
     let conventionBase = SupacodePaths.worktreeBaseDirectory(
       for: rootURL,
       globalDefaultPath: nil,
@@ -775,7 +775,7 @@ struct SidebarPersistenceMigratorTests {
       .appending(path: "sbertix", directoryHint: .isDirectory)
       .appending(path: "branch-a", directoryHint: .isDirectory)
       .path(percentEncoded: false)
-    let canonicalArchivedID = RepositoryPathNormalizer.normalize(archivedPath)!
+    let canonicalArchivedID = WorktreeID(RepositoryPathNormalizer.normalize(archivedPath)!)
     let archivedAt = Date(timeIntervalSince1970: 1_000_000)
 
     try withDependencies {
@@ -830,4 +830,263 @@ struct SidebarPersistenceMigratorTests {
       #expect(migrated.focusedWorktreeID == nil)
     }
   }
+
+  // MARK: - Remote-identity migration (schema v1 -> v2).
+
+  @Test func stripLegacyIDPrefixesRemovesFolderAndRemoteMarkers() {
+    #expect(SidebarPersistenceMigrator.stripLegacyIDPrefixes("/tmp/repo") == "/tmp/repo")
+    #expect(SidebarPersistenceMigrator.stripLegacyIDPrefixes("remote://me@box/srv") == "me@box/srv")
+    #expect(SidebarPersistenceMigrator.stripLegacyIDPrefixes("folder:/tmp/notes") == "/tmp/notes")
+    // A folder-remote id collapses both retired markers in one pass.
+    #expect(SidebarPersistenceMigrator.stripLegacyIDPrefixes("folder:remote://box/srv") == "box/srv")
+  }
+
+  @Test(.dependencies) func remoteIdentityMigrationDrainsLegacyConfigsAndRekeysIds() throws {
+    let storage = InMemorySettingsFileStorage()
+    // A schema-v1 sidebar carrying the retired prefixes: a remote git section and
+    // a local folder row, plus a remote-keyed focus.
+    var legacySidebar = SidebarState()
+    legacySidebar.schemaVersion = 1
+    legacySidebar.sections[RepositoryID("remote://me@box/srv/repo")] = SidebarState.Section(
+      buckets: [.pinned: SidebarState.Bucket(items: [WorktreeID("remote://me@box/srv/repo"): .init()])]
+    )
+    legacySidebar.sections[RepositoryID("/tmp/notes")] = SidebarState.Section(
+      buckets: [.unpinned: SidebarState.Bucket(items: [WorktreeID("folder:/tmp/notes"): .init()])]
+    )
+    legacySidebar.focusedWorktreeID = WorktreeID("folder:/tmp/notes")
+    try storage.save(JSONEncoder().encode(legacySidebar), SupacodePaths.sidebarURL)
+
+    // Raw legacy settings.json with the retired `global.remoteRepositories`. Fed to
+    // the drain via `readFile` so a later settings save can't erase it mid-test.
+    let legacySettings = Data(
+      #"{"global":{"remoteRepositories":[{"host":{"alias":"box","username":"me"},"remotePath":"/srv/repo/"}]}}"#.utf8
+    )
+
+    try withDependencies {
+      $0.settingsFileStorage = SettingsFileStorage(
+        load: { try storage.load($0) },
+        save: { try storage.save($0, $1) }
+      )
+      $0.defaultAppStorage = .inMemory
+      $0.date = .constant(Date(timeIntervalSince1970: 1_700_000_000))
+    } operation: {
+      @Shared(.settingsFile) var settingsFile
+      $settingsFile.withLock {
+        $0.repositories = ["remote://me@box/srv/repo": .default]
+        $0.pinnedWorktreeIDs = ["remote://me@box/srv/repo"]
+      }
+      let readFile: (URL) -> Data? = { url in
+        url == SupacodePaths.settingsURL ? legacySettings : (try? storage.load(url))
+      }
+      let fileExists: (URL) -> Bool = { (try? storage.load($0)) != nil }
+
+      let captured = SidebarPersistenceMigrator.captureLegacyRemoteRoots(
+        fileExists: fileExists, readFile: readFile)
+      SidebarPersistenceMigrator.migrateRemoteIdentityIfNeeded(
+        capturedLegacy: captured, fileExists: fileExists, readFile: readFile)
+
+      // Legacy config drained into remoteRepositoryRoots (trailing slash normalized).
+      @Shared(.remoteRepositoryRoots) var remoteRepositoryRoots
+      #expect(remoteRepositoryRoots == ["me@box/srv/repo"])
+      // Per-repo settings + pins re-keyed off the retired prefixes.
+      #expect(settingsFile.repositories["me@box/srv/repo"] != nil)
+      #expect(settingsFile.repositories["remote://me@box/srv/repo"] == nil)
+      #expect(settingsFile.pinnedWorktreeIDs == ["me@box/srv/repo"])
+
+      // sidebar.json re-keyed and stamped v2.
+      let migrated = try JSONDecoder().decode(SidebarState.self, from: storage.load(SupacodePaths.sidebarURL))
+      #expect(migrated.schemaVersion == 2)
+      #expect(migrated.sections[RepositoryID("me@box/srv/repo")] != nil)
+      #expect(migrated.sections[RepositoryID("remote://me@box/srv/repo")] == nil)
+      #expect(
+        migrated.sections[RepositoryID("me@box/srv/repo")]?.buckets[.pinned]?
+          .items[WorktreeID("me@box/srv/repo")] != nil)
+      #expect(
+        migrated.sections[RepositoryID("/tmp/notes")]?.buckets[.unpinned]?
+          .items[WorktreeID("/tmp/notes")] != nil)
+      #expect(migrated.focusedWorktreeID == WorktreeID("/tmp/notes"))
+
+      // Idempotent: a second pass is a no-op (the v2 gate short-circuits).
+      let captured2 = SidebarPersistenceMigrator.captureLegacyRemoteRoots(
+        fileExists: fileExists, readFile: readFile)
+      SidebarPersistenceMigrator.migrateRemoteIdentityIfNeeded(
+        capturedLegacy: captured2, fileExists: fileExists, readFile: readFile)
+      #expect(remoteRepositoryRoots == ["me@box/srv/repo"])
+      let again = try JSONDecoder().decode(SidebarState.self, from: storage.load(SupacodePaths.sidebarURL))
+      #expect(again.schemaVersion == 2)
+      #expect(again.sections.count == 2)
+    }
+  }
+
+  @Test(.dependencies) func remoteIdentityMigrationBailsWhenSidebarPresentButUnreadable() throws {
+    let storage = InMemorySettingsFileStorage()
+    var existing = SidebarState()
+    existing.schemaVersion = 1
+    existing.sections["/tmp/repo"] = SidebarState.Section(
+      buckets: [.pinned: SidebarState.Bucket(items: ["/tmp/repo/wt": .init()])]
+    )
+    let existingBytes = try JSONEncoder().encode(existing)
+    try storage.save(existingBytes, SupacodePaths.sidebarURL)
+
+    try withDependencies {
+      $0.settingsFileStorage = SettingsFileStorage(load: { try storage.load($0) }, save: { try storage.save($0, $1) })
+      $0.defaultAppStorage = .inMemory
+      $0.date = .constant(Date(timeIntervalSince1970: 1_700_000_000))
+    } operation: {
+      // Present (fileExists true) but unreadable (readFile nil): must NOT overwrite
+      // the layout with empty state, and must NOT stamp v2 (so it retries).
+      SidebarPersistenceMigrator.migrateRemoteIdentityIfNeeded(
+        capturedLegacy: .none, fileExists: { _ in true }, readFile: { _ in nil })
+      let after = try JSONDecoder().decode(SidebarState.self, from: storage.load(SupacodePaths.sidebarURL))
+      #expect(after.schemaVersion == 1)
+      #expect(after.sections["/tmp/repo"] != nil)
+    }
+  }
+
+  @Test(.dependencies) func remoteIdentityMigrationAbortsWhenSettingsUnreadable() throws {
+    let storage = InMemorySettingsFileStorage()
+    var existing = SidebarState()
+    existing.schemaVersion = 1
+    try storage.save(try JSONEncoder().encode(existing), SupacodePaths.sidebarURL)
+
+    try withDependencies {
+      $0.settingsFileStorage = SettingsFileStorage(load: { try storage.load($0) }, save: { try storage.save($0, $1) })
+      $0.defaultAppStorage = .inMemory
+      $0.date = .constant(Date(timeIntervalSince1970: 1_700_000_000))
+    } operation: {
+      // settings.json present but unreadable -> capture is `.unreadable`; the pass
+      // must abort without stamping v2 so the legacy field survives to next launch.
+      let captured = SidebarPersistenceMigrator.captureLegacyRemoteRoots(
+        fileExists: { _ in true }, readFile: { _ in nil })
+      #expect(captured == .unreadable)
+      SidebarPersistenceMigrator.migrateRemoteIdentityIfNeeded(
+        capturedLegacy: captured, fileExists: { _ in true }, readFile: { try? storage.load($0) })
+      let after = try JSONDecoder().decode(SidebarState.self, from: storage.load(SupacodePaths.sidebarURL))
+      #expect(after.schemaVersion == 1)
+    }
+  }
+
+  @Test(.dependencies) func remoteIdentityMigrationKeepsFirstOnKeyCollision() throws {
+    let storage = InMemorySettingsFileStorage()
+    // Both a retired `remote://X` section and a bare `X` section exist; after the
+    // prefix strip they collide and the first-seen entry must win (no trap, no dupe).
+    var legacy = SidebarState()
+    legacy.schemaVersion = 1
+    legacy.sections["remote://me@box/srv/repo"] = SidebarState.Section(
+      buckets: [.pinned: SidebarState.Bucket(items: ["remote://me@box/srv/repo": .init(title: "first")])]
+    )
+    legacy.sections["me@box/srv/repo"] = SidebarState.Section(
+      buckets: [.unpinned: SidebarState.Bucket(items: ["me@box/srv/repo": .init(title: "second")])]
+    )
+    try storage.save(try JSONEncoder().encode(legacy), SupacodePaths.sidebarURL)
+
+    try withDependencies {
+      $0.settingsFileStorage = SettingsFileStorage(load: { try storage.load($0) }, save: { try storage.save($0, $1) })
+      $0.defaultAppStorage = .inMemory
+      $0.date = .constant(Date(timeIntervalSince1970: 1_700_000_000))
+    } operation: {
+      SidebarPersistenceMigrator.migrateRemoteIdentityIfNeeded(
+        capturedLegacy: .none, fileExists: { (try? storage.load($0)) != nil }, readFile: { try? storage.load($0) })
+      let migrated = try JSONDecoder().decode(SidebarState.self, from: storage.load(SupacodePaths.sidebarURL))
+      #expect(migrated.sections.count == 1)
+      #expect(migrated.sections["me@box/srv/repo"]?.buckets[.pinned]?.items["me@box/srv/repo"]?.title == "first")
+    }
+  }
+
+  @Test(.dependencies) func remoteIdentityMigrationRekeysTerminalLayouts() throws {
+    let storage = InMemorySettingsFileStorage()
+    var sidebar = SidebarState()
+    sidebar.schemaVersion = 1
+    try storage.save(try JSONEncoder().encode(sidebar), SupacodePaths.sidebarURL)
+    // Terminal layouts keyed by the retired worktree-id prefixes must follow the
+    // ids, or remote/folder tabs won't restore after upgrade.
+    let snapshot = TerminalLayoutSnapshot(tabs: [], selectedTabIndex: 0)
+    let layouts: [String: TerminalLayoutSnapshot] = [
+      "remote://me@box/srv/repo": snapshot,
+      "folder:/tmp/notes": snapshot,
+      "/tmp/local/wt": snapshot,
+    ]
+    try storage.save(try JSONEncoder().encode(layouts), SupacodePaths.layoutsURL)
+
+    try withDependencies {
+      $0.settingsFileStorage = SettingsFileStorage(load: { try storage.load($0) }, save: { try storage.save($0, $1) })
+      $0.defaultAppStorage = .inMemory
+      $0.date = .constant(Date(timeIntervalSince1970: 1_700_000_000))
+    } operation: {
+      SidebarPersistenceMigrator.migrateRemoteIdentityIfNeeded(
+        capturedLegacy: .none, fileExists: { (try? storage.load($0)) != nil }, readFile: { try? storage.load($0) })
+      let migrated = try JSONDecoder().decode(
+        [String: TerminalLayoutSnapshot].self, from: storage.load(SupacodePaths.layoutsURL))
+      #expect(migrated["me@box/srv/repo"] != nil)
+      #expect(migrated["/tmp/notes"] != nil)
+      #expect(migrated["/tmp/local/wt"] != nil)
+      #expect(migrated["remote://me@box/srv/repo"] == nil)
+      #expect(migrated["folder:/tmp/notes"] == nil)
+    }
+  }
+
+  @Test(.dependencies) func backupSnapshotsSettingsAndSidebarBeforeMigrating() throws {
+    let storage = InMemorySettingsFileStorage()
+    let settingsData = Data(#"{"global":{"remoteRepositories":[]},"repositoryRoots":["/tmp/repo"]}"#.utf8)
+    try storage.save(settingsData, SupacodePaths.settingsURL)
+    var sidebar = SidebarState()
+    sidebar.schemaVersion = 1
+    let sidebarData = try JSONEncoder().encode(sidebar)
+    try storage.save(sidebarData, SupacodePaths.sidebarURL)
+
+    withDependencies {
+      $0.settingsFileStorage = SettingsFileStorage(load: { try storage.load($0) }, save: { try storage.save($0, $1) })
+      $0.defaultAppStorage = .inMemory
+    } operation: {
+      SidebarPersistenceMigrator.backupBeforeRemoteIdentityMigration(
+        fileExists: { (try? storage.load($0)) != nil }, readFile: { try? storage.load($0) })
+      let suffix = SidebarPersistenceMigrator.preMigrationBackupSuffix
+      let settingsBak = SupacodePaths.settingsURL.deletingLastPathComponent()
+        .appendingPathComponent(SupacodePaths.settingsURL.lastPathComponent + suffix)
+      let sidebarBak = SupacodePaths.sidebarURL.deletingLastPathComponent()
+        .appendingPathComponent(SupacodePaths.sidebarURL.lastPathComponent + suffix)
+      #expect((try? storage.load(settingsBak)) == settingsData)
+      #expect((try? storage.load(sidebarBak)) == sidebarData)
+    }
+  }
+
+  @Test(.dependencies) func backupSkipsOnceMigrated() throws {
+    let storage = InMemorySettingsFileStorage()
+    try storage.save(Data("{}".utf8), SupacodePaths.settingsURL)
+    var sidebar = SidebarState()
+    sidebar.schemaVersion = 2
+    try storage.save(try JSONEncoder().encode(sidebar), SupacodePaths.sidebarURL)
+
+    withDependencies {
+      $0.settingsFileStorage = SettingsFileStorage(load: { try storage.load($0) }, save: { try storage.save($0, $1) })
+      $0.defaultAppStorage = .inMemory
+    } operation: {
+      SidebarPersistenceMigrator.backupBeforeRemoteIdentityMigration(
+        fileExists: { (try? storage.load($0)) != nil }, readFile: { try? storage.load($0) })
+      let settingsBak = SupacodePaths.settingsURL.deletingLastPathComponent()
+        .appendingPathComponent(
+          SupacodePaths.settingsURL.lastPathComponent + SidebarPersistenceMigrator.preMigrationBackupSuffix)
+      #expect((try? storage.load(settingsBak)) == nil)
+    }
+  }
+
+  @Test(.dependencies) func remoteIdentityMigrationDrainsRemotesEvenWhenSidebarUnreadable() throws {
+    let storage = InMemorySettingsFileStorage()
+    // Sidebar present but unreadable: the re-key bails, but the captured remotes
+    // must still be drained to their new home, not discarded.
+    try storage.save(Data("not json".utf8), SupacodePaths.sidebarURL)
+
+    withDependencies {
+      $0.settingsFileStorage = SettingsFileStorage(load: { try storage.load($0) }, save: { try storage.save($0, $1) })
+      $0.defaultAppStorage = .inMemory
+      $0.date = .constant(Date(timeIntervalSince1970: 1_700_000_000))
+    } operation: {
+      SidebarPersistenceMigrator.migrateRemoteIdentityIfNeeded(
+        capturedLegacy: .roots(["me@box/srv/repo"]),
+        fileExists: { (try? storage.load($0)) != nil },
+        readFile: { try? storage.load($0) })
+      @Shared(.remoteRepositoryRoots) var remoteRepositoryRoots
+      #expect(remoteRepositoryRoots == ["me@box/srv/repo"])
+    }
+  }
 }
diff --git a/supacodeTests/SidebarStateTests.swift b/supacodeTests/SidebarStateTests.swift
index 9c471d249..39ff2dfe2 100644
--- a/supacodeTests/SidebarStateTests.swift
+++ b/supacodeTests/SidebarStateTests.swift
@@ -7,8 +7,8 @@ import Testing
 
 @MainActor
 struct SidebarStateTests {
-  private let repoA = "/tmp/repo-a"
-  private let repoB = "/tmp/repo-b"
+  private let repoA: Repository.ID = "/tmp/repo-a"
+  private let repoB: Repository.ID = "/tmp/repo-b"
 
   // MARK: - move
 
@@ -388,4 +388,195 @@ struct SidebarStateTests {
     #expect(decoded.collapsedBranchPrefixes.isEmpty)
     #expect(decoded.items.isEmpty)
   }
+
+  // MARK: - Item Codable round-trip.
+
+  @Test func itemRoundTripPreservesTitleAndColor() throws {
+    let archivedAt = Date(timeIntervalSinceReferenceDate: 1_700_000_000)
+    let original = SidebarState.Item(archivedAt: archivedAt, title: "Spicy", color: .custom("#0A1B2C"))
+
+    let encoded = try JSONEncoder().encode(original)
+    let decoded = try JSONDecoder().decode(SidebarState.Item.self, from: encoded)
+
+    #expect(decoded.archivedAt == archivedAt)
+    #expect(decoded.title == "Spicy")
+    #expect(decoded.color == .custom("#0A1B2C"))
+  }
+
+  @Test func itemDecodingDropsMalformedHexColorWithoutKillingRow() throws {
+    // Forward-compat: a hex value introduced by a downgrade-corrupted file (or hand-edit) must
+    // drop just the color, never crash the row decode.
+    let malformedJSON = """
+      { "title": "Renamed", "color": "not-a-hex" }
+      """
+    let data = Data(malformedJSON.utf8)
+    let decoded = try JSONDecoder().decode(SidebarState.Item.self, from: data)
+    #expect(decoded.title == "Renamed")
+    #expect(decoded.color == nil)
+  }
+
+  // MARK: - Archive / unarchive customization carry.
+
+  @Test func archiveCarriesTitleAndColorFromSourceBucket() {
+    var state = SidebarState()
+    state.insert(
+      worktree: "wt-1",
+      in: "repo",
+      bucket: .pinned,
+      item: .init(title: "Spicy", color: .red)
+    )
+
+    state.archive(worktree: "wt-1", in: "repo", from: .pinned, at: Date(timeIntervalSince1970: 1_000))
+
+    let archived = state.sections["repo"]?.buckets[.archived]?.items["wt-1"]
+    #expect(archived?.title == "Spicy")
+    #expect(archived?.color == .red)
+    #expect(archived?.archivedAt == Date(timeIntervalSince1970: 1_000))
+  }
+
+  @Test func unarchiveCarriesTitleAndColorBackAndClearsArchivedAt() {
+    var state = SidebarState()
+    state.insert(
+      worktree: "wt-1",
+      in: "repo",
+      bucket: .archived,
+      item: .init(archivedAt: Date(timeIntervalSince1970: 1_000), title: "Spicy", color: .red)
+    )
+
+    state.unarchive(worktree: "wt-1", in: "repo")
+
+    let unpinned = state.sections["repo"]?.buckets[.unpinned]?.items["wt-1"]
+    #expect(unpinned?.title == "Spicy")
+    #expect(unpinned?.color == .red)
+    #expect(unpinned?.archivedAt == nil)
+    #expect(state.sections["repo"]?.buckets[.archived]?.items["wt-1"] == nil)
+  }
+
+  // MARK: - mergeCustomization invariants.
+
+  @Test func mergeCustomizationLandsInExistingBucketWhenRowAlreadySeeded() {
+    var state = SidebarState()
+    state.insert(worktree: "wt-1", in: "repo", bucket: .pinned)
+
+    state.mergeCustomization(title: "Spicy", color: .red, worktree: "wt-1", in: "repo")
+
+    #expect(state.sections["repo"]?.buckets[.pinned]?.items["wt-1"]?.title == "Spicy")
+    #expect(state.sections["repo"]?.buckets[.pinned]?.items["wt-1"]?.color == .red)
+    #expect(state.sections["repo"]?.buckets[.unpinned]?.items["wt-1"] == nil)
+  }
+
+  @Test func mergeCustomizationFallsBackToUnpinnedWhenRowMissing() {
+    var state = SidebarState()
+
+    state.mergeCustomization(title: "Spicy", color: .red, worktree: "wt-1", in: "repo")
+
+    #expect(state.sections["repo"]?.buckets[.unpinned]?.items["wt-1"]?.title == "Spicy")
+    #expect(state.sections["repo"]?.buckets[.unpinned]?.items["wt-1"]?.color == .red)
+  }
+
+  @Test func mergeCustomizationPreservesPreExistingNonNilFields() {
+    var state = SidebarState()
+    state.insert(
+      worktree: "wt-1",
+      in: "repo",
+      bucket: .pinned,
+      item: .init(title: "Manual", color: .blue)
+    )
+
+    state.mergeCustomization(title: "Stale", color: .red, worktree: "wt-1", in: "repo")
+
+    // Manual customization wins against the re-seed payload.
+    #expect(state.sections["repo"]?.buckets[.pinned]?.items["wt-1"]?.title == "Manual")
+    #expect(state.sections["repo"]?.buckets[.pinned]?.items["wt-1"]?.color == .blue)
+  }
+
+  // MARK: - setCustomization (save-intent overwrite).
+
+  @Test func setCustomizationOverwritesPreExistingFields() {
+    var state = SidebarState()
+    state.insert(
+      worktree: "wt-1",
+      in: "repo",
+      bucket: .pinned,
+      item: .init(title: "Old", color: .blue)
+    )
+
+    state.setCustomization(title: "New", color: .red, worktree: "wt-1", in: "repo")
+
+    let item = state.sections["repo"]?.buckets[.pinned]?.items["wt-1"]
+    #expect(item?.title == "New")
+    #expect(item?.color == .red)
+  }
+
+  @Test func setCustomizationClearsFieldsWhenPassedNil() {
+    var state = SidebarState()
+    state.insert(
+      worktree: "wt-1",
+      in: "repo",
+      bucket: .pinned,
+      item: .init(title: "Spicy", color: .red)
+    )
+
+    state.setCustomization(title: nil, color: nil, worktree: "wt-1", in: "repo")
+
+    let item = state.sections["repo"]?.buckets[.pinned]?.items["wt-1"]
+    #expect(item?.title == nil)
+    #expect(item?.color == nil)
+  }
+
+  @Test func setCustomizationFallsBackToUnpinnedWhenRowMissing() {
+    var state = SidebarState()
+
+    state.setCustomization(title: "Spicy", color: .red, worktree: "wt-1", in: "repo")
+
+    let item = state.sections["repo"]?.buckets[.unpinned]?.items["wt-1"]
+    #expect(item?.title == "Spicy")
+    #expect(item?.color == .red)
+  }
+
+  // MARK: - removeAnywhere(preferring:) ordering.
+
+  @Test func removeAnywhereHonorsPreferringOrderWhenRowExistsInMultipleBuckets() {
+    var state = SidebarState()
+    state.insert(
+      worktree: "wt-1",
+      in: "repo",
+      bucket: .pinned,
+      item: .init(title: "Pinned-Payload", color: .red)
+    )
+    state.insert(
+      worktree: "wt-1",
+      in: "repo",
+      bucket: .unpinned,
+      item: .init(title: "Unpinned-Payload", color: .blue)
+    )
+
+    let carried = state.removeAnywhere(worktree: "wt-1", in: "repo", preferring: [.pinned, .unpinned])
+
+    #expect(carried?.title == "Pinned-Payload")
+    #expect(carried?.color == .red)
+    #expect(state.sections["repo"]?.buckets[.pinned]?.items["wt-1"] == nil)
+    #expect(state.sections["repo"]?.buckets[.unpinned]?.items["wt-1"] == nil)
+  }
+
+  @Test func removeAnywhereWithReversedPreferringPicksOppositeBucket() {
+    var state = SidebarState()
+    state.insert(
+      worktree: "wt-1",
+      in: "repo",
+      bucket: .pinned,
+      item: .init(title: "Pinned-Payload", color: .red)
+    )
+    state.insert(
+      worktree: "wt-1",
+      in: "repo",
+      bucket: .unpinned,
+      item: .init(title: "Unpinned-Payload", color: .blue)
+    )
+
+    let carried = state.removeAnywhere(worktree: "wt-1", in: "repo", preferring: [.unpinned, .pinned])
+
+    #expect(carried?.title == "Unpinned-Payload")
+    #expect(carried?.color == .blue)
+  }
 }
diff --git a/supacodeTests/SidebarStructureTests.swift b/supacodeTests/SidebarStructureTests.swift
index 28da77e46..6340dde14 100644
--- a/supacodeTests/SidebarStructureTests.swift
+++ b/supacodeTests/SidebarStructureTests.swift
@@ -20,7 +20,7 @@ struct SidebarStructureTests {
 
   private func makeWorktree(id: String, name: String, repoRoot: URL) -> Worktree {
     Worktree(
-      id: id,
+      id: WorktreeID(id),
       name: name,
       detail: "",
       workingDirectory: URL(fileURLWithPath: id),
@@ -30,7 +30,7 @@ struct SidebarStructureTests {
 
   private func makeMainWorktree(repoRoot: URL) -> Worktree {
     Worktree(
-      id: repoRoot.path(percentEncoded: false),
+      id: WorktreeID(repoRoot.path(percentEncoded: false)),
       name: "main",
       detail: "",
       workingDirectory: repoRoot,
@@ -68,7 +68,7 @@ struct SidebarStructureTests {
     let main = makeMainWorktree(repoRoot: repoRoot)
     let feature = makeWorktree(id: "/tmp/repo/wt", name: "feature", repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [main, feature])
@@ -91,7 +91,7 @@ struct SidebarStructureTests {
     let repoRoot = URL(fileURLWithPath: "/tmp/repo")
     let main = makeMainWorktree(repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [main])
@@ -124,7 +124,7 @@ struct SidebarStructureTests {
     let pinned = makeWorktree(id: "/tmp/repo/pinned", name: "pinned", repoRoot: repoRoot)
     let extra = makeWorktree(id: "/tmp/repo/extra", name: "extra", repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [main, pinned, extra])
@@ -157,7 +157,7 @@ struct SidebarStructureTests {
     let main = makeMainWorktree(repoRoot: repoRoot)
     let duplicate = makeWorktree(id: "/tmp/repo/dup", name: "duplicate", repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [main, duplicate])
@@ -193,7 +193,7 @@ struct SidebarStructureTests {
     let main = makeMainWorktree(repoRoot: repoRoot)
     let archived = makeWorktree(id: "/tmp/repo/arch", name: "arch", repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [main, archived])
@@ -243,7 +243,7 @@ struct SidebarStructureTests {
     let unpinX = makeWorktree(id: "/tmp/repo/x", name: "x-branch", repoRoot: repoRoot)
     let unpinB = makeWorktree(id: "/tmp/repo/b", name: "b-branch", repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [main, charlie, alpha, bravo, unpinB, unpinX])
@@ -265,7 +265,7 @@ struct SidebarStructureTests {
       sidebar.sections[repository.id] = section
     }
     for id in [alpha.id, bravo.id, charlie.id, unpinX.id, unpinB.id] {
-      let name = state.sidebarItems[id: id]?.name ?? id
+      let name = state.sidebarItems[id: id]?.name ?? id.rawValue
       state.sidebarItems[id: id]?.branchName = name
     }
     state.reconcileSidebarForTesting()
@@ -290,7 +290,7 @@ struct SidebarStructureTests {
     let charlie = makeWorktree(id: "/tmp/repo/charlie", name: "charlie", repoRoot: repoRoot)
     let alpha = makeWorktree(id: "/tmp/repo/alpha", name: "alpha", repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [main, charlie, alpha])
@@ -328,7 +328,7 @@ struct SidebarStructureTests {
     let alpha = makeWorktree(id: "/tmp/repo/alpha", name: "alpha", repoRoot: repoRoot)
     let bravo = makeWorktree(id: "/tmp/repo/bravo", name: "bravo", repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [main, charlie, alpha, bravo])
@@ -349,7 +349,7 @@ struct SidebarStructureTests {
       sidebar.sections[repository.id] = section
     }
     for id in [alpha.id, bravo.id, charlie.id] {
-      let name = state.sidebarItems[id: id]?.name ?? id
+      let name = state.sidebarItems[id: id]?.name ?? id.rawValue
       state.sidebarItems[id: id]?.branchName = name
     }
     state.$sidebarNestWorktreesByBranch.withLock { $0 = true }
@@ -377,7 +377,7 @@ struct SidebarStructureTests {
     let busy = makeWorktree(id: "/tmp/repo/busy", name: "busy", repoRoot: repoRoot)
     let idle = makeWorktree(id: "/tmp/repo/idle", name: "idle", repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [main, busy, idle])
@@ -412,7 +412,7 @@ struct SidebarStructureTests {
     let main = makeMainWorktree(repoRoot: repoRoot)
     let archived = makeWorktree(id: "/tmp/repo/archived", name: "archived", repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [main, archived])
@@ -438,21 +438,21 @@ struct SidebarStructureTests {
     let repoRoot = URL(fileURLWithPath: "/tmp/repo")
     let main = makeMainWorktree(repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [main])
     )
     var state = makeState(repositories: [repository])
     let failedRoot = URL(fileURLWithPath: "/tmp/broken")
-    let failedID = failedRoot.path(percentEncoded: false)
+    let failedID = RepositoryID(failedRoot.path(percentEncoded: false))
     state.repositoryRoots.append(failedRoot)
     state.loadFailuresByID[failedID] = "boom"
 
     let structure = state.computeSidebarStructure(groupPinned: false, groupActive: false)
 
     let failedIndex = structure.sections.firstIndex {
-      if case .failedRepository(let id, _, _, _) = $0 { return id == failedID }
+      if case .failedRepository(let id, _, _, _, _) = $0 { return id == failedID }
       return false
     }
     let repoIndex = structure.sections.firstIndex {
@@ -471,7 +471,7 @@ struct SidebarStructureTests {
     let main = makeMainWorktree(repoRoot: repoRoot)
     let busy = makeWorktree(id: "/tmp/repo/busy", name: "busy", repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "raw-folder-name",
       worktrees: IdentifiedArray(uniqueElements: [main, busy])
@@ -495,7 +495,7 @@ struct SidebarStructureTests {
     let main = makeMainWorktree(repoRoot: repoRoot)
     let busy = makeWorktree(id: "/tmp/repo/busy", name: "busy", repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "fallback-name",
       worktrees: IdentifiedArray(uniqueElements: [main, busy])
@@ -518,7 +518,7 @@ struct SidebarStructureTests {
     let main = makeMainWorktree(repoRoot: repoRoot)
     let archiving = makeWorktree(id: "/tmp/repo/archiving", name: "archiving", repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [main, archiving])
@@ -542,7 +542,7 @@ struct SidebarStructureTests {
     let main = makeMainWorktree(repoRoot: repoRoot)
     let deleting = makeWorktree(id: "/tmp/repo/deleting", name: "deleting", repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [main, deleting])
@@ -565,7 +565,7 @@ struct SidebarStructureTests {
     let main = makeMainWorktree(repoRoot: repoRoot)
     let pending = makeWorktree(id: "/tmp/repo/pending", name: "pending", repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [main, pending])
@@ -590,7 +590,7 @@ struct SidebarStructureTests {
     let main = makeMainWorktree(repoRoot: repoRoot)
     let other = makeWorktree(id: "/tmp/repo/other", name: "other", repoRoot: repoRoot)
     let repository = Repository(
-      id: repoRoot.path(percentEncoded: false),
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
       rootURL: repoRoot,
       name: "repo",
       worktrees: IdentifiedArray(uniqueElements: [main, other])
@@ -624,7 +624,7 @@ struct SidebarStructureTests {
     let folderURL = URL(fileURLWithPath: "/tmp/folder")
     let folderID = Repository.folderWorktreeID(for: folderURL)
     let folderRepo = Repository(
-      id: folderURL.path(percentEncoded: false),
+      id: RepositoryID(folderURL.path(percentEncoded: false)),
       rootURL: folderURL,
       name: "folder",
       worktrees: IdentifiedArray(
@@ -665,11 +665,245 @@ struct SidebarStructureTests {
     #expect(!hasFolderSection)
   }
 
+  // MARK: - Hoist summary.
+
+  @Test func hoistSummaryCountsPinnedAndActiveWithPinnedFirstTarget() {
+    let repoRoot = URL(fileURLWithPath: "/tmp/repo")
+    let main = makeMainWorktree(repoRoot: repoRoot)
+    let pinned = makeWorktree(id: "/tmp/repo/pinned", name: "pinned", repoRoot: repoRoot)
+    let busy = makeWorktree(id: "/tmp/repo/busy", name: "busy", repoRoot: repoRoot)
+    let repository = Repository(
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
+      rootURL: repoRoot,
+      name: "repo",
+      worktrees: IdentifiedArray(uniqueElements: [main, pinned, busy])
+    )
+    var state = makeState(repositories: [repository])
+    state.$sidebar.withLock { sidebar in
+      var section = sidebar.sections[repository.id] ?? .init()
+      var pinnedBucket = section.buckets[.pinned] ?? .init()
+      pinnedBucket.items[pinned.id] = .init()
+      section.buckets[.pinned] = pinnedBucket
+      sidebar.sections[repository.id] = section
+    }
+    state.sidebarItems[id: busy.id]?.runningScripts.append(.init(id: UUID(), tint: .blue))
+
+    let structure = state.computeSidebarStructure(groupPinned: true, groupActive: true)
+
+    let summary = structure.hoistSummaryByRepositoryID[repository.id]
+    #expect(summary?.pinnedCount == 1)
+    #expect(summary?.activeCount == 1)
+    // Pinned-first: the click target is the pinned hoist, not the active one.
+    #expect(summary?.revealTarget == pinned.id)
+    #expect(summary?.label == "+1 pinned, +1 active")
+  }
+
+  @Test func hoistSummaryFallsBackToActiveTargetWhenNoPinned() {
+    let repoRoot = URL(fileURLWithPath: "/tmp/repo")
+    let main = makeMainWorktree(repoRoot: repoRoot)
+    let busy = makeWorktree(id: "/tmp/repo/busy", name: "busy", repoRoot: repoRoot)
+    let repository = Repository(
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
+      rootURL: repoRoot,
+      name: "repo",
+      worktrees: IdentifiedArray(uniqueElements: [main, busy])
+    )
+    var state = makeState(repositories: [repository])
+    state.sidebarItems[id: busy.id]?.runningScripts.append(.init(id: UUID(), tint: .blue))
+
+    let structure = state.computeSidebarStructure(groupPinned: true, groupActive: true)
+
+    let summary = structure.hoistSummaryByRepositoryID[repository.id]
+    #expect(summary?.pinnedCount == 0)
+    #expect(summary?.activeCount == 1)
+    #expect(summary?.revealTarget == busy.id)
+    #expect(summary?.label == "+1 active")
+  }
+
+  @Test func hoistSummaryOmittedForRepoWithNoHoists() {
+    let repoRoot = URL(fileURLWithPath: "/tmp/repo")
+    let main = makeMainWorktree(repoRoot: repoRoot)
+    let idle = makeWorktree(id: "/tmp/repo/idle", name: "idle", repoRoot: repoRoot)
+    let repository = Repository(
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
+      rootURL: repoRoot,
+      name: "repo",
+      worktrees: IdentifiedArray(uniqueElements: [main, idle])
+    )
+    let state = makeState(repositories: [repository])
+
+    let structure = state.computeSidebarStructure(groupPinned: true, groupActive: true)
+
+    #expect(structure.hoistSummaryByRepositoryID[repository.id] == nil)
+  }
+
+  @Test func hoistSummaryExcludesFolders() {
+    let folderURL = URL(fileURLWithPath: "/tmp/folder")
+    let folderID = Repository.folderWorktreeID(for: folderURL)
+    let folderRepo = Repository(
+      id: RepositoryID(folderURL.path(percentEncoded: false)),
+      rootURL: folderURL,
+      name: "folder",
+      worktrees: IdentifiedArray(
+        uniqueElements: [
+          Worktree(
+            id: folderID,
+            name: "folder",
+            detail: "",
+            workingDirectory: folderURL,
+            repositoryRootURL: folderURL
+          )
+        ]
+      ),
+      isGitRepository: false
+    )
+    var state = makeState(repositories: [folderRepo])
+    state.$sidebar.withLock { sidebar in
+      var section = sidebar.sections[folderRepo.id] ?? .init()
+      var pinnedBucket = section.buckets[.pinned] ?? .init()
+      pinnedBucket.items[folderID] = .init()
+      section.buckets[.pinned] = pinnedBucket
+      section.buckets[.unpinned]?.items.removeValue(forKey: folderID)
+      sidebar.sections[folderRepo.id] = section
+    }
+
+    let structure = state.computeSidebarStructure(groupPinned: true, groupActive: false)
+
+    // The folder row is hoisted (so it carries a highlight tag) but a single-row
+    // folder gets no summary: its row stays fully visible at the top.
+    #expect(structure.hoistedRowIDs.contains(folderID))
+    #expect(structure.hoistSummaryByRepositoryID[folderRepo.id] == nil)
+  }
+
+  @Test func hoistSummaryCountsGitMainHoistedIntoActive() {
+    let repoRoot = URL(fileURLWithPath: "/tmp/repo")
+    let main = makeMainWorktree(repoRoot: repoRoot)
+    let repository = Repository(
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
+      rootURL: repoRoot,
+      name: "repo",
+      worktrees: IdentifiedArray(uniqueElements: [main])
+    )
+    var state = makeState(repositories: [repository])
+    state.sidebarItems[id: main.id]?.runningScripts.append(.init(id: UUID(), tint: .blue))
+
+    let structure = state.computeSidebarStructure(groupPinned: true, groupActive: true)
+
+    let summary = structure.hoistSummaryByRepositoryID[repository.id]
+    #expect(summary?.activeCount == 1)
+    #expect(summary?.pinnedCount == 0)
+    #expect(summary?.revealTarget == main.id)
+    // The repository section is still emitted (header + summary line), with no
+    // per-repo rows since main was hoisted.
+    let repoGroups = structure.sections.compactMap { section -> [SidebarItemGroup]? in
+      if case .repository(let id, let groups) = section, id == repository.id { return groups }
+      return nil
+    }.flatMap { $0 }
+    #expect(repoGroups.allSatisfy { $0.rowIDs.isEmpty })
+  }
+
+  @Test func hoistSummaryKeepsEachRepoTallyIndependent() {
+    let rootA = URL(fileURLWithPath: "/tmp/repo-a")
+    let rootB = URL(fileURLWithPath: "/tmp/repo-b")
+    let mainA = makeMainWorktree(repoRoot: rootA)
+    let mainB = makeMainWorktree(repoRoot: rootB)
+    let pinnedA = makeWorktree(id: "/tmp/repo-a/p", name: "pa", repoRoot: rootA)
+    let pinnedB = makeWorktree(id: "/tmp/repo-b/p", name: "pb", repoRoot: rootB)
+    let repoA = Repository(
+      id: RepositoryID(rootA.path(percentEncoded: false)),
+      rootURL: rootA,
+      name: "repo-a",
+      worktrees: IdentifiedArray(uniqueElements: [mainA, pinnedA])
+    )
+    let repoB = Repository(
+      id: RepositoryID(rootB.path(percentEncoded: false)),
+      rootURL: rootB,
+      name: "repo-b",
+      worktrees: IdentifiedArray(uniqueElements: [mainB, pinnedB])
+    )
+    var state = makeState(repositories: [repoA, repoB])
+    state.$sidebar.withLock { sidebar in
+      for (repoID, pinnedID) in [(repoA.id, pinnedA.id), (repoB.id, pinnedB.id)] {
+        var section = sidebar.sections[repoID] ?? .init()
+        var pinnedBucket = section.buckets[.pinned] ?? .init()
+        pinnedBucket.items[pinnedID] = .init()
+        section.buckets[.pinned] = pinnedBucket
+        sidebar.sections[repoID] = section
+      }
+    }
+
+    let structure = state.computeSidebarStructure(groupPinned: true, groupActive: false)
+
+    #expect(structure.hoistSummaryByRepositoryID[repoA.id]?.revealTarget == pinnedA.id)
+    #expect(structure.hoistSummaryByRepositoryID[repoB.id]?.revealTarget == pinnedB.id)
+    #expect(structure.hoistSummaryByRepositoryID[repoA.id]?.pinnedCount == 1)
+    #expect(structure.hoistSummaryByRepositoryID[repoB.id]?.pinnedCount == 1)
+  }
+
+  @Test func hoistSummaryTalliesMultipleRowsPerBucket() {
+    let repoRoot = URL(fileURLWithPath: "/tmp/repo")
+    let main = makeMainWorktree(repoRoot: repoRoot)
+    let pin1 = makeWorktree(id: "/tmp/repo/pin1", name: "pin1", repoRoot: repoRoot)
+    let pin2 = makeWorktree(id: "/tmp/repo/pin2", name: "pin2", repoRoot: repoRoot)
+    let busy1 = makeWorktree(id: "/tmp/repo/busy1", name: "busy1", repoRoot: repoRoot)
+    let busy2 = makeWorktree(id: "/tmp/repo/busy2", name: "busy2", repoRoot: repoRoot)
+    let repository = Repository(
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
+      rootURL: repoRoot,
+      name: "repo",
+      worktrees: IdentifiedArray(uniqueElements: [main, pin1, pin2, busy1, busy2])
+    )
+    var state = makeState(repositories: [repository])
+    state.$sidebar.withLock { sidebar in
+      var section = sidebar.sections[repository.id] ?? .init()
+      var pinnedBucket = section.buckets[.pinned] ?? .init()
+      pinnedBucket.items[pin1.id] = .init()
+      pinnedBucket.items[pin2.id] = .init()
+      section.buckets[.pinned] = pinnedBucket
+      sidebar.sections[repository.id] = section
+    }
+    state.sidebarItems[id: busy1.id]?.runningScripts.append(.init(id: UUID(), tint: .blue))
+    state.sidebarItems[id: busy2.id]?.runningScripts.append(.init(id: UUID(), tint: .blue))
+
+    let structure = state.computeSidebarStructure(groupPinned: true, groupActive: true)
+
+    let summary = structure.hoistSummaryByRepositoryID[repository.id]
+    #expect(summary?.pinnedCount == 2)
+    #expect(summary?.activeCount == 2)
+    #expect(summary?.label == "+2 pinned, +2 active")
+  }
+
+  @Test func hoistSummaryLabelOmitsActiveBucketWhenPinnedOnly() {
+    let repoRoot = URL(fileURLWithPath: "/tmp/repo")
+    let main = makeMainWorktree(repoRoot: repoRoot)
+    let pinned = makeWorktree(id: "/tmp/repo/pinned", name: "pinned", repoRoot: repoRoot)
+    let repository = Repository(
+      id: RepositoryID(repoRoot.path(percentEncoded: false)),
+      rootURL: repoRoot,
+      name: "repo",
+      worktrees: IdentifiedArray(uniqueElements: [main, pinned])
+    )
+    var state = makeState(repositories: [repository])
+    state.$sidebar.withLock { sidebar in
+      var section = sidebar.sections[repository.id] ?? .init()
+      var pinnedBucket = section.buckets[.pinned] ?? .init()
+      pinnedBucket.items[pinned.id] = .init()
+      section.buckets[.pinned] = pinnedBucket
+      sidebar.sections[repository.id] = section
+    }
+
+    let structure = state.computeSidebarStructure(groupPinned: true, groupActive: true)
+
+    let summary = structure.hoistSummaryByRepositoryID[repository.id]
+    #expect(summary?.activeCount == 0)
+    #expect(summary?.label == "+1 pinned")
+  }
+
   // MARK: - SidebarItemGroup.translateFilteredMove.
 
   @Test func translateFilteredMoveMapsAcrossHoistedRows() {
-    let full = ["a", "b", "c", "d", "e"]
-    let visible = ["a", "b", "d", "e"]  // c is hoisted.
+    let full: [Worktree.ID] = ["a", "b", "c", "d", "e"]
+    let visible: [Worktree.ID] = ["a", "b", "d", "e"]  // c is hoisted.
 
     // Move visible offset 2 (d) to visible offset 0 (before a).
     let result = SidebarItemGroup.translateFilteredMove(
@@ -683,8 +917,8 @@ struct SidebarStructureTests {
   }
 
   @Test func translateFilteredMoveDestinationPastEndMapsToFullEnd() {
-    let full = ["a", "b", "c", "d"]
-    let visible = ["a", "c", "d"]  // b is hoisted.
+    let full: [Worktree.ID] = ["a", "b", "c", "d"]
+    let visible: [Worktree.ID] = ["a", "c", "d"]  // b is hoisted.
 
     let result = SidebarItemGroup.translateFilteredMove(
       offsets: IndexSet([0]),
@@ -697,8 +931,8 @@ struct SidebarStructureTests {
   }
 
   @Test func translateFilteredMoveReturnsNilForOutOfRangeOffset() {
-    let full = ["a", "b", "c"]
-    let visible = ["a", "c"]
+    let full: [Worktree.ID] = ["a", "b", "c"]
+    let visible: [Worktree.ID] = ["a", "c"]
 
     let result = SidebarItemGroup.translateFilteredMove(
       offsets: IndexSet([5]),
@@ -710,8 +944,8 @@ struct SidebarStructureTests {
   }
 
   @Test func translateFilteredMoveReturnsNilForOutOfRangeDestination() {
-    let full = ["a", "b", "c"]
-    let visible = ["a", "c"]
+    let full: [Worktree.ID] = ["a", "b", "c"]
+    let visible: [Worktree.ID] = ["a", "c"]
 
     let result = SidebarItemGroup.translateFilteredMove(
       offsets: IndexSet([0]),
@@ -723,8 +957,8 @@ struct SidebarStructureTests {
   }
 
   @Test func translateFilteredMoveReturnsNilWhenVisibleHasIDNotInFull() {
-    let full = ["a", "b"]
-    let visible = ["a", "ghost"]  // "ghost" isn't in full.
+    let full: [Worktree.ID] = ["a", "b"]
+    let visible: [Worktree.ID] = ["a", "ghost"]  // "ghost" isn't in full.
 
     let result = SidebarItemGroup.translateFilteredMove(
       offsets: IndexSet([1]),
@@ -736,8 +970,8 @@ struct SidebarStructureTests {
   }
 
   @Test func translateFilteredMoveAppliedYieldsExpectedFullOrder() {
-    let full = ["a", "b", "c", "d", "e"]
-    let visible = ["a", "b", "d", "e"]  // c is hoisted.
+    let full: [Worktree.ID] = ["a", "b", "c", "d", "e"]
+    let visible: [Worktree.ID] = ["a", "b", "d", "e"]  // c is hoisted.
 
     // Drag b (visible 1) past d (to before e, visible 3).
     let translated = SidebarItemGroup.translateFilteredMove(
@@ -756,8 +990,8 @@ struct SidebarStructureTests {
   }
 
   @Test func translateFilteredMoveHandlesEmptyOffsets() {
-    let full = ["a", "b"]
-    let visible = ["a", "b"]
+    let full: [Worktree.ID] = ["a", "b"]
+    let visible: [Worktree.ID] = ["a", "b"]
 
     let result = SidebarItemGroup.translateFilteredMove(
       offsets: IndexSet(),
@@ -773,8 +1007,8 @@ struct SidebarStructureTests {
     // Inclusive upper-bound test: visible's last index (NOT past-end) when
     // followed by a hoisted tail row must map to its own full index, not the
     // full-end. Drops the dragged row before the hoisted tail, not after.
-    let full = ["a", "b", "c", "d"]  // d is hoisted.
-    let visible = ["a", "b", "c"]
+    let full: [Worktree.ID] = ["a", "b", "c", "d"]  // d is hoisted.
+    let visible: [Worktree.ID] = ["a", "b", "c"]
 
     let translated = SidebarItemGroup.translateFilteredMove(
       offsets: IndexSet([0]),
diff --git a/supacodeTests/SymlinkPreservingFileWriterTests.swift b/supacodeTests/SymlinkPreservingFileWriterTests.swift
new file mode 100644
index 000000000..896f5e153
--- /dev/null
+++ b/supacodeTests/SymlinkPreservingFileWriterTests.swift
@@ -0,0 +1,229 @@
+import Foundation
+import SupacodeSettingsShared
+import Testing
+
+struct SymlinkPreservingFileWriterTests {
+  private let fileManager = FileManager.default
+
+  private func makeTempDir() throws -> URL {
+    let dir = fileManager.temporaryDirectory
+      .appending(path: "symlink-writer-test-\(UUID().uuidString)", directoryHint: .isDirectory)
+    try fileManager.createDirectory(at: dir, withIntermediateDirectories: true)
+    return dir
+  }
+
+  private func isSymlink(_ url: URL) -> Bool {
+    (try? fileManager.destinationOfSymbolicLink(atPath: url.path(percentEncoded: false))) != nil
+  }
+
+  @Test func writesPlainFileWithContent() throws {
+    let dir = try makeTempDir()
+    defer { try? fileManager.removeItem(at: dir) }
+    let url = dir.appending(path: "settings.json", directoryHint: .notDirectory)
+    let payload = Data("{\"a\":1}".utf8)
+
+    try SymlinkPreservingFileWriter.write(payload, to: url)
+
+    #expect(try Data(contentsOf: url) == payload)
+    #expect(!isSymlink(url))
+  }
+
+  @Test func createsMissingParentDirectories() throws {
+    let dir = try makeTempDir()
+    defer { try? fileManager.removeItem(at: dir) }
+    let url = dir.appending(path: "nested/deep/settings.json", directoryHint: .notDirectory)
+    let payload = Data("{}".utf8)
+
+    try SymlinkPreservingFileWriter.write(payload, to: url)
+
+    #expect(try Data(contentsOf: url) == payload)
+  }
+
+  @Test func preservesAbsoluteSymlinkAndWritesThrough() throws {
+    let dir = try makeTempDir()
+    defer { try? fileManager.removeItem(at: dir) }
+    let target = dir.appending(path: "target.json", directoryHint: .notDirectory)
+    let link = dir.appending(path: "settings.json", directoryHint: .notDirectory)
+    try Data("old".utf8).write(to: target)
+    try fileManager.createSymbolicLink(at: link, withDestinationURL: target)
+    let payload = Data("new".utf8)
+
+    try SymlinkPreservingFileWriter.write(payload, to: link)
+
+    #expect(isSymlink(link))
+    #expect(try Data(contentsOf: target) == payload)
+    #expect(try Data(contentsOf: link) == payload)
+  }
+
+  @Test func preservesRelativeSymlinkAndWritesThrough() throws {
+    let dir = try makeTempDir()
+    defer { try? fileManager.removeItem(at: dir) }
+    let supacodeDir = dir.appending(path: ".supacode", directoryHint: .isDirectory)
+    let dotfilesDir = dir.appending(path: "dotfiles", directoryHint: .isDirectory)
+    try fileManager.createDirectory(at: supacodeDir, withIntermediateDirectories: true)
+    try fileManager.createDirectory(at: dotfilesDir, withIntermediateDirectories: true)
+    let target = dotfilesDir.appending(path: "settings.json", directoryHint: .notDirectory)
+    try Data("old".utf8).write(to: target)
+    let link = supacodeDir.appending(path: "settings.json", directoryHint: .notDirectory)
+    try fileManager.createSymbolicLink(
+      atPath: link.path(percentEncoded: false),
+      withDestinationPath: "../dotfiles/settings.json"
+    )
+    let payload = Data("new".utf8)
+
+    try SymlinkPreservingFileWriter.write(payload, to: link)
+
+    #expect(isSymlink(link))
+    #expect(try Data(contentsOf: target) == payload)
+  }
+
+  @Test func createsTargetForDanglingSymlinkWhenParentExists() throws {
+    let dir = try makeTempDir()
+    defer { try? fileManager.removeItem(at: dir) }
+    let supacodeDir = dir.appending(path: ".supacode", directoryHint: .isDirectory)
+    let dotfilesDir = dir.appending(path: "dotfiles", directoryHint: .isDirectory)
+    try fileManager.createDirectory(at: supacodeDir, withIntermediateDirectories: true)
+    try fileManager.createDirectory(at: dotfilesDir, withIntermediateDirectories: true)
+    let link = supacodeDir.appending(path: "settings.json", directoryHint: .notDirectory)
+    try fileManager.createSymbolicLink(
+      atPath: link.path(percentEncoded: false),
+      withDestinationPath: "../dotfiles/settings.json"
+    )
+    let payload = Data("new".utf8)
+
+    try SymlinkPreservingFileWriter.write(payload, to: link)
+
+    #expect(isSymlink(link))
+    let target = dotfilesDir.appending(path: "settings.json", directoryHint: .notDirectory)
+    #expect(try Data(contentsOf: target) == payload)
+  }
+
+  @Test func failsAndCreatesNoPhantomDirectoryForDanglingIntoMissingDir() throws {
+    let dir = try makeTempDir()
+    defer { try? fileManager.removeItem(at: dir) }
+    let supacodeDir = dir.appending(path: ".supacode", directoryHint: .isDirectory)
+    try fileManager.createDirectory(at: supacodeDir, withIntermediateDirectories: true)
+    let link = supacodeDir.appending(path: "settings.json", directoryHint: .notDirectory)
+    try fileManager.createSymbolicLink(
+      atPath: link.path(percentEncoded: false),
+      withDestinationPath: "../missing/settings.json"
+    )
+
+    #expect(throws: (any Error).self) {
+      try SymlinkPreservingFileWriter.write(Data("new".utf8), to: link)
+    }
+    let missingDir = dir.appending(path: "missing", directoryHint: .isDirectory)
+    #expect(!fileManager.fileExists(atPath: missingDir.path(percentEncoded: false)))
+    #expect(isSymlink(link))
+  }
+
+  @Test func followsSymlinkChainToFinalTarget() throws {
+    let dir = try makeTempDir()
+    defer { try? fileManager.removeItem(at: dir) }
+    let real = dir.appending(path: "real.json", directoryHint: .notDirectory)
+    let mid = dir.appending(path: "mid.json", directoryHint: .notDirectory)
+    let link = dir.appending(path: "link.json", directoryHint: .notDirectory)
+    try Data("old".utf8).write(to: real)
+    try fileManager.createSymbolicLink(atPath: mid.path(percentEncoded: false), withDestinationPath: "real.json")
+    try fileManager.createSymbolicLink(atPath: link.path(percentEncoded: false), withDestinationPath: "mid.json")
+    let payload = Data("new".utf8)
+
+    try SymlinkPreservingFileWriter.write(payload, to: link)
+
+    #expect(isSymlink(link))
+    #expect(isSymlink(mid))
+    #expect(try Data(contentsOf: real) == payload)
+  }
+
+  @Test func throwsOnSymlinkCycle() throws {
+    let dir = try makeTempDir()
+    defer { try? fileManager.removeItem(at: dir) }
+    let linkA = dir.appending(path: "a.json", directoryHint: .notDirectory)
+    let linkB = dir.appending(path: "b.json", directoryHint: .notDirectory)
+    try fileManager.createSymbolicLink(atPath: linkA.path(percentEncoded: false), withDestinationPath: "b.json")
+    try fileManager.createSymbolicLink(atPath: linkB.path(percentEncoded: false), withDestinationPath: "a.json")
+
+    #expect(throws: SymlinkPreservingFileWriterError.self) {
+      try SymlinkPreservingFileWriter.write(Data("x".utf8), to: linkA)
+    }
+    #expect(isSymlink(linkA))
+    #expect(isSymlink(linkB))
+  }
+
+  @Test func throwsOnOverlyDeepSymlinkChain() throws {
+    let dir = try makeTempDir()
+    defer { try? fileManager.removeItem(at: dir) }
+    // A 40-link chain (link0 -> link1 -> ... -> link40) exceeds the kernel's
+    // symlink-resolution limit, so the loader could never read it back.
+    for hop in 0..<40 {
+      let here = dir.appending(path: "link\(hop).json", directoryHint: .notDirectory)
+      try fileManager.createSymbolicLink(
+        atPath: here.path(percentEncoded: false),
+        withDestinationPath: "link\(hop + 1).json"
+      )
+    }
+    let head = dir.appending(path: "link0.json", directoryHint: .notDirectory)
+
+    #expect(throws: SymlinkPreservingFileWriterError.self) {
+      try SymlinkPreservingFileWriter.write(Data("x".utf8), to: head)
+    }
+    #expect(isSymlink(head))
+  }
+
+  @Test func writeOverwritesExistingRealFile() throws {
+    let dir = try makeTempDir()
+    defer { try? fileManager.removeItem(at: dir) }
+    let url = dir.appending(path: "settings.json", directoryHint: .notDirectory)
+    try Data("old".utf8).write(to: url)
+    let payload = Data("new".utf8)
+
+    try SymlinkPreservingFileWriter.write(payload, to: url)
+
+    #expect(try Data(contentsOf: url) == payload)
+    #expect(!isSymlink(url))
+  }
+
+  @Test func moveAsideMovesPlainFileWhenNotSymlink() throws {
+    let dir = try makeTempDir()
+    defer { try? fileManager.removeItem(at: dir) }
+    let url = dir.appending(path: "settings.json", directoryHint: .notDirectory)
+    let aside = dir.appending(path: "settings.json.corrupt", directoryHint: .notDirectory)
+    try Data("corrupt".utf8).write(to: url)
+
+    try SymlinkPreservingFileWriter.moveAside(at: url, to: aside)
+
+    #expect(try Data(contentsOf: aside) == Data("corrupt".utf8))
+    #expect(!fileManager.fileExists(atPath: url.path(percentEncoded: false)))
+  }
+
+  @Test func moveAsideFallsBackToMovingLinkOnCycle() throws {
+    let dir = try makeTempDir()
+    defer { try? fileManager.removeItem(at: dir) }
+    let linkA = dir.appending(path: "a.json", directoryHint: .notDirectory)
+    let linkB = dir.appending(path: "b.json", directoryHint: .notDirectory)
+    let aside = dir.appending(path: "a.json.corrupt", directoryHint: .notDirectory)
+    try fileManager.createSymbolicLink(atPath: linkA.path(percentEncoded: false), withDestinationPath: "b.json")
+    try fileManager.createSymbolicLink(atPath: linkB.path(percentEncoded: false), withDestinationPath: "a.json")
+
+    try SymlinkPreservingFileWriter.moveAside(at: linkA, to: aside)
+
+    #expect(isSymlink(aside))
+    #expect(!fileManager.fileExists(atPath: linkA.path(percentEncoded: false)))
+  }
+
+  @Test func moveAsideRelocatesTargetAndKeepsSymlink() throws {
+    let dir = try makeTempDir()
+    defer { try? fileManager.removeItem(at: dir) }
+    let target = dir.appending(path: "target.json", directoryHint: .notDirectory)
+    let link = dir.appending(path: "sidebar.json", directoryHint: .notDirectory)
+    let aside = dir.appending(path: "sidebar.json.corrupt", directoryHint: .notDirectory)
+    try Data("corrupt".utf8).write(to: target)
+    try fileManager.createSymbolicLink(at: link, withDestinationURL: target)
+
+    try SymlinkPreservingFileWriter.moveAside(at: link, to: aside)
+
+    #expect(isSymlink(link))
+    #expect(try Data(contentsOf: aside) == Data("corrupt".utf8))
+    #expect(!fileManager.fileExists(atPath: target.path(percentEncoded: false)))
+  }
+}
diff --git a/supacodeTests/TerminalTabFeatureTests.swift b/supacodeTests/TerminalTabFeatureTests.swift
index bd1cc0d53..108d0e51a 100644
--- a/supacodeTests/TerminalTabFeatureTests.swift
+++ b/supacodeTests/TerminalTabFeatureTests.swift
@@ -56,6 +56,36 @@ struct TerminalTabFeatureTests {
     }
   }
 
+  @Test func projectionChangedPropagatesSurfaceGeneration() async {
+    let tabID = TerminalTabID(rawValue: UUID())
+    let surface = UUID()
+    let store = TestStore(
+      initialState: TerminalTabFeature.State(
+        id: tabID,
+        worktreeID: "/tmp/repo",
+        surfaceIDs: [surface],
+        activeSurfaceID: surface,
+        unseenNotificationCount: 0
+      )
+    ) { TerminalTabFeature() }
+
+    // A same-UUID surface swap bumps only the generation; the leaf must mirror it
+    // so the view rebuilds.
+    await store.send(
+      .projectionChanged(
+        WorktreeTabProjection(
+          tabID: tabID,
+          surfaceIDs: [surface],
+          activeSurfaceID: surface,
+          unseenNotificationCount: 0,
+          surfaceGeneration: 1
+        )
+      )
+    ) {
+      $0.surfaceGeneration = 1
+    }
+  }
+
   @Test func projectionChangedTogglesSplitZoomedIndependently() async {
     let tabID = TerminalTabID(rawValue: UUID())
     let surface = UUID()
diff --git a/supacodeTests/ToolbarNotificationGroupingTests.swift b/supacodeTests/ToolbarNotificationGroupingTests.swift
index 031f9a08c..b53e8ef6a 100644
--- a/supacodeTests/ToolbarNotificationGroupingTests.swift
+++ b/supacodeTests/ToolbarNotificationGroupingTests.swift
@@ -4,6 +4,7 @@ import OrderedCollections
 import Sharing
 import Testing
 
+@testable import SupacodeSettingsShared
 @testable import supacode
 
 @MainActor
@@ -159,6 +160,70 @@ struct ToolbarNotificationGroupingTests {
     #expect(groups[0].unseenWorktreeCount == 0)
   }
 
+  @Test func usesResolvedSidebarTitleWhenCustomTitleIsSet() {
+    // A user-set custom title (from `WorktreeCustomizationFeature.save`)
+    // flows into `SidebarItemFeature.State.customTitle` via the reconcile
+    // pass; the notification popover must show that resolved title, not
+    // the raw branch name.
+    let repoPath = "/tmp/repo-customized"
+    let main = makeWorktree(id: repoPath, name: "main", repoRoot: repoPath)
+    let feature = makeWorktree(id: "\(repoPath)/feature", name: "feature/x", repoRoot: repoPath)
+
+    let repo = makeRepository(id: repoPath, name: "Repo", worktrees: [main, feature])
+    var state = RepositoriesFeature.State(reconciledRepositories: [repo])
+    state.repositoryRoots = [repo.rootURL]
+
+    state.sidebarItems[id: feature.id]?.customTitle = "Spicy"
+
+    setRowNotifications(
+      &state, id: feature.id,
+      notifications: [
+        WorktreeTerminalNotification(surfaceID: UUID(), title: "T", body: "done", createdAt: .distantPast)
+      ])
+
+    let groups = state.computeToolbarNotificationGroups()
+
+    #expect(groups.first?.worktrees.first?.name == "Spicy")
+  }
+
+  @Test func includesRemoteRepositoryNotifications() {
+    // Remote repos are host-keyed and absent from `repositoryRoots` (which is
+    // local-only), so `orderedRepositoryIDs()` doesn't list them. The toolbar
+    // bell must still surface their notifications.
+    let host = RemoteHost(alias: "devbox")
+    let repoID = "remote:devbox:/home/me/proj"
+    let feature = Worktree(
+      id: "devbox:/home/me/proj/feature",
+      name: "feature",
+      detail: "",
+      workingDirectory: URL(fileURLWithPath: "/home/me/proj/feature"),
+      repositoryRootURL: URL(fileURLWithPath: "/home/me/proj"),
+      host: host
+    )
+    let repo = Repository(
+      id: RepositoryID(repoID),
+      rootURL: URL(fileURLWithPath: "/home/me/proj"),
+      name: "proj",
+      worktrees: IdentifiedArray(uniqueElements: [feature]),
+      isGitRepository: true,
+      host: host
+    )
+    var state = RepositoriesFeature.State(reconciledRepositories: [repo])
+    // repositoryRoots intentionally left empty, the remote repo isn't in it.
+
+    setRowNotifications(
+      &state, id: feature.id,
+      notifications: [
+        WorktreeTerminalNotification(surfaceID: UUID(), title: "Remote", body: "needs input", createdAt: .distantPast)
+      ])
+
+    let groups = state.computeToolbarNotificationGroups()
+
+    #expect(groups.map(\.id) == [RepositoryID(repoID)])
+    #expect(groups.first?.worktrees.map(\.id) == [feature.id])
+    #expect(groups.first?.unseenWorktreeCount == 1)
+  }
+
   private func setRowNotifications(
     _ state: inout RepositoriesFeature.State,
     id: SidebarItemID,
@@ -175,7 +240,7 @@ struct ToolbarNotificationGroupingTests {
     repoRoot: String
   ) -> Worktree {
     Worktree(
-      id: id,
+      id: WorktreeID(id),
       name: name,
       detail: "detail",
       workingDirectory: URL(fileURLWithPath: id),
@@ -189,7 +254,7 @@ struct ToolbarNotificationGroupingTests {
     worktrees: [Worktree]
   ) -> Repository {
     Repository(
-      id: id,
+      id: RepositoryID(id),
       rootURL: URL(fileURLWithPath: id),
       name: name,
       worktrees: IdentifiedArray(uniqueElements: worktrees)
diff --git a/supacodeTests/WindowTitleTests.swift b/supacodeTests/WindowTitleTests.swift
index f53b0d011..ac9416bd9 100644
--- a/supacodeTests/WindowTitleTests.swift
+++ b/supacodeTests/WindowTitleTests.swift
@@ -4,6 +4,7 @@ import IdentifiedCollections
 import OrderedCollections
 import Testing
 
+@testable import SupacodeSettingsShared
 @testable import supacode
 
 @MainActor
@@ -84,8 +85,8 @@ struct WindowTitleTests {
 
   @Test func computeFailedRepositoryUsesDirectoryName() {
     var state = RepositoriesFeature.State()
-    let id = "/tmp/missing-repo"
-    state.repositoryRoots = [URL(fileURLWithPath: id)]
+    let id: Repository.ID = "/tmp/missing-repo"
+    state.repositoryRoots = [URL(fileURLWithPath: id.rawValue)]
     state.loadFailuresByID = [id: "Not found"]
     state.selection = .failedRepository(id)
     let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
@@ -94,8 +95,8 @@ struct WindowTitleTests {
 
   @Test func computeFailedRepositoryPrefersCustomTitle() {
     var state = RepositoriesFeature.State()
-    let id = "/tmp/missing-repo"
-    state.repositoryRoots = [URL(fileURLWithPath: id)]
+    let id: Repository.ID = "/tmp/missing-repo"
+    state.repositoryRoots = [URL(fileURLWithPath: id.rawValue)]
     state.loadFailuresByID = [id: "Not found"]
     state.selection = .failedRepository(id)
     state.$sidebar.withLock { sidebar in
@@ -107,19 +108,44 @@ struct WindowTitleTests {
     #expect(WindowTitle.compute(repositories: state, terminalManager: manager) == "My Project · Unavailable")
   }
 
+  @Test func computeFailedRemoteRepositoryUsesPlaceholderNameNotFileURL() {
+    let config = TestRemoteRepo(
+      host: RemoteHost(alias: "devbox"),
+      remotePath: "/home/me/proj",
+      displayName: "proj"
+    )
+    let id = RepositoriesFeature.remoteRepositoryID(for: config)
+    // A disconnected remote keeps a placeholder repository plus a load failure.
+    let placeholder = Repository(
+      id: id,
+      rootURL: URL(fileURLWithPath: config.normalizedRemotePath),
+      name: config.resolvedDisplayName,
+      worktrees: [],
+      isGitRepository: true,
+      host: config.host
+    )
+    var state = RepositoriesFeature.State()
+    state.repositories = [placeholder]
+    state.loadFailuresByID = [id: "Can't reach devbox."]
+    state.selection = .failedRepository(id)
+    let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
+    // Deriving from the `user@host` authority id as a file URL would mangle the name.
+    #expect(WindowTitle.compute(repositories: state, terminalManager: manager) == "proj · Unavailable")
+  }
+
   // MARK: - helpers.
 
   private func makeState(repoName: String, customTitle: String?) -> RepositoriesFeature.State {
     let rootURL = URL(fileURLWithPath: "/tmp/\(repoName)")
     let worktree = Worktree(
-      id: "/tmp/\(repoName)/main",
+      id: WorktreeID("/tmp/\(repoName)/main"),
       name: "main",
       detail: "",
       workingDirectory: URL(fileURLWithPath: "/tmp/\(repoName)/main"),
       repositoryRootURL: rootURL
     )
     let repository = Repository(
-      id: rootURL.path(percentEncoded: false),
+      id: RepositoryID(rootURL.path(percentEncoded: false)),
       rootURL: rootURL,
       name: repoName,
       worktrees: IdentifiedArray(uniqueElements: [worktree])
diff --git a/supacodeTests/WorktreeCreationPromptFeatureTests.swift b/supacodeTests/WorktreeCreationPromptFeatureTests.swift
index 9c52236fe..0f90a7b40 100644
--- a/supacodeTests/WorktreeCreationPromptFeatureTests.swift
+++ b/supacodeTests/WorktreeCreationPromptFeatureTests.swift
@@ -2,9 +2,11 @@ import ComposableArchitecture
 import Foundation
 import Testing
 
+@testable import SupacodeSettingsShared
 @testable import supacode
 
 @MainActor
+@Suite(.serialized)
 struct WorktreeCreationPromptFeatureTests {
   private func makeState(
     automaticBaseRef: String = "origin/main",
@@ -12,9 +14,11 @@ struct WorktreeCreationPromptFeatureTests {
     remoteNames: [String] = ["origin"],
     branchMenu: BaseRefBranchMenu? = nil,
     selectedBaseRef: String? = nil,
-    defaultWorktreeBaseDirectory: String = "/tmp/repo/.worktrees"
+    defaultWorktreeBaseDirectory: String = "/tmp/repo/.worktrees",
+    title: String = "",
+    color: RepositoryColor? = nil
   ) -> WorktreeCreationPromptFeature.State {
-    WorktreeCreationPromptFeature.State(
+    var state = WorktreeCreationPromptFeature.State(
       repositoryID: "/tmp/repo/",
       repositoryRootURL: URL(fileURLWithPath: "/tmp/repo"),
       repositoryName: "repo",
@@ -28,6 +32,9 @@ struct WorktreeCreationPromptFeatureTests {
       defaultWorktreeBaseDirectory: defaultWorktreeBaseDirectory,
       validationMessage: nil
     )
+    state.title = title
+    state.color = color
+    return state
   }
 
   @Test func baseRefSelectedUpdatesSelectionAndClearsValidation() async {
@@ -82,7 +89,9 @@ struct WorktreeCreationPromptFeatureTests {
           branchName: "feature/new",
           baseRef: "origin/dev",
           fetchOrigin: true,
-          placement: WorktreePlacementOverride(name: nil, path: nil)
+          placement: WorktreePlacementOverride(name: nil, path: nil),
+          title: nil,
+          color: nil
         )
       )
     )
@@ -106,7 +115,9 @@ struct WorktreeCreationPromptFeatureTests {
           branchName: "feature/new",
           baseRef: "main",
           fetchOrigin: false,
-          placement: WorktreePlacementOverride(name: nil, path: nil)
+          placement: WorktreePlacementOverride(name: nil, path: nil),
+          title: nil,
+          color: nil
         )
       )
     )
@@ -137,7 +148,9 @@ struct WorktreeCreationPromptFeatureTests {
           placement: WorktreePlacementOverride(
             name: "feature_new",
             path: "~/Repos"
-          )
+          ),
+          title: nil,
+          color: nil
         )
       )
     )
@@ -220,4 +233,85 @@ struct WorktreeCreationPromptFeatureTests {
     state.worktreeNameOverride = "feature_foo"
     #expect(state.resolvedWorktreeLocationPreview == "/tmp/repo/.worktrees/feature_foo/")
   }
+
+  // MARK: - Title / Color customization
+
+  @Test func submitTrimsBranchAndForwardsTitleAndColor() async {
+    var state = makeState(title: "  Spicy  ", color: .blue)
+    state.branchName = "  feature/x  "
+    let store = TestStore(initialState: state) {
+      WorktreeCreationPromptFeature()
+    }
+
+    await store.send(.createButtonTapped)
+    await store.receive(
+      .delegate(
+        .submit(
+          repositoryID: "/tmp/repo/",
+          branchName: "feature/x",
+          baseRef: nil,
+          fetchOrigin: true,
+          placement: WorktreePlacementOverride(name: nil, path: nil),
+          title: "Spicy",
+          color: .blue
+        )
+      )
+    )
+  }
+
+  @Test func submitPreservesTitleWhenItMatchesBranch() async {
+    var state = makeState(title: "feature/x")
+    state.branchName = "feature/x"
+    let store = TestStore(initialState: state) {
+      WorktreeCreationPromptFeature()
+    }
+
+    await store.send(.createButtonTapped)
+    await store.receive(
+      .delegate(
+        .submit(
+          repositoryID: "/tmp/repo/",
+          branchName: "feature/x",
+          baseRef: nil,
+          fetchOrigin: true,
+          placement: WorktreePlacementOverride(name: nil, path: nil),
+          title: "feature/x",
+          color: nil
+        )
+      )
+    )
+  }
+
+  @Test func submitWithNoCustomizationForwardsNilTitleAndColor() async {
+    var state = makeState()
+    state.branchName = "feature/x"
+    let store = TestStore(initialState: state) {
+      WorktreeCreationPromptFeature()
+    }
+
+    await store.send(.createButtonTapped)
+    await store.receive(
+      .delegate(
+        .submit(
+          repositoryID: "/tmp/repo/",
+          branchName: "feature/x",
+          baseRef: nil,
+          fetchOrigin: true,
+          placement: WorktreePlacementOverride(name: nil, path: nil),
+          title: nil,
+          color: nil
+        )
+      )
+    )
+  }
+
+  @Test func emptyBranchNameBlocksSubmit() async {
+    let store = TestStore(initialState: makeState()) {
+      WorktreeCreationPromptFeature()
+    }
+
+    await store.send(.createButtonTapped) {
+      $0.validationMessage = "Branch name required."
+    }
+  }
 }
diff --git a/supacodeTests/WorktreeCreationPromptParentTests.swift b/supacodeTests/WorktreeCreationPromptParentTests.swift
new file mode 100644
index 000000000..247c97a57
--- /dev/null
+++ b/supacodeTests/WorktreeCreationPromptParentTests.swift
@@ -0,0 +1,427 @@
+import ComposableArchitecture
+import Foundation
+import IdentifiedCollections
+import Testing
+
+@testable import SupacodeSettingsShared
+@testable import supacode
+
+@MainActor
+@Suite(.serialized)
+struct WorktreeCreationPromptParentTests {
+  private let repoID: Repository.ID = "/tmp/create-wt-repo"
+
+  private func makeStateWithPrompt(
+    pendingFor branchNames: [String: PendingWorktree.Customization] = [:],
+  ) -> RepositoriesFeature.State {
+    let mainWorktree = Worktree(
+      id: WorktreeID("\(repoID)/main"),
+      name: "main",
+      detail: "detail",
+      workingDirectory: URL(fileURLWithPath: repoID.rawValue),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue),
+    )
+    let repository = Repository(
+      id: repoID,
+      rootURL: URL(fileURLWithPath: repoID.rawValue),
+      name: "create-wt-repo",
+      worktrees: IdentifiedArray(uniqueElements: [mainWorktree]),
+      isGitRepository: true,
+    )
+    var state = RepositoriesFeature.State()
+    state.repositories = IdentifiedArray(uniqueElements: [repository])
+    state.repositoryRoots = [repository.rootURL]
+    state.worktreeCreationPrompt = WorktreeCreationPromptFeature.State(
+      repositoryID: repoID,
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue),
+      repositoryName: "create-wt-repo",
+      automaticBaseRef: "main",
+      defaultBranch: "main",
+      remoteNames: [],
+      branchMenu: nil,
+      branchName: "",
+      selectedBaseRef: nil,
+      fetchOrigin: false,
+      defaultWorktreeBaseDirectory: "/tmp/create-wt-repo/.worktrees",
+      validationMessage: nil,
+    )
+    if !branchNames.isEmpty {
+      state.pendingCreationCustomizations[repoID] = branchNames
+    }
+    return state
+  }
+
+  private func makeStore(
+    initialState: RepositoriesFeature.State
+  ) -> TestStoreOf<RepositoriesFeature> {
+    let store = TestStore(initialState: initialState) {
+      RepositoriesFeature()
+    } withDependencies: {
+      $0.uuid = .incrementing
+    }
+    store.exhaustivity = .off
+    return store
+  }
+
+  @Test func cancelClearsPendingCreationCustomizationsForRepo() async {
+    let store = makeStore(
+      initialState: makeStateWithPrompt(
+        pendingFor: ["feature/x": .init(title: "Test", color: .blue)]
+      ))
+
+    await store.send(.worktreeCreationPrompt(.presented(.delegate(.cancel)))) {
+      $0.worktreeCreationPrompt = nil
+      $0.pendingCreationCustomizations.removeValue(forKey: self.repoID)
+    }
+  }
+
+  @Test func dismissPreservesPendingCreationCustomizations() async {
+    // .dismiss also fires when the parent nils the prompt on the success path.
+    let store = makeStore(
+      initialState: makeStateWithPrompt(
+        pendingFor: ["feature/x": .init(title: "Test", color: .blue)]
+      ))
+
+    await store.send(.worktreeCreationPrompt(.dismiss)) {
+      $0.worktreeCreationPrompt = nil
+    }
+  }
+
+  @Test func submitWithoutCustomizationClearsStaleEntryForSameBranch() async {
+    let store = makeStore(
+      initialState: makeStateWithPrompt(
+        pendingFor: ["feature/x": .init(title: "Stale", color: .blue)]
+      ))
+
+    await store.send(
+      .worktreeCreationPrompt(
+        .presented(
+          .delegate(
+            .submit(
+              repositoryID: repoID,
+              branchName: "feature/x",
+              baseRef: nil,
+              fetchOrigin: false,
+              placement: WorktreePlacementOverride(name: nil, path: nil),
+              title: nil,
+              color: nil,
+            )
+          )))
+    ) {
+      $0.pendingCreationCustomizations.removeValue(forKey: self.repoID)
+    }
+  }
+
+  @Test func duplicateValidationFailureDropsPendingCustomization() async {
+    let store = makeStore(
+      initialState: makeStateWithPrompt(
+        pendingFor: ["feature/x": .init(title: "Old", color: .blue)]
+      ))
+
+    await store.send(
+      .promptedWorktreeCreationChecked(
+        repositoryID: repoID,
+        branchName: "feature/x",
+        baseRef: nil,
+        fetchOrigin: false,
+        placement: WorktreePlacementOverride(name: nil, path: nil),
+        duplicateMessage: "Branch name already exists.",
+      )
+    ) {
+      $0.worktreeCreationPrompt?.isValidating = false
+      $0.worktreeCreationPrompt?.validationMessage = "Branch name already exists."
+      $0.pendingCreationCustomizations.removeValue(forKey: self.repoID)
+    }
+  }
+
+  @Test func immediateDuplicateInStartPromptedClearsPendingCustomization() async {
+    // First-pass duplicate check (runs before the async branch-list fetch) is a normal
+    // prompt-flow rejection. The pending entry must be cleared.
+    var state = makeStateWithPrompt(
+      pendingFor: ["feature/x": .init(title: "Stale", color: .blue)]
+    )
+    // Add an existing worktree with the same name so the synchronous check trips.
+    let existing = Worktree(
+      id: WorktreeID("\(repoID)/feature-x"),
+      name: "feature/x",
+      detail: "detail",
+      workingDirectory: URL(fileURLWithPath: "\(repoID)/feature-x"),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue),
+    )
+    let repo = state.repositories[id: repoID]!
+    var worktrees = repo.worktrees
+    worktrees.append(existing)
+    state.repositories[id: repoID] = Repository(
+      id: repo.id,
+      rootURL: repo.rootURL,
+      name: repo.name,
+      worktrees: worktrees,
+      isGitRepository: true,
+    )
+    let store = makeStore(initialState: state)
+
+    await store.send(
+      .startPromptedWorktreeCreation(
+        repositoryID: repoID,
+        branchName: "feature/x",
+        baseRef: nil,
+        fetchOrigin: false,
+        placement: WorktreePlacementOverride(name: nil, path: nil),
+      )
+    ) {
+      $0.worktreeCreationPrompt?.isValidating = false
+      $0.worktreeCreationPrompt?.validationMessage = "Branch name already exists."
+      $0.pendingCreationCustomizations.removeValue(forKey: self.repoID)
+    }
+  }
+
+  @Test func createWorktreeForRemovingRepositoryClearsPendingCustomization() async {
+    var initial = makeStateWithPrompt(
+      pendingFor: ["feature/x": .init(title: "Stale", color: .blue)]
+    )
+    initial.removingRepositoryIDs[repoID] = RepositoriesFeature.RepositoryRemovalRecord(
+      disposition: .gitWorktreeDelete,
+      batchID: UUID()
+    )
+    let store = makeStore(initialState: initial)
+
+    await store.send(
+      .createWorktreeInRepository(
+        repositoryID: repoID,
+        nameSource: .explicit("feature/x"),
+        baseRefSource: .explicit(nil),
+        fetchOrigin: false,
+      )
+    ) {
+      $0.pendingCreationCustomizations.removeValue(forKey: self.repoID)
+    }
+  }
+
+  @Test func createWorktreeTransfersCustomizationFromMapToPendingRow() async {
+    // Phase-1 → phase-2 transition: when the explicit-name creation begins, the map
+    // entry for the branch must move onto the new `PendingWorktree.customization`.
+    let store = makeStore(
+      initialState: makeStateWithPrompt(
+        pendingFor: ["feature/x": .init(title: "Fresh", color: .red)]
+      ))
+
+    await store.send(
+      .createWorktreeInRepository(
+        repositoryID: repoID,
+        nameSource: .explicit("feature/x"),
+        baseRefSource: .explicit(nil),
+        fetchOrigin: false,
+      )
+    ) {
+      $0.pendingCreationCustomizations.removeValue(forKey: self.repoID)
+      $0.pendingWorktrees = [
+        PendingWorktree(
+          id: "pending:00000000-0000-0000-0000-000000000000",
+          repositoryID: self.repoID,
+          progress: WorktreeCreationProgress(
+            stage: .loadingLocalBranches,
+            worktreeName: "feature/x"
+          ),
+          customization: .init(title: "Fresh", color: .red)
+        )
+      ]
+    }
+  }
+
+  @Test func reloadThatPrunesPendingRowTransfersCustomizationToDiscoveredWorktree() async {
+    let pendingID: Worktree.ID = "pending:test"
+    var initial = makeStateWithPrompt()
+    initial.pendingWorktrees = [
+      PendingWorktree(
+        id: pendingID,
+        repositoryID: repoID,
+        progress: WorktreeCreationProgress(stage: .creatingWorktree, worktreeName: "feature/x"),
+        customization: .init(title: "Fresh", color: .red)
+      )
+    ]
+    let createdWorktreeID = WorktreeID("\(repoID)/feature-x")
+    let createdWorktree = Worktree(
+      id: createdWorktreeID,
+      name: "feature/x",
+      detail: "detail",
+      workingDirectory: URL(fileURLWithPath: createdWorktreeID.rawValue),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue),
+    )
+    let existingRepository = initial.repositories[id: repoID]!
+    var reloadedWorktrees = existingRepository.worktrees
+    reloadedWorktrees.append(createdWorktree)
+    let reloadedRepository = Repository(
+      id: repoID,
+      rootURL: existingRepository.rootURL,
+      name: existingRepository.name,
+      worktrees: reloadedWorktrees,
+      isGitRepository: true,
+    )
+    let store = makeStore(initialState: initial)
+
+    await store.send(
+      .repositoriesLoaded(
+        [reloadedRepository],
+        failures: [],
+        roots: [existingRepository.rootURL],
+        animated: false
+      )
+    ) {
+      $0.repositories = [reloadedRepository]
+      $0.repositoryRoots = [existingRepository.rootURL]
+      $0.pendingWorktrees.removeAll()
+      $0.isInitialLoadComplete = true
+      $0.$sidebar.withLock { sidebar in
+        sidebar.insert(
+          worktree: createdWorktreeID,
+          in: self.repoID,
+          bucket: .unpinned,
+          item: SidebarState.Item(title: "Fresh", color: .red),
+          position: nil,
+        )
+      }
+    }
+  }
+
+  @Test func reloadMatchesPendingRowsToDiscoveredWorktreesByName() async {
+    // Two concurrent pending creations, only one of the worktrees appears in the reload.
+    // The pending row whose `progress.worktreeName` matches the discovered worktree must
+    // be the one pruned; the other pending row must survive, and the matched one's
+    // customization must be seeded onto the discovered worktree's sidebar item.
+    let pendingAID: Worktree.ID = "pending:a"
+    let pendingBID: Worktree.ID = "pending:b"
+    var initial = makeStateWithPrompt()
+    initial.pendingWorktrees = [
+      PendingWorktree(
+        id: pendingAID,
+        repositoryID: repoID,
+        progress: WorktreeCreationProgress(stage: .creatingWorktree, worktreeName: "feature/a"),
+        customization: .init(title: "Title A", color: .red),
+      ),
+      PendingWorktree(
+        id: pendingBID,
+        repositoryID: repoID,
+        progress: WorktreeCreationProgress(stage: .creatingWorktree, worktreeName: "feature/b"),
+        customization: .init(title: "Title B", color: .blue),
+      ),
+    ]
+    let bWorktreeID = WorktreeID("\(repoID)/feature-b")
+    let bWorktree = Worktree(
+      id: bWorktreeID,
+      name: "feature/b",
+      detail: "detail",
+      workingDirectory: URL(fileURLWithPath: bWorktreeID.rawValue),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue),
+    )
+    let existingRepository = initial.repositories[id: repoID]!
+    var reloadedWorktrees = existingRepository.worktrees
+    reloadedWorktrees.append(bWorktree)
+    let reloadedRepository = Repository(
+      id: repoID,
+      rootURL: existingRepository.rootURL,
+      name: existingRepository.name,
+      worktrees: reloadedWorktrees,
+      isGitRepository: true,
+    )
+    let store = makeStore(initialState: initial)
+
+    await store.send(
+      .repositoriesLoaded(
+        [reloadedRepository],
+        failures: [],
+        roots: [existingRepository.rootURL],
+        animated: false,
+      )
+    ) {
+      $0.repositories = [reloadedRepository]
+      $0.repositoryRoots = [existingRepository.rootURL]
+      // Pending A (no matching discovered worktree) survives; pending B is pruned.
+      $0.pendingWorktrees = [
+        PendingWorktree(
+          id: pendingAID,
+          repositoryID: self.repoID,
+          progress: WorktreeCreationProgress(stage: .creatingWorktree, worktreeName: "feature/a"),
+          customization: .init(title: "Title A", color: .red),
+        )
+      ]
+      $0.isInitialLoadComplete = true
+      $0.$sidebar.withLock { sidebar in
+        sidebar.insert(
+          worktree: bWorktreeID,
+          in: self.repoID,
+          bucket: .unpinned,
+          item: SidebarState.Item(title: "Title B", color: .blue),
+          position: nil,
+        )
+      }
+    }
+  }
+
+  @Test func successAppliesCustomizationFromPendingRowToSidebar() async {
+    let pendingID: Worktree.ID = "pending:test"
+    var initial = makeStateWithPrompt()
+    initial.pendingWorktrees = [
+      PendingWorktree(
+        id: pendingID,
+        repositoryID: repoID,
+        progress: WorktreeCreationProgress(stage: .creatingWorktree, worktreeName: "feature/x"),
+        customization: .init(title: "Fresh", color: .red)
+      )
+    ]
+    let createdWorktreeID = WorktreeID("\(repoID)/feature-x")
+    let createdWorktree = Worktree(
+      id: createdWorktreeID,
+      name: "feature/x",
+      detail: "detail",
+      workingDirectory: URL(fileURLWithPath: createdWorktreeID.rawValue),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue),
+    )
+    let store = makeStore(initialState: initial)
+
+    await store.send(
+      .createRandomWorktreeSucceeded(
+        createdWorktree,
+        repositoryID: repoID,
+        pendingID: pendingID,
+      )
+    ) {
+      $0.pendingWorktrees.removeAll()
+      $0.$sidebar.withLock { sidebar in
+        sidebar.insert(
+          worktree: createdWorktreeID,
+          in: self.repoID,
+          bucket: .unpinned,
+          item: SidebarState.Item(title: "Fresh", color: .red),
+          position: nil,
+        )
+      }
+    }
+  }
+
+  @Test func submitWithCustomizationOverwritesStaleEntryForSameBranch() async {
+    let store = makeStore(
+      initialState: makeStateWithPrompt(
+        pendingFor: ["feature/x": .init(title: "Stale", color: .blue)]
+      ))
+
+    await store.send(
+      .worktreeCreationPrompt(
+        .presented(
+          .delegate(
+            .submit(
+              repositoryID: repoID,
+              branchName: "feature/x",
+              baseRef: nil,
+              fetchOrigin: false,
+              placement: WorktreePlacementOverride(name: nil, path: nil),
+              title: "Fresh",
+              color: .red,
+            )
+          )))
+    ) {
+      $0.pendingCreationCustomizations[self.repoID] = [
+        "feature/x": .init(title: "Fresh", color: .red)
+      ]
+    }
+  }
+}
diff --git a/supacodeTests/WorktreeCustomizationFeatureTests.swift b/supacodeTests/WorktreeCustomizationFeatureTests.swift
new file mode 100644
index 000000000..62151d7fe
--- /dev/null
+++ b/supacodeTests/WorktreeCustomizationFeatureTests.swift
@@ -0,0 +1,67 @@
+import ComposableArchitecture
+import Foundation
+import Testing
+
+@testable import SupacodeSettingsShared
+@testable import supacode
+
+@MainActor
+@Suite(.serialized)
+struct WorktreeCustomizationFeatureTests {
+  private func makeState(
+    title: String = "",
+    color: RepositoryColor? = nil,
+  ) -> WorktreeCustomizationFeature.State {
+    WorktreeCustomizationFeature.State(
+      worktreeID: "wt-1",
+      repositoryID: "/tmp/repo",
+      defaultName: "feature/x",
+      title: title,
+      color: color,
+    )
+  }
+
+  @Test func saveTrimsTitleAndForwardsValues() async {
+    let store = TestStore(initialState: makeState(title: "  Spicy  ", color: .blue)) {
+      WorktreeCustomizationFeature()
+    }
+
+    await store.send(.saveButtonTapped)
+    await store.receive(
+      .delegate(
+        .save(worktreeID: "wt-1", repositoryID: "/tmp/repo", title: "Spicy", color: .blue),
+      ))
+  }
+
+  @Test func saveDropsTitleOnlyWhenEmptyAfterTrim() async {
+    let store = TestStore(initialState: makeState(title: "   ")) {
+      WorktreeCustomizationFeature()
+    }
+
+    await store.send(.saveButtonTapped)
+    await store.receive(
+      .delegate(.save(worktreeID: "wt-1", repositoryID: "/tmp/repo", title: nil, color: nil)),
+    )
+  }
+
+  @Test func savePreservesTitleEvenWhenItMatchesDefault() async {
+    // Typing the default name locks it in as an explicit override (doesn't collapse to nil).
+    let store = TestStore(initialState: makeState(title: "feature/x")) {
+      WorktreeCustomizationFeature()
+    }
+
+    await store.send(.saveButtonTapped)
+    await store.receive(
+      .delegate(.save(worktreeID: "wt-1", repositoryID: "/tmp/repo", title: "feature/x", color: nil)),
+    )
+  }
+
+  @Test func cancelDelegatesCancel() async {
+    let store = TestStore(initialState: makeState()) {
+      WorktreeCustomizationFeature()
+    }
+
+    await store.send(.cancelButtonTapped)
+    await store.receive(.delegate(.cancel))
+  }
+}
diff --git a/supacodeTests/WorktreeCustomizationParentTests.swift b/supacodeTests/WorktreeCustomizationParentTests.swift
new file mode 100644
index 000000000..457846f0d
--- /dev/null
+++ b/supacodeTests/WorktreeCustomizationParentTests.swift
@@ -0,0 +1,352 @@
+import ComposableArchitecture
+import Foundation
+import IdentifiedCollections
+import OrderedCollections
+import SupacodeSettingsShared
+import Testing
+
+@testable import supacode
+
+@MainActor
+@Suite(.serialized)
+struct WorktreeCustomizationParentTests {
+  private let repoID: RepositoryID = "/tmp/customize-wt-repo"
+  private let worktreeID: WorktreeID = "/tmp/customize-wt-repo/feature-x"
+
+  private func makeInitialState(
+    isGitRepository: Bool = true,
+    seedSidebarBucket: Bool = true,
+  ) -> RepositoriesFeature.State {
+    let mainWorktree = Worktree(
+      id: WorktreeID("\(repoID)/main"),
+      name: "main",
+      detail: "detail",
+      workingDirectory: URL(fileURLWithPath: repoID.rawValue),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue),
+    )
+    let featureWorktree = Worktree(
+      id: worktreeID,
+      name: "feature/x",
+      detail: "detail",
+      workingDirectory: URL(fileURLWithPath: worktreeID.rawValue),
+      repositoryRootURL: URL(fileURLWithPath: repoID.rawValue),
+    )
+    let repository = Repository(
+      id: repoID,
+      rootURL: URL(fileURLWithPath: repoID.rawValue),
+      name: "customize-wt-repo",
+      worktrees: IdentifiedArray(uniqueElements: [mainWorktree, featureWorktree]),
+      isGitRepository: isGitRepository,
+    )
+    var state = RepositoriesFeature.State()
+    state.repositories = IdentifiedArray(uniqueElements: [repository])
+    state.repositoryRoots = [repository.rootURL]
+    if seedSidebarBucket {
+      state.$sidebar.withLock { sidebar in
+        sidebar.insert(worktree: self.worktreeID, in: self.repoID, bucket: .unpinned)
+      }
+    }
+    // Pre-build `sidebarItems` so save / cancel tests can assert against an
+    // existing per-row state instead of forcing the reducer's `syncSidebar`
+    // to materialise rows mid-action and flag the test on unrelated diffs.
+    RepositoriesFeature.syncSidebar(&state)
+    // Pre-warm the post-reduce caches so the in-reducer recompute is a delta
+    // from a populated baseline (matches what every action would see in a
+    // real run) rather than a build-from-nil that registers as state churn.
+    state.applyPostReduceCacheRecomputes()
+    return state
+  }
+
+  @Test func requestCustomizeWorktreeSeedsPromptFromStoredItem() async {
+    var initial = makeInitialState()
+    initial.$sidebar.withLock { sidebar in
+      sidebar.sections[self.repoID]?.buckets[.unpinned]?.items[self.worktreeID]?.title = "Spicy"
+      sidebar.sections[self.repoID]?.buckets[.unpinned]?.items[self.worktreeID]?.color = .blue
+    }
+    let store = TestStore(initialState: initial) {
+      RepositoriesFeature()
+    }
+
+    await store.send(.requestCustomizeWorktree(worktreeID, repoID)) {
+      $0.worktreeCustomization = WorktreeCustomizationFeature.State(
+        worktreeID: self.worktreeID,
+        repositoryID: self.repoID,
+        defaultName: "feature/x",
+        title: "Spicy",
+        color: .blue,
+      )
+    }
+  }
+
+  @Test func requestCustomizeWorktreeSeedsEmptyPromptWhenNoStoredItem() async {
+    let store = TestStore(initialState: makeInitialState(seedSidebarBucket: false)) {
+      RepositoriesFeature()
+    }
+
+    await store.send(.requestCustomizeWorktree(worktreeID, repoID)) {
+      $0.worktreeCustomization = WorktreeCustomizationFeature.State(
+        worktreeID: self.worktreeID,
+        repositoryID: self.repoID,
+        defaultName: "feature/x",
+        title: "",
+        color: nil,
+      )
+    }
+  }
+
+  @Test func requestCustomizeWorktreeOpensSheetForFolderSyntheticRow() async {
+    // Folder synthetic rows ARE the row the user customizes; they share the worktree path so the
+    // per-row title / color the picker writes lands on the visible folder row.
+    let store = TestStore(
+      initialState: makeInitialState(isGitRepository: false, seedSidebarBucket: false)
+    ) {
+      RepositoriesFeature()
+    }
+
+    await store.send(.requestCustomizeWorktree(worktreeID, repoID)) {
+      $0.worktreeCustomization = WorktreeCustomizationFeature.State(
+        worktreeID: self.worktreeID,
+        repositoryID: self.repoID,
+        defaultName: "customize-wt-repo",
+        title: "",
+        color: nil,
+      )
+    }
+  }
+
+  @Test func requestCustomizeWorktreeNoOpsForMainWorktrees() async {
+    // The context menu hides the entry for the main worktree row, but a future palette /
+    // deeplink could still route here. The reducer guard is the backstop.
+    let store = TestStore(initialState: makeInitialState(seedSidebarBucket: false)) {
+      RepositoriesFeature()
+    }
+
+    await store.send(.requestCustomizeWorktree(WorktreeID("\(repoID)/main"), repoID))
+    #expect(store.state.worktreeCustomization == nil)
+  }
+
+  @Test func saveDelegatePersistsTitleAndColorToBucketedItem() async {
+    var initial = makeInitialState()
+    initial.worktreeCustomization = WorktreeCustomizationFeature.State(
+      worktreeID: worktreeID,
+      repositoryID: repoID,
+      defaultName: "feature/x",
+      title: "",
+      color: nil,
+    )
+    let store = TestStore(initialState: initial) {
+      RepositoriesFeature()
+    }
+
+    await store.send(
+      .worktreeCustomization(
+        .presented(
+          .delegate(
+            .save(
+              worktreeID: worktreeID,
+              repositoryID: repoID,
+              title: "Renamed",
+              color: .red,
+            )
+          )))
+    ) {
+      $0.worktreeCustomization = nil
+      $0.$sidebar.withLock { sidebar in
+        sidebar.sections[self.repoID]?.buckets[.unpinned]?.items[self.worktreeID]?.title =
+          "Renamed"
+        sidebar.sections[self.repoID]?.buckets[.unpinned]?.items[self.worktreeID]?.color = .red
+      }
+      // syncSidebar fans the bucketed Item write into the per-row mirror.
+      $0.sidebarItems[id: self.worktreeID]?.customTitle = "Renamed"
+      $0.sidebarItems[id: self.worktreeID]?.customTint = .red
+      // The save action invalidates every cache; mirror the post-reduce hook
+      // so the test diff only contains intentional state changes.
+      $0.applyPostReduceCacheRecomputes()
+    }
+  }
+
+  @Test func saveDelegateRefreshesSelectedWorktreeSlice() async {
+    var initial = makeInitialState()
+    initial.setSingleWorktreeSelection(worktreeID)
+    initial.applyPostReduceCacheRecomputes(.selectedWorktreeSlice)
+    initial.worktreeCustomization = WorktreeCustomizationFeature.State(
+      worktreeID: worktreeID,
+      repositoryID: repoID,
+      defaultName: "feature/x",
+      title: "",
+      color: nil,
+    )
+    let store = TestStore(initialState: initial) {
+      RepositoriesFeature()
+    }
+
+    await store.send(
+      .worktreeCustomization(
+        .presented(
+          .delegate(
+            .save(
+              worktreeID: worktreeID,
+              repositoryID: repoID,
+              title: "Renamed",
+              color: .red,
+            )
+          )))
+    ) {
+      $0.worktreeCustomization = nil
+      $0.$sidebar.withLock { sidebar in
+        sidebar.sections[self.repoID]?.buckets[.unpinned]?.items[self.worktreeID]?.title =
+          "Renamed"
+        sidebar.sections[self.repoID]?.buckets[.unpinned]?.items[self.worktreeID]?.color = .red
+      }
+      $0.sidebarItems[id: self.worktreeID]?.customTitle = "Renamed"
+      $0.sidebarItems[id: self.worktreeID]?.customTint = .red
+      $0.applyPostReduceCacheRecomputes()
+    }
+    #expect(store.state.selectedWorktreeSlice?.resolvedSidebarTitle == "Renamed")
+    #expect(store.state.selectedWorktreeSlice?.customTint == .red)
+  }
+
+  @Test func pinWorktreePreservesCustomTitleAndColor() async {
+    var initial = makeInitialState()
+    initial.$sidebar.withLock { sidebar in
+      sidebar.sections[self.repoID]?.buckets[.unpinned]?.items[self.worktreeID]?.title =
+        "Renamed"
+      sidebar.sections[self.repoID]?.buckets[.unpinned]?.items[self.worktreeID]?.color = .red
+    }
+    RepositoriesFeature.syncSidebar(&initial)
+    initial.applyPostReduceCacheRecomputes()
+    let store = TestStore(initialState: initial) {
+      RepositoriesFeature()
+    } withDependencies: {
+      $0.analyticsClient.capture = { _, _ in }
+    }
+    store.exhaustivity = .off
+
+    await store.send(.pinWorktree(worktreeID))
+
+    #expect(store.state.sidebar.sections[repoID]?.buckets[.unpinned]?.items[worktreeID] == nil)
+    #expect(store.state.sidebar.sections[repoID]?.buckets[.pinned]?.items[worktreeID]?.title == "Renamed")
+    #expect(store.state.sidebar.sections[repoID]?.buckets[.pinned]?.items[worktreeID]?.color == .red)
+    #expect(store.state.sidebarItems[id: worktreeID]?.customTitle == "Renamed")
+    #expect(store.state.sidebarItems[id: worktreeID]?.customTint == .red)
+  }
+
+  @Test func unpinWorktreePreservesCustomTitleAndColor() async {
+    var initial = makeInitialState(seedSidebarBucket: false)
+    initial.$sidebar.withLock { sidebar in
+      sidebar.insert(
+        worktree: self.worktreeID,
+        in: self.repoID,
+        bucket: .pinned,
+        item: .init(title: "Renamed", color: .red)
+      )
+    }
+    RepositoriesFeature.syncSidebar(&initial)
+    initial.applyPostReduceCacheRecomputes()
+    let store = TestStore(initialState: initial) {
+      RepositoriesFeature()
+    } withDependencies: {
+      $0.analyticsClient.capture = { _, _ in }
+    }
+    store.exhaustivity = .off
+
+    await store.send(.unpinWorktree(worktreeID))
+
+    #expect(store.state.sidebar.sections[repoID]?.buckets[.pinned]?.items[worktreeID] == nil)
+    #expect(store.state.sidebar.sections[repoID]?.buckets[.unpinned]?.items[worktreeID]?.title == "Renamed")
+    #expect(store.state.sidebar.sections[repoID]?.buckets[.unpinned]?.items[worktreeID]?.color == .red)
+    #expect(store.state.sidebarItems[id: worktreeID]?.customTitle == "Renamed")
+    #expect(store.state.sidebarItems[id: worktreeID]?.customTint == .red)
+  }
+
+  @Test func unpinWorktreePrefersPinnedPayloadOverStaleUnpinnedSibling() async {
+    // Defensive coverage for a corrupted double-bucket pre-state (hand-edit,
+    // migrator race) where the same row exists in both `.pinned` and
+    // `.unpinned` with different payloads. The pinned entry is the live
+    // row the user sees; unpin must carry its `title` / `color` forward,
+    // not the stale unpinned sibling's.
+    var initial = makeInitialState(seedSidebarBucket: false)
+    initial.$sidebar.withLock { sidebar in
+      sidebar.insert(
+        worktree: self.worktreeID,
+        in: self.repoID,
+        bucket: .pinned,
+        item: .init(title: "Live", color: .red)
+      )
+      sidebar.insert(
+        worktree: self.worktreeID,
+        in: self.repoID,
+        bucket: .unpinned,
+        item: .init(title: "Stale", color: .blue)
+      )
+    }
+    RepositoriesFeature.syncSidebar(&initial)
+    initial.applyPostReduceCacheRecomputes()
+    let store = TestStore(initialState: initial) {
+      RepositoriesFeature()
+    } withDependencies: {
+      $0.analyticsClient.capture = { _, _ in }
+    }
+    store.exhaustivity = .off
+
+    await store.send(.unpinWorktree(worktreeID))
+
+    #expect(store.state.sidebar.sections[repoID]?.buckets[.pinned]?.items[worktreeID] == nil)
+    #expect(store.state.sidebar.sections[repoID]?.buckets[.unpinned]?.items[worktreeID]?.title == "Live")
+    #expect(store.state.sidebar.sections[repoID]?.buckets[.unpinned]?.items[worktreeID]?.color == .red)
+  }
+
+  @Test func pinWorktreePrefersUnpinnedPayloadOverStalePinnedSibling() async {
+    // Symmetric to the unpin case: when the same row appears in both buckets, `.unpinned` is the
+    // logical source for a pin, so its payload (not a stale `.pinned` sibling's) must round-trip.
+    var initial = makeInitialState(seedSidebarBucket: false)
+    initial.$sidebar.withLock { sidebar in
+      sidebar.insert(
+        worktree: self.worktreeID,
+        in: self.repoID,
+        bucket: .unpinned,
+        item: .init(title: "Live", color: .red)
+      )
+      sidebar.insert(
+        worktree: self.worktreeID,
+        in: self.repoID,
+        bucket: .pinned,
+        item: .init(title: "Stale", color: .blue)
+      )
+    }
+    RepositoriesFeature.syncSidebar(&initial)
+    initial.applyPostReduceCacheRecomputes()
+    let store = TestStore(initialState: initial) {
+      RepositoriesFeature()
+    } withDependencies: {
+      $0.analyticsClient.capture = { _, _ in }
+    }
+    store.exhaustivity = .off
+
+    await store.send(.pinWorktree(worktreeID))
+
+    #expect(store.state.sidebar.sections[repoID]?.buckets[.unpinned]?.items[worktreeID] == nil)
+    #expect(store.state.sidebar.sections[repoID]?.buckets[.pinned]?.items[worktreeID]?.title == "Live")
+    #expect(store.state.sidebar.sections[repoID]?.buckets[.pinned]?.items[worktreeID]?.color == .red)
+  }
+
+  @Test func cancelDelegateClearsPresentedState() async {
+    var initial = makeInitialState()
+    initial.worktreeCustomization = WorktreeCustomizationFeature.State(
+      worktreeID: worktreeID,
+      repositoryID: repoID,
+      defaultName: "feature/x",
+      title: "",
+      color: nil,
+    )
+    let store = TestStore(initialState: initial) {
+      RepositoriesFeature()
+    }
+
+    await store.send(
+      .worktreeCustomization(.presented(.delegate(.cancel)))
+    ) {
+      $0.worktreeCustomization = nil
+    }
+  }
+}
diff --git a/supacodeTests/WorktreeEnvironmentTests.swift b/supacodeTests/WorktreeEnvironmentTests.swift
index 8c9b72f59..6db3db9b4 100644
--- a/supacodeTests/WorktreeEnvironmentTests.swift
+++ b/supacodeTests/WorktreeEnvironmentTests.swift
@@ -2,6 +2,7 @@ import Darwin
 import Foundation
 import Testing
 
+@testable import SupacodeSettingsShared
 @testable import supacode
 
 @MainActor
@@ -55,10 +56,10 @@ struct WorktreeEnvironmentTests {
     #expect(runnerScript.contains("\"$SUPACODE_SHELL_PATH\" -l \(quotedScriptPath)") == true)
     // The runner exec-tails after emitting OSC 133;D so the outer shell
     // stays blocked and no new prompt prints in the readonly tab. Both
-    // 133;C and 133;D matter: `shell-integration = none` is on globally
-    // (GhosttyRuntime.bundledOverridesString) so Ghostty's shell shim
-    // won't emit prompt markers; the runner must self-emit so the
-    // tab-bar progress / `onCommandFinished` path still fires.
+    // 133;C and 133;D matter: blocking-script surfaces launch with
+    // `disableShellIntegration` so Ghostty injects no integration / prompt
+    // markers into the host shell; the runner must self-emit so the tab-bar
+    // progress / `onCommandFinished` path still fires.
     #expect(runnerScript.contains("exec tail -f /dev/null") == true)
     #expect(runnerScript.contains("133;C") == true)
     #expect(runnerScript.contains("133;D") == true)
@@ -95,6 +96,106 @@ struct WorktreeEnvironmentTests {
     )
   }
 
+  @Test func userScriptSurfaceEnvironmentCarriesIDKindAndScope() {
+    let definition = ScriptDefinition(id: UUID(), kind: .test, name: "Unit", command: "make test")
+    let env = BlockingScriptKind.script(definition).surfaceEnvironmentVariables(scope: .repo)
+    #expect(env["SUPACODE_BLOCKING_SCRIPT"] == "1")
+    #expect(env["SUPACODE_SCRIPT_ID"] == definition.id.uuidString)
+    #expect(env["SUPACODE_SCRIPT_KIND"] == "test")
+    #expect(env["SUPACODE_SCRIPT_SCOPE"] == "repo")
+    #expect(env.count == 4)
+  }
+
+  @Test func userScriptSurfaceEnvironmentOmitsScopeWhenUnresolved() {
+    let definition = ScriptDefinition(id: UUID(), kind: .run, name: "Run", command: "make run")
+    let env = BlockingScriptKind.script(definition).surfaceEnvironmentVariables(scope: nil)
+    #expect(env["SUPACODE_BLOCKING_SCRIPT"] == "1")
+    #expect(env["SUPACODE_SCRIPT_KIND"] == "run")
+    #expect(env["SUPACODE_SCRIPT_SCOPE"] == nil)
+    #expect(env.count == 3)
+  }
+
+  @Test func globalScriptSurfaceEnvironmentReportsGlobalScope() {
+    let definition = ScriptDefinition(id: UUID(), kind: .custom, name: "Deploy", command: "./deploy")
+    let env = BlockingScriptKind.script(definition).surfaceEnvironmentVariables(scope: .global)
+    #expect(env["SUPACODE_SCRIPT_KIND"] == "custom")
+    #expect(env["SUPACODE_SCRIPT_SCOPE"] == "global")
+  }
+
+  @Test func lifecycleSurfaceEnvironmentTagsKindWithoutIDOrScope() {
+    let archive = BlockingScriptKind.archive.surfaceEnvironmentVariables(scope: nil)
+    #expect(archive["SUPACODE_BLOCKING_SCRIPT"] == "1")
+    #expect(archive["SUPACODE_SCRIPT_KIND"] == "archive")
+    #expect(archive["SUPACODE_SCRIPT_ID"] == nil)
+    #expect(archive["SUPACODE_SCRIPT_SCOPE"] == nil)
+    #expect(archive.count == 2)
+
+    let delete = BlockingScriptKind.delete.surfaceEnvironmentVariables(scope: nil)
+    #expect(delete["SUPACODE_SCRIPT_KIND"] == "delete")
+    #expect(delete["SUPACODE_SCRIPT_ID"] == nil)
+    #expect(delete.count == 2)
+  }
+
+  @Test func remoteRunnerScriptFramesCdsAndRunsUserScriptAsChild() {
+    let runner = BlockingScriptRunner.remoteRunnerScript(remoteWorktreePath: "/home/me/wt")
+    // Same OSC 133 framing + read-only tail as the local runner, but on the host.
+    #expect(runner.contains("133;C"))
+    #expect(runner.contains("133;D"))
+    #expect(runner.contains("exec tail -f /dev/null"))
+    // cd into the remote worktree, then run the user script (`$1`) as a login-shell child.
+    #expect(runner.contains("cd -- '/home/me/wt'"))
+    #expect(runner.contains("\"$SHELL\" -l -c \"$1\""))
+    // Beta banner present (remote surfaces are in beta).
+    #expect(runner.contains("beta"))
+  }
+
+  @Test func remoteRunnerScriptSkipsCdForRootOrEmptyPath() {
+    #expect(!BlockingScriptRunner.remoteRunnerScript(remoteWorktreePath: "/").contains("cd -- "))
+    #expect(!BlockingScriptRunner.remoteRunnerScript(remoteWorktreePath: "  ").contains("cd -- "))
+  }
+
+  @Test func remoteCommandAppliesEnvironmentBeforeLoginShell() throws {
+    let host = RemoteHost(alias: "devbox")
+    let line = try #require(
+      BlockingScriptRunner.remoteCommand(
+        host: host,
+        script: "echo hi",
+        remoteWorktreePath: "/home/me/wt",
+        environment: ["SUPACODE_BLOCKING_SCRIPT": "1", "SUPACODE_SCRIPT_KIND": "run"]
+      )
+    )
+    #expect(line.contains("env SUPACODE_BLOCKING_SCRIPT="))
+    #expect(line.contains("SUPACODE_SCRIPT_KIND="))
+    // The env prefix precedes the login shell so its profile inherits the markers.
+    let envIndex = try #require(line.range(of: "env SUPACODE_BLOCKING_SCRIPT="))
+    let shellIndex = try #require(line.range(of: "\"$SHELL\" -l -c"))
+    #expect(envIndex.lowerBound < shellIndex.lowerBound)
+  }
+
+  @Test func remoteCommandOmitsEnvPrefixWhenEnvironmentEmpty() {
+    let host = RemoteHost(alias: "devbox")
+    let line = BlockingScriptRunner.remoteCommand(host: host, script: "echo hi", remoteWorktreePath: "/p")
+    #expect(line?.contains("exec \"$SHELL\" -l -c") == true)
+    #expect(line?.contains("env SUPACODE") == false)
+  }
+
+  @Test func remoteCommandWrapsRunnerInSSHWithUserScriptPositional() {
+    let host = RemoteHost(alias: "devbox", username: "alice", port: 2222)
+    let line = BlockingScriptRunner.remoteCommand(host: host, script: "echo hi", remoteWorktreePath: "/home/me/wt")
+    #expect(line?.hasPrefix("/usr/bin/ssh ") == true)
+    #expect(line?.contains("-p 2222 alice@devbox ") == true)
+    #expect(line?.contains("133;C") == true)
+    // The user script rides as a positional argument to the remote `-c` script.
+    #expect(line?.contains("'echo hi'") == true)
+    // No local blocking-script temp dir is referenced for the remote path.
+    #expect(line?.contains("supacode-blocking-script-") == false)
+  }
+
+  @Test func remoteCommandReturnsNilForEmptyScript() {
+    let host = RemoteHost(alias: "devbox")
+    #expect(BlockingScriptRunner.remoteCommand(host: host, script: "   ", remoteWorktreePath: "/p") == nil)
+  }
+
   @Test func blockingScriptLaunchPropagatesNonZeroExitCodeInZsh() throws {
     let launch = try #require(
       try BlockingScriptRunner.makeLaunch(
diff --git a/supacodeTests/WorktreeInfoWatcherManagerTests.swift b/supacodeTests/WorktreeInfoWatcherManagerTests.swift
index be886ed38..5b8b97f20 100644
--- a/supacodeTests/WorktreeInfoWatcherManagerTests.swift
+++ b/supacodeTests/WorktreeInfoWatcherManagerTests.swift
@@ -2,6 +2,7 @@ import Clocks
 import Foundation
 import Testing
 
+@testable import SupacodeSettingsShared
 @testable import supacode
 
 @MainActor
@@ -59,6 +60,75 @@ struct WorktreeInfoWatcherManagerTests {
     try FileManager.default.removeItem(at: tempRepository.tempRoot)
   }
 
+  @Test func emitsBranchChangedForRemoteWorktreeWhenHeadChanges() async throws {
+    let clock = TestClock()
+    let stub = RemoteBranchPollStub(responses: ["main", "feature"])
+    let manager = WorktreeInfoWatcherManager(
+      focusedInterval: .milliseconds(500),
+      unfocusedInterval: .milliseconds(500),
+      clock: clock,
+      pollRemoteBranch: { _ in await stub.next() }
+    )
+    let (collector, task) = startCollecting(manager.eventStream())
+    let remote = makeRemoteWorktree(name: "remote-eagle")
+
+    manager.handleCommand(.setPullRequestTrackingEnabled(false))
+    manager.handleCommand(.setWorktrees([remote]))
+    // The immediate first poll observes "main"; the 200ms branch debounce emits.
+    await drainAsyncEvents(200)
+    await clock.advance(by: .milliseconds(200))
+    await drainAsyncEvents(200)
+    #expect(await collector.branchChangedCount(worktreeID: remote.id) == 1)
+
+    // The next interval tick polls "feature" -> change -> debounce -> emit.
+    await clock.advance(by: .milliseconds(300))
+    await drainAsyncEvents(200)
+    await clock.advance(by: .milliseconds(200))
+    await drainAsyncEvents(200)
+    #expect(await collector.branchChangedCount(worktreeID: remote.id) == 2)
+
+    // Subsequent polls keep returning "feature", so no further branch changes.
+    await clock.advance(by: .milliseconds(500))
+    await drainAsyncEvents(200)
+    await clock.advance(by: .milliseconds(200))
+    await drainAsyncEvents(200)
+    #expect(await collector.branchChangedCount(worktreeID: remote.id) == 2)
+
+    manager.handleCommand(.stop)
+    await task.value
+  }
+
+  @Test func remoteHeadPollStopsAfterWorktreeRemoval() async throws {
+    let clock = TestClock()
+    let stub = RemoteBranchPollStub(responses: ["main"])
+    let manager = WorktreeInfoWatcherManager(
+      focusedInterval: .milliseconds(500),
+      unfocusedInterval: .milliseconds(500),
+      clock: clock,
+      pollRemoteBranch: { _ in await stub.next() }
+    )
+    let (collector, task) = startCollecting(manager.eventStream())
+    let remote = makeRemoteWorktree(name: "remote-eagle")
+
+    manager.handleCommand(.setPullRequestTrackingEnabled(false))
+    manager.handleCommand(.setWorktrees([remote]))
+    await drainAsyncEvents(200)
+    #expect(await stub.callCount >= 1)
+
+    // Removing the worktree must cancel the poll loop.
+    manager.handleCommand(.setWorktrees([]))
+    await drainAsyncEvents(200)
+    let callsAfterRemoval = await stub.callCount
+
+    await clock.advance(by: .seconds(2))
+    await drainAsyncEvents(200)
+    #expect(await stub.callCount == callsAfterRemoval)
+    _ = collector
+
+    manager.handleCommand(.stop)
+    await task.value
+  }
+
   @Test func selectionRefreshUsesCooldownWithinRepository() async throws {
     let clock = TestClock()
     let tempRepository = try makeTempRepository(worktreeNames: ["sparrow", "swift"])
@@ -146,6 +216,29 @@ struct WorktreeInfoWatcherManagerTests {
     await task.value
     try FileManager.default.removeItem(at: tempRepository.tempRoot)
   }
+
+  @Test func capsTheEventBufferUnderBackpressure() async throws {
+    let tempWorktree = try makeTempWorktree()
+    let manager = WorktreeInfoWatcherManager()
+    manager.handleCommand(.setPullRequestTrackingEnabled(false))
+    let stream = manager.eventStream()
+
+    // Each setWorktrees re-emits an immediate filesChanged for the worktree;
+    // with nothing draining, the buffer must cap rather than grow unbounded.
+    let overflow = WorktreeInfoWatcherManager.eventBufferCap + 50
+    for _ in 0..<overflow {
+      manager.handleCommand(.setWorktrees([tempWorktree.worktree]))
+    }
+    manager.handleCommand(.stop)
+
+    var count = 0
+    for await event in stream where event == .filesChanged(worktreeID: tempWorktree.worktree.id) {
+      count += 1
+    }
+
+    #expect(count == WorktreeInfoWatcherManager.eventBufferCap)
+    try FileManager.default.removeItem(at: tempWorktree.tempRoot)
+  }
 }
 
 actor EventCollector {
@@ -163,6 +256,14 @@ actor EventCollector {
     }
   }
 
+  func branchChangedCount(worktreeID: Worktree.ID) -> Int {
+    events.reduce(into: 0) { result, event in
+      if case .branchChanged(let id) = event, id == worktreeID {
+        result += 1
+      }
+    }
+  }
+
   func pullRequestRefreshCount(repositoryRootURL: URL) -> Int {
     events.reduce(into: 0) { result, event in
       if case .repositoryPullRequestRefresh(let rootURL, _) = event, rootURL == repositoryRootURL {
@@ -172,6 +273,37 @@ actor EventCollector {
   }
 }
 
+/// Stubs the remote-branch SSH poll: returns each queued value once, then
+/// repeats the last value for every subsequent poll. Tracks call count so a
+/// test can assert the poll loop stopped.
+actor RemoteBranchPollStub {
+  private var responses: [String?]
+  private(set) var callCount = 0
+
+  init(responses: [String?]) {
+    self.responses = responses
+  }
+
+  func next() -> String? {
+    callCount += 1
+    if responses.count > 1 {
+      return responses.removeFirst()
+    }
+    return responses.first ?? nil
+  }
+}
+
+private func makeRemoteWorktree(name: String) -> Worktree {
+  Worktree(
+    id: WorktreeID("devbox:/home/me/\(name)"),
+    name: name,
+    detail: "devbox",
+    workingDirectory: URL(fileURLWithPath: "/home/me/\(name)"),
+    repositoryRootURL: URL(fileURLWithPath: "/home/me/repo"),
+    host: RemoteHost(alias: "devbox")
+  )
+}
+
 private struct TempWorktree {
   let worktree: Worktree
   let tempRoot: URL
@@ -192,7 +324,7 @@ private func makeTempWorktree() throws -> TempWorktree {
   let headURL = gitDirectory.appending(path: "HEAD")
   try "ref: refs/heads/main\n".write(to: headURL, atomically: true, encoding: .utf8)
   let worktree = Worktree(
-    id: worktreeDirectory.path(percentEncoded: false),
+    id: WorktreeID(worktreeDirectory.path(percentEncoded: false)),
     name: "eagle",
     detail: "detail",
     workingDirectory: worktreeDirectory,
@@ -212,7 +344,7 @@ private func makeTempRepository(worktreeNames: [String]) throws -> TempRepositor
     let headURL = gitDirectory.appending(path: "HEAD")
     try "ref: refs/heads/\(name)\n".write(to: headURL, atomically: true, encoding: .utf8)
     let worktree = Worktree(
-      id: worktreeDirectory.path(percentEncoded: false),
+      id: WorktreeID(worktreeDirectory.path(percentEncoded: false)),
       name: name,
       detail: "detail",
       workingDirectory: worktreeDirectory,
diff --git a/supacodeTests/WorktreeTerminalManagerLayoutPersistenceTests.swift b/supacodeTests/WorktreeTerminalManagerLayoutPersistenceTests.swift
new file mode 100644
index 000000000..1e420ec00
--- /dev/null
+++ b/supacodeTests/WorktreeTerminalManagerLayoutPersistenceTests.swift
@@ -0,0 +1,358 @@
+import Clocks
+import Dependencies
+import Foundation
+import SupacodeSettingsShared
+import Testing
+
+@testable import supacode
+
+@MainActor
+@Suite(.serialized)
+struct LayoutPersistenceManagerTests {
+  /// Counts writer saves and mirrors the in-memory `@Shared(.layouts)` mutation
+  /// the app performs, so a test can assert both coalescing and final on-disk
+  /// state from one storage.
+  private struct Harness {
+    let manager: WorktreeTerminalManager
+    let clock: TestClock<Duration>
+    let saveCount: LockIsolated<Int>
+    let storage: SettingsFileStorage
+    let url: URL
+    /// When non-nil, the next save whose payload still contains `worktreeID`
+    /// (a positive snapshot) blocks on this semaphore so the test can hold the
+    /// positive flush Task in-flight while it triggers the prune.
+    let gate: LockIsolated<(worktreeID: String, semaphore: DispatchSemaphore)?>
+    /// Flips true once the gated positive save is blocked, proving the flush
+    /// Task is suspended inside `writer.flush` (i.e. `layoutFlushTasks[id]` is
+    /// still non-nil, before the spawning Task can clear it).
+    let gateEngaged: LockIsolated<Bool>
+  }
+
+  private func makeHarness() -> Harness {
+    let clock = TestClock()
+    let saveCount = LockIsolated(0)
+    let gate = LockIsolated<(worktreeID: String, semaphore: DispatchSemaphore)?>(nil)
+    let gateEngaged = LockIsolated(false)
+    let inner = SettingsFileStorage.inMemory()
+    let url = SupacodePaths.layoutsURL
+    let storage = SettingsFileStorage(
+      load: { try inner.load($0) },
+      save: { data, target in
+        if target == url { saveCount.withValue { $0 += 1 } }
+        // Block a positive snapshot write so the spawning flush Task stays
+        // in-flight; a delete payload (key absent) passes straight through.
+        if target == url,
+          let active = gate.value,
+          let dict = try? JSONDecoder().decode([String: TerminalLayoutSnapshot].self, from: data),
+          dict[active.worktreeID] != nil
+        {
+          gate.setValue(nil)
+          gateEngaged.setValue(true)
+          active.semaphore.wait()
+        }
+        try inner.save(data, target)
+      }
+    )
+    let manager = withDependencies {
+      $0.settingsFileStorage = storage
+    } operation: {
+      WorktreeTerminalManager(runtime: GhosttyRuntime(), clock: clock)
+    }
+    // Mirror the app's in-memory dict mutation; the writer's storage is the
+    // on-disk source of truth these tests assert against.
+    manager.saveLayoutSnapshot = { _, _ in }
+    return Harness(
+      manager: manager,
+      clock: clock,
+      saveCount: saveCount,
+      storage: storage,
+      url: url,
+      gate: gate,
+      gateEngaged: gateEngaged
+    )
+  }
+
+  private func readDict(_ harness: Harness) -> [String: TerminalLayoutSnapshot] {
+    guard let data = try? harness.storage.load(harness.url) else { return [:] }
+    return (try? JSONDecoder().decode([String: TerminalLayoutSnapshot].self, from: data)) ?? [:]
+  }
+
+  /// Awaits a condition by pumping the off-main actor flush onto the executor;
+  /// bounded so a never-true predicate can't hang the suite. No `Task.sleep`.
+  /// `megaYield` runs detached background work between checks so the writer
+  /// actor's flush actually lands even under a saturated cooperative pool.
+  private func waitUntil(_ predicate: () -> Bool) async {
+    for _ in 0..<200 {
+      if predicate() { return }
+      await Task.megaYield()
+    }
+  }
+
+  /// Yields enough for the latest debounce task to register its sleep with the
+  /// TestClock, then advances past the window so the flush fires.
+  private func settleThenAdvance(_ clock: TestClock<Duration>) async {
+    await Task.megaYield()
+    await clock.advance(by: .seconds(1))
+  }
+
+  private func makeWorktree(id: String = "/tmp/repo/wt-1") -> Worktree {
+    Worktree(
+      id: WorktreeID(id),
+      name: URL(fileURLWithPath: id).lastPathComponent,
+      detail: "detail",
+      workingDirectory: URL(fileURLWithPath: id),
+      repositoryRootURL: URL(fileURLWithPath: "/tmp/repo")
+    )
+  }
+
+  @Test func debounceCoalescesBurstIntoOneWrite() async {
+    let harness = makeHarness()
+    let worktree = makeWorktree()
+    let state = harness.manager.state(for: worktree)
+
+    // Several structural mutations within the window must coalesce to one flush.
+    _ = state.createTab(focusing: false)
+    _ = state.createTab(focusing: false)
+    _ = state.createTab(focusing: false)
+
+    #expect(harness.saveCount.value == 0)
+    await settleThenAdvance(harness.clock)
+    await waitUntil { harness.saveCount.value == 1 }
+    #expect(harness.saveCount.value == 1)
+    #expect(readDict(harness)[worktree.id.rawValue] != nil)
+  }
+
+  @Test func pruneDeletesAndCancelsQueuedSave() async {
+    let harness = makeHarness()
+    let worktree = makeWorktree()
+    let state = harness.manager.state(for: worktree)
+    _ = state.createTab(focusing: false)
+
+    // Seed disk with a prior snapshot so the delete has something to remove.
+    await settleThenAdvance(harness.clock)
+    await waitUntil { readDict(harness)[worktree.id.rawValue] != nil }
+
+    // Queue a positive save, then prune before the window elapses.
+    _ = state.createTab(focusing: false)
+    harness.manager.prune(keeping: [])
+    await waitUntil { readDict(harness)[worktree.id.rawValue] == nil }
+
+    // Pin the save count once the delete has flushed; a resurrecting positive
+    // write would bump it, so gating on a positive increment proves whether the
+    // queued save was actually cancelled rather than merely lagging.
+    let savesAfterDelete = harness.saveCount.value
+    await harness.clock.advance(by: .seconds(1))
+    await waitUntil { harness.saveCount.value > savesAfterDelete }
+    #expect(harness.saveCount.value == savesAfterDelete)
+    #expect(readDict(harness)[worktree.id.rawValue] == nil)
+  }
+
+  @Test func pruneAfterDebounceFiresDoesNotResurrect() async {
+    let harness = makeHarness()
+    let worktree = makeWorktree()
+    let state = harness.manager.state(for: worktree)
+    _ = state.createTab(focusing: false)
+
+    // Seed disk with a prior snapshot so the delete has something to remove.
+    await settleThenAdvance(harness.clock)
+    await waitUntil { readDict(harness)[worktree.id.rawValue] != nil }
+
+    // Arm the gate so the positive snapshot write blocks mid-flush, pinning the
+    // flush Task in-flight. Then queue the positive save and fire the debounce.
+    let release = DispatchSemaphore(value: 0)
+    let gatedID = worktree.id.rawValue
+    harness.gate.setValue((worktreeID: gatedID, semaphore: release))
+    _ = state.createTab(focusing: false)
+    await settleThenAdvance(harness.clock)
+
+    // The positive flush Task is provably suspended inside `writer.flush` (save
+    // blocked), so `layoutFlushTasks[id]` is still non-nil. Prune now captures
+    // that in-flight Task and must await it before deleting.
+    await waitUntil { harness.gateEngaged.value }
+    #expect(harness.gateEngaged.value)
+    harness.manager.prune(keeping: [])
+
+    // Release the positive flush; the delete chained behind it must win.
+    release.signal()
+    await waitUntil { readDict(harness)[worktree.id.rawValue] == nil }
+    #expect(readDict(harness)[worktree.id.rawValue] == nil)
+  }
+
+  @Test func cancelPendingLayoutSavesDropsQueuedFlush() async {
+    let harness = makeHarness()
+    let worktree = makeWorktree()
+    let state = harness.manager.state(for: worktree)
+    _ = state.createTab(focusing: false)
+
+    harness.manager.cancelPendingLayoutSaves()
+    await harness.clock.advance(by: .seconds(1))
+
+    // Queue and flush a control worktree's save AFTER the cancel. Once the
+    // control write lands, the executor has run long enough that the cancelled
+    // save would have fired too, so its continued absence proves suppression
+    // rather than mere lag.
+    let control = makeWorktree(id: "/tmp/repo/wt-control")
+    let controlState = harness.manager.state(for: control)
+    _ = controlState.createTab(focusing: false)
+    await settleThenAdvance(harness.clock)
+    await waitUntil { readDict(harness)[control.id.rawValue] != nil }
+
+    #expect(readDict(harness)[control.id.rawValue] != nil)
+    #expect(harness.saveCount.value == 1)
+    #expect(readDict(harness)[worktree.id.rawValue] == nil)
+  }
+
+  @Test func mergePreservesSiblingKeyWrittenByAnotherFlush() async {
+    let harness = makeHarness()
+    let wt1 = makeWorktree(id: "/tmp/repo/wt-1")
+    let wt2 = makeWorktree(id: "/tmp/repo/wt-2")
+
+    let state1 = harness.manager.state(for: wt1)
+    _ = state1.createTab(focusing: false)
+    await settleThenAdvance(harness.clock)
+    await waitUntil { readDict(harness)[wt1.id.rawValue] != nil }
+
+    let state2 = harness.manager.state(for: wt2)
+    _ = state2.createTab(focusing: false)
+    await settleThenAdvance(harness.clock)
+    await waitUntil { readDict(harness)[wt2.id.rawValue] != nil }
+
+    let dict = readDict(harness)
+    #expect(Set(dict.keys) == [wt1.id.rawValue, wt2.id.rawValue])
+  }
+
+  @Test func incrementalCaptureEmbedsLiveAgentRecords() async {
+    let harness = makeHarness()
+    let worktree = makeWorktree()
+    let state = harness.manager.state(for: worktree)
+    guard let tabID = state.createTab(focusing: false),
+      let surface = state.splitTree(for: tabID).root?.leftmostLeaf()
+    else {
+      Issue.record("Expected a tab and surface")
+      return
+    }
+    let record = TerminalLayoutSnapshot.SurfaceAgentRecord(agent: "claude", pids: [42], activity: "busy")
+    harness.manager.currentAgentsBySurface = { [surface.id: [record]] }
+    // Mark dirty again now that the agent reader is wired.
+    harness.manager.markLayoutDirty(worktreeID: worktree.id)
+
+    await settleThenAdvance(harness.clock)
+    await waitUntil { readDict(harness)[worktree.id.rawValue]?.tabs.first?.layout != nil }
+
+    let leaf = readDict(harness)[worktree.id.rawValue]?.tabs.first?.layout
+    guard case .leaf(let persisted) = leaf else {
+      Issue.record("Expected a leaf layout")
+      return
+    }
+    #expect(persisted.agents == [record])
+  }
+
+  @Test func presentButUnreadableFileAbortsAndPreservesSiblings() async {
+    let clock = TestClock()
+    let inner = SettingsFileStorage.inMemory()
+    let url = SupacodePaths.layoutsURL
+    // Flips on after the two siblings are seeded so the third flush's read fails
+    // with a non-absent error, exercising the abort branch.
+    let failLoad = LockIsolated(false)
+    let loadFailCount = LockIsolated(0)
+    let storage = SettingsFileStorage(
+      load: { target in
+        if target == url, failLoad.value {
+          loadFailCount.withValue { $0 += 1 }
+          throw CocoaError(.fileReadCorruptFile)
+        }
+        return try inner.load(target)
+      },
+      save: { data, target in try inner.save(data, target) }
+    )
+    let manager = withDependencies {
+      $0.settingsFileStorage = storage
+    } operation: {
+      WorktreeTerminalManager(runtime: GhosttyRuntime(), clock: clock)
+    }
+    manager.saveLayoutSnapshot = { _, _ in }
+
+    // Raw reader bypasses the throwing flag so assertions see the real disk state.
+    let readRaw: () -> [String: TerminalLayoutSnapshot] = {
+      guard let data = try? inner.load(url) else { return [:] }
+      return (try? JSONDecoder().decode([String: TerminalLayoutSnapshot].self, from: data)) ?? [:]
+    }
+
+    let wt1 = makeWorktree(id: "/tmp/repo/wt-1")
+    let wt2 = makeWorktree(id: "/tmp/repo/wt-2")
+    let state1 = manager.state(for: wt1)
+    _ = state1.createTab(focusing: false)
+    await Task.megaYield()
+    await clock.advance(by: .seconds(1))
+    await waitUntil { readRaw()[wt1.id.rawValue] != nil }
+    let state2 = manager.state(for: wt2)
+    _ = state2.createTab(focusing: false)
+    await Task.megaYield()
+    await clock.advance(by: .seconds(1))
+    await waitUntil { readRaw()[wt2.id.rawValue] != nil }
+    #expect(Set(readRaw().keys) == [wt1.id.rawValue, wt2.id.rawValue])
+
+    // Make the merge read fail, then flush a third key. The writer must abort
+    // rather than splice into an empty dict and clobber the two siblings.
+    failLoad.setValue(true)
+    let wt3 = makeWorktree(id: "/tmp/repo/wt-3")
+    let state3 = manager.state(for: wt3)
+    _ = state3.createTab(focusing: false)
+    await Task.megaYield()
+    await clock.advance(by: .seconds(1))
+    await waitUntil { loadFailCount.value > 0 }
+    #expect(loadFailCount.value > 0)
+
+    let dict = readRaw()
+    #expect(Set(dict.keys) == [wt1.id.rawValue, wt2.id.rawValue])
+    #expect(dict[wt3.id.rawValue] == nil)
+  }
+
+  @Test func renamePersistsCustomTitleIncrementally() async {
+    let harness = makeHarness()
+    let worktree = makeWorktree()
+    let state = harness.manager.state(for: worktree)
+    guard let tabID = state.createTab(focusing: false) else {
+      Issue.record("Expected a tab")
+      return
+    }
+    await settleThenAdvance(harness.clock)
+    await waitUntil { readDict(harness)[worktree.id.rawValue] != nil }
+
+    state.renameTab(tabID, title: "Renamed")
+    await settleThenAdvance(harness.clock)
+    await waitUntil { readDict(harness)[worktree.id.rawValue]?.tabs.first?.customTitle == "Renamed" }
+
+    #expect(readDict(harness)[worktree.id.rawValue]?.tabs.first?.customTitle == "Renamed")
+  }
+
+  @Test func onQuitFlushSyncPersistsLiveStatesAsTerminalWrite() {
+    let harness = makeHarness()
+    let wt1 = makeWorktree(id: "/tmp/repo/wt-1")
+    let wt2 = makeWorktree(id: "/tmp/repo/wt-2")
+    _ = harness.manager.state(for: wt1).createTab(focusing: false)
+    _ = harness.manager.state(for: wt2).createTab(focusing: false)
+
+    // Mirror the quit path: drop queued debounce saves, then the synchronous
+    // on-quit flush must land every live state as the terminal on-disk write.
+    harness.manager.cancelPendingLayoutSaves()
+    harness.manager.saveAllLayoutSnapshots()
+
+    #expect(Set(readDict(harness).keys) == [wt1.id.rawValue, wt2.id.rawValue])
+  }
+
+  @Test func capturedSnapshotRoundTripsThroughDisk() async {
+    let harness = makeHarness()
+    let worktree = makeWorktree()
+    let state = harness.manager.state(for: worktree)
+    _ = state.createTab(focusing: false)
+    _ = state.createTab(focusing: false)
+
+    await settleThenAdvance(harness.clock)
+    await waitUntil { readDict(harness)[worktree.id.rawValue] != nil }
+
+    let persisted = readDict(harness)[worktree.id.rawValue]
+    let inMemory = state.captureLayoutSnapshot()
+    #expect(persisted == inMemory)
+  }
+}
diff --git a/supacodeTests/WorktreeTerminalManagerReaperTests.swift b/supacodeTests/WorktreeTerminalManagerReaperTests.swift
new file mode 100644
index 000000000..91161cd54
--- /dev/null
+++ b/supacodeTests/WorktreeTerminalManagerReaperTests.swift
@@ -0,0 +1,118 @@
+import Dependencies
+import Foundation
+import Testing
+
+@testable import supacode
+
+@MainActor
+struct WorktreeTerminalManagerReaperTests {
+  /// Builds a manager whose injected zmx client records every kill and serves
+  /// the supplied `ls` listing (nil = probe failed).
+  private func makeManager(
+    listing: [ZmxSessionListParser.Entry]?,
+    killed: LockIsolated<[String]>
+  ) -> WorktreeTerminalManager {
+    withDependencies {
+      $0.zmxClient = ZmxClient(
+        executableURL: { nil },
+        isBundled: { true },
+        killSession: { id in killed.withValue { $0.append(id) } },
+        listSessionsWithClients: { listing }
+      )
+    } operation: {
+      WorktreeTerminalManager(runtime: GhosttyRuntime())
+    }
+  }
+
+  private func session(for surfaceID: UUID) -> String {
+    ZmxSessionID.make(surfaceID: surfaceID)
+  }
+
+  @Test func reapSparesAttachedOrphanEvenWhenUnknown() async {
+    let attached = UUID()
+    let idle = UUID()
+    let killed = LockIsolated<[String]>([])
+    let manager = makeManager(
+      listing: [
+        .init(name: session(for: attached), clients: 1),
+        .init(name: session(for: idle), clients: 0),
+      ],
+      killed: killed
+    )
+
+    await manager.reapOrphanSessions(knownSurfaceIDs: [])
+
+    #expect(killed.value == [session(for: idle)])
+  }
+
+  @Test func reapSkipsErrAndUnreachableSessions() async {
+    let unreachable = UUID()
+    let killed = LockIsolated<[String]>([])
+    let manager = makeManager(
+      listing: [.init(name: session(for: unreachable), clients: nil)],
+      killed: killed
+    )
+
+    await manager.reapOrphanSessions(knownSurfaceIDs: [])
+
+    #expect(killed.value.isEmpty)
+  }
+
+  @Test func reapKillsNothingWhenProbeUnavailable() async {
+    let idle = UUID()
+    let killed = LockIsolated<[String]>([])
+    let manager = makeManager(listing: nil, killed: killed)
+
+    await manager.reapOrphanSessions(knownSurfaceIDs: [idle])
+
+    #expect(killed.value.isEmpty)
+  }
+
+  @Test func terminateKillsTrackedEvenWithLiveClientsButSparesUntrackedInUse() async {
+    let killed = LockIsolated<[String]>([])
+    let listing = LockIsolated<[ZmxSessionListParser.Entry]?>([])
+    let manager = withDependencies {
+      $0.zmxClient = ZmxClient(
+        executableURL: { nil },
+        isBundled: { true },
+        killSession: { id in killed.withValue { $0.append(id) } },
+        listSessionsWithClients: { listing.value }
+      )
+    } operation: {
+      WorktreeTerminalManager(runtime: GhosttyRuntime())
+    }
+
+    let worktree = makeWorktree()
+    let state = manager.state(for: worktree)
+    guard let tabID = state.createTab(focusing: false),
+      let surface = state.splitTree(for: tabID).root?.leftmostLeaf()
+    else {
+      Issue.record("Expected a tab and surface")
+      return
+    }
+    let trackedSurfaceID = surface.id
+    let trackedSession = session(for: trackedSurfaceID)
+    let untrackedSession = session(for: UUID())
+    // The tracked session reports clients>0 (must still die) and an untracked
+    // session is in use (must be spared).
+    listing.setValue([
+      .init(name: trackedSession, clients: 2),
+      .init(name: untrackedSession, clients: 3),
+    ])
+
+    await manager.terminateAllSessions()
+
+    #expect(killed.value == [trackedSession])
+  }
+
+  private func makeWorktree(id: String = "/tmp/repo/wt-1") -> Worktree {
+    let name = URL(fileURLWithPath: id).lastPathComponent
+    return Worktree(
+      id: WorktreeID(id),
+      name: name,
+      detail: "detail",
+      workingDirectory: URL(fileURLWithPath: id),
+      repositoryRootURL: URL(fileURLWithPath: "/tmp/repo")
+    )
+  }
+}
diff --git a/supacodeTests/WorktreeTerminalManagerTests.swift b/supacodeTests/WorktreeTerminalManagerTests.swift
index bb8e0b999..143ab5a9a 100644
--- a/supacodeTests/WorktreeTerminalManagerTests.swift
+++ b/supacodeTests/WorktreeTerminalManagerTests.swift
@@ -142,7 +142,7 @@ struct WorktreeTerminalManagerTests {
     #expect(state.socketPath == nil)
   }
 
-  @Test func socketActivityEventRoutesToDecodedWorktreeState() async {
+  @Test func oscHookActivityEventRoutesToWorktreeState() async {
     let server = AgentHookSocketServer()
     let (manager, presence) = WorktreeTerminalManager.withPresenceHarness(socketServer: server)
     let worktree = makeWorktree(id: "/tmp/repo/wt with spaces")
@@ -157,14 +157,14 @@ struct WorktreeTerminalManagerTests {
       return
     }
 
-    server.onEvent?(makeHookEvent(.sessionStart, surfaceID: surface.id, pid: getpid()))
-    server.onEvent?(makeHookEvent(.busy, surfaceID: surface.id))
+    state.onAgentHookEvent?(makeHookEvent(.sessionStart, surfaceID: surface.id, pid: getpid()))
+    state.onAgentHookEvent?(makeHookEvent(.busy, surfaceID: surface.id))
     await presence.drain()
 
     #expect(presence.state.hasActivity(in: [surface.id]))
   }
 
-  @Test func socketIdleEventIsDebouncedAcrossToolStorm() async {
+  @Test func oscIdleEventIsDebouncedAcrossToolStorm() async {
     let clock = TestClock()
     let server = AgentHookSocketServer()
     let (manager, presence) = WorktreeTerminalManager.withPresenceHarness(socketServer: server, clock: clock)
@@ -179,23 +179,23 @@ struct WorktreeTerminalManagerTests {
       return
     }
 
-    server.onEvent?(makeHookEvent(.sessionStart, surfaceID: surface.id, pid: getpid()))
-    server.onEvent?(makeHookEvent(.busy, surfaceID: surface.id))
+    state.onAgentHookEvent?(makeHookEvent(.sessionStart, surfaceID: surface.id, pid: getpid()))
+    state.onAgentHookEvent?(makeHookEvent(.busy, surfaceID: surface.id))
     await presence.drain()
     #expect(presence.state.hasActivity(in: [surface.id]))
 
-    server.onEvent?(makeHookEvent(.idle, surfaceID: surface.id))
+    state.onAgentHookEvent?(makeHookEvent(.idle, surfaceID: surface.id))
     await clock.advance(by: .milliseconds(100))
     await presence.drain()
     #expect(presence.state.hasActivity(in: [surface.id]))
 
-    server.onEvent?(makeHookEvent(.busy, surfaceID: surface.id))
+    state.onAgentHookEvent?(makeHookEvent(.busy, surfaceID: surface.id))
     await clock.advance(by: .milliseconds(500))
     await presence.drain()
     #expect(presence.state.hasActivity(in: [surface.id]))
   }
 
-  @Test func socketIdleCommitsAfterDebounceWindow() async {
+  @Test func oscIdleCommitsAfterDebounceWindow() async {
     let clock = TestClock()
     let server = AgentHookSocketServer()
     let (manager, presence) = WorktreeTerminalManager.withPresenceHarness(socketServer: server, clock: clock)
@@ -210,9 +210,9 @@ struct WorktreeTerminalManagerTests {
       return
     }
 
-    server.onEvent?(makeHookEvent(.sessionStart, surfaceID: surface.id, pid: getpid()))
-    server.onEvent?(makeHookEvent(.busy, surfaceID: surface.id))
-    server.onEvent?(makeHookEvent(.idle, surfaceID: surface.id))
+    state.onAgentHookEvent?(makeHookEvent(.sessionStart, surfaceID: surface.id, pid: getpid()))
+    state.onAgentHookEvent?(makeHookEvent(.busy, surfaceID: surface.id))
+    state.onAgentHookEvent?(makeHookEvent(.idle, surfaceID: surface.id))
 
     await clock.advance(by: .milliseconds(399))
     await presence.drain()
@@ -223,7 +223,7 @@ struct WorktreeTerminalManagerTests {
     #expect(!presence.state.hasActivity(in: [surface.id]))
   }
 
-  @Test func socketIdleDebouncesPerAgentIndependently() async {
+  @Test func oscIdleDebouncesPerAgentIndependently() async {
     let clock = TestClock()
     let server = AgentHookSocketServer()
     let (manager, presence) = WorktreeTerminalManager.withPresenceHarness(socketServer: server, clock: clock)
@@ -238,13 +238,13 @@ struct WorktreeTerminalManagerTests {
       return
     }
 
-    server.onEvent?(makeHookEvent(.sessionStart, agent: .claude, surfaceID: surface.id, pid: getpid()))
-    server.onEvent?(makeHookEvent(.sessionStart, agent: .codex, surfaceID: surface.id, pid: getpid()))
-    server.onEvent?(makeHookEvent(.busy, agent: .claude, surfaceID: surface.id))
-    server.onEvent?(makeHookEvent(.busy, agent: .codex, surfaceID: surface.id))
+    state.onAgentHookEvent?(makeHookEvent(.sessionStart, agent: .claude, surfaceID: surface.id, pid: getpid()))
+    state.onAgentHookEvent?(makeHookEvent(.sessionStart, agent: .codex, surfaceID: surface.id, pid: getpid()))
+    state.onAgentHookEvent?(makeHookEvent(.busy, agent: .claude, surfaceID: surface.id))
+    state.onAgentHookEvent?(makeHookEvent(.busy, agent: .codex, surfaceID: surface.id))
 
     // Codex idles; Claude stays busy. After window, only Codex should commit idle.
-    server.onEvent?(makeHookEvent(.idle, agent: .codex, surfaceID: surface.id))
+    state.onAgentHookEvent?(makeHookEvent(.idle, agent: .codex, surfaceID: surface.id))
     await clock.advance(by: .milliseconds(400))
 
     await presence.drain()
@@ -256,7 +256,7 @@ struct WorktreeTerminalManagerTests {
     #expect(presence.state.hasActivity(in: [surface.id]))
   }
 
-  @Test func socketSessionEndCancelsPendingIdle() async {
+  @Test func oscSessionEndCancelsPendingIdle() async {
     let clock = TestClock()
     let server = AgentHookSocketServer()
     let (manager, presence) = WorktreeTerminalManager.withPresenceHarness(socketServer: server, clock: clock)
@@ -272,10 +272,10 @@ struct WorktreeTerminalManagerTests {
     }
 
     let pid = getpid()
-    server.onEvent?(makeHookEvent(.sessionStart, surfaceID: surface.id, pid: pid))
-    server.onEvent?(makeHookEvent(.busy, surfaceID: surface.id))
-    server.onEvent?(makeHookEvent(.idle, surfaceID: surface.id))
-    server.onEvent?(makeHookEvent(.sessionEnd, surfaceID: surface.id, pid: pid))
+    state.onAgentHookEvent?(makeHookEvent(.sessionStart, surfaceID: surface.id, pid: pid))
+    state.onAgentHookEvent?(makeHookEvent(.busy, surfaceID: surface.id))
+    state.onAgentHookEvent?(makeHookEvent(.idle, surfaceID: surface.id))
+    state.onAgentHookEvent?(makeHookEvent(.sessionEnd, surfaceID: surface.id, pid: pid))
 
     await clock.advance(by: .milliseconds(500))
     await presence.drain()
@@ -284,7 +284,7 @@ struct WorktreeTerminalManagerTests {
     #expect(!presence.state.hasActivity(in: [surface.id]))
   }
 
-  @Test func socketSurfaceClosedWhileIdlePendingIsHarmless() async {
+  @Test func oscSurfaceClosedWhileIdlePendingIsHarmless() async {
     let clock = TestClock()
     let server = AgentHookSocketServer()
     let (manager, presence) = WorktreeTerminalManager.withPresenceHarness(socketServer: server, clock: clock)
@@ -299,10 +299,13 @@ struct WorktreeTerminalManagerTests {
       return
     }
 
-    server.onEvent?(makeHookEvent(.sessionStart, surfaceID: surface.id, pid: getpid()))
-    server.onEvent?(makeHookEvent(.busy, surfaceID: surface.id))
-    server.onEvent?(makeHookEvent(.idle, surfaceID: surface.id))
+    state.onAgentHookEvent?(makeHookEvent(.sessionStart, surfaceID: surface.id, pid: getpid()))
+    state.onAgentHookEvent?(makeHookEvent(.busy, surfaceID: surface.id))
+    state.onAgentHookEvent?(makeHookEvent(.idle, surfaceID: surface.id))
 
+    // Settle the stream-delivered events before the direct close so a buffered
+    // busy can't resurrect activity after the surface is gone.
+    await presence.drain()
     presence.send(.surfaceClosed(surface.id))
     await clock.advance(by: .milliseconds(500))
     await presence.drain()
@@ -310,31 +313,27 @@ struct WorktreeTerminalManagerTests {
     #expect(!presence.state.hasActivity(in: [surface.id]))
   }
 
-  @Test func socketNotificationRoutesToDecodedWorktreeState() {
+  @Test func oscHookNotificationLandsInWorktreeState() {
     withDependencies {
       $0.date.now = Date(timeIntervalSince1970: 1_234)
+      $0.continuousClock = ImmediateClock()
     } operation: {
-      let server = AgentHookSocketServer()
-      let manager = WorktreeTerminalManager(runtime: GhosttyRuntime(), socketServer: server)
+      let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
       let worktree = makeWorktree(id: "/tmp/repo/wt with spaces")
 
       manager.handleCommand(.runBlockingScript(worktree, kind: .archive, script: "echo ok"))
 
       guard let state = manager.stateIfExists(for: worktree.id),
         let tabId = state.tabManager.selectedTabId,
-        let surface = state.splitTree(for: tabId).root?.leftmostLeaf(),
-        let encodedID = worktree.id.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed)
+        let surface = state.splitTree(for: tabId).root?.leftmostLeaf()
       else {
-        Issue.record("Expected blocking script tab and socket server")
+        Issue.record("Expected blocking script tab")
         return
       }
 
-      server.onNotification?(
-        encodedID,
-        tabId.rawValue,
-        surface.id,
-        AgentHookNotification(agent: "codex", event: "Stop", title: "Done", body: "All complete")
-      )
+      // The OSC notify path decodes + sanitizes app-side, then appends to the
+      // surface's worktree state via this same entry point.
+      state.appendHookNotification(title: "Done", body: "All complete", surfaceID: surface.id)
 
       #expect(
         state.notifications.contains {
@@ -519,6 +518,38 @@ struct WorktreeTerminalManagerTests {
     #expect(manager.hasUnseenNotifications(for: worktree.id) == false)
   }
 
+  @Test func dismissAllNotificationsRefreshesRowWhenAllAlreadyRead() {
+    // Repro of the stuck-toolbar-bell bug: dismissing already-read notifications
+    // flips no unseen flag, so the gated indicator emit used to skip the row
+    // projection refresh and the bell stayed showing them. Dismiss must signal
+    // unconditionally so the sidebar row's `notifications` array (which the bell
+    // group-existence check reads) clears.
+    let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
+    let state = manager.state(for: makeWorktree())
+    state.setNotificationsForTesting([makeNotification(isRead: true), makeNotification(isRead: true)])
+    var indicatorEmits = 0
+    state.onNotificationIndicatorChanged = { indicatorEmits += 1 }
+
+    state.dismissAllNotifications()
+
+    #expect(state.notifications.isEmpty)
+    #expect(indicatorEmits == 1)
+  }
+
+  @Test func dismissReadNotificationRefreshesRow() {
+    let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
+    let state = manager.state(for: makeWorktree())
+    let read = makeNotification(isRead: true)
+    state.setNotificationsForTesting([read])
+    var indicatorEmits = 0
+    state.onNotificationIndicatorChanged = { indicatorEmits += 1 }
+
+    state.dismissNotification(read.id)
+
+    #expect(state.notifications.isEmpty)
+    #expect(indicatorEmits == 1)
+  }
+
   // MARK: - Per-surface unseen flag
 
   @Test func setNotificationsForTestingHydratesPerSurfaceFlag() {
@@ -613,6 +644,7 @@ struct WorktreeTerminalManagerTests {
   @Test func appendNotificationFlipsPerSurfaceFlagOnArrival() {
     withDependencies {
       $0.date.now = Date(timeIntervalSince1970: 1_234)
+      $0.continuousClock = ImmediateClock()
     } operation: {
       let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
       let worktree = makeWorktree()
@@ -633,6 +665,7 @@ struct WorktreeTerminalManagerTests {
   @Test func appendNotificationDoesNotFlipFlagWhenFocusedAndSelected() {
     withDependencies {
       $0.date.now = Date(timeIntervalSince1970: 1_234)
+      $0.continuousClock = ImmediateClock()
     } operation: {
       let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
       let worktree = makeWorktree()
@@ -683,6 +716,417 @@ struct WorktreeTerminalManagerTests {
     #expect(state.surfaceStates[surfaceID] == nil)
   }
 
+  @Test func closeAllSurfacesClearsPerSurfaceBookkeeping() {
+    withDependencies {
+      $0.date.now = Date(timeIntervalSince1970: 1_234)
+      $0.continuousClock = ImmediateClock()
+    } operation: {
+      let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
+      let worktree = makeWorktree()
+      let state = manager.state(for: worktree)
+      guard let tabId = state.createTab(focusing: false),
+        let surface = state.splitTree(for: tabId).root?.leftmostLeaf()
+      else {
+        Issue.record("Expected a tab and surface")
+        return
+      }
+      let surfaceID = surface.id
+      state.appendHookNotification(title: "done", body: "exit 0", surfaceID: surfaceID)
+      #expect(state.surfaceStates[surfaceID] != nil)
+      #expect(state.debugCustomNotificationTimestampCount == 1)
+
+      state.closeAllSurfaces()
+
+      #expect(state.allSurfaceIDs.isEmpty)
+      #expect(state.surfaceStates[surfaceID] == nil)
+      #expect(state.debugCustomNotificationTimestampCount == 0)
+    }
+  }
+
+  @Test func pruneKeepsStatesAndSessionsOwnedByProtectedRepositoryIDs() async {
+    let probe = ZmxTestProbe(listing: [])
+    let manager = makeZmxBackedManager(probe: probe)
+    let activeWorktree = Worktree(
+      id: WorktreeID("/tmp/active-repo/wt-1"),
+      name: "wt-1",
+      detail: "",
+      workingDirectory: URL(fileURLWithPath: "/tmp/active-repo/wt-1"),
+      repositoryRootURL: URL(fileURLWithPath: "/tmp/active-repo"),
+    )
+    let failedRepoWorktree = Worktree(
+      id: WorktreeID("/tmp/failed-repo/wt-1"),
+      name: "wt-1",
+      detail: "",
+      workingDirectory: URL(fileURLWithPath: "/tmp/failed-repo/wt-1"),
+      repositoryRootURL: URL(fileURLWithPath: "/tmp/failed-repo"),
+    )
+    let removedWorktree = Worktree(
+      id: WorktreeID("/tmp/removed-repo/wt-1"),
+      name: "wt-1",
+      detail: "",
+      workingDirectory: URL(fileURLWithPath: "/tmp/removed-repo/wt-1"),
+      repositoryRootURL: URL(fileURLWithPath: "/tmp/removed-repo"),
+    )
+    _ = manager.state(for: activeWorktree).createTab()
+    let failedState = manager.state(for: failedRepoWorktree)
+    let removedState = manager.state(for: removedWorktree)
+    guard let failedTabID = failedState.createTab(),
+      let failedSurfaceID = failedState.splitTree(for: failedTabID).root?.leftmostLeaf().id,
+      let removedTabID = removedState.createTab(),
+      let removedSurfaceID = removedState.splitTree(for: removedTabID).root?.leftmostLeaf().id
+    else {
+      Issue.record("Expected protected and removed surfaces")
+      return
+    }
+    let failedRepositoryID = RepositoryID(
+      failedRepoWorktree.repositoryRootURL.standardizedFileURL.path(percentEncoded: false)
+    )
+
+    manager.prune(
+      keeping: [activeWorktree.id],
+      protectingRepositoryIDs: [failedRepositoryID]
+    )
+
+    #expect(manager.stateIfExists(for: activeWorktree.id) != nil)
+    #expect(manager.stateIfExists(for: failedRepoWorktree.id) != nil)
+    #expect(manager.stateIfExists(for: removedWorktree.id) == nil)
+    #expect(failedState.hasSurface(failedSurfaceID, in: failedTabID))
+    let removedSession = session(for: removedSurfaceID)
+    await probe.waitForKill { $0.contains(removedSession) }
+    let killed = await probe.killedSessions()
+    #expect(killed.contains(session(for: removedSurfaceID)))
+    #expect(!killed.contains(session(for: failedSurfaceID)))
+  }
+
+  @Test func unexpectedExitedZmxSurfaceWithLiveSessionReattachesAndKeepsTab() async {
+    let probe = ZmxTestProbe(listing: [])
+    let manager = makeZmxBackedManager(probe: probe)
+    let state = manager.state(for: makeWorktree())
+    guard let tabId = state.createTab(focusing: true),
+      let surface = state.splitTree(for: tabId).root?.leftmostLeaf()
+    else {
+      Issue.record("Expected a tab and surface")
+      return
+    }
+    let surfaceID = surface.id
+    let originalSurfaceState = state.surfaceStates[surfaceID]
+    let projections = LockIsolated<[WorktreeTabProjection]>([])
+    state.onTabProjectionChanged = { projection in
+      projections.withValue { $0.append(projection) }
+    }
+    await probe.setListing([.init(name: session(for: surfaceID), clients: 0)])
+
+    surface.bridge.closeSurface(processAlive: false)
+    await probe.waitForListCalls(atLeast: 1)
+    await waitUntil("zmx surface replacement") {
+      guard let replacement = state.splitTree(for: tabId).root?.leftmostLeaf() else { return false }
+      return replacement.id == surfaceID && replacement !== surface
+    }
+
+    #expect(state.tabManager.tabs.contains(where: { $0.id == tabId }))
+    guard let replacement = state.splitTree(for: tabId).root?.leftmostLeaf() else {
+      Issue.record("Expected a replacement surface")
+      return
+    }
+    #expect(replacement.id == surfaceID)
+    #expect(replacement !== surface)
+    #expect(replacement.shouldClaimFocus?() == true)
+    #expect(surface.shouldClaimFocus?() == false)
+    #expect(state.surfaceStates[surfaceID] === originalSurfaceState)
+    #expect(projections.value.last?.surfaceGeneration == 1)
+    #expect(await probe.killedSessions() == [])
+  }
+
+  @Test func unexpectedDetachedZmxSurfaceWithLiveSessionReattachesAndKeepsTab() async {
+    let probe = ZmxTestProbe(listing: [])
+    let manager = makeZmxBackedManager(probe: probe)
+    let state = manager.state(for: makeWorktree())
+    guard let tabId = state.createTab(focusing: true),
+      let surface = state.splitTree(for: tabId).root?.leftmostLeaf()
+    else {
+      Issue.record("Expected a tab and surface")
+      return
+    }
+    let surfaceID = surface.id
+    await probe.setListing([.init(name: session(for: surfaceID), clients: 0)])
+
+    surface.bridge.closeSurface(processAlive: true)
+    await probe.waitForListCalls(atLeast: 1)
+    await waitUntil("detached zmx surface replacement") {
+      guard let replacement = state.splitTree(for: tabId).root?.leftmostLeaf() else { return false }
+      return replacement.id == surfaceID && replacement !== surface
+    }
+
+    #expect(state.tabManager.tabs.contains(where: { $0.id == tabId }))
+    guard let replacement = state.splitTree(for: tabId).root?.leftmostLeaf() else {
+      Issue.record("Expected a replacement surface")
+      return
+    }
+    #expect(replacement.id == surfaceID)
+    #expect(replacement !== surface)
+    #expect(await probe.killedSessions() == [])
+  }
+
+  @Test func unexpectedDetachedZmxSurfaceInSplitReattachesOnlyThatPane() async {
+    let probe = ZmxTestProbe(listing: [])
+    let manager = makeZmxBackedManager(probe: probe)
+    let state = manager.state(for: makeWorktree())
+    guard let tabId = state.createTab(focusing: true),
+      let initialSurface = state.splitTree(for: tabId).root?.leftmostLeaf()
+    else {
+      Issue.record("Expected a tab and surface")
+      return
+    }
+    #expect(state.performSplitAction(.newSplit(direction: .right), for: initialSurface.id))
+    let originalLeaves = state.splitTree(for: tabId).leaves()
+    guard originalLeaves.count == 2 else {
+      Issue.record("Expected a split tab")
+      return
+    }
+    let target = originalLeaves[0]
+    let sibling = originalLeaves[1]
+    let targetID = target.id
+    let siblingID = sibling.id
+    await probe.setListing([.init(name: session(for: targetID), clients: 0)])
+
+    target.bridge.closeSurface(processAlive: true)
+    await probe.waitForListCalls(atLeast: 1)
+    await waitUntil("split zmx surface replacement") {
+      let leaves = state.splitTree(for: tabId).leaves()
+      guard leaves.count == 2 else { return false }
+      let replacement = leaves.first { $0.id == targetID }
+      return replacement != nil
+        && replacement !== target
+        && leaves.contains { $0 === sibling }
+    }
+
+    #expect(state.tabManager.tabs.contains(where: { $0.id == tabId }))
+    let leaves = state.splitTree(for: tabId).leaves()
+    #expect(leaves.count == 2)
+    #expect(Set(leaves.map(\.id)) == [targetID, siblingID])
+    #expect(leaves.contains { $0 === sibling })
+    #expect(await probe.killedSessions() == [])
+  }
+
+  @Test func ghosttyOriginatedCloseSurfaceInSplitWithAttachedClientClosesPaneSparingSession() async {
+    let probe = ZmxTestProbe(listing: [])
+    let manager = makeZmxBackedManager(probe: probe)
+    let state = manager.state(for: makeWorktree())
+    guard let tabId = state.createTab(focusing: true),
+      let initialSurface = state.splitTree(for: tabId).root?.leftmostLeaf()
+    else {
+      Issue.record("Expected a tab and surface")
+      return
+    }
+    #expect(state.performSplitAction(.newSplit(direction: .right), for: initialSurface.id))
+    let originalLeaves = state.splitTree(for: tabId).leaves()
+    guard originalLeaves.count == 2 else {
+      Issue.record("Expected a split tab")
+      return
+    }
+    let target = originalLeaves[0]
+    let sibling = originalLeaves[1]
+    let targetID = target.id
+    let siblingID = sibling.id
+    await probe.setListing([.init(name: session(for: targetID), clients: 1)])
+
+    target.bridge.closeSurface(processAlive: true)
+    await probe.waitForListCalls(atLeast: 1)
+    await waitUntil("split pane closes") {
+      let leaves = state.splitTree(for: tabId).leaves()
+      return leaves.count == 1 && leaves.first.map { $0 === sibling } == true
+    }
+
+    #expect(state.tabManager.tabs.contains(where: { $0.id == tabId }))
+    let leaves = state.splitTree(for: tabId).leaves()
+    #expect(leaves.map(\.id) == [siblingID])
+    #expect(leaves.first.map { $0 === sibling } == true)
+    // Another client is attached (clients == 1), so the shared session must survive.
+    #expect(await probe.killedSessions() == [])
+  }
+
+  @Test func staleOldSurfaceCallbacksAreIgnoredAfterZmxReattach() async {
+    let probe = ZmxTestProbe(listing: [])
+    let manager = makeZmxBackedManager(probe: probe)
+    let state = manager.state(for: makeWorktree())
+    let toggled = LockIsolated(false)
+    state.onCommandPaletteToggle = {
+      toggled.setValue(true)
+    }
+    guard let tabId = state.createTab(focusing: true),
+      let surface = state.splitTree(for: tabId).root?.leftmostLeaf()
+    else {
+      Issue.record("Expected a tab and surface")
+      return
+    }
+    let surfaceID = surface.id
+    await probe.setListing([.init(name: session(for: surfaceID), clients: 0)])
+
+    surface.bridge.closeSurface(processAlive: false)
+    await probe.waitForListCalls(atLeast: 1)
+    await waitUntil("zmx surface replacement") {
+      guard let replacement = state.splitTree(for: tabId).root?.leftmostLeaf() else { return false }
+      return replacement !== surface
+    }
+
+    #expect(surface.bridge.onCommandPaletteToggle?() == false)
+    #expect(toggled.value == false)
+  }
+
+  @Test func unexpectedExitedZmxSurfaceWithoutLiveSessionClosesAndKillsSession() async {
+    let probe = ZmxTestProbe(listing: [])
+    let manager = makeZmxBackedManager(probe: probe)
+    let state = manager.state(for: makeWorktree())
+    guard let tabId = state.createTab(focusing: false),
+      let surface = state.splitTree(for: tabId).root?.leftmostLeaf()
+    else {
+      Issue.record("Expected a tab and surface")
+      return
+    }
+    let surfaceID = surface.id
+
+    let expectedKill = session(for: surfaceID)
+    surface.bridge.closeSurface(processAlive: false)
+    await probe.waitForListCalls(atLeast: 1)
+    await probe.waitForKill { $0.contains(expectedKill) }
+    let killed = await probe.killedSessions()
+    await waitUntil("zmx surface tab closes") {
+      !state.tabManager.tabs.contains(where: { $0.id == tabId })
+    }
+
+    #expect(!state.tabManager.tabs.contains(where: { $0.id == tabId }))
+    #expect(state.surfaceStates[surfaceID] == nil)
+    #expect(killed == [session(for: surfaceID)])
+  }
+
+  @Test func unexpectedExitedZmxSurfaceWithUnavailableProbeClosesWithoutKillingSession() async {
+    let probe = ZmxTestProbe(listing: nil)
+    let manager = makeZmxBackedManager(probe: probe)
+    let state = manager.state(for: makeWorktree())
+    guard let tabId = state.createTab(focusing: false),
+      let surface = state.splitTree(for: tabId).root?.leftmostLeaf()
+    else {
+      Issue.record("Expected a tab and surface")
+      return
+    }
+    let surfaceID = surface.id
+
+    surface.bridge.closeSurface(processAlive: false)
+    await probe.waitForListCalls(atLeast: 1)
+    await waitUntil("zmx surface tab closes") {
+      !state.tabManager.tabs.contains(where: { $0.id == tabId })
+    }
+
+    #expect(!state.tabManager.tabs.contains(where: { $0.id == tabId }))
+    #expect(state.surfaceStates[surfaceID] == nil)
+    #expect(await probe.killedSessions() == [])
+  }
+
+  @Test func unexpectedExitedZmxSurfaceWithUnknownClientCountClosesWithoutKillingSession() async {
+    let probe = ZmxTestProbe(listing: [])
+    let manager = makeZmxBackedManager(probe: probe)
+    let state = manager.state(for: makeWorktree())
+    guard let tabId = state.createTab(focusing: false),
+      let surface = state.splitTree(for: tabId).root?.leftmostLeaf()
+    else {
+      Issue.record("Expected a tab and surface")
+      return
+    }
+    let surfaceID = surface.id
+    await probe.setListing([.init(name: session(for: surfaceID), clients: nil)])
+
+    surface.bridge.closeSurface(processAlive: false)
+    await probe.waitForListCalls(atLeast: 1)
+    await waitUntil("zmx surface tab closes") {
+      !state.tabManager.tabs.contains(where: { $0.id == tabId })
+    }
+
+    #expect(!state.tabManager.tabs.contains(where: { $0.id == tabId }))
+    #expect(state.surfaceStates[surfaceID] == nil)
+    #expect(await probe.killedSessions() == [])
+  }
+
+  @Test func explicitExitedZmxSurfaceCloseDoesNotRecoverLiveSession() async {
+    let probe = ZmxTestProbe(listing: [])
+    let manager = makeZmxBackedManager(probe: probe)
+    let state = manager.state(for: makeWorktree())
+    guard let tabId = state.createTab(focusing: false),
+      let surface = state.splitTree(for: tabId).root?.leftmostLeaf()
+    else {
+      Issue.record("Expected a tab and surface")
+      return
+    }
+    let surfaceID = surface.id
+    await probe.setListing([.init(name: session(for: surfaceID), clients: 1)])
+
+    let expectedKill = session(for: surfaceID)
+    #expect(state.closeSurface(id: surfaceID))
+    surface.bridge.closeSurface(processAlive: false)
+    await probe.waitForKill { $0.contains(expectedKill) }
+    let killed = await probe.killedSessions()
+    await waitUntil("explicit zmx surface tab closes") {
+      !state.tabManager.tabs.contains(where: { $0.id == tabId })
+    }
+
+    #expect(!state.tabManager.tabs.contains(where: { $0.id == tabId }))
+    #expect(state.surfaceStates[surfaceID] == nil)
+    #expect(killed == [session(for: surfaceID)])
+    #expect(await probe.listCallCount() == 0)
+  }
+
+  @Test func closeSurfaceBindingActionDoesNotRecoverLiveSession() async {
+    let probe = ZmxTestProbe(listing: [])
+    let manager = makeZmxBackedManager(probe: probe)
+    let state = manager.state(for: makeWorktree())
+    guard let tabId = state.createTab(focusing: false),
+      let surface = state.splitTree(for: tabId).root?.leftmostLeaf()
+    else {
+      Issue.record("Expected a tab and surface")
+      return
+    }
+    let surfaceID = surface.id
+    await probe.setListing([.init(name: session(for: surfaceID), clients: 1)])
+
+    let expectedKill = session(for: surfaceID)
+    #expect(state.performBindingAction("close_surface", onSurfaceID: surfaceID))
+    surface.bridge.closeSurface(processAlive: false)
+    await probe.waitForKill { $0.contains(expectedKill) }
+    let killed = await probe.killedSessions()
+    await waitUntil("binding-closed zmx surface tab closes") {
+      !state.tabManager.tabs.contains(where: { $0.id == tabId })
+    }
+
+    #expect(!state.tabManager.tabs.contains(where: { $0.id == tabId }))
+    #expect(state.surfaceStates[surfaceID] == nil)
+    #expect(killed == [session(for: surfaceID)])
+    #expect(await probe.listCallCount() == 0)
+  }
+
+  @Test func bypassZmxSurfaceExitKeepsCloseOnExitBehavior() async {
+    let probe = ZmxTestProbe(listing: [])
+    let manager = makeZmxBackedManager(probe: probe)
+    let worktree = makeWorktree()
+    let state = manager.state(for: worktree)
+    manager.handleCommand(.runBlockingScript(worktree, kind: .archive, script: "echo ok"))
+    guard let tabId = state.tabManager.selectedTabId,
+      let surface = state.splitTree(for: tabId).root?.leftmostLeaf()
+    else {
+      Issue.record("Expected a blocking-script tab and surface")
+      return
+    }
+    let surfaceID = surface.id
+    await probe.setListing([.init(name: session(for: surfaceID), clients: 1)])
+
+    surface.bridge.closeSurface(processAlive: false)
+    await waitUntil("bypass-zmx tab closes") {
+      !state.tabManager.tabs.contains(where: { $0.id == tabId })
+    }
+
+    #expect(!state.tabManager.tabs.contains(where: { $0.id == tabId }))
+    #expect(state.surfaceStates[surfaceID] == nil)
+    #expect(await probe.listCallCount() == 0)
+  }
+
   @Test func restoreLayoutSnapshotReDerivesPerSurfaceFlags() {
     let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
     let worktree = makeWorktree()
@@ -723,6 +1167,7 @@ struct WorktreeTerminalManagerTests {
   @Test func notificationsDisabledSkipsPerSurfaceFlag() {
     withDependencies {
       $0.date.now = Date(timeIntervalSince1970: 1_234)
+      $0.continuousClock = ImmediateClock()
     } operation: {
       let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
       let worktree = makeWorktree()
@@ -1237,7 +1682,7 @@ struct WorktreeTerminalManagerTests {
       return
     }
 
-    guard let tabs = manager.listTabs(worktreeID: worktree.id) else {
+    guard let tabs = manager.listTabs(worktreeID: worktree.id.rawValue) else {
       Issue.record("Expected non-nil tabs result")
       return
     }
@@ -1267,7 +1712,7 @@ struct WorktreeTerminalManagerTests {
       return
     }
 
-    guard let surfaces = manager.listSurfaces(worktreeID: worktree.id, tabID: tabID.rawValue.uuidString) else {
+    guard let surfaces = manager.listSurfaces(worktreeID: worktree.id.rawValue, tabID: tabID.rawValue.uuidString) else {
       Issue.record("Expected non-nil surfaces result")
       return
     }
@@ -1291,7 +1736,7 @@ struct WorktreeTerminalManagerTests {
     let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
     let worktree = makeWorktree()
     _ = manager.state(for: worktree)
-    #expect(manager.listSurfaces(worktreeID: worktree.id, tabID: "not-a-uuid") == nil)
+    #expect(manager.listSurfaces(worktreeID: worktree.id.rawValue, tabID: "not-a-uuid") == nil)
   }
 
   @Test func latestUnreadNotificationPicksNewestAcrossWorktrees() {
@@ -1457,23 +1902,364 @@ struct WorktreeTerminalManagerTests {
         "surface_id": "\(surfaceID.uuidString)"\(pidLine)
       }
       """
-    guard case .event(let event) = AgentHookSocketServer.parse(data: Data(json.utf8)) else {
+    guard let event = try? JSONDecoder().decode(AgentHookEvent.self, from: Data(json.utf8)) else {
       preconditionFailure("Failed to parse test event")
     }
     return event
   }
 
+  @Test func coalescesConsecutiveIdenticalTaskStatusEvents() async {
+    let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
+    let worktree = makeWorktree()
+    let state = manager.state(for: worktree)
+    let stream = manager.eventStream()
+
+    state.onTaskStatusChanged?(.running)
+    state.onTaskStatusChanged?(.running)
+    state.onTaskStatusChanged?(.idle)
+    state.onTaskStatusChanged?(.idle)
+    state.onTaskStatusChanged?(.running)
+
+    // Resubscribing finishes `stream` so the drain below terminates.
+    _ = manager.eventStream()
+
+    var statuses: [WorktreeTaskStatus] = []
+    for await event in stream {
+      guard case .taskStatusChanged(_, let status) = event else { continue }
+      statuses.append(status)
+    }
+
+    #expect(statuses == [.running, .idle, .running])
+  }
+
+  @Test func coalescesConsecutiveIdenticalFocusEvents() async {
+    let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
+    let worktree = makeWorktree()
+    let state = manager.state(for: worktree)
+    let stream = manager.eventStream()
+    let first = UUID()
+    let second = UUID()
+
+    state.onFocusChanged?(first)
+    state.onFocusChanged?(first)
+    state.onFocusChanged?(second)
+    state.onFocusChanged?(first)
+
+    _ = manager.eventStream()
+
+    var focused: [UUID] = []
+    for await event in stream {
+      guard case .focusChanged(_, let surfaceID) = event else { continue }
+      focused.append(surfaceID)
+    }
+
+    #expect(focused == [first, second, first])
+  }
+
+  @Test func capsTheLiveEventBufferUnderBackpressure() async {
+    let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
+    let worktree = makeWorktree()
+    let state = manager.state(for: worktree)
+    let stream = manager.eventStream()
+
+    // Lifecycle events are never coalesced, so each one occupies a buffer slot.
+    // Emitting past the cap with nothing draining must shed the oldest, not grow.
+    let overflow = WorktreeTerminalManager.eventBufferCap + 50
+    for _ in 0..<overflow {
+      state.onSetupScriptConsumed?()
+    }
+
+    _ = manager.eventStream()
+
+    var count = 0
+    for await event in stream {
+      if case .setupScriptConsumed = event { count += 1 }
+    }
+
+    #expect(count == WorktreeTerminalManager.eventBufferCap)
+  }
+
+  @Test func purgesCoalesceKeyOnTabTeardownSoIdenticalEventRedelivers() async {
+    let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
+    let worktree = makeWorktree()
+    let state = manager.state(for: worktree)
+    let stream = manager.eventStream()
+    let tabID = TerminalTabID()
+    let projection = WorktreeTabProjection(
+      tabID: tabID,
+      surfaceIDs: [UUID()],
+      activeSurfaceID: nil,
+      unseenNotificationCount: 0
+    )
+
+    state.onTabProjectionChanged?(projection)
+    state.onTabRemoved?(tabID)
+    // The teardown purged the stale key, so an identical projection for the same
+    // tab id (e.g. a snapshot restore reusing the UUID) must be delivered again.
+    state.onTabProjectionChanged?(projection)
+
+    _ = manager.eventStream()
+
+    var delivered = 0
+    for await event in stream {
+      if case .tabProjectionChanged(_, let value) = event, value.tabID == tabID {
+        delivered += 1
+      }
+    }
+
+    #expect(delivered == 2)
+  }
+
+  @Test func neverCoalescesConsecutiveLifecycleEvents() async {
+    let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
+    let worktree = makeWorktree()
+    let state = manager.state(for: worktree)
+    let stream = manager.eventStream()
+
+    state.onTabCreated?()
+    state.onTabCreated?()
+
+    _ = manager.eventStream()
+
+    var created = 0
+    for await event in stream {
+      if case .tabCreated = event { created += 1 }
+    }
+
+    #expect(created == 2)
+  }
+
+  @Test func coalescesPendingEventsBeforeSubscription() async {
+    let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
+    let worktree = makeWorktree()
+    let state = manager.state(for: worktree)
+
+    // No subscriber attached yet, so these buffer into pendingEvents; identical
+    // keys must collapse to the latest value before the first subscriber drains.
+    state.onTaskStatusChanged?(.running)
+    state.onTaskStatusChanged?(.idle)
+    state.onTaskStatusChanged?(.running)
+
+    let stream = manager.eventStream()
+    _ = manager.eventStream()
+
+    var statuses: [WorktreeTaskStatus] = []
+    for await event in stream {
+      guard case .taskStatusChanged(_, let status) = event else { continue }
+      statuses.append(status)
+    }
+
+    #expect(statuses == [.running])
+  }
+
+  @Test func capsPendingLifecycleEventsBeforeSubscription() async {
+    let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
+    let worktree = makeWorktree()
+    let state = manager.state(for: worktree)
+
+    // No subscriber attached: lifecycle events fill pendingEvents and must cap.
+    let overflow = WorktreeTerminalManager.pendingEventCap + 50
+    for _ in 0..<overflow {
+      state.onSetupScriptConsumed?()
+    }
+
+    let stream = manager.eventStream()
+    _ = manager.eventStream()
+
+    var count = 0
+    for await event in stream {
+      if case .setupScriptConsumed = event { count += 1 }
+    }
+
+    #expect(count == WorktreeTerminalManager.pendingEventCap)
+  }
+
+  @Test func seedsCoalesceCacheFromPendingReplaySoLiveDuplicateDedups() async {
+    let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
+    let worktree = makeWorktree()
+    let state = manager.state(for: worktree)
+
+    // Buffered before any subscriber attaches, then replayed on subscribe.
+    state.onTaskStatusChanged?(.running)
+    let stream = manager.eventStream()
+    // The replay seeded the cache, so this identical live value must dedup.
+    state.onTaskStatusChanged?(.running)
+
+    _ = manager.eventStream()
+
+    var statuses: [WorktreeTaskStatus] = []
+    for await event in stream {
+      guard case .taskStatusChanged(_, let status) = event else { continue }
+      statuses.append(status)
+    }
+
+    #expect(statuses == [.running])
+  }
+
   private func makeWorktree(id: String = "/tmp/repo/wt-1") -> Worktree {
     let name = URL(fileURLWithPath: id).lastPathComponent
     return Worktree(
-      id: id,
+      id: WorktreeID(id),
       name: name,
       detail: "detail",
       workingDirectory: URL(fileURLWithPath: id),
-      repositoryRootURL: URL(fileURLWithPath: "/tmp/repo")
+      repositoryRootURL: URL(fileURLWithPath: "/tmp/repo"),
     )
   }
 
+  private func makeZmxBackedManager(probe: ZmxTestProbe) -> WorktreeTerminalManager {
+    let zmxURL = FileManager.default.temporaryDirectory.appendingPathComponent("supacode-test-zmx-\(UUID().uuidString)")
+    let script = "#!/bin/sh\nexec /bin/cat\n"
+    do {
+      try script.write(to: zmxURL, atomically: true, encoding: .utf8)
+      try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: zmxURL.path)
+    } catch {
+      Issue.record("Failed to set up fake zmx binary: \(error)")
+    }
+
+    return withDependencies {
+      $0.zmxClient = ZmxClient(
+        executableURL: { zmxURL },
+        isBundled: { true },
+        killSession: { id in await probe.killSession(id) },
+        listSessionsWithClients: { await probe.listSessionsWithClients() },
+      )
+    } operation: {
+      let manager = WorktreeTerminalManager(runtime: GhosttyRuntime())
+      _ = manager.state(for: makeWorktree())
+      return manager
+    }
+  }
+
+  nonisolated private func session(for surfaceID: UUID) -> String {
+    ZmxSessionID.make(surfaceID: surfaceID)
+  }
+
+  // MainActor work schedules cooperatively, so yield-poll it; the deadline guards CI load.
+  private func waitUntil(
+    _ description: String,
+    sourceLocation: SourceLocation = #_sourceLocation,
+    condition: @MainActor () -> Bool
+  ) async {
+    let clock = ContinuousClock()
+    let deadline = clock.now.advanced(by: ZmxTestProbe.waitTimeout)
+    while !condition() && clock.now < deadline {
+      await Task.yield()
+    }
+    if !condition() {
+      Issue.record("Timed out waiting for \(description)", sourceLocation: sourceLocation)
+    }
+  }
+
+  private actor ZmxTestProbe {
+    // Backstop so a never-firing kill or probe fails fast instead of hanging.
+    static let waitTimeout: Duration = .seconds(10)
+
+    private enum Trigger {
+      case kill(@Sendable ([String]) -> Bool)
+      case list(threshold: Int)
+    }
+
+    // Resumed exactly once: by the event or the timeout.
+    private struct Waiter {
+      let id: UUID
+      let trigger: Trigger
+      let continuation: CheckedContinuation<Bool, Never>
+      let timeout: Task<Void, Never>
+    }
+
+    private var listing: [ZmxSessionListParser.Entry]?
+    private var killed: [String] = []
+    private var listCalls = 0
+    private var waiters: [Waiter] = []
+
+    init(listing: [ZmxSessionListParser.Entry]?) {
+      self.listing = listing
+    }
+
+    func setListing(_ listing: [ZmxSessionListParser.Entry]?) {
+      self.listing = listing
+    }
+
+    func listSessionsWithClients() -> [ZmxSessionListParser.Entry]? {
+      listCalls += 1
+      resumeWaiters()
+      return listing
+    }
+
+    func killSession(_ sessionID: String) {
+      killed.append(sessionID)
+      resumeWaiters()
+    }
+
+    func killedSessions() -> [String] {
+      killed
+    }
+
+    func listCallCount() -> Int {
+      listCalls
+    }
+
+    @discardableResult
+    func waitForKill(
+      where predicate: @escaping @Sendable ([String]) -> Bool,
+      sourceLocation: SourceLocation = #_sourceLocation
+    ) async -> Bool {
+      await wait(for: .kill(predicate), description: "zmx session kill", sourceLocation: sourceLocation)
+    }
+
+    @discardableResult
+    func waitForListCalls(
+      atLeast threshold: Int,
+      sourceLocation: SourceLocation = #_sourceLocation
+    ) async -> Bool {
+      await wait(for: .list(threshold: threshold), description: "zmx list probe call", sourceLocation: sourceLocation)
+    }
+
+    // The event resumes the waiter; the timeout only guards a regression.
+    private func wait(
+      for trigger: Trigger,
+      description: String,
+      sourceLocation: SourceLocation
+    ) async -> Bool {
+      if isSatisfied(trigger) { return true }
+      let id = UUID()
+      let satisfied = await withCheckedContinuation { (continuation: CheckedContinuation<Bool, Never>) in
+        // Strong capture: bounded and cancelled on the event path, so the continuation always resumes.
+        let timeout = Task { [self] in
+          try? await Task.sleep(for: Self.waitTimeout)
+          await expireWaiter(id)
+        }
+        waiters.append(Waiter(id: id, trigger: trigger, continuation: continuation, timeout: timeout))
+      }
+      if !satisfied {
+        Issue.record("Timed out waiting for \(description)", sourceLocation: sourceLocation)
+      }
+      return satisfied
+    }
+
+    private func isSatisfied(_ trigger: Trigger) -> Bool {
+      switch trigger {
+      case .kill(let predicate): predicate(killed)
+      case .list(let threshold): listCalls >= threshold
+      }
+    }
+
+    private func resumeWaiters() {
+      waiters.removeAll { waiter in
+        guard isSatisfied(waiter.trigger) else { return false }
+        waiter.timeout.cancel()
+        waiter.continuation.resume(returning: true)
+        return true
+      }
+    }
+
+    private func expireWaiter(_ id: UUID) {
+      guard let index = waiters.firstIndex(where: { $0.id == id }) else { return }
+      waiters.remove(at: index).continuation.resume(returning: false)
+    }
+  }
+
   private func nextEvent(
     _ stream: AsyncStream<TerminalClient.Event>,
     matching predicate: (TerminalClient.Event) -> Bool
diff --git a/supacodeTests/ZmxClientTests.swift b/supacodeTests/ZmxClientTests.swift
index c51e91120..29515c7de 100644
--- a/supacodeTests/ZmxClientTests.swift
+++ b/supacodeTests/ZmxClientTests.swift
@@ -78,6 +78,26 @@ struct ZmxAttachTests {
     )
     #expect(cmd == "'/zmx' attach s /bin/sh -c 'echo '\\''hi'\\'''")
   }
+
+  /// The interactive wrapper argv is exactly `[exe, "attach", sessionID]`, each a
+  /// separate element (no shell string), so Ghostty execs it directly.
+  @Test func buildWrapperArgvIsAttachWithSession() {
+    let argv = ZmxAttach.buildWrapperArgv(executablePath: "/path/to/zmx", sessionID: "supa-abc")
+    #expect(argv == ["/path/to/zmx", "attach", "supa-abc"])
+  }
+
+  /// A path with spaces stays a single argv element (no quoting / re-splitting),
+  /// since Ghostty receives a tokenized `direct:` command.
+  @Test func buildWrapperArgvKeepsSpacedPathAsOneElement() {
+    let argv = ZmxAttach.buildWrapperArgv(
+      executablePath: "/Applications/Supacode Dev.app/Contents/Resources/zmx/zmx",
+      sessionID: "supa-1"
+    )
+    #expect(argv.count == 3)
+    #expect(argv[0] == "/Applications/Supacode Dev.app/Contents/Resources/zmx/zmx")
+    #expect(argv[1] == "attach")
+    #expect(argv[2] == "supa-1")
+  }
 }
 
 @MainActor
@@ -130,15 +150,97 @@ struct ZmxSocketBudgetTests {
 }
 
 @MainActor
-struct ZmxClientNoopTests {
-  /// The default test impl is a no-op so existing TestStore tests are unaffected
-  /// by the wrap path. wrapCommand returning nil means callers fall through to
-  /// the raw command unchanged.
-  @Test func noopWrapCommandReturnsNil() {
-    let cmd = ZmxClient.noop.wrapCommand("any-id", "echo hi")
-    #expect(cmd == nil)
+struct ZmxResolveLaunchTests {
+  /// Interactive surface (nil command): nil command + `[exe, attach, id]` wrapper,
+  /// so Ghostty resolves + integrates the real shell and zmx wraps the result.
+  @Test func interactiveSurfaceGetsWrapperAndNilCommand() {
+    let resolved = ZmxAttach.resolveLaunch(executablePath: "/zmx", sessionID: "supa-abc", command: nil)
+    #expect(resolved.command == nil)
+    #expect(resolved.commandWrapper == ["/zmx", "attach", "supa-abc"])
+  }
+
+  /// Explicit command (script): wrapped command string and an EMPTY wrapper, so a
+  /// script is never double-wrapped via both `command` and a `command-wrapper`.
+  @Test func explicitCommandIsStringWrappedWithNoWrapper() {
+    let resolved = ZmxAttach.resolveLaunch(executablePath: "/zmx", sessionID: "s", command: "echo hi")
+    #expect(resolved.command == "'/zmx' attach s /bin/sh -c 'echo hi'")
+    #expect(resolved.commandWrapper.isEmpty)
+  }
+
+  /// A blank/whitespace command is normalized to interactive, so it can't slip
+  /// into the script path and launch a bare uninteg. shell.
+  @Test func blankCommandIsTreatedAsInteractive() {
+    let resolved = ZmxAttach.resolveLaunch(executablePath: "/zmx", sessionID: "s", command: "   \n")
+    #expect(resolved.command == nil)
+    #expect(resolved.commandWrapper == ["/zmx", "attach", "s"])
+  }
+
+  /// zmx unbundled / over budget (nil executable): raw command, no zmx at all.
+  @Test func nilExecutableFallsThroughToRawCommand() {
+    let interactive = ZmxAttach.resolveLaunch(executablePath: nil, sessionID: "s", command: nil)
+    #expect(interactive.command == nil)
+    #expect(interactive.commandWrapper.isEmpty)
+
+    let script = ZmxAttach.resolveLaunch(executablePath: nil, sessionID: "s", command: "echo hi")
+    #expect(script.command == "echo hi")
+    #expect(script.commandWrapper.isEmpty)
+  }
+}
+
+@MainActor
+struct ZmxSessionListParserTests {
+  @Test func parsesClientsZero() {
+    let entries = ZmxSessionListParser.parse("name=supa-abc\tpid=123\tclients=0\tcreated=0\n")
+    #expect(entries == [.init(name: "supa-abc", clients: 0)])
+  }
+
+  @Test func parsesClientsPositive() {
+    let entries = ZmxSessionListParser.parse("name=supa-abc\tpid=123\tclients=2\tcreated=0\n")
+    #expect(entries == [.init(name: "supa-abc", clients: 2)])
   }
 
+  @Test func errOrStatusLineYieldsNilClients() {
+    let entries = ZmxSessionListParser.parse(
+      "name=supa-abc\terr=ConnectionRefused\tstatus=cleaning up\n"
+    )
+    #expect(entries == [.init(name: "supa-abc", clients: nil)])
+  }
+
+  @Test func stripsCurrentSessionArrowPrefix() {
+    let entries = ZmxSessionListParser.parse("→ name=supa-abc\tpid=1\tclients=1\tcreated=0\n")
+    #expect(entries == [.init(name: "supa-abc", clients: 1)])
+  }
+
+  @Test func stripsLeadingIndentOnNonCurrentSessions() {
+    let entries = ZmxSessionListParser.parse("  name=supa-abc\tclients=0\tpid=1\tcreated=0\n")
+    #expect(entries == [.init(name: "supa-abc", clients: 0)])
+  }
+
+  @Test func filtersNonSupaSessions() {
+    let entries = ZmxSessionListParser.parse(
+      """
+      name=dev\tpid=1\tclients=2\tcreated=0
+      name=supa-abc\tpid=2\tclients=0\tcreated=0
+      """
+    )
+    #expect(entries == [.init(name: "supa-abc", clients: 0)])
+  }
+
+  @Test func dropsBlankAndMalformedLines() {
+    let entries = ZmxSessionListParser.parse(
+      """
+
+      garbage with no equals
+      name=supa-keep\tpid=9\tclients=3\tcreated=0
+
+      """
+    )
+    #expect(entries == [.init(name: "supa-keep", clients: 3)])
+  }
+}
+
+@MainActor
+struct ZmxClientNoopTests {
   @Test func noopExecutableURLReturnsNil() {
     #expect(ZmxClient.noop.executableURL() == nil)
   }