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

Each Supabase CLI version pulls its own ~7 GB set of Docker images. The VPS had
2.116.0 in /usr/local/bin and 2.121.0 from npm, so worktrees kept both sets.

- Add supabase 2.121.0 as an exact devDependency.
- db-gate.sh, teardown.sh, agent-stack.sh and the verify harness put the
  repo-pinned CLI first on PATH (.superset/lib/supabase-cli.sh).
- Bump the setup-cli steps in CI from 2.116.0 to 2.121.0.
- AGENTS.md and docs: use only the pinned CLI, never a global or @latest.

Author: Programcode

.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