Merge branch 'main' into fix/tri-6732-hover-vertical-timeline-does-not-update-on-task-runs

## Summary
- **Fix Docker publish automation**: The `v.docker.*` tags pushed by the
release workflow using `GITHUB_TOKEN` don't trigger the publish workflow
(GitHub Actions limitation to prevent infinite loops). Added a
`workflow_call` to `publish.yml` directly from the release job so Docker
images are built automatically after npm publish. Tags are still pushed
for reference.
- **Fix worker Containerfiles**: The coordinator, docker-provider, and
kubernetes-provider builds have been failing since the superjson
vendoring change in `@trigger.dev/core` (#2949). The Containerfiles now
run `bundle-vendor` before `build:bundle` to generate the vendor files
that esbuild needs.

### Context
- Docker images on GHCR have been stuck at v4.3.0 — v4.3.1, v4.3.2,
v4.3.3 tags existed on GitHub but never triggered publish runs
- The worker builds (publish-worker) have been failing on every push to
main since Jan 30

## Test plan
- [x] Verified kubernetes-provider Containerfile builds locally with the
fix
- [x] Manually dispatched publish workflow for v4.3.1 — all jobs
succeeded
<!-- devin-review-badge-begin -->

---

<a
href="https://app.devin.ai/review/triggerdotdev/trigger.dev/pull/3013"
target="_blank">
  <picture>
<source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1">
<img
src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1"
alt="Open with Devin">
  </picture>
</a>
<!-- devin-review-badge-end -->

.changeset/add-debounce-maxdelay.md

@@ -0,0 +1,16 @@
+---
+"@trigger.dev/core": patch
+"@trigger.dev/sdk": patch
+---
+
+Add `maxDelay` option to debounce feature. This allows setting a maximum time limit for how long a debounced run can be delayed, ensuring execution happens within a specified window even with continuous triggers.
+
+```typescript
+await myTask.trigger(payload, {
+  debounce: {
+    key: "my-key",
+    delay: "5s",
+    maxDelay: "30m", // Execute within 30 minutes regardless of continuous triggers
+  },
+});
+```

.changeset/blue-eyes-tickle.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-The dev command will now use the platform-provided engine URL

.changeset/breezy-turtles-talk.md

@@ -1,10 +0,0 @@
----
-"@trigger.dev/react-hooks": patch
-"@trigger.dev/sdk": patch
-"trigger.dev": patch
-"@trigger.dev/build": patch
-"@trigger.dev/core": patch
-"@trigger.dev/rsc": patch
----
-
-Run Engine 2.0 (alpha)

.changeset/calm-hooks-wait.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/react-hooks": patch
+---
+
+Fix `onComplete` callback firing prematurely when the realtime stream disconnects before the run finishes.

.changeset/consistent-stream-targets.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Aligned the SDK's `getRunIdForOptions` logic with the Core package to handle semantic targets (`root`, `parent`) in root tasks.

.changeset/eighty-rings-divide.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/core": patch
----
-
-Configurable queue consumer count in supervisor session

.changeset/export-start-attempt-hook-type.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Export `AnyOnStartAttemptHookFunction` type to allow defining `onStartAttempt` hooks for individual tasks.

.changeset/fix-dead-process-execute-hang.md

@@ -0,0 +1,5 @@
+---
+"trigger.dev": patch
+---
+
+Fix runner getting stuck indefinitely when `execute()` is called on a dead child process.

.changeset/four-needles-add.md

@@ -1,12 +0,0 @@
----
-"@trigger.dev/redis-worker": major
-"@trigger.dev/react-hooks": major
-"@trigger.dev/sdk": major
-"trigger.dev": major
-"@trigger.dev/python": major
-"@trigger.dev/build": major
-"@trigger.dev/core": major
-"@trigger.dev/rsc": major
----
-
-Trigger.dev v4 release. Please see our upgrade to v4 docs to view the full changelog: https://trigger.dev/docs/upgrade-to-v4

.changeset/gentle-waves-suffer.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-Fixed an issue with realtime streams that timeout and resume streaming dropping chunks

.changeset/green-lions-relate.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-The envvars.list() and retrieve() functions receive isSecret for each value. Secret values are always redacted.

.changeset/hip-cups-wave.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-Fix issue where realtime streams would cut off after 5 minutes

.changeset/honest-files-decide.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-Deprecate toolTask and replace with `ai.tool(mySchemaTask)`

.changeset/late-chairs-ring.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Fix init.ts in custom trigger dirs

.changeset/moody-squids-count.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Init command will now correctly install v4-beta packages

.changeset/nice-colts-boil.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Improve warm start times by eagerly creating the child TaskRunProcess when a previous run as completed

.changeset/polite-impalas-care.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Fixes runLimiter check on #dequeueRuns

.changeset/polite-lies-fix.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Update nypm package to support test-based bun.lock files

.changeset/pre.json

@@ -1,47 +0,0 @@
-{
-  "mode": "pre",
-  "tag": "v4-beta",
-  "initialVersions": {
-    "coordinator": "0.0.1",
-    "docker-provider": "0.0.1",
-    "kubernetes-provider": "0.0.1",
-    "supervisor": "0.0.1",
-    "webapp": "1.0.0",
-    "@trigger.dev/build": "3.3.17",
-    "trigger.dev": "3.3.17",
-    "@trigger.dev/core": "3.3.17",
-    "@trigger.dev/python": "3.3.17",
-    "@trigger.dev/react-hooks": "3.3.17",
-    "@trigger.dev/redis-worker": "3.3.17",
-    "@trigger.dev/rsc": "3.3.17",
-    "@trigger.dev/sdk": "3.3.17"
-  },
-  "changesets": [
-    "blue-eyes-tickle",
-    "breezy-turtles-talk",
-    "eighty-rings-divide",
-    "four-needles-add",
-    "gentle-waves-suffer",
-    "green-lions-relate",
-    "hip-cups-wave",
-    "honest-files-decide",
-    "late-chairs-ring",
-    "moody-squids-count",
-    "nice-colts-boil",
-    "polite-impalas-care",
-    "polite-lies-fix",
-    "red-wasps-cover",
-    "shiny-kiwis-beam",
-    "smart-coins-hammer",
-    "sour-mirrors-accept",
-    "spotty-ducks-punch",
-    "spotty-pants-wink",
-    "tender-jobs-collect",
-    "tidy-books-smell",
-    "tiny-buckets-teach",
-    "tricky-houses-invite",
-    "two-tigers-dream",
-    "weak-jobs-hide",
-    "wet-deers-think"
-  ]
-}

.changeset/red-wasps-cover.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/core": patch
----
-
-Suppress external instrumentation for fetch calls from ApiClient

.changeset/shiny-kiwis-beam.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Handle flush errors gracefully in dev

.changeset/smart-coins-hammer.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/core": patch
----
-
-fix: Realtime streams: prevent enqueuing into closed ReadableStream

.changeset/sour-mirrors-accept.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Improve usage flushing

.changeset/spotty-ducks-punch.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-fix: default machine config indexing now works

.changeset/spotty-pants-wink.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Prevent large outputs from overwriting each other

.changeset/tender-jobs-collect.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-TriggerApiError 4xx errors will no longer cause tasks to be retried

.changeset/tidy-books-smell.md

@@ -1,8 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-- Fix polling interval reset bug that could create duplicate intervals
-- Protect against unexpected attempt number changes
-- Prevent run execution zombies after warm starts

.changeset/tiny-buckets-teach.md

@@ -1,5 +0,0 @@
----
-"trigger.dev": patch
----
-
-Fix stalled run detection

.changeset/tricky-houses-invite.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Managed run controller performance and reliability improvements

.changeset/two-tigers-dream.md

@@ -1,5 +0,0 @@
----
-"@trigger.dev/sdk": patch
----
-
-maintain proper context in metadata.root and parent getters

.changeset/vendor-superjson-esm-fix.md

@@ -0,0 +1,7 @@
+---
+"@trigger.dev/core": patch
+---
+
+fix: vendor superjson to fix ESM/CJS compatibility
+
+Bundle superjson during build to avoid `ERR_REQUIRE_ESM` errors on Node.js versions that don't support `require(ESM)` by default (< 22.12.0) and AWS Lambda which intentionally disables it.

.changeset/weak-jobs-hide.md

@@ -1,7 +0,0 @@
----
-"@trigger.dev/sdk": patch
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-v4: New lifecycle hooks

.changeset/wet-deers-think.md

@@ -1,6 +0,0 @@
----
-"trigger.dev": patch
-"@trigger.dev/core": patch
----
-
-Fix QUEUED status snapshot handler

.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/mcp.json

@@ -1,7 +1,3 @@
 {
-  "mcpServers": {
-    "trigger.dev": {
-      "url": "http://localhost:3333/sse"
-    }
-  }
-}
+  "mcpServers": {}
+}

.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

.cursor/rules/webapp.mdc

@@ -6,7 +6,7 @@ alwaysApply: false
 
 The main trigger.dev webapp, which powers it's API and dashboard and makes up the docker image that is produced as an OSS image, is a Remix 2.1.0 app that uses an express server, written in TypeScript. The following subsystems are either included in the webapp or are used by the webapp in another part of the monorepo:
 
-- `@trigger.dev/database` exports a Prisma 5.4.1 client that is used extensively in the webapp to access a PostgreSQL instance. The schema file is [schema.prisma](mdc:internal-packages/database/prisma/schema.prisma)
+- `@trigger.dev/database` exports a Prisma 6.14.0 client that is used extensively in the webapp to access a PostgreSQL instance. The schema file is [schema.prisma](mdc:internal-packages/database/prisma/schema.prisma)
 - `@trigger.dev/core` is a published package and is used to share code between the `@trigger.dev/sdk` and the webapp. It includes functionality but also a load of Zod schemas for data validation. When importing from `@trigger.dev/core` in the webapp, we never import the root `@trigger.dev/core` path, instead we favor one of the subpath exports that you can find in [package.json](mdc:packages/core/package.json)
 - `@internal/run-engine` has all the code needed to trigger a run and take it through it's lifecycle to completion.
 - `@trigger.dev/redis-worker` is a custom redis based background job/worker system that's used in the webapp and also used inside the run engine.
@@ -31,7 +31,10 @@ We originally the Trigger.dev "Run Engine" not as a single system, but just spre
 - The batch trigger API endpoint is [api.v1.tasks.batch.ts](mdc:apps/webapp/app/routes/api.v1.tasks.batch.ts)
 - Setup code for the prisma client is in [db.server.ts](mdc:apps/webapp/app/db.server.ts)
 - The run engine is configured in [runEngine.server.ts](mdc:apps/webapp/app/v3/runEngine.server.ts)
-- All the "services" that are found in app/v3/services/**/*.server.ts
+- All the "services" that are found in app/v3/services/\*_/_.server.ts
 - The code for the TaskEvent data, which is the otel data sent from tasks to our servers, is in both the [eventRepository.server.ts](mdc:apps/webapp/app/v3/eventRepository.server.ts) and also the [otlpExporter.server.ts](mdc:apps/webapp/app/v3/otlpExporter.server.ts). The otel endpoints which are hit from production and development otel exporters is [otel.v1.logs.ts](mdc:apps/webapp/app/routes/otel.v1.logs.ts) and [otel.v1.traces.ts](mdc:apps/webapp/app/routes/otel.v1.traces.ts)
-- We use "presenters" to move more complex loader code into a class, and you can find those are app/v3/presenters/**/*.server.ts
+- We use "presenters" to move more complex loader code into a class, and you can find those are app/v3/presenters/\*_/_.server.ts
 
+- All the "services" that are found in app/v3/services/\*_/_.server.ts
+- The code for the TaskEvent data, which is the otel data sent from tasks to our servers, is in both the [eventRepository.server.ts](mdc:apps/webapp/app/v3/eventRepository.server.ts) and also the [otlpExporter.server.ts](mdc:apps/webapp/app/v3/otlpExporter.server.ts). The otel endpoints which are hit from production and development otel exporters is [otel.v1.logs.ts](mdc:apps/webapp/app/routes/otel.v1.logs.ts) and [otel.v1.traces.ts](mdc:apps/webapp/app/routes/otel.v1.traces.ts)
+- We use "presenters" to move more complex loader code into a class, and you can find those are app/v3/presenters/\*_/_.server.ts

.cursor/rules/writing-tasks.mdc

@@ -431,28 +431,6 @@ export async function POST(request: Request) {
 }
 ```
 
-### tasks.triggerAndPoll()
-
-Triggers a task and polls until completion. Not recommended for web requests as it blocks until the run completes. Consider using Realtime docs for better alternatives.
-
-```ts
-import { tasks } from "@trigger.dev/sdk/v3";
-import type { emailSequence } from "~/trigger/emails";
-
-export async function POST(request: Request) {
-  const data = await request.json();
-  const result = await tasks.triggerAndPoll<typeof emailSequence>(
-    "email-sequence",
-    {
-      to: data.email,
-      name: data.name,
-    },
-    { pollIntervalMs: 5000 }
-  );
-  return Response.json(result);
-}
-```
-
 ### batch.trigger()
 
 Triggers multiple runs of different tasks at once, useful when you need to execute multiple tasks simultaneously.

.cursorignore

@@ -4,4 +4,6 @@ apps/proxy/
 apps/coordinator/
 packages/rsc/
 .changeset
-.zed
+.zed
+.env
+!.env.example

.dockerignore

@@ -16,6 +16,8 @@
 **/dist
 **/node_modules
 
+**/generated/prisma
+
 apps/webapp/build
 apps/webapp/public/build
 

.env.example

@@ -12,7 +12,14 @@ APP_ENV=development
 APP_ORIGIN=http://localhost:3030
 ELECTRIC_ORIGIN=http://localhost:3060
 NODE_ENV=development
-V3_ENABLED=true
+
+# Clickhouse
+CLICKHOUSE_URL=http://default:password@localhost:8123
+RUN_REPLICATION_CLICKHOUSE_URL=http://default:password@localhost:8123
+RUN_REPLICATION_ENABLED=1
+
+# Set this to UTC because Node.js uses the system timezone
+TZ="UTC"
 
 # Redis is used for the v3 queuing and v2 concurrency control
 REDIS_HOST="localhost"
@@ -22,11 +29,14 @@ REDIS_TLS_DISABLED="true"
 DEV_OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:3030/otel"
 DEV_OTEL_BATCH_PROCESSING_ENABLED="0"
 
+# When the domain is set to `localhost` the CLI deploy command will only --load the image by default and not --push it
+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=
@@ -60,34 +70,11 @@ DEV_OTEL_BATCH_PROCESSING_ENABLED="0"
 # FROM_EMAIL=
 # REPLY_TO_EMAIL=
 
-# Remove the following line to enable logging telemetry traces to the console
-LOG_TELEMETRY="false"
-
 # CLOUD VARIABLES
 POSTHOG_PROJECT_KEY=
-PLAIN_API_KEY= 
-CLOUD_AIRTABLE_CLIENT_ID=
-CLOUD_AIRTABLE_CLIENT_SECRET=
-CLOUD_GITHUB_CLIENT_ID=
-CLOUD_GITHUB_CLIENT_SECRET=
-CLOUD_LINEAR_CLIENT_ID=
-CLOUD_LINEAR_CLIENT_SECRET=
-CLOUD_SLACK_APP_HOST=
-CLOUD_SLACK_CLIENT_ID=
-CLOUD_SLACK_CLIENT_SECRET= 
 
-# v3 variables
-PROVIDER_SECRET=provider-secret # generate the actual secret with `openssl rand -hex 32`
-COORDINATOR_SECRET=coordinator-secret # generate the actual secret with `openssl rand -hex 32`
-
-# Uncomment the following line to enable the registry proxy
-# ENABLE_REGISTRY_PROXY=true
+# DEPOT_ORG_ID=<Depot org id>
 # DEPOT_TOKEN=<Depot org token>
-# DEPOT_PROJECT_ID=<Depot project id>
-# DEPLOY_REGISTRY_HOST=${APP_ORIGIN} # This is the host that the deploy CLI will use to push images to the registry
-# CONTAINER_REGISTRY_ORIGIN=<Container registry origin e.g. https://registry.digitalocean.com>
-# CONTAINER_REGISTRY_USERNAME=<Container registry username e.g. Digital ocean email address>
-# CONTAINER_REGISTRY_PASSWORD=<Container registry password e.g. Digital ocean PAT>
 # DEV_OTEL_EXPORTER_OTLP_ENDPOINT="http://0.0.0.0:4318"
 # These are needed for the object store (for handling large payloads/outputs)
 # OBJECT_STORE_BASE_URL="https://{bucket}.{accountId}.r2.cloudflarestorage.com"
@@ -97,8 +84,11 @@ COORDINATOR_SECRET=coordinator-secret # generate the actual secret with `openssl
 
 # These control the server-side internal telemetry
 # INTERNAL_OTEL_TRACE_EXPORTER_URL=<URL to send traces to>
-# INTERNAL_OTEL_TRACE_EXPORTER_AUTH_HEADER_NAME=<Header name for the auth token>
-# INTERNAL_OTEL_TRACE_EXPORTER_AUTH_HEADER_VALUE=<Auth token value>
 # INTERNAL_OTEL_TRACE_LOGGING_ENABLED=1
-# INTERNAL_OTEL_TRACE_SAMPING_RATE=20 # this means 1/20 traces or 5% of traces will be sampled (sampled = recorded)
-# 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/workflows/changesets-pr.yml

@@ -0,0 +1,102 @@
+name: 🦋 Changesets PR
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "packages/**"
+      - ".changeset/**"
+      - "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 with version
+        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"
+          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: Commit and push lockfile
+        run: |
+          set -e
+          if git diff --quiet pnpm-lock.yaml; then
+            echo "No lockfile changes"
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git add pnpm-lock.yaml
+            git commit -m "chore: update lockfile for release"
+            git push origin changeset-release/main
+          fi

.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

