@generacy-ai/orchestrator 0.8.0 → 0.10.0

package/dist/services/adaptive-poll-controller.js

@@ -0,0 +1,96 @@
+/**
+ * #953 — Shared adaptive-polling decision function used by
+ * `LabelMonitorService`, `PrFeedbackMonitorService`, and
+ * `MergeConflictMonitorService`. Extracted to eliminate the three-way
+ * copy-paste that produced the "smee-less cluster stuck at base cadence" bug.
+ *
+ * Pure: no I/O, no `this`, no `Date.now()`. Time flows in via `params.nowMs`.
+ */
+/**
+ * Fast interval calculation shared between `decideAdaptivePoll` and callers
+ * that need the value at construction time.
+ */
+export function computeFastInterval(basePollIntervalMs, adaptiveDivisor, minPollIntervalMs) {
+    return Math.max(minPollIntervalMs, Math.floor(basePollIntervalMs / adaptiveDivisor));
+}
+/**
+ * Decide the next poll cadence given current state and tuning.
+ *
+ * Branch summary:
+ * - webhooksConfigured=false, adaptivePolling=true:
+ *     cycle 1  → { fast, healthy=false, to-fast, webhooks-not-configured }
+ *     cycle 2+ → { fast, healthy=false, none,    webhooks-not-configured }
+ * - webhooksConfigured=false, adaptivePolling=false:
+ *     always   → { base, healthy=true,  none,    operator-opt-out }
+ * - webhooksConfigured=true, lastWebhookEvent===null:
+ *     always   → { unchanged, unchanged, none,   quiet }
+ * - webhooksConfigured=true, lastWebhookEvent!==null:
+ *     staleness = nowMs - lastWebhookEvent; threshold = basePoll * 2
+ *     if (staleness > threshold && webhookHealthy) → to-fast, webhook-stale
+ *     else → { unchanged, unchanged, none, quiet }
+ *
+ * The `recordWebhookEvent` handler in each service also delegates here for
+ * the recovery path — it flips `webhookHealthy=true` and `lastWebhookEvent`
+ * before calling; the helper returns `to-base, webhook-recovered` when the
+ * caller was previously at the fast interval.
+ */
+export function decideAdaptivePoll(params) {
+    const { webhooksConfigured, adaptivePolling, basePollIntervalMs, currentPollIntervalMs, lastWebhookEvent, webhookHealthy, adaptiveDivisor, minPollIntervalMs, nowMs, } = params;
+    const fastIntervalMs = computeFastInterval(basePollIntervalMs, adaptiveDivisor, minPollIntervalMs);
+    if (!webhooksConfigured) {
+        if (!adaptivePolling) {
+            return {
+                currentPollIntervalMs: basePollIntervalMs,
+                webhookHealthy: true,
+                transition: 'none',
+                reason: 'operator-opt-out',
+            };
+        }
+        // adaptivePolling === true, webhooksConfigured === false:
+        // fast interval, unhealthy. Emit `to-fast` on the transition edge only.
+        const transition = webhookHealthy ? 'to-fast' : 'none';
+        return {
+            currentPollIntervalMs: fastIntervalMs,
+            webhookHealthy: false,
+            transition,
+            reason: 'webhooks-not-configured',
+        };
+    }
+    // webhooksConfigured === true from here on.
+    if (lastWebhookEvent === null) {
+        // Grace: never received an event, don't ratchet down cadence.
+        return {
+            currentPollIntervalMs,
+            webhookHealthy,
+            transition: 'none',
+            reason: 'quiet',
+        };
+    }
+    const staleness = nowMs - lastWebhookEvent;
+    const staleThreshold = basePollIntervalMs * 2;
+    // Recovery path: caller set webhookHealthy=true before delegating.
+    // If we're on the fast interval, transition back to base.
+    if (webhookHealthy && currentPollIntervalMs !== basePollIntervalMs) {
+        return {
+            currentPollIntervalMs: basePollIntervalMs,
+            webhookHealthy: true,
+            transition: 'to-base',
+            reason: 'webhook-recovered',
+        };
+    }
+    if (staleness > staleThreshold && webhookHealthy) {
+        return {
+            currentPollIntervalMs: fastIntervalMs,
+            webhookHealthy: false,
+            transition: 'to-fast',
+            reason: 'webhook-stale',
+        };
+    }
+    return {
+        currentPollIntervalMs,
+        webhookHealthy,
+        transition: 'none',
+        reason: 'quiet',
+    };
+}
+//# sourceMappingURL=adaptive-poll-controller.js.map

