Pin the Supabase CLI to 2.121.0 so every worktree uses one image set

.claude/skills/verify-debatelab/bin/verify.sh

@@ -25,6 +25,8 @@ SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 REPO="$(git -C "$SKILL_DIR" rev-parse --show-toplevel)"
 cd "$REPO"
 source "$REPO/.superset/lib/lock.sh"
+source "$REPO/.superset/lib/supabase-cli.sh"
+use_pinned_supabase_cli "$REPO"
 
 DB_LOCK="$HOME/.superset/debatelab-db.lock"
 FAKE_PROVIDER=debatelab-fake-openrouter

.github/workflows/agentic-e2e.yml

@@ -80,7 +80,7 @@ jobs:
       - name: Set up Supabase CLI
         uses: supabase/setup-cli@46f7f98c7f948ad727d22c1e67fab04c223a0520 # v3.0.0
         with:
-          version: 2.116.0
+          version: 2.121.0
 
       - name: Install dependencies
         run: npm ci
@@ -186,7 +186,7 @@ jobs:
       - name: Set up Supabase CLI
         uses: supabase/setup-cli@46f7f98c7f948ad727d22c1e67fab04c223a0520 # v3.0.0
         with:
-          version: 2.116.0
+          version: 2.121.0
 
       - name: Install dependencies
         run: npm ci

.github/workflows/database.yml

@@ -72,7 +72,7 @@ jobs:
       - name: Set up Supabase CLI
         uses: supabase/setup-cli@46f7f98c7f948ad727d22c1e67fab04c223a0520 # v3.0.0
         with:
-          version: 2.116.0
+          version: 2.121.0
 
       - name: Install dependencies
         run: npm ci

.github/workflows/live-e2e.yml

@@ -42,7 +42,7 @@ jobs:
       - name: Set up Supabase CLI
         uses: supabase/setup-cli@46f7f98c7f948ad727d22c1e67fab04c223a0520 # v3.0.0
         with:
-          version: 2.116.0
+          version: 2.121.0
 
       - name: Install dependencies
         run: npm ci

.github/workflows/model-matrix.yml

@@ -42,7 +42,7 @@ jobs:
       - name: Set up Supabase CLI
         uses: supabase/setup-cli@46f7f98c7f948ad727d22c1e67fab04c223a0520 # v3.0.0
         with:
-          version: 2.116.0
+          version: 2.121.0
 
       - name: Install dependencies
         run: npm ci

.superset/db-gate.sh

@@ -21,6 +21,8 @@ esac
 
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$DIR/lib/lock.sh"
+source "$DIR/lib/supabase-cli.sh"
+use_pinned_supabase_cli "$(cd "$DIR/.." && pwd)"
 
 DB_LOCK="$HOME/.superset/debatelab-db.lock"
 FAKE_PROVIDER=debatelab-fake-openrouter

.superset/lib/supabase-cli.sh

@@ -0,0 +1,14 @@
+# Puts the repo-pinned Supabase CLI (the exact `supabase` devDependency in
+# package.json) first on PATH. Every worktree then runs one CLI version, so
+# Docker keeps one Supabase image set instead of one per CLI version.
+# Tests point DEBATELAB_SUPABASE_BIN_DIR at a stub directory instead.
+#
+# usage: use_pinned_supabase_cli <repo root>
+use_pinned_supabase_cli() {
+  local bin="${DEBATELAB_SUPABASE_BIN_DIR:-$1/node_modules/.bin}"
+  if [ ! -x "$bin/supabase" ]; then
+    echo "The repo-pinned Supabase CLI is missing ($bin/supabase). Run npm ci first." >&2
+    return 1
+  fi
+  export PATH="$bin:$PATH"
+}

.superset/teardown.sh

@@ -6,6 +6,9 @@ set -euo pipefail
 
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$DIR/lib/lock.sh"
+source "$DIR/lib/supabase-cli.sh"
+# Teardown still runs when npm ci never did; then there is no stack to stop.
+use_pinned_supabase_cli "$(cd "$DIR/.." && pwd)" 2>/dev/null || exit 0
 
 WORKSPACE_KEY="$(pwd)"
 PORTS_LOCK="$HOME/.superset/debatelab-ports/lock"

AGENTS.md

