feat(code-reviewer) add council review type data model

apps/web/src/app/api/internal/code-review-status/[reviewId]/route.test.ts

@@ -250,6 +250,8 @@ function makeReview(overrides: Partial<CloudAgentCodeReview> = {}): CloudAgentCo
     previous_summary_body: null,
     previous_summary_head_sha: null,
     manual_config: null,
+    review_type: 'standard',
+    trigger_source: null,
     model: null,
     total_tokens_in: null,
     total_tokens_out: null,

apps/web/src/app/api/webhooks/bitbucket/[integrationId]/route.test.ts

@@ -344,6 +344,7 @@ describe('POST /api/webhooks/bitbucket/[integrationId]', () => {
           pr_number: PULL_REQUEST_ID,
           head_sha: DEFAULT_HEAD_SHA,
           status: 'pending',
+          trigger_source: 'webhook',
         })
       );
       const events = await organizationWebhookEvents();

apps/web/src/app/api/webhooks/bitbucket/[integrationId]/route.ts

@@ -530,6 +530,7 @@ export async function POST(request: NextRequest, context: RouteContext) {
         headRef: pullRequest.source.branch,
         headSha: pullRequest.source.sha,
         platform: 'bitbucket',
+        triggerSource: 'webhook',
       });
       await completeBitbucketWebhookEventInTransaction(tx, event.id, observation);
       return {

apps/web/src/lib/code-reviews/core/council-entitlement.test.ts

@@ -0,0 +1,122 @@
+import { TRPCError } from '@trpc/server';
+
+const mockGetOrganizationById = jest.fn();
+const mockGetMostRecentSeatPurchase = jest.fn();
+const mockIsLocalCodeReviewDevelopmentEnabled = jest.fn();
+
+jest.mock('@/lib/organizations/organizations', () => ({
+  getOrganizationById: (...args: unknown[]) => mockGetOrganizationById(...args),
+}));
+jest.mock('@/lib/organizations/organization-seats', () => ({
+  getMostRecentSeatPurchase: (...args: unknown[]) => mockGetMostRecentSeatPurchase(...args),
+}));
+jest.mock('@/lib/config.server', () => ({
+  isLocalCodeReviewDevelopmentEnabled: () => mockIsLocalCodeReviewDevelopmentEnabled(),
+}));
+
+// Real classifyOrganizationEntitlement is used (not mocked) so the tests exercise the
+// canonical active-entitlement logic layered on top of the plan tier.
+import {
+  isCouncilEntitledForOrganization,
+  isCouncilEntitledForOwner,
+  assertCouncilCreationAllowed,
+} from './council-entitlement';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const hardExpiredTrialEnd = new Date(Date.now() - 5 * DAY_MS).toISOString();
+
+function enterpriseOrg(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'org-1',
+    plan: 'enterprise',
+    created_at: new Date(Date.now() - 60 * DAY_MS).toISOString(),
+    free_trial_end_at: hardExpiredTrialEnd,
+    require_seats: true,
+    settings: {},
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockIsLocalCodeReviewDevelopmentEnabled.mockReturnValue(false);
+  mockGetMostRecentSeatPurchase.mockResolvedValue(null);
+});
+
+describe('isCouncilEntitledForOrganization', () => {
+  it('returns true for an enterprise org with an active paid subscription', async () => {
+    mockGetOrganizationById.mockResolvedValue(enterpriseOrg());
+    mockGetMostRecentSeatPurchase.mockResolvedValue({ subscription_status: 'active' });
+
+    await expect(isCouncilEntitledForOrganization('org-1')).resolves.toBe(true);
+  });
+
+  it('returns false for a lapsed enterprise org (plan still enterprise, subscription ended, trial hard-expired)', async () => {
+    // Regression: plan is NOT downgraded on cancellation, so plan alone must not grant council.
+    mockGetOrganizationById.mockResolvedValue(enterpriseOrg());
+    mockGetMostRecentSeatPurchase.mockResolvedValue({ subscription_status: 'ended' });
+
+    await expect(isCouncilEntitledForOrganization('org-1')).resolves.toBe(false);
+  });
+
+  it('returns false for a non-enterprise plan without checking subscription status', async () => {
+    mockGetOrganizationById.mockResolvedValue(enterpriseOrg({ plan: 'teams' }));
+
+    await expect(isCouncilEntitledForOrganization('org-1')).resolves.toBe(false);
+    expect(mockGetMostRecentSeatPurchase).not.toHaveBeenCalled();
+  });
+
+  it('returns false when the organization does not exist or id is missing', async () => {
+    mockGetOrganizationById.mockResolvedValue(null);
+    await expect(isCouncilEntitledForOrganization('org-1')).resolves.toBe(false);
+    await expect(isCouncilEntitledForOrganization(null)).resolves.toBe(false);
+    expect(mockGetOrganizationById).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('isCouncilEntitledForOwner', () => {
+  it('is never entitled for personal (user) owners', async () => {
+    await expect(isCouncilEntitledForOwner({ type: 'user', id: 'u1', userId: 'u1' })).resolves.toBe(
+      false
+    );
+    expect(mockGetOrganizationById).not.toHaveBeenCalled();
+  });
+});
+
+describe('assertCouncilCreationAllowed', () => {
+  const orgOwner = { type: 'org', id: 'org-1', userId: 'u1' } as const;
+
+  it('is a no-op for non-council reviews', async () => {
+    await expect(
+      assertCouncilCreationAllowed({ owner: orgOwner, reviewType: 'standard' })
+    ).resolves.toBeUndefined();
+    expect(mockGetOrganizationById).not.toHaveBeenCalled();
+  });
+
+  it('throws FORBIDDEN when a council review is requested without entitlement', async () => {
+    mockGetOrganizationById.mockResolvedValue(enterpriseOrg());
+    mockGetMostRecentSeatPurchase.mockResolvedValue({ subscription_status: 'ended' });
+
+    await expect(
+      assertCouncilCreationAllowed({ owner: orgOwner, reviewType: 'council' })
+    ).rejects.toThrow(TRPCError);
+  });
+
+  it('allows a council review for an entitled enterprise org', async () => {
+    mockGetOrganizationById.mockResolvedValue(enterpriseOrg());
+    mockGetMostRecentSeatPurchase.mockResolvedValue({ subscription_status: 'active' });
+
+    await expect(
+      assertCouncilCreationAllowed({ owner: orgOwner, reviewType: 'council' })
+    ).resolves.toBeUndefined();
+  });
+
+  it('bypasses entitlement in local development', async () => {
+    mockIsLocalCodeReviewDevelopmentEnabled.mockReturnValue(true);
+
+    await expect(
+      assertCouncilCreationAllowed({ owner: orgOwner, reviewType: 'council' })
+    ).resolves.toBeUndefined();
+    expect(mockGetOrganizationById).not.toHaveBeenCalled();
+  });
+});

apps/web/src/lib/code-reviews/core/council-entitlement.ts

@@ -0,0 +1,76 @@
+import 'server-only';
+
+import { TRPCError } from '@trpc/server';
+import { getOrganizationById } from '@/lib/organizations/organizations';
+import { getMostRecentSeatPurchase } from '@/lib/organizations/organization-seats';
+import { classifyOrganizationEntitlement } from '@/lib/organizations/trial-utils';
+import { isLocalCodeReviewDevelopmentEnabled } from '@/lib/config.server';
+import type { CodeReviewType } from '@kilocode/db/schema-types';
+import type { Owner } from './schemas';
+
+/**
+ * Which plan tier grants council. Council is enterprise-only.
+ *
+ * NOTE: this is only the tier label. `organizations.plan` stays `'enterprise'` even
+ * after an enterprise subscription ends (it is not downgraded on cancellation), so plan
+ * alone is NOT proof of active entitlement. Active-subscription/trial status is layered
+ * on separately in `isCouncilEntitledForOrganization`. Staged rollout (which entitled
+ * users see council yet) is a separate client-side PostHog concern handled elsewhere.
+ */
+export function isCouncilEntitledPlan(plan: string | null | undefined): boolean {
+  return plan === 'enterprise';
+}
+
+/**
+ * Council reviews are an enterprise-only paid feature. An organization is entitled only
+ * when it is on the enterprise tier AND currently has active entitlement (active paid
+ * subscription or non-expired trial). This mirrors the canonical entitlement check used
+ * by `requireActiveSubscriptionOrTrial`, so a lapsed enterprise org (plan still
+ * `'enterprise'`, seat purchase `ended`, trial hard-expired) cannot create paid council
+ * reviews. Personal owners are never entitled.
+ */
+export async function isCouncilEntitledForOrganization(
+  organizationId: string | null | undefined
+): Promise<boolean> {
+  if (!organizationId) return false;
+  const organization = await getOrganizationById(organizationId);
+  if (!organization || !isCouncilEntitledPlan(organization.plan)) return false;
+
+  const latestPurchase = await getMostRecentSeatPurchase(organizationId);
+  const classification = classifyOrganizationEntitlement({
+    organization,
+    latestSeatPurchaseStatus: latestPurchase?.subscription_status ?? null,
+    now: new Date(),
+  });
+  return classification.hasEntitlement;
+}
+
+export async function isCouncilEntitledForOwner(owner: Owner): Promise<boolean> {
+  return owner.type === 'org' ? isCouncilEntitledForOrganization(owner.id) : false;
+}
+
+/**
+ * Single enforcement point for council entitlement, invoked at the review-creation
+ * boundary. Any path that persists a `council` review (manual or automated) passes
+ * through here, so a non-entitled owner can never create one. Local dev bypasses so
+ * the feature can be exercised without an enterprise org.
+ *
+ * Throws FORBIDDEN when a council review is requested without entitlement.
+ */
+export async function assertCouncilCreationAllowed(params: {
+  owner: Owner;
+  reviewType?: CodeReviewType;
+}): Promise<void> {
+  if (params.reviewType !== 'council') return;
+  if (isLocalCodeReviewDevelopmentEnabled()) return;
+  if (await isCouncilEntitledForOwner(params.owner)) return;
+  throw new TRPCError({
+    code: 'FORBIDDEN',
+    message: 'Council reviews require an Enterprise plan.',
+  });
+}
+
+// NOTE: a config-save guard (`assertCouncilConfigAllowed`) will be added alongside the
+// council config-save path (PR #5) that actually accepts a `council` config, so it lands
+// with its first caller rather than as an unreferenced export. The creation-boundary
+// guard above already prevents a non-entitled owner from *running* a council review.

apps/web/src/lib/code-reviews/core/schemas.ts

@@ -7,7 +7,12 @@
 
 import * as z from 'zod';
 import type { CloudAgentCodeReview } from '@kilocode/db/schema';
-import { CODE_REVIEW_PLATFORMS, ManualCodeReviewConfigSchema } from '@kilocode/db/schema-types';
+import {
+  CODE_REVIEW_PLATFORMS,
+  ManualCodeReviewConfigSchema,
+  CodeReviewTypeSchema,
+  CodeReviewTriggerSourceSchema,
+} from '@kilocode/db/schema-types';
 import { CODE_REVIEW_STATUSES } from '@kilocode/app-shared/code-review';
 import { CodeReviewAgentConfigSchema } from '@/lib/agent-config/core/types';
 
@@ -121,6 +126,10 @@ export const CreateReviewParamsSchema = z.object({
   platform: CodeReviewPlatformSchema.default('github'),
   platformProjectId: z.number().int().positive().optional(),
   manualConfig: ManualCodeReviewConfigSchema.nullable().optional(),
+  // Review type for this run; unset defaults to standard at the insert boundary.
+  reviewType: CodeReviewTypeSchema.optional(),
+  // Origin of the run (manual vs webhook); optional for legacy/unknown callers.
+  triggerSource: CodeReviewTriggerSourceSchema.optional(),
 });
 
 /**

apps/web/src/lib/code-reviews/db/code-reviews.ts

@@ -17,6 +17,7 @@ import {
 import { eq, and, asc, desc, count, ne, inArray, sql, sum, gte, lte, isNull } from 'drizzle-orm';
 import { captureException } from '@sentry/nextjs';
 import { CreateReviewParamsSchema } from '../core';
+import { assertCouncilCreationAllowed } from '../core/council-entitlement';
 import type {
   CodeReviewPlatform,
   CreateReviewParams,
@@ -204,6 +205,8 @@ function codeReviewInsertValues(
     platform: params.platform ?? 'github',
     platform_project_id: params.platformProjectId ?? null,
     manual_config: params.manualConfig ?? null,
+    review_type: params.reviewType ?? 'standard',
+    trigger_source: params.triggerSource ?? null,
     agent_version: 'v2',
     status: 'pending',
   };
@@ -216,6 +219,7 @@ function codeReviewInsertValues(
 export async function createCodeReview(params: CreateReviewParams): Promise<string> {
   try {
     CreateReviewParamsSchema.parse(params);
+    await assertCouncilCreationAllowed({ owner: params.owner, reviewType: params.reviewType });
     const [review] = await db
       .insert(cloud_agent_code_reviews)
       .values(codeReviewInsertValues(params))
@@ -1448,6 +1452,7 @@ export async function createCodeReviewIfAbsentInTransaction(
   params: CreateReviewParams
 ): Promise<{ reviewId: string; created: boolean }> {
   CreateReviewParamsSchema.parse(params);
+  await assertCouncilCreationAllowed({ owner: params.owner, reviewType: params.reviewType });
   const [created] = await tx
     .insert(cloud_agent_code_reviews)
     .values(codeReviewInsertValues(params))

apps/web/src/lib/code-reviews/manual-code-review-jobs.ts

@@ -207,6 +207,7 @@ export async function createManualCodeReviewJob(params: {
       platform: source.platform,
       platformProjectId: source.platformProjectId,
       manualConfig,
+      triggerSource: 'manual',
     });
 
     logExceptInTest('[manual-code-review-job] Created manual Code Reviewer job', {

apps/web/src/lib/integrations/platforms/bitbucket/manual-code-review-trigger.ts

@@ -465,6 +465,7 @@ export async function triggerManualBitbucketCodeReview(input: {
         headRef: pullRequest.source.branch,
         headSha: pullRequest.source.sha,
         platform: 'bitbucket',
+        triggerSource: 'manual',
       });
       return {
         cancelledReviews,

apps/web/src/lib/integrations/platforms/github/webhook-handlers/pull-request-handler.test.ts

@@ -392,6 +392,7 @@ describe('handlePullRequest', () => {
         platform: 'github',
         platformIntegrationId: '8b2ff443-8396-4b07-99ae-7015789da7dd',
         repoFullName: 'acme/widgets',
+        triggerSource: 'webhook',
       })
     );
     expect(mockTryDispatchPendingReviews).toHaveBeenCalledTimes(1);

apps/web/src/lib/integrations/platforms/github/webhook-handlers/pull-request-handler.ts

@@ -311,6 +311,7 @@ export async function handlePullRequestCodeReview(
       headRef: checkoutRef.checkoutRef,
       headSha: pull_request.head.sha,
       platform: 'github',
+      triggerSource: 'webhook',
     });
 
     logExceptInTest(

apps/web/src/lib/integrations/platforms/gitlab/webhook-handlers/merge-request-handler.test.ts

@@ -299,6 +299,7 @@ describe('handleMergeRequestCodeReview', () => {
         platformIntegrationId: '8b2ff443-8396-4b07-99ae-7015789da7dd',
         repoFullName: 'acme/widgets',
         platformProjectId: 123,
+        triggerSource: 'webhook',
       })
     );
     expect(mockTryDispatchPendingReviews).toHaveBeenCalledTimes(1);

apps/web/src/lib/integrations/platforms/gitlab/webhook-handlers/merge-request-handler.ts

@@ -285,6 +285,7 @@ export async function handleMergeRequestCodeReview(
       headSha,
       platform: PLATFORM.GITLAB,
       platformProjectId: project.id,
+      triggerSource: 'webhook',
     });
 
     logExceptInTest(`Created code review ${reviewId} for ${project.path_with_namespace}!${mr.iid}`);

packages/db/src/migrations/0183_great_mercury.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "cloud_agent_code_reviews" ADD COLUMN "review_type" text DEFAULT 'standard' NOT NULL;--> statement-breakpoint
+ALTER TABLE "cloud_agent_code_reviews" ADD COLUMN "trigger_source" text;