From f384e8334a8eca3266ecb33e5fae7d1fbf148d59 Mon Sep 17 00:00:00 2001
From: Daniel Sutton <45313566+d-cs@users.noreply.github.com>
Date: Thu, 17 Sep 2026 12:41:09 +0000
Subject: [PATCH 1/6] feat(webapp,cli): support empty-string environment
 variable values

Adds support for environment variables with empty-string values, rolling
out gradually. Once enabled for your organization, an empty value stays
stored and available to tasks, including through environment-variable
imports and Vercel sync. Deleting a variable remains a separate action.
Also fixes local dev environment precedence so freshly resolved project
values reach task processes correctly.

Mono-RevId: 25dea78a2c72a984a9bd9ac432c11026f220576c
---
 .changeset/empty-dev-env-vars.md              |   6 +
 .server-changes/envvar-empty-value.md         |   6 +
 .../app/models/vercelIntegration.server.ts    | 147 +++--
 .../EnvironmentVariablesPresenter.server.ts   |   6 +
 .../route.tsx                                 |  28 +-
 .../route.tsx                                 |  63 ++-
 ...rojects.$projectRef.envvars.$slug.$name.ts |   1 -
 .../api.v1.projects.$projectRef.envvars.ts    |   5 +
 .../emptyEnvironmentValuesRollout.test.ts     | 293 ++++++++++
 .../emptyValuesFlag.server.ts                 |  34 ++
 .../environmentVariablesRepository.server.ts  | 130 +++--
 .../app/v3/environmentVariables/forms.ts      |  29 +
 .../app/v3/environmentVariables/repository.ts |   8 +-
 apps/webapp/app/v3/featureFlags.ts            |   2 +
 .../v3/vercel/environmentVariableValues.ts    |  57 ++
 .../test/environmentVariablesForms.test.ts    | 110 ++++
 .../environmentVariablesRepository.test.ts    | 506 +++++++++++++++++-
 .../vercelEnvironmentVariableValues.test.ts   |  77 +++
 docs/deploy-environment-variables.mdx         |   6 +
 docs/v3-openapi.yaml                          |   1 +
 packages/cli-v3/src/build/buildWorker.ts      |   2 +
 packages/cli-v3/src/build/extensions.test.ts  |  95 ++++
 packages/cli-v3/src/build/extensions.ts       |  27 +-
 packages/cli-v3/src/commands/deploy.ts        |   4 +
 packages/cli-v3/src/dev/backgroundWorker.ts   |   2 +
 packages/cli-v3/src/dev/devSupervisor.ts      |  38 +-
 .../src/entryPoints/dev-run-controller.ts     |  17 +-
 .../cli-v3/src/utilities/localEnvVars.test.ts |  64 +++
 packages/cli-v3/src/utilities/localEnvVars.ts |  25 +-
 .../src/utilities/sanitizeEnvVars.test.ts     |  39 ++
 .../cli-v3/src/utilities/sanitizeEnvVars.ts   |  23 +
 packages/core/src/v3/schemas/api.ts           |   1 +
 32 files changed, 1665 insertions(+), 187 deletions(-)
 create mode 100644 .changeset/empty-dev-env-vars.md
 create mode 100644 .server-changes/envvar-empty-value.md
 create mode 100644 apps/webapp/app/v3/environmentVariables/emptyEnvironmentValuesRollout.test.ts
 create mode 100644 apps/webapp/app/v3/environmentVariables/emptyValuesFlag.server.ts
 create mode 100644 apps/webapp/app/v3/environmentVariables/forms.ts
 create mode 100644 apps/webapp/app/v3/vercel/environmentVariableValues.ts
 create mode 100644 apps/webapp/test/environmentVariablesForms.test.ts
 create mode 100644 apps/webapp/test/vercelEnvironmentVariableValues.test.ts
 create mode 100644 packages/cli-v3/src/build/extensions.test.ts
 create mode 100644 packages/cli-v3/src/utilities/localEnvVars.test.ts
 create mode 100644 packages/cli-v3/src/utilities/sanitizeEnvVars.test.ts

diff --git a/.changeset/empty-dev-env-vars.md b/.changeset/empty-dev-env-vars.md
new file mode 100644
index 00000000000..e28169a97e3
--- /dev/null
+++ b/.changeset/empty-dev-env-vars.md
@@ -0,0 +1,6 @@
+---
+"trigger.dev": patch
+"@trigger.dev/core": patch
+---
+
+Fix stale and empty project environment values in `trigger dev`, and support empty values in `syncEnvVars()`.
diff --git a/.server-changes/envvar-empty-value.md b/.server-changes/envvar-empty-value.md
new file mode 100644
index 00000000000..892de94c810
--- /dev/null
+++ b/.server-changes/envvar-empty-value.md
@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+Support empty-string environment values across the dashboard, API, and Vercel sync behind a feature flag, disabled by default.
diff --git a/apps/webapp/app/models/vercelIntegration.server.ts b/apps/webapp/app/models/vercelIntegration.server.ts
index 277a985678b..2e95576bd2b 100644
--- a/apps/webapp/app/models/vercelIntegration.server.ts
+++ b/apps/webapp/app/models/vercelIntegration.server.ts
@@ -1,3 +1,11 @@
+import { emptyEnvironmentVariableValuesEnabledForProject } from "~/v3/environmentVariables/emptyValuesFlag.server";
+import {
+  normalizeTarget,
+  isVercelSecretType,
+  toVercelEnvironmentVariableValue,
+  resolveVercelSharedValue,
+  mergeVercelEnvironmentVariableValues,
+} from "~/v3/vercel/environmentVariableValues";
 import pLimit from "p-limit";
 import { Vercel } from "@vercel/sdk";
 import type {
@@ -38,12 +46,6 @@ import {
 // Pure helpers
 // ---------------------------------------------------------------------------
 
-function normalizeTarget(target: string[] | string | undefined): string[] {
-  if (Array.isArray(target)) return target.filter(Boolean);
-  if (typeof target === "string") return [target];
-  return [];
-}
-
 function readProjectEnvs(
   response: unknown,
   logContext: Record<string, unknown>
@@ -86,10 +88,6 @@ function hasVercelEnvVarForTarget(envs: ResponseBodyEnvs[], key: string, target:
   });
 }
 
-function isVercelSecretType(type: string): boolean {
-  return type === "secret" || type === "sensitive";
-}
-
 export type CreateEnvVarsIfAbsentResult = {
   written: string[];
   skipped: string[];
@@ -226,19 +224,6 @@ function toVercelCustomEnvironment({
   return { id, slug, description, branchMatcher };
 }
 
-function toVercelEnvironmentVariableValue(
-  env: ResponseBodyEnvs
-): VercelEnvironmentVariableValue | null {
-  if (!env.value) return null;
-  return {
-    key: env.key,
-    value: env.value,
-    target: normalizeTarget(env.target),
-    type: env.type,
-    isSecret: isVercelSecretType(env.type),
-  };
-}
-
 // ---------------------------------------------------------------------------
 // Repository
 // ---------------------------------------------------------------------------
@@ -474,7 +459,8 @@ export class VercelIntegrationRepository {
     teamId?: string | null,
     target?: string,
     /** If provided, only include keys that pass this filter */
-    shouldIncludeKey?: (key: string) => boolean
+    shouldIncludeKey?: (key: string) => boolean,
+    allowEmptyValues = true
   ): ResultAsync<VercelEnvironmentVariableValue[], VercelApiError> {
     return wrapVercelCallWithRecovery(
       client.projects.filterProjectEnvs({
@@ -499,7 +485,9 @@ export class VercelIntegrationRepository {
       return ResultAsync.fromPromise(
         Promise.all(
           filteredEnvs.map((env) =>
-            concurrencyLimit(() => this.#resolveEnvVarValue(client, projectId, teamId, env))
+            concurrencyLimit(() =>
+              this.#resolveEnvVarValue(client, projectId, teamId, env, allowEmptyValues)
+            )
           )
         ),
         (error) => toVercelApiError(error)
@@ -511,12 +499,13 @@ export class VercelIntegrationRepository {
     client: Vercel,
     projectId: string,
     teamId: string | null | undefined,
-    env: ResponseBodyEnvs
+    env: ResponseBodyEnvs,
+    allowEmptyValues: boolean
   ): Promise<VercelEnvironmentVariableValue | null> {
     // Non-encrypted vars: use value from list response if present
     if (env.type !== "encrypted" || !env.id) {
       if (env.value === undefined || env.value === null) return null;
-      return toVercelEnvironmentVariableValue(env);
+      return toVercelEnvironmentVariableValue(env, allowEmptyValues);
     }
 
     // Encrypted vars: fetch decrypted value via individual endpoint
@@ -545,7 +534,8 @@ export class VercelIntegrationRepository {
 
     // API returns union: ResponseBody1 has no value, ResponseBody2/3 have value
     const decryptedValue = (result.value as { value?: string }).value;
-    if (typeof decryptedValue !== "string") return null;
+    if (typeof decryptedValue !== "string" || (!allowEmptyValues && decryptedValue.trim() === ""))
+      return null;
 
     return {
       key: env.key,
@@ -653,7 +643,8 @@ export class VercelIntegrationRepository {
     client: Vercel,
     accessToken: string,
     teamId: string,
-    projectId?: string // Optional: filter by project
+    projectId?: string,
+    allowEmptyValues = true
   ): ResultAsync<
     Array<{
       key: string;
@@ -684,53 +675,43 @@ export class VercelIntegrationRepository {
 
               if (isSecret) return null;
 
-              const listValue = env.value;
-              const applyToAllCustomEnvs = env.applyToAllCustomEnvironments;
-
-              if (listValue) {
-                return {
-                  key: envKey,
-                  value: listValue,
-                  target: normalizeTarget(env.target),
-                  type,
-                  isSecret,
-                  applyToAllCustomEnvironments: applyToAllCustomEnvs,
-                };
-              }
-
-              // Try to get the decrypted value for this shared env var
-              const getResult = await callVercelWithRecovery(
-                client.environment.getSharedEnvVar({
-                  id: envId,
-                  teamId,
-                }),
-                VercelSchemas.getSharedEnvVar,
-                { context: "getSharedEnvVar" }
-              );
+              const value = await resolveVercelSharedValue(
+                env.value,
+                async () => {
+                  const getResult = await callVercelWithRecovery(
+                    client.environment.getSharedEnvVar({ id: envId, teamId }),
+                    VercelSchemas.getSharedEnvVar,
+                    { context: "getSharedEnvVar" }
+                  );
 
-              if (getResult.isOk()) {
-                if (!getResult.value.value) return null;
-                return {
-                  key: envKey,
-                  value: getResult.value.value,
-                  target: normalizeTarget(env.target),
-                  type,
-                  isSecret,
-                  applyToAllCustomEnvironments: applyToAllCustomEnvs,
-                };
-              }
-
-              logger.warn("Failed to get decrypted value for shared env var", {
-                teamId,
-                projectId,
-                envId,
-                envKey,
-                error: getResult.error.message,
-                errorType: getResult.error.errorType,
-                status: getResult.error.status,
-                authInvalid: getResult.error.authInvalid,
-              });
-              return null;
+                  if (getResult.isOk()) {
+                    return getResult.value.value ?? null;
+                  }
+
+                  logger.warn("Failed to get decrypted value for shared env var", {
+                    teamId,
+                    projectId,
+                    envId,
+                    envKey,
+                    error: getResult.error.message,
+                    errorType: getResult.error.errorType,
+                    status: getResult.error.status,
+                    authInvalid: getResult.error.authInvalid,
+                  });
+                  return null;
+                },
+                allowEmptyValues
+              );
+              if (value === null) return null;
+
+              return {
+                key: envKey,
+                value,
+                target: normalizeTarget(env.target),
+                type,
+                isSecret,
+                applyToAllCustomEnvironments: env.applyToAllCustomEnvironments,
+              };
             })
           )
         ),
@@ -1334,6 +1315,9 @@ export class VercelIntegrationRepository {
           }
 
           const envVarRepository = new EnvironmentVariablesRepository();
+          const allowEmptyValues = await emptyEnvironmentVariableValuesEnabledForProject(
+            params.projectId
+          );
 
           // Fetch shared env vars once (they apply across all targets)
           let sharedEnvVars: Array<{
@@ -1350,7 +1334,8 @@ export class VercelIntegrationRepository {
               client,
               accessToken,
               params.teamId,
-              params.vercelProjectId
+              params.vercelProjectId,
+              allowEmptyValues
             );
             sharedEnvVars = sharedResult.unwrapOr([]);
           }
@@ -1373,7 +1358,8 @@ export class VercelIntegrationRepository {
                   params.vercelProjectId,
                   params.teamId,
                   mapping.vercelTarget,
-                  shouldIncludeKey
+                  shouldIncludeKey,
+                  allowEmptyValues
                 );
 
                 if (envVarsResult.isErr()) {
@@ -1399,11 +1385,10 @@ export class VercelIntegrationRepository {
                   return matchesTarget || matchesCustomEnv;
                 });
 
-                const projectEnvVarKeys = new Set(projectEnvVars.map((v) => v.key));
-                const sharedEnvVarsToAdd = filteredSharedEnvVars.filter(
-                  (v) => !projectEnvVarKeys.has(v.key)
+                const mergedEnvVars = mergeVercelEnvironmentVariableValues(
+                  projectEnvVars,
+                  filteredSharedEnvVars
                 );
-                const mergedEnvVars = [...projectEnvVars, ...sharedEnvVarsToAdd];
 
                 if (mergedEnvVars.length === 0) {
                   return;
diff --git a/apps/webapp/app/presenters/v3/EnvironmentVariablesPresenter.server.ts b/apps/webapp/app/presenters/v3/EnvironmentVariablesPresenter.server.ts
index 4a217b568bc..87d59b04687 100644
--- a/apps/webapp/app/presenters/v3/EnvironmentVariablesPresenter.server.ts
+++ b/apps/webapp/app/presenters/v3/EnvironmentVariablesPresenter.server.ts
@@ -1,3 +1,4 @@
+import { emptyEnvironmentVariableValuesEnabled } from "~/v3/environmentVariables/emptyValuesFlag.server";
 import type { PrismaClient, PrismaReplicaClient } from "~/db.server";
 import { $replica, prisma } from "~/db.server";
 import type { Project } from "~/models/project.server";
@@ -39,6 +40,7 @@ export class EnvironmentVariablesPresenter {
     const project = await this.#replicaClient.project.findFirst({
       select: {
         id: true,
+        organization: { select: { featureFlags: true } },
       },
       where: {
         slug: projectSlug,
@@ -176,6 +178,10 @@ export class EnvironmentVariablesPresenter {
     }
 
     return {
+      allowEmptyEnvironmentVariableValues: await emptyEnvironmentVariableValuesEnabled(
+        project.organization.featureFlags,
+        this.#prismaClient
+      ),
       environmentVariables: environmentVariables.flatMap((environmentVariable) => {
         return sortedEnvironments.flatMap((env) => {
           const valueRecord = environmentVariable.values.find((v) => v.environmentId === env.id);
diff --git a/apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.environment-variables.new/route.tsx b/apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.environment-variables.new/route.tsx
index 7ba44ff4ee8..bf9af682105 100644
--- a/apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.environment-variables.new/route.tsx
+++ b/apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.environment-variables.new/route.tsx
@@ -1,5 +1,9 @@
 import { getFormProps, useForm, type FieldMetadata, type FormMetadata } from "@conform-to/react";
-import { parseWithZod } from "@conform-to/zod/v4";
+import {
+  emptyEnvironmentVariableValuesEnabled,
+  EMPTY_ENV_VALUES_DISABLED,
+} from "~/v3/environmentVariables/emptyValuesFlag.server";
+import { parseEnvironmentVariableForm } from "~/v3/environmentVariables/forms";
 import {
   LockClosedIcon,
   LockOpenIcon,
@@ -54,7 +58,10 @@ import {
   v3EnvironmentVariablesPath,
 } from "~/utils/pathBuilder";
 import { EnvironmentVariablesRepository } from "~/v3/environmentVariables/environmentVariablesRepository.server";
-import { EnvironmentVariableKey } from "~/v3/environmentVariables/repository";
+import {
+  EnvironmentVariableKey,
+  EnvironmentVariableValue,
+} from "~/v3/environmentVariables/repository";
 import { findUnauthorizedEnvironmentId } from "~/v3/writableEnvironments";
 import { pageMeta } from "~/utils/pageTitle";
 
@@ -62,7 +69,7 @@ export const meta = pageMeta("New environment variable");
 
 const Variable = z.object({
   key: EnvironmentVariableKey,
-  value: z.string().nonempty("Value is required"),
+  value: EnvironmentVariableValue,
 });
 
 type Variable = z.infer<typeof Variable>;
@@ -121,7 +128,7 @@ export const action = dashboardAction(
     }
 
     const formData = await request.formData();
-    const submission = parseWithZod(formData, { schema });
+    const submission = parseEnvironmentVariableForm(formData, schema);
 
     if (submission.status !== "success") {
       return json(submission.reply());
@@ -162,6 +169,7 @@ export const action = dashboardAction(
       },
       select: {
         id: true,
+        organization: { select: { featureFlags: true } },
       },
     });
     if (!project) {
@@ -193,6 +201,13 @@ export const action = dashboardAction(
       );
     }
 
+    if (
+      submission.value.variables.some((v) => v.value.trim() === "") &&
+      !(await emptyEnvironmentVariableValuesEnabled(project.organization.featureFlags))
+    ) {
+      return json(submission.reply({ formErrors: [EMPTY_ENV_VALUES_DISABLED] }));
+    }
+
     const repository = new EnvironmentVariablesRepository(prisma);
     const result = await repository.create(project.id, {
       ...submission.value,
@@ -238,7 +253,8 @@ export default function Page() {
     parentData,
     "Environment variables page loader data must be defined when rendering the create dialog"
   );
-  const { environments, hasStaging, writableEnvironmentIds } = parentData;
+  const { environments, hasStaging, writableEnvironmentIds, allowEmptyEnvironmentVariableValues } =
+    parentData;
   // Creating a variable is a write, so gate the targets on write access.
   const writableEnvironmentIdSet = new Set(writableEnvironmentIds);
   const lastSubmission = useActionData();
@@ -266,7 +282,7 @@ export default function Page() {
     // TODO: type this
     lastResult: lastSubmission as any,
     onValidate({ formData }) {
-      return parseWithZod(formData, { schema });
+      return parseEnvironmentVariableForm(formData, schema, allowEmptyEnvironmentVariableValues);
     },
     shouldRevalidate: "onSubmit",
     defaultValue: {
diff --git a/apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.environment-variables/route.tsx b/apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.environment-variables/route.tsx
index 2cb1758661b..ec76f56374e 100644
--- a/apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.environment-variables/route.tsx
+++ b/apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.environment-variables/route.tsx
@@ -1,5 +1,6 @@
+import { CheckboxWithLabel } from "~/components/primitives/Checkbox";
 import { getFormProps, getInputProps, useForm } from "@conform-to/react";
-import { parseWithZod } from "@conform-to/zod/v4";
+import { parseEnvironmentVariableForm } from "~/v3/environmentVariables/forms";
 import {
   BookOpenIcon,
   InformationCircleIcon,
@@ -108,6 +109,7 @@ export type MaskedEnvironmentVariable = EnvironmentVariableWithSetValues & {
 };
 
 export type EnvironmentVariablesPageLoaderData = {
+  allowEmptyEnvironmentVariableValues: boolean;
   environmentVariables: MaskedEnvironmentVariable[];
   environments: EnvironmentVariablesEnvironment[];
   hasStaging: boolean;
@@ -142,13 +144,19 @@ export const loader = dashboardLoader(
 
     try {
       const presenter = new EnvironmentVariablesPresenter();
-      const { environmentVariables, environments, hasStaging, vercelIntegration, pagination } =
-        await presenter.call({
-          userId: user.id,
-          projectSlug: projectParam,
-          page: searchParams.page,
-          search: searchParams.search,
-        });
+      const {
+        environmentVariables,
+        environments,
+        hasStaging,
+        vercelIntegration,
+        pagination,
+        allowEmptyEnvironmentVariableValues,
+      } = await presenter.call({
+        userId: user.id,
+        projectSlug: projectParam,
+        page: searchParams.page,
+        search: searchParams.search,
+      });
 
       const accessibleEnvironmentIds = environments
         .filter((env) => ability.can("read", { type: "envvars", envType: env.type }))
@@ -178,6 +186,7 @@ export const loader = dashboardLoader(
 
       return typedjson({
         environmentVariables: masked,
+        allowEmptyEnvironmentVariableValues,
         environments,
         hasStaging,
         vercelIntegration,
@@ -232,7 +241,7 @@ export const action = dashboardAction(
     }
 
     const formData = await request.formData();
-    const submission = parseWithZod(formData, { schema });
+    const submission = parseEnvironmentVariableForm(formData, schema);
 
     if (submission.status !== "success") {
       return json(submission.reply());
@@ -808,6 +817,10 @@ function EditEnvironmentVariablePanel({
   revealAll: boolean;
 }) {
   const [isOpen, setIsOpen] = useState(false);
+  const { allowEmptyEnvironmentVariableValues } =
+    useTypedLoaderData<EnvironmentVariablesPageLoaderData>();
+  const [emptyValueSelected, setEmptyValueSelected] = useState(false);
+  const [draftValue, setDraftValue] = useState(variable.value);
   const fetcher = useFetcher<typeof action>();
   const lastSubmission = fetcher.data as any;
 
@@ -826,13 +839,22 @@ function EditEnvironmentVariablePanel({
     // TODO: type this
     lastResult: lastSubmission as any,
     onValidate({ formData }) {
-      return parseWithZod(formData, { schema });
+      return parseEnvironmentVariableForm(formData, schema, allowEmptyEnvironmentVariableValues);
     },
     shouldRevalidate: "onSubmit",
   });
 
   return (
-    <Dialog open={isOpen} onOpenChange={setIsOpen}>
+    <Dialog
+      open={isOpen}
+      onOpenChange={(open) => {
+        setIsOpen(open);
+        if (open) {
+          setEmptyValueSelected(false);
+          setDraftValue(variable.value);
+        }
+      }}
+    >
       <DialogTrigger asChild>
         <Button variant="small-menu-item" LeadingIcon={PencilSquareIcon} fullWidth textAlignLeft />
       </DialogTrigger>
@@ -861,13 +883,26 @@ function EditEnvironmentVariablePanel({
             <InputGroup fullWidth>
               <Label>Value</Label>
               <Input
-                {...getInputProps(value, { type: "text" })}
+                {...getInputProps(value, { type: "text", value: false })}
                 placeholder={variable.isSecret ? "Set new secret value" : "Not set"}
-                defaultValue={variable.value}
+                value={emptyValueSelected ? "" : draftValue}
+                onChange={(event) => setDraftValue(event.currentTarget.value)}
+                disabled={emptyValueSelected}
                 type={"text"}
                 autoComplete="off"
               />
+              {emptyValueSelected && <input type="hidden" name={value.name} value="" />}
               <FormError id={value.errorId}>{value.errors}</FormError>
+              {variable.isSecret && allowEmptyEnvironmentVariableValues && (
+                <CheckboxWithLabel
+                  name="setEmptyValue"
+                  value="true"
+                  variant="description"
+                  label="Set to an empty string"
+                  description="Replaces the secret with an empty string and keeps the variable."
+                  onChange={setEmptyValueSelected}
+                />
+              )}
             </InputGroup>
 
             <FormError>{form.errors}</FormError>
@@ -909,7 +944,7 @@ function DeleteEnvironmentVariableButton({
     // TODO: type this
     lastResult: lastSubmission as any,
     onValidate({ formData }) {
-      return parseWithZod(formData, { schema });
+      return parseEnvironmentVariableForm(formData, schema);
     },
     shouldRevalidate: "onSubmit",
   });
diff --git a/apps/webapp/app/routes/api.v1.projects.$projectRef.envvars.$slug.$name.ts b/apps/webapp/app/routes/api.v1.projects.$projectRef.envvars.$slug.$name.ts
index ecec13a27f0..7ce55c43ee0 100644
--- a/apps/webapp/app/routes/api.v1.projects.$projectRef.envvars.$slug.$name.ts
+++ b/apps/webapp/app/routes/api.v1.projects.$projectRef.envvars.$slug.$name.ts
@@ -103,7 +103,6 @@ export async function action({ params, request }: ActionFunctionArgs) {
             },
           ],
           id: variable.id,
-          keepEmptyValues: true,
         });
 
         if (result.success) {
diff --git a/apps/webapp/app/routes/api.v1.projects.$projectRef.envvars.ts b/apps/webapp/app/routes/api.v1.projects.$projectRef.envvars.ts
index 92b29f1a651..713bde10df5 100644
--- a/apps/webapp/app/routes/api.v1.projects.$projectRef.envvars.ts
+++ b/apps/webapp/app/routes/api.v1.projects.$projectRef.envvars.ts
@@ -1,5 +1,6 @@
 import { type LoaderFunctionArgs, json } from "@remix-run/server-runtime";
 import { z } from "zod";
+import { emptyEnvironmentVariableValuesEnabled } from "~/v3/environmentVariables/emptyValuesFlag.server";
 import { prisma } from "~/db.server";
 import { env } from "~/env.server";
 import { authenticateApiKeyWithScope } from "~/services/apiAuth.server";
@@ -31,6 +32,7 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
   const { projectRef } = parsedParams.data;
 
   const project = await prisma.project.findFirst({
+    include: { organization: { select: { featureFlags: true } } },
     where: {
       externalRef: projectRef,
       environments: {
@@ -66,6 +68,9 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
   );
 
   return json({
+    allowEmptyEnvironmentVariableValues: await emptyEnvironmentVariableValuesEnabled(
+      project.organization.featureFlags
+    ),
     variables: environmentVariablesForApiKeyResponse(variables, authenticationResult.apiKey),
   });
 }
diff --git a/apps/webapp/app/v3/environmentVariables/emptyEnvironmentValuesRollout.test.ts b/apps/webapp/app/v3/environmentVariables/emptyEnvironmentValuesRollout.test.ts
new file mode 100644
index 00000000000..025bbe3db15
--- /dev/null
+++ b/apps/webapp/app/v3/environmentVariables/emptyEnvironmentValuesRollout.test.ts
@@ -0,0 +1,293 @@
+import { afterEach, describe, expect, vi } from "vitest";
+import type { PrismaClient } from "@trigger.dev/database";
+import { spawnSync } from "node:child_process";
+
+// External HTTP is stubbed intentionally for rollout verification.
+// Route/repository singletons use the same real, isolated Testcontainers database.
+const database = vi.hoisted(() => ({ client: undefined as PrismaClient | undefined }));
+vi.mock("~/db.server", async () => {
+  const actual = await import("@trigger.dev/database");
+  const proxy = new Proxy(
+    {},
+    {
+      get(_target, property) {
+        const client = database.client;
+        if (!client) throw new Error("Test database not connected");
+        const value = Reflect.get(client, property);
+        return typeof value === "function" ? value.bind(client) : value;
+      },
+    }
+  );
+  return {
+    ...actual,
+    prisma: proxy,
+    $replica: proxy,
+    $transaction: (client: PrismaClient, nameOrFn: unknown, fnOrOptions?: unknown) =>
+      client.$transaction((typeof nameOrFn === "string" ? fnOrOptions : nameOrFn) as never),
+  };
+});
+
+import { postgresTest } from "@internal/testcontainers";
+import { VercelIntegrationRepository } from "~/models/vercelIntegration.server";
+import { getSecretStore } from "~/services/secrets/secretStore.server";
+import { EnvironmentVariablesRepository } from "~/v3/environmentVariables/environmentVariablesRepository.server";
+import {
+  action as updateVariable,
+  loader as readVariable,
+} from "~/routes/api.v1.projects.$projectRef.envvars.$slug.$name";
+import { loader as readCapability } from "~/routes/api.v1.projects.$projectRef.envvars";
+import { action as importVariables } from "~/routes/api.v1.projects.$projectRef.envvars.$slug.import";
+import {
+  createRuntimeEnvironment,
+  createTestOrgProjectWithMember,
+} from "../../../test/fixtures/environmentVariablesFixtures";
+
+vi.setConfig({ testTimeout: 60_000 });
+afterEach(() => vi.unstubAllGlobals());
+
+function stubVercel(emptyValue: string) {
+  const originalFetch = globalThis.fetch;
+  const calls: string[] = [];
+  let fail = false;
+  const env = (id: string, key: string, value: string, type = "plain") => ({
+    id,
+    key,
+    value,
+    type,
+    target: ["production"],
+  });
+  const project = [
+    env("plain", "PLAIN", emptyValue),
+    env("encrypted", "ENCRYPTED", "ciphertext", "encrypted"),
+    env("collision", "COLLISION", emptyValue),
+    env("ordinary", "ORDINARY", "updated"),
+    env("sensitive", "SENSITIVE", "", "sensitive"),
+  ];
+  const shared = [
+    env("shared", "SHARED", emptyValue),
+    env("fallback", "COLLISION", "shared-fallback"),
+    env("encrypted-fallback", "ENCRYPTED", "encrypted-shared-fallback"),
+  ];
+  vi.stubGlobal("fetch", async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = new URL(input instanceof Request ? input.url : input.toString());
+    if (url.hostname === "localhost" && url.port === "18374") return originalFetch(input, init);
+    if (url.hostname !== "api.vercel.com")
+      throw new Error(`Unexpected external request: ${url.origin}`);
+    const method = input instanceof Request ? input.method : (init?.method ?? "GET");
+    expect(method).toBe("GET");
+    calls.push(url.pathname);
+    if (fail)
+      return Response.json(
+        { error: { code: "forbidden", message: "Fixture denied" } },
+        { status: 403 }
+      );
+    if (url.pathname === "/v1/env")
+      return Response.json({ data: shared, pagination: { next: null } });
+    if (/\/projects\/prj_fixture\/env$/.test(url.pathname)) return Response.json({ envs: project });
+    if (/\/projects\/prj_fixture\/env\/encrypted$/.test(url.pathname))
+      return Response.json(env("encrypted", "ENCRYPTED", emptyValue, "encrypted"));
+    if (url.pathname === "/v1/env/shared")
+      return Response.json(env("shared", "SHARED", emptyValue));
+    throw new Error(`Unexpected Vercel request: ${url.pathname}`);
+  });
+  return {
+    calls,
+    deny: () => {
+      fail = true;
+    },
+  };
+}
+
+async function fixture(prisma: PrismaClient) {
+  database.client = prisma;
+  const data = await createTestOrgProjectWithMember(prisma);
+  const environment = await createRuntimeEnvironment(prisma, {
+    projectId: data.project.id,
+    organizationId: data.organization.id,
+    type: "PRODUCTION",
+    slug: "prod",
+    apiKey: `tr_prod_${data.project.id}`,
+  });
+  const repository = new EnvironmentVariablesRepository(prisma, prisma);
+  const read = async () =>
+    Object.fromEntries(
+      (await repository.getEnvironment(data.project.id, environment.id)).map((v) => [
+        v.key,
+        v.value,
+      ])
+    );
+  const setFlag = (enabled: boolean) =>
+    prisma.organization.update({
+      where: { id: data.organization.id },
+      data: { featureFlags: { allowEmptyEnvironmentVariableValues: enabled } },
+    });
+  return { ...data, environment, repository, read, setFlag };
+}
+
+describe("empty env rollout through production boundaries", () => {
+  for (const emptyValue of ["", " \t "]) {
+    postgresTest(
+      `Vercel pull respects off/on/isolation/rollback for ${JSON.stringify(emptyValue)}`,
+      async ({ prisma }) => {
+        const operations: string[] = [];
+        const observed = prisma.$extends({
+          query: {
+            $allModels: {
+              $allOperations: async ({ model, operation, args, query }) => {
+                operations.push(`${model}.${operation}`);
+                return query(args);
+              },
+            },
+          },
+        }) as unknown as PrismaClient;
+        const f = await fixture(observed);
+        const other = await fixture(observed);
+        const external = stubVercel(emptyValue);
+        const tokenKey = `vercel-fixture-${f.project.id}`;
+        await getSecretStore("DATABASE", { prismaClient: prisma }).setSecret(tokenKey, {
+          accessToken: "fixture-only-token",
+        });
+        const integration = await prisma.organizationIntegration.create({
+          data: {
+            friendlyId: `int_${f.project.id}`,
+            service: "VERCEL",
+            integrationData: {},
+            organization: { connect: { id: f.organization.id } },
+            tokenReference: { create: { key: tokenKey } },
+          },
+          include: { tokenReference: true },
+        });
+        const pull = (projectId = f.project.id) =>
+          VercelIntegrationRepository.pullEnvVarsFromVercel({
+            projectId,
+            vercelProjectId: "prj_fixture",
+            teamId: "team_fixture",
+            syncEnvVarsMapping: {},
+            orgIntegration: integration,
+          });
+        await f.repository.create(f.project.id, {
+          override: true,
+          environmentIds: [f.environment.id],
+          variables: [{ key: "PLAIN", value: "original" }],
+          lastUpdatedBy: { type: "user", userId: f.user.id },
+        });
+        operations.length = 0;
+        const off = await pull();
+        expect(off.isOk()).toBe(true);
+        if (off.isOk()) expect(off.value.errors).toEqual([]);
+        expect(await f.read()).toEqual({
+          PLAIN: "original",
+          ENCRYPTED: "encrypted-shared-fallback",
+          COLLISION: "shared-fallback",
+          ORDINARY: "updated",
+        });
+        expect(operations.filter((op) => op === "FeatureFlag.findFirst")).toHaveLength(1);
+        await f.setFlag(true);
+        external.calls.length = 0;
+        const on = await pull();
+        expect(on.isOk()).toBe(true);
+        if (on.isOk()) expect(on.value.errors).toEqual([]);
+        expect(await f.read()).toEqual({
+          PLAIN: emptyValue,
+          ENCRYPTED: emptyValue,
+          COLLISION: emptyValue,
+          SHARED: emptyValue,
+          ORDINARY: "updated",
+        });
+        expect(external.calls.filter((p) => p === "/v1/env")).toHaveLength(1);
+        expect(external.calls.filter((p) => p.endsWith("/encrypted"))).toHaveLength(1);
+        expect(external.calls.some((p) => p.endsWith("/shared") || p.endsWith("/sensitive"))).toBe(
+          false
+        );
+        operations.length = 0;
+        const repeat = await pull();
+        expect(repeat.isOk() && repeat.value.syncedCount).toBe(0);
+        expect(
+          operations.filter((op) =>
+            /\.(create|createMany|update|updateMany|upsert|delete|deleteMany)$/.test(op)
+          )
+        ).toEqual([]);
+        expect(operations.filter((op) => op === "FeatureFlag.findFirst")).toHaveLength(0);
+        await pull(other.project.id);
+        expect(await other.read()).toEqual({
+          COLLISION: "shared-fallback",
+          ENCRYPTED: "encrypted-shared-fallback",
+          ORDINARY: "updated",
+        });
+        external.deny();
+        const failed = await pull();
+        expect(failed.isOk() && failed.value.errors.length).toBeGreaterThan(0);
+        expect((await f.read()).PLAIN).toBe(emptyValue);
+        await f.setFlag(false);
+        const stored = await f.read();
+        expect(stored.PLAIN).toBe(emptyValue);
+        const child = spawnSync(
+          process.execPath,
+          [
+            "-e",
+            'process.stdout.write(JSON.stringify({present:Object.hasOwn(process.env,"PLAIN"),empty:process.env.PLAIN===""}))',
+          ],
+          { env: { ...process.env, ...stored }, encoding: "utf8" }
+        );
+        expect(child.status).toBe(0);
+        expect(JSON.parse(child.stdout)).toEqual({ present: true, empty: emptyValue === "" });
+      }
+    );
+  }
+
+  postgresTest(
+    "REST update and billing-shaped import enforce the current organization flag",
+    async ({ prisma }) => {
+      const f = await fixture(prisma);
+      const params = { projectRef: f.project.externalRef, slug: "prod", name: "REST_EMPTY" };
+      const request = (method: string, body?: unknown) =>
+        new Request("http://localhost/api/envvars", {
+          method,
+          headers: {
+            authorization: `Bearer ${f.environment.apiKey}`,
+            "content-type": "application/json",
+          },
+          ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+      await f.repository.create(f.project.id, {
+        override: true,
+        environmentIds: [f.environment.id],
+        variables: [{ key: "REST_EMPTY", value: "original" }],
+      });
+      const capability = async () => {
+        const response = await readCapability({ params, context: {}, request: request("GET") });
+        expect(response.status).toBe(200);
+        return response.json();
+      };
+      expect((await capability()).allowEmptyEnvironmentVariableValues).toBe(false);
+      const update = () =>
+        updateVariable({ params, context: {}, request: request("PUT", { value: "" }) });
+      const off = await update();
+      expect(off?.status).toBe(400);
+      expect((await f.read()).REST_EMPTY).toBe("original");
+      const billingBody = {
+        variables: { BILLING_EMPTY: "", BILLING_NORMAL: "updated" },
+        override: true,
+        source: { type: "integration", integration: "vercel" },
+      };
+      const sync = () =>
+        importVariables({ params, context: {}, request: request("POST", billingBody) });
+      expect((await sync()).status).toBe(200);
+      expect((await f.read()).BILLING_EMPTY).toBeUndefined();
+      await f.setFlag(true);
+      expect((await capability()).allowEmptyEnvironmentVariableValues).toBe(true);
+      expect((await update())?.status).toBe(200);
+      expect((await sync()).status).toBe(200);
+      const response = await readVariable({ params, context: {}, request: request("GET") });
+      expect(response.status).toBe(200);
+      expect(await response.json()).toMatchObject({ name: "REST_EMPTY", value: "" });
+      expect((await f.read()).BILLING_EMPTY).toBe("");
+      await f.setFlag(false);
+      expect((await update())?.status).toBe(400);
+      const rolledBack = await capability();
+      expect(rolledBack.allowEmptyEnvironmentVariableValues).toBe(false);
+      expect(rolledBack.variables.REST_EMPTY).toBe("");
+      expect((await f.read()).REST_EMPTY).toBe("");
+    }
+  );
+});
diff --git a/apps/webapp/app/v3/environmentVariables/emptyValuesFlag.server.ts b/apps/webapp/app/v3/environmentVariables/emptyValuesFlag.server.ts
new file mode 100644
index 00000000000..bceeabb31ce
--- /dev/null
+++ b/apps/webapp/app/v3/environmentVariables/emptyValuesFlag.server.ts
@@ -0,0 +1,34 @@
+import { prisma, type PrismaClient } from "~/db.server";
+import { FEATURE_FLAG } from "~/v3/featureFlags";
+import { makeFlag } from "~/v3/featureFlags.server";
+
+export const EMPTY_ENV_VALUES_DISABLED =
+  "Empty environment variable values are not enabled for this organization.";
+
+export async function emptyEnvironmentVariableValuesEnabled(
+  organizationFeatureFlags: unknown,
+  client: PrismaClient = prisma
+): Promise<boolean> {
+  const enabled = await makeFlag(client)({
+    key: FEATURE_FLAG.allowEmptyEnvironmentVariableValues,
+    defaultValue: false,
+    overrides:
+      organizationFeatureFlags && typeof organizationFeatureFlags === "object"
+        ? (organizationFeatureFlags as Record<string, unknown>)
+        : undefined,
+  });
+  return enabled;
+}
+
+export async function emptyEnvironmentVariableValuesEnabledForProject(
+  projectId: string,
+  client: PrismaClient = prisma
+): Promise<boolean> {
+  const project = await client.project.findFirst({
+    where: { id: projectId, deletedAt: null },
+    select: { organization: { select: { featureFlags: true } } },
+  });
+  return project
+    ? emptyEnvironmentVariableValuesEnabled(project.organization.featureFlags, client)
+    : false;
+}
diff --git a/apps/webapp/app/v3/environmentVariables/environmentVariablesRepository.server.ts b/apps/webapp/app/v3/environmentVariables/environmentVariablesRepository.server.ts
index b38e069e637..76cc5345149 100644
--- a/apps/webapp/app/v3/environmentVariables/environmentVariablesRepository.server.ts
+++ b/apps/webapp/app/v3/environmentVariables/environmentVariablesRepository.server.ts
@@ -1,3 +1,7 @@
+import {
+  EMPTY_ENV_VALUES_DISABLED,
+  emptyEnvironmentVariableValuesEnabled,
+} from "./emptyValuesFlag.server";
 import type { AuthenticatedEnvironment } from "@trigger.dev/core/v3/auth/environment";
 import {
   boundedIn,
@@ -59,12 +63,17 @@ export class EnvironmentVariablesRepository implements Repository {
   ) {}
 
   async create(projectId: string, options: CreateEnvironmentVariables): Promise<CreateResult> {
+    if (options.environmentIds.length === 0) {
+      return { success: false as const, error: "At least one environment is required" };
+    }
+
     const project = await this.prismaClient.project.findFirst({
       where: {
         id: projectId,
         deletedAt: null,
       },
       select: {
+        organization: { select: { featureFlags: true } },
         environments: {
           select: {
             id: true,
@@ -106,8 +115,25 @@ export class EnvironmentVariablesRepository implements Repository {
     let values = removeBlacklistedVariables(options.variables);
     const removedBlacklisted = values.length !== options.variables.length;
 
-    //get rid of empty variables
-    values = values.filter((v) => v.key.trim() !== "" && v.value.trim() !== "");
+    //get rid of variables with an empty key (an empty value is a valid value)
+    values = values.filter((v) => v.key.trim() !== "");
+    if (
+      values.some((v) => v.value.trim() === "") &&
+      !(await emptyEnvironmentVariableValuesEnabled(
+        project.organization.featureFlags,
+        this.prismaClient
+      ))
+    ) {
+      values = values.filter((v) => v.value.trim() !== "");
+      // Automated sync must remain a no-op when every supplied value is disabled.
+      if (
+        values.length === 0 &&
+        options.lastUpdatedBy?.type === "integration" &&
+        !removedBlacklisted
+      ) {
+        return { success: true as const };
+      }
+    }
     if (values.length === 0) {
       return {
         success: false as const,
@@ -295,6 +321,7 @@ export class EnvironmentVariablesRepository implements Repository {
         deletedAt: null,
       },
       select: {
+        organization: { select: { featureFlags: true } },
         environments: {
           select: {
             id: true,
@@ -313,22 +340,18 @@ export class EnvironmentVariablesRepository implements Repository {
       return { success: false as const, error: `Environment not found` };
     }
 
-    //get rid of empty strings
-    let values = options.values.filter((v) => v.value.trim() !== "");
-
-    //add in empty values for environments that don't have a value
-    const environmentIds = project.environments.map((e) => e.id);
-
-    if (!options.keepEmptyValues) {
-      for (const environmentId of environmentIds) {
-        if (!values.some((v) => v.environmentId === environmentId)) {
-          values.push({
-            environmentId,
-            value: "",
-          });
-        }
-      }
+    // An empty string is a valid, distinct value stored verbatim, never
+    // treated as "absent" or "delete". Removal is a separate operation.
+    if (
+      options.values.some((v) => v.value.trim() === "") &&
+      !(await emptyEnvironmentVariableValuesEnabled(
+        project.organization.featureFlags,
+        this.prismaClient
+      ))
+    ) {
+      return { success: false as const, error: EMPTY_ENV_VALUES_DISABLED };
     }
+    const values = options.values;
 
     const environmentVariable = await this.prismaClient.environmentVariable.findFirst({
       select: {
@@ -360,41 +383,23 @@ export class EnvironmentVariablesRepository implements Repository {
           });
 
           if (existingValue && existingValue.valueReferenceId) {
-            if (value.value === "") {
-              //delete the value
-              await secretStore.deleteSecret(key);
-              await tx.secretReference.delete({
-                where: {
-                  id: existingValue.valueReferenceId,
-                },
-              });
-              await tx.environmentVariableValue.delete({
-                where: {
-                  variableId_environmentId: {
-                    variableId: environmentVariable.id,
-                    environmentId: value.environmentId,
-                  },
-                },
-              });
-            } else {
-              await secretStore.setSecret<{ secret: string }>(key, {
-                secret: value.value,
-              });
-              await tx.environmentVariableValue.update({
-                where: {
-                  variableId_environmentId: {
-                    variableId: environmentVariable.id,
-                    environmentId: value.environmentId,
-                  },
+            await secretStore.setSecret<{ secret: string }>(key, {
+              secret: value.value,
+            });
+            await tx.environmentVariableValue.update({
+              where: {
+                variableId_environmentId: {
+                  variableId: environmentVariable.id,
+                  environmentId: value.environmentId,
                 },
-                data: {
-                  version: {
-                    increment: 1,
-                  },
-                  lastUpdatedBy: options.lastUpdatedBy ? options.lastUpdatedBy : undefined,
+              },
+              data: {
+                version: {
+                  increment: 1,
                 },
-              });
-            }
+                lastUpdatedBy: options.lastUpdatedBy ? options.lastUpdatedBy : undefined,
+              },
+            });
             continue;
           }
 
@@ -440,6 +445,7 @@ export class EnvironmentVariablesRepository implements Repository {
         deletedAt: null,
       },
       select: {
+        organization: { select: { featureFlags: true } },
         environments: {
           select: {
             id: true,
@@ -466,6 +472,7 @@ export class EnvironmentVariablesRepository implements Repository {
           },
           select: {
             valueReferenceId: true,
+            isSecret: true,
           },
         },
       },
@@ -482,6 +489,27 @@ export class EnvironmentVariablesRepository implements Repository {
       return { success: false as const, error: "Environment variable value not found" };
     }
 
+    const value = options.setEmptyValue === "true" ? "" : options.value;
+    if (
+      value.trim() === "" &&
+      !(await emptyEnvironmentVariableValuesEnabled(
+        project.organization.featureFlags,
+        this.prismaClient
+      ))
+    ) {
+      return { success: false as const, error: EMPTY_ENV_VALUES_DISABLED };
+    }
+    if (
+      environmentVariable.values[0].isSecret &&
+      value === "" &&
+      options.setEmptyValue !== "true"
+    ) {
+      return {
+        success: false as const,
+        error: 'Enter a new secret value or select "Set to an empty string".',
+      };
+    }
+
     try {
       await $transaction(this.prismaClient, "edit env var value", async (tx) => {
         const secretStore = getSecretStore("DATABASE", {
@@ -490,7 +518,7 @@ export class EnvironmentVariablesRepository implements Repository {
 
         const key = secretKey(projectId, options.environmentId, environmentVariable.key);
         await secretStore.setSecret<{ secret: string }>(key, {
-          secret: options.value,
+          secret: value,
         });
 
         await tx.environmentVariableValue.update({
diff --git a/apps/webapp/app/v3/environmentVariables/forms.ts b/apps/webapp/app/v3/environmentVariables/forms.ts
new file mode 100644
index 00000000000..481cc3bc4dd
--- /dev/null
+++ b/apps/webapp/app/v3/environmentVariables/forms.ts
@@ -0,0 +1,29 @@
+import { parseWithZod } from "@conform-to/zod/v4";
+import { configureCoercion } from "@conform-to/zod/v4/future";
+import type { z } from "zod";
+import { EnvironmentVariableValue } from "./repository";
+
+function formCoercion(allowEmptyValues: boolean) {
+  return configureCoercion({
+    // Preserve only the value field; other fields keep Conform's normal coercion.
+    customize: (schema) =>
+      schema === EnvironmentVariableValue
+        ? (value) =>
+            !allowEmptyValues && typeof value === "string" && value.trim() === ""
+              ? undefined
+              : value
+        : null,
+  });
+}
+
+export function parseEnvironmentVariableForm<Schema extends z.ZodType>(
+  formData: FormData,
+  schema: Schema,
+  allowEmptyValues = true
+) {
+  const { coerceFormValue } = formCoercion(allowEmptyValues);
+  return parseWithZod(formData, {
+    schema: coerceFormValue(schema),
+    disableAutoCoercion: true,
+  });
+}
diff --git a/apps/webapp/app/v3/environmentVariables/repository.ts b/apps/webapp/app/v3/environmentVariables/repository.ts
index ba0d70b6e04..89f1000fc64 100644
--- a/apps/webapp/app/v3/environmentVariables/repository.ts
+++ b/apps/webapp/app/v3/environmentVariables/repository.ts
@@ -47,7 +47,6 @@ export const EditEnvironmentVariable = z.object({
       value: z.string(),
     })
   ),
-  keepEmptyValues: z.boolean().optional(),
   lastUpdatedBy: EnvironmentVariableUpdaterSchema.optional(),
 });
 export type EditEnvironmentVariable = z.infer<typeof EditEnvironmentVariable>;
@@ -64,10 +63,15 @@ export const DeleteEnvironmentVariableValue = z.object({
 });
 export type DeleteEnvironmentVariableValue = z.infer<typeof DeleteEnvironmentVariableValue>;
 
+// Forms preserve explicit empty strings through their custom coercion.
+// A missing field is still invalid.
+export const EnvironmentVariableValue = z.string();
+
 export const EditEnvironmentVariableValue = z.object({
   id: z.string(),
   environmentId: z.string(),
-  value: z.string(),
+  value: EnvironmentVariableValue,
+  setEmptyValue: z.literal("true").optional(),
   lastUpdatedBy: EnvironmentVariableUpdaterSchema.optional(),
 });
 export type EditEnvironmentVariableValue = z.infer<typeof EditEnvironmentVariableValue>;
diff --git a/apps/webapp/app/v3/featureFlags.ts b/apps/webapp/app/v3/featureFlags.ts
index cce2bb4ba9a..cee20ff990e 100644
--- a/apps/webapp/app/v3/featureFlags.ts
+++ b/apps/webapp/app/v3/featureFlags.ts
@@ -2,6 +2,7 @@ import { z } from "zod";
 import { DeployBuildPath } from "@trigger.dev/core/v3";
 
 export const FEATURE_FLAG = {
+  allowEmptyEnvironmentVariableValues: "allowEmptyEnvironmentVariableValues",
   defaultWorkerInstanceGroupId: "defaultWorkerInstanceGroupId",
   taskEventRepository: "taskEventRepository",
   hasQueryAccess: "hasQueryAccess",
@@ -49,6 +50,7 @@ export const FEATURE_FLAG = {
 } as const;
 
 export const FeatureFlagCatalog = {
+  [FEATURE_FLAG.allowEmptyEnvironmentVariableValues]: z.boolean(),
   [FEATURE_FLAG.defaultWorkerInstanceGroupId]: z.string(),
   [FEATURE_FLAG.taskEventRepository]: z.enum(["clickhouse", "clickhouse_v2", "postgres"]),
   [FEATURE_FLAG.hasQueryAccess]: z.coerce.boolean(),
diff --git a/apps/webapp/app/v3/vercel/environmentVariableValues.ts b/apps/webapp/app/v3/vercel/environmentVariableValues.ts
new file mode 100644
index 00000000000..0808a2d60bd
--- /dev/null
+++ b/apps/webapp/app/v3/vercel/environmentVariableValues.ts
@@ -0,0 +1,57 @@
+import type { ResponseBodyEnvs } from "@vercel/sdk/models/filterprojectenvsop";
+import type { VercelEnvironmentVariableValue } from "~/models/vercelIntegration.server";
+
+export function normalizeTarget(target: string[] | string | undefined): string[] {
+  if (Array.isArray(target)) return target.filter(Boolean);
+  if (typeof target === "string") return [target];
+  return [];
+}
+
+export function isVercelSecretType(type: string): boolean {
+  return type === "secret" || type === "sensitive";
+}
+
+export function toVercelEnvironmentVariableValue(
+  env: ResponseBodyEnvs,
+  allowEmptyValues = true
+): VercelEnvironmentVariableValue | null {
+  if (
+    env.value === undefined ||
+    env.value === null ||
+    (!allowEmptyValues && env.value.trim() === "")
+  )
+    return null;
+  return {
+    key: env.key,
+    value: env.value,
+    target: normalizeTarget(env.target),
+    type: env.type,
+    isSecret: isVercelSecretType(env.type),
+  };
+}
+
+/** Enabled inline values are authoritative; disabled blank values allow a fetched fallback. */
+export async function resolveVercelSharedValue(
+  inlineValue: string | null | undefined,
+  fetchValue: () => Promise<string | null>,
+  allowEmptyValues = true
+): Promise<string | null> {
+  if (
+    inlineValue !== undefined &&
+    inlineValue !== null &&
+    (allowEmptyValues || inlineValue.trim() !== "")
+  ) {
+    return inlineValue;
+  }
+  const value = await fetchValue();
+  return !allowEmptyValues && value !== null && value.trim() === "" ? null : value;
+}
+
+/** A project key takes precedence even when its value is empty. */
+export function mergeVercelEnvironmentVariableValues<
+  Project extends { key: string },
+  Shared extends { key: string },
+>(project: Project[], shared: Shared[]): Array<Project | Shared> {
+  const projectKeys = new Set(project.map((variable) => variable.key));
+  return [...project, ...shared.filter((variable) => !projectKeys.has(variable.key))];
+}
diff --git a/apps/webapp/test/environmentVariablesForms.test.ts b/apps/webapp/test/environmentVariablesForms.test.ts
new file mode 100644
index 00000000000..4eda7682bd3
--- /dev/null
+++ b/apps/webapp/test/environmentVariablesForms.test.ts
@@ -0,0 +1,110 @@
+import { parseEnvironmentVariableForm } from "~/v3/environmentVariables/forms";
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+import {
+  EditEnvironmentVariableValue,
+  EnvironmentVariableValue,
+} from "~/v3/environmentVariables/repository";
+
+describe("Environment variable edit form", () => {
+  test("accepts an empty value", () => {
+    const formData = new FormData();
+    formData.set("id", "var_123");
+    formData.set("environmentId", "env_123");
+    formData.set("value", "");
+
+    const submission = parseEnvironmentVariableForm(formData, EditEnvironmentVariableValue);
+
+    expect(submission.status).toBe("success");
+    if (submission.status === "success") {
+      expect(submission.value.value).toBe("");
+    }
+  });
+
+  test("accepts a non-empty value", () => {
+    const formData = new FormData();
+    formData.set("id", "var_123");
+    formData.set("environmentId", "env_123");
+    formData.set("value", "hello");
+
+    const submission = parseEnvironmentVariableForm(formData, EditEnvironmentVariableValue);
+
+    expect(submission.status).toBe("success");
+    if (submission.status === "success") {
+      expect(submission.value.value).toBe("hello");
+    }
+  });
+});
+
+describe("EnvironmentVariableValue field (shared by create and edit forms)", () => {
+  test("preserves an empty value through conform coercion", () => {
+    const formData = new FormData();
+    formData.set("value", "");
+
+    const submission = parseEnvironmentVariableForm(
+      formData,
+      z.object({ value: EnvironmentVariableValue })
+    );
+
+    expect(submission.status).toBe("success");
+    if (submission.status === "success") {
+      expect(submission.value.value).toBe("");
+    }
+  });
+});
+
+test("missing values are rejected, including nested create rows", () => {
+  const edit = new FormData();
+  edit.set("id", "var_123");
+  edit.set("environmentId", "env_123");
+  expect(parseEnvironmentVariableForm(edit, EditEnvironmentVariableValue).status).toBe("error");
+  const schema = z.object({
+    variables: z.array(z.object({ key: z.string(), value: EnvironmentVariableValue })),
+  });
+  const create = new FormData();
+  create.set("variables[0].key", "EMPTY");
+  expect(parseEnvironmentVariableForm(create, schema).status).toBe("error");
+  create.set("variables[0].value", "");
+  const result = parseEnvironmentVariableForm(create, schema);
+  expect(result.status).toBe("success");
+  if (result.status === "success")
+    expect(result.value.variables).toEqual([{ key: "EMPTY", value: "" }]);
+});
+
+test("preserves the explicit empty-secret choice for the write handler", () => {
+  const form = new FormData();
+  form.set("id", "var_123");
+  form.set("environmentId", "env_123");
+  // The disabled text input is replaced by a hidden empty value field.
+  form.set("value", "");
+  form.set("setEmptyValue", "true");
+  const result = parseEnvironmentVariableForm(form, EditEnvironmentVariableValue);
+  expect(result.status).toBe("success");
+  if (result.status === "success") {
+    expect(result.value.value).toBe("");
+    expect(result.value.setEmptyValue).toBe("true");
+  }
+});
+
+test("preserves whitespace when empty is not selected", () => {
+  const form = new FormData();
+  form.set("id", "var_123");
+  form.set("environmentId", "env_123");
+  form.set("value", "   ");
+  const result = parseEnvironmentVariableForm(form, EditEnvironmentVariableValue);
+  expect(result.status).toBe("success");
+  if (result.status === "success") expect(result.value.value).toBe("   ");
+});
+
+test("disabled rollout rejects empty form values while enabled accepts them", () => {
+  const form = new FormData();
+  form.set("id", "var_123");
+  form.set("environmentId", "env_123");
+  form.set("value", "");
+  expect(parseEnvironmentVariableForm(form, EditEnvironmentVariableValue, false).status).toBe(
+    "error"
+  );
+  expect(parseEnvironmentVariableForm(form, EditEnvironmentVariableValue, true).status).toBe(
+    "success"
+  );
+});
diff --git a/apps/webapp/test/environmentVariablesRepository.test.ts b/apps/webapp/test/environmentVariablesRepository.test.ts
index b5661c89cbe..445f2436311 100644
--- a/apps/webapp/test/environmentVariablesRepository.test.ts
+++ b/apps/webapp/test/environmentVariablesRepository.test.ts
@@ -18,13 +18,25 @@ vi.mock("~/db.server", () => ({
 }));
 
 import { postgresTest } from "@internal/testcontainers";
+import { emptyEnvironmentVariableValuesEnabled } from "~/v3/environmentVariables/emptyValuesFlag.server";
 import { EnvironmentVariablesRepository } from "~/v3/environmentVariables/environmentVariablesRepository.server";
 import {
   createEnvironmentVariable,
   createRuntimeEnvironment,
-  createTestOrgProjectWithMember,
+  createTestOrgProjectWithMember as createBaseOrgProjectWithMember,
 } from "./fixtures/environmentVariablesFixtures";
 
+async function createTestOrgProjectWithMember(
+  prisma: Parameters<typeof createBaseOrgProjectWithMember>[0]
+) {
+  const data = await createBaseOrgProjectWithMember(prisma);
+  await prisma.organization.update({
+    where: { id: data.organization.id },
+    data: { featureFlags: { allowEmptyEnvironmentVariableValues: true } },
+  });
+  return data;
+}
+
 vi.setConfig({ testTimeout: 60_000 });
 
 describe("EnvironmentVariablesRepository.getVariableValuesForKeys", () => {
@@ -256,4 +268,496 @@ describe("EnvironmentVariablesRepository.getVariableValuesForKeys", () => {
       expect(result.success).toBe(true);
     }
   );
+
+  postgresTest(
+    "create() rejects an empty environmentIds array without orphaning the key",
+    async ({ prisma }) => {
+      const { user, project } = await createTestOrgProjectWithMember(prisma);
+
+      const repository = new EnvironmentVariablesRepository(prisma, prisma);
+
+      const result = await repository.create(project.id, {
+        override: true,
+        environmentIds: [],
+        variables: [{ key: "ORPHAN_KEY", value: "v" }],
+        isSecret: false,
+        lastUpdatedBy: { type: "user", userId: user.id },
+      });
+
+      expect(result.success).toBe(false);
+
+      // The variable key must not be created when there is nowhere to store it.
+      const variable = await prisma.environmentVariable.findFirst({
+        where: { projectId: project.id, key: "ORPHAN_KEY" },
+      });
+      expect(variable).toBeNull();
+    }
+  );
 });
+
+describe("EnvironmentVariablesRepository empty values", () => {
+  postgresTest(
+    "edit() stores an empty value as a distinct, retrievable value",
+    async ({ prisma }) => {
+      const { user, organization, project } = await createTestOrgProjectWithMember(prisma);
+      const environment = await createRuntimeEnvironment(prisma, {
+        projectId: project.id,
+        organizationId: organization.id,
+        type: "PRODUCTION",
+      });
+
+      const repository = new EnvironmentVariablesRepository(prisma, prisma);
+
+      await createEnvironmentVariable(repository, project.id, {
+        environmentId: environment.id,
+        key: "EMPTY_ME",
+        value: "not-empty",
+        userId: user.id,
+      });
+
+      const variable = await prisma.environmentVariable.findFirstOrThrow({
+        where: { projectId: project.id, key: "EMPTY_ME" },
+      });
+
+      const result = await repository.edit(project.id, {
+        id: variable.id,
+        values: [{ environmentId: environment.id, value: "" }],
+        lastUpdatedBy: { type: "user", userId: user.id },
+      });
+
+      expect(result.success).toBe(true);
+
+      // The value is stored and round-trips as "", not deleted, not absent.
+      const values = await repository.getVariableValuesForKeys(project.id, [
+        { environmentId: environment.id, key: "EMPTY_ME" },
+      ]);
+      expect(values.get(`${environment.id}:EMPTY_ME`)).toBe("");
+
+      // The value row is retained.
+      const valueRows = await prisma.environmentVariableValue.findMany({
+        where: { variableId: variable.id, environmentId: environment.id },
+      });
+      expect(valueRows).toHaveLength(1);
+    }
+  );
+
+  postgresTest(
+    "edit() stores an empty value for an environment that had none",
+    async ({ prisma }) => {
+      const { user, organization, project } = await createTestOrgProjectWithMember(prisma);
+      const environment = await createRuntimeEnvironment(prisma, {
+        projectId: project.id,
+        organizationId: organization.id,
+        type: "PRODUCTION",
+      });
+
+      const repository = new EnvironmentVariablesRepository(prisma, prisma);
+
+      // Seed the variable in another environment so the key exists, but leave
+      // `environment` without a value for it.
+      const otherEnvironment = await createRuntimeEnvironment(prisma, {
+        projectId: project.id,
+        organizationId: organization.id,
+        type: "STAGING",
+      });
+      await createEnvironmentVariable(repository, project.id, {
+        environmentId: otherEnvironment.id,
+        key: "NEW_EMPTY",
+        value: "elsewhere",
+        userId: user.id,
+      });
+
+      const variable = await prisma.environmentVariable.findFirstOrThrow({
+        where: { projectId: project.id, key: "NEW_EMPTY" },
+      });
+
+      const result = await repository.edit(project.id, {
+        id: variable.id,
+        values: [{ environmentId: environment.id, value: "" }],
+        lastUpdatedBy: { type: "user", userId: user.id },
+      });
+
+      expect(result.success).toBe(true);
+
+      const values = await repository.getVariableValuesForKeys(project.id, [
+        { environmentId: environment.id, key: "NEW_EMPTY" },
+      ]);
+      expect(values.get(`${environment.id}:NEW_EMPTY`)).toBe("");
+    }
+  );
+
+  postgresTest("create() stores an empty value", async ({ prisma }) => {
+    const { user, organization, project } = await createTestOrgProjectWithMember(prisma);
+    const environment = await createRuntimeEnvironment(prisma, {
+      projectId: project.id,
+      organizationId: organization.id,
+      type: "PRODUCTION",
+    });
+
+    const repository = new EnvironmentVariablesRepository(prisma, prisma);
+
+    const result = await repository.create(project.id, {
+      override: true,
+      environmentIds: [environment.id],
+      variables: [{ key: "CREATED_EMPTY", value: "" }],
+      isSecret: false,
+      lastUpdatedBy: { type: "user", userId: user.id },
+    });
+
+    expect(result.success).toBe(true);
+
+    const values = await repository.getVariableValuesForKeys(project.id, [
+      { environmentId: environment.id, key: "CREATED_EMPTY" },
+    ]);
+    expect(values.get(`${environment.id}:CREATED_EMPTY`)).toBe("");
+  });
+
+  postgresTest("create() stores an empty secret value", async ({ prisma }) => {
+    const { user, organization, project } = await createTestOrgProjectWithMember(prisma);
+    const environment = await createRuntimeEnvironment(prisma, {
+      projectId: project.id,
+      organizationId: organization.id,
+      type: "PRODUCTION",
+    });
+
+    const repository = new EnvironmentVariablesRepository(prisma, prisma);
+
+    const result = await repository.create(project.id, {
+      override: true,
+      environmentIds: [environment.id],
+      variables: [{ key: "EMPTY_SECRET", value: "" }],
+      isSecret: true,
+      lastUpdatedBy: { type: "user", userId: user.id },
+    });
+
+    expect(result.success).toBe(true);
+
+    const values = await repository.getVariableValuesForKeys(project.id, [
+      { environmentId: environment.id, key: "EMPTY_SECRET" },
+    ]);
+    expect(values.get(`${environment.id}:EMPTY_SECRET`)).toBe("");
+  });
+
+  postgresTest("edit() stores a whitespace-only value verbatim", async ({ prisma }) => {
+    const { user, organization, project } = await createTestOrgProjectWithMember(prisma);
+    const environment = await createRuntimeEnvironment(prisma, {
+      projectId: project.id,
+      organizationId: organization.id,
+      type: "PRODUCTION",
+    });
+
+    const repository = new EnvironmentVariablesRepository(prisma, prisma);
+
+    await createEnvironmentVariable(repository, project.id, {
+      environmentId: environment.id,
+      key: "WHITESPACE",
+      value: "seed",
+      userId: user.id,
+    });
+
+    const variable = await prisma.environmentVariable.findFirstOrThrow({
+      where: { projectId: project.id, key: "WHITESPACE" },
+    });
+
+    const result = await repository.edit(project.id, {
+      id: variable.id,
+      values: [{ environmentId: environment.id, value: "   " }],
+      lastUpdatedBy: { type: "user", userId: user.id },
+    });
+
+    expect(result.success).toBe(true);
+
+    const values = await repository.getVariableValuesForKeys(project.id, [
+      { environmentId: environment.id, key: "WHITESPACE" },
+    ]);
+    expect(values.get(`${environment.id}:WHITESPACE`)).toBe("   ");
+  });
+});
+
+describe("EnvironmentVariablesRepository safe empty edits", () => {
+  postgresTest(
+    "an untouched secret is retained; selecting empty overrides previously entered text",
+    async ({ prisma }) => {
+      const { user, organization, project } = await createTestOrgProjectWithMember(prisma);
+      const environment = await createRuntimeEnvironment(prisma, {
+        projectId: project.id,
+        organizationId: organization.id,
+        type: "PRODUCTION",
+      });
+      const repository = new EnvironmentVariablesRepository(prisma, prisma);
+      await createEnvironmentVariable(repository, project.id, {
+        environmentId: environment.id,
+        key: "SECRET_EDIT",
+        value: "original",
+        isSecret: true,
+        userId: user.id,
+      });
+      const variable = await prisma.environmentVariable.findFirstOrThrow({
+        where: { projectId: project.id, key: "SECRET_EDIT" },
+      });
+      const edit = {
+        id: variable.id,
+        environmentId: environment.id,
+        value: "",
+        lastUpdatedBy: { type: "user" as const, userId: user.id },
+      };
+      expect((await repository.editValue(project.id, edit)).success).toBe(false);
+      const retained = await repository.getVariableValuesForKeys(project.id, [
+        { environmentId: environment.id, key: "SECRET_EDIT" },
+      ]);
+      expect(retained.get(`${environment.id}:SECRET_EDIT`)).toBe("original");
+      expect(
+        (
+          await repository.editValue(project.id, {
+            ...edit,
+            value: "typed-before-selecting-empty",
+            setEmptyValue: "true",
+          })
+        ).success
+      ).toBe(true);
+      const cleared = await repository.getVariableValuesForKeys(project.id, [
+        { environmentId: environment.id, key: "SECRET_EDIT" },
+      ]);
+      expect(cleared.get(`${environment.id}:SECRET_EDIT`)).toBe("");
+      const valueRow = await prisma.environmentVariableValue.findFirstOrThrow({
+        where: { variableId: variable.id, environmentId: environment.id },
+      });
+      expect(valueRow.isSecret).toBe(true);
+      expect(
+        (await repository.editValue(project.id, { ...edit, value: "replacement" })).success
+      ).toBe(true);
+      expect(
+        (
+          await repository.getVariableValuesForKeys(project.id, [
+            { environmentId: environment.id, key: "SECRET_EDIT" },
+          ])
+        ).get(`${environment.id}:SECRET_EDIT`)
+      ).toBe("replacement");
+    }
+  );
+
+  postgresTest(
+    "dashboard non-secret edits can store empty without a secret confirmation",
+    async ({ prisma }) => {
+      const { user, organization, project } = await createTestOrgProjectWithMember(prisma);
+      const environment = await createRuntimeEnvironment(prisma, {
+        projectId: project.id,
+        organizationId: organization.id,
+        type: "PRODUCTION",
+      });
+      const repository = new EnvironmentVariablesRepository(prisma, prisma);
+      await createEnvironmentVariable(repository, project.id, {
+        environmentId: environment.id,
+        key: "PLAIN_EDIT",
+        value: "original",
+        userId: user.id,
+      });
+      const variable = await prisma.environmentVariable.findFirstOrThrow({
+        where: { projectId: project.id, key: "PLAIN_EDIT" },
+      });
+      expect(
+        (
+          await repository.editValue(project.id, {
+            id: variable.id,
+            environmentId: environment.id,
+            value: "",
+          })
+        ).success
+      ).toBe(true);
+      expect(
+        (
+          await repository.getVariableValuesForKeys(project.id, [
+            { environmentId: environment.id, key: "PLAIN_EDIT" },
+          ])
+        ).get(`${environment.id}:PLAIN_EDIT`)
+      ).toBe("");
+    }
+  );
+});
+
+postgresTest("both edit paths can replace an unreadable secret", async ({ prisma }) => {
+  const { user, organization, project } = await createTestOrgProjectWithMember(prisma);
+  const environment = await createRuntimeEnvironment(prisma, {
+    projectId: project.id,
+    organizationId: organization.id,
+    type: "PRODUCTION",
+  });
+  const repository = new EnvironmentVariablesRepository(prisma, prisma);
+  await createEnvironmentVariable(repository, project.id, {
+    environmentId: environment.id,
+    key: "REPAIR_SECRET",
+    value: "before",
+    isSecret: true,
+    userId: user.id,
+  });
+  const variable = await prisma.environmentVariable.findFirstOrThrow({
+    where: { projectId: project.id, key: "REPAIR_SECRET" },
+  });
+  for (const path of ["api", "dashboard"] as const) {
+    await prisma.secretStore.update({
+      where: { key: `environmentvariable:${project.id}:${environment.id}:REPAIR_SECRET` },
+      data: { value: { unreadable: true } },
+    });
+    const result =
+      path === "api"
+        ? await repository.edit(project.id, {
+            id: variable.id,
+            values: [{ environmentId: environment.id, value: "" }],
+          })
+        : await repository.editValue(project.id, {
+            id: variable.id,
+            environmentId: environment.id,
+            value: "replacement",
+          });
+    expect(result, path).toEqual({ success: true });
+    const values = await repository.getVariableValuesForKeys(project.id, [
+      { environmentId: environment.id, key: "REPAIR_SECRET" },
+    ]);
+    expect(values.get(`${environment.id}:REPAIR_SECRET`)).toBe(path === "api" ? "" : "replacement");
+  }
+});
+
+postgresTest(
+  "rollout defaults off, isolates organizations, and preserves stored empties when disabled",
+  async ({ prisma }) => {
+    const { organization, project } = await createBaseOrgProjectWithMember(prisma);
+    const environment = await createRuntimeEnvironment(prisma, {
+      projectId: project.id,
+      organizationId: organization.id,
+      type: "PRODUCTION",
+    });
+    const repository = new EnvironmentVariablesRepository(prisma, prisma);
+    const create = (value: string) =>
+      repository.create(project.id, {
+        override: true,
+        environmentIds: [environment.id],
+        variables: [{ key: "ROLLOUT", value }],
+      });
+    expect((await create("")).success).toBe(false);
+    expect((await create("old")).success).toBe(true);
+    const variable = await prisma.environmentVariable.findUniqueOrThrow({
+      where: { projectId_key: { projectId: project.id, key: "ROLLOUT" } },
+    });
+    expect(
+      (
+        await repository.edit(project.id, {
+          id: variable.id,
+          values: [{ environmentId: environment.id, value: "" }],
+        })
+      ).success
+    ).toBe(false);
+    expect(
+      (
+        await repository.editValue(project.id, {
+          id: variable.id,
+          environmentId: environment.id,
+          value: "",
+          setEmptyValue: "true",
+        })
+      ).success
+    ).toBe(false);
+    await prisma.organization.update({
+      where: { id: organization.id },
+      data: { featureFlags: { allowEmptyEnvironmentVariableValues: true } },
+    });
+    expect((await create("")).success).toBe(true);
+    const other = await createBaseOrgProjectWithMember(prisma);
+    const otherEnv = await createRuntimeEnvironment(prisma, {
+      projectId: other.project.id,
+      organizationId: other.organization.id,
+      type: "PRODUCTION",
+    });
+    expect(
+      (
+        await repository.create(other.project.id, {
+          override: true,
+          environmentIds: [otherEnv.id],
+          variables: [{ key: "ROLLOUT", value: "" }],
+        })
+      ).success
+    ).toBe(false);
+    await prisma.organization.update({
+      where: { id: organization.id },
+      data: { featureFlags: { allowEmptyEnvironmentVariableValues: false } },
+    });
+    expect(await repository.getEnvironmentVariables(project.id, environment.id)).toEqual([
+      { key: "ROLLOUT", value: "" },
+    ]);
+    expect(
+      (
+        await repository.editValue(project.id, {
+          id: variable.id,
+          environmentId: environment.id,
+          value: "restored",
+        })
+      ).success
+    ).toBe(true);
+    expect(
+      (await repository.deleteValue(project.id, { id: variable.id, environmentId: environment.id }))
+        .success
+    ).toBe(true);
+  }
+);
+
+postgresTest(
+  "disabled rollout skips empty integration entries without dropping nonempty entries",
+  async ({ prisma }) => {
+    const { organization, project } = await createBaseOrgProjectWithMember(prisma);
+    const environment = await createRuntimeEnvironment(prisma, {
+      projectId: project.id,
+      organizationId: organization.id,
+      type: "PRODUCTION",
+    });
+    const repository = new EnvironmentVariablesRepository(prisma, prisma);
+    const common = {
+      override: true,
+      environmentIds: [environment.id],
+      lastUpdatedBy: { type: "integration" as const, integration: "vercel" },
+    };
+    await repository.create(project.id, { ...common, variables: [{ key: "KEEP", value: "old" }] });
+    expect(
+      (await repository.create(project.id, { ...common, variables: [{ key: "KEEP", value: "" }] }))
+        .success
+    ).toBe(true);
+    expect(
+      (
+        await repository.create(project.id, {
+          ...common,
+          variables: [
+            { key: "KEEP", value: "" },
+            { key: "NEW", value: "set" },
+          ],
+        })
+      ).success
+    ).toBe(true);
+    const values = Object.fromEntries(
+      (await repository.getEnvironmentVariables(project.id, environment.id)).map(
+        ({ key, value }) => [key, value]
+      )
+    );
+    expect(values).toEqual({ KEEP: "old", NEW: "set" });
+  }
+);
+
+postgresTest(
+  "flag resolution is strict and organization overrides beat the global default",
+  async ({ prisma }) => {
+    expect(await emptyEnvironmentVariableValuesEnabled(undefined, prisma)).toBe(false);
+    expect(
+      await emptyEnvironmentVariableValuesEnabled(
+        { allowEmptyEnvironmentVariableValues: "true" },
+        prisma
+      )
+    ).toBe(false);
+    await prisma.featureFlag.create({
+      data: { key: "allowEmptyEnvironmentVariableValues", value: true },
+    });
+    expect(await emptyEnvironmentVariableValuesEnabled(undefined, prisma)).toBe(true);
+    expect(
+      await emptyEnvironmentVariableValuesEnabled(
+        { allowEmptyEnvironmentVariableValues: false },
+        prisma
+      )
+    ).toBe(false);
+  }
+);
diff --git a/apps/webapp/test/vercelEnvironmentVariableValues.test.ts b/apps/webapp/test/vercelEnvironmentVariableValues.test.ts
new file mode 100644
index 00000000000..e4f4eb08f87
--- /dev/null
+++ b/apps/webapp/test/vercelEnvironmentVariableValues.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, test } from "vitest";
+import {
+  isVercelSecretType,
+  mergeVercelEnvironmentVariableValues,
+  resolveVercelSharedValue,
+  toVercelEnvironmentVariableValue,
+} from "~/v3/vercel/environmentVariableValues";
+
+describe("Vercel environment values", () => {
+  test.each(["", "  ", "text"])(
+    "retains project value %j and its key for shared precedence",
+    (value) => {
+      expect(
+        toVercelEnvironmentVariableValue({
+          key: "OVERRIDE",
+          value,
+          type: "plain",
+          target: ["production"],
+        })
+      ).toEqual({ key: "OVERRIDE", value, type: "plain", target: ["production"], isSecret: false });
+    }
+  );
+
+  test("omits an unavailable project value", () => {
+    expect(toVercelEnvironmentVariableValue({ key: "MISSING", type: "plain" })).toBeNull();
+  });
+
+  test("an inline shared empty value avoids fetching and cannot be replaced by a fallback", async () => {
+    const value = await resolveVercelSharedValue("", async () => {
+      throw new Error("An inline value must not fetch a fallback");
+    });
+    expect(value).toBe("");
+  });
+
+  test.each([null, undefined])(
+    "an absent shared value (%s) can resolve to empty",
+    async (inline) => {
+      expect(await resolveVercelSharedValue(inline, async () => "")).toBe("");
+      expect(await resolveVercelSharedValue(inline, async () => null)).toBeNull();
+    }
+  );
+
+  test("Vercel secret and sensitive types remain excluded", () => {
+    expect(isVercelSecretType("secret")).toBe(true);
+    expect(isVercelSecretType("sensitive")).toBe(true);
+    expect(isVercelSecretType("encrypted")).toBe(false);
+    expect(isVercelSecretType("plain")).toBe(false);
+  });
+});
+
+test("an empty project value overrides a nonempty shared value", () => {
+  const project = toVercelEnvironmentVariableValue({ key: "OVERRIDE", value: "", type: "plain" });
+  expect(project).not.toBeNull();
+  const merged = mergeVercelEnvironmentVariableValues(project ? [project] : [], [
+    { key: "OVERRIDE", value: "shared" },
+    { key: "SHARED_ONLY", value: "" },
+  ]);
+  expect(merged.map(({ key, value }) => ({ key, value }))).toEqual([
+    { key: "OVERRIDE", value: "" },
+    { key: "SHARED_ONLY", value: "" },
+  ]);
+});
+
+test.each(["", " \t "])("disabled rollout filters %j before merging", async (value) => {
+  const project = toVercelEnvironmentVariableValue(
+    { key: "OVERRIDE", value, type: "plain" },
+    false
+  );
+  expect(project).toBeNull();
+  expect(
+    mergeVercelEnvironmentVariableValues(project ? [project] : [], [
+      { key: "OVERRIDE", value: "shared" },
+    ])
+  ).toEqual([{ key: "OVERRIDE", value: "shared" }]);
+  expect(await resolveVercelSharedValue(value, async () => "fallback", false)).toBe("fallback");
+  expect(await resolveVercelSharedValue(undefined, async () => value, false)).toBeNull();
+});
diff --git a/docs/deploy-environment-variables.mdx b/docs/deploy-environment-variables.mdx
index ac44fdcccb2..820ed659d97 100644
--- a/docs/deploy-environment-variables.mdx
+++ b/docs/deploy-environment-variables.mdx
@@ -43,6 +43,12 @@ When creating an environment variable, you can mark it as a **Secret**. Secret v
 
 You can edit an environment variable's values. You cannot edit the key name, you must delete and create a new one.
 
+<Note>
+  An empty string is a valid value. Saving a variable with an empty value stores it as an empty
+  string (your task sees the variable set to `""`), which is different from deleting the variable
+  (where your task does not see it at all).
+</Note>
+
 <Steps>
 
 <Step title="Press the action button on a variable">
diff --git a/docs/v3-openapi.yaml b/docs/v3-openapi.yaml
index eeaac946a8e..6c182fad5bc 100644
--- a/docs/v3-openapi.yaml
+++ b/docs/v3-openapi.yaml
@@ -5503,6 +5503,7 @@ components:
       properties:
         value:
           type: string
+          description: The value to store. An empty string is valid and is stored as-is, not treated as a deletion.
           example: slack_123456
       required: ["value"]
     EnvVar:
diff --git a/packages/cli-v3/src/build/buildWorker.ts b/packages/cli-v3/src/build/buildWorker.ts
index 1aef4640727..2aee0192af7 100644
--- a/packages/cli-v3/src/build/buildWorker.ts
+++ b/packages/cli-v3/src/build/buildWorker.ts
@@ -48,6 +48,7 @@ export type BuildWorkerOptions = {
   resolvedConfig: ResolvedConfig;
   listener?: BuildWorkerEventListener;
   envVars?: Record<string, string>;
+  allowEmptyEnvironmentVariableValues?: boolean;
   rewritePaths?: boolean;
   forcedExternals?: string[];
   plain?: boolean;
@@ -66,6 +67,7 @@ export async function buildWorker(options: BuildWorkerOptions) {
     options.forcedExternals
   );
   const buildContext = createBuildContext(options.target, resolvedConfig, {
+    allowEmptyEnvironmentVariableValues: options.allowEmptyEnvironmentVariableValues,
     logger: options.plain
       ? {
           debug: (...args) => console.log(...args),
diff --git a/packages/cli-v3/src/build/extensions.test.ts b/packages/cli-v3/src/build/extensions.test.ts
new file mode 100644
index 00000000000..7286a73d56d
--- /dev/null
+++ b/packages/cli-v3/src/build/extensions.test.ts
@@ -0,0 +1,95 @@
+import { describe, expect, test } from "vitest";
+import type { ResolvedConfig } from "@trigger.dev/core/v3/build";
+import type { BuildManifest } from "@trigger.dev/core/v3/schemas";
+import { syncEnvVars } from "../../../build/src/extensions/core/syncEnvVars.js";
+import { createBuildContext, notifyExtensionOnBuildComplete } from "./extensions.js";
+
+const buckets = ["env", "parentEnv", "secretEnv", "secretParentEnv"] as const;
+
+describe("syncEnvVars through the deployment layer merger", () => {
+  test.each(buckets)("preserves empty values in %s", async (bucket) => {
+    const extension = syncEnvVars(() =>
+      [
+        { name: "CLEAR", value: "" },
+        { name: "NEW_EMPTY", value: "" },
+        { name: "UNCHANGED", value: "" },
+        { name: "SPACE", value: "  " },
+      ].map((item) => ({
+        ...item,
+        isSecret: bucket === "secretEnv" || bucket === "secretParentEnv",
+        isParentEnv: bucket === "parentEnv" || bucket === "secretParentEnv",
+      }))
+    );
+    const context = createBuildContext(
+      "deploy",
+      {
+        project: "proj_test",
+        workingDir: process.cwd(),
+        build: { extensions: [extension] },
+      } as ResolvedConfig,
+      { allowEmptyEnvironmentVariableValues: true }
+    );
+    const manifest = await notifyExtensionOnBuildComplete(context, {
+      environment: "prod",
+      build: {},
+      deploy: { env: { CLEAR: "old", UNCHANGED: "" } },
+    } as BuildManifest);
+
+    expect(manifest.deploy.sync?.[bucket]).toEqual({ CLEAR: "", NEW_EMPTY: "", SPACE: "  " });
+  });
+
+  test("override false protects existing values but allows a new empty variable", async () => {
+    const context = createBuildContext(
+      "deploy",
+      {
+        project: "proj_test",
+        workingDir: process.cwd(),
+        build: {
+          extensions: [syncEnvVars(() => ({ EXISTING: "", NEW_EMPTY: "" }), { override: false })],
+        },
+      } as ResolvedConfig,
+      { allowEmptyEnvironmentVariableValues: true }
+    );
+    const manifest = await notifyExtensionOnBuildComplete(context, {
+      environment: "prod",
+      build: {},
+      deploy: { env: { EXISTING: "keep" } },
+    } as BuildManifest);
+
+    expect(manifest.deploy.sync?.env).toEqual({ NEW_EMPTY: "" });
+  });
+});
+
+test.each([undefined, false])(
+  "a missing or disabled server capability (%s) skips empty sync values",
+  async (enabled) => {
+    const context = createBuildContext(
+      "deploy",
+      {
+        project: "proj_test",
+        workingDir: process.cwd(),
+        build: {
+          extensions: [
+            syncEnvVars(() => [
+              { name: "EMPTY", value: "" },
+              { name: "SECRET_EMPTY", value: "", isSecret: true },
+              { name: "PARENT_EMPTY", value: "", isParentEnv: true },
+              { name: "PARENT_SECRET_EMPTY", value: "", isParentEnv: true, isSecret: true },
+              { name: "SET", value: "new" },
+            ]),
+          ],
+        },
+      } as ResolvedConfig,
+      { allowEmptyEnvironmentVariableValues: enabled }
+    );
+    const manifest = await notifyExtensionOnBuildComplete(context, {
+      environment: "prod",
+      build: {},
+      deploy: { env: { EMPTY: "old" } },
+    } as BuildManifest);
+    expect(manifest.deploy.sync?.env).toEqual({ SET: "new" });
+    expect(manifest.deploy.sync?.parentEnv).toEqual({});
+    expect(manifest.deploy.sync?.secretEnv).toEqual({});
+    expect(manifest.deploy.sync?.secretParentEnv).toEqual({});
+  }
+);
diff --git a/packages/cli-v3/src/build/extensions.ts b/packages/cli-v3/src/build/extensions.ts
index 1f545034246..a7889bdb3ee 100644
--- a/packages/cli-v3/src/build/extensions.ts
+++ b/packages/cli-v3/src/build/extensions.ts
@@ -16,6 +16,7 @@ import { spinner } from "../utilities/windows.js";
 export interface InternalBuildContext extends BuildContext {
   getLayers(): BuildLayer[];
   clearLayers(): void;
+  readonly allowEmptyEnvironmentVariableValues: boolean;
   getPlugins(): RegisteredPlugin[];
   appendExtension(extension: BuildExtension): void;
   prependExtension(extension: BuildExtension): void;
@@ -57,7 +58,7 @@ export async function notifyExtensionOnBuildComplete(
 export function createBuildContext(
   target: BuildTarget,
   config: ResolvedConfig,
-  options?: { logger?: BuildLogger }
+  options?: { logger?: BuildLogger; allowEmptyEnvironmentVariableValues?: boolean }
 ): InternalBuildContext {
   const layers: BuildLayer[] = [];
   const registeredPlugins: RegisteredPlugin[] = [];
@@ -77,6 +78,7 @@ export function createBuildContext(
 
   return {
     target,
+    allowEmptyEnvironmentVariableValues: options?.allowEmptyEnvironmentVariableValues === true,
     config: config,
     workingDir: config.workingDir,
     addLayer(layer) {
@@ -123,7 +125,7 @@ function applyContextLayersToManifest(
   manifest: BuildManifest
 ): BuildManifest {
   for (const layer of context.getLayers()) {
-    manifest = applyLayerToManifest(layer, manifest);
+    manifest = applyLayerToManifest(layer, manifest, context.allowEmptyEnvironmentVariableValues);
   }
 
   context.clearLayers();
@@ -131,7 +133,18 @@ function applyContextLayersToManifest(
   return manifest;
 }
 
-function applyLayerToManifest(layer: BuildLayer, manifest: BuildManifest): BuildManifest {
+function shouldSyncEnvironmentVariableValue(
+  value: string | null | undefined,
+  allowEmptyValues: boolean
+): value is string {
+  return value !== undefined && value !== null && (value !== "" || allowEmptyValues);
+}
+
+function applyLayerToManifest(
+  layer: BuildLayer,
+  manifest: BuildManifest,
+  allowEmptyValues: boolean
+): BuildManifest {
   let $manifest = { ...manifest };
 
   if (layer.commands) {
@@ -151,7 +164,7 @@ function applyLayerToManifest(layer: BuildLayer, manifest: BuildManifest): Build
     $manifest.deploy.sync.parentEnv ??= {};
 
     for (const [key, value] of Object.entries(layer.deploy.env)) {
-      if (!value) {
+      if (!shouldSyncEnvironmentVariableValue(value, allowEmptyValues)) {
         continue;
       }
 
@@ -171,7 +184,7 @@ function applyLayerToManifest(layer: BuildLayer, manifest: BuildManifest): Build
     $manifest.deploy.sync.parentEnv ??= {};
 
     for (const [key, value] of Object.entries(layer.deploy.parentEnv)) {
-      if (!value) {
+      if (!shouldSyncEnvironmentVariableValue(value, allowEmptyValues)) {
         continue;
       }
 
@@ -191,7 +204,7 @@ function applyLayerToManifest(layer: BuildLayer, manifest: BuildManifest): Build
     $manifest.deploy.sync.secretEnv ??= {};
 
     for (const [key, value] of Object.entries(layer.deploy.secretEnv)) {
-      if (!value) {
+      if (!shouldSyncEnvironmentVariableValue(value, allowEmptyValues)) {
         continue;
       }
 
@@ -211,7 +224,7 @@ function applyLayerToManifest(layer: BuildLayer, manifest: BuildManifest): Build
     $manifest.deploy.sync.secretParentEnv ??= {};
 
     for (const [key, value] of Object.entries(layer.deploy.secretParentEnv)) {
-      if (!value) {
+      if (!shouldSyncEnvironmentVariableValue(value, allowEmptyValues)) {
         continue;
       }
 
diff --git a/packages/cli-v3/src/commands/deploy.ts b/packages/cli-v3/src/commands/deploy.ts
index 1acbd79d52d..8808ca5abfa 100644
--- a/packages/cli-v3/src/commands/deploy.ts
+++ b/packages/cli-v3/src/commands/deploy.ts
@@ -557,6 +557,8 @@ async function _deployCommand(dir: string, options: DeployCommandOptions) {
       resolvedConfig,
       rewritePaths: true,
       envVars: serverEnvVars.success ? serverEnvVars.data.variables : {},
+      allowEmptyEnvironmentVariableValues:
+        serverEnvVars.success && serverEnvVars.data.allowEmptyEnvironmentVariableValues === true,
       forcedExternals,
       plain: options.plain,
       listener: {
@@ -1604,6 +1606,8 @@ async function handleLocalBundleDeploy({
       resolvedConfig: config,
       rewritePaths: true,
       envVars: serverEnvVars.success ? serverEnvVars.data.variables : {},
+      allowEmptyEnvironmentVariableValues:
+        serverEnvVars.success && serverEnvVars.data.allowEmptyEnvironmentVariableValues === true,
       forcedExternals,
       plain: options.plain,
       listener: {
diff --git a/packages/cli-v3/src/dev/backgroundWorker.ts b/packages/cli-v3/src/dev/backgroundWorker.ts
index 6538f6aa2dd..2a4b0aa4fa9 100644
--- a/packages/cli-v3/src/dev/backgroundWorker.ts
+++ b/packages/cli-v3/src/dev/backgroundWorker.ts
@@ -14,6 +14,8 @@ import type { Metafile } from "esbuild";
 
 export type BackgroundWorkerOptions = {
   env: Record<string, string>;
+  processEnv: Record<string, string>;
+  envOverrides: Record<string, string>;
   cwd: string;
   stop: () => void;
 };
diff --git a/packages/cli-v3/src/dev/devSupervisor.ts b/packages/cli-v3/src/dev/devSupervisor.ts
index 7ad4ce00542..d1cd43b31ad 100644
--- a/packages/cli-v3/src/dev/devSupervisor.ts
+++ b/packages/cli-v3/src/dev/devSupervisor.ts
@@ -35,7 +35,7 @@ import { DevRunController } from "../entryPoints/dev-run-controller.js";
 import { cliLink, prettyError } from "../utilities/cliOutput.js";
 import { devBranchPathSegment } from "../utilities/devBranch.js";
 import { eventBus } from "../utilities/eventBus.js";
-import { resolveLocalEnvVars } from "../utilities/localEnvVars.js";
+import { resolveDevEnvVars } from "../utilities/localEnvVars.js";
 import { logger } from "../utilities/logger.js";
 import { resolveSourceFiles } from "../utilities/sourceFiles.js";
 import { getTmpRoot } from "../utilities/tempDirectories.js";
@@ -121,7 +121,7 @@ class DevSupervisor implements WorkerRuntime {
     this.runLimiter = pLimit(maxConcurrentRuns);
 
     // Initialize the task run process pool
-    const env = await this.#getEnvVars();
+    const { processEnv, envOverrides } = await this.#getEnvVars();
 
     const processKeepAlive =
       this.options.config.processKeepAlive ?? this.options.config.experimental_processKeepAlive;
@@ -148,7 +148,8 @@ class DevSupervisor implements WorkerRuntime {
     }
 
     this.taskRunProcessPool = new TaskRunProcessPool({
-      env,
+      // Project values are supplied fresh when each run obtains a process.
+      env: { ...processEnv, ...envOverrides },
       cwd: this.options.config.workingDir,
       enableProcessReuse,
       maxPoolSize,
@@ -335,10 +336,10 @@ class DevSupervisor implements WorkerRuntime {
       return;
     }
 
-    const env = await this.#getEnvVars();
+    const envVars = await this.#getEnvVars();
 
     const backgroundWorker = new BackgroundWorker(manifest, metafile, {
-      env,
+      ...envVars,
       cwd: this.options.config.workingDir,
       stop,
     });
@@ -656,7 +657,7 @@ class DevSupervisor implements WorkerRuntime {
     }
   }
 
-  async #getEnvVars(): Promise<Record<string, string>> {
+  async #getEnvVars() {
     const environmentVariablesResponse = await this.options.client.getEnvironmentVariables(
       this.options.config.project
     );
@@ -665,17 +666,20 @@ class DevSupervisor implements WorkerRuntime {
       ","
     );
 
-    return {
-      ...resolveLocalEnvVars(
-        this.options.args.envFile,
-        environmentVariablesResponse.success ? environmentVariablesResponse.data.variables : {}
-      ),
-      NODE_ENV: "development",
-      TRIGGER_API_URL: this.options.client.apiURL,
-      TRIGGER_SECRET_KEY: this.options.client.accessToken!,
-      OTEL_EXPORTER_OTLP_COMPRESSION: "none",
-      OTEL_IMPORT_HOOK_INCLUDES,
-    };
+    return resolveDevEnvVars({
+      envFile: this.options.args.envFile,
+      projectEnv: environmentVariablesResponse.success
+        ? environmentVariablesResponse.data.variables
+        : {},
+      projectRef: this.options.config.project,
+      overrides: {
+        NODE_ENV: "development",
+        TRIGGER_API_URL: this.options.client.apiURL,
+        TRIGGER_SECRET_KEY: this.options.client.accessToken!,
+        OTEL_EXPORTER_OTLP_COMPRESSION: "none",
+        OTEL_IMPORT_HOOK_INCLUDES,
+      },
+    });
   }
 
   async #registerWorker(worker: BackgroundWorker) {
diff --git a/packages/cli-v3/src/entryPoints/dev-run-controller.ts b/packages/cli-v3/src/entryPoints/dev-run-controller.ts
index d5121cdc468..e99e8eff345 100644
--- a/packages/cli-v3/src/entryPoints/dev-run-controller.ts
+++ b/packages/cli-v3/src/entryPoints/dev-run-controller.ts
@@ -22,7 +22,7 @@ import type { CliApiClient } from "../apiClient.js";
 import { TaskRunProcess } from "../executions/taskRunProcess.js";
 import { assertExhaustive } from "../utilities/assertExhaustive.js";
 import { logger } from "../utilities/logger.js";
-import { sanitizeEnvVars } from "../utilities/sanitizeEnvVars.js";
+import { buildDevRunEnv } from "../utilities/sanitizeEnvVars.js";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
 import type { BackgroundWorker } from "../dev/backgroundWorker.js";
@@ -631,6 +631,13 @@ export class DevRunController {
     // doesn't force-kill a healthy reused process on RETRY_IMMEDIATELY.
     this.discardProcessOnReturn = false;
 
+    const runEnv = buildDevRunEnv({
+      resolvedEnvVars: envVars,
+      processEnv: this.opts.worker.params.processEnv,
+      envOverrides: this.opts.worker.params.envOverrides,
+      projectRef: execution.project.ref,
+    });
+
     // Get process from pool instead of creating new one
     const { taskRunProcess, isReused } = await this.opts.taskRunProcessPool.getProcess(
       this.opts.worker.manifest,
@@ -642,6 +649,8 @@ export class DevRunController {
       },
       execution.machine,
       {
+        // Config imports in a new process run before its first IPC message.
+        ...runEnv,
         TRIGGER_WORKER_MANIFEST_PATH: join(this.opts.worker.build.outputPath, "index.json"),
         RUN_WORKER_SHOW_LOGS: this.opts.logLevel === "debug" ? "true" : "false",
         TRIGGER_WORKER_VERSION: this.opts.worker.serverWorker?.version,
@@ -690,11 +699,7 @@ export class DevRunController {
           metrics,
         },
         messageId: run.friendlyId,
-        env: {
-          ...sanitizeEnvVars(envVars ?? {}),
-          ...sanitizeEnvVars(this.opts.worker.params.env),
-          TRIGGER_PROJECT_REF: execution.project.ref,
-        },
+        env: runEnv,
       },
       isReused
     );
diff --git a/packages/cli-v3/src/utilities/localEnvVars.test.ts b/packages/cli-v3/src/utilities/localEnvVars.test.ts
new file mode 100644
index 00000000000..f6720151c8d
--- /dev/null
+++ b/packages/cli-v3/src/utilities/localEnvVars.test.ts
@@ -0,0 +1,64 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { expect, test } from "vitest";
+import { resolveDevEnvVars } from "./localEnvVars.js";
+import { buildDevRunEnv } from "./sanitizeEnvVars.js";
+
+test("server empties survive startup and subsequent runs without stale worker overrides", () => {
+  const directory = mkdtempSync(join(tmpdir(), "trigger-dev-env-"));
+  try {
+    const envFile = join(directory, ".env");
+    writeFileSync(envFile, 'TEST_FILE_OVERRIDE="local"\nTEST_LOCAL_EMPTY=\n');
+    const worker = resolveDevEnvVars({
+      envFile,
+      projectEnv: {
+        TEST_EMPTY: "",
+        TEST_UPDATED: "old",
+        TEST_REMOVED: "old",
+        TEST_FILE_OVERRIDE: "server",
+        TEST_LOCAL_EMPTY: "server",
+      },
+      overrides: { NODE_ENV: "development" },
+      projectRef: "proj_123",
+    });
+
+    // Indexing imports modules before any per-run IPC environment update.
+    const startup = spawnSync(
+      process.execPath,
+      ["-e", 'require("node:assert/strict").equal(process.env.TEST_EMPTY, "");'],
+      { env: worker.env, encoding: "utf8" }
+    );
+    expect(startup.stderr).toBe("");
+    expect(startup.status).toBe(0);
+
+    const runEnv = buildDevRunEnv({
+      resolvedEnvVars: {
+        TEST_EMPTY: "",
+        TEST_UPDATED: "",
+        TEST_FILE_OVERRIDE: "fresh-server",
+        TEST_LOCAL_EMPTY: "server",
+      },
+      processEnv: worker.processEnv,
+      envOverrides: worker.envOverrides,
+      projectRef: "proj_123",
+    });
+    const run = spawnSync(
+      process.execPath,
+      [
+        "-e",
+        'console.log(JSON.stringify({value:process.env.TEST_UPDATED, present:Object.hasOwn(process.env,"TEST_UPDATED")}))',
+      ],
+      { env: runEnv, encoding: "utf8" }
+    );
+    expect(run.status).toBe(0);
+    expect(JSON.parse(run.stdout)).toEqual({ value: "", present: true });
+    expect(runEnv.TEST_REMOVED).toBeUndefined();
+    expect(runEnv.TEST_FILE_OVERRIDE).toBe("local");
+    expect(runEnv.TEST_LOCAL_EMPTY).toBe("server");
+    expect(runEnv.NODE_ENV).toBe("development");
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
diff --git a/packages/cli-v3/src/utilities/localEnvVars.ts b/packages/cli-v3/src/utilities/localEnvVars.ts
index 225c2dae135..e34cd02f897 100644
--- a/packages/cli-v3/src/utilities/localEnvVars.ts
+++ b/packages/cli-v3/src/utilities/localEnvVars.ts
@@ -1,5 +1,28 @@
 import { resolveDotEnvVars } from "./dotEnv.js";
-import { sanitizeEnvVars } from "./sanitizeEnvVars.js";
+import { buildDevRunEnv, sanitizeEnvVars } from "./sanitizeEnvVars.js";
+
+export function resolveDevEnvVars({
+  envFile,
+  projectEnv,
+  overrides,
+  projectRef,
+}: {
+  envFile?: string;
+  projectEnv: Record<string, string>;
+  overrides: Record<string, string>;
+  projectRef: string;
+}) {
+  const processEnv = sanitizeEnvVars(gatherProcessEnv());
+  const envOverrides = {
+    ...sanitizeEnvVars(resolveDotEnvVars(undefined, envFile)),
+    ...overrides,
+  };
+  return {
+    processEnv,
+    envOverrides,
+    env: buildDevRunEnv({ resolvedEnvVars: projectEnv, processEnv, envOverrides, projectRef }),
+  };
+}
 
 export function resolveLocalEnvVars(
   envFile?: string,
diff --git a/packages/cli-v3/src/utilities/sanitizeEnvVars.test.ts b/packages/cli-v3/src/utilities/sanitizeEnvVars.test.ts
new file mode 100644
index 00000000000..919e58f464f
--- /dev/null
+++ b/packages/cli-v3/src/utilities/sanitizeEnvVars.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, test } from "vitest";
+import { buildDevRunEnv, sanitizeEnvVars } from "./sanitizeEnvVars.js";
+
+describe("sanitizeEnvVars", () => {
+  test("drops empty, whitespace-only, and undefined local values", () => {
+    expect(sanitizeEnvVars({ SET: "x", EMPTY: "", WHITESPACE: "   ", MISSING: undefined })).toEqual(
+      { SET: "x" }
+    );
+  });
+});
+
+describe("buildDevRunEnv", () => {
+  test("fresh project values override machine defaults, while local overrides win", () => {
+    const env = buildDevRunEnv({
+      resolvedEnvVars: { EMPTY: "", WHITESPACE: "   ", FILE_OVERRIDE: "server" },
+      processEnv: { EMPTY: "machine", FILE_OVERRIDE: "machine", LOCAL: "local" },
+      envOverrides: { FILE_OVERRIDE: "file", TRIGGER_PROJECT_REF: "wrong-project" },
+      projectRef: "proj_123",
+    });
+    expect(env).toEqual({
+      EMPTY: "",
+      WHITESPACE: "   ",
+      FILE_OVERRIDE: "file",
+      LOCAL: "local",
+      TRIGGER_PROJECT_REF: "proj_123",
+    });
+  });
+
+  test("handles an absent server response", () => {
+    expect(
+      buildDevRunEnv({
+        resolvedEnvVars: undefined,
+        processEnv: { LOCAL: "x" },
+        envOverrides: {},
+        projectRef: "proj_123",
+      })
+    ).toEqual({ LOCAL: "x", TRIGGER_PROJECT_REF: "proj_123" });
+  });
+});
diff --git a/packages/cli-v3/src/utilities/sanitizeEnvVars.ts b/packages/cli-v3/src/utilities/sanitizeEnvVars.ts
index 23f40b6be0f..79b67d0d3dd 100644
--- a/packages/cli-v3/src/utilities/sanitizeEnvVars.ts
+++ b/packages/cli-v3/src/utilities/sanitizeEnvVars.ts
@@ -22,3 +22,26 @@ export const sanitizeEnvVars = (
     )
   ) as Record<string, string>;
 };
+
+/**
+ * Keep machine defaults, fresh project values, and local overrides separate.
+ * The worker's merged startup environment must not override fresh project values.
+ */
+export const buildDevRunEnv = ({
+  resolvedEnvVars,
+  processEnv,
+  envOverrides,
+  projectRef,
+}: {
+  resolvedEnvVars: Record<string, string> | undefined;
+  processEnv: Record<string, string>;
+  envOverrides: Record<string, string>;
+  projectRef: string;
+}): Record<string, string> => {
+  return {
+    ...processEnv,
+    ...(resolvedEnvVars ?? {}),
+    ...envOverrides,
+    TRIGGER_PROJECT_REF: projectRef,
+  };
+};
diff --git a/packages/core/src/v3/schemas/api.ts b/packages/core/src/v3/schemas/api.ts
index 15618cd621a..731032613d2 100644
--- a/packages/core/src/v3/schemas/api.ts
+++ b/packages/core/src/v3/schemas/api.ts
@@ -650,6 +650,7 @@ export const RescheduleRunRequestBody = z.object({
 export type RescheduleRunRequestBody = z.infer<typeof RescheduleRunRequestBody>;
 
 export const GetEnvironmentVariablesResponseBody = z.object({
+  allowEmptyEnvironmentVariableValues: z.boolean().optional(),
   variables: z.record(z.string(), z.string()),
 });
 

From 2887725b91d4d721cb08bd3d0874889db3b37184 Mon Sep 17 00:00:00 2001
From: Eric Allam <eallam@icloud.com>
Date: Thu, 17 Sep 2026 13:46:08 +0000
Subject: [PATCH 2/6] chore(dashboard-agent): use Node.js 24 for task
 deployments

Use Node.js 24 for dashboard agent task deployments.

Mono-RevId: a0d27501dc1ede88a89955bed4dc2f346bed062f
---
 internal-packages/dashboard-agent/trigger.config.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/internal-packages/dashboard-agent/trigger.config.ts b/internal-packages/dashboard-agent/trigger.config.ts
index c6b7c11ca0f..adbb3f0854d 100644
--- a/internal-packages/dashboard-agent/trigger.config.ts
+++ b/internal-packages/dashboard-agent/trigger.config.ts
@@ -15,6 +15,7 @@ import { aptGet } from "@trigger.dev/build/extensions/core";
  */
 export default defineConfig({
   project: process.env.TRIGGER_DASHBOARD_AGENT_PROJECT_REF ?? "",
+  runtime: "node-24",
   dirs: ["./src"],
   // Keep test + eval files out of the task index. They import vitest, which
   // throws at registration. Setting this replaces the built-in defaults, so the

From 9c870f07e0b6491ca34315e6e6337f352a214439 Mon Sep 17 00:00:00 2001
From: Wes Mason <wes@trigger.dev>
Date: Thu, 17 Sep 2026 13:49:36 +0000
Subject: [PATCH 3/6] test(supervisor): pin run-crd workload options against
 silent drift

Mono-RevId: e42ec673635842461d2261b89345b9a2cc847db4
---
 .../src/workloadManager/runCrd.test.ts        | 170 ++++++++++++++++++
 1 file changed, 170 insertions(+)

diff --git a/apps/supervisor/src/workloadManager/runCrd.test.ts b/apps/supervisor/src/workloadManager/runCrd.test.ts
index e2db95ee1d7..e8cbcf7ef7c 100644
--- a/apps/supervisor/src/workloadManager/runCrd.test.ts
+++ b/apps/supervisor/src/workloadManager/runCrd.test.ts
@@ -227,3 +227,173 @@ describe("runnerTokenSecretName", () => {
     );
   });
 });
+
+/**
+ * Ties every shared workload-manager create-option to the Runner that the
+ * run-crd producer builds, so a new per-run option cannot be added and quietly
+ * dropped. It is the class of drift that lost TRIGGER_SNAPSHOT_ROUTE: the field
+ * was optional, three pod backends set it, and runCrd never did, which the type
+ * checker was happy with.
+ *
+ * The property, stated once: every create-option field either changes the
+ * Runner `runnerBodyFor` builds, or is listed in RUN_CRD_EXCLUDED with a reason.
+ * Optionality is not an excuse; a silent drop is. It is checked by behaviour,
+ * not by scanning source: for each field the test sets a probe value and asks
+ * whether the built Runner changes. A comment, a log line, or a reference from
+ * another method cannot fool that, where a textual `opts.<field>` scan could.
+ */
+describe("run-crd carries every shared create-option or excludes it on purpose", () => {
+  /**
+   * Every key of WorkloadManagerCreateOptions. Adding a field to the interface
+   * without adding it here is a compile error (see the exhaustiveness assertion
+   * below): a new option is acknowledged here or the build breaks.
+   */
+  const CREATE_OPTION_KEYS = [
+    "image",
+    "machine",
+    "version",
+    "nextAttemptNumber",
+    "dequeuedAt",
+    "placementTags",
+    "dequeueResponseMs",
+    "pollingIntervalMs",
+    "warmStartCheckMs",
+    "envId",
+    "envType",
+    "orgId",
+    "projectId",
+    "deploymentFriendlyId",
+    "deploymentVersion",
+    "runtime",
+    "deploymentToken",
+    "runId",
+    "runFriendlyId",
+    "snapshotId",
+    "snapshotFriendlyId",
+    "snapshotRoute",
+    "traceContext",
+    "annotations",
+    "hasPrivateLink",
+  ] as const satisfies readonly (keyof WorkloadManagerCreateOptions)[];
+
+  type ListedKey = (typeof CREATE_OPTION_KEYS)[number];
+  type MissingKey = Exclude<keyof WorkloadManagerCreateOptions, ListedKey>;
+  const KEYS_ARE_EXHAUSTIVE: [MissingKey] extends [never] ? true : ["unlisted keys", MissingKey] =
+    true;
+
+  /**
+   * Create-option fields that do not change the Runner `runnerBodyFor` builds,
+   * each with the reason it is not a spec field. Every such field must appear
+   * here, so not carrying one is always a decision on the record rather than an
+   * omission the type checker allowed. Some of these still shape creation by
+   * another route, the runner's name or its token Secret; they just are not
+   * values in the spec.
+   *
+   * snapshotRoute is superseded transport rather than a gap to fill: snapshot
+   * routing is becoming server-owned, so the runner-facing route is being
+   * removed rather than built into the Runner. This entry, the field on the
+   * create options, and the pod backends that set it come out together when that
+   * lands.
+   */
+  const RUN_CRD_EXCLUDED: Partial<Record<ListedKey, string>> = {
+    snapshotRoute:
+      "Superseded transport, not a run-crd gap: snapshot routing is becoming server-owned (a run's residency is decided from its stored state, not a runner-provided field), so the runner-facing route is being removed rather than built into the Runner. This entry, the field, and the pod backends that set it come out together when that lands.",
+    nextAttemptNumber:
+      "Not a spec field: it selects the runner's name via getRunnerId, so the attempt lives in the object's name rather than in the spec runnerBodyFor builds.",
+    deploymentToken:
+      "Not a spec field: it is written to a per-runner Secret and referenced by name (deployment.token), so the raw token is never a value in the spec.",
+    snapshotId: "Internal id; the bootstrap snapshot is identified by its friendly id.",
+    runId: "Internal id; the runner is named for, and reported against, the run's friendly id.",
+    version: "The deployment version is carried instead; nothing reads this alias.",
+    traceContext:
+      "Span context for the pod path's own emission; runnerBodyFor does not build it in.",
+    dequeueResponseMs: "Producer-side timing for the wide event; not built into the Runner.",
+    pollingIntervalMs: "Producer-side timing for the wide event; not built into the Runner.",
+    warmStartCheckMs: "Producer-side timing for the wide event; not built into the Runner.",
+  };
+
+  /**
+   * A value for each field that differs from createOptions()'s baseline, so a
+   * field the producer builds in makes the Runner change and one it ignores
+   * leaves it identical. Total over the keys, so a new option forces a probe
+   * here too.
+   */
+  const PROBES: Record<ListedKey, Partial<WorkloadManagerCreateOptions>> = {
+    image: { image: `registry.example.com/other/worker:2@sha256:${"1".repeat(64)}` },
+    machine: { machine: { name: "micro", cpu: 0.25, memory: 0.25, centsPerMs: 0 } },
+    version: { version: "99.9.9" },
+    nextAttemptNumber: { nextAttemptNumber: 5 },
+    dequeuedAt: { dequeuedAt: new Date("2026-01-01T00:00:00.000Z") },
+    placementTags: { placementTags: [{ key: "pool", values: ["spot"] }] },
+    dequeueResponseMs: { dequeueResponseMs: 999 },
+    pollingIntervalMs: { pollingIntervalMs: 999 },
+    warmStartCheckMs: { warmStartCheckMs: 999 },
+    envId: { envId: "env_other" },
+    envType: { envType: "STAGING" },
+    orgId: { orgId: "org_other" },
+    projectId: { projectId: "proj_other" },
+    deploymentFriendlyId: { deploymentFriendlyId: "deployment_other" },
+    deploymentVersion: { deploymentVersion: "99.9.9" },
+    runtime: { runtime: "bun" },
+    deploymentToken: { deploymentToken: "tok_probe" },
+    runId: { runId: "run_other_internal" },
+    runFriendlyId: { runFriendlyId: "run_other" },
+    snapshotId: { snapshotId: "snapshot_other_internal" },
+    snapshotFriendlyId: { snapshotFriendlyId: "snapshot_other" },
+    snapshotRoute: {
+      snapshotRoute: { version: 1, residency: "redis-primary", organizationId: "org_abc" },
+    },
+    traceContext: { traceContext: { traceparent: "00-probe-probe-01" } },
+    annotations: {
+      annotations: {
+        triggerSource: "schedule",
+        triggerAction: "trigger",
+        rootTriggerSource: "schedule",
+      },
+    },
+    hasPrivateLink: { hasPrivateLink: true },
+  };
+
+  const excluded = new Set(Object.keys(RUN_CRD_EXCLUDED) as ListedKey[]);
+  const baseline = JSON.stringify(runnerBodyFor(createOptions(), meta));
+
+  /** True when setting the field's probe changes the Runner runnerBodyFor builds. */
+  function changesRunner(field: ListedKey): boolean {
+    return JSON.stringify(runnerBodyFor(createOptions(PROBES[field]), meta)) !== baseline;
+  }
+
+  it("lists every create option, so a new field cannot slip past this test", () => {
+    // Fails to compile, not just at runtime, when a key is missing above.
+    expect(KEYS_ARE_EXHAUSTIVE).toBe(true);
+  });
+
+  it("gives each field a probe that sets only that field", () => {
+    // changesRunner reports any output difference, so a probe that also moved a
+    // second option could pass without its own field being built in. Pinning
+    // each probe to a single key keeps a difference attributable to that field.
+    for (const field of CREATE_OPTION_KEYS) {
+      expect(Object.keys(PROBES[field]), `PROBES.${field} must set only ${field}`).toEqual([field]);
+    }
+  });
+
+  it("builds every non-excluded create option into the Runner", () => {
+    const dropped = CREATE_OPTION_KEYS.filter((f) => !excluded.has(f) && !changesRunner(f));
+    expect(
+      dropped,
+      `runnerBodyFor ignores create-options it neither builds in nor excludes: ${
+        dropped.join(", ") || "(none)"
+      }. Build each into the Runner, or declare it in RUN_CRD_EXCLUDED with a reason. ` +
+        `Optionality is not an excuse for a silent drop.`
+    ).toEqual([]);
+  });
+
+  it("excludes only options the Runner genuinely does not carry", () => {
+    // An excluded field that changes the Runner means the exclusion is a lie:
+    // the field is built in after all and its reason is stale.
+    const carried = [...excluded].filter((f) => changesRunner(f)).sort();
+    expect(
+      carried,
+      `RUN_CRD_EXCLUDED lists options runnerBodyFor does build in: ${carried.join(", ")}`
+    ).toEqual([]);
+  });
+});

From 47649784e0227a43aad8222e0fafbe1ebbbd691c Mon Sep 17 00:00:00 2001
From: Daniel Sutton <45313566+d-cs@users.noreply.github.com>
Date: Thu, 17 Sep 2026 13:53:49 +0000
Subject: [PATCH 4/6] feat(webapp): auto-archive inactive preview branches

Add opt-in preview branch auto-archiving after a configurable period
without deployments. Projects can protect named branches and preview the
effect of their settings before saving. Availability is controlled by an
organization or global feature flag and is disabled by default.

Mono-RevId: 96ef71472cc849ed8fffbef47fc4503987ba6288
---
 .../preview-branch-auto-archive.md            |   6 +
 .../presenters/v3/BranchesPresenter.server.ts |  38 +-
 .../route.tsx                                 |  82 ++-
 .../resources.branches.auto-archive.tsx       | 381 ++++++++++
 .../app/services/archiveBranch.server.ts      |  10 +-
 .../services/branchArchiveMutation.server.ts  |  42 ++
 .../previewAutoArchive.server.test.ts         | 684 ++++++++++++++++++
 .../app/services/previewAutoArchive.server.ts | 393 ++++++++++
 apps/webapp/app/utils/previewAutoArchive.ts   |  34 +
 apps/webapp/app/v3/commonWorker.server.ts     |  15 +
 apps/webapp/app/v3/featureFlags.ts            |   3 +
 .../services/initializeDeployment.server.ts   |   5 +
 .../createDeploymentWithNextVersion.server.ts |  37 +-
 .../createDeploymentWithNextVersion.test.ts   |  32 +
 .../test/fixtures/previewAutoArchive.ts       |  66 ++
 apps/webapp/vitest.config.ts                  |   1 +
 .../migration.sql                             |   8 +
 .../migration.sql                             |   8 +
 .../migration.sql                             |   7 +
 .../database/prisma/schema.prisma             |   8 +
 20 files changed, 1829 insertions(+), 31 deletions(-)
 create mode 100644 .server-changes/preview-branch-auto-archive.md
 create mode 100644 apps/webapp/app/routes/resources.branches.auto-archive.tsx
 create mode 100644 apps/webapp/app/services/branchArchiveMutation.server.ts
 create mode 100644 apps/webapp/app/services/previewAutoArchive.server.test.ts
 create mode 100644 apps/webapp/app/services/previewAutoArchive.server.ts
 create mode 100644 apps/webapp/app/utils/previewAutoArchive.ts
 create mode 100644 apps/webapp/test/fixtures/previewAutoArchive.ts
 create mode 100644 internal-packages/database/prisma/migrations/20260916120000_preview_auto_archive/migration.sql
 create mode 100644 internal-packages/database/prisma/migrations/20260916130001_preview_archive_due_index/migration.sql
 create mode 100644 internal-packages/database/prisma/migrations/20260916130002_preview_archive_branch_index/migration.sql

diff --git a/.server-changes/preview-branch-auto-archive.md b/.server-changes/preview-branch-auto-archive.md
new file mode 100644
index 00000000000..b2b6bf5055c
--- /dev/null
+++ b/.server-changes/preview-branch-auto-archive.md
@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+Automatically archive preview branches after a configurable period without deployments, with protected branch names and a preview of affected branches.
diff --git a/apps/webapp/app/presenters/v3/BranchesPresenter.server.ts b/apps/webapp/app/presenters/v3/BranchesPresenter.server.ts
index 06dad762b0c..86159e061ec 100644
--- a/apps/webapp/app/presenters/v3/BranchesPresenter.server.ts
+++ b/apps/webapp/app/presenters/v3/BranchesPresenter.server.ts
@@ -1,3 +1,8 @@
+import { classifyPreviewBranch } from "~/utils/previewAutoArchive";
+import {
+  previewBranchActivity,
+  isPreviewAutoArchiveEnabled,
+} from "~/services/previewAutoArchive.server";
 import { GitMeta } from "@trigger.dev/core/v3";
 import { DEFAULT_DEV_BRANCH } from "@trigger.dev/core/v3/utils/gitBranch";
 import { type RuntimeEnvironmentType } from "@trigger.dev/database";
@@ -103,10 +108,12 @@ export class BranchesPresenter {
     projectSlug: Project["slug"];
     env: BranchableEnvironmentToken;
   } & Options) {
+    const envType = toBranchableEnvironmentType(env);
     const project = await this.#prismaClient.project.findFirst({
       select: {
         id: true,
         organizationId: true,
+        ...(envType === "PREVIEW" ? { organization: { select: { featureFlags: true } } } : {}),
       },
       where: {
         slug: projectSlug,
@@ -124,11 +131,18 @@ export class BranchesPresenter {
       throw new Error("Project not found");
     }
 
-    const envType = toBranchableEnvironmentType(env);
+    const autoArchiveAvailable =
+      envType === "PREVIEW" &&
+      (await isPreviewAutoArchiveEnabled(
+        this.#prismaClient,
+        project.organization?.featureFlags ?? null
+      ));
 
     const branchableEnvironment = await this.#prismaClient.runtimeEnvironment.findFirst({
       select: {
         id: true,
+        previewAutoArchiveAfterDays: true,
+        previewAutoArchiveExcludedBranches: true,
       },
       where: {
         projectId: project.id,
@@ -149,6 +163,7 @@ export class BranchesPresenter {
       }
       return {
         branchableEnvironment: null,
+        autoArchiveAvailable,
         currentPage: page,
         totalPages: 0,
         hasBranches: false,
@@ -235,10 +250,30 @@ export class BranchesPresenter {
       },
     });
 
+    const archiveActivity = autoArchiveAvailable
+      ? await previewBranchActivity(
+          this.#prismaClient,
+          branches.map(({ id }) => id)
+        )
+      : new Map<string, { lastDeploymentAt: Date | null; inProgress: boolean }>();
+
+    const excluded = new Set(branchableEnvironment.previewAutoArchiveExcludedBranches);
+    const archiveNow = new Date();
     const branchesFiltered = branches
       .filter((branch) => envType === "DEVELOPMENT" || branch.branchName !== null)
       .map((branch) => ({
         ...branch,
+        lastDeploymentAt: archiveActivity.get(branch.id)?.lastDeploymentAt ?? null,
+        autoArchive:
+          autoArchiveAvailable && branchableEnvironment.previewAutoArchiveAfterDays !== null
+            ? classifyPreviewBranch(
+                branch,
+                archiveActivity.get(branch.id)!,
+                branchableEnvironment.previewAutoArchiveAfterDays,
+                excluded,
+                archiveNow
+              )
+            : null,
         git: processGitMetadata(branch.git),
         branchName: branch.branchName ?? DEFAULT_DEV_BRANCH,
       }));
@@ -252,6 +287,7 @@ export class BranchesPresenter {
 
     return {
       branchableEnvironment,
+      autoArchiveAvailable,
       currentPage: page,
       totalPages: Math.ceil(visibleCount / BRANCHES_PER_PAGE),
       hasBranches: totalBranches > 0,
diff --git a/apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.branches/route.tsx b/apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.branches/route.tsx
index 044b24f8e0f..48a31788eb7 100644
--- a/apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.branches/route.tsx
+++ b/apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.branches/route.tsx
@@ -1,3 +1,4 @@
+import { AutoArchiveSettings } from "~/routes/resources.branches.auto-archive";
 import { getFormProps, getInputProps, useForm } from "@conform-to/react";
 import { parseWithZod } from "@conform-to/zod/v4";
 import { ArrowUpCircleIcon, CheckIcon, EnvelopeIcon, PlusIcon } from "@heroicons/react/20/solid";
@@ -6,7 +7,7 @@ import { DialogClose } from "@radix-ui/react-dialog";
 import { useFetcher, useSearchParams } from "@remix-run/react";
 import { type ActionFunctionArgs, json } from "@remix-run/server-runtime";
 import { tryCatch } from "@trigger.dev/core/v3";
-import { useCallback, useEffect, useState } from "react";
+import { type ReactNode, useCallback, useEffect, useState } from "react";
 import { SearchInput } from "~/components/primitives/SearchInput";
 import { typedjson, useTypedLoaderData } from "remix-typedjson";
 import { z } from "zod";
@@ -223,6 +224,7 @@ export default function Page() {
     hasBranches,
     canPurchaseBranches,
     canManageBranches,
+    autoArchiveAvailable,
     extraBranches,
     branchPricing,
     maxBranchQuota,
@@ -321,6 +323,21 @@ export default function Page() {
       </NavBar>
       <PageBody scrollable={false}>
         <div className="grid max-h-full min-h-full grid-rows-[auto_1fr_auto]">
+          <div className="flex items-center justify-between gap-x-1.5 p-2">
+            <BranchFilters>
+              {autoArchiveAvailable && (
+                <AutoArchiveSettings
+                  environment={branchableEnvironment}
+                  canManage={canManageBranches}
+                />
+              )}
+            </BranchFilters>
+            <PaginationControls
+              currentPage={currentPage}
+              totalPages={totalPages}
+              showPageNumbers={false}
+            />
+          </div>
           {!hasBranches ? (
             <MainCenteredContainer className="max-w-md">
               <BranchesNoBranches
@@ -333,21 +350,18 @@ export default function Page() {
             </MainCenteredContainer>
           ) : (
             <>
-              <div className="flex items-center justify-between gap-x-1.5 p-2">
-                <BranchFilters />
-                <PaginationControls
-                  currentPage={currentPage}
-                  totalPages={totalPages}
-                  showPageNumbers={false}
-                />
-              </div>
-
               <div className="grid max-h-full min-h-full grid-rows-[1fr] overflow-x-auto">
                 <Table>
                   <TableHeader>
                     <TableRow>
                       <TableHeaderCell>Branch</TableHeaderCell>
                       <TableHeaderCell>Created</TableHeaderCell>
+                      {autoArchiveAvailable && (
+                        <>
+                          <TableHeaderCell>Last deployment</TableHeaderCell>
+                          <TableHeaderCell>Auto-archive</TableHeaderCell>
+                        </>
+                      )}
                       <TableHeaderCell>Git</TableHeaderCell>
                       <TableHeaderCell>Archived</TableHeaderCell>
                       <TableHeaderCell>
@@ -357,7 +371,7 @@ export default function Page() {
                   </TableHeader>
                   <TableBody>
                     {branches.length === 0 ? (
-                      <TableBlankRow colSpan={5}>
+                      <TableBlankRow colSpan={autoArchiveAvailable ? 7 : 5}>
                         <Paragraph>There are no matches for your filters</Paragraph>
                       </TableBlankRow>
                     ) : (
@@ -383,6 +397,33 @@ export default function Page() {
                             <TableCell className={cellClass}>
                               <DateTime date={branch.createdAt} />
                             </TableCell>
+                            {autoArchiveAvailable && (
+                              <>
+                                <TableCell className={cellClass}>
+                                  {branch.lastDeploymentAt ? (
+                                    <DateTime date={branch.lastDeploymentAt} />
+                                  ) : (
+                                    "Never"
+                                  )}
+                                </TableCell>
+                                <TableCell className={cellClass}>
+                                  {branch.archivedAt ? (
+                                    "–"
+                                  ) : !branch.autoArchive ? (
+                                    "Disabled"
+                                  ) : branch.autoArchive.status === "protected" ? (
+                                    "Never"
+                                  ) : branch.autoArchive.status === "inProgress" ? (
+                                    "Deployment in progress"
+                                  ) : (
+                                    <DateTime
+                                      includeTime={false}
+                                      date={branch.autoArchive.archiveAt}
+                                    />
+                                  )}
+                                </TableCell>
+                              </>
+                            )}
                             <TableCell className={cellClass}>
                               <div className="-ml-1 flex items-center">
                                 <GitMetadata git={branch.git} />
@@ -526,7 +567,7 @@ export default function Page() {
   );
 }
 
-export function BranchFilters() {
+export function BranchFilters({ children }: { children?: ReactNode }) {
   const [searchParams, setSearchParams] = useSearchParams();
   const { showArchived } = BranchesOptions.parse(Object.fromEntries(searchParams.entries()));
 
@@ -546,14 +587,17 @@ export function BranchFilters() {
   );
 
   return (
-    <div className="flex w-full items-center justify-between gap-2">
+    <div className="flex w-full flex-wrap items-center justify-between gap-2">
       <SearchInput placeholder="Search branch name…" resetParams={["page"]} />
-      <Switch
-        checked={showArchived ?? false}
-        onCheckedChange={handleArchivedChange}
-        label="Show archived"
-        variant="secondary/small"
-      />
+      <div className="ml-auto flex flex-wrap items-center gap-2">
+        <Switch
+          checked={showArchived ?? false}
+          onCheckedChange={handleArchivedChange}
+          label="Show archived"
+          variant="secondary/small"
+        />
+        {children}
+      </div>
     </div>
   );
 }
diff --git a/apps/webapp/app/routes/resources.branches.auto-archive.tsx b/apps/webapp/app/routes/resources.branches.auto-archive.tsx
new file mode 100644
index 00000000000..d44bc623e15
--- /dev/null
+++ b/apps/webapp/app/routes/resources.branches.auto-archive.tsx
@@ -0,0 +1,381 @@
+import { type ActionFunctionArgs, type SerializeFrom, json } from "@remix-run/server-runtime";
+import { useFetcher } from "@remix-run/react";
+import { useEffect, useRef, useState } from "react";
+import { Cog6ToothIcon } from "@heroicons/react/20/solid";
+import { prisma } from "~/db.server";
+import { requireUserId } from "~/services/session.server";
+import { rbac } from "~/services/rbac.server";
+import {
+  previewAutoArchiveCount,
+  savePreviewAutoArchivePolicy,
+  isPreviewAutoArchiveEnabled,
+} from "~/services/previewAutoArchive.server";
+import { PreviewAutoArchivePolicy } from "~/utils/previewAutoArchive";
+import { Button } from "~/components/primitives/Buttons";
+import { Dialog, DialogContent, DialogHeader, DialogTrigger } from "~/components/primitives/Dialog";
+import { Input } from "~/components/primitives/Input";
+import { TextArea } from "~/components/primitives/TextArea";
+import { Label } from "~/components/primitives/Label";
+import { Paragraph } from "~/components/primitives/Paragraph";
+import { FormError } from "~/components/primitives/FormError";
+import { Switch } from "~/components/primitives/Switch";
+import { readBoundedBodyText } from "~/utils/boundedRequestBody.server";
+
+export async function action({ request }: ActionFunctionArgs) {
+  const userId = await requireUserId(request);
+  if (request.headers.get("content-type")?.split(";")[0] !== "application/x-www-form-urlencoded") {
+    return json({ ok: false, error: "Unsupported form encoding." } as const, { status: 415 });
+  }
+  const body = await readBoundedBodyText(request, 256 * 1024);
+  if (!body.ok)
+    return json({ ok: false, error: "Settings are too large." } as const, { status: 413 });
+  const form = new URLSearchParams(body.text);
+  const environmentId = form.get("environmentId");
+  const intent = form.get("intent");
+  if (typeof environmentId !== "string" || (intent !== "preview" && intent !== "save")) {
+    return json({ ok: false, error: "Invalid request" } as const, { status: 400 });
+  }
+  const policy = PreviewAutoArchivePolicy.safeParse({
+    days: form.get("enabled") === "on" ? Number(form.get("days")) : null,
+    excludedBranches: String(form.get("excludedBranches") ?? "")
+      .split("\n")
+      .map((name) => name.trim())
+      .filter(Boolean),
+  });
+  if (!policy.success) {
+    return json(
+      {
+        ok: false,
+        error: "Enter 1–365 days and up to 100 valid branch names, one per line.",
+      } as const,
+      { status: 400 }
+    );
+  }
+  const parent = await prisma.runtimeEnvironment.findFirst({
+    where: {
+      id: environmentId,
+      type: "PREVIEW",
+      parentEnvironmentId: null,
+      isBranchableEnvironment: true,
+      archivedAt: null,
+      organization: { members: { some: { userId } } },
+      project: { deletedAt: null },
+    },
+    select: {
+      id: true,
+      organizationId: true,
+      projectId: true,
+      organization: { select: { featureFlags: true } },
+    },
+  });
+  if (!parent)
+    return json({ ok: false, error: "Preview environment not found" } as const, { status: 404 });
+  if (!(await isPreviewAutoArchiveEnabled(prisma, parent.organization.featureFlags))) {
+    return json(
+      { ok: false, error: "Preview auto-archive is not enabled for this organization." } as const,
+      { status: 403 }
+    );
+  }
+  const auth = await rbac.authenticateSession(request, {
+    userId,
+    organizationId: parent.organizationId,
+    projectId: parent.projectId,
+  });
+  if (
+    !auth.ok ||
+    !(
+      auth.ability.can("write", { type: "branches", envType: "PREVIEW" }) ||
+      auth.ability.can("write", { type: "deployments", envType: "PREVIEW" })
+    )
+  ) {
+    return json(
+      { ok: false, error: "You don't have permission to manage preview branches." } as const,
+      { status: 403 }
+    );
+  }
+  const { days, excludedBranches } = policy.data;
+  let preview = {
+    count: 0,
+    scheduled: 0,
+    inProgress: 0,
+    protectedBranches: [] as string[],
+    partial: false,
+  };
+  if (intent === "save") {
+    await savePreviewAutoArchivePolicy(prisma, parent.id, policy.data);
+  } else if (days !== null) {
+    try {
+      preview = await previewAutoArchiveCount(prisma, parent.id, days, excludedBranches);
+    } catch {
+      return json(
+        {
+          ok: false,
+          error: "Unable to preview affected branches right now. Please try again.",
+        } as const,
+        { status: 503 }
+      );
+    }
+  }
+
+  return json({
+    ok: true,
+    saved: intent === "save",
+    ...preview,
+    policyKey: JSON.stringify(policy.data),
+  } as const);
+}
+
+export function AutoArchiveSettings({
+  environment,
+  canManage,
+}: {
+  environment: {
+    id: string;
+    previewAutoArchiveAfterDays: number | null;
+    previewAutoArchiveExcludedBranches: string[];
+  };
+  canManage: boolean;
+}) {
+  const [open, setOpen] = useState(false);
+  const fetcher = useFetcher<typeof action>();
+  const toggleRef = useRef<HTMLButtonElement>(null);
+  const enabled = environment.previewAutoArchiveAfterDays !== null;
+
+  function handleToggle(checked: boolean) {
+    if (checked) {
+      setOpen(true);
+    } else {
+      fetcher.submit(
+        {
+          environmentId: environment.id,
+          intent: "save",
+          excludedBranches: environment.previewAutoArchiveExcludedBranches.join("\n"),
+        },
+        { method: "post", action: "/resources/branches/auto-archive" }
+      );
+    }
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <div className="flex shrink-0 flex-col gap-1">
+        <div className="flex items-center gap-1.5">
+          <Switch
+            ref={toggleRef}
+            label="Auto-archive"
+            variant="secondary/small"
+            checked={enabled}
+            onCheckedChange={handleToggle}
+            disabled={!canManage || fetcher.state !== "idle"}
+          />
+          {enabled && (
+            <DialogTrigger asChild>
+              <Button
+                variant="secondary/small"
+                LeadingIcon={Cog6ToothIcon}
+                aria-label="Auto-archive settings"
+                className="shrink-0 whitespace-nowrap"
+                disabled={!canManage || fetcher.state !== "idle"}
+              >
+                Settings
+              </Button>
+            </DialogTrigger>
+          )}
+        </div>
+        {fetcher.data && !fetcher.data.ok && <FormError>{fetcher.data.error}</FormError>}
+      </div>
+      <DialogContent
+        className="max-h-[90vh] overflow-y-auto"
+        onCloseAutoFocus={(event) => {
+          event.preventDefault();
+          toggleRef.current?.focus();
+        }}
+      >
+        <DialogHeader>Auto-archive preview branches</DialogHeader>
+        {open && <AutoArchiveForm environment={environment} onSaved={() => setOpen(false)} />}
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function AutoArchiveForm({
+  environment,
+  onSaved,
+}: {
+  environment: {
+    id: string;
+    previewAutoArchiveAfterDays: number | null;
+    previewAutoArchiveExcludedBranches: string[];
+  };
+  onSaved: () => void;
+}) {
+  const fetcher = useFetcher<typeof action>();
+  const [preview, setPreview] = useState<{
+    data?: SerializeFrom<typeof action> | { ok: false; error: string };
+    pending: boolean;
+  }>({ pending: false });
+  const [requestedKey, setRequestedKey] = useState<string | null>(null);
+  const [days, setDays] = useState(String(environment.previewAutoArchiveAfterDays ?? 14));
+  const [excluded, setExcluded] = useState(
+    environment.previewAutoArchiveExcludedBranches.join("\n")
+  );
+  const policyKey = JSON.stringify({
+    days: Number(days),
+    excludedBranches: [
+      ...new Set(
+        excluded
+          .split("\n")
+          .map((name) => name.trim())
+          .filter(Boolean)
+      ),
+    ],
+  });
+  const valid = PreviewAutoArchivePolicy.safeParse(JSON.parse(policyKey)).success;
+  const reviewed =
+    valid && !preview.pending && preview.data?.ok && preview.data.policyKey === policyKey;
+  const busy = fetcher.state !== "idle";
+  useEffect(() => {
+    if (!valid || busy) return;
+    const controller = new AbortController();
+    const timer = setTimeout(async () => {
+      const policy = JSON.parse(policyKey) as { days: number; excludedBranches: string[] };
+      setRequestedKey(policyKey);
+      setPreview({ pending: true });
+      try {
+        // A read-only POST avoids URL-size limits for exclusions and Remix's
+        // page-wide action revalidation while the user edits the form.
+        const response = await fetch("/resources/branches/auto-archive", {
+          method: "POST",
+          signal: controller.signal,
+          body: new URLSearchParams({
+            environmentId: environment.id,
+            enabled: "on",
+            intent: "preview",
+            days: String(policy.days),
+            excludedBranches: policy.excludedBranches.join("\n"),
+          }),
+        });
+        const data = (await response.json()) as SerializeFrom<typeof action>;
+        if (!controller.signal.aborted) setPreview({ data, pending: false });
+      } catch {
+        if (!controller.signal.aborted) {
+          setPreview({
+            pending: false,
+            data: { ok: false, error: "Unable to preview branches. Edit a field to try again." },
+          });
+        }
+      }
+    }, 200);
+    return () => {
+      clearTimeout(timer);
+      controller.abort();
+    };
+  }, [policyKey, valid, busy, environment.id]);
+  useEffect(() => {
+    if (fetcher.state === "idle" && fetcher.data?.ok && fetcher.data.saved) onSaved();
+  }, [fetcher.state, fetcher.data, onSaved]);
+
+  return (
+    <fetcher.Form
+      method="post"
+      action="/resources/branches/auto-archive"
+      className="mt-4 flex flex-col gap-4"
+    >
+      <input type="hidden" name="environmentId" value={environment.id} />
+      <input type="hidden" name="enabled" value="on" />
+      <div className="flex flex-col gap-2">
+        <Label htmlFor="archive-days">Days without a deployment</Label>
+        <Input
+          id="archive-days"
+          name="days"
+          type="number"
+          min={1}
+          max={365}
+          required
+          disabled={busy}
+          value={days}
+          onChange={(event) => setDays(event.target.value)}
+        />
+      </div>
+      <div className="flex flex-col gap-2">
+        <Label htmlFor="archive-exclusions">Protected branches</Label>
+        <TextArea
+          id="archive-exclusions"
+          name="excludedBranches"
+          rows={3}
+          maxLength={25_600}
+          placeholder="staging"
+          disabled={busy}
+          value={excluded}
+          onChange={(event) => setExcluded(event.target.value)}
+        />
+        <Paragraph>Exact branch names, one per line.</Paragraph>
+      </div>
+      <section
+        className="min-h-36 max-h-48 overflow-y-auto rounded border border-grid-bright p-3"
+        aria-label="Archive preview"
+        aria-live="polite"
+        aria-busy={valid && !reviewed && preview.pending}
+      >
+        <Paragraph className="mb-2 text-text-bright">Preview</Paragraph>
+        {!valid ? (
+          <Paragraph>Enter 1–365 days and valid branch names to see the preview.</Paragraph>
+        ) : reviewed && preview.data?.ok ? (
+          <div className="space-y-2 text-sm text-text-dimmed">
+            <ul className="list-disc space-y-1 pl-4">
+              <li className={preview.data.count > 0 ? "text-amber-400" : undefined}>
+                {preview.data.partial ? "At least " : ""}
+                {preview.data.count} {preview.data.count === 1 ? "branch is" : "branches are"} ready
+                to archive now.
+                {preview.data.count > 0 &&
+                  " Saving will make these branches eligible for the next cleanup check."}
+              </li>
+              <li>
+                {preview.data.partial ? "At least " : ""}
+                {preview.data.scheduled}{" "}
+                {preview.data.scheduled === 1 ? "branch will" : "branches will"} archive later if no
+                new deployments occur.
+              </li>
+              <li>
+                {preview.data.partial ? "At least " : ""}
+                {preview.data.protectedBranches.length} protected{" "}
+                {preview.data.protectedBranches.length === 1 ? "branch will" : "branches will"} be
+                ignored.
+              </li>
+              {preview.data.inProgress > 0 && (
+                <li>
+                  {preview.data.partial ? "At least " : ""}
+                  {preview.data.inProgress}{" "}
+                  {preview.data.inProgress === 1 ? "branch has" : "branches have"} a deployment in
+                  progress and will be skipped.
+                </li>
+              )}
+            </ul>
+            {preview.data.protectedBranches.length > 0 && (
+              <p className="break-words">Protected: {preview.data.protectedBranches.join(", ")}</p>
+            )}
+            {preview.data.partial && (
+              <p>Preview limited to the first 1,000 branches. Cleanup checks all branches.</p>
+            )}
+          </div>
+        ) : requestedKey === policyKey && !preview.pending && preview.data && !preview.data.ok ? (
+          <FormError>{preview.data.error}</FormError>
+        ) : (
+          <Paragraph>Checking branches…</Paragraph>
+        )}
+      </section>
+      {fetcher.data && !fetcher.data.ok && <FormError>{fetcher.data.error}</FormError>}
+      <div className="flex justify-end gap-2">
+        <Button
+          type="submit"
+          name="intent"
+          value="save"
+          variant="primary/medium"
+          disabled={busy || !reviewed}
+        >
+          Save settings
+        </Button>
+      </div>
+    </fetcher.Form>
+  );
+}
diff --git a/apps/webapp/app/services/archiveBranch.server.ts b/apps/webapp/app/services/archiveBranch.server.ts
index 313e9af25b0..33f92ec9749 100644
--- a/apps/webapp/app/services/archiveBranch.server.ts
+++ b/apps/webapp/app/services/archiveBranch.server.ts
@@ -1,7 +1,7 @@
 import { type PrismaClient } from "@trigger.dev/database";
 import { prisma } from "~/db.server";
 import { logger } from "./logger.server";
-import { nanoid } from "nanoid";
+import { archiveBranchMutation } from "./branchArchiveMutation.server";
 import { controlPlaneResolver } from "~/v3/runOpsMigration/controlPlaneResolver.server";
 
 export class ArchiveBranchService {
@@ -84,13 +84,7 @@ export class ArchiveBranchService {
       // Branch archive is a SOFT update — do NOT hard-delete run-ops rows here (it would destroy a
       // retained branch's history). Any env hard-delete/purge belongs on a dedicated purge path
       // (owned by the cloud env-purge runbook), which has no site today.
-      const slug = `${environment.slug}-${nanoid(6)}`;
-      const shortcode = slug;
-
-      const updatedBranch = await this.#prismaClient.runtimeEnvironment.update({
-        where: { id: environmentId, archivedAt: null },
-        data: { archivedAt: new Date(), slug, shortcode },
-      });
+      const updatedBranch = await archiveBranchMutation(this.#prismaClient, environment);
 
       // archivedAt/slug/shortcode changed in the control-plane; drop any cached copy.
       controlPlaneResolver.invalidateEnvironment(environmentId);
diff --git a/apps/webapp/app/services/branchArchiveMutation.server.ts b/apps/webapp/app/services/branchArchiveMutation.server.ts
new file mode 100644
index 00000000000..22c605a3111
--- /dev/null
+++ b/apps/webapp/app/services/branchArchiveMutation.server.ts
@@ -0,0 +1,42 @@
+import { type PrismaClientOrTransaction } from "@trigger.dev/database";
+import { nanoid } from "nanoid";
+
+function archivedSlug(slug: string) {
+  return `${slug}-${nanoid(6)}`;
+}
+
+/** Preserve history and release the original name for a new environment generation. */
+export function archiveBranchMutation(
+  prisma: PrismaClientOrTransaction,
+  environment: { id: string; slug: string },
+  archivedAt = new Date()
+) {
+  const slug = archivedSlug(environment.slug);
+  return prisma.runtimeEnvironment.update({
+    where: { id: environment.id, archivedAt: null },
+    data: { archivedAt, slug, shortcode: slug },
+  });
+}
+
+/** The caller has locked and rechecked these exact environment generations. */
+export async function archiveBranchesMutation(
+  prisma: PrismaClientOrTransaction,
+  environments: Array<{ id: string; slug: string }>,
+  archivedAt: Date
+) {
+  if (environments.length > 100) throw new Error("Archive batch exceeds 100 branches");
+  if (!environments.length) return [];
+  const ids = environments.map(({ id }) => id);
+  const slugs = environments.map(({ slug }) => archivedSlug(slug));
+  // Prisma updateMany applies identical values to every row; each archive needs its own
+  // replacement slug. unnest pairs the bounded IDs and slugs for one UPDATE instead of
+  // up to 100 writes while holding row locks. RETURNING identifies the archived rows
+  // for cache invalidation without a separate read.
+  return prisma.$queryRaw<Array<{ id: string; branchName: string; archivedAt: Date }>>`
+    UPDATE "RuntimeEnvironment" e
+    SET "archivedAt" = ${archivedAt}, "updatedAt" = ${archivedAt}, slug = batch.slug, shortcode = batch.slug
+    FROM unnest(${ids}::text[], ${slugs}::text[]) AS batch(id, slug)
+    WHERE e.id = batch.id AND e."archivedAt" IS NULL
+    RETURNING e.id, e."branchName", e."archivedAt"
+  `;
+}
diff --git a/apps/webapp/app/services/previewAutoArchive.server.test.ts b/apps/webapp/app/services/previewAutoArchive.server.test.ts
new file mode 100644
index 00000000000..bb66b11b0c3
--- /dev/null
+++ b/apps/webapp/app/services/previewAutoArchive.server.test.ts
@@ -0,0 +1,684 @@
+import { postgresTest } from "@internal/testcontainers";
+import { expect, test } from "vitest";
+import type { PrismaClient } from "@trigger.dev/database";
+import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { $transaction } from "~/db.server";
+import { FeatureFlagCatalog, FEATURE_FLAG } from "~/v3/featureFlags";
+import { createDeploymentWithNextVersion } from "~/v3/services/initializeDeployment/createDeploymentWithNextVersion.server";
+import {
+  PreviewAutoArchivePolicy,
+  PREVIEW_AUTO_ARCHIVE_DAY_MS as DAY,
+} from "~/utils/previewAutoArchive";
+import {
+  seedPreviewArchive as seed,
+  archiveTestNow as now,
+  archiveTestOld as old,
+} from "../../test/fixtures/previewAutoArchive";
+import {
+  processPreviewAutoArchivePage,
+  previewAutoArchiveCount,
+  savePreviewAutoArchivePolicy,
+  isPreviewAutoArchiveEnabled,
+  previewBranchActivity,
+} from "./previewAutoArchive.server";
+
+postgresTest(
+  "rollout defaults off with organization overrides over the global flag",
+  async ({ prisma }) => {
+    const key = FEATURE_FLAG.previewAutoArchiveEnabled;
+    expect(FeatureFlagCatalog[key].safeParse("false").success).toBe(false);
+    expect(await isPreviewAutoArchiveEnabled(prisma, null)).toBe(false);
+    expect(await isPreviewAutoArchiveEnabled(prisma, { [key]: true })).toBe(true);
+    await prisma.featureFlag.create({ data: { key, value: true } });
+    expect(await isPreviewAutoArchiveEnabled(prisma, null)).toBe(true);
+    expect(await isPreviewAutoArchiveEnabled(prisma, { [key]: false })).toBe(false);
+    await prisma.featureFlag.update({ where: { key }, data: { value: false } });
+    expect(await isPreviewAutoArchiveEnabled(prisma, null)).toBe(false);
+    expect(await isPreviewAutoArchiveEnabled(prisma, { [key]: true })).toBe(true);
+  }
+);
+
+postgresTest(
+  "disabled rollout preserves configured policies and resumes when globally enabled",
+  async ({ prisma }) => {
+    const { parent, branch } = await seed(prisma, false);
+    const candidate = await branch();
+    const page = await processPreviewAutoArchivePage(prisma, 0, now);
+    expect(page).toMatchObject({ scanned: 0, archived: [] });
+    const paused = await prisma.runtimeEnvironment.findFirstOrThrow({ where: { id: parent.id } });
+    expect(paused.previewAutoArchiveAfterDays).toBe(14);
+    expect(paused.previewAutoArchiveNextCheckAt).toEqual(new Date(now.getTime() + 3_600_000));
+    await prisma.featureFlag.create({
+      data: { key: FEATURE_FLAG.previewAutoArchiveEnabled, value: true },
+    });
+    const resumed = await processPreviewAutoArchivePage(
+      prisma,
+      0,
+      paused.previewAutoArchiveNextCheckAt!
+    );
+    expect(resumed?.archived.map(({ id }) => id)).toEqual([candidate.id]);
+  }
+);
+
+postgresTest(
+  "revoking rollout between pages pauses without losing the cursor",
+  async ({ prisma }) => {
+    const { parent, organization, branch } = await seed(prisma);
+    for (let i = 0; i < 101; i++) await branch();
+    expect((await processPreviewAutoArchivePage(prisma, 0, now))?.archived).toHaveLength(100);
+    const before = await prisma.runtimeEnvironment.findFirstOrThrow({ where: { id: parent.id } });
+    await prisma.organization.update({
+      where: { id: organization.id },
+      data: { featureFlags: { previewAutoArchiveEnabled: false } },
+    });
+    await prisma.featureFlag.create({
+      data: { key: FEATURE_FLAG.previewAutoArchiveEnabled, value: true },
+    });
+    expect(await processPreviewAutoArchivePage(prisma, 0, now)).toMatchObject({
+      scanned: 0,
+      archived: [],
+    });
+    const paused = await prisma.runtimeEnvironment.findFirstOrThrow({ where: { id: parent.id } });
+    expect(paused.previewAutoArchiveCursorId).toBe(before.previewAutoArchiveCursorId);
+    expect(paused.previewAutoArchiveCursorCreatedAt).toEqual(
+      before.previewAutoArchiveCursorCreatedAt
+    );
+    await prisma.organization.update({
+      where: { id: organization.id },
+      data: { featureFlags: {} },
+    });
+    expect(
+      (await processPreviewAutoArchivePage(prisma, 0, paused.previewAutoArchiveNextCheckAt!))
+        ?.archived
+    ).toHaveLength(1);
+  }
+);
+
+const archiveGuard = {
+  archiveGuard: {
+    type: "PREVIEW" as const,
+  },
+};
+
+postgresTest(
+  "branch activity uses latest deployment and bounded existence probes",
+  async ({ prisma }) => {
+    const { branch, deployment } = await seed(prisma);
+    const empty = await branch();
+    const active = await branch();
+    await deployment(active.id, old, "BUILDING");
+    await deployment(active.id, now, "FAILED");
+    const rows = await previewBranchActivity(prisma, [empty.id, active.id]);
+    expect(rows.get(empty.id)).toMatchObject({ lastDeploymentAt: null, inProgress: false });
+    expect(rows.get(active.id)).toMatchObject({ lastDeploymentAt: now, inProgress: true });
+    await expect(previewBranchActivity(prisma, Array(1001).fill(empty.id))).rejects.toThrow(
+      "exceeds 1000"
+    );
+  }
+);
+
+function barrier() {
+  let release!: () => void;
+  const promise = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  return { promise, release };
+}
+
+postgresTest(
+  "live preview separates ready, future, protected and in-progress branches",
+  async ({ prisma }) => {
+    const { parent, branch, deployment } = await seed(prisma);
+    await branch("ready");
+    await branch("new", now);
+    await branch("protected-old");
+    await branch("protected-new", now);
+    const recent = await branch("recent");
+    await deployment(recent.id, now, "FAILED");
+    const active = await branch("active");
+    await deployment(active.id, now, "BUILDING");
+    const archived = await branch("archived");
+    await prisma.runtimeEnvironment.update({
+      where: { id: archived.id },
+      data: { archivedAt: now },
+    });
+    const other = await seed(prisma);
+    await other.branch("other-project");
+    const preview = await previewAutoArchiveCount(
+      prisma,
+      parent.id,
+      14,
+      ["protected-old", "protected-new", "missing"],
+      now
+    );
+    expect({ ...preview, protectedBranches: preview.protectedBranches.sort() }).toEqual({
+      count: 1,
+      scheduled: 2,
+      inProgress: 1,
+      protectedBranches: ["protected-new", "protected-old"],
+      partial: false,
+    });
+    expect(await previewAutoArchiveCount(prisma, parent.id, 30, [], now)).toMatchObject({
+      count: 0,
+      scheduled: 5,
+      inProgress: 1,
+      protectedBranches: [],
+    });
+  }
+);
+
+test("validates whole-day policies and exact protected names", () => {
+  expect(
+    PreviewAutoArchivePolicy.parse({ days: null, excludedBranches: ["staging", "staging"] })
+      .excludedBranches
+  ).toEqual(["staging"]);
+  for (const days of [0, -1, 1.5, 366])
+    expect(PreviewAutoArchivePolicy.safeParse({ days, excludedBranches: [] }).success).toBe(false);
+  expect(
+    PreviewAutoArchivePolicy.safeParse({ days: 14, excludedBranches: ["feature/*"] }).success
+  ).toBe(false);
+});
+
+postgresTest(
+  "shared eligibility agrees with preview counts and keeps recent, protected and in-flight branches",
+  async ({ prisma }) => {
+    const { parent, branch, deployment } = await seed(prisma);
+    const cutoff = new Date(now.getTime() - 14 * DAY);
+    const never = await branch();
+    const boundary = await branch(undefined, cutoff);
+    await branch(undefined, new Date(cutoff.getTime() + 1));
+    await branch("staging");
+    const recentFailure = await branch();
+    await deployment(recentFailure.id, new Date(now.getTime() - DAY), "FAILED");
+    const oldFailure = await branch();
+    await deployment(oldFailure.id, old, "FAILED");
+    const redeployed = await branch();
+    await deployment(redeployed.id, old);
+    await deployment(redeployed.id, new Date(now.getTime() - DAY));
+    for (const status of ["PENDING", "INSTALLING", "BUILDING", "DEPLOYING"] as const) {
+      const active = await branch();
+      await deployment(active.id, old, status);
+    }
+    expect(await previewAutoArchiveCount(prisma, parent.id, 14, ["staging"], now)).toMatchObject({
+      count: 3,
+      partial: false,
+    });
+    const page = await processPreviewAutoArchivePage(prisma, 0, now);
+    expect(page?.archived.map(({ id }) => id).sort()).toEqual(
+      [never.id, boundary.id, oldFailure.id].sort()
+    );
+    expect(await processPreviewAutoArchivePage(prisma, 0, now)).toBeNull();
+    expect(await previewAutoArchiveCount(prisma, parent.id, 14, ["staging"], now)).toMatchObject({
+      count: 0,
+      partial: false,
+    });
+  }
+);
+
+postgresTest("disabled policies and other environment types are excluded", async ({ prisma }) => {
+  const { parent, branch } = await seed(prisma);
+  const candidate = await branch();
+  await savePreviewAutoArchivePolicy(prisma, parent.id, { days: null, excludedBranches: [] }, now);
+  expect(await processPreviewAutoArchivePage(prisma, 0, now)).toBeNull();
+  for (const type of ["DEVELOPMENT", "STAGING", "PRODUCTION"] as const) {
+    await savePreviewAutoArchivePolicy(prisma, parent.id, { days: 14, excludedBranches: [] }, now);
+    await prisma.runtimeEnvironment.update({ where: { id: candidate.id }, data: { type } });
+    expect((await processPreviewAutoArchivePage(prisma, 0, now))?.archived).toEqual([]);
+  }
+});
+
+postgresTest(
+  "duplicate workers preserve history and cannot revisit a replacement generation",
+  async ({ prisma }) => {
+    const { branch, deployment } = await seed(prisma);
+    const original = await branch("exploration");
+    const history = await deployment(original.id, old);
+    const results = await Promise.all(
+      [0, 1, 2, 3].map((lane) => processPreviewAutoArchivePage(prisma, lane, now))
+    );
+    expect(results.flatMap((result) => result?.archived ?? [])).toHaveLength(1);
+    const replacement = await branch("exploration", now);
+    expect(replacement.id).not.toBe(original.id);
+    expect(await processPreviewAutoArchivePage(prisma, 0, now)).toBeNull();
+    expect(
+      (await prisma.runtimeEnvironment.findFirstOrThrow({ where: { id: replacement.id } }))
+        .archivedAt
+    ).toBeNull();
+    expect(
+      await prisma.workerDeployment.count({ where: { id: history.id, environmentId: original.id } })
+    ).toBe(1);
+  }
+);
+
+postgresTest(
+  "deployment locks are skipped without waiting, and the next sweep sees the deployment",
+  async ({ prisma }) => {
+    const { branch, deployData } = await seed(prisma);
+    const candidate = await branch();
+    const inserted = barrier();
+    const commit = barrier();
+    const deploying = $transaction(
+      prisma,
+      "testDeploymentFirst",
+      async (tx) => {
+        await createDeploymentWithNextVersion(tx, candidate.id, deployData, archiveGuard);
+        inserted.release();
+        await commit.promise;
+      },
+      { timeout: 15_000 }
+    );
+    await inserted.promise;
+    try {
+      expect((await processPreviewAutoArchivePage(prisma, 0, now))?.archived).toEqual([]);
+    } finally {
+      commit.release();
+    }
+    await deploying;
+    expect(
+      (await processPreviewAutoArchivePage(prisma, 0, new Date(now.getTime() + 60 * 60 * 1000)))
+        ?.archived
+    ).toEqual([]);
+    expect(
+      (await prisma.runtimeEnvironment.findFirstOrThrow({ where: { id: candidate.id } })).archivedAt
+    ).toBeNull();
+  }
+);
+
+postgresTest(
+  "a deployment committed after page selection is seen by the activity read after locking",
+  async ({ prisma }) => {
+    const { branch, deployData } = await seed(prisma);
+    const candidate = await branch();
+    const scanned = barrier();
+    const resume = barrier();
+    let gated = false;
+    // Pause a real query after it returns candidates; no database calls are mocked.
+    const coordinated = prisma.$extends({
+      query: {
+        $queryRaw: async ({ args, query }) => {
+          const result = await query(args);
+          if (
+            !gated &&
+            Array.isArray(result) &&
+            result.some(
+              (row) =>
+                row !== null && typeof row === "object" && "id" in row && row.id === candidate.id
+            )
+          ) {
+            gated = true;
+            scanned.release();
+            await resume.promise;
+          }
+          return result;
+        },
+      },
+    });
+    const cleaning = processPreviewAutoArchivePage(coordinated as unknown as PrismaClient, 0, now);
+    await scanned.promise;
+    try {
+      await createDeploymentWithNextVersion(
+        prisma,
+        candidate.id,
+        () => ({
+          ...deployData(),
+          status: "FAILED",
+          createdAt: now,
+        }),
+        archiveGuard
+      );
+    } finally {
+      resume.release();
+    }
+    expect((await cleaning)?.archived).toEqual([]);
+    expect(
+      (await prisma.runtimeEnvironment.findFirstOrThrow({ where: { id: candidate.id } })).archivedAt
+    ).toBeNull();
+  }
+);
+
+postgresTest(
+  "archive-first rejects a deployment prepared against the old generation",
+  async ({ prisma }) => {
+    const { branch, deployData } = await seed(prisma);
+    const candidate = await branch();
+    const preparing = barrier();
+    const prepared = barrier();
+    const deploying = createDeploymentWithNextVersion(
+      prisma,
+      candidate.id,
+      async () => {
+        preparing.release();
+        await prepared.promise;
+        return deployData();
+      },
+      archiveGuard
+    );
+    const rejected = expect(deploying).rejects.toMatchObject({
+      name: "ServiceValidationError",
+      status: 409,
+    });
+    await preparing.promise;
+    try {
+      expect((await processPreviewAutoArchivePage(prisma, 0, now))?.archived).toHaveLength(1);
+    } finally {
+      prepared.release();
+    }
+    await rejected;
+    expect(await prisma.workerDeployment.count({ where: { environmentId: candidate.id } })).toBe(0);
+  }
+);
+
+postgresTest(
+  "flag enabled during deployment preparation cannot bypass the archive lock",
+  async ({ prisma }) => {
+    const { branch, deployData, project } = await seed(prisma, false);
+    await prisma.organization.update({
+      where: { id: project.organizationId },
+      data: { featureFlags: { previewAutoArchiveEnabled: false } },
+    });
+    const candidate = await branch();
+    const preparing = barrier();
+    const resume = barrier();
+    const deploying = createDeploymentWithNextVersion(
+      prisma,
+      candidate.id,
+      async () => {
+        preparing.release();
+        await resume.promise;
+        return deployData();
+      },
+      archiveGuard
+    );
+    const rejected = expect(deploying).rejects.toMatchObject({ status: 409 });
+    await preparing.promise;
+    try {
+      await prisma.organization.update({
+        where: { id: project.organizationId },
+        data: { featureFlags: { previewAutoArchiveEnabled: true } },
+      });
+      expect((await processPreviewAutoArchivePage(prisma, 0, now))?.archived).toHaveLength(1);
+    } finally {
+      resume.release();
+    }
+    await rejected;
+    expect(await prisma.workerDeployment.count({ where: { environmentId: candidate.id } })).toBe(0);
+  }
+);
+
+postgresTest(
+  "a policy update owns the root and prevents cleanup using an outdated policy",
+  async ({ prisma }) => {
+    const { parent, branch } = await seed(prisma);
+    await branch();
+    const changed = barrier();
+    const commit = barrier();
+    const saving = $transaction(
+      prisma,
+      "testPolicyFirst",
+      async (tx) => {
+        await tx.runtimeEnvironment.update({
+          where: { id: parent.id },
+          data: { previewAutoArchiveAfterDays: null, previewAutoArchiveNextCheckAt: null },
+        });
+        changed.release();
+        await commit.promise;
+      },
+      { timeout: 15_000 }
+    );
+    await changed.promise;
+    try {
+      expect(await processPreviewAutoArchivePage(prisma, 0, now)).toBeNull();
+    } finally {
+      commit.release();
+    }
+    await saving;
+    expect(await processPreviewAutoArchivePage(prisma, 0, now)).toBeNull();
+  }
+);
+
+postgresTest(
+  "transaction-scoped lanes bound work across duplicate worker instances",
+  async ({ prisma }) => {
+    await seed(prisma);
+    const held = barrier();
+    const release = barrier();
+    const owner = $transaction(
+      prisma,
+      "holdArchiveLane",
+      async (tx) => {
+        // Prisma has no advisory-lock API. Hold the real production lane in this
+        // transaction so the test exercises contention between database connections.
+        await tx.$queryRaw`SELECT true AS held FROM (SELECT pg_advisory_xact_lock(hashtext('preview-branch-auto-archive'), 0)) AS lock`;
+        held.release();
+        await release.promise;
+      },
+      { timeout: 15_000 }
+    );
+    await held.promise;
+    try {
+      expect(await processPreviewAutoArchivePage(prisma, 0, now)).toBeNull();
+    } finally {
+      release.release();
+    }
+    await owner;
+    expect(await processPreviewAutoArchivePage(prisma, 0, now)).not.toBeNull();
+  }
+);
+
+postgresTest(
+  "bounded pages advance over sparse candidates and resume after completed work disappears",
+  async ({ prisma }) => {
+    const { parent, branch, deployment } = await seed(prisma);
+    const ids: string[] = [];
+    for (let i = 0; i < 205; i++) {
+      const b = await branch();
+      ids.push(b.id);
+      if (i < 200) await deployment(b.id, now, "FAILED");
+    }
+    const first = await processPreviewAutoArchivePage(prisma, 0, now);
+    expect(first?.scanned).toBe(100);
+    expect(first?.archived).toHaveLength(0);
+    const second = await processPreviewAutoArchivePage(prisma, 0, now);
+    expect(second?.scanned).toBe(100);
+    expect(second?.archived).toHaveLength(0);
+    const third = await processPreviewAutoArchivePage(prisma, 0, now);
+    expect(third?.scanned).toBe(5);
+    expect(third?.archived).toHaveLength(5);
+    const saved = await prisma.runtimeEnvironment.findFirstOrThrow({ where: { id: parent.id } });
+    expect(saved.previewAutoArchiveCursorId).toBeNull();
+    expect(saved.previewAutoArchiveNextCheckAt).toEqual(new Date(now.getTime() + 60 * 60 * 1000));
+    // A policy change must reset progress, so earlier branches are considered again.
+    await savePreviewAutoArchivePolicy(prisma, parent.id, { days: 1, excludedBranches: [] }, now);
+    expect(
+      (await prisma.runtimeEnvironment.findFirstOrThrow({ where: { id: parent.id } }))
+        .previewAutoArchiveCursorId
+    ).toBeNull();
+  }
+);
+
+postgresTest(
+  "a failed progress commit rolls back archives, backs off and lets other projects proceed",
+  async ({ prisma }) => {
+    const first = await seed(prisma);
+    await first.branch("rollback-target");
+    const other = await seed(prisma);
+    await other.branch("healthy-target");
+    // Prisma has no function DDL API. Embed this test-owned ID in a trigger function
+    // to fail the real progress write and verify rollback of the preceding archives.
+    await prisma.$executeRawUnsafe(`CREATE FUNCTION reject_archive_progress() RETURNS trigger LANGUAGE plpgsql AS $$
+    BEGIN IF OLD.id = '${first.parent.id}' AND NEW."previewAutoArchiveNextCheckAt" = TIMESTAMP '2026-09-16 13:00:00'
+    THEN RAISE EXCEPTION 'simulated crash before progress commit'; END IF; RETURN NEW; END $$`);
+    // Trigger DDL is unavailable through Prisma models; attach the injected failure
+    // to the actual UPDATE instead of mocking a database result.
+    await prisma.$executeRawUnsafe(
+      'CREATE TRIGGER archive_progress_failure BEFORE UPDATE ON "RuntimeEnvironment" FOR EACH ROW EXECUTE FUNCTION reject_archive_progress()'
+    );
+    await expect(processPreviewAutoArchivePage(prisma, 0, now)).rejects.toThrow("simulated crash");
+    expect(
+      await prisma.runtimeEnvironment.count({
+        where: { parentEnvironmentId: first.parent.id, archivedAt: { not: null } },
+      })
+    ).toBe(0);
+    const backedOff = await prisma.runtimeEnvironment.findFirstOrThrow({
+      where: { id: first.parent.id },
+    });
+    expect(backedOff.previewAutoArchiveCursorId).toBeNull();
+    expect(backedOff.previewAutoArchiveNextCheckAt).toEqual(
+      new Date(now.getTime() + 5 * 60 * 1000)
+    );
+    expect((await processPreviewAutoArchivePage(prisma, 0, now))?.parentId).toBe(other.parent.id);
+    // Remove the test trigger through DDL so the retry can exercise a successful commit.
+    await prisma.$executeRawUnsafe('DROP TRIGGER archive_progress_failure ON "RuntimeEnvironment"');
+    expect(
+      (await processPreviewAutoArchivePage(prisma, 0, new Date(now.getTime() + 5 * 60 * 1000)))
+        ?.archived
+    ).toHaveLength(1);
+  }
+);
+
+postgresTest(
+  "a large project yields between pages and deleted tenants stop scheduling",
+  async ({ prisma }) => {
+    const first = await seed(prisma);
+    for (let i = 0; i < 101; i++) await first.branch();
+    const second = await seed(prisma);
+    await prisma.runtimeEnvironment.update({
+      where: { id: first.parent.id },
+      data: { previewAutoArchiveNextCheckAt: old },
+    });
+    expect((await processPreviewAutoArchivePage(prisma, 0, now))?.parentId).toBe(first.parent.id);
+    // The first page moves to the back of the due queue.
+    await prisma.runtimeEnvironment.update({
+      where: { id: second.parent.id },
+      data: { previewAutoArchiveNextCheckAt: new Date(now.getTime() - 1) },
+    });
+    await prisma.organization.update({
+      where: { id: second.organization.id },
+      data: { deletedAt: now },
+    });
+    expect((await processPreviewAutoArchivePage(prisma, 0, now))?.parentId).toBe(second.parent.id);
+    expect(
+      (await prisma.runtimeEnvironment.findFirstOrThrow({ where: { id: second.parent.id } }))
+        .previewAutoArchiveNextCheckAt
+    ).toBeNull();
+    const last = await processPreviewAutoArchivePage(prisma, 0, now);
+    expect(last?.parentId).toBe(first.parent.id);
+    expect(last?.archived).toHaveLength(1);
+    expect(last?.complete).toBe(true);
+  }
+);
+
+postgresTest("preview counts are bounded and disclose incomplete results", async ({ prisma }) => {
+  const { parent, project, organization } = await seed(prisma);
+  // Test fixture only: generate_series creates the deterministic overflow sample in
+  // one INSERT. This is fixture convenience, not a requirement of the production query.
+  await prisma.$executeRaw`
+    INSERT INTO "RuntimeEnvironment" (id, slug, shortcode, "apiKey", "pkApiKey", "projectId", "organizationId", type, "branchName", "parentEnvironmentId", "createdAt", "updatedAt")
+    SELECT 'count-' || i, 'count-' || i, 'count-' || i, 'api-' || i, 'pk-' || i, ${project.id}, ${organization.id}, 'PREVIEW', 'branch-' || i, ${parent.id}, ${old}, ${old}
+    FROM generate_series(1, 1002) AS i
+  `;
+  expect(await previewAutoArchiveCount(prisma, parent.id, 14, [], now)).toMatchObject({
+    count: 1000,
+    partial: true,
+  });
+});
+
+postgresTest(
+  "additive migrations preserve branches and create usable indexes",
+  async ({ prisma, postgresContainer }) => {
+    const { parent, branch } = await seed(prisma);
+    const existing = await branch();
+    // Prisma cannot remove columns through its model API. Recreate the pre-migration
+    // table shape in this isolated test database before running the real migrations.
+    await prisma.$executeRawUnsafe(
+      'ALTER TABLE "RuntimeEnvironment" DROP COLUMN "previewAutoArchiveAfterDays", DROP COLUMN "previewAutoArchiveExcludedBranches", DROP COLUMN "previewAutoArchiveNextCheckAt", DROP COLUMN "previewAutoArchiveCursorCreatedAt", DROP COLUMN "previewAutoArchiveCursorId"'
+    );
+    const migrations = [
+      "20260916120000_preview_auto_archive",
+      "20260916130001_preview_archive_due_index",
+      "20260916130002_preview_archive_branch_index",
+    ];
+    const directory = await mkdtemp(join(tmpdir(), "preview-archive-migrations-"));
+    const database = fileURLToPath(
+      new URL("../../../../internal-packages/database/", import.meta.url)
+    );
+    const schema = join(directory, "schema.prisma");
+    const env = {
+      ...process.env,
+      DATABASE_URL: postgresContainer.getConnectionUri(),
+      DIRECT_URL: postgresContainer.getConnectionUri(),
+    };
+    const exec = promisify(execFile);
+    try {
+      await copyFile(join(database, "prisma/schema.prisma"), schema);
+      await mkdir(join(directory, "migrations/000_baseline"), { recursive: true });
+      await writeFile(
+        join(directory, "migrations/000_baseline/migration.sql"),
+        "-- db push baseline\n"
+      );
+      await writeFile(
+        join(directory, "migrations/migration_lock.toml"),
+        'provider = "postgresql"\n'
+      );
+      for (const migration of migrations.slice(0, 1)) {
+        await mkdir(join(directory, "migrations", migration));
+        await copyFile(
+          join(database, "prisma/migrations", migration, "migration.sql"),
+          join(directory, "migrations", migration, "migration.sql")
+        );
+      }
+      // Exercise the real Prisma runner: splitting SQL statements masks concurrent-index failures.
+      await exec(
+        "pnpm",
+        ["exec", "prisma", "migrate", "resolve", "--applied", "000_baseline", "--schema", schema],
+        { cwd: database, env }
+      );
+      await exec("pnpm", ["exec", "prisma", "migrate", "deploy", "--schema", schema], {
+        cwd: database,
+        env,
+      });
+      // Operations may pre-create indexes between the schema rollout and index migrations.
+      const dueSql = await readFile(
+        join(database, "prisma/migrations", migrations[1], "migration.sql"),
+        "utf8"
+      );
+      // Run the exact checked-in index DDL to exercise operational pre-creation;
+      // Prisma's model API cannot create a concurrent partial index.
+      await prisma.$executeRawUnsafe(dueSql);
+      for (const migration of migrations.slice(1)) {
+        await mkdir(join(directory, "migrations", migration));
+        await copyFile(
+          join(database, "prisma/migrations", migration, "migration.sql"),
+          join(directory, "migrations", migration, "migration.sql")
+        );
+      }
+      await exec("pnpm", ["exec", "prisma", "migrate", "deploy", "--schema", schema], {
+        cwd: database,
+        env,
+      });
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+    const migrated = await prisma.runtimeEnvironment.findFirstOrThrow({
+      where: { id: existing.id },
+    });
+    expect(migrated.archivedAt).toBeNull();
+    expect(migrated.previewAutoArchiveNextCheckAt).toBeNull();
+    expect(migrated.previewAutoArchiveExcludedBranches).toEqual([]);
+    await savePreviewAutoArchivePolicy(prisma, parent.id, { days: 14, excludedBranches: [] }, now);
+    expect((await processPreviewAutoArchivePage(prisma, 0, now))?.archived).toHaveLength(1);
+    // Index validity lives in PostgreSQL catalogs, which are not Prisma models.
+    // Inspect the real build results rather than assuming migration success implies validity.
+    const indexes = await prisma.$queryRaw<
+      Array<{ relname: string; indisvalid: boolean }>
+    >`SELECT c.relname, i.indisvalid FROM pg_index i JOIN pg_class c ON c.oid = i.indexrelid WHERE c.relname IN ('RuntimeEnvironment_preview_archive_due_idx', 'RuntimeEnvironment_preview_archive_scan_idx')`;
+    expect(indexes).toHaveLength(2);
+    expect(indexes.every((i) => i.indisvalid)).toBe(true);
+  },
+  60_000
+);
diff --git a/apps/webapp/app/services/previewAutoArchive.server.ts b/apps/webapp/app/services/previewAutoArchive.server.ts
new file mode 100644
index 00000000000..268355962f3
--- /dev/null
+++ b/apps/webapp/app/services/previewAutoArchive.server.ts
@@ -0,0 +1,393 @@
+import {
+  Prisma,
+  type PrismaClient,
+  type PrismaClientOrTransaction,
+  type RuntimeEnvironment,
+} from "@trigger.dev/database";
+import { $transaction } from "~/db.server";
+import {
+  PREVIEW_AUTO_ARCHIVE_DAY_MS,
+  PreviewAutoArchivePolicy,
+  classifyPreviewBranch,
+  type PreviewBranchActivity,
+} from "~/utils/previewAutoArchive";
+import { archiveBranchesMutation } from "./branchArchiveMutation.server";
+import { logger } from "./logger.server";
+import { FEATURE_FLAG } from "~/v3/featureFlags";
+import { makeFlag } from "~/v3/featureFlags.server";
+import { trail } from "agentcrumbs"; // @crumbs
+
+const crumb = trail("webapp"); // @crumbs
+const PREVIEW_ARCHIVE_PAGE_SIZE = 100;
+const PREVIEW_ARCHIVE_LANES = 4;
+const PREVIEW_LIMIT = 1_000;
+const HOUR_MS = 60 * 60 * 1_000;
+const RETRY_MS = 5 * 60 * 1_000;
+const MAX_PAGES_PER_TICK = 100;
+const TICK_BUDGET_MS = 20_000;
+
+/** One bounded activity read shared by the list, settings preview, and cleanup. */
+export async function previewBranchActivity(prisma: PrismaClientOrTransaction, ids: string[]) {
+  if (ids.length > PREVIEW_LIMIT) throw new Error("Branch activity batch exceeds 1000 branches");
+  if (!ids.length) return new Map<string, PreviewBranchActivity>();
+  // Prisma cannot express these per-branch LATERAL LIMIT 1 lookups in one query.
+  // unnest supplies the bounded IDs; the existing deployment indexes find the latest
+  // attempt and any active attempt without loading history or issuing per-branch queries.
+  const rows = await prisma.$queryRaw<Array<PreviewBranchActivity & { id: string }>>`
+    SELECT b.id, latest."createdAt" AS "lastDeploymentAt", (active.found IS NOT NULL) AS "inProgress"
+    FROM unnest(${ids}::text[]) AS b(id)
+    LEFT JOIN LATERAL (
+      SELECT d."createdAt" FROM "WorkerDeployment" d WHERE d."environmentId" = b.id
+      ORDER BY d."createdAt" DESC LIMIT 1
+    ) latest ON true
+    LEFT JOIN LATERAL (
+      SELECT true AS found FROM "WorkerDeployment" d WHERE d."environmentId" = b.id
+        AND d.status IN ('PENDING', 'INSTALLING', 'BUILDING', 'DEPLOYING') LIMIT 1
+    ) active ON true
+  `;
+  return new Map(rows.map((row) => [row.id, row]));
+}
+
+export function isPreviewAutoArchiveEnabled(
+  prisma: PrismaClientOrTransaction,
+  organizationFlags: unknown
+) {
+  return makeFlag(prisma)({
+    key: FEATURE_FLAG.previewAutoArchiveEnabled,
+    defaultValue: false,
+    overrides:
+      organizationFlags &&
+      typeof organizationFlags === "object" &&
+      !Array.isArray(organizationFlags)
+        ? (organizationFlags as Record<string, unknown>)
+        : undefined,
+  });
+}
+
+type DuePolicy = {
+  id: string;
+  previewAutoArchiveAfterDays: number;
+  previewAutoArchiveExcludedBranches: string[];
+  previewAutoArchiveNextCheckAt: Date;
+  previewAutoArchiveCursorCreatedAt: Date | null;
+  previewAutoArchiveCursorId: string | null;
+  projectDeletedAt: Date | null;
+  organizationDeletedAt: Date | null;
+  organizationFlags: Prisma.JsonValue;
+};
+
+type ArchiveBranch = Pick<RuntimeEnvironment, "id" | "slug" | "branchName" | "createdAt">;
+
+/** Claim one configured preview root using RuntimeEnvironment_preview_archive_due_idx. */
+function previewArchiveDueQuery(now: Date) {
+  // Prisma cannot express FOR UPDATE SKIP LOCKED. Claim and read the next due policy
+  // together so concurrent workers take different roots. OF e locks only the environment,
+  // while the joins provide tenant deletion and rollout state without extra lookups.
+  return Prisma.sql`
+    SELECT e.id, e."previewAutoArchiveAfterDays", e."previewAutoArchiveExcludedBranches",
+      e."previewAutoArchiveNextCheckAt", e."previewAutoArchiveCursorCreatedAt", e."previewAutoArchiveCursorId",
+      p."deletedAt" AS "projectDeletedAt", o."deletedAt" AS "organizationDeletedAt",
+      o."featureFlags" AS "organizationFlags"
+    FROM "RuntimeEnvironment" e
+    JOIN "Project" p ON p.id = e."projectId"
+    JOIN "Organization" o ON o.id = e."organizationId"
+    WHERE e.type = 'PREVIEW' AND e."parentEnvironmentId" IS NULL
+      AND e."isBranchableEnvironment" = true AND e."archivedAt" IS NULL
+      AND e."previewAutoArchiveAfterDays" IS NOT NULL
+      AND e."previewAutoArchiveNextCheckAt" IS NOT NULL AND e."previewAutoArchiveNextCheckAt" <= ${now}
+    ORDER BY e."previewAutoArchiveNextCheckAt", e.id
+    LIMIT 1 FOR UPDATE OF e SKIP LOCKED
+  `;
+}
+
+export async function previewAutoArchiveCount(
+  prisma: PrismaClient,
+  parentId: string,
+  days: number,
+  exclusions: string[],
+  now = new Date()
+) {
+  const result = await $transaction(
+    prisma,
+    "previewAutoArchiveCount",
+    async (tx) => {
+      const branches = await tx.runtimeEnvironment.findMany({
+        where: {
+          parentEnvironmentId: parentId,
+          type: "PREVIEW",
+          archivedAt: null,
+          branchName: { not: null },
+        },
+        select: { id: true, branchName: true, createdAt: true },
+        orderBy: [{ createdAt: "asc" }, { id: "asc" }],
+        take: PREVIEW_LIMIT + 1,
+      });
+      const sample = branches.slice(0, PREVIEW_LIMIT);
+      const activity = await previewBranchActivity(
+        tx,
+        sample.map(({ id }) => id)
+      );
+      const excluded = new Set(exclusions);
+      const result = {
+        count: 0,
+        scheduled: 0,
+        inProgress: 0,
+        protectedBranches: [] as string[],
+        partial: branches.length > PREVIEW_LIMIT,
+      };
+      for (const branch of sample) {
+        const { status } = classifyPreviewBranch(
+          branch,
+          activity.get(branch.id)!,
+          days,
+          excluded,
+          now
+        );
+        switch (status) {
+          case "protected":
+            result.protectedBranches.push(branch.branchName!);
+            break;
+          case "inProgress":
+            result.inProgress++;
+            break;
+          case "ready":
+            result.count++;
+            break;
+          case "scheduled":
+            result.scheduled++;
+            break;
+        }
+      }
+      return result;
+    },
+    { timeout: 5_000, maxWait: 1_000 }
+  );
+  if (!result) throw new Error("Failed to preview automatic archiving");
+  return result;
+}
+
+/** The route has already enforced membership and write permission. One row update
+ * changes policy and scheduling together, serializing with an executing page. */
+export async function savePreviewAutoArchivePolicy(
+  prisma: PrismaClient,
+  parentId: string,
+  input: { days: number | null; excludedBranches: string[] },
+  now = new Date()
+) {
+  const { days, excludedBranches } = PreviewAutoArchivePolicy.parse(input);
+  await prisma.runtimeEnvironment.update({
+    where: {
+      id: parentId,
+      type: "PREVIEW",
+      parentEnvironmentId: null,
+      isBranchableEnvironment: true,
+      archivedAt: null,
+    },
+    data: {
+      previewAutoArchiveAfterDays: days,
+      previewAutoArchiveExcludedBranches: excludedBranches,
+      previewAutoArchiveNextCheckAt: days === null ? null : now,
+      previewAutoArchiveCursorCreatedAt: null,
+      previewAutoArchiveCursorId: null,
+    },
+  });
+}
+
+/** At most four database pages globally, even with duplicate jobs or many webapp
+ * instances. Advisory locks are transaction-scoped: no lease TTL or orphan recovery. */
+export async function processPreviewAutoArchivePage(
+  prisma: PrismaClient,
+  lane: number,
+  now = new Date()
+) {
+  if (!Number.isInteger(lane) || lane < 0 || lane >= PREVIEW_ARCHIVE_LANES)
+    throw new Error("Invalid archive lane");
+  let claimed: DuePolicy | undefined;
+  const started = performance.now();
+  try {
+    const result = await $transaction(
+      prisma,
+      "processPreviewAutoArchivePage",
+      async (tx) => {
+        // PostgreSQL advisory locks cap concurrent cleanup pages across all app instances;
+        // an in-process limiter would not. Prisma has no advisory-lock API. The try form
+        // returns immediately when occupied, and the lock is released with this transaction.
+        const [lock] = await tx.$queryRaw<Array<{ acquired: boolean }>>`
+        SELECT pg_try_advisory_xact_lock(hashtext('preview-branch-auto-archive'), ${lane}::int) AS acquired
+      `;
+        if (!lock.acquired) return null;
+        // Execute the atomic policy claim defined above; Prisma findFirst cannot hold
+        // the SKIP LOCKED row claim through archiving and cursor advancement.
+        const [parent] = await tx.$queryRaw<DuePolicy[]>(previewArchiveDueQuery(now));
+        if (!parent) return null;
+        claimed = parent;
+        if (parent.projectDeletedAt || parent.organizationDeletedAt) {
+          await tx.runtimeEnvironment.update({
+            where: { id: parent.id },
+            data: {
+              previewAutoArchiveNextCheckAt: null,
+              previewAutoArchiveCursorCreatedAt: null,
+              previewAutoArchiveCursorId: null,
+            },
+          });
+          return { parentId: parent.id, scanned: 0, candidates: 0, archived: [], complete: true };
+        }
+        if (!(await isPreviewAutoArchiveEnabled(tx, parent.organizationFlags))) {
+          crumb("preview archive rollout disabled", { parentId: parent.id }); // @crumbs
+          // Keep durable progress and policy for re-enablement, without rescanning a
+          // disabled organization on every tick or starving other due projects.
+          await tx.runtimeEnvironment.update({
+            where: { id: parent.id },
+            data: { previewAutoArchiveNextCheckAt: new Date(now.getTime() + HOUR_MS) },
+          });
+          return { parentId: parent.id, scanned: 0, candidates: 0, archived: [], complete: true };
+        }
+        const cutoff = new Date(
+          now.getTime() - parent.previewAutoArchiveAfterDays * PREVIEW_AUTO_ARCHIVE_DAY_MS
+        );
+        const cursorCreatedAt = parent.previewAutoArchiveCursorCreatedAt;
+        const cursorId = parent.previewAutoArchiveCursorId;
+        // A tuple comparison seeks directly into the (parentEnvironmentId, createdAt, id)
+        // index. Prisma's equivalent OR filter can rescan earlier IDs sharing the timestamp.
+        const scanned = await tx.$queryRaw<Array<Omit<ArchiveBranch, "slug">>>`
+          SELECT id, "branchName", "createdAt" FROM "RuntimeEnvironment"
+          WHERE "parentEnvironmentId" = ${parent.id} AND type = 'PREVIEW'
+            AND "archivedAt" IS NULL AND "branchName" IS NOT NULL
+            AND "createdAt" <= ${cutoff}
+            ${
+              cursorCreatedAt && cursorId
+                ? Prisma.sql`AND ("createdAt", id) > (${cursorCreatedAt}, ${cursorId})`
+                : Prisma.empty
+            }
+          ORDER BY "createdAt", id
+          LIMIT ${PREVIEW_ARCHIVE_PAGE_SIZE}
+        `;
+        const excluded = new Set(parent.previewAutoArchiveExcludedBranches);
+        const ids = scanned
+          .filter(({ branchName }) => !excluded.has(branchName!))
+          .map(({ id }) => id);
+        let eligible: ArchiveBranch[] = [];
+        if (ids.length) {
+          // Prisma cannot express FOR UPDATE SKIP LOCKED. Share the deployment row lock
+          // before checking activity, skipping busy branches instead of waiting. Read the
+          // current slug under that lock and omit rows a manual archive already archived.
+          const locked = await tx.$queryRaw<ArchiveBranch[]>`
+            SELECT id, slug, "branchName", "createdAt" FROM "RuntimeEnvironment"
+            WHERE id = ANY(${ids}::text[]) AND "archivedAt" IS NULL
+            ORDER BY id FOR UPDATE SKIP LOCKED
+          `;
+          // A separate READ COMMITTED statement sees deployments committed before
+          // these locks. No eligibility query is needed before acquiring the locks.
+          const activity = await previewBranchActivity(
+            tx,
+            locked.map(({ id }) => id)
+          );
+          eligible = locked.filter(
+            (branch) =>
+              classifyPreviewBranch(
+                branch,
+                activity.get(branch.id)!,
+                parent.previewAutoArchiveAfterDays,
+                excluded,
+                now
+              ).status === "ready"
+          );
+        }
+        const archived = await archiveBranchesMutation(tx, eligible, now);
+        const complete = scanned.length < PREVIEW_ARCHIVE_PAGE_SIZE;
+        const last = scanned[scanned.length - 1];
+        await tx.runtimeEnvironment.update({
+          where: { id: parent.id },
+          data: {
+            previewAutoArchiveNextCheckAt: complete ? new Date(now.getTime() + HOUR_MS) : now,
+            previewAutoArchiveCursorCreatedAt: complete ? null : last.createdAt,
+            previewAutoArchiveCursorId: complete ? null : last.id,
+          },
+        });
+        // #region @crumbs
+        crumb("preview archive page", {
+          parentId: parent.id,
+          scanned: scanned.length,
+          archived: archived.length,
+        });
+        // #endregion @crumbs
+        return {
+          parentId: parent.id,
+          scanned: scanned.length,
+          candidates: ids.length,
+          archived,
+          complete,
+        };
+      },
+      { isolationLevel: "ReadCommitted", timeout: 5_000, maxWait: 1_000 }
+    );
+    if (result)
+      logger.debug("Preview archive page completed", {
+        parentId: result.parentId,
+        scanned: result.scanned,
+        candidates: result.candidates,
+        archived: result.archived.length,
+        durationMs: performance.now() - started,
+      });
+    return result ?? null;
+  } catch (error) {
+    if (claimed) {
+      // The page (including archives and cursor) rolled back. Conditional backoff
+      // cannot overwrite a subsequent successful page or a user's policy change.
+      await $transaction(
+        prisma,
+        "backoffPreviewAutoArchive",
+        async (tx) => {
+          await tx.runtimeEnvironment.updateMany({
+            where: {
+              id: claimed!.id,
+              previewAutoArchiveNextCheckAt: claimed!.previewAutoArchiveNextCheckAt,
+              previewAutoArchiveCursorCreatedAt: claimed!.previewAutoArchiveCursorCreatedAt,
+              previewAutoArchiveCursorId: claimed!.previewAutoArchiveCursorId,
+            },
+            data: { previewAutoArchiveNextCheckAt: new Date(now.getTime() + RETRY_MS) },
+          });
+        },
+        { timeout: 5_000, maxWait: 1_000 }
+      );
+    }
+    throw error;
+  }
+}
+
+/** Every tick rediscovers due pages from Postgres. No Redis continuation can be
+ * lost between committing a page and scheduling the next one. */
+export async function sweepPreviewAutoArchives(
+  prisma: PrismaClient,
+  onArchived: (ids: string[]) => void
+) {
+  const started = performance.now();
+  let admitted = 0;
+  let pages = 0;
+  let scanned = 0;
+  let archived = 0;
+  let failures = 0;
+  await Promise.all(
+    Array.from({ length: PREVIEW_ARCHIVE_LANES }, async (_, lane) => {
+      while (admitted < MAX_PAGES_PER_TICK && performance.now() - started < TICK_BUDGET_MS) {
+        admitted++;
+        try {
+          const result = await processPreviewAutoArchivePage(prisma, lane);
+          if (!result) break;
+          pages++;
+          scanned += result.scanned;
+          archived += result.archived.length;
+          onArchived(result.archived.map(({ id }) => id));
+        } catch (error) {
+          failures++;
+          logger.error("Preview auto-archive page failed", { error });
+          // Don't spin on database acquisition failures; the next tick retries.
+          break;
+        }
+      }
+    })
+  );
+  const stats = { pages, scanned, archived, failures, durationMs: performance.now() - started };
+  if (pages || failures) logger.info("Preview auto-archive sweep", stats);
+  return stats;
+}
diff --git a/apps/webapp/app/utils/previewAutoArchive.ts b/apps/webapp/app/utils/previewAutoArchive.ts
new file mode 100644
index 00000000000..479dca6a746
--- /dev/null
+++ b/apps/webapp/app/utils/previewAutoArchive.ts
@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { isValidGitBranchName } from "@trigger.dev/core/v3/utils/gitBranch";
+
+export const PreviewAutoArchivePolicy = z.object({
+  days: z.number().int().min(1).max(365).nullable(),
+  excludedBranches: z
+    .array(z.string().max(255).refine(isValidGitBranchName, "Invalid branch name"))
+    .max(100)
+    .transform((names) => [...new Set(names)]),
+});
+
+export const PREVIEW_AUTO_ARCHIVE_DAY_MS = 24 * 60 * 60 * 1000;
+
+export type PreviewBranchActivity = { lastDeploymentAt: Date | null; inProgress: boolean };
+
+/** Shared policy for the branch list, settings preview, and locked cleanup page. */
+export function classifyPreviewBranch(
+  branch: { branchName: string | null; createdAt: Date },
+  activity: PreviewBranchActivity,
+  days: number,
+  excluded: ReadonlySet<string>,
+  now: Date
+) {
+  const archiveAt = new Date(
+    (activity.lastDeploymentAt ?? branch.createdAt).getTime() + days * PREVIEW_AUTO_ARCHIVE_DAY_MS
+  );
+  if (branch.branchName !== null && excluded.has(branch.branchName)) {
+    return { status: "protected" as const, archiveAt };
+  }
+  if (activity.inProgress) {
+    return { status: "inProgress" as const, archiveAt };
+  }
+  return { status: archiveAt <= now ? ("ready" as const) : ("scheduled" as const), archiveAt };
+}
diff --git a/apps/webapp/app/v3/commonWorker.server.ts b/apps/webapp/app/v3/commonWorker.server.ts
index 5736458b12d..f565ebdd3d7 100644
--- a/apps/webapp/app/v3/commonWorker.server.ts
+++ b/apps/webapp/app/v3/commonWorker.server.ts
@@ -28,6 +28,9 @@ import { PerformTaskRunAlertsService } from "./services/alerts/performTaskRunAle
 import { BatchTriggerV3Service } from "./services/batchTriggerV3.server";
 import { TimeoutDeploymentService } from "./services/timeoutDeployment.server";
 import { BulkActionService } from "./services/bulk/BulkActionV2.server";
+import { prisma } from "~/db.server";
+import { sweepPreviewAutoArchives } from "~/services/previewAutoArchive.server";
+import { controlPlaneResolver } from "./runOpsMigration/controlPlaneResolver.server";
 
 function initializeWorker() {
   const redisOptions = {
@@ -51,6 +54,13 @@ function initializeWorker() {
     name: "common-worker",
     redisOptions,
     catalog: {
+      "previewBranches.autoArchiveSweep": {
+        schema: CronSchema,
+        cron: "* * * * *",
+        jitterInMs: 10_000,
+        visibilityTimeoutMs: 60_000,
+        retry: { maxAttempts: 3 },
+      },
       scheduleEmail: {
         schema: DeliverEmailSchema,
         visibilityTimeoutMs: 60_000,
@@ -194,6 +204,11 @@ function initializeWorker() {
     shutdownTimeoutMs: env.COMMON_WORKER_SHUTDOWN_TIMEOUT_MS,
     logger: new Logger("CommonWorker", env.COMMON_WORKER_LOG_LEVEL),
     jobs: {
+      "previewBranches.autoArchiveSweep": async () => {
+        await sweepPreviewAutoArchives(prisma, (ids) => {
+          for (const id of ids) controlPlaneResolver.invalidateEnvironment(id);
+        });
+      },
       scheduleEmail: async ({ payload }) => {
         await sendEmail(payload);
       },
diff --git a/apps/webapp/app/v3/featureFlags.ts b/apps/webapp/app/v3/featureFlags.ts
index cee20ff990e..d6f3b553cb5 100644
--- a/apps/webapp/app/v3/featureFlags.ts
+++ b/apps/webapp/app/v3/featureFlags.ts
@@ -8,6 +8,7 @@ export const FEATURE_FLAG = {
   hasQueryAccess: "hasQueryAccess",
   hasLogsPageAccess: "hasLogsPageAccess",
   hasWebhooksAccess: "hasWebhooksAccess",
+  previewAutoArchiveEnabled: "previewAutoArchiveEnabled",
   hasAiAccess: "hasAiAccess",
   hasDashboardAgentAccess: "hasDashboardAgentAccess",
   dashboardAgentTurnEvalsEnabled: "dashboardAgentTurnEvalsEnabled",
@@ -56,6 +57,8 @@ export const FeatureFlagCatalog = {
   [FEATURE_FLAG.hasQueryAccess]: z.coerce.boolean(),
   [FEATURE_FLAG.hasLogsPageAccess]: z.coerce.boolean(),
   [FEATURE_FLAG.hasWebhooksAccess]: z.coerce.boolean(),
+  // Opt-in rollout; organization overrides the global default. Unset means off.
+  [FEATURE_FLAG.previewAutoArchiveEnabled]: z.boolean(),
   [FEATURE_FLAG.hasAiAccess]: z.coerce.boolean(),
   // Gates the in-dashboard AI agent panel. Controllable globally and per-org
   // (org wins). Defaults off via DASHBOARD_AGENT_ENABLED.
diff --git a/apps/webapp/app/v3/services/initializeDeployment.server.ts b/apps/webapp/app/v3/services/initializeDeployment.server.ts
index ca7ce966006..e3d655dcbc8 100644
--- a/apps/webapp/app/v3/services/initializeDeployment.server.ts
+++ b/apps/webapp/app/v3/services/initializeDeployment.server.ts
@@ -392,6 +392,11 @@ export class InitializeDeploymentService extends BaseService {
             triggeredVia: payload.triggeredVia ?? undefined,
             startedAt: initialStatus === "BUILDING" ? new Date() : undefined,
           };
+        },
+        {
+          archiveGuard: {
+            type: environment.type,
+          },
         }
       );
 
diff --git a/apps/webapp/app/v3/services/initializeDeployment/createDeploymentWithNextVersion.server.ts b/apps/webapp/app/v3/services/initializeDeployment/createDeploymentWithNextVersion.server.ts
index 0a7e54c2947..3ee84250310 100644
--- a/apps/webapp/app/v3/services/initializeDeployment/createDeploymentWithNextVersion.server.ts
+++ b/apps/webapp/app/v3/services/initializeDeployment/createDeploymentWithNextVersion.server.ts
@@ -3,9 +3,12 @@ import {
   type Prisma,
   type PrismaClientOrTransaction,
   type WorkerDeployment,
+  type RuntimeEnvironmentType,
 } from "@trigger.dev/database";
 import { setTimeout as sleep } from "node:timers/promises";
 import { logger } from "~/services/logger.server";
+import { $transaction } from "~/db.server";
+import { ServiceValidationError } from "../common.server";
 import { calculateNextBuildVersion } from "../../utils/calculateNextBuildVersion";
 
 export type CreateDeploymentData = Omit<
@@ -16,6 +19,7 @@ export type CreateDeploymentData = Omit<
 export type CreateDeploymentWithNextVersionOptions = {
   maxRetries?: number;
   jitterMs?: { min: number; max: number };
+  archiveGuard?: { type: RuntimeEnvironmentType };
 };
 
 const DEFAULT_MAX_RETRIES = 5;
@@ -67,9 +71,36 @@ export async function createDeploymentWithNextVersion(
     const data = await buildData(version);
 
     try {
-      return await prisma.workerDeployment.create({
-        data: { ...data, environmentId, version },
-      });
+      // Non-preview deployments keep the original query path, including no flag lookup.
+      if (options.archiveGuard?.type !== "PREVIEW") {
+        return await prisma.workerDeployment.create({ data: { ...data, environmentId, version } });
+      }
+      // All previews lock, even with rollout disabled: flags can change during preparation.
+      // Build data (including registry calls) above, outside the short lock. The archive
+      // sweep takes this same lock before checking deployment activity.
+      const deployment = await $transaction(
+        prisma,
+        "createDeploymentWithBranchLock",
+        async (tx) => {
+          // Prisma reads cannot request FOR UPDATE. Hold the same environment row lock
+          // as archiving until the deployment is inserted, so checking archivedAt and
+          // creating a deployment cannot race with an archive. Wait for any current owner
+          // here: unlike cleanup, a deployment must inspect the result rather than skip it.
+          const environments = await tx.$queryRaw<Array<{ archivedAt: Date | null }>>`
+          SELECT "archivedAt" FROM "RuntimeEnvironment" WHERE id = ${environmentId} FOR UPDATE
+        `;
+          if (!environments.length || environments[0].archivedAt) {
+            throw new ServiceValidationError(
+              "This branch has been archived. Deploy again to create a fresh preview branch.",
+              409
+            );
+          }
+          return tx.workerDeployment.create({ data: { ...data, environmentId, version } });
+        },
+        { isolationLevel: "ReadCommitted", timeout: 5_000, maxWait: 1_000 }
+      );
+      if (!deployment) throw new Error("Failed to create deployment");
+      return deployment;
     } catch (error) {
       if (!isUniqueConstraintError(error, ["environmentId", "version"])) {
         throw error;
diff --git a/apps/webapp/test/createDeploymentWithNextVersion.test.ts b/apps/webapp/test/createDeploymentWithNextVersion.test.ts
index feb8d1c4006..5237c48a35c 100644
--- a/apps/webapp/test/createDeploymentWithNextVersion.test.ts
+++ b/apps/webapp/test/createDeploymentWithNextVersion.test.ts
@@ -39,6 +39,38 @@ async function seedEnvironment(prisma: PrismaClient) {
 }
 
 describe("createDeploymentWithNextVersion", () => {
+  containerTest("non-preview deployments use only the original queries", async ({ prisma }) => {
+    const { project, environment } = await seedEnvironment(prisma);
+    const operations: string[] = [];
+    const observed = prisma.$extends({
+      query: {
+        $allOperations: async ({ model, operation, args, query }) => {
+          operations.push(`${model ?? "raw"}.${operation}`);
+          return query(args);
+        },
+      },
+    });
+    for (const type of ["PRODUCTION", "STAGING", "DEVELOPMENT"] as const) {
+      operations.length = 0;
+      await createDeploymentWithNextVersion(
+        observed as unknown as PrismaClient,
+        environment.id,
+        () => ({
+          projectId: project.id,
+          friendlyId: `dark_${type}_${environment.id}`,
+          shortCode: `dark_${type}`,
+          contentHash: "dark",
+        }),
+        {
+          archiveGuard: {
+            type,
+          },
+        }
+      );
+      expect(operations).toEqual(["WorkerDeployment.findFirst", "WorkerDeployment.create"]);
+    }
+  });
+
   containerTest(
     "assigns unique sequential versions for concurrent calls in the same environment",
     async ({ prisma }) => {
diff --git a/apps/webapp/test/fixtures/previewAutoArchive.ts b/apps/webapp/test/fixtures/previewAutoArchive.ts
new file mode 100644
index 00000000000..d9f0a26319b
--- /dev/null
+++ b/apps/webapp/test/fixtures/previewAutoArchive.ts
@@ -0,0 +1,66 @@
+import { type PrismaClient, type WorkerDeploymentStatus } from "@trigger.dev/database";
+import { createTestOrgProjectWithMember, uniqueId } from "./environmentVariablesFixtures";
+export const archiveTestNow = new Date("2026-09-16T12:00:00Z");
+export const archiveTestOld = new Date(archiveTestNow.getTime() - 20 * 24 * 60 * 60 * 1000);
+const now = archiveTestNow;
+const old = archiveTestOld;
+export async function seedPreviewArchive(prisma: PrismaClient, rolloutEnabled = true) {
+  const { project, organization } = await createTestOrgProjectWithMember(prisma);
+  if (rolloutEnabled) {
+    await prisma.organization.update({
+      where: { id: organization.id },
+      data: { featureFlags: { previewAutoArchiveEnabled: true } },
+    });
+  }
+  const base = { projectId: project.id, organizationId: organization.id, type: "PREVIEW" as const };
+  const parent = await prisma.runtimeEnvironment.create({
+    data: {
+      ...base,
+      slug: "preview",
+      shortcode: "preview",
+      apiKey: uniqueId("api"),
+      pkApiKey: uniqueId("pk"),
+      isBranchableEnvironment: true,
+      previewAutoArchiveAfterDays: 14,
+      previewAutoArchiveNextCheckAt: now,
+      previewAutoArchiveExcludedBranches: ["staging"],
+    },
+  });
+  const branch = async (name = uniqueId("branch"), createdAt = old) =>
+    prisma.runtimeEnvironment.create({
+      data: {
+        ...base,
+        slug: `preview-${name}`,
+        shortcode: `preview-${name}`,
+        apiKey: uniqueId("api"),
+        pkApiKey: uniqueId("pk"),
+        branchName: name,
+        parentEnvironmentId: parent.id,
+        createdAt,
+      },
+    });
+  const deployment = async (
+    environmentId: string,
+    createdAt: Date,
+    status: WorkerDeploymentStatus = "DEPLOYED"
+  ) =>
+    prisma.workerDeployment.create({
+      data: {
+        environmentId,
+        projectId: project.id,
+        createdAt,
+        status,
+        version: uniqueId("version"),
+        friendlyId: uniqueId("deployment"),
+        shortCode: uniqueId("short"),
+        contentHash: "hash",
+      },
+    });
+  const deployData = () => ({
+    projectId: project.id,
+    friendlyId: uniqueId("deployment"),
+    shortCode: uniqueId("short"),
+    contentHash: "hash",
+  });
+  return { parent, branch, deployment, deployData, project, organization };
+}
diff --git a/apps/webapp/vitest.config.ts b/apps/webapp/vitest.config.ts
index 356f5b3c16b..6821b3ff494 100644
--- a/apps/webapp/vitest.config.ts
+++ b/apps/webapp/vitest.config.ts
@@ -19,6 +19,7 @@ export default defineConfig({
       "app/runEngine/concerns/**/*.test.ts",
       "app/runEngine/services/**/*.test.ts",
       "app/services/realtime/**/*.test.ts",
+      "app/services/previewAutoArchive.server.test.ts",
       "app/services/clickhouse/**/*.test.ts",
       "app/utils/**/*.test.ts",
       "app/hooks/**/*.test.ts",
diff --git a/internal-packages/database/prisma/migrations/20260916120000_preview_auto_archive/migration.sql b/internal-packages/database/prisma/migrations/20260916120000_preview_auto_archive/migration.sql
new file mode 100644
index 00000000000..2d43e2cf2e8
--- /dev/null
+++ b/internal-packages/database/prisma/migrations/20260916120000_preview_auto_archive/migration.sql
@@ -0,0 +1,8 @@
+-- Add policy and durable sweep progress together. IF NOT EXISTS supports pre-applying
+-- this exact DDL before deployment; existing column definitions are verified manually.
+ALTER TABLE "RuntimeEnvironment"
+ADD COLUMN IF NOT EXISTS "previewAutoArchiveAfterDays" INTEGER,
+ADD COLUMN IF NOT EXISTS "previewAutoArchiveExcludedBranches" TEXT[] NOT NULL DEFAULT ARRAY[]::TEXT[],
+ADD COLUMN IF NOT EXISTS "previewAutoArchiveNextCheckAt" TIMESTAMP(3),
+ADD COLUMN IF NOT EXISTS "previewAutoArchiveCursorCreatedAt" TIMESTAMP(3),
+ADD COLUMN IF NOT EXISTS "previewAutoArchiveCursorId" TEXT;
diff --git a/internal-packages/database/prisma/migrations/20260916130001_preview_archive_due_index/migration.sql b/internal-packages/database/prisma/migrations/20260916130001_preview_archive_due_index/migration.sql
new file mode 100644
index 00000000000..524ee9c01ee
--- /dev/null
+++ b/internal-packages/database/prisma/migrations/20260916130001_preview_archive_due_index/migration.sql
@@ -0,0 +1,8 @@
+-- Match the due-policy filter and ordering so cleanup starts with scheduled preview roots.
+-- Prisma cannot declare this partial predicate or a concurrent build. CONCURRENTLY keeps
+-- normal writes available; IF NOT EXISTS permits manual pre-creation. Keep one statement.
+CREATE INDEX CONCURRENTLY IF NOT EXISTS "RuntimeEnvironment_preview_archive_due_idx"
+ON "RuntimeEnvironment" ("previewAutoArchiveNextCheckAt", "id")
+WHERE "type" = 'PREVIEW' AND "parentEnvironmentId" IS NULL
+AND "isBranchableEnvironment" = true AND "archivedAt" IS NULL
+AND "previewAutoArchiveAfterDays" IS NOT NULL AND "previewAutoArchiveNextCheckAt" IS NOT NULL;
diff --git a/internal-packages/database/prisma/migrations/20260916130002_preview_archive_branch_index/migration.sql b/internal-packages/database/prisma/migrations/20260916130002_preview_archive_branch_index/migration.sql
new file mode 100644
index 00000000000..154a0862b18
--- /dev/null
+++ b/internal-packages/database/prisma/migrations/20260916130002_preview_archive_branch_index/migration.sql
@@ -0,0 +1,7 @@
+-- Support per-parent (createdAt, id) cursor seeks over active preview branches.
+-- Prisma cannot declare this partial predicate or a concurrent build. CONCURRENTLY keeps
+-- normal writes available; IF NOT EXISTS permits manual pre-creation. Keep one statement.
+CREATE INDEX CONCURRENTLY IF NOT EXISTS "RuntimeEnvironment_preview_archive_scan_idx"
+ON "RuntimeEnvironment" ("parentEnvironmentId", "createdAt", "id")
+WHERE "type" = 'PREVIEW' AND "archivedAt" IS NULL
+AND "parentEnvironmentId" IS NOT NULL AND "branchName" IS NOT NULL;
diff --git a/internal-packages/database/prisma/schema.prisma b/internal-packages/database/prisma/schema.prisma
index 06b83bfa803..c6f846fa4bd 100644
--- a/internal-packages/database/prisma/schema.prisma
+++ b/internal-packages/database/prisma/schema.prisma
@@ -336,6 +336,14 @@ model RuntimeEnvironment {
   parentEnvironmentId     String?
   childEnvironments       RuntimeEnvironment[] @relation("parentEnvironment")
 
+  /// Only configured on the PREVIEW root. Null disables automatic archiving.
+  previewAutoArchiveAfterDays        Int?
+  previewAutoArchiveExcludedBranches String[]  @default([])
+  /// Durable per-project cleanup progress. Null next-check disables scheduling.
+  previewAutoArchiveNextCheckAt      DateTime?
+  previewAutoArchiveCursorCreatedAt  DateTime?
+  previewAutoArchiveCursorId         String?
+
   // This is GitMeta type
   git Json?
 

From 230b5b0e2b66fd0c663000da80bf85cf9c425a3f Mon Sep 17 00:00:00 2001
From: Matt Aitken <matt@mattaitken.com>
Date: Thu, 17 Sep 2026 13:59:25 +0000
Subject: [PATCH 5/6] perf(webapp): subscribe socket.io namespaces lazily on
 first connection

Each server process opened Redis pub/sub subscriptions for every
socket.io namespace at startup, including namespaces it would never
serve a connection on. Every broadcast was therefore delivered to every
process, and all but the few holding a relevant connection discarded it.

Subscriptions are now opened per namespace the first time that process
serves a connection on it, which keeps broadcast fan-out to the
processes that can act on it. Behaviour is unchanged for a single
process deployment, where the first worker or dev worker connection
opens the same subscriptions as before.

Mono-RevId: c14a7b60cd4303f463a24c6e044b4d48cc25e981
---
 apps/webapp/app/v3/handleSocketIo.server.ts   |  68 +-
 .../app/v3/lazySocketIoAdapter.server.ts      | 260 ++++++
 apps/webapp/package.json                      |   1 +
 .../test/lazySocketIoAdapter.failover.test.ts | 343 ++++++++
 apps/webapp/test/lazySocketIoAdapter.test.ts  | 801 ++++++++++++++++++
 pnpm-lock.yaml                                |   3 +
 6 files changed, 1468 insertions(+), 8 deletions(-)
 create mode 100644 apps/webapp/app/v3/lazySocketIoAdapter.server.ts
 create mode 100644 apps/webapp/test/lazySocketIoAdapter.failover.test.ts
 create mode 100644 apps/webapp/test/lazySocketIoAdapter.test.ts

diff --git a/apps/webapp/app/v3/handleSocketIo.server.ts b/apps/webapp/app/v3/handleSocketIo.server.ts
index 1046c432a52..a3e03643f41 100644
--- a/apps/webapp/app/v3/handleSocketIo.server.ts
+++ b/apps/webapp/app/v3/handleSocketIo.server.ts
@@ -1,5 +1,4 @@
 import type { EventBusEventArgs } from "@internal/run-engine";
-import { createAdapter } from "@socket.io/redis-adapter";
 import { RunId } from "@trigger.dev/core/v3/isomorphic";
 import type {
   WorkerClientToServerEvents,
@@ -13,6 +12,11 @@ import { env } from "~/env.server";
 import { authenticateApiRequestWithFailure } from "~/services/apiAuth.server";
 import { logger } from "~/services/logger.server";
 import { singleton } from "~/utils/singleton";
+import {
+  createLazySocketIoAdapter,
+  withTimeout,
+  type LazySocketIoAdapter,
+} from "./lazySocketIoAdapter.server";
 import { recordRunDebugLog } from "./eventRepository/index.server";
 import { engine } from "./runEngine.server";
 import { WorkerGroupTokenService } from "./services/worker/workerGroupTokenService.server";
@@ -20,7 +24,11 @@ import { WorkerGroupTokenService } from "./services/worker/workerGroupTokenServi
 export const socketIo = singleton("socketIo", initalizeIoServer);
 
 function initalizeIoServer() {
-  const io = initializeSocketIOServerInstance();
+  const { io, lazyAdapter } = initializeSocketIOServerInstance();
+
+  if (lazyAdapter) {
+    io.use(activateNamespaceMiddleware(lazyAdapter, "/"));
+  }
 
   io.on("connection", (socket) => {
     logger.log(`[socket.io][${socket.id}] connection at url: ${socket.request.url}`);
@@ -28,6 +36,7 @@ function initalizeIoServer() {
 
   const workerNamespace = createWorkerNamespace({
     io,
+    lazyAdapter,
     namespace: "/worker",
     authenticate: async (request) => {
       const tokenService = new WorkerGroupTokenService();
@@ -40,6 +49,7 @@ function initalizeIoServer() {
   });
   const devWorkerNamespace = createWorkerNamespace({
     io,
+    lazyAdapter,
     namespace: "/dev-worker",
     authenticate: async (request) => {
       const authentication = await authenticateApiRequestWithFailure(request);
@@ -73,17 +83,19 @@ function initializeSocketIOServerInstance() {
     });
     const subClient = pubClient.duplicate();
 
+    const lazyAdapter = createLazySocketIoAdapter(pubClient, subClient, {
+      key: "tr:socket.io:",
+      publishOnSpecificResponseChannel: true,
+    });
+
     const io = new Server({
-      adapter: createAdapter(pubClient, subClient, {
-        key: "tr:socket.io:",
-        publishOnSpecificResponseChannel: true,
-      }),
+      adapter: lazyAdapter.adapter,
     });
 
-    return io;
+    return { io, lazyAdapter };
   }
 
-  return new Server();
+  return { io: new Server(), lazyAdapter: undefined };
 }
 
 function headersFromHandshake(handshake: Socket["handshake"]) {
@@ -97,12 +109,48 @@ function headersFromHandshake(handshake: Socket["handshake"]) {
   return headers;
 }
 
+/**
+ * Bounds how long a handshake waits for the Redis subscriptions to land. The
+ * Redis client's own offline queue and retry budget would otherwise hold the
+ * handshake open for an unpredictable stretch during a Redis blip.
+ */
+const NAMESPACE_ACTIVATION_TIMEOUT_MS = 5_000;
+
+/**
+ * Opens the namespace's Redis subscriptions before the handshake completes, so
+ * a socket cannot join a room while this process is still unsubscribed. A
+ * failure or timeout rejects the connection rather than accepting one that
+ * would silently miss notifications; the client reconnects and the run's
+ * snapshot poll covers the gap. The activation itself keeps going, so a slow
+ * one still benefits the next connection.
+ */
+function activateNamespaceMiddleware(lazyAdapter: LazySocketIoAdapter, namespace: string) {
+  return async (_socket: Socket, next: (err?: Error) => void) => {
+    try {
+      await withTimeout(
+        lazyAdapter.activate(namespace),
+        NAMESPACE_ACTIVATION_TIMEOUT_MS,
+        `socket.io namespace ${namespace} did not subscribe within ${NAMESPACE_ACTIVATION_TIMEOUT_MS}ms`
+      );
+      next();
+    } catch (error) {
+      logger.error("Failed to open socket.io Redis subscriptions", {
+        namespace,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      next(error instanceof Error ? error : new Error("socket.io subscribe failed"));
+    }
+  };
+}
+
 function createWorkerNamespace({
   io,
+  lazyAdapter,
   namespace,
   authenticate,
 }: {
   io: Server;
+  lazyAdapter: LazySocketIoAdapter | undefined;
   namespace: string;
   authenticate: (request: Request) => Promise<boolean>;
 }) {
@@ -142,6 +190,10 @@ function createWorkerNamespace({
     }
   });
 
+  if (lazyAdapter) {
+    worker.use(activateNamespaceMiddleware(lazyAdapter, namespace));
+  }
+
   worker.on("connection", async (socket) => {
     logger.debug("worker connected", { namespace, socketId: socket.id });
 
diff --git a/apps/webapp/app/v3/lazySocketIoAdapter.server.ts b/apps/webapp/app/v3/lazySocketIoAdapter.server.ts
new file mode 100644
index 00000000000..96c6d2d530e
--- /dev/null
+++ b/apps/webapp/app/v3/lazySocketIoAdapter.server.ts
@@ -0,0 +1,260 @@
+import { createAdapter } from "@socket.io/redis-adapter";
+import type { Redis } from "ioredis";
+import type { Namespace } from "socket.io";
+import type { Adapter } from "socket.io-adapter";
+
+type AdapterFactory = (nsp: Namespace) => Adapter;
+type CreateAdapterOptions = Parameters<typeof createAdapter>[2];
+
+export type LazySocketIoAdapter = {
+  /** Pass as the socket.io `Server`'s `adapter` option. */
+  adapter: AdapterFactory;
+  /**
+   * Opens this namespace's Redis subscriptions. Await it before a socket can
+   * join a room, so a broadcast can never arrive at an unsubscribed process.
+   * Idempotent, and safe to call concurrently. A failed attempt is retried on
+   * the next call rather than being cached.
+   */
+  activate: (namespaceName: string) => Promise<void>;
+  /** True once {@link activate} has been called for the namespace's current adapter. */
+  isActivated: (namespaceName: string) => boolean;
+  activatedNamespaces: () => string[];
+};
+
+/**
+ * Activation state for one adapter instance. Completion handlers close over
+ * this object rather than a namespace-keyed map, so an activation started by
+ * an adapter that has since been replaced can only ever mutate its own,
+ * orphaned state and never the replacement's.
+ */
+type NamespaceState = {
+  queue: Array<() => unknown>;
+  activation: Promise<void> | undefined;
+  ready: boolean;
+};
+
+/**
+ * `subClient` calls the adapter makes at construction time that we hold back.
+ * Everything else, including the `pmessageBuffer` / `messageBuffer` listener
+ * registration, still runs eagerly so no message can be dropped in the gap
+ * between subscribing and the handler being attached.
+ */
+const DEFERRED_METHODS = new Set(["subscribe", "psubscribe"]);
+
+const isLocalOnly = (opts: unknown) =>
+  Boolean((opts as { flags?: { local?: boolean } } | undefined)?.flags?.local);
+
+/**
+ * Adapter operations that publish a request and then wait on replies, keyed
+ * to a predicate over the call's arguments saying whether this particular call
+ * does. Each one sizes its wait from `serverCount()`, which is `NUMSUB` on the
+ * request channel, and assumes the caller is one of those subscribers. An
+ * unsubscribed caller would undercount peers (`fetchSockets` on a single
+ * active peer sees `numSub === 1` and silently returns only local results) and
+ * could not receive replies anyway, having no response-channel subscription.
+ * So a call that needs replies activates first, trading a subscription for a
+ * correct answer, while a call that cannot need one (`flags.local`) runs as
+ * stock and leaves an idle process idle.
+ *
+ * Not listed: `serverSideEmit` without an ack publishes with no `requestId`,
+ * so peers never reply, and with an ack it delegates to the wrapped
+ * `serverSideEmitWithAck`. `serverCount` gets its own wrapper below, since it
+ * must keep counting the caller without being made to subscribe.
+ */
+export const RESPONSE_DEPENDENT_METHODS: Readonly<
+  Record<string, (args: readonly unknown[]) => boolean>
+> = {
+  fetchSockets: ([opts]) => !isLocalOnly(opts),
+  allRooms: () => true,
+  serverSideEmitWithAck: () => true,
+  broadcastWithAck: ([, opts]) => !isLocalOnly(opts),
+};
+
+/**
+ * Rejects if `promise` has not settled within `ms`. The underlying work keeps
+ * running, so a slow activation still completes and benefits the next caller;
+ * only this caller stops waiting.
+ */
+export function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
+
+/**
+ * Wraps `@socket.io/redis-adapter` so a process only subscribes to a
+ * namespace's Redis channels once it actually serves a connection on that
+ * namespace, or issues an adapter operation that needs replies.
+ *
+ * Fan-out is O(subscribing processes), so a process holding no sockets for a
+ * namespace costs every publisher a delivery it will only discard. Deferring
+ * the subscription keeps each namespace's fan-out to the processes that can
+ * act on it, with no deployment-time configuration to keep in sync.
+ */
+export function createLazySocketIoAdapter(
+  pubClient: Redis,
+  subClient: Redis,
+  opts: CreateAdapterOptions
+): LazySocketIoAdapter {
+  /** The current adapter's state per namespace name; replaced wholesale on reconstruction. */
+  const states = new Map<string, NamespaceState>();
+
+  async function flush(state: NamespaceState) {
+    if (state.queue.length === 0) {
+      return;
+    }
+
+    /** Left in place until every call lands, so a failure retries the whole set. */
+    for (const call of state.queue) {
+      await call();
+    }
+
+    state.queue.length = 0;
+  }
+
+  function activateState(state: NamespaceState): Promise<void> {
+    if (state.activation) {
+      return state.activation;
+    }
+
+    const activation = flush(state).then(
+      () => {
+        state.ready = true;
+      },
+      (error) => {
+        state.activation = undefined;
+        throw error;
+      }
+    );
+
+    state.activation = activation;
+
+    return activation;
+  }
+
+  function activate(namespaceName: string): Promise<void> {
+    const state = states.get(namespaceName);
+
+    return state ? activateState(state) : Promise.resolve();
+  }
+
+  /**
+   * socket.io instantiates the adapter with `new`, so this has to be a
+   * constructable function. An arrow function throws "not a constructor".
+   */
+  const adapter = function (nsp: Namespace) {
+    /**
+     * A fresh state object per construction. A namespace rebuilt under the
+     * same name gets its own queue and readiness, and any activation the
+     * previous adapter still has in flight settles into that previous object,
+     * which nothing consults any more.
+     */
+    const state: NamespaceState = { queue: [], activation: undefined, ready: false };
+    states.set(nsp.name, state);
+
+    const deferredSubClient = new Proxy(subClient, {
+      get(target, prop) {
+        if (typeof prop === "string" && DEFERRED_METHODS.has(prop)) {
+          return (...args: unknown[]) => {
+            state.queue.push(() => (target as unknown as Record<string, Function>)[prop](...args));
+            return Promise.resolve(0);
+          };
+        }
+
+        const value = Reflect.get(target, prop, target);
+        return typeof value === "function" ? value.bind(target) : value;
+      },
+    });
+
+    const instance = createAdapter(pubClient, deferredSubClient as Redis, opts)(nsp);
+    const methods = instance as unknown as Record<string, unknown>;
+
+    /**
+     * The stock adapter's `serverCount()` always includes the caller, because
+     * the caller is always subscribed to the request channel that `NUMSUB`
+     * counts. A cold lazy adapter is not, so it adds itself back rather than
+     * subscribing just to be counted. Mid-activation, wait for the
+     * subscription to land so `NUMSUB` is exact instead of guessing which side
+     * of it we are on. Once ready, `NUMSUB` already counts this process.
+     *
+     * The cold decision is re-checked after the count resolves. The
+     * subscription travels on `subClient` and `NUMSUB` on `pubClient`, and
+     * Redis orders nothing across connections, so an activation that starts
+     * during the read can reach Redis before `NUMSUB` executes and the result
+     * would already include this process. Recounting after that activation
+     * settles is exact; the extra one is added only when the state stayed cold
+     * for the whole read. A rejected activation leaves this process
+     * unsubscribed, so it counts as cold.
+     */
+    const stockServerCount = methods.serverCount;
+
+    if (typeof stockServerCount === "function") {
+      const count = () =>
+        Promise.resolve((stockServerCount as () => unknown).apply(instance, [])).then(Number);
+
+      const countOnceSubscribed = (activation: Promise<void>) =>
+        activation.then(count, () => count().then((peers) => peers + 1));
+
+      methods.serverCount = () => {
+        if (state.ready) {
+          return count();
+        }
+
+        if (state.activation) {
+          return countOnceSubscribed(state.activation);
+        }
+
+        return count().then((peers) =>
+          state.activation ? countOnceSubscribed(state.activation) : peers + 1
+        );
+      };
+    }
+
+    for (const [method, needsReplies] of Object.entries(RESPONSE_DEPENDENT_METHODS)) {
+      const original = methods[method];
+
+      if (typeof original !== "function") {
+        continue;
+      }
+
+      const call = original as (...a: unknown[]) => unknown;
+
+      /**
+       * A call that cannot need replies, or one on an already subscribed
+       * namespace, delegates synchronously so the sync-returning
+       * `broadcastWithAck` keeps its ordering relative to a plain `broadcast`.
+       * Only the first reply-needing call pays the async activation. Readiness
+       * is this instance's own, never a namesake's.
+       */
+      methods[method] = (...args: unknown[]) => {
+        if (!needsReplies(args) || state.ready) {
+          return call.apply(instance, args);
+        }
+
+        return activateState(state).then(() => call.apply(instance, args));
+      };
+    }
+
+    return instance;
+  } as unknown as AdapterFactory;
+
+  return {
+    adapter,
+    activate,
+    isActivated: (namespaceName) => Boolean(states.get(namespaceName)?.activation),
+    activatedNamespaces: () =>
+      Array.from(states.entries())
+        .filter(([, state]) => Boolean(state.activation))
+        .map(([name]) => name),
+  };
+}
diff --git a/apps/webapp/package.json b/apps/webapp/package.json
index fc56b2110d5..75e1042a211 100644
--- a/apps/webapp/package.json
+++ b/apps/webapp/package.json
@@ -255,6 +255,7 @@
     "esbuild": "^0.15.10",
     "evalite": "1.0.0-beta.16",
     "jsdom": "^30.0.1",
+    "socket.io-client": "4.7.5",
     "supertest": "^7.0.0",
     "tailwind-scrollbar": "^4.0.2",
     "tsx": "^4.20.6",
diff --git a/apps/webapp/test/lazySocketIoAdapter.failover.test.ts b/apps/webapp/test/lazySocketIoAdapter.failover.test.ts
new file mode 100644
index 00000000000..9a3b7af6091
--- /dev/null
+++ b/apps/webapp/test/lazySocketIoAdapter.failover.test.ts
@@ -0,0 +1,343 @@
+import { isolatedRedisTest } from "@internal/testcontainers";
+import type { StartedRedisContainer } from "@internal/testcontainers";
+import { defaultReconnectOnError } from "@internal/redis";
+import { createAdapter } from "@socket.io/redis-adapter";
+import { Redis, type RedisOptions } from "ioredis";
+import { createServer, type Server as HttpServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { io as ioClient, type Socket as ClientSocket } from "socket.io-client";
+import { Server } from "socket.io";
+import { describe, expect, vi } from "vitest";
+import { createLazySocketIoAdapter, withTimeout } from "~/v3/lazySocketIoAdapter.server";
+
+vi.setConfig({ testTimeout: 90_000 });
+
+const KEY = "tr:socket.io:";
+const ADAPTER_OPTS = { key: KEY, publishOnSpecificResponseChannel: true } as const;
+const REQUEST_CHANNEL = `${KEY}-request#/worker#`;
+const ROOM = "room:run_failover";
+/** Mirrors the webapp's connection middleware bound. */
+const ACTIVATION_TIMEOUT_MS = 5_000;
+
+type Mode = "lazy" | "eager";
+type Cleanup = () => Promise<void> | void;
+
+function tracker() {
+  const cleanups: Cleanup[] = [];
+  let done = false;
+  return {
+    add: (fn: Cleanup) => cleanups.push(fn),
+    async run() {
+      if (done) return;
+      done = true;
+      for (const fn of cleanups.reverse()) await fn();
+    },
+  };
+}
+
+/**
+ * The production socket.io Redis client, minus TLS and auth: auto-pipelining,
+ * the shared reconnectOnError, and ioredis defaults for everything that governs
+ * recovery (autoResubscribe, autoResendUnfulfilledCommands, retryStrategy,
+ * maxRetriesPerRequest). Built from host/port directly so no fixture wrapping
+ * changes its connection behaviour.
+ */
+function prodShapedOptions(
+  container: StartedRedisContainer,
+  extra: RedisOptions = {}
+): RedisOptions {
+  return {
+    host: container.getHost(),
+    port: container.getPort(),
+    password: container.getPassword() || undefined,
+    enableAutoPipelining: true,
+    reconnectOnError: defaultReconnectOnError,
+    ...extra,
+  };
+}
+
+function client(
+  container: StartedRedisContainer,
+  cleanup: ReturnType<typeof tracker>,
+  extra: RedisOptions = {}
+) {
+  const c = new Redis(prodShapedOptions(container, extra));
+  c.on("error", () => {});
+  cleanup.add(async () => {
+    await c.quit().catch(() => {});
+  });
+  return c;
+}
+
+async function numsub(control: Redis): Promise<number> {
+  const res = (await control.pubsub("NUMSUB", REQUEST_CHANNEL)) as [string, number];
+  return Number(res[1]);
+}
+
+/**
+ * A node replacement as the client experiences it behind a stable endpoint:
+ * every connection dropped and server state gone, at the same address.
+ * Not `redisContainer.restart()`: docker remaps the host port on restart, so
+ * clients would retry a dead port, which is the opposite of production's
+ * stable DNS name and tests nothing about recovery.
+ */
+async function nodeSwap(control: Redis) {
+  await control.flushall();
+  await control.call("CLIENT", "KILL", "TYPE", "pubsub", "SKIPME", "yes");
+  await control.call("CLIENT", "KILL", "TYPE", "normal", "SKIPME", "yes");
+}
+
+async function waitFor(check: () => Promise<boolean>, message: string, timeoutMs = 20_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await check().catch(() => false)) return;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  throw new Error(`Timed out waiting for: ${message}`);
+}
+
+async function startServer(
+  mode: Mode,
+  container: StartedRedisContainer,
+  cleanup: ReturnType<typeof tracker>
+) {
+  const pubClient = new Redis(prodShapedOptions(container));
+  const subClient = pubClient.duplicate();
+  pubClient.on("error", () => {});
+  subClient.on("error", () => {});
+
+  const lazy =
+    mode === "lazy"
+      ? createLazySocketIoAdapter(pubClient, subClient, { ...ADAPTER_OPTS })
+      : undefined;
+  const io = new Server({
+    adapter: lazy ? lazy.adapter : createAdapter(pubClient, subClient, { ...ADAPTER_OPTS }),
+  });
+
+  const nsp = io.of("/worker");
+  if (lazy) {
+    nsp.use(async (_socket, next) => {
+      try {
+        await withTimeout(lazy.activate("/worker"), ACTIVATION_TIMEOUT_MS, "activation timed out");
+        next();
+      } catch (error) {
+        next(error instanceof Error ? error : new Error("activation failed"));
+      }
+    });
+  }
+  nsp.on("connection", (socket) => {
+    socket.on("join", (room: string, ack: () => void) => {
+      socket.join(room);
+      ack();
+    });
+  });
+
+  const httpServer: HttpServer = createServer();
+  io.attach(httpServer);
+  await new Promise<void>((resolve) => httpServer.listen(0, resolve));
+  const url = `http://localhost:${(httpServer.address() as AddressInfo).port}`;
+
+  cleanup.add(async () => {
+    await io.close();
+    await new Promise<void>((resolve) => httpServer.close(() => resolve()));
+    await new Promise((r) => setImmediate(r));
+    await subClient.quit().catch(() => {});
+    await pubClient.ping().catch(() => {});
+    await pubClient.quit().catch(() => {});
+  });
+
+  return { io, nsp, lazy, url, pubClient, subClient };
+}
+
+async function connectAndJoin(
+  url: string,
+  cleanup: ReturnType<typeof tracker>
+): Promise<ClientSocket> {
+  const socket = ioClient(`${url}/worker`, { transports: ["websocket"] });
+  cleanup.add(() => {
+    socket.disconnect();
+  });
+  await new Promise<void>((resolve, reject) => {
+    socket.once("connect", () => resolve());
+    socket.once("connect_error", reject);
+  });
+  await new Promise<void>((resolve) => socket.emit("join", ROOM, resolve));
+  return socket;
+}
+
+function expectDelivery(
+  socket: ClientSocket,
+  publisher: Server,
+  payload: string,
+  timeoutMs = 10_000
+) {
+  const received = new Promise<string>((resolve) =>
+    socket.once("run:notify", (p: { id: string }) => resolve(p.id))
+  );
+  publisher.of("/worker").to(ROOM).emit("run:notify", { id: payload });
+  return withTimeout(received, timeoutMs, `delivery of ${payload}`);
+}
+
+describe("lazy socket.io redis adapter under Redis failover", () => {
+  for (const mode of ["lazy", "eager"] as const) {
+    isolatedRedisTest(
+      `[${mode}] subscriptions and delivery recover after every pub/sub connection is killed`,
+      async ({ redisContainer }) => {
+        const cleanup = tracker();
+        try {
+          const control = client(redisContainer, cleanup);
+          const holder = await startServer(mode, redisContainer, cleanup);
+          const publisher = await startServer(mode, redisContainer, cleanup);
+          const socket = await connectAndJoin(holder.url, cleanup);
+
+          /** Lazy: only the holder subscribes. Eager: both processes subscribe at construction. */
+          const expected = mode === "lazy" ? 1 : 2;
+          await waitFor(
+            async () => (await numsub(control)) === expected,
+            `${expected} subscriber(s) before the kill`
+          );
+          await expect(expectDelivery(socket, publisher.io, "before-kill")).resolves.toBe(
+            "before-kill"
+          );
+
+          /** The node-swap shape: every subscriber connection is torn down server side. */
+          const killed = Number(await control.call("CLIENT", "KILL", "TYPE", "pubsub"));
+          expect(killed).toBeGreaterThanOrEqual(expected);
+          await waitFor(
+            async () => (await numsub(control)) === 0,
+            "subscriptions to be gone (proves the kill)"
+          );
+
+          await waitFor(
+            async () => (await numsub(control)) === expected,
+            "ioredis to resubscribe after reconnect"
+          );
+          await expect(expectDelivery(socket, publisher.io, "after-kill")).resolves.toBe(
+            "after-kill"
+          );
+
+          if (holder.lazy && publisher.lazy) {
+            expect(holder.lazy.isActivated("/worker")).toBe(true);
+            expect(publisher.lazy.isActivated("/worker")).toBe(false);
+          }
+        } finally {
+          await cleanup.run();
+        }
+      }
+    );
+
+    isolatedRedisTest(
+      `[${mode}] subscriptions and delivery recover after a node swap (every connection dropped, state wiped)`,
+      async ({ redisContainer }) => {
+        const cleanup = tracker();
+        try {
+          const control = client(redisContainer, cleanup);
+          const holder = await startServer(mode, redisContainer, cleanup);
+          const publisher = await startServer(mode, redisContainer, cleanup);
+          const socket = await connectAndJoin(holder.url, cleanup);
+
+          const expected = mode === "lazy" ? 1 : 2;
+          await waitFor(
+            async () => (await numsub(control)) === expected,
+            `${expected} subscriber(s) before the swap`
+          );
+          await expect(expectDelivery(socket, publisher.io, "before-swap")).resolves.toBe(
+            "before-swap"
+          );
+
+          await nodeSwap(control);
+          await waitFor(
+            async () => (await numsub(control)) === 0,
+            "subscriptions to be gone (proves the swap)"
+          );
+          await waitFor(
+            async () => (await numsub(control)) === expected,
+            "subscriptions to be restored after the swap"
+          );
+          await expect(expectDelivery(socket, publisher.io, "after-swap")).resolves.toBe(
+            "after-swap"
+          );
+
+          if (publisher.lazy) {
+            expect(publisher.lazy.isActivated("/worker")).toBe(false);
+          }
+        } finally {
+          await cleanup.run();
+        }
+      }
+    );
+  }
+
+  isolatedRedisTest(
+    "[lazy] an activation and a handshake that start during a Redis blackout complete once it lifts, and never hang",
+    async ({ redisContainer }) => {
+      const cleanup = tracker();
+      try {
+        const control = client(redisContainer, cleanup);
+        const holder = await startServer("lazy", redisContainer, cleanup);
+        const publisher = await startServer("lazy", redisContainer, cleanup);
+        /** Warm the publisher's pub connection so its later broadcast is not itself delayed by connect. */
+        await publisher.pubClient.ping();
+
+        const PAUSE_MS = 1_500;
+        /** Redis stops processing commands from every other connection; psubscribe from activation stalls. */
+        await control.call("CLIENT", "PAUSE", String(PAUSE_MS), "ALL");
+        const started = Date.now();
+
+        const activation = holder.lazy!.activate("/worker");
+        /** A handshake arriving mid-blackout waits on the same activation through the middleware. */
+        const socketPromise = connectAndJoin(holder.url, cleanup);
+
+        await withTimeout(
+          activation,
+          ACTIVATION_TIMEOUT_MS + 2_000,
+          "activation never settled after the blackout"
+        );
+        const elapsed = Date.now() - started;
+        /** Proves the pause actually held the subscribe in flight rather than it completing before the pause bit. */
+        expect(elapsed).toBeGreaterThan(PAUSE_MS * 0.6);
+
+        const socket = await socketPromise;
+        await waitFor(
+          async () => (await numsub(control)) === 1,
+          "holder subscribed after blackout"
+        );
+        await expect(expectDelivery(socket, publisher.io, "after-blackout")).resolves.toBe(
+          "after-blackout"
+        );
+        expect(publisher.lazy!.isActivated("/worker")).toBe(false);
+      } finally {
+        await cleanup.run();
+      }
+    }
+  );
+
+  isolatedRedisTest(
+    "[lazy] a process that stayed cold through a node swap activates and delivers afterwards",
+    async ({ redisContainer }) => {
+      const cleanup = tracker();
+      try {
+        const control = client(redisContainer, cleanup);
+        const holder = await startServer("lazy", redisContainer, cleanup);
+        const publisher = await startServer("lazy", redisContainer, cleanup);
+        expect(await numsub(control)).toBe(0);
+
+        await nodeSwap(control);
+        expect(holder.lazy!.isActivated("/worker")).toBe(false);
+
+        const socket = await connectAndJoin(holder.url, cleanup);
+        await waitFor(
+          async () => (await numsub(control)) === 1,
+          "holder to subscribe after the swap",
+          30_000
+        );
+        await expect(expectDelivery(socket, publisher.io, "cold-then-swap")).resolves.toBe(
+          "cold-then-swap"
+        );
+        expect(publisher.lazy!.isActivated("/worker")).toBe(false);
+      } finally {
+        await cleanup.run();
+      }
+    }
+  );
+});
diff --git a/apps/webapp/test/lazySocketIoAdapter.test.ts b/apps/webapp/test/lazySocketIoAdapter.test.ts
new file mode 100644
index 00000000000..0fdb694ec1e
--- /dev/null
+++ b/apps/webapp/test/lazySocketIoAdapter.test.ts
@@ -0,0 +1,801 @@
+import { redisTest } from "@internal/testcontainers";
+import { createAdapter } from "@socket.io/redis-adapter";
+import { Redis, type RedisOptions } from "ioredis";
+import { createServer, type Server as HttpServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { io as ioClient, type Socket as ClientSocket } from "socket.io-client";
+import { Server } from "socket.io";
+import { describe, expect } from "vitest";
+import {
+  createLazySocketIoAdapter,
+  RESPONSE_DEPENDENT_METHODS,
+  withTimeout,
+} from "~/v3/lazySocketIoAdapter.server";
+
+const KEY = "tr:socket.io:";
+const ADAPTER_OPTS = { key: KEY, publishOnSpecificResponseChannel: true } as const;
+const WORKER_REQUEST_CHANNEL = `${KEY}-request#/worker#`;
+const DEV_WORKER_REQUEST_CHANNEL = `${KEY}-request#/dev-worker#`;
+
+type Cleanup = () => Promise<void> | void;
+
+function tracker() {
+  const cleanups: Cleanup[] = [];
+  let done = false;
+  return {
+    add: (fn: Cleanup) => cleanups.push(fn),
+    async run() {
+      if (done) {
+        return;
+      }
+      done = true;
+      for (const fn of cleanups.reverse()) {
+        await fn();
+      }
+    },
+  };
+}
+
+/** ioredis surfaces post-disconnect socket errors as unhandled rejections; absorb them. */
+function createRedis(options: RedisOptions, cleanup: ReturnType<typeof tracker>): Redis {
+  const client = new Redis(options);
+  client.on("error", () => {});
+  cleanup.add(() => client.disconnect());
+  return client;
+}
+
+async function numsub(inspector: Redis, channel: string): Promise<number> {
+  const result = (await inspector.pubsub("NUMSUB", channel)) as [string, number];
+  return Number(result[1]);
+}
+
+/**
+ * Per-adapter response channels for /worker. Each adapter instance owns one,
+ * keyed by its uid, so this counts adapter instances that have flushed even
+ * when they share a single Redis connection (NUMSUB counts connections, not
+ * subscribe calls, so it cannot tell two adapters on one client apart).
+ */
+async function workerInstanceChannels(inspector: Redis): Promise<number> {
+  const channels = (await inspector.pubsub("CHANNELS", `${KEY}-response#/worker#*`)) as string[];
+  return channels.filter((c) => c !== `${KEY}-response#/worker#`).length;
+}
+
+async function numpat(inspector: Redis): Promise<number> {
+  return Number(await inspector.pubsub("NUMPAT"));
+}
+
+/**
+ * The /worker channels with the adapter's per-instance uid masked, so two
+ * adapter instances can be compared for shape.
+ */
+async function workerChannels(inspector: Redis): Promise<string[]> {
+  const channels = (await inspector.pubsub("CHANNELS", `${KEY}*`)) as string[];
+  return channels
+    .filter((c) => c.includes("#/worker#"))
+    .map((c) => c.replace(/(#\/worker#)[^#]+#$/, "$1<uid>#"))
+    .sort();
+}
+
+/**
+ * Waits for a Redis-visible condition. Subscriptions are issued over a
+ * separate connection, so they are not necessarily visible the instant an
+ * await resolves.
+ */
+async function waitFor(check: () => Promise<boolean>, message: string, timeoutMs = 5000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await check()) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error(`Timed out waiting for: ${message}`);
+}
+
+/**
+ * A socket.io server wired the way the webapp wires it: lazy adapter, plus a
+ * middleware that opens the namespace's subscriptions before the handshake
+ * completes.
+ */
+async function startLazyServer(redisOptions: RedisOptions, cleanup: ReturnType<typeof tracker>) {
+  const pubClient = new Redis(redisOptions);
+  const subClient = pubClient.duplicate();
+  pubClient.on("error", () => {});
+  subClient.on("error", () => {});
+  const lazy = createLazySocketIoAdapter(pubClient, subClient, { ...ADAPTER_OPTS });
+
+  const io = new Server({ adapter: lazy.adapter });
+
+  for (const namespace of ["/worker", "/dev-worker"]) {
+    io.of(namespace).use(async (_socket, next) => {
+      try {
+        await lazy.activate(namespace);
+        next();
+      } catch (error) {
+        next(error instanceof Error ? error : new Error("activate failed"));
+      }
+    });
+  }
+
+  const httpServer: HttpServer = createServer();
+  io.attach(httpServer);
+  await new Promise<void>((resolve) => httpServer.listen(0, resolve));
+  const port = (httpServer.address() as AddressInfo).port;
+
+  cleanup.add(async () => {
+    await io.close();
+    await new Promise<void>((resolve) => httpServer.close(() => resolve()));
+    /**
+     * Stop receiving before losing the ability to respond. A request that
+     * arrives on subClient makes the adapter publishResponse on pubClient
+     * without awaiting it, so quitting pub first (or concurrently) can reject
+     * that publish with "Connection is closed". close() also fires
+     * punsubscribe/unsubscribe unawaited, and enableAutoPipelining defers
+     * commands a tick, so let each side flush before the next step.
+     */
+    await new Promise((resolve) => setImmediate(resolve));
+    await subClient.quit().catch(() => {});
+    /**
+     * A publish enqueued via enableAutoPipelining is sent on a later
+     * setImmediate; quitting before that flush rejects it with "Connection is
+     * closed". PING joins the same pipeline behind any pending publish, so
+     * once it answers, those publishes have been sent.
+     */
+    await pubClient.ping().catch(() => {});
+    await pubClient.quit().catch(() => {});
+  });
+
+  return { io, lazy, port, url: `http://localhost:${port}` };
+}
+
+async function connectClient(
+  url: string,
+  namespace: string,
+  cleanup: ReturnType<typeof tracker>
+): Promise<ClientSocket> {
+  const socket = ioClient(`${url}${namespace}`, { transports: ["websocket"] });
+  cleanup.add(() => {
+    socket.disconnect();
+  });
+  await new Promise<void>((resolve, reject) => {
+    socket.once("connect", () => resolve());
+    socket.once("connect_error", reject);
+  });
+  return socket;
+}
+
+describe("lazy socket.io redis adapter", () => {
+  redisTest(
+    "does not subscribe until a namespace serves a connection",
+    async ({ redisOptions }) => {
+      const cleanup = tracker();
+      const inspector = createRedis(redisOptions, cleanup);
+
+      try {
+        const server = await startLazyServer(redisOptions, cleanup);
+
+        expect(await numpat(inspector)).toBe(0);
+        expect(await numsub(inspector, WORKER_REQUEST_CHANNEL)).toBe(0);
+
+        await connectClient(server.url, "/worker", cleanup);
+
+        await waitFor(
+          async () => (await numsub(inspector, WORKER_REQUEST_CHANNEL)) === 1,
+          "worker request channel to gain a subscriber"
+        );
+        expect(await numpat(inspector)).toBe(1);
+      } finally {
+        await cleanup.run();
+      }
+    }
+  );
+
+  redisTest(
+    "a connection on one namespace does not subscribe the other",
+    async ({ redisOptions }) => {
+      const cleanup = tracker();
+      const inspector = createRedis(redisOptions, cleanup);
+
+      try {
+        const server = await startLazyServer(redisOptions, cleanup);
+        await connectClient(server.url, "/worker", cleanup);
+
+        await waitFor(
+          async () => (await numsub(inspector, WORKER_REQUEST_CHANNEL)) === 1,
+          "worker namespace to activate"
+        );
+
+        expect(await numsub(inspector, DEV_WORKER_REQUEST_CHANNEL)).toBe(0);
+        expect(server.lazy.isActivated("/dev-worker")).toBe(false);
+        expect(server.lazy.activatedNamespaces()).toEqual(["/worker"]);
+
+        await connectClient(server.url, "/dev-worker", cleanup);
+
+        await waitFor(
+          async () => (await numsub(inspector, DEV_WORKER_REQUEST_CHANNEL)) === 1,
+          "dev-worker namespace to activate"
+        );
+        expect(await numpat(inspector)).toBe(2);
+      } finally {
+        await cleanup.run();
+      }
+    }
+  );
+
+  redisTest(
+    "an activated namespace subscribes exactly what the stock adapter does",
+    async ({ redisOptions }) => {
+      const eagerCleanup = tracker();
+      const inspector = createRedis(redisOptions, eagerCleanup);
+
+      let eagerChannels: string[] = [];
+      let eagerPatterns = 0;
+
+      try {
+        const eagerPub = new Redis(redisOptions);
+        const eagerSub = eagerPub.duplicate();
+        eagerPub.on("error", () => {});
+        eagerSub.on("error", () => {});
+        eagerCleanup.add(() => {
+          eagerPub.disconnect();
+          eagerSub.disconnect();
+        });
+
+        const eagerIo = new Server({
+          adapter: createAdapter(eagerPub, eagerSub, { ...ADAPTER_OPTS }),
+        });
+        eagerIo.of("/worker");
+
+        await waitFor(
+          async () => (await numsub(inspector, WORKER_REQUEST_CHANNEL)) === 1,
+          "stock adapter to subscribe"
+        );
+
+        eagerChannels = await workerChannels(inspector);
+        eagerPatterns = await numpat(inspector);
+      } finally {
+        await eagerCleanup.run();
+      }
+
+      const lazyCleanup = tracker();
+      const inspector2 = createRedis(redisOptions, lazyCleanup);
+
+      try {
+        await waitFor(
+          async () => (await numsub(inspector2, WORKER_REQUEST_CHANNEL)) === 0,
+          "stock adapter subscriptions to drain"
+        );
+
+        const server = await startLazyServer(redisOptions, lazyCleanup);
+        await connectClient(server.url, "/worker", lazyCleanup);
+
+        await waitFor(
+          async () => (await numsub(inspector2, WORKER_REQUEST_CHANNEL)) === 1,
+          "lazy adapter to subscribe after connection"
+        );
+
+        const lazyChannels = await workerChannels(inspector2);
+
+        expect(eagerChannels).toEqual([
+          `${KEY}-request#/worker#`,
+          `${KEY}-response#/worker#`,
+          `${KEY}-response#/worker#<uid>#`,
+        ]);
+        expect(lazyChannels).toEqual(eagerChannels);
+
+        /** The stock adapter also subscribes the unused default namespace; the lazy one does not. */
+        expect(eagerPatterns).toBe(2);
+        expect(await numpat(inspector2)).toBe(1);
+      } finally {
+        await lazyCleanup.run();
+      }
+    }
+  );
+
+  redisTest(
+    "a process with no connections receives nothing, and delivery still works",
+    async ({ redisOptions }) => {
+      const cleanup = tracker();
+      const inspector = createRedis(redisOptions, cleanup);
+
+      try {
+        const holder = await startLazyServer(redisOptions, cleanup);
+        const publisher = await startLazyServer(redisOptions, cleanup);
+
+        const client = await connectClient(holder.url, "/worker", cleanup);
+
+        const room = "room:run_test";
+        holder.io.of("/worker").sockets.get(client.id!)?.join(room);
+
+        await waitFor(
+          async () => (await numsub(inspector, WORKER_REQUEST_CHANNEL)) === 1,
+          "only the holder to be subscribed"
+        );
+
+        expect(publisher.lazy.isActivated("/worker")).toBe(false);
+        expect(await numsub(inspector, WORKER_REQUEST_CHANNEL)).toBe(1);
+        expect(await numpat(inspector)).toBe(1);
+
+        const received = new Promise<{ friendlyId: string }>((resolve) => {
+          client.on("run:notify", (payload: { run: { friendlyId: string } }) =>
+            resolve(payload.run)
+          );
+        });
+
+        publisher.io
+          .of("/worker")
+          .to(room)
+          .emit("run:notify", { version: "1", run: { friendlyId: "run_test" } });
+
+        await expect(received).resolves.toEqual({ friendlyId: "run_test" });
+
+        expect(publisher.lazy.isActivated("/worker")).toBe(false);
+      } finally {
+        await cleanup.run();
+      }
+    }
+  );
+
+  redisTest(
+    "a distributed query from a publisher with no connections still sees remote sockets",
+    async ({ redisOptions }) => {
+      const cleanup = tracker();
+      const inspector = createRedis(redisOptions, cleanup);
+
+      try {
+        const holder = await startLazyServer(redisOptions, cleanup);
+        const publisher = await startLazyServer(redisOptions, cleanup);
+
+        await connectClient(holder.url, "/worker", cleanup);
+
+        await waitFor(
+          async () => (await numsub(inspector, WORKER_REQUEST_CHANNEL)) === 1,
+          "only the holder to be subscribed"
+        );
+        expect(publisher.lazy.isActivated("/worker")).toBe(false);
+
+        /**
+         * fetchSockets sizes its wait from NUMSUB on the request channel and
+         * assumes the caller is one of them, so an unsubscribed caller would
+         * see numSub === 1, take it for itself and return only local sockets.
+         */
+        const sockets = await publisher.io.of("/worker").fetchSockets();
+
+        expect(sockets).toHaveLength(1);
+        expect(publisher.lazy.isActivated("/worker")).toBe(true);
+        await waitFor(
+          async () => (await numsub(inspector, WORKER_REQUEST_CHANNEL)) === 2,
+          "the querying process to have subscribed"
+        );
+      } finally {
+        await cleanup.run();
+      }
+    }
+  );
+
+  redisTest(
+    "a server-side emit with ack from a publisher with no connections reaches peers",
+    async ({ redisOptions }) => {
+      const cleanup = tracker();
+      const inspector = createRedis(redisOptions, cleanup);
+
+      try {
+        const holder = await startLazyServer(redisOptions, cleanup);
+        const publisher = await startLazyServer(redisOptions, cleanup);
+
+        await connectClient(holder.url, "/worker", cleanup);
+        holder.io.of("/worker").on("ping-peers", (ack: (value: string) => void) => ack("pong"));
+
+        await waitFor(
+          async () => (await numsub(inspector, WORKER_REQUEST_CHANNEL)) === 1,
+          "only the holder to be subscribed"
+        );
+        expect(publisher.lazy.isActivated("/worker")).toBe(false);
+
+        const responses = await publisher.io.of("/worker").serverSideEmitWithAck("ping-peers");
+
+        expect(responses).toEqual(["pong"]);
+        expect(publisher.lazy.isActivated("/worker")).toBe(true);
+      } finally {
+        await cleanup.run();
+      }
+    }
+  );
+
+  redisTest(
+    "every response-dependent adapter method still exists to be wrapped",
+    async ({ redisOptions }) => {
+      const cleanup = tracker();
+
+      try {
+        const server = await startLazyServer(redisOptions, cleanup);
+        const adapter = server.io.of("/worker").adapter as unknown as Record<string, unknown>;
+
+        /**
+         * The wrapper skips silently when a method is missing, so an upstream
+         * rename would drop the RPC protection without any other test noticing.
+         */
+        for (const method of Object.keys(RESPONSE_DEPENDENT_METHODS)) {
+          expect(typeof adapter[method], method).toBe("function");
+        }
+        /** Unwrapped, but the ack path of serverSideEmit relies on it reaching the wrapped emitWithAck. */
+        expect(typeof adapter.serverSideEmit).toBe("function");
+      } finally {
+        await cleanup.run();
+      }
+    }
+  );
+
+  redisTest(
+    "a namespace recreated under the same name activates like new",
+    async ({ redisOptions }) => {
+      const cleanup = tracker();
+      const inspector = createRedis(redisOptions, cleanup);
+
+      try {
+        const server = await startLazyServer(redisOptions, cleanup);
+        await server.lazy.activate("/worker");
+        await waitFor(
+          async () => (await workerInstanceChannels(inspector)) === 1,
+          "first adapter to subscribe"
+        );
+
+        /**
+         * Drop and rebuild the namespace so socket.io constructs a second
+         * adapter for the same name. A stale activation record would make the
+         * new adapter report itself subscribed while its queue never flushed.
+         */
+        (server.io as unknown as { _nsps: Map<string, unknown> })._nsps.delete("/worker");
+        server.io.of("/worker");
+
+        expect(server.lazy.isActivated("/worker")).toBe(false);
+
+        await server.lazy.activate("/worker");
+
+        expect(server.lazy.isActivated("/worker")).toBe(true);
+        await waitFor(
+          async () => (await workerInstanceChannels(inspector)) === 2,
+          "the recreated adapter to subscribe alongside the first"
+        );
+      } finally {
+        await cleanup.run();
+      }
+    }
+  );
+
+  redisTest(
+    "sync adapter operations return synchronously once the namespace is active",
+    async ({ redisOptions }) => {
+      const cleanup = tracker();
+
+      try {
+        const server = await startLazyServer(redisOptions, cleanup);
+        const adapter = server.io.of("/worker").adapter as unknown as {
+          broadcastWithAck: (...args: unknown[]) => unknown;
+        };
+        const args = [
+          { type: 2, data: ["noop"] },
+          { rooms: new Set<string>(), except: new Set<string>(), flags: { timeout: 60_000 } },
+          () => {},
+          () => {},
+        ];
+
+        const cold = adapter.broadcastWithAck(...args);
+        expect(cold).toBeInstanceOf(Promise);
+        await cold;
+
+        /**
+         * broadcastWithAck returns void in the stock adapter; a Promise here
+         * would mean the publish was deferred a tick and could reorder against
+         * a plain broadcast issued right after it.
+         */
+        const warm = adapter.broadcastWithAck(...args);
+        expect(warm).toBeUndefined();
+      } finally {
+        await cleanup.run();
+      }
+    }
+  );
+
+  redisTest("withTimeout bounds a stalled activation but passes fast ones through", async () => {
+    await expect(withTimeout(Promise.resolve("ok"), 1000, "slow")).resolves.toBe("ok");
+    await expect(withTimeout(Promise.reject(new Error("boom")), 1000, "slow")).rejects.toThrow(
+      "boom"
+    );
+    await expect(withTimeout(new Promise<never>(() => {}), 20, "stalled")).rejects.toThrow(
+      "stalled"
+    );
+  });
+
+  redisTest(
+    "a fire-and-forget server-side emit reaches peers without subscribing the sender",
+    async ({ redisOptions }) => {
+      const cleanup = tracker();
+      const inspector = createRedis(redisOptions, cleanup);
+
+      try {
+        const holder = await startLazyServer(redisOptions, cleanup);
+        const publisher = await startLazyServer(redisOptions, cleanup);
+
+        await connectClient(holder.url, "/worker", cleanup);
+        await waitFor(
+          async () => (await numsub(inspector, WORKER_REQUEST_CHANNEL)) === 1,
+          "holder to subscribe"
+        );
+
+        const received = new Promise<string>((resolve) =>
+          holder.io.of("/worker").on("fire", (value: string) => resolve(value))
+        );
+
+        /** No ack means no requestId on the wire, so peers never reply and the sender needs no subscription. */
+        publisher.io.of("/worker").serverSideEmit("fire", "payload");
+
+        await expect(received).resolves.toBe("payload");
+        expect(publisher.lazy.isActivated("/worker")).toBe(false);
+        expect(await numsub(inspector, WORKER_REQUEST_CHANNEL)).toBe(1);
+      } finally {
+        await cleanup.run();
+      }
+    }
+  );
+
+  redisTest(
+    "local-only fetchSockets and broadcastWithAck leave an idle process unsubscribed",
+    async ({ redisOptions }) => {
+      const cleanup = tracker();
+      const inspector = createRedis(redisOptions, cleanup);
+
+      try {
+        const server = await startLazyServer(redisOptions, cleanup);
+        const nsp = server.io.of("/worker");
+
+        const local = await nsp.local.fetchSockets();
+        expect(local).toEqual([]);
+
+        const adapter = nsp.adapter as unknown as {
+          broadcastWithAck: (...args: unknown[]) => unknown;
+        };
+        const result = adapter.broadcastWithAck(
+          { type: 2, data: ["noop"] },
+          { rooms: new Set<string>(), except: new Set<string>(), flags: { local: true } },
+          () => {},
+          () => {}
+        );
+
+        /** Synchronous on the cold path too, because a local call never activates. */
+        expect(result).toBeUndefined();
+        expect(server.lazy.isActivated("/worker")).toBe(false);
+        expect(await numpat(inspector)).toBe(0);
+      } finally {
+        await cleanup.run();
+      }
+    }
+  );
+
+  redisTest(
+    "an activation still in flight when its namespace is rebuilt cannot mark the replacement ready",
+    async ({ redisOptions }) => {
+      const cleanup = tracker();
+      const inspector = createRedis(redisOptions, cleanup);
+
+      try {
+        const pubClient = new Redis(redisOptions);
+        /**
+         * Not yet connected. The first queued psubscribe triggers ioredis's
+         * auto-connect, so the first adapter's flush is in flight from the
+         * moment activate() is called and cannot settle before the synchronous
+         * reconstruction below: a socket connect is at least a macrotask away.
+         */
+        const subClient = new Redis({ ...redisOptions, lazyConnect: true });
+        pubClient.on("error", () => {});
+        subClient.on("error", () => {});
+        cleanup.add(async () => {
+          /** Sub before pub, so an in-flight response still has a client to publish on. */
+          await subClient.quit().catch(() => {});
+          await pubClient.ping().catch(() => {});
+          await pubClient.quit().catch(() => {});
+        });
+
+        const lazy = createLazySocketIoAdapter(pubClient, subClient, { ...ADAPTER_OPTS });
+        const io = new Server({ adapter: lazy.adapter });
+        const first = io.of("/worker");
+        const firstActivation = lazy.activate("/worker");
+        expect(lazy.isActivated("/worker")).toBe(true);
+        expect(subClient.status).not.toBe("ready");
+
+        /** Rebuild under the same name while the first activation is still waiting on the connection. */
+        (io as unknown as { _nsps: Map<string, unknown> })._nsps.delete("/worker");
+        const second = io.of("/worker");
+        expect(second).not.toBe(first);
+        expect(lazy.isActivated("/worker")).toBe(false);
+
+        await firstActivation;
+
+        /**
+         * The first adapter's completion must have settled into its own state.
+         * The replacement is still cold: a reply-needing call takes the async
+         * path rather than the ready fast path, and its own response channel
+         * has not appeared.
+         */
+        expect(lazy.isActivated("/worker")).toBe(false);
+        const replacement = second.adapter as unknown as {
+          broadcastWithAck: (...args: unknown[]) => unknown;
+        };
+        const cold = replacement.broadcastWithAck(
+          { type: 2, data: ["noop"] },
+          { rooms: new Set<string>(), except: new Set<string>(), flags: { timeout: 60_000 } },
+          () => {},
+          () => {}
+        );
+        expect(cold).toBeInstanceOf(Promise);
+        await cold;
+
+        expect(lazy.isActivated("/worker")).toBe(true);
+        await waitFor(
+          async () => (await workerInstanceChannels(inspector)) === 2,
+          "both adapter generations to hold their own response channel"
+        );
+      } finally {
+        await cleanup.run();
+      }
+    }
+  );
+
+  redisTest(
+    "serverCount keeps counting the caller on a cold namespace without subscribing it",
+    async ({ redisOptions }) => {
+      const cleanup = tracker();
+      const inspector = createRedis(redisOptions, cleanup);
+
+      try {
+        const lone = await startLazyServer(redisOptions, cleanup);
+        const loneNsp = lone.io.of("/worker");
+
+        /** Stock adapter on a lone process returns 1: itself. The cold lazy adapter must agree. */
+        await expect(loneNsp.adapter.serverCount()).resolves.toBe(1);
+        expect(lone.lazy.isActivated("/worker")).toBe(false);
+        expect(await numsub(inspector, WORKER_REQUEST_CHANNEL)).toBe(0);
+
+        const peer = await startLazyServer(redisOptions, cleanup);
+        await connectClient(peer.url, "/worker", cleanup);
+        await waitFor(
+          async () => (await numsub(inspector, WORKER_REQUEST_CHANNEL)) === 1,
+          "peer to subscribe"
+        );
+
+        /** One subscribed peer plus the cold caller itself. */
+        await expect(loneNsp.adapter.serverCount()).resolves.toBe(2);
+        expect(lone.lazy.isActivated("/worker")).toBe(false);
+
+        /** Once subscribed, NUMSUB already includes this process; no double counting. */
+        await lone.lazy.activate("/worker");
+        await waitFor(
+          async () => (await numsub(inspector, WORKER_REQUEST_CHANNEL)) === 2,
+          "caller to subscribe"
+        );
+        await expect(loneNsp.adapter.serverCount()).resolves.toBe(2);
+      } finally {
+        await cleanup.run();
+      }
+    }
+  );
+
+  redisTest(
+    "serverCount does not double count when activation lands during its cold read",
+    async ({ redisOptions }) => {
+      const cleanup = tracker();
+
+      try {
+        /**
+         * Force the interleaving the bots described. The pub client is not yet
+         * connected, so the cold NUMSUB queues behind a TCP connect and
+         * handshake, while the sub client is already connected and a
+         * synchronously started activate() subscribes in a single round trip.
+         * The subscription therefore reaches Redis before NUMSUB executes, and
+         * NUMSUB already includes this process.
+         */
+        const pubClient = new Redis({ ...redisOptions, lazyConnect: true });
+        const subClient = new Redis(redisOptions);
+        pubClient.on("error", () => {});
+        subClient.on("error", () => {});
+        cleanup.add(async () => {
+          await subClient.quit().catch(() => {});
+          await pubClient.ping().catch(() => {});
+          await pubClient.quit().catch(() => {});
+        });
+        /**
+         * A real round trip, not a status poll: clients built from the fixture
+         * options sit in "wait" until their first command, so polling status
+         * without issuing one would never see "ready".
+         */
+        await subClient.ping();
+        expect(subClient.status).toBe("ready");
+
+        const lazy = createLazySocketIoAdapter(pubClient, subClient, { ...ADAPTER_OPTS });
+        const io = new Server({ adapter: lazy.adapter });
+        const nsp = io.of("/worker");
+
+        expect(pubClient.status).not.toBe("ready");
+        const counting = nsp.adapter.serverCount();
+        expect(lazy.isActivated("/worker")).toBe(false);
+        const activating = lazy.activate("/worker");
+
+        /** A lone process is exactly one server, cold or subscribed; never two. */
+        await expect(counting).resolves.toBe(1);
+        await activating;
+        await expect(nsp.adapter.serverCount()).resolves.toBe(1);
+      } finally {
+        await cleanup.run();
+      }
+    }
+  );
+
+  redisTest("activation is idempotent across concurrent connections", async ({ redisOptions }) => {
+    const cleanup = tracker();
+    const inspector = createRedis(redisOptions, cleanup);
+
+    try {
+      const server = await startLazyServer(redisOptions, cleanup);
+
+      await Promise.all([
+        connectClient(server.url, "/worker", cleanup),
+        connectClient(server.url, "/worker", cleanup),
+        connectClient(server.url, "/worker", cleanup),
+      ]);
+
+      await waitFor(
+        async () => (await numsub(inspector, WORKER_REQUEST_CHANNEL)) === 1,
+        "worker namespace to activate"
+      );
+
+      expect(await numsub(inspector, WORKER_REQUEST_CHANNEL)).toBe(1);
+      expect(await numpat(inspector)).toBe(1);
+      expect(server.lazy.activatedNamespaces()).toEqual(["/worker"]);
+    } finally {
+      await cleanup.run();
+    }
+  });
+
+  redisTest("a failed activation is retried rather than cached", async ({ redisOptions }) => {
+    const cleanup = tracker();
+    const inspector = createRedis(redisOptions, cleanup);
+
+    try {
+      const pubClient = new Redis(redisOptions);
+      pubClient.on("error", () => {});
+      /** Offline and refusing to queue, so the first subscribe rejects for real. */
+      const subClient = new Redis({
+        ...redisOptions,
+        lazyConnect: true,
+        enableOfflineQueue: false,
+      });
+      cleanup.add(() => {
+        pubClient.disconnect();
+        subClient.disconnect();
+      });
+
+      /** Connection failures here are expected; keep them off the unhandled path. */
+      subClient.on("error", () => {});
+
+      const lazy = createLazySocketIoAdapter(pubClient, subClient, { ...ADAPTER_OPTS });
+      const io = new Server({ adapter: lazy.adapter });
+      io.of("/worker");
+
+      await expect(lazy.activate("/worker")).rejects.toThrow();
+      expect(lazy.isActivated("/worker")).toBe(false);
+      expect(await numsub(inspector, WORKER_REQUEST_CHANNEL)).toBe(0);
+
+      /** The rejected command already kicked off a connect; wait for it to settle. */
+      await waitFor(async () => subClient.status === "ready", "subClient to reconnect");
+      await lazy.activate("/worker");
+
+      await waitFor(
+        async () => (await numsub(inspector, WORKER_REQUEST_CHANNEL)) === 1,
+        "retry to complete the full subscription set"
+      );
+      expect(await numpat(inspector)).toBe(1);
+    } finally {
+      await cleanup.run();
+    }
+  });
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 173aac3eea0..1d45c1ca4de 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -872,6 +872,9 @@ importers:
       jsdom:
         specifier: ^30.0.1
         version: 30.0.1
+      socket.io-client:
+        specifier: 4.7.5
+        version: 4.7.5(bufferutil@4.0.9)(supports-color@10.0.0)
       supertest:
         specifier: ^7.0.0
         version: 7.0.0

From 8067b1f6e4c97cc467339d3dadc4b584bf1e0638 Mon Sep 17 00:00:00 2001
From: Eric Allam <eallam@icloud.com>
Date: Thu, 17 Sep 2026 15:40:03 +0000
Subject: [PATCH 6/6] perf(ci): balance internal tests across two runners

Balance internal test files across packages and split the workload
across two runners to reduce CI waits. Preserve package test
configuration, refresh duration estimates, and combine all shard reports
for timing updates.

Mono-RevId: f43f740e7a8db6a812a157a8a02b2a15a7ac66fa
---
 .github/workflows/pr_checks.yml               |  10 +-
 .github/workflows/unit-tests-internal.yml     | 108 +++-
 .../observability-map/src/integration.test.ts |   6 +-
 .../scripts/update-test-timings.mjs           |  17 +
 .../src/internal-report-merge.test.ts         |  63 +++
 .../testcontainers/src/sequencer.cjs          |  11 +-
 .../testcontainers/src/sequencer.test.ts      |  48 ++
 .../testcontainers/src/test-timings.test.ts   | 102 ++++
 .../testcontainers/src/test-timings.ts        |  54 ++
 internal-test-projects.mts                    |  37 ++
 knip.json                                     |   6 +-
 test-timings.json                             | 473 +++++++++++++-----
 vitest.internal-reports.config.mjs            |   3 +
 vitest.internal.config.ts                     |  18 +
 14 files changed, 800 insertions(+), 156 deletions(-)
 create mode 100644 internal-packages/testcontainers/scripts/update-test-timings.mjs
 create mode 100644 internal-packages/testcontainers/src/internal-report-merge.test.ts
 create mode 100644 internal-packages/testcontainers/src/sequencer.test.ts
 create mode 100644 internal-packages/testcontainers/src/test-timings.test.ts
 create mode 100644 internal-packages/testcontainers/src/test-timings.ts
 create mode 100644 internal-test-projects.mts
 create mode 100644 vitest.internal-reports.config.mjs
 create mode 100644 vitest.internal.config.ts

diff --git a/.github/workflows/pr_checks.yml b/.github/workflows/pr_checks.yml
index 7a2f8fe42f0..a3e55807b4e 100644
--- a/.github/workflows/pr_checks.yml
+++ b/.github/workflows/pr_checks.yml
@@ -2,7 +2,7 @@ name: 🤖 PR Checks
 
 on:
   pull_request:
-    types: [opened, synchronize, reopened]
+    types: [opened, synchronize, reopened, ready_for_review]
   merge_group:
 
 concurrency:
@@ -91,6 +91,10 @@ jobs:
               - 'pnpm-lock.yaml'
               - 'pnpm-workspace.yaml'
               - 'turbo.json'
+              - 'vitest.internal.config.ts'
+              - 'vitest.internal-reports.config.mjs'
+              - 'internal-test-projects.mts'
+              - 'test-timings.json'
             # The whole webapp app tree, not just its routes, and that is the whole reason this
             # filter exists. Two tests in @internal/observability-map read it: integration.test.ts
             # scans the live route tree, and webappSymbols.test.ts walks all of apps/webapp/app and
@@ -110,8 +114,8 @@ jobs:
             # Deliberately NOT here: this package's own paths, and packages/plugins/src and
             # internal-packages/rbac/src, the other two trees webappSymbols.test.ts reads.
             # `internal` above already matches `internal-packages/**` and the shared packages, and
-            # `unit-tests-internal.yml` runs `turbo run test --filter "@internal/*"`, which picks up
-            # @internal/observability-map and runs the same vitest suite. Listing them here as well
+            # `unit-tests-internal.yml` loads every @internal/* test project through
+            # vitest.internal.config.ts, including the same observability-map suite. Listing them here as well
             # ran the suite twice on every PR touching them, which was this filter's own doing.
             #
             # Also deliberately NOT here: pr_checks.yml, package.json, pnpm-lock.yaml,
diff --git a/.github/workflows/unit-tests-internal.yml b/.github/workflows/unit-tests-internal.yml
index 8a0d5bebba2..c375d4fed8e 100644
--- a/.github/workflows/unit-tests-internal.yml
+++ b/.github/workflows/unit-tests-internal.yml
@@ -14,14 +14,18 @@ on:
 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.
+    # Two Docker daemons and disks, with twelve serial test processes per runner.
+    # Global shard indices ensure every file runs exactly once across both machines.
+    strategy:
+      fail-fast: false
+      matrix:
+        machine: [1, 2]
     runs-on: warp-ubuntu-latest-x64-32x
     env:
       DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
-      SHARD_TOTAL: 12
+      MACHINE_INDEX: ${{ matrix.machine }}
+      SHARDS_PER_MACHINE: 12
+      SHARD_TOTAL: 24
     steps:
       - name: 🔧 Disable IPv6
         run: |
@@ -104,24 +108,32 @@ jobs:
         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.
+        # Build once up-front so shard processes 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)
+      - name: 🧪 Run Internal Unit Tests (machine ${{ matrix.machine }}/2)
         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.
+          # Each process discovers all internal projects, then takes its globally
+          # balanced share of files. Keep one test file active per process.
+          first=$(( (MACHINE_INDEX - 1) * SHARDS_PER_MACHINE + 1 ))
+          last=$(( MACHINE_INDEX * SHARDS_PER_MACHINE ))
           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 &
+          for i in $(seq "$first" "$last"); do
+            (
+              started=$SECONDS
+              result=0
+              pnpm exec vitest run --config vitest.internal.config.ts \
+                --sequence.concurrent=false --reporter=default --reporter=blob \
+                --shard="$i/$SHARD_TOTAL" --passWithNoTests \
+                > "/tmp/internal-shard-$i.log" 2>&1 || result=$?
+              echo "::notice::internal shard $i/$SHARD_TOTAL finished in $((SECONDS - started))s (exit $result)"
+              exit "$result"
+            ) &
             pids[i]=$!
           done
-          for i in $(seq 1 "$SHARD_TOTAL"); do
+          for i in $(seq "$first" "$last"); do
             if ! wait "${pids[i]}"; then
               status=1
               echo "::error::internal unit test shard $i/$SHARD_TOTAL failed"
@@ -132,13 +144,67 @@ jobs:
           done
           exit "$status"
 
-      - name: Gather all reports
+      - name: Upload blob reports
         if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: internal-blob-report-${{ matrix.machine }}
+          path: .vitest-reports/*
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 1
+
+  merge-reports:
+    name: "📊 Merge Internal Reports"
+    if: ${{ !cancelled() }}
+    needs: [unitTests]
+    runs-on: warp-ubuntu-latest-x64-2x
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24.18.0
+
+      - name: Download blob reports
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          path: .vitest-reports
+          pattern: internal-blob-report-*
+          merge-multiple: true
+
+      - name: Check all shard reports are present
         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}"' _ {} \;
+          for i in $(seq 1 24); do
+            test -s ".vitest-reports/blob-$i-24.json"
+          done
 
       - name: 📊 Merge reports
+        run: >-
+          pnpm dlx vitest@4.1.7 run --config vitest.internal-reports.config.mjs --merge-reports
+          --reporter=default --reporter=json --outputFile.json=internal-test-results.json
+
+      - name: Validate merged test timings
+        run: |
+          cp test-timings.json "$RUNNER_TEMP/checked-test-timings.json"
+          node internal-packages/testcontainers/scripts/update-test-timings.mjs \
+            internal-test-results.json "$RUNNER_TEMP/checked-test-timings.json"
+
+      - name: Upload internal test timings
         if: ${{ !cancelled() }}
-        run: pnpm dlx vitest@4.1.7 run --merge-reports --pass-with-no-tests
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: internal-test-results
+          path: internal-test-results.json
+          if-no-files-found: error
+          retention-days: 14
diff --git a/internal-packages/observability-map/src/integration.test.ts b/internal-packages/observability-map/src/integration.test.ts
index 29a77510f02..800542f884e 100644
--- a/internal-packages/observability-map/src/integration.test.ts
+++ b/internal-packages/observability-map/src/integration.test.ts
@@ -9,6 +9,7 @@ import {
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import internalTestConfig from "../../../vitest.internal.config.js";
 import { isScannableFile, scanDirectory, scanFile } from "./scan.js";
 import { buildReport } from "./score.js";
 import { SCORED_CHECK_IDS } from "./checks/index.js";
@@ -306,7 +307,10 @@ describe("the package's tests are wired into the gate", () => {
     const internal = text.split("            internal:")[1]!.split("            obsmap:")[0]!;
     expect(internal).toContain(`'${PATH_PREFIX}internal-packages/**'`);
     expect(internal).not.toContain(`!${PATH_PREFIX}internal-packages/observability-map`);
-    expect(read(resolve(WORKFLOWS, "unit-tests-internal.yml"))).toContain('--filter "@internal/*"');
+    expect(read(resolve(WORKFLOWS, "unit-tests-internal.yml"))).toContain(
+      "--config vitest.internal.config.ts"
+    );
+    expect(internalTestConfig.test?.projects).toContain(resolve(__dirname, ".."));
   });
 
   // The test above only checks the package's own source path, a different overlap that was already
diff --git a/internal-packages/testcontainers/scripts/update-test-timings.mjs b/internal-packages/testcontainers/scripts/update-test-timings.mjs
new file mode 100644
index 00000000000..902603aeae3
--- /dev/null
+++ b/internal-packages/testcontainers/scripts/update-test-timings.mjs
@@ -0,0 +1,17 @@
+// Node 24 strips the helper's types, so the weekly job needs no dependency install.
+import { readFileSync, writeFileSync } from "node:fs";
+import { updateTestTimings } from "../src/test-timings.ts";
+
+const [reportPath, timingsPath] = process.argv.slice(2);
+if (!reportPath || !timingsPath) {
+  throw new Error(
+    "Usage: update-test-timings.mjs <internal-test-results.json> <test-timings.json>"
+  );
+}
+const previous = JSON.parse(readFileSync(timingsPath, "utf8"));
+const report = JSON.parse(readFileSync(reportPath, "utf8"));
+const updated = updateTestTimings(previous, report);
+writeFileSync(timingsPath, `${JSON.stringify(updated, null, 2)}\n`);
+console.log(
+  `Refreshed ${Object.keys(updated).filter((file) => updated[file] !== previous[file]).length} timings`
+);
diff --git a/internal-packages/testcontainers/src/internal-report-merge.test.ts b/internal-packages/testcontainers/src/internal-report-merge.test.ts
new file mode 100644
index 00000000000..beac07715f9
--- /dev/null
+++ b/internal-packages/testcontainers/src/internal-report-merge.test.ts
@@ -0,0 +1,63 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { expect, test } from "vitest";
+
+const monorepoRoot = resolve(__dirname, "../../..");
+const vitestCli = resolve(monorepoRoot, "node_modules/vitest/vitest.mjs");
+const projectHelper = pathToFileURL(resolve(monorepoRoot, "internal-test-projects.mts")).href;
+
+test("replays named project blobs into a nonempty JSON report without package dependencies", () => {
+  const root = mkdtempSync(resolve(tmpdir(), "internal-report-merge-"));
+  try {
+    const projects = ["first", "second"].map((name) => {
+      const directory = resolve(root, "internal-packages", name);
+      mkdirSync(directory, { recursive: true });
+      writeFileSync(
+        resolve(directory, "package.json"),
+        JSON.stringify({ name: `@internal/${name}`, scripts: { test: "vitest" } })
+      );
+      writeFileSync(
+        resolve(directory, "vitest.config.mjs"),
+        "export default { test: { globals: true } };"
+      );
+      writeFileSync(
+        resolve(directory, "example.test.js"),
+        "test('passes', () => expect(2 + 2).toBe(4));"
+      );
+      return directory;
+    });
+    writeFileSync(
+      resolve(root, "run.config.mjs"),
+      `export default { test: { projects: ${JSON.stringify(projects)} } };`
+    );
+    writeFileSync(
+      resolve(root, "merge.config.mjs"),
+      `import { getInternalTestReportConfig } from ${JSON.stringify(projectHelper)};
+export default getInternalTestReportConfig(${JSON.stringify(root)});`
+    );
+    const run = (args: string[]) =>
+      execFileSync(process.execPath, [vitestCli, "run", ...args], {
+        cwd: root,
+        encoding: "utf8",
+        timeout: 10_000,
+      });
+    run(["--config=run.config.mjs", "--maxWorkers=1", "--reporter=blob"]);
+    run([
+      "--config=merge.config.mjs",
+      "--merge-reports",
+      "--reporter=json",
+      "--outputFile.json=results.json",
+    ]);
+    const merged = JSON.parse(readFileSync(resolve(root, "results.json"), "utf8"));
+    expect(merged.success).toBe(true);
+    expect(merged.numPassedTests).toBe(2);
+    expect(merged.testResults.map((file: { name: string }) => file.name).sort()).toEqual(
+      projects.map((directory) => resolve(directory, "example.test.js")).sort()
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}, 30_000);
diff --git a/internal-packages/testcontainers/src/sequencer.cjs b/internal-packages/testcontainers/src/sequencer.cjs
index 14084e6e84d..e18e5ada183 100644
--- a/internal-packages/testcontainers/src/sequencer.cjs
+++ b/internal-packages/testcontainers/src/sequencer.cjs
@@ -56,8 +56,15 @@ function median(nums) {
 // It's a rotation of the bin->shard mapping, so coverage stays exact (each file runs once).
 function packageOffset(specs, count) {
   if (specs.length === 0) return 0;
-  const rel = path.relative(REPO_ROOT, specs[0].moduleId);
-  const key = rel.split(path.sep).slice(0, 2).join("/");
+  const keys = new Set(
+    specs.map((spec) =>
+      path.relative(REPO_ROOT, spec.moduleId).split(path.sep).slice(0, 2).join("/")
+    )
+  );
+  // A multi-project run is already balanced globally. Its mapping must not depend
+  // on which package happened to finish discovering files first.
+  if (keys.size !== 1) return 0;
+  const [key] = keys;
   // FNV-1a - spreads similar sibling package names (e.g. internal-packages/*) far better than a
   // simple polynomial hash mod count, which collided run-engine + schedule-engine onto one shard.
   let h = 2166136261;
diff --git a/internal-packages/testcontainers/src/sequencer.test.ts b/internal-packages/testcontainers/src/sequencer.test.ts
new file mode 100644
index 00000000000..1ddc3ea7895
--- /dev/null
+++ b/internal-packages/testcontainers/src/sequencer.test.ts
@@ -0,0 +1,48 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, test } from "vitest";
+import type { TestSpecification, Vitest } from "vitest/node";
+import { DurationShardingSequencer } from "./sequencer.cjs";
+
+const root = resolve(__dirname, "../../..");
+const timings: Record<string, number> = JSON.parse(
+  readFileSync(resolve(root, "test-timings.json"), "utf8")
+);
+const paths = Object.keys(timings).filter((file) => file.startsWith("internal-packages/"));
+// Sequencing only consumes moduleId; these are inputs to the scheduling algorithm.
+const specs = [...paths, "internal-packages/new-package/src/new.test.ts"].map(
+  (file) => ({ moduleId: resolve(root, file) }) as TestSpecification
+);
+
+function sequencer(index: number, count: number) {
+  return new DurationShardingSequencer({ config: { shard: { index, count } } } as Vitest);
+}
+
+describe("multi-project duration sharding", () => {
+  test.each([1, 2, 3, 12, 24])(
+    "assigns every file exactly once across %i shards",
+    async (count) => {
+      const shards = await Promise.all(
+        Array.from({ length: count }, (_, index) => sequencer(index + 1, count).shard(specs))
+      );
+      const assigned = shards.flat().map((spec) => spec.moduleId);
+      expect(assigned).toHaveLength(specs.length);
+      expect(new Set(assigned).size).toBe(specs.length);
+      expect(assigned.sort()).toEqual(specs.map((spec) => spec.moduleId).sort());
+    }
+  );
+
+  test("keeps the same assignment when project discovery order changes", async () => {
+    for (let index = 1; index <= 12; index++) {
+      const original = await sequencer(index, 12).shard(specs);
+      const reversed = await sequencer(index, 12).shard([...specs].reverse());
+      expect(reversed.map((spec) => spec.moduleId)).toEqual(original.map((spec) => spec.moduleId));
+    }
+  });
+
+  test("retains all files without sharding and accepts an empty project", async () => {
+    const unsharded = new DurationShardingSequencer({ config: {} } as Vitest);
+    expect(await unsharded.shard(specs)).toBe(specs);
+    expect(await sequencer(1, 12).shard([])).toEqual([]);
+  });
+});
diff --git a/internal-packages/testcontainers/src/test-timings.test.ts b/internal-packages/testcontainers/src/test-timings.test.ts
new file mode 100644
index 00000000000..ea929ba3aa8
--- /dev/null
+++ b/internal-packages/testcontainers/src/test-timings.test.ts
@@ -0,0 +1,102 @@
+import { describe, expect, test } from "vitest";
+import type { JsonTestResult } from "vitest/reporters";
+import { updateTestTimings } from "./test-timings.js";
+
+const file = "internal-packages/example/src/example.test.ts";
+function result(name = `/home/runner/work/repo/repo/${file}`): JsonTestResult {
+  return {
+    name,
+    status: "passed",
+    startTime: 1000,
+    endTime: 1250,
+    message: "",
+    assertionResults: [
+      {
+        ancestorTitles: [],
+        fullName: "example",
+        title: "example",
+        status: "passed",
+        failureMessages: [],
+        meta: {},
+        tags: [],
+      },
+    ],
+  };
+}
+function report(...results: JsonTestResult[]) {
+  return {
+    success: true,
+    numFailedTests: 0,
+    numFailedTestSuites: 0,
+    numTotalTests: results.reduce((sum, file) => sum + file.assertionResults.length, 0),
+    testResults: results,
+  };
+}
+
+describe("weekly internal test timings", () => {
+  test("normalizes runner paths and preserves unmeasured and non-internal files", () => {
+    const previous = { [file]: 500, "apps/webapp/other.test.ts": 800, "old.test.ts": 30 };
+    const next = updateTestTimings(previous, report(result()));
+    expect(next).toEqual({ ...previous, [file]: 250 });
+    expect(previous[file]).toBe(500);
+    expect(
+      updateTestTimings({}, report(result(`D:\\runner\\${file.replaceAll("/", "\\")}`)))
+    ).toEqual({
+      [file]: 250,
+    });
+  });
+
+  test("keeps timings for skipped files and records a positive duration for fast tests", () => {
+    const skipped = result("internal-packages/example/skipped.test.ts");
+    skipped.assertionResults[0]!.status = "pending";
+    const fast = result();
+    fast.endTime = fast.startTime;
+    expect(updateTestTimings({ [skipped.name]: 900 }, report(skipped, fast))).toEqual({
+      [skipped.name]: 900,
+      [file]: 1,
+    });
+  });
+
+  test("rejects failed, empty and truncated reports without changing stored timings", () => {
+    const previous = { [file]: 500 };
+    for (const invalid of [
+      report(),
+      { ...report(result()), success: false },
+      { ...report(result()), numFailedTests: 1 },
+      { ...report(result()), numFailedTestSuites: 1 },
+      { ...report(result()), numTotalTests: 2 },
+    ]) {
+      expect(() => updateTestTimings(previous, invalid)).toThrow(/complete, successful/);
+    }
+    expect(previous).toEqual({ [file]: 500 });
+  });
+
+  test("rejects overlapping shards even with different runner checkout paths", () => {
+    expect(() => updateTestTimings({}, report(result(), result(`/other/runner/${file}`)))).toThrow(
+      /Duplicate test file/
+    );
+  });
+
+  test.each(["apps/webapp/example.test.ts", "internal-packages/../example.test.ts"])(
+    "rejects unexpected path %s",
+    (path) => expect(() => updateTestTimings({}, report(result(path)))).toThrow(/Unexpected/)
+  );
+
+  test.each([-1, Number.NaN, Number.POSITIVE_INFINITY])(
+    "rejects invalid duration %s",
+    (duration) => {
+      const invalid = result();
+      invalid.endTime = invalid.startTime + duration;
+      expect(() => updateTestTimings({}, report(invalid))).toThrow(/Invalid test duration/);
+    }
+  );
+
+  test("rejects failed files and reports containing only skipped tests", () => {
+    const invalid = result();
+    invalid.status = "failed";
+    expect(() => updateTestTimings({}, report(invalid))).toThrow(/failed test file/);
+    invalid.status = "passed";
+    invalid.assertionResults[0]!.status = "pending";
+    expect(() => updateTestTimings({}, report(invalid))).toThrow(/No internal test timings/);
+  });
+});
diff --git a/internal-packages/testcontainers/src/test-timings.ts b/internal-packages/testcontainers/src/test-timings.ts
new file mode 100644
index 00000000000..3d987b60d1f
--- /dev/null
+++ b/internal-packages/testcontainers/src/test-timings.ts
@@ -0,0 +1,54 @@
+import type { JsonTestResults } from "vitest/reporters";
+
+type TimingReport = Pick<
+  JsonTestResults,
+  "success" | "numFailedTests" | "numFailedTestSuites" | "numTotalTests" | "testResults"
+>;
+
+/** Refresh only measured internal files; keep other suites and skipped files unchanged. */
+export function updateTestTimings(
+  previous: Record<string, number>,
+  report: TimingReport
+): Record<string, number> {
+  if (
+    report.success !== true ||
+    report.numFailedTests !== 0 ||
+    report.numFailedTestSuites !== 0 ||
+    !(report.numTotalTests > 0) ||
+    !Array.isArray(report.testResults) ||
+    report.testResults.reduce((sum, file) => sum + file.assertionResults.length, 0) !==
+      report.numTotalTests
+  ) {
+    throw new Error("Timings require a complete, successful internal test report");
+  }
+
+  const updated = { ...previous };
+  const seen = new Set<string>();
+  let measured = 0;
+  for (const result of report.testResults) {
+    // CI runners have different checkout prefixes. Store only monorepo-relative paths.
+    const file = result.name.replaceAll("\\", "/").match(/(?:^|\/)(internal-packages\/.+)$/)?.[1];
+    if (!file || file.split("/").some((part) => part === ".." || part === ".")) {
+      throw new Error(`Unexpected internal test path: ${result.name}`);
+    }
+    if (seen.has(file)) {
+      throw new Error(`Duplicate test file in shard reports: ${file}`);
+    }
+    seen.add(file);
+    if (
+      result.status !== "passed" ||
+      result.assertionResults.some((test) => test.status === "failed")
+    ) {
+      throw new Error(`Cannot record failed test file: ${file}`);
+    }
+    if (!result.assertionResults.some((test) => test.status === "passed")) continue;
+    const duration = result.endTime - result.startTime;
+    if (!Number.isFinite(duration) || duration < 0) {
+      throw new Error(`Invalid test duration for ${file}`);
+    }
+    updated[file] = Math.max(1, Math.round(duration));
+    measured++;
+  }
+  if (measured === 0) throw new Error("No internal test timings were measured");
+  return updated;
+}
diff --git a/internal-test-projects.mts b/internal-test-projects.mts
new file mode 100644
index 00000000000..7758a925733
--- /dev/null
+++ b/internal-test-projects.mts
@@ -0,0 +1,37 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export function getInternalTestProjects(monorepoRoot: string) {
+  return readdirSync(resolve(monorepoRoot, "internal-packages"))
+    .sort()
+    .flatMap((directory) => {
+      const root = resolve(monorepoRoot, "internal-packages", directory);
+      const manifestPath = resolve(root, "package.json");
+      if (!existsSync(manifestPath)) return [];
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+      if (!manifest.name?.startsWith("@internal/") || !manifest.scripts?.test) return [];
+      // Keep custom test commands from being bypassed if a package changes later.
+      if (
+        !/^vitest(?: run)?(?: --sequence.concurrent=false)?(?: --no-file-parallelism)?$/.test(
+          manifest.scripts.test
+        )
+      ) {
+        throw new Error(`Unsupported test command for ${manifest.name}: ${manifest.scripts.test}`);
+      }
+      return [{ root, name: manifest.name as string }];
+    });
+}
+
+// Report replay needs the same names and roots to reconstruct Vitest's test IDs.
+// Inline projects avoid loading package configs or installing workspace dependencies.
+export function getInternalTestReportConfig(monorepoRoot: string) {
+  return {
+    test: {
+      projects: getInternalTestProjects(monorepoRoot).map(({ root, name }) => ({
+        extends: false as const,
+        configFile: false as const,
+        test: { root, name },
+      })),
+    },
+  };
+}
diff --git a/knip.json b/knip.json
index 4221a927c2d..fb75544f4d9 100644
--- a/knip.json
+++ b/knip.json
@@ -3,7 +3,11 @@
   "tags": ["-knipignore"],
   "workspaces": {
     ".": {
-      "entry": ["scripts/**/*.{js,mjs,cjs,ts,mts,cts}"],
+      "entry": [
+        "scripts/**/*.{js,mjs,cjs,ts,mts,cts}",
+        "vitest.internal.config.ts",
+        "vitest.internal-reports.config.mjs"
+      ],
       "ignoreDependencies": ["agentcrumbs", "eslint", "lefthook"],
       "ignoreBinaries": ["infisical", "prisma"]
     },
diff --git a/test-timings.json b/test-timings.json
index 9852da212ee..867cbfa6a80 100644
--- a/test-timings.json
+++ b/test-timings.json
@@ -537,139 +537,356 @@
   "apps/webapp/test/workloadTokenAuthorization.test.ts": 2,
   "apps/webapp/test/workloadTokenGate.integration.test.ts": 2681,
   "apps/webapp/test/writableEnvironments.test.ts": 3,
-  "internal-packages/cache/src/stores/lruMemory.test.ts": 65,
-  "internal-packages/clickhouse/src/client/client.test.ts": 7547,
-  "internal-packages/clickhouse/src/taskRuns.test.ts": 6768,
-  "internal-packages/clickhouse/src/tsql.test.ts": 8254,
-  "internal-packages/clickhouse/src/tsqlFunctions.test.ts": 9360,
-  "internal-packages/dashboard-agent/src/dashboard-agent.test.ts": 1429,
-  "internal-packages/dashboard-agent/src/repo-tools.test.ts": 116,
-  "internal-packages/llm-model-catalog/src/registry.test.ts": 84,
-  "internal-packages/llm-model-catalog/src/sync.test.ts": 3585,
+  "internal-packages/cache/src/stores/lruMemory.test.ts": 24,
+  "internal-packages/clickhouse/src/client/client.test.ts": 9068,
+  "internal-packages/clickhouse/src/client/errors.test.ts": 4,
+  "internal-packages/clickhouse/src/queueMetrics.test.ts": 8063,
+  "internal-packages/clickhouse/src/taskEvents.test.ts": 6750,
+  "internal-packages/clickhouse/src/taskEventsSearch.test.ts": 7351,
+  "internal-packages/clickhouse/src/taskRuns.test.ts": 8409,
+  "internal-packages/clickhouse/src/tsql.test.ts": 16692,
+  "internal-packages/clickhouse/src/tsqlFunctions.test.ts": 12420,
+  "internal-packages/dashboard-agent-contracts/src/blocks.test.ts": 46,
+  "internal-packages/dashboard-agent-contracts/src/contracts.test.ts": 15,
+  "internal-packages/dashboard-agent-contracts/src/trigger-uri.test.ts": 9,
+  "internal-packages/dashboard-agent-contracts/src/watch.test.ts": 20,
+  "internal-packages/dashboard-agent-contracts/src/well-formed.test.ts": 5,
+  "internal-packages/dashboard-agent/src/cache-breakpoint.test.ts": 4,
+  "internal-packages/dashboard-agent/src/compaction.test.ts": 148,
+  "internal-packages/dashboard-agent/src/dashboard-agent.test.ts": 1059,
+  "internal-packages/dashboard-agent/src/eval-error-category.test.ts": 8,
+  "internal-packages/dashboard-agent/src/eval-redaction.test.ts": 6,
+  "internal-packages/dashboard-agent/src/investigation-sweep.test.ts": 14411,
+  "internal-packages/dashboard-agent/src/linkify-agent-text.test.ts": 6,
+  "internal-packages/dashboard-agent/src/maintenance.test.ts": 11122,
+  "internal-packages/dashboard-agent/src/model-provider.test.ts": 7,
+  "internal-packages/dashboard-agent/src/prompt-prefix.test.ts": 27,
+  "internal-packages/dashboard-agent/src/repo-tools.test.ts": 33,
+  "internal-packages/dashboard-agent/src/step-cache.test.ts": 6,
+  "internal-packages/dashboard-agent/src/tool-api-branch.test.ts": 16,
+  "internal-packages/dashboard-agent/src/tool-api-cross-project.test.ts": 79,
+  "internal-packages/dashboard-agent/src/tool-api-paths.test.ts": 12,
+  "internal-packages/dashboard-agent/src/tool-api-transport.test.ts": 9,
+  "internal-packages/dashboard-agent/src/tool-ask-support.test.ts": 5,
+  "internal-packages/dashboard-agent/src/tool-curation.test.ts": 13,
+  "internal-packages/dashboard-agent/src/tool-docs.test.ts": 3,
+  "internal-packages/dashboard-agent/src/tool-evidence.test.ts": 5,
+  "internal-packages/dashboard-agent/src/tool-locate.test.ts": 21,
+  "internal-packages/dashboard-agent/src/tool-query-retry-cap.test.ts": 3,
+  "internal-packages/dashboard-agent/src/tool-queue.test.ts": 18,
+  "internal-packages/dashboard-agent/src/transcript-storage.test.ts": 7088,
+  "internal-packages/dashboard-agent/src/watch-actions.test.ts": 673,
+  "internal-packages/dashboard-agent/src/watch-narration.test.ts": 4,
+  "internal-packages/dashboard-agent/src/watch-tick.test.ts": 34,
+  "internal-packages/dashboard-agent/src/watch-tools.test.ts": 5,
+  "internal-packages/llm-model-catalog/src/registry.test.ts": 10,
+  "internal-packages/llm-model-catalog/src/sync.test.ts": 7307,
+  "internal-packages/metrics-pipeline/src/consumer.test.ts": 1521,
+  "internal-packages/metrics-pipeline/src/pipeline.test.ts": 5,
+  "internal-packages/observability-map/src/adapters/remix.test.ts": 3,
+  "internal-packages/observability-map/src/checks/index.test.ts": 94,
+  "internal-packages/observability-map/src/cli.test.ts": 524,
+  "internal-packages/observability-map/src/docstringReferences.test.ts": 66,
+  "internal-packages/observability-map/src/integration.test.ts": 8037,
+  "internal-packages/observability-map/src/mutationCorpus.test.ts": 5,
+  "internal-packages/observability-map/src/mutationTrivia.test.ts": 50,
+  "internal-packages/observability-map/src/report/prComment.test.ts": 322,
+  "internal-packages/observability-map/src/report/prCommentCli.test.ts": 9,
+  "internal-packages/observability-map/src/report/terminal.test.ts": 130,
+  "internal-packages/observability-map/src/scan.test.ts": 140,
+  "internal-packages/observability-map/src/score.test.ts": 52,
+  "internal-packages/observability-map/src/sensitivity.test.ts": 32,
+  "internal-packages/observability-map/src/suppression.test.ts": 26,
+  "internal-packages/observability-map/src/triviality.test.ts": 43,
+  "internal-packages/observability-map/src/webappSymbols.test.ts": 13,
   "internal-packages/rbac/src/ability.test.ts": 55,
   "internal-packages/rbac/src/loader.test.ts": 77,
   "internal-packages/rbac/src/require-plugins.test.ts": 84,
-  "internal-packages/replication/src/client.test.ts": 33067,
-  "internal-packages/run-engine/src/batch-queue/tests/index.test.ts": 4370,
-  "internal-packages/run-engine/src/engine/systems/batchSystem.test.ts": 35042,
-  "internal-packages/run-engine/src/engine/systems/debounceSystem.test.ts": 14129,
-  "internal-packages/run-engine/src/engine/systems/delayedRunSystem.test.ts": 12805,
-  "internal-packages/run-engine/src/engine/systems/enqueueSystem.test.ts": 9585,
-  "internal-packages/run-engine/src/engine/systems/executionSnapshotSystem.test.ts": 12815,
-  "internal-packages/run-engine/src/engine/systems/pendingVersionSystem.test.ts": 12791,
-  "internal-packages/run-engine/src/engine/systems/runAttemptSystem.test.ts": 17101,
-  "internal-packages/run-engine/src/engine/systems/ttlSystem.test.ts": 12916,
-  "internal-packages/run-engine/src/engine/systems/waitpointSystem.test.ts": 31249,
-  "internal-packages/run-engine/src/engine/tests/attemptFailures.test.ts": 14624,
-  "internal-packages/run-engine/src/engine/tests/batchTrigger.test.ts": 17248,
-  "internal-packages/run-engine/src/engine/tests/batchTriggerAndWait.test.ts": 19939,
-  "internal-packages/run-engine/src/engine/tests/batchTwoPhase.test.ts": 13594,
-  "internal-packages/run-engine/src/engine/tests/blockEdgeResidency.test.ts": 6962,
-  "internal-packages/run-engine/src/engine/tests/cancelling.test.ts": 11125,
-  "internal-packages/run-engine/src/engine/tests/checkpointSystem.controlPlaneResolver.test.ts": 12189,
-  "internal-packages/run-engine/src/engine/tests/checkpointSystemStore.test.ts": 15100,
-  "internal-packages/run-engine/src/engine/tests/checkpoints.test.ts": 19226,
-  "internal-packages/run-engine/src/engine/tests/clearBlockingWaitpointsResidency.test.ts": 6030,
-  "internal-packages/run-engine/src/engine/tests/completeWaitpointCrossSeamGuard.test.ts": 9881,
-  "internal-packages/run-engine/src/engine/tests/completeWaitpointReadResidency.test.ts": 7270,
-  "internal-packages/run-engine/src/engine/tests/controlPlaneResolverInjectability.test.ts": 9790,
-  "internal-packages/run-engine/src/engine/tests/createCancelledRun.test.ts": 10516,
-  "internal-packages/run-engine/src/engine/tests/createFailedTaskRun.test.ts": 8961,
-  "internal-packages/run-engine/src/engine/tests/crossVersionCompat.test.ts": 6563,
-  "internal-packages/run-engine/src/engine/tests/datetimeWaitpointColocation.test.ts": 10600,
-  "internal-packages/run-engine/src/engine/tests/debounce.test.ts": 31044,
-  "internal-packages/run-engine/src/engine/tests/delayedRunSystem.controlPlaneResolver.test.ts": 12846,
-  "internal-packages/run-engine/src/engine/tests/delays.test.ts": 32798,
-  "internal-packages/run-engine/src/engine/tests/dequeueSystem.controlPlaneResolver.test.ts": 13496,
-  "internal-packages/run-engine/src/engine/tests/dequeueSystem.recovery.controlPlaneResolver.test.ts": 4805,
-  "internal-packages/run-engine/src/engine/tests/dequeuing.test.ts": 15045,
-  "internal-packages/run-engine/src/engine/tests/engineResidualInversions.controlPlaneResolver.test.ts": 5341,
-  "internal-packages/run-engine/src/engine/tests/getSnapshotsSince.test.ts": 222657,
-  "internal-packages/run-engine/src/engine/tests/getSnapshotsSinceResidency.test.ts": 5582,
-  "internal-packages/run-engine/src/engine/tests/heartbeats.test.ts": 29022,
-  "internal-packages/run-engine/src/engine/tests/heteroPostgresFixture.test.ts": 5790,
-  "internal-packages/run-engine/src/engine/tests/lazyWaitpoint.test.ts": 20398,
-  "internal-packages/run-engine/src/engine/tests/legacyRunNewTokenResumeFlow.test.ts": 6757,
-  "internal-packages/run-engine/src/engine/tests/lifecycleRouter.test.ts": 16360,
-  "internal-packages/run-engine/src/engine/tests/locking.test.ts": 50934,
-  "internal-packages/run-engine/src/engine/tests/pendingVersion.test.ts": 13218,
-  "internal-packages/run-engine/src/engine/tests/priority.test.ts": 11463,
-  "internal-packages/run-engine/src/engine/tests/runAttemptSystem.controlPlaneResolver.test.ts": 15028,
-  "internal-packages/run-engine/src/engine/tests/runStoreInjectability.test.ts": 9726,
-  "internal-packages/run-engine/src/engine/tests/startRunAttemptReadResidency.test.ts": 6902,
-  "internal-packages/run-engine/src/engine/tests/trigger.test.ts": 10838,
-  "internal-packages/run-engine/src/engine/tests/triggerAndWait.test.ts": 14414,
-  "internal-packages/run-engine/src/engine/tests/triggerCreateRouting.test.ts": 13971,
-  "internal-packages/run-engine/src/engine/tests/ttl.test.ts": 51947,
-  "internal-packages/run-engine/src/engine/tests/waitpointPublicRouter.test.ts": 14940,
-  "internal-packages/run-engine/src/engine/tests/waitpointRace.test.ts": 10633,
-  "internal-packages/run-engine/src/engine/tests/waitpointReplicaLag.test.ts": 5858,
-  "internal-packages/run-engine/src/engine/tests/waitpointSystem.controlPlaneResolver.test.ts": 11913,
-  "internal-packages/run-engine/src/engine/tests/waitpoints.test.ts": 29161,
-  "internal-packages/run-engine/src/engine/tests/workerQueueObservation.test.ts": 8582,
-  "internal-packages/run-engine/src/run-queue/index.test.ts": 82145,
-  "internal-packages/run-engine/src/run-queue/tests/ack.test.ts": 2823,
-  "internal-packages/run-engine/src/run-queue/tests/ckCounters.test.ts": 15673,
-  "internal-packages/run-engine/src/run-queue/tests/ckIndex.test.ts": 8611,
-  "internal-packages/run-engine/src/run-queue/tests/concurrencySweeper.test.ts": 6162,
-  "internal-packages/run-engine/src/run-queue/tests/dequeueMessageFromWorkerQueue.test.ts": 67581,
-  "internal-packages/run-engine/src/run-queue/tests/enqueueMessage.test.ts": 8763,
-  "internal-packages/run-engine/src/run-queue/tests/fairQueueSelectionStrategy.test.ts": 3513,
-  "internal-packages/run-engine/src/run-queue/tests/keyProducer.test.ts": 80,
-  "internal-packages/run-engine/src/run-queue/tests/migrateLegacyMasterQueue.test.ts": 1609,
-  "internal-packages/run-engine/src/run-queue/tests/nack.test.ts": 5927,
-  "internal-packages/run-engine/src/run-queue/tests/releaseConcurrency.test.ts": 2649,
-  "internal-packages/run-engine/src/run-queue/tests/workerQueueResolver.test.ts": 239,
-  "internal-packages/run-ops-database/prisma/schema.parity.test.ts": 43,
-  "internal-packages/run-store/src/PostgresRunStore.batchProbeReadClient.test.ts": 6303,
-  "internal-packages/run-store/src/PostgresRunStore.connectedRunsBounded.test.ts": 5104,
-  "internal-packages/run-store/src/PostgresRunStore.connectedRunsIncludeBounded.test.ts": 2362,
-  "internal-packages/run-store/src/PostgresRunStore.controlPlaneAlertFk.test.ts": 4777,
-  "internal-packages/run-store/src/PostgresRunStore.crossGenerationError.test.ts": 2646,
-  "internal-packages/run-store/src/PostgresRunStore.dedicatedRepro.test.ts": 12323,
-  "internal-packages/run-store/src/PostgresRunStore.dedicatedSelect.test.ts": 5884,
-  "internal-packages/run-store/src/PostgresRunStore.dualSchema.test.ts": 5443,
-  "internal-packages/run-store/src/PostgresRunStore.findRunsByIds.test.ts": 2707,
-  "internal-packages/run-store/src/PostgresRunStore.groupedRelations.test.ts": 2561,
-  "internal-packages/run-store/src/PostgresRunStore.hydratorSelectPushdown.test.ts": 2428,
-  "internal-packages/run-store/src/PostgresRunStore.sharedHydratedTarget.test.ts": 2289,
-  "internal-packages/run-store/src/PostgresRunStore.test.ts": 11219,
-  "internal-packages/run-store/src/PostgresRunStore.writeAtomicity.test.ts": 7791,
-  "internal-packages/run-store/src/batchCompletionResidency.test.ts": 6379,
-  "internal-packages/run-store/src/checkpointBatchReplicaLag.test.ts": 2667,
-  "internal-packages/run-store/src/clientCompat.test.ts": 32,
-  "internal-packages/run-store/src/runOpsStore.batchItemMisroute.test.ts": 5285,
-  "internal-packages/run-store/src/runOpsStore.crossDbCompletedWaitpoint.test.ts": 4837,
-  "internal-packages/run-store/src/runOpsStore.crossDbTokenBlock.test.ts": 4787,
-  "internal-packages/run-store/src/runOpsStore.flipWindowDuplicate.test.ts": 4844,
-  "internal-packages/run-store/src/runOpsStore.forWaitpointCompletion.test.ts": 96,
-  "internal-packages/run-store/src/runOpsStore.groupedReads.test.ts": 5767,
-  "internal-packages/run-store/src/runOpsStore.idempotencyDedup.test.ts": 6729,
-  "internal-packages/run-store/src/runOpsStore.mixedResidency.test.ts": 9524,
-  "internal-packages/run-store/src/runOpsStore.readAfterWrite.test.ts": 5519,
+  "internal-packages/redis/src/cluster.test.ts": 5,
+  "internal-packages/redis/src/clusterFailFast.test.ts": 15,
+  "internal-packages/redis/src/failFast.test.ts": 3,
+  "internal-packages/replication/src/client.publicationMisconfigured.test.ts": 10106,
+  "internal-packages/replication/src/client.test.ts": 188847,
+  "internal-packages/run-engine/src/batch-queue/tests/index.test.ts": 5229,
+  "internal-packages/run-engine/src/engine/retryDecisionReadAfterWrite.replicaLag.test.ts": 7434,
+  "internal-packages/run-engine/src/engine/systems/batchSystem.test.ts": 54877,
+  "internal-packages/run-engine/src/engine/systems/completedWaitpointCycle.test.ts": 13868,
+  "internal-packages/run-engine/src/engine/systems/completedWaitpointFreeze.test.ts": 79,
+  "internal-packages/run-engine/src/engine/systems/completedWaitpointResolver.test.ts": 13428,
+  "internal-packages/run-engine/src/engine/systems/debounceSystem.test.ts": 24401,
+  "internal-packages/run-engine/src/engine/systems/delayedRunSystem.test.ts": 25383,
+  "internal-packages/run-engine/src/engine/systems/enqueueSystem.test.ts": 16576,
+  "internal-packages/run-engine/src/engine/systems/executionSnapshotSystem.test.ts": 23596,
+  "internal-packages/run-engine/src/engine/systems/pendingVersionSystem.test.ts": 22160,
+  "internal-packages/run-engine/src/engine/systems/redisPrimaryCompletionAssociation.test.ts": 14357,
+  "internal-packages/run-engine/src/engine/systems/runAttemptSystem.test.ts": 26338,
+  "internal-packages/run-engine/src/engine/systems/ttlSystem.test.ts": 23771,
+  "internal-packages/run-engine/src/engine/systems/ttlSystemExpireReplicaLag.guard.test.ts": 14302,
+  "internal-packages/run-engine/src/engine/systems/waitpointCompletionGuard.test.ts": 23869,
+  "internal-packages/run-engine/src/engine/systems/waitpointSystem.test.ts": 46823,
+  "internal-packages/run-engine/src/engine/tests/attemptFailures.test.ts": 24253,
+  "internal-packages/run-engine/src/engine/tests/batchTrigger.test.ts": 21893,
+  "internal-packages/run-engine/src/engine/tests/batchTriggerAndWait.test.ts": 27085,
+  "internal-packages/run-engine/src/engine/tests/batchTwoPhase.test.ts": 35023,
+  "internal-packages/run-engine/src/engine/tests/blockEdgeResidency.test.ts": 17053,
+  "internal-packages/run-engine/src/engine/tests/cancellationRouteFallback.test.ts": 14322,
+  "internal-packages/run-engine/src/engine/tests/cancelling.test.ts": 17930,
+  "internal-packages/run-engine/src/engine/tests/checkpointRouteFallback.test.ts": 13251,
+  "internal-packages/run-engine/src/engine/tests/checkpointSystem.controlPlaneResolver.test.ts": 21627,
+  "internal-packages/run-engine/src/engine/tests/checkpointSystemStore.test.ts": 24809,
+  "internal-packages/run-engine/src/engine/tests/checkpoints.test.ts": 27249,
+  "internal-packages/run-engine/src/engine/tests/childCancelRoute.test.ts": 15432,
+  "internal-packages/run-engine/src/engine/tests/clearBlockingWaitpointsResidency.test.ts": 14407,
+  "internal-packages/run-engine/src/engine/tests/completeWaitpointCrossSeamGuard.test.ts": 16383,
+  "internal-packages/run-engine/src/engine/tests/completeWaitpointErrorClassification.test.ts": 4,
+  "internal-packages/run-engine/src/engine/tests/completeWaitpointReadResidency.test.ts": 14543,
+  "internal-packages/run-engine/src/engine/tests/completionRouteFallback.test.ts": 21750,
+  "internal-packages/run-engine/src/engine/tests/concurrencySweeperCallbackReplicaLag.guard.test.ts": 14663,
+  "internal-packages/run-engine/src/engine/tests/continueRunIfUnblockedNoopRoute.test.ts": 14408,
+  "internal-packages/run-engine/src/engine/tests/continueRunIfUnblockedRecordFetch.test.ts": 18044,
+  "internal-packages/run-engine/src/engine/tests/controlPlaneResolverInjectability.test.ts": 16602,
+  "internal-packages/run-engine/src/engine/tests/createCancelledRun.test.ts": 17473,
+  "internal-packages/run-engine/src/engine/tests/createFailedTaskRun.test.ts": 14684,
+  "internal-packages/run-engine/src/engine/tests/crossVersionCompat.test.ts": 14743,
+  "internal-packages/run-engine/src/engine/tests/datetimeWaitpointColocation.test.ts": 24457,
+  "internal-packages/run-engine/src/engine/tests/debounce.test.ts": 50104,
+  "internal-packages/run-engine/src/engine/tests/delayedRunSystem.controlPlaneResolver.test.ts": 23666,
+  "internal-packages/run-engine/src/engine/tests/delays.test.ts": 36771,
+  "internal-packages/run-engine/src/engine/tests/deletedProject.test.ts": 45774,
+  "internal-packages/run-engine/src/engine/tests/dequeueRouteLessRecovery.test.ts": 17277,
+  "internal-packages/run-engine/src/engine/tests/dequeueSystem.controlPlaneResolver.test.ts": 23613,
+  "internal-packages/run-engine/src/engine/tests/dequeueSystem.recovery.controlPlaneResolver.test.ts": 12628,
+  "internal-packages/run-engine/src/engine/tests/dequeuing.test.ts": 20998,
+  "internal-packages/run-engine/src/engine/tests/engineResidualInversions.controlPlaneResolver.test.ts": 14267,
+  "internal-packages/run-engine/src/engine/tests/engineStrictShutdown.test.ts": 14676,
+  "internal-packages/run-engine/src/engine/tests/ensureRunFinalized.test.ts": 59180,
+  "internal-packages/run-engine/src/engine/tests/executionLifecycleExpiryRoute.test.ts": 17002,
+  "internal-packages/run-engine/src/engine/tests/executionLifecycleSnapshotRoute.test.ts": 17218,
+  "internal-packages/run-engine/src/engine/tests/externalDeploymentParking.test.ts": 27298,
+  "internal-packages/run-engine/src/engine/tests/getSnapshotsSince.test.ts": 32641,
+  "internal-packages/run-engine/src/engine/tests/getSnapshotsSinceResidency.test.ts": 12561,
+  "internal-packages/run-engine/src/engine/tests/heartbeats.test.ts": 36211,
+  "internal-packages/run-engine/src/engine/tests/heteroPostgresFixture.test.ts": 11980,
+  "internal-packages/run-engine/src/engine/tests/initialTriggerSnapshotRoute.test.ts": 16656,
+  "internal-packages/run-engine/src/engine/tests/lazyWaitpoint.test.ts": 26936,
+  "internal-packages/run-engine/src/engine/tests/legacyRunNewTokenResumeFlow.test.ts": 12720,
+  "internal-packages/run-engine/src/engine/tests/lifecycleRouter.test.ts": 27752,
+  "internal-packages/run-engine/src/engine/tests/locking.test.ts": 51306,
+  "internal-packages/run-engine/src/engine/tests/pendingVersion.test.ts": 19639,
+  "internal-packages/run-engine/src/engine/tests/priority.test.ts": 17772,
+  "internal-packages/run-engine/src/engine/tests/queuePollLagSnapshotRoute.test.ts": 16149,
+  "internal-packages/run-engine/src/engine/tests/runAttemptSystem.controlPlaneResolver.test.ts": 24740,
+  "internal-packages/run-engine/src/engine/tests/runAttemptSystemReplicaLag.guard.test.ts": 21823,
+  "internal-packages/run-engine/src/engine/tests/runStoreInjectability.test.ts": 16519,
+  "internal-packages/run-engine/src/engine/tests/setRunStore.test.ts": 15185,
+  "internal-packages/run-engine/src/engine/tests/shutdown.test.ts": 8773,
+  "internal-packages/run-engine/src/engine/tests/snapshotRepairBinding.test.ts": 15000,
+  "internal-packages/run-engine/src/engine/tests/startRunAttemptReadResidency.test.ts": 11057,
+  "internal-packages/run-engine/src/engine/tests/startRunAttemptSnapshotRoute.test.ts": 14448,
+  "internal-packages/run-engine/src/engine/tests/systemFailureRoute.test.ts": 13579,
+  "internal-packages/run-engine/src/engine/tests/trigger.test.ts": 18235,
+  "internal-packages/run-engine/src/engine/tests/triggerAndWait.test.ts": 22348,
+  "internal-packages/run-engine/src/engine/tests/triggerCreateRouting.test.ts": 22236,
+  "internal-packages/run-engine/src/engine/tests/triggerSnapshotCollapse.test.ts": 20509,
+  "internal-packages/run-engine/src/engine/tests/ttl.test.ts": 59940,
+  "internal-packages/run-engine/src/engine/tests/ttlBatchExpiryRoute.test.ts": 20932,
+  "internal-packages/run-engine/src/engine/tests/ttlNackRequeue.test.ts": 23306,
+  "internal-packages/run-engine/src/engine/tests/waitpointCoordinatorStoreSwap.test.ts": 15180,
+  "internal-packages/run-engine/src/engine/tests/waitpointFanoutDisabled.test.ts": 16344,
+  "internal-packages/run-engine/src/engine/tests/waitpointPublicRouter.test.ts": 22549,
+  "internal-packages/run-engine/src/engine/tests/waitpointRace.test.ts": 16383,
+  "internal-packages/run-engine/src/engine/tests/waitpointReplicaLag.test.ts": 13108,
+  "internal-packages/run-engine/src/engine/tests/waitpointRouteFallback.test.ts": 15618,
+  "internal-packages/run-engine/src/engine/tests/waitpointSystem.controlPlaneResolver.test.ts": 21377,
+  "internal-packages/run-engine/src/engine/tests/waitpoints.test.ts": 35226,
+  "internal-packages/run-engine/src/engine/tests/workerQueueObservation.test.ts": 16406,
+  "internal-packages/run-engine/src/engine/waitpointCoordinator/fanoutPolicy.test.ts": 11,
+  "internal-packages/run-engine/src/engine/waitpointCoordinator/fanoutWorker.test.ts": 3413,
+  "internal-packages/run-engine/src/engine/waitpointCoordinator/keys.test.ts": 62,
+  "internal-packages/run-engine/src/engine/waitpointCoordinator/storeCoordinator.test.ts": 3357,
+  "internal-packages/run-engine/src/engine/waitpointCoordinator/waitpointMint.proof.test.ts": 19,
+  "internal-packages/run-engine/src/engine/waitpointCoordinator/waitpointMintSites.test.ts": 5,
+  "internal-packages/run-engine/src/engine/workerPayloads.test.ts": 6,
+  "internal-packages/run-engine/src/run-queue/index.test.ts": 83586,
+  "internal-packages/run-engine/src/run-queue/metrics.test.ts": 6063,
+  "internal-packages/run-engine/src/run-queue/tests/ack.test.ts": 2584,
+  "internal-packages/run-engine/src/run-queue/tests/ckCounters.test.ts": 15589,
+  "internal-packages/run-engine/src/run-queue/tests/ckIndex.test.ts": 9607,
+  "internal-packages/run-engine/src/run-queue/tests/ckWildcardKey.test.ts": 605,
+  "internal-packages/run-engine/src/run-queue/tests/concurrencySweeper.test.ts": 6168,
+  "internal-packages/run-engine/src/run-queue/tests/dequeueMessageFromWorkerQueue.test.ts": 67119,
+  "internal-packages/run-engine/src/run-queue/tests/enqueueMessage.test.ts": 10073,
+  "internal-packages/run-engine/src/run-queue/tests/fairQueueSelectionStrategy.test.ts": 2877,
+  "internal-packages/run-engine/src/run-queue/tests/keyProducer.test.ts": 10,
+  "internal-packages/run-engine/src/run-queue/tests/migrateLegacyMasterQueue.test.ts": 1452,
+  "internal-packages/run-engine/src/run-queue/tests/mixedVersionSnapshotRoute.test.ts": 6,
+  "internal-packages/run-engine/src/run-queue/tests/nack.test.ts": 8048,
+  "internal-packages/run-engine/src/run-queue/tests/nackRoute.test.ts": 1613,
+  "internal-packages/run-engine/src/run-queue/tests/releaseConcurrency.test.ts": 2793,
+  "internal-packages/run-engine/src/run-queue/tests/workerQueueResolver.test.ts": 27,
+  "internal-packages/run-ops-database/prisma/schema.parity.test.ts": 6,
+  "internal-packages/run-ops-database/src/schemaParity.test.ts": 6,
+  "internal-packages/run-store/src/PostgresRunStore.batchProbeReadClient.test.ts": 13977,
+  "internal-packages/run-store/src/PostgresRunStore.connectedRunsBounded.test.ts": 12445,
+  "internal-packages/run-store/src/PostgresRunStore.connectedRunsIncludeBounded.test.ts": 3472,
+  "internal-packages/run-store/src/PostgresRunStore.controlPlaneAlertFk.test.ts": 11911,
+  "internal-packages/run-store/src/PostgresRunStore.createRunNoTx.test.ts": 4681,
+  "internal-packages/run-store/src/PostgresRunStore.crossGenerationError.test.ts": 4998,
+  "internal-packages/run-store/src/PostgresRunStore.dedicatedRepro.test.ts": 30336,
+  "internal-packages/run-store/src/PostgresRunStore.dedicatedSelect.test.ts": 12689,
+  "internal-packages/run-store/src/PostgresRunStore.dualSchema.test.ts": 10948,
+  "internal-packages/run-store/src/PostgresRunStore.findRunsByIdempotencyKeys.test.ts": 8826,
+  "internal-packages/run-store/src/PostgresRunStore.findRunsByIds.test.ts": 7277,
+  "internal-packages/run-store/src/PostgresRunStore.groupedRelations.test.ts": 4182,
+  "internal-packages/run-store/src/PostgresRunStore.hydratorSelectPushdown.test.ts": 3409,
+  "internal-packages/run-store/src/PostgresRunStore.infraRetryBudget.test.ts": 8657,
+  "internal-packages/run-store/src/PostgresRunStore.sharedHydratedTarget.test.ts": 4459,
+  "internal-packages/run-store/src/PostgresRunStore.snapshotId.test.ts": 9127,
+  "internal-packages/run-store/src/PostgresRunStore.snapshotIdempotency.test.ts": 11456,
+  "internal-packages/run-store/src/PostgresRunStore.snapshotTimestamps.test.ts": 10187,
+  "internal-packages/run-store/src/PostgresRunStore.snapshotWriteBlipResilience.test.ts": 8708,
+  "internal-packages/run-store/src/PostgresRunStore.snapshotWrites.test.ts": 12462,
+  "internal-packages/run-store/src/PostgresRunStore.test.ts": 27233,
+  "internal-packages/run-store/src/PostgresRunStore.waitpointBlipResilience.test.ts": 10551,
+  "internal-packages/run-store/src/PostgresRunStore.writeAtomicity.test.ts": 22609,
+  "internal-packages/run-store/src/batchCompletionResidency.test.ts": 15168,
+  "internal-packages/run-store/src/checkpointBatchReplicaLag.test.ts": 7421,
+  "internal-packages/run-store/src/clientCompat.test.ts": 3,
+  "internal-packages/run-store/src/delegatingRunStore.forwarding.test.ts": 4,
+  "internal-packages/run-store/src/delegatingRunStore.test.ts": 5,
+  "internal-packages/run-store/src/pendingIndex.autoclaimCursor.test.ts": 796,
+  "internal-packages/run-store/src/pendingIndex.settle.test.ts": 739,
+  "internal-packages/run-store/src/pendingIndex.test.ts": 673,
+  "internal-packages/run-store/src/pendingRecoveryWorker.malformed.test.ts": 383,
+  "internal-packages/run-store/src/pendingRecoveryWorker.test.ts": 19620,
+  "internal-packages/run-store/src/placement.proof.test.ts": 37,
+  "internal-packages/run-store/src/redisSnapshotStore.finalizeBaseGuard.test.ts": 14020,
+  "internal-packages/run-store/src/redisSnapshotStore.gaps.test.ts": 457,
+  "internal-packages/run-store/src/redisSnapshotStore.namespaceMarker.test.ts": 623,
+  "internal-packages/run-store/src/redisSnapshotStore.outcomes.test.ts": 3,
+  "internal-packages/run-store/src/redisSnapshotStore.prepare.test.ts": 471,
+  "internal-packages/run-store/src/redisSnapshotStore.quarantineMove.test.ts": 388,
+  "internal-packages/run-store/src/redisSnapshotStore.readLiveness.test.ts": 460,
+  "internal-packages/run-store/src/redisSnapshotStore.recoveryLease.test.ts": 1857,
+  "internal-packages/run-store/src/redisSnapshotStore.residencyMarker.test.ts": 732,
+  "internal-packages/run-store/src/redisSnapshotStore.sinceCreatedAt.test.ts": 497,
+  "internal-packages/run-store/src/redisSnapshotStore.test.ts": 1653,
+  "internal-packages/run-store/src/runOpsStore.batchDependentAttemptReadView.replicaLag.test.ts": 14802,
+  "internal-packages/run-store/src/runOpsStore.batchIdempotencyDedupReadAfterWrite.test.ts": 12221,
+  "internal-packages/run-store/src/runOpsStore.batchItemMisroute.test.ts": 12314,
+  "internal-packages/run-store/src/runOpsStore.bulkActionReadView.replicaLag.test.ts": 11613,
+  "internal-packages/run-store/src/runOpsStore.cancelRunReadAfterWrite.replicaLag.test.ts": 11637,
+  "internal-packages/run-store/src/runOpsStore.crossDbCompletedWaitpoint.test.ts": 10587,
+  "internal-packages/run-store/src/runOpsStore.crossDbTokenBlock.test.ts": 11802,
+  "internal-packages/run-store/src/runOpsStore.dashboardAgentReadView.replicaLag.test.ts": 11785,
+  "internal-packages/run-store/src/runOpsStore.engineReadViews.replicaLag.test.ts": 11820,
+  "internal-packages/run-store/src/runOpsStore.envScopedResidency.test.ts": 7,
+  "internal-packages/run-store/src/runOpsStore.flipWindowDuplicate.test.ts": 10932,
+  "internal-packages/run-store/src/runOpsStore.forWaitpointCompletion.test.ts": 4,
+  "internal-packages/run-store/src/runOpsStore.groupedReads.test.ts": 13639,
+  "internal-packages/run-store/src/runOpsStore.idSetResidencyRouting.test.ts": 12697,
+  "internal-packages/run-store/src/runOpsStore.idempotencyDedup.test.ts": 13259,
+  "internal-packages/run-store/src/runOpsStore.idempotencyGlobalScopeCrossDb.test.ts": 12002,
+  "internal-packages/run-store/src/runOpsStore.idempotencyResetReadView.replicaLag.test.ts": 13570,
+  "internal-packages/run-store/src/runOpsStore.mixedResidency.test.ts": 18259,
+  "internal-packages/run-store/src/runOpsStore.modelRuntimeEnvReadView.replicaLag.test.ts": 12084,
+  "internal-packages/run-store/src/runOpsStore.nShardMatrix.test.ts": 28863,
+  "internal-packages/run-store/src/runOpsStore.newMethods.test.ts": 8,
+  "internal-packages/run-store/src/runOpsStore.presentersRunReadView.replicaLag.test.ts": 14864,
+  "internal-packages/run-store/src/runOpsStore.presentersSessionBatchReadView.replicaLag.test.ts": 14180,
+  "internal-packages/run-store/src/runOpsStore.presentersWaitpointReadView.replicaLag.test.ts": 17825,
+  "internal-packages/run-store/src/runOpsStore.readAfterWrite.test.ts": 11532,
+  "internal-packages/run-store/src/runOpsStore.realtimeServicesReadView.replicaLag.test.ts": 13730,
+  "internal-packages/run-store/src/runOpsStore.replayReadAfterWrite.replicaLag.test.ts": 11300,
   "internal-packages/run-store/src/runOpsStore.residencyMismatchFallback.test.ts": 5564,
-  "internal-packages/run-store/src/runOpsStore.routedReadPrimary.test.ts": 6475,
-  "internal-packages/run-store/src/runOpsStore.snapshotCompletedWaitpoints.test.ts": 4889,
-  "internal-packages/run-store/src/runOpsStore.snapshots.test.ts": 5938,
-  "internal-packages/run-store/src/runOpsStore.test.ts": 22578,
-  "internal-packages/run-store/src/runOpsStore.waitpoints.test.ts": 6504,
-  "internal-packages/run-store/src/scheduleSeam.test.ts": 5180,
-  "internal-packages/schedule-engine/test/scheduleEngine.test.ts": 125260,
-  "internal-packages/schedule-engine/test/scheduleEngine2.test.ts": 9011,
-  "internal-packages/schedule-engine/test/scheduleRecovery.test.ts": 10259,
-  "internal-packages/sdk-compat-tests/src/tests/bundler.test.ts": 170,
-  "internal-packages/sdk-compat-tests/src/tests/import.test.ts": 2455,
+  "internal-packages/run-store/src/runOpsStore.resolveRunForMutationReplicaLag.test.ts": 12994,
+  "internal-packages/run-store/src/runOpsStore.routedReadPrimary.test.ts": 16333,
+  "internal-packages/run-store/src/runOpsStore.routesBatchGetReadView.replicaLag.test.ts": 12837,
+  "internal-packages/run-store/src/runOpsStore.routesRealtimeStreamReadView.replicaLag.test.ts": 19189,
+  "internal-packages/run-store/src/runOpsStore.routesRunGetReadView.replicaLag.test.ts": 13949,
+  "internal-packages/run-store/src/runOpsStore.routesSpanTraceReadView.replicaLag.test.ts": 12114,
+  "internal-packages/run-store/src/runOpsStore.routingHydrationBlip.test.ts": 13163,
+  "internal-packages/run-store/src/runOpsStore.runKeyedRouting.test.ts": 9,
+  "internal-packages/run-store/src/runOpsStore.serviceBatchFamilyReadView.replicaLag.test.ts": 16640,
+  "internal-packages/run-store/src/runOpsStore.sessionMetadataRouteReadView.replicaLag.test.ts": 10451,
+  "internal-packages/run-store/src/runOpsStore.sessionRunProbeReadAfterWrite.test.ts": 11518,
+  "internal-packages/run-store/src/runOpsStore.shardMap.test.ts": 26,
+  "internal-packages/run-store/src/runOpsStore.snapshotCompletedWaitpoints.test.ts": 11704,
+  "internal-packages/run-store/src/runOpsStore.snapshots.test.ts": 12669,
+  "internal-packages/run-store/src/runOpsStore.standaloneWaitpointResidency.test.ts": 12754,
+  "internal-packages/run-store/src/runOpsStore.storeReceiverReadView.replicaLag.test.ts": 11587,
+  "internal-packages/run-store/src/runOpsStore.test.ts": 46795,
+  "internal-packages/run-store/src/runOpsStore.threeDbTopology.test.ts": 13900,
+  "internal-packages/run-store/src/runOpsStore.ttlExpireOrphanReplicaLag.test.ts": 11362,
+  "internal-packages/run-store/src/runOpsStore.usageCostUndercountReadAfterWrite.test.ts": 10750,
+  "internal-packages/run-store/src/runOpsStore.waitpointCompleteRouteAndReplayLoaderReadView.replicaLag.test.ts": 11217,
+  "internal-packages/run-store/src/runOpsStore.waitpointCompleteTokenReadAfterWrite.test.ts": 10736,
+  "internal-packages/run-store/src/runOpsStore.waitpointDedupReadAfterWrite.test.ts": 12161,
+  "internal-packages/run-store/src/runOpsStore.waitpoints.test.ts": 14067,
+  "internal-packages/run-store/src/scheduleSeam.test.ts": 13173,
+  "internal-packages/run-store/src/snapshotEntry.parity.test.ts": 13720,
+  "internal-packages/run-store/src/snapshotEntry.test.ts": 6,
+  "internal-packages/run-store/src/snapshotKeys.slots.test.ts": 9,
+  "internal-packages/run-store/src/snapshotKeys.test.ts": 56,
+  "internal-packages/run-store/src/snapshotResidency.test.ts": 3,
+  "internal-packages/run-store/src/snapshotResidencyResolver.test.ts": 934,
+  "internal-packages/run-store/src/snapshotStateVersion.test.ts": 449,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.allOps.test.ts": 26326,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.birthReadiness.test.ts": 15053,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.checkpointRestore.test.ts": 15274,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.dialResidency.test.ts": 17816,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.finalizeClassification.test.ts": 21964,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.forceDurableRoute.test.ts": 14100,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.foreignRunPostgres.test.ts": 14057,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.forkGuard.test.ts": 23146,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.gappedRead.test.ts": 13513,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.inTransaction.test.ts": 15256,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.inactivePerf.test.ts": 15474,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.lockWaitpointCycle.test.ts": 15728,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.metrics.test.ts": 14617,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.reads.test.ts": 14635,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.recovery.test.ts": 16175,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.redisOnly.test.ts": 16508,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.redisRead.test.ts": 16494,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.reproduceWindowDangling.test.ts": 15263,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.residencyDispatch.test.ts": 19302,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.route.test.ts": 16872,
+  "internal-packages/run-store/src/taskRunExecutionSnapshotStore.test.ts": 14510,
+  "internal-packages/schedule-engine/src/engine/scheduleCalculation.test.ts": 43,
+  "internal-packages/schedule-engine/src/engine/scheduleTiming.test.ts": 21,
+  "internal-packages/schedule-engine/src/engine/workerCatalog.test.ts": 4,
+  "internal-packages/schedule-engine/test/scheduleEngine.test.ts": 85230,
+  "internal-packages/schedule-engine/test/scheduleEngine2.test.ts": 15429,
+  "internal-packages/schedule-engine/test/scheduleRecovery.test.ts": 15708,
+  "internal-packages/sdk-compat-tests/src/tests/bundler.test.ts": 155,
+  "internal-packages/sdk-compat-tests/src/tests/import.test.ts": 1001,
   "internal-packages/sso/src/loader.test.ts": 61,
-  "internal-packages/tsql/src/grammar/parser.test.ts": 423,
-  "internal-packages/tsql/src/index.test.ts": 561,
-  "internal-packages/tsql/src/query/escape.test.ts": 50,
-  "internal-packages/tsql/src/query/parser.test.ts": 518,
-  "internal-packages/tsql/src/query/printer.test.ts": 872,
-  "internal-packages/tsql/src/query/results.test.ts": 59,
-  "internal-packages/tsql/src/query/schema.test.ts": 78,
-  "internal-packages/tsql/src/query/security.test.ts": 627,
-  "internal-packages/tsql/src/query/time_buckets.test.ts": 39,
-  "internal-packages/tsql/src/query/validator.test.ts": 557,
+  "internal-packages/testcontainers/src/clusterSlot.test.ts": 3,
+  "internal-packages/testcontainers/src/dbBlip.test.ts": 12775,
+  "internal-packages/testcontainers/src/faultInjection.test.ts": 4,
+  "internal-packages/testcontainers/src/heteroDedicated.test.ts": 10626,
+  "internal-packages/testcontainers/src/heteroRunOpsWithRedis.test.ts": 8168,
+  "internal-packages/testcontainers/src/nShardFixture.test.ts": 12884,
+  "internal-packages/testcontainers/src/warmup.test.ts": 22368,
+  "internal-packages/tsql/src/grammar/parser.test.ts": 76,
+  "internal-packages/tsql/src/index.test.ts": 121,
+  "internal-packages/tsql/src/query/escape.test.ts": 7,
+  "internal-packages/tsql/src/query/parser.test.ts": 131,
+  "internal-packages/tsql/src/query/printer.test.ts": 812,
+  "internal-packages/tsql/src/query/results.test.ts": 3,
+  "internal-packages/tsql/src/query/schema.test.ts": 13,
+  "internal-packages/tsql/src/query/security.test.ts": 329,
+  "internal-packages/tsql/src/query/time_buckets.test.ts": 6,
+  "internal-packages/tsql/src/query/validator.test.ts": 135,
+  "internal-packages/tsql/src/read-only.test.ts": 237,
+  "internal-packages/webhook-engine/src/engine/disabled.test.ts": 3,
+  "internal-packages/webhook-engine/src/engine/filter/filter.test.ts": 8,
+  "internal-packages/webhook-engine/src/engine/ingest.test.ts": 77399,
+  "internal-packages/webhook-engine/src/engine/partitions.test.ts": 9720,
+  "internal-packages/webhook-engine/src/engine/sessionKey.test.ts": 4,
+  "internal-packages/webhook-engine/src/engine/signing/signing.test.ts": 6,
+  "internal-packages/webhook-engine/src/engine/verification/verify.test.ts": 9,
+  "internal-packages/webhook-sources/src/roundtrip.test.ts": 88,
   "packages/build/src/extensions/core/syncEnvVars.test.ts": 33,
   "packages/core/src/v3/apiClient/bulkActions.test.ts": 214,
   "packages/core/src/v3/apiClient/runStream.test.ts": 2319,
diff --git a/vitest.internal-reports.config.mjs b/vitest.internal-reports.config.mjs
new file mode 100644
index 00000000000..e375b9c8fe8
--- /dev/null
+++ b/vitest.internal-reports.config.mjs
@@ -0,0 +1,3 @@
+import { getInternalTestReportConfig } from "./internal-test-projects.mts";
+
+export default getInternalTestReportConfig(import.meta.dirname);
diff --git a/vitest.internal.config.ts b/vitest.internal.config.ts
new file mode 100644
index 00000000000..0f51114fea3
--- /dev/null
+++ b/vitest.internal.config.ts
@@ -0,0 +1,18 @@
+import { getInternalTestProjects } from "./internal-test-projects.mjs";
+import { defineConfig } from "vitest/config";
+import { DurationShardingSequencer } from "./internal-packages/testcontainers/src/sequencer.cjs";
+
+// Match the packages selected by `turbo run test --filter "@internal/*"`.
+// Load each package's own config so its include/exclude patterns, setup files,
+// retries and timeouts still apply. A single discovery pass lets the sequencer
+// balance files across packages instead of giving every shard a slice of each.
+const projects = getInternalTestProjects(__dirname).map((project) => project.root);
+
+export default defineConfig({
+  test: {
+    projects,
+    sequence: { sequencer: DurationShardingSequencer, concurrent: false },
+    fileParallelism: false,
+    maxWorkers: 1,
+  },
+});