package/dist/services/adaptive-poll-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive-poll-controller.js","sourceRoot":"","sources":["../../src/services/adaptive-poll-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiDH;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,kBAA0B,EAC1B,eAAuB,EACvB,iBAAyB;IAEzB,OAAO,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,CAAC,KAAK,CAAC,kBAAkB,GAAG,eAAe,CAAC,CAAC,CAAC;AACvF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA0B;IAC3D,MAAM,EACJ,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,KAAK,GACN,GAAG,MAAM,CAAC;IAEX,MAAM,cAAc,GAAG,mBAAmB,CAAC,kBAAkB,EAAE,eAAe,EAAE,iBAAiB,CAAC,CAAC;IAEnG,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACxB,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,OAAO;gBACL,qBAAqB,EAAE,kBAAkB;gBACzC,cAAc,EAAE,IAAI;gBACpB,UAAU,EAAE,MAAM;gBAClB,MAAM,EAAE,kBAAkB;aAC3B,CAAC;QACJ,CAAC;QACD,0DAA0D;QAC1D,wEAAwE;QACxE,MAAM,UAAU,GAAG,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;QACvD,OAAO;YACL,qBAAqB,EAAE,cAAc;YACrC,cAAc,EAAE,KAAK;YACrB,UAAU;YACV,MAAM,EAAE,yBAAyB;SAClC,CAAC;IACJ,CAAC;IAED,4CAA4C;IAE5C,IAAI,gBAAgB,KAAK,IAAI,EAAE,CAAC;QAC9B,8DAA8D;QAC9D,OAAO;YACL,qBAAqB;YACrB,cAAc;YACd,UAAU,EAAE,MAAM;YAClB,MAAM,EAAE,OAAO;SAChB,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,GAAG,gBAAgB,CAAC;IAC3C,MAAM,cAAc,GAAG,kBAAkB,GAAG,CAAC,CAAC;IAE9C,mEAAmE;IACnE,0DAA0D;IAC1D,IAAI,cAAc,IAAI,qBAAqB,KAAK,kBAAkB,EAAE,CAAC;QACnE,OAAO;YACL,qBAAqB,EAAE,kBAAkB;YACzC,cAAc,EAAE,IAAI;YACpB,UAAU,EAAE,SAAS;YACrB,MAAM,EAAE,mBAAmB;SAC5B,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,GAAG,cAAc,IAAI,cAAc,EAAE,CAAC;QACjD,OAAO;YACL,qBAAqB,EAAE,cAAc;YACrC,cAAc,EAAE,KAAK;YACrB,UAAU,EAAE,SAAS;YACrB,MAAM,EAAE,eAAe;SACxB,CAAC;IACJ,CAAC;IAED,OAAO;QACL,qBAAqB;QACrB,cAAc;QACd,UAAU,EAAE,MAAM;QAClB,MAAM,EAAE,OAAO;KAChB,CAAC;AACJ,CAAC"}

package/dist/services/clarification-answer-monitor-service.d.ts