@@ -75,12 +75,12 @@ Database migrations and pgTAP policies use a separate Docker-backed gate. In Sup
 Outside Superset, run the underlying commands directly:
 
 ```bash
-supabase db start
+npx supabase db start
 npm run test:db
-supabase stop --no-backup
+npx supabase stop --no-backup
 ```
 
-Supabase CLI 2.115 or newer is required. Do not run this gate concurrently from multiple worktrees. If this task starts the stack, stop it before finishing, including after failures when safe.
+Use only the repo-pinned Supabase CLI (the exact `supabase` devDependency, 2.121.0). `npm run` scripts, `./.superset/db-gate.sh`, `scripts/agent-stack.sh`, and the verify harness already put it first on PATH; anywhere else, call `npx supabase`. Never use a global CLI or `npx supabase@latest`, and never bump the version in one worktree only: each CLI version pulls its own ~7 GB set of Docker images onto the shared VPS. Change it in `package.json`, `package-lock.json`, and the `setup-cli` steps in `.github/workflows/` together. Do not run this gate concurrently from multiple worktrees. If this task starts the stack, stop it before finishing, including after failures when safe.
 
 WebKit is a separate release smoke test:
 

README.md

@@ -24,7 +24,7 @@ Requirements:
 
 - Node.js 22.x and npm, using the committed `package-lock.json`
 - Deno 2.x for Edge Function tests
-- Docker and Supabase CLI 2.115 or newer for the local database gate
+- Docker and Supabase CLI 2.121.0, pinned in `package.json` (`npm ci` installs it) for the local database gate
 - Playwright browsers for browser tests
 
 ```bash

docs/development.md

@@ -21,7 +21,7 @@ Never overwrite unrelated changes. Do not switch to the primary checkout because
 - Node.js 22.x
 - npm and `package-lock.json`
 - Deno 2.x for Edge Function tests
-- Docker and Supabase CLI 2.115 or newer for database work
+- Docker and Supabase CLI 2.121.0, pinned in `package.json` (`npm ci` installs it) for database work
 - Playwright browser binaries for browser gates
 
 Install the locked JavaScript tree with the Node version from `.nvmrc`:
@@ -132,9 +132,9 @@ In a Superset workspace, use the repository's locking wrapper:
 Outside Superset, run the underlying commands directly:
 
 ```bash
-supabase db start
+npx supabase db start
 npm run test:db
-supabase stop --no-backup
+npx supabase stop --no-backup
 ```
 
 The default local stack begins at port `54321` and uses shared container names, so it is not parallel-safe across worktrees. The wrapper holds `~/.superset/debatelab-db.lock` through database tests and the real-Auth collaboration browser journey, and stops the stack and owned processes on exit. Outside Superset, coordinate ownership before starting it. The agent that starts the stack stops it before finishing, including after failures when safe.

docs/testing.md

@@ -166,7 +166,7 @@ It does not start local Supabase, run pgTAP, run WebKit, or use protected stagin
 Requirements:
 
 - Docker
-- Supabase CLI 2.115 or newer
+- Supabase CLI 2.121.0, pinned in `package.json` (`npm ci` installs it)
 - exclusive ownership of the local Supabase ports and containers
 
 In Superset, run:
@@ -178,9 +178,9 @@ In Superset, run:
 The wrapper acquires `~/.superset/debatelab-db.lock`, starts full local Supabase, runs `npm run test:db`, then holds the same lock while a controlled Mailpit relay, collaboration process, fake model provider, and Vite client run the real-Auth desktop/mobile workspace and full-stack feature journeys. The `Database` workflow runs this same gate on pull requests that touch its paths, and retains its logs and browser traces on failure. It stops every owned process and the stack on exit, including after failure. To run only the database portion under the same lock, use `./.superset/db-gate.sh --db-only`. Outside Superset, run it with:
 
 ```bash
-supabase db start
+npx supabase db start
 npm run test:db
-supabase stop --no-backup
+npx supabase stop --no-backup
 ```
 
 The stack replays migrations and runs pgTAP tests. The browser portion creates isolated local users and deletes them, captures mail only in local Mailpit, restarts the collaboration process, and proves recovery and revocation. `CREATE INDEX CONCURRENTLY` requires the stated CLI floor so it runs outside the migration batch.