@@ -1,5 +1,8 @@
 name: "E2E"
 
+permissions:
+  contents: read
+
 on:
   workflow_call:
     inputs:
@@ -28,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.11.1
+          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

@@ -5,6 +5,7 @@ on:
     types: [opened, synchronize, reopened]
     paths-ignore:
       - "docs/**"
+      - ".changeset/**"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@@ -28,3 +29,7 @@ jobs:
     with:
       package: cli-v3
     secrets: inherit
+
+  sdk-compat:
+    uses: ./.github/workflows/sdk-compat.yml
+    secrets: inherit

.github/workflows/publish-webapp.yml

@@ -1,5 +1,10 @@
 name: "🐳 Publish Webapp"
 
+permissions:
+  contents: read
+  packages: write
+  id-token: write
+
 on:
   workflow_call:
     inputs:
@@ -43,13 +48,25 @@ jobs:
           ref_without_tag=ghcr.io/triggerdotdev/trigger.dev
           image_tags=$ref_without_tag:${{ steps.get_tag.outputs.tag }}
 
-          # if tag is a semver, also tag it as v3
+          # if tag is a semver, also tag it as v4
           if [[ "${{ steps.get_tag.outputs.is_semver }}" == true ]]; then
-            image_tags=$image_tags,$ref_without_tag:v3
+            # TODO: switch to v4 tag on GA
+            image_tags=$image_tags,$ref_without_tag:v4-beta
           fi
 
           echo "image_tags=${image_tags}" >> "$GITHUB_OUTPUT"
 
+      - name: 📝 Set the build info
+        id: set_build_info
+        run: |
+          tag=${{ steps.get_tag.outputs.tag }}
+          if [[ "${{ steps.get_tag.outputs.is_semver }}" == true ]]; then
+            echo "BUILD_APP_VERSION=${tag}" >> "$GITHUB_OUTPUT"
+          fi
+          echo "BUILD_GIT_SHA=${{ github.sha }}" >> "$GITHUB_OUTPUT"
+          echo "BUILD_GIT_REF_NAME=${{ github.ref_name }}" >> "$GITHUB_OUTPUT"
+          echo "BUILD_TIMESTAMP_SECONDS=$(date +%s)" >> "$GITHUB_OUTPUT"
+
       - name: 🐙 Login to GitHub Container Registry
         uses: docker/login-action@v3
         with:
@@ -64,3 +81,13 @@ jobs:
           platforms: linux/amd64,linux/arm64
           tags: ${{ steps.set_tags.outputs.image_tags }}
           push: true
+          build-args: |
+            BUILD_APP_VERSION=${{ steps.set_build_info.outputs.BUILD_APP_VERSION }}
+            BUILD_GIT_SHA=${{ steps.set_build_info.outputs.BUILD_GIT_SHA }}
+            BUILD_GIT_REF_NAME=${{ steps.set_build_info.outputs.BUILD_GIT_REF_NAME }}
+            BUILD_TIMESTAMP_SECONDS=${{ steps.set_build_info.outputs.BUILD_TIMESTAMP_SECONDS }}
+            SENTRY_RELEASE=${{ steps.set_build_info.outputs.BUILD_GIT_SHA }}
+            SENTRY_ORG=triggerdev
+            SENTRY_PROJECT=trigger-cloud
+          secrets: |
+            sentry_auth_token=${{ secrets.SENTRY_AUTH_TOKEN }}

.github/workflows/publish-worker-v4.yml

@@ -1,4 +1,4 @@
-name: "⚒️ Publish Worker RE2"
+name: "⚒️ Publish Worker (v4)"
 
 on:
   workflow_call:
@@ -14,6 +14,7 @@ on:
       - "re2-prod-*"
 
 permissions:
+  id-token: write
   packages: write
   contents: read
 
@@ -35,6 +36,9 @@ jobs:
     env:
       DOCKER_BUILDKIT: "1"
     steps:
+      - name: 🏭 Setup Depot CLI
+        uses: depot/setup-action@v1
+
       - name: ⬇️ Checkout git repo
         uses: actions/checkout@v4
 
@@ -49,26 +53,26 @@ jobs:
           fi
           echo "repo=${repo}" >> "$GITHUB_OUTPUT"
 
-      - id: get_tag
+      - name: "#️⃣ Get image tag"
+        id: get_tag
         uses: ./.github/actions/get-image-tag
         with:
           tag: ${{ inputs.image_tag }}
 
-      - name: 🐋 Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      # ..to avoid rate limits when pulling images
-      - name: 🐳 Login to DockerHub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: 🚢 Build Container Image
+      - name: 📛 Set tags to push
+        id: set_tags
         run: |
-          docker build -t infra_image -f ./apps/${{ matrix.package }}/Containerfile .
+          ref_without_tag=ghcr.io/triggerdotdev/${{ steps.get_repository.outputs.repo }}
+          image_tags=$ref_without_tag:${{ steps.get_tag.outputs.tag }}
+
+          # if tag is a semver, also tag it as v4
+          if [[ "${{ steps.get_tag.outputs.is_semver }}" == true ]]; then
+            # TODO: switch to v4 tag on GA
+            image_tags=$image_tags,$ref_without_tag:v4-beta
+          fi
+
+          echo "image_tags=${image_tags}" >> "$GITHUB_OUTPUT"
 
-      # ..to push image
       - name: 🐙 Login to GitHub Container Registry
         uses: docker/login-action@v3
         with:
@@ -76,20 +80,10 @@ jobs:
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: 🐙 Push to GitHub Container Registry
-        run: |
-          docker tag infra_image "$REGISTRY/$REPOSITORY:$IMAGE_TAG"
-          docker push "$REGISTRY/$REPOSITORY:$IMAGE_TAG"
-        env:
-          REGISTRY: ghcr.io/triggerdotdev
-          REPOSITORY: ${{ steps.get_repository.outputs.repo }}
-          IMAGE_TAG: ${{ steps.get_tag.outputs.tag }}
-
-      - name: 🐙 Push 'v3' tag to GitHub Container Registry
-        if: steps.get_tag.outputs.is_semver == 'true'
-        run: |
-          docker tag infra_image "$REGISTRY/$REPOSITORY:v3"
-          docker push "$REGISTRY/$REPOSITORY:v3"
-        env:
-          REGISTRY: ghcr.io/triggerdotdev
-          REPOSITORY: ${{ steps.get_repository.outputs.repo }}
+      - name: 🐳 Build image and push to GitHub Container Registry
+        uses: depot/build-push-action@v1
+        with:
+          file: ./apps/${{ matrix.package }}/Containerfile
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.set_tags.outputs.image_tags }}
+          push: true

.github/workflows/publish-worker.yml

@@ -77,11 +77,11 @@ jobs:
           REPOSITORY: ${{ steps.get_repository.outputs.repo }}
           IMAGE_TAG: ${{ steps.get_tag.outputs.tag }}
 
-      - name: 🐙 Push 'v3' tag to GitHub Container Registry
-        if: steps.get_tag.outputs.is_semver == 'true'
-        run: |
-          docker tag infra_image "$REGISTRY/$REPOSITORY:v3"
-          docker push "$REGISTRY/$REPOSITORY:v3"
-        env:
-          REGISTRY: ghcr.io/triggerdotdev
-          REPOSITORY: ${{ steps.get_repository.outputs.repo }}
+      # - name: 🐙 Push 'v3' tag to GitHub Container Registry
+      #   if: steps.get_tag.outputs.is_semver == 'true'
+      #   run: |
+      #     docker tag infra_image "$REGISTRY/$REPOSITORY:v3"
+      #     docker push "$REGISTRY/$REPOSITORY:v3"
+      #   env:
+      #     REGISTRY: ghcr.io/triggerdotdev
+      #     REPOSITORY: ${{ steps.get_repository.outputs.repo }}

.github/workflows/publish.yml

@@ -1,6 +1,7 @@
 name: 🚀 Publish Trigger.dev Docker
 
 on:
+  workflow_dispatch:
   workflow_call:
     inputs:
       image_tag:
@@ -68,3 +69,10 @@ jobs:
     secrets: inherit
     with:
       image_tag: ${{ inputs.image_tag }}
+
+  publish-worker-v4:
+    needs: [typecheck]
+    uses: ./.github/workflows/publish-worker-v4.yml
+    secrets: inherit
+    with:
+      image_tag: ${{ inputs.image_tag }}

.github/workflows/release-helm.yml

@@ -0,0 +1,143 @@
+name: 🧭 Helm Chart Release
+
+on:
+  push:
+    tags:
+      - 'helm-v*'
+  workflow_dispatch:
+    inputs:
+      chart_version:
+        description: 'Chart version to release'
+        required: true
+        type: string
+
+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"
+
+  release:
+    needs: lint-and-test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # for gh-release
+      packages: 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: Extract version from tag or input
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VERSION="${{ github.event.inputs.chart_version }}"
+          else
+            VERSION="${{ github.ref_name }}"
+            VERSION="${VERSION#helm-v}"
+          fi
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Releasing version: $VERSION"
+
+      - name: Check Chart.yaml version matches release version
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          CHART_VERSION=$(grep '^version:' ./hosting/k8s/helm/Chart.yaml | awk '{print $2}')
+          echo "Chart.yaml version: $CHART_VERSION"
+          echo "Release version: $VERSION"
+          if [ "$CHART_VERSION" != "$VERSION" ]; then
+            echo "❌ Chart.yaml version does not match release version!"
+            exit 1
+          fi
+          echo "✅ Chart.yaml version matches release version."
+
+      - 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: Create GitHub Release
+        id: release
+        uses: softprops/action-gh-release@v1
+        if: github.event_name == 'push'
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: "Helm Chart ${{ steps.version.outputs.version }}"
+          body: |
+            ### Installation
+            ```bash
+            helm upgrade --install trigger \
+              oci://${{ env.REGISTRY }}/${{ github.repository_owner }}/charts/${{ env.CHART_NAME }} \
+              --version "${{ steps.version.outputs.version }}"
+            ```
+            
+            ### Changes
+            See commit history for detailed changes in this release.
+          files: |
+            /tmp/${{ env.CHART_NAME }}-${{ steps.version.outputs.version }}.tgz
+          token: ${{ secrets.GITHUB_TOKEN }}
+          draft: true
+          prerelease: true

.github/workflows/release.yml

@@ -1,101 +1,195 @@
 name: 🦋 Changesets Release
 
 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'
+    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
+      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.11.1
+          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
         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"
 
-  publish:
+      - 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
-    # if: needs.release.outputs.published == 'true'
-    # disable automatic publishing for now
-    if: false
     with:
       image_tag: v${{ 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

@@ -3,6 +3,9 @@ name: "ʦ TypeScript"
 on:
   workflow_call:
 
+permissions:
+  contents: read
+
 jobs:
   typecheck:
     runs-on: ubuntu-latest
@@ -16,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.11.1
+          node-version: 20.20.0
           cache: "pnpm"
 
       - name: 📥 Download deps
@@ -32,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

@@ -0,0 +1,141 @@
+name: "🧪 Unit Tests: Internal"
+
+permissions:
+  contents: read
+
+on:
+  workflow_call:
+
+jobs:
+  unitTests:
+    name: "🧪 Unit Tests: Internal"
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        shardIndex: [1, 2, 3, 4, 5, 6, 7, 8]
+        shardTotal: [8]
+    env:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      SHARD_INDEX: ${{ matrix.shardIndex }}
+      SHARD_TOTAL: ${{ matrix.shardTotal }}
+    steps:
+      - name: 🔧 Disable IPv6
+        run: |
+          sudo sysctl -w net.ipv6.conf.all.disable_ipv6=1
+          sudo sysctl -w net.ipv6.conf.default.disable_ipv6=1
+          sudo sysctl -w net.ipv6.conf.lo.disable_ipv6=1
+
+      - name: 🔧 Configure docker address pool
+        run: |
+          CONFIG='{
+            "default-address-pools" : [
+              {
+                "base" : "172.17.0.0/12",
+                "size" : 20
+              },
+              {
+                "base" : "192.168.0.0/16",
+                "size" : 24
+              }
+            ]
+          }'
+          mkdir -p /etc/docker
+          echo "$CONFIG" | sudo tee /etc/docker/daemon.json
+
+      - name: 🔧 Restart docker daemon
+        run: sudo systemctl restart docker
+
+      - 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"
+
+      # ..to avoid rate limits when pulling images
+      - name: 🐳 Login to DockerHub
+        if: ${{ env.DOCKERHUB_USERNAME }}
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: 🐳 Skipping DockerHub login (no secrets available)
+        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
+
+      - name: 📀 Generate Prisma Client
+        run: pnpm run generate
+
+      - name: 🧪 Run Internal Unit Tests
+        run: pnpm run test:internal --reporter=default --reporter=blob --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
+
+      - name: Gather all reports
+        if: ${{ !cancelled() }}
+        run: |
+          mkdir -p .vitest-reports
+          find . -type f -path '*/.vitest-reports/blob-*.json' \
+            -exec bash -c 'src="$1"; basename=$(basename "$src"); pkg=$(dirname "$src" | sed "s|^\./||;s|/\.vitest-reports$||;s|/|_|g"); cp "$src" ".vitest-reports/${pkg}-${basename}"' _ {} \;
+
+      - name: Upload blob reports to GitHub Actions Artifacts
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: internal-blob-report-${{ matrix.shardIndex }}
+          path: .vitest-reports/*
+          include-hidden-files: true
+          retention-days: 1
+
+  merge-reports:
+    name: "📊 Merge Reports"
+    if: ${{ !cancelled() }}
+    needs: [unitTests]
+    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
+          # no cache enabled, we're not installing deps
+
+      - name: Download blob reports from GitHub Actions Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: .vitest-reports
+          pattern: internal-blob-report-*
+          merge-multiple: true
+
+      - name: Merge reports
+        run: pnpm dlx vitest@3.1.4 run --merge-reports --pass-with-no-tests

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

@@ -0,0 +1,141 @@
+name: "🧪 Unit Tests: Packages"
+
+permissions:
+  contents: read
+
+on:
+  workflow_call:
+
+jobs:
+  unitTests:
+    name: "🧪 Unit Tests: Packages"
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        shardIndex: [1]
+        shardTotal: [1]
+    env:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      SHARD_INDEX: ${{ matrix.shardIndex }}
+      SHARD_TOTAL: ${{ matrix.shardTotal }}
+    steps:
+      - name: 🔧 Disable IPv6
+        run: |
+          sudo sysctl -w net.ipv6.conf.all.disable_ipv6=1
+          sudo sysctl -w net.ipv6.conf.default.disable_ipv6=1
+          sudo sysctl -w net.ipv6.conf.lo.disable_ipv6=1
+
+      - name: 🔧 Configure docker address pool
+        run: |
+          CONFIG='{
+            "default-address-pools" : [
+              {
+                "base" : "172.17.0.0/12",
+                "size" : 20
+              },
+              {
+                "base" : "192.168.0.0/16",
+                "size" : 24
+              }
+            ]
+          }'
+          mkdir -p /etc/docker
+          echo "$CONFIG" | sudo tee /etc/docker/daemon.json
+
+      - name: 🔧 Restart docker daemon
+        run: sudo systemctl restart docker
+
+      - 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"
+
+      # ..to avoid rate limits when pulling images
+      - name: 🐳 Login to DockerHub
+        if: ${{ env.DOCKERHUB_USERNAME }}
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: 🐳 Skipping DockerHub login (no secrets available)
+        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
+
+      - name: 📀 Generate Prisma Client
+        run: pnpm run generate
+
+      - name: 🧪 Run Package Unit Tests
+        run: pnpm run test:packages --reporter=default --reporter=blob --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
+
+      - name: Gather all reports
+        if: ${{ !cancelled() }}
+        run: |
+          mkdir -p .vitest-reports
+          find . -type f -path '*/.vitest-reports/blob-*.json' \
+            -exec bash -c 'src="$1"; basename=$(basename "$src"); pkg=$(dirname "$src" | sed "s|^\./||;s|/\.vitest-reports$||;s|/|_|g"); cp "$src" ".vitest-reports/${pkg}-${basename}"' _ {} \;
+
+      - name: Upload blob reports to GitHub Actions Artifacts
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: packages-blob-report-${{ matrix.shardIndex }}
+          path: .vitest-reports/*
+          include-hidden-files: true
+          retention-days: 1
+
+  merge-reports:
+    name: "📊 Merge Reports"
+    if: ${{ !cancelled() }}
+    needs: [unitTests]
+    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
+          # no cache enabled, we're not installing deps
+
+      - name: Download blob reports from GitHub Actions Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: .vitest-reports
+          pattern: packages-blob-report-*
+          merge-multiple: true
+
+      - name: Merge reports
+        run: pnpm dlx vitest@3.1.4 run --merge-reports --pass-with-no-tests

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

@@ -0,0 +1,149 @@
+name: "🧪 Unit Tests: Webapp"
+
+permissions:
+  contents: read
+
+on:
+  workflow_call:
+
+jobs:
+  unitTests:
+    name: "🧪 Unit Tests: Webapp"
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        shardIndex: [1, 2, 3, 4, 5, 6, 7, 8]
+        shardTotal: [8]
+    env:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      SHARD_INDEX: ${{ matrix.shardIndex }}
+      SHARD_TOTAL: ${{ matrix.shardTotal }}
+    steps:
+      - name: 🔧 Disable IPv6
+        run: |
+          sudo sysctl -w net.ipv6.conf.all.disable_ipv6=1
+          sudo sysctl -w net.ipv6.conf.default.disable_ipv6=1
+          sudo sysctl -w net.ipv6.conf.lo.disable_ipv6=1
+
+      - name: 🔧 Configure docker address pool
+        run: |
+          CONFIG='{
+            "default-address-pools" : [
+              {
+                "base" : "172.17.0.0/12",
+                "size" : 20
+              },
+              {
+                "base" : "192.168.0.0/16",
+                "size" : 24
+              }
+            ]
+          }'
+          mkdir -p /etc/docker
+          echo "$CONFIG" | sudo tee /etc/docker/daemon.json
+
+      - name: 🔧 Restart docker daemon
+        run: sudo systemctl restart docker
+
+      - 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"
+
+      # ..to avoid rate limits when pulling images
+      - name: 🐳 Login to DockerHub
+        if: ${{ env.DOCKERHUB_USERNAME }}
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: 🐳 Skipping DockerHub login (no secrets available)
+        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
+
+      - name: 📀 Generate Prisma Client
+        run: pnpm run generate
+
+      - name: 🧪 Run Webapp Unit Tests
+        run: pnpm run test:webapp --reporter=default --reporter=blob --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
+        env:
+          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/postgres
+          DIRECT_URL: postgresql://postgres:postgres@localhost:5432/postgres
+          SESSION_SECRET: "secret"
+          MAGIC_LINK_SECRET: "secret"
+          ENCRYPTION_KEY: "dummy-encryption-keeeey-32-bytes"
+          DEPLOY_REGISTRY_HOST: "docker.io"
+          CLICKHOUSE_URL: "http://default:password@localhost:8123"
+
+      - name: Gather all reports
+        if: ${{ !cancelled() }}
+        run: |
+          mkdir -p .vitest-reports
+          find . -type f -path '*/.vitest-reports/blob-*.json' \
+            -exec bash -c 'src="$1"; basename=$(basename "$src"); pkg=$(dirname "$src" | sed "s|^\./||;s|/\.vitest-reports$||;s|/|_|g"); cp "$src" ".vitest-reports/${pkg}-${basename}"' _ {} \;
+
+      - name: Upload blob reports to GitHub Actions Artifacts
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: webapp-blob-report-${{ matrix.shardIndex }}
+          path: .vitest-reports/*
+          include-hidden-files: true
+          retention-days: 1
+
+  merge-reports:
+    name: "📊 Merge Reports"
+    if: ${{ !cancelled() }}
+    needs: [unitTests]
+    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
+          # no cache enabled, we're not installing deps
+
+      - name: Download blob reports from GitHub Actions Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: .vitest-reports
+          pattern: webapp-blob-report-*
+          merge-multiple: true
+
+      - name: Merge reports
+        run: pnpm dlx vitest@3.1.4 run --merge-reports --pass-with-no-tests

.github/workflows/unit-tests.yml

@@ -1,53 +1,18 @@
 name: "🧪 Unit Tests"
 
+permissions:
+  contents: read
+
 on:
   workflow_call:
 
 jobs:
-  unitTests:
-    name: "🧪 Unit Tests"
-    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: 8.15.5
-
-      - name: ⎔ Setup node
-        uses: buildjet/setup-node@v4
-        with:
-          node-version: 20.11.1
-          cache: "pnpm"
-
-      # ..to avoid rate limits when pulling images
-      - name: 🐳 Login to DockerHub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: 📥 Download deps
-        run: pnpm install --frozen-lockfile
-
-      - name: 📀 Generate Prisma Client
-        run: pnpm run generate
-
-      - name: 🧪 Run Webapp Unit Tests
-        run: pnpm run test:webapp
-        env:
-          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/postgres
-          DIRECT_URL: postgresql://postgres:postgres@localhost:5432/postgres
-          SESSION_SECRET: "secret"
-          MAGIC_LINK_SECRET: "secret"
-          ENCRYPTION_KEY: "secret"
-      
-      - name: 🧪 Run Package Unit Tests
-        run: pnpm run test:packages
-      
-      - name: 🧪 Run Internal Unit Tests
-        run: pnpm run test:internal
+  webapp:
+    uses: ./.github/workflows/unit-tests-webapp.yml
+    secrets: inherit
+  packages:
+    uses: ./.github/workflows/unit-tests-packages.yml
+    secrets: inherit
+  internal:
+    uses: ./.github/workflows/unit-tests-internal.yml
+    secrets: inherit

.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,3 +64,7 @@ apps/**/public/build
 /packages/core/src/package.json
 /packages/trigger-sdk/src/package.json
 /packages/python/src/package.json
+**/.claude/settings.local.json
+.mcp.log
+.mcp.json
+.cursor/debug.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.11.1
+v20.20.0

.vscode/launch.json

@@ -59,7 +59,7 @@
       "request": "launch",
       "name": "Debug V3 Dev CLI",
       "command": "pnpm exec trigger dev",
-      "cwd": "${workspaceFolder}/references/v3-catalog",
+      "cwd": "${workspaceFolder}/references/hello-world",
       "sourceMaps": true
     },
     {
@@ -83,7 +83,7 @@
       "request": "launch",
       "name": "Debug V3 Deploy CLI",
       "command": "pnpm exec trigger deploy --self-hosted --load-image",
-      "cwd": "${workspaceFolder}/references/v3-catalog",
+      "cwd": "${workspaceFolder}/references/hello-world",
       "sourceMaps": true
     },
     {
@@ -91,7 +91,7 @@
       "request": "launch",
       "name": "Debug V3 list-profiles CLI",
       "command": "pnpm exec trigger list-profiles --log-level debug",
-      "cwd": "${workspaceFolder}/references/v3-catalog",
+      "cwd": "${workspaceFolder}/references/hello-world",
       "sourceMaps": true
     },
     {
@@ -99,7 +99,7 @@
       "request": "launch",
       "name": "Debug V3 update CLI",
       "command": "pnpm exec trigger update",
-      "cwd": "${workspaceFolder}/references/v3-catalog",
+      "cwd": "${workspaceFolder}/references/hello-world",
       "sourceMaps": true
     },
     {
@@ -107,7 +107,7 @@
       "request": "launch",
       "name": "Debug V3 Management",
       "command": "pnpm run management",
-      "cwd": "${workspaceFolder}/references/v3-catalog",
+      "cwd": "${workspaceFolder}/references/hello-world",
       "sourceMaps": true
     },
     {
@@ -146,7 +146,7 @@
       "type": "node-terminal",
       "request": "launch",
       "name": "Debug RunQueue tests",
-      "command": "pnpm run test ./src/run-queue/index.test.ts",
+      "command": "pnpm run test ./src/run-queue/index.test.ts --run",
       "cwd": "${workspaceFolder}/internal-packages/run-engine",
       "sourceMaps": true
     },

