feat: add SCM webhook lifecycle triggers (#394)

* feat(core): add scm webhook contract

Defines a provider-agnostic SCM webhook contract in core types and
config so SCM plugins can verify and normalize inbound webhook events
without reshaping project config later.

* feat(scm): trigger lifecycle checks from github webhooks

Adds GitHub webhook verification and event parsing, exposes a web
webhook endpoint, and routes matching PR/branch events through the
existing lifecycle manager so CI and review reactions update immediately.

* fix(scm): verify github signatures with raw webhook bytes

Preserves the original webhook bytes alongside the decoded payload so
GitHub HMAC verification uses the exact request body while the route
continues to drive lifecycle checks through the existing manager.

* fix(web): wire scm webhook route into main branch services

Restores the main-branch service and route-test wiring while keeping the
new webhook route coverage and scoped lifecycle helper in place.

* fix(webhooks): use singleton lifecycle manager and fail closed on scm API errors

Reuses the existing services lifecycle manager for webhook-triggered checks
so reactions and state transitions don't replay from a fresh instance, and
restores fail-closed behavior for GitHub review comment fetch failures.

* fix(webhooks): tighten project matching and restore scm compatibility methods

Prevents repository-less webhook events from matching all projects, restores
GitHub SCM PR utility methods and CI status rollup fallback, and adds tests
covering the compatibility paths and safer project matching behavior.

* fix(webhooks): pre-check content length and continue on parse errors

Adds an early content-length guard against configured maxBodyBytes before
reading the body and changes candidate parse failures to fail-forward so
one malformed payload path does not abort other valid candidate handling.

* fix(scm-github): parse review-comment timestamps from comment payload

Use comment.updated_at/created_at for pull_request_review_comment webhook
timestamps so normalized events retain temporal data for comment events.

* fix(webhooks): apply early size guard only when all candidates are bounded

Uses the broadest candidate limit for pre-read content-length checks and
skips early rejection when any matching project has no configured limit,
while retaining per-candidate verification limits.

* fix(webhooks): normalize repo matching and skip terminal sessions

Match webhook repository names case-insensitively against configured project
repos and avoid lifecycle checks for terminal sessions when resolving
webhook-affected sessions.

* fix(webhooks): fail forward when lifecycle checks throw

* fix(scm-github): parse push webhook branch and sha

* refactor(scm-github): dedupe cli exec helper wrappers

* fix(scm-github): tighten exec helper type and comment timestamps

* fix(scm-github): prefer head_commit timestamp for push events

* fix(webhooks): tighten repository parsing and helper visibility

* fix(scm-github): ignore non-head refs for push branch

* chore: trigger bugbot rerun

* feat(scm-gitlab): add webhook verification and event parsing

* fix(webhooks): share parser utils and handle check_run branch

* fix(webhooks): ignore gitlab tag refs in ci branch mapping

* fix(scm-gitlab): harden token and tag ref handling

* chore(scm-gitlab): update webhook helpers around bugbot threads

Author: harsh-batheja

agent-orchestrator.yaml.example

@@ -36,6 +36,17 @@ projects:
     #   plugin: linear
     #   teamId: "your-team-id"
 
+    # SCM webhook acceleration (optional)
+    # scm:
+    #   plugin: github
+    #   webhook:
+    #     path: /api/webhooks/github
+    #     secretEnvVar: GITHUB_WEBHOOK_SECRET
+    #     signatureHeader: x-hub-signature-256
+    #     eventHeader: x-github-event
+    #     deliveryHeader: x-github-delivery
+    #     maxBodyBytes: 1048576
+
     # Files to symlink into workspaces
     # symlinks: [.env, .claude]
 
@@ -45,11 +56,7 @@ projects:
 
     # Agent-specific config
     # agentConfig:
-    #   permissions: permissionless    # modes: permissionless | default | auto-edit | suggest
-    #                                  # - permissionless: no interactive permission prompts
-    #                                  # - default: agent defaults
-    #                                  # - auto-edit: auto-approve edits where supported
-    #                                  # - suggest: conservative/untrusted-approval mode where supported
+    #   permissions: skip    # --dangerously-skip-permissions
     #   model: opus
 
     # Inline rules included in every agent prompt for this project
@@ -67,10 +74,6 @@ projects:
     # OpenCode issue session strategy (only for agent: opencode)
     # opencodeIssueSessionStrategy: reuse   # reuse | delete | ignore
 
-    # OpenCode orchestrator session strategy (only for agent: opencode)
-    # Controls how the orchestrator's OpenCode session is managed
-    # orchestratorSessionStrategy: reuse    # reuse | delete | ignore
-
     # Per-project reaction overrides
     # reactions:
     #   approved-and-green:

packages/core/package.json

@@ -18,6 +18,10 @@
     "./utils": {
       "types": "./dist/utils.d.ts",
       "import": "./dist/utils.js"
+    },
+    "./scm-webhook-utils": {
+      "types": "./dist/scm-webhook-utils.d.ts",
+      "import": "./dist/scm-webhook-utils.js"
     }
   },
   "files": [

packages/core/src/__tests__/config-validation.test.ts

@@ -274,6 +274,64 @@ describe("Config Validation - Session Prefix Regex", () => {
   });
 });
 
