Merge remote-tracking branch 'origin/main' into feat/compute-workload-manager

Adds a "Create custom dashboard" button to the top right of the metrics
dashboard

 
<img width="3546" height="1934" alt="CleanShot 2026-02-19 at 11 25
12@2x"
src="https://github.com/user-attachments/assets/0bb46ade-47c9-4396-b62a-f4801d7d90b4"
/>

.changeset/fix-batch-queue-processing.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/redis-worker": patch
+---
+
+Fix slow batch queue processing by removing spurious cooloff on concurrency blocks and fixing a race condition where retry attempt counts were not atomically updated during message re-queue.

.changeset/fix-local-build-load.md

@@ -0,0 +1,5 @@
+---
+"trigger.dev": patch
+---
+
+Fix `--load` flag being silently ignored on local/self-hosted builds.

.changeset/input-stream-wait.md

@@ -0,0 +1,8 @@
+---
+"@trigger.dev/sdk": patch
+"@trigger.dev/react-hooks": patch
+---
+
+Add input streams for bidirectional communication with running tasks. Define typed input streams with `streams.input<T>({ id })`, then consume inside tasks via `.wait()` (suspends the process), `.once()` (waits for next message), or `.on()` (subscribes to a continuous stream). Send data from backends with `.send(runId, data)` or from frontends with the new `useInputStreamSend` React hook.
+
+Upgrade S2 SDK from 0.17 to 0.22 with support for custom endpoints (s2-lite) via the new `endpoints` configuration, `AppendRecord.string()` API, and `maxInflightBytes` session option.

.changeset/metal-steaks-try.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+fix(sdk): batch triggerAndWait variants now return correct run.taskIdentifier instead of unknown

.changeset/modern-boxes-watch.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Add PAYLOAD_TOO_LARGE error to handle graceful recovery of sending batch trigger items with payloads that exceed the maximum payload size

.claude/rules/database-safety.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "internal-packages/database/**"
+---
+
+# Database Migration Safety
+
+- When adding indexes to **existing tables**, use `CREATE INDEX CONCURRENTLY IF NOT EXISTS` to avoid table locks. These must be in their own separate migration file (one index per file).
+- Indexes on **newly created tables** (same migration as `CREATE TABLE`) do not need CONCURRENTLY.
+- When indexing a **new column on an existing table**, split into two migrations: first `ADD COLUMN IF NOT EXISTS`, then `CREATE INDEX CONCURRENTLY IF NOT EXISTS` in a separate file.
+- After generating a migration with Prisma, remove extraneous lines for: `_BackgroundWorkerToBackgroundWorkerFile`, `_BackgroundWorkerToTaskQueue`, `_TaskRunToTaskRunTag`, `_WaitpointRunConnections`, `_completedWaitpoints`, `SecretStore_key_idx`, and unrelated TaskRun indexes.
+- Never drop columns or tables without explicit approval.
+- New code should target `RunEngineVersion.V2` only.

.claude/rules/docs-writing.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - "docs/**"
+---
+
+# Documentation Writing Rules
+
+- Use Mintlify MDX format. Frontmatter: `title`, `description`, `sidebarTitle` (optional).
+- After creating a new page, add it to `docs.json` navigation under the correct group.
+- Use Mintlify components: `<Note>`, `<Warning>`, `<Info>`, `<Tip>`, `<CodeGroup>`, `<Expandable>`, `<Steps>`/`<Step>`.
+- Code examples should be complete and runnable where possible.
+- Always import from `@trigger.dev/sdk`, never `@trigger.dev/sdk/v3`.
+- Keep paragraphs short. Use headers to break up content.
+- Link to related pages using relative paths (e.g., `[Tasks](/tasks/overview)`).

.claude/rules/legacy-v3-code.md

@@ -0,0 +1,33 @@
+---
+paths:
+  - "apps/webapp/app/v3/**"
+---
+
+# Legacy V1 Engine Code in `app/v3/`
+
+The `v3/` directory name is misleading - most code here is actively used by the current V2 engine. Only the specific files below are legacy V1-only code.
+
+## V1-Only Files - Never Modify
+
+- `marqs/` directory (entire MarQS queue system: sharedQueueConsumer, devQueueConsumer, fairDequeuingStrategy, devPubSub)
+- `legacyRunEngineWorker.server.ts` (V1 background job worker)
+- `services/triggerTaskV1.server.ts` (deprecated V1 task triggering)
+- `services/cancelTaskRunV1.server.ts` (deprecated V1 cancellation)
+- `authenticatedSocketConnection.server.ts` (V1 dev WebSocket using DevQueueConsumer)
+- `sharedSocketConnection.ts` (V1 shared queue socket using SharedQueueConsumer)
+
+## V1/V2 Branching Pattern
+
+Some services act as routers that branch on `RunEngineVersion`:
+- `services/cancelTaskRun.server.ts` - calls V1 service or `engine.cancelRun()` for V2
+- `services/batchTriggerV3.server.ts` - uses marqs for V1 path, run-engine for V2
+
+When editing these shared services, only modify V2 code paths.
+
+## V2 Modern Stack
+
+- **Run lifecycle**: `@internal/run-engine` (internal-packages/run-engine)
+- **Background jobs**: `@trigger.dev/redis-worker` (not graphile-worker/zodworker)
+- **Queue operations**: RunQueue inside run-engine (not MarQS)
+- **V2 engine singleton**: `runEngine.server.ts`, `runEngineHandlers.server.ts`
+- **V2 workers**: `commonWorker.server.ts`, `alertsWorker.server.ts`, `batchTriggerWorker.server.ts`

.claude/rules/sdk-packages.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - "packages/**"
+---
+
+# Public Package Rules
+
+- Changes to `packages/` are **customer-facing**. Always add a changeset: `pnpm run changeset:add`
+- Default to **patch**. Get maintainer approval for minor. Never select major without explicit approval.
+- `@trigger.dev/core`: **Never import the root**. Always use subpath imports (e.g., `@trigger.dev/core/v3`).
+- Do NOT update `rules/` or `.claude/skills/trigger-dev-tasks/` unless explicitly asked. These are maintained in separate dedicated passes.
+- Test changes using `references/hello-world` reference project.

.claude/rules/server-apps.md

@@ -0,0 +1,23 @@
+---
+paths:
+  - "apps/**"
+---
+
+# Server App Changes
+
+When modifying server apps (webapp, supervisor, coordinator, etc.) with **no package changes**, add a `.server-changes/` file instead of a changeset:
+
+```bash
+cat > .server-changes/descriptive-name.md << 'EOF'
+---
+area: webapp
+type: fix
+---
+
+Brief description of what changed and why.
+EOF
+```
+
+- **area**: `webapp` | `supervisor` | `coordinator` | `kubernetes-provider` | `docker-provider`
+- **type**: `feature` | `fix` | `improvement` | `breaking`
+- If the PR also touches `packages/`, just the changeset is sufficient (no `.server-changes/` needed).

.claude/skills/trigger-dev-tasks/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: trigger-dev-tasks
+description: Use this skill when writing, designing, or optimizing Trigger.dev background tasks and workflows. This includes creating reliable async tasks, implementing AI workflows, setting up scheduled jobs, structuring complex task hierarchies with subtasks, configuring build extensions for tools like ffmpeg or Puppeteer/Playwright, and handling task schemas with Zod validation.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Trigger.dev Task Expert
+
+You are an expert Trigger.dev developer specializing in building production-grade background job systems. Tasks deployed to Trigger.dev run in Node.js 21+ and use the `@trigger.dev/sdk` package.
+
+## Critical Rules
+
+1. **Always use `@trigger.dev/sdk`** - Never use `@trigger.dev/sdk/v3` or deprecated `client.defineJob` pattern
+2. **Never use `node-fetch`** - Use the built-in `fetch` function
+3. **Export all tasks** - Every task must be exported, including subtasks
+4. **Never wrap wait/trigger calls in Promise.all** - `triggerAndWait`, `batchTriggerAndWait`, and `wait.*` calls cannot be wrapped in `Promise.all` or `Promise.allSettled`
+
+## Basic Task Pattern
+
+```ts
+import { task } from "@trigger.dev/sdk";
+
+export const processData = task({
+  id: "process-data",
+  retry: {
+    maxAttempts: 10,
+    factor: 1.8,
+    minTimeoutInMs: 500,
+    maxTimeoutInMs: 30_000,
+  },
+  run: async (payload: { userId: string; data: any[] }) => {
+    console.log(`Processing ${payload.data.length} items`);
+    return { processed: payload.data.length };
+  },
+});
+```
+
+## Schema Task (with validation)
+
+```ts
+import { schemaTask } from "@trigger.dev/sdk";
+import { z } from "zod";
+
+export const validatedTask = schemaTask({
+  id: "validated-task",
+  schema: z.object({
+    name: z.string(),
+    email: z.string().email(),
+  }),
+  run: async (payload) => {
+    // Payload is automatically validated and typed
+    return { message: `Hello ${payload.name}` };
+  },
+});
+```
+
+## Triggering Tasks
+
+### From Backend Code (type-only import to prevent dependency leakage)
+
+```ts
+import { tasks } from "@trigger.dev/sdk";
+import type { processData } from "./trigger/tasks";
+
+const handle = await tasks.trigger<typeof processData>("process-data", {
+  userId: "123",
+  data: [{ id: 1 }],
+});
+```
+
+### From Inside Tasks
+
+```ts
+export const parentTask = task({
+  id: "parent-task",
+  run: async (payload) => {
+    // Trigger and wait - returns Result object, NOT direct output
+    const result = await childTask.triggerAndWait({ data: "value" });
+    if (result.ok) {
+      console.log("Output:", result.output);
+    } else {
+      console.error("Failed:", result.error);
+    }
+
+    // Or unwrap directly (throws on error)
+    const output = await childTask.triggerAndWait({ data: "value" }).unwrap();
+  },
+});
+```
+
+## Idempotency (Critical for Retries)
+
+Always use idempotency keys when triggering tasks from inside other tasks:
+
+```ts
+import { idempotencyKeys } from "@trigger.dev/sdk";
+
+export const paymentTask = task({
+  id: "process-payment",
+  run: async (payload: { orderId: string }) => {
+    // Scoped to current run - survives retries
+    const key = await idempotencyKeys.create(`payment-${payload.orderId}`);
+
+    await chargeCustomer.trigger(payload, {
+      idempotencyKey: key,
+      idempotencyKeyTTL: "24h",
+    });
+  },
+});
+```
+
+## Trigger Options
+
+```ts
+await myTask.trigger(payload, {
+  delay: "1h",           // Delay execution
+  ttl: "10m",            // Cancel if not started within TTL
+  idempotencyKey: key,
+  queue: "my-queue",
+  machine: "large-1x",   // micro, small-1x, small-2x, medium-1x, medium-2x, large-1x, large-2x
+  maxAttempts: 3,
+  tags: ["user_123"],    // Max 10 tags
+  debounce: {            // Consolidate rapid triggers
+    key: "unique-key",
+    delay: "5s",
+    mode: "trailing",    // "leading" (default) or "trailing"
+  },
+});
+```
+
+## Debouncing
+
+Consolidate multiple triggers into a single execution:
+
+```ts
+// Rapid triggers with same key = single execution
+await myTask.trigger({ userId: "123" }, {
+  debounce: {
+    key: "user-123-update",
+    delay: "5s",
+  },
+});
+
+// Trailing mode: use payload from LAST trigger
+await myTask.trigger({ data: "latest" }, {
+  debounce: {
+    key: "my-key",
+    delay: "10s",
+    mode: "trailing",
+  },
+});
+```
+
+Use cases: user activity updates, webhook deduplication, search indexing, notification batching.
+
+## Batch Triggering
+
+Up to 1,000 items per batch, 3MB per payload:
+
+```ts
+const results = await myTask.batchTriggerAndWait([
+  { payload: { userId: "1" } },
+  { payload: { userId: "2" } },
+]);
+
+for (const result of results) {
+  if (result.ok) console.log(result.output);
+}
+```
+
+## Machine Presets
+
+| Preset      | vCPU | Memory |
+|-------------|------|--------|
+| micro       | 0.25 | 0.25GB |
+| small-1x    | 0.5  | 0.5GB  |
+| small-2x    | 1    | 1GB    |
+| medium-1x   | 1    | 2GB    |
+| medium-2x   | 2    | 4GB    |
+| large-1x    | 4    | 8GB    |
+| large-2x    | 8    | 16GB   |
+
+## Design Principles
+
+1. **Break complex workflows into subtasks** that can be independently retried and made idempotent
+2. **Don't over-complicate** - Sometimes `Promise.allSettled` inside a single task is better than many subtasks (each task has dedicated process and is charged by millisecond)
+3. **Always configure retries** - Set appropriate `maxAttempts` based on the operation
+4. **Use idempotency keys** - Especially for payment/critical operations
+5. **Group related subtasks** - Keep subtasks only used by one parent in the same file, don't export them
+6. **Use logger** - Log at key execution points with `logger.info()`, `logger.error()`, etc.
+
+## Reference Documentation
+
+For detailed documentation on specific topics, read these files:
+
+- `basic-tasks.md` - Task basics, triggering, waits
+- `advanced-tasks.md` - Tags, queues, concurrency, metadata, error handling
+- `scheduled-tasks.md` - Cron schedules, declarative and imperative
+- `realtime.md` - Real-time subscriptions, streams, React hooks
+- `config.md` - trigger.config.ts, build extensions (Prisma, Playwright, FFmpeg, etc.)

.claude/skills/trigger-dev-tasks/advanced-tasks.md

@@ -0,0 +1,485 @@
+# Trigger.dev Advanced Tasks (v4)
+
+**Advanced patterns and features for writing tasks**
+
+## Tags & Organization
+
+```ts
+import { task, tags } from "@trigger.dev/sdk";
+
+export const processUser = task({
+  id: "process-user",
+  run: async (payload: { userId: string; orgId: string }, { ctx }) => {
+    // Add tags during execution
+    await tags.add(`user_${payload.userId}`);
+    await tags.add(`org_${payload.orgId}`);
+
+    return { processed: true };
+  },
+});
+
+// Trigger with tags
+await processUser.trigger(
+  { userId: "123", orgId: "abc" },
+  { tags: ["priority", "user_123", "org_abc"] } // Max 10 tags per run
+);
+
+// Subscribe to tagged runs
+for await (const run of runs.subscribeToRunsWithTag("user_123")) {
+  console.log(`User task ${run.id}: ${run.status}`);
+}
+```
+
+**Tag Best Practices:**
+
+- Use prefixes: `user_123`, `org_abc`, `video:456`
+- Max 10 tags per run, 1-64 characters each
+- Tags don't propagate to child tasks automatically
+
+## Batch Triggering v2
+
+Enhanced batch triggering with larger payloads and streaming ingestion.
+
+### Limits
+
+- **Maximum batch size**: 1,000 items (increased from 500)
+- **Payload per item**: 3MB each (increased from 1MB combined)
+- Payloads > 512KB automatically offload to object storage
+
+### Rate Limiting (per environment)
+
+| Tier | Bucket Size | Refill Rate |
+|------|-------------|-------------|
+| Free | 1,200 runs | 100 runs/10 sec |
+| Hobby | 5,000 runs | 500 runs/5 sec |
+| Pro | 5,000 runs | 500 runs/5 sec |
+
+### Concurrent Batch Processing
+
+| Tier | Concurrent Batches |
+|------|-------------------|
+| Free | 1 |
+| Hobby | 10 |
+| Pro | 10 |
+
+### Usage
+
+```ts
+import { myTask } from "./trigger/myTask";
+
+// Basic batch trigger (up to 1,000 items)
+const runs = await myTask.batchTrigger([
+  { payload: { userId: "user-1" } },
+  { payload: { userId: "user-2" } },
+  { payload: { userId: "user-3" } },
+]);
+
+// Batch trigger with wait
+const results = await myTask.batchTriggerAndWait([
+  { payload: { userId: "user-1" } },
+  { payload: { userId: "user-2" } },
+]);
+
+for (const result of results) {
+  if (result.ok) {
+    console.log("Result:", result.output);
+  }
+}
+
+// With per-item options
+const batchHandle = await myTask.batchTrigger([
+  {
+    payload: { userId: "123" },
+    options: {
+      idempotencyKey: "user-123-batch",
+      tags: ["priority"],
+    },
+  },
+  {
+    payload: { userId: "456" },
+    options: {
+      idempotencyKey: "user-456-batch",
+    },
+  },
+]);
+```
+
+## Debouncing
+
+Consolidate multiple triggers into a single execution by debouncing task runs with a unique key and delay window.
+
+### Use Cases
+
+- **User activity updates**: Batch rapid user actions into a single run
+- **Webhook deduplication**: Handle webhook bursts without redundant processing
+- **Search indexing**: Combine document updates instead of processing individually
+- **Notification batching**: Group notifications to prevent user spam
+
+### Basic Usage
+
+```ts
+await myTask.trigger(
+  { userId: "123" },
+  {
+    debounce: {
+      key: "user-123-update",  // Unique identifier for debounce group
+      delay: "5s",              // Wait duration ("5s", "1m", or milliseconds)
+    },
+  }
+);
+```
+
+### Execution Modes
+
+**Leading Mode** (default): Uses payload/options from the first trigger; subsequent triggers only reschedule execution time.
+
+```ts
+// First trigger sets the payload
+await myTask.trigger({ action: "first" }, {
+  debounce: { key: "my-key", delay: "10s" }
+});
+
+// Second trigger only reschedules - payload remains "first"
+await myTask.trigger({ action: "second" }, {
+  debounce: { key: "my-key", delay: "10s" }
+});
+// Task executes with { action: "first" }
+```
+
+**Trailing Mode**: Uses payload/options from the most recent trigger.
+
+```ts
+await myTask.trigger(
+  { data: "latest-value" },
+  {
+    debounce: {
+      key: "trailing-example",
+      delay: "10s",
+      mode: "trailing",
+    },
+  }
+);
+```
+
+In trailing mode, these options update with each trigger:
+- `payload` — task input data
+- `metadata` — run metadata
+- `tags` — run tags (replaces existing)
+- `maxAttempts` — retry attempts
+- `maxDuration` — maximum compute time
+- `machine` — machine preset
+
+### Important Notes
+
+- Idempotency keys take precedence over debounce settings
+- Compatible with `triggerAndWait()` — parent runs block correctly on debounced execution
+- Debounce key is scoped to the task
+
+## Concurrency & Queues
+
+```ts
+import { task, queue } from "@trigger.dev/sdk";
+
+// Shared queue for related tasks
+const emailQueue = queue({
+  name: "email-processing",
+  concurrencyLimit: 5, // Max 5 emails processing simultaneously
+});
+
+// Task-level concurrency
+export const oneAtATime = task({
+  id: "sequential-task",
+  queue: { concurrencyLimit: 1 }, // Process one at a time
+  run: async (payload) => {
+    // Critical section - only one instance runs
+  },
+});
+
+// Per-user concurrency
+export const processUserData = task({
+  id: "process-user-data",
+  run: async (payload: { userId: string }) => {
+    // Override queue with user-specific concurrency
+    await childTask.trigger(payload, {
+      queue: {
+        name: `user-${payload.userId}`,
+        concurrencyLimit: 2,
+      },
+    });
+  },
+});
+
+export const emailTask = task({
+  id: "send-email",
+  queue: emailQueue, // Use shared queue
+  run: async (payload: { to: string }) => {
+    // Send email logic
+  },
+});
+```
+
+## Error Handling & Retries
+
+```ts
+import { task, retry, AbortTaskRunError } from "@trigger.dev/sdk";
+
+export const resilientTask = task({
+  id: "resilient-task",
+  retry: {
+    maxAttempts: 10,
+    factor: 1.8, // Exponential backoff multiplier
+    minTimeoutInMs: 500,
+    maxTimeoutInMs: 30_000,
+    randomize: false,
+  },
+  catchError: async ({ error, ctx }) => {
+    // Custom error handling
+    if (error.code === "FATAL_ERROR") {
+      throw new AbortTaskRunError("Cannot retry this error");
+    }
+
+    // Log error details
+    console.error(`Task ${ctx.task.id} failed:`, error);
+
+    // Allow retry by returning nothing
+    return { retryAt: new Date(Date.now() + 60000) }; // Retry in 1 minute
+  },
+  run: async (payload) => {
+    // Retry specific operations
+    const result = await retry.onThrow(
+      async () => {
+        return await unstableApiCall(payload);
+      },
+      { maxAttempts: 3 }
+    );
+
+    // Conditional HTTP retries
+    const response = await retry.fetch("https://api.example.com", {
+      retry: {
+        maxAttempts: 5,
+        condition: (response, error) => {
+          return response?.status === 429 || response?.status >= 500;
+        },
+      },
+    });
+
+    return result;
+  },
+});
+```
+
+## Machines & Performance
+
+```ts
+export const heavyTask = task({
+  id: "heavy-computation",
+  machine: { preset: "large-2x" }, // 8 vCPU, 16 GB RAM
+  maxDuration: 1800, // 30 minutes timeout
+  run: async (payload, { ctx }) => {
+    // Resource-intensive computation
+    if (ctx.machine.preset === "large-2x") {
+      // Use all available cores
+      return await parallelProcessing(payload);
+    }
+
+    return await standardProcessing(payload);
+  },
+});
+
+// Override machine when triggering
+await heavyTask.trigger(payload, {
+  machine: { preset: "medium-1x" }, // Override for this run
+});
+```
+
+**Machine Presets:**
+
+- `micro`: 0.25 vCPU, 0.25 GB RAM
+- `small-1x`: 0.5 vCPU, 0.5 GB RAM (default)
+- `small-2x`: 1 vCPU, 1 GB RAM
+- `medium-1x`: 1 vCPU, 2 GB RAM
+- `medium-2x`: 2 vCPU, 4 GB RAM
+- `large-1x`: 4 vCPU, 8 GB RAM
+- `large-2x`: 8 vCPU, 16 GB RAM
+
+## Idempotency
+
+```ts
+import { task, idempotencyKeys } from "@trigger.dev/sdk";
+
+export const paymentTask = task({
+  id: "process-payment",
+  retry: {
+    maxAttempts: 3,
+  },
+  run: async (payload: { orderId: string; amount: number }) => {
+    // Automatically scoped to this task run, so if the task is retried, the idempotency key will be the same
+    const idempotencyKey = await idempotencyKeys.create(`payment-${payload.orderId}`);
+
+    // Ensure payment is processed only once
+    await chargeCustomer.trigger(payload, {
+      idempotencyKey,
+      idempotencyKeyTTL: "24h", // Key expires in 24 hours
+    });
+  },
+});
+
+// Payload-based idempotency
+import { createHash } from "node:crypto";
+
+function createPayloadHash(payload: any): string {
+  const hash = createHash("sha256");
+  hash.update(JSON.stringify(payload));
+  return hash.digest("hex");
+}
+
+export const deduplicatedTask = task({
+  id: "deduplicated-task",
+  run: async (payload) => {
+    const payloadHash = createPayloadHash(payload);
+    const idempotencyKey = await idempotencyKeys.create(payloadHash);
+
+    await processData.trigger(payload, { idempotencyKey });
+  },
+});
+```
+
+## Metadata & Progress Tracking
+
+```ts
+import { task, metadata } from "@trigger.dev/sdk";
+
+export const batchProcessor = task({
+  id: "batch-processor",
+  run: async (payload: { items: any[] }, { ctx }) => {
+    const totalItems = payload.items.length;
+
+    // Initialize progress metadata
+    metadata
+      .set("progress", 0)
+      .set("totalItems", totalItems)
+      .set("processedItems", 0)
+      .set("status", "starting");
+
+    const results = [];
+
+    for (let i = 0; i < payload.items.length; i++) {
+      const item = payload.items[i];
+
+      // Process item
+      const result = await processItem(item);
+      results.push(result);
+
+      // Update progress
+      const progress = ((i + 1) / totalItems) * 100;
+      metadata
+        .set("progress", progress)
+        .increment("processedItems", 1)
+        .append("logs", `Processed item ${i + 1}/${totalItems}`)
+        .set("currentItem", item.id);
+    }
+
+    // Final status
+    metadata.set("status", "completed");
+
+    return { results, totalProcessed: results.length };
+  },
+});
+
+// Update parent metadata from child task
+export const childTask = task({
+  id: "child-task",
+  run: async (payload, { ctx }) => {
+    // Update parent task metadata
+    metadata.parent.set("childStatus", "processing");
+    metadata.root.increment("childrenCompleted", 1);
+
+    return { processed: true };
+  },
+});
+```
+
+## Logging & Tracing
+
+```ts
+import { task, logger } from "@trigger.dev/sdk";
+
+export const tracedTask = task({
+  id: "traced-task",
+  run: async (payload, { ctx }) => {
+    logger.info("Task started", { userId: payload.userId });
+
+    // Custom trace with attributes
+    const user = await logger.trace(
+      "fetch-user",
+      async (span) => {
+        span.setAttribute("user.id", payload.userId);
+        span.setAttribute("operation", "database-fetch");
+
+        const userData = await database.findUser(payload.userId);
+        span.setAttribute("user.found", !!userData);
+
+        return userData;
+      },
+      { userId: payload.userId }
+    );
+
+    logger.debug("User fetched", { user: user.id });
+
+    try {
+      const result = await processUser(user);
+      logger.info("Processing completed", { result });
+      return result;
+    } catch (error) {
+      logger.error("Processing failed", {
+        error: error.message,
+        userId: payload.userId,
+      });
+      throw error;
+    }
+  },
+});
+```
+
+## Hidden Tasks
+
+```ts
+// Hidden task - not exported, only used internally
+const internalProcessor = task({
+  id: "internal-processor",
+  run: async (payload: { data: string }) => {
+    return { processed: payload.data.toUpperCase() };
+  },
+});
+
+// Public task that uses hidden task
+export const publicWorkflow = task({
+  id: "public-workflow",
+  run: async (payload: { input: string }) => {
+    // Use hidden task internally
+    const result = await internalProcessor.triggerAndWait({
+      data: payload.input,
+    });
+
+    if (result.ok) {
+      return { output: result.output.processed };
+    }
+
+    throw new Error("Internal processing failed");
+  },
+});
+```
+
+## Best Practices
+
+- **Concurrency**: Use queues to prevent overwhelming external services
+- **Retries**: Configure exponential backoff for transient failures
+- **Idempotency**: Always use for payment/critical operations
+- **Metadata**: Track progress for long-running tasks
+- **Machines**: Match machine size to computational requirements
+- **Tags**: Use consistent naming patterns for filtering
+- **Debouncing**: Use for user activity, webhooks, and notification batching
+- **Batch triggering**: Use for bulk operations up to 1,000 items
+- **Error Handling**: Distinguish between retryable and fatal errors
+
+Design tasks to be stateless, idempotent, and resilient to failures. Use metadata for state tracking and queues for resource management.

.claude/skills/trigger-dev-tasks/basic-tasks.md

@@ -0,0 +1,199 @@
+# Trigger.dev Basic Tasks (v4)
+
+**MUST use `@trigger.dev/sdk`, NEVER `client.defineJob`**
+
+## Basic Task
+
+```ts
+import { task } from "@trigger.dev/sdk";
+
+export const processData = task({
+  id: "process-data",
+  retry: {
+    maxAttempts: 10,
+    factor: 1.8,
+    minTimeoutInMs: 500,
+    maxTimeoutInMs: 30_000,
+    randomize: false,
+  },
+  run: async (payload: { userId: string; data: any[] }) => {
+    // Task logic - runs for long time, no timeouts
+    console.log(`Processing ${payload.data.length} items for user ${payload.userId}`);
+    return { processed: payload.data.length };
+  },
+});
+```
+
+## Schema Task (with validation)
+
+```ts
+import { schemaTask } from "@trigger.dev/sdk";
+import { z } from "zod";
+
+export const validatedTask = schemaTask({
+  id: "validated-task",
+  schema: z.object({
+    name: z.string(),
+    age: z.number(),
+    email: z.string().email(),
+  }),
+  run: async (payload) => {
+    // Payload is automatically validated and typed
+    return { message: `Hello ${payload.name}, age ${payload.age}` };
+  },
+});
+```
+
+## Triggering Tasks
+
+### From Backend Code
+
+```ts
+import { tasks } from "@trigger.dev/sdk";
+import type { processData } from "./trigger/tasks";
+
+// Single trigger
+const handle = await tasks.trigger<typeof processData>("process-data", {
+  userId: "123",
+  data: [{ id: 1 }, { id: 2 }],
+});
+
+// Batch trigger (up to 1,000 items, 3MB per payload)
+const batchHandle = await tasks.batchTrigger<typeof processData>("process-data", [
+  { payload: { userId: "123", data: [{ id: 1 }] } },
+  { payload: { userId: "456", data: [{ id: 2 }] } },
+]);
+```
+
+### Debounced Triggering
+
+Consolidate multiple triggers into a single execution:
+
+```ts
+// Multiple rapid triggers with same key = single execution
+await myTask.trigger(
+  { userId: "123" },
+  {
+    debounce: {
+      key: "user-123-update",  // Unique key for debounce group
+      delay: "5s",              // Wait before executing
+    },
+  }
+);
+
+// Trailing mode: use payload from LAST trigger
+await myTask.trigger(
+  { data: "latest-value" },
+  {
+    debounce: {
+      key: "trailing-example",
+      delay: "10s",
+      mode: "trailing",  // Default is "leading" (first payload)
+    },
+  }
+);
+```
+
+**Debounce modes:**
+- `leading` (default): Uses payload from first trigger, subsequent triggers only reschedule
+- `trailing`: Uses payload from most recent trigger
+
+### From Inside Tasks (with Result handling)
+
+```ts
+export const parentTask = task({
+  id: "parent-task",
+  run: async (payload) => {
+    // Trigger and continue
+    const handle = await childTask.trigger({ data: "value" });
+
+    // Trigger and wait - returns Result object, NOT task output
+    const result = await childTask.triggerAndWait({ data: "value" });
+    if (result.ok) {
+      console.log("Task output:", result.output); // Actual task return value
+    } else {
+      console.error("Task failed:", result.error);
+    }
+
+    // Quick unwrap (throws on error)
+    const output = await childTask.triggerAndWait({ data: "value" }).unwrap();
+
+    // Batch trigger and wait
+    const results = await childTask.batchTriggerAndWait([
+      { payload: { data: "item1" } },
+      { payload: { data: "item2" } },
+    ]);
+
+    for (const run of results) {
+      if (run.ok) {
+        console.log("Success:", run.output);
+      } else {
+        console.log("Failed:", run.error);
+      }
+    }
+  },
+});
+
+export const childTask = task({
+  id: "child-task",
+  run: async (payload: { data: string }) => {
+    return { processed: payload.data };
+  },
+});
+```
+
+> Never wrap triggerAndWait or batchTriggerAndWait calls in a Promise.all or Promise.allSettled as this is not supported in Trigger.dev tasks.
+
+## Waits
+
+```ts
+import { task, wait } from "@trigger.dev/sdk";
+
+export const taskWithWaits = task({
+  id: "task-with-waits",
+  run: async (payload) => {
+    console.log("Starting task");
+
+    // Wait for specific duration
+    await wait.for({ seconds: 30 });
+    await wait.for({ minutes: 5 });
+    await wait.for({ hours: 1 });
+    await wait.for({ days: 1 });
+
+    // Wait until specific date
+    await wait.until({ date: new Date("2024-12-25") });
+
+    // Wait for token (from external system)
+    await wait.forToken({
+      token: "user-approval-token",
+      timeoutInSeconds: 3600, // 1 hour timeout
+    });
+
+    console.log("All waits completed");
+    return { status: "completed" };
+  },
+});
+```
+
+> Never wrap wait calls in a Promise.all or Promise.allSettled as this is not supported in Trigger.dev tasks.
+
+## Key Points
+
+- **Result vs Output**: `triggerAndWait()` returns a `Result` object with `ok`, `output`, `error` properties - NOT the direct task output
+- **Type safety**: Use `import type` for task references when triggering from backend
+- **Waits > 5 seconds**: Automatically checkpointed, don't count toward compute usage
+- **Debounce + idempotency**: Idempotency keys take precedence over debounce settings
+
+## NEVER Use (v2 deprecated)
+
+```ts
+// BREAKS APPLICATION
+client.defineJob({
+  id: "job-id",
+  run: async (payload, io) => {
+    /* ... */
+  },
+});
+```
+
+Use SDK (`@trigger.dev/sdk`), check `result.ok` before accessing `result.output`

.claude/skills/trigger-dev-tasks/config.md