.vscode/settings.json

@@ -6,5 +6,6 @@
     "**/node_modules/**": true,
     "packages/cli-v3/e2e": true
   },
-  "vitest.disableWorkspaceWarning": true
+  "vitest.disableWorkspaceWarning": true,
+  "typescript.experimental.useTsgo": false
 }

AGENTS.md

@@ -0,0 +1,68 @@
+# Guidance for Coding Agents
+
+This repository is a pnpm monorepo managed with Turbo. It contains multiple apps and packages that make up the Trigger.dev platform and SDK.
+
+## Repository layout
+- `apps/webapp` – Remix application that serves as the main API and dashboard.
+- `apps/supervisor` – Node application for executing built tasks.
+- `packages/*` – Published packages such as `@trigger.dev/sdk`, the CLI (`trigger.dev`), and shared libraries.
+- `internal-packages/*` – Internal-only packages used by the webapp and other apps.
+- `references/*` – Example projects for manual testing and development of new features.
+- `ai/references` – Contains additional documentation including an overview (`repo.md`) and testing guidelines (`tests.md`).
+
+See `ai/references/repo.md` for a more complete explanation of the workspaces.
+
+## Development setup
+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
+   pnpm run docker
+   ```
+4. Run database migrations:
+   ```bash
+   pnpm run db:migrate
+   ```
+5. Build the webapp, CLI and SDK packages:
+   ```bash
+   pnpm run build --filter webapp && pnpm run build --filter trigger.dev && pnpm run build --filter @trigger.dev/sdk
+   ```
+6. Launch the development server:
+   ```bash
+   pnpm run dev --filter webapp
+   ```
+   The webapp runs on <http://localhost:3030>.
+
+For full setup instructions see `CONTRIBUTING.md`.
+
+## Running tests
+- Unit tests use **vitest**. Run all tests:
+  ```bash
+  pnpm run test
+  ```
+- Run tests for a specific workspace (example for `webapp`):
+  ```bash
+  pnpm run test --filter webapp
+  ```
+- Prefer running a single test file from within its directory:
+  ```bash
+  cd apps/webapp
+  pnpm run test ./src/components/Button.test.ts
+  ```
+  If packages in that workspace need to be built first, run `pnpm run build --filter webapp`.
+
+Refer to `ai/references/tests.md` for details on writing tests. Tests should avoid mocks or stubs and use the helpers from `@internal/testcontainers` when Redis or Postgres are needed.
+
+## Coding style
+- Formatting is enforced using Prettier. Run `pnpm run format` before committing.
+- Follow the existing project conventions. Test files live beside the files under test and use descriptive `describe` and `it` blocks.
+- Do not commit directly to the `main` branch. All changes should be made in a separate branch and go through a pull request.
+
+## Additional docs
+- The root `README.md` describes Trigger.dev and links to documentation.
+- The `docs` workspace contains our documentation site, which can be run locally with:
+  ```bash
+  pnpm run dev --filter docs
+  ```
+- `references/README.md` explains how to create new reference projects for manual testing.
+

CHANGESETS.md

@@ -30,28 +30,16 @@ Please follow the best-practice of adding changesets in the same commit as the c
 
 ## Snapshot instructions
 
-!MAKE SURE TO UPDATE THE TAG IN THE INSTRUCTIONS BELOW!
+1. Update the `.changeset/config.json` file to set the `"changelog"` field to this:
 
-1. Add changesets as usual
-
-```sh
-pnpm run changeset:add
+```json
+"changelog": "@changesets/cli/changelog",
 ```
 
-2. Create a snapshot version (replace "prerelease" with your tag)
+2. Do a temporary commit (do NOT push this, you should undo it after)
 
-```sh
-pnpm exec changeset version --snapshot prerelease
-```
+3. Run `./scripts/publish-prerelease.sh prerelease`
 
-3. Build the packages:
+You can choose a different tag if you want, but usually `prerelease` is fine.
 
-```sh
-pnpm run build --filter "@trigger.dev/*" --filter "trigger.dev"
-```
-
-4. Publish the snapshot (replace "dev" with your tag)
-
-```sh
-pnpm exec changeset publish --no-git-tag --snapshot --tag prerelease
-```
+5. Undo the commit where you updated the config.json file.

CLAUDE.md

@@ -0,0 +1,303 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Development Commands
+
+This is a pnpm 10.23.0 monorepo using Turborepo. Run commands from root with `pnpm run`.
+
+### Essential Commands
+
+```bash
+# Start Docker services (PostgreSQL, Redis, Electric)
+pnpm run docker
+
+# Run database migrations
+pnpm run db:migrate
+
+# Seed the database (required for reference projects)
+pnpm run db:seed
+
+# Build packages (required before running)
+pnpm run build --filter webapp && pnpm run build --filter trigger.dev && pnpm run build --filter @trigger.dev/sdk
+
+# Run webapp in development mode (http://localhost:3030)
+pnpm run dev --filter webapp
+
+# Build and watch for changes (CLI and packages)
+pnpm run dev --filter trigger.dev --filter "@trigger.dev/*"
+```
+
+### Testing
+
+We use vitest exclusively. **Never mock anything** - use testcontainers instead.
+
+```bash
+# Run all tests for a package
+pnpm run test --filter webapp
+
+# Run a single test file (preferred - cd into directory first)
+cd internal-packages/run-engine
+pnpm run test ./src/engine/tests/ttl.test.ts --run
+
+# May need to build dependencies first
+pnpm run build --filter @internal/run-engine
+```
+
+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";
+
+// Redis only
+redisTest("should use redis", async ({ redisOptions }) => {
+  /* ... */
+});
+
+// PostgreSQL only
+postgresTest("should use postgres", async ({ prisma }) => {
+  /* ... */
+});
+
+// Both Redis and PostgreSQL
+containerTest("should use both", async ({ prisma, redisOptions }) => {
+  /* ... */
+});
+```
+
+### Changesets
+
+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 (breaking changes) without explicit approval
+
+## Architecture Overview
+
+### Apps
+
+- **apps/webapp**: Remix 2.1.0 app - main API, dashboard, and Docker image. Uses Express server.
+- **apps/supervisor**: Node.js app handling task execution, interfacing with Docker/Kubernetes.
+
+### Public Packages
+
+- **packages/trigger-sdk** (`@trigger.dev/sdk`): Main SDK
+- **packages/cli-v3** (`trigger.dev`): CLI package
+- **packages/core** (`@trigger.dev/core`): Shared code between SDK and webapp. Import subpaths only (never root).
+- **packages/build**: Build extensions and types
+- **packages/react-hooks**: React hooks for realtime and triggering
+- **packages/redis-worker** (`@trigger.dev/redis-worker`): Custom Redis-based background job system
+
+### Internal Packages
+
+- **internal-packages/database** (`@trigger.dev/database`): Prisma 6.14.0 client and schema
+- **internal-packages/clickhouse** (`@internal/clickhouse`): ClickHouse client and schema migrations
+- **internal-packages/run-engine** (`@internal/run-engine`): "Run Engine 2.0" - run lifecycle management
+- **internal-packages/redis** (`@internal/redis`): Redis client creation utilities
+- **internal-packages/testcontainers** (`@internal/testcontainers`): Test helpers for Redis/PostgreSQL containers
+- **internal-packages/zodworker** (`@internal/zodworker`): Graphile-worker wrapper (being replaced by redis-worker)
+
+### Reference Projects
+
+The `references/` directory contains test workspaces for developing and testing new SDK and platform features. Use these projects (e.g., `references/hello-world`) to manually test changes to the CLI, SDK, core packages, and webapp before submitting PRs.
+
+## Webapp Development
+
+### Key Locations
+
+- Trigger API: `apps/webapp/app/routes/api.v1.tasks.$taskId.trigger.ts`
+- Batch trigger: `apps/webapp/app/routes/api.v1.tasks.batch.ts`
+- Prisma setup: `apps/webapp/app/db.server.ts`
+- Run engine config: `apps/webapp/app/v3/runEngine.server.ts`
+- Services: `apps/webapp/app/v3/services/**/*.server.ts`
+- Presenters: `apps/webapp/app/v3/presenters/**/*.server.ts`
+- OTEL endpoints: `apps/webapp/app/routes/otel.v1.logs.ts`, `otel.v1.traces.ts`
+
+### Environment Variables
+
+Access via `env` export from `apps/webapp/app/env.server.ts`, never `process.env` directly.
+
+For testable code, **never import env.server.ts** in test files. Pass configuration as options instead. Example pattern:
+
+- `realtimeClient.server.ts` (testable service)
+- `realtimeClientGlobal.server.ts` (configuration)
+
+### Legacy vs Run Engine 2.0
+
+The codebase is transitioning from the "legacy run engine" (spread across codebase) to "Run Engine 2.0" (`@internal/run-engine`). Focus on Run Engine 2.0 for new work.
+
+## Docker Image Guidelines
+
+When updating Docker image references in `docker/Dockerfile` or other container files:
+
+- **Always use multiplatform/index digests**, not architecture-specific digests
+- Architecture-specific digests (e.g., for `linux/amd64` only) will cause CI failures on different build environments
+- On Docker Hub, the multiplatform digest is shown on the main image page, while architecture-specific digests are listed under "OS/ARCH"
+- Example: Use `node:20.20-bullseye-slim@sha256:abc123...` where the digest is from the multiplatform index, not from a specific OS/ARCH variant
+
+## Database Migrations (PostgreSQL)
+
+1. Edit `internal-packages/database/prisma/schema.prisma`
+2. Create migration:
+   ```bash
+   cd internal-packages/database
+   pnpm run db:migrate:dev:create --name "add_new_column"
+   ```
+3. **Important**: Generated migration includes extraneous changes. Remove lines related to:
+   - `_BackgroundWorkerToBackgroundWorkerFile`
+   - `_BackgroundWorkerToTaskQueue`
+   - `_TaskRunToTaskRunTag`
+   - `_WaitpointRunConnections`
+   - `_completedWaitpoints`
+   - `SecretStore_key_idx`
+   - Various `TaskRun` indexes unless you added them
+4. Apply migration:
+   ```bash
+   pnpm run db:migrate:deploy && pnpm run generate
+   ```
+
+### Index Migration Rules
+
+- Indexes **must use CONCURRENTLY** to avoid table locks
+- **CONCURRENTLY indexes must be in their own separate migration file** - they cannot be combined with other schema changes
+
+## ClickHouse Migrations
+
+ClickHouse migrations use Goose format and live in `internal-packages/clickhouse/schema/`.
+
+1. Create a new numbered SQL file (e.g., `010_add_new_column.sql`)
+2. Use Goose markers:
+
+   ```sql
+   -- +goose Up
+   ALTER TABLE trigger_dev.your_table
+   ADD COLUMN new_column String DEFAULT '';
+
+   -- +goose Down
+   ALTER TABLE trigger_dev.your_table
+   DROP COLUMN new_column;
+   ```
+
+Follow naming conventions in `internal-packages/clickhouse/README.md`:
+
+- `raw_` prefix for input tables
+- `_v1`, `_v2` suffixes for versioning
+- `_mv_v1` suffix for materialized views
+
+## Writing Trigger.dev Tasks
+
+Always import from `@trigger.dev/sdk`. Never use `@trigger.dev/sdk/v3` or deprecated `client.defineJob` pattern.
+
+```typescript
+import { task } from "@trigger.dev/sdk";
+
+// Every task must be exported
+export const myTask = task({
+  id: "my-task", // Unique ID
+  run: async (payload: { message: string }) => {
+    // Task logic - no timeouts
+  },
+});
+```
+
+### SDK Documentation Rules
+
+The `rules/` directory contains versioned documentation for writing Trigger.dev tasks, distributed to users via the SDK installer. Current version is defined in `rules/manifest.json`.
+
+- `rules/4.3.0/` - Latest: batch trigger v2 (1,000 items, 3MB payloads), debouncing
+- `rules/4.1.0/` - Realtime streams v2, updated config
+- `rules/4.0.0/` - Base v4 SDK documentation
+
+When adding new SDK features, create a new version directory with only the files that changed from the previous version. Update `manifest.json` to point unchanged files to previous versions.
+
+### Claude Code Skill
+
+The `.claude/skills/trigger-dev-tasks/` skill provides Claude Code with Trigger.dev task expertise. It includes:
+
+- `SKILL.md` - Core instructions and patterns
+- Reference files for basic tasks, advanced tasks, scheduled tasks, realtime, and config
+
+Keep the skill in sync with the latest rules version when SDK features change.
+
+## Testing with hello-world Reference Project
+
+First-time setup:
+
+1. Run `pnpm run db:seed` to seed the database (creates the hello-world project)
+2. Build CLI: `pnpm run build --filter trigger.dev && pnpm i`
+3. Authorize CLI: `cd references/hello-world && pnpm exec trigger login -a http://localhost:3030`
+
+Running:
+
+```bash
+cd references/hello-world
+pnpm exec trigger dev  # or with --log-level debug
+```
+
+## Local Task Testing Workflow
+
+This workflow enables Claude Code to run the webapp and trigger dev simultaneously, trigger tasks, and inspect results for testing code changes.
+
+### Step 1: Start Webapp in Background
+
+```bash
+# Run from repo root with run_in_background: true
+pnpm run dev --filter webapp
+```
+
+Verify webapp is running:
+
+```bash
+curl -s http://localhost:3030/healthcheck  # Should return 200
+```
+
+### Step 2: Start Trigger Dev in Background
+
+```bash
+# Run from hello-world directory with run_in_background: true
+cd references/hello-world && pnpm exec trigger dev
+```
+
+The worker will build and register tasks. Check output for "Local worker ready [node]" message.
+
+### Step 3: Trigger and Monitor Tasks via MCP
+
+Use the Trigger.dev MCP tools to interact with tasks:
+
+```
+# Get current worker and registered tasks
+mcp__trigger__get_current_worker(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev")
+
+# Trigger a task
+mcp__trigger__trigger_task(
+  projectRef: "proj_rrkpdguyagvsoktglnod",
+  environment: "dev",
+  taskId: "hello-world",
+  payload: {"message": "Hello from Claude"}
+)
+
+# List runs to see status
+mcp__trigger__list_runs(
+  projectRef: "proj_rrkpdguyagvsoktglnod",
+  environment: "dev",
+  taskIdentifier: "hello-world",
+  limit: 5
+)
+```
+
+### Step 4: Monitor Execution
+
+- Check trigger dev output file for real-time execution logs
+- Successful runs show: `Task | Run ID | Success (Xms)`
+- Dashboard available at: http://localhost:3030/orgs/references-9dfd/projects/hello-world-97DT/env/dev/runs
+
+### Key Project Refs
+
+- hello-world: `proj_rrkpdguyagvsoktglnod`

