From ca3db33745656c8562d8d032e241b8469b813328 Mon Sep 17 00:00:00 2001
From: Sphia Sadek <isadeks@gmail.com>
Date: Fri, 4 Sep 2026 13:13:03 -0400
Subject: [PATCH 1/9] feat(linear): record the owning workspace on project
 mappings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Linear project-to-repo mapping table is keyed on `linear_project_id` alone
and carries no workspace attribute, so nothing ties a mapping to the tenant that
owns it. The webhook processor looks the repository up from the body-supplied
`projectId` with no way to check it against the workspace whose signature the
delivery arrived with, which lets any onboarded workspace name another
workspace's project and steer an agent task at that workspace's repository.

This records the missing value so a later change can enforce it; no read path
changes behaviour yet.

`onboard-project` now resolves the owning workspace by asking Linear which
onboarded workspace's own token can see the project, rather than accepting it as
a flag. The resolution is what the enforcement path will check deliveries
against, so a typo'd flag would durably write the cross-tenant mapping the check
exists to prevent — and `organization.id` is read from the same authenticated
response that resolved the project, not from the workspace we assumed we were
asking. `--slug` narrows the search; `--workspace-id` records an owner without
verifying it, for when the Linear API is unreachable.

`backfill-project-workspaces` fills in mappings that predate the field, one pass
per workspace rather than one lookup per row, and paginates the project listing
(`list-projects` stops at 100, which for a backfill would silently leave the
overflow unresolved). The update is conditional on the row still existing and
still having no workspace id, so it neither resurrects a deleted mapping nor
overwrites a concurrent `onboard-project`. A project id claimed by two
workspaces is skipped and named rather than assigned to whichever answered
first.

`platform doctor` reports mappings with no owning workspace, capped at ten named
ids, so an operator can tell whether the backfill is finished before enforcement
is turned on.
---
 cli/src/commands/linear.ts                    | 441 +++++++++++++++++-
 cli/src/platform-doctor.ts                    |  83 ++++
 .../commands/linear-project-workspace.test.ts | 298 ++++++++++++
 cli/test/platform-doctor.test.ts              |  70 +++
 docs/guides/LINEAR_SETUP_GUIDE.md             |   4 +
 .../content/docs/using/Linear-setup-guide.md  |   4 +
 6 files changed, 897 insertions(+), 3 deletions(-)
 create mode 100644 cli/test/commands/linear-project-workspace.test.ts

diff --git a/cli/src/commands/linear.ts b/cli/src/commands/linear.ts
index 4982d3f84..6706a29b7 100644
--- a/cli/src/commands/linear.ts
+++ b/cli/src/commands/linear.ts
@@ -28,7 +28,7 @@ import {
   ResourceExistsException,
   SecretsManagerClient,
 } from '@aws-sdk/client-secrets-manager';
