feat: scope linear watcher per team and pick ticket team in UI (#240)

* feat: scope linear watcher per team and pick ticket team in UI

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor: address pr review for linear team scope

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hugocasa

backend/src/__tests__/api-validation.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { NotificationIdParamsSchema, RunIdParamsSchema, WorktreeNameParamsSchema } from "@webmux/api-contract";
+import { CreateWorktreeRequestSchema, NotificationIdParamsSchema, RunIdParamsSchema, WorktreeNameParamsSchema } from "@webmux/api-contract";
 import { z } from "zod";
 import { parseParams } from "../api-validation";
 
@@ -55,3 +55,36 @@ describe("parseParams", () => {
     });
   });
 });
+
+describe("CreateWorktreeRequestSchema linearTeamKey", () => {
+  it("uppercases and accepts a valid team key", () => {
+    const parsed = CreateWorktreeRequestSchema.safeParse({
+      createLinearTicket: true,
+      linearTeamKey: "eng",
+    });
+    expect(parsed.success).toBe(true);
+    if (parsed.success) expect(parsed.data.linearTeamKey).toBe("ENG");
+  });
+
+  it("rejects an issue-shaped key like ENG-123", () => {
+    const parsed = CreateWorktreeRequestSchema.safeParse({
+      createLinearTicket: true,
+      linearTeamKey: "ENG-123",
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it("rejects non-alpha characters", () => {
+    const parsed = CreateWorktreeRequestSchema.safeParse({
+      createLinearTicket: true,
+      linearTeamKey: "ENG2",
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it("allows omitting linearTeamKey", () => {
+    const parsed = CreateWorktreeRequestSchema.safeParse({});
+    expect(parsed.success).toBe(true);
+    if (parsed.success) expect(parsed.data.linearTeamKey).toBeUndefined();
+  });
+});

backend/src/__tests__/linear-auto-create-service.test.ts

@@ -153,6 +153,37 @@ describe("filterAutoCreateIssues", () => {
   });
 });
 
+describe("watchTeamKeys filter", () => {
+  beforeEach(() => {
+    resetProcessedIssues();
+  });
+
+  it("keeps every team when watchTeamKeys is undefined or empty", () => {
+    const eng = createIssue({ id: "eng", identifier: "ENG-1", branchName: "eng-1", team: { name: "Engineering", key: "ENG" } });
+    const ops = createIssue({ id: "ops", identifier: "OPS-1", branchName: "ops-1", team: { name: "Ops", key: "OPS" } });
+    expect(filterAutoCreateIssues([eng, ops], []).map((i) => i.identifier)).toEqual(["ENG-1", "OPS-1"]);
+    expect(filterAutoCreateIssues([eng, ops], [], []).map((i) => i.identifier)).toEqual(["ENG-1", "OPS-1"]);
+  });
+
+  it("drops issues whose team key is not in the (uppercase, normalized) allowlist", () => {
+    const eng = createIssue({ id: "eng", identifier: "ENG-1", branchName: "eng-1", team: { name: "Engineering", key: "ENG" } });
+    const ops = createIssue({ id: "ops", identifier: "OPS-1", branchName: "ops-1", team: { name: "Ops", key: "OPS" } });
+    const design = createIssue({ id: "des", identifier: "DES-1", branchName: "des-1", team: { name: "Design", key: "DES" } });
+    expect(filterAutoCreateIssues([eng, ops, design], [], ["ENG", "OPS"]).map((i) => i.identifier))
+      .toEqual(["ENG-1", "OPS-1"]);
+  });
+
+  it("applies the same filter to the oneshot variant", () => {
+    const ops = createIssue({
+      id: "ops", identifier: "OPS-1", branchName: "ops-1",
+      labels: [{ name: "webmux_oneshot", color: "#fff" }],
+      team: { name: "Ops", key: "OPS" },
+    });
+    expect(filterAutoOneshotIssues([ops], [], ["ENG"])).toEqual([]);
+    expect(filterAutoOneshotIssues([ops], [], ["OPS"]).map((i) => i.identifier)).toEqual(["OPS-1"]);
+  });
+});
+
 describe("filterAutoOneshotIssues", () => {
   beforeEach(() => {
     resetProcessedIssues();

backend/src/__tests__/setup.test.ts

@@ -80,7 +80,7 @@ describe("loadConfig", () => {
         "  linear:",
         "    enabled: false",
         "    createTicketOption: true",
-        "    teamId: team-123",
+        "    watchTeams: [ENG, ops]",
         "",
       ].join("\n"),
     );
@@ -110,7 +110,7 @@ describe("loadConfig", () => {
     expect(config.integrations.github.linkedRepos).toEqual([{ repo: "acme/linked", alias: "linked" }]);
     expect(config.integrations.linear.enabled).toBe(false);
     expect(config.integrations.linear.createTicketOption).toBe(true);
-    expect(config.integrations.linear.teamId).toBe("team-123");
+    expect(config.integrations.linear.watchTeams).toEqual(["ENG", "OPS"]);
   });
 
   it("uses the first configured profile when no default profile exists", async () => {
@@ -199,7 +199,7 @@ describe("loadConfig", () => {
 
     expect(config.integrations.linear.enabled).toBe(true);
     expect(config.integrations.linear.createTicketOption).toBe(false);
-    expect(config.integrations.linear.teamId).toBeUndefined();
+    expect(config.integrations.linear.watchTeams).toBeUndefined();
   });
 
   it("adds local profiles and appends local lifecycle hooks after project hooks", async () => {

backend/src/adapters/config.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { log } from "../lib/log";
 import type {
   AgentId,
   AgentKind,
@@ -393,25 +394,7 @@ function parseProjectConfig(parsed: Record<string, unknown>): ProjectConfig {
           ? parsed.integrations.github.autoRemoveOnMerge
           : DEFAULT_CONFIG.integrations.github.autoRemoveOnMerge,
       },
-      linear: {
-        enabled: isRecord(parsed.integrations) && isRecord(parsed.integrations.linear) && typeof parsed.integrations.linear.enabled === "boolean"
-          ? parsed.integrations.linear.enabled
-          : DEFAULT_CONFIG.integrations.linear.enabled,
-        autoCreateWorktrees: isRecord(parsed.integrations) && isRecord(parsed.integrations.linear) && typeof parsed.integrations.linear.autoCreateWorktrees === "boolean"
-          ? parsed.integrations.linear.autoCreateWorktrees
-          : DEFAULT_CONFIG.integrations.linear.autoCreateWorktrees,
-        createTicketOption: isRecord(parsed.integrations) &&
-            isRecord(parsed.integrations.linear) &&
-            typeof parsed.integrations.linear.createTicketOption === "boolean"
-          ? parsed.integrations.linear.createTicketOption
-          : DEFAULT_CONFIG.integrations.linear.createTicketOption,
-        ...(isRecord(parsed.integrations) &&
-            isRecord(parsed.integrations.linear) &&
-            typeof parsed.integrations.linear.teamId === "string" &&
-            parsed.integrations.linear.teamId.trim()
-          ? { teamId: parsed.integrations.linear.teamId.trim() }
-          : {}),
-      },
+      linear: parseLinearIntegration(parsed),
     },
     lifecycleHooks: parseLifecycleHooks(parsed.lifecycleHooks),
     autoName: parseAutoName(parsed.auto_name),
@@ -423,6 +406,46 @@ function defaultConfig(): ProjectConfig {
   return parseProjectConfig({});
 }
 
+function parseTeamKeyList(raw: unknown): string[] | undefined {
+  if (!Array.isArray(raw)) return undefined;
+  const keys = raw
+    .filter((entry): entry is string => typeof entry === "string")
+    .map((entry) => entry.trim().toUpperCase())
+    .filter((entry) => entry.length > 0);
+  return keys.length > 0 ? Array.from(new Set(keys)) : undefined;
+}
+
+/** Track whether the deprecation warning for `integrations.linear.teamId` has
+ *  already been logged this process so config reloads don't spam the log. */
+let warnedLegacyLinearTeamId = false;
+
+function parseLinearIntegration(parsed: Record<string, unknown>): LinearIntegrationConfig {
+  const defaults = DEFAULT_CONFIG.integrations.linear;
+  const linear = isRecord(parsed.integrations) && isRecord(parsed.integrations.linear)
+    ? parsed.integrations.linear
+    : null;
+
+  if (!linear) return { ...defaults };
+
+  if (typeof linear.teamId === "string" && !warnedLegacyLinearTeamId) {
+    warnedLegacyLinearTeamId = true;
+    log.warn("[config] integrations.linear.teamId is no longer used — the ticket team is now picked at creation time in the dashboard");
+  }
+
+  const watchTeams = parseTeamKeyList(linear.watchTeams);
+
+  return {
+    enabled: typeof linear.enabled === "boolean" ? linear.enabled : defaults.enabled,
+    autoCreateWorktrees: typeof linear.autoCreateWorktrees === "boolean"
+      ? linear.autoCreateWorktrees
+      : defaults.autoCreateWorktrees,
+    createTicketOption: typeof linear.createTicketOption === "boolean"
+      ? linear.createTicketOption
+      : defaults.createTicketOption,
+    ...(watchTeams ? { watchTeams } : {}),
+  };
+}
+
 function parseLocalLinearOverlay(parsed: Record<string, unknown>): Partial<LinearIntegrationConfig> | null {
   if (!isRecord(parsed.integrations)) return null;
   const linear = parsed.integrations.linear;
@@ -432,7 +455,8 @@ function parseLocalLinearOverlay(parsed: Record<string, unknown>): Partial<Linea
   if (typeof linear.enabled === "boolean") overlay.enabled = linear.enabled;
   if (typeof linear.autoCreateWorktrees === "boolean") overlay.autoCreateWorktrees = linear.autoCreateWorktrees;
   if (typeof linear.createTicketOption === "boolean") overlay.createTicketOption = linear.createTicketOption;
-  if (typeof linear.teamId === "string" && linear.teamId.trim()) overlay.teamId = linear.teamId.trim();
+  const watchTeams = parseTeamKeyList(linear.watchTeams);
+  if (watchTeams) overlay.watchTeams = watchTeams;
   return Object.keys(overlay).length > 0 ? overlay : null;
 }
 

backend/src/domain/config.ts

@@ -72,7 +72,9 @@ export interface LinearIntegrationConfig {
   enabled: boolean;
   autoCreateWorktrees: boolean;
   createTicketOption: boolean;
-  teamId?: string;
+  /** Restrict the auto-create watcher to issues from these team keys (e.g. ["ENG", "OPS"]).
+   *  When unset, all teams the authenticated user is assigned in are watched. */
+  watchTeams?: string[];
 }
 
 export interface IntegrationConfig {

backend/src/server.ts

@@ -165,11 +165,13 @@ async function runOneshotForIssue(issueId: string): Promise<void> {
 /** Safe to call multiple times — the guard prevents duplicate monitors. */
 function startLinearAutoCreate(): void {
   if (stopLinearAutoCreate) return;
+  const watchTeamKeys = config.integrations.linear.watchTeams;
   stopLinearAutoCreate = startLinearAutoCreateMonitor({
     lifecycleService,
     git,
     projectRoot: PROJECT_DIR,
     runOneshotForIssue,
+    ...(watchTeamKeys && watchTeamKeys.length > 0 ? { watchTeamKeys } : {}),
   });
 }
 
@@ -884,6 +886,9 @@ async function apiCreateWorktree(req: Request): Promise<Response> {
   const agents = body.agents;
   const createLinearTicket = body.createLinearTicket === true;
   const linearTitle = body.linearTitle?.trim() ? body.linearTitle.trim() : undefined;
+  // CreateWorktreeRequestSchema already trims, uppercases, and validates the
+  // team key shape — body.linearTeamKey is either a valid key or undefined.
+  const linearTeamKey = body.linearTeamKey;
   const mode = body.mode;
   const selectedAgents = agents
     ? agents
@@ -960,15 +965,22 @@ async function apiCreateWorktree(req: Request): Promise<Response> {
       return errorResponse("Linear ticket title could not be derived from the prompt", 400);
     }
 
-    const teamId = config.integrations.linear.teamId;
-    if (!teamId) {
-      return errorResponse("Linear teamId is not configured", 503);
+    if (!linearTeamKey) {
+      return errorResponse(
+        "Linear team is required to create a ticket. Provide `linearTeamKey` (e.g. \"ENG\").",
+        400,
+      );
+    }
+
+    const teamResult = await fetchTeamByKey(linearTeamKey);
+    if (!teamResult.ok) {
+      return errorResponse(teamResult.error, teamResult.status);
     }
 
     const linearResult = await createLinearIssue({
       title,
       description: resolvedPrompt ?? "",
-      teamId,
+      teamId: teamResult.data.id,
     });
     if (!linearResult.ok) {
       return errorResponse(linearResult.error, 502);

backend/src/services/linear-auto-create-service.ts

@@ -20,6 +20,9 @@ export interface LinearAutoCreateDependencies {
   fetchIssues?: typeof fetchAssignedIssues;
   /** Optional handler for the `webmux_oneshot` label variant. When omitted, oneshot triggering is skipped. */
   runOneshotForIssue?: (issueId: string) => Promise<void>;
+  /** Restrict triggering to issues whose team.key is in this list (uppercase).
+   *  Undefined or empty → no team filter (all teams). */
+  watchTeamKeys?: string[];
 }
 
 export interface LinearAutoCreateMonitorOptions {
@@ -37,16 +40,26 @@ function hasLabel(issue: LinearIssue, name: string): boolean {
   return issue.labels.some((l) => l.name.toLowerCase() === name);
 }
 
+function matchesTeamFilter(issue: LinearIssue, watchTeamKeys: string[] | undefined): boolean {
+  if (!watchTeamKeys || watchTeamKeys.length === 0) return true;
+  // watchTeamKeys is expected already-uppercase: parseTeamKeyList normalizes
+  // and dedupes before this code is reached.
+  return watchTeamKeys.includes(issue.team.key.toUpperCase());
+}
+
 /** Shared filter: Todo state, the label rule supplied by the caller, not yet
- *  processed, and no existing worktree on the branch. */
+ *  processed, no existing worktree on the branch, and (when configured) the
+ *  issue's team is in the watch list. */
 function filterTriggerableIssues(
   issues: LinearIssue[],
   existingBranches: string[],
   matchesLabelRule: (issue: LinearIssue) => boolean,
+  watchTeamKeys?: string[],
 ): LinearIssue[] {
   return issues.filter((issue) => {
     if (issue.state.name !== "Todo") return false;
     if (!matchesLabelRule(issue)) return false;
+    if (!matchesTeamFilter(issue, watchTeamKeys)) return false;
     if (processedIssueIds.has(issue.id)) return false;
     return !existingBranches.some((branch) => branchMatchesIssue(branch, issue.branchName));
   });
@@ -57,11 +70,13 @@ function filterTriggerableIssues(
 export function filterAutoCreateIssues(
   issues: LinearIssue[],
   existingBranches: string[],
+  watchTeamKeys?: string[],
 ): LinearIssue[] {
   return filterTriggerableIssues(
     issues,
     existingBranches,
     (issue) => hasLabel(issue, AUTO_CREATE_LABEL) && !hasLabel(issue, AUTO_ONESHOT_LABEL),
+    watchTeamKeys,
   );
 }
 
@@ -71,11 +86,13 @@ export function filterAutoCreateIssues(
 export function filterAutoOneshotIssues(
   issues: LinearIssue[],
   existingBranches: string[],
+  watchTeamKeys?: string[],
 ): LinearIssue[] {
   return filterTriggerableIssues(
     issues,
     existingBranches,
     (issue) => hasLabel(issue, AUTO_ONESHOT_LABEL),
+    watchTeamKeys,
   );
 }
 
@@ -114,9 +131,9 @@ export async function runLinearAutoCreateOnce(deps: LinearAutoCreateDependencies
     .map((entry) => entry.branch as string);
 
   const oneshotIssues = deps.runOneshotForIssue
-    ? filterAutoOneshotIssues(result.data, existingBranches)
+    ? filterAutoOneshotIssues(result.data, existingBranches, deps.watchTeamKeys)
     : [];
-  const createIssues = filterAutoCreateIssues(result.data, existingBranches);
+  const createIssues = filterAutoCreateIssues(result.data, existingBranches, deps.watchTeamKeys);
 
   if (oneshotIssues.length === 0 && createIssues.length === 0) {
     log.debug(`[linear-auto-create] no new labeled issues (${result.data.length} assigned, ${existingBranches.length} worktrees)`);

bin/src/init-helpers.test.ts

@@ -242,7 +242,7 @@ describe("buildStarterTemplate", () => {
     expect(template).toContain("# autoRemoveOnMerge: true");
     expect(template).toContain("# autoCreateWorktrees: true");
     expect(template).toContain("# createTicketOption: true");
-    expect(template).toContain("# teamId: team-123");
+    expect(template).toContain("# watchTeams: [ENG, OPS]");
     expect(template).toContain("# lifecycleHooks:");
     expect(template).toContain("# auto_name:");
     expect(template).toContain("# startupEnvs become runtime env vars for panes, agents, and hooks.");

bin/src/init-helpers.ts

@@ -677,12 +677,15 @@ integrations:
   linear:
     # Enable Linear issue lookup and linking in the UI.
     enabled: true
-    # Auto-create worktrees for assigned issues.
+    # Auto-create worktrees for assigned issues labeled "webmux" or "webmux_oneshot".
     # autoCreateWorktrees: true
-    # Show a create-ticket action in the dashboard.
+    # Show a create-ticket action in the dashboard. The team to file into is
+    # picked in the dialog at creation time.
     # createTicketOption: true
-    # Restrict issue sync to a specific Linear team id.
-    # teamId: team-123
+    # Restrict the auto-create watcher to issues from these teams. Useful when
+    # the authenticated Linear user is in multiple teams or when running webmux
+    # in several projects on the same machine that share a Linear account.
+    # watchTeams: [ENG, OPS]
 
 # startupEnvs become runtime env vars for panes, agents, and hooks.
 startupEnvs:

frontend/src/App.test.ts

@@ -598,6 +598,9 @@ describe("App create selection", () => {
     await fireEvent.input(screen.getByLabelText(/Prompt/i), {
       target: { value: "Implement the new flow" },
     });
+    await fireEvent.input(screen.getByLabelText(/Team key/i), {
+      target: { value: "ENG" },
+    });
     await fireEvent.input(screen.getByLabelText(/Linear ticket title/i), {
       target: { value: "Ship Linear-backed worktree creation" },
     });
@@ -614,6 +617,7 @@ describe("App create selection", () => {
           agents: ["claude"],
           prompt: "Implement the new flow",
           createLinearTicket: true,
+          linearTeamKey: "ENG",
           linearTitle: "Ship Linear-backed worktree creation",
         },
       });