@@ -0,0 +1,93 @@
+/**
+ * #958 T013 — Poll-based monitor that enqueues `continue` resume queue items
+ * for issues sitting at `waiting-for:clarification` + `agent:paused` when a
+ * new human-authored comment appears.
+ *
+ * Shape template: `merge-conflict-monitor-service.ts` (spec §Assumptions).
+ * Contract: `specs/958-found-during-local-snappoll/contracts/
+ *   clarification-answer-monitor.md`.
+ *
+ * Key divergences from the merge-conflict monitor (per data-model.md):
+ *   - Precondition label: `waiting-for:clarification` (was `waiting-for:merge-conflicts`).
+ *   - Additional predicate: at least one comment with `viewerDidAuthor === false`
+ *     that also passes `isTrustedCommentAuthor(_, 'answer-scanner', trustCtx)`.
+ *     Comments carrying the engine-written answer marker are treated as
+ *     cluster-self (not counted).
+ *   - Queue command: `command: 'continue'` (was `'resolve-merge-conflicts'`).
+ *
+ * Non-behavior (contract):
+ *   - MUST NOT apply `completed:clarification`. That label is reserved for
+ *     the human's explicit force-advance override (FR-011).
+ *   - MUST NOT modify `clarifications.md` — the monitor has no checkout; the
+ *     phase loop performs integration on the resume path.
+ *   - MUST NOT clear `waiting-for:clarification` or `agent:paused`.
+ */
+import { type GitHubClientFactory } from '@generacy-ai/workflow-engine';
+import type { MonitorState, QueueManager } from '../types/monitor.js';
+import type { RepositoryConfig, PrMonitorConfig } from '../config/schema.js';
+import type { Logger } from '../worker/types.js';
+import type { AuthHealthSink } from './label-monitor-service.js';
+export interface ClarificationAnswerEvent {
+    owner: string;
+    repo: string;
+    issueNumber: number;
+    issueLabels: string[];
+    source: 'poll';
+}
+export interface ClarificationAnswerMonitorOptions {
+    repositories: RepositoryConfig[];
+    pollIntervalMs: number;
+    adaptivePolling: boolean;
+    maxConcurrentPolls: number;
+}
+/**
+ * #987: options for the runtime `setWebhooksConfigured(true, opts?)` flip.
+ * See specs/987-summary-cluster-where-smee/contracts/setter-contract.md.
+ */
+export interface SetWebhooksConfiguredOptions {
+    basePollIntervalMs?: number;
+}
+export declare class ClarificationAnswerMonitorService {
+    private readonly logger;
+    private readonly createClient;
+    private readonly tokenProvider?;
+    private readonly queueManager;
+    private readonly options;
+    private readonly clusterGithubUsername;
+    private readonly authHealth;
+    private readonly githubAppCredentialId;
+    private abortController;
+    private state;
+    constructor(logger: Logger, createClient: GitHubClientFactory, queueManager: QueueManager, config: PrMonitorConfig, repositories: RepositoryConfig[], clusterGithubUsername?: string, tokenProvider?: () => Promise<string | undefined>, authHealth?: AuthHealthSink, githubAppCredentialId?: string, webhooksConfigured?: boolean);
+    /**
+     * Process a clarification-answer event: verify preconditions, check for a
+     * new human-authored comment, enqueue a resume via `enqueueIfAbsent`.
+     *
+     * Returns true if enqueued, false if skipped or duplicate.
+     */
+    processClarificationAnswerEvent(event: ClarificationAnswerEvent): Promise<boolean>;
+    /**
+     * #993 — positive answer predicate. Returns the first comment that qualifies
+     * as a real clarification answer, or `undefined` if none exists on the issue.
+     *
+     * Short-circuits when the issue carries no question-marker comment (data-
+     * integrity signal — the clarify phase always posts one before applying
+     * `waiting-for:clarification`).
+     */
+    private findAnswerCandidate;
+    startPolling(): Promise<void>;
+    stopPolling(): void;
+    poll(): Promise<void>;
+    private pollRepo;
+    recordWebhookEvent(): void;
+    private updateAdaptivePolling;
+    getState(): Readonly<MonitorState>;
+    /**
+     * #987: flip `webhooksConfigured` to `true` at runtime. Setter is one-way
+     * (Q1); `adaptivePolling` stays untouched so the staleness safety net is
+     * reachable (Q2). See specs/987-summary-cluster-where-smee/clarifications.md.
+     */
+    setWebhooksConfigured(configured: true, opts?: SetWebhooksConfiguredOptions): void;
+    private sleep;
+}
+//# sourceMappingURL=clarification-answer-monitor-service.d.ts.map

