test(aws): live lifecycle checks Joined from the completion output and NotJoined after removal

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

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

@@ -0,0 +1,832 @@
+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. Its `test` job runs vitest and
+# `cargo test` too, so a push that breaks either suite fails here as well.
+# Previews are not code-signed (releases are, in build-app.yml): see the
+# comment on the Windows job's "Build Tauri app" step.
+# build-app.yml used to do the build-check 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:
+  # The ephemeral Proxmox runners (eph-pve3-*) ship needrestart, which after
+  # any apt-get install stops at an interactive "Daemons using outdated
+  # libraries" prompt and hangs the job until it times out. `sudo` resets the
+  # environment, so the apt-get calls below also pass these via `sudo env`;
+  # here they reach the NodeSource setup script through `sudo -E`.
+  #
+  # SUSPEND skips needrestart entirely. Mode `a` (restart automatically) is not
+  # safe: on a host-mode runner it restarted act-runner.service mid-job and
+  # killed the job. Mode `l` (list only) is a fallback for a needrestart that
+  # ignores SUSPEND; it never prompts and never restarts anything.
+  NEEDRESTART_SUSPEND: "1"
+  NEEDRESTART_MODE: l
+  DEBIAN_FRONTEND: noninteractive
+  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"
+      # The app embeds the agent's sources for its local image build, and the
+      # agent's own tests run in the `test` job below.
+      - "container/triple-c-agent/**"
+  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}"
+
+  # The test suites. Before this job CI ran neither: every check below lived on
+  # a developer's machine. The one that matters most is the app-command ACL
+  # census — `cargo test` is what re-checks the committed capability files and
+  # `gen/schemas/acl-manifests.json` against `generate_handler!`, and vitest's
+  # `capabilities.test.ts` is what keeps each window's code to the wrappers its
+  # capability grants. A command left ungranted builds fine and only fails at
+  # runtime ("not allowed by ACL"), so these tests are the merge-time guard.
+  #
+  # Independent of the release: no `needs`, so it runs alongside the three
+  # platform builds rather than in front of them, and a red test fails the PR
+  # check without holding up a preview someone may want to try anyway.
+  #
+  # Setup mirrors build-linux on purpose — the same Node, the same apt set
+  # (`cargo test` compiles the whole Tauri crate, so it needs WebKitGTK like
+  # a real build) and `npm ci` from the lockfile for the reasons given there.
+  test:
+    runs-on: ubuntu-latest
+    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 env NEEDRESTART_SUSPEND=1 NEEDRESTART_MODE=l DEBIAN_FRONTEND=noninteractive apt-get install -y nodejs
+            hash -r
+          fi
+          node --version
+          npm --version
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: |
+          sudo env NEEDRESTART_SUSPEND=1 NEEDRESTART_MODE=l DEBIAN_FRONTEND=noninteractive apt-get update
+          sudo env NEEDRESTART_SUSPEND=1 NEEDRESTART_MODE=l DEBIAN_FRONTEND=noninteractive apt-get install -y \
+            libgtk-3-dev \
+            libwebkit2gtk-4.1-dev \
+            gstreamer1.0-plugins-base \
+            gstreamer1.0-plugins-good \
+            gstreamer1.0-pipewire \
+            gstreamer1.0-pulseaudio \
+            libayatana-appindicator3-dev \
+            librsvg2-dev \
+            libsoup-3.0-dev \
+            libssl-dev \
+            libxdo-dev \
+            pkg-config \
+            build-essential \
+            curl
+
+      - 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: npm ci
+
+      # `npm run build` is `tsc && vite build`: the type check, and the
+      # `dist/` that `tauri::generate_context!` needs to exist before the Rust
+      # crate — and so `cargo test` — will compile at all.
+      - name: Type-check and build the frontend
+        working-directory: ./app
+        run: npm run build
+
+      - name: Frontend tests (vitest)
+        working-directory: ./app
+        run: npx vitest run
+
+      # `--locked`: test against the committed Cargo.lock, never a re-resolved
+      # one, for the same reason the frontend uses `npm ci`.
+      - name: Backend tests (cargo test)
+        working-directory: ./app/src-tauri
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          cargo test --locked
+
+      # The in-container agent is its own crate (container/triple-c-agent): a
+      # real server on loopback, exercised over HTTP/WebSocket as the current
+      # user. Its root-only test is #[ignore]d. The Docker-parity test against
+      # a real container lives in the app (host::agent::live_tests, ignored).
+      - name: Agent tests (cargo test)
+        working-directory: ./container/triple-c-agent
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          cargo test --locked
+
+  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 env NEEDRESTART_SUSPEND=1 NEEDRESTART_MODE=l DEBIAN_FRONTEND=noninteractive 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 env NEEDRESTART_SUSPEND=1 NEEDRESTART_MODE=l DEBIAN_FRONTEND=noninteractive apt-get update
+          sudo env NEEDRESTART_SUSPEND=1 NEEDRESTART_MODE=l DEBIAN_FRONTEND=noninteractive apt-get install -y \
+            libgtk-3-dev \
+            libwebkit2gtk-4.1-dev \
+            gstreamer1.0-plugins-base \
+            gstreamer1.0-plugins-good \
+            gstreamer1.0-pipewire \
+            gstreamer1.0-pulseaudio \
+            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: |
+          # `npm ci` — from the lockfile, never resolving afresh.
+          #
+          # This used to be `rm -rf node_modules package-lock.json && npm
+          # install`, which deleted the lockfile "to ensure correct
+          # platform-specific bindings" (2d4fce9). That made every build
+          # re-resolve the whole tree against the registry, so a dependency
+          # publishing a new version could break CI with no change to this
+          # repo — and one did. Deleting the lockfile then hit a null
+          # dereference in npm 10.9.8's arborist peer-set resolver:
+          #
+          #   npm error Cannot read properties of null (reading 'edgesOut')
+          #     at #loadPeerSet (.../build-ideal-tree.js:1289:38)
+          #
+          # reached through vite → @vitejs/devtools → @vitejs/devtools-vitest
+          # → vitest@* → @vitest/browser-playwright → jsdom@* → canvas.
+          # Reproduced exactly by removing the lockfile locally on the same
+          # Node 22.23.2 the runner installs.
+          #
+          # The binding worry is obsolete: the committed lockfile records 25
+          # rollup platform variants, and `npm ci` on Linux installs precisely
+          # rollup-linux-x64-{gnu,musl} and @esbuild/linux-x64. Verified, along
+          # with a clean tsc, a successful build and 752 passing tests from the
+          # resulting tree.
+          #
+          # Do not "fix" a future dependency error by deleting the lockfile
+          # again. If `npm ci` refuses, package.json and the lockfile have
+          # genuinely diverged, and the fix is to commit an updated lockfile.
+          npm ci
+
+      - 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"
+          # AppImage only: the .deb and .rpm were dropped in favour of the one
+          # artifact that runs everywhere, and building them is pure cost.
+          # Left as "all" in tauri.conf.json so macOS and Windows are unaffected.
+          npx tauri build --bundles appimage
+
+      # linuxdeploy bundles a libwayland-client.so.0 that shadows the host's
+      # and breaks Mesa's EGL on systems newer than the build runner, so the
+      # window comes up blank. It has to come from the host; see the script
+      # header for the evidence and the trade.
+      - name: Finalize the AppImage
+        run: bash scripts/finalize-appimage.sh app/src-tauri/target/release/bundle/appimage
+
+      - name: Collect artifacts
+        run: |
+          mkdir -p artifacts
+          cp app/src-tauri/target/release/bundle/appimage/*.AppImage 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: |
+          # `npm ci` here too, so all three platforms install identically and
+          # none of them can re-resolve the tree mid-release. Windows already
+          # did. See the Linux job for what a fresh resolution cost us.
+          npm ci
+
+      - 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.23.4/node-v22.23.4-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%"
+          rem Pinned to the @tauri-apps/cli version in app/package-lock.json, which
+          rem the Linux and macOS jobs run, and kept identical to build-app.yml so
+          rem a preview is built by the same bundler as the release it previews.
+          cargo install tauri-cli --version "=2.11.0" --locked
+
+      - 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
+        # Previews are not code-signed: signing is metered, previews are built
+        # on every PR push, and a PR's workflow runs the PR's own code - so the
+        # signing secrets stay out of this workflow entirely. Releases are
+        # signed in build-app.yml.
+        #
+        # beforeBuildCommand is blanked through --config because the frontend
+        # was built in the step above. Not TAURI_CONFIG: the v2 CLI never
+        # reads that variable, and the inline one this step used to set was a
+        # no-op.
+        env:
+          # 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 --config "{\"build\":{\"beforeBuildCommand\":\"\"}}"
+
+      - 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

@@ -1,21 +1,37 @@
 name: Build App
 
+# **Releases are cut by hand.** This runs only when someone dispatches it
+# (Actions -> Build App -> Run workflow). Merging to main does not release:
+# main can carry finished-but-dormant work (a feature landing in phases) and
+# nothing reaches users until a release is cut on purpose.
+#
+# Dispatched on `main` it releases: Gitea and GitHub releases, the version tag,
+# the Linux update channel, and then the container images' `:latest` (see the
+# create-tag job). Dispatched on any other branch it is a dry run that builds,
+# signs and verifies all three platforms and publishes nothing, which is how to
+# exercise Windows signing before a merge. Every publishing step and job
+# carries the same `if:` (dispatch event *and* ref main); keep them in step if
+# one is ever added.
 on:
-  push:
-    branches: [main]
-    paths:
-      - "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: build-app-preview.yml carries the PR
+# check (tests plus all three platforms), and this workflow is releases only.
+
 env:
+  # The ephemeral Proxmox runners (eph-pve3-*) ship needrestart, which after
+  # any apt-get install stops at an interactive "Daemons using outdated
+  # libraries" prompt and hangs the job until it times out. `sudo` resets the
+  # environment, so the apt-get calls below also pass these via `sudo env`;
+  # here they reach the NodeSource setup script through `sudo -E`.
+  #
+  # SUSPEND skips needrestart entirely. Mode `a` (restart automatically) is not
+  # safe: on a host-mode runner it restarted act-runner.service mid-job and
+  # killed the job. Mode `l` (list only) is a fallback for a needrestart that
+  # ignores SUSPEND; it never prompts and never restarts anything.
+  NEEDRESTART_SUSPEND: "1"
+  NEEDRESTART_MODE: l
+  DEBIAN_FRONTEND: noninteractive
   GITEA_URL: ${{ gitea.server_url }}
   REPO: ${{ gitea.repository }}
 
@@ -39,16 +55,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}"
@@ -78,7 +133,7 @@ jobs:
           fi
           if [ "$NEED_INSTALL" = true ]; then
             curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
-            sudo apt-get install -y nodejs
+            sudo env NEEDRESTART_SUSPEND=1 NEEDRESTART_MODE=l DEBIAN_FRONTEND=noninteractive apt-get install -y nodejs
             hash -r
           fi
           echo "Node.js at: $(which node)"
@@ -100,10 +155,14 @@ jobs:
 
       - name: Install system dependencies
         run: |
-          sudo apt-get update
-          sudo apt-get install -y \
+          sudo env NEEDRESTART_SUSPEND=1 NEEDRESTART_MODE=l DEBIAN_FRONTEND=noninteractive apt-get update
+          sudo env NEEDRESTART_SUSPEND=1 NEEDRESTART_MODE=l DEBIAN_FRONTEND=noninteractive apt-get install -y \
             libgtk-3-dev \
             libwebkit2gtk-4.1-dev \
+            gstreamer1.0-plugins-base \
+            gstreamer1.0-plugins-good \
+            gstreamer1.0-pipewire \
+            gstreamer1.0-pulseaudio \
             libayatana-appindicator3-dev \
             librsvg2-dev \
             libsoup-3.0-dev \
@@ -133,8 +192,34 @@ jobs:
       - name: Install frontend dependencies
         working-directory: ./app
         run: |
-          rm -rf node_modules package-lock.json
-          npm install
+          # `npm ci` — from the lockfile, never resolving afresh.
+          #
+          # This used to be `rm -rf node_modules package-lock.json && npm
+          # install`, which deleted the lockfile "to ensure correct
+          # platform-specific bindings" (2d4fce9). That made every build
+          # re-resolve the whole tree against the registry, so a dependency
+          # publishing a new version could break CI with no change to this
+          # repo — and one did. Deleting the lockfile then hit a null
+          # dereference in npm 10.9.8's arborist peer-set resolver:
+          #
+          #   npm error Cannot read properties of null (reading 'edgesOut')
+          #     at #loadPeerSet (.../build-ideal-tree.js:1289:38)
+          #
+          # reached through vite → @vitejs/devtools → @vitejs/devtools-vitest
+          # → vitest@* → @vitest/browser-playwright → jsdom@* → canvas.
+          # Reproduced exactly by removing the lockfile locally on the same
+          # Node 22.23.2 the runner installs.
+          #
+          # The binding worry is obsolete: the committed lockfile records 25
+          # rollup platform variants, and `npm ci` on Linux installs precisely
+          # rollup-linux-x64-{gnu,musl} and @esbuild/linux-x64. Verified, along
+          # with a clean tsc, a successful build and 752 passing tests from the
+          # resulting tree.
+          #
+          # Do not "fix" a future dependency error by deleting the lockfile
+          # again. If `npm ci` refuses, package.json and the lockfile have
+          # genuinely diverged, and the fix is to commit an updated lockfile.
+          npm ci
 
       - name: Install Tauri CLI
         working-directory: ./app
@@ -146,42 +231,126 @@ jobs:
         working-directory: ./app
         run: |
           export PATH="$HOME/.cargo/bin:$PATH"
-          npx tauri build
+          # AppImage only: the .deb and .rpm were dropped in favour of the one
+          # artifact that runs everywhere, and building them is pure cost.
+          # Left as "all" in tauri.conf.json so macOS and Windows are unaffected.
+          npx tauri build --bundles appimage
+
+      # linuxdeploy bundles a libwayland-client.so.0 that shadows the host's
+      # and breaks Mesa's EGL on systems newer than the build runner, so the
+      # window comes up blank. It has to come from the host; see the script
+      # header for the evidence and the trade.
+      - name: Finalize the AppImage
+        run: bash scripts/finalize-appimage.sh app/src-tauri/target/release/bundle/appimage
 
       - name: Collect artifacts
         run: |
           mkdir -p artifacts
+          # The versioned AppImage only. The update channel's copy lives in
+          # bundle/appimage/update-channel/ precisely so this glob cannot pick
+          # it up and publish an 80 MB duplicate under a second name.
           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/
 
+          # A green job that published nothing is the worst outcome available:
+          # the release exists, carries no AppImage, and nobody is told. The
+          # `|| true` above is there so a missing bundle does not mask the real
+          # error, which makes this check the thing that catches it.
+          shopt -s nullglob
+          collected=(artifacts/*)
+          if [ ${#collected[@]} -eq 0 ]; then
+            echo "No artifacts collected — the bundler produced nothing." >&2
+            exit 1
+          fi
+
       - name: Upload to Gitea release
-        if: gitea.event_name == 'push'
+        if: gitea.event_name == 'workflow_dispatch' && gitea.ref == 'refs/heads/main'
         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}\", \"target_commitish\": \"${{ gitea.sha }}\", \"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}" \
               "${GITEA_URL}/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets?name=${filename}"
           done
 
+      # The fixed tag every installed AppImage checks for updates. Separate
+      # from the versioned release above because the updater's URL must never
+      # move, and `releases/latest` does.
+      - name: Publish the Linux update channel
+        if: gitea.event_name == 'workflow_dispatch' && gitea.ref == 'refs/heads/main'
+        env:
+          GH_PAT: ${{ secrets.GH_PAT }}
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          GITEA_SHA: ${{ gitea.sha }}
+        run: |
+          bash scripts/publish-update-channel.sh \
+            app/src-tauri/target/release/bundle/appimage/update-channel
+
   build-macos:
     runs-on: macos-latest
     needs: [compute-version]
@@ -237,8 +406,10 @@ jobs:
       - name: Install frontend dependencies
         working-directory: ./app
         run: |
-          rm -rf node_modules
-          npm install
+          # `npm ci` here too, so all three platforms install identically and
+          # none of them can re-resolve the tree mid-release. Windows already
+          # did. See the Linux job for what a fresh resolution cost us.
+          npm ci
 
       - name: Install Tauri CLI
         working-directory: ./app
@@ -260,25 +431,76 @@ jobs:
           ls -la artifacts/
 
       - name: Upload to Gitea release
-        if: gitea.event_name == 'push'
+        if: gitea.event_name == 'workflow_dispatch' && gitea.ref == 'refs/heads/main'
         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}\", \"target_commitish\": \"${{ gitea.sha }}\", \"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 +528,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 && (
@@ -322,7 +615,7 @@ jobs:
           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"
+            curl -fSL -o node-install.msi "https://nodejs.org/dist/v22.23.4/node-v22.23.4-x64.msi"
             msiexec /i node-install.msi /quiet /norestart
             del node-install.msi
           )
@@ -338,7 +631,11 @@ jobs:
       - name: Install Tauri CLI via cargo
         run: |
           set "PATH=%USERPROFILE%\.cargo\bin;C:\Program Files\nodejs;%PATH%"
-          cargo install tauri-cli --version "^2"
+          rem Pinned to the @tauri-apps/cli version in app/package-lock.json, which
+          rem the Linux and macOS jobs run: the Windows code-signing path (sign
+          rem command, NSIS uninstaller signing) was verified against it, and "^2"
+          rem would change it underneath the pipeline on any Tauri release.
+          cargo install tauri-cli --version "=2.11.0" --locked
 
       - name: Fix npm platform detection
         run: |
@@ -359,43 +656,132 @@ jobs:
           set "PATH=%USERPROFILE%\.cargo\bin;C:\Program Files\nodejs;%PATH%"
           npm run build
 
+      # Releases are signed with Azure Artifact Signing (scripts/windows-*.ps1).
+      # The setup fetches the signing client and a job-local .NET runtime, and
+      # writes the Tauri config holding the sign command, which "Build Tauri
+      # app" passes with --config. A missing secret fails here, before the build.
+      - name: Prepare code signing
+        env:
+          AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+          AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+          AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
+          ARTIFACT_SIGNING_ENDPOINT: ${{ secrets.ARTIFACT_SIGNING_ENDPOINT }}
+          ARTIFACT_SIGNING_ACCOUNT_NAME: ${{ secrets.ARTIFACT_SIGNING_ACCOUNT_NAME }}
+          ARTIFACT_SIGNING_PROFILE_NAME: ${{ secrets.ARTIFACT_SIGNING_PROFILE_NAME }}
+        run: powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass -File scripts\windows-signing-setup.ps1
+
       - name: Build Tauri app
         working-directory: ./app
+        # The sign command comes in through --config, from the file "Prepare
+        # code signing" wrote. Not TAURI_CONFIG: the v2 CLI never reads that
+        # variable (the inline one this step used to set was a no-op), and
+        # "Verify signatures" is what caught it.
         env:
-          TAURI_CONFIG: "{\"build\":{\"beforeBuildCommand\":\"\"}}"
+          # Read by the signing dlib itself, never passed on a command line.
+          AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+          AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+          AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
         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 --config "%TRIPLE_C_TAURI_SIGN_CONFIG%"
+
+      - name: Verify signatures
+        run: >-
+          powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass
+          -File scripts\windows-verify-signatures.ps1
+          app\src-tauri\target\release\bundle\msi\*.msi
+          app\src-tauri\target\release\bundle\nsis\*.exe
+
+      # Tauri reports a failed sign command as just "failed to run powershell";
+      # windows-sign.ps1 keeps its own transcript, signtool /debug included.
+      - name: Show signing output
+        if: failure()
+        run: if exist .code-signing\sign-output.log type .code-signing\sign-output.log
 
       - 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'
+        if: gitea.event_name == 'workflow_dispatch' && gitea.ref == 'refs/heads/main'
+        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
+                target_commitish = $env:COMMIT_SHA
+                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
     needs: [compute-version, build-linux, build-macos, build-windows]
-    if: gitea.event_name == 'push'
+    if: gitea.event_name == 'workflow_dispatch' && gitea.ref == 'refs/heads/main'
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -405,24 +791,56 @@ jobs:
       - name: Create version tag
         env:
           TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          VERSION: ${{ needs.compute-version.outputs.version }}
+          SHA: ${{ gitea.sha }}
         run: |
-          VERSION="${{ needs.compute-version.outputs.version }}"
+          set -euo pipefail
           TAG="v${VERSION}"
-          echo "Creating tag ${TAG}..."
 
-          # Create annotated tag via Gitea API
-          curl -s -X POST \
-            -H "Authorization: token ${TOKEN}" \
-            -H "Content-Type: application/json" \
-            -d "{\"tag_name\": \"${TAG}\", \"target\": \"${{ gitea.sha }}\", \"message\": \"Release ${TAG}\"}" \
-            "${GITEA_URL}/api/v1/repos/${REPO}/tags" || echo "Tag may already exist (created by release)"
+          # Usually already there: creating the Linux release creates its tag,
+          # at this commit (`target_commitish`). Create it if not, then insist
+          # it points here, because the container step below builds whatever
+          # the tag names.
+          if ! curl -fsS -o tag.json -H "Authorization: token ${TOKEN}" \
+              "${GITEA_URL}/api/v1/repos/${REPO}/tags/${TAG}"; then
+            echo "Creating tag ${TAG} at ${SHA}"
+            curl -fsS -X POST \
+              -H "Authorization: token ${TOKEN}" \
+              -H "Content-Type: application/json" \
+              -d "{\"tag_name\": \"${TAG}\", \"target\": \"${SHA}\", \"message\": \"Release ${TAG}\"}" \
+              "${GITEA_URL}/api/v1/repos/${REPO}/tags" > tag.json
+          fi
+          TAGGED=$(python3 -c "import json; print(json.load(open('tag.json'))['commit']['sha'])")
+          if [ "${TAGGED}" != "${SHA}" ]; then
+            echo "Tag ${TAG} points at ${TAGGED}, not the released commit ${SHA}" >&2
+            exit 1
+          fi
+          echo "Tag ${TAG} is at ${SHA}"
 
-          echo "Tag ${TAG} created successfully"
+      # The containers' `:latest` is what every installed app pulls, so it
+      # moves with an app release and at no other time (pushes to main only
+      # publish `:edge` and `:<sha>`). Each container workflow builds the tag
+      # it is handed, not main, so a merge landing mid-release cannot ride
+      # along.
+      - name: Release the container images
+        env:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          VERSION: ${{ needs.compute-version.outputs.version }}
+        run: |
+          set -euo pipefail
+          for WORKFLOW in build.yml build-stt.yml; do
+            echo "Dispatching ${WORKFLOW} for v${VERSION}"
+            curl -fsS -X POST \
+              -H "Authorization: token ${TOKEN}" \
+              -H "Content-Type: application/json" \
+              -d "{\"ref\": \"main\", \"inputs\": {\"release_tag\": \"v${VERSION}\"}}" \
+              "${GITEA_URL}/api/v1/repos/${REPO}/actions/workflows/${WORKFLOW}/dispatches"
+          done
 
   sync-to-github:
     runs-on: ubuntu-latest
     needs: [compute-version, build-linux, build-macos, build-windows]
-    if: gitea.event_name == 'push'
+    if: gitea.event_name == 'workflow_dispatch' && gitea.ref == 'refs/heads/main'
     env:
       GH_PAT: ${{ secrets.GH_PAT }}
       GITHUB_REPO: shadowdao/triple-c

.gitea/workflows/build-stt.yml

@@ -11,6 +11,12 @@ on:
     paths:
       - "stt-container/**"
       - ".gitea/workflows/build-stt.yml"
+  # Dispatched by build-app.yml when a release is cut, with the release's tag.
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: "Release tag to build as :latest (default: the newest vX.Y.Z)"
+        required: false
 
 env:
   REGISTRY: repo.anhonesthost.net
@@ -22,6 +28,65 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # **`:latest` is what installed apps pull, so only a release moves it.**
+      # A push to main publishes `:edge` and `:<sha>` (for testing a merged
+      # image by hand); a pull request publishes nothing. The weekly rebuild
+      # and a release dispatch build a release tag and publish it as `:latest`
+      # — the tag, not main, so unreleased container changes never reach users.
+      - name: Pick the source and the tags to publish
+        id: src
+        env:
+          EVENT: ${{ gitea.event_name }}
+          RELEASE_TAG: ${{ gitea.event.inputs.release_tag }}
+          REF: ${{ gitea.ref }}
+        run: |
+          set -euo pipefail
+          case "$EVENT" in
+            push|pull_request)
+              CHANNEL=edge
+              ;;
+            schedule|workflow_dispatch)
+              CHANNEL=latest
+              # `:latest` reaches every user, so it only comes from main: a
+              # dispatch from another branch, or a tag cut on one, is refused.
+              # An older release tag is allowed on purpose — that is a rollback.
+              if [ "$REF" != "refs/heads/main" ]; then
+                echo "Refusing to publish :latest from $REF (only main)" >&2
+                exit 1
+              fi
+              git fetch --tags --force
+              git fetch origin main
+              if [ -z "${RELEASE_TAG:-}" ]; then
+                RELEASE_TAG=$(git tag -l 'v*' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
+              fi
+              if ! echo "$RELEASE_TAG" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
+                echo "Not a release tag: '$RELEASE_TAG'" >&2
+                exit 1
+              fi
+              if ! git merge-base --is-ancestor "refs/tags/$RELEASE_TAG" FETCH_HEAD; then
+                echo "$RELEASE_TAG is not on main; refusing to publish it as :latest" >&2
+                exit 1
+              fi
+              git checkout --detach "refs/tags/$RELEASE_TAG"
+              echo "Building release $RELEASE_TAG"
+              ;;
+            *)
+              echo "Unexpected event $EVENT" >&2
+              exit 1
+              ;;
+          esac
+          SHA=$(git rev-parse HEAD)
+          {
+            echo "tags<<EOF"
+            echo "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:$CHANNEL"
+            echo "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:$SHA"
+            echo "ghcr.io/shadowdao/triple-c-stt:$CHANNEL"
+            echo "ghcr.io/shadowdao/triple-c-stt:$SHA"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
@@ -49,11 +114,14 @@ jobs:
           context: ./stt-container
           file: ./stt-container/Dockerfile
           platforms: linux/amd64,linux/arm64
-          push: ${{ gitea.event_name == 'push' }}
-          tags: |
-            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
-            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ gitea.sha }}
-            ghcr.io/shadowdao/triple-c-stt:latest
-            ghcr.io/shadowdao/triple-c-stt:${{ gitea.sha }}
+          # A pull_request run only validates; see the tag step for what each
+          # other event publishes.
+          push: ${{ gitea.event_name != 'pull_request' }}
+          tags: ${{ steps.src.outputs.tags }}
+          # The gha cache is served by the runner that picks the job up, and
+          # is unreachable from the job on some of ours (the home box's
+          # firewalled per-job bridge; ephemeral runners). Import failures
+          # only warn, but an export failure fails the build unless told not
+          # to -- the same setting build.yml already carries.
           cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-to: type=gha,mode=max,ignore-error=true

.gitea/workflows/build.yml

@@ -11,6 +11,17 @@ on:
     paths:
       - "container/**"
       - ".gitea/workflows/build.yml"
+  # Weekly rebuild with no commit needed, so OS security fixes published since
+  # the last push reach the image (see APT_REFRESH in container/Dockerfile).
+  # It rebuilds the newest *release*, not main, because it moves `:latest`.
+  schedule:
+    - cron: "17 4 * * 1"
+  # Dispatched by build-app.yml when a release is cut, with the release's tag.
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: "Release tag to build as :latest (default: the newest vX.Y.Z)"
+        required: false
 
 env:
   REGISTRY: repo.anhonesthost.net
@@ -22,12 +33,92 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # **`:latest` is what installed apps pull, so only a release moves it.**
+      # A push to main publishes `:edge` and `:<sha>` (for testing a merged
+      # image by hand); a pull request publishes nothing. The weekly rebuild
+      # and a release dispatch build a release tag and publish it as `:latest`
+      # — the tag, not main, so unreleased container changes never reach users.
+      - name: Pick the source and the tags to publish
+        id: src
+        env:
+          EVENT: ${{ gitea.event_name }}
+          RELEASE_TAG: ${{ gitea.event.inputs.release_tag }}
+          REF: ${{ gitea.ref }}
+        run: |
+          set -euo pipefail
+          case "$EVENT" in
+            push|pull_request)
+              CHANNEL=edge
+              ;;
+            schedule|workflow_dispatch)
+              CHANNEL=latest
+              # `:latest` reaches every user, so it only comes from main: a
+              # dispatch from another branch, or a tag cut on one, is refused.
+              # An older release tag is allowed on purpose — that is a rollback.
+              if [ "$REF" != "refs/heads/main" ]; then
+                echo "Refusing to publish :latest from $REF (only main)" >&2
+                exit 1
+              fi
+              git fetch --tags --force
+              git fetch origin main
+              if [ -z "${RELEASE_TAG:-}" ]; then
+                RELEASE_TAG=$(git tag -l 'v*' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
+              fi
+              if ! echo "$RELEASE_TAG" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
+                echo "Not a release tag: '$RELEASE_TAG'" >&2
+                exit 1
+              fi
+              if ! git merge-base --is-ancestor "refs/tags/$RELEASE_TAG" FETCH_HEAD; then
+                echo "$RELEASE_TAG is not on main; refusing to publish it as :latest" >&2
+                exit 1
+              fi
+              git checkout --detach "refs/tags/$RELEASE_TAG"
+              echo "Building release $RELEASE_TAG"
+              ;;
+            *)
+              echo "Unexpected event $EVENT" >&2
+              exit 1
+              ;;
+          esac
+          SHA=$(git rev-parse HEAD)
+          {
+            echo "tags<<EOF"
+            echo "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:$CHANNEL"
+            echo "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:$SHA"
+            echo "ghcr.io/shadowdao/triple-c-sandbox:$CHANNEL"
+            echo "ghcr.io/shadowdao/triple-c-sandbox:$SHA"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
+        with:
+          # Put BuildKit in the host's network namespace so it can reach
+          # act_runner's cache service.
+          #
+          # The `docker-container` driver — which the multi-arch build below
+          # requires, since the plain `docker` driver cannot do
+          # linux/amd64+linux/arm64 — runs BuildKit in its *own* container on
+          # Docker's default bridge. act_runner advertises ACTIONS_CACHE_URL as
+          # an address the *job* container can reach, and nothing teaches the
+          # BuildKit container about it: the job could reach
+          # 192.168.1.126:40649 while the container actually making the request
+          # could not, and the build died with `no route to host`.
+          #
+          # `no route to host` is EHOSTUNREACH — a firewall rejecting, not a
+          # missing route (a wrong address times out instead) — which is what a
+          # default firewalld zone does to traffic arriving from the docker
+          # bridge. Sharing the host's namespace sidesteps the question
+          # entirely: the cache address becomes local to BuildKit.
+          #
+          # No effect on runners where this already worked.
+          driver-opts: network=host
 
       - name: Login to Gitea Container Registry
         uses: docker/login-action@v3
@@ -43,17 +134,39 @@ jobs:
           username: shadowdao
           password: ${{ secrets.GH_PAT }}
 
+      # Changes once a week, which invalidates the cached `apt-get upgrade`
+      # layer (container/Dockerfile) so later security fixes are picked up.
+      - name: Compute the apt refresh stamp
+        id: apt
+        run: echo "stamp=$(date -u +%G-W%V)" >> $GITHUB_OUTPUT
+
       - name: Build and push container image
         uses: docker/build-push-action@v5
         with:
           context: ./container
           file: ./container/Dockerfile
           platforms: linux/amd64,linux/arm64
-          push: ${{ gitea.event_name == 'push' }}
-          tags: |
-            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
-            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ gitea.sha }}
-            ghcr.io/shadowdao/triple-c-sandbox:latest
-            ghcr.io/shadowdao/triple-c-sandbox:${{ gitea.sha }}
+          # A pull_request run only validates; see the tag step for what each
+          # other event publishes.
+          push: ${{ gitea.event_name != 'pull_request' }}
+          build-args: |
+            APT_REFRESH=${{ steps.apt.outputs.stamp }}
+          tags: ${{ steps.src.outputs.tags }}
+          # `ignore-error` is what stops a cache failure failing a build that
+          # already succeeded. act_runner emulates the GitHub Actions cache
+          # service on the runner host's LAN address, and the `docker-container`
+          # builder `setup-buildx-action` creates could not route to it —
+          # every layer of both arches built, then the job died on
+          # `GetCacheEntryDownloadURL: no route to host` while exporting.
+          #
+          # On a pull_request `push:` above is false, so this job pushes
+          # nothing and the cache is its only output: failing it discarded a
+          # complete, successful validation of the Dockerfile for both
+          # architectures. A cache is an optimisation and must degrade to
+          # "slow", never to "red".
+          #
+          # The import is already non-fatal — the build ran all 37 layers after
+          # warning that it could not read the cache — so only the exporter
+          # needs the flag.
           cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-to: type=gha,mode=max,ignore-error=true

.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

@@ -1,5 +1,29 @@
 node_modules/
 app/dist/
 app/src-tauri/target/
+container/triple-c-agent/target/
+# Written by build.rs (tauri-build AppManifest); gen/schemas/acl-manifests.json is the
+# tracked, reviewable form of the same information.
+app/src-tauri/permissions/autogenerated/
 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
+
+# Windows CI code signing (scripts/windows-signing-setup.ps1)
+.code-signing/
+
+# OpenTofu working state (aws/terraform/*): providers, local state, locks.
+# The modules' .terraform.lock.hcl files are committed.
+.terraform/
+*.tfstate
+*.tfstate.*
+.terraform.tfstate.lock.info

BUILDING.md

@@ -71,13 +71,29 @@ npm ci
 npx tauri build
 ```
 
+Linux ships as **AppImage only**. To match what CI produces, pass the bundle
+explicitly:
+
+```bash
+npx tauri build --bundles appimage
+```
+
+The `.deb` and `.rpm` bundles were dropped — two more artifacts to build and
+publish for an audience the AppImage already serves, and neither could
+self-update. A bare `npx tauri build` still emits them, because
+`tauri.conf.json` keeps `"targets": "all"` so that macOS and Windows are
+untouched; they are not released and not tested.
+
 Build artifacts are located in `app/src-tauri/target/release/bundle/`:
 
-| Format     | Path                          |
-|------------|-------------------------------|
-| AppImage   | `appimage/*.AppImage`         |
-| Debian pkg | `deb/*.deb`                   |
-| RPM pkg    | `rpm/*.rpm`                   |
+| Format     | Path                          | Released |
+|------------|-------------------------------|----------|
+| AppImage   | `appimage/*.AppImage`         | yes      |
+| Debian pkg | `deb/*.deb`                   | no       |
+| RPM pkg    | `rpm/*.rpm`                   | no       |
+
+`scripts/finalize-appimage.sh` post-processes the AppImage; see the Packaging
+section of `CLAUDE.md` for why both of its steps are load-bearing.
 
 ## macOS
 

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,197 @@ 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. Five 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` |
+| **Auto** | `auto` | `--permission-mode auto` |
+| **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 +237,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 +506,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, Notes toggle, 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 / Auto / 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 +634,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 *and* before every Claude session launches, 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,19 @@ 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`.
+- **The STT mic lives in the global `StatusBar`, not a per-terminal overlay.** 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.
+- **Scrolling is left to xterm, and the "Following" / "Jump to Current" controls that used to drive it are gone.** They were built for the normal buffer. Claude Code draws on the *alternate* screen, which has no scrollback, so in a Claude tab `viewportY` always equalled `baseY`, `isAtBottom` was permanently true and neither control could ever do anything — which is what made them look broken. **They did still work in `bash` tabs**, which run `bash -l` on the normal buffer; removing them is a real behaviour change there, and the justification is that xterm's native follow already covers it, not that nothing was lost. The manual `scrollToBottom()` on every write went with them — it fought that native behaviour, which follows the tail while the viewport is at the bottom and holds position while you read further up. `scrollToBottom()` remains only on activate and after a refit, and **both sample `viewportY >= baseY` before the `fit()`** so they re-anchor only a viewport that was already on the tail: the ResizeObserver fires for the Notes dock, the sidebar drag and any window resize, none of which are a reason to yank a reader to the bottom.
+- **A program that grabs the mouse and dies must be escapable without closing the tab.** A TUI sets DECSET `?1000`/`?1002`/`?1003` and, if it exits without resetting them, xterm keeps routing clicks, drags and (under `?1003`) every pointer *move* to the PTY — text selection dies and escape bytes flood the prompt. `TerminalView` reconciles a badge against `term.modes.mouseTrackingMode` **in the `term.write()` callback**: the mode only changes because the container printed a sequence, so one check per write catches every transition with no polling. Releasing writes the resets through `term.write`, **never `sendInput`** — the reset belongs to xterm's parser and must not reach the container, or a still-live TUI would simply re-grab the mouse on its next repaint. Bound to the control and to `Ctrl+Shift+X`, because the failure being recovered from is the pointer not working.
+- **The release control lives in the `StatusBar`, not over the terminal.** Mouse tracking is the *normal* steady state of every mouse-driven TUI — htop, vim, lazygit and Claude Code all set `?1000`/`?1002` — so a badge painted at `absolute top-2 right-4 z-50` would be on screen for the entire life of those programs and would swallow clicks aimed at that program's own top-right corner, silently killing its mouse with no undo. The active `TerminalView` publishes `terminalMouseCaptured` and `releaseActiveMouse` through the store instead, the same way `terminalHasSelection` and `sttToggle` already do.
+- **`macOptionClickForcesSelection: true` is set, and without it macOS has no force-select at all.** `SelectionService.shouldForceSelection` is `isMac ? altKey && macOptionClickForcesSelection : shiftKey`, and the option defaults to `false` — so the "hold Shift to select while a program holds the mouse" escape hatch is Shift everywhere else and **Option** on macOS, and existed on macOS only once this was turned on.
+- **Set store function values via object-merge, not the updater form** — `set({ fn: value })`, not `set(state => ...)` — when publishing action callbacks (like `sttToggle`) into the Zustand store.
+
 ### bollard (Docker API)
 
 **Chosen over:** Shelling out to the `docker` CLI, dockerode (Node.js), docker-api (Python)
@@ -113,7 +126,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)  │
@@ -123,7 +137,7 @@ Tauri uses a Rust backend paired with a web-based frontend rendered by the OS-na
 │                                                          │
 │  User: claude (UID/GID remapped to match host)           │
 │  Entrypoint: UID/GID remap → SSH setup → git config →   │
-│              docker socket perms → sleep infinity        │
+│              docker socket perms → root keepalive wait   │
 └──────────────────────────────────────────────────────────┘
 ```
 
@@ -150,22 +164,179 @@ 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 stays resident as root waiting on a root-owned `triple-c-keepalive` sleep — never a process the `claude` user can kill, since any `pkill sleep` a Claude session runs would otherwise stop the container.
+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 five-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` |
+| `Auto` | `--permission-mode auto` | `auto` |
+| `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
 
@@ -177,7 +348,7 @@ The entrypoint solves this by:
 3. Relocating any existing system user/group that conflicts with the target UID/GID.
 4. Fixing ownership of `/home/claude` after the change.
 
-This runs as root in the entrypoint, then the final `exec su -s /bin/bash claude -c "exec sleep infinity"` drops to the remapped user.
+This runs as root in the entrypoint. The entrypoint itself then stays running as root to keep the container alive; sessions reach the remapped `claude` user through `docker exec --user`. (Older images ended in `exec su -s /bin/bash claude -c "exec sleep infinity"`, which let any `claude` process stop the container by killing that sleep.)
 
 ### SSH Key Handling
 
@@ -195,10 +366,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 +393,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/Auto/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 +569,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 +596,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.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,28 @@
     "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": {
+    "@codemirror/commands": "^6.11.1",
+    "@codemirror/lang-css": "^6.3.1",
+    "@codemirror/lang-html": "^6.4.12",
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/lang-markdown": "^6.5.2",
+    "@codemirror/lang-python": "^6.2.1",
+    "@codemirror/lang-rust": "^6.0.2",
+    "@codemirror/lang-yaml": "^6.1.3",
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/legacy-modes": "^6.5.4",
+    "@codemirror/search": "^6.7.2",
+    "@codemirror/state": "^6.7.6",
+    "@codemirror/view": "^6.43.13",
+    "@lezer/highlight": "^1.2.3",
     "@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"] }
@@ -22,24 +21,91 @@ bollard = "0.18"
 keyring = { version = "3", features = ["apple-native", "windows-native", "linux-native"] }
 tokio = { version = "1", features = ["full"] }
 futures-util = "0.3"
+bytes = "1"
 uuid = { version = "1", features = ["v4"] }
 chrono = { version = "0.4", features = ["serde"] }
 dirs = "6"
 log = "0.4"
 fern = { version = "0.7", features = ["date-based"] }
 tar = "0.4"
+# Unpacks the pinned OpenTofu release archive (aws/tofu.rs); every platform's
+# archive is a .tar.gz. The version already in the tree.
+flate2 = "1"
 include_dir = "0.7"
 reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls", "multipart"] }
 iana-time-zone = "0.1"
 sha2 = "0.10"
 axum = { version = "0.8", features = ["ws"] }
+# Client side of triple-c-agent's two WebSocket endpoints (host/agent.rs). The
+# same version axum's `ws` already pulls in; plain ws:// only (the transport is
+# loopback or an SSM port-forward), so no TLS features.
+tokio-tungstenite = { version = "0.28", default-features = false, features = ["connect"] }
+# `PollSender`: the agent attach's stdin `AsyncWrite` over a bounded channel.
+# Already in the tree through tokio's ecosystem.
+tokio-util = "0.7"
 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"
+# WHATWG URL parsing for `url_open`'s re-validation of URLs arriving from the
+# container. Already in the tree transitively (reqwest), and the point of
+# using it rather than hand-rolling is parity with the frontend's `new URL()`.
+url = "2"
+similar = "2"
+# Marketplace repos are fetched on the host into a bare cache (spec §3).
+# Blocking client + rustls: no git binary or OpenSSL needed on the host.
+gix = { version = "0.88", default-features = false, features = ["blocking-network-client", "blocking-http-transport-reqwest-rust-tls", "credentials", "sha1"] }
+# AWS host (docs/superpowers/specs/2026-11-13-aws-ecs-host-design.md). The
+# service crates' default `rustls` feature is the *legacy* hyper 0.14 /
+# rustls 0.21 client, a second TLS stack next to the one reqwest already
+# brings; `default-https-client` is the current one, so defaults are off.
+aws-config = { version = "1.13.2", default-features = false, features = ["default-https-client", "rt-tokio", "credentials-process", "sso", "behavior-version-latest"] }
+aws-sdk-ssm = { version = "1.137.0", default-features = false, features = ["default-https-client", "rt-tokio", "behavior-version-latest"] }
+aws-sdk-ecs = { version = "1.159.0", default-features = false, features = ["default-https-client", "rt-tokio", "behavior-version-latest"] }
+aws-sdk-sts = { version = "1.126.0", default-features = false, features = ["default-https-client", "rt-tokio", "behavior-version-latest"] }
+aws-sdk-iam = { version = "1.136.0", default-features = false, features = ["default-https-client", "rt-tokio", "behavior-version-latest"] }
+aws-sdk-secretsmanager = { version = "1.128.0", default-features = false, features = ["default-https-client", "rt-tokio", "behavior-version-latest"] }
+# Named by src/aws/connection.rs: the credentials-provider trait (its profile
+# wrapper) and the profile-file set (aws-config's alias for it is deprecated).
+# Both are the versions aws-config already resolves.
+aws-credential-types = { version = "1.3.1", default-features = false }
+aws-runtime = { version = "1.10.4", default-features = false }
+# The default sleep and time source for the hand-built SdkConfig (no env/profile
+# loading); the version and feature already in the tree.
+aws-smithy-async = { version = "1.3.1", default-features = false, features = ["rt-tokio"] }
+aws-sdk-s3 = { version = "1.159.0", default-features = false, features = ["default-https-client", "rt-tokio", "behavior-version-latest"] }
+
+# aws/tofu.rs: `setsid` puts the detached OpenTofu runner in its own session,
+# and Cancel sends SIGINT to the runner process alone (never a group), which
+# forwards it to `tofu`. Liveness is the runner's `apply.lock`, not a PID.
+# Already in the tree through tokio and friends.
+[target.'cfg(unix)'.dependencies]
+libc = "0.2"
+
+# Linux only: WebKitGTK refuses getUserMedia until the embedder enables media
+# streams and answers the permission request (see src/linux_media.rs). Same
+# version tauri/wry already resolve, so this adds no second copy.
+[target.'cfg(target_os = "linux")'.dependencies]
+webkit2gtk = "2.0.2"
+
+[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"] }
+tempfile = "3"
+# Only `aws::live_tests` (ignored): it creates a throwaway environment key to
+# check that Secrets Manager and the permissions boundary see its tags.
+aws-sdk-kms = { version = "1.131.0", default-features = false, features = ["default-https-client", "rt-tokio", "behavior-version-latest"] }
+# Only `aws::tofu_modules` tests: they parse the shipped OpenTofu modules.
+hcl-rs = "0.20"
 
 [build-dependencies]
 tauri-build = { version = "2", features = [] }
+# build.rs reads capabilities/*.json to cross-check them against generate_handler!.
+serde_json = "1"
 
 [features]
 default = ["custom-protocol"]

app/src-tauri/build.rs

@@ -1,3 +1,208 @@
-fn main() {
-    tauri_build::build()
+//! Declares the Tauri `AppManifest`, so every app command is ACL-gated per window, and refuses
+//! to build unless every registered command is granted in exactly one capability file — the
+//! file whose `windows` the command's name says it belongs to. Without an app manifest, tauri
+//! 2.11 skips the ACL for app commands entirely (`webview/mod.rs:1794`), so any local window
+//! could call any command.
+//!
+//! Because the census can only vouch for what it reads, the build also stops on any capability
+//! tauri would load that the census does not: anything in `capabilities/` other than a
+//! top-level `*.json`, a `webviews`/`remote` key, `app.security.capabilities` in a tauri config
+//! or `TAURI_CONFIG`, and any hand-written file under `permissions/`.
+//!
+//! The parser and the rules live in `src/command_census.rs`, which `cargo test` also compiles,
+//! so they have unit tests. Spec: `docs/superpowers/specs/2026-09-22-app-manifest-lockdown-design.md`.
+
+#[path = "src/command_census.rs"]
+mod command_census;
+
+use std::path::Path;
+
+/// Stops the build. `what` names the check that failed, so a malformed capability file, a
+/// stray entry or a hand-written permission does not read as a grant/handler mismatch.
+fn fail(what: &str, problems: &[String], hint: &str) -> ! {
+    eprintln!();
+    eprintln!(
+        "{what} ({} problem{}):",
+        problems.len(),
+        if problems.len() == 1 { "" } else { "s" }
+    );
+    for p in problems {
+        eprintln!("  - {p}");
+    }
+    eprintln!();
+    eprintln!("{hint}");
+    eprintln!();
+    std::process::exit(1);
+}
+
+const LAYOUT_HINT: &str = "Every capability is a top-level capabilities/*.json file with a \
+    `windows` list and no `webviews` or `remote`, and no capability is declared anywhere else \
+    (tauri.conf.json, TAURI_CONFIG, subdirectories, .toml/.json5). The census in \
+    src/command_census.rs can only vouch for what it reads.";
+
+fn file_name(path: &Path) -> String {
+    path.file_name()
+        .expect("a directory entry has a file name")
+        .to_string_lossy()
+        .into_owned()
+}
+
+fn main() {
+    // tauri-build already emits rerun-if-changed for `capabilities`, `permissions` and the
+    // tauri config files, and rerun-if-env-changed for TAURI_CONFIG.
+    println!("cargo:rerun-if-changed=src/lib.rs");
+    println!("cargo:rerun-if-changed=src/command_census.rs");
+
+    let lib_rs = std::fs::read_to_string("src/lib.rs")
+        .expect("build.rs runs with CWD = src-tauri, so src/lib.rs must be readable");
+    let Some(commands) = command_census::registered_commands(&lib_rs) else {
+        fail(
+            "missing generate_handler! block",
+            &["src/lib.rs has no `generate_handler![ … ])` block to derive the AppManifest from"
+                .to_string()],
+            "build.rs derives the AppManifest from that block; see src/command_census.rs.",
+        );
+    };
+
+    check_tauri_config();
+    let files = read_capabilities();
+
+    let problems = command_census::check(&commands, &files);
+    if !problems.is_empty() {
+        fail(
+            "capabilities do not match generate_handler!",
+            &problems,
+            "Every app command needs exactly one bare `allow-<command-with-dashes>` grant: \
+             `viewer_*` commands in capabilities/file-viewer.json, everything else in \
+             capabilities/default.json. See src/command_census.rs.",
+        );
+    }
+
+    prune_permissions(&commands);
+
+    // `AppManifest::commands` takes `&'static [&'static str]` and the struct is `Copy`, so
+    // there is no owned form; leaking is fine in a process that exits right after.
+    let leaked: Vec<&'static str> = commands
+        .into_iter()
+        .map(|c| &*Box::leak(c.into_boxed_str()))
+        .collect();
+    let leaked: &'static [&'static str] = Box::leak(leaked.into_boxed_slice());
+    let attributes = tauri_build::Attributes::new()
+        .app_manifest(tauri_build::AppManifest::new().commands(leaked));
+    if let Err(error) = tauri_build::try_build(attributes) {
+        // Same shape as `tauri_build::build()`: message on stdout, then exit 1.
+        println!("{error:#}");
+        std::process::exit(1);
+    }
+}
+
+/// tauri-build writes `permissions/autogenerated/<command>.toml` for every manifest command
+/// and never deletes one, so a command removed from `lib.rs` would leave a permission a
+/// capability could still reference (and the build would pass). Delete only the stale files:
+/// tauri-build also emits `rerun-if-changed=permissions`, so regenerating everything would
+/// touch every mtime and re-run this script — and recompile the crate — on every cargo
+/// invocation. Anything else under `permissions/` is a hand-written grant the census cannot
+/// see, so it is refused — except OS/editor junk (`.DS_Store`, swap files), which tauri never
+/// loads and which is skipped (see `command_census::is_os_junk`).
+fn prune_permissions(commands: &[String]) {
+    let root = Path::new("permissions");
+    let Ok(entries) = std::fs::read_dir(root) else {
+        return;
+    };
+    for entry in entries {
+        let path = entry.expect("readable entry in permissions/").path();
+        if path.is_file() && command_census::is_os_junk(&file_name(&path)) {
+            // .DS_Store and friends: tauri never loads them, so they cannot grant anything.
+            continue;
+        }
+        if path.file_name().is_some_and(|n| n == "autogenerated") && path.is_dir() {
+            for file in std::fs::read_dir(&path).expect("readable permissions/autogenerated") {
+                let file = file.expect("readable entry").path();
+                let stem = file.file_stem().and_then(|s| s.to_str()).unwrap_or("");
+                let live = file.extension().is_some_and(|e| e == "toml")
+                    && commands.iter().any(|c| c == stem);
+                if !live {
+                    std::fs::remove_file(&file)
+                        .unwrap_or_else(|e| panic!("cannot delete stale {}: {e}", file.display()));
+                }
+            }
+        } else {
+            fail(
+                "hand-written permission",
+                &[format!(
+                    "{} is not generated by build.rs; hand-written permissions are not allowed \
+                     (every grant is a bare allow-* string in a capability file)",
+                    path.display()
+                )],
+                "permissions/ holds only build.rs's autogenerated/ directory. Delete the entry; \
+                 an app command is granted by listing allow-<command> in a capability file.",
+            );
+        }
+    }
+}
+
+/// Every capability tauri will load, read the way the census reads it — or the build stops.
+/// tauri-build loads `capabilities/**/*.{json,toml,json5}`; the census reads only top-level
+/// `*.json`, so anything else tauri could load is refused rather than granted unchecked.
+fn read_capabilities() -> Vec<command_census::CapabilityFile> {
+    let mut files = Vec::new();
+    let mut stray = Vec::new();
+    let mut invalid = Vec::new();
+    for entry in std::fs::read_dir("capabilities").expect("capabilities/ must exist") {
+        let path = entry.expect("readable entry in capabilities/").path();
+        let name = file_name(&path);
+        let is_file = path.is_file();
+        if is_file && command_census::is_os_junk(&name) {
+            continue;
+        }
+        if let Some(problem) = command_census::stray_capability_entry(&name, is_file) {
+            stray.push(problem);
+            continue;
+        }
+        let json = std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("{name}: {e}"));
+        match command_census::capability_file(&name, &json) {
+            Ok(file) => files.push(file),
+            Err(problem) => invalid.push(problem),
+        }
+    }
+    stray.sort();
+    if !stray.is_empty() {
+        fail("stray entry in capabilities/", &stray, LAYOUT_HINT);
+    }
+    invalid.sort();
+    if !invalid.is_empty() {
+        fail("invalid capability file", &invalid, LAYOUT_HINT);
+    }
+    files.sort_by(|a, b| a.name.cmp(&b.name));
+    files
+}
+
+/// tauri also takes capabilities inline from `app.security.capabilities` in any of its config
+/// files, or from the `TAURI_CONFIG` JSON that tauri-build merges over them. The census cannot
+/// see those, so they are refused; so is a config in a format it cannot read (JSON5, TOML).
+fn check_tauri_config() {
+    let mut problems = Vec::new();
+    for entry in std::fs::read_dir(".").expect("readable src-tauri/") {
+        let path = entry.expect("readable entry in src-tauri/").path();
+        let name = file_name(&path);
+        match command_census::tauri_config_file(&name) {
+            None => {}
+            Some(false) => problems.push(format!(
+                "{name}: the census reads JSON tauri configs only; a JSON5/TOML config could \
+                 declare capabilities it cannot see"
+            )),
+            Some(true) => {
+                let json =
+                    std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("{name}: {e}"));
+                problems.extend(command_census::tauri_config_problem(&name, &json));
+            }
+        }
+    }
+    if let Ok(json) = std::env::var("TAURI_CONFIG") {
+        problems.extend(command_census::tauri_config_problem("TAURI_CONFIG", &json));
+    }
+    problems.sort();
+    if !problems.is_empty() {
+        fail("capabilities declared outside capabilities/", &problems, LAYOUT_HINT);
+    }
 }

app/src-tauri/capabilities/default.json

@@ -1,33 +1,162 @@
 {
   "identifier": "default",
-  "description": "Default capabilities for Triple-C",
+  "description": "Default capabilities for Triple-C. Every entry here is an IPC command a compromised webview can call directly, so the set is an enumeration of what `app/src` actually invokes — plugin and core grants verified against tauri 2.11.0's `PLUGINS` table in tauri's own `build.rs` rather than assumed from a plugin's `default` set, app-command grants (the bare `allow-*` entries) cross-checked by this crate's `build.rs` against `generate_handler!`. `core:default` in particular is NOT used: it is an alias for `core:{path,event,window,webview,app,image,resources,menu,tray}:default`, and `core:image:default` carries `allow-from-path`, whose handler (`tauri-2.11.0/src/image/plugin.rs:41` → `src/image/mod.rs:96`) is a bare `std::fs::read(path)` with no scope mechanism of any kind. Nothing imports `@tauri-apps/api/image`, so the whole plugin is dropped rather than scoped — there is nothing to scope it with. `core:menu` and `core:tray` are dropped for the same reason (no menu, no tray icon); `core:window` and `core:path` because nothing imports them; `core:resources:allow-close` because no frontend value is a `Resource`; and `core:event`'s `allow-emit`/`allow-emit-to` because the frontend only ever *listens* — every emit in this app originates in Rust. Three notes on what is deliberately kept or accepted: (1) `core:webview:allow-internal-toggle-devtools` is not called by `app/src` at all — it is called by Tauri's own injected `toggle-devtools.js`, which binds Ctrl/Cmd+Shift+I. Both that script and the command behind it are `#[cfg(any(debug_assertions, feature = \"devtools\"))]`, so this grant is a `tauri dev` convenience that does not exist in a release bundle. (2) `opener:allow-open-url` is **gone**. It could not be narrowed by host — `TerminalView`'s `WebLinksAddon` opens links Claude printed inside the container, which are arbitrary by construction, so a host allowlist would have deleted the feature rather than bounded it — and it was carried here as an accepted residual risk: a compromised webview could make the OS open an attacker-chosen http(s) URL, an outbound channel. That risk is now closed rather than recorded. Every host-browser open in the app goes through the `open_url_external` command in `url_open.rs`, which exists because the AppImage environment leaks into a cold-launched browser on Linux (triple-c#34) and which re-validates the URL in Rust — scheme allowlist, no embedded credentials, no control characters, length cap, ASCII asserted before `execvp`. On macOS and Windows that command reaches the same plugin as before, via `OpenerExt::open_url`, whose desktop implementation calls `crate::open::open` directly and is therefore not gated by this file at all (`tauri-plugin-opener-2.5.3/src/lib.rs:60`). The plugin stays a dependency for exactly that reason; what is removed is the webview's ability to reach it without passing the Rust validation. (3) `drag:allow-start-drag` is **gone**, together with the OS drag-out it existed for. It could not be scoped — `tauri-plugin-drag` takes the item paths from the caller and has no scope mechanism, so a compromised webview could call `startDrag({ item: ['~/.ssh/id_rsa'] })` against any host path the user can read — and it was carried as an accepted residual risk for one gesture. Drag-out was held back for separate hardening (see branch `hold/disk-and-dragout`) and the plugin is no longer a dependency. Getting a file *out* of a container is either \"Back up container\" on the project's Overview tab, which archives a tree through the Docker API, or the Files tab's per-row \"Save to host…\", which copies one file; getting one *in* is a drop on the Terminal or the Files tab's \"Upload…\". None of the four touches this permission. The Files tab's two are worth separating out here, because they are the only host-path commands in the app whose dialog is opened by **Rust** rather than by the webview — `pick_save_path` and `pick_files_to_upload` in `commands/file_commands.rs` drive `tauri-plugin-dialog` from the backend, so a compromised webview can ask for a picker and nothing more: it cannot name a host path as an *input* to either command. Be precise about the limit of that claim — host paths do still travel outward in error text (`Failed to create /home/j/Documents/x.txt.triple-c-part-1a2b3c4d: Permission denied`), including canonicalized ones, which disclose symlink targets. That is accepted; the app already hands the webview the project paths. What is closed is the direction that mattered — the webview naming where bytes go. That is the shape an earlier revision of this file named as the honest one if the Files tab ever regained host I/O, and it is the shape it regained it in. The `dialog:allow-open` / `dialog:allow-save` grants below are therefore *not* what those two use; they remain for the frontend pickers in Add Project, the Config tab's workspace and access sections, the CA-certificate field and Backup. Two commands stillLine truncated
   "windows": ["main"],
   "permissions": [
-    "core:default",
-    "core:event:default",
-    "core:event:allow-emit",
     "core:event:allow-listen",
     "core:event:allow-unlisten",
-    "core:event:allow-emit-to",
-    "dialog:default",
+    "core:webview:allow-internal-toggle-devtools",
     "dialog:allow-open",
     "dialog:allow-save",
-    "dialog:allow-message",
-    "dialog:allow-ask",
-    "dialog:allow-confirm",
-    "store:default",
-    "store:allow-get",
-    "store:allow-set",
-    "store:allow-delete",
-    "store:allow-keys",
-    "store:allow-values",
-    "store:allow-entries",
-    "store:allow-length",
-    "store:allow-load",
-    "store:allow-reset",
-    "store:allow-save",
-    "store:allow-clear",
-    "opener:default",
-    "opener:allow-open-url"
+    "allow-check-docker",
+    "allow-check-image-exists",
+    "allow-build-image",
+    "allow-get-container-info",
+    "allow-list-projects",
+    "allow-add-project",
+    "allow-remove-project",
+    "allow-update-project",
+    "allow-start-project-container",
+    "allow-stop-project-container",
+    "allow-rebuild-project-container",
+    "allow-reconcile-project-statuses",
+    "allow-list-notes",
+    "allow-save-note",
+    "allow-delete-note",
+    "allow-get-container-staleness",
+    "allow-migrate-project-to-base",
+    "allow-confirm-migration",
+    "allow-rollback-migration",
+    "allow-get-migration-state",
+    "allow-set-auth-bridge-enabled",
+    "allow-get-auth-bridge-status",
+    "allow-set-browser-view-enabled",
+    "allow-get-browser-view-status",
+    "allow-check-browser-view-support",
+    "allow-install-browser-view-support",
+    "allow-install-browser-view-browser",
+    "allow-open-browser-view-popout",
+    "allow-close-browser-view-popout",
+    "allow-get-browser-view-popout-state",
+    "allow-set-browser-view-popout-always-on-top",
+    "allow-open-page-in-container-browser",
+    "allow-set-container-page-viewport",
+    "allow-get-container-page-state",
+    "allow-close-container-page",
+    "allow-set-browser-view-match-window",
+    "allow-get-browser-view-match-window",
+    "allow-acquire-claude-token",
+    "allow-submit-claude-token-code",
+    "allow-cancel-claude-token",
+    "allow-has-claude-token",
+    "allow-clear-claude-token",
+    "allow-sweep-claude-token-snapshots",
+    "allow-get-settings",
+    "allow-update-settings",
+    "allow-pull-image",
+    "allow-detect-aws-config",
+    "allow-inspect-ca-cert-path",
+    "allow-list-aws-profiles",
+    "allow-add-aws-profile-connection",
+    "allow-add-aws-keys-connection",
+    "allow-update-aws-connection",
+    "allow-remove-host-connection",
+    "allow-aws-connection-identity",
+    "allow-aws-connection-sso-login",
+    "allow-check-aws-permissions",
+    "allow-aws-policy-document",
+    "allow-detect-aws-environments",
+    "allow-deploy-aws-environment",
+    "allow-update-aws-environment",
+    "allow-repair-aws-environment",
+    "allow-destroy-incomplete-aws-environment",
+    "allow-unlock-aws-state",
+    "allow-follow-aws-deployment",
+    "allow-cancel-aws-deployment",
+    "allow-push-aws-saved-state",
+    "allow-onboard-aws-user",
+    "allow-deploy-aws-permissions-boundary",
+    "allow-save-aws-admin-bundle",
+    "allow-detect-host-timezone",
+    "allow-export-settings",
+    "allow-preview-settings-import",
+    "allow-apply-settings-import",
+    "allow-open-terminal-session",
+    "allow-terminal-input",
+    "allow-terminal-resize",
+    "allow-close-terminal-session",
+    "allow-paste-image-to-terminal",
+    "allow-upload-host-file-to-terminal",
+    "allow-start-audio-bridge",
+    "allow-send-audio-data",
+    "allow-stop-audio-bridge",
+    "allow-list-container-files",
+    "allow-download-container-backup",
+    "allow-download-container-file",
+    "allow-upload-files-to-container",
+    "allow-read-container-file",
+    "allow-rename-container-path",
+    "allow-create-container-directory",
+    "allow-open-file-viewer",
+    "allow-aws-sso-refresh",
+    "allow-get-app-version",
+    "allow-check-for-updates",
+    "allow-check-image-update",
+    "allow-get-help-content",
+    "allow-open-url-external",
+    "allow-detect-install-options",
+    "allow-run-docker-install",
+    "allow-start-web-terminal",
+    "allow-stop-web-terminal",
+    "allow-get-web-terminal-status",
+    "allow-regenerate-web-terminal-token",
+    "allow-get-stt-status",
+    "allow-start-stt",
+    "allow-stop-stt",
+    "allow-build-stt-image",
+    "allow-pull-stt-image",
+    "allow-transcribe-audio",
+    "allow-get-gateway-status",
+    "allow-start-gateway",
+    "allow-stop-gateway",
+    "allow-check-gateway-health",
+    "allow-build-gateway-image",
+    "allow-pull-gateway-image",
+    "allow-set-gateway-api-key",
+    "allow-clear-gateway-api-key",
+    "allow-get-gateway-auth-token",
+    "allow-regenerate-gateway-auth-token",
+    "allow-list-claude-sessions",
+    "allow-list-container-capabilities",
+    "allow-list-scheduled-tasks",
+    "allow-add-scheduled-task",
+    "allow-update-scheduled-task",
+    "allow-get-scheduled-task-log",
+    "allow-set-scheduled-task-enabled",
+    "allow-run-scheduled-task-now",
+    "allow-remove-scheduled-task",
+    "allow-get-scheduler-notifications",
+    "allow-clear-scheduler-notifications",
+    "allow-list-marketplace-snapshots",
+    "allow-refresh-marketplaces",
+    "allow-add-marketplace",
+    "allow-update-marketplace",
+    "allow-remove-marketplace",
+    "allow-install-marketplace-item",
+    "allow-uninstall-marketplace-item",
+    "allow-set-global-item-disabled",
+    "allow-forget-marketplace-installs",
+    "allow-list-marketplace-updates",
+    "allow-marketplace-item-diff",
+    "allow-update-marketplace-item",
+    "allow-apply-marketplace-now",
+    "allow-get-marketplace-sync-report",
+    "allow-add-marketplace-token-account",
+    "allow-add-marketplace-gh-host-account",
+    "allow-start-marketplace-gh-container-login",
+    "allow-cancel-marketplace-gh-login",
+    "allow-test-marketplace-account",
+    "allow-remove-marketplace-account",
+    "allow-marketplace-gh-host-available"
   ]
 }

app/src-tauri/capabilities/file-viewer.json

@@ -0,0 +1,16 @@
+{
+  "identifier": "file-viewer",
+  "description": "The terminal file viewer windows (`file-viewer-<n>`, opened by `open_file_viewer` on the app's own `viewer.html`). Same rules as `default.json`, including the layout checks: this file itself must stay a top-level `capabilities/*.json` with no `webviews` or `remote` key, or `build.rs` refuses the build rather than grant something the census cannot see. The five bare `allow-viewer-*` grants are the only app commands a viewer window can invoke: `build.rs` declares the AppManifest that makes tauri enforce that, and refuses any other bare grant in this file. The label gate inside `commands/file_viewer_commands.rs` is still what stops window A acting on window B's registry entry, because the ACL only decides which window may call. The rest of this file is the plugin-command surface a compromised viewer webview could reach, and it is the smallest one that lets the window work. `core:event:allow-listen`/`allow-unlisten` are for `file-viewer-goto` (Rust → this window; the viewer subscribes through `getCurrentWindow().listen`, because a bare `listen()` in *any* window receives an `emit_to`). `core:window:allow-destroy` is not optional: `getCurrentWindow().onCloseRequested` in @tauri-apps/api 2.11 makes Rust `prevent_close()` whenever a JS listener exists and then calls `destroy()` itself, so without this grant the window's X button does nothing once the unsaved-changes guard is installed. `allow-close` is deliberately absent — nothing calls it, and `destroy` is the only exit. No `set-title`/`set-focus`/`unminimize`: those are done from Rust when a second click targets an already-open file. `core:webview:allow-internal-toggle-devtools` is the same dev-only convenience `default.json` carries.",
+  "windows": ["file-viewer-*"],
+  "permissions": [
+    "core:event:allow-listen",
+    "core:event:allow-unlisten",
+    "core:window:allow-destroy",
+    "core:webview:allow-internal-toggle-devtools",
+    "allow-viewer-get-state",
+    "allow-viewer-choose-file",
+    "allow-viewer-read-file",
+    "allow-viewer-poll-file",
+    "allow-viewer-write-file"
+  ]
+}

app/src-tauri/gen/schemas/acl-manifests.json

@@ -1 +1 @@
-{"core":{"default_permission":{"identifier":"default","description":"Default core plugins set.","permissions":["core:path:default","core:event:default","core:window:default","core:webview:default","core:app:default","core:image:default","core:resources:default","core:menu:default","core:tray:default"]},"permissions":{},"permission_sets":{},"global_scope_schema":null},"core:app":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin.","permissions":["allow-version","allow-name","allow-tauri-version","allow-identifier","allow-bundle-type","allow-register-listener","allow-remove-listener"]},"permissions":{"allow-app-hide":{"identifier":"allow-app-hide","description":"Enables the app_hide command without any pre-configured scope.","commands":{"allow":["app_hide"],"deny":[]}},"allow-app-show":{"identifier":"allow-app-show","description":"Enables the app_show command without any pre-configured scope.","commands":{"allow":["app_show"],"deny":[]}},"allow-bundle-type":{"identifier":"allow-bundle-type","description":"Enables the bundle_type command without any pre-configured scope.","commands":{"allow":["bundle_type"],"deny":[]}},"allow-default-window-icon":{"identifier":"allow-default-window-icon","description":"Enables the default_window_icon command without any pre-configured scope.","commands":{"allow":["default_window_icon"],"deny":[]}},"allow-fetch-data-store-identifiers":{"identifier":"allow-fetch-data-store-identifiers","description":"Enables the fetch_data_store_identifiers command without any pre-configured scope.","commands":{"allow":["fetch_data_store_identifiers"],"deny":[]}},"allow-identifier":{"identifier":"allow-identifier","description":"Enables the identifier command without any pre-configured scope.","commands":{"allow":["identifier"],"deny":[]}},"allow-name":{"identifier":"allow-name","description":"Enables the name command without any pre-configured scope.","commands":{"allow":["name"],"deny":[]}},"allow-register-listener":{"identifier":"allow-register-listener","description":"Enables the register_listener command without any pre-configured scope.","commands":{"allow":["register_listener"],"deny":[]}},"allow-remove-data-store":{"identifier":"allow-remove-data-store","description":"Enables the remove_data_store command without any pre-configured scope.","commands":{"allow":["remove_data_store"],"deny":[]}},"allow-remove-listener":{"identifier":"allow-remove-listener","description":"Enables the remove_listener command without any pre-configured scope.","commands":{"allow":["remove_listener"],"deny":[]}},"allow-set-app-theme":{"identifier":"allow-set-app-theme","description":"Enables the set_app_theme command without any pre-configured scope.","commands":{"allow":["set_app_theme"],"deny":[]}},"allow-set-dock-visibility":{"identifier":"allow-set-dock-visibility","description":"Enables the set_dock_visibility command without any pre-configured scope.","commands":{"allow":["set_dock_visibility"],"deny":[]}},"allow-tauri-version":{"identifier":"allow-tauri-version","description":"Enables the tauri_version command without any pre-configured scope.","commands":{"allow":["tauri_version"],"deny":[]}},"allow-version":{"identifier":"allow-version","description":"Enables the version command without any pre-configured scope.","commands":{"allow":["version"],"deny":[]}},"deny-app-hide":{"identifier":"deny-app-hide","description":"Denies the app_hide command without any pre-configured scope.","commands":{"allow":[],"deny":["app_hide"]}},"deny-app-show":{"identifier":"deny-app-show","description":"Denies the app_show command without any pre-configured scope.","commands":{"allow":[],"deny":["app_show"]}},"deny-bundle-type":{"identifier":"deny-bundle-type","description":"Denies the bundle_type command without any pre-configured scope.","commands":{"allow":[],"deny":["bundle_type"]}},"deny-default-window-icon":{"identifier":"deny-default-window-icon","description":"Denies the default_window_icon command without any pre-configured scope.","commands":{"allow":[],"deny":["default_window_icon"]}},"deny-fetch-data-store-identifiers":{"identifier":"deny-fetch-data-store-identifiers","description":"Denies the fetch_data_store_identifiers command without any pre-configured scope.","commands":{"allow":[],"deny":["fetch_data_store_identifiers"]}},"deny-identifier":{"identifier":"deny-identifier","description":"Denies the identifier command without any pre-configured scope.","commands":{"allow":[],"deny":["identifier"]}},"deny-name":{"identifier":"deny-name","description":"Denies the name command without any pre-configured scope.","commands":{"allow":[],"deny":["name"]}},"deny-register-listener":{"identifier":"deny-register-listener","description":"Denies the register_listener command without any pre-configured scope.","commands":{"allow":[],"deny":["register_listener"]}},"deny-remove-data-store":{"identifier":"deny-remove-data-store","description":"Denies the remove_data_store command Line truncated
+{"__app-acl__":{"default_permission":null,"permissions":{"allow-acquire-claude-token":{"identifier":"allow-acquire-claude-token","description":"Enables the acquire_claude_token command without any pre-configured scope.","commands":{"allow":["acquire_claude_token"],"deny":[]}},"allow-add-aws-keys-connection":{"identifier":"allow-add-aws-keys-connection","description":"Enables the add_aws_keys_connection command without any pre-configured scope.","commands":{"allow":["add_aws_keys_connection"],"deny":[]}},"allow-add-aws-profile-connection":{"identifier":"allow-add-aws-profile-connection","description":"Enables the add_aws_profile_connection command without any pre-configured scope.","commands":{"allow":["add_aws_profile_connection"],"deny":[]}},"allow-add-marketplace":{"identifier":"allow-add-marketplace","description":"Enables the add_marketplace command without any pre-configured scope.","commands":{"allow":["add_marketplace"],"deny":[]}},"allow-add-marketplace-gh-host-account":{"identifier":"allow-add-marketplace-gh-host-account","description":"Enables the add_marketplace_gh_host_account command without any pre-configured scope.","commands":{"allow":["add_marketplace_gh_host_account"],"deny":[]}},"allow-add-marketplace-token-account":{"identifier":"allow-add-marketplace-token-account","description":"Enables the add_marketplace_token_account command without any pre-configured scope.","commands":{"allow":["add_marketplace_token_account"],"deny":[]}},"allow-add-project":{"identifier":"allow-add-project","description":"Enables the add_project command without any pre-configured scope.","commands":{"allow":["add_project"],"deny":[]}},"allow-add-scheduled-task":{"identifier":"allow-add-scheduled-task","description":"Enables the add_scheduled_task command without any pre-configured scope.","commands":{"allow":["add_scheduled_task"],"deny":[]}},"allow-apply-marketplace-now":{"identifier":"allow-apply-marketplace-now","description":"Enables the apply_marketplace_now command without any pre-configured scope.","commands":{"allow":["apply_marketplace_now"],"deny":[]}},"allow-apply-settings-import":{"identifier":"allow-apply-settings-import","description":"Enables the apply_settings_import command without any pre-configured scope.","commands":{"allow":["apply_settings_import"],"deny":[]}},"allow-aws-connection-identity":{"identifier":"allow-aws-connection-identity","description":"Enables the aws_connection_identity command without any pre-configured scope.","commands":{"allow":["aws_connection_identity"],"deny":[]}},"allow-aws-connection-sso-login":{"identifier":"allow-aws-connection-sso-login","description":"Enables the aws_connection_sso_login command without any pre-configured scope.","commands":{"allow":["aws_connection_sso_login"],"deny":[]}},"allow-aws-policy-document":{"identifier":"allow-aws-policy-document","description":"Enables the aws_policy_document command without any pre-configured scope.","commands":{"allow":["aws_policy_document"],"deny":[]}},"allow-aws-sso-refresh":{"identifier":"allow-aws-sso-refresh","description":"Enables the aws_sso_refresh command without any pre-configured scope.","commands":{"allow":["aws_sso_refresh"],"deny":[]}},"allow-build-gateway-image":{"identifier":"allow-build-gateway-image","description":"Enables the build_gateway_image command without any pre-configured scope.","commands":{"allow":["build_gateway_image"],"deny":[]}},"allow-build-image":{"identifier":"allow-build-image","description":"Enables the build_image command without any pre-configured scope.","commands":{"allow":["build_image"],"deny":[]}},"allow-build-stt-image":{"identifier":"allow-build-stt-image","description":"Enables the build_stt_image command without any pre-configured scope.","commands":{"allow":["build_stt_image"],"deny":[]}},"allow-cancel-aws-deployment":{"identifier":"allow-cancel-aws-deployment","description":"Enables the cancel_aws_deployment command without any pre-configured scope.","commands":{"allow":["cancel_aws_deployment"],"deny":[]}},"allow-cancel-claude-token":{"identifier":"allow-cancel-claude-token","description":"Enables the cancel_claude_token command without any pre-configured scope.","commands":{"allow":["cancel_claude_token"],"deny":[]}},"allow-cancel-marketplace-gh-login":{"identifier":"allow-cancel-marketplace-gh-login","description":"Enables the cancel_marketplace_gh_login command without any pre-configured scope.","commands":{"allow":["cancel_marketplace_gh_login"],"deny":[]}},"allow-check-aws-permissions":{"identifier":"allow-check-aws-permissions","description":"Enables the check_aws_permissions command without any pre-configured scope.","commands":{"allow":["check_aws_permissions"],"deny":[]}},"allow-check-browser-view-support":{"identifier":"allow-check-browser-view-support","description":"Enables the check_browser_view_support command without any pre-configured scope.","commands":{"allow":["check_browser_view_support"],"deny":[]}},"allow-check-docker":{"identifier":"allow-Line truncated

app/src-tauri/gen/schemas/capabilities.json

@@ -1 +1 @@
-{"default":{"identifier":"default","description":"Default capabilities for Triple-C","local":true,"windows":["main"],"permissions":["core:default","core:event:default","core:event:allow-emit","core:event:allow-listen","core:event:allow-unlisten","core:event:allow-emit-to","dialog:default","dialog:allow-open","dialog:allow-save","dialog:allow-message","dialog:allow-ask","dialog:allow-confirm","store:default","store:allow-get","store:allow-set","store:allow-delete","store:allow-keys","store:allow-values","store:allow-entries","store:allow-length","store:allow-load","store:allow-reset","store:allow-save","store:allow-clear","opener:default","opener:allow-open-url"]}}
+{"default":{"identifier":"default","description":"Default capabilities for Triple-C. Every entry here is an IPC command a compromised webview can call directly, so the set is an enumeration of what `app/src` actually invokes — plugin and core grants verified against tauri 2.11.0's `PLUGINS` table in tauri's own `build.rs` rather than assumed from a plugin's `default` set, app-command grants (the bare `allow-*` entries) cross-checked by this crate's `build.rs` against `generate_handler!`. `core:default` in particular is NOT used: it is an alias for `core:{path,event,window,webview,app,image,resources,menu,tray}:default`, and `core:image:default` carries `allow-from-path`, whose handler (`tauri-2.11.0/src/image/plugin.rs:41` → `src/image/mod.rs:96`) is a bare `std::fs::read(path)` with no scope mechanism of any kind. Nothing imports `@tauri-apps/api/image`, so the whole plugin is dropped rather than scoped — there is nothing to scope it with. `core:menu` and `core:tray` are dropped for the same reason (no menu, no tray icon); `core:window` and `core:path` because nothing imports them; `core:resources:allow-close` because no frontend value is a `Resource`; and `core:event`'s `allow-emit`/`allow-emit-to` because the frontend only ever *listens* — every emit in this app originates in Rust. Three notes on what is deliberately kept or accepted: (1) `core:webview:allow-internal-toggle-devtools` is not called by `app/src` at all — it is called by Tauri's own injected `toggle-devtools.js`, which binds Ctrl/Cmd+Shift+I. Both that script and the command behind it are `#[cfg(any(debug_assertions, feature = \"devtools\"))]`, so this grant is a `tauri dev` convenience that does not exist in a release bundle. (2) `opener:allow-open-url` is **gone**. It could not be narrowed by host — `TerminalView`'s `WebLinksAddon` opens links Claude printed inside the container, which are arbitrary by construction, so a host allowlist would have deleted the feature rather than bounded it — and it was carried here as an accepted residual risk: a compromised webview could make the OS open an attacker-chosen http(s) URL, an outbound channel. That risk is now closed rather than recorded. Every host-browser open in the app goes through the `open_url_external` command in `url_open.rs`, which exists because the AppImage environment leaks into a cold-launched browser on Linux (triple-c#34) and which re-validates the URL in Rust — scheme allowlist, no embedded credentials, no control characters, length cap, ASCII asserted before `execvp`. On macOS and Windows that command reaches the same plugin as before, via `OpenerExt::open_url`, whose desktop implementation calls `crate::open::open` directly and is therefore not gated by this file at all (`tauri-plugin-opener-2.5.3/src/lib.rs:60`). The plugin stays a dependency for exactly that reason; what is removed is the webview's ability to reach it without passing the Rust validation. (3) `drag:allow-start-drag` is **gone**, together with the OS drag-out it existed for. It could not be scoped — `tauri-plugin-drag` takes the item paths from the caller and has no scope mechanism, so a compromised webview could call `startDrag({ item: ['~/.ssh/id_rsa'] })` against any host path the user can read — and it was carried as an accepted residual risk for one gesture. Drag-out was held back for separate hardening (see branch `hold/disk-and-dragout`) and the plugin is no longer a dependency. Getting a file *out* of a container is either \"Back up container\" on the project's Overview tab, which archives a tree through the Docker API, or the Files tab's per-row \"Save to host…\", which copies one file; getting one *in* is a drop on the Terminal or the Files tab's \"Upload…\". None of the four touches this permission. The Files tab's two are worth separating out here, because they are the only host-path commands in the app whose dialog is opened by **Rust** rather than by the webview — `pick_save_path` and `pick_files_to_upload` in `commands/file_commands.rs` drive `tauri-plugin-dialog` from the backend, so a compromised webview can ask for a picker and nothing more: it cannot name a host path as an *input* to either command. Be precise about the limit of that claim — host paths do still travel outward in error text (`Failed to create /home/j/Documents/x.txt.triple-c-part-1a2b3c4d: Permission denied`), including canonicalized ones, which disclose symlink targets. That is accepted; the app already hands the webview the project paths. What is closed is the direction that mattered — the webview naming where bytes go. That is the shape an earlier revision of this file named as the honest one if the Files tab ever regained host I/O, and it is the shape it regained it in. The `dialog:allow-open` / `dialog:allow-save` grants below are therefore *not* what those two use; they remain for the frontend pickers in Add Project, the Config tab's workspace and access sections, the CA-certificate fielLine truncated

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

@@ -0,0 +1,875 @@
+//! 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_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::host::{ContainerTarget, 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: ContainerTarget,
+        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,
+            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: ContainerTarget,
+    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 !container.is_running().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 = container.exec_oneshot_limited("claude", cmd, PROC_NET_OUTPUT_LIMIT) => {
+                res.map(|(out, _)| out)
+            }
+        };
+
+        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, &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: &ContainerTarget,
+    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.clone(), 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(
+            &ContainerTarget::docker("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,831 @@
+//! 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::host::ContainerTarget::attach_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 crate::host::{AttachedExec, ContainerTarget, ExecChunk};
+use futures_util::StreamExt;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::{TcpListener, TcpStream};
+use tokio::task::{JoinHandle, JoinSet};
+
+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`.
+    ///
+    /// 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: ContainerTarget,
+        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, 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: ContainerTarget,
+    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.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: ContainerTarget,
+    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, 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: ContainerTarget,
+    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 container.attach_exec(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(ExecChunk::StdOut(message)) => {
+                if host_tx.write_all(&message).await.is_err() {
+                    break;
+                }
+            }
+            Ok(ExecChunk::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/aws/connection.rs

@@ -0,0 +1,300 @@
+//! An `SdkConfig` built from a saved `HostConnection`, never from the
+//! process's default credentials chain.
+
+use aws_config::identity::IdentityCache;
+use aws_config::profile::ProfileFileCredentialsProvider;
+use aws_config::provider_config::ProviderConfig;
+use aws_config::retry::RetryConfig;
+use aws_config::{BehaviorVersion, Region, SdkConfig};
+use aws_credential_types::provider::error::CredentialsError;
+use aws_credential_types::provider::{future, ProvideCredentials, SharedCredentialsProvider};
+use aws_credential_types::Credentials;
+use aws_runtime::env_config::file::EnvConfigFiles;
+use aws_smithy_async::rt::sleep::default_async_sleep;
+use aws_smithy_async::time::SharedTimeSource;
+
+use super::error::{AwsError, ProfileCredentialsError};
+use crate::models::host_connection::{AwsAuth, HostConnection, HostKind};
+use crate::storage::secure;
+
+/// The SDK config for `conn` in `region`. Credentials are resolved lazily,
+/// so a missing profile or an expired SSO session surfaces on the first
+/// call and is classified there (`classify_sdk_error`).
+pub async fn sdk_config(conn: &HostConnection, region: &str) -> Result<SdkConfig, AwsError> {
+    sdk_config_with(conn, region, None).await
+}
+
+/// `sdk_config` with the profile files overridden (tests pass temp files so
+/// neither the process environment nor `~/.aws` is consulted).
+pub(crate) async fn sdk_config_with(
+    conn: &HostConnection,
+    region: &str,
+    profile_files: Option<EnvConfigFiles>,
+) -> Result<SdkConfig, AwsError> {
+    let HostKind::Aws { auth, .. } = &conn.kind;
+    let region = Region::new(region.to_string());
+    let credentials = match auth {
+        AwsAuth::Profile { name } => {
+            // The profile is read for credentials only (static keys, SSO,
+            // assume-role, credential_process), never for endpoints or
+            // service settings.
+            let mut builder = ProfileFileCredentialsProvider::builder()
+                .configure(&ProviderConfig::default().with_region(Some(region.clone())))
+                .profile_name(name);
+            if let Some(files) = profile_files {
+                builder = builder.profile_files(files);
+            }
+            SharedCredentialsProvider::new(NamedProfileProvider {
+                profile: name.clone(),
+                inner: builder.build(),
+            })
+        }
+        AwsAuth::Keys { keyring_ref } => {
+            let keys = secure::get_aws_keys(keyring_ref)
+                .map_err(|message| AwsError::Other { message })?
+                .ok_or(AwsError::KeysMissing)?;
+            keys_credentials(&keys)
+        }
+    };
+    Ok(build_sdk_config(region, credentials))
+}
+
+/// The SDK config for keys not yet saved (the add-connection check runs
+/// before anything touches the keychain).
+pub fn sdk_config_for_keys(keys: &secure::AwsKeys, region: &str) -> SdkConfig {
+    build_sdk_config(Region::new(region.to_string()), keys_credentials(keys))
+}
+
+fn keys_credentials(keys: &secure::AwsKeys) -> SharedCredentialsProvider {
+    SharedCredentialsProvider::new(Credentials::new(
+        keys.access_key_id.as_str(),
+        keys.secret_access_key.as_str(),
+        keys.session_token.clone(),
+        None,
+        "triple-c-connection",
+    ))
+}
+
+/// Built by hand rather than with `aws_config::defaults(..).load()`, which
+/// would read `AWS_ENDPOINT_URL[_<SERVICE>]`, FIPS/dual-stack, retry and
+/// other settings from the process environment and the default profile. A
+/// stray endpoint there would send every connection's signed requests (and
+/// the permission check) somewhere other than AWS. Connections talk to the
+/// real regional endpoints; a profile's own `endpoint_url` is ignored too.
+/// The HTTP client, timeouts and stalled-stream protection are each service
+/// client's defaults (the `default-https-client` stack every AWS crate here
+/// is built with).
+fn build_sdk_config(region: Region, credentials: SharedCredentialsProvider) -> SdkConfig {
+    let mut builder = SdkConfig::builder()
+        .behavior_version(BehaviorVersion::latest())
+        .region(region)
+        .credentials_provider(credentials)
+        .identity_cache(IdentityCache::lazy().build())
+        .retry_config(RetryConfig::standard())
+        .time_source(SharedTimeSource::default());
+    if let Some(sleep) = default_async_sleep() {
+        builder = builder.sleep_impl(sleep);
+    }
+    builder.build()
+}
+
+/// Puts the profile's name into the source chain of every credentials error,
+/// so a failure deep inside the SDK can be reported against the profile.
+#[derive(Debug)]
+struct NamedProfileProvider {
+    profile: String,
+    inner: ProfileFileCredentialsProvider,
+}
+
+impl NamedProfileProvider {
+    async fn load(&self) -> Result<Credentials, CredentialsError> {
+        self.inner.provide_credentials().await.map_err(|e| {
+            let not_loaded = matches!(e, CredentialsError::CredentialsNotLoaded(_));
+            let timed_out = matches!(e, CredentialsError::ProviderTimedOut(_));
+            if timed_out {
+                return e;
+            }
+            let invalid = matches!(e, CredentialsError::InvalidConfiguration(_));
+            let wrapped = ProfileCredentialsError {
+                profile: self.profile.clone(),
+                not_loaded,
+                source: e,
+            };
+            // Keep the error's kind; only its context changes.
+            if not_loaded {
+                CredentialsError::not_loaded(wrapped)
+            } else if invalid {
+                CredentialsError::invalid_configuration(wrapped)
+            } else {
+                CredentialsError::provider_error(wrapped)
+            }
+        })
+    }
+}
+
+impl ProvideCredentials for NamedProfileProvider {
+    fn provide_credentials<'a>(&'a self) -> future::ProvideCredentials<'a>
+    where
+        Self: 'a,
+    {
+        future::ProvideCredentials::new(self.load())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::aws::identity::caller_identity;
+    use crate::aws::AwsError;
+    use crate::models::host_connection::{AwsAuth, HostConnection, HostKind};
+    use aws_runtime::env_config::file::{EnvConfigFileKind, EnvConfigFiles};
+
+    fn profile_conn(name: &str) -> HostConnection {
+        HostConnection {
+            id: "c1".into(),
+            name: "Test".into(),
+            kind: HostKind::Aws {
+                auth: AwsAuth::Profile { name: name.into() },
+                default_region: "us-west-2".into(),
+            },
+        }
+    }
+
+    /// Empty config and credentials files, passed explicitly so neither the
+    /// process environment nor ~/.aws is consulted.
+    #[tokio::test]
+    async fn a_missing_profile_is_reported_by_name() {
+        let dir = tempfile::tempdir().unwrap();
+        let config = dir.path().join("config");
+        let creds = dir.path().join("credentials");
+        std::fs::write(&config, "").unwrap();
+        std::fs::write(&creds, "").unwrap();
+        let files = EnvConfigFiles::builder()
+            .include_default_config_file(false)
+            .include_default_credentials_file(false)
+            .with_file(EnvConfigFileKind::Config, &config)
+            .with_file(EnvConfigFileKind::Credentials, &creds)
+            .build();
+        let cfg = sdk_config_with(&profile_conn("nope"), "us-west-2", Some(files))
+            .await
+            .unwrap();
+        let err = caller_identity(&cfg).await.unwrap_err();
+        assert_eq!(
+            err,
+            AwsError::ProfileNotFound {
+                profile: "nope".into()
+            }
+        );
+    }
+
+    /// A profile that the files do define but under another name is still
+    /// "not found" for the name the connection asked for.
+    #[tokio::test]
+    async fn a_profile_absent_from_populated_files_is_reported_by_name() {
+        let dir = tempfile::tempdir().unwrap();
+        let config = dir.path().join("config");
+        std::fs::write(
+            &config,
+            "[profile other]\naws_access_key_id = AKIDTEST\naws_secret_access_key = s\n",
+        )
+        .unwrap();
+        let files = EnvConfigFiles::builder()
+            .include_default_config_file(false)
+            .include_default_credentials_file(false)
+            .with_file(EnvConfigFileKind::Config, &config)
+            .build();
+        let cfg = sdk_config_with(&profile_conn("nope"), "us-west-2", Some(files))
+            .await
+            .unwrap();
+        let err = caller_identity(&cfg).await.unwrap_err();
+        assert_eq!(
+            err,
+            AwsError::ProfileNotFound {
+                profile: "nope".into()
+            }
+        );
+    }
+
+    #[tokio::test]
+    async fn the_region_comes_from_the_argument() {
+        let dir = tempfile::tempdir().unwrap();
+        let config = dir.path().join("config");
+        std::fs::write(&config, "[profile p]\nregion = eu-west-1\n").unwrap();
+        let files = EnvConfigFiles::builder()
+            .include_default_config_file(false)
+            .include_default_credentials_file(false)
+            .with_file(EnvConfigFileKind::Config, &config)
+            .build();
+        let cfg = sdk_config_with(&profile_conn("p"), "ap-south-1", Some(files))
+            .await
+            .unwrap();
+        assert_eq!(cfg.region().map(|r| r.as_ref()), Some("ap-south-1"));
+    }
+
+    /// Config files that try to redirect every call. A connection always
+    /// talks to the real regional AWS endpoints, so none of this may reach
+    /// the config: not the named profile's `endpoint_url`, not `[default]`'s,
+    /// not a per-service `services` section.
+    const REDIRECTING_CONFIG: &str = "[default]
+endpoint_url = http://127.0.0.1:9
+retry_mode = adaptive
+max_attempts = 9
+use_fips_endpoint = true
+
+[profile p]
+endpoint_url = http://127.0.0.1:9
+retry_mode = adaptive
+max_attempts = 9
+use_dualstack_endpoint = true
+services = redirect
+aws_access_key_id = AKIDTEST
+aws_secret_access_key = s
+
+[services redirect]
+sts =
+  endpoint_url = http://127.0.0.1:9
+";
+
+    fn assert_isolated(cfg: &aws_config::SdkConfig) {
+        assert_eq!(cfg.endpoint_url(), None);
+        assert!(
+            cfg.service_config().is_none(),
+            "service config loaded from env/profile"
+        );
+        assert_eq!(cfg.use_fips(), None);
+        assert_eq!(cfg.use_dual_stack(), None);
+        let retry = cfg.retry_config().expect("retry config");
+        assert_eq!(retry.mode(), aws_config::retry::RetryMode::Standard);
+        assert_eq!(retry.max_attempts(), 3);
+        assert_eq!(cfg.region().map(|r| r.as_ref()), Some("us-west-2"));
+    }
+
+    #[tokio::test]
+    async fn a_profile_connection_ignores_endpoint_and_service_settings_in_the_profile() {
+        let dir = tempfile::tempdir().unwrap();
+        let config = dir.path().join("config");
+        std::fs::write(&config, REDIRECTING_CONFIG).unwrap();
+        let files = EnvConfigFiles::builder()
+            .include_default_config_file(false)
+            .include_default_credentials_file(false)
+            .with_file(EnvConfigFileKind::Config, &config)
+            .build();
+        let cfg = sdk_config_with(&profile_conn("p"), "us-west-2", Some(files))
+            .await
+            .unwrap();
+        assert_isolated(&cfg);
+    }
+
+    /// The keys arm reads no files or environment at all: same isolation.
+    #[test]
+    fn a_keys_connection_config_is_isolated() {
+        let keys = crate::storage::secure::AwsKeys {
+            access_key_id: "AKIDTEST".into(),
+            secret_access_key: "s".into(),
+            session_token: None,
+        };
+        let cfg = build_sdk_config(Region::new("us-west-2"), keys_credentials(&keys));
+        assert_isolated(&cfg);
+        assert!(cfg.credentials_provider().is_some());
+    }
+}

app/src-tauri/src/aws/error.rs

@@ -0,0 +1,157 @@
+//! What can go wrong talking to AWS, in the terms the UI acts on.
+
+use std::error::Error;
+
+use aws_sdk_sts::error::{DisplayErrorContext, ErrorMetadata};
+use serde::Serialize;
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum AwsError {
+    /// The UI offers "Sign in".
+    SsoExpired {
+        profile: String,
+    },
+    ProfileNotFound {
+        profile: String,
+    },
+    /// The keychain entry for a keys connection is gone.
+    KeysMissing,
+    InvalidCredentials {
+        message: String,
+    },
+    AccessDenied {
+        action: String,
+        message: String,
+    },
+    /// `s3:CreateBucket` said `BucketAlreadyExists`: the state bucket's
+    /// name belongs to another AWS account. Never treated as success.
+    StateBucketTaken {
+        bucket: String,
+    },
+    Other {
+        message: String,
+    },
+}
+
+impl std::fmt::Display for AwsError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            AwsError::SsoExpired { profile } if profile.is_empty() => {
+                write!(f, "The AWS SSO session has expired; sign in again")
+            }
+            AwsError::SsoExpired { profile } => write!(
+                f,
+                "The AWS SSO session for profile \"{profile}\" has expired; sign in again"
+            ),
+            AwsError::ProfileNotFound { profile } => write!(
+                f,
+                "AWS profile \"{profile}\" was not found, or has no credentials, in the AWS config and credentials files"
+            ),
+            AwsError::KeysMissing => write!(
+                f,
+                "The access keys for this connection are no longer in the system keychain; enter them again"
+            ),
+            AwsError::InvalidCredentials { message } => {
+                write!(f, "AWS rejected the credentials: {message}")
+            }
+            AwsError::AccessDenied { action, message } => {
+                write!(f, "Access denied for {action}: {message}")
+            }
+            AwsError::StateBucketTaken { bucket } => write!(
+                f,
+                "The state bucket name \"{bucket}\" is already taken by another AWS account, so \
+                 Triple-C can't keep OpenTofu state there"
+            ),
+            AwsError::Other { message } => f.write_str(message),
+        }
+    }
+}
+
+/// Carried in the source chain of every credentials error from a profile
+/// connection, so classification knows which profile failed and whether it
+/// produced no credentials at all (absent, or present without credentials).
+#[derive(Debug)]
+pub(crate) struct ProfileCredentialsError {
+    pub profile: String,
+    pub not_loaded: bool,
+    pub source: aws_credential_types::provider::error::CredentialsError,
+}
+
+impl std::fmt::Display for ProfileCredentialsError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "credentials for profile `{}`", self.profile)
+    }
+}
+
+impl Error for ProfileCredentialsError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        Some(&self.source)
+    }
+}
+
+const SSO_EXPIRED: &[&str] = &[
+    "The SSO session associated with this profile has expired",
+    "Token has expired",
+    "the SSO token has expired",
+];
+const SSO_REVOKED: &[&str] = &[
+    "UnauthorizedException",
+    "Session token not found or invalid",
+];
+const DENIED_CODES: &[&str] = &[
+    "AccessDeniedException",
+    "AccessDenied",
+    "UnauthorizedOperation",
+];
+const BAD_CREDENTIAL_CODES: &[&str] = &[
+    "ExpiredToken",
+    "InvalidClientTokenId",
+    "SignatureDoesNotMatch",
+    "UnrecognizedClientException",
+];
+
+/// Classify any SDK error (an `SdkError`, a credentials error, ...) from
+/// calling `action` (e.g. `iam:GetRole`). Matching is on the full display
+/// chain, which carries both provider messages and service error codes.
+pub fn classify_sdk_error(action: &str, err: &(dyn Error + 'static)) -> AwsError {
+    let text = DisplayErrorContext(err).to_string();
+    let mut chain = std::iter::successors(Some(err), |e| (*e).source());
+    let profile = chain
+        .clone()
+        .find_map(|e| e.downcast_ref::<ProfileCredentialsError>());
+    // The service's own message, when one is in the chain.
+    let service_message = chain
+        .find_map(|e| e.downcast_ref::<ErrorMetadata>())
+        .and_then(|m| m.message())
+        .map(str::to_string);
+    let message = service_message.unwrap_or_else(|| text.clone());
+
+    if SSO_EXPIRED.iter().any(|s| text.contains(s)) {
+        return AwsError::SsoExpired {
+            profile: profile.map(|p| p.profile.clone()).unwrap_or_default(),
+        };
+    }
+    // SSO's GetRoleCredentials on a revoked or signed-out session. Only
+    // inside a profile's credentials: other services use this code too.
+    if let Some(p) = profile.filter(|_| SSO_REVOKED.iter().any(|s| text.contains(s))) {
+        return AwsError::SsoExpired {
+            profile: p.profile.clone(),
+        };
+    }
+    if let Some(p) = profile.filter(|p| p.not_loaded) {
+        return AwsError::ProfileNotFound {
+            profile: p.profile.clone(),
+        };
+    }
+    if DENIED_CODES.iter().any(|c| text.contains(c)) {
+        return AwsError::AccessDenied {
+            action: action.to_string(),
+            message,
+        };
+    }
+    if BAD_CREDENTIAL_CODES.iter().any(|c| text.contains(c)) {
+        return AwsError::InvalidCredentials { message };
+    }
+    AwsError::Other { message: text }
+}

app/src-tauri/src/aws/identity.rs

@@ -0,0 +1,413 @@
+//! Who the connection's credentials are, and which IAM principal the
+//! policy simulator should be asked about.
+
+use aws_config::SdkConfig;
+use serde::Serialize;
+
+use super::error::{classify_sdk_error, AwsError};
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct CallerIdentity {
+    pub account: String,
+    pub arn: String,
+    /// STS `UserId`: the principal's unique id (for a role session,
+    /// `<role id>:<session name>`).
+    pub user_id: String,
+}
+
+/// `sts:GetCallerIdentity`, which needs no IAM permission: it is the
+/// connection test itself.
+pub async fn caller_identity(cfg: &SdkConfig) -> Result<CallerIdentity, AwsError> {
+    const ACTION: &str = "sts:GetCallerIdentity";
+    let out = aws_sdk_sts::Client::new(cfg)
+        .get_caller_identity()
+        .send()
+        .await
+        .map_err(|e| classify_sdk_error(ACTION, &e))?;
+    let field = |v: Option<&str>, name: &str| {
+        v.map(str::to_string).ok_or_else(|| AwsError::Other {
+            message: format!("{ACTION} returned no {name}"),
+        })
+    };
+    Ok(CallerIdentity {
+        account: field(out.account(), "Account")?,
+        arn: field(out.arn(), "Arn")?,
+        user_id: field(out.user_id(), "UserId")?,
+    })
+}
+
+/// The principal to simulate, as far as the caller's ARN tells us.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum PrincipalArn {
+    /// An IAM user or role ARN, usable as `PolicySourceArn` directly.
+    Exact(String),
+    /// A role session: the role's ARN carries a path the session ARN lacks,
+    /// so it has to be looked up (`resolve_principal`).
+    AssumedRole { account: String, role_name: String },
+}
+
+/// Map the caller's ARN to a simulatable principal. Root, federated users
+/// and anything unrecognised cannot be simulated; the caller falls back to
+/// probing instead.
+pub fn principal_for_simulation(caller_arn: &str) -> Result<PrincipalArn, AwsError> {
+    let unsupported = || AwsError::Other {
+        message: format!("IAM policy simulation isn't possible for the principal {caller_arn}"),
+    };
+    // arn:<partition>:<service>:<region>:<account>:<resource>
+    let mut parts = caller_arn.splitn(6, ':');
+    let (Some("arn"), Some(partition), Some(service), Some(_region), Some(account), Some(resource)) = (
+        parts.next(),
+        parts.next(),
+        parts.next(),
+        parts.next(),
+        parts.next(),
+        parts.next(),
+    ) else {
+        return Err(unsupported());
+    };
+    if partition.is_empty() || account.is_empty() {
+        return Err(unsupported());
+    }
+    match service {
+        "iam" if resource.starts_with("user/") || resource.starts_with("role/") => {
+            Ok(PrincipalArn::Exact(caller_arn.to_string()))
+        }
+        "sts" => match resource
+            .strip_prefix("assumed-role/")
+            .and_then(|r| r.split_once('/'))
+        {
+            Some((role_name, _session)) if !role_name.is_empty() => Ok(PrincipalArn::AssumedRole {
+                account: account.to_string(),
+                role_name: role_name.to_string(),
+            }),
+            _ => Err(unsupported()),
+        },
+        _ => Err(unsupported()),
+    }
+}
+
+/// The full ARN to simulate. An assumed role needs `iam:GetRole` to recover
+/// the role's path (SSO roles live under `/aws-reserved/...`).
+pub async fn resolve_principal(
+    iam: &aws_sdk_iam::Client,
+    p: PrincipalArn,
+) -> Result<String, AwsError> {
+    const ACTION: &str = "iam:GetRole";
+    let (account, role_name) = match p {
+        PrincipalArn::Exact(arn) => return Ok(arn),
+        PrincipalArn::AssumedRole { account, role_name } => (account, role_name),
+    };
+    let out = iam
+        .get_role()
+        .role_name(&role_name)
+        .send()
+        .await
+        .map_err(|e| classify_sdk_error(ACTION, &e))?;
+    let arn = out
+        .role()
+        .map(|r| r.arn().to_string())
+        .filter(|a| !a.is_empty())
+        .ok_or_else(|| AwsError::Other {
+            message: format!("{ACTION} returned no role for {role_name}"),
+        })?;
+    // The role must be the session's own: same account.
+    if arn.split(':').nth(4) != Some(account.as_str()) {
+        return Err(AwsError::Other {
+            message: format!("{ACTION} for {role_name} returned {arn}, outside account {account}"),
+        });
+    }
+    Ok(arn)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::aws::error::classify_sdk_error;
+    use crate::aws::AwsError;
+    use tokio::io::{AsyncReadExt, AsyncWriteExt};
+
+    #[test]
+    fn iam_user_arn_is_used_as_is() {
+        let arn = "arn:aws:iam::111122223333:user/alice";
+        assert_eq!(
+            principal_for_simulation(arn).unwrap(),
+            PrincipalArn::Exact(arn.into())
+        );
+    }
+
+    #[test]
+    fn iam_role_arn_is_used_as_is() {
+        let arn = "arn:aws:iam::111122223333:role/ops/deployer";
+        assert_eq!(
+            principal_for_simulation(arn).unwrap(),
+            PrincipalArn::Exact(arn.into())
+        );
+    }
+
+    #[test]
+    fn assumed_role_arn_maps_to_role_name() {
+        let arn = "arn:aws:sts::111122223333:assumed-role/AWSReservedSSO_Admin_abc/alice@x.com";
+        assert_eq!(
+            principal_for_simulation(arn).unwrap(),
+            PrincipalArn::AssumedRole {
+                account: "111122223333".into(),
+                role_name: "AWSReservedSSO_Admin_abc".into(),
+            }
+        );
+    }
+
+    #[test]
+    fn root_and_federated_arns_are_rejected_for_simulation() {
+        for arn in [
+            "arn:aws:iam::1:root",
+            "arn:aws:sts::1:federated-user/bob",
+            "not-an-arn",
+        ] {
+            match principal_for_simulation(arn) {
+                Err(AwsError::Other { message }) => {
+                    assert!(
+                        message.contains("simulation isn't possible"),
+                        "{arn}: {message}"
+                    )
+                }
+                other => panic!("{arn}: expected Other, got {other:?}"),
+            }
+        }
+    }
+
+    /// A one-shot-per-connection HTTP server that answers every request with
+    /// `status` and `body`, and reports each request it saw.
+    async fn fake_endpoint(
+        status: &'static str,
+        body: &'static str,
+    ) -> (String, tokio::sync::mpsc::UnboundedReceiver<String>) {
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let port = listener.local_addr().unwrap().port();
+        let (tx, rx) = tokio::sync::mpsc::unbounded_channel::<String>();
+        tokio::spawn(async move {
+            loop {
+                let Ok((mut sock, _)) = listener.accept().await else {
+                    return;
+                };
+                let tx = tx.clone();
+                tokio::spawn(async move {
+                    let mut buf = vec![0u8; 64 * 1024];
+                    let mut req = Vec::new();
+                    loop {
+                        let n = match sock.read(&mut buf).await {
+                            Ok(0) | Err(_) => return,
+                            Ok(n) => n,
+                        };
+                        req.extend_from_slice(&buf[..n]);
+                        let text = String::from_utf8_lossy(&req).into_owned();
+                        let Some(head_end) = text.find("\r\n\r\n") else {
+                            continue;
+                        };
+                        let len = text[..head_end]
+                            .lines()
+                            .find_map(|l| {
+                                let (k, v) = l.split_once(':')?;
+                                k.eq_ignore_ascii_case("content-length")
+                                    .then(|| v.trim().parse::<usize>().ok())
+                                    .flatten()
+                            })
+                            .unwrap_or(0);
+                        if req.len() < head_end + 4 + len {
+                            continue;
+                        }
+                        let _ = tx.send(text);
+                        let resp = format!(
+                            "HTTP/1.1 {status}\r\nContent-Type: text/xml\r\nContent-Length: {}\r\n\r\n{body}",
+                            body.len()
+                        );
+                        let _ = sock.write_all(resp.as_bytes()).await;
+                        req.clear();
+                    }
+                });
+            }
+        });
+        (format!("http://127.0.0.1:{port}"), rx)
+    }
+
+    fn iam_client(endpoint: String) -> aws_sdk_iam::Client {
+        let conf = aws_sdk_iam::Config::builder()
+            .behavior_version(aws_sdk_iam::config::BehaviorVersion::latest())
+            .region(aws_sdk_iam::config::Region::new("us-east-1"))
+            .credentials_provider(aws_sdk_iam::config::Credentials::new(
+                "AKIDTEST", "secret", None, None, "test",
+            ))
+            .endpoint_url(endpoint)
+            .build();
+        aws_sdk_iam::Client::from_conf(conf)
+    }
+
+    const ROLE_ARN: &str = "arn:aws:iam::111122223333:role/aws-reserved/sso.amazonaws.com/us-west-2/AWSReservedSSO_Admin_abc";
+
+    #[tokio::test]
+    async fn assumed_role_arn_maps_to_role_arn_with_path() {
+        const BODY: &str = r#"<GetRoleResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
+  <GetRoleResult>
+    <Role>
+      <Path>/aws-reserved/sso.amazonaws.com/us-west-2/</Path>
+      <RoleName>AWSReservedSSO_Admin_abc</RoleName>
+      <RoleId>AROAEXAMPLEID</RoleId>
+      <Arn>arn:aws:iam::111122223333:role/aws-reserved/sso.amazonaws.com/us-west-2/AWSReservedSSO_Admin_abc</Arn>
+      <CreateDate>2024-01-01T00:00:00Z</CreateDate>
+    </Role>
+  </GetRoleResult>
+  <ResponseMetadata><RequestId>req-1</RequestId></ResponseMetadata>
+</GetRoleResponse>"#;
+        let (endpoint, mut seen) = fake_endpoint("200 OK", BODY).await;
+        let p = PrincipalArn::AssumedRole {
+            account: "111122223333".into(),
+            role_name: "AWSReservedSSO_Admin_abc".into(),
+        };
+        let arn = resolve_principal(&iam_client(endpoint), p).await.unwrap();
+        assert_eq!(arn, ROLE_ARN);
+        let req = seen.recv().await.unwrap();
+        assert!(req.contains("Action=GetRole"), "{req}");
+        assert!(req.contains("RoleName=AWSReservedSSO_Admin_abc"), "{req}");
+    }
+
+    #[tokio::test]
+    async fn an_exact_principal_needs_no_lookup() {
+        // No endpoint answers: any request would fail the test.
+        let client = iam_client("http://127.0.0.1:9".into());
+        let arn = "arn:aws:iam::111122223333:user/alice";
+        let got = resolve_principal(&client, PrincipalArn::Exact(arn.into()))
+            .await
+            .unwrap();
+        assert_eq!(got, arn);
+    }
+
+    #[tokio::test]
+    async fn a_denied_get_role_is_access_denied_for_get_role() {
+        const BODY: &str = r#"<ErrorResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
+  <Error>
+    <Type>Sender</Type>
+    <Code>AccessDenied</Code>
+    <Message>User: arn:aws:sts::111122223333:assumed-role/R/alice is not authorized to perform: iam:GetRole</Message>
+  </Error>
+  <RequestId>req-2</RequestId>
+</ErrorResponse>"#;
+        let (endpoint, _seen) = fake_endpoint("403 Forbidden", BODY).await;
+        let p = PrincipalArn::AssumedRole {
+            account: "111122223333".into(),
+            role_name: "R".into(),
+        };
+        match resolve_principal(&iam_client(endpoint), p).await {
+            Err(AwsError::AccessDenied { action, message }) => {
+                assert_eq!(action, "iam:GetRole");
+                assert!(
+                    message.contains("is not authorized to perform: iam:GetRole"),
+                    "{message}"
+                );
+            }
+            other => panic!("expected AccessDenied, got {other:?}"),
+        }
+    }
+
+    #[derive(Debug)]
+    struct Msg(&'static str, Option<Box<dyn std::error::Error + 'static>>);
+    impl std::fmt::Display for Msg {
+        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+            f.write_str(self.0)
+        }
+    }
+    impl std::error::Error for Msg {
+        fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+            self.1.as_deref()
+        }
+    }
+
+    #[test]
+    fn an_expired_sso_token_is_reported_as_sso_expired() {
+        for leaf in [
+            "The SSO session associated with this profile has expired or is otherwise invalid",
+            "Token has expired and refresh failed",
+        ] {
+            // Deep in the chain, as the SDK reports it.
+            let err = Msg("dispatch failure", Some(Box::new(Msg(leaf, None))));
+            assert!(
+                matches!(
+                    classify_sdk_error("sts:GetCallerIdentity", &err),
+                    AwsError::SsoExpired { .. }
+                ),
+                "{leaf}"
+            );
+        }
+    }
+
+    /// SSO's GetRoleCredentials on a revoked or signed-out session. Inside a
+    /// profile connection's credentials that means "sign in again".
+    #[test]
+    fn a_revoked_sso_session_is_reported_as_sso_expired() {
+        use crate::aws::error::ProfileCredentialsError;
+        use aws_credential_types::provider::error::CredentialsError;
+        let leaf = CredentialsError::provider_error(
+            "service error: unhandled error (UnauthorizedException): Session token not found or invalid",
+        );
+        let err = CredentialsError::provider_error(ProfileCredentialsError {
+            profile: "dev".into(),
+            not_loaded: false,
+            source: leaf,
+        });
+        assert_eq!(
+            classify_sdk_error(
+                "sts:GetCallerIdentity",
+                &Msg("dispatch failure", Some(Box::new(err)))
+            ),
+            AwsError::SsoExpired {
+                profile: "dev".into()
+            }
+        );
+    }
+
+    /// The same error code from some other service, outside any profile's
+    /// credentials, is not an SSO problem.
+    #[test]
+    fn an_unauthorized_exception_outside_profile_credentials_is_not_sso() {
+        let err = Msg(
+            "service error: unhandled error (UnauthorizedException): Session token not found or invalid",
+            None,
+        );
+        assert!(!matches!(
+            classify_sdk_error("ecs:ListClusters", &err),
+            AwsError::SsoExpired { .. }
+        ));
+    }
+
+    #[test]
+    fn service_error_codes_are_classified() {
+        let denied = Msg(
+            "service error: unhandled error (AccessDeniedException)",
+            None,
+        );
+        assert!(matches!(
+            classify_sdk_error("ecs:ListClusters", &denied),
+            AwsError::AccessDenied { action, .. } if action == "ecs:ListClusters"
+        ));
+        for code in [
+            "ExpiredToken",
+            "InvalidClientTokenId",
+            "SignatureDoesNotMatch",
+        ] {
+            let text: &'static str =
+                Box::leak(format!("service error: unhandled error ({code})").into_boxed_str());
+            assert!(
+                matches!(
+                    classify_sdk_error("sts:GetCallerIdentity", &Msg(text, None)),
+                    AwsError::InvalidCredentials { .. }
+                ),
+                "{code}"
+            );
+        }
+        assert!(matches!(
+            classify_sdk_error(
+                "sts:GetCallerIdentity",
+                &Msg("io error: connection refused", None)
+            ),
+            AwsError::Other { .. }
+        ));
+    }
+}

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

@@ -0,0 +1,21 @@
+//! AWS connection plumbing: an SDK config built from a saved
+//! `HostConnection`, the caller's identity, the tier policies and the
+//! permission check.
+//!
+
+mod connection;
+pub mod environments;
+mod error;
+mod identity;
+#[cfg(test)]
+mod live_tests;
+pub mod permissions;
+pub mod policies;
+#[cfg(test)]
+mod policy_eval;
+pub mod tofu;
+pub mod tofu_modules;
+
+pub use connection::{sdk_config, sdk_config_for_keys};
+pub use error::{classify_sdk_error, AwsError};
+pub use identity::{caller_identity, CallerIdentity};

app/src-tauri/src/aws/permissions.rs

@@ -0,0 +1,544 @@
+//! The permission check: which Triple-C tier the connection's credentials
+//! can act as, by simulating each tier's checks (`policies::checks`) with
+//! IAM's policy simulator, or — when the caller may not simulate itself —
+//! by a few read-only probes.
+
+use std::future::Future;
+
+use futures_util::stream::{self, StreamExt, TryStreamExt};
+use serde::Serialize;
+
+use super::error::{classify_sdk_error, AwsError};
+use super::identity::{self, principal_for_simulation, CallerIdentity, PrincipalArn};
+use super::policies::{checks, render, Check, ContextValue, Placeholders, Tier};
+
+/// How many simulations are in flight at once.
+const CONCURRENCY: usize = 2;
+
+/// One `SimulatePrincipalPolicy` request, fully rendered.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SimulationRequest {
+    pub principal: String,
+    pub action: String,
+    pub resource: String,
+    pub context: Vec<ContextEntry>,
+}
+
+/// A context key with every value it carries in the request.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ContextEntry {
+    pub key: String,
+    pub values: Vec<String>,
+}
+
+impl ContextEntry {
+    /// Sent as `StringList` when the key has more than one value, `String`
+    /// otherwise.
+    pub fn is_list(&self) -> bool {
+        self.values.len() > 1
+    }
+}
+
+/// Builds the simulation for `check`: the resource and every literal context
+/// value rendered with `p`, `OwnerId` as `user_id`, and `aws:userid` =
+/// `user_id` added. A key appearing more than once becomes one entry holding
+/// all its values (in order, without duplicates).
+pub fn simulation_request(check: &Check, p: &Placeholders, user_id: &str) -> SimulationRequest {
+    let mut context: Vec<ContextEntry> = Vec::new();
+    let mut add = |key: &str, value: String| match context.iter_mut().find(|e| e.key == key) {
+        Some(e) if e.values.contains(&value) => {}
+        Some(e) => e.values.push(value),
+        None => context.push(ContextEntry {
+            key: key.to_string(),
+            values: vec![value],
+        }),
+    };
+    for (key, value) in check.context {
+        let value = match value {
+            ContextValue::OwnerId => user_id.to_string(),
+            ContextValue::Literal(template) => render(template, p),
+        };
+        add(key, value);
+    }
+    add("aws:userid", user_id.to_string());
+    SimulationRequest {
+        principal: p.principal.to_string(),
+        action: check.action.to_string(),
+        resource: render(check.resource, p),
+        context,
+    }
+}
+
+/// The read-only calls used when simulation isn't possible.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Probe {
+    EcsListClusters,
+    SsmGetParametersByPath,
+    SecretsListSecrets,
+}
+
+impl Probe {
+    const ALL: [Probe; 3] = [
+        Probe::EcsListClusters,
+        Probe::SsmGetParametersByPath,
+        Probe::SecretsListSecrets,
+    ];
+
+    /// The probe standing in for a read check's service, if there is one.
+    fn for_action(action: &str) -> Option<Probe> {
+        match action.split_once(':')?.0 {
+            "ecs" => Some(Probe::EcsListClusters),
+            "ssm" => Some(Probe::SsmGetParametersByPath),
+            "secretsmanager" => Some(Probe::SecretsListSecrets),
+            _ => None,
+        }
+    }
+
+    fn action(self) -> &'static str {
+        match self {
+            Probe::EcsListClusters => "ecs:ListClusters",
+            Probe::SsmGetParametersByPath => "ssm:GetParametersByPath",
+            Probe::SecretsListSecrets => "secretsmanager:ListSecrets",
+        }
+    }
+}
+
+/// What the permission check needs from AWS. The methods return `Send`
+/// futures so `check_permissions` is `Send` (a Tauri command needs that) for
+/// any implementation; an impl may still write them as `async fn`.
+pub trait PermissionApi: Send + Sync {
+    /// The ARN to simulate for the caller's principal (`iam:GetRole` for a
+    /// role session).
+    fn resolve_principal(
+        &self,
+        principal: PrincipalArn,
+    ) -> impl Future<Output = Result<String, AwsError>> + Send;
+    /// Whether the simulator says `allowed`.
+    fn simulate(
+        &self,
+        request: &SimulationRequest,
+    ) -> impl Future<Output = Result<bool, AwsError>> + Send;
+    fn probe(&self, probe: Probe) -> impl Future<Output = Result<(), AwsError>> + Send;
+}
+
+/// The real thing, from a connection's `SdkConfig`.
+pub struct SdkPermissionApi {
+    iam: aws_sdk_iam::Client,
+    ecs: aws_sdk_ecs::Client,
+    ssm: aws_sdk_ssm::Client,
+    secrets: aws_sdk_secretsmanager::Client,
+}
+
+impl SdkPermissionApi {
+    pub fn new(cfg: &aws_config::SdkConfig) -> Self {
+        // IAM throttles SimulatePrincipalPolicy hard: a full check (about a
+        // hundred simulations) failed a third of its rows with "Rate
+        // exceeded" under standard retries (verified live). Adaptive retry
+        // backs off client-side once throttled, with room to retry.
+        let iam = aws_sdk_iam::config::Builder::from(cfg)
+            .retry_config(aws_config::retry::RetryConfig::adaptive().with_max_attempts(10))
+            .build();
+        SdkPermissionApi {
+            iam: aws_sdk_iam::Client::from_conf(iam),
+            ecs: aws_sdk_ecs::Client::new(cfg),
+            ssm: aws_sdk_ssm::Client::new(cfg),
+            secrets: aws_sdk_secretsmanager::Client::new(cfg),
+        }
+    }
+}
+
+impl PermissionApi for SdkPermissionApi {
+    async fn resolve_principal(&self, principal: PrincipalArn) -> Result<String, AwsError> {
+        identity::resolve_principal(&self.iam, principal).await
+    }
+
+    async fn simulate(&self, request: &SimulationRequest) -> Result<bool, AwsError> {
+        use aws_sdk_iam::types::{ContextEntry as SdkEntry, ContextKeyTypeEnum};
+        const ACTION: &str = "iam:SimulatePrincipalPolicy";
+        let entries = request.context.iter().map(|e| {
+            SdkEntry::builder()
+                .context_key_name(&e.key)
+                .set_context_key_values(Some(e.values.clone()))
+                .context_key_type(if e.is_list() {
+                    ContextKeyTypeEnum::StringList
+                } else {
+                    ContextKeyTypeEnum::String
+                })
+                .build()
+        });
+        let out = self
+            .iam
+            .simulate_principal_policy()
+            .policy_source_arn(&request.principal)
+            .action_names(&request.action)
+            .resource_arns(&request.resource)
+            .set_context_entries(Some(entries.collect()))
+            .send()
+            .await
+            .map_err(|e| classify_sdk_error(ACTION, &e))?;
+        let decision = out
+            .evaluation_results()
+            .first()
+            .map(|r| r.eval_decision().as_str())
+            .ok_or_else(|| AwsError::Other {
+                message: format!("{ACTION} returned no result for {}", request.action),
+            })?;
+        Ok(decision == "allowed")
+    }
+
+    async fn probe(&self, probe: Probe) -> Result<(), AwsError> {
+        let action = probe.action();
+        let classify = |e: &(dyn std::error::Error + 'static)| classify_sdk_error(action, e);
+        match probe {
+            Probe::EcsListClusters => self
+                .ecs
+                .list_clusters()
+                .max_results(1)
+                .send()
+                .await
+                .map(drop)
+                .map_err(|e| classify(&e)),
+            Probe::SsmGetParametersByPath => self
+                .ssm
+                .get_parameters_by_path()
+                .path("/triple-c/environments")
+                .max_results(1)
+                .send()
+                .await
+                .map(drop)
+                .map_err(|e| classify(&e)),
+            Probe::SecretsListSecrets => self
+                .secrets
+                .list_secrets()
+                .max_results(1)
+                .send()
+                .await
+                .map(drop)
+                .map_err(|e| classify(&e)),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum Verdict {
+    Allowed,
+    Denied,
+    Unverified,
+}
+
+/// One row per action. An action checked against several resources (or
+/// with several contexts) is `Denied` if any of them is, else `Unverified`
+/// if any is, else `Allowed`.
+#[derive(Debug, Clone, Serialize)]
+pub struct ActionResult {
+    pub action: String,
+    pub verdict: Verdict,
+    /// Set when the row is `Unverified` because a call failed (throttling,
+    /// network, ...): the error, as `AwsError` displays it. Such a row
+    /// blocks its tier's claim; an `Unverified` row without a note (a write
+    /// in probe mode, an unprobed read) does not.
+    pub note: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct TierResult {
+    pub tier: Tier,
+    pub results: Vec<ActionResult>,
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum Method {
+    Simulated,
+    /// Simulation wasn't possible; `reason` says why.
+    Probed {
+        reason: String,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum Summary {
+    EnvironmentAdmin,
+    WorkspaceUser,
+    Insufficient,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct PermissionReport {
+    pub identity: CallerIdentity,
+    pub region: String,
+    pub method: Method,
+    pub summary: Summary,
+    /// `[WorkspaceUser, EnvironmentAdmin]`.
+    pub tiers: Vec<TierResult>,
+}
+
+const TIERS: [Tier; 2] = [Tier::WorkspaceUser, Tier::EnvironmentAdmin];
+
+/// One check's result, before checks are folded into per-action rows.
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum Outcome {
+    Allowed,
+    Denied,
+    /// Not checkable by design (a write in probe mode, an unprobed read).
+    Unverified,
+    /// The call failed for a reason that says nothing about the permission.
+    Failed(String),
+}
+
+/// The worst of `outcomes`: Denied, then Failed (as `Unverified` with the
+/// first failure as its note), then Unverified, then Allowed.
+fn aggregate(outcomes: &[Outcome]) -> (Verdict, Option<String>) {
+    if outcomes.contains(&Outcome::Denied) {
+        return (Verdict::Denied, None);
+    }
+    if let Some(note) = outcomes.iter().find_map(|o| match o {
+        Outcome::Failed(m) => Some(m.clone()),
+        _ => None,
+    }) {
+        return (Verdict::Unverified, Some(note));
+    }
+    if outcomes.contains(&Outcome::Unverified) {
+        return (Verdict::Unverified, None);
+    }
+    (Verdict::Allowed, None)
+}
+
+/// Folds per-check outcomes (in `checks(tier)` order) into one row per
+/// action, in first-appearance order.
+fn tier_result(tier: Tier, outcomes: Vec<Outcome>) -> TierResult {
+    let mut rows: Vec<(&'static str, Vec<Outcome>)> = Vec::new();
+    for (check, outcome) in checks(tier).iter().zip(outcomes) {
+        match rows.iter_mut().find(|(a, _)| *a == check.action) {
+            Some((_, os)) => os.push(outcome),
+            None => rows.push((check.action, vec![outcome])),
+        }
+    }
+    TierResult {
+        tier,
+        results: rows
+            .into_iter()
+            .map(|(action, os)| {
+                let (verdict, note) = aggregate(&os);
+                ActionResult {
+                    action: action.to_string(),
+                    verdict,
+                    note,
+                }
+            })
+            .collect(),
+    }
+}
+
+/// A tier is claimed when none of its rows is `Denied` or failed (has a
+/// note). Design-level `Unverified` rows don't block. A probed run never
+/// claims the admin tier (R15): it is nearly all writes, which probes can't
+/// see, so "nothing denied" would mean nothing.
+fn summary(tiers: &[TierResult], probed: bool) -> Summary {
+    let clear = |t: Tier| {
+        tiers.iter().filter(|r| r.tier == t).all(|r| {
+            r.results
+                .iter()
+                .all(|a| a.verdict != Verdict::Denied && a.note.is_none())
+        })
+    };
+    if !clear(Tier::WorkspaceUser) {
+        Summary::Insufficient
+    } else if !probed && clear(Tier::EnvironmentAdmin) {
+        Summary::EnvironmentAdmin
+    } else {
+        Summary::WorkspaceUser
+    }
+}
+
+/// Errors that mean the credentials themselves don't work: the UI acts on
+/// these (sign in, re-enter keys) rather than showing a report.
+fn is_credential_error(e: &AwsError) -> bool {
+    matches!(
+        e,
+        AwsError::SsoExpired { .. }
+            | AwsError::InvalidCredentials { .. }
+            | AwsError::ProfileNotFound { .. }
+            | AwsError::KeysMissing
+    )
+}
+
+/// Which tiers the caller's credentials can act as, in `region`.
+///
+/// Simulates every check of both tiers against the caller's principal. It
+/// falls back to probes when the principal can't be simulated (root,
+/// federated user), resolving it is denied (`iam:GetRole`), or the first
+/// simulation is denied. In probe mode a read check whose service has a
+/// probe takes that probe's result; the check behind the fallback (the
+/// caller's own `iam:GetRole` / `iam:SimulatePrincipalPolicy`) is `Denied`;
+/// every other check is `Unverified`.
+///
+/// A credential error (SSO expired, invalid or missing credentials) from
+/// any call is returned as `Err`, as is any other failure resolving the
+/// principal. Other failures of individual checks (throttling, network)
+/// make that row `Unverified` with a note, which blocks its tier's claim.
+/// See [`summary`] for the claim rules.
+pub async fn check_permissions<A: PermissionApi>(
+    api: &A,
+    identity: &CallerIdentity,
+    region: &str,
+) -> Result<PermissionReport, AwsError> {
+    let (method, outcomes) = match simulate_all(api, identity, region).await? {
+        Simulation::Done(outcomes) => (Method::Simulated, outcomes),
+        Simulation::Fallback { reason, denied } => (
+            Method::Probed { reason },
+            probe_all(api, denied.as_deref()).await?,
+        ),
+    };
+    let failed: Vec<&str> = outcomes
+        .iter()
+        .flatten()
+        .filter_map(|o| match o {
+            Outcome::Failed(m) => Some(m.as_str()),
+            _ => None,
+        })
+        .collect();
+    if let Some(first) = failed.first() {
+        let total: usize = outcomes.iter().map(Vec::len).sum();
+        log::warn!(
+            "AWS permission check: {} of {total} checks could not be evaluated (first: {first})",
+            failed.len()
+        );
+    }
+    let probed = matches!(method, Method::Probed { .. });
+    let tiers: Vec<TierResult> = TIERS
+        .into_iter()
+        .zip(outcomes)
+        .map(|(tier, os)| tier_result(tier, os))
+        .collect();
+    Ok(PermissionReport {
+        identity: identity.clone(),
+        region: region.to_string(),
+        method,
+        summary: summary(&tiers, probed),
+        tiers,
+    })
+}
+
+enum Simulation {
+    Done([Vec<Outcome>; 2]),
+    /// Simulation isn't possible. `denied` is the action whose denial
+    /// caused it, if one did.
+    Fallback {
+        reason: String,
+        denied: Option<String>,
+    },
+}
+
+impl Simulation {
+    fn fallback(e: AwsError) -> Self {
+        let denied = match &e {
+            AwsError::AccessDenied { action, .. } => Some(action.clone()),
+            _ => None,
+        };
+        Simulation::Fallback {
+            reason: e.to_string(),
+            denied,
+        }
+    }
+}
+
+fn simulated_outcome(r: Result<bool, AwsError>) -> Result<Outcome, AwsError> {
+    match r {
+        Ok(true) => Ok(Outcome::Allowed),
+        Ok(false) => Ok(Outcome::Denied),
+        Err(e) if is_credential_error(&e) => Err(e),
+        Err(e) => Ok(Outcome::Failed(e.to_string())),
+    }
+}
+
+/// Per-tier outcomes by simulation, or why simulation isn't possible.
+async fn simulate_all<A: PermissionApi>(
+    api: &A,
+    identity: &CallerIdentity,
+    region: &str,
+) -> Result<Simulation, AwsError> {
+    let principal = match principal_for_simulation(&identity.arn) {
+        Ok(p) => p,
+        Err(e) => return Ok(Simulation::fallback(e)),
+    };
+    let principal = match api.resolve_principal(principal).await {
+        Ok(p) => p,
+        Err(e @ AwsError::AccessDenied { .. }) => return Ok(Simulation::fallback(e)),
+        Err(e) => return Err(e),
+    };
+    let p = Placeholders {
+        region,
+        account: &identity.account,
+        principal: &principal,
+    };
+    let mut requests = TIERS
+        .into_iter()
+        .flat_map(|t| checks(t).iter())
+        .map(|c| simulation_request(c, &p, &identity.user_id))
+        .collect::<Vec<_>>()
+        .into_iter();
+    let Some(first) = requests.next() else {
+        return Ok(Simulation::Done([Vec::new(), Vec::new()]));
+    };
+    // The first simulation alone: if the caller may not simulate at all,
+    // that's the moment to fall back, before spending the rest.
+    let first = match api.simulate(&first).await {
+        Err(e @ AwsError::AccessDenied { .. }) => return Ok(Simulation::fallback(e)),
+        r => simulated_outcome(r)?,
+    };
+    // Owned requests: a closure over borrowed ones makes the future's
+    // `Send` unprovable (rustc's higher-ranked closure limitation).
+    let rest: Vec<Outcome> = stream::iter(requests)
+        .map(|r| async move { simulated_outcome(api.simulate(&r).await) })
+        .buffered(CONCURRENCY)
+        .try_collect()
+        .await?;
+    let mut all = std::iter::once(first).chain(rest);
+    Ok(Simulation::Done(
+        TIERS.map(|t| all.by_ref().take(checks(t).len()).collect()),
+    ))
+}
+
+/// Per-tier outcomes from the three probes. `denied` is the action whose
+/// denial forced probing; the caller's own-principal checks of it are
+/// `Denied`.
+async fn probe_all<A: PermissionApi>(
+    api: &A,
+    denied: Option<&str>,
+) -> Result<[Vec<Outcome>; 2], AwsError> {
+    let results =
+        futures_util::future::join_all(Probe::ALL.map(|p| async move { (p, api.probe(p).await) }))
+            .await;
+    if let Some((_, Err(e))) = results
+        .iter()
+        .find(|(_, r)| matches!(r, Err(e) if is_credential_error(e)))
+    {
+        return Err(e.clone());
+    }
+    let probe_outcome = |probe: Probe| match results.iter().find(|(p, _)| *p == probe) {
+        Some((_, Ok(()))) => Outcome::Allowed,
+        Some((_, Err(AwsError::AccessDenied { .. }))) => Outcome::Denied,
+        Some((_, Err(e))) => Outcome::Failed(e.to_string()),
+        None => Outcome::Unverified,
+    };
+    Ok(TIERS.map(|t| {
+        checks(t)
+            .iter()
+            .map(|c| {
+                if denied == Some(c.action) && c.resource == "{principal}" {
+                    return Outcome::Denied;
+                }
+                match Probe::for_action(c.action) {
+                    Some(probe) if !c.write => probe_outcome(probe),
+                    _ => Outcome::Unverified,
+                }
+            })
+            .collect()
+    }))
+}
+
+#[cfg(test)]
+mod tests;

app/src-tauri/src/aws/permissions/tests.rs

@@ -0,0 +1,630 @@
+use std::collections::HashSet;
+use std::sync::Mutex;
+
+use super::*;
+use crate::aws::policies::{checks, Check, ContextValue, Placeholders, Tier};
+
+const USER_ID: &str = "AROAEXAMPLEID:alice@example.com";
+const ROLE_ARN: &str =
+    "arn:aws:iam::111122223333:role/aws-reserved/sso.amazonaws.com/us-west-2/AWSReservedSSO_Ws_abc";
+
+fn identity() -> CallerIdentity {
+    CallerIdentity {
+        account: "111122223333".into(),
+        arn: "arn:aws:sts::111122223333:assumed-role/AWSReservedSSO_Ws_abc/alice@example.com"
+            .into(),
+        user_id: USER_ID.into(),
+    }
+}
+
+const ALL_PROBES: [Probe; 3] = [
+    Probe::EcsListClusters,
+    Probe::SsmGetParametersByPath,
+    Probe::SecretsListSecrets,
+];
+
+/// A simulation call as the fake saw it.
+#[derive(Debug, Clone)]
+struct Simulated {
+    principal: String,
+    action: String,
+    resource: String,
+    context: Vec<ContextEntry>,
+}
+
+struct FakeApi {
+    allow: HashSet<&'static str>,
+    simulate_denied: bool,
+    get_role_denied: bool,
+    /// Returned by `resolve_principal` (after `get_role_denied`).
+    resolve_error: Option<AwsError>,
+    /// Returned by `simulate` for the named action.
+    simulate_errors: Vec<(&'static str, AwsError)>,
+    probes_ok: HashSet<Probe>,
+    /// Returned by every probe not in `probes_ok` (default: AccessDenied).
+    probe_error: Option<AwsError>,
+    simulated: Mutex<Vec<Simulated>>,
+    probed: Mutex<Vec<Probe>>,
+}
+
+impl FakeApi {
+    fn allowing(tiers: &[Tier]) -> Self {
+        let allow = tiers
+            .iter()
+            .flat_map(|t| checks(*t).iter().map(|c| c.action))
+            .collect();
+        FakeApi {
+            allow,
+            simulate_denied: false,
+            get_role_denied: false,
+            resolve_error: None,
+            simulate_errors: Vec::new(),
+            probes_ok: ALL_PROBES.into_iter().collect(),
+            probe_error: None,
+            simulated: Mutex::new(Vec::new()),
+            probed: Mutex::new(Vec::new()),
+        }
+    }
+
+    fn simulated(&self) -> Vec<Simulated> {
+        self.simulated.lock().unwrap().clone()
+    }
+}
+
+impl PermissionApi for FakeApi {
+    async fn resolve_principal(&self, principal: PrincipalArn) -> Result<String, AwsError> {
+        if self.get_role_denied {
+            return Err(AwsError::AccessDenied {
+                action: "iam:GetRole".into(),
+                message: "not authorized to perform: iam:GetRole".into(),
+            });
+        }
+        if let Some(e) = &self.resolve_error {
+            return Err(e.clone());
+        }
+        Ok(match principal {
+            PrincipalArn::Exact(arn) => arn,
+            PrincipalArn::AssumedRole { .. } => ROLE_ARN.into(),
+        })
+    }
+
+    async fn simulate(&self, request: &SimulationRequest) -> Result<bool, AwsError> {
+        self.simulated.lock().unwrap().push(Simulated {
+            principal: request.principal.clone(),
+            action: request.action.clone(),
+            resource: request.resource.clone(),
+            context: request.context.clone(),
+        });
+        if self.simulate_denied {
+            return Err(AwsError::AccessDenied {
+                action: "iam:SimulatePrincipalPolicy".into(),
+                message: "not authorized to perform: iam:SimulatePrincipalPolicy".into(),
+            });
+        }
+        if let Some((_, e)) = self
+            .simulate_errors
+            .iter()
+            .find(|(a, _)| *a == request.action)
+        {
+            return Err(e.clone());
+        }
+        Ok(self.allow.contains(request.action.as_str()))
+    }
+
+    async fn probe(&self, probe: Probe) -> Result<(), AwsError> {
+        self.probed.lock().unwrap().push(probe);
+        if self.probes_ok.contains(&probe) {
+            Ok(())
+        } else if let Some(e) = &self.probe_error {
+            Err(e.clone())
+        } else {
+            Err(AwsError::AccessDenied {
+                action: format!("{probe:?}"),
+                message: "denied".into(),
+            })
+        }
+    }
+}
+
+fn try_run(api: &FakeApi, id: &CallerIdentity) -> Result<PermissionReport, AwsError> {
+    tokio::runtime::Builder::new_current_thread()
+        .build()
+        .unwrap()
+        .block_on(check_permissions(api, id, "eu-west-1"))
+}
+
+fn run(api: &FakeApi) -> PermissionReport {
+    try_run(api, &identity()).unwrap()
+}
+
+fn row<'a>(report: &'a PermissionReport, t: Tier, action: &str) -> &'a ActionResult {
+    tier(report, t)
+        .results
+        .iter()
+        .find(|r| r.action == action)
+        .unwrap_or_else(|| panic!("{action} not in {t:?}"))
+}
+
+fn throttled() -> AwsError {
+    AwsError::Other {
+        message: "Rate exceeded (Throttling)".into(),
+    }
+}
+
+fn tier(report: &PermissionReport, t: Tier) -> &TierResult {
+    report.tiers.iter().find(|r| r.tier == t).unwrap()
+}
+
+fn verdict(report: &PermissionReport, t: Tier, action: &str) -> Verdict {
+    tier(report, t)
+        .results
+        .iter()
+        .find(|r| r.action == action)
+        .unwrap_or_else(|| panic!("{action} not in {t:?}"))
+        .verdict
+        .clone()
+}
+
+#[test]
+fn a_full_workspace_policy_reports_workspace_user() {
+    let api = FakeApi::allowing(&[Tier::WorkspaceUser]);
+    let report = run(&api);
+    assert_eq!(report.method, Method::Simulated);
+    assert_eq!(report.summary, Summary::WorkspaceUser);
+    assert_eq!(report.region, "eu-west-1");
+    assert_eq!(report.identity, identity());
+    let tiers: Vec<Tier> = report.tiers.iter().map(|t| t.tier).collect();
+    assert_eq!(tiers, [Tier::WorkspaceUser, Tier::EnvironmentAdmin]);
+    assert!(tier(&report, Tier::WorkspaceUser)
+        .results
+        .iter()
+        .all(|r| r.verdict == Verdict::Allowed));
+    // Every check was simulated against the resolved role, not the session.
+    let sims = api.simulated();
+    let total = checks(Tier::WorkspaceUser).len() + checks(Tier::EnvironmentAdmin).len();
+    assert_eq!(sims.len(), total);
+    assert!(sims.iter().all(|s| s.principal == ROLE_ARN));
+}
+
+#[test]
+fn admin_and_workspace_policies_report_environment_admin() {
+    let api = FakeApi::allowing(&[Tier::WorkspaceUser, Tier::EnvironmentAdmin]);
+    let report = run(&api);
+    assert_eq!(report.method, Method::Simulated);
+    assert_eq!(report.summary, Summary::EnvironmentAdmin);
+}
+
+#[test]
+fn a_missing_action_reports_insufficient_and_names_it() {
+    let mut api = FakeApi::allowing(&[Tier::WorkspaceUser, Tier::EnvironmentAdmin]);
+    api.allow.remove("iam:PassRole");
+    let report = run(&api);
+    assert_eq!(report.summary, Summary::Insufficient);
+    assert_eq!(
+        verdict(&report, Tier::WorkspaceUser, "iam:PassRole"),
+        Verdict::Denied
+    );
+    assert_eq!(
+        verdict(&report, Tier::WorkspaceUser, "ecs:RunTask"),
+        Verdict::Allowed
+    );
+}
+
+#[test]
+fn an_admin_gap_still_reports_workspace_user() {
+    let mut api = FakeApi::allowing(&[Tier::WorkspaceUser, Tier::EnvironmentAdmin]);
+    api.allow.remove("ec2:CreateVpc");
+    let report = run(&api);
+    assert_eq!(report.summary, Summary::WorkspaceUser);
+    assert_eq!(
+        verdict(&report, Tier::EnvironmentAdmin, "ec2:CreateVpc"),
+        Verdict::Denied
+    );
+}
+
+/// An action checked against several resources is one row; any denial wins.
+#[test]
+fn an_action_checked_twice_is_one_row_and_denied_if_either_is() {
+    let api = FakeApi::allowing(&[Tier::WorkspaceUser]);
+    let report = run(&api);
+    let rows = tier(&report, Tier::WorkspaceUser)
+        .results
+        .iter()
+        .filter(|r| r.action == "ssm:StartSession")
+        .count();
+    assert_eq!(rows, 1);
+    let failed = || Outcome::Failed("Throttling".into());
+    assert_eq!(
+        aggregate(&[Outcome::Allowed, Outcome::Denied, failed()]),
+        (Verdict::Denied, None)
+    );
+    assert_eq!(
+        aggregate(&[Outcome::Allowed, Outcome::Unverified, failed()]),
+        (Verdict::Unverified, Some("Throttling".into()))
+    );
+    assert_eq!(
+        aggregate(&[Outcome::Allowed, Outcome::Unverified]),
+        (Verdict::Unverified, None)
+    );
+    assert_eq!(aggregate(&[Outcome::Allowed]), (Verdict::Allowed, None));
+}
+
+fn context_value<'a>(s: &'a Simulated, key: &str) -> Option<&'a ContextEntry> {
+    s.context.iter().find(|e| e.key == key)
+}
+
+#[test]
+fn owner_context_is_sent_with_owner_scoped_checks() {
+    let api = FakeApi::allowing(&[Tier::WorkspaceUser]);
+    run(&api);
+    let sims = api.simulated();
+    let run_task = sims.iter().find(|s| s.action == "ecs:RunTask").unwrap();
+    let owner = context_value(run_task, "aws:RequestTag/triple-c:owner").unwrap();
+    assert_eq!(owner.values, [USER_ID]);
+    // Literals are rendered like resources.
+    let cluster = context_value(run_task, "ecs:cluster").unwrap();
+    assert_eq!(
+        cluster.values,
+        ["arn:aws:ecs:eu-west-1:111122223333:cluster/triple-c-probe"]
+    );
+    assert_eq!(
+        run_task.resource,
+        "arn:aws:ecs:eu-west-1:111122223333:task-definition/triple-c-probe:1"
+    );
+    // aws:userid on every simulation.
+    for s in &sims {
+        let userid = context_value(s, "aws:userid")
+            .unwrap_or_else(|| panic!("{} has no aws:userid", s.action));
+        assert_eq!(userid.values, [USER_ID], "{}", s.action);
+    }
+}
+
+#[test]
+fn the_principal_placeholder_is_the_resolved_role() {
+    let api = FakeApi::allowing(&[Tier::WorkspaceUser]);
+    run(&api);
+    let sims = api.simulated();
+    let get_role = sims
+        .iter()
+        .find(|s| s.action == "iam:GetRole" && s.resource == ROLE_ARN)
+        .expect("iam:GetRole on the caller's own role");
+    // The policies name a user's own ARN by `${aws:username}`.
+    assert_eq!(
+        context_value(get_role, "aws:username").unwrap().values,
+        [ROLE_ARN.rsplit('/').next().unwrap()]
+    );
+}
+
+#[test]
+fn a_repeated_context_key_is_one_string_list_entry() {
+    static CTX: &[(&str, ContextValue)] = &[
+        ("aws:TagKeys", ContextValue::Literal("triple-c:owner")),
+        (
+            "ecs:cluster",
+            ContextValue::Literal("arn:{region}:{account}"),
+        ),
+        ("aws:TagKeys", ContextValue::Literal("triple-c:component")),
+        ("aws:TagKeys", ContextValue::OwnerId),
+    ];
+    let check = Check {
+        action: "ecs:TagResource",
+        resource: "arn:aws:ecs:{region}:{account}:task/x",
+        context: CTX,
+        write: true,
+    };
+    let p = Placeholders {
+        region: "eu-west-1",
+        account: "111122223333",
+        principal: ROLE_ARN,
+    };
+    let req = simulation_request(&check, &p, USER_ID);
+    assert_eq!(req.principal, ROLE_ARN);
+    assert_eq!(req.action, "ecs:TagResource");
+    assert_eq!(req.resource, "arn:aws:ecs:eu-west-1:111122223333:task/x");
+    assert_eq!(
+        req.context,
+        [
+            ContextEntry {
+                key: "aws:TagKeys".into(),
+                values: vec![
+                    "triple-c:owner".into(),
+                    "triple-c:component".into(),
+                    USER_ID.into()
+                ],
+            },
+            ContextEntry {
+                key: "ecs:cluster".into(),
+                values: vec!["arn:eu-west-1:111122223333".into()],
+            },
+            ContextEntry {
+                key: "aws:userid".into(),
+                values: vec![USER_ID.into()],
+            },
+        ]
+    );
+    assert!(req.context[0].is_list());
+    assert!(!req.context[1].is_list());
+}
+
+#[test]
+fn a_check_naming_aws_userid_itself_is_not_sent_it_twice() {
+    static CTX: &[(&str, ContextValue)] = &[("aws:userid", ContextValue::OwnerId)];
+    let check = Check {
+        action: "sts:GetCallerIdentity",
+        resource: "*",
+        context: CTX,
+        write: false,
+    };
+    let p = Placeholders {
+        region: "r",
+        account: "a",
+        principal: "p",
+    };
+    let req = simulation_request(&check, &p, USER_ID);
+    assert_eq!(
+        req.context,
+        [ContextEntry {
+            key: "aws:userid".into(),
+            values: vec![USER_ID.into()],
+        }]
+    );
+}
+
+#[test]
+fn a_denied_simulation_falls_back_to_probes_and_marks_writes_unverified() {
+    let mut api = FakeApi::allowing(&[Tier::WorkspaceUser, Tier::EnvironmentAdmin]);
+    api.simulate_denied = true;
+    let report = run(&api);
+    match &report.method {
+        Method::Probed { reason } => {
+            assert!(reason.contains("iam:SimulatePrincipalPolicy"), "{reason}")
+        }
+        m => panic!("expected Probed, got {m:?}"),
+    }
+    // Only the first simulation was tried.
+    assert_eq!(api.simulated().len(), 1);
+    let mut probed = api.probed.lock().unwrap().clone();
+    probed.sort_by_key(|p| format!("{p:?}"));
+    let mut all = ALL_PROBES.to_vec();
+    all.sort_by_key(|p| format!("{p:?}"));
+    assert_eq!(probed, all);
+
+    let ws = Tier::WorkspaceUser;
+    assert_eq!(verdict(&report, ws, "ecs:RunTask"), Verdict::Unverified);
+    assert_eq!(verdict(&report, ws, "iam:PassRole"), Verdict::Unverified);
+    // Reads with a probe get its result.
+    assert_eq!(verdict(&report, ws, "ecs:ListClusters"), Verdict::Allowed);
+    assert_eq!(
+        verdict(&report, ws, "ecs:DescribeClusters"),
+        Verdict::Allowed
+    );
+    assert_eq!(
+        verdict(&report, ws, "ssm:GetParametersByPath"),
+        Verdict::Allowed
+    );
+    assert_eq!(
+        verdict(&report, ws, "secretsmanager:ListSecrets"),
+        Verdict::Allowed
+    );
+    // Reads with no probe are unverified.
+    assert_eq!(
+        verdict(&report, ws, "logs:FilterLogEvents"),
+        Verdict::Unverified
+    );
+    assert_eq!(verdict(&report, ws, "iam:GetRole"), Verdict::Unverified);
+    assert_eq!(
+        verdict(&report, ws, "sts:GetCallerIdentity"),
+        Verdict::Unverified
+    );
+    // The fallback itself is evidence: the caller may not simulate itself,
+    // which both tiers need.
+    for t in [ws, Tier::EnvironmentAdmin] {
+        assert_eq!(
+            verdict(&report, t, "iam:SimulatePrincipalPolicy"),
+            Verdict::Denied
+        );
+    }
+    assert_eq!(report.summary, Summary::Insufficient);
+}
+
+#[test]
+fn a_denied_get_role_falls_back_to_probes() {
+    let mut api = FakeApi::allowing(&[Tier::WorkspaceUser]);
+    api.get_role_denied = true;
+    let report = run(&api);
+    match &report.method {
+        Method::Probed { reason } => assert!(reason.contains("iam:GetRole"), "{reason}"),
+        m => panic!("expected Probed, got {m:?}"),
+    }
+    assert!(api.simulated().is_empty());
+    assert_eq!(api.probed.lock().unwrap().len(), ALL_PROBES.len());
+    // Denied on the caller's own role: direct evidence.
+    assert_eq!(
+        verdict(&report, Tier::WorkspaceUser, "iam:GetRole"),
+        Verdict::Denied
+    );
+    assert_eq!(report.summary, Summary::Insufficient);
+}
+
+#[test]
+fn an_unsimulatable_principal_falls_back_to_probes() {
+    let api = FakeApi::allowing(&[Tier::WorkspaceUser]);
+    let mut id = identity();
+    id.arn = "arn:aws:iam::111122223333:root".into();
+    let report = try_run(&api, &id).unwrap();
+    match &report.method {
+        Method::Probed { reason } => assert!(reason.contains("simulation"), "{reason}"),
+        m => panic!("expected Probed, got {m:?}"),
+    }
+    assert!(api.simulated().is_empty());
+}
+
+/// R15: the admin tier is nearly all writes, so a probed run can't vouch
+/// for it — every probe passing still caps at WorkspaceUser.
+#[test]
+fn a_probed_run_never_claims_environment_admin() {
+    let api = FakeApi::allowing(&[Tier::WorkspaceUser, Tier::EnvironmentAdmin]);
+    let mut id = identity();
+    id.arn = "arn:aws:iam::111122223333:root".into();
+    let report = try_run(&api, &id).unwrap();
+    assert!(matches!(report.method, Method::Probed { .. }));
+    assert!(tier(&report, Tier::EnvironmentAdmin)
+        .results
+        .iter()
+        .all(|r| r.verdict != Verdict::Denied));
+    assert_eq!(report.summary, Summary::WorkspaceUser);
+}
+
+#[test]
+fn throttled_simulations_block_the_tier_and_carry_notes() {
+    let mut api = FakeApi::allowing(&[Tier::WorkspaceUser, Tier::EnvironmentAdmin]);
+    api.simulate_errors = vec![("ec2:CreateVpc", throttled())];
+    let report = run(&api);
+    assert_eq!(report.method, Method::Simulated);
+    let r = row(&report, Tier::EnvironmentAdmin, "ec2:CreateVpc");
+    assert_eq!(r.verdict, Verdict::Unverified);
+    assert!(r.note.as_deref().unwrap().contains("Throttling"), "{r:?}");
+    // Allowed rows carry no note.
+    assert_eq!(row(&report, Tier::WorkspaceUser, "ecs:RunTask").note, None);
+    assert_eq!(report.summary, Summary::WorkspaceUser);
+
+    // In the workspace tier, it blocks everything.
+    let mut api = FakeApi::allowing(&[Tier::WorkspaceUser, Tier::EnvironmentAdmin]);
+    api.simulate_errors = vec![("ecs:RunTask", throttled())];
+    let report = run(&api);
+    assert_eq!(report.summary, Summary::Insufficient);
+    assert!(row(&report, Tier::WorkspaceUser, "ecs:RunTask")
+        .note
+        .is_some());
+}
+
+#[test]
+fn a_throttled_first_simulation_is_a_note_not_a_fallback() {
+    let mut api = FakeApi::allowing(&[Tier::WorkspaceUser, Tier::EnvironmentAdmin]);
+    let first = checks(Tier::WorkspaceUser)[0].action;
+    api.simulate_errors = vec![(first, throttled())];
+    let report = run(&api);
+    assert_eq!(report.method, Method::Simulated);
+    assert!(row(&report, Tier::WorkspaceUser, first).note.is_some());
+    assert_eq!(report.summary, Summary::Insufficient);
+}
+
+#[test]
+fn an_expired_sso_session_mid_check_is_an_error() {
+    let mut api = FakeApi::allowing(&[Tier::WorkspaceUser, Tier::EnvironmentAdmin]);
+    let sso = AwsError::SsoExpired {
+        profile: "dev".into(),
+    };
+    api.simulate_errors = vec![("logs:FilterLogEvents", sso.clone())];
+    assert_eq!(try_run(&api, &identity()).unwrap_err(), sso);
+}
+
+#[test]
+fn credential_errors_anywhere_are_errors() {
+    let bad = AwsError::InvalidCredentials {
+        message: "ExpiredToken".into(),
+    };
+    // From resolving the principal.
+    let mut api = FakeApi::allowing(&[Tier::WorkspaceUser]);
+    api.resolve_error = Some(bad.clone());
+    assert_eq!(try_run(&api, &identity()).unwrap_err(), bad);
+    // From the first simulation.
+    let mut api = FakeApi::allowing(&[Tier::WorkspaceUser]);
+    api.simulate_errors = vec![(checks(Tier::WorkspaceUser)[0].action, bad.clone())];
+    assert_eq!(try_run(&api, &identity()).unwrap_err(), bad);
+    // From a probe.
+    let mut api = FakeApi::allowing(&[Tier::WorkspaceUser]);
+    api.get_role_denied = true;
+    api.probes_ok.remove(&Probe::SecretsListSecrets);
+    api.probe_error = Some(AwsError::KeysMissing);
+    assert_eq!(
+        try_run(&api, &identity()).unwrap_err(),
+        AwsError::KeysMissing
+    );
+}
+
+#[test]
+fn a_transport_error_resolving_the_principal_is_an_error() {
+    let mut api = FakeApi::allowing(&[Tier::WorkspaceUser]);
+    let net = AwsError::Other {
+        message: "dispatch failure: connection refused".into(),
+    };
+    api.resolve_error = Some(net.clone());
+    assert_eq!(try_run(&api, &identity()).unwrap_err(), net);
+    assert!(api.probed.lock().unwrap().is_empty());
+}
+
+#[test]
+fn a_failed_probe_marks_its_reads_denied() {
+    let mut api = FakeApi::allowing(&[Tier::WorkspaceUser]);
+    api.simulate_denied = true;
+    api.probes_ok.remove(&Probe::EcsListClusters);
+    let report = run(&api);
+    let ws = Tier::WorkspaceUser;
+    assert_eq!(verdict(&report, ws, "ecs:ListClusters"), Verdict::Denied);
+    assert_eq!(
+        verdict(&report, ws, "ecs:DescribeClusters"),
+        Verdict::Denied
+    );
+    assert_eq!(
+        verdict(&report, ws, "secretsmanager:ListSecrets"),
+        Verdict::Allowed
+    );
+    assert_eq!(report.summary, Summary::Insufficient);
+}
+
+#[test]
+fn a_probe_failing_for_another_reason_leaves_its_reads_unverified_and_blocks() {
+    let mut api = FakeApi::allowing(&[Tier::WorkspaceUser]);
+    let mut id = identity();
+    id.arn = "arn:aws:iam::111122223333:root".into();
+    api.probes_ok.remove(&Probe::EcsListClusters);
+    api.probe_error = Some(AwsError::Other {
+        message: "connection reset".into(),
+    });
+    let report = try_run(&api, &id).unwrap();
+    let r = row(&report, Tier::WorkspaceUser, "ecs:ListClusters");
+    assert_eq!(r.verdict, Verdict::Unverified);
+    assert!(r.note.as_deref().unwrap().contains("connection reset"));
+    // Design-level unverified rows carry no note.
+    assert_eq!(row(&report, Tier::WorkspaceUser, "ecs:RunTask").note, None);
+    assert_eq!(report.summary, Summary::Insufficient);
+}
+
+#[test]
+fn the_report_serializes_for_the_ui() {
+    let mut api = FakeApi::allowing(&[Tier::WorkspaceUser]);
+    api.get_role_denied = true;
+    let v = serde_json::to_value(run(&api)).unwrap();
+    // Probed because iam:GetRole is denied, which the workspace tier needs.
+    assert_eq!(v["summary"], "insufficient");
+    assert!(v["tiers"][0]["results"][0]
+        .as_object()
+        .unwrap()
+        .contains_key("note"));
+    assert_eq!(v["tiers"][0]["tier"], "workspace_user");
+    assert!(v["method"]["probed"]["reason"].is_string(), "{v}");
+    assert!(["allowed", "denied", "unverified"]
+        .contains(&v["tiers"][0]["results"][0]["verdict"].as_str().unwrap()));
+}
+
+/// Tauri commands need a `Send` future.
+#[allow(dead_code)]
+fn check_permissions_is_send() {
+    fn assert_send<T: Send>(_: T) {}
+    fn with<A: PermissionApi>(api: &A, id: &CallerIdentity) {
+        assert_send(check_permissions(api, id, "r"));
+    }
+    let _ = with::<SdkPermissionApi>;
+}
+
+/// D8: CloudFormation left the policies, so nothing probes it either.
+#[test]
+fn no_probe_is_cloudformation() {
+    assert_eq!(Probe::ALL, ALL_PROBES);
+    for p in Probe::ALL {
+        assert!(!p.action().starts_with("cloudformation:"), "{p:?}");
+        assert_eq!(Probe::for_action(p.action()), Some(p));
+    }
+    assert_eq!(Probe::for_action("cloudformation:DescribeStacks"), None);
+}

app/src-tauri/src/aws/policy_eval.rs

@@ -0,0 +1,303 @@
+//! The test-only IAM evaluator the policy drift guards use (moved here from
+//! `policies.rs` so the Terraform-module tests can ask it too). It is
+//! deliberately small: the operators the shipped policies use and nothing
+//! else; an unknown operator fails the test rather than being ignored. It is
+//! not IAM -- `live_tests.rs` and the live runs are the proof.
+
+use serde_json::Value;
+
+use super::policies::{render, Check, ContextValue, Placeholders};
+
+pub(crate) const AT: Placeholders = Placeholders {
+    region: "us-west-2",
+    account: "111122223333",
+    principal: "arn:aws:iam::111122223333:role/aws-reserved/sso.amazonaws.com/us-west-2/AWSReservedSSO_Dev_0123456789abcdef",
+};
+pub(crate) const ME: &str = "AROAEXAMPLEME:alice@example.com";
+pub(crate) const SOMEONE_ELSE: &str = "AROAEXAMPLEOTHER:bob@example.com";
+
+/// What [`Request::resolve`] turns IAM's `${*}` into: a literal `*` in a
+/// pattern, which [`glob`] matches only against a `*`.
+const LITERAL_STAR: char = '\u{e000}';
+
+/// IAM wildcard match: `*` is any run of characters (including `:` and
+/// `/`), `?` is exactly one; [`LITERAL_STAR`] is a plain `*`.
+pub(crate) fn glob(pattern: &str, text: &str) -> bool {
+    let p: Vec<char> = pattern.chars().collect();
+    let t: Vec<char> = text.chars().collect();
+    let (mut pi, mut ti) = (0, 0);
+    let (mut star, mut mark) = (None, 0);
+    while ti < t.len() {
+        if pi < p.len()
+            && (p[pi] == '?' || p[pi] == t[ti] || (p[pi] == LITERAL_STAR && t[ti] == '*'))
+        {
+            pi += 1;
+            ti += 1;
+        } else if pi < p.len() && p[pi] == '*' {
+            star = Some(pi);
+            mark = ti;
+            pi += 1;
+        } else if let Some(s) = star {
+            pi = s + 1;
+            mark += 1;
+            ti = mark;
+        } else {
+            return false;
+        }
+    }
+    while pi < p.len() && p[pi] == '*' {
+        pi += 1;
+    }
+    pi == p.len()
+}
+
+pub(crate) fn parse(name: &str, json: &str) -> Value {
+    serde_json::from_str(json).unwrap_or_else(|e| panic!("{name} is not JSON: {e}"))
+}
+
+pub(crate) fn statements_of(doc: &Value) -> Vec<Value> {
+    doc["Statement"]
+        .as_array()
+        .expect("policy has no Statement array")
+        .clone()
+}
+
+pub(crate) fn effect(stmt: &Value) -> &str {
+    stmt["Effect"].as_str().unwrap_or("<no Effect>")
+}
+
+/// `Action` / `Resource` / condition values: a string or an array of them.
+pub(crate) fn strings(v: &Value) -> Vec<String> {
+    match v {
+        Value::String(s) => vec![s.clone()],
+        Value::Array(a) => a
+            .iter()
+            .map(|x| x.as_str().expect("expected a string").to_string())
+            .collect(),
+        other => panic!("expected a string or array, got {other}"),
+    }
+}
+
+pub(crate) fn actions(stmt: &Value) -> Vec<String> {
+    strings(&stmt["Action"])
+}
+
+pub(crate) fn resources(stmt: &Value) -> Vec<String> {
+    strings(&stmt["Resource"])
+}
+
+pub(crate) fn sid(stmt: &Value) -> &str {
+    stmt["Sid"].as_str().unwrap_or("<no Sid>")
+}
+
+pub(crate) fn rendered(check: &Check) -> String {
+    render(check.resource, &AT)
+}
+
+/// The request: who calls, and whose the resource / request tag is.
+#[derive(Clone, Copy)]
+pub(crate) struct Request<'a> {
+    pub check: &'a Check,
+    /// `${aws:userid}` of the caller.
+    pub caller: &'a str,
+    /// What `OwnerId` context entries carry.
+    pub owner: &'a str,
+}
+
+impl Request<'_> {
+    pub(crate) fn context_value(&self, key: &str) -> Option<String> {
+        self.context_values(key).into_iter().next()
+    }
+
+    /// All values of a (possibly multi-valued) key.
+    pub(crate) fn context_values(&self, key: &str) -> Vec<String> {
+        self.check
+            .context
+            .iter()
+            .filter(|(k, _)| *k == key)
+            .map(|(_, v)| match v {
+                ContextValue::OwnerId => self.owner.to_string(),
+                ContextValue::Literal(l) => render(l, &AT),
+            })
+            .collect()
+    }
+
+    /// Resolves `${…}` policy variables the way the simulator does: from
+    /// the request context. An unresolvable variable makes the string
+    /// match nothing (`None`).
+    pub(crate) fn resolve(&self, s: &str) -> Option<String> {
+        let mut out = String::new();
+        let mut rest = s;
+        while let Some(start) = rest.find("${") {
+            out.push_str(&rest[..start]);
+            let end = rest[start..].find('}').expect("unterminated ${") + start;
+            let name = &rest[start + 2..end];
+            let value = if name == "*" {
+                Some(LITERAL_STAR.to_string())
+            } else if name == "aws:userid" {
+                Some(self.caller.to_string())
+            } else {
+                self.context_value(name)
+            };
+            out.push_str(&value?);
+            rest = &rest[end + 1..];
+        }
+        out.push_str(rest);
+        Some(out)
+    }
+}
+
+/// Statements that name the action and one of whose resources matches
+/// the rendered resource.
+pub(crate) fn matching<'s>(stmts: &'s [Value], req: &Request) -> Vec<&'s Value> {
+    let resource = rendered(req.check);
+    stmts
+        .iter()
+        .filter(|s| actions(s).iter().any(|a| glob(a, req.check.action)))
+        .filter(|s| {
+            resources(s)
+                .iter()
+                .filter_map(|r| req.resolve(r))
+                .any(|r| glob(&r, &resource))
+        })
+        .collect()
+}
+
+/// A deliberately small IAM condition evaluator: the operators the
+/// shipped policies use, and nothing else (an unknown operator fails the
+/// test rather than being ignored).
+pub(crate) fn conditions_hold(stmt: &Value, req: &Request) -> bool {
+    let Some(cond) = stmt.get("Condition") else {
+        return true;
+    };
+    let cond = cond.as_object().expect("Condition is an object");
+    cond.iter().all(|(op, entries)| {
+        let entries = entries.as_object().expect("condition block is an object");
+        // ForAllValues: every value of the (multi-valued) key matches
+        // one of the policy's values. Vacuously true when the key is
+        // absent, which is why statements pair it with a required key.
+        if let Some(base) = op.strip_prefix("ForAllValues:") {
+            assert_eq!(
+                base,
+                "StringEquals",
+                "{}: unsupported ForAllValues operator",
+                sid(stmt)
+            );
+            return entries.iter().all(|(key, want)| {
+                let allowed: Vec<String> = strings(want)
+                    .iter()
+                    .filter_map(|p| req.resolve(p))
+                    .collect();
+                req.context_values(key).iter().all(|v| allowed.contains(v))
+            });
+        }
+        if op == "Null" {
+            return entries.iter().all(|(key, want)| {
+                let absent = req.context_value(key).is_none();
+                match want.as_str() {
+                    Some("true") => absent,
+                    Some("false") => !absent,
+                    _ => panic!("{}: Null takes \"true\" or \"false\"", sid(stmt)),
+                }
+            });
+        }
+        let (base, if_exists) = match op.strip_suffix("IfExists") {
+            Some(b) => (b, true),
+            None => (op.as_str(), false),
+        };
+        // A negated operator holds when the key is absent, and
+        // otherwise when no value matches.
+        let (matches, negated): (fn(&str, &str) -> bool, bool) = match base {
+            "StringEquals" => (|p, v| p == v, false),
+            "StringLike" | "ArnLike" => (glob, false),
+            "StringNotEquals" => (|p, v| p == v, true),
+            "StringNotLike" => (glob, true),
+            other => panic!("{}: unsupported condition operator {other}", sid(stmt)),
+        };
+        entries
+            .iter()
+            .all(|(key, want)| match req.context_value(key) {
+                None => if_exists || negated,
+                Some(value) => {
+                    let any = strings(want)
+                        .iter()
+                        .filter_map(|p| req.resolve(p))
+                        .any(|p| matches(&p, &value));
+                    any != negated
+                }
+            })
+    })
+}
+
+/// Allowed by some Allow and by no Deny among `stmts`.
+pub(crate) fn evaluate_in(stmts: &[Value], req: Request) -> bool {
+    let applies = |s: &&Value| conditions_hold(s, &req);
+    let allowed = matching(stmts, &req)
+        .into_iter()
+        .filter(|s| effect(s) == "Allow")
+        .any(|s| applies(&s));
+    let denied = matching(stmts, &req)
+        .into_iter()
+        .filter(|s| effect(s) == "Deny")
+        .any(|s| applies(&s));
+    allowed && !denied
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use ContextValue::Literal;
+
+    #[test]
+    fn glob_behaves_like_iam_wildcards() {
+        assert!(glob("ecs:Describe*", "ecs:DescribeClusters"));
+        assert!(!glob("ecs:Describe*", "ecs:ListClusters"));
+        assert!(glob(
+            "arn:aws:ecs:*:*:task/triple-c-*/*",
+            "arn:aws:ecs:us-west-2:1:task/triple-c-x/abc"
+        ));
+        assert!(!glob(
+            "arn:aws:ecs:*:*:task/triple-c-*/*",
+            "arn:aws:ecs:us-west-2:1:task/other/abc"
+        ));
+        assert!(glob("a?c", "abc"));
+        assert!(!glob("a?c", "ac"));
+        // `${*}` (resolved to LITERAL_STAR) matches only a real `*`.
+        let literal = format!("arn:aws:ec2:*:*:{LITERAL_STAR}/{LITERAL_STAR}");
+        assert!(glob(&literal, "arn:aws:ec2:us-west-2:1:*/*"));
+        assert!(!glob(&literal, "arn:aws:ec2:us-west-2:1:elastic-ip/eipalloc-1"));
+    }
+
+    #[test]
+    fn for_all_values_is_vacuous_on_an_absent_key() {
+        let stmt: Value = serde_json::json!({
+            "Sid": "T", "Effect": "Allow", "Action": "x:Y", "Resource": "*",
+            "Condition": { "ForAllValues:StringEquals": { "aws:TagKeys": ["a", "b"] } }
+        });
+        let check = |context| Check {
+            action: "x:Y",
+            resource: "*",
+            context,
+            write: true,
+        };
+        let holds = |c: &Check| {
+            conditions_hold(
+                &stmt,
+                &Request {
+                    check: c,
+                    caller: ME,
+                    owner: ME,
+                },
+            )
+        };
+        assert!(holds(&check(&[])));
+        assert!(holds(&check(&[
+            ("aws:TagKeys", Literal("a")),
+            ("aws:TagKeys", Literal("b"))
+        ])));
+        assert!(!holds(&check(&[
+            ("aws:TagKeys", Literal("a")),
+            ("aws:TagKeys", Literal("c"))
+        ])));
+    }
+}

app/src-tauri/src/aws/tofu_modules.rs

@@ -0,0 +1,251 @@
+//! The OpenTofu modules Triple-C ships (`aws/terraform/*` at the repo root)
+//! and the names the modules and the app agree on.
+//!
+//! Every name a module or a phase-4 command uses — environment, parameter,
+//! owner key, per-user roles, state bucket and keys — is built here and
+//! nowhere else. The tests parse the shipped HCL and pin it to these
+//! constants: versions, default tags, the record's fields, no inbound access
+//! and no endpoint overrides.
+
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+use sha2::{Digest, Sha256};
+
+use crate::models::host_connection::validate_supported_region;
+
+/// `locals.template_version` (and the `triple-c:template-version` default
+/// tag) of `aws/terraform/environment`.
+pub const ENVIRONMENT_MODULE_VERSION: u32 = 1;
+/// The same for the user-onboarding module.
+#[allow(dead_code)] // the onboarding module's version; checked against its HCL by a test
+pub const ONBOARD_MODULE_VERSION: u32 = 1;
+/// The permissions boundary every module-created role carries (no path).
+/// Equal to [`super::policies::PERMISSIONS_BOUNDARY_NAME`]; a test checks it.
+pub const BOUNDARY_POLICY_NAME: &str = "triple-c-permissions-boundary";
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)]
+#[serde(rename_all = "snake_case")]
+pub enum ModuleKind {
+    Environment,
+    UserOnboard,
+    PermissionsBoundary,
+}
+
+macro_rules! module {
+    ($dir:literal: $($file:literal),+ $(,)?) => {
+        &[$(($file, include_str!(concat!("../../../../aws/terraform/", $dir, "/", $file)))),+]
+    };
+}
+
+const ENVIRONMENT_FILES: &[(&str, &str)] = module!("environment":
+    "versions.tf",
+    "variables.tf",
+    "main.tf",
+    "network.tf",
+    "outputs.tf",
+    ".terraform.lock.hcl",
+);
+
+const USER_ONBOARD_FILES: &[(&str, &str)] = module!("user-onboard":
+    "versions.tf",
+    "variables.tf",
+    "main.tf",
+    "iam.tf",
+    "efs.tf",
+    "outputs.tf",
+    ".terraform.lock.hcl",
+);
+
+const PERMISSIONS_BOUNDARY_FILES: &[(&str, &str)] = module!("permissions-boundary":
+    "versions.tf",
+    "variables.tf",
+    "main.tf",
+    "outputs.tf",
+    ".terraform.lock.hcl",
+);
+
+/// The module's files as (file name relative to the module directory,
+/// contents), lock file included, for writing into a work or bundle folder.
+pub fn module_files(kind: ModuleKind) -> &'static [(&'static str, &'static str)] {
+    match kind {
+        ModuleKind::Environment => ENVIRONMENT_FILES,
+        ModuleKind::UserOnboard => USER_ONBOARD_FILES,
+        ModuleKind::PermissionsBoundary => PERMISSIONS_BOUNDARY_FILES,
+    }
+}
+
+/// `^[a-z][a-z0-9-]{0,19}$`, not ending in `-`, with no `--` — the same rule
+/// as the module's `environment_name` validation.
+pub fn validate_environment_name(name: &str) -> Result<String, String> {
+    let b = name.as_bytes();
+    let ok = !b.is_empty()
+        && b.len() <= 20
+        && b[0].is_ascii_lowercase()
+        && b.iter()
+            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || *c == b'-')
+        && !name.ends_with('-')
+        && !name.contains("--");
+    if ok {
+        Ok(name.to_string())
+    } else {
+        Err(format!(
+            "\"{}\" is not a valid environment name: use 1 to 20 lowercase letters, digits and \
+             single hyphens, starting with a letter and not ending in a hyphen",
+            name.escape_debug()
+        ))
+    }
+}
+
+/// The SSM parameter holding an environment's record.
+pub fn environment_parameter_name(env: &str) -> String {
+    format!("/triple-c/environments/{env}")
+}
+
+/// The first 12 hex characters of `sha256("<region>:<aws:userid>")`. A
+/// `UserId` holds a `:`, which IAM role names reject, so per-user names use
+/// this instead. The region is part of it because role names are
+/// account-global while environments are regional: the same user in the same
+/// environment name in two regions gets two sets of roles.
+pub fn owner_key(region: &str, user_id: &str) -> String {
+    Sha256::digest(format!("{region}:{user_id}").as_bytes())
+        .iter()
+        .take(6)
+        .map(|b| format!("{b:02x}"))
+        .collect()
+}
+
+/// A user's (task role, execution role) names. At most 47 characters.
+pub fn user_role_names(env: &str, owner_key: &str) -> (String, String) {
+    (
+        format!("triple-c-{env}-{owner_key}-task"),
+        format!("triple-c-{env}-{owner_key}-exec"),
+    )
+}
+
+/// The per-account, per-region state bucket.
+pub fn state_bucket_name(account: &str, region: &str) -> String {
+    format!("triple-c-tfstate-{account}-{region}")
+}
+
+/// One deployment, i.e. one state object in the bucket (D9).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Deployment<'a> {
+    /// The environment module for this environment name.
+    Environment(&'a str),
+    /// A user's onboarding module in an environment.
+    User { env: &'a str, owner_key: &'a str },
+    /// The account's permissions-boundary module.
+    Boundary,
+}
+
+/// A deployment's state object in [`state_bucket_name`] (D9); the lock is the
+/// same key plus `.tflock`.
+pub fn state_key(d: Deployment) -> String {
+    match d {
+        Deployment::Environment(env) => format!("environments/{env}/terraform.tfstate"),
+        Deployment::User { env, owner_key } => {
+            format!("users/{env}/{owner_key}/terraform.tfstate")
+        }
+        Deployment::Boundary => "boundary/terraform.tfstate".to_string(),
+    }
+}
+
+/// How an environment's tasks reach the network (D4).
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(tag = "mode", rename_all = "kebab-case")]
+pub enum NetworkChoice {
+    /// A new VPC with two public subnets; tasks get a public IP. No NAT, $0.
+    Public,
+    /// A new VPC with private subnets behind one NAT gateway (~$33/month).
+    PrivateNat,
+    /// The user's own VPC and exactly two subnets.
+    Existing {
+        vpc_id: String,
+        subnet_ids: Vec<String>,
+        assign_public_ip: bool,
+    },
+}
+
+/// `vpc-` / `subnet-` followed by 8 or 17 lowercase hex characters.
+fn is_aws_id(id: &str, prefix: &str) -> bool {
+    id.strip_prefix(prefix).is_some_and(|hex| {
+        (hex.len() == 8 || hex.len() == 17)
+            && hex.bytes().all(|c| matches!(c, b'0'..=b'9' | b'a'..=b'f'))
+    })
+}
+
+/// The environment module's `terraform.tfvars.json`. Applies the same rules
+/// as the module's variable validations, so a bad value fails here first.
+pub fn environment_vars(
+    env: &str,
+    region: &str,
+    network: &NetworkChoice,
+) -> Result<serde_json::Value, String> {
+    let env = validate_environment_name(env)?;
+    let region = validate_supported_region(region)?;
+    let (mode, vpc_id, subnet_ids, assign_public_ip) = match network {
+        NetworkChoice::Public => ("public", String::new(), Vec::new(), false),
+        NetworkChoice::PrivateNat => ("private-nat", String::new(), Vec::new(), false),
+        NetworkChoice::Existing {
+            vpc_id,
+            subnet_ids,
+            assign_public_ip,
+        } => {
+            if !is_aws_id(vpc_id, "vpc-") {
+                return Err(format!("\"{}\" is not a VPC id", vpc_id.escape_debug()));
+            }
+            if subnet_ids.len() != 2 {
+                return Err(format!(
+                    "An existing network needs exactly 2 subnets (in different availability \
+                     zones), not {}",
+                    subnet_ids.len()
+                ));
+            }
+            if let Some(bad) = subnet_ids.iter().find(|s| !is_aws_id(s, "subnet-")) {
+                return Err(format!("\"{}\" is not a subnet id", bad.escape_debug()));
+            }
+            if subnet_ids[0] == subnet_ids[1] {
+                return Err("The two subnets must be different".into());
+            }
+            (
+                "existing",
+                vpc_id.clone(),
+                subnet_ids.clone(),
+                *assign_public_ip,
+            )
+        }
+    };
+    Ok(json!({
+        "environment_name": env,
+        "region": region,
+        "network_mode": mode,
+        "vpc_id": vpc_id,
+        "subnet_ids": subnet_ids,
+        "assign_public_ip": assign_public_ip,
+    }))
+}
+
+/// The onboarding module's `terraform.tfvars.json` for the user whose
+/// `aws:userid` is `owner_id`. Bedrock stays on the workspace user's own
+/// credentials unless a later setting opts the task role in.
+pub fn onboarding_vars(env: &str, region: &str, owner_id: &str) -> serde_json::Value {
+    json!({
+        "environment_name": env,
+        "region": region,
+        "owner_id": owner_id,
+        "owner_key": owner_key(region, owner_id),
+        "bedrock_on_task_role": false,
+    })
+}
+
+/// The boundary module's `terraform.tfvars.json`: the shipped boundary
+/// document itself, so the module holds no second copy.
+pub fn boundary_vars(region: &str) -> serde_json::Value {
+    json!({
+        "region": region,
+        "policy_json": super::policies::permissions_boundary_json(),
+    })
+}
+
+#[cfg(test)]
+mod tests;

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

@@ -0,0 +1,454 @@
+//! 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::host::ContainerTarget;
+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.
+///
+/// Either way the choice is persisted, so it survives an app restart. This is
+/// the only caller allowed to write `false`: every other path to
+/// [`BrowserViewManager::stop`](crate::browser_view::BrowserViewManager::stop)
+/// is a teardown rather than the user changing their mind. Enabling persists
+/// inside `start`, which is the single funnel for it.
+#[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 {
+        // Persist first, then tear down: the supervisor's own teardown emit
+        // reads this flag back out of the store, and reading it mid-stop would
+        // announce a view that is going away as still enabled.
+        //
+        // But the write's outcome is a *value*, not a branch. A `?` here meant
+        // that a store with no such project record returned early and
+        // `manager().stop()` never ran, leaving the supervisor, the proxy and
+        // the host port up for a project that, as far as the user is concerned,
+        // just had its view switched off. That state is not hypothetical while
+        // a session is live — the supervisor's own `store.get()` check in
+        // [`crate::browser_view`] exists because a record can go away
+        // underneath it — and before the flag was persisted at all, turning the
+        // view off always tore the session down.
+        let persisted = state
+            .projects_store
+            .set_browser_view_enabled(&project_id, false);
+        // Awaits the supervisor, so the host port is released before we return.
+        //
+        // A failed write is still reported rather than logged and swallowed.
+        // The resources are gone either way by this point, so surfacing it
+        // costs nothing that matters, and the failure it describes is one the
+        // user needs: the stored flag still says *enabled*, so the view comes
+        // back by itself on the next launch. Returning `Ok` would be a claim
+        // about persistence that isn't true.
+        tear_down_then_report(persisted, manager().stop(&project_id)).await?;
+        return Ok(manager().status(&project_id, false).await);
+    }
+
+    let container = running_container(&state, &project_id, "opening the browser view").await?;
+
+    manager()
+        .start(
+            project_id,
+            container,
+            app_handle,
+            state.projects_store.clone(),
+        )
+        .await
+}
+
+/// Await `teardown`, then report `persisted`.
+///
+/// Trivial on purpose, and split out for one reason: it is the whole rule the
+/// disable path of [`set_browser_view_enabled`] has to obey — the teardown is
+/// unconditional, and a failed persist surfaces only after it has run — and as
+/// a free function that rule can be tested without a live `AppState`.
+async fn tear_down_then_report(
+    persisted: Result<(), String>,
+    teardown: impl std::future::Future<Output = ()>,
+) -> Result<(), String> {
+    teardown.await;
+    persisted
+}
+
+/// Current status. Cheap: the session map in this process plus the stored flag,
+/// never the container.
+///
+/// The two are independent on purpose — this is what the pane reads on mount,
+/// and after an app restart the honest answer is "enabled, nothing running".
+#[tauri::command]
+pub async fn get_browser_view_status(
+    project_id: String,
+    state: State<'_, AppState>,
+) -> Result<BrowserViewStatus, String> {
+    Ok(manager().status(&project_id, enabled_for(&state, &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 = running_container(&state, &project_id, "checking for Playwright").await?;
+    crate::browser_view::detect::detect(&container).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 = running_container(&state, &project_id, "installing Playwright").await?;
+    install::install_packages(&app_handle, &project_id, &container).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 = running_container(&state, &project_id, "installing a browser").await?;
+    install::install_browser(&app_handle, &project_id, &container, 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, enabled_for(&state, &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 = 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).await?;
+    let opened = page::open(
+        &app_handle,
+        &project_id,
+        &container,
+        &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, enabled_for(&state, &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,
+                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, enabled_for(&state, &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 = running_container(&state, &project_id, "resizing the page").await?;
+    page::set_viewport(&container, 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) = running_container(&state, &project_id, "reading the page").await else {
+        return Ok(page::PageState::default());
+    };
+    Ok(page::state(&container).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 = running_container(&state, &project_id, "closing the page").await?;
+    page::close(&container).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 = running_container(&state, &project_id, "matching the window").await?;
+    page::set_viewport(&container, 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 stored browser-view opt-in.
+///
+/// The manager holds no copy of this — see
+/// [`BrowserViewManager`](crate::browser_view::BrowserViewManager) — so every
+/// status call reads it here, the way `get_auth_bridge_status` does. A project
+/// that has gone away reads as off, which is the only answer that can be given
+/// about a record that no longer exists.
+fn enabled_for(state: &State<'_, AppState>, project_id: &str) -> bool {
+    state
+        .projects_store
+        .get(project_id)
+        .is_some_and(|p| p.browser_view_enabled)
+}
+
+/// 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<ContainerTarget, String> {
+    let project = state
+        .projects_store
+        .get(project_id)
+        .ok_or_else(|| format!("Project {} not found", project_id))?;
+
+    let Some(container) = ContainerTarget::for_project(&project) else {
+        return Err(format!(
+            "This project has no container yet. Start it before {}.",
+            action
+        ));
+    };
+    if !container.is_running().await.unwrap_or(false) {
+        return Err(format!(
+            "The container for “{}” isn't running. Start it before {}.",
+            project.name, action
+        ));
+    }
+    Ok(container)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicBool, Ordering};
+
+    /// The regression: turning the view off must not leave the supervisor, the
+    /// proxy and the host port running just because the project record could
+    /// not be written — which is exactly what a missing record did.
+    #[tokio::test]
+    async fn a_failed_persist_does_not_skip_the_teardown() {
+        let torn_down = AtomicBool::new(false);
+        let result = tear_down_then_report(Err("Project x not found".to_string()), async {
+            torn_down.store(true, Ordering::SeqCst);
+        })
+        .await;
+
+        assert!(
+            torn_down.load(Ordering::SeqCst),
+            "the session must be torn down even when the store write failed"
+        );
+        assert_eq!(
+            result.err().as_deref(),
+            Some("Project x not found"),
+            "and the write failure must still reach the caller, not be swallowed"
+        );
+    }
+
+    #[tokio::test]
+    async fn a_successful_persist_reports_success_after_the_teardown() {
+        let torn_down = AtomicBool::new(false);
+        let result = tear_down_then_report(Ok(()), async {
+            torn_down.store(true, Ordering::SeqCst);
+        })
+        .await;
+
+        assert!(torn_down.load(Ordering::SeqCst));
+        assert!(result.is_ok());
+    }
+}

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

@@ -0,0 +1,700 @@
+//! 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::host::ContainerTarget;
+
+/// 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: &ContainerTarget) -> Result<PlaywrightDetection, String> {
+    let output = container
+        .exec_oneshot(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,977 @@
+//! 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. The opt-in itself is
+//! [`Project::browser_view_enabled`](crate::models::Project), persisted like
+//! `auth_bridge_enabled` and read from the store on demand rather than cached
+//! here — so the pane comes back the way it was left. What does *not* persist
+//! is the session: nothing starts a viewer on app start, so a project left
+//! enabled reports `enabled: true` with a state of `Off` until the pane asks
+//! for one. That is deliberate, and the reason the flag and the session are
+//! separate ideas — see [`BrowserViewManager::status`].
+//!
+//! 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)` → persist `false`, then [`BrowserViewManager::stop`] |
+//! | Container stopped, by the UI or otherwise | supervisor's `is_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 — and since the
+//! opt-in is now durable, the restarted app says `enabled` with nothing running,
+//! which is exactly the state that invites the user to press the button that
+//! reclaims it. Nothing reclaims it on its own, because nothing auto-starts.
+
+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::host::ContainerTarget;
+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, read from the persisted project record. Off by
+    /// default, and true without a `Running` state whenever the view is turned
+    /// on but has nothing up — a stopped container, or an app that has just
+    /// restarted and does not auto-start viewers.
+    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>>>;
+
+/// Live sessions, and nothing else.
+///
+/// The per-project opt-in deliberately is **not** a field here. It lives on
+/// the project record as
+/// [`browser_view_enabled`](crate::models::Project::browser_view_enabled) and
+/// is read from [`ProjectsStore`] at each use, exactly as
+/// [`crate::auth_bridge::AuthBridgeManager`] treats `auth_bridge_enabled`:
+/// one copy, durable across a restart, and impossible to get out of step with
+/// what the Config tab shows. A cached copy here was the previous design and
+/// its only observable behaviour was forgetting the user's choice on every
+/// app start.
+#[derive(Default)]
+pub struct BrowserViewManager {
+    sessions: SessionMap,
+    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 {
+    /// Current status without touching the container.
+    ///
+    /// `enabled` is passed in rather than looked up, the way
+    /// [`crate::auth_bridge::AuthBridgeManager::status`] takes it: the flag is
+    /// the caller's to read from the store, and keeping it out of here is what
+    /// stops a second copy of it appearing. A project whose view is enabled but
+    /// whose container is stopped — or whose app has just restarted — reports
+    /// `enabled: true` with a state of `Off`, which is the honest answer.
+    pub async fn status(&self, project_id: &str, enabled: bool) -> BrowserViewStatus {
+        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.
+    ///
+    /// This is the single funnel for turning the view **on**, so it is also
+    /// where the durable flag is written — both call sites (the toggle and
+    /// `open_page_in_container_browser`, which opens a page and then shows it)
+    /// mean "on", and neither can forget. The **off** direction is not
+    /// symmetric and must not be: [`Self::stop`] is reached by teardown paths
+    /// that are not the user changing their mind, so the command owns that
+    /// write. See [`Self::stop`].
+    pub async fn start(
+        &self,
+        project_id: String,
+        container: ContainerTarget,
+        app: AppHandle,
+        store: Arc<ProjectsStore>,
+    ) -> Result<BrowserViewStatus, String> {
+        store.set_browser_view_enabled(&project_id, true)?;
+
+        // 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, true).await);
+        }
+
+        let detection = detect::detect(&container).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, &cli_entry).await;
+
+        let (container_port, entry_path) = start_viewer(&container, &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.clone(),
+            container_port,
+            PortFamily::V4,
+            token.clone(),
+        )
+        .await
+        {
+            Ok(p) => p,
+            Err(e) => {
+                let _ = kill_dashboard(&container, &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,
+            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, true).await;
+        emit(&app, &project_id, &status);
+        Ok(status)
+    }
+
+    /// Stop one project's view and wait until its host port has been released.
+    ///
+    /// Tears the *session* down and deliberately leaves the durable flag alone.
+    /// Most callers are not the user turning the feature off — a migration
+    /// removes the container out from under a running view
+    /// (`migration_commands`), and the container can stop for any other reason
+    /// — and persisting `false` for those would quietly opt the project out of
+    /// a feature it never asked to lose. `set_browser_view_enabled(false)` is
+    /// the one caller that means it, and it writes the flag itself first.
+    pub async fn stop(&self, project_id: &str) {
+        // 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: ContainerTarget,
+    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 !container.is_running().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, 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, &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);
+
+    // Straight from the store, like the auth bridge's own teardown emit: the
+    // session is over, but the project may well still be opted in — a stopped
+    // container is not a changed mind, and the pane has to show the difference.
+    let enabled = store
+        .get(&project_id)
+        .is_some_and(|p| p.browser_view_enabled);
+    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: &ContainerTarget,
+    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
+    );
+    container
+        .exec_oneshot(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: &ContainerTarget, cli_entry: &str) -> Result<String, String> {
+    let script = format!(
+        "{}; NO_UPDATE_NOTIFIER=1 node {} show --kill",
+        WORKDIR_PREFIX,
+        shell_quote(cli_entry)
+    );
+    container
+        .exec_oneshot(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: &ContainerTarget) -> String {
+    container
+        .exec_oneshot(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: &ContainerTarget,
+    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, &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, 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, port).await {
+            Ok(path) => return Ok((port, path)),
+            Err(e) => {
+                let log = read_viewer_log(container).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, 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: &ContainerTarget, tried: &[u16]) -> Result<u16, String> {
+    let text = container
+        .exec_oneshot(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: &ContainerTarget, port: u16) -> Result<String, String> {
+    let deadline = tokio::time::Instant::now() + READY_TIMEOUT;
+    loop {
+        let last = match probe_entry_path(container, 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: &ContainerTarget, 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,
+        container.exec_oneshot(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());
+    }
+
+    #[tokio::test]
+    async fn the_opt_in_and_the_live_session_are_separate_answers() {
+        let manager = BrowserViewManager::default();
+
+        // Exactly what the pane reads on mount after an app restart of a
+        // project that was left enabled: the durable flag says on, and nothing
+        // auto-starts, so the state is honestly `Off`. The old in-memory flag
+        // could not express this — it came back `false` and the pane silently
+        // showed the feature as never having been turned on.
+        let status = manager.status("p1", true).await;
+        assert!(status.enabled);
+        assert_eq!(status.state, BrowserViewState::Off);
+        assert!(status.url.is_none());
+
+        // The flag belongs to the caller, read from the store. The manager
+        // keeps no copy, so it has nothing to contradict it with.
+        assert!(!manager.status("p1", false).await.enabled);
+    }
+
+    #[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::host::ContainerTarget;
+
+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: &ContainerTarget,
+    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).await.ready {
+        emit_progress(app, project_id, "Navigating the container's browser…");
+        set_viewport(container, viewport).await?;
+        navigate(container, url).await?;
+        if let Some(state) = wait_for_url(container, url).await {
+            return Ok(state);
+        }
+        // It stopped answering; fall through and start a fresh one.
+    }
+
+    close(container).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
+    );
+    container
+        .exec_oneshot_as(
+            "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).await
+}
+
+/// Resize the open page. Cheap enough to call from a window-resize handler.
+pub async fn set_viewport(container: &ContainerTarget, viewport: Viewport) -> Result<(), String> {
+    write_control(
+        container,
+        serde_json::json!({ "viewport": viewport }).to_string(),
+    )
+    .await
+}
+
+/// Navigate the open page without relaunching the browser.
+pub async fn navigate(container: &ContainerTarget, url: &str) -> Result<(), String> {
+    write_control(container, 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: &ContainerTarget) {
+    let _ = write_control(container, 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: &ContainerTarget) -> PageState {
+    let script = format!(
+        "try{{process.stdout.write(require('fs').readFileSync('{}','utf8'));}}catch(e){{}}",
+        STATE_PATH
+    );
+    let Ok((out, _)) = container
+        .exec_oneshot_as(
+            "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: &ContainerTarget, json: String) -> Result<(), String> {
+    let script = format!(
+        "require('fs').writeFileSync('{}',process.argv[1]);",
+        CONTROL_PATH
+    );
+    container
+        .exec_oneshot_as(
+            "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: &ContainerTarget, url: &str) -> Option<PageState> {
+    let deadline = std::time::Instant::now() + REUSE_TIMEOUT;
+    loop {
+        let state = state(container).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: &ContainerTarget) -> Result<PageState, String> {
+    let deadline = std::time::Instant::now() + READY_TIMEOUT;
+    loop {
+        let state = state(container).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) = state
+            .projects_store
+            .get(&project_id)
+            .and_then(|p| crate::host::ContainerTarget::for_project(&p))
+        else {
+            return;
+        };
+        if let Err(e) = super::page::set_viewport(
+            &container,
+            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,794 @@
+//! 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;
+use crate::host::ContainerTarget;
+
+/// 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`'s `container_port`.
+    pub async fn bind(
+        container: ContainerTarget,
+        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,
+                        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: ContainerTarget,
+    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.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: ContainerTarget,
+    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, 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/command_census.rs

@@ -0,0 +1,581 @@
+//! The command census shared by `build.rs` and the `cargo test` suite.
+//!
+//! `build.rs` pulls this file in with `#[path = "src/command_census.rs"]` and `lib.rs` with
+//! `#[cfg(test)] mod command_census;`, so the parser that decides what the Tauri `AppManifest`
+//! declares is the parser the tests exercise, and the rules that decide whether the build
+//! passes have unit tests. Nothing here may reference the crate: only `std` and `serde_json`
+//! (a dependency of both the crate and the build script).
+//!
+//! Spec: `docs/superpowers/specs/2026-09-22-app-manifest-lockdown-design.md` §3.2.
+
+use std::collections::{BTreeMap, BTreeSet};
+
+/// The command names inside `generate_handler![ … ])` in `lib.rs`, in registration order,
+/// duplicates kept (the caller decides whether that is an error). `None` if the block is
+/// missing or unterminated.
+///
+/// Comma-split, not line-split: `// Docker` style comments are stripped from every line first
+/// (a whole-line comment strips to nothing; a trailing one leaves the code before it), and the
+/// *cleaned* text is then split on `,` so each grant is its own item regardless of how many
+/// share a line. A line-split version of this parser shipped first and used
+/// `rsplit("::").next()` once *per line*: two commands on one line (`a::x, b::y,`) collapsed to
+/// a single item, silently dropping `a::x` — a denied command at runtime with nothing flagging
+/// it. Comma-splitting fixes that because it no longer assumes one item per line.
+pub fn registered_commands(lib_rs: &str) -> Option<Vec<String>> {
+    let (_, rest) = lib_rs.split_once("generate_handler![")?;
+    let (inside, _) = rest.split_once("])")?;
+    let cleaned: String = inside
+        .lines()
+        // Strip a trailing `//` comment (and a whole-line one, which strips to "").
+        .map(|l| l.split("//").next().unwrap_or(""))
+        .collect::<Vec<_>>()
+        .join("\n");
+    Some(
+        cleaned
+            .split(',')
+            .map(str::trim)
+            .filter(|s| !s.is_empty())
+            .filter_map(|s| {
+                // `a::b::name` → `name`; a bare `name` (no `::`) is its own last segment.
+                s.rsplit("::").next().map(|n| n.trim().to_string())
+            })
+            .filter(|n| !n.is_empty())
+            .collect(),
+    )
+}
+
+/// `viewer_read_file` → `allow-viewer-read-file`. tauri-utils 2.9.0 (`acl/build.rs:290`)
+/// replaces only `_`; permission identifiers may not contain `_`, but the command name inside
+/// the generated permission stays snake_case.
+pub fn allow_permission(command: &str) -> String {
+    format!("allow-{}", command.replace('_', "-"))
+}
+
+/// The `windows` list of the one capability file that may grant `command`. A command that
+/// must be callable from both windows is a design change: make it here, visibly, rather than
+/// by widening a capability file.
+pub fn expected_windows(command: &str) -> &'static [&'static str] {
+    if command.starts_with("viewer_") {
+        &["file-viewer-*"]
+    } else {
+        &["main"]
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CapabilityFile {
+    pub name: String,
+    pub windows: Vec<String>,
+    pub bare: Vec<String>,
+}
+
+/// One `capabilities/*.json`, reduced to what the census checks. Plugin and core grants
+/// (anything with a `:`) are not this module's business; the exact-set tests in `lib.rs` and
+/// `file_viewer/mod.rs` pin those.
+pub fn capability_file(name: &str, json: &str) -> Result<CapabilityFile, String> {
+    let value: serde_json::Value =
+        serde_json::from_str(json).map_err(|e| format!("{name}: not valid JSON: {e}"))?;
+    // `webviews` would extend the grants to webviews by label (the browser-view pop-out is
+    // meant to be in no capability), and `remote` would extend them to a remote origin. The
+    // census reasons about `windows` only, so either key is refused rather than half-checked.
+    for key in ["webviews", "remote"] {
+        if value.get(key).is_some() {
+            return Err(format!(
+                "{name}: `{key}` is not allowed; capabilities here are scoped by `windows` only"
+            ));
+        }
+    }
+    let windows = value["windows"]
+        .as_array()
+        .ok_or_else(|| format!("{name}: `windows` must be an array"))?
+        .iter()
+        .map(|w| {
+            w.as_str()
+                .map(str::to_string)
+                .ok_or_else(|| format!("{name}: `windows` entries must be strings"))
+        })
+        .collect::<Result<Vec<_>, _>>()?;
+    let mut bare = Vec::new();
+    for grant in value["permissions"]
+        .as_array()
+        .ok_or_else(|| format!("{name}: `permissions` must be an array"))?
+    {
+        let id = match grant {
+            serde_json::Value::String(s) => s.as_str(),
+            serde_json::Value::Object(o) => o
+                .get("identifier")
+                .and_then(|i| i.as_str())
+                .ok_or_else(|| format!("{name}: a scoped grant needs a string `identifier`"))?,
+            _ => return Err(format!("{name}: a grant is a string or an object")),
+        };
+        if !id.contains(':') {
+            bare.push(id.to_string());
+        }
+    }
+    Ok(CapabilityFile { name: name.to_string(), windows, bare })
+}
+
+/// Why an entry directly under `capabilities/` cannot be a capability the census reads, or
+/// `None` if it is one (a top-level `*.json` file). tauri-build loads `capabilities/**/*` with
+/// the extensions `json`, `toml` and (with a feature) `json5`, subdirectories included; the
+/// census reads only top-level JSON, so anything else tauri might load is refused rather than
+/// left for tauri to grant from unchecked. OS and editor junk, which tauri never loads, is the
+/// caller's to skip first (see [`is_os_junk`]).
+pub fn stray_capability_entry(name: &str, is_file: bool) -> Option<String> {
+    if !is_file {
+        return Some(format!(
+            "capabilities/{name} is not a regular file; tauri loads capabilities from \
+             subdirectories too, so every capability must be a top-level capabilities/*.json"
+        ));
+    }
+    if name.ends_with(".json") {
+        return None;
+    }
+    Some(format!(
+        "capabilities/{name} is not a .json file; tauri may load it (it reads .toml and .json5 \
+         too) but the census cannot check it, so every capability must be a top-level \
+         capabilities/*.json"
+    ))
+}
+
+/// Files the OS or an editor drops next to real ones (`.DS_Store`, `Thumbs.db`, `desktop.ini`,
+/// Vim swap files, `name~` backups). tauri-build loads only `json`/`toml`/`json5` from
+/// `capabilities/` and `permissions/`, so a junk name with one of those extensions (an Emacs
+/// `.#default.json` lock, a macOS `._default.json`) is *not* junk: tauri would try to load it,
+/// and the caller must refuse it.
+pub fn is_os_junk(name: &str) -> bool {
+    let loadable = [".json", ".json5", ".toml"].iter().any(|e| name.ends_with(e));
+    !loadable
+        && (matches!(name, ".DS_Store" | "Thumbs.db" | "desktop.ini")
+            || name.ends_with(".swp")
+            || name.ends_with(".swo")
+            || name.ends_with('~'))
+}
+
+/// Which files next to `Cargo.toml` tauri reads as its config: `tauri.conf.json[5]`,
+/// `Tauri.toml` and the per-platform `tauri.<platform>.conf.json[5]` / `Tauri.<platform>.toml`
+/// (tauri-utils `config/parse.rs`). `Some(true)` = JSON the census can read, `Some(false)` = a
+/// format it cannot (JSON5/TOML), `None` = not a tauri config file.
+pub fn tauri_config_file(name: &str) -> Option<bool> {
+    if name.starts_with("tauri.") && name.ends_with(".conf.json") {
+        Some(true)
+    } else if (name.starts_with("tauri.") && name.ends_with(".conf.json5"))
+        || (name.starts_with("Tauri.") && name.ends_with(".toml"))
+    {
+        Some(false)
+    } else {
+        None
+    }
+}
+
+/// A problem with a tauri config (a `tauri*.conf.json` file, or the `TAURI_CONFIG` JSON that
+/// tauri-build merges over it), or `None`. `app.security.capabilities` is refused whenever it
+/// is non-empty: an inline object is a capability the census never sees, and a list of
+/// identifiers switches every *other* capability file off, which the census also assumes is
+/// not happening.
+pub fn tauri_config_problem(name: &str, json: &str) -> Option<String> {
+    let value: serde_json::Value = match serde_json::from_str(json) {
+        Ok(v) => v,
+        Err(e) => return Some(format!("{name}: not valid JSON: {e}")),
+    };
+    match value.pointer("/app/security/capabilities") {
+        None | Some(serde_json::Value::Null) => None,
+        Some(serde_json::Value::Array(a)) if a.is_empty() => None,
+        Some(_) => Some(format!(
+            "{name}: app.security.capabilities is not allowed; every capability lives in a \
+             top-level capabilities/*.json file, where the census checks it"
+        )),
+    }
+}
+
+/// Everything that must hold between the handler list and the capability files. Returns every
+/// violation rather than the first, so a batch of forgotten grants is one build failure; an
+/// empty vector is a pass.
+pub fn check(commands: &[String], files: &[CapabilityFile]) -> Vec<String> {
+    let mut problems = Vec::new();
+    if commands.is_empty() {
+        problems.push(
+            "no commands were parsed out of generate_handler! — an empty AppManifest would \
+             silently leave every app command ungated"
+                .to_string(),
+        );
+        return problems;
+    }
+
+    let mut seen: BTreeSet<&str> = BTreeSet::new();
+    for c in commands {
+        if !c.bytes().all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_') {
+            problems.push(format!("{c:?} is not a command name ([a-z0-9_]+)"));
+        }
+        if !seen.insert(c.as_str()) {
+            problems.push(format!("{c} is registered more than once"));
+        }
+    }
+
+    let known: BTreeMap<String, &str> =
+        seen.iter().map(|c| (allow_permission(c), *c)).collect();
+    for f in files {
+        let windows: Vec<&str> = f.windows.iter().map(String::as_str).collect();
+        for id in &f.bare {
+            match known.get(id) {
+                Some(command) => {
+                    let want = expected_windows(command);
+                    if windows.as_slice() != want {
+                        problems.push(format!(
+                            "{}: {id} must be granted in the capability file whose windows are \
+                             {want:?}, not {windows:?}",
+                            f.name
+                        ));
+                    }
+                }
+                None if id.starts_with("deny-") => problems.push(format!(
+                    "{}: {id}: deny-* is global in tauri 2.11 — it would deny the command for \
+                     every window, not just this one; use allow-lists only",
+                    f.name
+                )),
+                None if id.starts_with("allow-") => problems.push(format!(
+                    "{}: {id} names no registered command (the identifier is allow-<command> \
+                     with every `_` replaced by `-`)",
+                    f.name
+                )),
+                None => problems.push(format!(
+                    "{}: {id}: only allow-<command> app grants are permitted as bare identifiers",
+                    f.name
+                )),
+            }
+        }
+    }
+
+    for c in &seen {
+        let id = allow_permission(c);
+        let holders: Vec<&str> = files
+            .iter()
+            .filter(|f| f.bare.iter().any(|b| b == &id))
+            .map(|f| f.name.as_str())
+            .collect();
+        match holders.len() {
+            0 => problems.push(format!(
+                "{c} is registered but no capability file grants {id}; add it to the file \
+                 whose windows are {:?}",
+                expected_windows(c)
+            )),
+            1 => {}
+            _ => problems.push(format!(
+                "{id} is granted in more than one capability file: {holders:?}"
+            )),
+        }
+    }
+    problems
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn cmds(names: &[&str]) -> Vec<String> {
+        names.iter().map(|n| n.to_string()).collect()
+    }
+
+    fn file(name: &str, windows: &[&str], bare: &[&str]) -> CapabilityFile {
+        CapabilityFile {
+            name: name.to_string(),
+            windows: windows.iter().map(|w| w.to_string()).collect(),
+            bare: bare.iter().map(|b| b.to_string()).collect(),
+        }
+    }
+
+    /// The two files as they must look after the lockdown, for a three-command app.
+    fn good_files() -> Vec<CapabilityFile> {
+        vec![
+            file("default.json", &["main"], &["allow-check-docker", "allow-open-file-viewer"]),
+            file("file-viewer.json", &["file-viewer-*"], &["allow-viewer-read-file"]),
+        ]
+    }
+
+    const THREE: &[&str] = &["check_docker", "open_file_viewer", "viewer_read_file"];
+
+    #[test]
+    fn the_parser_reads_the_handler_list_in_order_and_ignores_comments() {
+        let lib_rs = r#"
+            .invoke_handler(tauri::generate_handler![
+                // Docker
+                commands::docker_commands::check_docker,
+                commands::docker_commands::build_image, // trailing comment is not a command
+                url_open::open_url_external,
+
+                // Viewer
+                commands::file_viewer_commands::viewer_read_file
+            ])
+            .run(tauri::generate_context!())
+        "#;
+        assert_eq!(
+            registered_commands(lib_rs).unwrap(),
+            cmds(&["check_docker", "build_image", "open_url_external", "viewer_read_file"])
+        );
+    }
+
+    #[test]
+    fn the_parser_keeps_duplicates_so_the_caller_can_report_them() {
+        let lib_rs = "generate_handler![\n a::x,\n b::x,\n])";
+        assert_eq!(registered_commands(lib_rs).unwrap(), cmds(&["x", "x"]));
+    }
+
+    #[test]
+    fn the_parser_returns_none_without_a_handler_block() {
+        assert_eq!(registered_commands("fn main() {}"), None);
+        assert_eq!(registered_commands("generate_handler![ a::b, "), None, "unterminated");
+    }
+
+    /// The bug this regression-tests: a line-split parser applies `rsplit("::").next()` once
+    /// per *line*, so two commands sharing a line collapse into one item and the first is
+    /// silently dropped. Comma-splitting must keep both regardless of layout.
+    #[test]
+    fn two_commands_on_one_line_are_both_kept() {
+        let lib_rs = "generate_handler![\n a::x, b::y,\n])";
+        assert_eq!(registered_commands(lib_rs).unwrap(), cmds(&["x", "y"]));
+    }
+
+    /// Mirrors the real `lib.rs` handler list's shape: `// Section` comments between groups,
+    /// and command paths one (`open_url_external`), two (`url_open::open_url_external`) and
+    /// three (`commands::docker_commands::check_docker`) segments deep, all ending in a comma
+    /// except the last entry before `])`.
+    #[test]
+    fn a_fixture_shaped_like_the_real_handler_list_parses_every_command() {
+        let lib_rs = r#"
+            .invoke_handler(tauri::generate_handler![
+                // Docker
+                commands::docker_commands::check_docker,
+                commands::docker_commands::build_image,
+                // Opening a link in the host browser
+                url_open::open_url_external,
+                // Bare, module-less command
+                open_help,
+                // Terminal file viewer
+                commands::file_viewer_commands::viewer_read_file
+            ])
+            .run(tauri::generate_context!())
+        "#;
+        assert_eq!(
+            registered_commands(lib_rs).unwrap(),
+            cmds(&[
+                "check_docker",
+                "build_image",
+                "open_url_external",
+                "open_help",
+                "viewer_read_file",
+            ])
+        );
+    }
+
+    #[test]
+    fn permission_identifiers_replace_only_underscores() {
+        assert_eq!(allow_permission("check_docker"), "allow-check-docker");
+        assert_eq!(allow_permission("viewer_read_file"), "allow-viewer-read-file");
+        assert_eq!(allow_permission("aws_sso_refresh"), "allow-aws-sso-refresh");
+    }
+
+    #[test]
+    fn viewer_commands_belong_to_the_viewer_windows_and_nothing_else_does() {
+        assert_eq!(expected_windows("viewer_read_file"), ["file-viewer-*"]);
+        assert_eq!(expected_windows("open_file_viewer"), ["main"]);
+        assert_eq!(expected_windows("check_docker"), ["main"]);
+    }
+
+    #[test]
+    fn a_capability_file_yields_its_windows_and_bare_grants_only() {
+        let json = r#"{
+            "identifier": "default",
+            "description": "x",
+            "windows": ["main"],
+            "permissions": [
+                "core:event:allow-listen",
+                { "identifier": "fs:allow-read", "allow": [{ "path": "$APPDATA/*" }] },
+                "allow-check-docker",
+                { "identifier": "allow-list-projects" }
+            ]
+        }"#;
+        let parsed = capability_file("default.json", json).unwrap();
+        assert_eq!(parsed.name, "default.json");
+        assert_eq!(parsed.windows, vec!["main"]);
+        assert_eq!(parsed.bare, vec!["allow-check-docker", "allow-list-projects"]);
+    }
+
+    #[test]
+    fn a_capability_file_without_windows_or_permissions_is_an_error() {
+        assert!(capability_file("x.json", r#"{"permissions": []}"#).unwrap_err().contains("windows"));
+        assert!(capability_file("x.json", r#"{"windows": ["main"]}"#).unwrap_err().contains("permissions"));
+        assert!(capability_file("x.json", "not json").unwrap_err().contains("x.json"));
+    }
+
+    #[test]
+    fn webviews_and_remote_keys_are_refused() {
+        let with = |extra: &str| {
+            format!(r#"{{"windows": ["main"], {extra}, "permissions": ["allow-check-docker"]}}"#)
+        };
+        let err = capability_file("d.json", &with(r#""webviews": ["browser-view-*"]"#)).unwrap_err();
+        assert!(err.contains("d.json") && err.contains("`webviews`"), "{err}");
+        let err = capability_file("d.json", &with(r#""remote": {"urls": ["https://*"]}"#)).unwrap_err();
+        assert!(err.contains("`remote`"), "{err}");
+        // Present-but-empty is still refused: the key itself is the widening surface.
+        assert!(capability_file("d.json", &with(r#""webviews": []"#)).is_err());
+    }
+
+    #[test]
+    fn only_top_level_json_files_are_capabilities() {
+        assert_eq!(stray_capability_entry("default.json", true), None);
+        for name in ["extra.toml", "extra.json5", "notes.txt", ".DS_Store"] {
+            let err = stray_capability_entry(name, true).expect(name);
+            assert!(err.contains(name) && err.contains("not a .json file"), "{err}");
+        }
+        let err = stray_capability_entry("sub", false).unwrap();
+        assert!(err.contains("capabilities/sub") && err.contains("not a regular file"), "{err}");
+        // A directory named like a capability is still a directory.
+        assert!(stray_capability_entry("x.json", false).is_some());
+    }
+
+    #[test]
+    fn os_junk_is_recognised_but_never_something_tauri_would_load() {
+        for junk in [".DS_Store", "Thumbs.db", "desktop.ini", ".default.json.swp", ".x.swo", "default.json~"] {
+            assert!(is_os_junk(junk), "{junk}");
+        }
+        for real in ["default.json", "x.toml", "x.json5", ".#default.json", "._default.json", "notes.txt", "extra"] {
+            assert!(!is_os_junk(real), "{real}");
+        }
+    }
+
+    #[test]
+    fn tauri_config_files_are_found_by_name_and_format() {
+        assert_eq!(tauri_config_file("tauri.conf.json"), Some(true));
+        assert_eq!(tauri_config_file("tauri.linux.conf.json"), Some(true));
+        assert_eq!(tauri_config_file("tauri.conf.json5"), Some(false));
+        assert_eq!(tauri_config_file("tauri.windows.conf.json5"), Some(false));
+        assert_eq!(tauri_config_file("Tauri.toml"), Some(false));
+        assert_eq!(tauri_config_file("Tauri.macos.toml"), Some(false));
+        assert_eq!(tauri_config_file("Cargo.toml"), None);
+        assert_eq!(tauri_config_file("build.rs"), None);
+    }
+
+    #[test]
+    fn inline_capabilities_in_the_tauri_config_are_refused() {
+        let ok = r#"{"app": {"security": {"csp": "default-src 'self'"}}}"#;
+        assert_eq!(tauri_config_problem("tauri.conf.json", ok), None);
+        assert_eq!(tauri_config_problem("t", r#"{"app": {"security": {"capabilities": []}}}"#), None);
+        assert_eq!(tauri_config_problem("t", r#"{"build": {"beforeBuildCommand": ""}}"#), None);
+        let inline = r#"{"app": {"security": {"capabilities": [
+            {"identifier": "x", "windows": ["file-viewer-*"], "permissions": ["allow-read-container-file"]}
+        ]}}}"#;
+        let err = tauri_config_problem("tauri.conf.json", inline).unwrap();
+        assert!(err.contains("tauri.conf.json") && err.contains("app.security.capabilities"), "{err}");
+        let by_name = r#"{"app": {"security": {"capabilities": ["default"]}}}"#;
+        assert!(tauri_config_problem("TAURI_CONFIG", by_name).unwrap().contains("TAURI_CONFIG"));
+        assert!(tauri_config_problem("t", "{").unwrap().contains("not valid JSON"));
+    }
+
+    #[test]
+    fn a_correct_census_has_no_problems() {
+        assert_eq!(check(&cmds(THREE), &good_files()), Vec::<String>::new());
+    }
+
+    #[test]
+    fn an_empty_command_list_is_refused_because_it_would_disable_the_acl() {
+        let problems = check(&[], &good_files());
+        assert_eq!(problems.len(), 1);
+        assert!(problems[0].contains("no commands"), "{problems:?}");
+    }
+
+    #[test]
+    fn a_command_without_a_grant_is_named_together_with_the_file_it_belongs_in() {
+        let files = vec![
+            file("default.json", &["main"], &["allow-check-docker"]),
+            file("file-viewer.json", &["file-viewer-*"], &["allow-viewer-read-file"]),
+        ];
+        let problems = check(&cmds(THREE), &files);
+        assert_eq!(problems.len(), 1, "{problems:?}");
+        assert!(problems[0].contains("open_file_viewer"));
+        assert!(problems[0].contains("allow-open-file-viewer"));
+        assert!(problems[0].contains("[\"main\"]"));
+    }
+
+    #[test]
+    fn a_grant_in_two_files_is_reported_once_naming_both() {
+        let files = vec![
+            file("default.json", &["main"], &["allow-check-docker", "allow-open-file-viewer"]),
+            file("extra.json", &["main"], &["allow-check-docker"]),
+            file("file-viewer.json", &["file-viewer-*"], &["allow-viewer-read-file"]),
+        ];
+        let problems = check(&cmds(THREE), &files);
+        assert_eq!(problems.len(), 1, "{problems:?}");
+        assert!(problems[0].contains("allow-check-docker"));
+        assert!(problems[0].contains("default.json") && problems[0].contains("extra.json"));
+    }
+
+    #[test]
+    fn a_grant_that_names_no_command_is_a_typo() {
+        let mut files = good_files();
+        files[0].bare.push("allow-check-dokcer".to_string());
+        let problems = check(&cmds(THREE), &files);
+        assert_eq!(problems.len(), 1, "{problems:?}");
+        assert!(problems[0].contains("default.json: allow-check-dokcer"));
+        assert!(problems[0].contains("no registered command"));
+    }
+
+    #[test]
+    fn deny_grants_are_refused_with_the_reason() {
+        let mut files = good_files();
+        files[1].bare.push("deny-check-docker".to_string());
+        let problems = check(&cmds(THREE), &files);
+        assert_eq!(problems.len(), 1, "{problems:?}");
+        assert!(problems[0].contains("file-viewer.json: deny-check-docker"));
+        assert!(problems[0].contains("global"));
+    }
+
+    #[test]
+    fn other_bare_identifiers_are_refused() {
+        let mut files = good_files();
+        files[0].bare.push("default".to_string());
+        let problems = check(&cmds(THREE), &files);
+        assert_eq!(problems.len(), 1, "{problems:?}");
+        assert!(problems[0].contains("default.json: default"));
+    }
+
+    #[test]
+    fn a_grant_in_the_wrong_file_is_refused_even_though_it_is_granted_exactly_once() {
+        let files = vec![
+            file("default.json", &["main"], &["allow-check-docker", "allow-open-file-viewer", "allow-viewer-read-file"]),
+            file("file-viewer.json", &["file-viewer-*"], &[]),
+        ];
+        let problems = check(&cmds(THREE), &files);
+        assert_eq!(problems.len(), 1, "{problems:?}");
+        assert!(problems[0].contains("allow-viewer-read-file"));
+        assert!(problems[0].contains("[\"file-viewer-*\"]"));
+    }
+
+    #[test]
+    fn a_widened_windows_list_is_the_wrong_file_too() {
+        let files = vec![
+            file("default.json", &["main", "file-viewer-*"], &["allow-check-docker", "allow-open-file-viewer"]),
+            file("file-viewer.json", &["file-viewer-*"], &["allow-viewer-read-file"]),
+        ];
+        let problems = check(&cmds(THREE), &files);
+        assert_eq!(problems.len(), 2, "{problems:?}");
+    }
+
+    #[test]
+    fn bad_names_and_duplicate_registrations_are_refused() {
+        let commands = cmds(&["check_docker", "Check-Docker", "check_docker", "open_file_viewer", "viewer_read_file"]);
+        let problems = check(&commands, &good_files());
+        assert!(problems.iter().any(|p| p.contains("\"Check-Docker\"") && p.contains("[a-z0-9_]+")), "{problems:?}");
+        assert!(problems.iter().any(|p| p.contains("check_docker is registered more than once")), "{problems:?}");
+    }
+
+    #[test]
+    fn every_problem_is_reported_in_one_pass() {
+        let files = vec![
+            file("default.json", &["main"], &["allow-check-docker", "allow-nope", "deny-check-docker"]),
+            file("file-viewer.json", &["file-viewer-*"], &[]),
+        ];
+        let problems = check(&cmds(THREE), &files);
+        // typo, deny, open_file_viewer missing, viewer_read_file missing
+        assert_eq!(problems.len(), 4, "{problems:?}");
+    }
+}

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

@@ -0,0 +1,65 @@
+//! 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::host::ContainerTarget;
+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) = ContainerTarget::for_project(&project) {
+            if container.is_running().await.unwrap_or(false) {
+                state
+                    .auth_bridge
+                    .start(
+                        project_id.clone(),
+                        container,
+                        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/aws_commands.rs

@@ -52,7 +52,8 @@ pub async fn run_sso_login(profile: &str) -> Result<(), String> {
     log::info!("Running host-side AWS SSO login for profile '{}'", profile);
 
     let status = tokio::process::Command::new("aws")
-        .args(["sso", "login", "--profile", profile])
+        // One argv element, so a name starting with `-` is never an option.
+        .args(["sso", "login", &format!("--profile={profile}")])
         .status()
         .await
         .map_err(|e| format!("Failed to run aws sso login: {}", e))?;

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/environment_commands/tests.rs

@@ -0,0 +1,631 @@
+use std::fs;
+use std::time::Duration;
+
+use serde_json::json;
+
+use super::*;
+use crate::aws::tofu::Workdir;
+use crate::aws::environments::{
+    EnvironmentState, Knowable, LockInfo, OnboardingState,
+};
+use crate::aws::tofu_modules::{
+    environment_vars, module_files, onboarding_vars, owner_key, state_key, ModuleKind,
+};
+
+const ACCOUNT: &str = "123456789012";
+const REGION: &str = "eu-west-1";
+const USER_ID: &str = "AROAEXAMPLEID12345678:alice";
+
+fn info(name: &str, mode: &str, assign_public_ip: bool) -> EnvironmentInfo {
+    EnvironmentInfo {
+        schema: 1,
+        name: name.into(),
+        template_version: 1,
+        cluster_arn: format!("arn:aws:ecs:{REGION}:{ACCOUNT}:cluster/triple-c-{name}"),
+        security_group_id: "sg-0123456789abcdef0".into(),
+        subnet_ids: vec![
+            "subnet-0123456789abcdef0".into(),
+            "subnet-0fedcba9876543210".into(),
+        ],
+        assign_public_ip,
+        kms_key_arn: format!("arn:aws:kms:{REGION}:{ACCOUNT}:key/1234abcd-12ab"),
+        log_group: format!("/triple-c/{name}"),
+        network_mode: mode.into(),
+        tenancy: "strict".into(),
+    }
+}
+
+fn env(name: &str, state: EnvironmentState, actions: Vec<EnvironmentAction>) -> DetectedEnvironment {
+    DetectedEnvironment {
+        name: name.into(),
+        template_version: None,
+        state,
+        actions,
+        info: None,
+        onboarding: None,
+        onboarding_actions: Vec::new(),
+        onboarded_users: Some(0),
+    }
+}
+
+fn scan(boundary: Knowable, environments: Vec<DetectedEnvironment>) -> EnvironmentScan {
+    EnvironmentScan {
+        region: REGION.into(),
+        account: ACCOUNT.into(),
+        owner_id: USER_ID.into(),
+        owner_key: owner_key(REGION, USER_ID),
+        state_bucket: Knowable::Yes,
+        boundary,
+        environments,
+    }
+}
+
+fn lock(age_secs: u64, local_process: bool) -> LockInfo {
+    LockInfo {
+        who: "someone@host".into(),
+        created: String::new(),
+        operation: "OperationTypeApply".into(),
+        age_secs,
+        local_process,
+    }
+}
+
+#[test]
+fn only_our_state_keys_are_accepted() {
+    let ok = owner_key(REGION, USER_ID);
+    let good = [
+        (
+            "environments/dev/terraform.tfstate".to_string(),
+            DeploymentKey::Environment("dev".into()),
+        ),
+        (
+            format!("users/dev/{ok}/terraform.tfstate"),
+            DeploymentKey::User { env: "dev".into(), owner_key: ok.clone() },
+        ),
+        ("boundary/terraform.tfstate".to_string(), DeploymentKey::Boundary),
+    ];
+    for (key, want) in good {
+        let parsed = parse_state_key(&key).unwrap();
+        assert_eq!(parsed, want);
+        assert_eq!(state_key(parsed.deployment()), key, "round trip");
+    }
+    let bad = [
+        "",
+        "environments/dev/terraform.tfstate.tflock",
+        "environments/Dev/terraform.tfstate",
+        "environments/dev-/terraform.tfstate",
+        "environments/../terraform.tfstate",
+        "environments/dev/../../boundary/terraform.tfstate",
+        "/environments/dev/terraform.tfstate",
+        "environments//terraform.tfstate",
+        "environments/dev/x/terraform.tfstate",
+        "environments/dev/terraform.tfstate/",
+        "users/dev/terraform.tfstate",
+        "users/dev/ABCDEF012345/terraform.tfstate",
+        "users/dev/abcdef01234/terraform.tfstate",
+        "users/dev/abcdef0123456/terraform.tfstate",
+        "users/dev/abcdef01234g/terraform.tfstate",
+        "boundary/x/terraform.tfstate",
+        "boundary/terraform.tfstate ",
+        "something/else",
+        "environments\\dev\\terraform.tfstate",
+    ];
+    for key in bad {
+        assert!(parse_state_key(key).is_err(), "{key:?} must be refused");
+    }
+}
+
+#[test]
+fn deploy_refuses_an_existing_name_and_a_missing_boundary() {
+    use EnvironmentAction::*;
+    let existing = vec![
+        env("dev", EnvironmentState::Ready, vec![Join]),
+        env("half", EnvironmentState::Incomplete { lock: None }, vec![Repair, Destroy]),
+    ];
+    let s = scan(Knowable::Yes, existing.clone());
+    assert!(deploy_refusal(&s, "prod").is_ok());
+    let e = deploy_refusal(&s, "dev").unwrap_err();
+    assert!(e.contains("already exists"), "{e}");
+    assert!(deploy_refusal(&s, "half").is_err(), "state without a record is taken too");
+    assert!(deploy_refusal(&s, "Not Valid").is_err());
+
+    let no_boundary = scan(Knowable::No, existing.clone());
+    let e = deploy_refusal(&no_boundary, "prod").unwrap_err();
+    assert!(e.contains("permissions boundary"), "{e}");
+    // A caller who can't tell is let through (the apply itself would fail).
+    assert!(deploy_refusal(&scan(Knowable::Unknown, existing), "prod").is_ok());
+}
+
+#[test]
+fn update_reuses_the_recorded_network() {
+    assert_eq!(
+        network_from_record(&info("dev", "public", true), None).unwrap(),
+        NetworkChoice::Public
+    );
+    assert_eq!(
+        network_from_record(&info("dev", "private-nat", false), None).unwrap(),
+        NetworkChoice::PrivateNat
+    );
+    let existing = info("dev", "existing", false);
+    assert_eq!(
+        network_from_record(&existing, Some("vpc-0123456789abcdef0")).unwrap(),
+        NetworkChoice::Existing {
+            vpc_id: "vpc-0123456789abcdef0".into(),
+            subnet_ids: existing.subnet_ids.clone(),
+            assign_public_ip: false,
+        }
+    );
+    // The VPC isn't in the record: without it from the state, refuse rather
+    // than guess.
+    assert!(network_from_record(&existing, None).is_err());
+    assert!(network_from_record(&existing, Some("not-a-vpc")).is_err());
+    assert!(network_from_record(&info("dev", "carrier-pigeon", false), None).is_err());
+    // And it round-trips into the module's variables unchanged.
+    let vars = environment_vars(
+        "dev",
+        REGION,
+        &network_from_record(&existing, Some("vpc-0123456789abcdef0")).unwrap(),
+    )
+    .unwrap();
+    assert_eq!(vars["network_mode"], "existing");
+    assert_eq!(vars["subnet_ids"], json!(existing.subnet_ids));
+}
+
+#[test]
+fn the_vpc_is_read_from_the_state_outputs() {
+    let state = json!({
+        "version": 4,
+        "outputs": { "vpc_id": { "value": "vpc-0123456789abcdef0", "type": "string" } },
+    })
+    .to_string();
+    assert_eq!(
+        vpc_id_from_state(state.as_bytes()).as_deref(),
+        Some("vpc-0123456789abcdef0")
+    );
+    assert_eq!(vpc_id_from_state(b"{}"), None);
+    assert_eq!(vpc_id_from_state(b"not json"), None);
+    let hostile = json!({"outputs": {"vpc_id": {"value": "vpc-1\"; rm -rf /"}}}).to_string();
+    assert_eq!(vpc_id_from_state(hostile.as_bytes()), None);
+}
+
+#[test]
+fn bundles_contain_the_module_backend_vars_and_readme() {
+    let dir = tempfile::tempdir().unwrap();
+    let ok = owner_key(REGION, USER_ID);
+    let d = Deployment::User { env: "dev", owner_key: &ok };
+    let vars = onboarding_vars("dev", REGION, USER_ID);
+    let written = write_bundle(dir.path(), d, ACCOUNT, REGION, &vars).unwrap();
+
+    for (name, text) in module_files(ModuleKind::UserOnboard) {
+        assert_eq!(&fs::read_to_string(dir.path().join(name)).unwrap(), text);
+        assert!(written.contains(&name.to_string()));
+    }
+    let bucket = format!("triple-c-tfstate-{ACCOUNT}-{REGION}");
+    let key = state_key(d);
+    let backend = fs::read_to_string(dir.path().join("backend.hcl")).unwrap();
+    assert!(backend.contains(&format!("bucket = \"{bucket}\"")), "{backend}");
+    assert!(backend.contains(&format!("key = \"{key}\"")), "{backend}");
+    assert!(backend.contains("use_lockfile = true"), "{backend}");
+    let tfvars: Value =
+        serde_json::from_str(&fs::read_to_string(dir.path().join("terraform.tfvars.json")).unwrap())
+            .unwrap();
+    assert_eq!(tfvars, vars);
+
+    let readme = fs::read_to_string(dir.path().join("README.txt")).unwrap();
+    for needle in [
+        bucket.as_str(),
+        key.as_str(),
+        ACCOUNT,
+        REGION,
+        "tofu init -backend-config=backend.hcl",
+        "tofu apply",
+        "terraform providers lock",
+        "registry.opentofu.org",
+        "1.10",
+        "aws s3api create-bucket",
+    ] {
+        assert!(readme.contains(needle), "README lacks {needle:?}:\n{readme}");
+    }
+    // Outside us-east-1 the bucket needs a location constraint.
+    assert!(readme.contains(&format!("\"LocationConstraint\":\"{REGION}\"")), "{readme}");
+    // The admin policy allows s3:CreateBucket only with the component tag
+    // in the request, so the tag goes on the create itself; and the bucket
+    // is configured as the app configures it, TLS-only policy included.
+    let create = readme
+        .lines()
+        .find(|l| l.contains("aws s3api create-bucket"))
+        .unwrap();
+    assert!(
+        create.contains(r#""Tags":[{"Key":"triple-c:component","Value":"state"}]"#),
+        "{create}"
+    );
+    for needle in [
+        "put-bucket-versioning",
+        "put-bucket-encryption",
+        "put-public-access-block",
+        "put-bucket-policy",
+        "aws:SecureTransport",
+        "DenyInsecureTransport",
+    ] {
+        assert!(readme.contains(needle), "README lacks {needle:?}:\n{readme}");
+    }
+    assert!(!readme.contains("put-bucket-tagging"), "a later tag can't satisfy the create");
+
+    // Writing again over our own files is fine...
+    write_bundle(dir.path(), d, ACCOUNT, REGION, &vars).unwrap();
+    // ...but an unrelated file (or folder) means the wrong folder.
+    fs::write(dir.path().join("notes.txt"), "mine").unwrap();
+    let e = write_bundle(dir.path(), d, ACCOUNT, REGION, &vars).unwrap_err();
+    assert!(e.contains("notes.txt"), "{e}");
+    assert_eq!(fs::read_to_string(dir.path().join("notes.txt")).unwrap(), "mine");
+    fs::remove_file(dir.path().join("notes.txt")).unwrap();
+    fs::create_dir(dir.path().join(".terraform")).unwrap();
+    assert!(write_bundle(dir.path(), d, ACCOUNT, REGION, &vars).is_err());
+}
+
+#[test]
+fn a_us_east_1_bundle_creates_its_bucket_without_a_location_constraint() {
+    let dir = tempfile::tempdir().unwrap();
+    let vars = environment_vars("dev", "us-east-1", &NetworkChoice::Public).unwrap();
+    write_bundle(dir.path(), Deployment::Environment("dev"), ACCOUNT, "us-east-1", &vars).unwrap();
+    let readme = fs::read_to_string(dir.path().join("README.txt")).unwrap();
+    assert!(readme.contains("aws s3api create-bucket"), "{readme}");
+    assert!(!readme.contains("LocationConstraint"), "{readme}");
+    assert!(readme.contains(r#""Tags":[{"Key":"triple-c:component","Value":"state"}]"#), "{readme}");
+    assert!(readme.contains("tofu destroy"), "{readme}");
+    for (name, _) in module_files(ModuleKind::Environment) {
+        assert!(dir.path().join(name).is_file(), "{name}");
+    }
+}
+
+#[test]
+fn owner_ids_must_look_like_an_aws_user_id() {
+    for ok in ["AIDAEXAMPLEUSERID1234", "AROAEXAMPLEID12345678:alice", "AROA1234567890ABCDEF:a.b@c_d-e+f=g,h"] {
+        assert_eq!(validate_owner_id(ok).unwrap(), ok);
+    }
+    for bad in [
+        "",
+        "123456789012",
+        "aidaexampleuserid1234",
+        "AROAEXAMPLEID12345678:",
+        "AROAEXAMPLEID12345678:a b",
+        "AROAEXAMPLEID12345678:a:b",
+        "AROAEXAMPLEID12345678:\"",
+        &format!("AROAEXAMPLEID12345678:{}", "a".repeat(65)),
+        &"A".repeat(129),
+    ] {
+        assert!(validate_owner_id(bad).is_err(), "{bad:?}");
+    }
+}
+
+#[test]
+fn server_side_rechecks_follow_the_detected_actions() {
+    use EnvironmentAction::*;
+    let s = scan(
+        Knowable::Yes,
+        vec![
+            env("broken", EnvironmentState::Incomplete { lock: None }, vec![Repair, Destroy]),
+            env(
+                "working",
+                EnvironmentState::Incomplete { lock: Some(lock(9000, false)) },
+                vec![Repair, Unlock],
+            ),
+            env("ready", EnvironmentState::Ready, vec![Join]),
+            env("busy", EnvironmentState::Deploying { lock: Some(lock(10, true)) }, vec![Follow]),
+        ],
+    );
+    assert!(require_action(&s, "broken", Destroy).is_ok());
+    assert!(require_action(&s, "working", Destroy).is_err(), "never destroy a working env (D6)");
+    assert!(require_action(&s, "ready", Destroy).is_err());
+    assert!(require_action(&s, "missing", Destroy).is_err());
+    assert!(require_action(&s, "working", Repair).is_ok());
+    assert!(require_action(&s, "ready", Update).is_err());
+
+    assert!(unlock_refusal(&s, "working").is_ok());
+    assert!(unlock_refusal(&s, "broken").is_err(), "no lock to remove");
+    assert!(unlock_refusal(&s, "busy").is_err(), "a local runner holds it");
+    let local_stale = scan(
+        Knowable::Yes,
+        vec![env(
+            "x",
+            EnvironmentState::Incomplete { lock: Some(lock(9000, true)) },
+            vec![Unlock],
+        )],
+    );
+    assert!(unlock_refusal(&local_stale, "x").is_err());
+}
+
+#[test]
+fn onboarding_needs_a_joinable_environment_and_the_boundary() {
+    use EnvironmentAction::*;
+    let mut ready = env("dev", EnvironmentState::Ready, vec![Join]);
+    ready.onboarding = Some(OnboardingState::NotJoined);
+    let mut busy = env("busy", EnvironmentState::Ready, vec![Join]);
+    busy.onboarding = Some(OnboardingState::InProgress { lock: None });
+    let half = env("half", EnvironmentState::Incomplete { lock: None }, vec![Repair, Destroy]);
+    let s = scan(Knowable::Yes, vec![ready.clone(), busy, half]);
+    assert!(onboard_refusal(&s, "dev").is_ok());
+    assert!(onboard_refusal(&s, "busy").is_err());
+    assert!(onboard_refusal(&s, "half").is_err());
+    assert!(onboard_refusal(&s, "nope").is_err());
+    assert!(onboard_refusal(&scan(Knowable::No, vec![ready]), "dev").is_err());
+}
+
+#[test]
+fn progress_events_have_the_documented_shape() {
+    let p = DeployProgress {
+        op_id: "op".into(),
+        state_key: "boundary/terraform.tfstate".into(),
+        events: vec![],
+        done: false,
+        cancellable: true,
+        result: None,
+    };
+    let v = serde_json::to_value(&p).unwrap();
+    assert_eq!(
+        v,
+        json!({"op_id": "op", "state_key": "boundary/terraform.tfstate", "events": [], "done": false, "cancellable": true})
+    );
+    let done = DeployProgress {
+        done: true,
+        result: Some(TofuOutcome { ok: false, exit_code: 1, summary: Some("boom".into()) }),
+        ..p
+    };
+    let v = serde_json::to_value(&done).unwrap();
+    assert_eq!(v["result"], json!({"ok": false, "exit_code": 1, "summary": "boom"}));
+}
+
+#[test]
+fn an_already_running_start_names_the_deployment_and_suggests_follow() {
+    let e = start_error(StartError::AlreadyRunning, "environment \"dev\"");
+    let msg = e.to_string();
+    assert!(msg.contains("already running for environment \"dev\""), "{msg}");
+    assert!(msg.contains("Follow"), "{msg}");
+    let inner = AwsError::KeysMissing;
+    assert_eq!(start_error(StartError::Failed(inner.clone()), "x"), inner);
+}
+
+#[tokio::test]
+async fn a_follower_emits_nothing_until_its_gate_opens() {
+    use std::sync::{Arc, Mutex};
+    // A finished run: the whole replay and `done` are available at once,
+    // the case where events could otherwise beat the op id to the caller.
+    let dir = tempfile::tempdir().unwrap();
+    let lines: String = (0..450).map(|i| format!("line {i}\n")).collect();
+    fs::write(dir.path().join("apply.log"), lines).unwrap();
+    fs::write(dir.path().join("apply.exit"), "0\n").unwrap();
+    let wd = Workdir { dir: dir.path().to_path_buf() };
+    let base = DeployProgress {
+        op_id: "op-1".into(),
+        state_key: "boundary/terraform.tfstate".into(),
+        events: vec![],
+        done: false,
+        cancellable: true,
+        result: None,
+    };
+    let seen: Arc<Mutex<Vec<DeployProgress>>> = Arc::default();
+    let sink = seen.clone();
+    let (gate, rx) = Gate::new();
+    let task = tokio::spawn(follow_and_report(
+        rx,
+        wd,
+        base,
+        Duration::from_millis(10),
+        move |p| sink.lock().unwrap().push(p.clone()),
+    ));
+    tokio::time::sleep(Duration::from_millis(150)).await;
+    assert!(seen.lock().unwrap().is_empty(), "emitted before the gate opened");
+
+    gate.open();
+    task.await.unwrap();
+    let seen = seen.lock().unwrap();
+    let batches: Vec<usize> = seen.iter().filter(|p| !p.done).map(|p| p.events.len()).collect();
+    assert_eq!(batches, vec![200, 200, 50], "the whole log, in capped batches");
+    assert!(seen.iter().all(|p| p.op_id == "op-1" && p.state_key == "boundary/terraform.tfstate"));
+    let last = seen.last().unwrap();
+    assert!(last.done && !last.cancellable);
+    assert_eq!(last.result, Some(TofuOutcome { ok: true, exit_code: 0, summary: None }));
+    assert_eq!(seen.iter().filter(|p| p.done).count(), 1);
+}
+
+#[tokio::test]
+async fn a_dropped_gate_still_releases_the_follower() {
+    let dir = tempfile::tempdir().unwrap();
+    fs::write(dir.path().join("apply.log"), "x\n").unwrap();
+    fs::write(dir.path().join("apply.exit"), "1\n").unwrap();
+    let (gate, rx) = Gate::new();
+    drop(gate);
+    let mut n = 0;
+    follow_and_report(
+        rx,
+        Workdir { dir: dir.path().to_path_buf() },
+        DeployProgress {
+            op_id: "o".into(),
+            state_key: "k".into(),
+            events: vec![],
+            done: false,
+            cancellable: false,
+            result: None,
+        },
+        Duration::from_millis(10),
+        |_| n += 1,
+    )
+    .await;
+    assert_eq!(n, 2);
+}
+
+#[test]
+fn destroy_needs_the_action_no_record_and_no_lock() {
+    use EnvironmentAction::*;
+    let mut stale_with_record = env(
+        "rec",
+        EnvironmentState::Incomplete { lock: Some(lock(9000, false)) },
+        vec![Repair, Destroy, Unlock],
+    );
+    // Stale lock + record + no state: detection offers Destroy; the guard
+    // must still refuse (the record says it may be working).
+    stale_with_record.info = Some(info("rec", "public", true));
+    let mut record_unlocked = env("rec2", EnvironmentState::Incomplete { lock: None }, vec![Destroy]);
+    record_unlocked.info = Some(info("rec2", "public", true));
+    let s = scan(
+        Knowable::Yes,
+        vec![
+            stale_with_record,
+            record_unlocked,
+            env("locked", EnvironmentState::Incomplete { lock: Some(lock(9000, false)) }, vec![Repair, Destroy, Unlock]),
+            env("half", EnvironmentState::Incomplete { lock: None }, vec![Repair, Destroy]),
+            env("ready", EnvironmentState::Ready, vec![Join]),
+        ],
+    );
+    let e = destroy_refusal(&s, "rec").unwrap_err();
+    assert!(e.contains("valid record"), "{e}");
+    assert!(destroy_refusal(&s, "rec2").unwrap_err().contains("valid record"));
+    assert!(destroy_refusal(&s, "locked").unwrap_err().contains("Unlock it first"));
+    assert!(destroy_refusal(&s, "ready").is_err());
+    assert!(destroy_refusal(&s, "missing").is_err());
+    assert_eq!(destroy_refusal(&s, "half").unwrap().name, "half");
+}
+
+#[test]
+fn destroy_is_refused_while_users_are_onboarded() {
+    use EnvironmentAction::*;
+    let mut onboarded = env("half", EnvironmentState::Incomplete { lock: None }, vec![Repair, Destroy]);
+    onboarded.onboarded_users = Some(2);
+    let mut unknown = env("blind", EnvironmentState::Incomplete { lock: None }, vec![Repair, Destroy]);
+    unknown.onboarded_users = None;
+    let s = scan(Knowable::Yes, vec![onboarded, unknown]);
+    let e = destroy_refusal(&s, "half").unwrap_err();
+    assert!(e.contains("remove the onboarded users' stacks first"), "{e}");
+    assert!(e.contains("users/half/"), "{e}");
+    // Without a listing there's no telling, and nothing to destroy from.
+    assert!(destroy_refusal(&s, "blind").unwrap_err().contains("can't list"));
+}
+
+#[test]
+fn only_your_own_stale_onboarding_lock_can_be_removed() {
+    use EnvironmentAction::*;
+    let mut stale = env("dev", EnvironmentState::Ready, vec![Join]);
+    stale.onboarding = Some(OnboardingState::Incomplete { lock: Some(lock(9000, false)) });
+    stale.onboarding_actions = vec![Unlock];
+    let mut live = env("live", EnvironmentState::Ready, vec![Join]);
+    live.onboarding = Some(OnboardingState::InProgress { lock: Some(lock(10, false)) });
+    let mut none = env("none", EnvironmentState::Ready, vec![Join]);
+    none.onboarding = Some(OnboardingState::Incomplete { lock: None });
+    let s = scan(Knowable::Yes, vec![stale, live, none]);
+    let mine = owner_key(REGION, USER_ID);
+    assert!(onboarding_unlock_refusal(&s, "dev", &mine).is_ok());
+    let e = onboarding_unlock_refusal(&s, "dev", "0123456789ab").unwrap_err();
+    assert!(e.contains("your own"), "{e}");
+    assert!(onboarding_unlock_refusal(&s, "live", &mine).is_err());
+    assert!(onboarding_unlock_refusal(&s, "none", &mine).is_err());
+    assert!(onboarding_unlock_refusal(&s, "missing", &mine).is_err());
+}
+
+#[test]
+fn a_boundary_bundle_names_an_administrator_without_the_admin_files() {
+    let dir = tempfile::tempdir().unwrap();
+    write_bundle(dir.path(), Deployment::Boundary, ACCOUNT, REGION, &boundary_vars(REGION)).unwrap();
+    let readme = fs::read_to_string(dir.path().join("README.txt")).unwrap();
+    assert!(readme.contains("account administrator"), "{readme}");
+    assert!(readme.contains("WITHOUT"), "{readme}");
+    assert!(!readme.contains("that carry the Triple-C environment-admin"), "{readme}");
+}
+
+#[test]
+fn repair_and_update_are_refused_under_a_held_lock() {
+    use EnvironmentAction::*;
+    let s = scan(
+        Knowable::Yes,
+        vec![
+            env("locked", EnvironmentState::Incomplete { lock: Some(lock(9000, false)) }, vec![Repair, Unlock]),
+            env("free", EnvironmentState::Incomplete { lock: None }, vec![Repair]),
+            env("old", EnvironmentState::UpdateAvailable, vec![Join, Update]),
+        ],
+    );
+    let e = reapply_refusal(&s, "locked", Repair).unwrap_err();
+    assert!(e.contains("Unlock it first"), "{e}");
+    assert!(reapply_refusal(&s, "free", Repair).is_ok());
+    assert!(reapply_refusal(&s, "old", Update).is_ok());
+    assert!(reapply_refusal(&s, "free", Update).is_err());
+}
+
+#[test]
+fn unlock_deletes_only_a_still_stale_lock_and_reads_412_as_changed() {
+    assert!(stale_lock_refusal(0).is_err());
+    assert!(stale_lock_refusal(LIVE_LOCK_SECS - 1).is_err());
+    assert!(stale_lock_refusal(LIVE_LOCK_SECS).is_ok());
+    assert!(is_precondition_failed(Some("PreconditionFailed"), Some(412)));
+    assert!(is_precondition_failed(None, Some(412)));
+    assert!(!is_precondition_failed(Some("AccessDenied"), Some(403)));
+    assert!(!is_precondition_failed(None, Some(404)));
+}
+
+#[test]
+fn an_existing_boundary_without_state_here_is_refused() {
+    assert!(boundary_refusal(&Knowable::Yes, Some(false)).unwrap_err().contains("already exists"));
+    assert!(boundary_refusal(&Knowable::Yes, Some(true)).is_ok(), "re-apply our own");
+    assert!(boundary_refusal(&Knowable::Yes, None).is_ok(), "can't tell");
+    assert!(boundary_refusal(&Knowable::No, Some(false)).is_ok());
+    assert!(boundary_refusal(&Knowable::Unknown, Some(false)).is_ok());
+}
+
+#[test]
+fn a_follow_is_refused_while_a_launch_holds_the_folder() {
+    let dir = Path::new("/w/env/dev");
+    let mut slots: Slots<u32> = Slots::default();
+    slots.begin_launch(dir).unwrap();
+    let mut spawned = false;
+    let r = slots.install_follower(dir, "f1", false, || {
+        spawned = true;
+        1
+    });
+    assert_eq!(r.unwrap_err(), SlotBusy::Launching);
+    assert!(!spawned, "nothing is spawned for a refused follow");
+    // The launch's own follower replaces its Launching slot.
+    assert_eq!(slots.install_follower(dir, "l1", true, || 2).unwrap(), None);
+    slots.end_launch(dir); // the guard dropping afterwards
+    assert!(!slots.is_free(dir), "end_launch must not clear a follower");
+}
+
+#[test]
+fn a_launch_is_refused_while_a_follower_or_launch_holds_the_folder() {
+    let dir = Path::new("/w/env/dev");
+    let mut slots: Slots<u32> = Slots::default();
+    slots.install_follower(dir, "f1", false, || 1).unwrap();
+    assert_eq!(slots.begin_launch(dir).unwrap_err(), SlotBusy::Following);
+    slots.finish_follower(dir, "f1");
+    slots.begin_launch(dir).unwrap();
+    assert_eq!(slots.begin_launch(dir).unwrap_err(), SlotBusy::Launching);
+    slots.end_launch(dir);
+    assert!(slots.is_free(dir));
+    // Other folders are independent.
+    slots.begin_launch(dir).unwrap();
+    slots.begin_launch(Path::new("/w/env/prod")).unwrap();
+}
+
+#[test]
+fn a_finishing_follower_only_removes_its_own_slot() {
+    let dir = Path::new("/w/env/dev");
+    let mut slots: Slots<u32> = Slots::default();
+    slots.install_follower(dir, "old", false, || 1).unwrap();
+    // A re-follow replaces it and hands back the old task to abort.
+    assert_eq!(slots.install_follower(dir, "new", false, || 2).unwrap(), Some(1));
+    slots.finish_follower(dir, "old");
+    assert!(!slots.is_free(dir), "the old follower must not remove the new one's slot");
+    slots.finish_follower(dir, "new");
+    assert!(slots.is_free(dir));
+    // Nor a launch's slot.
+    slots.begin_launch(dir).unwrap();
+    slots.finish_follower(dir, "new");
+    assert_eq!(slots.begin_launch(dir).unwrap_err(), SlotBusy::Launching);
+}
+
+#[test]
+fn ending_a_launch_never_clears_a_following_slot() {
+    let dir = Path::new("/w/env/dev");
+    let mut slots: Slots<u32> = Slots::default();
+    slots.install_follower(dir, "f", false, || 1).unwrap();
+    slots.end_launch(dir);
+    assert_eq!(slots.begin_launch(dir).unwrap_err(), SlotBusy::Following);
+    slots.end_launch(Path::new("/w/env/none")); // nothing there: no-op
+}

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

@@ -0,0 +1,373 @@
+//! IPC for the terminal file viewer. Every command here is gated on the calling
+//! window's label and reads its target from the registry — no path, no label, no
+//! project id crosses IPC from a viewer window. See spec §6.
+
+use base64::engine::general_purpose::STANDARD as BASE64;
+use base64::Engine as _;
+use serde::Serialize;
+use tauri::{AppHandle, Emitter, Manager, State};
+
+use crate::commands::file_commands::{
+    fetch_container_file, not_running_message, require_running, validate_container_write_path, MAX_READ_BYTES,
+};
+use crate::file_viewer::is_viewer_label;
+use crate::file_viewer::poll::{poll_file, ViewerPoll};
+use crate::file_viewer::registry::{
+    Choice, Location, Reservation, ViewerRegistry, ViewerTarget, ViewerTargetState,
+};
+use crate::file_viewer::resolve::{candidate_paths, fallback_candidate_paths, probe_candidates};
+use crate::file_viewer::window::open_viewer_window;
+use crate::file_viewer::write::{sha256_hex, write_file, SavedFile, MAX_WRITE_BYTES};
+use crate::host::ContainerTarget;
+use crate::models::Project;
+use crate::AppState;
+
+pub const GOTO_EVENT: &str = "file-viewer-goto";
+
+#[derive(Clone, Debug, Serialize)]
+pub struct ViewerState {
+    pub project_id: String,
+    pub project_name: String,
+    pub raw_path: String,
+    pub state: ViewerTargetState,
+    pub initial: Location,
+}
+
+#[derive(Clone, Debug, Serialize)]
+pub struct ViewerFile {
+    pub contents_base64: String,
+    pub truncated: bool,
+    pub size: u64,
+    pub hash: String,
+    pub editable: bool,
+    pub readonly_reason: Option<String>,
+}
+
+fn require_main(window_label: &str) -> Result<(), String> {
+    if window_label == "main" {
+        Ok(())
+    } else {
+        Err("Only the main window can open files.".into())
+    }
+}
+
+fn require_viewer(window_label: &str) -> Result<String, String> {
+    if is_viewer_label(window_label) {
+        Ok(window_label.to_string())
+    } else {
+        Err("This command belongs to a file window.".into())
+    }
+}
+
+fn viewer_state_of(_label: &str, target: ViewerTarget) -> ViewerState {
+    ViewerState {
+        project_id: target.project_id,
+        project_name: target.project_name,
+        raw_path: target.raw_path,
+        state: target.state,
+        initial: target.initial,
+    }
+}
+
+fn window_title(raw_path: &str, project_name: &str) -> String {
+    let base = raw_path.trim_end_matches('/').rsplit('/').next().unwrap_or(raw_path);
+    format!("{} — {}", base, project_name)
+}
+
+/// Refuses a save payload before decoding it: base64 of at most
+/// [`MAX_WRITE_BYTES`] is at most `4 * ceil(MAX_WRITE_BYTES / 3)` characters.
+/// `write_file` enforces the cap on the decoded bytes too; this stops a
+/// compromised viewer from making the app allocate and decode an arbitrarily
+/// large string first.
+fn check_encoded_len(encoded_len: usize) -> Result<(), String> {
+    if encoded_len > MAX_WRITE_BYTES.div_ceil(3) * 4 {
+        return Err("Files over 1 MiB are read-only in the viewer.".into());
+    }
+    Ok(())
+}
+
+/// The caller's registry entry, or a sentence.
+fn own_target(
+    window: &tauri::Window,
+    registry: &ViewerRegistry,
+) -> Result<(String, ViewerTarget), String> {
+    let label = require_viewer(window.label())?;
+    let target = registry
+        .get(&label)
+        .ok_or_else(|| "This file window is no longer registered.".to_string())?;
+    Ok((label, target))
+}
+
+fn resolved_path(target: &ViewerTarget) -> Result<String, String> {
+    match &target.state {
+        ViewerTargetState::Resolved { container_path } => Ok(container_path.clone()),
+        _ => Err("Choose a file first.".into()),
+    }
+}
+
+/// The one place a viewer command looks up its project (P14).
+fn project_of(state: &AppState, project_id: &str) -> Result<Project, String> {
+    state
+        .projects_store
+        .get(project_id)
+        .ok_or_else(|| "This project no longer exists.".to_string())
+}
+
+/// `action` completes "Start the project before …", e.g. "saving this file".
+async fn running_container_of(project: &Project, action: &str) -> Result<ContainerTarget, String> {
+    let container = ContainerTarget::for_project(project)
+        .ok_or_else(|| not_running_message(action, "files live in its container"))?;
+    require_running(&container, action).await?;
+    Ok(container)
+}
+
+/// The container of the project a viewer window belongs to, if it is running.
+async fn running_container_for(
+    state: &AppState,
+    target: &ViewerTarget,
+    action: &str,
+) -> Result<ContainerTarget, String> {
+    running_container_of(&project_of(state, &target.project_id)?, action).await
+}
+
+/// Raises an existing viewer window and moves it to `location`.
+fn focus_viewer(app: &AppHandle, label: &str, location: Location) {
+    if let Some(existing) = app.get_webview_window(label) {
+        let _ = existing.unminimize();
+        let _ = existing.set_focus();
+        let _ = app.emit_to(label, GOTO_EVENT, location);
+    }
+}
+
+// Nine parameters are fixed by the IPC contract (P10); four injected by Tauri.
+#[allow(clippy::too_many_arguments)]
+#[tauri::command]
+pub async fn open_file_viewer(
+    project_id: String,
+    path: String,
+    line: Option<u32>,
+    col: Option<u32>,
+    end_line: Option<u32>,
+    window: tauri::Window,
+    app: AppHandle,
+    registry: State<'_, ViewerRegistry>,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    require_main(window.label())?;
+    let project = project_of(&state, &project_id)?;
+    let container = running_container_of(&project, "opening files").await?;
+
+    let mounts: Vec<String> = project.paths.iter().map(|p| p.mount_name.clone()).collect();
+    let mut candidates = candidate_paths(&path, &mounts)?;
+    let mut matches = probe_candidates(&container, &candidates).await?;
+    // Not in the project: try home and /tmp, as a second exec so a project file
+    // never becomes a chooser because a namesake sits in /tmp.
+    if matches.is_empty() {
+        let fallbacks = fallback_candidate_paths(&path);
+        if !fallbacks.is_empty() {
+            matches = probe_candidates(&container, &fallbacks).await?;
+            candidates.extend(fallbacks);
+        }
+    }
+    let initial = Location { line, col, end_line };
+
+    let target_state = match matches.len() {
+        0 => ViewerTargetState::NotFound { tried: candidates },
+        1 => ViewerTargetState::Resolved { container_path: matches[0].clone() },
+        _ => ViewerTargetState::Choose { candidates: matches },
+    };
+
+    let title = window_title(&path, &project.name);
+    let target = ViewerTarget {
+        project_id,
+        project_name: project.name.clone(),
+        raw_path: path,
+        state: target_state,
+        initial: initial.clone(),
+    };
+    // Dedupe, stale pruning and the cap are one registry call, so a second click
+    // while the first window is still being built finds it rather than reading
+    // its not-yet-existing window as stale.
+    let label = match registry.reserve(target, |l| app.get_webview_window(l).is_some())? {
+        Reservation::Reserved(label) => label,
+        // Still being built: it opens at its own location in a moment.
+        Reservation::Existing { built: false, .. } => return Ok(()),
+        Reservation::Existing { label, built: true } => {
+            focus_viewer(&app, &label, initial);
+            return Ok(());
+        }
+    };
+    if let Err(e) = open_viewer_window(&app, &label, &title) {
+        registry.remove(&label);
+        return Err(e);
+    }
+    registry.mark_built(&label);
+    Ok(())
+}
+
+#[tauri::command]
+pub async fn viewer_get_state(
+    window: tauri::Window,
+    registry: State<'_, ViewerRegistry>,
+) -> Result<ViewerState, String> {
+    let (label, target) = own_target(&window, &registry)?;
+    Ok(viewer_state_of(&label, target))
+}
+
+#[tauri::command]
+pub async fn viewer_choose_file(
+    index: usize,
+    window: tauri::Window,
+    registry: State<'_, ViewerRegistry>,
+) -> Result<ViewerState, String> {
+    let (label, target) = own_target(&window, &registry)?;
+    let chosen = match &target.state {
+        ViewerTargetState::Choose { candidates } => candidates
+            .get(index)
+            .cloned()
+            .ok_or_else(|| "That choice is no longer available.".to_string())?,
+        _ => return Err("This window is not choosing a file.".into()),
+    };
+    let app = window.app_handle();
+    match registry.choose(&label, chosen, |l| app.get_webview_window(l).is_some())? {
+        Choice::Resolved(updated) => Ok(viewer_state_of(&label, updated)),
+        // Another window already has this file. This window was only ever a
+        // chooser, so hand over to that one and close this one, as a second
+        // click on the same path would have. The error is what this window
+        // shows if the destroy fails.
+        Choice::AlreadyOpen { label: other, .. } => {
+            focus_viewer(app, &other, target.initial);
+            let _ = window.destroy();
+            Err("This file is already open in another window.".into())
+        }
+    }
+}
+
+#[tauri::command]
+pub async fn viewer_read_file(
+    max_bytes: u64,
+    window: tauri::Window,
+    registry: State<'_, ViewerRegistry>,
+    state: State<'_, AppState>,
+) -> Result<ViewerFile, String> {
+    let (_label, target) = own_target(&window, &registry)?;
+    let path = resolved_path(&target)?;
+    let container = running_container_for(&state, &target, "opening files").await?;
+    let cap = max_bytes.clamp(1, MAX_READ_BYTES);
+    let fetched = fetch_container_file(&container, &path, cap).await?;
+    let (editable, readonly_reason) = match validate_container_write_path("File", &path) {
+        Ok(()) => (true, None),
+        Err(reason) => (false, Some(reason)),
+    };
+    Ok(ViewerFile {
+        hash: sha256_hex(&fetched.bytes),
+        contents_base64: BASE64.encode(&fetched.bytes),
+        truncated: fetched.truncated,
+        size: fetched.size,
+        editable,
+        readonly_reason,
+    })
+}
+
+#[tauri::command]
+pub async fn viewer_poll_file(
+    window: tauri::Window,
+    registry: State<'_, ViewerRegistry>,
+    state: State<'_, AppState>,
+) -> Result<ViewerPoll, String> {
+    let (_label, target) = own_target(&window, &registry)?;
+    let path = resolved_path(&target)?;
+    let container = running_container_for(&state, &target, "checking this file for changes").await?;
+    poll_file(&container, &path).await
+}
+
+/// Errors from `write_file` pass through unchanged: the frontend matches the
+/// `write::CONFLICT_PREFIX`/`GONE_PREFIX` prefixes and `READ_ONLY_MESSAGE` (TS copies in
+/// `app/src/viewer/ipcMessages.ts`), and anything else (a full disk) is already a
+/// sentence it shows as is. Success is a `SavedFile`: the new base hash and the hash
+/// the disk held right after the swap.
+#[tauri::command]
+pub async fn viewer_write_file(
+    contents_base64: String,
+    base_hash: String,
+    window: tauri::Window,
+    registry: State<'_, ViewerRegistry>,
+    state: State<'_, AppState>,
+) -> Result<SavedFile, String> {
+    let (_label, target) = own_target(&window, &registry)?;
+    let path = resolved_path(&target)?;
+    validate_container_write_path("File", &path)?;
+    check_encoded_len(contents_base64.len())?;
+    let bytes = BASE64
+        .decode(contents_base64.as_bytes())
+        .map_err(|_| "The editor sent malformed content.".to_string())?;
+    let container = running_container_for(&state, &target, "saving this file").await?;
+    write_file(&container, &state.exec_manager, &path, &bytes, &base_hash).await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn open_is_main_only_and_viewer_commands_are_viewer_only() {
+        assert!(require_main("main").is_ok());
+        assert!(require_main("file-viewer-1").is_err());
+        assert!(require_main("browser-view-x").is_err());
+        assert_eq!(require_viewer("file-viewer-7").unwrap(), "file-viewer-7");
+        assert!(require_viewer("main").is_err());
+        assert!(require_viewer("file-viewer-").is_err());
+    }
+
+    /// Both "no container" refusals a viewer command can give start with the prefix
+    /// the viewer reads as "Container not running" (`ipcMessages.ts`).
+    #[test]
+    fn not_running_refusals_carry_the_shared_prefix() {
+        use crate::commands::file_commands::NOT_RUNNING_PREFIX;
+        let m = not_running_message("checking this file for changes", "files live in its container");
+        assert_eq!(m, "Start the project before checking this file for changes — files live in its container.");
+        assert!(m.starts_with(NOT_RUNNING_PREFIX));
+    }
+
+    #[test]
+    fn a_saved_file_serialises_both_hashes() {
+        let json = serde_json::to_value(SavedFile { hash: "a".into(), disk_hash: "b".into() }).unwrap();
+        assert_eq!(json, serde_json::json!({ "hash": "a", "disk_hash": "b" }));
+    }
+
+    #[test]
+    fn the_title_is_basename_then_project() {
+        assert_eq!(window_title("app/src/lib/urlRelay.ts", "Triple-C"), "urlRelay.ts — Triple-C");
+        assert_eq!(window_title("/workspace/x/README.md", "x"), "README.md — x");
+        assert_eq!(window_title("Makefile", "p"), "Makefile — p");
+    }
+
+    #[test]
+    fn viewer_state_serialises_the_ipc_shape() {
+        let target = ViewerTarget {
+            project_id: "pid".into(),
+            project_name: "P".into(),
+            raw_path: "src/a.rs".into(),
+            state: ViewerTargetState::Resolved { container_path: "/workspace/p/src/a.rs".into() },
+            initial: Location { line: Some(3), col: Some(2), end_line: None },
+        };
+        let json = serde_json::to_value(viewer_state_of("file-viewer-1", target)).unwrap();
+        assert_eq!(json["project_id"], "pid");
+        assert_eq!(json["state"]["kind"], "resolved");
+        assert_eq!(json["state"]["container_path"], "/workspace/p/src/a.rs");
+        assert_eq!(json["initial"]["line"], 3);
+        assert!(json["initial"]["end_line"].is_null());
+    }
+
+    #[test]
+    fn the_encoded_length_is_capped_before_decoding() {
+        let at_cap = BASE64.encode(vec![0u8; MAX_WRITE_BYTES]);
+        assert!(check_encoded_len(at_cap.len()).is_ok());
+        // MAX + 1 and MAX + 2 bytes pad to the same length as MAX; `write_file`'s
+        // decoded check refuses those. The first size this bound itself refuses:
+        let over_cap = BASE64.encode(vec![0u8; MAX_WRITE_BYTES + 3]);
+        assert!(check_encoded_len(over_cap.len()).is_err());
+        assert!(check_encoded_len(at_cap.len() + 1).is_err());
+        assert!(check_encoded_len(0).is_ok());
+    }
+}

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/host_commands.rs

@@ -0,0 +1,557 @@
+//! Commands for host connections (AWS): add, update, remove, identity,
+//! sign-in and the permission check.
+
+use std::future::Future;
+
+use tauri::State;
+
+use crate::aws::permissions::{check_permissions, PermissionReport, SdkPermissionApi};
+use crate::aws::policies::{policy_files, Tier};
+use crate::aws::{caller_identity, sdk_config, sdk_config_for_keys, AwsError, CallerIdentity};
+use crate::models::{
+    validate_connection_name, validate_profile_name, validate_supported_region, AppSettings, AwsAuth,
+    HostConnection, HostKind,
+};
+use crate::storage::secure::{self, AwsKeys};
+use crate::storage::settings_store::SettingsStore;
+use crate::AppState;
+
+fn other(message: impl Into<String>) -> AwsError {
+    AwsError::Other { message: message.into() }
+}
+
+fn check_id(id: &str) -> Result<(), String> {
+    if secure::is_valid_connection_id(id) {
+        Ok(())
+    } else {
+        Err("Invalid connection id".to_string())
+    }
+}
+
+/// What the identity check is asked to authenticate with.
+pub(crate) enum Credentials {
+    /// A named host profile (the connection itself).
+    Profile(HostConnection),
+    /// Keys not yet in the keychain, and the region to call in.
+    Keys(AwsKeys, String),
+}
+
+/// Validate-free core of both add commands: `GetCallerIdentity` first, and
+/// only on success keys are stored and the connection saved. An expired SSO
+/// session on a profile still saves (the UI then offers "Sign in").
+pub(crate) async fn add_connection_with<I, Fut>(
+    conn: HostConnection,
+    keys: Option<AwsKeys>,
+    identity: I,
+    store_keys: impl Fn(&str, &AwsKeys) -> Result<(), String>,
+    delete_keys: impl Fn(&str) -> Result<(), String>,
+    settings: &SettingsStore,
+) -> Result<HostConnection, AwsError>
+where
+    I: FnOnce(Credentials) -> Fut,
+    Fut: Future<Output = Result<CallerIdentity, AwsError>>,
+{
+    let HostKind::Aws { auth, default_region } = &conn.kind;
+    let credentials = match (&keys, auth) {
+        (Some(k), AwsAuth::Keys { .. }) => Credentials::Keys(k.clone(), default_region.clone()),
+        (None, AwsAuth::Profile { .. }) => Credentials::Profile(conn.clone()),
+        _ => return Err(other("Connection credentials do not match its auth method")),
+    };
+    match identity(credentials).await {
+        Ok(_) => {}
+        Err(AwsError::SsoExpired { .. }) if keys.is_none() => {}
+        Err(e) => return Err(e),
+    }
+
+    if let Some(k) = &keys {
+        store_keys(&conn.id, k).map_err(other)?;
+    }
+    if let Err(e) = settings.modify(|all| {
+        all.hosts.push(conn.clone());
+        Ok(())
+    }) {
+        if keys.is_some() {
+            let _ = delete_keys(&conn.id);
+        }
+        return Err(other(e));
+    }
+    Ok(conn)
+}
+
+/// Removes the stored connection with this id, however malformed its other
+/// fields are (a broken entry must stay removable). Its keychain entry is
+/// deleted only for a `Keys` connection whose `keyring_ref` is its own valid id.
+pub(crate) fn remove_connection_with(
+    id: &str,
+    delete_keys: impl Fn(&str) -> Result<(), String>,
+    settings: &SettingsStore,
+) -> Result<AppSettings, String> {
+    check_id(id)?;
+    let existing = settings
+        .get()
+        .hosts
+        .into_iter()
+        .find(|h| h.id == id)
+        .ok_or_else(|| "Connection not found".to_string())?;
+    let HostKind::Aws { auth, .. } = &existing.kind;
+    if let AwsAuth::Keys { keyring_ref } = auth {
+        if keyring_ref == id && secure::is_valid_connection_id(keyring_ref) {
+            delete_keys(keyring_ref)?;
+        }
+    }
+    settings
+        .modify(|s| {
+            s.hosts.retain(|h| h.id != id);
+            Ok(())
+        })
+        .map(|(saved, ())| saved)
+}
+
+async fn real_identity(c: Credentials) -> Result<CallerIdentity, AwsError> {
+    let cfg = match c {
+        Credentials::Profile(conn) => {
+            let HostKind::Aws { default_region, .. } = &conn.kind;
+            sdk_config(&conn, default_region).await?
+        }
+        Credentials::Keys(keys, region) => sdk_config_for_keys(&keys, &region),
+    };
+    caller_identity(&cfg).await
+}
+
+pub(crate) fn aws_conn(id: &str, settings: &AppSettings) -> Result<HostConnection, String> {
+    check_id(id)?;
+    let conn = settings
+        .hosts
+        .iter()
+        .find(|h| h.id == id)
+        .cloned()
+        .ok_or_else(|| "Connection not found".to_string())?;
+    // Defense in depth: stored values are re-checked before they reach the
+    // keychain, the SDK or a subprocess.
+    let HostKind::Aws { auth, default_region } = &conn.kind;
+    validate_supported_region(default_region)?;
+    match auth {
+        AwsAuth::Profile { name } => {
+            validate_profile_name(name)?;
+        }
+        AwsAuth::Keys { keyring_ref } if keyring_ref != id => {
+            return Err("Connection's keychain reference does not match its id".to_string());
+        }
+        AwsAuth::Keys { .. } => {}
+    }
+    Ok(conn)
+}
+
+fn validated(name: &str, region: &str) -> Result<(String, String), AwsError> {
+    Ok((
+        validate_connection_name(name).map_err(other)?,
+        validate_supported_region(region).map_err(other)?,
+    ))
+}
+
+#[tauri::command]
+pub async fn add_aws_profile_connection(
+    name: String,
+    profile: String,
+    default_region: String,
+    state: State<'_, AppState>,
+) -> Result<HostConnection, AwsError> {
+    let (name, default_region) = validated(&name, &default_region)?;
+    let profile = validate_profile_name(&profile).map_err(other)?;
+    let conn = HostConnection {
+        id: uuid::Uuid::new_v4().to_string(),
+        name,
+        kind: HostKind::Aws { auth: AwsAuth::Profile { name: profile }, default_region },
+    };
+    add_connection_with(
+        conn,
+        None,
+        real_identity,
+        secure::store_aws_keys,
+        secure::delete_aws_keys,
+        &state.settings_store,
+    )
+    .await
+}
+
+#[tauri::command]
+pub async fn add_aws_keys_connection(
+    name: String,
+    access_key_id: String,
+    secret_access_key: String,
+    session_token: Option<String>,
+    default_region: String,
+    state: State<'_, AppState>,
+) -> Result<HostConnection, AwsError> {
+    let (name, default_region) = validated(&name, &default_region)?;
+    let access_key_id = access_key_id.trim().to_string();
+    let secret_access_key = secret_access_key.trim().to_string();
+    let session_token = session_token.map(|t| t.trim().to_string()).filter(|t| !t.is_empty());
+    if access_key_id.is_empty() || secret_access_key.is_empty() {
+        return Err(other("Access key ID and secret access key are required"));
+    }
+    let id = uuid::Uuid::new_v4().to_string();
+    let conn = HostConnection {
+        id: id.clone(),
+        name,
+        kind: HostKind::Aws { auth: AwsAuth::Keys { keyring_ref: id }, default_region },
+    };
+    let keys = AwsKeys { access_key_id, secret_access_key, session_token };
+    add_connection_with(
+        conn,
+        Some(keys),
+        real_identity,
+        secure::store_aws_keys,
+        secure::delete_aws_keys,
+        &state.settings_store,
+    )
+    .await
+}
+
+#[tauri::command]
+pub async fn update_aws_connection(
+    id: String,
+    name: String,
+    default_region: String,
+    state: State<'_, AppState>,
+) -> Result<HostConnection, AwsError> {
+    let (name, region) = validated(&name, &default_region)?;
+    let (_, updated) = state
+        .settings_store
+        .modify(|settings| {
+            aws_conn(&id, settings)?;
+            let conn = settings.hosts.iter_mut().find(|h| h.id == id).expect("checked above");
+            conn.name = name;
+            let HostKind::Aws { default_region, .. } = &mut conn.kind;
+            *default_region = region;
+            Ok(conn.clone())
+        })
+        .map_err(other)?;
+    Ok(updated)
+}
+
+#[tauri::command]
+pub async fn remove_host_connection(
+    id: String,
+    state: State<'_, AppState>,
+) -> Result<AppSettings, String> {
+    remove_connection_with(&id, secure::delete_aws_keys, &state.settings_store)
+}
+
+#[tauri::command]
+pub async fn aws_connection_identity(
+    id: String,
+    state: State<'_, AppState>,
+) -> Result<CallerIdentity, AwsError> {
+    let conn = aws_conn(&id, &state.settings_store.get()).map_err(other)?;
+    let HostKind::Aws { default_region, .. } = &conn.kind;
+    let cfg = sdk_config(&conn, default_region).await?;
+    caller_identity(&cfg).await
+}
+
+#[tauri::command]
+pub async fn aws_connection_sso_login(
+    id: String,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let conn = aws_conn(&id, &state.settings_store.get())?;
+    let HostKind::Aws { auth, .. } = &conn.kind;
+    let AwsAuth::Profile { name } = auth else {
+        return Err("Only profile connections use SSO".to_string());
+    };
+    let name = validate_profile_name(name)?;
+    super::aws_commands::run_sso_login(&name).await
+}
+
+#[tauri::command]
+pub async fn check_aws_permissions(
+    id: String,
+    region: Option<String>,
+    state: State<'_, AppState>,
+) -> Result<PermissionReport, AwsError> {
+    let conn = aws_conn(&id, &state.settings_store.get()).map_err(other)?;
+    let HostKind::Aws { default_region, .. } = &conn.kind;
+    let region = match region {
+        Some(r) => validate_supported_region(&r).map_err(other)?,
+        None => default_region.clone(),
+    };
+    let cfg = sdk_config(&conn, &region).await?;
+    let identity = caller_identity(&cfg).await?;
+    let api = SdkPermissionApi::new(&cfg);
+    check_permissions(&api, &identity, &region).await
+}
+
+/// One policy file of a tier: its file name under `aws/policies/` and its
+/// JSON, verbatim.
+#[derive(Debug, Clone, serde::Serialize, PartialEq, Eq)]
+pub struct PolicyFile {
+    pub name: String,
+    pub json: String,
+}
+
+/// Every policy file `tier` needs, in order; all of them are required (D7).
+#[tauri::command]
+pub fn aws_policy_document(tier: Tier) -> Vec<PolicyFile> {
+    policy_files(tier)
+        .iter()
+        .map(|(name, json)| PolicyFile {
+            name: name.to_string(),
+            json: json.to_string(),
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::cell::RefCell;
+
+    fn profile_conn() -> HostConnection {
+        HostConnection {
+            id: "c1".into(),
+            name: "Prod".into(),
+            kind: HostKind::Aws {
+                auth: AwsAuth::Profile { name: "dev".into() },
+                default_region: "us-west-2".into(),
+            },
+        }
+    }
+
+    fn keys_conn() -> HostConnection {
+        HostConnection {
+            id: "c2".into(),
+            name: "K".into(),
+            kind: HostKind::Aws {
+                auth: AwsAuth::Keys { keyring_ref: "c2".into() },
+                default_region: "us-west-2".into(),
+            },
+        }
+    }
+
+    fn keys() -> AwsKeys {
+        AwsKeys { access_key_id: "AKIA".into(), secret_access_key: "s".into(), session_token: None }
+    }
+
+    fn ident() -> CallerIdentity {
+        CallerIdentity { account: "1".into(), arn: "arn:aws:iam::1:user/u".into(), user_id: "U".into() }
+    }
+
+    fn store_in(dir: &tempfile::TempDir) -> SettingsStore {
+        SettingsStore::at_path(dir.path().join("settings.json"))
+    }
+
+    #[tokio::test]
+    async fn adding_saves_nothing_when_identity_fails() {
+        let dir = tempfile::tempdir().unwrap();
+        let settings = store_in(&dir);
+        let calls = RefCell::new(Vec::<String>::new());
+        let err = add_connection_with(
+            keys_conn(),
+            Some(keys()),
+            |_| async { Err(AwsError::InvalidCredentials { message: "bad".into() }) },
+            |id, _| { calls.borrow_mut().push(format!("store {id}")); Ok(()) },
+            |id| { calls.borrow_mut().push(format!("delete {id}")); Ok(()) },
+            &settings,
+        )
+        .await
+        .unwrap_err();
+        assert!(matches!(err, AwsError::InvalidCredentials { .. }));
+        assert!(settings.get().hosts.is_empty());
+        assert!(!dir.path().join("settings.json").exists());
+        assert!(calls.borrow().is_empty(), "{:?}", calls.borrow());
+    }
+
+    #[tokio::test]
+    async fn an_sso_expired_profile_is_still_saved() {
+        let dir = tempfile::tempdir().unwrap();
+        let settings = store_in(&dir);
+        let saved = add_connection_with(
+            profile_conn(),
+            None,
+            |_| async { Err(AwsError::SsoExpired { profile: "dev".into() }) },
+            |_, _| Ok(()),
+            |_| Ok(()),
+            &settings,
+        )
+        .await
+        .unwrap();
+        assert_eq!(settings.get().hosts, vec![saved]);
+    }
+
+    #[tokio::test]
+    async fn a_successful_keys_add_stores_keys_then_settings() {
+        let dir = tempfile::tempdir().unwrap();
+        let settings = store_in(&dir);
+        let calls = RefCell::new(Vec::<String>::new());
+        let saved = add_connection_with(
+            keys_conn(),
+            Some(keys()),
+            |c| async move {
+                assert!(matches!(c, Credentials::Keys(..)));
+                Ok(ident())
+            },
+            |id, _| { calls.borrow_mut().push(format!("store {id}")); Ok(()) },
+            |id| { calls.borrow_mut().push(format!("delete {id}")); Ok(()) },
+            &settings,
+        )
+        .await
+        .unwrap();
+        assert_eq!(*calls.borrow(), vec!["store c2".to_string()]);
+        assert_eq!(settings.get().hosts, vec![saved]);
+    }
+
+    #[tokio::test]
+    async fn keys_are_removed_if_saving_settings_fails() {
+        let dir = tempfile::tempdir().unwrap();
+        // The parent directory does not exist, so saving fails.
+        let settings = SettingsStore::at_path(dir.path().join("missing/settings.json"));
+        let calls = RefCell::new(Vec::<String>::new());
+        let err = add_connection_with(
+            keys_conn(),
+            Some(keys()),
+            |_| async { Ok(ident()) },
+            |id, _| { calls.borrow_mut().push(format!("store {id}")); Ok(()) },
+            |id| { calls.borrow_mut().push(format!("delete {id}")); Ok(()) },
+            &settings,
+        )
+        .await
+        .unwrap_err();
+        assert!(matches!(err, AwsError::Other { .. }));
+        assert_eq!(*calls.borrow(), vec!["store c2".to_string(), "delete c2".to_string()]);
+        assert!(settings.get().hosts.is_empty(), "no unsaved connection in memory");
+    }
+
+    #[tokio::test]
+    async fn a_non_sso_identity_error_on_a_profile_saves_nothing() {
+        let dir = tempfile::tempdir().unwrap();
+        let settings = store_in(&dir);
+        let err = add_connection_with(
+            profile_conn(),
+            None,
+            |_| async { Err(AwsError::ProfileNotFound { profile: "dev".into() }) },
+            |_, _| Ok(()),
+            |_| Ok(()),
+            &settings,
+        )
+        .await
+        .unwrap_err();
+        assert!(matches!(err, AwsError::ProfileNotFound { .. }));
+        assert!(settings.get().hosts.is_empty());
+        assert!(!dir.path().join("settings.json").exists());
+    }
+
+    #[tokio::test]
+    async fn a_failing_store_keys_saves_nothing() {
+        let dir = tempfile::tempdir().unwrap();
+        let settings = store_in(&dir);
+        let deletes = RefCell::new(0);
+        let err = add_connection_with(
+            keys_conn(),
+            Some(keys()),
+            |_| async { Ok(ident()) },
+            |_, _| Err("keychain locked".to_string()),
+            |_| { *deletes.borrow_mut() += 1; Ok(()) },
+            &settings,
+        )
+        .await
+        .unwrap_err();
+        assert!(matches!(err, AwsError::Other { .. }));
+        assert!(settings.get().hosts.is_empty());
+        assert!(!dir.path().join("settings.json").exists());
+    }
+
+    #[test]
+    fn a_keys_connection_whose_keyring_ref_differs_from_its_id_is_refused() {
+        let mut s = AppSettings::default();
+        let mut c = keys_conn();
+        c.kind = HostKind::Aws {
+            auth: AwsAuth::Keys { keyring_ref: "other".into() },
+            default_region: "us-west-2".into(),
+        };
+        s.hosts.push(c);
+        assert!(aws_conn("c2", &s).is_err());
+        s.hosts = vec![keys_conn()];
+        assert!(aws_conn("c2", &s).is_ok());
+    }
+
+    #[test]
+    fn stored_regions_and_profiles_are_revalidated() {
+        let with = |profile: &str, region: &str| {
+            let mut c = profile_conn();
+            c.kind = HostKind::Aws {
+                auth: AwsAuth::Profile { name: profile.into() },
+                default_region: region.into(),
+            };
+            let mut s = AppSettings::default();
+            s.hosts.push(c);
+            s
+        };
+        assert!(aws_conn("c1", &with("dev", "us-west-2")).is_ok());
+        assert!(aws_conn("c1", &with("dev", "not a region")).is_err());
+        assert!(aws_conn("c1", &with("a b", "us-west-2")).is_err());
+    }
+
+    #[test]
+    fn a_connection_with_an_invalid_stored_region_can_still_be_removed() {
+        let dir = tempfile::tempdir().unwrap();
+        let settings = store_in(&dir);
+        let mut c = keys_conn();
+        c.kind = HostKind::Aws {
+            auth: AwsAuth::Keys { keyring_ref: "c2".into() },
+            default_region: "not a region".into(),
+        };
+        settings.update(AppSettings { hosts: vec![c, profile_conn()], ..AppSettings::default() }).unwrap();
+        let deleted = RefCell::new(Vec::<String>::new());
+        let after = remove_connection_with(
+            "c2",
+            |id| { deleted.borrow_mut().push(id.to_string()); Ok(()) },
+            &settings,
+        )
+        .unwrap();
+        assert_eq!(after.hosts, vec![profile_conn()]);
+        assert_eq!(settings.get().hosts, vec![profile_conn()]);
+        assert_eq!(*deleted.borrow(), vec!["c2".to_string()]);
+    }
+
+    #[test]
+    fn removal_leaves_the_keychain_alone_when_keyring_ref_is_not_the_id() {
+        let dir = tempfile::tempdir().unwrap();
+        let settings = store_in(&dir);
+        let mut c = keys_conn();
+        c.kind = HostKind::Aws {
+            auth: AwsAuth::Keys { keyring_ref: "someone-else".into() },
+            default_region: "us-west-2".into(),
+        };
+        settings.update(AppSettings { hosts: vec![c], ..AppSettings::default() }).unwrap();
+        remove_connection_with("c2", |_| panic!("must not touch the keychain"), &settings).unwrap();
+        assert!(settings.get().hosts.is_empty());
+        assert!(remove_connection_with("c2", |_| Ok(()), &settings).is_err());
+        assert!(remove_connection_with("bad id!", |_| Ok(()), &settings).is_err());
+    }
+
+    #[test]
+    fn china_and_govcloud_regions_are_refused_for_connections() {
+        for r in ["cn-north-1", "us-gov-west-1"] {
+            let e = validated("Prod", r).unwrap_err();
+            assert!(matches!(&e, AwsError::Other { message } if message == "China and GovCloud regions aren't supported yet."), "{e:?}");
+        }
+        assert!(validated("Prod", "eu-west-1").is_ok());
+    }
+
+    #[test]
+    fn the_policy_document_is_every_file_of_the_tier() {
+        let admin = aws_policy_document(Tier::EnvironmentAdmin);
+        let names: Vec<&str> = admin.iter().map(|f| f.name.as_str()).collect();
+        assert_eq!(names, ["environment-admin.json", "environment-admin-network.json"]);
+        for f in &admin {
+            serde_json::from_str::<serde_json::Value>(&f.json).expect("policy JSON");
+        }
+        let ws = aws_policy_document(Tier::WorkspaceUser);
+        assert_eq!(ws.len(), 1);
+        assert_eq!(ws[0].name, "workspace-user.json");
+        assert_eq!(
+            serde_json::to_value(&ws[0]).unwrap()["name"],
+            "workspace-user.json"
+        );
+    }
+}

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,21 @@
+pub mod auth_bridge_commands;
+pub mod auth_token_commands;
 pub mod aws_commands;
 pub mod docker_commands;
+pub mod environment_commands;
 pub mod file_commands;
+pub mod file_viewer_commands;
+pub mod gateway_commands;
 pub mod help_commands;
-pub mod mcp_commands;
+pub mod host_commands;
+pub mod inspect_commands;
+pub mod install_helper_commands;
+pub mod marketplace_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,186 @@ pub async fn get_settings(state: State<'_, AppState>) -> Result<AppSettings, Str
     Ok(state.settings_store.get())
 }
 
-#[tauri::command]
-pub async fn update_settings(
-    settings: AppSettings,
-    state: State<'_, AppState>,
-) -> Result<AppSettings, String> {
-    state.settings_store.update(settings)
+/// 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 merges `/tmp/.host-ssh` into `~/.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(())
+}
+
+/// Marketplace state is written only by the marketplace commands
+/// (`commands/marketplace_commands.rs`), each of which returns fresh settings.
+/// Every other settings save posts the frontend's copy back whole, and that
+/// copy can predate an install made a moment ago, so what is stored wins.
+/// `apply_settings_import` is the one caller that replaces it, explicitly.
+pub(crate) fn restore_marketplace_fields(incoming: &mut AppSettings, stored: &AppSettings) {
+    incoming.marketplace_accounts = stored.marketplace_accounts.clone();
+    incoming.marketplaces = stored.marketplaces.clone();
+    incoming.global_marketplace_installs = stored.global_marketplace_installs.clone();
+}
+
+/// Host connections change only through `host_commands` (which validates
+/// them and owns their keychain entries) and settings import, never through
+/// a settings save the frontend posts back.
+pub(crate) fn restore_host_fields(incoming: &mut AppSettings, stored: &AppSettings) {
+    incoming.hosts = stored.hosts.clone();
 }
 
 #[tauri::command]
-pub async fn pull_image(
-    image_name: String,
-    app_handle: tauri::AppHandle,
-) -> Result<(), String> {
+pub async fn update_settings(
+    mut settings: AppSettings,
+    state: State<'_, AppState>,
+) -> Result<AppSettings, String> {
+    let before = state.settings_store.get();
+
+    validate_settings_update(&before, &settings)?;
+    restore_marketplace_fields(&mut settings, &before);
+    restore_host_fields(&mut settings, &before);
+
+    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> {
     use tauri::Emitter;
     docker::pull_image(&image_name, move |msg| {
         let _ = app_handle.emit("image-pull-progress", msg);
@@ -67,6 +235,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 +355,146 @@ 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);
+    }
+
+    #[test]
+    fn a_stale_settings_save_cannot_overwrite_marketplace_state() {
+        use crate::models::marketplace::Marketplace;
+        let mut stored = AppSettings::default();
+        stored.marketplaces.push(Marketplace {
+            id: "m1".into(),
+            name: "Team".into(),
+            url: "https://example.invalid/r.git".into(),
+            branch: None,
+            account_id: None,
+        });
+        // The frontend's copy predates the marketplace being added.
+        let mut incoming = AppSettings::default();
+        incoming.auto_check_updates = false;
+
+        restore_marketplace_fields(&mut incoming, &stored);
+
+        assert_eq!(incoming.marketplaces, stored.marketplaces);
+        assert!(
+            !incoming.auto_check_updates,
+            "the edit the save was for still applies"
+        );
+    }
+
+    #[test]
+    fn update_settings_cannot_change_hosts() {
+        use crate::models::{AwsAuth, HostConnection, HostKind};
+        let conn = |id: &str, region: &str| HostConnection {
+            id: id.into(),
+            name: "Prod".into(),
+            kind: HostKind::Aws {
+                auth: AwsAuth::Profile { name: "dev".into() },
+                default_region: region.into(),
+            },
+        };
+        let mut stored = AppSettings::default();
+        stored.hosts.push(conn("c1", "us-west-2"));
+        let mut incoming = AppSettings::default();
+        incoming.hosts = vec![conn("c1", "not a region"), conn("evil", "us-east-1")];
+        incoming.auto_check_updates = false;
+
+        restore_host_fields(&mut incoming, &stored);
+
+        assert_eq!(incoming.hosts, stored.hosts);
+        assert!(!incoming.auto_check_updates);
+    }
+}

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

@@ -1,15 +1,76 @@
 use tauri::{AppHandle, Emitter, State};
 
 use crate::commands::aws_commands;
+use crate::host::ContainerTarget;
 use crate::models::{Backend, BedrockAuthMethod, Project};
 use crate::AppState;
 
 /// Build the command to run in the container terminal.
 ///
-/// For Bedrock Profile projects, wraps `claude` in a bash script that validates
-/// the AWS session first. If the SSO session is expired, runs `aws sso login`
-/// so the user can re-authenticate (the URL is clickable via xterm.js WebLinksAddon).
-fn build_terminal_cmd(project: &Project, state: &AppState, session_name: Option<&str>) -> Vec<String> {
+/// Always a `bash -c` script, because every session runs [`UPDATE_PRELUDE`]
+/// before `exec claude`. For Bedrock Profile projects the script additionally
+/// validates the AWS session first, and runs `aws sso login` if it has expired
+/// so the user can re-authenticate (the URL is clickable via xterm.js
+/// WebLinksAddon).
+fn build_terminal_cmd(
+    project: &Project,
+    state: &AppState,
+    session_name: Option<&str>,
+    resume_session_id: Option<&str>,
+) -> Vec<String> {
+    let settings = state.settings_store.get();
+    build_claude_terminal_cmd(
+        project,
+        settings.global_aws.aws_profile.as_deref(),
+        session_name,
+        resume_session_id,
+    )
+}
+
+/// Shell line run immediately before `exec claude` in every Claude terminal
+/// session.
+///
+/// `container/entrypoint.sh` already runs `claude update` when the container
+/// starts, but containers here use a stop/start (and often just keep running)
+/// model, so a long-lived container's CLI goes stale between restarts. Running
+/// it per session is what keeps a week-old container current.
+///
+/// Deliberately non-fatal and time-bounded: `|| echo` swallows a failure (no
+/// network, npm registry down) so a session always opens, and `timeout 60`
+/// bounds how long a user waits for a terminal.
+///
+/// **`flock` is load-bearing, not tidiness.** Nothing serialises this against
+/// the entrypoint's own `claude update`, and the entrypoint prints "container
+/// ready" only *after* its copy finishes — so "start the project, open a tab"
+/// races two updaters against the same `~/.claude/bin` install, as does
+/// opening two tabs at once. `|| echo` would then hide a half-written install
+/// behind a friendly message and the very next line (`exec claude`) would run
+/// it. `-w 90` gives the entrypoint's `timeout 120` copy room to finish rather
+/// than failing the wait, and `-E 0` makes losing the race a success: the
+/// other holder just updated, so there is nothing left to do.
+pub(crate) const UPDATE_PRELUDE: &str = concat!(
+    "flock -w 90 -E 0 /tmp/.triple-c-claude-update.lock ",
+    r#"timeout 60 claude update 2>&1 || echo "(update skipped — continuing)""#,
+);
+
+/// Single-quote one argument for interpolation into a shell script string.
+fn shell_quote_arg(arg: &str) -> String {
+    format!(" '{}'", arg.replace('\'', "'\\''"))
+}
+
+/// The testable core of [`build_terminal_cmd`], taking the resolved global AWS
+/// profile rather than the whole [`AppState`].
+///
+/// `resume_session_id` adds `--resume <id>` (flag spelling checked against the
+/// CLI in the container image) and drops `-n`: the resumed conversation keeps
+/// the name it already has, and the tab label the caller passes as
+/// `session_name` — often just "resume" — must not overwrite it.
+fn build_claude_terminal_cmd(
+    project: &Project,
+    global_aws_profile: Option<&str>,
+    session_name: Option<&str>,
+    resume_session_id: Option<&str>,
+) -> Vec<String> {
     let is_bedrock_profile = project.backend == Backend::Bedrock
         && project
             .bedrock_config
@@ -17,36 +78,32 @@ 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();
+
+    // The args are interpolated into a shell script string, so single-quote
+    // each one.
+    let session_flags = match resume_session_id {
+        Some(id) => format!(" --resume{}", shell_quote_arg(id)),
+        None => session_name
+            .filter(|n| !n.is_empty())
+            .map(|n| format!(" -n{}", shell_quote_arg(n)))
+            .unwrap_or_default(),
+    };
+    let permission_flags: String = permission_args.iter().map(|a| shell_quote_arg(a)).collect();
+    let claude_cmd = format!("exec claude{}{}", permission_flags, session_flags);
+
     if !is_bedrock_profile {
-        let mut cmd = vec!["claude".to_string()];
-        if project.full_permissions {
-            cmd.push("--dangerously-skip-permissions".to_string());
-        }
-        if let Some(name) = session_name {
-            if !name.is_empty() {
-                cmd.push("-n".to_string());
-                cmd.push(name.to_string());
-            }
-        }
-        return cmd;
+        return vec![
+            "bash".to_string(),
+            "-c".to_string(),
+            format!("{}\n{}\n", UPDATE_PRELUDE, claude_cmd),
+        ];
     }
 
-    let profile = aws_commands::resolve_profile_for_project(
-        project,
-        state.settings_store.get().global_aws.aws_profile.as_deref(),
-    );
+    let profile = aws_commands::resolve_profile_for_project(project, global_aws_profile);
 
     // Build a bash wrapper that validates credentials, re-auths if needed,
     // then exec's into claude.
-    let name_flag = session_name
-        .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)
-    };
 
     let script = format!(
         r#"
@@ -73,9 +130,11 @@ else
         echo ""
     fi
 fi
+{update_prelude}
 {claude_cmd}
 "#,
         profile = profile,
+        update_prelude = UPDATE_PRELUDE,
         claude_cmd = claude_cmd
     );
 
@@ -92,6 +151,7 @@ pub async fn open_terminal_session(
     session_id: String,
     session_type: Option<String>,
     session_name: Option<String>,
+    resume_session_id: Option<String>,
     app_handle: AppHandle,
     state: State<'_, AppState>,
 ) -> Result<(), String> {
@@ -100,14 +160,24 @@ pub async fn open_terminal_session(
         .get(&project_id)
         .ok_or_else(|| format!("Project {} not found", project_id))?;
 
-    let container_id = project
-        .container_id
-        .as_ref()
+    let target = ContainerTarget::for_project(&project)
         .ok_or_else(|| "Container not running".to_string())?;
 
+    if let Some(id) = resume_session_id.as_deref() {
+        crate::commands::inspect_commands::validate_session_id(id)?;
+    }
+
     let cmd = match session_type.as_deref() {
+        Some("bash") if resume_session_id.is_some() => {
+            return Err("Only a Claude session can resume a conversation".to_string());
+        }
         Some("bash") => vec!["bash".to_string(), "-l".to_string()],
-        _ => build_terminal_cmd(&project, &state, session_name.as_deref()),
+        _ => build_terminal_cmd(
+            &project,
+            &state,
+            session_name.as_deref(),
+            resume_session_id.as_deref(),
+        ),
     };
 
     let output_event = format!("terminal-output-{}", session_id);
@@ -118,7 +188,7 @@ pub async fn open_terminal_session(
     state
         .exec_manager
         .create_session(
-            container_id,
+            &target,
             &session_id,
             cmd,
             move |data| {
@@ -169,7 +239,7 @@ pub async fn paste_image_to_terminal(
     image_data: Vec<u8>,
     state: State<'_, AppState>,
 ) -> Result<String, String> {
-    let container_id = state.exec_manager.get_container_id(&session_id).await?;
+    let target = state.exec_manager.get_target(&session_id).await?;
 
     let timestamp = std::time::SystemTime::now()
         .duration_since(std::time::UNIX_EPOCH)
@@ -179,7 +249,93 @@ pub async fn paste_image_to_terminal(
 
     state
         .exec_manager
-        .write_file_to_container(&container_id, &file_name, &image_data)
+        .write_file_to_container(&target, &file_name, &image_data)
+        .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 target = state.exec_manager.get_target(&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::host::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.
+    target
+        .exec_oneshot(vec![
+            "mkdir".to_string(),
+            "-p".to_string(),
+            "/tmp/triple-c-drops".to_string(),
+        ])
+        .await?;
+
+    let file_name = format!("triple-c-drops/{}", base);
+    target
+        .upload_host_file(&host_path, "/tmp", &file_name)
         .await
 }
 
@@ -188,8 +344,8 @@ pub async fn start_audio_bridge(
     session_id: String,
     state: State<'_, AppState>,
 ) -> Result<(), String> {
-    // Get container_id from the terminal session
-    let container_id = state.exec_manager.get_container_id(&session_id).await?;
+    // Get the container from the terminal session
+    let target = state.exec_manager.get_target(&session_id).await?;
 
     // Create audio bridge exec session with ID "audio-{session_id}"
     // The loop handles reconnection when the FIFO reader (fake rec) is killed and restarted
@@ -203,7 +359,7 @@ pub async fn start_audio_bridge(
     state
         .exec_manager
         .create_session_with_tty(
-            &container_id,
+            &target,
             &audio_session_id,
             cmd,
             false,
@@ -232,3 +388,197 @@ pub async fn stop_audio_bridge(
     state.exec_manager.close_session(&audio_session_id).await;
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{build_claude_terminal_cmd, UPDATE_PRELUDE};
+    use crate::models::Project;
+
+    /// 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"`).
+    /// A `Project` with only the fields these tests care about set; the rest
+    /// come through serde so the test does not have to track every field.
+    fn project(backend: &str, bedrock_config: serde_json::Value) -> Project {
+        serde_json::from_value(serde_json::json!({
+            "id": "p1",
+            "name": "Test",
+            "paths": [],
+            "container_id": null,
+            "status": "running",
+            "backend": backend,
+            "bedrock_config": bedrock_config,
+            "ollama_config": null,
+            "openai_compatible_config": null,
+            "allow_docker_access": false,
+            "full_permissions": false,
+            "ssh_key_path": null,
+            "git_user_name": null,
+            "git_user_email": null,
+            "created_at": "now",
+            "updated_at": "now"
+        }))
+        .expect("test project deserializes")
+    }
+
+    /// Every Claude session updates the CLI before launching it.
+    ///
+    /// `container/entrypoint.sh` only updates at container *start*, and these
+    /// containers are long-lived, so a stale CLI is the normal case without
+    /// this. The plain (non-Bedrock) path therefore has to be a `bash -c`
+    /// wrapper rather than a bare `claude` argv.
+    #[test]
+    fn build_terminal_cmd_updates_before_launching_claude() {
+        let cmd = build_claude_terminal_cmd(&project("anthropic", serde_json::Value::Null), None, None, None);
+
+        assert_eq!(cmd[0], "bash");
+        assert_eq!(cmd[1], "-c");
+        assert!(
+            cmd[2].contains(UPDATE_PRELUDE),
+            "plain path must run the update prelude: {}",
+            cmd[2]
+        );
+        assert!(cmd[2].contains("exec claude"), "got: {}", cmd[2]);
+        // The update has to happen *before* the exec, which never returns.
+        assert!(
+            cmd[2].find(UPDATE_PRELUDE).unwrap() < cmd[2].find("exec claude").unwrap(),
+            "prelude must precede the exec: {}",
+            cmd[2]
+        );
+        assert!(
+            UPDATE_PRELUDE.contains("timeout 60") && UPDATE_PRELUDE.contains("||"),
+            "the update must stay time-bounded and non-fatal"
+        );
+    }
+
+    /// The session name is interpolated into a shell script, so a quote in it
+    /// must not break out of its single-quoted argument.
+    #[test]
+    fn build_terminal_cmd_escapes_a_quoted_session_name() {
+        let cmd = build_claude_terminal_cmd(
+            &project("anthropic", serde_json::Value::Null),
+            None,
+            Some("Bob's tab; rm -rf /"),
+            None,
+        );
+
+        assert!(
+            cmd[2].contains(r#"exec claude -n 'Bob'\''s tab; rm -rf /'"#),
+            "session name must be single-quote escaped: {}",
+            cmd[2]
+        );
+    }
+
+    /// Permission flags travel the same escaped path, and an empty name adds
+    /// no `-n` at all.
+    #[test]
+    fn build_terminal_cmd_quotes_permission_flags_and_omits_an_empty_name() {
+        let mut p = project("anthropic", serde_json::Value::Null);
+        p.full_permissions = true;
+        let cmd = build_claude_terminal_cmd(&p, None, Some(""), None);
+
+        assert!(
+            cmd[2].contains("exec claude '--dangerously-skip-permissions'\n"),
+            "got: {}",
+            cmd[2]
+        );
+        assert!(!cmd[2].contains(" -n "), "empty name must add no flag: {}", cmd[2]);
+    }
+
+    /// Auto mode is passed as a `--permission-mode` value, not its own flag.
+    #[test]
+    fn build_terminal_cmd_passes_auto_permission_mode() {
+        let mut p = project("anthropic", serde_json::Value::Null);
+        p.permission_mode = Some(crate::models::project::PermissionMode::Auto);
+        let cmd = build_claude_terminal_cmd(&p, None, None, None);
+
+        assert!(
+            cmd[2].contains("exec claude '--permission-mode' 'auto'"),
+            "got: {}",
+            cmd[2]
+        );
+    }
+
+    /// The Bedrock-profile path keeps its AWS validation *and* gains the
+    /// prelude, immediately before the exec.
+    #[test]
+    fn build_terminal_cmd_bedrock_validates_aws_and_updates() {
+        let cmd = build_claude_terminal_cmd(
+            &project("bedrock", serde_json::json!({
+                "auth_method": "profile",
+                "aws_region": "us-east-1",
+                "aws_profile": "acme",
+                "model_id": null,
+                "disable_prompt_caching": false
+            })),
+            None,
+            Some("it's fine"),
+            None,
+        );
+
+        assert_eq!(cmd[0], "bash");
+        let script = &cmd[2];
+        assert!(script.contains("aws sts get-caller-identity --profile 'acme'"), "got: {}", script);
+        assert!(script.contains("triple-c-sso-refresh"), "got: {}", script);
+        assert!(script.contains(UPDATE_PRELUDE), "got: {}", script);
+        assert!(script.contains(r#"exec claude -n 'it'\''s fine'"#), "got: {}", script);
+        assert!(
+            script.find(UPDATE_PRELUDE).unwrap() < script.find("exec claude").unwrap(),
+            "prelude must precede the exec: {}",
+            script
+        );
+    }
+
+    /// Resume goes through the same launch as a new session — prelude,
+    /// permission flags — and passes the id instead of the tab label, so a
+    /// label of "resume" does not rename the conversation.
+    #[test]
+    fn build_terminal_cmd_resumes_without_renaming() {
+        let mut p = project("anthropic", serde_json::Value::Null);
+        p.full_permissions = true;
+        let cmd = build_claude_terminal_cmd(
+            &p,
+            None,
+            Some("resume"),
+            Some("e13d312d-2f38-4cf6-b0e0-1db60208a74c"),
+        );
+
+        assert!(cmd[2].contains(UPDATE_PRELUDE), "got: {}", cmd[2]);
+        assert!(
+            cmd[2].contains(
+                "exec claude '--dangerously-skip-permissions' --resume 'e13d312d-2f38-4cf6-b0e0-1db60208a74c'\n"
+            ),
+            "got: {}",
+            cmd[2]
+        );
+        assert!(!cmd[2].contains(" -n "), "resume must not rename: {}", cmd[2]);
+    }
+
+    #[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/container_watch.rs

@@ -0,0 +1,328 @@
+//! Notices a project container that stopped without the app asking.
+//!
+//! Until this existed the app only ever learned a container's state from its
+//! own commands and from `reconcile_project_statuses`, which the frontend runs
+//! once, when Docker first answers. A container that died underneath a running
+//! app — the entrypoint's keepalive killed, an OOM, `docker stop` from a shell,
+//! a daemon restart — left its project at Running indefinitely: every terminal
+//! disconnected, while the sidebar, Start/Stop and Project Home all still
+//! described a live container.
+//!
+//! One subscription to the host's death reports (`host::watch`; for Docker,
+//! the daemon's event stream filtered to container `die` events, so an idle
+//! daemon costs nothing and the app hears about a death as it happens — no
+//! polling loop). Each `die` naming a project's container is
+//! confirmed with one inspect before anything changes (an event can be
+//! replayed, and a restart can reuse the id), and the flip itself is
+//! [`ProjectsStore::mark_exited`]'s compare-and-set, which never touches a
+//! project a command owns and refuses if the store changed while the inspect
+//! was in flight. The frontend hears it on [`CONTAINER_EXITED_EVENT`].
+//!
+//! The stream drops whenever the daemon does. Each (re)subscription asks for
+//! events since just before it, and first re-checks every Running project once —
+//! the only window that replay cannot cover is a daemon restart, which forgets
+//! its event history, and that is exactly when containers go away.
+
+use std::future::Future;
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use futures_util::StreamExt;
+use serde::Serialize;
+use tauri::{AppHandle, Emitter};
+use tokio::sync::watch;
+
+use crate::host::watch::ExitSource;
+use crate::host::ContainerTarget;
+use crate::models::{Project, ProjectStatus};
+use crate::storage::projects_store::{ExitMark, ProjectsStore};
+
+/// Emitted as a [`ContainerExited`] whenever this module flips a project to
+/// Stopped.
+pub const CONTAINER_EXITED_EVENT: &str = "project-container-exited";
+
+const RETRY_MIN: Duration = Duration::from_secs(5);
+const RETRY_MAX: Duration = Duration::from_secs(60);
+/// A stream that stayed up this long (or delivered anything) was a working
+/// connection, so its loss starts the backoff over. Anything shorter — the
+/// daemon answers ping but the events call fails — keeps backing off, or it
+/// would re-sweep and re-log every five seconds forever.
+const STABLE_AFTER: Duration = Duration::from_secs(60);
+/// How often `settle` re-confirms when the store keeps changing under it.
+const SETTLE_ATTEMPTS: usize = 3;
+
+/// How the app found out, which decides whether it is news to the user.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ExitReason {
+    /// The container died while this app was running and watching — any
+    /// sessions it had were just cut off.
+    Exited,
+    /// Found already stopped on the first look of this run: it went down
+    /// while the app was closed (a host reboot, typically). Nothing the user
+    /// can see was interrupted, so it is not news.
+    FoundStopped,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct ContainerExited<'a> {
+    pub project: &'a Project,
+    pub reason: ExitReason,
+}
+
+fn project_busy(project_id: &str) -> bool {
+    crate::project_lock::held(project_id).is_some()
+}
+
+/// Confirm `container` really stopped and, if a project was Running on it,
+/// flip that project. Returns what changed.
+async fn settle(store: &ProjectsStore, container: &ContainerTarget) -> Option<Project> {
+    let container_id = container.id();
+    for _ in 0..SETTLE_ATTEMPTS {
+        // Cheap and allocation-free: most containers that die are not ours
+        // (probe and scratch containers, other software on the daemon), and
+        // those cost no inspect at all.
+        let seen = store.running_on(container_id)?;
+        // Positive exit only: a host that can't answer must not mark every
+        // project Stopped.
+        if !container.has_exited().await {
+            return None;
+        }
+        match store.mark_exited(container_id, &seen, project_busy) {
+            ExitMark::Flipped(p) => return Some(*p),
+            ExitMark::NotApplicable => return None,
+            // The store moved while the host was answering — possibly a stop and
+            // start of this very container. The inspect is stale; ask again.
+            ExitMark::Changed => continue,
+        }
+    }
+    None
+}
+
+/// Re-check every Running project once. Used on each (re)subscription.
+async fn sweep(store: &ProjectsStore) -> Vec<Project> {
+    let mut changed = Vec::new();
+    for p in store.list() {
+        if p.status != ProjectStatus::Running {
+            continue;
+        }
+        let Some(container) = ContainerTarget::for_project(&p) else { continue };
+        if let Some(c) = settle(store, &container).await {
+            changed.push(c);
+        }
+    }
+    changed
+}
+
+/// The wait before connection attempt `n + 1`, after `n` consecutive
+/// unproductive ones: 5 s, 10 s, 20 s, 40 s, then 60 s for good.
+fn retry_delay(consecutive_failures: u32) -> Duration {
+    let doublings = consecutive_failures.saturating_sub(1).min(8);
+    (RETRY_MIN * 2u32.pow(doublings)).min(RETRY_MAX)
+}
+
+/// `fut`, unless the app starts shutting down first. Every host call in here
+/// goes through this: a wedged daemon must not hold shutdown for its full
+/// budget.
+async fn unless_cancelled<T>(
+    cancel: &mut watch::Receiver<bool>,
+    fut: impl Future<Output = T>,
+) -> Option<T> {
+    if *cancel.borrow() {
+        return None;
+    }
+    tokio::select! {
+        // `Err` means the sender is gone, i.e. so is the app.
+        _ = cancel.changed() => None,
+        v = fut => Some(v),
+    }
+}
+
+/// One connection: ping, sweep, then follow the event stream until it ends.
+/// `None` when cancelled; otherwise whether the connection was a working one
+/// (see [`STABLE_AFTER`]).
+async fn watch_once(
+    store: &ProjectsStore,
+    cancel: &mut watch::Receiver<bool>,
+    sweep_reason: ExitReason,
+    on_change: &impl Fn(&Project, ExitReason),
+) -> Option<bool> {
+    let source = ExitSource::Docker;
+    if !unless_cancelled(cancel, source.reachable()).await? {
+        return Some(false);
+    }
+    // A second's overlap: the host replays from `since`, so a death during
+    // the sweep below is still delivered. Duplicates are harmless — `settle`
+    // confirms with an inspect every time.
+    let since = chrono::Utc::now().timestamp() - 1;
+    for p in unless_cancelled(cancel, sweep(store)).await? {
+        on_change(&p, sweep_reason);
+    }
+    let mut deaths = source.deaths(since);
+    let connected = Instant::now();
+    let mut delivered = false;
+    loop {
+        match unless_cancelled(cancel, deaths.next()).await? {
+            Some(Ok(container)) => {
+                delivered = true;
+                if let Some(p) = unless_cancelled(cancel, settle(store, &container)).await? {
+                    on_change(&p, ExitReason::Exited);
+                }
+            }
+            Some(Err(e)) => {
+                log::info!("Container watch: event stream ended ({e}) — reconnecting");
+                break;
+            }
+            None => {
+                log::info!("Container watch: event stream closed — reconnecting");
+                break;
+            }
+        }
+    }
+    Some(delivered || connected.elapsed() >= STABLE_AFTER)
+}
+
+/// Watch until `cancel` flips, calling `on_change` for every project whose
+/// container is found to have stopped on its own. Separate from [`spawn`] so a
+/// test can drive it without a Tauri app.
+pub(crate) async fn run(
+    store: Arc<ProjectsStore>,
+    mut cancel: watch::Receiver<bool>,
+    on_change: impl Fn(&Project, ExitReason),
+) {
+    // Only the first look of the run finds containers that stopped while the
+    // app was closed. A sweep after a reconnect finds ones that died while we
+    // were running — the daemon restarting is the usual cause — and those
+    // cut off live sessions just as a `die` event would.
+    let mut sweep_reason = ExitReason::FoundStopped;
+    let mut failures: u32 = 0;
+    loop {
+        let Some(healthy) = watch_once(&store, &mut cancel, sweep_reason, &on_change).await else {
+            return;
+        };
+        sweep_reason = ExitReason::Exited;
+        failures = if healthy { 1 } else { failures + 1 };
+        unless_cancelled(&mut cancel, tokio::time::sleep(retry_delay(failures))).await;
+        if *cancel.borrow() {
+            return;
+        }
+    }
+}
+
+/// Start the watcher for the life of the app.
+pub fn spawn(
+    app: AppHandle,
+    store: Arc<ProjectsStore>,
+    cancel: watch::Receiver<bool>,
+) -> tauri::async_runtime::JoinHandle<()> {
+    tauri::async_runtime::spawn(async move {
+        run(store, cancel, |p, reason| {
+            log::warn!(
+                "Project '{}' ({}): its container stopped without the app asking ({:?}) — marking Stopped",
+                p.name,
+                p.id,
+                reason
+            );
+            let _ = app.emit(CONTAINER_EXITED_EVENT, ContainerExited { project: p, reason });
+        })
+        .await;
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn retries_back_off_to_a_minute_and_stay_there() {
+        let secs: Vec<u64> = (1..=7).map(|n| retry_delay(n).as_secs()).collect();
+        assert_eq!(secs, vec![5, 10, 20, 40, 60, 60, 60]);
+        assert_eq!(retry_delay(0), RETRY_MIN);
+        assert_eq!(retry_delay(u32::MAX), RETRY_MAX);
+    }
+
+    #[test]
+    fn the_event_says_why_so_the_ui_can_tell_news_from_housekeeping() {
+        let p = Project::new("demo".to_string(), Vec::new());
+        let v = serde_json::to_value(ContainerExited { project: &p, reason: ExitReason::Exited }).unwrap();
+        assert_eq!(v["reason"], "exited");
+        assert_eq!(v["project"]["name"], "demo");
+        let v = serde_json::to_value(ContainerExited { project: &p, reason: ExitReason::FoundStopped })
+            .unwrap();
+        assert_eq!(v["reason"], "found_stopped");
+        assert_eq!(CONTAINER_EXITED_EVENT, "project-container-exited");
+    }
+
+    /// The shutdown path: a host call that never answers (a wedged daemon)
+    /// must give way to cancellation at once, not hold teardown.
+    #[tokio::test]
+    async fn a_hung_docker_call_yields_to_cancellation() {
+        let (tx, mut rx) = watch::channel(false);
+        let canceller = tokio::spawn(async move {
+            tokio::time::sleep(Duration::from_millis(20)).await;
+            let _ = tx.send(true);
+        });
+        let hung = std::future::pending::<()>();
+        let out = tokio::time::timeout(Duration::from_secs(2), unless_cancelled(&mut rx, hung)).await;
+        assert_eq!(out.expect("returned promptly"), None);
+        canceller.await.unwrap();
+        // Already cancelled: it does not even start the call.
+        assert_eq!(unless_cancelled(&mut rx, async { 1 }).await, None);
+    }
+
+    /// End to end against a real daemon: a Running project whose container is
+    /// killed from outside the app is flipped to Stopped and reported as a live
+    /// exit; one found already stopped on the first look is reported as such;
+    /// and one whose container is still up is left alone.
+    #[tokio::test]
+    #[ignore = "needs a Docker daemon; creates and removes throwaway containers"]
+    async fn a_container_killed_outside_the_app_flips_its_project_to_stopped() {
+        use std::process::Command;
+        fn docker_cli(args: &[&str]) -> String {
+            let out = Command::new("docker").args(args).output().expect("docker cli");
+            assert!(out.status.success(), "docker {:?}: {}", args, String::from_utf8_lossy(&out.stderr));
+            String::from_utf8_lossy(&out.stdout).trim().to_string()
+        }
+        let tag = uuid::Uuid::new_v4().simple().to_string();
+        let doomed = docker_cli(&["run", "-d", "--name", &format!("tc-watch-a-{tag}"), "alpine:3", "sleep", "300"]);
+        let alive = docker_cli(&["run", "-d", "--name", &format!("tc-watch-b-{tag}"), "alpine:3", "sleep", "300"]);
+        let already = docker_cli(&["create", "--name", &format!("tc-watch-c-{tag}"), "alpine:3", "true"]);
+
+        let dir = std::env::temp_dir().join(format!("triple-c-watch-{tag}"));
+        std::fs::create_dir_all(&dir).unwrap();
+        let running = |name: &str, cid: &str| {
+            let mut p = Project::new(name.to_string(), Vec::new());
+            p.container_id = Some(cid.to_string());
+            p.status = ProjectStatus::Running;
+            p
+        };
+        let (a, b, c) = (running("a", &doomed), running("b", &alive), running("c", &already));
+        let (a_id, b_id, c_id) = (a.id.clone(), b.id.clone(), c.id.clone());
+        let store = Arc::new(ProjectsStore::over_file_for_test(dir.join("projects.json"), vec![a, b, c]));
+
+        let (cancel_tx, cancel_rx) = watch::channel(false);
+        let (seen_tx, mut seen_rx) = tokio::sync::mpsc::unbounded_channel::<(String, ExitReason)>();
+        let watcher = tokio::spawn(run(store.clone(), cancel_rx, move |p, why| {
+            let _ = seen_tx.send((p.id.clone(), why));
+        }));
+        let first = tokio::time::timeout(Duration::from_secs(10), seen_rx.recv()).await;
+        // Subscribed by now (the sweep precedes it, and `since` overlaps);
+        // kill from "outside".
+        docker_cli(&["kill", &doomed]);
+        let second = tokio::time::timeout(Duration::from_secs(15), seen_rx.recv()).await;
+
+        let t0 = Instant::now();
+        let _ = cancel_tx.send(true);
+        let _ = watcher.await;
+        let shutdown = t0.elapsed();
+        let statuses: Vec<ProjectStatus> =
+            [&a_id, &b_id, &c_id].iter().map(|id| store.get(id).unwrap().status).collect();
+        docker_cli(&["rm", "-f", &doomed, &alive, &already]);
+        std::fs::remove_dir_all(&dir).ok();
+
+        assert_eq!(first.expect("sweep within 10s"), Some((c_id, ExitReason::FoundStopped)));
+        assert_eq!(second.expect("die within 15s"), Some((a_id, ExitReason::Exited)));
+        assert_eq!(statuses, vec![ProjectStatus::Stopped, ProjectStatus::Running, ProjectStatus::Stopped]);
+        assert!(shutdown < Duration::from_secs(1), "stopped watching in {shutdown:?}");
+    }
+}

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/client.rs

@@ -26,3 +26,13 @@ pub async fn check_docker_available() -> Result<bool, String> {
         }
     }
 }
+
+/// The daemon socket a project container gets bind-mounted when Docker access
+/// is enabled and no path is configured.
+pub fn default_docker_socket() -> String {
+    if cfg!(target_os = "windows") {
+        "//./pipe/docker_engine".to_string()
+    } else {
+        "/var/run/docker.sock".to_string()
+    }
+}

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

@@ -0,0 +1,114 @@
+//! The Docker half of `container_watch`: reachability, the daemon's container
+//! `die` event stream, and the "has it positively exited" check. Everything
+//! about *what to do* with a death (confirm, compare-and-set the store, tell
+//! the frontend, back off) is host-neutral and stays in `container_watch.rs`,
+//! which reaches these through `host::watch`.
+
+use std::collections::HashMap;
+use std::pin::Pin;
+
+use bollard::errors::Error as DockerError;
+use bollard::models::{EventMessage, EventMessageTypeEnum};
+use bollard::system::EventsOptions;
+use futures_util::{Stream, StreamExt};
+
+use super::client::get_docker;
+
+/// Whether the daemon answers at all.
+pub async fn ping() -> bool {
+    match get_docker() {
+        Ok(docker) => docker.ping().await.is_ok(),
+        Err(_) => false,
+    }
+}
+
+/// The container id a Docker event reports as having died, if it is one.
+pub(crate) fn died_container(msg: &EventMessage) -> Option<&str> {
+    if msg.typ != Some(EventMessageTypeEnum::CONTAINER) || msg.action.as_deref() != Some("die") {
+        return None;
+    }
+    msg.actor.as_ref()?.id.as_deref().filter(|id| !id.is_empty())
+}
+
+fn die_filter() -> HashMap<String, Vec<String>> {
+    HashMap::from([
+        ("type".to_string(), vec!["container".to_string()]),
+        ("event".to_string(), vec!["die".to_string()]),
+    ])
+}
+
+/// Container ids as Docker reports them dying, replayed from `since` (unix
+/// seconds). Filtered daemon-side to container `die` events, so an idle daemon
+/// costs nothing. Anything else that comes through is dropped here. An `Err`
+/// item, or the stream ending, means the connection is gone.
+pub fn container_deaths(since: i64) -> Pin<Box<dyn Stream<Item = Result<String, String>> + Send>> {
+    let docker = match get_docker() {
+        Ok(d) => d,
+        Err(e) => return Box::pin(futures_util::stream::once(async move { Err(e) })),
+    };
+    let events = docker.events(Some(EventsOptions::<String> {
+        since: Some(since.to_string()),
+        until: None,
+        filters: die_filter(),
+    }));
+    Box::pin(events.filter_map(|item| async move {
+        match item {
+            Ok(msg) => died_container(&msg).map(|id| Ok(id.to_string())),
+            Err(e) => Some(Err(e.to_string())),
+        }
+    }))
+}
+
+/// `true` only when Docker positively says the container is not running: it
+/// inspects as stopped, or it no longer exists. Any other failure is "don't
+/// know" — `is_container_running` maps every error to `false`, which is right
+/// for its callers and wrong for the watcher, where it would mark every project
+/// Stopped the moment the daemon hiccups.
+pub async fn has_exited(container_id: &str) -> bool {
+    let Ok(docker) = get_docker() else { return false };
+    match docker.inspect_container(container_id, None).await {
+        Ok(info) => !info.state.and_then(|s| s.running).unwrap_or(false),
+        Err(DockerError::DockerResponseServerError { status_code: 404, .. }) => true,
+        Err(_) => false,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use bollard::models::EventActor;
+
+    fn event(typ: EventMessageTypeEnum, action: &str, id: Option<&str>) -> EventMessage {
+        EventMessage {
+            typ: Some(typ),
+            action: Some(action.to_string()),
+            actor: Some(EventActor { id: id.map(str::to_string), attributes: None }),
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn only_a_container_die_names_a_container() {
+        let die = event(EventMessageTypeEnum::CONTAINER, "die", Some("abc"));
+        assert_eq!(died_container(&die), Some("abc"));
+
+        for (typ, action, id) in [
+            (EventMessageTypeEnum::CONTAINER, "stop", Some("abc")),
+            (EventMessageTypeEnum::CONTAINER, "start", Some("abc")),
+            (EventMessageTypeEnum::CONTAINER, "exec_die", Some("abc")),
+            (EventMessageTypeEnum::NETWORK, "die", Some("abc")),
+            (EventMessageTypeEnum::CONTAINER, "die", None),
+            (EventMessageTypeEnum::CONTAINER, "die", Some("")),
+        ] {
+            assert_eq!(died_container(&event(typ, action, id)), None, "{typ:?} {action} {id:?}");
+        }
+    }
+
+    #[test]
+    fn the_subscription_is_filtered_to_container_deaths_daemon_side() {
+        let f = die_filter();
+        assert_eq!(f.get("type"), Some(&vec!["container".to_string()]));
+        assert_eq!(f.get("event"), Some(&vec!["die".to_string()]));
+        assert_eq!(f.len(), 2);
+    }
+}

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

@@ -15,8 +15,16 @@ const TASK_RUNNER: &str = include_str!("../../../../container/triple-c-task-runn
 const OSC52_CLIPBOARD: &str = include_str!("../../../../container/osc52-clipboard");
 const AUDIO_SHIM: &str = include_str!("../../../../container/audio-shim");
 const SSO_REFRESH: &str = include_str!("../../../../container/triple-c-sso-refresh");
+const TRIPLE_C_OPEN: &str = include_str!("../../../../container/triple-c-open");
+const PLAYWRIGHT_HEAL: &str = include_str!("../../../../container/triple-c-playwright-heal");
 
 static MISSION_CONTROL_DIR: Dir = include_dir!("$CARGO_MANIFEST_DIR/../../container/mission-control");
+static SKILLS_DIR: Dir = include_dir!("$CARGO_MANIFEST_DIR/../../container/skills");
+// The agent crate's sources only — never the whole crate directory, which can
+// hold a multi-hundred-megabyte `target/` from a local build.
+const AGENT_CARGO_TOML: &str = include_str!("../../../../container/triple-c-agent/Cargo.toml");
+const AGENT_CARGO_LOCK: &str = include_str!("../../../../container/triple-c-agent/Cargo.lock");
+static AGENT_SRC_DIR: Dir = include_dir!("$CARGO_MANIFEST_DIR/../../container/triple-c-agent/src");
 
 pub async fn image_exists(image_name: &str) -> Result<bool, String> {
     let docker = get_docker()?;
@@ -69,25 +77,32 @@ pub async fn get_local_image_digest(image_name: &str) -> Result<Option<String>,
     Ok(None)
 }
 
+/// Split an image reference into the `fromImage` and `tag` the pull API takes.
+/// A digest reference (`repo@sha256:…`, optionally `repo:tag@sha256:…`) is
+/// pulled by digest: the API takes the digest in the `tag` field.
+fn split_image_ref(image_name: &str) -> (&str, &str) {
+    if let Some((name, digest)) = image_name.split_once('@') {
+        let repo = match name.rfind(':') {
+            Some(pos) if !name[pos + 1..].contains('/') => &name[..pos],
+            _ => name,
+        };
+        return (repo, digest);
+    }
+    match image_name.rfind(':') {
+        // The colon is part of a port (e.g., host:port/repo), not a tag.
+        Some(pos) if image_name[pos + 1..].contains('/') => (image_name, "latest"),
+        Some(pos) => (&image_name[..pos], &image_name[pos + 1..]),
+        None => (image_name, "latest"),
+    }
+}
+
 pub async fn pull_image<F>(image_name: &str, on_progress: F) -> Result<(), String>
 where
     F: Fn(String) + Send + 'static,
 {
     let docker = get_docker()?;
 
-    // Parse image name into from_image and tag
-    let (from_image, tag) = if let Some(pos) = image_name.rfind(':') {
-        // Check that the colon is part of a tag, not a port
-        let after_colon = &image_name[pos + 1..];
-        if after_colon.contains('/') {
-            // The colon is part of a port (e.g., host:port/repo)
-            (image_name, "latest")
-        } else {
-            (&image_name[..pos], after_colon)
-        }
-    } else {
-        (image_name, "latest")
-    };
+    let (from_image, tag) = split_image_ref(image_name);
 
     let options = CreateImageOptions {
         from_image,
@@ -130,10 +145,28 @@ where
 
     let tar_bytes = create_build_context().map_err(|e| format!("Failed to create build context: {}", e))?;
 
+    // The Dockerfile builds `triple-c-agent` in a stage pinned to
+    // `$BUILDPLATFORM` and cross-compiles for `$TARGETARCH`, so CI's arm64
+    // image compiles natively instead of under QEMU. BuildKit predefines both;
+    // the classic builder this API call uses does not, and an empty
+    // `--platform=` fails the build outright (verified, Engine 29.9). So pass
+    // them, describing the daemon's own platform: a local build is always
+    // native.
+    let arch = docker
+        .version()
+        .await
+        .ok()
+        .and_then(|v| v.arch)
+        .filter(|a| !a.is_empty())
+        .unwrap_or_else(|| native_docker_arch().to_string());
+    let build_platform = format!("linux/{}", arch);
+    let buildargs = local_build_args(&build_platform, &arch);
+
     let options = BuildImageOptions {
         t: full_name.as_str(),
         rm: true,
         forcerm: true,
+        buildargs,
         ..Default::default()
     };
 
@@ -184,6 +217,20 @@ fn append_embedded_dir(
     Ok(())
 }
 
+/// Docker's name for this machine's architecture, for when the daemon does
+/// not say.
+fn native_docker_arch() -> &'static str {
+    match std::env::consts::ARCH {
+        "aarch64" => "arm64",
+        "x86_64" => "amd64",
+        other => other,
+    }
+}
+
+fn local_build_args<'a>(build_platform: &'a str, arch: &'a str) -> HashMap<&'a str, &'a str> {
+    HashMap::from([("BUILDPLATFORM", build_platform), ("TARGETARCH", arch)])
+}
+
 fn create_build_context() -> Result<Vec<u8>, std::io::Error> {
     let mut buf = Vec::new();
     {
@@ -196,8 +243,14 @@ fn create_build_context() -> Result<Vec<u8>, std::io::Error> {
         append_file_to_archive(&mut archive, "osc52-clipboard", OSC52_CLIPBOARD.as_bytes(), 0o755)?;
         append_file_to_archive(&mut archive, "audio-shim", AUDIO_SHIM.as_bytes(), 0o755)?;
         append_file_to_archive(&mut archive, "triple-c-sso-refresh", SSO_REFRESH.as_bytes(), 0o755)?;
+        append_file_to_archive(&mut archive, "triple-c-open", TRIPLE_C_OPEN.as_bytes(), 0o755)?;
+        append_file_to_archive(&mut archive, "triple-c-playwright-heal", PLAYWRIGHT_HEAL.as_bytes(), 0o755)?;
 
         append_embedded_dir(&mut archive, &MISSION_CONTROL_DIR, "mission-control")?;
+        append_embedded_dir(&mut archive, &SKILLS_DIR, "skills")?;
+        append_file_to_archive(&mut archive, "triple-c-agent/Cargo.toml", AGENT_CARGO_TOML.as_bytes(), 0o644)?;
+        append_file_to_archive(&mut archive, "triple-c-agent/Cargo.lock", AGENT_CARGO_LOCK.as_bytes(), 0o644)?;
+        append_embedded_dir(&mut archive, &AGENT_SRC_DIR, "triple-c-agent/src")?;
 
         archive.finish()?;
     }
@@ -205,3 +258,244 @@ fn create_build_context() -> Result<Vec<u8>, std::io::Error> {
     let _ = buf.flush();
     Ok(buf)
 }
+
+#[cfg(test)]
+mod build_context_tests {
+    use super::{create_build_context, DOCKERFILE};
+
+    /// The local build (`ImageSource::LocalBuild`) ships the Dockerfile with a
+    /// hand-assembled context, and nothing else checks the two agree: CI builds
+    /// from the real `container/` directory, so a `COPY` of something missing
+    /// here only fails for users who build locally. That went unnoticed for
+    /// `skills`, `triple-c-open` and `triple-c-playwright-heal`. Every `COPY`
+    /// source (not `--from=` stages) must be present as a file or directory
+    /// prefix in the archive.
+    #[test]
+    fn every_dockerfile_copy_source_is_in_the_local_build_context() {
+        let tar_bytes = create_build_context().expect("context builds");
+        let mut archive = tar::Archive::new(&tar_bytes[..]);
+        let paths: Vec<String> = archive
+            .entries()
+            .unwrap()
+            .map(|e| e.unwrap().path().unwrap().to_string_lossy().into_owned())
+            .collect();
+        let mut missing = Vec::new();
+        for line in DOCKERFILE.lines() {
+            let line = line.trim();
+            let Some(rest) = line.strip_prefix("COPY ") else { continue };
+            let args: Vec<&str> = rest.split_whitespace().filter(|a| !a.starts_with("--")).collect();
+            if rest.contains("--from=") || args.len() < 2 {
+                continue;
+            }
+            for src in &args[..args.len() - 1] {
+                let src = src.trim_end_matches('/');
+                let present = paths.iter().any(|p| p == src || p.starts_with(&format!("{}/", src)));
+                if !present {
+                    missing.push(src.to_string());
+                }
+            }
+        }
+        assert!(missing.is_empty(), "COPY sources missing from the local build context: {:?}", missing);
+    }
+}
+
+#[cfg(all(test, unix))]
+mod tests {
+    use super::ENTRYPOINT;
+    use std::fs;
+    use std::path::Path;
+    use std::process::Command;
+
+    /// The `sync_host_ssh` function from `entrypoint.sh`, cut out between its
+    /// markers so it can be run against temp dirs instead of the real ~/.ssh.
+    fn sync_fn() -> &'static str {
+        let start = ENTRYPOINT.find("# >>> sync_host_ssh").expect("start marker");
+        let end = ENTRYPOINT.find("# <<< sync_host_ssh").expect("end marker");
+        &ENTRYPOINT[start..end]
+    }
+
+    fn sync(src: &Path, dest: &Path) -> String {
+        let script = format!("{}\nsync_host_ssh \"$1\" \"$2\"\n", sync_fn());
+        let out = Command::new("bash")
+            .arg("-c")
+            .arg(script)
+            .arg("sync")
+            .arg(src)
+            .arg(dest)
+            .output()
+            .expect("run bash");
+        assert!(out.status.success(), "sync failed: {}", String::from_utf8_lossy(&out.stderr));
+        String::from_utf8_lossy(&out.stdout).into_owned()
+    }
+
+    fn read(p: &Path) -> String {
+        fs::read_to_string(p).unwrap()
+    }
+
+    #[test]
+    fn container_created_keys_survive_restart() {
+        let tmp = tempfile::tempdir().unwrap();
+        let (src, dest) = (tmp.path().join("host"), tmp.path().join("ssh"));
+        fs::create_dir_all(&src).unwrap();
+        fs::write(src.join("id_host"), "host-key").unwrap();
+
+        sync(&src, &dest);
+        fs::write(dest.join("id_container"), "made-in-container").unwrap();
+        sync(&src, &dest);
+
+        assert_eq!(read(&dest.join("id_container")), "made-in-container");
+        assert_eq!(read(&dest.join("id_host")), "host-key");
+    }
+
+    #[test]
+    fn container_file_wins_over_same_named_host_file() {
+        let tmp = tempfile::tempdir().unwrap();
+        let (src, dest) = (tmp.path().join("host"), tmp.path().join("ssh"));
+        fs::create_dir_all(&src).unwrap();
+        fs::write(src.join("id_host"), "host-key").unwrap();
+        sync(&src, &dest);
+
+        fs::write(dest.join("id_ed25519"), "container-key").unwrap();
+        fs::write(src.join("id_ed25519"), "host-ed25519").unwrap();
+        let out = sync(&src, &dest);
+
+        assert_eq!(read(&dest.join("id_ed25519")), "container-key");
+        assert!(out.contains("keeping container's"), "{out}");
+    }
+
+    #[test]
+    fn host_changes_propagate_until_edited_in_container() {
+        let tmp = tempfile::tempdir().unwrap();
+        let (src, dest) = (tmp.path().join("host"), tmp.path().join("ssh"));
+        fs::create_dir_all(&src).unwrap();
+        fs::write(src.join("config"), "v1").unwrap();
+        fs::write(src.join("id_old"), "old").unwrap();
+        sync(&src, &dest);
+
+        fs::write(src.join("config"), "v2").unwrap();
+        fs::remove_file(src.join("id_old")).unwrap();
+        sync(&src, &dest);
+        assert_eq!(read(&dest.join("config")), "v2");
+        assert!(!dest.join("id_old").exists(), "host-removed, unedited file is dropped");
+
+        fs::write(dest.join("config"), "edited in container").unwrap();
+        fs::write(src.join("config"), "v3").unwrap();
+        sync(&src, &dest);
+        assert_eq!(read(&dest.join("config")), "edited in container");
+
+        fs::remove_file(src.join("config")).unwrap();
+        sync(&src, &dest);
+        assert_eq!(read(&dest.join("config")), "edited in container");
+    }
+
+    #[test]
+    fn known_hosts_is_unioned() {
+        let tmp = tempfile::tempdir().unwrap();
+        let (src, dest) = (tmp.path().join("host"), tmp.path().join("ssh"));
+        fs::create_dir_all(&src).unwrap();
+        fs::create_dir_all(&dest).unwrap();
+        fs::write(src.join("known_hosts"), "hostA key\n").unwrap();
+        fs::write(dest.join("known_hosts"), "containerB key\n").unwrap();
+
+        sync(&src, &dest);
+        let kh = read(&dest.join("known_hosts"));
+        assert!(kh.contains("hostA key") && kh.contains("containerB key"), "{kh}");
+    }
+
+    #[test]
+    fn upgrade_from_wipe_and_copy_backs_up_differing_files() {
+        // No manifest yet: the state an existing project is in on its first
+        // start with this entrypoint.
+        let tmp = tempfile::tempdir().unwrap();
+        let (src, dest) = (tmp.path().join("host"), tmp.path().join("ssh"));
+        fs::create_dir_all(&src).unwrap();
+        fs::create_dir_all(&dest).unwrap();
+        fs::write(src.join("id_rsa"), "host").unwrap();
+        fs::write(dest.join("id_rsa"), "container").unwrap();
+        fs::write(dest.join("id_extra"), "extra").unwrap();
+
+        sync(&src, &dest);
+
+        assert_eq!(read(&dest.join("id_rsa")), "host");
+        assert_eq!(read(&dest.join("id_rsa.triple-c-backup")), "container");
+        assert_eq!(read(&dest.join("id_extra")), "extra");
+    }
+
+    #[test]
+    fn nested_host_files_are_copied() {
+        let tmp = tempfile::tempdir().unwrap();
+        let (src, dest) = (tmp.path().join("host"), tmp.path().join("ssh"));
+        fs::create_dir_all(src.join("config.d")).unwrap();
+        fs::write(src.join("config.d/work"), "Host work").unwrap();
+
+        sync(&src, &dest);
+        assert_eq!(read(&dest.join("config.d/work")), "Host work");
+    }
+}
+
+#[cfg(test)]
+mod apt_refresh_tests {
+    use super::DOCKERFILE;
+
+    const BUILD_WORKFLOW: &str = include_str!("../../../../.gitea/workflows/build.yml");
+
+    /// The `RUN` instruction (with its `\` continuations) that contains `needle`.
+    fn run_containing(needle: &str) -> String {
+        let mut run = String::new();
+        let mut current = String::new();
+        for line in DOCKERFILE.lines() {
+            if line.starts_with("RUN ") {
+                current.clear();
+            }
+            current.push_str(line);
+            current.push('\n');
+            if !line.trim_end().ends_with('\\') {
+                if current.contains(needle) && current.starts_with("RUN ") {
+                    run = current.clone();
+                }
+                current.clear();
+            }
+        }
+        run
+    }
+
+    /// CI builds with `cache-from: type=gha`, so the `apt-get upgrade` layer is
+    /// only re-run when its cache key changes. An ARG changes a RUN's key only
+    /// where it is *used*, so the upgrade's RUN must reference it, after an
+    /// `ARG APT_REFRESH` declared in its stage.
+    #[test]
+    fn the_apt_upgrade_layer_is_keyed_on_apt_refresh() {
+        let arg = DOCKERFILE.find("\nARG APT_REFRESH").expect("ARG APT_REFRESH declared");
+        let run = run_containing("upgrade -y");
+        assert!(!run.is_empty(), "no RUN with apt-get upgrade");
+        assert!(DOCKERFILE.find(&run).unwrap() > arg, "ARG must come before the RUN");
+        assert!(run.contains("${APT_REFRESH"), "RUN must use APT_REFRESH: {run}");
+    }
+
+    /// …and CI must actually pass a value that changes at least weekly, and
+    /// rebuild on a schedule so a week with no commits still gets the fixes.
+    #[test]
+    fn ci_passes_a_weekly_apt_refresh_and_rebuilds_on_a_schedule() {
+        assert!(BUILD_WORKFLOW.contains("APT_REFRESH=${{ steps.apt.outputs.stamp }}"));
+        assert!(BUILD_WORKFLOW.contains("date -u +%G-W%V"));
+        assert!(BUILD_WORKFLOW.contains("schedule:"));
+        // A scheduled run must publish, a PR run must not.
+        assert!(BUILD_WORKFLOW.contains("push: ${{ gitea.event_name != 'pull_request' }}"));
+    }
+}
+
+#[cfg(test)]
+mod pull_ref_tests {
+    use super::split_image_ref;
+
+    #[test]
+    fn split_image_ref_handles_tags_ports_and_digests() {
+        assert_eq!(split_image_ref("repo:v1"), ("repo", "v1"));
+        assert_eq!(split_image_ref("repo"), ("repo", "latest"));
+        assert_eq!(split_image_ref("host:5000/repo"), ("host:5000/repo", "latest"));
+        assert_eq!(split_image_ref("host:5000/repo:v1"), ("host:5000/repo", "v1"));
+        assert_eq!(split_image_ref("ghcr.io/a/b@sha256:abc"), ("ghcr.io/a/b", "sha256:abc"));
+        assert_eq!(split_image_ref("ghcr.io/a/b:v1@sha256:abc"), ("ghcr.io/a/b", "sha256:abc"));
+        assert_eq!(split_image_ref("host:5000/b@sha256:abc"), ("host:5000/b", "sha256:abc"));
+    }
+}

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,19 @@
+pub mod ca_certs;
 pub mod client;
+pub mod events;
 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;
 
+/// The container user `claude`'s home directory, as the image creates it.
+pub(crate) const CONTAINER_HOME: &str = "/home/claude";
+
+#[allow(unused_imports)]
+pub use gateway::*;
 #[allow(unused_imports)]
 pub use stt::*;
 #[allow(unused_imports)]
@@ -16,4 +25,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/file_viewer/mod.rs

@@ -0,0 +1,109 @@
+//! The terminal file viewer: one OS window per clicked path.
+//!
+//! Every window is a `file-viewer-<n>` label registered in [`registry::ViewerRegistry`];
+//! the commands in `commands/file_viewer_commands.rs` gate on the label and act only on
+//! the caller's own entry, which is why nothing here takes a path from a window.
+//!
+//! `file-viewer-*` is also the `windows` glob of `capabilities/file-viewer.json`, which grants
+//! exactly the five `viewer_*` commands and nothing else. Labels are minted only here; a window
+//! created anywhere else with a matching label would inherit those grants.
+
+pub mod poll;
+pub mod registry;
+pub mod resolve;
+pub mod window;
+pub mod write;
+
+/// Spec §3: the 21st click is refused with a toast.
+pub const MAX_VIEWER_WINDOWS: usize = 20;
+pub const VIEWER_LABEL_PREFIX: &str = "file-viewer-";
+
+pub fn is_viewer_label(label: &str) -> bool {
+    label
+        .strip_prefix(VIEWER_LABEL_PREFIX)
+        .is_some_and(|rest| !rest.is_empty() && rest.bytes().all(|b| b.is_ascii_digit()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn only_numbered_viewer_labels_pass() {
+        assert!(is_viewer_label("file-viewer-1"));
+        assert!(is_viewer_label("file-viewer-20"));
+        assert!(!is_viewer_label("file-viewer-"));
+        assert!(!is_viewer_label("file-viewer-x"));
+        assert!(!is_viewer_label("main"));
+        assert!(!is_viewer_label("browser-view-abc"));
+    }
+
+    /// Both Vite's dev server and Tauri's asset lookup fall back to `index.html`
+    /// when `viewer.html` is missing, so a broken entry opens the *main app* in
+    /// the viewer window with no error anywhere. Pin the two files the entry needs.
+    #[test]
+    fn the_viewer_entry_exists_and_is_a_vite_input() {
+        let app_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("..");
+        let html = std::fs::read_to_string(app_dir.join("viewer.html")).expect("app/viewer.html");
+        assert!(html.contains("/src/viewer/main.tsx"));
+        assert!(!html.contains("<style"), "an inline <style> makes Tauri add a style nonce, which disables 'unsafe-inline' and breaks CodeMirror");
+        let vite = std::fs::read_to_string(app_dir.join("vite.config.ts")).expect("vite.config.ts");
+        assert!(vite.contains("viewer.html"), "vite.config.ts must list viewer.html in build.rollupOptions.input");
+    }
+
+    #[derive(serde::Deserialize)]
+    struct Capability {
+        windows: Vec<String>,
+        permissions: Vec<String>,
+    }
+
+    /// Task 12: a substring check on the capability JSON (the form this test used to take)
+    /// only proves a permission string appears *somewhere* in the file — it would not catch
+    /// `windows` widened past `file-viewer-*`, nor an extra grant slipped in beside the ones
+    /// this window actually needs. Parse both capability files and pin `windows`/`permissions`
+    /// exactly, so a later widening of either file is a failing test, not a silent threat-model
+    /// drift — this file *is* the reviewed threat model of record (see its own description).
+    #[test]
+    fn the_viewer_capability_grants_exactly_the_reviewed_windows_and_permissions() {
+        let app_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("..");
+        let raw = std::fs::read_to_string(app_dir.join("src-tauri/capabilities/file-viewer.json"))
+            .expect("capabilities/file-viewer.json");
+        let cap: Capability = serde_json::from_str(&raw).expect("file-viewer.json must be valid JSON");
+
+        assert_eq!(cap.windows, vec!["file-viewer-*"]);
+
+        let mut permissions = cap.permissions;
+        permissions.sort();
+        assert_eq!(
+            permissions,
+            vec![
+                // App commands (bare): the five viewer commands, and nothing else — build.rs
+                // refuses any other bare grant in this file.
+                "allow-viewer-choose-file",
+                "allow-viewer-get-state",
+                "allow-viewer-poll-file",
+                "allow-viewer-read-file",
+                "allow-viewer-write-file",
+                // Plugin/core grants, unchanged.
+                "core:event:allow-listen",
+                "core:event:allow-unlisten",
+                "core:webview:allow-internal-toggle-devtools",
+                "core:window:allow-destroy",
+            ]
+        );
+    }
+
+    /// The main window's capability file must stay scoped to `main` — a `windows` list that
+    /// grew to include `file-viewer-*` would hand every viewer window the dialog/store surface
+    /// `default.json` grants `main`, which is a much larger IPC surface than the one
+    /// `file-viewer.json` was deliberately kept small.
+    #[test]
+    fn the_default_capability_is_scoped_to_the_main_window_only() {
+        let app_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("..");
+        let raw = std::fs::read_to_string(app_dir.join("src-tauri/capabilities/default.json"))
+            .expect("capabilities/default.json");
+        let cap: Capability = serde_json::from_str(&raw).expect("default.json must be valid JSON");
+
+        assert_eq!(cap.windows, vec!["main"]);
+    }
+}

app/src-tauri/src/file_viewer/poll.rs

@@ -0,0 +1,198 @@
+//! One cheap exec per tick: the file's full hash and size, or "gone".
+//!
+//! This is what the 2 s poll asks, instead of re-downloading up to 1 MiB of archive per
+//! window per tick. The hash is coreutils `sha256sum`, which equals `write::sha256_hex`
+//! of the bytes whenever the read was not truncated — the only case in which the
+//! editor uses a hash as its save base.
+
+use serde::Serialize;
+
+use crate::host::ContainerTarget;
+
+#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
+pub struct ViewerPoll {
+    pub exists: bool,
+    pub hash: Option<String>,
+    pub size: Option<u64>,
+}
+
+/// Exit 4 = gone. A failure after `test -f` passed is re-checked: if the file vanished
+/// in between (deleted while being hashed), that is "gone", not an error (M6).
+pub const POLL_SCRIPT: &str = r#"test -f "$1" || exit 4
+sha256sum -- "$1" && stat -c %s -- "$1" && exit 0
+test -f "$1" || exit 4
+exit 1"#;
+
+pub fn parse_poll_output(code: i64, stdout: &str) -> ViewerPoll {
+    if code == 4 {
+        return ViewerPoll { exists: false, hash: None, size: None };
+    }
+    let mut lines = stdout.lines();
+    let hash = lines
+        .next()
+        .and_then(|l| l.split_whitespace().next())
+        // GNU `sha256sum` prefixes the line with `\` when the name contains a
+        // backslash or a newline; strip it before validating the hex (P15).
+        .map(|h| h.trim_start_matches('\\'))
+        .filter(|h| super::write::is_sha256_hex(h))
+        .map(str::to_string);
+    let size = lines.next().and_then(|l| l.trim().parse::<u64>().ok());
+    ViewerPoll { exists: true, hash, size }
+}
+
+pub async fn poll_file(
+    container: &ContainerTarget,
+    container_path: &str,
+) -> Result<ViewerPoll, String> {
+    let cmd = vec![
+        "sh".to_string(),
+        "-c".to_string(),
+        POLL_SCRIPT.to_string(),
+        "poll".to_string(),
+        container_path.to_string(),
+    ];
+    let (stdout, stderr, code) = container
+        .exec_oneshot_streams_as("claude", cmd, Vec::new())
+        .await?;
+    if code != 0 && code != 4 {
+        return Err(format!(
+            "Could not check the file: {}",
+            crate::commands::file_commands::clip_container_text(&stderr)
+        ));
+    }
+    Ok(parse_poll_output(code, &stdout))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_present_file_yields_hash_and_size() {
+        let out = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  /workspace/x\n42\n";
+        assert_eq!(
+            parse_poll_output(0, out),
+            ViewerPoll {
+                exists: true,
+                hash: Some("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855".into()),
+                size: Some(42)
+            }
+        );
+    }
+
+    #[test]
+    fn exit_four_means_gone() {
+        assert_eq!(parse_poll_output(4, ""), ViewerPoll { exists: false, hash: None, size: None });
+    }
+
+    #[test]
+    fn garbage_is_not_a_hash() {
+        let p = parse_poll_output(0, "not a hash  /x\nabc\n");
+        assert_eq!(p, ViewerPoll { exists: true, hash: None, size: None });
+    }
+
+    #[test]
+    fn the_script_tests_existence_before_hashing() {
+        assert!(POLL_SCRIPT.contains("test -f \"$1\" || exit 4"));
+        assert!(POLL_SCRIPT.contains("sha256sum -- \"$1\""));
+        assert!(POLL_SCRIPT.contains("stat -c %s -- \"$1\""));
+    }
+
+    #[cfg(unix)]
+    fn run_poll_script(path_env: Option<&str>, target: &std::path::Path) -> (i64, String, String) {
+        let mut cmd = std::process::Command::new("sh");
+        if let Some(p) = path_env {
+            cmd.env("PATH", p);
+        }
+        let out = cmd.arg("-c").arg(POLL_SCRIPT).arg("poll").arg(target).output().unwrap();
+        (
+            out.status.code().unwrap_or(-1) as i64,
+            String::from_utf8_lossy(&out.stdout).into_owned(),
+            String::from_utf8_lossy(&out.stderr).into_owned(),
+        )
+    }
+
+    #[cfg(unix)]
+    fn test_dir(name: &str) -> std::path::PathBuf {
+        let dir = std::env::temp_dir().join(format!("tc-poll-{}-{}", name, uuid::Uuid::new_v4()));
+        std::fs::create_dir_all(&dir).unwrap();
+        dir
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn on_the_host_the_poll_script_reports_hash_size_and_gone() {
+        let dir = test_dir("plain");
+        let target = dir.join("t.txt");
+        std::fs::write(&target, b"hello\n").unwrap();
+        let (code, stdout, stderr) = run_poll_script(None, &target);
+        assert_eq!(code, 0, "stderr={stderr}");
+        let p = parse_poll_output(code, &stdout);
+        assert_eq!(p.hash.as_deref(), Some(super::super::write::sha256_hex(b"hello\n").as_str()));
+        assert_eq!(p.size, Some(6));
+
+        let (code, _, _) = run_poll_script(None, &dir.join("missing"));
+        assert_eq!(code, 4);
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    /// M6: the file is deleted after `test -f` passed but before `sha256sum` read it
+    /// (a `sha256sum` shim on PATH deletes it and fails). That is "gone", not an error
+    /// the viewer would have to explain.
+    #[cfg(unix)]
+    #[test]
+    fn on_the_host_a_file_deleted_mid_poll_reads_as_gone() {
+        use std::os::unix::fs::PermissionsExt;
+        let dir = test_dir("race");
+        let bin = dir.join("bin");
+        std::fs::create_dir_all(&bin).unwrap();
+        let shim = bin.join("sha256sum");
+        std::fs::write(&shim, "#!/bin/sh\nrm -f -- \"$2\"\necho 'sha256sum: No such file or directory' >&2\nexit 1\n").unwrap();
+        std::fs::set_permissions(&shim, std::fs::Permissions::from_mode(0o755)).unwrap();
+        let target = dir.join("t.txt");
+        std::fs::write(&target, b"x").unwrap();
+        let path = format!("{}:{}", bin.display(), std::env::var("PATH").unwrap_or_default());
+
+        let (code, stdout, stderr) = run_poll_script(Some(&path), &target);
+
+        assert_eq!(code, 4, "stderr={stderr}");
+        assert_eq!(parse_poll_output(code, &stdout), ViewerPoll { exists: false, hash: None, size: None });
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    /// A failure with the file still present stays a real error (exit 1), which
+    /// `poll_file` turns into "Could not check the file: …".
+    #[cfg(unix)]
+    #[test]
+    fn on_the_host_a_hash_failure_on_a_present_file_is_an_error() {
+        use std::os::unix::fs::PermissionsExt;
+        let dir = test_dir("fail");
+        let bin = dir.join("bin");
+        std::fs::create_dir_all(&bin).unwrap();
+        let shim = bin.join("sha256sum");
+        std::fs::write(&shim, "#!/bin/sh\necho 'sha256sum: Permission denied' >&2\nexit 1\n").unwrap();
+        std::fs::set_permissions(&shim, std::fs::Permissions::from_mode(0o755)).unwrap();
+        let target = dir.join("t.txt");
+        std::fs::write(&target, b"x").unwrap();
+        let path = format!("{}:{}", bin.display(), std::env::var("PATH").unwrap_or_default());
+
+        let (code, _stdout, stderr) = run_poll_script(Some(&path), &target);
+
+        assert_eq!(code, 1, "stderr={stderr}");
+        assert!(stderr.contains("Permission denied"));
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    /// P15: a path containing a backslash makes GNU `sha256sum` prefix the whole
+    /// line with `\`; that must not blind change detection by yielding `hash: None`.
+    #[test]
+    fn a_backslash_prefixed_hash_is_still_recognised() {
+        let out = "\\e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  /workspace/x\\y\n7\n";
+        let p = parse_poll_output(0, out);
+        assert_eq!(
+            p.hash.as_deref(),
+            Some("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855")
+        );
+        assert_eq!(p.size, Some(7));
+    }
+}

app/src-tauri/src/file_viewer/registry.rs

@@ -0,0 +1,379 @@
+//! Which viewer window is looking at what.
+//!
+//! Managed with `app.manage(ViewerRegistry::default())` rather than as a field on
+//! `AppState`, like the browser view keeps its own state. A label is reserved *before*
+//! the window is built so two concurrent clicks cannot both pass the cap check.
+
+use std::collections::HashMap;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Mutex;
+
+use serde::{Deserialize, Serialize};
+
+use super::{MAX_VIEWER_WINDOWS, VIEWER_LABEL_PREFIX};
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub struct Location {
+    pub line: Option<u32>,
+    pub col: Option<u32>,
+    pub end_line: Option<u32>,
+}
+
+#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum ViewerTargetState {
+    Resolved { container_path: String },
+    Choose { candidates: Vec<String> },
+    NotFound { tried: Vec<String> },
+}
+
+#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
+pub struct ViewerTarget {
+    pub project_id: String,
+    pub project_name: String,
+    pub raw_path: String,
+    pub state: ViewerTargetState,
+    pub initial: Location,
+}
+
+/// What [`ViewerRegistry::reserve`] decided.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum Reservation {
+    /// A window is already registered on this file. `built` is false while that
+    /// window is still being created: it has no `WebviewWindow` to focus yet, and
+    /// it will open at its own location, so the caller should simply return.
+    Existing { label: String, built: bool },
+    /// A new label, registered and counted against the cap; build its window,
+    /// then call [`ViewerRegistry::mark_built`] (or `remove` if building failed).
+    Reserved(String),
+}
+
+/// What [`ViewerRegistry::choose`] decided.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum Choice {
+    /// The caller's entry now points at the chosen file.
+    Resolved(ViewerTarget),
+    /// Another window already has that file; the caller's entry is unchanged.
+    AlreadyOpen { label: String, built: bool },
+}
+
+#[derive(Clone, Debug)]
+struct Entry {
+    target: ViewerTarget,
+    /// Set once the window's `build()` has returned. Until then the label has no
+    /// window by design, so "registered but windowless" means "being built", not
+    /// "stale" — only built entries are ever pruned.
+    built: bool,
+}
+
+#[derive(Default)]
+pub struct ViewerRegistry {
+    entries: Mutex<HashMap<String, Entry>>,
+    next: AtomicU64,
+}
+
+fn same_file(t: &ViewerTarget, project_id: &str, container_path: &str) -> bool {
+    t.project_id == project_id
+        && matches!(&t.state, ViewerTargetState::Resolved { container_path: p } if p == container_path)
+}
+
+fn open_on(
+    entries: &HashMap<String, Entry>,
+    project_id: &str,
+    container_path: &str,
+    except: Option<&str>,
+) -> Option<(String, bool)> {
+    entries
+        .iter()
+        .find(|(label, e)| Some(label.as_str()) != except && same_file(&e.target, project_id, container_path))
+        .map(|(label, e)| (label.clone(), e.built))
+}
+
+/// Drops built entries whose window is gone, whatever their state. `Destroyed`
+/// normally removes an entry; this is the backstop for one it missed, so a leak
+/// can never hold a cap slot for good.
+fn prune(entries: &mut HashMap<String, Entry>, is_live: &dyn Fn(&str) -> bool) {
+    entries.retain(|label, e| !e.built || is_live(label));
+}
+
+impl ViewerRegistry {
+    fn lock(&self) -> std::sync::MutexGuard<'_, HashMap<String, Entry>> {
+        self.entries.lock().unwrap_or_else(|e| e.into_inner())
+    }
+
+    /// Finds the window already open on a resolved target, or reserves a label,
+    /// in one critical section, after pruning built entries `is_live` says are
+    /// gone. `is_live` runs under the registry lock and must not call back into
+    /// the registry.
+    pub fn reserve(
+        &self,
+        target: ViewerTarget,
+        is_live: impl Fn(&str) -> bool,
+    ) -> Result<Reservation, String> {
+        let mut entries = self.lock();
+        prune(&mut entries, &is_live);
+        if let ViewerTargetState::Resolved { container_path } = &target.state {
+            if let Some((label, built)) = open_on(&entries, &target.project_id, container_path, None) {
+                return Ok(Reservation::Existing { label, built });
+            }
+        }
+        if entries.len() >= MAX_VIEWER_WINDOWS {
+            return Err(format!(
+                "{} file windows are already open — close one before opening another.",
+                MAX_VIEWER_WINDOWS
+            ));
+        }
+        let n = self.next.fetch_add(1, Ordering::SeqCst) + 1;
+        let label = format!("{}{}", VIEWER_LABEL_PREFIX, n);
+        entries.insert(label.clone(), Entry { target, built: false });
+        Ok(Reservation::Reserved(label))
+    }
+
+    /// Records that `label`'s window exists. A no-op if it was already removed
+    /// (a window destroyed the moment it appeared).
+    pub fn mark_built(&self, label: &str) {
+        if let Some(e) = self.lock().get_mut(label) {
+            e.built = true;
+        }
+    }
+
+    /// Points `label`'s entry at `container_path`, unless another window already
+    /// has that file open — then the entry is left alone, so no two entries are
+    /// ever resolved to the same file.
+    pub fn choose(
+        &self,
+        label: &str,
+        container_path: String,
+        is_live: impl Fn(&str) -> bool,
+    ) -> Result<Choice, String> {
+        let mut entries = self.lock();
+        prune(&mut entries, &is_live);
+        let project_id = entries
+            .get(label)
+            .ok_or_else(|| "This file window is no longer registered.".to_string())?
+            .target
+            .project_id
+            .clone();
+        if let Some((other, built)) = open_on(&entries, &project_id, &container_path, Some(label)) {
+            return Ok(Choice::AlreadyOpen { label: other, built });
+        }
+        let entry = entries.get_mut(label).expect("checked above under the same lock");
+        entry.target.state = ViewerTargetState::Resolved { container_path };
+        Ok(Choice::Resolved(entry.target.clone()))
+    }
+
+    pub fn get(&self, label: &str) -> Option<ViewerTarget> {
+        self.lock().get(label).map(|e| e.target.clone())
+    }
+
+    pub fn set_state(&self, label: &str, state: ViewerTargetState) -> Result<ViewerTarget, String> {
+        let mut entries = self.lock();
+        let entry = entries
+            .get_mut(label)
+            .ok_or_else(|| "This file window is no longer registered.".to_string())?;
+        entry.target.state = state;
+        Ok(entry.target.clone())
+    }
+
+    pub fn remove(&self, label: &str) {
+        self.lock().remove(label);
+    }
+
+    pub fn find_open(&self, project_id: &str, container_path: &str) -> Option<String> {
+        open_on(&self.lock(), project_id, container_path, None).map(|(label, _)| label)
+    }
+
+    pub fn len(&self) -> usize {
+        self.lock().len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn target(project: &str, path: &str) -> ViewerTarget {
+        ViewerTarget {
+            project_id: project.into(),
+            project_name: "Demo".into(),
+            raw_path: path.into(),
+            state: ViewerTargetState::Resolved { container_path: path.into() },
+            initial: Location { line: Some(3), col: None, end_line: None },
+        }
+    }
+
+    fn all_live(_: &str) -> bool {
+        true
+    }
+
+    /// Reserves a label that must be new.
+    fn fresh(r: &ViewerRegistry, t: ViewerTarget) -> String {
+        match r.reserve(t, all_live).unwrap() {
+            Reservation::Reserved(label) => label,
+            other => panic!("expected a new label, got {:?}", other),
+        }
+    }
+
+    fn choosing(project: &str, candidates: &[&str]) -> ViewerTarget {
+        ViewerTarget {
+            state: ViewerTargetState::Choose { candidates: candidates.iter().map(|c| c.to_string()).collect() },
+            ..target(project, "a")
+        }
+    }
+
+    #[test]
+    fn labels_are_sequential_and_never_reused() {
+        let r = ViewerRegistry::default();
+        let a = fresh(&r, target("p", "/workspace/a"));
+        let b = fresh(&r, target("p", "/workspace/b"));
+        assert_eq!(a, "file-viewer-1");
+        assert_eq!(b, "file-viewer-2");
+        r.remove(&a);
+        let c = fresh(&r, target("p", "/workspace/c"));
+        assert_eq!(c, "file-viewer-3");
+        assert_eq!(r.len(), 2);
+    }
+
+    #[test]
+    fn the_cap_refuses_the_twenty_first_window() {
+        let r = ViewerRegistry::default();
+        for i in 0..MAX_VIEWER_WINDOWS {
+            fresh(&r, target("p", &format!("/workspace/{}", i)));
+        }
+        let err = r.reserve(target("p", "/workspace/one-more"), all_live).unwrap_err();
+        assert!(err.contains("20"), "{}", err);
+        assert_eq!(r.len(), MAX_VIEWER_WINDOWS);
+    }
+
+    #[test]
+    fn an_open_resolved_file_is_found_by_project_and_path() {
+        let r = ViewerRegistry::default();
+        let label = fresh(&r, target("p", "/workspace/a"));
+        assert_eq!(r.find_open("p", "/workspace/a"), Some(label.clone()));
+        assert_eq!(r.find_open("other", "/workspace/a"), None);
+        // A window still choosing is not "open on" any path.
+        r.set_state(&label, ViewerTargetState::Choose { candidates: vec!["/workspace/a".into()] }).unwrap();
+        assert_eq!(r.find_open("p", "/workspace/a"), None);
+        r.remove(&label);
+        assert_eq!(r.get(&label), None);
+    }
+
+    #[test]
+    fn set_state_on_an_unknown_label_is_an_error() {
+        let r = ViewerRegistry::default();
+        assert!(r.set_state("file-viewer-9", ViewerTargetState::NotFound { tried: vec![] }).is_err());
+    }
+
+    #[test]
+    fn target_state_serialises_with_a_kind_tag() {
+        let s = serde_json::to_string(&ViewerTargetState::NotFound { tried: vec!["/x".into()] }).unwrap();
+        assert_eq!(s, r#"{"kind":"not_found","tried":["/x"]}"#);
+    }
+
+    /// I1: a second click while the first window is still being built must find
+    /// that window, not read it as stale and reserve a second one.
+    #[test]
+    fn a_window_being_built_is_found_not_replaced() {
+        let r = ViewerRegistry::default();
+        let a = fresh(&r, target("p", "/workspace/a"));
+        // No window exists yet for `a`: `is_live` says so, and it must not matter.
+        let second = r.reserve(target("p", "/workspace/a"), |_| false).unwrap();
+        assert_eq!(second, Reservation::Existing { label: a.clone(), built: false });
+        assert!(r.get(&a).is_some());
+        assert_eq!(r.len(), 1);
+
+        r.mark_built(&a);
+        let third = r.reserve(target("p", "/workspace/a"), all_live).unwrap();
+        assert_eq!(third, Reservation::Existing { label: a, built: true });
+        assert_eq!(r.len(), 1);
+    }
+
+    /// A built entry whose window is gone is stale: pruned, and the file reopens.
+    #[test]
+    fn a_built_entry_without_a_window_is_pruned_and_the_file_reopens() {
+        let r = ViewerRegistry::default();
+        let a = fresh(&r, target("p", "/workspace/a"));
+        r.mark_built(&a);
+        let again = r.reserve(target("p", "/workspace/a"), |_| false).unwrap();
+        assert_eq!(again, Reservation::Reserved("file-viewer-2".into()));
+        assert_eq!(r.get(&a), None);
+        assert_eq!(r.len(), 1);
+    }
+
+    /// M2: a leaked entry of any state cannot hold a cap slot once built and gone,
+    /// and an entry still being built always keeps its slot.
+    #[test]
+    fn leaked_entries_of_every_state_free_their_cap_slot() {
+        let r = ViewerRegistry::default();
+        let mut labels = Vec::new();
+        for i in 0..MAX_VIEWER_WINDOWS {
+            let t = match i % 3 {
+                0 => target("p", &format!("/workspace/{}", i)),
+                1 => choosing("p", &["/workspace/x", "/workspace/y"]),
+                _ => ViewerTarget { state: ViewerTargetState::NotFound { tried: vec![] }, ..target("p", "z") },
+            };
+            labels.push(fresh(&r, t));
+        }
+        // All still being built: none may be pruned, so the cap holds.
+        assert!(r.reserve(target("p", "/workspace/new"), |_| false).is_err());
+        for l in &labels {
+            r.mark_built(l);
+        }
+        // Built, and one of each state has lost its window.
+        let dead = [labels[0].clone(), labels[1].clone(), labels[2].clone()];
+        let live = |l: &str| !dead.iter().any(|d| d == l);
+        assert!(matches!(r.reserve(target("p", "/workspace/new"), live), Ok(Reservation::Reserved(_))));
+        assert_eq!(r.len(), MAX_VIEWER_WINDOWS - 2);
+        for d in &dead {
+            assert_eq!(r.get(d), None);
+        }
+    }
+
+    #[test]
+    fn mark_built_on_a_removed_label_is_a_no_op() {
+        let r = ViewerRegistry::default();
+        let a = fresh(&r, target("p", "/workspace/a"));
+        r.remove(&a);
+        r.mark_built(&a);
+        assert_eq!(r.get(&a), None);
+    }
+
+    /// M5: choosing a file another window already has leaves the chooser alone,
+    /// so two entries are never resolved to the same file.
+    #[test]
+    fn choosing_a_file_open_elsewhere_does_not_resolve_a_second_entry() {
+        let r = ViewerRegistry::default();
+        let open = fresh(&r, target("p", "/workspace/x"));
+        r.mark_built(&open);
+        let chooser = fresh(&r, choosing("p", &["/workspace/x", "/workspace/y"]));
+        r.mark_built(&chooser);
+
+        let c = r.choose(&chooser, "/workspace/x".into(), all_live).unwrap();
+        assert_eq!(c, Choice::AlreadyOpen { label: open.clone(), built: true });
+        assert!(matches!(r.get(&chooser).unwrap().state, ViewerTargetState::Choose { .. }));
+
+        match r.choose(&chooser, "/workspace/y".into(), all_live).unwrap() {
+            Choice::Resolved(t) => assert_eq!(t.state, ViewerTargetState::Resolved { container_path: "/workspace/y".into() }),
+            other => panic!("expected Resolved, got {:?}", other),
+        }
+        assert_eq!(r.find_open("p", "/workspace/y"), Some(chooser));
+    }
+
+    #[test]
+    fn choosing_the_same_path_in_another_project_is_not_a_duplicate() {
+        let r = ViewerRegistry::default();
+        fresh(&r, target("other", "/workspace/x"));
+        let chooser = fresh(&r, choosing("p", &["/workspace/x"]));
+        assert!(matches!(r.choose(&chooser, "/workspace/x".into(), all_live), Ok(Choice::Resolved(_))));
+    }
+
+    #[test]
+    fn choose_on_an_unknown_label_is_an_error() {
+        let r = ViewerRegistry::default();
+        assert!(r.choose("file-viewer-9", "/workspace/x".into(), all_live).is_err());
+    }
+}

app/src-tauri/src/file_viewer/resolve.rs

@@ -0,0 +1,240 @@
+//! Turning what Claude printed into a container path that exists.
+//!
+//! Relative paths are the common case (Claude prints project-relative paths). The
+//! terminal exec's cwd is `/workspace`, and each project path is mounted at
+//! `/workspace/<mount_name>`, so those are the roots probed, in that order.
+//! A relative path none of them has is then tried under `/home/claude` and `/tmp`
+//! ([`fallback_candidate_paths`]); `~/p` is `/home/claude/p`. The probe
+//! is one exec as the container user and prints `realpath -e` of every candidate that
+//! is a regular file: `fetch_container_file` refuses a symlink, so the registry must
+//! hold the resolved path, not the one that was clicked.
+
+use crate::commands::file_commands::validate_container_path;
+use crate::docker::CONTAINER_HOME;
+use crate::host::ContainerTarget;
+
+pub const MAX_CANDIDATES: usize = 16;
+const MAX_RAW_LEN: usize = 4096;
+
+/// `$@` are the candidates. For each regular file, print its resolved path.
+pub const PROBE_SCRIPT: &str = r#"for c in "$@"; do if test -f "$c"; then realpath -e -- "$c" 2>/dev/null; fi; done; exit 0"#;
+
+pub fn candidate_paths(raw: &str, mount_names: &[String]) -> Result<Vec<String>, String> {
+    if raw.is_empty() {
+        return Err("The path is empty.".into());
+    }
+    if raw.len() > MAX_RAW_LEN {
+        return Err("The path is too long.".into());
+    }
+    if raw.contains('\0') {
+        return Err("The path contains a NUL byte.".into());
+    }
+    if raw.split('/').any(|seg| seg == "..") {
+        return Err(format!("{} climbs out of its folder with `..`; refusing.", raw));
+    }
+
+    if raw.starts_with('/') {
+        let normalised = collapse(raw);
+        validate_container_path("File", &normalised)?;
+        return Ok(vec![normalised]);
+    }
+
+    // Claude Code prints paths under $HOME as `~/...`. Only the bare `~/` form:
+    // `~user/` names some other account's home and stays an ordinary name.
+    if let Some(rest) = raw.strip_prefix("~/") {
+        let rest = collapse(rest);
+        if rest.is_empty() {
+            return Err("The path is empty.".into());
+        }
+        let p = format!("{}/{}", CONTAINER_HOME, rest);
+        validate_container_path("File", &p)?;
+        return Ok(vec![p]);
+    }
+
+    let rel = relative_part(raw).ok_or_else(|| "The path is empty.".to_string())?;
+
+    let mut out: Vec<String> = Vec::new();
+    let mut push = |candidate: String| {
+        if out.len() < MAX_CANDIDATES && !out.contains(&candidate) {
+            out.push(candidate);
+        }
+    };
+    push(format!("/workspace/{}", rel));
+    for mount in mount_names {
+        if mount.is_empty() || mount.contains('/') || mount == "." || mount == ".." {
+            continue;
+        }
+        push(format!("/workspace/{}/{}", mount, rel));
+    }
+    for c in &out {
+        validate_container_path("File", c)?;
+    }
+    Ok(out)
+}
+
+/// Where a relative path is looked for when no project root has it, in order.
+/// The container user's home, then `/tmp` (drops, pastes and scratch files).
+/// Probed only after [`candidate_paths`] found nothing, so a project file never
+/// turns into a "which one?" chooser because a same-named file sits in `/tmp`.
+const FALLBACK_ROOTS: &[&str] = &[CONTAINER_HOME, "/tmp"];
+
+/// The second tier for a relative path: [`FALLBACK_ROOTS`]`/<p>`. Empty for an
+/// absolute or `~/` path (those name one place already) and for anything
+/// [`candidate_paths`] refuses — it is always called after that succeeded, but
+/// must not be a way around its checks.
+pub fn fallback_candidate_paths(raw: &str) -> Vec<String> {
+    if raw.starts_with('/') || raw.starts_with("~/") || candidate_paths(raw, &[]).is_err() {
+        return Vec::new();
+    }
+    let Some(rel) = relative_part(raw) else { return Vec::new() };
+    FALLBACK_ROOTS
+        .iter()
+        .map(|root| format!("{}/{}", root, rel))
+        .filter(|c| validate_container_path("File", c).is_ok())
+        .take(MAX_CANDIDATES)
+        .collect()
+}
+
+/// `./a//b` → `a/b`; `None` when nothing is left.
+fn relative_part(raw: &str) -> Option<String> {
+    let rel = collapse(raw.strip_prefix("./").unwrap_or(raw));
+    let rel = rel.trim_start_matches("./");
+    (!rel.is_empty()).then(|| rel.to_string())
+}
+
+/// `a//b/./c` → `a/b/c`. Never touches `..` (rejected before this runs).
+fn collapse(path: &str) -> String {
+    let absolute = path.starts_with('/');
+    let joined = path
+        .split('/')
+        .filter(|seg| !seg.is_empty() && *seg != ".")
+        .collect::<Vec<_>>()
+        .join("/");
+    if absolute { format!("/{}", joined) } else { joined }
+}
+
+/// One resolved path per line; anything that is not an absolute, valid container path is
+/// dropped (the script's own diagnostics go to stderr, but a hostile `realpath` output is
+/// still container-authored text).
+pub fn parse_probe_output(stdout: &str) -> Vec<String> {
+    let mut seen: Vec<String> = Vec::new();
+    for line in stdout.lines() {
+        let line = line.trim();
+        if line.is_empty() || validate_container_path("File", line).is_err() {
+            continue;
+        }
+        if !seen.iter().any(|s| s == line) {
+            seen.push(line.to_string());
+        }
+    }
+    seen
+}
+
+pub async fn probe_candidates(
+    container: &ContainerTarget,
+    candidates: &[String],
+) -> Result<Vec<String>, String> {
+    let mut cmd: Vec<String> = vec!["sh".into(), "-c".into(), PROBE_SCRIPT.into(), "probe".into()];
+    cmd.extend(candidates.iter().cloned());
+    let (stdout, _stderr, _code) = container
+        .exec_oneshot_streams_as("claude", cmd, Vec::new())
+        .await?;
+    Ok(parse_probe_output(&stdout))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn mounts(names: &[&str]) -> Vec<String> {
+        names.iter().map(|s| s.to_string()).collect()
+    }
+
+    #[test]
+    fn an_absolute_path_is_its_own_only_candidate() {
+        let c = candidate_paths("/workspace/api/src/main.rs", &mounts(&["api"])).unwrap();
+        assert_eq!(c, vec!["/workspace/api/src/main.rs"]);
+    }
+
+    #[test]
+    fn a_relative_path_probes_workspace_then_each_mount() {
+        let c = candidate_paths("src/main.rs", &mounts(&["api", "web"])).unwrap();
+        assert_eq!(
+            c,
+            vec!["/workspace/src/main.rs", "/workspace/api/src/main.rs", "/workspace/web/src/main.rs"]
+        );
+    }
+
+    #[test]
+    fn dot_prefix_and_duplicate_slashes_are_normalised_and_candidates_deduped() {
+        let c = candidate_paths("./src//main.rs", &mounts(&["api", "api", ""])).unwrap();
+        assert_eq!(c, vec!["/workspace/src/main.rs", "/workspace/api/src/main.rs"]);
+    }
+
+    #[test]
+    fn an_absolute_tmp_path_is_accepted_as_is() {
+        // Claude Code's scratchpad: long, and with a segment that starts with `-`.
+        let p = "/tmp/claude-1000/-workspace/5e4ab145-915e-4902-9329-e039e2a07562/scratchpad/notes.md";
+        assert_eq!(candidate_paths(p, &mounts(&["api"])).unwrap(), vec![p]);
+    }
+
+    #[test]
+    fn a_home_relative_path_is_the_container_users_home() {
+        // Claude Code prints paths under $HOME as `~/...`.
+        let c = candidate_paths("~/.claude/plans/plan.md", &mounts(&["api"])).unwrap();
+        assert_eq!(c, vec!["/home/claude/.claude/plans/plan.md"]);
+        assert!(candidate_paths("~/", &[]).is_err());
+        assert!(candidate_paths("~/../etc/passwd", &[]).is_err());
+        // `~user/` is not expanded; it stays an ordinary relative name.
+        assert_eq!(candidate_paths("~bob/x.md", &[]).unwrap(), vec!["/workspace/~bob/x.md"]);
+    }
+
+    #[test]
+    fn a_relative_path_falls_back_to_home_and_tmp() {
+        assert_eq!(
+            fallback_candidate_paths("scratch/notes.md"),
+            vec!["/home/claude/scratch/notes.md", "/tmp/scratch/notes.md"]
+        );
+        assert_eq!(fallback_candidate_paths("./notes.md"), vec!["/home/claude/notes.md", "/tmp/notes.md"]);
+        // Absolute, home-relative and refused paths have no fallbacks.
+        assert!(fallback_candidate_paths("/tmp/notes.md").is_empty());
+        assert!(fallback_candidate_paths("~/notes.md").is_empty());
+        assert!(fallback_candidate_paths("../notes.md").is_empty());
+        assert!(fallback_candidate_paths("").is_empty());
+    }
+
+    #[test]
+    fn traversal_nul_and_oversize_are_refused() {
+        assert!(candidate_paths("../etc/passwd", &[]).is_err());
+        assert!(candidate_paths("src/../../x", &[]).is_err());
+        assert!(candidate_paths("/workspace/../etc/passwd", &[]).is_err());
+        assert!(candidate_paths("a\0b", &[]).is_err());
+        assert!(candidate_paths("", &[]).is_err());
+        assert!(candidate_paths(&"a".repeat(5000), &[]).is_err());
+    }
+
+    #[test]
+    fn candidate_list_is_capped() {
+        let many: Vec<String> = (0..40).map(|i| format!("m{}", i)).collect();
+        let c = candidate_paths("x.rs", &many).unwrap();
+        assert_eq!(c.len(), MAX_CANDIDATES);
+    }
+
+    #[test]
+    fn probe_output_keeps_valid_resolved_regular_files_only() {
+        let out = "/workspace/api/src/main.rs\n/workspace/api/src/main.rs\n\nrelative/junk\n/etc/../x\n/workspace/web/src/main.rs\n";
+        assert_eq!(
+            parse_probe_output(out),
+            vec!["/workspace/api/src/main.rs", "/workspace/web/src/main.rs"]
+        );
+    }
+
+    #[test]
+    fn the_probe_script_prints_resolved_paths_of_regular_files() {
+        // Shape assertions: the script is data handed to `sh -c`, and these are the
+        // three things a later edit must not lose.
+        assert!(PROBE_SCRIPT.contains("test -f"));
+        assert!(PROBE_SCRIPT.contains("realpath -e --"));
+        assert!(PROBE_SCRIPT.contains("for c in \"$@\""));
+    }
+}

app/src-tauri/src/file_viewer/window.rs

@@ -0,0 +1,27 @@
+//! The viewer window itself. Mirrors `browser_view/popout.rs`, with two differences:
+//! the URL is the app's own second entry (`WebviewUrl::App`), so the capability in
+//! `capabilities/file-viewer.json` applies; and the registry entry is removed on
+//! `Destroyed`, which fires for both the X button (after JS calls `destroy()`) and a
+//! Rust-side `destroy()`.
+
+use tauri::{AppHandle, Manager, WebviewUrl, WebviewWindowBuilder, WindowEvent};
+
+use super::registry::ViewerRegistry;
+
+pub fn open_viewer_window(app: &AppHandle, label: &str, title: &str) -> Result<(), String> {
+    let window = WebviewWindowBuilder::new(app, label, WebviewUrl::App("viewer.html".into()))
+        .title(title)
+        .inner_size(900.0, 700.0)
+        .min_inner_size(480.0, 320.0)
+        .build()
+        .map_err(|e| format!("Could not open the file window: {}", e))?;
+
+    let app_for_event = app.clone();
+    let label_owned = label.to_string();
+    window.on_window_event(move |event| {
+        if let WindowEvent::Destroyed = event {
+            app_for_event.state::<ViewerRegistry>().remove(&label_owned);
+        }
+    });
+    Ok(())
+}