chore: release v4.5.4 (#4228)

## Summary
2 new features, 11 improvements, 5 bug fixes.

## Breaking changes
- Trigger.dev v3 is no longer supported. For self-hosted deployments,
4.5.0 is the last version we officially support for running v3; stay on
4.5.0 or upgrade to v4. v3 triggers, batch triggers, reschedules, and
deploys now return a clear upgrade message instead of running.
([#4236](https://github.com/triggerdotdev/trigger.dev/pull/4236))

## Improvements
- You can now mark environment variables synced via the `syncEnvVars`
build extension as secrets. Return `{ name, value, isSecret: true }`
from your callback and those variables are stored redacted in the
dashboard, just like manually created secret env vars.
([#4203](https://github.com/triggerdotdev/trigger.dev/pull/4203))
- Remove the legacy `--mcp` and `--mcp-port` options from the `dev`
command. Run the dedicated `trigger mcp` command to start the
Trigger.dev MCP server.
([#4246](https://github.com/triggerdotdev/trigger.dev/pull/4246))
- Removed the unused `ResourceMonitor` export from
`@trigger.dev/core/v3/serverOnly`. It was a server-side logging helper
with no remaining consumers.
([#4244](https://github.com/triggerdotdev/trigger.dev/pull/4244))
- Removed the unused `@trigger.dev/core/v3/zodNamespace` export and the
legacy v3 socket message schemas. These were only used by the
now-retired v3 engine and have no v4 consumers.
([#4236](https://github.com/triggerdotdev/trigger.dev/pull/4236))

## Bug fixes
- Fix a `chat.agent` message-loss race where sending a message right
after an action (such as an undo) could drop the follow-up's response
from the UI until a refresh.
([#4234](https://github.com/triggerdotdev/trigger.dev/pull/4234))

## Server changes

These changes affect the self-hosted Docker image and Trigger.dev Cloud:

- Added `EVENT_REPOSITORY_POSTGRES_WRITES_DISABLED` to skip all
PostgreSQL task-event writes for deployments that store task events in
ClickHouse. Leave it off unless `EVENT_REPOSITORY_DEFAULT_STORE` is
`clickhouse_v2`, otherwise task events are lost.
([#4242](https://github.com/triggerdotdev/trigger.dev/pull/4242))
- Promo credits: a /promo signup landing page, redeeming a promo code
when a new org selects a plan, and showing remaining credits on the
usage page.
([#4138](https://github.com/triggerdotdev/trigger.dev/pull/4138))
- Speed up retrieving a background worker by version. The endpoint no
longer runs a slow lookup that scanned the full task table for large
deployments; it now reuses data it already loads, so the response is the
same but returns much faster.
([#4245](https://github.com/triggerdotdev/trigger.dev/pull/4245))
- Clearer login error when an email address is blocked by the
WHITELISTED_EMAILS setting: the message now explains the address isn't
allowed on this instance instead of the ambiguous "This email is
unauthorized".
([#4220](https://github.com/triggerdotdev/trigger.dev/pull/4220))
- Make the native build server the default in project build settings.
It's now opt-out, stored as a new `disableNativeBuildServer` key. Also
clarifies in the UI that build settings apply to GitHub-triggered and
native build server deployments.
([#3980](https://github.com/triggerdotdev/trigger.dev/pull/3980))
- Optionally process high-volume telemetry ingestion in parallel for
higher throughput under heavy load by setting
`OTEL_TRANSFORM_WORKER_POOL_ENABLED=1`. Off by default.
([#4232](https://github.com/triggerdotdev/trigger.dev/pull/4232))
- Add a `REALTIME_BACKEND_DEFAULT` env var to choose the default
realtime backend (`electric`, `native`, or `shadow`) for environments
whose org has no per-org override. Defaults to `electric`, so existing
behavior is unchanged.
([#4231](https://github.com/triggerdotdev/trigger.dev/pull/4231))
- Clarified on the Regions page that a region only affects where your
runs execute, not where your data is stored. This shows as a tooltip on
the Location column and in the confirmation dialog when you change your
default region.
([#4226](https://github.com/triggerdotdev/trigger.dev/pull/4226))
- Improved the reliability of how run data is read and written.
([#4237](https://github.com/triggerdotdev/trigger.dev/pull/4237))
- Fixed stale login errors: an error from a previous login attempt (for
example a rejected email address) no longer keeps reappearing on the
login page and no longer makes later, successful attempts look like they
failed.
([#4220](https://github.com/triggerdotdev/trigger.dev/pull/4220))
- The Errors page now shows better details for each error. Errors that
don't carry a message — such as errors thrown without a message, or
values thrown that aren't `Error` objects — get a meaningful title
instead of all reading "Unknown error", and are grouped by their name
(or value) rather than collapsed into a single group. The error type now
shows the actual error name, and stack traces now appear where
previously they were missing.
([#4225](https://github.com/triggerdotdev/trigger.dev/pull/4225))
- Return a clear client error when SSO form submissions use an
unsupported content type
([#4238](https://github.com/triggerdotdev/trigger.dev/pull/4238))
- Query page: extracting fields from a run's output with JSON functions
(such as JSONExtractString or JSONExtractInt) no longer fails with an
"illegal type: JSON" error.
([#4221](https://github.com/triggerdotdev/trigger.dev/pull/4221))

<details>
<summary>Raw changeset output</summary>

# Releases
## @trigger.dev/build@4.5.4

### Patch Changes

- You can now mark environment variables synced via the `syncEnvVars`
build extension as secrets. Return `{ name, value, isSecret: true }`
from your callback and those variables are stored redacted in the
dashboard, just like manually created secret env vars.
([#4203](https://github.com/triggerdotdev/trigger.dev/pull/4203))
- Updated dependencies:
  - `@trigger.dev/core@4.5.4`
## trigger.dev@4.5.4

### Patch Changes

- Remove the legacy `--mcp` and `--mcp-port` options from the `dev`
command. Run the dedicated `trigger mcp` command to start the
Trigger.dev MCP server.
([#4246](https://github.com/triggerdotdev/trigger.dev/pull/4246))
- Updated dependencies:
  - `@trigger.dev/core@4.5.4`
  - `@trigger.dev/build@4.5.4`
  - `@trigger.dev/schema-to-json@4.5.4`
## @trigger.dev/core@4.5.4

### Patch Changes

- Removed the unused `ResourceMonitor` export from
`@trigger.dev/core/v3/serverOnly`. It was a server-side logging helper
with no remaining consumers.
([#4244](https://github.com/triggerdotdev/trigger.dev/pull/4244))
- Removed the unused `@trigger.dev/core/v3/zodNamespace` export and the
legacy v3 socket message schemas. These were only used by the
now-retired v3 engine and have no v4 consumers.
([#4236](https://github.com/triggerdotdev/trigger.dev/pull/4236))
## @trigger.dev/python@4.5.4

### Patch Changes

- Updated dependencies:
  - `@trigger.dev/sdk@4.5.4`
  - `@trigger.dev/core@4.5.4`
  - `@trigger.dev/build@4.5.4`
## @trigger.dev/react-hooks@4.5.4

### Patch Changes

- Updated dependencies:
  - `@trigger.dev/core@4.5.4`
## @trigger.dev/redis-worker@4.5.4

### Patch Changes

- Updated dependencies:
  - `@trigger.dev/core@4.5.4`
## @trigger.dev/rsc@4.5.4

### Patch Changes

- Updated dependencies:
  - `@trigger.dev/core@4.5.4`
## @trigger.dev/schema-to-json@4.5.4

### Patch Changes

- Updated dependencies:
  - `@trigger.dev/core@4.5.4`
## @trigger.dev/sdk@4.5.4

### Patch Changes

- Fix a `chat.agent` message-loss race where sending a message right
after an action (such as an undo) could drop the follow-up's response
from the UI until a refresh.
([#4234](https://github.com/triggerdotdev/trigger.dev/pull/4234))
- Updated dependencies:
  - `@trigger.dev/core@4.5.4`

</details>

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

.changeset/config.json

@@ -1,22 +1,23 @@
 {
   "$schema": "https://unpkg.com/@changesets/config@2.2.0/schema.json",
-  "changelog": "@changesets/cli/changelog",
-  "commit": false,
-  "fixed": [
-    [
-      "@trigger.dev/*"
-    ]
+  "changelog": [
+    "@remix-run/changelog-github",
+    {
+      "repo": "triggerdotdev/trigger.dev"
+    }
   ],
+  "commit": false,
+  "fixed": [["@trigger.dev/*", "trigger.dev"]],
   "linked": [],
   "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
   "ignore": [
     "webapp",
-    "emails",
-    "@trigger.dev/database"
+    "supervisor",
+    "@trigger.dev/plugins"
   ],
   "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
     "onlyUpdatePeerDependentsWhenOutOfRange": true
   }
-}
+}

.claude/REVIEW.md

@@ -0,0 +1,82 @@
+# REVIEW.md — Trigger.dev OSS
+
+Repo-specific signal for anyone (human or agent) reviewing a PR in this codebase. Calibrates what counts as critical, what to always check, and what to skip.
+
+## What makes a 🔴 Important finding here
+
+Reserve 🔴 for things that would page someone or block a rollback. In this codebase, that means:
+
+- **Rolling-deploy breakage.** Old and new versions of the webapp/supervisor run side-by-side during deploys. A change is broken if:
+  - A Lua script's behavior changes for a given key set without versioning (rename the script with a behavior-descriptive suffix like `Tracked` rather than `V2` — both versions must coexist safely).
+  - A Redis data shape used by both versions changes in place. New shapes need a new key namespace.
+  - A migration is not backward-compatible with the prior image.
+- **Schema / migration safety.** Prisma migrations must be backward-compatible with the prior deploy. Adding NOT NULL without a default, dropping a column an old image still reads, renaming a column — all 🔴.
+- **ClickHouse migration ordering + idempotency.** Goose runs in strict mode in the deploy pipeline and refuses to apply a missing version below the current version — slotting a new file in below the latest already-applied version blocks the deploy. New ClickHouse migration files MUST use the next available number (`max(files in internal-packages/clickhouse/schema/) + 1`); if main has added migrations while you've been on a branch, renumber yours. DDL must also be idempotent (`ADD COLUMN IF NOT EXISTS`, `DROP COLUMN IF EXISTS`, `CREATE TABLE IF NOT EXISTS`, `ADD INDEX IF NOT EXISTS`) so a partial / `--allow-missing` apply elsewhere doesn't fail on retry. Either fault is 🔴 — both break test/prod deploys. Rules live in `internal-packages/clickhouse/CLAUDE.md`.
+- **Queue / concurrency correctness.** RunQueue, MarQS (V1, legacy), redis-worker — any change to enqueue / dequeue / locking semantics. Re-derive the invariant on paper before flagging or accepting.
+- **Missing index on a hot table.** New Prisma queries against `TaskRun`, `TaskRunExecutionSnapshot`, `JobRun`, `Project`, etc. must use an existing index. Check `internal-packages/database/prisma/schema.prisma` for the relevant `@@index` lines — don't guess and don't propose `EXPLAIN`.
+- **Recovery-path queries.** Any `TaskRun.findFirst` / `findMany` added to a schedule, run-recovery, or restart loop. Recovery fan-outs (Redis crash, restart storms) turn "rare indexed query" into a DB incident. 🔴 even if indexed.
+- **Aggregations on hot tables.** No `COUNT` / `GROUP BY` on `TaskRun` or other tables that can reach billions of rows. Use Redis or ClickHouse for counts.
+- **Prod Redis blast-radius.** New code paths that `SCAN` with broad patterns (`*foo*`) on prod-shaped Redis, or `EVAL` Lua with `SCAN` loops inside. Both are 🔴.
+- **`@trigger.dev/core` direct import** from anywhere outside the SDK package. Always import from `@trigger.dev/sdk`. Core direct imports are 🔴 — they break the public API contract.
+- **Heavy execute-deps imported into request-handler bundles.** Specifically `chat.handover` and similar split-bundle entry points must not transitively import the agent task's execute path. Watch for new imports added at module top-level of route files.
+- **V1 engine code modified in a "V2 only" PR.** The `apps/webapp/app/v3/` directory contains both. If the PR description says V2-only but it touches `triggerTaskV1`, `cancelTaskRunV1`, `MarQS`, etc. — 🔴.
+
+## Performance (always review)
+
+Every PR gets a performance pass — not just the ones that look perf-sensitive. For each new query or unit of work, weigh three things: (a) the size of the table it hits, (b) whether it sits on a hot path, (c) whether the data it walks can be deep or wide (run trees, batches). The 🔴 bullets above on indexes, recovery-path queries, aggregations, and Redis `SCAN` are part of this pass — the rest below extends it.
+
+**Treat these tables as large — no scans, no `COUNT` / `GROUP BY`, no unbounded fetch:**
+
+- **Postgres — the `TaskRun` family:** `TaskRun`, `TaskRunExecutionSnapshot`, `Waitpoint`, `BatchTaskRun` and their join tables. Assume billions of rows.
+- **ClickHouse — `task_events_v1` / `task_events_v2`.** Partitioned by `toDate(inserted_at)`; `ORDER BY (environment_id, toUnixTimestamp(start_time), trace_id)`. Note `span_id` / `parent_span_id` are NOT in the sort key — span-id lookups can't skip granules, only `environment_id` + a `start_time` window can.
+
+**Hot paths — extra scrutiny on any added query or work:**
+
+- **Trigger + batch trigger** (`triggerTask.server.ts`, `batchTriggerV3.server.ts`) — see `apps/webapp/CLAUDE.md`; do not add DB queries to these.
+- **Dequeue / RunQueue** (`dequeueSystem.ts`, run-queue read/lock paths) — runs on every execution.
+- **Execution-snapshot creation in the run engine** — any engine function that writes a `TaskRunExecutionSnapshot` runs per state transition; a new query there multiplies by run volume.
+- **OTEL ingestion** (`otel.v1.traces.ts`, `otel.v1.logs.ts`) — write volume scales with customer span counts.
+- **Trace + run-list reads** (trace view, run list, span detail) — read paths over the large tables above.
+
+**Deep / wide shapes — one run can explode into a huge tree or batch; code that walks them is the trap:**
+
+- Trace span subtrees (deeply nested child runs → deep span trees).
+- Batch + parent/child fan-out (one run triggers thousands of children).
+- Waitpoint / run-dependency chains.
+- Tag / attribute many-to-many joins against the run/event tables.
+
+**Anti-patterns (severity):**
+
+- **Per-level fan-out that re-scans a large table once per tree depth** → 🔴. A BFS issuing one query per level (e.g. `parent_span_id IN {thisLevel}`) re-reads the same granules D times for a depth-D tree. Prefer one windowed query + an in-memory tree build.
+- **Dropping the partition-pruning predicate** — `inserted_at` for ClickHouse, the `createdAt` window for partitioned Postgres — to "widen" a lookup → 🔴. Without it the query scans every partition. Keep a bounded window even for ancestor / backfill lookups.
+- **Unbounded `IN (...)` built from a result set** (a BFS frontier, a batch's child ids) → 🟡. It can reach the row cap (`MAXIMUM_TRACE_SUMMARY_VIEW_COUNT` defaults to 25k). Cap or chunk to ≤1–2k ids per query.
+- **Sequential per-level round-trips** where one recursive or windowed query would do → 🟡. N levels = N round-trip latencies stacked.
+- **Replacing a single bounded query with a multi-query walk for _every_ call** (not just a rare fallback) → 🔴 on a hot read path, 🟡 elsewhere. Keep the cheap single-query path; branch into the expensive walk only when the cheap one comes up short.
+
+## Always check
+
+- **Tests use testcontainers, not mocks.** Vitest with `redisTest` / `postgresTest` / `containerTest` from `@internal/testcontainers`. Any new `vi.mock(...)` on Redis, Postgres, BullMQ, or other infra is wrong here — 🔴 if added in production-path tests, 🟡 if isolated unit test.
+- **Public-package changes have a changeset.** `pnpm run changeset:add` produces `.changeset/*.md`. Required for any edit under `packages/*`. Missing → 🟡; missing on a breaking change → 🔴.
+- **Server-only changes have `.server-changes/*.md`.** Required for `apps/webapp/`, `apps/supervisor/` edits with no public-package change. Body should be 1-2 sentences (it has to fit as one bullet in a future changelog). Missing → 🟡.
+- **Lua script naming.** Coexisting scripts use behavior-descriptive suffixes (`Tracked`), never `V2`. Old name must keep working until the next deploy clears it.
+- **RunQueue payload shape.** V2 run-queue payload's `projectId` is consumed by `workerQueueResolver` for override matching. If a PR drops it from the payload, 🔴.
+- **`safeSend` scope.** Defensive IPC wrappers belong on loop / interval / handler contexts, not one-shot terminal sends. If the PR adds `safeSend` to a single terminal call for consistency, 🟡 with a "remove this" suggestion.
+- **Zod version.** Pinned to `3.25.76` monorepo-wide. New package adding zod with a different version or range — 🔴.
+
+## Skip (do NOT flag)
+
+- Anything oxfmt / oxlint catches. CI enforces both via the `code-quality` check.
+- TypeScript style preferences (`type` vs `interface`) — already covered by repo standards.
+- Test coverage exhortations as a generic suggestion. Only flag missing tests when a specific code path is genuinely untested and the path has prior incidents.
+- `agentcrumbs` markers (`// @crumbs`, `// #region @crumbs`) and `agentcrumbs` imports — these are temporary debug instrumentation stripped before merge.
+- `// removed comments for removed code`, renamed `_unused` vars, re-exported types as "backwards compatibility shims" — also covered by repo standards.
+- Suggestions to "add error handling" without naming a specific scenario that breaks.
+- Documentation prose nitpicks in `docs/*` MDX files unless factually wrong.
+
+## Things V1/legacy that should NOT block a PR
+
+The `apps/webapp/app/v3/` directory name is misleading — most code there is V2. Only specific files are V1-only legacy: `MarQS` queue, `triggerTaskV1`, `cancelTaskRunV1`, and a handful of others (see `apps/webapp/CLAUDE.md` for the exact list). Don't flag "you should refactor this to use V2" on those — they're frozen.
+
+## Confidence calibration for this repo
+
+The most common false-positive pattern: speculating about race conditions in code paths the agent doesn't have runtime visibility into. If the only evidence is "this *could* race", drop it. If you can point to a specific interleaving with file:line for each step, surface it.

.claude/review-guides/chat-agent-sessions-row-agnostic.md

@@ -0,0 +1,287 @@
+# Review guide — chat.agent on Sessions, row-agnostic addressing
+
+Scope: the 12 uncommitted files. **No new behaviour beyond the public surface
+already on this branch** — this is plumbing cleanup that:
+
+1. Eliminates the transport's session-creation step
+2. Makes `chatId` the universal addressing string everywhere
+3. Makes the server-side stream/append/wait routes row-agnostic
+
+## The two design moves
+
+**Move 1 — agent owns session lifecycle.** `chat.agent` and
+`chat.customAgent` upsert the backing `Session` row at bind, fire-and-forget,
+keyed on `externalId = payload.chatId`. The transport, server-side
+`AgentChat`, and `chat.createTriggerAction` no longer create sessions at all.
+Browsers cannot mint sessions either (`POST /api/v1/sessions` is now
+secret-key-only). One owner, one path.
+
+**Move 2 — `chatId` is the only address.** The transport, server-side
+`AgentChat`, JWT scopes, and S2 stream paths all use `chatId` directly. The
+Session's friendlyId is informational. To make this safe, the three stream
+routes (`.in/.out` PUT, GET, POST append, plus the run-engine `wait`
+endpoint) became "row-optional" and derive a *canonical addressing key*
+(`row.externalId ?? row.friendlyId`, fallback to the URL param when the row
+hasn't been upserted yet). Same canonical key is used to build the S2 stream
+path, the waitpoint cache key, and the JWT resource set — so any caller
+addressing by either form converges on the same physical stream.
+
+Together these remove an entire class of "did the row land yet?" races. The
+transport can subscribe to `/sessions/{chatId}/out` before the agent boots,
+the agent's `void sessions.create({externalId: chatId})` lands a moment
+later, and any earlier reads/writes are already on the right S2 key.
+
+---
+
+## Read in this order
+
+### 1. `apps/webapp/app/services/realtime/sessions.server.ts` (+34 lines)
+
+The new primitive. Two helpers:
+
+- `isSessionFriendlyIdForm(value)` — `value.startsWith("session_")`. Used to
+  decide whether a missing row is a hard 404 (opaque friendlyId) or a soft
+  "row will land later" (externalId form).
+- `canonicalSessionAddressingKey(row, paramSession)` — `row.externalId ??
+  row.friendlyId` if the row exists, else `paramSession`. **This is the load-
+  bearing function.** Read its docstring.
+
+**Question to ask:** can two callers addressing the "same" session ever get
+different canonical keys? Only if the row exists for one and not the other,
+*and* the URL forms differ — but in that case the row-less caller used the
+externalId form (friendlyId-form would have 404'd earlier), and the row-ful
+caller computes `row.externalId ?? row.friendlyId`. If the row's externalId
+matches the URL, they converge. If it doesn't, there's no row to find by
+that string anyway. The interesting edge is "row exists with no externalId",
+addressed via friendlyId — both sides read `row.friendlyId`. ✓
+
+### 2. `apps/webapp/app/routes/realtime.v1.sessions.$session.$io.ts` (+47/-12)
+
+PUT initialize + GET subscribe (SSE). Both use the helper. The interesting
+part is the loader's `findResource` + `authorization.resource`:
+
+```ts
+findResource: async (params, auth) => {
+  const row = await resolveSessionByIdOrExternalId(...);
+  if (!row && isSessionFriendlyIdForm(params.session)) return undefined; // 404
+  return { row, addressingKey: canonicalSessionAddressingKey(row, params.session) };
+},
+authorization: {
+  resource: ({ row, addressingKey }) => {
+    const ids = new Set<string>([addressingKey]);
+    if (row) {
+      ids.add(row.friendlyId);
+      if (row.externalId) ids.add(row.externalId);
+    }
+    return { sessions: [...ids] };
+  },
+  superScopes: ["read:sessions", "read:all", "admin"],
+},
+```
+
+**Why three IDs in the resource set?** `checkAuthorization` is "any-match"
+across the resource values. We want a JWT scoped to *either* form to
+authorize *either* URL form. Smoke test verified the 4-cell matrix passes.
+
+**The PUT path** (action handler) is simpler — it just resolves the row,
+builds an addressing key, and hands it to `initializeSessionStream`. Worth
+noting the `closedAt` check is now `maybeSession?.closedAt` — no row means
+no closedAt to enforce.
+
+### 3. `apps/webapp/app/routes/realtime.v1.sessions.$session.$io.append.ts` (+22/-13)
+
+POST append (browser writes a record to `.in` or server writes to `.out`).
+Same row-optional pattern. Both the S2 append and the waitpoint drain use
+`addressingKey`.
+
+**Question to ask:** what fires the waitpoint? An agent's
+`session.in.wait()` registers a waitpoint keyed on `(addressingKey, io)` via
+the wait endpoint (file 4). The append handler drains by the *same* key —
+even if the agent registered with externalId form and the transport
+appended via friendlyId form, both compute the same canonical key, so they
+converge. ✓
+
+### 4. `apps/webapp/app/routes/api.v1.runs.$runFriendlyId.session-streams.wait.ts` (+18/-13)
+
+The agent's `.in.wait()` endpoint. Run-engine creates the waitpoint, then
+registers it in Redis under `(addressingKey, io)`. The race-check that runs
+right after creation reads from S2 by the same key. Three call sites —
+`addSessionStreamWaitpoint`, `readSessionStreamRecords`,
+`removeSessionStreamWaitpoint` — all consistent.
+
+### 5. `apps/webapp/app/routes/api.v1.sessions.ts` (+4/-2)
+
+**Security tightening.** Removed `allowJWT: true` and `corsStrategy: "all"`
+from the `POST /api/v1/sessions` action — secret-key only now.
+
+**Question to ask:** was the JWT path actually used? Until this branch, the
+transport called it via `ensureSession` (now deleted). After this branch,
+nobody reaches it from the browser. `chat.createTriggerAction` (server
+secret key) is the only browser-adjacent path.
+
+### 6. `packages/trigger-sdk/src/v3/ai.ts` (+62/-39)
+
+Two near-identical edits — one in `chatAgent`, one in `chatCustomAgent`.
+Both bind on `payload.chatId` and fire-and-forget the upsert:
+
+```ts
+locals.set(chatSessionHandleKey, sessions.open(payload.chatId));
+void sessions
+  .create({ type: "chat.agent", externalId: payload.chatId })
+  .catch(() => { /* best effort */ });
+```
+
+**Question to ask:** why `void`-and-`catch`? Awaiting the upsert would gate
+the agent's bind on a network round-trip that doesn't unblock anything
+user-visible — `.in/.out` routes are row-agnostic and the waitpoint cache
+is keyed on the addressing string, not the row id. If the upsert genuinely
+fails, the next bind retries the same idempotent call (`sessions.create`
+upserts on `externalId`, so concurrent triggers on one chatId converge to
+one row). The row matters for downstream metadata + listing, not for live
+addressing.
+
+The PAT scope minting in `chatAgent` (two call sites — preload and
+sendMessage) now uses `payload.chatId` for the `sessions:` resource. That
+matches what the transport/AgentChat use as the JWT resource and what the
+JWT's resource set in the loader includes. Cross-form addressing works
+either way (smoke-tested), but using `chatId` keeps the chain tight.
+
+`createChatTriggerAction` is the most visibly trimmed: no pre-create, no
+threading `sessionId` into payload, scope mint uses `chatId`. Return type
+no longer carries `sessionId` — note `TriggerChatTaskResult.sessionId` was
+already declared optional, so this isn't a public-API break.
+
+**Stale docstring to flag:** `chat.ts:59` and `chat.ts:112` still describe
+PAT scopes as `read:sessions:{sessionId}` and
+`write:sessions:{sessionId}`. Functionally either ID works (row lookup
+canonicalises), but the doc text is now out of date — it should say
+`{chatId}`. Worth a tidy-up before merge but not blocking.
+
+### 7. `packages/trigger-sdk/src/v3/chat.ts` (+63/-117)
+
+**The biggest mechanical edit.** Net -54 lines from deleting `ensureSession`
+and untangling its callers.
+
+What disappeared:
+- `private async ensureSession(chatId)` — gone
+- The "lazy upsert from the browser if no triggerTask callback" branch in
+  `sendMessages` and `preload` — gone
+- The "throw if neither path surfaced a sessionId" guard — gone
+- All `state.sessionId` URL params replaced with `chatId`
+- `subscribeToSessionStream`'s `chatId?` (optional) is now `chatId` (required)
+
+What stayed:
+- `state.sessionId` in `ChatSessionState` — optional, informational
+- The `restore from external storage` branch in the constructor still
+  hydrates `sessionId` if persisted, just doesn't *require* it
+- `notifySessionChange` still surfaces `sessionId` if known
+
+**Question to ask:** does the transport ever still need the friendlyId? The
+only place is the `onSessionChange` callback's payload (so consumers
+persisting state can save it for later display). The transport itself never
+puts it in a URL or a waitpoint key.
+
+The `sendMessages` path is worth re-reading: when state.runId is set, it
+appends to `.in/append` and subscribes to `.out`. If the append fails with
+a non-auth error, it falls through to triggering a new run (legacy "run is
+dead" detection — unchanged from pre-Sessions, doesn't depend on
+addressing).
+
+### 8. `packages/trigger-sdk/src/v3/chat-client.ts` (+34/-33)
+
+Server-side `AgentChat`. Mirrors the transport changes — every URL uses
+`this.chatId`. `triggerNewRun` no longer pre-creates a session. `ChatSession`
+and internal `SessionState` types now have optional `sessionId`.
+
+The shape of the diff is identical to the transport: delete the upsert,
+swap addressing identifiers, optionalise the friendlyId. If you've read
+`chat.ts` carefully, this one is mostly mechanical confirmation that both
+client surfaces (browser transport + server-side AgentChat) speak the same
+addressing protocol.
+
+### 9. Test infrastructure — `sessions.ts` (+18) + `mock-chat-agent.ts` (+25)
+
+`__setSessionCreateImplForTests` mirrors the existing
+`__setSessionOpenImplForTests`. `mockChatAgent` installs a no-op create stub
+returning a synthetic `CreatedSessionResponseBody` so the agent's bind-time
+`void sessions.create(...)` doesn't try to hit a real API. Cleanup runs in
+the same `.finally` as the open override.
+
+**Question to ask:** is the synthetic response shape correct? It mirrors
+`CreatedSessionResponseBody` — `id`, `externalId`, `type`, `tags`,
+`metadata`, `closedAt`, `closedReason`, `expiresAt`, `createdAt`,
+`updatedAt`, `isCached`. Tests don't currently assert on this object, so
+the bar is "doesn't crash + matches the type". Met.
+
+### 10. `packages/trigger-sdk/src/v3/chat.test.ts` (+13/-12)
+
+Three classes of test edits, all consequences:
+
+- Stream URL assertion: `chat-1` (the chatId) instead of
+  `session_streamurl` (the friendlyId)
+- `renewRunAccessToken` callback: `sessionId: undefined` (was
+  `DEFAULT_SESSION_ID` because the mocked trigger doesn't surface it)
+- Token resolve count: `1` (was `2` — second resolve was for `ensureSession`)
+- One `onSessionChange` matchObject loses `sessionId`
+
+### 11. `apps/webapp/app/routes/_app.../playground/.../route.tsx` (1 line)
+
+`sessionId: string` → `sessionId?: string` in the playground sidebar prop
+to track the transport type change.
+
+---
+
+## Edge cases I checked, so you don't have to
+
+- **Cross-form JWT auth (curl matrix).** JWT scoped to externalId can call
+  externalId URL ✓ and friendlyId URL ✓. JWT scoped to friendlyId can call
+  externalId URL ✓ and friendlyId URL ✓. Smoke-tested.
+- **Row materialises after subscribe.** Transport opens
+  `GET /sessions/{chatId}/out` before agent's bind upsert lands → 200 OK,
+  `addressingKey = chatId` (paramSession fallback). Once the row lands
+  with `externalId = chatId`, addressingKey resolves to the same value via
+  `row.externalId`. Same S2 key throughout.
+- **Concurrent triggers on one chatId.** Two browser tabs trigger two runs
+  → two binds → two `sessions.create({externalId: chatId})` calls. Upsert
+  semantics: both return the same row.
+- **Closed session enforcement.** Still enforced when a row exists.
+  `maybeSession?.closedAt` is null-safe; no row = no close-state to honour.
+- **Agent run cancellation.** Frontend doesn't auto-detect — unchanged from
+  pre-Sessions; messages sit in S2 until the next trigger (the existing
+  run-PAT auth-error path is the only reaper). Out of scope for this branch.
+- **Idle timeout in dev.** Runs stay `EXECUTING_WITH_WAITPOINTS` past the
+  configured idle because dev runs don't snapshot/restore; the in-process
+  idle clock advances locally without touching the row. Expected, not a
+  regression.
+
+## Things explicitly **not** in this branch
+
+- Run-state subscription on the transport side (the "run died, re-trigger
+  silently" UX gap)
+- Session auto-close on agent exit (still client-driven by design)
+- Any change to `Session` schema, `sessions.create` semantics, or
+  `chatAccessTokenTTL`
+- Docstring updates for `read:sessions:{sessionId}` / `write:sessions:{sessionId}`
+  in `chat.ts:59` and `chat.ts:112` (functional but textually stale —
+  follow-up nit)
+
+---
+
+## What I'd be ready to answer cold
+
+- Why fire-and-forget upsert (vs. `await`) in the agent's bind step
+- Why the route's authorization resource set has three IDs (cross-form JWT
+  auth)
+- Why `POST /api/v1/sessions` lost `allowJWT` (security tightening — no
+  caller needs it after the transport's `ensureSession` is gone)
+- What converges two callers using different URL forms onto the same S2
+  stream (`canonicalSessionAddressingKey`, identical computation on both
+  sides for any given row)
+- What makes `sessions.create` race-safe under concurrent triggers
+  (`externalId` upsert)
+- Why `state.sessionId` stayed on `ChatSessionState` at all (pure
+  informational, surfaced via `onSessionChange` for consumer persistence;
+  zero addressing role)
+- Why the chat-client (server-side AgentChat) and chat (transport) edits
+  look near-identical (they implement the same client protocol against the
+  same row-agnostic routes)

.claude/rules/database-safety.md

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

.claude/rules/docs-writing.md

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

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

@@ -0,0 +1,26 @@
+---
+paths:
+  - "apps/webapp/app/v3/**"
+---
+
+# v3 (engine V1) has been removed
+
+The v3 engine (RunEngineVersion `V1`: MarQS queue + Graphile worker) is end-of-life and its execution code has been removed from the webapp. The `app/v3/` directory name is historical: everything under it now serves the current V2 engine (`@internal/run-engine` + `@trigger.dev/redis-worker`).
+
+There is no `V1` execution path anymore. If you find a `RunEngineVersion` branch, the `V1` arm should only reject or finalize gracefully (for example, mark a historical run cancelled in the DB), never run V1 work. Do not reintroduce MarQS, the graphile worker, or the v3 socket.io namespaces.
+
+## The deprecation boundary (keep this)
+
+Requests from clients still on v3 (old SDK/CLI) or historical V1 runs must return a clean 4xx, never a 5xx. The boundary lives in:
+
+- `engineDeprecation.server.ts` - the `V3_TRIGGER_DEPRECATION_MESSAGE` / `V3_DEV_DEPRECATION_MESSAGE` / `V3_MIGRATION_URL` upgrade messages.
+- `engineVersion.server.ts` - `determineEngineVersion()` still detects a V1 project/run so callers can reject it.
+- `services/triggerTask.server.ts`, `services/cancelTaskRun.server.ts`, `services/rescheduleTaskRun.server.ts` - the `V1` arm rejects or finalizes gracefully instead of executing.
+- `services/initializeDeployment.server.ts` - the `DEPRECATE_V3_CLI_DEPLOYS_ENABLED`-gated v3 CLI deploy rejection.
+- `handleWebsockets.server.ts` - the legacy `trigger dev` websocket closes with the upgrade message.
+
+## V2 modern stack
+
+- **Run lifecycle**: `@internal/run-engine` (`runEngine.server.ts`, `runEngineHandlers.server.ts`)
+- **Background jobs**: `@trigger.dev/redis-worker` (`commonWorker.server.ts`, `alertsWorker.server.ts`, `batchTriggerWorker.server.ts`; `legacyRunEngineWorker.server.ts` still hosts the live batch-completion jobs)
+- **Queue operations**: RunQueue inside run-engine (`runQueue.server.ts`), not MarQS

.claude/rules/package-installation.md

@@ -0,0 +1,22 @@
+---
+paths:
+  - "**/package.json"
+---
+
+# Installing Packages
+
+When adding a new dependency to any package.json in the monorepo:
+
+1. **Look up the latest version** on npm before adding:
+   ```bash
+   pnpm view <package-name> version
+   ```
+   If unsure which version to use (e.g. major version compatibility), confirm with the user.
+
+2. **Edit the package.json directly** — do NOT use `pnpm add` as it can cause issues in the monorepo. Add the dependency with the correct version range (typically `^x.y.z`).
+
+3. **Run `pnpm i` from the repo root** after editing to install and update the lockfile:
+   ```bash
+   pnpm i
+   ```
+   Always run from the repo root, not from the package directory.

.claude/rules/sdk-packages.md

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

.claude/rules/server-apps.md

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

.claude/skills/drizzle/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: drizzle
+description: Use this skill when writing or modifying Drizzle ORM schemas, queries, or migrations in this repo — specifically the `@internal/dashboard-agent-db` package (the dashboard agent's conversation datastore). Covers pg-core schema definition, the postgres-js driver, drizzle-kit migrations, and this repo's conventions: a dedicated Postgres schema, foreign-key-free cross-database design, pooler-safe connections, and the access-pattern query layer. Drizzle is NOT the main database — that's Prisma.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Drizzle ORM (this repo)
+
+Drizzle is used in exactly one place: **`internal-packages/dashboard-agent-db`** (`@internal/dashboard-agent-db`), the in-dashboard agent's conversation store. Everything else in the monorepo is **Prisma** (`@trigger.dev/database`). Keep them separate.
+
+Pinned versions: **`drizzle-orm` ^0.45**, **`drizzle-kit` ^0.31** (dev), **`postgres` ^3.4** (postgres.js driver). drizzle-orm and drizzle-kit are intentionally on different version lines — 0.31.x is the correct companion for 0.45.x, there is no peer dependency between them.
+
+## Critical rules
+
+1. **Drizzle is only the agent's own datastore.** The agent (and its task bundle) must have **no access to the main Prisma database or ClickHouse**. Never import the Prisma client into the agent task or into `@internal/dashboard-agent-db`. Main data is reached via the API, not Drizzle.
+2. **Foreign-key-free.** In cloud this DB is a *separate* PlanetScale database, so it can't FK into the main DB. Reference main entities (`organizationId`, `userId`, …) **by id only — never `.references()`**. Joins happen in app code; tenant scoping is enforced in the query layer.
+3. **One dedicated Postgres schema.** All tables live under `pgSchema("trigger_dashboard_agent")` so they're schema-qualified and isolated from Prisma's `public` schema (this is what makes the OSS single-database fallback safe).
+4. **Pooler-safe connections.** Connections go through a transaction-mode pooler (PlanetScale / PgBouncer-style), so postgres.js must run with **`prepare: false`** — prepared statements don't survive a connection being handed to another client between checkouts.
+5. **Node16 module resolution.** Relative imports need explicit **`.js`** extensions (`import { chats } from "./schema.js"`), even though the source is `.ts`.
+6. **Scope every user query.** All queries that touch user data go through `src/queries.ts` and are scoped by `organizationId` / `userId`, so callers can't forget the `where`. Don't write ad-hoc cross-tenant queries elsewhere.
+
+## Package layout
+
+```text
+internal-packages/dashboard-agent-db/
+  drizzle.config.ts      # drizzle-kit config (schema path, out dir, schemaFilter)
+  drizzle/               # generated migrations (committed)
+  src/
+    schema.ts            # pgSchema + table definitions
+    client.ts            # createDashboardAgentDb() — postgres.js + drizzle
+    queries.ts           # the access-pattern layer (org/user-scoped)
+    index.ts             # barrel: re-exports schema, client, queries
+```
+
+`package.json` points `main`/`types` at `./src/index.ts` (consumed as source, no build step) — same as other simple internal packages.
+
+## Schema (pg-core)
+
+Use `pgSchema(...).table(...)`, not the bare `pgTable`, so tables land in the dedicated schema. ([schemas](https://orm.drizzle.team/docs/schemas), [pg column types](https://orm.drizzle.team/docs/column-types/pg), [indexes](https://orm.drizzle.team/docs/indexes-constraints))
+
+```ts
+import { sql } from "drizzle-orm";
+import { index, jsonb, pgSchema, text, timestamp } from "drizzle-orm/pg-core";
+
+export const dashboardAgentSchema = pgSchema("trigger_dashboard_agent");
+
+export const chats = dashboardAgentSchema.table(
+  "chats",
+  {
+    id: text("id").primaryKey(),
+    organizationId: text("organization_id").notNull(), // FK-free: id only, no .references()
+    userId: text("user_id").notNull(),
+    title: text("title").notNull().default("New chat"),
+    // JSONB with a typed view; .default([]) / .default({}) emit '[]'::jsonb / '{}'::jsonb
+    messages: jsonb("messages").$type<unknown[]>().notNull().default([]),
+    metadata: jsonb("metadata").$type<Record<string, unknown>>().notNull().default({}),
+    deletedAt: timestamp("deleted_at", { withTimezone: true }), // soft delete
+    lastMessageAt: timestamp("last_message_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  // Extra config returns an ARRAY in drizzle-orm 0.36+ (not an object).
+  (t) => [
+    // Partial + ordered composite index. `.desc()` on the column, `.where(sql`...`)` for partial.
+    index("chats_org_user_last_msg_idx")
+      .on(t.organizationId, t.userId, t.lastMessageAt.desc())
+      .where(sql`${t.deletedAt} is null`),
+  ]
+);
+
+// Inferred row types for the query layer + consumers.
+export type Chat = typeof chats.$inferSelect;
+export type NewChat = typeof chats.$inferInsert;
+```
+
+Notes:
+- `timestamp(..., { withTimezone: true })` → `timestamp with time zone`. Use `.defaultNow()` for `DEFAULT now()`.
+- For a "newest first, nulls last" sort the partial index uses `.desc()`; the *query* uses raw `sql` for `NULLS LAST` (see below).
+- Don't add `.references()` — see critical rule 2.
+
+## Client (postgres.js + drizzle)
+
+([connect overview](https://orm.drizzle.team/docs/connect-overview)) One small pool, `prepare: false`. In the agent task create it once in `onBoot` (per-process); in the webapp wrap it in the `singleton(...)` helper.
+
+```ts
+import { drizzle, type PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import postgres, { type Sql } from "postgres";
+import * as schema from "./schema.js";
+
+export type DashboardAgentDb = PostgresJsDatabase<typeof schema>;
+
+export function createDashboardAgentDb(connectionString: string, opts: { max?: number } = {}) {
+  const sql: Sql = postgres(connectionString, {
+    max: opts.max ?? 5,        // small — the pooler does the real pooling
+    idle_timeout: 20,          // release conns when an agent run suspends
+    prepare: false,            // REQUIRED for transaction-mode poolers
+  });
+  return { db: drizzle(sql, { schema }), sql, close: () => sql.end() };
+}
+```
+
+## Queries (the access-pattern layer)
+
+([select](https://orm.drizzle.team/docs/select), [insert](https://orm.drizzle.team/docs/insert), [operators](https://orm.drizzle.team/docs/operators), [transactions](https://orm.drizzle.team/docs/transactions), [joins](https://orm.drizzle.team/docs/joins))
+
+```ts
+import { and, desc, eq, isNull, sql } from "drizzle-orm";
+
+// Select EXPLICIT columns for list views — never select a large blob (messages)
+// or a secret (tokens) you don't need. `NULLS LAST` needs raw sql in orderBy.
+await db
+  .select({ id: chats.id, title: chats.title, lastMessageAt: chats.lastMessageAt })
+  .from(chats)
+  .where(and(eq(chats.organizationId, orgId), eq(chats.userId, userId), isNull(chats.deletedAt)))
+  .orderBy(sql`${chats.pinnedAt} desc nulls last`, desc(chats.lastMessageAt))
+  .limit(50);
+
+// Idempotent create (avoids a duplicate-key race between two writers).
+await db.insert(chats).values({ id, organizationId: orgId, userId }).onConflictDoNothing();
+
+// Upsert.
+await db
+  .insert(chatSessions)
+  .values({ chatId, publicAccessToken })
+  .onConflictDoUpdate({ target: chatSessions.chatId, set: { publicAccessToken, updatedAt: sql`now()` } });
+
+// Owner-scope a join (this DB is FK-free, so enforce ownership in the query).
+await db
+  .select({ /* session cols */ })
+  .from(chatSessions)
+  .innerJoin(chats, eq(chats.id, chatSessions.chatId))
+  .where(and(eq(chatSessions.chatId, chatId), eq(chats.userId, userId)));
+
+// Multi-write that must be consistent on the next read → one transaction.
+await db.transaction(async (tx) => {
+  await tx.update(chats).set({ messages, updatedAt: sql`now()` }).where(eq(chats.id, chatId));
+  await tx.insert(chatSessions).values({ /* ... */ }).onConflictDoUpdate({ /* ... */ });
+});
+```
+
+Use `sql\`now()\`` for DB-side timestamps in updates.
+
+## Migrations (drizzle-kit)
+
+([kit overview](https://orm.drizzle.team/docs/kit-overview), [generate](https://orm.drizzle.team/docs/drizzle-kit-generate), [migrate](https://orm.drizzle.team/docs/drizzle-kit-migrate))
+
+`drizzle.config.ts` must set **`schemaFilter`** so drizzle-kit only ever manages our schema — never Prisma's `public` (critical in the OSS single-DB fallback):
+
+```ts
+import { defineConfig } from "drizzle-kit";
+export default defineConfig({
+  schema: "./src/schema.ts",
+  out: "./drizzle",
+  dialect: "postgresql",
+  schemaFilter: ["trigger_dashboard_agent"],
+  dbCredentials: { url: process.env.DASHBOARD_AGENT_DATABASE_URL ?? process.env.DATABASE_URL ?? "postgres://placeholder" },
+});
+```
+
+Workflow:
+
+```bash
+cd internal-packages/dashboard-agent-db
+pnpm run db:generate   # diff schema.ts → emit SQL into drizzle/. OFFLINE (no DB needed).
+#   review the generated drizzle/000N_*.sql before committing
+pnpm run db:migrate    # apply pending migrations. Needs a real DATABASE URL.
+```
+
+- `db:generate` is **offline** — it only reads `schema.ts`, so you can verify a schema change compiles to valid DDL with no database. Use it as a fast check.
+- drizzle-kit names migration files with a **random suffix** (`0000_magenta_lilandra.sql`). Don't regenerate a committed migration just to "refresh" it — that churns the filename. After the first migration is committed, schema changes produce a **new** `000N_*.sql`; commit that.
+- Generated DDL for a new schema is one `CREATE SCHEMA` + schema-qualified `CREATE TABLE`s + indexes, **no foreign keys** (by design here).
+
+## Common gotchas
+
+- **`prepare: false`** is not optional with a pooler — without it you'll get prepared-statement errors under load.
+- **Missing `.js` extension** on a relative import → TS2835 under Node16 resolution.
+- **Extra-config callback returns an array** `(t) => [ ... ]` in drizzle-orm 0.36+. The old object form `(t) => ({ ... })` is deprecated.
+- **`NULLS LAST` / `NULLS FIRST`** aren't on the `desc()` helper — use raw `sql\`col desc nulls last\`` in `orderBy`.
+- **Don't `SELECT *` into list views** — explicitly pick columns so you never ship a megabyte `messages` blob or a session token to a list query.
+- **Adding a dependency**: edit `package.json`, then `pnpm i` from the repo root (never `pnpm add`). Mind the repo's `minimumReleaseAge` (3 days) — pin with a caret range and let pnpm resolve an old-enough version.
+
+## Reference (official docs)
+
+- Schema declaration — https://orm.drizzle.team/docs/sql-schema-declaration
+- PostgreSQL column types — https://orm.drizzle.team/docs/column-types/pg
+- Schemas (`pgSchema`) — https://orm.drizzle.team/docs/schemas
+- Indexes & constraints — https://orm.drizzle.team/docs/indexes-constraints
+- Connect (postgres-js) — https://orm.drizzle.team/docs/connect-overview
+- Select / Insert / Update / Delete — https://orm.drizzle.team/docs/select · /insert · /update · /delete
+- Joins / Operators — https://orm.drizzle.team/docs/joins · /operators
+- Transactions — https://orm.drizzle.team/docs/transactions
+- drizzle-kit (generate / migrate / push) — https://orm.drizzle.team/docs/kit-overview

.claude/skills/errors-api-e2e/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: errors-api-e2e
+description: End-to-end smoke test for the public Errors HTTP API (error groups). Seeds failed runs into ClickHouse so the error materialized views populate, then drives the real endpoints against the running webapp — list (with filters + pagination), retrieve, resolve/ignore/unresolve, the `filter[error]` runs filter, user attribution via the `trigger.dev mint-token` -> JWT exchange, and the 401/403/404 negatives. Use for "smoke test the errors API", "test the errors API e2e", "prove the errors endpoints work", or to re-verify after changes.
+allowed-tools: Read, Bash
+---
+
+# Errors API — end-to-end smoke test
+
+Proves the public Errors API against the **running** webapp with real HTTP. No
+mocks. The error data plane is ClickHouse (`errors_v1` + `error_occurrences_v1`,
+both materialized-view-fed from `task_runs_v2`) plus Postgres `ErrorGroupState`
+for lifecycle status; this skill seeds straight into `task_runs_v2` and lets the
+MVs do the rest.
+
+Code under test:
+- `apps/webapp/app/routes/api.v1.errors.ts` — `GET /api/v1/errors` (list).
+- `apps/webapp/app/routes/api.v1.errors.$errorId.ts` — `GET /api/v1/errors/:errorId` (detail).
+- `apps/webapp/app/routes/api.v1.errors.$errorId.{resolve,ignore,unresolve}.ts` — state actions.
+- `apps/webapp/app/presenters/v3/ApiErrorListPresenter.server.ts` / `ApiErrorGroupPresenter.server.ts`.
+- `apps/webapp/app/presenters/v3/ApiRunListPresenter.server.ts` — the `filter[error]` addition on `GET /api/v1/runs`.
+- `apps/webapp/app/v3/services/errorGroupActions.server.ts` — resolve/ignore/unresolve (nullable `userId`).
+- Attribution: `api.v1.projects.$projectRef.$env.jwt.ts` stamps `act:{sub}` for PAT **and** UAT exchanges; `@trigger.dev/rbac` surfaces `act.sub` through bearer auth; the action handlers read `authentication.actor?.sub`.
+
+`errorId` is `error_<fingerprint>` (round-trips via `ErrorId` in `@trigger.dev/core/v3/isomorphic`).
+
+## Prerequisites
+
+- Webapp running on http://localhost:3030 (`pnpm run dev --filter webapp`). Confirm `curl -s http://localhost:3030/healthcheck`.
+- DB seeded (`pnpm run db:seed`), and a local ClickHouse reachable at `CLICKHOUSE_URL` (the `pnpm run docker` stack).
+- The CLI built + logged in to localhost:3030 (`pnpm run build --filter trigger.dev`; profile `default` points at localhost:3030). Needed only for the attribution leg.
+
+> Important wiring facts the seed relies on (verified):
+> - The MVs read the error type/message from `error.data.*`, so the seeded
+>   `error` JSON column **must** be wrapped: `{"data": {"type": ..., "message": ..., "stack": ...}}`.
+> - The MVs only fire for failed statuses: `SYSTEM_FAILURE | CRASHED | INTERRUPTED | COMPLETED_WITH_ERRORS | TIMED_OUT`, and require a non-empty `error_fingerprint`.
+> - `GET /api/v1/runs` lists run **ids** from ClickHouse but **hydrates from Postgres** `TaskRun`. So the error-list/detail/action legs work from a ClickHouse-only seed, but the `filter[error]` leg needs a **paired** Postgres `TaskRun` row whose `id` equals the ClickHouse `run_id`.
+
+Run everything from the repo root in one shell. Invoke the built CLI via a
+function (a `CLI="node …"` variable won't word-split under zsh):
+```bash
+cli() { node packages/cli-v3/dist/esm/index.js "$@"; }
+PROFILE=default
+```
+
+## Setup — resolve a dev environment + connection strings
+
+```bash
+cd apps/webapp
+CHURL=$(grep -E "^CLICKHOUSE_URL=" .env | head -1 | cut -d= -f2- | tr -d '"')
+DBURL=$(grep -E "^DATABASE_URL=" .env | head -1 | cut -d= -f2- | tr -d '"' | tr -d "'" | sed 's/?.*//')
+
+# Pick the seeded hello-world dev env (proj_rrkpdguyagvsoktglnod). Adjust the
+# WHERE if you want a different project.
+read ENV ORG PROJ REF < <(psql "$DBURL" -t -A -F' ' -c "
+  SELECT re.id, re.\"organizationId\", re.\"projectId\", p.\"externalRef\"
+  FROM \"RuntimeEnvironment\" re
+  JOIN \"Project\" p ON p.id = re.\"projectId\"
+  WHERE re.slug='dev' AND p.\"externalRef\"='proj_rrkpdguyagvsoktglnod' LIMIT 1;")
+APIKEY=$(psql "$DBURL" -t -A -c "SELECT \"apiKey\" FROM \"RuntimeEnvironment\" WHERE id='$ENV';")
+cd ..
+H="Authorization: Bearer $APIKEY"
+B="http://localhost:3030"
+```
+
+## Steps
+
+### 1. Seed two error groups (ClickHouse, MV-fed)
+
+```bash
+RUN=$(node -e 'console.log(Date.now().toString(36))')
+TASK="errors-api-e2e-$RUN"; FP_A="fpA${RUN}"; FP_B="fpB${RUN}"
+ERRID_A="error_$FP_A"; ERRID_B="error_$FP_B"
+NOW_CH=$(node -e 'console.log(new Date().toISOString().replace("T"," ").replace("Z","").slice(0,23))')
+NOW_MS=$(node -e 'console.log(Date.now())')
+Q=$(python3 -c "import urllib.parse;print(urllib.parse.quote('INSERT INTO trigger_dev.task_runs_v2 FORMAT JSONEachRow'))")
+
+mkrow() { # status fingerprint errorType message runId
+  echo "{\"environment_id\":\"$ENV\",\"organization_id\":\"$ORG\",\"project_id\":\"$PROJ\",\"run_id\":\"$5\",\"friendly_id\":\"run_$5\",\"status\":\"$1\",\"environment_type\":\"DEVELOPMENT\",\"engine\":\"V2\",\"task_identifier\":\"$TASK\",\"created_at\":\"$NOW_CH\",\"updated_at\":\"$NOW_CH\",\"error\":{\"data\":{\"type\":\"$3\",\"message\":\"$4\",\"stack\":\"at x (a.ts:1:1)\"}},\"error_fingerprint\":\"$2\",\"task_version\":\"20240101.1\",\"_version\":\"$NOW_MS\",\"_is_deleted\":0}"
+}
+ROWS="$(mkrow COMPLETED_WITH_ERRORS $FP_A AlphaBoom 'alpha boom happened' r_a1_$RUN)
+$(mkrow COMPLETED_WITH_ERRORS $FP_A AlphaBoom 'alpha boom happened' r_a2_$RUN)
+$(mkrow CRASHED $FP_B BetaCrash 'beta crash happened' r_b1_$RUN)"
+printf '%s' "$ROWS" | curl -s "$CHURL/?query=$Q" --data-binary @-
+
+# Poll until both fingerprints appear in errors_v1 (the MV is near-instant locally).
+for i in $(seq 1 10); do
+  N=$(curl -s "$CHURL" --data-binary "SELECT count() FROM (SELECT 1 FROM trigger_dev.errors_v1 WHERE environment_id='$ENV' AND error_fingerprint IN ('$FP_A','$FP_B') GROUP BY error_fingerprint)")
+  [ "$N" = "2" ] && break; sleep 1
+done
+echo "seeded fingerprints in errors_v1: $N (want 2)"
+```
+PASS: `N = 2`. Alpha has 2 occurrences, beta 1.
+
+### 2. List + filters + pagination
+
+```bash
+curl -s "$B/api/v1/errors?filter%5BtaskIdentifier%5D=$TASK&filter%5Bperiod%5D=1d" -H "$H" \
+  | python3 -c "import sys,json;d=json.load(sys.stdin);print('count',len(d['data']),[(e['id'],e['status'],e['count']) for e in d['data']])"
+```
+PASS: 2 groups, both `status=unresolved`, alpha `count=2`, beta `count=1`, ids `error_<fp>`.
+
+Assert each filter narrows correctly (each should return the noted shape):
+```bash
+curl -s "$B/api/v1/errors?filter%5BtaskIdentifier%5D=$TASK&filter%5Bstatus%5D=unresolved&filter%5Bperiod%5D=1d" -H "$H" | python3 -c "import sys,json;print('unresolved:',len(json.load(sys.stdin)['data']))"   # 2
+curl -s "$B/api/v1/errors?filter%5BtaskIdentifier%5D=$TASK&filter%5Bsearch%5D=AlphaBoom&filter%5Bperiod%5D=1d" -H "$H" | python3 -c "import sys,json;print('search:',[e['errorType'] for e in json.load(sys.stdin)['data']])"   # ['AlphaBoom']
+curl -s "$B/api/v1/errors?filter%5BtaskIdentifier%5D=$TASK&filter%5Bperiod%5D=1d&page%5Bsize%5D=1" -H "$H" | python3 -c "import sys,json;d=json.load(sys.stdin);print('page size 1:',len(d['data']),'next?',bool(d['pagination'].get('next')))"   # 1 / True
+```
+PASS: `unresolved: 2`, `search: ['AlphaBoom']`, `page size 1: 1 / next? True`.
+
+### 3. Retrieve detail
+
+```bash
+curl -s "$B/api/v1/errors/$ERRID_A" -H "$H" \
+  | python3 -c "import sys,json;d=json.load(sys.stdin);print(d['id'],d['errorType'],d['status'],d['count'],d['affectedVersions'],d['resolvedBy'])"
+```
+PASS: `error_<fpA> AlphaBoom unresolved 2 ['20240101.1'] None`.
+
+### 4. Resolve / ignore / unresolve (env API key — `resolvedBy` null)
+
+```bash
+st(){ python3 -c "import sys,json;d=json.load(sys.stdin);print('status',d['status'],'| resolvedInVersion',d['resolvedInVersion'],'| resolvedBy',d['resolvedBy'],'| ignoredUntil',bool(d['ignoredUntil']),'| reason',d['ignoredReason'])"; }
+
+curl -s -X POST "$B/api/v1/errors/$ERRID_A/resolve" -H "$H" -H 'Content-Type: application/json' -d '{"resolvedInVersion":"20240101.1"}' >/dev/null
+curl -s "$B/api/v1/errors/$ERRID_A" -H "$H" | st   # status resolved | resolvedInVersion 20240101.1 | resolvedBy None
+
+curl -s -X POST "$B/api/v1/errors/$ERRID_B/ignore" -H "$H" -H 'Content-Type: application/json' -d '{"duration":3600000,"reason":"known flake"}' >/dev/null
+curl -s "$B/api/v1/errors/$ERRID_B" -H "$H" | st   # status ignored | ignoredUntil True | reason known flake
+
+curl -s -X POST "$B/api/v1/errors/$ERRID_A/unresolve" -H "$H" >/dev/null
+curl -s "$B/api/v1/errors/$ERRID_A" -H "$H" | st   # status unresolved
+```
+PASS: each transition reflected; `filter[status]=ignored` returns only beta:
+```bash
+curl -s "$B/api/v1/errors?filter%5BtaskIdentifier%5D=$TASK&filter%5Bstatus%5D=ignored&filter%5Bperiod%5D=1d" -H "$H" | python3 -c "import sys,json;print([e['id'] for e in json.load(sys.stdin)['data']])"   # [error_<fpB>]
+```
+
+### 5. `filter[error]` on the runs list (paired PG + CH seed)
+
+The runs list hydrates from Postgres, so seed a matching `TaskRun` row + a CH row
+that share `run_id`/`id` and carry a fingerprint:
+```bash
+RID="re2e${RUN}"; FRID="run_${RID}"; FP_R="fpR${RUN}"
+psql "$DBURL" -v ON_ERROR_STOP=1 -c "
+  INSERT INTO \"TaskRun\" (id, \"friendlyId\", \"taskIdentifier\", payload, \"traceId\", \"spanId\", \"runtimeEnvironmentId\", \"projectId\", queue, status, \"createdAt\", \"updatedAt\")
+  VALUES ('$RID','$FRID','$TASK','{}','trace_$RID','span_$RID','$ENV','$PROJ','task/$TASK','COMPLETED_WITH_ERRORS', now(), now())
+  ON CONFLICT (id) DO NOTHING;" >/dev/null
+ROW="{\"environment_id\":\"$ENV\",\"organization_id\":\"$ORG\",\"project_id\":\"$PROJ\",\"run_id\":\"$RID\",\"friendly_id\":\"$FRID\",\"status\":\"COMPLETED_WITH_ERRORS\",\"environment_type\":\"DEVELOPMENT\",\"engine\":\"V2\",\"task_identifier\":\"$TASK\",\"created_at\":\"$NOW_CH\",\"updated_at\":\"$NOW_CH\",\"error\":{\"data\":{\"type\":\"RunsFilterErr\",\"message\":\"for runs filter\",\"stack\":\"at x\"}},\"error_fingerprint\":\"$FP_R\",\"task_version\":\"20240101.1\",\"_version\":\"$NOW_MS\",\"_is_deleted\":0}"
+printf '%s' "$ROW" | curl -s "$CHURL/?query=$Q" --data-binary @-
+sleep 1
+curl -s "$B/api/v1/runs?filter%5Berror%5D=error_$FP_R" -H "$H" | python3 -c "import sys,json;d=json.load(sys.stdin);print('runs:',[r['id'] for r in d['data']])"
+```
+PASS: one run, `run_<RID>` (status maps to `FAILED`). Proves `filter[error]` -> fingerprint -> CH -> PG hydration.
+
+### 6. Attribution — `mint-token` -> JWT exchange records the acting user
+
+```bash
+TOKEN=$(cli mint-token --profile $PROFILE --client errors-api-e2e 2>/dev/null)            # UAT
+ENVJWT=$(curl -sS -X POST "$B/api/v1/projects/$REF/dev/jwt" -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' -d '{"claims":{"scopes":["read:errors","write:errors"]}}' \
+  | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")
+# Decoded env JWT carries act.sub = the user id.
+node -e 'const p=JSON.parse(Buffer.from(process.argv[1].split(".")[1],"base64url").toString());console.log("act:",JSON.stringify(p.act))' "$ENVJWT"
+
+curl -s -X POST "$B/api/v1/errors/$ERRID_A/resolve" -H "Authorization: Bearer $ENVJWT" \
+  -H 'Content-Type: application/json' -d '{"resolvedInVersion":"20240101.2"}' >/dev/null
+curl -s "$B/api/v1/errors/$ERRID_A" -H "$H" | python3 -c "import sys,json;d=json.load(sys.stdin);print('resolvedBy:',d['resolvedBy'])"
+```
+PASS: `act.sub` is the user id (matches `cli whoami`), and `detail.resolvedBy` equals that user id (not null). A plain env key leaves it null (step 4). A **PAT** exchanged the same way also stamps `act` — repeat with the stored PAT to confirm `ignoredByUserId` attribution.
+
+### 7. Negatives
+
+```bash
+curl -s -o /dev/null -w 'unknown id: %{http_code} (404)\n'        "$B/api/v1/errors/error_doesnotexist0000" -H "$H"
+curl -s -o /dev/null -w 'no auth list: %{http_code} (401)\n'      "$B/api/v1/errors"
+curl -s -o /dev/null -w 'no auth resolve: %{http_code} (401)\n'   -X POST "$B/api/v1/errors/$ERRID_B/resolve" -H 'Content-Type: application/json' -d '{}'
+
+# read-only JWT must be denied on write, allowed on read
+READJWT=$(curl -sS -X POST "$B/api/v1/projects/$REF/dev/jwt" -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' -d '{"claims":{"scopes":["read:errors"]}}' | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")
+curl -s -o /dev/null -w 'read JWT write: %{http_code} (403)\n'    -X POST "$B/api/v1/errors/$ERRID_B/resolve" -H "Authorization: Bearer $READJWT" -H 'Content-Type: application/json' -d '{}'
+curl -s -o /dev/null -w 'read JWT read: %{http_code} (200)\n'     "$B/api/v1/errors?filter%5BtaskIdentifier%5D=$TASK" -H "Authorization: Bearer $READJWT"
+```
+PASS: `404`, `401`, `401`, `403`, `200` respectively.
+
+## Result
+
+Report PASS only if: step 1 lands 2 groups in `errors_v1`; step 2's filters and
+pagination narrow correctly; step 3 returns the detail; step 4's resolve/ignore/
+unresolve flip status (and `filter[status]` follows); step 5's `filter[error]`
+returns the paired run; step 6 records `resolvedBy` = the acting user via the
+JWT exchange (null with a plain env key); and step 7 returns 404/401/401/403/200.
+A red leg is a bug or a missing prereq — report the exact status + body and file
+a Linear issue, don't tune around it.
+
+## Notes / gotchas
+
+- Run files use a unique `$RUN` suffix per invocation, so reruns don't collide and seeded rows stay isolated by their unique task identifier. They are local-dev test rows (90-day ClickHouse TTL); no cleanup required.
+- After **adding** the route files, the classic Remix dev compiler may not register them until a dev-server restart (a stale manifest returns Remix's HTML 404 on the new paths). If `POST …/resolve` returns a 404 HTML page rather than 401/200, restart `pnpm run dev --filter webapp`.
+- The rbac `act` extraction lives in `@trigger.dev/rbac` (a built dep). After editing it, `pnpm run build --filter @trigger.dev/rbac` and restart the webapp so the attribution leg (step 6) reflects the change.

.claude/skills/span-timeline-events/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: span-timeline-events
+description: Use when adding, modifying, or debugging OTel span timeline events in the trace view. Covers event structure, ClickHouse storage constraints, rendering in SpanTimeline component, admin visibility, and the step-by-step process for adding new events.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Span Timeline Events
+
+The trace view's right panel shows a timeline of events for the selected span. These are OTel span events rendered by `app/utils/timelineSpanEvents.ts` and the `SpanTimeline` component.
+
+## How They Work
+
+1. **Span events** in OTel are attached to a parent span. In ClickHouse, they're stored as separate rows with `kind: "SPAN_EVENT"` sharing the parent span's `span_id`. The `#mergeRecordsIntoSpanDetail` method reassembles them into the span's `events` array at query time.
+2. The timeline only renders events whose `name` starts with `trigger.dev/` - all others are silently filtered out.
+3. The **display name** comes from `properties.event` (not the span event name), mapped through `getFriendlyNameForEvent()`.
+4. Events are shown on the **span they belong to** - events on one span don't appear in another span's timeline.
+
+## ClickHouse Storage Constraint
+
+When events are written to ClickHouse, `spanEventsToTaskEventV1Input()` filters out events whose `start_time` is not greater than the parent span's `startTime`. Events at or before the span start are silently dropped. This means span events must have timestamps strictly after the span's own `startTimeUnixNano`.
+
+## Timeline Rendering (SpanTimeline component)
+
+The `SpanTimeline` component in `app/components/run/RunTimeline.tsx` renders:
+
+1. **Events** (thin 1px line with hollow dots) - all events from `createTimelineSpanEventsFromSpanEvents()`
+2. **"Started"** marker (thick cap) - at the span's `startTime`
+3. **Duration bar** (thick 7px line) - from "Started" to "Finished"
+4. **"Finished"** marker (thick cap) - at `startTime + duration`
+
+The thin line before "Started" only appears when there are events with timestamps between the span start and the first child span. For the Attempt span this works well (Dequeued -> Pod scheduled -> Launched -> etc. all happen before execution starts). Events all get `lineVariant: "light"` (thin) while the execution bar gets `variant: "normal"` (thick).
+
+## Trace View Sort Order
+
+Sibling spans (same parent) are sorted by `start_time ASC` from the ClickHouse query. The `createTreeFromFlatItems` function preserves this order. Event timestamps don't affect sort order - only the span's own `start_time`.
+
+## Event Structure
+
+```typescript
+// OTel span event format
+{
+  name: "trigger.dev/run",        // Must start with "trigger.dev/" to render
+  timeUnixNano: "1711200000000000000",
+  attributes: [
+    { key: "event", value: { stringValue: "dequeue" } },  // The actual event type
+    { key: "duration", value: { intValue: 150 } },         // Optional: duration in ms
+  ]
+}
+```
+
+## Admin-Only Events
+
+`getAdminOnlyForEvent()` controls visibility. Events default to **admin-only** (`true`).
+
+| Event | Admin-only | Friendly name |
+|-------|-----------|---------------|
+| `dequeue` | No | Dequeued |
+| `fork` | No | Launched |
+| `import` | No (if no fork event) | Importing task file |
+| `create_attempt` | Yes | Attempt created |
+| `lazy_payload` | Yes | Lazy attempt initialized |
+| `pod_scheduled` | Yes | Pod scheduled |
+| (default) | Yes | (raw event name) |
+
+## Adding New Timeline Events
+
+1. Add OTLP span event with `name: "trigger.dev/<scope>"` and `properties.event: "<type>"`
+2. Event timestamp must be strictly after the parent span's `startTimeUnixNano` (ClickHouse drops earlier events)
+3. Add friendly name in `getFriendlyNameForEvent()` in `app/utils/timelineSpanEvents.ts`
+4. Set admin visibility in `getAdminOnlyForEvent()`
+5. Optionally add help text in `getHelpTextForEvent()`
+
+## Key Files
+
+- `app/utils/timelineSpanEvents.ts` - filtering, naming, admin logic
+- `app/components/run/RunTimeline.tsx` - `SpanTimeline` component (thin line + thick bar rendering)
+- `app/presenters/v3/SpanPresenter.server.ts` - loads span data including events
+- `app/v3/eventRepository/clickhouseEventRepository.server.ts` - `spanEventsToTaskEventV1Input()` (storage filter), `#mergeRecordsIntoSpanDetail` (reassembly)

.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
+```

.configs/tsconfig.base.json

@@ -0,0 +1,36 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable", "DOM.AsyncIterable"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "moduleDetection": "force",
+    "verbatimModuleSyntax": false,
+    "jsx": "react",
+
+    "strict": true,
+    "alwaysStrict": true,
+    "strictPropertyInitialization": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+
+    "noFallthroughCasesInSwitch": true,
+    "resolveJsonModule": true,
+
+    "removeComments": false,
+    "esModuleInterop": true,
+    "emitDecoratorMetadata": false,
+    "experimentalDecorators": false,
+    "downlevelIteration": true,
+    "isolatedModules": true,
+    "noUncheckedIndexedAccess": true,
+
+    "pretty": true,
+    "customConditions": ["@triggerdotdev/source"]
+  }
+}

.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

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "linear": {
+      "url": "https://mcp.linear.app/mcp"
+    }
+  }
+}

.cursor/rules/executing-commands.mdc

@@ -0,0 +1,24 @@
+---
+description: how to run commands in the monorepo
+globs: 
+alwaysApply: true
+---
+Almost all commands in the monorepo should be executed when `pnpm run ...` from the root of the monorepo. For example, running tests for the `@internal/run-engine` internal package:
+
+```
+pnpm run dev --filter webapp
+```
+
+But often, when running tests, it's better to `cd` into the directory and then run tests:
+
+```
+cd apps/webapp
+pnpm run test --run
+```
+
+This way you can run for a single file easily:
+
+```
+cd internal-packages/run-engine
+pnpm run test ./src/engine/tests/ttl.test.ts --run
+```

.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/repo.mdc

@@ -0,0 +1,6 @@
+---
+description: understanding the structure of the monorepo
+globs: 
+alwaysApply: true
+---
+We've documented the structure of our monorepo here: [repo.md](mdc:ai/references/repo.md)

.cursor/rules/webapp.mdc

@@ -0,0 +1,40 @@
+---
+description: Making updates to the main trigger.dev remix webapp
+globs: apps/webapp/**/*.tsx,apps/webapp/**/*.ts
+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.17.4 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 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.
+
+## Environment variables and testing
+
+In the webapp, all environment variables are accessed through the `env` export of [env.server.ts](mdc:apps/webapp/app/env.server.ts), instead of directly accessing `process.env`.
+
+Ideally, the `env.server.ts` file would never be imported into a test file, either directly or indirectly. Tests should only imported classes and functions from a file matching `app/**/*.ts` of the webapp, and that file should not use environment variables, everything should be passed through as options instead. This "service/configuration" separation is important, and can be seen in a few places in the code for examples:
+
+- [realtimeClient.server.ts](mdc:apps/webapp/app/services/realtimeClient.server.ts) is the testable service, and [realtimeClientGlobal.server.ts](mdc:apps/webapp/app/services/realtimeClientGlobal.server.ts) is the configuration
+
+Also for writing tests in the webapp, checkout our [tests.md](mdc:ai/references/tests.md) guide
+
+## Legacy run engine vs Run Engine 2.0
+
+We originally the Trigger.dev "Run Engine" not as a single system, but just spread out all over the codebase, with no real separate or encapsulation. And we didn't even call it a "Run Engine". With Run Engine 2.0, we've completely rewritten big parts of the way the system works, and moved it over to an internal package called `@internal/run-engine`. So we've retroactively named the previous run engine "Legacy run engine". We're focused almost exclusively now on moving to Run Engine 2.0 and will be deprecating and removing the legacy run engine code eventually.
+
+## Where to look for code
+
+- The trigger API endpoint is [api.v1.tasks.$taskId.trigger.ts](mdc:apps/webapp/app/routes/api.v1.tasks.$taskId.trigger.ts)
+- 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
+- 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
+
+- 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-tests.mdc

@@ -0,0 +1,6 @@
+---
+description: How to write tests in the monorepo
+globs: 
+alwaysApply: true
+---
+Follow our [tests.md](mdc:ai/references/tests.md) guide for how to write tests in the monorepo.

.cursorignore

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

.dockerignore

@@ -1,43 +1,25 @@
-\*.log
-.git
-.github
+**/*.log
+**/*.pem
+**/*.tsbuildinfo
 
-# editor
+**/.cache
+**/.env
+**/.next
+**/.output
+**/.trigger
+**/.tshy
+**/.tshy-build
+**/.turbo
+**/.vercel
+**/.wrangler
 
-.idea
-.vscode
+**/dist
+**/node_modules
 
-# dependencies
+**/generated/prisma
 
-node_modules
-.pnp
-.pnp.js
-
-# testing
-
-coverage
-
-# next.js
-
-.next/
-build
-
-# packages
-
-build
-dist
-packages/\*\*/dist
-
-# misc
-
-.DS_Store
-\*.pem
-
-.turbo
-.vercel
-.cache
-.output
-apps/\*\*/public/build
+apps/webapp/build
+apps/webapp/public/build
 
 cypress/screenshots
 cypress/videos
@@ -46,8 +28,21 @@ apps/**/styles/tailwind.css
 packages/**/styles/tailwind.css
 
 .changeset
-references
+.DS_Store
+.git
+.github
+.idea
+.pnp
+.pnp.js
+.vscode
+
+coverage
+build
+docs
 examples
+out
+references
+
 CHANGESETS.md
 CONTRIBUTING.md
 README.md

.env.example

@@ -7,34 +7,163 @@ DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres?schema=publi
 # This sets the URL used for direct connections to the database and should only be needed in limited circumstances
 # See: https://www.prisma.io/docs/reference/api-reference/prisma-schema-reference#fields:~:text=the%20shadow%20database.-,directUrl,-No
 DIRECT_URL=${DATABASE_URL}
+# Dedicated run-ops database (@internal/run-ops-database). Only needed to run prisma commands
+# against it or to enable the run-ops split; start it with `docker compose --profile runops up`.
+RUN_OPS_DATABASE_URL=postgresql://postgres:postgres@localhost:5434/postgres?schema=public
 REMIX_APP_PORT=3030
+# Dev-only: stream the webapp's logs over a local telnet/TCP socket (nc localhost 6767). Uncomment to enable.
+# WEBAPP_TELNET_LOGS_PORT=6767
 APP_ENV=development
 APP_ORIGIN=http://localhost:3030
+ELECTRIC_ORIGIN=http://localhost:3060
 NODE_ENV=development
 
+# Clickhouse
+CLICKHOUSE_URL=http://default:password@localhost:8123
+RUN_REPLICATION_CLICKHOUSE_URL=http://default:password@localhost:8123
+RUN_REPLICATION_ENABLED=1
+# Store task run spans/traces in ClickHouse so the dashboard trace view is
+# populated in local dev. The local stack is ClickHouse-backed (see above), so
+# leaving this unset falls back to the "postgres" store and dev run traces show
+# up empty even though the run itself appears.
+EVENT_REPOSITORY_DEFAULT_STORE=clickhouse_v2
+
+# 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"
+REDIS_PORT="6379"
+REDIS_TLS_DISABLED="true"
+
+DEV_OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:3030/otel"
+DEV_OTEL_BATCH_PROCESSING_ENABLED="0"
+
+# Realtime streams v2 (Sessions, chat.agent, large stream backfills) backed
+# by S2 (https://s2.dev). The `s2` service in docker/docker-compose.yml runs
+# the open-source s2-lite binary and pre-creates a basin named `trigger-local`
+# (see docker/config/s2-spec.json). Comment these out to fall back to v1
+# (Redis-only) streams; Sessions and chat.agent then become unavailable.
+REALTIME_STREAMS_S2_BASIN=trigger-local
+REALTIME_STREAMS_S2_ACCESS_TOKEN=ignored
+REALTIME_STREAMS_S2_ENDPOINT=http://localhost:4566/v1
+REALTIME_STREAMS_S2_SKIP_ACCESS_TOKENS=true
+REALTIME_STREAMS_DEFAULT_VERSION=v2
+
+# Running multiple instances side by side (worktrees, branch experiments)
+#
+# Every host port in docker/docker-compose.yml is `${VAR:-default}` and the
+# project name comes from `COMPOSE_PROJECT_NAME`. To stand up a second stack
+# alongside the default one, uncomment the block below in this clone's `.env`
+# (pick any offset that doesn't clash with anything else running), then update
+# the URL/PORT vars further up to match. Default values are commented for
+# reference.
+#
+# --- core (pnpm run docker) ---
+# COMPOSE_PROJECT_NAME=triggerdotdev-docker-alt
+# CONTAINER_PREFIX=alt-
+# POSTGRES_HOST_PORT=15432           # default 5432
+# REDIS_HOST_PORT=16379              # default 6379
+# ELECTRIC_HOST_PORT=13060           # default 3060
+# MINIO_API_HOST_PORT=19005          # default 9005
+# MINIO_CONSOLE_HOST_PORT=19006      # default 9006
+# CLICKHOUSE_HTTP_HOST_PORT=18123    # default 8123
+# CLICKHOUSE_TCP_HOST_PORT=19000     # default 9000
+# S2_HOST_PORT=14566                 # default 4566
+# REMIX_APP_PORT=13030               # default 3030
+# --- extras (only needed if you also run `pnpm run docker:full`) ---
+# ELECTRIC_SHARD_1_HOST_PORT=13061   # default 3061
+# CH_UI_HOST_PORT=15521              # default 5521
+# TOXIPROXY_PROXY_HOST_PORT=40303    # default 30303
+# TOXIPROXY_API_HOST_PORT=18474      # default 8474
+# NGINX_H2_HOST_PORT=18443           # default 8443
+# OTEL_GRPC_HOST_PORT=14317          # default 4317
+# OTEL_HTTP_HOST_PORT=14318          # default 4318
+# OTEL_PROMETHEUS_HOST_PORT=18889    # default 8889
+# PROMETHEUS_HOST_PORT=19090         # default 9090
+# GRAFANA_HOST_PORT=13001            # default 3001
+# (and update DATABASE_URL / CLICKHOUSE_URL / REDIS_PORT / APP_ORIGIN /
+#  LOGIN_ORIGIN / ELECTRIC_ORIGIN / REALTIME_STREAMS_S2_ENDPOINT to match)
+
+# 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)$"
 # 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=
 
-# Resend is an email service used for signing in to Trigger.dev via a Magic Link.
-# Emails will print to the console if you leave these commented out
+# Configure an email transport to allow users to sign in to Trigger.dev via a Magic Link.
+# If none are configured, emails will print to the console instead.
+# Uncomment one of the following blocks to allow delivery of
+
+# Resend
 ### Visit https://resend.com, create an account and get your API key. Then insert it below along with your From and Reply To email addresses. Visit https://resend.com/docs for more information.
-# RESEND_API_KEY=<api_key>
+# EMAIL_TRANSPORT=resend
+# FROM_EMAIL=
+# REPLY_TO_EMAIL=
+# RESEND_API_KEY=
+
+# Generic SMTP
+### Enter the configuration provided by your mail provider. Visit https://nodemailer.com/smtp/ for more information
+### SMTP_SECURE = false will use STARTTLS when connecting to a server that supports it (usually port 587)
+# EMAIL_TRANSPORT=smtp
+# FROM_EMAIL=
+# REPLY_TO_EMAIL=
+# SMTP_HOST=
+# SMTP_PORT=587
+# SMTP_SECURE=false
+# SMTP_USER=
+# SMTP_PASSWORD=
+
+# AWS Simple Email Service
+### Authentication is configured using the default Node.JS credentials provider chain (https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromnodeproviderchain)
+# EMAIL_TRANSPORT=aws-ses
 # FROM_EMAIL=
 # REPLY_TO_EMAIL=
 
 # 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= 
+
+# DEPOT_ORG_ID=<Depot org id>
+# DEPOT_TOKEN=<Depot org token>
+# DEV_OTEL_EXPORTER_OTLP_ENDPOINT="http://0.0.0.0:4318"
+# These are needed for the object store (for handling large payloads/outputs)
+#
+# Default provider
+# OBJECT_STORE_BASE_URL=http://localhost:9005
+# OBJECT_STORE_BUCKET=packets
+# OBJECT_STORE_ACCESS_KEY_ID=minioadmin
+# OBJECT_STORE_SECRET_ACCESS_KEY=minioadmin
+# OBJECT_STORE_REGION=us-east-1
+# OBJECT_STORE_SERVICE=s3
+#
+# OBJECT_STORE_DEFAULT_PROTOCOL=s3  # Only specify this if you're going to migrate object storage and set protocol values below
+# Named providers (protocol-prefixed data) - optional for multi-provider support
+# OBJECT_STORE_S3_BASE_URL=https://s3.amazonaws.com
+# OBJECT_STORE_S3_ACCESS_KEY_ID=
+# OBJECT_STORE_S3_SECRET_ACCESS_KEY=
+# OBJECT_STORE_S3_REGION=us-east-1
+# OBJECT_STORE_S3_SERVICE=s3
+#
+# OBJECT_STORE_R2_BASE_URL=https://{bucket}.{accountId}.r2.cloudflarestorage.com
+# OBJECT_STORE_R2_ACCESS_KEY_ID=
+# OBJECT_STORE_R2_SECRET_ACCESS_KEY=
+# OBJECT_STORE_R2_REGION=auto
+# OBJECT_STORE_R2_SERVICE=s3
+# CHECKPOINT_THRESHOLD_IN_MS=10000
+
+# These control the server-side internal telemetry
+# INTERNAL_OTEL_TRACE_EXPORTER_URL=<URL to send traces to>
+# INTERNAL_OTEL_TRACE_LOGGING_ENABLED=1
+# INTERNAL_OTEL_TRACE_INSTRUMENT_PRISMA_ENABLED=0
+
+# Enable local observability stack (requires `pnpm run docker:full` to bring up otel-collector + prometheus + grafana)
+# 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

.eslintignore

@@ -1,4 +0,0 @@
-*/**.js
-*/**.d.ts
-packages/*/dist
-packages/*/lib

.eslintrc.js

@@ -1,14 +0,0 @@
-module.exports = {
-  root: true,
-  // This tells ESLint to load the config from the package `eslint-config-custom`
-  extends: ["custom"],
-  settings: {
-    next: {
-      rootDir: ["apps/*/"],
-    },
-  },
-  parserOptions: {
-    sourceType: "module",
-    ecmaVersion: 2020,
-  },
-};

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: [triggerdotdev]

.github/ISSUE_TEMPLATE/instrumentation_request.yml

@@ -0,0 +1,21 @@
+name: OpenTelemetry Auto-Instrumentation Request
+description: Suggest an SDK that you'd like to be auto-instrumented in the Run log view
+title: "auto-instrumentation: "
+labels: ["🌟 enhancement"]
+body:
+  - type: textarea
+    attributes:
+      label: What API or SDK would you to have automatic spans for?
+      description: A clear description of which API or SDK you'd like, and links to it.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Is there an existing OpenTelemetry auto-instrumentation package?
+      description: You can search for existing ones – https://opentelemetry.io/ecosystem/registry/?component=instrumentation&language=js
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Additional information
+      description: Add any other information related to the feature here. If your feature request is related to any issues or discussions, link them here.

.github/ISSUE_TEMPLATE/vouch-request.yml

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

.github/VOUCHED.td

@@ -0,0 +1,27 @@
+# Vouched contributors for Trigger.dev
+# See: https://github.com/mitchellh/vouch
+#
+# Org members
+0ski
+D-K-P
+ericallam
+matt-aitken
+mpcgrid
+myftija
+nicktrn
+samejr
+isshaddad
+# Bots
+devin-ai-integration[bot]
+dependabot[bot]
+# Outside contributors
+gautamsi
+capaj
+chengzp
+bharathkumar39293
+bhekanik
+jrossi
+ThullyoCunha
+ConProgramming
+saasjesus
+brentshulman-silkline

.github/actionlint.yaml

@@ -0,0 +1,5 @@
+self-hosted-runner:
+  labels:
+    - warp-ubuntu-*
+    - warp-macos-*
+    - warp-windows-*

.github/actions/get-image-tag/action.yml

@@ -0,0 +1,91 @@
+name: "#️⃣ Get image tag (action)"
+
+description: This action gets the image tag from the commit ref or input (if provided)
+
+outputs:
+  tag:
+    description: The image tag
+    value: ${{ steps.get_tag.outputs.tag }}
+  is_semver:
+    description: Whether the tag is a semantic version
+    value: ${{ steps.check_semver.outputs.is_semver }}
+
+inputs:
+  tag:
+    description: The image tag. If this is set it will return the tag as is.
+    required: false
+    default: ""
+
+runs:
+  using: "composite"
+  steps:
+    - name: "#️⃣ Get image tag (step)"
+      id: get_tag
+      shell: bash
+      run: |
+        if [[ -n "${INPUTS_TAG}" ]]; then
+          tag="${INPUTS_TAG}"
+        elif [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+          if [[ "${GITHUB_REF_NAME}" == infra-*-* ]]; then
+            env=$(echo ${GITHUB_REF_NAME} | cut -d- -f2)
+            sha=$(echo "${GITHUB_SHA}" | head -c7)
+            ts=$(date +%s)
+            tag=${env}-${sha}-${ts}
+          elif [[ "${GITHUB_REF_NAME}" == re2-*-* ]]; then
+            env=$(echo ${GITHUB_REF_NAME} | cut -d- -f2)
+            sha=$(echo "${GITHUB_SHA}" | head -c7)
+            ts=$(date +%s)
+            tag=${env}-${sha}-${ts}
+          elif [[ "${GITHUB_REF_NAME}" == v.docker.* ]]; then
+            version="${GITHUB_REF_NAME#v.docker.}"
+            tag="v${version}"
+          elif [[ "${GITHUB_REF_NAME}" == build-* ]]; then
+            tag="${GITHUB_REF_NAME#build-}"
+          else
+            echo "Invalid git tag: ${GITHUB_REF_NAME}"
+            exit 1
+          fi
+        elif [[ "${GITHUB_REF_NAME}" == "main" ]]; then
+          tag="main"
+        else
+          echo "Invalid git ref: ${GITHUB_REF}"
+          exit 1
+        fi
+        echo "tag=${tag}" >> "$GITHUB_OUTPUT"
+      env:
+        INPUTS_TAG: ${{ inputs.tag }}
+
+    - name: 🔍 Check for validity
+      id: check_validity
+      shell: bash
+      env:
+        tag: ${{ steps.get_tag.outputs.tag }}
+      run: |
+        if [[ "${tag}" =~ ^[a-z0-9]+([._-][a-z0-9]+)*$ ]]; then
+          echo "Tag is valid: ${tag}"
+        else
+          echo "Tag is not valid: ${tag}"
+          exit 1
+        fi
+
+    - name: 🆚 Check for semver
+      id: check_semver
+      shell: bash
+      env:
+        tag: ${{ steps.get_tag.outputs.tag }}
+      # Will match most semver formats except build metadata, i.e. v1.2.3+build.1
+      # Valid matches:
+      # v1.2.3
+      # v1.2.3-alpha
+      # v1.2.3-alpha.1
+      # v1.2.3-rc.1
+      # v1.2.3-beta-1
+      run: |
+        if [[ "${tag}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$ ]]; then
+          echo "Tag is a semantic version: ${tag}"
+          is_semver=true
+        else
+          echo "Tag is not a semantic version: ${tag}"
+          is_semver=false
+        fi
+        echo "is_semver=${is_semver}" >> "$GITHUB_OUTPUT"

.github/copilot-instructions.md

@@ -0,0 +1 @@
+This is the repo for Trigger.dev, a background jobs platform written in TypeScript. Our webapp at apps/webapp is a Remix 2.1 app that uses Node.js v20. Our SDK is an isomorphic TypeScript SDK at packages/trigger-sdk. Always prefer using isomorphic code like fetch, ReadableStream, etc. instead of Node.js specific code. Our tests are all vitest. We use prisma in internal-packages/database for our database interactions using PostgreSQL. For TypeScript, we usually use types over interfaces. We use zod a lot in packages/core and in the webapp. Avoid enums. Use strict mode. No default exports, use function declarations.

.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      github-actions:
+        patterns:
+          - "*"

.github/labeler.yml

@@ -9,4 +9,4 @@
   - any: ["**/*.md"]
 
 "📌 area: ci":
-  - any: [".github/**/*"]
+  - any: [".github/**/*"]

.github/test/README.md

@@ -0,0 +1,70 @@
+# GitHub Action Tests
+
+This directory contains necessary files to allow local testing of GitHub Actions workflows, composite actions, etc. You will need to install [act](https://github.com/nektos/act) to perform tests.
+
+## Workflow tests
+
+Trigger specific workflow files by specifying their full path:
+
+```
+act -W .github/workflow/release.yml
+```
+
+You will likely need to override any custom runners we use, e.g. buildjet. For example:
+
+```
+override=catthehacker/ubuntu:act-latest
+
+act -W .github/workflow/release.yml \
+    -P buildjet-8vcpu-ubuntu-2204=$override
+
+# override multiple images at the same time
+act -W .github/workflow/release.yml \
+    -P buildjet-8vcpu-ubuntu-2204=$override \
+    -P buildjet-16vcpu-ubuntu-2204=$override
+```
+
+Trigger with specific event payloads to test pushing to branches or tags:
+
+```
+override=catthehacker/ubuntu:act-latest
+
+# simulate push to main
+act -W .github/workflow/publish.yml \
+    -P buildjet-8vcpu-ubuntu-2204=$override \
+    -P buildjet-16vcpu-ubuntu-2204=$override \
+    -e .github/events/push-tag-main.json
+
+# simulate a `build-` prefixed tag
+act -W .github/workflow/publish.yml \
+    -P buildjet-8vcpu-ubuntu-2204=$override \
+    -P buildjet-16vcpu-ubuntu-2204=$override \
+    -e .github/events/push-tag-buld.json
+```
+
+By default, `act` will send a push event. To trigger a different event:
+
+```
+# basic syntax
+act <EVENT> ...
+
+# simulate a pull request
+act pull_request
+
+# only trigger a specific workflow
+act pull_request -W .github/workflow/pr_checks.yml
+```
+
+## Composite action tests
+
+The composite (custom) action tests can be run by triggering the `test-actions` workflow:
+
+```
+act -W .github/test/test-actions.yml
+```
+
+## Helpful flags
+
+- `--pull=false` - perform fully offline tests if all images are already present
+- `-j <job_name>` - run the specified job only
+- `-l push` - list all workflows with push triggers

.github/test/events/push-main.json

@@ -0,0 +1,3 @@
+{
+  "ref": "refs/heads/main"
+}

.github/test/events/push-tag-build.json

@@ -0,0 +1,3 @@
+{
+  "ref": "refs/tags/build-buildtag"
+}

.github/test/events/push-tag-docker-nonsemver.json

@@ -0,0 +1,3 @@
+{
+  "ref": "refs/tags/v.docker.nonsemver"
+}

.github/test/events/push-tag-docker.json

@@ -0,0 +1,3 @@
+{
+  "ref": "refs/tags/v.docker.1.2.3"
+}

.github/test/events/push-tag-infra-prod.json

@@ -0,0 +1,3 @@
+{
+  "ref": "refs/tags/infra-prod-anything"
+}

.github/test/events/push-tag-infra-test.json

@@ -0,0 +1,3 @@
+{
+  "ref": "refs/tags/infra-test-anything"
+}

.github/test/events/push-tag-semver.json

@@ -0,0 +1,3 @@
+{
+  "ref": "refs/tags/1.2.3"
+}

.github/test/events/push-tag.json

@@ -0,0 +1,3 @@
+{
+  "ref": "refs/tags/standard-tag"
+}

.github/test/test-actions.yml

@@ -0,0 +1,152 @@
+name: Test Actions
+
+on:
+  workflow_dispatch:
+
+jobs:
+  get-image-tag-none:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Log current ref
+        run: |
+          echo "ref: ${{ github.ref }}"
+          echo "ref_type: ${{ github.ref_type }}"
+          echo "ref_name: ${{ github.ref_name }}"
+
+      - name: Run without input tag
+        id: get_tag
+        # this step may fail depending on the current ref
+        continue-on-error: true
+        uses: ./.github/actions/get-image-tag
+
+      - name: Verify output
+        run: |
+          echo "${{ toJson(steps.get_tag) }}"
+
+  get-image-tag-null:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Log current ref
+        run: |
+          echo "ref: ${{ github.ref }}"
+          echo "ref_type: ${{ github.ref_type }}"
+          echo "ref_name: ${{ github.ref_name }}"
+
+      - name: Run without input tag
+        id: get_tag
+        uses: ./.github/actions/get-image-tag
+        # this step may fail depending on the current ref
+        continue-on-error: true
+        with:
+          # this should behave exactly as when no tag is provided
+          tag: null
+
+      - name: Verify output
+        run: |
+          echo "${{ toJson(steps.get_tag) }}"
+
+  get-image-tag-override:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run with tag override
+        id: get_tag
+        uses: ./.github/actions/get-image-tag
+        with:
+          tag: "abc-123"
+
+      - name: Verify output
+        run: |
+          echo "${{ toJson(steps.get_tag) }}"
+
+  get-image-tag-invalid-string:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run with invalid string
+        id: get_tag
+        uses: ./.github/actions/get-image-tag
+        # this step is expected to fail
+        continue-on-error: true
+        with:
+          # does not end with alphanumeric character
+          tag: "abc-123-"
+
+      - name: Fail job if previous step did not fail
+        if: steps.get_tag.outcome != 'failure'
+        run: exit 1
+
+      - name: Verify output
+        run: |
+          echo "${{ toJson(steps.get_tag) }}"
+
+  get-image-tag-prerelease:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run with prerelease semver
+        id: get_tag
+        uses: ./.github/actions/get-image-tag
+        with:
+          tag: "v1.2.3-beta.4"
+
+      - name: Verify output
+        run: |
+          echo "${{ toJson(steps.get_tag) }}"
+
+  get-image-tag-semver:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run with basic semver
+        id: get_tag
+        uses: ./.github/actions/get-image-tag
+        with:
+          tag: "v1.2.3"
+
+      - name: Verify output
+        run: |
+          echo "${{ toJson(steps.get_tag) }}"
+
+  get-image-tag-invalid-semver:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run with invalid semver
+        id: get_tag
+        uses: ./.github/actions/get-image-tag
+        # this step is expected to fail
+        continue-on-error: true
+        with:
+          tag: "v1.2.3-"
+
+      - name: Fail job if previous step did not fail
+        if: steps.get_tag.outcome != 'failure'
+        run: exit 1
+
+      - name: Verify output
+        run: |
+          echo "${{ toJson(steps.get_tag) }}"

.github/workflows/changesets-pr.yml

@@ -0,0 +1,99 @@
+name: 🦋 Changesets PR
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "packages/**"
+      - ".changeset/**"
+      - ".server-changes/**"
+      - "package.json"
+      - "pnpm-lock.yaml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  release-pr:
+    name: Create Release PR
+    runs-on: warp-ubuntu-latest-x64-2x
+    permissions:
+      contents: write
+      pull-requests: write
+      checks: write
+    if: github.repository == 'triggerdotdev/trigger.dev'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 # zizmor: ignore[artipacked] changesets/action pushes the release branch; no artifact upload here so no leak path
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+
+      - name: Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Create release PR
+        id: changesets
+        uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1.9.0
+        with:
+          version: pnpm run changeset:version
+          commit: "chore: release"
+          title: "chore: release"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Update PR title and enhance body
+        if: steps.changesets.outputs.published != 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          PR_NUMBER=$(gh pr list --head changeset-release/main --json number --jq '.[0].number')
+          if [ -n "$PR_NUMBER" ]; then
+            git fetch origin changeset-release/main
+            # we arbitrarily reference the version of the cli package here; it is the same for all package releases
+            VERSION=$(git show origin/changeset-release/main:packages/cli-v3/package.json | jq -r '.version')
+            gh pr edit "$PR_NUMBER" --title "chore: release v$VERSION"
+
+            # Enhance the PR body with a clean, deduplicated summary
+            RAW_BODY=$(gh pr view "$PR_NUMBER" --json body --jq '.body')
+            ENHANCED_BODY=$(CHANGESET_PR_BODY="$RAW_BODY" node scripts/enhance-release-pr.mjs "$VERSION")
+            if [ -n "$ENHANCED_BODY" ]; then
+              gh api repos/triggerdotdev/trigger.dev/pulls/"$PR_NUMBER" \
+                -X PATCH \
+                -f body="$ENHANCED_BODY"
+            fi
+          fi
+
+      # The changesets bot authors release PRs with GITHUB_TOKEN, which by GitHub
+      # design cannot trigger downstream workflows. That leaves the required
+      # "All PR Checks" status permanently Expected and the PR unmergeable.
+      # The release PR only bumps package.json + lockfile + CHANGELOGs from
+      # changesets already on main, so we self-report the required check as
+      # success. If a human ever pushes to changeset-release/main, the real
+      # pr_checks.yml fires and its result overwrites this one (last write wins
+      # for the same context on the same SHA).
+      - name: Self-report "All PR Checks" success on release PR
+        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 [ -z "$PR_NUMBER" ]; then exit 0; fi
+          HEAD_SHA=$(gh pr view "$PR_NUMBER" --json headRefOid --jq '.headRefOid')
+          gh api -X POST repos/${{ github.repository }}/check-runs \
+            -f name="All PR Checks" \
+            -f head_sha="$HEAD_SHA" \
+            -f status=completed \
+            -f conclusion=success \
+            -f 'output[title]=Auto-pass for changeset release PR' \
+            -f 'output[summary]=Required check auto-satisfied for changeset-release/main PRs. Full CI ran on the underlying commits before they landed on main.'

.github/workflows/check-review-md.yml

@@ -0,0 +1,95 @@
+name: 🔎 REVIEW.md Drift Audit
+
+on:
+  pull_request:
+    types: [opened, ready_for_review, synchronize]
+    paths-ignore:
+      - "docs/**"
+      - ".changeset/**"
+      - ".server-changes/**"
+
+concurrency:
+  group: review-md-drift-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  audit:
+    # Set the ENABLE_CLAUDE_CODE repository variable to 'false' to turn off Claude
+    # jobs; leave it unset (the default) to keep them enabled.
+    if: >-
+      vars.ENABLE_CLAUDE_CODE != 'false' &&
+      github.event.pull_request.draft == false &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: warp-ubuntu-latest-x64-2x
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@428971d2ecd6e3a7cb0ee0da2a3a8b33fdb3678d # v1.0.157
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          use_sticky_comment: true
+          allowed_bots: "devin-ai-integration[bot]"
+
+          claude_args: |
+            --max-turns 30
+            --allowedTools "Read,Glob,Grep,Bash(git diff:*)"
+
+          prompt: |
+            You are auditing this PR for drift against `.claude/REVIEW.md`.
+
+            ## Context
+
+            `.claude/REVIEW.md` is the repo's source of truth for what AI / agent code reviewers should treat as critical findings (rolling-deploy safety, hot-table indexes, recovery-path queries, testcontainers usage, Lua versioning, etc.). It is consumed by review agents to calibrate severity. If REVIEW.md goes stale, every future agent review degrades.
+
+            ## Strategy — read this first
+
+            You have a hard turn budget. Spend it on signal, not coverage. The audit is allowed to miss things; it is NOT allowed to time out.
+
+            1. Read `.claude/REVIEW.md` once, in full.
+            2. Run `git diff origin/main...HEAD --name-only` to get the list of changed files. Do NOT read the diff content yet.
+            3. Scan the file-list for relevance to REVIEW.md scope. Relevance signals: changes to Prisma schema, Redis / queue / Lua code, hot tables, recovery / restart loops, new packages, deletions of paths REVIEW.md cites. Skim everything else.
+            4. Open at most **5 files** total — only the ones most likely to surface a real signal. If nothing in the file-list looks relevant to any REVIEW.md rule, do NOT read any files; go straight to the verdict.
+            5. Form a verdict and stop. Do not exhaust the turn budget exploring.
+
+            Large PRs (>50 files changed) are a strong signal to be MORE selective, not more thorough. Pick 3-5 files at most.
+
+            ## What to look for
+
+            - **Stale references** — does any REVIEW.md rule cite a file, directory, function, table, Prisma model, or package name that has been removed or renamed in this PR (or is already gone from `main`)?
+            - **Contradictions** — does code in this PR clearly violate a current REVIEW.md rule? (Don't re-review the PR. Only flag if REVIEW.md and the PR plainly disagree.)
+            - **Missing rules** — does this PR introduce a new pattern future reviewers should know about? Examples: a new hot table, a new Lua-script versioning convention, a new safety wrapper, a new "must always check" invariant.
+            - **Obsolete rules** — has the repo moved past a constraint REVIEW.md still asserts? (e.g. a deprecated path is gone, a pattern is now linted, V1 code is deleted.)
+
+            ## Response format
+
+            If nothing needs changing:
+
+            ✅ REVIEW.md looks current for this PR.
+
+            Otherwise:
+
+            📝 **REVIEW.md updates suggested:**
+
+            - **[stale]** `<rule excerpt>` — <what's stale and why>
+            - **[contradiction]** `<rule excerpt>` — <what in this PR disagrees>
+            - **[missing]** under `## <section>` — <one-sentence draft rule>
+            - **[obsolete]** `<rule excerpt>` — <why this rule no longer applies>
+
+            ## Rules
+
+            - Maximum 3 suggestions per audit. Pick the highest-signal ones.
+            - Only flag things that would actually mislead a future reviewer. Style and wording do not count.
+            - Do NOT review the PR itself. Do NOT propose rules outside REVIEW.md's existing sections.
+            - Do NOT propose rules for one-off PR specifics that don't generalize to future PRs.
+            - If REVIEW.md does not exist in the repo, respond with `(skip)` and stop.
+            - When in doubt between "one more file read" and "finish now" — finish now.

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

@@ -0,0 +1,83 @@
+name: 📝 Agent Instructions Audit
+
+on:
+  pull_request:
+    types: [opened, ready_for_review, synchronize]
+    paths-ignore:
+      - "docs/**"
+      - ".changeset/**"
+      - ".server-changes/**"
+      - "**/*.md"
+
+concurrency:
+  group: agent-instructions-audit-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  audit:
+    # Set the ENABLE_CLAUDE_CODE repository variable to 'false' to turn off Claude
+    # jobs; leave it unset (the default) to keep them enabled.
+    if: >-
+      vars.ENABLE_CLAUDE_CODE != 'false' &&
+      github.event.pull_request.draft == false &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: warp-ubuntu-latest-x64-2x
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@428971d2ecd6e3a7cb0ee0da2a3a8b33fdb3678d # v1.0.157
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          use_sticky_comment: true
+          allowed_bots: "devin-ai-integration[bot]"
+
+          claude_args: |
+            --max-turns 25
+            --model claude-opus-4-8
+            --allowedTools "Read,Glob,Grep,Bash(git diff:*)"
+
+          prompt: |
+            You are reviewing a PR to check whether any agent instruction files need updating.
+
+            In this repo:
+            - Root shared agent guidance lives in `AGENTS.md`.
+            - Root `CLAUDE.md` is only a Claude Code adapter that imports `AGENTS.md`.
+            - Subdirectories may still have scoped `CLAUDE.md` files.
+            - `.claude/rules/` contains additional Claude Code guidance.
+
+            ## Your task
+
+            1. Run `git diff origin/main...HEAD --name-only` to see which files changed in this PR.
+            2. For each changed directory, check the applicable instruction files: root `AGENTS.md`, any `CLAUDE.md` in that directory or a parent directory, and relevant `.claude/rules/` files.
+            3. Determine if any instruction file should be updated based on the changes. Consider:
+               - New files/directories that aren't covered by existing documentation
+               - Changed architecture or patterns that contradict current agent guidance
+               - New dependencies, services, or infrastructure that agents should know about
+               - Renamed or moved files that are referenced in an instruction file
+               - Changes to build commands, test patterns, or development workflows
+
+            ## Response format
+
+            If NO updates are needed, respond with exactly:
+            ✅ Agent instruction files look current for this PR.
+
+            If updates ARE needed, respond with a short list:
+            📝 **Agent instruction updates suggested:**
+            - `AGENTS.md`: [what should be added/changed]
+            - `path/to/CLAUDE.md`: [what should be added/changed]
+            - `.claude/rules/file.md`: [what should be added/changed]
+
+            Keep suggestions specific and brief. Only flag things that would actually mislead agents in future sessions.
+            Do NOT suggest updates for trivial changes (bug fixes, small refactors within existing patterns).
+            Do NOT suggest creating new CLAUDE.md files - only updates to existing instruction files.

.github/workflows/claude.yml

@@ -0,0 +1,76 @@
+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:
+    # Set the ENABLE_CLAUDE_CODE repository variable to 'false' to turn off Claude
+    # jobs; leave it unset (the default) to keep them enabled.
+    if: |
+      vars.ENABLE_CLAUDE_CODE != 'false' &&
+      (
+        (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: warp-ubuntu-latest-x64-2x
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          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@428971d2ecd6e3a7cb0ee0da2a3a8b33fdb3678d # v1.0.157
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+
+          # 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/code-quality.yml

@@ -0,0 +1,38 @@
+name: "🎨 Format & Lint"
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  code-quality:
+    runs-on: warp-ubuntu-latest-x64-2x
+
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          cache: "pnpm"
+
+      - name: 📥 Download deps
+        run: pnpm install --frozen-lockfile
+
+      - name: 💅 Check formatting
+        run: pnpm exec oxfmt --check .
+
+      - name: 🔎 Lint
+        run: pnpm exec oxlint .

.github/workflows/dashboard-agent-deploy.yml

@@ -0,0 +1,72 @@
+name: "🤖 Deploy dashboard agent"
+
+# Deploys the @internal/dashboard-agent chat.agent to its Trigger.dev project
+# with --skip-promotion, so a deploy never becomes "current" on its own. The
+# consuming app cuts over by pinning DASHBOARD_AGENT_VERSION to the new version.
+# Runs a leg per environment (staging + prod), each gated by its own environment;
+# a push to main that touches the agent or its store triggers both. Version
+# numbers are per-environment, so pin each environment to its own leg's version.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "internal-packages/dashboard-agent/**"
+      - "internal-packages/dashboard-agent-db/**"
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  deploy:
+    name: Deploy dashboard agent (${{ matrix.environment }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      # One environment at a time: parallel deploys of the same project race.
+      max-parallel: 1
+      matrix:
+        environment: [staging, prod]
+    # Per-environment reviewer gate + source of the scoped deploy PAT.
+    environment: dashboard-agent-${{ matrix.environment }}
+    concurrency:
+      group: dashboard-agent-deploy-${{ matrix.environment }}
+      cancel-in-progress: false
+    permissions:
+      contents: read
+    env:
+      TRIGGER_API_URL: https://api.trigger.dev
+      TRIGGER_DASHBOARD_AGENT_PROJECT_REF: ${{ vars.TRIGGER_DASHBOARD_AGENT_PROJECT_REF }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          cache: "pnpm"
+
+      - name: Install + build the CLI and the agent's deps
+        run: |
+          set -euo pipefail
+          pnpm install --frozen-lockfile
+          # Prisma client is needed because the build closure pulls in @trigger.dev/database.
+          pnpm run generate
+          # Config-time imports the agent's trigger.config.ts needs: defineConfig (sdk), aptGet (build).
+          pnpm run build --filter trigger.dev --filter @trigger.dev/build --filter @trigger.dev/sdk
+
+      - name: Deploy (--skip-promotion)
+        working-directory: internal-packages/dashboard-agent
+        env:
+          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_DASHBOARD_AGENT_DEPLOY_TOKEN }}
+        # Invoke the built CLI directly (what the workspace .bin/trigger wrapper does),
+        # so a not-yet-linked bin after a fresh install can't break the deploy.
+        run: node ../../packages/cli-v3/dist/esm/index.js deploy --skip-promotion --env ${{ matrix.environment }}

.github/workflows/dependabot-critical-alerts.yml

@@ -0,0 +1,87 @@
+name: Dependabot Critical Alerts
+
+on:
+  schedule:
+    - cron: "0 8 * * *" # Daily 08:00 UTC
+  workflow_dispatch:
+    inputs:
+      severity:
+        description: "Severity to alert on"
+        type: choice
+        options:
+          - critical
+          - high
+          - medium
+          - low
+        default: critical
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  alert:
+    name: Post critical alerts
+    # Set the ENABLE_DEPENDABOT_ALERTS repository variable to 'false' to turn off
+    # the Dependabot alert/summary notifiers — e.g. forks/mirrors that lack the
+    # DEPENDABOT_ALERTS_TOKEN / SLACK_BOT_TOKEN secrets. Defaults to enabled.
+    if: ${{ vars.ENABLE_DEPENDABOT_ALERTS != 'false' }}
+    runs-on: warp-ubuntu-latest-x64-2x
+    environment: dependabot-summary
+    env:
+      SEVERITY: ${{ inputs.severity || 'critical' }}
+    steps:
+      - name: Fetch alerts
+        id: alerts
+        env:
+          GH_TOKEN: ${{ secrets.DEPENDABOT_ALERTS_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          gh api -X GET "/repos/$REPO/dependabot/alerts" \
+            -F state=open -F severity="$SEVERITY" --paginate > pages.json
+          jq -s 'add' pages.json > alerts.json
+          TOTAL=$(jq 'length' alerts.json)
+          echo "total=$TOTAL" >> "$GITHUB_OUTPUT"
+          if [ "$TOTAL" = "0" ]; then
+            exit 0
+          fi
+          LIST=$(jq -r '
+            map("• <\(.html_url)|#\(.number)> *\(.dependency.package.name)* - \(.security_advisory.summary)")
+            | join("\n")
+          ' alerts.json)
+          {
+            echo "list<<EOF"
+            echo "$LIST"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Build Slack payload
+        if: steps.alerts.outputs.total != '0'
+        env:
+          REPO: ${{ github.repository }}
+          CHANNEL: ${{ vars.SLACK_CHANNEL_ID }}
+          TOTAL: ${{ steps.alerts.outputs.total }}
+          LIST: ${{ steps.alerts.outputs.list }}
+        run: |
+          jq -n \
+            --arg channel "$CHANNEL" \
+            --arg repo "$REPO" \
+            --arg total "$TOTAL" \
+            --arg list "$LIST" \
+            --arg severity "$SEVERITY" \
+            '{
+              channel: $channel,
+              text: ":bufo-alarma: `\($repo)` - *\($total) open \($severity) alert(s)*\n\($list)\n\n<https://github.com/\($repo)/security/dependabot?q=is%3Aopen+severity%3A\($severity)|View \($severity) alerts>"
+            }' > payload.json
+
+      - name: Post Slack alert
+        if: steps.alerts.outputs.total != '0'
+        uses: slackapi/slack-github-action@45a88b9581bfab2566dc881e2cd66d334e621e2c # v3.0.3
+        with:
+          method: chat.postMessage
+          token: ${{ secrets.SLACK_BOT_TOKEN }}
+          payload-file-path: payload.json

.github/workflows/dependabot-weekly-summary.yml

@@ -0,0 +1,210 @@
+name: Dependabot Weekly Summary
+
+on:
+  schedule:
+    - cron: "0 8 * * 1" # Mon 08:00 UTC
+  workflow_dispatch:
+
+# Single-purpose monitoring workflow; serialise on workflow name only - we never
+# want two concurrent summary runs racing to post the same digest.
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read # gh CLI baseline
+  pull-requests: read # gh pr list (open dependabot PRs)
+  actions: read # gh run list / view (parse latest dependabot run logs)
+
+jobs:
+  summary:
+    name: Post weekly Dependabot summary
+    # Set the ENABLE_DEPENDABOT_ALERTS repository variable to 'false' to turn off
+    # the Dependabot alert/summary notifiers — e.g. forks/mirrors that lack the
+    # DEPENDABOT_ALERTS_TOKEN / SLACK_BOT_TOKEN secrets. Defaults to enabled.
+    if: ${{ vars.ENABLE_DEPENDABOT_ALERTS != 'false' }}
+    runs-on: warp-ubuntu-latest-x64-2x
+    environment: dependabot-summary
+    env:
+      # Severities surface in the actions list when their remaining TTR drops
+      # below this many days. Override via repo/env var ACTION_THRESHOLD_DAYS.
+      THRESHOLD_DAYS: ${{ vars.ACTION_THRESHOLD_DAYS || '7' }}
+    steps:
+      - name: Fetch alerts and compute summaries
+        id: alerts
+        env:
+          GH_TOKEN: ${{ secrets.DEPENDABOT_ALERTS_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          if ! gh api -X GET "/repos/$REPO/dependabot/alerts" --paginate > pages.json 2> err.txt; then
+            echo "total=?" >> "$GITHUB_OUTPUT"
+            ERR=$(head -c 200 err.txt | tr '\n' ' ')
+            echo "by_severity=:x: _failed to fetch alerts: ${ERR}_" >> "$GITHUB_OUTPUT"
+            echo "actions=:x: _alerts unavailable_" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          jq -s '[.[][] | select(.state == "open")]' pages.json > open.json
+
+          TOTAL=$(jq 'length' open.json)
+          echo "total=$TOTAL" >> "$GITHUB_OUTPUT"
+
+          if [ "$TOTAL" = "0" ]; then
+            echo "by_severity=:white_check_mark: No open alerts." >> "$GITHUB_OUTPUT"
+            echo "actions=_None_" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Severity breakdown - real newlines so jq --arg in the payload
+          # builder encodes them as proper \n in JSON (Slack renders as breaks).
+          BY_SEV=$(jq -r '
+            group_by(.security_advisory.severity)
+            | map({sev: .[0].security_advisory.severity,
+                   count: length,
+                   weight: ({"critical":0,"high":1,"medium":2,"low":3}[.[0].security_advisory.severity])})
+            | sort_by(.weight)
+            | map("• *\(.count)* \(.sev)")
+            | join("\n")
+          ' open.json)
+          {
+            echo "by_severity<<EOF"
+            echo "$BY_SEV"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+          # Actions: alerts within THRESHOLD_DAYS of their TTR (P0=7d, P1=30d, P2=90d, P3=no deadline)
+          # Grouped by (package, severity); shows earliest deadline per group.
+          ACTIONS=$(jq -r --argjson threshold "$THRESHOLD_DAYS" '
+            [.[]
+              | (.security_advisory.severity) as $sev
+              | ({"critical":7,"high":30,"medium":90,"low":null}[$sev]) as $ttr
+              | select($ttr != null)
+              | ((now - (.created_at | fromdateiso8601)) / 86400 | floor) as $age
+              | {pkg: .dependency.package.name, sev: $sev, remaining: ($ttr - $age)}
+            ]
+            | group_by([.pkg, .sev])
+            | map({pkg: .[0].pkg, sev: .[0].sev, count: length, min_remaining: ([.[].remaining] | min)})
+            | map(select(.min_remaining < $threshold))
+            | sort_by(.min_remaining)
+            | if length == 0 then "_None_"
+              else (map(
+                "• *\(.pkg)* (\(.sev))" +
+                (if .count > 1 then " ×\(.count)" else "" end) + " - " +
+                (if .min_remaining < 0 then "*OVERDUE* by \(-.min_remaining)d"
+                 else "\(.min_remaining)d remaining" end)
+              ) | join("\n"))
+              end
+          ' open.json)
+          {
+            echo "actions<<EOF"
+            echo "$ACTIONS"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Fetch open dependabot PRs
+        id: prs
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          REPO_URL: https://github.com/${{ github.repository }}
+        run: |
+          if ! PR_JSON=$(gh pr list --repo "$REPO" --state open --author "app/dependabot" --json number,title 2> err.txt); then
+            ERR=$(head -c 200 err.txt | tr '\n' ' ')
+            echo "list=:x: _failed to fetch PRs: ${ERR}_" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          LIST=$(echo "$PR_JSON" | jq -r --arg url "$REPO_URL" '
+            if length == 0 then "_None_"
+            else (map("• <\($url)/pull/\(.number)|#\(.number)> \(.title)") | join("\n"))
+            end
+          ')
+          {
+            echo "list<<EOF"
+            echo "$LIST"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Find latest npm dependabot run
+        id: latest
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          # Repos without a dependabot.yml have no "Dependabot Updates" workflow;
+          # treat the lookup failure as "no recent run found" rather than failing.
+          if ! RUN_ID=$(gh run list --repo "$REPO" --workflow "Dependabot Updates" --status success --limit 30 --json databaseId,name --jq 'first(.[] | select(.name | startswith("npm_and_yarn")) | .databaseId) // empty' 2>/dev/null); then
+            RUN_ID=""
+          fi
+          echo "run_id=$RUN_ID" >> "$GITHUB_OUTPUT"
+
+      - name: Extract stuck deps (only if actions pending)
+        id: stuck
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          RUN_ID: ${{ steps.latest.outputs.run_id }}
+          ACTIONS: ${{ steps.alerts.outputs.actions }}
+        run: |
+          # Skip the stuck section entirely when nothing in the actions list
+          # - keeps the digest tidy when there's nothing to actually act on.
+          if [ "$ACTIONS" = "_None_" ]; then
+            echo "section=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          HEADER=$'\n\n*Couldn\'t auto-fix (need manual `pnpm.overrides`):*\n'
+          if [ -z "$RUN_ID" ]; then
+            {
+              echo "section<<EOF"
+              echo "${HEADER}_(no recent npm run found)_"
+              echo "EOF"
+            } >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          gh run view "$RUN_ID" --repo "$REPO" --log > log.txt 2>&1 || true
+          STUCK=$(grep -oE "No update possible for [^[:space:]]+ [0-9][^[:space:]]*" log.txt | sed 's/No update possible for //' | sort -u || true)
+          if [ -z "$STUCK" ]; then
+            {
+              echo "section<<EOF"
+              echo "${HEADER}_None_"
+              echo "EOF"
+            } >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          LIST=$(echo "$STUCK" | awk 'NR>1{printf "\n"} {printf "• *%s* %s", $1, $2}')
+          {
+            echo "section<<EOF"
+            echo "${HEADER}${LIST}"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Build Slack payload
+        env:
+          REPO: ${{ github.repository }}
+          CHANNEL: ${{ vars.SLACK_CHANNEL_ID }}
+          TOTAL: ${{ steps.alerts.outputs.total }}
+          BY_SEVERITY: ${{ steps.alerts.outputs.by_severity }}
+          PRS_LIST: ${{ steps.prs.outputs.list }}
+          ACTIONS: ${{ steps.alerts.outputs.actions }}
+          STUCK: ${{ steps.stuck.outputs.section }}
+        run: |
+          # Build payload via jq so PR titles or error strings containing
+          # quotes/backslashes/newlines can't break the JSON.
+          jq -n \
+            --arg channel "$CHANNEL" \
+            --arg repo "$REPO" \
+            --arg total "$TOTAL" \
+            --arg by_severity "$BY_SEVERITY" \
+            --arg prs_list "$PRS_LIST" \
+            --arg actions "$ACTIONS" \
+            --arg stuck "$STUCK" \
+            --arg threshold "$THRESHOLD_DAYS" \
+            '{
+              channel: $channel,
+              text: ":calendar: *Weekly Dependabot summary* - `\($repo)`\n\n*Open alerts (\($total)):*\n\($by_severity)\n\n*Open Dependabot PRs:*\n\($prs_list)\n\n*Actions needed (<\($threshold)d remaining):*\n\($actions)\($stuck)\n\n<https://github.com/\($repo)/security/dependabot|Dependabot alerts>"
+            }' > payload.json
+
+      - name: Post Slack summary
+        uses: slackapi/slack-github-action@45a88b9581bfab2566dc881e2cd66d334e621e2c # v3.0.3
+        with:
+          method: chat.postMessage
+          token: ${{ secrets.SLACK_BOT_TOKEN }}
+          payload-file-path: payload.json

.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: 📚 Docs Checks
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - "docs/**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  check-broken-links:
+    runs-on: warp-ubuntu-latest-x64-2x
+    defaults:
+      run:
+        working-directory: ./docs
+    steps:
+      - name: 📥 Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: 📦 Cache npm
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: |
+            ~/.npm
+          key: |
+            ${{ runner.os }}-mintlify
+          restore-keys: |
+            ${{ runner.os }}-mintlify
+
+      - name: 🔗 Check for broken links
+        run: npx mintlify@4.0.393 broken-links

.github/workflows/e2e-webapp-auth-full.yml

@@ -0,0 +1,120 @@
+name: "🛡️ E2E Tests: Webapp Auth (full)"
+
+# Comprehensive RBAC auth test suite — see TRI-8731. Runs separately from
+# the smoke e2e-webapp.yml because it covers every route family with a
+# pass/fail matrix and would otherwise dominate per-PR CI time.
+#
+# Triggered:
+#   - Manually via workflow_dispatch.
+#   - Nightly via schedule.
+#   - On pull requests touching auth-relevant files only (paths filter).
+
+permissions:
+  contents: read
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 4 * * *" # 04:00 UTC daily
+  pull_request:
+    paths:
+      - "apps/webapp/app/services/routeBuilders/**"
+      - "apps/webapp/app/services/rbac.server.ts"
+      - "apps/webapp/app/services/apiAuth.server.ts"
+      - "apps/webapp/app/services/personalAccessToken.server.ts"
+      - "apps/webapp/app/services/sessionStorage.server.ts"
+      - "apps/webapp/app/routes/api.v*.**"
+      - "apps/webapp/app/routes/realtime.v*.**"
+      - "apps/webapp/test/**/*.e2e.full.test.ts"
+      - "apps/webapp/test/setup/global-e2e-full-setup.ts"
+      - "apps/webapp/test/helpers/sharedTestServer.ts"
+      - "apps/webapp/test/helpers/seedTestSession.ts"
+      - "apps/webapp/vitest.e2e.full.config.ts"
+      - "internal-packages/rbac/**"
+      - "packages/plugins/**"
+      - ".github/workflows/e2e-webapp-auth-full.yml"
+
+jobs:
+  e2eAuthFull:
+    name: "🛡️ E2E Auth Tests (full)"
+    runs-on: warp-ubuntu-latest-x64-8x
+    timeout-minutes: 30
+    env:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+    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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          # Don't leave the GITHUB_TOKEN in .git/config — this job
+          # doesn't need to push and the persisted creds would be
+          # readable from any subsequent step (zizmor/artipacked).
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          cache: "pnpm"
+
+      - name: 🐳 Login to DockerHub
+        if: ${{ env.DOCKERHUB_USERNAME }}
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        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: |
+          docker pull postgres:14
+          docker pull redis:7.2
+          docker pull testcontainers/ryuk:0.11.0
+
+      - name: 📥 Download deps
+        run: pnpm install --frozen-lockfile
+
+      - name: 📀 Generate Prisma Client
+        run: pnpm run generate
+
+      - name: 🏗️ Build Webapp
+        run: pnpm run build --filter webapp
+
+      - name: 🛡️ Run Webapp Full Auth E2E Tests
+        run: cd apps/webapp && pnpm exec vitest run --config vitest.e2e.full.config.ts --reporter=default
+        env:
+          WEBAPP_TEST_VERBOSE: "1"

.github/workflows/e2e-webapp.yml

@@ -0,0 +1,97 @@
+name: "🧪 E2E Tests: Webapp"
+
+permissions:
+  contents: read
+
+on:
+  workflow_call:
+    secrets:
+      DOCKERHUB_USERNAME:
+        required: false
+      DOCKERHUB_TOKEN:
+        required: false
+
+jobs:
+  e2eTests:
+    name: "🧪 E2E Tests: Webapp"
+    runs-on: warp-ubuntu-latest-x64-16x
+    timeout-minutes: 20
+    env:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+    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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          cache: "pnpm"
+
+      # ..to avoid rate limits when pulling images
+      - name: 🐳 Login to DockerHub
+        if: ${{ env.DOCKERHUB_USERNAME }}
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        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 redis:7.2
+          docker pull testcontainers/ryuk:0.11.0
+          echo "Image pre-pull complete"
+
+      - name: 📥 Download deps
+        run: pnpm install --frozen-lockfile
+
+      - name: 📀 Generate Prisma Client
+        run: pnpm run generate
+
+      - name: 🏗️ Build Webapp
+        run: pnpm run build --filter webapp
+
+      - name: 🧪 Run Webapp E2E Tests
+        run: cd apps/webapp && pnpm exec vitest run --config vitest.e2e.config.ts --reporter=default
+        env:
+          WEBAPP_TEST_VERBOSE: "1"

.github/workflows/e2e.yml

@@ -1,65 +1,62 @@
-name: "🧪 E2E Tests"
+name: "E2E"
+
+permissions:
+  contents: read
+
 on:
   workflow_call:
-jobs:
-  e2e:
-    name: "🧪 E2E Tests"
-    runs-on: buildjet-4vcpu-ubuntu-2204
-    steps:
-      - name: 🐳 Login to Docker Hub
-        uses: docker/login-action@v2
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
+    inputs:
+      package:
+        description: The identifier of the job to run
+        default: webapp
+        required: false
+        type: string
 
+jobs:
+  cli-v3:
+    name: "🧪 CLI v3 tests (${{ matrix.os }} - ${{ matrix.package-manager }})"
+    if: inputs.package == 'cli-v3' || inputs.package == ''
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [warp-ubuntu-latest-x64-4x, warp-windows-latest-x64-8x]
+        package-manager: ["npm", "pnpm"]
+    steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: ⎔ Setup pnpm
-        uses: pnpm/action-setup@v2.2.4
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
         with:
-          version: 7.18
+          version: 10.33.2
 
       - name: ⎔ Setup node
-        uses: buildjet/setup-node@v3
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: 18
-          cache: "pnpm"
+          node-version: 22.23.1
 
       - name: 📥 Download deps
-        run: pnpm install --frozen-lockfile
+        run: pnpm install --frozen-lockfile --filter trigger.dev...
 
-      - name: Install Playwright Browsers
-        run: npx playwright install --with-deps
+      # Prisma clients generate concurrently and share one engine binary in the
+      # pnpm store; the generate script retries the transient Windows EPERM race.
+      - name: 📀 Generate Prisma Client
+        run: pnpm run generate
 
-      - name: Run Playwright tests
+      - name: 🔧 Build v3 cli monorepo dependencies
+        run: pnpm run build --filter trigger.dev^...
+
+      - name: 🔧 Build worker template files
+        run: pnpm --filter trigger.dev run --if-present build:workers
+
+      - name: Enable corepack
+        run: corepack enable
+
+      - name: Run E2E Tests
+        shell: bash
         run: |
-          # Setup environment variables
-          cp ./.env.example ./.env
-          cp ./references/nextjs-test/.env.example ./references/nextjs-test/.env.local
-
-          # 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
-
-          # Execute tests
-          pnpm run docker
-          pnpm run db:migrate
-          pnpm run db:seed
-          pnpm run test:e2e
-
-          # Cleanup
-          pnpm run docker:stop
-
-      - name: Upload Playwright report
-        uses: actions/upload-artifact@v3
-        if: always()
-        with:
-          name: playwright-report
-          path: playwright-report/
-          retention-days: 30
+          LOG=debug PM=${{ matrix.package-manager }} pnpm --filter trigger.dev run test:e2e

.github/workflows/helm-prerelease.yml

@@ -0,0 +1,205 @@
+name: 🧭 Helm Chart Prerelease
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - "hosting/k8s/helm/**"
+  push:
+    branches:
+      - main
+    paths:
+      - "hosting/k8s/helm/**"
+  workflow_dispatch:
+    inputs:
+      app_version:
+        description: "Override appVersion (e.g. 'main', 'v4.4.4'). Leave empty to keep Chart.yaml value."
+        required: false
+        type: string
+        default: ""
+
+concurrency:
+  group: helm-prerelease-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  REGISTRY: ghcr.io
+  CHART_NAME: trigger
+
+jobs:
+  lint-and-test:
+    runs-on: warp-ubuntu-latest-x64-2x
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Helm
+        uses: azure/setup-helm@9bc31f4ebc9c6b171d7bfbaa5d006ae7abdb4310 # v5.0.1
+        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@sha256:85dbef6b4b312b99133decc9c6fc9495e9fc5f92293d4ff3b7e1b30f5611823c
+        with:
+          entrypoint: "/kubeconform"
+          args: "-summary -output json ./helm-output"
+
+  prerelease:
+    needs: lint-and-test
+    # Set the ENABLE_HELM_PRERELEASE repository variable to 'false' to turn off
+    # publishing the chart to GHCR — e.g. forks/mirrors that lack write_package
+    # on the owner's charts namespace. Defaults to enabled; the lint-and-test
+    # job above always runs regardless.
+    if: |
+      vars.ENABLE_HELM_PRERELEASE != 'false' &&
+      ((github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) ||
+      github.event_name == 'push' ||
+      github.event_name == 'workflow_dispatch')
+    runs-on: warp-ubuntu-latest-x64-2x
+    permissions:
+      contents: read
+      packages: write
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Helm
+        uses: azure/setup-helm@9bc31f4ebc9c6b171d7bfbaa5d006ae7abdb4310 # v5.0.1
+        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@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        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}')
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            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}"
+          elif [[ "${{ github.event_name }}" == "push" ]]; then
+            SHORT_SHA=$(echo "${GITHUB_SHA}" | cut -c1-7)
+            PRERELEASE_VERSION="${BASE_VERSION}-main.${SHORT_SHA}"
+          else
+            SHORT_SHA=$(echo "${GITHUB_SHA}" | cut -c1-7)
+            REF_SLUG=$(echo "${GITHUB_REF_NAME}" | tr '/' '-' | tr -cd 'a-zA-Z0-9-')
+            if [[ -z "$REF_SLUG" ]]; then
+              REF_SLUG="manual"
+            fi
+            PRERELEASE_VERSION="${BASE_VERSION}-${REF_SLUG}.${SHORT_SHA}"
+          fi
+          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
+        env:
+          STEPS_VERSION_OUTPUTS_VERSION: ${{ steps.version.outputs.version }}
+
+      - name: Override appVersion
+        if: github.event_name == 'workflow_dispatch' && inputs.app_version != ''
+        env:
+          APP_VERSION: ${{ inputs.app_version }}
+        run: |
+          yq -i '.appVersion = strenv(APP_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"
+        env:
+          STEPS_VERSION_OUTPUTS_VERSION: ${{ steps.version.outputs.version }}
+
+      - name: Write run summary
+        run: |
+          {
+            echo "### 🧭 Helm Chart Prerelease Published"
+            echo ""
+            echo "**Version:** \`${STEPS_VERSION_OUTPUTS_VERSION}\`"
+            echo ""
+            echo "**Install:**"
+            echo '```bash'
+            echo "helm upgrade --install trigger \\"
+            echo "  oci://${{ env.REGISTRY }}/${{ github.repository_owner }}/charts/${{ env.CHART_NAME }} \\"
+            echo "  --version \"${STEPS_VERSION_OUTPUTS_VERSION}\""
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+        env:
+          STEPS_VERSION_OUTPUTS_VERSION: ${{ steps.version.outputs.version }}
+
+      - name: Find existing comment
+        if: github.event_name == 'pull_request'
+        uses: peter-evans/find-comment@b30e6a3c0ed37e7c023ccd3f1db5c6c0b0c23aad # v4.0.0
+        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
+        if: github.event_name == 'pull_request'
+        uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9 # v5.0.0
+        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

@@ -1,13 +1,8 @@
 name: 🤖 PR Checks
 
 on:
-  pull_request_target:
-    branches:
-      - main
-    paths-ignore:
-      - "**.md"
-      - ".github/CODEOWNERS"
-      - ".github/ISSUE_TEMPLATE/**"
+  pull_request:
+    types: [opened, synchronize, reopened]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@@ -15,17 +10,174 @@ concurrency:
 
 permissions:
   contents: read
-  id-token: write
+  pull-requests: read
 
 jobs:
-  typecheck:
-    uses: ./.github/workflows/typecheck.yml
-    secrets: inherit
+  changes:
+    name: Detect changes
+    runs-on: warp-ubuntu-latest-x64-2x
+    outputs:
+      code: ${{ steps.code_filter.outputs.code }}
+      typecheck_self: ${{ steps.filter.outputs.typecheck_self }}
+      webapp: ${{ steps.filter.outputs.webapp }}
+      packages: ${{ steps.filter.outputs.packages }}
+      internal: ${{ steps.filter.outputs.internal }}
+      cli: ${{ steps.filter.outputs.cli }}
+      sdk: ${{ steps.filter.outputs.sdk }}
+    steps:
+      # `code` uses `every` semantics so the negation patterns actually subtract.
+      # With the default `some` quantifier, `**` matches every file and the
+      # subsequent `!...` patterns are no-ops (each pattern is OR'd, not AND'd).
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        id: code_filter
+        with:
+          predicate-quantifier: every
+          filters: |
+            code:
+              - '**'
+              - '!docs/**'
+              - '!.changeset/**'
+              - '!hosting/**'
+              - '!.github/**'
+              - '!**/*.md'
+              - '!**/.env.example'
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        id: filter
+        with:
+          filters: |
+            typecheck_self:
+              - '.github/workflows/pr_checks.yml'
+              - '.github/workflows/typecheck.yml'
+              - '.github/workflows/code-quality.yml'
+            webapp:
+              - 'apps/webapp/**'
+              - 'packages/**'
+              - 'internal-packages/**'
+              - '.github/workflows/pr_checks.yml'
+              - '.github/workflows/unit-tests-webapp.yml'
+              - '.github/workflows/e2e-webapp.yml'
+              - '.configs/**'
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - 'pnpm-workspace.yaml'
+              - 'turbo.json'
+            packages:
+              - 'packages/**'
+              - '.github/workflows/pr_checks.yml'
+              - '.github/workflows/unit-tests-packages.yml'
+              - '.configs/**'
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - 'pnpm-workspace.yaml'
+              - 'turbo.json'
+            internal:
+              - 'internal-packages/**'
+              - 'packages/**'
+              - '.github/workflows/pr_checks.yml'
+              - '.github/workflows/unit-tests-internal.yml'
+              - '.configs/**'
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - 'pnpm-workspace.yaml'
+              - 'turbo.json'
+            cli:
+              - 'packages/cli-v3/**'
+              - 'packages/build/**'
+              - 'packages/core/**'
+              - 'packages/schema-to-json/**'
+              - '.github/workflows/pr_checks.yml'
+              - '.github/workflows/e2e.yml'
+              - '.configs/**'
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - 'pnpm-workspace.yaml'
+              - 'turbo.json'
+            sdk:
+              - 'packages/trigger-sdk/**'
+              - 'packages/core/**'
+              - '.github/workflows/pr_checks.yml'
+              - '.github/workflows/sdk-compat.yml'
+              - '.configs/**'
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - 'pnpm-workspace.yaml'
+              - 'turbo.json'
 
-  units:
-    uses: ./.github/workflows/unit-tests.yml
-    secrets: inherit
+  code-quality:
+    uses: ./.github/workflows/code-quality.yml
+
+  typecheck:
+    needs: changes
+    if: needs.changes.outputs.code == 'true' || needs.changes.outputs.typecheck_self == 'true'
+    uses: ./.github/workflows/typecheck.yml
+
+  webapp:
+    needs: changes
+    if: needs.changes.outputs.webapp == 'true'
+    uses: ./.github/workflows/unit-tests-webapp.yml
+    secrets:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+
+  e2e-webapp:
+    needs: changes
+    if: needs.changes.outputs.webapp == 'true'
+    uses: ./.github/workflows/e2e-webapp.yml
+    secrets:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+
+  packages:
+    needs: changes
+    if: needs.changes.outputs.packages == 'true'
+    uses: ./.github/workflows/unit-tests-packages.yml
+    secrets:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+
+  internal:
+    needs: changes
+    if: needs.changes.outputs.internal == 'true'
+    uses: ./.github/workflows/unit-tests-internal.yml
+    secrets:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
 
   e2e:
+    needs: changes
+    if: needs.changes.outputs.cli == 'true'
     uses: ./.github/workflows/e2e.yml
-    secrets: inherit
+    with:
+      package: cli-v3
+
+  sdk-compat:
+    needs: changes
+    if: needs.changes.outputs.sdk == 'true'
+    uses: ./.github/workflows/sdk-compat.yml
+
+  all-checks:
+    name: All PR Checks
+    needs:
+      - changes
+      - code-quality
+      - typecheck
+      - webapp
+      - e2e-webapp
+      - packages
+      - internal
+      - e2e
+      - sdk-compat
+    if: always()
+    runs-on: warp-ubuntu-latest-x64-2x
+    steps:
+      - name: Verify all checks
+        run: |
+          if [[ "${{ contains(needs.*.result, 'failure') }}" == "true" ]]; then
+            echo "One or more checks failed"
+            exit 1
+          fi
+          if [[ "${{ contains(needs.*.result, 'cancelled') }}" == "true" ]]; then
+            echo "One or more checks were cancelled"
+            exit 1
+          fi
+          echo "All checks passed or were skipped due to path filters"

.github/workflows/preview-dispatch.yml

@@ -0,0 +1,76 @@
+name: 🌱 Preview environment dispatch
+
+# Opt-in per-PR preview environments
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, closed, labeled, unlabeled]
+
+# Serialize a PR's events so dispatches arrive in order. Cloud-side concurrency
+# collapses by branch but can't fix out-of-order arrival — e.g. a push racing a
+# close could cancel the in-flight destroy and leak the preview. One short API
+# call, so queuing is cheap; cancel-in-progress: false lets an in-flight
+# dispatch finish (GitHub keeps only the latest pending, the desired behavior).
+concurrency:
+  group: preview-dispatch-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+permissions: {}
+
+jobs:
+  dispatch:
+    name: Dispatch preview-deploy to cloud
+    runs-on: warp-ubuntu-latest-x64-2x
+    #   label added             -> create
+    #   new commit while labeled -> update
+    #   label removed / PR closed -> destroy
+    if: >-
+      github.event.pull_request.head.repo.full_name == github.repository &&
+      (
+        (github.event.action == 'labeled' && github.event.label.name == 'preview') ||
+        (github.event.action == 'unlabeled' && github.event.label.name == 'preview') ||
+        (
+          contains(github.event.pull_request.labels.*.name, 'preview') &&
+          contains(fromJSON('["opened","reopened","synchronize","closed"]'), github.event.action)
+        )
+      )
+    steps:
+      - name: Build dispatch payload
+        id: payload
+        env:
+          ACTION: ${{ github.event.action }}
+          BRANCH: ${{ github.event.pull_request.head.ref }}
+          COMMIT: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+          # Map the GitHub PR action to the cloud pipeline's lifecycle event.
+          case "$ACTION" in
+            labeled | opened | reopened) EVENT=opened ;;
+            synchronize) EVENT=synchronize ;;
+            unlabeled | closed) EVENT=closed ;;
+            *) echo "unexpected action: $ACTION" >&2; exit 1 ;;
+          esac
+          # jq --arg JSON-escapes every value, so a branch name containing
+          # quotes/braces can't break or inject into the client payload.
+          payload=$(jq -nc \
+            --arg b "$BRANCH" \
+            --arg c "$COMMIT" \
+            --arg e "$EVENT" \
+            '{branch_name: $b, commit: $c, pull_request_event: $e}')
+          {
+            echo "client_payload=$payload"
+            echo "summary=$EVENT for $BRANCH @ ${COMMIT:0:7}"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Log dispatch
+        env:
+          SUMMARY: ${{ steps.payload.outputs.summary }}
+        run: echo "Dispatching preview-deploy event ($SUMMARY)"
+
+      - name: Send repository_dispatch
+        uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v4.0.1
+        with:
+          token: ${{ secrets.CROSS_REPO_PAT }}
+          repository: triggerdotdev/cloud
+          event-type: preview-deploy
+          client-payload: ${{ steps.payload.outputs.client_payload }}

.github/workflows/preview-packages.yml

@@ -0,0 +1,83 @@
+name: 📦 Preview packages (pkg.pr.new)
+
+# Publishes installable preview builds of the public @trigger.dev/* packages
+# for every push to a branch, via https://pkg.pr.new. These are NOT published
+# to npm — pkg.pr.new serves them by commit SHA and drops install instructions
+# in a comment on the associated PR, e.g.
+#   npm i https://pkg.pr.new/@trigger.dev/sdk@<sha>
+#
+# Prerequisites:
+#   - The pkg.pr.new GitHub App must be installed on triggerdotdev/trigger.dev
+#     (https://github.com/apps/pkg-pr-new). Publishing fails until it is.
+#
+# Fork note: pkg.pr.new authenticates with a GitHub Actions OIDC token, which
+# GitHub does not issue to pull_request workflows from forks. This `push`
+# trigger therefore covers branches pushed to this repo (the core team), not
+# external fork PRs. Adding fork coverage would require a workflow_run two-stage
+# setup.
+
+on:
+  push:
+    branches-ignore:
+      - main
+      - changeset-release/main
+    paths:
+      - "package.json"
+      - "packages/**"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "turbo.json"
+      - ".github/workflows/preview-packages.yml"
+      - "scripts/stamp-preview-version.mjs"
+      - "scripts/updateVersion.ts"
+
+concurrency:
+  group: preview-packages-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  id-token: write # OIDC token used by pkg.pr.new to authenticate the publish
+
+jobs:
+  publish:
+    name: Build and publish previews
+    runs-on: warp-ubuntu-latest-x64-8x
+    if: github.repository == 'triggerdotdev/trigger.dev'
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          cache: "pnpm"
+
+      - name: 📥 Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: 📀 Generate Prisma client
+        run: pnpm run generate
+
+      # Stamp a unique 0.0.0-preview-<sha> version before building so it can't
+      # collide with real npm versions and so updateVersion.ts bakes it into the
+      # runtime VERSION constant. See scripts/stamp-preview-version.mjs.
+      - name: 🏷️ Stamp preview version
+        run: node scripts/stamp-preview-version.mjs
+        env:
+          GITHUB_SHA: ${{ github.sha }}
+
+      - name: 🔨 Build packages
+        run: pnpm run build --filter "@trigger.dev/*" --filter "trigger.dev"
+
+      - name: 🚀 Publish previews to pkg.pr.new
+        run: pnpm exec pkg-pr-new publish --pnpm --compact --commentWithSha './packages/*'

.github/workflows/publish-docs.yml

@@ -0,0 +1,36 @@
+name: 📚 Publish docs
+
+on:
+  push:
+    tags:
+      - "docs-release-*"
+
+# Only needs to move the docs-live ref; Mintlify's GitHub app deploys from it.
+permissions:
+  contents: write
+
+concurrency:
+  group: publish-docs
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: warp-ubuntu-latest-x64-2x
+    steps:
+      - name: 📥 Checkout tagged commit
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: 🔗 Check for broken links
+        working-directory: ./docs
+        run: npx mintlify@4.0.393 broken-links
+
+      - name: 🚀 Fast-forward docs-live to the tagged commit
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh api -X PATCH \
+            "repos/${{ github.repository }}/git/refs/heads/docs-live" \
+            -f sha="${{ github.sha }}" \
+            -F force=false

.github/workflows/publish-webapp.yml

@@ -0,0 +1,149 @@
+name: "🐳 Publish Webapp"
+
+permissions:
+  contents: read
+  packages: write
+  id-token: write
+  attestations: write
+
+on:
+  workflow_call:
+    inputs:
+      image_tag:
+        description: The image tag to publish
+        type: string
+        required: false
+        default: ""
+      image_registry:
+        description: The registry namespace to publish under (e.g. ghcr.io/<owner>)
+        type: string
+        required: false
+        default: ""
+    outputs:
+      version:
+        description: The published image tag
+        value: ${{ jobs.publish.outputs.version }}
+      short_sha:
+        description: Short commit SHA of the published build
+        value: ${{ jobs.publish.outputs.short_sha }}
+      image_repo:
+        description: The image repository the build was published to (without tag)
+        value: ${{ jobs.publish.outputs.image_repo }}
+      digest:
+        description: Multi-arch index digest (sha256:...) of the published image
+        value: ${{ jobs.publish.outputs.digest }}
+    secrets:
+      SENTRY_AUTH_TOKEN:
+        required: false
+
+jobs:
+  publish:
+    runs-on: warp-ubuntu-latest-x64-2x
+    env:
+      PRISMA_ENGINES_CHECKSUM_IGNORE_MISSING: 1
+    outputs:
+      version: ${{ steps.get_tag.outputs.tag }}
+      short_sha: ${{ steps.get_commit.outputs.sha_short }}
+      image_repo: ${{ steps.set_tags.outputs.image_repo }}
+      digest: ${{ steps.build_push.outputs.digest }}
+    steps:
+      - name: 🏭 Setup Depot CLI
+        uses: depot/setup-action@15c09a5f77a0840ad4bce955686522a257853461 # v1.7.1
+
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          submodules: recursive
+          persist-credentials: false
+
+      - name: "#️⃣ Get the image tag"
+        id: get_tag
+        uses: ./.github/actions/get-image-tag
+        with:
+          tag: ${{ inputs.image_tag }}
+
+      - name: 🔢 Get the commit hash
+        id: get_commit
+        run: |
+          echo "sha_short=$(echo "${GITHUB_SHA}" | cut -c1-7)" >> "$GITHUB_OUTPUT"
+
+      - name: 📛 Set the tags
+        id: set_tags
+        run: |
+          # The registry namespace is resolved by the caller (defaulting to
+          # ghcr.io/<owner>, overridable via the IMAGE_REGISTRY repository
+          # variable); the webapp image lives at <registry>/<repo-name>. A fork
+          # therefore publishes to its own package automatically.
+          image_tags=$REF_WITHOUT_TAG:${STEPS_GET_TAG_OUTPUTS_TAG}
+
+          if [[ "${STEPS_GET_TAG_OUTPUTS_TAG}" =~ ^v4\.[0-9]+\.[0-9]+$ ]]; then
+            image_tags=$image_tags,$REF_WITHOUT_TAG:v4,$REF_WITHOUT_TAG:latest
+          fi
+
+          # when pushing the mutable main tag, also push an immutable-by-convention
+          # full-commit-sha tag so a commit can be resolved to a specific digest
+          if [[ "${STEPS_GET_TAG_OUTPUTS_TAG}" == "main" ]]; then
+            image_tags=$image_tags,$REF_WITHOUT_TAG:${GITHUB_SHA}
+          fi
+
+          echo "image_tags=${image_tags}" >> "$GITHUB_OUTPUT"
+          echo "image_repo=${REF_WITHOUT_TAG}" >> "$GITHUB_OUTPUT"
+        env:
+          REF_WITHOUT_TAG: ${{ format('{0}/{1}', inputs.image_registry || vars.IMAGE_REGISTRY || format('ghcr.io/{0}', github.repository_owner), github.event.repository.name) }}
+          STEPS_GET_TAG_OUTPUTS_TAG: ${{ steps.get_tag.outputs.tag }}
+          STEPS_GET_TAG_OUTPUTS_IS_SEMVER: ${{ steps.get_tag.outputs.is_semver }}
+
+      - 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}"
+            fi
+            echo "BUILD_GIT_SHA=${GITHUB_SHA}"
+            echo "BUILD_GIT_REF_NAME=${GITHUB_REF_NAME}"
+            echo "BUILD_TIMESTAMP_SECONDS=$(date +%s)"
+            echo "BUILD_TIMESTAMP_RFC3339=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+          } >> "$GITHUB_OUTPUT"
+        env:
+          STEPS_GET_TAG_OUTPUTS_TAG: ${{ steps.get_tag.outputs.tag }}
+          STEPS_GET_TAG_OUTPUTS_IS_SEMVER: ${{ steps.get_tag.outputs.is_semver }}
+
+      - name: 🐙 Login to GitHub Container Registry
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: 🐳 Build image and push to GitHub Container Registry
+        id: build_push
+        uses: depot/build-push-action@98e78adca7817480b8185f474a400b451d74e287 # v1.18.0
+        with:
+          file: ./docker/Dockerfile
+          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 }}
+            BUILD_TIMESTAMP_RFC3339=${{ steps.set_build_info.outputs.BUILD_TIMESTAMP_RFC3339 }}
+            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 }}
+
+      - name: 🪪 Attest build provenance
+        # Image is already pushed by this point — don't fail releases (and the
+        # downstream publish-helm job) on a Sigstore/GHCR-referrer hiccup. Real
+        # config errors still surface as a step warning in the workflow run.
+        continue-on-error: true
+        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
+        with:
+          subject-name: ${{ steps.set_tags.outputs.image_repo }}
+          subject-digest: ${{ steps.build_push.outputs.digest }}
+          push-to-registry: true

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

@@ -0,0 +1,103 @@
+name: "⚒️ Publish Worker (v4)"
+
+on:
+  workflow_call:
+    inputs:
+      image_tag:
+        description: The image tag to publish
+        type: string
+        required: false
+        default: ""
+      image_registry:
+        description: The registry namespace to publish under (e.g. ghcr.io/<owner>)
+        type: string
+        required: false
+        default: ""
+  push:
+    tags:
+      - "re2-test-*"
+      - "re2-prod-*"
+
+permissions:
+  id-token: write
+  packages: write
+  contents: read
+
+jobs:
+  # check-branch:
+  #   runs-on: warp-ubuntu-latest-x64-2x
+  #   steps:
+  #     - name: Fail if re2-prod-* is pushed from a non-main branch
+  #       if: startsWith(github.ref_name, 're2-prod-') && github.base_ref != 'main'
+  #       run: |
+  #         echo "🚫 re2-prod-* tags can only be pushed from the main branch."
+  #         exit 1
+  build:
+    # needs: check-branch
+    strategy:
+      matrix:
+        package: [supervisor]
+    runs-on: warp-ubuntu-latest-x64-2x
+    env:
+      DOCKER_BUILDKIT: "1"
+    steps:
+      - name: 🏭 Setup Depot CLI
+        uses: depot/setup-action@15c09a5f77a0840ad4bce955686522a257853461 # v1.7.1
+
+      - name: ⬇️ Checkout git repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: 📦 Get image repo
+        id: get_repository
+        env:
+          PACKAGE: ${{ matrix.package }}
+        run: |
+          if [[ "$PACKAGE" == *-provider ]]; then
+            repo="provider/${PACKAGE%-provider}"
+          else
+            repo="$PACKAGE"
+          fi
+          echo "repo=${repo}" >> "$GITHUB_OUTPUT"
+
+      - name: "#️⃣ Get image tag"
+        id: get_tag
+        uses: ./.github/actions/get-image-tag
+        with:
+          tag: ${{ inputs.image_tag }}
+
+      - name: 📛 Set tags to push
+        id: set_tags
+        run: |
+          # Resolved by the caller when invoked from publish.yml; falls back to the
+          # IMAGE_REGISTRY repository variable (or ghcr.io/<owner>) for the direct
+          # push triggers above, so a fork publishes to its own namespace.
+          ref_without_tag=${IMAGE_REGISTRY}/${STEPS_GET_REPOSITORY_OUTPUTS_REPO}
+          image_tags=$ref_without_tag:${STEPS_GET_TAG_OUTPUTS_TAG}
+
+          if [[ "${STEPS_GET_TAG_OUTPUTS_TAG}" =~ ^v4\.[0-9]+\.[0-9]+$ ]]; then
+            image_tags=$image_tags,$ref_without_tag:v4,$ref_without_tag:latest
+          fi
+
+          echo "image_tags=${image_tags}" >> "$GITHUB_OUTPUT"
+        env:
+          IMAGE_REGISTRY: ${{ inputs.image_registry || vars.IMAGE_REGISTRY || format('ghcr.io/{0}', github.repository_owner) }}
+          STEPS_GET_REPOSITORY_OUTPUTS_REPO: ${{ steps.get_repository.outputs.repo }}
+          STEPS_GET_TAG_OUTPUTS_TAG: ${{ steps.get_tag.outputs.tag }}
+          STEPS_GET_TAG_OUTPUTS_IS_SEMVER: ${{ steps.get_tag.outputs.is_semver }}
+
+      - name: 🐙 Login to GitHub Container Registry
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: 🐳 Build image and push to GitHub Container Registry
+        uses: depot/build-push-action@98e78adca7817480b8185f474a400b451d74e287 # v1.18.0
+        with:
+          file: ./apps/${{ matrix.package }}/Containerfile
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.set_tags.outputs.image_tags }}
+          push: true

.github/workflows/publish.yml

@@ -1,23 +1,42 @@
 name: 🚀 Publish Trigger.dev Docker
 
 on:
+  workflow_dispatch:
+  workflow_call:
+    inputs:
+      image_tag:
+        description: The image tag to publish
+        required: true
+        type: string
+    secrets:
+      DOCKERHUB_USERNAME:
+        required: false
+      DOCKERHUB_TOKEN:
+        required: false
+      SENTRY_AUTH_TOKEN:
+        required: false
+      CROSS_REPO_PAT:
+        required: false
   push:
     branches:
       - main
-      - improvements/*
     tags:
       - "v.docker.*"
+      - "build-*"
     paths:
+      - ".github/actions/**/*.yml"
       - ".github/workflows/publish.yml"
+      - ".github/workflows/typecheck.yml"
+      - ".github/workflows/unit-tests.yml"
+      - ".github/workflows/e2e.yml"
+      - ".github/workflows/publish-webapp.yml"
       - "packages/**"
       - "!packages/**/*.md"
       - "!packages/**/*.eslintrc"
+      - "internal-packages/**"
       - "apps/**"
       - "!apps/**/*.md"
       - "!apps/**/*.eslintrc"
-      - "integrations/**"
-      - "!integrations/**/*.md"
-      - "!integrations/**/*.eslintrc"
       - "pnpm-lock.yaml"
       - "pnpm-workspace.yaml"
       - "turbo.json"
@@ -26,8 +45,6 @@ on:
       - "tests/**"
 
 permissions:
-  id-token: write
-  packages: write
   contents: read
 
 concurrency:
@@ -39,83 +56,94 @@ env:
 jobs:
   typecheck:
     uses: ./.github/workflows/typecheck.yml
-    secrets: inherit
 
   units:
     uses: ./.github/workflows/unit-tests.yml
-    secrets: inherit
+    secrets:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
 
-  e2e:
-    uses: ./.github/workflows/e2e.yml
-    secrets: inherit
+  publish-webapp:
+    needs: [typecheck]
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+      attestations: write
+    uses: ./.github/workflows/publish-webapp.yml
+    secrets:
+      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+    with:
+      image_tag: ${{ inputs.image_tag }}
+      # Target registry namespace. Defaults to ghcr.io/<owner> so a fork publishes
+      # to its own namespace; set the IMAGE_REGISTRY repository variable to override.
+      image_registry: ${{ vars.IMAGE_REGISTRY || format('ghcr.io/{0}', github.repository_owner) }}
 
-  publish:
-    needs: [typecheck, units, e2e]
-    runs-on: buildjet-4vcpu-ubuntu-2204
-    outputs:
-      version: ${{ steps.get_version.outputs.version }}
-      short_sha: ${{ steps.get_commit.outputs.sha_short }}
+  publish-worker-v4:
+    needs: [typecheck]
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+    uses: ./.github/workflows/publish-worker-v4.yml
+    with:
+      image_tag: ${{ inputs.image_tag }}
+      image_registry: ${{ vars.IMAGE_REGISTRY || format('ghcr.io/{0}', github.repository_owner) }}
+
+  # OS-level CVE scan of the image just published above. Report-only (writes to
+  # the run summary); runs alongside the worker publishes and never blocks them.
+  scan-webapp:
+    needs: [publish-webapp]
+    permissions:
+      contents: read
+      packages: read # pull the just-published image from GHCR
+    uses: ./.github/workflows/trivy-image-webapp.yml
+    with:
+      image-ref: ${{ needs.publish-webapp.outputs.image_repo }}:${{ needs.publish-webapp.outputs.version }}
+
+  # Announce the freshly published mutable `main` webapp image to subscriber
+  # repos via repository_dispatch, handing them a digest-pinned ref to build or
+  # deploy from. The repo, ref prefix, and dispatch target all default to the
+  # canonical values and can be overridden by repository variables.
+  #
+  # `push` only: release builds reach publish.yml via workflow_call (from
+  # release.yml) with an explicit image_tag while github.ref_name is still
+  # `main`, so gate on the event to avoid dispatching — and failing on the
+  # absent CROSS_REPO_PAT — during a release.
+  dispatch-main-image:
+    name: 📣 Dispatch main image
+    needs: [publish-webapp]
+    if: github.repository == (vars.MAIN_IMAGE_DISPATCH_REPO || 'triggerdotdev/trigger.dev') && github.event_name == 'push' && startsWith(github.ref_name, vars.MAIN_IMAGE_DISPATCH_REF_PREFIX || 'main')
+    runs-on: warp-ubuntu-latest-x64-2x
+    permissions: {}
     steps:
-      - name: 🐳 Login to Docker Hub
-        uses: docker/login-action@v2
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-      - name: ⬇️ Checkout repo
-        uses: actions/checkout@v3
-
-      - name: 🆚 Get the version
-        id: get_version
+      - name: Build dispatch payload
+        id: payload
+        env:
+          IMAGE_REPO: ${{ needs.publish-webapp.outputs.image_repo }}
+          DIGEST: ${{ needs.publish-webapp.outputs.digest }}
+          COMMIT: ${{ github.sha }}
         run: |
-          IMAGE_TAG="${GITHUB_REF#refs/tags/}"
-          if [[ $GITHUB_REF == refs/tags/* ]]; then
-            if [[ $IMAGE_TAG == v.docker.* ]]; then
-              ORIGINAL_VERSION="${IMAGE_TAG#v.docker.}"
-              IMAGE_TAG="v${ORIGINAL_VERSION}"
-            fi
-            echo "IMAGE_TAG=${IMAGE_TAG}"
-          elif [[ $GITHUB_REF == refs/heads/improvements/* ]]; then
-            ORIGINAL_VERSION="${GITHUB_REF#refs/heads/improvements/}"
-            IMAGE_TAG="${ORIGINAL_VERSION}.rc"
-            echo "IMAGE_TAG=${IMAGE_TAG}"
-          elif [[ $GITHUB_REF == refs/heads/* ]]; then
-            IMAGE_TAG="${GITHUB_REF#refs/heads/}"
-            echo "IMAGE_TAG=${IMAGE_TAG}"
-          else
-            echo "Invalid reference: ${GITHUB_REF}"
+          set -euo pipefail
+          # Pin to the exact multi-arch index just pushed so subscribers resolve a
+          # single immutable artifact rather than chasing the moving `main` tag.
+          if [[ -z "${DIGEST}" ]]; then
+            echo "::error::publish-webapp produced no image digest; refusing to dispatch"
             exit 1
           fi
-          echo "::set-output name=version::${IMAGE_TAG}"
-      - name: 🔢 Get the commit hash
-        id: get_commit
-        run: |
-          echo ::set-output name=sha_short::$(echo ${{ github.sha }} | cut -c1-7)
+          image="${IMAGE_REPO}@${DIGEST}"
+          # jq --arg JSON-escapes every value, so the ref/commit can't break out of
+          # or inject into the client payload.
+          payload=$(jq -nc \
+            --arg img "$image" \
+            --arg c "$COMMIT" \
+            '{image: $img, commit: $c}')
+          echo "client_payload=$payload" >> "$GITHUB_OUTPUT"
 
-      - name: 🐳 Build Docker Image
-        run: |
-          docker build -t release_build_image -f ./docker/Dockerfile .
-
-      - name: 🐙 Login to GitHub Container Registry
-        uses: docker/login-action@v2
+      - name: Send repository_dispatch
+        uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v4.0.1
         with:
-          registry: ghcr.io
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: 🐙 Push to GitHub Container Registry
-        run: |
-          docker tag release_build_image $REGISTRY/$REPOSITORY:$IMAGE_TAG
-          docker push $REGISTRY/$REPOSITORY:$IMAGE_TAG
-        env:
-          REGISTRY: ghcr.io/triggerdotdev
-          REPOSITORY: trigger.dev
-          IMAGE_TAG: ${{ steps.get_version.outputs.version }}
-
-      - name: 🐙 Push 'latest' to GitHub Container Registry
-        if: startsWith(github.ref, 'refs/tags/')
-        run: |
-          docker tag release_build_image $REGISTRY/$REPOSITORY:latest
-          docker push $REGISTRY/$REPOSITORY:latest
-        env:
-          REGISTRY: ghcr.io/triggerdotdev
-          REPOSITORY: trigger.dev
+          token: ${{ secrets.CROSS_REPO_PAT }}
+          repository: ${{ vars.MAIN_IMAGE_DISPATCH_TARGET || 'triggerdotdev/cloud' }}
+          event-type: main-image-published
+          client-payload: ${{ steps.payload.outputs.client_payload }}

.github/workflows/release-helm.yml

@@ -0,0 +1,163 @@
+name: 🧭 Helm Chart Release
+
+on:
+  push:
+    tags:
+      - "helm-v*"
+  workflow_call:
+    inputs:
+      chart_version:
+        description: "Chart version to release"
+        required: true
+        type: string
+  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: warp-ubuntu-latest-x64-2x
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Helm
+        uses: azure/setup-helm@9bc31f4ebc9c6b171d7bfbaa5d006ae7abdb4310 # v5.0.1
+        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@sha256:85dbef6b4b312b99133decc9c6fc9495e9fc5f92293d4ff3b7e1b30f5611823c
+        with:
+          entrypoint: "/kubeconform"
+          args: "-summary -output json ./helm-output"
+
+  release:
+    needs: lint-and-test
+    # Set the ENABLE_HELM_PRERELEASE repository variable to 'false' to turn off
+    # publishing the chart to GHCR — e.g. forks/mirrors that lack write_package
+    # on the owner's charts namespace. Defaults to enabled; the lint-and-test
+    # job above always runs regardless.
+    if: ${{ vars.ENABLE_HELM_PRERELEASE != 'false' }}
+    runs-on: warp-ubuntu-latest-x64-2x
+    permissions:
+      contents: write # for gh-release
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Helm
+        uses: azure/setup-helm@9bc31f4ebc9c6b171d7bfbaa5d006ae7abdb4310 # v5.0.1
+        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@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract version from tag or input
+        id: version
+        run: |
+          if [ -n "${INPUTS_CHART_VERSION}" ]; then
+            VERSION="${INPUTS_CHART_VERSION}"
+          else
+            VERSION="${GITHUB_REF_NAME}"
+            VERSION="${VERSION#helm-v}"
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Releasing version: $VERSION"
+        env:
+          INPUTS_CHART_VERSION: ${{ inputs.chart_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."
+        env:
+          STEPS_VERSION_OUTPUTS_VERSION: ${{ steps.version.outputs.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"
+        env:
+          STEPS_VERSION_OUTPUTS_VERSION: ${{ steps.version.outputs.version }}
+
+      - name: Create GitHub Release
+        id: release
+        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v3.0.1
+        with:
+          tag_name: helm-v${{ steps.version.outputs.version }}
+          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,72 +1,343 @@
 name: 🦋 Changesets Release
 
 on:
-  push:
+  pull_request:
+    types: [closed]
     branches:
       - main
-    paths-ignore:
-      - "**.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 }}
+  cancel-in-progress: false
 
 jobs:
-  release:
-    name: 🦋 Changesets Release
-    runs-on: buildjet-4vcpu-ubuntu-2204
+  show-release-summary:
+    name: 📋 Release Summary
+    runs-on: ubuntu-latest
+    permissions: {}
     if: |
-      github.repository == 'triggerdotdev/trigger.dev'
-    outputs:
-      published_packages: ${{ steps.changesets.outputs.publishedPackages }}
-      published: ${{ steps.changesets.outputs.published }}
+      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: 🛑 Cancel Previous Runs
-        uses: styfle/cancel-workflow-action@0.11.0
+      - name: Show release summary
+        env:
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          echo "$PR_BODY" | sed -n '/^# Releases/,$p' >> "$GITHUB_STEP_SUMMARY"
 
-      - name: ⬇️ Checkout repo
-        uses: actions/checkout@v3
+  release:
+    name: 🚀 Release npm packages
+    runs-on: ubuntu-latest # this cannot run on non-GH runner
+    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 }}
+      is_prerelease: ${{ steps.get_version.outputs.is_prerelease }}
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 # zizmor: ignore[artipacked] needs persisted git creds for tag push; no artifact upload here so no leak path
         with:
           fetch-depth: 0
+          ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.ref || github.sha }}
 
-      - name: ⎔ Setup pnpm
-        uses: pnpm/action-setup@v2.2.4
-        with:
-          version: 7.18
+      - 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
+        env:
+          GITHUB_EVENT_INPUTS_REF: ${{ github.event.inputs.ref }}
 
-      - name: ⎔ Setup node
-        uses: buildjet/setup-node@v3
+      - name: Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
         with:
-          node-version: 18
+          version: 10.33.2
+
+      - name: Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
           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: 🔎 Type check
-        run: pnpm run typecheck
+      - name: Build
+        run: pnpm run build --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
+      - name: Type check
+        run: pnpm run typecheck --filter "@trigger.dev/*" --filter "trigger.dev"
 
-        # 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
+      - name: Publish
         id: changesets
-        uses: changesets/action@v1
+        uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1.9.0
         with:
-          version: pnpm run changeset:version
-          commit: "chore: Update version for release"
-          title: "chore: Update version for release"
           publish: pnpm run changeset:release
           createGithubReleases: false
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - 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"
+          # Any semver with a hyphen is a prerelease (e.g. 4.5.0-rc.0, 0.0.0-snapshot-...)
+          if [[ "${package_version}" == *-* ]]; then
+            echo "is_prerelease=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is_prerelease=false" >> "$GITHUB_OUTPUT"
+          fi
+        env:
+          STEPS_CHANGESETS_OUTPUTS_PUBLISHEDPACKAGES: ${{ steps.changesets.outputs.publishedPackages }}
+
+      - name: Create unified GitHub release
+        if: steps.changesets.outputs.published == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_PR_BODY: ${{ github.event.pull_request.body }}
+          STEPS_GET_VERSION_OUTPUTS_PACKAGE_VERSION: ${{ steps.get_version.outputs.package_version }}
+          STEPS_GET_VERSION_OUTPUTS_IS_PRERELEASE: ${{ steps.get_version.outputs.is_prerelease }}
+        run: |
+          VERSION="${STEPS_GET_VERSION_OUTPUTS_PACKAGE_VERSION}"
+
+          # On the pull_request merge event RELEASE_PR_BODY is the merged "Version Packages"
+          # PR body, which holds the changelog. On a workflow_dispatch re-run (the recovery
+          # path after a failed merge-triggered run) there is no pull_request context, so it's
+          # empty. Fall back to the body of the most recently merged changeset-release/main PR
+          # so the "What's changed" section is still populated.
+          if [ -z "${RELEASE_PR_BODY}" ]; then
+            echo "RELEASE_PR_BODY is empty (workflow_dispatch re-run); fetching merged changeset-release/main PR body"
+            RELEASE_PR_BODY="$(gh pr list --repo triggerdotdev/trigger.dev \
+              --head changeset-release/main --state merged \
+              --json body,mergedAt --limit 10 \
+              -q 'sort_by(.mergedAt) | reverse | .[0].body')"
+          fi
+          export RELEASE_PR_BODY
+
+          node scripts/generate-github-release.mjs "$VERSION" > /tmp/release-body.md
+          PRERELEASE_FLAG=""
+          if [ "${STEPS_GET_VERSION_OUTPUTS_IS_PRERELEASE}" = "true" ]; then
+            PRERELEASE_FLAG="--prerelease"
+          fi
+          gh release create "v${VERSION}" \
+            --title "trigger.dev v${VERSION}" \
+            --notes-file /tmp/release-body.md \
+            --target main \
+            $PRERELEASE_FLAG
+
+      - 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}"
+        env:
+          STEPS_GET_VERSION_OUTPUTS_PACKAGE_VERSION: ${{ steps.get_version.outputs.package_version }}
+
+      - name: Create and push Helm chart tag
+        if: steps.changesets.outputs.published == 'true'
+        run: |
+          set -e
+          git tag "helm-v${STEPS_GET_VERSION_OUTPUTS_PACKAGE_VERSION}"
+          git push origin "helm-v${STEPS_GET_VERSION_OUTPUTS_PACKAGE_VERSION}"
+        env:
+          STEPS_GET_VERSION_OUTPUTS_PACKAGE_VERSION: ${{ 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'
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+      attestations: write
+    uses: ./.github/workflows/publish.yml
+    secrets:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+    with:
+      image_tag: v${{ needs.release.outputs.published_package_version }}
+
+  # Trigger Helm chart release directly via workflow_call (same GITHUB_TOKEN
+  # limitation as the Docker path). Runs after Docker images are published so
+  # the chart never references images that don't exist yet.
+  publish-helm:
+    name: 🧭 Publish Helm chart
+    needs: [release, publish-docker]
+    if: needs.release.outputs.published == 'true'
+    permissions:
+      contents: write
+      packages: write
+    uses: ./.github/workflows/release-helm.yml
+    with:
+      chart_version: ${{ needs.release.outputs.published_package_version }}
+
+  # After Docker images are published, update the GitHub release with the exact GHCR tag URL.
+  # The GHCR package version ID is only known after the image is pushed, so we query for it here.
+  update-release:
+    name: 🔗 Update release Docker link
+    needs: [release, publish-docker]
+    if: needs.release.outputs.published == 'true'
+    runs-on: warp-ubuntu-latest-x64-2x
+    permissions:
+      contents: write
+      packages: read
+    steps:
+      - name: Update GitHub release with Docker image link
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NEEDS_RELEASE_OUTPUTS_PUBLISHED_PACKAGE_VERSION: ${{ needs.release.outputs.published_package_version }}
+        run: |
+          set -e
+          VERSION="${NEEDS_RELEASE_OUTPUTS_PUBLISHED_PACKAGE_VERSION}"
+          TAG="v${VERSION}"
+
+          # Query GHCR for the version ID matching this tag
+          VERSION_ID=$(gh api --paginate -H "Accept: application/vnd.github+json" \
+            /orgs/triggerdotdev/packages/container/trigger.dev/versions \
+            --jq ".[] | select(.metadata.container.tags[] == \"${TAG}\") | .id" \
+            | head -1)
+
+          if [ -z "$VERSION_ID" ]; then
+            echo "Warning: Could not find GHCR version ID for tag ${TAG}, skipping update"
+            exit 0
+          fi
+
+          DOCKER_URL="https://github.com/triggerdotdev/trigger.dev/pkgs/container/trigger.dev/${VERSION_ID}?tag=${TAG}"
+          GENERIC_URL="https://github.com/triggerdotdev/trigger.dev/pkgs/container/trigger.dev"
+
+          # Get current release body and replace the generic link with the tag-specific one.
+          # Use word boundary after GENERIC_URL (closing paren) to avoid matching URLs that
+          # already have a version ID appended (idempotent on re-runs).
+          gh release view "${TAG}" --repo triggerdotdev/trigger.dev --json body --jq '.body' > /tmp/release-body.md
+          sed -i "s|${GENERIC_URL})|${DOCKER_URL})|g" /tmp/release-body.md
+
+          gh release edit "${TAG}" --repo triggerdotdev/trigger.dev --notes-file /tmp/release-body.md
+
+  # Dispatch changelog entry creation to the marketing site repo.
+  # Runs after update-release so the GitHub release body already has the exact Docker image URL.
+  dispatch-changelog:
+    name: 📝 Dispatch changelog PR
+    needs: [release, update-release]
+    if: needs.release.outputs.published == 'true' && needs.release.outputs.is_prerelease != 'true'
+    runs-on: warp-ubuntu-latest-x64-2x
+    permissions: {}
+    steps:
+      - uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v4.0.1
+        with:
+          token: ${{ secrets.CROSS_REPO_PAT }}
+          repository: triggerdotdev/trigger.dev-site-v3
+          event-type: new-release
+          client-payload: '{"version": "${{ needs.release.outputs.published_package_version }}"}'
+
+  # The prerelease job needs to be on the same workflow file due to a limitation related to how npm verifies OIDC claims.
+  prerelease:
+    name: 🧪 Prerelease
+    runs-on: ubuntu-latest # this cannot run on non-GH runner
+    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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.inputs.ref }}
+          persist-credentials: false
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          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: Exit changeset pre mode (if active)
+        run: |
+          if [ -f .changeset/pre.json ]; then
+            echo "Repo is in changeset pre mode; exiting so snapshot release can run"
+            pnpm exec changeset pre exit
+          fi
+
+      - name: Snapshot version
+        run: pnpm exec changeset version --snapshot "${GITHUB_EVENT_INPUTS_PRERELEASE_TAG}"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_EVENT_INPUTS_PRERELEASE_TAG: ${{ github.event.inputs.prerelease_tag }}
+
+      - 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_EVENT_INPUTS_PRERELEASE_TAG: ${{ github.event.inputs.prerelease_tag }}

.github/workflows/sdk-compat.yml

@@ -0,0 +1,182 @@
+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: [warp-ubuntu-latest-x64-4x]
+        node: ["20.20", "22.23", "24.18", "26.4"]
+
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        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: warp-ubuntu-latest-x64-4x
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          cache: "pnpm"
+
+      - name: 🥟 Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        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: warp-ubuntu-latest-x64-4x
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          cache: "pnpm"
+
+      - name: 🦕 Setup Deno
+        uses: denoland/setup-deno@667a34cdef165d8d2b2e98dde39547c9daac7282 # v2.0.4
+        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: warp-ubuntu-latest-x64-4x
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          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/trivy-image-webapp.yml

@@ -0,0 +1,75 @@
+name: Trivy Image Scan (webapp)
+
+# OS-level CVE scan of a published webapp image. Called by the publish pipeline
+# (publish.yml) to scan each build right after it's pushed to GHCR — so every
+# main build and every release is scanned, not rebuilt. Also runnable ad-hoc
+# via workflow_dispatch against any image ref.
+#
+# Report-only: writes a table to the run summary. No SARIF upload, no gate.
+# Library/dependency CVEs are covered by Dependabot, so this is restricted to
+# OS packages (`vuln-type: os`) to avoid double-reporting.
+
+on:
+  workflow_call:
+    inputs:
+      image-ref:
+        description: "Full image ref to scan (e.g. ghcr.io/triggerdotdev/trigger.dev:main)"
+        type: string
+        required: true
+  workflow_dispatch:
+    inputs:
+      image-ref:
+        description: "Full image ref to scan"
+        type: string
+        required: false
+        default: "ghcr.io/triggerdotdev/trigger.dev:main"
+
+permissions: {}
+
+concurrency:
+  group: trivy-image-webapp-${{ inputs.image-ref }}
+  cancel-in-progress: true
+
+jobs:
+  scan:
+    name: Scan
+    runs-on: warp-ubuntu-latest-x64-2x
+    permissions:
+      contents: read
+      packages: read # pull the image from GHCR
+    steps:
+      # Authenticate to GHCR so the scan also works for private images
+      # (GITHUB_TOKEN isn't forwarded to Docker automatically). Harmless for
+      # public images. Pairs with the packages: read permission above.
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Run Trivy image scan
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
+        with:
+          scan-type: image
+          image-ref: ${{ inputs.image-ref }}
+          # vuln-type maps to --pkg-types: OS packages only (library deps are
+          # Dependabot's job). ignore-unfixed drops vulns with no patch yet.
+          vuln-type: os
+          ignore-unfixed: true
+          severity: HIGH,CRITICAL
+          format: table
+          output: trivy-image-webapp.txt
+
+      - name: Job summary
+        if: always()
+        env:
+          IMAGE_REF: ${{ inputs.image-ref }}
+        run: |
+          {
+            echo "## Trivy Image Scan (webapp) — \`${IMAGE_REF}\`"
+            echo '```'
+            # GitHub step summary is capped at 1 MiB; truncate large reports.
+            head -c 900000 trivy-image-webapp.txt 2>/dev/null || echo "(no report produced)"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/typecheck.yml

@@ -1,25 +1,31 @@
 name: "ʦ TypeScript"
+
 on:
   workflow_call:
+
+permissions:
+  contents: read
+
 jobs:
   typecheck:
-    runs-on: buildjet-4vcpu-ubuntu-2204
+    runs-on: warp-ubuntu-latest-x64-16x
 
     steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: ⎔ Setup pnpm
-        uses: pnpm/action-setup@v2.2.4
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
         with:
-          version: 7.18
+          version: 10.33.2
 
       - name: ⎔ Setup node
-        uses: buildjet/setup-node@v3
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: 18
+          node-version: 22.23.1
           cache: "pnpm"
 
       - name: 📥 Download deps
@@ -29,4 +35,9 @@ jobs:
         run: pnpm run generate
 
       - name: 🔎 Type check
-        run: pnpm run typecheck --filter webapp
+        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,146 @@
+name: "🧪 Unit Tests: Internal"
+
+permissions:
+  contents: read
+
+on:
+  workflow_call:
+    secrets:
+      DOCKERHUB_USERNAME:
+        required: false
+      DOCKERHUB_TOKEN:
+        required: false
+
+jobs:
+  unitTests:
+    name: "🧪 Unit Tests: Internal"
+    # Single big machine instead of a 12-job matrix: the internal suites are serial
+    # (fileParallelism: false) and container-wait-bound, so 12 in-machine shard processes
+    # fit comfortably in 32 vCPUs while paying the setup cost (install, prisma generate,
+    # image pulls) once instead of 12 times.
+    runs-on: warp-ubuntu-latest-x64-32x
+    env:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      SHARD_TOTAL: 12
+    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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          cache: "pnpm"
+
+      # ..to avoid rate limits when pulling images
+      - name: 🐳 Login to DockerHub
+        if: ${{ env.DOCKERHUB_USERNAME }}
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        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: |
+          # Retry each pull - DockerHub registry timeouts are a recurring transient CI flake.
+          pull() {
+            for attempt in 1 2 3; do
+              docker pull "$1" && return 0
+              echo "::warning::docker pull $1 failed (attempt ${attempt}/3); retrying in 10s"
+              sleep 10
+            done
+            echo "::error::docker pull $1 failed after 3 attempts"
+            return 1
+          }
+          echo "Pre-pulling Docker images with authenticated session..."
+          pull postgres:14
+          pull postgres:17 # for the heterogeneous PG14/17 test fixture gate (heteroPostgresTest)
+          pull clickhouse/clickhouse-server:26.2.19.43-alpine@sha256:c6ad6a7eb2fb5999df3adfb8b69a0c7222c68fa9b8f6b04a088564ebbc959251
+          pull redis:7.2
+          pull testcontainers/ryuk:0.14.0
+          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: 🏗️ Build test dependencies
+        # Build once up-front so the parallel shard runs below (turbo --only) never race
+        # to build or cache-restore the same outputs concurrently.
+        run: pnpm exec turbo run build --filter "@internal/*..."
+
+      - name: 🧪 Run Internal Unit Tests (${{ env.SHARD_TOTAL }} in-machine shards)
+        run: |
+          # Same shard partitioning as the old 12-job matrix (DurationShardingSequencer
+          # keys off --shard=i/N), but as parallel local processes. --only skips the
+          # ^build dependency handled by the step above.
+          status=0
+          declare -a pids
+          for i in $(seq 1 "$SHARD_TOTAL"); do
+            pnpm exec turbo run test --only --concurrency=1 --filter "@internal/*" -- \
+              --run --reporter=default --reporter=blob --shard="$i/$SHARD_TOTAL" --passWithNoTests \
+              > "/tmp/internal-shard-$i.log" 2>&1 &
+            pids[i]=$!
+          done
+          for i in $(seq 1 "$SHARD_TOTAL"); do
+            if ! wait "${pids[i]}"; then
+              status=1
+              echo "::error::internal unit test shard $i/$SHARD_TOTAL failed"
+            fi
+            echo "::group::🧪 shard $i/$SHARD_TOTAL"
+            cat "/tmp/internal-shard-$i.log"
+            echo "::endgroup::"
+          done
+          exit "$status"
+
+      - 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: 📊 Merge reports
+        if: ${{ !cancelled() }}
+        run: pnpm dlx vitest@4.1.7 run --merge-reports --pass-with-no-tests

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

@@ -0,0 +1,160 @@
+name: "🧪 Unit Tests: Packages"
+
+permissions:
+  contents: read
+
+on:
+  workflow_call:
+    secrets:
+      DOCKERHUB_USERNAME:
+        required: false
+      DOCKERHUB_TOKEN:
+        required: false
+
+jobs:
+  unitTests:
+    name: "🧪 Unit Tests: Packages"
+    runs-on: warp-ubuntu-latest-x64-4x
+    strategy:
+      # one flaky shard shouldn't cancel its siblings - lets us re-run only the failed shard
+      fail-fast: false
+      matrix:
+        shardIndex: [1, 2, 3]
+        shardTotal: [3]
+    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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          cache: "pnpm"
+
+      # ..to avoid rate limits when pulling images
+      - name: 🐳 Login to DockerHub
+        if: ${{ env.DOCKERHUB_USERNAME }}
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        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: |
+          # Retry each pull - DockerHub registry timeouts are a recurring transient CI flake.
+          pull() {
+            for attempt in 1 2 3; do
+              docker pull "$1" && return 0
+              echo "::warning::docker pull $1 failed (attempt ${attempt}/3); retrying in 10s"
+              sleep 10
+            done
+            echo "::error::docker pull $1 failed after 3 attempts"
+            return 1
+          }
+          echo "Pre-pulling Docker images with authenticated session..."
+          pull postgres:14
+          pull clickhouse/clickhouse-server:26.2.19.43-alpine@sha256:c6ad6a7eb2fb5999df3adfb8b69a0c7222c68fa9b8f6b04a088564ebbc959251
+          pull redis:7.2
+          pull testcontainers/ryuk:0.14.0
+          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 }} --passWithNoTests
+
+      - 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@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        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: warp-ubuntu-latest-x64-2x
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          # no cache enabled, we're not installing deps
+
+      - name: Download blob reports from GitHub Actions Artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          path: .vitest-reports
+          pattern: packages-blob-report-*
+          merge-multiple: true
+
+      - name: Merge reports
+        run: pnpm dlx vitest@4.1.7 run --merge-reports --pass-with-no-tests

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

@@ -0,0 +1,174 @@
+name: "🧪 Unit Tests: Webapp"
+
+permissions:
+  contents: read
+
+on:
+  workflow_call:
+    secrets:
+      DOCKERHUB_USERNAME:
+        required: false
+      DOCKERHUB_TOKEN:
+        required: false
+
+jobs:
+  unitTests:
+    name: "🧪 Unit Tests: Webapp"
+    # 10 shards on 16x machines: webapp test throughput is limited per-machine (one
+    # docker daemon + disk absorbing all the per-file Postgres/ClickHouse container
+    # spin-up), so many machines beats few big ones - fewer/bigger (3x32) measured
+    # SLOWER than 10x8. The 16x (vs 8x) gives the fork pool the CPU headroom the 8x
+    # runners lacked. Setup overhead per machine is ~1 min on warm runners.
+    runs-on: warp-ubuntu-latest-x64-16x
+    strategy:
+      # one flaky shard shouldn't cancel its siblings - lets us re-run only the failed shard
+      fail-fast: false
+      matrix:
+        shardIndex: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
+        shardTotal: [12]
+    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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          cache: "pnpm"
+
+      # ..to avoid rate limits when pulling images
+      - name: 🐳 Login to DockerHub
+        if: ${{ env.DOCKERHUB_USERNAME }}
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        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: |
+          # Retry each pull - DockerHub registry timeouts are a recurring transient CI flake.
+          pull() {
+            for attempt in 1 2 3; do
+              docker pull "$1" && return 0
+              echo "::warning::docker pull $1 failed (attempt ${attempt}/3); retrying in 10s"
+              sleep 10
+            done
+            echo "::error::docker pull $1 failed after 3 attempts"
+            return 1
+          }
+          echo "Pre-pulling Docker images with authenticated session..."
+          pull postgres:14
+          pull clickhouse/clickhouse-server:26.2.19.43-alpine@sha256:c6ad6a7eb2fb5999df3adfb8b69a0c7222c68fa9b8f6b04a088564ebbc959251
+          pull redis:7.2
+          pull testcontainers/ryuk:0.14.0
+          pull electricsql/electric:1.2.4
+          pull minio/minio:latest
+          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 }} --passWithNoTests
+        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@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        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: warp-ubuntu-latest-x64-2x
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22.23.1
+          # no cache enabled, we're not installing deps
+
+      - name: Download blob reports from GitHub Actions Artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          path: .vitest-reports
+          pattern: webapp-blob-report-*
+          merge-multiple: true
+
+      - name: Merge reports
+        run: pnpm dlx vitest@4.1.7 run --merge-reports --pass-with-no-tests

.github/workflows/unit-tests.yml

@@ -1,30 +1,34 @@
 name: "🧪 Unit Tests"
+
+permissions:
+  contents: read
+
 on:
   workflow_call:
+    secrets:
+      DOCKERHUB_USERNAME:
+        required: false
+      DOCKERHUB_TOKEN:
+        required: false
+
 jobs:
-  unitTests:
-    name: "🧪 Unit Tests"
-    runs-on: buildjet-4vcpu-ubuntu-2204
-    steps:
-      - name: ⬇️ Checkout repo
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-
-      - name: ⎔ Setup pnpm
-        uses: pnpm/action-setup@v2.2.4
-        with:
-          version: 7.18
-
-      - name: ⎔ Setup node
-        uses: buildjet/setup-node@v3
-        with:
-          node-version: 18
-          cache: "pnpm"
-
-      - name: 📥 Download deps
-        run: pnpm install --frozen-lockfile
-
-      - name: Run Unit Tests
-        run: |
-          pnpm run test
+  webapp:
+    uses: ./.github/workflows/unit-tests-webapp.yml
+    secrets:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+  e2e-webapp:
+    uses: ./.github/workflows/e2e-webapp.yml
+    secrets:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+  packages:
+    uses: ./.github/workflows/unit-tests-packages.yml
+    secrets:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+  internal:
+    uses: ./.github/workflows/unit-tests-internal.yml
+    secrets:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}

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

@@ -0,0 +1,50 @@
+name: Vouch - Check PR
+
+on:
+  pull_request_target: # zizmor: ignore[dangerous-triggers] needed to comment/close fork PRs; safe because we never check out PR HEAD ref so no fork-controlled code runs
+    types: [opened, reopened]
+
+permissions: {}
+
+jobs:
+  check-vouch:
+    runs-on: warp-ubuntu-latest-x64-2x
+    permissions:
+      contents: read
+      pull-requests: write # auto-close unvouched PRs
+      issues: read
+    steps:
+      - uses: mitchellh/vouch/action/check-pr@c6d80ead49839655b61b422700b7a3bc9d0804a9 # v1.4.2
+        with:
+          pr-number: ${{ github.event.pull_request.number }}
+          auto-close: true
+          require-vouch: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  require-draft:
+    needs: check-vouch
+    permissions:
+      pull-requests: write # close non-draft PRs with a comment
+    if: >
+      github.event.pull_request.draft == false &&
+      github.event.pull_request.author_association != 'MEMBER' &&
+      github.event.pull_request.author_association != 'OWNER' &&
+      github.event.pull_request.author_association != 'COLLABORATOR' &&
+      github.event.pull_request.user.login != 'devin-ai-integration[bot]' &&
+      github.event.pull_request.user.login != 'dependabot[bot]' &&
+      github.event.pull_request.user.login != 'github-actions[bot]'
+    runs-on: warp-ubuntu-latest-x64-2x
+    steps:
+      - name: Close non-draft PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          STATE=$(gh pr view ${{ github.event.pull_request.number }} --repo ${{ github.repository }} --json state -q '.state')
+          if [ "$STATE" != "OPEN" ]; then
+            echo "PR is already closed, skipping."
+            exit 0
+          fi
+          gh pr close ${{ github.event.pull_request.number }} \
+            --repo ${{ github.repository }} \
+            --comment "Thanks for your contribution! We require all external PRs to be opened in **draft** status first so you can address CodeRabbit review comments and ensure CI passes before requesting a review. Please re-open this PR as a draft. See [CONTRIBUTING.md](https://github.com/${{ github.repository }}/blob/main/CONTRIBUTING.md#pr-workflow) for details."

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

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

.github/workflows/workflow-checks.yml

@@ -0,0 +1,58 @@
+name: Workflow Checks
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - ".github/workflows/**"
+      - ".github/actions/**"
+      - ".github/zizmor.yml"
+      - ".github/actionlint.yaml"
+  pull_request:
+    paths:
+      - ".github/workflows/**"
+      - ".github/actions/**"
+      - ".github/zizmor.yml"
+      - ".github/actionlint.yaml"
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  actionlint:
+    name: Actionlint
+    runs-on: warp-ubuntu-latest-x64-2x
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Run actionlint
+        uses: docker://rhysd/actionlint:1.7.12@sha256:b1934ee5f1c509618f2508e6eb47ee0d3520686341fec936f3b79331f9315667
+
+  zizmor:
+    name: Zizmor
+    # Uploads SARIF to the Security tab, which requires GitHub code scanning to be
+    # enabled on the repository. Set the ENABLE_WORKFLOW_SECURITY_SCAN repository
+    # variable to 'false' to skip this job where code scanning isn't available;
+    # leave it unset (the default) to run the scan.
+    if: ${{ vars.ENABLE_WORKFLOW_SECURITY_SCAN != 'false' }}
+    runs-on: warp-ubuntu-latest-x64-2x
+    permissions:
+      security-events: write # Upload SARIF to GitHub Security tab
+      contents: read # Read workflow files for analysis
+      actions: read # Read workflow run metadata
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Run zizmor
+        uses: zizmorcore/zizmor-action@192e21d79ab29983730a13d1382995c2307fbcaa # v0.5.7

.github/zizmor.yml

@@ -0,0 +1,5 @@
+rules:
+  unpinned-uses:
+    config:
+      policies:
+        "*": hash-pin

.gitignore

@@ -12,10 +12,12 @@ coverage
 # next.js
 .next/
 out/
-build
 dist
 packages/**/dist
 
+# vendored bundles (generated during build)
+packages/**/src/**/vendor
+
 # Tailwind
 apps/**/styles/tailwind.css
 packages/**/styles/tailwind.css
@@ -30,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
@@ -53,4 +53,26 @@ apps/**/public/build
 /playwright-report/
 /playwright/.cache/
 
-.cosine
+.cosine
+.trigger
+.tshy*
+.yarn
+*.tsbuildinfo
+/packages/cli-v3/src/package.json
+.husky
+/packages/react-hooks/src/package.json
+/packages/core/src/package.json
+/packages/trigger-sdk/src/package.json
+/packages/python/src/package.json
+**/.claude/settings.local.json
+.claude/architecture/
+.claude/docs-plans/
+.claude/plans/
+.claude/review-guides/
+.claude/scheduled_tasks.lock
+.mcp.log
+.mcp.json
+.cursor/debug.log
+ailogger-output.log
+# per-package vitest timing capture (transient; merged into root test-timings.json)
+.vitest-timing.json

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "internal-packages/otlp-importer/protos"]
+	path = internal-packages/otlp-importer/protos
+	url = https://github.com/open-telemetry/opentelemetry-proto.git

.npmrc

@@ -1,2 +0,0 @@
-link-workspace-packages=false
-public-hoist-pattern[]=*prisma*

.nvmrc

@@ -1 +1 @@
-v18.18.0
+v22.23.1

.oxfmtrc.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "semi": true,
+  "singleQuote": false,
+  "jsxSingleQuote": false,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "sortPackageJson": false,
+  "ignorePatterns": [
+    "node_modules",
+    ".env",
+    ".env.local",
+    "pnpm-lock.yaml",
+    "tailwind.css",
+    ".babelrc.json",
+    "**/.react-email/",
+    "**/storybook-static/",
+    "**/.changeset/",
+    "**/dist/",
+    "internal-packages/tsql/src/grammar/",
+    "internal-packages/llm-model-catalog/src/defaultPrices.ts",
+    "internal-packages/llm-model-catalog/src/modelCatalog.ts",
+    // Maybe turn these on in the future
+    "**/*.yaml",
+    "**/*.mdx",
+    "**/*.md"
+  ]
+}

.oxlintrc.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript", "import", "react"],
+  "jsPlugins": ["./oxlint-plugins/no-thrown-unawaited-redirect.mjs"],
+  "ignorePatterns": [
+    "**/dist/**",
+    "**/build/**",
+    "**/*.d.ts",
+    "**/seed.js",
+    "**/seedCloud.ts",
+    "**/populate.js",
+    "internal-packages/tsql/src/grammar/"
+  ],
+  "rules": {
+    "no-unused-vars": [
+      "error",
+      {
+        "args": "none",
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_",
+        "caughtErrors": "all",
+        "caughtErrorsIgnorePattern": "^_",
+        "destructuredArrayIgnorePattern": "^_",
+        "ignoreRestSiblings": true
+      }
+    ],
+    "no-empty-pattern": "off",
+    "no-control-regex": "off",
+    "typescript/no-non-null-asserted-optional-chain": "off",
+    "no-unused-expressions": ["warn", { "allowShortCircuit": true, "allowTernary": true }],
+    "typescript/consistent-type-imports": "error",
+    "import/no-duplicates": "error",
+    "import/namespace": "off",
+    "react-hooks/exhaustive-deps": "off",
+    "react-hooks/rules-of-hooks": "off",
+    "trigger/no-thrown-unawaited-redirect": "error"
+  }
+}

.prettierignore

@@ -1,11 +0,0 @@
-node_modules
-.env
-.env.local
-pnpm-lock.yaml
-tailwind.css
-.babelrc.json
-**/.react-email/
-**/storybook-static/
-**/.changeset/
-**/build/
-**/dist/

.server-changes/README.md

@@ -0,0 +1,95 @@
+# Server Changes
+
+This directory tracks changes to server-only components (webapp, supervisor, etc.) that are not captured by changesets. Changesets only track published npm packages — server changes would otherwise go undocumented.
+
+## When to add a file
+
+**Server-only PRs**: If your PR only changes `apps/webapp/`, `apps/supervisor/`, or other server components (and does NOT change anything in `packages/`), add a `.server-changes/` file.
+
+**Mixed PRs** (both packages and server): Just add a changeset as usual. No `.server-changes/` file needed — the changeset covers it.
+
+**Package-only PRs**: Just add a changeset as usual.
+
+## File format
+
+Create a markdown file with a descriptive name:
+
+```
+.server-changes/fix-batch-queue-stalls.md
+```
+
+With this format:
+
+```markdown
+---
+area: webapp
+type: fix
+---
+
+Speed up batch queue processing by removing stalls and fixing retry race
+```
+
+### Fields
+
+- **area** (required): `webapp` | `supervisor`
+- **type** (required): `feature` | `fix` | `improvement` | `breaking`
+
+### Description
+
+The body text (below the frontmatter) is a one-line description of the change. Keep it concise — it will appear in release notes.
+
+### Writing guidance
+
+These entries are public-facing - they ship verbatim in user-visible release notes. A few rules to keep them clean:
+
+- **Write for the user, not the reviewer.** Lead with what the user notices or has to do. If a reader who doesn't know the codebase can't tell what changed for them, rewrite it.
+- **One sentence is usually enough.** The body is the bullet in the changelog. If you need a paragraph, you're probably describing the implementation rather than the change.
+- **Describe behavior, not implementation.** Skip internal scopes, middleware names, library specifics, framework internals. Users care about what's different for them, not how it's wired.
+- **Never name internal tools or infra.** Observability stacks, internal services, infra components, monitoring backends, CI surfaces, AWS specifics - none of these belong in user-facing notes.
+
+Before / after:
+
+- ❌ _"The image verification step now parses the manifest's layer media types and returns a new result the finalizer rejects."_ (describes the wiring; a user can't act on it)
+- ✅ _"Deploying with an outdated CLI could produce an image that fails to start on every run. These deploys are now stopped before going live, with a message asking you to upgrade the CLI and re-deploy."_ (what the user sees and does)
+
+## Lifecycle
+
+1. Engineer adds a `.server-changes/` file in their PR
+2. Files accumulate on `main` as PRs merge
+3. The changeset release PR includes these in its summary
+4. After the release merges, CI cleans up the consumed files
+
+## Examples
+
+**New feature:**
+
+```markdown
+---
+area: webapp
+type: feature
+---
+
+TRQL query language and the Query page
+```
+
+**Bug fix:**
+
+```markdown
+---
+area: webapp
+type: fix
+---
+
+Fix schedule limit counting for orgs with custom limits
+```
+
+**Improvement:**
+
+```markdown
+---
+area: webapp
+type: improvement
+---
+
+Use the replica for API auth queries to reduce primary load
+```

.vouch.yml

@@ -0,0 +1,4 @@
+vouch:
+  - github: edosrecki
+  - github: GautamBytes
+  - github: ConProgramming

.vscode/extensions.json

@@ -1,9 +1,4 @@
 {
-	"recommendations": [
-        "astro-build.astro-vscode",
-        "denoland.vscode-deno"
-    ],
-	"unwantedRecommendations": [
-		
-	]
-}
+  "recommendations": ["bierner.comment-tagged-templates"],
+  "unwantedRecommendations": []
+}

.vscode/launch.json

@@ -9,7 +9,34 @@
       "request": "launch",
       "name": "Debug WebApp",
       "command": "pnpm run dev --filter webapp",
-      "envFile": "${workspaceFolder}/apps/webapp/.env",
+      "envFile": "${workspaceFolder}/.env",
+      "cwd": "${workspaceFolder}",
+      "sourceMaps": true
+    },
+    {
+      "type": "node-terminal",
+      "request": "launch",
+      "name": "Debug realtimeStreams.test.ts",
+      "command": "pnpm run test -t RealtimeStreams",
+      "envFile": "${workspaceFolder}/.env",
+      "cwd": "${workspaceFolder}/apps/webapp",
+      "sourceMaps": true
+    },
+    {
+      "type": "node-terminal",
+      "request": "launch",
+      "name": "Debug triggerTask.test.ts",
+      "command": "pnpm run test --run ./test/engine/triggerTask.test.ts",
+      "envFile": "${workspaceFolder}/.env",
+      "cwd": "${workspaceFolder}/apps/webapp",
+      "sourceMaps": true
+    },
+    {
+      "type": "node-terminal",
+      "request": "launch",
+      "name": "Debug opened test file",
+      "command": "pnpm run test -- ./${relativeFile}",
+      "envFile": "${workspaceFolder}/.env",
       "cwd": "${workspaceFolder}",
       "sourceMaps": true
     },
@@ -20,13 +47,36 @@
       "url": "http://localhost:3030",
       "webRoot": "${workspaceFolder}/apps/webapp/app"
     },
+    {
+      "type": "node",
+      "request": "attach",
+      "name": "Attach to Trigger.dev CLI (v3)",
+      "port": 9229,
+      "restart": true,
+      "skipFiles": ["<node_internals>/**"]
+    },
     {
       "type": "node-terminal",
       "request": "launch",
-      "name": "Debug BYO Auth",
-      "command": "pnpm run byo-auth",
-      "envFile": "${workspaceFolder}/references/job-catalog/.env",
-      "cwd": "${workspaceFolder}/references/job-catalog",
+      "name": "Debug CLI e2e tests",
+      "command": "MOD=otel-telemetry-loader pnpm run test:e2e",
+      "cwd": "${workspaceFolder}/packages/cli-v3",
+      "sourceMaps": true
+    },
+    {
+      "type": "node-terminal",
+      "request": "launch",
+      "name": "Debug RunEngine tests",
+      "command": "pnpm run test ./src/engine/tests/releaseConcurrencyTokenBucketQueue.test.ts -t 'Should retrieve metrics for all queues via getQueueMetrics'",
+      "cwd": "${workspaceFolder}/internal-packages/run-engine",
+      "sourceMaps": true
+    },
+    {
+      "type": "node-terminal",
+      "request": "launch",
+      "name": "Debug RunQueue tests",
+      "command": "pnpm run test ./src/run-queue/index.test.ts --run",
+      "cwd": "${workspaceFolder}/internal-packages/run-engine",
       "sourceMaps": true
     }
   ]

.vscode/settings.json

@@ -1,4 +1,11 @@
 {
-  "deno.enablePaths": ["references/deno-reference"],
-  "debug.toolBarLocation": "commandCenter"
+  "deno.enablePaths": ["runtime_tests/tests/deno"],
+  "debug.toolBarLocation": "commandCenter",
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "search.exclude": {
+    "**/node_modules/**": true,
+    "packages/cli-v3/e2e": true
+  },
+  "vitest.disableWorkspaceWarning": true,
+  "chat.agent.maxRequests": 10000
 }

.zed/tasks.json

@@ -0,0 +1,45 @@
+[
+  {
+    "label": "Build packages",
+    "command": "pnpm run build --filter \"@trigger.dev/*\" --filter trigger.dev",
+    //"args": [],
+    // Env overrides for the command, will be appended to the terminal's environment from the settings.
+    "env": { "foo": "bar" },
+    // Current working directory to spawn the command into, defaults to current project root.
+    //"cwd": "/path/to/working/directory",
+    // Whether to use a new terminal tab or reuse the existing one to spawn the process, defaults to `false`.
+    "use_new_terminal": false,
+    // Whether to allow multiple instances of the same task to be run, or rather wait for the existing ones to finish, defaults to `false`.
+    "allow_concurrent_runs": false,
+    // What to do with the terminal pane and tab, after the command was started:
+    // * `always` — always show the task's pane, and focus the corresponding tab in it (default)
+    // * `no_focus` — always show the task's pane, add the task's tab in it, but don't focus it
+    // * `never` — do not alter focus, but still add/reuse the task's tab in its pane
+    "reveal": "always",
+    // What to do with the terminal pane and tab, after the command has finished:
+    // * `never` — Do nothing when the command finishes (default)
+    // * `always` — always hide the terminal tab, hide the pane also if it was the last tab in it
+    // * `on_success` — hide the terminal tab on task success only, otherwise behaves similar to `always`
+    "hide": "never",
+    // Which shell to use when running a task inside the terminal.
+    // May take 3 values:
+    // 1. (default) Use the system's default terminal configuration in /etc/passwd
+    //      "shell": "system"
+    // 2. A program:
+    //      "shell": {
+    //        "program": "sh"
+    //      }
+    // 3. A program with arguments:
+    //     "shell": {
+    //         "with_arguments": {
+    //           "program": "/bin/bash",
+    //           "args": ["--login"]
+    //         }
+    //     }
+    "shell": "system",
+    // Whether to show the task line in the output of the spawned task, defaults to `true`.
+    "show_summary": true,
+    // Whether to show the command line in the output of the spawned task, defaults to `true`.
+    "show_output": true
+  }
+]

AGENTS.md

@@ -0,0 +1,275 @@
+# AGENTS.md
+
+This file provides guidance to Claude Code when working with this repository. Subdirectory CLAUDE.md files provide deeper context when you navigate into specific areas.
+
+## Build and Development Commands
+
+This is a pnpm 10.33.2 monorepo using Turborepo. Run commands from root with `pnpm run`.
+
+**Adding dependencies:** Edit `package.json` directly instead of using `pnpm add`, then run `pnpm i` from the repo root. See `.claude/rules/package-installation.md` for the full process.
+
+```bash
+pnpm run docker              # Core dev services (Postgres, Redis, Electric, MinIO, ClickHouse, s2-lite)
+# pnpm run docker:full       # Same + observability stack (Prometheus, Grafana, OTEL) and chaos tooling
+pnpm run db:migrate           # Run database migrations
+pnpm run db:seed              # Seed the database (required for reference projects)
+
+# Build packages (required before running)
+pnpm run build --filter webapp && pnpm run build --filter trigger.dev && pnpm run build --filter @trigger.dev/sdk
+
+pnpm run dev --filter webapp  # Run webapp (http://localhost:3030)
+pnpm run dev --filter trigger.dev --filter "@trigger.dev/*"  # Watch CLI and packages
+```
+
+### Verifying Changes
+
+The verification command depends on where the change lives:
+
+- **Apps and internal packages** (`apps/*`, `internal-packages/*`): Use `typecheck`. **Never use `build`** for these — building proves almost nothing about correctness.
+- **Public packages** (`packages/*`): Use `build`.
+
+```bash
+# Apps and internal packages — use typecheck
+pnpm run typecheck --filter webapp                  # ~1-2 minutes
+pnpm run typecheck --filter @internal/run-engine
+
+# Public packages — use build
+pnpm run build --filter @trigger.dev/sdk
+pnpm run build --filter @trigger.dev/core
+```
+
+Only run typecheck/build after major changes (new files, significant refactors, schema changes). For small edits, trust the types and let CI catch issues.
+
+## Testing
+
+We use vitest exclusively. **Never mock anything** - use testcontainers instead.
+
+```bash
+pnpm run test --filter webapp                          # All tests for a package
+cd internal-packages/run-engine
+pnpm run test ./src/engine/tests/ttl.test.ts --run     # Single test file
+pnpm run build --filter @internal/run-engine           # May need to build deps first
+```
+
+Test files go next to source files (e.g., `MyService.ts` -> `MyService.test.ts`).
+
+### Testcontainers for Redis/PostgreSQL
+
+```typescript
+import { redisTest, postgresTest, containerTest } from "@internal/testcontainers";
+
+redisTest("should use redis", async ({ redisOptions }) => {
+  /* ... */
+});
+postgresTest("should use postgres", async ({ prisma }) => {
+  /* ... */
+});
+containerTest("should use both", async ({ prisma, redisOptions }) => {
+  /* ... */
+});
+```
+
+## Code Style
+
+### Formatting and linting
+
+Format and lint are enforced by CI (`code-quality` check). Run before committing:
+
+```bash
+pnpm run format      # oxfmt — auto-fixes formatting
+pnpm run lint:fix    # oxlint — auto-fixes lint violations
+pnpm run lint        # oxlint — check only (no fixes)
+```
+
+### Imports
+
+**Prefer static imports over dynamic imports.** Only use dynamic `import()` when:
+- Circular dependencies cannot be resolved otherwise
+- Code splitting is genuinely needed for performance
+- The module must be loaded conditionally at runtime
+
+Dynamic imports add unnecessary overhead in hot paths and make code harder to analyze. If you find yourself using `await import()`, ask if a regular `import` statement would work instead.
+
+## Changesets and Server Changes
+
+When modifying any public package (`packages/*` or `integrations/*`), add a changeset:
+
+```bash
+pnpm run changeset:add
+```
+
+- Default to **patch** for bug fixes and minor changes
+- Confirm with maintainers before selecting **minor** (new features)
+- **Never** select major without explicit approval
+
+When modifying only server components (`apps/webapp/`, `apps/supervisor/`, etc.) with no package changes, add a `.server-changes/` file instead. See `.server-changes/README.md` for format and documentation.
+
+**Write the description for users, not maintainers.** Both changesets and `.server-changes/` notes ship verbatim in user-visible release notes. Lead with what changed *for the user* - one plain sentence describing behavior, not implementation, and never naming internal tools or infra. The full writing guidance in `.server-changes/README.md` applies to changesets too.
+
+## Dependency Pinning
+
+Zod is pinned to a single version across the entire monorepo (currently `3.25.76`). When adding zod to a new or existing package, use the **exact same version** as the rest of the repo - never a different version or a range. Mismatched zod versions cause runtime type incompatibilities (e.g., schemas from one package can't be used as body validators in another).
+
+## Architecture Overview
+
+### Request Flow
+
+User API call -> Webapp routes -> Services -> RunEngine -> Redis Queue -> Supervisor -> Container execution -> Results back through RunEngine -> ClickHouse (analytics) + PostgreSQL (state)
+
+### Apps
+
+- **apps/webapp**: Remix 2.17.4 app - main API, dashboard, orchestration. Uses Express server.
+- **apps/supervisor**: Manages task execution containers (Docker/Kubernetes).
+
+### Public Packages
+
+- **packages/trigger-sdk** (`@trigger.dev/sdk`): Main SDK for writing tasks
+- **packages/cli-v3** (`trigger.dev`): CLI - also bundles code that goes into customer task images
+- **packages/core** (`@trigger.dev/core`): Shared types. **Import subpaths only** (never root).
+- **packages/build** (`@trigger.dev/build`): Build extensions and types
+- **packages/react-hooks**: React hooks for realtime and triggering
+- **packages/redis-worker** (`@trigger.dev/redis-worker`): Redis-based background job system
+
+### Internal Packages
+
+- **internal-packages/database**: Prisma 6.14.0 client and schema (PostgreSQL)
+- **internal-packages/clickhouse**: ClickHouse client, schema migrations, analytics queries
+- **internal-packages/run-engine**: "Run Engine 2.0" - core run lifecycle management
+- **internal-packages/redis**: Redis client creation utilities (ioredis)
+- **internal-packages/testcontainers**: Test helpers for Redis/PostgreSQL containers
+- **internal-packages/schedule-engine**: Durable cron scheduling
+
+### v3 (engine V1) removed
+
+v3 (engine V1: MarQS + Graphile worker) is end-of-life and its execution code has been removed. The `apps/webapp/app/v3/` directory name is historical - everything there now serves V2 (Run Engine 2.0, `@internal/run-engine` + redis-worker). There is no V1 execution path: a `RunEngineVersion` `V1` branch only rejects or finalizes gracefully so v3 clients get a clean 4xx, never a 5xx. Do not reintroduce V1. See `apps/webapp/CLAUDE.md` and `.claude/rules/legacy-v3-code.md`.
+
+### Documentation
+
+Docs live in `docs/` as a Mintlify site (MDX format). See `docs/CLAUDE.md` for conventions.
+
+### Reference Projects
+
+Reference/example projects for testing SDK and platform features live in a separate repo: [`triggerdotdev/references`](https://github.com/triggerdotdev/references). Clone it alongside this repo and use its `projects/hello-world` to manually test changes before submitting PRs. See that repo's README for setup and linking to a local monorepo build.
+
+## Docker Image Guidelines
+
+When updating Docker image references:
+
+- **Always use multiplatform/index digests**, not architecture-specific digests
+- Architecture-specific digests cause CI failures on different build environments
+- Use the digest from the main Docker Hub page, not from a specific OS/ARCH variant
+
+## Writing Trigger.dev Tasks
+
+Always import from `@trigger.dev/sdk`. Never use `@trigger.dev/sdk/v3` or deprecated `client.defineJob`.
+
+```typescript
+import { task } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  run: async (payload: { message: string }) => {
+    // Task logic
+  },
+});
+```
+
+### SDK Documentation Rules
+
+The `rules/` directory contains versioned SDK documentation distributed via the SDK installer. Current version: `rules/manifest.json`. Do NOT update `rules/` or `.claude/skills/trigger-dev-tasks/` unless explicitly asked - these are maintained in separate dedicated passes.
+
+## Testing with the hello-world Reference Project
+
+The reference projects live in the separate [`triggerdotdev/references`](https://github.com/triggerdotdev/references) repo - clone it alongside this repo.
+
+First-time setup:
+
+1. `pnpm run db:seed` to seed the database (creates the References org + hello-world project)
+2. Build the CLI/packages you want to test: `pnpm run build --filter trigger.dev`
+3. In your `references` clone, follow its README to link to your local monorepo build, then authorize: `cd projects/hello-world && pnpm exec trigger login -a http://localhost:3030`
+
+Running (from your `references` clone): `cd projects/hello-world && pnpm exec trigger dev`
+
+## Local Task Testing Workflow
+
+### Step 1: Start Webapp in Background
+
+```bash
+# Run from repo root with run_in_background: true
+pnpm run dev --filter webapp
+curl -s http://localhost:3030/healthcheck  # Verify running
+```
+
+### Step 2: Start Trigger Dev in Background
+
+```bash
+# in your triggerdotdev/references clone
+cd projects/hello-world && pnpm exec trigger dev
+# Wait for "Local worker ready [node]"
+```
+
+### Step 3: Trigger and Monitor Tasks via MCP
+
+```
+mcp__trigger__get_current_worker(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev")
+mcp__trigger__trigger_task(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev", taskId: "hello-world", payload: {"message": "Hello"})
+mcp__trigger__list_runs(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev", taskIdentifier: "hello-world", limit: 5)
+```
+
+Dashboard: http://localhost:3030/orgs/references-9dfd/projects/hello-world-97DT/env/dev/runs
+
+<!-- intent-skills:start -->
+
+# Skill mappings — when working in these areas, load the linked skill file into context.
+
+skills:
+
+- task: "Using agentcrumbs for debug tracing, adding crumbs, trails, markers, querying traces, or stripping debug code before merge"
+  load: "node_modules/agentcrumbs/skills/agentcrumbs/SKILL.md"
+- task: "Setting up agentcrumbs in the project, initializing namespace catalog, running crumbs init"
+  load: "node_modules/agentcrumbs/skills/agentcrumbs/init/SKILL.md"
+<!-- intent-skills:end -->
+
+## agentcrumbs
+
+Add crumbs as you write code — not just when debugging. Mark lines with
+`// @crumbs` or wrap blocks in `// #region @crumbs`. They stay on the
+branch throughout development and are stripped by `agentcrumbs strip`
+before merge.
+
+### Namespaces
+
+| Namespace         | Description                                    | Path                                |
+| ----------------- | ---------------------------------------------- | ----------------------------------- |
+| `webapp`          | Main Remix app — API, dashboard, orchestration | `apps/webapp`                       |
+| `supervisor`      | Task execution container manager               | `apps/supervisor`                   |
+| `sdk`             | Main SDK for writing tasks                     | `packages/trigger-sdk`              |
+| `cli`             | CLI and task image bundling                    | `packages/cli-v3`                   |
+| `core`            | Shared types and subpath exports               | `packages/core`                     |
+| `build`           | Build extensions and types                     | `packages/build`                    |
+| `react-hooks`     | React hooks for realtime/triggering            | `packages/react-hooks`              |
+| `redis-worker`    | Redis-based background job system              | `packages/redis-worker`             |
+| `run-engine`      | Run Engine 2.0 — core run lifecycle            | `internal-packages/run-engine`      |
+| `database`        | Prisma client and schema                       | `internal-packages/database`        |
+| `clickhouse`      | ClickHouse client, migrations, analytics       | `internal-packages/clickhouse`      |
+| `schedule-engine` | Durable cron scheduling                        | `internal-packages/schedule-engine` |
+| `run-queue`       | Run queue management                           | `internal-packages/run-queue`       |
+
+Do not invent new namespaces — pick from this table or ask first.
+
+### For PR reviewers
+
+Do not flag `// @crumbs` markers, `#region @crumbs` blocks, or agentcrumbs
+imports in reviews. These are temporary debug instrumentation stripped
+before merge. Data logged in crumbs (IDs, names, values) never reaches
+production.
+
+### CLI
+
+```bash
+pnpm exec agentcrumbs collect    # start collector (multi-service)
+pnpm exec agentcrumbs tail --app trigger       # live tail
+pnpm exec agentcrumbs clear --app trigger      # remove crumbs before merge
+```
+
+The preferred way to query for crumbs is to use `pnpm exec agentcrumbs query --app trigger` with the `--limit` option and cursor pagination, and clear existing crumbs before reproducing a bug via `pnpm exec agentcrumbs clear --app trigger`.