package/dist/services/clarification-answer-monitor-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clarification-answer-monitor-service.d.ts","sourceRoot":"","sources":["../../src/services/clarification-answer-monitor-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAEb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAcjE,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iCAAiC;IAChD,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,4BAA4B;IAC3C,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AA4BD,qBAAa,iCAAiC;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAoC;IACnE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAqB;IAC3D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAqB;IAC3D,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,KAAK,CAAe;gBAG1B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,mBAAmB,EACjC,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,eAAe,EACvB,YAAY,EAAE,gBAAgB,EAAE,EAChC,qBAAqB,CAAC,EAAE,MAAM,EAC9B,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,EACjD,UAAU,CAAC,EAAE,cAAc,EAC3B,qBAAqB,CAAC,EAAE,MAAM,EAC9B,kBAAkB,GAAE,OAAe;IA6BrC;;;;;OAKG;IACG,+BAA+B,CACnC,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,OAAO,CAAC;IA+FnB;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAyCrB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAmCnC,WAAW,IAAI,IAAI;IAQb,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAkBb,QAAQ;IAoFtB,kBAAkB,IAAI,IAAI;IAwB1B,OAAO,CAAC,qBAAqB;IA0B7B,QAAQ,IAAI,QAAQ,CAAC,YAAY,CAAC;IAIlC;;;;OAIG;IACH,qBAAqB,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,4BAA4B,GAAG,IAAI;IAalF,OAAO,CAAC,KAAK;CAcd"}

package/dist/services/clarification-answer-monitor-service.js

