fix(branches): preserve API compatibility at scale

The branch picker needs bounded name search, but changing the stable v1 metadata endpoint would break clients that depend on project-qualified tokens. Keep that contract intact and expose picker-oriented search through an additive route.\n\nLarge archives also need a bounded Activity branch panel. Preserve the report total by aggregating overflow into an Other row instead of rendering an unbounded list or silently dropping data.

Author: wesm

docs/session-api.md

@@ -117,36 +117,58 @@ for filter options:
 GET /api/v1/projects
 GET /api/v1/machines
 GET /api/v1/branches
+GET /api/v1/branch-names
 GET /api/v1/agents
 ```
 
-`GET /api/v1/branches` returns a bounded list of distinct branch names for
-filter pickers. Results are sorted by session count and then branch name. The
-search is case-insensitive and matches branch-name substrings.
+`GET /api/v1/branches` preserves the stable project-qualified metadata
+contract. It returns distinct `(project, branch)` pairs, ordered by project and
+branch, plus an opaque token for exact filtering:
+
+```json
+{
+  "branches": [
+    {
+      "project": "myapp",
+      "branch": "main",
+      "token": "..."
+    }
+  ]
+}
+```
+
+Pass the token back as `git_branch` when project identity must remain exact;
+treat it as opaque and URL-encode it in manual HTTP calls.
+
+`GET /api/v1/branch-names` is the bounded name-search contract used by filter
+pickers. It deduplicates same-named branches after applying project scope and
+orders names by the most recent matching session activity, then branch name.
+Search is case-insensitive and matches branch-name substrings.
 
 | Query parameter | Meaning |
 |-----------------|---------|
 | `search` | Optional case-insensitive branch-name substring |
 | `projects` | Optional repeated project filter applied before branch-name deduplication |
 | `scope` | `roots` by default; `all` also includes subagent and fork sessions |
 | `limit` | Maximum branch names, from 1 through 100; default 100 |
+| `include_one_shot` | Include one-shot sessions; default false |
+| `include_automated` | Include automated sessions; default false |
 
 ```json
 {
   "branches": [
     {
-      "branch": "main",
-      "session_count": 42
+      "branch": "main"
     }
   ],
   "has_more": false
 }
 ```
 
-`has_more` is true when additional matching branch names exist beyond the
-requested limit. Branch-aware endpoints accept branch names directly in
-`git_branch`; clients do not obtain opaque filter tokens from this metadata
-endpoint.
+`has_more` is true when additional matching names exist beyond the requested
+limit. Branch-aware endpoints accept these names directly in `git_branch` for
+name-based filtering, or the token from `/api/v1/branches` for an exact
+project/branch identity.
 
 ## Commands
 
@@ -236,7 +258,7 @@ therefore appear on both dates.
 | `--project`           | `project`           | string                            |
 | `--exclude-project`   | `exclude_project`   | string                            |
 | `--machine`           | `machine`           | string                            |
-| `--branch`            | `git_branch`        | Branch name; the CLI requires `--project`. Direct HTTP callers may supply project scope separately |
+| `--branch`            | `git_branch`        | Branch name; the CLI requires `--project` and sends an exact opaque token. Direct HTTP callers may use a name or token |
 | `--agent`             | `agent`             | string                            |
 | `--date`              | `date`              | `YYYY-MM-DD`                      |
 | `--date-from`         | `date_from`         | `YYYY-MM-DD`                      |

frontend/src/lib/api/client.ts

@@ -39,7 +39,7 @@ export async function searchBranches(
   params: BranchSearchParams,
 ): Promise<BranchSearchResponse> {
   configureGeneratedClient();
-  const response = await MetadataService.getApiV1Branches({
+  const response = await MetadataService.getApiV1BranchNames({
     projects: params.projects,
     search: params.search || undefined,
     limit: params.limit ?? 100,

frontend/src/lib/api/generated/index.ts

@@ -45,6 +45,8 @@
   const byProject = $derived(rankedRows(report.by_project));
   const byModel = $derived(rankedRows(report.by_model));
   const byAgent = $derived(rankedRows(report.by_agent));
+  const BRANCH_ROW_LIMIT = 40;
+  const OTHER_BRANCHES_KEY = "__activity_other_branches__";
   // Tokenizing branch rows depends only on the report, not the metric, so
   // keep it out of the rankedRows derived: flipping minutes/cost re-ranks
   // without re-allocating every row of an uncapped (project, branch) list.
@@ -55,7 +57,34 @@
       displayLabel: branchLabel(b.project, b.branch, m.shared_no_branch()),
     })),
   );
-  const byBranch = $derived(rankedRows(branchRows));
+  const byBranch = $derived.by(() => {
+    const ranked = rankedRows(branchRows);
+    if (ranked.length <= BRANCH_ROW_LIMIT) return ranked;
+
+    const visible = ranked.slice(0, BRANCH_ROW_LIMIT - 1);
+    const omitted = ranked.slice(BRANCH_ROW_LIMIT - 1);
+    const sum = (value: (row: BreakdownRow) => number) =>
+      omitted.reduce((total, row) => total + value(row), 0);
+    return [
+      ...visible,
+      {
+        key: OTHER_BRANCHES_KEY,
+        displayLabel: m.shared_other(),
+        agent_minutes: sum((row) => row.agent_minutes),
+        cost: moneyFromMicrodollars(sum((row) => row.cost.microdollars)),
+        interactive_agent_minutes: sum(
+          (row) => row.interactive_agent_minutes,
+        ),
+        automated_agent_minutes: sum((row) => row.automated_agent_minutes),
+        interactive_cost: moneyFromMicrodollars(
+          sum((row) => row.interactive_cost.microdollars),
+        ),
+        automated_cost: moneyFromMicrodollars(
+          sum((row) => row.automated_cost.microdollars),
+        ),
+      },
+    ];
+  });
 
   interface Panel {
     title: string;

frontend/src/lib/api/generated/models/BranchesResponse.ts

@@ -394,4 +394,51 @@ describe("Breakdowns", () => {
     unmount(component);
     target.remove();
   });
+
+  it("caps large branch panels with an aggregated Other row", async () => {
+    const report = makeReport();
+    report.by_branch = Array.from({ length: 41 }, (_, index) => {
+      const value = index < 39 ? 2 : 1;
+      return {
+        project_key: `pl1:sha256:${index}`,
+        project: `project-${index}`,
+        branch: `branch-${index}`,
+        agent_minutes: value,
+        cost: testMoney(value),
+        interactive_agent_minutes: value,
+        automated_agent_minutes: 0,
+        interactive_cost: testMoney(value),
+        automated_cost: testMoney(0),
+      };
+    });
+    const target = document.createElement("div");
+    document.body.appendChild(target);
+    const component = mount(Breakdowns, { target, props: { report } });
+    await tick();
+
+    const branchPanel = Array.from(
+      target.querySelectorAll<HTMLElement>(".breakdown-panel"),
+    ).find(
+      (panel) => panel.querySelector(".panel-title")?.textContent === "Branch",
+    );
+    expect(branchPanel?.querySelectorAll(".bar-row")).toHaveLength(40);
+    const otherRow = Array.from(
+      branchPanel?.querySelectorAll<HTMLElement>(".bar-row") ?? [],
+    ).find((row) => row.querySelector(".bar-label")?.textContent === "Other");
+    expect(otherRow?.querySelector(".bar-value")?.textContent?.trim()).toBe("2");
+    expect(branchPanel?.textContent).not.toContain("project-39/branch-39");
+    expect(branchPanel?.textContent).not.toContain("project-40/branch-40");
+
+    const costButton = Array.from(
+      target.querySelectorAll<HTMLButtonElement>(".metric-btn"),
+    ).find((button) => button.textContent?.trim() === "Cost");
+    costButton?.click();
+    await tick();
+    expect(otherRow?.querySelector(".bar-value")?.textContent?.trim()).toBe(
+      "$2.00",
+    );
+
+    await unmount(component);
+    target.remove();
+  });
 });

frontend/src/lib/api/generated/models/DbBranchInfo.ts

@@ -503,7 +503,7 @@ describe("UsagePage refresh behavior", () => {
     );
     vi.spyOn(usage, "fetchAll").mockResolvedValue();
     vi.spyOn(sessions, "loadAgents").mockResolvedValue();
-    const searchBranches = vi.spyOn(MetadataService, "getApiV1Branches")
+    const searchBranches = vi.spyOn(MetadataService, "getApiV1BranchNames")
       .mockResolvedValue({ branches: [], has_more: false });
     router.route = "usage";
     router.params = {