fix(env): scope branch-override lookup by branchId

`findVariableByNaturalKey` listed environment variables by
`(projectId, class, key)` only and filtered by branch client-side, but
the list endpoint is paginated (default 100 rows, ordered createdAt
asc). Once a project accumulates more than a page of preview overrides
for a key, the newest branch's row falls off the first page, so the
lookup returns null even though the row exists.

`project env update --branch` then reports the variable as not found,
and `project env add --branch`'s pre-check also misses it and POSTs,
which the server rejects with a 409. The two paths contradict each
other and neither can touch an existing branch override.

Pass `branchId` to the list query for branch-scoped lookups (the
endpoint already supports the filter) so the server returns the single
exact row regardless of how many branches exist. Role-scoped lookups
are unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: kristof-siket

packages/cli/src/controllers/app-env-api.ts

@@ -33,6 +33,11 @@ export async function findVariableByNaturalKey(
   resolved: ResolvedEnvApiScope,
   signal: AbortSignal,
 ): Promise<RawEnvironmentVariable | null> {
+  // Filter by branchId server-side for branch-scoped lookups. The list
+  // endpoint is paginated (default 100 rows, createdAt asc); without this
+  // filter a project with more than a page of preview overrides for `key`
+  // pushes the newest branch's row off the first page, so the row this
+  // lookup exists to find is silently invisible and add/update misfire.
   const { data, error, response } = await client.GET(
     "/v1/environment-variables",
     {
@@ -41,6 +46,9 @@ export async function findVariableByNaturalKey(
           projectId,
           class: resolved.apiTarget.class,
           key,
+          ...(resolved.apiTarget.branchId !== null
+            ? { branchId: resolved.apiTarget.branchId }
+            : {}),
         },
       },
       signal,

packages/cli/tests/app-env.test.ts

@@ -944,6 +944,67 @@ describe("env update", () => {
     );
   });
 
+  it("scopes the branch-override lookup by branchId so it survives pagination", async () => {
+    const client = createMockClient();
+    client.envGET
+      .mockResolvedValueOnce({
+        data: {
+          data: [makeBranchRow()],
+          pagination: { hasMore: false, nextCursor: null },
+        },
+        response: { status: 200 },
+      })
+      .mockResolvedValueOnce({
+        data: {
+          data: [
+            makeVariableRow({
+              id: "envvar_branch",
+              key: "DATABASE_URL",
+              class: "preview",
+              branchId: "br_feature",
+            }),
+          ],
+          pagination: { hasMore: false, nextCursor: null },
+        },
+        response: { status: 200 },
+      });
+    client.PATCH.mockResolvedValueOnce({
+      data: {
+        data: makeVariableRow({
+          id: "envvar_branch",
+          key: "DATABASE_URL",
+          class: "preview",
+          branchId: "br_feature",
+        }),
+      },
+      response: { status: 200 },
+    });
+
+    const { controllers, createTempCwd, createTestCommandContext } =
+      await loadControllers(client, "proj_123");
+    const cwd = await createTempCwd();
+    await writeLocalPin(cwd);
+    const { context } = await createTestCommandContext({ cwd });
+
+    await controllers.runEnvUpdate(context, "DATABASE_URL=postgresql://new", {
+      branchName: "feature/foo",
+    });
+
+    expect(client.GET).toHaveBeenCalledWith(
+      "/v1/environment-variables",
+      expect.objectContaining({
+        params: {
+          query: expect.objectContaining({
+            projectId: "proj_123",
+            class: "preview",
+            key: "DATABASE_URL",
+            branchId: "br_feature",
+          }),
+        },
+      }),
+    );
+  });
+
   it("updates variables from a dotenv file via PATCH", async () => {
     const client = createMockClient();
     client.envGET