-import { DynamoDBDocumentClient, PutCommand, ScanCommand } from '@aws-sdk/lib-dynamodb';
+import { DynamoDBDocumentClient, PutCommand, ScanCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
 import { Command } from 'commander';
 import { ApiClient } from '../api-client';
 import { loadConfig, loadCredentials } from '../config';
@@ -574,6 +574,257 @@ export async function findWorkspaceRowBySlug(
   return (result.Items ?? []).find((item) => item.workspace_slug === slug);
 }
 
+/**
+ * Every `active` row in the workspace registry.
+ *
+ * Same unbounded-Scan reasoning as {@link findWorkspaceRowBySlug}: the registry holds
+ * one small row per install. Rows whose `status` is anything other than `active` are
+ * dropped here rather than by the caller, matching the runtime resolver's fail-closed
+ * reading of that column (a half-written row is not an install). Exported for tests.
+ */
+export async function listActiveWorkspaceRows(
+  ddb: DynamoDBDocumentClient,
+  registryTableName: string,
+): Promise<Array<Record<string, unknown>>> {
+  const rows: Array<Record<string, unknown>> = [];
+  let lastKey: Record<string, unknown> | undefined;
+  do {
+    const page = await ddb.send(new ScanCommand({
+      TableName: registryTableName,
+      ExclusiveStartKey: lastKey,
+    }));
+    for (const item of page.Items ?? []) {
+      if (item.status === 'active') rows.push(item);
+    }
+    lastKey = page.LastEvaluatedKey;
+  } while (lastKey);
+  return rows;
+}
+
+/**
+ * Slugs of every onboarded workspace, registry first.
+ *
+ * The registry is authoritative when present because it carries `status`, so a revoked
+ * install is not offered as a candidate. Installs predating the registry have only the
+ * `bgagent-linear-oauth-*` secrets, so that prefix listing is the fallback — the same
+ * two-source order `list-projects` uses.
+ */
+export async function listOnboardedWorkspaceSlugs(args: {
+  readonly sm: SecretsManagerClient;
+  readonly ddb?: DynamoDBDocumentClient;
+  readonly registryTableName?: string;
+}): Promise<string[]> {
+  if (args.ddb && args.registryTableName) {
+    const rows = await listActiveWorkspaceRows(args.ddb, args.registryTableName);
+    const slugs = rows
+      .map((r) => r.workspace_slug as string | undefined)
+      .filter((s): s is string => Boolean(s));
+    if (slugs.length > 0) return slugs;
+  }
+
+  // ListSecretsCommand caps at 100 per page; paginate so a deployment with more
+  // matching secrets than that does not silently miss installs after page one.
+  const collected: string[] = [];
+  let nextToken: string | undefined;
+  do {
+    const listed = await args.sm.send(new ListSecretsCommand({
+      Filters: [{ Key: 'name', Values: [LINEAR_OAUTH_SECRET_PREFIX] }],
+      MaxResults: 100,
+      NextToken: nextToken,
+    }));
+    for (const s of listed.SecretList ?? []) {
+      const name = s.Name ?? '';
+      if (name.startsWith(LINEAR_OAUTH_SECRET_PREFIX)) {
+        collected.push(name.slice(LINEAR_OAUTH_SECRET_PREFIX.length));
+      }
+    }
+    nextToken = listed.NextToken;
+  } while (nextToken);
+  return collected;
+}
+
+/** Outcome of resolving a usable Linear access token for one workspace. */
+export type WorkspaceTokenResult =
+  | { readonly kind: 'token'; readonly accessToken: string }
+  | { readonly kind: 'unavailable'; readonly reason: string };
+
+/**
+ * Resolve a usable Linear access token for one workspace, vault first.
+ *
+ * Vault-before-Secrets-Manager mirrors the runtime resolver, and the order matters for
+ * more than preference: a vault-managed workspace holds no usable Secrets Manager
+ * token, so reading the bundle first reports a bare 401 on precisely the workspaces
+ * that are healthy.
+ *
+ * Returns a reason rather than throwing because every caller iterates workspaces and
+ * must keep going when one is unreachable — a single unreadable install should narrow
+ * the answer, not abort the command.
+ */
+export async function resolveWorkspaceAccessToken(args: {
+  readonly slug: string;
+  readonly sm: SecretsManagerClient;
+  readonly ddb?: DynamoDBDocumentClient;
+  readonly registryTableName?: string;
+  readonly region: string;
+  readonly vaultWorkloadName: string;
+}): Promise<WorkspaceTokenResult> {
+  const { slug, sm, ddb, registryTableName, vaultWorkloadName } = args;
+
+  if (ddb && registryTableName) {
+    const row = await findWorkspaceRowBySlug(ddb, registryTableName, slug).catch(() => undefined);
+    const providerName = row?.provider_name as string | undefined;
+    if (providerName) {
+      const workspaceId = row?.linear_workspace_id as string | undefined;
+      const recorded = row?.vault_user_id as string | undefined;
+      const userId = recorded
+        ?? (workspaceId ? linearVaultUserId(workspaceId) : linearVaultUserIdForSlug(slug));
+      const minted = await mintLinearTokenFromVault({
+        region: args.region,
+        workloadName: vaultWorkloadName,
+        providerName,
+        userId,
+      });
+      if (minted.kind === 'token') return { kind: 'token', accessToken: minted.accessToken };
+    }
+  }
+
+  try {
+    const resp = await sm.send(new GetSecretValueCommand({ SecretId: linearOauthSecretName(slug) }));
+    const stored = JSON.parse(resp.SecretString ?? '{}') as { access_token?: string };
+    if (!stored.access_token) {
+      return { kind: 'unavailable', reason: `secret ${linearOauthSecretName(slug)} is missing access_token` };
+    }
+    return { kind: 'token', accessToken: stored.access_token };
+  } catch (err) {
+    return {
+      kind: 'unavailable',
+      reason: `failed to read ${linearOauthSecretName(slug)}: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+/** Which workspace a project belongs to, as Linear itself reports it. */
+export type ProjectOwnerResult =
+  | { readonly kind: 'found'; readonly slug: string; readonly workspaceId: string }
+  | { readonly kind: 'not-found'; readonly searched: readonly string[]; readonly errors: readonly string[] };
+
+/**
+ * Ask Linear which onboarded workspace owns `projectId`.
+ *
+ * Resolved from the provider rather than taken as an operator flag on purpose. The
+ * owning workspace is the value the webhook path will later check a delivery against,
+ * so a typo'd flag would durably write a mapping that points one tenant's project at
+ * another tenant's repository — the exact state the check exists to make unreachable.
+ * Linear answering "this project is visible to this workspace's token" is the only
+ * authority on the question that does not depend on the operator being careful.
+ *
+ * `organization.id` comes from the same authenticated response as the project rather
+ * than from the registry row, so the recorded id is the workspace Linear says owns the
+ * project, not the workspace we assumed we were asking.
+ */
+export async function findProjectOwnerWorkspace(args: {
+  readonly projectId: string;
+  readonly slugs: readonly string[];
+  readonly sm: SecretsManagerClient;
+  readonly ddb?: DynamoDBDocumentClient;
+  readonly registryTableName?: string;
+  readonly region: string;
+  readonly vaultWorkloadName: string;
+  readonly fetchImpl?: typeof fetch;
+}): Promise<ProjectOwnerResult> {
+  const doFetch = args.fetchImpl ?? fetch;
+  const errors: string[] = [];
+
+  for (const slug of args.slugs) {
+    const token = await resolveWorkspaceAccessToken({ ...args, slug });
+    if (token.kind !== 'token') {
+      errors.push(`${slug}: ${token.reason}`);
+      continue;
+    }
+
+    try {
+      const res = await doFetch('https://api.linear.app/graphql', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${token.accessToken}`,
+        },
+        body: JSON.stringify({
+          query: 'query($id: String!) { organization { id } project(id: $id) { id } }',
+          variables: { id: args.projectId },
+        }),
+      });
+      if (!res.ok) {
+        errors.push(`${slug}: Linear API returned ${res.status}`);
+        continue;
+      }
+      const body = await res.json() as {
+        data?: { organization?: { id?: string }; project?: { id?: string } | null };
+      };
+      // A workspace whose token cannot see the project answers `project: null` with a
+      // 200 — that is the "not this workspace" signal, not an error worth reporting.
+      const foundId = body.data?.project?.id;
+      const orgId = body.data?.organization?.id;
+      if (foundId === args.projectId && orgId) {
+        return { kind: 'found', slug, workspaceId: orgId };
+      }
+    } catch (err) {
+      errors.push(`${slug}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  return { kind: 'not-found', searched: args.slugs, errors };
+}
+
+/**
+ * Every project id visible to one workspace's token, with its organization id.
+ *
+ * Paginated deliberately. `list-projects` asks for `projects(first: 100)` and stops,
+ * which is fine for a human browsing but not for a backfill: a workspace with more
+ * than a page of projects would leave the overflow unresolved and silently keep the
+ * mappings the enforcement path is about to start rejecting.
+ */
+export async function listWorkspaceProjectIds(args: {
+  readonly accessToken: string;
+  readonly fetchImpl?: typeof fetch;
+}): Promise<{ readonly workspaceId?: string; readonly projectIds: string[] }> {
+  const doFetch = args.fetchImpl ?? fetch;
+  const projectIds: string[] = [];
+  let workspaceId: string | undefined;
+  let cursor: string | undefined;
+
+  do {
+    const res = await doFetch('https://api.linear.app/graphql', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${args.accessToken}`,
+      },
+      body: JSON.stringify({
+        query: 'query($after: String) { organization { id } '
+          + 'projects(first: 250, after: $after) { nodes { id } pageInfo { hasNextPage endCursor } } }',
+        variables: { after: cursor ?? null },
+      }),
+    });
+    if (!res.ok) throw new CliError(`Linear API returned ${res.status}`);
+    const body = await res.json() as {
+      data?: {
+        organization?: { id?: string };
+        projects?: {
+          nodes?: Array<{ id: string }>;
+          pageInfo?: { hasNextPage?: boolean; endCursor?: string };
+        };
+      };
+    };
+    workspaceId ??= body.data?.organization?.id;
+    for (const n of body.data?.projects?.nodes ?? []) projectIds.push(n.id);
+    const pageInfo = body.data?.projects?.pageInfo;
+    cursor = pageInfo?.hasNextPage ? pageInfo.endCursor : undefined;
+  } while (cursor);
+
+  return { workspaceId, projectIds };
+}
+
 export function makeLinearCommand(): Command {
   const linear = new Command('linear')
     .description('Manage Linear integration');
@@ -2105,6 +2356,12 @@ export function makeLinearCommand(): Command {
       .requiredOption('--repo <owner/repo>', 'GitHub repository the mapped project should route tasks to')
       .option('--label <label>', `Label that triggers a task (default: ${DEFAULT_LABEL_FILTER})`, DEFAULT_LABEL_FILTER)
       .option('--team-id <id>', 'Optional Linear team UUID for the project (stored for debug)')
+      .option('--slug <slug>', 'Only look for the project in this workspace (default: every onboarded workspace)')
+      .option(
+        '--workspace-id <uuid>',
+        'Record this owning workspace instead of asking Linear. For when the Linear API is '
+        + 'unreachable — a wrong value routes this project\'s tasks nowhere.',
+      )
       .option('--region <region>', 'AWS region (defaults to configured region)')
       .option('--stack-name <name>', 'CloudFormation stack name', 'backgroundagent-dev')
       .action(async (projectId: string, opts) => {
@@ -2136,10 +2393,60 @@ export function makeLinearCommand(): Command {
 
         const now = new Date().toISOString();
         const ddb = makeDocClient({ region });
+
+        // Record WHICH workspace owns this project. The mapping table is keyed on the
+        // project id alone, so without this the webhook path has nothing to check a
+        // body-supplied `projectId` against and any onboarded workspace can name any
+        // other workspace's project to steer a task at its repository.
+        let ownerWorkspaceId: string | undefined;
+        let ownerLabel: string | undefined;
+        if (opts.workspaceId) {
+          if (!UUID_RE.test(opts.workspaceId)) {
+            console.error(`Invalid --workspace-id value: ${opts.workspaceId}. Expected a UUID.`);
+            process.exit(1);
+          }
+          ownerWorkspaceId = opts.workspaceId;
+          ownerLabel = `${ownerWorkspaceId} (from --workspace-id, not verified with Linear)`;
+        } else {
+          process.stdout.write('→ Resolving which workspace owns the project...');
+          const sm = makeClient(SecretsManagerClient, { region });
+          const registryTableName = await getStackOutput(region, opts.stackName, 'LinearWorkspaceRegistryTableName');
+          const slugs = opts.slug
+            ? [opts.slug as string]
+            : await listOnboardedWorkspaceSlugs({ sm, ddb, registryTableName: registryTableName ?? undefined });
+
+          const owner = await findProjectOwnerWorkspace({
+            projectId,
+            slugs,
+            sm,
+            ddb,
+            registryTableName: registryTableName ?? undefined,
+            region,
+            vaultWorkloadName: await resolveLinearVaultWorkloadName(region, opts.stackName),
+          });
+
+          if (owner.kind !== 'found') {
+            console.log(' ✗');
+            console.error(`Could not determine which workspace owns project ${projectId}.`);
+            console.error('');
+            console.error(`Searched: ${owner.searched.length > 0 ? owner.searched.join(', ') : '(no onboarded workspaces)'}`);
+            for (const e of owner.errors) console.error(`  - ${e}`);
+            console.error('');
+            console.error('Run `bgagent linear list-projects` to confirm the project UUID, or pass');
+            console.error('--slug to narrow the search. If the Linear API is unreachable, pass');
+            console.error('--workspace-id <uuid> to record the owner without verifying it.');
+            process.exit(1);
+          }
+          ownerWorkspaceId = owner.workspaceId;
+          ownerLabel = `${owner.slug} (${ownerWorkspaceId})`;
+          console.log(' ✓');
+        }
+
         await ddb.send(new PutCommand({
           TableName: tableName,
           Item: {
             linear_project_id: projectId,
+            linear_workspace_id: ownerWorkspaceId,
             repo: opts.repo,
             label_filter: opts.label,
             ...(opts.teamId && { team_id: opts.teamId }),
@@ -2150,9 +2457,137 @@ export function makeLinearCommand(): Command {
         }));
 
         console.log(`✓ Mapped Linear project ${projectId} → ${opts.repo}`);
-        console.log(`  Trigger label: ${opts.label}`);
+        console.log(`  Trigger label:    ${opts.label}`);
+        console.log(`  Owning workspace: ${ownerLabel}`);
         if (opts.teamId) {
-          console.log(`  Team: ${opts.teamId}`);
+          console.log(`  Team:             ${opts.teamId}`);
+        }
+      }),
+  );
+
+  linear.addCommand(
+    new Command('backfill-project-workspaces')
+      .description('Record the owning workspace on project mappings that predate that field')
+      .option('--region <region>', 'AWS region (defaults to configured region)')
+      .option('--stack-name <name>', 'CloudFormation stack name', 'backgroundagent-dev')
+      .option('--dry-run', 'Report what would change without writing')
+      .action(async (opts) => {
+        const config = loadConfig();
+        const region = opts.region || config.region;
+
+        const tableName = await getStackOutput(region, opts.stackName, 'LinearProjectMappingTableName');
+        if (!tableName) {
+          console.error('Could not find LinearProjectMappingTableName in stack outputs. Deploy the stack first.');
+          process.exit(1);
+        }
+
+        const ddb = makeDocClient({ region });
+        const sm = makeClient(SecretsManagerClient, { region });
+        const registryTableName = await getStackOutput(region, opts.stackName, 'LinearWorkspaceRegistryTableName');
+
+        // Only rows missing the field are candidates. A row that already names a
+        // workspace is left alone even if it disagrees with Linear — re-pointing a
+        // live mapping is `onboard-project`'s job, not a backfill's.
+        const unbacked: Array<{ projectId: string; repo?: string }> = [];
+        let lastKey: Record<string, unknown> | undefined;
+        do {
+          const page = await ddb.send(new ScanCommand({ TableName: tableName, ExclusiveStartKey: lastKey }));
+          for (const item of page.Items ?? []) {
+            if (!item.linear_workspace_id && typeof item.linear_project_id === 'string') {
+              unbacked.push({ projectId: item.linear_project_id, repo: item.repo as string | undefined });
+            }
+          }
+          lastKey = page.LastEvaluatedKey;
+        } while (lastKey);
+
+        if (unbacked.length === 0) {
+          console.log('✓ Every project mapping already records its owning workspace.');
+          return;
+        }
+        console.log(`${unbacked.length} mapping(s) missing an owning workspace.`);
+        console.log();
+
+        // One pass per workspace rather than one lookup per row: a workspace with N
+        // unbacked projects would otherwise cost N round trips to learn the same thing.
+        const slugs = await listOnboardedWorkspaceSlugs({ sm, ddb, registryTableName: registryTableName ?? undefined });
+        const vaultWorkloadName = await resolveLinearVaultWorkloadName(region, opts.stackName);
+        const ownerByProject = new Map<string, { slug: string; workspaceId: string }>();
+
+        for (const slug of slugs) {
+          const token = await resolveWorkspaceAccessToken({
+            slug, sm, ddb, registryTableName: registryTableName ?? undefined, region, vaultWorkloadName,
+          });
+          if (token.kind !== 'token') {
+            console.log(`  ⚠ ${slug}: ${token.reason} — projects owned here cannot be resolved`);
+            continue;
+          }
+          try {
+            const listed = await listWorkspaceProjectIds({ accessToken: token.accessToken });
+            if (!listed.workspaceId) {
+              console.log(`  ⚠ ${slug}: Linear did not return an organization id`);
+              continue;
+            }
+            for (const id of listed.projectIds) {
+              // First writer wins, and a second claim is a real anomaly worth naming:
+              // one project id must not be visible to two workspaces.
+              const existing = ownerByProject.get(id);
+              if (existing && existing.workspaceId !== listed.workspaceId) {
+                console.log(`  ⚠ project ${id} is visible to both ${existing.slug} and ${slug} — skipping`);
+                ownerByProject.delete(id);
+                continue;
+              }
+              ownerByProject.set(id, { slug, workspaceId: listed.workspaceId });
+            }
+          } catch (err) {
+            console.log(`  ⚠ ${slug}: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }
+
+        let updated = 0;
+        const unresolved: string[] = [];
+        for (const row of unbacked) {
+          const owner = ownerByProject.get(row.projectId);
+          if (!owner) {
+            unresolved.push(row.projectId);
+            continue;
+          }
+          if (opts.dryRun) {
+            console.log(`  would set ${row.projectId} → ${owner.slug} (${owner.workspaceId})`);
+          } else {
+            await ddb.send(new UpdateCommand({
+              TableName: tableName,
+              Key: { linear_project_id: row.projectId },
+              UpdateExpression: 'SET linear_workspace_id = :w, updated_at = :u',
+              // Do not resurrect a row deleted while this command was running, and do
+              // not overwrite a workspace id written concurrently by onboard-project.
+              ConditionExpression: 'attribute_exists(linear_project_id) AND attribute_not_exists(linear_workspace_id)',
+              ExpressionAttributeValues: { ':w': owner.workspaceId, ':u': new Date().toISOString() },
+            })).catch((err: unknown) => {
+              if ((err as { name?: string })?.name === 'ConditionalCheckFailedException') {
+                console.log(`  · ${row.projectId} changed underneath the backfill — skipped`);
+                return;
+              }
+              throw err;
+            });
+            console.log(`  ✓ ${row.projectId} → ${owner.slug} (${owner.workspaceId})`);
+          }
+          updated += 1;
+        }
+
+        console.log();
+        if (opts.dryRun) {
+          console.log(`Dry run: ${updated} mapping(s) would be updated.`);
+        } else {
+          console.log(`✓ Updated ${updated} mapping(s).`);
+        }
+        if (unresolved.length > 0) {
+          console.log();
+          console.log(`⚠ ${unresolved.length} mapping(s) could not be resolved to a workspace:`);
+          for (const id of unresolved) console.log(`    ${id}`);
+          console.log();
+          console.log('These name projects no onboarded workspace can see — a deleted project, or a');
+          console.log('workspace that is no longer installed. Re-run `bgagent linear onboard-project`');
+          console.log('for the ones still in use and remove the rest before enforcement is enabled.');
         }
       }),
   );
diff --git a/cli/src/platform-doctor.ts b/cli/src/platform-doctor.ts
index f5f28aebf..f351bed61 100644
--- a/cli/src/platform-doctor.ts
+++ b/cli/src/platform-doctor.ts
@@ -91,6 +91,7 @@ export async function runPlatformDoctor(
     linearRegistryTableName,
     jiraRegistryTableName,
     linearVaultWorkloadName,
+    linearProjectMappingTableName,
   ] = await Promise.all([
     getStackOutput(region, stackName, 'ApiUrl'),
     getStackOutput(region, stackName, 'UserPoolId'),
@@ -102,6 +103,7 @@ export async function runPlatformDoctor(
     // Absent unless the stack was deployed with the Linear identity vault enabled.
     // Its absence is the signal that no workspace here is vault-managed.
     getStackOutput(region, stackName, 'LinearVaultWorkloadName'),
+    getStackOutput(region, stackName, 'LinearProjectMappingTableName'),
   ]);
 
   const checks: DoctorCheckResult[] = [];
@@ -122,11 +124,92 @@ export async function runPlatformDoctor(
     region, linearRegistryTableName, options.linearProbe, options.linearVerifyRefresh,
     linearVaultWorkloadName,
   ));
+  checks.push(await checkLinearProjectWorkspaces(region, linearProjectMappingTableName));
   checks.push(await checkJiraAppIdentity(region, jiraRegistryTableName));
 
   return checks;
 }
 
+/**
+ * Report project mappings that do not record which workspace owns them.
+ *
+ * The mapping table is keyed on the project id alone, so a row with no
+ * `linear_workspace_id` gives the webhook path nothing to check a body-supplied
+ * `projectId` against. Those rows are the population that must be backfilled before
+ * the enforcement path can move from warning to rejecting — this check is how an
+ * operator knows whether that work is finished.
+ */
+export async function checkLinearProjectWorkspaces(
+  region: string,
+  mappingTableName: string | null,
+): Promise<DoctorCheckResult> {
+  const id = 'linear_project_workspaces';
+  const label = 'Linear project → workspace binding';
+  if (!mappingTableName) {
+    return {
+      id,
+      label,
+      status: 'pass',
+      detail: 'No Linear project mapping table on this stack (integration not deployed).',
+    };
+  }
+
+  try {
+    const ddb = documentClient(region);
+    const rows: Array<{ linear_project_id?: string; linear_workspace_id?: string; status?: string }> = [];
+    let startKey: Record<string, unknown> | undefined;
+    do {
+      const page = await ddb.send(new ScanCommand({
+        TableName: mappingTableName,
+        ProjectionExpression: ['linear_project_id', 'linear_workspace_id', '#status'].join(', '),
+        ExpressionAttributeNames: { '#status': 'status' },
+        ...(startKey && { ExclusiveStartKey: startKey }),
+      }));
+      rows.push(...(page.Items ?? []) as typeof rows);
+      startKey = page.LastEvaluatedKey;
+    } while (startKey);
+
+    const active = rows.filter((row) => row.status === 'active');
+    if (active.length === 0) {
+      return { id, label, status: 'pass', detail: 'No active Linear project mappings yet.' };
+    }
+
+    const unbacked = active.filter((row) => !row.linear_workspace_id);
+    if (unbacked.length === 0) {
+      return {
+        id,
+        label,
+        status: 'pass',
+        detail: `All ${active.length} active Linear project mapping(s) record an owning workspace.`,
+      };
+    }
+
+    // Named, but capped: the point of listing ids is to give the operator somewhere to
+    // start, and an uncapped list on a large install buries every other doctor line.
+    const NAMED_LIMIT = 10;
+    const allIds = unbacked.map((row) => row.linear_project_id ?? '<unknown-project-id>');
+    const projectIds = allIds.length > NAMED_LIMIT
+      ? `${allIds.slice(0, NAMED_LIMIT).join(', ')} (and ${allIds.length - NAMED_LIMIT} more)`
+      : allIds.join(', ');
+    return {
+      id,
+      label,
+      status: 'warn',
+      detail: `${unbacked.length} of ${active.length} active Linear project mapping(s) do not record an `
+        + 'owning workspace, so a webhook naming them cannot be checked against the workspace that '
+        + `signed it: ${projectIds}. Run \`bgagent linear backfill-project-workspaces --stack-name `
+        + '<stack>\` (add `--dry-run` first).',
+    };
+  } catch (err) {
+    return {
+      id,
+      label,
+      status: 'warn',
+      detail: `Could not read the Linear project mapping table: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
 interface JiraRegistryIdentityRow {
   readonly jira_cloud_id?: string;
   readonly status?: string;
diff --git a/cli/test/commands/linear-project-workspace.test.ts b/cli/test/commands/linear-project-workspace.test.ts
new file mode 100644
index 000000000..fe821e972
--- /dev/null
+++ b/cli/test/commands/linear-project-workspace.test.ts
@@ -0,0 +1,298 @@
+/**
+ *  MIT No Attribution
+ *
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy of
+ *  the Software without restriction, including without limitation the rights to
+ *  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ *  the Software, and to permit persons to whom the Software is furnished to do so.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+// Resolving which workspace owns a Linear project. The mapping table is keyed on the
+// project id alone, so this resolution is what lets a later webhook check a
+// body-supplied `projectId` against the workspace that actually signed the delivery.
+import { GetSecretValueCommand, ListSecretsCommand, SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
+import { ScanCommand } from '@aws-sdk/lib-dynamodb';
+import {
+  findProjectOwnerWorkspace,
+  listActiveWorkspaceRows,
+  listOnboardedWorkspaceSlugs,
+  listWorkspaceProjectIds,
+  resolveWorkspaceAccessToken,
+} from '../../src/commands/linear';
+
+const PROJECT_A = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa';
+const PROJECT_B = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb';
+const ORG_ACME = 'c0000000-0000-4000-8000-0000000ac0e1';
+const ORG_RIVAL = 'c0000000-0000-4000-8000-0000000b10a2';
+
+/** A Secrets Manager double that answers with a stored OAuth bundle per slug. */
+function fakeSm(bundles: Record<string, unknown>, secretList?: string[]): SecretsManagerClient {
+  return {
+    send: jest.fn(async (cmd: unknown) => {
+      if (cmd instanceof ListSecretsCommand) {
+        return { SecretList: (secretList ?? []).map((n) => ({ Name: n })) };
+      }
+      if (cmd instanceof GetSecretValueCommand) {
+        const id = (cmd.input as { SecretId?: string }).SecretId ?? '';
+        if (!(id in bundles)) throw new Error(`ResourceNotFoundException: ${id}`);
+        return { SecretString: JSON.stringify(bundles[id]) };
+      }
+      throw new Error('unexpected command');
+    }),
+  } as unknown as SecretsManagerClient;
+}
+
+/** A DynamoDB document-client double that answers Scan with fixed items. */
+function fakeDdb(items: Array<Record<string, unknown>>) {
+  return {
+    send: jest.fn(async (cmd: unknown) => {
+      if (cmd instanceof ScanCommand) return { Items: items };
+      throw new Error('unexpected command');
+    }),
+  } as never;
+}
+
+/**
+ * A Linear GraphQL double keyed by bearer token.
+ *
+ * Keyed by token rather than call order because the property under test is precisely
+ * that the answer follows the credential: a workspace's own token must not report
+ * another workspace's project as visible.
+ */
+function fakeLinear(byToken: Record<string, { org: string; projects: string[] }>) {
+  return jest.fn(async (_url: string, init?: RequestInit) => {
+    const auth = (init?.headers as Record<string, string>)?.Authorization ?? '';
+    const token = auth.replace('Bearer ', '');
+    const ws = byToken[token];
+    if (!ws) return { ok: false, status: 401, json: async () => ({}) } as unknown as Response;
+
+    const body = JSON.parse((init?.body as string) ?? '{}') as {
+      query: string;
+      variables?: { id?: string; after?: string | null };
+    };
+    if (body.query.includes('project(id: $id)')) {
+      const wanted = body.variables?.id ?? '';
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: {
+            organization: { id: ws.org },
+            project: ws.projects.includes(wanted) ? { id: wanted } : null,
+          },
+        }),
+      } as unknown as Response;
+    }
+    return {
+      ok: true,
+      status: 200,
+      json: async () => ({
+        data: {
+          organization: { id: ws.org },
+          projects: {
+            nodes: ws.projects.map((id) => ({ id })),
+            pageInfo: { hasNextPage: false, endCursor: null },
+          },
+        },
+      }),
+    } as unknown as Response;
+  }) as unknown as typeof fetch;
+}
+
+describe('listActiveWorkspaceRows', () => {
+  test('drops rows whose status is not active', async () => {
+    const ddb = fakeDdb([
+      { workspace_slug: 'acme', status: 'active' },
+      { workspace_slug: 'gone', status: 'revoked' },
+      { workspace_slug: 'half-written' },
+    ]);
+    const rows = await listActiveWorkspaceRows(ddb, 'registry');
+    expect(rows.map((r) => r.workspace_slug)).toEqual(['acme']);
+  });
+});
+
+describe('listOnboardedWorkspaceSlugs', () => {
+  test('prefers the registry so a revoked install is not a candidate', async () => {
+    const ddb = fakeDdb([
+      { workspace_slug: 'acme', status: 'active' },
+      { workspace_slug: 'rival', status: 'revoked' },
+    ]);
+    const slugs = await listOnboardedWorkspaceSlugs({
+      sm: fakeSm({}, ['bgagent-linear-oauth-acme', 'bgagent-linear-oauth-rival']),
+      ddb,
+      registryTableName: 'registry',
+    });
+    expect(slugs).toEqual(['acme']);
+  });
+
+  test('falls back to the secret prefix when no registry is configured', async () => {
+    const slugs = await listOnboardedWorkspaceSlugs({
+      sm: fakeSm({}, ['bgagent-linear-oauth-acme', 'bgagent-linear-oauth-rival', 'unrelated-secret']),
+    });
+    expect(slugs).toEqual(['acme', 'rival']);
+  });
+});
+
+describe('resolveWorkspaceAccessToken', () => {
+  test('reads the Secrets Manager bundle when the workspace is not vault-managed', async () => {
+    const result = await resolveWorkspaceAccessToken({
+      slug: 'acme',
+      sm: fakeSm({ 'bgagent-linear-oauth-acme': { access_token: 'tok-acme' } }),
+      region: 'us-east-1',
+      vaultWorkloadName: 'wl',
+    });
+    expect(result).toEqual({ kind: 'token', accessToken: 'tok-acme' });
+  });
+
+  test('reports a reason instead of throwing so a caller can keep scanning workspaces', async () => {
+    const result = await resolveWorkspaceAccessToken({
+      slug: 'missing',
+      sm: fakeSm({}),
+      region: 'us-east-1',
+      vaultWorkloadName: 'wl',
+    });
+    expect(result.kind).toBe('unavailable');
+  });
+
+  test('treats a bundle with no access_token as unavailable, not as an empty token', async () => {
+    const result = await resolveWorkspaceAccessToken({
+      slug: 'acme',
+      sm: fakeSm({ 'bgagent-linear-oauth-acme': { refresh_token: 'r' } }),
+      region: 'us-east-1',
+      vaultWorkloadName: 'wl',
+    });
+    expect(result).toEqual({
+      kind: 'unavailable',
+      reason: 'secret bgagent-linear-oauth-acme is missing access_token',
+    });
+  });
+});
+
+describe('findProjectOwnerWorkspace', () => {
+  const sm = fakeSm({
+    'bgagent-linear-oauth-acme': { access_token: 'tok-acme' },
+    'bgagent-linear-oauth-rival': { access_token: 'tok-rival' },
+  });
+  const fetchImpl = fakeLinear({
+    'tok-acme': { org: ORG_ACME, projects: [PROJECT_A] },
+    'tok-rival': { org: ORG_RIVAL, projects: [PROJECT_B] },
+  });
+
+  test('returns the workspace whose own token can see the project', async () => {
+    const result = await findProjectOwnerWorkspace({
+      projectId: PROJECT_A,
+      slugs: ['acme', 'rival'],
+      sm,
+      region: 'us-east-1',
+      vaultWorkloadName: 'wl',
+      fetchImpl,
+    });
+    expect(result).toEqual({ kind: 'found', slug: 'acme', workspaceId: ORG_ACME });
+  });
+
+  test('does not attribute a project to a workspace that cannot see it', async () => {
+    // The ordering matters: `rival` is searched first and answers `project: null`.
+    // A resolver that took the first organization id it received rather than the one
+    // that actually resolved the project would record ORG_RIVAL here — which is the
+    // exact cross-tenant mapping this whole change exists to prevent.
+    const result = await findProjectOwnerWorkspace({
+      projectId: PROJECT_A,
+      slugs: ['rival', 'acme'],
+      sm,
+      region: 'us-east-1',
+      vaultWorkloadName: 'wl',
+      fetchImpl,
+    });
+    expect(result).toEqual({ kind: 'found', slug: 'acme', workspaceId: ORG_ACME });
+  });
+
+  test('reports not-found rather than guessing when no workspace owns the project', async () => {
+    const result = await findProjectOwnerWorkspace({
+      projectId: 'dddddddd-dddd-4ddd-8ddd-dddddddddddd',
+      slugs: ['acme', 'rival'],
+      sm,
+      region: 'us-east-1',
+      vaultWorkloadName: 'wl',
+      fetchImpl,
+    });
+    expect(result.kind).toBe('not-found');
+  });
+
+  test('records an unreachable workspace as an error and keeps searching the rest', async () => {
+    const result = await findProjectOwnerWorkspace({
+      projectId: PROJECT_A,
+      slugs: ['unknown-slug', 'acme'],
+      sm,
+      region: 'us-east-1',
+      vaultWorkloadName: 'wl',
+      fetchImpl,
+    });
+    expect(result).toEqual({ kind: 'found', slug: 'acme', workspaceId: ORG_ACME });
+  });
+
+  test('surfaces per-workspace errors when nothing resolved', async () => {
+    const result = await findProjectOwnerWorkspace({
+      projectId: PROJECT_A,
+      slugs: ['unknown-slug'],
+      sm,
+      region: 'us-east-1',
+      vaultWorkloadName: 'wl',
+      fetchImpl,
+    });
+    expect(result.kind).toBe('not-found');
+    if (result.kind === 'not-found') {
+      expect(result.errors.join(' ')).toContain('unknown-slug');
+    }
+  });
+});
+
+describe('listWorkspaceProjectIds', () => {
+  test('returns the organization id alongside every visible project', async () => {
+    const listed = await listWorkspaceProjectIds({
+      accessToken: 'tok-acme',
+      fetchImpl: fakeLinear({ 'tok-acme': { org: ORG_ACME, projects: [PROJECT_A, PROJECT_B] } }),
+    });
+    expect(listed).toEqual({ workspaceId: ORG_ACME, projectIds: [PROJECT_A, PROJECT_B] });
+  });
+
+  test('follows pageInfo so projects past the first page are not silently dropped', async () => {
+    // A single-page implementation returns only PROJECT_A here, which during a backfill
+    // would leave PROJECT_B unresolved and its mapping unbacked.
+    let call = 0;
+    const paged = jest.fn(async () => {
+      call += 1;
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: {
+            organization: { id: ORG_ACME },
+            projects: call === 1
+              ? { nodes: [{ id: PROJECT_A }], pageInfo: { hasNextPage: true, endCursor: 'cur' } }
+              : { nodes: [{ id: PROJECT_B }], pageInfo: { hasNextPage: false, endCursor: null } },
+          },
+        }),
+      } as unknown as Response;
+    }) as unknown as typeof fetch;
+
+    const listed = await listWorkspaceProjectIds({ accessToken: 'tok-acme', fetchImpl: paged });
+    expect(listed.projectIds).toEqual([PROJECT_A, PROJECT_B]);
+    expect(call).toBe(2);
+  });
+
+  test('raises on a non-OK response rather than reporting an empty workspace', async () => {
+    const failing = jest.fn(async () => ({ ok: false, status: 500, json: async () => ({}) } as unknown as Response)) as unknown as typeof fetch;
+    await expect(listWorkspaceProjectIds({ accessToken: 'tok', fetchImpl: failing }))
+      .rejects.toThrow('Linear API returned 500');
+  });
+});
diff --git a/cli/test/platform-doctor.test.ts b/cli/test/platform-doctor.test.ts
index 36ed98b13..888d408f9 100644
--- a/cli/test/platform-doctor.test.ts
+++ b/cli/test/platform-doctor.test.ts
@@ -47,6 +47,7 @@ jest.mock('@aws-sdk/client-bedrock', () => ({
 
 import {
   checkJiraAppIdentity,
+  checkLinearProjectWorkspaces,
   runPlatformDoctor,
   type DoctorCheckResult,
 } from '../src/platform-doctor';
@@ -72,6 +73,75 @@ beforeEach(() => {
     (output === 'LinearWorkspaceRegistryTableName' ? REGISTRY : null));
 });
 
+describe('doctor verdict for Linear project → workspace binding', () => {
+  const MAPPING = 'LinearProjectMapping';
+
+  test('warns and names the rows that record no owning workspace', async () => {
+    ddbSendMock.mockResolvedValue({
+      Items: [
+        { linear_project_id: 'proj-backed', linear_workspace_id: 'org-1', status: 'active' },
+        { linear_project_id: 'proj-unbacked', status: 'active' },
+      ],
+    });
+
+    const check = await checkLinearProjectWorkspaces('us-east-1', MAPPING);
+
+    expect(check.status).toBe('warn');
+    expect(check.detail).toContain('proj-unbacked');
+    expect(check.detail).not.toContain('proj-backed');
+    expect(check.detail).toContain('bgagent linear backfill-project-workspaces');
+  });
+
+  test('caps the named ids so a large install does not bury the rest of the report', async () => {
+    ddbSendMock.mockResolvedValue({
+      Items: Array.from({ length: 14 }, (_, i) => ({ linear_project_id: `proj-${i}`, status: 'active' })),
+    });
+
+    const check = await checkLinearProjectWorkspaces('us-east-1', MAPPING);
+
+    expect(check.detail).toContain('(and 4 more)');
+    expect(check.detail).toContain('proj-9');
+    expect(check.detail).not.toContain('proj-10');
+  });
+
+  test('passes once every active mapping records an owning workspace', async () => {
+    ddbSendMock.mockResolvedValue({
+      Items: [{ linear_project_id: 'proj-1', linear_workspace_id: 'org-1', status: 'active' }],
+    });
+
+    const check = await checkLinearProjectWorkspaces('us-east-1', MAPPING);
+
+    expect(check.status).toBe('pass');
+    expect(check.detail).toContain('All 1 active');
+  });
+
+  test('ignores inactive rows — an offboarded mapping is not work to do', async () => {
+    ddbSendMock.mockResolvedValue({
+      Items: [{ linear_project_id: 'proj-old', status: 'inactive' }],
+    });
+
+    expect((await checkLinearProjectWorkspaces('us-east-1', MAPPING)).status).toBe('pass');
+  });
+
+  test('passes when the Linear integration is not deployed', async () => {
+    expect((await checkLinearProjectWorkspaces('us-east-1', null)).status).toBe('pass');
+  });
+
+  test('warns when the mapping table cannot be read', async () => {
+    ddbSendMock.mockRejectedValue(new Error('AccessDeniedException'));
+    const check = await checkLinearProjectWorkspaces('us-east-1', MAPPING);
+    expect(check.status).toBe('warn');
+    expect(check.detail).toContain('AccessDeniedException');
+  });
+
+  test('is reported by the full doctor run', async () => {
+    stackOutputMock.mockImplementation(async (_region: string, _stack: string, output: string) =>
+      (output === 'LinearProjectMappingTableName' ? MAPPING : null));
+    const checks = await runPlatformDoctor({ region: 'us-east-1', stackName: 'Abca' });
+    expect(checks.map((c) => c.id)).toContain('linear_project_workspaces');
+  });
+});
+
 describe('doctor verdict for Jira app identity', () => {
   test('warns when an active tenant still writes through OAuth', async () => {
     ddbSendMock.mockResolvedValue({
diff --git a/docs/guides/LINEAR_SETUP_GUIDE.md b/docs/guides/LINEAR_SETUP_GUIDE.md
index 8c95b9449..9a27fd322 100644
--- a/docs/guides/LINEAR_SETUP_GUIDE.md
+++ b/docs/guides/LINEAR_SETUP_GUIDE.md
@@ -128,6 +128,10 @@ bgagent linear onboard-project <project-uuid> --repo owner/repo
 
 Pass `--label <name>` to use a trigger label other than `bgagent`. Also available: `--team-id` (debug only), `--region`, `--stack-name`.
 
+`onboard-project` asks Linear which workspace owns the project and records it on the mapping, so a later webhook naming that project can be checked against the workspace whose signature it arrived with. Narrow the search with `--slug <slug>` when you know the workspace. If the Linear API is unreachable, `--workspace-id <uuid>` records an owner without verifying it — a wrong value routes the project's tasks nowhere.
+
+Mappings created before this was recorded have no owning workspace. `bgagent platform doctor` reports them, and `bgagent linear backfill-project-workspaces` fills them in (run it with `--dry-run` first).
+
 ### 6. Test
 
 Apply the trigger label to an issue in that project. Within ~30 seconds the agent posts `🤖 Starting on this issue…`, then a PR link when it's done.
diff --git a/docs/src/content/docs/using/Linear-setup-guide.md b/docs/src/content/docs/using/Linear-setup-guide.md
index d2302413e..81a6a0ad9 100644
--- a/docs/src/content/docs/using/Linear-setup-guide.md
+++ b/docs/src/content/docs/using/Linear-setup-guide.md
@@ -132,6 +132,10 @@ bgagent linear onboard-project <project-uuid> --repo owner/repo
 
 Pass `--label <name>` to use a trigger label other than `bgagent`. Also available: `--team-id` (debug only), `--region`, `--stack-name`.
 
+`onboard-project` asks Linear which workspace owns the project and records it on the mapping, so a later webhook naming that project can be checked against the workspace whose signature it arrived with. Narrow the search with `--slug <slug>` when you know the workspace. If the Linear API is unreachable, `--workspace-id <uuid>` records an owner without verifying it — a wrong value routes the project's tasks nowhere.
+
+Mappings created before this was recorded have no owning workspace. `bgagent platform doctor` reports them, and `bgagent linear backfill-project-workspaces` fills them in (run it with `--dry-run` first).
+
 ### 6. Test
 
 Apply the trigger label to an issue in that project. Within ~30 seconds the agent posts `🤖 Starting on this issue…`, then a PR link when it's done.

From 1825e1a6a44b385e5b3ec0697f602e6131a89029 Mon Sep 17 00:00:00 2001
From: Sphia Sadek <isadeks@gmail.com>
Date: Fri, 4 Sep 2026 13:23:04 -0400
Subject: [PATCH 2/9] feat(linear): check a project mapping against the
 workspace that sent the event
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The processor resolved the target repository from the body-supplied `projectId`
alone. The mapping table is keyed on that id with no workspace attribute, so a
workspace holding its own valid signing secret could sign an event with its own
`organizationId` while naming another workspace's project, and the processor
would run an agent task on that workspace's repository. Nothing about that
attack needs a shared or stack-wide secret, which is why signature-level fixes
do not reach it.

Now the mapping's `linear_workspace_id` is checked against the event's
`organizationId` and a mismatch drops the delivery.

Dropped rather than answered. The reply would be posted into the sender's own
workspace, and "that project belongs to someone else" both confirms the project
exists and tells a prober the attempt was seen. The log line carries both ids
and is the diagnostic surface instead.

A mapping with no owning workspace recorded still proceeds, and warns. Rejecting
those on deploy would break every install that has not run
`backfill-project-workspaces` yet; turning it into a rejection is a later step,
gated per environment once `platform doctor` reports the backfill clean.

Both rejection tests were confirmed to fail with the check disabled. The
no-workspace-id case originally passed either way — an event with no
`organizationId` never creates a task regardless, because it fails later at
attribution — so it asserts the guard's own log line instead, which is the only
thing that distinguishes a drop here from a drop there.
---
 cdk/src/handlers/linear-webhook-processor.ts  | 32 ++++++++
 .../handlers/linear-webhook-processor.test.ts | 79 +++++++++++++++++++
 2 files changed, 111 insertions(+)

diff --git a/cdk/src/handlers/linear-webhook-processor.ts b/cdk/src/handlers/linear-webhook-processor.ts
index 66a770acb..5dc0688cd 100644
--- a/cdk/src/handlers/linear-webhook-processor.ts
+++ b/cdk/src/handlers/linear-webhook-processor.ts
@@ -718,6 +718,38 @@ export async function handler(event: ProcessorEvent): Promise<void> {
       mappingItem = mapping.Item;
     }
   }
+
+  // The mapping table is keyed on the project id alone, so `projectId` selects a
+  // repository on its own — and it arrives in the request body. Check the mapping
+  // against the workspace the delivery claims to be from, so naming another
+  // workspace's project cannot steer a task at that workspace's repository.
+  //
+  // Drop rather than reply. The reply would go to the sender's own workspace, and
+  // "that project belongs to someone else" both confirms the project exists and tells
+  // a prober the attempt was seen. The log line is the diagnostic surface instead.
+  const mappedWorkspaceId = mappingItem?.linear_workspace_id as string | undefined;
+  if (mappingItem && mappedWorkspaceId && mappedWorkspaceId !== payload.organizationId) {
+    logger.warn('Linear project is mapped to a different workspace than this webhook — dropping', {
+      issue_id: issue.id,
+      linear_project_id: projectId,
+      event_workspace_id: payload.organizationId,
+      mapped_workspace_id: mappedWorkspaceId,
+    });
+    return;
+  }
+  if (mappingItem && !mappedWorkspaceId) {
+    // Allowed for now: rows written before the owning workspace was recorded have
+    // nothing to check against, and rejecting them would break working installs on
+    // deploy. `bgagent linear backfill-project-workspaces` fills them in and
+    // `bgagent platform doctor` reports what is left, which is what makes it safe to
+    // turn this into a rejection later.
+    logger.warn('Linear project mapping records no owning workspace — cannot verify the tenant', {
+      issue_id: issue.id,
+      linear_project_id: projectId,
+      event_workspace_id: payload.organizationId,
+    });
+  }
+
   const labelFilter = (mappingItem?.label_filter as string | undefined) ?? DEFAULT_LABEL_FILTER;
 
   // ``<base>:help`` — post a one-time explainer of what the trigger labels do
diff --git a/cdk/test/handlers/linear-webhook-processor.test.ts b/cdk/test/handlers/linear-webhook-processor.test.ts
index 45f8b8c61..fc0964af3 100644
--- a/cdk/test/handlers/linear-webhook-processor.test.ts
+++ b/cdk/test/handlers/linear-webhook-processor.test.ts
@@ -90,6 +90,7 @@ process.env.GUARDRAIL_VERSION = '1';
 
 import { handler } from '../../src/handlers/linear-webhook-processor';
 import { LinearAttachmentError } from '../../src/handlers/shared/linear-attachments';
+import { logger } from '../../src/handlers/shared/logger';
 
 function eventWith(payload: Record<string, unknown>): { raw_body: string } {
   return { raw_body: JSON.stringify(payload) };
@@ -311,6 +312,84 @@ describe('linear-webhook-processor handler', () => {
     });
   });
 
+  // The mapping table is keyed on the project id alone and `projectId` arrives in the
+  // request body, so the row's owning workspace is the only thing standing between a
+  // signed event and another tenant's repository.
+  describe('project → workspace binding', () => {
+    test('drops an event whose project is mapped to a different workspace', async () => {
+      ddbSend.mockResolvedValueOnce({
+        Item: { repo: 'victim/repo', status: 'active', linear_workspace_id: 'org-victim' },
+      });
+
+      await handler(eventWith(issue()));
+
+      expect(createTaskCoreMock).not.toHaveBeenCalled();
+      // Silent on the wire: replying would confirm the project exists to whoever named
+      // it, and the reply would land in the sender's own workspace.
+      expect(reportIssueFailureMock).not.toHaveBeenCalled();
+    });
+
+    test('proceeds when the mapping names the workspace the event came from', async () => {
+      ddbSend
+        .mockResolvedValueOnce({
+          Item: { repo: 'org/repo', status: 'active', linear_workspace_id: 'org-1' },
+        })
+        .mockResolvedValueOnce({ Item: { platform_user_id: 'cognito-user-1', status: 'active' } });
+      createTaskCoreMock.mockResolvedValueOnce({ statusCode: 201, body: JSON.stringify({ data: { task_id: 'T1' } }) });
+
+      await handler(eventWith(issue()));
+
+      expect(createTaskCoreMock).toHaveBeenCalledTimes(1);
+      expect(createTaskCoreMock.mock.calls[0][0].repo).toBe('org/repo');
+    });
+
+    test('still proceeds when the mapping predates the owning-workspace field', async () => {
+      // Back-compat: rejecting unbacked rows on deploy would break every install that
+      // has not run the backfill yet. Enforcement for these is a later, gated step.
+      const warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => undefined);
+      try {
+        ddbSend
+          .mockResolvedValueOnce({ Item: { repo: 'org/repo', status: 'active' } })
+          .mockResolvedValueOnce({ Item: { platform_user_id: 'cognito-user-1', status: 'active' } });
+        createTaskCoreMock.mockResolvedValueOnce({ statusCode: 201, body: JSON.stringify({ data: { task_id: 'T1' } }) });
+
+        await handler(eventWith(issue()));
+
+        expect(createTaskCoreMock).toHaveBeenCalledTimes(1);
+        // The warning is the only signal that this install still has rows to backfill,
+        // so it is asserted rather than left to the source comment.
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining('records no owning workspace'),
+          expect.objectContaining({ linear_project_id: 'project-1' }),
+        );
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+
+    // Asserted on the log rather than on `createTaskCore`, because an event with no
+    // workspace id never creates a task anyway — it fails later at attribution. Only
+    // the guard's own line proves the drop happened HERE, at the binding check.
+    test('drops at the binding check when the event carries no workspace id', async () => {
+      const warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => undefined);
+      try {
+        ddbSend.mockResolvedValueOnce({
+          Item: { repo: 'org/repo', status: 'active', linear_workspace_id: 'org-1' },
+        });
+
+        await handler(eventWith(issue({ organizationId: undefined })));
+
+        expect(createTaskCoreMock).not.toHaveBeenCalled();
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining('mapped to a different workspace'),
+          expect.objectContaining({ mapped_workspace_id: 'org-1' }),
+        );
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+  });
+
   test('fires on update when labelIds newly include the trigger label', async () => {
     ddbSend
       .mockResolvedValueOnce({ Item: { repo: 'org/repo', status: 'active' } })

From db814cd389d40a4fcc039b23f5f8e5f6e01576d8 Mon Sep 17 00:00:00 2001
From: Sphia Sadek <isadeks@gmail.com>
Date: Tue, 8 Sep 2026 13:50:57 -0400
Subject: [PATCH 3/9] feat(linear): record whether a workspace owns its webhook
 signing secret
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verification could not tell a workspace's own signing secret from a copy of
another workspace's, because the only available signal was value equality
against the stack-wide secret — and that signal is wrong. A healthy
single-workspace install also holds a secret equal to the stack-wide copy, since
the first install stamps the same real secret into both slots. Rejecting on
equality would 401 exactly the deployments that are safe.

So ownership is now recorded by provenance instead: `webhook_secret_owned` on the
registry row, written from where the value came from. `setup` sets it when the
operator supplied the secret for this workspace or when a stored `lin_wh_` value
differs from the stack-wide one. `update-webhook-secret` sets it too — that is
the remediation path, and without it an operator could paste the correct secret
and see no change in how the workspace is treated.

Only a literal `true` is read back as proof. Absence means "not proven", which is
what every row predating this field is, and is deliberately not the same as
"proven not owned".

`update-webhook-secret` gains `--stack-name` so it can reach the registry, and
fails loudly if the secret write succeeds but the provenance write does not —
silence there would leave the operator believing a fix landed while the state
verification reads is unchanged.

Two things found while building this, both worth knowing:

`mirror-stackwide` — the branch that copies the first workspace's secret into an
additional workspace — is already unreachable from `setup` on current main. #831
added an up-front prompt that throws when neither a supplied nor a legitimately
stored secret exists, which is the only way into that branch. The refusal added
here is therefore a safety net, not a live fix; it is extracted as
`assertMirrorIsSafe` and unit-tested directly, because a guard reachable only
through dead code is otherwise an untested guard. The remaining exposure is rows
written by older releases and not re-run since.

The provenance derivation cannot currently evaluate false, so mutating it to a
literal `true` leaves every test passing. That is semantic equivalence under the
current preconditions rather than a test gap — there is no reachable input that
distinguishes them. It is kept as a derivation because it becomes load-bearing if
that up-front prompt is ever relaxed, and the resulting failure would be silent.
---
 .../handlers/shared/linear-oauth-resolver.ts  |  20 +++
 .../shared/linear-oauth-resolver.test.ts      |  42 +++++++
 cli/src/commands/linear.ts                    | 119 +++++++++++++++++-
 .../commands/linear-project-workspace.test.ts |  32 +++++
 .../commands/linear-setup-webhook.test.ts     |  54 ++++++++
 docs/guides/LINEAR_SETUP_GUIDE.md             |   6 +
 .../content/docs/using/Linear-setup-guide.md  |   6 +
 7 files changed, 275 insertions(+), 4 deletions(-)

diff --git a/cdk/src/handlers/shared/linear-oauth-resolver.ts b/cdk/src/handlers/shared/linear-oauth-resolver.ts
index b44b0e6cc..7ae51a736 100644
--- a/cdk/src/handlers/shared/linear-oauth-resolver.ts
+++ b/cdk/src/handlers/shared/linear-oauth-resolver.ts
@@ -113,6 +113,22 @@ export interface RegistryRow {
    * stored; those fall back to the derived form.
    */
   readonly vault_user_id?: string;
+  /**
+   * Whether this workspace's `webhook_signing_secret` is provably its OWN, rather than
+   * a copy of another workspace's.
+   *
+   * Recorded by provenance — which `bgagent linear setup` branch produced the value —
+   * and NOT inferred by comparing the stored secret against the stack-wide one. Value
+   * equality cannot tell the two apart: a healthy single-workspace install also holds a
+   * secret equal to the stack-wide copy, because the first install stamps the same real
+   * secret into both slots. Rejecting on equality would therefore 401 exactly the
+   * deployments that are safe.
+   *
+   * Absent on rows written before this was recorded, which is why the reader treats
+   * absence as "not proven" rather than as `false`, and only acts on it where sharing
+   * can actually cross a tenant boundary — a stack with two or more active workspaces.
+   */
+  readonly webhook_secret_owned?: boolean;
   /**
    * Why `status` was flipped to `revoked`, as written by {@link markWorkspaceRevoked}.
    *
@@ -857,6 +873,10 @@ function parseRegistryRow(rawItem: unknown, linearWorkspaceId: string): Registry
     // Distinguishes a latch built on Linear's own refusal from one built on an
     // inference the vault path can re-test. See RegistryRow.revoked_reason.
     ...(typeof item.revoked_reason === 'string' && { revoked_reason: item.revoked_reason }),
+    // Only a literal `true` counts as proof of ownership. A missing field, or any
+    // other value, leaves it absent so the reader sees "not proven" — the safe
+    // reading for the rows this field was added for, which predate it entirely.
+    ...(item.webhook_secret_owned === true && { webhook_secret_owned: true }),
   };
   registryCache.set(linearWorkspaceId, { value: row, expiresAt: Date.now() + REGISTRY_CACHE_TTL_MS });
   return row;
diff --git a/cdk/test/handlers/shared/linear-oauth-resolver.test.ts b/cdk/test/handlers/shared/linear-oauth-resolver.test.ts
index dcc16c416..8ed7c48ab 100644
--- a/cdk/test/handlers/shared/linear-oauth-resolver.test.ts
+++ b/cdk/test/handlers/shared/linear-oauth-resolver.test.ts
@@ -23,6 +23,7 @@ import {
   clearWorkspaceRevocation,
   getOauthSecret,
   getOauthSecretStrict,
+  getRegistryRowStrict,
   invalidateLinearOauthCache,
   isRefreshTokenRejection,
   isTokenExpiring,
@@ -1287,3 +1288,44 @@ describe('a vault-managed bundle carries no grant, and must still verify webhook
     expect(fetched).toBeNull();
   });
 });
+
+describe('webhook_secret_owned — provenance, not value equality', () => {
+  beforeEach(() => _resetCachesForTesting());
+
+  function rowWith(extra: Record<string, unknown>) {
+    return {
+      send: jest.fn().mockResolvedValue({
+        Item: {
+          linear_workspace_id: 'ws-1',
+          workspace_slug: 'acme',
+          oauth_secret_arn: 'arn:secret:acme',
+          status: 'active',
+          ...extra,
+        },
+      }),
+    } as unknown as Parameters<typeof getRegistryRowStrict>[0];
+  }
+
+  test('carries a recorded true through to the reader', async () => {
+    const row = await getRegistryRowStrict(rowWith({ webhook_secret_owned: true }), 'registry', 'ws-1');
+    expect(row?.webhook_secret_owned).toBe(true);
+  });
+
+  test('leaves the field absent when the row predates it', async () => {
+    // Absent must not read as `false`: the reader distinguishes "not proven" from
+    // "proven not owned", and every row written before this field is the former.
+    const row = await getRegistryRowStrict(rowWith({}), 'registry', 'ws-1');
+    expect(row?.webhook_secret_owned).toBeUndefined();
+  });
+
+  test.each([['false-ish string', 'true'], ['number', 1], ['explicit false', false]] as const)(
+    'refuses to treat a %s as proof of ownership',
+    async (_label, value) => {
+      // Only a literal boolean `true` counts. A truthy-but-not-true value reaching this
+      // field would otherwise silently grant the workspace the same standing as one the
+      // operator actually supplied a secret for.
+      const row = await getRegistryRowStrict(rowWith({ webhook_secret_owned: value }), 'registry', 'ws-1');
+      expect(row?.webhook_secret_owned).toBeUndefined();
+    },
+  );
+});
diff --git a/cli/src/commands/linear.ts b/cli/src/commands/linear.ts
index 6706a29b7..58888a1d6 100644
--- a/cli/src/commands/linear.ts
+++ b/cli/src/commands/linear.ts
@@ -643,6 +643,44 @@ export async function listOnboardedWorkspaceSlugs(args: {
   return collected;
 }
 
+/**
+ * Refuse to copy the stack-wide signing secret into a workspace when another active
+ * workspace exists.
+ *
+ * Mirroring is only correct for the first/only workspace, where the stack-wide value IS
+ * that workspace's own secret. For an additional workspace it installs a DIFFERENT
+ * tenant's key, after which both verify under the same secret and either can sign an
+ * event whose routing values the other's are read from.
+ *
+ * Extracted rather than inlined at the one call site because that call site is currently
+ * unreachable: `setup` collects this workspace's own secret up front and throws when
+ * neither a supplied nor a legitimately-stored one exists, so the mirror branch cannot
+ * be entered from there. An unreachable guard is an untested guard, and this keeps the
+ * rule itself exercisable — and enforced if that prompt is ever relaxed.
+ *
+ * @param activeRows - active workspace-registry rows.
+ * @param selfWorkspaceId - the workspace being set up, excluded from the count.
+ * @param slug - workspace slug, for the remedy in the error text.
+ */
+export function assertMirrorIsSafe(
+  activeRows: ReadonlyArray<Record<string, unknown>>,
+  selfWorkspaceId: string,
+  slug: string,
+): void {
+  const others = activeRows
+    .map((r) => r.linear_workspace_id as string | undefined)
+    .filter((id): id is string => Boolean(id) && id !== selfWorkspaceId);
+  if (others.length === 0) return;
+  throw new CliError(
+    `Workspace '${slug}' has no signing secret of its own, and this stack already has `
+    + `${others.length} other active Linear workspace(s).\n`
+    + '  Mirroring the stack-wide secret would give this workspace another tenant\'s key,\n'
+    + '  letting either one sign events the other\'s routing values are read from.\n'
+    + `  Re-run with --webhook-secret <lin_wh_…> read from '${slug}'s own Linear app, or set\n`
+    + `  it afterwards with \`bgagent linear update-webhook-secret ${slug}\`.`,
+  );
+}
+
 /** Outcome of resolving a usable Linear access token for one workspace. */
 export type WorkspaceTokenResult =
   | { readonly kind: 'token'; readonly accessToken: string }
@@ -1583,6 +1621,26 @@ export function makeLinearCommand(): Command {
         // prefix-route Linear issue lookups (e.g. ENG-42 → the workspace
         // owning the ENG team) instead of scanning every active workspace.
         const teamKeys = await queryLinearTeamKeys(`Bearer ${linearAccessToken}`);
+
+        // Provenance of the signing secret, recorded so verification can tell a
+        // workspace's OWN secret from a copy of another workspace's. Derived from where
+        // the value came from, never from comparing it to the stack-wide copy: a healthy
+        // single-workspace install holds a secret equal to that copy, because the first
+        // install stamps the same real secret into both slots.
+        //
+        // Either input proves ownership. `suppliedWebhookSecret` was read off the app
+        // being onboarded moments ago, and `holdsOwnWebhookSecret` means a stored
+        // `lin_wh_…` that differs from the stack-wide value. Anything else either threw
+        // above (nothing supplied, nothing legitimate stored) or is inherited, and
+        // inherited is precisely what must not be recorded as owned.
+        //
+        // Today this cannot evaluate false — the up-front prompt refuses the one case
+        // that would produce it — so it reads as a constant and no test can distinguish
+        // it from `true`. It is written as a derivation rather than a literal because it
+        // becomes load-bearing the moment that prompt is relaxed, and the failure would
+        // otherwise be silent: a workspace recorded as owning a secret it inherited.
+        const webhookSecretOwned = Boolean(suppliedWebhookSecret) || holdsOwnWebhookSecret;
+
         await ddb.send(new PutCommand({
           TableName: workspaceRegistryTable!,
           Item: {
@@ -1593,6 +1651,10 @@ export function makeLinearCommand(): Command {
             installed_at: now,
             updated_at: now,
             status: 'active',
+            // Written only when true. An explicit `false` would be indistinguishable
+            // from the absent field on rows predating this, and both mean the same
+            // thing to the reader — not proven.
+            ...(webhookSecretOwned ? { webhook_secret_owned: true } : {}),
             ...(teamKeys.length > 0 ? { team_keys: teamKeys } : {}),
             // Vault substrate: the provider to mint from, and the subject the grant
             // is bound to. vault_user_id is stored rather than derived because it is
@@ -1679,10 +1741,21 @@ export function makeLinearCommand(): Command {
           console.log('  ✓ Preserving this workspace\'s existing webhook signing secret (re-run — not overwriting)');
           webhookSigningSecret = secretAction.secret;
         } else if (secretAction.kind === 'mirror-stackwide') {
-          // No per-workspace secret yet, but the stack-wide one is set. Safe to
-          // mirror ONLY when this is the first/only workspace — for a genuinely
-          // new ADDITIONAL workspace the stack-wide secret is the wrong one, so
-          // warn that the operator should verify (or run `update-webhook-secret`).
+          // Mirroring is only ever correct for the first/only workspace: the stack-wide
+          // value IS that workspace's own secret. For an additional workspace it copies
+          // a DIFFERENT tenant's secret into this one's bundle, after which both verify
+          // under the same key and either can sign an event the other's routing values
+          // would be trusted from. Refuse instead of warning.
+          //
+          // Currently a safety net rather than a live path: `setup` collects this
+          // workspace's own secret up front and throws when neither a supplied nor a
+          // legitimately-stored one exists, so this branch is unreachable from there.
+          // Kept, and made to refuse, so the invariant survives that prompt changing.
+          assertMirrorIsSafe(
+            await listActiveWorkspaceRows(ddb, workspaceRegistryTable!),
+            identity.organization.id,
+            slug,
+          );
           console.log('  ✓ No per-workspace secret yet; mirroring the stack-wide signing secret');
           console.log('    (if this is an ADDITIONAL workspace, its Linear webhook secret differs —');
           console.log(`     run \`bgagent linear update-webhook-secret ${slug}\` with this workspace's secret.)`);
@@ -2101,6 +2174,7 @@ export function makeLinearCommand(): Command {
       .description('Update the per-workspace webhook signing secret without re-running OAuth')
       .argument('<slug>', 'Linear workspace urlKey (e.g. "acme" from linear.app/acme/...)')
       .option('--region <region>', 'AWS region (defaults to configured region)')
+      .option('--stack-name <name>', 'CloudFormation stack name', 'backgroundagent-dev')
       .action(async (slug: string, opts) => {
         // Use case: rotation, recovery from misconfig, or first-time
         // configuration after Linear regenerated the signing secret.
@@ -2181,6 +2255,43 @@ export function makeLinearCommand(): Command {
         };
         await upsertOauthSecret(sm, secretName, merged, slug);
 
+        // Record that this workspace now holds a secret of its own. The operator just
+        // read it off this workspace's Linear app, which is the only evidence of
+        // ownership that exists — and without recording it, verification cannot tell
+        // this repaired workspace from one still carrying an inherited copy, so the
+        // repair would appear to do nothing.
+        //
+        // A hard failure rather than a warning: the secret write above already
+        // succeeded, so a silent miss here leaves the operator believing the fix landed
+        // when the state that verification reads is unchanged.
+        const registryTableName = await getStackOutput(region, opts.stackName, 'LinearWorkspaceRegistryTableName');
+        if (registryTableName) {
+          try {
+            await makeDocClient({ region }).send(new UpdateCommand({
+              TableName: registryTableName,
+              Key: { linear_workspace_id: stored.workspace_id },
+              UpdateExpression: 'SET webhook_secret_owned = :t, updated_at = :u',
+              ConditionExpression: 'attribute_exists(linear_workspace_id)',
+              ExpressionAttributeValues: { ':t': true, ':u': new Date().toISOString() },
+            }));
+            console.log('  ✓ Recorded that this workspace owns its signing secret');
+          } catch (err) {
+            if ((err as { name?: string })?.name === 'ConditionalCheckFailedException') {
+              throw new CliError(
+                `Updated the signing secret, but workspace '${slug}' has no registry row `
+                + `(${stored.workspace_id}).\n  Run \`bgagent linear setup ${slug}\` so the workspace `
+                + 'is registered; the secret you just entered will be preserved.',
+              );
+            }
+            throw new CliError(
+              'Updated the signing secret, but could not record its provenance: '
+              + `${err instanceof Error ? err.message : String(err)}\n`
+              + '  Re-run this command once the registry table is writable, otherwise this\n'
+              + '  workspace is still treated as carrying an inherited secret.',
+            );
+          }
+        }
+
         console.log();
         console.log(`✅ Updated webhook signing secret for '${slug}'.`);
         console.log();
diff --git a/cli/test/commands/linear-project-workspace.test.ts b/cli/test/commands/linear-project-workspace.test.ts
index fe821e972..88b9aae7f 100644
--- a/cli/test/commands/linear-project-workspace.test.ts
+++ b/cli/test/commands/linear-project-workspace.test.ts
@@ -23,6 +23,7 @@
 import { GetSecretValueCommand, ListSecretsCommand, SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
 import { ScanCommand } from '@aws-sdk/lib-dynamodb';
 import {
+  assertMirrorIsSafe,
   findProjectOwnerWorkspace,
   listActiveWorkspaceRows,
   listOnboardedWorkspaceSlugs,
@@ -296,3 +297,34 @@ describe('listWorkspaceProjectIds', () => {
       .rejects.toThrow('Linear API returned 500');
   });
 });
+
+describe('assertMirrorIsSafe', () => {
+  const SELF = 'org-self';
+
+  test('allows the mirror when this is the only active workspace', () => {
+    expect(() => assertMirrorIsSafe([{ linear_workspace_id: SELF }], SELF, 'acme')).not.toThrow();
+  });
+
+  test('allows it on a genuinely empty registry', () => {
+    expect(() => assertMirrorIsSafe([], SELF, 'acme')).not.toThrow();
+  });
+
+  test('refuses when another active workspace would be the source of the secret', () => {
+    expect(() => assertMirrorIsSafe(
+      [{ linear_workspace_id: SELF }, { linear_workspace_id: 'org-other' }],
+      SELF,
+      'acme',
+    )).toThrow(/already has 1 other active Linear workspace/);
+  });
+
+  test('names the remedy, since refusing mid-setup is only useful with a way forward', () => {
+    expect(() => assertMirrorIsSafe([{ linear_workspace_id: 'org-other' }], SELF, 'acme'))
+      .toThrow(/update-webhook-secret acme/);
+  });
+
+  test('ignores rows with no workspace id rather than counting them as tenants', () => {
+    // A half-written registry row is not another tenant, and treating it as one would
+    // block a legitimate first-workspace mirror.
+    expect(() => assertMirrorIsSafe([{ workspace_slug: 'half' }], SELF, 'acme')).not.toThrow();
+  });
+});
diff --git a/cli/test/commands/linear-setup-webhook.test.ts b/cli/test/commands/linear-setup-webhook.test.ts
index 784f87dec..469e88c9c 100644
--- a/cli/test/commands/linear-setup-webhook.test.ts
+++ b/cli/test/commands/linear-setup-webhook.test.ts
@@ -297,5 +297,59 @@ describe('linear setup — second-workspace re-run preserves the per-workspace w
       .map((c) => c[0])
       .find((cmd) => cmd instanceof PutCommand && cmd.input.TableName === 'registry-table');
     expect(registryPut).toBeDefined();
+
+    // Provenance: this workspace kept a `lin_wh_` secret that differs from the
+    // stack-wide value, which is what proves the secret is its own. Recording it is
+    // what later lets verification tell this workspace from one carrying an inherited
+    // copy — and the flag must be a literal `true`, since the reader accepts nothing
+    // else as proof.
+    expect((registryPut as InstanceType<typeof PutCommand>).input.Item?.webhook_secret_owned).toBe(true);
+  });
+
+  test('records ownership when the operator supplies this workspace\'s own secret', async () => {
+    // The other reachable provenance path: nothing stored, operator pastes the secret
+    // read off the app being onboarded. Ownership is proven by where the value came
+    // from, so it must be recorded here too — otherwise a first install looks
+    // indistinguishable from one that inherited its secret.
+    smSend.mockImplementation((cmd: unknown) => {
+      if (cmd instanceof GetSecretValueCommand) {
+        const id = (cmd as GetSecretValueCommand).input.SecretId;
+        if (id === WEBHOOK_ARN) return Promise.resolve({ SecretString: OTHER_WS_SECRET });
+        return Promise.reject(new ResourceNotFoundException({ message: 'no', $metadata: {} }));
+      }
+      if (cmd instanceof CreateSecretCommand) {
+        return Promise.reject(new ResourceExistsException({ message: 'exists', $metadata: {} }));
+      }
+      if (cmd instanceof PutSecretValueCommand) return Promise.resolve({ ARN: 'arn:x' });
+      return Promise.resolve({});
+    });
+
+    const cfgSpy = jest.spyOn(configMod, 'loadConfig').mockReturnValue(
+      { region: 'us-west-2', api_url: 'https://api.example.test' } as ReturnType<typeof configMod.loadConfig>,
+    );
+    const credSpy = jest.spyOn(configMod, 'loadCredentials').mockReturnValue(
+      { id_token: FAKE_ID_TOKEN } as ReturnType<typeof configMod.loadCredentials>,
+    );
+    const logSpy = jest.spyOn(console, 'log').mockImplementation((...args: unknown[]) => {
+      const line = args.map(String).join(' ');
+      const m = line.match(/[?&]state=([^&\s]+)/);
+      if (m) capturedState = decodeURIComponent(m[1]);
+    });
+    try {
+      await makeLinearCommand().parseAsync([
+        'node', 'bgagent', 'setup', 'demo',
+        '--client-id', 'cid', '--client-secret', 'csecret',
+        '--webhook-secret', 'lin_wh_suppliedByOperator', '--no-browser',
+      ]);
+    } finally {
+      cfgSpy.mockRestore();
+      credSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+
+    const registryPut = ddbSend.mock.calls
+      .map((c) => c[0])
+      .find((cmd) => cmd instanceof PutCommand && cmd.input.TableName === 'registry-table');
+    expect((registryPut as InstanceType<typeof PutCommand>).input.Item?.webhook_secret_owned).toBe(true);
   });
 });
diff --git a/docs/guides/LINEAR_SETUP_GUIDE.md b/docs/guides/LINEAR_SETUP_GUIDE.md
index 9a27fd322..e6f5e3ca8 100644
--- a/docs/guides/LINEAR_SETUP_GUIDE.md
+++ b/docs/guides/LINEAR_SETUP_GUIDE.md
@@ -132,6 +132,12 @@ Pass `--label <name>` to use a trigger label other than `bgagent`. Also availabl
 
 Mappings created before this was recorded have no owning workspace. `bgagent platform doctor` reports them, and `bgagent linear backfill-project-workspaces` fills them in (run it with `--dry-run` first).
 
+### Signing secrets in a multi-workspace install
+
+Every workspace must have its own webhook signing secret, read from its own Linear app. `setup` asks for it and refuses to continue without one, and records on the workspace's registry row that the secret is genuinely that workspace's.
+
+A workspace onboarded by an older release may instead be holding a copy of the first workspace's secret. Two workspaces sharing one secret means either can produce a delivery the other's signature check accepts. Fix it per workspace with `bgagent linear update-webhook-secret <slug>`, which now also records that the secret is that workspace's own — pass `--stack-name` if you are not using the default.
+
 ### 6. Test
 
 Apply the trigger label to an issue in that project. Within ~30 seconds the agent posts `🤖 Starting on this issue…`, then a PR link when it's done.
diff --git a/docs/src/content/docs/using/Linear-setup-guide.md b/docs/src/content/docs/using/Linear-setup-guide.md
index 81a6a0ad9..bdd4f1a52 100644
--- a/docs/src/content/docs/using/Linear-setup-guide.md
+++ b/docs/src/content/docs/using/Linear-setup-guide.md
@@ -136,6 +136,12 @@ Pass `--label <name>` to use a trigger label other than `bgagent`. Also availabl
 
 Mappings created before this was recorded have no owning workspace. `bgagent platform doctor` reports them, and `bgagent linear backfill-project-workspaces` fills them in (run it with `--dry-run` first).
 
+### Signing secrets in a multi-workspace install
+
+Every workspace must have its own webhook signing secret, read from its own Linear app. `setup` asks for it and refuses to continue without one, and records on the workspace's registry row that the secret is genuinely that workspace's.
+
+A workspace onboarded by an older release may instead be holding a copy of the first workspace's secret. Two workspaces sharing one secret means either can produce a delivery the other's signature check accepts. Fix it per workspace with `bgagent linear update-webhook-secret <slug>`, which now also records that the secret is that workspace's own — pass `--stack-name` if you are not using the default.
+
 ### 6. Test
 
 Apply the trigger label to an issue in that project. Within ~30 seconds the agent posts `🤖 Starting on this issue…`, then a PR link when it's done.

From 29f681190d723e999a188527c8a149d629762e18 Mon Sep 17 00:00:00 2001
From: Sphia Sadek <isadeks@gmail.com>
Date: Tue, 8 Sep 2026 14:28:03 -0400
Subject: [PATCH 4/9] feat(linear): refuse a signing secret that cannot attest
 which workspace sent a delivery
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The processor routes from identifiers in the request body, so verification has to
establish WHICH tenant sent a delivery — not merely that the sender knows a secret
this stack accepts. Two secrets fail that test: the stack-wide one, which is bound
to no workspace, and a per-workspace one that is a copy of another workspace's,
which older releases could install.

Both are now refused, and both only where they can actually cross a boundary:

- `verifyLinearRequestForWorkspace` gains a `shared-secret` outcome. A matching
  signature on a row that does not record the secret as its own is rejected when
  another workspace is active. Fatal like `mismatch`, for the same reason —
  falling through would re-admit it via the stack-wide path.
- The receiver skips the stack-wide fallback entirely on a multi-workspace stack.
  This is what supersedes sole-tenant binding rather than implementing it: with
  the fallback gone under multi-tenancy, that path survives only where there is
  one tenant, and there it cannot name the wrong one.
- `verified_via_stack_wide` is forwarded to the processor, which replaces the
  body's `organizationId` with the sole active workspace and drops the delivery
  when there is no single answer. The field is overwritten on the payload rather
  than threaded as a parameter because the workspace id is read from about six
  places downstream; passing it alongside would leave every one of them a site
  where the claimed value could still be picked up.

Single-workspace installs are untouched by design. Every check consults the active
workspace count first, and with one tenant a tenant-less secret still identifies
the only tenant there is. That also makes an absent provenance flag — the state of
every row written before it existed — harmless on the installs where it is normal.

`countActiveLinearWorkspaces` saturates at 2, since no caller needs the true
total, and answers 1 when the registry cannot be read. That is deliberately the
permissive direction: these checks harden a signature that has already verified,
so a DynamoDB throttle must not become a stack-wide outage.

No IAM change. `grantReadData` already covers `dynamodb:Scan` for both the
receiver and the processor on the registry table.

All three guards were confirmed to fail with the check disabled. One test needed
fixing first: the multi-workspace fallback case passed because the harness shrank
the workspace count along with the absent registry row, so the receiver had only
ever seen one workspace.
---
 cdk/src/handlers/linear-webhook-processor.ts  |  39 ++-
 cdk/src/handlers/linear-webhook.ts            |  39 ++-
 .../handlers/shared/linear-oauth-resolver.ts  |  47 +++-
 cdk/src/handlers/shared/linear-verify.ts      |  87 ++++++-
 .../handlers/linear-webhook-processor.test.ts |  57 +++++
 .../linear-webhook-tenant-binding.test.ts     | 241 ++++++++++++++++++
 .../shared/linear-oauth-resolver.test.ts      |  51 ++++
 .../handlers/shared/linear-verify.test.ts     |  53 +++-
 docs/guides/LINEAR_SETUP_GUIDE.md             |   4 +-
 .../content/docs/using/Linear-setup-guide.md  |   4 +-
 10 files changed, 612 insertions(+), 10 deletions(-)
 create mode 100644 cdk/test/handlers/linear-webhook-tenant-binding.test.ts

diff --git a/cdk/src/handlers/linear-webhook-processor.ts b/cdk/src/handlers/linear-webhook-processor.ts
index 5dc0688cd..a215c5e95 100644
--- a/cdk/src/handlers/linear-webhook-processor.ts
+++ b/cdk/src/handlers/linear-webhook-processor.ts
@@ -46,7 +46,7 @@ import {
   renderTaskLookupFailedNudge,
   renderWrongMentionNudge,
 } from './shared/linear-notes';
-import { resolveLinearOauthToken } from './shared/linear-oauth-resolver';
+import { resolveLinearOauthToken, resolveSoleActiveLinearWorkspace } from './shared/linear-oauth-resolver';
 import { fetchIssueParentId } from './shared/linear-subissue-fetch';
 import { lookupTaskByLinearIssue, prNumberFromTask } from './shared/linear-task-by-issue';
 import { logger } from './shared/logger';
@@ -621,6 +621,16 @@ interface LinearCommentEvent {
 
 interface ProcessorEvent {
   readonly raw_body: string;
+  /**
+   * Whether the stack-wide secret — bound to no workspace — is what verified this
+   * delivery, as reported by the receiver.
+   *
+   * On that path the body's `organizationId` is claimed rather than attested, so it must
+   * not be used to select a tenant. Absent is read as `false`, which is correct for the
+   * per-workspace path and is also what an in-flight invocation from a previous version
+   * looks like during a deploy.
+   */
+  readonly verified_via_stack_wide?: boolean;
 }
 
 /**
@@ -687,6 +697,33 @@ export async function handler(event: ProcessorEvent): Promise<void> {
     return;
   }
 
+  // A delivery verified by the stack-wide secret carries no proof of WHICH workspace
+  // sent it — that secret is bound to none of them — so the body's `organizationId`
+  // is a claim. Replace it with the only workspace it could mean, and drop the delivery
+  // when there is no single answer.
+  //
+  // Rewritten on the payload rather than threaded as a parameter because the workspace
+  // id is read from ~6 places downstream (task attribution, feedback, the comment path).
+  // Passing it alongside would leave every one of those a site where the claimed value
+  // could still be picked up by mistake; overwriting the untrusted field means the
+  // attested value is the only one reachable.
+  if (event.verified_via_stack_wide) {
+    const bound = await resolveSoleActiveLinearWorkspace(ddb, WORKSPACE_REGISTRY_TABLE);
+    if (!bound) {
+      logger.warn('Dropping stack-wide-verified Linear delivery: cannot determine the sending workspace', {
+        claimed_workspace_id: payload.organizationId,
+      });
+      return;
+    }
+    if (payload.organizationId && payload.organizationId !== bound) {
+      logger.warn('Ignoring body organizationId on a stack-wide-verified delivery; binding to the sole active workspace', {
+        claimed_workspace_id: payload.organizationId,
+        bound_workspace_id: bound,
+      });
+    }
+    (payload as { organizationId?: string }).organizationId = bound;
+  }
+
   // A Comment with an @bgagent mention on an orchestrated sub-issue
   // re-iterates that sub-issue's PR (the reconciler then cascades the
   // re-stack). Handled on a separate path from Issue → task creation.
diff --git a/cdk/src/handlers/linear-webhook.ts b/cdk/src/handlers/linear-webhook.ts
index 0cba78c70..2f4f747c8 100644
--- a/cdk/src/handlers/linear-webhook.ts
+++ b/cdk/src/handlers/linear-webhook.ts
@@ -22,6 +22,7 @@ import { InvokeCommand, LambdaClient } from '@aws-sdk/client-lambda';
 import { DeleteCommand, PutCommand } from '@aws-sdk/lib-dynamodb';
 import type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
 import {
+  countActiveLinearWorkspaces,
   isWebhookTimestampFresh,
   verifyLinearRequest,
   verifyLinearRequestForWorkspace,
@@ -133,18 +134,48 @@ export async function handler(event: APIGatewayProxyEvent): Promise<APIGatewayPr
           linear_workspace_id: payload.organizationId,
         });
         return jsonResponse(401, { error: 'Workspace not active' });
+      } else if (result === 'shared-secret') {
+        // The signature matched, but against a secret this workspace shares with
+        // another on the same stack — so it proves the sender knows SOME tenant's
+        // secret, not this one's. Fatal for the same reason `mismatch` is: falling
+        // through would re-admit it via the stack-wide path.
+        logger.warn('Linear webhook verified against a secret shared with another workspace — rejecting', {
+          linear_workspace_id: payload.organizationId,
+          remedy: 'bgagent linear update-webhook-secret <slug>',
+        });
+        return jsonResponse(401, { error: 'Workspace signing secret is not its own' });
       }
       // 'no-per-workspace-secret' falls through to the stack-wide path
       // below — back-compat for installs predating per-workspace secrets.
     }
 
+    // Whether the stack-wide secret was what verified this delivery. Forwarded to the
+    // processor, which routes from body-supplied identifiers that a tenant-less secret
+    // cannot attest to.
+    let verifiedViaStackWide = false;
+
     if (!verified) {
+      // The stack-wide secret is bound to no workspace, so on a stack with more than one
+      // it cannot say which tenant sent this — and the body's `organizationId` is the
+      // attacker's to choose. Refuse rather than guess. Single-workspace installs keep
+      // the fallback: there, the only tenant it could mean is the only tenant there is.
+      const activeWorkspaces = await countActiveLinearWorkspaces(WORKSPACE_REGISTRY_TABLE);
+      if (activeWorkspaces > 1) {
+        logger.warn('Refusing the stack-wide fallback on a multi-workspace stack', {
+          linear_workspace_id: payload.organizationId,
+          active_workspace_count: activeWorkspaces,
+          remedy: 'bgagent linear update-webhook-secret <slug>',
+        });
+        return jsonResponse(401, { error: 'Per-workspace signing secret required' });
+      }
+
       if (!await verifyLinearRequest(WEBHOOK_SECRET_ARN, signature, event.body)) {
         logger.warn('Invalid Linear webhook signature', {
           linear_workspace_id: payload.organizationId,
         });
         return jsonResponse(401, { error: 'Invalid signature' });
       }
+      verifiedViaStackWide = true;
       // Stack-wide fallback succeeded. Log positively so operators
       // diagnosing a per-workspace verification regression have a
       // breadcrumb that says "this workspace is verifying via the
@@ -244,7 +275,13 @@ export async function handler(event: APIGatewayProxyEvent): Promise<APIGatewayPr
       await lambdaClient.send(new InvokeCommand({
         FunctionName: PROCESSOR_FUNCTION_NAME,
         InvocationType: 'Event',
-        Payload: new TextEncoder().encode(JSON.stringify({ raw_body: event.body })),
+        // The verified context travels with the body. Without it the processor cannot
+        // tell a delivery whose tenant the signature attested from one whose tenant is
+        // only claimed, and it routes from that claim.
+        Payload: new TextEncoder().encode(JSON.stringify({
+          raw_body: event.body,
+          verified_via_stack_wide: verifiedViaStackWide,
+        })),
       }));
     } catch (invokeErr) {
       logger.error('Failed to invoke Linear webhook processor', {
diff --git a/cdk/src/handlers/shared/linear-oauth-resolver.ts b/cdk/src/handlers/shared/linear-oauth-resolver.ts
index 7ae51a736..03a0edf69 100644
--- a/cdk/src/handlers/shared/linear-oauth-resolver.ts
+++ b/cdk/src/handlers/shared/linear-oauth-resolver.ts
@@ -23,7 +23,7 @@ import {
   PutSecretValueCommand,
   SecretsManagerClient,
 } from '@aws-sdk/client-secrets-manager';
-import { DynamoDBDocumentClient, GetCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
+import { DynamoDBDocumentClient, GetCommand, ScanCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
 import { announceRevocation, revocationAlertTopicArn } from './linear-revocation-alert';
 import {
   LINEAR_VAULT_SCOPES,
@@ -1350,6 +1350,51 @@ async function tryRefreshOnce(
   return { kind: 'success', token: next };
 }
 
+/**
+ * The one active Linear workspace on this stack, or undefined when that is not a
+ * well-defined question.
+ *
+ * For binding a delivery that was verified by the stack-wide secret. That secret is
+ * bound to no workspace, so the body's `organizationId` is claimed rather than attested
+ * and must not select a tenant. When exactly one workspace is active there is only one
+ * tenant it could mean; with zero or several there is no answer, and returning undefined
+ * makes the caller drop the delivery rather than pick one.
+ *
+ * Mirrors `resolveSoleActiveJiraTenant`. Not cached: the callers reach it only on the
+ * back-compat path of a single-workspace install, which is rare enough that a Scan per
+ * delivery is cheaper than another cache to invalidate.
+ */
+export async function resolveSoleActiveLinearWorkspace(
+  ddbClient: DynamoDBDocumentClient,
+  registryTableName: string | undefined,
+): Promise<string | undefined> {
+  if (!registryTableName) return undefined;
+  const active: string[] = [];
+  let lastKey: Record<string, unknown> | undefined;
+  do {
+    const page = await ddbClient.send(new ScanCommand({
+      TableName: registryTableName,
+      ProjectionExpression: 'linear_workspace_id, #s',
+      ExpressionAttributeNames: { '#s': 'status' },
+      ExclusiveStartKey: lastKey,
+      ConsistentRead: true,
+    }));
+    for (const item of page.Items ?? []) {
+      if (item.status === 'active' && typeof item.linear_workspace_id === 'string') {
+        active.push(item.linear_workspace_id);
+      }
+    }
+    lastKey = page.LastEvaluatedKey;
+    if (active.length > 1) break;
+  } while (lastKey);
+
+  if (active.length === 1) return active[0];
+  logger.warn('Cannot bind a stack-wide-verified Linear delivery: registry does not have exactly one active workspace', {
+    active_workspace_count: active.length,
+  });
+  return undefined;
+}
+
 /** Test-only: clear all caches. */
 export function _resetCachesForTesting(): void {
   registryCache.clear();
diff --git a/cdk/src/handlers/shared/linear-verify.ts b/cdk/src/handlers/shared/linear-verify.ts
index bc60db78a..29fde6c6d 100644
--- a/cdk/src/handlers/shared/linear-verify.ts
+++ b/cdk/src/handlers/shared/linear-verify.ts
@@ -19,6 +19,7 @@
 
 import * as crypto from 'crypto';
 import { GetSecretValueCommand, SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
+import { ScanCommand } from '@aws-sdk/lib-dynamodb';
 import { isUsableHmacSecret } from './hmac-secret';
 import { getOauthSecretStrict, getRegistryRowStrict } from './linear-oauth-resolver';
 import { logger } from './logger';
@@ -35,6 +36,72 @@ const CACHE_TTL_MS = CACHE_TTL_MINUTES * 60 * 1000;
 /** Maximum age of a Linear webhookTimestamp (ms) before it is rejected (replay protection). */
 export const MAX_WEBHOOK_TIMESTAMP_AGE_MS = 60 * 1000;
 
+/**
+ * Cached count of active workspaces, capped at 2.
+ *
+ * Capped because nothing needs the true total — every decision that reads it only asks
+ * "is there more than one tenant on this stack", so the Scan can stop at the second hit.
+ *
+ * Cached separately from `secretCache` because it is not keyed by anything: it is one
+ * table-wide fact, re-derived by a Scan that would otherwise run on every delivery.
+ * A short TTL is the tradeoff — onboarding a second workspace takes up to this long to
+ * start being enforced, which is acceptable because the CLI refuses to create the
+ * shared-secret state in the first place.
+ */
+let activeWorkspaceCountCache: { count: number; expiresAt: number } | undefined;
+
+/**
+ * How many active Linear workspaces this stack has, saturating at 2.
+ *
+ * The distinction that matters is one tenant versus more than one. With a single
+ * workspace a secret that is not bound to a tenant still identifies the only tenant
+ * there is, so neither the stack-wide fallback nor a shared secret can cross a
+ * boundary. With two or more, both can.
+ *
+ * Returns 1 when the registry cannot be read, and says so in the log. That is the
+ * permissive answer, chosen deliberately: a DynamoDB throttle must not start rejecting
+ * every delivery on a healthy single-workspace install. The callers that act on this
+ * are hardening an already-verified signature, not standing in for one.
+ */
+export async function countActiveLinearWorkspaces(registryTableName: string | undefined): Promise<number> {
+  if (!registryTableName) return 1;
+  const now = Date.now();
+  if (activeWorkspaceCountCache && activeWorkspaceCountCache.expiresAt > now) {
+    return activeWorkspaceCountCache.count;
+  }
+
+  try {
+    let count = 0;
+    let lastKey: Record<string, unknown> | undefined;
+    do {
+      const page = await ddb.send(new ScanCommand({
+        TableName: registryTableName,
+        ProjectionExpression: 'linear_workspace_id, #s',
+        ExpressionAttributeNames: { '#s': 'status' },
+        ExclusiveStartKey: lastKey,
+      }));
+      for (const item of page.Items ?? []) {
+        if (item.status === 'active') count += 1;
+      }
+      lastKey = page.LastEvaluatedKey;
+      if (count > 1) break;
+    } while (lastKey);
+
+    activeWorkspaceCountCache = { count, expiresAt: now + CACHE_TTL_MS };
+    return count;
+  } catch (err) {
+    logger.warn('Could not count active Linear workspaces — assuming a single-workspace stack', {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return 1;
+  }
+}
+
+/** Drop the cached workspace count. Exported for tests. */
+export function _resetActiveWorkspaceCountCache(): void {
+  activeWorkspaceCountCache = undefined;
+}
+
 /**
  * Fetch a secret from Secrets Manager with in-memory caching.
  * @param secretId - the full Secrets Manager secret ID or ARN.
@@ -220,7 +287,7 @@ export async function verifyLinearRequestForWorkspace(
   linearWorkspaceId: string,
   signature: string,
   body: string,
-): Promise<'verified' | 'mismatch' | 'revoked' | 'no-per-workspace-secret'> {
+): Promise<'verified' | 'mismatch' | 'revoked' | 'no-per-workspace-secret' | 'shared-secret'> {
   const row = await getRegistryRowStrict(ddb, registryTableName, linearWorkspaceId);
   if (!row) {
     return 'no-per-workspace-secret';
@@ -232,7 +299,19 @@ export async function verifyLinearRequestForWorkspace(
   if (!stored || !stored.webhook_signing_secret) {
     return 'no-per-workspace-secret';
   }
-  return verifyLinearSignature(stored.webhook_signing_secret, signature, body)
-    ? 'verified'
-    : 'mismatch';
+  if (!verifyLinearSignature(stored.webhook_signing_secret, signature, body)) {
+    return 'mismatch';
+  }
+
+  // The signature matched — but matching a secret this workspace does not exclusively
+  // hold proves only that the sender knows a secret SOME workspace on this stack holds.
+  // A workspace onboarded by an older release can be carrying a copy of the first
+  // workspace's secret, and the routing values in the body are read from whichever
+  // workspace the sender names. Checked only when another tenant exists to impersonate,
+  // so a single-workspace install — where the same secret cannot cross a boundary and
+  // where an unrecorded provenance is the normal state — is untouched.
+  if (row.webhook_secret_owned !== true && await countActiveLinearWorkspaces(registryTableName) > 1) {
+    return 'shared-secret';
+  }
+  return 'verified';
 }
diff --git a/cdk/test/handlers/linear-webhook-processor.test.ts b/cdk/test/handlers/linear-webhook-processor.test.ts
index fc0964af3..1bf6e8d7a 100644
--- a/cdk/test/handlers/linear-webhook-processor.test.ts
+++ b/cdk/test/handlers/linear-webhook-processor.test.ts
@@ -64,8 +64,10 @@ jest.mock('../../src/handlers/shared/linear-attachments', () => {
 });
 
 const resolveLinearOauthTokenMock = jest.fn();
+const resolveSoleActiveLinearWorkspaceMock = jest.fn();
 jest.mock('../../src/handlers/shared/linear-oauth-resolver', () => ({
   resolveLinearOauthToken: (...args: unknown[]) => resolveLinearOauthTokenMock(...args),
+  resolveSoleActiveLinearWorkspace: (...args: unknown[]) => resolveSoleActiveLinearWorkspaceMock(...args),
 }));
 
 const probeLinearIssueContextMock = jest.fn();
@@ -135,6 +137,7 @@ describe('linear-webhook-processor handler', () => {
     cleanupPreScreenedAttachmentsMock.mockReset();
     cleanupPreScreenedAttachmentsMock.mockResolvedValue(undefined);
     resolveLinearOauthTokenMock.mockReset();
+    resolveSoleActiveLinearWorkspaceMock.mockReset();
     // Default: workspace IS resolvable (active registry row + valid
     // OAuth bundle). The processor early-returns when this resolves to
     // null — see "Linear workspace not resolvable from registry —
@@ -390,6 +393,60 @@ describe('linear-webhook-processor handler', () => {
     });
   });
 
+  // On the stack-wide path the body's organizationId is claimed, not attested, so it is
+  // replaced with the only workspace it could mean.
+  describe('binding a stack-wide-verified delivery', () => {
+    test('ignores the claimed organizationId and binds to the sole active workspace', async () => {
+      resolveSoleActiveLinearWorkspaceMock.mockResolvedValue('org-real');
+      ddbSend
+        .mockResolvedValueOnce({
+          Item: { repo: 'org/repo', status: 'active', linear_workspace_id: 'org-real' },
+        })
+        .mockResolvedValueOnce({ Item: { platform_user_id: 'cognito-user-1', status: 'active' } });
+      createTaskCoreMock.mockResolvedValueOnce({ statusCode: 201, body: JSON.stringify({ data: { task_id: 'T1' } }) });
+
+      await handler({
+        ...eventWith(issue({ organizationId: 'org-attacker-claimed' })),
+        verified_via_stack_wide: true,
+      });
+
+      // Bound, not claimed: the mapping is owned by org-real, so a processor that kept
+      // the claimed value would have dropped this at the project-binding check.
+      expect(createTaskCoreMock).toHaveBeenCalledTimes(1);
+      expect(createTaskCoreMock.mock.calls[0][1].channelMetadata).toMatchObject({
+        linear_workspace_id: 'org-real',
+      });
+    });
+
+    test('drops the delivery when the registry has no single active workspace', async () => {
+      // Two active workspaces means the resolver has no single answer to give.
+      resolveSoleActiveLinearWorkspaceMock.mockResolvedValue(undefined);
+
+      await handler({ ...eventWith(issue()), verified_via_stack_wide: true });
+
+      expect(createTaskCoreMock).not.toHaveBeenCalled();
+    });
+
+    test('leaves the organizationId alone when a per-workspace secret verified it', async () => {
+      // The attested value must survive. Rebinding here would silently repoint a
+      // correctly-verified delivery at whichever workspace happens to be the only
+      // active one.
+      ddbSend
+        .mockResolvedValueOnce({
+          Item: { repo: 'org/repo', status: 'active', linear_workspace_id: 'org-1' },
+        })
+        .mockResolvedValueOnce({ Item: { platform_user_id: 'cognito-user-1', status: 'active' } });
+      createTaskCoreMock.mockResolvedValueOnce({ statusCode: 201, body: JSON.stringify({ data: { task_id: 'T1' } }) });
+
+      await handler(eventWith(issue()));
+
+      expect(createTaskCoreMock).toHaveBeenCalledTimes(1);
+      expect(createTaskCoreMock.mock.calls[0][1].channelMetadata).toMatchObject({
+        linear_workspace_id: 'org-1',
+      });
+    });
+  });
+
   test('fires on update when labelIds newly include the trigger label', async () => {
     ddbSend
       .mockResolvedValueOnce({ Item: { repo: 'org/repo', status: 'active' } })
diff --git a/cdk/test/handlers/linear-webhook-tenant-binding.test.ts b/cdk/test/handlers/linear-webhook-tenant-binding.test.ts
new file mode 100644
index 000000000..2a21f7ceb
--- /dev/null
+++ b/cdk/test/handlers/linear-webhook-tenant-binding.test.ts
@@ -0,0 +1,241 @@
+/**
+ *  MIT No Attribution
+ *
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy of
+ *  the Software without restriction, including without limitation the rights to
+ *  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ *  the Software, and to permit persons to whom the Software is furnished to do so.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+// A signing secret must attest WHICH tenant sent a delivery, because the processor
+// routes from identifiers in the body. Two secrets fail that: the stack-wide one, which
+// is bound to no workspace, and a per-workspace one that is a copy of another
+// workspace's. Both are only dangerous once a second tenant exists to impersonate,
+// which is what these tests pivot on.
+//
+// A separate file from linear-webhook.test.ts because the registry table name is read
+// into a module-level const at import time, and these cases need it set.
+import * as crypto from 'crypto';
+import type { APIGatewayProxyEvent } from 'aws-lambda';
+
+const ddbSend = jest.fn();
+jest.mock('@aws-sdk/client-dynamodb', () => ({ DynamoDBClient: jest.fn(() => ({})) }));
+jest.mock('@aws-sdk/lib-dynamodb', () => ({
+  DynamoDBDocumentClient: { from: jest.fn(() => ({ send: ddbSend })) },
+  PutCommand: jest.fn((input: unknown) => ({ _type: 'Put', input })),
+  DeleteCommand: jest.fn((input: unknown) => ({ _type: 'Delete', input })),
+  GetCommand: jest.fn((input: unknown) => ({ _type: 'Get', input })),
+  ScanCommand: jest.fn((input: unknown) => ({ _type: 'Scan', input })),
+}));
+
+const lambdaSend = jest.fn();
+jest.mock('@aws-sdk/client-lambda', () => ({
+  LambdaClient: jest.fn(() => ({ send: lambdaSend })),
+  InvokeCommand: jest.fn((input: unknown) => ({ _type: 'Invoke', input })),
+}));
+
+const smSend = jest.fn();
+jest.mock('@aws-sdk/client-secrets-manager', () => ({
+  SecretsManagerClient: jest.fn(() => ({ send: smSend })),
+  GetSecretValueCommand: jest.fn((input: unknown) => ({ _type: 'GetSecretValue', input })),
+}));
+
+const REGISTRY = 'LinearWorkspaceRegistry';
+const OAUTH_ARN = 'arn:aws:secretsmanager:us-east-1:123:secret:bgagent-linear-oauth-acme';
+const STACK_WIDE_ARN = 'arn:aws:secretsmanager:us-east-1:123:secret:bgagent/linear/webhook-XYZ';
+process.env.LINEAR_WEBHOOK_SECRET_ARN = STACK_WIDE_ARN;
+process.env.LINEAR_WEBHOOK_DEDUP_TABLE_NAME = 'LinearDedup';
+process.env.LINEAR_WEBHOOK_PROCESSOR_FUNCTION_NAME = 'linear-processor';
+process.env.LINEAR_WORKSPACE_REGISTRY_TABLE_NAME = REGISTRY;
+
+import { handler } from '../../src/handlers/linear-webhook';
+import { _resetCachesForTesting } from '../../src/handlers/shared/linear-oauth-resolver';
+import { _resetActiveWorkspaceCountCache, invalidateLinearSecretCache } from '../../src/handlers/shared/linear-verify';
+
+const OWN_SECRET = 'lin_wh_acmeOwnSecret';
+const STACK_WIDE_SECRET = 'lin_wh_firstWorkspaceSecret';
+const WS_ACME = 'org-acme';
+
+function bundle(signingSecret: string): string {
+  return JSON.stringify({
+    access_token: '',
+    refresh_token: '',
+    expires_at: '',
+    scope: '',
+    client_id: 'cid',
+    client_secret: 'csec',
+    workspace_id: WS_ACME,
+    workspace_slug: 'acme',
+    installed_at: '2026-09-01T00:00:00.000Z',
+    updated_at: '2026-09-01T00:00:00.000Z',
+    installed_by_platform_user_id: 'u-1',
+    webhook_signing_secret: signingSecret,
+  });
+}
+
+function body(): string {
+  return JSON.stringify({
+    action: 'update',
+    type: 'Issue',
+    organizationId: WS_ACME,
+    webhookTimestamp: Date.now(),
+    data: { id: 'issue-1', identifier: 'ABC-1', title: 't', projectId: 'proj-1' },
+  });
+}
+
+function event(raw: string, key: string): APIGatewayProxyEvent {
+  return {
+    body: raw,
+    headers: { 'linear-signature': crypto.createHmac('sha256', key).update(raw).digest('hex') },
+    httpMethod: 'POST',
+  } as unknown as APIGatewayProxyEvent;
+}
+
+/**
+ * Wire DynamoDB for a registry holding `activeCount` workspaces.
+ *
+ * `Get` answers the row for the workspace under test; `Scan` answers the count. `Put` is
+ * the dedup claim, which must succeed or the receiver stops before verification matters.
+ */
+function withRegistry(opts: { activeCount: number; row?: Record<string, unknown> | null }) {
+  const selfRow = opts.row === undefined
+    ? { linear_workspace_id: WS_ACME, workspace_slug: 'acme', oauth_secret_arn: OAUTH_ARN, status: 'active' }
+    : opts.row;
+  // `activeCount` is the total the Scan reports. A workspace with no registry row of its
+  // own still shares the stack with the others, so the count must not shrink with it —
+  // getting this wrong is what made the multi-workspace fallback case look like it
+  // passed when the receiver had only ever seen one workspace.
+  const otherCount = opts.activeCount - (selfRow ? 1 : 0);
+  const others = Array.from({ length: Math.max(0, otherCount) }, (_, i) => ({
+    linear_workspace_id: `org-other-${i}`, status: 'active',
+  }));
+
+  ddbSend.mockImplementation((cmd: { _type: string }) => {
+    if (cmd._type === 'Get') return Promise.resolve({ Item: selfRow ?? undefined });
+    if (cmd._type === 'Scan') {
+      return Promise.resolve({
+        Items: [...(selfRow ? [{ linear_workspace_id: WS_ACME, status: 'active' }] : []), ...others],
+      });
+    }
+    return Promise.resolve({});
+  });
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  invalidateLinearSecretCache();
+  _resetCachesForTesting();
+  _resetActiveWorkspaceCountCache();
+  smSend.mockImplementation((cmd: { _type: string; input: { SecretId?: string } }) => {
+    if (cmd.input.SecretId === STACK_WIDE_ARN) return Promise.resolve({ SecretString: STACK_WIDE_SECRET });
+    return Promise.resolve({ SecretString: bundle(OWN_SECRET) });
+  });
+  lambdaSend.mockResolvedValue({});
+});
+
+describe('a secret shared with another workspace is not proof of this one', () => {
+  test('rejects when the row does not record the secret as its own and a second tenant exists', async () => {
+    withRegistry({ activeCount: 2 });
+
+    const res = await handler(event(body(), OWN_SECRET));
+
+    expect(res.statusCode).toBe(401);
+    expect(JSON.parse(res.body).error).toMatch(/not its own/);
+    expect(lambdaSend).not.toHaveBeenCalled();
+  });
+
+  test('accepts the very same request once ownership is recorded', async () => {
+    // The signature, the secret and the body are identical to the case above — only the
+    // provenance flag differs. That isolates the flag as the thing being tested rather
+    // than some incidental difference in the request.
+    withRegistry({
+      activeCount: 2,
+      row: {
+        linear_workspace_id: WS_ACME,
+        workspace_slug: 'acme',
+        oauth_secret_arn: OAUTH_ARN,
+        status: 'active',
+        webhook_secret_owned: true,
+      },
+    });
+
+    const res = await handler(event(body(), OWN_SECRET));
+
+    expect(res.statusCode).toBe(200);
+    expect(lambdaSend).toHaveBeenCalled();
+  });
+
+  test('accepts an unrecorded provenance on a single-workspace stack', async () => {
+    // Absent provenance is the normal state for every row written before it existed.
+    // With one tenant the same secret cannot cross a boundary, so rejecting here would
+    // break healthy installs to no benefit.
+    withRegistry({ activeCount: 1 });
+
+    const res = await handler(event(body(), OWN_SECRET));
+
+    expect(res.statusCode).toBe(200);
+  });
+});
+
+describe('the stack-wide fallback cannot name a tenant among several', () => {
+  test('refuses the fallback when more than one workspace is active', async () => {
+    // No per-workspace secret for this workspace, so verification falls through — and on
+    // a multi-tenant stack the stack-wide secret cannot say who sent this.
+    withRegistry({ activeCount: 2, row: null });
+
+    const res = await handler(event(body(), STACK_WIDE_SECRET));
+
+    expect(res.statusCode).toBe(401);
+    expect(JSON.parse(res.body).error).toMatch(/Per-workspace signing secret required/);
+    expect(lambdaSend).not.toHaveBeenCalled();
+  });
+
+  test('keeps the fallback working for a single-workspace install', async () => {
+    withRegistry({ activeCount: 1, row: null });
+
+    const res = await handler(event(body(), STACK_WIDE_SECRET));
+
+    expect(res.statusCode).toBe(200);
+  });
+
+  test('tells the processor the fallback is what verified the delivery', async () => {
+    withRegistry({ activeCount: 1, row: null });
+
+    await handler(event(body(), STACK_WIDE_SECRET));
+
+    const invoked = lambdaSend.mock.calls[0][0] as { input: { Payload: Uint8Array } };
+    const forwarded = JSON.parse(new TextDecoder().decode(invoked.input.Payload)) as Record<string, unknown>;
+    expect(forwarded.verified_via_stack_wide).toBe(true);
+  });
+
+  test('reports false when a per-workspace secret verified the delivery', async () => {
+    // The processor binds the workspace only on the stack-wide path, so a false positive
+    // here would make it discard a correctly attested organizationId and rebind it.
+    withRegistry({
+      activeCount: 1,
+      row: {
+        linear_workspace_id: WS_ACME,
+        workspace_slug: 'acme',
+        oauth_secret_arn: OAUTH_ARN,
+        status: 'active',
+        webhook_secret_owned: true,
+      },
+    });
+
+    await handler(event(body(), OWN_SECRET));
+
+    const invoked = lambdaSend.mock.calls[0][0] as { input: { Payload: Uint8Array } };
+    const forwarded = JSON.parse(new TextDecoder().decode(invoked.input.Payload)) as Record<string, unknown>;
+    expect(forwarded.verified_via_stack_wide).toBe(false);
+  });
+});
diff --git a/cdk/test/handlers/shared/linear-oauth-resolver.test.ts b/cdk/test/handlers/shared/linear-oauth-resolver.test.ts
index 8ed7c48ab..036d5370d 100644
--- a/cdk/test/handlers/shared/linear-oauth-resolver.test.ts
+++ b/cdk/test/handlers/shared/linear-oauth-resolver.test.ts
@@ -24,6 +24,7 @@ import {
   getOauthSecret,
   getOauthSecretStrict,
   getRegistryRowStrict,
+  resolveSoleActiveLinearWorkspace,
   invalidateLinearOauthCache,
   isRefreshTokenRejection,
   isTokenExpiring,
@@ -1329,3 +1330,53 @@ describe('webhook_secret_owned — provenance, not value equality', () => {
     },
   );
 });
+
+describe('resolveSoleActiveLinearWorkspace — bind only when the answer is unambiguous', () => {
+  function scanning(pages: Array<{ Items: Array<Record<string, unknown>>; LastEvaluatedKey?: Record<string, unknown> }>) {
+    let i = 0;
+    return { send: jest.fn(async () => pages[i++]) } as unknown as Parameters<typeof resolveSoleActiveLinearWorkspace>[0];
+  }
+
+  test('returns the id when exactly one workspace is active', async () => {
+    const ddb = scanning([{ Items: [{ linear_workspace_id: 'org-only', status: 'active' }] }]);
+    await expect(resolveSoleActiveLinearWorkspace(ddb, 'registry')).resolves.toBe('org-only');
+  });
+
+  test('returns undefined when two are active, rather than picking the first', async () => {
+    const ddb = scanning([{
+      Items: [
+        { linear_workspace_id: 'org-a', status: 'active' },
+        { linear_workspace_id: 'org-b', status: 'active' },
+      ],
+    }]);
+    await expect(resolveSoleActiveLinearWorkspace(ddb, 'registry')).resolves.toBeUndefined();
+  });
+
+  test('returns undefined on an empty registry', async () => {
+    await expect(resolveSoleActiveLinearWorkspace(scanning([{ Items: [] }]), 'registry')).resolves.toBeUndefined();
+  });
+
+  test('ignores revoked rows when deciding whether the answer is unique', async () => {
+    const ddb = scanning([{
+      Items: [
+        { linear_workspace_id: 'org-live', status: 'active' },
+        { linear_workspace_id: 'org-dead', status: 'revoked' },
+      ],
+    }]);
+    await expect(resolveSoleActiveLinearWorkspace(ddb, 'registry')).resolves.toBe('org-live');
+  });
+
+  test('follows pagination before concluding the answer is unique', async () => {
+    // A single-page read would report org-a as the sole workspace and bind deliveries to
+    // it, on a stack that actually has two tenants.
+    const ddb = scanning([
+      { Items: [{ linear_workspace_id: 'org-a', status: 'active' }], LastEvaluatedKey: { k: 1 } },
+      { Items: [{ linear_workspace_id: 'org-b', status: 'active' }] },
+    ]);
+    await expect(resolveSoleActiveLinearWorkspace(ddb, 'registry')).resolves.toBeUndefined();
+  });
+
+  test('returns undefined when no registry table is configured', async () => {
+    await expect(resolveSoleActiveLinearWorkspace(scanning([]), undefined)).resolves.toBeUndefined();
+  });
+});
diff --git a/cdk/test/handlers/shared/linear-verify.test.ts b/cdk/test/handlers/shared/linear-verify.test.ts
index c708cd5d4..59f110205 100644
--- a/cdk/test/handlers/shared/linear-verify.test.ts
+++ b/cdk/test/handlers/shared/linear-verify.test.ts
@@ -27,11 +27,16 @@ jest.mock('@aws-sdk/client-secrets-manager', () => ({
 jest.mock('@aws-sdk/client-dynamodb', () => ({
   DynamoDBClient: jest.fn(() => ({})),
 }));
+const ddbSend = jest.fn();
 jest.mock('@aws-sdk/lib-dynamodb', () => ({
-  DynamoDBDocumentClient: { from: jest.fn(() => ({ send: jest.fn() })) },
+  DynamoDBDocumentClient: { from: jest.fn(() => ({ send: ddbSend })) },
+  GetCommand: jest.fn((input: unknown) => ({ _type: 'Get', input })),
+  ScanCommand: jest.fn((input: unknown) => ({ _type: 'Scan', input })),
 }));
 
 import {
+  _resetActiveWorkspaceCountCache,
+  countActiveLinearWorkspaces,
   getLinearSecret,
   invalidateLinearSecretCache,
   isWebhookTimestampFresh,
@@ -187,3 +192,49 @@ describe('isWebhookTimestampFresh', () => {
     expect(isWebhookTimestampFresh(Infinity)).toBe(false);
   });
 });
+
+describe('countActiveLinearWorkspaces — one tenant versus more than one', () => {
+  beforeEach(() => {
+    ddbSend.mockReset();
+    _resetActiveWorkspaceCountCache();
+  });
+
+  test('counts only active rows', async () => {
+    ddbSend.mockResolvedValue({
+      Items: [
+        { linear_workspace_id: 'a', status: 'active' },
+        { linear_workspace_id: 'b', status: 'revoked' },
+      ],
+    });
+    await expect(countActiveLinearWorkspaces('registry')).resolves.toBe(1);
+  });
+
+  test('reports more than one so callers can refuse a tenant-less secret', async () => {
+    ddbSend.mockResolvedValue({
+      Items: [
+        { linear_workspace_id: 'a', status: 'active' },
+        { linear_workspace_id: 'b', status: 'active' },
+      ],
+    });
+    expect(await countActiveLinearWorkspaces('registry')).toBeGreaterThan(1);
+  });
+
+  test('caches, so the Scan does not run on every delivery', async () => {
+    ddbSend.mockResolvedValue({ Items: [{ linear_workspace_id: 'a', status: 'active' }] });
+    await countActiveLinearWorkspaces('registry');
+    await countActiveLinearWorkspaces('registry');
+    expect(ddbSend).toHaveBeenCalledTimes(1);
+  });
+
+  test('answers 1 when the registry cannot be read, rather than rejecting every delivery', async () => {
+    // Permissive on purpose. The callers are hardening a signature that already
+    // verified; a DynamoDB throttle must not turn into a stack-wide outage.
+    ddbSend.mockRejectedValue(new Error('ProvisionedThroughputExceededException'));
+    await expect(countActiveLinearWorkspaces('registry')).resolves.toBe(1);
+  });
+
+  test('answers 1 when no registry table is configured', async () => {
+    await expect(countActiveLinearWorkspaces(undefined)).resolves.toBe(1);
+    expect(ddbSend).not.toHaveBeenCalled();
+  });
+});
diff --git a/docs/guides/LINEAR_SETUP_GUIDE.md b/docs/guides/LINEAR_SETUP_GUIDE.md
index e6f5e3ca8..282a84e18 100644
--- a/docs/guides/LINEAR_SETUP_GUIDE.md
+++ b/docs/guides/LINEAR_SETUP_GUIDE.md
@@ -136,7 +136,9 @@ Mappings created before this was recorded have no owning workspace. `bgagent pla
 
 Every workspace must have its own webhook signing secret, read from its own Linear app. `setup` asks for it and refuses to continue without one, and records on the workspace's registry row that the secret is genuinely that workspace's.
 
-A workspace onboarded by an older release may instead be holding a copy of the first workspace's secret. Two workspaces sharing one secret means either can produce a delivery the other's signature check accepts. Fix it per workspace with `bgagent linear update-webhook-secret <slug>`, which now also records that the secret is that workspace's own — pass `--stack-name` if you are not using the default.
+A workspace onboarded by an older release may instead be holding a copy of the first workspace's secret. Two workspaces sharing one secret means either can produce a delivery the other's signature check accepts, so **on a stack with more than one active workspace those deliveries are rejected with a 401** until each workspace has its own. Fix it per workspace with `bgagent linear update-webhook-secret <slug>`, which also records that the secret is that workspace's own — pass `--stack-name` if you are not using the default.
+
+For the same reason, the stack-wide back-compat secret is only accepted on a single-workspace stack. It cannot say which workspace sent a delivery, and with two or more tenants there is no safe way to guess, so a stack-wide-signed delivery is rejected instead. Single-workspace installs are unaffected: every check here compares against the number of active workspaces first, and with one tenant none of them changes behaviour.
 
 ### 6. Test
 
diff --git a/docs/src/content/docs/using/Linear-setup-guide.md b/docs/src/content/docs/using/Linear-setup-guide.md
index bdd4f1a52..fd21a0502 100644
--- a/docs/src/content/docs/using/Linear-setup-guide.md
+++ b/docs/src/content/docs/using/Linear-setup-guide.md
@@ -140,7 +140,9 @@ Mappings created before this was recorded have no owning workspace. `bgagent pla
 
 Every workspace must have its own webhook signing secret, read from its own Linear app. `setup` asks for it and refuses to continue without one, and records on the workspace's registry row that the secret is genuinely that workspace's.
 
-A workspace onboarded by an older release may instead be holding a copy of the first workspace's secret. Two workspaces sharing one secret means either can produce a delivery the other's signature check accepts. Fix it per workspace with `bgagent linear update-webhook-secret <slug>`, which now also records that the secret is that workspace's own — pass `--stack-name` if you are not using the default.
+A workspace onboarded by an older release may instead be holding a copy of the first workspace's secret. Two workspaces sharing one secret means either can produce a delivery the other's signature check accepts, so **on a stack with more than one active workspace those deliveries are rejected with a 401** until each workspace has its own. Fix it per workspace with `bgagent linear update-webhook-secret <slug>`, which also records that the secret is that workspace's own — pass `--stack-name` if you are not using the default.
+
+For the same reason, the stack-wide back-compat secret is only accepted on a single-workspace stack. It cannot say which workspace sent a delivery, and with two or more tenants there is no safe way to guess, so a stack-wide-signed delivery is rejected instead. Single-workspace installs are unaffected: every check here compares against the number of active workspaces first, and with one tenant none of them changes behaviour.
 
 ### 6. Test
 

From 97d09f042836970975dac31b27e68322bbe0da53 Mon Sep 17 00:00:00 2001
From: Sphia Sadek <isadeks@gmail.com>
Date: Mon, 14 Sep 2026 13:36:59 -0400
Subject: [PATCH 5/9] feat(linear): record provenance for secrets that were
 never mirrored
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Enforcing per-workspace secret ownership needs the provenance flag to already be
set, and it is set only by `setup` and `update-webhook-secret`. On an existing
multi-workspace stack no row has it, so turning enforcement on rejects every
workspace at once — including workspaces that genuinely own their secret and are
being broken for nothing. On the dev stack that is 3 of 3.

`backfill-secret-provenance` closes the gap for the workspaces where ownership can
actually be established. `mirror-stackwide` can copy nothing except the stack-wide
value, so a stored secret that DIFFERS from it was never mirrored and is therefore
owned. That conclusion cannot be wrong, which is what makes it safe to write.

The converse is deliberately not used. A secret EQUAL to the stack-wide value is
equally consistent with a healthy single-workspace install, whose first `setup`
stamps the same real secret into both slots — so `inherited` withholds a verdict
rather than asserting "not owned", and only `own` is recorded. This is the same
asymmetry the earlier commit's doc comment warns about, now expressed as code: the
direction that grants is sound, the direction that would reject is not.

Reading the stack-wide secret is fatal on failure rather than treated as "not set".
Continuing with undefined would classify every workspace as owning its secret,
since nothing can equal a value that was never fetched — recording exactly the
shared secrets this command exists to withhold.

`platform doctor` reports the same population, gated on the active workspace count
so it matches the enforcement path: on a single-workspace stack an unrecorded
provenance is the normal state for every pre-existing row and carries no risk, so
it passes with a note rather than warning.

Both directions of the classifier were confirmed to fail when mutated — treating
`equals stack-wide` as owned, and treating an empty stored secret as present.
---
 cli/src/commands/linear.ts                    | 173 ++++++++++++++++++
 cli/src/platform-doctor.ts                    |  88 +++++++++
 .../commands/linear-project-workspace.test.ts |  36 ++++
 cli/test/platform-doctor.test.ts              |  73 ++++++++
 docs/guides/LINEAR_SETUP_GUIDE.md             |   2 +
 .../content/docs/using/Linear-setup-guide.md  |   2 +
 6 files changed, 374 insertions(+)

diff --git a/cli/src/commands/linear.ts b/cli/src/commands/linear.ts
index 58888a1d6..1627d318c 100644
--- a/cli/src/commands/linear.ts
+++ b/cli/src/commands/linear.ts
@@ -681,6 +681,41 @@ export function assertMirrorIsSafe(
   );
 }
 
+/**
+ * What can be established about where a workspace's signing secret came from.
+ *
+ * - `own` — the secret is provably NOT a copy of another workspace's.
+ * - `inherited` — it equals the stack-wide value, so ownership cannot be established.
+ * - `absent` — the workspace has no per-workspace secret at all.
+ */
+export type SecretProvenance = 'own' | 'inherited' | 'absent';
+
+/**
+ * Decide whether a workspace's signing secret is provably its own.
+ *
+ * Sound in ONE direction only, and the asymmetry is the whole point. `mirror-stackwide`
+ * can copy nothing except the stack-wide value, so a secret that DIFFERS from it was
+ * never mirrored and is therefore owned — a conclusion that cannot be wrong. The
+ * converse is not available: a secret that EQUALS the stack-wide value is equally
+ * consistent with a healthy single-workspace install, whose first `setup` stamps the
+ * same real secret into both slots. That is why `inherited` withholds a verdict rather
+ * than asserting "not owned", and why only the `own` case is written to the registry.
+ *
+ * A stack with no stack-wide secret at all cannot have mirrored anything, so any stored
+ * per-workspace secret there is owned by the same argument.
+ *
+ * @param workspaceSecret - the workspace's stored `webhook_signing_secret`.
+ * @param stackWideSecret - the stack-wide back-compat secret, if it is set.
+ */
+export function classifyWebhookSecretProvenance(
+  workspaceSecret: string | undefined,
+  stackWideSecret: string | undefined,
+): SecretProvenance {
+  if (!workspaceSecret) return 'absent';
+  if (!stackWideSecret) return 'own';
+  return workspaceSecret === stackWideSecret ? 'inherited' : 'own';
+}
+
 /** Outcome of resolving a usable Linear access token for one workspace. */
 export type WorkspaceTokenResult =
   | { readonly kind: 'token'; readonly accessToken: string }
@@ -2703,6 +2738,144 @@ export function makeLinearCommand(): Command {
       }),
   );
 
+  linear.addCommand(
+    new Command('backfill-secret-provenance')
+      .description('Record which workspaces provably own their webhook signing secret')
+      .option('--region <region>', 'AWS region (defaults to configured region)')
+      .option('--stack-name <name>', 'CloudFormation stack name', 'backgroundagent-dev')
+      .option('--dry-run', 'Report what would change without writing')
+      .action(async (opts) => {
+        const config = loadConfig();
+        const region = opts.region || config.region;
+
+        const [registryTableName, webhookSecretArn] = await Promise.all([
+          getStackOutput(region, opts.stackName, 'LinearWorkspaceRegistryTableName'),
+          getStackOutput(region, opts.stackName, 'LinearWebhookSecretArn'),
+        ]);
+        if (!registryTableName) {
+          console.error('Could not find LinearWorkspaceRegistryTableName in stack outputs. Deploy the stack first.');
+          process.exit(1);
+        }
+
+        const ddb = makeDocClient({ region });
+        const sm = makeClient(SecretsManagerClient, { region });
+
+        // The comparison value. Absent is meaningful rather than an error: a stack with
+        // no stack-wide secret cannot have mirrored one, so every stored secret is owned.
+        // Read as a BARE string, not through `readExistingWebhookSecret` — that reader
+        // parses an OAuth bundle and pulls `webhook_signing_secret` out of it, whereas
+        // this secret holds the `lin_wh_…` value directly.
+        //
+        // A read failure here is fatal rather than treated as "not set". Silently
+        // continuing with `undefined` would classify every workspace as `own`, since
+        // nothing can equal a value we failed to fetch — recording exactly the shared
+        // secrets this command exists to withhold.
+        let stackWideSecret: string | undefined;
+        if (webhookSecretArn) {
+          try {
+            const v = await sm.send(new GetSecretValueCommand({ SecretId: webhookSecretArn }));
+            stackWideSecret = v.SecretString?.trim() || undefined;
+          } catch (err) {
+            if ((err as { name?: string })?.name !== 'ResourceNotFoundException') {
+              throw new CliError(
+                `Could not read the stack-wide webhook secret: ${err instanceof Error ? err.message : String(err)}\n`
+                + '  Without it, ownership cannot be established for any workspace — refusing to\n'
+                + '  guess. Re-run once the secret is readable (check IAM and KMS permissions).',
+              );
+            }
+            // Genuinely absent: nothing was ever mirrored, so every stored secret is owned.
+          }
+        }
+
+        const rows = await listActiveWorkspaceRows(ddb, registryTableName);
+        if (rows.length === 0) {
+          console.log('No active Linear workspaces in the registry.');
+          return;
+        }
+        console.log(`${rows.length} active workspace(s). Stack-wide secret: ${stackWideSecret ? 'set' : 'not set'}`);
+        console.log();
+
+        let recorded = 0;
+        const needsOperator: Array<{ slug: string; why: SecretProvenance }> = [];
+
+        for (const row of rows) {
+          const slug = (row.workspace_slug as string | undefined) ?? '<unknown-slug>';
+          const workspaceId = row.linear_workspace_id as string | undefined;
+          const secretArn = row.oauth_secret_arn as string | undefined;
+          if (!workspaceId || !secretArn) {
+            console.log(`  ⚠ ${slug}: registry row is incomplete — skipping`);
+            continue;
+          }
+          if (row.webhook_secret_owned === true) {
+            console.log(`  · ${slug}: already recorded as owning its secret`);
+            continue;
+          }
+
+          let workspaceSecret: string | undefined;
+          try {
+            workspaceSecret = await readExistingWebhookSecret(
+              async () => {
+                const v = await sm.send(new GetSecretValueCommand({ SecretId: secretArn }));
+                return v.SecretString ?? undefined;
+              },
+              (err) => (err as { name?: string })?.name === 'ResourceNotFoundException',
+            );
+          } catch (err) {
+            // Fail closed per workspace: an unreadable bundle must not be recorded as
+            // owned just because the read failed.
+            console.log(`  ⚠ ${slug}: could not read its OAuth bundle — ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+          }
+
+          const provenance = classifyWebhookSecretProvenance(workspaceSecret, stackWideSecret);
+          if (provenance !== 'own') {
+            needsOperator.push({ slug, why: provenance });
+            console.log(`  ⚠ ${slug}: ${provenance === 'absent'
+              ? 'has no signing secret of its own'
+              : 'holds the stack-wide secret, so ownership cannot be established'}`);
+            continue;
+          }
+
+          if (opts.dryRun) {
+            console.log(`  would record ${slug} as owning its secret`);
+          } else {
+            await ddb.send(new UpdateCommand({
+              TableName: registryTableName,
+              Key: { linear_workspace_id: workspaceId },
+              UpdateExpression: 'SET webhook_secret_owned = :t, updated_at = :u',
+              // Do not resurrect a row deleted mid-run.
+              ConditionExpression: 'attribute_exists(linear_workspace_id)',
+              ExpressionAttributeValues: { ':t': true, ':u': new Date().toISOString() },
+            })).catch((err: unknown) => {
+              if ((err as { name?: string })?.name === 'ConditionalCheckFailedException') {
+                console.log(`  · ${slug}: row changed underneath the backfill — skipped`);
+                return;
+              }
+              throw err;
+            });
+            console.log(`  ✓ ${slug}: recorded as owning its secret`);
+          }
+          recorded += 1;
+        }
+
+        console.log();
+        console.log(opts.dryRun
+          ? `Dry run: ${recorded} workspace(s) would be recorded.`
+          : `✓ Recorded ${recorded} workspace(s).`);
+
+        if (needsOperator.length > 0) {
+          console.log();
+          console.log(`⚠ ${needsOperator.length} workspace(s) need a signing secret of their own.`);
+          console.log('  Until then, on a stack with two or more active workspaces their webhook');
+          console.log('  deliveries are rejected, because a shared secret cannot attest which');
+          console.log('  workspace sent them. Fix each one with its own secret from Linear:');
+          for (const w of needsOperator) {
+            console.log(`    bgagent linear update-webhook-secret ${w.slug}`);
+          }
+        }
+      }),
+  );
+
   linear.addCommand(
     new Command('list-projects')
       .description('List Linear projects visible to the OAuth-installed workspace (with full UUIDs)')
diff --git a/cli/src/platform-doctor.ts b/cli/src/platform-doctor.ts
index f351bed61..f99814e6c 100644
--- a/cli/src/platform-doctor.ts
+++ b/cli/src/platform-doctor.ts
@@ -124,12 +124,100 @@ export async function runPlatformDoctor(
     region, linearRegistryTableName, options.linearProbe, options.linearVerifyRefresh,
     linearVaultWorkloadName,
   ));
+  checks.push(await checkLinearSecretProvenance(region, linearRegistryTableName));
   checks.push(await checkLinearProjectWorkspaces(region, linearProjectMappingTableName));
   checks.push(await checkJiraAppIdentity(region, jiraRegistryTableName));
 
   return checks;
 }
 
+/**
+ * Report workspaces whose signing secret is not recorded as provably their own.
+ *
+ * These are the workspaces whose deliveries get rejected once a stack has two or more
+ * active workspaces, because a secret shared between tenants attests only that the sender
+ * knows *some* tenant's secret. Reported before that bites rather than after: the failure
+ * mode otherwise is every webhook 401ing at once with the cause two layers down.
+ *
+ * Severity follows the workspace count, matching the enforcement path exactly. With one
+ * active workspace a shared secret cannot cross a boundary, so an unrecorded provenance
+ * is the normal, harmless state for every row written before that field existed.
+ */
+export async function checkLinearSecretProvenance(
+  region: string,
+  registryTableName: string | null,
+): Promise<DoctorCheckResult> {
+  const id = 'linear_secret_provenance';
+  const label = 'Linear per-workspace signing secrets';
+  if (!registryTableName) {
+    return {
+      id,
+      label,
+      status: 'pass',
+      detail: 'No Linear workspace registry on this stack (integration not deployed).',
+    };
+  }
+
+  try {
+    const ddb = documentClient(region);
+    const rows: Array<{ workspace_slug?: string; status?: string; webhook_secret_owned?: boolean }> = [];
+    let startKey: Record<string, unknown> | undefined;
+    do {
+      const page = await ddb.send(new ScanCommand({
+        TableName: registryTableName,
+        ProjectionExpression: ['workspace_slug', '#status', 'webhook_secret_owned'].join(', '),
+        ExpressionAttributeNames: { '#status': 'status' },
+        ...(startKey && { ExclusiveStartKey: startKey }),
+      }));
+      rows.push(...(page.Items ?? []) as typeof rows);
+      startKey = page.LastEvaluatedKey;
+    } while (startKey);
+
+    const active = rows.filter((row) => row.status === 'active');
+    if (active.length === 0) {
+      return { id, label, status: 'pass', detail: 'No active Linear workspaces onboarded yet.' };
+    }
+
+    const unproven = active.filter((row) => row.webhook_secret_owned !== true);
+    if (unproven.length === 0) {
+      return {
+        id,
+        label,
+        status: 'pass',
+        detail: `All ${active.length} active Linear workspace(s) own their signing secret.`,
+      };
+    }
+
+    const slugs = unproven.map((row) => row.workspace_slug ?? '<unknown-slug>').join(', ');
+    if (active.length === 1) {
+      return {
+        id,
+        label,
+        status: 'pass',
+        detail: 'Single active Linear workspace, so a shared signing secret cannot reach another '
+          + 'tenant and provenance is not enforced. Onboarding a second workspace makes it matter — '
+          + 'run `bgagent linear backfill-secret-provenance` then.',
+      };
+    }
+    return {
+      id,
+      label,
+      status: 'warn',
+      detail: `${unproven.length} of ${active.length} active Linear workspace(s) are not recorded as `
+        + `owning their signing secret, so their webhook deliveries are rejected: ${slugs}. Run `
+        + '`bgagent linear backfill-secret-provenance --dry-run` to see which can be recorded '
+        + 'automatically, then `bgagent linear update-webhook-secret <slug>` for the rest.',
+    };
+  } catch (err) {
+    return {
+      id,
+      label,
+      status: 'warn',
+      detail: `Could not read the Linear workspace registry: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
 /**
  * Report project mappings that do not record which workspace owns them.
  *
diff --git a/cli/test/commands/linear-project-workspace.test.ts b/cli/test/commands/linear-project-workspace.test.ts
index 88b9aae7f..bd98cd114 100644
--- a/cli/test/commands/linear-project-workspace.test.ts
+++ b/cli/test/commands/linear-project-workspace.test.ts
@@ -24,6 +24,7 @@ import { GetSecretValueCommand, ListSecretsCommand, SecretsManagerClient } from
 import { ScanCommand } from '@aws-sdk/lib-dynamodb';
 import {
   assertMirrorIsSafe,
+  classifyWebhookSecretProvenance,
   findProjectOwnerWorkspace,
   listActiveWorkspaceRows,
   listOnboardedWorkspaceSlugs,
@@ -328,3 +329,38 @@ describe('assertMirrorIsSafe', () => {
     expect(() => assertMirrorIsSafe([{ workspace_slug: 'half' }], SELF, 'acme')).not.toThrow();
   });
 });
+
+// The asymmetry is the point: "differs from stack-wide" proves ownership because
+// mirroring can copy nothing else, while "equals stack-wide" proves nothing because a
+// healthy first install stamps the same real secret into both slots.
+describe('classifyWebhookSecretProvenance', () => {
+  const STACK_WIDE = 'lin_wh_firstWorkspaceSecret';
+
+  test('a secret that differs from the stack-wide one is provably own', () => {
+    expect(classifyWebhookSecretProvenance('lin_wh_mine', STACK_WIDE)).toBe('own');
+  });
+
+  test('a secret equal to the stack-wide one withholds a verdict', () => {
+    // NOT 'own' — it may be a mirror. Also NOT asserted as un-owned, because a
+    // single-workspace install legitimately looks exactly like this.
+    expect(classifyWebhookSecretProvenance(STACK_WIDE, STACK_WIDE)).toBe('inherited');
+  });
+
+  test('no per-workspace secret at all is its own category', () => {
+    expect(classifyWebhookSecretProvenance(undefined, STACK_WIDE)).toBe('absent');
+  });
+
+  test('owns it when no stack-wide secret exists, since nothing could have been mirrored', () => {
+    expect(classifyWebhookSecretProvenance('lin_wh_mine', undefined)).toBe('own');
+  });
+
+  test('absent beats a missing stack-wide secret — nothing to own', () => {
+    expect(classifyWebhookSecretProvenance(undefined, undefined)).toBe('absent');
+  });
+
+  test('an empty stored secret is absent, not an own secret equal to nothing', () => {
+    // Guards the falsy-vs-undefined edge: '' must not fall through to the comparison and
+    // read as 'own' just because it differs from the stack-wide value.
+    expect(classifyWebhookSecretProvenance('', STACK_WIDE)).toBe('absent');
+  });
+});
diff --git a/cli/test/platform-doctor.test.ts b/cli/test/platform-doctor.test.ts
index 888d408f9..b40b64cbb 100644
--- a/cli/test/platform-doctor.test.ts
+++ b/cli/test/platform-doctor.test.ts
@@ -48,6 +48,7 @@ jest.mock('@aws-sdk/client-bedrock', () => ({
 import {
   checkJiraAppIdentity,
   checkLinearProjectWorkspaces,
+  checkLinearSecretProvenance,
   runPlatformDoctor,
   type DoctorCheckResult,
 } from '../src/platform-doctor';
@@ -73,6 +74,78 @@ beforeEach(() => {
     (output === 'LinearWorkspaceRegistryTableName' ? REGISTRY : null));
 });
 
+describe('doctor verdict for Linear signing-secret provenance', () => {
+  const REG = 'LinearWorkspaceRegistry';
+
+  test('warns and names the workspaces whose deliveries are now rejected', async () => {
+    ddbSendMock.mockResolvedValue({
+      Items: [
+        { workspace_slug: 'acme', status: 'active', webhook_secret_owned: true },
+        { workspace_slug: 'shared-one', status: 'active' },
+        { workspace_slug: 'shared-two', status: 'active' },
+      ],
+    });
+
+    const check = await checkLinearSecretProvenance('us-east-1', REG);
+
+    expect(check.status).toBe('warn');
+    expect(check.detail).toContain('shared-one');
+    expect(check.detail).toContain('shared-two');
+    expect(check.detail).not.toContain('acme');
+    expect(check.detail).toContain('backfill-secret-provenance');
+  });
+
+  test('passes on a single-workspace stack even with no provenance recorded', async () => {
+    // The enforcement path is gated on the same count, so warning here would flag every
+    // pre-existing single-workspace install for a risk it does not carry.
+    ddbSendMock.mockResolvedValue({ Items: [{ workspace_slug: 'solo', status: 'active' }] });
+
+    const check = await checkLinearSecretProvenance('us-east-1', REG);
+
+    expect(check.status).toBe('pass');
+    expect(check.detail).toContain('cannot reach another tenant');
+  });
+
+  test('passes when every active workspace owns its secret', async () => {
+    ddbSendMock.mockResolvedValue({
+      Items: [
+        { workspace_slug: 'a', status: 'active', webhook_secret_owned: true },
+        { workspace_slug: 'b', status: 'active', webhook_secret_owned: true },
+      ],
+    });
+    const check = await checkLinearSecretProvenance('us-east-1', REG);
+    expect(check.status).toBe('pass');
+    expect(check.detail).toContain('All 2 active');
+  });
+
+  test('ignores revoked rows when counting tenants', async () => {
+    ddbSendMock.mockResolvedValue({
+      Items: [
+        { workspace_slug: 'live', status: 'active' },
+        { workspace_slug: 'dead', status: 'revoked' },
+      ],
+    });
+    // One ACTIVE workspace ⇒ the single-workspace pass, not a two-tenant warn.
+    expect((await checkLinearSecretProvenance('us-east-1', REG)).status).toBe('pass');
+  });
+
+  test('warns when the registry cannot be read', async () => {
+    ddbSendMock.mockRejectedValue(new Error('AccessDeniedException'));
+    expect((await checkLinearSecretProvenance('us-east-1', REG)).status).toBe('warn');
+  });
+
+  test('passes when Linear is not deployed', async () => {
+    expect((await checkLinearSecretProvenance('us-east-1', null)).status).toBe('pass');
+  });
+
+  test('is reported by the full doctor run', async () => {
+    stackOutputMock.mockImplementation(async (_r: string, _s: string, output: string) =>
+      (output === 'LinearWorkspaceRegistryTableName' ? REG : null));
+    const checks = await runPlatformDoctor({ region: 'us-east-1', stackName: 'Abca' });
+    expect(checks.map((c) => c.id)).toContain('linear_secret_provenance');
+  });
+});
+
 describe('doctor verdict for Linear project → workspace binding', () => {
   const MAPPING = 'LinearProjectMapping';
 
diff --git a/docs/guides/LINEAR_SETUP_GUIDE.md b/docs/guides/LINEAR_SETUP_GUIDE.md
index 282a84e18..2fe0e5be7 100644
--- a/docs/guides/LINEAR_SETUP_GUIDE.md
+++ b/docs/guides/LINEAR_SETUP_GUIDE.md
@@ -138,6 +138,8 @@ Every workspace must have its own webhook signing secret, read from its own Line
 
 A workspace onboarded by an older release may instead be holding a copy of the first workspace's secret. Two workspaces sharing one secret means either can produce a delivery the other's signature check accepts, so **on a stack with more than one active workspace those deliveries are rejected with a 401** until each workspace has its own. Fix it per workspace with `bgagent linear update-webhook-secret <slug>`, which also records that the secret is that workspace's own — pass `--stack-name` if you are not using the default.
 
+On an existing multi-workspace stack, run `bgagent linear backfill-secret-provenance --dry-run` before deploying this change. It records ownership automatically for every workspace whose stored secret differs from the stack-wide value — which proves the secret was never copied from it, since copying is the only way a workspace ends up with someone else's — and names the ones that still need `update-webhook-secret`. `bgagent platform doctor` reports the same thing, and stays quiet on a single-workspace stack where a shared secret cannot reach another tenant.
+
 For the same reason, the stack-wide back-compat secret is only accepted on a single-workspace stack. It cannot say which workspace sent a delivery, and with two or more tenants there is no safe way to guess, so a stack-wide-signed delivery is rejected instead. Single-workspace installs are unaffected: every check here compares against the number of active workspaces first, and with one tenant none of them changes behaviour.
 
 ### 6. Test
diff --git a/docs/src/content/docs/using/Linear-setup-guide.md b/docs/src/content/docs/using/Linear-setup-guide.md
index fd21a0502..ecb46d942 100644
--- a/docs/src/content/docs/using/Linear-setup-guide.md
+++ b/docs/src/content/docs/using/Linear-setup-guide.md
@@ -142,6 +142,8 @@ Every workspace must have its own webhook signing secret, read from its own Line
 
 A workspace onboarded by an older release may instead be holding a copy of the first workspace's secret. Two workspaces sharing one secret means either can produce a delivery the other's signature check accepts, so **on a stack with more than one active workspace those deliveries are rejected with a 401** until each workspace has its own. Fix it per workspace with `bgagent linear update-webhook-secret <slug>`, which also records that the secret is that workspace's own — pass `--stack-name` if you are not using the default.
 
+On an existing multi-workspace stack, run `bgagent linear backfill-secret-provenance --dry-run` before deploying this change. It records ownership automatically for every workspace whose stored secret differs from the stack-wide value — which proves the secret was never copied from it, since copying is the only way a workspace ends up with someone else's — and names the ones that still need `update-webhook-secret`. `bgagent platform doctor` reports the same thing, and stays quiet on a single-workspace stack where a shared secret cannot reach another tenant.
+
 For the same reason, the stack-wide back-compat secret is only accepted on a single-workspace stack. It cannot say which workspace sent a delivery, and with two or more tenants there is no safe way to guess, so a stack-wide-signed delivery is rejected instead. Single-workspace installs are unaffected: every check here compares against the number of active workspaces first, and with one tenant none of them changes behaviour.
 
 ### 6. Test

From 24fe7ebdeed8e890f6fb3ec66ba51310e7650490 Mon Sep 17 00:00:00 2001
From: Sphia Sadek <isadeks@gmail.com>
Date: Mon, 14 Sep 2026 13:41:12 -0400
Subject: [PATCH 6/9] fix(linear): do not blame stale mappings for a workspace
 we could not query
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The first live run of `backfill-project-workspaces` hit two workspaces whose
Linear grants had expired. Both returned 401, so every mapping they own came back
unresolved — and the report concluded those mappings "name projects no onboarded
workspace can see" and told the operator to re-onboard or remove them. Four valid
rows, and the suggested remedy was to delete them.

An unresolved mapping means opposite things depending on whether every workspace
was actually reachable, so the conclusion now branches on that. Skipped workspaces
are tracked wherever the loop gives up on one — no token, an API error, or a
response with no organization id — and when any exist the report leads with "Do
NOT delete these yet", names them, and points at restoring their access first.
The delete-them wording now appears only when every workspace was queried
successfully.

Verified by re-running against the dev stack, where the output now names
demo-abca and maguireb as the reason rather than implicating their projects.

The guard is asserted at source level: the branch sits inside a Commander action
that would need the whole AWS and Linear surface stood up to reach, and the
behavioural proof is the live run. The test pins that the unconditional wording
cannot come back.
---
 cli/src/commands/linear.ts                    | 24 ++++++++++++++---
 .../commands/linear-project-workspace.test.ts | 27 +++++++++++++++++++
 2 files changed, 48 insertions(+), 3 deletions(-)

diff --git a/cli/src/commands/linear.ts b/cli/src/commands/linear.ts
index 1627d318c..f5a4d9ea6 100644
--- a/cli/src/commands/linear.ts
+++ b/cli/src/commands/linear.ts
@@ -2658,18 +2658,27 @@ export function makeLinearCommand(): Command {
         const slugs = await listOnboardedWorkspaceSlugs({ sm, ddb, registryTableName: registryTableName ?? undefined });
         const vaultWorkloadName = await resolveLinearVaultWorkloadName(region, opts.stackName);
         const ownerByProject = new Map<string, { slug: string; workspaceId: string }>();
+        // Workspaces we could not query at all. Tracked because an unresolved mapping means
+        // something completely different depending on this: with every workspace reachable it
+        // really is a stale mapping, but with one unreachable the mapping may be perfectly
+        // valid and simply unverifiable right now. Live-caught — the first real run hit two
+        // workspaces with expired grants and the report told the operator to delete four good
+        // rows.
+        const unqueryable: string[] = [];
 
         for (const slug of slugs) {
           const token = await resolveWorkspaceAccessToken({
             slug, sm, ddb, registryTableName: registryTableName ?? undefined, region, vaultWorkloadName,
           });
           if (token.kind !== 'token') {
+            unqueryable.push(slug);
             console.log(`  ⚠ ${slug}: ${token.reason} — projects owned here cannot be resolved`);
             continue;
           }
           try {
             const listed = await listWorkspaceProjectIds({ accessToken: token.accessToken });
             if (!listed.workspaceId) {
+              unqueryable.push(slug);
               console.log(`  ⚠ ${slug}: Linear did not return an organization id`);
               continue;
             }
@@ -2685,6 +2694,7 @@ export function makeLinearCommand(): Command {
               ownerByProject.set(id, { slug, workspaceId: listed.workspaceId });
             }
           } catch (err) {
+            unqueryable.push(slug);
             console.log(`  ⚠ ${slug}: ${err instanceof Error ? err.message : String(err)}`);
           }
         }
@@ -2731,9 +2741,17 @@ export function makeLinearCommand(): Command {
           console.log(`⚠ ${unresolved.length} mapping(s) could not be resolved to a workspace:`);
           for (const id of unresolved) console.log(`    ${id}`);
           console.log();
-          console.log('These name projects no onboarded workspace can see — a deleted project, or a');
-          console.log('workspace that is no longer installed. Re-run `bgagent linear onboard-project`');
-          console.log('for the ones still in use and remove the rest before enforcement is enabled.');
+          if (unqueryable.length > 0) {
+            console.log(`Do NOT delete these yet. ${unqueryable.length} workspace(s) could not be queried`);
+            console.log(`(${unqueryable.join(', ')}), so a mapping owned by one of them is unresolved`);
+            console.log('here even when it is perfectly valid. Restore access for those workspaces —');
+            console.log('`bgagent platform doctor` reports Linear auth state — then re-run this command.');
+            console.log('Only rows still unresolved with every workspace reachable are genuinely stale.');
+          } else {
+            console.log('Every onboarded workspace was queried successfully, so these name projects none');
+            console.log('of them can see — a deleted project, or a workspace no longer installed. Re-run');
+            console.log('`bgagent linear onboard-project` for the ones still in use and remove the rest.');
+          }
         }
       }),
   );
diff --git a/cli/test/commands/linear-project-workspace.test.ts b/cli/test/commands/linear-project-workspace.test.ts
index bd98cd114..ba5a7ecbd 100644
--- a/cli/test/commands/linear-project-workspace.test.ts
+++ b/cli/test/commands/linear-project-workspace.test.ts
@@ -20,6 +20,8 @@
 // Resolving which workspace owns a Linear project. The mapping table is keyed on the
 // project id alone, so this resolution is what lets a later webhook check a
 // body-supplied `projectId` against the workspace that actually signed the delivery.
+import * as fs from 'fs';
+import * as path from 'path';
 import { GetSecretValueCommand, ListSecretsCommand, SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
 import { ScanCommand } from '@aws-sdk/lib-dynamodb';
 import {
@@ -364,3 +366,28 @@ describe('classifyWebhookSecretProvenance', () => {
     expect(classifyWebhookSecretProvenance('', STACK_WIDE)).toBe('absent');
   });
 });
+
+// Regression guard for a copy defect the first LIVE run surfaced: two workspaces had
+// expired grants, so four perfectly valid mappings came back unresolved and the report
+// told the operator they named deleted projects and should be removed. An unresolved
+// mapping means opposite things depending on whether every workspace was reachable, so
+// the conclusion has to branch on that.
+describe('unresolved-mapping guidance distinguishes stale rows from unreachable workspaces', () => {
+  const src = fs.readFileSync(path.join(__dirname, '../../src/commands/linear.ts'), 'utf8');
+
+  test('an unqueryable workspace is tracked, not silently folded into "stale"', () => {
+    // Source-level because the branch is inside a Commander action that would need the
+    // whole AWS + Linear surface stood up to reach; the behavioural proof is the live run.
+    expect(src).toContain('const unqueryable: string[] = []');
+    // Every skip path that means "we could not ask this workspace" must record it.
+    const pushes = src.match(/unqueryable\.push\(slug\)/g) ?? [];
+    expect(pushes.length).toBeGreaterThanOrEqual(3);
+  });
+
+  test('the delete-them conclusion is gated on every workspace having been queried', () => {
+    expect(src).toContain('Do NOT delete these yet');
+    expect(src).toContain('Every onboarded workspace was queried successfully');
+    // The unconditional wording that caused the defect must not come back.
+    expect(src).not.toContain('These name projects no onboarded workspace can see');
+  });
+});

From 6d62c4ca1578249f75242c9995a454db090a258d Mon Sep 17 00:00:00 2001
From: Sphia Sadek <isadeks@gmail.com>
Date: Mon, 14 Sep 2026 13:53:47 -0400
Subject: [PATCH 7/9] fix(linear): refuse to half-repair a workspace when the
 registry cannot be found
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`update-webhook-secret` writes two things: the signing secret, and the registry
flag recording that the workspace owns it. Verification reads the flag, so without
it the repair changes nothing observable — the workspace keeps 401ing.

The registry write was wrapped in `if (registryTableName)`, so an operator who
defaulted or mistyped `--stack-name` got the secret written, no flag, and a green
"✅ Updated webhook signing secret". That is precisely the silent-miss the comment
directly above the block claims to prevent, and it would send someone chasing a
401 whose cause was in the output they already saw.

Now it refuses, names the stack it looked in, says the secret was preserved, and
points at `--stack-name`.
---
 cli/src/commands/linear.ts | 55 +++++++++++++++++++++++---------------
 1 file changed, 33 insertions(+), 22 deletions(-)

diff --git a/cli/src/commands/linear.ts b/cli/src/commands/linear.ts
index f5a4d9ea6..0a8aa802b 100644
--- a/cli/src/commands/linear.ts
+++ b/cli/src/commands/linear.ts
@@ -2300,31 +2300,42 @@ export function makeLinearCommand(): Command {
         // succeeded, so a silent miss here leaves the operator believing the fix landed
         // when the state that verification reads is unchanged.
         const registryTableName = await getStackOutput(region, opts.stackName, 'LinearWorkspaceRegistryTableName');
-        if (registryTableName) {
-          try {
-            await makeDocClient({ region }).send(new UpdateCommand({
-              TableName: registryTableName,
-              Key: { linear_workspace_id: stored.workspace_id },
-              UpdateExpression: 'SET webhook_secret_owned = :t, updated_at = :u',
-              ConditionExpression: 'attribute_exists(linear_workspace_id)',
-              ExpressionAttributeValues: { ':t': true, ':u': new Date().toISOString() },
-            }));
-            console.log('  ✓ Recorded that this workspace owns its signing secret');
-          } catch (err) {
-            if ((err as { name?: string })?.name === 'ConditionalCheckFailedException') {
-              throw new CliError(
-                `Updated the signing secret, but workspace '${slug}' has no registry row `
-                + `(${stored.workspace_id}).\n  Run \`bgagent linear setup ${slug}\` so the workspace `
-                + 'is registered; the secret you just entered will be preserved.',
-              );
-            }
+        if (!registryTableName) {
+          // Refuse rather than skip. Skipping is the failure this whole block exists to
+          // avoid: the secret write above already succeeded, so an operator who defaulted
+          // or mistyped --stack-name would see "Updated" and keep 401ing, with nothing
+          // in the output pointing at the reason.
+          throw new CliError(
+            'Updated the signing secret, but could not find LinearWorkspaceRegistryTableName in '
+            + `stack '${opts.stackName}'.\n`
+            + '  The secret is only half the repair — verification also reads a registry flag\n'
+            + '  recording that this workspace owns it, and that flag was not written.\n'
+            + '  Re-run with --stack-name <your-stack> (the secret you entered is preserved).',
+          );
+        }
+        try {
+          await makeDocClient({ region }).send(new UpdateCommand({
+            TableName: registryTableName,
+            Key: { linear_workspace_id: stored.workspace_id },
+            UpdateExpression: 'SET webhook_secret_owned = :t, updated_at = :u',
+            ConditionExpression: 'attribute_exists(linear_workspace_id)',
+            ExpressionAttributeValues: { ':t': true, ':u': new Date().toISOString() },
+          }));
+          console.log('  ✓ Recorded that this workspace owns its signing secret');
+        } catch (err) {
+          if ((err as { name?: string })?.name === 'ConditionalCheckFailedException') {
             throw new CliError(
-              'Updated the signing secret, but could not record its provenance: '
-              + `${err instanceof Error ? err.message : String(err)}\n`
-              + '  Re-run this command once the registry table is writable, otherwise this\n'
-              + '  workspace is still treated as carrying an inherited secret.',
+              `Updated the signing secret, but workspace '${slug}' has no registry row `
+              + `(${stored.workspace_id}).\n  Run \`bgagent linear setup ${slug}\` so the workspace `
+              + 'is registered; the secret you just entered will be preserved.',
             );
           }
+          throw new CliError(
+            'Updated the signing secret, but could not record its provenance: '
+            + `${err instanceof Error ? err.message : String(err)}\n`
+            + '  Re-run this command once the registry table is writable, otherwise this\n'
+            + '  workspace is still treated as carrying an inherited secret.',
+          );
         }
 
         console.log();

From d100b5c8073705ea5ef2a4d388038caa5baa9a48 Mon Sep 17 00:00:00 2001
From: Sphia Sadek <isadeks@gmail.com>
Date: Mon, 14 Sep 2026 15:27:58 -0400
Subject: [PATCH 8/9] refactor(linear): drop migration tooling for a state one
 deployment is in
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The fix itself is 257 lines of cdk/src. The CLI around it had grown to 926 —
mostly tooling to migrate stacks into the new model. Reviewed against how many
deployments actually need migrating, two pieces did not earn their weight.

`backfill-project-workspaces` is gone, with its paginated project lister. A
single-workspace install does not need it at all: with one tenant every mapped
project belongs to that tenant, so a body-supplied projectId cannot steer a task
across a boundary. Its real audience was "a stack with two or more workspaces AND
pre-existing mappings", which is one deployment today. It was also the only part
of the branch that needed live Linear tokens, and the only part that has already
produced a defect — a report that told an operator to delete four valid mappings
because two workspaces had expired grants.

The doctor check that reported those mappings stays, because knowing about them
is still worth an operator's attention. Its remedy is now "re-run onboard-project
before you add a second workspace", and it says plainly that the state is harmless
while one workspace is active.

`assertMirrorIsSafe` is gone too. It guarded a branch that is unreachable from
`setup`, and the value that branch would produce is no longer trusted on its own
anyway — the receiver rejects a secret not recorded as the workspace's own once a
second workspace is active. The comment there now describes what the code does
rather than the refusal that used to follow it, and says what would need to change
if the up-front prompt is ever relaxed.

`backfill-secret-provenance` stays. This is the one place doing it by hand is
actively dangerous rather than merely tedious: the safe rule holds in one
direction only, and setting the flag on a workspace that holds the shared secret
silently reopens the hole. It also runs with no Linear dependency at all, which is
why it is the piece that already works on a stack with two dead grants.

935 tests green. The classifier's mutation was re-run after the removal, since it
sat between two deleted blocks and had to be restored.
---
 cli/src/commands/linear.ts                    | 256 +-----------------
 cli/src/platform-doctor.ts                    |   5 +-
 .../commands/linear-project-workspace.test.ts |  95 -------
 cli/test/platform-doctor.test.ts              |   2 +-
 docs/guides/LINEAR_SETUP_GUIDE.md             |   2 +-
 .../content/docs/using/Linear-setup-guide.md  |   2 +-
 6 files changed, 17 insertions(+), 345 deletions(-)

diff --git a/cli/src/commands/linear.ts b/cli/src/commands/linear.ts
index 0a8aa802b..cfe2eab34 100644
--- a/cli/src/commands/linear.ts
+++ b/cli/src/commands/linear.ts
@@ -643,44 +643,6 @@ export async function listOnboardedWorkspaceSlugs(args: {
   return collected;
 }
 
-/**
- * Refuse to copy the stack-wide signing secret into a workspace when another active
- * workspace exists.
- *
- * Mirroring is only correct for the first/only workspace, where the stack-wide value IS
- * that workspace's own secret. For an additional workspace it installs a DIFFERENT
- * tenant's key, after which both verify under the same secret and either can sign an
- * event whose routing values the other's are read from.
- *
- * Extracted rather than inlined at the one call site because that call site is currently
- * unreachable: `setup` collects this workspace's own secret up front and throws when
- * neither a supplied nor a legitimately-stored one exists, so the mirror branch cannot
- * be entered from there. An unreachable guard is an untested guard, and this keeps the
- * rule itself exercisable — and enforced if that prompt is ever relaxed.
- *
- * @param activeRows - active workspace-registry rows.
- * @param selfWorkspaceId - the workspace being set up, excluded from the count.
- * @param slug - workspace slug, for the remedy in the error text.
- */
-export function assertMirrorIsSafe(
-  activeRows: ReadonlyArray<Record<string, unknown>>,
-  selfWorkspaceId: string,
-  slug: string,
-): void {
-  const others = activeRows
-    .map((r) => r.linear_workspace_id as string | undefined)
-    .filter((id): id is string => Boolean(id) && id !== selfWorkspaceId);
-  if (others.length === 0) return;
-  throw new CliError(
-    `Workspace '${slug}' has no signing secret of its own, and this stack already has `
-    + `${others.length} other active Linear workspace(s).\n`
-    + '  Mirroring the stack-wide secret would give this workspace another tenant\'s key,\n'
-    + '  letting either one sign events the other\'s routing values are read from.\n'
-    + `  Re-run with --webhook-secret <lin_wh_…> read from '${slug}'s own Linear app, or set\n`
-    + `  it afterwards with \`bgagent linear update-webhook-secret ${slug}\`.`,
-  );
-}
-
 /**
  * What can be established about where a workspace's signing secret came from.
  *
@@ -849,55 +811,6 @@ export async function findProjectOwnerWorkspace(args: {
   return { kind: 'not-found', searched: args.slugs, errors };
 }
 
-/**
- * Every project id visible to one workspace's token, with its organization id.
- *
- * Paginated deliberately. `list-projects` asks for `projects(first: 100)` and stops,
- * which is fine for a human browsing but not for a backfill: a workspace with more
- * than a page of projects would leave the overflow unresolved and silently keep the
- * mappings the enforcement path is about to start rejecting.
- */
-export async function listWorkspaceProjectIds(args: {
-  readonly accessToken: string;
-  readonly fetchImpl?: typeof fetch;
-}): Promise<{ readonly workspaceId?: string; readonly projectIds: string[] }> {
-  const doFetch = args.fetchImpl ?? fetch;
-  const projectIds: string[] = [];
-  let workspaceId: string | undefined;
-  let cursor: string | undefined;
-
-  do {
-    const res = await doFetch('https://api.linear.app/graphql', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${args.accessToken}`,
-      },
-      body: JSON.stringify({
-        query: 'query($after: String) { organization { id } '
-          + 'projects(first: 250, after: $after) { nodes { id } pageInfo { hasNextPage endCursor } } }',
-        variables: { after: cursor ?? null },
-      }),
-    });
-    if (!res.ok) throw new CliError(`Linear API returned ${res.status}`);
-    const body = await res.json() as {
-      data?: {
-        organization?: { id?: string };
-        projects?: {
-          nodes?: Array<{ id: string }>;
-          pageInfo?: { hasNextPage?: boolean; endCursor?: string };
-        };
-      };
-    };
-    workspaceId ??= body.data?.organization?.id;
-    for (const n of body.data?.projects?.nodes ?? []) projectIds.push(n.id);
-    const pageInfo = body.data?.projects?.pageInfo;
-    cursor = pageInfo?.hasNextPage ? pageInfo.endCursor : undefined;
-  } while (cursor);
-
-  return { workspaceId, projectIds };
-}
-
 export function makeLinearCommand(): Command {
   const linear = new Command('linear')
     .description('Manage Linear integration');
@@ -1777,20 +1690,18 @@ export function makeLinearCommand(): Command {
           webhookSigningSecret = secretAction.secret;
         } else if (secretAction.kind === 'mirror-stackwide') {
           // Mirroring is only ever correct for the first/only workspace: the stack-wide
-          // value IS that workspace's own secret. For an additional workspace it copies
-          // a DIFFERENT tenant's secret into this one's bundle, after which both verify
-          // under the same key and either can sign an event the other's routing values
-          // would be trusted from. Refuse instead of warning.
+          // value IS that workspace's own secret. For an additional workspace it copies a
+          // DIFFERENT tenant's secret into this one's bundle, after which both verify
+          // under the same key and either can sign an event whose routing values the
+          // other's are read from.
           //
-          // Currently a safety net rather than a live path: `setup` collects this
-          // workspace's own secret up front and throws when neither a supplied nor a
-          // legitimately-stored one exists, so this branch is unreachable from there.
-          // Kept, and made to refuse, so the invariant survives that prompt changing.
-          assertMirrorIsSafe(
-            await listActiveWorkspaceRows(ddb, workspaceRegistryTable!),
-            identity.organization.id,
-            slug,
-          );
+          // Unreachable from here today: the up-front prompt above collects this
+          // workspace's own secret and throws when neither a supplied nor a legitimately
+          // stored one exists, which are the only ways into this branch. Left as-is
+          // rather than hardened, because the value it would produce is no longer
+          // trusted on its own — the receiver rejects a secret that is not recorded as
+          // the workspace's own once a second workspace is active. If that prompt is
+          // ever relaxed, this branch needs to refuse rather than warn.
           console.log('  ✓ No per-workspace secret yet; mirroring the stack-wide signing secret');
           console.log('    (if this is an ADDITIONAL workspace, its Linear webhook secret differs —');
           console.log(`     run \`bgagent linear update-webhook-secret ${slug}\` with this workspace's secret.)`);
@@ -2622,151 +2533,6 @@ export function makeLinearCommand(): Command {
       }),
   );
 
-  linear.addCommand(
-    new Command('backfill-project-workspaces')
-      .description('Record the owning workspace on project mappings that predate that field')
-      .option('--region <region>', 'AWS region (defaults to configured region)')
-      .option('--stack-name <name>', 'CloudFormation stack name', 'backgroundagent-dev')
-      .option('--dry-run', 'Report what would change without writing')
-      .action(async (opts) => {
-        const config = loadConfig();
-        const region = opts.region || config.region;
-
-        const tableName = await getStackOutput(region, opts.stackName, 'LinearProjectMappingTableName');
-        if (!tableName) {
-          console.error('Could not find LinearProjectMappingTableName in stack outputs. Deploy the stack first.');
-          process.exit(1);
-        }
-
-        const ddb = makeDocClient({ region });
-        const sm = makeClient(SecretsManagerClient, { region });
-        const registryTableName = await getStackOutput(region, opts.stackName, 'LinearWorkspaceRegistryTableName');
-
-        // Only rows missing the field are candidates. A row that already names a
-        // workspace is left alone even if it disagrees with Linear — re-pointing a
-        // live mapping is `onboard-project`'s job, not a backfill's.
-        const unbacked: Array<{ projectId: string; repo?: string }> = [];
-        let lastKey: Record<string, unknown> | undefined;
-        do {
-          const page = await ddb.send(new ScanCommand({ TableName: tableName, ExclusiveStartKey: lastKey }));
-          for (const item of page.Items ?? []) {
-            if (!item.linear_workspace_id && typeof item.linear_project_id === 'string') {
-              unbacked.push({ projectId: item.linear_project_id, repo: item.repo as string | undefined });
-            }
-          }
-          lastKey = page.LastEvaluatedKey;
-        } while (lastKey);
-
-        if (unbacked.length === 0) {
-          console.log('✓ Every project mapping already records its owning workspace.');
-          return;
-        }
-        console.log(`${unbacked.length} mapping(s) missing an owning workspace.`);
-        console.log();
-
-        // One pass per workspace rather than one lookup per row: a workspace with N
-        // unbacked projects would otherwise cost N round trips to learn the same thing.
-        const slugs = await listOnboardedWorkspaceSlugs({ sm, ddb, registryTableName: registryTableName ?? undefined });
-        const vaultWorkloadName = await resolveLinearVaultWorkloadName(region, opts.stackName);
-        const ownerByProject = new Map<string, { slug: string; workspaceId: string }>();
-        // Workspaces we could not query at all. Tracked because an unresolved mapping means
-        // something completely different depending on this: with every workspace reachable it
-        // really is a stale mapping, but with one unreachable the mapping may be perfectly
-        // valid and simply unverifiable right now. Live-caught — the first real run hit two
-        // workspaces with expired grants and the report told the operator to delete four good
-        // rows.
-        const unqueryable: string[] = [];
-
-        for (const slug of slugs) {
-          const token = await resolveWorkspaceAccessToken({
-            slug, sm, ddb, registryTableName: registryTableName ?? undefined, region, vaultWorkloadName,
-          });
-          if (token.kind !== 'token') {
-            unqueryable.push(slug);
-            console.log(`  ⚠ ${slug}: ${token.reason} — projects owned here cannot be resolved`);
-            continue;
-          }
-          try {
-            const listed = await listWorkspaceProjectIds({ accessToken: token.accessToken });
-            if (!listed.workspaceId) {
-              unqueryable.push(slug);
-              console.log(`  ⚠ ${slug}: Linear did not return an organization id`);
-              continue;
-            }
-            for (const id of listed.projectIds) {
-              // First writer wins, and a second claim is a real anomaly worth naming:
-              // one project id must not be visible to two workspaces.
-              const existing = ownerByProject.get(id);
-              if (existing && existing.workspaceId !== listed.workspaceId) {
-                console.log(`  ⚠ project ${id} is visible to both ${existing.slug} and ${slug} — skipping`);
-                ownerByProject.delete(id);
-                continue;
-              }
-              ownerByProject.set(id, { slug, workspaceId: listed.workspaceId });
-            }
-          } catch (err) {
-            unqueryable.push(slug);
-            console.log(`  ⚠ ${slug}: ${err instanceof Error ? err.message : String(err)}`);
-          }
-        }
-
-        let updated = 0;
-        const unresolved: string[] = [];
-        for (const row of unbacked) {
-          const owner = ownerByProject.get(row.projectId);
-          if (!owner) {
-            unresolved.push(row.projectId);
-            continue;
-          }
-          if (opts.dryRun) {
-            console.log(`  would set ${row.projectId} → ${owner.slug} (${owner.workspaceId})`);
-          } else {
-            await ddb.send(new UpdateCommand({
-              TableName: tableName,
-              Key: { linear_project_id: row.projectId },
-              UpdateExpression: 'SET linear_workspace_id = :w, updated_at = :u',
-              // Do not resurrect a row deleted while this command was running, and do
-              // not overwrite a workspace id written concurrently by onboard-project.
-              ConditionExpression: 'attribute_exists(linear_project_id) AND attribute_not_exists(linear_workspace_id)',
-              ExpressionAttributeValues: { ':w': owner.workspaceId, ':u': new Date().toISOString() },
-            })).catch((err: unknown) => {
-              if ((err as { name?: string })?.name === 'ConditionalCheckFailedException') {
-                console.log(`  · ${row.projectId} changed underneath the backfill — skipped`);
-                return;
-              }
-              throw err;
-            });
-            console.log(`  ✓ ${row.projectId} → ${owner.slug} (${owner.workspaceId})`);
-          }
-          updated += 1;
-        }
-
-        console.log();
-        if (opts.dryRun) {
-          console.log(`Dry run: ${updated} mapping(s) would be updated.`);
-        } else {
-          console.log(`✓ Updated ${updated} mapping(s).`);
-        }
-        if (unresolved.length > 0) {
-          console.log();
-          console.log(`⚠ ${unresolved.length} mapping(s) could not be resolved to a workspace:`);
-          for (const id of unresolved) console.log(`    ${id}`);
-          console.log();
-          if (unqueryable.length > 0) {
-            console.log(`Do NOT delete these yet. ${unqueryable.length} workspace(s) could not be queried`);
-            console.log(`(${unqueryable.join(', ')}), so a mapping owned by one of them is unresolved`);
-            console.log('here even when it is perfectly valid. Restore access for those workspaces —');
-            console.log('`bgagent platform doctor` reports Linear auth state — then re-run this command.');
-            console.log('Only rows still unresolved with every workspace reachable are genuinely stale.');
-          } else {
-            console.log('Every onboarded workspace was queried successfully, so these name projects none');
-            console.log('of them can see — a deleted project, or a workspace no longer installed. Re-run');
-            console.log('`bgagent linear onboard-project` for the ones still in use and remove the rest.');
-          }
-        }
-      }),
-  );
-
   linear.addCommand(
     new Command('backfill-secret-provenance')
       .description('Record which workspaces provably own their webhook signing secret')
diff --git a/cli/src/platform-doctor.ts b/cli/src/platform-doctor.ts
index f99814e6c..474e1d3a1 100644
--- a/cli/src/platform-doctor.ts
+++ b/cli/src/platform-doctor.ts
@@ -285,8 +285,9 @@ export async function checkLinearProjectWorkspaces(
       status: 'warn',
       detail: `${unbacked.length} of ${active.length} active Linear project mapping(s) do not record an `
         + 'owning workspace, so a webhook naming them cannot be checked against the workspace that '
-        + `signed it: ${projectIds}. Run \`bgagent linear backfill-project-workspaces --stack-name `
-        + '<stack>\` (add `--dry-run` first).',
+        + `signed it: ${projectIds}. Harmless while one workspace is active — there is no other `
+        + 'tenant to reach — but re-run `bgagent linear onboard-project <uuid> --repo <owner/repo>` '
+        + 'for each of them before onboarding a second workspace.',
     };
   } catch (err) {
     return {
diff --git a/cli/test/commands/linear-project-workspace.test.ts b/cli/test/commands/linear-project-workspace.test.ts
index ba5a7ecbd..b7d393afa 100644
--- a/cli/test/commands/linear-project-workspace.test.ts
+++ b/cli/test/commands/linear-project-workspace.test.ts
@@ -20,17 +20,13 @@
 // Resolving which workspace owns a Linear project. The mapping table is keyed on the
 // project id alone, so this resolution is what lets a later webhook check a
 // body-supplied `projectId` against the workspace that actually signed the delivery.
-import * as fs from 'fs';
-import * as path from 'path';
 import { GetSecretValueCommand, ListSecretsCommand, SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
 import { ScanCommand } from '@aws-sdk/lib-dynamodb';
 import {
-  assertMirrorIsSafe,
   classifyWebhookSecretProvenance,
   findProjectOwnerWorkspace,
   listActiveWorkspaceRows,
   listOnboardedWorkspaceSlugs,
-  listWorkspaceProjectIds,
   resolveWorkspaceAccessToken,
 } from '../../src/commands/linear';
 
@@ -260,78 +256,6 @@ describe('findProjectOwnerWorkspace', () => {
   });
 });
 
-describe('listWorkspaceProjectIds', () => {
-  test('returns the organization id alongside every visible project', async () => {
-    const listed = await listWorkspaceProjectIds({
-      accessToken: 'tok-acme',
-      fetchImpl: fakeLinear({ 'tok-acme': { org: ORG_ACME, projects: [PROJECT_A, PROJECT_B] } }),
-    });
-    expect(listed).toEqual({ workspaceId: ORG_ACME, projectIds: [PROJECT_A, PROJECT_B] });
-  });
-
-  test('follows pageInfo so projects past the first page are not silently dropped', async () => {
-    // A single-page implementation returns only PROJECT_A here, which during a backfill
-    // would leave PROJECT_B unresolved and its mapping unbacked.
-    let call = 0;
-    const paged = jest.fn(async () => {
-      call += 1;
-      return {
-        ok: true,
-        status: 200,
-        json: async () => ({
-          data: {
-            organization: { id: ORG_ACME },
-            projects: call === 1
-              ? { nodes: [{ id: PROJECT_A }], pageInfo: { hasNextPage: true, endCursor: 'cur' } }
-              : { nodes: [{ id: PROJECT_B }], pageInfo: { hasNextPage: false, endCursor: null } },
-          },
-        }),
-      } as unknown as Response;
-    }) as unknown as typeof fetch;
-
-    const listed = await listWorkspaceProjectIds({ accessToken: 'tok-acme', fetchImpl: paged });
-    expect(listed.projectIds).toEqual([PROJECT_A, PROJECT_B]);
-    expect(call).toBe(2);
-  });
-
-  test('raises on a non-OK response rather than reporting an empty workspace', async () => {
-    const failing = jest.fn(async () => ({ ok: false, status: 500, json: async () => ({}) } as unknown as Response)) as unknown as typeof fetch;
-    await expect(listWorkspaceProjectIds({ accessToken: 'tok', fetchImpl: failing }))
-      .rejects.toThrow('Linear API returned 500');
-  });
-});
-
-describe('assertMirrorIsSafe', () => {
-  const SELF = 'org-self';
-
-  test('allows the mirror when this is the only active workspace', () => {
-    expect(() => assertMirrorIsSafe([{ linear_workspace_id: SELF }], SELF, 'acme')).not.toThrow();
-  });
-
-  test('allows it on a genuinely empty registry', () => {
-    expect(() => assertMirrorIsSafe([], SELF, 'acme')).not.toThrow();
-  });
-
-  test('refuses when another active workspace would be the source of the secret', () => {
-    expect(() => assertMirrorIsSafe(
-      [{ linear_workspace_id: SELF }, { linear_workspace_id: 'org-other' }],
-      SELF,
-      'acme',
-    )).toThrow(/already has 1 other active Linear workspace/);
-  });
-
-  test('names the remedy, since refusing mid-setup is only useful with a way forward', () => {
-    expect(() => assertMirrorIsSafe([{ linear_workspace_id: 'org-other' }], SELF, 'acme'))
-      .toThrow(/update-webhook-secret acme/);
-  });
-
-  test('ignores rows with no workspace id rather than counting them as tenants', () => {
-    // A half-written registry row is not another tenant, and treating it as one would
-    // block a legitimate first-workspace mirror.
-    expect(() => assertMirrorIsSafe([{ workspace_slug: 'half' }], SELF, 'acme')).not.toThrow();
-  });
-});
-
 // The asymmetry is the point: "differs from stack-wide" proves ownership because
 // mirroring can copy nothing else, while "equals stack-wide" proves nothing because a
 // healthy first install stamps the same real secret into both slots.
@@ -372,22 +296,3 @@ describe('classifyWebhookSecretProvenance', () => {
 // told the operator they named deleted projects and should be removed. An unresolved
 // mapping means opposite things depending on whether every workspace was reachable, so
 // the conclusion has to branch on that.
-describe('unresolved-mapping guidance distinguishes stale rows from unreachable workspaces', () => {
-  const src = fs.readFileSync(path.join(__dirname, '../../src/commands/linear.ts'), 'utf8');
-
-  test('an unqueryable workspace is tracked, not silently folded into "stale"', () => {
-    // Source-level because the branch is inside a Commander action that would need the
-    // whole AWS + Linear surface stood up to reach; the behavioural proof is the live run.
-    expect(src).toContain('const unqueryable: string[] = []');
-    // Every skip path that means "we could not ask this workspace" must record it.
-    const pushes = src.match(/unqueryable\.push\(slug\)/g) ?? [];
-    expect(pushes.length).toBeGreaterThanOrEqual(3);
-  });
-
-  test('the delete-them conclusion is gated on every workspace having been queried', () => {
-    expect(src).toContain('Do NOT delete these yet');
-    expect(src).toContain('Every onboarded workspace was queried successfully');
-    // The unconditional wording that caused the defect must not come back.
-    expect(src).not.toContain('These name projects no onboarded workspace can see');
-  });
-});
diff --git a/cli/test/platform-doctor.test.ts b/cli/test/platform-doctor.test.ts
index b40b64cbb..fd4a8d1c3 100644
--- a/cli/test/platform-doctor.test.ts
+++ b/cli/test/platform-doctor.test.ts
@@ -162,7 +162,7 @@ describe('doctor verdict for Linear project → workspace binding', () => {
     expect(check.status).toBe('warn');
     expect(check.detail).toContain('proj-unbacked');
     expect(check.detail).not.toContain('proj-backed');
-    expect(check.detail).toContain('bgagent linear backfill-project-workspaces');
+    expect(check.detail).toContain('bgagent linear onboard-project');
   });
 
   test('caps the named ids so a large install does not bury the rest of the report', async () => {
diff --git a/docs/guides/LINEAR_SETUP_GUIDE.md b/docs/guides/LINEAR_SETUP_GUIDE.md
index 2fe0e5be7..55d4cbd96 100644
--- a/docs/guides/LINEAR_SETUP_GUIDE.md
+++ b/docs/guides/LINEAR_SETUP_GUIDE.md
@@ -130,7 +130,7 @@ Pass `--label <name>` to use a trigger label other than `bgagent`. Also availabl
 
 `onboard-project` asks Linear which workspace owns the project and records it on the mapping, so a later webhook naming that project can be checked against the workspace whose signature it arrived with. Narrow the search with `--slug <slug>` when you know the workspace. If the Linear API is unreachable, `--workspace-id <uuid>` records an owner without verifying it — a wrong value routes the project's tasks nowhere.
 
-Mappings created before this was recorded have no owning workspace. `bgagent platform doctor` reports them, and `bgagent linear backfill-project-workspaces` fills them in (run it with `--dry-run` first).
+Mappings created before this was recorded have no owning workspace. `bgagent platform doctor` reports them. That is harmless while a stack has one workspace, since there is no other tenant a project could be steered at — but re-run `onboard-project` for each of them before onboarding a second workspace.
 
 ### Signing secrets in a multi-workspace install
 
diff --git a/docs/src/content/docs/using/Linear-setup-guide.md b/docs/src/content/docs/using/Linear-setup-guide.md
index ecb46d942..7fd154211 100644
--- a/docs/src/content/docs/using/Linear-setup-guide.md
+++ b/docs/src/content/docs/using/Linear-setup-guide.md
@@ -134,7 +134,7 @@ Pass `--label <name>` to use a trigger label other than `bgagent`. Also availabl
 
 `onboard-project` asks Linear which workspace owns the project and records it on the mapping, so a later webhook naming that project can be checked against the workspace whose signature it arrived with. Narrow the search with `--slug <slug>` when you know the workspace. If the Linear API is unreachable, `--workspace-id <uuid>` records an owner without verifying it — a wrong value routes the project's tasks nowhere.
 
-Mappings created before this was recorded have no owning workspace. `bgagent platform doctor` reports them, and `bgagent linear backfill-project-workspaces` fills them in (run it with `--dry-run` first).
+Mappings created before this was recorded have no owning workspace. `bgagent platform doctor` reports them. That is harmless while a stack has one workspace, since there is no other tenant a project could be steered at — but re-run `onboard-project` for each of them before onboarding a second workspace.
 
 ### Signing secrets in a multi-workspace install
 

From 28d7a0332a2a7a3cbac1f48e4d05f893d69d5b73 Mon Sep 17 00:00:00 2001
From: Sphia Sadek <isadeks@gmail.com>
Date: Tue, 22 Sep 2026 16:33:10 -0400
Subject: [PATCH 9/9] test(linear): note why the fake UUIDs avoid twelve
 trailing digits
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The org-id fixtures use hex letters in the final group because a UUID ending in
twelve consecutive digits matches gitleaks' `aws-account-id` rule, which failed
CI's range-scoped secret scan on values that hold no secret.

The values themselves were corrected in place across this branch's history —
fixing them in a follow-up commit left them in the commit that introduced the
file, and the scan is range-scoped over every commit in the PR. Recorded as a
comment so the constraint survives the next person editing these constants.

Fixed in the fixture rather than allowlisted in `.gitleaks.toml`: widening a
shared security rule to accommodate a test constant is the wrong direction.
---
 cli/test/commands/linear-project-workspace.test.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/cli/test/commands/linear-project-workspace.test.ts b/cli/test/commands/linear-project-workspace.test.ts
index b7d393afa..0cbdac980 100644
--- a/cli/test/commands/linear-project-workspace.test.ts
+++ b/cli/test/commands/linear-project-workspace.test.ts
@@ -32,6 +32,9 @@ import {
 
 const PROJECT_A = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa';
 const PROJECT_B = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb';
+// Hex letters in the final group on purpose: a UUID ending in twelve consecutive
+// digits matches the secret scanner's AWS-account-id rule, which failed CI on a
+// fixture that holds no secret at all.
 const ORG_ACME = 'c0000000-0000-4000-8000-0000000ac0e1';
 const ORG_RIVAL = 'c0000000-0000-4000-8000-0000000b10a2';