@@ -0,0 +1,452 @@
+/**
+ * #958 T013 — Poll-based monitor that enqueues `continue` resume queue items
+ * for issues sitting at `waiting-for:clarification` + `agent:paused` when a
+ * new human-authored comment appears.
+ *
+ * Shape template: `merge-conflict-monitor-service.ts` (spec §Assumptions).
+ * Contract: `specs/958-found-during-local-snappoll/contracts/
+ *   clarification-answer-monitor.md`.
+ *
+ * Key divergences from the merge-conflict monitor (per data-model.md):
+ *   - Precondition label: `waiting-for:clarification` (was `waiting-for:merge-conflicts`).
+ *   - Additional predicate: at least one comment with `viewerDidAuthor === false`
+ *     that also passes `isTrustedCommentAuthor(_, 'answer-scanner', trustCtx)`.
+ *     Comments carrying the engine-written answer marker are treated as
+ *     cluster-self (not counted).
+ *   - Queue command: `command: 'continue'` (was `'resolve-merge-conflicts'`).
+ *
+ * Non-behavior (contract):
+ *   - MUST NOT apply `completed:clarification`. That label is reserved for
+ *     the human's explicit force-advance override (FR-011).
+ *   - MUST NOT modify `clarifications.md` — the monitor has no checkout; the
+ *     phase loop performs integration on the resume path.
+ *   - MUST NOT clear `waiting-for:clarification` or `agent:paused`.
+ */
+import { GhAuthError, isTrustedCommentAuthor, tryLoadCommentTrustConfig, } from '@generacy-ai/workflow-engine';
+import { JitTokenError } from '@generacy-ai/control-plane';
+import { filterByAssignee } from './identity.js';
+import { commentCarriesAnswerMarker, commentCarriesMachineMarker, matchClarificationQuestionMarker, } from '../worker/clarification-markers.js';
+import { decideAdaptivePoll } from './adaptive-poll-controller.js';
+const WAITING_FOR_CLARIFICATION_LABEL = 'waiting-for:clarification';
+const AGENT_PAUSED_LABEL = 'agent:paused';
+const MIN_POLL_INTERVAL_MS = 10_000;
+const ADAPTIVE_DIVISOR = 2;
+/**
+ * Adapter: pino-style logger (WorkerContext.Logger) → workflow-engine Logger.
+ * Same bridge used by `clarification-poster.ts` — kept private to this file
+ * so the merge-conflict monitor's DI surface stays untouched.
+ */
+function toEngineLogger(logger) {
+    return {
+        info: (msg, meta) => {
+            if (meta && typeof meta === 'object')
+                logger.info(meta, msg);
+            else
+                logger.info(msg);
+        },
+        warn: (msg, meta) => {
+            if (meta && typeof meta === 'object')
+                logger.warn(meta, msg);
+            else
+                logger.warn(msg);
+        },
+        error: (msg, meta) => {
+            if (meta && typeof meta === 'object')
+                logger.error(meta, msg);
+            else
+                logger.error(msg);
+        },
+        debug: (msg, meta) => {
+            if (meta && typeof meta === 'object')
+                logger.debug(meta, msg);
+            else
+                logger.debug(msg);
+        },
+    };
+}
+export class ClarificationAnswerMonitorService {
+    logger;
+    createClient;
+    tokenProvider;
+    queueManager;
+    options;
+    clusterGithubUsername;
+    authHealth;
+    githubAppCredentialId;
+    abortController = null;
+    state;
+    constructor(logger, createClient, queueManager, config, repositories, clusterGithubUsername, tokenProvider, authHealth, githubAppCredentialId, webhooksConfigured = false) {
+        this.logger = logger;
+        this.createClient = createClient;
+        this.tokenProvider = tokenProvider;
+        this.queueManager = queueManager;
+        this.clusterGithubUsername = clusterGithubUsername;
+        this.authHealth = authHealth ?? { recordResult: () => undefined };
+        this.githubAppCredentialId = githubAppCredentialId;
+        this.options = {
+            repositories,
+            pollIntervalMs: config.pollIntervalMs,
+            adaptivePolling: config.adaptivePolling,
+            maxConcurrentPolls: config.maxConcurrentPolls,
+        };
+        this.state = {
+            isPolling: false,
+            webhookHealthy: true,
+            lastWebhookEvent: null,
+            currentPollIntervalMs: config.pollIntervalMs,
+            basePollIntervalMs: config.pollIntervalMs,
+            webhooksConfigured,
+        };
+    }
+    // ==========================================================================
+    // Event Processing
+    // ==========================================================================
+    /**
+     * Process a clarification-answer event: verify preconditions, check for a
+     * new human-authored comment, enqueue a resume via `enqueueIfAbsent`.
+     *
+     * Returns true if enqueued, false if skipped or duplicate.
+     */
+    async processClarificationAnswerEvent(event) {
+        const { owner, repo, issueNumber, issueLabels, source } = event;
+        const hasWaitingFor = issueLabels.includes(WAITING_FOR_CLARIFICATION_LABEL);
+        const hasPaused = issueLabels.includes(AGENT_PAUSED_LABEL);
+        if (!hasWaitingFor || !hasPaused) {
+            this.logger.debug({ owner, repo, issueNumber, source, hasWaitingFor, hasPaused }, 'Precondition failed for clarification-answer enqueue (need waiting-for:clarification + agent:paused)');
+            return false;
+        }
+        const blockedLabel = issueLabels.find((l) => l.startsWith('blocked:'));
+        if (blockedLabel) {
+            this.logger.info({ owner, repo, issueNumber, blockedLabel, reason: 'blocked-label-present' }, 'Skipping clarification-answer enqueue while blocked:* label is present');
+            return false;
+        }
+        // Fetch comments and require ≥1 human-authored (viewerDidAuthor === false)
+        // trusted comment. `viewerDidAuthor === true` comments (cluster-self) do
+        // not count as "new human answer" — even if they carry the answer marker,
+        // the phase loop is the source of truth for integrating cluster-relayed
+        // answers, not the monitor.
+        const client = this.createClient(undefined, this.tokenProvider);
+        let comments;
+        try {
+            comments = await client.getIssueCommentsWithViewerAuth(owner, repo, issueNumber);
+        }
+        catch (err) {
+            this.logger.warn({ err: String(err), owner, repo, issueNumber }, 'Failed to fetch comments during clarification-answer event — skipping');
+            return false;
+        }
+        const trustConfig = tryLoadCommentTrustConfig(process.cwd(), toEngineLogger(this.logger));
+        const trustCtx = {
+            logger: toEngineLogger(this.logger),
+            ...(this.clusterGithubUsername ? { botLogin: this.clusterGithubUsername } : {}),
+            ...(trustConfig ? { config: trustConfig } : {}),
+        };
+        const candidate = this.findAnswerCandidate(comments, trustCtx);
+        if (!candidate) {
+            this.logger.debug({ owner, repo, issueNumber }, 'No answer candidate found — nothing to resume on (no question-marker comment, or no comment newer than the latest question by a non-bot trusted author)');
+            return false;
+        }
+        const workflowLabel = issueLabels.find((l) => l.startsWith('workflow:'));
+        const workflowName = workflowLabel
+            ? workflowLabel.slice('workflow:'.length)
+            : 'speckit-feature';
+        const queueItem = {
+            owner,
+            repo,
+            issueNumber,
+            workflowName,
+            command: 'continue',
+            priority: Date.now(),
+            enqueuedAt: new Date().toISOString(),
+            metadata: {},
+            queueReason: 'resume',
+        };
+        const itemKey = `${owner}/${repo}#${issueNumber}`;
+        const enqueued = await this.queueManager.enqueueIfAbsent(queueItem);
+        if (!enqueued) {
+            this.logger.info({ itemKey, reason: 'in-flight', owner, repo, issueNumber }, 'Dropping clarification-answer enqueue (item already in flight)');
+            return false;
+        }
+        this.logger.info({
+            event: 'clarification-answer-resume-enqueued',
+            owner,
+            repo,
+            issueNumber,
+            source,
+        }, 'Clarification-answer resume enqueued');
+        return true;
+    }
+    /**
+     * #993 — positive answer predicate. Returns the first comment that qualifies
+     * as a real clarification answer, or `undefined` if none exists on the issue.
+     *
+     * Short-circuits when the issue carries no question-marker comment (data-
+     * integrity signal — the clarify phase always posts one before applying
+     * `waiting-for:clarification`).
+     */
+    findAnswerCandidate(comments, trustCtx) {
+        // `created_at`-only newness is intentional (replay-safe); blocks the
+        // `<!-- generacy-stage:specification -->` summary re-trigger vector where
+        // the bot updates its own summary and advances `updated_at` every poll.
+        const questionAnchor = latestQuestionCommentCreatedAt(comments);
+        if (questionAnchor === undefined)
+            return undefined;
+        for (const c of comments) {
+            // `[bot]`-suffix authors are dropped upstream of the trust helper.
+            // Cluster-relayed answers flow through the `completed:clarification`
+            // label / LabelMonitorService path, never through this monitor.
+            if (isBotAuthoredLogin(c.author))
+                continue;
+            if (c.created_at <= questionAnchor)
+                continue;
+            // Branch (a) runs before the machine-marker skip: `commentCarriesAnswerMarker`
+            // is a positive signal, and the answer-marker prefix is present in
+            // MACHINE_MARKERS as a #976 engine-noise entry. Without this order, a
+            // non-bot human posting `<!-- generacy-clarification-answers:1 -->` would
+            // be filtered out as machine noise (SC-003 regression).
+            if (commentCarriesAnswerMarker(c.body))
+                return c;
+            if (commentCarriesMachineMarker(c.body))
+                continue;
+            const decision = isTrustedCommentAuthor(c, 'answer-scanner', trustCtx);
+            if (decision.trusted &&
+                decision.reason !== 'bot' &&
+                decision.reason !== 'self-authored') {
+                return c;
+            }
+        }
+        return undefined;
+    }
+    // ==========================================================================
+    // Polling
+    // ==========================================================================
+    async startPolling() {
+        if (this.state.isPolling) {
+            this.logger.warn('Clarification-answer monitor polling already running');
+            return;
+        }
+        const ac = new AbortController();
+        this.abortController = ac;
+        this.state.isPolling = true;
+        this.logger.info({ intervalMs: this.state.currentPollIntervalMs, repos: this.options.repositories.length }, 'Starting clarification-answer monitor polling');
+        while (!ac.signal.aborted) {
+            try {
+                await this.poll();
+            }
+            catch (error) {
+                this.logger.error({ err: error }, 'Error during clarification-answer poll cycle');
+            }
+            if (this.options.adaptivePolling) {
+                this.updateAdaptivePolling();
+            }
+            await this.sleep(this.state.currentPollIntervalMs, ac.signal);
+        }
+        this.state.isPolling = false;
+        this.logger.info('Clarification-answer monitor polling loop stopped');
+    }
+    stopPolling() {
+        if (this.abortController) {
+            this.abortController.abort();
+            this.abortController = null;
+            this.logger.info('Clarification-answer monitor polling stop requested');
+        }
+    }
+    async poll() {
+        const repos = this.options.repositories;
+        if (repos.length === 0)
+            return;
+        const semaphore = new Semaphore(this.options.maxConcurrentPolls);
+        const pollTasks = repos.map(({ owner, repo }) => semaphore.acquire().then(async (release) => {
+            try {
+                await this.pollRepo(owner, repo);
+            }
+            finally {
+                release();
+            }
+        }));
+        await Promise.allSettled(pollTasks);
+    }
+    async pollRepo(owner, repo) {
+        const client = this.createClient(undefined, this.tokenProvider);
+        let allIssues;
+        try {
+            allIssues = await client.listIssuesWithLabel(owner, repo, WAITING_FOR_CLARIFICATION_LABEL);
+            if (this.githubAppCredentialId) {
+                this.authHealth.recordResult(this.githubAppCredentialId, { ok: true });
+            }
+        }
+        catch (error) {
+            if (error instanceof JitTokenError) {
+                this.logger.warn({ code: error.code, message: error.message, owner, repo }, 'JIT GitHub token refresh failed — skipping clarification-answer monitor cycle');
+                return;
+            }
+            if (error instanceof GhAuthError) {
+                if (this.githubAppCredentialId) {
+                    this.authHealth.recordResult(this.githubAppCredentialId, { ok: false, statusCode: error.statusCode });
+                }
+                this.logger.warn({
+                    credentialId: this.githubAppCredentialId,
+                    statusCode: error.statusCode,
+                    owner,
+                    repo,
+                }, 'GitHub authentication failing on clarification-answer monitor — investigate credential refresh chain');
+                return;
+            }
+            this.logger.warn({ err: String(error), owner, repo }, 'Error polling repository for clarification-answer pauses');
+            return;
+        }
+        const issues = filterByAssignee(allIssues, this.clusterGithubUsername, this.logger);
+        if (issues.length === 0) {
+            this.logger.debug({ owner, repo }, 'No clarification-answer pauses found this cycle');
+            return;
+        }
+        this.logger.info({ owner, repo, count: issues.length }, 'Clarification-answer pauses found');
+        for (const issue of issues) {
+            const event = {
+                owner,
+                repo,
+                issueNumber: issue.number,
+                issueLabels: issue.labels.map((l) => l.name),
+                source: 'poll',
+            };
+            try {
+                await this.processClarificationAnswerEvent(event);
+            }
+            catch (err) {
+                this.logger.warn({ err: String(err), owner, repo, issueNumber: issue.number }, 'Error processing clarification-answer event — continuing to next issue');
+            }
+        }
+    }
+    // ==========================================================================
+    // Adaptive Polling
+    // ==========================================================================
+    recordWebhookEvent() {
+        this.state.lastWebhookEvent = Date.now();
+        this.state.webhookHealthy = true;
+        const decision = decideAdaptivePoll({
+            webhooksConfigured: this.state.webhooksConfigured,
+            adaptivePolling: this.options.adaptivePolling,
+            basePollIntervalMs: this.state.basePollIntervalMs,
+            currentPollIntervalMs: this.state.currentPollIntervalMs,
+            lastWebhookEvent: this.state.lastWebhookEvent,
+            webhookHealthy: this.state.webhookHealthy,
+            adaptiveDivisor: ADAPTIVE_DIVISOR,
+            minPollIntervalMs: MIN_POLL_INTERVAL_MS,
+            nowMs: Date.now(),
+        });
+        this.state.currentPollIntervalMs = decision.currentPollIntervalMs;
+        this.state.webhookHealthy = decision.webhookHealthy;
+        if (decision.transition !== 'none') {
+            this.logger.info({ intervalMs: this.state.currentPollIntervalMs, reason: decision.reason }, 'Webhook reconnected, restoring clarification-answer monitor poll interval');
+        }
+    }
+    updateAdaptivePolling() {
+        const decision = decideAdaptivePoll({
+            webhooksConfigured: this.state.webhooksConfigured,
+            adaptivePolling: this.options.adaptivePolling,
+            basePollIntervalMs: this.state.basePollIntervalMs,
+            currentPollIntervalMs: this.state.currentPollIntervalMs,
+            lastWebhookEvent: this.state.lastWebhookEvent,
+            webhookHealthy: this.state.webhookHealthy,
+            adaptiveDivisor: ADAPTIVE_DIVISOR,
+            minPollIntervalMs: MIN_POLL_INTERVAL_MS,
+            nowMs: Date.now(),
+        });
+        this.state.currentPollIntervalMs = decision.currentPollIntervalMs;
+        this.state.webhookHealthy = decision.webhookHealthy;
+        if (decision.transition !== 'none') {
+            this.logger.info({ intervalMs: this.state.currentPollIntervalMs, reason: decision.reason }, 'Webhooks appear unhealthy, increasing clarification-answer poll frequency');
+        }
+    }
+    // ==========================================================================
+    // State access
+    // ==========================================================================
+    getState() {
+        return { ...this.state };
+    }
+    /**
+     * #987: flip `webhooksConfigured` to `true` at runtime. Setter is one-way
+     * (Q1); `adaptivePolling` stays untouched so the staleness safety net is
+     * reachable (Q2). See specs/987-summary-cluster-where-smee/clarifications.md.
+     */
+    setWebhooksConfigured(configured, opts) {
+        void configured;
+        this.state.webhooksConfigured = true;
+        if (opts?.basePollIntervalMs !== undefined) {
+            this.state.basePollIntervalMs = opts.basePollIntervalMs;
+            this.state.currentPollIntervalMs = opts.basePollIntervalMs;
+        }
+    }
+    // ==========================================================================
+    // Utilities
+    // ==========================================================================
+    sleep(ms, signal) {
+        return new Promise((resolve) => {
+            if (signal.aborted) {
+                resolve();
+                return;
+            }
+            const timer = setTimeout(resolve, ms);
+            const onAbort = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+}
+/**
+ * #993 FR-001 — case-insensitive, whitespace-tolerant `[bot]`-suffix test.
+ * Mirrors `normalizeLogin`'s trim+lowercase shape without stripping the
+ * suffix (we're detecting it, not removing it). Any App bot identity
+ * (`generacy-ai[bot]`, `staging-generacy[bot]`, `dependabot[bot]`, …)
+ * is treated identically.
+ */
+function isBotAuthoredLogin(author) {
+    return author.trim().toLowerCase().endsWith('[bot]');
+}
+/**
+ * #993 FR-004 — newness anchor. Returns the newest `created_at` (ISO-8601
+ * lexicographic compare) among comments carrying a question marker.
+ * `undefined` when the issue has no question-marker comment.
+ */
+function latestQuestionCommentCreatedAt(comments) {
+    let latest;
+    for (const c of comments) {
+        if (matchClarificationQuestionMarker(c.body) === undefined)
+            continue;
+        if (latest === undefined || c.created_at > latest)
+            latest = c.created_at;
+    }
+    return latest;
+}
+/**
+ * Simple semaphore for bounded concurrency. Copy of the merge-conflict
+ * monitor's helper — deliberately duplicated to keep the two monitors
+ * shape-parallel and diffable.
+ */
+class Semaphore {
+    count;
+    waiting = [];
+    constructor(max) {
+        this.count = max;
+    }
+    async acquire() {
+        if (this.count > 0) {
+            this.count--;
+            return () => this.release();
+        }
+        return new Promise((resolve) => {
+            this.waiting.push(() => {
+                this.count--;
+                resolve(() => this.release());
+            });
+        });
+    }
+    release() {
+        this.count++;
+        const next = this.waiting.shift();
+        if (next)
+            next();
+    }
+}
+//# sourceMappingURL=clarification-answer-monitor-service.js.map