@@ -0,0 +1,346 @@
+# Trigger.dev Configuration
+
+**Complete guide to configuring `trigger.config.ts` with build extensions**
+
+## Basic Configuration
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+
+export default defineConfig({
+  project: "<project-ref>", // Required: Your project reference
+  dirs: ["./trigger"], // Task directories
+  runtime: "node", // "node", "node-22", or "bun"
+  logLevel: "info", // "debug", "info", "warn", "error"
+
+  // Default retry settings
+  retries: {
+    enabledInDev: false,
+    default: {
+      maxAttempts: 3,
+      minTimeoutInMs: 1000,
+      maxTimeoutInMs: 10000,
+      factor: 2,
+      randomize: true,
+    },
+  },
+
+  // Build configuration
+  build: {
+    autoDetectExternal: true,
+    keepNames: true,
+    minify: false,
+    extensions: [], // Build extensions go here
+  },
+
+  // Global lifecycle hooks
+  onStartAttempt: async ({ payload, ctx }) => {
+    console.log("Global task start");
+  },
+  onSuccess: async ({ payload, output, ctx }) => {
+    console.log("Global task success");
+  },
+  onFailure: async ({ payload, error, ctx }) => {
+    console.log("Global task failure");
+  },
+});
+```
+
+## Build Extensions
+
+### Database & ORM
+
+#### Prisma
+
+```ts
+import { prismaExtension } from "@trigger.dev/build/extensions/prisma";
+
+extensions: [
+  prismaExtension({
+    schema: "prisma/schema.prisma",
+    version: "5.19.0", // Optional: specify version
+    migrate: true, // Run migrations during build
+    directUrlEnvVarName: "DIRECT_DATABASE_URL",
+    typedSql: true, // Enable TypedSQL support
+  }),
+];
+```
+
+#### TypeScript Decorators (for TypeORM)
+
+```ts
+import { emitDecoratorMetadata } from "@trigger.dev/build/extensions/typescript";
+
+extensions: [
+  emitDecoratorMetadata(), // Enables decorator metadata
+];
+```
+
+### Scripting Languages
+
+#### Python
+
+```ts
+import { pythonExtension } from "@trigger.dev/build/extensions/python";
+
+extensions: [
+  pythonExtension({
+    scripts: ["./python/**/*.py"], // Copy Python files
+    requirementsFile: "./requirements.txt", // Install packages
+    devPythonBinaryPath: ".venv/bin/python", // Dev mode binary
+  }),
+];
+
+// Usage in tasks
+const result = await python.runInline(`print("Hello, world!")`);
+const output = await python.runScript("./python/script.py", ["arg1"]);
+```
+
+### Browser Automation
+
+#### Playwright
+
+```ts
+import { playwright } from "@trigger.dev/build/extensions/playwright";
+
+extensions: [
+  playwright({
+    browsers: ["chromium", "firefox", "webkit"], // Default: ["chromium"]
+    headless: true, // Default: true
+  }),
+];
+```
+
+#### Puppeteer
+
+```ts
+import { puppeteer } from "@trigger.dev/build/extensions/puppeteer";
+
+extensions: [puppeteer()];
+
+// Environment variable needed:
+// PUPPETEER_EXECUTABLE_PATH: "/usr/bin/google-chrome-stable"
+```
+
+#### Lightpanda
+
+```ts
+import { lightpanda } from "@trigger.dev/build/extensions/lightpanda";
+
+extensions: [
+  lightpanda({
+    version: "latest", // or "nightly"
+    disableTelemetry: false,
+  }),
+];
+```
+
+### Media Processing
+
+#### FFmpeg
+
+```ts
+import { ffmpeg } from "@trigger.dev/build/extensions/core";
+
+extensions: [
+  ffmpeg({ version: "7" }), // Static build, or omit for Debian version
+];
+
+// Automatically sets FFMPEG_PATH and FFPROBE_PATH
+// Add fluent-ffmpeg to external packages if using
+```
+
+#### Audio Waveform
+
+```ts
+import { audioWaveform } from "@trigger.dev/build/extensions/audioWaveform";
+
+extensions: [
+  audioWaveform(), // Installs Audio Waveform 1.1.0
+];
+```
+
+### System & Package Management
+
+#### System Packages (apt-get)
+
+```ts
+import { aptGet } from "@trigger.dev/build/extensions/core";
+
+extensions: [
+  aptGet({
+    packages: ["ffmpeg", "imagemagick", "curl=7.68.0-1"], // Can specify versions
+  }),
+];
+```
+
+#### Additional NPM Packages
+
+Only use this for installing CLI tools, NOT packages you import in your code.
+
+```ts
+import { additionalPackages } from "@trigger.dev/build/extensions/core";
+
+extensions: [
+  additionalPackages({
+    packages: ["wrangler"], // CLI tools and specific versions
+  }),
+];
+```
+
+#### Additional Files
+
+```ts
+import { additionalFiles } from "@trigger.dev/build/extensions/core";
+
+extensions: [
+  additionalFiles({
+    files: ["wrangler.toml", "./assets/**", "./fonts/**"], // Glob patterns supported
+  }),
+];
+```
+
+### Environment & Build Tools
+
+#### Environment Variable Sync
+
+```ts
+import { syncEnvVars } from "@trigger.dev/build/extensions/core";
+
+extensions: [
+  syncEnvVars(async (ctx) => {
+    // ctx contains: environment, projectRef, env
+    return [
+      { name: "SECRET_KEY", value: await getSecret(ctx.environment) },
+      { name: "API_URL", value: ctx.environment === "prod" ? "api.prod.com" : "api.dev.com" },
+    ];
+  }),
+];
+```
+
+#### ESBuild Plugins
+
+```ts
+import { esbuildPlugin } from "@trigger.dev/build/extensions";
+import { sentryEsbuildPlugin } from "@sentry/esbuild-plugin";
+
+extensions: [
+  esbuildPlugin(
+    sentryEsbuildPlugin({
+      org: process.env.SENTRY_ORG,
+      project: process.env.SENTRY_PROJECT,
+      authToken: process.env.SENTRY_AUTH_TOKEN,
+    }),
+    { placement: "last", target: "deploy" } // Optional config
+  ),
+];
+```
+
+## Custom Build Extensions
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+
+const customExtension = {
+  name: "my-custom-extension",
+
+  externalsForTarget: (target) => {
+    return ["some-native-module"]; // Add external dependencies
+  },
+
+  onBuildStart: async (context) => {
+    console.log(`Build starting for ${context.target}`);
+    // Register esbuild plugins, modify build context
+  },
+
+  onBuildComplete: async (context, manifest) => {
+    console.log("Build complete, adding layers");
+    // Add build layers, modify deployment
+    context.addLayer({
+      id: "my-layer",
+      files: [{ source: "./custom-file", destination: "/app/custom" }],
+      commands: ["chmod +x /app/custom"],
+    });
+  },
+};
+
+export default defineConfig({
+  project: "my-project",
+  build: {
+    extensions: [customExtension],
+  },
+});
+```
+
+## Advanced Configuration
+
+### Telemetry
+
+```ts
+import { PrismaInstrumentation } from "@prisma/instrumentation";
+import { OpenAIInstrumentation } from "@langfuse/openai";
+
+export default defineConfig({
+  // ... other config
+  telemetry: {
+    instrumentations: [new PrismaInstrumentation(), new OpenAIInstrumentation()],
+    exporters: [customExporter], // Optional custom exporters
+  },
+});
+```
+
+### Machine & Performance
+
+```ts
+export default defineConfig({
+  // ... other config
+  defaultMachine: "large-1x", // Default machine for all tasks
+  maxDuration: 300, // Default max duration (seconds)
+  enableConsoleLogging: true, // Console logging in development
+});
+```
+
+## Common Extension Combinations
+
+### Full-Stack Web App
+
+```ts
+extensions: [
+  prismaExtension({ schema: "prisma/schema.prisma", migrate: true }),
+  additionalFiles({ files: ["./public/**", "./assets/**"] }),
+  syncEnvVars(async (ctx) => [...envVars]),
+];
+```
+
+### AI/ML Processing
+
+```ts
+extensions: [
+  pythonExtension({
+    scripts: ["./ai/**/*.py"],
+    requirementsFile: "./requirements.txt",
+  }),
+  ffmpeg({ version: "7" }),
+  additionalPackages({ packages: ["wrangler"] }),
+];
+```
+
+### Web Scraping
+
+```ts
+extensions: [
+  playwright({ browsers: ["chromium"] }),
+  puppeteer(),
+  additionalFiles({ files: ["./selectors.json", "./proxies.txt"] }),
+];
+```
+
+## Best Practices
+
+- **Use specific versions**: Pin extension versions for reproducible builds
+- **External packages**: Add modules with native addons to the `build.external` array
+- **Environment sync**: Use `syncEnvVars` for dynamic secrets
+- **File paths**: Use glob patterns for flexible file inclusion
+- **Debug builds**: Use `--log-level debug --dry-run` for troubleshooting
+
+Extensions only affect deployment, not local development. Use `external` array for packages that shouldn't be bundled.

.claude/skills/trigger-dev-tasks/realtime.md

