@generacy-ai/orchestrator 0.7.0 → 0.9.0

package/dist/services/webhook-setup-service.js

@@ -8,40 +8,54 @@
  * This eliminates manual webhook configuration and ensures near-instant label
  * detection via Smee instead of relying on 15-minute polling fallback.
  */
+import { readFile } from 'node:fs/promises';
 import { executeCommand } from '@generacy-ai/workflow-engine';
 import { JitTokenError } from '@generacy-ai/control-plane';
+/** Locked event set on all Generacy-created/updated webhooks (FR-001). */
+const LOCKED_EVENTS = ['issues', 'pull_request', 'check_run', 'check_suite'];
+/** Default location of the persisted smee channel URL (written by SmeeChannelResolver). */
+const DEFAULT_CHANNEL_FILE_PATH = '/var/lib/generacy/smee-channel';
 /**
  * Service for auto-configuring GitHub webhooks for monitored repositories.
  *
  * When SMEE_CHANNEL_URL is configured, this service verifies and creates
  * GitHub webhooks for all monitored repositories on orchestrator startup,
  * ensuring near-instant label detection via Smee instead of 15-minute polling.
- *
- * Features:
- * - Creates missing webhooks pointing to Smee channel URL
- * - Skips existing active webhooks (idempotent)
- * - Reactivates inactive webhooks and merges events
- * - Graceful error handling (per-repo failures don't block startup)
- * - Warns on event mismatches without modifying
- * - Validates Smee URL format (warns on non-smee.io URLs)
- *
- * Error Handling:
- * - 403/404 errors: Logged as warnings, system falls back to polling
- * - Network/API errors: Logged and continue with next repo
- * - All errors are non-fatal and don't block orchestrator startup
  */
 export class WebhookSetupService {
     _logger;
     _tokenProvider;
+    _sendRelayEvent;
+    _statusReporter;
+    _channelFilePath;
+    _installationIdProvider;
+    /**
+     * Set of `owner/repo` values for which the 403 fail-loud triple has already
+     * fired within this orchestrator boot. Bounds cloud-side banner noise to
+     * at most N events per boot for a cluster with N configured repos
+     * (see `contracts/webhook-registration-forbidden-event.md` §"Emission rate").
+     */
+    _forbiddenFiredForRepo = new Set();
+    /**
+     * Cached github-app installation id resolved once at startup via
+     * `installationIdProvider`. `undefined` means "not yet resolved this boot";
+     * `null` means "resolved, but no id available"; `number` means resolved.
+     */
+    _installationIdCache;
     /**
      * Creates a new WebhookSetupService instance.
      *
      * @param logger - Logger instance for structured logging (Pino/Fastify compatible)
      * @param tokenProvider - Optional async function returning a GH_TOKEN for auth
+     * @param options - Optional DI hooks for #972 fail-loud triple + FR-004 persisted-URL healing
      */
-    constructor(logger, tokenProvider) {
+    constructor(logger, tokenProvider, options = {}) {
         this._logger = logger;
         this._tokenProvider = tokenProvider;
+        this._sendRelayEvent = options.sendRelayEvent;
+        this._statusReporter = options.statusReporter;
+        this._channelFilePath = options.channelFilePath ?? DEFAULT_CHANNEL_FILE_PATH;
+        this._installationIdProvider = options.installationIdProvider;
     }
     /**
      * Invariant: when a tokenProvider is configured, the env override ALWAYS
@@ -60,38 +74,13 @@ export class WebhookSetupService {
     /**
      * Ensure webhooks exist for all repositories.
      *
-     * This is the main entry point for webhook setup. For each repository:
-     * 1. Lists existing webhooks via GitHub API
-     * 2. Checks if a webhook already exists for the Smee channel URL
-     * 3. Creates missing webhooks, reactivates inactive ones, or skips active ones
-     * 4. Logs results and continues on errors (graceful degradation)
-     *
-     * Per-repository errors are logged but don't block the overall process,
-     * allowing partial success when some repositories fail (e.g., due to
-     * insufficient permissions).
+     * For each repository, evaluates the decision matrix documented at
+     * `specs/972-summary-snappoll-preview/contracts/ensure-webhooks-behavior.md`.
+     * Per-repository errors are logged but don't block the overall process.
      *
      * @param smeeChannelUrl - The Smee channel URL to configure webhooks for
-     *                         (e.g., 'https://smee.io/abc123'). URL is validated
-     *                         and a warning is logged if it doesn't point to smee.io.
-     * @param repositories - List of repositories to ensure webhooks for. Each
-     *                       repository is processed sequentially to avoid rate limits.
-     * @returns Promise resolving to a summary of webhook setup results, including
-     *          aggregate counts and detailed per-repository results.
-     *
-     * @example
-     * ```typescript
-     * const service = new WebhookSetupService(logger);
-     * const summary = await service.ensureWebhooks(
-     *   'https://smee.io/abc123',
-     *   [
-     *     { owner: 'myorg', repo: 'myrepo' },
-     *     { owner: 'myorg', repo: 'another-repo' }
-     *   ]
-     * );
-     * console.log(`Created: ${summary.created}, Skipped: ${summary.skipped}, Failed: ${summary.failed}`);
-     * ```
-     *
-     * @see {@link WebhookSetupSummary} for the structure of the returned summary
+     * @param repositories - List of repositories to ensure webhooks for
+     * @returns Promise resolving to a summary of webhook setup results
      */
     async ensureWebhooks(smeeChannelUrl, repositories) {
         // Validate Smee URL (warn if not smee.io)
@@ -99,6 +88,10 @@ export class WebhookSetupService {
         if (!normalizedUrl.startsWith('https://smee.io/')) {
             this._logger.warn({ smeeChannelUrl }, 'SMEE_CHANNEL_URL does not point to smee.io — ensure this URL is correct');
         }
+        // Read the persisted channel URL once per ensureWebhooks() invocation.
+        // Used to detect the FR-004 stale-channel-rotation case (row 6 of the
+        // decision matrix).
+        const previouslyPersistedUrl = await this._readPersistedChannelUrl();
         // Initialize counters
         const results = [];
         let created = 0;
@@ -107,7 +100,7 @@ export class WebhookSetupService {
         let failed = 0;
         // Process each repository
         for (const repo of repositories) {
-            const result = await this._ensureWebhookForRepo(repo.owner, repo.repo, smeeChannelUrl);
+            const result = await this._ensureWebhookForRepo(repo.owner, repo.repo, smeeChannelUrl, previouslyPersistedUrl);
             results.push(result);
             // Update counters based on action
             switch (result.action) {
@@ -138,248 +131,400 @@ export class WebhookSetupService {
     /**
      * Ensure webhook exists for a single repository.
      *
-     * Internal method that handles webhook verification and setup for one repository.
-     * All errors are caught and converted to a 'failed' result to allow graceful
-     * degradation.
-     *
-     * Logic flow:
-     * 1. List existing webhooks
-     * 2. Find webhook matching the Smee URL (case-insensitive)
-     * 3. If not found: Create new webhook → 'created'
-     * 4. If found and active: Skip → 'skipped' (warn on event mismatch)
-     * 5. If found but inactive: Reactivate and merge events → 'reactivated'
-     *
-     * @param owner - Repository owner (organization or user)
-     * @param repo - Repository name
-     * @param smeeChannelUrl - The Smee channel URL to configure
-     * @returns Promise resolving to the result of webhook setup for this repository
-     *
-     * @throws Never throws - all errors are caught and returned as 'failed' results
+     * Implements rows 1-11 of the per-repo decision matrix in
+     * `contracts/ensure-webhooks-behavior.md`.
      */
-    async _ensureWebhookForRepo(owner, repo, smeeChannelUrl) {
+    async _ensureWebhookForRepo(owner, repo, smeeChannelUrl, previouslyPersistedUrl) {
+        // List existing webhooks. When list fails with 403, emit the fail-loud
+        // triple; other list errors return a `failed` result with the raw stderr.
+        let existingWebhooks;
         try {
-            // List existing webhooks
-            const existingWebhooks = await this._listRepoWebhooks(owner, repo);
-            // Check for matching webhook
-            const matchingWebhook = this._findMatchingWebhook(existingWebhooks, smeeChannelUrl);
-            // No matching webhook - create new one
-            if (!matchingWebhook) {
-                const webhookId = await this._createRepoWebhook(owner, repo, smeeChannelUrl);
-                this._logger.info({ owner, repo, webhookId, action: 'created' }, 'Created new webhook for repository');
-                return {
+            existingWebhooks = await this._listRepoWebhooks(owner, repo);
+        }
+        catch (error) {
+            return this._handleGhFailure(owner, repo, error, 'list', 'Insufficient permissions to manage webhooks (admin:repo_hook required)');
+        }
+        // FR-004 decision matrix: find whether to skip, reactivate, PATCH, log-and-skip, or create.
+        const selection = this._selectExistingHookForUpdate(existingWebhooks, smeeChannelUrl, previouslyPersistedUrl);
+        if (selection.kind === 'skip-active') {
+            const hook = selection.hook;
+            const missingEvents = LOCKED_EVENTS.filter((e) => !hook.events.includes(e));
+            if (missingEvents.length > 0) {
+                this._logger.warn({
                     owner,
                     repo,
-                    action: 'created',
-                    webhookId,
-                };
+                    webhookId: hook.id,
+                    currentEvents: hook.events,
+                    expectedEvents: ['issues'],
+                }, 'Existing webhook has event mismatch - events not updated');
             }
-            // Matching webhook exists and is active
-            if (matchingWebhook.active) {
-                // Check for event mismatch
-                const hasIssuesEvent = matchingWebhook.events.includes('issues');
-                if (!hasIssuesEvent) {
-                    this._logger.warn({
-                        owner,
-                        repo,
-                        webhookId: matchingWebhook.id,
-                        currentEvents: matchingWebhook.events,
-                        expectedEvents: ['issues'],
-                    }, 'Existing webhook has event mismatch - events not updated');
-                }
-                this._logger.info({ owner, repo, webhookId: matchingWebhook.id, action: 'skipped' }, 'Webhook already exists and is active');
-                return {
-                    owner,
-                    repo,
-                    action: 'skipped',
-                    webhookId: matchingWebhook.id,
-                };
+            this._logger.info({ owner, repo, webhookId: hook.id, action: 'skipped' }, 'Webhook already exists and is active');
+            return { owner, repo, action: 'skipped', webhookId: hook.id };
+        }
+        if (selection.kind === 'reactivate') {
+            const hook = selection.hook;
+            const mergedEvents = [...new Set([...hook.events, 'issues'])];
+            try {
+                await this._updateRepoWebhook(owner, repo, hook.id, {
+                    active: true,
+                    events: mergedEvents,
+                });
+            }
+            catch (error) {
+                return this._handleGhFailure(owner, repo, error, 'patch', 'Failed to manage webhook for repository');
             }
-            // Matching webhook exists but is inactive - reactivate and merge events
-            const mergedEvents = [
-                ...new Set([...matchingWebhook.events, 'issues']),
-            ];
-            await this._updateRepoWebhook(owner, repo, matchingWebhook.id, {
-                active: true,
-                events: mergedEvents,
-            });
             this._logger.info({
                 owner,
                 repo,
-                webhookId: matchingWebhook.id,
+                webhookId: hook.id,
                 action: 'reactivated',
                 events: mergedEvents,
             }, 'Reactivated inactive webhook');
-            return {
+            return { owner, repo, action: 'reactivated', webhookId: hook.id };
+        }
+        if (selection.kind === 'update-url') {
+            const hook = selection.hook;
+            try {
+                await this._updateRepoWebhookConfig(owner, repo, hook.id, {
+                    url: smeeChannelUrl,
+                    active: true,
+                    events: [...LOCKED_EVENTS],
+                });
+            }
+            catch (error) {
+                return this._handleGhFailure(owner, repo, error, 'patch', 'Failed to manage webhook for repository');
+            }
+            this._logger.info({
                 owner,
                 repo,
+                webhookId: hook.id,
                 action: 'reactivated',
-                webhookId: matchingWebhook.id,
-            };
+                oldUrl: hook.config?.url,
+                newUrl: smeeChannelUrl,
+                events: [...LOCKED_EVENTS],
+            }, 'Updated Generacy webhook to current channel URL');
+            return { owner, repo, action: 'reactivated', webhookId: hook.id };
+        }
+        if (selection.kind === 'foreign') {
+            const hook = selection.hook;
+            const truncatedUrl = (hook.config?.url ?? '').slice(0, 80);
+            this._logger.warn({ owner, repo, webhookId: hook.id, foreignUrl: truncatedUrl }, 'Foreign webhook present; not modifying');
+            return { owner, repo, action: 'skipped', webhookId: hook.id };
+        }
+        // selection.kind === 'create' — no existing hook match, POST a new one.
+        let webhookId;
+        try {
+            webhookId = await this._createRepoWebhook(owner, repo, smeeChannelUrl);
         }
         catch (error) {
-            // Handle per-repo errors gracefully
-            const errorMessage = String(error);
-            // Determine appropriate log level and message based on error type
-            if (error instanceof JitTokenError) {
-                this._logger.warn({ owner, repo, code: error.code, message: error.message }, 'JIT GitHub token refresh failed — skipping webhook setup for repository');
-            }
-            else if (errorMessage.includes('403') || errorMessage.includes('404')) {
-                this._logger.warn({ owner, repo, error: errorMessage }, 'Insufficient permissions to manage webhooks (admin:repo_hook required)');
-            }
-            else if (errorMessage.includes('500')) {
-                this._logger.warn({ owner, repo, error: errorMessage }, 'GitHub API error while managing webhooks');
-            }
-            else {
-                this._logger.warn({ owner, repo, error: errorMessage }, 'Failed to manage webhook for repository');
+            return this._handleGhFailure(owner, repo, error, 'create', 'Failed to manage webhook for repository');
+        }
+        this._logger.info({ owner, repo, webhookId, action: 'created' }, 'Created new webhook for repository');
+        return { owner, repo, action: 'created', webhookId };
+    }
+    /**
+     * Read the previously-persisted smee channel URL from disk.
+     *
+     * Returns `null` on ENOENT, on empty content, or on any read/parse error.
+     * Written only by `SmeeChannelResolver`; read-only here.
+     */
+    async _readPersistedChannelUrl() {
+        try {
+            const raw = await readFile(this._channelFilePath, 'utf8');
+            const trimmed = raw.trim();
+            return trimmed.length > 0 ? trimmed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Decision matrix for choosing what to do with the existing hook set.
+     *
+     * Implements rows 4-9 of `contracts/ensure-webhooks-behavior.md`. First
+     * match wins. `matches(A, B)` is case-insensitive string equality per
+     * `data-model.md` §"Field-Level Validation Rules Summary".
+     */
+    _selectExistingHookForUpdate(hooks, currentUrl, persistedUrl) {
+        const currentNormalized = currentUrl.toLowerCase();
+        const persistedNormalized = persistedUrl?.toLowerCase() ?? null;
+        // Row 4/5: hook whose config.url matches the CURRENT channel URL.
+        const currentMatch = hooks.find((h) => (h.config?.url?.toLowerCase() ?? '') === currentNormalized);
+        if (currentMatch) {
+            return currentMatch.active
+                ? { kind: 'skip-active', hook: currentMatch }
+                : { kind: 'reactivate', hook: currentMatch };
+        }
+        // Row 6: hook whose config.url matches the PERSISTED (rotated) channel URL.
+        if (persistedNormalized !== null &&
+            persistedNormalized !== currentNormalized) {
+            const persistedMatch = hooks.find((h) => (h.config?.url?.toLowerCase() ?? '') === persistedNormalized);
+            if (persistedMatch) {
+                return { kind: 'update-url', hook: persistedMatch };
             }
+        }
+        // Row 8: existing foreign smee hook — do not touch, log-and-skip.
+        // A hook is "foreign" when its URL is neither the current nor the persisted
+        // Generacy channel URL. We only flag smee.io URLs to keep the signal
+        // relevant (a random non-smee webhook is almost certainly the operator's).
+        const foreign = hooks.find((h) => {
+            const url = (h.config?.url ?? '').toLowerCase();
+            if (!url)
+                return false;
+            if (url === currentNormalized)
+                return false;
+            if (persistedNormalized !== null && url === persistedNormalized)
+                return false;
+            return url.startsWith('https://smee.io/');
+        });
+        if (foreign) {
+            return { kind: 'foreign', hook: foreign };
+        }
+        // Row 9: no match — POST a new hook.
+        return { kind: 'create' };
+    }
+    /**
+     * Detect whether a `gh api` failure is the 403 fail-loud case.
+     *
+     * Matches the two error patterns GitHub can return for the same underlying
+     * failure mode: `HTTP 403` (canonical) and `Resource not accessible by
+     * integration` (typical stderr wording). Both patterns fire for the same
+     * missing-scope case; matching either is sufficient (case-insensitive
+     * substring). See `contracts/webhook-registration-forbidden-event.md`
+     * §"Trigger conditions".
+     */
+    _isForbiddenError(stderr) {
+        const lower = stderr.toLowerCase();
+        return (lower.includes('http 403') ||
+            lower.includes('resource not accessible by integration'));
+    }
+    /**
+     * Handle any `gh` failure (list, create, or patch) from within
+     * `_ensureWebhookForRepo`. On 403 → emit the fail-loud triple; on 404/500
+     * → warn-only; on all other errors → generic warn.
+     *
+     * Guarantees the log line is the audit floor (always fires); relay event +
+     * status transition are best-effort per the contracts.
+     */
+    _handleGhFailure(owner, repo, error, site, genericMessage) {
+        const errorMessage = String(error);
+        if (error instanceof JitTokenError) {
+            this._logger.warn({ owner, repo, code: error.code, message: error.message, site }, 'JIT GitHub token refresh failed — skipping webhook setup for repository');
+            return { owner, repo, action: 'failed', error: errorMessage };
+        }
+        if (this._isForbiddenError(errorMessage)) {
+            this._fireForbiddenTriple(owner, repo, errorMessage);
             return {
                 owner,
                 repo,
                 action: 'failed',
-                error: errorMessage,
+                error: 'webhook-registration-forbidden',
             };
         }
+        if (errorMessage.includes('403') || errorMessage.includes('404')) {
+            this._logger.warn({ owner, repo, error: errorMessage, site }, 'Insufficient permissions to manage webhooks (admin:repo_hook required)');
+        }
+        else if (errorMessage.includes('500')) {
+            this._logger.warn({ owner, repo, error: errorMessage, site }, 'GitHub API error while managing webhooks');
+        }
+        else {
+            this._logger.warn({ owner, repo, error: errorMessage, site }, genericMessage);
+        }
+        return { owner, repo, action: 'failed', error: errorMessage };
     }
     /**
-     * Find a webhook matching the given URL.
+     * Emit the fail-loud triple (warn log + relay event + degraded status) for
+     * a webhook-registration 403. Bounded to at most once per `(repo, boot)`
+     * per `contracts/webhook-registration-forbidden-event.md` §"Emission rate".
      *
-     * Uses case-insensitive URL comparison. No URL normalization is performed -
-     * simple string matching after lowercasing both URLs. This means that
-     * 'https://smee.io/ABC' and 'https://smee.io/abc' are considered equal,
-     * but trailing slashes or different protocols would not match.
-     *
-     * @param webhooks - Array of webhooks to search through
-     * @param targetUrl - The URL to match (typically the Smee channel URL)
-     * @returns The first matching webhook, or undefined if none found
-     *
-     * @example
-     * ```typescript
-     * const webhooks = [
-     *   { id: 1, active: true, config: { url: 'https://smee.io/ABC' }, events: ['issues'] }
-     * ];
-     * const match = this._findMatchingWebhook(webhooks, 'https://smee.io/abc');
-     * // Returns the webhook with id: 1
-     * ```
+     * The log line is synchronous and always succeeds — this is the audit
+     * floor. Relay event and status transition are fire-and-forget.
      */
-    _findMatchingWebhook(webhooks, targetUrl) {
-        const normalizedTargetUrl = targetUrl.toLowerCase();
-        return webhooks.find((webhook) => {
-            const webhookUrl = webhook.config?.url?.toLowerCase() ?? '';
-            return webhookUrl === normalizedTargetUrl;
+    _fireForbiddenTriple(owner, repo, ghStderr) {
+        const repoKey = `${owner}/${repo}`;
+        if (this._forbiddenFiredForRepo.has(repoKey)) {
+            // Already fired for this repo this boot — silence to bound cloud noise.
+            // The individual `gh` failure is still surfaced via the caller's return.
+            return;
+        }
+        this._forbiddenFiredForRepo.add(repoKey);
+        // Resolve installation id best-effort. `undefined` means "not resolved
+        // yet"; anything else (null or number) means "resolved" for this boot.
+        this._resolveInstallationId()
+            .then((installationId) => {
+            // 1. Structured warn log — synchronous, audit-floor guarantee.
+            this._logger.warn({
+                owner,
+                repo,
+                installationId,
+                missingScope: 'admin:repo_hook',
+                reason: 'webhook-registration-forbidden',
+                ghStderr,
+            }, 'Webhook registration forbidden: missing admin:repo_hook scope');
+            // 2. `cluster.bootstrap` relay event.
+            if (this._sendRelayEvent) {
+                try {
+                    this._sendRelayEvent('cluster.bootstrap', {
+                        status: 'failed',
+                        reason: 'webhook-registration-forbidden',
+                        repo: repoKey,
+                        installationId,
+                        missingScope: 'admin:repo_hook',
+                    });
+                }
+                catch {
+                    // fire-and-forget
+                }
+            }
+            // 3. Cluster status → degraded.
+            if (this._statusReporter) {
+                this._statusReporter
+                    .pushStatus('degraded', 'webhook-registration-forbidden')
+                    .catch(() => {
+                    // fire-and-forget
+                });
+            }
+        })
+            .catch(() => {
+            // Provider failure must not swallow the audit-floor log line — emit
+            // with null installationId so operators still see the 403 signal.
+            this._logger.warn({
+                owner,
+                repo,
+                installationId: null,
+                missingScope: 'admin:repo_hook',
+                reason: 'webhook-registration-forbidden',
+                ghStderr,
+            }, 'Webhook registration forbidden: missing admin:repo_hook scope');
+            if (this._sendRelayEvent) {
+                try {
+                    this._sendRelayEvent('cluster.bootstrap', {
+                        status: 'failed',
+                        reason: 'webhook-registration-forbidden',
+                        repo: repoKey,
+                        installationId: null,
+                        missingScope: 'admin:repo_hook',
+                    });
+                }
+                catch {
+                    // fire-and-forget
+                }
+            }
+            if (this._statusReporter) {
+                this._statusReporter
+                    .pushStatus('degraded', 'webhook-registration-forbidden')
+                    .catch(() => {
+                    // fire-and-forget
+                });
+            }
         });
     }
+    /**
+     * Resolve the github-app installation id, caching the result for the process
+     * lifetime. Returns `null` when no provider is configured or the provider
+     * cannot resolve an id (per data-model.md, `null` is a valid emit value).
+     */
+    async _resolveInstallationId() {
+        if (this._installationIdCache !== undefined)
+            return this._installationIdCache;
+        if (!this._installationIdProvider) {
+            this._installationIdCache = null;
+            return null;
+        }
+        try {
+            const resolved = await this._installationIdProvider();
+            this._installationIdCache = resolved ?? null;
+        }
+        catch {
+            this._installationIdCache = null;
+        }
+        return this._installationIdCache;
+    }
     /**
      * List webhooks for a repository via GitHub API.
      *
-     * Uses the `gh` CLI to call `GET /repos/{owner}/{repo}/hooks`.
-     * Errors are logged and an empty array is returned for graceful degradation.
-     *
-     * @param owner - Repository owner (organization or user)
-     * @param repo - Repository name
-     * @returns Promise resolving to an array of webhooks (empty array on error)
-     *
-     * @see {@link https://docs.github.com/en/rest/webhooks/repos#list-repository-webhooks}
+     * Errors are thrown so the per-repo catch branch can classify them as 403
+     * (fail-loud) vs 404/500 (warn-only). Returns an empty array when the API
+     * returns a well-formed non-array response.
      */
     async _listRepoWebhooks(owner, repo) {
+        const env = await this.resolveTokenEnv();
+        const result = await executeCommand('gh', [
+            'api',
+            `/repos/${owner}/${repo}/hooks`,
+        ], { env });
+        if (result.exitCode !== 0) {
+            // Surface stderr as the thrown error so the catch branch can classify
+            // the failure (403 → fail-loud; else → warn). Preserves the pre-#972
+            // warn log line for the 500/404/other cases via `_handleGhFailure`.
+            const errorMsg = result.stderr.trim() || 'Unknown error';
+            this._logger.warn({ owner, repo, stderr: result.stderr }, 'Failed to list webhooks for repository');
+            throw new Error(errorMsg);
+        }
+        // Parse JSON response
+        let parsed;
         try {
-            const env = await this.resolveTokenEnv();
-            const result = await executeCommand('gh', [
-                'api',
-                `/repos/${owner}/${repo}/hooks`,
-            ], { env });
-            if (result.exitCode !== 0) {
-                this._logger.warn({ owner, repo, stderr: result.stderr }, 'Failed to list webhooks for repository');
-                return [];
-            }
-            // Parse JSON response
-            const parsed = JSON.parse(result.stdout);
-            // Validate the response is an array
-            if (!Array.isArray(parsed)) {
-                this._logger.warn({ owner, repo, response: result.stdout }, 'Unexpected response format when listing webhooks (expected array)');
-                return [];
-            }
-            // Return as GitHubWebhook array (minimal validation - trust GitHub API)
-            return parsed;
+            parsed = JSON.parse(result.stdout);
         }
         catch (error) {
-            if (error instanceof JitTokenError) {
-                this._logger.warn({ owner, repo, code: error.code, message: error.message }, 'JIT GitHub token refresh failed — skipping webhook listing for repository');
-                return [];
-            }
-            // Handle parse errors and other exceptions gracefully
             this._logger.warn({ owner, repo, error: String(error) }, 'Error listing webhooks for repository');
             return [];
         }
+        if (!Array.isArray(parsed)) {
+            this._logger.warn({ owner, repo, response: result.stdout }, 'Unexpected response format when listing webhooks (expected array)');
+            return [];
+        }
+        return parsed;
     }
     /**
      * Create a new webhook for a repository via GitHub API.
      *
-     * Uses the `gh` CLI to call `POST /repos/{owner}/{repo}/hooks` with:
-     * - `config.url`: The Smee channel URL
-     * - `config.content_type`: 'json'
-     * - `events`: ['issues']
-     * - `active`: true
-     *
-     * @param owner - Repository owner (organization or user)
-     * @param repo - Repository name
-     * @param smeeChannelUrl - The Smee channel URL to configure
-     * @returns Promise resolving to the webhook ID on success
-     * @throws Error if webhook creation fails (caught and logged by caller)
+     * FR-001: locks the create-time event list to `issues`, `pull_request`,
+     * `check_run`, `check_suite`. `content_type` is `json`; `active` is `true`.
      *
      * @see {@link https://docs.github.com/en/rest/webhooks/repos#create-a-repository-webhook}
      */
     async _createRepoWebhook(owner, repo, smeeChannelUrl) {
         const env = await this.resolveTokenEnv();
-        const result = await executeCommand('gh', [
+        const args = [
             'api',
             '-X', 'POST',
             `/repos/${owner}/${repo}/hooks`,
             '-f', `config[url]=${smeeChannelUrl}`,
             '-f', 'config[content_type]=json',
-            '-F', 'events[]=issues',
             '-F', 'active=true',
-        ], { env });
+        ];
+        for (const event of LOCKED_EVENTS) {
+            args.push('-F', `events[]=${event}`);
+        }
+        const result = await executeCommand('gh', args, { env });
         if (result.exitCode !== 0) {
-            // Extract error message from stderr for better debugging
             const errorMsg = result.stderr.trim() || 'Unknown error';
             throw new Error(`Failed to create webhook: ${errorMsg}`);
         }
-        // Parse response to get webhook ID
         const response = JSON.parse(result.stdout);
         return response.id;
     }
     /**
      * Update an existing webhook (reactivate and/or merge events) via GitHub API.
      *
-     * Uses the `gh` CLI to call `PATCH /repos/{owner}/{repo}/hooks/{webhookId}`.
-     * When reactivating an inactive webhook, this method also merges the 'issues'
-     * event with any existing events to preserve the webhook's original configuration.
-     *
-     * @param owner - Repository owner (organization or user)
-     * @param repo - Repository name
-     * @param webhookId - Webhook ID to update
-     * @param updates - Updates to apply
-     * @param updates.active - Set webhook active status (true to reactivate)
-     * @param updates.events - Event types to subscribe to (merged with existing)
-     * @returns Promise resolving to true on success
-     * @throws Error if webhook update fails (caught and logged by caller)
+     * Used for the `reactivate` decision-matrix row (inactive hook matching
+     * current URL). Preserves pre-#972 argv ordering so the existing test
+     * assertions (`build correct PATCH request with active flag and merged events`)
+     * continue to pass.
      *
      * @see {@link https://docs.github.com/en/rest/webhooks/repos#update-a-repository-webhook}
      */
     async _updateRepoWebhook(owner, repo, webhookId, updates) {
-        // Build gh api command arguments
         const args = [
             'api',
             '-X', 'PATCH',
             `/repos/${owner}/${repo}/hooks/${webhookId}`,
         ];
-        // Add active flag if specified
         if (updates.active !== undefined) {
             args.push('-F', `active=${updates.active}`);
         }
-        // Add events if specified (merge with existing)
         if (updates.events && updates.events.length > 0) {
-            // GitHub expects events as an array, so we need to add each event
             updates.events.forEach((event) => {
                 args.push('-F', `events[]=${event}`);
             });
@@ -387,7 +532,30 @@ export class WebhookSetupService {
         const env = await this.resolveTokenEnv();
         const result = await executeCommand('gh', args, { env });
         if (result.exitCode !== 0) {
-            // Extract error message from stderr for better debugging
+            const errorMsg = result.stderr.trim() || 'Unknown error';
+            throw new Error(`Failed to update webhook: ${errorMsg}`);
+        }
+        return true;
+    }
+    /**
+     * Update an existing webhook's `config.url` to the current channel (FR-004
+     * stale-channel heal). Also enforces the locked events set and active flag.
+     */
+    async _updateRepoWebhookConfig(owner, repo, webhookId, updates) {
+        const args = [
+            'api',
+            '-X', 'PATCH',
+            `/repos/${owner}/${repo}/hooks/${webhookId}`,
+            '-f', `config[url]=${updates.url}`,
+            '-f', 'config[content_type]=json',
+            '-F', `active=${updates.active}`,
+        ];
+        for (const event of updates.events) {
+            args.push('-F', `events[]=${event}`);
+        }
+        const env = await this.resolveTokenEnv();
+        const result = await executeCommand('gh', args, { env });
+        if (result.exitCode !== 0) {
             const errorMsg = result.stderr.trim() || 'Unknown error';
             throw new Error(`Failed to update webhook: ${errorMsg}`);
         }