feat: deployment-wide default model and default plan model

Extends the existing `model_preferences` table with `default_model` and
`default_plan_model` columns. Surfaces them via a new section in
Settings → Models so the deployment-wide defaults are configurable from
the UI instead of being scattered across Terraform env vars on each
worker.

Why: with plan-mode (preceding PR in stack), every deployment now
needs two default models — one for build turns, one for plan turns.
The control-plane is the natural source of truth (already serves
`enabledModels` via `/model-preferences`). The bots and the web UI
read from this single place instead of each worker carrying its own
`DEFAULT_MODEL` env var that must be kept in sync.

Changes:

- D1 migration `0021_add_default_models_to_model_preferences.sql`
  adds two nullable columns via `ALTER TABLE ADD COLUMN`. Existing
  deployments keep working because the read path falls back to the
  env var, then to the shared library constant.
- `db/model-preferences.ts` extended to read/write the new fields
  atomically across the three-field tuple.
- `GET /model-preferences` now returns `{ enabledModels, defaultModel,
  defaultPlanModel }`; `PUT` validates `defaultModel ∈ enabledModels`.
- Web Settings → Models gets a new "Default Models" section with two
  combobox pickers. Disabling a model that's the current default is
  blocked inline.
- Terraform: production workers gain `DEFAULT_MODEL` (control-plane,
  which didn't have one) and `DEFAULT_PLAN_MODEL` (all four). These
  remain fallbacks — the DB value wins when set.
- `docs/GETTING_STARTED.md` gets a "Configure Default Models" subsection.

Verification: `npm run typecheck`, `npm run lint`, `npm test`
(shared 183/183, control-plane 1162/1162, web 259/259) — all green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bleleve

docs/GETTING_STARTED.md

@@ -318,21 +318,8 @@ Save these values somewhere secure—you'll need them in the next step.
 ```bash
 cd terraform/environments/production
 
-# Copy the example files
+# Copy the example file and fill in values
 cp terraform.tfvars.example terraform.tfvars
-cp backend.tfvars.example backend.tfvars
-```
-
-### Configure `backend.tfvars`
-
-Fill in your R2 credentials:
-
-```hcl
-access_key = "your-r2-access-key-id"
-secret_key = "your-r2-secret-access-key"
-endpoints = {
-  s3 = "https://YOUR_CLOUDFLARE_ACCOUNT_ID.r2.cloudflarestorage.com"
-}
 ```
 
 ### Configure `terraform.tfvars`
@@ -454,8 +441,11 @@ Then run:
 ```bash
 cd terraform/environments/production
 
-# Initialize Terraform with backend config
-terraform init -backend-config=backend.tfvars
+# Initialize Terraform with R2 backend credentials
+terraform init \
+  -backend-config="access_key=YOUR_R2_ACCESS_KEY_ID" \
+  -backend-config="secret_key=YOUR_R2_SECRET_ACCESS_KEY" \
+  -backend-config='endpoints={s3="https://YOUR_CLOUDFLARE_ACCOUNT_ID.r2.cloudflarestorage.com"}'
 
 # Deploy (phase 1 - creates workers without bindings)
 terraform apply
@@ -645,13 +635,38 @@ curl -I https://open-inspect-web-{deployment_name}.YOUR-SUBDOMAIN.workers.dev
 3. Create a new session with a repository
 4. Send a prompt and verify the sandbox starts
 
+### Configure Default Models
+
+The web UI exposes a **Settings → Models → Default Models** section that controls which build and
+plan models the deployment uses by default. Bots (Linear, GitHub, Slack) read these values at
+session-creation time, so changes propagate without a Terraform redeploy.
+
+1. Open **Settings → Models** in the web UI.
+2. Under **Default Models**, pick:
+   - **Default model** — the build model used when no per-request override is in play.
+   - **Default plan model** — the model that runs the planning turn when plan mode is enabled.
+3. Save. The values are stored in D1; bots fall back to the worker's `DEFAULT_MODEL` /
+   `DEFAULT_PLAN_MODEL` env var only when the control plane is unreachable, then to a shared
+   constant.
+
+Disabling a model that is the current default is blocked inline — pick a new default first.
+
+See [PLAN_MODE.md](PLAN_MODE.md) for the full plan-mode workflow these defaults feed into.
+
 ---
 
 ## Step 10: Set Up CI/CD (Optional)
 
-Enable automatic deployments when you push to main by adding GitHub Secrets.
+Enable automatic deployments by configuring GitHub Environments and secrets:
+
+- **`main` branch** → deploys **staging** (`terraform/environments/staging`)
+- **`stable` branch** → deploys **production** (`terraform/environments/production`)
+
+Create `staging` and `production` environments under Settings → Environments. Add secrets to each
+environment (or use repository-level secrets shared by both). Pull requests to `main` run
+`terraform plan` against staging.
 
-Go to your fork's Settings → Secrets and variables → Actions, and add:
+Go to your fork's Settings → Secrets and variables → Actions (or per-environment secrets), and add:
 
 | Secret Name                   | Value                                                                         |
 | ----------------------------- | ----------------------------------------------------------------------------- |
@@ -719,8 +734,9 @@ gh secret set GH_APP_PRIVATE_KEY < private-key-pkcs8.pem
 
 Once configured, the GitHub Actions workflow will:
 
-- Run `terraform plan` on pull requests (with PR comment)
-- Run `terraform apply` when merged to main
+- Run `terraform plan` on pull requests to `main` (staging, with PR comment)
+- Run `terraform apply` on pushes to `main` (staging)
+- Run `terraform apply` on pushes to `stable` (production)
 
 ---
 
@@ -749,7 +765,10 @@ terraform apply
 Re-run init with backend config:
 
 ```bash
-terraform init -backend-config=backend.tfvars
+terraform init \
+  -backend-config="access_key=YOUR_R2_ACCESS_KEY_ID" \
+  -backend-config="secret_key=YOUR_R2_SECRET_ACCESS_KEY" \
+  -backend-config='endpoints={s3="https://YOUR_CLOUDFLARE_ACCOUNT_ID.r2.cloudflarestorage.com"}'
 ```
 
 ### GitHub App authentication fails

packages/control-plane/src/db/model-preferences.ts

@@ -7,28 +7,54 @@ export class ModelPreferencesValidationError extends Error {
   }
 }
 
+export interface ModelPreferences {
+  enabledModels: string[];
+  defaultModel: string | null;
+  defaultPlanModel: string | null;
+}
+
+interface ModelPreferencesRow {
+  enabled_models: string;
+  default_model: string | null;
+  default_plan_model: string | null;
+}
+
 export class ModelPreferencesStore {
   constructor(private readonly db: D1Database) {}
 
   /**
-   * Get the list of enabled model IDs, or null if no preferences stored.
+   * Get the full singleton preferences row, or null if no preferences stored.
    */
-  async getEnabledModels(): Promise<string[] | null> {
+  async getPreferences(): Promise<ModelPreferences | null> {
     const row = await this.db
-      .prepare("SELECT enabled_models FROM model_preferences WHERE id = 'global'")
-      .first<{ enabled_models: string }>();
+      .prepare(
+        "SELECT enabled_models, default_model, default_plan_model FROM model_preferences WHERE id = 'global'"
+      )
+      .first<ModelPreferencesRow>();
 
     if (!row) return null;
 
-    return JSON.parse(row.enabled_models) as string[];
+    return {
+      enabledModels: JSON.parse(row.enabled_models) as string[],
+      defaultModel: row.default_model,
+      defaultPlanModel: row.default_plan_model,
+    };
   }
 
   /**
-   * Set the list of enabled model IDs.
-   * Validates all IDs against VALID_MODELS.
+   * Back-compat shim. Prefer getPreferences() for new callers.
    */
-  async setEnabledModels(modelIds: string[]): Promise<void> {
-    const unique = [...new Set(modelIds)];
+  async getEnabledModels(): Promise<string[] | null> {
+    return (await this.getPreferences())?.enabledModels ?? null;
+  }
+
+  /**
+   * Atomically persist the three preference fields. defaultModel /
+   * defaultPlanModel may be null (= delegate to env/shared fallback). When
+   * non-null, they must be members of enabledModels.
+   */
+  async setPreferences(prefs: ModelPreferences): Promise<void> {
+    const unique = [...new Set(prefs.enabledModels)];
     const invalid = unique.filter((id) => !isValidModel(id));
     if (invalid.length > 0) {
       throw new ModelPreferencesValidationError(`Invalid model IDs: ${invalid.join(", ")}`);
@@ -38,16 +64,46 @@ export class ModelPreferencesStore {
       throw new ModelPreferencesValidationError("At least one model must be enabled");
     }
 
+    const enabledSet = new Set(unique);
+
+    if (prefs.defaultModel !== null) {
+      if (!isValidModel(prefs.defaultModel)) {
+        throw new ModelPreferencesValidationError(
+          `Invalid default model ID: ${prefs.defaultModel}`
+        );
+      }
+      if (!enabledSet.has(prefs.defaultModel)) {
+        throw new ModelPreferencesValidationError(
+          `Default model "${prefs.defaultModel}" is not in the enabled models list`
+        );
+      }
+    }
+
+    if (prefs.defaultPlanModel !== null) {
+      if (!isValidModel(prefs.defaultPlanModel)) {
+        throw new ModelPreferencesValidationError(
+          `Invalid default plan model ID: ${prefs.defaultPlanModel}`
+        );
+      }
+      if (!enabledSet.has(prefs.defaultPlanModel)) {
+        throw new ModelPreferencesValidationError(
+          `Default plan model "${prefs.defaultPlanModel}" is not in the enabled models list`
+        );
+      }
+    }
+
     const now = Date.now();
     await this.db
       .prepare(
-        `INSERT INTO model_preferences (id, enabled_models, updated_at)
-         VALUES ('global', ?, ?)
+        `INSERT INTO model_preferences (id, enabled_models, default_model, default_plan_model, updated_at)
+         VALUES ('global', ?, ?, ?, ?)
          ON CONFLICT(id) DO UPDATE SET
-           enabled_models = excluded.enabled_models,
-           updated_at = excluded.updated_at`
+           enabled_models     = excluded.enabled_models,
+           default_model      = excluded.default_model,
+           default_plan_model = excluded.default_plan_model,
+           updated_at         = excluded.updated_at`
       )
-      .bind(JSON.stringify(unique), now)
+      .bind(JSON.stringify(unique), prefs.defaultModel, prefs.defaultPlanModel, now)
       .run();
   }
 }