@@ -0,0 +1,244 @@
+# Trigger.dev Realtime
+
+**Real-time monitoring and updates for runs**
+
+## Core Concepts
+
+Realtime allows you to:
+
+- Subscribe to run status changes, metadata updates, and streams
+- Build real-time dashboards and UI updates
+- Monitor task progress from frontend and backend
+
+## Authentication
+
+### Public Access Tokens
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+// Read-only token for specific runs
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      runs: ["run_123", "run_456"],
+      tasks: ["my-task-1", "my-task-2"],
+    },
+  },
+  expirationTime: "1h", // Default: 15 minutes
+});
+```
+
+### Trigger Tokens (Frontend only)
+
+```ts
+// Single-use token for triggering tasks
+const triggerToken = await auth.createTriggerPublicToken("my-task", {
+  expirationTime: "30m",
+});
+```
+
+## Backend Usage
+
+### Subscribe to Runs
+
+```ts
+import { runs, tasks } from "@trigger.dev/sdk";
+
+// Trigger and subscribe
+const handle = await tasks.trigger("my-task", { data: "value" });
+
+// Subscribe to specific run
+for await (const run of runs.subscribeToRun<typeof myTask>(handle.id)) {
+  console.log(`Status: ${run.status}, Progress: ${run.metadata?.progress}`);
+  if (run.status === "COMPLETED") break;
+}
+
+// Subscribe to runs with tag
+for await (const run of runs.subscribeToRunsWithTag("user-123")) {
+  console.log(`Tagged run ${run.id}: ${run.status}`);
+}
+
+// Subscribe to batch
+for await (const run of runs.subscribeToBatch(batchId)) {
+  console.log(`Batch run ${run.id}: ${run.status}`);
+}
+```
+
+### Realtime Streams v2
+
+```ts
+import { streams, InferStreamType } from "@trigger.dev/sdk";
+
+// 1. Define streams (shared location)
+export const aiStream = streams.define<string>({
+  id: "ai-output",
+});
+
+export type AIStreamPart = InferStreamType<typeof aiStream>;
+
+// 2. Pipe from task
+export const streamingTask = task({
+  id: "streaming-task",
+  run: async (payload) => {
+    const completion = await openai.chat.completions.create({
+      model: "gpt-4",
+      messages: [{ role: "user", content: payload.prompt }],
+      stream: true,
+    });
+
+    const { waitUntilComplete } = aiStream.pipe(completion);
+    await waitUntilComplete();
+  },
+});
+
+// 3. Read from backend
+const stream = await aiStream.read(runId, {
+  timeoutInSeconds: 300,
+  startIndex: 0, // Resume from specific chunk
+});
+
+for await (const chunk of stream) {
+  console.log("Chunk:", chunk); // Fully typed
+}
+```
+
+## React Frontend Usage
+
+### Installation
+
+```bash
+npm add @trigger.dev/react-hooks
+```
+
+### Triggering Tasks
+
+```tsx
+"use client";
+import { useTaskTrigger, useRealtimeTaskTrigger } from "@trigger.dev/react-hooks";
+import type { myTask } from "../trigger/tasks";
+
+function TriggerComponent({ accessToken }: { accessToken: string }) {
+  // Basic trigger
+  const { submit, handle, isLoading } = useTaskTrigger<typeof myTask>("my-task", {
+    accessToken,
+  });
+
+  // Trigger with realtime updates
+  const {
+    submit: realtimeSubmit,
+    run,
+    isLoading: isRealtimeLoading,
+  } = useRealtimeTaskTrigger<typeof myTask>("my-task", { accessToken });
+
+  return (
+    <div>
+      <button onClick={() => submit({ data: "value" })} disabled={isLoading}>
+        Trigger Task
+      </button>
+
+      <button onClick={() => realtimeSubmit({ data: "realtime" })} disabled={isRealtimeLoading}>
+        Trigger with Realtime
+      </button>
+
+      {run && <div>Status: {run.status}</div>}
+    </div>
+  );
+}
+```
+
+### Subscribing to Runs
+
+```tsx
+"use client";
+import { useRealtimeRun, useRealtimeRunsWithTag } from "@trigger.dev/react-hooks";
+import type { myTask } from "../trigger/tasks";
+
+function SubscribeComponent({ runId, accessToken }: { runId: string; accessToken: string }) {
+  // Subscribe to specific run
+  const { run, error } = useRealtimeRun<typeof myTask>(runId, {
+    accessToken,
+    onComplete: (run) => {
+      console.log("Task completed:", run.output);
+    },
+  });
+
+  // Subscribe to tagged runs
+  const { runs } = useRealtimeRunsWithTag("user-123", { accessToken });
+
+  if (error) return <div>Error: {error.message}</div>;
+  if (!run) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <div>Status: {run.status}</div>
+      <div>Progress: {run.metadata?.progress || 0}%</div>
+      {run.output && <div>Result: {JSON.stringify(run.output)}</div>}
+
+      <h3>Tagged Runs:</h3>
+      {runs.map((r) => (
+        <div key={r.id}>
+          {r.id}: {r.status}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Realtime Streams with React
+
+```tsx
+"use client";
+import { useRealtimeStream } from "@trigger.dev/react-hooks";
+import { aiStream } from "../trigger/streams";
+
+function StreamComponent({ runId, accessToken }: { runId: string; accessToken: string }) {
+  // Pass defined stream directly for type safety
+  const { parts, error } = useRealtimeStream(aiStream, runId, {
+    accessToken,
+    timeoutInSeconds: 300,
+    throttleInMs: 50, // Control re-render frequency
+  });
+
+  if (error) return <div>Error: {error.message}</div>;
+  if (!parts) return <div>Loading...</div>;
+
+  const text = parts.join(""); // parts is typed as AIStreamPart[]
+
+  return <div>Streamed Text: {text}</div>;
+}
+```
+
+### Wait Tokens
+
+```tsx
+"use client";
+import { useWaitToken } from "@trigger.dev/react-hooks";
+
+function WaitTokenComponent({ tokenId, accessToken }: { tokenId: string; accessToken: string }) {
+  const { complete } = useWaitToken(tokenId, { accessToken });
+
+  return <button onClick={() => complete({ approved: true })}>Approve Task</button>;
+}
+```
+
+## Run Object Properties
+
+Key properties available in run subscriptions:
+
+- `id`: Unique run identifier
+- `status`: `QUEUED`, `EXECUTING`, `COMPLETED`, `FAILED`, `CANCELED`, etc.
+- `payload`: Task input data (typed)
+- `output`: Task result (typed, when completed)
+- `metadata`: Real-time updatable data
+- `createdAt`, `updatedAt`: Timestamps
+- `costInCents`: Execution cost
+
+## Best Practices
+
+- **Use Realtime over SWR**: Recommended for most use cases due to rate limits
+- **Scope tokens properly**: Only grant necessary read/trigger permissions
+- **Handle errors**: Always check for errors in hooks and subscriptions
+- **Type safety**: Use task types for proper payload/output typing
+- **Cleanup subscriptions**: Backend subscriptions auto-complete, frontend hooks auto-cleanup

.claude/skills/trigger-dev-tasks/scheduled-tasks.md

@@ -0,0 +1,113 @@
+# Scheduled Tasks (Cron)
+
+Recurring tasks using cron. For one-off future runs, use the **delay** option.
+
+## Define a Scheduled Task
+
+```ts
+import { schedules } from "@trigger.dev/sdk";
+
+export const task = schedules.task({
+  id: "first-scheduled-task",
+  run: async (payload) => {
+    payload.timestamp; // Date (scheduled time, UTC)
+    payload.lastTimestamp; // Date | undefined
+    payload.timezone; // IANA, e.g. "America/New_York" (default "UTC")
+    payload.scheduleId; // string
+    payload.externalId; // string | undefined
+    payload.upcoming; // Date[]
+
+    payload.timestamp.toLocaleString("en-US", { timeZone: payload.timezone });
+  },
+});
+```
+
+> Scheduled tasks need at least one schedule attached to run.
+
+## Attach Schedules
+
+**Declarative (sync on dev/deploy):**
+
+```ts
+schedules.task({
+  id: "every-2h",
+  cron: "0 */2 * * *", // UTC
+  run: async () => {},
+});
+
+schedules.task({
+  id: "tokyo-5am",
+  cron: { pattern: "0 5 * * *", timezone: "Asia/Tokyo", environments: ["PRODUCTION", "STAGING"] },
+  run: async () => {},
+});
+```
+
+**Imperative (SDK or dashboard):**
+
+```ts
+await schedules.create({
+  task: task.id,
+  cron: "0 0 * * *",
+  timezone: "America/New_York", // DST-aware
+  externalId: "user_123",
+  deduplicationKey: "user_123-daily", // updates if reused
+});
+```
+
+### Dynamic / Multi-tenant Example
+
+```ts
+// /trigger/reminder.ts
+export const reminderTask = schedules.task({
+  id: "todo-reminder",
+  run: async (p) => {
+    if (!p.externalId) throw new Error("externalId is required");
+    const user = await db.getUser(p.externalId);
+    await sendReminderEmail(user);
+  },
+});
+```
+
+```ts
+// app/reminders/route.ts
+export async function POST(req: Request) {
+  const data = await req.json();
+  return Response.json(
+    await schedules.create({
+      task: reminderTask.id,
+      cron: "0 8 * * *",
+      timezone: data.timezone,
+      externalId: data.userId,
+      deduplicationKey: `${data.userId}-reminder`,
+    })
+  );
+}
+```
+
+## Cron Syntax (no seconds)
+
+```
+* * * * *
+| | | | └ day of week (0–7 or 1L–7L; 0/7=Sun; L=last)
+| | | └── month (1–12)
+| | └──── day of month (1–31 or L)
+| └────── hour (0–23)
+└──────── minute (0–59)
+```
+
+## When Schedules Won't Trigger
+
+- **Dev:** only when the dev CLI is running.
+- **Staging/Production:** only for tasks in the **latest deployment**.
+
+## SDK Management
+
+```ts
+await schedules.retrieve(id);
+await schedules.list();
+await schedules.update(id, { cron: "0 0 1 * *", externalId: "ext", deduplicationKey: "key" });
+await schedules.deactivate(id);
+await schedules.activate(id);
+await schedules.del(id);
+await schedules.timezones(); // list of IANA timezones
+```

.cursor/commands/deslop.md

@@ -0,0 +1,11 @@
+# Remove AI code slop
+
+Check the diff against main, and remove all AI generated slop introduced in this branch.
+
+This includes:
+- Extra comments that a human wouldn't add or is inconsistent with the rest of the file
+- Extra defensive checks or try/catch blocks that are abnormal for that area of the codebase (especially if called by trusted / validated codepaths)
+- Casts to any to get around type issues
+- Any other style that is inconsistent with the file
+
+Report at the end with only a 1-3 sentence summary of what you changed

.cursor/rules/migrations.mdc

@@ -0,0 +1,6 @@
+---
+description: how to create and apply database migrations
+alwaysApply: false
+---
+
+Follow our [migrations.md](mdc:ai/references/migrations.md) guide for how to create and apply database migrations.

.cursor/rules/otel-metrics.mdc

@@ -0,0 +1,66 @@
+---
+description: Guidelines for creating OpenTelemetry metrics to avoid cardinality issues
+globs:
+  - "**/*.ts"
+---
+
+# OpenTelemetry Metrics Guidelines
+
+When creating or editing OTEL metrics (counters, histograms, gauges), always ensure metric attributes have **low cardinality**.
+
+## What is Cardinality?
+
+Cardinality refers to the number of unique values an attribute can have. Each unique combination of attribute values creates a new time series, which consumes memory and storage in your metrics backend.
+
+## Rules
+
+### DO use low-cardinality attributes:
+- **Enums**: `environment_type` (PRODUCTION, STAGING, DEVELOPMENT, PREVIEW)
+- **Booleans**: `hasFailures`, `streaming`, `success`
+- **Bounded error codes**: A finite, controlled set of error types
+- **Shard IDs**: When sharding is bounded (e.g., 0-15)
+
+### DO NOT use high-cardinality attributes:
+- **UUIDs/IDs**: `envId`, `userId`, `runId`, `projectId`, `organizationId`
+- **Unbounded integers**: `itemCount`, `batchSize`, `retryCount`
+- **Timestamps**: `createdAt`, `startTime`
+- **Free-form strings**: `errorMessage`, `taskName`, `queueName`
+
+## Example
+
+```typescript
+// BAD - High cardinality
+this.counter.add(1, {
+  envId: options.environmentId,        // UUID - unbounded
+  itemCount: options.runCount,         // Integer - unbounded
+});
+
+// GOOD - Low cardinality
+this.counter.add(1, {
+  environment_type: options.environmentType,  // Enum - 4 values
+  streaming: true,                            // Boolean - 2 values
+});
+```
+
+## Prometheus Metric Naming
+
+When metrics are exported via OTLP to Prometheus, the exporter automatically adds unit suffixes to metric names:
+
+| OTel Metric Name | Unit | Prometheus Name |
+|------------------|------|-----------------|
+| `my_duration_ms` | `ms` | `my_duration_ms_milliseconds` |
+| `my_counter` | counter | `my_counter_total` |
+| `items_inserted` | counter | `items_inserted_inserts_total` |
+| `batch_size` | histogram | `batch_size_items_bucket` |
+
+Keep this in mind when writing Grafana dashboards or Prometheus queries—the metric names in Prometheus will differ from the names defined in code.
+
+## Reference
+
+See the schedule engine (`internal-packages/schedule-engine/src/engine/index.ts`) for a good example of low-cardinality metric attributes.
+
+High cardinality metrics can cause:
+- Memory bloat in metrics backends (Axiom, Prometheus, etc.)
+- Slow queries and dashboard timeouts
+- Increased costs (many backends charge per time series)
+- Potential data loss or crashes at scale

.env.example

@@ -34,9 +34,9 @@ DEPLOY_REGISTRY_HOST=localhost:5000
 
 # OPTIONAL VARIABLES
 # This is used for validating emails that are allowed to log in. Every email that do not match this regex will be rejected.
-# WHITELISTED_EMAILS="authorized@yahoo\.com|authorized@gmail\.com"
+# WHITELISTED_EMAILS="^(authorized@yahoo\.com|authorized@gmail\.com)$"
 # Accounts with these emails will get global admin rights. This grants access to the admin UI.
-# ADMIN_EMAILS="admin@example\.com|another-admin@example\.com"
+# ADMIN_EMAILS="^(admin@example\.com|another-admin@example\.com)$"
 # This is used for logging in via GitHub. You can leave these commented out if you don't want to use GitHub for authentication.
 # AUTH_GITHUB_CLIENT_ID=
 # AUTH_GITHUB_CLIENT_SECRET=
@@ -85,4 +85,10 @@ POSTHOG_PROJECT_KEY=
 # These control the server-side internal telemetry
 # INTERNAL_OTEL_TRACE_EXPORTER_URL=<URL to send traces to>
 # INTERNAL_OTEL_TRACE_LOGGING_ENABLED=1
-# INTERNAL_OTEL_TRACE_INSTRUMENT_PRISMA_ENABLED=0,
+# INTERNAL_OTEL_TRACE_INSTRUMENT_PRISMA_ENABLED=0
+
+# Enable local observability stack (requires `pnpm run docker` to start otel-collector)
+# Uncomment these to send metrics to the local Prometheus via OTEL Collector:
+# INTERNAL_OTEL_METRIC_EXPORTER_ENABLED=1
+# INTERNAL_OTEL_METRIC_EXPORTER_URL=http://localhost:4318/v1/metrics
+# INTERNAL_OTEL_METRIC_EXPORTER_INTERVAL_MS=15000

.github/ISSUE_TEMPLATE/vouch-request.yml

@@ -0,0 +1,28 @@
+name: Vouch Request
+description: Request to be vouched as a contributor
+labels: ["vouch-request"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Vouch Request
+
+        We use [vouch](https://github.com/mitchellh/vouch) to manage contributor trust. PRs from unvouched users are automatically closed.
+
+        To get vouched, fill out this form. A maintainer will review your request and vouch for you by commenting on this issue.
+  - type: textarea
+    id: context
+    attributes:
+      label: Why do you want to contribute?
+      description: Tell us a bit about yourself and what you'd like to work on.
+      placeholder: "I'd like to fix a bug I found in..."
+    validations:
+      required: true
+  - type: textarea
+    id: prior-work
+    attributes:
+      label: Prior contributions or relevant experience
+      description: Links to previous open source work, relevant projects, or anything that helps us understand your background.
+      placeholder: "https://github.com/..."
+    validations:
+      required: false

.github/VOUCHED.td

@@ -0,0 +1,16 @@
+# Vouched contributors for Trigger.dev
+# See: https://github.com/mitchellh/vouch
+#
+# Org members
+0ski
+D-K-P
+ericallam
+matt-aitken
+mpcgrid
+myftija
+nicktrn
+samejr
+isshaddad
+# Outside contributors
+gautamsi
+capaj

.github/workflows/changesets-pr.yml

@@ -0,0 +1,123 @@
+name: 🦋 Changesets PR
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "packages/**"
+      - ".changeset/**"
+      - ".server-changes/**"
+      - "package.json"
+      - "pnpm-lock.yaml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  release-pr:
+    name: Create Release PR
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    if: github.repository == 'triggerdotdev/trigger.dev'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup node
+        uses: buildjet/setup-node@v4
+        with:
+          node-version: 20.20.0
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Create release PR
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          version: pnpm run changeset:version
+          commit: "chore: release"
+          title: "chore: release"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Update PR title and enhance body
+        if: steps.changesets.outputs.published != 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          PR_NUMBER=$(gh pr list --head changeset-release/main --json number --jq '.[0].number')
+          if [ -n "$PR_NUMBER" ]; then
+            git fetch origin changeset-release/main
+            # we arbitrarily reference the version of the cli package here; it is the same for all package releases
+            VERSION=$(git show origin/changeset-release/main:packages/cli-v3/package.json | jq -r '.version')
+            gh pr edit "$PR_NUMBER" --title "chore: release v$VERSION"
+
+            # Enhance the PR body with a clean, deduplicated summary
+            RAW_BODY=$(gh pr view "$PR_NUMBER" --json body --jq '.body')
+            ENHANCED_BODY=$(CHANGESET_PR_BODY="$RAW_BODY" node scripts/enhance-release-pr.mjs "$VERSION")
+            if [ -n "$ENHANCED_BODY" ]; then
+              gh api repos/triggerdotdev/trigger.dev/pulls/"$PR_NUMBER" \
+                -X PATCH \
+                -f body="$ENHANCED_BODY"
+            fi
+          fi
+
+  update-lockfile:
+    name: Update lockfile on release PR
+    runs-on: ubuntu-latest
+    needs: release-pr
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout release branch
+        uses: actions/checkout@v4
+        with:
+          ref: changeset-release/main
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.23.0
+
+      - name: Setup node
+        uses: buildjet/setup-node@v4
+        with:
+          node-version: 20.20.0
+
+      - name: Install and update lockfile
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Clean up consumed .server-changes/ files
+        run: |
+          set -e
+          shopt -s nullglob
+          files=(.server-changes/*.md)
+          for f in "${files[@]}"; do
+            if [ "$(basename "$f")" != "README.md" ]; then
+              git rm --ignore-unmatch "$f"
+            fi
+          done
+
+      - name: Commit and push lockfile + server-changes cleanup
+        run: |
+          set -e
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add pnpm-lock.yaml
+          if ! git diff --cached --quiet; then
+            git commit -m "chore: update lockfile and clean up .server-changes/ for release"
+            git push origin changeset-release/main
+          else
+            echo "No changes to commit"
+          fi

.github/workflows/claude-md-audit.yml

@@ -0,0 +1,69 @@
+name: 📝 CLAUDE.md Audit
+
+on:
+  pull_request:
+    types: [opened, ready_for_review, synchronize]
+    paths-ignore:
+      - "docs/**"
+      - ".changeset/**"
+      - ".server-changes/**"
+      - "**/*.md"
+      - "references/**"
+
+concurrency:
+  group: claude-md-audit-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  audit:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          use_sticky_comment: true
+
+          claude_args: |
+            --max-turns 15
+            --allowedTools "Read,Glob,Grep,Bash(git diff:*)"
+
+          prompt: |
+            You are reviewing a PR to check whether any CLAUDE.md files or .claude/rules/ files need updating.
+
+            ## Your task
+
+            1. Run `git diff origin/main...HEAD --name-only` to see which files changed in this PR.
+            2. For each changed directory, check if there's a CLAUDE.md in that directory or a parent directory.
+            3. Determine if any CLAUDE.md or .claude/rules/ file should be updated based on the changes. Consider:
+               - New files/directories that aren't covered by existing documentation
+               - Changed architecture or patterns that contradict current CLAUDE.md guidance
+               - New dependencies, services, or infrastructure that Claude should know about
+               - Renamed or moved files that are referenced in CLAUDE.md
+               - Changes to build commands, test patterns, or development workflows
+
+            ## Response format
+
+            If NO updates are needed, respond with exactly:
+            ✅ CLAUDE.md files look current for this PR.
+
+            If updates ARE needed, respond with a short list:
+            📝 **CLAUDE.md updates suggested:**
+            - `path/to/CLAUDE.md`: [what should be added/changed]
+            - `.claude/rules/file.md`: [what should be added/changed]
+
+            Keep suggestions specific and brief. Only flag things that would actually mislead Claude in future sessions.
+            Do NOT suggest updates for trivial changes (bug fixes, small refactors within existing patterns).
+            Do NOT suggest creating new CLAUDE.md files - only updates to existing ones.

.github/workflows/claude.yml

@@ -0,0 +1,70 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.23.0
+
+      - name: ⎔ Setup node
+        uses: buildjet/setup-node@v4
+        with:
+          node-version: 20.20.0
+          cache: "pnpm"
+
+      - name: 📥 Download deps
+        run: pnpm install --frozen-lockfile
+
+      - name: 📀 Generate Prisma Client
+        run: pnpm run generate
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          claude_args: |
+            --model claude-opus-4-5-20251101
+            --allowedTools "Bash(pnpm:*),Bash(turbo:*),Bash(git:*),Bash(gh:*),Bash(npx:*),Bash(docker:*),Edit,MultiEdit,Read,Write,Glob,Grep,LS,Task"
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'

.github/workflows/e2e.yml

@@ -31,12 +31,12 @@ jobs:
       - name: ⎔ Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 8.15.5
+          version: 10.23.0
 
       - name: ⎔ Setup node
         uses: buildjet/setup-node@v4
         with:
-          node-version: 20.19.0
+          node-version: 20.20.0
 
       - name: 📥 Download deps
         run: pnpm install --frozen-lockfile --filter trigger.dev...

.github/workflows/helm-pr-prerelease.yml

@@ -0,0 +1,138 @@
+name: 🧭 Helm Chart PR Prerelease
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - "hosting/k8s/helm/**"
+
+concurrency:
+  group: helm-prerelease-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+env:
+  REGISTRY: ghcr.io
+  CHART_NAME: trigger
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Helm
+        uses: azure/setup-helm@v4
+        with:
+          version: "3.18.3"
+
+      - name: Build dependencies
+        run: helm dependency build ./hosting/k8s/helm/
+
+      - name: Extract dependency charts
+        run: |
+          cd ./hosting/k8s/helm/
+          for file in ./charts/*.tgz; do echo "Extracting $file"; tar -xzf "$file" -C ./charts; done
+
+      - name: Lint Helm Chart
+        run: |
+          helm lint ./hosting/k8s/helm/
+
+      - name: Render templates
+        run: |
+          helm template test-release ./hosting/k8s/helm/ \
+            --values ./hosting/k8s/helm/values.yaml \
+            --output-dir ./helm-output
+
+      - name: Validate manifests
+        uses: docker://ghcr.io/yannh/kubeconform:v0.7.0
+        with:
+          entrypoint: "/kubeconform"
+          args: "-summary -output json ./helm-output"
+
+  prerelease:
+    needs: lint-and-test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Helm
+        uses: azure/setup-helm@v4
+        with:
+          version: "3.18.3"
+
+      - name: Build dependencies
+        run: helm dependency build ./hosting/k8s/helm/
+
+      - name: Extract dependency charts
+        run: |
+          cd ./hosting/k8s/helm/
+          for file in ./charts/*.tgz; do echo "Extracting $file"; tar -xzf "$file" -C ./charts; done
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate prerelease version
+        id: version
+        run: |
+          BASE_VERSION=$(grep '^version:' ./hosting/k8s/helm/Chart.yaml | awk '{print $2}')
+          PR_NUMBER=${{ github.event.pull_request.number }}
+          SHORT_SHA=$(echo "${{ github.event.pull_request.head.sha }}" | cut -c1-7)
+          PRERELEASE_VERSION="${BASE_VERSION}-pr${PR_NUMBER}.${SHORT_SHA}"
+          echo "version=$PRERELEASE_VERSION" >> $GITHUB_OUTPUT
+          echo "Prerelease version: $PRERELEASE_VERSION"
+
+      - name: Update Chart.yaml with prerelease version
+        run: |
+          sed -i "s/^version:.*/version: ${{ steps.version.outputs.version }}/" ./hosting/k8s/helm/Chart.yaml
+
+      - name: Package Helm Chart
+        run: |
+          helm package ./hosting/k8s/helm/ --destination /tmp/
+
+      - name: Push Helm Chart to GHCR
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          CHART_PACKAGE="/tmp/${{ env.CHART_NAME }}-${VERSION}.tgz"
+
+          # Push to GHCR OCI registry
+          helm push "$CHART_PACKAGE" "oci://${{ env.REGISTRY }}/${{ github.repository_owner }}/charts"
+
+      - name: Find existing comment
+        uses: peter-evans/find-comment@v3
+        id: find-comment
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: "github-actions[bot]"
+          body-includes: "Helm Chart Prerelease Published"
+
+      - name: Create or update PR comment
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          comment-id: ${{ steps.find-comment.outputs.comment-id }}
+          issue-number: ${{ github.event.pull_request.number }}
+          body: |
+            ### 🧭 Helm Chart Prerelease Published
+
+            **Version:** `${{ steps.version.outputs.version }}`
+
+            **Install:**
+            ```bash
+            helm upgrade --install trigger \
+              oci://ghcr.io/${{ github.repository_owner }}/charts/trigger \
+              --version "${{ steps.version.outputs.version }}"
+            ```
+
+            > ⚠️ This is a prerelease for testing. Do not use in production.
+          edit-mode: replace

.github/workflows/pr_checks.yml

@@ -29,3 +29,7 @@ jobs:
     with:
       package: cli-v3
     secrets: inherit
+
+  sdk-compat:
+    uses: ./.github/workflows/sdk-compat.yml
+    secrets: inherit

.github/workflows/publish.yml

@@ -1,6 +1,7 @@
 name: 🚀 Publish Trigger.dev Docker
 
 on:
+  workflow_dispatch:
   workflow_call:
     inputs:
       image_tag:

.github/workflows/release.yml

@@ -1,98 +1,264 @@
 name: 🦋 Changesets Release
 
-permissions:
-  contents: write
-
 on:
-  push:
+  pull_request:
+    types: [closed]
     branches:
       - main
-    paths-ignore:
-      - "docs/**"
-      - "**.md"
-      - ".github/CODEOWNERS"
-      - ".github/ISSUE_TEMPLATE/**"
+  workflow_dispatch:
+    inputs:
+      type:
+        description: "Select release type"
+        required: true
+        type: choice
+        options:
+          - release
+          - prerelease
+        default: "prerelease"
+      ref:
+        description: "The ref (branch, tag, or SHA) to checkout and release from"
+        required: true
+        type: string
+      prerelease_tag:
+        description: "The npm dist-tag for the prerelease (e.g., 'v4-prerelease')"
+        required: false
+        type: string
+        default: "prerelease"
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
 
 jobs:
-  release:
-    name: 🦋 Changesets Release
+  show-release-summary:
+    name: 📋 Release Summary
     runs-on: ubuntu-latest
+    if: |
+      github.repository == 'triggerdotdev/trigger.dev' &&
+      github.event_name == 'pull_request' &&
+      github.event.pull_request.merged == true &&
+      github.event.pull_request.head.ref == 'changeset-release/main'
+    steps:
+      - name: Show release summary
+        env:
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          echo "$PR_BODY" | sed -n '/^# Releases/,$p' >> $GITHUB_STEP_SUMMARY
+
+  release:
+    name: 🚀 Release npm packages
+    runs-on: ubuntu-latest
+    environment: npm-publish
     permissions:
       contents: write
       packages: write
-      pull-requests: write
-    if: github.repository == 'triggerdotdev/trigger.dev'
+      id-token: write
+    if: |
+      github.repository == 'triggerdotdev/trigger.dev' &&
+      (
+        (github.event_name == 'workflow_dispatch' && github.event.inputs.type == 'release') ||
+        (github.event_name == 'pull_request' && github.event.pull_request.merged == true && github.event.pull_request.head.ref == 'changeset-release/main')
+      )
     outputs:
       published: ${{ steps.changesets.outputs.published }}
       published_packages: ${{ steps.changesets.outputs.publishedPackages }}
       published_package_version: ${{ steps.get_version.outputs.package_version }}
     steps:
-      - name: ⬇️ Checkout repo
+      - name: Checkout repo
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.ref || github.sha }}
 
-      - name: ⎔ Setup pnpm
+      - name: Verify ref is on main
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          if ! git merge-base --is-ancestor ${{ github.event.inputs.ref }} origin/main; then
+            echo "Error: ref must be an ancestor of main (i.e., already merged)"
+            exit 1
+          fi
+
+      - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 8.15.5
+          version: 10.23.0
 
-      - name: ⎔ Setup node
+      - name: Setup node
         uses: buildjet/setup-node@v4
         with:
-          node-version: 20.19.0
+          node-version: 20.20.0
           cache: "pnpm"
 
-      - name: 📥 Download deps
+      # npm v11.5.1 or newer is required for OIDC support
+      # https://github.blog/changelog/2025-07-31-npm-trusted-publishing-with-oidc-is-generally-available/#whats-new
+      - name: Setup npm 11.x for OIDC
+        run: npm install -g npm@11.6.4
+
+      - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: 📀 Generate Prisma Client
+      - name: Generate Prisma client
         run: pnpm run generate
 
-      - name: 🏗️ Build
+      - name: Build
         run: pnpm run build --filter "@trigger.dev/*" --filter "trigger.dev"
 
-      - name: 🔎 Type check
+      - name: Type check
         run: pnpm run typecheck --filter "@trigger.dev/*" --filter "trigger.dev"
 
-      - name: 🔐 Setup npm auth
-        run: |
-          echo "registry=https://registry.npmjs.org" >> ~/.npmrc
-          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" >> ~/.npmrc
-
-        # This action has two responsibilities. The first time the workflow runs
-        # (initial push to the `main` branch) it will create a new branch and
-        # then open a PR with the related changes for the new version. After the
-        # PR is merged, the workflow will run again and this action will build +
-        # publish to npm.
-      - name: 🚀 PR / Publish
-        if: ${{ !env.ACT }}
+      - name: Publish
         id: changesets
         uses: changesets/action@v1
         with:
-          version: pnpm run changeset:version
-          commit: "chore: Update version for release"
-          title: "chore: Update version for release"
           publish: pnpm run changeset:release
-          createGithubReleases: true
+          createGithubReleases: false
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-      # - name: 🚀 PR / Publish (mock)
-      #   if: ${{ env.ACT }}
-      #   id: changesets
-      #   run: |
-      #     echo "published=true" >> "$GITHUB_OUTPUT"
-      #     echo "publishedPackages=[{\"name\": \"@xx/xx\", \"version\": \"1.2.0\"}, {\"name\": \"@xx/xy\", \"version\": \"0.8.9\"}]" >> "$GITHUB_OUTPUT"
-
-      - name: 📦 Get package version
+      - name: Show package version
         if: steps.changesets.outputs.published == 'true'
         id: get_version
         run: |
           package_version=$(echo '${{ steps.changesets.outputs.publishedPackages }}' | jq -r '.[0].version')
           echo "package_version=${package_version}" >> "$GITHUB_OUTPUT"
+
+      - name: Create unified GitHub release
+        if: steps.changesets.outputs.published == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          VERSION="${{ steps.get_version.outputs.package_version }}"
+          node scripts/generate-github-release.mjs "$VERSION" > /tmp/release-body.md
+          gh release create "v${VERSION}" \
+            --title "trigger.dev v${VERSION}" \
+            --notes-file /tmp/release-body.md \
+            --target main
+
+      - name: Create and push Docker tag
+        if: steps.changesets.outputs.published == 'true'
+        run: |
+          set -e
+          git tag "v.docker.${{ steps.get_version.outputs.package_version }}"
+          git push origin "v.docker.${{ steps.get_version.outputs.package_version }}"
+
+  # Trigger Docker builds directly via workflow_call since tags pushed with
+  # GITHUB_TOKEN don't trigger other workflows (GitHub Actions limitation).
+  publish-docker:
+    name: 🐳 Publish Docker images
+    needs: release
+    if: needs.release.outputs.published == 'true'
+    uses: ./.github/workflows/publish.yml
+    secrets: inherit
+    with:
+      image_tag: v${{ needs.release.outputs.published_package_version }}
+
+  # After Docker images are published, update the GitHub release with the exact GHCR tag URL.
+  # The GHCR package version ID is only known after the image is pushed, so we query for it here.
+  update-release:
+    name: 🔗 Update release Docker link
+    needs: [release, publish-docker]
+    if: needs.release.outputs.published == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      packages: read
+    steps:
+      - name: Update GitHub release with Docker image link
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          VERSION="${{ needs.release.outputs.published_package_version }}"
+          TAG="v${VERSION}"
+
+          # Query GHCR for the version ID matching this tag
+          VERSION_ID=$(gh api --paginate -H "Accept: application/vnd.github+json" \
+            /orgs/triggerdotdev/packages/container/trigger.dev/versions \
+            --jq ".[] | select(.metadata.container.tags[] == \"${TAG}\") | .id" \
+            | head -1)
+
+          if [ -z "$VERSION_ID" ]; then
+            echo "Warning: Could not find GHCR version ID for tag ${TAG}, skipping update"
+            exit 0
+          fi
+
+          DOCKER_URL="https://github.com/triggerdotdev/trigger.dev/pkgs/container/trigger.dev/${VERSION_ID}?tag=${TAG}"
+          GENERIC_URL="https://github.com/triggerdotdev/trigger.dev/pkgs/container/trigger.dev"
+
+          # Get current release body and replace the generic link with the tag-specific one.
+          # Use word boundary after GENERIC_URL (closing paren) to avoid matching URLs that
+          # already have a version ID appended (idempotent on re-runs).
+          gh release view "${TAG}" --json body --jq '.body' > /tmp/release-body.md
+          sed -i "s|${GENERIC_URL})|${DOCKER_URL})|g" /tmp/release-body.md
+
+          gh release edit "${TAG}" --notes-file /tmp/release-body.md
+
+  # Dispatch changelog entry creation to the marketing site repo.
+  # Runs after update-release so the GitHub release body already has the exact Docker image URL.
+  dispatch-changelog:
+    name: 📝 Dispatch changelog PR
+    needs: [release, update-release]
+    if: needs.release.outputs.published == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.CROSS_REPO_PAT }}
+          repository: triggerdotdev/trigger.dev-site-v3
+          event-type: new-release
+          client-payload: '{"version": "${{ needs.release.outputs.published_package_version }}"}'
+
+  # The prerelease job needs to be on the same workflow file due to a limitation related to how npm verifies OIDC claims.
+  prerelease:
+    name: 🧪 Prerelease
+    runs-on: ubuntu-latest
+    environment: npm-publish
+    permissions:
+      contents: read
+      id-token: write
+    if: github.repository == 'triggerdotdev/trigger.dev' && github.event_name == 'workflow_dispatch' && github.event.inputs.type == 'prerelease'
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.inputs.ref }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.23.0
+
+      - name: Setup node
+        uses: buildjet/setup-node@v4
+        with:
+          node-version: 20.20.0
+          cache: "pnpm"
+
+      # npm v11.5.1 or newer is required for OIDC support
+      # https://github.blog/changelog/2025-07-31-npm-trusted-publishing-with-oidc-is-generally-available/#whats-new
+      - name: Setup npm 11.x for OIDC
+        run: npm install -g npm@11.6.4
+
+      - name: Download deps
+        run: pnpm install --frozen-lockfile
+
+      - name: Generate Prisma Client
+        run: pnpm run generate
+
+      - name: Snapshot version
+        run: pnpm exec changeset version --snapshot ${{ github.event.inputs.prerelease_tag }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Clean
+        run: pnpm run clean --filter "@trigger.dev/*" --filter "trigger.dev"
+
+      - name: Build
+        run: pnpm run build --filter "@trigger.dev/*" --filter "trigger.dev"
+
+      - name: Publish prerelease
+        run: pnpm exec changeset publish --no-git-tag --snapshot --tag ${{ github.event.inputs.prerelease_tag }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/sdk-compat.yml

@@ -0,0 +1,178 @@
+name: "🔌 SDK Compatibility Tests"
+
+permissions:
+  contents: read
+
+on:
+  workflow_call:
+
+jobs:
+  node-compat:
+    name: "Node.js ${{ matrix.node }} (${{ matrix.os }})"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        node: ["20.20", "22.12"]
+
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.23.0
+
+      - name: ⎔ Setup node
+        uses: buildjet/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: "pnpm"
+
+      - name: 📥 Download deps
+        run: pnpm install --frozen-lockfile
+
+      - name: 📀 Generate Prisma Client
+        run: pnpm run generate
+
+      - name: 🔨 Build SDK dependencies
+        shell: bash
+        run: pnpm run build --filter '@trigger.dev/sdk^...'
+
+      - name: 🔨 Build SDK
+        shell: bash
+        run: pnpm run build --filter '@trigger.dev/sdk'
+
+      - name: 🧪 Run SDK Compatibility Tests
+        shell: bash
+        run: pnpm --filter @internal/sdk-compat-tests test
+
+  bun-compat:
+    name: "Bun Runtime"
+    runs-on: ubuntu-latest
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.23.0
+
+      - name: ⎔ Setup node
+        uses: buildjet/setup-node@v4
+        with:
+          node-version: 20.20.0
+          cache: "pnpm"
+
+      - name: 🥟 Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: 📥 Download deps
+        run: pnpm install --frozen-lockfile
+
+      - name: 📀 Generate Prisma Client
+        run: pnpm run generate
+
+      - name: 🔨 Build SDK dependencies
+        run: pnpm run build --filter @trigger.dev/sdk^...
+
+      - name: 🔨 Build SDK
+        run: pnpm run build --filter @trigger.dev/sdk
+
+      - name: 🧪 Run Bun Compatibility Test
+        working-directory: internal-packages/sdk-compat-tests/src/fixtures/bun
+        run: bun run test.ts
+
+  deno-compat:
+    name: "Deno Runtime"
+    runs-on: ubuntu-latest
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.23.0
+
+      - name: ⎔ Setup node
+        uses: buildjet/setup-node@v4
+        with:
+          node-version: 20.20.0
+          cache: "pnpm"
+
+      - name: 🦕 Setup Deno
+        uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+
+      - name: 📥 Download deps
+        run: pnpm install --frozen-lockfile
+
+      - name: 📀 Generate Prisma Client
+        run: pnpm run generate
+
+      - name: 🔨 Build SDK dependencies
+        run: pnpm run build --filter @trigger.dev/sdk^...
+
+      - name: 🔨 Build SDK
+        run: pnpm run build --filter @trigger.dev/sdk
+
+      - name: 🔗 Link node_modules for Deno fixture
+        working-directory: internal-packages/sdk-compat-tests/src/fixtures/deno
+        run: ln -s ../../../../../node_modules node_modules
+
+      - name: 🧪 Run Deno Compatibility Test
+        working-directory: internal-packages/sdk-compat-tests/src/fixtures/deno
+        run: deno run --allow-read --allow-env --allow-sys test.ts
+
+  cloudflare-compat:
+    name: "Cloudflare Workers"
+    runs-on: ubuntu-latest
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.23.0
+
+      - name: ⎔ Setup node
+        uses: buildjet/setup-node@v4
+        with:
+          node-version: 20.20.0
+          cache: "pnpm"
+
+      - name: 📥 Download deps
+        run: pnpm install --frozen-lockfile
+
+      - name: 📀 Generate Prisma Client
+        run: pnpm run generate
+
+      - name: 🔨 Build SDK dependencies
+        run: pnpm run build --filter @trigger.dev/sdk^...
+
+      - name: 🔨 Build SDK
+        run: pnpm run build --filter @trigger.dev/sdk
+
+      - name: 📥 Install Cloudflare fixture deps
+        working-directory: internal-packages/sdk-compat-tests/src/fixtures/cloudflare-worker
+        run: pnpm install
+
+      - name: 🧪 Run Cloudflare Workers Compatibility Test (dry-run)
+        working-directory: internal-packages/sdk-compat-tests/src/fixtures/cloudflare-worker
+        run: npx wrangler deploy --dry-run --outdir dist

.github/workflows/typecheck.yml

@@ -19,12 +19,12 @@ jobs:
       - name: ⎔ Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 8.15.5
+          version: 10.23.0
 
       - name: ⎔ Setup node
         uses: buildjet/setup-node@v4
         with:
-          node-version: 20.19.0
+          node-version: 20.20.0
           cache: "pnpm"
 
       - name: 📥 Download deps
@@ -35,6 +35,8 @@ jobs:
 
       - name: 🔎 Type check
         run: pnpm run typecheck
+        env:
+          NODE_OPTIONS: --max-old-space-size=8192
 
       - name: 🔎 Check exports
         run: pnpm run check-exports

.github/workflows/unit-tests-internal.yml

@@ -53,12 +53,12 @@ jobs:
       - name: ⎔ Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 8.15.5
+          version: 10.23.0
 
       - name: ⎔ Setup node
         uses: buildjet/setup-node@v4
         with:
-          node-version: 20.19.0
+          node-version: 20.20.0
           cache: "pnpm"
 
       # ..to avoid rate limits when pulling images
@@ -72,6 +72,17 @@ jobs:
         if: ${{ !env.DOCKERHUB_USERNAME }}
         run: echo "DockerHub login skipped because secrets are not available."
 
+      - name: 🐳 Pre-pull testcontainer images
+        if: ${{ env.DOCKERHUB_USERNAME }}
+        run: |
+          echo "Pre-pulling Docker images with authenticated session..."
+          docker pull postgres:14
+          docker pull clickhouse/clickhouse-server:25.4-alpine
+          docker pull redis:7-alpine
+          docker pull testcontainers/ryuk:0.11.0
+          docker pull electricsql/electric:1.2.4
+          echo "Image pre-pull complete"
+
       - name: 📥 Download deps
         run: pnpm install --frozen-lockfile
 
@@ -111,12 +122,12 @@ jobs:
       - name: ⎔ Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 8.15.5
+          version: 10.23.0
 
       - name: ⎔ Setup node
         uses: buildjet/setup-node@v4
         with:
-          node-version: 20.19.0
+          node-version: 20.20.0
           # no cache enabled, we're not installing deps
 
       - name: Download blob reports from GitHub Actions Artifacts

.github/workflows/unit-tests-packages.yml

@@ -53,12 +53,12 @@ jobs:
       - name: ⎔ Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 8.15.5
+          version: 10.23.0
 
       - name: ⎔ Setup node
         uses: buildjet/setup-node@v4
         with:
-          node-version: 20.19.0
+          node-version: 20.20.0
           cache: "pnpm"
 
       # ..to avoid rate limits when pulling images
@@ -72,6 +72,17 @@ jobs:
         if: ${{ !env.DOCKERHUB_USERNAME }}
         run: echo "DockerHub login skipped because secrets are not available."
 
+      - name: 🐳 Pre-pull testcontainer images
+        if: ${{ env.DOCKERHUB_USERNAME }}
+        run: |
+          echo "Pre-pulling Docker images with authenticated session..."
+          docker pull postgres:14
+          docker pull clickhouse/clickhouse-server:25.4-alpine
+          docker pull redis:7-alpine
+          docker pull testcontainers/ryuk:0.11.0
+          docker pull electricsql/electric:1.2.4
+          echo "Image pre-pull complete"
+
       - name: 📥 Download deps
         run: pnpm install --frozen-lockfile
 
@@ -111,12 +122,12 @@ jobs:
       - name: ⎔ Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 8.15.5
+          version: 10.23.0
 
       - name: ⎔ Setup node
         uses: buildjet/setup-node@v4
         with:
-          node-version: 20.19.0
+          node-version: 20.20.0
           # no cache enabled, we're not installing deps
 
       - name: Download blob reports from GitHub Actions Artifacts

.github/workflows/unit-tests-webapp.yml

@@ -53,12 +53,12 @@ jobs:
       - name: ⎔ Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 8.15.5
+          version: 10.23.0
 
       - name: ⎔ Setup node
         uses: buildjet/setup-node@v4
         with:
-          node-version: 20.19.0
+          node-version: 20.20.0
           cache: "pnpm"
 
       # ..to avoid rate limits when pulling images
@@ -72,6 +72,17 @@ jobs:
         if: ${{ !env.DOCKERHUB_USERNAME }}
         run: echo "DockerHub login skipped because secrets are not available."
 
+      - name: 🐳 Pre-pull testcontainer images
+        if: ${{ env.DOCKERHUB_USERNAME }}
+        run: |
+          echo "Pre-pulling Docker images with authenticated session..."
+          docker pull postgres:14
+          docker pull clickhouse/clickhouse-server:25.4-alpine
+          docker pull redis:7-alpine
+          docker pull testcontainers/ryuk:0.11.0
+          docker pull electricsql/electric:1.2.4
+          echo "Image pre-pull complete"
+
       - name: 📥 Download deps
         run: pnpm install --frozen-lockfile
 
@@ -119,12 +130,12 @@ jobs:
       - name: ⎔ Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 8.15.5
+          version: 10.23.0
 
       - name: ⎔ Setup node
         uses: buildjet/setup-node@v4
         with:
-          node-version: 20.19.0
+          node-version: 20.20.0
           # no cache enabled, we're not installing deps
 
       - name: Download blob reports from GitHub Actions Artifacts

.github/workflows/vouch-check-pr.yml

@@ -0,0 +1,22 @@
+name: Vouch - Check PR
+
+on:
+  pull_request_target:
+    types: [opened, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: read
+
+jobs:
+  check-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: mitchellh/vouch/action/check-pr@c6d80ead49839655b61b422700b7a3bc9d0804a9 # v1.4.2
+        with:
+          pr-number: ${{ github.event.pull_request.number }}
+          auto-close: true
+          require-vouch: true
+        env:
+          GH_TOKEN: ${{ github.token }}

.github/workflows/vouch-manage-by-issue.yml

@@ -0,0 +1,24 @@
+name: Vouch - Manage by Issue
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: write
+  issues: write
+
+jobs:
+  manage:
+    runs-on: ubuntu-latest
+    if: >-
+      contains(github.event.comment.body, 'vouch') ||
+      contains(github.event.comment.body, 'denounce') ||
+      contains(github.event.comment.body, 'unvouch')
+    steps:
+      - uses: mitchellh/vouch/action/manage-by-issue@c6d80ead49839655b61b422700b7a3bc9d0804a9 # v1.4.2
+        with:
+          comment-id: ${{ github.event.comment.id }}
+          issue-id: ${{ github.event.issue.number }}
+        env:
+          GH_TOKEN: ${{ github.token }}

.gitignore

@@ -15,6 +15,9 @@ out/
 dist
 packages/**/dist
 
+# vendored bundles (generated during build)
+packages/**/src/**/vendor
+
 # Tailwind
 apps/**/styles/tailwind.css
 packages/**/styles/tailwind.css
@@ -29,12 +32,10 @@ yarn-debug.log*
 yarn-error.log*
 
 # local env files
-.env.docker
+.env
+.env.*
 .docker/*.env
-.env.local
-.env.development.local
-.env.test.local
-.env.production.local
+!.env.example
 
 # turbo
 .turbo
@@ -63,5 +64,8 @@ apps/**/public/build
 /packages/core/src/package.json
 /packages/trigger-sdk/src/package.json
 /packages/python/src/package.json
-.claude
-.mcp.log
+**/.claude/settings.local.json
+.mcp.log
+.mcp.json
+.cursor/debug.log
+ailogger-output.log

.npmrc

@@ -1,5 +0,0 @@
-link-workspace-packages=false
-public-hoist-pattern[]=*prisma*
-prefer-workspace-packages=true
-update-notifier=false
-side-effects-cache=false

.nvmrc

@@ -1 +1 @@
-v20.19.0
+v20.20.0

.server-changes/README.md

@@ -0,0 +1,81 @@
+# Server Changes
+
+This directory tracks changes to server-only components (webapp, supervisor, coordinator, etc.) that are not captured by changesets. Changesets only track published npm packages — server changes would otherwise go undocumented.
+
+## When to add a file
+
+**Server-only PRs**: If your PR only changes `apps/webapp/`, `apps/supervisor/`, `apps/coordinator/`, or other server components (and does NOT change anything in `packages/`), add a `.server-changes/` file.
+
+**Mixed PRs** (both packages and server): Just add a changeset as usual. No `.server-changes/` file needed — the changeset covers it.
+
+**Package-only PRs**: Just add a changeset as usual.
+
+## File format
+
+Create a markdown file with a descriptive name:
+
+```
+.server-changes/fix-batch-queue-stalls.md
+```
+
+With this format:
+
+```markdown
+---
+area: webapp
+type: fix
+---
+
+Speed up batch queue processing by removing stalls and fixing retry race
+```
+
+### Fields
+
+- **area** (required): `webapp` | `supervisor` | `coordinator` | `kubernetes-provider` | `docker-provider`
+- **type** (required): `feature` | `fix` | `improvement` | `breaking`
+
+### Description
+
+The body text (below the frontmatter) is a one-line description of the change. Keep it concise — it will appear in release notes.
+
+## Lifecycle
+
+1. Engineer adds a `.server-changes/` file in their PR
+2. Files accumulate on `main` as PRs merge
+3. The changeset release PR includes these in its summary
+4. After the release merges, CI cleans up the consumed files
+
+## Examples
+
+**New feature:**
+
+```markdown
+---
+area: webapp
+type: feature
+---
+
+TRQL query language and the Query page
+```
+
+**Bug fix:**
+
+```markdown
+---
+area: webapp
+type: fix
+---
+
+Fix schedule limit counting for orgs with custom limits
+```
+
+**Improvement:**
+
+```markdown
+---
+area: webapp
+type: improvement
+---
+
+Use the replica for API auth queries to reduce primary load
+```

.server-changes/batch-queue-perf-fixes.md

@@ -0,0 +1,10 @@
+---
+area: webapp
+type: fix
+---
+
+Speed up batch queue processing by disabling cooloff and increasing the batch queue processing concurrency limits on the cloud:
+
+- Pro plan: increase to 50 from 10.
+- Hobby plan: increase to 10 from 5.
+- Free plan: increase to 5 from 1.

.server-changes/fix-blocking-waitpoint-race-condition.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+Fix a race condition in the waitpoint system where a run could be blocked by a completed waitpoint but never be resumed because of a PostgreSQL MVCC issue. This was most likely to occur when creating a waitpoint via `wait.forToken()` at the same moment as completing the token with `wait.completeToken()`. Other types of waitpoints (timed, child runs) were not affected.

.server-changes/fix-dispatch-shard-tenant-based.md

@@ -0,0 +1,9 @@
+---
+area: webapp
+type: feature
+---
+
+Two-level tenant dispatch architecture for batch queue processing. Replaces the
+single master queue with a two-level index: a dispatch index (tenant → shard)
+and per-tenant queue indexes (tenant → queues). This enables O(1) tenant
+selection and fair scheduling across tenants regardless of queue count. Improves batch queue processing performance.

.server-changes/fix-metrics-dashboard-chart-bugs.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+Fix metrics dashboard chart series colors going out of sync and widgets not reloading stale data when scrolled back into view

.server-changes/graceful-oversized-batch-items.md

@@ -0,0 +1,10 @@
+---
+area: webapp
+type: fix
+---
+
+Gracefully handle oversized batch items instead of aborting the stream.
+
+When an NDJSON batch item exceeds the maximum size, the parser now emits an error marker instead of throwing, allowing the batch to seal normally. The oversized item becomes a pre-failed run with `PAYLOAD_TOO_LARGE` error code, while other items in the batch process successfully. This prevents `batchTriggerAndWait` from seeing connection errors and retrying with exponential backoff.
+
+Also fixes the NDJSON parser not consuming the remainder of an oversized line split across multiple chunks, which caused "Invalid JSON" errors on subsequent lines.

.server-changes/input-stream-wait.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+Add input streams with API routes for sending data to running tasks, SSE reading, and waitpoint creation. Includes Redis cache for fast `.send()` to `.wait()` bridging, dashboard span support for input stream operations, and s2-lite support with configurable S2 endpoint, access token skipping, and S2-Basin headers for self-hosted deployments. Adds s2-lite to Docker Compose for local development.

.server-changes/require-admin-during-impersonation.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+Require the user is an admin during an impersonation session. Previously only the impersonation cookie was checked; now the real user's admin flag is verified on every request. If admin has been revoked, the session falls back to the real user's ID.

.vscode/launch.json

@@ -31,6 +31,15 @@
       "cwd": "${workspaceFolder}/apps/webapp",
       "sourceMaps": true
     },
+    {
+      "type": "node-terminal",
+      "request": "launch",
+      "name": "Debug opened test file",
+      "command": "pnpm run test -- ./${relativeFile}",
+      "envFile": "${workspaceFolder}/.env",
+      "cwd": "${workspaceFolder}",
+      "sourceMaps": true
+    },
     {
       "type": "chrome",
       "request": "launch",

.vscode/settings.json

@@ -7,5 +7,5 @@
     "packages/cli-v3/e2e": true
   },
   "vitest.disableWorkspaceWarning": true,
-  "typescript.experimental.useTsgo": false
+  "chat.agent.maxRequests": 10000
 }

AGENTS.md

@@ -13,7 +13,7 @@ This repository is a pnpm monorepo managed with Turbo. It contains multiple apps
 See `ai/references/repo.md` for a more complete explanation of the workspaces.
 
 ## Development setup
-1. Install dependencies with `pnpm i` (pnpm `8.15.5` and Node.js `20.11.1` are required).
+1. Install dependencies with `pnpm i` (pnpm `10.23.0` and Node.js `20.20.0` are required).
 2. Copy `.env.example` to `.env` and generate a random 16 byte hex string for `ENCRYPTION_KEY` (`openssl rand -hex 16`). Update other secrets if needed.
 3. Start the local services with Docker:
    ```bash

CHANGESETS.md

@@ -1,24 +1,49 @@
-# Changesets
+# Changesets and Server Changes
 
-Trigger.dev uses [changesets](https://github.com/changesets/changesets) to manage updated our packages and releasing them to npm.
+Trigger.dev uses [changesets](https://github.com/changesets/changesets) to manage package versions and releasing them to npm. For server-only changes, we use a lightweight `.server-changes/` convention.
 
-## Adding a changeset
+## Adding a changeset (package changes)
 
 To add a changeset, use `pnpm run changeset:add` and follow the instructions [here](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md). Please only ever select one of our public packages when adding a changeset.
 
-## Release instructions (local only)
+## Adding a server change (server-only changes)
 
-Based on the instructions [here](https://github.com/changesets/changesets/blob/main/docs/intro-to-using-changesets.md)
+If your PR only changes server components (`apps/webapp/`, `apps/supervisor/`, etc.) and does NOT change any published packages, add a `.server-changes/` file instead of a changeset:
 
-1. Run `pnpm run changeset:version`
-2. Run `pnpm run changeset:release`
+```sh
+cat > .server-changes/fix-batch-queue-stalls.md << 'EOF'
+---
+area: webapp
+type: fix
+---
+
+Speed up batch queue processing by removing stalls and fixing retry race
+EOF
+```
+
+- `area`: `webapp` | `supervisor` | `coordinator` | `kubernetes-provider` | `docker-provider`
+- `type`: `feature` | `fix` | `improvement` | `breaking`
+
+For **mixed PRs** (both packages and server): just add a changeset. No `.server-changes/` file needed.
+
+See `.server-changes/README.md` for full documentation.
+
+## When to add which
+
+| PR changes | What to add |
+|---|---|
+| Only packages (`packages/`) | Changeset (`pnpm run changeset:add`) |
+| Only server (`apps/`) | `.server-changes/` file |
+| Both packages and server | Just the changeset |
 
 ## Release instructions (CI)
 
 Please follow the best-practice of adding changesets in the same commit as the code making the change with `pnpm run changeset:add`, as it will allow our release.yml CI workflow to function properly:
 
-- Anytime new changesets are added in a commit in the `main` branch, the [release.yml](./.github/workflows/release.yml) workflow will run and will automatically create/update a PR with a fresh run of `pnpm run changeset:version`.
-- When the version PR is merged into `main`, the release.yml workflow will automatically run `pnpm run changeset:release` to build and release packages to npm.
+- Anytime new changesets are added in a commit in the `main` branch, the [changesets-pr.yml](./.github/workflows/changesets-pr.yml) workflow will run and will automatically create/update a PR with a fresh run of `pnpm run changeset:version`.
+- The release PR body is automatically enhanced with a clean, deduplicated summary that includes both package changes and `.server-changes/` entries.
+- Consumed `.server-changes/` files are removed on the `changeset-release/main` branch — the same way changesets deletes `.changeset/*.md` files. When the release PR merges, they're gone from main.
+- When the version PR is merged into `main`, the [release.yml](./.github/workflows/release.yml) workflow will automatically build, release packages to npm, and create a single unified GitHub release.
 
 ## Pre-release instructions
 

CLAUDE.md

@@ -0,0 +1,162 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository. Subdirectory CLAUDE.md files provide deeper context when you navigate into specific areas.
+
+## Build and Development Commands
+
+This is a pnpm 10.23.0 monorepo using Turborepo. Run commands from root with `pnpm run`.
+
+```bash
+pnpm run docker              # Start Docker services (PostgreSQL, Redis, Electric)
+pnpm run db:migrate           # Run database migrations
+pnpm run db:seed              # Seed the database (required for reference projects)
+
+# Build packages (required before running)
+pnpm run build --filter webapp && pnpm run build --filter trigger.dev && pnpm run build --filter @trigger.dev/sdk
+
+pnpm run dev --filter webapp  # Run webapp (http://localhost:3030)
+pnpm run dev --filter trigger.dev --filter "@trigger.dev/*"  # Watch CLI and packages
+```
+
+## Testing
+
+We use vitest exclusively. **Never mock anything** - use testcontainers instead.
+
+```bash
+pnpm run test --filter webapp                          # All tests for a package
+cd internal-packages/run-engine
+pnpm run test ./src/engine/tests/ttl.test.ts --run     # Single test file
+pnpm run build --filter @internal/run-engine           # May need to build deps first
+```
+
+Test files go next to source files (e.g., `MyService.ts` -> `MyService.test.ts`).
+
+### Testcontainers for Redis/PostgreSQL
+
+```typescript
+import { redisTest, postgresTest, containerTest } from "@internal/testcontainers";
+
+redisTest("should use redis", async ({ redisOptions }) => { /* ... */ });
+postgresTest("should use postgres", async ({ prisma }) => { /* ... */ });
+containerTest("should use both", async ({ prisma, redisOptions }) => { /* ... */ });
+```
+
+## Changesets and Server Changes
+
+When modifying any public package (`packages/*` or `integrations/*`), add a changeset:
+
+```bash
+pnpm run changeset:add
+```
+
+- Default to **patch** for bug fixes and minor changes
+- Confirm with maintainers before selecting **minor** (new features)
+- **Never** select major without explicit approval
+
+When modifying only server components (`apps/webapp/`, `apps/supervisor/`, etc.) with no package changes, add a `.server-changes/` file instead. See `.server-changes/README.md` for format and documentation.
+
+## Architecture Overview
+
+### Request Flow
+
+User API call -> Webapp routes -> Services -> RunEngine -> Redis Queue -> Supervisor -> Container execution -> Results back through RunEngine -> ClickHouse (analytics) + PostgreSQL (state)
+
+### Apps
+
+- **apps/webapp**: Remix 2.1.0 app - main API, dashboard, orchestration. Uses Express server.
+- **apps/supervisor**: Manages task execution containers (Docker/Kubernetes).
+
+### Public Packages
+
+- **packages/trigger-sdk** (`@trigger.dev/sdk`): Main SDK for writing tasks
+- **packages/cli-v3** (`trigger.dev`): CLI - also bundles code that goes into customer task images
+- **packages/core** (`@trigger.dev/core`): Shared types. **Import subpaths only** (never root).
+- **packages/build** (`@trigger.dev/build`): Build extensions and types
+- **packages/react-hooks**: React hooks for realtime and triggering
+- **packages/redis-worker** (`@trigger.dev/redis-worker`): Redis-based background job system
+
+### Internal Packages
+
+- **internal-packages/database**: Prisma 6.14.0 client and schema (PostgreSQL)
+- **internal-packages/clickhouse**: ClickHouse client, schema migrations, analytics queries
+- **internal-packages/run-engine**: "Run Engine 2.0" - core run lifecycle management
+- **internal-packages/redis**: Redis client creation utilities (ioredis)
+- **internal-packages/testcontainers**: Test helpers for Redis/PostgreSQL containers
+- **internal-packages/schedule-engine**: Durable cron scheduling
+- **internal-packages/zodworker**: Graphile-worker wrapper (DEPRECATED - use redis-worker)
+
+### Legacy V1 Engine Code
+
+The `apps/webapp/app/v3/` directory name is misleading - most code there is actively used by V2. Only specific files are V1-only legacy (MarQS queue, triggerTaskV1, cancelTaskRunV1, etc.). See `apps/webapp/CLAUDE.md` for the exact list. When you encounter V1/V2 branching in services, only modify V2 code paths. All new work uses Run Engine 2.0 (`@internal/run-engine`) and redis-worker.
+
+### Documentation
+
+Docs live in `docs/` as a Mintlify site (MDX format). See `docs/CLAUDE.md` for conventions.
+
+### Reference Projects
+
+The `references/` directory contains test workspaces for testing SDK and platform features. Use `references/hello-world` to manually test changes before submitting PRs.
+
+## Docker Image Guidelines
+
+When updating Docker image references:
+
+- **Always use multiplatform/index digests**, not architecture-specific digests
+- Architecture-specific digests cause CI failures on different build environments
+- Use the digest from the main Docker Hub page, not from a specific OS/ARCH variant
+
+## Writing Trigger.dev Tasks
+
+Always import from `@trigger.dev/sdk`. Never use `@trigger.dev/sdk/v3` or deprecated `client.defineJob`.
+
+```typescript
+import { task } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  run: async (payload: { message: string }) => {
+    // Task logic
+  },
+});
+```
+
+### SDK Documentation Rules
+
+The `rules/` directory contains versioned SDK documentation distributed via the SDK installer. Current version: `rules/manifest.json`. Do NOT update `rules/` or `.claude/skills/trigger-dev-tasks/` unless explicitly asked - these are maintained in separate dedicated passes.
+
+## Testing with hello-world Reference Project
+
+First-time setup:
+
+1. `pnpm run db:seed` to seed the database
+2. Build CLI: `pnpm run build --filter trigger.dev && pnpm i`
+3. Authorize: `cd references/hello-world && pnpm exec trigger login -a http://localhost:3030`
+
+Running: `cd references/hello-world && pnpm exec trigger dev`
+
+## Local Task Testing Workflow
+
+### Step 1: Start Webapp in Background
+
+```bash
+# Run from repo root with run_in_background: true
+pnpm run dev --filter webapp
+curl -s http://localhost:3030/healthcheck  # Verify running
+```
+
+### Step 2: Start Trigger Dev in Background
+
+```bash
+cd references/hello-world && pnpm exec trigger dev
+# Wait for "Local worker ready [node]"
+```
+
+### Step 3: Trigger and Monitor Tasks via MCP
+
+```
+mcp__trigger__get_current_worker(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev")
+mcp__trigger__trigger_task(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev", taskId: "hello-world", payload: {"message": "Hello"})
+mcp__trigger__list_runs(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev", taskIdentifier: "hello-world", limit: 5)
+```
+
+Dashboard: http://localhost:3030/orgs/references-9dfd/projects/hello-world-97DT/env/dev/runs

CONTRIBUTING.md

@@ -2,10 +2,25 @@
 
 Thank you for taking the time to contribute to Trigger.dev. Your involvement is not just welcomed, but we encourage it! 🚀
 
-Please take some time to read this guide to understand contributing best practices for Trigger.dev.
+Please take some time to read this guide to understand contributing best practices for Trigger.dev. Note that we use [vouch](https://github.com/mitchellh/vouch) to manage contributor trust, so you'll need to be vouched before opening a PR.
 
 Thank you for helping us make Trigger.dev even better! 🤩
 
+> **Important:** We only accept PRs that address a single issue. Please do not submit PRs containing multiple unrelated fixes or features. If you have multiple contributions, open a separate PR for each one.
+
+## Getting vouched (required before opening a PR)
+
+We use [vouch](https://github.com/mitchellh/vouch) to manage contributor trust. **PRs from unvouched users are automatically closed.**
+
+Before you open your first pull request, you need to be vouched by a maintainer. Here's how:
+
+1. Open a [Vouch Request](https://github.com/triggerdotdev/trigger.dev/issues/new?template=vouch-request.yml) issue.
+2. Tell us what you'd like to work on and share any relevant background.
+3. A maintainer will review your request and vouch for you by commenting on the issue.
+4. Once vouched, your PRs will be accepted normally.
+
+If you're unsure whether you're already vouched, go ahead and open a PR — the check will tell you.
+
 ## Developing
 
 The development branch is `main`. This is the branch that all pull
@@ -14,8 +29,8 @@ branch are tagged into a release periodically.
 
 ### Prerequisites
 
-- [Node.js](https://nodejs.org/en) version 20.11.1
-- [pnpm package manager](https://pnpm.io/installation) version 8.15.5
+- [Node.js](https://nodejs.org/en) version 20.20.0
+- [pnpm package manager](https://pnpm.io/installation) version 10.23.0
 - [Docker](https://www.docker.com/get-started/)
 - [protobuf](https://github.com/protocolbuffers/protobuf)
 
@@ -34,9 +49,9 @@ branch are tagged into a release periodically.
    ```
    cd trigger.dev
    ```
-3. Ensure you are on the correct version of Node.js (20.11.1). If you are using `nvm`, there is an `.nvmrc` file that will automatically select the correct version of Node.js when you navigate to the repository.
+3. Ensure you are on the correct version of Node.js (20.20.0). If you are using `nvm`, there is an `.nvmrc` file that will automatically select the correct version of Node.js when you navigate to the repository.
 
-4. Run `corepack enable` to use the correct version of pnpm (`8.15.5`) as specified in the root `package.json` file.
+4. Run `corepack enable` to use the correct version of pnpm (`10.23.0`) as specified in the root `package.json` file.
 
 5. Install the required packages using pnpm.
    ```
@@ -92,7 +107,7 @@ We use the `<root>/references/hello-world` subdirectory as a staging ground for
 
 First, make sure you are running the webapp according to the instructions above. Then:
 
-1. Visit http://localhost:3030 in your browser and create a new V3 project called "hello-world".
+1. Visit http://localhost:3030 in your browser and create a new project called "hello-world".
 
 2. In Postgres go to the "Projects" table and for the project you create change the `externalRef` to `proj_rrkpdguyagvsoktglnod`.
 
@@ -127,7 +142,7 @@ pnpm exec trigger deploy --profile local
 
 ### Running
 
-The following steps should be followed any time you start working on a new feature you want to test in v3:
+The following steps should be followed any time you start working on a new feature you want to test:
 
 1. Make sure the webapp is running on localhost:3030
 
@@ -252,6 +267,39 @@ You will be prompted to select which packages to include in the changeset. Only
 
 Most of the time the changes you'll make are likely to be categorized as patch releases. If you feel like there is the need for a minor or major release of the package based on the changes being made, add the changeset as such and it will be discussed during PR review.
 
+## Adding server changes
+
+Changesets only track published npm packages. If your PR only changes server components (`apps/webapp/`, `apps/supervisor/`, `apps/coordinator/`, etc.) with no package changes, add a `.server-changes/` file so the change appears in release notes.
+
+Create a markdown file with a descriptive name:
+
+```sh
+cat > .server-changes/fix-batch-queue-stalls.md << 'EOF'
+---
+area: webapp
+type: fix
+---
+
+Speed up batch queue processing by removing stalls and fixing retry race
+EOF
+```
+
+**Fields:**
+- `area` (required): `webapp` | `supervisor` | `coordinator` | `kubernetes-provider` | `docker-provider`
+- `type` (required): `feature` | `fix` | `improvement` | `breaking`
+
+The body text (below the frontmatter) is a one-line description of the change. Keep it concise — it will appear in release notes.
+
+**When to add which:**
+
+| PR changes | What to add |
+|---|---|
+| Only packages (`packages/`) | Changeset |
+| Only server (`apps/`) | `.server-changes/` file |
+| Both packages and server | Just the changeset |
+
+See `.server-changes/README.md` for more details.
+
 ## Troubleshooting
 
 ### EADDRINUSE: address already in use :::3030

README.md

@@ -4,7 +4,7 @@
 
 ### Build and deploy fully‑managed AI agents and workflows
 
-[Website](https://trigger.dev) | [Docs](https://trigger.dev/docs) | [Issues](https://github.com/triggerdotdev/trigger.dev/issues) | [Feature requests](https://triggerdev.featurebase.app/) | [Public roadmap](https://triggerdev.featurebase.app/roadmap) | [Self-hosting](https://trigger.dev/docs/self-hosting/overview)
+[Website](https://trigger.dev) | [Docs](https://trigger.dev/docs) | [Issues](https://github.com/triggerdotdev/trigger.dev/issues) | [Example projects](https://github.com/triggerdotdev/examples) | [Feature requests](https://triggerdev.featurebase.app/) | [Public roadmap](https://triggerdev.featurebase.app/roadmap) | [Self-hosting](https://trigger.dev/docs/self-hosting/overview) 
 
 [![Open Source](https://img.shields.io/badge/Open%20Source-%E2%9D%A4-red.svg)](https://github.com/triggerdotdev/trigger.dev)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/triggerdotdev/trigger.dev/blob/main/LICENSE)

RELEASE.md

@@ -1,5 +1,28 @@
 ## Guide on releasing a new version
 
+### Automated release (v4+)
+
+Releases are fully automated via CI:
+
+1. PRs merge to `main` with changesets (for package changes) and/or `.server-changes/` files (for server-only changes).
+2. The [changesets-pr.yml](./.github/workflows/changesets-pr.yml) workflow automatically creates/updates the `changeset-release/main` PR with version bumps and an enhanced summary of all changes. Consumed `.server-changes/` files are removed on the release branch (same approach changesets uses for `.changeset/` files — they're deleted on the branch, so merging the PR cleans them up).
+3. When ready to release, merge the changeset release PR into `main`.
+4. The [release.yml](./.github/workflows/release.yml) workflow automatically:
+   - Publishes all packages to npm
+   - Creates a single unified GitHub release (e.g., "trigger.dev v4.3.4")
+   - Tags and triggers Docker image builds
+   - After Docker images are pushed, updates the GitHub release with the exact GHCR tag link
+
+### What engineers need to do
+
+- **Package changes**: Add a changeset with `pnpm run changeset:add`
+- **Server-only changes**: Add a `.server-changes/` file (see `.server-changes/README.md`)
+- **Mixed PRs**: Just the changeset is enough
+
+See `CHANGESETS.md` for full details on changesets and server changes.
+
+### Legacy release (v3)
+
 1. Merge in the changeset PR into main, making sure to cancel both the release and publish github actions from that merge.
 2. Pull the changes locally into main
 3. Run `pnpm i` which will update the pnpm lock file with the new versions

ai/references/migrations.md

@@ -0,0 +1,121 @@
+## Creating and applying migrations
+
+We use prisma migrations to manage the database schema. Please follow the following steps when editing the `internal-packages/database/prisma/schema.prisma` file:
+
+Edit the `schema.prisma` file to add or modify the schema.
+
+Create a new migration file but don't apply it yet:
+
+```bash
+cd internal-packages/database
+pnpm run db:migrate:dev:create --name "add_new_column_to_table"
+```
+
+The migration file will be created in the `prisma/migrations` directory, but it will have a bunch of edits to the schema that are not needed and will need to be removed before we can apply the migration. Here's an example of what the migration file might look like:
+
+```sql
+-- AlterEnum
+ALTER TYPE "public"."TaskRunExecutionStatus" ADD VALUE 'DELAYED';
+
+-- AlterTable
+ALTER TABLE "public"."TaskRun" ADD COLUMN     "debounce" JSONB;
+
+-- AlterTable
+ALTER TABLE "public"."_BackgroundWorkerToBackgroundWorkerFile" ADD CONSTRAINT "_BackgroundWorkerToBackgroundWorkerFile_AB_pkey" PRIMARY KEY ("A", "B");
+
+-- DropIndex
+DROP INDEX "public"."_BackgroundWorkerToBackgroundWorkerFile_AB_unique";
+
+-- AlterTable
+ALTER TABLE "public"."_BackgroundWorkerToTaskQueue" ADD CONSTRAINT "_BackgroundWorkerToTaskQueue_AB_pkey" PRIMARY KEY ("A", "B");
+
+-- DropIndex
+DROP INDEX "public"."_BackgroundWorkerToTaskQueue_AB_unique";
+
+-- AlterTable
+ALTER TABLE "public"."_TaskRunToTaskRunTag" ADD CONSTRAINT "_TaskRunToTaskRunTag_AB_pkey" PRIMARY KEY ("A", "B");
+
+-- DropIndex
+DROP INDEX "public"."_TaskRunToTaskRunTag_AB_unique";
+
+-- AlterTable
+ALTER TABLE "public"."_WaitpointRunConnections" ADD CONSTRAINT "_WaitpointRunConnections_AB_pkey" PRIMARY KEY ("A", "B");
+
+-- DropIndex
+DROP INDEX "public"."_WaitpointRunConnections_AB_unique";
+
+-- AlterTable
+ALTER TABLE "public"."_completedWaitpoints" ADD CONSTRAINT "_completedWaitpoints_AB_pkey" PRIMARY KEY ("A", "B");
+
+-- DropIndex
+DROP INDEX "public"."_completedWaitpoints_AB_unique";
+
+-- CreateIndex
+CREATE INDEX "SecretStore_key_idx" ON "public"."SecretStore"("key" text_pattern_ops);
+
+-- CreateIndex
+CREATE INDEX "TaskRun_runtimeEnvironmentId_id_idx" ON "public"."TaskRun"("runtimeEnvironmentId", "id" DESC);
+
+-- CreateIndex
+CREATE INDEX "TaskRun_runtimeEnvironmentId_createdAt_idx" ON "public"."TaskRun"("runtimeEnvironmentId", "createdAt" DESC);
+```
+
+All the following lines should be removed:
+
+```sql
+-- AlterTable
+ALTER TABLE "public"."_BackgroundWorkerToBackgroundWorkerFile" ADD CONSTRAINT "_BackgroundWorkerToBackgroundWorkerFile_AB_pkey" PRIMARY KEY ("A", "B");
+
+-- DropIndex
+DROP INDEX "public"."_BackgroundWorkerToBackgroundWorkerFile_AB_unique";
+
+-- AlterTable
+ALTER TABLE "public"."_BackgroundWorkerToTaskQueue" ADD CONSTRAINT "_BackgroundWorkerToTaskQueue_AB_pkey" PRIMARY KEY ("A", "B");
+
+-- DropIndex
+DROP INDEX "public"."_BackgroundWorkerToTaskQueue_AB_unique";
+
+-- AlterTable
+ALTER TABLE "public"."_TaskRunToTaskRunTag" ADD CONSTRAINT "_TaskRunToTaskRunTag_AB_pkey" PRIMARY KEY ("A", "B");
+
+-- DropIndex
+DROP INDEX "public"."_TaskRunToTaskRunTag_AB_unique";
+
+-- AlterTable
+ALTER TABLE "public"."_WaitpointRunConnections" ADD CONSTRAINT "_WaitpointRunConnections_AB_pkey" PRIMARY KEY ("A", "B");
+
+-- DropIndex
+DROP INDEX "public"."_WaitpointRunConnections_AB_unique";
+
+-- AlterTable
+ALTER TABLE "public"."_completedWaitpoints" ADD CONSTRAINT "_completedWaitpoints_AB_pkey" PRIMARY KEY ("A", "B");
+
+-- DropIndex
+DROP INDEX "public"."_completedWaitpoints_AB_unique";
+
+-- CreateIndex
+CREATE INDEX "SecretStore_key_idx" ON "public"."SecretStore"("key" text_pattern_ops);
+
+-- CreateIndex
+CREATE INDEX "TaskRun_runtimeEnvironmentId_id_idx" ON "public"."TaskRun"("runtimeEnvironmentId", "id" DESC);
+
+-- CreateIndex
+CREATE INDEX "TaskRun_runtimeEnvironmentId_createdAt_idx" ON "public"."TaskRun"("runtimeEnvironmentId", "createdAt" DESC);
+```
+
+Leaving only this:
+
+```sql
+-- AlterEnum
+ALTER TYPE "public"."TaskRunExecutionStatus" ADD VALUE 'DELAYED';
+
+-- AlterTable
+ALTER TABLE "public"."TaskRun" ADD COLUMN     "debounce" JSONB;
+```
+
+After editing the migration file, apply the migration:
+
+```bash
+cd internal-packages/database
+pnpm run db:migrate:deploy && pnpm run generate
+```

ai/references/repo.md

@@ -1,6 +1,6 @@
 ## Repo Overview
 
-This is a pnpm 8.15.5 monorepo that uses turborepo @turbo.json. The following workspaces are relevant
+This is a pnpm 10.23.0 monorepo that uses turborepo @turbo.json. The following workspaces are relevant
 
 ## Apps
 

apps/coordinator/Containerfile

@@ -35,7 +35,7 @@ COPY --from=pruner --chown=node:node /app/out/full/ .
 COPY --from=dev-deps --chown=node:node /app/ .
 COPY --chown=node:node turbo.json turbo.json
 
-RUN pnpm run -r --filter coordinator build:bundle
+RUN pnpm run -r --filter @trigger.dev/core bundle-vendor && pnpm run -r --filter coordinator build:bundle
 
 FROM alpine AS cri-tools
 

apps/docker-provider/Containerfile

@@ -31,7 +31,7 @@ COPY --from=pruner --chown=node:node /app/out/full/ .
 COPY --from=dev-deps --chown=node:node /app/ .
 COPY --chown=node:node turbo.json turbo.json
 
-RUN pnpm run -r --filter docker-provider build:bundle
+RUN pnpm run -r --filter @trigger.dev/core bundle-vendor && pnpm run -r --filter docker-provider build:bundle
 
 FROM base AS runner
 

apps/kubernetes-provider/Containerfile

@@ -31,7 +31,7 @@ COPY --from=pruner --chown=node:node /app/out/full/ .
 COPY --from=dev-deps --chown=node:node /app/ .
 COPY --chown=node:node turbo.json turbo.json
 
-RUN pnpm run -r --filter kubernetes-provider build:bundle
+RUN pnpm run -r --filter @trigger.dev/core bundle-vendor && pnpm run -r --filter kubernetes-provider build:bundle
 
 FROM base AS runner
 

apps/supervisor/CLAUDE.md

@@ -0,0 +1,20 @@
+# Supervisor
+
+Node.js app that manages task execution containers. Receives work from the platform, starts Docker/Kubernetes containers, monitors execution, and reports results.
+
+## Key Directories
+
+- `src/services/` - Core service logic
+- `src/workloadManager/` - Container orchestration abstraction (Docker or Kubernetes)
+- `src/workloadServer/` - HTTP server for workload communication (heartbeats, snapshots)
+- `src/clients/` - Platform communication (webapp/coordinator)
+- `src/env.ts` - Environment configuration
+
+## Architecture
+
+- **WorkloadManager**: Abstracts Docker vs Kubernetes execution
+- **SupervisorSession**: Manages the dequeue loop with EWMA-based dynamic scaling
+- **ResourceMonitor**: Tracks CPU/memory during execution
+- **PodCleaner/FailedPodHandler**: Kubernetes-specific cleanup
+
+Communicates with the platform via Socket.io and HTTP. Receives task assignments through the dequeue protocol from the webapp.

apps/supervisor/Containerfile

@@ -5,7 +5,7 @@ WORKDIR /app
 FROM node-22-alpine AS pruner
 
 COPY --chown=node:node . .
-RUN npx -q turbo@1.10.9 prune --scope=supervisor --docker
+RUN npx -q turbo@2.5.4 prune --scope=supervisor --docker
 
 FROM node-22-alpine AS base
 
@@ -16,7 +16,7 @@ COPY --from=pruner --chown=node:node /app/out/json/ .
 COPY --from=pruner --chown=node:node /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
 COPY --from=pruner --chown=node:node /app/out/pnpm-workspace.yaml ./pnpm-workspace.yaml
 
-RUN corepack enable && corepack prepare --activate
+RUN corepack enable && corepack prepare pnpm@10.23.0 --activate
 
 FROM base AS deps-fetcher
 RUN apk add --no-cache python3-dev py3-setuptools make g++ gcc linux-headers
@@ -37,7 +37,7 @@ COPY --chown=node:node scripts/updateVersion.ts scripts/updateVersion.ts
 
 RUN pnpm run generate && \
   pnpm run --filter supervisor... build&& \
-  pnpm deploy --filter=supervisor --prod /prod/supervisor
+  pnpm deploy --legacy --filter=supervisor --prod /prod/supervisor
 
 FROM base AS runner
 

apps/supervisor/src/env.ts

@@ -3,117 +3,169 @@ import { env as stdEnv } from "std-env";
 import { z } from "zod";
 import { AdditionalEnvVars, BoolEnv } from "./envUtil.js";
 
-const Env = z.object({
-  // This will come from `spec.nodeName` in k8s
-  TRIGGER_WORKER_INSTANCE_NAME: z.string().default(randomUUID()),
-  TRIGGER_WORKER_HEARTBEAT_INTERVAL_SECONDS: z.coerce.number().default(30),
+const Env = z
+  .object({
+    // This will come from `spec.nodeName` in k8s
+    TRIGGER_WORKER_INSTANCE_NAME: z.string().default(randomUUID()),
+    TRIGGER_WORKER_HEARTBEAT_INTERVAL_SECONDS: z.coerce.number().default(30),
 
-  // Required settings
-  TRIGGER_API_URL: z.string().url(),
-  TRIGGER_WORKER_TOKEN: z.string(), // accepts file:// path to read from a file
-  MANAGED_WORKER_SECRET: z.string(),
-  OTEL_EXPORTER_OTLP_ENDPOINT: z.string().url(), // set on the runners
+    // Required settings
+    TRIGGER_API_URL: z.string().url(),
+    TRIGGER_WORKER_TOKEN: z.string(), // accepts file:// path to read from a file
+    MANAGED_WORKER_SECRET: z.string(),
+    OTEL_EXPORTER_OTLP_ENDPOINT: z.string().url(), // set on the runners
 
-  // Workload API settings (coordinator mode) - the workload API is what the run controller connects to
-  TRIGGER_WORKLOAD_API_ENABLED: BoolEnv.default(true),
-  TRIGGER_WORKLOAD_API_PROTOCOL: z
-    .string()
-    .transform((s) => z.enum(["http", "https"]).parse(s.toLowerCase()))
-    .default("http"),
-  TRIGGER_WORKLOAD_API_DOMAIN: z.string().optional(), // If unset, will use orchestrator-specific default
-  TRIGGER_WORKLOAD_API_HOST_INTERNAL: z.string().default("0.0.0.0"),
-  TRIGGER_WORKLOAD_API_PORT_INTERNAL: z.coerce.number().default(8020), // This is the port the workload API listens on
-  TRIGGER_WORKLOAD_API_PORT_EXTERNAL: z.coerce.number().default(8020), // This is the exposed port passed to the run controller
+    // Workload API settings (coordinator mode) - the workload API is what the run controller connects to
+    TRIGGER_WORKLOAD_API_ENABLED: BoolEnv.default(true),
+    TRIGGER_WORKLOAD_API_PROTOCOL: z
+      .string()
+      .transform((s) => z.enum(["http", "https"]).parse(s.toLowerCase()))
+      .default("http"),
+    TRIGGER_WORKLOAD_API_DOMAIN: z.string().optional(), // If unset, will use orchestrator-specific default
+    TRIGGER_WORKLOAD_API_HOST_INTERNAL: z.string().default("0.0.0.0"),
+    TRIGGER_WORKLOAD_API_PORT_INTERNAL: z.coerce.number().default(8020), // This is the port the workload API listens on
+    TRIGGER_WORKLOAD_API_PORT_EXTERNAL: z.coerce.number().default(8020), // This is the exposed port passed to the run controller
 
-  // Runner settings
-  RUNNER_HEARTBEAT_INTERVAL_SECONDS: z.coerce.number().optional(),
-  RUNNER_SNAPSHOT_POLL_INTERVAL_SECONDS: z.coerce.number().optional(),
-  RUNNER_ADDITIONAL_ENV_VARS: AdditionalEnvVars, // optional (csv)
-  RUNNER_PRETTY_LOGS: BoolEnv.default(false),
+    // Runner settings
+    RUNNER_HEARTBEAT_INTERVAL_SECONDS: z.coerce.number().optional(),
+    RUNNER_SNAPSHOT_POLL_INTERVAL_SECONDS: z.coerce.number().optional(),
+    RUNNER_ADDITIONAL_ENV_VARS: AdditionalEnvVars, // optional (csv)
+    RUNNER_PRETTY_LOGS: BoolEnv.default(false),
 
-  // Dequeue settings (provider mode)
-  TRIGGER_DEQUEUE_ENABLED: BoolEnv.default(true),
-  TRIGGER_DEQUEUE_INTERVAL_MS: z.coerce.number().int().default(250),
-  TRIGGER_DEQUEUE_IDLE_INTERVAL_MS: z.coerce.number().int().default(1000),
-  TRIGGER_DEQUEUE_MAX_RUN_COUNT: z.coerce.number().int().default(1),
-  TRIGGER_DEQUEUE_MIN_CONSUMER_COUNT: z.coerce.number().int().default(1),
-  TRIGGER_DEQUEUE_MAX_CONSUMER_COUNT: z.coerce.number().int().default(10),
-  TRIGGER_DEQUEUE_SCALING_STRATEGY: z.enum(["none", "smooth", "aggressive"]).default("none"),
-  TRIGGER_DEQUEUE_SCALING_UP_COOLDOWN_MS: z.coerce.number().int().default(5000), // 5 seconds
-  TRIGGER_DEQUEUE_SCALING_DOWN_COOLDOWN_MS: z.coerce.number().int().default(30000), // 30 seconds
-  TRIGGER_DEQUEUE_SCALING_TARGET_RATIO: z.coerce.number().default(1.0), // Target ratio of queue items to consumers (1.0 = 1 item per consumer)
-  TRIGGER_DEQUEUE_SCALING_EWMA_ALPHA: z.coerce.number().min(0).max(1).default(0.3), // Smooths queue length measurements (0=historical, 1=current)
-  TRIGGER_DEQUEUE_SCALING_BATCH_WINDOW_MS: z.coerce.number().int().positive().default(1000), // Batch window for metrics processing (ms)
-  TRIGGER_DEQUEUE_SCALING_DAMPING_FACTOR: z.coerce.number().min(0).max(1).default(0.7), // Smooths consumer count changes after EWMA (0=no scaling, 1=immediate)
+    // Dequeue settings (provider mode)
+    TRIGGER_DEQUEUE_ENABLED: BoolEnv.default(true),
+    TRIGGER_DEQUEUE_INTERVAL_MS: z.coerce.number().int().default(250),
+    TRIGGER_DEQUEUE_IDLE_INTERVAL_MS: z.coerce.number().int().default(1000),
+    TRIGGER_DEQUEUE_MAX_RUN_COUNT: z.coerce.number().int().default(1),
+    TRIGGER_DEQUEUE_MIN_CONSUMER_COUNT: z.coerce.number().int().default(1),
+    TRIGGER_DEQUEUE_MAX_CONSUMER_COUNT: z.coerce.number().int().default(10),
+    TRIGGER_DEQUEUE_SCALING_STRATEGY: z.enum(["none", "smooth", "aggressive"]).default("none"),
+    TRIGGER_DEQUEUE_SCALING_UP_COOLDOWN_MS: z.coerce.number().int().default(5000), // 5 seconds
+    TRIGGER_DEQUEUE_SCALING_DOWN_COOLDOWN_MS: z.coerce.number().int().default(30000), // 30 seconds
+    TRIGGER_DEQUEUE_SCALING_TARGET_RATIO: z.coerce.number().default(1.0), // Target ratio of queue items to consumers (1.0 = 1 item per consumer)
+    TRIGGER_DEQUEUE_SCALING_EWMA_ALPHA: z.coerce.number().min(0).max(1).default(0.3), // Smooths queue length measurements (0=historical, 1=current)
+    TRIGGER_DEQUEUE_SCALING_BATCH_WINDOW_MS: z.coerce.number().int().positive().default(1000), // Batch window for metrics processing (ms)
+    TRIGGER_DEQUEUE_SCALING_DAMPING_FACTOR: z.coerce.number().min(0).max(1).default(0.7), // Smooths consumer count changes after EWMA (0=no scaling, 1=immediate)
 
-  // Optional services
-  TRIGGER_WARM_START_URL: z.string().optional(),
-  TRIGGER_CHECKPOINT_URL: z.string().optional(),
-  TRIGGER_METADATA_URL: z.string().optional(),
+    // Optional services
+    TRIGGER_WARM_START_URL: z.string().optional(),
+    TRIGGER_CHECKPOINT_URL: z.string().optional(),
+    TRIGGER_METADATA_URL: z.string().optional(),
 
-  // Used by the resource monitor
-  RESOURCE_MONITOR_ENABLED: BoolEnv.default(false),
-  RESOURCE_MONITOR_OVERRIDE_CPU_TOTAL: z.coerce.number().optional(),
-  RESOURCE_MONITOR_OVERRIDE_MEMORY_TOTAL_GB: z.coerce.number().optional(),
+    // Used by the resource monitor
+    RESOURCE_MONITOR_ENABLED: BoolEnv.default(false),
+    RESOURCE_MONITOR_OVERRIDE_CPU_TOTAL: z.coerce.number().optional(),
+    RESOURCE_MONITOR_OVERRIDE_MEMORY_TOTAL_GB: z.coerce.number().optional(),
 
-  // Docker settings
-  DOCKER_API_VERSION: z.string().optional(),
-  DOCKER_PLATFORM: z.string().optional(), // e.g. linux/amd64, linux/arm64
-  DOCKER_STRIP_IMAGE_DIGEST: BoolEnv.default(true),
-  DOCKER_REGISTRY_USERNAME: z.string().optional(),
-  DOCKER_REGISTRY_PASSWORD: z.string().optional(),
-  DOCKER_REGISTRY_URL: z.string().optional(), // e.g. https://index.docker.io/v1
-  DOCKER_ENFORCE_MACHINE_PRESETS: BoolEnv.default(true),
-  DOCKER_AUTOREMOVE_EXITED_CONTAINERS: BoolEnv.default(true),
-  /**
-   * Network mode to use for all runners. Supported standard values are: `bridge`, `host`, `none`, and `container:<name|id>`.
-   * Any other value is taken as a custom network's name to which all runners should connect to.
-   *
-   * Accepts a list of comma-separated values to attach to multiple networks. Additional networks are interpreted as network names and will be attached after container creation.
-   *
-   * **WARNING**: Specifying multiple networks will slightly increase startup times.
-   *
-   * @default "host"
-   */
-  DOCKER_RUNNER_NETWORKS: z.string().default("host"),
+    // Docker settings
+    DOCKER_API_VERSION: z.string().optional(),
+    DOCKER_PLATFORM: z.string().optional(), // e.g. linux/amd64, linux/arm64
+    DOCKER_STRIP_IMAGE_DIGEST: BoolEnv.default(true),
+    DOCKER_REGISTRY_USERNAME: z.string().optional(),
+    DOCKER_REGISTRY_PASSWORD: z.string().optional(),
+    DOCKER_REGISTRY_URL: z.string().optional(), // e.g. https://index.docker.io/v1
+    DOCKER_ENFORCE_MACHINE_PRESETS: BoolEnv.default(true),
+    DOCKER_AUTOREMOVE_EXITED_CONTAINERS: BoolEnv.default(true),
+    /**
+     * Network mode to use for all runners. Supported standard values are: `bridge`, `host`, `none`, and `container:<name|id>`.
+     * Any other value is taken as a custom network's name to which all runners should connect to.
+     *
+     * Accepts a list of comma-separated values to attach to multiple networks. Additional networks are interpreted as network names and will be attached after container creation.
+     *
+     * **WARNING**: Specifying multiple networks will slightly increase startup times.
+     *
+     * @default "host"
+     */
+    DOCKER_RUNNER_NETWORKS: z.string().default("host"),
 
-  // Kubernetes settings
-  KUBERNETES_FORCE_ENABLED: BoolEnv.default(false),
-  KUBERNETES_NAMESPACE: z.string().default("default"),
-  KUBERNETES_WORKER_NODETYPE_LABEL: z.string().default("v4-worker"),
-  KUBERNETES_IMAGE_PULL_SECRETS: z.string().optional(), // csv
-  KUBERNETES_EPHEMERAL_STORAGE_SIZE_LIMIT: z.string().default("10Gi"),
-  KUBERNETES_EPHEMERAL_STORAGE_SIZE_REQUEST: z.string().default("2Gi"),
-  KUBERNETES_STRIP_IMAGE_DIGEST: BoolEnv.default(false),
-  KUBERNETES_CPU_REQUEST_MIN_CORES: z.coerce.number().min(0).default(0),
-  KUBERNETES_CPU_REQUEST_RATIO: z.coerce.number().min(0).max(1).default(0.75), // Ratio of CPU limit, so 0.75 = 75% of CPU limit
-  KUBERNETES_MEMORY_REQUEST_MIN_GB: z.coerce.number().min(0).default(0),
-  KUBERNETES_MEMORY_REQUEST_RATIO: z.coerce.number().min(0).max(1).default(1), // Ratio of memory limit, so 1 = 100% of memory limit
-  KUBERNETES_MEMORY_OVERHEAD_GB: z.coerce.number().min(0).optional(), // Optional memory overhead to add to the limit in GB
-  KUBERNETES_SCHEDULER_NAME: z.string().optional(), // Custom scheduler name for pods
+    // Compute settings
+    COMPUTE_GATEWAY_URL: z.string().url().optional(),
+    COMPUTE_GATEWAY_AUTH_TOKEN: z.string().optional(),
+    COMPUTE_GATEWAY_TIMEOUT_MS: z.coerce.number().int().default(30_000),
+    COMPUTE_SNAPSHOTS_ENABLED: BoolEnv.default(false),
 
-  // Placement tags settings
-  PLACEMENT_TAGS_ENABLED: BoolEnv.default(false),
-  PLACEMENT_TAGS_PREFIX: z.string().default("node.cluster.x-k8s.io"),
+    // Kubernetes settings
+    KUBERNETES_FORCE_ENABLED: BoolEnv.default(false),
+    KUBERNETES_NAMESPACE: z.string().default("default"),
+    KUBERNETES_WORKER_NODETYPE_LABEL: z.string().default("v4-worker"),
+    KUBERNETES_IMAGE_PULL_SECRETS: z.string().optional(), // csv
+    KUBERNETES_EPHEMERAL_STORAGE_SIZE_LIMIT: z.string().default("10Gi"),
+    KUBERNETES_EPHEMERAL_STORAGE_SIZE_REQUEST: z.string().default("2Gi"),
+    KUBERNETES_STRIP_IMAGE_DIGEST: BoolEnv.default(false),
+    KUBERNETES_CPU_REQUEST_MIN_CORES: z.coerce.number().min(0).default(0),
+    KUBERNETES_CPU_REQUEST_RATIO: z.coerce.number().min(0).max(1).default(0.75), // Ratio of CPU limit, so 0.75 = 75% of CPU limit
+    KUBERNETES_MEMORY_REQUEST_MIN_GB: z.coerce.number().min(0).default(0),
+    KUBERNETES_MEMORY_REQUEST_RATIO: z.coerce.number().min(0).max(1).default(1), // Ratio of memory limit, so 1 = 100% of memory limit
 
-  // Metrics
-  METRICS_ENABLED: BoolEnv.default(true),
-  METRICS_COLLECT_DEFAULTS: BoolEnv.default(true),
-  METRICS_HOST: z.string().default("127.0.0.1"),
-  METRICS_PORT: z.coerce.number().int().default(9090),
+    // Per-preset overrides of the global KUBERNETES_CPU_REQUEST_RATIO
+    KUBERNETES_CPU_REQUEST_RATIO_MICRO: z.coerce.number().min(0).max(1).optional(),
+    KUBERNETES_CPU_REQUEST_RATIO_SMALL_1X: z.coerce.number().min(0).max(1).optional(),
+    KUBERNETES_CPU_REQUEST_RATIO_SMALL_2X: z.coerce.number().min(0).max(1).optional(),
+    KUBERNETES_CPU_REQUEST_RATIO_MEDIUM_1X: z.coerce.number().min(0).max(1).optional(),
+    KUBERNETES_CPU_REQUEST_RATIO_MEDIUM_2X: z.coerce.number().min(0).max(1).optional(),
+    KUBERNETES_CPU_REQUEST_RATIO_LARGE_1X: z.coerce.number().min(0).max(1).optional(),
+    KUBERNETES_CPU_REQUEST_RATIO_LARGE_2X: z.coerce.number().min(0).max(1).optional(),
 
-  // Pod cleaner
-  POD_CLEANER_ENABLED: BoolEnv.default(true),
-  POD_CLEANER_INTERVAL_MS: z.coerce.number().int().default(10000),
-  POD_CLEANER_BATCH_SIZE: z.coerce.number().int().default(500),
+    // Per-preset overrides of the global KUBERNETES_MEMORY_REQUEST_RATIO
+    KUBERNETES_MEMORY_REQUEST_RATIO_MICRO: z.coerce.number().min(0).max(1).optional(),
+    KUBERNETES_MEMORY_REQUEST_RATIO_SMALL_1X: z.coerce.number().min(0).max(1).optional(),
+    KUBERNETES_MEMORY_REQUEST_RATIO_SMALL_2X: z.coerce.number().min(0).max(1).optional(),
+    KUBERNETES_MEMORY_REQUEST_RATIO_MEDIUM_1X: z.coerce.number().min(0).max(1).optional(),
+    KUBERNETES_MEMORY_REQUEST_RATIO_MEDIUM_2X: z.coerce.number().min(0).max(1).optional(),
+    KUBERNETES_MEMORY_REQUEST_RATIO_LARGE_1X: z.coerce.number().min(0).max(1).optional(),
+    KUBERNETES_MEMORY_REQUEST_RATIO_LARGE_2X: z.coerce.number().min(0).max(1).optional(),
 
-  // Failed pod handler
-  FAILED_POD_HANDLER_ENABLED: BoolEnv.default(true),
-  FAILED_POD_HANDLER_RECONNECT_INTERVAL_MS: z.coerce.number().int().default(1000),
+    KUBERNETES_MEMORY_OVERHEAD_GB: z.coerce.number().min(0).optional(), // Optional memory overhead to add to the limit in GB
+    KUBERNETES_SCHEDULER_NAME: z.string().optional(), // Custom scheduler name for pods
+    KUBERNETES_LARGE_MACHINE_POOL_LABEL: z.string().optional(), // if set, large-* presets affinity for machinepool=<value>
 
-  // Debug
-  DEBUG: BoolEnv.default(false),
-  SEND_RUN_DEBUG_LOGS: BoolEnv.default(false),
-});
+    // Project affinity settings - pods from the same project prefer the same node
+    KUBERNETES_PROJECT_AFFINITY_ENABLED: BoolEnv.default(false),
+    KUBERNETES_PROJECT_AFFINITY_WEIGHT: z.coerce.number().int().min(1).max(100).default(50),
+    KUBERNETES_PROJECT_AFFINITY_TOPOLOGY_KEY: z
+      .string()
+      .trim()
+      .min(1)
+      .default("kubernetes.io/hostname"),
+
+    // Placement tags settings
+    PLACEMENT_TAGS_ENABLED: BoolEnv.default(false),
+    PLACEMENT_TAGS_PREFIX: z.string().default("node.cluster.x-k8s.io"),
+
+    // Metrics
+    METRICS_ENABLED: BoolEnv.default(true),
+    METRICS_COLLECT_DEFAULTS: BoolEnv.default(true),
+    METRICS_HOST: z.string().default("127.0.0.1"),
+    METRICS_PORT: z.coerce.number().int().default(9090),
+
+    // Pod cleaner
+    POD_CLEANER_ENABLED: BoolEnv.default(true),
+    POD_CLEANER_INTERVAL_MS: z.coerce.number().int().default(10000),
+    POD_CLEANER_BATCH_SIZE: z.coerce.number().int().default(500),
+
+    // Failed pod handler
+    FAILED_POD_HANDLER_ENABLED: BoolEnv.default(true),
+    FAILED_POD_HANDLER_RECONNECT_INTERVAL_MS: z.coerce.number().int().default(1000),
+
+    // Debug
+    DEBUG: BoolEnv.default(false),
+    SEND_RUN_DEBUG_LOGS: BoolEnv.default(false),
+  })
+  .superRefine((data, ctx) => {
+    if (data.COMPUTE_SNAPSHOTS_ENABLED && !data.TRIGGER_METADATA_URL) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "TRIGGER_METADATA_URL is required when COMPUTE_SNAPSHOTS_ENABLED is true",
+        path: ["TRIGGER_METADATA_URL"],
+      });
+    }
+    if (data.COMPUTE_SNAPSHOTS_ENABLED && !data.TRIGGER_WORKLOAD_API_DOMAIN) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "TRIGGER_WORKLOAD_API_DOMAIN is required when COMPUTE_SNAPSHOTS_ENABLED is true",
+        path: ["TRIGGER_WORKLOAD_API_DOMAIN"],
+      });
+    }
+  });
 
 export const env = Env.parse(stdEnv);