+describe("Config Validation - SCM webhook contract", () => {
+  it("accepts a project scm webhook block and defaults enabled=true", () => {
+    const config = validateConfig({
+      projects: {
+        proj1: {
+          path: "/repos/test",
+          repo: "org/test",
+          defaultBranch: "main",
+          scm: {
+            plugin: "github",
+            webhook: {
+              path: "/api/webhooks/github",
+              secretEnvVar: "GITHUB_WEBHOOK_SECRET",
+              eventHeader: "x-github-event",
+              deliveryHeader: "x-github-delivery",
+              signatureHeader: "x-hub-signature-256",
+              maxBodyBytes: 1048576,
+            },
+          },
+        },
+      },
+    });
+
+    expect(config.projects["proj1"]?.scm).toEqual({
+      plugin: "github",
+      webhook: {
+        enabled: true,
+        path: "/api/webhooks/github",
+        secretEnvVar: "GITHUB_WEBHOOK_SECRET",
+        eventHeader: "x-github-event",
+        deliveryHeader: "x-github-delivery",
+        signatureHeader: "x-hub-signature-256",
+        maxBodyBytes: 1048576,
+      },
+    });
+  });
+
+  it("rejects non-positive scm webhook maxBodyBytes", () => {
+    expect(() =>
+      validateConfig({
+        projects: {
+          proj1: {
+            path: "/repos/test",
+            repo: "org/test",
+            defaultBranch: "main",
+            scm: {
+              plugin: "github",
+              webhook: {
+                maxBodyBytes: 0,
+              },
+            },
+          },
+        },
+      }),
+    ).toThrow();
+  });
+});
+
 describe("Config Schema Validation", () => {
   it("requires projects field", () => {
     const config = {

packages/core/src/config.ts

@@ -70,6 +70,17 @@ const TrackerConfigSchema = z
 const SCMConfigSchema = z
   .object({
     plugin: z.string(),
+    webhook: z
+      .object({
+        enabled: z.boolean().default(true),
+        path: z.string().optional(),
+        secretEnvVar: z.string().optional(),
+        signatureHeader: z.string().optional(),
+        eventHeader: z.string().optional(),
+        deliveryHeader: z.string().optional(),
+        maxBodyBytes: z.number().int().positive().optional(),
+      })
+      .optional(),
   })
   .passthrough();
 

packages/core/src/index.ts

@@ -95,6 +95,12 @@ export {
   normalizeRetryConfig,
   readLastJsonlEntry,
 } from "./utils.js";
+export {
+  getWebhookHeader,
+  parseWebhookJsonObject,
+  parseWebhookTimestamp,
+  parseWebhookBranchRef,
+} from "./scm-webhook-utils.js";
 export { asValidOpenCodeSessionId } from "./opencode-session-id.js";
 export { normalizeOrchestratorSessionStrategy } from "./orchestrator-session-strategy.js";
 export type { NormalizedOrchestratorSessionStrategy } from "./orchestrator-session-strategy.js";

packages/core/src/scm-webhook-utils.ts

@@ -0,0 +1,35 @@
+import type { SCMWebhookRequest } from "./types.js";
+
+export function getWebhookHeader(
+  headers: SCMWebhookRequest["headers"],
+  name: string,
+): string | undefined {
+  const target = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() !== target) continue;
+    if (Array.isArray(value)) return value[0];
+    return value;
+  }
+  return undefined;
+}
+
+export function parseWebhookJsonObject(body: string): Record<string, unknown> {
+  const parsed: unknown = JSON.parse(body);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Webhook payload must be a JSON object");
+  }
+  return parsed as Record<string, unknown>;
+}
+
+export function parseWebhookTimestamp(value: unknown): Date | undefined {
+  if (typeof value !== "string") return undefined;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
+export function parseWebhookBranchRef(ref: unknown): string | undefined {
+  if (typeof ref !== "string" || ref.length === 0) return undefined;
+  if (ref.startsWith("refs/heads/")) return ref.slice("refs/heads/".length);
+  if (ref.startsWith("refs/")) return undefined;
+  return ref;
+}

packages/core/src/types.ts

@@ -518,6 +518,16 @@ export interface CreateIssueInput {
 export interface SCM {
   readonly name: string;
 
+  verifyWebhook?(
+    request: SCMWebhookRequest,
+    project: ProjectConfig,
+  ): Promise<SCMWebhookVerificationResult>;
+
+  parseWebhook?(
+    request: SCMWebhookRequest,
+    project: ProjectConfig,
+  ): Promise<SCMWebhookEvent | null>;
+
   // --- PR Lifecycle ---
 
   /** Detect if a session has an open PR (by branch name) */
@@ -601,6 +611,42 @@ export const PR_STATE = {
 
 export type MergeMethod = "merge" | "squash" | "rebase";
 
+export interface SCMWebhookRequest {
+  method: string;
+  headers: Record<string, string | string[] | undefined>;
+  body: string;
+  rawBody?: Uint8Array;
+  path?: string;
+  query?: Record<string, string | string[] | undefined>;
+}
+
+export interface SCMWebhookVerificationResult {
+  ok: boolean;
+  reason?: string;
+  deliveryId?: string;
+  eventType?: string;
+}
+
+export type SCMWebhookEventKind = "pull_request" | "ci" | "review" | "comment" | "push" | "unknown";
+
+export interface SCMWebhookEvent {
+  provider: string;
+  kind: SCMWebhookEventKind;
+  action: string;
+  rawEventType: string;
+  deliveryId?: string;
+  projectId?: string;
+  repository?: {
+    owner: string;
+    name: string;
+  };
+  prNumber?: number;
+  branch?: string;
+  sha?: string;
+  timestamp?: Date;
+  data: Record<string, unknown>;
+}
+
 // --- CI Types ---
 
 export interface CICheck {
@@ -951,9 +997,20 @@ export interface TrackerConfig {
 
 export interface SCMConfig {
   plugin: string;
+  webhook?: SCMWebhookConfig;
   [key: string]: unknown;
 }
 
+export interface SCMWebhookConfig {
+  enabled?: boolean;
+  path?: string;
+  secretEnvVar?: string;
+  signatureHeader?: string;
+  eventHeader?: string;
+  deliveryHeader?: string;
+  maxBodyBytes?: number;
+}
+
 export interface NotifierConfig {
   plugin: string;
   [key: string]: unknown;