Merge pull request 'Add a per-project Notes tab with a send-to-agent action' (#48) from feat/project-notes into main

Sending already switched to the target terminal's tab, which looks like it
should be enough: `TerminalView` focuses xterm whenever a terminal becomes
active. But that effect keys off `active`, so it only fires on a *change* —
and the dock's ordinary case is sending to the terminal already on screen.
`setActiveTabKey` writes the key that is already set, nothing changes, no
effect re-runs, and focus stays on the Send button. The note is sitting in the
prompt and the user still has to click the terminal before pressing Enter.

So the send now asks for focus explicitly, through a one-shot request in the
store that `TerminalView` consumes and clears — the shape `pendingHomeTab`
already uses. Clearing is not tidiness: hold the id and the second send to the
same terminal writes a value that is already there, which is precisely the
no-op this exists to fix.

Focus is requested only on success. A failed send toasts and leaves the user
where they are, because there is nothing in the prompt to press Enter on.

The three `TerminalView` tests give focus away after mounting before making
any assertion, so what they observe is the request landing and never the focus
that `active` already grants on mount — which would pass with the feature
absent.

752 tests pass, 62 files.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011YPqHpjV4EL6RNEwrRKqQm

.gitea/workflows/build-app-preview.yml

@@ -0,0 +1,651 @@
+name: Build App (Preview)
+
+# Builds the Tauri app for branches other than main and publishes the bundles as
+# a **prerelease**, so they are downloadable from the Releases page. No GitHub
+# sync.
+#
+# This is also the **PR build check**: it compiles Linux, macOS and Windows, so
+# a push that breaks any of them fails here. build-app.yml used to do that job
+# in parallel and publish nothing, which meant six OS builds per push and one
+# unreachable set of bundles; it is now releases-only.
+#
+# The cost of the swap, stated plainly: one prerelease per PR commit that
+# touches `app/**` — so the workflow prunes its own, keeping the newest
+# KEEP_PREVIEWS (see Lifecycle).
+#
+# ## Why not workflow artifacts
+#
+# Two attempts failed before this one, and both failure modes are worth knowing:
+#
+#  * `actions/upload-artifact@v4` cannot run here at all. It bundles
+#    `@actions/artifact` v2, whose `isGhes()` treats any GITHUB_SERVER_URL that
+#    is not github.com / *.ghe.com / *.localhost as GitHub Enterprise Server and
+#    throws before making a single request. act_runner sets that variable to this
+#    Gitea instance, so every platform died with "GHESNotSupportedError" — after
+#    the whole Tauri build had been paid for (run #265).
+#  * `@v3` uploads *succeed*, and the files are downloadable by direct URL — but
+#    Gitea does not **list** them: `/api/v1/…/runs/<id>/artifacts` reports
+#    `total_count: 0` and the run page shows nothing (verified on run #267).
+#    A build nobody can find is not a build.
+#
+# So previews publish the same way every other workflow here does: curl to the
+# Gitea releases API. One release per preview, tagged `preview-<sha>`.
+#
+# ## Lifecycle
+#
+# The `preview-` tag prefix is deliberate. `cleanup-releases.yml` keeps the most
+# recent `v<major>.<minor>.<patch>` releases and separately deletes every release
+# whose tag does *not* start with `v[0-9]` — so previews never crowd the real
+# release list, and a manual cleanup sweeps any this workflow missed.
+#
+# But that cleanup is a manual, dry-run-by-default action, and one prerelease per
+# pushed commit accumulates faster than anyone runs it. So the last job here
+# prunes previous previews itself, keeping the newest few. Bundles are ~130 MB a
+# release; the point of a preview is the build you are testing now.
+#
+# A preview release is not meant to reach GitHub. `build-app.yml`'s inline
+# mirror never sees one (it only runs for its own `push`-triggered release),
+# but `backfill-releases.yml` pulls every Gitea release unfiltered and would
+# faithfully forward a preview's `prerelease: true` if it were ever dispatched
+# while one existed — so `GitHubRelease::prerelease` in `update_commands.rs`
+# is real defence, not a no-op, even though the `preview-<sha>` tag shape
+# (never valid semver) already blocks it independently. (The previous
+# mechanism here, `sync-release.yml`, was `workflow_dispatch`-only and read
+# `gitea.event.release.*` fields that are only ever populated by a `release`
+# trigger, so it could never have actually run; deleted rather than fixed,
+# since build-app.yml's inline mirror already does what it was meant to do
+# for real releases. See triple-c#32.)
+
+env:
+  GITEA_URL: ${{ gitea.server_url }}
+  REPO: ${{ gitea.repository }}
+  # How many preview releases survive a run, newest first — including the one
+  # just published.
+  KEEP_PREVIEWS: "2"
+
+on:
+  # Every push to an open PR: this *is* the branch's build check — it compiles
+  # Linux, macOS and Windows — and publishing the result costs nothing extra
+  # once they are built. build-app.yml deliberately no longer runs on PRs.
+  pull_request:
+    branches: [main]
+    paths:
+      - "app/**"
+      - "VERSION"
+      - ".gitea/workflows/build-app-preview.yml"
+  workflow_dispatch:
+
+jobs:
+  compute-version:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.VERSION }}
+      sha: ${{ steps.version.outputs.SHA }}
+      # Everything after the first `-` in VERSION (e.g. `preview.a1b2c3d`).
+      # The bundle version fields never see this — see "Set app version" in
+      # each build job — but it is baked into the binary as
+      # `TRIPLE_C_BUILD_SUFFIX` so `get_app_version()` can still report it.
+      # An installed preview otherwise reports the same bare number a
+      # production build would, indistinguishable in the About panel and to
+      # `check_for_updates`. See triple-c#32.
+      suffix: ${{ steps.version.outputs.SUFFIX }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Fetch all tags
+        run: git fetch --tags
+
+      - name: Compute preview version
+        id: version
+        run: |
+          MAJOR_MINOR=$(cat VERSION | tr -d '[:space:]')
+          SHORT_SHA=$(git rev-parse --short HEAD)
+          # From the checkout, not from `gitea.sha`: on a pull_request event
+          # that variable can be the merge ref, which is not the commit anyone
+          # is testing and not something to hang a tag on.
+          echo "SHA=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
+
+          # The patch number must be the same "one past the highest patch
+          # already used" build-app.yml computes for a real release — not a
+          # distance from the latest tag. It used to be
+          # `git rev-list --count <latest tag>..HEAD`, which build-app.yml's
+          # own history section documents as broken for exactly this reason:
+          # it resets to zero on every tag cut, so previews went *backwards*
+          # (0.4.62 -> 0.4.0) the moment a release landed, and nothing stopped
+          # a preview number from later colliding with a real release's.
+          #
+          # Reading the same `v${MAJOR_MINOR}.*` tags (including the `-mac`
+          # / `-win` suffixed ones a partially-published release can leave
+          # behind) means a preview built right before a release computes the
+          # exact number that release is about to take — e.g. `0.4.13` for
+          # both. That makes the two numerically *equal*, not "preview less
+          # than release" — plain semver ordering does not make a
+          # `-preview.<sha>` suffix sort lower on its own here, because
+          # `check_for_updates` compares against the bare, stripped
+          # `CARGO_PKG_VERSION`, never the suffixed display string. What
+          # closes the loop is `update_commands.rs`'s `is_preview_build`
+          # check, which relaxes that one comparison to `>=` specifically so
+          # "a release exists at my own number" reads as an update. See
+          # triple-c#32.
+          HIGHEST=$(git tag -l "v${MAJOR_MINOR}.*" \
+            | grep -E "^v${MAJOR_MINOR}\.[0-9]+(-mac|-win)?$" \
+            | sed -E "s/^v${MAJOR_MINOR}\.([0-9]+).*/\1/" \
+            | sort -n | tail -1 || true)
+
+          # Mirrors build-app.yml's own `EXISTING` guard: this workflow is
+          # also `workflow_dispatch`-able on `main`, not just PR-triggered, so
+          # HEAD can be a commit a release was already cut from. Without this,
+          # dispatching a preview there would compute `HIGHEST + 1` — one past
+          # that release — and produce exactly the "preview outranks
+          # production" failure triple-c#32 was filed over, just reintroduced
+          # through the manual-dispatch door instead of the automatic one.
+          EXISTING=$(git tag --points-at HEAD \
+            | grep -E "^v${MAJOR_MINOR}\.[0-9]+$" \
+            | sed -E "s/^v${MAJOR_MINOR}\.([0-9]+)$/\1/" \
+            | sort -n | tail -1 || true)
+
+          if [ -n "$EXISTING" ]; then
+            echo "HEAD is already tagged v${MAJOR_MINOR}.${EXISTING} — matching it"
+            PATCH="${EXISTING}"
+          elif [ -n "$HIGHEST" ]; then
+            echo "Highest patch already used on this line: ${HIGHEST}"
+            PATCH=$((HIGHEST + 1))
+          else
+            echo "No v${MAJOR_MINOR}.* tag yet — starting this line at .0"
+            PATCH=0
+          fi
+
+          SUFFIX="preview.${SHORT_SHA}"
+          VERSION="${MAJOR_MINOR}.${PATCH}-${SUFFIX}"
+          echo "VERSION=${VERSION}" >> $GITHUB_OUTPUT
+          echo "SUFFIX=${SUFFIX}" >> $GITHUB_OUTPUT
+          echo "Computed preview version: ${VERSION}"
+
+  # One release, created once. The three build jobs run concurrently, so
+  # get-or-create in each of them would race on the same tag: whoever loses gets
+  # a 409 and (the way the old build-app.yml parsed it) an empty release id that
+  # still reported success. Creating it in a job they all depend on removes the
+  # race rather than handling it.
+  create-release:
+    runs-on: ubuntu-latest
+    needs: [compute-version]
+    outputs:
+      release_id: ${{ steps.release.outputs.RELEASE_ID }}
+      tag: ${{ steps.release.outputs.TAG }}
+    steps:
+      - name: Create the preview release
+        id: release
+        env:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          VERSION: ${{ needs.compute-version.outputs.version }}
+          SHA: ${{ needs.compute-version.outputs.sha }}
+          BRANCH: ${{ gitea.head_ref || gitea.ref_name }}
+        run: |
+          set -euo pipefail
+          TAG="preview-${VERSION##*.}"
+          echo "TAG=${TAG}" >> $GITHUB_OUTPUT
+
+          # Idempotent: re-dispatching the same commit must update the existing
+          # release rather than fail on the duplicate tag.
+          HTTP_CODE=$(curl -sS -o release.json -w '%{http_code}' \
+            -H "Authorization: token ${TOKEN}" \
+            "${GITEA_URL}/api/v1/repos/${REPO}/releases/tags/${TAG}")
+          case "${HTTP_CODE}" in
+            200) echo "Release ${TAG} already exists, reusing" ;;
+            404)
+              echo "Creating release ${TAG}"
+              # prerelease: true keeps it off "latest" — this is a branch build,
+              # not something anyone should install by accident.
+              curl -fsS -X POST \
+                -H "Authorization: token ${TOKEN}" \
+                -H "Content-Type: application/json" \
+                -d "{\"tag_name\": \"${TAG}\", \"target_commitish\": \"${SHA}\", \"name\": \"Preview ${VERSION}\", \"prerelease\": true, \"body\": \"Unreleased build of \`${BRANCH}\` at ${SHA}. Not a release — pruned by Cleanup Old Releases.\"}" \
+                "${GITEA_URL}/api/v1/repos/${REPO}/releases" > release.json
+              ;;
+            *)
+              echo "Unexpected HTTP ${HTTP_CODE} from get-release-by-tag" >&2
+              cat release.json >&2 || true
+              exit 1
+              ;;
+          esac
+
+          RELEASE_ID=$(grep -o '"id":[0-9]*' release.json | head -1 | grep -o '[0-9]*' || true)
+          if [ -z "${RELEASE_ID}" ]; then
+            echo "Failed to parse release id; response was:" >&2
+            cat release.json >&2
+            exit 1
+          fi
+          echo "RELEASE_ID=${RELEASE_ID}" >> $GITHUB_OUTPUT
+          echo "Release ${TAG} is id ${RELEASE_ID}"
+
+  build-linux:
+    runs-on: ubuntu-latest
+    needs: [compute-version, create-release]
+    steps:
+      - name: Install Node.js 22
+        run: |
+          NEED_INSTALL=false
+          if command -v node >/dev/null 2>&1; then
+            NODE_MAJOR=$(node --version | sed 's/v\([0-9]*\).*/\1/')
+            OLD_NODE_DIR=$(dirname "$(which node)")
+            echo "Found Node.js $(node --version) at $(which node) (major: ${NODE_MAJOR})"
+            if [ "$NODE_MAJOR" -lt 22 ]; then
+              echo "Node.js ${NODE_MAJOR} is too old, removing before installing 22..."
+              sudo rm -f "${OLD_NODE_DIR}/node" "${OLD_NODE_DIR}/npm" "${OLD_NODE_DIR}/npx" "${OLD_NODE_DIR}/corepack"
+              hash -r
+              NEED_INSTALL=true
+            fi
+          else
+            echo "Node.js not found, installing 22..."
+            NEED_INSTALL=true
+          fi
+          if [ "$NEED_INSTALL" = true ]; then
+            curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+            sudo apt-get install -y nodejs
+            hash -r
+          fi
+          node --version
+          npm --version
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set app version
+        run: |
+          # Tauri / Cargo require a strict semver; strip the preview suffix for
+          # the bundle version but keep it in the artifact filename.
+          BASE_VERSION="$(echo '${{ needs.compute-version.outputs.version }}' | cut -d'-' -f1)"
+          sed -i "s/\"version\": \".*\"/\"version\": \"${BASE_VERSION}\"/" app/src-tauri/tauri.conf.json
+          sed -i "s/\"version\": \".*\"/\"version\": \"${BASE_VERSION}\"/" app/package.json
+          sed -i "s/^version = \".*\"/version = \"${BASE_VERSION}\"/" app/src-tauri/Cargo.toml
+          echo "Patched version to ${BASE_VERSION}"
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libgtk-3-dev \
+            libwebkit2gtk-4.1-dev \
+            libayatana-appindicator3-dev \
+            librsvg2-dev \
+            libsoup-3.0-dev \
+            libssl-dev \
+            libxdo-dev \
+            patchelf \
+            pkg-config \
+            build-essential \
+            curl \
+            wget \
+            file \
+            xdg-utils
+
+      - name: Install Rust stable
+        run: |
+          if command -v rustup >/dev/null 2>&1; then
+            rustup update stable
+            rustup default stable
+          else
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
+          fi
+          export PATH="$HOME/.cargo/bin:$PATH"
+          rustc --version
+          cargo --version
+
+      - name: Install frontend dependencies
+        working-directory: ./app
+        run: |
+          rm -rf node_modules package-lock.json
+          npm install
+
+      - name: Install Tauri CLI
+        working-directory: ./app
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          npx tauri --version || npm install @tauri-apps/cli
+
+      - name: Build Tauri app
+        working-directory: ./app
+        env:
+          # Baked into the binary via `option_env!` in `get_app_version()` —
+          # the bundle version above stays bare (WiX/MSI's ProductVersion has
+          # no room for a suffix), so this is the only place a preview build
+          # can still tell itself apart from a production one. See
+          # triple-c#32.
+          TRIPLE_C_BUILD_SUFFIX: ${{ needs.compute-version.outputs.suffix }}
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          npx tauri build
+
+      - name: Collect artifacts
+        run: |
+          mkdir -p artifacts
+          cp app/src-tauri/target/release/bundle/appimage/*.AppImage artifacts/ 2>/dev/null || true
+          cp app/src-tauri/target/release/bundle/deb/*.deb artifacts/ 2>/dev/null || true
+          cp app/src-tauri/target/release/bundle/rpm/*.rpm artifacts/ 2>/dev/null || true
+          ls -la artifacts/
+
+      # Assets, not workflow artifacts — see the note at the top of this file.
+      # Delete-then-upload so a re-dispatch replaces rather than 409s, and the
+      # retry/http1.1 hardening that build-app.yml learned from real macOS
+      # upload failures (curl exit 92 and exit 28 mid-stream).
+      - name: Upload Linux bundles to the preview release
+        shell: bash
+        env:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          RELEASE_ID: ${{ needs.create-release.outputs.release_id }}
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          files=(artifacts/*)
+          if [ ${#files[@]} -eq 0 ]; then
+            echo "No Linux bundles were produced" >&2
+            exit 1
+          fi
+          for file in "${files[@]}"; do
+            filename=$(basename "$file")
+            EXISTING_ID=$(curl -sS \
+              -H "Authorization: token ${TOKEN}" \
+              "${GITEA_URL}/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets" \
+              | python3 -c "import json,sys; t=sys.argv[1]; print(next((a['id'] for a in json.load(sys.stdin) if a.get('name')==t), ''))" "${filename}" || true)
+            if [ -n "${EXISTING_ID}" ]; then
+              echo "Replacing existing asset ${filename}"
+              curl -fsS -X DELETE \
+                -H "Authorization: token ${TOKEN}" \
+                "${GITEA_URL}/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets/${EXISTING_ID}"
+            fi
+            echo "Uploading ${filename}..."
+            curl -fsS --http1.1 --retry 5 --retry-all-errors --retry-delay 5 --max-time 600 \
+              -X POST \
+              -H "Authorization: token ${TOKEN}" \
+              -H "Content-Type: application/octet-stream" \
+              --data-binary "@${file}" \
+              "${GITEA_URL}/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets?name=${filename}"
+          done
+
+  build-macos:
+    runs-on: macos-latest
+    needs: [compute-version, create-release]
+    steps:
+      - name: Install Node.js 22
+        run: |
+          NEED_INSTALL=false
+          if command -v node >/dev/null 2>&1; then
+            NODE_MAJOR=$(node --version | sed 's/v\([0-9]*\).*/\1/')
+            if [ "$NODE_MAJOR" -lt 22 ]; then
+              NEED_INSTALL=true
+            fi
+          else
+            NEED_INSTALL=true
+          fi
+          if [ "$NEED_INSTALL" = true ]; then
+            brew install node@22
+            brew link --overwrite node@22
+          fi
+          node --version
+          npm --version
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set app version
+        run: |
+          BASE_VERSION="$(echo '${{ needs.compute-version.outputs.version }}' | cut -d'-' -f1)"
+          sed -i '' "s/\"version\": \".*\"/\"version\": \"${BASE_VERSION}\"/" app/src-tauri/tauri.conf.json
+          sed -i '' "s/\"version\": \".*\"/\"version\": \"${BASE_VERSION}\"/" app/package.json
+          sed -i '' "s/^version = \".*\"/version = \"${BASE_VERSION}\"/" app/src-tauri/Cargo.toml
+          echo "Patched version to ${BASE_VERSION}"
+
+      - name: Install Rust stable
+        run: |
+          if command -v rustup >/dev/null 2>&1; then
+            rustup update stable
+            rustup default stable
+          else
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
+          fi
+          export PATH="$HOME/.cargo/bin:$PATH"
+          rustup target add aarch64-apple-darwin x86_64-apple-darwin
+          rustc --version
+          cargo --version
+
+      - name: Install frontend dependencies
+        working-directory: ./app
+        run: |
+          rm -rf node_modules
+          npm install
+
+      - name: Install Tauri CLI
+        working-directory: ./app
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          npx tauri --version || npm install @tauri-apps/cli
+
+      - name: Build Tauri app (universal)
+        working-directory: ./app
+        env:
+          # See the matching comment on the Linux job's "Build Tauri app" step.
+          TRIPLE_C_BUILD_SUFFIX: ${{ needs.compute-version.outputs.suffix }}
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          npx tauri build --target universal-apple-darwin
+
+      - name: Collect artifacts
+        run: |
+          mkdir -p artifacts
+          cp app/src-tauri/target/universal-apple-darwin/release/bundle/dmg/*.dmg artifacts/ 2>/dev/null || true
+          cp app/src-tauri/target/universal-apple-darwin/release/bundle/macos/*.app.tar.gz artifacts/ 2>/dev/null || true
+          ls -la artifacts/
+
+      # Assets, not workflow artifacts — see the note at the top of this file.
+      # Delete-then-upload so a re-dispatch replaces rather than 409s, and the
+      # retry/http1.1 hardening that build-app.yml learned from real macOS
+      # upload failures (curl exit 92 and exit 28 mid-stream).
+      - name: Upload macOS bundles to the preview release
+        shell: bash
+        env:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          RELEASE_ID: ${{ needs.create-release.outputs.release_id }}
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          files=(artifacts/*)
+          if [ ${#files[@]} -eq 0 ]; then
+            echo "No macOS bundles were produced" >&2
+            exit 1
+          fi
+          for file in "${files[@]}"; do
+            filename=$(basename "$file")
+            EXISTING_ID=$(curl -sS \
+              -H "Authorization: token ${TOKEN}" \
+              "${GITEA_URL}/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets" \
+              | python3 -c "import json,sys; t=sys.argv[1]; print(next((a['id'] for a in json.load(sys.stdin) if a.get('name')==t), ''))" "${filename}" || true)
+            if [ -n "${EXISTING_ID}" ]; then
+              echo "Replacing existing asset ${filename}"
+              curl -fsS -X DELETE \
+                -H "Authorization: token ${TOKEN}" \
+                "${GITEA_URL}/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets/${EXISTING_ID}"
+            fi
+            echo "Uploading ${filename}..."
+            curl -fsS --http1.1 --retry 5 --retry-all-errors --retry-delay 5 --max-time 600 \
+              -X POST \
+              -H "Authorization: token ${TOKEN}" \
+              -H "Content-Type: application/octet-stream" \
+              --data-binary "@${file}" \
+              "${GITEA_URL}/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets?name=${filename}"
+          done
+
+  build-windows:
+    runs-on: windows-latest
+    needs: [compute-version, create-release]
+    defaults:
+      run:
+        shell: cmd
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set app version
+        shell: powershell
+        run: |
+          $raw = "${{ needs.compute-version.outputs.version }}"
+          $version = $raw.Split('-')[0]
+          (Get-Content app/src-tauri/tauri.conf.json) -replace '"version": ".*?"', "`"version`": `"$version`"" | Set-Content app/src-tauri/tauri.conf.json
+          (Get-Content app/package.json) -replace '"version": ".*?"', "`"version`": `"$version`"" | Set-Content app/package.json
+          (Get-Content app/src-tauri/Cargo.toml) -replace '^version = ".*?"', "version = `"$version`"" | Set-Content app/src-tauri/Cargo.toml
+          Write-Host "Patched version to $version"
+
+      - name: Install Rust stable
+        run: |
+          where rustup >nul 2>&1 && (
+            rustup update stable
+            rustup default stable
+          ) || (
+            curl -fSL -o rustup-init.exe https://win.rustup.rs/x86_64
+            rustup-init.exe -y --default-toolchain stable
+            del rustup-init.exe
+          )
+
+      - name: Install Node.js
+        run: |
+          where node >nul 2>&1 && (
+            node --version
+          ) || (
+            curl -fSL -o node-install.msi "https://nodejs.org/dist/v22.14.0/node-v22.14.0-x64.msi"
+            msiexec /i node-install.msi /quiet /norestart
+            del node-install.msi
+          )
+
+      - name: Verify tools
+        run: |
+          set "PATH=%USERPROFILE%\.cargo\bin;C:\Program Files\nodejs;%PATH%"
+          rustc --version
+          cargo --version
+          node --version
+          npm --version
+
+      - name: Install Tauri CLI via cargo
+        run: |
+          set "PATH=%USERPROFILE%\.cargo\bin;C:\Program Files\nodejs;%PATH%"
+          cargo install tauri-cli --version "^2"
+
+      - name: Fix npm platform detection
+        run: |
+          set "PATH=%USERPROFILE%\.cargo\bin;C:\Program Files\nodejs;%PATH%"
+          npm config set os win32
+          npm config list
+
+      - name: Install frontend dependencies
+        working-directory: ./app
+        run: |
+          set "PATH=%USERPROFILE%\.cargo\bin;C:\Program Files\nodejs;%PATH%"
+          if exist node_modules rmdir /s /q node_modules
+          npm ci
+
+      - name: Build frontend
+        working-directory: ./app
+        run: |
+          set "PATH=%USERPROFILE%\.cargo\bin;C:\Program Files\nodejs;%PATH%"
+          npm run build
+
+      - name: Build Tauri app
+        working-directory: ./app
+        env:
+          TAURI_CONFIG: "{\"build\":{\"beforeBuildCommand\":\"\"}}"
+          # See the matching comment on the Linux job's "Build Tauri app" step.
+          TRIPLE_C_BUILD_SUFFIX: ${{ needs.compute-version.outputs.suffix }}
+        run: |
+          set "PATH=%USERPROFILE%\.cargo\bin;C:\Program Files\nodejs;%PATH%"
+          cargo tauri build
+
+      - name: Collect artifacts
+        run: |
+          set "PATH=%USERPROFILE%\.cargo\bin;C:\Program Files\nodejs;%PATH%"
+          mkdir artifacts
+          copy app\src-tauri\target\release\bundle\msi\*.msi artifacts\ 2>nul
+          copy app\src-tauri\target\release\bundle\nsis\*.exe artifacts\ 2>nul
+          dir artifacts\
+
+      # PowerShell, because this job's default shell is cmd. Same
+      # delete-then-upload shape as the other two.
+      - name: Upload Windows bundles to the preview release
+        shell: powershell
+        env:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          RELEASE_ID: ${{ needs.create-release.outputs.release_id }}
+        run: |
+          $ErrorActionPreference = "Stop"
+          $headers = @{ Authorization = "token $env:TOKEN" }
+          $api = "$env:GITEA_URL/api/v1/repos/$env:REPO"
+          $files = @(Get-ChildItem -File -Path artifacts\*)
+          if ($files.Count -eq 0) { throw "No Windows bundles were produced" }
+
+          $existing = Invoke-RestMethod -Method Get -Headers $headers -Uri "$api/releases/$env:RELEASE_ID/assets"
+          foreach ($file in $files) {
+            $name = $file.Name
+            $dupe = $existing | Where-Object { $_.name -eq $name }
+            if ($dupe) {
+              Write-Host "Replacing existing asset $name"
+              Invoke-RestMethod -Method Delete -Headers $headers -Uri "$api/releases/$env:RELEASE_ID/assets/$($dupe.id)" | Out-Null
+            }
+            Write-Host "Uploading $name..."
+            $uploadUri = "$api/releases/$env:RELEASE_ID/assets?name=$([uri]::EscapeDataString($name))"
+            curl.exe -fsS --retry 5 --retry-all-errors --retry-delay 5 --max-time 600 `
+              -X POST -H "Authorization: token $env:TOKEN" `
+              -H "Content-Type: application/octet-stream" `
+              --data-binary "@$($file.FullName)" $uploadUri
+            if ($LASTEXITCODE -ne 0) { throw "Upload of $name failed (curl exit $LASTEXITCODE)" }
+          }
+
+  # Keep the preview list short. Runs after the builds and only if all three
+  # succeeded: a half-published run must not be what evicts a good older build.
+  prune-previews:
+    runs-on: ubuntu-latest
+    needs: [create-release, build-linux, build-macos, build-windows]
+    steps:
+      - name: Delete all but the newest preview releases
+        env:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          KEEP_TAG: ${{ needs.create-release.outputs.tag }}
+        run: |
+          set -euo pipefail
+          curl -fsS -H "Authorization: token ${TOKEN}" \
+            "${GITEA_URL}/api/v1/repos/${REPO}/releases?limit=50" > releases.json
+
+          # Newest first by creation time, `preview-` only, and never the one
+          # this run just published — a clock skew must not delete it.
+          DOOMED=$(python3 - "${KEEP_PREVIEWS}" "${KEEP_TAG}" <<'PY'
+          import json, sys
+          keep, keep_tag = int(sys.argv[1]), sys.argv[2]
+          previews = [r for r in json.load(open("releases.json"))
+                      if r["tag_name"].startswith("preview-")]
+          previews.sort(key=lambda r: r["created_at"], reverse=True)
+          for r in previews[keep:]:
+              if r["tag_name"] != keep_tag:
+                  print(r["id"], r["tag_name"])
+          PY
+          )
+
+          if [ -z "${DOOMED}" ]; then
+            echo "Nothing to prune (keeping ${KEEP_PREVIEWS})"
+            exit 0
+          fi
+
+          echo "${DOOMED}" | while read -r ID TAG; do
+            [ -z "${ID}" ] && continue
+            echo "Deleting ${TAG} (id ${ID})"
+            # Best effort: a preview someone deleted by hand mid-run is not a
+            # reason to fail a build that otherwise succeeded.
+            curl -sS -X DELETE -H "Authorization: token ${TOKEN}" \
+              "${GITEA_URL}/api/v1/repos/${REPO}/releases/${ID}" || true
+            curl -sS -X DELETE -H "Authorization: token ${TOKEN}" \
+              "${GITEA_URL}/api/v1/repos/${REPO}/tags/${TAG}" || true
+          done

.gitea/workflows/build-app.yml

@@ -7,14 +7,14 @@ on:
       - "app/**"
       - "VERSION"
       - ".gitea/workflows/build-app.yml"
-  pull_request:
-    branches: [main]
-    paths:
-      - "app/**"
-      - "VERSION"
-      - ".gitea/workflows/build-app.yml"
   workflow_dispatch:
 
+# Deliberately **not** on pull_request. Every publishing step here is gated on
+# `gitea.event_name == 'push'`, so a PR run compiled all three platforms and
+# produced nothing — and it ran alongside build-app-preview.yml, which compiles
+# the same three and publishes them. Six OS builds per push, one set of which
+# was unreachable. Previews now carry the PR check; this workflow is releases.
+
 env:
   GITEA_URL: ${{ gitea.server_url }}
   REPO: ${{ gitea.repository }}
@@ -39,16 +39,55 @@ jobs:
           MAJOR_MINOR=$(cat VERSION | tr -d '[:space:]')
           echo "Major.Minor: ${MAJOR_MINOR}"
 
-          # Find the latest tag matching v{MAJOR_MINOR}.N (exclude -mac, -win suffixes)
-          # `|| true` so an empty grep result doesn't fail the step under pipefail.
-          LATEST_TAG=$(git tag -l "v${MAJOR_MINOR}.*" --sort=-v:refname | grep -E "^v${MAJOR_MINOR}\.[0-9]+$" | head -1 || true)
+          # The patch number is **one past the highest patch already used**, and
+          # never a distance.
+          #
+          # It used to be `git rev-list --count <highest tag>..HEAD`, which is
+          # not a counter at all: it measures how far HEAD has drifted from
+          # whichever tag sorts highest, and that resets to zero every time a
+          # tag is cut. The published history is the proof — each of these is
+          # exactly what the old formula returned at the time:
+          #
+          #   v0.4.0 -> 3 commits -> v0.4.3    looked fine
+          #   v0.4.3 -> 4 commits -> v0.4.4    fine by luck, 4 > 3
+          #   v0.4.4 -> 2 commits -> v0.4.2    went backwards
+          #   v0.4.4 -> 6 commits -> v0.4.6    jumped, skipping .5
+          #   v0.4.6 -> 3 commits -> v0.4.3    already taken; the upload failed
+          #
+          # Reusing a version is worse than failing to publish one: the macOS
+          # and Windows steps replace assets in place, so a duplicate silently
+          # rewrote a release that had been public for three days. Monotonic
+          # numbering is what stops that at the source.
+          #
+          # Suffixed tags count too. `create-tag` is skipped when any platform
+          # job fails, so a run can publish v0.4.7-mac and never create the
+          # plain v0.4.7 — reading only unsuffixed tags would then hand the
+          # same number out twice.
+          HIGHEST=$(git tag -l "v${MAJOR_MINOR}.*" \
+            | grep -E "^v${MAJOR_MINOR}\.[0-9]+(-mac|-win)?$" \
+            | sed -E "s/^v${MAJOR_MINOR}\.([0-9]+).*/\1/" \
+            | sort -n | tail -1 || true)
 
-          if [ -n "$LATEST_TAG" ]; then
-            echo "Latest matching tag: ${LATEST_TAG}"
-            PATCH=$(git rev-list --count "${LATEST_TAG}..HEAD")
+          # A re-run of a commit that already released must not mint a new
+          # version just because its own tag now exists.
+          EXISTING=$(git tag --points-at HEAD \
+            | grep -E "^v${MAJOR_MINOR}\.[0-9]+$" \
+            | sed -E "s/^v${MAJOR_MINOR}\.([0-9]+)$/\1/" \
+            | sort -n | tail -1 || true)
+
+          if [ -n "$EXISTING" ]; then
+            echo "HEAD is already tagged v${MAJOR_MINOR}.${EXISTING} — reusing it"
+            PATCH="${EXISTING}"
+          elif [ -n "$HIGHEST" ]; then
+            echo "Highest patch already used on this line: ${HIGHEST}"
+            PATCH=$((HIGHEST + 1))
           else
-            echo "No matching tag found for v${MAJOR_MINOR}.*, using total commit count"
-            PATCH=$(git rev-list --count HEAD)
+            # A minor line nobody has tagged yet is a *new* line, and a new line
+            # starts at .0 — that is what "we are moving to 0.4.x" means. The
+            # old fallback here counted every commit in the repository, which
+            # would have made the first 0.4 build 0.4.234.
+            echo "No v${MAJOR_MINOR}.* tag yet — starting this line at .0"
+            PATCH=0
           fi
 
           VERSION="${MAJOR_MINOR}.${PATCH}"
@@ -161,21 +200,70 @@ jobs:
         env:
           TOKEN: ${{ secrets.REGISTRY_TOKEN }}
         run: |
+          set -euo pipefail
           TAG="v${{ needs.compute-version.outputs.version }}"
-          # Create release
-          curl -s -X POST \
+
+          # Idempotent get-or-create, matching build-macos. This step used to
+          # POST /releases unconditionally: against a tag that already existed
+          # Gitea answered 409, the grep below found no id, and the run died
+          # with a bare "exitcode '1'" and not one line of output explaining
+          # it — `curl -s` with no `-f` swallows the HTTP error, so nothing
+          # ever said "409" or "duplicate tag". Hence -fsS throughout, and
+          # pipefail so a failure cannot be stepped over.
+          HTTP_CODE=$(curl -sS -o release.json -w '%{http_code}' \
             -H "Authorization: token ${TOKEN}" \
-            -H "Content-Type: application/json" \
-            -d "{\"tag_name\": \"${TAG}\", \"name\": \"Triple-C ${TAG} (Linux)\", \"body\": \"Automated build from commit ${{ gitea.sha }}\"}" \
-            "${GITEA_URL}/api/v1/repos/${REPO}/releases" > release.json
-          RELEASE_ID=$(cat release.json | grep -o '"id":[0-9]*' | head -1 | grep -o '[0-9]*')
+            "${GITEA_URL}/api/v1/repos/${REPO}/releases/tags/${TAG}")
+          case "${HTTP_CODE}" in
+            200)
+              echo "Release ${TAG} already exists, reusing"
+              ;;
+            404)
+              echo "Creating release ${TAG}"
+              curl -fsS -X POST \
+                -H "Authorization: token ${TOKEN}" \
+                -H "Content-Type: application/json" \
+                -d "{\"tag_name\": \"${TAG}\", \"name\": \"Triple-C ${TAG} (Linux)\", \"body\": \"Automated build from commit ${{ gitea.sha }}\"}" \
+                "${GITEA_URL}/api/v1/repos/${REPO}/releases" > release.json
+              ;;
+            *)
+              echo "Unexpected ${HTTP_CODE} looking up release ${TAG}:" >&2
+              cat release.json >&2
+              exit 1
+              ;;
+          esac
+
+          RELEASE_ID=$(python3 -c "import json,sys; print(json.load(open('release.json')).get('id',''))")
+          if [ -z "${RELEASE_ID}" ]; then
+            echo "No release id for ${TAG}; refusing to upload into nothing:" >&2
+            cat release.json >&2
+            exit 1
+          fi
           echo "Release ID: ${RELEASE_ID}"
-          # Upload each artifact
+
+          # Replace-not-conflict, so a retry after a partial upload succeeds.
+          # Versions are monotonic now (see compute-version), so this can only
+          # ever be replacing an asset from a failed run of this same commit —
+          # never one belonging to an already-published version.
           for file in artifacts/*; do
             [ -f "$file" ] || continue
             filename=$(basename "$file")
+
+            EXISTING_ID=$(curl -sS \
+              -H "Authorization: token ${TOKEN}" \
+              "${GITEA_URL}/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets" \
+              | python3 -c "import json,sys; t=sys.argv[1]; print(next((a['id'] for a in json.load(sys.stdin) if a.get('name')==t), ''))" "${filename}" || true)
+            if [ -n "${EXISTING_ID}" ]; then
+              echo "Deleting existing asset ${filename} (id ${EXISTING_ID})"
+              curl -fsS -X DELETE \
+                -H "Authorization: token ${TOKEN}" \
+                "${GITEA_URL}/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets/${EXISTING_ID}"
+            fi
+
             echo "Uploading ${filename}..."
-            curl -s -X POST \
+            curl -fsS --http1.1 \
+              --retry 5 --retry-all-errors --retry-delay 5 \
+              --max-time 600 \
+              -X POST \
               -H "Authorization: token ${TOKEN}" \
               -H "Content-Type: application/octet-stream" \
               --data-binary "@${file}" \
@@ -264,21 +352,72 @@ jobs:
         env:
           TOKEN: ${{ secrets.REGISTRY_TOKEN }}
         run: |
+          set -euo pipefail
           TAG="v${{ needs.compute-version.outputs.version }}-mac"
-          # Create release
-          curl -s -X POST \
+
+          # Idempotent get-or-create. macOS upload has historically failed
+          # mid-stream (curl exit 92, exit 28), leaving the release record
+          # with empty assets. A naive POST /releases on the next run hits
+          # 409 from Gitea for the duplicate tag, the JSON parse below
+          # then yields an empty RELEASE_ID, and pipefail aborts with an
+          # opaque exit 1. Look the release up by tag first; create only
+          # if it doesn't exist; reuse the existing id otherwise.
+          HTTP_CODE=$(curl -sS -o release.json -w '%{http_code}' \
             -H "Authorization: token ${TOKEN}" \
-            -H "Content-Type: application/json" \
-            -d "{\"tag_name\": \"${TAG}\", \"name\": \"Triple-C v${{ needs.compute-version.outputs.version }} (macOS)\", \"body\": \"Automated build from commit ${{ gitea.sha }}\"}" \
-            "${GITEA_URL}/api/v1/repos/${REPO}/releases" > release.json
-          RELEASE_ID=$(cat release.json | grep -o '"id":[0-9]*' | head -1 | grep -o '[0-9]*')
+            "${GITEA_URL}/api/v1/repos/${REPO}/releases/tags/${TAG}")
+          case "${HTTP_CODE}" in
+            200)
+              echo "Release ${TAG} already exists, reusing"
+              ;;
+            404)
+              echo "Release ${TAG} not found, creating"
+              curl -fsS -X POST \
+                -H "Authorization: token ${TOKEN}" \
+                -H "Content-Type: application/json" \
+                -d "{\"tag_name\": \"${TAG}\", \"name\": \"Triple-C v${{ needs.compute-version.outputs.version }} (macOS)\", \"body\": \"Automated build from commit ${{ gitea.sha }}\"}" \
+                "${GITEA_URL}/api/v1/repos/${REPO}/releases" > release.json
+              ;;
+            *)
+              echo "Unexpected HTTP ${HTTP_CODE} from get-release-by-tag" >&2
+              cat release.json >&2 || true
+              exit 1
+              ;;
+          esac
+
+          RELEASE_ID=$(grep -o '"id":[0-9]*' release.json | head -1 | grep -o '[0-9]*' || true)
+          if [ -z "${RELEASE_ID}" ]; then
+            echo "Failed to parse release id; response was:" >&2
+            cat release.json >&2
+            exit 1
+          fi
           echo "Release ID: ${RELEASE_ID}"
-          # Upload each artifact
+
+          # Upload each artifact. If an asset with the same name already
+          # exists on the release (left over from a partial prior run),
+          # delete it first so the upload is replace-not-conflict.
+          # Network hardening: HTTP/1.1 to dodge HTTP/2 stream flakes
+          # the macOS runner has hit, retries with backoff for transient
+          # drops, and -f so HTTP errors stop being silently swallowed.
           for file in artifacts/*; do
             [ -f "$file" ] || continue
             filename=$(basename "$file")
+
+            EXISTING_ID=$(curl -sS \
+              -H "Authorization: token ${TOKEN}" \
+              "${GITEA_URL}/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets" \
+              | python3 -c "import json,sys; t=sys.argv[1]; print(next((a['id'] for a in json.load(sys.stdin) if a.get('name')==t), ''))" "${filename}" || true)
+            if [ -n "${EXISTING_ID}" ]; then
+              echo "Deleting existing asset ${filename} (id ${EXISTING_ID})"
+              curl -fsS -X DELETE \
+                -H "Authorization: token ${TOKEN}" \
+                "${GITEA_URL}/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets/${EXISTING_ID}"
+            fi
+
             echo "Uploading ${filename}..."
-            curl -s -X POST \
+            curl -fsS --http1.1 \
+              --retry 5 --retry-all-errors --retry-delay 5 \
+              --max-time 600 \
+              -X POST \
               -H "Authorization: token ${TOKEN}" \
               -H "Content-Type: application/octet-stream" \
               --data-binary "@${file}" \
@@ -306,6 +445,77 @@ jobs:
           (Get-Content app/src-tauri/Cargo.toml) -replace '^version = ".*?"', "version = `"$version`"" | Set-Content app/src-tauri/Cargo.toml
           Write-Host "Patched version to $version"
 
+      - name: Install MSVC C++ build tools
+        shell: cmd
+        run: |
+          rem Tauri links with MSVC, so rustc needs link.exe and the Windows SDK.
+          rem This job previously assumed a hand-provisioned runner; a runner
+          rem without them registers fine, advertises windows-latest, accepts the
+          rem job, downloads the whole crate graph and only then fails at link
+          rem time with "linker `link.exe` not found".
+          rem
+          rem rustc finds MSVC via vswhere and the registry rather than PATH, so
+          rem installing is enough - no dev-shell activation needed here.
+          rem
+          rem Delayed expansion is required: %VAR% inside a parenthesised block
+          rem is substituted when the block is PARSED, not when it runs, so both
+          rem %ERRORLEVEL% and %VSEXIT% would read as their pre-block values.
+          setlocal enabledelayedexpansion
+          set "VCPATH="
+          set "VSWHERE=%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\vswhere.exe"
+          if exist "%VSWHERE%" (
+            for /f "usebackq delims=" %%i in (`"%VSWHERE%" -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath`) do set "VCPATH=%%i"
+          )
+          if defined VCPATH (
+            echo MSVC build tools already present at !VCPATH!
+          ) else (
+            echo MSVC build tools not found - installing Visual Studio Build Tools
+            curl -fSL -o "%TEMP%\vs_BuildTools.exe" https://aka.ms/vs/17/release/vs_BuildTools.exe || exit /b 1
+            "%TEMP%\vs_BuildTools.exe" --quiet --wait --norestart --nocache --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended
+            set "VSEXIT=!ERRORLEVEL!"
+            del "%TEMP%\vs_BuildTools.exe" 2>nul
+            rem 3010 means installed, reboot pending - a success for our purposes.
+            if not "!VSEXIT!"=="0" if not "!VSEXIT!"=="3010" (
+              echo Visual Studio Build Tools installer failed with exit code !VSEXIT!
+              exit /b 1
+            )
+            echo Visual Studio Build Tools installed
+          )
+          endlocal
+
+      - name: Work around WOW64 redirection for 32-bit bundlers
+        shell: cmd
+        run: |
+          rem Tauri downloads its bundlers - candle.exe, light.exe and
+          rem makensis.exe - and every one of them is 32-bit. When the runner
+          rem runs as SYSTEM its %LOCALAPPDATA% is under
+          rem C:\Windows\System32\config\systemprofile, and WOW64 redirection
+          rem serves any 32-bit process reading System32 from SysWOW64 instead -
+          rem where those directories do not exist. The bundlers then cannot see
+          rem their own folder: candle exits 0x80131700 and makensis reports
+          rem "Unable to start child process, error 0x2". Tauri surfaces neither,
+          rem only "failed to run candle.exe", which is why this is worth a
+          rem comment this long.
+          rem
+          rem Junctioning the SysWOW64 view onto the System32 originals makes the
+          rem redirected path resolve to the same files. A runner running as a
+          rem normal user has a profile outside System32 and skips all of this.
+          echo.%LOCALAPPDATA%| find /I "\system32\" >nul
+          if errorlevel 1 goto skipwow
+
+          if not exist "%WINDIR%\System32\config\systemprofile\AppData\Local\tauri" mkdir "%WINDIR%\System32\config\systemprofile\AppData\Local\tauri"
+          if not exist "%WINDIR%\SysWOW64\config\systemprofile\AppData\Local" mkdir "%WINDIR%\SysWOW64\config\systemprofile\AppData\Local"
+          if not exist "%WINDIR%\SysWOW64\config\systemprofile\AppData\Local\tauri" mklink /J "%WINDIR%\SysWOW64\config\systemprofile\AppData\Local\tauri" "%WINDIR%\System32\config\systemprofile\AppData\Local\tauri"
+
+          if not exist "%WINDIR%\System32\config\systemprofile\.cache" mkdir "%WINDIR%\System32\config\systemprofile\.cache"
+          if not exist "%WINDIR%\SysWOW64\config\systemprofile\.cache" mklink /J "%WINDIR%\SysWOW64\config\systemprofile\.cache" "%WINDIR%\System32\config\systemprofile\.cache"
+
+          echo WOW64 junctions in place for the SYSTEM profile
+          goto :eof
+
+          :skipwow
+          echo Runner profile is outside System32 - WOW64 junctions not needed
+
       - name: Install Rust stable
         run: |
           where rustup >nul 2>&1 && (
@@ -365,32 +575,86 @@ jobs:
           TAURI_CONFIG: "{\"build\":{\"beforeBuildCommand\":\"\"}}"
         run: |
           set "PATH=%USERPROFILE%\.cargo\bin;C:\Program Files\nodejs;%PATH%"
-          cargo tauri build
+          rem Every Tauri bundler it downloads - candle.exe, light.exe and
+          rem makensis.exe - is 32-bit. A runner running as SYSTEM has
+          rem %LOCALAPPDATA% under C:\Windows\system32\config\systemprofile, and
+          rem WOW64 redirection sends 32-bit processes reading System32 to
+          rem SysWOW64, so they cannot see their own directory: candle exits
+          rem 0x80131700 and makensis reports "Unable to start child process,
+          rem error 0x2".
+          rem
+          rem The build VM carries junctions from the SysWOW64 view of
+          rem systemprofile\AppData\Local\tauri and systemprofile\.cache to the
+          rem System32 originals, which makes the redirected view resolve. A
+          rem runner running as a normal user needs no such patch.
+          cargo tauri build --bundles msi,nsis
 
       - name: Collect artifacts
         run: |
           set "PATH=%USERPROFILE%\.cargo\bin;C:\Program Files\nodejs;%PATH%"
           mkdir artifacts
-          copy app\src-tauri\target\release\bundle\msi\*.msi artifacts\ 2>nul
-          copy app\src-tauri\target\release\bundle\nsis\*.exe artifacts\ 2>nul
+          copy app\src-tauri\target\release\bundle\msi\*.msi artifacts\ || exit /b 1
+          copy app\src-tauri\target\release\bundle\nsis\*.exe artifacts\ || exit /b 1
           dir artifacts\
 
       - name: Upload to Gitea release
         if: gitea.event_name == 'push'
+        shell: powershell
         env:
           TOKEN: ${{ secrets.REGISTRY_TOKEN }}
           COMMIT_SHA: ${{ gitea.sha }}
+          VERSION: ${{ needs.compute-version.outputs.version }}
         run: |
-          set "TAG=v${{ needs.compute-version.outputs.version }}-win"
-          echo Creating release %TAG%...
-          curl -s -X POST -H "Authorization: token %TOKEN%" -H "Content-Type: application/json" -d "{\"tag_name\": \"%TAG%\", \"name\": \"Triple-C v${{ needs.compute-version.outputs.version }} (Windows)\", \"body\": \"Automated build from commit %COMMIT_SHA%\"}" "%GITEA_URL%/api/v1/repos/%REPO%/releases" > release.json
-          for /f "tokens=2 delims=:," %%a in ('findstr /c:"\"id\"" release.json') do set "RELEASE_ID=%%a" & goto :found
-          :found
-          echo Release ID: %RELEASE_ID%
-          for %%f in (artifacts\*) do (
-            echo Uploading %%~nxf...
-            curl -s -X POST -H "Authorization: token %TOKEN%" -H "Content-Type: application/octet-stream" --data-binary "@%%f" "%GITEA_URL%/api/v1/repos/%REPO%/releases/%RELEASE_ID%/assets?name=%%~nxf"
-          )
+          $ErrorActionPreference = "Stop"
+          $tag = "v$env:VERSION-win"
+          $headers = @{ Authorization = "token $env:TOKEN" }
+          $api = "$env:GITEA_URL/api/v1/repos/$env:REPO"
+
+          # Idempotent get-or-create. The old cmd-batch version swallowed
+          # curl errors and parsed the release id with findstr, so a 409 on
+          # a pre-existing tag yielded an empty RELEASE_ID and uploads went to
+          # a malformed .../releases//assets URL while the step still reported
+          # success. Look the release up by tag first; create only on 404.
+          try {
+            $release = Invoke-RestMethod -Method Get -Headers $headers -Uri "$api/releases/tags/$tag"
+            Write-Host "Release $tag already exists, reusing"
+          } catch {
+            if ($_.Exception.Response.StatusCode.value__ -eq 404) {
+              Write-Host "Release $tag not found, creating"
+              $body = @{
+                tag_name = $tag
+                name     = "Triple-C v$env:VERSION (Windows)"
+                body     = "Automated build from commit $env:COMMIT_SHA"
+              } | ConvertTo-Json
+              $release = Invoke-RestMethod -Method Post -Headers $headers `
+                -ContentType "application/json" -Body $body -Uri "$api/releases"
+            } else {
+              throw
+            }
+          }
+
+          $releaseId = $release.id
+          if (-not $releaseId) { throw "Failed to resolve release id for $tag" }
+          Write-Host "Release ID: $releaseId"
+
+          # Upload each artifact. Delete any same-named asset left over from a
+          # partial prior run first, so the upload replaces rather than 409s.
+          $existing = Invoke-RestMethod -Method Get -Headers $headers -Uri "$api/releases/$releaseId/assets"
+          foreach ($file in Get-ChildItem -File -Path artifacts\*) {
+            $name = $file.Name
+            $dupe = $existing | Where-Object { $_.name -eq $name }
+            if ($dupe) {
+              Write-Host "Deleting existing asset $name (id $($dupe.id))"
+              Invoke-RestMethod -Method Delete -Headers $headers -Uri "$api/releases/$releaseId/assets/$($dupe.id)" | Out-Null
+            }
+            Write-Host "Uploading $name..."
+            $uploadUri = "$api/releases/$releaseId/assets?name=$([uri]::EscapeDataString($name))"
+            curl.exe -fsS --retry 5 --retry-all-errors --retry-delay 5 --max-time 600 `
+              -X POST -H "Authorization: token $env:TOKEN" `
+              -H "Content-Type: application/octet-stream" `
+              --data-binary "@$($file.FullName)" $uploadUri
+            if ($LASTEXITCODE -ne 0) { throw "Upload of $name failed (curl exit $LASTEXITCODE)" }
+          }
 
   create-tag:
     runs-on: ubuntu-latest

.gitea/workflows/secret-scan.yml

@@ -0,0 +1,32 @@
+name: Secret Scan
+
+# **No `paths:` filter, deliberately.** The credential this exists for lived in
+# `app/src-tauri/src/docker/container.rs`, which `build.yml` would have skipped —
+# that workflow only runs for `container/**`. A scan that can be avoided by
+# touching the wrong directory is not a scan.
+#
+# This is the half of the check that nobody can bypass. The pre-commit hook in
+# `.githooks/` is faster and friendlier, but it is opt-in per clone and
+# `--no-verify` skips it; both are true of every git hook and neither is fixable
+# from inside a repository.
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # The whole tracked tree, not just the diff. Scanning a range is cheaper
+      # but depends on getting the range right across pushes, force-pushes,
+      # merges and PR events — and a wrong range fails *open*. The full scan
+      # takes under half a second on this repository and cannot be evaded by
+      # arranging for the interesting commit to sit outside the window.
+      - name: Scan tracked files for credentials
+        run: sh scripts/scan-secrets.sh --tracked

.gitea/workflows/sync-release.yml

@@ -1,59 +0,0 @@
-name: Sync Release to GitHub
-
-on:
-  workflow_dispatch:
-
-jobs:
-  sync-release:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Mirror release to GitHub
-        env:
-          GH_PAT: ${{ secrets.GH_PAT }}
-          GITHUB_REPO: shadowdao/triple-c
-          RELEASE_TAG: ${{ gitea.event.release.tag_name }}
-          RELEASE_NAME: ${{ gitea.event.release.name }}
-          RELEASE_BODY: ${{ gitea.event.release.body }}
-          IS_PRERELEASE: ${{ gitea.event.release.prerelease }}
-          IS_DRAFT: ${{ gitea.event.release.draft }}
-        run: |
-          set -e
-
-          echo "==> Creating release $RELEASE_TAG on GitHub..."
-
-          RESPONSE=$(curl -sf -X POST \
-            -H "Authorization: Bearer $GH_PAT" \
-            -H "Accept: application/vnd.github+json" \
-            -H "Content-Type: application/json" \
-            https://api.github.com/repos/$GITHUB_REPO/releases \
-            -d "{
-              \"tag_name\": \"$RELEASE_TAG\",
-              \"name\": \"$RELEASE_NAME\",
-              \"body\": $(echo "$RELEASE_BODY" | jq -Rs .),
-              \"draft\": $IS_DRAFT,
-              \"prerelease\": $IS_PRERELEASE
-            }")
-
-          UPLOAD_URL=$(echo "$RESPONSE" | jq -r '.upload_url' | sed 's/{?name,label}//')
-          echo "Release created. Upload URL: $UPLOAD_URL"
-
-          echo '${{ toJSON(gitea.event.release.assets) }}' | jq -c '.[]' | while read asset; do
-            ASSET_NAME=$(echo "$asset" | jq -r '.name')
-            ASSET_URL=$(echo "$asset" | jq -r '.browser_download_url')
-
-            echo "==> Downloading asset: $ASSET_NAME"
-            curl -sfL -o "/tmp/$ASSET_NAME" "$ASSET_URL"
-
-            echo "==> Uploading $ASSET_NAME to GitHub..."
-            ENCODED_NAME=$(python3 -c "import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1]))" "$ASSET_NAME")
-            curl -sf -X POST \
-              -H "Authorization: Bearer $GH_PAT" \
-              -H "Accept: application/vnd.github+json" \
-              -H "Content-Type: application/octet-stream" \
-              --data-binary "@/tmp/$ASSET_NAME" \
-              "$UPLOAD_URL?name=$ENCODED_NAME"
-
-            echo "  Uploaded: $ASSET_NAME"
-          done
-
-          echo "==> Release sync complete."

.githooks/pre-commit

@@ -0,0 +1,14 @@
+#!/bin/sh
+# Refuse a commit that adds something shaped like a live credential.
+#
+# Installed by pointing git at this directory:
+#
+#     git config core.hooksPath .githooks
+#
+# which `npm run hooks` in app/ does for you. It is per-clone — git will not let
+# a repository configure its own hooks path, for the obvious reason that cloning
+# a repo would then be enough to run its code. So this is opt-in on every
+# machine, `--no-verify` skips it, and neither of those is a flaw to fix here:
+# the CI job in `.gitea/workflows/build.yml` is the half nobody can bypass. The
+# hook exists to tell you in one second rather than in five minutes.
+exec "$(git rev-parse --show-toplevel)/scripts/scan-secrets.sh" --staged

.gitignore

@@ -3,3 +3,13 @@ app/dist/
 app/src-tauri/target/
 Screenshot*.png
 code-review.md
+
+# Windows NTFS alternate-data-stream artifacts, created when files arrive
+# through the WSL/host bind mount.
+*:Zone.Identifier
+
+# Local bug-report screenshots, same spirit as Screenshot*.png above.
+screenshot_for_fix/
+
+# Package files pulled in by ad-hoc verification runs.
+*.deb

CLAUDE.md

@@ -56,38 +56,418 @@ docker exec stdout → tokio task → emit("terminal-output-{sessionId}") → li
 
 ### Frontend Structure (`app/src/`)
 
-- **`store/appState.ts`** — Single Zustand store for all app state (projects, sessions, UI)
+- **`store/appState.ts`** — Single Zustand store for all app state (projects, sessions, UI). The
+  main area is a single ordered tab strip holding two tab kinds, keyed `term:<id>` and
+  `home:<id>`; `activeSessionId` is *derived* from `activeTabKey` so exactly one thing is current.
+  `tabOrder` is user-reorderable (drag, or `Ctrl+Shift+←/→` via `moveActiveTab`) — so **never
+  treat a tab's position as identity**: address tabs by key, and index only through `tabOrder`.
+  `moveTab` deliberately does not activate what it moves.
+  - **The tab drag is pointer events, not HTML5 drag-and-drop, and must stay that way.** Tauri's
+    `dragDropEnabled` blocks HTML5 drag inside the webview on Windows, and it cannot simply be
+    turned off: `TerminalView` needs Tauri's native drag-drop event because it is the only one
+    that carries dropped *file paths*. An HTML5 drag also carries a `DataTransfer`, which the
+    default handler types into any text field the drag is released over.
+  - **A new app-level shortcut must not swallow a text-editing chord.** `useKeyboardShortcuts`
+    binds on `document` in the capture phase, so `inTextField()` guards the arrow bindings —
+    excluding xterm's helper textarea, which is an input-method shim rather than a field.
 - **`hooks/`** — All Tauri IPC calls are encapsulated in hooks (`useTerminal`, `useProjects`, `useDocker`, `useSettings`)
 - **`lib/tauri-commands.ts`** — Typed `invoke()` wrappers; TypeScript types in `lib/types.ts` must match Rust models
 - **`components/terminal/TerminalView.tsx`** — xterm.js integration with WebGL rendering, URL detection for OAuth flow
-- **`components/layout/`** — TopBar (tabs + status), Sidebar (project list), StatusBar
-- **`components/projects/`** — ProjectCard, ProjectList, AddProjectDialog
-- **`components/settings/`** — Settings panels for API keys, Docker, AWS, Web Terminal
+- **`components/layout/`** — TopBar, MainTabs (the unified tab strip), Sidebar, StatusBar
+- **`components/projects/`** — `ProjectRow` (select-only list row), `ProjectList`, `AddProjectDialog`,
+  and the editors reused by Project Home
+- **`components/projects/home/`** — **Project Home**, the main-area view for a project:
+  Overview / Sessions / Automation / Config / Files. Per-project configuration lives here, not in
+  modals — see "UI conventions" below.
+  - **The Files pane's host transfers open their dialog from Rust, and that is the whole
+    design — do not move it back into the webview.** The tab browses, views (text and image),
+    renames and creates folders inside the container (`list_container_files`,
+    `read_container_file`, `rename_container_path`, `create_container_directory`), and it
+    copies single files in and out (`upload_files_to_container`, `download_container_file`).
+    The second pair call `pick_files_to_upload` / `pick_save_path`, which drive
+    `tauri-plugin-dialog` from the *backend*: the webview can ask for a picker and that is the
+    entirety of its influence — it cannot name a host path as an *input*. The claim stops
+    there and should not be widened: host paths still travel outward in error text, canonical
+    ones included. What is closed is the direction that produced the criticals.
+    That shape is not decoration. Four successive audits found that host filesystem paths
+    crossing IPC were where the criticals lived — a caller-named host destination for
+    container-controlled bytes, an arbitrary host source read into the container, a `link(2)`
+    upload reservation that succeeded against a directory and failed forever on any filesystem
+    without hard links. The feature was removed rather than fixed a fifth time, and it came
+    back only in the shape that removes the class: a frontend-driven dialog handing Rust a
+    string is the exact thing that failed, so re-introducing `open()`/`save()` in `FilesTab`
+    would undo the whole point while looking like a simplification.
+    None of the reservation machinery came back with it. There is no destination reservation,
+    no placeholder rollback and no collision marker — the OS save dialog already asks about
+    overwriting, and Docker's archive extractor overwrites on upload the way `cp` does.
+  - **Drag-and-drop is still not it.** There is no drop-into-the-Files-pane and no OS
+    drag-out; the buttons are the gesture. A file also gets *in* by being dropped on the
+    Terminal, and a whole tree comes *out* through "Back up container" — those two predate the
+    Files work and their hardening is not to be weakened. `TerminalView`'s `onDragDropEvent`
+    is Tauri's native drop event (window-wide, so routed by `lib/dropTarget.ts` — geometry for
+    *whose* drop it is, a document-wide `dropIsBlocked` for whether the app should accept one
+    at all; keep both halves and keep `PaneVisibility`). Backup is
+    `file_commands::download_container_backup`.
+  - **`resolve_host_path` applies the full lexical predicate twice — as written, and again
+    after canonicalisation.** That includes the general hidden-component rule, which
+    deliberately over-catches: a path resolving through `node_modules/.pnpm`, `~/.cache` or
+    `~/.local/share` is refused. Do not narrow it back to a list of "credential" directories.
+    That was tried, and allow-by-omission let `~/.local/bin` (write there and you own the
+    user's next shell command), `~/.password-store`, browser profiles and `~/.pki/nssdb`
+    through a planted symlink with a perfectly visible name. Over-refusing is the cheaper
+    mistake. Note the cost is real and has grown: of the four callers, the Files pane's two
+    are routine, and their path comes from a dialog — so an over-catch refuses a destination a
+    person actually chose (`~/.config` is the common one). Accepted, and not a reason to
+    narrow the rule, because the terminal drop and `download_container_backup` still take
+    their host path over IPC and this predicate is their only boundary.
+  - **OS drag-out is not here.** `tauri-plugin-drag`, `stage_container_file_for_drag` and its
+    host staging directory were held back for separate hardening and live on
+    `hold/disk-and-dragout`. Do not re-add `drag:allow-start-drag` or a staging command
+    without taking that work back whole: the plugin has no scope mechanism, so the grant lets
+    a compromised webview start a drag on *any* host path the user can read, and the staging
+    directory is a host-temp disk leak with a gesture attached unless its exit-clear and
+    startup-reap come back with it.
+- **`components/settings/`** — Host-level settings: Docker, AWS, Web Terminal, STT, shared auth.
+  There is deliberately **no Disk panel** here. The disk survey and its reclaim / destroy /
+  compaction surface were held back for separate hardening and live on `hold/disk-and-dragout`;
+  one of their IPC commands was a verified arbitrary-DELETE primitive, so if that work returns it
+  returns whole, `generate_handler!` entries and typed confirmations included. The *prevention*
+  half stayed and is not disk-panel code: the pre-commit scrub in `docker/container.rs`, capped
+  container logs, the `triple-c.base` / `triple-c.managed` labels, `sweep_orphaned_snapshots` and
+  the startup housekeeping in `lib.rs`, the migration reapers, and `project_lock.rs`.
+- **`components/ui/`** — Shared primitives. **Use these; do not hand-roll replacements.**
+  `Modal` (the only correct way to build a dialog — it supplies `role="dialog"`, `aria-modal`,
+  focus trap and restore), `Button`, `Toggle`, `Field`, `SegmentedControl`, `StatusIndicator`,
+  `SaveIndicator`, `OverflowMenu`, `ToastHost`, `Tooltip`
+
+### UI conventions
+
+- **Project config belongs in Project Home's Config tab, not a modal.** Modals are reserved for
+  short, genuinely modal tasks (add project, confirm removal, token acquisition). The app
+  previously had ~12 hand-rolled modals; they were consolidated deliberately.
+- **Never bypass the design tokens.** All colour comes from CSS custom properties in `index.css`.
+  Filled buttons use `--accent-emphasis` (not `--accent`, which fails WCAG AA against white).
+  Use `--text-disabled` rather than `disabled:opacity-50`.
+- **Never write `focus:outline-none`.** A global `:focus-visible` ring is defined in `index.css`.
+- **Status must not be encoded in colour alone** — `StatusIndicator` pairs a glyph with a word.
+- Keyboard: `Ctrl+T` new terminal, `Ctrl+Shift+W` close tab, `Ctrl+Tab` cycle, `Ctrl+1..9` jump,
+  `Ctrl+Shift+←/→` move the active tab. `Ctrl+W` is intentionally left alone — it is readline's
+  `kill-word` inside the terminal, and plain `Ctrl+←/→` is its word-wise cursor motion, which is
+  why tab-moving takes Shift.
 
 ### Backend Structure (`app/src-tauri/src/`)
 
-- **`commands/`** — Tauri command handlers (docker, project, settings, terminal). These are the IPC entry points called by `invoke()`.
+- **`commands/`** — Tauri command handlers. These are the IPC entry points called by `invoke()`.
+  Beyond docker/project/settings/terminal: `inspect_commands.rs` (read-only views into a
+  container — Claude sessions, installed capabilities, scheduler tasks), `auth_bridge_commands.rs`,
+  `auth_token_commands.rs`.
+- **`auth_bridge/`** — Host-side loopback bridge so browser logins run *inside* a container can
+  complete against the host browser. Discovers listeners by parsing `/proc/net/tcp{,6}` (the image
+  has no `ss`/`netstat`/`lsof`), binds host `127.0.0.1` **only**, and tunnels in over the Docker
+  API via `socat`. Opt-in per project.
+- **`browser_view/`** — Watch and take over the browser Claude drives with Playwright inside the
+  container. Runs Playwright's own dashboard (`browser.bind()` + `playwright-cli show`) in the
+  container and fronts it with a **token-gated** loopback proxy. Deliberately does **not** reuse
+  the auth bridge's `PortForward`, which binds an unauthenticated port — fine for a throwaway
+  OAuth listener, wrong for remote control of a browser. Host ports are confined to
+  `47820..=47827` because CSP `frame-src` cannot express a port range and must enumerate them;
+  a unit test asserts the Rust range matches `tauri.conf.json`. Opt-in per project.
+  - **`popout.rs` puts the same URL in a second OS window** (`WebviewUrl::External`), so the view
+    can be watched on another monitor or pinned on top while the main window is used for work.
+    Three things it rests on: no capability lists that window, so it has **no IPC surface** — do
+    not give it one; the app CSP does not apply, because it is a top-level document rather than a
+    frame, and the token gate is what protects the port in both cases; and the window is owned by
+    the *session*, so the supervisor's teardown closes it rather than leaving a window onto a
+    viewer that no longer exists. It closes with `destroy()`, never `close()`, to stay clear of
+    `CloseRequested`. The pane drops its iframe while popped out — two viewers can both *drive*
+    the browser.
+  - **`page.rs` opens a page, which is the one thing the pane could not do.** A URL plus a
+    viewport: launch a browser in the container, `browser.bind()` it so the pane shows it, and
+    keep the handle. Serves auth (the OAuth callback listener is *in* the container, so a
+    container-side browser closes the loop with no host round trip and no auth bridge) and dev
+    servers on container loopback. **Verified: a second client cannot join a bound browser** —
+    `chromium.connect()` against the published endpoint times out in every URL form, because that
+    socket speaks the dashboard's transport, not the public connect protocol. So whoever launches
+    is the only process that can drive, which is why the helper is resident and why live resize
+    applies to pages *we* opened and never to `@playwright/mcp`'s (those take `--viewport-size` /
+    `PLAYWRIGHT_MCP_VIEWPORT_SIZE` at launch). Control is a polled JSON file in `/tmp` — no port,
+    no second listener — and a re-open with a helper already up *navigates* rather than
+    relaunching, so a session signed in on one page survives to the next.
+  - **Resizing the window does not resize the page.** The viewer is a CDP screencast: a bigger
+    window is the same pixels drawn larger. `page.setViewportSize()` is what reflows (measured
+    against a `@media (max-width: 900px)` rule), and match-window mode pushes the pop-out's
+    settled `Resized` size into it — debounced by generation counter, since a drag emits
+    continuously and each one costs a container exec.
+  - **`lib.rs`'s `on_window_event` fires for every window and must stay guarded on
+    `label() == "main"`.** Without that guard, closing a pop-out runs the app's shutdown: every
+    container stopped, process exited.
+  - **Detection has to look past `node_modules`.** `claude mcp add … npx @playwright/mcp@latest`
+    installs into `~/.npm/_npx/<hash>/node_modules`, not any `node_modules`, so `detect.rs`
+    globs that cache as well as `/workspace`, `$HOME/node_modules` and `npm root -g`. It also
+    hops from a wrapper `playwright` to its **nested** `playwright-core`: verified that npm does
+    not hoist for global installs, and the wrapper ships no `types/types.d.ts`, so reading the
+    wrapper alone reports a current build as "predates `browser.bind()`".
+  - **`@playwright/mcp` can never satisfy this pane.** It bundles a `playwright-core` that binds,
+    but never `@playwright/cli`, which is the viewer. Never offer it as a setup route — only as
+    what binds sessions automatically once Playwright is present.
+  - **`install.rs` installs into `/workspace`, as `claude`, with `--no-save`.** `/workspace` is
+    *not* a bind mount — project directories are mounted at `/workspace/{mount_name}` — so this
+    touches nothing of the user's, needs no sudo (npm's prefix is `/usr`, which is root-owned),
+    and is on the module resolution path for scripts in the project. Browsers go to
+    `~/.cache/ms-playwright` as `claude`, i.e. the home volume.
+  - **Current base images ship Chromium's shared libraries; older ones do not** — and a project
+    keeps the base image it was first built from until it is migrated, so "older" is the normal
+    case. Without them `playwright install chromium` downloads a browser that cannot launch, which
+    is why installing Chrome via apt looks like a fix. `install.rs` asks
+    `install-deps --dry-run` first and skips the apt step when the answer is "all present",
+    *saying so* in the progress stream. Do not decide this by probing for library names: the
+    dry-run simulates the same `apt-get install` the fix would run, so check and fix cannot
+    disagree about what the dependency set is. Note that `--dry-run` exits **0** both when
+    everything is installed and when Playwright has no list for the platform — match on its
+    output, not its exit code. Either way the action ends by *actually launching* the browser to
+    verify. `@playwright/mcp` wants the `chrome` **channel** specifically, so both browsers are
+    offered.
 - **`docker/`** — Docker API layer using bollard:
   - `client.rs` — Singleton Docker connection via `OnceLock`
   - `container.rs` — Container lifecycle (create, start, stop, remove, inspect)
-  - `exec.rs` — PTY exec sessions with bidirectional stdin/stdout streaming
+  - `exec.rs` — Attached exec streaming. `create_attached_exec()` is the **single** place an
+    attached exec is opened; terminal sessions and the auth bridge both go through it.
   - `image.rs` — Image build/pull with progress streaming
+  - `gateway.rs` — Optional LiteLLM sibling container giving Claude Code an Anthropic-format
+    front end for providers that only speak OpenAI (see `gateway-container/`). Mirrors `stt.rs`.
+    Its bind address is **detected, never `0.0.0.0`** — unlike STT, *project containers* consume
+    it, so loopback alone is not always enough: Docker Desktop gets `127.0.0.1` (containers reach
+    it via `host.docker.internal`), native Linux gets the default bridge gateway (`172.17.0.1`).
+    `GatewayBinding` derives the bind address and the advertised `base_url` together so they
+    cannot drift. A wildcard bind would be LAN-reachable — Docker's rules precede host firewalls —
+    in front of a container config holding a billed provider key. It also **always** sets a
+    LiteLLM `master_key`, since LiteLLM without one accepts any key.
+  - `migration.rs` — Base-image migration: manifest capture via throwaway containers, the pure
+    delta computation (dpkg-ownership filter, bind-mount exclusion, verbatim-copy set), and the
+    crash-recovery state machine. See "Base-image migration" below.
+  - `legacy_cleanup.rs` — One-release migration shim removing leftovers from the deleted MCP
+    feature (containers labelled `triple-c.mcp-server`, `triple-c-net-*` networks). Deletable once
+    users have migrated.
 - **`web_terminal/`** — Remote terminal access via axum HTTP+WebSocket server:
   - `server.rs` — Axum server lifecycle (start/stop), serves embedded HTML and handles WS upgrades
   - `ws_handler.rs` — Per-connection WebSocket handler with JSON protocol, session management, cleanup on disconnect
   - `terminal.html` — Self-contained xterm.js web UI embedded via `include_str!()`
-- **`models/`** — Serde structs (`Project`, `Backend`, `BedrockConfig`, `OllamaConfig`, `OpenAiCompatibleConfig`, `ClaudeCodeSettings`, `ContainerInfo`, `AppSettings`, `WebTerminalSettings`). These define the IPC contract with the frontend.
+- **`models/`** — Serde structs (`Project`, `Backend`, `BedrockConfig`, `OllamaConfig`, `LlamaCppConfig`, `OpenAiCompatibleConfig`, `ClaudeCodeSettings`, `ContainerInfo`, `AppSettings`, `WebTerminalSettings`). These define the IPC contract with the frontend.
 - **`storage/`** — Persistence: `projects_store.rs` (JSON file with atomic writes), `secure.rs` (OS keychain via `keyring` crate), `settings_store.rs`
 
 ### Container (`container/`)
 
-- **`Dockerfile`** — Ubuntu 24.04 base with Claude Code, Node.js 22, Python 3.12, Rust, Docker CLI, git, gh, AWS CLI v2, ripgrep, pnpm, uv, ruff pre-installed
+- **`Dockerfile`** — Ubuntu 24.04 base with Claude Code, Node.js 22, Python 3.12, Rust, Docker CLI, git, gh, AWS CLI v2, ripgrep, pnpm, uv, ruff pre-installed, plus the shared
+  libraries a browser links against (see below) and the VPN tooling the `vpn_support_enabled`
+  toggle grants capability for (`iproute2`, `wireguard-tools`, `iptables`)
+- **Browser runtime libraries are baked in; browser *binaries* are not.** A layer runs
+  `npx --yes playwright@latest install-deps chromium` as root, so Playwright names its own
+  dependencies and the list cannot rot against Ubuntu 24.04's `t64` renames or a new Chromium
+  dependency. Measured: +99 packages, +334 MiB unpacked / +119 MiB compressed, on both arches. Do
+  not replace it with a hand-written apt list without pinning the Playwright version you derived
+  it from — a `chromium`-only list saves ~94 MiB (Playwright's `tools` group: xvfb and the CJK
+  fonts) and nothing more, because `libgbm1` → `mesa-libgallium` → `libllvm20` is ~213 MiB that
+  no trimming removes.
+  - The `install-deps --dry-run` call after it is a **build-time assertion, not decoration**: on a
+    platform Playwright's table does not cover, `install-deps` prints a warning and returns having
+    installed nothing **with exit status 0**. Without the assertion that ships a broken image
+    behind a clean build log.
+  - Baking the libraries but not the browsers is the whole point of the split. Browsers live in
+    `~/.cache/ms-playwright` (home volume) and already survive recreation *and* migration; a
+    runtime `apt-get install` of the libraries lands in the writable layer, is re-paid after every
+    Reset, and is **lost on base-image migration**, which replays apt from a manifest. The runtime
+    approach converges on the worst state: a 400 MB browser present with its libraries gone.
+  - The layer sits immediately after Node (npx is its only prerequisite) and well above the shim
+    `COPY`s, so editing a shim does not re-run a multi-hundred-megabyte apt install.
 - **`entrypoint.sh`** — UID/GID remapping to match host user, SSH key setup, git config, docker socket permissions, Claude Code settings.json injection, then `sleep infinity`
 - **`triple-c-scheduler`** — Bash-based scheduled task system for recurring Claude Code invocations
 
+**`/home/claude` in the image is seed-only.** It is the mount point of the named volume
+`triple-c-home-{projectId}`, so after a project's *first* start the image's copy of that directory
+is masked permanently and can never be updated again. A change you make under `/home/claude` in
+the `Dockerfile` or in `entrypoint.sh`'s "copy this into the home dir" style reaches **new
+projects only** — existing ones will never see it, with or without a base-image migration.
+
+So: **anything that must stay upgradable belongs in `/usr/local/bin` or `/opt`, or must be seeded
+by `entrypoint.sh` at runtime** (i.e. written on every start, from a source outside the home
+volume, the way `CLAUDE_INSTRUCTIONS` → `~/.claude/CLAUDE.md` and the Mission Control skill copy
+already are). Putting it in the image's `/home/claude` and expecting an image update to deliver it
+is the mistake.
+
+The flip side is the useful half of the same fact: Claude Code itself (`~/.local/bin`), cargo, uv,
+ruff, the OAuth login, `~/.claude.json`, skills, transcripts, scheduler tasks and SSH keys all
+re-attach for free when a container is recreated from a *different* image — which is what makes
+base-image migration cheap.
+
+### Corporate CA certificates (`docker/ca_certs.rs`, `entrypoint.sh`)
+
+A global `AppSettings::ca_cert_path` with a per-project `Project::ca_cert_path` override, accepting
+a single certificate file **or** a directory. Follows the SSH/AWS host-mount pattern: read-only
+bind mount at `/tmp/.host-ca`, applied by the entrypoint on every start, so it survives recreation,
+migration and Reset. Four things here are not obvious:
+
+- **`update-ca-certificates` globs `*.crt`, case-sensitively.** A `.pem` that is merely copied into
+  `/usr/local/share/ca-certificates/` is ignored in total silence. Certificates are *renamed* —
+  `container_cert_name()` in Rust, mirrored in a few lines of shell in `entrypoint.sh` (the Rust
+  side carries the unit tests). A single-file mount lands at `/tmp/.host-ca/<name>.crt` so the
+  entrypoint only ever sees a directory and the file keeps a recognisable name.
+- **The system store is not enough.** Only curl/git/apt read it. Node — and therefore Claude Code
+  itself — needs `NODE_EXTRA_CA_CERTS`; Python/requests need `REQUESTS_CA_BUNDLE`/`SSL_CERT_FILE`;
+  Chrome/Chromium read neither and want their own NSS database at `~/.pki/nssdb`, seeded with
+  `certutil` (`libnss3-tools`, added to the image for this). The NSS step warns and continues if
+  `certutil` is missing rather than failing the start.
+- **Those env vars are set from Rust at creation, never exported by the entrypoint.** A terminal
+  session is a `docker exec`, which inherits the container's configured env and sees nothing the
+  entrypoint exported — the same lesson that made `$BROWSER` an image-level `ENV`. The bundle path
+  is deterministic (`/etc/ssl/certs/ca-certificates.crt`), so Rust can set them up front. They are
+  emitted **empty** when no CA is configured, for the `MANAGED_AUTH_KEYS` reason: `docker commit`
+  bakes env into the snapshot image. Empty is safe — verified on Ubuntu 24.04 that curl, `openssl
+  s_client` and Python's `ssl` behave exactly as with the vars unset.
+- **`triple-c.ca-fingerprint` covers the certificate *bytes*, not just the path.** Replacing a
+  rotated CA at the same location must recreate the container; the copy inside is made once, at
+  start, so nothing else would notice. The entrypoint is stamped/idempotent on restart, and
+  actively **removes** `triple-c-*.crt` when the setting is cleared — `/usr/local/share` rides the
+  project's snapshot image, so turning the feature off has to undo, not merely stop.
+
+### VPN support (`vpn_support_enabled`, `docker/container.rs`)
+
+An opt-in per-project switch granting the container what a VPN client needs to build a tunnel.
+`vpn_host_config()` is the single definition of what that means, and it is unit-tested because a
+container is created once by a very long function where a dropped capability is invisible.
+
+- **All three pieces or none.** `CAP_NET_ADMIN` (Docker's default set has `net_raw` but *not*
+  `net_admin`, so a client can ping but never connect), the `/dev/net/tun` device (absent
+  entirely from a default container — nothing to open even with the capability), and
+  `net.ipv4.conf.all.src_valid_mark=1` (WireGuard's `wg-quick` sets it and cannot from inside a
+  container, since `/proc/sys` is read-only, so handshake packets die to reverse-path filtering).
+  Any two without the third still presents as a connection that hangs to a timeout, which is why
+  the tests assert the whole set.
+- **The device is passed through from the host, never `mknod`-ed inside.** The kernel's `tun`
+  module has to back it.
+- **A missing device fails at `start`, not `create` — verified against Docker 29.7.** `docker
+  create --device /dev/does-not-exist` succeeds and prints an id; runc resolves the device (and
+  validates sysctls) only when it builds the container. So the guard belongs on the start path:
+  `explain_container_failure()` covers both and is called from `start_container`, where it has a
+  container id and no project — which is why it keys off the error naming `/dev/net/tun` rather
+  than off `vpn_support_enabled`. Nothing else in Triple-C requests a device, so that is
+  unambiguous. A version of this check wired to `create` alone is dead code that looks correct.
+- **`NET_ADMIN` here is not user-namespaced.** Docker does not enable userns remapping by default,
+  so only the *network* namespace confines it: no reach onto host interfaces, but promiscuous
+  mode, arbitrary addresses/routes/NAT on the shared `docker0` segment (sibling containers, the
+  LiteLLM gateway among them, are ARP-spoofable), netlink-triggered host module auto-load, and
+  enough authority to flush in-container netfilter rules that sandbox mode may rely on. Keep the
+  code comments honest about this — an earlier draft claimed it "confers no authority" outside the
+  container, which is too strong.
+- **`triple-c.vpn-support` is written unconditionally, including `false`.** The usual
+  `docker commit` reason: a `true` stamped once would ride the snapshot image into every future
+  container and make the switch impossible to turn off.
+- Off is byte-identical to a container created before the feature existed, and a missing label
+  reads as `false`, so no existing project is churned.
+- **The toggle grants capability and stops there — it routes nothing.** `vpn_host_config()` returns
+  a cap, a device and a sysctl; no client is installed, no route is touched, no tunnel is started
+  or restored. Users read the name as "turn the VPN on" and report the default network not routing
+  through it as a bug. It isn't, and the docs say so explicitly; keep it that way.
+- **The tooling is baked, not installed at runtime.** `iproute2` and `wireguard-tools` are in
+  `container/Dockerfile` because a runtime install lands in the writable layer and is lost on
+  base-image migration — leaving a project holding the capability with nothing able to exercise it,
+  and no error that points at why. `iptables` is included and `nftables` deliberately is not; see
+  the Dockerfile comment for why that way round.
+- **Anything built on this fails open.** The network namespace is rebuilt on every start and no
+  service manager runs inside, so a tunnel never survives stop/start or recreation — while leftover
+  `/run` state makes it look as though it did. Note the two different mechanisms: `/run` is in the
+  writable layer, so on a stop/start it is simply the same container's files, and on a recreation
+  `docker commit` has carried it into the snapshot. Traffic silently reverts to the real address.
+  Any future autostart or killswitch work starts here.
+- **`/run` riding the snapshot means a VPN client's key material can end up in an image.** Verified:
+  a fresh container off the whp snapshot already contained the `wg.priv` a previous tunnel left in
+  `/run`. Anything writing key material there inherits the problem — the same `docker commit`
+  hazard as `triple-c.git-token-hash` and the custom-env fingerprint, in a directory that looks
+  ephemeral and is not. A VPN client that does this should delete its key on teardown.
+- **`iptables` is baked, and picking `nftables` instead would have been wrong.** `Recommends:
+  nftables | iptables` is stripped by `--no-install-recommends`, and `wg-quick` needs a backend for
+  any `AllowedIPs = 0.0.0.0/0`. `nftables` is the tempting choice — preferred by `wg-quick`, half
+  the size — but `wg-quick` picks nft *unconditionally* when present, and its nft ruleset needs
+  `nft_fib_ipv4`, which LinuxKit (Docker Desktop for Mac) does not build while it *does* build
+  `xt_CONNMARK`. Shipping nftables would therefore have forfeited Mac. See the Dockerfile comment;
+  the kernel-config evidence is quoted there.
+- **Two `wg-quick` failures remain, and only one is ours to fix.** Full tunnels still need
+  `xt_CONNMARK`, which WSL2 before 6.6 lacks — nothing installable changes that. And every
+  provider's stock config carries a `DNS =` line that fails in `set_dns()` before any routing, so it
+  breaks split tunnels too; `openresolv` has no candidate on noble and `resolvconf` drags in
+  systemd-resolved, so that one is documented rather than fixed. Driving `wg` and `ip route`
+  directly avoids both, which is what the skill does.
+- **The `pia-vpn` skill is installed *and removed* from `VPN_SUPPORT_ENABLED`.** `container/skills/`
+  is baked to `/opt/triple-c-skills` and `install_feature_skill()` in `entrypoint.sh` copies it into
+  `~/.claude/skills/` on every start — refreshed each time, so a fix reaches any project whose base
+  image has the source, and `rm -rf`'d first, so files dropped from a later version do not linger.
+  The removal branch matters as much as the install: `~/.claude` is a persisted volume, so a skill
+  left behind after the toggle goes off would keep instructing an agent to use a capability the
+  container no longer has. Which is also why the variable is sent as `0` rather than omitted (see
+  `vpn_env_var`, tested), and why it is in `RESERVED_ENV_EXACT` — a custom env var of that name
+  could otherwise claim the skill without the capability behind it.
+- **Both halves of that live in the base image, so neither reaches an existing project.** A
+  recreation builds from the project's *own snapshot*, which has no `/opt/triple-c-skills` and no
+  updated `entrypoint.sh`; only a migration or a Reset delivers them. The install path says so out
+  loud rather than returning silently, and `/opt/triple-c-skills` is in `FEATURE_PROBES` so the
+  migration pre-flight lists it as missing. Worth knowing before adding anything else behind an
+  existing toggle: the label fingerprints *the setting*, not the set of things the setting drives,
+  so a project already at `true` gets no recreation at all on upgrade.
+
 ### Container Lifecycle
 
-Containers use a **stop/start** model (not create/destroy). Installed packages persist across stops. The `.claude` config dir uses a named Docker volume (`triple-c-claude-config-{projectId}`) so OAuth tokens survive even container resets.
+Containers use a **stop/start** model (not create/destroy). Installed packages persist across stops. The `.claude` config dir uses a named Docker volume (`triple-c-claude-config-{projectId}`), nested inside the home volume (`triple-c-home-{projectId}`), so OAuth tokens and Claude Code config survive container stop/start *and* container recreation.
+
+**Reset is the exception and it is destructive.** `rebuild_project_container` calls
+`remove_project_volumes`, which deletes *both* volumes — so a Reset wipes `~/.claude`,
+`~/.claude.json`, the OAuth credential, installed skills, and session transcripts. That is
+intentional (Reset exists to get back to a clean base image), but do not describe Reset as
+preserving credentials.
+
+### Base-image migration (`docker/migration.rs`, `commands/migration_commands.rs`)
+
+A container is created from `triple-c-snapshot-{projectId}:latest` whenever that image exists, and
+every recreation re-commits it — so without an explicit act, a project stays on the base image it
+was first built from **forever** and never picks up a new `socat`, a new `/usr/local/bin` shim or a
+security update. Migration is the non-destructive way out; Reset is the destructive one.
+
+- **Staleness is a surfaced signal, not an automatic trigger.** `triple-c.base-image-id` records
+  the lineage but is deliberately **not** compared in `container_needs_recreation` — see the long
+  comment there. Comparing it would recreate every project *from its own snapshot* on the next base
+  bump: churn on the old base, and it would consume the "you should migrate" signal without
+  migrating. `get_container_staleness` surfaces it; `migrate_project_to_base` acts on it.
+- **A missing lineage label means "unknown, probe instead", never "stale".**
+- **`:latest` keeps pointing at the old lineage until the final commit.** That is what makes every
+  crash before that point self-heal — `start_project_container` just recreates from the old
+  snapshot. After the container swap, the new container's `triple-c.migration-state=in-progress`
+  label plus the persisted state file let `reconcile_project_statuses` offer resume or rollback.
+- **Rollback restores the system layer only.** The volumes are never touched at any point, so work
+  done in `$HOME` during a migrated session survives a rollback. Say so in any UI copy.
+- **`/var` is never copied either, and that is the one way migration is *more* destructive than
+  the ordinary recreate.** A recreate builds from the project's snapshot, so `/var/lib/postgresql`
+  rides along; a migration builds from the base and the apt replay hands back an empty cluster.
+  Copying a live database's files onto a different base's version of the same package is a
+  corruption risk, not a fix — so the answer is disclosure. `unpreserved_data()` reports
+  first-level directories under `/var/lib` and `/var/www` that the base does not ship *and* that
+  hold non-dpkg-owned files (which is what keeps `/var/lib/apt` and `/var/lib/dpkg` out of it),
+  and the pre-flight, the banner and the finished report all name them. Do not make this silent.
+- **The rollback pin is not best-effort.** After `commit_container_snapshot` the commit is the only
+  copy of the old system layer, so a `docker tag` that fails — or succeeds without the reference
+  resolving — aborts the migration before `remove_container`. Same rule in reverse for
+  `rollback_migration`: the image is confirmed to exist before the container is destroyed.
+- **`resume` must check the container's `triple-c.migration-state` label**, exactly as
+  `reconcile_migration` does. Without it a record left behind by a failed commit "resumes" into
+  the *old, unmigrated* container and commits it as migrated.
+- **Anything that stops, removes or recreates a project's container consults
+  `migration_commands::is_migrating`.** The window between `remove_container` and the create that
+  follows looks exactly like "no container" to Start, and Reset would delete the volumes out from
+  under a live run.
+- **`/etc` is never copied**, only reported: the snapshot lineage has
+  `/etc/apt/sources.list.d/nodesource.sources` where the current base has `nodesource.list`, and
+  having both breaks every `apt-get update` on a duplicate source. Verified, not theoretical.
+- **`docker diff` is useless here** — on a snapshot-derived container it reports only changes since
+  the last commit. Migration diffs two filesystem manifests instead, filtered through dpkg
+  ownership and presence-in-the-new-base. Measured on a real project, that turns 8,677 raw path
+  differences into 2 genuinely user-authored ones.
 
 ### Authentication
 
@@ -95,7 +475,20 @@ Per-project, independently configured:
 - **Anthropic (OAuth)** — `claude login` in terminal, token persists in config volume
 - **AWS Bedrock** — Static keys, profile, or bearer token injected as env vars
 - **Ollama** — Connect to a local or remote Ollama server via `ANTHROPIC_BASE_URL` (e.g., `http://host.docker.internal:11434`)
-- **OpenAI Compatible** — Connect through any OpenAI API-compatible endpoint (LiteLLM, OpenRouter, vLLM, etc.) via `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN`
+- **llama.cpp** — Connect to a local or remote `llama-server` via `ANTHROPIC_BASE_URL` (e.g., `http://host.docker.internal:8080`, its default port)
+- **OpenAI Compatible** — Connect through a gateway implementing the **Anthropic Messages API** (LiteLLM) via `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN`
+
+**Claude Code only ever speaks the Anthropic Messages API** (`POST /v1/messages?beta=true`) to
+`ANTHROPIC_BASE_URL` — never OpenAI's `/v1/chat/completions`. Ollama and llama.cpp implement
+`/v1/messages` natively, which is why each gets a plain base-URL backend with no translation shim.
+A server that only exposes an OpenAI-shaped API does not work behind any backend.
+
+For every backend pointing at a custom endpoint (`Backend::uses_custom_endpoint`), all four
+`ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU,FABLE}_MODEL` vars are pinned to the backend's configured
+model id, with an optional per-backend Haiku override. Without this, Claude Code's background
+calls resolve `haiku` to an Anthropic model id the local server does not have and fail silently.
+Anthropic and Bedrock deliberately keep Claude Code's own defaults.
+`ANTHROPIC_SMALL_FAST_MODEL` is deprecated and must not be used.
 
 ## Styling
 
@@ -108,10 +501,202 @@ Per-project, independently configured:
 
 - Frontend types in `lib/types.ts` must stay in sync with Rust structs in `models/`
 - Tauri commands are registered in `lib.rs` via `.invoke_handler(tauri::generate_handler![...])`
-- Tauri v2 permissions are declared in `capabilities/default.json` — new IPC commands need permission grants there
+- `capabilities/default.json` grants permissions for **plugin** commands only (`core:`, `dialog:`,
+  `store:`, `opener:`). Application commands registered through `generate_handler!` do **not**
+  need an entry there — adding one is not required and none exists for any app command.
 - The `projects.json` file uses atomic writes (write to `.tmp`, then `rename()`). Corrupted files are backed up to `.bak`.
+- **Adding project state that changes the container?** `container_needs_recreation()` is entirely
+  **label-based** — it does not diff the container's env. If a new setting affects the container's
+  environment or configuration, you must also write a corresponding `triple-c.*` label at creation
+  and compare it there, or the change will silently not take effect until some unrelated setting
+  forces a rebuild. Never put a secret in a label; labels are readable via `docker inspect`.
+  (`triple-c.base-image-id` is the one deliberate exception — it is written but not compared; the
+  reasoning is in the comment beside the check.)
+- **Always write a `triple-c.*` label explicitly, even when the value is empty.** Docker merges an
+  image's labels into a container's at creation, and `docker commit` copies container labels onto
+  the snapshot image — so a label stamped once rides that snapshot into *every* future container
+  forever. Verified on this host, and it is not hypothetical: `triple-c.mcp-fingerprint` has not
+  been written by any code since the MCP feature was removed, yet a snapshot image was found still
+  carrying a non-empty one, which made its one-shot recreation shim recreate that project on every
+  single start. Writing the key explicitly overrides the inherited value — the same defence
+  `MANAGED_AUTH_KEYS` applies to env vars.
+- **New model fields need an explicit serde default when the correct default isn't the zero value.**
+  `#[serde(default)]` on a `bool` yields `false`; follow the `default_full_permissions` pattern in
+  `models/project.rs` for anything that should default to true.
 - Cross-platform paths: Docker socket is `/var/run/docker.sock` on Linux/macOS, `//./pipe/docker_engine` on Windows
 
+## Secrets
+
+**`scripts/scan-secrets.sh` refuses a commit that adds something shaped like a live
+credential.** Enable the hook once per clone with `npm run hooks` (from `app/`), which sets
+`core.hooksPath` to `.githooks`. A repository cannot configure its own hooks path — cloning it
+would then be enough to run its code — so this is opt-in everywhere, and `--no-verify` skips it.
+The `Secret Scan` workflow is the half nobody can bypass; it carries **no `paths:` filter**, on
+purpose, because the incident that prompted all this lived in `app/**` and `build.yml` only runs
+for `container/**`.
+
+Three rules, and the second half of the third is what keeps it usable: vendor-prefixed tokens
+(`ghp_`, `sk-`, `AKIA`, `xox`, …), `BEGIN … PRIVATE KEY` blocks, and an opaque literal assigned to
+a secret-shaped name. That last one needs **both** halves — the identifier must read as a
+credential *and* the whole literal must be hex or base64 with no word structure. Name-proximity
+alone flags `secure::get_project_secret(&id, "aws-secret-access-key")`, which is a keychain key
+name; the literal test is what excludes it. Measured against the tree: 0 false positives, and it
+catches the real incident (`9b2f4fe`) when replayed.
+
+A line ending `pragma: allowlist secret` is skipped. Make a fixture obviously fake before reaching
+for it.
+
+**Why this exists:** `the_custom_env_fingerprint_never_carries_the_value` used the maintainer's
+real Gitea **site-admin** token as its fixture — a test about secrets not escaping, leaking one. It
+survived 92 commits and fourteen days in the public GitHub mirror, past five audit rounds and two
+independent reviews, because every one of them read the code under change and this sat in a test
+nobody had reason to open. Fixtures are never live values; there is no case where they need to be.
+
+## Settings export/import
+
+`commands::settings_export_commands`, `storage::settings_crypto`, `models::settings_export`
+(triple-c#35). Exports the *host* environment — global `AppSettings` plus the global secrets that
+live in the OS keychain instead: the shared Claude Code OAuth login and the model gateway's two
+keys. Per-project settings, per-project secrets, and anything in a project's Docker volumes are
+deliberately out of scope — this is not a project backup.
+
+- **`AppSettings` is not entirely the non-secret shape it looks like, and a review of this feature
+  caught the one place that isn't.** `WebTerminalSettings::access_token` is a live bearer
+  credential for a server that binds every interface — exporting `AppSettings` wholesale would
+  have carried it along as if it were as inert as a port number, and importing it would have
+  applied `web_terminal.enabled` and the token together with no more warning than any other
+  setting, letting a crafted export silently stand up a LAN-listening terminal on the next launch.
+  `export_settings`/`apply_settings_import` carve this one field out into `ExportedSecrets`
+  instead, with the same "only overwrite what the import actually has" treatment as the other
+  three secrets — except "leave it alone" has to be done by hand in `apply_settings_import`, since
+  unlike the keychain secrets this one lives inside the `AppSettings` blob that gets replaced
+  wholesale. `SettingsImportPreview::enables_web_terminal` also exists because of this: `enabled`
+  and the token are independent fields, and "this turns on a listening service" must not hide
+  inside a generic "settings replaced" summary. Read this as the standing example of the class of
+  thing to keep checking for in this feature, not a one-off fixed bug — any other field that looks
+  like config but is actually a live credential would have the same problem.
+- **Encrypted because it can carry live credentials, not for appearance's sake.** Argon2id derives
+  a 256-bit key from the user's password (memory-hard — meaningfully resistant to GPU/ASIC
+  brute-forcing, unlike PBKDF2 at any reasonable iteration count), AES-256-GCM does the actual
+  encryption. A wrong password fails GCM's authentication tag rather than producing silent
+  garbage. The salt and nonce are not secret and are written in the clear in the file's own
+  header — the salt's job is only to make two exports of the same password derive different keys,
+  and the nonce's only requirement is per-encryption uniqueness, which a fresh random draw on
+  every export already gives it.
+- **The save/open dialogs are opened from Rust**, the same boundary `file_commands.rs`'s
+  `pick_save_path`/`pick_files_to_upload` draw and document at length: a frontend-driven dialog
+  handing Rust a host path string is the exact shape of bug that produced this app's past
+  criticals. `preview_settings_import` resolves the chosen path itself and remembers it
+  (`AppState::pending_settings_import`) so `apply_settings_import` re-reads the same file without
+  a path ever crossing back over IPC. It also pins a hash of the file's ciphertext next to that
+  path, and `apply_settings_import` refuses to proceed if the file on disk no longer matches it —
+  otherwise confirming a preview would not actually be binding on what gets applied, which matters
+  given this feature's own threat model: a file shared between people may sit in a synced or
+  otherwise shared directory that changes between the two calls.
+- **The decrypted payload is not cached between preview and apply — only the password is reused.**
+  The frontend holds the password in React state and passes it to both calls; nothing in Rust
+  holds decrypted plaintext — secrets included — in memory for longer than one command's
+  execution, so `apply_settings_import` always re-decrypts rather than reusing anything
+  `preview_settings_import` computed. `preview_settings_import` returns counts and presence flags
+  only (`SettingsImportPreview`), never a secret value, so it's safe to hand to the frontend and
+  render directly.
+- **Import replaces settings wholesale, but only writes secrets actually present in the file.**
+  An import is "restore this environment," so the settings half is a full replace, not a
+  field-by-field merge. Secrets are different on purpose: an absent secret in the export means
+  "the source machine never had this configured," not "delete this on import" — a user who wants
+  to clear a secret already has dedicated UI for that (signing out of shared auth, clearing the
+  gateway key). Secrets are restored *before* the settings replace runs, not after — replacing
+  settings is what triggers `reconcile_gateway`, and restoring the other way round leaves a real
+  window where a gateway recreation happens against the destination's old keys.
+- **A restored gateway secret nudges a running gateway container to recreate itself, even when
+  nothing about the gateway's *shape* changed.** `reconcile_gateway`'s `gateway_shape_changed` only
+  compares port/provider/base URL/models — deliberately, since that's what's rendered into the
+  container's config — so a secret-only change (same shape, new key) is invisible to it. Left
+  alone, a running container would keep serving the old key material indefinitely after an import
+  that restored a new one. `apply_settings_import` tracks whether either gateway secret was
+  actually written and, if the gateway is enabled and its container both exists and is running,
+  calls `docker::gateway::ensure_gateway_running` directly afterward — its own fingerprint already
+  includes the secret rotation id (`storage::secure::get_gateway_secret_version`), so it recreates
+  exactly when it should and no more.
+- **A keychain write failing during import is reported back, not only logged.** Each of the three
+  `secure::store_*` calls collects its error into `SettingsImportOutcome::secret_restore_warnings`
+  in addition to logging it — an import that silently restores two of three secrets but not the
+  third must not read as unqualified success just because the settings half of the import (which
+  runs after, and is validated before any of this) went through. `apply_settings_import` returns
+  `SettingsImportOutcome { settings, secret_restore_warnings }` rather than bare `AppSettings` for
+  this reason; `ImportSettingsModal` shows any warnings alongside the "Settings imported" message.
+- **The imported settings are validated *before* any secret is written, not just before the
+  settings replace.** `apply_settings_import` calls
+  `settings_commands::validate_settings_update(&current, &settings)` — the same checks
+  `update_settings` runs internally, pulled out into its own function specifically so this caller
+  can run them first — and only proceeds to the three keychain writes if that passes. A review
+  caught the earlier ordering: writing secrets first meant a rejected import (a bad env var name, a
+  disallowed host path) still left the keychain overwritten with the file's secrets while the
+  settings themselves stayed unchanged, a silently half-applied state the error message gave no
+  hint of.
+- **`read_and_decrypt` checks `format_version` before attempting to parse the full payload, not
+  after.** A version bump that isn't deserialize-compatible is exactly the case that check exists
+  for, and parsing the full struct first would fail on the shape mismatch before the version check
+  ever ran. Neither error path interpolates what `serde_json` actually says into the message
+  shown to the user — its type-mismatch errors quote the offending value inline, and the plaintext
+  here can hold a live credential.
+- **The 8-character password minimum is enforced in `export_settings` itself, not only in the
+  export modal.** The frontend minimum is a UX nudge; the Rust command is the actual boundary a
+  weak password has to cross, and Argon2id's memory-hardness buys little against an attacker who
+  can just try a short password directly. Measured with `.chars().count()` (Unicode scalar values)
+  rather than `.len()` (bytes), to stay as close as this pair of languages allows to the frontend's
+  `.length` check (UTF-16 code units) — the two only diverge on astral-plane characters. The
+  derived key and both plaintext buffers — the payload built for export, and whatever `decrypt`
+  recovers on import — are wrapped in `zeroize::Zeroizing` for the same reason every other secret
+  in this codebase gets handled carefully — cheap insurance (`zeroize` is already pulled in
+  transitively via `aes-gcm`) for material that exists only to hold or produce live credentials.
+- **The preview also discloses non-blank custom base URLs** (`global_ollama`, `global_llamacpp`,
+  `global_openai_compatible`, `gateway.api_base`) so an import that would redirect model traffic to
+  a different server is visible in the confirmation dialog rather than discovered later — these are
+  endpoints, not secrets, so `SettingsImportPreview` carries and `describeImport` renders the actual
+  URL rather than just a presence flag. `describeImportWarnings` additionally calls out a web
+  terminal token that arrives with the terminal left *off*: `start_web_terminal` only mints a fresh
+  token when none is already set, so a planted token would otherwise activate silently the next
+  time someone turns the terminal on, with no import-time signal that it wasn't freshly generated.
+- **The preview also discloses a custom Docker image, and warns on one every time — not just on
+  change.** `custom_image_name`/`image_source` weren't in scope for the base-URL disclosure above,
+  but a review pointed out they're a sharper version of the same problem: this is the image *every*
+  project container is created from (`models::container_config::resolve_image_name`), so a crafted
+  export pointing it at an attacker-controlled image is a path to running arbitrary code with
+  whatever a project's containers are allowed to reach, not merely a redirected API endpoint.
+  `describeImportWarnings` fires on `image_source == Custom` unconditionally rather than only when
+  it differs from the destination's current value, since re-importing the same risky configuration
+  is still worth surfacing every time a user confirms an import.
+- **Every free-form string a preview surfaces is sanitized and length-capped before it's built.**
+  `SettingsImportPreview::from_payload`'s `sanitize_for_preview` strips control characters and caps
+  at 100 characters (`MAX_PREVIEW_STRING_LEN`) for every base URL and the custom image name — a
+  review noted that, unlike the count- and boolean-derived fields the preview started with, these
+  are verbatim strings from a not-yet-trusted decrypted payload rendered directly into the
+  confirmation dialog. Unbounded, a single pathological value (very long, or holding embedded
+  newlines) could push the security warnings above the scroll fold in the dialog that exists
+  specifically to make them unmissable — the frontend's `<li>`/warning boxes also get `break-all`
+  as a second layer against the same failure mode.
+
+## Packaging
+
+Linux ships as `.deb`, `.rpm` and AppImage, all three built by `build-app.yml` (releases) and
+`build-app-preview.yml` (the PR check). **There is deliberately no Arch package.** A
+`triple-c-bin` `PKGBUILD` and a `publish-arch-package.yml` existed and were removed; they live on
+`hold/arch-packaging`. Do not re-add them without the piece that was always missing: the package
+was never on the AUR, so it was a manual `pacman -U` of a downloaded file — the same gesture as
+the AppImage, for a second artifact to keep working. Being `workflow_dispatch`-only it also
+reached 1 release in 28, while `HOW-TO-USE.md` told Arch users to download it from every release.
+An AUR account and its SSH key as a repo secret are what would make it worth having; until then
+the AppImage is the Arch story.
+
+`scripts/install-appimage.sh` is the desktop-integration half, and it exists because an AppImage
+has no installer: it extracts the bundled icons into `~/.local/share/icons/hicolor` and writes a
+`.desktop` entry. It **rewrites** the `Exec` line rather than copying the bundled entry — the
+bundled one is `Exec=triple-c`, which resolves only inside the AppImage's own mount, so a
+verbatim copy yields a launcher entry that starts nothing. It keeps `StartupWMClass` exactly as
+the bundle sets it, which is what lets the shell match the window to the entry. Extraction uses
+`--appimage-extract`, which needs no FUSE, so the script works before `fuse2` is installed.
+
 ## Testing
 
 Frontend tests use Vitest with jsdom environment and React Testing Library. Setup file at `src/test/setup.ts`. Run a single test file:

DESIGN-REVIEW.md

@@ -0,0 +1,337 @@
+# Triple-C Design & Product Review
+
+**Date:** 2026-08-09 · **Version reviewed:** 0.3.0 · **Reviewer:** Fable 5
+
+Scope: `app/src/` (App, layout, projects, settings, terminal, ui, store, index.css),
+README/CLAUDE.md/TODO.md, the four repo screenshots, and `triple-c-app-logov2.png`.
+
+---
+
+## Summary verdict
+
+The bones are good. The floating-panel layout reads clean, the GitHub-dark palette is
+inoffensive, and terminal-as-centerpiece is correct for this product.
+
+The two real problems are structural, and they are the same problem seen from two sides:
+**the project — the app's actual unit of work — has no room to live.** Everything about a
+project (backend auth, mounts, git identity, env vars, ports, Claude settings, file
+manager) is stuffed into a ~280px sidebar card (`ProjectCard.tsx`, 1,257 lines) that
+sprays out seven modals to compensate.
+
+`screenshot_for_fix/project_config_run_off.png` is not a bug to patch. It is the
+architecture reporting that the config does not fit where it lives. Fixing that one thing
+also solves the modal pile, the density problems, *and* creates the surface where newer
+Claude Code concepts belong.
+
+---
+
+## Part A — Visual & interaction design
+
+### A1. Tokens: coherent but thin, with one real contrast failure
+
+`index.css` is GitHub Primer dark, verbatim (`#0d1117 / #161b22 / #21262d / #30363d /
+#8b949e / #58a6ff`). Defensible — familiar, calm, terminal-adjacent — but the token layer
+stops at 11 variables. Roles the code is already faking ad hoc:
+
+- **No elevation/overlay token.** Modals reuse `--bg-secondary`, so a modal over the
+  sidebar is the same color as the sidebar. Add `--bg-overlay: #1c2128` and
+  `--shadow-overlay`.
+- **No muted-accent tokens.** The code hand-rolls `bg-yellow-500/20 text-yellow-400`,
+  `bg-blue-500/20 text-blue-400`, `--warning/15`, `--error/10`. Add `--accent-muted`,
+  `--warning-muted`, `--error-muted`, `--success-muted`. Those raw Tailwind palette colors
+  are the only two places the token system leaks.
+- **Radius drift:** `rounded` (4px), `rounded-lg` (8px), plus hardcoded 3px/6px in help
+  styles. Pick two: 6px controls, 8px panels.
+
+**Contrast bug (concrete):** white text on `--accent #58a6ff` is ~**2.5:1** — fails WCAG
+AA. That is the primary button ("Add Project"), the "Update" pill, and more. Primer solves
+this with two accents: keep `#58a6ff` as the *foreground/link* accent and add
+`--accent-emphasis: #1f6feb` for filled buttons (white on `#1f6feb` ≈ 4.7:1).
+
+Same story for `bg-[var(--success)] text-white` ON toggles — `#3fb950` + white ≈ **2.1:1**,
+the worst offender in the app.
+
+What passes: `--text-secondary #8b949e` on `#161b22` ≈ 5.8:1, fine even at 12px.
+`--warning #d29922` ≈ 7:1. But `disabled:opacity-50` on secondary text drops to ~2.4:1 —
+and since the entire config form is disabled while the container runs, **the most common
+state of the form is illegible.** Use a dedicated `--text-disabled: #6e7681` instead of
+opacity.
+
+### A2. Type and density: everything is 12px
+
+Roughly 90% of the UI is `text-xs`. Hierarchy is carried almost entirely by weight plus a
+single `text-lg` modal title. Forms feel cramped rather than dense — density is
+information per pixel, not small type.
+
+Proposed scale with roles: **11px** uppercase section labels (already used, keep) ·
+**12px** secondary/meta · **13px** default UI/body/form values · **14px** panel headers ·
+**16px** view titles.
+
+Path strings in mono are a nice identity touch — extend mono to all machine values (model
+IDs, ports, digests), which the Bedrock/Ollama forms currently render in the UI face.
+
+The outer chrome spends generously while content starves: `App.tsx` wraps everything in
+`p-6 gap-4`, then the config form gets ~180px-wide inputs for AWS secret keys. Keep the
+floating-island look; `p-3 gap-3` buys content ~24px horizontally and the terminal two
+more rows.
+
+### A3. The project card is three components wearing one div
+
+`ProjectCard` is simultaneously a list row, a command strip, and the entire settings form.
+
+- **Selection and disclosure are conflated.** Clicking a row both selects it and expands an
+  accordion in place, shoving the other projects down. The 06-28 screenshot shows 18
+  projects — this jank is daily.
+- **Actions are unstyled text links.** `ActionButton` renders `text-xs px-2 py-0.5` colored
+  text with no border or background, so Start/Stop/Terminal/Shell/Files/Backup/Config/Remove
+  read as a wrapping line of links. Worse, **Remove (destructive, red) wraps directly next
+  to Config** with a ~20px hit target.
+- **Double-click-to-rename** is undiscoverable and keyboard/touch-inaccessible.
+- **27 hover-only `<Tooltip>` markers in ProjectCard alone.** When a form needs 27 tooltips,
+  the form is the problem.
+
+### A4. Modals: eight is a pattern smell, and none are real dialogs
+
+Hanging off ProjectCard: EnvVars, PortMappings, ClaudeInstructions, ClaudeCodeSettings,
+ContainerProgress, FileManager, ConfirmRemove — plus AddProject, three reused from
+SettingsPanel, and Update/ImageUpdate/Help from TopBar.
+
+Each reimplements the overlay div, Escape handler, and click-outside logic by hand. **None
+has `role="dialog"`, `aria-modal`, a focus trap, or focus restore** — zero hits for
+`role=`, `aria-modal`, or `tabIndex` across `components/`.
+
+The pattern is wrong not because modals are bad, but because these are not modal *tasks*.
+Env vars, ports, instructions, and Claude settings are all "edit part of the project
+config" — a detail view's job.
+
+- Legitimately modal: **ConfirmRemove**, **AddProject**.
+- **FileManager** wants to be a main-area tab, not a 42rem popup.
+- **ContainerProgressModal actively hurts:** starting a container blocks the entire app
+  behind an overlay for an operation designed to be routine. Replace with inline row state
+  plus an error toast.
+- Whatever survives should be one shared `<Modal>` primitive with focus trap + ARIA.
+
+### A5. Keyboard and focus: currently unsupported
+
+For a tool whose centerpiece is a keyboard-driven terminal, the chrome is mouse-only.
+
+- Inputs use `focus:outline-none` with only a low-contrast border swap; **buttons have no
+  focus style at all** — tabbing through the sidebar is invisible.
+- One-line fix: add `--focus-ring: #58a6ff` and
+  `:focus-visible { outline: 2px solid var(--focus-ring); outline-offset: 1px; }`
+- No shortcuts for constant actions: `Ctrl+T` new terminal, `Ctrl+Tab`/`Ctrl+1..9` switch,
+  `Ctrl+W` close, `Ctrl+P` project switcher. The only shortcut in the app is the STT mic.
+- Hit targets below 24px: tab close "×" (~14px), Tooltip "?" (14px), Browse "...". The
+  status bar is `h-6` yet hosts two interactive controls.
+
+### A6. Status communication
+
+Three disconnected dot systems (TopBar Docker/Image, per-project status, StatusBar counts),
+all 8px and color-only.
+
+- **Stopped (gray) and error (red) differ only by hue**, and Docker-unavailable renders the
+  same gray as Docker-still-being-checked (`dockerAvailable === null` and `false` both fall
+  through). An outage should be loud; unknown should pulse.
+- Color-only encoding fails colorblind users. Add shape or text — `● Running`, `○ Stopped`,
+  `⚠ Error`. The words are already in the model.
+- Raw `String(e)` errors dumped into a 12px card line; bollard errors are long. Errors need
+  a home: toast plus expandable detail.
+- The TopBar tab strip is visually disconnected from the terminal it controls. Move tabs
+  onto the terminal panel's top edge so the active tab connects to its content.
+
+### A7. Empty and first-run states
+
+`WelcomeScreen` is three lines of gray text with no affordance — "Add a project from the
+sidebar" *describes* a button instead of *being* one. This is also where brand could exist:
+the orange sun-gear logo appears nowhere in the UI and shares no DNA with the blue-on-
+graphite chrome.
+
+Make it an onboarding checklist reusing state already tracked:
+✓ Docker detected → ✓ Image pulled → **[ Add your first project ]** → open terminal.
+The same pattern fixes the "image missing" case, today just a gray dot in the corner.
+
+### A8. Dark-only: keep it
+
+Right call. Terminal-first developer tool, xterm content is dark, audience expects it. The
+tokens make a light theme cheap later. Don't spend on it now — but keep discipline that no
+color bypasses the token layer.
+
+### A9. Iconography
+
+Mixed: hand-inlined Feather-style SVGs in the sidebar rail, text glyphs elsewhere ("×",
+"?", "...", "+", "✓", "✕"). Adopt `lucide-react` — same stroke style already being
+imitated, tree-shakeable — and replace the text glyphs. It also supplies the per-concept
+icons Part B needs.
+
+---
+
+## Part B — Information architecture & product concepts
+
+### B1. The diagnosis
+
+Current IA: `Projects | MCP | Settings` in a sidebar, terminal in main, project detail
+crammed into the list.
+
+Deleting the MCP tab was correct — but **the lesson matters more than the freed slot.
+MCP died as a Triple-C feature because Claude Code absorbed it.** Hooks, skills, agents,
+plugins, output styles, and statusline are all the same species: files under `.claude/`
+that Claude Code manages natively with its own TUIs (`/agents`, `/hooks`, `/plugins`). If
+Triple-C builds form editors for them, it loses the same race again and becomes exactly
+what it should fear — a settings-file editor with a GUI skin.
+
+What Claude Code *cannot* do is what Triple-C uniquely owns: **the container boundary and
+what persists behind it.** The config volume, the workspace mounts, the lifecycle, the
+scheduler already shipping in every image, and the fleet view across many projects.
+
+> **Principle: Triple-C shows state and launches things. Claude Code edits its own config.**
+
+Sessions, checkpoints, background tasks, scheduled tasks, capability inventory → surface
+them, read from the volume, launch into the terminal. Hook/skill/agent *editing* →
+deep-link into the terminal, don't rebuild.
+
+### B2. Proposed IA: three nouns
+
+**Project** (a sandboxed workspace) · **Session** (a resumable conversation) ·
+**Library** (reusable capabilities pushed into projects). Everything is one of these, or
+Settings.
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│  TopBar:  ⌂ api-server │ ▣ api-server ✕ │ ▣ api (bash) ✕ │  ● ● ? │
+├─────────────┬──────────────────────────────────────────────────────┤
+│  ◤ Projects │   MAIN AREA — a tab strip of two tab kinds:          │
+│  ● api-serv │   ⌂ project-home tabs   ▣ terminal tabs              │
+│  ○ blog     │                                                      │
+│  ● data-pipe│   ⌂ api-server                    ● Running · 2h 14m │
+│      …      │   ┌─────────┬──────────┬────────────┬────────┐       │
+│  ◧ Library  │   │Overview │ Sessions │ Automation │ Config │       │
+│  ⚙ Settings │   └─────────┴──────────┴────────────┴────────┘       │
+├─────────────┴──────────────────────────────────────────────────────┤
+│  StatusBar: 18 projects · 8 running · 4 terminals        🎤  ↓Jump │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+- **Sidebar** becomes a pure list plus nav rail. Rows carry name, path, status dot, and on
+  hover a play/stop and terminal button. Clicking opens (or focuses) that project's
+  **Project Home** tab. The freed MCP slot becomes **Library**.
+- **Main area** hosts two tab kinds: terminals (as today) and project-home tabs, like VS
+  Code's Settings tab. The terminal stays the centerpiece; Project Home is one keystroke
+  away rather than a layer on top.
+- **All seven config modals dissolve** into the Config tab, full-width, grouped:
+  *Workspace* (folders/mounts), *Model* (backend + auth), *Access* (git/SSH/env/ports),
+  *Runtime* (docker access, sandbox, permission mode, Mission Control). Room for visible
+  helper text kills most of the 27 tooltips. Save-on-blur stays but gains a visible
+  "Saved ✓ / Failed" indicator — today failures go only to `console.error`, which is
+  silent data loss.
+
+#### Project Home — Overview tab
+
+```
+ api-server                                  ● Running · started 2h ago
+ [ Stop ] [ Open Claude Terminal ] [ Shell ] [ Files ]        [⋯ menu]
+
+ Permission mode   ( Plan ) ( Default ) ( Accept Edits ) (▮ Bypass ▮)
+ Sandbox           ON — bubblewrap isolation           Backend  Anthropic
+
+ CAPABILITIES (read from container volume)
+ ◆ Skills 7    ◆ Agents 3    ◆ Hooks 2    ◆ Plugins 1    ◆ Commands 5
+   └ click any → drawer listing names/descriptions,
+     [Manage in terminal] → opens claude with /agents etc.
+
+ RECENT SESSIONS                              SCHEDULED TASKS
+ "Refactor OAuth flow"  2h ago  [Resume]      nightly-review  0 3 * * *
+ "Fix flaky CI test"    1d ago  [Resume]      [2 notifications]
+```
+
+### B3. The four concepts worth building
+
+**1. Sessions & Resume — the flagship.** The stop/start container model creates a problem
+plain Claude Code doesn't have: stop a container, come back Tuesday, and "which
+conversation was I in?" is buried in the volume. Read session metadata via `docker exec`
+(the exec and tar plumbing already exists), list sessions with summary and age, and make
+**[Resume]** open a terminal running `claude --resume <id>`. Closing a terminal tab today
+silently abandons a session; it should say "Session saved — resume from Project Home."
+This turns the biggest architectural quirk into the best feature.
+
+Do **not** build a checkpoint browser. Mention rewind (`Esc Esc`) in Help and stop there.
+
+**2. Library — the MCP tab's successor.** The pattern was already invented three times:
+global MCP servers with per-project checkboxes, global Claude instructions, and Mission
+Control's bundled skill install. Generalize it once: a Library of **skills, agents, and
+slash commands** defined globally with per-project enable, synced into the container's
+`.claude` volume by the entrypoint. Across many projects, "write a skill once, enable it in
+twelve sandboxes" is genuinely differentiated. Keep the editor minimal — name plus markdown
+textarea, or "import from folder." Not a structured form per frontmatter field.
+
+**3. Permission mode as the hero control.** The whole pitch is "sandbox so you can safely
+go fast," yet that pitch is expressed as a scary boolean buried in a config accordion.
+Replace it with Claude Code's real vocabulary — a segmented control (**Plan / Default /
+Accept Edits / Bypass**) on Overview, echoed as a badge on terminal tabs, with sandbox
+state beside it. When sandbox is ON, Bypass loses its red paint ("contained by sandbox");
+when sandbox is OFF *and* Bypass is on, that is when caution color earns its place. This
+reframes the product's core value in the product's own UI.
+
+**4. Automation tab.** `triple-c-scheduler` ships in every container with
+add/list/logs/notifications — and its only UI is a CLAUDE.md paragraph telling Claude to
+run it. Wrap it: task list (name, cron, last run, enabled), toggle/run-now/view-log, and a
+notification badge on the project row. "Your nightly agent left you a note" is a reason to
+open the app in the morning. Fleet-of-scheduled-agents management across projects is
+something the Claude Code TUI does not offer.
+
+**Explicitly skip:** status line builder, output-styles editor, hook *editors* (surface the
+count, deep-link to the terminal), checkpoint browser, marketplace browser. Each is niche,
+natively handled, or a settings-editor trap.
+
+### B4. Coherence test
+
+Every screen answers exactly one question:
+
+| Screen | Question |
+|---|---|
+| Sidebar | What projects exist and are they up? |
+| Project Home | What can this sandbox do, and where did I leave off? |
+| Terminal | Do the work. |
+| Library | What capabilities do I reuse? |
+| Settings | How does the host behave? |
+
+Anything that doesn't answer one of those doesn't get a nav slot.
+
+---
+
+## Priorities
+
+### Tier 1 — high impact, cheap
+
+1. `:focus-visible` ring and stop stripping outlines (one CSS rule + token). Add
+   `Ctrl+T` / `Ctrl+W` / `Ctrl+1..9` / `Ctrl+Tab`.
+2. Contrast: `--accent-emphasis: #1f6feb` for filled buttons; kill white-on-`#3fb950`;
+   `--text-disabled` instead of `opacity-50`.
+3. Real buttons for project actions; Remove into an overflow menu; primary action filled.
+4. Inline start/stop progress and an error toast; delete `ContainerProgressModal`.
+5. Status dots get labels or shapes; Docker-down turns red; null state pulses.
+6. Welcome screen becomes an onboarding checklist with a real button, plus the logo.
+7. One shared `<Modal>` with focus trap and ARIA for the modals that remain.
+8. Permission-mode segmented control replacing the boolean.
+9. `lucide-react` icons; move the tab strip onto the terminal panel.
+
+### Tier 2 — high impact, expensive
+
+1. **Project Home tabbed view** — the structural fix that dissolves the modal pile and the
+   1,257-line ProjectCard. The forms already exist; this is mostly moving and splitting.
+2. **Sessions tab** with `claude --resume`.
+3. **Library** — generalize global→per-project sync to skills/agents/commands.
+4. **Automation tab** wrapping `triple-c-scheduler`, with notification badges.
+
+### Tier 3 — skip
+
+- Light theme (dark-only is right; tokens keep the door open).
+- Editors for hooks, statusline, output styles; checkpoint browser; marketplace browser.
+- Any new global sidebar tab beyond Library.
+- Rebuilding MCP management in any form. Let the deletion be a lesson, not a vacancy.
+
+---
+
+**One sentence:** promote the project from a sidebar card to a first-class workspace view,
+use the volume you already own to surface sessions/capabilities/automation instead of
+building config editors, and spend a focused week on focus rings, contrast, and button
+affordances — the visual layer needs sanding, not redesign.

README.md

@@ -1,6 +1,32 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="branding/triple-c-lockup-dark.svg">
+  <img src="branding/triple-c-lockup-light.svg" alt="Triple-C — Coding Container" width="429" height="112">
+</picture>
+
 # Triple-C (Claude-Code-Container)
 
-Triple-C is a cross-platform desktop application that sandboxes Claude Code inside Docker containers. Each project can optionally enable full permissions mode (`--dangerously-skip-permissions`), giving Claude unrestricted access within the sandbox.
+Triple-C is a cross-platform desktop application that sandboxes Claude Code inside Docker containers. Each project chooses its own **permission mode** — from Plan (read-only) through to Bypass (`--dangerously-skip-permissions`), which gives Claude unrestricted access within the sandbox.
+
+This file is the architectural tour: what each subsystem is and why it works the way it does.
+
+| Document | For |
+|---|---|
+| [HOW-TO-USE.md](HOW-TO-USE.md) | Using the app — first launch, projects, settings, troubleshooting |
+| [BUILDING.md](BUILDING.md) | Building from source on Linux, macOS and Windows |
+| [TECHNICAL.md](TECHNICAL.md) | Technology choices and the dependency inventory |
+| [ROADMAP.md](ROADMAP.md) | Claude Code feature parity, gaps and sequencing |
+| [CLAUDE.md](CLAUDE.md) | Working *on* this repo, for Claude Code |
+| [branding/](branding/README.md) | The mark, the palette, and how the icons are generated |
+
+## Contents
+
+- [Architecture](#architecture) — layout, tabs, shortcuts, Project Home
+- [Permission Modes](#permission-modes)
+- [Containers](#containers) — lifecycle, base-image migration, mounts, CA certificates, sibling containers
+- [Models and Authentication](#models-and-authentication) — backends, model aliases, gateway, shared token
+- [Bridges to the Host](#bridges-to-the-host) — URL relay, auth bridge, browser view, host file transfers
+- [Inside a Project](#inside-a-project) — capability tiles, Mission Control, web terminal, speech-to-text
+- [Key Files](#key-files) · [CSS / Styling Notes](#css--styling-notes) · [Container Image](#container-image)
 
 ## Architecture
 
@@ -13,46 +39,196 @@ Triple-C is a cross-platform desktop application that sandboxes Claude Code insi
 
 ```
 ┌─────────────────────────────────────────────────────┐
-│  TopBar (terminal tabs + Docker/Image status)       │
+│  TopBar (MainTabs strip + Docker/Image status + ?)  │
 ├────────────┬────────────────────────────────────────┤
-│  Sidebar   │  Main Content (terminal views)         │
-│  (25% w,   │                                        │
-│  responsive│                                        │
+│  Sidebar   │  Main Content                          │
+│  (25% w,   │   · Project Home views, or             │
+│  responsive│   · terminal views (xterm.js)          │
 │  min/max)  │                                        │
 ├────────────┴────────────────────────────────────────┤
-│  StatusBar (project/terminal counts)                │
+│  StatusBar (project/terminal counts, STT, scroll)   │
 └─────────────────────────────────────────────────────┘
 ```
 
+The main area is driven by **one ordered tab strip** (`components/layout/MainTabs.tsx`) holding
+two tab kinds: `home:<projectId>` (Project Home) and `term:<sessionId>` (a terminal). There is no
+separate terminal tab bar. `activeSessionId` is derived from the active tab key, so exactly one
+thing is current at a time.
+
+Tabs are user-reorderable — drag one, or move the active tab with `Ctrl+Shift+←/→`. A tab's
+position is therefore never its identity: tabs are addressed by key, and indexed only through
+`tabOrder`. The drag is built on pointer events rather than HTML5 drag-and-drop, deliberately:
+Tauri's `dragDropEnabled` blocks HTML5 drag inside the webview on Windows, and it cannot simply be
+switched off because `TerminalView` needs Tauri's native drag-drop event — the only one that
+carries dropped *file paths*.
+
+### Keyboard Shortcuts
+
+Implemented in `hooks/useKeyboardShortcuts.ts` (document-level, capture phase):
+
+| Shortcut | Action |
+|---|---|
+| `Ctrl+T` | New Claude terminal for the current project (no-op unless it is running) |
+| `Ctrl+Shift+W` | Close the active tab |
+| `Ctrl+Tab` / `Ctrl+Shift+Tab` | Cycle tabs forward / backward |
+| `Ctrl+1` … `Ctrl+9` | Jump to the nth tab |
+| `Ctrl+Shift+←` / `Ctrl+Shift+→` | Move the active tab left / right |
+
+`Ctrl+W` is deliberately **not** bound: it is readline's `kill-word`, used constantly in the
+terminal this app is built around. Plain `Ctrl+←/→` is readline's word-wise cursor motion, which is
+why moving a tab takes Shift as well.
+
+Terminal-scoped keys are handled in `TerminalView.tsx`:
+
+| Shortcut | Action |
+|---|---|
+| `Ctrl+Shift+C` / `Ctrl+Shift+Alt+C` | Copy the selection, trimmed / exactly as-is |
+| `Ctrl+Shift+M` | Toggle speech-to-text recording |
+| `Shift+Enter` | Insert a newline in Claude Code's prompt instead of submitting |
+| `Alt+Enter` | The same thing — xterm.js already ESC-prefixes on Alt, so this has always worked |
+
+`Shift+Enter` sends `ESC` + `CR`, which is what Claude Code's own `/terminal-setup` installs for
+VS Code, Cursor, Alacritty and Zed. It is bound in Claude sessions only: in a bash tab those bytes
+are unbound in readline. The web terminal does the same, and adds an `↵+` key beside Enter for
+devices with no Shift.
+
+### Project Home
+
+Clicking a project row in the sidebar opens **Project Home** in the main area — the per-project
+view, with tabs **Overview · Sessions · Automation · Config · Files · Browser**. The sidebar row
+itself is select-only (plus hover controls for start/stop and opening a terminal); it holds no
+configuration. Per-project configuration lives in the Config tab rather than in modals.
+
+| Tab | Contents |
+|---|---|
+| **Overview** | Permission mode control, sandbox/backend/Docker-access summary, capability tiles, recent sessions, scheduled tasks, base-image staleness banner |
+| **Sessions** | Past Claude Code conversations read from the config volume, with **Resume** |
+| **Automation** | The container's `triple-c-scheduler` tasks — create, edit, enable/disable, run now, read logs, remove, and completion notifications |
+| **Config** | Workspace (name, folders), Model (backend), Access (SSH, git, env vars, port mappings), Runtime (permission mode, sandbox, Docker access, Mission Control, instructions, Claude Code settings) |
+| **Files** | Browse, view, rename and create folders inside the container, upload host files into the directory on screen, and save one file back out to the host — see [Host File Transfers](#host-file-transfers). A whole tree still comes out through **Back up container** |
+| **Browser** | Watch and take over the Playwright browser inside the container — see [Browser View](#browser-view) |
+
+Container start/stop progress is reported inline (on the sidebar row and in the Project Home
+header) via the `container-progress` event, and failures surface as toasts. There is no blocking
+progress modal.
+
+## Permission Modes
+
+`PermissionMode` in `models/project.rs` replaces the old `full_permissions` boolean. Four states,
+mapped to CLI flags by `PermissionMode::cli_args()`:
+
+| Mode | Serialized | CLI args passed to `claude` |
+|---|---|---|
+| **Plan** | `plan` | `--permission-mode plan` |
+| **Default** | `default` | *(none)* |
+| **Accept Edits** | `acceptEdits` | `--permission-mode acceptEdits` |
+| **Bypass** | `bypass` | `--dangerously-skip-permissions` |
+
+`Project.permission_mode` is `Option<PermissionMode>`; `effective_permission_mode()` falls back to
+the legacy `full_permissions` flag (`true` → Bypass) for records written before the change. Changing
+the mode affects terminals opened **from then on** — a running `claude` process keeps the argv it
+was launched with.
+
+Scheduled tasks honour it too. The mode is injected as `TRIPLE_C_PERMISSION_MODE` (via
+`as_env_value()`) and written as the `triple-c.permission-mode` container label; the entrypoint
+snapshots it into `~/.claude/scheduler/.env`, and `container/triple-c-task-runner` translates it
+back into flags for its headless `claude -p` run. Because it travels as container env, a mode change
+only reaches the scheduler after the container is recreated on its next start (the label mismatch
+forces that).
+
+## Containers
+
 ### Container Lifecycle
 
-1. **Create**: New container created with bind mounts, env vars, and labels
-2. **Start**: Container started, entrypoint remaps UID/GID, sets up SSH, configures Docker group, sets up MCP servers, injects Claude Code settings
-3. **Terminal**: `docker exec` launches Claude Code (or bash shell) with a PTY
-4. **Stop**: Container halted (filesystem persists in named volume); MCP containers stopped
-5. **Restart**: Existing container restarted; recreated if settings changed (detected via SHA-256 fingerprint)
-6. **Reset**: Container removed and recreated from scratch (named volume preserved)
+1. **Create**: New container created with bind mounts, named volumes, env vars, and labels
+2. **Start**: Container started, entrypoint remaps UID/GID, sets up SSH, configures Docker group, installs any CA certificates, injects Claude Code settings, rebuilds the scheduler crontab
+3. **Terminal**: `docker exec` launches Claude Code (with the project's permission-mode flags) or a bash login shell, with a PTY
+4. **Stop**: Container halted (its filesystem layer and both named volumes persist)
+5. **Restart**: Existing container restarted; if any `triple-c.*` label no longer matches the project's settings, the container is committed to a snapshot image, removed, and recreated from that snapshot — so installed packages survive
+6. **Migrate**: The project is moved onto a newer base image without losing its volumes — see below
+
+Each recreation moves the `triple-c-snapshot-{projectId}:latest` tag, leaving the image it pointed
+at before untagged but still on disk — multiple gigabytes per recreation. `sweep_orphaned_snapshots`
+clears those after a recreation and after a migration is accepted. It only ever removes images that
+are **both** untagged *and* labelled `triple-c.managed=true`, so a live snapshot tag and a
+migration's `pre-migration-*` rollback pin are structurally out of reach, and removal is unforced so
+Docker itself refuses while any container — including a stopped project's — is still built from the
+image.
+7. **Reset**: Container, snapshot image **and both named volumes** all removed, then recreated from the clean base image. `remove_project_volumes` deletes `triple-c-home-{projectId}` and `triple-c-claude-config-{projectId}`, so `~/.claude`, `~/.claude.json`, the OAuth login, installed skills, session transcripts and the scheduler's tasks are all lost.
+
+### Base-Image Migration
+
+A container is created from `triple-c-snapshot-{projectId}:latest` whenever that image exists, and
+every recreation re-commits it. So without an explicit act, a project stays on the base image it was
+first built from **forever** — it never picks up a new `/usr/local/bin` shim, a new `socat`, or a
+security update. **Update container base…** (Project Home → overflow menu) is the non-destructive
+way out; Reset is the destructive one. `docker/migration.rs` owns it.
+
+- **Staleness is surfaced, not acted on.** `triple-c.base-image-id` records the lineage and
+  `get_container_staleness` reports it as a banner, but it is deliberately *not* compared in
+  `container_needs_recreation`. Comparing it there would recreate every project *from its own
+  snapshot* on the next base bump: churn on the old base, and the "you should migrate" signal
+  consumed without migrating. A missing lineage label means "unknown, probe instead" — never
+  "stale".
+- **What comes across**: the apt package delta and user-authored files, computed by diffing two
+  filesystem manifests through dpkg ownership and presence-in-the-new-base. (`docker diff` is
+  useless here — on a snapshot-derived container it only reports changes since the last commit.
+  Measured on a real project, manifest diffing turned 8,677 raw path differences into 2 genuinely
+  user-authored ones.) Both named volumes are untouched at every step, so `$HOME`, the OAuth login,
+  skills, transcripts and scheduler tasks simply re-attach.
+- **What does not**: `/etc` is reported but never copied — the old lineage has
+  `/etc/apt/sources.list.d/nodesource.sources` where the current base has `nodesource.list`, and
+  having both breaks every `apt-get update`. `/var` is not copied either, and that is the one way
+  migration is *more* destructive than an ordinary recreate: a database under `/var/lib` rides along
+  on a recreate, but a migration builds from the base and the apt replay hands back an empty
+  cluster. `unpreserved_data()` names those directories in the pre-flight, the banner and the final
+  report.
+- **Crash-safety**: `:latest` keeps pointing at the old lineage until the final commit, so any
+  failure before that self-heals — the next start just recreates from the old snapshot. After the
+  container swap, a `triple-c.migration-state=in-progress` label plus a persisted state file let the
+  app offer **resume** or **rollback**. Rollback restores the system layer only; work done in
+  `$HOME` during a migrated session survives it.
 
 ### Mounts
 
 | Target in Container | Source | Type | Notes |
 |---|---|---|---|
-| `/workspace` | Project directory | Bind | Read-write |
-| `/home/claude/.claude` | `triple-c-claude-config-{projectId}` | Named Volume | Persists across container recreation |
+| `/workspace/<mount-name>` | Each configured project folder | Bind | Read-write; one per folder |
+| `/home/claude` | `triple-c-home-{projectId}` | Named Volume | Home directory; survives stop/start and recreation |
+| `/home/claude/.claude` | `triple-c-claude-config-{projectId}` | Named Volume | Nested inside the home volume; Docker gives the more specific mount precedence |
 | `/tmp/.host-ssh` | SSH key directory | Bind | Read-only; entrypoint copies to `~/.ssh` |
-| `/home/claude/.aws` | AWS config directory | Bind | Read-only; for Bedrock auth |
-| `/var/run/docker.sock` | Host Docker socket | Bind | If "Allow container spawning" is ON, or auto-enabled by stdio+Docker MCP servers |
+| `/tmp/.host-aws` | AWS config directory | Bind | Read-only; entrypoint copies to `~/.aws`; for Bedrock auth |
+| `/tmp/.host-ca` | CA certificate file or directory | Bind | Read-only; entrypoint installs into the system and NSS stores |
+| `/var/run/docker.sock` | Host Docker socket | Bind | If "Allow container spawning" is ON |
 
-### Authentication Modes
+These two named volumes are the only ones a project owns. Both are removed by Reset and by project
+removal, and by nothing else.
 
-Each project can independently use one of:
+### Corporate CA Certificates
 
-- **Anthropic** (OAuth): User runs `claude login` inside the terminal on first use. Token persisted in the config volume across restarts and resets.
-- **AWS Bedrock**: Per-project AWS credentials (static keys, profile, or bearer token). SSO sessions are validated before launching Claude for Profile auth.
-- **Ollama**: Connect to a local or remote Ollama server via `ANTHROPIC_BASE_URL` (e.g., `http://host.docker.internal:11434`). Requires a model ID, and the model must be pulled (or used via Ollama cloud) before starting the container.
-- **OpenAI Compatible**: Connect through any OpenAI API-compatible endpoint (LiteLLM, OpenRouter, vLLM, text-generation-inference, LocalAI, etc.) via `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN`. API key stored securely in OS keychain.
+A global **Certificates** setting (`AppSettings::ca_cert_path`) with a per-project override
+(`Project::ca_cert_path`), accepting a single certificate file **or** a directory. It follows the
+SSH/AWS host-mount pattern — read-only bind mount at `/tmp/.host-ca`, applied by the entrypoint on
+every start — so it survives recreation, migration and Reset.
 
-> **Note:** Ollama and OpenAI Compatible support is best-effort. Claude Code is designed for Anthropic models, so some features (tool use, extended thinking, prompt caching, etc.) may not work as expected with non-Anthropic models behind these backends.
+- **Certificates are renamed to `.crt`.** `update-ca-certificates` globs `*.crt`, case-sensitively;
+  a `.pem` merely copied into `/usr/local/share/ca-certificates/` is ignored in total silence.
+  `container_cert_name()` in Rust does the renaming, mirrored in a few lines of shell in the
+  entrypoint. A single-file mount lands at `/tmp/.host-ca/<name>.crt`, so the entrypoint only ever
+  sees a directory.
+- **The system store is not enough.** Only curl, git and apt read it. Node — and therefore Claude
+  Code itself — needs `NODE_EXTRA_CA_CERTS`; Python and requests need
+  `REQUESTS_CA_BUNDLE`/`SSL_CERT_FILE`; Chromium reads neither and wants its own NSS database at
+  `~/.pki/nssdb`, seeded with `certutil` (from `libnss3-tools`). The NSS step warns and continues
+  rather than failing the start.
+- **Those env vars are set from Rust at creation, never exported by the entrypoint.** A terminal
+  session is a `docker exec`, which inherits the container's configured env and sees nothing the
+  entrypoint exported — the same lesson that made `$BROWSER` an image-level `ENV`. They are emitted
+  **empty** when no CA is configured, because `docker commit` bakes env into the snapshot image.
+- **`triple-c.ca-fingerprint` covers the certificate bytes, not the path.** Replacing a rotated CA
+  at the same location still forces the recreation that copies it in. Clearing the setting actively
+  **removes** `triple-c-*.crt` from the container — `/usr/local/share` rides the project's snapshot,
+  so turning the feature off has to undo, not merely stop.
 
 ### Container Spawning (Sibling Containers)
 
@@ -60,26 +236,256 @@ When "Allow container spawning" is enabled per-project, the host Docker socket i
 
 If the Docker access setting is toggled after a container already exists, the container is automatically recreated on next start to apply the mount change. The named config volume (keyed by project ID) is preserved across recreation.
 
-### MCP Server Architecture
+### Docker Socket Path
 
-Triple-C supports [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers as a Beta feature. MCP servers extend Claude Code with external tools and data sources.
+The socket path is OS-aware:
+- **Linux/macOS**: `/var/run/docker.sock`
+- **Windows**: `//./pipe/docker_engine`
 
-**Modes**: Each MCP server operates in one of four modes based on transport type and whether a Docker image is specified:
+Users can override this in Settings via the global `docker_socket_path` option.
 
-| Mode | Where It Runs | How It Communicates |
-|------|--------------|---------------------|
-| Stdio + Manual | Inside the project container | Direct stdin/stdout (e.g., `npx -y @mcp/server`) |
-| Stdio + Docker | Separate MCP container | `docker exec -i <mcp-container> <command>` from the project container |
-| HTTP + Manual | External / user-provided | Connects to the URL you specify |
-| HTTP + Docker | Separate MCP container | `http://<mcp-container>:<port>/mcp` via Docker DNS on a shared bridge network |
+## Models and Authentication
 
-**Key behaviors**:
-- **Global library**: MCP servers are defined globally in the MCP sidebar tab and stored in `mcp_servers.json`
-- **Per-project toggles**: Each project enables/disables individual servers via checkboxes
-- **Auto-pull**: Docker images for MCP servers are pulled automatically if not present when the project starts
-- **Docker networking**: Docker-based MCP containers run on a per-project bridge network (`triple-c-net-{projectId}`), reachable by container name — not localhost
-- **Auto-detection**: Config changes are detected via SHA-256 fingerprints and trigger automatic container recreation
-- **Config injection**: MCP server configuration is written to `~/.claude.json` inside the container via the `MCP_SERVERS_JSON` environment variable, merged by the entrypoint using `jq`
+### Authentication Modes
+
+Each project can independently use one of:
+
+- **Anthropic** (OAuth or shared token): either the shared `claude setup-token` token injected as `CLAUDE_CODE_OAUTH_TOKEN` (see below), or a per-container `claude login`. An interactive login's token lives in the config volume and survives container stop/start and recreation — but **not** a Reset, which deletes the volumes.
+- **AWS Bedrock**: Per-project AWS credentials (static keys, profile, or bearer token). SSO sessions are validated before launching Claude for Profile auth.
+- **Ollama**: Connect to a local or remote Ollama server via `ANTHROPIC_BASE_URL` (e.g., `http://host.docker.internal:11434`). Requires a model ID, and the model must be pulled (or used via Ollama cloud) before starting the container.
+- **llama.cpp**: Connect to a local or remote `llama-server` via `ANTHROPIC_BASE_URL` (e.g., `http://host.docker.internal:8080` — 8080 is `llama-server`'s default port). `ANTHROPIC_AUTH_TOKEN` is set to a placeholder; `llama-server` ignores it unless it was started with `--api-key`.
+- **OpenAI Compatible**: Connect through a gateway that implements the **Anthropic Messages API**, via `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN`. API key stored securely in OS keychain. Triple-C can run that gateway for you — see [Model Gateway](#model-gateway-litellm-sibling-container).
+
+> **The endpoint must speak the Anthropic Messages API.** Claude Code only ever sends
+> `POST /v1/messages?beta=true` in Anthropic Messages format to `ANTHROPIC_BASE_URL` — it never
+> speaks OpenAI's `/v1/chat/completions`. So a server that exposes *only* an OpenAI-compatible API
+> (plain vLLM, text-generation-inference, LocalAI, OpenRouter, …) will **not** work behind any of
+> these backends. What does work: **LiteLLM**, which exposes an Anthropic-shaped route, and
+> **Ollama** and **llama.cpp**, both of which implement `POST /v1/messages` natively — which is why
+> they get first-class backends of their own rather than going through a translation layer.
+
+#### Model alias variables
+
+The `opus` / `sonnet` / `haiku` / `fable` aliases in Claude Code resolve to Anthropic model IDs by
+default. Against a local server those IDs do not exist, so anything that uses an alias fails —
+most visibly the **background** calls (conversation titles, summaries), which use `haiku`.
+
+For every backend that points at a custom endpoint (Ollama, llama.cpp, OpenAI Compatible),
+Triple-C therefore sets all four:
+
+| Variable | Value |
+|---|---|
+| `ANTHROPIC_DEFAULT_OPUS_MODEL` | the backend's configured model ID |
+| `ANTHROPIC_DEFAULT_SONNET_MODEL` | the backend's configured model ID |
+| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | the **Background model** override, else the configured model ID |
+| `ANTHROPIC_DEFAULT_FABLE_MODEL` | the backend's configured model ID |
+
+A local server usually serves exactly one model, so pointing every alias at it is the right
+default. If you run a second, smaller model for cheap background work, set **Background model**
+(Config → Model, and in global Backend settings) and only the Haiku alias moves.
+
+These are *not* set for the Anthropic or Bedrock backends, which reach servers that really do host
+the Anthropic model IDs. Triple-C manages all four names, so they cannot be set as custom
+environment variables. (`ANTHROPIC_SMALL_FAST_MODEL` is deprecated and is not used.)
+
+> **Note:** Ollama, llama.cpp and OpenAI Compatible support is best-effort. Claude Code is designed for Anthropic models, so some features (tool use, extended thinking, prompt caching, etc.) may not work as expected with non-Anthropic models behind these backends.
+
+### Model Gateway (LiteLLM sibling container)
+
+For providers that only speak OpenAI's API, Triple-C can run **LiteLLM** as a sibling container
+(`docker/gateway.rs`, `gateway-container/`) that gives Claude Code the Anthropic-format front end it
+requires. Settings → Gateway configures the provider prefix (`openai`, `azure`, `gemini`, `groq`,
+…), an optional API base override, the models to serve, and the host port (default `4000`). A
+project then consumes it with the OpenAI Compatible backend. It mirrors the STT container's
+lifecycle, including auto-start with the app.
+
+Its bind address is **detected, never `0.0.0.0`**. Unlike STT, the consumers are *project
+containers*, so loopback alone is not always enough: Docker Desktop binds `127.0.0.1` and advertises
+`host.docker.internal`; native Linux binds the default bridge gateway (`172.17.0.1`) and advertises
+the same literal. `GatewayBinding` derives the bind address and the advertised `base_url` together
+so the two cannot drift. A wildcard bind would be LAN-reachable — Docker's rules precede host
+firewalls — in front of a config file holding a billed provider key. A LiteLLM `master_key` is
+**always** set, because LiteLLM without one accepts any key.
+
+### Shared Claude Authentication Token
+
+Rather than running `claude login` in every container, `claude setup-token` can be run once
+(`commands/auth_token_commands.rs`). The flow borrows a running container, runs the CLI on a PTY,
+and the long-lived token it prints is stored in the OS keychain — it is never returned to the
+frontend and never logged. Streamed output passes through a chunk-boundary-safe redactor that masks
+anything resembling an `sk-ant-` secret.
+
+The token is injected as `CLAUDE_CODE_OAUTH_TOKEN` into every project where the backend is
+Anthropic, the project has not opted out (`use_shared_auth_token`, default `true`), and a token is
+actually stored. It is a reserved env key, so it cannot be hand-set as a custom variable.
+
+Rotation is tracked with a random id (not a hash of the token) mirrored into the
+`triple-c.claude-token-version` label — a hash in a `docker inspect`-readable label would be an
+offline verification oracle. Acquiring, rotating, revoking or opting out changes that label, which
+forces a container recreation on the next start; that is when a container picks the token up or has
+it cleared.
+
+## Bridges to the Host
+
+### URL Relay (host browser)
+
+There is no browser and no display inside the container, so any CLI that wants to open a web page
+— `gh auth login`, `aws sso login`, `gcloud auth login`, `az login`, vendor CLIs, `xdg-open`,
+Python's `webbrowser` — simply fails. The URL relay forwards the *request* to the host, where the
+user's real browser is. Nothing is rendered or forwarded from the container; only the URL travels.
+It complements the Auth Bridge below: the relay gets the login page open, the bridge lets the
+callback land.
+
+**Transport — an OSC escape sequence, following `osc52-clipboard`.** `container/triple-c-open`
+writes
+
+```
+ESC ] 7777 ; open ; <base64(url)> BEL
+```
+
+to **`/dev/tty`**, and `TerminalView.tsx` picks it up with `term.parser.registerOscHandler(7777, …)`.
+`/dev/tty` rather than stdout is the whole point: the shim usually runs as a grandchild of
+something that captures its children's output (Claude Code invoking `gh auth login` as a tool
+call), so a printed sentinel line — the `###TRIPLE_C_SSO_REFRESH###` approach — would be swallowed
+by the intermediate process and never reach the terminal. A control sequence on the controlling
+terminal always arrives, and is invisible to terminals that don't know it. Base64 keeps a `;`,
+`BEL` or `ESC` inside the URL from breaking out of the sequence.
+
+**Container side** — `container/triple-c-open`, installed as `xdg-open`, `sensible-browser`,
+`www-browser`, `x-www-browser`, `gnome-open`, `gvfs-open`, `kde-open`, `open`, and exported as
+`$BROWSER`. Ubuntu 24.04 ships a real `/usr/bin/sensible-browser` (from `sensible-utils`), so that
+one is `dpkg-divert`ed rather than merely shadowed by a `/usr/local/bin` symlink; `www-browser` and
+`x-www-browser` are registered through `update-alternatives` and pinned with `--set`, because
+`sensible-browser` probes them by absolute path and because a later `apt install firefox` must not
+be able to steal them. `xdg-open` is diverted pre-emptively so installing `xdg-utils` inside the
+container cannot displace the relay. `BROWSER` is an image-level `ENV` — terminal sessions are
+separate `docker exec`s and never see what the entrypoint exported — and the entrypoint also
+forwards it into the scheduler's cron environment file.
+
+**No terminal attached** (cron-driven scheduled tasks, or a plain `docker exec` from outside
+Triple-C): there is no handshake and nothing to wait for, so the shim never blocks. The write to
+`/dev/tty` fails, and it prints the URL in plain text on its own line and exits 0 — which lands in
+the scheduler task log where a human can still act on it.
+
+**Security posture — the container is the untrusted side.** `app/src/lib/urlRelay.ts` validates
+before anything reaches `openUrl`: `http:`/`https:` only (`file:`, `javascript:`, `data:` and every
+registered protocol handler rejected), no embedded credentials, no control characters or
+whitespace, length-capped, and returned WHATWG-normalized so the prompt shows exactly what will
+open. Nothing opens automatically — the user confirms in the existing `UrlToast`, and prompts are
+rate-limited (5 per 10 s, repeats of the same URL collapsed) so a loop in the container cannot bury
+the UI.
+
+**Web terminal** — deliberately *not* a copy of the desktop behaviour. The browser there belongs to
+a remote viewer, possibly on a phone across a tunnel, so `terminal.html` renders the relayed URL as
+a tap-to-open link banner with the same scheme allowlist and rate limit, and opens nothing by
+itself. The OSC handler is registered regardless so the sequence is consumed rather than painted as
+garbage.
+
+### Auth Bridge
+
+Browser-based logins run *inside* a container (`claude login`, `aws sso login`, Concourse
+`fly login`) start an ephemeral HTTP listener on the container's loopback and expect the host
+browser's redirect to reach it. `auth_bridge/` closes that gap:
+
+- Listeners are discovered by parsing `/proc/net/tcp{,6}` every 2 seconds — the image ships no
+  `ss`, `netstat` or `lsof`. Only `TCP_LISTEN` rows bound to loopback are considered; wildcard
+  binds are deliberately ignored (that is the port-mappings feature's job).
+- Each discovered port is bound on the host at **the same port number**, on `127.0.0.1` (required)
+  and `[::1]` (best effort) — never a wildcard address. Node resolves `localhost` to IPv6 first, so
+  `claude login` often binds `::1` alone; the bridge follows the family it actually finds.
+- Traffic is carried in over the Docker API by an attached exec running `socat`, because container
+  IPs are not routable from the host on Docker Desktop.
+- Ports already covered by the project's port mappings are skipped, and a host port that is already
+  in use is reported as a conflict rather than fought over.
+
+Opt-in per project (`auth_bridge_enabled`, default `false`), purely host-side, so toggling it never
+recreates the container. The poller stops on its own when the container stops.
+
+**Security posture:** the host side binds loopback only. Everything reachable through it is an
+unauthenticated service inside the container, so widening those addresses would publish container
+internals to the LAN. Nothing else on the network can reach a bridged port.
+
+### Browser View
+
+Watch — and take over — the browser Claude is driving with Playwright inside the container. The
+**Browser** tab runs Playwright's own dashboard (`browser.bind()` plus `playwright-cli show`) in the
+container and fronts it with a **token-gated** loopback proxy on the host (`browser_view/`). Opt-in
+per project.
+
+- **It deliberately does not reuse the auth bridge's `PortForward`**, which binds an
+  unauthenticated port — fine for a throwaway OAuth listener, wrong for remote control of a browser.
+  Host ports are confined to `47820..=47827` because CSP `frame-src` cannot express a port range and
+  has to enumerate them; a unit test asserts the Rust range matches `tauri.conf.json`.
+- **Pop out** puts the same URL in a second OS window (`popout.rs`), so the view can be watched on
+  another monitor or pinned on top while the main window is used for work. No capability lists that
+  window, so it has **no IPC surface**; the app CSP does not apply to it either, because it is a
+  top-level document rather than a frame — the token gate is what protects the port in both cases.
+  The window is owned by the *session*, so the supervisor's teardown closes it. The pane drops its
+  iframe while popped out, and both viewers can drive the browser.
+- **Open page…** launches a browser in the container at a URL and viewport you choose and binds it,
+  so the pane shows it (`page.rs`). This is what serves container-side auth — the OAuth callback
+  listener is *in* the container, so a container-side browser closes the loop with no host round
+  trip and no auth bridge — and dev servers on container loopback. Re-opening with a helper already
+  up *navigates* rather than relaunching, so a session signed in on one page survives to the next.
+- **Resizing the window does not resize the page.** The viewer is a CDP screencast: a bigger window
+  is the same pixels drawn larger. `page.setViewportSize()` is what reflows, and match-window mode
+  pushes the pop-out's settled size into it, debounced by generation counter because a drag emits
+  continuously and each event costs a container exec.
+- **Setup is two clicks, and nothing installs itself.** Detection has to look past `node_modules` —
+  `claude mcp add … npx @playwright/mcp@latest` installs into `~/.npm/_npx/<hash>/node_modules` — and
+  hops from a wrapper `playwright` to its **nested** `playwright-core`, because npm does not hoist
+  for global installs and the wrapper ships no type definitions to read a version from. Installing
+  puts Playwright in `/workspace` with `--no-save` (not a bind mount, so it touches nothing of
+  yours) and browsers in `~/.cache/ms-playwright`, which is inside the home volume and so survives
+  recreation *and* migration.
+- **`@playwright/mcp` can never satisfy this pane** on its own: it bundles a `playwright-core` that
+  binds, but never `@playwright/cli`, which is the viewer. It is what binds sessions automatically
+  once Playwright is present — not a setup route.
+
+### Host File Transfers
+
+Four routes move files across the boundary: **Upload…** and the per-row **Save to host…** in the
+Files tab, a file dropped onto the Terminal tab, and **Back up container**. All four share one path
+policy in `commands/file_commands.rs`.
+
+- **The OS dialogs are opened by Rust, not by the webview.** `upload_files_to_container` and
+  `download_container_file` drive `tauri-plugin-dialog` themselves and take nothing but a project
+  id and a container-side path; `FilesTab.tsx` imports no dialog plugin and `useFileManager`'s
+  `uploadFiles` takes no argument at all. The web UI can ask for a dialog, and that is the whole of
+  its influence over where a file comes from or goes — it cannot name a host path as an *input*.
+  This is a boundary rather than a convention: a dialog the page itself opens is only as trustworthy
+  as the page. Be precise about the limit, though — host paths still travel *outward* in error text,
+  canonical ones included, so this closes the inbound direction and not both.
+- **The dialog's pre-filled name is sanitized, because a container authored it.** On Windows the
+  save dialog parses its name box as a path, and a container can name a file
+  `..\..\Users\you\…\Word\STARTUP\x.dotm` — one POSIX segment, so nothing upstream objects.
+  `suggested_save_name` replaces every separator and every character NTFS refuses, so the string
+  cannot be a path on any platform this ships to.
+- **One policy for every host path.** A source or destination whose path passes through a hidden
+  folder (`~/.ssh`, `~/.cache`, `~/.local/share`, anything dot-prefixed) or a system location is
+  refused, and the check is applied both to the path as written and to what it resolves to after
+  symlinks. It over-catches deliberately, so it will occasionally refuse somewhere a person
+  genuinely meant — `~/.config`, say — and the refusal is a sentence naming the folder that tripped
+  it, not an errno.
+- **Uploads are capped at 256 MB per file**; past that the answer is a mount, not a copy. One
+  dialog's selection is handled file by file, so a folder or an oversized file among the selection
+  is reported by name and does not stop the others. Uploaded files land owned by the container user,
+  not root. A cancelled dialog is silent — `Ok(None)`, not an error.
+- **`download_container_file` is one file and files only** — no button on a folder row. A directory
+  is what `download_container_backup` is for. There is no drop target on the Files pane; the
+  Terminal tab keeps the one it has.
+
+## Inside a Project
+
+### Container Introspection (Capability Tiles)
+
+`list_container_capabilities` (`commands/inspect_commands.rs`) runs a read-only `find`/`jq` script
+inside a running container and returns counts plus item lists for **skills, agents, commands, hooks,
+plugins and MCP servers**, at user scope (`/home/claude/.claude`) and project scope
+(`/workspace/*/.claude`, `/workspace/*/.mcp.json`). Overview renders these as tiles.
+
+Triple-C does not create or edit any of them — Claude Code owns that configuration, and the tiles
+link out to a terminal where `/agents`, `/hooks`, `/plugins` and `/mcp` do the real work.
 
 ### Mission Control Integration
 
@@ -99,75 +505,122 @@ The web terminal shares the existing `ExecSessionManager` via `Arc`-wrapped stor
 
 ### Speech-to-Text (Voice Mode)
 
-Triple-C includes optional speech-to-text powered by [Faster Whisper](https://github.com/SYSTRAN/faster-whisper) running in a separate Docker container. When enabled, a microphone button appears in the bottom-left corner of each terminal view.
+Triple-C includes optional speech-to-text powered by [Faster Whisper](https://github.com/SYSTRAN/faster-whisper) running in a separate Docker container. When enabled, a microphone button appears in the StatusBar whenever a terminal session is active.
 
 - **Hotkey**: `Ctrl+Shift+M` to toggle recording
 - **Models**: `tiny`, `small`, or `medium` (configurable in Settings)
 - **Port**: Default `9876` (configurable)
+- **Input device**: Selectable in Settings when the host exposes more than one microphone
 - **Language**: Optional language hint for transcription
 - **Auto-start**: When STT is enabled in Settings, the container starts automatically with the app — no need to manually start it after each restart
 - **On-demand fallback**: If not auto-started, the container starts automatically when you first click the mic button
 
 **How it works**: Audio is captured in the browser via the Web Audio API, encoded as WAV, and sent to the Faster Whisper container's `/transcribe` endpoint. The transcribed text is inserted directly into the active terminal. The STT container uses a named Docker volume (`triple-c-stt-model-cache`) to cache Whisper models across restarts.
 
-### Docker Socket Path
-
-The socket path is OS-aware:
-- **Linux/macOS**: `/var/run/docker.sock`
-- **Windows**: `//./pipe/docker_engine`
-
-Users can override this in Settings via the global `docker_socket_path` option.
-
 ## Key Files
 
+### Frontend — layout and projects
+
 | File | Purpose |
 |---|---|
-| `app/src/App.tsx` | Root layout (TopBar + Sidebar + Main + StatusBar) |
-| `app/src/index.css` | Global CSS variables, dark theme, `color-scheme: dark` |
-| `app/src/components/layout/TopBar.tsx` | Terminal tabs + Docker/Image status indicators |
-| `app/src/components/layout/Sidebar.tsx` | Responsive sidebar (25% width, min 224px, max 320px) |
-| `app/src/components/layout/StatusBar.tsx` | Running project/terminal counts |
-| `app/src/components/projects/ProjectCard.tsx` | Project config, backend selector, action buttons |
-| `app/src/components/projects/ClaudeCodeSettingsModal.tsx` | Claude Code CLI settings modal (TUI mode, effort, focus, caching) |
+| `app/src/App.tsx` | Root layout (TopBar + Sidebar + Main + StatusBar + ToastHost) |
+| `app/src/index.css` | Global CSS variables, dark theme, `color-scheme: dark`, `:focus-visible` ring |
+| `app/src/components/layout/TopBar.tsx` | Hosts MainTabs + Docker/Image status indicators + Help |
+| `app/src/components/layout/MainTabs.tsx` | The single main-area tab strip (Project Home + terminal tabs), pointer-event drag reordering |
+| `app/src/components/layout/Sidebar.tsx` | Responsive sidebar (25% width, min 224px, max 320px), collapsible to an icon rail |
+| `app/src/components/layout/StatusBar.tsx` | Project/terminal counts, Jump to Current, STT mic |
+| `app/src/components/projects/ProjectRow.tsx` | Select-only sidebar row; opens Project Home, with hover start/stop and terminal controls |
 | `app/src/components/projects/ProjectList.tsx` | Project list in sidebar |
-| `app/src/components/projects/FileManagerModal.tsx` | File browser modal (browse, download, upload) |
-| `app/src/components/projects/ContainerProgressModal.tsx` | Real-time container operation progress |
-| `app/src/components/mcp/McpPanel.tsx` | MCP server library (global configuration) |
-| `app/src/components/mcp/McpServerCard.tsx` | Individual MCP server configuration card |
-| `app/src/components/settings/SettingsPanel.tsx` | Docker, AWS, timezone, web terminal, and global settings |
+| `app/src/components/projects/PermissionModeControl.tsx` | Plan / Default / Accept Edits / Bypass segmented control |
+| `app/src/components/ui/` | Shared primitives: `Modal`, `Button`, `Toggle`, `Field`, `SegmentedControl`, `StatusIndicator`, `SaveIndicator`, `OverflowMenu`, `ToastHost`, `Tooltip` |
+| `app/src/hooks/useKeyboardShortcuts.ts` | `Ctrl+T`, `Ctrl+Shift+W`, `Ctrl+Tab`, `Ctrl+1..9`, `Ctrl+Shift+←/→` |
+| `app/src/hooks/useContainerProgress.ts` | `container-progress` event → inline progress lines |
+
+### Frontend — Project Home
+
+| File | Purpose |
+|---|---|
+| `app/src/components/projects/home/ProjectHome.tsx` | Project Home shell: header actions, overflow menu, tab strip |
+| `app/src/components/projects/home/OverviewTab.tsx` | Permission mode, summary, capability tiles, recent sessions and tasks |
+| `app/src/components/projects/home/SessionsTab.tsx` | Past Claude sessions with Resume |
+| `app/src/components/projects/home/AutomationTab.tsx` | Scheduler tasks: create, toggle, run now, logs, remove, notifications |
+| `app/src/components/projects/home/TaskEditorModal.tsx` | Create/edit a scheduled task; `taskValidation.ts` holds the cron and schedule rules |
+| `app/src/components/projects/home/ConfigTab.tsx` | Config sections (Workspace, Model, Access, Runtime) |
+| `app/src/components/projects/home/FilesTab.tsx` | Container-side file browser (navigate, view, rename, new folder) plus **Upload…** and per-row **Save to host…**; imports no dialog plugin — the dialogs are Rust's |
+| `app/src/components/projects/home/BrowserTab.tsx` | Browser view pane: detect, install, watch, take over, pop out |
+| `app/src/components/projects/home/OpenPageDialog.tsx` | Open a URL in the container's browser at a chosen viewport |
+| `app/src/components/projects/home/ContainerMigrationBanner.tsx` | Base-image staleness banner, migration progress, resume/rollback |
+| `app/src/components/projects/home/CapabilityTiles.tsx` | Read-only skills/agents/commands/hooks/plugins/MCP counts |
+| `app/src/components/projects/ClaudeCodeSettingsEditor.tsx` | Claude Code CLI settings → `tui`, `effortLevel`, `viewMode`, `autoScrollEnabled`, `showThinkingSummaries`, `awaySummaryEnabled`, plus the env-var flags (scrub, 1h caching). Every managed key is re-emitted on each start, `null` meaning "delete". |
+
+### Frontend — settings, terminal and hooks
+
+| File | Purpose |
+|---|---|
+| `app/src/components/settings/SettingsPanel.tsx` | Docker, AWS, timezone, certificates, gateway, web terminal, STT, shared auth and global settings |
+| `app/src/components/settings/CertificateSettings.tsx` | Corporate CA certificate path (global), with `CaCertPathInput` |
+| `app/src/components/settings/GatewaySettings.tsx` | LiteLLM gateway: provider, API base, models, port, container controls |
+| `app/src/components/settings/SharedAuthSettings.tsx` | Acquire / revoke the shared Claude authentication token |
 | `app/src/components/settings/WebTerminalSettings.tsx` | Web terminal toggle, URL, token management |
-| `app/src/components/settings/SttSettings.tsx` | STT settings panel (model, port, language, container controls) |
-| `app/src/components/terminal/TerminalView.tsx` | xterm.js terminal with WebGL, URL detection, OSC 52 clipboard, image paste |
-| `app/src/components/terminal/SttButton.tsx` | Mic button overlay with on-demand container start |
-| `app/src/components/terminal/TerminalTabs.tsx` | Tab bar for multiple terminal sessions (claude + bash) |
+| `app/src/components/settings/SttSettings.tsx` | STT settings panel (model, port, language, device, container controls) |
+| `app/src/components/settings/UpdateDialog.tsx` | New-release notice with download links (`update_commands.rs`) |
+| `app/src/components/terminal/TerminalView.tsx` | xterm.js terminal with WebGL, URL detection, OSC 52 clipboard, OSC 7777 URL relay, image paste |
+| `app/src/components/terminal/SttButton.tsx` | Mic button with on-demand STT container start |
 | `app/src/hooks/useTerminal.ts` | Terminal session management (claude and bash modes) |
-| `app/src/hooks/useFileManager.ts` | File manager operations (list, download, upload) |
-| `app/src/hooks/useMcpServers.ts` | MCP server CRUD operations |
+| `app/src/hooks/useProjectActions.ts` | Start/stop/reset/backup and terminal-opening helpers |
+| `app/src/hooks/useContainerMigration.ts` | Staleness polling, migration run, resume and rollback |
+| `app/src/hooks/useFileManager.ts` | File browser operations (list, navigate, rename, mkdir) and the host transfers (upload, save one file out); never handles a host path |
+| `app/src/hooks/useClaudeAuth.ts` | Shared-token status and acquisition |
 | `app/src/hooks/useSTT.ts` | Speech-to-text recording, transcription, and container management |
-| `app/src-tauri/src/docker/container.rs` | Container creation, mounts, env vars, MCP injection, fingerprinting |
-| `app/src-tauri/src/docker/exec.rs` | PTY exec sessions, file upload/download via tar |
+| `app/src/lib/urlRelay.ts` | Host-side relay validation: OSC 7777 parsing, http/https allowlist, rate limiting |
+| `app/src/lib/wav.ts` | WAV audio encoding for STT transcription |
+
+### Backend (Rust)
+
+| File | Purpose |
+|---|---|
+| `app/src-tauri/src/docker/container.rs` | Container creation, mounts, env vars, labels, recreation checks, `remove_project_volumes` |
+| `app/src-tauri/src/docker/exec.rs` | `create_attached_exec()` — the single attached-exec path; one-shot execs and single-file tar building |
 | `app/src-tauri/src/docker/image.rs` | Image building/pulling |
-| `app/src-tauri/src/docker/network.rs` | Per-project bridge networks for MCP containers |
+| `app/src-tauri/src/docker/migration.rs` | Base-image migration: manifest capture, delta computation, crash-recovery state machine |
+| `app/src-tauri/src/docker/ca_certs.rs` | CA certificate discovery, `.crt` renaming, fingerprinting |
+| `app/src-tauri/src/docker/gateway.rs` | LiteLLM sibling container: binding detection, config rendering, lifecycle |
+| `app/src-tauri/src/docker/stt.rs` | Speech-to-text container lifecycle |
+| `app/src-tauri/src/docker/legacy_cleanup.rs` | One-release migration shim removing leftovers from the deleted MCP feature |
+| `app/src-tauri/src/auth_bridge/` | Loopback callback bridge (`mod.rs`, `proc_net.rs`, `tunnel.rs`) |
+| `app/src-tauri/src/browser_view/` | Browser view: `detect.rs`, `install.rs`, `page.rs`, `popout.rs`, `proxy.rs`, `commands.rs` |
 | `app/src-tauri/src/commands/project_commands.rs` | Start/stop/rebuild Tauri command handlers |
-| `app/src-tauri/src/commands/file_commands.rs` | File manager Tauri commands (list, download, upload) |
-| `app/src-tauri/src/commands/mcp_commands.rs` | MCP server CRUD Tauri commands |
-| `app/src-tauri/src/models/project.rs` | Project struct (backend, Docker access, Claude Code settings, MCP servers, Mission Control) |
-| `app/src-tauri/src/models/mcp_server.rs` | MCP server struct (transport, Docker image, env vars) |
-| `app/src-tauri/src/models/app_settings.rs` | Global settings (image source, Docker socket, AWS, Claude Code settings, web terminal, STT) |
+| `app/src-tauri/src/commands/migration_commands.rs` | Staleness, migrate, confirm, rollback, reconcile, `is_migrating` |
+| `app/src-tauri/src/commands/inspect_commands.rs` | Read-only container views: sessions, capabilities, scheduler tasks |
+| `app/src-tauri/src/commands/auth_token_commands.rs` | `claude setup-token` flow, redaction, keychain storage |
+| `app/src-tauri/src/commands/auth_bridge_commands.rs` | Auth bridge enable/status commands |
+| `app/src-tauri/src/commands/file_commands.rs` | Container-side file commands (list, read, rename, mkdir), the host transfers `upload_files_to_container` and `download_container_file` — each opening its own OS dialog here in Rust — plus `download_container_backup`, and the hidden-folder path policy all of them share |
+| `app/src-tauri/src/commands/stt_commands.rs` | STT start/stop/transcribe Tauri commands |
+| `app/src-tauri/src/commands/web_terminal_commands.rs` | Web terminal start/stop/status Tauri commands |
+| `app/src-tauri/src/models/project.rs` | Project struct (backend, `PermissionMode`, Docker access, Claude Code settings, Mission Control, auth bridge, browser view, CA path, shared-token opt-out) |
+| `app/src-tauri/src/models/app_settings.rs` | Global settings (image source, Docker socket, AWS, CA path, Claude Code settings, web terminal, STT, gateway) |
+| `app/src-tauri/src/models/gateway_settings.rs` | Gateway provider, models, port and API base |
 | `app/src-tauri/src/web_terminal/server.rs` | Axum HTTP+WS server for remote terminal access |
 | `app/src-tauri/src/web_terminal/ws_handler.rs` | WebSocket connection handler and session management |
 | `app/src-tauri/src/web_terminal/terminal.html` | Embedded web UI (xterm.js, project picker, tabs) |
-| `app/src-tauri/src/commands/stt_commands.rs` | STT start/stop/transcribe Tauri commands |
-| `app/src-tauri/src/commands/web_terminal_commands.rs` | Web terminal start/stop/status Tauri commands |
-| `app/src-tauri/src/storage/mcp_store.rs` | MCP server persistence (JSON with atomic writes) |
-| `app/src-tauri/src/docker/stt.rs` | STT Docker container lifecycle (create, start, stop, build, pull) |
-| `app/src/lib/wav.ts` | WAV audio encoding for STT transcription |
+| `app/src-tauri/src/storage/secure.rs` | OS keychain access (per-project secrets, shared token, gateway keys, rotation id) |
+
+### Container and packaging
+
+| File | Purpose |
+|---|---|
+| `container/Dockerfile` | Ubuntu 24.04 sandbox image with Claude Code + dev tools + clipboard/audio shims + browser runtime libraries |
+| `container/entrypoint.sh` | UID/GID remap, SSH setup, CA installation, Docker group config, Claude Code settings injection, Mission Control setup |
+| `container/osc52-clipboard` | Clipboard shim (xclip/xsel/pbcopy via OSC 52) |
+| `container/triple-c-open` | URL relay shim (xdg-open/`$BROWSER`/sensible-browser via OSC 7777); prints the URL when no terminal is attached |
+| `container/audio-shim` | Audio capture shim (rec/arecord via FIFO) for voice mode |
+| `container/triple-c-scheduler` | Bash CLI managing scheduled task JSON and the crontab |
+| `container/triple-c-task-runner` | Cron entry point; maps `TRIPLE_C_PERMISSION_MODE` to flags and runs `claude -p` |
+| `container/triple-c-sso-refresh` | AWS SSO session refresh helper |
+| `gateway-container/` | LiteLLM image and rendered `config.yaml` for the model gateway |
 | `stt-container/Dockerfile` | Faster Whisper STT container image (Python 3.11 + FastAPI) |
 | `stt-container/server.py` | STT HTTP server (POST /transcribe endpoint) |
-| `container/Dockerfile` | Ubuntu 24.04 sandbox image with Claude Code + dev tools + clipboard/audio shims |
-| `container/entrypoint.sh` | UID/GID remap, SSH setup, Docker group config, MCP injection, Claude Code settings injection, Mission Control setup |
-| `container/osc52-clipboard` | Clipboard shim (xclip/xsel/pbcopy via OSC 52) |
-| `container/audio-shim` | Audio capture shim (rec/arecord via FIFO) for voice mode |
+| `branding/` | Logo sources, palette, and `build-icons.py`, which generates every packaged icon |
 
 ## CSS / Styling Notes
 
@@ -180,8 +633,34 @@ Users can override this in Settings via the global `docker_socket_path` option.
 
 **Base**: Ubuntu 24.04
 
-**Pre-installed tools**: Claude Code, Node.js 22 LTS + pnpm, Python 3.12 + uv + ruff, Rust (stable), Docker CLI, git + gh, AWS CLI v2, ripgrep, openssh-client, build-essential
+**Pre-installed tools**: Claude Code, Node.js 22 LTS + pnpm, Python 3.12 + uv + ruff, Rust (stable), Docker CLI, git + gh, AWS CLI v2, ripgrep, openssh-client, build-essential, `libnss3-tools` (for `certutil`, used to seed Chromium's CA store)
 
-**Shims**: `xclip`/`xsel`/`pbcopy` (OSC 52 clipboard forwarding), `rec`/`arecord` (audio FIFO for voice mode)
+**Shims**: `xclip`/`xsel`/`pbcopy` (OSC 52 clipboard forwarding), `xdg-open`/`sensible-browser`/`www-browser`/`x-www-browser`/`$BROWSER` (OSC 7777 URL relay to the host browser), `rec`/`arecord` (audio FIFO for voice mode)
+
+**Browser runtime libraries**: the shared libraries Chromium links against (`libnss3`, `libgbm1`,
+`libatk*`, `libasound2t64`, `libcups2t64`, `libpango`, `libdrm2`, … plus fonts) are baked in, via
+`npx playwright install-deps chromium` at build time. Without them `playwright install chromium`
+downloads a browser that then dies at launch with *"Host system is missing dependencies:
+libnss3.so"* — which is why installing `google-chrome-stable` used to look like the fix (apt was
+pulling the libraries in as *its* dependencies). Measured cost of the layer: +99 packages,
+**+334 MiB unpacked / +119 MiB compressed** (2950 → 3284 MiB unpacked, 759 → 878 MiB compressed).
+Two thirds of that is not avoidable by trimming — `libgbm1`, which Chromium needs, depends on
+`mesa-libgallium`, which depends on `libllvm20`. The list is taken from Playwright rather than
+hand-written so it cannot rot against Ubuntu 24.04's `t64` renames or a future Chromium dependency,
+and the `install-deps --dry-run` that follows it is a build-time assertion: on a platform
+Playwright has no list for, `install-deps` installs nothing and still exits 0.
+
+**Browser binaries are deliberately not baked.** They are large, they are version-coupled to
+whatever Playwright the user installs, and they already persist: `~/.cache/ms-playwright` is inside
+the home volume, so a downloaded browser survives container recreation *and* base-image migration.
+The libraries are the opposite — a runtime `apt-get install` lands in the container's writable
+layer, is re-paid after every Reset, and is lost on migration (which replays apt from a manifest
+against the new base). Baking one and not the other puts each half where it already persists.
+
+**`/home/claude` in the image is seed-only.** It is the mount point of the `triple-c-home-{projectId}`
+volume, so after a project's *first* start the image's copy of that directory is masked permanently.
+A change made under `/home/claude` in the Dockerfile reaches **new projects only** — with or without
+a base-image migration. Anything that must stay upgradable belongs in `/usr/local/bin` or `/opt`, or
+must be seeded by `entrypoint.sh` on every start.
 
 **Default user**: `claude` (UID/GID 1000, remapped by entrypoint to match host)

ROADMAP.md

@@ -0,0 +1,265 @@
+# Triple-C Roadmap — Claude Code Feature Parity
+
+**Date:** 2026-08-09 · **Baseline:** v0.3.0 · **Claude Code reference:** 2.1.226
+
+Companion to [DESIGN-REVIEW.md](DESIGN-REVIEW.md), which covers visual design and
+information architecture. This document covers *which Claude Code capabilities Triple-C
+should surface, and why.*
+
+---
+
+## Guiding principle
+
+> **Triple-C shows state and launches things. Claude Code edits its own config.**
+
+Triple-C's built-in MCP server management was removed in this cycle because Claude Code
+absorbed the capability natively (`claude mcp add/list/remove`, `.mcp.json`, `/mcp`).
+Hooks, skills, agents, plugins, output styles, and statusline are the same species: files
+under `.claude/` with first-class Claude Code TUIs. Building GUI form editors for them
+means losing the same race again.
+
+What Claude Code cannot do is what Triple-C uniquely owns: **the container boundary and
+what persists behind it** — the config volume, workspace mounts, lifecycle, the bundled
+scheduler, and the fleet view across many projects.
+
+---
+
+## Current coverage (v0.3.0)
+
+Triple-C sets exactly six `settings.json` keys, plus a sandbox block:
+
+| Key | Surfaced as |
+|---|---|
+| `tui` | TUI mode select — unset (Claude Code chooses), `default` (classic renderer), `fullscreen` (flicker-free alt-screen). Three distinct states, not two. |
+| `effortLevel` | Effort level select (`low`/`medium`/`high`/`xhigh`) |
+| `viewMode` | Focus mode toggle, written as `"focus"`. Unset means the user's own `verbose` setting and sticky `/focus` choice still apply. |
+| `autoScrollEnabled` | Auto-scroll toggle. Claude Code's default is `true`, so it is the *off* state that writes `false`. |
+| `showThinkingSummaries` | Thinking summaries toggle (Claude Code default `false`) |
+| `awaySummaryEnabled` | Session recap toggle. Claude Code's recap is **on** by default, so again it is the off state that writes `false`. |
+| `sandbox.*` | Sandbox toggle (`enabled`, `enableWeakerNestedSandbox`, `allowUnsandboxedCommands`) |
+
+Every one of those keys is emitted on **every** start, with a JSON `null` standing for
+"delete this key". `~/.claude/settings.json` sits on the config volume and the entrypoint
+merges into it, so a key merely omitted when its control goes off left the previous
+on-value in place forever.
+
+Plus four env feature flags — `CLAUDE_CODE_NO_FLICKER`, `CLAUDE_CODE_ENABLE_AWAY_SUMMARY`,
+`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`, `ENABLE_PROMPT_CACHING_1H` — and arbitrary user-set
+`CLAUDE_CODE_*` vars via the Env Vars modal. The four are written on every container
+create *including* their off value, because `docker commit` bakes a container's env into
+the snapshot image: a value written once would otherwise ride that snapshot into every
+future container. That also makes them Triple-C's to own, so all four are reserved names
+— hand-setting one in the Env Vars modal is skipped with a warning, the same as any other
+`triple-c.*`-managed variable. `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` is what actually enforces
+the recap choice — it takes precedence over `awaySummaryEnabled` *and* over the
+in-container `/config` toggle, so turning the control off sends `0` while leaving it on
+sends an empty value rather than `1`: Triple-C's default must not overrule a `/config`
+choice it never asked about.
+
+Also covered: per-project auth backends (Anthropic OAuth, Bedrock incl. SSO refresh,
+Ollama, OpenAI-compatible), user-level `CLAUDE.md` composition, `claude update` on every
+container start, terminal ergonomics (OAuth URL detection, OSC 52 clipboard, image paste,
+file drag-drop, STT), the web terminal, and workspace backup.
+
+---
+
+## Gap analysis
+
+### Committed for this cycle
+
+| # | Gap | Today | Plan |
+|---|---|---|---|
+| 1 | **Permission modes** | one boolean → `--dangerously-skip-permissions` | Four-state control (Plan / Default / Accept Edits / Bypass) → `--permission-mode`. Verified choices on 2.1.226: `acceptEdits`, `auto`, `bypassPermissions`, `manual`, `dontAsk`, `plan`. |
+| 2 | **Session resume** | none | List sessions from the config volume; `[Resume]` opens a terminal on `claude --resume <id>`. |
+| 3 | **Capability inventory** | none | Read-only counts + names for skills / agents / hooks / plugins / commands / native MCP servers. Deep-link to the terminal to manage. |
+| 4 | **Automation** | `triple-c-scheduler` ships in every container with *zero* UI | Task list, cron editor, run-now, logs, notification badges. |
+| 5 | **Container auth handoff** | manual code paste | See "Authentication handoff" below — design decision pending. |
+
+### Deliberately skipped
+
+Status line builder · output-styles editor · hook *editors* · checkpoint/rewind browser ·
+plugin marketplace browser. Each is niche, natively handled by Claude Code's own TUI, or a
+settings-editor trap. Surface counts and deep-link instead.
+
+### Not yet scheduled
+
+- Granular `permissions.allow` / `ask` / `deny` rules and `additionalDirectories`
+- Sandbox detail settings (`filesystem.allowRead/allowWrite`, `allowedDomains`,
+  `excludedCommands`) — currently documented for hand-editing via `SANDBOX_INSTRUCTIONS`
+- Project-level `.claude/settings.json` vs user-level settings hierarchy
+- A model picker. **Note:** the only model strings in the app today are stale placeholders
+  (`anthropic.claude-sonnet-4-20250514-v1:0` in `AwsSettings.tsx` and `ProjectCard.tsx`,
+  `qwen3.5:27b`, `gpt-4o / gemini-pro / etc.`). These are free-text placeholders, not
+  dropdowns, but they should be refreshed to current model identifiers regardless.
+- The container's settings.json merge is **shallow** (`jq -s '.[0] * .[1]'`), so a
+  user-authored nested block such as `sandbox.filesystem.allowWrite` is replaced wholesale
+  on every container start. Worth deepening to `*` recursive merge.
+
+---
+
+## Authentication handoff
+
+**Goal:** stop making users hand-copy an auth code into every container.
+
+**Constraint discovered during research:** `claude login`'s callback server uses an
+**ephemeral port** and its redirect URI is **not configurable** for the main login flow
+(`--callback-port` and `oauth.callbackPort` apply to *MCP server* OAuth only). So a design
+that pre-assigns each container a fixed callback port and routes to it cannot work as
+stated — there is no fixed port to route.
+
+There is also a known container gotcha: on Linux, Node resolves `localhost` to IPv6 first,
+so the callback server may bind `[::1]:PORT` only and be unreachable over IPv4
+([anthropics/claude-code#44844](https://github.com/anthropics/claude-code/issues/44844)).
+
+Two viable options:
+
+### Option A — long-lived token injection (simple)
+
+`claude setup-token` (verified present on 2.1.226: *"Set up a long-lived authentication
+token (requires Claude subscription)"*) returns a ~1-year OAuth token. Triple-C runs it in
+a running container, stores the token in the OS keychain via the existing `secure.rs`, and
+injects `CLAUDE_CODE_OAUTH_TOKEN` into every container on the Anthropic backend.
+
+**Correction to an earlier assumption in this document.** `setup-token` does *not* start a
+loopback callback listener, so it does not need the Auth Bridge. Verified by running it
+under a pty: its `redirect_uri` is Anthropic-hosted
+(`https://platform.claude.com/oauth/code/callback`), the user copies a code off that page,
+and the CLI blocks at a `Paste code here if prompted >` prompt on **stdin**. A stdin path
+is therefore mandatory — the flow cannot complete without one.
+
+- No routing, no ports, no proxy.
+- One auth event covers every project.
+- Cost: small. Reuses existing keychain and env-injection plumbing.
+- Limits: token is subscription-scoped and expires annually; per the docs a `setup-token`
+  token cannot drive Remote Control sessions or claude.ai connector fetches.
+
+Change detection uses a **random rotation id** in the `triple-c.claude-token-version`
+label, not a hash of the token. Labels are readable by anything that can run
+`docker inspect`, so a hash would be an offline verification oracle — given a candidate
+token you could confirm it. A presence boolean would instead miss rotations and silently
+leave containers on a stale token.
+
+### Option B — the Auth Bridge (general loopback-callback bridge)
+
+Option A only solves Claude Code. The same problem affects every CLI that authenticates by
+starting a temporary loopback listener and opening a browser at a URL that redirects back
+to it — Concourse `fly login` (random loopback port serving `/auth/callback`),
+`aws sso login`, and many others. Inside a container the host browser cannot reach that
+listener, so login stalls.
+
+Because the ports are ephemeral and unconfigurable, nothing can be pre-assigned. The bridge
+**discovers** listeners instead:
+
+1. While enabled for a running project, poll the container for loopback TCP listeners by
+   reading `/proc/net/tcp` and `/proc/net/tcp6` over `docker exec` — no dependency on
+   `ss`/`netstat`/`lsof`, which aren't guaranteed in the image.
+2. For each newly-appeared loopback listener, bind **the same port on the host's
+   `127.0.0.1`** (never `0.0.0.0` — that would expose container internals to the LAN).
+3. Proxy each accepted connection into the container over the Docker API via
+   `socat - TCP:127.0.0.1:<port>` (socat already ships in the image), reusing the existing
+   attached-exec streaming in `docker/exec.rs`. Going through the Docker API rather than a
+   container IP keeps this working on Docker Desktop, where container IPs are not routable
+   from the host.
+4. Fall back to `TCP6:[::1]:<port>` when the listener appeared only on IPv6 — on Linux,
+   Node resolves `localhost` to IPv6 first, so `claude login` frequently binds `::1` only
+   ([anthropics/claude-code#44844](https://github.com/anthropics/claude-code/issues/44844)).
+5. Tear down when the listener vanishes, the container stops, the bridge is disabled, or
+   the app exits. Ports already covered by the project's explicit port mappings are skipped;
+   host-side conflicts are reported rather than silently swallowed.
+
+Opt-in per project (`auth_bridge_enabled`, default off), since it makes container-internal
+loopback services reachable from the host.
+
+**Plan:** ship **A** for Claude Code specifically — it removes the pain for the common case
+at a fraction of the cost — and **B** as the general mechanism covering every other CLI.
+They compose: A means most users never trigger a browser login at all; B catches AWS SSO,
+Concourse, and anything else that needs a real callback.
+
+---
+
+## Sequencing
+
+**Phase 0 — done.** Remove MCP (frontend, backend, entrypoint, docs) with a self-healing
+migration for containers created against the old per-project Docker network.
+
+**Phase 1 — foundations.** Permission modes end-to-end (including the scheduler bug fix
+below). Read-only introspection backend: sessions, capabilities, scheduler.
+
+**Phase 2 — Tier-1 polish.** Focus rings, contrast fixes, real buttons, inline start/stop
+progress, status labels, onboarding welcome screen, shared accessible `<Modal>`.
+
+**Phase 3 — Project Home.** Move project config out of the sidebar card into a tabbed
+main-area view (Overview / Sessions / Automation / Config), dissolving the modal pile and
+splitting the 1,257-line `ProjectCard`.
+
+**Phase 4 — authentication handoff.** Option A, then evaluate B.
+
+**Phase 5 — Library.** Global skills/agents/commands with per-project enable, synced into
+the config volume by the entrypoint. Generalizes the pattern the MCP tab was reaching for.
+
+---
+
+## Bugs found during this review
+
+1. **Scheduled tasks ignore the project's permission setting.**
+   `container/triple-c-task-runner:69` runs
+   `claude -p "$PROMPT" --dangerously-skip-permissions` unconditionally, regardless of the
+   project's Full Permissions toggle. Being fixed as part of Phase 1.
+
+2. **Docs claim Reset preserves credentials; it does not.**
+   `rebuild_project_container` calls `remove_project_volumes`, which deletes both
+   `triple-c-home-{id}` (holding `~/.claude.json`) and `triple-c-claude-config-{id}`
+   (holding `~/.claude`). README.md, HOW-TO-USE.md, and CLAUDE.md all still state that
+   OAuth tokens survive a Reset. Pre-existing; not yet corrected.
+
+3. **An invalid cron expression silently unscheduled every task.** Found while adding
+   task creation to the Automation tab, and the most serious bug in this review.
+   `triple-c-scheduler` never validated `--schedule`, and `rebuild_crontab` regenerates the
+   *entire* crontab and pipes it to `crontab`, which rejects the whole file if any single
+   line is malformed — with the error discarded by `2>/dev/null || true`. So one bad
+   schedule silently unscheduled every other task in the container, reporting success.
+   Reproduced directly. This mattered because the global CLAUDE.md instructs Claude to use
+   this CLI, so Claude itself could trigger it. Fixed at the root: `add` now validates the
+   expression and exits non-zero, and `rebuild_crontab` reports a rejected crontab instead
+   of swallowing it. The Rust `add_scheduled_task` command validates independently.
+
+4. **Reset was destructive with no confirmation.** It deletes both volumes — the login,
+   installed skills, all session transcripts — from a single unconfirmed click, while the
+   comparably destructive Remove already confirmed. Now gated by a dialog that names each
+   loss. Fixed.
+
+5. **Cancelling authentication did not cancel.** Fixed — see the handoff section above.
+
+6. **Stale model placeholders** — see "Not yet scheduled" above.
+
+7. **Silent save failures.** Project config saves on blur; failures went only to
+   `console.error`. Fixed in Phase 3 — `useProjectSave` now renders a
+   Saved / Saving / Save failed indicator and raises a toast.
+
+---
+
+## Known gaps left by Phase 2–3
+
+- **Editing a scheduled task changes its id.** `triple-c-scheduler` has no `edit`
+  subcommand, and hand-editing its JSON behind its back would desync the crontab, so edit is
+  implemented as add-then-remove. The add runs first, so a rejected edit leaves the original
+  intact. The task gets a new id and its older logs stay under the old one; the editor says
+  so before saving.
+- **`open_terminal_session` takes no command argument.** "Resume session" and
+  "Manage in terminal" therefore open a bash tab and *type* the command after a
+  fixed prompt delay. It works, but it is timing-dependent and will misfire on a
+  slow container start. The fix is a `command: Option<String>` parameter on the
+  Tauri command so the exec launches the process directly.
+- **Uptime is observed, not reported.** `get_container_info` returns a status enum
+  with no start time, so Project Home records "running since" when the app *sees*
+  the transition. A container already running when the app launches shows
+  `● Running` with no elapsed time. Surfacing Docker's `State.StartedAt` would fix it.
+- **`lucide-react` was not adopted** (DESIGN-REVIEW Tier-1 #9) — no package-registry
+  access in the build environment used for this cycle. The existing inline SVGs and
+  text glyphs remain.
+- **The tab strip stayed in the TopBar** rather than moving onto the terminal panel's
+  top edge. DESIGN-REVIEW §A6 asks for the move but its own §B2 layout diagram puts
+  the tabs in the TopBar; the diagram won. Worth revisiting.
+- **`Ctrl+Shift+W`, not `Ctrl+W`, closes a tab.** Plain `Ctrl+W` is readline's
+  `kill-word`, used constantly inside the terminal this app is built around;
+  intercepting it globally would break word-erase in every shell.

TECHNICAL.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Triple-C (Claude-Code-Container) sandboxes Claude Code inside Docker containers so that when running with `--dangerously-skip-permissions`, Claude only has access to files and projects you explicitly provide. The project consists of two components: a **Docker container image** pre-loaded with development tools, and a **cross-platform desktop application** for managing project containers, terminal sessions, and authentication.
+Triple-C (Claude-Code-Container) sandboxes Claude Code inside Docker containers so that even in its most permissive mode — `--dangerously-skip-permissions` — Claude only has access to files and projects you explicitly provide. The project consists of two components: a **Docker container image** pre-loaded with development tools, and a **cross-platform desktop application** for managing project containers, terminal sessions, and authentication.
 
 ---
 
@@ -57,6 +57,16 @@ Tauri uses a Rust backend paired with a web-based frontend rendered by the OS-na
 - **Web links addon** — `@xterm/addon-web-links` makes URLs in terminal output clickable. Combined with `tauri-plugin-opener`, clicked URLs open in the host browser — essential for the `claude login` OAuth flow where Claude prints an authentication URL that must be opened on the host.
 - **Bidirectional data flow** — xterm.js exposes `term.onData()` for user keystrokes and `term.write()` for incoming data. This maps directly to our Tauri event-based streaming architecture.
 
+#### Terminal Layout & StatusBar Controls
+
+Implementation gotchas for the terminal view and its global controls (merged in PR #7, `terminal-layout-statusbar`):
+
+- **xterm padding lives on a wrapper, never the host.** FitAddon measures the same element that `term.open()` mounts into, so any padding on that host element makes the grid overhang and clip its rightmost column / bottom row. Padding must live on a **wrapper `div`**; the xterm host fills it with no padding of its own. Do not reintroduce padding on the host element in `TerminalView.tsx`.
+- **STT mic and "Jump to Current" live in the global `StatusBar`, not per-terminal overlays.** There is a single `useSTT` instance in `App.tsx` bound to the active session. `Ctrl+Shift+M` routes through the Zustand store (`sttToggle`).
+- **Recording is pinned to where it started.** The STT transcript targets `recordingSessionIdRef` (the session recording began in), **not** the live active session — switching tabs mid-recording must not misroute the transcript.
+- **"Jump to Current" state is written only by the active terminal.** The active `TerminalView` surfaces `terminalAtBottom` and `scrollActiveToBottom` through the store; only the active terminal writes them, and they are cleared on its unmount.
+- **Set store function values via object-merge, not the updater form** — `set({ fn: value })`, not `set(state => ...)` — when publishing action callbacks (like `scrollActiveToBottom`) into the Zustand store.
+
 ### bollard (Docker API)
 
 **Chosen over:** Shelling out to the `docker` CLI, dockerode (Node.js), docker-api (Python)
@@ -113,7 +123,8 @@ Tauri uses a Rust backend paired with a web-based frontend rendered by the OS-na
 ┌──────────────────────────────────────────────────────────┐
 │                 Docker Container (per project)            │
 │                                                          │
-│  /workspace ←── bind mount ──► Host project directory    │
+│  /workspace/<name> ←─ bind mount ─► Host project folder  │
+│  /home/claude ←── named volume (home dir)                │
 │  /home/claude/.claude ←── named volume (persists config) │
 │  /tmp/.host-ssh ←── read-only bind mount (SSH keys)      │
 │  /var/run/docker.sock ←── optional (sibling containers)  │
@@ -150,22 +161,178 @@ Terminal resize follows the same pattern: `ResizeObserver` detects container siz
 
 Containers follow a **stop/start** model, not create/destroy:
 
-1. **First start**: A new container is created with bind mounts, environment variables, and labels. The entrypoint remaps UID/GID, configures SSH and git, then runs `sleep infinity` to keep the container alive.
-2. **Terminal open**: `docker exec` launches `claude --dangerously-skip-permissions` with a PTY in the running container.
+1. **First start**: A new container is created with bind mounts, named volumes, environment variables, and labels. The entrypoint remaps UID/GID, configures SSH and git, rebuilds the scheduler crontab, then runs `sleep infinity` to keep the container alive.
+2. **Terminal open**: `docker exec` launches `claude` with a PTY in the running container, with the permission-mode flags from `PermissionMode::cli_args()` (or `bash -l` for a shell session).
 3. **Stop**: `docker stop` halts the container but preserves its filesystem. Any packages Claude installed via `apt`, `pip`, `cargo`, etc. survive.
-4. **Restart**: `docker start` resumes the existing container. All installed tools and configuration persist.
-5. **Reset**: The container is removed and recreated from the image. This is a clean slate — the nuclear option when the container state is corrupted.
+4. **Restart**: `docker start` resumes the existing container — unless `container_needs_recreation()` finds a `triple-c.*` label that no longer matches the project's settings, in which case the container is committed to a snapshot image (`triple-c-snapshot-{projectId}:latest`), removed, and recreated from that snapshot. Installed tools survive; the named volumes are untouched.
+5. **Reset**: `rebuild_project_container` closes live exec sessions, removes the container, removes the snapshot image, calls `remove_project_volumes` to delete **both** named volumes, then starts fresh from the clean base image.
 
-The `.claude` configuration directory uses a **named Docker volume** (`triple-c-claude-config-{projectId}`) so OAuth tokens from `claude login` persist even across container resets.
+Two named volumes exist per project and they are the only ones it owns:
+
+| Volume | Mount point | Purpose |
+|---|---|---|
+| `triple-c-home-{projectId}` | `/home/claude` | Home directory — `~/.claude.json`, `~/.local`, `~/.ssh`, `~/.aws` |
+| `triple-c-claude-config-{projectId}` | `/home/claude/.claude` | Claude Code config: OAuth credential, settings, skills/agents/commands, session transcripts, scheduler state. Nested inside the home volume; Docker gives the more specific mount precedence. |
+
+`remove_project_volumes` names those two volumes explicitly (no prefix sweep) and is called from
+exactly two places: `remove_project` and `rebuild_project_container`. Ordinary container removal
+passes `v: false`, so stop/start and recreation never touch the volumes — **only Reset and project
+removal delete them.** A Reset therefore destroys the `claude login` credential, installed skills,
+session transcripts and scheduled tasks; it does not touch host bind mounts, the project record, or
+host keychain secrets.
+
+### Permission Modes
+
+`PermissionMode` (`models/project.rs`) is a four-state enum replacing the earlier `full_permissions`
+boolean. It reaches Claude Code by two different routes:
+
+| Mode | `cli_args()` — interactive terminals | `as_env_value()` — scheduler |
+|---|---|---|
+| `Plan` | `--permission-mode plan` | `plan` |
+| `Default` | *(no flag)* | `default` |
+| `AcceptEdits` | `--permission-mode acceptEdits` | `acceptEdits` |
+| `Bypass` | `--dangerously-skip-permissions` | `bypass` |
+
+`Project.permission_mode` is `Option<PermissionMode>`, and `effective_permission_mode()` resolves
+`None` from the legacy `full_permissions` flag, so records written before the change keep behaving
+the same way.
+
+**Interactive path.** `build_terminal_cmd()` evaluates `cli_args()` when a session is created, so
+the flags are fixed for the life of that `claude` process. Changing the mode affects terminals
+opened afterwards, not running ones. The same applies to `resume_session_command`, which builds
+`claude <flags> --resume <id>` server-side.
+
+**Scheduler path.** Cron jobs run with a minimal environment, so the mode travels as
+`TRIPLE_C_PERMISSION_MODE` in the container's env; the entrypoint snapshots the allowlisted
+variables into `~/.claude/scheduler/.env`, and `triple-c-task-runner` sources that file and maps the
+value back to flags for its `claude -p` run. Container env can only change at create time, so
+`container_needs_recreation()` compares a `triple-c.permission-mode` label and forces a recreation
+on the next start. A mode change therefore reaches new terminals immediately but the scheduler only
+after a stop/start. `TRIPLE_C_PERMISSION_MODE` is a reserved env key so it cannot be hand-set.
 
 ### Authentication Modes
 
-Each project independently chooses one of two authentication methods:
+Each project independently chooses one backend:
 
-| Mode | How It Works | When to Use |
+| Backend | How It Works | When to Use |
 |------|-------------|-------------|
-| **Anthropic (OAuth)** | User runs `claude login` or `/login` inside the terminal. OAuth URL opens in host browser via URL detection. Token persists in the `.claude` config volume. | Default — personal and team use |
-| **AWS Bedrock** | Per-project AWS credentials (static keys, profile, or bearer token) injected as env vars. `~/.aws` config optionally bind-mounted read-only. | Enterprise environments using Bedrock |
+| **Anthropic** | Either the shared `CLAUDE_CODE_OAUTH_TOKEN` injected from the OS keychain, or a per-container `claude login` whose credential persists in the `.claude` config volume. The OAuth URL opens in the host browser via URL detection. | Default — personal and team use |
+| **AWS Bedrock** | Per-project AWS credentials (static keys, named profile, or bearer token) injected as env vars. `~/.aws` config optionally bind-mounted read-only; SSO sessions are validated before launching Claude for profile auth. | Enterprise environments using Bedrock |
+| **Ollama** | `ANTHROPIC_BASE_URL` points at an Ollama server; `ANTHROPIC_AUTH_TOKEN` is set to the placeholder `ollama`. Ollama implements `POST /v1/messages` natively. | Local models (best-effort) |
+| **llama.cpp** | `ANTHROPIC_BASE_URL` points at a `llama-server` (default port 8080); `ANTHROPIC_AUTH_TOKEN` is set to the placeholder `llama.cpp`, which `llama-server` ignores unless started with `--api-key`. `llama-server` implements `POST /v1/messages` and `/v1/messages/count_tokens` natively. | Local models (best-effort) |
+| **OpenAI Compatible** | `ANTHROPIC_BASE_URL` plus `ANTHROPIC_AUTH_TOKEN` point at a gateway. **Despite the name, the endpoint must implement the Anthropic Messages API** — Claude Code only ever sends `POST /v1/messages?beta=true`, never `/v1/chat/completions`. LiteLLM works; a bare OpenAI-only server does not. | Anthropic-shaped gateways (best-effort) |
+
+#### Model aliases on custom endpoints
+
+`Backend::uses_custom_endpoint()` (Ollama, llama.cpp, OpenAI Compatible) gates the emission of
+`ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU,FABLE}_MODEL`, computed by
+`docker::container::compute_model_aliases`. All four default to the backend's resolved model id;
+each backend carries an optional `haiku_model_id` override, because the Haiku alias is what Claude
+Code uses for background work. Anthropic and Bedrock emit none of them and keep Claude Code's
+defaults; the four names are in `MANAGED_AUTH_KEYS`, so switching away from a custom endpoint
+blanks the values baked into the snapshot image. The resolved alias set is folded into each
+backend's `triple-c.*-fingerprint` label, since `container_needs_recreation` is label-based and
+never diffs env. `ANTHROPIC_SMALL_FAST_MODEL` is deprecated and unused.
+
+### Shared Claude Authentication Token
+
+`commands/auth_token_commands.rs` runs `claude setup-token` on a PTY inside a running container.
+Contrary to the loopback pattern most CLI logins use, `setup-token` redirects to an Anthropic-hosted
+page and then blocks on a stdin paste prompt, so the flow needs a way to feed the pasted code back
+in — hence `submit_claude_token_code`. The flow is single-flight (the token is global, so two
+concurrent logins would race to overwrite each other's keychain entry) and times out after 15
+minutes.
+
+- **Storage** — the OS keychain, under a dedicated service name; the token is never returned to the
+  frontend, never written to a log, and no command accepts or returns it.
+- **The sign-in URL comes from the OSC 8 parameter, not the screen.** The CLI emits the URL as a
+  hyperlink and slices the *visible* text of it to the terminal width — measured against 2.1.226, a
+  346-character URL arrives at 80 columns as five separate hyperlink emissions, each carrying the
+  whole URL in its parameter and 80 characters of it on screen. Scraping the visible text yields a
+  URL that parses, points at `claude.com`, and cannot authorise anything, so the ANSI stripper
+  surfaces the hyperlink target and `claude-token-link` carries it to the UI. The frontend applies
+  the `ANTHROPIC_SIGN_IN_HOSTS` allowlist to it before display and again before `openUrl` — an OSC 8
+  parameter is container output that is never rendered, which makes it the *easier* place to hide a
+  hostile host, not a trusted one. `stty cols 400` (up from 200, which the URL still overflowed)
+  removes wrapping as a variable elsewhere, but it is not the fix: that line fails silently.
+- **A rejected code is recoverable, not a hang.** On a bad paste the CLI prints
+  `OAuth error: Invalid code…` / `Press Enter to retry.` and blocks on stdin rather than exiting.
+  The streamed output is scanned for that, `claude-token-code-rejected` reopens the input with an
+  explanation, and the Enter is sent so the next code has a prompt to land in — bounded by
+  `MAX_CODE_ATTEMPTS`, after which the flow reports a failure. Without this the exec sat until the
+  15-minute timeout with the UI still saying "Finishing sign-in".
+- **Redaction** — streamed output is stripped of ANSI sequences and passed through a stateful
+  redactor that masks anything matching `sk-ant-` with a plausible body, withholding any tail that
+  could still grow into a secret across a chunk boundary. A credential split across a hard line
+  wrap is reassembled by both the parser and the redactor from the same `scan_credential_body`, so
+  the two cannot disagree about where a credential ends — previously a wrapped token was rejected
+  as too short *and* its second line, which carries no `sk-ant-` marker, was printed to the UI in
+  clear. A run is only joined across a break that sits at a plausible terminal margin and is not
+  already long enough to be a whole credential; otherwise a repainting TUI would weld one frame's
+  token onto the next frame's first word.
+- **Injection** — `CLAUDE_CODE_OAUTH_TOKEN` is set only when the backend is Anthropic, the project
+  has not opted out (`use_shared_auth_token`, default `true`), and a non-blank token is stored. When
+  those conditions do not hold, the variable is explicitly set to empty rather than omitted, so a
+  value baked into a snapshot image by `docker commit` is actively cleared.
+- **Rotation** — a random UUID minted on each store is mirrored into the
+  `triple-c.claude-token-version` label. It is deliberately *not* a hash of the token: labels are
+  readable by anything that can run `docker inspect`, and a hash would be an offline verification
+  oracle. A label mismatch forces container recreation on the next start, which is when a container
+  picks up or loses the token.
+
+### Auth Bridge
+
+CLIs that log in through a browser (`claude login`, `aws sso login`, `fly login`) start an ephemeral
+HTTP listener on an unpredictable loopback port and hand the provider a `http://localhost:<port>/…`
+redirect. Run inside a container, that listener is unreachable from the host browser and nothing can
+be pre-published at container-creation time. `auth_bridge/` bridges it at runtime:
+
+- **Discovery** (`proc_net.rs`) — a `docker exec` reads `/proc/net/tcp` and `/proc/net/tcp6` every
+  two seconds. The image ships no `ss`, `netstat` or `lsof`. Only rows in state `0A` (`TCP_LISTEN`)
+  bound to loopback are kept; wildcard binds are ignored on purpose, since publishing those is the
+  port-mappings feature's job.
+- **Family handling** — a `::1`-only listener genuinely cannot be reached over `127.0.0.1`, and Node
+  resolves `localhost` to IPv6 first on Linux, so `claude login` frequently binds `::1` alone. The
+  socat target follows the family actually observed; IPv4-mapped rows in `/proc/net/tcp6` are
+  treated as IPv4.
+- **Host bind** (`tunnel.rs`) — the same port number is bound on the host: `127.0.0.1` is required,
+  `[::1]` is best-effort. **The host side binds loopback only, never a wildcard address** —
+  everything behind it is an unauthenticated in-container service that bound loopback precisely
+  because it expected to be unreachable.
+- **Transport** — each accepted connection is proxied by an attached exec running
+  `socat - TCP:127.0.0.1:<port>`, because container IPs are not routable from the host under Docker
+  Desktop. It goes through the same `create_attached_exec()` helper as terminal sessions, with
+  `tty: false` so socat's stderr is demultiplexed away from the proxied byte stream.
+- **Policy** — ports appearing in the project's port mappings are skipped, and a host bind failure
+  is recorded as a conflict and retried later rather than fought over.
+- **Lifecycle** — opt-in per project (`auth_bridge_enabled`, default `false`). It is purely
+  host-side, so it deliberately has no container-recreation label. The poller stops itself when the
+  project is gone, the flag is cleared, or the container is no longer running, and `stop()` awaits
+  it so host ports are provably released.
+
+### Container Introspection
+
+`list_container_capabilities` (`commands/inspect_commands.rs`) executes a read-only shell script in
+a running container and returns counts and item lists for skills, agents, commands, hooks, plugins
+and MCP servers, across user scope (`/home/claude/.claude`) and project scope
+(`/workspace/*/.claude`, `/workspace/*/.mcp.json`). Everything is computed in-container with
+`find`/`awk`/`jq`; only the JSON summary crosses the wire, and a stopped container yields zeros
+rather than an error.
+
+The script writes nothing. Claude Code owns this configuration and has its own tooling for it
+(`/agents`, `/hooks`, `/plugins`, `/mcp`); Triple-C surfaces counts and opens a terminal rather than
+rebuilding those editors as forms. `list_claude_sessions` and the scheduler commands
+(`list_scheduled_tasks`, `get_scheduled_task_log`, `set_scheduled_task_enabled`,
+`run_scheduled_task_now`, `remove_scheduled_task`, `clear_scheduler_notifications`) live in the same
+module; the mutating ones shell out to `triple-c-scheduler` rather than editing its state files.
+
+### Main-Area Tab Model
+
+The frontend keeps a single ordered `tabOrder` array in the Zustand store holding two tab kinds,
+`home:<projectId>` and `term:<sessionId>`, rendered by `components/layout/MainTabs.tsx`.
+`activeSessionId` is *derived* from `activeTabKey`, so exactly one thing is current and a Project
+Home tab and a terminal cannot both claim focus. Project configuration is a main-area view
+(`components/projects/home/`), not a modal; the sidebar row is select-only.
 
 ### UID/GID Remapping
 
@@ -195,10 +362,12 @@ This avoids the common Docker problem where bind-mount permissions can't be chan
 | Data | Storage | Location |
 |------|---------|----------|
 | Project configurations | JSON file (atomic writes) | `~/.local/share/triple-c/projects.json` |
-| API keys | OS keychain | macOS Keychain / Windows Credential Manager / Linux Secret Service |
+| API keys and per-project secrets | OS keychain | macOS Keychain / Windows Credential Manager / Linux Secret Service |
+| Shared Claude token + rotation id | OS keychain | Separate service entries; never on disk, never in a label |
 | App settings | Tauri plugin-store | App data directory |
-| Claude config/tokens | Named Docker volume | `triple-c-claude-config-{projectId}` |
-| Container filesystem | Docker container layer | Preserved across stop/start, cleared on reset |
+| Claude config, sessions, scheduler state | Named Docker volume | `triple-c-claude-config-{projectId}` |
+| Container home directory | Named Docker volume | `triple-c-home-{projectId}` |
+| Container filesystem | Docker container layer, preserved into `triple-c-snapshot-{projectId}:latest` on recreation | Survives stop/start and recreation; destroyed by Reset |
 
 The projects store uses **atomic writes** (write to `.json.tmp`, then `rename()`) to prevent data corruption if the app crashes mid-write. Corrupted files are backed up to `.json.bak` before being replaced.
 
@@ -220,98 +389,159 @@ The `TerminalView` component works around this with a **URL accumulator**:
 triple-c/
 ├── README.md                      # Architecture overview
 ├── TECHNICAL.md                   # This document
-├── HOW-TO-USE.md                  # User guide
+├── HOW-TO-USE.md                  # User guide (also served by the in-app Help dialog)
 ├── BUILDING.md                    # Build instructions
 ├── CLAUDE.md                      # Claude Code instructions
+├── DESIGN-REVIEW.md               # UI/UX review notes
+├── ROADMAP.md                     # Planned work
 │
-├── container/
+├── container/                     # Sandbox image
 │   ├── Dockerfile                 # Ubuntu 24.04 + all dev tools + Claude Code
-│   ├── entrypoint.sh              # UID/GID remap, SSH setup, git config, MCP injection
+│   ├── entrypoint.sh              # UID/GID remap, SSH setup, git config, settings injection,
+│   │                              # scheduler env snapshot + crontab rebuild
 │   ├── osc52-clipboard            # Clipboard shim (xclip/xsel/pbcopy via OSC 52)
 │   ├── audio-shim                 # Audio capture shim (rec/arecord via FIFO)
 │   ├── triple-c-scheduler         # Bash-based cron task system
-│   └── triple-c-task-runner       # Task execution runner for scheduler
+│   ├── triple-c-task-runner       # Cron entry point; permission mode → flags → `claude -p`
+│   ├── triple-c-sso-refresh       # AWS SSO session refresh helper
+│   └── mission-control/           # Bundled Flight Control methodology (skills, docs, templates)
+│
+├── stt-container/                 # Speech-to-text image
+│   ├── Dockerfile                 # Faster Whisper (Python 3.11 + FastAPI)
+│   └── server.py                  # POST /transcribe endpoint
 │
 ├── .gitea/
 │   └── workflows/
-│       ├── build-app.yml          # Build Tauri app (Linux/macOS/Windows)
-│       ├── build.yml              # Build container image (multi-arch)
-│       ├── sync-release.yml       # Mirror releases to GitHub
-│       └── backfill-releases.yml  # Bulk copy releases to GitHub
+│       ├── build-app.yml            # Build Tauri app (Linux/macOS/Windows); mirrors releases to GitHub inline
+│       ├── build-app-preview.yml    # Preview builds
+│       ├── build.yml                # Build container image (multi-arch)
+│       ├── build-stt.yml            # Build the STT image
+│       ├── backfill-releases.yml    # Bulk copy releases to GitHub
+│       ├── cleanup-releases.yml     # Prune old releases
 │
 └── app/                           # Tauri v2 desktop application
     ├── package.json               # React, xterm.js, zustand, tailwindcss
     ├── vite.config.ts             # Vite bundler config
+    ├── vitest.config.ts           # Vitest (jsdom) config
     ├── index.html                 # HTML entry point
     │
     ├── src/                       # React frontend
     │   ├── main.tsx               # React DOM root
-    │   ├── App.tsx                # Top-level layout
-    │   ├── index.css              # CSS variables, dark theme, scrollbars
+    │   ├── App.tsx                # Top-level layout + welcome screen
+    │   ├── index.css              # CSS variables, dark theme, focus ring, scrollbars
     │   ├── store/
-    │   │   └── appState.ts        # Zustand store (projects, sessions, MCP, UI)
+    │   │   └── appState.ts        # Zustand store (projects, sessions, tab strip, toasts)
     │   ├── hooks/
+    │   │   ├── useClaudeAuth.ts   # Shared token status + acquisition
+    │   │   ├── useContainerProgress.ts # container-progress events → inline progress
     │   │   ├── useDocker.ts       # Docker status, image build/pull
-    │   │   ├── useFileManager.ts  # File manager operations
-    │   │   ├── useMcpServers.ts   # MCP server CRUD
+    │   │   ├── useFileManager.ts  # File browser operations + host transfers
+    │   │   ├── useInstallHelper.ts # Guided Docker installation
+    │   │   ├── useKeyboardShortcuts.ts # Ctrl+T / Ctrl+Shift+W / Ctrl+Tab / Ctrl+1..9
+    │   │   ├── useProjectActions.ts # Start/stop/reset/backup, open terminals
     │   │   ├── useProjects.ts     # Project CRUD operations
+    │   │   ├── useSaveState.ts    # Saved / Saving / Failed indicator state
     │   │   ├── useSettings.ts     # App settings
+    │   │   ├── useSTT.ts          # Speech-to-text recording and container control
     │   │   ├── useTerminal.ts     # Terminal I/O, resize, session events
     │   │   ├── useUpdates.ts      # App update checking
     │   │   └── useVoice.ts        # Voice mode audio capture
     │   ├── lib/
     │   │   ├── types.ts           # TypeScript interfaces matching Rust models
     │   │   ├── tauri-commands.ts  # Typed invoke() wrappers
+    │   │   ├── urlDetector.ts     # Long-URL reassembly for OAuth flows
+    │   │   ├── wav.ts             # WAV encoding for STT
     │   │   └── constants.ts       # App-wide constants
     │   └── components/
-    │       ├── layout/            # Sidebar, TopBar, StatusBar
-    │       ├── mcp/               # McpPanel, McpServerCard
-    │       ├── projects/          # ProjectCard, ProjectList, AddProjectDialog,
-    │       │                      # FileManagerModal, ContainerProgressModal, modals
+    │       ├── DockerInstallDialog.tsx # First-run Docker setup
+    │       ├── layout/            # TopBar, MainTabs (the unified tab strip),
+    │       │                      # Sidebar, StatusBar, HelpDialog
+    │       ├── projects/
+    │       │   ├── home/                 # Project Home — the main-area project view
+    │       │   │   ├── ProjectHome.tsx   # Header, actions, overflow menu, tab strip
+    │       │   │   ├── OverviewTab.tsx   # Permission mode, summary, recent activity
+    │       │   │   ├── SessionsTab.tsx   # Past Claude sessions + Resume
+    │       │   │   ├── AutomationTab.tsx # Scheduler tasks + notifications
+    │       │   │   ├── ConfigTab.tsx     # Config section host
+    │       │   │   ├── FilesTab.tsx      # In-container file browser, upload / save to host
+    │       │   │   ├── CapabilityTiles.tsx # Read-only capability counts
+    │       │   │   ├── format.ts         # Age / size / uptime formatting
+    │       │   │   └── config/           # WorkspaceSection, ModelSection,
+    │       │   │                         # AccessSection, RuntimeSection
+    │       │   ├── ProjectRow.tsx        # Select-only sidebar row
+    │       │   ├── ProjectList.tsx       # Sidebar project list
+    │       │   ├── AddProjectDialog.tsx  # New-project dialog
+    │       │   ├── PermissionModeControl.tsx # Plan/Default/Accept Edits/Bypass
+    │       │   ├── ConfirmRemoveModal.tsx    # Project removal confirmation
+    │       │   └── *Editor.tsx / *Modal.tsx  # EnvVars, PortMappings,
+    │       │                                 # ClaudeInstructions, ClaudeCodeSettings —
+    │       │                                 # editors reused by Project Home
     │       ├── settings/          # SettingsPanel, DockerSettings, AwsSettings,
-    │       │                      # WebTerminalSettings, UpdateDialog
-    │       └── terminal/          # TerminalView (xterm.js), TerminalTabs, UrlToast
+    │       │                      # OllamaSettings, LlamaCppSettings,
+    │       │                      # OpenAiCompatibleSettings,
+    │       │                      # SharedAuthSettings, ClaudeAuthModal,
+    │       │                      # WebTerminalSettings, SttSettings,
+    │       │                      # MicrophoneSettings, UpdateDialog, ImageUpdateDialog
+    │       ├── terminal/          # TerminalView (xterm.js), TerminalContextMenu,
+    │       │                      # SttButton, UrlToast, trimSelection
+    │       └── ui/                # Shared primitives: Modal, Button, Toggle, Field,
+    │                              # SegmentedControl, StatusIndicator, SaveIndicator,
+    │                              # OverflowMenu, ToastHost, Tooltip, AccordionSection
     │
     └── src-tauri/                 # Rust backend
         ├── Cargo.toml             # Rust dependencies
         ├── tauri.conf.json        # Tauri app configuration
+        ├── build.rs               # Tauri build script
         ├── capabilities/
-        │   └── default.json       # Tauri v2 permission grants
+        │   └── default.json       # Tauri v2 plugin permission grants
         └── src/
             ├── lib.rs             # App builder, plugin + command registration
             ├── main.rs            # Entry point
             ├── logging.rs         # Log configuration
             ├── commands/          # Tauri command handlers
-            │   ├── docker_commands.rs   # Docker status, image ops
-            │   ├── file_commands.rs     # File manager (list/download/upload)
-            │   ├── mcp_commands.rs      # MCP server CRUD
-            │   ├── project_commands.rs  # Start/stop/rebuild containers
-            │   ├── settings_commands.rs # Settings CRUD
-            │   ├── terminal_commands.rs # Terminal I/O, resize
-            │   ├── update_commands.rs   # App update checking
+            │   ├── auth_bridge_commands.rs  # Enable/status for the loopback bridge
+            │   ├── auth_token_commands.rs   # claude setup-token flow, redaction, keychain
+            │   ├── aws_commands.rs          # AWS profile/region discovery
+            │   ├── docker_commands.rs       # Docker status, image ops
+            │   ├── file_commands.rs         # File browser + host transfers (Rust-opened dialogs)
+            │   ├── help_commands.rs         # Serves HOW-TO-USE.md to the Help dialog
+            │   ├── inspect_commands.rs      # Sessions, capabilities, scheduler tasks
+            │   ├── install_helper_commands.rs # Guided Docker installation
+            │   ├── project_commands.rs      # Start/stop/rebuild/backup containers
+            │   ├── settings_commands.rs     # Settings CRUD
+            │   ├── stt_commands.rs          # STT start/stop/transcribe
+            │   ├── terminal_commands.rs     # Terminal I/O, resize
+            │   ├── update_commands.rs       # App update checking
             │   └── web_terminal_commands.rs # Web terminal start/stop/status
-            ├── web_terminal/       # Remote terminal access
+            ├── auth_bridge/       # Host-side loopback callback bridge
+            │   ├── mod.rs         # Per-project poller, status, lifecycle
+            │   ├── proc_net.rs    # /proc/net/tcp{,6} parsing, loopback filtering
+            │   └── tunnel.rs      # Host loopback bind + socat tunnel over the Docker API
+            ├── web_terminal/      # Remote terminal access
             │   ├── mod.rs         # Module root
             │   ├── server.rs      # Axum HTTP+WS server lifecycle
             │   ├── ws_handler.rs  # WebSocket connection handler
             │   └── terminal.html  # Embedded xterm.js web UI
+            ├── install_helper/    # Docker installation assistance
+            │   ├── mod.rs         # Install orchestration
+            │   └── platform.rs    # Per-OS install strategies
             ├── docker/            # Docker API layer
             │   ├── client.rs      # bollard singleton connection
-            │   ├── container.rs   # Create, start, stop, remove, fingerprinting
-            │   ├── exec.rs        # PTY exec sessions with bidirectional streaming
+            │   ├── container.rs   # Create/start/stop/remove, labels, recreation checks,
+            │   │                  # remove_project_volumes, snapshot commit
+            │   ├── exec.rs        # create_attached_exec() — the single attached-exec path
             │   ├── image.rs       # Build from Dockerfile, pull from registry
-            │   └── network.rs     # Per-project bridge networks for MCP
+            │   ├── stt.rs         # Speech-to-text container lifecycle
+            │   └── legacy_cleanup.rs # Migration shim for the removed MCP feature
             ├── models/            # Data structures
-            │   ├── project.rs     # Project, Backend, BedrockConfig
-            │   ├── mcp_server.rs  # MCP server configuration
-            │   ├── app_settings.rs # Global settings (image source, AWS, etc.)
+            │   ├── project.rs     # Project, Backend, PermissionMode, BedrockConfig, …
+            │   ├── app_settings.rs # Global settings (image source, AWS, STT, web terminal)
             │   ├── container_config.rs # Image name resolution
             │   └── update_info.rs # Update metadata
             └── storage/           # Persistence
                 ├── projects_store.rs  # JSON file with atomic writes
-                ├── mcp_store.rs       # MCP server persistence
                 ├── settings_store.rs  # App settings (Tauri plugin-store)
-                └── secure.rs          # OS keychain via keyring
+                └── secure.rs          # OS keychain via keyring (secrets, shared token)
 ```
 
 ---
@@ -335,6 +565,11 @@ triple-c/
 | `tar` | 0.4 | In-memory tar archives for Docker build context |
 | `dirs` | 6.x | Cross-platform app data directory paths |
 | `serde` / `serde_json` | 1.x | Serialization for IPC and persistence |
+| `log` / `fern` | 0.4 / 0.7 | Date-based file logging |
+| `include_dir` | 0.7 | Embeds the container build context in the binary |
+| `reqwest` | 0.12 | HTTPS (rustls) for update checks, help content, STT uploads |
+| `iana-time-zone` | 0.1 | Host timezone detection for container `TZ` |
+| `sha2` | 0.10 | Settings fingerprints |
 | `axum` | 0.8 | HTTP+WebSocket server for web terminal |
 | `tower-http` | 0.6 | CORS middleware for web terminal |
 | `base64` | 0.22 | Terminal data encoding over WebSocket |
@@ -357,6 +592,8 @@ triple-c/
 | `zustand` | 5.x | Lightweight state management |
 | `tailwindcss` | 4.x | Utility-first CSS framework |
 | `vite` | 6.x | Frontend build tool and dev server |
+| `vitest` | 4.x | Test runner (jsdom environment) |
+| `@testing-library/react` | 16.x | Component tests |
 
 ### Container Image
 

VERSION

@@ -1 +1 @@
-0.3
+0.4

app/index.html

@@ -2,7 +2,7 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Triple-C</title>
   </head>

app/package-lock.json

@@ -1,17 +1,16 @@
 {
   "name": "triple-c",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "triple-c",
-      "version": "0.2.0",
+      "version": "0.4.0",
       "dependencies": {
         "@tauri-apps/api": "^2",
         "@tauri-apps/plugin-dialog": "^2.7.0",
         "@tauri-apps/plugin-opener": "^2.5.3",
-        "@tauri-apps/plugin-store": "^2",
         "@xterm/addon-fit": "^0.10",
         "@xterm/addon-web-links": "^0.12.0",
         "@xterm/addon-webgl": "^0.18",
@@ -1757,9 +1756,9 @@
       }
     },
     "node_modules/@tauri-apps/api": {
-      "version": "2.10.1",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/api/-/api-2.10.1.tgz",
-      "integrity": "sha512-hKL/jWf293UDSUN09rR69hrToyIXBb8CjGaWC7gfinvnQrBVvnLr08FeFi38gxtugAVyVcTa5/FD/Xnkb1siBw==",
+      "version": "2.11.0",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/api/-/api-2.11.0.tgz",
+      "integrity": "sha512-7CinYODhky9lmO23xHnUFv0Xt43fbtWMyxZcLcRBlFkcgXKuEirBvHpmtJ89YMhyeGcq20Wuc47Fa4XjyniywA==",
       "license": "Apache-2.0 OR MIT",
       "funding": {
         "type": "opencollective",
@@ -1767,9 +1766,9 @@
       }
     },
     "node_modules/@tauri-apps/cli": {
-      "version": "2.10.0",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli/-/cli-2.10.0.tgz",
-      "integrity": "sha512-ZwT0T+7bw4+DPCSWzmviwq5XbXlM0cNoleDKOYPFYqcZqeKY31KlpoMW/MOON/tOFBPgi31a2v3w9gliqwL2+Q==",
+      "version": "2.11.0",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli/-/cli-2.11.0.tgz",
+      "integrity": "sha512-W5Wbuqsb2pHFPTj4TaRNKTj5rwXhDShPiLSY9T18y4ouSR/NNCptAEFxFsBtyNRgL6Vs1a/q9LzfqqYzEwC+Jw==",
       "dev": true,
       "license": "Apache-2.0 OR MIT",
       "bin": {
@@ -1783,23 +1782,23 @@
         "url": "https://opencollective.com/tauri"
       },
       "optionalDependencies": {
-        "@tauri-apps/cli-darwin-arm64": "2.10.0",
-        "@tauri-apps/cli-darwin-x64": "2.10.0",
-        "@tauri-apps/cli-linux-arm-gnueabihf": "2.10.0",
-        "@tauri-apps/cli-linux-arm64-gnu": "2.10.0",
-        "@tauri-apps/cli-linux-arm64-musl": "2.10.0",
-        "@tauri-apps/cli-linux-riscv64-gnu": "2.10.0",
-        "@tauri-apps/cli-linux-x64-gnu": "2.10.0",
-        "@tauri-apps/cli-linux-x64-musl": "2.10.0",
-        "@tauri-apps/cli-win32-arm64-msvc": "2.10.0",
-        "@tauri-apps/cli-win32-ia32-msvc": "2.10.0",
-        "@tauri-apps/cli-win32-x64-msvc": "2.10.0"
+        "@tauri-apps/cli-darwin-arm64": "2.11.0",
+        "@tauri-apps/cli-darwin-x64": "2.11.0",
+        "@tauri-apps/cli-linux-arm-gnueabihf": "2.11.0",
+        "@tauri-apps/cli-linux-arm64-gnu": "2.11.0",
+        "@tauri-apps/cli-linux-arm64-musl": "2.11.0",
+        "@tauri-apps/cli-linux-riscv64-gnu": "2.11.0",
+        "@tauri-apps/cli-linux-x64-gnu": "2.11.0",
+        "@tauri-apps/cli-linux-x64-musl": "2.11.0",
+        "@tauri-apps/cli-win32-arm64-msvc": "2.11.0",
+        "@tauri-apps/cli-win32-ia32-msvc": "2.11.0",
+        "@tauri-apps/cli-win32-x64-msvc": "2.11.0"
       }
     },
     "node_modules/@tauri-apps/cli-darwin-arm64": {
-      "version": "2.10.0",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-darwin-arm64/-/cli-darwin-arm64-2.10.0.tgz",
-      "integrity": "sha512-avqHD4HRjrMamE/7R/kzJPcAJnZs0IIS+1nkDP5b+TNBn3py7N2aIo9LIpy+VQq0AkN8G5dDpZtOOBkmWt/zjA==",
+      "version": "2.11.0",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-darwin-arm64/-/cli-darwin-arm64-2.11.0.tgz",
+      "integrity": "sha512-UfMeDNlgIP252rm/KSTuu8yHatPua5TjtUEUf+jyIzVwBNcIl7Ywkdpfj+e5jVVg3EfCTp+4gwuL1dNpgF8clg==",
       "cpu": [
         "arm64"
       ],
@@ -1814,9 +1813,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-darwin-x64": {
-      "version": "2.10.0",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-darwin-x64/-/cli-darwin-x64-2.10.0.tgz",
-      "integrity": "sha512-keDmlvJRStzVFjZTd0xYkBONLtgBC9eMTpmXnBXzsHuawV2q9PvDo2x6D5mhuoMVrJ9QWjgaPKBBCFks4dK71Q==",
+      "version": "2.11.0",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-darwin-x64/-/cli-darwin-x64-2.11.0.tgz",
+      "integrity": "sha512-lY1+aPlgyMN7vgjtCdQ3+WODfZkebAcxnrCrO0HjqDpKSXieDkrJbimqeaoM4RwhTSrCLRHfVYiYrfE5E131tg==",
       "cpu": [
         "x64"
       ],
@@ -1831,9 +1830,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-linux-arm-gnueabihf": {
-      "version": "2.10.0",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm-gnueabihf/-/cli-linux-arm-gnueabihf-2.10.0.tgz",
-      "integrity": "sha512-e5u0VfLZsMAC9iHaOEANumgl6lfnJx0Dtjkd8IJpysZ8jp0tJ6wrIkto2OzQgzcYyRCKgX72aKE0PFgZputA8g==",
+      "version": "2.11.0",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm-gnueabihf/-/cli-linux-arm-gnueabihf-2.11.0.tgz",
+      "integrity": "sha512-5uCP0AusgN3NrKC8EpkuJwjek1k8pEffBdugJSpXPey/QGbPEb8vZ542n/giJ2mZPjMSllDkdhG2QIDpBY4PpQ==",
       "cpu": [
         "arm"
       ],
@@ -1848,9 +1847,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-linux-arm64-gnu": {
-      "version": "2.10.0",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm64-gnu/-/cli-linux-arm64-gnu-2.10.0.tgz",
-      "integrity": "sha512-YrYYk2dfmBs5m+OIMCrb+JH/oo+4FtlpcrTCgiFYc7vcs6m3QDd1TTyWu0u01ewsCtK2kOdluhr/zKku+KP7HA==",
+      "version": "2.11.0",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm64-gnu/-/cli-linux-arm64-gnu-2.11.0.tgz",
+      "integrity": "sha512-loDPqtRHMSbIcrH2VBd4GgHoQlF7jJnrZj7MxA2lj1cixS/jEgMAPFqj83U6Wvjete4HfYplbE/gCpSFifA9jw==",
       "cpu": [
         "arm64"
       ],
@@ -1865,9 +1864,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-linux-arm64-musl": {
-      "version": "2.10.0",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.10.0.tgz",
-      "integrity": "sha512-GUoPdVJmrJRIXFfW3Rkt+eGK9ygOdyISACZfC/bCSfOnGt8kNdQIQr5WRH9QUaTVFIwxMlQyV3m+yXYP+xhSVA==",
+      "version": "2.11.0",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.11.0.tgz",
+      "integrity": "sha512-DtSE8ZBlB9H+L+eHkfZ3myt00EVEyAB3e41juEHoE2qT88fgVlJvyrwa9SZYc/xTwCS9TnmK+R84tpg+ZsAg7Q==",
       "cpu": [
         "arm64"
       ],
@@ -1882,9 +1881,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-linux-riscv64-gnu": {
-      "version": "2.10.0",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-riscv64-gnu/-/cli-linux-riscv64-gnu-2.10.0.tgz",
-      "integrity": "sha512-JO7s3TlSxshwsoKNCDkyvsx5gw2QAs/Y2GbR5UE2d5kkU138ATKoPOtxn8G1fFT1aDW4LH0rYAAfBpGkDyJJnw==",
+      "version": "2.11.0",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-riscv64-gnu/-/cli-linux-riscv64-gnu-2.11.0.tgz",
+      "integrity": "sha512-5QdgS4LD+kntClI1aj2JmwjW38LosNXxwCe8viIHEwqYIWuMPdNEIau6/cLogI38Yzx9DnfCPRfEWLyI+5li8Q==",
       "cpu": [
         "riscv64"
       ],
@@ -1899,9 +1898,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-linux-x64-gnu": {
-      "version": "2.10.0",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-x64-gnu/-/cli-linux-x64-gnu-2.10.0.tgz",
-      "integrity": "sha512-Uvh4SUUp4A6DVRSMWjelww0GnZI3PlVy7VS+DRF5napKuIehVjGl9XD0uKoCoxwAQBLctvipyEK+pDXpJeoHng==",
+      "version": "2.11.0",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-x64-gnu/-/cli-linux-x64-gnu-2.11.0.tgz",
+      "integrity": "sha512-5UynPXo3Zq9khjVdAbD+YogeLltdVUeOah2ioSIM3tu6H7wY9vMy6rgGJhv9r5R8ZXmk9GttMippdqYJWrnLnA==",
       "cpu": [
         "x64"
       ],
@@ -1916,9 +1915,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-linux-x64-musl": {
-      "version": "2.10.0",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-x64-musl/-/cli-linux-x64-musl-2.10.0.tgz",
-      "integrity": "sha512-AP0KRK6bJuTpQ8kMNWvhIpKUkQJfcPFeba7QshOQZjJ8wOS6emwTN4K5g/d3AbCMo0RRdnZWwu67MlmtJyxC1Q==",
+      "version": "2.11.0",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-x64-musl/-/cli-linux-x64-musl-2.11.0.tgz",
+      "integrity": "sha512-CNz7fHbApz1Zyhhq73jtGn9JqgNEV/lIWnTnUo6h6ujw+mHsTmkLszvJSM8W6JBaDjNpTTFr/RSNoVL5FMwcTg==",
       "cpu": [
         "x64"
       ],
@@ -1933,9 +1932,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-win32-arm64-msvc": {
-      "version": "2.10.0",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-arm64-msvc/-/cli-win32-arm64-msvc-2.10.0.tgz",
-      "integrity": "sha512-97DXVU3dJystrq7W41IX+82JEorLNY+3+ECYxvXWqkq7DBN6FsA08x/EFGE8N/b0LTOui9X2dvpGGoeZKKV08g==",
+      "version": "2.11.0",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-arm64-msvc/-/cli-win32-arm64-msvc-2.11.0.tgz",
+      "integrity": "sha512-K+br+VXZ+Xx0n/9FdWohpW5Ugq+2FQUpJScqcPl1hTxXfh3fgjYgt4qA2NgrjlJo+zZPNrmUMl+NLvm0ufEqBQ==",
       "cpu": [
         "arm64"
       ],
@@ -1950,9 +1949,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-win32-ia32-msvc": {
-      "version": "2.10.0",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-ia32-msvc/-/cli-win32-ia32-msvc-2.10.0.tgz",
-      "integrity": "sha512-EHyQ1iwrWy1CwMalEm9z2a6L5isQ121pe7FcA2xe4VWMJp+GHSDDGvbTv/OPdkt2Lyr7DAZBpZHM6nvlHXEc4A==",
+      "version": "2.11.0",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-ia32-msvc/-/cli-win32-ia32-msvc-2.11.0.tgz",
+      "integrity": "sha512-OFV+s3MLZnd75zl0ZAFU5riMpGK4waUEA8ZDuijDsnkU0btz/gHhqh5jVlOn8thyvgdtT3Xyoxqo099MMifH3g==",
       "cpu": [
         "ia32"
       ],
@@ -1967,9 +1966,9 @@
       }
     },
     "node_modules/@tauri-apps/cli-win32-x64-msvc": {
-      "version": "2.10.0",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-x64-msvc/-/cli-win32-x64-msvc-2.10.0.tgz",
-      "integrity": "sha512-NTpyQxkpzGmU6ceWBTY2xRIEaS0ZLbVx1HE1zTA3TY/pV3+cPoPPOs+7YScr4IMzXMtOw7tLw5LEXo5oIG3qaQ==",
+      "version": "2.11.0",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-x64-msvc/-/cli-win32-x64-msvc-2.11.0.tgz",
+      "integrity": "sha512-AeDTWBd2cOZ6TX133BWsoo+LutG9o0JRcgjMsIfLE13ZugpgCMv/2dJbUiBGeRvbPOGin5A3aYmsArPVV6ZSHQ==",
       "cpu": [
         "x64"
       ],
@@ -2001,15 +2000,6 @@
         "@tauri-apps/api": "^2.8.0"
       }
     },
-    "node_modules/@tauri-apps/plugin-store": {
-      "version": "2.4.2",
-      "resolved": "https://registry.npmjs.org/@tauri-apps/plugin-store/-/plugin-store-2.4.2.tgz",
-      "integrity": "sha512-0ClHS50Oq9HEvLPhNzTNFxbWVOqoAp3dRvtewQBeqfIQ0z5m3JRnOISIn2ZVPCrQC0MyGyhTS9DWhHjpigQE7A==",
-      "license": "MIT OR Apache-2.0",
-      "dependencies": {
-        "@tauri-apps/api": "^2.8.0"
-      }
-    },
     "node_modules/@testing-library/dom": {
       "version": "10.4.1",
       "resolved": "https://registry.npmjs.org/@testing-library/dom/-/dom-10.4.1.tgz",

app/package.json

@@ -1,7 +1,7 @@
 {
   "name": "triple-c",
   "private": true,
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -9,13 +9,13 @@
     "preview": "vite preview",
     "tauri": "tauri",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "hooks": "git -C .. config core.hooksPath .githooks && echo \"pre-commit secret scan enabled\""
   },
   "dependencies": {
     "@tauri-apps/api": "^2",
     "@tauri-apps/plugin-dialog": "^2.7.0",
     "@tauri-apps/plugin-opener": "^2.5.3",
-    "@tauri-apps/plugin-store": "^2",
     "@xterm/addon-fit": "^0.10",
     "@xterm/addon-web-links": "^0.12.0",
     "@xterm/addon-webgl": "^0.18",

app/public/favicon.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" width="128" height="128" role="img" aria-label="Triple-C">
+  <title>Triple-C application icon, small-size variant</title>
+  <!-- Source for every raster ≤ 32 px: the small mark, drawn at 82% so the strokes
+       survive being resampled down to 16 px. See build-icons.py. -->
+  <rect width="128" height="128" rx="28.16" fill="#0D1117"/>
+  <g transform="translate(2.9236 2.9236) scale(0.95418)">
+    <g fill="none" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M112 50 L112 38 A22 22 0 0 0 90 16 L38 16 A22 22 0 0 0 16 38 L16 90 A22 22 0 0 0 38 112 L90 112 A22 22 0 0 0 112 90 L112 78"
+            stroke="#58A6FF" stroke-width="14"/>
+      <path d="M46 50 L62 66 L46 82" stroke="#F0821E" stroke-width="13"/>
+    </g>
+  </g>
+</svg>

app/src-tauri/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "triple-c"
-version = "0.3.0"
+version = "0.4.0"
 edition = "2021"
 
 [lib]
@@ -13,7 +13,6 @@ path = "src/main.rs"
 
 [dependencies]
 tauri = { version = "2", features = ["image-png", "image-ico"] }
-tauri-plugin-store = "2"
 tauri-plugin-dialog = "2"
 tauri-plugin-opener = "2"
 serde = { version = "1", features = ["derive"] }
@@ -37,6 +36,14 @@ tower-http = { version = "0.6", features = ["cors"] }
 base64 = "0.22"
 rand = "0.9"
 local-ip-address = "0.6"
+argon2 = "0.5"
+aes-gcm = "0.10"
+zeroize = "1"
+
+[dev-dependencies]
+# `test-util` (not part of tokio's `full`) lets the auto-start retry tests run
+# their backoff schedule under a paused clock instead of in real seconds.
+tokio = { version = "1", features = ["full", "test-util"] }
 
 [build-dependencies]
 tauri-build = { version = "2", features = [] }

app/src-tauri/gen/schemas/desktop-schema.json

@@ -351,10 +351,10 @@
           "markdownDescription": "Default core plugins set.\n#### This default permission set includes:\n\n- `core:path:default`\n- `core:event:default`\n- `core:window:default`\n- `core:webview:default`\n- `core:app:default`\n- `core:image:default`\n- `core:resources:default`\n- `core:menu:default`\n- `core:tray:default`"
         },
         {
-          "description": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-version`\n- `allow-name`\n- `allow-tauri-version`\n- `allow-identifier`\n- `allow-bundle-type`\n- `allow-register-listener`\n- `allow-remove-listener`",
+          "description": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-version`\n- `allow-name`\n- `allow-tauri-version`\n- `allow-identifier`\n- `allow-bundle-type`\n- `allow-register-listener`\n- `allow-remove-listener`\n- `allow-supports-multiple-windows`",
           "type": "string",
           "const": "core:app:default",
-          "markdownDescription": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-version`\n- `allow-name`\n- `allow-tauri-version`\n- `allow-identifier`\n- `allow-bundle-type`\n- `allow-register-listener`\n- `allow-remove-listener`"
+          "markdownDescription": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-version`\n- `allow-name`\n- `allow-tauri-version`\n- `allow-identifier`\n- `allow-bundle-type`\n- `allow-register-listener`\n- `allow-remove-listener`\n- `allow-supports-multiple-windows`"
         },
         {
           "description": "Enables the app_hide command without any pre-configured scope.",
@@ -428,6 +428,12 @@
           "const": "core:app:allow-set-dock-visibility",
           "markdownDescription": "Enables the set_dock_visibility command without any pre-configured scope."
         },
+        {
+          "description": "Enables the supports_multiple_windows command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:app:allow-supports-multiple-windows",
+          "markdownDescription": "Enables the supports_multiple_windows command without any pre-configured scope."
+        },
         {
           "description": "Enables the tauri_version command without any pre-configured scope.",
           "type": "string",
@@ -512,6 +518,12 @@
           "const": "core:app:deny-set-dock-visibility",
           "markdownDescription": "Denies the set_dock_visibility command without any pre-configured scope."
         },
+        {
+          "description": "Denies the supports_multiple_windows command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:app:deny-supports-multiple-windows",
+          "markdownDescription": "Denies the supports_multiple_windows command without any pre-configured scope."
+        },
         {
           "description": "Denies the tauri_version command without any pre-configured scope.",
           "type": "string",
@@ -1035,10 +1047,10 @@
           "markdownDescription": "Denies the close command without any pre-configured scope."
         },
         {
-          "description": "Default permissions for the plugin, which enables all commands.\n#### This default permission set includes:\n\n- `allow-new`\n- `allow-get-by-id`\n- `allow-remove-by-id`\n- `allow-set-icon`\n- `allow-set-menu`\n- `allow-set-tooltip`\n- `allow-set-title`\n- `allow-set-visible`\n- `allow-set-temp-dir-path`\n- `allow-set-icon-as-template`\n- `allow-set-show-menu-on-left-click`",
+          "description": "Default permissions for the plugin, which enables all commands.\n#### This default permission set includes:\n\n- `allow-new`\n- `allow-get-by-id`\n- `allow-remove-by-id`\n- `allow-set-icon`\n- `allow-set-menu`\n- `allow-set-tooltip`\n- `allow-set-title`\n- `allow-set-visible`\n- `allow-set-temp-dir-path`\n- `allow-set-icon-as-template`\n- `allow-set-icon-with-as-template`\n- `allow-set-show-menu-on-left-click`",
           "type": "string",
           "const": "core:tray:default",
-          "markdownDescription": "Default permissions for the plugin, which enables all commands.\n#### This default permission set includes:\n\n- `allow-new`\n- `allow-get-by-id`\n- `allow-remove-by-id`\n- `allow-set-icon`\n- `allow-set-menu`\n- `allow-set-tooltip`\n- `allow-set-title`\n- `allow-set-visible`\n- `allow-set-temp-dir-path`\n- `allow-set-icon-as-template`\n- `allow-set-show-menu-on-left-click`"
+          "markdownDescription": "Default permissions for the plugin, which enables all commands.\n#### This default permission set includes:\n\n- `allow-new`\n- `allow-get-by-id`\n- `allow-remove-by-id`\n- `allow-set-icon`\n- `allow-set-menu`\n- `allow-set-tooltip`\n- `allow-set-title`\n- `allow-set-visible`\n- `allow-set-temp-dir-path`\n- `allow-set-icon-as-template`\n- `allow-set-icon-with-as-template`\n- `allow-set-show-menu-on-left-click`"
         },
         {
           "description": "Enables the get_by_id command without any pre-configured scope.",
@@ -1070,6 +1082,12 @@
           "const": "core:tray:allow-set-icon-as-template",
           "markdownDescription": "Enables the set_icon_as_template command without any pre-configured scope."
         },
+        {
+          "description": "Enables the set_icon_with_as_template command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:tray:allow-set-icon-with-as-template",
+          "markdownDescription": "Enables the set_icon_with_as_template command without any pre-configured scope."
+        },
         {
           "description": "Enables the set_menu command without any pre-configured scope.",
           "type": "string",
@@ -1136,6 +1154,12 @@
           "const": "core:tray:deny-set-icon-as-template",
           "markdownDescription": "Denies the set_icon_as_template command without any pre-configured scope."
         },
+        {
+          "description": "Denies the set_icon_with_as_template command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:tray:deny-set-icon-with-as-template",
+          "markdownDescription": "Denies the set_icon_with_as_template command without any pre-configured scope."
+        },
         {
           "description": "Denies the set_menu command without any pre-configured scope.",
           "type": "string",
@@ -1395,10 +1419,16 @@
           "markdownDescription": "Denies the webview_size command without any pre-configured scope."
         },
         {
-          "description": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-get-all-windows`\n- `allow-scale-factor`\n- `allow-inner-position`\n- `allow-outer-position`\n- `allow-inner-size`\n- `allow-outer-size`\n- `allow-is-fullscreen`\n- `allow-is-minimized`\n- `allow-is-maximized`\n- `allow-is-focused`\n- `allow-is-decorated`\n- `allow-is-resizable`\n- `allow-is-maximizable`\n- `allow-is-minimizable`\n- `allow-is-closable`\n- `allow-is-visible`\n- `allow-is-enabled`\n- `allow-title`\n- `allow-current-monitor`\n- `allow-primary-monitor`\n- `allow-monitor-from-point`\n- `allow-available-monitors`\n- `allow-cursor-position`\n- `allow-theme`\n- `allow-is-always-on-top`\n- `allow-internal-toggle-maximize`",
+          "description": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-get-all-windows`\n- `allow-scale-factor`\n- `allow-inner-position`\n- `allow-outer-position`\n- `allow-inner-size`\n- `allow-outer-size`\n- `allow-is-fullscreen`\n- `allow-is-minimized`\n- `allow-is-maximized`\n- `allow-is-focused`\n- `allow-is-decorated`\n- `allow-is-resizable`\n- `allow-is-maximizable`\n- `allow-is-minimizable`\n- `allow-is-closable`\n- `allow-is-visible`\n- `allow-is-enabled`\n- `allow-title`\n- `allow-current-monitor`\n- `allow-primary-monitor`\n- `allow-monitor-from-point`\n- `allow-available-monitors`\n- `allow-cursor-position`\n- `allow-theme`\n- `allow-is-always-on-top`\n- `allow-activity-name`\n- `allow-scene-identifier`\n- `allow-internal-toggle-maximize`",
           "type": "string",
           "const": "core:window:default",
-          "markdownDescription": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-get-all-windows`\n- `allow-scale-factor`\n- `allow-inner-position`\n- `allow-outer-position`\n- `allow-inner-size`\n- `allow-outer-size`\n- `allow-is-fullscreen`\n- `allow-is-minimized`\n- `allow-is-maximized`\n- `allow-is-focused`\n- `allow-is-decorated`\n- `allow-is-resizable`\n- `allow-is-maximizable`\n- `allow-is-minimizable`\n- `allow-is-closable`\n- `allow-is-visible`\n- `allow-is-enabled`\n- `allow-title`\n- `allow-current-monitor`\n- `allow-primary-monitor`\n- `allow-monitor-from-point`\n- `allow-available-monitors`\n- `allow-cursor-position`\n- `allow-theme`\n- `allow-is-always-on-top`\n- `allow-internal-toggle-maximize`"
+          "markdownDescription": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-get-all-windows`\n- `allow-scale-factor`\n- `allow-inner-position`\n- `allow-outer-position`\n- `allow-inner-size`\n- `allow-outer-size`\n- `allow-is-fullscreen`\n- `allow-is-minimized`\n- `allow-is-maximized`\n- `allow-is-focused`\n- `allow-is-decorated`\n- `allow-is-resizable`\n- `allow-is-maximizable`\n- `allow-is-minimizable`\n- `allow-is-closable`\n- `allow-is-visible`\n- `allow-is-enabled`\n- `allow-title`\n- `allow-current-monitor`\n- `allow-primary-monitor`\n- `allow-monitor-from-point`\n- `allow-available-monitors`\n- `allow-cursor-position`\n- `allow-theme`\n- `allow-is-always-on-top`\n- `allow-activity-name`\n- `allow-scene-identifier`\n- `allow-internal-toggle-maximize`"
+        },
+        {
+          "description": "Enables the activity_name command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:window:allow-activity-name",
+          "markdownDescription": "Enables the activity_name command without any pre-configured scope."
         },
         {
           "description": "Enables the available_monitors command without any pre-configured scope.",
@@ -1592,6 +1622,12 @@
           "const": "core:window:allow-scale-factor",
           "markdownDescription": "Enables the scale_factor command without any pre-configured scope."
         },
+        {
+          "description": "Enables the scene_identifier command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:window:allow-scene-identifier",
+          "markdownDescription": "Enables the scene_identifier command without any pre-configured scope."
+        },
         {
           "description": "Enables the set_always_on_bottom command without any pre-configured scope.",
           "type": "string",
@@ -1856,6 +1892,12 @@
           "const": "core:window:allow-unminimize",
           "markdownDescription": "Enables the unminimize command without any pre-configured scope."
         },
+        {
+          "description": "Denies the activity_name command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:window:deny-activity-name",
+          "markdownDescription": "Denies the activity_name command without any pre-configured scope."
+        },
         {
           "description": "Denies the available_monitors command without any pre-configured scope.",
           "type": "string",
@@ -2048,6 +2090,12 @@
           "const": "core:window:deny-scale-factor",
           "markdownDescription": "Denies the scale_factor command without any pre-configured scope."
         },
+        {
+          "description": "Denies the scene_identifier command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:window:deny-scene-identifier",
+          "markdownDescription": "Denies the scene_identifier command without any pre-configured scope."
+        },
         {
           "description": "Denies the set_always_on_bottom command without any pre-configured scope.",
           "type": "string",
@@ -2313,22 +2361,22 @@
           "markdownDescription": "Denies the unminimize command without any pre-configured scope."
         },
         {
-          "description": "This permission set configures the types of dialogs\navailable from the dialog plugin.\n\n#### Granted Permissions\n\nAll dialog types are enabled.\n\n\n\n#### This default permission set includes:\n\n- `allow-ask`\n- `allow-confirm`\n- `allow-message`\n- `allow-save`\n- `allow-open`",
+          "description": "This permission set configures the types of dialogs\navailable from the dialog plugin.\n\n#### Granted Permissions\n\nAll dialog types are enabled.\n\n\n\n#### This default permission set includes:\n\n- `allow-message`\n- `allow-save`\n- `allow-open`",
           "type": "string",
           "const": "dialog:default",
-          "markdownDescription": "This permission set configures the types of dialogs\navailable from the dialog plugin.\n\n#### Granted Permissions\n\nAll dialog types are enabled.\n\n\n\n#### This default permission set includes:\n\n- `allow-ask`\n- `allow-confirm`\n- `allow-message`\n- `allow-save`\n- `allow-open`"
+          "markdownDescription": "This permission set configures the types of dialogs\navailable from the dialog plugin.\n\n#### Granted Permissions\n\nAll dialog types are enabled.\n\n\n\n#### This default permission set includes:\n\n- `allow-message`\n- `allow-save`\n- `allow-open`"
         },
         {
-          "description": "Enables the ask command without any pre-configured scope.",
+          "description": "Enables the ask command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `allow-message` and will be removed in v3)",
           "type": "string",
           "const": "dialog:allow-ask",
-          "markdownDescription": "Enables the ask command without any pre-configured scope."
+          "markdownDescription": "Enables the ask command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `allow-message` and will be removed in v3)"
         },
         {
-          "description": "Enables the confirm command without any pre-configured scope.",
+          "description": "Enables the confirm command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `allow-message` and will be removed in v3)",
           "type": "string",
           "const": "dialog:allow-confirm",
-          "markdownDescription": "Enables the confirm command without any pre-configured scope."
+          "markdownDescription": "Enables the confirm command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `allow-message` and will be removed in v3)"
         },
         {
           "description": "Enables the message command without any pre-configured scope.",
@@ -2349,16 +2397,16 @@
           "markdownDescription": "Enables the save command without any pre-configured scope."
         },
         {
-          "description": "Denies the ask command without any pre-configured scope.",
+          "description": "Denies the ask command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `deny-message` and will be removed in v3)",
           "type": "string",
           "const": "dialog:deny-ask",
-          "markdownDescription": "Denies the ask command without any pre-configured scope."
+          "markdownDescription": "Denies the ask command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `deny-message` and will be removed in v3)"
         },
         {
-          "description": "Denies the confirm command without any pre-configured scope.",
+          "description": "Denies the confirm command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `deny-message` and will be removed in v3)",
           "type": "string",
           "const": "dialog:deny-confirm",
-          "markdownDescription": "Denies the confirm command without any pre-configured scope."
+          "markdownDescription": "Denies the confirm command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `deny-message` and will be removed in v3)"
         },
         {
           "description": "Denies the message command without any pre-configured scope.",
@@ -2425,180 +2473,6 @@
           "type": "string",
           "const": "opener:deny-reveal-item-in-dir",
           "markdownDescription": "Denies the reveal_item_in_dir command without any pre-configured scope."
-        },
-        {
-          "description": "This permission set configures what kind of\noperations are available from the store plugin.\n\n#### Granted Permissions\n\nAll operations are enabled by default.\n\n\n#### This default permission set includes:\n\n- `allow-load`\n- `allow-get-store`\n- `allow-set`\n- `allow-get`\n- `allow-has`\n- `allow-delete`\n- `allow-clear`\n- `allow-reset`\n- `allow-keys`\n- `allow-values`\n- `allow-entries`\n- `allow-length`\n- `allow-reload`\n- `allow-save`",
-          "type": "string",
-          "const": "store:default",
-          "markdownDescription": "This permission set configures what kind of\noperations are available from the store plugin.\n\n#### Granted Permissions\n\nAll operations are enabled by default.\n\n\n#### This default permission set includes:\n\n- `allow-load`\n- `allow-get-store`\n- `allow-set`\n- `allow-get`\n- `allow-has`\n- `allow-delete`\n- `allow-clear`\n- `allow-reset`\n- `allow-keys`\n- `allow-values`\n- `allow-entries`\n- `allow-length`\n- `allow-reload`\n- `allow-save`"
-        },
-        {
-          "description": "Enables the clear command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-clear",
-          "markdownDescription": "Enables the clear command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the delete command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-delete",
-          "markdownDescription": "Enables the delete command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the entries command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-entries",
-          "markdownDescription": "Enables the entries command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the get command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-get",
-          "markdownDescription": "Enables the get command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the get_store command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-get-store",
-          "markdownDescription": "Enables the get_store command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the has command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-has",
-          "markdownDescription": "Enables the has command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the keys command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-keys",
-          "markdownDescription": "Enables the keys command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the length command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-length",
-          "markdownDescription": "Enables the length command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the load command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-load",
-          "markdownDescription": "Enables the load command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the reload command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-reload",
-          "markdownDescription": "Enables the reload command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the reset command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-reset",
-          "markdownDescription": "Enables the reset command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the save command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-save",
-          "markdownDescription": "Enables the save command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the set command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-set",
-          "markdownDescription": "Enables the set command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the values command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-values",
-          "markdownDescription": "Enables the values command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the clear command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-clear",
-          "markdownDescription": "Denies the clear command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the delete command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-delete",
-          "markdownDescription": "Denies the delete command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the entries command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-entries",
-          "markdownDescription": "Denies the entries command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the get command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-get",
-          "markdownDescription": "Denies the get command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the get_store command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-get-store",
-          "markdownDescription": "Denies the get_store command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the has command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-has",
-          "markdownDescription": "Denies the has command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the keys command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-keys",
-          "markdownDescription": "Denies the keys command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the length command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-length",
-          "markdownDescription": "Denies the length command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the load command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-load",
-          "markdownDescription": "Denies the load command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the reload command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-reload",
-          "markdownDescription": "Denies the reload command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the reset command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-reset",
-          "markdownDescription": "Denies the reset command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the save command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-save",
-          "markdownDescription": "Denies the save command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the set command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-set",
-          "markdownDescription": "Denies the set command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the values command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-values",
-          "markdownDescription": "Denies the values command without any pre-configured scope."
         }
       ]
     },

app/src-tauri/gen/schemas/linux-schema.json

@@ -351,10 +351,10 @@
           "markdownDescription": "Default core plugins set.\n#### This default permission set includes:\n\n- `core:path:default`\n- `core:event:default`\n- `core:window:default`\n- `core:webview:default`\n- `core:app:default`\n- `core:image:default`\n- `core:resources:default`\n- `core:menu:default`\n- `core:tray:default`"
         },
         {
-          "description": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-version`\n- `allow-name`\n- `allow-tauri-version`\n- `allow-identifier`\n- `allow-bundle-type`\n- `allow-register-listener`\n- `allow-remove-listener`",
+          "description": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-version`\n- `allow-name`\n- `allow-tauri-version`\n- `allow-identifier`\n- `allow-bundle-type`\n- `allow-register-listener`\n- `allow-remove-listener`\n- `allow-supports-multiple-windows`",
           "type": "string",
           "const": "core:app:default",
-          "markdownDescription": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-version`\n- `allow-name`\n- `allow-tauri-version`\n- `allow-identifier`\n- `allow-bundle-type`\n- `allow-register-listener`\n- `allow-remove-listener`"
+          "markdownDescription": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-version`\n- `allow-name`\n- `allow-tauri-version`\n- `allow-identifier`\n- `allow-bundle-type`\n- `allow-register-listener`\n- `allow-remove-listener`\n- `allow-supports-multiple-windows`"
         },
         {
           "description": "Enables the app_hide command without any pre-configured scope.",
@@ -428,6 +428,12 @@
           "const": "core:app:allow-set-dock-visibility",
           "markdownDescription": "Enables the set_dock_visibility command without any pre-configured scope."
         },
+        {
+          "description": "Enables the supports_multiple_windows command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:app:allow-supports-multiple-windows",
+          "markdownDescription": "Enables the supports_multiple_windows command without any pre-configured scope."
+        },
         {
           "description": "Enables the tauri_version command without any pre-configured scope.",
           "type": "string",
@@ -512,6 +518,12 @@
           "const": "core:app:deny-set-dock-visibility",
           "markdownDescription": "Denies the set_dock_visibility command without any pre-configured scope."
         },
+        {
+          "description": "Denies the supports_multiple_windows command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:app:deny-supports-multiple-windows",
+          "markdownDescription": "Denies the supports_multiple_windows command without any pre-configured scope."
+        },
         {
           "description": "Denies the tauri_version command without any pre-configured scope.",
           "type": "string",
@@ -1035,10 +1047,10 @@
           "markdownDescription": "Denies the close command without any pre-configured scope."
         },
         {
-          "description": "Default permissions for the plugin, which enables all commands.\n#### This default permission set includes:\n\n- `allow-new`\n- `allow-get-by-id`\n- `allow-remove-by-id`\n- `allow-set-icon`\n- `allow-set-menu`\n- `allow-set-tooltip`\n- `allow-set-title`\n- `allow-set-visible`\n- `allow-set-temp-dir-path`\n- `allow-set-icon-as-template`\n- `allow-set-show-menu-on-left-click`",
+          "description": "Default permissions for the plugin, which enables all commands.\n#### This default permission set includes:\n\n- `allow-new`\n- `allow-get-by-id`\n- `allow-remove-by-id`\n- `allow-set-icon`\n- `allow-set-menu`\n- `allow-set-tooltip`\n- `allow-set-title`\n- `allow-set-visible`\n- `allow-set-temp-dir-path`\n- `allow-set-icon-as-template`\n- `allow-set-icon-with-as-template`\n- `allow-set-show-menu-on-left-click`",
           "type": "string",
           "const": "core:tray:default",
-          "markdownDescription": "Default permissions for the plugin, which enables all commands.\n#### This default permission set includes:\n\n- `allow-new`\n- `allow-get-by-id`\n- `allow-remove-by-id`\n- `allow-set-icon`\n- `allow-set-menu`\n- `allow-set-tooltip`\n- `allow-set-title`\n- `allow-set-visible`\n- `allow-set-temp-dir-path`\n- `allow-set-icon-as-template`\n- `allow-set-show-menu-on-left-click`"
+          "markdownDescription": "Default permissions for the plugin, which enables all commands.\n#### This default permission set includes:\n\n- `allow-new`\n- `allow-get-by-id`\n- `allow-remove-by-id`\n- `allow-set-icon`\n- `allow-set-menu`\n- `allow-set-tooltip`\n- `allow-set-title`\n- `allow-set-visible`\n- `allow-set-temp-dir-path`\n- `allow-set-icon-as-template`\n- `allow-set-icon-with-as-template`\n- `allow-set-show-menu-on-left-click`"
         },
         {
           "description": "Enables the get_by_id command without any pre-configured scope.",
@@ -1070,6 +1082,12 @@
           "const": "core:tray:allow-set-icon-as-template",
           "markdownDescription": "Enables the set_icon_as_template command without any pre-configured scope."
         },
+        {
+          "description": "Enables the set_icon_with_as_template command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:tray:allow-set-icon-with-as-template",
+          "markdownDescription": "Enables the set_icon_with_as_template command without any pre-configured scope."
+        },
         {
           "description": "Enables the set_menu command without any pre-configured scope.",
           "type": "string",
@@ -1136,6 +1154,12 @@
           "const": "core:tray:deny-set-icon-as-template",
           "markdownDescription": "Denies the set_icon_as_template command without any pre-configured scope."
         },
+        {
+          "description": "Denies the set_icon_with_as_template command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:tray:deny-set-icon-with-as-template",
+          "markdownDescription": "Denies the set_icon_with_as_template command without any pre-configured scope."
+        },
         {
           "description": "Denies the set_menu command without any pre-configured scope.",
           "type": "string",
@@ -1395,10 +1419,16 @@
           "markdownDescription": "Denies the webview_size command without any pre-configured scope."
         },
         {
-          "description": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-get-all-windows`\n- `allow-scale-factor`\n- `allow-inner-position`\n- `allow-outer-position`\n- `allow-inner-size`\n- `allow-outer-size`\n- `allow-is-fullscreen`\n- `allow-is-minimized`\n- `allow-is-maximized`\n- `allow-is-focused`\n- `allow-is-decorated`\n- `allow-is-resizable`\n- `allow-is-maximizable`\n- `allow-is-minimizable`\n- `allow-is-closable`\n- `allow-is-visible`\n- `allow-is-enabled`\n- `allow-title`\n- `allow-current-monitor`\n- `allow-primary-monitor`\n- `allow-monitor-from-point`\n- `allow-available-monitors`\n- `allow-cursor-position`\n- `allow-theme`\n- `allow-is-always-on-top`\n- `allow-internal-toggle-maximize`",
+          "description": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-get-all-windows`\n- `allow-scale-factor`\n- `allow-inner-position`\n- `allow-outer-position`\n- `allow-inner-size`\n- `allow-outer-size`\n- `allow-is-fullscreen`\n- `allow-is-minimized`\n- `allow-is-maximized`\n- `allow-is-focused`\n- `allow-is-decorated`\n- `allow-is-resizable`\n- `allow-is-maximizable`\n- `allow-is-minimizable`\n- `allow-is-closable`\n- `allow-is-visible`\n- `allow-is-enabled`\n- `allow-title`\n- `allow-current-monitor`\n- `allow-primary-monitor`\n- `allow-monitor-from-point`\n- `allow-available-monitors`\n- `allow-cursor-position`\n- `allow-theme`\n- `allow-is-always-on-top`\n- `allow-activity-name`\n- `allow-scene-identifier`\n- `allow-internal-toggle-maximize`",
           "type": "string",
           "const": "core:window:default",
-          "markdownDescription": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-get-all-windows`\n- `allow-scale-factor`\n- `allow-inner-position`\n- `allow-outer-position`\n- `allow-inner-size`\n- `allow-outer-size`\n- `allow-is-fullscreen`\n- `allow-is-minimized`\n- `allow-is-maximized`\n- `allow-is-focused`\n- `allow-is-decorated`\n- `allow-is-resizable`\n- `allow-is-maximizable`\n- `allow-is-minimizable`\n- `allow-is-closable`\n- `allow-is-visible`\n- `allow-is-enabled`\n- `allow-title`\n- `allow-current-monitor`\n- `allow-primary-monitor`\n- `allow-monitor-from-point`\n- `allow-available-monitors`\n- `allow-cursor-position`\n- `allow-theme`\n- `allow-is-always-on-top`\n- `allow-internal-toggle-maximize`"
+          "markdownDescription": "Default permissions for the plugin.\n#### This default permission set includes:\n\n- `allow-get-all-windows`\n- `allow-scale-factor`\n- `allow-inner-position`\n- `allow-outer-position`\n- `allow-inner-size`\n- `allow-outer-size`\n- `allow-is-fullscreen`\n- `allow-is-minimized`\n- `allow-is-maximized`\n- `allow-is-focused`\n- `allow-is-decorated`\n- `allow-is-resizable`\n- `allow-is-maximizable`\n- `allow-is-minimizable`\n- `allow-is-closable`\n- `allow-is-visible`\n- `allow-is-enabled`\n- `allow-title`\n- `allow-current-monitor`\n- `allow-primary-monitor`\n- `allow-monitor-from-point`\n- `allow-available-monitors`\n- `allow-cursor-position`\n- `allow-theme`\n- `allow-is-always-on-top`\n- `allow-activity-name`\n- `allow-scene-identifier`\n- `allow-internal-toggle-maximize`"
+        },
+        {
+          "description": "Enables the activity_name command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:window:allow-activity-name",
+          "markdownDescription": "Enables the activity_name command without any pre-configured scope."
         },
         {
           "description": "Enables the available_monitors command without any pre-configured scope.",
@@ -1592,6 +1622,12 @@
           "const": "core:window:allow-scale-factor",
           "markdownDescription": "Enables the scale_factor command without any pre-configured scope."
         },
+        {
+          "description": "Enables the scene_identifier command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:window:allow-scene-identifier",
+          "markdownDescription": "Enables the scene_identifier command without any pre-configured scope."
+        },
         {
           "description": "Enables the set_always_on_bottom command without any pre-configured scope.",
           "type": "string",
@@ -1856,6 +1892,12 @@
           "const": "core:window:allow-unminimize",
           "markdownDescription": "Enables the unminimize command without any pre-configured scope."
         },
+        {
+          "description": "Denies the activity_name command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:window:deny-activity-name",
+          "markdownDescription": "Denies the activity_name command without any pre-configured scope."
+        },
         {
           "description": "Denies the available_monitors command without any pre-configured scope.",
           "type": "string",
@@ -2048,6 +2090,12 @@
           "const": "core:window:deny-scale-factor",
           "markdownDescription": "Denies the scale_factor command without any pre-configured scope."
         },
+        {
+          "description": "Denies the scene_identifier command without any pre-configured scope.",
+          "type": "string",
+          "const": "core:window:deny-scene-identifier",
+          "markdownDescription": "Denies the scene_identifier command without any pre-configured scope."
+        },
         {
           "description": "Denies the set_always_on_bottom command without any pre-configured scope.",
           "type": "string",
@@ -2313,22 +2361,22 @@
           "markdownDescription": "Denies the unminimize command without any pre-configured scope."
         },
         {
-          "description": "This permission set configures the types of dialogs\navailable from the dialog plugin.\n\n#### Granted Permissions\n\nAll dialog types are enabled.\n\n\n\n#### This default permission set includes:\n\n- `allow-ask`\n- `allow-confirm`\n- `allow-message`\n- `allow-save`\n- `allow-open`",
+          "description": "This permission set configures the types of dialogs\navailable from the dialog plugin.\n\n#### Granted Permissions\n\nAll dialog types are enabled.\n\n\n\n#### This default permission set includes:\n\n- `allow-message`\n- `allow-save`\n- `allow-open`",
           "type": "string",
           "const": "dialog:default",
-          "markdownDescription": "This permission set configures the types of dialogs\navailable from the dialog plugin.\n\n#### Granted Permissions\n\nAll dialog types are enabled.\n\n\n\n#### This default permission set includes:\n\n- `allow-ask`\n- `allow-confirm`\n- `allow-message`\n- `allow-save`\n- `allow-open`"
+          "markdownDescription": "This permission set configures the types of dialogs\navailable from the dialog plugin.\n\n#### Granted Permissions\n\nAll dialog types are enabled.\n\n\n\n#### This default permission set includes:\n\n- `allow-message`\n- `allow-save`\n- `allow-open`"
         },
         {
-          "description": "Enables the ask command without any pre-configured scope.",
+          "description": "Enables the ask command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `allow-message` and will be removed in v3)",
           "type": "string",
           "const": "dialog:allow-ask",
-          "markdownDescription": "Enables the ask command without any pre-configured scope."
+          "markdownDescription": "Enables the ask command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `allow-message` and will be removed in v3)"
         },
         {
-          "description": "Enables the confirm command without any pre-configured scope.",
+          "description": "Enables the confirm command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `allow-message` and will be removed in v3)",
           "type": "string",
           "const": "dialog:allow-confirm",
-          "markdownDescription": "Enables the confirm command without any pre-configured scope."
+          "markdownDescription": "Enables the confirm command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `allow-message` and will be removed in v3)"
         },
         {
           "description": "Enables the message command without any pre-configured scope.",
@@ -2349,16 +2397,16 @@
           "markdownDescription": "Enables the save command without any pre-configured scope."
         },
         {
-          "description": "Denies the ask command without any pre-configured scope.",
+          "description": "Denies the ask command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `deny-message` and will be removed in v3)",
           "type": "string",
           "const": "dialog:deny-ask",
-          "markdownDescription": "Denies the ask command without any pre-configured scope."
+          "markdownDescription": "Denies the ask command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `deny-message` and will be removed in v3)"
         },
         {
-          "description": "Denies the confirm command without any pre-configured scope.",
+          "description": "Denies the confirm command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `deny-message` and will be removed in v3)",
           "type": "string",
           "const": "dialog:deny-confirm",
-          "markdownDescription": "Denies the confirm command without any pre-configured scope."
+          "markdownDescription": "Denies the confirm command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `deny-message` and will be removed in v3)"
         },
         {
           "description": "Denies the message command without any pre-configured scope.",
@@ -2425,180 +2473,6 @@
           "type": "string",
           "const": "opener:deny-reveal-item-in-dir",
           "markdownDescription": "Denies the reveal_item_in_dir command without any pre-configured scope."
-        },
-        {
-          "description": "This permission set configures what kind of\noperations are available from the store plugin.\n\n#### Granted Permissions\n\nAll operations are enabled by default.\n\n\n#### This default permission set includes:\n\n- `allow-load`\n- `allow-get-store`\n- `allow-set`\n- `allow-get`\n- `allow-has`\n- `allow-delete`\n- `allow-clear`\n- `allow-reset`\n- `allow-keys`\n- `allow-values`\n- `allow-entries`\n- `allow-length`\n- `allow-reload`\n- `allow-save`",
-          "type": "string",
-          "const": "store:default",
-          "markdownDescription": "This permission set configures what kind of\noperations are available from the store plugin.\n\n#### Granted Permissions\n\nAll operations are enabled by default.\n\n\n#### This default permission set includes:\n\n- `allow-load`\n- `allow-get-store`\n- `allow-set`\n- `allow-get`\n- `allow-has`\n- `allow-delete`\n- `allow-clear`\n- `allow-reset`\n- `allow-keys`\n- `allow-values`\n- `allow-entries`\n- `allow-length`\n- `allow-reload`\n- `allow-save`"
-        },
-        {
-          "description": "Enables the clear command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-clear",
-          "markdownDescription": "Enables the clear command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the delete command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-delete",
-          "markdownDescription": "Enables the delete command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the entries command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-entries",
-          "markdownDescription": "Enables the entries command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the get command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-get",
-          "markdownDescription": "Enables the get command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the get_store command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-get-store",
-          "markdownDescription": "Enables the get_store command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the has command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-has",
-          "markdownDescription": "Enables the has command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the keys command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-keys",
-          "markdownDescription": "Enables the keys command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the length command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-length",
-          "markdownDescription": "Enables the length command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the load command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-load",
-          "markdownDescription": "Enables the load command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the reload command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-reload",
-          "markdownDescription": "Enables the reload command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the reset command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-reset",
-          "markdownDescription": "Enables the reset command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the save command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-save",
-          "markdownDescription": "Enables the save command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the set command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-set",
-          "markdownDescription": "Enables the set command without any pre-configured scope."
-        },
-        {
-          "description": "Enables the values command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:allow-values",
-          "markdownDescription": "Enables the values command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the clear command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-clear",
-          "markdownDescription": "Denies the clear command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the delete command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-delete",
-          "markdownDescription": "Denies the delete command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the entries command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-entries",
-          "markdownDescription": "Denies the entries command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the get command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-get",
-          "markdownDescription": "Denies the get command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the get_store command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-get-store",
-          "markdownDescription": "Denies the get_store command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the has command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-has",
-          "markdownDescription": "Denies the has command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the keys command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-keys",
-          "markdownDescription": "Denies the keys command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the length command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-length",
-          "markdownDescription": "Denies the length command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the load command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-load",
-          "markdownDescription": "Denies the load command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the reload command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-reload",
-          "markdownDescription": "Denies the reload command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the reset command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-reset",
-          "markdownDescription": "Denies the reset command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the save command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-save",
-          "markdownDescription": "Denies the save command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the set command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-set",
-          "markdownDescription": "Denies the set command without any pre-configured scope."
-        },
-        {
-          "description": "Denies the values command without any pre-configured scope.",
-          "type": "string",
-          "const": "store:deny-values",
-          "markdownDescription": "Denies the values command without any pre-configured scope."
         }
       ]
     },

app/src-tauri/src/auth_bridge/mod.rs

@@ -0,0 +1,868 @@
+//! Auth Bridge — lets browser-based OAuth logins run by CLIs *inside* a
+//! container complete against the browser on the *host*.
+//!
+//! ## The problem
+//!
+//! `claude login`, Concourse's `fly login`, `aws sso login` and friends all use
+//! the same pattern: start a throwaway HTTP listener on a random loopback port,
+//! then open a browser at a provider URL whose redirect points back to
+//! `http://localhost:<that port>/callback`. Run inside a container, the listener
+//! is on the *container's* loopback, the browser is on the *host's*, and the
+//! callback goes nowhere — the login just hangs. The ports are ephemeral and not
+//! configurable, so nothing can be pre-published at container creation time.
+//!
+//! ## The mechanism
+//!
+//! While the bridge is enabled for a running project, poll the container every
+//! [`POLL_INTERVAL`] for loopback TCP listeners (see [`proc_net`]). For each one
+//! that appears, bind the *same* port on the host's loopback and proxy each
+//! accepted connection into the container over `docker exec … socat` (see
+//! [`tunnel`]). When the in-container listener goes away, drop the host
+//! listener. The host and container therefore agree on the port number, which is
+//! the whole trick: the redirect URL the provider was given resolves correctly
+//! on both sides.
+//!
+//! ## Lifecycle and teardown
+//!
+//! One poller task per project. It is the only thing that owns
+//! [`PortForward`]s, and it always tears them down on its way out, so every way
+//! the bridge can end funnels through the same code:
+//!
+//! | Trigger | Path |
+//! |---|---|
+//! | Bridge disabled | `set_auth_bridge_enabled(false)` → [`AuthBridgeManager::stop`] |
+//! | Container stopped via UI | `stop_project_container` → [`AuthBridgeManager::stop`] |
+//! | Container stopped/died another way | poller's own `is_container_running` check → loop exits |
+//! | Project deleted | `remove_project` → [`AuthBridgeManager::stop`]; also the poller's `store.get()` check |
+//! | Container rebuilt | `rebuild_project_container` → stop, then start re-arms it |
+//! | App exit | window `CloseRequested` → [`AuthBridgeManager::stop_all`] |
+//!
+//! [`AuthBridgeManager::stop`] awaits the poller, so host ports are provably
+//! released before it returns. As a backstop for any path that skips all of the
+//! above (a panicking poller, an aborted task), `PortForward`'s [`Drop`] aborts
+//! the accept loop, which drops the socket.
+
+pub mod proc_net;
+pub mod tunnel;
+
+use std::collections::{BTreeMap, HashMap, HashSet};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+use std::time::Duration;
+
+use serde::Serialize;
+use tauri::{AppHandle, Emitter};
+use tokio::sync::{watch, Mutex};
+use tokio::task::JoinHandle;
+
+use crate::docker::container::is_container_running;
+use crate::docker::exec::{exec_oneshot_limited, PROC_NET_OUTPUT_LIMIT};
+use crate::storage::projects_store::ProjectsStore;
+
+use proc_net::PortFamily;
+use tunnel::PortForward;
+
+/// How often the container is polled for new/vanished loopback listeners.
+/// Short enough that a login redirect isn't left waiting, cheap enough to run
+/// continuously (one `cat` of two procfs files per tick).
+const POLL_INTERVAL: Duration = Duration::from_secs(2);
+
+/// Emitted whenever the bridged-port set (or the conflict set) changes.
+/// Payload: `{ project_id, status: AuthBridgeStatus }`.
+const AUTH_BRIDGE_EVENT: &str = "auth-bridge-changed";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// IPC response models
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// A port currently bound on the host loopback and forwarded into the container.
+#[derive(Debug, Clone, Serialize)]
+pub struct BridgedPort {
+    pub port: u16,
+    pub family: PortFamily,
+    /// RFC 3339 timestamp of when the host listener was bound.
+    pub bridged_at: String,
+    /// Set when only the IPv4 half of the host listener could be bound. The
+    /// port still works, but not for a client that insists on `::1` — see
+    /// [`tunnel::PortForward::ipv6_warning`].
+    pub ipv6_warning: Option<String>,
+}
+
+/// A loopback listener that was discovered but could not be bridged.
+#[derive(Debug, Clone, Serialize)]
+pub struct PortConflict {
+    pub port: u16,
+    pub reason: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct AuthBridgeStatus {
+    pub enabled: bool,
+    pub active_ports: Vec<BridgedPort>,
+    pub conflicts: Vec<PortConflict>,
+}
+
+impl AuthBridgeStatus {
+    fn disabled() -> Self {
+        Self {
+            enabled: false,
+            active_ports: Vec::new(),
+            conflicts: Vec::new(),
+        }
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Manager
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Everything the poller owns for one project. Live ports and conflicts sit
+/// behind an `Arc<Mutex<…>>` so `get_auth_bridge_status` can read them without
+/// disturbing the poller.
+#[derive(Default)]
+struct BridgeState {
+    forwards: BTreeMap<u16, PortForward>,
+    conflicts: BTreeMap<u16, String>,
+}
+
+impl BridgeState {
+    fn snapshot(&self, enabled: bool) -> AuthBridgeStatus {
+        AuthBridgeStatus {
+            enabled,
+            active_ports: self
+                .forwards
+                .values()
+                .map(|f| BridgedPort {
+                    port: f.port,
+                    family: f.family,
+                    bridged_at: f.bridged_at.clone(),
+                    ipv6_warning: f.ipv6_warning.clone(),
+                })
+                .collect(),
+            conflicts: self
+                .conflicts
+                .iter()
+                .map(|(port, reason)| PortConflict {
+                    port: *port,
+                    reason: reason.clone(),
+                })
+                .collect(),
+        }
+    }
+}
+
+struct ProjectBridge {
+    /// Distinguishes this poller from a later one for the same project, so a
+    /// poller that exits late can't remove its replacement's map entry.
+    epoch: u64,
+    cancel: watch::Sender<bool>,
+    state: Arc<Mutex<BridgeState>>,
+    poller: JoinHandle<()>,
+}
+
+type BridgeMap = Arc<Mutex<HashMap<String, ProjectBridge>>>;
+
+#[derive(Default)]
+pub struct AuthBridgeManager {
+    bridges: BridgeMap,
+    next_epoch: AtomicU64,
+}
+
+impl AuthBridgeManager {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Start polling for `project_id`. Idempotent: a call while a live poller
+    /// already exists for the project is a no-op.
+    pub async fn start(
+        &self,
+        project_id: String,
+        container_id: String,
+        app: AppHandle,
+        store: Arc<ProjectsStore>,
+    ) {
+        let mut map = self.bridges.lock().await;
+
+        // A finished poller has already torn its ports down, so its entry is
+        // just a husk and can be replaced. A live one means we're already on.
+        if map
+            .get(&project_id)
+            .is_some_and(|b| !b.poller.is_finished())
+        {
+            return;
+        }
+
+        let epoch = self.next_epoch.fetch_add(1, Ordering::Relaxed);
+        let state = Arc::new(Mutex::new(BridgeState::default()));
+        let (cancel_tx, cancel_rx) = watch::channel(false);
+
+        log::info!(
+            "Auth bridge: starting for project {} (container {})",
+            project_id,
+            &container_id[..container_id.len().min(12)]
+        );
+
+        let poller = tokio::spawn(poll_loop(
+            project_id.clone(),
+            container_id,
+            epoch,
+            app,
+            store,
+            state.clone(),
+            self.bridges.clone(),
+            cancel_rx,
+        ));
+
+        map.insert(
+            project_id,
+            ProjectBridge {
+                epoch,
+                cancel: cancel_tx,
+                state,
+                poller,
+            },
+        );
+    }
+
+    /// Stop the bridge for one project and wait until every host port it held
+    /// has been released.
+    pub async fn stop(&self, project_id: &str) {
+        // Remove under the lock, then release it before awaiting: the poller
+        // takes the same lock to deregister itself on exit.
+        let bridge = self.bridges.lock().await.remove(project_id);
+        if let Some(bridge) = bridge {
+            let _ = bridge.cancel.send(true);
+            let _ = bridge.poller.await;
+            log::info!("Auth bridge: stopped for project {}", project_id);
+        }
+    }
+
+    /// Stop every bridge. Used on app exit.
+    pub async fn stop_all(&self) {
+        let bridges: Vec<(String, ProjectBridge)> =
+            self.bridges.lock().await.drain().collect();
+        for (project_id, bridge) in bridges {
+            let _ = bridge.cancel.send(true);
+            let _ = bridge.poller.await;
+            log::info!("Auth bridge: stopped for project {}", project_id);
+        }
+    }
+
+    /// Current status. `enabled` comes from the persisted project record, so a
+    /// project whose bridge is on but whose container is stopped still reports
+    /// `enabled: true` with no active ports.
+    pub async fn status(&self, project_id: &str, enabled: bool) -> AuthBridgeStatus {
+        // Clone the per-project handle out and drop the map lock before taking
+        // the state lock. Holding both across the nested await is not a
+        // deadlock — the order is consistently bridges→state — but it puts a
+        // cheap UI status call behind whatever the poller is doing under
+        // `state`, and behind every other project's status call too.
+        let state = self.bridges.lock().await.get(project_id).map(|b| b.state.clone());
+        match state {
+            Some(state) => state.lock().await.snapshot(enabled),
+            None => AuthBridgeStatus {
+                enabled,
+                ..AuthBridgeStatus::disabled()
+            },
+        }
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Poller
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[allow(clippy::too_many_arguments)]
+async fn poll_loop(
+    project_id: String,
+    container_id: String,
+    epoch: u64,
+    app: AppHandle,
+    store: Arc<ProjectsStore>,
+    state: Arc<Mutex<BridgeState>>,
+    bridges: BridgeMap,
+    mut cancel: watch::Receiver<bool>,
+) {
+    let mut exec_failures: u32 = 0;
+
+    loop {
+        // Stop conditions checked every tick, so the bridge winds itself down
+        // even when nothing calls `stop()` (container died, project deleted
+        // out from under us, flag flipped off by another path).
+        let project = match store.get(&project_id) {
+            Some(p) => p,
+            None => {
+                log::info!("Auth bridge: project {} is gone — tearing down", project_id);
+                break;
+            }
+        };
+        if !project.auth_bridge_enabled {
+            log::info!("Auth bridge: disabled for project {} — tearing down", project_id);
+            break;
+        }
+        if !is_container_running(&container_id).await.unwrap_or(false) {
+            log::info!(
+                "Auth bridge: container for project {} is no longer running — tearing down",
+                project_id
+            );
+            break;
+        }
+
+        // One exec per tick reads both procfs files.
+        //
+        // Absolute path, deliberately: the image's `ENV PATH` puts a
+        // container-writable directory first, so a bare `cat` is a name the
+        // container can rebind to a shim that prints whatever it likes. It
+        // still could not make us bind a *non-loopback* port, but it decides
+        // how much output this loop ingests and how many host ports it is asked
+        // for, which is why the call is also length-capped and the result
+        // count is capped in `reconcile`.
+        let cmd = vec![
+            "/usr/bin/cat".to_string(),
+            "/proc/net/tcp".to_string(),
+            "/proc/net/tcp6".to_string(),
+        ];
+        // Cancellation races the exec, not just the sleep, so disabling the
+        // bridge or stopping the container doesn't wait out an in-flight poll.
+        let discovery = tokio::select! {
+            _ = cancel.changed() => break,
+            res = exec_oneshot_limited(&container_id, cmd, PROC_NET_OUTPUT_LIMIT) => res,
+        };
+
+        match discovery {
+            Ok(text) => {
+                exec_failures = 0;
+                let discovered = proc_net::parse_loopback_listeners(&text);
+                // Re-read every tick: a project can gain a port mapping and the
+                // gateway/STT/web-terminal ports can be re-pointed while the
+                // bridge is running, and a stale reservation set is a hole.
+                let skip = skipped_ports(&project, &store.list(), &app_settings(&app));
+                if reconcile(&container_id, &discovered, &skip, &state).await {
+                    emit_status(&app, &project_id, &state, true).await;
+                }
+            }
+            Err(e) => {
+                exec_failures += 1;
+                // Transient failures happen (container restarting, engine busy);
+                // only complain once per streak.
+                if exec_failures == 1 {
+                    log::warn!(
+                        "Auth bridge: failed to read /proc/net/tcp in container for project {}: {}",
+                        project_id,
+                        e
+                    );
+                }
+            }
+        }
+
+        tokio::select! {
+            _ = cancel.changed() => break,
+            _ = tokio::time::sleep(POLL_INTERVAL) => {}
+        }
+    }
+
+    teardown(&project_id, &state).await;
+    emit_status(
+        &app,
+        &project_id,
+        &state,
+        store
+            .get(&project_id)
+            .is_some_and(|p| p.auth_bridge_enabled),
+    )
+    .await;
+
+    // Deregister, unless a newer poller has already taken this project's slot.
+    let mut map = bridges.lock().await;
+    if map.get(&project_id).is_some_and(|b| b.epoch == epoch) {
+        map.remove(&project_id);
+    }
+}
+
+/// Every port this project's bridge must not take.
+///
+/// The bridge's rule is "a container loopback listener on port N becomes an
+/// **unauthenticated** host listener on port N". That is only safe for ports
+/// nothing else on the host owns, so everything that *is* owned has to be
+/// enumerated here. Four sources:
+///
+/// 1. **This project's own published ports** — a container port that Docker
+///    already publishes has a host-side path, and the mapping's host port is a
+///    binding we must not fight over.
+/// 2. **Every other project's published host ports.** The container names the
+///    *host* port, so project A's container listening on 8080 would otherwise
+///    have the bridge bind host 8080 — the port project B publishes on. Only
+///    the host end of another project's mapping is reserved: its container end
+///    is a number inside a different network namespace and means nothing here.
+/// 3. **This app's own host services** — the LiteLLM gateway, the STT sidecar
+///    and the web terminal. All three are off by default and bind on demand, so
+///    first-come would win: a container that binds container-loopback 4000
+///    while the gateway is stopped gets host `127.0.0.1:4000` mirrored to it
+///    within one [`POLL_INTERVAL`], after which the gateway cannot start and
+///    anything on the host dialling 4000 — including *other project
+///    containers*, which reach the gateway by host address — is talking to the
+///    squatting container instead. The web terminal is the worst of the three,
+///    because its access token travels in the URL query. Both the *configured*
+///    port and the shipped default are reserved: the configured one is what the
+///    service will bind next, and the default is what it falls back to for a
+///    fresh profile or a settings file that failed to parse.
+/// 4. [`RESERVED_CONTAINER_PORTS`] and [`RESERVED_HOST_PORTS`] — the
+///    browser-view pane's two ends, which it exposes on its own authenticated
+///    terms.
+///
+/// Pure on purpose: everything it needs is passed in, so the whole reservation
+/// policy is unit-testable without a store, a container or an app handle.
+fn skipped_ports(
+    project: &crate::models::Project,
+    all_projects: &[crate::models::Project],
+    settings: &crate::models::AppSettings,
+) -> HashSet<u16> {
+    let mut skip: HashSet<u16> = project
+        .port_mappings
+        .iter()
+        .flat_map(|m| [m.container_port, m.host_port])
+        .collect();
+
+    // Other projects: host end only.
+    skip.extend(
+        all_projects
+            .iter()
+            .filter(|p| p.id != project.id)
+            .flat_map(|p| p.port_mappings.iter().map(|m| m.host_port)),
+    );
+
+    skip.extend(app_service_host_ports(settings));
+    skip.extend(RESERVED_CONTAINER_PORTS.clone());
+    skip.extend(RESERVED_HOST_PORTS.clone());
+    skip
+}
+
+/// Current app settings, or defaults if the state is not reachable.
+///
+/// Falling back rather than unwrapping matters: the reservation set is a safety
+/// rail, and a rail that panics the poller when it cannot read its input is
+/// worse than one that falls back to the shipped port numbers — which are what
+/// the services use anyway until someone changes them.
+fn app_settings(app: &AppHandle) -> crate::models::AppSettings {
+    use tauri::Manager;
+    app.try_state::<crate::AppState>()
+        .map(|state| state.settings_store.get())
+        .unwrap_or_default()
+}
+
+/// Host ports this app's own sibling services bind, configured value and
+/// shipped default alike.
+///
+/// Read off the settings models rather than restated as literals here: a
+/// duplicated port number is exactly the kind of constant that drifts silently,
+/// and the failure mode of drift is a reservation that no longer covers the
+/// service it was written for.
+fn app_service_host_ports(settings: &crate::models::AppSettings) -> Vec<u16> {
+    use crate::models::{SttSettings, WebTerminalSettings};
+
+    vec![
+        // LiteLLM gateway (`docker/gateway.rs`).
+        settings.gateway.port,
+        crate::models::default_gateway_port(),
+        // Speech-to-text sidecar (`docker/stt.rs`).
+        settings.stt.port,
+        SttSettings::default().port,
+        // Remote web terminal (`web_terminal/server.rs`) — binds 0.0.0.0, and
+        // its access token is in the URL query.
+        settings.web_terminal.port,
+        WebTerminalSettings::default().port,
+    ]
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Reservations
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Container loopback ports another feature owns, which the bridge must leave
+/// alone.
+///
+/// The bridge's contract is "mirror every container loopback listener onto the
+/// same host port, **unauthenticated**" — correct for the throwaway OAuth
+/// callback listeners it exists for, wrong for anything sensitive. The
+/// browser-view pane runs Playwright's dashboard on a container loopback port
+/// in this range and puts a token-gated listener in front of it; mirroring that
+/// port here would quietly publish an ungated second door to full control of a
+/// browser inside the container.
+///
+/// This is a constant rather than a registry the pane populates at runtime, and
+/// that is the point: Playwright's dashboard is a detached daemon that outlives
+/// the app, so after a crash an orphaned viewer can still be listening with
+/// nothing in this process left to remember it. A static range is the only form
+/// of the rule that survives a restart. It must stay in step with
+/// `browser_view::VIEWER_PORTS`, which asserts on it.
+pub const RESERVED_CONTAINER_PORTS: std::ops::RangeInclusive<u16> = 39321..=39328;
+
+/// Host ports another feature binds on demand, which the bridge must not take
+/// first.
+///
+/// These are the browser-view proxy's host ports. The bridge binds *host* ports
+/// named by the container, so a container listening on 47820 would have the
+/// bridge take the host side of that number — and then the browser-view pane,
+/// which only binds when the user opens it, finds its port gone. The two ranges
+/// are separate constants because they guard opposite ends of the same
+/// mechanism: [`RESERVED_CONTAINER_PORTS`] is about not *publishing* something,
+/// this one is about not *stealing* something.
+pub const RESERVED_HOST_PORTS: std::ops::RangeInclusive<u16> =
+    crate::browser_view::proxy::PROXY_PORTS;
+
+/// Most host ports the bridge will hold for one project at a time.
+///
+/// The discovery input is entirely container-controlled, and each
+/// [`PortForward`] costs two listeners plus a task, so without a cap a
+/// container that reports tens of thousands of fake listeners exhausts the
+/// app's file descriptors and the host's ephemeral ports in a single tick. A
+/// real login flow uses one or two ports at a time; anything past a couple of
+/// dozen is not a login.
+const MAX_FORWARDS: usize = 24;
+
+/// Most conflicts recorded at once, so a flood of unbindable ports can't grow
+/// the status payload (and the UI list) without bound either.
+const MAX_CONFLICTS: usize = 32;
+
+/// Bring the set of host listeners in line with what the container is currently
+/// listening on. Returns whether anything the UI cares about changed.
+async fn reconcile(
+    container_id: &str,
+    discovered: &BTreeMap<u16, PortFamily>,
+    skip: &HashSet<u16>,
+    state: &Arc<Mutex<BridgeState>>,
+) -> bool {
+    let mut changed = false;
+    let mut st = state.lock().await;
+
+    // Drop host listeners whose container-side counterpart vanished, became
+    // covered by an explicit port mapping, or changed address family (a family
+    // change alters the socat target, so it has to be rebound below).
+    let stale: Vec<u16> = st
+        .forwards
+        .iter()
+        .filter(|(port, forward)| match discovered.get(port) {
+            None => true,
+            Some(_) if skip.contains(port) => true,
+            Some(family) => *family != forward.family,
+        })
+        .map(|(port, _)| *port)
+        .collect();
+    for port in stale {
+        if let Some(mut forward) = st.forwards.remove(&port) {
+            forward.shutdown().await;
+            log::info!("Auth bridge: released host port {}", port);
+            changed = true;
+        }
+    }
+
+    // Forget conflicts for ports that are no longer relevant.
+    let before = st.conflicts.len();
+    st.conflicts
+        .retain(|port, _| discovered.contains_key(port) && !skip.contains(port));
+    changed |= st.conflicts.len() != before;
+
+    for (&port, &family) in discovered {
+        if skip.contains(&port) || st.forwards.contains_key(&port) {
+            continue;
+        }
+        if st.forwards.len() >= MAX_FORWARDS {
+            // Don't even attempt the bind: the point of the cap is to stop the
+            // container dictating how many host resources we take.
+            changed |= note_conflict(
+                &mut st,
+                port,
+                format!(
+                    "The auth bridge is already holding {} ports for this project; \
+                     {} was not bridged.",
+                    MAX_FORWARDS, port
+                ),
+            );
+            continue;
+        }
+        match PortForward::bind(container_id.to_string(), port, family).await {
+            Ok(forward) => {
+                if st.conflicts.remove(&port).is_some() {
+                    log::info!("Auth bridge: host port {} became available", port);
+                }
+                log::info!(
+                    "Auth bridge: bridging 127.0.0.1:{} → container {} ({:?})",
+                    port,
+                    family.socat_target(port),
+                    family
+                );
+                st.forwards.insert(port, forward);
+                changed = true;
+            }
+            Err(e) => {
+                // Conflict policy: never fight for a port. Something else on the
+                // host owns it — another project's bridge, or an unrelated
+                // process. Skip it, record why so the UI can say so, and retry
+                // on later ticks in case the owner releases it. Warn only on
+                // the transition so a long-lived conflict doesn't spam the log.
+                let reason = format!(
+                    "Host port {} is already in use ({}); not bridged.",
+                    port, e
+                );
+                if st.conflicts.get(&port) != Some(&reason) {
+                    log::warn!("Auth bridge: {}", reason);
+                }
+                changed |= note_conflict(&mut st, port, reason);
+            }
+        }
+    }
+
+    changed
+}
+
+/// Record why a port wasn't bridged, up to [`MAX_CONFLICTS`]. Returns whether
+/// the recorded set changed.
+fn note_conflict(state: &mut BridgeState, port: u16, reason: String) -> bool {
+    match state.conflicts.get(&port) {
+        Some(existing) if *existing == reason => false,
+        Some(_) => {
+            state.conflicts.insert(port, reason);
+            true
+        }
+        None if state.conflicts.len() < MAX_CONFLICTS => {
+            state.conflicts.insert(port, reason);
+            true
+        }
+        None => false,
+    }
+}
+
+/// Release every host port held for this project. Awaits each shutdown, so on
+/// return nothing is bound.
+async fn teardown(project_id: &str, state: &Arc<Mutex<BridgeState>>) {
+    let mut st = state.lock().await;
+    let forwards = std::mem::take(&mut st.forwards);
+    st.conflicts.clear();
+    let count = forwards.len();
+    for (_, mut forward) in forwards {
+        forward.shutdown().await;
+    }
+    if count > 0 {
+        log::info!(
+            "Auth bridge: released {} host port(s) for project {}",
+            count,
+            project_id
+        );
+    }
+}
+
+async fn emit_status(
+    app: &AppHandle,
+    project_id: &str,
+    state: &Arc<Mutex<BridgeState>>,
+    enabled: bool,
+) {
+    let status = state.lock().await.snapshot(enabled);
+    let _ = app.emit(
+        AUTH_BRIDGE_EVENT,
+        serde_json::json!({
+            "project_id": project_id,
+            "status": status,
+        }),
+    );
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::{AppSettings, PortMapping, Project, ProjectPath};
+
+    fn project_with_mappings(mappings: Vec<(u16, u16)>) -> Project {
+        let mut p = Project::new(
+            "test".to_string(),
+            vec![ProjectPath {
+                host_path: "/tmp".to_string(),
+                mount_name: "tmp".to_string(),
+            }],
+        );
+        p.port_mappings = mappings
+            .into_iter()
+            .map(|(host_port, container_port)| PortMapping {
+                host_port,
+                container_port,
+                protocol: "tcp".to_string(),
+            })
+            .collect();
+        p
+    }
+
+    /// The common case: one project, no siblings, stock settings.
+    fn skip_for(project: &Project) -> HashSet<u16> {
+        skipped_ports(project, std::slice::from_ref(project), &AppSettings::default())
+    }
+
+    #[test]
+    fn ports_already_published_by_docker_are_skipped() {
+        let skip = skip_for(&project_with_mappings(vec![(3000, 3000), (8081, 8080)]));
+        assert!(skip.contains(&3000));
+        // Both ends of an asymmetric mapping are off limits: the container port
+        // is already reachable, and the host port is Docker's binding.
+        assert!(skip.contains(&8080));
+        assert!(skip.contains(&8081));
+        assert!(!skip.contains(&34567));
+    }
+
+    #[test]
+    fn no_mappings_means_nothing_but_the_reservations_are_skipped() {
+        let settings = AppSettings::default();
+        let project = project_with_mappings(vec![]);
+        let skip = skip_for(&project);
+
+        let mut expected: HashSet<u16> = RESERVED_CONTAINER_PORTS.collect();
+        expected.extend(RESERVED_HOST_PORTS);
+        expected.extend(app_service_host_ports(&settings));
+        assert_eq!(skip, expected);
+
+        // The ranges and the service ports are disjoint, so nothing above is
+        // accidentally counting the same port twice.
+        assert_eq!(
+            skip.len(),
+            RESERVED_CONTAINER_PORTS.clone().count()
+                + RESERVED_HOST_PORTS.clone().count()
+                + 3
+        );
+    }
+
+    #[test]
+    fn this_apps_own_host_services_are_never_taken() {
+        // The bug this guards: the reserved set used to cover only the
+        // browser-view ranges and this project's own mappings, so a container
+        // binding container-loopback 4000 / 9876 / 7681 while the matching
+        // service was stopped had that port mirrored, unauthenticated, onto the
+        // host — taking the gateway's, the STT sidecar's or the web terminal's
+        // door before they could bind it.
+        let settings = AppSettings::default();
+        let skip = skip_for(&project_with_mappings(vec![]));
+
+        assert!(skip.contains(&settings.gateway.port), "LiteLLM gateway port");
+        assert!(skip.contains(&settings.stt.port), "STT sidecar port");
+        assert!(skip.contains(&settings.web_terminal.port), "web terminal port");
+
+        // The shipped defaults, spelled out once so a change to any of them is
+        // a change to this assertion and not a silent narrowing.
+        assert!(skip.contains(&4000));
+        assert!(skip.contains(&9876));
+        assert!(skip.contains(&7681));
+    }
+
+    #[test]
+    fn a_reconfigured_service_port_is_reserved_alongside_its_default() {
+        let mut settings = AppSettings::default();
+        settings.gateway.port = 4321;
+        settings.stt.port = 9000;
+        settings.web_terminal.port = 8443;
+        let project = project_with_mappings(vec![]);
+        let skip = skipped_ports(&project, std::slice::from_ref(&project), &settings);
+
+        for port in [4321, 9000, 8443] {
+            assert!(skip.contains(&port), "configured port {} should be reserved", port);
+        }
+        // The default stays reserved too: it is what the service falls back to
+        // for a fresh profile or an unparseable settings file, so leaving it
+        // open is leaving the same squat available one restart later.
+        for port in [4000, 9876, 7681] {
+            assert!(skip.contains(&port), "default port {} should be reserved", port);
+        }
+    }
+
+    #[test]
+    fn another_projects_published_host_port_is_not_stolen() {
+        // The container names the *host* port. Without this, project A's
+        // container listening on 8080 takes the host 8080 that project B
+        // publishes on — the bridge wins the race whenever B's container is not
+        // running yet.
+        let mine = project_with_mappings(vec![]);
+        let mut theirs = project_with_mappings(vec![(8080, 3000)]);
+        theirs.id = format!("{}-other", mine.id);
+
+        let skip = skipped_ports(
+            &mine,
+            &[mine.clone(), theirs.clone()],
+            &AppSettings::default(),
+        );
+        assert!(skip.contains(&8080), "another project's host port");
+        // …but not the other project's *container* port: that number lives in a
+        // different network namespace and means nothing on this host, and
+        // reserving it would refuse a legitimate login callback for no reason.
+        assert!(!skip.contains(&3000));
+    }
+
+    #[test]
+    fn the_browser_views_host_ports_are_never_taken() {
+        // The bridge binds *host* ports chosen by the container, so without
+        // this it can take the port the browser-view proxy will want later —
+        // that pane binds on demand, so first-come would win.
+        let skip = skip_for(&project_with_mappings(vec![]));
+        for port in RESERVED_HOST_PORTS {
+            assert!(skip.contains(&port), "host port {} should be reserved", port);
+        }
+        assert!(!skip.contains(&(RESERVED_HOST_PORTS.end() + 1)));
+    }
+
+    #[test]
+    fn conflicts_stop_being_recorded_past_the_cap() {
+        let mut st = BridgeState::default();
+        for port in 1000u16..1000 + MAX_CONFLICTS as u16 {
+            assert!(note_conflict(&mut st, port, "busy".to_string()));
+        }
+        // Past the cap: new ports are dropped rather than growing the status
+        // payload the UI renders.
+        assert!(!note_conflict(&mut st, 9999, "busy".to_string()));
+        assert_eq!(st.conflicts.len(), MAX_CONFLICTS);
+        // A changed reason for a port already tracked still updates.
+        assert!(!note_conflict(&mut st, 1000, "busy".to_string()));
+        assert!(note_conflict(&mut st, 1000, "different".to_string()));
+        assert_eq!(st.conflicts.len(), MAX_CONFLICTS);
+    }
+
+    #[tokio::test]
+    async fn the_host_ports_one_container_can_demand_are_capped() {
+        // The container fully controls the discovery input (it can shim the
+        // probe command), and each forward costs two listeners plus a task —
+        // uncapped, one tick could exhaust the app's fds and the host's
+        // ephemeral ports.
+        let discovered: BTreeMap<u16, PortFamily> =
+            (45000u16..45200).map(|p| (p, PortFamily::V4)).collect();
+        let state = Arc::new(Mutex::new(BridgeState::default()));
+
+        reconcile("no-such-container", &discovered, &HashSet::new(), &state).await;
+
+        let mut st = state.lock().await;
+        assert!(
+            st.forwards.len() <= MAX_FORWARDS,
+            "bridged {} ports, cap is {}",
+            st.forwards.len(),
+            MAX_FORWARDS
+        );
+        assert!(st.conflicts.len() <= MAX_CONFLICTS);
+        // Nowhere near the 200 the "container" asked for.
+        assert!(st.forwards.len() + st.conflicts.len() < discovered.len());
+
+        for (_, mut forward) in std::mem::take(&mut st.forwards) {
+            forward.shutdown().await;
+        }
+    }
+
+    #[test]
+    fn the_browser_views_ports_are_never_mirrored() {
+        // Mirroring these would publish an ungated second door to the
+        // Playwright dashboard, which the pane deliberately keeps behind a
+        // token-checking listener.
+        let skip = skip_for(&project_with_mappings(vec![]));
+        for port in RESERVED_CONTAINER_PORTS {
+            assert!(skip.contains(&port), "port {} should be reserved", port);
+        }
+        assert!(!skip.contains(&(RESERVED_CONTAINER_PORTS.end() + 1)));
+
+        // Reservations coexist with Docker's own published ports.
+        let skip = skip_for(&project_with_mappings(vec![(3000, 3000)]));
+        assert!(skip.contains(RESERVED_CONTAINER_PORTS.start()));
+        assert!(skip.contains(&3000));
+    }
+}

app/src-tauri/src/auth_bridge/proc_net.rs

@@ -0,0 +1,302 @@
+//! Discovery of loopback TCP listeners by parsing `/proc/net/tcp` and
+//! `/proc/net/tcp6` from inside the container.
+//!
+//! ## Why /proc and not `ss`
+//!
+//! The container image (`container/Dockerfile`) ships neither `iproute2` (`ss`)
+//! nor `net-tools` (`netstat`) nor `lsof`. `/proc/net/tcp{,6}` is part of procfs
+//! and needs no package at all, so discovery works in the stock image and in any
+//! snapshot derived from it.
+//!
+//! ## Wire format
+//!
+//! Both files are fixed-column text with a header line:
+//!
+//! ```text
+//!   sl  local_address rem_address   st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode
+//!    0: 0100007F:8707 00000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 27764798 1 ...
+//! ```
+//!
+//! Only two columns matter: `local_address` (index 1) and `st` (index 3).
+//! `st == 0A` is `TCP_LISTEN`; every other state is a connection, not a listener.
+//!
+//! ## Hex and endianness
+//!
+//! `local_address` is `<address>:<port>`, both hex, but they are *not* encoded
+//! the same way:
+//!
+//! * The **port** is a plain big-endian `%04X` — `8707` is 34567.
+//! * The **address** is printed as one `%08X` per 32-bit word *in host byte
+//!   order*, which is little-endian on every platform this app targets. So each
+//!   8-hex-digit group must be parsed as a `u32` and then expanded with
+//!   [`u32::to_le_bytes`] to recover the address bytes in network order:
+//!   `0100007F` → `0x0100007F` → `[7F, 00, 00, 01]` → `127.0.0.1`.
+//!
+//! IPv4 rows have one such group (8 hex digits); IPv6 rows have four (32 hex
+//! digits), each converted independently, in order, to fill the 16 address
+//! bytes. `::1` is therefore `00000000000000000000000001000000`, and the
+//! IPv4-mapped `::ffff:127.0.0.1` is `0000000000000000FFFF00000100007F`.
+//!
+//! ## What counts as loopback
+//!
+//! Only `127.0.0.0/8` and `::1` (plus IPv4-mapped loopback, reported as v4).
+//! A `0.0.0.0` or `::` listener is a service deliberately published to the
+//! outside world — that is the port-mappings feature's job, not the auth
+//! bridge's — so those rows are dropped.
+
+use std::collections::BTreeMap;
+use std::net::{Ipv4Addr, Ipv6Addr};
+
+use serde::{Deserialize, Serialize};
+
+/// The `st` column value for `TCP_LISTEN`.
+const TCP_LISTEN: &str = "0A";
+
+/// Which loopback address family (or families) a container-side listener was
+/// found on. Determines the `socat` target address used to reach it.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum PortFamily {
+    /// Only `127.0.0.0/8`.
+    V4,
+    /// Only `::1`. Common in practice: Node resolves `localhost` to IPv6 first
+    /// on Linux, so `claude login` frequently binds `::1` and nothing else
+    /// (anthropics/claude-code#44844).
+    V6,
+    /// Both — reachable either way; we use IPv4.
+    Dual,
+}
+
+impl PortFamily {
+    fn merge(self, other: PortFamily) -> PortFamily {
+        if self == other {
+            self
+        } else {
+            PortFamily::Dual
+        }
+    }
+
+    /// The `socat` address that reaches this listener from inside the container.
+    /// A `::1`-only listener genuinely cannot be reached via `127.0.0.1`
+    /// (verified: connect gets ECONNREFUSED), hence the split.
+    pub fn socat_target(&self, port: u16) -> String {
+        match self {
+            PortFamily::V4 | PortFamily::Dual => format!("TCP:127.0.0.1:{}", port),
+            PortFamily::V6 => format!("TCP6:[::1]:{}", port),
+        }
+    }
+}
+
+/// One parsed LISTEN row that survived the loopback filter.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub struct LoopbackListener {
+    pub port: u16,
+    pub family: PortFamily,
+}
+
+/// Parse the concatenated contents of `/proc/net/tcp` and `/proc/net/tcp6` into
+/// the set of loopback ports being listened on, keyed by port with the families
+/// merged (a port bound on both `127.0.0.1` and `::1` yields
+/// [`PortFamily::Dual`]).
+///
+/// Unparseable lines — the two header lines, `cat`'s "No such file" complaint
+/// when IPv6 is disabled, anything else that ends up interleaved in the exec's
+/// combined output — are silently ignored rather than failing the whole poll.
+pub fn parse_loopback_listeners(text: &str) -> BTreeMap<u16, PortFamily> {
+    let mut ports: BTreeMap<u16, PortFamily> = BTreeMap::new();
+    for listener in parse_listener_rows(text) {
+        ports
+            .entry(listener.port)
+            .and_modify(|f| *f = f.merge(listener.family))
+            .or_insert(listener.family);
+    }
+    ports
+}
+
+/// Row-level parse, before per-port family merging. Split out so tests can
+/// assert on the individual rows.
+pub fn parse_listener_rows(text: &str) -> Vec<LoopbackListener> {
+    text.lines().filter_map(parse_listener_row).collect()
+}
+
+fn parse_listener_row(line: &str) -> Option<LoopbackListener> {
+    let mut fields = line.split_whitespace();
+    let _sl = fields.next()?;
+    let local_address = fields.next()?;
+    let _rem_address = fields.next()?;
+    let state = fields.next()?;
+
+    if state != TCP_LISTEN {
+        return None;
+    }
+
+    let (addr_hex, port_hex) = local_address.split_once(':')?;
+    // The port is a straightforward big-endian hex u16 — no byte swapping.
+    let port = u16::from_str_radix(port_hex, 16).ok()?;
+    if port == 0 {
+        return None;
+    }
+
+    let family = match addr_hex.len() {
+        8 => {
+            let addr = Ipv4Addr::from(parse_le_word(addr_hex)?);
+            addr.is_loopback().then_some(PortFamily::V4)
+        }
+        32 => {
+            let mut octets = [0u8; 16];
+            for (i, group) in addr_hex.as_bytes().chunks(8).enumerate() {
+                let group = std::str::from_utf8(group).ok()?;
+                octets[i * 4..i * 4 + 4].copy_from_slice(&parse_le_word(group)?);
+            }
+            let addr = Ipv6Addr::from(octets);
+            // An IPv4-mapped row describes a v4 socket, so it is reachable at
+            // 127.0.0.1 and must be classified as v4, not v6.
+            match addr.to_ipv4_mapped() {
+                Some(v4) => v4.is_loopback().then_some(PortFamily::V4),
+                None => addr.is_loopback().then_some(PortFamily::V6),
+            }
+        }
+        _ => None,
+    }?;
+
+    Some(LoopbackListener { port, family })
+}
+
+/// Parse one `%08X` procfs address word into its four address bytes in network
+/// order. The kernel prints the word in host byte order, so the recovered bytes
+/// are the little-endian expansion of the parsed integer.
+fn parse_le_word(hex: &str) -> Option<[u8; 4]> {
+    Some(u32::from_str_radix(hex, 16).ok()?.to_le_bytes())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Verbatim `cat /proc/net/tcp` from a running `triple-c:latest` container
+    /// with three listeners deliberately started:
+    ///   * `socat TCP4-LISTEN:34567,bind=127.0.0.1`  → row 0 (`0100007F:8707`)
+    ///   * `socat TCP4-LISTEN:34569,bind=0.0.0.0`    → row 1 (`00000000:8709`)
+    ///   * `node ... .listen(34568, "::1")`          → appears in TCP6 only
+    const REAL_PROC_NET_TCP: &str = concat!(
+        "  sl  local_address rem_address   st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode                                                     \n",
+        "   0: 0100007F:8707 00000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 27764798 1 0000000000000000 100 0 0 10 0                  \n",
+        "   1: 00000000:8709 00000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 27758875 1 0000000000000000 100 0 0 10 0                  \n",
+    );
+
+    /// Verbatim `cat /proc/net/tcp6` from the same container. The single row is
+    /// the Node listener bound to `::1` only — the case that motivates the
+    /// TCP6 socat target.
+    const REAL_PROC_NET_TCP6: &str = concat!(
+        "  sl  local_address                         remote_address                        st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode\n",
+        "   0: 00000000000000000000000001000000:8708 00000000000000000000000000000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 27747129 1 0000000000000000 100 0 0 10 0\n",
+    );
+
+    fn both_files() -> String {
+        format!("{}{}", REAL_PROC_NET_TCP, REAL_PROC_NET_TCP6)
+    }
+
+    #[test]
+    fn parses_ipv4_loopback_row_with_little_endian_address() {
+        let rows = parse_listener_rows(REAL_PROC_NET_TCP);
+        // 0100007F → 127.0.0.1 (kept), 00000000 → 0.0.0.0 (dropped).
+        assert_eq!(
+            rows,
+            vec![LoopbackListener {
+                port: 0x8707,
+                family: PortFamily::V4
+            }]
+        );
+        assert_eq!(rows[0].port, 34567);
+    }
+
+    #[test]
+    fn parses_ipv6_loopback_row() {
+        let rows = parse_listener_rows(REAL_PROC_NET_TCP6);
+        assert_eq!(
+            rows,
+            vec![LoopbackListener {
+                port: 34568,
+                family: PortFamily::V6
+            }]
+        );
+    }
+
+    #[test]
+    fn ignores_wildcard_bind_addresses() {
+        // 0.0.0.0:34569 is in the fixture and must never be bridged — that is
+        // the port-mappings feature's territory.
+        let ports = parse_loopback_listeners(&both_files());
+        assert!(!ports.contains_key(&34569));
+
+        // Same for the IPv6 wildcard and a non-loopback unicast address.
+        let wildcard_v6 = "   0: 00000000000000000000000000000000:1F90 00000000000000000000000000000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 1 1 0 100 0 0 10 0";
+        let lan_v4 = "   0: 0245A8C0:1F90 00000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 1 1 0 100 0 0 10 0";
+        assert!(parse_listener_rows(wildcard_v6).is_empty());
+        assert!(parse_listener_rows(lan_v4).is_empty());
+    }
+
+    #[test]
+    fn parses_both_files_concatenated_as_one_exec_output() {
+        let ports = parse_loopback_listeners(&both_files());
+        assert_eq!(ports.len(), 2);
+        assert_eq!(ports.get(&34567), Some(&PortFamily::V4));
+        assert_eq!(ports.get(&34568), Some(&PortFamily::V6));
+    }
+
+    #[test]
+    fn merges_families_for_a_dual_stack_port() {
+        let dual = format!(
+            "{}   1: 00000000000000000000000001000000:8707 00000000000000000000000000000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 2 1 0 100 0 0 10 0\n",
+            both_files()
+        );
+        let ports = parse_loopback_listeners(&dual);
+        assert_eq!(ports.get(&34567), Some(&PortFamily::Dual));
+    }
+
+    #[test]
+    fn ipv4_mapped_loopback_is_reported_as_v4() {
+        // ::ffff:127.0.0.1 — a v4 socket surfacing in /proc/net/tcp6.
+        let row = "   0: 0000000000000000FFFF00000100007F:8707 00000000000000000000000000000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 1 1 0 100 0 0 10 0";
+        assert_eq!(
+            parse_listener_rows(row),
+            vec![LoopbackListener {
+                port: 34567,
+                family: PortFamily::V4
+            }]
+        );
+    }
+
+    #[test]
+    fn ignores_non_listen_states() {
+        // Same loopback address, state 01 (ESTABLISHED) instead of 0A.
+        let established = "   0: 0100007F:8707 0100007F:C350 01 00000000:00000000 00:00000000 00000000     0        0 1 1 0 100 0 0 10 0";
+        assert!(parse_listener_rows(established).is_empty());
+    }
+
+    #[test]
+    fn ignores_headers_and_garbage() {
+        assert!(parse_listener_rows("").is_empty());
+        assert!(parse_listener_rows(
+            "cat: /proc/net/tcp6: No such file or directory\n\n  sl  local_address rem_address   st\n"
+        )
+        .is_empty());
+        // Truncated / malformed rows must not panic or be accepted.
+        assert!(parse_listener_rows("   0: 0100007F 00000000:0000 0A").is_empty());
+        assert!(parse_listener_rows("   0: ZZZZZZZZ:8707 00000000:0000 0A x").is_empty());
+        assert!(parse_listener_rows("   0: 0100007F:0000 00000000:0000 0A x").is_empty());
+    }
+
+    #[test]
+    fn socat_target_matches_family() {
+        assert_eq!(
+            PortFamily::V4.socat_target(34567),
+            "TCP:127.0.0.1:34567"
+        );
+        assert_eq!(
+            PortFamily::Dual.socat_target(34567),
+            "TCP:127.0.0.1:34567"
+        );
+        assert_eq!(PortFamily::V6.socat_target(34568), "TCP6:[::1]:34568");
+    }
+}

app/src-tauri/src/auth_bridge/tunnel.rs

@@ -0,0 +1,828 @@
+//! Host-side loopback listener for one bridged port, and the per-connection
+//! tunnel that carries its bytes into the container.
+//!
+//! ## Why not connect to the container's IP
+//!
+//! Container IPs are not routable from the host on Docker Desktop (macOS and
+//! Windows run the engine in a VM), so a host→`172.17.x.x` dial cannot be the
+//! transport. The Docker API is the only channel guaranteed to reach the
+//! container from the host, so each accepted connection is carried by a
+//! `docker exec` running `socat - TCP:127.0.0.1:<port>`, with the exec's stdin
+//! and stdout wired to the TCP socket. `socat` ships in the container image.
+//!
+//! The exec plumbing itself is *not* reimplemented here: it comes from
+//! [`crate::docker::exec::create_attached_exec`], the same helper the
+//! interactive terminal sessions are built on.
+//!
+//! ## What the host listener is, and is not
+//!
+//! The listener is **not authenticated**, and cannot be. The port number is
+//! chosen by whatever CLI is logging in, the redirect URL is the provider's, and
+//! nothing in that chain can be taught to present a token — so there is no path
+//! token to add. Anything that can reach `127.0.0.1:<port>` on this host reaches
+//! the container-side listener. That includes **any web page the user has open**,
+//! which can port-scan loopback from script.
+//!
+//! Two things narrow that, and neither is a substitute for the other:
+//!
+//! * The whole feature is opt-in per project, off by default, and only mirrors
+//!   ports while its container is running.
+//! * [`web_request_verdict`] refuses the one case that is unambiguously a web
+//!   page reaching in: a request whose fetch metadata says it is a cross-site
+//!   **sub-resource** (`fetch`, `XMLHttpRequest`, `<img>`, `<script src>`,
+//!   `<iframe>`). Cross-site *navigations* are allowed, because that is exactly
+//!   what an OAuth redirect is.
+//!
+//! The residual risk, stated plainly rather than papered over: a client that
+//! sends no `Sec-Fetch-Site` header at all is not filtered — that is every
+//! non-browser client (which is the point; `curl`, a CLI, the container's own
+//! probe must all still work) but also any browser predating fetch metadata
+//! (Chrome < 76, Firefox < 90, Safari < 16.4). A page can also still reach the
+//! port with a top-level navigation it opens itself (`window.open`), which
+//! carries `Sec-Fetch-Mode: navigate` and is indistinguishable from the redirect
+//! the bridge exists to deliver. And nothing here inspects *what* is behind the
+//! port: if the container has something more interesting than a throwaway OAuth
+//! listener on loopback, a same-machine caller reaches it.
+//!
+//! ## Bounds
+//!
+//! Every accepted connection costs a `docker exec`, and the number of
+//! connections is decided by whoever can reach the port. So each forward caps
+//! concurrent connections ([`MAX_CONNECTIONS`]), refuses a client that opens a
+//! socket and then says nothing ([`FIRST_BYTE_TIMEOUT`], enforced *before* the
+//! exec is created), and drops a connection the container has gone quiet on
+//! ([`IDLE_TIMEOUT`]).
+
+use std::net::{Ipv4Addr, Ipv6Addr, SocketAddr};
+use std::time::Duration;
+
+use bollard::container::LogOutput;
+use futures_util::StreamExt;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::{TcpListener, TcpStream};
+use tokio::task::{JoinHandle, JoinSet};
+
+use crate::docker::exec::{create_attached_exec, AttachedExec};
+
+use super::proc_net::PortFamily;
+
+/// Buffer size for the host→container direction. OAuth callbacks are tiny; this
+/// only needs to not be pathological.
+const PUMP_BUF: usize = 16 * 1024;
+
+/// Concurrent connections one forwarded port will carry.
+///
+/// Each one is a `docker exec`, and the client side is anything on the host that
+/// can dial loopback — including a web page in a loop. A login callback is one
+/// connection, occasionally a handful; this is generous for that and still a
+/// bound the engine will not notice.
+const MAX_CONNECTIONS: usize = 16;
+
+/// How long an accepted connection has to send its first byte before it is
+/// dropped, *without* a `docker exec` ever being created for it.
+///
+/// This is a deliberate narrowing of what the bridge carries: a client that
+/// connects and says nothing is not the HTTP OAuth callback this exists for, and
+/// forwarding it costs a container exec for a socket that may never speak. A
+/// server-speaks-first protocol behind a bridged port would be refused by this;
+/// that is the trade, and it is the only protocol shape affected.
+const FIRST_BYTE_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// How long a live connection may go with nothing coming back from the container
+/// before it is torn down. Generous, because a bridged port is not always a
+/// short OAuth callback — but finite, so an abandoned connection cannot pin an
+/// exec forever.
+const IDLE_TIMEOUT: Duration = Duration::from_secs(600);
+
+/// Ceiling on the request head buffered for [`web_request_verdict`]. Real heads
+/// are well under 8 KiB; past this we stop looking and forward what we have.
+const MAX_HEAD: usize = 32 * 1024;
+
+/// How long the rest of a request head has, once the first line has identified
+/// the connection as HTTP. Only a stalled or hostile client reaches it.
+const HEAD_TIMEOUT: Duration = Duration::from_secs(10);
+
+/// Aborts a task when dropped, so a cancelled parent can never leave a detached
+/// child running.
+struct AbortOnDrop(JoinHandle<()>);
+
+impl Drop for AbortOnDrop {
+    fn drop(&mut self) {
+        self.0.abort();
+    }
+}
+
+/// One host loopback port bound and proxied into the container.
+///
+/// The accept loop owns the [`TcpListener`](tokio::net::TcpListener)s and the
+/// [`JoinSet`] of live connection tasks, so aborting the single task handle
+/// releases the port *and* tears down every connection under it. [`Drop`] does
+/// that as a backstop; [`PortForward::shutdown`] does it deterministically by
+/// also awaiting the aborted task, which guarantees the socket is closed before
+/// the caller proceeds (important when a port is rebound right after).
+pub struct PortForward {
+    pub port: u16,
+    pub family: PortFamily,
+    pub bridged_at: String,
+    /// Why `[::1]` could not be taken alongside `127.0.0.1`, if it could not.
+    ///
+    /// A half-bound forward is the one failure mode that looks like a success:
+    /// the status says the port is bridged, and a browser that resolves
+    /// `localhost` to `::1` and does not fall back still gets a refused
+    /// connection. It is not a conflict — the IPv4 half really is carrying
+    /// traffic — so it rides along with the port it belongs to and the UI says
+    /// so, rather than being logged at debug where nobody sees it.
+    pub ipv6_warning: Option<String>,
+    task: JoinHandle<()>,
+}
+
+impl Drop for PortForward {
+    fn drop(&mut self) {
+        self.task.abort();
+    }
+}
+
+impl PortForward {
+    /// Bind `port` on the host loopback and start proxying into `container_id`.
+    ///
+    /// The bind happens before the task is spawned, so an already-taken port is
+    /// reported to the caller as an error rather than disappearing into a
+    /// background task.
+    pub async fn bind(
+        container_id: String,
+        port: u16,
+        family: PortFamily,
+    ) -> Result<Self, std::io::Error> {
+        // SECURITY BOUNDARY: the host side binds loopback ONLY — 127.0.0.1 and
+        // ::1, never 0.0.0.0 / ::. Everything reachable through this socket is
+        // an unauthenticated service inside the container that deliberately
+        // bound loopback because it expected to be reachable from nowhere else.
+        // Binding a wildcard address here would publish container internals to
+        // every host on the LAN. Do not "fix" a connectivity problem by
+        // widening these addresses.
+        let v4 = TcpListener::bind(SocketAddr::from((Ipv4Addr::LOCALHOST, port))).await?;
+
+        // Also take ::1 when it is available. Browsers and CLIs resolve
+        // `localhost` to either family, and the IPv6 answer is often tried
+        // first, so a v4-only host listener would miss those callbacks. This is
+        // best-effort: if ::1 is unavailable (no IPv6, or that half is taken)
+        // the v4 listener alone still works, so it is not treated as a conflict.
+        let (v6, ipv6_warning) =
+            match TcpListener::bind(SocketAddr::from((Ipv6Addr::LOCALHOST, port))).await {
+                Ok(l) => (Some(l), None),
+                Err(e) => {
+                    // Warn, not debug. Best-effort is about whether to *fail*,
+                    // not about whether to say anything: on a host where
+                    // `localhost` resolves to `::1` and the client does not
+                    // fall back to IPv4, the callback is refused while the
+                    // bridge reports itself healthy — a silent failure with no
+                    // thread back to this line.
+                    log::warn!(
+                        "Auth bridge: bound 127.0.0.1:{} but not [::1]:{} ({}) — continuing with IPv4 only; \
+                         a client that resolves localhost to ::1 without falling back will not reach it",
+                        port,
+                        port,
+                        e
+                    );
+                    (
+                        None,
+                        Some(format!(
+                            "IPv4 only — [::1]:{} could not be bound ({}). A browser that resolves \
+                             localhost to ::1 without falling back will not reach this port.",
+                            port, e
+                        )),
+                    )
+                }
+            };
+
+        let target = family.socat_target(port);
+        let task = tokio::spawn(accept_loop(container_id, port, target, v4, v6));
+
+        Ok(Self {
+            port,
+            family,
+            bridged_at: chrono::Utc::now().to_rfc3339(),
+            ipv6_warning,
+            task,
+        })
+    }
+
+    /// Stop accepting, drop the host socket, and abort every in-flight
+    /// connection. Awaits the aborted task so the port is provably released
+    /// when this returns.
+    pub async fn shutdown(&mut self) {
+        self.task.abort();
+        let _ = (&mut self.task).await;
+    }
+}
+
+/// Accept on both loopback listeners until aborted. Dropping this future drops
+/// the listeners (freeing the port) and the `JoinSet` (aborting live tunnels).
+async fn accept_loop(
+    container_id: String,
+    port: u16,
+    target: String,
+    v4: TcpListener,
+    v6: Option<TcpListener>,
+) {
+    let mut conns: JoinSet<()> = JoinSet::new();
+
+    loop {
+        let accepted = tokio::select! {
+            r = v4.accept() => r,
+            r = accept_optional(v6.as_ref()) => r,
+            // Reap finished tunnels so the JoinSet doesn't grow without bound.
+            // When the set is empty `join_next()` yields None, the pattern fails
+            // to match, and the branch simply drops out of the select.
+            Some(_) = conns.join_next() => continue,
+        };
+
+        match accepted {
+            Ok((stream, peer)) => {
+                // Reap first, so the cap counts *live* connections rather than
+                // every one this listener has ever accepted.
+                while conns.try_join_next().is_some() {}
+                if conns.len() >= MAX_CONNECTIONS {
+                    // Dropping the stream closes it. Better than queueing: the
+                    // client side is whatever can dial loopback, so a queue is
+                    // just a slower way to run out of execs.
+                    log::warn!(
+                        "Auth bridge: refusing connection from {} to bridged port {} — \
+                         {} concurrent connections already open on it",
+                        peer,
+                        port,
+                        MAX_CONNECTIONS
+                    );
+                    continue;
+                }
+                log::debug!("Auth bridge: connection from {} to bridged port {}", peer, port);
+                let _ = stream.set_nodelay(true);
+                conns.spawn(tunnel_connection(
+                    container_id.clone(),
+                    target.clone(),
+                    stream,
+                    port,
+                ));
+            }
+            Err(e) => {
+                log::warn!("Auth bridge: accept failed on port {}: {} — stopping listener", port, e);
+                return;
+            }
+        }
+    }
+}
+
+/// `accept()` on an optional listener; never completes when there is none, so it
+/// can sit in a `select!` arm unconditionally.
+async fn accept_optional(
+    listener: Option<&TcpListener>,
+) -> std::io::Result<(TcpStream, SocketAddr)> {
+    match listener {
+        Some(l) => l.accept().await,
+        None => std::future::pending().await,
+    }
+}
+
+/// Carry one accepted host connection into the container over `socat`, after
+/// deciding it is not a web page reaching into loopback.
+///
+/// Nothing is forwarded until that decision is made, so a refused request never
+/// reaches the container at all — not even a `docker exec`.
+async fn tunnel_connection(container_id: String, target: String, mut stream: TcpStream, port: u16) {
+    let head = match read_leading_bytes(&mut stream).await {
+        Ok(head) => head,
+        Err(e) => {
+            log::debug!(
+                "Auth bridge: dropping connection to bridged port {} before forwarding: {}",
+                port,
+                e
+            );
+            return;
+        }
+    };
+
+    if let LeadingBytes::HttpRequest { buffer, head_len } = &head {
+        // Authorize against the head slice only. Parsing past the blank line is
+        // how a request *body* gets read as headers — a cross-site `fetch` with
+        // a `text/plain` body is not preflighted, so it can put any line it
+        // likes in there.
+        let head_text = String::from_utf8_lossy(&buffer[..*head_len]);
+        if web_request_verdict(&head_text) == Verdict::RefuseCrossSite {
+            log::warn!(
+                "Auth bridge: refused a cross-site sub-resource request to bridged port {} — \
+                 a web page, not a login redirect",
+                port
+            );
+            let _ = refuse(&mut stream).await;
+            return;
+        }
+    }
+
+    // The bytes already off the socket go back on the wire first, byte-exact.
+    tunnel_connection_with_prelude(container_id, target, stream, port, head.into_buffer()).await
+}
+
+/// What the first bytes of an accepted connection turned out to be.
+enum LeadingBytes {
+    /// An HTTP request whose head we have in full. `head_len` is one past the
+    /// blank line; `buffer` may hold pipelined body bytes beyond it.
+    HttpRequest { buffer: Vec<u8>, head_len: usize },
+    /// Not HTTP, or HTTP we gave up on reading. Forwarded verbatim, ungated.
+    Opaque(Vec<u8>),
+}
+
+impl LeadingBytes {
+    fn into_buffer(self) -> Vec<u8> {
+        match self {
+            LeadingBytes::HttpRequest { buffer, .. } => buffer,
+            LeadingBytes::Opaque(buffer) => buffer,
+        }
+    }
+}
+
+/// Read just enough of the connection to classify it, without consuming
+/// anything the caller cannot replay.
+///
+/// Bails out to [`LeadingBytes::Opaque`] the moment the first line proves this
+/// is not HTTP, so a non-HTTP protocol pays one line of latency and no more.
+/// The only hard failure is silence: a client that sends nothing within
+/// [`FIRST_BYTE_TIMEOUT`] is dropped before an exec is spent on it.
+async fn read_leading_bytes(stream: &mut TcpStream) -> Result<LeadingBytes, String> {
+    let mut buf: Vec<u8> = Vec::with_capacity(1024);
+    let mut chunk = [0u8; 1024];
+    let mut deadline = tokio::time::Instant::now() + FIRST_BYTE_TIMEOUT;
+
+    loop {
+        let n = match tokio::time::timeout_at(deadline, stream.read(&mut chunk)).await {
+            Ok(Ok(0)) if buf.is_empty() => {
+                return Err("closed before sending anything".to_string())
+            }
+            // A half-close after some bytes is legitimate; forward what we have.
+            Ok(Ok(0)) => return Ok(LeadingBytes::Opaque(buf)),
+            Ok(Ok(n)) => n,
+            Ok(Err(e)) => return Err(format!("read failed: {}", e)),
+            Err(_) if buf.is_empty() => {
+                return Err(format!(
+                    "sent nothing within {}s",
+                    FIRST_BYTE_TIMEOUT.as_secs()
+                ))
+            }
+            // Bytes arrived but the head never finished. Fail open: this is a
+            // gate on top of the bridge, not the bridge's reason to exist.
+            Err(_) => return Ok(LeadingBytes::Opaque(buf)),
+        };
+        buf.extend_from_slice(&chunk[..n]);
+
+        // Once the first line is complete we know whether to keep reading.
+        if let Some(eol) = buf.iter().position(|b| *b == b'\n') {
+            if !is_http_request_line(&buf[..eol]) {
+                return Ok(LeadingBytes::Opaque(buf));
+            }
+            deadline = deadline.max(tokio::time::Instant::now() + HEAD_TIMEOUT);
+        } else if buf.len() > MAX_HEAD {
+            return Ok(LeadingBytes::Opaque(buf));
+        }
+
+        if let Some(head_len) = find_head_end(&buf) {
+            return Ok(LeadingBytes::HttpRequest {
+                buffer: buf,
+                head_len,
+            });
+        }
+        if buf.len() > MAX_HEAD {
+            return Ok(LeadingBytes::Opaque(buf));
+        }
+    }
+}
+
+/// Whether a first line looks like `METHOD target HTTP/1.x`.
+fn is_http_request_line(line: &[u8]) -> bool {
+    let line = String::from_utf8_lossy(line);
+    let line = line.trim_end_matches(['\r', '\n']);
+    let mut parts = line.split(' ');
+    let (Some(method), Some(target), Some(version), None) =
+        (parts.next(), parts.next(), parts.next(), parts.next())
+    else {
+        return false;
+    };
+    !method.is_empty()
+        && method.chars().all(|c| c.is_ascii_uppercase())
+        && !target.is_empty()
+        && (version == "HTTP/1.1" || version == "HTTP/1.0")
+}
+
+/// Index just past the blank line terminating an HTTP head, if it has arrived.
+/// Tolerates a bare-LF terminator, which some minimal clients still emit.
+fn find_head_end(buf: &[u8]) -> Option<usize> {
+    buf.windows(4)
+        .position(|w| w == b"\r\n\r\n")
+        .map(|i| i + 4)
+        .or_else(|| buf.windows(2).position(|w| w == b"\n\n").map(|i| i + 2))
+}
+
+/// Tell a refused caller why, then close. Plain text and `Connection: close` —
+/// there is no session here to keep alive.
+async fn refuse(stream: &mut TcpStream) -> std::io::Result<()> {
+    const BODY: &str = "This port is bridged from a container by Triple-C for a sign-in \
+                        callback. It is not an API for web pages to call.\n";
+    let response = format!(
+        "HTTP/1.1 403 Forbidden\r\n\
+         Content-Type: text/plain; charset=utf-8\r\n\
+         Content-Length: {}\r\n\
+         Cache-Control: no-store\r\n\
+         Connection: close\r\n\r\n{}",
+        BODY.len(),
+        BODY
+    );
+    stream.write_all(response.as_bytes()).await?;
+    stream.shutdown().await
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The gate — pure, so it can be tested without sockets
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum Verdict {
+    /// Forward it. Either it is not a browser, or the browser says this is a
+    /// navigation or a same-origin request.
+    Allow,
+    /// Fetch metadata says a document on another site pulled this in as a
+    /// sub-resource. No login flow looks like that.
+    RefuseCrossSite,
+}
+
+/// Decide whether an HTTP request head arriving on a bridged port may be
+/// forwarded into the container.
+///
+/// Deliberately fail-open — see the module docs for exactly what that leaves
+/// uncovered. The only refusal is the case with no innocent reading:
+/// `Sec-Fetch-Site` says another site, and `Sec-Fetch-Mode` says this is not a
+/// navigation. `Sec-Fetch-*` are forbidden header names, so page script cannot
+/// set or clear them.
+pub(crate) fn web_request_verdict(head: &str) -> Verdict {
+    let mut lines = head.split(['\r', '\n']).filter(|l| !l.is_empty());
+    // Skip the request line.
+    if lines.next().is_none() {
+        return Verdict::Allow;
+    }
+
+    let mut site: Option<&str> = None;
+    let mut mode: Option<&str> = None;
+    for line in lines {
+        let Some((name, value)) = line.split_once(':') else {
+            continue;
+        };
+        let value = value.trim();
+        match name.trim().to_ascii_lowercase().as_str() {
+            // A duplicate of either header is header smuggling, not a client.
+            // Refuse rather than pick a winner: last-occurrence-wins is what
+            // turns a smuggling primitive into a bypass.
+            "sec-fetch-site" if site.is_some() => return Verdict::RefuseCrossSite,
+            "sec-fetch-mode" if mode.is_some() => return Verdict::RefuseCrossSite,
+            "sec-fetch-site" => site = Some(value),
+            "sec-fetch-mode" => mode = Some(value),
+            _ => {}
+        }
+    }
+
+    let Some(site) = site else {
+        // No fetch metadata: a CLI, `curl`, or a browser old enough not to send
+        // it. Not something this gate can judge.
+        return Verdict::Allow;
+    };
+    if site.eq_ignore_ascii_case("same-origin") || site.eq_ignore_ascii_case("none") {
+        return Verdict::Allow;
+    }
+    // `navigate` is precisely the OAuth redirect: the provider sends the browser
+    // to `http://localhost:<port>/callback`, cross-site, as a document load.
+    // Refusing it would refuse the feature.
+    if mode.is_none_or(|m| m.eq_ignore_ascii_case("navigate")) {
+        return Verdict::Allow;
+    }
+    Verdict::RefuseCrossSite
+}
+
+/// As [`tunnel_connection`], but `prelude` is written into the container first,
+/// ahead of anything further read from `stream`.
+///
+/// This exists for callers that must *inspect* the beginning of a connection
+/// before deciding to forward it — the browser-view proxy reads the HTTP request
+/// head off the socket to check a token, and then has to put those same bytes
+/// back on the wire. Passing them here keeps the byte stream exact, rather than
+/// re-serialising a parsed request.
+pub async fn tunnel_connection_with_prelude(
+    container_id: String,
+    target: String,
+    stream: TcpStream,
+    port: u16,
+    prelude: Vec<u8>,
+) {
+    let cmd = vec!["socat".to_string(), "-".to_string(), target.clone()];
+
+    let AttachedExec {
+        mut output,
+        mut input,
+        ..
+    } = match create_attached_exec(&container_id, cmd, false).await {
+        Ok(e) => e,
+        Err(e) => {
+            log::warn!(
+                "Auth bridge: failed to open tunnel exec for port {} ({}): {}",
+                port,
+                target,
+                e
+            );
+            return;
+        }
+    };
+
+    let (mut host_rx, mut host_tx) = stream.into_split();
+
+    // Host → container. Runs as its own task so the container→host direction is
+    // never blocked behind a client that has stopped sending. Finishing this
+    // direction drops `input`, which closes the exec's stdin and lets socat see
+    // a clean EOF (a half-close, not a teardown of the whole connection).
+    let upstream = AbortOnDrop(tokio::spawn(async move {
+        // Bytes the caller already consumed from the socket go first, so the
+        // container sees the connection exactly as the client sent it.
+        if !prelude.is_empty()
+            && (input.write_all(&prelude).await.is_err() || input.flush().await.is_err())
+        {
+            return;
+        }
+        let mut buf = vec![0u8; PUMP_BUF];
+        loop {
+            // Idle-bounded. Without this a client that connects, sends a
+            // request and then never speaks or closes holds the exec open for
+            // as long as the container runs.
+            match tokio::time::timeout(IDLE_TIMEOUT, host_rx.read(&mut buf)).await {
+                Ok(Ok(0)) | Err(_) => break,
+                Ok(Ok(n)) => {
+                    if input.write_all(&buf[..n]).await.is_err() || input.flush().await.is_err() {
+                        break;
+                    }
+                }
+                Ok(Err(_)) => break,
+            }
+        }
+    }));
+
+    // Container → host. This direction is authoritative: when the exec's output
+    // stream ends, socat has exited and the connection is over. It is also the
+    // one that decides the connection is dead: nothing back from the container
+    // for `IDLE_TIMEOUT` tears the whole thing down, exec included.
+    while let Some(chunk) = match tokio::time::timeout(IDLE_TIMEOUT, output.next()).await {
+        Ok(chunk) => chunk,
+        Err(_) => {
+            log::debug!(
+                "Auth bridge: bridged port {} idle for {}s — closing the tunnel",
+                port,
+                IDLE_TIMEOUT.as_secs()
+            );
+            None
+        }
+    } {
+        match chunk {
+            // Only stdout is payload. The exec is created with tty = false
+            // precisely so Docker demultiplexes these, keeping socat's stderr
+            // diagnostics out of the proxied byte stream.
+            Ok(LogOutput::StdOut { message }) => {
+                if host_tx.write_all(&message).await.is_err() {
+                    break;
+                }
+            }
+            Ok(LogOutput::StdErr { message }) => {
+                log::debug!(
+                    "Auth bridge: socat stderr for port {}: {}",
+                    port,
+                    String::from_utf8_lossy(&message).trim()
+                );
+            }
+            Ok(_) => {}
+            Err(e) => {
+                log::debug!("Auth bridge: tunnel stream error on port {}: {}", port, e);
+                break;
+            }
+        }
+    }
+
+    let _ = host_tx.shutdown().await;
+    // Explicit: stop reading from the host now that the container side is gone.
+    drop(upstream);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn head(lines: &[&str]) -> String {
+        format!("{}\r\n\r\n", lines.join("\r\n"))
+    }
+
+    #[test]
+    fn a_cli_callback_with_no_fetch_metadata_is_forwarded() {
+        // The overwhelmingly common case, and the reason the gate fails open:
+        // `curl`, a CLI's own probe, and anything not a browser send none of
+        // these headers, and none of them can be judged from the wire.
+        let verdict = web_request_verdict(&head(&[
+            "GET /callback?code=abc HTTP/1.1",
+            "Host: localhost:41733",
+            "User-Agent: curl/8.5.0",
+        ]));
+        assert_eq!(verdict, Verdict::Allow);
+    }
+
+    #[test]
+    fn the_oauth_redirect_is_forwarded_even_though_it_is_cross_site() {
+        // This is the feature. The provider bounces the browser to
+        // `http://localhost:<port>/callback`, which is cross-site and a
+        // navigation. Refusing it would refuse every login the bridge exists
+        // for.
+        for site in ["cross-site", "same-site"] {
+            let verdict = web_request_verdict(&head(&[
+                "GET /callback?code=abc&state=xyz HTTP/1.1",
+                "Host: localhost:41733",
+                &format!("Sec-Fetch-Site: {}", site),
+                "Sec-Fetch-Mode: navigate",
+                "Sec-Fetch-Dest: document",
+            ]));
+            assert_eq!(verdict, Verdict::Allow, "site={}", site);
+        }
+    }
+
+    #[test]
+    fn a_form_post_callback_is_forwarded() {
+        // `response_mode=form_post` providers POST the callback as a
+        // navigation. Still a navigation, still allowed.
+        let verdict = web_request_verdict(&head(&[
+            "POST /callback HTTP/1.1",
+            "Host: localhost:41733",
+            "Origin: https://login.microsoftonline.com",
+            "Sec-Fetch-Site: cross-site",
+            "Sec-Fetch-Mode: navigate",
+        ]));
+        assert_eq!(verdict, Verdict::Allow);
+    }
+
+    #[test]
+    fn a_cross_site_subresource_from_a_web_page_is_refused() {
+        // The case the gate exists for: a page the user happens to have open
+        // scanning loopback and poking whatever answers.
+        for mode in ["cors", "no-cors", "same-origin", "websocket"] {
+            let verdict = web_request_verdict(&head(&[
+                "GET /admin HTTP/1.1",
+                "Host: 127.0.0.1:41733",
+                "Origin: https://evil.example",
+                "Sec-Fetch-Site: cross-site",
+                &format!("Sec-Fetch-Mode: {}", mode),
+            ]));
+            assert_eq!(verdict, Verdict::RefuseCrossSite, "mode={}", mode);
+        }
+    }
+
+    #[test]
+    fn the_containers_own_same_origin_requests_are_forwarded() {
+        let verdict = web_request_verdict(&head(&[
+            "GET /style.css HTTP/1.1",
+            "Host: localhost:41733",
+            "Sec-Fetch-Site: same-origin",
+            "Sec-Fetch-Mode: no-cors",
+        ]));
+        assert_eq!(verdict, Verdict::Allow);
+        // `none` is a user-initiated load — typed URL, bookmark.
+        let verdict = web_request_verdict(&head(&[
+            "GET / HTTP/1.1",
+            "Host: localhost:41733",
+            "Sec-Fetch-Site: none",
+            "Sec-Fetch-Mode: navigate",
+        ]));
+        assert_eq!(verdict, Verdict::Allow);
+    }
+
+    #[test]
+    fn duplicated_fetch_metadata_is_refused_rather_than_resolved() {
+        // Last-occurrence-wins is what turns any header-smuggling primitive
+        // into a bypass, and no real client sends two.
+        let verdict = web_request_verdict(&head(&[
+            "GET /x HTTP/1.1",
+            "Sec-Fetch-Site: cross-site",
+            "Sec-Fetch-Mode: cors",
+            "Sec-Fetch-Site: same-origin",
+        ]));
+        assert_eq!(verdict, Verdict::RefuseCrossSite);
+    }
+
+    #[test]
+    fn only_the_head_is_ever_judged() {
+        // A cross-site `text/plain` POST is not preflighted, so its *body* is
+        // fully attacker-chosen. `tunnel_connection` slices at the blank line
+        // before calling in; this pins that the slice is what gets judged.
+        let raw = "POST /x HTTP/1.1\r\n\
+                   Sec-Fetch-Site: cross-site\r\n\
+                   Sec-Fetch-Mode: cors\r\n\
+                   Content-Type: text/plain\r\n\r\n\
+                   Sec-Fetch-Site: same-origin\r\n";
+        let head_len = find_head_end(raw.as_bytes()).expect("head terminator");
+        let head = &raw[..head_len];
+        assert!(!head.contains("same-origin"), "the forged line must be past the slice");
+        assert_eq!(web_request_verdict(head), Verdict::RefuseCrossSite);
+
+        // And if the slice were ever got wrong, the duplicate rule is the
+        // backstop: a forged `Sec-Fetch-*` line is by construction a second
+        // copy of one the browser already sent, which is refused outright
+        // rather than resolved in the forgery's favour.
+        assert_eq!(web_request_verdict(raw), Verdict::RefuseCrossSite);
+    }
+
+    #[test]
+    fn a_non_http_first_line_is_never_treated_as_a_request() {
+        // Bridged ports are not all HTTP. Anything whose first line is not a
+        // request line is forwarded verbatim rather than parsed.
+        assert!(!is_http_request_line(b"\x16\x03\x01\x02\x00\x01"));
+        assert!(!is_http_request_line(b"*1\r"));
+        assert!(!is_http_request_line(b"SSH-2.0-OpenSSH_9.6"));
+        assert!(!is_http_request_line(b"GET /x HTTP/2.0"));
+        assert!(!is_http_request_line(b"get /x HTTP/1.1"));
+        assert!(is_http_request_line(b"GET /x HTTP/1.1\r"));
+        assert!(is_http_request_line(b"POST /callback?code=a%20b HTTP/1.0"));
+    }
+
+    #[test]
+    fn head_end_is_found_for_both_terminators() {
+        assert_eq!(find_head_end(b"GET / HTTP/1.1\r\n\r\nBODY"), Some(18));
+        assert_eq!(find_head_end(b"GET / HTTP/1.1\n\nBODY"), Some(16));
+        assert_eq!(find_head_end(b"GET / HTTP/1.1\r\nHost: x\r\n"), None);
+    }
+
+    #[tokio::test]
+    async fn a_client_that_says_nothing_never_costs_a_container_exec() {
+        // Every accepted connection would otherwise spawn a `docker exec`
+        // immediately, so silence was free for the caller and expensive here.
+        let listener = TcpListener::bind(SocketAddr::from((Ipv4Addr::LOCALHOST, 0)))
+            .await
+            .expect("bind");
+        let addr = listener.local_addr().expect("addr");
+        let accept = tokio::spawn(async move {
+            let (mut stream, _) = listener.accept().await.expect("accept");
+            read_leading_bytes(&mut stream).await
+        });
+
+        let _client = TcpStream::connect(addr).await.expect("connect");
+        let started = tokio::time::Instant::now();
+        let result = accept.await.expect("join");
+
+        assert!(result.is_err(), "silence should not be forwarded");
+        assert!(
+            started.elapsed() >= FIRST_BYTE_TIMEOUT,
+            "should have waited out the first-byte grace period"
+        );
+    }
+
+    #[tokio::test]
+    async fn a_non_http_client_is_classified_from_its_first_line_alone() {
+        let listener = TcpListener::bind(SocketAddr::from((Ipv4Addr::LOCALHOST, 0)))
+            .await
+            .expect("bind");
+        let addr = listener.local_addr().expect("addr");
+        let accept = tokio::spawn(async move {
+            let (mut stream, _) = listener.accept().await.expect("accept");
+            read_leading_bytes(&mut stream).await
+        });
+
+        let mut client = TcpStream::connect(addr).await.expect("connect");
+        client.write_all(b"SSH-2.0-OpenSSH_9.6\r\n").await.expect("write");
+
+        let result = accept.await.expect("join").expect("classified");
+        // Verbatim, and without waiting for a head terminator that will never
+        // come — the whole buffer is replayed into the tunnel.
+        assert!(matches!(result, LeadingBytes::Opaque(_)));
+        assert_eq!(result.into_buffer(), b"SSH-2.0-OpenSSH_9.6\r\n");
+    }
+
+    #[tokio::test]
+    async fn an_http_head_is_read_whole_and_replayed_whole() {
+        let listener = TcpListener::bind(SocketAddr::from((Ipv4Addr::LOCALHOST, 0)))
+            .await
+            .expect("bind");
+        let addr = listener.local_addr().expect("addr");
+        let accept = tokio::spawn(async move {
+            let (mut stream, _) = listener.accept().await.expect("accept");
+            read_leading_bytes(&mut stream).await
+        });
+
+        let raw = b"POST /callback HTTP/1.1\r\nHost: localhost\r\nContent-Length: 4\r\n\r\ncode";
+        let mut client = TcpStream::connect(addr).await.expect("connect");
+        client.write_all(raw).await.expect("write");
+
+        let result = accept.await.expect("join").expect("classified");
+        match &result {
+            LeadingBytes::HttpRequest { buffer, head_len } => {
+                assert_eq!(&buffer[*head_len..], b"code", "body must survive the peek");
+                assert!(!buffer[..*head_len].ends_with(b"code"));
+            }
+            LeadingBytes::Opaque(_) => panic!("should have been recognised as HTTP"),
+        }
+        assert_eq!(result.into_buffer(), raw.to_vec());
+    }
+}

app/src-tauri/src/browser_view/commands.rs

@@ -0,0 +1,346 @@
+//! IPC surface for the browser view pane. The mechanism lives in
+//! [`crate::browser_view`]; this file only translates between it and the
+//! frontend.
+
+use tauri::{AppHandle, State};
+
+use crate::browser_view::install::{self, BrowserSetupOutcome};
+use crate::browser_view::{manager, page, popout, BrowserViewState, BrowserViewStatus};
+use crate::AppState;
+
+/// Turn the pane on or off for a project.
+///
+/// Enabling probes the container and brings the viewer up when it can; a
+/// container that isn't running, or one without Playwright, comes back as a
+/// non-`Running` status carrying an explanation rather than an error, so the
+/// pane always has something specific to say. This is host-side only — no
+/// container recreation is involved either way.
+#[tauri::command]
+pub async fn set_browser_view_enabled(
+    project_id: String,
+    enabled: bool,
+    app_handle: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<BrowserViewStatus, String> {
+    if !enabled {
+        // Awaits the supervisor, so the host port is released before we return.
+        manager().stop(&project_id).await;
+        return Ok(manager().status(&project_id).await);
+    }
+
+    let container_id = running_container(&state, &project_id, "opening the browser view").await?;
+
+    manager()
+        .start(
+            project_id,
+            container_id,
+            app_handle,
+            state.projects_store.clone(),
+        )
+        .await
+}
+
+/// Current status. Cheap: reads in-process state only, never the container.
+#[tauri::command]
+pub async fn get_browser_view_status(project_id: String) -> Result<BrowserViewStatus, String> {
+    Ok(manager().status(&project_id).await)
+}
+
+/// Probe the container for Playwright without starting anything.
+///
+/// Lets the pane say "install this" before the user asks for a view, and lets
+/// them re-check after installing without toggling the feature. Read-only: it
+/// runs one `node -e` and changes nothing.
+#[tauri::command]
+pub async fn check_browser_view_support(
+    project_id: String,
+    state: State<'_, AppState>,
+) -> Result<crate::browser_view::detect::PlaywrightDetection, String> {
+    let container_id = running_container(&state, &project_id, "checking for Playwright").await?;
+    crate::browser_view::detect::detect(&container_id).await
+}
+
+/// Install `playwright` and `@playwright/cli` into the container.
+///
+/// **This mutates the container**, so it is a command of its own and is only
+/// ever reached by the user pressing the button — nothing here runs on tab
+/// open. Progress streams on `container-progress`; the outcome carries a fresh
+/// probe so the pane updates itself.
+///
+/// Browsers are *not* fetched here. They are hundreds of megabytes and get
+/// their own action, with the size stated before the click.
+#[tauri::command]
+pub async fn install_browser_view_support(
+    project_id: String,
+    app_handle: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<BrowserSetupOutcome, String> {
+    let container_id = running_container(&state, &project_id, "installing Playwright").await?;
+    install::install_packages(&app_handle, &project_id, &container_id).await
+}
+
+/// Install a browser — `chromium` (Playwright's own build, for scripts that
+/// call `chromium.launch()`) or `chrome` (the Google Chrome channel that
+/// `@playwright/mcp` asks for) — along with the system libraries it needs, and
+/// verify that it actually starts.
+///
+/// Also a mutation, also user-initiated only.
+#[tauri::command]
+pub async fn install_browser_view_browser(
+    project_id: String,
+    browser: String,
+    app_handle: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<BrowserSetupOutcome, String> {
+    let target = install::BrowserTarget::parse(&browser)?;
+    let container_id = running_container(&state, &project_id, "installing a browser").await?;
+    install::install_browser(&app_handle, &project_id, &container_id, target).await
+}
+
+/// Detach the view into a window of its own, or raise the one already open.
+///
+/// Host-side and window-only: the viewer keeps running exactly as it was, and
+/// this touches neither the container nor the proxy. Requires a *live* view,
+/// because a window with nothing behind it is not worth opening — the pane
+/// only offers the button in that state, and this enforces it.
+#[tauri::command]
+pub async fn open_browser_view_popout(
+    project_id: String,
+    always_on_top: bool,
+    app_handle: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let status = manager().status(&project_id).await;
+    let (BrowserViewState::Running, Some(url)) = (status.state, status.url.as_deref()) else {
+        return Err(
+            "The browser view isn't running. Start it before opening it in its own window."
+                .to_string(),
+        );
+    };
+
+    let name = state
+        .projects_store
+        .get(&project_id)
+        .map(|p| p.name)
+        .unwrap_or_else(|| "Triple-C".to_string());
+
+    popout::open(&app_handle, &project_id, &name, url, always_on_top)
+}
+
+/// Close the pop-out, putting the view back in the tab. No-op if it is closed.
+///
+/// Propagates a failed close rather than reporting success: the pane restores
+/// its iframe on success, and doing that with the window still up puts two
+/// viewers on one browser.
+#[tauri::command]
+pub async fn close_browser_view_popout(
+    project_id: String,
+    app_handle: AppHandle,
+) -> Result<(), String> {
+    popout::close(&app_handle, &project_id)
+}
+
+/// Whether the pop-out is open, and whether it is pinned on top.
+///
+/// Read on every pane mount: the window outlives the pane — which is unmounted
+/// whenever another Project Home sub-tab is selected — so neither fact can be
+/// carried in component state.
+#[tauri::command]
+pub async fn get_browser_view_popout_state(
+    project_id: String,
+    app_handle: AppHandle,
+) -> Result<popout::PopoutState, String> {
+    Ok(popout::state(&app_handle, &project_id))
+}
+
+/// Pin the pop-out above other windows, so it can be watched while working in
+/// the main one.
+#[tauri::command]
+pub async fn set_browser_view_popout_always_on_top(
+    project_id: String,
+    on_top: bool,
+    app_handle: AppHandle,
+) -> Result<(), String> {
+    popout::set_always_on_top(&app_handle, &project_id, on_top)
+}
+
+/// Open a URL in a browser *inside* the container, published so the pane shows
+/// it.
+///
+/// Two uses, one action: an auth URL — where the OAuth callback listener is in
+/// the container too, so the loop closes without the host being involved at all
+/// — and a dev server on container loopback, which is how you watch a UI Claude
+/// is building.
+///
+/// The scheme allow-list mirrors the URL relay's: `http`/`https` only, so this
+/// can never be talked into opening `file:` on the container's filesystem.
+#[tauri::command]
+pub async fn open_page_in_container_browser(
+    project_id: String,
+    url: String,
+    width: u32,
+    height: u32,
+    show_window: bool,
+    app_handle: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<page::PageState, String> {
+    let trimmed = url.trim();
+    if !(trimmed.starts_with("http://") || trimmed.starts_with("https://")) {
+        return Err("Only http:// and https:// URLs can be opened in the browser.".to_string());
+    }
+    let container_id = running_container(&state, &project_id, "opening a page").await?;
+    crate::commands::project_commands::emit_progress(
+        &app_handle,
+        &project_id,
+        "Checking the container for Playwright…",
+    );
+    let detection = crate::browser_view::detect::detect(&container_id).await?;
+    let opened = page::open(
+        &app_handle,
+        &project_id,
+        &container_id,
+        &detection,
+        trimmed,
+        page::Viewport::sane(width, height),
+    )
+    .await?;
+
+    // A page nobody can see is not an opened page. Opening one used to leave
+    // the user to go and press Start in the Browser tab themselves — and from
+    // the terminal's URL prompt, with no indication that was even needed.
+    // Asking for a page *is* asking to watch it, so the viewer comes up too.
+    let status = manager().status(&project_id).await;
+    if status.state != BrowserViewState::Running {
+        crate::commands::project_commands::emit_progress(
+            &app_handle,
+            &project_id,
+            "Starting the viewer…",
+        );
+        manager()
+            .start(
+                project_id.clone(),
+                container_id,
+                app_handle.clone(),
+                state.projects_store.clone(),
+            )
+            .await?;
+    }
+
+    // From the terminal there is no pane on screen to fill, so the page needs a
+    // window of its own or it lands somewhere the user isn't looking.
+    if show_window {
+        let status = manager().status(&project_id).await;
+        if let Some(url) = status.url.as_deref() {
+            let name = state
+                .projects_store
+                .get(&project_id)
+                .map(|p| p.name)
+                .unwrap_or_else(|| "Triple-C".to_string());
+            popout::open(&app_handle, &project_id, &name, url, false)?;
+        }
+    }
+
+    crate::commands::project_commands::emit_progress(&app_handle, &project_id, "");
+    Ok(opened)
+}
+
+/// Resize the page this opened. The pop-out's "match window" mode calls this on
+/// every settled resize, so it is deliberately cheap: one control-file write.
+#[tauri::command]
+pub async fn set_container_page_viewport(
+    project_id: String,
+    width: u32,
+    height: u32,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let container_id = running_container(&state, &project_id, "resizing the page").await?;
+    page::set_viewport(&container_id, page::Viewport::sane(width, height)).await
+}
+
+/// State of the page this opened, if any. Never fails: "no page" is an answer.
+#[tauri::command]
+pub async fn get_container_page_state(
+    project_id: String,
+    state: State<'_, AppState>,
+) -> Result<page::PageState, String> {
+    let Ok(container_id) = running_container(&state, &project_id, "reading the page").await else {
+        return Ok(page::PageState::default());
+    };
+    Ok(page::state(&container_id).await)
+}
+
+/// Close the page this opened, leaving the view itself running.
+#[tauri::command]
+pub async fn close_container_page(
+    project_id: String,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let container_id = running_container(&state, &project_id, "closing the page").await?;
+    page::close(&container_id).await;
+    Ok(())
+}
+
+/// Make the page track the pop-out window's size as it is dragged.
+///
+/// Only affects a page **this app opened**: a bound browser admits no second
+/// client, so one `@playwright/mcp` launched keeps the viewport it was given.
+/// Turning it on applies the window's current size immediately, so the toggle
+/// has a visible effect without waiting for a drag.
+#[tauri::command]
+pub async fn set_browser_view_match_window(
+    project_id: String,
+    enabled: bool,
+    app_handle: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    popout::set_match_window(&project_id, enabled);
+    if !enabled {
+        return Ok(());
+    }
+    let Some((width, height)) = popout::inner_size(&app_handle, &project_id) else {
+        return Ok(());
+    };
+    let container_id = running_container(&state, &project_id, "matching the window").await?;
+    page::set_viewport(&container_id, page::Viewport::sane(width, height)).await
+}
+
+/// Whether match-window mode is on. Read on mount, like the rest of the
+/// pop-out's state — the pane is unmounted whenever another sub-tab is shown.
+#[tauri::command]
+pub async fn get_browser_view_match_window(project_id: String) -> Result<bool, String> {
+    Ok(popout::match_window(&project_id))
+}
+
+/// The project's container, or a sentence saying why there isn't one.
+///
+/// Every command here needs a *running* container, and every one of them used
+/// to be able to fail somewhere further in with a Docker error instead. The
+/// `action` is folded into the message so "start the container first" arrives
+/// attached to what the user was trying to do.
+async fn running_container(
+    state: &State<'_, AppState>,
+    project_id: &str,
+    action: &str,
+) -> Result<String, String> {
+    let project = state
+        .projects_store
+        .get(project_id)
+        .ok_or_else(|| format!("Project {} not found", project_id))?;
+
+    let Some(container_id) = project.container_id.clone() else {
+        return Err(format!(
+            "This project has no container yet. Start it before {}.",
+            action
+        ));
+    };
+    if !crate::docker::container::is_container_running(&container_id)
+        .await
+        .unwrap_or(false)
+    {
+        return Err(format!(
+            "The container for “{}” isn't running. Start it before {}.",
+            project.name, action
+        ));
+    }
+    Ok(container_id)
+}

app/src-tauri/src/browser_view/detect.rs

@@ -0,0 +1,698 @@
+//! Is there anything in this container worth watching, and can we serve a viewer
+//! for it?
+//!
+//! Playwright is **not** in the container image — it is installed by the user or
+//! by Claude, into whichever `node_modules` happens to be in scope. So detection
+//! has to be done inside the container, at the moment the pane is opened, and it
+//! has to produce an *actionable* answer when the pieces are missing: the pane's
+//! one unforgivable failure mode would be an unexplained spinner.
+//!
+//! Three things must line up:
+//!
+//! 1. **`playwright-core`** (directly, or via `playwright`, which re-exports it),
+//! 2. at a version whose `Browser` exposes **`bind()`** — the live-dashboard API
+//!    that publishes a browser for a viewer to attach to, and
+//! 3. **`@playwright/cli`**, which ships the viewer UI itself.
+//!
+//! Discovery of published browsers is local-filesystem based (a cache directory
+//! plus a unix-socket singleton in the temp dir), which is exactly why the viewer
+//! has to run *in the container* next to the browsers rather than on the host.
+//!
+//! ## Where a Playwright can legitimately be
+//!
+//! `node_modules` is not the only answer, and assuming it was is what made this
+//! probe lie. `claude mcp add … npx @playwright/mcp@latest` — the way most
+//! people end up with Playwright in the container — installs nothing into any
+//! `node_modules`: npx unpacks the tree into `~/.npm/_npx/<hash>/node_modules`
+//! and runs it from there. So that cache is searched too, every entry of it,
+//! and [`PlaywrightDetection::searched`] echoes back every root actually
+//! consulted so a "not found" is checkable rather than merely asserted.
+//!
+//! Note what that npx route can and cannot do: `@playwright/mcp` bundles a
+//! `playwright-core` new enough to `bind()`, so it can satisfy points 1 and 2 —
+//! but it never ships `@playwright/cli`, so it can never satisfy point 3 on its
+//! own. Any message that offers it as a way to *set up* this pane is sending
+//! the user down a dead end; see [`PlaywrightDetection::blocker`].
+
+use serde::{Deserialize, Serialize};
+
+use crate::docker::exec::exec_oneshot;
+
+/// Marks the JSON payload in the probe's stdout, so unrelated chatter on the
+/// same stream (npm notices, Node warnings) can't be mistaken for the result.
+const MARKER: &str = "__TRIPLE_C_BROWSER_VIEW__";
+
+/// What the probe found. Serialised straight to the frontend so the pane can
+/// explain itself precisely rather than saying "not available".
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct PlaywrightDetection {
+    /// Node's own version, if `node` ran at all.
+    #[serde(default)]
+    pub node_version: Option<String>,
+    /// Resolved `playwright-core` (or `playwright`) version.
+    #[serde(default)]
+    pub playwright_version: Option<String>,
+    /// Absolute path of the resolved package manifest, for the diagnostics line.
+    #[serde(default)]
+    pub playwright_path: Option<String>,
+    /// Absolute path of the resolved Playwright's own CLI entry (`cli.js`).
+    ///
+    /// Both `playwright` and `playwright-core` declare one, and it is the thing
+    /// that installs browsers and their system libraries. Driving *that* file
+    /// with `node` — rather than whatever `playwright` happens to be on `PATH` —
+    /// is what keeps the browser install pinned to the copy this pane found.
+    #[serde(default)]
+    pub playwright_cli: Option<String>,
+    /// Whether the resolved build's type definitions declare `Browser.bind()`.
+    #[serde(default)]
+    pub has_bind: bool,
+    /// Resolved `@playwright/cli` version — the package that serves the viewer.
+    #[serde(default)]
+    pub cli_version: Option<String>,
+    /// Absolute path of `@playwright/cli`'s entry script. Invoked with `node`
+    /// directly rather than through its bin shim, so the viewer's PID is the one
+    /// we can signal.
+    #[serde(default)]
+    pub cli_entry: Option<String>,
+    /// Browser bundles present in the Playwright browser cache
+    /// (`~/.cache/ms-playwright`), e.g. `chromium-1200`. `ffmpeg-*` is excluded
+    /// — it is not a browser and its presence must not read as one.
+    ///
+    /// Not part of [`PlaywrightDetection::is_usable`]: the viewer serves
+    /// whatever has been published to it, and a browser could in principle be
+    /// remote. It is here because "installed but no browser to drive" is a real
+    /// state the pane has to be able to say out loud.
+    #[serde(default)]
+    pub browsers: Vec<String>,
+    /// Path to Google Chrome, if the `chrome` *channel* is installed.
+    ///
+    /// Separate from [`Self::browsers`] because it is not in Playwright's cache
+    /// at all — the channel is an apt package. It is tracked because
+    /// `@playwright/mcp` asks for `channel: 'chrome'` specifically, so a
+    /// container with the bundled Chromium and no Chrome is set up for the
+    /// user's own scripts and not for the MCP plugin.
+    #[serde(default)]
+    pub chrome_channel: Option<String>,
+    /// The Chromium binary the *resolved* Playwright would launch, asked of the
+    /// build itself rather than derived from the cache listing.
+    #[serde(default)]
+    pub chromium_executable: Option<String>,
+    /// Whether that binary is actually on disk.
+    ///
+    /// False with a non-empty [`Self::browsers`] is the revision-skew case: two
+    /// Playwright copies in one container pin different revisions, so the cache
+    /// can be full of browsers and every launch still fail.
+    #[serde(default)]
+    pub chromium_executable_exists: bool,
+    /// The version a *script's* `require("playwright")` resolves to.
+    ///
+    /// Tracked separately from [`Self::playwright_version`] because they are
+    /// routinely different in one directory: `@playwright/cli` pins its own
+    /// `playwright-core`, npm hoists that, and a separately-installed
+    /// `playwright` then nests a second core beside it. The viewer uses one,
+    /// Claude's scripts use the other.
+    #[serde(default)]
+    pub script_playwright_version: Option<String>,
+    /// The Chromium that copy would launch, and whether it is there. This is
+    /// the pair that decides whether a script Claude writes actually runs.
+    #[serde(default)]
+    pub script_chromium_executable: Option<String>,
+    #[serde(default)]
+    pub script_chromium_executable_exists: bool,
+    /// Where the probe looked, echoed back for the "not found" message.
+    #[serde(default)]
+    pub searched: Vec<String>,
+}
+
+impl PlaywrightDetection {
+    /// Everything needed to actually serve the pane.
+    pub fn is_usable(&self) -> bool {
+        self.playwright_version.is_some() && self.has_bind && self.cli_entry.is_some()
+    }
+
+    /// A specific, actionable explanation of what is missing. `None` when the
+    /// container is ready.
+    ///
+    /// Every branch names the *package* that is missing and points at this
+    /// pane's install action, because assembling npm commands by hand is the
+    /// thing that went wrong for real users. `@playwright/mcp` is named only in
+    /// the role it actually plays — it binds sessions automatically once
+    /// Playwright is present — and never as a route through setup, because it
+    /// does not ship `@playwright/cli` and so can never make the viewer work.
+    pub fn blocker(&self) -> Option<String> {
+        if self.node_version.is_none() {
+            return Some(
+                "Node.js isn't runnable in this container, so Playwright can't be detected."
+                    .to_string(),
+            );
+        }
+        if self.playwright_version.is_none() {
+            return Some(format!(
+                "Playwright isn't installed in this container. Two packages are needed: \
+                 `playwright` (for the `browser.bind()` live-dashboard API) and \
+                 `@playwright/cli` (the viewer UI this pane embeds). Use “Set up Playwright” \
+                 below to install both into the container. Installing `@playwright/mcp` on \
+                 its own is not enough — it binds sessions for you once Playwright is there, \
+                 but it never provides the viewer. Looked in: {}.",
+                self.searched_text()
+            ));
+        }
+        if !self.has_bind {
+            return Some(format!(
+                "Playwright {} is installed{}, but it predates the live-dashboard API \
+                 (`browser.bind()`). Use “Set up Playwright” below to upgrade to the latest \
+                 `playwright`, then restart the browser Claude is driving.",
+                self.playwright_version.as_deref().unwrap_or("?"),
+                match self.playwright_path.as_deref() {
+                    Some(p) => format!(" at {}", p),
+                    None => String::new(),
+                }
+            ));
+        }
+        if self.cli_entry.is_none() {
+            return Some(format!(
+                "Playwright {} is installed, but `@playwright/cli` — the package that serves \
+                 the viewer UI — isn't, and nothing else provides it (`@playwright/mcp` does \
+                 not). Use “Set up Playwright” below to install it. Looked in: {}.",
+                self.playwright_version.as_deref().unwrap_or("?"),
+                self.searched_text()
+            ));
+        }
+        None
+    }
+
+    /// The revision-skew sentence, for the pane's browser step.
+    ///
+    /// Separate from [`Self::blocker`] because it does not block the *viewer* —
+    /// the dashboard runs fine; it is the browser that cannot start. Names both
+    /// halves, because "install a browser" over a cache that visibly already
+    /// has one reads as nonsense without them.
+    pub fn skew_message(&self) -> Option<String> {
+        if !self.revision_skew() {
+            return None;
+        }
+        // Which half is broken changes what the user sees, so say the one that
+        // is. The scripts case is the one that looks like a lie: the pane is
+        // green, the viewer works, and every script Claude writes dies.
+        if self.scripts_cannot_launch() {
+            return Some(format!(
+                "This container has {}, and the viewer works — but `require(\"playwright\")` \
+                 resolves Playwright {}, which launches {}. That file isn't there, so every \
+                 script Claude writes fails with “Executable doesn't exist”. Two copies ended \
+                 up in one tree: `@playwright/cli` pins its own `playwright-core`, and a \
+                 separately-installed `playwright` nests a second one beside it. “Set up \
+                 Playwright” below reinstalls them as one consistent set.",
+                self.browsers.join(", "),
+                self.script_playwright_version.as_deref().unwrap_or("?"),
+                self.script_chromium_executable.as_deref().unwrap_or("?"),
+            ));
+        }
+        Some(format!(
+            "This container has {}, but Playwright {} launches {} — which isn't there, so \
+             every `chromium.launch()` fails with “Executable doesn't exist”. That happens \
+             when two Playwright copies share a container (typically an npx `@playwright/mcp` \
+             alongside this one); each pins its own browser revision. “Install Chromium” below \
+             fetches the revision this build needs — it runs that build's own installer, so it \
+             cannot pick the wrong one again.",
+            self.browsers.join(", "),
+            self.playwright_version.as_deref().unwrap_or("?"),
+            self.chromium_executable.as_deref().unwrap_or("?"),
+        ))
+    }
+
+    /// Whether Playwright is present but has no browser at all to drive —
+    /// neither a downloaded bundle nor the Chrome channel. Advisory: the viewer
+    /// still runs, it just has nothing to show until a browser is bound.
+    pub fn needs_browser(&self) -> bool {
+        self.playwright_version.is_some()
+            && self.chrome_channel.is_none()
+            && (self.browsers.is_empty() || self.revision_skew())
+    }
+
+    /// Browsers are installed, but not the revision this Playwright launches.
+    ///
+    /// The container looks equipped and every `chromium.launch()` fails with
+    /// "Executable doesn't exist". It happens whenever two Playwright copies
+    /// share a container — the npx `@playwright/mcp` one and a `/workspace`
+    /// one — because each pins its own revision and installs into the same
+    /// cache. The install action fixes it: it runs the *resolved* build's own
+    /// CLI, so it fetches exactly the revision that was missing.
+    ///
+    /// Requires the probe to have answered: an older container image, or a
+    /// Playwright too broken to `require`, leaves `chromium_executable` unset,
+    /// and "didn't answer" must not read as "skewed".
+    pub fn revision_skew(&self) -> bool {
+        !self.browsers.is_empty() && (self.viewer_cannot_launch() || self.scripts_cannot_launch())
+    }
+
+    /// The copy serving the viewer would not find its browser.
+    fn viewer_cannot_launch(&self) -> bool {
+        self.chromium_executable.is_some() && !self.chromium_executable_exists
+    }
+
+    /// `require("playwright")` — what every script Claude writes uses — would
+    /// not find its browser. Independent of the above, and the more common of
+    /// the two: `@playwright/cli` pins a `playwright-core`, npm hoists it, and
+    /// a separately-installed `playwright` nests a second one that no browser
+    /// was ever downloaded for.
+    fn scripts_cannot_launch(&self) -> bool {
+        self.script_chromium_executable.is_some() && !self.script_chromium_executable_exists
+    }
+
+    /// The searched roots as prose, so a message never trails off into "Looked
+    /// in: ." when the probe couldn't build a root list at all.
+    fn searched_text(&self) -> String {
+        if self.searched.is_empty() {
+            "the container's default module paths".to_string()
+        } else {
+            self.searched.join(", ")
+        }
+    }
+}
+
+/// One `node -e` probe, run as `claude` inside the container.
+///
+/// No shell quoting is involved: the script is a single `argv` element. The
+/// script finds the global `node_modules` root and the npx cache itself, so a
+/// Playwright installed with `npm i -g`, or merely *run* once through
+/// `npx @playwright/mcp`, is found as readily as one in
+/// `/workspace/node_modules`.
+pub async fn detect(container_id: &str) -> Result<PlaywrightDetection, String> {
+    let output = exec_oneshot(
+        container_id,
+        vec!["node".to_string(), "-e".to_string(), PROBE.to_string()],
+    )
+    .await?;
+
+    parse_probe_output(&output)
+}
+
+/// Pull the marked JSON object out of the probe's combined output.
+///
+/// `exec_oneshot` interleaves stdout and stderr, and Node happily writes
+/// deprecation warnings to the latter, so the payload is located by marker
+/// rather than by assuming it is the whole stream.
+pub(crate) fn parse_probe_output(output: &str) -> Result<PlaywrightDetection, String> {
+    let start = output.find(MARKER).ok_or_else(|| {
+        let trimmed = output.trim();
+        if trimmed.is_empty() {
+            "Playwright detection produced no output. Is Node.js present in the container?"
+                .to_string()
+        } else {
+            format!(
+                "Playwright detection failed: {}",
+                trimmed.lines().next_back().unwrap_or(trimmed)
+            )
+        }
+    })? + MARKER.len();
+
+    // The payload runs to the end of that line; anything the probe's own
+    // children wrote afterwards is not ours.
+    let json = output[start..].lines().next().unwrap_or("").trim();
+    serde_json::from_str(json)
+        .map_err(|e| format!("Could not read the Playwright detection result: {}", e))
+}
+
+/// The probe. Kept as one string so the quoting story is "there isn't one".
+///
+/// Deliberately tolerant: every lookup is individually guarded, because a
+/// half-installed `node_modules` must produce a *partial* answer that
+/// [`PlaywrightDetection::blocker`] can turn into advice, not an exception that
+/// produces "detection failed".
+const PROBE: &str = concat!(
+    r#"const fs=require("fs"),path=require("path"),cp=require("child_process");"#,
+    r#"const out={node_version:process.versions.node,searched:[],has_bind:false,browsers:[]};"#,
+    // `npm root -g` is the only reliable way to learn the global prefix, and it
+    // is cheap enough to pay for once per pane open.
+    r#"let g=null;try{g=cp.execSync("npm root -g",{encoding:"utf8",stdio:["ignore","pipe","ignore"]}).trim()||null;}catch(e){}"#,
+    r#"const home=process.env.HOME||null;"#,
+    // The npx cache. `npm config get cache` would be authoritative but costs a
+    // second npm start-up; npm exports its resolved config into the
+    // environment of anything it runs, so `npm_config_cache` covers the
+    // overridden case and `~/.npm` covers the default.
+    r#"const cache=process.env.npm_config_cache||(home?path.join(home,".npm"):null);"#,
+    // Every `_npx/<hash>` is a separate tree — `@playwright/mcp` and any other
+    // npx-run package each get their own — so all of them are searched, in a
+    // stable order, and all of them are reported in `searched`.
+    r#"const npx=[];if(cache){try{for(const d of fs.readdirSync(path.join(cache,"_npx")).sort()){"#,
+    r#"const p=path.join(cache,"_npx",d,"node_modules");"#,
+    r#"try{if(fs.statSync(p).isDirectory())npx.push(p);}catch(e){}}}catch(e){}}"#,
+    r#"const roots=[...new Set(["/workspace",process.cwd(),home?path.join(home,"node_modules"):null,g,...npx].filter(Boolean))];"#,
+    r#"out.searched=roots;"#,
+    r#"const at=(s,r)=>{try{return require.resolve(s,{paths:[r]});}catch(e){return null;}};"#,
+    r#"const res=(s)=>{for(const r of roots){const p=at(s,r);if(p)return p;}return null;};"#,
+    // One `bin` reader for both packages: `bin` is a string for some manifests
+    // and an object for others, and getting that wrong on either one loses the
+    // entry point silently.
+    r#"const bin=(m,j)=>{const b=typeof j.bin==="string"?{[j.name]:j.bin}:(j.bin||{});"#,
+    r#"const k=Object.keys(b)[0];return k?path.resolve(path.dirname(m),b[k]):null;};"#,
+    // `playwright-core` is what carries the typings and the browser registry, but
+    // it is frequently *nested*: verified against a real `npm i -g playwright
+    // @playwright/cli`, npm does not hoist for global installs, so the global
+    // root holds `playwright/` and `@playwright/cli/` and no top-level
+    // `playwright-core/`. Resolving only the outer `playwright` would then read
+    // a package that ships no `types/types.d.ts` at all and report a perfectly
+    // current build as "predates browser.bind()". So: hop from the wrapper to
+    // its own `playwright-core`, and only fall back to the wrapper's manifest.
+    r#"let core=res("playwright-core/package.json");"#,
+    r#"if(!core){const pw=res("playwright/package.json");"#,
+    r#"if(pw)core=at("playwright-core/package.json",path.dirname(pw))||pw;}"#,
+    r#"if(core){try{out.playwright_path=core;const j=JSON.parse(fs.readFileSync(core,"utf8"));"#,
+    r#"out.playwright_version=j.version;out.playwright_cli=bin(core,j);}catch(e){}"#,
+    // `bind`/`unbind` are checked against the shipped type definitions rather
+    // than by loading the module: it is a static read, needs no browser, and
+    // cannot be tripped up by a package that fails to import.
+    r#"try{const t=fs.readFileSync(path.join(path.dirname(core),"types","types.d.ts"),"utf8");"#,
+    r#"out.has_bind=/\bunbind\s*\(\s*\)/.test(t)&&/\bbind\s*\(/.test(t);}catch(e){}}"#,
+    r#"const cli=res("@playwright/cli/package.json");"#,
+    r#"if(cli){try{const j=JSON.parse(fs.readFileSync(cli,"utf8"));out.cli_version=j.version;"#,
+    r#"out.cli_entry=bin(cli,j);}catch(e){}}"#,
+    // Browser bundles. `ffmpeg-*` lives in the same directory and is filtered
+    // out: it is not something that can be driven, and counting it would let
+    // the pane claim a browser is present when none is.
+    r#"try{const bd=process.env.PLAYWRIGHT_BROWSERS_PATH||(home?path.join(home,".cache","ms-playwright"):null);"#,
+    r#"if(bd)out.browsers=fs.readdirSync(bd).filter((n)=>/^(chromium|firefox|webkit)/.test(n)).sort();}catch(e){}"#,
+    // What this Playwright would *actually launch*, and whether it is there.
+    //
+    // A cache listing is not the same question. Two Playwright copies in one
+    // container — the npx `@playwright/mcp` one and a `/workspace` one — pin
+    // different browser revisions, and each installs its own. So the cache can
+    // hold `chromium-1237` while the resolved build wants `chromium-1234` and
+    // every `chromium.launch()` dies with "Executable doesn't exist", *while
+    // the pane reports a browser installed*. Asking the build itself sidesteps
+    // revision arithmetic entirely: this is the path a launch would use.
+    r#"const exe=(dir)=>{try{const bt=require(dir).chromium;"#,
+    r#"const ep=bt&&bt.executablePath?bt.executablePath():null;"#,
+    r#"return ep?[ep,fs.existsSync(ep)]:null;}catch(e){return null;}};"#,
+    r#"if(core){const r=exe(path.dirname(core));"#,
+    r#"if(r){out.chromium_executable=r[0];out.chromium_executable_exists=r[1];}}"#,
+    // And separately: what a *script* gets. `require("playwright")` is what
+    // every Playwright example writes, and it resolves the wrapper — which
+    // carries its own nested `playwright-core` whenever npm could not settle on
+    // one version. That copy can want a different browser revision than the one
+    // the viewer's copy installed, so it is asked its own question.
+    r#"try{const w=res("playwright/package.json");"#,
+    r#"if(w){const j=JSON.parse(fs.readFileSync(w,"utf8"));out.script_playwright_version=j.version;"#,
+    r#"const wc=at("playwright-core/package.json",path.dirname(w));"#,
+    r#"const r=exe(path.dirname(wc||w));"#,
+    r#"if(r){out.script_chromium_executable=r[0];out.script_chromium_executable_exists=r[1];}}}catch(e){}"#,
+    // The Chrome *channel* is an apt package, not a Playwright download, so it
+    // is looked for where apt puts it.
+    r#"try{for(const p of ["/usr/bin/google-chrome-stable","/usr/bin/google-chrome","/opt/google/chrome/chrome"]){"#,
+    r#"if(fs.existsSync(p)){out.chrome_channel=p;break;}}}catch(e){}"#,
+    r#"process.stdout.write("\n__TRIPLE_C_BROWSER_VIEW__"+JSON.stringify(out)+"\n");"#,
+);
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn payload(json: &str) -> String {
+        format!("some npm noise\n{}{}\n", MARKER, json)
+    }
+
+    #[test]
+    fn a_complete_install_is_usable() {
+        let d = parse_probe_output(&payload(
+            r#"{"node_version":"22.11.0","playwright_version":"1.62.1","has_bind":true,"cli_version":"0.1.18","cli_entry":"/workspace/node_modules/@playwright/cli/playwright-cli.js","searched":["/workspace"]}"#,
+        ))
+        .unwrap();
+        assert!(d.is_usable());
+        assert_eq!(d.blocker(), None);
+    }
+
+    #[test]
+    fn stderr_noise_before_and_after_the_payload_is_ignored() {
+        let out = format!(
+            "(node:41) Warning: something\n{}{}\nnpm notice trailing\n",
+            MARKER, r#"{"node_version":"22.11.0","has_bind":false}"#
+        );
+        let d = parse_probe_output(&out).unwrap();
+        assert_eq!(d.node_version.as_deref(), Some("22.11.0"));
+    }
+
+    #[test]
+    fn a_missing_playwright_names_both_packages_and_where_we_looked() {
+        let d = parse_probe_output(&payload(
+            r#"{"node_version":"22.11.0","searched":["/workspace","/usr/lib/node_modules","/home/claude/.npm/_npx/a1/node_modules"]}"#,
+        ))
+        .unwrap();
+        assert!(!d.is_usable());
+        let msg = d.blocker().unwrap();
+        // The two packages that actually have to be there, by name.
+        assert!(msg.contains("`playwright`"), "{}", msg);
+        assert!(msg.contains("`@playwright/cli`"), "{}", msg);
+        assert!(msg.contains("browser.bind"), "{}", msg);
+        // Every root consulted, including the npx cache, so the claim is checkable.
+        assert!(msg.contains("/usr/lib/node_modules"), "{}", msg);
+        assert!(msg.contains("/home/claude/.npm/_npx/a1/node_modules"), "{}", msg);
+    }
+
+    #[test]
+    fn no_message_offers_playwright_mcp_as_a_way_through_setup() {
+        // It bundles a playwright-core new enough to bind, but never ships the
+        // viewer — so proposing it as an install route is a dead end, which is
+        // exactly what a user hit. It may only be named for what it does do.
+        for json in [
+            r#"{"node_version":"22.11.0","searched":["/workspace"]}"#,
+            r#"{"node_version":"22.11.0","playwright_version":"1.44.0","has_bind":false}"#,
+            r#"{"node_version":"22.11.0","playwright_version":"1.62.1","has_bind":true}"#,
+        ] {
+            let msg = parse_probe_output(&payload(json)).unwrap().blocker().unwrap();
+            let offers_install = msg.contains("install `@playwright/mcp`")
+                || msg.contains("or use `@playwright/mcp`")
+                || msg.contains("npm i -D @playwright/mcp")
+                || msg.contains("npm i -g @playwright/mcp");
+            assert!(!offers_install, "{}", msg);
+            // And every message points at the one action that does work.
+            assert!(msg.contains("Set up Playwright"), "{}", msg);
+        }
+    }
+
+    #[test]
+    fn a_playwright_without_bind_asks_for_an_upgrade() {
+        let d = parse_probe_output(&payload(
+            r#"{"node_version":"22.11.0","playwright_version":"1.44.0","playwright_path":"/workspace/node_modules/playwright/package.json","has_bind":false,"cli_entry":"/x/cli.js"}"#,
+        ))
+        .unwrap();
+        let msg = d.blocker().unwrap();
+        assert!(msg.contains("1.44.0"), "{}", msg);
+        assert!(msg.contains("/workspace/node_modules/playwright"), "{}", msg);
+        assert!(msg.contains("Set up Playwright"), "{}", msg);
+    }
+
+    #[test]
+    fn an_npx_cached_playwright_counts_as_installed() {
+        // What `claude mcp add … npx @playwright/mcp@latest` leaves behind: a
+        // real playwright-core, in no `node_modules` the old probe looked at.
+        // It satisfies bind — and nothing else, because npx never brings the
+        // viewer with it.
+        let d = parse_probe_output(&payload(
+            concat!(
+                r#"{"node_version":"22.11.0","playwright_version":"1.62.1","#,
+                r#""playwright_path":"/home/claude/.npm/_npx/9f/node_modules/playwright-core/package.json","#,
+                r#""playwright_cli":"/home/claude/.npm/_npx/9f/node_modules/playwright-core/cli.js","#,
+                r#""has_bind":true,"#,
+                r#""searched":["/workspace","/usr/lib/node_modules","/home/claude/.npm/_npx/9f/node_modules"]}"#,
+            ),
+        ))
+        .unwrap();
+        assert_eq!(d.playwright_version.as_deref(), Some("1.62.1"));
+        assert!(d.has_bind);
+        assert_eq!(
+            d.playwright_cli.as_deref(),
+            Some("/home/claude/.npm/_npx/9f/node_modules/playwright-core/cli.js")
+        );
+        // Still not usable, and the message says why: the viewer is missing.
+        assert!(!d.is_usable());
+        let msg = d.blocker().unwrap();
+        assert!(msg.contains("@playwright/cli"), "{}", msg);
+    }
+
+    #[test]
+    fn the_probe_searches_the_npx_cache_as_well_as_the_module_roots() {
+        // The roots are built inside the probe, so this is the only place the
+        // set can be asserted without a container. Each fragment is load-bearing:
+        // dropping any one of them is how an install becomes invisible.
+        assert!(PROBE.contains(r#""/workspace""#), "{}", PROBE);
+        assert!(PROBE.contains("process.cwd()"), "{}", PROBE);
+        assert!(PROBE.contains(r#"path.join(home,"node_modules")"#), "{}", PROBE);
+        assert!(PROBE.contains("npm root -g"), "{}", PROBE);
+        assert!(PROBE.contains(r#"path.join(cache,"_npx")"#), "{}", PROBE);
+        assert!(PROBE.contains("npm_config_cache"), "{}", PROBE);
+        // Every one of them, not just the first hit, and all of them reported.
+        assert!(PROBE.contains("...npx"), "{}", PROBE);
+        assert!(PROBE.contains("out.searched=roots"), "{}", PROBE);
+    }
+
+    #[test]
+    fn a_partial_tree_still_answers_rather_than_failing() {
+        // Playwright resolved, but its manifest unreadable and no viewer: the
+        // probe's guards must still produce a parseable payload carrying what
+        // it did learn, because that is what the message is built from.
+        let d = parse_probe_output(&payload(
+            r#"{"node_version":"22.11.0","has_bind":false,"searched":["/workspace"],"browsers":["chromium-1200"]}"#,
+        ))
+        .unwrap();
+        assert_eq!(d.node_version.as_deref(), Some("22.11.0"));
+        assert_eq!(d.browsers, vec!["chromium-1200".to_string()]);
+        assert!(d.blocker().is_some());
+    }
+
+    #[test]
+    fn a_playwright_with_no_browser_bundle_is_flagged_without_blocking() {
+        let d = parse_probe_output(&payload(
+            concat!(
+                r#"{"node_version":"22.11.0","playwright_version":"1.62.1","has_bind":true,"#,
+                r#""cli_version":"0.1.18","cli_entry":"/g/cli.js","browsers":[]}"#,
+            ),
+        ))
+        .unwrap();
+        // Serving the viewer is possible; there is just nothing to drive yet.
+        assert!(d.is_usable());
+        assert_eq!(d.blocker(), None);
+        assert!(d.needs_browser());
+
+        let with_browser = parse_probe_output(&payload(
+            concat!(
+                r#"{"node_version":"22.11.0","playwright_version":"1.62.1","has_bind":true,"#,
+                r#""cli_version":"0.1.18","cli_entry":"/g/cli.js","browsers":["chromium-1200"]}"#,
+            ),
+        ))
+        .unwrap();
+        assert!(!with_browser.needs_browser());
+
+        // The Chrome channel counts too — it is an apt package rather than a
+        // Playwright download, so it never appears in `browsers`, and
+        // `@playwright/mcp` is the caller that asks for it.
+        let chrome_only = parse_probe_output(&payload(
+            concat!(
+                r#"{"node_version":"22.11.0","playwright_version":"1.62.1","has_bind":true,"#,
+                r#""cli_version":"0.1.18","cli_entry":"/g/cli.js","browsers":[],"#,
+                r#""chrome_channel":"/usr/bin/google-chrome-stable"}"#,
+            ),
+        ))
+        .unwrap();
+        assert!(!chrome_only.needs_browser());
+        assert_eq!(
+            chrome_only.chrome_channel.as_deref(),
+            Some("/usr/bin/google-chrome-stable")
+        );
+    }
+
+    #[test]
+    fn the_probe_looks_for_the_chrome_channel_where_apt_puts_it() {
+        assert!(PROBE.contains("google-chrome-stable"), "{}", PROBE);
+        assert!(PROBE.contains("/opt/google/chrome/chrome"), "{}", PROBE);
+    }
+
+    #[test]
+    fn the_probe_asks_playwright_what_it_would_launch() {
+        // Not derived from the cache listing — asked of the build, because the
+        // cache can hold a browser this build will never launch.
+        assert!(PROBE.contains("executablePath"), "{}", PROBE);
+        assert!(PROBE.contains("out.chromium_executable_exists"), "{}", PROBE);
+    }
+
+    /// A container carrying browsers from a *different* Playwright copy.
+    fn skewed() -> PlaywrightDetection {
+        parse_probe_output(&payload(concat!(
+            r#"{"node_version":"22.11.0","playwright_version":"1.62.1","has_bind":true,"#,
+            r#""cli_version":"0.1.18","cli_entry":"/g/cli.js","browsers":["chromium-1237"],"#,
+            r#""chromium_executable":"/home/claude/.cache/ms-playwright/chromium-1234/chrome-linux64/chrome","#,
+            r#""chromium_executable_exists":false}"#,
+        )))
+        .unwrap()
+    }
+
+    #[test]
+    fn a_browser_cache_full_of_the_wrong_revision_counts_as_no_browser() {
+        let d = skewed();
+        // The viewer still serves — it is the browser that cannot start.
+        assert!(d.is_usable());
+        assert_eq!(d.blocker(), None);
+        assert!(d.revision_skew());
+        assert!(d.needs_browser(), "a browser that cannot launch is not a browser");
+    }
+
+    #[test]
+    fn the_skew_message_names_both_revisions_and_the_way_out() {
+        let msg = skewed().skew_message().unwrap();
+        assert!(msg.contains("chromium-1237"), "{}", msg); // what is there
+        assert!(msg.contains("chromium-1234"), "{}", msg); // what it wants
+        assert!(msg.contains("Install Chromium"), "{}", msg); // what fixes it
+    }
+
+    #[test]
+    fn the_chrome_channel_covers_a_skewed_cache() {
+        // The channel is an apt binary at a fixed path, so a revision mismatch
+        // cannot affect it: there is still something to drive.
+        let mut d = skewed();
+        d.chrome_channel = Some("/usr/bin/google-chrome-stable".to_string());
+        assert!(!d.needs_browser());
+    }
+
+    #[test]
+    fn a_probe_that_could_not_answer_is_not_reported_as_skew() {
+        // Older container, or a Playwright too broken to `require`: unset is
+        // "unknown", and unknown must never render as "your browsers are wrong".
+        let d = parse_probe_output(&payload(concat!(
+            r#"{"node_version":"22.11.0","playwright_version":"1.62.1","has_bind":true,"#,
+            r#""cli_version":"0.1.18","cli_entry":"/g/cli.js","browsers":["chromium-1237"]}"#,
+        )))
+        .unwrap();
+        assert!(!d.revision_skew());
+        assert!(!d.needs_browser());
+        assert_eq!(d.skew_message(), None);
+    }
+
+    #[test]
+    fn a_missing_viewer_package_is_reported_separately() {
+        let d = parse_probe_output(&payload(
+            r#"{"node_version":"22.11.0","playwright_version":"1.62.1","has_bind":true}"#,
+        ))
+        .unwrap();
+        assert!(!d.is_usable());
+        assert!(d.blocker().unwrap().contains("@playwright/cli"));
+    }
+
+    #[test]
+    fn a_container_without_node_says_so() {
+        let d = parse_probe_output(&payload(r#"{"has_bind":false}"#)).unwrap();
+        assert!(d.blocker().unwrap().contains("Node.js"));
+    }
+
+    #[test]
+    fn an_unmarked_stream_surfaces_the_containers_own_error() {
+        let err = parse_probe_output("sh: 1: node: not found\n").unwrap_err();
+        assert!(err.contains("node: not found"), "{}", err);
+    }
+
+    #[test]
+    fn an_empty_stream_is_explained_rather_than_parsed() {
+        let err = parse_probe_output("   \n").unwrap_err();
+        assert!(err.contains("no output"), "{}", err);
+    }
+
+    #[test]
+    fn the_probe_reads_bind_from_the_nested_core_of_a_wrapper_install() {
+        // `npm i -g playwright` leaves `playwright-core` under
+        // `playwright/node_modules`, and the wrapper ships no
+        // `types/types.d.ts` — so without this hop a current build reports
+        // `has_bind: false`. Verified against a real global install.
+        assert!(
+            PROBE.contains(r#"at("playwright-core/package.json",path.dirname(pw))"#),
+            "{}",
+            PROBE
+        );
+    }
+
+    #[test]
+    fn the_probe_is_a_single_argv_element_with_no_quoting_hazards() {
+        // It is passed straight to `node -e`; a stray single quote would only
+        // matter if someone later routed it through a shell, and a newline
+        // would break the marker-line contract in `parse_probe_output`.
+        assert!(!PROBE.contains('\n'));
+        assert!(PROBE.contains(MARKER));
+    }
+}

app/src-tauri/src/browser_view/mod.rs

@@ -0,0 +1,928 @@
+//! Browser view — watch, and take over, the browser Claude is driving.
+//!
+//! ## What is actually being watched
+//!
+//! Playwright ships a live dashboard. A script inside the container calls
+//! `await browser.bind('claude')`, which publishes a descriptor for the running
+//! browser into `~/.cache/ms-playwright/b/`; `@playwright/mcp` does this for you.
+//! `playwright-cli show --host 127.0.0.1 --port <p>` then serves a React viewer
+//! that watches that directory, connects to the published browser, and gives you
+//! a CDP screencast with full mouse and keyboard takeover — all of which works
+//! with `headless: true`, which is the only thing that could work in a container.
+//!
+//! Discovery is *local filesystem*, so the viewer has to run in the same
+//! container as the browsers. There is nothing a host-side viewer could see.
+//!
+//! ## Getting it onto the screen safely
+//!
+//! ```text
+//!   webview <iframe>                    host                          container
+//!   ────────────────                    ────                          ─────────
+//!   http://127.0.0.1:47820/index.html
+//!            ?ws=…&token=…   ────►  BrowserViewProxy   ──socat exec──►  playwright-cli show
+//!                                   (token gate)          (Docker API)   127.0.0.1:39321
+//! ```
+//!
+//! The proxy is the *only* host-bound socket, and it authenticates before a byte
+//! reaches the container — see [`proxy`] for the gate, and for why the auth
+//! bridge's unauthenticated [`PortForward`](crate::auth_bridge::tunnel::PortForward)
+//! is deliberately not used to carry this port. The container-side viewer port is
+//! additionally *reserved* with
+//! [`crate::auth_bridge::RESERVED_CONTAINER_PORTS`], so that a project which
+//! also has the auth bridge on cannot end up with the viewer mirrored onto the
+//! host a second time, ungated.
+//!
+//! ## Lifecycle
+//!
+//! Off by default and per-project opt-in, exactly like `auth_bridge_enabled`.
+//! One supervisor task per session owns the proxy and the viewer process, and it
+//! is the only thing that tears them down, so every way a session can end funnels
+//! through one code path:
+//!
+//! | Trigger | Path |
+//! |---|---|
+//! | Turned off in the UI | `set_browser_view_enabled(false)` → [`BrowserViewManager::stop`] |
+//! | Container stopped, by the UI or otherwise | supervisor's `is_container_running` check |
+//! | Project deleted | supervisor's `store.get()` check |
+//! | Container rebuilt | old container stops → supervisor exits; the new one is not auto-started |
+//! | Viewer died in the container | supervisor's periodic HTTP liveness probe |
+//! | App exit | [`BrowserViewManager::stop_all`] |
+//!
+//! [`BrowserViewManager::stop`] awaits the supervisor, so the host port is
+//! provably released before it returns.
+//!
+//! One honest gap, verified rather than assumed: `playwright-cli show` is only
+//! a launcher — the dashboard it starts reparents to PID 1 and survives the
+//! exec that spawned it. Every ordinary teardown path above calls
+//! [`kill_dashboard`], which does stop it, but a *hard* app crash leaves the
+//! dashboard running inside the container until the container stops. That
+//! orphan is reachable on container loopback only: the host-side port dies with
+//! the app, and [`crate::auth_bridge::RESERVED_CONTAINER_PORTS`] is a constant
+//! precisely so the bridge will not mirror an orphan the next time the app
+//! starts. The next [`BrowserViewManager::start`] reclaims it.
+
+pub mod commands;
+pub mod detect;
+pub mod install;
+pub mod page;
+pub mod popout;
+pub mod proxy;
+
+use std::collections::HashMap;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::{Arc, OnceLock};
+use std::time::Duration;
+
+use serde::Serialize;
+use tauri::{AppHandle, Emitter};
+use tokio::sync::{watch, Mutex};
+use tokio::task::JoinHandle;
+
+use crate::auth_bridge::proc_net::{self, PortFamily};
+use crate::docker::container::is_container_running;
+use crate::docker::exec::exec_oneshot;
+use crate::storage::projects_store::ProjectsStore;
+
+use detect::PlaywrightDetection;
+use proxy::BrowserViewProxy;
+
+/// Emitted whenever a project's browser view starts, stops or fails.
+/// Payload: `{ project_id, status: BrowserViewStatus }`.
+const BROWSER_VIEW_EVENT: &str = "browser-view-changed";
+
+/// Container-side ports the viewer may bind, tried in order. The dashboard is a
+/// per-workspace singleton inside the container, so only one is ever in use at
+/// a time; the range exists only so an unrelated service already sitting on the
+/// first port doesn't take the feature down.
+///
+/// This *is* [`crate::auth_bridge::RESERVED_CONTAINER_PORTS`] — the bridge must
+/// never mirror these, so the two cannot be allowed to drift.
+const VIEWER_PORTS: std::ops::RangeInclusive<u16> = crate::auth_bridge::RESERVED_CONTAINER_PORTS;
+
+/// How often the supervisor re-checks that the session still has a reason to
+/// exist. Matches the auth bridge's cadence.
+const SUPERVISE_INTERVAL: Duration = Duration::from_secs(2);
+
+/// Supervisor ticks between HTTP liveness probes of the viewer. The two cheap
+/// checks run every tick; this one costs a container exec, so it runs at 1/5
+/// the rate (~10s).
+const LIVENESS_EVERY: u32 = 5;
+
+/// Ceiling on one readiness/liveness probe. Enforced inside the container by
+/// Node and again here, so neither a wedged daemon nor a wedged exec can stall
+/// the supervisor.
+const PROBE_TIMEOUT: Duration = Duration::from_secs(4);
+
+/// How long to wait for `playwright-cli show` to start answering HTTP.
+const READY_TIMEOUT: Duration = Duration::from_secs(30);
+const READY_POLL: Duration = Duration::from_millis(400);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// IPC response model
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum BrowserViewState {
+    /// Not running. Either never started, or stopped.
+    Off,
+    /// Running and reachable at `url`.
+    Running,
+    /// The container can't serve this — see `message` for what to install.
+    Unavailable,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct BrowserViewStatus {
+    /// The per-project opt-in. Off by default.
+    pub enabled: bool,
+    pub state: BrowserViewState,
+    /// Fully-formed, token-bearing URL for the pane's iframe. Loopback only.
+    pub url: Option<String>,
+    pub host_port: Option<u16>,
+    pub container_port: Option<u16>,
+    /// RFC 3339 timestamp of when the viewer came up.
+    pub started_at: Option<String>,
+    /// What was found in the container. Present even when unusable, because
+    /// that is exactly when the user needs to see it.
+    pub detection: Option<PlaywrightDetection>,
+    /// Human-readable explanation, set whenever `state` isn't `Running`.
+    pub message: Option<String>,
+}
+
+impl BrowserViewStatus {
+    fn off(enabled: bool) -> Self {
+        Self {
+            enabled,
+            state: BrowserViewState::Off,
+            url: None,
+            host_port: None,
+            container_port: None,
+            started_at: None,
+            detection: None,
+            message: None,
+        }
+    }
+
+    fn unavailable(enabled: bool, detection: PlaywrightDetection, message: String) -> Self {
+        Self {
+            enabled,
+            state: BrowserViewState::Unavailable,
+            detection: Some(detection),
+            message: Some(message),
+            ..Self::off(enabled)
+        }
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Manager
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Everything a live session exposes to `status()`. Fixed once the session is
+/// up, so it can be cloned out from under the map lock.
+#[derive(Debug, Clone)]
+struct SessionMeta {
+    url: String,
+    host_port: u16,
+    container_port: u16,
+    started_at: String,
+    detection: PlaywrightDetection,
+}
+
+struct Session {
+    /// Distinguishes this supervisor from a later one for the same project, so
+    /// a supervisor that exits late can't evict its replacement.
+    epoch: u64,
+    cancel: watch::Sender<bool>,
+    meta: SessionMeta,
+    supervisor: JoinHandle<()>,
+}
+
+type SessionMap = Arc<Mutex<HashMap<String, Session>>>;
+
+#[derive(Default)]
+pub struct BrowserViewManager {
+    sessions: SessionMap,
+    /// The per-project opt-in.
+    ///
+    /// NOTE: in memory only, so it does not survive an app restart. The durable
+    /// home for this is a `browser_view_enabled: bool` field on
+    /// `models::Project` (see the report) — `models/project.rs` is out of scope
+    /// for this change, so the flag lives here and the wiring is otherwise
+    /// identical to `auth_bridge_enabled`.
+    enabled: Mutex<std::collections::HashSet<String>>,
+    next_epoch: AtomicU64,
+}
+
+/// Process-wide handle.
+///
+/// Deliberately *not* a field on `AppState`: keeping it here means the feature
+/// needs no edit to `lib.rs` beyond declaring the module and registering the
+/// commands, and it lets teardown paths reach it without threading state.
+pub fn manager() -> &'static Arc<BrowserViewManager> {
+    static MANAGER: OnceLock<Arc<BrowserViewManager>> = OnceLock::new();
+    MANAGER.get_or_init(|| Arc::new(BrowserViewManager::default()))
+}
+
+impl BrowserViewManager {
+    pub async fn is_enabled(&self, project_id: &str) -> bool {
+        self.enabled.lock().await.contains(project_id)
+    }
+
+    async fn set_enabled(&self, project_id: &str, enabled: bool) {
+        let mut set = self.enabled.lock().await;
+        if enabled {
+            set.insert(project_id.to_string());
+        } else {
+            set.remove(project_id);
+        }
+    }
+
+    /// Current status without touching the container.
+    pub async fn status(&self, project_id: &str) -> BrowserViewStatus {
+        let enabled = self.is_enabled(project_id).await;
+        match self.sessions.lock().await.get(project_id) {
+            Some(session) => BrowserViewStatus {
+                enabled,
+                state: BrowserViewState::Running,
+                url: Some(session.meta.url.clone()),
+                host_port: Some(session.meta.host_port),
+                container_port: Some(session.meta.container_port),
+                started_at: Some(session.meta.started_at.clone()),
+                detection: Some(session.meta.detection.clone()),
+                message: None,
+            },
+            None => BrowserViewStatus::off(enabled),
+        }
+    }
+
+    /// Probe the container and, if it can serve a viewer, bring one up.
+    ///
+    /// Idempotent: a call while a live session exists returns that session's
+    /// status untouched, so re-opening the tab does not restart the dashboard.
+    pub async fn start(
+        &self,
+        project_id: String,
+        container_id: String,
+        app: AppHandle,
+        store: Arc<ProjectsStore>,
+    ) -> Result<BrowserViewStatus, String> {
+        self.set_enabled(&project_id, true).await;
+
+        // Bind the answer before acting on it: `status()` takes the same lock,
+        // and this mutex is not reentrant.
+        let already_live = self
+            .sessions
+            .lock()
+            .await
+            .get(&project_id)
+            .is_some_and(|s| !s.supervisor.is_finished());
+        if already_live {
+            return Ok(self.status(&project_id).await);
+        }
+
+        let detection = detect::detect(&container_id).await?;
+        if !detection.is_usable() {
+            let blocker = detection.blocker().unwrap_or_else(|| {
+                "Playwright is present but incomplete in this container.".to_string()
+            });
+            let status = BrowserViewStatus::unavailable(true, detection, blocker);
+            emit(&app, &project_id, &status);
+            return Ok(status);
+        }
+        // `is_usable()` already established this, so the fallback is unreachable.
+        let cli_entry = detection.cli_entry.clone().unwrap_or_default();
+
+        // The dashboard is a per-workspace singleton keyed on a unix socket in
+        // the temp dir, not on a port. Verified: while one is running, a second
+        // `show --port` prints "Dashboard is running pid=…", exits 0, and
+        // *ignores the port you asked for*. So always reclaim first — including
+        // a daemon this app orphaned in an earlier run, since it outlives us.
+        // Doing this before choosing a port also frees the one a previous
+        // session was using, so sessions don't walk up the range. Best-effort:
+        // a container with no dashboard makes this a no-op.
+        let _ = kill_dashboard(&container_id, &cli_entry).await;
+
+        let (container_port, entry_path) = start_viewer(&container_id, &cli_entry).await?;
+
+        let token = generate_token();
+        // `--host 127.0.0.1` is ours to set, so the family is known and there is
+        // no need to go back to /proc/net to work it out.
+        let proxy = match BrowserViewProxy::bind(
+            container_id.clone(),
+            container_port,
+            PortFamily::V4,
+            token.clone(),
+        )
+        .await
+        {
+            Ok(p) => p,
+            Err(e) => {
+                let _ = kill_dashboard(&container_id, &cli_entry).await;
+                return Err(e);
+            }
+        };
+
+        let meta = SessionMeta {
+            url: build_url(proxy.port, &entry_path, &token),
+            host_port: proxy.port,
+            container_port,
+            started_at: chrono::Utc::now().to_rfc3339(),
+            detection,
+        };
+
+        let epoch = self.next_epoch.fetch_add(1, Ordering::Relaxed);
+        let (cancel_tx, cancel_rx) = watch::channel(false);
+        let supervisor = tokio::spawn(supervise(
+            project_id.clone(),
+            container_id.clone(),
+            cli_entry,
+            container_port,
+            epoch,
+            app.clone(),
+            store,
+            self.sessions.clone(),
+            cancel_rx,
+            proxy,
+        ));
+
+        log::info!(
+            "Browser view: project {} → 127.0.0.1:{} → container 127.0.0.1:{}",
+            project_id,
+            meta.host_port,
+            container_port
+        );
+
+        self.sessions.lock().await.insert(
+            project_id.clone(),
+            Session {
+                epoch,
+                cancel: cancel_tx,
+                meta,
+                supervisor,
+            },
+        );
+
+        let status = self.status(&project_id).await;
+        emit(&app, &project_id, &status);
+        Ok(status)
+    }
+
+    /// Stop one project's view and wait until its host port has been released.
+    pub async fn stop(&self, project_id: &str) {
+        self.set_enabled(project_id, false).await;
+        // Remove under the lock, then release it before awaiting: the
+        // supervisor takes the same lock to deregister itself on exit.
+        let session = self.sessions.lock().await.remove(project_id);
+        if let Some(session) = session {
+            let _ = session.cancel.send(true);
+            let _ = session.supervisor.await;
+            log::info!("Browser view: stopped for project {}", project_id);
+        }
+    }
+
+    /// Stop every view. Used on app exit.
+    pub async fn stop_all(&self) {
+        let sessions: Vec<(String, Session)> = self.sessions.lock().await.drain().collect();
+        for (project_id, session) in sessions {
+            let _ = session.cancel.send(true);
+            let _ = session.supervisor.await;
+            log::info!("Browser view: stopped for project {}", project_id);
+        }
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Supervisor
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Owns the proxy and the viewer process for one session and is the only thing
+/// that tears them down, so a session can't half-die.
+#[allow(clippy::too_many_arguments)]
+async fn supervise(
+    project_id: String,
+    container_id: String,
+    cli_entry: String,
+    container_port: u16,
+    epoch: u64,
+    app: AppHandle,
+    store: Arc<ProjectsStore>,
+    sessions: SessionMap,
+    mut cancel: watch::Receiver<bool>,
+    mut proxy: BrowserViewProxy,
+) {
+    let mut ticks: u32 = 0;
+    loop {
+        if store.get(&project_id).is_none() {
+            log::info!("Browser view: project {} is gone — tearing down", project_id);
+            break;
+        }
+        if !is_container_running(&container_id).await.unwrap_or(false) {
+            log::info!(
+                "Browser view: container for project {} is no longer running — tearing down",
+                project_id
+            );
+            break;
+        }
+        // The dashboard is a detached daemon, so there is no process handle to
+        // watch: liveness has to be an actual request. That costs an exec, so
+        // it runs at a coarser cadence than the two cheap checks above.
+        ticks = ticks.wrapping_add(1);
+        if ticks % LIVENESS_EVERY == 0 {
+            // Cancellation races the probe, not just the sleep, so stopping the
+            // view never waits out an in-flight exec.
+            let alive = tokio::select! {
+                _ = cancel.changed() => break,
+                res = probe_entry_path(&container_id, container_port) => res.is_ok(),
+            };
+            if !alive {
+                log::warn!(
+                    "Browser view: the viewer for project {} stopped answering — tearing down",
+                    project_id
+                );
+                break;
+            }
+        }
+
+        tokio::select! {
+            _ = cancel.changed() => break,
+            _ = tokio::time::sleep(SUPERVISE_INTERVAL) => {}
+        }
+    }
+
+    proxy.shutdown().await;
+    let _ = kill_dashboard(&container_id, &cli_entry).await;
+
+    // Deregister, unless a newer session has already taken this project's slot.
+    let superseded = {
+        let mut map = sessions.lock().await;
+        match map.get(&project_id) {
+            Some(session) if session.epoch == epoch => {
+                map.remove(&project_id);
+                false
+            }
+            // Someone else owns this project now: `stop` removes the session
+            // from the map *before* awaiting this task, and teardown below is
+            // seconds of Docker work, so a restart in that window is ordinary.
+            Some(_) => true,
+            None => false,
+        }
+    };
+
+    // Everything past here speaks for the project as a whole, so a superseded
+    // supervisor must say nothing: closing the pop-out would destroy the *new*
+    // session's window, and the off-status would report a running view as
+    // stopped.
+    if superseded {
+        return;
+    }
+
+    // A pop-out outlives the tab, so nothing else would take it down: the
+    // window would sit there showing a frozen last frame of a viewer that no
+    // longer exists. The session owns it, and this is where the session ends.
+    let _ = popout::close(&app, &project_id);
+
+    let enabled = manager().is_enabled(&project_id).await;
+    emit(&app, &project_id, &BrowserViewStatus::off(enabled));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The viewer process
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Where the detached viewer's own output goes, so a failed start still has
+/// something to show the user.
+const VIEWER_LOG: &str = "/tmp/triple-c-browser-view.log";
+
+/// Start `playwright-cli show`, detached.
+///
+/// `playwright-cli show` is a *launcher*: verified that it spawns
+/// `playwright-core/lib/entry/dashboardApp.js`, which reparents to PID 1 and
+/// outlives both the launcher and the exec that started it. So there is no
+/// point tying a process lifetime to the exec's stdin — signalling the launcher
+/// leaves the dashboard bound to its port and still serving. Teardown is
+/// [`kill_dashboard`], which is the only thing verified to actually stop it.
+///
+/// Consequently this is a fire-and-forget exec: the launcher's output is
+/// redirected to [`VIEWER_LOG`] (both so `exec_oneshot` can return immediately
+/// rather than waiting on an inherited stdout, and so a failure has a trail),
+/// and readiness is established by [`wait_until_ready`] instead.
+async fn launch_viewer(container_id: &str, cli_entry: &str, port: u16) -> Result<(), String> {
+    // `NO_UPDATE_NOTIFIER` stops the CLI phoning registry.npmjs.org on every
+    // launch; the container may have no egress, and we don't want to wait out a
+    // DNS timeout before the dashboard binds.
+    let script = format!(
+        "{}; NO_UPDATE_NOTIFIER=1 nohup node {} show --host 127.0.0.1 --port {} >{} 2>&1 &",
+        WORKDIR_PREFIX,
+        shell_quote(cli_entry),
+        port,
+        VIEWER_LOG
+    );
+    exec_oneshot(
+        container_id,
+        vec!["sh".to_string(), "-c".to_string(), script],
+    )
+    .await
+    .map(|_| ())
+    .map_err(|e| format!("Could not start the Playwright viewer: {}", e))
+}
+
+/// The dashboard singleton is keyed on a hash of the working directory, so
+/// `show` and `show --kill` must agree on one. `exec_oneshot` doesn't set a
+/// working directory (it inherits the image's), and `/workspace` is both what
+/// the image sets today and where Claude actually runs — but pinning it here
+/// means a change to the image can't silently split the two into different
+/// singletons, leaving a dashboard nothing can kill.
+const WORKDIR_PREFIX: &str = "cd /workspace 2>/dev/null || true";
+
+/// Stop the dashboard daemon. Verified to free the port and stop answering.
+async fn kill_dashboard(container_id: &str, cli_entry: &str) -> Result<String, String> {
+    let script = format!(
+        "{}; NO_UPDATE_NOTIFIER=1 node {} show --kill",
+        WORKDIR_PREFIX,
+        shell_quote(cli_entry)
+    );
+    exec_oneshot(
+        container_id,
+        vec!["sh".to_string(), "-c".to_string(), script],
+    )
+    .await
+}
+
+/// Turn a failed start into something the user can act on.
+///
+/// The one failure worth naming is the singleton clash: if a dashboard we
+/// couldn't reclaim is still alive, the launcher exits 0 having printed
+/// "Dashboard is running pid=…" and having silently ignored the port we asked
+/// for, so all the caller sees is a port that never answers.
+fn explain_start_failure(err: &str, log: &str) -> String {
+    let log = log.trim();
+    if log.contains("Dashboard is running") {
+        return format!(
+            "Another Playwright dashboard is already running in this container and would not \
+             give up its port. Stop it from a terminal in the container with \
+             `npx playwright-cli show --kill`, then try again.\n\nViewer output:\n{}",
+            log
+        );
+    }
+    if log.is_empty() {
+        err.to_string()
+    } else {
+        format!("{}\n\nViewer output:\n{}", err, log)
+    }
+}
+
+/// Tail of the viewer's own output, for a start that didn't come up.
+async fn read_viewer_log(container_id: &str) -> String {
+    exec_oneshot(
+        container_id,
+        vec!["tail".to_string(), "-n".to_string(), "40".to_string(), VIEWER_LOG.to_string()],
+    )
+    .await
+    .unwrap_or_default()
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Readiness, ports, URLs
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// How many free ports a start will try before giving up.
+///
+/// More than one because port choice is a check-then-bind: the free list comes
+/// from a snapshot of the container's `/proc/net/tcp`, and anything in the
+/// container may bind the port we picked before the dashboard gets to it. One
+/// retry per lost race is the recovery; the cap is what stops a container that
+/// binds every candidate from holding a start open for
+/// `MAX_PORT_ATTEMPTS × READY_TIMEOUT`.
+const MAX_PORT_ATTEMPTS: usize = 3;
+
+/// Get a viewer listening inside the container and return the port it is on
+/// plus the path the pane should load.
+///
+/// ## The check/bind race
+///
+/// [`pick_viewer_port`] reads a *snapshot* of container listeners; the dashboard
+/// binds some milliseconds later. Nothing here can make that atomic — the bind
+/// happens in another process, in another namespace, and `playwright-cli show`
+/// reports the port it actually took only on a first-ever start (see
+/// [`wait_until_ready`]). What is possible is to stop treating the first
+/// candidate as the only one: if the port we picked does not come up, walk to
+/// the next free candidate rather than failing the whole start.
+///
+/// Residual, stated rather than glossed: a container-side process that binds the
+/// candidate port *and answers HTTP* is indistinguishable from the dashboard at
+/// this layer, and the pane would then front it. What contains that is
+/// downstream — the host proxy is loopback-only and token-gated, and the pane's
+/// iframe is sandboxed — not this function.
+async fn start_viewer(container_id: &str, cli_entry: &str) -> Result<(u16, String), String> {
+    let mut tried: Vec<u16> = Vec::new();
+    let mut last: Option<String> = None;
+
+    for _ in 0..MAX_PORT_ATTEMPTS {
+        // Re-read the listener snapshot each attempt: the port that was free a
+        // moment ago is exactly the one we may have just lost.
+        let port = match pick_viewer_port(container_id, &tried).await {
+            Ok(p) => p,
+            Err(e) => {
+                // Report why the *attempts* failed, not just "nothing free":
+                // the exhausted range is the symptom, the last start failure is
+                // the thing the user can act on.
+                return Err(match last {
+                    Some(prev) => format!("{} ({})", e, prev),
+                    None => e,
+                });
+            }
+        };
+        tried.push(port);
+
+        launch_viewer(container_id, cli_entry, port).await?;
+
+        // Wait for it to actually answer, and learn the entry URL while we're
+        // there — see `probe_entry_path` for why that matters. This, not the
+        // launcher's stdout, is the readiness signal: verified that the
+        // "Listening on …" line is printed only on the very first start.
+        match wait_until_ready(container_id, port).await {
+            Ok(path) => return Ok((port, path)),
+            Err(e) => {
+                let log = read_viewer_log(container_id).await;
+                // Always kill before retrying: the dashboard is a singleton, so
+                // a launcher that came up on some *other* port would otherwise
+                // make every further attempt a no-op that silently ignores the
+                // port we asked for.
+                let _ = kill_dashboard(container_id, cli_entry).await;
+                last = Some(explain_start_failure(&e, &log));
+            }
+        }
+    }
+
+    Err(last.unwrap_or_else(|| "The Playwright viewer did not start.".to_string()))
+}
+
+/// First port in [`VIEWER_PORTS`] that nothing in the container is listening on
+/// and that this start has not already tried.
+async fn pick_viewer_port(container_id: &str, tried: &[u16]) -> Result<u16, String> {
+    let text = exec_oneshot(
+        container_id,
+        vec![
+            // Absolute path, deliberately, for the same reason the auth bridge
+            // uses one: `container/Dockerfile` puts a container-writable
+            // directory first on `PATH`, so a bare `cat` is a name the container
+            // can rebind to a shim. A shimmed listener list is a shimmed answer
+            // to "which port is free" — i.e. the container choosing which port
+            // the viewer, and therefore the host-side proxy, ends up on.
+            "/usr/bin/cat".to_string(),
+            "/proc/net/tcp".to_string(),
+            "/proc/net/tcp6".to_string(),
+        ],
+    )
+    .await
+    .unwrap_or_default();
+    let taken = proc_net::parse_loopback_listeners(&text);
+    VIEWER_PORTS
+        .clone()
+        .find(|p| !taken.contains_key(p) && !tried.contains(p))
+        .ok_or_else(|| {
+            format!(
+                "No free port in {}–{} inside the container for the Playwright viewer.",
+                VIEWER_PORTS.start(),
+                VIEWER_PORTS.end()
+            )
+        })
+}
+
+/// Poll the viewer until it answers, and return the path the pane should load.
+async fn wait_until_ready(container_id: &str, port: u16) -> Result<String, String> {
+    let deadline = tokio::time::Instant::now() + READY_TIMEOUT;
+    loop {
+        let last = match probe_entry_path(container_id, port).await {
+            Ok(path) => return Ok(path),
+            Err(e) => e,
+        };
+        if tokio::time::Instant::now() >= deadline {
+            return Err(format!(
+                "The Playwright viewer did not start listening on container port {} within {}s ({}).",
+                port,
+                READY_TIMEOUT.as_secs(),
+                last
+            ));
+        }
+        tokio::time::sleep(READY_POLL).await;
+    }
+}
+
+const PROBE_MARKER: &str = "__TRIPLE_C_BV_PATH__";
+
+/// Ask the viewer, from inside the container, what it wants to be loaded as.
+///
+/// `GET /` answers `302 Location: /index.html?ws=<guid>`, where the guid is the
+/// dashboard's own per-run capability for its WebSocket. Resolving that here and
+/// pointing the iframe straight at the final URL means the pane never traverses
+/// a redirect — which matters, because a redirect drops the `?token=` the proxy
+/// gate wants and would leave a fresh connection to be authorised with nothing.
+/// A `200` (no redirect) is fine too; then the entry point is just `/`.
+async fn probe_entry_path(container_id: &str, port: u16) -> Result<String, String> {
+    // The request is bounded on both sides. Verified: the dashboard answers a
+    // bad WebSocket path by holding the socket open forever rather than
+    // erroring, so "no reply" is a state this probe has to be able to leave —
+    // otherwise a wedged daemon would wedge the supervisor, and `stop()` waits
+    // on the supervisor.
+    let script = format!(
+        r#"const q=require("http").get({{host:"127.0.0.1",port:{},path:"/",headers:{{host:"127.0.0.1:{}"}}}},r=>{{process.stdout.write("\n{}"+r.statusCode+" "+(r.headers.location||"/")+"\n");r.resume();process.exit(0);}});q.on("error",e=>{{process.stderr.write(String(e.message));process.exit(1);}});q.setTimeout({},()=>{{process.stderr.write("timed out waiting for the viewer");q.destroy();process.exit(1);}});"#,
+        port,
+        port,
+        PROBE_MARKER,
+        PROBE_TIMEOUT.as_millis()
+    );
+    let out = tokio::time::timeout(
+        PROBE_TIMEOUT * 2,
+        exec_oneshot(
+            container_id,
+            vec!["node".to_string(), "-e".to_string(), script],
+        ),
+    )
+    .await
+    .map_err(|_| "the viewer probe did not return".to_string())??;
+    parse_entry_probe(&out)
+}
+
+/// Turn the readiness probe's output into the path to load.
+fn parse_entry_probe(out: &str) -> Result<String, String> {
+    let Some(idx) = out.find(PROBE_MARKER) else {
+        let trimmed = out.trim();
+        return Err(if trimmed.is_empty() {
+            "no response".to_string()
+        } else {
+            trimmed.lines().next_back().unwrap_or(trimmed).to_string()
+        });
+    };
+    let line = out[idx + PROBE_MARKER.len()..]
+        .lines()
+        .next()
+        .unwrap_or("")
+        .trim();
+    let (status, location) = line.split_once(' ').unwrap_or((line, "/"));
+    match status {
+        "301" | "302" | "303" | "307" | "308" => {
+            // Only same-origin, absolute paths — the dashboard never sends
+            // anything else, and following an off-host redirect through the
+            // pane would be a nasty surprise.
+            if location.starts_with('/') {
+                Ok(location.to_string())
+            } else {
+                Ok("/".to_string())
+            }
+        }
+        "200" => Ok("/".to_string()),
+        other => Err(format!("viewer answered HTTP {}", other)),
+    }
+}
+
+/// The pane's iframe URL: the viewer's own entry path with our session token
+/// appended, on the host loopback port the gate is listening on.
+fn build_url(host_port: u16, entry_path: &str, token: &str) -> String {
+    let sep = if entry_path.contains('?') { '&' } else { '?' };
+    format!(
+        "http://127.0.0.1:{}{}{}token={}",
+        host_port, entry_path, sep, token
+    )
+}
+
+/// Single-quote a path for `sh -c`. Paths from `require.resolve` never contain
+/// quotes in practice, but this is a shell command line and the cost of being
+/// sure is one line.
+fn shell_quote(s: &str) -> String {
+    format!("'{}'", s.replace('\'', r"'\''"))
+}
+
+/// 256 bits of URL-safe randomness, matching `web_terminal`'s token shape.
+fn generate_token() -> String {
+    use base64::Engine;
+    use rand::Rng;
+    let mut rng = rand::rng();
+    let bytes: Vec<u8> = (0..32).map(|_| rng.random::<u8>()).collect();
+    base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(&bytes)
+}
+
+fn emit(app: &AppHandle, project_id: &str, status: &BrowserViewStatus) {
+    let _ = app.emit(
+        BROWSER_VIEW_EVENT,
+        serde_json::json!({ "project_id": project_id, "status": status }),
+    );
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_redirect_becomes_the_entry_path() {
+        let out = format!("\n{}302 /index.html?ws=abc123\n", PROBE_MARKER);
+        assert_eq!(parse_entry_probe(&out).unwrap(), "/index.html?ws=abc123");
+    }
+
+    #[test]
+    fn a_plain_200_entry_point_is_the_root() {
+        let out = format!("\n{}200 /\n", PROBE_MARKER);
+        assert_eq!(parse_entry_probe(&out).unwrap(), "/");
+    }
+
+    #[test]
+    fn an_off_host_redirect_is_not_followed() {
+        let out = format!("\n{}302 https://evil.example/\n", PROBE_MARKER);
+        assert_eq!(parse_entry_probe(&out).unwrap(), "/");
+    }
+
+    #[test]
+    fn a_refused_connection_is_an_error_the_poller_can_retry() {
+        // Verified shape: node writes this to stderr with no trailing newline.
+        let err = parse_entry_probe("connect ECONNREFUSED 127.0.0.1:39321").unwrap_err();
+        assert!(err.contains("ECONNREFUSED"), "{}", err);
+        assert_eq!(parse_entry_probe("").unwrap_err(), "no response");
+        assert!(parse_entry_probe("timed out waiting for the viewer")
+            .unwrap_err()
+            .contains("timed out"));
+    }
+
+    #[test]
+    fn an_unexpected_status_is_surfaced_rather_than_loaded() {
+        let out = format!("\n{}500 /\n", PROBE_MARKER);
+        assert!(parse_entry_probe(&out).unwrap_err().contains("500"));
+    }
+
+    #[test]
+    fn the_pane_url_is_loopback_and_carries_the_token() {
+        let url = build_url(47820, "/index.html?ws=abc", "TOKEN");
+        assert_eq!(url, "http://127.0.0.1:47820/index.html?ws=abc&token=TOKEN");
+        assert!(url.starts_with("http://127.0.0.1:"));
+
+        // A viewer that doesn't redirect gets a `?`, not a stray `&`.
+        assert_eq!(
+            build_url(47821, "/", "T"),
+            "http://127.0.0.1:47821/?token=T"
+        );
+    }
+
+    #[test]
+    fn tokens_are_unique_and_url_safe() {
+        let a = generate_token();
+        let b = generate_token();
+        assert_ne!(a, b);
+        assert_eq!(a.len(), 43); // 32 bytes, base64url, unpadded
+        assert!(a.chars().all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_'));
+    }
+
+    #[test]
+    fn shell_quoting_survives_a_hostile_path() {
+        assert_eq!(shell_quote("/a/b/cli.js"), "'/a/b/cli.js'");
+        assert_eq!(
+            shell_quote("/a/'; rm -rf /; '"),
+            r#"'/a/'\''; rm -rf /; '\'''"#
+        );
+    }
+
+    #[test]
+    fn a_singleton_clash_is_named_rather_than_left_as_a_dead_port() {
+        let msg = explain_start_failure(
+            "did not start listening on container port 39321 within 30s",
+            "Dashboard is running pid=1823\n",
+        );
+        assert!(msg.contains("show --kill"), "{}", msg);
+        assert!(msg.contains("pid=1823"), "{}", msg);
+    }
+
+    #[test]
+    fn an_ordinary_start_failure_keeps_the_error_and_any_log() {
+        assert_eq!(explain_start_failure("boom", "   "), "boom");
+        let msg = explain_start_failure("boom", "EADDRINUSE 39321");
+        assert!(msg.starts_with("boom"), "{}", msg);
+        assert!(msg.contains("EADDRINUSE 39321"), "{}", msg);
+    }
+
+    #[test]
+    fn the_viewer_port_range_is_bounded() {
+        assert_eq!(VIEWER_PORTS.clone().count(), 8);
+        // The auth bridge refuses to mirror exactly this range; if they ever
+        // drifted apart the pane would gain an ungated second front door.
+        assert_eq!(VIEWER_PORTS, crate::auth_bridge::RESERVED_CONTAINER_PORTS);
+    }
+
+    #[test]
+    fn an_off_status_says_nothing_is_running() {
+        let s = BrowserViewStatus::off(true);
+        assert!(s.enabled);
+        assert_eq!(s.state, BrowserViewState::Off);
+        assert!(s.url.is_none());
+    }
+
+    #[test]
+    fn an_unavailable_status_keeps_the_detail_the_user_needs() {
+        let mut d = PlaywrightDetection::default();
+        d.node_version = Some("22.11.0".to_string());
+        let s = BrowserViewStatus::unavailable(true, d, "install it".to_string());
+        assert_eq!(s.state, BrowserViewState::Unavailable);
+        assert_eq!(s.message.as_deref(), Some("install it"));
+        assert!(s.detection.is_some());
+        assert!(s.url.is_none());
+    }
+}

app/src-tauri/src/browser_view/page.rs

@@ -0,0 +1,375 @@
+//! Open a page in the container's browser, and resize it while it runs.
+//!
+//! The pane [watches](super) browsers something else published. This opens one:
+//! the user hands it a URL, it launches a browser inside the container,
+//! publishes it with `browser.bind()` so the pane picks it up, and holds the
+//! handle so the page can be navigated and **resized** afterwards.
+//!
+//! ## Why the handle has to be held
+//!
+//! Verified against a real bound browser: a second client cannot join one.
+//! `chromium.connect()` against the published endpoint times out in every URL
+//! form — the descriptor's socket speaks the dashboard's own transport, not the
+//! public connect protocol. So whoever launches the browser is the only process
+//! that can ever drive it. That is the whole reason this helper is a resident
+//! process rather than a one-shot `node -e` that exits.
+//!
+//! It also draws the line for the feature: pages *this* opens can be resized
+//! live; a browser `@playwright/mcp` launched can only be watched, and its size
+//! is whatever `--viewport-size` it was given.
+//!
+//! ## Control channel
+//!
+//! A JSON file in `/tmp`, polled by the helper. No port, no second listener, no
+//! addition to the proxy's attack surface — and it composes with the one exec
+//! path this codebase already has. Writes go through `node -e` rather than
+//! shell redirection so a URL never touches a shell.
+//!
+//! ## Viewport, and why it is the interesting part
+//!
+//! `page.setViewportSize()` genuinely reflows: measured on a page carrying a
+//! `@media (max-width: 900px)` rule, the rule fires at 800×600 and clears at
+//! 1440×900. Resizing the *window* the pane lives in does nothing of the sort —
+//! the viewer is a CDP screencast, so a bigger window is the same pixels drawn
+//! larger. This is what makes the pop-out usable as a responsive-design ruler.
+
+use serde::{Deserialize, Serialize};
+use tauri::AppHandle;
+
+use crate::commands::project_commands::emit_progress;
+use crate::docker::exec::exec_oneshot_as;
+
+use super::detect::PlaywrightDetection;
+
+/// Control file the helper polls, and the state file it writes back.
+const CONTROL_PATH: &str = "/tmp/triple-c-page-control.json";
+const STATE_PATH: &str = "/tmp/triple-c-page-state.json";
+/// Where the detached helper's own output goes, so a failed start has a trail.
+const HELPER_LOG: &str = "/tmp/triple-c-page.log";
+
+/// How long to wait for the helper to report that the page is up.
+const READY_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(45);
+/// Navigating a browser that is already up. One page load, not a cold start.
+const REUSE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(35);
+const READY_POLL: std::time::Duration = std::time::Duration::from_millis(400);
+
+/// A viewport, in CSS pixels.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+pub struct Viewport {
+    pub width: u32,
+    pub height: u32,
+}
+
+impl Viewport {
+    /// Clamped to something a browser will accept. A window dragged to nothing
+    /// must not ask Chromium for a zero-width page.
+    pub fn sane(width: u32, height: u32) -> Self {
+        Self {
+            width: width.clamp(200, 7680),
+            height: height.clamp(200, 4320),
+        }
+    }
+}
+
+/// What the helper reports about itself.
+#[derive(Debug, Clone, Deserialize, Serialize, Default)]
+pub struct PageState {
+    #[serde(default)]
+    pub ready: bool,
+    #[serde(default)]
+    pub url: Option<String>,
+    #[serde(default)]
+    pub viewport: Option<Viewport>,
+    #[serde(default)]
+    pub error: Option<String>,
+}
+
+/// Open `url` in a freshly launched, bound browser.
+///
+/// Replaces any page this opened before: one helper per container, because the
+/// pane shows one browser and a second would just compete for the pane.
+pub async fn open(
+    app: &AppHandle,
+    project_id: &str,
+    container_id: &str,
+    detection: &PlaywrightDetection,
+    url: &str,
+    viewport: Viewport,
+) -> Result<PageState, String> {
+    let core = detection.playwright_path.as_deref().ok_or_else(|| {
+        "Playwright isn't installed in this container — set it up from the Browser tab first."
+            .to_string()
+    })?;
+    // The directory of the resolved manifest is what `require()` wants.
+    let core_dir = core.trim_end_matches("/package.json");
+
+    // The executable is passed explicitly rather than left to Playwright's
+    // revision lookup: a container can hold browsers a given copy will not
+    // launch (see `detect::revision_skew`), and this is the one place we know
+    // which binary is actually on disk.
+    let executable = detection
+        .chromium_executable
+        .as_deref()
+        .filter(|_| detection.chromium_executable_exists);
+
+    // Reuse a helper that is already up. Relaunching would throw away the
+    // browser's cookies and storage — which for the auth case means signing in
+    // again to reach the second page, having just signed in on the first.
+    if state(container_id).await.ready {
+        emit_progress(app, project_id, "Navigating the container's browser…");
+        set_viewport(container_id, viewport).await?;
+        navigate(container_id, url).await?;
+        if let Some(state) = wait_for_url(container_id, url).await {
+            return Ok(state);
+        }
+        // It stopped answering; fall through and start a fresh one.
+    }
+
+    close(container_id).await;
+    // Cold start: a browser launch plus a page load, which is the several
+    // seconds the user would otherwise spend wondering whether the click
+    // registered.
+    emit_progress(app, project_id, "Launching a browser in the container…");
+
+    let config = serde_json::json!({
+        "core": core_dir,
+        "executable": executable,
+        "url": url,
+        "viewport": viewport,
+        "control": CONTROL_PATH,
+        "state": STATE_PATH,
+    });
+    let script = format!("const CFG={};{}", config, HELPER);
+
+    // Detached, for the same reason the viewer is: the process has to outlive
+    // the exec that started it, or the page closes the moment we return.
+    let launcher = format!(
+        "cd /workspace 2>/dev/null || true; rm -f {} {}; nohup node -e {} >{} 2>&1 &",
+        STATE_PATH,
+        CONTROL_PATH,
+        shell_quote(&script),
+        HELPER_LOG
+    );
+    exec_oneshot_as(
+        container_id,
+        "claude",
+        vec!["sh".to_string(), "-c".to_string(), launcher],
+        Vec::new(),
+    )
+    .await
+    .map_err(|e| format!("Could not start the browser helper: {}", e))?;
+
+    emit_progress(app, project_id, "Waiting for the page to load…");
+    wait_until_ready(container_id).await
+}
+
+/// Resize the open page. Cheap enough to call from a window-resize handler.
+pub async fn set_viewport(container_id: &str, viewport: Viewport) -> Result<(), String> {
+    write_control(
+        container_id,
+        serde_json::json!({ "viewport": viewport }).to_string(),
+    )
+    .await
+}
+
+/// Navigate the open page without relaunching the browser.
+pub async fn navigate(container_id: &str, url: &str) -> Result<(), String> {
+    write_control(container_id, serde_json::json!({ "url": url }).to_string()).await
+}
+
+/// Ask the helper to shut down. Best effort: a container that has none is the
+/// normal case, and the caller is usually about to start one anyway.
+pub async fn close(container_id: &str) {
+    let _ = write_control(container_id, serde_json::json!({ "close": true }).to_string()).await;
+}
+
+/// Current state, or a default when no helper has ever run here.
+pub async fn state(container_id: &str) -> PageState {
+    let script = format!(
+        "try{{process.stdout.write(require('fs').readFileSync('{}','utf8'));}}catch(e){{}}",
+        STATE_PATH
+    );
+    let Ok((out, _)) = exec_oneshot_as(
+        container_id,
+        "claude",
+        vec!["node".to_string(), "-e".to_string(), script],
+        Vec::new(),
+    )
+    .await
+    else {
+        return PageState::default();
+    };
+    serde_json::from_str(out.trim()).unwrap_or_default()
+}
+
+/// Write the control file through Node rather than a shell redirect, so a URL
+/// is never interpreted by `sh`.
+async fn write_control(container_id: &str, json: String) -> Result<(), String> {
+    let script = format!(
+        "require('fs').writeFileSync('{}',process.argv[1]);",
+        CONTROL_PATH
+    );
+    exec_oneshot_as(
+        container_id,
+        "claude",
+        vec!["node".to_string(), "-e".to_string(), script, json],
+        Vec::new(),
+    )
+    .await
+    .map(|_| ())
+    .map_err(|e| format!("Could not reach the browser helper: {}", e))
+}
+
+/// Wait for a *running* helper to report the URL we just asked it for.
+///
+/// Bounded much tighter than a cold start: the browser is already up, so this
+/// is one navigation. `None` means it stopped answering, and the caller starts
+/// a fresh helper rather than reporting a page that isn't there.
+async fn wait_for_url(container_id: &str, url: &str) -> Option<PageState> {
+    let deadline = std::time::Instant::now() + REUSE_TIMEOUT;
+    loop {
+        let state = state(container_id).await;
+        if state.ready && state.url.as_deref() == Some(url) {
+            return Some(state);
+        }
+        if std::time::Instant::now() >= deadline {
+            return None;
+        }
+        tokio::time::sleep(READY_POLL).await;
+    }
+}
+
+/// Poll the state file until the helper says the page is up, or says why not.
+async fn wait_until_ready(container_id: &str) -> Result<PageState, String> {
+    let deadline = std::time::Instant::now() + READY_TIMEOUT;
+    loop {
+        let state = state(container_id).await;
+        if let Some(error) = state.error.clone() {
+            return Err(error);
+        }
+        if state.ready {
+            return Ok(state);
+        }
+        if std::time::Instant::now() >= deadline {
+            return Err(format!(
+                "The browser didn't come up within {}s. Its log is at {} inside the container.",
+                READY_TIMEOUT.as_secs(),
+                HELPER_LOG
+            ));
+        }
+        tokio::time::sleep(READY_POLL).await;
+    }
+}
+
+/// Single-quote for `sh`, the same way [`super`] does for the viewer's paths.
+fn shell_quote(s: &str) -> String {
+    format!("'{}'", s.replace('\'', r"'\''"))
+}
+
+/// The resident helper, appended to a `const CFG={…};` prelude.
+///
+/// Deliberately one string passed as a single `argv` element — no shell parsing
+/// of any part of it, exactly like `detect`'s probe. It launches, binds, and
+/// then polls the control file; every failure path writes the state file, so a
+/// helper that dies during startup is reported rather than waited out.
+const HELPER: &str = concat!(
+    r#"const fs=require('fs');"#,
+    r#"const {chromium}=require(CFG.core);"#,
+    r#"const write=(o)=>{try{fs.writeFileSync(CFG.state,JSON.stringify(o));}catch(e){}};"#,
+    r#"const fail=(e)=>{write({ready:false,error:String(e&&e.message||e)});process.exit(1);};"#,
+    r#"process.on('unhandledRejection',fail);"#,
+    r#"(async()=>{"#,
+    // `chromiumSandbox:false` because the container has no user namespaces to
+    // give Chromium; headless because there is no display, which is also the
+    // only mode the dashboard can screencast anyway.
+    r#"const opts={headless:true,chromiumSandbox:false};"#,
+    r#"if(CFG.executable)opts.executablePath=CFG.executable;"#,
+    r#"const browser=await chromium.launch(opts);"#,
+    r#"const ctx=await browser.newContext({viewport:CFG.viewport});"#,
+    r#"const page=await ctx.newPage();"#,
+    // Bind before navigating: the pane should show the page loading rather than
+    // appearing once it is done.
+    r#"await browser.bind('claude',{metadata:{source:'triple-c'}});"#,
+    r#"let current=CFG.url,viewport=CFG.viewport;"#,
+    r#"const report=()=>write({ready:true,url:current,viewport});"#,
+    r#"try{await page.goto(CFG.url,{waitUntil:'domcontentloaded',timeout:30000});}catch(e){}"#,
+    r#"report();"#,
+    // The control loop. A poll, not a watcher: `fs.watch` misses writes on some
+    // filesystems and this costs nothing at 4 Hz.
+    r#"setInterval(async()=>{let c;try{c=JSON.parse(fs.readFileSync(CFG.control,'utf8'));}catch(e){return;}"#,
+    r#"try{fs.unlinkSync(CFG.control);}catch(e){}"#,
+    r#"if(c.close){await browser.close().catch(()=>{});write({ready:false});process.exit(0);}"#,
+    r#"if(c.viewport){viewport=c.viewport;await page.setViewportSize(c.viewport).catch(()=>{});}"#,
+    r#"if(c.url&&c.url!==current){current=c.url;await page.goto(c.url,{waitUntil:'domcontentloaded',timeout:30000}).catch(()=>{});}"#,
+    r#"report();},250);"#,
+    // A browser that dies (crash, or the user closing the last page) must not
+    // leave a helper claiming a live page.
+    r#"browser.on('disconnected',()=>{write({ready:false});process.exit(0);});"#,
+    r#"})().catch(fail);"#,
+);
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_helper_is_one_argv_element_with_no_shell_hazards() {
+        // Same rule as the detect probe: it is passed as a single argument, so
+        // it must contain neither a newline nor a single quote that would end
+        // the quoting `open` wraps it in.
+        assert!(!HELPER.contains('\n'), "{}", HELPER);
+        assert!(HELPER.contains("chromium.launch"), "{}", HELPER);
+    }
+
+    #[test]
+    fn the_helper_binds_so_the_pane_can_see_the_page() {
+        // Without this the page opens and the pane shows nothing — the whole
+        // feature hinges on the browser being published.
+        assert!(HELPER.contains("browser.bind('claude'"), "{}", HELPER);
+    }
+
+    #[test]
+    fn the_helper_reports_startup_failures_instead_of_hanging() {
+        // `wait_until_ready` polls the state file; a helper that dies silently
+        // would turn every failure into a 45-second timeout.
+        assert!(HELPER.contains("unhandledRejection"), "{}", HELPER);
+        assert!(HELPER.contains("error:String"), "{}", HELPER);
+    }
+
+    #[test]
+    fn a_viewport_is_clamped_to_something_a_browser_accepts() {
+        assert_eq!(Viewport::sane(0, 0), Viewport { width: 200, height: 200 });
+        assert_eq!(
+            Viewport::sane(99_999, 99_999),
+            Viewport { width: 7680, height: 4320 }
+        );
+        assert_eq!(
+            Viewport::sane(1440, 900),
+            Viewport { width: 1440, height: 900 }
+        );
+    }
+
+    #[test]
+    fn a_url_is_never_parsed_by_a_shell() {
+        // The launcher runs through `sh -c`, so the script is quoted with the
+        // POSIX close-escape-reopen form: the embedded quote becomes `'\''`,
+        // which leaves the `;rm` inside the string rather than starting a new
+        // command. (A naive "the output must not contain ';rm'" check fails
+        // here and would be wrong — that substring is *inside* the quoting.)
+        assert_eq!(
+            shell_quote("http://x/?a=1&b=2';rm -rf /"),
+            r"'http://x/?a=1&b=2'\'';rm -rf /'"
+        );
+        // The control channel doesn't go near a shell at all: the JSON travels
+        // as an argv element to `node`.
+        assert!(!HELPER.contains("exec("), "{}", HELPER);
+    }
+
+    #[test]
+    fn state_defaults_to_not_ready_rather_than_failing() {
+        // An empty/absent state file is the normal case before anything runs.
+        let s: PageState = serde_json::from_str("{}").unwrap();
+        assert!(!s.ready);
+        assert!(s.error.is_none());
+    }
+}

app/src-tauri/src/browser_view/popout.rs

@@ -0,0 +1,338 @@
+//! The browser view in a window of its own.
+//!
+//! Watching a browser and working in a terminal are the same task done at the
+//! same time, and a tab can only be one of them. So the pane can be detached
+//! into a second OS window — put on the other monitor, or pinned on top of
+//! whatever else is in front.
+//!
+//! ## Why this is a native window and not a second iframe
+//!
+//! The window loads the *same* token-bearing loopback URL the pane's iframe
+//! uses ([`crate::browser_view::BrowserViewStatus::url`]), as its top-level
+//! document. That has two consequences worth stating:
+//!
+//! - It is a **remote-origin** webview. No capability lists this window, so it
+//!   has no IPC surface at all — `invoke` is not reachable from it, which is
+//!   exactly right for a page served out of a container. Do not add one.
+//! - The app CSP does not apply, and does not need to: `frame-src` exists to
+//!   constrain what the *app's* document may embed, and this is not embedded.
+//!   The port is still confined to [`crate::browser_view::proxy`]'s range and
+//!   still gated by the session token, which is what actually protects it.
+//!
+//! ## Lifetime
+//!
+//! The window is owned by the session, not by the user's patience: when a view
+//! stops — the user pressed Stop, the container went away, the viewer died —
+//! the supervisor's teardown calls [`close`], because a window left showing a
+//! dead viewer is worse than no window. The reverse is not true; closing the
+//! window leaves the view running, and the pane takes it back into the tab.
+
+use std::collections::HashMap;
+use std::sync::{Mutex, OnceLock};
+use std::time::Duration;
+
+use serde::Serialize;
+use tauri::{AppHandle, Emitter, Manager, WebviewUrl, WebviewWindowBuilder, WindowEvent};
+
+/// Emitted when a pop-out opens or closes. Payload: [`PopoutState`] plus the
+/// project id.
+///
+/// The window can close without the app asking it to — the user hits its X, or
+/// a teardown takes it — so the pane learns about it the same way it learns
+/// about everything else here, by listening.
+const POPOUT_EVENT: &str = "browser-view-popout-changed";
+
+/// What the pane needs to render its pop-out controls.
+///
+/// Both fields are read from the window itself rather than remembered on either
+/// side: the pane is unmounted whenever another Project Home sub-tab is
+/// selected, so anything it merely *remembers* about the window is gone by the
+/// time the user comes back, while the window is still there.
+#[derive(Debug, Clone, Copy, Serialize)]
+pub struct PopoutState {
+    pub open: bool,
+    pub always_on_top: bool,
+}
+
+impl PopoutState {
+    const CLOSED: Self = Self {
+        open: false,
+        always_on_top: false,
+    };
+}
+
+/// Tauri window labels admit `[a-zA-Z0-9-/:_]` only. Project ids are UUIDs, so
+/// this never fires in practice; it exists so a hand-edited `projects.json`
+/// cannot produce a label Tauri rejects at build time.
+pub fn window_label(project_id: &str) -> String {
+    let id: String = project_id
+        .chars()
+        .map(|c| if c.is_ascii_alphanumeric() || c == '-' || c == '_' { c } else { '_' })
+        .collect();
+    format!("browser-view-{}", id)
+}
+
+/// Open the pop-out, or raise it if it is already open.
+///
+/// `url` is the live session's URL; the caller has already established that the
+/// view is running, because there is nothing to show otherwise.
+pub fn open(
+    app: &AppHandle,
+    project_id: &str,
+    project_name: &str,
+    url: &str,
+    always_on_top: bool,
+) -> Result<(), String> {
+    let label = window_label(project_id);
+
+    if let Some(window) = app.get_webview_window(&label) {
+        // Asking twice means "I can't see it", not "open another".
+        let _ = window.unminimize();
+        let _ = window.set_focus();
+        let _ = window.set_always_on_top(always_on_top);
+        emit(app, project_id, state(app, project_id));
+        return Ok(());
+    }
+
+    let parsed = url
+        .parse()
+        .map_err(|e| format!("The browser view's address is not a URL: {}", e))?;
+
+    let project_id_owned = project_id.to_string();
+    let app_for_event = app.clone();
+
+    let window = WebviewWindowBuilder::new(app, &label, WebviewUrl::External(parsed))
+        .title(format!("{} — browser", project_name))
+        .inner_size(1100.0, 820.0)
+        .min_inner_size(480.0, 360.0)
+        .always_on_top(always_on_top)
+        .build()
+        .map_err(|e| format!("Could not open the browser window: {}", e))?;
+
+    // Closed from its own titlebar, this is the only thing that tells the pane
+    // to take the view back into the tab. `Resized` drives match-window mode —
+    // see `set_match_window`.
+    window.on_window_event(move |event| match event {
+        WindowEvent::Destroyed => {
+            set_match_window(&project_id_owned, false);
+            emit(&app_for_event, &project_id_owned, PopoutState::CLOSED);
+        }
+        WindowEvent::Resized(size) => {
+            on_resized(&app_for_event, &project_id_owned, size.width, size.height);
+        }
+        _ => {}
+    });
+
+    log::info!("Browser view: popped out for project {}", project_id);
+    emit(app, project_id, state(app, project_id));
+    Ok(())
+}
+
+/// Close the pop-out if there is one. Safe to call when there isn't.
+///
+/// `destroy`, not `close`: `close` raises `CloseRequested`, and the app's
+/// window-event handler treats that as a request to quit for the main window.
+/// Nothing here should ever be able to be mistaken for that.
+///
+/// A failure is **returned, not logged and forgotten**. The pane puts its
+/// iframe back the moment it believes the window is gone, so reporting a close
+/// that did not happen is how you end up with two viewers driving one browser —
+/// the exact state the iframe is dropped to prevent.
+pub fn close(app: &AppHandle, project_id: &str) -> Result<(), String> {
+    if let Some(window) = app.get_webview_window(&window_label(project_id)) {
+        window.destroy().map_err(|e| {
+            log::warn!(
+                "Browser view: could not close the pop-out for project {}: {}",
+                project_id,
+                e
+            );
+            format!("Could not close the browser window: {}", e)
+        })?;
+    }
+    // `Destroyed` covers the normal path; a window that was already gone still
+    // owes the pane an answer.
+    emit(app, project_id, PopoutState::CLOSED);
+    Ok(())
+}
+
+/// Whether the window exists and how it is stacked, read from the window.
+pub fn state(app: &AppHandle, project_id: &str) -> PopoutState {
+    match app.get_webview_window(&window_label(project_id)) {
+        Some(window) => PopoutState {
+            open: true,
+            // A window that cannot answer is not a reason to fail the call; the
+            // pin is a preference, and "not pinned" is the safe reading.
+            always_on_top: window.is_always_on_top().unwrap_or(false),
+        },
+        None => PopoutState::CLOSED,
+    }
+}
+
+/// Pin the pop-out above other windows, or unpin it. No-op when it is closed.
+pub fn set_always_on_top(app: &AppHandle, project_id: &str, on_top: bool) -> Result<(), String> {
+    let Some(window) = app.get_webview_window(&window_label(project_id)) else {
+        return Ok(());
+    };
+    window
+        .set_always_on_top(on_top)
+        .map_err(|e| format!("Could not change the window's stacking: {}", e))?;
+    emit(app, project_id, state(app, project_id));
+    Ok(())
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Match-window mode
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Projects whose pop-out is driving the page's viewport, and the generation of
+/// the latest resize for each — the debounce is "did anything else arrive while
+/// I slept?", which needs no timer to cancel.
+static MATCH_WINDOW: OnceLock<Mutex<HashMap<String, (bool, u64)>>> = OnceLock::new();
+
+/// How long the window has to stop moving before the page is resized.
+///
+/// A drag emits `Resized` continuously; each one costs a container exec, and
+/// Chromium relayouts the page. Settling first turns a drag into one resize.
+const RESIZE_SETTLE: Duration = Duration::from_millis(300);
+
+fn match_window_map() -> &'static Mutex<HashMap<String, (bool, u64)>> {
+    MATCH_WINDOW.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+/// Turn match-window mode on or off for a project.
+///
+/// Only ever affects a page **Triple-C opened** — a bound browser cannot be
+/// joined by a second client, so a page `@playwright/mcp` launched keeps
+/// whatever viewport it was given. See [`super::page`].
+pub fn set_match_window(project_id: &str, enabled: bool) {
+    let mut map = match_window_map().lock().unwrap_or_else(|e| e.into_inner());
+    let entry = map.entry(project_id.to_string()).or_insert((false, 0));
+    entry.0 = enabled;
+}
+
+pub fn match_window(project_id: &str) -> bool {
+    match_window_map()
+        .lock()
+        .unwrap_or_else(|e| e.into_inner())
+        .get(project_id)
+        .map(|(on, _)| *on)
+        .unwrap_or(false)
+}
+
+/// The pop-out's current inner size, for applying match-window immediately
+/// rather than only on the next drag.
+pub fn inner_size(app: &AppHandle, project_id: &str) -> Option<(u32, u32)> {
+    let window = app.get_webview_window(&window_label(project_id))?;
+    let size = window.inner_size().ok()?;
+    Some((size.width, size.height))
+}
+
+/// Debounce a resize, then push the settled size into the page's viewport.
+fn on_resized(app: &AppHandle, project_id: &str, width: u32, height: u32) {
+    let generation = {
+        let mut map = match_window_map().lock().unwrap_or_else(|e| e.into_inner());
+        let Some(entry) = map.get_mut(project_id) else {
+            return;
+        };
+        if !entry.0 {
+            return;
+        }
+        entry.1 += 1;
+        entry.1
+    };
+
+    let app = app.clone();
+    let project_id = project_id.to_string();
+    tauri::async_runtime::spawn(async move {
+        tokio::time::sleep(RESIZE_SETTLE).await;
+        // Superseded by a later resize: that one will do the work.
+        {
+            let map = match_window_map().lock().unwrap_or_else(|e| e.into_inner());
+            match map.get(&project_id) {
+                Some((true, latest)) if *latest == generation => {}
+                _ => return,
+            }
+        }
+
+        let state = app.state::<crate::AppState>();
+        let Some(container_id) = state
+            .projects_store
+            .get(&project_id)
+            .and_then(|p| p.container_id)
+        else {
+            return;
+        };
+        if let Err(e) = super::page::set_viewport(
+            &container_id,
+            super::page::Viewport::sane(width, height),
+        )
+        .await
+        {
+            log::debug!("Browser view: could not match the page to the window: {}", e);
+        }
+    });
+}
+
+fn emit(app: &AppHandle, project_id: &str, state: PopoutState) {
+    let _ = app.emit(
+        POPOUT_EVENT,
+        serde_json::json!({
+            "project_id": project_id,
+            "open": state.open,
+            "always_on_top": state.always_on_top,
+        }),
+    );
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn labels_are_derived_from_the_project_and_are_tauri_safe() {
+        assert_eq!(
+            window_label("6b1f4a2c-0d5e-4f9a-9c11-2f0b7d3e8a44"),
+            "browser-view-6b1f4a2c-0d5e-4f9a-9c11-2f0b7d3e8a44"
+        );
+        assert_eq!(window_label("a b/c.d"), "browser-view-a_b_c_d");
+    }
+
+    #[test]
+    fn distinct_projects_get_distinct_windows() {
+        assert_ne!(window_label("alpha"), window_label("beta"));
+    }
+
+    #[test]
+    fn match_window_is_off_until_asked_for_and_is_per_project() {
+        assert!(!match_window("mw-a"));
+        set_match_window("mw-a", true);
+        assert!(match_window("mw-a"));
+        // Another project's window must not start driving its page too.
+        assert!(!match_window("mw-b"));
+        set_match_window("mw-a", false);
+        assert!(!match_window("mw-a"));
+    }
+
+    #[test]
+    fn a_resize_supersedes_the_one_before_it() {
+        // The debounce is a generation counter, not a cancellable timer: only
+        // the newest resize of a drag survives to touch the container.
+        set_match_window("mw-gen", true);
+        let read = || {
+            match_window_map()
+                .lock()
+                .unwrap()
+                .get("mw-gen")
+                .map(|(_, g)| *g)
+                .unwrap()
+        };
+        let before = read();
+        {
+            let mut map = match_window_map().lock().unwrap();
+            let entry = map.get_mut("mw-gen").unwrap();
+            entry.1 += 1;
+        }
+        assert!(read() > before);
+        set_match_window("mw-gen", false);
+    }
+}

app/src-tauri/src/browser_view/proxy.rs

@@ -0,0 +1,793 @@
+//! The host-side, token-gated front door for one project's Playwright viewer.
+//!
+//! ## Why this is not `PortForward` on its own
+//!
+//! [`crate::auth_bridge::tunnel::PortForward`] mirrors a container loopback port
+//! onto the *same* host loopback port with **no authentication at all**. That is
+//! the right trade for the auth bridge — the things it exposes are short-lived
+//! OAuth callback listeners whose whole purpose is to receive one unauthenticated
+//! request — but it is the wrong trade here. The Playwright viewer is full mouse
+//! and keyboard control of a browser running inside a container that has
+//! passwordless sudo and, very often, the host's Docker socket bind-mounted. A
+//! bare loopback port is reachable by:
+//!
+//! * any other local user on a multi-user host, and
+//! * **any web page the user happens to have open**, via localhost port scanning
+//!   or DNS rebinding.
+//!
+//! So this module keeps the tunnel half of the auth bridge (a per-connection
+//! `socat` exec through the Docker API — see
+//! [`crate::auth_bridge::tunnel::tunnel_connection_with_prelude`]) and replaces
+//! the listener half with one that authenticates before a single byte reaches
+//! the container. There is therefore exactly **one** host-bound socket per
+//! session, and it is gated.
+//!
+//! ## The gate
+//!
+//! Gating happens on the first HTTP request head of every accepted TCP
+//! connection, before anything is forwarded. To get a connection through you
+//! must satisfy all of:
+//!
+//! 1. `Host` is `127.0.0.1:<port>` or `localhost:<port>` — this is the
+//!    anti-DNS-rebinding check. A page on `evil.com` that rebinds its name to
+//!    127.0.0.1 still sends `Host: evil.com`.
+//! 2. Either
+//!    * the request carries the session token (in `?token=`, in a `Cookie`, or
+//!      in the query of a same-origin `Referer`), **or**
+//!    * `Origin` / `Referer` is exactly this proxy's own origin — i.e. the
+//!      request was issued by a document that we already served, which itself
+//!      had to present the token. This is what lets the viewer's own
+//!      sub-resource and WebSocket requests through: a browser will not let a
+//!      hostile page forge either header, and requests that carry neither (a
+//!      cross-site `<script src>` or a top-level navigation) are rejected.
+//!
+//! Once the first head passes, the rest of the connection is spliced verbatim,
+//! so HTTP/1.1 keep-alive, the WebSocket upgrade and the CDP screencast frames
+//! all pass through untouched and protocol-agnostically. Riding an existing
+//! connection is not an escalation: opening one required the token.
+//!
+//! ## Port allocation and the CSP
+//!
+//! Host ports come from the small fixed range [`PROXY_PORTS`]. That is
+//! deliberate: `tauri.conf.json`'s `frame-src` has to name every origin the pane
+//! may embed, and CSP has no port wildcards short of `http://127.0.0.1:*`.
+//! Allocating from a bounded, known range keeps that directive an exact
+//! enumeration instead of "any localhost port".
+
+use std::net::{Ipv4Addr, SocketAddr};
+
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::{TcpListener, TcpStream};
+use tokio::task::{JoinHandle, JoinSet};
+
+use crate::auth_bridge::proc_net::PortFamily;
+use crate::auth_bridge::tunnel::tunnel_connection_with_prelude;
+
+/// Host loopback ports the pane may be served on, and therefore the exact set of
+/// origins enumerated in the app's `frame-src`. Keep the two in sync: adding a
+/// port here without adding it to `tauri.conf.json` produces a pane that is
+/// silently blocked by CSP.
+pub const PROXY_PORTS: std::ops::RangeInclusive<u16> = 47820..=47827;
+
+/// Ceiling on the request head we will buffer before deciding. Real heads are
+/// well under 8 KiB; anything larger is either broken or hostile.
+const MAX_HEAD: usize = 32 * 1024;
+
+/// How long a freshly accepted connection has to produce a complete request
+/// head. Prevents a slowloris from pinning accept-loop tasks.
+const HEAD_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
+
+const REFUSAL_BODY: &str = concat!(
+    "<!doctype html><meta charset=\"utf-8\">",
+    "<title>Not available</title>",
+    "<p>This Triple-C browser view is only reachable from the app that started it.</p>"
+);
+
+/// A bound, token-gated host listener in front of one container-side viewer.
+///
+/// The accept loop owns the [`TcpListener`] and the [`JoinSet`] of live
+/// connections, so aborting the one task handle releases the port *and* tears
+/// down everything under it. [`Drop`] does that as a backstop;
+/// [`BrowserViewProxy::shutdown`] does it deterministically by also awaiting the
+/// aborted task, so the port is provably free before the caller continues.
+pub struct BrowserViewProxy {
+    pub port: u16,
+    task: JoinHandle<()>,
+}
+
+impl Drop for BrowserViewProxy {
+    fn drop(&mut self) {
+        self.task.abort();
+    }
+}
+
+impl BrowserViewProxy {
+    /// Take the first free port in [`PROXY_PORTS`] on the host loopback and
+    /// start gating connections into `container_id`'s `container_port`.
+    pub async fn bind(
+        container_id: String,
+        container_port: u16,
+        family: PortFamily,
+        token: String,
+    ) -> Result<Self, String> {
+        let mut last_err = None;
+        for port in PROXY_PORTS {
+            // SECURITY BOUNDARY: 127.0.0.1 ONLY, never 0.0.0.0. Unlike
+            // `web_terminal`, which binds a wildcard on purpose because remote
+            // access *is* its feature, this pane is remote control of a browser
+            // in a privileged container and must never leave the host. Do not
+            // "fix" a connectivity problem by widening this address.
+            match TcpListener::bind(SocketAddr::from((Ipv4Addr::LOCALHOST, port))).await {
+                Ok(listener) => {
+                    let task = tokio::spawn(accept_loop(
+                        listener,
+                        container_id,
+                        family.socat_target(container_port),
+                        container_port,
+                        token,
+                        self_origins(port),
+                        host_authorities(port),
+                    ));
+                    log::info!("Browser view: proxy listening on 127.0.0.1:{}", port);
+                    return Ok(Self { port, task });
+                }
+                Err(e) => last_err = Some(e),
+            }
+        }
+        Err(format!(
+            "No free host port in {}–{} for the browser view proxy ({}). \
+             Close another project's browser view and try again.",
+            PROXY_PORTS.start(),
+            PROXY_PORTS.end(),
+            last_err
+                .map(|e| e.to_string())
+                .unwrap_or_else(|| "range empty".to_string())
+        ))
+    }
+
+    /// Stop accepting, release the host port and abort every live connection.
+    pub async fn shutdown(&mut self) {
+        self.task.abort();
+        let _ = (&mut self.task).await;
+        log::info!("Browser view: proxy on 127.0.0.1:{} released", self.port);
+    }
+}
+
+/// The origins a request may legitimately claim to come from.
+fn self_origins(port: u16) -> Vec<String> {
+    vec![
+        format!("http://127.0.0.1:{}", port),
+        format!("http://localhost:{}", port),
+    ]
+}
+
+/// The `Host` values we will answer to. Anything else is a rebinding attempt.
+fn host_authorities(port: u16) -> Vec<String> {
+    vec![
+        format!("127.0.0.1:{}", port),
+        format!("localhost:{}", port),
+    ]
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn accept_loop(
+    listener: TcpListener,
+    container_id: String,
+    target: String,
+    container_port: u16,
+    token: String,
+    origins: Vec<String>,
+    authorities: Vec<String>,
+) {
+    let mut conns: JoinSet<()> = JoinSet::new();
+
+    loop {
+        let accepted = tokio::select! {
+            r = listener.accept() => r,
+            // Reap finished connections so the set can't grow without bound.
+            // An empty set yields `None`, the pattern fails, and the branch is
+            // simply dropped from the select.
+            Some(_) = conns.join_next() => continue,
+        };
+
+        match accepted {
+            Ok((stream, _peer)) => {
+                let _ = stream.set_nodelay(true);
+                conns.spawn(serve_connection(
+                    stream,
+                    container_id.clone(),
+                    target.clone(),
+                    container_port,
+                    token.clone(),
+                    origins.clone(),
+                    authorities.clone(),
+                ));
+            }
+            Err(e) => {
+                log::warn!("Browser view: accept failed: {} — stopping proxy listener", e);
+                return;
+            }
+        }
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn serve_connection(
+    mut stream: TcpStream,
+    container_id: String,
+    target: String,
+    container_port: u16,
+    token: String,
+    origins: Vec<String>,
+    authorities: Vec<String>,
+) {
+    let (head, head_len) = match tokio::time::timeout(HEAD_TIMEOUT, read_head(&mut stream)).await {
+        Ok(Ok(head)) => head,
+        Ok(Err(e)) => {
+            log::debug!("Browser view: dropping connection: {}", e);
+            let _ = reject(&mut stream, 400, "Bad Request").await;
+            return;
+        }
+        Err(_) => {
+            log::debug!("Browser view: dropping connection: no request head within timeout");
+            return;
+        }
+    };
+
+    // Authorize against the head slice only — never the trailing body bytes.
+    let head_text = String::from_utf8_lossy(&head[..head_len]).into_owned();
+    let verdict = authorize(&head_text, &token, &origins, &authorities);
+    if verdict != Verdict::Allow {
+        log::warn!(
+            "Browser view: rejected a connection on the proxy for container port {} ({:?})",
+            container_port,
+            verdict
+        );
+        let _ = reject(&mut stream, 403, "Forbidden").await;
+        return;
+    }
+
+    // Authorized: hand the socket to the same socat-over-Docker-exec tunnel the
+    // auth bridge uses, replaying the head we had to buffer to make the call.
+    tunnel_connection_with_prelude(container_id, target, stream, container_port, head).await;
+}
+
+/// Read bytes until the end of the HTTP request head (`\r\n\r\n`), or fail.
+/// Returns the bytes read so far and the index one past the head terminator.
+///
+/// Both halves matter. The caller must replay the **whole** buffer into the
+/// tunnel — a client may pipeline body bytes into the same packet as the head —
+/// but it must authorize against the **head only**. Returning just the buffer
+/// is how a request body gets parsed as headers, which defeats the token gate
+/// and the anti-rebinding check outright: a cross-site `fetch` with a
+/// `text/plain` body of `a=x\r\nSec-Fetch-Site: same-origin\r\n` is not
+/// preflighted, and the forged line wins the last-occurrence match below.
+async fn read_head(stream: &mut TcpStream) -> Result<(Vec<u8>, usize), String> {
+    let mut buf = Vec::with_capacity(1024);
+    let mut chunk = [0u8; 1024];
+    loop {
+        let n = stream
+            .read(&mut chunk)
+            .await
+            .map_err(|e| format!("read failed: {}", e))?;
+        if n == 0 {
+            return Err("connection closed before a request head arrived".to_string());
+        }
+        buf.extend_from_slice(&chunk[..n]);
+        if let Some(head_end) = find_head_end(&buf) {
+            return Ok((buf, head_end));
+        }
+        if buf.len() > MAX_HEAD {
+            return Err(format!("request head exceeded {} bytes", MAX_HEAD));
+        }
+    }
+}
+
+/// Index just past the blank line terminating the head, if it has arrived.
+/// Tolerates a bare-LF terminator, which some minimal clients still emit.
+fn find_head_end(buf: &[u8]) -> Option<usize> {
+    buf.windows(4)
+        .position(|w| w == b"\r\n\r\n")
+        .map(|i| i + 4)
+        .or_else(|| buf.windows(2).position(|w| w == b"\n\n").map(|i| i + 2))
+}
+
+async fn reject(stream: &mut TcpStream, code: u16, reason: &str) -> std::io::Result<()> {
+    let body = REFUSAL_BODY;
+    let response = format!(
+        "HTTP/1.1 {} {}\r\n\
+         Content-Type: text/html; charset=utf-8\r\n\
+         Content-Length: {}\r\n\
+         Cache-Control: no-store\r\n\
+         Connection: close\r\n\r\n{}",
+        code,
+        reason,
+        body.len(),
+        body
+    );
+    stream.write_all(response.as_bytes()).await?;
+    stream.shutdown().await
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The gate itself — pure, so it can be tested without sockets
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum Verdict {
+    Allow,
+    /// No request line, or one we can't parse.
+    Malformed,
+    /// `Host` is not one of ours — a rebinding attempt, or a stray client.
+    BadHost,
+    /// Well-formed and addressed to us, but presented no token and no proof of
+    /// having come from a document we served.
+    Unauthenticated,
+}
+
+/// Decide whether the connection whose first request head this is may be
+/// spliced into the container. See the module docs for the rules.
+pub(crate) fn authorize(
+    head: &str,
+    token: &str,
+    self_origins: &[String],
+    host_authorities: &[String],
+) -> Verdict {
+    let mut lines = head.split(['\r', '\n']).filter(|l| !l.is_empty());
+
+    let Some(request_line) = lines.next() else {
+        return Verdict::Malformed;
+    };
+    // "GET /path?query HTTP/1.1"
+    let mut parts = request_line.split(' ');
+    let (Some(_method), Some(request_target)) = (parts.next(), parts.next()) else {
+        return Verdict::Malformed;
+    };
+    if !request_target.starts_with('/') && !request_target.starts_with("http") {
+        // CONNECT and origin-form-violating targets are not something the
+        // viewer ever sends; refuse to be used as a forward proxy.
+        return Verdict::Malformed;
+    }
+
+    let mut host = None;
+    let mut origin = None;
+    let mut referer = None;
+    let mut cookie = None;
+    let mut fetch_site = None;
+    for line in lines {
+        let Some((name, value)) = line.split_once(':') else {
+            continue;
+        };
+        let value = value.trim();
+        // Duplicates of a security-relevant header are refused rather than
+        // resolved. Last-occurrence-wins is what turns any header-smuggling
+        // primitive into a full bypass, and no legitimate client sends two.
+        match name.trim().to_ascii_lowercase().as_str() {
+            "host" if host.is_some() => return Verdict::Malformed,
+            "origin" if origin.is_some() => return Verdict::Malformed,
+            "sec-fetch-site" if fetch_site.is_some() => return Verdict::Malformed,
+            "host" => host = Some(value),
+            "origin" => origin = Some(value),
+            "referer" => referer = Some(value),
+            "cookie" => cookie = Some(value),
+            "sec-fetch-site" => fetch_site = Some(value),
+            _ => {}
+        }
+    }
+
+    // 1. Anti-rebinding. A hostile page that points its own name at 127.0.0.1
+    //    still sends its own name here.
+    match host {
+        Some(h) if host_authorities.iter().any(|a| a.eq_ignore_ascii_case(h)) => {}
+        _ => return Verdict::BadHost,
+    }
+
+    // 2a. An explicit token, from the request target, a cookie, or the query of
+    //     the referring document's URL (same-origin requests send the full URL,
+    //     query included, under the default referrer policy).
+    if query_token(request_target).is_some_and(|t| tokens_match(t, token))
+        || cookie_token(cookie.unwrap_or("")).is_some_and(|t| tokens_match(t, token))
+        || referer.and_then(query_token).is_some_and(|t| tokens_match(t, token))
+    {
+        return Verdict::Allow;
+    }
+
+    // 2b. …or proof that a document we already served issued this request. The
+    //     viewer's WebSocket upgrade carries `Origin` and no `Referer`, and
+    //     nothing in it is under our control, so this is the clause that makes
+    //     the pane work at all. A browser will not let a hostile page forge
+    //     either header; a request with neither (cross-site `<script src>`,
+    //     top-level navigation, `curl`) falls through and is refused.
+    if origin.is_some_and(|o| origin_is_self(o, self_origins))
+        || referer.is_some_and(|r| origin_is_self(r, self_origins))
+        // Fetch metadata says the same thing as `Origin`, and keeps saying it
+        // for the plain sub-resource loads that carry no `Origin` and whose
+        // `Referer` a `no-referrer` policy could strip. `Sec-Fetch-Site` is a
+        // forbidden header, so page script cannot set it either.
+        || fetch_site.is_some_and(|s| s.eq_ignore_ascii_case("same-origin"))
+    {
+        return Verdict::Allow;
+    }
+
+    Verdict::Unauthenticated
+}
+
+/// The value of a `token` query parameter in a request target or absolute URL.
+fn query_token(target: &str) -> Option<&str> {
+    let query = target.split_once('?')?.1;
+    // Fragments never reach the wire in a request target, but a `Referer` can
+    // legally carry one on some clients.
+    let query = query.split('#').next().unwrap_or(query);
+    query.split('&').find_map(|pair| {
+        let (k, v) = pair.split_once('=')?;
+        (k == "token").then_some(v)
+    })
+}
+
+/// The value of our session cookie in a `Cookie` header.
+fn cookie_token(cookie_header: &str) -> Option<&str> {
+    cookie_header.split(';').find_map(|pair| {
+        let (k, v) = pair.split_once('=')?;
+        (k.trim() == COOKIE_NAME).then_some(v.trim())
+    })
+}
+
+/// Name of the cookie the gate will accept a token in. Nothing sets it today —
+/// the pane relies on the query parameter for the document and on `Origin` /
+/// `Referer` for everything under it, because a webview iframe pointed at
+/// 127.0.0.1 is a third-party context and WKWebView and WebKitGTK both drop
+/// third-party cookies by default. It is accepted so that a future first-party
+/// entry point (opening the pane in the user's own browser, say) needs no
+/// change here.
+const COOKIE_NAME: &str = "triple_c_browser_view";
+
+/// Whether a URL (or bare origin) has exactly one of our own origins.
+fn origin_is_self(value: &str, self_origins: &[String]) -> bool {
+    // Compare scheme://host:port only; a Referer carries a path as well.
+    let origin = match value.split_once("://") {
+        Some((scheme, rest)) => {
+            let authority = rest.split(['/', '?', '#']).next().unwrap_or(rest);
+            format!("{}://{}", scheme, authority)
+        }
+        None => value.to_string(),
+    };
+    self_origins.iter().any(|o| o.eq_ignore_ascii_case(&origin))
+}
+
+/// Length-independent-ish equality. A timing oracle over a loopback socket is
+/// not a realistic attack, but comparing in constant time costs nothing and
+/// keeps the primitive honest.
+fn tokens_match(candidate: &str, expected: &str) -> bool {
+    let a = candidate.as_bytes();
+    let b = expected.as_bytes();
+    let mut diff = (a.len() ^ b.len()) as u8;
+    for i in 0..a.len().max(b.len()) {
+        let x = a.get(i).copied().unwrap_or(0);
+        let y = b.get(i).copied().unwrap_or(0);
+        diff |= x ^ y;
+    }
+    diff == 0
+}
+
+#[cfg(test)]
+mod tests {
+
+    /// The body of a cross-site POST must never be parsed as headers.
+    ///
+    /// `text/plain` is CORS-safelisted, so `fetch(..., {mode:'no-cors'})` sends
+    /// this with no preflight. Before the head was truncated at its terminator,
+    /// the forged trailing line won the last-occurrence match and the gate
+    /// returned Allow — an unauthenticated takeover of the container's browser
+    /// from any page the user happened to visit.
+    #[test]
+    fn body_bytes_are_not_parsed_as_headers() {
+        // Deliberately no Sec-Fetch-Site in the head, so the duplicate-header
+        // guard is not what saves us — this isolates truncation on its own.
+        let raw = concat!(
+            "POST / HTTP/1.1\r\n",
+            "Host: 127.0.0.1:47820\r\n",
+            "Content-Type: text/plain\r\n",
+            "\r\n",
+            "a=x\r\nSec-Fetch-Site: same-origin\r\n",
+        );
+        let head_end = find_head_end(raw.as_bytes()).expect("terminator present");
+        let head = &raw[..head_end];
+        let verdict = authorize(
+            head,
+            "tok",
+            &["http://127.0.0.1:47820".to_string()],
+            &["127.0.0.1:47820".to_string()],
+        );
+        assert_ne!(verdict, Verdict::Allow, "body line must not authorize");
+
+        // And the whole buffer — the pre-fix input — would have been allowed,
+        // which is what makes the truncation load-bearing rather than cosmetic.
+        assert_eq!(
+            authorize(
+                raw,
+                "tok",
+                &["http://127.0.0.1:47820".to_string()],
+                &["127.0.0.1:47820".to_string()]
+            ),
+            Verdict::Allow,
+            "guard test: the untruncated buffer is exactly the bypass"
+        );
+    }
+
+    /// A smuggled duplicate must be refused, not resolved last-wins.
+    #[test]
+    fn duplicate_security_headers_are_refused() {
+        for dup in [
+            "Host: 127.0.0.1:47820",
+            "Origin: http://127.0.0.1:47820",
+            "Sec-Fetch-Site: same-origin",
+        ] {
+            let raw = format!(
+                "GET / HTTP/1.1\r\nHost: evil.example:47820\r\nOrigin: http://evil.example\r\nSec-Fetch-Site: cross-site\r\n{}\r\n\r\n",
+                dup
+            );
+            assert_eq!(
+                authorize(
+                    &raw,
+                    "tok",
+                    &["http://127.0.0.1:47820".to_string()],
+                    &["127.0.0.1:47820".to_string()]
+                ),
+                Verdict::Malformed,
+                "duplicate {} must be refused",
+                dup
+            );
+        }
+    }
+
+    /// find_head_end must report the index, and it must exclude the body.
+    #[test]
+    fn head_end_excludes_the_body() {
+        let raw = b"GET / HTTP/1.1\r\nHost: a\r\n\r\nBODYBYTES";
+        let end = find_head_end(raw).expect("terminator");
+        assert_eq!(&raw[..end], b"GET / HTTP/1.1\r\nHost: a\r\n\r\n");
+        assert!(!raw[..end].ends_with(b"BODYBYTES"));
+    }
+
+    use super::*;
+
+    const TOKEN: &str = "s3cr3t-token-value";
+
+    fn origins() -> Vec<String> {
+        self_origins(47820)
+    }
+    fn authorities() -> Vec<String> {
+        host_authorities(47820)
+    }
+
+    fn head(request_line: &str, headers: &[&str]) -> String {
+        let mut s = String::from(request_line);
+        s.push_str("\r\n");
+        for h in headers {
+            s.push_str(h);
+            s.push_str("\r\n");
+        }
+        s.push_str("\r\n");
+        s
+    }
+
+    fn verdict(request_line: &str, headers: &[&str]) -> Verdict {
+        authorize(&head(request_line, headers), TOKEN, &origins(), &authorities())
+    }
+
+    #[test]
+    fn the_initial_document_is_allowed_by_its_query_token() {
+        assert_eq!(
+            verdict(
+                &format!("GET /?token={} HTTP/1.1", TOKEN),
+                &["Host: 127.0.0.1:47820"]
+            ),
+            Verdict::Allow
+        );
+    }
+
+    #[test]
+    fn a_wrong_token_is_not_enough() {
+        assert_eq!(
+            verdict("GET /?token=nope HTTP/1.1", &["Host: 127.0.0.1:47820"]),
+            Verdict::Unauthenticated
+        );
+    }
+
+    #[test]
+    fn a_subresource_is_allowed_by_the_token_in_its_referer() {
+        assert_eq!(
+            verdict(
+                "GET /assets/app.js HTTP/1.1",
+                &[
+                    "Host: 127.0.0.1:47820",
+                    &format!("Referer: http://127.0.0.1:47820/?token={}", TOKEN),
+                ]
+            ),
+            Verdict::Allow
+        );
+    }
+
+    #[test]
+    fn the_websocket_upgrade_is_allowed_by_its_own_origin() {
+        // The viewer's CDP screencast socket carries Origin and no Referer, and
+        // its URL is not ours to add a token to.
+        assert_eq!(
+            verdict(
+                "GET /ws HTTP/1.1",
+                &[
+                    "Host: 127.0.0.1:47820",
+                    "Upgrade: websocket",
+                    "Connection: Upgrade",
+                    "Origin: http://127.0.0.1:47820",
+                ]
+            ),
+            Verdict::Allow
+        );
+    }
+
+    #[test]
+    fn a_subresource_is_allowed_by_fetch_metadata_when_the_referer_is_stripped() {
+        assert_eq!(
+            verdict(
+                "GET /assets/app.js HTTP/1.1",
+                &[
+                    "Host: 127.0.0.1:47820",
+                    "Sec-Fetch-Site: same-origin",
+                    "Sec-Fetch-Dest: script",
+                ]
+            ),
+            Verdict::Allow
+        );
+    }
+
+    #[test]
+    fn cross_site_fetch_metadata_is_refused() {
+        for site in ["cross-site", "same-site", "none"] {
+            assert_eq!(
+                verdict(
+                    "GET /assets/app.js HTTP/1.1",
+                    &["Host: 127.0.0.1:47820", &format!("Sec-Fetch-Site: {}", site)]
+                ),
+                Verdict::Unauthenticated,
+                "Sec-Fetch-Site: {}",
+                site
+            );
+        }
+    }
+
+    #[test]
+    fn a_hostile_pages_fetch_is_refused_by_its_origin() {
+        assert_eq!(
+            verdict(
+                "GET / HTTP/1.1",
+                &["Host: 127.0.0.1:47820", "Origin: http://evil.example"]
+            ),
+            Verdict::Unauthenticated
+        );
+    }
+
+    #[test]
+    fn a_bare_port_scan_is_refused() {
+        // No token, no Origin, no Referer — a cross-site <script src>, a
+        // top-level navigation, or curl.
+        assert_eq!(
+            verdict("GET / HTTP/1.1", &["Host: 127.0.0.1:47820"]),
+            Verdict::Unauthenticated
+        );
+    }
+
+    #[test]
+    fn dns_rebinding_is_refused_even_with_a_valid_token() {
+        // The attacker's name resolves to 127.0.0.1, but the Host header still
+        // says who the browser thinks it is talking to.
+        assert_eq!(
+            verdict(
+                &format!("GET /?token={} HTTP/1.1", TOKEN),
+                &["Host: evil.example:47820"]
+            ),
+            Verdict::BadHost
+        );
+    }
+
+    #[test]
+    fn localhost_is_an_acceptable_authority_and_origin() {
+        assert_eq!(
+            verdict(
+                "GET /ws HTTP/1.1",
+                &["Host: localhost:47820", "Origin: http://localhost:47820"]
+            ),
+            Verdict::Allow
+        );
+    }
+
+    #[test]
+    fn another_panes_origin_does_not_authorize_this_one() {
+        // Ports are what separate one project's pane from another's, so the
+        // neighbouring port must not be accepted as "self".
+        assert_eq!(
+            verdict(
+                "GET /ws HTTP/1.1",
+                &["Host: 127.0.0.1:47820", "Origin: http://127.0.0.1:47821"]
+            ),
+            Verdict::Unauthenticated
+        );
+    }
+
+    #[test]
+    fn a_cookie_borne_token_is_accepted() {
+        assert_eq!(
+            verdict(
+                "GET /assets/app.js HTTP/1.1",
+                &[
+                    "Host: 127.0.0.1:47820",
+                    &format!("Cookie: other=1; {}={}", COOKIE_NAME, TOKEN),
+                ]
+            ),
+            Verdict::Allow
+        );
+    }
+
+    #[test]
+    fn a_missing_host_header_is_refused() {
+        assert_eq!(
+            verdict(&format!("GET /?token={} HTTP/1.1", TOKEN), &[]),
+            Verdict::BadHost
+        );
+    }
+
+    #[test]
+    fn header_names_are_matched_case_insensitively() {
+        assert_eq!(
+            verdict(
+                "GET /ws HTTP/1.1",
+                &["HOST: 127.0.0.1:47820", "ORIGIN: http://127.0.0.1:47820"]
+            ),
+            Verdict::Allow
+        );
+    }
+
+    #[test]
+    fn a_connect_request_cannot_turn_this_into_a_forward_proxy() {
+        assert_eq!(
+            verdict("CONNECT evil.example:443 HTTP/1.1", &["Host: 127.0.0.1:47820"]),
+            Verdict::Malformed
+        );
+    }
+
+    #[test]
+    fn an_empty_head_is_malformed() {
+        assert_eq!(authorize("", TOKEN, &origins(), &authorities()), Verdict::Malformed);
+    }
+
+    #[test]
+    fn the_head_terminator_is_found_for_both_crlf_and_lf() {
+        assert_eq!(find_head_end(b"GET / HTTP/1.1\r\n\r\n"), Some(18));
+        assert_eq!(find_head_end(b"GET / HTTP/1.1\n\n"), Some(16));
+        assert_eq!(find_head_end(b"GET / HTTP/1.1\r\nHost: x\r\n"), None);
+    }
+
+    #[test]
+    fn query_token_ignores_lookalike_parameters() {
+        assert_eq!(query_token("/?mytoken=a&token=b"), Some("b"));
+        assert_eq!(query_token("/?tokenish=a"), None);
+        assert_eq!(query_token("/nothing"), None);
+    }
+
+    #[test]
+    fn tokens_match_rejects_prefixes_and_suffixes() {
+        assert!(tokens_match(TOKEN, TOKEN));
+        assert!(!tokens_match(&TOKEN[..5], TOKEN));
+        assert!(!tokens_match(&format!("{}x", TOKEN), TOKEN));
+        assert!(!tokens_match("", TOKEN));
+    }
+
+    #[test]
+    fn the_proxy_port_range_is_the_one_the_csp_enumerates() {
+        // tauri.conf.json lists these origins in `frame-src`; a change here
+        // without a change there yields a pane that is silently blocked.
+        assert_eq!(PROXY_PORTS.clone().count(), 8);
+        assert_eq!(*PROXY_PORTS.start(), 47820);
+        assert_eq!(*PROXY_PORTS.end(), 47827);
+    }
+}

app/src-tauri/src/commands/auth_bridge_commands.rs

@@ -0,0 +1,67 @@
+//! IPC surface for the auth bridge. The mechanism lives in
+//! [`crate::auth_bridge`]; this file only translates between it and the
+//! frontend, and keeps the persisted per-project flag in step.
+
+use tauri::{AppHandle, State};
+
+use crate::auth_bridge::AuthBridgeStatus;
+use crate::AppState;
+
+/// Turn the bridge on or off for a project and return the resulting status.
+///
+/// Enabling starts polling immediately when the container is already running;
+/// otherwise the flag is simply persisted and `start_project_container` arms the
+/// bridge on the next start. This is a host-side feature, so no container
+/// recreation is involved either way.
+#[tauri::command]
+pub async fn set_auth_bridge_enabled(
+    project_id: String,
+    enabled: bool,
+    app_handle: AppHandle,
+    state: State<'_, AppState>,
+) -> Result<AuthBridgeStatus, String> {
+    state
+        .projects_store
+        .set_auth_bridge_enabled(&project_id, enabled)?;
+
+    if enabled {
+        let project = state
+            .projects_store
+            .get(&project_id)
+            .ok_or_else(|| format!("Project {} not found", project_id))?;
+        if let Some(container_id) = project.container_id {
+            if crate::docker::container::is_container_running(&container_id)
+                .await
+                .unwrap_or(false)
+            {
+                state
+                    .auth_bridge
+                    .start(
+                        project_id.clone(),
+                        container_id,
+                        app_handle,
+                        state.projects_store.clone(),
+                    )
+                    .await;
+            }
+        }
+    } else {
+        // Awaits the poller, so every host port is released before we return.
+        state.auth_bridge.stop(&project_id).await;
+    }
+
+    Ok(state.auth_bridge.status(&project_id, enabled).await)
+}
+
+#[tauri::command]
+pub async fn get_auth_bridge_status(
+    project_id: String,
+    state: State<'_, AppState>,
+) -> Result<AuthBridgeStatus, String> {
+    let enabled = state
+        .projects_store
+        .get(&project_id)
+        .map(|p| p.auth_bridge_enabled)
+        .unwrap_or(false);
+    Ok(state.auth_bridge.status(&project_id, enabled).await)
+}

app/src-tauri/src/commands/docker_commands.rs

@@ -37,20 +37,3 @@ pub async fn get_container_info(
     docker::get_container_info(&project).await
 }
 
-#[tauri::command]
-pub async fn list_sibling_containers() -> Result<Vec<serde_json::Value>, String> {
-    let containers = docker::list_sibling_containers().await?;
-    let result: Vec<serde_json::Value> = containers
-        .into_iter()
-        .map(|c| {
-            serde_json::json!({
-                "id": c.id,
-                "names": c.names,
-                "image": c.image,
-                "state": c.state,
-                "status": c.status,
-            })
-        })
-        .collect();
-    Ok(result)
-}

app/src-tauri/src/commands/gateway_commands.rs

@@ -0,0 +1,88 @@
+//! Tauri commands for the model gateway container.
+//!
+//! Mirrors `stt_commands`. The one rule that is specific to this module: the
+//! **provider API key never crosses back to the frontend**. It goes in through
+//! `set_gateway_api_key`, lives in the OS keychain, and is only ever read
+//! host-side when rendering the gateway config. `get_gateway_status` reports
+//! its presence as a boolean.
+//!
+//! The gateway *master key* is different and is returned deliberately — it is
+//! the value the user has to paste into a project's model config as its auth
+//! token, so keeping it hidden would just make the feature unusable.
+
+use tauri::{AppHandle, Emitter, State};
+
+use crate::docker::gateway;
+use crate::models::GatewayStatus;
+use crate::storage::secure;
+use crate::AppState;
+
+#[tauri::command]
+pub async fn get_gateway_status(state: State<'_, AppState>) -> Result<GatewayStatus, String> {
+    let settings = state.settings_store.get();
+    gateway::get_gateway_status(&settings.gateway).await
+}
+
+#[tauri::command]
+pub async fn start_gateway(state: State<'_, AppState>) -> Result<GatewayStatus, String> {
+    let settings = state.settings_store.get();
+    gateway::ensure_gateway_running(&settings.gateway).await
+}
+
+#[tauri::command]
+pub async fn stop_gateway() -> Result<(), String> {
+    gateway::stop_gateway_container().await
+}
+
+/// Whether the gateway is actually answering yet. LiteLLM needs a few seconds
+/// after the container starts before `/v1/messages` will serve anything.
+#[tauri::command]
+pub async fn check_gateway_health(state: State<'_, AppState>) -> Result<bool, String> {
+    let settings = state.settings_store.get();
+    gateway::check_gateway_health(settings.gateway.port).await
+}
+
+#[tauri::command]
+pub async fn build_gateway_image(app_handle: AppHandle) -> Result<(), String> {
+    gateway::build_gateway_image(move |msg| {
+        let _ = app_handle.emit("gateway-build-progress", &msg);
+    })
+    .await
+}
+
+#[tauri::command]
+pub async fn pull_gateway_image(app_handle: AppHandle) -> Result<(), String> {
+    gateway::pull_gateway_image(move |msg| {
+        let _ = app_handle.emit("gateway-pull-progress", &msg);
+    })
+    .await
+}
+
+/// Store the upstream provider API key. Write-only from the frontend's point
+/// of view — there is no matching getter.
+#[tauri::command]
+pub async fn set_gateway_api_key(api_key: String) -> Result<(), String> {
+    secure::store_gateway_api_key(&api_key)
+}
+
+/// Forget the provider API key. The gateway keeps serving until it is
+/// restarted, at which point it will refuse to start without a key.
+#[tauri::command]
+pub async fn clear_gateway_api_key() -> Result<(), String> {
+    secure::delete_gateway_api_key()
+}
+
+/// The token a project sends to the gateway (`ANTHROPIC_AUTH_TOKEN`), minting
+/// one on first use.
+#[tauri::command]
+pub async fn get_gateway_auth_token() -> Result<String, String> {
+    secure::get_or_create_gateway_master_key()
+}
+
+/// Mint a new gateway auth token, invalidating the old one. Projects still
+/// holding the previous value stop working until they are updated, and the
+/// gateway is recreated on its next start because the rotation id moved.
+#[tauri::command]
+pub async fn regenerate_gateway_auth_token() -> Result<String, String> {
+    secure::regenerate_gateway_master_key()
+}

app/src-tauri/src/commands/install_helper_commands.rs

@@ -0,0 +1,11 @@
+use crate::install_helper::{self, InstallOptions};
+
+#[tauri::command]
+pub async fn detect_install_options() -> Result<InstallOptions, String> {
+    Ok(install_helper::detect_install_options())
+}
+
+#[tauri::command]
+pub async fn run_docker_install(app_handle: tauri::AppHandle) -> Result<(), String> {
+    install_helper::platform::run_install(&app_handle).await
+}

app/src-tauri/src/commands/mcp_commands.rs

@@ -1,38 +0,0 @@
-use tauri::State;
-
-use crate::models::McpServer;
-use crate::AppState;
-
-#[tauri::command]
-pub async fn list_mcp_servers(state: State<'_, AppState>) -> Result<Vec<McpServer>, String> {
-    Ok(state.mcp_store.list())
-}
-
-#[tauri::command]
-pub async fn add_mcp_server(
-    name: String,
-    state: State<'_, AppState>,
-) -> Result<McpServer, String> {
-    let name = name.trim().to_string();
-    if name.is_empty() {
-        return Err("MCP server name cannot be empty.".to_string());
-    }
-    let server = McpServer::new(name);
-    state.mcp_store.add(server)
-}
-
-#[tauri::command]
-pub async fn update_mcp_server(
-    server: McpServer,
-    state: State<'_, AppState>,
-) -> Result<McpServer, String> {
-    state.mcp_store.update(server)
-}
-
-#[tauri::command]
-pub async fn remove_mcp_server(
-    server_id: String,
-    state: State<'_, AppState>,
-) -> Result<(), String> {
-    state.mcp_store.remove(&server_id)
-}

app/src-tauri/src/commands/mod.rs

@@ -1,10 +1,17 @@
+pub mod auth_bridge_commands;
+pub mod auth_token_commands;
 pub mod aws_commands;
 pub mod docker_commands;
 pub mod file_commands;
+pub mod gateway_commands;
 pub mod help_commands;
-pub mod mcp_commands;
+pub mod inspect_commands;
+pub mod install_helper_commands;
+pub mod migration_commands;
+pub mod notes_commands;
 pub mod project_commands;
 pub mod settings_commands;
+pub mod settings_export_commands;
 pub mod stt_commands;
 pub mod terminal_commands;
 pub mod update_commands;

app/src-tauri/src/commands/notes_commands.rs

@@ -0,0 +1,33 @@
+use crate::models::Note;
+use crate::storage::notes_store;
+
+/// Every project's notes, oldest concept first: pinned notes, then most
+/// recently edited.
+///
+/// Sorted here rather than in the webview so the dock and the tab — two views
+/// of the same list — cannot drift into two different orders.
+#[tauri::command]
+pub async fn list_notes(project_id: String) -> Result<Vec<Note>, String> {
+    let mut notes = notes_store::load(&project_id)?;
+    notes.sort_by(|a, b| {
+        b.pinned
+            .cmp(&a.pinned)
+            .then_with(|| b.updated_at.cmp(&a.updated_at))
+    });
+    Ok(notes)
+}
+
+/// Insert or replace one note.
+///
+/// There is deliberately no whole-list setter. A bulk write is exactly the
+/// clobbering this store's per-project file exists to avoid, and every caller
+/// here is editing one note.
+#[tauri::command]
+pub async fn save_note(project_id: String, note: Note) -> Result<Note, String> {
+    notes_store::upsert(&project_id, note)
+}
+
+#[tauri::command]
+pub async fn delete_note(project_id: String, note_id: String) -> Result<(), String> {
+    notes_store::delete(&project_id, &note_id)
+}

app/src-tauri/src/commands/settings_commands.rs

@@ -1,6 +1,7 @@
 use tauri::State;
 
 use crate::docker;
+use crate::models::gateway_settings::GatewaySettings;
 use crate::models::AppSettings;
 use crate::AppState;
 
@@ -9,19 +10,166 @@ pub async fn get_settings(state: State<'_, AppState>) -> Result<AppSettings, Str
     Ok(state.settings_store.get())
 }
 
+/// Everything `update_settings` refuses a save over, run against the store's
+/// *current* value and the incoming one.
+///
+/// Pulled out so a caller that does other, harder-to-undo work alongside a
+/// settings save — `settings_export_commands::apply_settings_import`
+/// restores three keychain secrets in the same command — can run this
+/// *first* and bail before touching anything, rather than discovering the
+/// rejection only when `update_settings` itself runs partway through.
+pub fn validate_settings_update(
+    before: &AppSettings,
+    incoming: &AppSettings,
+) -> Result<(), String> {
+    // The global half of the same rule the project half gets in
+    // `update_project`: a global custom env var is merged into every project's
+    // container environment, so an unchecked name here reaches all of them.
+    crate::models::validate_env_vars_update(
+        &before.global_custom_env_vars,
+        &incoming.global_custom_env_vars,
+    )?;
+
+    // The same for the two host paths this struct owns. `update_project`
+    // validated its per-project overrides and this side validated nothing,
+    // which left the wider hole of the two: `default_ssh_key_path` is the
+    // fallback for **every** project without an override
+    // (`container.rs`'s `create_container`), so `/` here read-only bind-mounts
+    // the whole host at `/tmp/.host-ssh` for all of them — and `entrypoint.sh`
+    // then does `cp -a /tmp/.host-ssh ~/.ssh`, recursively copying it into the
+    // home volume this release exists to bound.
+    //
+    // Grandfathered the same way project paths are: a value carried over
+    // unchanged still saves, so a store written before this check cannot lock
+    // the user out of their own settings.
+    crate::commands::project_commands::validate_mounted_host_path(
+        "SSH key path",
+        before.default_ssh_key_path.as_deref(),
+        incoming.default_ssh_key_path.as_deref(),
+    )?;
+    crate::commands::project_commands::validate_mounted_host_path(
+        "CA certificate path",
+        before.ca_cert_path.as_deref(),
+        incoming.ca_cert_path.as_deref(),
+    )?;
+
+    // Third host path this struct owns, same reasoning: any project with
+    // `allow_docker_access` bind-mounts this path in as the Docker socket
+    // (`project_commands.rs`'s container creation), so an unchecked value
+    // here is a read-write bind mount of whatever it names into every such
+    // project's container.
+    crate::commands::project_commands::validate_mounted_host_path(
+        "Docker socket path",
+        before.docker_socket_path.as_deref(),
+        incoming.docker_socket_path.as_deref(),
+    )?;
+
+    Ok(())
+}
+
 #[tauri::command]
 pub async fn update_settings(
     settings: AppSettings,
     state: State<'_, AppState>,
 ) -> Result<AppSettings, String> {
-    state.settings_store.update(settings)
+    let before = state.settings_store.get();
+
+    validate_settings_update(&before, &settings)?;
+
+    let saved = state.settings_store.update(settings)?;
+
+    // Persisting a setting is not the same as applying it. The gateway is the
+    // one settings block that owns a *container*, so a saved change that the
+    // running container doesn't reflect is a live desync, not a preference.
+    reconcile_gateway(&before.gateway, &saved.gateway).await;
+
+    Ok(saved)
+}
+
+/// What a settings save has to do to the gateway container to stay honest.
+///
+/// Kept separate from the IPC command and expressed over plain settings so the
+/// decision is testable without Docker.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum GatewayAction {
+    /// Nothing to do.
+    None,
+    /// The gateway is off — a container left running must be stopped.
+    StopIfRunning,
+    /// The published shape moved. A *running* container is now serving on the
+    /// old binding while status reports the new one, so it has to be recreated.
+    RestartIfRunning,
+}
+
+/// Whether the container's published shape (as opposed to a purely cosmetic
+/// field) changed. Provider, models and base URL all change the rendered
+/// LiteLLM config, which is only read at boot.
+fn gateway_shape_changed(before: &GatewaySettings, after: &GatewaySettings) -> bool {
+    before.port != after.port
+        || before.provider.trim() != after.provider.trim()
+        || before.api_base.as_deref().unwrap_or("").trim()
+            != after.api_base.as_deref().unwrap_or("").trim()
+        || before.valid_models() != after.valid_models()
+}
+
+fn gateway_action(before: &GatewaySettings, after: &GatewaySettings) -> GatewayAction {
+    if !after.enabled {
+        // Includes the case where it was already disabled: a container found
+        // running while the feature is off should not stay up.
+        return GatewayAction::StopIfRunning;
+    }
+    if gateway_shape_changed(before, after) {
+        return GatewayAction::RestartIfRunning;
+    }
+    GatewayAction::None
+}
+
+/// Apply [`gateway_action`]. Never fails the settings save: the settings *are*
+/// saved by this point, and a Docker hiccup must not make the UI think they
+/// weren't. Both paths are no-ops when no container exists, so this stays cheap
+/// on the overwhelmingly common "gateway not in use" save.
+async fn reconcile_gateway(before: &GatewaySettings, after: &GatewaySettings) {
+    let action = gateway_action(before, after);
+    if action == GatewayAction::None {
+        return;
+    }
+
+    let (exists, running) = match docker::gateway::gateway_container_presence().await {
+        Ok(presence) => presence,
+        // Docker down: there is nothing running to desync from.
+        Err(e) => {
+            log::debug!("Gateway reconcile skipped ({})", e);
+            return;
+        }
+    };
+    if !exists || !running {
+        return;
+    }
+
+    match action {
+        GatewayAction::StopIfRunning => {
+            log::info!("Model gateway disabled in settings — stopping the container");
+            if let Err(e) = docker::gateway::stop_gateway_container().await {
+                log::error!(
+                    "Failed to stop the model gateway after it was disabled: {}",
+                    e
+                );
+            }
+        }
+        GatewayAction::RestartIfRunning => {
+            log::info!("Model gateway settings changed — recreating the container");
+            // The fingerprint no longer matches, so this stops, removes and
+            // recreates with the new port/config in one step.
+            if let Err(e) = docker::gateway::ensure_gateway_running(after).await {
+                log::error!("Failed to apply the new model gateway settings: {}", e);
+            }
+        }
+        GatewayAction::None => unreachable!(),
+    }
 }
 
 #[tauri::command]
-pub async fn pull_image(
-    image_name: String,
-    app_handle: tauri::AppHandle,
-) -> Result<(), String> {
+pub async fn pull_image(image_name: String, app_handle: tauri::AppHandle) -> Result<(), String> {
     use tauri::Emitter;
     docker::pull_image(&image_name, move |msg| {
         let _ = app_handle.emit("image-pull-progress", msg);
@@ -67,6 +215,78 @@ pub async fn detect_aws_config() -> Result<Option<String>, String> {
     Ok(None)
 }
 
+/// What the UI shows next to a corporate CA certificate path.
+///
+/// Errors are returned *inside* the payload rather than as `Err` so the field
+/// can render its own inline message while the user is still typing — a toast
+/// per keystroke would be unusable. The same check runs again, as a hard error,
+/// when the container is created.
+#[derive(Debug, serde::Serialize)]
+pub struct CaCertInfo {
+    pub exists: bool,
+    pub is_directory: bool,
+    /// How many certificate files were found.
+    pub cert_count: usize,
+    /// The names they will be installed as inside the container. Surfacing
+    /// these makes the silent `.pem` → `.crt` rename visible, which is the one
+    /// step users most often do by hand and get wrong.
+    pub installed_names: Vec<String>,
+    /// Why the path is unusable, if it is.
+    pub error: Option<String>,
+}
+
+#[tauri::command]
+pub async fn inspect_ca_cert_path(path: String) -> Result<CaCertInfo, String> {
+    use crate::docker::ca_certs;
+
+    let trimmed = path.trim();
+    if trimmed.is_empty() {
+        return Ok(CaCertInfo {
+            exists: false,
+            is_directory: false,
+            cert_count: 0,
+            installed_names: Vec::new(),
+            error: None,
+        });
+    }
+
+    let p = std::path::Path::new(trimmed);
+    let exists = p.exists();
+    let is_directory = p.is_dir();
+
+    match ca_certs::resolve(Some(trimmed)) {
+        Ok(Some(resolved)) => Ok(CaCertInfo {
+            exists,
+            is_directory,
+            cert_count: resolved.cert_files.len(),
+            installed_names: resolved
+                .cert_files
+                .iter()
+                .map(|f| {
+                    ca_certs::container_cert_name(
+                        &f.file_name().unwrap_or_default().to_string_lossy(),
+                    )
+                })
+                .collect(),
+            error: None,
+        }),
+        Ok(None) => Ok(CaCertInfo {
+            exists,
+            is_directory,
+            cert_count: 0,
+            installed_names: Vec::new(),
+            error: None,
+        }),
+        Err(e) => Ok(CaCertInfo {
+            exists,
+            is_directory,
+            cert_count: 0,
+            installed_names: Vec::new(),
+            error: Some(e),
+        }),
+    }
+}
+
 #[tauri::command]
 pub async fn list_aws_profiles() -> Result<Vec<String>, String> {
     let mut profiles = Vec::new();
@@ -115,3 +335,99 @@ pub async fn list_aws_profiles() -> Result<Vec<String>, String> {
 
     Ok(profiles)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::gateway_settings::GatewayModel;
+
+    fn enabled_gateway() -> GatewaySettings {
+        GatewaySettings {
+            enabled: true,
+            port: 4000,
+            provider: "openai".to_string(),
+            api_base: None,
+            models: vec![GatewayModel {
+                name: "gpt-5.1".to_string(),
+                model_id: "gpt-5.1".to_string(),
+            }],
+        }
+    }
+
+    #[test]
+    fn disabling_the_gateway_stops_it() {
+        // The bug: turning the toggle off only persisted `enabled: false` and
+        // hid the Stop button, leaving a container serving with no way to stop
+        // it.
+        let before = enabled_gateway();
+        let mut after = before.clone();
+        after.enabled = false;
+        assert_eq!(
+            gateway_action(&before, &after),
+            GatewayAction::StopIfRunning
+        );
+        // Still true when it was already off — a stray running container is
+        // still a container that shouldn't be up.
+        assert_eq!(gateway_action(&after, &after), GatewayAction::StopIfRunning);
+    }
+
+    #[test]
+    fn changing_the_port_reconciles_the_container() {
+        // Otherwise status reports the new port while the container keeps the
+        // old binding, and every project gets a broken ANTHROPIC_BASE_URL.
+        let before = enabled_gateway();
+        let mut after = before.clone();
+        after.port = 4100;
+        assert_eq!(
+            gateway_action(&before, &after),
+            GatewayAction::RestartIfRunning
+        );
+    }
+
+    #[test]
+    fn config_changes_that_only_take_effect_at_boot_reconcile_too() {
+        let before = enabled_gateway();
+
+        let mut provider = before.clone();
+        provider.provider = "groq".to_string();
+        assert_eq!(
+            gateway_action(&before, &provider),
+            GatewayAction::RestartIfRunning
+        );
+
+        let mut api_base = before.clone();
+        api_base.api_base = Some("https://example.test/v1".to_string());
+        assert_eq!(
+            gateway_action(&before, &api_base),
+            GatewayAction::RestartIfRunning
+        );
+
+        let mut models = before.clone();
+        models.models[0].model_id = "gpt-4.1".to_string();
+        assert_eq!(
+            gateway_action(&before, &models),
+            GatewayAction::RestartIfRunning
+        );
+    }
+
+    #[test]
+    fn saving_an_unchanged_or_half_typed_gateway_touches_nothing() {
+        let before = enabled_gateway();
+        assert_eq!(gateway_action(&before, &before), GatewayAction::None);
+
+        // Whitespace-only edits don't reach the rendered config.
+        let mut trimmed = before.clone();
+        trimmed.provider = "  openai  ".to_string();
+        trimmed.api_base = Some("   ".to_string());
+        assert_eq!(gateway_action(&before, &trimmed), GatewayAction::None);
+
+        // A half-filled model row is skipped when rendering, so it must not
+        // bounce a live container either.
+        let mut half_typed = before.clone();
+        half_typed.models.push(GatewayModel {
+            name: "gpt".to_string(),
+            model_id: String::new(),
+        });
+        assert_eq!(gateway_action(&before, &half_typed), GatewayAction::None);
+    }
+}

app/src-tauri/src/commands/settings_export_commands.rs

@@ -0,0 +1,654 @@
+//! Settings export/import — see triple-c#35.
+//!
+//! Exports the *host* environment (global `AppSettings` plus the global
+//! secrets kept in the OS keychain: the shared Claude Code OAuth login and
+//! the model gateway's two keys), encrypted with a user-chosen password —
+//! see `storage::settings_crypto` for the actual cryptography. Deliberately
+//! out of scope: per-project settings, per-project secrets, and anything
+//! living in a project's Docker volumes.
+//!
+//! **The save/open dialogs are opened from Rust**, the same pattern
+//! `file_commands.rs`'s `pick_save_path`/`pick_files_to_upload` already
+//! establish and document at length: a frontend-driven dialog handing Rust a
+//! host path string is the exact shape of bug that produced this app's past
+//! criticals, so the boundary here is drawn the same place. The frontend can
+//! ask for a picker; it cannot name a host path as an *input*. `preview_
+//! settings_import` resolves the chosen path itself and remembers it
+//! (`AppState::pending_settings_import`) so `apply_settings_import` re-reads
+//! the same file without the path ever crossing back over IPC.
+//!
+//! The *decrypted payload* is not cached between preview and apply — the
+//! password the frontend passes to each call is what it already held for
+//! the first, not a fresh secret extracted from the user, but nothing here
+//! keeps the plaintext itself — export/import secrets included — around for
+//! longer than one command's execution; `apply_settings_import` re-decrypts
+//! the file rather than reusing anything `preview_settings_import` computed.
+//!
+//! **This is new attack surface**: a settings export is a file one person
+//! can hand another and ask them to import, together with a password, and
+//! `apply_settings_import` applies whatever `AppSettings` it decrypts to
+//! wholesale — see the module doc on `models::settings_export` for the
+//! `web_terminal.access_token` carve-out a review of this feature found,
+//! and treat that as the standing example of the class of thing to keep
+//! checking for here, not a one-off fixed bug.
+
+#[cfg(test)]
+use std::path::Path;
+use std::path::PathBuf;
+
+use sha2::{Digest, Sha256};
+use tauri::State;
+use tauri_plugin_dialog::DialogExt;
+use zeroize::Zeroizing;
+
+use crate::models::{
+    AppSettings, ExportedSecrets, SettingsExportPayload, SettingsImportOutcome,
+    SettingsImportPreview, SETTINGS_EXPORT_FORMAT_VERSION,
+};
+use crate::storage::{secure, settings_crypto};
+use crate::AppState;
+
+/// What `preview_settings_import` pins so `apply_settings_import` can tell
+/// whether the file it's about to re-read is the same one the user actually
+/// saw a preview of. Confirming a preview is only meaningful if it's binding
+/// on what gets applied — without this, a file replaced on disk between the
+/// two calls (this app's own stated threat model is a file shared between
+/// people, which may sit in a synced or shared directory) would decrypt and
+/// apply silently different content than what the confirmation dialog showed.
+#[derive(Debug, Clone)]
+pub struct PendingSettingsImport {
+    path: PathBuf,
+    ciphertext_hash: [u8; 32],
+}
+
+fn hash_ciphertext(data: &[u8]) -> [u8; 32] {
+    Sha256::digest(data).into()
+}
+
+const FILE_EXTENSION: &str = "triplec";
+
+/// Enforced here, not only in the export modal: the frontend's minimum is a
+/// UX nudge, but `export_settings` is the actual boundary a weak password
+/// has to cross, and Argon2id's memory-hardness buys little against an
+/// attacker who can just try a three-character password directly.
+const MIN_PASSWORD_LEN: usize = 8;
+
+fn suggested_export_name() -> String {
+    // Timestamped so exporting more than once doesn't silently overwrite an
+    // earlier file just because the save dialog defaults to the same name.
+    format!(
+        "triple-c-settings-{}.{}",
+        chrono::Utc::now().format("%Y%m%d-%H%M%S"),
+        FILE_EXTENSION
+    )
+}
+
+async fn pick_export_save_path(window: &tauri::Window, suggested: &str) -> Option<PathBuf> {
+    let (tx, rx) = tokio::sync::oneshot::channel();
+    window
+        .dialog()
+        .file()
+        .set_parent(window)
+        .set_title("Export Triple-C settings")
+        .set_file_name(suggested)
+        .add_filter("Triple-C settings export", &[FILE_EXTENSION])
+        .save_file(move |picked| {
+            let _ = tx.send(picked);
+        });
+    rx.await.ok().flatten().and_then(|p| p.into_path().ok())
+}
+
+async fn pick_import_open_path(window: &tauri::Window) -> Option<PathBuf> {
+    let (tx, rx) = tokio::sync::oneshot::channel();
+    window
+        .dialog()
+        .file()
+        .set_parent(window)
+        .set_title("Import Triple-C settings")
+        .add_filter("Triple-C settings export", &[FILE_EXTENSION])
+        .pick_file(move |picked| {
+            let _ = tx.send(picked);
+        });
+    rx.await.ok().flatten().and_then(|p| p.into_path().ok())
+}
+
+/// Gather the current global secrets, and hand back the `AppSettings` to
+/// export with the web-terminal token blanked out of it — see the module
+/// doc comment on `models::settings_export` for why that field cannot
+/// travel through `settings` like the rest of this struct.
+///
+/// A missing keychain secret reads as `None` — a keychain read failure is
+/// treated as "nothing to export" for that one entry rather than aborting
+/// the whole export, matching how the rest of this app degrades a keychain
+/// error to "absent" (`has_claude_oauth_token`, `has_gateway_api_key`)
+/// rather than surfacing it as a hard failure.
+fn split_settings_and_secrets(current: AppSettings) -> (AppSettings, ExportedSecrets) {
+    let mut settings = current;
+    let web_terminal_access_token = settings.web_terminal.access_token.take();
+
+    let secrets = ExportedSecrets {
+        claude_oauth_token: secure::get_claude_oauth_token().unwrap_or_default(),
+        gateway_api_key: secure::get_gateway_api_key().unwrap_or_default(),
+        gateway_master_key: secure::get_gateway_master_key().unwrap_or_default(),
+        web_terminal_access_token,
+    };
+
+    (settings, secrets)
+}
+
+/// Export the current global settings and secrets to a password-encrypted
+/// file. `Ok(false)` means the save dialog was dismissed — not an error, and
+/// deliberately distinguishable from one so the frontend shows nothing
+/// rather than a "failed" toast for a plain cancel.
+#[tauri::command]
+pub async fn export_settings(
+    password: String,
+    window: tauri::Window,
+    state: State<'_, AppState>,
+) -> Result<bool, String> {
+    // `.chars().count()` — Unicode scalar values, not bytes — to stay as
+    // close as this pair of languages allows to the frontend's `.length`
+    // check (UTF-16 code units); the two only diverge on astral-plane
+    // characters, which no reasonable password touches.
+    if password.chars().count() < MIN_PASSWORD_LEN {
+        return Err(format!(
+            "Use a password of at least {} characters.",
+            MIN_PASSWORD_LEN
+        ));
+    }
+
+    let Some(dest) = pick_export_save_path(&window, &suggested_export_name()).await else {
+        return Ok(false);
+    };
+
+    let (settings, secrets) = split_settings_and_secrets(state.settings_store.get());
+    if secrets.is_empty() {
+        log::info!("Exporting settings with no global secrets configured on this machine");
+    }
+
+    let payload = SettingsExportPayload {
+        format_version: SETTINGS_EXPORT_FORMAT_VERSION,
+        exported_at: chrono::Utc::now().to_rfc3339(),
+        app_version: env!("CARGO_PKG_VERSION").to_string(),
+        settings,
+        secrets,
+    };
+
+    let plaintext = Zeroizing::new(
+        serde_json::to_vec(&payload)
+            .map_err(|e| format!("Failed to prepare settings for export: {}", e))?,
+    );
+    let encrypted = settings_crypto::encrypt(&plaintext, &password)?;
+
+    std::fs::write(&dest, &encrypted).map_err(|e| format!("Failed to write export file: {}", e))?;
+
+    Ok(true)
+}
+
+/// Open a file picker, decrypt the chosen file with `password`, and return a
+/// preview (counts and presence flags only — never a secret value) for a
+/// confirmation UI. `Ok(None)` means the picker was dismissed.
+///
+/// Remembers the resolved path *and a hash of the file's ciphertext* in
+/// `AppState::pending_settings_import` for `apply_settings_import` to check
+/// against — does **not** remember the decrypted payload itself, so the
+/// password must be supplied again to actually apply it — seeing the preview
+/// is not the same as committing to it. The hash exists so it also can't be
+/// swapped out from under that commitment: `apply_settings_import` refuses to
+/// proceed if the file on disk no longer matches what was just previewed.
+#[tauri::command]
+pub async fn preview_settings_import(
+    password: String,
+    window: tauri::Window,
+    state: State<'_, AppState>,
+) -> Result<Option<SettingsImportPreview>, String> {
+    if password.is_empty() {
+        return Err("A password is required to open a settings export.".to_string());
+    }
+
+    let Some(path) = pick_import_open_path(&window).await else {
+        return Ok(None);
+    };
+
+    let encrypted = std::fs::read(&path).map_err(|e| format!("Failed to read export file: {}", e))?;
+    let payload = read_and_decrypt_bytes(&encrypted, &password)?;
+    let preview = SettingsImportPreview::from_payload(&payload);
+
+    *state.pending_settings_import.lock().await = Some(PendingSettingsImport {
+        path,
+        ciphertext_hash: hash_ciphertext(&encrypted),
+    });
+
+    Ok(Some(preview))
+}
+
+/// Apply the import a prior `preview_settings_import` call resolved a path
+/// for. Fails if no preview is pending — this is not a general "decrypt and
+/// apply this file" entry point, deliberately: seeing the preview first is
+/// required, not just encouraged, since it is the only place a user is told
+/// what an import is about to touch before it touches it. That requirement
+/// is only real if the file can't change out from under it, so this also
+/// refuses to proceed if the file's ciphertext no longer matches the hash
+/// `preview_settings_import` pinned — a file replaced on disk between the
+/// two calls (this feature's own threat model is a file shared between
+/// people, which may sit in a synced or shared directory) must not be able
+/// to apply silently different content than what the confirmation dialog
+/// showed.
+///
+/// Global settings are replaced wholesale — an import is "restore this
+/// environment," not a field-by-field merge. Global secrets are handled
+/// differently and on purpose: **only secrets actually present in the
+/// import are written**; a secret the export doesn't have is left alone on
+/// this machine rather than cleared, because an absent secret in the export
+/// means "the source machine never had this configured," not "delete this
+/// on import." A user who wants to clear a secret already has dedicated UI
+/// for that (signing out of shared auth, clearing the gateway key).
+///
+/// Order matters here, twice over.
+///
+/// First: the imported settings are **validated before any secret is
+/// written**, using the same checks `update_settings` itself runs
+/// (`settings_commands::validate_settings_update`). Restoring a secret is
+/// hard to undo unnoticed — a stale env-var-name rejection or a disallowed
+/// host path used to be caught only when `update_settings` ran, by which
+/// point the three keychain secrets below were already overwritten with the
+/// file's, each with a fresh rotation id, silently flagging every project
+/// container for recreation — while the error the user saw talked only
+/// about the rejected setting and said nothing about the credentials that
+/// had already moved. Failing this check first makes a rejected import
+/// leave nothing touched, matching what "the import failed" is supposed to
+/// mean.
+///
+/// Second, among the things that *do* get written: secrets are restored
+/// **before** the settings replace runs (which is what triggers
+/// `reconcile_gateway`), so a gateway recreation that replace provokes sees
+/// the final key material rather than racing it — restoring the other way
+/// round left a real window where the running gateway and the keychain
+/// briefly disagreed. A gateway *secret* alone (same shape, new key) is
+/// invisible to `reconcile_gateway`'s shape comparison, so this additionally
+/// nudges a running gateway container to recreate itself whenever a secret
+/// this import carried was actually written — otherwise the running
+/// container keeps serving the old key material indefinitely while every
+/// project container is handed the new one.
+///
+/// A keychain write failing is reported back rather than only logged: an
+/// import that silently restores two of three secrets but not the third
+/// must not read as unqualified success.
+///
+/// The pending import is only cleared on success. A failure here (rejected
+/// by the validation above, a stale-file mismatch, or some other error)
+/// leaves it pending so the frontend can let the user retry `apply` without
+/// making them pick the file and re-enter the password again — the
+/// preview's job was confirming *what* to import, not spending the one
+/// attempt at applying it.
+#[tauri::command]
+pub async fn apply_settings_import(
+    password: String,
+    state: State<'_, AppState>,
+) -> Result<SettingsImportOutcome, String> {
+    if password.is_empty() {
+        return Err("A password is required to import settings.".to_string());
+    }
+
+    let pending = state
+        .pending_settings_import
+        .lock()
+        .await
+        .clone()
+        .ok_or_else(|| "No import is pending — choose a file first.".to_string())?;
+
+    let encrypted = std::fs::read(&pending.path)
+        .map_err(|e| format!("Failed to read export file: {}", e))?;
+    if hash_ciphertext(&encrypted) != pending.ciphertext_hash {
+        return Err(
+            "This file changed since you reviewed it — choose it again to see an up-to-date preview."
+                .to_string(),
+        );
+    }
+    let payload = read_and_decrypt_bytes(&encrypted, &password)?;
+
+    let current = state.settings_store.get();
+
+    // The web-terminal token lives inside `AppSettings` itself rather than
+    // the keychain, so "leave an absent secret alone" has to be done by
+    // hand here: carry the destination's current token forward when the
+    // import doesn't have one, instead of letting the wholesale replace
+    // below blank it (every export writes `None` there — see
+    // `split_settings_and_secrets`).
+    let mut settings = payload.settings;
+    settings.web_terminal.access_token = non_blank(payload.secrets.web_terminal_access_token)
+        .or_else(|| current.web_terminal.access_token.clone());
+
+    crate::commands::settings_commands::validate_settings_update(&current, &settings)?;
+
+    let mut secret_restore_warnings = Vec::new();
+    let mut gateway_secret_changed = false;
+
+    if let Some(token) = non_blank(payload.secrets.claude_oauth_token) {
+        if let Err(e) = secure::store_claude_oauth_token(&token) {
+            log::warn!(
+                "Settings import: could not restore the shared Claude login: {}",
+                e
+            );
+            secret_restore_warnings
+                .push(format!("Could not restore your shared Claude login: {}", e));
+        }
+    }
+    if let Some(key) = non_blank(payload.secrets.gateway_api_key) {
+        match secure::store_gateway_api_key(&key) {
+            Ok(()) => gateway_secret_changed = true,
+            Err(e) => {
+                log::warn!(
+                    "Settings import: could not restore the gateway provider API key: {}",
+                    e
+                );
+                secret_restore_warnings.push(format!(
+                    "Could not restore the gateway provider API key: {}",
+                    e
+                ));
+            }
+        }
+    }
+    if let Some(key) = non_blank(payload.secrets.gateway_master_key) {
+        match secure::store_gateway_master_key(&key) {
+            Ok(()) => gateway_secret_changed = true,
+            Err(e) => {
+                log::warn!(
+                    "Settings import: could not restore the gateway master key: {}",
+                    e
+                );
+                secret_restore_warnings
+                    .push(format!("Could not restore the gateway master key: {}", e));
+            }
+        }
+    }
+
+    let saved =
+        crate::commands::settings_commands::update_settings(settings, state.clone()).await?;
+
+    // `reconcile_gateway` (inside `update_settings`) only reacts to a changed
+    // *shape* — port, provider, base URL, models — because that's what's
+    // rendered into the container's config. A secret changing with the shape
+    // held constant is invisible to it, so a running gateway container would
+    // otherwise keep serving the old key material forever after an import
+    // that restored a new one, while `docker::gateway`'s own fingerprint
+    // (which does include the secret rotation id) means the *next* unrelated
+    // settings save would suddenly and confusingly recreate it instead.
+    if gateway_secret_changed && saved.gateway.enabled {
+        match crate::docker::gateway::gateway_container_presence().await {
+            Ok((true, true)) => {
+                if let Err(e) = crate::docker::gateway::ensure_gateway_running(&saved.gateway).await
+                {
+                    log::error!(
+                        "Settings import: could not apply the restored gateway credentials to the running gateway container: {}",
+                        e
+                    );
+                }
+            }
+            Ok(_) => {}
+            Err(e) => log::debug!("Settings import: gateway reconcile skipped ({})", e),
+        }
+    }
+
+    state.pending_settings_import.lock().await.take();
+
+    Ok(SettingsImportOutcome {
+        settings: saved,
+        secret_restore_warnings,
+    })
+}
+
+fn non_blank(value: Option<String>) -> Option<String> {
+    value.filter(|v| !v.trim().is_empty())
+}
+
+/// Only the field `read_and_decrypt` needs before deciding whether the rest
+/// of the payload is even worth attempting to parse.
+#[derive(serde::Deserialize)]
+struct FormatVersionProbe {
+    format_version: u32,
+}
+
+/// Read and decrypt an export file at `path`, then parse it — see
+/// `read_and_decrypt_bytes` for why the format-version check runs before the
+/// full parse. Every real caller already has the file's bytes in hand by the
+/// time it needs this (`preview_settings_import`/`apply_settings_import`
+/// both hash the ciphertext first) and calls `read_and_decrypt_bytes`
+/// directly to avoid reading the file twice; this path-based wrapper only
+/// exists now for tests that don't need that.
+#[cfg(test)]
+fn read_and_decrypt(path: &Path, password: &str) -> Result<SettingsExportPayload, String> {
+    let encrypted =
+        std::fs::read(path).map_err(|e| format!("Failed to read export file: {}", e))?;
+    read_and_decrypt_bytes(&encrypted, password)
+}
+
+/// Decrypt and parse an already-read export file's bytes, checking the
+/// format version **before** attempting to deserialize the full payload.
+///
+/// That ordering is not just tidiness: a version bump that isn't
+/// deserialize-compatible (a field's type changes, not just a new
+/// `#[serde(default)]`-covered one) is exactly the case this check exists
+/// for, and parsing the full struct first would fail on the shape mismatch
+/// before the version check ever ran, surfacing a raw parse error instead
+/// of "update Triple-C" — and, more seriously, `serde_json`'s type-mismatch
+/// errors quote the offending value inline. This file is not attacker
+/// content in the usual sense (it must still decrypt under the right
+/// password), but the plaintext it decrypts to can hold a live credential,
+/// so neither error path below ever interpolates what `serde_json`
+/// actually says — only a fixed, generic message.
+fn read_and_decrypt_bytes(encrypted: &[u8], password: &str) -> Result<SettingsExportPayload, String> {
+    let plaintext = settings_crypto::decrypt(encrypted, password)?;
+
+    let probe: FormatVersionProbe = serde_json::from_slice(&plaintext)
+        .map_err(|_| "This file doesn't look like a valid settings export.".to_string())?;
+    if probe.format_version > SETTINGS_EXPORT_FORMAT_VERSION {
+        return Err(format!(
+            "This export was made by a newer version of Triple-C (format {}, this app supports up to {}). \
+             Update Triple-C before importing it.",
+            probe.format_version, SETTINGS_EXPORT_FORMAT_VERSION
+        ));
+    }
+
+    serde_json::from_slice(&plaintext).map_err(|_| {
+        "This file doesn't look like a valid settings export (unexpected shape).".to_string()
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn non_blank_treats_whitespace_only_as_absent() {
+        assert_eq!(non_blank(Some("   ".to_string())), None);
+        assert_eq!(non_blank(Some("".to_string())), None);
+        assert_eq!(non_blank(None), None);
+        assert_eq!(non_blank(Some(" a ".to_string())), Some(" a ".to_string()));
+    }
+
+    #[test]
+    fn ciphertext_hashing_is_deterministic_and_tamper_sensitive() {
+        // What `apply_settings_import` compares against the pinned hash from
+        // `preview_settings_import` to detect a file swapped out from under a
+        // pending import — this only defends anything if identical bytes
+        // always hash identically and any change to those bytes changes the
+        // hash.
+        let bytes = b"pretend this is an encrypted export file";
+        assert_eq!(hash_ciphertext(bytes), hash_ciphertext(bytes));
+
+        let mut tampered = bytes.to_vec();
+        tampered[0] ^= 0xFF;
+        assert_ne!(hash_ciphertext(bytes), hash_ciphertext(&tampered));
+    }
+
+    fn write_export(
+        dir: &std::path::Path,
+        name: &str,
+        payload: &SettingsExportPayload,
+        password: &str,
+    ) -> PathBuf {
+        write_raw_export(dir, name, &serde_json::to_value(payload).unwrap(), password)
+    }
+
+    /// Like `write_export`, but takes an arbitrary `serde_json::Value` rather
+    /// than a real `SettingsExportPayload` — for fixtures that are
+    /// deliberately not shape-compatible, which the typed helper above can't
+    /// produce at all.
+    fn write_raw_export(
+        dir: &std::path::Path,
+        name: &str,
+        value: &serde_json::Value,
+        password: &str,
+    ) -> PathBuf {
+        let plaintext = serde_json::to_vec(value).unwrap();
+        let encrypted = settings_crypto::encrypt(&plaintext, password).unwrap();
+        let path = dir.join(name);
+        std::fs::write(&path, &encrypted).unwrap();
+        path
+    }
+
+    #[test]
+    fn splitting_settings_moves_the_web_terminal_token_out_rather_than_copying_it() {
+        let mut settings = AppSettings::default();
+        settings.web_terminal.access_token = Some("super-secret-token".to_string());
+
+        let (settings, secrets) = split_settings_and_secrets(settings);
+
+        assert_eq!(settings.web_terminal.access_token, None);
+        assert_eq!(
+            secrets.web_terminal_access_token,
+            Some("super-secret-token".to_string())
+        );
+    }
+
+    #[test]
+    fn splitting_settings_with_no_token_leaves_it_absent_on_both_sides() {
+        let (settings, secrets) = split_settings_and_secrets(AppSettings::default());
+
+        assert_eq!(settings.web_terminal.access_token, None);
+        assert_eq!(secrets.web_terminal_access_token, None);
+    }
+
+    fn sample_payload(format_version: u32) -> SettingsExportPayload {
+        SettingsExportPayload {
+            format_version,
+            exported_at: "2026-08-27T00:00:00Z".to_string(),
+            app_version: "0.4.14".to_string(),
+            settings: AppSettings::default(),
+            secrets: ExportedSecrets::default(),
+        }
+    }
+
+    fn temp_dir(name: &str) -> PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "triple-c-settings-export-test-{}-{}",
+            name,
+            uuid::Uuid::new_v4().simple()
+        ));
+        std::fs::create_dir_all(&dir).unwrap();
+        dir
+    }
+
+    #[test]
+    fn a_file_from_a_newer_format_is_refused_before_the_full_shape_is_parsed() {
+        // Shape-incompatible with the *current* `SettingsExportPayload` (a
+        // future version could easily have changed `settings` from an object
+        // to something else) as well as newer — so this only passes under
+        // the probe-first ordering. Parsing the full struct first (the old
+        // behavior) would fail on the shape mismatch and never reach the
+        // version check, producing the "unexpected shape" message instead of
+        // "newer version" / "Update Triple-C".
+        let dir = temp_dir("newer-format");
+        let path = write_raw_export(
+            &dir,
+            "export.triplec",
+            &serde_json::json!({
+                "format_version": SETTINGS_EXPORT_FORMAT_VERSION + 1,
+                "exported_at": "2026-08-27T00:00:00Z",
+                "app_version": "9.9.9",
+                "settings": "this-app-version-stores-settings-differently",
+                "secrets": {},
+            }),
+            "correct password",
+        );
+
+        let err = read_and_decrypt(&path, "correct password").unwrap_err();
+        assert!(err.contains("newer version"), "unexpected message: {}", err);
+        assert!(err.contains("Update Triple-C"));
+
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn a_file_at_the_current_format_is_accepted() {
+        let dir = temp_dir("current-format");
+        let path = write_export(
+            &dir,
+            "export.triplec",
+            &sample_payload(SETTINGS_EXPORT_FORMAT_VERSION),
+            "correct password",
+        );
+
+        let payload = read_and_decrypt(&path, "correct password").unwrap();
+        assert_eq!(payload.format_version, SETTINGS_EXPORT_FORMAT_VERSION);
+
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn a_malformed_payload_produces_a_generic_error_not_a_raw_serde_message() {
+        // A `format_version` the probe accepts, but a `settings` field of
+        // the wrong *type* rather than just a missing field — this is what
+        // makes `serde_json` produce an "invalid type: string `...`, expected
+        // struct AppSettings" error that quotes the offending value
+        // verbatim. That value here stands in for plaintext that, in a real
+        // export, could be a live credential — the assertion below is only
+        // meaningful against a fixture that actually exercises serde's
+        // value-quoting behavior, which a merely-missing-field fixture does
+        // not.
+        let dir = temp_dir("malformed");
+        let path = write_raw_export(
+            &dir,
+            "export.triplec",
+            &serde_json::json!({
+                "format_version": SETTINGS_EXPORT_FORMAT_VERSION,
+                "exported_at": "2026-08-27T00:00:00Z",
+                "app_version": "0.4.14",
+                "settings": "NOT-A-REAL-CREDENTIAL-abc123",
+                "secrets": {},
+            }),
+            "correct password",
+        );
+
+        let err = read_and_decrypt(&path, "correct password").unwrap_err();
+        assert!(
+            !err.contains("NOT-A-REAL-CREDENTIAL-abc123"),
+            "leaked plaintext into the error: {}",
+            err
+        );
+        assert!(err.contains("doesn't look like a valid settings export"));
+
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn the_wrong_password_is_reported_without_a_version_check_ever_running() {
+        let dir = temp_dir("wrong-password");
+        let path = write_export(
+            &dir,
+            "export.triplec",
+            &sample_payload(SETTINGS_EXPORT_FORMAT_VERSION),
+            "correct password",
+        );
+
+        let err = read_and_decrypt(&path, "wrong password").unwrap_err();
+        assert!(
+            err.contains("Wrong password"),
+            "unexpected message: {}",
+            err
+        );
+
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}

app/src-tauri/src/commands/terminal_commands.rs

@@ -17,11 +17,11 @@ fn build_terminal_cmd(project: &Project, state: &AppState, session_name: Option<
             .map(|b| b.auth_method == BedrockAuthMethod::Profile)
             .unwrap_or(false);
 
+    let permission_args = project.effective_permission_mode().cli_args();
+
     if !is_bedrock_profile {
         let mut cmd = vec!["claude".to_string()];
-        if project.full_permissions {
-            cmd.push("--dangerously-skip-permissions".to_string());
-        }
+        cmd.extend(permission_args);
         if let Some(name) = session_name {
             if !name.is_empty() {
                 cmd.push("-n".to_string());
@@ -42,11 +42,13 @@ fn build_terminal_cmd(project: &Project, state: &AppState, session_name: Option<
         .filter(|n| !n.is_empty())
         .map(|n| format!(" -n '{}'", n.replace('\'', "'\\''")))
         .unwrap_or_default();
-    let claude_cmd = if project.full_permissions {
-        format!("exec claude --dangerously-skip-permissions{}", name_flag)
-    } else {
-        format!("exec claude{}", name_flag)
-    };
+    // The args are interpolated into a shell script string, so single-quote
+    // each one (same escaping style as name_flag above).
+    let permission_flags: String = permission_args
+        .iter()
+        .map(|a| format!(" '{}'", a.replace('\'', "'\\''")))
+        .collect();
+    let claude_cmd = format!("exec claude{}{}", permission_flags, name_flag);
 
     let script = format!(
         r#"
@@ -183,6 +185,94 @@ pub async fn paste_image_to_terminal(
         .await
 }
 
+/// Copy a host file (e.g. dragged onto the terminal) into the container so
+/// Claude Code can read it, and return the in-container path. Mirrors the
+/// image-paste flow: the file is placed under /tmp/triple-c-drops/ keeping its
+/// original name. Returns an error for paths that aren't readable regular files
+/// (e.g. a dropped directory).
+#[tauri::command]
+pub async fn upload_host_file_to_terminal(
+    session_id: String,
+    host_path: String,
+    state: State<'_, AppState>,
+) -> Result<String, String> {
+    // The drop target is a host path chosen by the webview, not by the OS drag
+    // itself, so it goes through `file_commands`' host-read policy: absolute,
+    // no traversal, and nothing whose path passes through a hidden directory
+    // (`~/.ssh`, `~/.aws`, `~/.local/bin`) or a system location — applied to
+    // the path with its symlinks already resolved, so a visible directory that
+    // *leads* to one of those is refused too. What comes back is that resolved
+    // path, and it is what gets opened. Four commands touch a host path now,
+    // but only two take it *over IPC*: this one and `download_container_backup`.
+    // The Files pane's `download_container_file` and `upload_files_to_container`
+    // open their dialog from Rust instead, so for them the policy above is
+    // defence in depth and for these two it is the boundary itself.
+    // The name is taken from the path the user actually dropped, *before*
+    // resolution. Deriving it from the resolved path renames the file behind
+    // the user's back: dropping `~/Downloads/latest.log`, where `latest.log` is
+    // a symlink, would land it in the container as `2026-08-23.log`.
+    let base = crate::commands::file_commands::host_upload_name(&host_path)?;
+    let host_path = crate::commands::file_commands::resolve_host_read_path(&host_path).await?;
+
+    let container_id = state.exec_manager.get_container_id(&session_id).await?;
+
+    let meta = tokio::fs::metadata(&host_path)
+        .await
+        .map_err(|e| format!("Cannot access {}: {}", host_path, e))?;
+    // `!is_file()`, not `!is_dir()`. A FIFO is neither a directory nor a
+    // regular file, reports `len() == 0`, and passes both the directory check
+    // and the size cap below — and `std::fs::File::open` on one blocks forever
+    // with no writer, with no timeout anywhere on this path. The upload then
+    // never returns, the toast sticks on "Adding N files…" for the session and
+    // the rest of the batch is abandoned. Sockets and device nodes are the same
+    // shape. This is one of two routes for getting a host file into a
+    // container (the Files pane's upload is the other), so it is the wrong
+    // place to be clever.
+    if !meta.is_file() {
+        return Err(if meta.is_dir() {
+            format!("{} is a directory — drop individual files", host_path)
+        } else {
+            format!(
+                "{} is not a regular file — only ordinary files can be dropped into a terminal",
+                host_path
+            )
+        });
+    }
+
+    // Guard against ballooning host RAM: the file is packed into an in-memory
+    // tar before upload, so cap the size of a dropped file. The ceiling lives
+    // with the code that does the reading, which re-applies it to the open
+    // descriptor — this check is here only so the refusal reads like a sentence
+    // instead of arriving after a 300 MB read.
+    use crate::docker::exec::MAX_DROP_BYTES;
+    if meta.len() > MAX_DROP_BYTES {
+        return Err(format!(
+            "File too large to drop into the terminal ({:.0} MB; limit {} MB). Mount it into the project instead.",
+            meta.len() as f64 / (1024.0 * 1024.0),
+            MAX_DROP_BYTES / (1024 * 1024)
+        ));
+    }
+
+
+
+    // Ensure the destination directory exists rather than relying on Docker's
+    // archive extractor to create the parent for the uploaded tar entry.
+    crate::docker::exec::exec_oneshot(
+        &container_id,
+        vec!["mkdir".to_string(), "-p".to_string(), "/tmp/triple-c-drops".to_string()],
+    )
+    .await?;
+
+    let file_name = format!("triple-c-drops/{}", base);
+    crate::docker::exec::upload_host_file_to_container(
+        &container_id,
+        &host_path,
+        "/tmp",
+        &file_name,
+    )
+    .await
+}
+
 #[tauri::command]
 pub async fn start_audio_bridge(
     session_id: String,
@@ -232,3 +322,37 @@ pub async fn stop_audio_bridge(
     state.exec_manager.close_session(&audio_session_id).await;
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    /// A dropped file must be named the way the *user* named it.
+    ///
+    /// The bug this pins: `upload_host_file_to_terminal` derived the tar entry
+    /// name from the path *after* symlink resolution, so dropping
+    /// `~/Downloads/latest.log` — where `latest.log` is a symlink to
+    /// `2026-08-23.log` — silently landed the file in the container under the
+    /// target's name. Nothing errored; the user just got a name they never
+    /// typed.
+    ///
+    /// This asserts the shared helper's contract from the terminal side: the
+    /// answer comes from the spelling, and a path that does not name a file is
+    /// refused rather than silently substituted (it used to fall back to
+    /// `"dropped-file"`).
+    #[test]
+    fn a_dropped_file_keeps_the_name_the_user_dropped() {
+        use crate::commands::file_commands::host_upload_name;
+
+        assert_eq!(
+            host_upload_name("/home/u/Downloads/latest.log").unwrap(),
+            "latest.log"
+        );
+        assert!(
+            host_upload_name("/home/u/Downloads/").is_err(),
+            "a directory is not a file to drop"
+        );
+        assert!(
+            host_upload_name("/home/u/..").is_err(),
+            "the name becomes a tar entry, a container path and an argv element"
+        );
+    }
+}

app/src-tauri/src/commands/update_commands.rs

@@ -16,9 +16,37 @@ const REGISTRY_API_BASE: &str =
 const GHCR_TOKEN_URL: &str =
     "https://ghcr.io/token?scope=repository:shadowdao/triple-c-sandbox:pull";
 
+/// The build-time preview suffix, if one was baked in and isn't blank.
+///
+/// The bundle version itself (`tauri.conf.json`, `Cargo.toml`, `package.json`)
+/// is never given a `-preview.<sha>` suffix — `build-app-preview.yml` strips
+/// it before patching those files, because the Windows MSI's `ProductVersion`
+/// is a fixed-width numeric field with no room for one, and nothing here can
+/// verify a change to that without an actual Windows build. `TRIPLE_C_BUILD_SUFFIX`
+/// is the workaround: set as a build-time env var in the preview workflow
+/// only, so `option_env!` bakes it into the binary without the bundle version
+/// ever seeing it. A production build sets nothing, so `option_env!` reads
+/// `None` here — see triple-c#32.
+///
+/// The single source of truth for "is this a preview build": both
+/// `get_app_version()` (what the About panel shows) and `check_for_updates()`
+/// (whether a same-numbered release counts as an update — see `pick_update`)
+/// read this rather than each calling `option_env!` themselves, so the two
+/// can never silently disagree about which build this is.
+fn preview_build_suffix() -> Option<&'static str> {
+    option_env!("TRIPLE_C_BUILD_SUFFIX").filter(|s| !s.is_empty())
+}
+
+fn format_app_version(base: &str, build_suffix: Option<&str>) -> String {
+    match build_suffix {
+        Some(suffix) if !suffix.is_empty() => format!("{}-{}", base, suffix),
+        _ => base.to_string(),
+    }
+}
+
 #[tauri::command]
 pub fn get_app_version() -> String {
-    env!("CARGO_PKG_VERSION").to_string()
+    format_app_version(env!("CARGO_PKG_VERSION"), preview_build_suffix())
 }
 
 #[tauri::command]
@@ -51,30 +79,20 @@ pub async fn check_for_updates() -> Result<Option<UpdateInfo>, String> {
         &[".AppImage", ".deb", ".rpm"]
     };
 
-    // Filter releases that have at least one asset matching the current platform
-    let platform_releases: Vec<&GitHubRelease> = releases
-        .iter()
-        .filter(|r| {
-            r.assets.iter().any(|a| {
-                platform_extensions.iter().any(|ext| a.name.ends_with(ext))
-            })
-        })
-        .collect();
+    // `current_version` above is always the bare, stripped `CARGO_PKG_VERSION`
+    // — the preview workflow patches `Cargo.toml` with that before compiling,
+    // never the `-preview.<sha>`-suffixed one `get_app_version()` reports —
+    // so a preview build and the release it precedes compile to the identical
+    // numeric tuple by construction (see `build-app-preview.yml`'s "highest
+    // tag used, +1" computation). A strict `>` therefore never fires for the
+    // one release a preview most needs to be offered. `is_preview_build`
+    // relaxes that one comparison to `>=` so "there is a real release at my
+    // own number" reads as an update, without touching the production case
+    // — see `pick_update`.
+    let is_preview_build = preview_build_suffix().is_some();
 
-    // Find the latest release with a higher semver version
-    let mut best: Option<(&GitHubRelease, (u32, u32, u32))> = None;
-    for release in &platform_releases {
-        if let Some(ver) = parse_semver_from_tag(&release.tag_name) {
-            if ver > current_semver {
-                if best.is_none() || ver > best.unwrap().1 {
-                    best = Some((release, ver));
-                }
-            }
-        }
-    }
-
-    match best {
-        Some((release, _)) => {
+    match pick_update(&releases, current_semver, platform_extensions, is_preview_build) {
+        Some(release) => {
             // Only include assets matching the current platform
             let assets = release
                 .assets
@@ -105,6 +123,51 @@ pub async fn check_for_updates() -> Result<Option<UpdateInfo>, String> {
     }
 }
 
+/// Pick the newest available update out of a release list, or `None` if
+/// nothing beats `current_semver`. Pure and synchronous — split out of
+/// `check_for_updates` so the prerelease/platform/version filtering can be
+/// tested without a live HTTP call.
+///
+/// Three filters, all of which must pass: not a prerelease (see the long
+/// comment on `GitHubRelease::prerelease`), at least one asset for this
+/// platform, and a tag that parses as semver *and* beats what is running. A
+/// tag that does not parse — `preview-<sha>` (the shape
+/// `build-app-preview.yml` actually creates release tags with), most
+/// realistically — is skipped rather than erroring, the same as it always
+/// has been; nothing here changes what an update tag is expected to look
+/// like, only what channel it is allowed to come from.
+///
+/// `is_preview_build` relaxes "beats" from `>` to `>=`. A preview build's
+/// `current_semver` is the bare number it was compiled with, which is by
+/// construction identical to the release it precedes — see the comment at
+/// `check_for_updates`'s call site — so a strict `>` would never fire for
+/// exactly the release a preview install most needs to be told about.
+fn pick_update<'a>(
+    releases: &'a [GitHubRelease],
+    current_semver: (u32, u32, u32),
+    platform_extensions: &[&str],
+    is_preview_build: bool,
+) -> Option<&'a GitHubRelease> {
+    releases
+        .iter()
+        .filter(|r| !r.prerelease)
+        .filter(|r| {
+            r.assets
+                .iter()
+                .any(|a| platform_extensions.iter().any(|ext| a.name.ends_with(ext)))
+        })
+        .filter_map(|r| parse_semver_from_tag(&r.tag_name).map(|ver| (r, ver)))
+        .filter(|(_, ver)| {
+            if is_preview_build {
+                *ver >= current_semver
+            } else {
+                *ver > current_semver
+            }
+        })
+        .max_by_key(|(_, ver)| *ver)
+        .map(|(r, _)| r)
+}
+
 /// Parse a semver string like "0.2.5" -> (0, 2, 5)
 fn parse_semver(version: &str) -> Option<(u32, u32, u32)> {
     let clean = version.trim_start_matches('v');
@@ -131,6 +194,120 @@ fn extract_version_from_tag(tag: &str) -> Option<String> {
     Some(format!("{}.{}.{}", major, minor, patch))
 }
 
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::GitHubAsset;
+
+    // ── format_app_version ──────────────────────────────────────────────
+
+    #[test]
+    fn a_production_build_reports_the_bare_version() {
+        assert_eq!(format_app_version("0.4.12", None), "0.4.12");
+        // An empty env var (set but blank) must not print a trailing dash.
+        assert_eq!(format_app_version("0.4.12", Some("")), "0.4.12");
+    }
+
+    #[test]
+    fn a_preview_build_reports_its_suffix() {
+        assert_eq!(
+            format_app_version("0.4.12", Some("preview.a1b2c3d")),
+            "0.4.12-preview.a1b2c3d"
+        );
+    }
+
+    // ── pick_update ──────────────────────────────────────────────────────
+
+    fn release(tag: &str, prerelease: bool, asset_names: &[&str]) -> GitHubRelease {
+        GitHubRelease {
+            tag_name: tag.to_string(),
+            html_url: format!("https://example.invalid/{}", tag),
+            body: String::new(),
+            assets: asset_names
+                .iter()
+                .map(|name| GitHubAsset {
+                    name: name.to_string(),
+                    browser_download_url: String::new(),
+                    size: 0,
+                })
+                .collect(),
+            published_at: "2026-01-01T00:00:00Z".to_string(),
+            prerelease,
+        }
+    }
+
+    const LINUX_EXTENSIONS: &[&str] = &[".AppImage", ".deb", ".rpm"];
+
+    #[test]
+    fn a_prerelease_is_never_offered_even_if_its_tag_would_otherwise_win() {
+        let releases = vec![release("v9.9.9", true, &["app-9.9.9.AppImage"])];
+        assert!(pick_update(&releases, (0, 4, 10), LINUX_EXTENSIONS, false).is_none());
+    }
+
+    #[test]
+    fn a_release_with_no_asset_for_this_platform_is_skipped() {
+        let releases = vec![release("v0.4.12", false, &["app-0.4.12.msi"])];
+        assert!(pick_update(&releases, (0, 4, 10), LINUX_EXTENSIONS, false).is_none());
+    }
+
+    #[test]
+    fn a_release_that_is_not_newer_is_not_offered() {
+        let releases = vec![release("v0.4.10", false, &["app.AppImage"])];
+        assert!(pick_update(&releases, (0, 4, 10), LINUX_EXTENSIONS, false).is_none());
+    }
+
+    #[test]
+    fn an_untagged_or_unparseable_release_is_skipped_not_fatal() {
+        // A `-preview.<sha>` tag is exactly the shape this must not choke on
+        // or mistake for an update — it simply never parses as a bare semver.
+        let releases = vec![
+            release("preview-a1b2c3d", false, &["app.AppImage"]),
+            release("v0.4.12", false, &["app.AppImage"]),
+        ];
+        let best = pick_update(&releases, (0, 4, 10), LINUX_EXTENSIONS, false).unwrap();
+        assert_eq!(best.tag_name, "v0.4.12");
+    }
+
+    #[test]
+    fn the_highest_qualifying_version_wins_not_the_first_or_last_in_the_list() {
+        let releases = vec![
+            release("v0.4.11", false, &["app.AppImage"]),
+            release("v0.4.13", false, &["app.AppImage"]),
+            release("v0.4.12", false, &["app.AppImage"]),
+        ];
+        let best = pick_update(&releases, (0, 4, 10), LINUX_EXTENSIONS, false).unwrap();
+        assert_eq!(best.tag_name, "v0.4.13");
+    }
+
+    // ── is_preview_build (>= instead of >) ─────────────────────────────────
+
+    /// The exact scenario triple-c#32 was filed to fix: a preview compiled as
+    /// `0.4.12-preview.<sha>` (bare `CARGO_PKG_VERSION` "0.4.12") must be
+    /// offered the `v0.4.12` release that follows it, even though the two
+    /// compute to the identical numeric tuple.
+    #[test]
+    fn a_preview_build_is_offered_the_release_it_precedes() {
+        let releases = vec![release("v0.4.12", false, &["app.AppImage"])];
+        assert!(pick_update(&releases, (0, 4, 12), LINUX_EXTENSIONS, false).is_none());
+        let best = pick_update(&releases, (0, 4, 12), LINUX_EXTENSIONS, true).unwrap();
+        assert_eq!(best.tag_name, "v0.4.12");
+    }
+
+    #[test]
+    fn a_preview_build_is_not_offered_an_older_release() {
+        let releases = vec![release("v0.4.11", false, &["app.AppImage"])];
+        assert!(pick_update(&releases, (0, 4, 12), LINUX_EXTENSIONS, true).is_none());
+    }
+
+    #[test]
+    fn a_production_build_still_requires_strictly_newer() {
+        // A production build must never treat "equal" as an update — that
+        // would perpetually re-offer the version already running.
+        let releases = vec![release("v0.4.12", false, &["app.AppImage"])];
+        assert!(pick_update(&releases, (0, 4, 12), LINUX_EXTENSIONS, false).is_none());
+    }
+}
+
 /// Check whether a newer container image is available in the registry.
 ///
 /// Compares the local image digest with the remote registry digest using the

app/src-tauri/src/docker/ca_certs.rs

@@ -0,0 +1,580 @@
+//! Corporate CA certificate injection.
+//!
+//! Users behind a TLS-terminating corporate proxy need their organisation's
+//! root CA inside every container, or **every** HTTPS call fails — npm, pip,
+//! git, curl, the Playwright browser, and Claude Code's own API calls.
+//!
+//! The mechanism follows the SSH/AWS host-mount pattern in [`super::container`]:
+//! a host path is bind-mounted **read-only** into the container and
+//! `entrypoint.sh` applies it on every start. That is what makes it durable
+//! across container recreation, base-image migration and Reset — a certificate
+//! installed by hand inside a running container is lost the first time any of
+//! those happen.
+//!
+//! ## Two things that are easy to get wrong
+//!
+//! 1. **`update-ca-certificates` only reads `*.crt`.** It globs
+//!    `/usr/local/share/ca-certificates/*.crt` case-sensitively, so a `.pem`
+//!    (the far more common export format) that is merely *copied* in is
+//!    silently ignored — no warning, no error, just a container that still
+//!    cannot speak HTTPS. Certificates must be **renamed**, which is what
+//!    [`container_cert_name`] does.
+//!
+//! 2. **The system trust store is not enough.** Only curl/git/apt read it.
+//!    Node — and therefore Claude Code itself — needs `NODE_EXTRA_CA_CERTS`,
+//!    Python/requests need `REQUESTS_CA_BUNDLE`/`SSL_CERT_FILE`, and
+//!    Chrome/Chromium read neither: they have their own NSS database at
+//!    `~/.pki/nssdb`, seeded by `certutil` in the entrypoint.
+//!
+//! ## Why the env vars are set from Rust and not exported by the entrypoint
+//!
+//! An `export` in `entrypoint.sh` reaches only the entrypoint's own children.
+//! Every terminal session is a separate `docker exec`, which inherits the
+//! *container's* configured env and sees nothing the entrypoint exported —
+//! the same lesson that forced `$BROWSER` to become an image-level `ENV` for
+//! the URL relay shim. Since the bundle path written by
+//! `update-ca-certificates` is deterministic ([`CA_BUNDLE_PATH`]), Rust can set
+//! all three vars at container creation, where `docker exec` will see them.
+
+use std::path::{Path, PathBuf};
+
+use sha2::{Digest, Sha256};
+
+/// Where the host's CA material is bind-mounted, read-only. Mirrors
+/// `/tmp/.host-ssh` and `/tmp/.host-aws`.
+///
+/// A *directory* on the host is mounted here as-is. A single *file* is mounted
+/// at `<CA_MOUNT_DIR>/<normalised name>` — Docker creates the parent — so the
+/// entrypoint only ever has to deal with a directory, and the certificate keeps
+/// a recognisable name instead of becoming the literal path `.host-ca`.
+pub const CA_MOUNT_DIR: &str = "/tmp/.host-ca";
+
+/// The concatenated PEM bundle `update-ca-certificates` writes on
+/// Debian/Ubuntu. Deterministic, which is what lets the env vars below be set
+/// at container-creation time, before the entrypoint has run.
+pub const CA_BUNDLE_PATH: &str = "/etc/ssl/certs/ca-certificates.crt";
+
+/// Consulted by Node — and therefore by Claude Code itself, which is the whole
+/// reason this feature exists.
+pub const NODE_EXTRA_CA_CERTS: &str = "NODE_EXTRA_CA_CERTS";
+/// Consulted by `requests` (and so by pip's vendored copy).
+pub const REQUESTS_CA_BUNDLE: &str = "REQUESTS_CA_BUNDLE";
+/// Consulted by OpenSSL, and so by Python's `ssl` module.
+pub const SSL_CERT_FILE: &str = "SSL_CERT_FILE";
+
+/// Every env var this module owns, in a fixed order.
+///
+/// Also the list that must be *cleared* when no CA is configured: `docker
+/// commit` bakes a container's env into the project's snapshot image, and
+/// create-time env replaces image `ENV` per key — so without an explicit empty
+/// value, removing the setting would leave the vars live in every future
+/// container. Empty is safe for all three (verified on Ubuntu 24.04: curl,
+/// `openssl s_client` and Python's `ssl` all behave exactly as they do with the
+/// variable unset).
+pub const CA_ENV_KEYS: &[&str] = &[NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, SSL_CERT_FILE];
+
+/// Extensions treated as certificates when the configured path is a directory.
+/// Matched case-insensitively. DER is deliberately absent — the system store
+/// and every consumer here want PEM.
+const CERT_EXTENSIONS: &[&str] = &["crt", "pem", "cer", "cert", "ca-bundle"];
+
+/// A configured CA path that has been checked and resolved into everything the
+/// container creation path needs.
+#[derive(Debug, Clone, PartialEq)]
+pub struct ResolvedCa {
+    /// The host path, as configured.
+    pub host_path: String,
+    /// Whether the host path is a directory (as opposed to a single file).
+    pub is_dir: bool,
+    /// The bind-mount target inside the container.
+    pub mount_target: String,
+    /// The certificate files found, sorted.
+    pub cert_files: Vec<PathBuf>,
+}
+
+fn sha256_hex(input: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(input.as_bytes());
+    format!("{:x}", hasher.finalize())
+}
+
+/// The file name a certificate is installed as under
+/// `/usr/local/share/ca-certificates/`.
+///
+/// `update-ca-certificates` globs `*.crt` **case-sensitively**, so `.pem`,
+/// `.cer`, `.CRT` and extension-less files all have to end up as a lowercase
+/// `.crt` or they are ignored without a word. Characters outside
+/// `[A-Za-z0-9._-]` are replaced so that whitespace cannot break the shell
+/// loops that walk the store, and leading dots are stripped so a hidden file
+/// does not stay hidden.
+///
+/// `entrypoint.sh` reimplements exactly this in a few lines of shell (it has to
+/// rename the files inside the container); the two must agree, which is what
+/// the unit tests below pin down.
+pub fn container_cert_name(file_name: &str) -> String {
+    let sanitized: String = file_name
+        .chars()
+        .map(|c| {
+            if c.is_ascii_alphanumeric() || c == '.' || c == '_' || c == '-' {
+                c
+            } else {
+                '_'
+            }
+        })
+        .collect();
+    let sanitized = sanitized.trim_start_matches('.');
+    // Strip one trailing extension, whatever it is, then force `.crt`. A name
+    // with no dot keeps its whole self as the stem.
+    let stem = match sanitized.rfind('.') {
+        Some(i) => &sanitized[..i],
+        None => sanitized,
+    };
+    let stem = if stem.is_empty() { "corporate-ca" } else { stem };
+    format!("{}.crt", stem)
+}
+
+/// Whether a directory entry looks like a certificate worth installing.
+fn is_cert_file(path: &Path) -> bool {
+    let Some(ext) = path.extension().and_then(|e| e.to_str()) else {
+        return false;
+    };
+    let ext = ext.to_ascii_lowercase();
+    CERT_EXTENSIONS.contains(&ext.as_str())
+}
+
+/// The certificate files a configured path contributes.
+///
+/// A file is taken at face value — the user pointed at it explicitly, so its
+/// extension is not second-guessed. A directory is scanned one level deep
+/// (matching the entrypoint's `find -maxdepth 1`) and filtered by extension,
+/// so an `openssl.cnf` or a README sitting next to the certs is skipped.
+/// The result is sorted, so the fingerprint is stable across filesystem
+/// enumeration order.
+pub fn collect_cert_files(path: &Path) -> Vec<PathBuf> {
+    if path.is_file() {
+        return vec![path.to_path_buf()];
+    }
+    if !path.is_dir() {
+        return Vec::new();
+    }
+    let Ok(entries) = std::fs::read_dir(path) else {
+        return Vec::new();
+    };
+    let mut files: Vec<PathBuf> = entries
+        .filter_map(|e| e.ok())
+        .map(|e| e.path())
+        .filter(|p| p.is_file() && is_cert_file(p))
+        .collect();
+    files.sort();
+    files
+}
+
+/// Resolve the configured CA path, or explain why it cannot be used.
+///
+/// `Ok(None)` means "no CA configured", which is the overwhelmingly common
+/// case and must stay free. An `Err` aborts the container start: behind a
+/// TLS-intercepting proxy a container without the CA is broken in a dozen
+/// confusing ways, so naming the bad path once is far kinder than letting npm,
+/// pip and Claude Code each fail their own way.
+pub fn resolve(path: Option<&str>) -> Result<Option<ResolvedCa>, String> {
+    let Some(raw) = path.map(str::trim).filter(|s| !s.is_empty()) else {
+        return Ok(None);
+    };
+    let root = Path::new(raw);
+    if !root.exists() {
+        return Err(format!(
+            "Corporate CA certificate path '{}' does not exist. Update it in \
+             Settings → Certificates, or clear this project's override in \
+             Project Home → Config → Access.",
+            raw
+        ));
+    }
+
+    let is_dir = root.is_dir();
+    if !is_dir && !root.is_file() {
+        return Err(format!(
+            "Corporate CA certificate path '{}' is neither a file nor a directory.",
+            raw
+        ));
+    }
+
+    let cert_files = collect_cert_files(root);
+    if cert_files.is_empty() {
+        return Err(format!(
+            "Corporate CA certificate directory '{}' contains no certificate files \
+             (looked for {} one level deep).",
+            raw,
+            CERT_EXTENSIONS
+                .iter()
+                .map(|e| format!(".{}", e))
+                .collect::<Vec<_>>()
+                .join(", ")
+        ));
+    }
+
+    let mount_target = if is_dir {
+        CA_MOUNT_DIR.to_string()
+    } else {
+        let name = root
+            .file_name()
+            .map(|n| container_cert_name(&n.to_string_lossy()))
+            .unwrap_or_else(|| "corporate-ca.crt".to_string());
+        format!("{}/{}", CA_MOUNT_DIR, name)
+    };
+
+    Ok(Some(ResolvedCa {
+        host_path: raw.to_string(),
+        is_dir,
+        mount_target,
+        cert_files,
+    }))
+}
+
+/// Fingerprint of the CA configuration, for the `triple-c.ca-fingerprint`
+/// label.
+///
+/// `container_needs_recreation` is label-based and never diffs env or mounts,
+/// so without this, changing the CA path would silently do nothing until some
+/// unrelated setting forced a rebuild.
+///
+/// It covers **both** the resolved path *and the bytes of every certificate*,
+/// because replacing a rotated CA at the same path is at least as common as
+/// moving it — and the container's copy is made once, at start, so nothing else
+/// would notice.
+///
+/// Never returns an error: a path that has gone missing hashes differently from
+/// one that is present, which is exactly the "something changed, recreate"
+/// signal wanted here. Reporting the problem is [`resolve`]'s job.
+pub fn compute_ca_fingerprint(path: Option<&str>) -> String {
+    let Some(raw) = path.map(str::trim).filter(|s| !s.is_empty()) else {
+        return String::new();
+    };
+    let mut parts: Vec<String> = vec![raw.to_string()];
+    let root = Path::new(raw);
+    if !root.exists() {
+        parts.push("<missing>".to_string());
+    } else {
+        for file in collect_cert_files(root) {
+            let name = file
+                .file_name()
+                .map(|n| container_cert_name(&n.to_string_lossy()))
+                .unwrap_or_default();
+            let digest = match std::fs::read(&file) {
+                Ok(bytes) => {
+                    let mut hasher = Sha256::new();
+                    hasher.update(&bytes);
+                    format!("{:x}", hasher.finalize())
+                }
+                Err(_) => "<unreadable>".to_string(),
+            };
+            parts.push(format!("{}:{}", name, digest));
+        }
+    }
+    sha256_hex(&parts.join("|"))
+}
+
+/// The env vars to set on the container.
+///
+/// Always returns all of [`CA_ENV_KEYS`]: pointing at the bundle when a CA is
+/// configured, empty when it is not. The empty case is not cosmetic — see the
+/// note on [`CA_ENV_KEYS`].
+pub fn ca_env_vars(resolved: Option<&ResolvedCa>) -> Vec<(&'static str, String)> {
+    let value = if resolved.is_some() { CA_BUNDLE_PATH } else { "" };
+    CA_ENV_KEYS
+        .iter()
+        .map(|key| (*key, value.to_string()))
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+
+    /// A scratch directory that cleans itself up. `tempfile` is not a
+    /// dependency of this crate and this is the only test that needs one.
+    struct TempDir(PathBuf);
+
+    impl TempDir {
+        fn new(tag: &str) -> Self {
+            let mut p = std::env::temp_dir();
+            p.push(format!(
+                "triple-c-ca-test-{}-{}-{:?}",
+                tag,
+                std::process::id(),
+                std::time::SystemTime::now()
+                    .duration_since(std::time::UNIX_EPOCH)
+                    .unwrap()
+                    .as_nanos()
+            ));
+            fs::create_dir_all(&p).unwrap();
+            TempDir(p)
+        }
+        fn path(&self) -> &Path {
+            &self.0
+        }
+        fn write(&self, name: &str, contents: &str) -> PathBuf {
+            let p = self.0.join(name);
+            fs::write(&p, contents).unwrap();
+            p
+        }
+    }
+
+    impl Drop for TempDir {
+        fn drop(&mut self) {
+            let _ = fs::remove_dir_all(&self.0);
+        }
+    }
+
+    // ── container_cert_name ────────────────────────────────────────────────
+
+    #[test]
+    fn a_pem_is_renamed_to_crt_not_merely_copied() {
+        // The whole point: update-ca-certificates globs *.crt and would
+        // silently ignore corp-root.pem.
+        assert_eq!(container_cert_name("corp-root.pem"), "corp-root.crt");
+    }
+
+    #[test]
+    fn a_crt_keeps_its_name() {
+        assert_eq!(container_cert_name("corp-root.crt"), "corp-root.crt");
+    }
+
+    #[test]
+    fn other_certificate_extensions_are_renamed_too() {
+        assert_eq!(container_cert_name("zscaler.cer"), "zscaler.crt");
+        assert_eq!(container_cert_name("zscaler.cert"), "zscaler.crt");
+        assert_eq!(container_cert_name("bundle.ca-bundle"), "bundle.crt");
+    }
+
+    #[test]
+    fn an_uppercase_extension_is_lowercased() {
+        // `find -name '*.crt'` is case-sensitive, so CA.CRT would be ignored.
+        assert_eq!(container_cert_name("CA.CRT"), "CA.crt");
+        assert_eq!(container_cert_name("CA.PEM"), "CA.crt");
+    }
+
+    #[test]
+    fn a_name_without_an_extension_gains_one() {
+        assert_eq!(container_cert_name("corporate-root"), "corporate-root.crt");
+    }
+
+    #[test]
+    fn only_the_last_extension_is_replaced() {
+        assert_eq!(container_cert_name("corp.root.ca.pem"), "corp.root.ca.crt");
+    }
+
+    #[test]
+    fn unsafe_characters_are_replaced() {
+        assert_eq!(
+            container_cert_name("Corp Root CA (2026).pem"),
+            "Corp_Root_CA__2026_.crt"
+        );
+        assert_eq!(container_cert_name("a/b.pem"), "a_b.crt");
+    }
+
+    #[test]
+    fn leading_dots_are_stripped_so_the_file_is_not_hidden() {
+        assert_eq!(container_cert_name(".hidden.pem"), "hidden.crt");
+    }
+
+    #[test]
+    fn a_degenerate_name_still_produces_a_usable_file() {
+        assert_eq!(container_cert_name(".pem"), "pem.crt");
+        assert_eq!(container_cert_name(""), "corporate-ca.crt");
+        assert_eq!(container_cert_name("..."), "corporate-ca.crt");
+    }
+
+    #[test]
+    fn every_produced_name_ends_in_lowercase_crt() {
+        for input in [
+            "a.pem", "b.CRT", "c", ".d.pem", "", "e f.cer", "...", "ç.pem",
+        ] {
+            let out = container_cert_name(input);
+            assert!(
+                out.ends_with(".crt"),
+                "{:?} produced {:?}, which update-ca-certificates would ignore",
+                input,
+                out
+            );
+            assert!(
+                out.chars()
+                    .all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '_' || c == '-'),
+                "{:?} produced {:?}, which is not shell-safe",
+                input,
+                out
+            );
+        }
+    }
+
+    // ── fingerprint ────────────────────────────────────────────────────────
+
+    #[test]
+    fn no_configured_path_fingerprints_as_empty() {
+        assert_eq!(compute_ca_fingerprint(None), "");
+        assert_eq!(compute_ca_fingerprint(Some("")), "");
+        assert_eq!(compute_ca_fingerprint(Some("   ")), "");
+    }
+
+    #[test]
+    fn changing_the_path_changes_the_fingerprint() {
+        let a = TempDir::new("path-a");
+        let b = TempDir::new("path-b");
+        // Identical *content* in both, so only the path differs.
+        a.write("corp.pem", "CERT-BODY");
+        b.write("corp.pem", "CERT-BODY");
+
+        let fp_a = compute_ca_fingerprint(Some(a.path().to_str().unwrap()));
+        let fp_b = compute_ca_fingerprint(Some(b.path().to_str().unwrap()));
+        assert_ne!(fp_a, "");
+        assert_ne!(
+            fp_a, fp_b,
+            "two different paths must not share a fingerprint"
+        );
+    }
+
+    #[test]
+    fn changing_the_certificate_content_at_the_same_path_changes_the_fingerprint() {
+        // The case a path-only fingerprint would miss: the corporate CA is
+        // rotated and the new one dropped in at exactly the same location.
+        let dir = TempDir::new("rotate");
+        dir.write("corp.pem", "OLD-CERT");
+        let before = compute_ca_fingerprint(Some(dir.path().to_str().unwrap()));
+
+        dir.write("corp.pem", "NEW-CERT");
+        let after = compute_ca_fingerprint(Some(dir.path().to_str().unwrap()));
+
+        assert_ne!(
+            before, after,
+            "replacing the certificate at the same path must force a recreation"
+        );
+    }
+
+    #[test]
+    fn adding_or_removing_a_certificate_changes_the_fingerprint() {
+        let dir = TempDir::new("add");
+        dir.write("one.pem", "A");
+        let one = compute_ca_fingerprint(Some(dir.path().to_str().unwrap()));
+        dir.write("two.pem", "B");
+        let two = compute_ca_fingerprint(Some(dir.path().to_str().unwrap()));
+        assert_ne!(one, two);
+        fs::remove_file(dir.path().join("two.pem")).unwrap();
+        assert_eq!(compute_ca_fingerprint(Some(dir.path().to_str().unwrap())), one);
+    }
+
+    #[test]
+    fn an_unchanged_directory_fingerprints_identically() {
+        let dir = TempDir::new("stable");
+        dir.write("corp.pem", "SAME");
+        let a = compute_ca_fingerprint(Some(dir.path().to_str().unwrap()));
+        let b = compute_ca_fingerprint(Some(dir.path().to_str().unwrap()));
+        assert_eq!(a, b, "the fingerprint must not churn on repeated reads");
+    }
+
+    #[test]
+    fn a_missing_path_fingerprints_differently_from_a_present_one() {
+        let dir = TempDir::new("missing");
+        let present = compute_ca_fingerprint(Some(dir.path().to_str().unwrap()));
+        let missing =
+            compute_ca_fingerprint(Some(&format!("{}-gone", dir.path().to_str().unwrap())));
+        assert_ne!(present, missing);
+        assert_ne!(missing, "");
+    }
+
+    #[test]
+    fn non_certificate_files_in_the_directory_are_ignored() {
+        let dir = TempDir::new("noise");
+        dir.write("corp.pem", "CERT");
+        let before = compute_ca_fingerprint(Some(dir.path().to_str().unwrap()));
+        dir.write("README.md", "hello");
+        dir.write("openssl.cnf", "[req]");
+        assert_eq!(
+            compute_ca_fingerprint(Some(dir.path().to_str().unwrap())),
+            before
+        );
+    }
+
+    // ── resolve ────────────────────────────────────────────────────────────
+
+    #[test]
+    fn no_path_resolves_to_nothing() {
+        assert_eq!(resolve(None).unwrap(), None);
+        assert_eq!(resolve(Some("  ")).unwrap(), None);
+    }
+
+    #[test]
+    fn a_missing_path_is_an_actionable_error() {
+        let err = resolve(Some("/definitely/not/here/corp.pem")).unwrap_err();
+        assert!(err.contains("/definitely/not/here/corp.pem"), "{}", err);
+        assert!(err.contains("Settings"), "{}", err);
+    }
+
+    #[test]
+    fn an_empty_directory_is_an_actionable_error() {
+        let dir = TempDir::new("empty");
+        let err = resolve(Some(dir.path().to_str().unwrap())).unwrap_err();
+        assert!(err.contains("no certificate files"), "{}", err);
+        assert!(err.contains(".pem"), "{}", err);
+    }
+
+    #[test]
+    fn a_directory_mounts_at_the_shared_mount_point() {
+        let dir = TempDir::new("dir");
+        dir.write("corp.pem", "CERT");
+        let resolved = resolve(Some(dir.path().to_str().unwrap())).unwrap().unwrap();
+        assert!(resolved.is_dir);
+        assert_eq!(resolved.mount_target, CA_MOUNT_DIR);
+        assert_eq!(resolved.cert_files.len(), 1);
+    }
+
+    #[test]
+    fn a_single_file_mounts_under_the_mount_point_with_a_crt_name() {
+        // Mounting a file *at* /tmp/.host-ca would leave the entrypoint with no
+        // name to work from, and would make the mount point a file rather than
+        // the directory the entrypoint expects.
+        let dir = TempDir::new("file");
+        let file = dir.write("corp root.pem", "CERT");
+        let resolved = resolve(Some(file.to_str().unwrap())).unwrap().unwrap();
+        assert!(!resolved.is_dir);
+        assert_eq!(
+            resolved.mount_target,
+            format!("{}/corp_root.crt", CA_MOUNT_DIR)
+        );
+    }
+
+    #[test]
+    fn a_file_is_accepted_whatever_its_extension() {
+        // The user pointed at it explicitly; don't second-guess.
+        let dir = TempDir::new("odd-ext");
+        let file = dir.write("corp.txt", "CERT");
+        let resolved = resolve(Some(file.to_str().unwrap())).unwrap().unwrap();
+        assert_eq!(resolved.cert_files, vec![file]);
+    }
+
+    // ── env vars ───────────────────────────────────────────────────────────
+
+    #[test]
+    fn configured_ca_points_every_consumer_at_the_bundle() {
+        let dir = TempDir::new("env");
+        dir.write("corp.pem", "CERT");
+        let resolved = resolve(Some(dir.path().to_str().unwrap())).unwrap();
+        let vars = ca_env_vars(resolved.as_ref());
+        assert_eq!(
+            vars,
+            vec![
+                (NODE_EXTRA_CA_CERTS, CA_BUNDLE_PATH.to_string()),
+                (REQUESTS_CA_BUNDLE, CA_BUNDLE_PATH.to_string()),
+                (SSL_CERT_FILE, CA_BUNDLE_PATH.to_string()),
+            ]
+        );
+    }
+
+    #[test]
+    fn no_ca_clears_every_var_rather_than_omitting_it() {
+        // Omitting them would let a value baked into the project's snapshot
+        // image survive the setting being turned off.
+        let vars = ca_env_vars(None);
+        assert_eq!(vars.len(), CA_ENV_KEYS.len());
+        assert!(vars.iter().all(|(_, v)| v.is_empty()));
+    }
+}

app/src-tauri/src/docker/exec.rs

@@ -1,13 +1,94 @@
-use bollard::container::UploadToContainerOptions;
+use bollard::container::{LogOutput, UploadToContainerOptions};
 use bollard::exec::{CreateExecOptions, ResizeExecOptions, StartExecResults};
-use futures_util::StreamExt;
+use futures_util::{Stream, StreamExt};
 use std::collections::HashMap;
+use std::pin::Pin;
 use std::sync::Arc;
-use tokio::io::AsyncWriteExt;
+use tokio::io::{AsyncWrite, AsyncWriteExt};
 use tokio::sync::{mpsc, Mutex};
 
 use super::client::get_docker;
 
+/// A `docker exec` that has been created and started with stdin/stdout/stderr
+/// attached — the raw duplex halves, before any policy about what to do with
+/// them.
+///
+/// This is the single place in the codebase that knows how to open an attached
+/// exec. Both consumers are built on it:
+///   * [`ExecSessionManager`] — interactive terminals and the audio bridge,
+///     which pump bytes through mpsc channels and a callback.
+///   * `auth_bridge` — per-connection `socat` tunnels, which pump bytes
+///     straight between a host TCP socket and these halves.
+///
+/// With `tty = false` the output stream is demultiplexed by Docker, so the
+/// consumer can tell [`LogOutput::StdOut`] from [`LogOutput::StdErr`]. That
+/// distinction matters for the auth bridge: `socat`'s diagnostics must not be
+/// spliced into the proxied byte stream.
+pub struct AttachedExec {
+    pub exec_id: String,
+    pub output: Pin<Box<dyn Stream<Item = Result<LogOutput, bollard::errors::Error>> + Send>>,
+    pub input: Pin<Box<dyn AsyncWrite + Send>>,
+}
+
+/// Create and start an exec with stdin + stdout + stderr attached, returning the
+/// raw duplex halves. Runs as `claude` in `/workspace`, like every other exec
+/// this app opens.
+pub async fn create_attached_exec(
+    container_id: &str,
+    cmd: Vec<String>,
+    tty: bool,
+) -> Result<AttachedExec, String> {
+    create_attached_exec_as(container_id, cmd, tty, "claude", "/workspace").await
+}
+
+/// [`create_attached_exec`] with the user and working directory spelled out.
+///
+/// Only base-image migration needs this: replaying `apt` and unpacking a
+/// payload tar at `/` have to run as **root**, and every other caller wants the
+/// `claude` / `/workspace` defaults that [`create_attached_exec`] supplies. It
+/// stays the single place an attached exec is opened.
+pub async fn create_attached_exec_as(
+    container_id: &str,
+    cmd: Vec<String>,
+    tty: bool,
+    user: &str,
+    working_dir: &str,
+) -> Result<AttachedExec, String> {
+    let docker = get_docker()?;
+
+    let exec = docker
+        .create_exec(
+            container_id,
+            CreateExecOptions {
+                attach_stdin: Some(true),
+                attach_stdout: Some(true),
+                attach_stderr: Some(true),
+                tty: Some(tty),
+                cmd: Some(cmd),
+                user: Some(user.to_string()),
+                working_dir: Some(working_dir.to_string()),
+                ..Default::default()
+            },
+        )
+        .await
+        .map_err(|e| format!("Failed to create exec: {}", e))?;
+
+    let exec_id = exec.id.clone();
+
+    match docker
+        .start_exec(&exec_id, None)
+        .await
+        .map_err(|e| format!("Failed to start exec: {}", e))?
+    {
+        StartExecResults::Attached { output, input } => Ok(AttachedExec {
+            exec_id,
+            output,
+            input,
+        }),
+        StartExecResults::Detached => Err("Exec started in detached mode".to_string()),
+    }
+}
+
 pub struct ExecSession {
     pub exec_id: String,
     pub container_id: String,
@@ -80,82 +161,55 @@ impl ExecSessionManager {
     where
         F: Fn(Vec<u8>) + Send + 'static,
     {
-        let docker = get_docker()?;
-
-        let exec = docker
-            .create_exec(
-                container_id,
-                CreateExecOptions {
-                    attach_stdin: Some(true),
-                    attach_stdout: Some(true),
-                    attach_stderr: Some(true),
-                    tty: Some(tty),
-                    cmd: Some(cmd),
-                    user: Some("claude".to_string()),
-                    working_dir: Some("/workspace".to_string()),
-                    ..Default::default()
-                },
-            )
-            .await
-            .map_err(|e| format!("Failed to create exec: {}", e))?;
-
-        let exec_id = exec.id.clone();
-
-        let result = docker
-            .start_exec(&exec_id, None)
-            .await
-            .map_err(|e| format!("Failed to start exec: {}", e))?;
+        let AttachedExec {
+            exec_id,
+            mut output,
+            mut input,
+        } = create_attached_exec(container_id, cmd, tty).await?;
 
         let (input_tx, mut input_rx) = mpsc::unbounded_channel::<Vec<u8>>();
         let (shutdown_tx, mut shutdown_rx) = mpsc::channel::<()>(1);
 
-        match result {
-            StartExecResults::Attached { mut output, mut input } => {
-                // Output reader task
-                let session_id_clone = session_id.to_string();
-                let shutdown_tx_clone = shutdown_tx.clone();
-                tokio::spawn(async move {
-                    loop {
-                        tokio::select! {
-                            msg = output.next() => {
-                                match msg {
-                                    Some(Ok(output)) => {
-                                        on_output(output.into_bytes().to_vec());
-                                    }
-                                    Some(Err(e)) => {
-                                        log::error!("Exec output error for {}: {}", session_id_clone, e);
-                                        break;
-                                    }
-                                    None => {
-                                        log::info!("Exec output stream ended for {}", session_id_clone);
-                                        break;
-                                    }
-                                }
+        // Output reader task
+        let session_id_clone = session_id.to_string();
+        let shutdown_tx_clone = shutdown_tx.clone();
+        tokio::spawn(async move {
+            loop {
+                tokio::select! {
+                    msg = output.next() => {
+                        match msg {
+                            Some(Ok(output)) => {
+                                on_output(output.into_bytes().to_vec());
                             }
-                            _ = shutdown_rx.recv() => {
-                                log::info!("Exec session {} shutting down", session_id_clone);
+                            Some(Err(e)) => {
+                                log::error!("Exec output error for {}: {}", session_id_clone, e);
+                                break;
+                            }
+                            None => {
+                                log::info!("Exec output stream ended for {}", session_id_clone);
                                 break;
                             }
                         }
                     }
-                    on_exit();
-                    let _ = shutdown_tx_clone;
-                });
-
-                // Input writer task
-                tokio::spawn(async move {
-                    while let Some(data) = input_rx.recv().await {
-                        if let Err(e) = input.write_all(&data).await {
-                            log::error!("Failed to write to exec stdin: {}", e);
-                            break;
-                        }
+                    _ = shutdown_rx.recv() => {
+                        log::info!("Exec session {} shutting down", session_id_clone);
+                        break;
                     }
-                });
+                }
             }
-            StartExecResults::Detached => {
-                return Err("Exec started in detached mode".to_string());
+            on_exit();
+            let _ = shutdown_tx_clone;
+        });
+
+        // Input writer task
+        tokio::spawn(async move {
+            while let Some(data) = input_rx.recv().await {
+                if let Err(e) = input.write_all(&data).await {
+                    log::error!("Failed to write to exec stdin: {}", e);
+                    break;
+                }
             }
-        }
+        });
 
         let session = ExecSession {
             exec_id,
@@ -247,21 +301,10 @@ impl ExecSessionManager {
     ) -> Result<String, String> {
         let docker = get_docker()?;
 
-        // Build a tar archive in memory containing the file
-        let mut tar_buf = Vec::new();
-        {
-            let mut builder = tar::Builder::new(&mut tar_buf);
-            let mut header = tar::Header::new_gnu();
-            header.set_size(data.len() as u64);
-            header.set_mode(0o644);
-            header.set_cksum();
-            builder
-                .append_data(&mut header, file_name, data)
-                .map_err(|e| format!("Failed to create tar entry: {}", e))?;
-            builder
-                .finish()
-                .map_err(|e| format!("Failed to finalize tar: {}", e))?;
-        }
+        // Owned by the container user, stamped now: a default tar header would
+        // land it as root:root/1970 and Claude Code could not rewrite it.
+        let (uid, gid) = container_user_ids(container_id).await;
+        let tar_buf = build_single_file_tar(file_name, data, 0o644, uid, gid, now_epoch_secs())?;
 
         docker
             .upload_to_container(
@@ -279,8 +322,401 @@ impl ExecSessionManager {
     }
 }
 
+/// Ceiling on one host file packed into a container upload.
+///
+/// The file goes through host RAM twice — once as bytes, once inside the tar —
+/// so this is a memory bound, and it is checked against the *descriptor* that
+/// was opened rather than a `metadata` call that described whatever the path
+/// meant a moment earlier.
+pub const MAX_DROP_BYTES: u64 = 256 * 1024 * 1024;
+
+/// Upload a host file into `dest_dir` under `dest_name`. The file is
+/// read and packed into the tar inside a blocking task, so the synchronous IO
+/// runs off the async worker. The tar's declared entry size is taken from the
+/// bytes actually read (not a separate `stat`), so a file changing size between
+/// a size check and the read can't desync the header and corrupt the archive.
+/// Returns the in-container path (`<dest_dir>/<dest_name>`).
+///
+/// `dest_dir` must already exist and must already have been checked by the
+/// caller — Docker's archive extractor writes wherever it is pointed. The two
+/// callers both do that first, by different routes because they are answering
+/// different questions: the terminal drop stages into a fixed `/tmp` path it
+/// creates itself, and the Files pane passes the directory the user is looking
+/// at, which `file_commands::resolve_container_dir` has already confirmed
+/// resolves inside `CONTAINER_WRITE_ROOTS`.
+pub async fn upload_host_file_to_container(
+    container_id: &str,
+    host_path: &str,
+    dest_dir: &str,
+    dest_name: &str,
+) -> Result<String, String> {
+    let ids = container_user_ids(container_id).await;
+    upload_host_file_with_ids(container_id, host_path, dest_dir, dest_name, ids).await
+}
+
+/// [`upload_host_file_to_container`] for a caller that already knows the
+/// container user's ids.
+///
+/// `container_user_ids` is a `docker exec`, and the Files pane's upload is a
+/// *selection* — one dialog can hand back twenty files. Resolving the ids per
+/// file made twenty extra round trips to answer the same `id -u` twenty times,
+/// which is seconds of latency for a fact that cannot change inside one
+/// container's lifetime. So the loop resolves once and passes the answer in.
+/// The wrapper above keeps the single-file callers unchanged.
+pub async fn upload_host_file_with_ids(
+    container_id: &str,
+    host_path: &str,
+    dest_dir: &str,
+    dest_name: &str,
+    (uid, gid): (u64, u64),
+) -> Result<String, String> {
+    let host_path = host_path.to_string();
+    let dest_name = dest_name.to_string();
+    let dest_for_blk = dest_name.clone();
+    let mtime = now_epoch_secs();
+
+    let tar_buf = tokio::task::spawn_blocking(move || -> Result<Vec<u8>, String> {
+        // The caller resolved this path (`resolve_host_read_path`); opening it
+        // is a second trip through the same directories, so the descriptor is
+        // checked against the path that was validated before its bytes are
+        // packed into anything. Two paths reach here: the terminal's drop
+        // target, and the Files pane's upload via `upload_host_file_with_ids`.
+        // Between them they are how host bytes enter a container.
+        let file = std::fs::File::open(&host_path)
+            .map_err(|e| format!("Failed to read {}: {}", host_path, e))?;
+        crate::commands::file_commands::verify_opened_path(
+            &file,
+            std::path::Path::new(&host_path),
+        )?;
+        let mut data = Vec::new();
+        std::io::Read::read_to_end(
+            &mut std::io::Read::take(file, MAX_DROP_BYTES.saturating_add(1)),
+            &mut data,
+        )
+        .map_err(|e| format!("Failed to read {}: {}", host_path, e))?;
+        if data.len() as u64 > MAX_DROP_BYTES {
+            return Err(format!(
+                "File too large to upload (limit {} MB)",
+                MAX_DROP_BYTES / (1024 * 1024)
+            ));
+        }
+        build_single_file_tar(&dest_for_blk, &data[..], 0o644, uid, gid, mtime)
+    })
+    .await
+    .map_err(|e| format!("Upload task panicked: {}", e))??;
+
+    let docker = get_docker()?;
+    docker
+        .upload_to_container(
+            container_id,
+            Some(UploadToContainerOptions {
+                path: dest_dir.to_string(),
+                ..Default::default()
+            }),
+            tar_buf.into(),
+        )
+        .await
+        .map_err(|e| format!("Failed to upload file to container: {}", e))?;
+
+    Ok(container_join(dest_dir, &dest_name))
+}
+
+/// Join a container directory to a name that may itself carry separators.
+///
+/// Only the *reported* path — the bytes have already landed by the time this is
+/// called — but that path is what the terminal echoes and what the Files pane
+/// puts in its toast, so `/tmp//x` reading back as a different file than `/tmp/x`
+/// is worth the four lines. `"/"` trims to `""` and yields `/x`.
+fn container_join(dir: &str, name: &str) -> String {
+    format!("{}/{}", dir.trim_end_matches('/'), name.trim_start_matches('/'))
+}
+
+/// Write `data` into the container at `<dest_dir>/<file_name>` with `mode`.
+///
+/// For small, generated files — migration uses it for the `tar -T` include
+/// list, which can be too long to pass as argv. Anything large should be
+/// streamed through an attached exec's stdin instead, since this buffers the
+/// whole payload in memory twice (once raw, once tarred).
+pub async fn upload_bytes_to_container(
+    container_id: &str,
+    dest_dir: &str,
+    file_name: &str,
+    data: &[u8],
+    mode: u32,
+) -> Result<String, String> {
+    let docker = get_docker()?;
+
+    // Root-owned on purpose: the only caller is migration, whose `tar -T` list
+    // is read back as root. The mtime still gets stamped so the file doesn't
+    // read as 1970.
+    let tar_buf = build_single_file_tar(file_name, data, mode, 0, 0, now_epoch_secs())?;
+
+    docker
+        .upload_to_container(
+            container_id,
+            Some(UploadToContainerOptions {
+                path: dest_dir.to_string(),
+                ..Default::default()
+            }),
+            tar_buf.into(),
+        )
+        .await
+        .map_err(|e| format!("Failed to upload file to container: {}", e))?;
+
+    Ok(format!("{}/{}", dest_dir.trim_end_matches('/'), file_name))
+}
+
+/// Build an in-memory tar archive holding a single regular file.
+///
+/// The uid/gid/mtime arguments exist because `tar::Header::new_gnu()` zeroes
+/// them and Docker's archive extractor honours the header verbatim: a header
+/// left at the defaults lands the file inside the container as `root:root`
+/// with a 1970-01-01 mtime — not writable by `claude`, and confusing in any
+/// listing. Callers that upload on a user's behalf should pass the container
+/// user's ids from [`container_user_ids`].
+pub fn build_single_file_tar(
+    file_name: &str,
+    data: &[u8],
+    mode: u32,
+    uid: u64,
+    gid: u64,
+    mtime: u64,
+) -> Result<Vec<u8>, String> {
+    let mut tar_buf = Vec::with_capacity(data.len() + 1024);
+    {
+        let mut builder = tar::Builder::new(&mut tar_buf);
+        let mut header = tar::Header::new_gnu();
+        // Size comes from the bytes in hand, so header and payload can't disagree.
+        header.set_size(data.len() as u64);
+        header.set_mode(mode);
+        header.set_uid(uid);
+        header.set_gid(gid);
+        header.set_mtime(mtime);
+        header.set_cksum();
+        builder
+            .append_data(&mut header, file_name, data)
+            .map_err(|e| format!("Failed to create tar entry: {}", e))?;
+        builder
+            .finish()
+            .map_err(|e| format!("Failed to finalize tar: {}", e))?;
+    }
+    Ok(tar_buf)
+}
+
+/// Seconds since the Unix epoch, for a tar header mtime.
+pub fn now_epoch_secs() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_secs())
+        .unwrap_or(0)
+}
+
+/// The numeric uid/gid of the container's `claude` user.
+///
+/// It is not a constant: `entrypoint.sh` remaps `claude` to the *host* user's
+/// ids on Unix so bind-mounted project files stay writable, and deliberately
+/// does not on Windows. So the only reliable answer comes from asking the
+/// container. Falls back to 1000:1000 (the image's build-time ids) if the exec
+/// fails, which is strictly better than the 0:0 a default tar header carries.
+pub async fn container_user_ids(container_id: &str) -> (u64, u64) {
+    let out = exec_oneshot_limited(
+        container_id,
+        vec!["sh".to_string(), "-c".to_string(), "id -u; id -g".to_string()],
+        256,
+    )
+    .await
+    .unwrap_or_default();
+
+    let mut ids = out.lines().filter_map(|l| l.trim().parse::<u64>().ok());
+    match (ids.next(), ids.next()) {
+        (Some(uid), Some(gid)) => (uid, gid),
+        _ => (1000, 1000),
+    }
+}
+
+/// Ceiling on how much container output a one-shot exec will buffer into the
+/// host process.
+///
+/// Every `exec_oneshot*` call reads the whole stream into a `String` before any
+/// caller sees a byte, and what it is reading is *container-controlled* — the
+/// scheduler notifications reader `cat`s up to 50 files with no size cap, and
+/// the auth bridge reads `/proc/net/tcp` every two seconds. Neither has an
+/// upstream bound, so this is where the bound goes. Generous enough that no
+/// legitimate reader (the largest is a package manifest of a full image) comes
+/// close.
+pub const MAX_ONESHOT_OUTPUT: usize = 8 * 1024 * 1024;
+
+/// The auth bridge's per-tick budget. It reads two procfs files whose rows are
+/// ~150 bytes; a real container has tens of listeners, and the parser only ever
+/// yields at most one entry per port number. 1 MiB is thousands of rows — far
+/// past anything genuine, far short of a problem.
+pub const PROC_NET_OUTPUT_LIMIT: usize = 1024 * 1024;
+
+/// Marker on the "that command printed more than this will buffer" refusal.
+///
+/// The byte count on its own is a fact about the transport, not about what the
+/// user did — "Command output exceeded 8388608 bytes" is not a sentence anybody
+/// can act on. A caller that knows what it was reading can recognise this and
+/// say the useful thing instead; see `list_container_files`, where the real
+/// cause is a directory with more entries than the panel can render.
+pub const OUTPUT_LIMIT_MARKER: &str = "OUTPUT_LIMIT";
+
+/// Append to `buf` while it stays inside `limit`, returning the range the chunk
+/// now occupies. `None` once the limit is exceeded, at which point the caller
+/// must stop reading — and nothing is appended, so a caller that ignored the
+/// answer cannot parse a half-read document.
+///
+/// Bytes rather than `str` on purpose: Docker frames a stream wherever it
+/// likes, so a chunk boundary can fall inside a UTF-8 sequence. Decoding each
+/// chunk on its own turned that into two replacement characters in the middle
+/// of a filename; the decode happens once, at the end, over the whole buffer.
+fn push_capped(buf: &mut Vec<u8>, chunk: &[u8], limit: usize) -> Option<(usize, usize)> {
+    if buf.len() + chunk.len() > limit {
+        return None;
+    }
+    let start = buf.len();
+    buf.extend_from_slice(chunk);
+    Some((start, buf.len()))
+}
+
 /// Run a one-shot (non-interactive) exec command in a container and collect stdout.
 pub async fn exec_oneshot(container_id: &str, cmd: Vec<String>) -> Result<String, String> {
+    exec_oneshot_env(container_id, cmd, Vec::new()).await
+}
+
+/// [`exec_oneshot`] with a caller-chosen output ceiling, for readers whose
+/// input is fully container-controlled and whose legitimate output is small.
+pub async fn exec_oneshot_limited(
+    container_id: &str,
+    cmd: Vec<String>,
+    limit: usize,
+) -> Result<String, String> {
+    exec_oneshot_inner(container_id, "claude", cmd, Vec::new(), limit)
+        .await
+        .map(|(output, _)| output)
+}
+
+/// Like `exec_oneshot`, but passes additional environment variables to the exec
+/// process. Secrets passed this way live only in `/proc/<pid>/environ` (readable
+/// by the same user / root) rather than in the process argv, so they are not
+/// exposed via `ps`.
+///
+/// NOTE: the command's exit code is NOT checked — callers that need to know
+/// whether the command succeeded should use `exec_oneshot_env_status`.
+pub async fn exec_oneshot_env(
+    container_id: &str,
+    cmd: Vec<String>,
+    env: Vec<String>,
+) -> Result<String, String> {
+    exec_oneshot_env_status(container_id, cmd, env)
+        .await
+        .map(|(output, _exit_code)| output)
+}
+
+/// Like `exec_oneshot_env`, but also returns the command's exit code (0 on
+/// success). The returned string contains both stdout and stderr, interleaved
+/// in arrival order, which is useful for surfacing failure detail.
+pub async fn exec_oneshot_env_status(
+    container_id: &str,
+    cmd: Vec<String>,
+    env: Vec<String>,
+) -> Result<(String, i64), String> {
+    exec_oneshot_as(container_id, "claude", cmd, env).await
+}
+
+/// [`exec_oneshot_env_status`] with the user spelled out.
+///
+/// Base-image migration is the only caller that needs anything but `claude`:
+/// `apt-get`, `npm -g` and the payload unpack all run as **root**. Note that
+/// the container does grant `claude` passwordless sudo, but going through
+/// `sudo` would put the whole command in `ps` output and add a second failure
+/// mode to interpret, so the exec is simply created as root.
+pub async fn exec_oneshot_as(
+    container_id: &str,
+    user: &str,
+    cmd: Vec<String>,
+    env: Vec<String>,
+) -> Result<(String, i64), String> {
+    exec_oneshot_inner(container_id, user, cmd, env, MAX_ONESHOT_OUTPUT).await
+}
+
+/// What a one-shot exec printed, with the two streams still tellable apart.
+///
+/// `combined` is stdout and stderr interleaved in arrival order — the shape
+/// every existing caller reads, and the right one for surfacing "why did that
+/// fail". `stdout_ranges` indexes the parts of it that came from stdout, so a
+/// caller that is *parsing* output can have just that without the buffer being
+/// held twice.
+struct OneshotOutput {
+    combined: Vec<u8>,
+    stdout_ranges: Vec<(usize, usize)>,
+    exit_code: i64,
+}
+
+impl OneshotOutput {
+    /// Everything the command printed, in the order it printed it.
+    fn text(&self) -> String {
+        String::from_utf8_lossy(&self.combined).into_owned()
+    }
+
+    /// stdout alone — for callers that parse it, where a diagnostic spliced in
+    /// mid-record is a parse error at best.
+    fn stdout(&self) -> String {
+        let mut out = Vec::with_capacity(self.combined.len());
+        for (start, end) in &self.stdout_ranges {
+            out.extend_from_slice(&self.combined[*start..*end]);
+        }
+        String::from_utf8_lossy(&out).into_owned()
+    }
+
+    /// stderr alone — the complement of [`Self::stdout`], i.e. the diagnostics.
+    fn stderr(&self) -> String {
+        let mut out = Vec::with_capacity(self.combined.len());
+        let mut cursor = 0usize;
+        for (start, end) in &self.stdout_ranges {
+            out.extend_from_slice(&self.combined[cursor..*start]);
+            cursor = *end;
+        }
+        out.extend_from_slice(&self.combined[cursor..]);
+        String::from_utf8_lossy(&out).into_owned()
+    }
+}
+
+/// [`exec_oneshot_as`] with the two streams kept apart, for callers that parse
+/// stdout.
+///
+/// `find`'s own diagnostics ("Permission denied") used to arrive inside the
+/// records its `-printf` was emitting. GNU `find` escapes tabs and newlines in
+/// those messages, so the listing parser held — but "the parser holds" is not
+/// the same as "the input is trustworthy", and the fix costs one enum match.
+pub async fn exec_oneshot_streams_as(
+    container_id: &str,
+    user: &str,
+    cmd: Vec<String>,
+    env: Vec<String>,
+) -> Result<(String, String, i64), String> {
+    let out = exec_oneshot_raw(container_id, user, cmd, env, MAX_ONESHOT_OUTPUT).await?;
+    Ok((out.stdout(), out.stderr(), out.exit_code))
+}
+
+async fn exec_oneshot_inner(
+    container_id: &str,
+    user: &str,
+    cmd: Vec<String>,
+    env: Vec<String>,
+    limit: usize,
+) -> Result<(String, i64), String> {
+    let out = exec_oneshot_raw(container_id, user, cmd, env, limit).await?;
+    Ok((out.text(), out.exit_code))
+}
+
+async fn exec_oneshot_raw(
+    container_id: &str,
+    user: &str,
+    cmd: Vec<String>,
+    env: Vec<String>,
+    limit: usize,
+) -> Result<OneshotOutput, String> {
     let docker = get_docker()?;
 
     let exec = docker
@@ -290,7 +726,8 @@ pub async fn exec_oneshot(container_id: &str, cmd: Vec<String>) -> Result<String
                 attach_stdout: Some(true),
                 attach_stderr: Some(true),
                 cmd: Some(cmd),
-                user: Some("claude".to_string()),
+                env: if env.is_empty() { None } else { Some(env) },
+                user: Some(user.to_string()),
                 ..Default::default()
             },
         )
@@ -302,17 +739,226 @@ pub async fn exec_oneshot(container_id: &str, cmd: Vec<String>) -> Result<String
         .await
         .map_err(|e| format!("Failed to start exec: {}", e))?;
 
+    let mut combined: Vec<u8> = Vec::new();
+    let mut stdout_ranges: Vec<(usize, usize)> = Vec::new();
     match result {
         StartExecResults::Attached { mut output, .. } => {
-            let mut stdout = String::new();
             while let Some(msg) = output.next().await {
                 match msg {
-                    Ok(data) => stdout.push_str(&String::from_utf8_lossy(&data.into_bytes())),
+                    Ok(data) => {
+                        let from_stdout = matches!(data, LogOutput::StdOut { .. });
+                        let bytes = data.into_bytes();
+                        match push_capped(&mut combined, &bytes, limit) {
+                            Some(range) => {
+                                if from_stdout {
+                                    stdout_ranges.push(range);
+                                }
+                            }
+                            // Stop reading rather than truncate silently: every
+                            // caller parses this output, and a half-read
+                            // manifest or JSON array is worse than an error.
+                            // Dropping `output` kills the exec's stream.
+                            None => {
+                                return Err(format!(
+                                    "{}: Command output exceeded {} bytes and was abandoned",
+                                    OUTPUT_LIMIT_MARKER, limit
+                                ))
+                            }
+                        }
+                    }
                     Err(e) => return Err(format!("Exec output error: {}", e)),
                 }
             }
-            Ok(stdout)
         }
-        StartExecResults::Detached => Err("Exec started in detached mode".to_string()),
+        StartExecResults::Detached => return Err("Exec started in detached mode".to_string()),
+    }
+
+    // The output stream draining doesn't strictly guarantee inspect_exec has the
+    // final exit_code populated yet, so poll until the exec reports finished.
+    let exit_code = require_exit_code(wait_for_exec_exit(&exec.id).await)?;
+
+    Ok(OneshotOutput {
+        combined,
+        stdout_ranges,
+        exit_code,
+    })
+}
+
+/// Turn "the exit code could not be determined" into an error rather than a 0.
+///
+/// `unwrap_or(0)` is how a rename that never happened reported success: callers
+/// branch on `code != 0`, so an unreadable status silently became "it worked",
+/// the UI closed its rename box and the file had not moved. An exec whose
+/// outcome cannot be established has not been established to have succeeded —
+/// fail closed and let the caller surface it.
+///
+/// The `test -e` probe in `rename_container_path` also fails closed under this:
+/// it propagates the error instead of reading an undeterminable status as
+/// "the destination does not exist".
+fn require_exit_code(code: Option<i64>) -> Result<i64, String> {
+    code.ok_or_else(|| {
+        "Could not determine whether the command finished (Docker did not report an exit status)"
+            .to_string()
+    })
+}
+
+/// Poll `inspect_exec` until the exec reports finished and return its exit code.
+/// Returns `None` if the code can't be determined (inspect error, or the exec
+/// doesn't report finished within ~5s — which shouldn't happen once its output
+/// stream has drained).
+///
+/// The window is generous because `None` is no longer a shrug: since
+/// [`require_exit_code`], it fails the whole call. Waiting a few seconds longer
+/// for a busy daemon to settle costs nothing in the normal case — the loop exits
+/// on the first poll that reports finished — and it is the difference between a
+/// spurious "the rename failed" and a real one.
+pub async fn wait_for_exec_exit(exec_id: &str) -> Option<i64> {
+    let docker = get_docker().ok()?;
+    for _ in 0..200 {
+        match docker.inspect_exec(exec_id).await {
+            Ok(info) => {
+                if info.running != Some(true) {
+                    // Finished. `exit_code` rather than `unwrap_or(0)`: an exec
+                    // that has stopped without a reported code is a status
+                    // nobody can vouch for, and flattening it to *success* is
+                    // the wrong default when a caller is deciding whether to
+                    // rename a downloaded file over the user's own.
+                    // `download_container_file` treats `None` as a failure
+                    // precisely because it cannot tell that silence from a
+                    // clean exit; an `unwrap_or` here made that check
+                    // unreachable. Callers that only care about "did it fail
+                    // loudly" use `is_some_and`, which reads `None` as before.
+                    return info.exit_code;
+                }
+            }
+            Err(_) => return None,
+        }
+        tokio::time::sleep(std::time::Duration::from_millis(25)).await;
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The frames a demultiplexed exec hands back, as `(is_stdout, bytes)`.
+    fn collect(frames: &[(bool, &[u8])]) -> OneshotOutput {
+        let mut combined = Vec::new();
+        let mut stdout_ranges = Vec::new();
+        for (from_stdout, bytes) in frames {
+            let range = push_capped(&mut combined, bytes, usize::MAX).unwrap();
+            if *from_stdout {
+                stdout_ranges.push(range);
+            }
+        }
+        OneshotOutput {
+            combined,
+            stdout_ranges,
+            exit_code: 0,
+        }
+    }
+
+    #[test]
+    fn output_under_the_limit_is_buffered_whole() {
+        let mut buf = Vec::new();
+        assert_eq!(push_capped(&mut buf, b"hello ", 16), Some((0, 6)));
+        assert_eq!(push_capped(&mut buf, b"world", 16), Some((6, 11)));
+        assert_eq!(buf, b"hello world");
+    }
+
+    #[test]
+    fn output_over_the_limit_is_refused_rather_than_truncated() {
+        // The abandoned chunk must not land in the buffer either: a caller that
+        // ignored the error would otherwise parse a half-read document.
+        let mut buf = Vec::new();
+        assert!(push_capped(&mut buf, b"0123456789", 12).is_some());
+        assert!(push_capped(&mut buf, b"0123456789", 12).is_none());
+        assert_eq!(buf, b"0123456789");
+    }
+
+    #[test]
+    fn a_single_oversized_chunk_is_refused() {
+        let mut buf = Vec::new();
+        assert!(push_capped(&mut buf, b"0123456789", 4).is_none());
+        assert!(buf.is_empty());
+    }
+
+    #[test]
+    fn a_character_split_across_two_frames_survives_the_decode() {
+        // Docker frames a stream wherever it likes, and a filename is where
+        // that shows: decoding each chunk on its own turned the two halves of
+        // `ü` into two replacement characters in the middle of a name.
+        let out = collect(&[(true, &[0xc3]), (true, &[0xbc, b'.', b't', b'x', b't'])]);
+        assert_eq!(out.stdout(), "ü.txt");
+        assert_eq!(out.text(), "ü.txt");
+    }
+
+    #[test]
+    fn a_diagnostic_never_lands_in_the_stream_a_caller_parses() {
+        // `find`'s "Permission denied" used to arrive inside the records its
+        // `-printf` was emitting. Arrival order is still available for the
+        // error message; the parser gets stdout alone.
+        let out = collect(&[
+            (true, b"first"),
+            (false, b"find: /x: Permission denied\n"),
+            (true, b"second"),
+        ]);
+        assert_eq!(out.stdout(), "firstsecond");
+        assert_eq!(out.stderr(), "find: /x: Permission denied\n");
+        assert_eq!(out.text(), "firstfind: /x: Permission denied\nsecond");
+    }
+
+    #[test]
+    fn an_output_limit_refusal_is_marked_so_a_caller_can_reword_it() {
+        // "Command output exceeded 8388608 bytes" is a fact about a buffer.
+        // The marker is what lets `list_container_files` say "too many entries"
+        // instead, which is the thing that actually happened.
+        assert!(!OUTPUT_LIMIT_MARKER.is_empty());
+        let refusal = format!(
+            "{}: Command output exceeded {} bytes and was abandoned",
+            OUTPUT_LIMIT_MARKER, MAX_ONESHOT_OUTPUT
+        );
+        assert!(refusal.starts_with(OUTPUT_LIMIT_MARKER));
+    }
+
+    #[test]
+    fn an_undeterminable_exit_status_is_an_error_not_a_zero() {
+        // The bug this guards: `unwrap_or(0)` made every caller that branches on
+        // `code != 0` — rename, mkdir — report success for an exec whose outcome
+        // nobody could read.
+        assert_eq!(require_exit_code(Some(0)).unwrap(), 0);
+        assert_eq!(require_exit_code(Some(1)).unwrap(), 1);
+        assert!(require_exit_code(None).is_err());
+    }
+
+    #[test]
+    fn the_bridge_budget_is_far_smaller_than_the_general_one() {
+        // The auth bridge re-reads container-controlled procfs every 2s, so it
+        // gets a tighter ceiling than one-shot readers that run on demand.
+        assert!(PROC_NET_OUTPUT_LIMIT < MAX_ONESHOT_OUTPUT);
+        // …but still comfortably above a genuine /proc/net/tcp{,6} pair.
+        assert!(PROC_NET_OUTPUT_LIMIT > 100 * 150);
+    }
+
+    /// The reported path, which is what the terminal echoes back to Claude and
+    /// what the Files pane puts in its log line. `/tmp//x` and `/tmp/x` are the
+    /// same file to the kernel and different strings to a person reading either
+    /// of those.
+    #[test]
+    fn container_join_produces_one_separator() {
+        assert_eq!(container_join("/tmp", "a.txt"), "/tmp/a.txt");
+        // The terminal's drop passes a nested name; it must not gain a second
+        // slash at the seam.
+        assert_eq!(
+            container_join("/tmp", "triple-c-drops/a.txt"),
+            "/tmp/triple-c-drops/a.txt"
+        );
+        // A directory the user navigated to can carry a trailing slash, and the
+        // container root is the case where trimming it must not eat the only
+        // separator there is.
+        assert_eq!(container_join("/workspace/", "a.txt"), "/workspace/a.txt");
+        assert_eq!(container_join("/", "a.txt"), "/a.txt");
+        assert_eq!(container_join("/", "/a.txt"), "/a.txt");
     }
 }

app/src-tauri/src/docker/gateway.rs

@@ -0,0 +1,949 @@
+//! Lifecycle for the **model gateway** container — a pinned LiteLLM proxy that
+//! Triple-C runs as a sibling of the project containers.
+//!
+//! Shape mirrors `docker::stt`: an image that is either pulled from a registry
+//! or built locally from an embedded Dockerfile, a fixed container name, a
+//! named volume, and `get_* / ensure_*_running / stop_* / pull_* / build_*`.
+//!
+//! Two things differ from STT, both deliberate:
+//!
+//! * **The published host address is *detected*, not fixed.** STT is consumed
+//!   by the Tauri host process, so loopback is always enough. The gateway is
+//!   consumed by *project containers*, and how a container reaches the host
+//!   depends on the engine — so the bind address does too. See
+//!   [`GatewayBinding`]. It is never `0.0.0.0`: the config behind this port
+//!   holds a billed provider key, and Docker's published-port rules land in the
+//!   `DOCKER` iptables chain *ahead* of a host firewall, so a wildcard bind is
+//!   genuinely LAN-reachable even with `ufw` enabled.
+//! * **The rendered config is uploaded into the container over the Docker
+//!   API** rather than passed as env. It holds the provider API key, and both
+//!   env vars and labels are readable by anything on the host via
+//!   `docker inspect`.
+
+use bollard::container::{
+    Config, CreateContainerOptions, ListContainersOptions, RemoveContainerOptions,
+    StartContainerOptions, StopContainerOptions, UploadToContainerOptions,
+};
+use bollard::image::BuildImageOptions;
+use bollard::models::{HostConfig, Mount, MountTypeEnum, PortBinding};
+use bollard::network::InspectNetworkOptions;
+use bollard::Docker;
+use futures_util::StreamExt;
+use sha2::{Digest, Sha256};
+use std::collections::HashMap;
+use std::io::Write;
+use std::sync::OnceLock;
+use tokio::sync::{Mutex, OnceCell};
+
+use super::client::get_docker;
+use crate::models::gateway_settings::{GatewaySettings, GatewayStatus};
+use crate::storage::secure;
+
+const GATEWAY_CONTAINER_NAME: &str = "triple-c-gateway";
+const GATEWAY_CONFIG_VOLUME: &str = "triple-c-gateway-config";
+
+/// Upstream LiteLLM, pinned to an exact release.
+///
+/// LiteLLM 1.82.7 and 1.82.8 shipped credential-harvesting malware on PyPI, so
+/// nothing here may float a tag or resolve `litellm` at build time. v1.96.0 is
+/// also above the 1.84.0 floor set by the proxy auth-bypass CVEs — see the long
+/// comment in `gateway-container/Dockerfile`, and keep the two in lockstep.
+const GATEWAY_REGISTRY_IMAGE: &str = "ghcr.io/berriai/litellm:v1.96.0";
+const GATEWAY_LOCAL_IMAGE: &str = "triple-c-gateway:latest";
+
+const GATEWAY_DOCKERFILE: &str = include_str!("../../../../gateway-container/Dockerfile");
+const GATEWAY_DEFAULT_CONFIG: &str = include_str!("../../../../gateway-container/config.yaml");
+
+/// Where the generated config lands inside the container. Backed by
+/// [`GATEWAY_CONFIG_VOLUME`] so the file with the provider key lives in a
+/// Docker-managed volume rather than an image layer.
+const GATEWAY_CONFIG_DIR: &str = "/etc/litellm";
+const GATEWAY_CONFIG_PATH: &str = "/etc/litellm/config.yaml";
+
+/// Container-side port. Only the *host* port is user-configurable.
+const GATEWAY_INTERNAL_PORT: u16 = 4000;
+
+const CONFIG_FINGERPRINT_LABEL: &str = "triple-c.gateway.config-fingerprint";
+
+/// The default bridge gateway address on a stock native-Linux engine. Only a
+/// fallback: the real value is read from the `bridge` network's IPAM config.
+const DEFAULT_BRIDGE_GATEWAY: &str = "172.17.0.1";
+
+/// Where the gateway's published port is bound on the host, and the address a
+/// *project container* uses to reach it.
+///
+/// Project containers run on Docker's default bridge with no user-defined
+/// network and no `--add-host`, so the only address they share with the gateway
+/// is the host itself — but *which* host address works is engine-specific, and
+/// the whole point of this type is that the two answers are derived together so
+/// they cannot drift apart:
+///
+/// * **Docker Desktop** (macOS / Windows / WSL2) resolves `host.docker.internal`
+///   from inside containers automatically, and its port forwarder reaches the
+///   host's *loopback*. So: bind `127.0.0.1`, hand out `host.docker.internal`.
+/// * **Native Linux Docker** injects no `host.docker.internal`, and the address
+///   containers share with the host is the default bridge gateway (normally
+///   `172.17.0.1`). So: bind that address, and hand out the same literal.
+///
+/// Neither case binds `0.0.0.0`. The bridge-gateway bind is reachable from
+/// every container on the default bridge — which is the requirement — without
+/// publishing a key-bearing proxy to the LAN.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct GatewayBinding {
+    /// Host address the published port is bound to (`HostIp`).
+    pub host_ip: String,
+    /// Host address a project container should dial.
+    pub container_host: String,
+}
+
+impl GatewayBinding {
+    fn desktop() -> Self {
+        Self {
+            host_ip: "127.0.0.1".to_string(),
+            container_host: "host.docker.internal".to_string(),
+        }
+    }
+
+    fn bridge(gateway_ip: &str) -> Self {
+        Self {
+            host_ip: gateway_ip.to_string(),
+            container_host: gateway_ip.to_string(),
+        }
+    }
+
+    /// The value a project should use as its base URL (`ANTHROPIC_BASE_URL`).
+    pub fn base_url(&self, port: u16) -> String {
+        format!("http://{}:{}", self.container_host, port)
+    }
+
+    /// The address the *host* process (health checks) should dial.
+    fn host_url(&self, port: u16) -> String {
+        format!("http://{}:{}", self.host_ip, port)
+    }
+}
+
+/// Decide the binding from what the daemon reports. Pure, so the engine-shape
+/// matrix is testable without a daemon.
+fn binding_for(operating_system: &str, bridge_gateway: Option<&str>) -> GatewayBinding {
+    // Docker Desktop reports exactly "Docker Desktop" here on every platform it
+    // ships for; matched loosely so a future suffix doesn't silently flip us
+    // onto the bridge path.
+    if operating_system.to_ascii_lowercase().contains("docker desktop") {
+        return GatewayBinding::desktop();
+    }
+    GatewayBinding::bridge(
+        bridge_gateway
+            .map(str::trim)
+            .filter(|g| !g.is_empty())
+            .unwrap_or(DEFAULT_BRIDGE_GATEWAY),
+    )
+}
+
+/// Detection is one `info` + one `inspect_network` per process; the answer
+/// cannot change without the engine being replaced under us.
+static GATEWAY_BINDING: OnceCell<GatewayBinding> = OnceCell::const_new();
+
+/// The gateway's host binding, detected once and cached.
+///
+/// When Docker is unreachable the *loopback* answer is returned without being
+/// cached: it is the conservative one (nothing is published anywhere yet, and
+/// the only caller in that state is status reporting), and the next call
+/// re-detects once the daemon is up.
+pub async fn gateway_binding() -> GatewayBinding {
+    if let Some(binding) = GATEWAY_BINDING.get() {
+        return binding.clone();
+    }
+    match detect_binding().await {
+        Ok(binding) => {
+            let _ = GATEWAY_BINDING.set(binding.clone());
+            binding
+        }
+        Err(e) => {
+            log::debug!("Gateway bind detection deferred ({}), assuming loopback", e);
+            GatewayBinding::desktop()
+        }
+    }
+}
+
+async fn detect_binding() -> Result<GatewayBinding, String> {
+    let docker = get_docker()?;
+    let info = docker
+        .info()
+        .await
+        .map_err(|e| format!("Failed to query the Docker daemon: {}", e))?;
+    let operating_system = info.operating_system.unwrap_or_default();
+    let gateway_ip = bridge_gateway_ip(&docker).await;
+    let binding = binding_for(&operating_system, gateway_ip.as_deref());
+    log::info!(
+        "Model gateway will publish on {} (engine OS: {})",
+        binding.host_ip,
+        if operating_system.is_empty() {
+            "unknown"
+        } else {
+            &operating_system
+        }
+    );
+    Ok(binding)
+}
+
+/// The default bridge's gateway address, straight from its IPAM config, so a
+/// host whose bridge subnet was customised still gets a reachable bind.
+async fn bridge_gateway_ip(docker: &Docker) -> Option<String> {
+    let network = docker
+        .inspect_network("bridge", None::<InspectNetworkOptions<String>>)
+        .await
+        .ok()?;
+    network
+        .ipam?
+        .config?
+        .into_iter()
+        .find_map(|c| c.gateway.filter(|g| !g.trim().is_empty()))
+}
+
+fn sha256_hex(input: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(input.as_bytes());
+    format!("{:x}", hasher.finalize())
+}
+
+pub async fn get_gateway_status(settings: &GatewaySettings) -> Result<GatewayStatus, String> {
+    let image_exists = super::image::image_exists(GATEWAY_REGISTRY_IMAGE)
+        .await
+        .unwrap_or(false)
+        || super::image::image_exists(GATEWAY_LOCAL_IMAGE)
+            .await
+            .unwrap_or(false);
+
+    let (container_exists, running) = match find_gateway_container().await? {
+        Some((_, state, _)) => (true, state == "running"),
+        None => (false, false),
+    };
+
+    Ok(GatewayStatus {
+        container_exists,
+        running,
+        port: settings.port,
+        image_exists,
+        model_count: settings.valid_models().len(),
+        has_api_key: secure::has_gateway_api_key(),
+        base_url: gateway_binding().await.base_url(settings.port),
+    })
+}
+
+/// Whether a gateway container exists, and whether it is running. Used by the
+/// settings reconcile, which must not start anything the user never started.
+pub async fn gateway_container_presence() -> Result<(bool, bool), String> {
+    Ok(match find_gateway_container().await? {
+        Some((_, state, _)) => (true, state == "running"),
+        None => (false, false),
+    })
+}
+
+/// Whether a container summary's names contain *exactly* our container.
+///
+/// Docker's `name` filter is an unanchored regex, so listing with it also
+/// returns `triple-c-gateway-backup`, `my-triple-c-gateway`, and anything else
+/// containing the string. Taking `.first()` of that would let this module
+/// adopt — and then force-remove — a container it does not own.
+/// `container::find_existing_container` matches exactly for the same reason.
+fn is_gateway_container(names: Option<&Vec<String>>) -> bool {
+    let expected = format!("/{}", GATEWAY_CONTAINER_NAME);
+    names.is_some_and(|names| names.iter().any(|n| n == &expected))
+}
+
+/// `(id, state, config fingerprint label)` for the gateway container, if any.
+async fn find_gateway_container() -> Result<Option<(String, String, String)>, String> {
+    let docker = get_docker()?;
+
+    let filters: HashMap<String, Vec<String>> = HashMap::from([(
+        "name".to_string(),
+        vec![format!("/{}", GATEWAY_CONTAINER_NAME)],
+    )]);
+
+    let containers = docker
+        .list_containers(Some(ListContainersOptions {
+            all: true,
+            filters,
+            ..Default::default()
+        }))
+        .await
+        .map_err(|e| format!("Failed to list containers: {}", e))?;
+
+    // The filter is a prefilter only — the exact-name check is what decides.
+    for container in &containers {
+        if !is_gateway_container(container.names.as_ref()) {
+            continue;
+        }
+        let id = container.id.clone().unwrap_or_default();
+        let state = container.state.clone().unwrap_or_default();
+        let fingerprint = container
+            .labels
+            .as_ref()
+            .and_then(|l| l.get(CONFIG_FINGERPRINT_LABEL))
+            .cloned()
+            .unwrap_or_default();
+
+        return Ok(Some((id, state, fingerprint)));
+    }
+
+    Ok(None)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Config generation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Render a YAML double-quoted scalar.
+///
+/// Everything that reaches the config comes from user input (model names, base
+/// URLs, keys), so nothing may be interpolated raw — a stray `"` or newline
+/// would otherwise rewrite the document.
+fn yaml_str(value: &str) -> String {
+    let mut out = String::with_capacity(value.len() + 2);
+    out.push('"');
+    for c in value.chars() {
+        match c {
+            '"' => out.push_str("\\\""),
+            '\\' => out.push_str("\\\\"),
+            '\n' => out.push_str("\\n"),
+            '\r' => out.push_str("\\r"),
+            '\t' => out.push_str("\\t"),
+            c if (c as u32) < 0x20 => out.push_str(&format!("\\x{:02x}", c as u32)),
+            c => out.push(c),
+        }
+    }
+    out.push('"');
+    out
+}
+
+/// The parts of the config that are safe to hash into a Docker label — i.e.
+/// everything except the two secrets, whose changes are tracked by the
+/// keychain rotation id instead.
+fn config_shape(settings: &GatewaySettings, binding: &GatewayBinding) -> String {
+    let models: Vec<String> = settings
+        .valid_models()
+        .iter()
+        .map(|m| format!("{}={}", m.name.trim(), m.model_id.trim()))
+        .collect();
+    // `bind` is part of the shape so that moving between engines (or a bridge
+    // subnet change) recreates the container instead of leaving it published on
+    // an address the new environment doesn't use.
+    format!(
+        "provider={};api_base={};port={};bind={};models={}",
+        settings.provider.trim(),
+        settings.api_base.as_deref().unwrap_or("").trim(),
+        settings.port,
+        binding.host_ip,
+        models.join(",")
+    )
+}
+
+/// Render the LiteLLM config for the current settings.
+///
+/// `api_key` and `master_key` come from the keychain. The returned string
+/// contains both — it goes straight into the Docker upload and must never be
+/// logged or surfaced.
+fn render_config(settings: &GatewaySettings, api_key: &str, master_key: &str) -> String {
+    let provider = settings.provider.trim();
+    let api_base = settings
+        .api_base
+        .as_deref()
+        .map(str::trim)
+        .filter(|s| !s.is_empty());
+
+    let mut out = String::from(
+        "# Generated by Triple-C — do not edit by hand; it is overwritten on every\n\
+         # gateway (re)start from Settings → Model Gateway.\n\
+         model_list:\n",
+    );
+
+    for model in settings.valid_models() {
+        out.push_str(&format!("  - model_name: {}\n", yaml_str(model.name.trim())));
+        out.push_str("    litellm_params:\n");
+        out.push_str(&format!(
+            "      model: {}\n",
+            yaml_str(&format!("{}/{}", provider, model.model_id.trim()))
+        ));
+        out.push_str(&format!("      api_key: {}\n", yaml_str(api_key)));
+        if let Some(base) = api_base {
+            out.push_str(&format!("      api_base: {}\n", yaml_str(base)));
+        }
+    }
+
+    out.push_str("general_settings:\n");
+    out.push_str(&format!("  master_key: {}\n", yaml_str(master_key)));
+    out.push_str("litellm_settings:\n");
+    // Claude Code's Anthropic-format requests carry fields some providers
+    // reject outright; dropping the unsupported ones is what lets the
+    // translation survive across providers.
+    out.push_str("  drop_params: true\n");
+
+    out
+}
+
+/// Upload the rendered config into the container's config volume.
+///
+/// Runs against a *created but not yet started* container, which is when the
+/// volume already exists but LiteLLM has not read anything from it.
+async fn upload_config(container_id: &str, config: &str) -> Result<(), String> {
+    let docker = get_docker()?;
+
+    let mut buf = Vec::new();
+    {
+        let mut archive = tar::Builder::new(&mut buf);
+        let mut header = tar::Header::new_gnu();
+        header.set_size(config.len() as u64);
+        // World-readable: the upstream image may run LiteLLM as a non-root
+        // user, and a root-owned 0600 file would simply be unreadable. The
+        // secret is only exposed to the gateway container itself, which is
+        // the one process that needs it.
+        header.set_mode(0o644);
+        header.set_cksum();
+        archive
+            .append_data(&mut header, "config.yaml", config.as_bytes())
+            .map_err(|e| format!("Failed to build the gateway config archive: {}", e))?;
+        archive
+            .finish()
+            .map_err(|e| format!("Failed to build the gateway config archive: {}", e))?;
+    }
+    let _ = buf.flush();
+
+    docker
+        .upload_to_container(
+            container_id,
+            Some(UploadToContainerOptions {
+                path: GATEWAY_CONFIG_DIR,
+                ..Default::default()
+            }),
+            buf.into(),
+        )
+        .await
+        .map_err(|e| format!("Failed to upload the gateway config: {}", e))
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Lifecycle
+// ─────────────────────────────────────────────────────────────────────────────
+
+async fn create_gateway_container(
+    settings: &GatewaySettings,
+    binding: &GatewayBinding,
+    fingerprint: &str,
+) -> Result<String, String> {
+    let docker = get_docker()?;
+
+    // Local build first, then the pinned upstream image — same precedence as
+    // the STT container.
+    let image = if super::image::image_exists(GATEWAY_LOCAL_IMAGE)
+        .await
+        .unwrap_or(false)
+    {
+        GATEWAY_LOCAL_IMAGE.to_string()
+    } else if super::image::image_exists(GATEWAY_REGISTRY_IMAGE)
+        .await
+        .unwrap_or(false)
+    {
+        GATEWAY_REGISTRY_IMAGE.to_string()
+    } else {
+        return Err(
+            "Gateway image not found. Please pull or build the image first.".to_string(),
+        );
+    };
+
+    let mut port_bindings = HashMap::new();
+    port_bindings.insert(
+        format!("{}/tcp", GATEWAY_INTERNAL_PORT),
+        Some(vec![PortBinding {
+            // Never `0.0.0.0`: the narrowest host address project containers
+            // can still reach. See `GatewayBinding`.
+            host_ip: Some(binding.host_ip.clone()),
+            host_port: Some(settings.port.to_string()),
+        }]),
+    );
+
+    let mut exposed_ports: HashMap<String, HashMap<(), ()>> = HashMap::new();
+    exposed_ports.insert(format!("{}/tcp", GATEWAY_INTERNAL_PORT), HashMap::new());
+
+    let host_config = HostConfig {
+        port_bindings: Some(port_bindings),
+        mounts: Some(vec![Mount {
+            target: Some(GATEWAY_CONFIG_DIR.to_string()),
+            source: Some(GATEWAY_CONFIG_VOLUME.to_string()),
+            typ: Some(MountTypeEnum::VOLUME),
+            ..Default::default()
+        }]),
+        init: Some(true),
+        ..Default::default()
+    };
+
+    // Non-secret only. Labels are readable by anything on the host.
+    let mut labels = HashMap::new();
+    labels.insert(CONFIG_FINGERPRINT_LABEL.to_string(), fingerprint.to_string());
+    labels.insert(
+        "triple-c.gateway.port".to_string(),
+        settings.port.to_string(),
+    );
+    labels.insert("triple-c.gateway.bind".to_string(), binding.host_ip.clone());
+    labels.insert(
+        "triple-c.gateway.provider".to_string(),
+        settings.provider.trim().to_string(),
+    );
+
+    let config = Config {
+        image: Some(image),
+        // The upstream entrypoint (`docker/prod_entrypoint.sh`) execs
+        // `litellm "$@"`. Passed explicitly so the pulled upstream image and
+        // our locally built one behave identically.
+        cmd: Some(vec![
+            "--config".to_string(),
+            GATEWAY_CONFIG_PATH.to_string(),
+            "--host".to_string(),
+            "0.0.0.0".to_string(),
+            "--port".to_string(),
+            GATEWAY_INTERNAL_PORT.to_string(),
+        ]),
+        exposed_ports: Some(exposed_ports),
+        host_config: Some(host_config),
+        labels: Some(labels),
+        ..Default::default()
+    };
+
+    let options = CreateContainerOptions {
+        name: GATEWAY_CONTAINER_NAME,
+        ..Default::default()
+    };
+
+    let response = docker
+        .create_container(Some(options), config)
+        .await
+        .map_err(|e| format!("Failed to create gateway container: {}", e))?;
+
+    Ok(response.id)
+}
+
+/// Serialises every mutation of the single fixed-name gateway container.
+///
+/// `ensure_gateway_running` is check-then-act over one container name, so two
+/// concurrent callers — the setup auto-start and the user's Start button is the
+/// realistic pair — would both see `None` and both try to create it, and the
+/// loser would surface a raw Docker 409. Migration guards the same shape with
+/// `ActiveGuard`; here the right behaviour is to *serialise* rather than
+/// refuse, because the second caller then observes the first's container, finds
+/// a matching fingerprint, and returns its status — which is exactly what it
+/// asked for.
+fn gateway_lock() -> &'static Mutex<()> {
+    static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    LOCK.get_or_init(|| Mutex::new(()))
+}
+
+pub async fn ensure_gateway_running(settings: &GatewaySettings) -> Result<GatewayStatus, String> {
+    let _guard = gateway_lock().lock().await;
+    ensure_gateway_running_locked(settings).await
+}
+
+async fn ensure_gateway_running_locked(
+    settings: &GatewaySettings,
+) -> Result<GatewayStatus, String> {
+    let docker = get_docker()?;
+
+    if settings.valid_models().is_empty() {
+        return Err(
+            "The gateway has no models configured. Add at least one model in Settings."
+                .to_string(),
+        );
+    }
+
+    let api_key = secure::get_gateway_api_key()?
+        .filter(|k| !k.trim().is_empty())
+        .ok_or_else(|| {
+            "No provider API key stored for the gateway. Add one in Settings.".to_string()
+        })?;
+    let master_key = secure::get_or_create_gateway_master_key()?;
+
+    let binding = gateway_binding().await;
+
+    // Rotation id, not a hash of either secret — see `storage::secure`.
+    let secret_version = secure::get_gateway_secret_version()?.unwrap_or_default();
+    let fingerprint = sha256_hex(&format!(
+        "{}|{}",
+        config_shape(settings, &binding),
+        secret_version
+    ));
+
+    if let Some((id, state, existing_fingerprint)) = find_gateway_container().await? {
+        if existing_fingerprint == fingerprint {
+            if state == "running" {
+                return get_gateway_status(settings).await;
+            }
+            docker
+                .start_container(&id, None::<StartContainerOptions<String>>)
+                .await
+                .map_err(|e| format!("Failed to start gateway container: {}", e))?;
+            return get_gateway_status(settings).await;
+        }
+
+        // Config or a secret changed — recreate so the new config is uploaded.
+        if state == "running" {
+            docker
+                .stop_container(&id, None::<StopContainerOptions>)
+                .await
+                .map_err(|e| format!("Failed to stop gateway container: {}", e))?;
+        }
+        docker
+            .remove_container(
+                &id,
+                Some(RemoveContainerOptions {
+                    force: true,
+                    ..Default::default()
+                }),
+            )
+            .await
+            .map_err(|e| format!("Failed to remove gateway container: {}", e))?;
+    }
+
+    let id = create_gateway_container(settings, &binding, &fingerprint).await?;
+
+    // Upload before the first start: LiteLLM reads the config once at boot.
+    let rendered = render_config(settings, &api_key, &master_key);
+    if let Err(e) = upload_config(&id, &rendered).await {
+        // Don't leave a half-configured container behind for the next run to
+        // mistake for a good one.
+        let _ = docker
+            .remove_container(
+                &id,
+                Some(RemoveContainerOptions {
+                    force: true,
+                    ..Default::default()
+                }),
+            )
+            .await;
+        return Err(e);
+    }
+
+    docker
+        .start_container(&id, None::<StartContainerOptions<String>>)
+        .await
+        .map_err(|e| format!("Failed to start gateway container: {}", e))?;
+
+    log::info!(
+        "Model gateway started on {}:{} ({} model(s))",
+        binding.host_ip,
+        settings.port,
+        settings.valid_models().len()
+    );
+
+    get_gateway_status(settings).await
+}
+
+/// Grace period given to LiteLLM on stop. The Docker default is 10s, which app
+/// exit cannot afford to spend on a proxy that holds no state worth flushing.
+const GATEWAY_STOP_GRACE_SECS: i64 = 3;
+
+pub async fn stop_gateway_container() -> Result<(), String> {
+    // Same lock as `ensure_gateway_running`, so a stop can't interleave with a
+    // create/start and leave a container running behind a "stopped" return.
+    let _guard = gateway_lock().lock().await;
+    let docker = get_docker()?;
+
+    if let Some((id, state, _)) = find_gateway_container().await? {
+        if state == "running" {
+            docker
+                .stop_container(
+                    &id,
+                    Some(StopContainerOptions {
+                        t: GATEWAY_STOP_GRACE_SECS,
+                    }),
+                )
+                .await
+                .map_err(|e| format!("Failed to stop gateway container: {}", e))?;
+        }
+    }
+
+    Ok(())
+}
+
+/// Ask the running gateway whether it is up. LiteLLM takes several seconds to
+/// boot, so "container running" and "gateway answering" are not the same thing.
+pub async fn check_gateway_health(port: u16) -> Result<bool, String> {
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(5))
+        .build()
+        .map_err(|e| format!("Failed to build HTTP client: {}", e))?;
+
+    // Dial whatever the container is actually published on — with a
+    // bridge-gateway bind, the host's loopback answers nothing.
+    let base = gateway_binding().await.host_url(port);
+
+    match client
+        .get(format!("{}/health/liveliness", base))
+        .send()
+        .await
+    {
+        Ok(response) => Ok(response.status().is_success()),
+        Err(e) if e.is_connect() || e.is_timeout() => Ok(false),
+        Err(e) => Err(format!("Gateway health check failed: {}", e)),
+    }
+}
+
+pub async fn pull_gateway_image<F>(on_progress: F) -> Result<(), String>
+where
+    F: Fn(String) + Send + 'static,
+{
+    super::image::pull_image(GATEWAY_REGISTRY_IMAGE, on_progress).await
+}
+
+pub async fn build_gateway_image<F>(on_progress: F) -> Result<(), String>
+where
+    F: Fn(String) + Send + 'static,
+{
+    let docker = get_docker()?;
+
+    let tar_bytes = create_gateway_build_context()
+        .map_err(|e| format!("Failed to create gateway build context: {}", e))?;
+
+    let options = BuildImageOptions {
+        t: GATEWAY_LOCAL_IMAGE,
+        rm: true,
+        forcerm: true,
+        ..Default::default()
+    };
+
+    let mut stream = docker.build_image(options, None, Some(tar_bytes.into()));
+
+    while let Some(result) = stream.next().await {
+        match result {
+            Ok(output) => {
+                if let Some(stream) = output.stream {
+                    on_progress(stream);
+                }
+                if let Some(error) = output.error {
+                    return Err(format!("Build error: {}", error));
+                }
+            }
+            Err(e) => return Err(format!("Build stream error: {}", e)),
+        }
+    }
+
+    Ok(())
+}
+
+fn create_gateway_build_context() -> Result<Vec<u8>, std::io::Error> {
+    let mut buf = Vec::new();
+    {
+        let mut archive = tar::Builder::new(&mut buf);
+
+        let mut dockerfile_header = tar::Header::new_gnu();
+        dockerfile_header.set_size(GATEWAY_DOCKERFILE.len() as u64);
+        dockerfile_header.set_mode(0o644);
+        dockerfile_header.set_cksum();
+        archive.append_data(
+            &mut dockerfile_header,
+            "Dockerfile",
+            GATEWAY_DOCKERFILE.as_bytes(),
+        )?;
+
+        let mut config_header = tar::Header::new_gnu();
+        config_header.set_size(GATEWAY_DEFAULT_CONFIG.len() as u64);
+        config_header.set_mode(0o644);
+        config_header.set_cksum();
+        archive.append_data(
+            &mut config_header,
+            "config.yaml",
+            GATEWAY_DEFAULT_CONFIG.as_bytes(),
+        )?;
+
+        archive.finish()?;
+    }
+
+    let _ = buf.flush();
+    Ok(buf)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::gateway_settings::GatewayModel;
+
+    fn settings() -> GatewaySettings {
+        GatewaySettings {
+            enabled: true,
+            port: 4000,
+            provider: "openai".to_string(),
+            api_base: None,
+            models: vec![
+                GatewayModel {
+                    name: "gpt-5.1".to_string(),
+                    model_id: "gpt-5.1".to_string(),
+                },
+                // Half-filled rows must not reach the YAML.
+                GatewayModel {
+                    name: "  ".to_string(),
+                    model_id: "gpt-4o".to_string(),
+                },
+            ],
+        }
+    }
+
+    #[test]
+    fn valid_models_skips_incomplete_rows() {
+        assert_eq!(settings().valid_models().len(), 1);
+    }
+
+    #[test]
+    fn render_config_composes_provider_and_model_id() {
+        let yaml = render_config(&settings(), "sk-provider", "sk-master");
+        assert!(yaml.contains("model_name: \"gpt-5.1\""));
+        assert!(yaml.contains("model: \"openai/gpt-5.1\""));
+        assert!(yaml.contains("api_key: \"sk-provider\""));
+        assert!(yaml.contains("master_key: \"sk-master\""));
+        assert!(yaml.contains("drop_params: true"));
+        // The skipped row must be absent.
+        assert!(!yaml.contains("gpt-4o"));
+    }
+
+    #[test]
+    fn render_config_emits_api_base_only_when_set() {
+        let mut s = settings();
+        assert!(!render_config(&s, "k", "m").contains("api_base"));
+        s.api_base = Some("https://example.test/v1".to_string());
+        assert!(render_config(&s, "k", "m").contains("api_base: \"https://example.test/v1\""));
+        // Blank is treated as unset rather than emitted as an empty URL.
+        s.api_base = Some("   ".to_string());
+        assert!(!render_config(&s, "k", "m").contains("api_base"));
+    }
+
+    #[test]
+    fn yaml_str_escapes_injection_attempts() {
+        let hostile = "a\"\nmaster_key: \"pwned";
+        let quoted = yaml_str(hostile);
+        assert!(quoted.starts_with('"') && quoted.ends_with('"'));
+        // No raw newline can escape the scalar and start a new YAML key.
+        assert!(!quoted[1..quoted.len() - 1].contains('\n'));
+        assert!(quoted.contains("\\\""));
+    }
+
+    #[test]
+    fn config_shape_excludes_secrets_and_tracks_changes() {
+        let binding = GatewayBinding::desktop();
+        let a = config_shape(&settings(), &binding);
+        let mut s = settings();
+        s.models[0].model_id = "gpt-4.1".to_string();
+        assert_ne!(a, config_shape(&s, &binding));
+        assert!(!a.contains("sk-"));
+    }
+
+    #[test]
+    fn config_shape_tracks_the_bind_address() {
+        // Moving between engines must recreate the container rather than leave
+        // it published on an address the new environment doesn't use.
+        let s = settings();
+        assert_ne!(
+            config_shape(&s, &GatewayBinding::desktop()),
+            config_shape(&s, &GatewayBinding::bridge("172.17.0.1"))
+        );
+    }
+
+    #[test]
+    fn docker_desktop_binds_loopback_and_hands_out_host_docker_internal() {
+        let binding = binding_for("Docker Desktop", None);
+        assert_eq!(binding.host_ip, "127.0.0.1");
+        assert_eq!(binding.base_url(4000), "http://host.docker.internal:4000");
+        // Detection must not depend on the bridge answer on this engine.
+        assert_eq!(binding, binding_for("Docker Desktop", Some("172.17.0.1")));
+    }
+
+    #[test]
+    fn native_linux_binds_the_bridge_gateway_it_reports() {
+        // A project container can't reach the host's loopback here, but it can
+        // reach the bridge gateway — and so can nothing on the LAN.
+        let binding = binding_for("Ubuntu 24.04.1 LTS", Some("172.19.0.1"));
+        assert_eq!(binding.host_ip, "172.19.0.1");
+        assert_eq!(binding.base_url(4000), "http://172.19.0.1:4000");
+        assert_eq!(binding.host_url(4000), "http://172.19.0.1:4000");
+    }
+
+    #[test]
+    fn a_missing_bridge_answer_falls_back_to_the_documented_default() {
+        for reported in [None, Some(""), Some("   ")] {
+            assert_eq!(
+                binding_for("Ubuntu 24.04.1 LTS", reported).host_ip,
+                "172.17.0.1"
+            );
+        }
+    }
+
+    #[test]
+    fn no_engine_shape_ever_binds_a_wildcard_address() {
+        // The regression this guards: the published port fronts a container
+        // config holding a billed provider key, and Docker's rules sit ahead of
+        // the host firewall.
+        for os in ["Docker Desktop", "Ubuntu 24.04.1 LTS", "", "Rancher Desktop"] {
+            for gw in [None, Some("172.17.0.1"), Some("10.0.0.1")] {
+                let host_ip = binding_for(os, gw).host_ip;
+                assert_ne!(host_ip, "0.0.0.0", "os={:?} gw={:?}", os, gw);
+                assert_ne!(host_ip, "::", "os={:?} gw={:?}", os, gw);
+                assert!(!host_ip.is_empty());
+            }
+        }
+    }
+
+    #[test]
+    fn only_the_exact_container_name_is_adopted() {
+        // Docker's `name` filter is an unanchored regex: all of these come back
+        // from a filtered list. Adopting one would force-remove a user's
+        // container.
+        assert!(is_gateway_container(Some(&vec![
+            "/triple-c-gateway".to_string()
+        ])));
+        assert!(is_gateway_container(Some(&vec![
+            "/something-else".to_string(),
+            "/triple-c-gateway".to_string(),
+        ])));
+        for impostor in [
+            "/triple-c-gateway-backup",
+            "/my-triple-c-gateway",
+            "/triple-c-gateway2",
+            "triple-c-gateway",
+        ] {
+            assert!(
+                !is_gateway_container(Some(&vec![impostor.to_string()])),
+                "{} must not be adopted",
+                impostor
+            );
+        }
+        assert!(!is_gateway_container(None));
+        assert!(!is_gateway_container(Some(&vec![])));
+    }
+
+    #[tokio::test]
+    async fn the_gateway_lock_serialises_concurrent_callers() {
+        // The auto-start racing the Start button: both would otherwise see no
+        // container and both create one, and the loser gets a Docker 409.
+        use std::sync::atomic::{AtomicUsize, Ordering};
+        use std::sync::Arc;
+
+        let inside = Arc::new(AtomicUsize::new(0));
+        let overlaps = Arc::new(AtomicUsize::new(0));
+
+        let mut tasks = Vec::new();
+        for _ in 0..8 {
+            let inside = inside.clone();
+            let overlaps = overlaps.clone();
+            tasks.push(tokio::spawn(async move {
+                let _guard = gateway_lock().lock().await;
+                if inside.fetch_add(1, Ordering::SeqCst) != 0 {
+                    overlaps.fetch_add(1, Ordering::SeqCst);
+                }
+                tokio::task::yield_now().await;
+                tokio::time::sleep(std::time::Duration::from_millis(1)).await;
+                inside.fetch_sub(1, Ordering::SeqCst);
+            }));
+        }
+        for t in tasks {
+            t.await.unwrap();
+        }
+
+        assert_eq!(overlaps.load(Ordering::SeqCst), 0);
+        assert_eq!(inside.load(Ordering::SeqCst), 0);
+    }
+}

app/src-tauri/src/docker/legacy_cleanup.rs

@@ -0,0 +1,137 @@
+//! One-release migration shim for the removed built-in MCP feature.
+//!
+//! Older releases created a per-project user-defined bridge network
+//! (`triple-c-net-<projectId>`) plus one container per Docker-backed MCP
+//! server, and attached the project container to that network. Now that MCP
+//! support is gone, those leftovers have to be torn down — a container whose
+//! `NetworkMode` names a network that no longer exists refuses to start, so
+//! the cleanup is paired with a forced container recreation (see
+//! `container_needs_recreation`).
+//!
+//! Everything here is best-effort: failures are logged and never abort the
+//! caller, and absent resources are a silent no-op. This module can be deleted
+//! a release after all users have migrated.
+
+use bollard::container::{ListContainersOptions, RemoveContainerOptions};
+use bollard::network::InspectNetworkOptions;
+use std::collections::HashMap;
+
+use super::client::get_docker;
+
+/// Network name used by the old MCP implementation for a project.
+fn legacy_network_name(project_id: &str) -> String {
+    format!("triple-c-net-{}", project_id)
+}
+
+/// Force-remove every leftover MCP server container.
+///
+/// Matched by the `triple-c.mcp-server` label rather than by name, so
+/// containers survive even if the MCP server definitions they came from are
+/// already gone from storage. Best-effort: errors are logged and skipped.
+pub async fn remove_legacy_mcp_containers(project_id: &str) {
+    let docker = match get_docker() {
+        Ok(d) => d,
+        Err(e) => {
+            log::debug!(
+                "Skipping legacy MCP container cleanup for project {}: {}",
+                project_id,
+                e
+            );
+            return;
+        }
+    };
+
+    let filters: HashMap<String, Vec<String>> = HashMap::from([(
+        "label".to_string(),
+        vec!["triple-c.mcp-server".to_string()],
+    )]);
+
+    let containers = match docker
+        .list_containers(Some(ListContainersOptions {
+            all: true,
+            filters,
+            ..Default::default()
+        }))
+        .await
+    {
+        Ok(c) => c,
+        Err(e) => {
+            log::warn!("Failed to list legacy MCP containers: {}", e);
+            return;
+        }
+    };
+
+    for container in containers {
+        let Some(id) = container.id else { continue };
+        match docker
+            .remove_container(
+                &id,
+                Some(RemoveContainerOptions {
+                    force: true,
+                    ..Default::default()
+                }),
+            )
+            .await
+        {
+            Ok(_) => log::info!("Removed legacy MCP container {}", id),
+            Err(e) => log::warn!("Failed to remove legacy MCP container {}: {}", id, e),
+        }
+    }
+}
+
+/// Remove the old per-project Docker network, disconnecting any remaining
+/// members first (a network with attached endpoints cannot be deleted).
+///
+/// Silent no-op when the network does not exist. Best-effort: errors are
+/// logged and never propagated.
+pub async fn remove_legacy_project_network(project_id: &str) {
+    let docker = match get_docker() {
+        Ok(d) => d,
+        Err(e) => {
+            log::debug!(
+                "Skipping legacy network cleanup for project {}: {}",
+                project_id,
+                e
+            );
+            return;
+        }
+    };
+    let network_name = legacy_network_name(project_id);
+
+    // Inspect to discover connected containers; absence means nothing to do.
+    let info = match docker
+        .inspect_network(&network_name, None::<InspectNetworkOptions<String>>)
+        .await
+    {
+        Ok(info) => info,
+        Err(_) => {
+            log::debug!("Legacy network {} not present, nothing to do", network_name);
+            return;
+        }
+    };
+
+    if let Some(containers) = info.containers {
+        for container_id in containers.into_keys() {
+            let disconnect_opts = bollard::network::DisconnectNetworkOptions {
+                container: container_id.clone(),
+                force: true,
+            };
+            if let Err(e) = docker
+                .disconnect_network(&network_name, disconnect_opts)
+                .await
+            {
+                log::warn!(
+                    "Failed to disconnect container {} from legacy network {}: {}",
+                    container_id,
+                    network_name,
+                    e
+                );
+            }
+        }
+    }
+
+    match docker.remove_network(&network_name).await {
+        Ok(_) => log::info!("Removed legacy Docker network {}", network_name),
+        Err(e) => log::warn!("Failed to remove legacy network {}: {}", network_name, e),
+    }
+}

app/src-tauri/src/docker/mod.rs

@@ -1,10 +1,15 @@
+pub mod ca_certs;
 pub mod client;
 pub mod container;
 pub mod image;
 pub mod exec;
-pub mod network;
+pub mod gateway;
+pub mod legacy_cleanup;
+pub mod migration;
 pub mod stt;
 
+#[allow(unused_imports)]
+pub use gateway::*;
 #[allow(unused_imports)]
 pub use stt::*;
 #[allow(unused_imports)]
@@ -16,4 +21,9 @@ pub use image::*;
 #[allow(unused_imports)]
 pub use exec::*;
 #[allow(unused_imports)]
-pub use network::*;
+pub use legacy_cleanup::*;
+#[allow(unused_imports)]
+pub use migration::*;
+// Deliberately *not* re-exported flat: `ca_certs::resolve` and
+// `ca_certs::CA_MOUNT_DIR` are far clearer than bare `resolve` in a module that
+// already re-exports five other namespaces.

app/src-tauri/src/docker/network.rs

@@ -1,129 +0,0 @@
-use bollard::network::{CreateNetworkOptions, InspectNetworkOptions};
-use std::collections::HashMap;
-
-use super::client::get_docker;
-
-/// Network name for a project's MCP containers.
-fn project_network_name(project_id: &str) -> String {
-    format!("triple-c-net-{}", project_id)
-}
-
-/// Ensure a Docker bridge network exists for the project.
-/// Returns the network name.
-pub async fn ensure_project_network(project_id: &str) -> Result<String, String> {
-    let docker = get_docker()?;
-    let network_name = project_network_name(project_id);
-
-    // Check if network already exists
-    match docker
-        .inspect_network(&network_name, None::<InspectNetworkOptions<String>>)
-        .await
-    {
-        Ok(_) => {
-            log::debug!("Network {} already exists", network_name);
-            return Ok(network_name);
-        }
-        Err(_) => {
-            // Network doesn't exist, create it
-        }
-    }
-
-    let options = CreateNetworkOptions {
-        name: network_name.clone(),
-        driver: "bridge".to_string(),
-        labels: HashMap::from([
-            ("triple-c.managed".to_string(), "true".to_string()),
-            ("triple-c.project-id".to_string(), project_id.to_string()),
-        ]),
-        ..Default::default()
-    };
-
-    docker
-        .create_network(options)
-        .await
-        .map_err(|e| format!("Failed to create network {}: {}", network_name, e))?;
-
-    log::info!("Created Docker network {}", network_name);
-    Ok(network_name)
-}
-
-/// Connect a container to the project network.
-#[allow(dead_code)]
-pub async fn connect_container_to_network(
-    container_id: &str,
-    network_name: &str,
-) -> Result<(), String> {
-    let docker = get_docker()?;
-
-    let config = bollard::network::ConnectNetworkOptions {
-        container: container_id.to_string(),
-        ..Default::default()
-    };
-
-    docker
-        .connect_network(network_name, config)
-        .await
-        .map_err(|e| {
-            format!(
-                "Failed to connect container {} to network {}: {}",
-                container_id, network_name, e
-            )
-        })?;
-
-    log::debug!(
-        "Connected container {} to network {}",
-        container_id,
-        network_name
-    );
-    Ok(())
-}
-
-/// Remove the project network (best-effort). Disconnects all containers first.
-pub async fn remove_project_network(project_id: &str) -> Result<(), String> {
-    let docker = get_docker()?;
-    let network_name = project_network_name(project_id);
-
-    // Inspect to get connected containers
-    let info = match docker
-        .inspect_network(&network_name, None::<InspectNetworkOptions<String>>)
-        .await
-    {
-        Ok(info) => info,
-        Err(_) => {
-            log::debug!(
-                "Network {} not found, nothing to remove",
-                network_name
-            );
-            return Ok(());
-        }
-    };
-
-    // Disconnect all containers
-    if let Some(containers) = info.containers {
-        for (container_id, _) in containers {
-            let disconnect_opts = bollard::network::DisconnectNetworkOptions {
-                container: container_id.clone(),
-                force: true,
-            };
-            if let Err(e) = docker
-                .disconnect_network(&network_name, disconnect_opts)
-                .await
-            {
-                log::warn!(
-                    "Failed to disconnect container {} from network {}: {}",
-                    container_id,
-                    network_name,
-                    e
-                );
-            }
-        }
-    }
-
-    // Remove the network
-    match docker.remove_network(&network_name).await {
-        Ok(_) => log::info!("Removed Docker network {}", network_name),
-        Err(e) => log::warn!("Failed to remove network {}: {}", network_name, e),
-    }
-
-    Ok(())
-}

app/src-tauri/src/install_helper/mod.rs

@@ -0,0 +1,53 @@
+// Helpers for detecting whether Docker (or a Docker-compatible runtime) is
+// installed on the host and, when missing, offering to install it for the user.
+//
+// We use the Docker convenience script on Linux and Rancher Desktop on macOS /
+// Windows. On every platform we also surface an official documentation URL so
+// users without a recognised package manager can install manually.
+
+use serde::{Deserialize, Serialize};
+
+pub mod platform;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct InstallOptions {
+    /// "linux" | "macos" | "windows" | "unknown"
+    pub os: String,
+    /// User-facing name of what we'd install ("Docker Engine" / "Rancher Desktop").
+    pub product_name: String,
+    /// Whether we can kick off a one-click install with what's on this machine.
+    pub can_auto_install: bool,
+    /// Short identifier of the method we'd use ("pkexec", "brew", "winget", or None).
+    pub auto_install_method: Option<String>,
+    /// If auto-install isn't possible, a human-readable reason to show the user.
+    pub auto_install_blocker: Option<String>,
+    /// Official documentation URL for manual install.
+    pub docs_url: String,
+    /// Ordered manual install steps (plain text lines).
+    pub manual_steps: Vec<String>,
+    /// Notes to display after a successful auto-install (e.g. log out/back in).
+    pub post_install_notes: Vec<String>,
+}
+
+pub fn detect_install_options() -> InstallOptions {
+    if cfg!(target_os = "linux") {
+        platform::linux_options()
+    } else if cfg!(target_os = "macos") {
+        platform::macos_options()
+    } else if cfg!(target_os = "windows") {
+        platform::windows_options()
+    } else {
+        InstallOptions {
+            os: "unknown".into(),
+            product_name: "Docker".into(),
+            can_auto_install: false,
+            auto_install_method: None,
+            auto_install_blocker: Some("Unsupported operating system".into()),
+            docs_url: "https://docs.docker.com/get-docker/".into(),
+            manual_steps: vec![
+                "Visit the Docker documentation and follow the install guide for your OS.".into(),
+            ],
+            post_install_notes: vec![],
+        }
+    }
+}

app/src-tauri/src/install_helper/platform.rs

@@ -0,0 +1,288 @@
+use std::path::PathBuf;
+use std::process::Stdio;
+
+use tauri::{AppHandle, Emitter};
+use tokio::io::{AsyncBufReadExt, BufReader};
+use tokio::process::Command;
+
+use super::InstallOptions;
+
+const PROGRESS_EVENT: &str = "docker-install-progress";
+
+fn which(cmd: &str) -> bool {
+    find_on_path(cmd).is_some()
+}
+
+/// Search PATH for an executable, plus a handful of well-known locations that
+/// GUI-launched apps on macOS/Linux typically miss (Homebrew prefixes, etc.).
+fn find_on_path(cmd: &str) -> Option<PathBuf> {
+    #[cfg(unix)]
+    let extra: &[&str] = &[
+        "/opt/homebrew/bin",
+        "/usr/local/bin",
+        "/usr/bin",
+        "/bin",
+    ];
+    #[cfg(windows)]
+    let extra: &[&str] = &[];
+
+    if let Ok(path) = std::env::var("PATH") {
+        let sep = if cfg!(windows) { ';' } else { ':' };
+        for dir in path.split(sep).chain(extra.iter().copied()) {
+            let candidate = PathBuf::from(dir).join(cmd);
+            if candidate.is_file() {
+                return Some(candidate);
+            }
+            #[cfg(windows)]
+            for ext in ["exe", "cmd", "bat"] {
+                let mut with_ext = candidate.clone();
+                with_ext.set_extension(ext);
+                if with_ext.is_file() {
+                    return Some(with_ext);
+                }
+            }
+        }
+    }
+    for dir in extra {
+        let candidate = PathBuf::from(dir).join(cmd);
+        if candidate.is_file() {
+            return Some(candidate);
+        }
+    }
+    None
+}
+
+async fn stream(app: &AppHandle, mut child: tokio::process::Child) -> Result<(), String> {
+    let stdout = child.stdout.take();
+    let stderr = child.stderr.take();
+
+    let app_out = app.clone();
+    let out_task = tokio::spawn(async move {
+        if let Some(out) = stdout {
+            let mut lines = BufReader::new(out).lines();
+            while let Ok(Some(line)) = lines.next_line().await {
+                let _ = app_out.emit(PROGRESS_EVENT, line);
+            }
+        }
+    });
+
+    let app_err = app.clone();
+    let err_task = tokio::spawn(async move {
+        if let Some(err) = stderr {
+            let mut lines = BufReader::new(err).lines();
+            while let Ok(Some(line)) = lines.next_line().await {
+                let _ = app_err.emit(PROGRESS_EVENT, line);
+            }
+        }
+    });
+
+    let status = child
+        .wait()
+        .await
+        .map_err(|e| format!("install process failed: {}", e))?;
+    let _ = out_task.await;
+    let _ = err_task.await;
+
+    if !status.success() {
+        return Err(format!(
+            "installer exited with status {}",
+            status.code().map(|c| c.to_string()).unwrap_or_else(|| "signal".into())
+        ));
+    }
+    Ok(())
+}
+
+// ─── Linux ───────────────────────────────────────────────────────────────────
+
+pub fn linux_options() -> InstallOptions {
+    let has_pkexec = which("pkexec");
+    let has_curl = which("curl");
+
+    let (can_auto, blocker) = match (has_pkexec, has_curl) {
+        (true, true) => (true, None),
+        (false, _) => (
+            false,
+            Some("pkexec not found — install policykit-1 or follow manual steps.".into()),
+        ),
+        (_, false) => (
+            false,
+            Some("curl not found — install curl or follow manual steps.".into()),
+        ),
+    };
+
+    InstallOptions {
+        os: "linux".into(),
+        product_name: "Docker Engine".into(),
+        can_auto_install: can_auto,
+        auto_install_method: if can_auto { Some("pkexec".into()) } else { None },
+        auto_install_blocker: blocker,
+        docs_url: "https://docs.docker.com/engine/install/".into(),
+        manual_steps: vec![
+            "Open a terminal.".into(),
+            "Run: curl -fsSL https://get.docker.com | sh".into(),
+            "Add yourself to the docker group: sudo usermod -aG docker $USER".into(),
+            "Log out and log back in for group changes to take effect.".into(),
+        ],
+        post_install_notes: vec![
+            "Log out and log back in (or reboot) so your user picks up the docker group.".into(),
+            "If Docker isn't detected after re-login, start the service: sudo systemctl start docker".into(),
+        ],
+    }
+}
+
+async fn run_linux_install(app: &AppHandle) -> Result<(), String> {
+    // Grab the current username so pkexec (which runs as root) can add the
+    // original invoking user to the docker group.
+    let invoking_user = std::env::var("USER")
+        .or_else(|_| std::env::var("LOGNAME"))
+        .map_err(|_| "could not determine invoking username".to_string())?;
+
+    // Write a self-contained installer script to a temp file. Running the
+    // Docker convenience script then appending the user to the docker group
+    // and enabling the service.
+    let script = format!(
+        r#"#!/bin/sh
+set -e
+echo "[triple-c] Downloading Docker install script..."
+curl -fsSL https://get.docker.com -o /tmp/triple-c-get-docker.sh
+echo "[triple-c] Running Docker install script (may take a few minutes)..."
+sh /tmp/triple-c-get-docker.sh
+rm -f /tmp/triple-c-get-docker.sh
+echo "[triple-c] Adding {user} to docker group..."
+usermod -aG docker "{user}" || true
+echo "[triple-c] Enabling docker service..."
+systemctl enable --now docker 2>/dev/null || service docker start 2>/dev/null || true
+echo "[triple-c] Install complete. Log out and back in to use Docker without sudo."
+"#,
+        user = invoking_user
+    );
+
+    let script_path: PathBuf = std::env::temp_dir().join("triple-c-install-docker.sh");
+    tokio::fs::write(&script_path, script)
+        .await
+        .map_err(|e| format!("failed to write install script: {}", e))?;
+
+    let _ = app.emit(
+        PROGRESS_EVENT,
+        format!("Requesting administrator privileges via pkexec..."),
+    );
+
+    let child = Command::new("pkexec")
+        .arg("sh")
+        .arg(&script_path)
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .map_err(|e| format!("failed to launch pkexec: {}", e))?;
+
+    let result = stream(app, child).await;
+    let _ = tokio::fs::remove_file(&script_path).await;
+    result
+}
+
+// ─── macOS ───────────────────────────────────────────────────────────────────
+
+pub fn macos_options() -> InstallOptions {
+    let has_brew = which("brew");
+    InstallOptions {
+        os: "macos".into(),
+        product_name: "Rancher Desktop".into(),
+        can_auto_install: has_brew,
+        auto_install_method: if has_brew { Some("brew".into()) } else { None },
+        auto_install_blocker: if has_brew {
+            None
+        } else {
+            Some("Homebrew not found — use the manual download.".into())
+        },
+        docs_url: "https://docs.rancherdesktop.io/getting-started/installation/".into(),
+        manual_steps: vec![
+            "Download the Rancher Desktop .dmg from the official site.".into(),
+            "Open the .dmg and drag Rancher Desktop into Applications.".into(),
+            "Launch Rancher Desktop and complete the first-run setup (choose dockerd/moby).".into(),
+            "Once the Docker socket is available, come back and click Refresh.".into(),
+        ],
+        post_install_notes: vec![
+            "Launch Rancher Desktop from Applications if it didn't open automatically.".into(),
+            "In Preferences, make sure the container engine is set to dockerd (moby).".into(),
+        ],
+    }
+}
+
+async fn run_macos_install(app: &AppHandle) -> Result<(), String> {
+    let brew = find_on_path("brew")
+        .ok_or_else(|| "Homebrew not found — follow the manual steps instead.".to_string())?;
+    let _ = app.emit(
+        PROGRESS_EVENT,
+        format!("Running: {} install --cask rancher", brew.display()),
+    );
+    let child = Command::new(&brew)
+        .args(["install", "--cask", "rancher"])
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .map_err(|e| format!("failed to launch brew: {}", e))?;
+    stream(app, child).await
+}
+
+// ─── Windows ─────────────────────────────────────────────────────────────────
+
+pub fn windows_options() -> InstallOptions {
+    let has_winget = which("winget");
+    InstallOptions {
+        os: "windows".into(),
+        product_name: "Rancher Desktop".into(),
+        can_auto_install: has_winget,
+        auto_install_method: if has_winget { Some("winget".into()) } else { None },
+        auto_install_blocker: if has_winget {
+            None
+        } else {
+            Some("winget not found — use the manual download.".into())
+        },
+        docs_url: "https://docs.rancherdesktop.io/getting-started/installation/".into(),
+        manual_steps: vec![
+            "Download the Rancher Desktop .msi from the official site.".into(),
+            "Run the installer and accept the WSL2 prompts if asked.".into(),
+            "Launch Rancher Desktop and complete the first-run setup (choose dockerd/moby).".into(),
+            "Once the Docker engine is running, come back and click Refresh.".into(),
+        ],
+        post_install_notes: vec![
+            "Launch Rancher Desktop from the Start menu if it didn't open automatically.".into(),
+            "In Preferences > Container Engine, make sure dockerd (moby) is selected.".into(),
+        ],
+    }
+}
+
+async fn run_windows_install(app: &AppHandle) -> Result<(), String> {
+    let _ = app.emit(
+        PROGRESS_EVENT,
+        "Running: winget install --id SUSE.RancherDesktop -e --accept-package-agreements --accept-source-agreements".to_string(),
+    );
+    let child = Command::new("winget")
+        .args([
+            "install",
+            "--id",
+            "SUSE.RancherDesktop",
+            "-e",
+            "--accept-package-agreements",
+            "--accept-source-agreements",
+        ])
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .map_err(|e| format!("failed to launch winget: {}", e))?;
+    stream(app, child).await
+}
+
+// ─── Dispatcher ──────────────────────────────────────────────────────────────
+
+pub async fn run_install(app: &AppHandle) -> Result<(), String> {
+    if cfg!(target_os = "linux") {
+        run_linux_install(app).await
+    } else if cfg!(target_os = "macos") {
+        run_macos_install(app).await
+    } else if cfg!(target_os = "windows") {
+        run_windows_install(app).await
+    } else {
+        Err("auto-install is not supported on this OS".into())
+    }
+}

app/src-tauri/src/lib.rs

@@ -1,25 +1,203 @@
+mod auth_bridge;
+mod browser_view;
 mod commands;
 mod docker;
+mod install_helper;
 mod logging;
 mod models;
+mod project_lock;
 mod storage;
 pub mod web_terminal;
 
-use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
 
+use auth_bridge::AuthBridgeManager;
 use docker::exec::ExecSessionManager;
 use storage::projects_store::ProjectsStore;
 use storage::settings_store::SettingsStore;
-use storage::mcp_store::McpStore;
-use tauri::Manager;
+use tauri::async_runtime::JoinHandle;
+use tauri::{Emitter, Manager};
+use tokio::sync::watch;
 use web_terminal::WebTerminalServer;
 
 pub struct AppState {
     pub projects_store: Arc<ProjectsStore>,
     pub settings_store: Arc<SettingsStore>,
-    pub mcp_store: Arc<McpStore>,
     pub exec_manager: Arc<ExecSessionManager>,
+    pub auth_bridge: Arc<AuthBridgeManager>,
     pub web_terminal_server: Arc<tokio::sync::Mutex<Option<WebTerminalServer>>>,
+    pub lifecycle: Arc<Lifecycle>,
+    /// The file `preview_settings_import` last decrypted successfully, held
+    /// so `apply_settings_import` can re-read and re-decrypt the same file
+    /// without the frontend ever passing a host path back to Rust as an
+    /// argument — see the doc comment on `commands::settings_export_commands`
+    /// for why that direction specifically is the one this app treats as
+    /// dangerous. Deliberately re-decrypted rather than cached in plaintext:
+    /// nothing here holds a decrypted secret in memory for longer than one
+    /// command's execution.
+    ///
+    /// Also pins a hash of the file's ciphertext at preview time, so
+    /// `apply_settings_import` can refuse to proceed if the file on disk
+    /// changed underneath the pending import — otherwise confirming a
+    /// preview is not actually binding on what gets applied.
+    pub pending_settings_import:
+        Arc<tokio::sync::Mutex<Option<commands::settings_export_commands::PendingSettingsImport>>>,
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Startup / shutdown coordination
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Total wall-clock budget for teardown before the process exits regardless.
+///
+/// Six teardown steps used to run *serially* inside a `block_on` on the
+/// window-event thread with no timeout: two container stops at Docker's default
+/// 10s grace, a `docker exec` per browser-view project, and every bollard call
+/// inheriting a 120s client timeout. Quitting after Docker Desktop had already
+/// gone away froze the window for minutes. Nothing here is worth more than a
+/// few seconds of a user's exit.
+const SHUTDOWN_BUDGET: Duration = Duration::from_secs(8);
+
+/// How long the in-flight auto-start tasks get to notice cancellation before
+/// they are aborted. They only have to reach their next await point.
+const STARTUP_CANCEL_BUDGET: Duration = Duration::from_secs(3);
+
+/// Backoff (seconds) between auto-start attempts. Docker Desktop routinely
+/// takes 30-60s to accept API calls after login, which is exactly the window in
+/// which Triple-C used to be launched, fail once, and stay broken for the whole
+/// session.
+const AUTOSTART_DELAYS: [u64; 8] = [0, 2, 4, 8, 15, 15, 30, 30];
+
+/// Owns the "is the app going away?" signal and the handles of the background
+/// tasks started during `setup`.
+///
+/// Both auto-starts are fire-and-forget, and quitting quickly used to race
+/// them: `CloseRequested` stopped a gateway container that did not exist yet,
+/// and the detached task then created and started it *after* the app was gone —
+/// leaving an orphan proxy holding a provider key. The same shape orphaned the
+/// web terminal, whose task wrote its server into the state slot that
+/// `CloseRequested` had already `take()`-n. Shutdown therefore cancels and
+/// waits for these tasks *before* running teardown, so teardown always sees the
+/// final state of the world.
+pub struct Lifecycle {
+    cancel: watch::Sender<bool>,
+    tasks: Mutex<Vec<JoinHandle<()>>>,
+    shutting_down: AtomicBool,
+}
+
+impl Lifecycle {
+    fn new() -> Self {
+        let (cancel, _) = watch::channel(false);
+        Self {
+            cancel,
+            tasks: Mutex::new(Vec::new()),
+            shutting_down: AtomicBool::new(false),
+        }
+    }
+
+    /// A receiver that flips to `true` when the app starts shutting down.
+    pub fn cancellation(&self) -> watch::Receiver<bool> {
+        self.cancel.subscribe()
+    }
+
+    pub fn is_shutting_down(&self) -> bool {
+        *self.cancel.borrow()
+    }
+
+    /// Register a startup task so shutdown can wait for it.
+    fn track(&self, handle: JoinHandle<()>) {
+        self.tasks
+            .lock()
+            .unwrap_or_else(|e| e.into_inner())
+            .push(handle);
+    }
+
+    /// `true` the first time only — the window can emit `CloseRequested` again
+    /// once we ask the app to exit, and teardown must not restart.
+    fn begin_shutdown(&self) -> bool {
+        if self.shutting_down.swap(true, Ordering::SeqCst) {
+            return false;
+        }
+        // `send_replace`, not `send`: `send` reports an error *and leaves the
+        // value untouched* when nothing is subscribed, which is exactly the
+        // case when neither auto-start is enabled — and `is_shutting_down` (the
+        // web terminal's check) reads that stored value.
+        self.cancel.send_replace(true);
+        true
+    }
+
+    /// Let the tracked startup tasks unwind, then abort whatever is left.
+    async fn settle_startup_tasks(&self) {
+        let mut handles: Vec<JoinHandle<()>> = std::mem::take(
+            &mut *self.tasks.lock().unwrap_or_else(|e| e.into_inner()),
+        );
+        if handles.is_empty() {
+            return;
+        }
+        let settle = async {
+            for handle in &mut handles {
+                let _ = handle.await;
+            }
+        };
+        if tokio::time::timeout(STARTUP_CANCEL_BUDGET, settle).await.is_err() {
+            log::warn!("Startup tasks did not settle in time — aborting them");
+            for handle in &handles {
+                handle.abort();
+            }
+        }
+    }
+}
+
+/// Run an auto-start until it succeeds, the app quits, or the retries run out.
+///
+/// Without this a launch that beats the Docker daemon (or Docker Desktop) to
+/// readiness left the gateway and STT down for the entire session, with no
+/// path back: nothing re-attempts them.
+async fn autostart_with_retry<F, Fut>(label: &str, mut cancel: watch::Receiver<bool>, mut attempt: F)
+where
+    F: FnMut() -> Fut,
+    Fut: std::future::Future<Output = Result<(), String>>,
+{
+    for (index, delay) in AUTOSTART_DELAYS.iter().enumerate() {
+        if *delay > 0 {
+            tokio::select! {
+                _ = cancel.changed() => return,
+                _ = tokio::time::sleep(Duration::from_secs(*delay)) => {}
+            }
+        }
+        if *cancel.borrow() {
+            return;
+        }
+
+        // Cancellation races the attempt itself, not just the backoff, so a
+        // quick quit isn't held up by an in-flight Docker call — and, more
+        // importantly, so the attempt cannot complete after teardown has run.
+        let result = tokio::select! {
+            _ = cancel.changed() => return,
+            r = attempt() => r,
+        };
+
+        match result {
+            Ok(()) => {
+                if index > 0 {
+                    log::info!("{} auto-start succeeded on attempt {}", label, index + 1);
+                }
+                return;
+            }
+            Err(e) => {
+                let last = index + 1 == AUTOSTART_DELAYS.len();
+                if index == 0 {
+                    log::warn!("{} auto-start failed ({}) — will retry", label, e);
+                } else if last {
+                    log::error!("{} auto-start gave up after {} attempts: {}", label, index + 1, e);
+                } else {
+                    log::debug!("{} auto-start attempt {} failed: {}", label, index + 1, e);
+                }
+            }
+        }
+    }
 }
 
 pub fn run() {
@@ -39,30 +217,27 @@ pub fn run() {
             panic!("Failed to initialize settings store: {}", e);
         }
     });
-    let mcp_store = Arc::new(match McpStore::new() {
-        Ok(s) => s,
-        Err(e) => {
-            log::error!("Failed to initialize MCP store: {}", e);
-            panic!("Failed to initialize MCP store: {}", e);
-        }
-    });
     let exec_manager = Arc::new(ExecSessionManager::new());
+    let auth_bridge = Arc::new(AuthBridgeManager::new());
+    let lifecycle = Arc::new(Lifecycle::new());
 
     // Clone Arcs for the setup closure (web terminal auto-start)
     let projects_store_setup = projects_store.clone();
     let settings_store_setup = settings_store.clone();
     let exec_manager_setup = exec_manager.clone();
+    let lifecycle_setup = lifecycle.clone();
 
     tauri::Builder::default()
-        .plugin(tauri_plugin_store::Builder::default().build())
         .plugin(tauri_plugin_dialog::init())
         .plugin(tauri_plugin_opener::init())
         .manage(AppState {
             projects_store,
             settings_store,
-            mcp_store,
             exec_manager,
+            auth_bridge,
             web_terminal_server: Arc::new(tokio::sync::Mutex::new(None)),
+            lifecycle,
+            pending_settings_import: Arc::new(tokio::sync::Mutex::new(None)),
         })
         .setup(move |app| {
             match tauri::image::Image::from_bytes(include_bytes!("../icons/icon.png")) {
@@ -76,6 +251,40 @@ pub fn run() {
                 }
             }
 
+            // ── Startup disk housekeeping ────────────────────────────────
+            // Until now the only sweep ran *after* a recreation, so a user who
+            // simply stopped launching a project kept its orphaned snapshot
+            // layers forever, and anything a crash left behind (a probe
+            // container pinning a base image, a rollback pin whose migration
+            // record is gone) had no path back at all. All of it is
+            // read-mostly and finishes in well under a second on an idle daemon,
+            // but they are detached anyway: housekeeping must never delay the
+            // window appearing, and a daemon that is not running yet is a
+            // logged warning rather than a failed start.
+            //
+            // Ordering matters. Probes are removed first because a probe holds
+            // an image open and the sweep will not force; pins are untagged
+            // second so the images they were holding are dangling by the time
+            // the sweep lists them; the sweep runs last and collects both.
+            let projects_store_for_cleanup = projects_store_setup.clone();
+            tauri::async_runtime::spawn(async move {
+                crate::docker::reap_probe_containers().await;
+                let reaped = crate::docker::reap_stale_migration_pins().await;
+                if reaped > 0 {
+                    log::info!("Startup housekeeping dropped {} stale rollback pin(s)", reaped);
+                }
+                crate::docker::sweep_orphaned_snapshots_logged("startup").await;
+                // A container/image/volume `remove_project` could not delete
+                // is recorded rather than lost — see triple-c#31 — and this is
+                // the only place anything ever retries it. Takes the store so
+                // it can refuse to touch a project that turns out to still be
+                // live — see the long comment on the function itself.
+                crate::commands::project_commands::retry_pending_cleanup_logged(
+                    &projects_store_for_cleanup,
+                )
+                .await;
+            });
+
             // Auto-start web terminal server if enabled in settings
             let settings = settings_store_setup.get();
             if settings.web_terminal.enabled {
@@ -87,8 +296,9 @@ pub fn run() {
                     let set_store = settings_store_setup.clone();
                     let state = app.state::<AppState>();
                     let web_server_mutex = state.web_terminal_server.clone();
+                    let lifecycle = lifecycle_setup.clone();
 
-                    tauri::async_runtime::spawn(async move {
+                    let handle = tauri::async_runtime::spawn(async move {
                         match WebTerminalServer::start(
                             port,
                             token,
@@ -99,6 +309,16 @@ pub fn run() {
                         .await
                         {
                             Ok(server) => {
+                                // The app may have been asked to quit while the
+                                // server was coming up, in which case teardown
+                                // has already emptied this slot and would never
+                                // look at it again. Stop it here instead of
+                                // storing an orphan.
+                                if lifecycle.is_shutting_down() {
+                                    server.stop();
+                                    log::info!("Web terminal stopped immediately: app is exiting");
+                                    return;
+                                }
                                 let mut guard = web_server_mutex.lock().await;
                                 *guard = Some(server);
                                 log::info!("Web terminal auto-started on port {}", port);
@@ -108,43 +328,130 @@ pub fn run() {
                             }
                         }
                     });
+                    lifecycle_setup.track(handle);
                 }
             }
 
             // Auto-start STT container if enabled in settings
             if settings.stt.enabled {
                 let stt_settings = settings.stt.clone();
-                tauri::async_runtime::spawn(async move {
-                    match docker::stt::ensure_stt_running(&stt_settings).await {
-                        Ok(status) => {
-                            if status.running {
-                                log::info!("STT container auto-started on port {}", stt_settings.port);
-                            } else {
-                                log::warn!("STT auto-start: container not running after ensure_stt_running");
-                            }
+                let cancel = lifecycle_setup.cancellation();
+                let handle = tauri::async_runtime::spawn(async move {
+                    autostart_with_retry("STT container", cancel, || async {
+                        let status = docker::stt::ensure_stt_running(&stt_settings).await?;
+                        if status.running {
+                            log::info!("STT container auto-started on port {}", stt_settings.port);
+                            Ok(())
+                        } else {
+                            Err("container not running after ensure_stt_running".to_string())
                         }
-                        Err(e) => {
-                            log::error!("Failed to auto-start STT container: {}", e);
-                        }
-                    }
+                    })
+                    .await;
                 });
+                lifecycle_setup.track(handle);
+            }
+
+            // Auto-start model gateway container if enabled in settings
+            if settings.gateway.enabled {
+                let gateway_settings = settings.gateway.clone();
+                let cancel = lifecycle_setup.cancellation();
+                let handle = tauri::async_runtime::spawn(async move {
+                    autostart_with_retry("Model gateway", cancel, || async {
+                        let status =
+                            docker::gateway::ensure_gateway_running(&gateway_settings).await?;
+                        if status.running {
+                            log::info!(
+                                "Model gateway auto-started on port {}",
+                                gateway_settings.port
+                            );
+                            Ok(())
+                        } else {
+                            Err("container not running after ensure_gateway_running".to_string())
+                        }
+                    })
+                    .await;
+                });
+                lifecycle_setup.track(handle);
             }
 
             Ok(())
         })
         .on_window_event(|window, event| {
-            if let tauri::WindowEvent::CloseRequested { .. } = event {
+            if let tauri::WindowEvent::CloseRequested { api, .. } = event {
+                // This handler fires for *every* window, and what follows stops
+                // containers and exits the process. Only the main window means
+                // that. Secondary windows — the browser view's pop-out — are
+                // closed and reopened freely and must just close.
+                if window.label() != "main" {
+                    return;
+                }
+
                 let state = window.state::<AppState>();
-                tauri::async_runtime::block_on(async {
-                    // Stop web terminal server
-                    let mut server_guard = state.web_terminal_server.lock().await;
-                    if let Some(server) = server_guard.take() {
-                        server.stop();
+                let lifecycle = state.lifecycle.clone();
+
+                // Already shutting down: let the window close. That covers our
+                // own `exit` unwinding it, and it deliberately leaves a second
+                // click on the X as a force-quit — teardown is a courtesy, not
+                // a hostage situation.
+                if !lifecycle.begin_shutdown() {
+                    return;
+                }
+
+                let exec_manager = state.exec_manager.clone();
+                let auth_bridge = state.auth_bridge.clone();
+                let web_terminal_server = state.web_terminal_server.clone();
+                drop(state);
+
+                // Teardown talks to Docker, so it cannot be instant. Keep the
+                // window alive and tell the UI what is happening rather than
+                // blocking the event thread on it and looking hung.
+                api.prevent_close();
+                let _ = window.emit("app-shutting-down", ());
+
+                let app_handle = window.app_handle().clone();
+                tauri::async_runtime::spawn(async move {
+                    let teardown = async {
+                        // First: let the auto-starts unwind. Anything they are
+                        // midway through creating has to exist before the stops
+                        // below run, or it outlives the app.
+                        lifecycle.settle_startup_tasks().await;
+
+                        // Then everything else, concurrently — these touch
+                        // different subsystems and nothing here depends on
+                        // another's result. Serially, the two container stops
+                        // alone were 20s of Docker's default grace period.
+                        let web_terminal = async {
+                            if let Some(server) = web_terminal_server.lock().await.take() {
+                                server.stop();
+                            }
+                        };
+                        let stop_stt = async {
+                            if let Err(e) = docker::stt::stop_stt_container().await {
+                                log::warn!("Failed to stop the STT container on exit: {}", e);
+                            }
+                        };
+                        let stop_gateway = async {
+                            if let Err(e) = docker::gateway::stop_gateway_container().await {
+                                log::warn!("Failed to stop the model gateway on exit: {}", e);
+                            }
+                        };
+                        tokio::join!(
+                            web_terminal,
+                            stop_stt,
+                            stop_gateway,
+                            exec_manager.close_all_sessions(),
+                            auth_bridge.stop_all(),
+                            browser_view::manager().stop_all(),
+                        );
+                    };
+
+                    if tokio::time::timeout(SHUTDOWN_BUDGET, teardown).await.is_err() {
+                        log::warn!(
+                            "Shutdown exceeded {}s — exiting with teardown incomplete",
+                            SHUTDOWN_BUDGET.as_secs()
+                        );
                     }
-                    // Stop STT container
-                    let _ = docker::stt::stop_stt_container().await;
-                    // Close all exec sessions
-                    state.exec_manager.close_all_sessions().await;
+                    app_handle.exit(0);
                 });
             }
         })
@@ -154,7 +461,6 @@ pub fn run() {
             commands::docker_commands::check_image_exists,
             commands::docker_commands::build_image,
             commands::docker_commands::get_container_info,
-            commands::docker_commands::list_sibling_containers,
             // Projects
             commands::project_commands::list_projects,
             commands::project_commands::add_project,
@@ -164,31 +470,72 @@ pub fn run() {
             commands::project_commands::stop_project_container,
             commands::project_commands::rebuild_project_container,
             commands::project_commands::reconcile_project_statuses,
+            // Notes
+            commands::notes_commands::list_notes,
+            commands::notes_commands::save_note,
+            commands::notes_commands::delete_note,
+            // Container base-image migration
+            commands::migration_commands::get_container_staleness,
+            commands::migration_commands::migrate_project_to_base,
+            commands::migration_commands::confirm_migration,
+            commands::migration_commands::rollback_migration,
+            commands::migration_commands::get_migration_state,
+            // Auth bridge
+            commands::auth_bridge_commands::set_auth_bridge_enabled,
+            commands::auth_bridge_commands::get_auth_bridge_status,
+            // Browser view (Playwright dashboard pane)
+            browser_view::commands::set_browser_view_enabled,
+            browser_view::commands::get_browser_view_status,
+            browser_view::commands::check_browser_view_support,
+            browser_view::commands::install_browser_view_support,
+            browser_view::commands::install_browser_view_browser,
+            browser_view::commands::open_browser_view_popout,
+            browser_view::commands::close_browser_view_popout,
+            browser_view::commands::get_browser_view_popout_state,
+            browser_view::commands::set_browser_view_popout_always_on_top,
+            browser_view::commands::open_page_in_container_browser,
+            browser_view::commands::set_container_page_viewport,
+            browser_view::commands::get_container_page_state,
+            browser_view::commands::close_container_page,
+            browser_view::commands::set_browser_view_match_window,
+            browser_view::commands::get_browser_view_match_window,
+            // Shared Claude Code auth token
+            commands::auth_token_commands::acquire_claude_token,
+            commands::auth_token_commands::submit_claude_token_code,
+            commands::auth_token_commands::cancel_claude_token,
+            commands::auth_token_commands::has_claude_token,
+            commands::auth_token_commands::clear_claude_token,
+            commands::auth_token_commands::sweep_claude_token_snapshots,
             // Settings
             commands::settings_commands::get_settings,
             commands::settings_commands::update_settings,
             commands::settings_commands::pull_image,
             commands::settings_commands::detect_aws_config,
+            commands::settings_commands::inspect_ca_cert_path,
             commands::settings_commands::list_aws_profiles,
             commands::settings_commands::detect_host_timezone,
+            // Settings export/import
+            commands::settings_export_commands::export_settings,
+            commands::settings_export_commands::preview_settings_import,
+            commands::settings_export_commands::apply_settings_import,
             // Terminal
             commands::terminal_commands::open_terminal_session,
             commands::terminal_commands::terminal_input,
             commands::terminal_commands::terminal_resize,
             commands::terminal_commands::close_terminal_session,
             commands::terminal_commands::paste_image_to_terminal,
+            commands::terminal_commands::upload_host_file_to_terminal,
             commands::terminal_commands::start_audio_bridge,
             commands::terminal_commands::send_audio_data,
             commands::terminal_commands::stop_audio_bridge,
             // Files
             commands::file_commands::list_container_files,
+            commands::file_commands::download_container_backup,
             commands::file_commands::download_container_file,
-            commands::file_commands::upload_file_to_container,
-            // MCP
-            commands::mcp_commands::list_mcp_servers,
-            commands::mcp_commands::add_mcp_server,
-            commands::mcp_commands::update_mcp_server,
-            commands::mcp_commands::remove_mcp_server,
+            commands::file_commands::upload_files_to_container,
+            commands::file_commands::read_container_file,
+            commands::file_commands::rename_container_path,
+            commands::file_commands::create_container_directory,
             // AWS
             commands::aws_commands::aws_sso_refresh,
             // Updates
@@ -197,6 +544,9 @@ pub fn run() {
             commands::update_commands::check_image_update,
             // Help
             commands::help_commands::get_help_content,
+            // Install helper
+            commands::install_helper_commands::detect_install_options,
+            commands::install_helper_commands::run_docker_install,
             // Web Terminal
             commands::web_terminal_commands::start_web_terminal,
             commands::web_terminal_commands::stop_web_terminal,
@@ -209,7 +559,398 @@ pub fn run() {
             commands::stt_commands::build_stt_image,
             commands::stt_commands::pull_stt_image,
             commands::stt_commands::transcribe_audio,
+            // Model gateway (LiteLLM)
+            commands::gateway_commands::get_gateway_status,
+            commands::gateway_commands::start_gateway,
+            commands::gateway_commands::stop_gateway,
+            commands::gateway_commands::check_gateway_health,
+            commands::gateway_commands::build_gateway_image,
+            commands::gateway_commands::pull_gateway_image,
+            commands::gateway_commands::set_gateway_api_key,
+            commands::gateway_commands::clear_gateway_api_key,
+            commands::gateway_commands::get_gateway_auth_token,
+            commands::gateway_commands::regenerate_gateway_auth_token,
+            // Container introspection (sessions / capabilities / scheduler)
+            commands::inspect_commands::list_claude_sessions,
+            commands::inspect_commands::resume_session_command,
+            commands::inspect_commands::list_container_capabilities,
+            commands::inspect_commands::list_scheduled_tasks,
+            commands::inspect_commands::add_scheduled_task,
+            commands::inspect_commands::update_scheduled_task,
+            commands::inspect_commands::get_scheduled_task_log,
+            commands::inspect_commands::set_scheduled_task_enabled,
+            commands::inspect_commands::run_scheduled_task_now,
+            commands::inspect_commands::remove_scheduled_task,
+            commands::inspect_commands::get_scheduler_notifications,
+            commands::inspect_commands::clear_scheduler_notifications,
         ])
         .run(tauri::generate_context!())
         .expect("error while running tauri application");
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::AtomicUsize;
+
+    /// Drives the retry loop under a paused clock, so the real backoff schedule
+    /// is exercised without waiting for it.
+    async fn run_autostart(
+        cancel: watch::Receiver<bool>,
+        outcomes: Vec<Result<(), String>>,
+    ) -> usize {
+        let calls = Arc::new(AtomicUsize::new(0));
+        let counter = calls.clone();
+        let outcomes = Arc::new(Mutex::new(outcomes.into_iter()));
+        autostart_with_retry("test", cancel, move || {
+            let counter = counter.clone();
+            let outcomes = outcomes.clone();
+            async move {
+                counter.fetch_add(1, Ordering::SeqCst);
+                outcomes
+                    .lock()
+                    .unwrap()
+                    .next()
+                    .unwrap_or(Err("still down".to_string()))
+            }
+        })
+        .await;
+        calls.load(Ordering::SeqCst)
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn a_working_autostart_runs_exactly_once() {
+        let (_tx, rx) = watch::channel(false);
+        assert_eq!(run_autostart(rx, vec![Ok(())]).await, 1);
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn an_autostart_that_beat_docker_to_readiness_recovers() {
+        // The regression: Docker not being up yet used to cost the whole
+        // session — gateway down, STT down, and nothing ever retried.
+        let (_tx, rx) = watch::channel(false);
+        let calls = run_autostart(
+            rx,
+            vec![
+                Err("daemon not running".to_string()),
+                Err("daemon not running".to_string()),
+                Ok(()),
+            ],
+        )
+        .await;
+        assert_eq!(calls, 3);
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn a_permanently_failing_autostart_gives_up_rather_than_looping_forever() {
+        let (_tx, rx) = watch::channel(false);
+        assert_eq!(
+            run_autostart(rx, vec![]).await,
+            AUTOSTART_DELAYS.len(),
+            "should attempt once per backoff step and then stop"
+        );
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn a_quick_quit_stops_the_retries_before_they_start() {
+        // Quitting before the first attempt must not leave a task that creates
+        // and starts a container after teardown has already run.
+        let (tx, rx) = watch::channel(false);
+        tx.send(true).unwrap();
+        assert_eq!(run_autostart(rx, vec![Ok(())]).await, 0);
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn cancelling_between_attempts_stops_the_retries() {
+        let (tx, rx) = watch::channel(false);
+        let calls = Arc::new(AtomicUsize::new(0));
+        let counter = calls.clone();
+        autostart_with_retry("test", rx, move || {
+            let counter = counter.clone();
+            let tx = tx.clone();
+            async move {
+                counter.fetch_add(1, Ordering::SeqCst);
+                // The app starts quitting while this attempt is in flight.
+                let _ = tx.send(true);
+                Err("daemon not running".to_string())
+            }
+        })
+        .await;
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+    }
+
+    #[test]
+    fn shutdown_begins_exactly_once() {
+        // `CloseRequested` fires again when our own `exit(0)` unwinds the
+        // window; teardown must not start a second time.
+        let lifecycle = Lifecycle::new();
+        assert!(!lifecycle.is_shutting_down());
+        assert!(lifecycle.begin_shutdown());
+        assert!(lifecycle.is_shutting_down());
+        assert!(!lifecycle.begin_shutdown());
+    }
+
+    #[tokio::test]
+    async fn beginning_shutdown_notifies_already_running_startup_tasks() {
+        let lifecycle = Lifecycle::new();
+        let mut cancel = lifecycle.cancellation();
+        assert!(!*cancel.borrow());
+        lifecycle.begin_shutdown();
+        assert!(cancel.changed().await.is_ok());
+        assert!(*cancel.borrow());
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn a_startup_task_that_ignores_cancellation_is_abandoned_not_awaited() {
+        // The budget is what keeps a wedged auto-start from turning quit into a
+        // multi-minute freeze.
+        let lifecycle = Lifecycle::new();
+        lifecycle.track(tauri::async_runtime::spawn(async {
+            tokio::time::sleep(Duration::from_secs(600)).await;
+        }));
+        lifecycle.begin_shutdown();
+        let started = tokio::time::Instant::now();
+        lifecycle.settle_startup_tasks().await;
+        assert!(started.elapsed() <= STARTUP_CANCEL_BUDGET + Duration::from_secs(1));
+    }
+
+    /// The capability file is the app's entire IPC attack surface, and it is
+    /// data — nothing in `cargo test` reads it, so a widened grant lands with a
+    /// green suite. This is what noticing looks like.
+    ///
+    /// It exists because `core:default` was granted for months. That alias
+    /// pulls in `core:image:default` → `allow-from-path`, which is an
+    /// unconditional `std::fs::read` of any host path with no scope check, and
+    /// nothing in the frontend has ever imported `@tauri-apps/api/image`.
+    /// Every `#[tauri::command]` is registered, and every registration names a
+    /// command that exists.
+    ///
+    /// This is the shape of the bug that caused the original OAuth-callback
+    /// complaint: `set_auth_bridge_enabled` existed, worked, and had a typed
+    /// frontend wrapper — with **zero call sites**. The switch the docs told
+    /// users to flip was never wired to anything, so the bridge stayed off and
+    /// every login callback was refused. Nothing failed; the feature was simply
+    /// absent, and no test noticed because both halves compiled.
+    ///
+    /// The reverse direction matters too, and for a sharper reason: a command
+    /// that is registered but reachable from nowhere is still IPC surface a
+    /// compromised webview can call. `list_sibling_containers` — which returned
+    /// every container on the daemon, including the user's unrelated work —
+    /// sat in exactly that state, and this test is what found it. It has since
+    /// been removed at all four levels: registration, command, docker helper,
+    /// and the frontend wrapper and type.
+    ///
+    /// So this asserts the two lists agree, and leaves *deciding* what belongs
+    /// on them to a human. It cannot see frontend call sites; `tsc` and the
+    /// vitest suite cover that side.
+    #[test]
+    fn every_command_is_registered_exactly_once() {
+        use std::collections::BTreeSet;
+
+        let mut defined: BTreeSet<String> = BTreeSet::new();
+
+        // Walk the source tree for the command attribute and take the `fn` name
+        // that follows.
+        //
+        // The first version of this matched `line.trim() == "#[tauri::command]"`
+        // exactly and broke on the first non-`#` line. An audit got five real,
+        // compiling, unregistered commands past it — `#[tauri::command(async)]`,
+        // `#[tauri::command(rename_all = "snake_case")]`, a trailing comment,
+        // spaces in the path, and a bare `#[command]` after `use tauri::command`
+        // — plus `pub(crate) fn` and a `///` line between attribute and `fn`.
+        // Every one of those is a command the frontend could not call, which is
+        // the bug this test exists for, and the test stayed green.
+        //
+        // The asymmetry matters: confusion on the *definition* side is a silent
+        // pass, while on the *registration* side it fails loudly against
+        // legitimate code — and rustc already covers that direction. So this
+        // errs toward over-matching definitions.
+        fn collect(dir: &std::path::Path, out: &mut BTreeSet<String>) {
+            let Ok(entries) = std::fs::read_dir(dir) else { return };
+            for entry in entries.flatten() {
+                let path = entry.path();
+                if path.is_dir() {
+                    collect(&path, out);
+                } else if path.extension().is_some_and(|e| e == "rs") {
+                    let Ok(text) = std::fs::read_to_string(&path) else { continue };
+                    let lines: Vec<&str> = text.lines().collect();
+                    for (i, line) in lines.iter().enumerate() {
+                        let t = line.trim();
+                        // `#[tauri::command]`, `#[tauri::command(async)]`,
+                        // `#[tauri :: command]`, a bare `#[command]` under
+                        // `use tauri::command`, and any of those with a
+                        // trailing comment.
+                        let attr = t.strip_prefix("#[").map(|a| {
+                            a.split(']').next().unwrap_or("").replace(' ', "")
+                        });
+                        let is_command_attr = attr.is_some_and(|a| {
+                            a == "command" || a == "tauri::command"
+                                || a.starts_with("command(")
+                                || a.starts_with("tauri::command(")
+                        });
+                        if !is_command_attr {
+                            continue;
+                        }
+                        // Skip further attributes and doc comments rather than
+                        // giving up at the first line that is not an attribute.
+                        for next in lines.iter().skip(i + 1) {
+                            let t = next.trim();
+                            if t.starts_with('#') || t.starts_with("//") || t.is_empty() {
+                                continue;
+                            }
+                            // Any visibility, then `fn` or `async fn`.
+                            let after_vis = t
+                                .strip_prefix("pub(crate) ")
+                                .or_else(|| t.strip_prefix("pub(super) "))
+                                .or_else(|| t.strip_prefix("pub(in crate) "))
+                                .or_else(|| t.strip_prefix("pub "))
+                                .unwrap_or(t);
+                            let after_async =
+                                after_vis.strip_prefix("async ").unwrap_or(after_vis);
+                            if let Some(rest) = after_async.strip_prefix("fn ") {
+                                if let Some(name) = rest.split(['(', '<']).next() {
+                                    out.insert(name.trim().to_string());
+                                }
+                            }
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+        collect(
+            std::path::Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/src")),
+            &mut defined,
+        );
+
+        // The registration list, read from this file rather than from a macro
+        // expansion so the test does not depend on `generate_handler!`'s shape.
+        let this = include_str!("lib.rs");
+        let handler = this
+            .split_once("generate_handler![")
+            .and_then(|(_, rest)| rest.split_once("])"))
+            .map(|(inside, _)| inside)
+            .expect("lib.rs should contain a generate_handler! list");
+        // Line-based, not `split(',')`: the list is grouped under `// Docker`
+        // style comments, and splitting on commas glues each comment to the
+        // command that follows it. A `starts_with("//")` filter then drops that
+        // command — silently, and once per group.
+        let registered: BTreeSet<String> = handler
+            .lines()
+            .map(str::trim)
+            .filter(|l| !l.is_empty() && !l.starts_with("//"))
+            .filter_map(|l| {
+                l.trim_end_matches(',')
+                    .rsplit("::")
+                    .next()
+                    .map(|n| n.trim().to_string())
+            })
+            .filter(|n| !n.is_empty())
+            .collect();
+
+        assert!(
+            !defined.is_empty() && !registered.is_empty(),
+            "the scan found nothing — it has stopped testing anything (defined={}, registered={})",
+            defined.len(),
+            registered.len()
+        );
+
+        let unregistered: Vec<&String> = defined.difference(&registered).collect();
+        assert!(
+            unregistered.is_empty(),
+            "these commands exist but are not registered, so the frontend cannot call them: {:?}",
+            unregistered
+        );
+
+        let undefined: Vec<&String> = registered.difference(&defined).collect();
+        assert!(
+            undefined.is_empty(),
+            "these are registered but no `#[tauri::command]` defines them: {:?}",
+            undefined
+        );
+
+        // "exactly once" was in this test's name and not in its body: both
+        // sides were sets, so registering the same command twice in a
+        // hand-maintained 118-line list compiled, warned about nothing, and
+        // passed here.
+        let mut seen: Vec<&str> = Vec::new();
+        let mut duplicated: Vec<&str> = Vec::new();
+        for line in handler
+            .lines()
+            .map(str::trim)
+            .filter(|l| !l.is_empty() && !l.starts_with("//"))
+        {
+            if let Some(name) = line.trim_end_matches(',').rsplit("::").next() {
+                let name = name.trim();
+                if name.is_empty() {
+                    continue;
+                }
+                if seen.contains(&name) {
+                    duplicated.push(name);
+                } else {
+                    seen.push(name);
+                }
+            }
+        }
+        assert!(
+            duplicated.is_empty(),
+            "these are registered more than once: {:?}",
+            duplicated
+        );
+    }
+
+    #[test]
+    fn the_capability_grants_are_the_ones_that_were_reviewed() {
+        let raw = include_str!("../capabilities/default.json");
+        let parsed: serde_json::Value =
+            serde_json::from_str(raw).expect("capabilities/default.json must parse");
+        let listed: Vec<String> = parsed["permissions"]
+            .as_array()
+            .expect("a `permissions` array")
+            .iter()
+            .map(|p| match p {
+                // A scoped grant is an object; its identifier is what matters here.
+                serde_json::Value::Object(o) => o["identifier"]
+                    .as_str()
+                    .expect("a scoped grant needs an identifier")
+                    .to_string(),
+                other => other.as_str().expect("a grant is a string or an object").to_string(),
+            })
+            .collect();
+
+        let mut sorted = listed.clone();
+        sorted.sort();
+        let mut expected = vec![
+            "core:event:allow-listen",
+            "core:event:allow-unlisten",
+            "core:webview:allow-internal-toggle-devtools",
+            "dialog:allow-open",
+            "dialog:allow-save",
+            "opener:allow-open-url",
+        ];
+        expected.sort();
+        assert_eq!(
+            sorted, expected,
+            "the capability set changed. That is allowed — but it is the IPC \
+             surface a compromised webview can call, so update this list \
+             deliberately rather than to make the test pass."
+        );
+
+        // Belt and braces: the `*:default` aliases are the specific trap here,
+        // because they expand to a set the file never spells out. `store:*` in
+        // particular was an arbitrary host-file read/write primitive.
+        for grant in &listed {
+            assert!(
+                !grant.ends_with(":default"),
+                "{} is an alias — it expands to permissions this file does not \
+                 name. Enumerate them instead.",
+                grant
+            );
+            assert!(
+                !grant.starts_with("store:"),
+                "store:* is `PathBuf::push` against AppData, which an absolute \
+                 path discards: an arbitrary host-file read/write."
+            );
+        }
+    }
+}

app/src-tauri/src/logging.rs

@@ -1,6 +1,11 @@
 use std::fs;
 use std::path::PathBuf;
 
+/// The level the dispatch is built with, and the level restored by hand if
+/// installing it fails — see the failure branch in [`init`] for why that
+/// matters more than it looks.
+const LOG_LEVEL: log::LevelFilter = log::LevelFilter::Info;
+
 /// Returns the log directory path: `<data_dir>/triple-c/logs/`
 fn log_dir() -> Option<PathBuf> {
     dirs::data_dir().map(|d| d.join("triple-c").join("logs"))
@@ -33,7 +38,7 @@ pub fn init() {
                 message
             ))
         })
-        .level(log::LevelFilter::Info)
+        .level(LOG_LEVEL)
         .chain(std::io::stderr());
 
     if let Some((_path, file)) = &log_file_path {
@@ -41,7 +46,28 @@ pub fn init() {
     }
 
     if let Err(e) = dispatch.apply() {
-        eprintln!("Failed to initialise logger: {}", e);
+        // H2's other half. `fern::Dispatch::apply` calls `log::set_boxed_logger`
+        // and only then `log::set_max_level`, so a failure returns with the
+        // global filter still at its default, `LevelFilter::Off`. That is not
+        // merely "no log output": every `log::info!(…)` expands to
+        // `if Info <= max_level() { … }`, so at `Off` the macro never evaluates
+        // its own arguments. Anything a call site put in an argument list —
+        // a function call, an `await`, a side effect — silently stops
+        // happening, app-wide, because a logger could not be installed.
+        //
+        // Call sites must not put effects in log arguments (see the
+        // pre-migration scrub in `migration_commands.rs`), but "the whole
+        // program's log macros are dead and nothing said so" is its own
+        // hazard, so the level this dispatch was configured with is restored
+        // by hand. Nothing is listening — `log`'s default logger is a no-op —
+        // but the macros evaluate, and the one thing that *is* guaranteed to
+        // reach the user, the stderr line below, says what happened.
+        eprintln!(
+            "Failed to initialise logger: {}. Log output is disabled for this run; \
+             log macros still evaluate their arguments.",
+            e
+        );
+        log::set_max_level(LOG_LEVEL);
     }
 
     // Install a panic hook that writes to the log file so crashes are captured.
@@ -71,3 +97,40 @@ pub fn init() {
         log::info!("Logging to {}", path.display());
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_logger_that_could_not_be_installed_still_leaves_the_macros_evaluating() {
+        // H2: `log::info!(…)` expands to `if Info <= max_level() { … }`, so at
+        // `LevelFilter::Off` the arguments are never evaluated. `fern` returns
+        // before `set_max_level` when `apply()` fails, which leaves exactly
+        // that state — and a call site that folded an effect into an argument
+        // list then stops performing it, app-wide, because a log file could not
+        // be opened. The failure branch restores the level for that reason.
+        //
+        // Asserted on the level itself rather than by driving `init`, which
+        // installs a process-global logger and a panic hook and can only run
+        // once per process.
+        assert_ne!(LOG_LEVEL, log::LevelFilter::Off);
+
+        // The property that makes the above worth asserting, demonstrated
+        // against the macro itself: a side effect in an argument list runs only
+        // while the level admits the record.
+        let mut ran = false;
+        let effect = |v: &mut bool| {
+            *v = true;
+            0
+        };
+        let previous = log::max_level();
+        log::set_max_level(log::LevelFilter::Off);
+        log::info!("{}", effect(&mut ran));
+        assert!(!ran, "the premise is wrong: arguments evaluated at LevelFilter::Off");
+        log::set_max_level(LOG_LEVEL);
+        log::info!("{}", effect(&mut ran));
+        assert!(ran, "arguments did not evaluate at the level this module configures");
+        log::set_max_level(previous);
+    }
+}

app/src-tauri/src/main.rs

@@ -1,6 +1,136 @@
 // Prevents additional console window on Windows in release
 #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
 
+/// WebKitGTK's DMA-BUF renderer (its default accelerated-compositing path
+/// since 2.42) fails outright on some Mesa/driver/compositor combinations
+/// under Wayland, printing `Could not create default EGL display:
+/// EGL_BAD_PARAMETER. Aborting.` straight to stderr from WebKitGTK's own C
+/// code and killing the webview before Triple-C's own logging even starts —
+/// see triple-c#34, reported on CachyOS/Arch with Wayland.
+///
+/// Set unconditionally on Linux rather than gated on `WAYLAND_DISPLAY`: that
+/// variable is exported into an XWayland client's environment too, so a
+/// gate on it wouldn't even cleanly separate "Wayland" from "X11" — and
+/// there is no reliable heuristic at all for the actual variable that
+/// matters, which Mesa/driver/compositor combination is affected. This is
+/// the blunt instrument, chosen deliberately because the fallback is a real
+/// trade, not a free one: the terminal's `@xterm/addon-webgl` renderer
+/// (`TerminalView.tsx`) is the one surface in this app actually asking for
+/// GPU compositing, and it degrades to xterm's canvas renderer under this
+/// setting — slower on very heavy output, but the addon's own construction
+/// is already wrapped in a fallback (`WebGL not available` is a handled
+/// case, not a crash), so this is a real but graceful downgrade, traded
+/// against a startup abort that has no fallback at all.
+///
+/// Must be set before `triple_c_lib::run()` — GTK/WebKitGTK reads it at
+/// their own init time, which happens inside the Tauri builder that
+/// function calls into, not at binary load.
+///
+/// A user who has already set this themselves is left alone — with one
+/// correction. The earlier version of this function left *any* pre-set value
+/// alone, including `0`, on the assumption WebKitGTK reads the variable as a
+/// boolean. WebKitGTK reads it as presence-only, so `WEBKIT_DISABLE_DMABUF_
+/// RENDERER=0` disabled DMA-BUF exactly like `=1` did, and there was no value
+/// at all a user could set to get the accelerated path back: the escape hatch
+/// the comment described did not exist. `0`, `false` and empty are now treated
+/// as an explicit opt-out and the variable is *removed*, which is the only
+/// thing WebKitGTK reads as "enabled". The default is unchanged — unset still
+/// means disabled on Linux, so nobody who was not deliberately overriding this
+/// sees any difference.
+///
+/// That matters more than it looks, because the trade described above is not
+/// the trade actually being made. `@xterm/addon-webgl` does not fall back to
+/// the canvas renderer here: its constructor throws only when WebGL is
+/// *absent*, and with DMA-BUF disabled WebGL is still present — served by
+/// software rasterisation. So the addon loads happily and every terminal frame
+/// is rendered on the CPU and copied, which is slower than the canvas renderer
+/// this comment assumed it would degrade to, not faster. See
+/// `terminal_gpu_rendering` in `AppSettings` for the switch that decides
+/// whether the addon is loaded at all.
+///
+/// This env var also leaks to whatever the app spawns afterwards — notably
+/// a cold-launched default browser via the `opener` plugin's `xdg-open`
+/// call. Narrow in practice (an already-running browser just receives the
+/// URL; most non-WebKitGTK browsers ignore the variable entirely), but
+/// worth knowing before chasing the "links don't open" half of triple-c#34
+/// as a separate, unrelated cause.
+#[cfg(target_os = "linux")]
+const DMABUF_VAR: &str = "WEBKIT_DISABLE_DMABUF_RENDERER";
+
+/// What to do with `WEBKIT_DISABLE_DMABUF_RENDERER`, given whatever it is
+/// already set to. Split from the mutation so it can be tested without
+/// touching process-wide environment state from a parallel test runner.
+#[cfg(target_os = "linux")]
+#[derive(Debug, PartialEq, Eq)]
+enum DmabufAction {
+    /// Not set by the user — apply the workaround.
+    Disable,
+    /// Explicitly opted out. WebKitGTK reads presence, not value, so the only
+    /// way to express "enabled" is for the variable not to exist.
+    Remove,
+    /// Set to something meaning "disabled". Already what we want; leave it.
+    LeaveAlone,
+}
+
+#[cfg(target_os = "linux")]
+fn dmabuf_action(current: Option<&str>) -> DmabufAction {
+    match current {
+        None => DmabufAction::Disable,
+        Some(value) => match value.trim().to_ascii_lowercase().as_str() {
+            "" | "0" | "false" | "no" => DmabufAction::Remove,
+            _ => DmabufAction::LeaveAlone,
+        },
+    }
+}
+
+#[cfg(target_os = "linux")]
+fn apply_webkit_wayland_workaround() {
+    let current = std::env::var(DMABUF_VAR).ok();
+    match dmabuf_action(current.as_deref()) {
+        DmabufAction::Disable => std::env::set_var(DMABUF_VAR, "1"),
+        DmabufAction::Remove => std::env::remove_var(DMABUF_VAR),
+        DmabufAction::LeaveAlone => {}
+    }
+}
+
+#[cfg(all(test, target_os = "linux"))]
+mod tests {
+    use super::{dmabuf_action, DmabufAction};
+
+    #[test]
+    fn unset_gets_the_workaround() {
+        assert_eq!(dmabuf_action(None), DmabufAction::Disable);
+    }
+
+    #[test]
+    fn falsey_values_opt_out_by_removing_the_variable() {
+        // The bug this replaces: these all previously read as "user set it,
+        // leave it alone", and WebKitGTK then disabled DMA-BUF anyway because
+        // it only checks presence. There was no way to ask for the GPU path.
+        for value in ["0", "false", "no", "", "  0  ", "FALSE", "No"] {
+            assert_eq!(
+                dmabuf_action(Some(value)),
+                DmabufAction::Remove,
+                "{value:?} should opt out"
+            );
+        }
+    }
+
+    #[test]
+    fn other_values_are_left_alone() {
+        for value in ["1", "true", "yes", "anything"] {
+            assert_eq!(
+                dmabuf_action(Some(value)),
+                DmabufAction::LeaveAlone,
+                "{value:?} should be left alone"
+            );
+        }
+    }
+}
+
 fn main() {
+    #[cfg(target_os = "linux")]
+    apply_webkit_wayland_workaround();
+
     triple_c_lib::run()
 }

app/src-tauri/src/models/app_settings.rs

@@ -1,5 +1,6 @@
 use serde::{Deserialize, Serialize};
 
+use super::gateway_settings::GatewaySettings;
 use super::project::{ClaudeCodeSettings, EnvVar};
 
 fn default_true() -> bool {
@@ -32,6 +33,8 @@ pub struct GlobalAwsSettings {
     pub aws_profile: Option<String>,
     #[serde(default)]
     pub aws_region: Option<String>,
+    #[serde(default)]
+    pub default_model_id: Option<String>,
 }
 
 impl Default for GlobalAwsSettings {
@@ -40,14 +43,58 @@ impl Default for GlobalAwsSettings {
             aws_config_path: None,
             aws_profile: None,
             aws_region: None,
+            default_model_id: None,
         }
     }
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct GlobalOllamaSettings {
+    #[serde(default)]
+    pub base_url: Option<String>,
+    #[serde(default)]
+    pub default_model_id: Option<String>,
+    /// Global fallback for the `haiku` alias override. Blank means "use the
+    /// resolved model id", which is what makes background Claude Code calls
+    /// work against a server that only serves one model.
+    #[serde(default)]
+    pub default_haiku_model_id: Option<String>,
+}
+
+/// Global defaults for the llama.cpp (`llama-server`) backend.
+/// Mirrors [`GlobalOllamaSettings`]; used when the per-project field is blank.
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct GlobalLlamaCppSettings {
+    #[serde(default)]
+    pub base_url: Option<String>,
+    #[serde(default)]
+    pub default_model_id: Option<String>,
+    #[serde(default)]
+    pub default_haiku_model_id: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct GlobalOpenAiCompatibleSettings {
+    #[serde(default)]
+    pub base_url: Option<String>,
+    #[serde(default)]
+    pub default_model_id: Option<String>,
+    #[serde(default)]
+    pub default_haiku_model_id: Option<String>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AppSettings {
     #[serde(default)]
     pub default_ssh_key_path: Option<String>,
+    /// Path to the organisation's root CA — a single certificate file or a
+    /// directory of them. Mounted read-only into every container, which then
+    /// installs it into the system trust store, Node's `NODE_EXTRA_CA_CERTS`,
+    /// Python's `REQUESTS_CA_BUNDLE`/`SSL_CERT_FILE` and Chrome's NSS database.
+    /// Required when the host sits behind a TLS-terminating corporate proxy.
+    /// Overridden per project by `Project::ca_cert_path`.
+    #[serde(default)]
+    pub ca_cert_path: Option<String>,
     #[serde(default)]
     pub default_git_user_name: Option<String>,
     #[serde(default)]
@@ -60,6 +107,12 @@ pub struct AppSettings {
     pub custom_image_name: Option<String>,
     #[serde(default)]
     pub global_aws: GlobalAwsSettings,
+    #[serde(default)]
+    pub global_ollama: GlobalOllamaSettings,
+    #[serde(default)]
+    pub global_llamacpp: GlobalLlamaCppSettings,
+    #[serde(default)]
+    pub global_openai_compatible: GlobalOpenAiCompatibleSettings,
     #[serde(default = "default_global_instructions")]
     pub global_claude_instructions: Option<String>,
     #[serde(default)]
@@ -79,7 +132,29 @@ pub struct AppSettings {
     #[serde(default)]
     pub stt: SttSettings,
     #[serde(default)]
+    pub gateway: GatewaySettings,
+    #[serde(default)]
     pub global_claude_code_settings: Option<ClaudeCodeSettings>,
+    /// Whether the terminal loads `@xterm/addon-webgl`.
+    ///
+    /// `None` is "auto", and auto is not the same answer on every platform.
+    /// On Linux the app disables WebKitGTK's DMA-BUF renderer at startup (see
+    /// `apply_webkit_wayland_workaround` in `main.rs`, and triple-c#34), which
+    /// does not remove WebGL — it leaves it backed by software rasterisation.
+    /// The addon therefore loads successfully and then renders every frame on
+    /// the CPU, which is slower than the canvas renderer it would otherwise
+    /// have fallen back to. So auto means enabled on macOS and Windows, and
+    /// disabled on Linux.
+    ///
+    /// `Some(true)` / `Some(false)` force it either way on any platform. A
+    /// Linux user running X11, or one whose driver stack is unaffected, can
+    /// turn it back on; anyone seeing terminal lag can turn it off without
+    /// waiting for a release. Deliberately `Option<bool>` rather than `bool`:
+    /// the zero value has to mean "we choose", not "off", or every existing
+    /// settings file would silently pin the answer at whatever the default was
+    /// the day it was written.
+    #[serde(default)]
+    pub terminal_gpu_rendering: Option<bool>,
 }
 
 fn default_stt_model() -> String {
@@ -150,12 +225,16 @@ impl Default for AppSettings {
     fn default() -> Self {
         Self {
             default_ssh_key_path: None,
+            ca_cert_path: None,
             default_git_user_name: None,
             default_git_user_email: None,
             docker_socket_path: None,
             image_source: ImageSource::default(),
             custom_image_name: None,
             global_aws: GlobalAwsSettings::default(),
+            global_ollama: GlobalOllamaSettings::default(),
+            global_llamacpp: GlobalLlamaCppSettings::default(),
+            global_openai_compatible: GlobalOpenAiCompatibleSettings::default(),
             global_claude_instructions: default_global_instructions(),
             global_custom_env_vars: Vec::new(),
             auto_check_updates: true,
@@ -165,7 +244,9 @@ impl Default for AppSettings {
             dismissed_image_digest: None,
             web_terminal: WebTerminalSettings::default(),
             stt: SttSettings::default(),
+            gateway: GatewaySettings::default(),
             global_claude_code_settings: None,
+            terminal_gpu_rendering: None,
         }
     }
 }

app/src-tauri/src/models/gateway_settings.rs

@@ -0,0 +1,99 @@
+//! Settings and status for the **model gateway** — a LiteLLM proxy container
+//! Triple-C runs as a sibling of the project containers.
+//!
+//! Claude Code speaks only the Anthropic Messages API (`POST
+//! ${ANTHROPIC_BASE_URL}/v1/messages`). OpenAI has no such route, so an OpenAI
+//! key cannot drive Claude Code directly. The gateway exposes `/v1/messages`
+//! in Anthropic format and translates each call to the configured provider,
+//! which is what turns "OpenAI Compatible" from *bring your own proxy* into
+//! something Triple-C manages itself.
+//!
+//! Nothing secret lives in this module. The provider API key and the gateway's
+//! own master key are held in the OS keychain (see `storage::secure`); what is
+//! persisted to `settings.json` is only the non-secret shape of the config.
+
+use serde::{Deserialize, Serialize};
+
+/// LiteLLM's own default port, and the one the existing "OpenAI Compatible"
+/// placeholder text already suggests.
+pub fn default_gateway_port() -> u16 {
+    4000
+}
+
+fn default_gateway_provider() -> String {
+    "openai".to_string()
+}
+
+/// One entry of LiteLLM's `model_list`.
+///
+/// `name` is the friendly handle a project puts in its model field — it is what
+/// Claude Code sends as the `model` of a `/v1/messages` request. `model_id` is
+/// the provider-side id. The gateway config composes them as
+/// `<provider>/<model_id>`, which is why the shape stays generic across
+/// providers instead of hard-coding OpenAI.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub struct GatewayModel {
+    /// Friendly name projects use (e.g. `gpt-5.1`).
+    pub name: String,
+    /// Provider-side model id (e.g. `gpt-5.1`).
+    pub model_id: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct GatewaySettings {
+    /// Auto-start the gateway container with the app.
+    #[serde(default)]
+    pub enabled: bool,
+    /// Host port the gateway is published on.
+    #[serde(default = "default_gateway_port")]
+    pub port: u16,
+    /// LiteLLM provider prefix — `openai`, `azure`, `gemini`, `groq`, …
+    #[serde(default = "default_gateway_provider")]
+    pub provider: String,
+    /// Optional provider base URL override (Azure endpoints, proxies, …).
+    #[serde(default)]
+    pub api_base: Option<String>,
+    /// Models the gateway should serve.
+    #[serde(default)]
+    pub models: Vec<GatewayModel>,
+}
+
+impl Default for GatewaySettings {
+    fn default() -> Self {
+        Self {
+            enabled: false,
+            port: default_gateway_port(),
+            provider: default_gateway_provider(),
+            api_base: None,
+            models: Vec::new(),
+        }
+    }
+}
+
+impl GatewaySettings {
+    /// Models with both fields filled in. Half-typed rows in the UI must not
+    /// reach the generated YAML.
+    pub fn valid_models(&self) -> Vec<&GatewayModel> {
+        self.models
+            .iter()
+            .filter(|m| !m.name.trim().is_empty() && !m.model_id.trim().is_empty())
+            .collect()
+    }
+}
+
+/// What the settings UI needs to know about the gateway. Deliberately carries
+/// **no** secret: `has_api_key` is a boolean, not the key.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct GatewayStatus {
+    pub container_exists: bool,
+    pub running: bool,
+    pub port: u16,
+    pub image_exists: bool,
+    /// Number of fully-specified models in the current settings.
+    pub model_count: usize,
+    /// Whether a provider API key is present in the keychain.
+    pub has_api_key: bool,
+    /// The value a project should use for its base URL. See
+    /// `docker::gateway::gateway_base_url`.
+    pub base_url: String,
+}

app/src-tauri/src/models/mcp_server.rs

@@ -1,70 +0,0 @@
-use serde::{Deserialize, Serialize};
-use std::collections::HashMap;
-
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "snake_case")]
-pub enum McpTransportType {
-    Stdio,
-    #[serde(alias = "sse")]
-    Http,
-}
-
-impl Default for McpTransportType {
-    fn default() -> Self {
-        Self::Stdio
-    }
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct McpServer {
-    pub id: String,
-    pub name: String,
-    #[serde(default)]
-    pub transport_type: McpTransportType,
-    pub command: Option<String>,
-    #[serde(default)]
-    pub args: Vec<String>,
-    #[serde(default)]
-    pub env: HashMap<String, String>,
-    pub url: Option<String>,
-    #[serde(default)]
-    pub headers: HashMap<String, String>,
-    #[serde(default)]
-    pub docker_image: Option<String>,
-    #[serde(default)]
-    pub container_port: Option<u16>,
-    pub created_at: String,
-    pub updated_at: String,
-}
-
-impl McpServer {
-    pub fn new(name: String) -> Self {
-        let now = chrono::Utc::now().to_rfc3339();
-        Self {
-            id: uuid::Uuid::new_v4().to_string(),
-            name,
-            transport_type: McpTransportType::default(),
-            command: None,
-            args: Vec::new(),
-            env: HashMap::new(),
-            url: None,
-            headers: HashMap::new(),
-            docker_image: None,
-            container_port: None,
-            created_at: now.clone(),
-            updated_at: now,
-        }
-    }
-
-    pub fn is_docker(&self) -> bool {
-        self.docker_image.is_some()
-    }
-
-    pub fn mcp_container_name(&self) -> String {
-        format!("triple-c-mcp-{}", self.id)
-    }
-
-    pub fn effective_container_port(&self) -> u16 {
-        self.container_port.unwrap_or(3000)
-    }
-}

app/src-tauri/src/models/migration.rs

@@ -0,0 +1,292 @@
+//! Contract types for **container base-image migration**.
+//!
+//! ## Why this exists
+//!
+//! A project's container is created from `triple-c-snapshot-<id>:latest`
+//! whenever that image exists, and every recreation re-commits it. Nothing ever
+//! moved a project back onto a *newer base image*: `container_needs_recreation`
+//! compared the container's actual image against the `triple-c.image` label that
+//! `create_container` wrote from the very image it created from — a tautology
+//! that could never fire. So a project stayed pinned to its own snapshot
+//! lineage forever and never picked up base-image fixes (a new `socat`, a new
+//! `/usr/local/bin` shim, security updates). The only escape was Reset, which
+//! deletes both named volumes and takes the login, the skills and every session
+//! transcript with it.
+//!
+//! Migration is the non-destructive alternative: recreate the container from the
+//! current base, then replay onto it the small set of things the base does not
+//! carry, and leave the volumes strictly alone.
+//!
+//! ## What actually needs replaying
+//!
+//! `/home/claude` is the named volume `triple-c-home-<id>`, with
+//! `/home/claude/.claude` nested inside it. The image's own `/home/claude` is
+//! **seed-only** — once the volume is mounted the image's copy is masked
+//! permanently. So Claude Code itself (it installs to `~/.local/bin`), cargo,
+//! uv, ruff, the OAuth login, `~/.claude.json`, skills, transcripts, scheduler
+//! tasks and SSH keys all re-attach for free across an image swap.
+//!
+//! What is genuinely lost is confined to the container's writable layer:
+//! root-level `apt` installs, `npm -g` packages (npm's prefix is `/usr`),
+//! `/usr/local`, `/opt`, `/srv`, anything under `/workspace` that is not on a
+//! bind mount — and **`/var`**. The first four are what [`MigrationOptions`]
+//! can replay. `/var` is not, and that gap is deliberate rather than an
+//! oversight, so it is stated here rather than glossed over:
+//!
+//! Service state lives in `/var/lib/<service>` and `/var/www`. Replaying the
+//! apt delta reinstalls `postgresql` onto the new base and hands back an
+//! **empty** cluster; the old one is gone with the writable layer. The
+//! ordinary recreate path does not have this problem, because it creates from
+//! the project's own snapshot and `/var` rides along — so a silent migration
+//! would be *more* destructive than the thing it is sold as a safer
+//! alternative to.
+//!
+//! Copying a live database's files out with `tar` and unpacking them onto a
+//! different base's version of the same package is not a fix; it is a
+//! corruption risk wearing a fix's clothes. So the answer is disclosure:
+//! [`crate::docker::migration::unpreserved_data`] finds the data-bearing
+//! subtrees under `/var` that the base does not ship, and
+//! [`ContainerStaleness::unpreserved_data`] carries them into the pre-flight,
+//! where the user is told to back them up before anything is touched.
+//!
+//! ## Serde
+//!
+//! Plain snake_case, matching every other IPC struct in this crate
+//! (`ContainerInfo`, `ClaudeSession`, …) and `app/src/lib/types.ts`.
+
+use serde::{Deserialize, Serialize};
+
+/// How a finished migration attempt ended.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MigrationPhase {
+    /// The container now runs on the current base and everything requested was
+    /// replayed.
+    Succeeded,
+    /// The container now runs on the current base, but at least one package or
+    /// path could not be replayed. Deliberately distinct from `Failed`: one
+    /// missing apt package must never cost the user the whole migration.
+    Partial,
+    /// The migration could not complete. If the container had already been
+    /// swapped, an automatic rollback was attempted — check
+    /// [`MigrationReport::rollback_available`] and the message.
+    Failed,
+    /// The migration was undone; the container is back on its pre-migration
+    /// snapshot image.
+    RolledBack,
+}
+
+/// One package that could not be replayed onto the new base.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PackageFailure {
+    pub name: String,
+    /// Trimmed tail of the package manager's own error output.
+    pub reason: String,
+}
+
+/// A data-bearing subtree the migration will destroy and cannot put back.
+///
+/// See [`crate::docker::migration::unpreserved_data`]. Surfaced in the
+/// pre-flight so the user can take a backup first; never copied.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct UnpreservedData {
+    /// Absolute path of the directory, e.g. `/var/lib/postgresql`.
+    pub path: String,
+    /// Total size of the non-package files beneath it.
+    pub bytes: u64,
+    /// How many non-package files it holds.
+    pub file_count: u32,
+}
+
+/// Everything the UI needs to decide whether a project is worth migrating, and
+/// to explain to the user what migrating would actually change.
+///
+/// A field being empty always means "nothing found", never "not checked" —
+/// [`ContainerStaleness::probe_error`] is the single place a failed inspection
+/// is reported.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct ContainerStaleness {
+    /// The container's lineage is not the current base image.
+    /// Always `false` when `known` is `false` — an unknown lineage is not a
+    /// claim of staleness.
+    pub stale: bool,
+    /// Whether the lineage could be established at all. `false` means the
+    /// container (or its snapshot image) predates the `triple-c.base-image-id`
+    /// label, i.e. **"unknown, probe instead"** — never "stale".
+    pub known: bool,
+    /// Image ID of the base this container's lineage descends from.
+    pub base_image_id: Option<String>,
+    /// Image ID of the base image currently configured in settings.
+    pub current_base_image_id: Option<String>,
+    /// `Created` timestamp of the project's snapshot image, RFC 3339.
+    pub snapshot_created_at: Option<String>,
+    /// Concrete paths the current base ships that this container does not,
+    /// e.g. `/usr/bin/socat`.
+    pub missing_paths: Vec<String>,
+    /// Human labels for the same, e.g. `"Auth bridge tunnel (socat)"`.
+    pub missing_features: Vec<String>,
+    /// `apt-mark showmanual` in the container minus the base's own set — the
+    /// packages a migration would replay.
+    pub apt_delta: Vec<String>,
+    /// Globally-installed npm packages the base does not ship.
+    pub npm_global_delta: Vec<String>,
+    /// Non-dpkg-owned paths under the verbatim-copy roots that would be carried
+    /// across. Empty when nothing user-authored was found.
+    pub verbatim_paths: Vec<String>,
+    /// Data-bearing subtrees under `/var` that a migration **destroys and
+    /// cannot restore** — a database's files, a served site. Empty on an
+    /// ordinary container; when it is not, the pre-flight has to say so before
+    /// anything is touched. See [`UnpreservedData`].
+    #[serde(default)]
+    pub unpreserved_data: Vec<UnpreservedData>,
+    /// dpkg packages the current base carries at a different version than this
+    /// container does. A rough "how much security drift" number, not a promise
+    /// that every one of them is newer.
+    pub outdated_package_count: u32,
+    /// Set when the container/image could not be inspected. Everything else is
+    /// then at its default.
+    pub probe_error: Option<String>,
+}
+
+/// What a migration should replay. All three default to off so that
+/// `MigrationOptions::default()` is the minimal, fastest migration.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct MigrationOptions {
+    /// Replay the apt and `npm -g` deltas onto the new base.
+    #[serde(default)]
+    pub replay_packages: bool,
+    /// Copy the verbatim payload (`/usr/local`, `/opt`, `/srv`, and the
+    /// non-bind-mounted parts of `/workspace`) onto the new base.
+    #[serde(default)]
+    pub copy_paths: bool,
+    /// Keep the `:pre-migration-<ts>` rollback tag after the migration reports
+    /// success. Costs the full size of the old snapshot image (snapshots share
+    /// almost no layers with the current base) but makes rollback instant.
+    #[serde(default)]
+    pub keep_rollback: bool,
+}
+
+/// The outcome of one migration attempt.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct MigrationReport {
+    pub phase: MigrationPhase,
+    pub packages_requested: Vec<String>,
+    pub packages_installed: Vec<String>,
+    pub packages_failed: Vec<PackageFailure>,
+    pub paths_copied: Vec<String>,
+    /// Human labels for base features the container gained, e.g.
+    /// `"Auth bridge tunnel (socat)"`.
+    pub features_restored: Vec<String>,
+    /// A `:pre-migration-<ts>` image tag still exists, so
+    /// `rollback_migration` can put the old system layer back.
+    pub rollback_available: bool,
+    /// One paragraph fit to show the user verbatim.
+    pub message: String,
+}
+
+impl MigrationReport {
+    /// A report for a migration that never got past pre-flight. Nothing was
+    /// touched, so there is nothing to roll back.
+    pub fn failed_preflight(message: impl Into<String>) -> Self {
+        Self {
+            phase: MigrationPhase::Failed,
+            packages_requested: Vec::new(),
+            packages_installed: Vec::new(),
+            packages_failed: Vec::new(),
+            paths_copied: Vec::new(),
+            features_restored: Vec::new(),
+            rollback_available: false,
+            message: message.into(),
+        }
+    }
+}
+
+/// What a migration decided to do, frozen at pre-flight time.
+///
+/// Persisted with the state because a **resume** cannot recompute it: by the
+/// time the app comes back up the container has already been replaced by one
+/// created from the base, so its apt/npm sets *are* the base's and the deltas
+/// would come out empty.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+pub struct MigrationPlan {
+    pub apt_packages: Vec<String>,
+    pub npm_packages: Vec<String>,
+    pub verbatim_paths: Vec<String>,
+    /// Base-image paths the old container lacked, so the finished migration can
+    /// report which of them it actually gained.
+    pub missing_paths: Vec<String>,
+    /// What the pre-flight found under `/var` that the migration would destroy.
+    /// Frozen here so the finished report can name it even though the container
+    /// it was measured on no longer exists.
+    #[serde(default)]
+    pub unpreserved_data: Vec<UnpreservedData>,
+}
+
+/// Persisted, host-side migration state. Written **before** anything
+/// destructive happens and removed on confirm or rollback, so a crash at any
+/// point leaves a record of what was in flight.
+///
+/// `phase` is a free-form string rather than [`MigrationPhase`] because it also
+/// carries the *in-flight* phases, which are not outcomes:
+///
+/// | `phase` | Meaning | Offered next |
+/// |---|---|---|
+/// | `in-progress` | A migration is running right now | — |
+/// | `interrupted` | The app died after the container swap | resume, rollback |
+/// | `awaiting-confirmation` | Migration finished; rollback still possible | confirm, rollback |
+///
+/// See [`MIGRATION_PHASE_IN_PROGRESS`] and friends.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct MigrationState {
+    pub phase: String,
+    /// Image ID of the snapshot the project was on before the swap.
+    pub from_image_id: Option<String>,
+    /// Image ID of the base being migrated to.
+    pub to_base_id: Option<String>,
+    /// RFC 3339.
+    pub started_at: String,
+    /// Present once the attempt produced one.
+    #[serde(default)]
+    pub report: Option<MigrationReport>,
+    /// The `:pre-migration-<ts>` tag holding the old system layer, if one was
+    /// created. `rollback_migration` retags this back to `:latest`.
+    #[serde(default)]
+    pub rollback_image: Option<String>,
+    /// Host path of the staged verbatim payload tar, if one was staged.
+    #[serde(default)]
+    pub staging_path: Option<String>,
+    /// The options the attempt was started with, so a resume replays the same
+    /// things the user originally asked for.
+    #[serde(default)]
+    pub options: MigrationOptions,
+    /// The frozen pre-flight plan. See [`MigrationPlan`].
+    #[serde(default)]
+    pub plan: Option<MigrationPlan>,
+}
+
+/// A migration is running in this process right now.
+pub const MIGRATION_PHASE_IN_PROGRESS: &str = "in-progress";
+/// The app died after the container swap but before the final commit.
+pub const MIGRATION_PHASE_INTERRUPTED: &str = "interrupted";
+/// The migration finished; the user has not yet confirmed or rolled back.
+pub const MIGRATION_PHASE_AWAITING: &str = "awaiting-confirmation";
+
+impl MigrationState {
+    pub fn new(
+        from_image_id: Option<String>,
+        to_base_id: Option<String>,
+        options: MigrationOptions,
+    ) -> Self {
+        Self {
+            phase: MIGRATION_PHASE_IN_PROGRESS.to_string(),
+            from_image_id,
+            to_base_id,
+            started_at: chrono::Utc::now().to_rfc3339(),
+            report: None,
+            rollback_image: None,
+            staging_path: None,
+            options,
+            plan: None,
+        }
+    }
+}

app/src-tauri/src/models/mod.rs

@@ -1,11 +1,17 @@
-pub mod project;
-pub mod container_config;
 pub mod app_settings;
+pub mod container_config;
+pub mod gateway_settings;
+pub mod migration;
+pub mod note;
+pub mod project;
+pub mod settings_export;
 pub mod update_info;
-pub mod mcp_server;
 
-pub use project::*;
-pub use container_config::*;
 pub use app_settings::*;
+pub use container_config::*;
+pub use gateway_settings::*;
+pub use migration::*;
+pub use note::*;
+pub use project::*;
+pub use settings_export::*;
 pub use update_info::*;
-pub use mcp_server::*;

app/src-tauri/src/models/note.rs

@@ -0,0 +1,34 @@
+use serde::{Deserialize, Serialize};
+
+/// One note. A scratchpad entry the user can also fire at a running Claude
+/// session.
+///
+/// Deliberately has no `kind`/`type` field. What makes a note "for the agent"
+/// is that the user pressed Send, not a mode chosen when it was written — a
+/// classification decision at writing time is one the user is least willing to
+/// make, and it would turn one pane into two features.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct Note {
+    pub id: String,
+    pub title: String,
+    pub body: String,
+    /// Pinned notes sort first, then by `updated_at` descending.
+    #[serde(default)]
+    pub pinned: bool,
+    pub created_at: String,
+    pub updated_at: String,
+}
+
+impl Note {
+    pub fn new(title: String, body: String) -> Self {
+        let now = chrono::Utc::now().to_rfc3339();
+        Self {
+            id: uuid::Uuid::new_v4().to_string(),
+            title,
+            body,
+            pinned: false,
+            created_at: now.clone(),
+            updated_at: now,
+        }
+    }
+}

app/src-tauri/src/models/project.rs

@@ -1,3 +1,5 @@
+use std::collections::HashMap;
+
 use serde::{Deserialize, Serialize};
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
@@ -6,6 +8,100 @@ pub struct EnvVar {
     pub value: String,
 }
 
+/// Whether `key` is a name a shell will read back as an ordinary variable:
+/// `[A-Za-z_][A-Za-z0-9_]*`.
+///
+/// ## Why a charset rule, and not just the reserved-name list
+///
+/// `docker::container::is_reserved_env_key` answers a different question — "is
+/// this one of the names Triple-C manages itself" — and nothing anywhere asked
+/// what the *characters* were. A key is joined into `KEY=VALUE` and handed to
+/// the daemon, which puts it in the container's environment verbatim, so a name
+/// that is not an identifier travels through unchallenged.
+///
+/// The one that matters is `BASH_FUNC_name%%`, bash's wire format for an
+/// exported shell function: bash imports those at startup and the *body* is the
+/// value. Today that is latent rather than live — the image's `/bin/sh` is
+/// dash, which does not import them, and an auditor confirmed the vector fires
+/// under `bash -c` and not under `sh -c` in the shipped image. But the
+/// pre-commit scrub runs `/bin/sh -c` **as root**, `/bin/sh` is whatever
+/// `ubuntu:24.04` points it at, and nothing pins that. One base-image change,
+/// or one call site spelled `bash`, turns a stored project setting into root
+/// code execution inside the container at commit time.
+///
+/// So the rule is the shape of the thing rather than a list of the names that
+/// are known to be dangerous: `IFS`, `LD_PRELOAD` and `PATH` are all perfectly
+/// good identifiers and are the user's business, while nothing legitimate needs
+/// a `%`, a `(` or a space in an environment variable name.
+///
+/// The key is judged **trimmed**, because that is what `create_container` sends
+/// — ` FOO ` already reaches the container as `FOO`, and refusing it here would
+/// break a setting that works.
+pub fn is_valid_env_key(key: &str) -> bool {
+    let mut chars = key.trim().chars();
+    match chars.next() {
+        Some(c) if c.is_ascii_alphabetic() || c == '_' => {}
+        _ => return false,
+    }
+    chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
+}
+
+/// Validate a custom environment variable list that is about to be stored,
+/// admitting the entries it is already stored with.
+///
+/// Same shape, and the same reasoning, as
+/// `commands::project_commands::validate_project_paths_update`: nothing ever
+/// checked these keys, so `projects.json` and `settings.json` in the field can
+/// hold whatever was typed. Holding every save to the new rule would make such
+/// a project unsavable *entirely* — `update_project` is the single command
+/// behind the whole Config tab — and would buy nothing, because the stored key
+/// is already being handed to every container that starts. An entry carried
+/// over verbatim is admitted; a new or edited one is held to the rule, which is
+/// what keeps the escalation closed, since escalation means *introducing* a bad
+/// key through this command.
+///
+/// Counted rather than set-tested, for the same reason as the folder rows: a
+/// second copy of an existing entry is a new entry.
+///
+/// The blank entry is not a violation. "+ Add variable" appends
+/// `{key: "", value: ""}` and saves the list immediately, so refusing it would
+/// turn the button itself into an error toast; `create_container` skips an
+/// empty key, so it reaches nothing.
+pub fn validate_env_vars_update(stored: &[EnvVar], incoming: &[EnvVar]) -> Result<(), String> {
+    // An entry with no key is the placeholder, whatever is in its value:
+    // `create_container` skips it, so it reaches nothing and there is nothing
+    // to refuse. The editor saves on every blur, and typing the value before
+    // the name is an ordinary way to fill a row in.
+    let is_blank = |v: &EnvVar| v.key.trim().is_empty();
+
+    let mut carried: std::collections::HashMap<(&str, &str), usize> =
+        std::collections::HashMap::new();
+    for v in stored.iter().filter(|v| !is_blank(v)) {
+        *carried
+            .entry((v.key.as_str(), v.value.as_str()))
+            .or_insert(0) += 1;
+    }
+
+    for v in incoming.iter().filter(|v| !is_blank(v)) {
+        match carried.get_mut(&(v.key.as_str(), v.value.as_str())) {
+            Some(remaining) if *remaining > 0 => {
+                *remaining -= 1;
+            }
+            _ => {
+                if !is_valid_env_key(&v.key) {
+                    return Err(format!(
+                        "'{}' is not a usable environment variable name. Use a letter or \
+                         underscore followed by letters, digits or underscores.",
+                        v.key
+                    ));
+                }
+            }
+        }
+    }
+
+    Ok(())
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 pub struct ProjectPath {
     pub host_path: String,
@@ -28,34 +124,196 @@ fn default_full_permissions() -> bool {
     true
 }
 
+/// `use_shared_auth_token` defaults to **on**: once the user has run
+/// `claude setup-token` once, every existing Anthropic-backend project should
+/// pick the token up without being edited one by one. Projects deliberately
+/// pinned to their own `claude login` identity opt out.
+fn default_use_shared_auth_token() -> bool {
+    true
+}
+
+/// How much autonomy Claude Code is granted inside the container.
+///
+/// Maps onto Claude Code CLI flags — see [`PermissionMode::cli_args`], which is
+/// the single definition of that mapping and must be used by every call site.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+#[serde(rename_all = "camelCase")]
+pub enum PermissionMode {
+    /// Read-only planning mode.
+    Plan,
+    /// Claude Code's own default behavior (prompts for permission).
+    #[default]
+    Default,
+    /// Auto-accept file edits, prompt for everything else.
+    AcceptEdits,
+    /// Skip all permission prompts.
+    Bypass,
+}
+
+impl PermissionMode {
+    /// The CLI flags this mode adds to a `claude` invocation.
+    /// Defined once here so every call site stays in sync.
+    pub fn cli_args(&self) -> Vec<String> {
+        match self {
+            PermissionMode::Plan => vec!["--permission-mode".to_string(), "plan".to_string()],
+            PermissionMode::Default => Vec::new(),
+            PermissionMode::AcceptEdits => {
+                vec!["--permission-mode".to_string(), "acceptEdits".to_string()]
+            }
+            PermissionMode::Bypass => vec!["--dangerously-skip-permissions".to_string()],
+        }
+    }
+
+    /// The wire value used for the `TRIPLE_C_PERMISSION_MODE` container env var.
+    /// Matches the serde `camelCase` representation.
+    pub fn as_env_value(&self) -> &'static str {
+        match self {
+            PermissionMode::Plan => "plan",
+            PermissionMode::Default => "default",
+            PermissionMode::AcceptEdits => "acceptEdits",
+            PermissionMode::Bypass => "bypass",
+        }
+    }
+}
+
 /// Settings for Claude Code CLI behavior inside the container.
 /// These map to Claude Code env vars and ~/.claude/settings.json entries.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
+#[serde(from = "StoredClaudeCodeSettings")]
+/// Every field is three-state, and the third state is load-bearing.
+///
+/// `None` means "not set at this level". For a *project* that is "inherit
+/// whatever the global settings say"; for the *global* settings it is "leave
+/// Claude Code's own default alone". `Some(false)` is a deliberate off, which
+/// is what lets a project turn a globally-enabled setting back off — with a
+/// plain `bool` there is no value that can express that, which is why these
+/// were widened from `bool`.
 pub struct ClaudeCodeSettings {
-    /// TUI rendering mode: None = default, Some("fullscreen") = flicker-free alt-screen
-    #[serde(default)]
+    /// TUI renderer. `None` leaves settings.json's `tui` key unset, which is
+    /// what lets Claude Code pick the renderer itself; `Some("default")` pins
+    /// the classic main-screen renderer and `Some("fullscreen")` the alt-screen
+    /// one. All three are distinct — "let it choose" is not "classic".
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub tui_mode: Option<String>,
-    /// Effort level: None = default, Some("low"|"medium"|"high")
-    #[serde(default)]
+    /// Saved `/effort` level: `None` = unset, otherwise one of
+    /// `"low" | "medium" | "high" | "xhigh"`. Written to settings.json as
+    /// `effortLevel` (**not** `effort`, which Claude Code has never read).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub effort: Option<String>,
-    /// Disable auto-scroll in fullscreen TUI mode
-    #[serde(default)]
-    pub auto_scroll_disabled: bool,
-    /// Enable focus mode (collapsed tool output)
-    #[serde(default)]
-    pub focus_mode: bool,
+    /// Disable auto-scroll in fullscreen TUI mode. Held in the *disabled* sense
+    /// because Claude Code's `autoScrollEnabled` defaults to `true`, so the
+    /// zero value of this field has to mean "leave it on".
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub auto_scroll_disabled: Option<bool>,
+    /// Collapse tool output to one-line summaries. Written to settings.json as
+    /// `viewMode: "focus"`; there is no `focusMode` key in Claude Code.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub focus_mode: Option<bool>,
     /// Show thinking summaries in responses
-    #[serde(default)]
-    pub show_thinking_summaries: bool,
-    /// Enable session recap when returning to a session
-    #[serde(default)]
-    pub enable_session_recap: bool,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub show_thinking_summaries: Option<bool>,
+    /// Turn the session recap **off**.
+    ///
+    /// Held in the disabled sense for the same reason as `auto_scroll_disabled`,
+    /// and the rename from the old `enable_session_recap` is load-bearing rather
+    /// than cosmetic. Claude Code's recap is on by default, so the old field was
+    /// inverted: switching it on was a no-op and switching it off did nothing at
+    /// all. Reusing the name with the opposite meaning would have read every
+    /// stored `enable_session_recap: false` — which is what every project that
+    /// never touched the control holds — as "the user turned the recap off" and
+    /// silently disabled it for all of them. A new name lets the old key be
+    /// ignored, which lands every existing project on the correct default.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub session_recap_disabled: Option<bool>,
     /// Strip credentials from subprocess environments
-    #[serde(default)]
-    pub env_scrub: bool,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub env_scrub: Option<bool>,
     /// Enable 1-hour prompt cache TTL (vs default 5-minute)
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub prompt_caching_1h: Option<bool>,
+}
+
+/// `ClaudeCodeSettings` in every shape `projects.json` and `settings.json` can
+/// be holding, which is what [`ClaudeCodeSettings`] is actually deserialised
+/// through.
+///
+/// ## The upgrade this exists to survive
+///
+/// Before the widening, the five booleans were plain `bool`s with
+/// `#[serde(default)]` and no `skip_serializing_if`, so **every** settings
+/// object ever written carries an explicit `"env_scrub": false` — not because
+/// anyone chose it, but because that is what a `bool` serialises to. Under the
+/// old merge (`if p.x { true } else { g.x }`) that `false` carried no
+/// information at all: it was the only value an unset switch could produce, and
+/// the global always won.
+///
+/// Read as `Some(false)` by the new code it becomes a *deliberate off* that
+/// beats a global `Some(true)` — so upgrading silently turned five settings off
+/// for every project that had ever opened this editor, `env_scrub` ("strip
+/// credentials from subprocess environments") among them. There is no store
+/// migration anywhere: `projects_store` parses these structs directly.
+///
+/// ## How an old record is told apart from a new one
+///
+/// By `enable_session_recap`. It was in the struct from the day it existed and
+/// was a plain `bool`, so its key is present in every pre-widening record and
+/// in no other — the field was *renamed* to `session_recap_disabled` precisely
+/// so the old key could be ignored (see the doc on that field), and the new
+/// code has never written it. Its presence is therefore an exact statement that
+/// these bytes were written by a binary in which `false` meant "unset", and the
+/// booleans are read back that way: `true` is a real choice and survives,
+/// `false` becomes `None` and inherits again.
+///
+/// Nothing marks a *new* record, and nothing needs to: absent is `None` (the
+/// fields skip serialising when unset) and a present `false` is the deliberate
+/// off the widening was for. That is also what keeps a downgrade survivable —
+/// an older binary reads an absent key as `false` through its own
+/// `#[serde(default)]`, where a `null` would fail to parse and take the whole
+/// of `projects.json` down with it, since `ProjectsStore` parses all-or-nothing
+/// and starts empty on an error.
+#[derive(Deserialize)]
+struct StoredClaudeCodeSettings {
     #[serde(default)]
-    pub prompt_caching_1h: bool,
+    tui_mode: Option<String>,
+    #[serde(default)]
+    effort: Option<String>,
+    #[serde(default)]
+    auto_scroll_disabled: Option<bool>,
+    #[serde(default)]
+    focus_mode: Option<bool>,
+    #[serde(default)]
+    show_thinking_summaries: Option<bool>,
+    #[serde(default)]
+    session_recap_disabled: Option<bool>,
+    #[serde(default)]
+    env_scrub: Option<bool>,
+    #[serde(default)]
+    prompt_caching_1h: Option<bool>,
+    /// The pre-widening spelling of `session_recap_disabled`, and the *only*
+    /// use of its value: presence dates the record. Its meaning was inverted
+    /// and it never worked, so it is read for the marker and discarded.
+    #[serde(default)]
+    enable_session_recap: Option<bool>,
+}
+
+impl From<StoredClaudeCodeSettings> for ClaudeCodeSettings {
+    fn from(stored: StoredClaudeCodeSettings) -> Self {
+        let pre_widening = stored.enable_session_recap.is_some();
+        // On a pre-widening record `false` is what an untouched switch wrote,
+        // so it means "not set at this level" and must inherit. A `true` was a
+        // real choice either way.
+        let read = |v: Option<bool>| if pre_widening { v.filter(|on| *on) } else { v };
+        ClaudeCodeSettings {
+            tui_mode: stored.tui_mode,
+            effort: stored.effort,
+            auto_scroll_disabled: read(stored.auto_scroll_disabled),
+            focus_mode: read(stored.focus_mode),
+            show_thinking_summaries: read(stored.show_thinking_summaries),
+            session_recap_disabled: read(stored.session_recap_disabled),
+            env_scrub: read(stored.env_scrub),
+            prompt_caching_1h: read(stored.prompt_caching_1h),
+        }
+    }
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -69,14 +327,72 @@ pub struct Project {
     pub backend: Backend,
     pub bedrock_config: Option<BedrockConfig>,
     pub ollama_config: Option<OllamaConfig>,
+    #[serde(default, alias = "llama_cpp_config")]
+    pub llamacpp_config: Option<LlamaCppConfig>,
     #[serde(alias = "litellm_config")]
     pub openai_compatible_config: Option<OpenAiCompatibleConfig>,
     pub allow_docker_access: bool,
     #[serde(default)]
+    pub sandbox_mode_enabled: bool,
+    #[serde(default)]
     pub mission_control_enabled: bool,
+    /// Opt in to the auth bridge: while the container runs, its loopback
+    /// listeners are mirrored onto the host's loopback so browser OAuth
+    /// callbacks (`claude login`, `fly login`, `aws sso login`) can reach them.
+    /// Purely host-side — it deliberately has no container-recreation label,
+    /// because toggling it changes nothing about the container itself.
+    #[serde(default)]
+    pub auth_bridge_enabled: bool,
+    /// Opt in to the browser-view pane, which watches and takes over the
+    /// browser Claude drives with Playwright inside the container. Purely
+    /// host-side like `auth_bridge_enabled`, so it likewise has no
+    /// container-recreation label.
+    #[serde(default)]
+    pub browser_view_enabled: bool,
+    /// Grant the container what a VPN client needs to build a tunnel:
+    /// `CAP_NET_ADMIN`, the `/dev/net/tun` device, and the WireGuard
+    /// `src_valid_mark` sysctl. Without all three a client (PIA, WireGuard,
+    /// OpenVPN) installs and runs but its connection attempt hangs until it
+    /// times out, because it cannot create the tunnel interface or touch the
+    /// routing table.
+    ///
+    /// Off by default and deliberately opt-in: `NET_ADMIN` lets anything in the
+    /// container reconfigure its own network stack, which reaches further than
+    /// it sounds — see `vpn_host_config` for what it does and does not confer.
+    /// Unlike `auth_bridge_enabled` this *is*
+    /// container state, so it carries a `triple-c.vpn-support` label and is
+    /// compared in `container_needs_recreation` — capabilities and devices are
+    /// fixed at creation and can only change by recreating the container.
+    #[serde(default)]
+    pub vpn_support_enabled: bool,
+    /// Use the shared, long-lived Claude Code OAuth token (from
+    /// `claude setup-token`, held in the OS keychain) for this project instead
+    /// of requiring its own `claude login`. Only consulted when `backend` is
+    /// [`Backend::Anthropic`] and a token has actually been stored.
+    ///
+    /// Defaults to **true** so a single `setup-token` run covers every project;
+    /// turn it off to pin a project to the identity it logged in with inside
+    /// its own container.
+    #[serde(default = "default_use_shared_auth_token")]
+    pub use_shared_auth_token: bool,
+    /// Legacy binary permission flag. Superseded by `permission_mode`, but kept
+    /// because it is the value already stored in users' `projects.json`; it is
+    /// the fallback in `effective_permission_mode()` so old projects keep
+    /// behaving identically without a data migration.
     #[serde(default = "default_full_permissions")]
     pub full_permissions: bool,
+    /// Per-project permission mode. `None` means "not set yet" → fall back to
+    /// the legacy `full_permissions` flag.
+    #[serde(default)]
+    pub permission_mode: Option<PermissionMode>,
     pub ssh_key_path: Option<String>,
+    /// Per-project override for the corporate CA certificate path (file or
+    /// directory). Blank falls back to `AppSettings::ca_cert_path`.
+    ///
+    /// `#[serde(default)]` rather than a required field: every project stored
+    /// before this existed must keep loading.
+    #[serde(default)]
+    pub ca_cert_path: Option<String>,
     #[serde(skip_serializing, default)]
     pub git_token: Option<String>,
     pub git_user_name: Option<String>,
@@ -88,9 +404,10 @@ pub struct Project {
     #[serde(default)]
     pub claude_instructions: Option<String>,
     #[serde(default)]
-    pub enabled_mcp_servers: Vec<String>,
-    #[serde(default)]
     pub claude_code_settings: Option<ClaudeCodeSettings>,
+    /// User-defined display names for terminal tabs, keyed by session id.
+    #[serde(default)]
+    pub renamed_session_names: HashMap<String, String>,
     pub created_at: String,
     pub updated_at: String,
 }
@@ -105,12 +422,69 @@ pub enum ProjectStatus {
     Error,
 }
 
+/// What `remove_project` could not delete, named so the UI can say so instead
+/// of reporting a clean removal that was not one.
+///
+/// The project record is dropped from `projects.json` regardless — see the
+/// long comment on `remove_project` for why refusing is not the answer — but
+/// anything named here is also written to a pending-cleanup record that
+/// startup housekeeping retries, so it stays reachable after the project it
+/// belonged to no longer exists.
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+pub struct ProjectRemovalReport {
+    /// The project's container, if it could not be removed. Named by its
+    /// deterministic `triple-c-{id}` name (see `Project::container_name`),
+    /// not the container id, since the id can be stale or absent and the
+    /// name is what a later retry can still resolve.
+    pub container: Option<String>,
+    /// The `triple-c-snapshot-{id}` image, if it could not be removed.
+    pub image: Option<String>,
+    /// Named volumes (home, claude config) that could not be removed.
+    pub volumes: Vec<String>,
+    /// True once the leftovers above were durably recorded for automatic
+    /// retry on the next launch. False means the pending-cleanup record
+    /// itself could not be written — nothing will retry these, and the UI
+    /// must say so rather than promising a retry that will not happen.
+    /// Meaningless (and left at its default) when `is_clean()` is true.
+    pub retry_scheduled: bool,
+}
+
+impl ProjectRemovalReport {
+    /// True when nothing was left behind.
+    pub fn is_clean(&self) -> bool {
+        self.container.is_none() && self.image.is_none() && self.volumes.is_empty()
+    }
+}
+
+/// What `rebuild_project_container` (Reset) produced: the project as it
+/// stands after restarting, and anything Reset could not clear.
+///
+/// Reset's contract is "back to a clean base image", so a leftover volume or
+/// image here is reused/rebuilt-from as-is by the container this creates —
+/// the opposite of what was asked for — and unlike [`ProjectRemovalReport`]
+/// there is no pending-cleanup record for either: the project id survives
+/// Reset, so a later Reset attempt can retry them itself.
+#[derive(Debug, Clone, Serialize)]
+pub struct ProjectResetOutcome {
+    pub project: Project,
+    /// The `triple-c-snapshot-{id}` image, if Reset could not remove it. The
+    /// more serious of the two leftovers here: the new container is created
+    /// from this image whenever it exists, so a surviving image means Reset
+    /// silently rebuilt the exact system layer it was asked to discard.
+    pub leftover_image: Option<String>,
+    /// Volumes that survived Reset and were mounted into the new container
+    /// unchanged.
+    pub leftover_volumes: Vec<String>,
+}
+
 /// Which AI model backend/provider the project uses.
 /// - `Anthropic`: Direct Anthropic API (user runs `claude login` inside the container)
 /// - `Bedrock`: AWS Bedrock with per-project AWS credentials
 /// - `Ollama`: Local or remote Ollama server
-/// - `OpenAiCompatible`: Any OpenAI API-compatible endpoint (e.g., LiteLLM, vLLM, etc.)
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+/// - `LlamaCpp`: A local or remote `llama-server` (llama.cpp)
+/// - `OpenAiCompatible`: Any endpoint that speaks the Anthropic Messages API
+///   (e.g. LiteLLM). See [`Backend::uses_custom_endpoint`].
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "snake_case")]
 pub enum Backend {
     /// Backward compat: old projects stored as "login" or "api_key" map to Anthropic.
@@ -118,6 +492,10 @@ pub enum Backend {
     Anthropic,
     Bedrock,
     Ollama,
+    /// Serialises as `llama_cpp`; the aliases accept the spellings a
+    /// hand-edited `projects.json` is likely to contain.
+    #[serde(alias = "llamacpp", alias = "llama-cpp", alias = "llama.cpp")]
+    LlamaCpp,
     #[serde(alias = "lite_llm", alias = "litellm")]
     OpenAiCompatible,
 }
@@ -128,6 +506,28 @@ impl Default for Backend {
     }
 }
 
+impl Backend {
+    /// Whether this backend points Claude Code at a non-Anthropic HTTP endpoint
+    /// via `ANTHROPIC_BASE_URL`.
+    ///
+    /// Those endpoints serve whatever model *they* were started with, so
+    /// Claude Code's built-in `opus`/`sonnet`/`haiku`/`fable` aliases resolve to
+    /// Anthropic model ids the server has never heard of. Every backend for
+    /// which this returns `true` therefore gets the
+    /// `ANTHROPIC_DEFAULT_*_MODEL` alias vars pinned to the configured model —
+    /// see `docker::container::compute_model_aliases`.
+    ///
+    /// Bedrock is deliberately excluded: it talks to AWS, which does host the
+    /// real Anthropic model ids, so Claude Code's own defaults are correct
+    /// there. Anthropic is excluded for the same reason.
+    pub fn uses_custom_endpoint(&self) -> bool {
+        matches!(
+            self,
+            Backend::Ollama | Backend::LlamaCpp | Backend::OpenAiCompatible
+        )
+    }
+}
+
 /// How Bedrock authenticates with AWS.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "snake_case")]
@@ -159,30 +559,67 @@ pub struct BedrockConfig {
     pub aws_bearer_token: Option<String>,
     pub model_id: Option<String>,
     pub disable_prompt_caching: bool,
+    /// Optional value for the `ANTHROPIC_BEDROCK_SERVICE_TIER` env var
+    /// (e.g. "priority"). Empty/None means leave unset.
+    #[serde(default)]
+    pub service_tier: Option<String>,
 }
 
 /// Ollama configuration for a project.
-/// Ollama exposes an Anthropic-compatible API endpoint.
+/// Ollama natively implements the Anthropic Messages API at `/v1/messages`.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct OllamaConfig {
     /// The base URL of the Ollama server (e.g., "http://host.docker.internal:11434" or "http://192.168.1.100:11434")
     pub base_url: String,
     /// Optional model override (e.g., "qwen3.5:27b")
     pub model_id: Option<String>,
+    /// Optional override for the model the `haiku` alias resolves to.
+    /// Blank falls back to `model_id`. See [`Backend::uses_custom_endpoint`].
+    #[serde(default)]
+    pub haiku_model_id: Option<String>,
+}
+
+/// llama.cpp (`llama-server`) configuration for a project.
+///
+/// `llama-server` natively implements the Anthropic Messages API at
+/// `POST /v1/messages` (plus `/v1/messages/count_tokens`), so Claude Code can
+/// talk to it directly through `ANTHROPIC_BASE_URL` — exactly like Ollama, with
+/// no translation shim.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct LlamaCppConfig {
+    /// The base URL of the llama-server instance. `llama-server`'s default
+    /// listen port is 8080 (`--port PORT | port to listen (default: 8080)`).
+    pub base_url: String,
+    /// Optional model override. `llama-server` serves whatever model it was
+    /// started with, so this is mostly the id Claude Code should *say* it is
+    /// using — but it is also what the model aliases are pinned to.
+    pub model_id: Option<String>,
+    /// Optional override for the model the `haiku` alias resolves to.
+    /// Blank falls back to `model_id`.
+    #[serde(default)]
+    pub haiku_model_id: Option<String>,
 }
 
 /// OpenAI Compatible endpoint configuration for a project.
-/// Routes Anthropic API calls through any OpenAI API-compatible endpoint
-/// (e.g., LiteLLM, vLLM, or other compatible gateways).
+///
+/// Despite the name (kept for backward compatibility with existing
+/// `projects.json` data), the endpoint must implement the **Anthropic Messages
+/// API** — Claude Code only ever speaks `POST /v1/messages`. Gateways such as
+/// LiteLLM expose an Anthropic-shaped route and work; a bare
+/// `/v1/chat/completions` server does not.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct OpenAiCompatibleConfig {
-    /// The base URL of the OpenAI-compatible endpoint (e.g., "http://host.docker.internal:4000" or "https://api.example.com")
+    /// The base URL of the endpoint (e.g., "http://host.docker.internal:4000" or "https://api.example.com")
     pub base_url: String,
-    /// API key for the OpenAI-compatible endpoint
+    /// API key for the endpoint
     #[serde(skip_serializing, default)]
     pub api_key: Option<String>,
     /// Optional model override
     pub model_id: Option<String>,
+    /// Optional override for the model the `haiku` alias resolves to.
+    /// Blank falls back to `model_id`.
+    #[serde(default)]
+    pub haiku_model_id: Option<String>,
 }
 
 impl Project {
@@ -197,24 +634,43 @@ impl Project {
             backend: Backend::default(),
             bedrock_config: None,
             ollama_config: None,
+            llamacpp_config: None,
             openai_compatible_config: None,
             allow_docker_access: false,
+            sandbox_mode_enabled: false,
             mission_control_enabled: false,
+            auth_bridge_enabled: false,
+            browser_view_enabled: false,
+            vpn_support_enabled: false,
+            use_shared_auth_token: default_use_shared_auth_token(),
             full_permissions: false,
+            permission_mode: None,
             ssh_key_path: None,
+            ca_cert_path: None,
             git_token: None,
             git_user_name: None,
             git_user_email: None,
             custom_env_vars: Vec::new(),
             port_mappings: Vec::new(),
             claude_instructions: None,
-            enabled_mcp_servers: Vec::new(),
             claude_code_settings: None,
+            renamed_session_names: HashMap::new(),
             created_at: now.clone(),
             updated_at: now,
         }
     }
 
+    /// The permission mode to actually use for this project.
+    /// Falls back to the legacy `full_permissions` boolean when the newer
+    /// `permission_mode` field has never been set.
+    pub fn effective_permission_mode(&self) -> PermissionMode {
+        self.permission_mode.unwrap_or(if self.full_permissions {
+            PermissionMode::Bypass
+        } else {
+            PermissionMode::Default
+        })
+    }
+
     pub fn container_name(&self) -> String {
         format!("triple-c-{}", self.id)
     }
@@ -244,3 +700,189 @@ impl Project {
         val
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // ── ProjectRemovalReport ────────────────────────────────────────────────
+
+    #[test]
+    fn a_report_is_clean_only_with_nothing_left_behind() {
+        assert!(ProjectRemovalReport::default().is_clean());
+
+        let mut r = ProjectRemovalReport::default();
+        r.container = Some("abc123".to_string());
+        assert!(!r.is_clean(), "a leftover container must not read as clean");
+
+        let mut r = ProjectRemovalReport::default();
+        r.image = Some("triple-c-snapshot-x:latest".to_string());
+        assert!(!r.is_clean(), "a leftover image must not read as clean");
+
+        let mut r = ProjectRemovalReport::default();
+        r.volumes.push("triple-c-home-x".to_string());
+        assert!(!r.is_clean(), "a leftover volume must not read as clean");
+    }
+
+    // ── Custom environment variable names ─────────────────────────────────
+
+    #[test]
+    fn an_env_var_name_has_to_be_a_shell_identifier() {
+        for ok in ["PATH", "_", "_x", "MY_VAR2", "a", " SPACED_BY_THE_EDITOR "] {
+            assert!(is_valid_env_key(ok), "'{}' should be a usable name", ok);
+        }
+        for bad in [
+            // bash's wire format for an exported shell function: the value is
+            // the body, and a `bash` that imports it runs it. The scrub exec is
+            // `/bin/sh -c` as root, and nothing pins `/bin/sh` to dash.
+            "BASH_FUNC_stat%%",
+            "BASH_FUNC_ls()",
+            "MY VAR",
+            "2FAST",
+            "WITH-DASH",
+            "WITH.DOT",
+            "",
+            "   ",
+            "$(id)",
+            "A=B",
+        ] {
+            assert!(!is_valid_env_key(bad), "'{}' should be refused", bad);
+        }
+    }
+
+    fn env(key: &str, value: &str) -> EnvVar {
+        EnvVar { key: key.to_string(), value: value.to_string() }
+    }
+
+    #[test]
+    fn a_bad_env_var_name_cannot_be_introduced_but_a_stored_one_does_not_brick_the_editor() {
+        let bad = [env("BASH_FUNC_stat%%", "() { id; }")];
+        // Introducing it through the Config tab is the escalation.
+        assert!(validate_env_vars_update(&[], &bad).is_err());
+        // Already stored: it is handed to every container that starts whether
+        // or not an unrelated save is allowed through, and refusing the save
+        // would make every toggle on the Config tab fail.
+        assert!(validate_env_vars_update(&bad, &bad).is_ok());
+        // Editing its value is a new entry, and refused again.
+        assert!(
+            validate_env_vars_update(&bad, &[env("BASH_FUNC_stat%%", "() { rm -rf /; }")]).is_err()
+        );
+        // Fixing the name is what the message asks for, and it saves.
+        assert!(validate_env_vars_update(&bad, &[env("STAT", "() { id; }")]).is_ok());
+        // Dropping it entirely is always fine.
+        assert!(validate_env_vars_update(&bad, &[]).is_ok());
+    }
+
+    #[test]
+    fn the_blank_row_the_add_button_saves_is_not_an_error() {
+        // "+ Add variable" appends an empty entry and saves the list at once,
+        // so this is the button, not an attempt at anything.
+        assert!(validate_env_vars_update(&[], &[env("", "")]).is_ok());
+        // Typing the value before the name is an ordinary way to fill it in,
+        // and an entry with no name reaches no container either way.
+        assert!(validate_env_vars_update(&[], &[env("", "value-first")]).is_ok());
+        assert!(validate_env_vars_update(&[], &[env("GOOD", "v"), env("", "")]).is_ok());
+    }
+
+    #[test]
+    fn a_stored_entry_may_be_kept_but_not_multiplied() {
+        let stored = [env("BAD NAME", "v")];
+        assert!(validate_env_vars_update(&stored, &stored).is_ok());
+        // A second copy is a new entry, and held to the rule.
+        assert!(
+            validate_env_vars_update(&stored, &[env("BAD NAME", "v"), env("BAD NAME", "v")])
+                .is_err()
+        );
+    }
+
+    // ── Claude Code settings written before the fields were widened ───────
+
+    /// `projects.json` exactly as the shipped `main` binary wrote it: the five
+    /// booleans were plain `bool`s that always serialised, so every project
+    /// that ever opened the editor carries `false` for the ones it never
+    /// touched.
+    const MAIN_SHAPE_PROJECT: &str = r#"{
+        "id": "p1",
+        "name": "demo",
+        "paths": [{ "host_path": "/home/u/demo", "mount_name": "demo" }],
+        "container_id": null,
+        "status": "stopped",
+        "backend": "anthropic",
+        "bedrock_config": null,
+        "ollama_config": null,
+        "openai_compatible_config": null,
+        "allow_docker_access": false,
+        "ssh_key_path": null,
+        "git_user_name": null,
+        "git_user_email": null,
+        "claude_code_settings": {
+            "tui_mode": "fullscreen",
+            "effort": null,
+            "auto_scroll_disabled": false,
+            "focus_mode": false,
+            "show_thinking_summaries": false,
+            "enable_session_recap": false,
+            "env_scrub": false,
+            "prompt_caching_1h": false
+        },
+        "created_at": "2026-01-01T00:00:00Z",
+        "updated_at": "2026-01-01T00:00:00Z"
+    }"#;
+
+    #[test]
+    fn a_setting_stored_as_false_by_the_old_binary_still_inherits_the_global() {
+        let project: Project = serde_json::from_str(MAIN_SHAPE_PROJECT).unwrap();
+        let stored = project.claude_code_settings.expect("settings should parse");
+
+        // Read verbatim these would be `Some(false)`, which under
+        // `docker::container::merge_claude_code_settings` beats the global.
+        assert_eq!(stored.env_scrub, None);
+        assert_eq!(stored.auto_scroll_disabled, None);
+        assert_eq!(stored.focus_mode, None);
+        assert_eq!(stored.show_thinking_summaries, None);
+        assert_eq!(stored.prompt_caching_1h, None);
+        assert_eq!(stored.session_recap_disabled, None);
+        // A value the user did choose is untouched.
+        assert_eq!(stored.tui_mode.as_deref(), Some("fullscreen"));
+
+        // The merge rule itself, spelled the way
+        // `merge_claude_code_settings` spells it. `main` resolved this with
+        // `if p.env_scrub { true } else { g.env_scrub }`, i.e. the global won —
+        // and it has to go on winning, because the user never turned this off.
+        let global = ClaudeCodeSettings { env_scrub: Some(true), ..Default::default() };
+        assert_eq!(
+            stored.env_scrub.or(global.env_scrub),
+            Some(true),
+            "upgrading silently turned off 'strip credentials from subprocess environments'"
+        );
+    }
+
+    #[test]
+    fn an_off_chosen_in_the_new_editor_still_beats_a_global_on() {
+        // Same record without the pre-widening key: this `false` is the
+        // deliberate off the widening exists to make expressible.
+        let json = r#"{ "env_scrub": false }"#;
+        let chosen: ClaudeCodeSettings = serde_json::from_str(json).unwrap();
+        assert_eq!(chosen.env_scrub, Some(false));
+        let global = ClaudeCodeSettings { env_scrub: Some(true), ..Default::default() };
+        assert_eq!(chosen.env_scrub.or(global.env_scrub), Some(false));
+    }
+
+    #[test]
+    fn an_unset_setting_is_written_as_absent_rather_than_null() {
+        // A downgrade parses these fields as plain `bool` with
+        // `#[serde(default)]`: an absent key is `false`, a `null` is a parse
+        // error — and `ProjectsStore` parses all-or-nothing, so one project
+        // with one null empties the whole list and the next save persists that.
+        let json = serde_json::to_string(&ClaudeCodeSettings::default()).unwrap();
+        assert_eq!(json, "{}");
+        assert!(!json.contains("null"));
+
+        let partial = ClaudeCodeSettings { env_scrub: Some(false), ..Default::default() };
+        let json = serde_json::to_string(&partial).unwrap();
+        assert_eq!(json, r#"{"env_scrub":false}"#);
+        // And it reads back as what it is.
+        let round_tripped: ClaudeCodeSettings = serde_json::from_str(&json).unwrap();
+        assert_eq!(round_tripped, partial);
+    }
+}

app/src-tauri/src/models/settings_export.rs

@@ -0,0 +1,366 @@
+//! Settings export/import — see triple-c#35.
+//!
+//! `SettingsExportPayload` is the whole plaintext export before encryption
+//! and after decryption (see `storage::settings_crypto`). It bundles
+//! `AppSettings` — with one field carved out, see below — with the global
+//! secrets that live in the OS keychain instead: the shared Claude Code
+//! OAuth login and the model gateway's two keys. Per-project settings,
+//! per-project secrets, and anything living in a project's Docker volumes
+//! are deliberately out of scope: this exports the *host* environment, not
+//! any one project's.
+//!
+//! **`AppSettings` is not entirely the non-secret shape it looks like.**
+//! `WebTerminalSettings::access_token` is a live bearer credential for a
+//! server that binds every interface, stored as a plain field on the
+//! struct that is otherwise safe to treat as config. A review of this
+//! feature caught it: exporting `AppSettings` wholesale would have carried
+//! that token along as if it were as inert as a port number, and — worse —
+//! importing it would apply `web_terminal.enabled` and the token together
+//! with no more warning than any other setting, letting a crafted export
+//! silently stand up a LAN-listening terminal server with an
+//! attacker-known token on the next launch. `export_settings` /
+//! `apply_settings_import` blank this field out of the `settings` they
+//! read from and write to, and it travels only through
+//! [`ExportedSecrets::web_terminal_access_token`] instead, with the same
+//! "only overwrite what the import actually has" treatment as the other
+//! three secrets.
+
+use serde::{Deserialize, Serialize};
+
+use super::{AppSettings, ImageSource};
+
+/// Bumped when the shape of [`SettingsExportPayload`] changes in a way that
+/// isn't just an additive, `#[serde(default)]`-covered field — e.g. if a
+/// field is ever removed or its meaning changes. `apply_settings_import`
+/// checks this before touching anything.
+pub const SETTINGS_EXPORT_FORMAT_VERSION: u32 = 1;
+
+/// The global secrets bundled into an export. Deliberately a separate struct
+/// from `AppSettings`: these live in the OS keychain, never in
+/// `settings.json`, and — outside of this export/import flow — the values
+/// themselves never cross into the frontend; see the doc comments on
+/// `storage::secure::get_gateway_api_key` and
+/// `commands::settings_export_commands` for why that boundary matters here
+/// too.
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct ExportedSecrets {
+    #[serde(default)]
+    pub claude_oauth_token: Option<String>,
+    #[serde(default)]
+    pub gateway_api_key: Option<String>,
+    #[serde(default)]
+    pub gateway_master_key: Option<String>,
+    /// See the module doc comment — this is `AppSettings::web_terminal
+    /// .access_token`, carved out because it is a live bearer credential,
+    /// not config, despite living on a struct that is otherwise safe to
+    /// export wholesale.
+    #[serde(default)]
+    pub web_terminal_access_token: Option<String>,
+}
+
+impl ExportedSecrets {
+    pub fn is_empty(&self) -> bool {
+        let blank = |s: &Option<String>| s.as_deref().is_none_or(|v| v.trim().is_empty());
+        blank(&self.claude_oauth_token)
+            && blank(&self.gateway_api_key)
+            && blank(&self.gateway_master_key)
+            && blank(&self.web_terminal_access_token)
+    }
+}
+
+/// What `apply_settings_import` hands back: the settings that were actually
+/// saved, plus a human-readable note for each keychain secret this import
+/// carried but could not be restored. A keychain write failing partway
+/// through must not read as unqualified success just because the settings
+/// half of the import went through.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SettingsImportOutcome {
+    pub settings: AppSettings,
+    #[serde(default)]
+    pub secret_restore_warnings: Vec<String>,
+}
+
+/// The full plaintext payload — this is what gets encrypted on export and
+/// what decryption recovers on import. Never written to disk unencrypted;
+/// see `storage::settings_crypto`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SettingsExportPayload {
+    pub format_version: u32,
+    /// RFC3339. Purely informational — shown in the import preview so a user
+    /// picking between a few old export files has something to go on.
+    pub exported_at: String,
+    /// The exporting app's `CARGO_PKG_VERSION`. Also informational: every
+    /// field below already round-trips through `#[serde(default)]`-covered
+    /// `AppSettings`, so an older or newer export still deserializes; this is
+    /// for a human to notice "this is from a much older version" if an import
+    /// ever looks wrong, not something the code branches on.
+    pub app_version: String,
+    pub settings: AppSettings,
+    #[serde(default)]
+    pub secrets: ExportedSecrets,
+}
+
+/// What `preview_settings_import` hands the frontend before anything is
+/// applied — counts and presence flags only, **never** a secret value itself,
+/// so this type is safe to return across the IPC boundary and render
+/// directly. The confirmation UI is built from this.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SettingsImportPreview {
+    pub exported_at: String,
+    pub app_version: String,
+    pub custom_env_var_count: usize,
+    pub gateway_model_count: usize,
+    pub has_claude_code_settings: bool,
+    pub has_claude_oauth_token: bool,
+    pub has_gateway_api_key: bool,
+    pub has_gateway_master_key: bool,
+    pub has_web_terminal_access_token: bool,
+    /// Whether the imported settings turn the web terminal on. Named
+    /// separately from the token above: `enabled` and the token are two
+    /// different fields, either can be true without the other, and
+    /// "this import turns on a service that listens on your network" is
+    /// exactly the kind of change a wholesale settings replace must not
+    /// bury in a generic "settings replaced" line — see the module doc
+    /// comment on why this field exists at all.
+    pub enables_web_terminal: bool,
+    /// Non-blank custom base URLs the import would set, so a redirect of
+    /// model traffic to somewhere other than the usual provider is visible
+    /// at import time rather than discovered later. These are endpoints, not
+    /// secrets — safe to show verbatim, unlike everything above.
+    #[serde(default)]
+    pub ollama_base_url: Option<String>,
+    #[serde(default)]
+    pub llamacpp_base_url: Option<String>,
+    #[serde(default)]
+    pub openai_compatible_base_url: Option<String>,
+    #[serde(default)]
+    pub gateway_api_base: Option<String>,
+    /// Whether the import sets a custom Docker image, and its name if so —
+    /// disclosed for the same reason as the base URLs above, and arguably
+    /// more sharply: this is the image *every* project container is created
+    /// from (`models::container_config::resolve_image_name`), so a crafted
+    /// export pointing it at an attacker-controlled image is a path to
+    /// running arbitrary code with whatever a project's containers are
+    /// allowed to reach (the Docker socket, an SSH key, project files) —
+    /// not merely a redirected API endpoint.
+    #[serde(default)]
+    pub image_source: ImageSource,
+    #[serde(default)]
+    pub custom_image_name: Option<String>,
+}
+
+/// A cap on how much of a decrypted, not-yet-trusted string gets echoed back
+/// into a preview a user reads and a UI renders without truncation of its
+/// own. Applied to every field above that carries free-form text straight
+/// from the import file rather than a count or a boolean — a base URL or an
+/// image name a hostile export author controls has had no validation done
+/// on it yet at preview time, and nothing stops it from being pathological
+/// (embedded control characters, or long enough to blow out the confirmation
+/// dialog and push the security warnings below it off screen).
+const MAX_PREVIEW_STRING_LEN: usize = 100;
+
+fn sanitize_for_preview(value: &str) -> String {
+    let cleaned: String = value.chars().filter(|c| !c.is_control()).collect();
+    let trimmed = cleaned.trim();
+    if trimmed.chars().count() > MAX_PREVIEW_STRING_LEN {
+        let truncated: String = trimmed.chars().take(MAX_PREVIEW_STRING_LEN).collect();
+        format!("{}…", truncated)
+    } else {
+        trimmed.to_string()
+    }
+}
+
+impl SettingsImportPreview {
+    pub fn from_payload(payload: &SettingsExportPayload) -> Self {
+        let non_blank = |s: &Option<String>| s.as_deref().is_some_and(|v| !v.trim().is_empty());
+        let sanitized_non_blank = |s: &Option<String>| {
+            s.as_deref()
+                .map(sanitize_for_preview)
+                .filter(|v| !v.is_empty())
+        };
+        Self {
+            exported_at: payload.exported_at.clone(),
+            app_version: payload.app_version.clone(),
+            custom_env_var_count: payload.settings.global_custom_env_vars.len(),
+            gateway_model_count: payload.settings.gateway.models.len(),
+            has_claude_code_settings: payload.settings.global_claude_code_settings.is_some(),
+            has_claude_oauth_token: non_blank(&payload.secrets.claude_oauth_token),
+            has_gateway_api_key: non_blank(&payload.secrets.gateway_api_key),
+            has_gateway_master_key: non_blank(&payload.secrets.gateway_master_key),
+            has_web_terminal_access_token: non_blank(&payload.secrets.web_terminal_access_token),
+            enables_web_terminal: payload.settings.web_terminal.enabled,
+            ollama_base_url: sanitized_non_blank(&payload.settings.global_ollama.base_url),
+            llamacpp_base_url: sanitized_non_blank(&payload.settings.global_llamacpp.base_url),
+            openai_compatible_base_url: sanitized_non_blank(
+                &payload.settings.global_openai_compatible.base_url,
+            ),
+            gateway_api_base: sanitized_non_blank(&payload.settings.gateway.api_base),
+            image_source: payload.settings.image_source.clone(),
+            custom_image_name: sanitized_non_blank(&payload.settings.custom_image_name),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::AppSettings;
+
+    fn payload_with(secrets: ExportedSecrets) -> SettingsExportPayload {
+        let settings = AppSettings {
+            global_custom_env_vars: vec![
+                crate::models::EnvVar {
+                    key: "A".to_string(),
+                    value: "1".to_string(),
+                },
+                crate::models::EnvVar {
+                    key: "B".to_string(),
+                    value: "2".to_string(),
+                },
+            ],
+            ..AppSettings::default()
+        };
+        SettingsExportPayload {
+            format_version: SETTINGS_EXPORT_FORMAT_VERSION,
+            exported_at: "2026-08-27T00:00:00Z".to_string(),
+            app_version: "0.4.14".to_string(),
+            settings,
+            secrets,
+        }
+    }
+
+    #[test]
+    fn the_preview_never_carries_a_secret_value() {
+        let payload = payload_with(ExportedSecrets {
+            claude_oauth_token: Some("sk-super-secret-token".to_string()),
+            gateway_api_key: Some("sk-another-secret".to_string()),
+            gateway_master_key: Some("sk-triple-c-yet-another".to_string()),
+            web_terminal_access_token: Some("wt-super-secret-token".to_string()),
+        });
+        let preview = SettingsImportPreview::from_payload(&payload);
+        let serialized = serde_json::to_string(&preview).unwrap();
+
+        assert!(!serialized.contains("sk-super-secret-token"));
+        assert!(!serialized.contains("sk-another-secret"));
+        assert!(!serialized.contains("sk-triple-c-yet-another"));
+        assert!(!serialized.contains("wt-super-secret-token"));
+        assert!(preview.has_claude_oauth_token);
+        assert!(preview.has_gateway_api_key);
+        assert!(preview.has_gateway_master_key);
+        assert!(preview.has_web_terminal_access_token);
+    }
+
+    #[test]
+    fn a_blank_secret_reads_as_absent_in_the_preview() {
+        // A keychain entry that exists but holds only whitespace must not
+        // read as "present" — same "blank counts as absent" rule the
+        // keychain layer itself applies when storing these.
+        let payload = payload_with(ExportedSecrets {
+            claude_oauth_token: Some("   ".to_string()),
+            gateway_api_key: None,
+            gateway_master_key: None,
+            web_terminal_access_token: Some("   ".to_string()),
+        });
+        let preview = SettingsImportPreview::from_payload(&payload);
+        assert!(!preview.has_claude_oauth_token);
+        assert!(!preview.has_gateway_api_key);
+        assert!(!preview.has_gateway_master_key);
+        assert!(!preview.has_web_terminal_access_token);
+    }
+
+    #[test]
+    fn enabling_the_web_terminal_is_surfaced_regardless_of_whether_a_token_came_with_it() {
+        // `enabled` and the token are independent fields — a crafted export
+        // could set one without the other, and both are worth a user's
+        // attention: this is the field that exists specifically so "this
+        // import turns on a service that listens on your network" cannot
+        // hide inside a generic "settings replaced" summary.
+        let mut payload = payload_with(ExportedSecrets::default());
+        payload.settings.web_terminal.enabled = true;
+        let preview = SettingsImportPreview::from_payload(&payload);
+        assert!(preview.enables_web_terminal);
+        assert!(!preview.has_web_terminal_access_token);
+    }
+
+    #[test]
+    fn custom_base_urls_are_surfaced_but_blank_ones_read_as_absent() {
+        let mut payload = payload_with(ExportedSecrets::default());
+        payload.settings.global_ollama.base_url = Some("http://attacker.example:11434".to_string());
+        payload.settings.global_llamacpp.base_url = Some("   ".to_string());
+        payload.settings.gateway.api_base = Some("https://gateway.example/v1".to_string());
+
+        let preview = SettingsImportPreview::from_payload(&payload);
+        assert_eq!(
+            preview.ollama_base_url.as_deref(),
+            Some("http://attacker.example:11434")
+        );
+        assert_eq!(preview.llamacpp_base_url, None);
+        assert_eq!(preview.openai_compatible_base_url, None);
+        assert_eq!(
+            preview.gateway_api_base.as_deref(),
+            Some("https://gateway.example/v1")
+        );
+    }
+
+    #[test]
+    fn counts_reflect_the_real_settings() {
+        let payload = payload_with(ExportedSecrets::default());
+        let preview = SettingsImportPreview::from_payload(&payload);
+        assert_eq!(preview.custom_env_var_count, 2);
+    }
+
+    #[test]
+    fn an_empty_secrets_bundle_reports_itself_as_empty() {
+        assert!(ExportedSecrets::default().is_empty());
+        assert!(!ExportedSecrets {
+            claude_oauth_token: Some("x".to_string()),
+            ..Default::default()
+        }
+        .is_empty());
+    }
+
+    #[test]
+    fn a_secrets_bundle_holding_only_whitespace_still_reports_itself_as_empty() {
+        // Matches the "blank counts as absent" rule every other consumer of
+        // these fields applies (`has_claude_oauth_token` and friends above) —
+        // a keychain entry that exists but holds only whitespace carries
+        // nothing usable, so the export-time "nothing to export" log line
+        // must still fire for it.
+        assert!(ExportedSecrets {
+            claude_oauth_token: Some("   ".to_string()),
+            ..Default::default()
+        }
+        .is_empty());
+    }
+
+    #[test]
+    fn a_custom_docker_image_is_surfaced() {
+        let mut payload = payload_with(ExportedSecrets::default());
+        payload.settings.image_source = crate::models::ImageSource::Custom;
+        payload.settings.custom_image_name = Some("ghcr.io/attacker/triple-c:latest".to_string());
+
+        let preview = SettingsImportPreview::from_payload(&payload);
+        assert_eq!(preview.image_source, crate::models::ImageSource::Custom);
+        assert_eq!(
+            preview.custom_image_name.as_deref(),
+            Some("ghcr.io/attacker/triple-c:latest")
+        );
+    }
+
+    #[test]
+    fn preview_strings_are_stripped_of_control_characters_and_capped_in_length() {
+        let mut payload = payload_with(ExportedSecrets::default());
+        payload.settings.global_ollama.base_url =
+            Some(format!("http://example.test/{}\u{0007}bell", "x".repeat(200)));
+
+        let preview = SettingsImportPreview::from_payload(&payload);
+        let shown = preview.ollama_base_url.expect("non-blank base url");
+        assert!(!shown.contains('\u{0007}'), "control character leaked into the preview");
+        // +1 for the trailing ellipsis appended when truncated.
+        assert!(
+            shown.chars().count() <= MAX_PREVIEW_STRING_LEN + 1,
+            "preview string was not capped: {} chars",
+            shown.chars().count()
+        );
+    }
+}

app/src-tauri/src/models/update_info.rs

@@ -26,6 +26,24 @@ pub struct GitHubRelease {
     pub body: String,
     pub assets: Vec<GitHubAsset>,
     pub published_at: String,
+    /// Whether GitHub itself has this release marked as a prerelease.
+    /// `#[serde(default)]` rather than required: every response GitHub sends
+    /// carries this, but nothing here should refuse to parse the rest of a
+    /// release over one missing field. Defaults to `false` (offered) rather
+    /// than `true` (excluded) — a missing field only happens if GitHub's API
+    /// shape changes, and "API changed, therefore updates silently stop
+    /// working forever" is the worse failure of the two.
+    ///
+    /// `build-app.yml`'s own mirror never publishes a prerelease, but
+    /// `.gitea/workflows/backfill-releases.yml` forwards every Gitea release
+    /// unfiltered, `prerelease` included. A preview release's `preview-<sha>`
+    /// tag already fails semver parsing on its own, so this field is not what
+    /// stops *that* case — it is what stops the case tag-parsing can't catch:
+    /// a normally-tagged release (`v0.4.13`) that someone marks as a
+    /// prerelease on Gitea (a hotfix candidate, an RC) and a backfill then
+    /// mirrors as-is. Real defence for that case, not a no-op.
+    #[serde(default)]
+    pub prerelease: bool,
 }
 
 /// GitHub API asset response (internal).

app/src-tauri/src/project_lock.rs

@@ -0,0 +1,370 @@
+//! Per-project mutual exclusion for everything that rewrites a project's
+//! container or its snapshot image.
+//!
+//! ## Why polling was not enough
+//!
+//! Until this module existed the app had exactly one mutual-exclusion
+//! primitive — the `ACTIVE_MIGRATIONS` set behind
+//! `migration_commands::is_migrating` — and it was **one-way**. A migration
+//! took a guard for its whole run; everything else merely *asked once, at
+//! entry*, whether a migration was in flight and then proceeded with no claim
+//! of its own. Two non-migration operations on the same project could not see
+//! each other at all, and a migration could start underneath one that was
+//! already halfway through.
+//!
+//! That is not a theoretical gap. Compaction resolves
+//! `triple-c-snapshot-{id}:latest` when its build starts and commits back over
+//! that same tag minutes later, and the Settings panel is a sidebar rather than
+//! a modal — so Project Home stays live with Start, Stop, Reset and Migrate all
+//! clickable while a compaction runs. Three interleavings were reproduced:
+//!
+//! * Compaction commits `flat(A)` over `:latest` after a migration has already
+//!   moved that tag to a new lineage. The migration is silently reverted, the
+//!   config replay lands twice, and the migration record says
+//!   `awaiting-confirmation` against a base the tag no longer points at.
+//! * Compaction resolves A, the user starts the project and works for an hour,
+//!   a recreate commits D over `:latest`, and the compaction then overwrites it
+//!   with `flat(A)` — orphaning an hour of system-layer work while reporting
+//!   success and a byte saving.
+//! * Compaction resurrects the system layer a Reset had just destroyed.
+//!
+//! Every one of those is "two writers of `:latest`, neither holding anything".
+//! So this registry replaces the polling with an actual claim: an operation
+//! **acquires** a [`ProjectGuard`] and holds it for its whole run, and a second
+//! operation on the same project is refused with a message naming the holder.
+//!
+//! ## What this does NOT protect against, stated plainly
+//!
+//! **This is in-process state.** Two copies of the app pointed at the same
+//! Docker daemon share nothing here: instance A's compaction and instance B's
+//! migration will both acquire happily and then race exactly as before.
+//! `reap_probe_containers` and the `triple-c-compact-*` / `triple-c-scrub-*`
+//! sweeps are worse than that — they are daemon-wide force-removals driven by
+//! a name or a label, so instance B can destroy a container instance A is
+//! mid-commit against.
+//!
+//! A daemon-visible lock was considered and rejected for now, and the reasoning
+//! is recorded here so it is not re-derived from scratch:
+//!
+//! * A **lock container** would work — container names are unique daemon-wide
+//!   and `create` fails atomically on a name conflict — but a container has to
+//!   be created *from an image*, and that pins the image. A lock on
+//!   `triple-c-snapshot-{id}` would block the very `rmi`/sweep paths it guards,
+//!   and a leaked lock container would pin multiple gigabytes forever.
+//! * A **named volume** is not usable: `create_volume` on an existing name
+//!   returns the existing volume rather than failing, so it cannot be a
+//!   test-and-set.
+//! * A **label on the snapshot image** is not atomic — read/modify/commit has
+//!   the same race it would be trying to close.
+//!
+//! So the cross-process case is **documented, not solved**. What this module
+//! does do about it is bound the damage: [`any_held_excluding`] lets the daemon-wide
+//! reapers skip work while this process is mid-operation, and the reapers
+//! themselves gained age gates so a young container belonging to somebody else
+//! is left alone (see `docker::migration::reap_probe_containers`).
+//!
+//! ## Refuse, do not queue
+//!
+//! [`try_acquire`] never waits. Every caller is a user-initiated action behind
+//! a button, and a button that blocks for the four minutes a compaction takes
+//! is worse than one that says what is running. The refusal string is written
+//! for the user and names the holder.
+
+use std::collections::HashMap;
+use std::sync::{Mutex, OnceLock};
+
+/// The operations that claim a project.
+///
+/// One variant per *class of writer*, not per command: `Recreate` covers Start
+/// as well, because Start's create-and-commit path is the same writer of
+/// `triple-c-snapshot-{id}:latest` that a recreate is.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProjectOp {
+    /// `migrate_project_to_base`, `resume_migration`, `rollback_migration`,
+    /// `confirm_migration`.
+    Migration,
+    /// `disk::compact_snapshot` — the long one, and the reason this exists.
+    ///
+    /// Not constructed on this branch: the Disk panel and its compaction were
+    /// held back for separate hardening and live on `hold/disk-and-dragout`.
+    /// The variant stays because this registry is the thing that made those
+    /// operations safe to re-land, and a re-land that had to re-derive the
+    /// claim classes would be re-deriving the bug.
+    #[allow(dead_code)]
+    Compaction,
+    /// Start / stop / recreate. Anything in `start_project_container`'s path.
+    Recreate,
+    /// `rebuild_project_container` — deletes both volumes and the snapshot.
+    Reset,
+    /// `disk::destroy` — a volume, a snapshot image, or a rollback pin.
+    Destroy,
+    /// `disk::clear_caches` — an exec into the live container. It does not
+    /// write `:latest`, but it must not run while the container is being
+    /// removed out from under it.
+    ///
+    /// Not constructed on this branch, for the same reason as
+    /// [`ProjectOp::Compaction`].
+    #[allow(dead_code)]
+    CacheClear,
+    /// `container::scrub_secrets_from_snapshots` — the third writer of
+    /// `triple-c-snapshot-{id}:latest`, reached from `clear_claude_token`. It
+    /// creates a scratch container from the snapshot and commits back over the
+    /// same tag, so it is the same read-modify-write shape as a compaction and
+    /// loses the same race: any `:latest` move landing between its create and
+    /// its commit is overwritten by an image derived from the pre-read state.
+    SecretScrub,
+}
+
+impl ProjectOp {
+    /// What is happening, phrased for the message a user reads.
+    pub fn describe(self) -> &'static str {
+        match self {
+            ProjectOp::Migration => "A container base update is running for this project",
+            ProjectOp::Compaction => "This project's snapshot is being compacted",
+            ProjectOp::Recreate => "This project's container is being started or recreated",
+            ProjectOp::Reset => "This project is being reset",
+            ProjectOp::Destroy => "Something of this project's is being deleted",
+            ProjectOp::CacheClear => "This project's caches are being cleared",
+            ProjectOp::SecretScrub => "A revoked credential is being removed from this project's snapshot",
+        }
+    }
+
+    /// What the *refused* caller was trying to do, for the tail of the message.
+    fn blocked_action(self) -> &'static str {
+        match self {
+            ProjectOp::Migration => "starting a base update",
+            ProjectOp::Compaction => "compacting its snapshot",
+            ProjectOp::Recreate => "starting or recreating its container",
+            ProjectOp::Reset => "resetting it",
+            ProjectOp::Destroy => "deleting anything of its",
+            ProjectOp::CacheClear => "clearing its caches",
+            ProjectOp::SecretScrub => "removing a credential from its snapshot",
+        }
+    }
+}
+
+/// Project id → the operation currently holding it.
+///
+/// A `std::sync::Mutex` rather than a `tokio` one on purpose: it is only ever
+/// held for the length of a `HashMap` insert or remove, never across an await,
+/// and [`is_held_by`] has to be callable from the synchronous helpers in
+/// `disk.rs` that already ask this question.
+static HOLDERS: OnceLock<Mutex<HashMap<String, ProjectOp>>> = OnceLock::new();
+
+fn holders() -> &'static Mutex<HashMap<String, ProjectOp>> {
+    HOLDERS.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+/// A claim on one project, released on drop.
+///
+/// RAII rather than an explicit release for the reason [`ProjectOp::Migration`]'s
+/// predecessor already learned: a plain release statement is skipped by an
+/// early `?`, by a panic, and by the future simply being dropped. A guard is
+/// not.
+/// Dropping this releases the claim, so a caller that discards it has taken no
+/// lock at all — `let _ = try_acquire(...)` drops immediately and reads as
+/// success. `#[must_use]` makes that a compile warning rather than a race.
+#[must_use = "the claim is released as soon as this guard is dropped; bind it for the whole operation"]
+#[derive(Debug)]
+pub struct ProjectGuard {
+    project_id: String,
+}
+
+impl Drop for ProjectGuard {
+    fn drop(&mut self) {
+        // `into_inner` on a poisoned lock: a panic while some other thread held
+        // this map for the duration of one insert cannot have left it
+        // inconsistent, and refusing to release afterwards would strand the
+        // project as permanently busy.
+        holders()
+            .lock()
+            .unwrap_or_else(|e| e.into_inner())
+            .remove(&self.project_id);
+    }
+}
+
+/// Claim a project for `op`, or say who has it.
+///
+/// The error is user-facing copy, not a debug string — it goes straight back
+/// over IPC to a toast.
+pub fn try_acquire(project_id: &str, op: ProjectOp) -> Result<ProjectGuard, String> {
+    let mut map = holders().lock().unwrap_or_else(|e| e.into_inner());
+    if let Some(holder) = map.get(project_id).copied() {
+        return Err(format!(
+            "{}. Wait for it to finish before {}.",
+            holder.describe(),
+            op.blocked_action()
+        ));
+    }
+    map.insert(project_id.to_string(), op);
+    Ok(ProjectGuard {
+        project_id: project_id.to_string(),
+    })
+}
+
+/// Which operation holds this project, if any.
+pub fn held(project_id: &str) -> Option<ProjectOp> {
+    holders()
+        .lock()
+        .unwrap_or_else(|e| e.into_inner())
+        .get(project_id)
+        .copied()
+}
+
+/// Whether this project is held by exactly `op`.
+///
+/// `migration_commands::is_migrating` is this, specialised — which is the whole
+/// point of folding `ACTIVE_MIGRATIONS` into this registry: there is now one
+/// answer to "is something happening to this project", not two that can
+/// disagree.
+pub fn is_held_by(project_id: &str, op: ProjectOp) -> bool {
+    held(project_id) == Some(op)
+}
+
+/// Whether any project **other than** `exclude_project_id` is currently held by
+/// `op`. Pass an empty id to ask about every project.
+///
+/// Used by the daemon-wide reapers, which cannot tell which project a
+/// `triple-c-compact-*` container belongs to — the name carries a random uuid,
+/// not a project id — so "is this process compacting anything right now" is the
+/// only in-process question they can ask before force-removing one. The
+/// exclusion is for the reaper that runs *inside* a compaction, which is
+/// already holding a claim of its own and would otherwise see it and skip.
+///
+/// No production caller on this branch: the compaction reaper it was written
+/// for went to `hold/disk-and-dragout` with the rest of the Disk panel. Kept
+/// (and still tested) because it is the only bound this module offers on the
+/// cross-process case documented above.
+#[allow(dead_code)]
+pub fn any_held_excluding(op: ProjectOp, exclude_project_id: &str) -> bool {
+    holders()
+        .lock()
+        .unwrap_or_else(|e| e.into_inner())
+        .iter()
+        .any(|(project_id, held)| *held == op && project_id != exclude_project_id)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Ids are namespaced per test: the registry is process-global, and
+    /// `cargo test` runs these on several threads at once.
+    fn id(name: &str) -> String {
+        format!("project-lock-test-{}", name)
+    }
+
+    #[test]
+    fn a_second_acquire_on_the_same_project_is_refused() {
+        let p = id("second-acquire");
+        let first = try_acquire(&p, ProjectOp::Compaction).expect("first claim");
+        let second = try_acquire(&p, ProjectOp::Recreate);
+        let err = second.expect_err("a second claim must be refused, not queued");
+        // The refusal has to name the holder — "busy" alone leaves the user
+        // with nothing to wait for.
+        assert!(err.contains("snapshot is being compacted"), "{}", err);
+        assert!(err.contains("starting or recreating"), "{}", err);
+        drop(first);
+        // And it has to be retakeable the moment the holder goes away. Bound
+        // rather than discarded: `#[must_use]` is what stops a real caller
+        // writing `try_acquire(...)` and believing it holds something.
+        let retaken = try_acquire(&p, ProjectOp::Recreate).expect("released on drop");
+        drop(retaken);
+    }
+
+    #[test]
+    fn the_guard_releases_on_an_early_return() {
+        let p = id("early-return");
+        fn bails(project_id: &str) -> Result<(), String> {
+            let _guard = try_acquire(project_id, ProjectOp::Reset)?;
+            Err("something failed".to_string())
+        }
+        assert!(bails(&p).is_err());
+        assert_eq!(held(&p), None, "an early `?` must not strand the claim");
+    }
+
+    #[test]
+    fn the_guard_releases_on_a_panic() {
+        let p = id("panic");
+        let result = std::panic::catch_unwind(|| {
+            let _guard = try_acquire(&id("panic"), ProjectOp::Migration).unwrap();
+            panic!("boom");
+        });
+        assert!(result.is_err());
+        assert_eq!(held(&p), None, "a panic must not strand the claim either");
+    }
+
+    #[test]
+    fn two_projects_do_not_block_each_other() {
+        let a = id("independent-a");
+        let b = id("independent-b");
+        let _one = try_acquire(&a, ProjectOp::Compaction).expect("a");
+        let _two = try_acquire(&b, ProjectOp::Compaction).expect("b");
+        assert!(is_held_by(&a, ProjectOp::Compaction));
+        assert!(is_held_by(&b, ProjectOp::Compaction));
+    }
+
+    #[test]
+    fn is_held_by_distinguishes_the_operation() {
+        let p = id("which-op");
+        let _guard = try_acquire(&p, ProjectOp::Compaction).unwrap();
+        assert!(is_held_by(&p, ProjectOp::Compaction));
+        assert!(
+            !is_held_by(&p, ProjectOp::Migration),
+            "a compaction is not a migration — `is_migrating` is built on this"
+        );
+    }
+
+    #[test]
+    fn any_held_sees_across_projects() {
+        let p = id("any-held");
+        assert!(!any_held_excluding(ProjectOp::Destroy, ""));
+        let _guard = try_acquire(&p, ProjectOp::Destroy).unwrap();
+        assert!(any_held_excluding(ProjectOp::Destroy, ""));
+        // …and a holder can ask the question without its own claim answering
+        // it, which is what lets a compaction sweep leftovers before it starts.
+        assert!(!any_held_excluding(ProjectOp::Destroy, &p));
+    }
+
+    /// Concurrency, not just sequencing: N threads racing for one project must
+    /// produce exactly one winner.
+    #[test]
+    fn exactly_one_of_many_racing_threads_wins() {
+        use std::sync::atomic::{AtomicUsize, Ordering};
+        use std::sync::Arc;
+
+        let p = id("race");
+        let start = Arc::new(std::sync::Barrier::new(8));
+        // The second barrier is what makes this deterministic rather than
+        // merely likely: no winner releases until every thread has had its
+        // turn, so "only one got in" cannot be an artefact of a loser arriving
+        // after the winner already left.
+        let attempted = Arc::new(std::sync::Barrier::new(8));
+        let won = Arc::new(AtomicUsize::new(0));
+        let mut handles = Vec::new();
+        for _ in 0..8 {
+            let start = Arc::clone(&start);
+            let attempted = Arc::clone(&attempted);
+            let won = Arc::clone(&won);
+            let p = p.clone();
+            handles.push(std::thread::spawn(move || {
+                start.wait();
+                let claim = try_acquire(&p, ProjectOp::Compaction);
+                if claim.is_ok() {
+                    won.fetch_add(1, Ordering::SeqCst);
+                }
+                attempted.wait();
+                drop(claim);
+            }));
+        }
+        for handle in handles {
+            handle.join().unwrap();
+        }
+        assert_eq!(
+            won.load(Ordering::SeqCst),
+            1,
+            "eight threads raced for one project and more than one got in"
+        );
+        assert_eq!(held(&p), None);
+    }
+}

app/src-tauri/src/storage/mcp_store.rs

@@ -1,106 +0,0 @@
-use std::fs;
-use std::path::PathBuf;
-use std::sync::Mutex;
-
-use crate::models::McpServer;
-
-pub struct McpStore {
-    servers: Mutex<Vec<McpServer>>,
-    file_path: PathBuf,
-}
-
-impl McpStore {
-    pub fn new() -> Result<Self, String> {
-        let data_dir = dirs::data_dir()
-            .ok_or_else(|| "Could not determine data directory. Set XDG_DATA_HOME on Linux.".to_string())?
-            .join("triple-c");
-
-        fs::create_dir_all(&data_dir).ok();
-
-        let file_path = data_dir.join("mcp_servers.json");
-
-        let servers = if file_path.exists() {
-            match fs::read_to_string(&file_path) {
-                Ok(data) => {
-                    match serde_json::from_str::<Vec<McpServer>>(&data) {
-                        Ok(parsed) => parsed,
-                        Err(e) => {
-                            log::error!("Failed to parse mcp_servers.json: {}. Starting with empty list.", e);
-                            let backup = file_path.with_extension("json.bak");
-                            if let Err(be) = fs::copy(&file_path, &backup) {
-                                log::error!("Failed to back up corrupted mcp_servers.json: {}", be);
-                            }
-                            Vec::new()
-                        }
-                    }
-                }
-                Err(e) => {
-                    log::error!("Failed to read mcp_servers.json: {}", e);
-                    Vec::new()
-                }
-            }
-        } else {
-            Vec::new()
-        };
-
-        Ok(Self {
-            servers: Mutex::new(servers),
-            file_path,
-        })
-    }
-
-    fn lock(&self) -> std::sync::MutexGuard<'_, Vec<McpServer>> {
-        self.servers.lock().unwrap_or_else(|e| e.into_inner())
-    }
-
-    fn save(&self, servers: &[McpServer]) -> Result<(), String> {
-        let data = serde_json::to_string_pretty(servers)
-            .map_err(|e| format!("Failed to serialize MCP servers: {}", e))?;
-
-        // Atomic write: write to temp file, then rename
-        let tmp_path = self.file_path.with_extension("json.tmp");
-        fs::write(&tmp_path, data)
-            .map_err(|e| format!("Failed to write temp MCP servers file: {}", e))?;
-        fs::rename(&tmp_path, &self.file_path)
-            .map_err(|e| format!("Failed to rename MCP servers file: {}", e))?;
-        Ok(())
-    }
-
-    pub fn list(&self) -> Vec<McpServer> {
-        self.lock().clone()
-    }
-
-    pub fn get(&self, id: &str) -> Option<McpServer> {
-        self.lock().iter().find(|s| s.id == id).cloned()
-    }
-
-    pub fn add(&self, server: McpServer) -> Result<McpServer, String> {
-        let mut servers = self.lock();
-        let cloned = server.clone();
-        servers.push(server);
-        self.save(&servers)?;
-        Ok(cloned)
-    }
-
-    pub fn update(&self, updated: McpServer) -> Result<McpServer, String> {
-        let mut servers = self.lock();
-        if let Some(s) = servers.iter_mut().find(|s| s.id == updated.id) {
-            *s = updated.clone();
-            self.save(&servers)?;
-            Ok(updated)
-        } else {
-            Err(format!("MCP server {} not found", updated.id))
-        }
-    }
-
-    pub fn remove(&self, id: &str) -> Result<(), String> {
-        let mut servers = self.lock();
-        let initial_len = servers.len();
-        servers.retain(|s| s.id != id);
-        if servers.len() == initial_len {
-            return Err(format!("MCP server {} not found", id));
-        }
-        self.save(&servers)?;
-        Ok(())
-    }
-}

app/src-tauri/src/storage/migration_store.rs

@@ -0,0 +1,512 @@
+//! Host-side persistence for in-flight container base-image migrations.
+//!
+//! One JSON file per project under `<data_dir>/triple-c/migrations/`, written
+//! with the same write-temp-then-rename dance as `projects.json` so a crash can
+//! never leave a half-written state file. The staged verbatim payload tar lives
+//! in the same directory.
+//!
+//! This is deliberately *not* part of `projects.json`: a migration is transient
+//! and a migration record must survive independently of a project save racing
+//! it. It is also the crash record — see
+//! [`crate::models::MigrationState`] for the phase table.
+
+use std::fs;
+use std::path::PathBuf;
+
+use crate::models::MigrationState;
+
+/// `<data_dir>/triple-c/migrations`, created on demand.
+pub fn migrations_dir() -> Result<PathBuf, String> {
+    let dir = dirs::data_dir()
+        .ok_or_else(|| {
+            "Could not determine data directory. Set XDG_DATA_HOME on Linux.".to_string()
+        })?
+        .join("triple-c")
+        .join("migrations");
+    fs::create_dir_all(&dir)
+        .map_err(|e| format!("Failed to create migrations directory: {}", e))?;
+    Ok(dir)
+}
+
+fn state_path(project_id: &str) -> Result<PathBuf, String> {
+    Ok(migrations_dir()?.join(format!("{}.json", sanitize(project_id))))
+}
+
+/// Host path for a project's staged verbatim payload.
+pub fn staging_path(project_id: &str) -> Result<PathBuf, String> {
+    Ok(migrations_dir()?.join(format!("{}-payload.tar", sanitize(project_id))))
+}
+
+/// Project ids are UUIDs, but they arrive over IPC, so refuse to let one steer
+/// the write anywhere but the migrations directory.
+fn sanitize(project_id: &str) -> String {
+    project_id
+        .chars()
+        .map(|c| if c.is_ascii_alphanumeric() || c == '-' || c == '_' { c } else { '_' })
+        .collect()
+}
+
+/// Read a project's migration state. `Ok(None)` means no migration is in
+/// flight; an unparseable file is treated the same way (and logged) rather than
+/// blocking every future migration on a corrupt record.
+///
+/// **A corrupt record is copied aside and left in place.** An earlier version
+/// *renamed* it to `.bak`, on the reasoning that a file nothing can parse
+/// should stop making the project look busy. That destroyed the one signal
+/// [`has_record`] exists to carry. The chain, in order:
+///
+/// 1. The rename makes the file vanish, so `has_record` — pure filesystem
+///    presence — flips to false.
+/// 2. `reconcile_migration` calls this, gets `Ok(None)`, and returns. An
+///    in-flight or interrupted migration becomes invisible: no resume offer, no
+///    rollback offer, and the phase is never normalised.
+/// 3. Both pin reapers use `has_record` as their conservative guard, so the
+///    project's `:pre-migration-*` tag — the only copy of its pre-migration
+///    system layer — is now "ownerless" to both of them, and the startup sweep
+///    turns the untag into a deletion.
+///
+/// A record that cannot be parsed is exactly the case where the *most*
+/// conservative answer is wanted, not the least. So the bytes are copied to a
+/// **uniquely named** backup (a fixed `.bak` meant a second corruption silently
+/// overwrote the first, and nothing ever read either back) and the original
+/// stays where it is. The pin it describes then ages out through the ownerless
+/// tombstone in `docker::migration::reap_stale_migration_pins` rather than
+/// being reaped on the next app start.
+pub fn load(project_id: &str) -> Result<Option<MigrationState>, String> {
+    let path = state_path(project_id)?;
+    if !path.exists() {
+        return Ok(None);
+    }
+    let data = fs::read_to_string(&path)
+        .map_err(|e| format!("Failed to read migration state: {}", e))?;
+    match serde_json::from_str::<MigrationState>(&data) {
+        Ok(state) => Ok(Some(state)),
+        Err(e) => {
+            // Three outcomes, and they must not be conflated: a copy was made,
+            // a copy was deliberately not made, or a copy failed. The previous
+            // version folded "already kept enough" into `Ok(())` and then told
+            // the user "a copy was kept at <path>" — naming a file that was
+            // never created. A message that invents a backup is worse than no
+            // message, because it is what someone reads before going to look
+            // for their data.
+            let backup = corrupt_backup_path(&path, &chrono::Utc::now());
+            let kept = if backup.exists() {
+                Kept::AlreadyThere
+            } else if corrupt_backups_full(&path) {
+                Kept::EnoughAlready(MAX_CORRUPT_BACKUPS)
+            } else {
+                match fs::copy(&path, &backup) {
+                    Ok(_) => Kept::Copied,
+                    Err(e) => Kept::Failed(e.to_string()),
+                }
+            };
+            log::error!(
+                "Failed to parse migration state for project {}: {} — treating as absent, but \
+                 the record is left in place so `has_record` still protects its rollback pin{}",
+                project_id,
+                e,
+                match kept {
+                    Kept::Copied | Kept::AlreadyThere =>
+                        format!(" (a copy is at {})", backup.display()),
+                    // The earliest copies are the ones worth having, so the cap
+                    // keeps those and drops this one. Say so, rather than
+                    // implying a file exists.
+                    Kept::EnoughAlready(n) => format!(
+                        " (no copy kept — {} earlier copies of this record are already saved \
+                         alongside it)",
+                        n
+                    ),
+                    Kept::Failed(ref e) => format!(" (could not keep a copy: {})", e),
+                }
+            );
+            Ok(None)
+        }
+    }
+}
+
+/// What [`load`] did about a copy of an unparseable record, so the log line can
+/// tell the truth about whether a file exists.
+enum Kept {
+    Copied,
+    /// This exact second's copy was already on disk.
+    AlreadyThere,
+    /// The cap is reached; the earlier copies are kept and this one is not.
+    EnoughAlready(usize),
+    Failed(String),
+}
+
+/// Where a copy of an unparseable record is kept.
+///
+/// Timestamped rather than a fixed `.bak`: a second corruption used to
+/// overwrite the first, so the one case where the user's bytes matter most was
+/// the case where they were most likely to be gone.
+fn corrupt_backup_path(path: &std::path::Path, now: &chrono::DateTime<chrono::Utc>) -> PathBuf {
+    path.with_extension(format!("json.corrupt-{}.bak", now.format("%Y%m%d-%H%M%S")))
+}
+
+/// How many timestamped copies of one project's corrupt record are kept.
+///
+/// Timestamping fixed the "second corruption overwrote the first" bug and
+/// introduced its opposite: [`load`] runs on every reconcile, every survey and
+/// every reaper pass, so a record that is *persistently* unparseable — the
+/// normal case, since nothing repairs it — mints a new copy every time the
+/// clock's second changes. Nothing ever reads them back and nothing ever
+/// removed them.
+///
+/// Four is enough for the only use there is: a human looking at what the file
+/// held. See [`corrupt_backups_full`] for why the cap is applied before the
+/// copy rather than by pruning after it.
+const MAX_CORRUPT_BACKUPS: usize = 4;
+
+/// Whether [`MAX_CORRUPT_BACKUPS`] copies of this record already exist.
+///
+/// Asked *before* the copy rather than pruning after it, so the cap is not
+/// implemented by writing a file and deleting it again on every pass — and so
+/// the copies that survive are the oldest, which are the ones taken closest to
+/// whatever produced the corruption.
+///
+/// A directory that cannot be listed answers "not full": failing open here
+/// costs at most one extra file, and failing closed would drop the very first
+/// copy of a record nothing else has kept.
+fn corrupt_backups_full(path: &std::path::Path) -> bool {
+    let (Some(dir), Some(stem)) = (path.parent(), path.file_stem()) else {
+        return false;
+    };
+    // `{stem}.json.corrupt-` — the same shape `corrupt_backup_path` builds, so
+    // this can never match another project's copies or an unrelated `.bak`.
+    let prefix = format!("{}.json.corrupt-", stem.to_string_lossy());
+    let Ok(entries) = fs::read_dir(dir) else {
+        return false;
+    };
+    entries
+        .flatten()
+        .filter(|e| {
+            let name = e.file_name().to_string_lossy().to_string();
+            name.starts_with(&prefix) && name.ends_with(".bak")
+        })
+        .count()
+        >= MAX_CORRUPT_BACKUPS
+}
+
+/// Whether a project has a migration record on disk *at all*, without parsing
+/// it.
+///
+/// The pin reaper needs "is this project's rollback image still somebody's only
+/// copy?" and must answer it conservatively. [`load`] cannot be used for that
+/// question on its own — it deliberately reports a corrupt record as absent —
+/// so this asks the filesystem instead. `load` moving a corrupt record aside is
+/// what keeps the two answers from disagreeing forever.
+pub fn has_record(project_id: &str) -> Result<bool, String> {
+    Ok(state_path(project_id)?.exists())
+}
+
+/// Atomically **and durably** write a project's migration state.
+///
+/// Write-temp-then-rename alone is only half of it, and the missing half is the
+/// half this record exists for. `fs::write` returns once the bytes are in the
+/// page cache; a rename over them is atomic *with respect to other readers*,
+/// not with respect to power loss. Losing power in that window leaves the
+/// rename applied and the data not yet written — i.e. a 0-byte or truncated
+/// `{id}.json` — which is precisely the corrupt-record case above, produced by
+/// the code whose job is to make that case impossible.
+///
+/// So: fsync the file before the rename, and fsync the *directory* after it,
+/// because the rename itself is directory metadata and is not durable until the
+/// directory is synced. A sync that fails is reported rather than swallowed —
+/// this is the crash record, and "probably written" is not a state it may be
+/// in.
+pub fn save(project_id: &str, state: &MigrationState) -> Result<(), String> {
+    let path = state_path(project_id)?;
+    let data = serde_json::to_string_pretty(state)
+        .map_err(|e| format!("Failed to serialize migration state: {}", e))?;
+    let tmp = path.with_extension("json.tmp");
+
+    {
+        use std::io::Write;
+        let mut file = fs::File::create(&tmp)
+            .map_err(|e| format!("Failed to write migration state: {}", e))?;
+        file.write_all(data.as_bytes())
+            .map_err(|e| format!("Failed to write migration state: {}", e))?;
+        file.sync_all()
+            .map_err(|e| format!("Failed to flush migration state to disk: {}", e))?;
+    }
+
+    fs::rename(&tmp, &path).map_err(|e| format!("Failed to commit migration state: {}", e))?;
+    sync_dir(&path);
+    // A project with a record is not ownerless, whatever a reaper concluded
+    // before this write — so the grace clock is thrown away rather than left to
+    // expire against a pin that now has an owner again.
+    clear_ownerless_for_project(project_id);
+    Ok(())
+}
+
+/// fsync the directory holding `path`, so a rename into it survives power loss.
+///
+/// Best effort *only* on the platforms where it is meaningless: Windows has no
+/// directory handle to sync and returns an error for the attempt, so a failure
+/// is logged rather than propagated. The file's own `sync_all` above is the
+/// part that carries the data, and it is not best effort.
+fn sync_dir(path: &std::path::Path) {
+    let Some(dir) = path.parent() else {
+        return;
+    };
+    match fs::File::open(dir).and_then(|d| d.sync_all()) {
+        Ok(()) => {}
+        Err(e) => log::debug!(
+            "Could not fsync the migrations directory {}: {} — the record itself was flushed",
+            dir.display(),
+            e
+        ),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Ownerless-pin tombstones
+// ---------------------------------------------------------------------------
+
+/// Marker recording **when a rollback pin was first seen with no record behind
+/// it**.
+///
+/// ## Why the grace period cannot be measured from the tag
+///
+/// `docker::migration::pin_is_reapable` used to date a pin from the timestamp
+/// encoded in `pre-migration-<YYYYmmdd-HHMMSS>` — i.e. from when the migration
+/// *started*. That is the wrong epoch by a whole feature. A migration is
+/// allowed to sit at `awaiting-confirmation` indefinitely; `keep_rollback`
+/// exists precisely so a user can run on the new base for a month before
+/// deciding. If that project's record is then lost — a corrupt file, a deleted
+/// state file, a half-restored data directory — the pin is fourteen days old on
+/// the very first check, so it is untagged on the next app start and the
+/// startup sweep deletes the image two lines later. The fourteen-day grace
+/// period the constant promises is zero in the only situation it was written
+/// for.
+///
+/// The clock has to start when the *claim* was lost, and nothing on the daemon
+/// records that moment. So it is written down here, the first time a reaper
+/// notices, and the age is measured from the marker.
+///
+/// One file per `(project_id, tag)` in the migrations directory, holding an
+/// RFC3339 instant. Tiny, and losing one costs a fresh fourteen days rather
+/// than a deletion — the failure direction that keeps somebody's only rollback
+/// copy.
+fn ownerless_marker_path(project_id: &str, tag: &str) -> Result<PathBuf, String> {
+    Ok(migrations_dir()?.join(format!(
+        "{}.{}.ownerless",
+        sanitize(project_id),
+        sanitize(tag)
+    )))
+}
+
+/// Read the first-observed instant for a pin, creating the marker if this is
+/// the first sighting. Returns `None` when the clock has not started yet.
+///
+/// **Clock skew is handled here rather than at the comparison.** A host clock
+/// that was running fast when the marker was written leaves a timestamp in the
+/// future; measured naively that is a negative age, which a `num_days() >= 14`
+/// test reads as "never reapable" — a pin that can never be collected, forever.
+/// A marker dated after `now` is therefore rewritten to `now`, restarting the
+/// grace period. The other direction — a clock jumping forward — cannot shorten
+/// the period below what has actually elapsed on the *marker's* terms, because
+/// there is nothing to compare against but wall time; what it cannot do any
+/// more is make every pin instantly reapable, which dating from the tag did.
+///
+/// ## Why the write re-checks `has_record`
+///
+/// Both reapers ask [`has_record`] and only call this when the answer is no,
+/// which leaves a window: a [`save`] landing between the two runs its
+/// `clear_ownerless_for_project` against a marker that does not exist yet, and
+/// this then plants one — dated *now* — behind a perfectly valid record. The
+/// marker is invisible while the record stands, so nothing notices. It only
+/// matters later, if that record is legitimately lost: the pin is then already
+/// fourteen days ownerless on its very first check and is reaped with **zero**
+/// grace, which is the exact failure the tombstone exists to prevent.
+///
+/// So the write is followed by a second `has_record`, and a marker that turns
+/// out to sit behind a record is removed again. The two orderings that remain
+/// are both safe: a `save` completing *after* this re-check clears the marker
+/// itself, and one completing before it is what the re-check sees.
+pub fn note_ownerless_since(
+    project_id: &str,
+    tag: &str,
+    now: &chrono::DateTime<chrono::Utc>,
+) -> Option<chrono::DateTime<chrono::Utc>> {
+    let path = ownerless_marker_path(project_id, tag).ok()?;
+    let existing = fs::read_to_string(&path).ok().and_then(|raw| {
+        chrono::DateTime::parse_from_rfc3339(raw.trim())
+            .ok()
+            .map(|t| t.with_timezone(&chrono::Utc))
+    });
+    match existing {
+        Some(seen) if seen <= *now => Some(seen),
+        // Absent, unparseable, or dated in the future: (re)start the clock.
+        _ => {
+            if let Err(e) = fs::write(&path, now.to_rfc3339()) {
+                log::warn!(
+                    "Could not record that rollback pin {}:{} is ownerless: {} — its grace \
+                     period restarts on the next check",
+                    project_id,
+                    tag,
+                    e
+                );
+                return None;
+            }
+            // A record that appeared while this was being written owns the pin,
+            // and a tombstone behind an owned pin is a fourteen-day head start
+            // on reaping it the moment that record is next lost.
+            if has_record(project_id).unwrap_or(false) {
+                log::debug!(
+                    "A migration record for {} appeared while marking {} ownerless; \
+                     the marker was dropped again",
+                    project_id,
+                    tag
+                );
+                clear_ownerless(project_id, tag);
+            }
+            None
+        }
+    }
+}
+
+/// Forget a pin's ownerless marker. Missing is success.
+///
+/// Called when the pin is untagged, and when a record reappears for the
+/// project — a re-migrated project must not inherit the previous run's clock.
+pub fn clear_ownerless(project_id: &str, tag: &str) {
+    let Ok(path) = ownerless_marker_path(project_id, tag) else {
+        return;
+    };
+    match fs::remove_file(&path) {
+        Ok(()) => {}
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
+        Err(e) => log::warn!("Could not remove {}: {}", path.display(), e),
+    }
+}
+
+/// Drop every ownerless marker belonging to one project.
+///
+/// A project that has a record again is by definition not ownerless, whatever
+/// a reaper concluded before.
+pub fn clear_ownerless_for_project(project_id: &str) {
+    let Ok(dir) = migrations_dir() else {
+        return;
+    };
+    let prefix = format!("{}.", sanitize(project_id));
+    let Ok(entries) = fs::read_dir(&dir) else {
+        return;
+    };
+    for entry in entries.flatten() {
+        let name = entry.file_name().to_string_lossy().to_string();
+        if name.starts_with(&prefix) && name.ends_with(".ownerless") {
+            let _ = fs::remove_file(entry.path());
+        }
+    }
+}
+
+/// Remove a project's migration state file. Missing is success.
+pub fn clear(project_id: &str) -> Result<(), String> {
+    let path = state_path(project_id)?;
+    match fs::remove_file(&path) {
+        Ok(()) => Ok(()),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(e) => Err(format!("Failed to remove migration state: {}", e)),
+    }
+}
+
+/// Remove a project's staged payload. Missing is success.
+pub fn clear_staging(project_id: &str) -> Result<(), String> {
+    let path = staging_path(project_id)?;
+    match fs::remove_file(&path) {
+        Ok(()) => Ok(()),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(e) => Err(format!("Failed to remove staged migration payload: {}", e)),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn corrupt_copies_of_one_record_are_capped() {
+        // `load` runs on every reconcile, every survey and every reaper pass,
+        // and nothing repairs an unparseable record — so a persistently corrupt
+        // one minted a new timestamped copy every time the clock's second
+        // changed, and nothing ever removed them.
+        let dir = std::env::temp_dir().join(format!(
+            "triple-c-corrupt-cap-{}",
+            uuid::Uuid::new_v4().simple()
+        ));
+        fs::create_dir_all(&dir).expect("temp dir");
+        let record = dir.join("some-project.json");
+
+        assert!(!corrupt_backups_full(&record), "an empty directory is not full");
+        for n in 0..MAX_CORRUPT_BACKUPS {
+            fs::write(
+                dir.join(format!("some-project.json.corrupt-2026010{}-000000.bak", n)),
+                "x",
+            )
+            .unwrap();
+        }
+        assert!(corrupt_backups_full(&record));
+
+        // Another project's copies, and an unrelated `.bak`, are not this
+        // record's — the prefix is the whole point of the naming.
+        let other = dir.join("other-project.json");
+        assert!(!corrupt_backups_full(&other));
+        fs::write(dir.join("some-project.json.bak"), "x").unwrap();
+        assert!(!corrupt_backups_full(&other));
+
+        fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn project_ids_cannot_escape_the_migrations_directory() {
+        assert_eq!(sanitize("../../etc/passwd"), "______etc_passwd");
+        assert_eq!(sanitize("a/b"), "a_b");
+        // The real shape — a UUID — must survive untouched, or state files
+        // would move the first time this function changed.
+        assert_eq!(
+            sanitize("ab62cd24-51aa-4645-8f5c-17a124062050"),
+            "ab62cd24-51aa-4645-8f5c-17a124062050"
+        );
+    }
+
+    /// The log line must not name a backup that was never written.
+    ///
+    /// `load` runs on every reconcile, every survey and every reaper pass, so a
+    /// persistently corrupt record hits the `MAX_CORRUPT_BACKUPS` cap within
+    /// seconds. The previous code folded "already kept enough" into `Ok(())`
+    /// and then reported " (a copy was kept at <path>)" — pointing at a file
+    /// that does not exist. That is the message someone reads immediately
+    /// before going to look for their data.
+    #[test]
+    fn the_corrupt_record_message_only_claims_a_copy_that_exists() {
+        let dir = std::env::temp_dir().join(format!(
+            "tc-mstore-{}",
+            uuid::Uuid::new_v4().simple()
+        ));
+        std::fs::create_dir_all(&dir).unwrap();
+        let path = dir.join("p.json");
+        std::fs::write(&path, b"{ not json").unwrap();
+
+        // Fill the cap with copies that really are on disk.
+        for i in 0..MAX_CORRUPT_BACKUPS {
+            let b = path.with_extension(format!("json.corrupt-2026010{}-000000.bak", i));
+            std::fs::write(&b, b"{ not json").unwrap();
+        }
+        assert!(corrupt_backups_full(&path), "precondition: the cap is reached");
+
+        // With the cap reached, no new copy may be created — and that is the
+        // state in which the old message lied.
+        let before: Vec<_> = std::fs::read_dir(&dir).unwrap().flatten().collect();
+        let fresh = corrupt_backup_path(&path, &chrono::Utc::now());
+        assert!(
+            !fresh.exists(),
+            "the cap is reached, so this timestamped copy must not be written"
+        );
+        let after: Vec<_> = std::fs::read_dir(&dir).unwrap().flatten().collect();
+        assert_eq!(before.len(), after.len(), "nothing new appeared on disk");
+
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}

app/src-tauri/src/storage/mod.rs

@@ -1,7 +1,10 @@
+pub mod migration_store;
+pub mod notes_store;
+pub mod pending_cleanup;
 pub mod projects_store;
 pub mod secure;
+pub mod settings_crypto;
 pub mod settings_store;
-pub mod mcp_store;
 
 #[allow(unused_imports)]
 pub use projects_store::*;
@@ -9,5 +12,3 @@ pub use projects_store::*;
 pub use secure::*;
 #[allow(unused_imports)]
 pub use settings_store::*;
-#[allow(unused_imports)]
-pub use mcp_store::*;

app/src-tauri/src/storage/notes_store.rs

@@ -0,0 +1,593 @@
+//! Host-side persistence for per-project notes.
+//!
+//! One JSON file per project under `<data_dir>/triple-c/notes/`, on the same
+//! free-function shape as `migration_store` — no struct, nothing in
+//! `AppState`, no in-memory copy. `ProjectsStore` holds a `Mutex` because it
+//! caches the project list; a store that reads and writes the file per call
+//! has nothing to cache and nothing to guard.
+//!
+//! Deliberately *not* a field on `Project`. `projects.json` is rewritten on
+//! every blur by the debounced-nothing save path in `useSaveState`, so notes
+//! there would mean the whole project list is rewritten per edit, and a note
+//! save racing a Config save would silently drop one of them.
+
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::sync::{Mutex, OnceLock};
+
+use serde::{Deserialize, Serialize};
+
+use crate::models::Note;
+
+/// The version stamped into every notes file this build writes.
+const NOTES_FORMAT_VERSION: u32 = 1;
+
+/// What is actually on disk: a version envelope around the notes.
+///
+/// The list is wrapped rather than written bare because the wrapper costs
+/// nothing today and cannot be added cheaply later — once files exist in the
+/// field, every reader has to sniff two shapes forever. `version` is written
+/// and read back but nothing branches on it yet: it is the hook a future
+/// format change hangs off, and its value is only useful if it has been there
+/// since the first file.
+///
+/// Not in `models/` and not exposed over IPC: the frontend receives
+/// `Vec<Note>` from `list_notes` and never sees the envelope, so this is a
+/// storage detail rather than part of the IPC contract.
+#[derive(Debug, Serialize, Deserialize)]
+struct ProjectNotes {
+    version: u32,
+    #[serde(default)]
+    notes: Vec<Note>,
+}
+
+/// Serialises the read-modify-write half of an upsert or delete.
+///
+/// Nothing here is cached, so there is no shared state to protect — but an
+/// upsert reads the whole file, edits one entry and writes it back, and two of
+/// those interleaving would lose whichever note was written first. The read
+/// path does not take it.
+fn write_lock() -> &'static Mutex<()> {
+    static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    LOCK.get_or_init(|| Mutex::new(()))
+}
+
+/// `<data_dir>/triple-c/notes`, created on demand.
+pub fn notes_dir() -> Result<PathBuf, String> {
+    let dir = dirs::data_dir()
+        .ok_or_else(|| {
+            "Could not determine data directory. Set XDG_DATA_HOME on Linux.".to_string()
+        })?
+        .join("triple-c")
+        .join("notes");
+    fs::create_dir_all(&dir).map_err(|e| format!("Failed to create notes directory: {}", e))?;
+    Ok(dir)
+}
+
+/// Project ids are UUIDs, but they arrive over IPC, so refuse to let one steer
+/// the write anywhere but the notes directory.
+fn sanitize(project_id: &str) -> String {
+    project_id
+        .chars()
+        .map(|c| if c.is_ascii_alphanumeric() || c == '-' || c == '_' { c } else { '_' })
+        .collect()
+}
+
+fn notes_path_in(dir: &Path, project_id: &str) -> PathBuf {
+    dir.join(format!("{}.json", sanitize(project_id)))
+}
+
+// ── Public API. Each resolves the real directory, then defers to the `_in`
+// variant, which is what the tests exercise against a temp dir. `ProjectsStore`
+// hardcodes `dirs::data_dir()` in its constructor and is therefore untestable
+// as a unit; this store does not inherit that. ─────────────────────────────
+
+pub fn load(project_id: &str) -> Result<Vec<Note>, String> {
+    load_in(&notes_dir()?, project_id)
+}
+
+pub fn upsert(project_id: &str, note: Note) -> Result<Note, String> {
+    upsert_in(&notes_dir()?, project_id, note)
+}
+
+pub fn delete(project_id: &str, note_id: &str) -> Result<(), String> {
+    delete_in(&notes_dir()?, project_id, note_id)
+}
+
+/// Remove a project's notes file entirely. Missing is success.
+pub fn clear(project_id: &str) -> Result<(), String> {
+    clear_in(&notes_dir()?, project_id)
+}
+
+// ── Implementation ─────────────────────────────────────────────────────────
+
+/// Read a project's notes. A missing file is an empty list.
+///
+/// **An unparseable file is copied aside and left in place**, then reported as
+/// empty. Erroring instead would make the Notes tab permanently unusable for
+/// that project with no way out through the UI; deleting instead would destroy
+/// the only copy of what the user wrote. The copy is timestamped so a second
+/// corruption cannot overwrite the first — which is the one taken before
+/// anything rewrote the file, and therefore the one worth having — and capped,
+/// because `list_notes` runs on *every* panel mount. See [`keep_corrupt_copy`].
+fn load_in(dir: &Path, project_id: &str) -> Result<Vec<Note>, String> {
+    let path = notes_path_in(dir, project_id);
+    if !path.exists() {
+        return Ok(Vec::new());
+    }
+    let data = fs::read_to_string(&path).map_err(|e| format!("Failed to read notes: {}", e))?;
+    match parse(&data) {
+        Ok(notes) => Ok(notes),
+        Err(e) => {
+            let kept = keep_corrupt_copy(&path, &chrono::Utc::now());
+            log::error!(
+                "Failed to parse notes for project {}: {} — treating as empty; the file is \
+                 left in place{}",
+                project_id,
+                e,
+                kept.describe()
+            );
+            Ok(Vec::new())
+        }
+    }
+}
+
+/// Parse a notes file: the versioned envelope, or a bare array.
+///
+/// The bare array is what this store wrote before [`ProjectNotes`] existed —
+/// only ever on a development build, but a developer's own notes are still
+/// prose nothing else holds a copy of, and the alternative is `load_in`
+/// declaring a perfectly readable file corrupt. It is read, never written: the
+/// first save rewrites the file with an envelope.
+fn parse(data: &str) -> Result<Vec<Note>, serde_json::Error> {
+    match serde_json::from_str::<ProjectNotes>(data) {
+        Ok(file) => Ok(file.notes),
+        // Report the envelope's error, not the array's — the envelope is the
+        // shape this store writes, so its message is the one that describes
+        // what is actually wrong with the file.
+        Err(envelope_err) => serde_json::from_str::<Vec<Note>>(data).map_err(|_| envelope_err),
+    }
+}
+
+/// How many timestamped copies of one project's corrupt notes file are kept.
+///
+/// Timestamping fixes "a second corruption overwrote the first" and introduces
+/// its opposite: `load_in` runs on every `list_notes`, which is every panel
+/// mount — every project switch, every dock-follows-tab change, every sub-tab
+/// toggle. A file that is *persistently* unparseable (the normal case, since
+/// nothing repairs it) would otherwise mint a fresh full copy of the user's
+/// prose every time the clock's second changed. Nothing ever reads them back
+/// and nothing ever removed them.
+///
+/// Four is enough for the only use there is: a human looking at what the file
+/// held. Same constant, same reasoning as `migration_store`.
+const MAX_CORRUPT_BACKUPS: usize = 4;
+
+/// What [`keep_corrupt_copy`] did, so the log line can tell the truth about
+/// whether a file exists.
+///
+/// Three outcomes, and they must not be conflated. Folding "already kept
+/// enough" into success and then saying "a copy was kept" names a file that
+/// was never created — which is what someone reads before going to look for
+/// their data.
+enum Kept {
+    Copied(PathBuf),
+    /// This exact second's copy was already on disk.
+    AlreadyThere(PathBuf),
+    /// The cap is reached; the earlier copies are kept and this one is not.
+    EnoughAlready(usize),
+    Failed(String),
+}
+
+impl Kept {
+    fn describe(&self) -> String {
+        match self {
+            Kept::Copied(p) | Kept::AlreadyThere(p) => format!(" (a copy is at {})", p.display()),
+            // The earliest copies are the ones worth having, so the cap keeps
+            // those and drops this one. Say so, rather than implying a file
+            // exists.
+            Kept::EnoughAlready(n) => format!(
+                " (no copy kept — {} earlier copies of this file are already saved alongside it)",
+                n
+            ),
+            Kept::Failed(e) => format!(" (could not keep a copy: {})", e),
+        }
+    }
+}
+
+/// Where a copy of an unreadable notes file is kept.
+fn corrupt_backup_path(path: &Path, now: &chrono::DateTime<chrono::Utc>) -> PathBuf {
+    path.with_extension(format!("json.corrupt-{}.bak", now.format("%Y%m%d-%H%M%S")))
+}
+
+/// Whether [`MAX_CORRUPT_BACKUPS`] copies of this project's file already exist.
+///
+/// Asked *before* the copy rather than pruning after it, so the cap is not
+/// implemented by writing a file and deleting it again on every pass — and so
+/// the copies that survive are the oldest, which are the ones taken closest to
+/// whatever produced the corruption.
+///
+/// A directory that cannot be listed answers "not full": failing open costs at
+/// most one extra file, and failing closed would drop the very first copy of
+/// prose nothing else has kept.
+fn corrupt_backups_full(path: &Path) -> bool {
+    let (Some(dir), Some(stem)) = (path.parent(), path.file_stem()) else {
+        return false;
+    };
+    // `{stem}.json.corrupt-` — the same shape `corrupt_backup_path` builds, so
+    // this can never match another project's copies or an unrelated `.bak`.
+    let prefix = format!("{}.json.corrupt-", stem.to_string_lossy());
+    let Ok(entries) = fs::read_dir(dir) else {
+        return false;
+    };
+    entries
+        .flatten()
+        .filter(|e| {
+            let name = e.file_name().to_string_lossy().to_string();
+            name.starts_with(&prefix) && name.ends_with(".bak")
+        })
+        .count()
+        >= MAX_CORRUPT_BACKUPS
+}
+
+fn keep_corrupt_copy(path: &Path, now: &chrono::DateTime<chrono::Utc>) -> Kept {
+    let backup = corrupt_backup_path(path, now);
+    if backup.exists() {
+        return Kept::AlreadyThere(backup);
+    }
+    if corrupt_backups_full(path) {
+        return Kept::EnoughAlready(MAX_CORRUPT_BACKUPS);
+    }
+    match fs::copy(path, &backup) {
+        Ok(_) => Kept::Copied(backup),
+        Err(e) => Kept::Failed(e.to_string()),
+    }
+}
+
+/// Insert or replace one note, leaving the rest untouched.
+///
+/// `created_at` and `id` are the store's, not the caller's: the webview sends
+/// a whole `Note` back and must not be able to rewrite when a note was made.
+/// `updated_at` is stamped here for the same reason.
+fn upsert_in(dir: &Path, project_id: &str, mut note: Note) -> Result<Note, String> {
+    let _guard = write_lock().lock().unwrap_or_else(|e| e.into_inner());
+    let mut notes = load_in(dir, project_id)?;
+    note.updated_at = chrono::Utc::now().to_rfc3339();
+    match notes.iter_mut().find(|n| n.id == note.id) {
+        Some(existing) => {
+            note.created_at = existing.created_at.clone();
+            *existing = note.clone();
+        }
+        None => notes.push(note.clone()),
+    }
+    save_all(dir, project_id, &notes)?;
+    Ok(note)
+}
+
+/// Remove one note. Removing one that is already gone is success — the UI can
+/// retry a delete whose result it never saw.
+fn delete_in(dir: &Path, project_id: &str, note_id: &str) -> Result<(), String> {
+    let _guard = write_lock().lock().unwrap_or_else(|e| e.into_inner());
+    let mut notes = load_in(dir, project_id)?;
+    let before = notes.len();
+    notes.retain(|n| n.id != note_id);
+    if notes.len() == before {
+        return Ok(());
+    }
+    save_all(dir, project_id, &notes)
+}
+
+fn clear_in(dir: &Path, project_id: &str) -> Result<(), String> {
+    let _guard = write_lock().lock().unwrap_or_else(|e| e.into_inner());
+    let path = notes_path_in(dir, project_id);
+    match fs::remove_file(&path) {
+        Ok(()) => Ok(()),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(e) => Err(format!("Failed to remove notes: {}", e)),
+    }
+}
+
+/// Atomically **and durably** write the whole list.
+///
+/// Write-temp-then-rename alone is only half of it. `fs::write` returns once
+/// the bytes are in the page cache; the rename is atomic with respect to other
+/// readers, not to power loss. Losing power in that window leaves the rename
+/// applied and the data not written — a truncated file, produced by the code
+/// whose job is to prevent one. So the file is fsynced before the rename and
+/// the directory after it, since the rename is directory metadata. Notes are
+/// prose the user typed and nothing else holds a copy.
+fn save_all(dir: &Path, project_id: &str, notes: &[Note]) -> Result<(), String> {
+    let path = notes_path_in(dir, project_id);
+    let file = ProjectNotes {
+        version: NOTES_FORMAT_VERSION,
+        notes: notes.to_vec(),
+    };
+    let data = serde_json::to_string_pretty(&file)
+        .map_err(|e| format!("Failed to serialize notes: {}", e))?;
+    let tmp = path.with_extension("json.tmp");
+
+    {
+        use std::io::Write;
+        let mut file =
+            fs::File::create(&tmp).map_err(|e| format!("Failed to write notes: {}", e))?;
+        file.write_all(data.as_bytes())
+            .map_err(|e| format!("Failed to write notes: {}", e))?;
+        file.sync_all()
+            .map_err(|e| format!("Failed to flush notes to disk: {}", e))?;
+    }
+
+    fs::rename(&tmp, &path).map_err(|e| format!("Failed to commit notes: {}", e))?;
+    sync_dir(&path);
+    Ok(())
+}
+
+/// fsync the directory holding `path`, so the rename survives power loss.
+///
+/// Best effort only where it is meaningless: Windows has no directory handle
+/// to sync and returns an error for the attempt, so a failure is logged rather
+/// than propagated. The file's own `sync_all` carries the data and is not best
+/// effort.
+fn sync_dir(path: &Path) {
+    let Some(dir) = path.parent() else { return };
+    if let Err(e) = fs::File::open(dir).and_then(|d| d.sync_all()) {
+        log::debug!(
+            "Could not fsync the notes directory {}: {} — the file itself was flushed",
+            dir.display(),
+            e
+        );
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn temp_dir(tag: &str) -> std::path::PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "triple-c-notes-{}-{}",
+            tag,
+            uuid::Uuid::new_v4().simple()
+        ));
+        std::fs::create_dir_all(&dir).expect("temp dir");
+        dir
+    }
+
+    fn corrupt_copies(dir: &std::path::Path) -> Vec<String> {
+        std::fs::read_dir(dir)
+            .unwrap()
+            .flatten()
+            .map(|e| e.file_name().to_string_lossy().to_string())
+            .filter(|n| n.contains(".corrupt-"))
+            .collect()
+    }
+
+    #[test]
+    fn project_ids_cannot_escape_the_notes_directory() {
+        // The id arrives over IPC. It must not be able to steer the write.
+        assert_eq!(sanitize("../../etc/passwd"), "______etc_passwd");
+        assert_eq!(sanitize("a/b"), "a_b");
+        assert_eq!(sanitize("a\\b"), "a_b");
+        // A real UUID must survive untouched, or every note file would move
+        // the first time this function changed.
+        assert_eq!(
+            sanitize("ab62cd24-51aa-4645-8f5c-17a124062050"),
+            "ab62cd24-51aa-4645-8f5c-17a124062050"
+        );
+    }
+
+    #[test]
+    fn a_missing_file_is_an_empty_list_not_an_error() {
+        let dir = temp_dir("missing");
+        assert_eq!(load_in(&dir, "nobody").unwrap(), Vec::<Note>::new());
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn an_upserted_note_round_trips() {
+        let dir = temp_dir("roundtrip");
+        let note = Note::new("Deploy steps".into(), "one\ntwo".into());
+        let saved = upsert_in(&dir, "p1", note.clone()).unwrap();
+        assert_eq!(saved.id, note.id);
+
+        let loaded = load_in(&dir, "p1").unwrap();
+        assert_eq!(loaded.len(), 1);
+        assert_eq!(loaded[0].body, "one\ntwo");
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn upserting_an_existing_id_replaces_it_and_keeps_created_at() {
+        let dir = temp_dir("replace");
+        let mut note = Note::new("Title".into(), "first".into());
+        upsert_in(&dir, "p1", note.clone()).unwrap();
+
+        note.body = "second".into();
+        note.created_at = "1999-01-01T00:00:00Z".into(); // a client must not rewrite this
+        let saved = upsert_in(&dir, "p1", note.clone()).unwrap();
+
+        let loaded = load_in(&dir, "p1").unwrap();
+        assert_eq!(loaded.len(), 1, "an upsert must not append a duplicate");
+        assert_eq!(loaded[0].body, "second");
+        assert_ne!(
+            saved.created_at, "1999-01-01T00:00:00Z",
+            "created_at is owned by the store, not by whatever the webview sent"
+        );
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn deleting_a_note_leaves_the_others_and_a_missing_one_is_success() {
+        let dir = temp_dir("delete");
+        let keep = upsert_in(&dir, "p1", Note::new("keep".into(), "".into())).unwrap();
+        let drop = upsert_in(&dir, "p1", Note::new("drop".into(), "".into())).unwrap();
+
+        delete_in(&dir, "p1", &drop.id).unwrap();
+        let loaded = load_in(&dir, "p1").unwrap();
+        assert_eq!(loaded.len(), 1);
+        assert_eq!(loaded[0].id, keep.id);
+
+        // Idempotent: removing what is already gone is not an error, because
+        // the UI can retry a delete it never saw the result of.
+        delete_in(&dir, "p1", &drop.id).unwrap();
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn an_unreadable_file_is_copied_aside_and_reads_as_empty() {
+        // Same reasoning as migration_store: a corrupt file must not make the
+        // tab permanently unusable, and the bytes must not be destroyed.
+        let dir = temp_dir("corrupt");
+        let path = notes_path_in(&dir, "p1");
+        std::fs::write(&path, b"{ not json").unwrap();
+
+        assert_eq!(load_in(&dir, "p1").unwrap(), Vec::<Note>::new());
+        assert!(path.exists(), "the unreadable file is left in place");
+
+        assert_eq!(
+            corrupt_copies(&dir).len(),
+            1,
+            "the bytes must be kept exactly once"
+        );
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn what_is_written_is_a_version_envelope_not_a_bare_array() {
+        // The envelope costs nothing now and cannot be added cheaply once
+        // files exist in the field, so the very first file has to carry it.
+        let dir = temp_dir("envelope");
+        upsert_in(&dir, "p1", Note::new("t".into(), "b".into())).unwrap();
+
+        let raw = std::fs::read_to_string(notes_path_in(&dir, "p1")).unwrap();
+        let parsed: serde_json::Value = serde_json::from_str(&raw).unwrap();
+        assert_eq!(parsed["version"], NOTES_FORMAT_VERSION);
+        assert_eq!(parsed["notes"].as_array().unwrap().len(), 1);
+        assert_eq!(parsed["notes"][0]["body"], "b");
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn a_pre_envelope_bare_array_still_reads_and_is_not_called_corrupt() {
+        // Only a development build ever wrote this shape, but declaring a
+        // perfectly readable file corrupt is the one outcome this store exists
+        // to avoid. It is read, never written back.
+        let dir = temp_dir("legacy");
+        let note = Note::new("Deploy".into(), "one\ntwo".into());
+        std::fs::write(
+            notes_path_in(&dir, "p1"),
+            serde_json::to_string(&vec![note.clone()]).unwrap(),
+        )
+        .unwrap();
+
+        let loaded = load_in(&dir, "p1").unwrap();
+        assert_eq!(loaded.len(), 1);
+        assert_eq!(loaded[0].body, "one\ntwo");
+        let copies = corrupt_copies(&dir);
+        assert!(copies.is_empty(), "a readable file must not be copied aside");
+
+        // The next write upgrades it in place.
+        upsert_in(&dir, "p1", note).unwrap();
+        let raw = std::fs::read_to_string(notes_path_in(&dir, "p1")).unwrap();
+        assert!(raw.contains("\"version\""));
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn corrupt_copies_are_capped_rather_than_one_per_second() {
+        // `list_notes` runs on every panel mount, so an unrepaired file would
+        // otherwise mint a full copy of the user's prose every time the
+        // clock's second changed.
+        let dir = temp_dir("cap");
+        let path = notes_path_in(&dir, "p1");
+        std::fs::write(&path, b"{ not json").unwrap();
+
+        let base = chrono::Utc::now();
+        for i in 0..MAX_CORRUPT_BACKUPS as i64 + 3 {
+            let at = base + chrono::Duration::seconds(i);
+            let kept = keep_corrupt_copy(&path, &at);
+            if i < MAX_CORRUPT_BACKUPS as i64 {
+                assert!(matches!(kept, Kept::Copied(_)), "copy {} should be kept", i);
+            } else {
+                assert!(
+                    matches!(kept, Kept::EnoughAlready(MAX_CORRUPT_BACKUPS)),
+                    "copy {} should be refused by the cap",
+                    i
+                );
+            }
+        }
+        assert_eq!(corrupt_copies(&dir).len(), MAX_CORRUPT_BACKUPS);
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn a_second_read_in_the_same_second_does_not_re_copy() {
+        let dir = temp_dir("samesecond");
+        let path = notes_path_in(&dir, "p1");
+        std::fs::write(&path, b"{ not json").unwrap();
+
+        let at = chrono::Utc::now();
+        assert!(matches!(keep_corrupt_copy(&path, &at), Kept::Copied(_)));
+        assert!(matches!(
+            keep_corrupt_copy(&path, &at),
+            Kept::AlreadyThere(_)
+        ));
+        assert_eq!(corrupt_copies(&dir).len(), 1);
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn the_log_line_never_claims_a_backup_that_was_not_written() {
+        // A message that invents a backup is worse than no message: it is what
+        // someone reads before going to look for their data.
+        let dir = temp_dir("honesty");
+        let path = notes_path_in(&dir, "p1");
+        std::fs::write(&path, b"{ not json").unwrap();
+
+        let copied = keep_corrupt_copy(&path, &chrono::Utc::now()).describe();
+        assert!(copied.contains("a copy is at"));
+
+        let refused = Kept::EnoughAlready(MAX_CORRUPT_BACKUPS).describe();
+        assert!(refused.contains("no copy kept"));
+        assert!(!refused.contains("a copy is at"));
+
+        let failed = Kept::Failed("permission denied".into()).describe();
+        assert!(failed.contains("could not keep a copy"));
+        assert!(!failed.contains("a copy is at"));
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn a_write_leaves_no_temp_file_behind() {
+        let dir = temp_dir("tmp");
+        upsert_in(&dir, "p1", Note::new("t".into(), "b".into())).unwrap();
+        let leftovers: Vec<_> = std::fs::read_dir(&dir)
+            .unwrap()
+            .flatten()
+            .filter(|e| e.file_name().to_string_lossy().ends_with(".tmp"))
+            .collect();
+        assert!(leftovers.is_empty(), "the rename must have consumed the temp file");
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn clearing_a_project_removes_its_file_and_missing_is_success() {
+        let dir = temp_dir("clear");
+        upsert_in(&dir, "p1", Note::new("t".into(), "b".into())).unwrap();
+        assert!(notes_path_in(&dir, "p1").exists());
+
+        clear_in(&dir, "p1").unwrap();
+        assert!(!notes_path_in(&dir, "p1").exists());
+        clear_in(&dir, "p1").unwrap(); // idempotent
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn clearing_is_what_project_removal_calls_and_it_never_fails_on_absence() {
+        // `remove_project` must not be able to fail because a project simply
+        // never had any notes — an orphaned notes file is harmless, a project
+        // that cannot be removed is not.
+        let dir = temp_dir("removal");
+        assert!(clear_in(&dir, "never-had-notes").is_ok());
+        std::fs::remove_dir_all(&dir).ok();
+    }
+}

app/src-tauri/src/storage/pending_cleanup.rs

@@ -0,0 +1,349 @@
+//! Host-side record of Docker resources `remove_project` could not delete.
+//!
+//! `remove_project` drops a project's id from `projects.json` unconditionally
+//! — see the comment on `ProjectRemovalReport` — so once that happens nothing
+//! in the app can name the leftover container, image or volume again by any
+//! path a user can reach. This is what keeps it reachable anyway: one JSON
+//! file per affected project under `<data_dir>/triple-c/pending-cleanup/`,
+//! written *before* the project record is dropped. Startup housekeeping
+//! retries every record on the next launch (see
+//! `commands::project_commands::retry_pending_cleanup_logged`) and deletes
+//! the ones that fully succeed.
+//!
+//! **This record is written in the same instant its record in `projects.json`
+//! is destroyed, and it is the only remaining handle on the leftover
+//! resource** — which is a stronger claim on durability than an ordinary
+//! write-temp-then-rename gives. `storage::migration_store::save` carries the
+//! same reasoning for the migration state file: `fs::write` returns once the
+//! bytes are in the page cache, and a rename over them is atomic with respect
+//! to other readers, not to power loss. A crash in that window leaves the
+//! rename applied and the data half-written, which [`list`] then treats as
+//! unparseable and skips — reproducing the exact bug this module exists to
+//! close, silently, with only a startup log line as evidence. So `save` here
+//! takes the same `File::create` → `write_all` → `sync_all` → `rename` →
+//! directory-sync shape `migration_store` does.
+
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PendingCleanup {
+    pub project_id: String,
+    /// Kept only so a log line or a future UI can name the project without a
+    /// second lookup — the project record itself is already gone by the time
+    /// this is read back.
+    pub project_name: String,
+    /// The project's container, if it could not be removed. Named by its
+    /// deterministic `triple-c-{id}` name rather than the (possibly stale)
+    /// container id Docker handed out — Docker's remove-container API
+    /// accepts either, and the name is the one identifier guaranteed to still
+    /// resolve to the same container by the time a retry runs.
+    pub container_id: Option<String>,
+    pub image: Option<String>,
+    pub volumes: Vec<String>,
+    pub recorded_at: String,
+}
+
+impl PendingCleanup {
+    /// True once nothing named here still needs to be removed.
+    pub fn is_empty(&self) -> bool {
+        self.container_id.is_none() && self.image.is_none() && self.volumes.is_empty()
+    }
+}
+
+/// `<data_dir>/triple-c/pending-cleanup`, created on demand.
+fn dir() -> Result<PathBuf, String> {
+    let dir = dirs::data_dir()
+        .ok_or_else(|| {
+            "Could not determine data directory. Set XDG_DATA_HOME on Linux.".to_string()
+        })?
+        .join("triple-c")
+        .join("pending-cleanup");
+    fs::create_dir_all(&dir)
+        .map_err(|e| format!("Failed to create pending-cleanup directory: {}", e))?;
+    Ok(dir)
+}
+
+/// Project ids are UUIDs, but they arrive over IPC, so refuse to let one steer
+/// the write anywhere but the pending-cleanup directory. Mirrors
+/// `storage::migration_store::sanitize`.
+fn sanitize(project_id: &str) -> String {
+    project_id
+        .chars()
+        .map(|c| if c.is_ascii_alphanumeric() || c == '-' || c == '_' { c } else { '_' })
+        .collect()
+}
+
+/// Write (or overwrite) a project's pending-cleanup record.
+pub fn save(record: &PendingCleanup) -> Result<(), String> {
+    save_in(&dir()?, record)
+}
+
+/// Remove a project's pending-cleanup record. Missing is success — this is
+/// how a fully-succeeded retry (or a record that never existed) is expressed.
+pub fn clear(project_id: &str) -> Result<(), String> {
+    clear_in(&dir()?, project_id)
+}
+
+/// Every pending-cleanup record on disk. An unparseable file is logged and
+/// skipped rather than blocking every other project's retry — the same
+/// "one bad record can't wedge the rest" reasoning as the migration store.
+pub fn list() -> Vec<PendingCleanup> {
+    let Ok(dir) = dir() else { return Vec::new() };
+    list_in(&dir)
+}
+
+fn path_in(dir: &Path, project_id: &str) -> PathBuf {
+    dir.join(format!("{}.json", sanitize(project_id)))
+}
+
+/// Durable write: fsync the file before the rename, and fsync the directory
+/// after it — see the module doc comment for why a plain
+/// write-temp-then-rename is not enough here. Mirrors
+/// `storage::migration_store::save`/`sync_dir`.
+fn save_in(dir: &Path, record: &PendingCleanup) -> Result<(), String> {
+    let path = path_in(dir, &record.project_id);
+    let data = serde_json::to_string_pretty(record)
+        .map_err(|e| format!("Failed to serialize pending cleanup record: {}", e))?;
+    let tmp = path.with_extension("json.tmp");
+
+    {
+        use std::io::Write;
+        let mut file = fs::File::create(&tmp)
+            .map_err(|e| format!("Failed to write pending cleanup record: {}", e))?;
+        file.write_all(data.as_bytes())
+            .map_err(|e| format!("Failed to write pending cleanup record: {}", e))?;
+        file.sync_all()
+            .map_err(|e| format!("Failed to flush pending cleanup record to disk: {}", e))?;
+    }
+
+    fs::rename(&tmp, &path)
+        .map_err(|e| format!("Failed to commit pending cleanup record: {}", e))?;
+    sync_dir(&path);
+    Ok(())
+}
+
+fn clear_in(dir: &Path, project_id: &str) -> Result<(), String> {
+    let path = path_in(dir, project_id);
+    match fs::remove_file(&path) {
+        Ok(()) => Ok(()),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(e) => Err(format!("Failed to remove pending cleanup record: {}", e)),
+    }
+}
+
+fn list_in(dir: &Path) -> Vec<PendingCleanup> {
+    let Ok(entries) = fs::read_dir(dir) else { return Vec::new() };
+
+    entries
+        .flatten()
+        .filter(|e| e.path().extension().is_some_and(|ext| ext == "json"))
+        .filter_map(|e| {
+            let path = e.path();
+            let data = fs::read_to_string(&path).ok()?;
+            match serde_json::from_str::<PendingCleanup>(&data) {
+                Ok(record) => Some(record),
+                Err(err) => {
+                    // Moved aside rather than left in place: a record nothing
+                    // ever repairs would otherwise warn on every single
+                    // startup forever, same as an ordinary `.json` file it
+                    // would keep looking like one to `list_in` on the next
+                    // call too. One aside-copy is enough here — this only
+                    // ever holds names to retry removing, not the class of
+                    // once-in-a-lifetime crash evidence `migration_store`
+                    // keeps multiple timestamped backups of.
+                    let corrupt = path.with_extension("json.corrupt");
+                    let moved = !corrupt.exists() && fs::rename(&path, &corrupt).is_ok();
+                    log::warn!(
+                        "Could not parse pending cleanup record {}: {}{}",
+                        path.display(),
+                        err,
+                        if moved {
+                            format!(" — moved aside to {}", corrupt.display())
+                        } else {
+                            " — leaving it in place".to_string()
+                        }
+                    );
+                    None
+                }
+            }
+        })
+        .collect()
+}
+
+/// fsync the directory holding `path`, so a rename into it survives power
+/// loss. Best effort only on the platforms where it is meaningless: Windows
+/// has no directory handle to sync and errors on the attempt, so failure is
+/// logged rather than propagated — the file's own `sync_all` above is what
+/// carries the data. Mirrors `storage::migration_store::sync_dir`, which is
+/// private to that module, so this is a small deliberate duplicate rather
+/// than a shared dependency between two otherwise-independent stores.
+fn sync_dir(path: &Path) {
+    let Some(dir) = path.parent() else { return };
+    match fs::File::open(dir).and_then(|d| d.sync_all()) {
+        Ok(()) => {}
+        Err(e) => log::debug!(
+            "Could not fsync the pending-cleanup directory {}: {} — the record itself was flushed",
+            dir.display(),
+            e
+        ),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn temp_dir(name: &str) -> PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "triple-c-pending-cleanup-{}-{}",
+            name,
+            uuid::Uuid::new_v4().simple()
+        ));
+        fs::create_dir_all(&dir).unwrap();
+        dir
+    }
+
+    fn record(project_id: &str) -> PendingCleanup {
+        PendingCleanup {
+            project_id: project_id.to_string(),
+            project_name: "Some Project".to_string(),
+            container_id: Some("triple-c-abc".to_string()),
+            image: Some("triple-c-snapshot-abc:latest".to_string()),
+            volumes: vec!["triple-c-home-abc".to_string()],
+            recorded_at: "2026-08-25T00:00:00Z".to_string(),
+        }
+    }
+
+    #[test]
+    fn project_ids_cannot_escape_the_pending_cleanup_directory() {
+        assert_eq!(sanitize("../../etc/passwd"), "______etc_passwd");
+        assert_eq!(sanitize("a/b"), "a_b");
+        assert_eq!(
+            sanitize("ab62cd24-51aa-4645-8f5c-17a124062050"),
+            "ab62cd24-51aa-4645-8f5c-17a124062050"
+        );
+    }
+
+    #[test]
+    fn is_empty_reflects_whatever_still_needs_removing() {
+        let mut r = record("p1");
+        assert!(!r.is_empty());
+
+        r.container_id = None;
+        r.image = None;
+        assert!(!r.is_empty(), "a leftover volume alone still counts");
+
+        r.volumes.clear();
+        assert!(r.is_empty());
+    }
+
+    /// Exercises the real `save_in`/`list_in`/`clear_in` — not a
+    /// re-implementation of their bodies — against a temp directory standing
+    /// in for `dir()`.
+    #[test]
+    fn a_saved_record_round_trips_and_clearing_removes_it() {
+        let dir = temp_dir("roundtrip");
+        let rec = record("proj-1");
+
+        save_in(&dir, &rec).expect("save");
+        let found = list_in(&dir);
+        assert_eq!(found.len(), 1);
+        assert_eq!(found[0].project_id, "proj-1");
+        assert_eq!(found[0].volumes, vec!["triple-c-home-abc".to_string()]);
+
+        clear_in(&dir, "proj-1").expect("clear");
+        assert!(list_in(&dir).is_empty());
+
+        fs::remove_dir_all(&dir).ok();
+    }
+
+    /// A second `save` for the same project overwrites rather than appending
+    /// — a retry that narrows the leftovers must not leave the old, wider
+    /// record behind it.
+    #[test]
+    fn saving_the_same_project_twice_overwrites_not_appends() {
+        let dir = temp_dir("overwrite");
+        let mut rec = record("proj-1");
+        save_in(&dir, &rec).expect("save");
+
+        rec.container_id = None;
+        rec.image = None;
+        save_in(&dir, &rec).expect("save again");
+
+        let found = list_in(&dir);
+        assert_eq!(found.len(), 1, "one file per project, not one per save");
+        assert!(found[0].container_id.is_none());
+        assert_eq!(found[0].volumes, vec!["triple-c-home-abc".to_string()]);
+
+        fs::remove_dir_all(&dir).ok();
+    }
+
+    /// A record that fails to parse must not poison the rest of the listing.
+    #[test]
+    fn an_unparseable_record_is_skipped_not_fatal() {
+        let dir = temp_dir("corrupt");
+        fs::write(dir.join("bad.json"), "{ not json").unwrap();
+        save_in(&dir, &record("proj-2")).expect("save");
+
+        let found = list_in(&dir);
+        assert_eq!(found.len(), 1);
+        assert_eq!(found[0].project_id, "proj-2");
+
+        fs::remove_dir_all(&dir).ok();
+    }
+
+    /// A record that fails to parse is moved aside once, rather than left in
+    /// place to be re-warned about — and re-warned about — on every future
+    /// launch forever.
+    #[test]
+    fn an_unparseable_record_is_moved_aside_exactly_once() {
+        let dir = temp_dir("corrupt-aside");
+        let bad = dir.join("bad.json");
+        fs::write(&bad, "{ not json").unwrap();
+
+        list_in(&dir);
+        assert!(!bad.exists(), "the bad file should have been moved aside");
+        let corrupt = dir.join("bad.json.corrupt");
+        assert!(corrupt.exists(), "and the moved copy should be at .json.corrupt");
+
+        // A second pass must not warn about `bad.json` again — it is gone —
+        // and must not choke on `.json.corrupt` already being there.
+        assert!(list_in(&dir).is_empty());
+        assert!(corrupt.exists(), "the aside copy is not itself deleted");
+
+        fs::remove_dir_all(&dir).ok();
+    }
+
+    /// `list_in` must not pick up the `.json.tmp` staging file `save_in`
+    /// leaves behind if a crash lands between the write and the rename — the
+    /// whole point of the temp-then-rename dance is that only the renamed
+    /// file is ever a complete record.
+    #[test]
+    fn a_leftover_tmp_file_is_not_listed() {
+        let dir = temp_dir("tmp-leftover");
+        fs::write(dir.join("proj-3.json.tmp"), "not a complete record").unwrap();
+        assert!(list_in(&dir).is_empty());
+
+        fs::remove_dir_all(&dir).ok();
+    }
+
+    /// Clearing by project id must remove exactly the file that id maps to
+    /// under `sanitize`, and nothing else.
+    #[test]
+    fn clearing_one_project_does_not_touch_another() {
+        let dir = temp_dir("clear-scoped");
+        save_in(&dir, &record("proj-a")).unwrap();
+        save_in(&dir, &record("proj-b")).unwrap();
+
+        clear_in(&dir, "proj-a").unwrap();
+
+        let found = list_in(&dir);
+        assert_eq!(found.len(), 1);
+        assert_eq!(found[0].project_id, "proj-b");
+
+        fs::remove_dir_all(&dir).ok();
+    }
+}

app/src-tauri/src/storage/projects_store.rs

@@ -1,9 +1,65 @@
 use std::fs;
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 use std::sync::Mutex;
 
 use crate::models::Project;
 
+/// The sticky marker for `projects.json`: `projects.json.corrupt`, beside it.
+///
+/// Derived from the file rather than from `dirs::data_dir()` so the marker
+/// always lands in the directory the store is actually using — and so the
+/// writer can be tested against a temp directory.
+fn corrupt_marker_for(file_path: &Path) -> PathBuf {
+    file_path.with_extension("json.corrupt")
+}
+
+/// Keep the bytes of an unparseable `projects.json`, and record that it
+/// happened.
+///
+/// **The existing `.bak` is never overwritten.** A second corruption used to
+/// clobber the first, and the first is the valuable one: it was taken before
+/// the app rewrote the file with whatever it had in memory, so it is the only
+/// copy that can still hold the full project list. Later ones are copies of an
+/// already-degraded file and get a timestamped name.
+fn record_corrupt_load(file_path: &Path, now: &chrono::DateTime<chrono::Utc>) {
+    let first = file_path.with_extension("json.bak");
+    let backup = if first.exists() {
+        file_path.with_extension(format!("json.corrupt-{}.bak", now.format("%Y%m%d-%H%M%S")))
+    } else {
+        first
+    };
+    if !backup.exists() {
+        if let Err(e) = fs::copy(file_path, &backup) {
+            log::error!("Failed to back up corrupted projects.json: {}", e);
+        } else {
+            log::error!(
+                "A copy of the unreadable projects.json was kept at {}",
+                backup.display()
+            );
+        }
+    }
+
+    // Sticky, and written even though nothing in the app reads it back on this
+    // branch: the Disk panel's `project_store_trust` was the reader and went to
+    // `hold/disk-and-dragout`. The marker stays because it is the only durable
+    // record that a project list was lost — the in-memory symptom does not
+    // survive the next save — and because re-deriving *when* it happened is
+    // impossible after the fact.
+    let marker = corrupt_marker_for(file_path);
+    if marker.exists() {
+        // The *first* corruption is the one that dates the loss.
+        return;
+    }
+    if let Err(e) = fs::write(&marker, now.to_rfc3339()) {
+        log::error!(
+            "Could not record the corrupt projects.json load at {}: {} — nothing will be able to \
+             tell later that the project list was incomplete",
+            marker.display(),
+            e
+        );
+    }
+}
+
 pub struct ProjectsStore {
     projects: Mutex<Vec<Project>>,
     file_path: PathBuf,
@@ -43,20 +99,14 @@ impl ProjectsStore {
                                 Ok(parsed) => (parsed, migrated),
                                 Err(e) => {
                                     log::error!("Failed to parse migrated projects.json: {}. Starting with empty list.", e);
-                                    let backup = file_path.with_extension("json.bak");
-                                    if let Err(be) = fs::copy(&file_path, &backup) {
-                                        log::error!("Failed to back up corrupted projects.json: {}", be);
-                                    }
+                                    record_corrupt_load(&file_path, &chrono::Utc::now());
                                     (Vec::new(), false)
                                 }
                             }
                         }
                         Err(e) => {
                             log::error!("Failed to parse projects.json: {}. Starting with empty list.", e);
-                            let backup = file_path.with_extension("json.bak");
-                            if let Err(be) = fs::copy(&file_path, &backup) {
-                                log::error!("Failed to back up corrupted projects.json: {}", be);
-                            }
+                            record_corrupt_load(&file_path, &chrono::Utc::now());
                             (Vec::new(), false)
                         }
                     }
@@ -177,6 +227,20 @@ impl ProjectsStore {
         }
     }
 
+    /// Granular setter for the auth bridge opt-in, so toggling it can't clobber
+    /// concurrent edits to the rest of the project record.
+    pub fn set_auth_bridge_enabled(&self, project_id: &str, enabled: bool) -> Result<(), String> {
+        let mut projects = self.lock();
+        if let Some(p) = projects.iter_mut().find(|p| p.id == project_id) {
+            p.auth_bridge_enabled = enabled;
+            p.updated_at = chrono::Utc::now().to_rfc3339();
+            self.save(&projects)?;
+            Ok(())
+        } else {
+            Err(format!("Project {} not found", project_id))
+        }
+    }
+
     pub fn set_container_id(&self, project_id: &str, container_id: Option<String>) -> Result<(), String> {
         let mut projects = self.lock();
         if let Some(p) = projects.iter_mut().find(|p| p.id == project_id) {
@@ -189,3 +253,89 @@ impl ProjectsStore {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn temp_dir(tag: &str) -> PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "triple-c-store-{}-{}",
+            tag,
+            uuid::Uuid::new_v4().simple()
+        ));
+        fs::create_dir_all(&dir).expect("temp dir");
+        dir
+    }
+
+    #[test]
+    fn a_corrupt_load_leaves_a_marker_the_next_write_cannot_erase() {
+        // H-3, the whole chain in one test. `ProjectsStore::new()` swallows an
+        // unparseable file into an empty list *without rewriting it*, and the
+        // first `save()` after that — as little as `update_status()` — writes
+        // `[{one project}]` over it. Everything the old guard keyed on ("the
+        // list is empty and the file exists") is gone at that point, while
+        // every *other* project's volumes are still on the daemon claimed by
+        // nobody.
+        let dir = temp_dir("corrupt");
+        let file = dir.join("projects.json");
+        fs::write(&file, "{ this is not a project list").unwrap();
+
+        let now = chrono::Utc::now();
+        record_corrupt_load(&file, &now);
+
+        let marker = corrupt_marker_for(&file);
+        assert!(marker.exists(), "the corrupt load must be recorded on disk");
+        assert_eq!(fs::read_to_string(&marker).unwrap(), now.to_rfc3339());
+        assert!(
+            dir.join("projects.json.bak").exists(),
+            "the unreadable bytes must be kept"
+        );
+
+        // The write that used to erase the evidence. The marker is a separate
+        // file, so it does not care.
+        fs::write(&file, r#"[{"id":"the-one-project-started-since"}]"#).unwrap();
+        assert!(marker.exists());
+
+        fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn a_second_corruption_keeps_the_first_copy_and_the_first_date() {
+        // The `.bak` used to be a fixed name, so a second corruption clobbered
+        // the first — and the first is the only copy taken before the app
+        // rewrote the file with whatever it had in memory, i.e. the only one
+        // that can still hold the full project list.
+        let dir = temp_dir("second");
+        let file = dir.join("projects.json");
+        fs::write(&file, "original bytes").unwrap();
+        let first = chrono::DateTime::parse_from_rfc3339("2026-01-01T00:00:00Z")
+            .unwrap()
+            .with_timezone(&chrono::Utc);
+        record_corrupt_load(&file, &first);
+
+        fs::write(&file, "degraded bytes").unwrap();
+        let second = chrono::DateTime::parse_from_rfc3339("2026-06-01T00:00:00Z")
+            .unwrap()
+            .with_timezone(&chrono::Utc);
+        record_corrupt_load(&file, &second);
+
+        assert_eq!(
+            fs::read_to_string(dir.join("projects.json.bak")).unwrap(),
+            "original bytes",
+            "the first copy must survive the second corruption"
+        );
+        assert_eq!(
+            fs::read_to_string(dir.join("projects.json.corrupt-20260601-000000.bak")).unwrap(),
+            "degraded bytes"
+        );
+        // And the marker still dates the loss from the first failure, which is
+        // when the project list actually stopped being complete.
+        assert_eq!(
+            fs::read_to_string(corrupt_marker_for(&file)).unwrap(),
+            first.to_rfc3339()
+        );
+
+        fs::remove_dir_all(&dir).ok();
+    }
+}

app/src-tauri/src/storage/secure.rs

@@ -1,45 +1,445 @@
+//! OS keychain access, via the `keyring` crate.
+//!
+//! Two kinds of secret live here:
+//!   * **per-project** secrets (git token, AWS keys, …), keyed by project id;
+//!   * the **shared Claude Code OAuth token**, which is global — one
+//!     `claude setup-token` run authenticates every Anthropic-backend project.
+//!
+//! Nothing in this module ever logs a secret or folds one into an error string.
+
+/// Keychain service for the single, global Claude Code OAuth token minted by
+/// `claude setup-token` and consumed via `CLAUDE_CODE_OAUTH_TOKEN`.
+const CLAUDE_TOKEN_SERVICE: &str = "triple-c-claude-oauth-token";
+
+/// Keychain service for the token's **rotation id** — a fresh random value
+/// written every time the token is stored.
+///
+/// Container recreation is driven off Docker labels, which anything on the host
+/// can read with `docker inspect`. The token itself must obviously not go in a
+/// label, and neither should a bare hash of it: a hash is a verification oracle
+/// (holding a candidate token, you could confirm it). This id is not derived
+/// from the token at all — it is unrelated random data that merely *changes*
+/// whenever the token does, which is exactly (and only) what change detection
+/// needs.
+const CLAUDE_TOKEN_VERSION_SERVICE: &str = "triple-c-claude-oauth-token-version";
+
+/// Fixed account name used for every triple-c keychain entry.
+const KEYCHAIN_ACCOUNT: &str = "secret";
+
+/// Every per-project secret this app stores, and therefore every one it has to
+/// be able to delete.
+///
+/// This list is the **only** definition. It used to exist twice — once
+/// implicitly, as whatever `store_secrets_for_project` happened to write, and
+/// once explicitly, as a literal array inside `delete_project_secrets` — and
+/// the two drifted: `openai-compatible-api-key` was added to the writer and
+/// never to the deleter, so removing a project left a live provider API key in
+/// the user's login keychain with nothing left in the app that referenced it,
+/// or would ever offer to clean it up.
+///
+/// Drift is now a compile-time-shaped error rather than a review-time one:
+/// [`project_secret_entry`] refuses a key that is not in this list, so a new
+/// secret cannot be stored until it has been added here, and adding it here is
+/// what makes [`delete_project_secrets`] cover it.
+pub const PROJECT_SECRET_KEYS: &[&str] = &[
+    "git-token",
+    "aws-access-key-id",
+    "aws-secret-access-key",
+    "aws-session-token",
+    "aws-bearer-token",
+    "openai-compatible-api-key",
+];
+
+/// The keychain entry for one per-project secret, rejecting any key name not in
+/// [`PROJECT_SECRET_KEYS`]. See that constant for why the rejection matters.
+fn project_secret_entry(project_id: &str, key_name: &str) -> Result<keyring::Entry, String> {
+    if !PROJECT_SECRET_KEYS.contains(&key_name) {
+        return Err(format!(
+            "Unknown project secret '{}'. Add it to PROJECT_SECRET_KEYS so project deletion \
+             clears it too.",
+            key_name
+        ));
+    }
+    let service = format!("triple-c-project-{}-{}", project_id, key_name);
+    keyring::Entry::new(&service, KEYCHAIN_ACCOUNT).map_err(|e| format!("Keyring error: {}", e))
+}
+
 /// Store a per-project secret in the OS keychain.
 pub fn store_project_secret(project_id: &str, key_name: &str, value: &str) -> Result<(), String> {
-    let service = format!("triple-c-project-{}-{}", project_id, key_name);
-    let entry = keyring::Entry::new(&service, "secret")
-        .map_err(|e| format!("Keyring error: {}", e))?;
-    entry
+    project_secret_entry(project_id, key_name)?
         .set_password(value)
         .map_err(|e| format!("Failed to store project secret '{}': {}", key_name, e))
 }
 
 /// Retrieve a per-project secret from the OS keychain.
 pub fn get_project_secret(project_id: &str, key_name: &str) -> Result<Option<String>, String> {
-    let service = format!("triple-c-project-{}-{}", project_id, key_name);
-    let entry = keyring::Entry::new(&service, "secret")
-        .map_err(|e| format!("Keyring error: {}", e))?;
-    match entry.get_password() {
+    match project_secret_entry(project_id, key_name)?.get_password() {
         Ok(value) => Ok(Some(value)),
         Err(keyring::Error::NoEntry) => Ok(None),
         Err(e) => Err(format!("Failed to retrieve project secret '{}': {}", key_name, e)),
     }
 }
 
-/// Delete all known secrets for a project from the OS keychain.
+/// Delete one per-project secret, treating "wasn't there" as success.
+pub fn delete_project_secret(project_id: &str, key_name: &str) -> Result<(), String> {
+    match project_secret_entry(project_id, key_name)?.delete_credential() {
+        Ok(()) | Err(keyring::Error::NoEntry) => Ok(()),
+        Err(e) => Err(format!("Failed to delete project secret '{}': {}", key_name, e)),
+    }
+}
+
+/// Write a per-project secret, or **clear** it when there is nothing to write.
+///
+/// This is the function every save path should call, and the reason it exists
+/// is that the obvious `if let Some(v) = … { store(v) }` is wrong. The editors
+/// in `components/projects/home/config/` send a blanked field as `null`
+/// (`AccessSection.tsx`: `save({ git_token: gitToken || null })`), so a `None`
+/// is a user asking for the secret to be *removed* — and skipping it left the
+/// old value in the keychain, where `load_secrets_for_project` read it straight
+/// back out and put it back on the project. Clearing a credential through the
+/// UI was therefore impossible: the field looked empty and the container kept
+/// getting the old token.
+///
+/// `Some("")` and `Some("   ")` are treated the same as `None` — a field the
+/// user emptied, whichever shape it arrives in — because a stored empty secret
+/// is not a secret, and `container_config` would inject it as an env var that
+/// overrides the unset case with a blank.
+// TODO(handoff): `commands/project_commands.rs::store_secrets_for_project` is
+// the one caller this is for, and it still uses the `if let Some(v) = … ` shape
+// that cannot clear anything. That file belongs to another change in this round,
+// so the switch is deliberately left to it; the six call sites there become
+// `store_or_clear_project_secret(&project.id, "<key>", field.as_deref())?`.
+#[allow(dead_code)]
+pub fn store_or_clear_project_secret(
+    project_id: &str,
+    key_name: &str,
+    value: Option<&str>,
+) -> Result<(), String> {
+    match secret_to_store(value) {
+        Some(v) => store_project_secret(project_id, key_name, v),
+        None => delete_project_secret(project_id, key_name),
+    }
+}
+
+/// The store-or-clear decision, split out so it can be tested without a
+/// keychain backend: `Some` means "write this", `None` means "remove whatever
+/// is there".
+#[allow(dead_code)]
+fn secret_to_store(value: Option<&str>) -> Option<&str> {
+    match value.map(str::trim) {
+        Some(v) if !v.is_empty() => Some(v),
+        _ => None,
+    }
+}
+
+/// Delete every known secret for a project from the OS keychain.
+///
+/// Called when a project is removed, so it must cover [`PROJECT_SECRET_KEYS`]
+/// exhaustively — a key missed here outlives the project that explained it.
+/// One key failing does not stop the rest: a partial cleanup that keeps going
+/// leaves strictly fewer credentials behind than one that gives up.
 pub fn delete_project_secrets(project_id: &str) -> Result<(), String> {
-    let secret_keys = [
-        "git-token",
-        "aws-access-key-id",
-        "aws-secret-access-key",
-        "aws-session-token",
-        "aws-bearer-token",
-    ];
-    for key_name in &secret_keys {
-        let service = format!("triple-c-project-{}-{}", project_id, key_name);
-        let entry = keyring::Entry::new(&service, "secret")
-            .map_err(|e| format!("Keyring error: {}", e))?;
-        match entry.delete_credential() {
-            Ok(()) => {}
-            Err(keyring::Error::NoEntry) => {}
-            Err(e) => {
-                log::warn!("Failed to delete project secret '{}': {}", key_name, e);
-            }
+    for key_name in PROJECT_SECRET_KEYS {
+        if let Err(e) = delete_project_secret(project_id, key_name) {
+            log::warn!("Failed to delete project secret '{}': {}", key_name, e);
         }
     }
     Ok(())
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Shared Claude Code OAuth token (global, not per project)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Read a single-value keychain entry. `Ok(None)` when the entry is absent.
+/// The error text names the entry, never its value.
+fn read_entry(service: &str, label: &str) -> Result<Option<String>, String> {
+    let entry = keyring::Entry::new(service, KEYCHAIN_ACCOUNT)
+        .map_err(|e| format!("Keyring error: {}", e))?;
+    match entry.get_password() {
+        Ok(value) => Ok(Some(value)),
+        Err(keyring::Error::NoEntry) => Ok(None),
+        Err(e) => Err(format!("Failed to retrieve {}: {}", label, e)),
+    }
+}
+
+/// Delete a keychain entry, treating "wasn't there" as success.
+fn delete_entry(service: &str, label: &str) -> Result<(), String> {
+    let entry = keyring::Entry::new(service, KEYCHAIN_ACCOUNT)
+        .map_err(|e| format!("Keyring error: {}", e))?;
+    match entry.delete_credential() {
+        Ok(()) | Err(keyring::Error::NoEntry) => Ok(()),
+        Err(e) => Err(format!("Failed to delete {}: {}", label, e)),
+    }
+}
+
+/// Store the shared Claude Code OAuth token, replacing any previous one, and
+/// mint a fresh rotation id so containers holding the old token are flagged for
+/// recreation. Blank input is rejected rather than silently stored.
+pub fn store_claude_oauth_token(token: &str) -> Result<(), String> {
+    if token.trim().is_empty() {
+        return Err("Refusing to store an empty Claude authentication token.".to_string());
+    }
+
+    let entry = keyring::Entry::new(CLAUDE_TOKEN_SERVICE, KEYCHAIN_ACCOUNT)
+        .map_err(|e| format!("Keyring error: {}", e))?;
+    entry
+        .set_password(token)
+        .map_err(|e| format!("Failed to store the Claude authentication token: {}", e))?;
+
+    // Rotation id second: if this fails the token is still usable, and the
+    // stale id only costs one extra container recreation later.
+    let version = uuid::Uuid::new_v4().to_string();
+    let version_entry = keyring::Entry::new(CLAUDE_TOKEN_VERSION_SERVICE, KEYCHAIN_ACCOUNT)
+        .map_err(|e| format!("Keyring error: {}", e))?;
+    version_entry
+        .set_password(&version)
+        .map_err(|e| format!("Failed to store the Claude token rotation id: {}", e))?;
+
+    Ok(())
+}
+
+/// Retrieve the shared Claude Code OAuth token, if one has been stored.
+pub fn get_claude_oauth_token() -> Result<Option<String>, String> {
+    read_entry(CLAUDE_TOKEN_SERVICE, "the Claude authentication token")
+}
+
+/// The rotation id of the currently stored token. Opaque random data — safe to
+/// put in a Docker label, unlike the token or any hash of it.
+pub fn get_claude_oauth_token_version() -> Result<Option<String>, String> {
+    read_entry(
+        CLAUDE_TOKEN_VERSION_SERVICE,
+        "the Claude token rotation id",
+    )
+}
+
+/// Whether a shared Claude Code OAuth token is currently stored. A keychain
+/// failure is reported as "no token" rather than surfacing as an error, so the
+/// UI degrades to the un-authenticated state instead of breaking.
+pub fn has_claude_oauth_token() -> bool {
+    matches!(get_claude_oauth_token(), Ok(Some(t)) if !t.trim().is_empty())
+}
+
+/// Delete the shared Claude Code OAuth token and its rotation id. Both are
+/// attempted even if the first fails, so a partial failure cannot strand the
+/// token behind a deleted id.
+pub fn delete_claude_oauth_token() -> Result<(), String> {
+    let token_result = delete_entry(CLAUDE_TOKEN_SERVICE, "the Claude authentication token");
+    let version_result = delete_entry(
+        CLAUDE_TOKEN_VERSION_SERVICE,
+        "the Claude token rotation id",
+    );
+    token_result.and(version_result)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Model gateway secrets (global, not per project)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Keychain service for the upstream provider API key (OpenAI etc.) the
+/// LiteLLM gateway authenticates to the model provider with. This value is
+/// written into the gateway's generated `config.yaml`, which is uploaded
+/// straight into the container over the Docker API — it is never an env var,
+/// never a Docker label, and is never returned to the frontend.
+const GATEWAY_API_KEY_SERVICE: &str = "triple-c-gateway-provider-api-key";
+
+/// Keychain service for the gateway's **master key** — the credential a
+/// *project* presents to the gateway as `ANTHROPIC_AUTH_TOKEN`. Unlike the
+/// provider key this one is minted by Triple-C and must be readable by the
+/// user, since they have to paste it into a project's model config.
+const GATEWAY_MASTER_KEY_SERVICE: &str = "triple-c-gateway-master-key";
+
+/// Rotation id covering *both* gateway secrets, on the same reasoning as
+/// `CLAUDE_TOKEN_VERSION_SERVICE`: container recreation is driven off Docker
+/// labels, labels are world-readable via `docker inspect`, and a hash of a
+/// secret is a verification oracle. This is unrelated random data that merely
+/// changes whenever either secret does.
+const GATEWAY_SECRET_VERSION_SERVICE: &str = "triple-c-gateway-secret-version";
+
+/// Mint a fresh gateway rotation id. Called after either gateway secret moves.
+fn bump_gateway_secret_version() -> Result<(), String> {
+    let version = uuid::Uuid::new_v4().to_string();
+    let entry = keyring::Entry::new(GATEWAY_SECRET_VERSION_SERVICE, KEYCHAIN_ACCOUNT)
+        .map_err(|e| format!("Keyring error: {}", e))?;
+    entry
+        .set_password(&version)
+        .map_err(|e| format!("Failed to store the gateway secret rotation id: {}", e))
+}
+
+/// The rotation id of the currently stored gateway secrets. Opaque random
+/// data — safe to put in a Docker label, unlike either secret.
+pub fn get_gateway_secret_version() -> Result<Option<String>, String> {
+    read_entry(
+        GATEWAY_SECRET_VERSION_SERVICE,
+        "the gateway secret rotation id",
+    )
+}
+
+/// Store the provider API key, replacing any previous one. Blank input is
+/// rejected rather than silently stored.
+pub fn store_gateway_api_key(key: &str) -> Result<(), String> {
+    if key.trim().is_empty() {
+        return Err("Refusing to store an empty gateway provider API key.".to_string());
+    }
+
+    let entry = keyring::Entry::new(GATEWAY_API_KEY_SERVICE, KEYCHAIN_ACCOUNT)
+        .map_err(|e| format!("Keyring error: {}", e))?;
+    entry
+        .set_password(key.trim())
+        .map_err(|e| format!("Failed to store the gateway provider API key: {}", e))?;
+
+    // Rotation id second: if this fails the key is still usable, and the stale
+    // id only costs one extra container recreation later.
+    bump_gateway_secret_version()
+}
+
+/// Retrieve the provider API key. **Host-side only** — this is consumed when
+/// rendering the gateway config and must not be handed to the frontend.
+pub fn get_gateway_api_key() -> Result<Option<String>, String> {
+    read_entry(GATEWAY_API_KEY_SERVICE, "the gateway provider API key")
+}
+
+/// Whether a provider API key is stored. A keychain failure is reported as
+/// "no key" so the UI degrades to the unconfigured state instead of breaking.
+pub fn has_gateway_api_key() -> bool {
+    matches!(get_gateway_api_key(), Ok(Some(k)) if !k.trim().is_empty())
+}
+
+/// Delete the provider API key and rotate the id so a running gateway holding
+/// the old key is flagged for recreation.
+pub fn delete_gateway_api_key() -> Result<(), String> {
+    let delete_result = delete_entry(GATEWAY_API_KEY_SERVICE, "the gateway provider API key");
+    let version_result = bump_gateway_secret_version();
+    delete_result.and(version_result)
+}
+
+/// The gateway master key, minting one on first use.
+///
+/// The gateway is published on a host port so project containers can reach it,
+/// which means an unauthenticated gateway would be an open proxy onto the
+/// user's provider account for anything that can route to the host. LiteLLM
+/// only enforces auth when a master key is configured, so Triple-C always
+/// configures one.
+pub fn get_or_create_gateway_master_key() -> Result<String, String> {
+    if let Some(existing) = get_gateway_master_key()? {
+        return Ok(existing);
+    }
+    regenerate_gateway_master_key()
+}
+
+/// Read the gateway master key without minting one if none exists yet.
+/// Distinct from [`get_or_create_gateway_master_key`], which mints as a side
+/// effect the read half of that function must not have — settings export
+/// (triple-c#35) needs "is there one, and if so what is it", not "make sure
+/// one exists".
+pub fn get_gateway_master_key() -> Result<Option<String>, String> {
+    Ok(read_entry(GATEWAY_MASTER_KEY_SERVICE, "the gateway master key")?
+        .filter(|k| !k.trim().is_empty()))
+}
+
+/// Mint a new gateway master key, invalidating the old one. Projects using the
+/// previous value must be updated.
+pub fn regenerate_gateway_master_key() -> Result<String, String> {
+    // LiteLLM requires the master key to start with `sk-`.
+    let key = format!("sk-triple-c-{}", uuid::Uuid::new_v4().simple());
+    store_gateway_master_key(&key)?;
+    Ok(key)
+}
+
+/// Store an exact given gateway master key, replacing any previous one.
+///
+/// Distinct from [`regenerate_gateway_master_key`], which always mints a
+/// fresh random value: this exists for settings import (triple-c#35), where
+/// restoring the *same* key an export captured is the point — projects on
+/// the destination machine may not exist yet, but a project migrated or
+/// re-added later that still has the old key pasted into its config must
+/// keep working against it. Blank input is rejected rather than silently
+/// stored, matching every other `store_*` function in this module.
+pub fn store_gateway_master_key(key: &str) -> Result<(), String> {
+    if key.trim().is_empty() {
+        return Err("Refusing to store an empty gateway master key.".to_string());
+    }
+
+    let entry = keyring::Entry::new(GATEWAY_MASTER_KEY_SERVICE, KEYCHAIN_ACCOUNT)
+        .map_err(|e| format!("Keyring error: {}", e))?;
+    entry
+        .set_password(key.trim())
+        .map_err(|e| format!("Failed to store the gateway master key: {}", e))?;
+
+    bump_gateway_secret_version()
+}
+
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The regression this list exists for. `openai-compatible-api-key` was
+    /// written by `store_secrets_for_project` and missing from the delete list,
+    /// so it survived project deletion.
+    #[test]
+    fn every_secret_the_app_writes_is_one_it_can_delete() {
+        for key in [
+            "git-token",
+            "aws-access-key-id",
+            "aws-secret-access-key",
+            "aws-session-token",
+            "aws-bearer-token",
+            "openai-compatible-api-key",
+        ] {
+            assert!(
+                PROJECT_SECRET_KEYS.contains(&key),
+                "{} is written by commands/project_commands.rs but would outlive the project",
+                key
+            );
+        }
+    }
+
+    #[test]
+    fn the_key_list_has_no_duplicates() {
+        let mut seen = std::collections::HashSet::new();
+        for key in PROJECT_SECRET_KEYS {
+            assert!(seen.insert(*key), "duplicate project secret key {}", key);
+        }
+    }
+
+    /// A key that is not in the list is refused *before* any keychain entry is
+    /// constructed, which is what makes the list authoritative rather than
+    /// advisory. Without this, a new secret can be stored under a name nothing
+    /// ever deletes.
+    #[test]
+    fn an_unlisted_key_cannot_be_stored_at_all() {
+        let err = store_project_secret("some-project", "brand-new-token", "value")
+            .expect_err("an unlisted key must be refused");
+        assert!(
+            err.contains("PROJECT_SECRET_KEYS"),
+            "the refusal should say how to fix it: {}",
+            err
+        );
+
+        let err = get_project_secret("some-project", "brand-new-token")
+            .expect_err("an unlisted key must be refused on read too");
+        assert!(err.contains("brand-new-token"), "{}", err);
+
+        let err = delete_project_secret("some-project", "brand-new-token")
+            .expect_err("an unlisted key must be refused on delete too");
+        assert!(err.contains("brand-new-token"), "{}", err);
+    }
+
+    /// The blanked-field case. `AccessSection.tsx` sends `gitToken || null`, so
+    /// a cleared field arrives as `None` — and before this existed, `None` was
+    /// skipped and the old secret stayed in the keychain forever.
+    #[test]
+    fn a_blanked_field_clears_rather_than_being_skipped() {
+        assert_eq!(secret_to_store(None), None);
+        assert_eq!(secret_to_store(Some("")), None);
+        assert_eq!(secret_to_store(Some("   \t\n")), None);
+    }
+
+    #[test]
+    fn a_real_value_is_stored_trimmed() {
+        assert_eq!(secret_to_store(Some("ghp_abc123")), Some("ghp_abc123"));
+        // Pasted credentials routinely carry a trailing newline.
+        assert_eq!(secret_to_store(Some("  ghp_abc123\n")), Some("ghp_abc123"));
+    }
+}

app/src-tauri/src/storage/settings_crypto.rs

@@ -0,0 +1,184 @@
+//! Password-based encryption for the settings export/import file — see
+//! triple-c#35.
+//!
+//! The exported payload can carry live credentials (the shared Claude OAuth
+//! token, the gateway provider/master keys — see
+//! `commands::settings_export_commands`), so this is not encryption for its
+//! own sake; a wrong or missing key here is a real credential leak, not a
+//! cosmetic bug. Argon2id derives a 256-bit key from the password (memory-
+//! hard, meaningfully resistant to GPU/ASIC brute-forcing in a way PBKDF2 at
+//! any reasonable iteration count is not), and AES-256-GCM is what actually
+//! encrypts — authenticated, so a wrong password is detected by a failed tag
+//! check rather than producing silent garbage.
+//!
+//! File format: `MAGIC (4 bytes) | salt (16 bytes) | nonce (12 bytes) |
+//! ciphertext+tag`. The salt and nonce are not secret — they are written in
+//! the clear right here, on purpose. The salt's only job is to make two
+//! exports with the same password derive different keys (defeats a
+//! precomputed-table attack against the password alone); the nonce's job is
+//! GCM's requirement that a (key, nonce) pair never repeat. Both hold
+//! because a fresh random value is drawn for each, on every call to
+//! [`encrypt`].
+//!
+//! The whole header (magic + salt + nonce) is passed to AES-GCM as
+//! associated data, not just placed alongside the ciphertext — free to do,
+//! and it makes tampering with any header byte fail the same authentication
+//! check the ciphertext gets, by construction rather than as a side effect
+//! of the salt/nonce also feeding key derivation and the cipher.
+
+use aes_gcm::aead::{Aead, KeyInit, Payload};
+use aes_gcm::{Aes256Gcm, Nonce};
+use argon2::{Algorithm, Argon2, Params, Version};
+use rand::RngCore;
+use zeroize::Zeroizing;
+
+/// Identifies the file as a Triple-C settings export and pins the format —
+/// a change to the salt/nonce lengths or the KDF/cipher choice below needs a
+/// new magic value, not a silent reinterpretation of old bytes.
+const MAGIC: &[u8; 4] = b"TCX1";
+const SALT_LEN: usize = 16;
+const NONCE_LEN: usize = 12;
+const KEY_LEN: usize = 32;
+const HEADER_LEN: usize = MAGIC.len() + SALT_LEN + NONCE_LEN;
+
+/// Argon2id parameters: memory cost in KiB, time cost (iterations),
+/// parallelism. `(19 MiB, 2, 1)` is OWASP's documented minimum recommendation
+/// for Argon2id — deliberately heavier than a login-flow KDF would use, since
+/// this runs once per export/import rather than on every request, so trading
+/// roughly a second of wall time for real brute-force resistance costs
+/// nothing a user would notice.
+fn argon2_params() -> Params {
+    Params::new(19 * 1024, 2, 1, Some(KEY_LEN)).expect("hardcoded Argon2 params are valid")
+}
+
+/// The derived key is wrapped in `Zeroizing` so it is overwritten with zeros
+/// when it drops rather than left in freed memory for whatever reuses that
+/// stack slot next — cheap insurance (`zeroize` is already in the dependency
+/// tree via `aes-gcm`) for material that exists only to decrypt live
+/// credentials.
+fn derive_key(password: &str, salt: &[u8]) -> Result<Zeroizing<[u8; KEY_LEN]>, String> {
+    let argon2 = Argon2::new(Algorithm::Argon2id, Version::V0x13, argon2_params());
+    let mut key = Zeroizing::new([0u8; KEY_LEN]);
+    argon2
+        .hash_password_into(password.as_bytes(), salt, &mut *key)
+        .map_err(|e| format!("Failed to derive encryption key: {}", e))?;
+    Ok(key)
+}
+
+/// Encrypt `plaintext` with a key derived from `password`. Returns the whole
+/// file's bytes (header + ciphertext) — see the module doc for the layout.
+pub fn encrypt(plaintext: &[u8], password: &str) -> Result<Vec<u8>, String> {
+    let mut salt = [0u8; SALT_LEN];
+    rand::rng().fill_bytes(&mut salt);
+    let key = derive_key(password, &salt)?;
+
+    let mut nonce_bytes = [0u8; NONCE_LEN];
+    rand::rng().fill_bytes(&mut nonce_bytes);
+    let nonce = Nonce::from_slice(&nonce_bytes);
+
+    let mut header = Vec::with_capacity(HEADER_LEN);
+    header.extend_from_slice(MAGIC);
+    header.extend_from_slice(&salt);
+    header.extend_from_slice(&nonce_bytes);
+
+    let cipher = Aes256Gcm::new_from_slice(&*key)
+        .map_err(|e| format!("Failed to initialize cipher: {}", e))?;
+    // The header (magic + salt + nonce) is authenticated as associated data
+    // even though none of it is secret: it costs nothing extra here, and it
+    // means tampering with any header byte is caught by the same tag check
+    // that already covers the ciphertext, by construction rather than as a
+    // side effect of the header also feeding key/nonce derivation.
+    let ciphertext = cipher
+        .encrypt(nonce, Payload { msg: plaintext, aad: &header })
+        .map_err(|e| format!("Encryption failed: {}", e))?;
+
+    let mut out = header;
+    out.extend_from_slice(&ciphertext);
+    Ok(out)
+}
+
+/// Decrypt a file produced by [`encrypt`]. The one error this returns for a
+/// wrong password is deliberately generic ("wrong password, or the file is
+/// corrupted") rather than distinguishing the two: GCM's authentication tag
+/// fails to verify for the wrong key on essentially any ciphertext, so there
+/// is no reliable way to tell "wrong password" from "corrupted file" apart,
+/// and guessing would be worse than saying so.
+///
+/// Returns `Zeroizing<Vec<u8>>` rather than a plain `Vec<u8>` — the plaintext
+/// this recovers is the whole settings-plus-secrets payload, so it gets the
+/// same "wipe it when it drops" treatment as the derived key in
+/// [`derive_key`].
+pub fn decrypt(data: &[u8], password: &str) -> Result<Zeroizing<Vec<u8>>, String> {
+    if data.len() < HEADER_LEN {
+        return Err("This does not look like a Triple-C settings export (file too short).".to_string());
+    }
+    if &data[..MAGIC.len()] != MAGIC {
+        return Err("This does not look like a Triple-C settings export (unrecognized file).".to_string());
+    }
+    let header = &data[..HEADER_LEN];
+    let salt = &data[MAGIC.len()..MAGIC.len() + SALT_LEN];
+    let nonce_bytes = &data[MAGIC.len() + SALT_LEN..HEADER_LEN];
+    let ciphertext = &data[HEADER_LEN..];
+
+    let key = derive_key(password, salt)?;
+    let cipher = Aes256Gcm::new_from_slice(&*key)
+        .map_err(|e| format!("Failed to initialize cipher: {}", e))?;
+    let nonce = Nonce::from_slice(nonce_bytes);
+    cipher
+        .decrypt(nonce, Payload { msg: ciphertext, aad: header })
+        .map(Zeroizing::new)
+        .map_err(|_| "Wrong password, or the file is corrupted.".to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_round_trip_with_the_right_password_recovers_the_plaintext() {
+        let plaintext = b"{\"settings\": \"whatever\"}";
+        let encrypted = encrypt(plaintext, "correct horse battery staple").unwrap();
+        let decrypted = decrypt(&encrypted, "correct horse battery staple").unwrap();
+        assert_eq!(&*decrypted, plaintext);
+    }
+
+    #[test]
+    fn the_wrong_password_fails_rather_than_returning_garbage() {
+        let encrypted = encrypt(b"secret payload", "correct password").unwrap();
+        let result = decrypt(&encrypted, "wrong password");
+        assert!(result.is_err(), "decrypting with the wrong password must fail, not silently succeed");
+    }
+
+    #[test]
+    fn two_exports_of_the_same_plaintext_and_password_produce_different_files() {
+        // If this ever failed it would mean the salt or nonce stopped being
+        // randomized — either one repeating is a real security regression
+        // (a fixed salt lets an attacker precompute against the password
+        // alone; a repeated (key, nonce) pair breaks GCM's guarantees
+        // outright), not just a cosmetic one.
+        let a = encrypt(b"same plaintext", "same password").unwrap();
+        let b = encrypt(b"same plaintext", "same password").unwrap();
+        assert_ne!(a, b, "two independent exports must not be byte-identical");
+    }
+
+    #[test]
+    fn corrupting_a_single_byte_of_ciphertext_is_detected() {
+        let mut encrypted = encrypt(b"tamper-evident payload", "a password").unwrap();
+        let last = encrypted.len() - 1;
+        encrypted[last] ^= 0xFF;
+        assert!(decrypt(&encrypted, "a password").is_err());
+    }
+
+    #[test]
+    fn a_file_that_is_too_short_is_rejected_cleanly_not_by_panicking() {
+        assert!(decrypt(b"short", "any password").is_err());
+        assert!(decrypt(b"", "any password").is_err());
+    }
+
+    #[test]
+    fn a_file_with_the_wrong_magic_is_rejected() {
+        let mut encrypted = encrypt(b"payload", "password").unwrap();
+        encrypted[0] = b'X';
+        assert!(decrypt(&encrypted, "password").is_err());
+    }
+}

app/src-tauri/src/web_terminal/terminal.html

@@ -3,11 +3,78 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
+<!--
+  This page is served by an axum server bound 0.0.0.0 (remote access is the
+  feature) behind a permissive CORS layer, and it fronts a shell in a container.
+  It gets a CSP of its own because nothing else gives it one: the app's
+  `tauri.conf.json` CSP covers the desktop webview, never this document.
+
+  `default-src 'none'` is the base, so anything not named below is refused
+  outright. What is named:
+    script-src  jsdelivr for the three xterm bundles, plus 'unsafe-inline' for
+                this page's own inline <script>. Nonces/hashes were considered
+                and rejected: the file is a static `include_str!()` asset, so a
+                hash would have to be recomputed by hand on every edit to the
+                script, and the failure mode of getting that wrong is a terminal
+                that silently will not start.
+    style-src   the xterm stylesheet, this page's <style>, and the one inline
+                `style=` attribute below (style attributes need 'unsafe-inline').
+    connect-src the WebSocket back to this same server. `ws:`/`wss:` as schemes
+                rather than an origin, because the host and port are whatever
+                the user reached this page on and are not knowable at build time.
+    form-action / base-uri / object-src / frame-ancestors — all 'none'. Note
+                `frame-ancestors` is ignored in a <meta> CSP; it is here as a
+                statement of intent, and the real protection would be a response
+                header from `server.rs`.
+  Deliberately absent: 'unsafe-eval', and any origin other than jsdelivr.
+-->
+<meta http-equiv="Content-Security-Policy" content="
+  default-src 'none';
+  script-src 'unsafe-inline' https://cdn.jsdelivr.net;
+  style-src 'unsafe-inline' https://cdn.jsdelivr.net;
+  img-src 'self' data:;
+  font-src 'self' data:;
+  connect-src 'self' ws: wss:;
+  form-action 'none';
+  base-uri 'none';
+  object-src 'none';
+  frame-ancestors 'none';
+">
 <title>Triple-C Web Terminal</title>
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@xterm/xterm@5.5.0/css/xterm.min.css">
-<script src="https://cdn.jsdelivr.net/npm/@xterm/xterm@5.5.0/lib/xterm.min.js"></script>
-<script src="https://cdn.jsdelivr.net/npm/@xterm/addon-fit@0.10.0/lib/addon-fit.min.js"></script>
-<script src="https://cdn.jsdelivr.net/npm/@xterm/addon-web-links@0.11.0/lib/addon-web-links.min.js"></script>
+<!--
+  Subresource Integrity on every CDN asset.
+
+  Without it this page executes whatever jsdelivr returns, inside a document
+  that holds the web terminal's access token and drives a shell in a container —
+  an upstream compromise, a hijacked package version or a MITM on a phone's
+  network is arbitrary code with that reach. The hashes below were computed
+  from the exact bytes at these pinned versions. `crossorigin="anonymous"` is
+  required for SRI to be checked on a cross-origin fetch.
+
+  Bumping a version means recomputing its hash:
+      curl -sS <url> | openssl dgst -sha384 -binary | openssl base64 -A
+  A mismatched hash blocks the asset, so a stale hash shows up immediately as a
+  terminal that does not render — never as an unverified load.
+
+  These are still remote loads: the remote terminal does not work with no
+  internet on the client side, and vendoring the ~300 KB of minified xterm into
+  this file would fix that. It was not done here — SRI already closes the
+  integrity half, which is the security half, and the availability half is a
+  separate call about binary size and diff readability.
+-->
+<link rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/@xterm/xterm@5.5.0/css/xterm.min.css"
+      integrity="sha384-tStR1zLfWgsiXCF3IgfB3lBa8KmBe/lG287CL9WCeKgQYcp1bjb4/+mwN6oti4Co"
+      crossorigin="anonymous">
+<script src="https://cdn.jsdelivr.net/npm/@xterm/xterm@5.5.0/lib/xterm.min.js"
+        integrity="sha384-J4qzUjBl1FxyLsl/kQPQIOeINsmp17OHYXDOMpMxlKX53ZfYsL+aWHpgArvOuof9"
+        crossorigin="anonymous"></script>
+<script src="https://cdn.jsdelivr.net/npm/@xterm/addon-fit@0.10.0/lib/addon-fit.min.js"
+        integrity="sha384-XGqKrV8Jrukp1NITJbOEHwg01tNkuXr6uB6YEj69ebpYU3v7FvoGgEg23C1Gcehk"
+        crossorigin="anonymous"></script>
+<script src="https://cdn.jsdelivr.net/npm/@xterm/addon-web-links@0.11.0/lib/addon-web-links.min.js"
+        integrity="sha384-S1biLeI8L/bFduIVvCxbn/l4EtaG4nTqQjGF7qCYTbsGXGFe8KgIKXtw4+UWxprv"
+        crossorigin="anonymous"></script>
 <style>
   :root {
     --bg-primary: #1a1b26;
@@ -159,7 +226,7 @@
     position: absolute;
     inset: 0;
     display: none;
-    padding: 4px;
+    padding: 4px 4px 16px 4px;
   }
   .terminal-container.active { display: block; }
 
@@ -226,6 +293,51 @@
   .scroll-bottom-btn:hover { background: var(--accent-hover); }
   .scroll-bottom-btn.visible { display: flex; }
 
+  /* ── URL relay banner ───────────────────── */
+  .relay-banner {
+    position: absolute;
+    top: 8px;
+    left: 50%;
+    transform: translateX(-50%);
+    max-width: min(94%, 620px);
+    display: none;
+    align-items: center;
+    gap: 10px;
+    padding: 8px 10px;
+    background: var(--bg-secondary);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    box-shadow: 0 4px 12px rgba(0,0,0,0.45);
+    z-index: 30;
+  }
+  .relay-banner.visible { display: flex; }
+  .relay-banner-text { flex: 1; min-width: 0; }
+  .relay-banner-label {
+    font-size: 11px;
+    color: var(--text-secondary);
+    margin-bottom: 2px;
+  }
+  .relay-banner-url {
+    display: block;
+    font-size: 12px;
+    font-family: 'Cascadia Code', 'Fira Code', 'JetBrains Mono', 'Menlo', monospace;
+    color: var(--accent);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .relay-banner-dismiss {
+    flex-shrink: 0;
+    background: transparent;
+    border: none;
+    color: var(--text-secondary);
+    font-size: 14px;
+    line-height: 1;
+    padding: 4px 6px;
+    cursor: pointer;
+  }
+  .relay-banner-dismiss:hover { color: var(--text-primary); }
+
   /* ── Empty State ─────────────────────────── */
   .empty-state {
     display: flex;
@@ -272,6 +384,15 @@
     <div class="hint">Use the buttons above to start a Claude or Bash session</div>
   </div>
   <button class="scroll-bottom-btn" id="scrollBottomBtn" title="Scroll to bottom">&#8595;</button>
+  <!-- URL relay: a CLI in the container asked for a browser. Tap-to-open only,
+       never automatic — see the OSC 7777 handler below. -->
+  <div class="relay-banner" id="relayBanner">
+    <div class="relay-banner-text">
+      <div class="relay-banner-label">Container asked to open a URL &mdash; tap to open here</div>
+      <a class="relay-banner-url" id="relayBannerLink" target="_blank" rel="noopener noreferrer"></a>
+    </div>
+    <button class="relay-banner-dismiss" id="relayBannerDismiss" aria-label="Dismiss">&#10005;</button>
+  </div>
 </div>
 
 <!-- Input Bar for mobile/tablet -->
@@ -280,6 +401,9 @@
     autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"
     enterkeyhint="send" inputmode="text">
   <button class="key-btn" id="btnEnter">Enter</button>
+  <!-- A newline *without* submitting. There is no Shift on a phone keyboard,
+       so the chord the desktop app binds needs a key of its own here. -->
+  <button class="key-btn" id="btnNewline" title="Insert a newline without submitting (Shift+Enter)">&#8629;+</button>
   <button class="key-btn" id="btnTab">Tab</button>
   <button class="key-btn" id="btnCtrlC">^C</button>
 </div>
@@ -306,9 +430,130 @@
   const emptyState = document.getElementById('emptyState');
   const mobileInput = document.getElementById('mobileInput');
   const btnEnter = document.getElementById('btnEnter');
+  const btnNewline = document.getElementById('btnNewline');
+
+  // Whether the *active* session understands ESC+CR as "insert a newline".
+  //
+  // Only Claude Code does. `bash -l` has no readline binding for `\e\r`, so
+  // sending it there is a silent no-op — which is worse from the mobile bar
+  // than from a hardware key, because the bar puts a dedicated button on
+  // screen that appears to do nothing. The xterm key handler is already scoped
+  // this way; these two paths were not.
+  function activeSessionTakesEscCr() {
+    const s = activeSessionId && sessions[activeSessionId];
+    return !!s && s.type === 'claude';
+  }
   const btnTab = document.getElementById('btnTab');
   const btnCtrlC = document.getElementById('btnCtrlC');
   const scrollBottomBtn = document.getElementById('scrollBottomBtn');
+  const relayBanner = document.getElementById('relayBanner');
+  const relayBannerLink = document.getElementById('relayBannerLink');
+  const relayBannerDismiss = document.getElementById('relayBannerDismiss');
+
+  // ── URL relay (OSC 7777) ───────────────────
+  // `container/triple-c-open` — installed in the container as xdg-open,
+  // $BROWSER, sensible-browser, ... — emits ESC]7777;open;<base64(url)>BEL
+  // when a CLI wants a browser. The desktop app turns that into a host-browser
+  // open; here the only browser available is the *remote viewer's*.
+  //
+  // That is a different trust situation, so this deliberately does NOT mirror
+  // the desktop behaviour: nothing opens by itself. The web terminal may be
+  // reached from a phone on the LAN or through a tunnel, and the viewer's
+  // browser carries their own logged-in sessions and can reach their own
+  // network. We surface the request as a tap-to-open link and let the human
+  // decide. (A popup would be blocked without a user gesture anyway.)
+  // The same http/https allowlist as the desktop side applies — this file is
+  // standalone (embedded via include_str!) so it cannot import lib/urlRelay.ts;
+  // the logic is kept deliberately short and identical in behaviour.
+  const RELAY_OSC = 7777;
+  const RELAY_MAX_URL = 8192;
+  let relayTimes = [];
+  let relayLastUrl = null;
+  let relayLastAt = 0;
+  let relayHideTimer = null;
+
+  // ─── shared-url-sanitizer ─────────────────────────────────────
+  // THIS IS A COPY OF `sanitizeRelayUrl` IN app/src/lib/urlRelay.ts.
+  // It exists only because this file is embedded standalone via include_str!()
+  // and cannot import a module. Change one, change the other — and note that
+  // app/src/lib/urlRelay.embedded.test.ts reads this file, extracts the block
+  // between these two markers and runs it against the same table of cases as
+  // the TypeScript original, so a divergence fails the suite instead of
+  // silently shipping. Keep the markers, the function name and the arity
+  // intact: that test finds the code by them.
+  function sanitizeRelayUrl(raw) {
+    if (typeof raw !== 'string') return null;
+    const s = raw.trim();
+    if (!s || s.length > RELAY_MAX_URL) return null;
+    // Control characters and whitespace first: new URL() strips tabs/newlines,
+    // so "java\nscript:" would otherwise slip through as javascript:. Quotes
+    // and backticks go with them — all three are illegal in a URL, and this
+    // string ends up as an argument to something that may treat them as syntax.
+    for (const ch of s) {
+      const code = ch.codePointAt(0);
+      if (code <= 0x20 || code === 0x7f) return null;
+      if (code >= 0x80 && code <= 0x9f) return null;
+      if (ch === '"' || ch === "'" || ch === '`') return null;
+      if (ch.trim() === '') return null;
+    }
+    let u;
+    try { u = new URL(s); } catch (e) { return null; }
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') return null;
+    if (!u.hostname) return null;
+    if (u.username || u.password) return null;  // origin spoofing
+    return u.toString();
+  }
+  // ─── end shared-url-sanitizer ────────────────────────────────
+
+  function parseRelayOsc(data) {
+    if (typeof data !== 'string') return null;
+    const sep = data.indexOf(';');
+    if (sep === -1) return null;
+    if (data.slice(0, sep) !== 'open') return null;
+    const body = data.slice(sep + 1);
+    if (!body || body.length > RELAY_MAX_URL * 2) return null;
+    if (!/^[A-Za-z0-9+/]+=*$/.test(body)) return null;
+    let text;
+    try {
+      const bin = atob(body);
+      const bytes = Uint8Array.from(bin, c => c.charCodeAt(0));
+      text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    } catch (e) { return null; }
+    return sanitizeRelayUrl(text);
+  }
+
+  // Cap the prompt rate so a runaway loop in the container can't bury the UI.
+  function relayAllowed(url) {
+    const now = Date.now();
+    if (url === relayLastUrl && now - relayLastAt < 5000) {
+      relayLastAt = now;
+      return false;
+    }
+    relayTimes = relayTimes.filter(t => now - t < 10000);
+    if (relayTimes.length >= 5) return false;
+    relayTimes.push(now);
+    relayLastUrl = url;
+    relayLastAt = now;
+    return true;
+  }
+
+  function hideRelayBanner() {
+    relayBanner.classList.remove('visible');
+    relayBannerLink.removeAttribute('href');
+    relayBannerLink.textContent = '';
+    clearTimeout(relayHideTimer);
+  }
+
+  function showRelayBanner(url) {
+    relayBannerLink.href = url;
+    relayBannerLink.textContent = url;
+    relayBanner.classList.add('visible');
+    clearTimeout(relayHideTimer);
+    relayHideTimer = setTimeout(hideRelayBanner, 60000);
+  }
+
+  relayBannerDismiss.addEventListener('click', hideRelayBanner);
+  relayBannerLink.addEventListener('click', () => hideRelayBanner());
 
   // ── WebSocket ──────────────────────────────
   function connect() {
@@ -357,7 +602,7 @@
         updateProjectList(msg.projects);
         break;
       case 'opened':
-        onSessionOpened(msg.session_id, msg.project_name);
+        onSessionOpened(msg.session_id, msg.project_name, msg.session_type);
         break;
       case 'output':
         onSessionOutput(msg.session_id, msg.data);
@@ -408,8 +653,18 @@
     });
   }
 
-  function onSessionOpened(sessionId, projectName) {
-    const sessionType = pendingSessionType || 'claude';
+  function onSessionOpened(sessionId, projectName, serverSessionType) {
+    // Prefer the type the *server* reports for this session. The old path read
+    // a single `pendingSessionType` global set at request time, so opening two
+    // sessions before the first reply landed swapped their labels — routine on
+    // mobile, where nothing disables the buttons. That was cosmetic until
+    // Shift+Enter became type-dependent: a Claude session labelled `shell`
+    // sends a bare CR and submits a half-written prompt.
+    //
+    // The fallback keeps an older server working, and defaults to `claude`,
+    // which is the safe direction — ESC+CR is an unbound no-op in bash, while
+    // a bare CR in Claude Code loses the prompt.
+    const sessionType = serverSessionType || pendingSessionType || 'claude';
     pendingSessionType = null;
 
     // Create terminal
@@ -448,6 +703,15 @@
     const webLinksAddon = new WebLinksAddon.WebLinksAddon();
     term.loadAddon(webLinksAddon);
 
+    // URL relay from the container (see the OSC 7777 notes above). Always
+    // returns true so the sequence is consumed and never painted as garbage,
+    // whether or not we act on it.
+    term.parser.registerOscHandler(RELAY_OSC, data => {
+      const url = parseRelayOsc(data);
+      if (url && relayAllowed(url)) showRelayBanner(url);
+      return true;
+    });
+
     // Create container div
     const container = document.createElement('div');
     container.className = 'terminal-container';
@@ -476,6 +740,34 @@
       });
     });
 
+    // Shift+Enter inserts a newline in Claude Code's prompt instead of
+    // submitting it. xterm.js does not consult `shiftKey` for Enter, so
+    // without this Shift+Enter is byte-identical to Enter.
+    //
+    // `\x1b\r` — ESC then CR — is what Claude Code parses as `return` with
+    // meta, and it is the same sequence its own `/terminal-setup` installs for
+    // VS Code, Cursor, Alacritty and Zed. Do not "simplify" it to `\n`: that
+    // also works in Claude Code, but a shell would *run* the line, so the two
+    // session types would diverge. Claude sessions only, for that reason —
+    // `bash -l` has no readline binding for `\e\r`.
+    term.attachCustomKeyEventHandler(e => {
+      if (
+        e.type === 'keydown' && e.key === 'Enter' && e.shiftKey &&
+        !e.ctrlKey && !e.altKey && !e.metaKey && !e.isComposing &&
+        sessionType === 'claude'
+      ) {
+        sendTerminalInput('\x1b\r');
+        // `preventDefault()` is what stops the submit, not the `return false`.
+        // xterm's `_keyDown` returns before setting `_keyDownHandled`, so
+        // `_keyPress` still fires and emits a bare CR for Enter — inserting the
+        // newline and then submitting the prompt anyway. See the same comment
+        // in TerminalView.tsx.
+        e.preventDefault();
+        return false;
+      }
+      return true;
+    });
+
     // Track scroll position for scroll-to-bottom button
     term.onScroll(() => updateScrollButton());
 
@@ -527,6 +819,7 @@
       switchToSession(remaining[remaining.length - 1]);
     } else {
       activeSessionId = null;
+      syncNewlineButton();
       emptyState.style.display = '';
     }
   }
@@ -553,6 +846,7 @@
 
   function switchToSession(sessionId) {
     activeSessionId = sessionId;
+    syncNewlineButton();
 
     // Update tab styles
     document.querySelectorAll('.tab').forEach(t => t.classList.remove('active'));
@@ -628,7 +922,11 @@
         sendTerminalInput(val);
         mobileInput.value = '';
       }
-      sendTerminalInput('\r');
+      // Shift+Enter is a newline, not a submit — same bytes, and the same
+      // reasoning, as the terminal's own key handler above. A hardware
+      // keyboard on a tablet is the only way to reach this; the phone case is
+      // the dedicated newline button beside Enter.
+      sendTerminalInput(e.shiftKey && activeSessionTakesEscCr() ? '\x1b\r' : '\r');
     } else if (e.key === 'Tab') {
       e.preventDefault();
       sendTerminalInput('\t');
@@ -636,6 +934,27 @@
   });
 
   btnEnter.onclick = () => { sendTerminalInput('\r'); mobileInput.focus(); };
+  btnNewline.onclick = () => {
+    if (!activeSessionTakesEscCr()) { mobileInput.focus(); return; }
+    sendTerminalInput('\x1b\r');
+    mobileInput.focus();
+  };
+
+  // Keep the button's affordance honest: on a shell tab there is no byte that
+  // means "newline without running the line", so the control is disabled
+  // rather than left looking live.
+  function syncNewlineButton() {
+    const usable = activeSessionTakesEscCr();
+    btnNewline.disabled = !usable;
+    btnNewline.title = usable
+      ? 'Insert a newline without submitting (Shift+Enter)'
+      : 'Only Claude sessions support this — a shell runs the line instead';
+  }
+
+  // With no session open yet, `activeSessionTakesEscCr()` is already false —
+  // but nothing had called this, so the button rendered live before the first
+  // tab existed.
+  syncNewlineButton();
   btnTab.onclick = () => { sendTerminalInput('\t'); mobileInput.focus(); };
   btnCtrlC.onclick = () => { sendTerminalInput('\x03'); mobileInput.focus(); };
 

app/src-tauri/src/web_terminal/ws_handler.rs

@@ -46,6 +46,16 @@ enum ServerMessage {
     Opened {
         session_id: String,
         project_name: String,
+        /// Echoed back so the client can label the session from the reply
+        /// rather than from a global set at request time.
+        ///
+        /// Without it the client correlates through a single
+        /// `pendingSessionType`, so opening two sessions before the first
+        /// reply lands swaps their labels. That used to be cosmetic; it stopped
+        /// being cosmetic when Shift+Enter became type-dependent, because a
+        /// Claude session mislabelled as a shell now submits a half-written
+        /// prompt instead of inserting a newline.
+        session_type: String,
     },
     Output {
         session_id: String,
@@ -205,11 +215,11 @@ fn build_terminal_cmd(project: &Project, settings_store: &crate::storage::settin
             .map(|b| b.auth_method == BedrockAuthMethod::Profile)
             .unwrap_or(false);
 
+    let permission_args = project.effective_permission_mode().cli_args();
+
     if !is_bedrock_profile {
         let mut cmd = vec!["claude".to_string()];
-        if project.full_permissions {
-            cmd.push("--dangerously-skip-permissions".to_string());
-        }
+        cmd.extend(permission_args);
         return cmd;
     }
 
@@ -218,11 +228,13 @@ fn build_terminal_cmd(project: &Project, settings_store: &crate::storage::settin
         settings_store.get().global_aws.aws_profile.as_deref(),
     );
 
-    let claude_cmd = if project.full_permissions {
-        "exec claude --dangerously-skip-permissions"
-    } else {
-        "exec claude"
-    };
+    // The args are interpolated into a shell script string below, so
+    // single-quote each one.
+    let permission_flags: String = permission_args
+        .iter()
+        .map(|a| format!(" '{}'", a.replace('\'', "'\\''")))
+        .collect();
+    let claude_cmd = format!("exec claude{}", permission_flags);
 
     let script = format!(
         r#"
@@ -317,6 +329,11 @@ async fn handle_open(
     let _ = out_tx.send(ServerMessage::Opened {
         session_id,
         project_name,
+        // Derived from the same match that chose `cmd` above, not echoed from
+        // the request: anything that is not exactly "bash" runs Claude, so
+        // echoing the raw value would label an unrecognised string as its own
+        // type and put the client back where it started.
+        session_type: if session_type == Some("bash") { "bash" } else { "claude" }.to_string(),
     });
 
     Ok(())

app/src-tauri/tauri.conf.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/tauri-apps/tauri/dev/crates/tauri-cli/schema.json",
   "productName": "Triple-C",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "identifier": "com.triple-c.desktop",
   "build": {
     "beforeDevCommand": "npm run dev",
@@ -22,7 +22,7 @@
       }
     ],
     "security": {
-      "csp": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' asset: https://asset.localhost; font-src 'self' data:; connect-src 'self' ipc: http://ipc.localhost"
+      "csp": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' blob:; font-src 'self'; connect-src 'self' ipc: http://ipc.localhost; frame-src http://127.0.0.1:47820 http://127.0.0.1:47821 http://127.0.0.1:47822 http://127.0.0.1:47823 http://127.0.0.1:47824 http://127.0.0.1:47825 http://127.0.0.1:47826 http://127.0.0.1:47827; form-action 'none'; base-uri 'none'; object-src 'none'"
     }
   },
   "bundle": {
@@ -33,6 +33,7 @@
       "icons/128x128.png",
       "icons/128x128@2x.png",
       "icons/icon.ico",
+      "icons/icon.icns",
       "icons/icon.png"
     ]
   },

app/src/App.tsx

@@ -1,26 +1,77 @@
-import { useEffect } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { useShallow } from "zustand/react/shallow";
+import { listen } from "@tauri-apps/api/event";
 import Sidebar from "./components/layout/Sidebar";
 import TopBar from "./components/layout/TopBar";
 import StatusBar from "./components/layout/StatusBar";
+import NotesDock from "./components/layout/NotesDock";
 import TerminalView from "./components/terminal/TerminalView";
+import DockerInstallDialog from "./components/DockerInstallDialog";
+import ProjectHome from "./components/projects/home/ProjectHome";
+import AddProjectDialog from "./components/projects/AddProjectDialog";
+import ToastHost from "./components/ui/ToastHost";
+import { PaneVisibilityProvider } from "./components/ui/PaneVisibility";
+import StatusIndicator from "./components/ui/StatusIndicator";
+import Button from "./components/ui/Button";
 import { useDocker } from "./hooks/useDocker";
 import { useSettings } from "./hooks/useSettings";
 import { useProjects } from "./hooks/useProjects";
-import { useMcpServers } from "./hooks/useMcpServers";
 import { useUpdates } from "./hooks/useUpdates";
-import { useAppState } from "./store/appState";
+import { useTerminal } from "./hooks/useTerminal";
+import { useSTT } from "./hooks/useSTT";
+import { useContainerProgress } from "./hooks/useContainerProgress";
+import { useKeyboardShortcuts } from "./hooks/useKeyboardShortcuts";
+import { useAppState, isHomeTab, tabKeyId, homeTabKey } from "./store/appState";
 import { reconcileProjectStatuses } from "./lib/tauri-commands";
 
 export default function App() {
   const { checkDocker, checkImage, startDockerPolling } = useDocker();
   const { loadSettings } = useSettings();
   const { refresh } = useProjects();
-  const { refresh: refreshMcp } = useMcpServers();
   const { loadVersion, checkForUpdates, checkImageUpdate, startPeriodicCheck } = useUpdates();
-  const { sessions, activeSessionId, setProjects } = useAppState(
-    useShallow(s => ({ sessions: s.sessions, activeSessionId: s.activeSessionId, setProjects: s.setProjects }))
-  );
+  const { sessions, activeSessionId, tabOrder, activeTabKey, setProjects, setSttToggle } =
+    useAppState(
+      useShallow(s => ({
+        sessions: s.sessions,
+        activeSessionId: s.activeSessionId,
+        tabOrder: s.tabOrder,
+        activeTabKey: s.activeTabKey,
+        setProjects: s.setProjects,
+        setSttToggle: s.setSttToggle,
+      }))
+    );
+  const [showInstallDialog, setShowInstallDialog] = useState(false);
+  const [shuttingDown, setShuttingDown] = useState(false);
+
+  /**
+   * Everything that can only be done once Docker answers. Called from the
+   * startup check *and* from the poller when the daemon shows up later — a
+   * session that launched before Docker was ready otherwise never reconciles
+   * container state or recovers an interrupted migration.
+   */
+  const onDockerReady = useCallback(async () => {
+    checkImage();
+    // Reconcile project statuses against actual Docker container state,
+    // then refresh the project list so the UI reflects reality.
+    try {
+      setProjects(await reconcileProjectStatuses());
+    } catch {
+      // If reconciliation fails (e.g. Docker hiccup), just load from store
+      refresh();
+    }
+  }, [checkImage, setProjects, refresh]);
+
+  // Single STT instance bound to the active session. The mic lives in the
+  // StatusBar; the terminal's Ctrl+Shift+M shortcut calls stt.toggle via the
+  // store (registered below).
+  const { sendInput } = useTerminal();
+  const stt = useSTT(activeSessionId ?? "", sendInput);
+  useEffect(() => {
+    setSttToggle(stt.toggle);
+  }, [stt.toggle, setSttToggle]);
+
+  useContainerProgress();
+  useKeyboardShortcuts();
 
   // Initialize on mount
   useEffect(() => {
@@ -28,21 +79,13 @@ export default function App() {
     let stopPolling: (() => void) | undefined;
     checkDocker().then((available) => {
       if (available) {
-        checkImage();
-        // Reconcile project statuses against actual Docker container state,
-        // then refresh the project list so the UI reflects reality.
-        reconcileProjectStatuses().then((projects) => {
-          setProjects(projects);
-        }).catch(() => {
-          // If reconciliation fails (e.g. Docker hiccup), just load from store
-          refresh();
-        });
+        onDockerReady();
       } else {
-        stopPolling = startDockerPolling();
+        setShowInstallDialog(true);
+        stopPolling = startDockerPolling(onDockerReady);
       }
     });
     refresh();
-    refreshMcp();
 
     // Update detection
     loadVersion();
@@ -58,44 +101,186 @@ export default function App() {
     };
   }, []); // eslint-disable-line react-hooks/exhaustive-deps
 
+  // The backend prevents the window closing so it can stop containers first,
+  // which freezes the UI for several seconds. This says why.
+  useEffect(() => {
+    let unlisten: (() => void) | undefined;
+    let cancelled = false;
+    listen("app-shutting-down", () => setShuttingDown(true))
+      .then((fn) => {
+        if (cancelled) fn();
+        else unlisten = fn;
+      })
+      .catch((e) => console.error("Failed to listen for shutdown:", e));
+    return () => {
+      cancelled = true;
+      unlisten?.();
+    };
+  }, []);
+
+  const homeProjectIds = tabOrder.filter(isHomeTab).map(tabKeyId);
+
   return (
-    <div className="flex flex-col h-screen p-6 gap-4 bg-[var(--bg-primary)]">
+    <div className="flex flex-col h-screen p-3 gap-3 bg-[var(--bg-primary)]">
       <TopBar />
-      <div className="flex flex-1 min-h-0 gap-4">
+      <div className="flex flex-1 min-h-0 gap-3">
         <Sidebar />
-        <main className="flex-1 bg-[var(--bg-secondary)] border border-[var(--border-color)] rounded-lg min-w-0 overflow-hidden">
-          {sessions.length === 0 ? (
+        <main className="flex-1 bg-[var(--bg-secondary)] border border-[var(--border-color)] rounded-[var(--radius-panel)] min-w-0 overflow-hidden">
+          {tabOrder.length === 0 ? (
             <WelcomeScreen />
           ) : (
             <div className="w-full h-full">
+              {/* Every tab stays mounted and the inactive ones are merely
+                  `hidden`, which a dialog's portal to `document.body` does not
+                  inherit: a confirmation opened in one project stayed painted
+                  over whatever tab the user switched to, kept its focus trap,
+                  and — being a blocking overlay — refused every native file
+                  drop in the window. `PaneVisibilityProvider` is how a `Modal`
+                  inside a pane finds out the pane stepped aside. */}
+              {homeProjectIds.map((projectId) => (
+                <PaneVisibilityProvider
+                  key={projectId}
+                  visible={activeTabKey === homeTabKey(projectId)}
+                >
+                  <ProjectHome
+                    projectId={projectId}
+                    active={activeTabKey === homeTabKey(projectId)}
+                  />
+                </PaneVisibilityProvider>
+              ))}
               {sessions.map((session) => (
-                <TerminalView
+                <PaneVisibilityProvider
                   key={session.id}
-                  sessionId={session.id}
-                  active={session.id === activeSessionId}
-                />
+                  visible={session.id === activeSessionId}
+                >
+                  <TerminalView
+                    sessionId={session.id}
+                    active={session.id === activeSessionId}
+                  />
+                </PaneVisibilityProvider>
               ))}
             </div>
           )}
         </main>
+        <NotesDock />
       </div>
-      <StatusBar />
+      <StatusBar stt={stt} />
+      <ToastHost />
+      {showInstallDialog && (
+        <DockerInstallDialog onClose={() => setShowInstallDialog(false)} />
+      )}
+      {shuttingDown && (
+        <div
+          className="fixed inset-0 z-50 flex items-center justify-center bg-[var(--bg-primary)]/95 backdrop-blur-sm"
+          role="status"
+          aria-live="polite"
+          /* Covers the whole window, so no pane underneath may accept a
+             native file drop while it is up — see `lib/dropTarget.ts`. */
+          data-blocks-drop="true"
+          data-testid="shutdown-overlay"
+        >
+          <div className="flex flex-col items-center gap-2 px-6 text-center">
+            <StatusIndicator tone="busy" label="Shutting down" className="text-sm" />
+            <p className="text-[13px] text-[var(--text-secondary)]">
+              Stopping containers before quitting. This window will close on its own.
+            </p>
+          </div>
+        </div>
+      )}
     </div>
   );
 }
 
+/**
+ * First run is a checklist, not a paragraph: it reuses state the app already
+ * tracks and ends in a real button.
+ */
 function WelcomeScreen() {
+  const { dockerAvailable, imageExists, projects, openProjectHome } = useAppState(
+    useShallow((s) => ({
+      dockerAvailable: s.dockerAvailable,
+      imageExists: s.imageExists,
+      projects: s.projects,
+      openProjectHome: s.openProjectHome,
+    })),
+  );
+  const [showAdd, setShowAdd] = useState(false);
+
+  const steps: {
+    label: string;
+    state: boolean | null;
+    pendingLabel: string;
+    failLabel: string;
+  }[] = [
+    {
+      label: "Docker detected",
+      state: dockerAvailable,
+      pendingLabel: "Checking for Docker…",
+      failLabel: "Docker not available",
+    },
+    {
+      label: "Container image ready",
+      state: imageExists,
+      pendingLabel: "Checking for the image…",
+      failLabel: "Image not pulled yet — see Settings › Container",
+    },
+    {
+      label: `${projects.length} project${projects.length === 1 ? "" : "s"} configured`,
+      state: projects.length > 0 ? true : false,
+      pendingLabel: "",
+      failLabel: "No projects yet",
+    },
+  ];
+
   return (
-    <div className="flex items-center justify-center h-full text-[var(--text-secondary)]">
-      <div className="text-center">
-        <h1 className="text-3xl font-bold mb-2 text-[var(--text-primary)]">
-          Triple-C
-        </h1>
-        <p className="text-sm mb-4">Claude Code Container</p>
-        <p className="text-xs max-w-md">
-          Add a project from the sidebar, start its container, then open a
-          terminal to begin using Claude Code in a sandboxed environment.
+    <div className="flex items-center justify-center h-full p-6">
+      <div className="w-full max-w-md">
+        <h1 className="text-xl font-semibold text-[var(--text-primary)]">Triple-C</h1>
+        <p className="text-[13px] text-[var(--text-secondary)] mb-5">
+          Claude Code, sandboxed in a container.
         </p>
+
+        <ol className="space-y-2 mb-5">
+          {steps.map((step) => (
+            <li
+              key={step.label}
+              className="flex items-center gap-2 px-3 py-2 bg-[var(--bg-primary)] border border-[var(--border-color)] rounded-[var(--radius-control)]"
+            >
+              <StatusIndicator
+                tone={step.state === true ? "ok" : step.state === false ? "error" : "unknown"}
+                label={
+                  step.state === true
+                    ? step.label
+                    : step.state === false
+                      ? step.failLabel
+                      : step.pendingLabel
+                }
+                className="text-[13px]"
+              />
+            </li>
+          ))}
+        </ol>
+
+        <div className="flex items-center gap-2">
+          <Button size="md" variant="primary" onClick={() => setShowAdd(true)}>
+            {projects.length === 0 ? "Add your first project" : "Add a project"}
+          </Button>
+          {projects.length > 0 && (
+            <Button size="md" onClick={() => openProjectHome(projects[0].id)}>
+              Open {projects[0].name}
+            </Button>
+          )}
+        </div>
+
+        <p className="mt-4 text-xs text-[var(--text-secondary)]">
+          Then start its container and press{" "}
+          <kbd className="px-1 py-0.5 font-mono bg-[var(--bg-tertiary)] border border-[var(--border-color)] rounded-[4px]">
+            Ctrl+T
+          </kbd>{" "}
+          to open a Claude terminal.
+        </p>
+
+        {showAdd && <AddProjectDialog onClose={() => setShowAdd(false)} />}
       </div>
     </div>
   );

app/src/components/DockerInstallDialog.tsx

@@ -0,0 +1,177 @@
+import { useEffect, useState } from "react";
+import { openUrl } from "@tauri-apps/plugin-opener";
+import { useInstallHelper } from "../hooks/useInstallHelper";
+import { useDocker } from "../hooks/useDocker";
+import Modal from "./ui/Modal";
+import Button from "./ui/Button";
+
+interface Props {
+  onClose: () => void;
+}
+
+type Phase = "idle" | "installing" | "done" | "error";
+
+export default function DockerInstallDialog({ onClose }: Props) {
+  const { options, loadOptions, runInstall } = useInstallHelper();
+  const { checkDocker } = useDocker();
+  const [showManual, setShowManual] = useState(false);
+  const [phase, setPhase] = useState<Phase>("idle");
+  const [log, setLog] = useState<string[]>([]);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    loadOptions();
+  }, [loadOptions]);
+
+  const handleInstall = async () => {
+    setPhase("installing");
+    setLog([]);
+    setError(null);
+    try {
+      await runInstall((line) => setLog((prev) => [...prev, line]));
+      setPhase("done");
+      // Re-check Docker so the rest of the app can proceed without a reload.
+      await checkDocker();
+    } catch (e) {
+      setError(String(e));
+      setPhase("error");
+    }
+  };
+
+  const handleOpenDocs = async () => {
+    if (!options) return;
+    try {
+      await openUrl(options.docs_url);
+    } catch (e) {
+      console.error("Failed to open docs URL:", e);
+    }
+  };
+
+  const handleRecheck = async () => {
+    const available = await checkDocker();
+    if (available) onClose();
+  };
+
+  if (!options) {
+    return null;
+  }
+
+  const installVerb =
+    phase === "installing" ? "Installing…" : `Install ${options.product_name}`;
+
+  return (
+    <Modal
+      title="Docker not detected"
+      onClose={onClose}
+      widthClassName="w-[34rem]"
+      // Closing mid-install would orphan a privileged installer.
+      dismissible={phase !== "installing"}
+      footer={
+        phase === "idle" ? (
+          <Button variant="ghost" onClick={onClose}>
+            Dismiss
+          </Button>
+        ) : undefined
+      }
+    >
+      <p className="text-[13px] text-[var(--text-secondary)] mb-4">
+        Triple-C needs a Docker-compatible runtime to manage sandboxed project
+        containers. We can install{" "}
+        <span className="text-[var(--text-primary)]">{options.product_name}</span> for
+        you, or you can follow the official instructions.
+      </p>
+
+      {phase === "idle" && (
+        <div className="flex flex-col gap-2">
+          {options.can_auto_install ? (
+            <Button size="md" variant="primary" onClick={handleInstall}>
+              {installVerb} ({options.auto_install_method})
+            </Button>
+          ) : (
+            <div className="text-xs text-[var(--text-secondary)] bg-[var(--bg-primary)] border border-[var(--border-color)] rounded-[var(--radius-control)] p-2">
+              One-click install unavailable:{" "}
+              <span className="text-[var(--text-primary)]">
+                {options.auto_install_blocker ?? "required tooling missing."}
+              </span>
+            </div>
+          )}
+
+          <Button size="md" onClick={() => setShowManual((s) => !s)}>
+            {showManual ? "Hide manual instructions" : "Show manual instructions"}
+          </Button>
+
+          <Button size="md" onClick={handleOpenDocs}>
+            Open official documentation ↗
+          </Button>
+        </div>
+      )}
+
+      {phase === "installing" && (
+        <div className="text-xs text-[var(--text-secondary)]">
+          Installing… a system password prompt may appear. Do not close this window.
+        </div>
+      )}
+
+      {phase === "done" && (
+        <div className="flex flex-col gap-2">
+          <div className="text-[13px] text-[var(--success)]">Install finished.</div>
+          {options.post_install_notes.length > 0 && (
+            <ul className="text-xs text-[var(--text-secondary)] list-disc list-inside space-y-1">
+              {options.post_install_notes.map((note, i) => (
+                <li key={i}>{note}</li>
+              ))}
+            </ul>
+          )}
+          <div className="flex gap-2 mt-2">
+            <Button size="md" variant="primary" onClick={handleRecheck}>
+              Re-check Docker
+            </Button>
+            <Button size="md" onClick={onClose}>
+              Close
+            </Button>
+          </div>
+        </div>
+      )}
+
+      {phase === "error" && (
+        <div className="flex flex-col gap-2">
+          <div className="text-[13px] text-[var(--error)]">Install failed.</div>
+          {error && (
+            <div className="text-xs font-mono text-[var(--error)] break-words">
+              {error}
+            </div>
+          )}
+          <div className="flex gap-2 mt-2">
+            <Button size="md" onClick={() => setPhase("idle")}>
+              Back
+            </Button>
+            <Button size="md" variant="primary" onClick={handleOpenDocs}>
+              Open official docs ↗
+            </Button>
+          </div>
+        </div>
+      )}
+
+      {(showManual || phase === "error") && (
+        <div className="mt-4">
+          <div className="text-xs font-medium mb-1.5 text-[var(--text-secondary)]">
+            Manual install steps
+          </div>
+          <ol className="text-xs text-[var(--text-secondary)] list-decimal list-inside space-y-1 bg-[var(--bg-primary)] border border-[var(--border-color)] rounded-[var(--radius-control)] p-2">
+            {options.manual_steps.map((step, i) => (
+              <li key={i}>{step}</li>
+            ))}
+          </ol>
+        </div>
+      )}
+
+      {log.length > 0 && (
+        <div className="mt-4 max-h-48 overflow-y-auto bg-[var(--bg-primary)] border border-[var(--border-color)] rounded-[var(--radius-control)] p-2 text-xs font-mono text-[var(--text-secondary)]">
+          {log.map((line, i) => (
+            <div key={i}>{line}</div>
+          ))}
+        </div>
+      )}
+    </Modal>
+  );
+}

app/src/components/layout/HelpDialog.test.tsx

@@ -0,0 +1,100 @@
+import { describe, it, expect } from "vitest";
+import { renderMarkdown } from "./HelpDialog";
+
+/**
+ * `renderMarkdown` builds HTML by regex substitution and the result is handed
+ * to `dangerouslySetInnerHTML`. Its input is the help document, which is
+ * fetched from GitHub at runtime — remote, versioned by someone else, and not
+ * something the app gets to trust. These tests pin the escaping.
+ */
+/**
+ * Parse rendered HTML and return its first anchor, asserting that *no* element
+ * anywhere in the output grew an attribute outside the allowed set. A broken
+ * attribute value is only interesting if it becomes an attribute, so the check
+ * has to run through a real parser rather than over the string.
+ */
+const ALLOWED_ATTRS = new Set(["class", "href", "target", "rel", "id"]);
+
+function onlyAnchor(html: string): HTMLAnchorElement {
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  for (const el of Array.from(doc.body.querySelectorAll("*"))) {
+    for (const name of attrNames(el)) {
+      expect(ALLOWED_ATTRS.has(name), `unexpected attribute ${name}`).toBe(true);
+    }
+  }
+  const anchors = doc.querySelectorAll("a");
+  expect(anchors.length).toBeGreaterThan(0);
+  return anchors[0] as HTMLAnchorElement;
+}
+
+/** Attribute names the parser actually saw on an element. */
+function attrNames(el: Element): string[] {
+  return Array.from(el.attributes).map((a) => a.name);
+}
+
+describe("renderMarkdown escaping", () => {
+  it("escapes the quote characters an attribute value is delimited by", () => {
+    const html = renderMarkdown('He said "hi" and it\'s fine.');
+    expect(html).not.toMatch(/said "hi"/);
+    expect(html).toContain(""hi"");
+    expect(html).toContain("it's");
+  });
+
+  it("does not let a link target break out of href=\"…\"", () => {
+    // The sink: the URL capture is `[^)]+`, which includes `"` and spaces, and
+    // the value lands directly inside `href="…"`. Asserted through the DOM,
+    // not by string matching — the payload text legitimately survives *inside*
+    // the attribute value; what must not happen is it becoming an attribute.
+    const a = onlyAnchor(
+      renderMarkdown(
+        '[click](https://example.com/" onmouseover="steal() formaction="https://evil.example)',
+      ),
+    );
+    expect(attrNames(a)).toEqual(["class", "href", "target", "rel"]);
+    expect(a.getAttribute("href")).toContain('" onmouseover="');
+  });
+
+  it("does not let an in-document anchor break out of href=\"#…\"", () => {
+    const a = onlyAnchor(
+      renderMarkdown('[jump](#top" onfocus="steal() autofocus="x)'),
+    );
+    expect(attrNames(a)).toEqual(["class", "href"]);
+  });
+
+  it("does not let a bare URL break out of href=\"…\"", () => {
+    const a = onlyAnchor(
+      renderMarkdown('See https://example.com/a"onmouseover="steal()\n'),
+    );
+    expect(attrNames(a)).toEqual(["class", "href", "target", "rel"]);
+  });
+
+  it("still renders ordinary links intact", () => {
+    const html = renderMarkdown("[docs](https://example.com/a?x=1&y=2)");
+    // `&` was entity-escaped by the first pass and must not be escaped twice.
+    expect(html).toContain('href="https://example.com/a?x=1&y=2"');
+    expect(html).not.toContain("&");
+    expect(html).toContain('target="_blank"');
+    expect(html).toContain('rel="noopener noreferrer"');
+    expect(html).toContain(">docs</a>");
+  });
+
+  it("still renders an in-document anchor link intact", () => {
+    const html = renderMarkdown("[jump](#getting-started)");
+    expect(html).toContain('href="#getting-started"');
+  });
+
+  it("keeps header slugs stable across the new quote escaping", () => {
+    // The regression this guards: quotes now become entities *before*
+    // `slugify` sees them, and an entity's letters would otherwise survive
+    // into the id ("claude39s-setup"), silently breaking every
+    // `[…](#claudes-setup)` in the document.
+    expect(renderMarkdown("## Claude's setup")).toContain('id="claudes-setup"');
+    expect(renderMarkdown('## The "safe" mode')).toContain('id="the-safe-mode"');
+  });
+
+  it("still refuses to emit raw tags from the source document", () => {
+    const html = renderMarkdown("<img src=x onerror=alert(1)>");
+    expect(html).not.toContain("<img");
+    expect(html).toContain("&lt;img");
+  });
+});

app/src/components/layout/HelpDialog.tsx

@@ -1,5 +1,7 @@
 import { useEffect, useRef, useCallback, useState } from "react";
 import { getHelpContent } from "../../lib/tauri-commands";
+import Modal from "../ui/Modal";
+import Button from "../ui/Button";
 
 interface Props {
   onClose: () => void;
@@ -10,21 +12,67 @@ function slugify(text: string): string {
   return text
     .toLowerCase()
     .replace(/<[^>]+>/g, "")       // strip HTML tags (e.g. from inline code)
+    // Quote characters are escaped to entities before this runs (see
+    // `renderMarkdown`). Drop those two entities whole, so a header with an
+    // apostrophe or a quote slugifies to what it did when the character was
+    // simply stripped — otherwise every such anchor id silently changes and
+    // the in-document links pointing at it stop resolving. `&amp;`/`&lt;`/
+    // `&gt;` are deliberately not in this list: they were already entities
+    // before, so their existing (odd) slugs are the established ones.
+    .replace(/&quot;|&#39;/g, "")
     .replace(/[^\w\s-]/g, "")      // remove non-word chars except spaces/dashes
     .replace(/\s+/g, "-")          // spaces to dashes
     .replace(/-+/g, "-")           // collapse consecutive dashes
     .replace(/^-|-$/g, "");        // trim leading/trailing dashes
 }
 
-/** Simple markdown-to-HTML converter for the help content. */
-function renderMarkdown(md: string): string {
+/**
+ * Escape a captured markdown value that is about to be interpolated into an
+ * HTML *attribute* value.
+ *
+ * `renderMarkdown` entity-escapes the whole document first, but that pass only
+ * covered `&`, `<` and `>` — not the quote characters, which is all an
+ * attribute value is delimited by. `[x](https://a" onload="…)` therefore closed
+ * `href="` and started a new attribute, because the URL capture is `[^)]+` and
+ * `"` is in `[^)]`. The document is remote GitHub markdown, so that capture is
+ * not ours to trust.
+ *
+ * Only quotes are escaped here: `&`, `<` and `>` have already been converted by
+ * the caller, and re-escaping the `&` would double-encode every `&amp;` in a
+ * query string.
+ */
+function attr(value: string): string {
+  return value.replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+/**
+ * Simple markdown-to-HTML converter for the help content.
+ *
+ * Exported for `HelpDialog.test.tsx`: the output goes to
+ * `dangerouslySetInnerHTML`, so the escaping rules below are security rules and
+ * need to be asserted rather than assumed.
+ */
+export function renderMarkdown(md: string): string {
   let html = md;
 
   // Normalize line endings
   html = html.replace(/\r\n/g, "\n");
 
-  // Escape HTML entities (but we'll re-introduce tags below)
-  html = html.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  // Escape HTML entities (but we'll re-introduce tags below).
+  //
+  // The quote characters are part of this on purpose. Everything below builds
+  // HTML by regex substitution, and several of those substitutions drop a
+  // capture straight into an attribute value (`href="$2"`). Leaving `"` and `'`
+  // live meant a link target could close the attribute and open another one —
+  // in a document fetched from GitHub at runtime and handed to
+  // `dangerouslySetInnerHTML`. Escaping here closes every such sink at the
+  // source; `attr()` below is the belt to this pair of braces.
+  html = html
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
 
   // Fenced code blocks (```...```)
   html = html.replace(/```(\w*)\n([\s\S]*?)```/g, (_m, _lang, code) => {
@@ -82,13 +130,15 @@ function renderMarkdown(md: string): string {
   // Markdown-style anchor links [text](#anchor)
   html = html.replace(
     /\[([^\]]+)\]\(#([^)]+)\)/g,
-    '<a class="help-link" href="#$2">$1</a>',
+    (_m, text: string, anchor: string) =>
+      `<a class="help-link" href="#${attr(anchor)}">${text}</a>`,
   );
 
   // Markdown-style external links [text](url)
   html = html.replace(
     /\[([^\]]+)\]\((https?:\/\/[^)]+)\)/g,
-    '<a class="help-link" href="$2" target="_blank" rel="noopener noreferrer">$1</a>',
+    (_m, text: string, url: string) =>
+      `<a class="help-link" href="${attr(url)}" target="_blank" rel="noopener noreferrer">${text}</a>`,
   );
 
   // Unordered list items (- ...)
@@ -115,7 +165,8 @@ function renderMarkdown(md: string): string {
   // Links - convert bare URLs to clickable links (skip already-wrapped URLs)
   html = html.replace(
     /(?<!="|'>)(https?:\/\/[^\s<)]+)/g,
-    '<a class="help-link" href="$1" target="_blank" rel="noopener noreferrer">$1</a>',
+    (_m, url: string) =>
+      `<a class="help-link" href="${attr(url)}" target="_blank" rel="noopener noreferrer">${url}</a>`,
   );
 
   // Wrap remaining loose text lines in paragraphs
@@ -140,32 +191,16 @@ function renderMarkdown(md: string): string {
 }
 
 export default function HelpDialog({ onClose }: Props) {
-  const overlayRef = useRef<HTMLDivElement>(null);
   const contentRef = useRef<HTMLDivElement>(null);
   const [markdown, setMarkdown] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
 
-  useEffect(() => {
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (e.key === "Escape") onClose();
-    };
-    document.addEventListener("keydown", handleKeyDown);
-    return () => document.removeEventListener("keydown", handleKeyDown);
-  }, [onClose]);
-
   useEffect(() => {
     getHelpContent()
       .then(setMarkdown)
       .catch((e) => setError(String(e)));
   }, []);
 
-  const handleOverlayClick = useCallback(
-    (e: React.MouseEvent<HTMLDivElement>) => {
-      if (e.target === overlayRef.current) onClose();
-    },
-    [onClose],
-  );
-
   // Handle anchor link clicks to scroll within the dialog
   const handleContentClick = useCallback((e: React.MouseEvent<HTMLDivElement>) => {
     const target = e.target as HTMLElement;
@@ -179,40 +214,25 @@ export default function HelpDialog({ onClose }: Props) {
   }, []);
 
   return (
-    <div
-      ref={overlayRef}
-      onClick={handleOverlayClick}
-      className="fixed inset-0 bg-black/50 flex items-center justify-center z-50"
+    <Modal
+      title="How to Use Triple-C"
+      onClose={onClose}
+      widthClassName="w-[48rem]"
+      footer={<Button onClick={onClose}>Close</Button>}
     >
-      <div className="bg-[var(--bg-secondary)] border border-[var(--border-color)] rounded-lg shadow-xl w-[48rem] max-w-[90vw] max-h-[85vh] flex flex-col">
-        {/* Header */}
-        <div className="flex items-center justify-between px-6 py-4 border-b border-[var(--border-color)] flex-shrink-0">
-          <h2 className="text-lg font-semibold">How to Use Triple-C</h2>
-          <button
-            onClick={onClose}
-            className="px-3 py-1.5 text-xs bg-[var(--bg-tertiary)] border border-[var(--border-color)] rounded hover:bg-[var(--border-color)] transition-colors"
-          >
-            Close
-          </button>
-        </div>
-
-        {/* Scrollable content */}
-        <div
-          ref={contentRef}
-          onClick={handleContentClick}
-          className="flex-1 overflow-y-auto px-6 py-4 help-content"
-        >
-          {error && (
-            <p className="text-[var(--error)] text-sm">Failed to load help content: {error}</p>
-          )}
-          {!markdown && !error && (
-            <p className="text-[var(--text-secondary)] text-sm">Loading...</p>
-          )}
-          {markdown && (
-            <div dangerouslySetInnerHTML={{ __html: renderMarkdown(markdown) }} />
-          )}
-        </div>
+      <div ref={contentRef} onClick={handleContentClick} className="help-content">
+        {error && (
+          <p className="text-[var(--error)] text-sm">
+            Failed to load help content: {error}
+          </p>
+        )}
+        {!markdown && !error && (
+          <p className="text-[var(--text-secondary)] text-sm">Loading…</p>
+        )}
+        {markdown && (
+          <div dangerouslySetInnerHTML={{ __html: renderMarkdown(markdown) }} />
+        )}
       </div>
-    </div>
+    </Modal>
   );
 }

app/src/components/layout/MainTabs.test.tsx

@@ -0,0 +1,267 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
+import MainTabs from "./MainTabs";
+import { useAppState, homeTabKey, terminalTabKey } from "../../store/appState";
+import type { Project, TerminalSession } from "../../lib/types";
+
+const close = vi.fn();
+
+const sessions: TerminalSession[] = [
+  {
+    id: "s1",
+    projectId: "p1",
+    projectName: "api-server",
+    sessionName: "claude",
+    sessionType: "claude",
+  },
+  {
+    id: "s2",
+    projectId: "p1",
+    projectName: "api-server",
+    sessionName: "shell",
+    sessionType: "bash",
+  },
+] as unknown as TerminalSession[];
+
+const projects: Project[] = [
+  {
+    id: "p1",
+    name: "api-server",
+    status: "running",
+    permission_mode: "bypass",
+    renamed_session_names: {},
+  },
+] as unknown as Project[];
+
+vi.mock("../../hooks/useTerminal", () => ({
+  useTerminal: () => ({ sessions, close }),
+}));
+vi.mock("../../hooks/useProjects", () => ({
+  useProjects: () => ({ projects, update: vi.fn() }),
+}));
+
+const HOME = homeTabKey("p1");
+const S1 = terminalTabKey("s1");
+const S2 = terminalTabKey("s2");
+
+/**
+ * A pointer event carrying a real `clientX`.
+ *
+ * jsdom implements no `PointerEvent`, so Testing Library's synthesized one has
+ * no coordinates — and the coordinate is the whole point here, since it decides
+ * which slot the drop lands in. `MouseEvent` has one, and React dispatches on
+ * the event's type name either way.
+ */
+function pointer(el: Element, type: string, clientX: number) {
+  fireEvent(el, new MouseEvent(type, { bubbles: true, cancelable: true, clientX, button: 0 }));
+}
+
+/** Press, move past the drag threshold, and release over `endX`. */
+function dragTab(el: Element, fromX: number, endX: number) {
+  pointer(el, "pointerdown", fromX);
+  pointer(el, "pointermove", endX);
+  pointer(el, "pointerup", endX);
+}
+
+/** Pin a tab's geometry so "past the midpoint" means something in jsdom. */
+function place(el: Element, left: number, width = 100) {
+  el.getBoundingClientRect = () =>
+    ({ left, width, right: left + width, top: 0, bottom: 30, height: 30, x: left, y: 0 }) as DOMRect;
+}
+
+/** Lay the strip out as three 100px tabs starting at x=0. */
+function laidOut() {
+  const tabs = screen.getAllByRole("tab");
+  tabs.forEach((tab, i) => place(tab, i * 100));
+  return tabs;
+}
+
+const order = () => useAppState.getState().tabOrder;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  useAppState.setState({
+    tabOrder: [HOME, S1, S2],
+    activeTabKey: HOME,
+    activeSessionId: null,
+    projects,
+  });
+});
+
+describe("MainTabs reordering", () => {
+  it("drags a tab to the front", () => {
+    render(<MainTabs />);
+    const tabs = laidOut();
+
+    // Left half of the first tab — the tab lands before it.
+    dragTab(tabs[2], 250, 10);
+
+    expect(order()).toEqual([S2, HOME, S1]);
+  });
+
+  it("drops after the tab when the pointer is past its midpoint", () => {
+    render(<MainTabs />);
+    const tabs = laidOut();
+
+    dragTab(tabs[0], 50, 190);
+
+    expect(order()).toEqual([S1, HOME, S2]);
+  });
+
+  it("drops at the end when released past the last tab", () => {
+    render(<MainTabs />);
+    const tabs = laidOut();
+
+    dragTab(tabs[0], 50, 800);
+
+    expect(order()).toEqual([S1, S2, HOME]);
+  });
+
+  it("dragging does not steal the selection", () => {
+    render(<MainTabs />);
+    const tabs = laidOut();
+
+    dragTab(tabs[1], 150, 290);
+
+    expect(order()).toEqual([HOME, S2, S1]);
+    expect(useAppState.getState().activeTabKey).toBe(HOME);
+  });
+
+  it("does not let a drag select the tab's text", () => {
+    // A pointer-driven drag is still a mouse drag as far as the browser is
+    // concerned, so without this the label highlights blue while you move it.
+    // The rename field is exempt — selecting there is the whole point.
+    render(<MainTabs />);
+    for (const tab of screen.getAllByRole("tab")) {
+      expect(tab.className).toContain("select-none");
+    }
+
+    fireEvent.doubleClick(screen.getAllByRole("tab")[1]);
+    expect(screen.getByLabelText("Rename tab").className).toContain("select-text");
+  });
+
+  it("shows the tab itself under the cursor while dragging", () => {
+    // A dimmed source tab and a thin line do not read as "I am holding this
+    // tab" — the dragged copy is what makes the gesture legible.
+    render(<MainTabs />);
+    const tabs = laidOut();
+    expect(screen.queryByTestId("tab-drag-ghost")).toBeNull();
+
+    pointer(tabs[2], "pointerdown", 250);
+    pointer(tabs[2], "pointermove", 120);
+
+    const ghost = screen.getByTestId("tab-drag-ghost");
+    expect(ghost).toHaveTextContent("shell (bash)");
+    expect(ghost).toHaveTextContent("▣");
+
+    pointer(tabs[2], "pointerup", 120);
+    expect(screen.queryByTestId("tab-drag-ghost")).toBeNull();
+  });
+
+  it("carries the project name when a home tab is dragged", () => {
+    render(<MainTabs />);
+    const tabs = laidOut();
+
+    pointer(tabs[0], "pointerdown", 50);
+    pointer(tabs[0], "pointermove", 250);
+
+    expect(screen.getByTestId("tab-drag-ghost")).toHaveTextContent("api-server");
+    expect(screen.getByTestId("tab-drag-ghost")).toHaveTextContent("⌂");
+  });
+
+  it("drops the dragged copy when the drag is abandoned", () => {
+    render(<MainTabs />);
+    const tabs = laidOut();
+
+    pointer(tabs[2], "pointerdown", 250);
+    pointer(tabs[2], "pointermove", 10);
+    fireEvent.keyDown(window, { key: "Escape" });
+
+    expect(screen.queryByTestId("tab-drag-ghost")).toBeNull();
+  });
+
+  it("shows the drop marker only while a drag is under way", () => {
+    render(<MainTabs />);
+    const tabs = laidOut();
+    expect(screen.queryByTestId("tab-drop-marker")).toBeNull();
+
+    pointer(tabs[2], "pointerdown", 250);
+    pointer(tabs[2], "pointermove", 10);
+    expect(screen.getByTestId("tab-drop-marker")).toBeInTheDocument();
+
+    pointer(tabs[2], "pointerup", 10);
+    expect(screen.queryByTestId("tab-drop-marker")).toBeNull();
+  });
+
+  it("abandons the drag on Escape, leaving the order alone", () => {
+    render(<MainTabs />);
+    const tabs = laidOut();
+
+    pointer(tabs[2], "pointerdown", 250);
+    pointer(tabs[2], "pointermove", 10);
+    fireEvent.keyDown(window, { key: "Escape" });
+
+    expect(screen.queryByTestId("tab-drop-marker")).toBeNull();
+    pointer(tabs[2], "pointerup", 10);
+    expect(order()).toEqual([HOME, S1, S2]);
+  });
+
+  it("treats a press that barely moves as a click, not a drag", () => {
+    render(<MainTabs />);
+    const tabs = laidOut();
+
+    // Two pixels of tremble, under the threshold.
+    pointer(tabs[2], "pointerdown", 250);
+    pointer(tabs[2], "pointermove", 252);
+    pointer(tabs[2], "pointerup", 252);
+    fireEvent.click(tabs[2]);
+
+    expect(order()).toEqual([HOME, S1, S2]);
+    expect(useAppState.getState().activeTabKey).toBe(S2);
+  });
+
+  it("does not select the tab it just dropped", () => {
+    render(<MainTabs />);
+    const tabs = laidOut();
+
+    dragTab(tabs[2], 250, 10);
+    // The browser fires a click after the pointerup that ended the drag.
+    fireEvent.click(tabs[2]);
+
+    expect(order()).toEqual([S2, HOME, S1]);
+    expect(useAppState.getState().activeTabKey).toBe(HOME);
+  });
+
+  it("ignores a press that starts on the close button", () => {
+    render(<MainTabs />);
+    const tabs = laidOut();
+    const close = screen.getByRole("button", { name: "Close shell (bash)" });
+
+    fireEvent(close, new MouseEvent("pointerdown", { bubbles: true, clientX: 290, button: 0 }));
+    pointer(tabs[2], "pointermove", 10);
+
+    expect(screen.queryByTestId("tab-drop-marker")).toBeNull();
+    expect(order()).toEqual([HOME, S1, S2]);
+  });
+
+  it("does not drag a tab that is being renamed — that drag selects text", () => {
+    render(<MainTabs />);
+    const tabs = laidOut();
+    fireEvent.doubleClick(tabs[1]);
+    expect(screen.getByLabelText("Rename tab")).toBeInTheDocument();
+
+    dragTab(screen.getAllByRole("tab")[1], 150, 10);
+
+    expect(order()).toEqual([HOME, S1, S2]);
+  });
+
+  it("carries no drag payload that another element could receive", () => {
+    // An HTML5 drag would put the tab key in a DataTransfer, and releasing over
+    // any text field in the app would type `term:…` into it. Pointer events
+    // have nothing to hand over, and the tabs are not draggable at all.
+    render(<MainTabs />);
+    for (const tab of screen.getAllByRole("tab")) {
+      expect(tab).not.toHaveAttribute("draggable", "true");
+    }
+  });
+});

app/src/components/layout/MainTabs.tsx

@@ -0,0 +1,535 @@
+import { Fragment, useEffect, useRef, useState } from "react";
+import { useShallow } from "zustand/react/shallow";
+import { useTerminal } from "../../hooks/useTerminal";
+import { useProjects } from "../../hooks/useProjects";
+import {
+  useAppState,
+  isHomeTab,
+  tabKeyId,
+  terminalTabKey,
+} from "../../store/appState";
+import { effectivePermissionMode } from "../projects/PermissionModeControl";
+import { ProjectStatusIndicator } from "../ui/StatusIndicator";
+import { sessionDisplayName } from "../../lib/sessionName";
+import type { PermissionMode } from "../../lib/types";
+
+interface ContextMenuState {
+  sessionId: string;
+  x: number;
+  y: number;
+}
+
+/** Pixels of horizontal travel before a press becomes a drag rather than a click. */
+const DRAG_THRESHOLD = 4;
+
+const MODE_BADGE: Record<PermissionMode, { text: string; className: string }> = {
+  plan: { text: "plan", className: "bg-[var(--bg-tertiary)] text-[var(--text-secondary)]" },
+  default: { text: "ask", className: "bg-[var(--bg-tertiary)] text-[var(--text-secondary)]" },
+  acceptEdits: { text: "edits", className: "bg-[var(--accent-muted)] text-[var(--accent)]" },
+  bypass: { text: "bypass", className: "bg-[var(--warning-muted)] text-[var(--warning)]" },
+};
+
+/**
+ * One strip for both main-area tab kinds: Project Home views (⌂) and
+ * terminals (▣).
+ *
+ * Tabs are draggable, on pointer events rather than HTML5 drag-and-drop — see
+ * `pointerProps` for why neither of the two obvious alternatives works.
+ * `Ctrl+Shift+←/→` does the same thing without a mouse.
+ */
+export default function MainTabs() {
+  const { sessions, close } = useTerminal();
+  const { projects, update } = useProjects();
+  const { tabOrder, activeTabKey, setActiveTabKey, closeHomeTab, moveTab } = useAppState(
+    useShallow((s) => ({
+      tabOrder: s.tabOrder,
+      activeTabKey: s.activeTabKey,
+      setActiveTabKey: s.setActiveTabKey,
+      closeHomeTab: s.closeHomeTab,
+      moveTab: s.moveTab,
+    })),
+  );
+  const [menu, setMenu] = useState<ContextMenuState | null>(null);
+  const [renamingId, setRenamingId] = useState<string | null>(null);
+  const [renameDraft, setRenameDraft] = useState("");
+  const renameInputRef = useRef<HTMLInputElement>(null);
+  /** The tab being dragged, and the slot it would drop into. */
+  const [dragKey, setDragKey] = useState<string | null>(null);
+  const [dropIndex, setDropIndex] = useState<number | null>(null);
+  /** Where the dragged tab is drawn, and how it looked when the drag started. */
+  const [ghost, setGhost] = useState<{ x: number; y: number; label: string; icon: string } | null>(
+    null,
+  );
+  const stripRef = useRef<HTMLDivElement>(null);
+  /** A press that has not yet moved far enough to be a drag. */
+  const pending = useRef<{
+    key: string;
+    startX: number;
+    dragging: boolean;
+    offsetX: number;
+    width: number;
+    height: number;
+    top: number;
+  } | null>(null);
+  const suppressClick = useRef(false);
+
+  useEffect(() => {
+    if (!menu) return;
+    const dismiss = () => setMenu(null);
+    window.addEventListener("click", dismiss);
+    window.addEventListener("scroll", dismiss, true);
+    return () => {
+      window.removeEventListener("click", dismiss);
+      window.removeEventListener("scroll", dismiss, true);
+    };
+  }, [menu]);
+
+  useEffect(() => {
+    if (renamingId) {
+      renameInputRef.current?.focus();
+      renameInputRef.current?.select();
+    }
+  }, [renamingId]);
+
+  // Escape abandons a drag — the one affordance a pointer-event drag has to
+  // supply for itself, since the OS is not running this one.
+  useEffect(() => {
+    if (!dragKey) return;
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== "Escape") return;
+      pending.current = null;
+      setDragKey(null);
+      setDropIndex(null);
+      setGhost(null);
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [dragKey]);
+
+  if (tabOrder.length === 0) {
+    return (
+      <div className="px-3 text-xs text-[var(--text-secondary)] leading-10">
+        No open tabs — select a project to open its home view.
+      </div>
+    );
+  }
+
+  const getCustomName = (projectId: string, sessionId: string): string | null => {
+    const project = projects.find((p) => p.id === projectId);
+    return project?.renamed_session_names?.[sessionId] ?? null;
+  };
+
+  const startRename = (sessionId: string) => {
+    const session = sessions.find((s) => s.id === sessionId);
+    if (!session) return;
+    const current =
+      getCustomName(session.projectId, sessionId) ??
+      session.sessionName ??
+      session.projectName;
+    setRenameDraft(current);
+    setRenamingId(sessionId);
+    setMenu(null);
+  };
+
+  const commitRename = async (sessionId: string) => {
+    const session = sessions.find((s) => s.id === sessionId);
+    if (!session) {
+      setRenamingId(null);
+      return;
+    }
+    const project = projects.find((p) => p.id === session.projectId);
+    if (!project) {
+      setRenamingId(null);
+      return;
+    }
+    const trimmed = renameDraft.trim();
+    const map = { ...(project.renamed_session_names ?? {}) };
+    if (trimmed) {
+      map[sessionId] = trimmed;
+    } else {
+      delete map[sessionId];
+    }
+    try {
+      await update({ ...project, renamed_session_names: map });
+    } catch (err) {
+      console.error("Failed to rename terminal tab:", err);
+    } finally {
+      setRenamingId(null);
+    }
+  };
+
+  const clearCustomName = async (sessionId: string) => {
+    const session = sessions.find((s) => s.id === sessionId);
+    if (!session) return;
+    const project = projects.find((p) => p.id === session.projectId);
+    if (!project) return;
+    const map = { ...(project.renamed_session_names ?? {}) };
+    if (!(sessionId in map)) {
+      setMenu(null);
+      return;
+    }
+    delete map[sessionId];
+    try {
+      await update({ ...project, renamed_session_names: map });
+    } catch (err) {
+      console.error("Failed to reset terminal tab name:", err);
+    } finally {
+      setMenu(null);
+    }
+  };
+
+  const tabClass = (active: boolean, dragging: boolean) =>
+    `flex items-center gap-1.5 pl-3 pr-1.5 h-full text-xs cursor-pointer select-none border-r border-[var(--border-color)] transition-colors ${
+      active
+        ? "bg-[var(--bg-primary)] text-[var(--text-primary)]"
+        : "text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
+    }${dragging ? " opacity-40" : ""}`;
+
+  /**
+   * What a tab reads as, for the dragged copy. Same sources the tab itself
+   * uses — a ghost showing a different name from the tab it came from would be
+   * worse than no ghost.
+   */
+  const tabLabel = (key: string): string => {
+    if (isHomeTab(key)) {
+      return projects.find((p) => p.id === tabKeyId(key))?.name ?? "";
+    }
+    const session = sessions.find((s) => s.id === tabKeyId(key));
+    if (!session) return "";
+    return sessionDisplayName(
+      session,
+      projects.find((p) => p.id === session.projectId),
+    );
+  };
+
+  const endDrag = () => {
+    pending.current = null;
+    setDragKey(null);
+    setDropIndex(null);
+    setGhost(null);
+  };
+
+  /**
+   * Which slot the pointer is currently over, as an insertion index into
+   * `tabOrder`.
+   *
+   * Measured from the tabs actually on screen rather than from the event's
+   * target, so the answer is the same whatever the pointer happens to be over —
+   * including the drop marker itself, and including a `tabOrder` entry whose
+   * session has already gone and which therefore renders nothing.
+   */
+  const dropIndexAt = (clientX: number): number => {
+    const strip = stripRef.current;
+    if (!strip) return tabOrder.length;
+    for (const el of strip.querySelectorAll<HTMLElement>("[data-tab-index]")) {
+      const rect = el.getBoundingClientRect();
+      if (clientX < rect.left + rect.width / 2) return Number(el.dataset.tabIndex);
+    }
+    return tabOrder.length;
+  };
+
+  /**
+   * Dragging is done with pointer events, not HTML5 drag-and-drop.
+   *
+   * Two reasons, both load-bearing. Tauri's `dragDropEnabled` — which the
+   * terminal needs left on, because only the native drag-drop event carries
+   * dropped *file paths* — blocks HTML5 drag inside the webview on Windows, so
+   * an HTML5 implementation is simply dead there. And an HTML5 drag carries a
+   * `DataTransfer`: released over any text field in the app, the default
+   * handler types the payload into it.
+   */
+  const pointerProps = (key: string, renaming: boolean) => ({
+    onPointerDown: (e: React.PointerEvent<HTMLDivElement>) => {
+      // Left button only, never from the close button, and never while the
+      // rename input is up — that drag is a text selection.
+      if (e.button !== 0 || renaming) return;
+      if ((e.target as HTMLElement).closest("button, input")) return;
+      const rect = e.currentTarget.getBoundingClientRect();
+      pending.current = {
+        key,
+        startX: e.clientX,
+        dragging: false,
+        // Where inside the tab the pointer grabbed it, so the ghost sits under
+        // the cursor exactly where the real tab was — the thing that makes a
+        // drag feel like moving an object rather than nudging a setting.
+        offsetX: e.clientX - rect.left,
+        width: rect.width,
+        height: rect.height,
+        top: rect.top,
+      };
+      e.currentTarget.setPointerCapture?.(e.pointerId);
+    },
+    onPointerMove: (e: React.PointerEvent<HTMLDivElement>) => {
+      const drag = pending.current;
+      if (!drag) return;
+      // A few pixels of slop, so a click that trembles stays a click.
+      if (!drag.dragging && Math.abs(e.clientX - drag.startX) < DRAG_THRESHOLD) return;
+      drag.dragging = true;
+      setDragKey(drag.key);
+      setDropIndex(dropIndexAt(e.clientX));
+      setGhost({
+        x: e.clientX - drag.offsetX,
+        y: drag.top,
+        label: tabLabel(drag.key),
+        icon: isHomeTab(drag.key) ? "⌂" : "▣",
+      });
+    },
+    onPointerUp: (e: React.PointerEvent<HTMLDivElement>) => {
+      const drag = pending.current;
+      e.currentTarget.releasePointerCapture?.(e.pointerId);
+      if (!drag?.dragging) {
+        pending.current = null;
+        return; // a plain click: leave it to `onClick` to select the tab
+      }
+      const to = dropIndexAt(e.clientX);
+      const from = tabOrder.indexOf(drag.key);
+      // `to` is a slot in the strip as it looks *now*; `moveTab` places the tab
+      // after pulling it out, so every slot past its own shifts down one.
+      if (from !== -1) moveTab(drag.key, to > from ? to - 1 : to);
+      // The click that follows this pointerup is the drag's, not a selection.
+      suppressClick.current = true;
+      endDrag();
+    },
+    onPointerCancel: endDrag,
+  });
+
+  /** A drag in progress swallows the click it ends with. */
+  const activateTab = (key: string) => {
+    if (suppressClick.current) {
+      suppressClick.current = false;
+      return;
+    }
+    setActiveTabKey(key);
+  };
+
+  const dropMarker = (
+    <div
+      aria-hidden="true"
+      data-testid="tab-drop-marker"
+      className="w-0.5 -mx-px h-full bg-[var(--accent)] flex-shrink-0 pointer-events-none"
+    />
+  );
+
+  const renderTab = (key: string, index: number) => {
+    const active = activeTabKey === key;
+
+    if (isHomeTab(key)) {
+      const projectId = tabKeyId(key);
+      const project = projects.find((p) => p.id === projectId);
+      if (!project) return null;
+      return (
+        <div
+          role="tab"
+          aria-selected={active}
+          tabIndex={0}
+          data-tab-index={index}
+          onClick={() => activateTab(key)}
+          onKeyDown={(e) => {
+            if (e.key === "Enter" || e.key === " ") {
+              e.preventDefault();
+              setActiveTabKey(key);
+            }
+          }}
+          {...pointerProps(key, false)}
+          className={tabClass(active, dragKey === key)}
+        >
+          <span aria-hidden="true" className="text-[var(--text-secondary)]">⌂</span>
+          <span className="truncate max-w-[160px]" title={`${project.name} — project home`}>
+            {project.name}
+          </span>
+          <ProjectStatusIndicator status={project.status} iconOnly />
+          <button
+            type="button"
+            onClick={(e) => {
+              e.stopPropagation();
+              closeHomeTab(projectId);
+            }}
+            aria-label={`Close ${project.name} home tab`}
+            title="Close tab"
+            className="w-6 h-6 flex items-center justify-center rounded-[var(--radius-control)] text-[var(--text-secondary)] hover:text-[var(--error)] hover:bg-[var(--bg-tertiary)] transition-colors"
+          >
+            <span aria-hidden="true">×</span>
+          </button>
+        </div>
+      );
+    }
+
+    const sessionId = tabKeyId(key);
+    const session = sessions.find((s) => s.id === sessionId);
+    if (!session) return null;
+    const project = projects.find((p) => p.id === session.projectId);
+    const displayLabel = sessionDisplayName(session, project);
+    const isRenaming = renamingId === session.id;
+    const badge = project ? MODE_BADGE[effectivePermissionMode(project)] : null;
+
+    return (
+      <div
+        role="tab"
+        aria-selected={active}
+        tabIndex={0}
+        data-tab-index={index}
+        onClick={() => activateTab(terminalTabKey(session.id))}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            setActiveTabKey(terminalTabKey(session.id));
+          }
+        }}
+        onContextMenu={(e) => {
+          e.preventDefault();
+          setMenu({ sessionId: session.id, x: e.clientX, y: e.clientY });
+        }}
+        onDoubleClick={() => startRename(session.id)}
+        {...pointerProps(key, isRenaming)}
+        className={tabClass(active, dragKey === key)}
+      >
+        <span aria-hidden="true" className="text-[var(--text-secondary)]">▣</span>
+        {isRenaming ? (
+          <input
+            ref={renameInputRef}
+            value={renameDraft}
+            aria-label="Rename tab"
+            onChange={(e) => setRenameDraft(e.target.value)}
+            onClick={(e) => e.stopPropagation()}
+            onBlur={() => commitRename(session.id)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter") (e.target as HTMLInputElement).blur();
+              if (e.key === "Escape") setRenamingId(null);
+            }}
+            className="max-w-[180px] px-1 py-0 select-text bg-[var(--bg-primary)] border border-[var(--accent)] rounded-[var(--radius-control)] text-xs text-[var(--text-primary)]"
+          />
+        ) : (
+          <span className="truncate max-w-[180px]" title={displayLabel}>
+            {displayLabel}
+          </span>
+        )}
+        {badge && (
+          <span
+            className={`px-1 py-0.5 rounded-[4px] text-[10px] leading-none font-medium ${badge.className}`}
+            title={`Permission mode: ${badge.text}`}
+          >
+            {badge.text}
+          </span>
+        )}
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation();
+            close(session.id);
+          }}
+          aria-label={`Close ${displayLabel}`}
+          title="Close terminal"
+          className="w-6 h-6 flex items-center justify-center rounded-[var(--radius-control)] text-[var(--text-secondary)] hover:text-[var(--error)] hover:bg-[var(--bg-tertiary)] transition-colors"
+        >
+          <span aria-hidden="true">×</span>
+        </button>
+      </div>
+    );
+  };
+
+  // The marker goes before the first tab that is *actually on screen* at or
+  // past the drop slot. Addressing it by raw index would lose it whenever a
+  // `tabOrder` entry renders nothing — the window between a session ending and
+  // the store dropping its key — leaving the drag with no visible target.
+  let markerPending = dragKey !== null && dropIndex !== null;
+
+  return (
+    <div ref={stripRef} className="flex items-center h-full" role="tablist" aria-label="Open tabs">
+      {tabOrder.map((key, index) => {
+        const tab = renderTab(key, index);
+        if (!tab) return null;
+        const marker = markerPending && index >= (dropIndex ?? 0);
+        if (marker) markerPending = false;
+        return (
+          <Fragment key={key}>
+            {marker && dropMarker}
+            {tab}
+          </Fragment>
+        );
+      })}
+
+      {/* The empty run after the last tab is a drop target too — it is where
+          the hand naturally goes to say "put it at the end". */}
+      <div className="flex-1 self-stretch">{markerPending && dropMarker}</div>
+
+      {ghost && (
+        // A copy of the tab, following the pointer. Without it the only
+        // feedback is a dimmed source and a thin line, which reads as "some
+        // setting changed" rather than "I am holding this tab".
+        <div
+          aria-hidden="true"
+          data-testid="tab-drag-ghost"
+          className="fixed z-50 flex items-center gap-1.5 px-3 h-8 text-xs rounded-[var(--radius-control)] bg-[var(--bg-primary)] text-[var(--text-primary)] border border-[var(--accent)] pointer-events-none select-none"
+          style={{
+            left: ghost.x,
+            top: ghost.y,
+            boxShadow: "var(--shadow-overlay)",
+            opacity: 0.9,
+          }}
+        >
+          <span className="text-[var(--text-secondary)]">{ghost.icon}</span>
+          <span className="truncate max-w-[180px]">{ghost.label}</span>
+        </div>
+      )}
+
+      {menu && (() => {
+        const session = sessions.find((s) => s.id === menu.sessionId);
+        const hasCustom = session
+          ? !!getCustomName(session.projectId, menu.sessionId)
+          : false;
+        return (
+          <div
+            role="menu"
+            className="fixed z-50 min-w-[160px] py-1 bg-[var(--bg-overlay)] border border-[var(--border-color)] rounded-[var(--radius-panel)] text-xs"
+            style={{ top: menu.y, left: menu.x, boxShadow: "var(--shadow-overlay)" }}
+            onClick={(e) => e.stopPropagation()}
+          >
+            <button
+              type="button"
+              role="menuitem"
+              className="w-full text-left px-3 py-1.5 text-[var(--text-primary)] hover:bg-[var(--bg-tertiary)] transition-colors"
+              onClick={() => startRename(menu.sessionId)}
+            >
+              Rename tab
+            </button>
+            {hasCustom && (
+              <button
+                type="button"
+                role="menuitem"
+                className="w-full text-left px-3 py-1.5 text-[var(--text-secondary)] hover:bg-[var(--bg-tertiary)] transition-colors"
+                onClick={() => clearCustomName(menu.sessionId)}
+              >
+                Reset name
+              </button>
+            )}
+            {session && (
+              <button
+                type="button"
+                role="menuitem"
+                className="w-full text-left px-3 py-1.5 text-[var(--text-primary)] hover:bg-[var(--bg-tertiary)] transition-colors"
+                onClick={() => {
+                  useAppState.getState().openProjectHome(session.projectId);
+                  setMenu(null);
+                }}
+              >
+                Open project home
+              </button>
+            )}
+            <div className="border-t border-[var(--border-color)] my-1" />
+            <button
+              type="button"
+              role="menuitem"
+              className="w-full text-left px-3 py-1.5 text-[var(--error)] hover:bg-[var(--bg-tertiary)] transition-colors"
+              onClick={() => {
+                close(menu.sessionId);
+                setMenu(null);
+              }}
+            >
+              Close tab
+            </button>
+          </div>
+        );
+      })()}
+    </div>
+  );
+}

app/src/components/layout/NotesDock.test.tsx

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import NotesDock from "./NotesDock";
+import type { Project, TerminalSession } from "../../lib/types";
+
+vi.mock("../notes/NotesDockPanel", () => ({
+  default: ({ projectId }: { projectId: string }) => (
+    <div data-testid="panel">{`panel:${projectId}`}</div>
+  ),
+}));
+
+let state: Record<string, unknown> = {};
+vi.mock("../../store/appState", () => ({
+  useAppState: Object.assign(
+    (selector: (s: unknown) => unknown) => selector(state),
+    { getState: () => state },
+  ),
+  isHomeTab: (k: string) => k.startsWith("home:"),
+  isTerminalTab: (k: string) => k.startsWith("term:"),
+  tabKeyId: (k: string) => k.slice(k.indexOf(":") + 1),
+  // The mocked store module still needs to supply the width constants the
+  // dock imports from it for the separator's aria-value attributes.
+  NOTES_DOCK_MIN_WIDTH: 260,
+  NOTES_DOCK_MAX_WIDTH: 720,
+}));
+
+const session: TerminalSession = {
+  id: "s1",
+  projectId: "p9",
+  projectName: "api",
+  sessionType: "claude",
+  sessionName: null,
+};
+
+beforeEach(() => {
+  state = {
+    notesDockOpen: true,
+    setNotesDockOpen: vi.fn(),
+    toggleNotesDock: vi.fn(),
+    notesDockWidth: 352,
+    setNotesDockWidth: vi.fn(),
+    activeTabKey: null,
+    sessions: [session],
+    projects: [{ id: "p9", name: "api" } as unknown as Project],
+  };
+});
+
+describe("NotesDock", () => {
+  it("renders nothing when closed", () => {
+    state.notesDockOpen = false;
+    const { container } = render(<NotesDock />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("follows a project home tab", () => {
+    state.activeTabKey = "home:p1";
+    render(<NotesDock />);
+    expect(screen.getByTestId("panel")).toHaveTextContent("panel:p1");
+  });
+
+  it("follows the project of the active terminal tab", () => {
+    // The dock exists to be visible while the agent runs, so a terminal tab
+    // must resolve to its project, not to nothing.
+    state.activeTabKey = "term:s1";
+    render(<NotesDock />);
+    expect(screen.getByTestId("panel")).toHaveTextContent("panel:p9");
+  });
+
+  it("explains itself when no project is active", () => {
+    state.activeTabKey = null;
+    render(<NotesDock />);
+    expect(screen.queryByTestId("panel")).not.toBeInTheDocument();
+    expect(screen.getByText(/open a project/i)).toBeInTheDocument();
+  });
+
+  it("shows nothing for a terminal whose session has gone", () => {
+    state.activeTabKey = "term:vanished";
+    render(<NotesDock />);
+    expect(screen.queryByTestId("panel")).not.toBeInTheDocument();
+  });
+
+  it("renders at the stored width", () => {
+    state.activeTabKey = "home:p1";
+    state.notesDockWidth = 420;
+    render(<NotesDock />);
+    expect(screen.getByLabelText("Notes")).toHaveStyle({ width: "420px" });
+  });
+
+  it("has a keyboard-reachable resize handle", () => {
+    // Drag is a mouse gesture; a separator that only responds to pointer
+    // events is unusable without one.
+    state.activeTabKey = "home:p1";
+    render(<NotesDock />);
+    const handle = screen.getByRole("separator", { name: /resize notes/i });
+    fireEvent.keyDown(handle, { key: "ArrowLeft" });
+    expect(state.setNotesDockWidth).toHaveBeenCalled();
+  });
+
+  it("widens on ArrowLeft and narrows on ArrowRight, by the exact step", () => {
+    // The dock sits on the right edge, so dragging or pressing left grows it
+    // and right shrinks it. Asserting only "was called" would pass even if
+    // the branches were swapped or the sign inverted.
+    state.activeTabKey = "home:p1";
+    render(<NotesDock />);
+    const handle = screen.getByRole("separator", { name: /resize notes/i });
+
+    fireEvent.keyDown(handle, { key: "ArrowLeft" });
+    expect(state.setNotesDockWidth).toHaveBeenLastCalledWith(368);
+
+    fireEvent.keyDown(handle, { key: "ArrowRight" });
+    expect(state.setNotesDockWidth).toHaveBeenLastCalledWith(336);
+  });
+});

app/src/components/layout/NotesDock.tsx

@@ -0,0 +1,128 @@
+import { useShallow } from "zustand/react/shallow";
+import {
+  useAppState,
+  isHomeTab,
+  isTerminalTab,
+  tabKeyId,
+  NOTES_DOCK_MIN_WIDTH,
+  NOTES_DOCK_MAX_WIDTH,
+} from "../../store/appState";
+import NotesDockPanel from "../notes/NotesDockPanel";
+import Button from "../ui/Button";
+
+/**
+ * Notes beside whatever is on screen.
+ *
+ * Project Home and Terminal are sibling top-level tabs, so notes living only
+ * in a sub-tab would be hidden exactly when the agent is running — which is
+ * when a note is worth sending. The dock is the answer to that.
+ *
+ * **It takes space from inside the window and never resizes it.** Growing the
+ * OS window was tried and rejected on evidence: honoured under XWayland,
+ * silently corrupting under native Wayland, where `outer_position()` returns a
+ * confident `Ok(0,0)` for a window that is somewhere else. See the design doc,
+ * §6.1. Narrowing the terminal instead costs nothing — `TerminalView`'s
+ * ResizeObserver already reflows xterm and resizes the container PTY.
+ */
+export default function NotesDock() {
+  const {
+    notesDockOpen,
+    setNotesDockOpen,
+    notesDockWidth,
+    setNotesDockWidth,
+    activeTabKey,
+    sessions,
+  } = useAppState(
+    useShallow((s) => ({
+      notesDockOpen: s.notesDockOpen,
+      setNotesDockOpen: s.setNotesDockOpen,
+      notesDockWidth: s.notesDockWidth,
+      setNotesDockWidth: s.setNotesDockWidth,
+      activeTabKey: s.activeTabKey,
+      sessions: s.sessions,
+    })),
+  );
+
+  // Dragging the separator. Pointer capture rather than window listeners, so
+  // the drag survives the pointer crossing the terminal — which swallows
+  // events — and ends correctly if the button is released outside the window.
+  const onPointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
+    e.preventDefault();
+    const handle = e.currentTarget;
+    handle.setPointerCapture(e.pointerId);
+    const startX = e.clientX;
+    const startWidth = notesDockWidth;
+    // The dock is on the right, so dragging left widens it.
+    const onMove = (move: PointerEvent) =>
+      setNotesDockWidth(startWidth + (startX - move.clientX));
+    const onUp = () => {
+      handle.releasePointerCapture(e.pointerId);
+      handle.removeEventListener("pointermove", onMove);
+      handle.removeEventListener("pointerup", onUp);
+    };
+    handle.addEventListener("pointermove", onMove);
+    handle.addEventListener("pointerup", onUp);
+  };
+
+  const onHandleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
+    const step = e.shiftKey ? 64 : 16;
+    if (e.key === "ArrowLeft") {
+      e.preventDefault();
+      setNotesDockWidth(notesDockWidth + step);
+    } else if (e.key === "ArrowRight") {
+      e.preventDefault();
+      setNotesDockWidth(notesDockWidth - step);
+    }
+  };
+
+  if (!notesDockOpen) return null;
+
+  // Follow whatever is in front: a home tab is its own project, a terminal tab
+  // is the project it belongs to.
+  let projectId: string | null = null;
+  if (activeTabKey && isHomeTab(activeTabKey)) {
+    projectId = tabKeyId(activeTabKey);
+  } else if (activeTabKey && isTerminalTab(activeTabKey)) {
+    projectId =
+      sessions.find((s) => s.id === tabKeyId(activeTabKey))?.projectId ?? null;
+  }
+
+  return (
+    <aside
+      aria-label="Notes"
+      style={{ width: `${notesDockWidth}px` }}
+      className="relative flex-shrink-0 flex flex-col min-h-0 bg-[var(--bg-secondary)] border border-[var(--border-color)] rounded-[var(--radius-panel)] overflow-hidden"
+    >
+      {/* Separator, not decoration: it carries a role and arrow keys, because
+          a resize that only answers to a drag is unavailable to anyone not
+          using a mouse. */}
+      <div
+        role="separator"
+        aria-label="Resize notes panel"
+        aria-orientation="vertical"
+        aria-valuenow={notesDockWidth}
+        aria-valuemin={NOTES_DOCK_MIN_WIDTH}
+        aria-valuemax={NOTES_DOCK_MAX_WIDTH}
+        tabIndex={0}
+        onPointerDown={onPointerDown}
+        onKeyDown={onHandleKeyDown}
+        className="absolute left-0 top-0 h-full w-1.5 cursor-col-resize hover:bg-[var(--accent-muted)] transition-colors"
+      />
+      <div className="flex items-center justify-between gap-2 px-3 h-9 flex-shrink-0 border-b border-[var(--border-color)]">
+        <h2 className="text-[13px] font-semibold text-[var(--text-primary)]">Notes</h2>
+        <Button variant="ghost" onClick={() => setNotesDockOpen(false)} aria-label="Close notes">
+          Close
+        </Button>
+      </div>
+      <div className="flex-1 min-h-0">
+        {projectId ? (
+          <NotesDockPanel projectId={projectId} />
+        ) : (
+          <p className="p-4 text-[13px] text-[var(--text-secondary)]">
+            Open a project or a terminal to see its notes.
+          </p>
+        )}
+      </div>
+    </aside>
+  );
+}

app/src/components/layout/Sidebar.test.tsx

@@ -8,6 +8,9 @@ vi.mock("../../store/appState", () => ({
     selector({
       sidebarView: "projects",
       setSidebarView: vi.fn(),
+      sidebarCollapsed: false,
+      setSidebarCollapsed: vi.fn(),
+      toggleSidebarCollapsed: vi.fn(),
     })
   ),
 }));
@@ -19,9 +22,6 @@ vi.mock("../projects/ProjectList", () => ({
 vi.mock("../settings/SettingsPanel", () => ({
   default: () => <div data-testid="settings-panel">SettingsPanel</div>,
 }));
-vi.mock("../mcp/McpPanel", () => ({
-  default: () => <div data-testid="mcp-panel">McpPanel</div>,
-}));
 
 describe("Sidebar", () => {
   beforeEach(() => {
@@ -34,6 +34,12 @@ describe("Sidebar", () => {
     expect(screen.getByText("Settings")).toBeInTheDocument();
   });
 
+  it("renders the project list, not a settings form, in the projects view", () => {
+    render(<Sidebar />);
+    expect(screen.getByTestId("project-list")).toBeInTheDocument();
+    expect(screen.queryByTestId("settings-panel")).not.toBeInTheDocument();
+  });
+
   it("content area has min-w-0 to prevent flex overflow", () => {
     const { container } = render(<Sidebar />);
     const contentArea = container.querySelector(".overflow-y-auto");

app/src/components/layout/Sidebar.tsx

@@ -1,15 +1,87 @@
+import type { ReactNode } from "react";
 import { useShallow } from "zustand/react/shallow";
 import { useAppState } from "../../store/appState";
 import ProjectList from "../projects/ProjectList";
-import McpPanel from "../mcp/McpPanel";
 import SettingsPanel from "../settings/SettingsPanel";
 
+type SidebarView = "projects" | "settings";
+
+const RAIL_ICONS: { view: SidebarView; label: string; icon: ReactNode }[] = [
+  {
+    view: "projects",
+    label: "Projects",
+    icon: (
+      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+        <path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V7z" />
+      </svg>
+    ),
+  },
+  {
+    view: "settings",
+    label: "Settings",
+    icon: (
+      <svg className="w-5 h-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+        <circle cx="12" cy="12" r="3" />
+        <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-4 0v-.09a1.65 1.65 0 0 0-1-1.51 1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1 0-4h.09a1.65 1.65 0 0 0 1.51-1 1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z" />
+      </svg>
+    ),
+  },
+];
+
 export default function Sidebar() {
-  const { sidebarView, setSidebarView } = useAppState(
-    useShallow(s => ({ sidebarView: s.sidebarView, setSidebarView: s.setSidebarView }))
+  const { sidebarView, setSidebarView, sidebarCollapsed, setSidebarCollapsed, toggleSidebarCollapsed } = useAppState(
+    useShallow(s => ({
+      sidebarView: s.sidebarView,
+      setSidebarView: s.setSidebarView,
+      sidebarCollapsed: s.sidebarCollapsed,
+      setSidebarCollapsed: s.setSidebarCollapsed,
+      toggleSidebarCollapsed: s.toggleSidebarCollapsed,
+    }))
   );
 
-  const tabCls = (view: typeof sidebarView) =>
+  if (sidebarCollapsed) {
+    const railBtn = (view: SidebarView, label: string, icon: ReactNode) => {
+      const active = sidebarView === view;
+      return (
+        <button
+          key={view}
+          onClick={() => {
+            setSidebarView(view);
+            setSidebarCollapsed(false);
+          }}
+          title={label}
+          aria-label={label}
+          className={`flex items-center justify-center h-10 w-full transition-colors ${
+            active
+              ? "text-[var(--accent)]"
+              : "text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
+          }`}
+        >
+          {icon}
+        </button>
+      );
+    };
+
+    return (
+      <div className="flex flex-col h-full w-12 bg-[var(--bg-secondary)] border border-[var(--border-color)] rounded-[var(--radius-panel)] overflow-hidden">
+        <button
+          onClick={toggleSidebarCollapsed}
+          title="Expand sidebar"
+          aria-label="Expand sidebar"
+          className="flex items-center justify-center h-10 border-b border-[var(--border-color)] text-[var(--text-secondary)] hover:text-[var(--text-primary)] transition-colors"
+        >
+          <svg className="w-4 h-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <polyline points="9 18 15 12 9 6" />
+          </svg>
+        </button>
+        <div className="flex flex-col py-1">
+          {RAIL_ICONS.map(({ view, label, icon }) => railBtn(view, label, icon))}
+        </div>
+      </div>
+    );
+  }
+
+  const tabCls = (view: SidebarView) =>
     `flex-1 px-3 py-2 text-sm font-medium transition-colors ${
       sidebarView === view
         ? "text-[var(--accent)] border-b-2 border-[var(--accent)]"
@@ -17,29 +89,30 @@ export default function Sidebar() {
     }`;
 
   return (
-    <div className="flex flex-col h-full w-[25%] min-w-56 max-w-80 bg-[var(--bg-secondary)] border border-[var(--border-color)] rounded-lg overflow-hidden">
+    <div className="flex flex-col h-full w-[25%] min-w-56 max-w-80 bg-[var(--bg-secondary)] border border-[var(--border-color)] rounded-[var(--radius-panel)] overflow-hidden">
       {/* Nav tabs */}
       <div className="flex border-b border-[var(--border-color)]">
         <button onClick={() => setSidebarView("projects")} className={tabCls("projects")}>
           Projects
         </button>
-        <button onClick={() => setSidebarView("mcp")} className={tabCls("mcp")}>
-          MCP <span className="text-[0.6rem] px-1 py-0.5 rounded bg-yellow-500/20 text-yellow-400 ml-0.5">Beta</span>
-        </button>
         <button onClick={() => setSidebarView("settings")} className={tabCls("settings")}>
           Settings
         </button>
+        <button
+          onClick={toggleSidebarCollapsed}
+          title="Collapse sidebar"
+          aria-label="Collapse sidebar"
+          className="px-2 text-[var(--text-secondary)] hover:text-[var(--text-primary)] transition-colors"
+        >
+          <svg className="w-4 h-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <polyline points="15 18 9 12 15 6" />
+          </svg>
+        </button>
       </div>
 
       {/* Content */}
       <div className="flex-1 overflow-y-auto overflow-x-hidden p-1 min-w-0">
-        {sidebarView === "projects" ? (
-          <ProjectList />
-        ) : sidebarView === "mcp" ? (
-          <McpPanel />
-        ) : (
-          <SettingsPanel />
-        )}
+        {sidebarView === "projects" ? <ProjectList /> : <SettingsPanel />}
       </div>
     </div>
   );