apps/supervisor/src/index.ts

@@ -14,6 +14,7 @@ import {
 } from "./resourceMonitor.js";
 import { KubernetesWorkloadManager } from "./workloadManager/kubernetes.js";
 import { DockerWorkloadManager } from "./workloadManager/docker.js";
+import { ComputeWorkloadManager } from "./workloadManager/compute.js";
 import {
   HttpServer,
   CheckpointClient,
@@ -35,9 +36,11 @@ class ManagedSupervisor {
   private readonly metricsServer?: HttpServer;
   private readonly workloadServer: WorkloadServer;
   private readonly workloadManager: WorkloadManager;
+  private readonly computeManager?: ComputeWorkloadManager;
   private readonly logger = new SimpleStructuredLogger("managed-supervisor");
   private readonly resourceMonitor: ResourceMonitor;
   private readonly checkpointClient?: CheckpointClient;
+  private readonly isComputeMode: boolean;
 
   private readonly podCleaner?: PodCleaner;
   private readonly failedPodHandler?: FailedPodHandler;
@@ -77,9 +80,22 @@ class ManagedSupervisor {
         : new DockerResourceMonitor(new Docker())
       : new NoopResourceMonitor();
 
-    this.workloadManager = this.isKubernetes
-      ? new KubernetesWorkloadManager(workloadManagerOptions)
-      : new DockerWorkloadManager(workloadManagerOptions);
+    this.isComputeMode = !!env.COMPUTE_GATEWAY_URL;
+
+    if (env.COMPUTE_GATEWAY_URL) {
+      const computeManager = new ComputeWorkloadManager({
+        ...workloadManagerOptions,
+        gatewayUrl: env.COMPUTE_GATEWAY_URL,
+        gatewayAuthToken: env.COMPUTE_GATEWAY_AUTH_TOKEN,
+        gatewayTimeoutMs: env.COMPUTE_GATEWAY_TIMEOUT_MS,
+      });
+      this.computeManager = computeManager;
+      this.workloadManager = computeManager;
+    } else {
+      this.workloadManager = this.isKubernetes
+        ? new KubernetesWorkloadManager(workloadManagerOptions)
+        : new DockerWorkloadManager(workloadManagerOptions);
+    }
 
     if (this.isKubernetes) {
       if (env.POD_CLEANER_ENABLED) {
@@ -187,7 +203,7 @@ class ManagedSupervisor {
       this.workloadServer.notifyRun({ run });
     });
 
-    this.workerSession.on("runQueueMessage", async ({ time, message }) => {
+    this.workerSession.on("runQueueMessage", async ({ time, message, dequeueResponseMs, pollingIntervalMs }) => {
       this.logger.log(`Received message with timestamp ${time.toLocaleString()}`, message);
 
       if (message.completedWaitpoints.length > 0) {
@@ -207,6 +223,33 @@ class ManagedSupervisor {
       if (checkpoint) {
         this.logger.log("Restoring run", { runId: message.run.id });
 
+        if (this.isComputeMode && this.computeManager && env.COMPUTE_SNAPSHOTS_ENABLED) {
+          try {
+            // Derive runnerId unique per restore cycle (matches iceman's pattern)
+            const runIdShort = message.run.friendlyId.replace("run_", "");
+            const checkpointSuffix = checkpoint.id.slice(-8);
+            const runnerId = `runner-${runIdShort}-${checkpointSuffix}`;
+
+            const didRestore = await this.computeManager.restore({
+              snapshotId: checkpoint.location,
+              runnerId,
+              runFriendlyId: message.run.friendlyId,
+              snapshotFriendlyId: message.snapshot.friendlyId,
+              machine: message.run.machine,
+            });
+
+            if (didRestore) {
+              this.logger.log("Compute restore successful", { runId: message.run.id, runnerId });
+            } else {
+              this.logger.error("Compute restore failed", { runId: message.run.id, runnerId });
+            }
+          } catch (error) {
+            this.logger.error("Failed to restore run (compute)", { error });
+          }
+
+          return;
+        }
+
         if (!this.checkpointClient) {
           this.logger.error("No checkpoint client", { runId: message.run.id });
           return;
@@ -236,7 +279,9 @@ class ManagedSupervisor {
 
       this.logger.log("Scheduling run", { runId: message.run.id });
 
+      const warmStartStart = performance.now();
       const didWarmStart = await this.tryWarmStart(message);
+      const warmStartCheckMs = Math.round(performance.now() - warmStartStart);
 
       if (didWarmStart) {
         this.logger.log("Warm start successful", { runId: message.run.id });
@@ -244,14 +289,25 @@ class ManagedSupervisor {
       }
 
       try {
+        if (!message.deployment.friendlyId) {
+          // mostly a type guard, deployments always exists for deployed environments
+          // a proper fix would be to use a discriminated union schema to differentiate between dequeued runs in dev and in deployed environments.
+          throw new Error("Deployment is missing");
+        }
+
         await this.workloadManager.create({
           dequeuedAt: message.dequeuedAt,
+          dequeueResponseMs,
+          pollingIntervalMs,
+          warmStartCheckMs,
           envId: message.environment.id,
           envType: message.environment.type,
           image: message.image,
           machine: message.run.machine,
           orgId: message.organization.id,
           projectId: message.project.id,
+          deploymentFriendlyId: message.deployment.friendlyId,
+          deploymentVersion: message.backgroundWorker.version,
           runId: message.run.id,
           runFriendlyId: message.run.friendlyId,
           version: message.version,
@@ -288,6 +344,7 @@ class ManagedSupervisor {
       host: env.TRIGGER_WORKLOAD_API_HOST_INTERNAL,
       workerClient: this.workerSession.httpClient,
       checkpointClient: this.checkpointClient,
+      computeManager: this.computeManager,
     });
 
     this.workloadServer.on("runConnected", this.onRunConnected.bind(this));

apps/supervisor/src/workloadManager/compute.ts

@@ -0,0 +1,311 @@
+import { SimpleStructuredLogger } from "@trigger.dev/core/v3/utils/structuredLogger";
+import {
+  type WorkloadManager,
+  type WorkloadManagerCreateOptions,
+  type WorkloadManagerOptions,
+} from "./types.js";
+import { env } from "../env.js";
+import { getRunnerId } from "../util.js";
+import { tryCatch } from "@trigger.dev/core";
+
+type ComputeWorkloadManagerOptions = WorkloadManagerOptions & {
+  gatewayUrl: string;
+  gatewayAuthToken?: string;
+  gatewayTimeoutMs: number;
+};
+
+export class ComputeWorkloadManager implements WorkloadManager {
+  private readonly logger = new SimpleStructuredLogger("compute-workload-manager");
+
+  constructor(private opts: ComputeWorkloadManagerOptions) {
+    if (opts.workloadApiDomain) {
+      this.logger.warn("⚠️ Custom workload API domain", {
+        domain: opts.workloadApiDomain,
+      });
+    }
+  }
+
+  async create(opts: WorkloadManagerCreateOptions) {
+    const runnerId = getRunnerId(opts.runFriendlyId, opts.nextAttemptNumber);
+
+    const envVars: Record<string, string> = {
+      OTEL_EXPORTER_OTLP_ENDPOINT: env.OTEL_EXPORTER_OTLP_ENDPOINT,
+      TRIGGER_DEQUEUED_AT_MS: String(opts.dequeuedAt.getTime()),
+      TRIGGER_POD_SCHEDULED_AT_MS: String(Date.now()),
+      TRIGGER_ENV_ID: opts.envId,
+      TRIGGER_DEPLOYMENT_ID: opts.deploymentFriendlyId,
+      TRIGGER_DEPLOYMENT_VERSION: opts.deploymentVersion,
+      TRIGGER_RUN_ID: opts.runFriendlyId,
+      TRIGGER_SNAPSHOT_ID: opts.snapshotFriendlyId,
+      TRIGGER_SUPERVISOR_API_PROTOCOL: this.opts.workloadApiProtocol,
+      TRIGGER_SUPERVISOR_API_PORT: String(this.opts.workloadApiPort),
+      TRIGGER_SUPERVISOR_API_DOMAIN: this.opts.workloadApiDomain ?? "",
+      TRIGGER_WORKER_INSTANCE_NAME: env.TRIGGER_WORKER_INSTANCE_NAME,
+      TRIGGER_RUNNER_ID: runnerId,
+      TRIGGER_MACHINE_CPU: String(opts.machine.cpu),
+      TRIGGER_MACHINE_MEMORY: String(opts.machine.memory),
+      PRETTY_LOGS: String(env.RUNNER_PRETTY_LOGS),
+    };
+
+    if (this.opts.warmStartUrl) {
+      envVars.TRIGGER_WARM_START_URL = this.opts.warmStartUrl;
+    }
+
+    if (env.COMPUTE_SNAPSHOTS_ENABLED && this.opts.metadataUrl) {
+      envVars.TRIGGER_METADATA_URL = this.opts.metadataUrl;
+    }
+
+    if (this.opts.heartbeatIntervalSeconds) {
+      envVars.TRIGGER_HEARTBEAT_INTERVAL_SECONDS = String(this.opts.heartbeatIntervalSeconds);
+    }
+
+    if (this.opts.snapshotPollIntervalSeconds) {
+      envVars.TRIGGER_SNAPSHOT_POLL_INTERVAL_SECONDS = String(
+        this.opts.snapshotPollIntervalSeconds
+      );
+    }
+
+    if (this.opts.additionalEnvVars) {
+      Object.assign(envVars, this.opts.additionalEnvVars);
+    }
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    if (this.opts.gatewayAuthToken) {
+      headers["Authorization"] = `Bearer ${this.opts.gatewayAuthToken}`;
+    }
+
+    // Strip image digest — resolve by tag, not digest
+    const imageRef = opts.image.split("@")[0]!;
+
+    const url = `${this.opts.gatewayUrl}/api/instances`;
+
+    // Wide event: single canonical log line emitted in finally
+    const event: Record<string, unknown> = {
+      // High-cardinality identifiers
+      runId: opts.runFriendlyId,
+      runnerId,
+      envId: opts.envId,
+      envType: opts.envType,
+      orgId: opts.orgId,
+      projectId: opts.projectId,
+      deploymentVersion: opts.deploymentVersion,
+      machine: opts.machine.name,
+      // Environment
+      instanceName: env.TRIGGER_WORKER_INSTANCE_NAME,
+      // Supervisor timing
+      dequeueResponseMs: opts.dequeueResponseMs,
+      pollingIntervalMs: opts.pollingIntervalMs,
+      warmStartCheckMs: opts.warmStartCheckMs,
+      // Request
+      image: imageRef,
+      url,
+    };
+
+    const startMs = performance.now();
+
+    try {
+      const [fetchError, response] = await tryCatch(
+        fetch(url, {
+          method: "POST",
+          headers,
+          signal: AbortSignal.timeout(this.opts.gatewayTimeoutMs),
+          body: JSON.stringify({
+            name: runnerId,
+            image: imageRef,
+            env: envVars,
+            cpu: opts.machine.cpu,
+            memory_gb: opts.machine.memory,
+            metadata: {
+              runId: opts.runFriendlyId,
+              envId: opts.envId,
+              envType: opts.envType,
+              orgId: opts.orgId,
+              projectId: opts.projectId,
+              deploymentVersion: opts.deploymentVersion,
+              machine: opts.machine.name,
+            },
+          }),
+        })
+      );
+
+      if (fetchError) {
+        event.error = fetchError instanceof Error ? fetchError.message : String(fetchError);
+        event.errorType =
+          fetchError instanceof DOMException && fetchError.name === "TimeoutError"
+            ? "timeout"
+            : "fetch";
+        return;
+      }
+
+      event.status = response.status;
+
+      if (!response.ok) {
+        const [bodyError, body] = await tryCatch(response.text());
+        event.responseBody = bodyError ? undefined : body;
+        return;
+      }
+
+      const [parseError, data] = await tryCatch(response.json());
+
+      if (parseError) {
+        event.error = parseError instanceof Error ? parseError.message : String(parseError);
+        event.errorType = "parse";
+        return;
+      }
+
+      event.instanceId = data.id;
+      event.ok = true;
+    } finally {
+      event.durationMs = Math.round(performance.now() - startMs);
+      event.ok ??= false;
+      this.logger.info("create instance", event);
+    }
+  }
+
+  private get authHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (this.opts.gatewayAuthToken) {
+      headers["Authorization"] = `Bearer ${this.opts.gatewayAuthToken}`;
+    }
+    return headers;
+  }
+
+  async snapshot(opts: {
+    runnerId: string;
+    callbackUrl: string;
+    metadata: Record<string, string>;
+  }): Promise<boolean> {
+    const url = `${this.opts.gatewayUrl}/api/instances/${opts.runnerId}/snapshot`;
+
+    const [error, response] = await tryCatch(
+      fetch(url, {
+        method: "POST",
+        headers: this.authHeaders,
+        signal: AbortSignal.timeout(this.opts.gatewayTimeoutMs),
+        body: JSON.stringify({
+          callback: {
+            url: opts.callbackUrl,
+            metadata: opts.metadata,
+          },
+        }),
+      })
+    );
+
+    if (error) {
+      this.logger.error("snapshot request failed", {
+        runnerId: opts.runnerId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return false;
+    }
+
+    if (response.status !== 202) {
+      this.logger.error("snapshot request rejected", {
+        runnerId: opts.runnerId,
+        status: response.status,
+      });
+      return false;
+    }
+
+    this.logger.info("snapshot request accepted", { runnerId: opts.runnerId });
+    return true;
+  }
+
+  async deleteInstance(runnerId: string): Promise<boolean> {
+    const url = `${this.opts.gatewayUrl}/api/instances/${runnerId}`;
+
+    const [error, response] = await tryCatch(
+      fetch(url, {
+        method: "DELETE",
+        headers: this.authHeaders,
+        signal: AbortSignal.timeout(this.opts.gatewayTimeoutMs),
+      })
+    );
+
+    if (error) {
+      this.logger.error("delete instance failed", {
+        runnerId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return false;
+    }
+
+    if (!response.ok) {
+      this.logger.error("delete instance rejected", {
+        runnerId,
+        status: response.status,
+      });
+      return false;
+    }
+
+    this.logger.info("delete instance success", { runnerId });
+    return true;
+  }
+
+  async restore(opts: {
+    snapshotId: string;
+    runnerId: string;
+    runFriendlyId: string;
+    snapshotFriendlyId: string;
+    machine: { cpu: number; memory: number };
+  }): Promise<boolean> {
+    const url = `${this.opts.gatewayUrl}/api/snapshots/${opts.snapshotId}/restore`;
+
+    const metadata: Record<string, string> = {
+      TRIGGER_RUNNER_ID: opts.runnerId,
+      TRIGGER_RUN_ID: opts.runFriendlyId,
+      TRIGGER_SNAPSHOT_ID: opts.snapshotFriendlyId,
+      TRIGGER_SUPERVISOR_API_PROTOCOL: this.opts.workloadApiProtocol,
+      TRIGGER_SUPERVISOR_API_PORT: String(this.opts.workloadApiPort),
+      TRIGGER_SUPERVISOR_API_DOMAIN: this.opts.workloadApiDomain ?? "",
+      TRIGGER_WORKER_INSTANCE_NAME: env.TRIGGER_WORKER_INSTANCE_NAME,
+    };
+
+    const body = {
+      name: opts.runnerId,
+      metadata,
+      cpu: opts.machine.cpu,
+      memory_mb: opts.machine.memory * 1024,
+    };
+
+    this.logger.debug("restore request body", { url, body });
+
+    const [error, response] = await tryCatch(
+      fetch(url, {
+        method: "POST",
+        headers: this.authHeaders,
+        signal: AbortSignal.timeout(this.opts.gatewayTimeoutMs),
+        body: JSON.stringify(body),
+      })
+    );
+
+    if (error) {
+      this.logger.error("restore request failed", {
+        snapshotId: opts.snapshotId,
+        runnerId: opts.runnerId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return false;
+    }
+
+    if (!response.ok) {
+      this.logger.error("restore request rejected", {
+        snapshotId: opts.snapshotId,
+        runnerId: opts.runnerId,
+        status: response.status,
+      });
+      return false;
+    }
+
+    this.logger.info("restore request success", {
+      snapshotId: opts.snapshotId,
+      runnerId: opts.runnerId,
+    });
+    return true;
+  }
+}

apps/supervisor/src/workloadManager/docker.ts

@@ -72,6 +72,8 @@ export class DockerWorkloadManager implements WorkloadManager {
       `TRIGGER_DEQUEUED_AT_MS=${opts.dequeuedAt.getTime()}`,
       `TRIGGER_POD_SCHEDULED_AT_MS=${Date.now()}`,
       `TRIGGER_ENV_ID=${opts.envId}`,
+      `TRIGGER_DEPLOYMENT_ID=${opts.deploymentFriendlyId}`,
+      `TRIGGER_DEPLOYMENT_VERSION=${opts.deploymentVersion}`,
       `TRIGGER_RUN_ID=${opts.runFriendlyId}`,
       `TRIGGER_SNAPSHOT_ID=${opts.snapshotFriendlyId}`,
       `TRIGGER_SUPERVISOR_API_PROTOCOL=${this.opts.workloadApiProtocol}`,

apps/supervisor/src/workloadManager/kubernetes.ts

@@ -4,7 +4,12 @@ import {
   type WorkloadManagerCreateOptions,
   type WorkloadManagerOptions,
 } from "./types.js";
-import type { EnvironmentType, MachinePreset, PlacementTag } from "@trigger.dev/core/v3";
+import type {
+  EnvironmentType,
+  MachinePreset,
+  MachinePresetName,
+  PlacementTag,
+} from "@trigger.dev/core/v3";
 import { PlacementTagProcessor } from "@trigger.dev/core/v3/serverOnly";
 import { env } from "../env.js";
 import { type K8sApi, createK8sApi, type k8s } from "../clients/kubernetes.js";
@@ -14,6 +19,26 @@ type ResourceQuantities = {
   [K in "cpu" | "memory" | "ephemeral-storage"]?: string;
 };
 
+const cpuRequestRatioByMachinePreset: Record<MachinePresetName, number | undefined> = {
+  micro: env.KUBERNETES_CPU_REQUEST_RATIO_MICRO,
+  "small-1x": env.KUBERNETES_CPU_REQUEST_RATIO_SMALL_1X,
+  "small-2x": env.KUBERNETES_CPU_REQUEST_RATIO_SMALL_2X,
+  "medium-1x": env.KUBERNETES_CPU_REQUEST_RATIO_MEDIUM_1X,
+  "medium-2x": env.KUBERNETES_CPU_REQUEST_RATIO_MEDIUM_2X,
+  "large-1x": env.KUBERNETES_CPU_REQUEST_RATIO_LARGE_1X,
+  "large-2x": env.KUBERNETES_CPU_REQUEST_RATIO_LARGE_2X,
+};
+
+const memoryRequestRatioByMachinePreset: Record<MachinePresetName, number | undefined> = {
+  micro: env.KUBERNETES_MEMORY_REQUEST_RATIO_MICRO,
+  "small-1x": env.KUBERNETES_MEMORY_REQUEST_RATIO_SMALL_1X,
+  "small-2x": env.KUBERNETES_MEMORY_REQUEST_RATIO_SMALL_2X,
+  "medium-1x": env.KUBERNETES_MEMORY_REQUEST_RATIO_MEDIUM_1X,
+  "medium-2x": env.KUBERNETES_MEMORY_REQUEST_RATIO_MEDIUM_2X,
+  "large-1x": env.KUBERNETES_MEMORY_REQUEST_RATIO_LARGE_1X,
+  "large-2x": env.KUBERNETES_MEMORY_REQUEST_RATIO_LARGE_2X,
+};
+
 export class KubernetesWorkloadManager implements WorkloadManager {
   private readonly logger = new SimpleStructuredLogger("kubernetes-workload-provider");
   private k8s: K8sApi;
@@ -95,6 +120,7 @@ export class KubernetesWorkloadManager implements WorkloadManager {
           },
           spec: {
             ...this.addPlacementTags(this.#defaultPodSpec, opts.placementTags),
+            affinity: this.#getAffinity(opts.machine, opts.projectId),
             terminationGracePeriodSeconds: 60 * 60,
             containers: [
               {
@@ -123,6 +149,14 @@ export class KubernetesWorkloadManager implements WorkloadManager {
                     name: "TRIGGER_ENV_ID",
                     value: opts.envId,
                   },
+                  {
+                    name: "TRIGGER_DEPLOYMENT_ID",
+                    value: opts.deploymentFriendlyId,
+                  },
+                  {
+                    name: "TRIGGER_DEPLOYMENT_VERSION",
+                    value: opts.deploymentVersion,
+                  },
                   {
                     name: "TRIGGER_SNAPSHOT_ID",
                     value: opts.snapshotFriendlyId,
@@ -312,8 +346,11 @@ export class KubernetesWorkloadManager implements WorkloadManager {
   }
 
   #getResourceRequestsForMachine(preset: MachinePreset): ResourceQuantities {
-    const cpuRequest = preset.cpu * this.cpuRequestRatio;
-    const memoryRequest = preset.memory * this.memoryRequestRatio;
+    const cpuRatio = cpuRequestRatioByMachinePreset[preset.name] ?? this.cpuRequestRatio;
+    const memoryRatio = memoryRequestRatioByMachinePreset[preset.name] ?? this.memoryRequestRatio;
+
+    const cpuRequest = preset.cpu * cpuRatio;
+    const memoryRequest = preset.memory * memoryRatio;
 
     // Clamp between min and max
     const clampedCpu = this.clamp(cpuRequest, this.cpuRequestMinCores, preset.cpu);
@@ -348,4 +385,91 @@ export class KubernetesWorkloadManager implements WorkloadManager {
       },
     };
   }
+
+  #isLargeMachine(preset: MachinePreset): boolean {
+    return preset.name.startsWith("large-");
+  }
+
+  #getAffinity(preset: MachinePreset, projectId: string): k8s.V1Affinity | undefined {
+    const nodeAffinity = this.#getNodeAffinityRules(preset);
+    const podAffinity = this.#getProjectPodAffinity(projectId);
+
+    if (!nodeAffinity && !podAffinity) {
+      return undefined;
+    }
+
+    return {
+      ...(nodeAffinity && { nodeAffinity }),
+      ...(podAffinity && { podAffinity }),
+    };
+  }
+
+  #getNodeAffinityRules(preset: MachinePreset): k8s.V1NodeAffinity | undefined {
+    if (!env.KUBERNETES_LARGE_MACHINE_POOL_LABEL) {
+      return undefined;
+    }
+
+    if (this.#isLargeMachine(preset)) {
+      // soft preference for the large-machine pool, falls back to standard if unavailable
+      return {
+        preferredDuringSchedulingIgnoredDuringExecution: [
+          {
+            weight: 100,
+            preference: {
+              matchExpressions: [
+                {
+                  key: "node.cluster.x-k8s.io/machinepool",
+                  operator: "In",
+                  values: [env.KUBERNETES_LARGE_MACHINE_POOL_LABEL],
+                },
+              ],
+            },
+          },
+        ],
+      };
+    }
+
+    // not schedulable in the large-machine pool
+    return {
+      requiredDuringSchedulingIgnoredDuringExecution: {
+        nodeSelectorTerms: [
+          {
+            matchExpressions: [
+              {
+                key: "node.cluster.x-k8s.io/machinepool",
+                operator: "NotIn",
+                values: [env.KUBERNETES_LARGE_MACHINE_POOL_LABEL],
+              },
+            ],
+          },
+        ],
+      },
+    };
+  }
+
+  #getProjectPodAffinity(projectId: string): k8s.V1PodAffinity | undefined {
+    if (!env.KUBERNETES_PROJECT_AFFINITY_ENABLED) {
+      return undefined;
+    }
+
+    return {
+      preferredDuringSchedulingIgnoredDuringExecution: [
+        {
+          weight: env.KUBERNETES_PROJECT_AFFINITY_WEIGHT,
+          podAffinityTerm: {
+            labelSelector: {
+              matchExpressions: [
+                {
+                  key: "project",
+                  operator: "In",
+                  values: [projectId],
+                },
+              ],
+            },
+            topologyKey: env.KUBERNETES_PROJECT_AFFINITY_TOPOLOGY_KEY,
+          },
+        },
+      ],
+    };
+  }
 }

apps/supervisor/src/workloadManager/types.ts

@@ -24,11 +24,17 @@ export interface WorkloadManagerCreateOptions {
   nextAttemptNumber?: number;
   dequeuedAt: Date;
   placementTags?: PlacementTag[];
+  // Timing context (populated by supervisor handler, included in wide event)
+  dequeueResponseMs?: number;
+  pollingIntervalMs?: number;
+  warmStartCheckMs?: number;
   // identifiers
   envId: string;
   envType: EnvironmentType;
   orgId: string;
   projectId: string;
+  deploymentFriendlyId: string;
+  deploymentVersion: string;
   runId: string;
   runFriendlyId: string;
   snapshotId: string;

apps/supervisor/src/workloadServer/index.ts

@@ -24,6 +24,7 @@ import { HttpServer, type CheckpointClient } from "@trigger.dev/core/v3/serverOn
 import { type IncomingMessage } from "node:http";
 import { register } from "../metrics.js";
 import { env } from "../env.js";
+import type { ComputeWorkloadManager } from "../workloadManager/compute.js";
 
 // Use the official export when upgrading to socket.io@4.8.0
 interface DefaultEventsMap {
@@ -53,15 +54,25 @@ type WorkloadServerEvents = {
   ];
 };
 
+const ComputeSnapshotCallbackBody = z.object({
+  snapshot_id: z.string(),
+  instance_id: z.string(),
+  status: z.enum(["completed", "failed"]),
+  error: z.string().optional(),
+  metadata: z.record(z.string()).optional(),
+});
+
 type WorkloadServerOptions = {
   port: number;
   host?: string;
   workerClient: SupervisorHttpClient;
   checkpointClient?: CheckpointClient;
+  computeManager?: ComputeWorkloadManager;
 };
 
 export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
   private checkpointClient?: CheckpointClient;
+  private computeManager?: ComputeWorkloadManager;
 
   private readonly logger = new SimpleStructuredLogger("workload-server");
 
@@ -93,6 +104,7 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
 
     this.workerClient = opts.workerClient;
     this.checkpointClient = opts.checkpointClient;
+    this.computeManager = opts.computeManager;
 
     this.httpServer = this.createHttpServer({ host, port });
     this.websocketServer = this.createWebsocketServer();
@@ -231,18 +243,6 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
           handler: async ({ reply, params, req }) => {
             this.logger.debug("Suspend request", { params, headers: req.headers });
 
-            if (!this.checkpointClient) {
-              reply.json(
-                {
-                  ok: false,
-                  error: "Checkpoints disabled",
-                } satisfies WorkloadSuspendRunResponseBody,
-                false,
-                400
-              );
-              return;
-            }
-
             const runnerId = this.runnerIdFromRequest(req);
             const deploymentVersion = this.deploymentVersionFromRequest(req);
             const projectRef = this.projectRefFromRequest(req);
@@ -263,6 +263,48 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
               return;
             }
 
+            if (this.computeManager && env.COMPUTE_SNAPSHOTS_ENABLED) {
+              if (!env.TRIGGER_WORKLOAD_API_DOMAIN) {
+                this.logger.error(
+                  "TRIGGER_WORKLOAD_API_DOMAIN is not set, cannot create snapshot callback URL"
+                );
+                reply.json({ error: "Snapshot callbacks not configured" }, false, 500);
+                return;
+              }
+
+              // Compute mode: fire-and-forget snapshot with callback
+              reply.json({ ok: true } satisfies WorkloadSuspendRunResponseBody, false, 202);
+
+              const callbackUrl = `${env.TRIGGER_WORKLOAD_API_PROTOCOL}://${env.TRIGGER_WORKLOAD_API_DOMAIN}:${env.TRIGGER_WORKLOAD_API_PORT_EXTERNAL}/api/v1/compute/snapshot-complete`;
+
+              const snapshotResult = await this.computeManager.snapshot({
+                runnerId,
+                callbackUrl,
+                metadata: {
+                  runId: params.runFriendlyId,
+                  snapshotFriendlyId: params.snapshotFriendlyId,
+                },
+              });
+
+              if (!snapshotResult) {
+                this.logger.error("Failed to request compute snapshot", { params, runnerId });
+              }
+
+              return;
+            }
+
+            if (!this.checkpointClient) {
+              reply.json(
+                {
+                  ok: false,
+                  error: "Checkpoints disabled",
+                } satisfies WorkloadSuspendRunResponseBody,
+                false,
+                400
+              );
+              return;
+            }
+
             reply.json(
               {
                 ok: true,
@@ -394,6 +436,76 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
       });
     }
 
+    // Compute snapshot callback endpoint
+    httpServer.route("/api/v1/compute/snapshot-complete", "POST", {
+      bodySchema: ComputeSnapshotCallbackBody,
+      handler: async ({ reply, body }) => {
+        this.logger.info("Compute snapshot callback", {
+          snapshotId: body.snapshot_id,
+          instanceId: body.instance_id,
+          status: body.status,
+          error: body.error,
+          metadata: body.metadata,
+        });
+
+        const runId = body.metadata?.runId;
+        const snapshotFriendlyId = body.metadata?.snapshotFriendlyId;
+
+        if (!runId || !snapshotFriendlyId) {
+          this.logger.error("Compute snapshot callback missing metadata", { body });
+          reply.empty(400);
+          return;
+        }
+
+        if (body.status === "completed") {
+          const result = await this.workerClient.submitSuspendCompletion({
+            runId,
+            snapshotId: snapshotFriendlyId,
+            body: {
+              success: true,
+              checkpoint: {
+                type: "KUBERNETES",
+                location: body.snapshot_id,
+              },
+            },
+          });
+
+          if (result.success) {
+            this.logger.info("Suspend completion submitted", {
+              runId,
+              instanceId: body.instance_id,
+              snapshotId: body.snapshot_id,
+            });
+          } else {
+            this.logger.error("Failed to submit suspend completion", {
+              runId,
+              snapshotFriendlyId,
+              error: result.error,
+            });
+          }
+        } else {
+          const result = await this.workerClient.submitSuspendCompletion({
+            runId,
+            snapshotId: snapshotFriendlyId,
+            body: {
+              success: false,
+              error: body.error ?? "Snapshot failed",
+            },
+          });
+
+          if (!result.success) {
+            this.logger.error("Failed to submit suspend failure", {
+              runId,
+              snapshotFriendlyId,
+              error: result.error,
+            });
+          }
+        }
+
+        reply.empty(200);
+      },
+    });
+
     return httpServer;
   }
 

apps/webapp/CLAUDE.md

@@ -0,0 +1,58 @@
+# Webapp
+
+Remix 2.1.0 app serving as the main API, dashboard, and orchestration engine. Uses an Express server (`server.ts`).
+
+## Key File Locations
+
+- **Trigger API**: `app/routes/api.v1.tasks.$taskId.trigger.ts`
+- **Batch trigger**: `app/routes/api.v1.tasks.batch.ts`
+- **OTEL endpoints**: `app/routes/otel.v1.logs.ts`, `app/routes/otel.v1.traces.ts`
+- **Prisma setup**: `app/db.server.ts`
+- **Run engine config**: `app/v3/runEngine.server.ts`
+- **Services**: `app/v3/services/**/*.server.ts`
+- **Presenters**: `app/v3/presenters/**/*.server.ts`
+
+## Route Convention
+
+Routes use Remix flat-file convention with dot-separated segments:
+`api.v1.tasks.$taskId.trigger.ts` -> `/api/v1/tasks/:taskId/trigger`
+
+## Environment Variables
+
+Access via `env` export from `app/env.server.ts`. **Never use `process.env` directly.**
+
+For testable code, **never import env.server.ts** in test files. Pass configuration as options instead:
+- `realtimeClient.server.ts` (testable service, takes config as constructor arg)
+- `realtimeClientGlobal.server.ts` (creates singleton with env config)
+
+## Run Engine 2.0
+
+The webapp integrates `@internal/run-engine` via `app/v3/runEngine.server.ts`. This is the singleton engine instance. Services in `app/v3/services/` call engine methods for all run lifecycle operations (triggering, completing, cancelling, etc.).
+
+The `engineVersion.server.ts` file determines V1 vs V2 for a given environment. New code should always target V2.
+
+## Background Workers
+
+Background job workers use `@trigger.dev/redis-worker`:
+- `app/v3/commonWorker.server.ts`
+- `app/v3/alertsWorker.server.ts`
+- `app/v3/batchTriggerWorker.server.ts`
+
+Do NOT add new jobs using zodworker/graphile-worker (legacy).
+
+## Real-time
+
+- Socket.io: `app/v3/handleSocketIo.server.ts`, `app/v3/handleWebsockets.server.ts`
+- Electric SQL: Powers real-time data sync for the dashboard
+
+## Legacy V1 Code
+
+The `app/v3/` directory name is misleading - most code is actively used by V2. Only these specific files are V1-only legacy:
+- `app/v3/marqs/` (old MarQS queue system)
+- `app/v3/legacyRunEngineWorker.server.ts`
+- `app/v3/services/triggerTaskV1.server.ts`
+- `app/v3/services/cancelTaskRunV1.server.ts`
+- `app/v3/authenticatedSocketConnection.server.ts`
+- `app/v3/sharedSocketConnection.ts`
+
+Some services (e.g., `cancelTaskRun.server.ts`, `batchTriggerV3.server.ts`) branch on `RunEngineVersion` to support both V1 and V2. When editing these, only modify V2 code paths.

apps/webapp/app/assets/icons/AbacusIcon.tsx

@@ -0,0 +1,71 @@
+export function AbacusIcon({ className }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <g clipPath="url(#clip0_16909_120578)">
+        <path
+          d="M4 3V21"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+        <path
+          d="M20 21V3"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+        <path
+          d="M8 5L8 6"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+        <path
+          d="M14 5L14 6"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+        <path
+          d="M15 10L15 11"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+        <path
+          d="M9 10L9 11"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+        <path
+          d="M12 15L12 16"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+        <path
+          d="M8 15L8 16"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+        <path
+          d="M3 21H21"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+      </g>
+    </svg>
+  );
+}

apps/webapp/app/assets/icons/ArrowTopRightBottomLeftIcon.tsx

@@ -0,0 +1,22 @@
+export function ArrowTopRightBottomLeftIcon({ className }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <path
+        d="M14.8258 10.5L20.125 5.20083V8.5625C20.125 9.08027 20.5447 9.5 21.0625 9.5C21.5803 9.5 22 9.08027 22 8.5625V2.9375C22 2.41973 21.5803 2 21.0625 2H15.4375C14.9197 2 14.5 2.41973 14.5 2.9375C14.5 3.45527 14.9197 3.875 15.4375 3.875H18.7992L13.5 9.17417C13.1339 9.54029 13.1339 10.1339 13.5 10.5C13.8661 10.8661 14.4597 10.8661 14.8258 10.5Z"
+        fill="currentColor"
+      />
+      <path
+        d="M2 21.0625V15.4375C2 14.9197 2.41973 14.5 2.9375 14.5C3.45527 14.5 3.875 14.9197 3.875 15.4375V18.7992L9.17417 13.5C9.54029 13.1339 10.1339 13.1339 10.5 13.5C10.8661 13.8661 10.8661 14.4597 10.5 14.8258L5.20083 20.125H8.5625C9.08027 20.125 9.5 20.5447 9.5 21.0625C9.5 21.5803 9.08027 22 8.5625 22H2.9375C2.69757 22 2.45765 21.9085 2.27459 21.7254C2.1847 21.6355 2.11689 21.5319 2.07114 21.4214C2.0253 21.3108 2 21.1896 2 21.0625Z"
+        fill="currentColor"
+      />
+      <path
+        d="M14.8258 10.5L20.125 5.20083V10C20.125 10.5178 20.5447 10.9375 21.0625 10.9375C21.5803 10.9375 22 10.5178 22 10V2.9375C22 2.41973 21.5803 2 21.0625 2H14C13.4822 2 13.0625 2.41973 13.0625 2.9375C13.0625 3.45527 13.4822 3.875 14 3.875H18.7992L13.5 9.17417C13.1339 9.54029 13.1339 10.1339 13.5 10.5C13.8661 10.8661 14.4597 10.8661 14.8258 10.5Z"
+        fill="currentColor"
+      />
+      <path
+        d="M2 21.0625V13.9375C2 13.4197 2.41973 13 2.9375 13C3.45527 13 3.875 13.4197 3.875 13.9375V18.7992L9.17417 13.5C9.54029 13.1339 10.1339 13.1339 10.5 13.5C10.8661 13.8661 10.8661 14.4597 10.5 14.8258L5.20083 20.125H10.0625C10.5803 20.125 11 20.5447 11 21.0625C11 21.5803 10.5803 22 10.0625 22H2.9375C2.69757 22 2.45765 21.9085 2.27459 21.7254C2.1847 21.6355 2.11689 21.5319 2.07114 21.4214C2.0253 21.3108 2 21.1896 2 21.0625Z"
+        fill="currentColor"
+      />
+    </svg>
+  );
+}

apps/webapp/app/assets/icons/ChevronExtraSmallDown.tsx

@@ -0,0 +1,13 @@
+export function ChevronExtraSmallDown({ className }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 18 18" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <path
+        d="M15 6L9.75926 12.1142C9.36016 12.5798 8.63984 12.5798 8.24074 12.1142L3 6"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeMiterlimit="1.00244"
+        strokeLinecap="round"
+      />
+    </svg>
+  );
+}

apps/webapp/app/assets/icons/ChevronExtraSmallUp.tsx

@@ -0,0 +1,13 @@
+export function ChevronExtraSmallUp({ className }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 18 18" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <path
+        d="M3 12L8.24074 5.8858C8.63984 5.42019 9.36016 5.42019 9.75926 5.8858L15 12"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeMiterlimit="1.00244"
+        strokeLinecap="round"
+      />
+    </svg>
+  );
+}

apps/webapp/app/assets/icons/LogsIcon.tsx

@@ -0,0 +1,66 @@
+export function LogsIcon({ className }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <circle cx="4" cy="10" r="1" fill="currentColor" />
+      <circle cx="4" cy="5" r="1" fill="currentColor" />
+      <circle cx="4" cy="14" r="1" fill="currentColor" />
+      <circle cx="4" cy="19" r="1" fill="currentColor" />
+      <path
+        d="M7 9.75L10 9.75"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M7 5L10 5"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M7 14.25H10"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M7 19H10"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M13 5H20"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M13 9.75H20"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M13 14.25H20"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M13 19H20"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}

apps/webapp/app/assets/logos/GoogleLogo.tsx

@@ -0,0 +1,22 @@
+export function GoogleLogo({ className }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <path
+        d="M19.9075 21.0983C22.7427 18.4521 24.0028 14.0417 23.2468 9.82031H11.9688V14.4827H18.3953C18.1433 15.9949 17.2612 17.255 16.0011 18.0741L19.9075 21.0983Z"
+        fill="#4285F4"
+      />
+      <path
+        d="M1.25781 17.3802C2.08665 19.013 3.27532 20.4362 4.73421 21.5428C6.1931 22.6493 7.88415 23.4102 9.67988 23.7681C11.4756 24.1261 13.3292 24.0717 15.1008 23.6091C16.8725 23.1465 18.516 22.2877 19.9075 21.0976L16.0011 18.0733C12.6618 20.2785 7.11734 19.4594 5.22717 14.293L1.25781 17.3802Z"
+        fill="#34A853"
+      />
+      <path
+        d="M5.22701 14.2922C4.72297 12.717 4.72297 11.2679 5.22701 9.69275L1.25765 6.60547C-0.191479 9.50373 -0.632519 13.5991 1.25765 17.3794L5.22701 14.2922Z"
+        fill="#FBBC02"
+      />
+      <path
+        d="M5.22717 9.69209C6.6133 5.34469 12.5358 2.82446 16.5052 6.5418L19.9705 3.13949C15.0561 -1.58594 5.47919 -1.39692 1.25781 6.60481L5.22717 9.69209Z"
+        fill="#EA4335"
+      />
+    </svg>
+  );
+}

apps/webapp/app/components/AlphaBadge.tsx

@@ -0,0 +1,61 @@
+import { cn } from "~/utils/cn";
+import { Badge } from "./primitives/Badge";
+import { SimpleTooltip } from "./primitives/Tooltip";
+
+export function AlphaBadge({
+  inline = false,
+  className,
+}: {
+  inline?: boolean;
+  className?: string;
+}) {
+  return (
+    <SimpleTooltip
+      button={
+        <Badge variant="extra-small" className={cn(inline ? "inline-grid" : "", className)}>
+          Alpha
+        </Badge>
+      }
+      content="This feature is in Alpha."
+      disableHoverableContent
+    />
+  );
+}
+
+export function AlphaTitle({ children }: { children: React.ReactNode }) {
+  return (
+    <>
+      <span>{children}</span>
+      <AlphaBadge />
+    </>
+  );
+}
+
+export function BetaBadge({
+  inline = false,
+  className,
+}: {
+  inline?: boolean;
+  className?: string;
+}) {
+  return (
+    <SimpleTooltip
+      button={
+        <Badge variant="extra-small" className={cn(inline ? "inline-grid" : "", className)}>
+          Beta
+        </Badge>
+      }
+      content="This feature is in Beta."
+      disableHoverableContent
+    />
+  );
+}
+
+export function BetaTitle({ children }: { children: React.ReactNode }) {
+  return (
+    <>
+      <span>{children}</span>
+      <BetaBadge />
+    </>
+  );
+}

apps/webapp/app/components/AskAI.tsx

@@ -5,6 +5,7 @@ import {
   HandThumbUpIcon,
   StopIcon,
 } from "@heroicons/react/20/solid";
+import { cn } from "~/utils/cn";
 import { type FeedbackComment, KapaProvider, type QA, useChat } from "@kapaai/react-sdk";
 import { useSearchParams } from "@remix-run/react";
 import DOMPurify from "dompurify";
@@ -37,7 +38,7 @@ function useKapaWebsiteId() {
   return routeMatch?.kapa.websiteId;
 }
 
-export function AskAI() {
+export function AskAI({ isCollapsed = false }: { isCollapsed?: boolean }) {
   const { isManagedCloud } = useFeatures();
   const websiteId = useKapaWebsiteId();
 
@@ -54,21 +55,23 @@ export function AskAI() {
           hideShortcutKey
           data-modal-override-open-class-ask-ai="true"
           disabled
+          className={isCollapsed ? "w-full justify-center" : ""}
         >
           <AISparkleIcon className="size-5" />
         </Button>
       }
     >
-      {() => <AskAIProvider websiteId={websiteId} />}
+      {() => <AskAIProvider websiteId={websiteId} isCollapsed={isCollapsed} />}
     </ClientOnly>
   );
 }
 
 type AskAIProviderProps = {
   websiteId: string;
+  isCollapsed?: boolean;
 };
 
-function AskAIProvider({ websiteId }: AskAIProviderProps) {
+function AskAIProvider({ websiteId, isCollapsed = false }: AskAIProviderProps) {
   const [isOpen, setIsOpen] = useState(false);
   const [initialQuery, setInitialQuery] = useState<string | undefined>();
   const [searchParams, setSearchParams] = useSearchParams();
@@ -112,28 +115,39 @@ function AskAIProvider({ websiteId }: AskAIProviderProps) {
       }}
       botProtectionMechanism="hcaptcha"
     >
-      <TooltipProvider disableHoverableContent>
-        <Tooltip>
-          <TooltipTrigger asChild>
-            <div className="inline-flex">
-              <Button
-                variant="small-menu-item"
-                data-action="ask-ai"
-                shortcut={{ modifiers: ["mod"], key: "/", enabledOnInputElements: true }}
-                hideShortcutKey
-                data-modal-override-open-class-ask-ai="true"
-                onClick={() => openAskAI()}
-              >
-                <AISparkleIcon className="size-5" />
-              </Button>
-            </div>
-          </TooltipTrigger>
-          <TooltipContent side="top" className="flex items-center gap-1 py-1.5 pl-2.5 pr-2 text-xs">
-            Ask AI
-            <ShortcutKey shortcut={{ modifiers: ["mod"], key: "/" }} variant="medium/bright" />
-          </TooltipContent>
-        </Tooltip>
-      </TooltipProvider>
+      <motion.div layout="position" transition={{ duration: 0.2, ease: "easeInOut" }}>
+        <TooltipProvider disableHoverableContent>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <span className={cn("inline-flex h-8", isCollapsed && "w-full")}>
+                <Button
+                  variant="small-menu-item"
+                  data-action="ask-ai"
+                  shortcut={{ modifiers: ["mod"], key: "i", enabledOnInputElements: true }}
+                  hideShortcutKey
+                  data-modal-override-open-class-ask-ai="true"
+                  onClick={() => openAskAI()}
+                  fullWidth={isCollapsed}
+                  className={cn("h-full", isCollapsed && "justify-center")}
+                >
+                  <AISparkleIcon className="size-5" />
+                </Button>
+              </span>
+            </TooltipTrigger>
+            <TooltipContent
+              side="right"
+              sideOffset={8}
+              className="flex items-center gap-2 text-xs"
+            >
+              Ask AI
+              <span className="flex items-center">
+                <ShortcutKey shortcut={{ modifiers: ["mod"] }} variant="medium/bright" />
+                <ShortcutKey shortcut={{ key: "i" }} variant="medium/bright" />
+              </span>
+            </TooltipContent>
+          </Tooltip>
+        </TooltipProvider>
+      </motion.div>
       <AskAIDialog
         initialQuery={initialQuery}
         isOpen={isOpen}

apps/webapp/app/components/BlankStatePanels.tsx

@@ -52,6 +52,13 @@ import {
 } from "./SetupCommands";
 import { StepContentContainer } from "./StepContentContainer";
 import { V4Badge } from "./V4Badge";
+import {
+  ClientTabs,
+  ClientTabsContent,
+  ClientTabsList,
+  ClientTabsTrigger,
+} from "./primitives/ClientTabs";
+import { GitHubSettingsPanel } from "~/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.github";
 
 export function HasNoTasksDev() {
   return (
@@ -93,62 +100,7 @@ export function HasNoTasksDev() {
 }
 
 export function HasNoTasksDeployed({ environment }: { environment: MinimumEnvironment }) {
-  return (
-    <PackageManagerProvider>
-      <div>
-        <div className="mb-6 flex items-center justify-between border-b">
-          <div className="mb-2 flex items-center gap-2">
-            <EnvironmentIcon environment={environment} className="-ml-1 size-8" />
-            <Header1>Deploy your tasks to {environmentFullTitle(environment)}</Header1>
-          </div>
-          <div className="flex items-center">
-            <SimpleTooltip
-              button={
-                <LinkButton
-                  variant="small-menu-item"
-                  LeadingIcon={BookOpenIcon}
-                  leadingIconClassName="text-blue-500"
-                  to={docsPath("deployment/overview")}
-                />
-              }
-              content="Deploy docs"
-            />
-            <SimpleTooltip
-              button={
-                <LinkButton
-                  variant="small-menu-item"
-                  LeadingIcon={QuestionMarkCircleIcon}
-                  leadingIconClassName="text-blue-500"
-                  to={docsPath("troubleshooting#deployment")}
-                />
-              }
-              content="Troubleshooting docs"
-            />
-            <AskAI />
-          </div>
-        </div>
-        <StepNumber stepNumber="1a" title="Run the CLI 'deploy' command" />
-        <StepContentContainer>
-          <Paragraph spacing>
-            This will deploy your tasks to the {environmentFullTitle(environment)} environment. Read
-            the <TextLink to={docsPath("deployment/overview")}>full guide</TextLink>.
-          </Paragraph>
-          <TriggerDeployStep environment={environment} />
-        </StepContentContainer>
-        <StepNumber stepNumber="1b" title="Or deploy using GitHub Actions" />
-        <StepContentContainer>
-          <Paragraph spacing>
-            Read the <TextLink to={docsPath("github-actions")}>GitHub Actions guide</TextLink> to
-            get started.
-          </Paragraph>
-        </StepContentContainer>
-        <StepNumber stepNumber="2" title="Waiting for tasks to deploy" displaySpinner />
-        <StepContentContainer>
-          <Paragraph>This page will automatically refresh when your tasks are deployed.</Paragraph>
-        </StepContentContainer>
-      </div>
-    </PackageManagerProvider>
-  );
+  return <DeploymentOnboardingSteps />;
 }
 
 export function SchedulesNoPossibleTaskPanel() {
@@ -266,45 +218,7 @@ export function TestHasNoTasks() {
 }
 
 export function DeploymentsNone() {
-  const organization = useOrganization();
-  const project = useProject();
-  const environment = useEnvironment();
-
-  return (
-    <InfoPanel
-      icon={ServerStackIcon}
-      iconClassName="text-deployments"
-      title="Deploy for the first time"
-      panelClassName="max-w-full"
-    >
-      <Paragraph spacing variant="small">
-        There are several ways to deploy your tasks. You can use the CLI or a Continuous Integration
-        service like GitHub Actions. Make sure you{" "}
-        <TextLink href={v3EnvironmentVariablesPath(organization, project, environment)}>
-          set your environment variables
-        </TextLink>{" "}
-        first.
-      </Paragraph>
-      <div className="flex gap-3">
-        <LinkButton
-          to={docsPath("v3/cli-deploy")}
-          variant="docs/medium"
-          LeadingIcon={BookOpenIcon}
-          className="inline-flex"
-        >
-          Deploy with the CLI
-        </LinkButton>
-        <LinkButton
-          to={docsPath("v3/github-actions")}
-          variant="docs/medium"
-          LeadingIcon={BookOpenIcon}
-          className="inline-flex"
-        >
-          Deploy with GitHub actions
-        </LinkButton>
-      </div>
-    </InfoPanel>
-  );
+  return <DeploymentOnboardingSteps />;
 }
 
 export function DeploymentsNoneDev() {
@@ -313,46 +227,52 @@ export function DeploymentsNoneDev() {
   const environment = useEnvironment();
 
   return (
-    <div className="space-y-8">
-      <InfoPanel
-        icon={ServerStackIcon}
-        iconClassName="text-deployments"
-        title="Deploying tasks"
-        panelClassName="max-w-full"
-      >
-        <Paragraph spacing variant="small">
+    <>
+      <div className="mb-6 flex items-center justify-between border-b">
+        <div className="mb-2 flex items-center gap-2">
+          <EnvironmentIcon environment={environment} className="-ml-1 size-8" />
+          <Header1>Deploy your tasks</Header1>
+        </div>
+        <div className="flex items-center">
+          <SimpleTooltip
+            button={
+              <LinkButton
+                variant="small-menu-item"
+                LeadingIcon={BookOpenIcon}
+                leadingIconClassName="text-blue-500"
+                to={docsPath("deployment/overview")}
+              />
+            }
+            content="Deploy docs"
+          />
+          <SimpleTooltip
+            button={
+              <LinkButton
+                variant="small-menu-item"
+                LeadingIcon={QuestionMarkCircleIcon}
+                leadingIconClassName="text-blue-500"
+                to={docsPath("troubleshooting#deployment")}
+              />
+            }
+            content="Troubleshooting docs"
+          />
+          <AskAI />
+        </div>
+      </div>
+      <StepNumber stepNumber="→" title="Switch to a deployed environment" />
+      <StepContentContainer className="mb-4 flex flex-col gap-4">
+        <Paragraph>
           This is the Development environment. When you're ready to deploy your tasks, switch to a
           different environment.
         </Paragraph>
-        <Paragraph spacing variant="small">
-          There are several ways to deploy your tasks. You can use the CLI or a Continuous
-          Integration service like GitHub Actions. Make sure you{" "}
-          <TextLink href={v3EnvironmentVariablesPath(organization, project, environment)}>
-            set your environment variables
-          </TextLink>{" "}
-          first.
-        </Paragraph>
-        <div className="flex gap-3">
-          <LinkButton
-            to={docsPath("v3/cli-deploy")}
-            variant="docs/medium"
-            LeadingIcon={BookOpenIcon}
-            className="inline-flex"
-          >
-            Deploy with the CLI
-          </LinkButton>
-          <LinkButton
-            to={docsPath("v3/github-actions")}
-            variant="docs/medium"
-            LeadingIcon={BookOpenIcon}
-            className="inline-flex"
-          >
-            Deploy with GitHub actions
-          </LinkButton>
-        </div>
-      </InfoPanel>
-      <SwitcherPanel />
-    </div>
+        <EnvironmentSelector
+          organization={organization}
+          project={project}
+          environment={environment}
+          className="w-fit border border-charcoal-600 bg-secondary hover:border-charcoal-550 hover:bg-charcoal-600"
+        />
+      </StepContentContainer>
+    </>
   );
 }
 
@@ -670,3 +590,99 @@ export function BulkActionsNone() {
     </div>
   );
 }
+
+function DeploymentOnboardingSteps() {
+  const environment = useEnvironment();
+  const organization = useOrganization();
+  const project = useProject();
+
+  return (
+    <PackageManagerProvider>
+      <div className="mb-2 flex items-center justify-between border-b">
+        <div className="mb-2 flex min-w-0 items-center gap-2">
+          <EnvironmentIcon environment={environment} className="-ml-1 size-8 shrink-0" />
+          <Header1 className="truncate">Deploy your tasks to {environmentFullTitle(environment)}</Header1>
+        </div>
+        <div className="flex items-center">
+          <SimpleTooltip
+            button={
+              <LinkButton
+                variant="small-menu-item"
+                LeadingIcon={BookOpenIcon}
+                leadingIconClassName="text-blue-500"
+                to={docsPath("deployment/overview")}
+              />
+            }
+            content="Deploy docs"
+          />
+          <SimpleTooltip
+            button={
+              <LinkButton
+                variant="small-menu-item"
+                LeadingIcon={QuestionMarkCircleIcon}
+                leadingIconClassName="text-blue-500"
+                to={docsPath("troubleshooting#deployment")}
+              />
+            }
+            content="Troubleshooting docs"
+          />
+          <AskAI />
+        </div>
+      </div>
+      <ClientTabs defaultValue="github">
+        <ClientTabsList variant="segmented" className="mb-6">
+          <ClientTabsTrigger value={"github"} variant="segmented" layoutId="deploy-tabs">
+            GitHub
+          </ClientTabsTrigger>
+          <ClientTabsTrigger value={"cli"} variant="segmented" layoutId="deploy-tabs">
+            Manual
+          </ClientTabsTrigger>
+          <ClientTabsTrigger value={"github-actions"} variant="segmented" layoutId="deploy-tabs">
+            GitHub Actions
+          </ClientTabsTrigger>
+        </ClientTabsList>
+        <ClientTabsContent value={"github"}>
+          <StepNumber stepNumber="1" title="Connect your GitHub repository" />
+          <StepContentContainer>
+            <Paragraph spacing>
+              Deploy automatically with every push. Read the{" "}
+              <TextLink to={docsPath("github-integration")}>full guide</TextLink>.
+            </Paragraph>
+            <div className="w-fit">
+              <GitHubSettingsPanel
+                organizationSlug={organization.slug}
+                projectSlug={project.slug}
+                environmentSlug={environment.slug}
+                billingPath={v3BillingPath({ slug: organization.slug })}              
+              />
+            </div>
+          </StepContentContainer>
+        </ClientTabsContent>
+        <ClientTabsContent value={"cli"}>
+          <StepNumber stepNumber="1" title="Run the CLI 'deploy' command" />
+          <StepContentContainer>
+            <Paragraph spacing>
+              This will deploy your tasks to the {environmentFullTitle(environment)} environment.
+              Read the <TextLink to={docsPath("deployment/overview")}>full guide</TextLink>.
+            </Paragraph>
+            <TriggerDeployStep environment={environment} />
+          </StepContentContainer>
+        </ClientTabsContent>
+        <ClientTabsContent value={"github-actions"}>
+          <StepNumber stepNumber="1" title="Deploy using GitHub Actions" />
+          <StepContentContainer>
+            <Paragraph spacing>
+              Read the <TextLink to={docsPath("github-actions")}>GitHub Actions guide</TextLink> to
+              get started.
+            </Paragraph>
+          </StepContentContainer>
+        </ClientTabsContent>
+      </ClientTabs>
+
+      <StepNumber stepNumber="2" title="Waiting for tasks to deploy" displaySpinner />
+      <StepContentContainer>
+        <Paragraph>This page will automatically refresh when your tasks are deployed.</Paragraph>
+      </StepContentContainer>
+    </PackageManagerProvider>
+  );
+}

apps/webapp/app/components/ErrorDisplay.tsx

@@ -1,11 +1,10 @@
 import { HomeIcon } from "@heroicons/react/20/solid";
 import { isRouteErrorResponse, useRouteError } from "@remix-run/react";
-import { motion } from "framer-motion";
 import { friendlyErrorDisplay } from "~/utils/httpErrors";
 import { LinkButton } from "./primitives/Buttons";
 import { Header1 } from "./primitives/Headers";
 import { Paragraph } from "./primitives/Paragraph";
-import Spline from "@splinetool/react-spline";
+import { TriggerRotatingLogo } from "./TriggerRotatingLogo";
 import { type ReactNode } from "react";
 
 type ErrorDisplayOptions = {
@@ -57,14 +56,7 @@ export function ErrorDisplay({ title, message, button }: DisplayOptionsProps) {
           {button ? button.title : "Go to homepage"}
         </LinkButton>
       </div>
-      <motion.div
-        className="pointer-events-none absolute inset-0 overflow-hidden"
-        initial={{ opacity: 0 }}
-        animate={{ opacity: 1 }}
-        transition={{ delay: 0.5, duration: 2, ease: "easeOut" }}
-      >
-        <Spline scene="https://prod.spline.design/wRly8TZN-e0Twb8W/scene.splinecode" />
-      </motion.div>
+      <TriggerRotatingLogo />
     </div>
   );
 }

apps/webapp/app/components/GitHubLoginButton.tsx

@@ -32,8 +32,6 @@ export function OctoKitty({ className }: { className?: string }) {
       baseProfile="tiny"
       id="Layer_1"
       xmlns="http://www.w3.org/2000/svg"
-      x="0px"
-      y="0px"
       viewBox="0 0 2350 2314.8"
       xmlSpace="preserve"
       fill="currentColor"

apps/webapp/app/components/LogLevelTooltipInfo.tsx

@@ -0,0 +1,56 @@
+import { Header3 } from "./primitives/Headers";
+import { Paragraph } from "./primitives/Paragraph";
+import { LogLevel } from "./logs/LogLevel";
+
+export function LogLevelTooltipInfo() {
+  return (
+    <div className="flex max-w-xs flex-col gap-4 p-1 pb-2">
+      <div>
+        <Header3>Log Levels</Header3>
+        <Paragraph variant="small" className="text-text-dimmed">
+          Structured logging helps you debug and monitor your tasks.
+        </Paragraph>
+      </div>
+      <div>
+        <div className="mb-1">
+          <LogLevel level="TRACE" />
+        </div>
+        <Paragraph variant="small" className="text-text-dimmed">
+          Traces and spans representing the execution flow of your tasks.
+        </Paragraph>
+      </div>
+      <div>
+        <div className="mb-1">
+          <LogLevel level="INFO" />
+        </div>
+        <Paragraph variant="small" className="text-text-dimmed">
+          General informational messages about task execution.
+        </Paragraph>
+      </div>
+      <div>
+        <div className="mb-1">
+          <LogLevel level="WARN" />
+        </div>
+        <Paragraph variant="small" className="text-text-dimmed">
+          Warning messages indicating potential issues that don't prevent execution.
+        </Paragraph>
+      </div>
+      <div>
+        <div className="mb-1">
+          <LogLevel level="ERROR" />
+        </div>
+        <Paragraph variant="small" className="text-text-dimmed">
+          Error messages for failures and exceptions during task execution.
+        </Paragraph>
+      </div>
+      <div>
+        <div className="mb-1">
+          <LogLevel level="DEBUG" />
+        </div>
+        <Paragraph variant="small" className="text-text-dimmed">
+          Detailed diagnostic information for development and debugging.
+        </Paragraph>
+      </div>
+    </div>
+  );
+}

apps/webapp/app/components/Shortcuts.tsx

@@ -1,18 +1,17 @@
 import { Keyboard } from "lucide-react";
+import { useState } from "react";
+import { useShortcutKeys } from "~/hooks/useShortcutKeys";
+import { Button } from "./primitives/Buttons";
 import { Header3 } from "./primitives/Headers";
 import { Paragraph } from "./primitives/Paragraph";
 import {
   Sheet,
   SheetContent,
-  SheetDescription,
   SheetHeader,
   SheetTitle,
-  SheetTrigger,
+  SheetTrigger
 } from "./primitives/SheetV3";
 import { ShortcutKey } from "./primitives/ShortcutKey";
-import { Button } from "./primitives/Buttons";
-import { useState } from "react";
-import { useShortcutKeys } from "~/hooks/useShortcutKeys";
 
 export function Shortcuts() {
   return (
@@ -26,8 +25,8 @@ export function Shortcuts() {
           fullWidth
           textAlignLeft
           shortcut={{ modifiers: ["shift"], key: "?", enabled: false }}
-          className="gap-x-0 pl-0.5"
-          iconSpacing="gap-x-0.5"
+          className="gap-x-0 pl-1.5"
+          iconSpacing="gap-x-1.5"
         >
           Shortcuts
         </Button>
@@ -77,11 +76,16 @@ function ShortcutContent() {
               <ShortcutKey shortcut={{ key: "enter" }} variant="medium/bright" />
             </Shortcut>
             <Shortcut name="Ask AI">
-              <ShortcutKey shortcut={{ modifiers: ["mod"], key: "/" }} variant="medium/bright" />
+              <ShortcutKey shortcut={{ modifiers: ["mod"] }} variant="medium/bright" />
+              <ShortcutKey shortcut={{ key: "i" }} variant="medium/bright" />
             </Shortcut>
             <Shortcut name="Filter">
               <ShortcutKey shortcut={{ key: "f" }} variant="medium/bright" />
             </Shortcut>
+            <Shortcut name="Toggle side menu">
+              <ShortcutKey shortcut={{ modifiers: ["mod"]}} variant="medium/bright" />
+              <ShortcutKey shortcut={{ key: "b" }} variant="medium/bright" />
+            </Shortcut>
             <Shortcut name="Select filter">
               <ShortcutKey shortcut={{ key: "1" }} variant="medium/bright" />
               <Paragraph variant="small" className="ml-1.5">
@@ -134,6 +138,10 @@ function ShortcutContent() {
               <ShortcutKey shortcut={{ key: "arrowleft" }} variant="medium/bright" />
               <ShortcutKey shortcut={{ key: "arrowright" }} variant="medium/bright" />
             </Shortcut>
+            <Shortcut name="Jump to next/previous run">
+              <ShortcutKey shortcut={{ key: "j" }} variant="medium/bright" />
+              <ShortcutKey shortcut={{ key: "k" }} variant="medium/bright" />
+            </Shortcut>
             <Shortcut name="Expand all">
               <ShortcutKey shortcut={{ key: "e" }} variant="medium/bright" />
             </Shortcut>
@@ -154,6 +162,43 @@ function ShortcutContent() {
               <ShortcutKey shortcut={{ key: "p" }} variant="medium/bright" />
             </Shortcut>
           </div>
+          <div className="space-y-3">
+            <Header3>Logs page</Header3>
+            <Shortcut name="Filter by task">
+              <ShortcutKey shortcut={{ key: "t" }} variant="medium/bright" />
+            </Shortcut>
+            <Shortcut name="Filter by run ID">
+              <ShortcutKey shortcut={{ key: "i" }} variant="medium/bright" />
+            </Shortcut>
+            <Shortcut name="Filter by level">
+              <ShortcutKey shortcut={{ key: "l" }} variant="medium/bright" />
+            </Shortcut>
+            <Shortcut name="Select log level">
+              <ShortcutKey shortcut={{ key: "1" }} variant="medium/bright" />
+              <Paragraph variant="small" className="ml-1.5">
+                to
+              </Paragraph>
+              <ShortcutKey shortcut={{ key: "4" }} variant="medium/bright" />
+            </Shortcut>
+            <Shortcut name="Close detail panel">
+              <ShortcutKey shortcut={{ key: "esc" }} variant="medium/bright" />
+            </Shortcut>
+            <Shortcut name="Details tab">
+              <ShortcutKey shortcut={{ key: "d" }} variant="medium/bright" />
+            </Shortcut>
+            <Shortcut name="Run tab">
+              <ShortcutKey shortcut={{ key: "r" }} variant="medium/bright" />
+            </Shortcut>
+            <Shortcut name="View full run">
+              <ShortcutKey shortcut={{ key: "v" }} variant="medium/bright" />
+            </Shortcut>
+          </div>
+          <div className="space-y-3">
+            <Header3>Metrics page</Header3>
+            <Shortcut name="Toggle fullscreen chart">
+              <ShortcutKey shortcut={{ key: "v" }} variant="medium/bright" />
+            </Shortcut>
+          </div>
           <div className="space-y-3">
             <Header3>Schedules page</Header3>
             <Shortcut name="New schedule">

apps/webapp/app/components/TimezoneSetter.tsx

@@ -0,0 +1,30 @@
+import { useFetcher } from "@remix-run/react";
+import { useEffect, useRef } from "react";
+import { useTypedLoaderData } from "remix-typedjson";
+import type { loader } from "~/root";
+
+export function TimezoneSetter() {
+  const { timezone: storedTimezone } = useTypedLoaderData<typeof loader>();
+  const fetcher = useFetcher();
+  const hasSetTimezone = useRef(false);
+
+  useEffect(() => {
+    if (hasSetTimezone.current) return;
+
+    const browserTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+
+    if (browserTimezone && browserTimezone !== storedTimezone) {
+      hasSetTimezone.current = true;
+      fetcher.submit(
+        { timezone: browserTimezone },
+        {
+          method: "POST",
+          action: "/resources/timezone",
+          encType: "application/json",
+        }
+      );
+    }
+  }, [storedTimezone, fetcher]);
+
+  return null;
+}

apps/webapp/app/components/TriggerRotatingLogo.tsx

@@ -0,0 +1,75 @@
+import { motion } from "framer-motion";
+import { useEffect, useState } from "react";
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      "spline-viewer": React.DetailedHTMLProps<
+        React.HTMLAttributes<HTMLElement> & {
+          url?: string;
+          "loading-anim-type"?: string;
+        },
+        HTMLElement
+      >;
+    }
+  }
+
+  interface Window {
+    __splineLoader?: Promise<void>;
+  }
+}
+
+export function TriggerRotatingLogo() {
+  const [isSplineReady, setIsSplineReady] = useState(false);
+
+  useEffect(() => {
+    // Already registered from a previous render
+    if (customElements.get("spline-viewer")) {
+      setIsSplineReady(true);
+      return;
+    }
+
+    // Another mount already started loading - share the same promise
+    if (window.__splineLoader) {
+      window.__splineLoader.then(() => setIsSplineReady(true)).catch(() => setIsSplineReady(false));
+      return;
+    }
+
+    // First mount: create script and shared loader promise
+    const script = document.createElement("script");
+    script.type = "module";
+    // Version pinned; SRI hash omitted as unpkg doesn't guarantee hash stability across deploys
+    script.src = "https://unpkg.com/@splinetool/viewer@1.12.29/build/spline-viewer.js";
+
+    window.__splineLoader = new Promise<void>((resolve, reject) => {
+      script.onload = () => resolve();
+      script.onerror = () => reject();
+    });
+
+    window.__splineLoader.then(() => setIsSplineReady(true)).catch(() => setIsSplineReady(false));
+
+    document.head.appendChild(script);
+
+    // Intentionally no cleanup: once the custom element is registered globally,
+    // removing the script would break re-mounts while providing no benefit
+  }, []);
+
+  if (!isSplineReady) {
+    return null;
+  }
+
+  return (
+    <motion.div
+      className="pointer-events-none absolute inset-0 overflow-hidden"
+      initial={{ opacity: 0 }}
+      animate={{ opacity: 1 }}
+      transition={{ delay: 0.5, duration: 2, ease: "easeOut" }}
+    >
+      <spline-viewer
+        loading-anim-type="spinner-small-light"
+        url="https://prod.spline.design/wRly8TZN-e0Twb8W/scene.splinecode"
+        style={{ width: "100%", height: "100%" }}
+      />
+    </motion.div>
+  );
+}

apps/webapp/app/components/UserProfilePhoto.tsx

@@ -22,6 +22,7 @@ export function UserAvatar({
         className={cn("aspect-square rounded-full p-[7%]")}
         src={avatarUrl}
         alt={name ?? "User"}
+        referrerPolicy="no-referrer"
       />
     </div>
   ) : (

apps/webapp/app/components/code/AIQueryInput.tsx

@@ -0,0 +1,415 @@
+import { CheckIcon, PencilSquareIcon, PlusIcon, XMarkIcon } from "@heroicons/react/20/solid";
+import { AnimatePresence, motion } from "framer-motion";
+import { Suspense, lazy, useCallback, useEffect, useRef, useState } from "react";
+import { Button } from "~/components/primitives/Buttons";
+import { Spinner } from "~/components/primitives/Spinner";
+import { useEnvironment } from "~/hooks/useEnvironment";
+import { useOrganization } from "~/hooks/useOrganizations";
+import { useProject } from "~/hooks/useProject";
+import type { AITimeFilter } from "~/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.query/types";
+import { cn } from "~/utils/cn";
+
+// Lazy load streamdown components to avoid SSR issues
+const StreamdownRenderer = lazy(() =>
+  import("streamdown").then((mod) => ({
+    default: ({ children, isAnimating }: { children: string; isAnimating: boolean }) => (
+      <mod.ShikiThemeContext.Provider value={["one-dark-pro", "one-dark-pro"]}>
+        <mod.Streamdown isAnimating={isAnimating}>{children}</mod.Streamdown>
+      </mod.ShikiThemeContext.Provider>
+    ),
+  }))
+);
+
+type StreamEventType =
+  | { type: "thinking"; content: string }
+  | { type: "tool_call"; tool: string; args: unknown }
+  | { type: "time_filter"; filter: AITimeFilter }
+  | { type: "result"; success: true; query: string; timeFilter?: AITimeFilter }
+  | { type: "result"; success: false; error: string };
+
+export type AIQueryMode = "new" | "edit";
+
+interface AIQueryInputProps {
+  onQueryGenerated: (query: string) => void;
+  /** Called when the AI sets a time filter - updates URL search params */
+  onTimeFilterChange?: (filter: AITimeFilter) => void;
+  /** Set this to a prompt to auto-populate and immediately submit */
+  autoSubmitPrompt?: string;
+  /** Change this to force re-submission even if prompt is the same */
+  autoSubmitKey?: number;
+  /** Get the current query in the editor (used for edit mode) */
+  getCurrentQuery?: () => string;
+}
+
+export function AIQueryInput({
+  onQueryGenerated,
+  onTimeFilterChange,
+  autoSubmitPrompt,
+  autoSubmitKey,
+  getCurrentQuery,
+}: AIQueryInputProps) {
+  const [prompt, setPrompt] = useState("");
+  const [mode, setMode] = useState<AIQueryMode>("new");
+  const [isLoading, setIsLoading] = useState(false);
+  const [thinking, setThinking] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [showThinking, setShowThinking] = useState(false);
+  const [lastResult, setLastResult] = useState<"success" | "error" | null>(null);
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const abortControllerRef = useRef<AbortController | null>(null);
+  const lastAutoSubmitRef = useRef<{ prompt: string; key?: number } | null>(null);
+
+  const organization = useOrganization();
+  const project = useProject();
+  const environment = useEnvironment();
+
+  const resourcePath = `/resources/orgs/${organization.slug}/projects/${project.slug}/env/${environment.slug}/query/ai-generate`;
+
+  // Can only use edit mode if there's a current query
+  const canEdit = Boolean(getCurrentQuery?.()?.trim());
+
+  // If mode is edit but there's no current query, switch to new
+  useEffect(() => {
+    if (mode === "edit" && !canEdit) {
+      setMode("new");
+    }
+  }, [mode, canEdit]);
+
+  const submitQuery = useCallback(
+    async (queryPrompt: string, submitMode: AIQueryMode = mode) => {
+      if (!queryPrompt.trim() || isLoading) return;
+      const currentQuery = getCurrentQuery?.();
+      if (submitMode === "edit" && !currentQuery?.trim()) return;
+
+      setIsLoading(true);
+      setThinking("");
+      setError(null);
+      setShowThinking(true);
+      setLastResult(null);
+
+      // Abort any existing request
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort();
+      }
+      abortControllerRef.current = new AbortController();
+
+      try {
+        const formData = new FormData();
+        formData.append("prompt", queryPrompt);
+        formData.append("mode", submitMode);
+        if (submitMode === "edit" && currentQuery) {
+          formData.append("currentQuery", currentQuery);
+        }
+
+        const response = await fetch(resourcePath, {
+          method: "POST",
+          body: formData,
+          signal: abortControllerRef.current.signal,
+        });
+
+        if (!response.ok) {
+          const errorData = (await response.json()) as { error?: string };
+          setError(errorData.error || "Failed to generate query");
+          setIsLoading(false);
+          setLastResult("error");
+          return;
+        }
+
+        const reader = response.body?.getReader();
+        if (!reader) {
+          setError("No response stream");
+          setIsLoading(false);
+          setLastResult("error");
+          return;
+        }
+
+        const decoder = new TextDecoder();
+        let buffer = "";
+
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+
+          buffer += decoder.decode(value, { stream: true });
+
+          // Process complete events from buffer
+          const lines = buffer.split("\n\n");
+          buffer = lines.pop() || ""; // Keep incomplete line in buffer
+
+          for (const line of lines) {
+            if (line.startsWith("data: ")) {
+              try {
+                const event = JSON.parse(line.slice(6)) as StreamEventType;
+                processStreamEvent(event);
+              } catch {
+                // Ignore parse errors
+              }
+            }
+          }
+        }
+
+        // Process any remaining data
+        if (buffer.startsWith("data: ")) {
+          try {
+            const event = JSON.parse(buffer.slice(6)) as StreamEventType;
+            processStreamEvent(event);
+          } catch {
+            // Ignore parse errors
+          }
+        }
+      } catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+          // Request was aborted, ignore
+          return;
+        }
+        setError(err instanceof Error ? err.message : "An error occurred");
+        setLastResult("error");
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [isLoading, resourcePath, mode, getCurrentQuery]
+  );
+
+  const processStreamEvent = useCallback(
+    (event: StreamEventType) => {
+      switch (event.type) {
+        case "thinking":
+          setThinking((prev) => prev + event.content);
+          break;
+        case "tool_call":
+          // Tool calls are handled silently — no UI text needed
+          break;
+        case "time_filter":
+          // Apply time filter immediately when the AI sets it
+          onTimeFilterChange?.(event.filter);
+          break;
+        case "result":
+          if (event.success) {
+            // Apply time filter if included in result (backup in case time_filter event was missed)
+            if (event.timeFilter) {
+              onTimeFilterChange?.(event.timeFilter);
+            }
+            onQueryGenerated(event.query);
+            setPrompt("");
+            setLastResult("success");
+            // Keep thinking visible to show what happened
+          } else {
+            setError(event.error);
+            setLastResult("error");
+          }
+          break;
+      }
+    },
+    [onQueryGenerated, onTimeFilterChange]
+  );
+
+  const handleSubmit = useCallback(
+    (e?: React.FormEvent) => {
+      e?.preventDefault();
+      submitQuery(prompt);
+    },
+    [prompt, submitQuery]
+  );
+
+  // Auto-submit when autoSubmitPrompt or autoSubmitKey changes
+  useEffect(() => {
+    if (!autoSubmitPrompt || !autoSubmitPrompt.trim() || isLoading) {
+      return;
+    }
+
+    const last = lastAutoSubmitRef.current;
+    const isDifferent =
+      last === null || autoSubmitPrompt !== last.prompt || autoSubmitKey !== last.key;
+
+    if (isDifferent) {
+      lastAutoSubmitRef.current = { prompt: autoSubmitPrompt, key: autoSubmitKey };
+      setPrompt(autoSubmitPrompt);
+      submitQuery(autoSubmitPrompt);
+    }
+  }, [autoSubmitPrompt, autoSubmitKey, isLoading, submitQuery]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort();
+      }
+    };
+  }, []);
+
+  // Auto-hide error after delay
+  useEffect(() => {
+    if (error) {
+      const timer = setTimeout(() => setError(null), 15000);
+      return () => clearTimeout(timer);
+    }
+  }, [error]);
+
+  return (
+    <div className="flex flex-col">
+      {/* Gradient border wrapper like the schedules AI input */}
+      <div
+        className="overflow-hidden rounded-md p-px"
+        style={{ background: "linear-gradient(to bottom right, #E543FF, #286399)" }}
+      >
+        <div className="overflow-hidden rounded-md bg-background-bright">
+          <form onSubmit={handleSubmit}>
+            <textarea
+              ref={textareaRef}
+              name="prompt"
+              placeholder={
+                mode === "edit"
+                  ? "e.g. add a filter for failed runs, change the limit to 50"
+                  : "e.g. show me failed runs from the last 7 days"
+              }
+              value={prompt}
+              onChange={(e) => setPrompt(e.target.value)}
+              disabled={isLoading}
+              rows={8}
+              className="m-0 min-h-10 w-full resize-none border-0 bg-background-bright px-3 py-2.5 text-sm text-text-bright scrollbar-thin scrollbar-track-transparent scrollbar-thumb-charcoal-600 file:border-0 file:bg-transparent file:text-base file:font-medium placeholder:text-text-dimmed focus:border-0 focus:outline-none focus:ring-0 focus-visible:outline-none focus-visible:ring-0 focus-visible:ring-offset-0 disabled:cursor-not-allowed disabled:opacity-50"
+              onKeyDown={(e) => {
+                if (e.key === "Enter" && !e.shiftKey && prompt.trim() && !isLoading) {
+                  e.preventDefault();
+                  handleSubmit();
+                }
+              }}
+            />
+            <div className="flex justify-end gap-2 px-2 pb-2">
+              {isLoading ? (
+                <Button
+                  type="button"
+                  variant="tertiary/small"
+                  disabled={true}
+                  LeadingIcon={Spinner}
+                  className="pl-2"
+                  iconSpacing="gap-1.5"
+                >
+                  {mode === "edit" ? "Editing…" : "Generating…"}
+                </Button>
+              ) : (
+                <>
+                  <Button
+                    type="button"
+                    variant="tertiary/small"
+                    disabled={!prompt.trim()}
+                    LeadingIcon={PlusIcon}
+                    iconSpacing="gap-1.5"
+                    onClick={() => {
+                      setMode("new");
+                      submitQuery(prompt, "new");
+                    }}
+                  >
+                    New query
+                  </Button>
+                  <Button
+                    type="button"
+                    variant="tertiary/small"
+                    disabled={!prompt.trim() || !canEdit}
+                    LeadingIcon={PencilSquareIcon}
+                    className={cn(!canEdit && "opacity-50")}
+                    iconSpacing="gap-2"
+                    tooltip={!canEdit ? "Write a query first to enable editing" : undefined}
+                    onClick={() => {
+                      setMode("edit");
+                      submitQuery(prompt, "edit");
+                    }}
+                  >
+                    Edit query
+                  </Button>
+                </>
+              )}
+            </div>
+          </form>
+        </div>
+      </div>
+
+      {/* Error message */}
+      <AnimatePresence>
+        {error && (
+          <motion.div
+            initial={{ opacity: 0, height: 0 }}
+            animate={{ opacity: 1, height: "auto" }}
+            exit={{ opacity: 0, height: 0 }}
+            transition={{ duration: 0.2 }}
+            className="overflow-hidden"
+          >
+            <div className="rounded-md border border-error/30 bg-error/10 px-3 py-2 text-sm text-error">
+              {error}
+            </div>
+          </motion.div>
+        )}
+      </AnimatePresence>
+
+      {/* Thinking panel - stays visible after completion */}
+      <AnimatePresence>
+        {showThinking && thinking && (
+          <motion.div
+            initial={{ opacity: 0, height: 0 }}
+            animate={{ opacity: 1, height: "auto" }}
+            exit={{ opacity: 0, height: 0 }}
+            transition={{ duration: 0.2 }}
+            className="overflow-hidden"
+          >
+            <div className="px-1">
+              <div className="rounded-b-lg border-x border-b border-grid-dimmed bg-charcoal-850 p-3 pb-1">
+                <div className="mb-1 flex items-center justify-between">
+                  <div className="flex items-center gap-1">
+                    {isLoading ? (
+                      <Spinner className="size-4" />
+                    ) : lastResult === "success" ? (
+                      <CheckIcon className="size-4 text-success" />
+                    ) : lastResult === "error" ? (
+                      <XMarkIcon className="size-4 text-error" />
+                    ) : null}
+                    <span className="text-xs font-medium text-text-dimmed">
+                      {isLoading
+                        ? "AI is thinking…"
+                        : lastResult === "success"
+                        ? "Query generated"
+                        : lastResult === "error"
+                        ? "Generation failed"
+                        : "AI response"}
+                    </span>
+                  </div>
+                  {isLoading ? (
+                    <Button
+                      variant="minimal/small"
+                      onClick={() => {
+                        if (abortControllerRef.current) {
+                          abortControllerRef.current.abort();
+                        }
+                        setIsLoading(false);
+                        setShowThinking(false);
+                        setThinking("");
+                      }}
+                      className="text-xs"
+                    >
+                      Cancel
+                    </Button>
+                  ) : (
+                    <Button
+                      variant="minimal/small"
+                      onClick={() => {
+                        setShowThinking(false);
+                        setThinking("");
+                      }}
+                      className="text-xs"
+                    >
+                      Dismiss
+                    </Button>
+                  )}
+                </div>
+                <div className="streamdown-container max-h-96 overflow-y-auto text-xs text-text-dimmed scrollbar-thin scrollbar-track-transparent scrollbar-thumb-charcoal-600">
+                  <Suspense fallback={<p className="whitespace-pre-wrap">{thinking}</p>}>
+                    <StreamdownRenderer isAnimating={isLoading}>{thinking}</StreamdownRenderer>
+                  </Suspense>
+                </div>
+              </div>
+            </div>
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </div>
+  );
+}

apps/webapp/app/components/code/ChartConfigPanel.tsx

@@ -0,0 +1,624 @@
+import type { OutputColumnMetadata } from "@internal/clickhouse";
+import { IconSortAscending, IconSortDescending } from "@tabler/icons-react";
+import { BarChart, CheckIcon, LineChart, Plus, XIcon } from "lucide-react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { cn } from "~/utils/cn";
+import { Paragraph } from "../primitives/Paragraph";
+import { Popover, PopoverContent, PopoverTrigger } from "../primitives/Popover";
+import { Select, SelectItem } from "../primitives/Select";
+import { Switch } from "../primitives/Switch";
+import SegmentedControl from "../primitives/SegmentedControl";
+import { Button } from "../primitives/Buttons";
+import {
+  type AggregationType,
+  type ChartConfiguration,
+  type SortDirection,
+} from "../metrics/QueryWidget";
+import { CHART_COLORS_BY_HUE, getSeriesColor } from "./chartColors";
+
+export const defaultChartConfig: ChartConfiguration = {
+  chartType: "bar",
+  xAxisColumn: null,
+  yAxisColumns: [],
+  groupByColumn: null,
+  stacked: false,
+  sortByColumn: null,
+  sortDirection: "asc",
+  aggregation: "sum",
+  seriesColors: {},
+};
+
+interface ChartConfigPanelProps {
+  columns: OutputColumnMetadata[];
+  config: ChartConfiguration;
+  onChange: (config: ChartConfiguration) => void;
+  className?: string;
+}
+
+// Type detection helpers
+function isNumericType(type: string): boolean {
+  return (
+    type.startsWith("Int") ||
+    type.startsWith("UInt") ||
+    type.startsWith("Float") ||
+    type.startsWith("Decimal") ||
+    type.startsWith("Nullable(Int") ||
+    type.startsWith("Nullable(UInt") ||
+    type.startsWith("Nullable(Float") ||
+    type.startsWith("Nullable(Decimal")
+  );
+}
+
+function isDateTimeType(type: string): boolean {
+  return (
+    type === "DateTime" ||
+    type === "DateTime64" ||
+    type === "Date" ||
+    type === "Date32" ||
+    type.startsWith("DateTime64(") ||
+    type.startsWith("Nullable(DateTime") ||
+    type.startsWith("Nullable(Date")
+  );
+}
+
+function isStringType(type: string): boolean {
+  return (
+    type === "String" ||
+    type === "LowCardinality(String)" ||
+    type === "Nullable(String)" ||
+    type.startsWith("Enum") ||
+    type.startsWith("FixedString")
+  );
+}
+
+export function ChartConfigPanel({ columns, config, onChange, className }: ChartConfigPanelProps) {
+  // Categorize columns by type
+  const { numericColumns, dateTimeColumns, categoricalColumns, allColumns } = useMemo(() => {
+    const numeric: OutputColumnMetadata[] = [];
+    const dateTime: OutputColumnMetadata[] = [];
+    const categorical: OutputColumnMetadata[] = [];
+
+    for (const col of columns) {
+      if (isNumericType(col.type)) {
+        numeric.push(col);
+      }
+      if (isDateTimeType(col.type)) {
+        dateTime.push(col);
+      }
+      if (isStringType(col.type) || isDateTimeType(col.type)) {
+        categorical.push(col);
+      }
+    }
+
+    return {
+      numericColumns: numeric,
+      dateTimeColumns: dateTime,
+      categoricalColumns: categorical,
+      allColumns: columns,
+    };
+  }, [columns]);
+
+  // Create a stable key from column names and types to detect actual changes
+  const columnsKey = useMemo(() => columns.map((c) => `${c.name}:${c.type}`).join(","), [columns]);
+
+  // Use refs to access current config/onChange without adding them as dependencies
+  const configRef = useRef(config);
+  const onChangeRef = useRef(onChange);
+  useEffect(() => {
+    configRef.current = config;
+    onChangeRef.current = onChange;
+  });
+
+  // Auto-select defaults when columns change
+  useEffect(() => {
+    if (columns.length === 0) return;
+
+    const currentConfig = configRef.current;
+    let needsUpdate = false;
+    const updates: Partial<ChartConfiguration> = {};
+
+    // Auto-select X-axis (prefer datetime, then first categorical)
+    if (!currentConfig.xAxisColumn) {
+      const defaultX = dateTimeColumns[0] ?? categoricalColumns[0] ?? columns[0];
+      if (defaultX) {
+        updates.xAxisColumn = defaultX.name;
+        needsUpdate = true;
+      }
+    }
+
+    // Auto-select Y-axis (first numeric column)
+    if (currentConfig.yAxisColumns.length === 0 && numericColumns.length > 0) {
+      updates.yAxisColumns = [numericColumns[0].name];
+      needsUpdate = true;
+    }
+
+    // Determine the effective x-axis column (either existing or newly selected)
+    const effectiveXAxis = updates.xAxisColumn ?? currentConfig.xAxisColumn;
+
+    // Auto-set sort to x-axis ASC if it's a datetime column and no sort is configured
+    if (
+      effectiveXAxis &&
+      !currentConfig.sortByColumn &&
+      dateTimeColumns.some((col) => col.name === effectiveXAxis)
+    ) {
+      updates.sortByColumn = effectiveXAxis;
+      updates.sortDirection = "asc";
+      needsUpdate = true;
+    }
+
+    if (needsUpdate) {
+      onChangeRef.current({ ...currentConfig, ...updates });
+    }
+    // Only re-run when the actual column structure changes, not on every config change.
+    // columnsKey (a string) is stable when columns match, so this won't re-fire
+    // unnecessarily when the same query is re-run with identical columns.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [columnsKey]);
+
+  const updateConfig = useCallback(
+    (updates: Partial<ChartConfiguration>) => {
+      onChange({ ...config, ...updates });
+    },
+    [config, onChange]
+  );
+
+  // X-axis options: prefer datetime and string columns at the top
+  const xAxisOptions = useMemo(() => {
+    const preferred = [
+      ...dateTimeColumns,
+      ...categoricalColumns.filter((c) => !isDateTimeType(c.type)),
+    ];
+    const preferredNames = new Set(preferred.map((c) => c.name));
+    const other = allColumns.filter((c) => !preferredNames.has(c.name));
+
+    const options: Array<{ value: string; label: string; type: string }> = [];
+
+    for (const col of preferred) {
+      options.push({ value: col.name, label: col.name, type: col.type });
+    }
+    for (const col of other) {
+      options.push({ value: col.name, label: col.name, type: col.type });
+    }
+
+    return options;
+  }, [allColumns, dateTimeColumns, categoricalColumns]);
+
+  // Y-axis options: numeric columns only
+  const yAxisOptions = useMemo(() => {
+    return numericColumns.map((col) => ({
+      value: col.name,
+      label: col.name,
+      type: col.type,
+    }));
+  }, [numericColumns]);
+
+  // Aggregation options
+  const aggregationOptions = [
+    { value: "sum", label: "Sum" },
+    { value: "avg", label: "Average" },
+    { value: "count", label: "Count" },
+    { value: "min", label: "Min" },
+    { value: "max", label: "Max" },
+  ];
+
+  // Group by options: categorical columns (excluding selected X axis)
+  const groupByOptions = useMemo(() => {
+    const options = categoricalColumns
+      .filter((col) => col.name !== config.xAxisColumn)
+      .map((col) => ({
+        value: col.name,
+        label: col.name,
+        type: col.type,
+      }));
+
+    return [{ value: "__none__", label: "None", type: "" }, ...options];
+  }, [categoricalColumns, config.xAxisColumn]);
+
+  // Sort by options: all columns
+  const sortByOptions = useMemo(() => {
+    const options = allColumns.map((col) => ({
+      value: col.name,
+      label: col.name,
+      type: col.type,
+    }));
+
+    return [{ value: "__none__", label: "None", type: "" }, ...options];
+  }, [allColumns]);
+
+  if (columns.length === 0) {
+    return (
+      <div className={cn("flex items-center justify-center p-4", className)}>
+        <Paragraph variant="small" className="text-text-dimmed">
+          Run a query to configure the chart
+        </Paragraph>
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn("flex flex-col gap-3 p-2", className)}>
+      {/* Chart Type */}
+      <div className="flex flex-col gap-3">
+        <ConfigField label="Type">
+          <SegmentedControl
+            name="chartType"
+            value={config.chartType}
+            variant="secondary/small"
+            options={[
+              {
+                label: (
+                  <span className="flex items-center gap-1">
+                    <BarChart className="size-3" /> Bar
+                  </span>
+                ),
+                value: "bar",
+              },
+              {
+                label: (
+                  <span className="flex items-center gap-1">
+                    <LineChart className="size-3" /> Line
+                  </span>
+                ),
+                value: "line",
+              },
+            ]}
+            onChange={(value) => updateConfig({ chartType: value as "bar" | "line" })}
+          />
+        </ConfigField>
+      </div>
+
+      <div className="flex flex-col gap-3">
+        {/* X-Axis */}
+        <ConfigField label="X-Axis">
+          <Select
+            value={config.xAxisColumn ?? ""}
+            setValue={(value) => {
+              const updates: Partial<ChartConfiguration> = { xAxisColumn: value || null };
+              // Auto-set sort to x-axis ASC if selecting a datetime column
+              if (value) {
+                const selectedCol = columns.find((c) => c.name === value);
+                if (selectedCol && isDateTimeType(selectedCol.type)) {
+                  updates.sortByColumn = value;
+                  updates.sortDirection = "asc";
+                }
+              }
+              updateConfig(updates);
+            }}
+            variant="tertiary/small"
+            placeholder="Select column"
+            items={xAxisOptions}
+            dropdownIcon
+            className="min-w-[140px]"
+          >
+            {(items) =>
+              items.map((item) => (
+                <SelectItem key={item.value} value={item.value}>
+                  <span className="flex items-center gap-2">
+                    <span>{item.label}</span>
+                    <TypeBadge type={item.type} />
+                  </span>
+                </SelectItem>
+              ))
+            }
+          </Select>
+        </ConfigField>
+
+        {/* Y-Axis / Series */}
+        <ConfigField label={config.yAxisColumns.length > 1 ? "Series" : "Y-Axis"}>
+          {yAxisOptions.length === 0 ? (
+            <span className="text-xs text-text-dimmed">No numeric columns</span>
+          ) : (
+            <div className="flex flex-col gap-1.5">
+              {/* Always show at least one dropdown, even if yAxisColumns is empty */}
+              {(config.yAxisColumns.length === 0 ? [""] : config.yAxisColumns).map((col, index) => (
+                <div key={index} className="flex items-center gap-1">
+                  {col && !config.groupByColumn && (
+                    <SeriesColorPicker
+                      color={config.seriesColors?.[col] ?? getSeriesColor(index)}
+                      onColorChange={(color) => {
+                        updateConfig({
+                          seriesColors: { ...config.seriesColors, [col]: color },
+                        });
+                      }}
+                    />
+                  )}
+                  <Select
+                    value={col}
+                    setValue={(value) => {
+                      const newColumns = [...config.yAxisColumns];
+                      const updates: Partial<ChartConfiguration> = {};
+                      if (value) {
+                        // If this is a new slot (empty string), add it
+                        if (index >= config.yAxisColumns.length) {
+                          newColumns.push(value);
+                        } else {
+                          // If the column name changed, migrate the color
+                          const oldCol = newColumns[index];
+                          if (oldCol && oldCol !== value && config.seriesColors?.[oldCol]) {
+                            const newSeriesColors = { ...config.seriesColors };
+                            newSeriesColors[value] = newSeriesColors[oldCol];
+                            delete newSeriesColors[oldCol];
+                            updates.seriesColors = newSeriesColors;
+                          }
+                          newColumns[index] = value;
+                        }
+                      } else if (index < config.yAxisColumns.length) {
+                        newColumns.splice(index, 1);
+                      }
+                      updateConfig({ ...updates, yAxisColumns: newColumns });
+                    }}
+                    variant="tertiary/small"
+                    placeholder="Select column"
+                    items={yAxisOptions.filter(
+                      (opt) => opt.value === col || !config.yAxisColumns.includes(opt.value)
+                    )}
+                    dropdownIcon
+                    className="min-w-[140px] flex-1"
+                  >
+                    {(items) =>
+                      items.map((item) => (
+                        <SelectItem key={item.value} value={item.value}>
+                          <span className="flex items-center gap-2">
+                            <span>{item.label}</span>
+                            <TypeBadge type={item.type} />
+                          </span>
+                        </SelectItem>
+                      ))
+                    }
+                  </Select>
+
+                  {index > 0 && (
+                    <button
+                      type="button"
+                      onClick={() => {
+                        const removedCol = config.yAxisColumns[index];
+                        const newColumns = config.yAxisColumns.filter((_, i) => i !== index);
+                        const updates: Partial<ChartConfiguration> = { yAxisColumns: newColumns };
+                        // Clean up the color entry for the removed series
+                        if (removedCol && config.seriesColors?.[removedCol]) {
+                          const newSeriesColors = { ...config.seriesColors };
+                          delete newSeriesColors[removedCol];
+                          updates.seriesColors = newSeriesColors;
+                        }
+                        updateConfig(updates);
+                      }}
+                      className="rounded p-1 text-text-dimmed hover:bg-charcoal-700 hover:text-text-bright"
+                      title="Remove series"
+                    >
+                      <XIcon className="h-3.5 w-3.5" />
+                    </button>
+                  )}
+                </div>
+              ))}
+
+              {/* Add another series button - only show when we have at least one series and not grouped */}
+              {config.yAxisColumns.length > 0 &&
+                config.yAxisColumns.length < yAxisOptions.length &&
+                !config.groupByColumn && (
+                  <button
+                    type="button"
+                    onClick={() => {
+                      const availableColumns = yAxisOptions.filter(
+                        (opt) => !config.yAxisColumns.includes(opt.value)
+                      );
+                      if (availableColumns.length > 0) {
+                        updateConfig({
+                          yAxisColumns: [...config.yAxisColumns, availableColumns[0].value],
+                        });
+                      }
+                    }}
+                    className="flex items-center gap-1 self-start rounded px-1 py-0.5 text-xs text-text-dimmed hover:bg-charcoal-700 hover:text-text-bright"
+                  >
+                    <Plus className="h-3 w-3" />
+                    Add series
+                  </button>
+                )}
+
+              {config.groupByColumn && config.yAxisColumns.length === 1 && (
+                <span className="text-xxs text-text-dimmed">
+                  Remove group by to add multiple series
+                </span>
+              )}
+            </div>
+          )}
+        </ConfigField>
+
+        {/* Aggregation */}
+        <ConfigField label="Aggregation">
+          <Select
+            value={config.aggregation}
+            setValue={(value) => updateConfig({ aggregation: value as AggregationType })}
+            variant="tertiary/small"
+            items={aggregationOptions}
+            dropdownIcon
+            className="min-w-[100px]"
+          >
+            {(items) =>
+              items.map((item) => (
+                <SelectItem key={item.value} value={item.value}>
+                  {item.label}
+                </SelectItem>
+              ))
+            }
+          </Select>
+        </ConfigField>
+
+        {/* Group By - disabled when multiple series are selected */}
+        <ConfigField label="Group by">
+          {config.yAxisColumns.length > 1 ? (
+            <span className="text-xs text-text-dimmed">Not available with multiple series</span>
+          ) : (
+            <Select
+              value={config.groupByColumn ?? "__none__"}
+              setValue={(value) =>
+                updateConfig({ groupByColumn: value === "__none__" ? null : value })
+              }
+              variant="tertiary/small"
+              placeholder="None"
+              items={groupByOptions}
+              dropdownIcon
+              className="min-w-[140px]"
+              text={(t) => (t === "__none__" ? "None" : t)}
+            >
+              {(items) =>
+                items.map((item) => (
+                  <SelectItem key={item.value} value={item.value}>
+                    <span className="flex items-center gap-2">
+                      <span>{item.label}</span>
+                      {item.type && <TypeBadge type={item.type} />}
+                    </span>
+                  </SelectItem>
+                ))
+              }
+            </Select>
+          )}
+        </ConfigField>
+
+        {/* Stacked toggle (when grouped or multiple series) */}
+        {(config.groupByColumn || config.yAxisColumns.length > 1) && (
+          <ConfigField label={config.groupByColumn ? "Stack groups" : "Stack series"}>
+            <Switch
+              variant="medium"
+              checked={config.stacked}
+              onCheckedChange={(checked) => updateConfig({ stacked: checked })}
+            />
+          </ConfigField>
+        )}
+
+        {/* Order By */}
+        <ConfigField label="Order by">
+          <Select
+            value={config.sortByColumn ?? "__none__"}
+            setValue={(value) =>
+              updateConfig({ sortByColumn: value === "__none__" ? null : value })
+            }
+            variant="tertiary/small"
+            placeholder="None"
+            items={sortByOptions}
+            dropdownIcon
+            className="min-w-[140px]"
+            text={(t) => (t === "__none__" ? "None" : t)}
+          >
+            {(items) =>
+              items.map((item) => (
+                <SelectItem key={item.value} value={item.value}>
+                  <span className="flex items-center gap-2">
+                    <span>{item.label}</span>
+                    {item.type && <TypeBadge type={item.type} />}
+                  </span>
+                </SelectItem>
+              ))
+            }
+          </Select>
+        </ConfigField>
+
+        {/* Sort Direction (only when sorting) */}
+        {config.sortByColumn && (
+          <ConfigField label="Sort direction">
+            <SegmentedControl
+              name="sortDirection"
+              value={config.sortDirection}
+              variant="secondary/small"
+              options={[
+                {
+                  label: (
+                    <span className="flex items-center gap-1">
+                      <IconSortAscending className="size-3" /> Asc
+                    </span>
+                  ),
+                  value: "asc",
+                },
+                {
+                  label: (
+                    <span className="flex items-center gap-1">
+                      <IconSortDescending className="size-3" /> Desc
+                    </span>
+                  ),
+                  value: "desc",
+                },
+              ]}
+              onChange={(value) => updateConfig({ sortDirection: value as SortDirection })}
+            />
+          </ConfigField>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function ConfigField({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <div className="flex flex-col gap-1">
+      {label && <span className="text-xs text-text-bright">{label}</span>}
+      {children}
+    </div>
+  );
+}
+
+function SeriesColorPicker({
+  color,
+  onColorChange,
+}: {
+  color: string;
+  onColorChange: (color: string) => void;
+}) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          className="flex-shrink-0 rounded p-0.5 hover:bg-charcoal-700"
+          title="Change series color"
+        >
+          <span
+            className="block h-4 w-4 rounded-full border border-white/30"
+            style={{ backgroundColor: color }}
+          />
+        </button>
+      </PopoverTrigger>
+      <PopoverContent align="start" className="w-auto p-2">
+        <div className="grid grid-cols-6 gap-1.5">
+          {CHART_COLORS_BY_HUE.map((c) => (
+            <button
+              key={c}
+              type="button"
+              onClick={() => {
+                onColorChange(c);
+                setOpen(false);
+              }}
+              className="group/swatch flex h-6 w-6 items-center justify-center rounded-full border border-white/30"
+              style={{ backgroundColor: c }}
+              title={c}
+            >
+              {c === color && <CheckIcon className="h-3.5 w-3.5 text-white drop-shadow-md" />}
+            </button>
+          ))}
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+function TypeBadge({ type }: { type: string }) {
+  // Simplify type for display
+  let displayType = type;
+  if (type.startsWith("Nullable(")) {
+    displayType = type.slice(9, -1) + "?";
+  }
+  if (type.startsWith("LowCardinality(")) {
+    displayType = type.slice(15, -1);
+  }
+
+  // Shorten long type names
+  if (displayType.length > 12) {
+    displayType = displayType.slice(0, 10) + "…";
+  }
+
+  return (
+    <span className="rounded bg-charcoal-750 px-1 py-0.5 font-mono text-xxs text-text-dimmed">
+      {displayType}
+    </span>
+  );
+}

apps/webapp/app/components/code/CodeBlock.tsx

@@ -5,6 +5,7 @@ import { Highlight, Prism } from "prism-react-renderer";
 import { forwardRef, ReactNode, useCallback, useEffect, useState } from "react";
 import { TextWrapIcon } from "~/assets/icons/TextWrapIcon";
 import { cn } from "~/utils/cn";
+import { highlightSearchText } from "~/utils/logUtils";
 import { Button } from "../primitives/Buttons";
 import { Dialog, DialogContent, DialogHeader, DialogTitle } from "../primitives/Dialog";
 import { Paragraph } from "../primitives/Paragraph";
@@ -20,6 +21,8 @@ async function setup() {
   await import("prismjs/components/prism-json");
   //@ts-ignore
   await import("prismjs/components/prism-typescript");
+  //@ts-ignore
+  await import("prismjs/components/prism-sql.js");
 }
 setup();
 
@@ -62,6 +65,12 @@ type CodeBlockProps = {
 
   /** Whether to show the open in modal button */
   showOpenInModal?: boolean;
+
+  /** Search term to highlight in the code */
+  searchTerm?: string;
+
+  /** Whether to wrap the code */
+  wrap?: boolean;
 };
 
 const dimAmount = 0.5;
@@ -200,6 +209,8 @@ export const CodeBlock = forwardRef<HTMLDivElement, CodeBlockProps>(
       showChrome = false,
       fileName,
       rowTitle,
+      searchTerm,
+      wrap = false,
       ...props
     }: CodeBlockProps,
     ref
@@ -208,7 +219,7 @@ export const CodeBlock = forwardRef<HTMLDivElement, CodeBlockProps>(
     const [copied, setCopied] = useState(false);
     const [modalCopied, setModalCopied] = useState(false);
     const [isModalOpen, setIsModalOpen] = useState(false);
-    const [isWrapped, setIsWrapped] = useState(false);
+    const [isWrapped, setIsWrapped] = useState(wrap);
 
     const onCopied = useCallback(
       (event: React.MouseEvent<HTMLButtonElement>) => {
@@ -236,7 +247,7 @@ export const CodeBlock = forwardRef<HTMLDivElement, CodeBlockProps>(
       [code]
     );
 
-    code = code.trim();
+    code = code?.trim() ?? "";
     const lineCount = code.split("\n").length;
     const maxLineWidth = lineCount.toString().length;
     let maxHeight: string | undefined = undefined;
@@ -338,6 +349,7 @@ export const CodeBlock = forwardRef<HTMLDivElement, CodeBlockProps>(
               className="px-2 py-3"
               preClassName="text-xs"
               isWrapped={isWrapped}
+              searchTerm={searchTerm}
             />
           ) : (
             <div
@@ -358,7 +370,7 @@ export const CodeBlock = forwardRef<HTMLDivElement, CodeBlockProps>(
                 )}
                 dir="ltr"
               >
-                {code}
+                {highlightSearchText(code, searchTerm)}
               </pre>
             </div>
           )}
@@ -400,7 +412,7 @@ export const CodeBlock = forwardRef<HTMLDivElement, CodeBlockProps>(
                 className="overflow-auto px-3 py-3 scrollbar-thin scrollbar-track-transparent scrollbar-thumb-charcoal-600"
               >
                 <pre className="relative mr-2 p-2 font-mono text-base leading-relaxed" dir="ltr">
-                  {code}
+                  {highlightSearchText(code, searchTerm)}
                 </pre>
               </div>
             )}
@@ -449,6 +461,7 @@ type HighlightCodeProps = {
   className?: string;
   preClassName?: string;
   isWrapped: boolean;
+  searchTerm?: string;
 };
 
 function HighlightCode({
@@ -461,6 +474,7 @@ function HighlightCode({
   className,
   preClassName,
   isWrapped,
+  searchTerm,
 }: HighlightCodeProps) {
   const [isLoaded, setIsLoaded] = useState(false);
 
@@ -470,6 +484,8 @@ function HighlightCode({
       import("prismjs/components/prism-json"),
       //@ts-ignore
       import("prismjs/components/prism-typescript"),
+      //@ts-ignore
+      import("prismjs/components/prism-sql.js"),
     ]).then(() => setIsLoaded(true));
   }, []);
 
@@ -552,6 +568,10 @@ function HighlightCode({
                     <div className="flex-1">
                       {line.map((token, key) => {
                         const tokenProps = getTokenProps({ token, key });
+
+                        // Highlight search term matches in token
+                        const content = highlightSearchText(token.content, searchTerm);
+
                         return (
                           <span
                             key={key}
@@ -560,7 +580,9 @@ function HighlightCode({
                               color: tokenProps?.style?.color as string,
                               ...tokenProps.style,
                             }}
-                          />
+                          >
+                            {content}
+                          </span>
                         );
                       })}
                     </div>

apps/webapp/app/components/code/TSQLEditor.tsx

@@ -0,0 +1,387 @@
+import { sql, StandardSQL } from "@codemirror/lang-sql";
+import { autocompletion, startCompletion } from "@codemirror/autocomplete";
+import { linter, lintGutter } from "@codemirror/lint";
+import { EditorView, keymap } from "@codemirror/view";
+import type { ViewUpdate } from "@codemirror/view";
+import { CheckIcon, ClipboardIcon, SparklesIcon, TrashIcon } from "@heroicons/react/20/solid";
+import {
+  type ReactCodeMirrorProps,
+  type UseCodeMirror,
+  useCodeMirror,
+} from "@uiw/react-codemirror";
+import { useCallback, useEffect, useRef, useState, useMemo } from "react";
+import { cn } from "~/utils/cn";
+import { Button } from "../primitives/Buttons";
+import { getEditorSetup } from "./codeMirrorSetup";
+import { darkTheme } from "./codeMirrorTheme";
+import { createTSQLCompletion } from "./tsql/tsqlCompletion";
+import { createTSQLLinter } from "./tsql/tsqlLinter";
+import type { TableSchema } from "@internal/tsql";
+import { format as formatSQL } from "sql-formatter";
+
+export interface TSQLEditorProps extends Omit<ReactCodeMirrorProps, "onBlur"> {
+  /** Initial value for the editor */
+  defaultValue?: string;
+  /** Whether the editor is read-only */
+  readOnly?: boolean;
+  /** Called when the editor content changes */
+  onChange?: (value: string) => void;
+  /** Called when the editor state updates */
+  onUpdate?: (update: ViewUpdate) => void;
+  /** Called when the editor loses focus */
+  onBlur?: (code: string) => void;
+  /** Schema for table/column autocompletion */
+  schema?: TableSchema[];
+  /** Show copy button */
+  showCopyButton?: boolean;
+  /** Show clear button */
+  showClearButton?: boolean;
+  /** Show format button */
+  showFormatButton?: boolean;
+  /** Enable linting (syntax checking) */
+  linterEnabled?: boolean;
+  /** Placeholder text when empty */
+  placeholder?: string;
+  /** Additional actions to show in the toolbar */
+  additionalActions?: React.ReactNode;
+  /** Minimum height of the editor */
+  minHeight?: string;
+}
+
+type TSQLEditorDefaultProps = Partial<TSQLEditorProps>;
+
+const defaultProps: TSQLEditorDefaultProps = {
+  readOnly: false,
+  basicSetup: false,
+  linterEnabled: true,
+  showCopyButton: true,
+  showClearButton: false,
+  showFormatButton: true,
+  schema: [],
+};
+
+// Toggle comment on current line or selected lines with -- comment symbol
+const toggleLineComment = (view: EditorView): boolean => {
+  const { from, to } = view.state.selection.main;
+  const startLine = view.state.doc.lineAt(from);
+  // When `to` is exactly at the start of a line and there's an actual selection,
+  // the caret sits before that line — so exclude it by stepping back one position.
+  const adjustedTo = to > from && view.state.doc.lineAt(to).from === to ? to - 1 : to;
+  const endLine = view.state.doc.lineAt(adjustedTo);
+
+  // Collect all lines in the selection
+  const lines: { from: number; to: number; text: string }[] = [];
+  for (let i = startLine.number; i <= endLine.number; i++) {
+    const line = view.state.doc.line(i);
+    lines.push({ from: line.from, to: line.to, text: line.text });
+  }
+
+  // Determine action: if all non-empty lines are commented, uncomment; otherwise comment
+  const allCommented = lines.every((line) => {
+    const trimmed = line.text.trimStart();
+    return trimmed.length === 0 || trimmed.startsWith("--");
+  });
+
+  const changes = lines
+    .map((line) => {
+      const trimmed = line.text.trimStart();
+      if (trimmed.length === 0) return null; // skip empty lines
+      const indent = line.text.length - trimmed.length;
+
+      if (allCommented) {
+        // Remove comment: strip "-- " or just "--"
+        const afterComment = trimmed.slice(2);
+        const newText = line.text.slice(0, indent) + afterComment.replace(/^\s/, "");
+        return { from: line.from, to: line.to, insert: newText };
+      } else {
+        // Add comment: prepend "-- " to the line content
+        const newText = line.text.slice(0, indent) + "-- " + trimmed;
+        return { from: line.from, to: line.to, insert: newText };
+      }
+    })
+    .filter((c): c is { from: number; to: number; insert: string } => c !== null);
+
+  if (changes.length > 0) {
+    view.dispatch({ changes });
+  }
+
+  return true;
+};
+
+export function TSQLEditor(opts: TSQLEditorProps) {
+  const {
+    defaultValue = "",
+    readOnly = false,
+    onChange,
+    onUpdate,
+    onBlur,
+    basicSetup = false,
+    autoFocus,
+    showCopyButton = true,
+    showClearButton = false,
+    showFormatButton = true,
+    linterEnabled = true,
+    schema = [],
+    placeholder = "",
+    additionalActions,
+    minHeight = undefined,
+  } = {
+    ...defaultProps,
+    ...opts,
+  };
+
+  // Create extensions - memoize to avoid recreating on every render
+  const extensions = useMemo(() => {
+    const exts = getEditorSetup();
+
+    // Add SQL language support with StandardSQL dialect
+    // This provides syntax highlighting
+    exts.push(
+      sql({
+        dialect: StandardSQL,
+        upperCaseKeywords: true,
+      })
+    );
+
+    // Add custom TSQL completion
+    if (schema && schema.length > 0) {
+      exts.push(
+        autocompletion({
+          override: [createTSQLCompletion(schema)],
+          activateOnTyping: true,
+          maxRenderedOptions: 50,
+        })
+      );
+
+      // Trigger autocomplete when ' is typed in value context
+      // CodeMirror's activateOnTyping only triggers on alphanumeric characters,
+      // so we manually trigger for quotes after comparison operators
+      exts.push(
+        EditorView.domEventHandlers({
+          keyup: (event, view) => {
+            // Trigger on quote key (both ' and shift+' on some keyboards)
+            if (event.key === "'" || event.key === '"' || event.code === "Quote") {
+              setTimeout(() => {
+                startCompletion(view);
+              }, 50);
+            }
+            return false;
+          },
+        })
+      );
+    }
+
+    // Add TSQL linter
+    if (linterEnabled) {
+      exts.push(lintGutter());
+      exts.push(
+        linter(createTSQLLinter({ schema }), {
+          delay: 300, // Debounce linting for better performance
+        })
+      );
+    }
+
+    // Add keyboard shortcut for toggling comments
+    exts.push(
+      keymap.of([
+        { key: "Cmd-/", run: toggleLineComment },
+        { key: "Ctrl-/", run: toggleLineComment },
+      ])
+    );
+
+    return exts;
+  }, [schema, linterEnabled]);
+
+  const editor = useRef<HTMLDivElement>(null);
+
+  const settings: Omit<UseCodeMirror, "onBlur"> = {
+    ...opts,
+    container: editor.current,
+    extensions,
+    editable: !readOnly,
+    contentEditable: !readOnly,
+    value: defaultValue,
+    autoFocus,
+    theme: darkTheme(),
+    indentWithTab: false,
+    basicSetup,
+    onChange,
+    onUpdate,
+    placeholder,
+  };
+
+  const { setContainer, view } = useCodeMirror(settings);
+  const [copied, setCopied] = useState(false);
+
+  useEffect(() => {
+    if (editor.current) {
+      setContainer(editor.current);
+    }
+  }, [setContainer]);
+
+  // Update editor when defaultValue changes
+  useEffect(() => {
+    if (view !== undefined) {
+      if (view.state.doc.toString() === defaultValue) return;
+      view.dispatch({
+        changes: { from: 0, to: view.state.doc.length, insert: defaultValue },
+      });
+    }
+  }, [defaultValue, view]);
+
+  const clear = () => {
+    if (view === undefined) return;
+    view.dispatch({
+      changes: { from: 0, to: view.state.doc.length, insert: undefined },
+    });
+    onChange?.("");
+  };
+
+  const copy = useCallback(() => {
+    if (view === undefined) return;
+    navigator.clipboard.writeText(view.state.doc.toString());
+    setCopied(true);
+    setTimeout(() => {
+      setCopied(false);
+    }, 1500);
+  }, [view]);
+
+  const format = useCallback(() => {
+    if (view === undefined) return;
+    const currentContent = view.state.doc.toString();
+    if (!currentContent.trim()) return;
+
+    try {
+      const formatted = autoFormatSQL(currentContent);
+      view.dispatch({
+        changes: { from: 0, to: view.state.doc.length, insert: formatted },
+      });
+      onChange?.(formatted);
+    } catch {
+      // If formatting fails (e.g., invalid SQL), silently ignore
+    }
+  }, [view, onChange]);
+
+  const showButtons = showClearButton || showCopyButton || showFormatButton || additionalActions;
+
+  return (
+    <div
+      className={cn("relative flex h-full flex-col", opts.className)}
+      style={minHeight ? { minHeight } : undefined}
+    >
+      <div
+        className={cn(
+          "min-h-0 flex-1 overflow-auto scrollbar-thin scrollbar-track-transparent scrollbar-thumb-charcoal-600"
+        )}
+        ref={editor}
+        onClick={() => {
+          view?.focus();
+        }}
+        onBlur={() => {
+          if (!onBlur) return;
+          if (!view) return;
+          onBlur(view.state.doc.toString());
+        }}
+      />
+      {showButtons && (
+        <div className="absolute right-0 top-0 z-10 flex items-center justify-end bg-charcoal-900/80 p-1.5">
+          {additionalActions && additionalActions}
+          {showFormatButton && (
+            <Button
+              type="button"
+              variant="minimal/small"
+              className="flex-none"
+              onClick={(event) => {
+                event.preventDefault();
+                event.stopPropagation();
+                format();
+              }}
+              shortcut={{ key: "f", modifiers: ["shift", "alt"], enabledOnInputElements: true }}
+            >
+              Format
+            </Button>
+          )}
+          {showClearButton && (
+            <Button
+              type="button"
+              variant="minimal/small"
+              TrailingIcon={TrashIcon}
+              onClick={(event) => {
+                event.preventDefault();
+                event.stopPropagation();
+                clear();
+              }}
+            >
+              Clear
+            </Button>
+          )}
+          {showCopyButton && (
+            <Button
+              type="button"
+              variant="minimal/small"
+              TrailingIcon={copied ? CheckIcon : ClipboardIcon}
+              trailingIconClassName={
+                copied ? "text-green-500 group-hover:text-green-500" : undefined
+              }
+              onClick={(event) => {
+                event.preventDefault();
+                event.stopPropagation();
+                copy();
+              }}
+            >
+              Copy
+            </Button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// SQL keywords that legitimately appear before parentheses with a space
+const SQL_KEYWORDS_BEFORE_PAREN = new Set([
+  "IN",
+  "NOT",
+  "EXISTS",
+  "OVER",
+  "USING",
+  "VALUES",
+  "BETWEEN",
+  "LIKE",
+  "AND",
+  "OR",
+  "ON",
+  "SET",
+  "INTO",
+  "TABLE",
+  "CASE",
+  "WHEN",
+  "THEN",
+  "ELSE",
+  "AS",
+  "FROM",
+  "WHERE",
+  "HAVING",
+  "JOIN",
+  "SELECT",
+]);
+
+export function autoFormatSQL(sql: string) {
+  let formatted = formatSQL(sql, {
+    language: "sql",
+    keywordCase: "upper",
+    indentStyle: "standard",
+    linesBetweenQueries: 2,
+  });
+
+  // sql-formatter adds a space before ( for unknown/custom functions (e.g. timeBucket ())
+  // Remove that space for anything that isn't a SQL keyword
+  formatted = formatted.replace(/(\b\w+)\s+\(/g, (match, name) => {
+    if (SQL_KEYWORDS_BEFORE_PAREN.has(name.toUpperCase())) {
+      return match;
+    }
+    return `${name}(`;
+  });
+
+  return formatted;
+}

apps/webapp/app/components/code/chartColors.ts

@@ -0,0 +1,183 @@
+/**
+ * Chart color palette defined in HSL (Hue, Saturation, Lightness).
+ *
+ * HSL is a human-friendly color model:
+ *   h: 0–360  (hue — position on the color wheel: 0=red, 120=green, 240=blue)
+ *   s: 0–100  (saturation — 0 is gray, 100 is full color)
+ *   l: 0–100  (lightness — 0 is black, 50 is pure color, 100 is white)
+ */
+
+interface HSLColor {
+  h: number;
+  s: number;
+  l: number;
+}
+
+interface ChartColorDef {
+  name: string;
+  hsl: HSLColor;
+}
+
+// ---------------------------------------------------------------------------
+// Palette — 30 distinct colors for chart series, defined in HSL
+// ---------------------------------------------------------------------------
+const CHART_COLOR_DEFS: ChartColorDef[] = [
+  // Primary colors (high contrast, spread across hue wheel)
+  { name: "Purple", hsl: { h: 252, s: 98, l: 66 } },
+  { name: "Green", hsl: { h: 142, s: 71, l: 45 } },
+  { name: "Amber", hsl: { h: 38, s: 92, l: 50 } },
+  { name: "Red", hsl: { h: 0, s: 84, l: 60 } },
+  { name: "Cyan", hsl: { h: 189, s: 95, l: 43 } },
+  { name: "Pink", hsl: { h: 330, s: 81, l: 60 } },
+  { name: "Violet", hsl: { h: 258, s: 90, l: 66 } },
+  { name: "Teal", hsl: { h: 173, s: 80, l: 40 } },
+  { name: "Orange", hsl: { h: 25, s: 95, l: 53 } },
+  { name: "Indigo", hsl: { h: 239, s: 84, l: 67 } },
+  // Extended palette
+  { name: "Lime", hsl: { h: 84, s: 81, l: 44 } },
+  { name: "Sky", hsl: { h: 199, s: 89, l: 48 } },
+  { name: "Rose", hsl: { h: 350, s: 89, l: 60 } },
+  { name: "Fuchsia", hsl: { h: 271, s: 91, l: 65 } },
+  { name: "Yellow", hsl: { h: 45, s: 93, l: 47 } },
+  { name: "Emerald", hsl: { h: 160, s: 84, l: 39 } },
+  { name: "Blue", hsl: { h: 217, s: 91, l: 60 } },
+  { name: "Magenta", hsl: { h: 292, s: 84, l: 61 } },
+  { name: "Stone", hsl: { h: 25, s: 5, l: 45 } },
+  { name: "Gold", hsl: { h: 48, s: 96, l: 53 } },
+  // Additional distinct colors (lighter variants)
+  { name: "Turquoise", hsl: { h: 173, s: 66, l: 50 } },
+  { name: "Light Orange", hsl: { h: 27, s: 96, l: 61 } },
+  { name: "Yellow-Green", hsl: { h: 83, s: 78, l: 55 } },
+  { name: "Light Blue", hsl: { h: 198, s: 93, l: 60 } },
+  { name: "Light Purple", hsl: { h: 270, s: 95, l: 75 } },
+  { name: "Light Green", hsl: { h: 142, s: 69, l: 58 } },
+  { name: "Light Amber", hsl: { h: 43, s: 96, l: 56 } },
+  { name: "Light Pink", hsl: { h: 329, s: 86, l: 70 } },
+  { name: "Light Cyan", hsl: { h: 187, s: 92, l: 69 } },
+  { name: "Light Indigo", hsl: { h: 235, s: 89, l: 74 } },
+];
+
+// ---------------------------------------------------------------------------
+// HSL ↔ Hex conversion
+// ---------------------------------------------------------------------------
+
+/** Convert an HSL color (h: 0–360, s: 0–100, l: 0–100) to a hex string */
+function hslToHex({ h, s, l }: HSLColor): string {
+  const sNorm = s / 100;
+  const lNorm = l / 100;
+
+  const c = (1 - Math.abs(2 * lNorm - 1)) * sNorm;
+  const hPrime = h / 60;
+  const x = c * (1 - Math.abs((hPrime % 2) - 1));
+  const m = lNorm - c / 2;
+
+  let r1: number, g1: number, b1: number;
+
+  if (hPrime < 1) {
+    r1 = c;
+    g1 = x;
+    b1 = 0;
+  } else if (hPrime < 2) {
+    r1 = x;
+    g1 = c;
+    b1 = 0;
+  } else if (hPrime < 3) {
+    r1 = 0;
+    g1 = c;
+    b1 = x;
+  } else if (hPrime < 4) {
+    r1 = 0;
+    g1 = x;
+    b1 = c;
+  } else if (hPrime < 5) {
+    r1 = x;
+    g1 = 0;
+    b1 = c;
+  } else {
+    r1 = c;
+    g1 = 0;
+    b1 = x;
+  }
+
+  const toHex = (v: number) =>
+    Math.round((v + m) * 255)
+      .toString(16)
+      .padStart(2, "0");
+
+  return `#${toHex(r1)}${toHex(g1)}${toHex(b1)}`;
+}
+
+/** Convert a hex string to HSL (h: 0–360, s: 0–100, l: 0–100) */
+function hexToHsl(hex: string): HSLColor {
+  const r = parseInt(hex.slice(1, 3), 16) / 255;
+  const g = parseInt(hex.slice(3, 5), 16) / 255;
+  const b = parseInt(hex.slice(5, 7), 16) / 255;
+
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const delta = max - min;
+  const l = (max + min) / 2;
+
+  if (delta === 0) {
+    return { h: 0, s: 0, l: Math.round(l * 100) };
+  }
+
+  const s = delta / (1 - Math.abs(2 * l - 1));
+
+  let h: number;
+  if (max === r) {
+    h = 60 * (((g - b) / delta + 6) % 6);
+  } else if (max === g) {
+    h = 60 * ((b - r) / delta + 2);
+  } else {
+    h = 60 * ((r - g) / delta + 4);
+  }
+
+  return {
+    h: Math.round(h),
+    s: Math.round(s * 100),
+    l: Math.round(l * 100),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Derived hex palette (for consumers that need plain hex strings)
+// ---------------------------------------------------------------------------
+
+/** Color palette for chart series — 30 distinct hex colors derived from HSL definitions */
+const CHART_COLORS: string[] = CHART_COLOR_DEFS.map((def) => hslToHex(def.hsl));
+
+/** Get the hex color for a series by its index (wraps around) */
+export function getSeriesColor(index: number): string {
+  return CHART_COLORS[index % CHART_COLORS.length];
+}
+
+// ---------------------------------------------------------------------------
+// Hue-sorted palette (rainbow order for color pickers)
+// ---------------------------------------------------------------------------
+
+const SATURATION_THRESHOLD = 10;
+
+/**
+ * Chart colors sorted by perceived hue — the natural rainbow order
+ * that humans expect: red -> orange -> yellow -> green -> cyan -> blue -> purple -> pink.
+ *
+ * Very desaturated colors (like grays) are placed at the end since they don't
+ * have a strong hue.
+ */
+export const CHART_COLORS_BY_HUE: string[] = [...CHART_COLOR_DEFS]
+  .sort((a, b) => {
+    const aIsGray = a.hsl.s < SATURATION_THRESHOLD;
+    const bIsGray = b.hsl.s < SATURATION_THRESHOLD;
+
+    // Push desaturated colors to the end
+    if (aIsGray && !bIsGray) return 1;
+    if (!aIsGray && bIsGray) return -1;
+    if (aIsGray && bIsGray) return a.hsl.l - b.hsl.l;
+
+    // Sort by hue, then by saturation (more vivid first), then by lightness
+    if (a.hsl.h !== b.hsl.h) return a.hsl.h - b.hsl.h;
+    if (a.hsl.s !== b.hsl.s) return b.hsl.s - a.hsl.s;
+    return a.hsl.l - b.hsl.l;
+  })
+  .map((def) => hslToHex(def.hsl));

apps/webapp/app/components/code/codeMirrorSetup.ts

@@ -1,5 +1,5 @@
 import { closeBrackets } from "@codemirror/autocomplete";
-import { indentWithTab } from "@codemirror/commands";
+import { indentWithTab, history, historyKeymap, undo, redo } from "@codemirror/commands";
 import { bracketMatching } from "@codemirror/language";
 import { lintKeymap } from "@codemirror/lint";
 import { highlightSelectionMatches } from "@codemirror/search";
@@ -18,6 +18,7 @@ export function getEditorSetup(showLineNumbers = true, showHighlights = true): A
   const options = [
     drawSelection(),
     dropCursor(),
+    history(),
     bracketMatching(),
     closeBrackets(),
     Prec.highest(
@@ -31,7 +32,15 @@ export function getEditorSetup(showLineNumbers = true, showHighlights = true): A
         },
       ])
     ),
-    keymap.of([indentWithTab, ...lintKeymap]),
+    // Explicit undo/redo keybindings with high precedence
+    Prec.high(
+      keymap.of([
+        { key: "Mod-z", run: undo },
+        { key: "Mod-Shift-z", run: redo },
+        { key: "Mod-y", run: redo },
+      ])
+    ),
+    keymap.of([indentWithTab, ...historyKeymap, ...lintKeymap]),
   ];
 
   if (showLineNumbers) {

apps/webapp/app/components/code/codeMirrorTheme.ts

@@ -67,9 +67,10 @@ export function darkTheme(): Extension {
       },
 
       ".cm-cursor, .cm-dropCursor": { borderLeftColor: cursor },
-      "&.cm-focused .cm-selectionBackground, .cm-selectionBackground, .cm-content ::selection": {
-        backgroundColor: selection,
-      },
+      "&.cm-focused .cm-selectionBackground, .cm-selectionBackground, .cm-content ::selection":
+        {
+          backgroundColor: selection,
+        },
 
       ".cm-panels": { backgroundColor: darkBackground, color: ivory },
       ".cm-panels.cm-panels-top": { borderBottom: "2px solid black" },
@@ -87,8 +88,8 @@ export function darkTheme(): Extension {
       ".cm-selectionMatch": { backgroundColor: "#aafe661a" },
 
       "&.cm-focused .cm-matchingBracket, &.cm-focused .cm-nonmatchingBracket": {
-        backgroundColor: "#bad0f847",
-        outline: "1px solid #515a6b",
+        backgroundColor: "rgba(18, 19, 23, 0.9)",
+        outline: "1px solid rgba(81, 90, 107, 0.5)",
       },
 
       ".cm-gutters": {
@@ -166,14 +167,20 @@ export function darkTheme(): Extension {
         backgroundColor: scrollbarBg,
       },
     },
-    { dark: true }
+    { dark: true },
   );
 
   /// The highlighting style for code in the JSON Hero theme.
   const jsonHeroHighlightStyle = HighlightStyle.define([
     { tag: tags.keyword, color: violet },
     {
-      tag: [tags.name, tags.deleted, tags.character, tags.propertyName, tags.macroName],
+      tag: [
+        tags.name,
+        tags.deleted,
+        tags.character,
+        tags.propertyName,
+        tags.macroName,
+      ],
       color: lilac,
     },
     { tag: [tags.function(tags.variableName), tags.labelName], color: malibu },

apps/webapp/app/components/code/tsql/index.ts

@@ -0,0 +1,6 @@
+// TSQL CodeMirror support
+// Provides syntax highlighting, autocompletion, and linting for TSQL queries
+
+export { createTSQLCompletion } from "./tsqlCompletion";
+export { createTSQLLinter, isValidTSQLQuery, getTSQLError, type TSQLLinterConfig } from "./tsqlLinter";
+

apps/webapp/app/components/code/tsql/tsqlCompletion.ts

@@ -0,0 +1,490 @@
+import type { CompletionContext, CompletionResult, Completion } from "@codemirror/autocomplete";
+import {
+  type TableSchema,
+  type ColumnSchema,
+  TSQL_CLICKHOUSE_FUNCTIONS,
+  TSQL_AGGREGATIONS,
+} from "@internal/tsql";
+
+/**
+ * SQL keywords for autocomplete
+ */
+const SQL_KEYWORDS = [
+  "SELECT",
+  "FROM",
+  "WHERE",
+  "AND",
+  "OR",
+  "NOT",
+  "IN",
+  "LIKE",
+  "ILIKE",
+  "BETWEEN",
+  "IS",
+  "NULL",
+  "TRUE",
+  "FALSE",
+  "AS",
+  "ORDER",
+  "BY",
+  "ASC",
+  "DESC",
+  "LIMIT",
+  "OFFSET",
+  "GROUP",
+  "HAVING",
+  "DISTINCT",
+  "JOIN",
+  "LEFT",
+  "RIGHT",
+  "INNER",
+  "OUTER",
+  "FULL",
+  "CROSS",
+  "ON",
+  "UNION",
+  "INTERSECT",
+  "EXCEPT",
+  "ALL",
+  "WITH",
+  "CASE",
+  "WHEN",
+  "THEN",
+  "ELSE",
+  "END",
+  "OVER",
+  "PARTITION",
+  "ROWS",
+  "RANGE",
+  "UNBOUNDED",
+  "PRECEDING",
+  "FOLLOWING",
+  "CURRENT",
+  "ROW",
+  "NULLS",
+  "FIRST",
+  "LAST",
+];
+
+/**
+ * Create keyword completions from the SQL keywords list
+ */
+function createKeywordCompletions(): Completion[] {
+  return SQL_KEYWORDS.map((keyword) => ({
+    label: keyword,
+    type: "keyword",
+    boost: -1, // Keywords should have lower priority than schema items
+  }));
+}
+
+/**
+ * Create function completions from TSQL function definitions
+ */
+function createFunctionCompletions(): Completion[] {
+  const functions: Completion[] = [];
+
+  // Add regular functions
+  for (const [name, meta] of Object.entries(TSQL_CLICKHOUSE_FUNCTIONS)) {
+    // Skip internal functions starting with _
+    if (name.startsWith("_")) continue;
+
+    const argsHint =
+      meta.maxArgs === 0
+        ? "()"
+        : meta.minArgs === meta.maxArgs
+        ? `(${meta.minArgs} args)`
+        : `(${meta.minArgs}${meta.maxArgs ? `-${meta.maxArgs}` : "+"} args)`;
+
+    functions.push({
+      label: name,
+      type: "function",
+      detail: argsHint,
+      apply: `${name}()`,
+    });
+  }
+
+  // Add aggregate functions with slightly higher boost
+  for (const [name, meta] of Object.entries(TSQL_AGGREGATIONS)) {
+    if (name.startsWith("_")) continue;
+
+    const argsHint =
+      meta.maxArgs === 0
+        ? "()"
+        : meta.minArgs === meta.maxArgs
+        ? `(${meta.minArgs} args)`
+        : `(${meta.minArgs}${meta.maxArgs ? `-${meta.maxArgs}` : "+"} args)`;
+
+    functions.push({
+      label: name,
+      type: "function",
+      detail: `aggregate ${argsHint}`,
+      apply: `${name}()`,
+      boost: 0.5,
+    });
+  }
+
+  // Add special TSQL functions not in the ClickHouse function registry
+  functions.push({
+    label: "timeBucket",
+    type: "function",
+    detail: "auto time bucket (0 args)",
+    apply: "timeBucket()",
+    boost: 1.5,
+    info: "Automatically bucket by time using the table's time column. Interval is chosen based on the query's time range.",
+  });
+
+  return functions;
+}
+
+/**
+ * Create table completions from schema
+ */
+function createTableCompletions(schema: TableSchema[]): Completion[] {
+  return schema.map((table) => ({
+    label: table.name,
+    type: "class", // Using "class" type for tables gives them a nice icon
+    detail: table.description || "table",
+    boost: 1, // Tables should have higher priority
+  }));
+}
+
+/**
+ * Create column completions for a specific table
+ */
+function createColumnCompletions(table: TableSchema, prefix?: string): Completion[] {
+  const columns: Completion[] = [];
+
+  for (const [name, column] of Object.entries(table.columns)) {
+    columns.push({
+      label: prefix ? `${prefix}.${name}` : name,
+      type: "property", // Using "property" type for columns
+      detail: `${column.type}${column.description ? ` - ${column.description}` : ""}`,
+      boost: 2, // Columns should have highest priority
+    });
+  }
+
+  return columns;
+}
+
+/**
+ * Extract table names/aliases from the current query context
+ * This is a simplified parser that looks for FROM and JOIN clauses
+ */
+function extractTablesFromQuery(doc: string, schema: TableSchema[]): Map<string, TableSchema> {
+  const tableMap = new Map<string, TableSchema>();
+  const tableNames = schema.map((t) => t.name);
+
+  // Simple regex to find table references in FROM and JOIN clauses
+  // Handles: FROM table_name, FROM table_name AS alias, FROM table_name alias
+  const tablePattern = /(?:FROM|JOIN)\s+(\w+)(?:\s+(?:AS\s+)?(\w+))?/gi;
+
+  let match;
+  while ((match = tablePattern.exec(doc)) !== null) {
+    const tableName = match[1];
+    const alias = match[2] || tableName;
+
+    // Find the table schema if it exists
+    const tableSchema = schema.find((t) => t.name.toLowerCase() === tableName.toLowerCase());
+
+    if (tableSchema) {
+      tableMap.set(alias.toLowerCase(), tableSchema);
+    }
+  }
+
+  return tableMap;
+}
+
+/**
+ * Determine what context we're in based on cursor position
+ */
+type CompletionContextType =
+  | "table" // After FROM or JOIN
+  | "column" // After SELECT, WHERE, ORDER BY, GROUP BY, etc.
+  | "alias" // After table_name.
+  | "value" // After comparison operator (=, !=, IN, etc.)
+  | "general"; // Anywhere else
+
+/**
+ * Result of context detection
+ */
+interface ContextResult {
+  type: CompletionContextType;
+  tablePrefix?: string;
+  /** Column being compared (for value context) */
+  columnName?: string;
+  /** Table alias for the column (for value context) */
+  columnTableAlias?: string;
+}
+
+/**
+ * Extract column name from text before a comparison operator
+ * Handles: "column =", "table.column =", "column IN", "column = 'partial", etc.
+ */
+function extractColumnBeforeOperator(
+  textBefore: string
+): { columnName: string; tableAlias?: string } | null {
+  // Match patterns like: column =, column !=, column IN, table.column =, etc.
+  // We need to capture the column (and optional table prefix) before the operator
+  // Also match when user is typing a partial string value like: column = 'val
+  const patterns = [
+    // column = or column != or column <> (with optional whitespace and optional partial string value)
+    /(\w+)\.(\w+)\s*(?:=|!=|<>)\s*(?:'[^']*)?$/i,
+    /(\w+)\s*(?:=|!=|<>)\s*(?:'[^']*)?$/i,
+    // column IN ( or column NOT IN ( (with optional partial string value)
+    /(\w+)\.(\w+)\s+(?:NOT\s+)?IN\s*\(\s*(?:'[^']*)?$/i,
+    /(\w+)\s+(?:NOT\s+)?IN\s*\(\s*(?:'[^']*)?$/i,
+    // After a comma in IN clause (with optional partial string value)
+    /(\w+)\.(\w+)\s+(?:NOT\s+)?IN\s*\([^)]*,\s*(?:'[^']*)?$/i,
+    /(\w+)\s+(?:NOT\s+)?IN\s*\([^)]*,\s*(?:'[^']*)?$/i,
+  ];
+
+  for (const pattern of patterns) {
+    const match = textBefore.match(pattern);
+    if (match) {
+      if (match.length === 3) {
+        // table.column pattern
+        return { tableAlias: match[1], columnName: match[2] };
+      } else {
+        // just column pattern
+        return { columnName: match[1] };
+      }
+    }
+  }
+
+  return null;
+}
+
+function determineContext(doc: string, pos: number): ContextResult {
+  // Get text before cursor
+  const textBefore = doc.slice(0, pos);
+
+  // Check if we're in a value context (after comparison operator)
+  // This should be checked before other contexts
+  const columnInfo = extractColumnBeforeOperator(textBefore);
+  if (columnInfo) {
+    return {
+      type: "value",
+      columnName: columnInfo.columnName,
+      columnTableAlias: columnInfo.tableAlias,
+    };
+  }
+
+  // Check if we're completing after a dot (table.column)
+  const dotMatch = textBefore.match(/(\w+)\.\s*$/);
+  if (dotMatch) {
+    return { type: "alias", tablePrefix: dotMatch[1] };
+  }
+
+  // Find the LAST significant keyword before cursor
+  // We match all keywords and take the last one
+  const keywordPattern = /\b(SELECT|FROM|JOIN|WHERE|AND|OR|ORDER\s+BY|GROUP\s+BY|HAVING|ON)\b/gi;
+  let lastMatch: RegExpExecArray | null = null;
+  let match: RegExpExecArray | null;
+
+  while ((match = keywordPattern.exec(textBefore)) !== null) {
+    lastMatch = match;
+  }
+
+  if (lastMatch) {
+    const keyword = lastMatch[1].toUpperCase().replace(/\s+/g, " ");
+
+    if (keyword === "FROM" || keyword === "JOIN") {
+      return { type: "table" };
+    }
+
+    if (
+      keyword === "SELECT" ||
+      keyword === "WHERE" ||
+      keyword === "AND" ||
+      keyword === "OR" ||
+      keyword === "ORDER BY" ||
+      keyword === "GROUP BY" ||
+      keyword === "HAVING" ||
+      keyword === "ON"
+    ) {
+      return { type: "column" };
+    }
+  }
+
+  return { type: "general" };
+}
+
+/**
+ * Find a column schema by name in the tables map
+ */
+function findColumnSchema(
+  columnName: string,
+  tableAlias: string | undefined,
+  tables: Map<string, TableSchema>
+): ColumnSchema | null {
+  if (tableAlias) {
+    // Look in specific table
+    const tableSchema = tables.get(tableAlias.toLowerCase());
+    if (tableSchema) {
+      return tableSchema.columns[columnName] || null;
+    }
+  } else {
+    // Look in all tables
+    for (const tableSchema of tables.values()) {
+      const col = tableSchema.columns[columnName];
+      if (col) {
+        return col;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Create completions for enum values from allowedValues
+ */
+function createEnumValueCompletions(columnSchema: ColumnSchema): Completion[] {
+  if (!columnSchema.allowedValues || columnSchema.allowedValues.length === 0) {
+    return [];
+  }
+
+  return columnSchema.allowedValues.map((value) => ({
+    label: `'${value}'`,
+    type: "enum",
+    detail: columnSchema.description || "allowed value",
+    boost: 3, // Highest priority for enum values in value context
+  }));
+}
+
+/**
+ * Create a TSQL-aware autocompletion source
+ *
+ * @param schema - Array of table schemas to use for completions
+ * @returns A CodeMirror completion source function
+ */
+export function createTSQLCompletion(
+  schema: TableSchema[]
+): (context: CompletionContext) => CompletionResult | null {
+  // Pre-compute static completions
+  const keywordCompletions = createKeywordCompletions();
+  const functionCompletions = createFunctionCompletions();
+  const tableCompletions = createTableCompletions(schema);
+
+  return (context: CompletionContext): CompletionResult | null => {
+    // Get the word being typed - include single quotes for value completion
+    const word = context.matchBefore(/[\w.']+/);
+
+    // Don't show completions if no word is being typed and not explicitly triggered
+    if (!word && !context.explicit) {
+      return null;
+    }
+
+    const from = word ? word.from : context.pos;
+    const doc = context.state.doc.toString();
+    const queryContext = determineContext(doc, context.pos);
+
+    let options: Completion[] = [];
+    // Track if we need to extend replacement range (e.g., to consume auto-paired closing quote)
+    let to: number | undefined = undefined;
+
+    switch (queryContext.type) {
+      case "table":
+        // After FROM or JOIN, show only tables
+        options = tableCompletions;
+        break;
+
+      case "alias":
+        // After table., show columns for that table
+        if (queryContext.tablePrefix) {
+          const tables = extractTablesFromQuery(doc, schema);
+          const tableSchema = tables.get(queryContext.tablePrefix.toLowerCase());
+
+          if (tableSchema) {
+            options = createColumnCompletions(tableSchema);
+          }
+        }
+        break;
+
+      case "value":
+        // After comparison operator, show enum values if available
+        if (queryContext.columnName) {
+          const tables = extractTablesFromQuery(doc, schema);
+          const columnSchema = findColumnSchema(
+            queryContext.columnName,
+            queryContext.columnTableAlias,
+            tables
+          );
+
+          if (columnSchema) {
+            options = createEnumValueCompletions(columnSchema);
+            // Check if there's a closing quote right after cursor (from auto-pairing)
+            // If so, extend replacement range to include it to avoid 'Completed''
+            const charAfterCursor = context.state.doc.sliceString(context.pos, context.pos + 1);
+            if (charAfterCursor === "'") {
+              to = context.pos + 1;
+            }
+          }
+        }
+        break;
+
+      case "column":
+        // After SELECT, WHERE, etc., show columns, functions, and some keywords
+        {
+          const tables = extractTablesFromQuery(doc, schema);
+
+          // Add columns from all tables in the query
+          tables.forEach((tableSchema, alias) => {
+            // If multiple tables, prefix with alias
+            const prefix = tables.size > 1 ? alias : undefined;
+            options.push(...createColumnCompletions(tableSchema, prefix));
+          });
+
+          // Also add functions and relevant keywords
+          options.push(...functionCompletions);
+          options.push(
+            ...keywordCompletions.filter((k) =>
+              [
+                "AND",
+                "OR",
+                "NOT",
+                "IN",
+                "LIKE",
+                "ILIKE",
+                "BETWEEN",
+                "IS",
+                "NULL",
+                "AS",
+                "CASE",
+                "WHEN",
+                "THEN",
+                "ELSE",
+                "END",
+              ].includes(k.label as string)
+            )
+          );
+        }
+        break;
+
+      case "general":
+      default:
+        // Show everything
+        options = [...tableCompletions, ...functionCompletions, ...keywordCompletions];
+
+        // Also add columns from tables in query
+        {
+          const tables = extractTablesFromQuery(doc, schema);
+          tables.forEach((tableSchema, alias) => {
+            const prefix = tables.size > 1 ? alias : undefined;
+            options.push(...createColumnCompletions(tableSchema, prefix));
+          });
+        }
+        break;
+    }
+
+    const result: CompletionResult = {
+      from,
+      options,
+      validFor: /^[\w.']*$/,
+    };
+    // Only set 'to' if we need to extend the replacement range
+    if (to !== undefined) {
+      result.to = to;
+    }
+    return result;
+  };
+}