CONTRIBUTING.md

@@ -14,8 +14,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 +34,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.
    ```
@@ -62,15 +62,13 @@ branch are tagged into a release periodically.
    pnpm run docker
    ```
 
-   This will also start and run a local instance of [pgAdmin](https://www.pgadmin.org/) on [localhost:5480](http://localhost:5480), preconfigured with email `admin@example.com` and pwd `admin`. Then use `postgres` as the password to the Trigger.dev server.
-
 9. Migrate the database
    ```
    pnpm run db:migrate
    ```
-10. Build the server app
+10. Build everything
     ```
-    pnpm run build --filter webapp
+    pnpm run build --filter webapp && pnpm run build --filter trigger.dev && pnpm run build --filter @trigger.dev/sdk
     ```
 11. Run the app. See the section below.
 
@@ -86,21 +84,19 @@ branch are tagged into a release periodically.
 
 2. Once the app is running click the magic link button and enter your email. You will automatically be logged in, since you are running locally. Create an Org and your first project in the dashboard.
 
-## Manual testing using v3-catalog
+## Manual testing using hello-world
 
-We use the `<root>/references/v3-catalog` subdirectory as a staging ground for testing changes to the SDK (`@trigger.dev/sdk` at `<root>/packages/trigger-sdk`), the Core package (`@trigger.dev/core` at `<root>packages/core`), the CLI (`trigger.dev` at `<root>/packages/cli-v3`) and the platform (The remix app at `<root>/apps/webapp`). The instructions below will get you started on using the `v3-catalog` for local development of Trigger.dev (v3).
+We use the `<root>/references/hello-world` subdirectory as a staging ground for testing changes to the SDK (`@trigger.dev/sdk` at `<root>/packages/trigger-sdk`), the Core package (`@trigger.dev/core` at `<root>packages/core`), the CLI (`trigger.dev` at `<root>/packages/cli-v3`) and the platform (The remix app at `<root>/apps/webapp`). The instructions below will get you started on using the `hello-world` for local development of Trigger.dev.
 
 ### First-time setup
 
 First, make sure you are running the webapp according to the instructions above. Then:
 
-1. In Postgres go to the "Organizations" table and on your org set the `v3Enabled` column to `true`.
+1. Visit http://localhost:3030 in your browser and create a new project called "hello-world".
 
-2. Visit http://localhost:3030 in your browser and create a new V3 project called "v3-catalog". If you don't see an option for V3, you haven't set the `v3Enabled` flag to true.
+2. In Postgres go to the "Projects" table and for the project you create change the `externalRef` to `proj_rrkpdguyagvsoktglnod`.
 
-3. In Postgres go to the "Projects" table and for the project you create change the `externalRef` to `yubjwjsfkxnylobaqvqz`.
-
-4. Build the CLI
+3. Build the CLI
 
 ```sh
 # Build the CLI
@@ -109,10 +105,10 @@ pnpm run build --filter trigger.dev
 pnpm i
 ```
 
-5. Change into the `<root>/references/v3-catalog` directory and authorize the CLI to the local server:
+4. Change into the `<root>/references/hello-world` directory and authorize the CLI to the local server:
 
 ```sh
-cd references/v3-catalog
+cd references/hello-world
 cp .env.example .env
 pnpm exec trigger login -a http://localhost:3030
 ```
@@ -122,7 +118,7 @@ This will open a new browser window and authorize the CLI against your local use
 You can optionally pass a `--profile` flag to the `login` command, which will allow you to use the CLI with separate accounts/servers. We suggest using a profile called `local` for your local development:
 
 ```sh
-cd references/v3-catalog
+cd references/hello-world
 pnpm exec trigger login -a http://localhost:3030 --profile local
 # later when you run the dev or deploy command:
 pnpm exec trigger dev --profile local
@@ -131,7 +127,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
 
@@ -141,84 +137,29 @@ The following steps should be followed any time you start working on a new featu
 pnpm run dev --filter trigger.dev --filter "@trigger.dev/*"
 ```
 
-3. Open another terminal window, and change into the `<root>/references/v3-catalog` directory.
+3. Open another terminal window, and change into the `<root>/references/hello-world` directory.
 
-4. You'll need to run the following commands to setup prisma and migrate the database:
+4. Run the `dev` command, which will register all the local tasks with the platform and allow you to start testing task execution:
 
 ```sh
-pnpm exec prisma migrate deploy
-pnpm run generate:prisma
-```
-
-5. Run the `dev` command, which will register all the local tasks with the platform and allow you to start testing task execution:
-
-```sh
-# in <root>/references/v3-catalog
+# in <root>/references/hello-world
 pnpm exec trigger dev
 ```
 
 If you want additional debug logging, you can use the `--log-level debug` flag:
 
 ```sh
-# in <root>/references/v3-catalog
+# in <root>/references/hello-world
 pnpm exec trigger dev --log-level debug
 ```
 
-6. If you make any changes in the CLI/Core/SDK, you'll need to `CTRL+C` to exit the `dev` command and restart it to pickup changes. Any changes to the files inside of the `v3-catalog/src/trigger` dir will automatically be rebuilt by the `dev` command.
+6. If you make any changes in the CLI/Core/SDK, you'll need to `CTRL+C` to exit the `dev` command and restart it to pickup changes. Any changes to the files inside of the `hello-world/src/trigger` dir will automatically be rebuilt by the `dev` command.
 
-7. Navigate to the `v3-catalog` project in your local dashboard at localhost:3030 and you should see the list of tasks.
+7. Navigate to the `hello-world` project in your local dashboard at localhost:3030 and you should see the list of tasks.
 
-8. Go to the "Test" page in the sidebar and select a task. Then enter a payload and click "Run test". You can tell what the payloads should be by looking at the relevant task file inside the `/references/v3-catalog/src/trigger` folder. Many of them accept an empty payload.
+8. Go to the "Test" page in the sidebar and select a task. Then enter a payload and click "Run test". You can tell what the payloads should be by looking at the relevant task file inside the `/references/hello-world/src/trigger` folder. Many of them accept an empty payload.
 
-9. Feel free to add additional files in `v3-catalog/src/trigger` to test out specific aspects of the system, or add in edge cases.
-
-## Running end-to-end webapp tests (deprecated)
-
-To run the end-to-end tests, follow the steps below:
-
-1. Set up environment variables (copy example envs into the correct place)
-
-```sh
-cp ./.env.example ./.env
-cp ./references/nextjs-test/.env.example ./references/nextjs-test/.env.local
-```
-
-2. Set up dependencies
-
-```sh
-# Build packages
-pnpm run build --filter @references/nextjs-test^...
-pnpm --filter @trigger.dev/database generate
-
-# Move trigger-cli bin to correct place
-pnpm install --frozen-lockfile
-
-# Install playwrite browsers (ONE TIME ONLY)
-npx playwright install
-```
-
-3. Set up the database
-
-```sh
-pnpm run docker
-pnpm run db:migrate
-pnpm run db:seed
-```
-
-4. Run the end-to-end tests
-
-```sh
-pnpm run test:e2e
-```
-
-### Cleanup
-
-The end-to-end tests use a `setup` and `teardown` script to seed the database with test data. If the test runner doesn't exit cleanly, then the database can be left in a state where the tests can't run because the `setup` script will try to create data that already exists. If this happens, you can manually delete the `users` and `organizations` from the database using prisma studio:
-
-```sh
-# With the database running (i.e. pnpm run docker)
-pnpm run db:studio
-```
+9. Feel free to add additional files in `hello-world/src/trigger` to test out specific aspects of the system, or add in edge cases.
 
 ## Adding and running migrations
 

README.md

@@ -1,44 +1,76 @@
 <div align="center">
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://imagedelivery.net/3TbraffuDZ4aEf8KWOmI_w/a45d1fa2-0ae8-4a39-4409-f4f934bfae00/public">
-  <source media="(prefers-color-scheme: light)" srcset="https://imagedelivery.net/3TbraffuDZ4aEf8KWOmI_w/3f5ad4c1-c4c8-4277-b622-290e7f37bd00/public">
-  <img alt="Trigger.dev logo" src="https://imagedelivery.net/3TbraffuDZ4aEf8KWOmI_w/a45d1fa2-0ae8-4a39-4409-f4f934bfae00/public">
-</picture>
-  
-### Open source background jobs and AI infrastructure
 
-[Discord](https://trigger.dev/discord) | [Website](https://trigger.dev) | [Issues](https://github.com/triggerdotdev/trigger.dev/issues) | [Docs](https://trigger.dev/docs)
+![Trigger.dev logo](https://content.trigger.dev/github-header-banner.jpg)
 
-[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/triggerdotdev.svg?style=social&label=Follow%20%40trigger.dev)](https://twitter.com/triggerdotdev)
+### 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) | [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)
+[![npm](https://img.shields.io/npm/v/@trigger.dev/sdk.svg?label=npm)](https://www.npmjs.com/package/@trigger.dev/sdk)
+[![SDK downloads](https://img.shields.io/npm/dm/@trigger.dev/sdk.svg?label=SDK%20downloads)](https://www.npmjs.com/package/@trigger.dev/sdk)
+
+[![Twitter Follow](https://img.shields.io/twitter/follow/triggerdotdev?style=social)](https://twitter.com/triggerdotdev)
+[![Discord](https://img.shields.io/discord/1066956501299777596?logo=discord&logoColor=white&color=7289da)](https://discord.gg/nkqV9xBYWy)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/triggerdotdev/trigger.dev)
+[![GitHub stars](https://img.shields.io/github/stars/triggerdotdev/trigger.dev?style=social)](https://github.com/triggerdotdev/trigger.dev)
 
 </div>
 
 ## About Trigger.dev
 
-Trigger.dev is an open source platform and SDK which allows you to create long-running background jobs. Write normal async code, deploy, and never hit a timeout.
+Trigger.dev is the open-source platform for building AI workflows in TypeScript. Long-running tasks with retries, queues, observability, and elastic scaling.
 
-### Key features:
+## The platform designed for building AI agents
 
-- JavaScript and TypeScript SDK
-- No timeouts
-- Retries (with exponential backoff)
-- Queues and concurrency controls
-- Schedules and crons
-- Full Observability; logs, live trace views, advanced filtering
-- React hooks to interact with the Trigger API from your React app
-- Pipe LLM streams straight to your users through the Realtime API
-- Trigger tasks and display the run status and metadata anywhere in your app
-- Custom alerts, get notified by email, Slack or webhooks
-- No infrastructure to manage
-- Elastic (scaling)
-- Works with your existing tech stack
+Build [AI agents](https://trigger.dev/product/ai-agents) using all the frameworks, services and LLMs you're used to, deploy them to Trigger.dev and get durable, long-running tasks with retries, queues, observability, and elastic scaling out of the box.
 
-## In your codebase
+- **Long-running without timeouts**: Execute your tasks with absolutely no timeouts, unlike AWS Lambda, Vercel, and other serverless platforms.
+
+- **Durability, retries & queues**: Build rock solid agents and AI applications using our durable tasks, retries, queues and idempotency.
+
+- **True runtime freedom**: Customize your deployed tasks with system packages – run browsers, Python scripts, FFmpeg and more.
+
+- **Human-in-the-loop**: Programmatically pause your tasks until a human can approve, reject or give feedback.
+
+- **Realtime apps & streaming**: Move your background jobs to the foreground by subscribing to runs or streaming AI responses to your app.
+
+- **Observability & monitoring**: Each run has full tracing and logs. Configure error alerts to catch bugs fast.
+
+## Key features:
+
+- **[JavaScript and TypeScript SDK](https://trigger.dev/docs/tasks/overview)** - Build background tasks using familiar programming models
+- **[Long-running tasks](https://trigger.dev/docs/runs/max-duration)** - Handle resource-heavy tasks without timeouts
+- **[Durable cron schedules](https://trigger.dev/docs/tasks/scheduled#scheduled-tasks-cron)** - Create and attach recurring schedules of up to a year
+- **[Trigger.dev Realtime](https://trigger.dev/docs/realtime/overview)** - Trigger, subscribe to, and get real-time updates for runs, with LLM streaming support
+- **[Build extensions](https://trigger.dev/docs/config/extensions/overview#build-extensions)** - Hook directly into the build system and customize the build process. Run Python scripts, FFmpeg, browsers, and more.
+- **[React hooks](https://trigger.dev/docs/frontend/react-hooks#react-hooks)** - Interact with the Trigger.dev API on your frontend using our React hooks package
+- **[Batch triggering](https://trigger.dev/docs/triggering#tasks-batchtrigger)** - Use batchTrigger() to initiate multiple runs of a task with custom payloads and options
+- **[Structured inputs / outputs](https://trigger.dev/docs/tasks/schemaTask#schematask)** - Define precise data schemas for your tasks with runtime payload validation
+- **[Waits](https://trigger.dev/docs/wait)** - Add waits to your tasks to pause execution for a specified duration
+- **[Preview branches](https://trigger.dev/docs/deployment/preview-branches)** - Create isolated environments for testing and development. Integrates with Vercel and git workflows
+- **[Waitpoints](https://trigger.dev/docs/wait-for-token#wait-for-token)** - Add human-in-the-loop judgment at critical decision points without disrupting workflow
+- **[Concurrency & queues](https://trigger.dev/docs/queue-concurrency#concurrency-and-queues)** - Set concurrency rules to manage how multiple tasks execute
+- **[Multiple environments](https://trigger.dev/docs/how-it-works#dev-mode)** - Support for DEV, PREVIEW, STAGING, and PROD environments
+- **[No infrastructure to manage](https://trigger.dev/docs/how-it-works#trigger-dev-architecture)** - Auto-scaling infrastructure that eliminates timeouts and server management
+- **[Automatic retries](https://trigger.dev/docs/errors-retrying)** - If your task encounters an uncaught error, we automatically attempt to run it again
+- **[Checkpointing](https://trigger.dev/docs/how-it-works#the-checkpoint-resume-system)** - Tasks are inherently durable, thanks to our checkpointing feature
+- **[Versioning](https://trigger.dev/docs/versioning)** - Atomic versioning allows you to deploy new versions without affecting running tasks
+- **[Machines](https://trigger.dev/docs/machines)** - Configure the number of vCPUs and GBs of RAM you want the task to use
+- **[Observability & monitoring](https://trigger.dev/product/observability-and-monitoring)** - Monitor every aspect of your tasks' performance with comprehensive logging and visualization tools
+- **[Logging & tracing](https://trigger.dev/docs/logging)** - Comprehensive logging and tracing for all your tasks
+- **[Tags](https://trigger.dev/docs/tags#tags)** - Attach up to ten tags to each run, allowing you to filter via the dashboard, realtime, and the SDK
+- **[Run metadata](https://trigger.dev/docs/runs/metadata#run-metadata)** - Attach metadata to runs which updates as the run progresses and is available to use in your frontend for live updates
+- **[Bulk actions](https://trigger.dev/docs/bulk-actions)** - Perform actions on multiple runs simultaneously, including replaying and cancelling
+- **[Real-time alerts](https://trigger.dev/docs/troubleshooting-alerts#alerts)** - Choose your preferred notification method for run failures and deployments
+
+## Write tasks in your codebase
 
 Create tasks where they belong: in your codebase. Version control, localhost, test and review like you're already used to.
 
 ```ts
-import { task } from "@trigger.dev/sdk/v3";
+import { task } from "@trigger.dev/sdk";
 
 //1. You need to export each task
 export const helloWorld = task({
@@ -58,13 +90,13 @@ Use our SDK to write tasks in your codebase. There's no infrastructure to manage
 
 ## Environments
 
-We support `Development`, `Staging`, and `Production` environments, allowing you to test your tasks before deploying them to production.
+We support `Development`, `Staging`, `Preview`, and `Production` environments, allowing you to test your tasks before deploying them to production.
 
 ## Full visibility of every job run
 
 View every task in every run so you can tell exactly what happened. We provide a full trace view of every task run so you can see what happened at every step.
 
-![Trace view image](https://imagedelivery.net/3TbraffuDZ4aEf8KWOmI_w/7c1b347f-004c-4482-38a7-3f6fa9c00d00/public)
+![Trace view image](https://content.trigger.dev/trace-view.png)
 
 # Getting started
 
@@ -73,14 +105,19 @@ The quickest way to get started is to create an account and project in our [web
 ### Useful links:
 
 - [Quick start](https://trigger.dev/docs/quick-start) - get up and running in minutes
-- [How it works](https://trigger.dev/docs/v3/how-it-works) - understand how Trigger.dev works under the hood
+- [How it works](https://trigger.dev/docs/how-it-works) - understand how Trigger.dev works under the hood
 - [Guides and examples](https://trigger.dev/docs/guides/introduction) - walk-through guides and code examples for popular frameworks and use cases
 
 ## Self-hosting
 
-If you prefer to self-host Trigger.dev, you can follow our [self-hosting guide](https://trigger.dev/docs/v3/open-source-self-hosting#overview).
+If you prefer to self-host Trigger.dev, you can follow our [self-hosting guides](https://trigger.dev/docs/self-hosting/overview):
 
-We also have a dedicated self-hosting channel in our [Discord server](https://trigger.dev/discord) for support.
+- [Docker self-hosting guide](https://trigger.dev/docs/self-hosting/docker) - use Docker Compose to spin up a Trigger.dev instance
+- [Kubernetes self-hosting guide](https://trigger.dev/docs/self-hosting/kubernetes) - use our official Helm chart to deploy Trigger.dev to your Kubernetes cluster
+
+## Support and community
+
+We have a large active community in our official [Discord server](https://trigger.dev/discord) for support, including a dedicated channel for self-hosting.
 
 ## Development
 

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/coordinator/tsconfig.json

@@ -1,6 +1,6 @@
 {
   "compilerOptions": {
-    "target": "es2018",
+    "target": "es2020",
     "module": "commonjs",
     "esModuleInterop": true,
     "resolveJsonModule": true,

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/docker-provider/tsconfig.json

@@ -1,6 +1,6 @@
 {
   "compilerOptions": {
-    "target": "es2018",
+    "target": "es2020",
     "module": "commonjs",
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,

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/kubernetes-provider/tsconfig.json

@@ -1,6 +1,6 @@
 {
   "compilerOptions": {
-    "target": "es2018",
+    "target": "es2020",
     "module": "commonjs",
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,

apps/supervisor/.env.example

@@ -7,12 +7,11 @@ MANAGED_WORKER_SECRET=managed-secret
 # Point this at the webapp in prod
 TRIGGER_API_URL=http://localhost:3030
 
-# Point this at the OTel collector in prod
+# Point this at the webapp or an OTel collector in prod
 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:3030/otel
 # Use this on macOS
 # OTEL_EXPORTER_OTLP_ENDPOINT=http://host.docker.internal:3030/otel
 
 # Optional settings
 DEBUG=1
-ENFORCE_MACHINE_PRESETS=1
 TRIGGER_DEQUEUE_INTERVAL_MS=1000

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,9 +16,10 @@ 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
 RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store pnpm fetch --frozen-lockfile
 
 FROM deps-fetcher AS dev-deps
@@ -36,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/README.md

@@ -19,6 +19,8 @@ curl -sS \
     -d "{\"name\": \"$wg_name\"}"
 ```
 
+If the worker group is newly created, the response will include a `token` field. If the group already exists, no token is returned.
+
 2. Create `.env` and set the worker token
 
 ```sh
@@ -34,7 +36,7 @@ TRIGGER_WORKER_TOKEN=tr_wgt_...
 pnpm dev
 ```
 
-4. Build CLI, then deploy a reference project
+4. Build CLI, then deploy a test project
 
 ```sh
 pnpm exec trigger deploy --self-hosted
@@ -43,16 +45,36 @@ pnpm exec trigger deploy --self-hosted
 pnpm exec trigger deploy --self-hosted --network host
 ```
 
-## Additional worker groups
+## Worker group management
 
-When adding more worker groups you might also want to make them the default for a specific project. This will allow you to test it without having to change the global default:
+### Shared variables
 
 ```sh
 api_url=http://localhost:3030
+admin_pat=tr_pat_... # edit this
+```
+
+- These are used by all commands
+
+### Create a worker group
+
+```sh
 wg_name=my-worker
 
-# edit these
-admin_pat=tr_pat_...
+curl -sS \
+    -X POST \
+    "$api_url/admin/api/v1/workers" \
+    -H "Authorization: Bearer $admin_pat" \
+    -H "Content-Type: application/json" \
+    -d "{\"name\": \"$wg_name\"}"
+```
+
+- If the worker group already exists, no token will be returned
+
+### Set a worker group as default for a project
+
+```sh
+wg_name=my-worker
 project_id=clsw6q8wz...
 
 curl -sS \
@@ -60,8 +82,24 @@ curl -sS \
     "$api_url/admin/api/v1/workers" \
     -H "Authorization: Bearer $admin_pat" \
     -H "Content-Type: application/json" \
-    -d "{
-        \"name\": \"$wg_name\",
-        \"makeDefaultForProjectId\": \"$project_id\"
-    }"
+    -d "{\"name\": \"$wg_name\", \"projectId\": \"$project_id\", \"makeDefaultForProject\": true}"
 ```
+
+- If the worker group doesn't exist, yet it will be created
+- If the worker group already exists, it will be attached to the project as default. No token will be returned.
+
+### Remove the default worker group from a project
+
+```sh
+project_id=clsw6q8wz...
+
+curl -sS \
+    -X POST \
+    "$api_url/admin/api/v1/workers" \
+    -H "Authorization: Bearer $admin_pat" \
+    -H "Content-Type: application/json" \
+    -d "{\"projectId\": \"$project_id\", \"removeDefaultFromProject\": true}"
+```
+
+- The project will then use the global default again
+- When `removeDefaultFromProject: true` no other actions will be performed

apps/supervisor/package.json

@@ -13,19 +13,16 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@aws-sdk/client-ecr": "^3.839.0",
     "@kubernetes/client-node": "^1.0.0",
     "@trigger.dev/core": "workspace:*",
-    "dockerode": "^4.0.3",
-    "nanoid": "^5.0.9",
+    "dockerode": "^4.0.6",
     "prom-client": "^15.1.0",
     "socket.io": "4.7.4",
     "std-env": "^3.8.0",
-    "tinyexec": "^0.3.1",
-    "zod": "3.23.8"
+    "zod": "3.25.76"
   },
   "devDependencies": {
-    "@types/dockerode": "^3.3.33",
-    "docker-api-ts": "^0.2.2",
-    "vitest": "^1.4.0"
+    "@types/dockerode": "^3.3.33"
   }
 }

apps/supervisor/src/clients/kubernetes.ts

@@ -3,9 +3,12 @@ import { Informer } from "@kubernetes/client-node";
 import { ListPromise } from "@kubernetes/client-node";
 import { KubernetesObject } from "@kubernetes/client-node";
 import { assertExhaustive } from "@trigger.dev/core/utils";
+import { SimpleStructuredLogger } from "@trigger.dev/core/v3/utils/structuredLogger";
 
 export const RUNTIME_ENV = process.env.KUBERNETES_PORT ? "kubernetes" : "local";
 
+const logger = new SimpleStructuredLogger("kubernetes-client");
+
 export function createK8sApi() {
   const kubeConfig = getKubeConfig();
 
@@ -31,7 +34,7 @@ export function createK8sApi() {
 export type K8sApi = ReturnType<typeof createK8sApi>;
 
 function getKubeConfig() {
-  console.log("getKubeConfig()", { RUNTIME_ENV });
+  logger.debug("getKubeConfig()", { RUNTIME_ENV });
 
   const kubeConfig = new k8s.KubeConfig();
 

apps/supervisor/src/env.ts

@@ -6,14 +6,16 @@ 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),
 
   // Required settings
   TRIGGER_API_URL: z.string().url(),
-  TRIGGER_WORKER_TOKEN: z.string(),
+  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_ENABLED: BoolEnv.default(true),
   TRIGGER_WORKLOAD_API_PROTOCOL: z
     .string()
     .transform((s) => z.enum(["http", "https"]).parse(s.toLowerCase()))
@@ -27,35 +29,97 @@ const Env = z.object({
   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_DOCKER_AUTOREMOVE: BoolEnv.default(true),
+  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(1000),
-  TRIGGER_DEQUEUE_MAX_RUN_COUNT: z.coerce.number().int().default(10),
-  TRIGGER_DEQUEUE_MAX_CONSUMER_COUNT: z.coerce.number().int().default(1),
+  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(),
 
-  // Used by the workload manager, e.g docker/k8s
-  DOCKER_NETWORK: z.string().default("host"),
-  OTEL_EXPORTER_OTLP_ENDPOINT: z.string().url(),
-  ENFORCE_MACHINE_PRESETS: z.coerce.boolean().default(false),
-  KUBERNETES_IMAGE_PULL_SECRETS: z.string().optional(), // csv
-
   // Used by the resource monitor
-  OVERRIDE_CPU_TOTAL: z.coerce.number().optional(),
-  OVERRIDE_MEMORY_TOTAL_GB: z.coerce.number().optional(),
+  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(),
 
-  // Kubernetes specific settings
+  // 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"),
-  EPHEMERAL_STORAGE_SIZE_LIMIT: z.string().default("10Gi"),
-  EPHEMERAL_STORAGE_SIZE_REQUEST: z.string().default("2Gi"),
+  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
+
+  // 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(),
+
+  // 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(),
+
+  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>
+
+  // 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),
@@ -74,6 +138,7 @@ const Env = z.object({
 
   // Debug
   DEBUG: BoolEnv.default(false),
+  SEND_RUN_DEBUG_LOGS: BoolEnv.default(false),
 });
 
 export const env = Env.parse(stdEnv);

apps/supervisor/src/envUtil.ts

@@ -1,6 +1,9 @@
 import { z } from "zod";
+import { SimpleStructuredLogger } from "@trigger.dev/core/v3/utils/structuredLogger";
 
-export const BoolEnv = z.preprocess((val) => {
+const logger = new SimpleStructuredLogger("env-util");
+
+const baseBoolEnv = z.preprocess((val) => {
   if (typeof val !== "string") {
     return val;
   }
@@ -8,6 +11,11 @@ export const BoolEnv = z.preprocess((val) => {
   return ["true", "1"].includes(val.toLowerCase().trim());
 }, z.boolean());
 
+// Create a type-safe version that only accepts boolean defaults
+export const BoolEnv = baseBoolEnv as Omit<typeof baseBoolEnv, "default"> & {
+  default: (value: boolean) => z.ZodDefault<typeof baseBoolEnv>;
+};
+
 export const AdditionalEnvVars = z.preprocess((val) => {
   if (typeof val !== "string") {
     return val;
@@ -33,7 +41,7 @@ export const AdditionalEnvVars = z.preprocess((val) => {
     // Return undefined if no valid key-value pairs were found
     return Object.keys(result).length === 0 ? undefined : result;
   } catch (error) {
-    console.warn("Failed to parse additional env vars", { error, val });
+    logger.warn("Failed to parse additional env vars", { error, val });
     return undefined;
   }
 }, z.record(z.string(), z.string()).optional());

apps/supervisor/src/index.ts

@@ -9,6 +9,7 @@ import { type DequeuedMessage } from "@trigger.dev/core/v3";
 import {
   DockerResourceMonitor,
   KubernetesResourceMonitor,
+  NoopResourceMonitor,
   type ResourceMonitor,
 } from "./resourceMonitor.js";
 import { KubernetesWorkloadManager } from "./workloadManager/kubernetes.js";
@@ -23,6 +24,7 @@ import { collectDefaultMetrics } from "prom-client";
 import { register } from "./metrics.js";
 import { PodCleaner } from "./services/podCleaner.js";
 import { FailedPodHandler } from "./services/failedPodHandler.js";
+import { getWorkerToken } from "./workerToken.js";
 
 if (env.METRICS_COLLECT_DEFAULTS) {
   collectDefaultMetrics({ register });
@@ -33,7 +35,7 @@ class ManagedSupervisor {
   private readonly metricsServer?: HttpServer;
   private readonly workloadServer: WorkloadServer;
   private readonly workloadManager: WorkloadManager;
-  private readonly logger = new SimpleStructuredLogger("managed-worker");
+  private readonly logger = new SimpleStructuredLogger("managed-supervisor");
   private readonly resourceMonitor: ResourceMonitor;
   private readonly checkpointClient?: CheckpointClient;
 
@@ -47,11 +49,11 @@ class ManagedSupervisor {
     const { TRIGGER_WORKER_TOKEN, MANAGED_WORKER_SECRET, ...envWithoutSecrets } = env;
 
     if (env.DEBUG) {
-      console.debug("[ManagedSupervisor] Starting up", { envWithoutSecrets });
+      this.logger.debug("Starting up", { envWithoutSecrets });
     }
 
     if (this.warmStartUrl) {
-      this.logger.log("[ManagedWorker] 🔥 Warm starts enabled", {
+      this.logger.log("🔥 Warm starts enabled", {
         warmStartUrl: this.warmStartUrl,
       });
     }
@@ -66,12 +68,22 @@ class ManagedSupervisor {
       heartbeatIntervalSeconds: env.RUNNER_HEARTBEAT_INTERVAL_SECONDS,
       snapshotPollIntervalSeconds: env.RUNNER_SNAPSHOT_POLL_INTERVAL_SECONDS,
       additionalEnvVars: env.RUNNER_ADDITIONAL_ENV_VARS,
-      dockerAutoremove: env.RUNNER_DOCKER_AUTOREMOVE,
+      dockerAutoremove: env.DOCKER_AUTOREMOVE_EXITED_CONTAINERS,
     } satisfies WorkloadManagerOptions;
 
+    this.resourceMonitor = env.RESOURCE_MONITOR_ENABLED
+      ? this.isKubernetes
+        ? new KubernetesResourceMonitor(createK8sApi(), env.TRIGGER_WORKER_INSTANCE_NAME)
+        : new DockerResourceMonitor(new Docker())
+      : new NoopResourceMonitor();
+
+    this.workloadManager = this.isKubernetes
+      ? new KubernetesWorkloadManager(workloadManagerOptions)
+      : new DockerWorkloadManager(workloadManagerOptions);
+
     if (this.isKubernetes) {
       if (env.POD_CLEANER_ENABLED) {
-        this.logger.log("[ManagedWorker] 🧹 Pod cleaner enabled", {
+        this.logger.log("🧹 Pod cleaner enabled", {
           namespace: env.KUBERNETES_NAMESPACE,
           batchSize: env.POD_CLEANER_BATCH_SIZE,
           intervalMs: env.POD_CLEANER_INTERVAL_MS,
@@ -83,11 +95,11 @@ class ManagedSupervisor {
           intervalMs: env.POD_CLEANER_INTERVAL_MS,
         });
       } else {
-        this.logger.warn("[ManagedWorker] Pod cleaner disabled");
+        this.logger.warn("Pod cleaner disabled");
       }
 
       if (env.FAILED_POD_HANDLER_ENABLED) {
-        this.logger.log("[ManagedWorker] 🔁 Failed pod handler enabled", {
+        this.logger.log("🔁 Failed pod handler enabled", {
           namespace: env.KUBERNETES_NAMESPACE,
           reconnectIntervalMs: env.FAILED_POD_HANDLER_RECONNECT_INTERVAL_MS,
         });
@@ -97,36 +109,52 @@ class ManagedSupervisor {
           reconnectIntervalMs: env.FAILED_POD_HANDLER_RECONNECT_INTERVAL_MS,
         });
       } else {
-        this.logger.warn("[ManagedWorker] Failed pod handler disabled");
+        this.logger.warn("Failed pod handler disabled");
       }
+    }
 
-      this.resourceMonitor = new KubernetesResourceMonitor(
-        createK8sApi(),
-        env.TRIGGER_WORKER_INSTANCE_NAME
+    if (env.TRIGGER_DEQUEUE_INTERVAL_MS > env.TRIGGER_DEQUEUE_IDLE_INTERVAL_MS) {
+      this.logger.warn(
+        `⚠️  TRIGGER_DEQUEUE_INTERVAL_MS (${env.TRIGGER_DEQUEUE_INTERVAL_MS}) is greater than TRIGGER_DEQUEUE_IDLE_INTERVAL_MS (${env.TRIGGER_DEQUEUE_IDLE_INTERVAL_MS}) - did you mix them up?`
       );
-      this.workloadManager = new KubernetesWorkloadManager(workloadManagerOptions);
-    } else {
-      this.resourceMonitor = new DockerResourceMonitor(new Docker());
-      this.workloadManager = new DockerWorkloadManager(workloadManagerOptions);
     }
 
     this.workerSession = new SupervisorSession({
-      workerToken: env.TRIGGER_WORKER_TOKEN,
+      workerToken: getWorkerToken(),
       apiUrl: env.TRIGGER_API_URL,
       instanceName: env.TRIGGER_WORKER_INSTANCE_NAME,
       managedWorkerSecret: env.MANAGED_WORKER_SECRET,
       dequeueIntervalMs: env.TRIGGER_DEQUEUE_INTERVAL_MS,
+      dequeueIdleIntervalMs: env.TRIGGER_DEQUEUE_IDLE_INTERVAL_MS,
       queueConsumerEnabled: env.TRIGGER_DEQUEUE_ENABLED,
       maxRunCount: env.TRIGGER_DEQUEUE_MAX_RUN_COUNT,
-      maxConsumerCount: env.TRIGGER_DEQUEUE_MAX_CONSUMER_COUNT,
+      metricsRegistry: register,
+      scaling: {
+        strategy: env.TRIGGER_DEQUEUE_SCALING_STRATEGY,
+        minConsumerCount: env.TRIGGER_DEQUEUE_MIN_CONSUMER_COUNT,
+        maxConsumerCount: env.TRIGGER_DEQUEUE_MAX_CONSUMER_COUNT,
+        scaleUpCooldownMs: env.TRIGGER_DEQUEUE_SCALING_UP_COOLDOWN_MS,
+        scaleDownCooldownMs: env.TRIGGER_DEQUEUE_SCALING_DOWN_COOLDOWN_MS,
+        targetRatio: env.TRIGGER_DEQUEUE_SCALING_TARGET_RATIO,
+        ewmaAlpha: env.TRIGGER_DEQUEUE_SCALING_EWMA_ALPHA,
+        batchWindowMs: env.TRIGGER_DEQUEUE_SCALING_BATCH_WINDOW_MS,
+        dampingFactor: env.TRIGGER_DEQUEUE_SCALING_DAMPING_FACTOR,
+      },
       runNotificationsEnabled: env.TRIGGER_WORKLOAD_API_ENABLED,
+      heartbeatIntervalSeconds: env.TRIGGER_WORKER_HEARTBEAT_INTERVAL_SECONDS,
+      sendRunDebugLogs: env.SEND_RUN_DEBUG_LOGS,
       preDequeue: async () => {
+        if (!env.RESOURCE_MONITOR_ENABLED) {
+          return {};
+        }
+
         if (this.isKubernetes) {
           // Not used in k8s for now
           return {};
         }
 
         const resources = await this.resourceMonitor.getNodeResources();
+
         return {
           maxResources: {
             cpu: resources.cpuAvailable,
@@ -142,7 +170,7 @@ class ManagedSupervisor {
     });
 
     if (env.TRIGGER_CHECKPOINT_URL) {
-      this.logger.log("[ManagedWorker] 🥶 Checkpoints enabled", {
+      this.logger.log("🥶 Checkpoints enabled", {
         checkpointUrl: env.TRIGGER_CHECKPOINT_URL,
       });
 
@@ -153,43 +181,34 @@ class ManagedSupervisor {
       });
     }
 
-    // setInterval(async () => {
-    //   const resources = await this.resourceMonitor.getNodeResources(true);
-    //   this.logger.debug("[ManagedWorker] Current resources", { resources });
-    // }, 1000);
-
     this.workerSession.on("runNotification", async ({ time, run }) => {
-      this.logger.log("[ManagedWorker] runNotification", { time, run });
+      this.logger.log("runNotification", { time, run });
 
       this.workloadServer.notifyRun({ run });
     });
 
     this.workerSession.on("runQueueMessage", async ({ time, message }) => {
-      this.logger.log(
-        `[ManagedWorker] Received message with timestamp ${time.toLocaleString()}`,
-        message
-      );
+      this.logger.log(`Received message with timestamp ${time.toLocaleString()}`, message);
 
       if (message.completedWaitpoints.length > 0) {
-        this.logger.debug("[ManagedWorker] Run has completed waitpoints", {
+        this.logger.debug("Run has completed waitpoints", {
           runId: message.run.id,
           completedWaitpoints: message.completedWaitpoints.length,
         });
-        // TODO: Do something with them or if we don't need the data here, maybe we shouldn't even send it
       }
 
       if (!message.image) {
-        this.logger.error("[ManagedWorker] Run has no image", { runId: message.run.id });
+        this.logger.error("Run has no image", { runId: message.run.id });
         return;
       }
 
       const { checkpoint, ...rest } = message;
 
       if (checkpoint) {
-        this.logger.log("[ManagedWorker] Restoring run", { runId: message.run.id });
+        this.logger.log("Restoring run", { runId: message.run.id });
 
         if (!this.checkpointClient) {
-          this.logger.error("[ManagedWorker] No checkpoint client", { runId: message.run.id });
+          this.logger.error("No checkpoint client", { runId: message.run.id });
           return;
         }
 
@@ -204,27 +223,33 @@ class ManagedSupervisor {
           });
 
           if (didRestore) {
-            this.logger.log("[ManagedWorker] Restore successful", { runId: message.run.id });
+            this.logger.log("Restore successful", { runId: message.run.id });
           } else {
-            this.logger.error("[ManagedWorker] Restore failed", { runId: message.run.id });
+            this.logger.error("Restore failed", { runId: message.run.id });
           }
         } catch (error) {
-          this.logger.error("[ManagedWorker] Failed to restore run", { error });
+          this.logger.error("Failed to restore run", { error });
         }
 
         return;
       }
 
-      this.logger.log("[ManagedWorker] Scheduling run", { runId: message.run.id });
+      this.logger.log("Scheduling run", { runId: message.run.id });
 
       const didWarmStart = await this.tryWarmStart(message);
 
       if (didWarmStart) {
-        this.logger.log("[ManagedWorker] Warm start successful", { runId: message.run.id });
+        this.logger.log("Warm start successful", { runId: message.run.id });
         return;
       }
 
       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,
           envId: message.environment.id,
@@ -233,12 +258,15 @@ class ManagedSupervisor {
           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,
           nextAttemptNumber: message.run.attemptNumber,
           snapshotId: message.snapshot.id,
           snapshotFriendlyId: message.snapshot.friendlyId,
+          placementTags: message.placementTags,
         });
 
         // Disabled for now
@@ -247,7 +275,7 @@ class ManagedSupervisor {
         //   memory: message.run.machine.memory,
         // });
       } catch (error) {
-        this.logger.error("[ManagedWorker] Failed to create workload", { error });
+        this.logger.error("Failed to create workload", { error });
       }
     });
 
@@ -275,12 +303,12 @@ class ManagedSupervisor {
   }
 
   async onRunConnected({ run }: { run: { friendlyId: string } }) {
-    this.logger.debug("[ManagedWorker] Run connected", { run });
+    this.logger.debug("Run connected", { run });
     this.workerSession.subscribeToRunNotifications([run.friendlyId]);
   }
 
   async onRunDisconnected({ run }: { run: { friendlyId: string } }) {
-    this.logger.debug("[ManagedWorker] Run disconnected", { run });
+    this.logger.debug("Run disconnected", { run });
     this.workerSession.unsubscribeFromRunNotifications([run.friendlyId]);
   }
 
@@ -301,7 +329,7 @@ class ManagedSupervisor {
       });
 
       if (!res.ok) {
-        this.logger.error("[ManagedWorker] Warm start failed", {
+        this.logger.error("Warm start failed", {
           runId: dequeuedMessage.run.id,
         });
         return false;
@@ -311,7 +339,7 @@ class ManagedSupervisor {
       const parsedData = z.object({ didWarmStart: z.boolean() }).safeParse(data);
 
       if (!parsedData.success) {
-        this.logger.error("[ManagedWorker] Warm start response invalid", {
+        this.logger.error("Warm start response invalid", {
           runId: dequeuedMessage.run.id,
           data,
         });
@@ -320,7 +348,7 @@ class ManagedSupervisor {
 
       return parsedData.data.didWarmStart;
     } catch (error) {
-      this.logger.error("[ManagedWorker] Warm start error", {
+      this.logger.error("Warm start error", {
         runId: dequeuedMessage.run.id,
         error,
       });
@@ -329,7 +357,7 @@ class ManagedSupervisor {
   }
 
   async start() {
-    this.logger.log("[ManagedWorker] Starting up");
+    this.logger.log("Starting up");
 
     // Optional services
     await this.podCleaner?.start();
@@ -337,21 +365,21 @@ class ManagedSupervisor {
     await this.metricsServer?.start();
 
     if (env.TRIGGER_WORKLOAD_API_ENABLED) {
-      this.logger.log("[ManagedWorker] Workload API enabled", {
+      this.logger.log("Workload API enabled", {
         protocol: env.TRIGGER_WORKLOAD_API_PROTOCOL,
         domain: env.TRIGGER_WORKLOAD_API_DOMAIN,
         port: env.TRIGGER_WORKLOAD_API_PORT_INTERNAL,
       });
       await this.workloadServer.start();
     } else {
-      this.logger.warn("[ManagedWorker] Workload API disabled");
+      this.logger.warn("Workload API disabled");
     }
 
     await this.workerSession.start();
   }
 
   async stop() {
-    this.logger.log("[ManagedWorker] Shutting down");
+    this.logger.log("Shutting down");
     await this.workerSession.stop();
 
     // Optional services

apps/supervisor/src/resourceMonitor.ts

@@ -1,5 +1,4 @@
 import type Docker from "dockerode";
-import type * as TDocker from "docker-api-ts";
 import type { MachineResources } from "@trigger.dev/core/v3";
 import { SimpleStructuredLogger } from "@trigger.dev/core/v3/utils/structuredLogger";
 import { env } from "./env.js";
@@ -71,18 +70,21 @@ export abstract class ResourceMonitor {
   }
 
   protected applyOverrides(resources: NodeResources): NodeResources {
-    if (!env.OVERRIDE_CPU_TOTAL && !env.OVERRIDE_MEMORY_TOTAL_GB) {
+    if (
+      !env.RESOURCE_MONITOR_OVERRIDE_CPU_TOTAL &&
+      !env.RESOURCE_MONITOR_OVERRIDE_MEMORY_TOTAL_GB
+    ) {
       return resources;
     }
 
     logger.debug("[ResourceMonitor] 🛡️ Applying resource overrides", {
-      cpuTotal: env.OVERRIDE_CPU_TOTAL,
-      memoryTotalGb: env.OVERRIDE_MEMORY_TOTAL_GB,
+      cpuTotal: env.RESOURCE_MONITOR_OVERRIDE_CPU_TOTAL,
+      memoryTotalGb: env.RESOURCE_MONITOR_OVERRIDE_MEMORY_TOTAL_GB,
     });
 
-    const cpuTotal = env.OVERRIDE_CPU_TOTAL ?? resources.cpuTotal;
-    const memoryTotal = env.OVERRIDE_MEMORY_TOTAL_GB
-      ? this.gbToBytes(env.OVERRIDE_MEMORY_TOTAL_GB)
+    const cpuTotal = env.RESOURCE_MONITOR_OVERRIDE_CPU_TOTAL ?? resources.cpuTotal;
+    const memoryTotal = env.RESOURCE_MONITOR_OVERRIDE_MEMORY_TOTAL_GB
+      ? this.gbToBytes(env.RESOURCE_MONITOR_OVERRIDE_MEMORY_TOTAL_GB)
       : resources.memoryTotal;
 
     const cpuDiff = cpuTotal - resources.cpuTotal;
@@ -100,6 +102,11 @@ export abstract class ResourceMonitor {
   }
 }
 
+type SystemInfo = {
+  NCPU: number | undefined;
+  MemTotal: number | undefined;
+};
+
 export class DockerResourceMonitor extends ResourceMonitor {
   private docker: Docker;
 
@@ -114,7 +121,7 @@ export class DockerResourceMonitor extends ResourceMonitor {
       return this.cachedResources;
     }
 
-    const info: TDocker.SystemInfo = await this.docker.info();
+    const info: SystemInfo = await this.docker.info();
     const stats = await this.docker.listContainers({ all: true });
 
     // Get system-wide resources
@@ -208,6 +215,21 @@ export class KubernetesResourceMonitor extends ResourceMonitor {
   }
 }
 
+export class NoopResourceMonitor extends ResourceMonitor {
+  constructor() {
+    super(NoopResourceParser);
+  }
+
+  async getNodeResources(): Promise<NodeResources> {
+    return {
+      cpuTotal: 0,
+      cpuAvailable: Infinity,
+      memoryTotal: 0,
+      memoryAvailable: Infinity,
+    };
+  }
+}
+
 abstract class ResourceParser {
   abstract cpu(cpu: number | string): number;
   abstract memory(memory: number | string): number;
@@ -244,3 +266,13 @@ class KubernetesResourceParser extends ResourceParser {
     return parseInt(memory);
   }
 }
+
+class NoopResourceParser extends ResourceParser {
+  cpu(cpu: number): number {
+    return cpu;
+  }
+
+  memory(memory: number): number {
+    return memory;
+  }
+}

apps/supervisor/src/services/failedPodHandler.ts

@@ -25,6 +25,7 @@ export class FailedPodHandler {
 
   private readonly informer: Informer<V1Pod>;
   private readonly reconnectIntervalMs: number;
+  private reconnecting = false;
 
   // Metrics
   private readonly register: Registry;
@@ -250,21 +251,48 @@ export class FailedPodHandler {
   }
 
   private makeOnError(informerName: string) {
-    return () => this.onError(informerName);
+    return (err?: unknown) => this.onError(informerName, err);
   }
 
-  private async onError(informerName: string) {
+  private async onError(informerName: string, err?: unknown) {
     if (!this.isRunning) {
       this.logger.warn("onError: informer not running");
       return;
     }
 
-    this.logger.error("error event fired", { informerName });
-    this.informerEventsTotal.inc({ namespace: this.namespace, verb: "error" });
+    // Guard against multiple simultaneous reconnections
+    if (this.reconnecting) {
+      this.logger.debug("onError: reconnection already in progress, skipping", {
+        informerName,
+      });
+      return;
+    }
 
-    // Reconnect on errors
-    await setTimeout(this.reconnectIntervalMs);
-    await this.informer.start();
+    this.reconnecting = true;
+
+    try {
+      const error = err instanceof Error ? err : undefined;
+      this.logger.error("error event fired", {
+        informerName,
+        error: error?.message,
+        errorType: error?.name,
+      });
+      this.informerEventsTotal.inc({ namespace: this.namespace, verb: "error" });
+
+      // Reconnect on errors
+      await setTimeout(this.reconnectIntervalMs);
+      await this.informer.start();
+    } catch (handlerError) {
+      const error = handlerError instanceof Error ? handlerError : undefined;
+      this.logger.error("onError: reconnection attempt failed", {
+        informerName,
+        error: error?.message,
+        errorType: error?.name,
+        errorStack: error?.stack,
+      });
+    } finally {
+      this.reconnecting = false;
+    }
   }
 
   private makeOnConnect(informerName: string) {

apps/supervisor/src/util.ts

@@ -1,8 +1,17 @@
-export function getDockerHostDomain() {
-  const isMacOs = process.platform === "darwin";
-  const isWindows = process.platform === "win32";
+import { isMacOS, isWindows } from "std-env";
 
-  return isMacOs || isWindows ? "host.docker.internal" : "localhost";
+export function normalizeDockerHostUrl(url: string) {
+  const $url = new URL(url);
+
+  if ($url.hostname === "localhost") {
+    $url.hostname = getDockerHostDomain();
+  }
+
+  return $url.toString();
+}
+
+export function getDockerHostDomain() {
+  return isMacOS || isWindows ? "host.docker.internal" : "localhost";
 }
 
 export function getRunnerId(runId: string, attemptNumber?: number) {

apps/supervisor/src/workerToken.ts

@@ -0,0 +1,29 @@
+import { readFileSync } from "fs";
+import { env } from "./env.js";
+
+export function getWorkerToken() {
+  if (!env.TRIGGER_WORKER_TOKEN.startsWith("file://")) {
+    return env.TRIGGER_WORKER_TOKEN;
+  }
+
+  const tokenPath = env.TRIGGER_WORKER_TOKEN.replace("file://", "");
+
+  console.debug(
+    JSON.stringify({
+      message: "🔑 Reading worker token from file",
+      tokenPath,
+    })
+  );
+
+  try {
+    const token = readFileSync(tokenPath, "utf8").trim();
+    return token;
+  } catch (error) {
+    console.error(`Failed to read worker token from file: ${tokenPath}`, error);
+    throw new Error(
+      `Unable to read worker token from file: ${
+        error instanceof Error ? error.message : "Unknown error"
+      }`
+    );
+  }
+}

apps/supervisor/src/workloadManager/docker.ts

@@ -4,88 +4,301 @@ import {
   type WorkloadManagerCreateOptions,
   type WorkloadManagerOptions,
 } from "./types.js";
-import { x } from "tinyexec";
 import { env } from "../env.js";
-import { getDockerHostDomain, getRunnerId } from "../util.js";
+import { getDockerHostDomain, getRunnerId, normalizeDockerHostUrl } from "../util.js";
+import Docker from "dockerode";
+import { tryCatch } from "@trigger.dev/core";
+import { ECRAuthService } from "./ecrAuth.js";
 
 export class DockerWorkloadManager implements WorkloadManager {
-  private readonly logger = new SimpleStructuredLogger("docker-workload-provider");
+  private readonly logger = new SimpleStructuredLogger("docker-workload-manager");
+  private readonly docker: Docker;
+
+  private readonly runnerNetworks: string[];
+  private readonly staticAuth?: Docker.AuthConfig;
+  private readonly platformOverride?: string;
+  private readonly ecrAuthService?: ECRAuthService;
 
   constructor(private opts: WorkloadManagerOptions) {
+    this.docker = new Docker({
+      version: env.DOCKER_API_VERSION,
+    });
+
     if (opts.workloadApiDomain) {
-      this.logger.warn("[DockerWorkloadProvider] ⚠️ Custom workload API domain", {
+      this.logger.warn("⚠️ Custom workload API domain", {
         domain: opts.workloadApiDomain,
       });
     }
+
+    this.runnerNetworks = env.DOCKER_RUNNER_NETWORKS.split(",");
+
+    this.platformOverride = env.DOCKER_PLATFORM;
+    if (this.platformOverride) {
+      this.logger.info("🖥️  Platform override", {
+        targetPlatform: this.platformOverride,
+        hostPlatform: process.arch,
+      });
+    }
+
+    if (env.DOCKER_REGISTRY_USERNAME && env.DOCKER_REGISTRY_PASSWORD && env.DOCKER_REGISTRY_URL) {
+      this.logger.info("🐋 Using Docker registry credentials", {
+        username: env.DOCKER_REGISTRY_USERNAME,
+        url: env.DOCKER_REGISTRY_URL,
+      });
+
+      this.staticAuth = {
+        username: env.DOCKER_REGISTRY_USERNAME,
+        password: env.DOCKER_REGISTRY_PASSWORD,
+        serveraddress: env.DOCKER_REGISTRY_URL,
+      };
+    } else if (ECRAuthService.hasAWSCredentials()) {
+      this.logger.info("🐋 AWS credentials found, initializing ECR auth service");
+      this.ecrAuthService = new ECRAuthService();
+    } else {
+      this.logger.warn(
+        "🐋 No Docker registry credentials or AWS credentials provided, skipping auth"
+      );
+    }
   }
 
   async create(opts: WorkloadManagerCreateOptions) {
-    this.logger.log("[DockerWorkloadProvider] Creating container", { opts });
+    this.logger.log("create()", { opts });
 
     const runnerId = getRunnerId(opts.runFriendlyId, opts.nextAttemptNumber);
 
-    const runArgs = [
-      "run",
-      "--detach",
-      `--network=${env.DOCKER_NETWORK}`,
-      `--env=TRIGGER_DEQUEUED_AT_MS=${opts.dequeuedAt.getTime()}`,
-      `--env=TRIGGER_POD_SCHEDULED_AT_MS=${Date.now()}`,
-      `--env=TRIGGER_ENV_ID=${opts.envId}`,
-      `--env=TRIGGER_RUN_ID=${opts.runFriendlyId}`,
-      `--env=TRIGGER_SNAPSHOT_ID=${opts.snapshotFriendlyId}`,
-      `--env=TRIGGER_SUPERVISOR_API_PROTOCOL=${this.opts.workloadApiProtocol}`,
-      `--env=TRIGGER_SUPERVISOR_API_PORT=${this.opts.workloadApiPort}`,
-      `--env=TRIGGER_SUPERVISOR_API_DOMAIN=${this.opts.workloadApiDomain ?? getDockerHostDomain()}`,
-      `--env=TRIGGER_WORKER_INSTANCE_NAME=${env.TRIGGER_WORKER_INSTANCE_NAME}`,
-      `--env=OTEL_EXPORTER_OTLP_ENDPOINT=${env.OTEL_EXPORTER_OTLP_ENDPOINT}`,
-      `--env=TRIGGER_RUNNER_ID=${runnerId}`,
-      `--hostname=${runnerId}`,
-      `--name=${runnerId}`,
+    // Build environment variables
+    const envVars: string[] = [
+      `OTEL_EXPORTER_OTLP_ENDPOINT=${env.OTEL_EXPORTER_OTLP_ENDPOINT}`,
+      `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}`,
+      `TRIGGER_SUPERVISOR_API_PORT=${this.opts.workloadApiPort}`,
+      `TRIGGER_SUPERVISOR_API_DOMAIN=${this.opts.workloadApiDomain ?? getDockerHostDomain()}`,
+      `TRIGGER_WORKER_INSTANCE_NAME=${env.TRIGGER_WORKER_INSTANCE_NAME}`,
+      `TRIGGER_RUNNER_ID=${runnerId}`,
+      `TRIGGER_MACHINE_CPU=${opts.machine.cpu}`,
+      `TRIGGER_MACHINE_MEMORY=${opts.machine.memory}`,
+      `PRETTY_LOGS=${env.RUNNER_PRETTY_LOGS}`,
     ];
 
-    if (this.opts.dockerAutoremove) {
-      runArgs.push("--rm");
-    }
-
     if (this.opts.warmStartUrl) {
-      runArgs.push(`--env=TRIGGER_WARM_START_URL=${this.opts.warmStartUrl}`);
+      envVars.push(`TRIGGER_WARM_START_URL=${normalizeDockerHostUrl(this.opts.warmStartUrl)}`);
     }
 
     if (this.opts.metadataUrl) {
-      runArgs.push(`--env=TRIGGER_METADATA_URL=${this.opts.metadataUrl}`);
+      envVars.push(`TRIGGER_METADATA_URL=${this.opts.metadataUrl}`);
     }
 
     if (this.opts.heartbeatIntervalSeconds) {
-      runArgs.push(
-        `--env=TRIGGER_HEARTBEAT_INTERVAL_SECONDS=${this.opts.heartbeatIntervalSeconds}`
-      );
+      envVars.push(`TRIGGER_HEARTBEAT_INTERVAL_SECONDS=${this.opts.heartbeatIntervalSeconds}`);
     }
 
     if (this.opts.snapshotPollIntervalSeconds) {
-      runArgs.push(
-        `--env=TRIGGER_SNAPSHOT_POLL_INTERVAL_SECONDS=${this.opts.snapshotPollIntervalSeconds}`
+      envVars.push(
+        `TRIGGER_SNAPSHOT_POLL_INTERVAL_SECONDS=${this.opts.snapshotPollIntervalSeconds}`
       );
     }
 
     if (this.opts.additionalEnvVars) {
       Object.entries(this.opts.additionalEnvVars).forEach(([key, value]) => {
-        runArgs.push(`--env=${key}=${value}`);
+        envVars.push(`${key}=${value}`);
       });
     }
 
-    if (env.ENFORCE_MACHINE_PRESETS) {
-      runArgs.push(`--cpus=${opts.machine.cpu}`, `--memory=${opts.machine.memory}G`);
-      runArgs.push(`--env=TRIGGER_MACHINE_CPU=${opts.machine.cpu}`);
-      runArgs.push(`--env=TRIGGER_MACHINE_MEMORY=${opts.machine.memory}`);
+    const hostConfig: Docker.HostConfig = {
+      AutoRemove: !!this.opts.dockerAutoremove,
+    };
+
+    const [firstNetwork, ...remainingNetworks] = this.runnerNetworks;
+
+    // Always attach the first network at container creation time. This has the following benefits:
+    // - If there is only a single network to attach, this will prevent having to make a separate request.
+    // - If there are multiple networks to attach, this will ensure the runner won't also be connected to the bridge network
+    hostConfig.NetworkMode = firstNetwork;
+
+    if (env.DOCKER_ENFORCE_MACHINE_PRESETS) {
+      hostConfig.NanoCpus = opts.machine.cpu * 1e9;
+      hostConfig.Memory = opts.machine.memory * 1024 * 1024 * 1024;
     }
 
-    runArgs.push(`${opts.image}`);
+    let imageRef = opts.image;
 
-    try {
-      const { stdout, stderr } = await x("docker", runArgs);
-      this.logger.debug("[DockerWorkloadProvider] Create succeeded", { stdout, stderr });
-    } catch (error) {
-      this.logger.error("[DockerWorkloadProvider] Create failed:", { opts, error });
+    if (env.DOCKER_STRIP_IMAGE_DIGEST) {
+      imageRef = opts.image.split("@")[0]!;
     }
+
+    const containerCreateOpts: Docker.ContainerCreateOptions = {
+      name: runnerId,
+      Hostname: runnerId,
+      HostConfig: hostConfig,
+      Image: imageRef,
+      AttachStdout: false,
+      AttachStderr: false,
+      AttachStdin: false,
+    };
+
+    if (this.platformOverride) {
+      containerCreateOpts.platform = this.platformOverride;
+    }
+
+    const logger = this.logger.child({ opts, containerCreateOpts });
+
+    const [inspectError, inspectResult] = await tryCatch(this.docker.getImage(imageRef).inspect());
+
+    let shouldPull = !!inspectError;
+    if (this.platformOverride) {
+      const imageArchitecture = inspectResult?.Architecture;
+
+      // When the image architecture doesn't match the platform, we need to pull the image
+      if (imageArchitecture && !this.platformOverride.includes(imageArchitecture)) {
+        shouldPull = true;
+      }
+    }
+
+    // If the image is not present, try to pull it
+    if (shouldPull) {
+      logger.info("Pulling image", {
+        error: inspectError,
+        image: opts.image,
+        targetPlatform: this.platformOverride,
+        imageArchitecture: inspectResult?.Architecture,
+      });
+
+      // Get auth config (static or ECR)
+      const authConfig = await this.getAuthConfig();
+
+      // Ensure the image is present
+      const [createImageError, imageResponseReader] = await tryCatch(
+        this.docker.createImage(authConfig, {
+          fromImage: imageRef,
+          ...(this.platformOverride ? { platform: this.platformOverride } : {}),
+        })
+      );
+      if (createImageError) {
+        logger.error("Failed to pull image", { error: createImageError });
+        return;
+      }
+
+      const [imageReadError, imageResponse] = await tryCatch(readAllChunks(imageResponseReader));
+      if (imageReadError) {
+        logger.error("failed to read image response", { error: imageReadError });
+        return;
+      }
+
+      logger.debug("pulled image", { image: opts.image, imageResponse });
+    } else {
+      // Image is present, so we can use it to create the container
+    }
+
+    // Create container
+    const [createContainerError, container] = await tryCatch(
+      this.docker.createContainer({
+        ...containerCreateOpts,
+        // Add env vars here so they're not logged
+        Env: envVars,
+      })
+    );
+
+    if (createContainerError) {
+      logger.error("Failed to create container", { error: createContainerError });
+      return;
+    }
+
+    // If there are multiple networks to attach to we need to attach the remaining ones after creation
+    if (remainingNetworks.length > 0) {
+      await this.attachContainerToNetworks({
+        containerId: container.id,
+        networkNames: remainingNetworks,
+      });
+    }
+
+    // Start container
+    const [startError, startResult] = await tryCatch(container.start());
+
+    if (startError) {
+      logger.error("Failed to start container", { error: startError, containerId: container.id });
+      return;
+    }
+
+    logger.debug("create succeeded", { startResult, containerId: container.id });
+  }
+
+  /**
+   * Get authentication config for Docker operations
+   * Uses static credentials if available, otherwise attempts ECR auth
+   */
+  private async getAuthConfig(): Promise<Docker.AuthConfig | undefined> {
+    // Use static credentials if available
+    if (this.staticAuth) {
+      return this.staticAuth;
+    }
+
+    // Use ECR auth if service is available
+    if (this.ecrAuthService) {
+      const ecrAuth = await this.ecrAuthService.getAuthConfig();
+      return ecrAuth || undefined;
+    }
+
+    // No auth available
+    return undefined;
+  }
+
+  private async attachContainerToNetworks({
+    containerId,
+    networkNames,
+  }: {
+    containerId: string;
+    networkNames: string[];
+  }) {
+    this.logger.debug("Attaching container to networks", { containerId, networkNames });
+
+    const [error, networkResults] = await tryCatch(
+      this.docker.listNetworks({
+        filters: {
+          // Full name matches only to prevent unexpected results
+          name: networkNames.map((name) => `^${name}$`),
+        },
+      })
+    );
+
+    if (error) {
+      this.logger.error("Failed to list networks", { networkNames });
+      return;
+    }
+
+    const results = await Promise.allSettled(
+      networkResults.map((networkInfo) => {
+        const network = this.docker.getNetwork(networkInfo.Id);
+        return network.connect({ Container: containerId });
+      })
+    );
+
+    if (results.some((r) => r.status === "rejected")) {
+      this.logger.error("Failed to attach container to some networks", {
+        containerId,
+        networkNames,
+        results,
+      });
+      return;
+    }
+
+    this.logger.debug("Attached container to networks", {
+      containerId,
+      networkNames,
+      results,
+    });
   }
 }
+
+async function readAllChunks(reader: NodeJS.ReadableStream) {
+  const chunks = [];
+  for await (const chunk of reader) {
+    chunks.push(chunk.toString());
+  }
+  return chunks;
+}

apps/supervisor/src/workloadManager/ecrAuth.ts

@@ -0,0 +1,144 @@
+import { ECRClient, GetAuthorizationTokenCommand } from "@aws-sdk/client-ecr";
+import { SimpleStructuredLogger } from "@trigger.dev/core/v3/utils/structuredLogger";
+import { tryCatch } from "@trigger.dev/core";
+import Docker from "dockerode";
+
+interface ECRTokenCache {
+  token: string;
+  username: string;
+  serverAddress: string;
+  expiresAt: Date;
+}
+
+export class ECRAuthService {
+  private readonly logger = new SimpleStructuredLogger("ecr-auth-service");
+  private readonly ecrClient: ECRClient;
+  private tokenCache: ECRTokenCache | null = null;
+
+  constructor() {
+    this.ecrClient = new ECRClient();
+
+    this.logger.info("🔐 ECR Auth Service initialized", {
+      region: this.ecrClient.config.region,
+    });
+  }
+
+  /**
+   * Check if we have AWS credentials configured
+   */
+  static hasAWSCredentials(): boolean {
+    if (process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY) {
+      return true;
+    }
+
+    if (
+      process.env.AWS_PROFILE ||
+      process.env.AWS_ROLE_ARN ||
+      process.env.AWS_WEB_IDENTITY_TOKEN_FILE
+    ) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if the current token is still valid with a 10-minute buffer
+   */
+  private isTokenValid(): boolean {
+    if (!this.tokenCache) {
+      return false;
+    }
+
+    const now = new Date();
+    const bufferMs = 10 * 60 * 1000; // 10 minute buffer before expiration
+    return now < new Date(this.tokenCache.expiresAt.getTime() - bufferMs);
+  }
+
+  /**
+   * Get a fresh ECR authorization token from AWS
+   */
+  private async fetchNewToken(): Promise<ECRTokenCache | null> {
+    const [error, response] = await tryCatch(
+      this.ecrClient.send(new GetAuthorizationTokenCommand({}))
+    );
+
+    if (error) {
+      this.logger.error("Failed to get ECR authorization token", { error });
+      return null;
+    }
+
+    const authData = response.authorizationData?.[0];
+    if (!authData?.authorizationToken || !authData.proxyEndpoint) {
+      this.logger.error("Invalid ECR authorization response", { authData });
+      return null;
+    }
+
+    // Decode the base64 token to get username:password
+    const decoded = Buffer.from(authData.authorizationToken, "base64").toString("utf-8");
+    const [username, password] = decoded.split(":", 2);
+
+    if (!username || !password) {
+      this.logger.error("Failed to parse ECR authorization token");
+      return null;
+    }
+
+    const expiresAt = authData.expiresAt || new Date(Date.now() + 12 * 60 * 60 * 1000); // Default 12 hours
+
+    const tokenCache: ECRTokenCache = {
+      token: password,
+      username,
+      serverAddress: authData.proxyEndpoint,
+      expiresAt,
+    };
+
+    this.logger.info("🔐 Successfully fetched ECR token", {
+      username,
+      serverAddress: authData.proxyEndpoint,
+      expiresAt: expiresAt.toISOString(),
+    });
+
+    return tokenCache;
+  }
+
+  /**
+   * Get ECR auth config for Docker operations
+   * Returns cached token if valid, otherwise fetches a new one
+   */
+  async getAuthConfig(): Promise<Docker.AuthConfig | null> {
+    // Check if cached token is still valid
+    if (this.isTokenValid()) {
+      this.logger.debug("Using cached ECR token");
+      return {
+        username: this.tokenCache!.username,
+        password: this.tokenCache!.token,
+        serveraddress: this.tokenCache!.serverAddress,
+      };
+    }
+
+    // Fetch new token
+    this.logger.info("Fetching new ECR authorization token");
+    const newToken = await this.fetchNewToken();
+
+    if (!newToken) {
+      return null;
+    }
+
+    // Cache the new token
+    this.tokenCache = newToken;
+
+    return {
+      username: newToken.username,
+      password: newToken.token,
+      serveraddress: newToken.serverAddress,
+    };
+  }
+
+  /**
+   * Clear the cached token (useful for testing or forcing refresh)
+   */
+  clearCache(): void {
+    this.tokenCache = null;
+    this.logger.debug("ECR token cache cleared");
+  }
+}

apps/supervisor/src/workloadManager/kubernetes.ts

@@ -4,7 +4,13 @@ import {
   type WorkloadManagerCreateOptions,
   type WorkloadManagerOptions,
 } from "./types.js";
-import type { EnvironmentType, MachinePreset } 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";
 import { getRunnerId } from "../util.js";
@@ -13,13 +19,45 @@ 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;
   private namespace = env.KUBERNETES_NAMESPACE;
+  private placementTagProcessor: PlacementTagProcessor;
+
+  // Resource settings
+  private readonly cpuRequestMinCores = env.KUBERNETES_CPU_REQUEST_MIN_CORES;
+  private readonly cpuRequestRatio = env.KUBERNETES_CPU_REQUEST_RATIO;
+  private readonly memoryRequestMinGb = env.KUBERNETES_MEMORY_REQUEST_MIN_GB;
+  private readonly memoryRequestRatio = env.KUBERNETES_MEMORY_REQUEST_RATIO;
+  private readonly memoryOverheadGb = env.KUBERNETES_MEMORY_OVERHEAD_GB;
 
   constructor(private opts: WorkloadManagerOptions) {
     this.k8s = createK8sApi();
+    this.placementTagProcessor = new PlacementTagProcessor({
+      enabled: env.PLACEMENT_TAGS_ENABLED,
+      prefix: env.PLACEMENT_TAGS_PREFIX,
+    });
 
     if (opts.workloadApiDomain) {
       this.logger.warn("[KubernetesWorkloadManager] ⚠️ Custom workload API domain", {
@@ -28,6 +66,39 @@ export class KubernetesWorkloadManager implements WorkloadManager {
     }
   }
 
+  private addPlacementTags(
+    podSpec: Omit<k8s.V1PodSpec, "containers">,
+    placementTags?: PlacementTag[]
+  ): Omit<k8s.V1PodSpec, "containers"> {
+    const nodeSelector = this.placementTagProcessor.convertToNodeSelector(
+      placementTags,
+      podSpec.nodeSelector
+    );
+
+    return {
+      ...podSpec,
+      nodeSelector,
+    };
+  }
+
+  private stripImageDigest(imageRef: string): string {
+    if (!env.KUBERNETES_STRIP_IMAGE_DIGEST) {
+      return imageRef;
+    }
+
+    const atIndex = imageRef.lastIndexOf("@");
+
+    if (atIndex === -1) {
+      return imageRef;
+    }
+
+    return imageRef.substring(0, atIndex);
+  }
+
+  private clamp(value: number, min: number, max: number): number {
+    return Math.min(Math.max(value, min), max);
+  }
+
   async create(opts: WorkloadManagerCreateOptions) {
     this.logger.log("[KubernetesWorkloadManager] Creating container", { opts });
 
@@ -48,12 +119,13 @@ export class KubernetesWorkloadManager implements WorkloadManager {
             },
           },
           spec: {
-            ...this.#defaultPodSpec,
+            ...this.addPlacementTags(this.#defaultPodSpec, opts.placementTags),
+            affinity: this.#getAffinity(opts.machine, opts.projectId),
             terminationGracePeriodSeconds: 60 * 60,
             containers: [
               {
                 name: "run-controller",
-                image: opts.image,
+                image: this.stripImageDigest(opts.image),
                 ports: [
                   {
                     containerPort: 8000,
@@ -77,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,
@@ -228,21 +308,30 @@ export class KubernetesWorkloadManager implements WorkloadManager {
       restartPolicy: "Never",
       automountServiceAccountToken: false,
       imagePullSecrets: this.getImagePullSecrets(),
-      nodeSelector: {
-        nodetype: env.KUBERNETES_WORKER_NODETYPE_LABEL,
-      },
+      ...(env.KUBERNETES_SCHEDULER_NAME
+        ? {
+            schedulerName: env.KUBERNETES_SCHEDULER_NAME,
+          }
+        : {}),
+      ...(env.KUBERNETES_WORKER_NODETYPE_LABEL
+        ? {
+            nodeSelector: {
+              nodetype: env.KUBERNETES_WORKER_NODETYPE_LABEL,
+            },
+          }
+        : {}),
     };
   }
 
   get #defaultResourceRequests(): ResourceQuantities {
     return {
-      "ephemeral-storage": env.EPHEMERAL_STORAGE_SIZE_REQUEST,
+      "ephemeral-storage": env.KUBERNETES_EPHEMERAL_STORAGE_SIZE_REQUEST,
     };
   }
 
   get #defaultResourceLimits(): ResourceQuantities {
     return {
-      "ephemeral-storage": env.EPHEMERAL_STORAGE_SIZE_LIMIT,
+      "ephemeral-storage": env.KUBERNETES_EPHEMERAL_STORAGE_SIZE_LIMIT,
     };
   }
 
@@ -252,20 +341,35 @@ export class KubernetesWorkloadManager implements WorkloadManager {
       envtype: this.#envTypeToLabelValue(opts.envType),
       org: opts.orgId,
       project: opts.projectId,
+      machine: opts.machine.name,
     };
   }
 
   #getResourceRequestsForMachine(preset: MachinePreset): ResourceQuantities {
+    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);
+    const clampedMemory = this.clamp(memoryRequest, this.memoryRequestMinGb, preset.memory);
+
     return {
-      cpu: `${preset.cpu * 0.75}`,
-      memory: `${preset.memory}G`,
+      cpu: `${clampedCpu}`,
+      memory: `${clampedMemory}G`,
     };
   }
 
   #getResourceLimitsForMachine(preset: MachinePreset): ResourceQuantities {
+    const memoryLimit = this.memoryOverheadGb
+      ? preset.memory + this.memoryOverheadGb
+      : preset.memory;
+
     return {
       cpu: `${preset.cpu}`,
-      memory: `${preset.memory}G`,
+      memory: `${memoryLimit}G`,
     };
   }
 
@@ -281,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

@@ -1,4 +1,4 @@
-import { type EnvironmentType, type MachinePreset } from "@trigger.dev/core/v3";
+import type { EnvironmentType, MachinePreset, PlacementTag } from "@trigger.dev/core/v3";
 
 export interface WorkloadManagerOptions {
   workloadApiProtocol: "http" | "https";
@@ -23,11 +23,14 @@ export interface WorkloadManagerCreateOptions {
   version: string;
   nextAttemptNumber?: number;
   dequeuedAt: Date;
+  placementTags?: PlacementTag[];
   // 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

@@ -16,13 +16,14 @@ import {
   type WorkloadRunAttemptCompleteResponseBody,
   WorkloadRunAttemptStartRequestBody,
   type WorkloadRunAttemptStartResponseBody,
-  type WorkloadRunLatestSnapshotResponseBody,
+  WorkloadRunSnapshotsSinceResponseBody,
   type WorkloadServerToClientEvents,
   type WorkloadSuspendRunResponseBody,
 } from "@trigger.dev/core/v3/workers";
 import { HttpServer, type CheckpointClient } from "@trigger.dev/core/v3/serverOnly";
 import { type IncomingMessage } from "node:http";
 import { register } from "../metrics.js";
+import { env } from "../env.js";
 
 // Use the official export when upgrading to socket.io@4.8.0
 interface DefaultEventsMap {
@@ -62,6 +63,8 @@ type WorkloadServerOptions = {
 export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
   private checkpointClient?: CheckpointClient;
 
+  private readonly logger = new SimpleStructuredLogger("workload-server");
+
   private readonly httpServer: HttpServer;
   private readonly websocketServer: Namespace<
     WorkloadClientToServerEvents,
@@ -122,7 +125,7 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
   }
 
   private createHttpServer({ host, port }: { host: string; port: number }) {
-    return new HttpServer({
+    const httpServer = new HttpServer({
       port,
       host,
       metrics: {
@@ -150,7 +153,7 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
             );
 
             if (!startResponse.success) {
-              console.error("Failed to start run", {
+              this.logger.error("Failed to start run", {
                 params,
                 error: startResponse.error,
               });
@@ -170,7 +173,6 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
           paramsSchema: WorkloadActionParams,
           bodySchema: WorkloadRunAttemptCompleteRequestBody,
           handler: async ({ req, reply, params, body }) => {
-            console.log("headers", req.headers);
             const completeResponse = await this.workerClient.completeRunAttempt(
               params.runFriendlyId,
               params.snapshotFriendlyId,
@@ -179,7 +181,7 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
             );
 
             if (!completeResponse.success) {
-              console.error("Failed to complete run", {
+              this.logger.error("Failed to complete run", {
                 params,
                 error: completeResponse.error,
               });
@@ -207,7 +209,7 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
             );
 
             if (!heartbeatResponse.success) {
-              console.error("Failed to heartbeat run", {
+              this.logger.error("Failed to heartbeat run", {
                 params,
                 error: heartbeatResponse.error,
               });
@@ -227,7 +229,7 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
         {
           paramsSchema: WorkloadActionParams,
           handler: async ({ reply, params, req }) => {
-            console.debug("Suspend request", { params, headers: req.headers });
+            this.logger.debug("Suspend request", { params, headers: req.headers });
 
             if (!this.checkpointClient) {
               reply.json(
@@ -246,7 +248,7 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
             const projectRef = this.projectRefFromRequest(req);
 
             if (!runnerId || !deploymentVersion || !projectRef) {
-              console.error("Invalid headers for suspend request", {
+              this.logger.error("Invalid headers for suspend request", {
                 ...params,
                 headers: req.headers,
               });
@@ -282,7 +284,7 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
             });
 
             if (!suspendResult) {
-              console.error("Failed to suspend run", { params });
+              this.logger.error("Failed to suspend run", { params });
               return;
             }
           },
@@ -294,7 +296,7 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
         {
           paramsSchema: WorkloadActionParams,
           handler: async ({ req, reply, params }) => {
-            console.debug("Run continuation request", { params });
+            this.logger.debug("Run continuation request", { params });
 
             const continuationResult = await this.workerClient.continueRunExecution(
               params.runFriendlyId,
@@ -303,7 +305,7 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
             );
 
             if (!continuationResult.success) {
-              console.error("Failed to continue run execution", { params });
+              this.logger.error("Failed to continue run execution", { params });
               reply.json(
                 {
                   ok: false,
@@ -319,41 +321,31 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
           },
         }
       )
-      .route("/api/v1/workload-actions/runs/:runFriendlyId/snapshots/latest", "GET", {
-        paramsSchema: WorkloadActionParams.pick({ runFriendlyId: true }),
-        handler: async ({ req, reply, params }) => {
-          const latestSnapshotResponse = await this.workerClient.getLatestSnapshot(
-            params.runFriendlyId,
-            this.runnerIdFromRequest(req)
-          );
+      .route(
+        "/api/v1/workload-actions/runs/:runFriendlyId/snapshots/since/:snapshotFriendlyId",
+        "GET",
+        {
+          paramsSchema: WorkloadActionParams,
+          handler: async ({ req, reply, params }) => {
+            const sinceSnapshotResponse = await this.workerClient.getSnapshotsSince(
+              params.runFriendlyId,
+              params.snapshotFriendlyId,
+              this.runnerIdFromRequest(req)
+            );
 
-          if (!latestSnapshotResponse.success) {
-            console.error("Failed to get latest snapshot", {
-              runId: params.runFriendlyId,
-              error: latestSnapshotResponse.error,
-            });
-            reply.empty(500);
-            return;
-          }
+            if (!sinceSnapshotResponse.success) {
+              this.logger.error("Failed to get snapshots since", {
+                runId: params.runFriendlyId,
+                error: sinceSnapshotResponse.error,
+              });
+              reply.empty(500);
+              return;
+            }
 
-          reply.json({
-            execution: latestSnapshotResponse.data.execution,
-          } satisfies WorkloadRunLatestSnapshotResponseBody);
-        },
-      })
-      .route("/api/v1/workload-actions/runs/:runFriendlyId/logs/debug", "POST", {
-        paramsSchema: WorkloadActionParams.pick({ runFriendlyId: true }),
-        bodySchema: WorkloadDebugLogRequestBody,
-        handler: async ({ req, reply, params, body }) => {
-          reply.empty(204);
-
-          await this.workerClient.sendDebugLog(
-            params.runFriendlyId,
-            body,
-            this.runnerIdFromRequest(req)
-          );
-        },
-      })
+            reply.json(sinceSnapshotResponse.data satisfies WorkloadRunSnapshotsSinceResponseBody);
+          },
+        }
+      )
       .route("/api/v1/workload-actions/deployments/:deploymentId/dequeue", "GET", {
         paramsSchema: z.object({
           deploymentId: z.string(),
@@ -367,7 +359,7 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
           );
 
           if (!dequeueResponse.success) {
-            console.error("Failed to get latest snapshot", {
+            this.logger.error("Failed to get latest snapshot", {
               deploymentId: params.deploymentId,
               error: dequeueResponse.error,
             });
@@ -378,6 +370,31 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
           reply.json(dequeueResponse.data satisfies WorkloadDequeueFromVersionResponseBody);
         },
       });
+
+    if (env.SEND_RUN_DEBUG_LOGS) {
+      httpServer.route("/api/v1/workload-actions/runs/:runFriendlyId/logs/debug", "POST", {
+        paramsSchema: WorkloadActionParams.pick({ runFriendlyId: true }),
+        bodySchema: WorkloadDebugLogRequestBody,
+        handler: async ({ req, reply, params, body }) => {
+          reply.empty(204);
+
+          await this.workerClient.sendDebugLog(
+            params.runFriendlyId,
+            body,
+            this.runnerIdFromRequest(req)
+          );
+        },
+      });
+    } else {
+      // Lightweight mock route without schemas
+      httpServer.route("/api/v1/workload-actions/runs/:runFriendlyId/logs/debug", "POST", {
+        handler: async ({ reply }) => {
+          reply.empty(204);
+        },
+      });
+    }
+
+    return httpServer;
   }
 
   private createWebsocketServer() {
@@ -391,14 +408,14 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
     > = io.of("/workload");
 
     websocketServer.on("disconnect", (socket) => {
-      console.log("[WorkloadSocket] disconnect", socket.id);
+      this.logger.log("[WS] disconnect", socket.id);
     });
     websocketServer.use(async (socket, next) => {
-      function setSocketDataFromHeader(
+      const setSocketDataFromHeader = (
         dataKey: keyof typeof socket.data,
         headerName: string,
         required: boolean = true
-      ) {
+      ) => {
         const value = socket.handshake.headers[headerName];
 
         if (value) {
@@ -414,27 +431,26 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
         }
 
         if (required) {
-          console.error("[WorkloadSocket] missing required header", { headerName });
+          this.logger.error("[WS] missing required header", { headerName });
           throw new Error("missing header");
         }
-      }
+      };
 
       try {
         setSocketDataFromHeader("deploymentId", WORKLOAD_HEADERS.DEPLOYMENT_ID);
         setSocketDataFromHeader("runnerId", WORKLOAD_HEADERS.RUNNER_ID);
       } catch (error) {
-        console.error("[WorkloadSocket] setSocketDataFromHeader error", { error });
+        this.logger.error("[WS] setSocketDataFromHeader error", { error });
         socket.disconnect(true);
         return;
       }
 
-      console.debug("[WorkloadSocket] auth success", socket.data);
+      this.logger.debug("[WS] auth success", socket.data);
 
       next();
     });
     websocketServer.on("connection", (socket) => {
-      const logger = new SimpleStructuredLogger("workload-namespace", undefined, {
-        namespace: "workload",
+      const socketLogger = this.logger.child({
         socketId: socket.id,
         socketData: socket.data,
       });
@@ -449,11 +465,11 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
       };
 
       const runConnected = (friendlyId: string) => {
-        logger.debug("runConnected", { ...getSocketMetadata() });
+        socketLogger.debug("runConnected", { ...getSocketMetadata() });
 
         // If there's already a run ID set, we should "disconnect" it from this socket
         if (socket.data.runFriendlyId && socket.data.runFriendlyId !== friendlyId) {
-          logger.debug("runConnected: disconnecting existing run", {
+          socketLogger.debug("runConnected: disconnecting existing run", {
             ...getSocketMetadata(),
             newRunId: friendlyId,
             oldRunId: socket.data.runFriendlyId,
@@ -467,14 +483,14 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
       };
 
       const runDisconnected = (friendlyId: string) => {
-        logger.debug("runDisconnected", { ...getSocketMetadata() });
+        socketLogger.debug("runDisconnected", { ...getSocketMetadata() });
 
         this.runSockets.delete(friendlyId);
         this.emit("runDisconnected", { run: { friendlyId } });
         socket.data.runFriendlyId = undefined;
       };
 
-      logger.log("wsServer socket connected", { ...getSocketMetadata() });
+      socketLogger.log("wsServer socket connected", { ...getSocketMetadata() });
 
       // FIXME: where does this get set?
       if (socket.data.runFriendlyId) {
@@ -482,7 +498,7 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
       }
 
       socket.on("disconnecting", (reason, description) => {
-        logger.log("Socket disconnecting", { ...getSocketMetadata(), reason, description });
+        socketLogger.log("Socket disconnecting", { ...getSocketMetadata(), reason, description });
 
         if (socket.data.runFriendlyId) {
           runDisconnected(socket.data.runFriendlyId);
@@ -490,11 +506,11 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
       });
 
       socket.on("disconnect", (reason, description) => {
-        logger.log("Socket disconnected", { ...getSocketMetadata(), reason, description });
+        socketLogger.log("Socket disconnected", { ...getSocketMetadata(), reason, description });
       });
 
       socket.on("error", (error) => {
-        logger.error("Socket error", {
+        socketLogger.error("Socket error", {
           ...getSocketMetadata(),
           error: {
             name: error.name,
@@ -505,7 +521,7 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
       });
 
       socket.on("run:start", async (message) => {
-        const log = logger.child({
+        const log = socketLogger.child({
           eventName: "run:start",
           ...getSocketMetadata(),
           ...message,
@@ -521,7 +537,7 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
       });
 
       socket.on("run:stop", async (message) => {
-        const log = logger.child({
+        const log = socketLogger.child({
           eventName: "run:stop",
           ...getSocketMetadata(),
           ...message,
@@ -545,7 +561,7 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
       const runSocket = this.runSockets.get(run.friendlyId);
 
       if (!runSocket) {
-        console.debug("[WorkloadServer] notifyRun: Run socket not found", { run });
+        this.logger.debug("notifyRun: Run socket not found", { run });
 
         this.workerClient.sendDebugLog(run.friendlyId, {
           time: new Date(),
@@ -556,14 +572,14 @@ export class WorkloadServer extends EventEmitter<WorkloadServerEvents> {
       }
 
       runSocket.emit("run:notify", { version: "1", run });
-      console.debug("[WorkloadServer] run:notify sent", { run });
+      this.logger.debug("run:notify sent", { run });
 
       this.workerClient.sendDebugLog(run.friendlyId, {
         time: new Date(),
         message: "run:notify supervisor -> runner",
       });
     } catch (error) {
-      console.error("[WorkloadServer] Error in notifyRun", { run, error });
+      this.logger.error("Error in notifyRun", { run, error });
 
       this.workerClient.sendDebugLog(run.friendlyId, {
         time: new Date(),