factory-factory 0.3.21 → 0.4.1

package/dist/src/backend/services/ratchet/service/ratchet.service.js

@@ -1,19 +1,29 @@
 import { EventEmitter } from 'node:events';
+import pLimit from 'p-limit';
 import { toError } from '../../../../backend/lib/error-utils.js';
-import { SERVICE_INTERVAL_MS, SERVICE_TIMEOUT_MS } from '../../../../backend/services/constants.js';
+import { SERVICE_INTERVAL_MS, SERVICE_THRESHOLDS, SERVICE_TIMEOUT_MS, } from '../../../../backend/services/constants.js';
 import { createLogger } from '../../../../backend/services/logger.service.js';
 import { RateLimitBackoff } from '../../../../backend/services/rate-limit-backoff.js';
-import { workspaceAccessor } from '../../../../backend/services/workspace/index.js';
-import { CIStatus, RatchetState } from '../../../../shared/core/index.js';
-import { getActiveRatchetSession as getActiveRatchetSessionHelper, hasActiveSession as hasActiveSessionHelper, } from './ratchet-active-session.helpers.js';
-import { buildRatchetingLogContext as buildRatchetingLogContextHelper, logWorkspaceRatchetingDecision as logWorkspaceRatchetingDecisionHelper, } from './ratchet-decision-logging.helpers.js';
+import { userSettingsService } from '../../../../backend/services/settings/index.js';
+import { workspaceDataService, workspaceRatchetService } from '../../../../backend/services/workspace/index.js';
+import { CIStatus, RatchetState, SessionStatus } from '../../../../shared/core/index.js';
+import { checkActiveFixerSession as checkActiveFixerSessionHelper, hasActiveSession as hasActiveSessionHelper, } from './ratchet-active-session.helpers.js';
+import { logWorkspaceRatchetingDecision as logWorkspaceRatchetingDecisionHelper } from './ratchet-decision-logging.helpers.js';
 import { triggerRatchetFixer } from './ratchet-fixer-dispatch.helpers.js';
-import { computeDispatchSnapshotKey as computeDispatchSnapshotKeyHelper, computeLatestReviewActivityAtMs as computeLatestReviewActivityAtMsHelper, determineRatchetState as determineRatchetStateHelper, fetchPRState as fetchPRStateHelper, getAuthenticatedUsernameCached as getAuthenticatedUsernameCachedHelper, hasNewReviewActivitySinceLastDispatch as hasNewReviewActivitySinceLastDispatchHelper, shouldSkipCleanPR as shouldSkipCleanPRHelper, } from './ratchet-pr-state.helpers.js';
-import { handleReviewCommentPoll as handleReviewCommentPollHelper } from './ratchet-review-poll.helpers.js';
-import { RatchetWorkspaceCheckCoordinator } from './ratchet-workspace-check-coordinator.js';
+import { determineRatchetState as determineRatchetStateHelper, fetchPRState as fetchPRStateHelper, getAuthenticatedUsernameCached as getAuthenticatedUsernameCachedHelper, hasNewReviewActivitySinceLastDispatch as hasNewReviewActivitySinceLastDispatchHelper, isPRStateFetchSkipped, shouldSkipCleanPR as shouldSkipCleanPRHelper, } from './ratchet-pr-state.helpers.js';
+import { assertValidRatchetTransition } from './ratchet-state-machine.js';
+import { RatchetWorkspaceCheckCoordinator, } from './ratchet-workspace-check-coordinator.js';
 const logger = createLogger('ratchet');
+const RATCHET_WORKSPACE_CONCURRENCY = 3;
+const ratchetWorkspaceLimit = pLimit(RATCHET_WORKSPACE_CONCURRENCY);
+const scheduleRatchetBatchCheck = (task) => ratchetWorkspaceLimit(task);
+const RECENTLY_FETCHED_REASON = 'recently_fetched';
+function isRecentlyFetchedWaitResult(result) {
+    return result.action.type === 'WAITING' && result.action.reason === RECENTLY_FETCHED_REASON;
+}
 export const RATCHET_STATE_CHANGED = 'ratchet_state_changed';
 export const RATCHET_TOGGLED = 'ratchet_toggled';
+export const RATCHET_DISPATCH_CHANGED = 'ratchet_dispatch_changed';
 class RatchetService extends EventEmitter {
     isShuttingDown = false;
     monitorLoop = null;
@@ -23,14 +33,21 @@ class RatchetService extends EventEmitter {
     checkCoordinator = new RatchetWorkspaceCheckCoordinator(() => this.workspaceCheckTimeoutMs);
     cachedAuthenticatedUsername = null;
     backoff = new RateLimitBackoff();
-    reviewPollTrackers = new Map();
     sessionBridge = null;
     githubBridge = null;
     snapshotBridge = null;
+    workspaceBridge = null;
     configure(bridges) {
         this.sessionBridge = bridges.session;
         this.githubBridge = bridges.github;
         this.snapshotBridge = bridges.snapshot;
+        this.workspaceBridge = bridges.workspace;
+    }
+    get workspace() {
+        if (!this.workspaceBridge) {
+            throw new Error('RatchetService not configured: workspace bridge missing. Call configure() first.');
+        }
+        return this.workspaceBridge;
     }
     get session() {
         if (!this.sessionBridge) {
@@ -125,11 +142,12 @@ class RatchetService extends EventEmitter {
         if (this.isShuttingDown) {
             return { checked: 0, stateChanges: 0, actionsTriggered: 0, results: [] };
         }
-        const workspaces = await workspaceAccessor.findWithPRsForRatchet();
+        const workspaces = await workspaceRatchetService.findCandidates();
         if (workspaces.length === 0) {
             return { checked: 0, stateChanges: 0, actionsTriggered: 0, results: [] };
         }
-        const results = await Promise.all(workspaces.map((workspace) => this.runWorkspaceCheckSafely(workspace)));
+        const userSettings = await userSettingsService.get();
+        const results = await Promise.all(workspaces.map((workspace) => this.runWorkspaceCheckSafely(workspace, undefined, scheduleRatchetBatchCheck, userSettings.ratchetReviewTriggerMode)));
         const stateChanges = results.filter((r) => r.previousState !== r.newState).length;
         const actionsTriggered = results.filter((r) => r.action.type === 'TRIGGERED_FIXER').length;
         if (stateChanges > 0 || actionsTriggered > 0) {
@@ -141,22 +159,68 @@ class RatchetService extends EventEmitter {
         }
         return { checked: workspaces.length, stateChanges, actionsTriggered, results };
     }
-    async checkWorkspaceById(workspaceId) {
+    async checkWorkspaceById(workspaceId, opts) {
         if (this.isShuttingDown) {
             return null;
         }
-        const workspace = await workspaceAccessor.findForRatchetById(workspaceId);
+        const workspace = await workspaceRatchetService.findCandidateById(workspaceId);
         if (!workspace) {
             return null;
         }
-        return this.runWorkspaceCheckSafely(workspace);
+        const userSettings = await userSettingsService.get();
+        const reviewTriggerMode = userSettings.ratchetReviewTriggerMode;
+        const result = await this.runWorkspaceCheckSafely(workspace, opts, undefined, reviewTriggerMode);
+        if (opts?.bypassPrFetchCooldown && isRecentlyFetchedWaitResult(result)) {
+            const freshWorkspace = await workspaceRatchetService.findCandidateById(workspaceId);
+            if (!freshWorkspace) {
+                return result;
+            }
+            return this.runWorkspaceCheckSafely(freshWorkspace, opts, undefined, reviewTriggerMode);
+        }
+        return result;
+    }
+    async recordSessionEnd(workspaceId, sessionId, outcome) {
+        const settled = await this.workspace.recordSessionEnd(workspaceId, sessionId, outcome);
+        if (!settled) {
+            return;
+        }
+        this.emit(RATCHET_DISPATCH_CHANGED, {
+            workspaceId,
+        });
     }
-    async clearRatchetActiveSessionIfMatching(workspaceId, sessionId) {
-        await workspaceAccessor.clearRatchetActiveSession(workspaceId, sessionId);
+    async markPrClosed(workspaceId) {
+        const maxCasAttempts = 3;
+        for (let attempt = 0; attempt < maxCasAttempts; attempt++) {
+            const workspace = await workspaceDataService.findById(workspaceId);
+            if (!workspace?.ratchetEnabled || workspace.ratchetState === RatchetState.IDLE) {
+                return;
+            }
+            const fromState = workspace.ratchetState;
+            assertValidRatchetTransition(workspaceId, fromState, RatchetState.IDLE);
+            const updated = await workspaceRatchetService.transitionStateIfEnabled(workspaceId, fromState, {
+                ratchetState: RatchetState.IDLE,
+                ratchetLastCheckedAt: new Date(),
+            });
+            if (updated) {
+                this.emit(RATCHET_STATE_CHANGED, {
+                    workspaceId,
+                    fromState,
+                    toState: RatchetState.IDLE,
+                });
+                return;
+            }
+        }
+        logger.warn('markPrClosed gave up after losing repeated state CAS races', {
+            workspaceId,
+            attempts: maxCasAttempts,
+        });
     }
-    async runWorkspaceCheckSafely(workspace) {
+    async runWorkspaceCheckSafely(workspace, opts, schedule, reviewTriggerMode) {
         try {
-            return await this.checkCoordinator.run(workspace, () => this.processWorkspace(workspace));
+            return await this.checkCoordinator.run(workspace, (signal, commitSideEffects) => {
+                signal.throwIfAborted();
+                return this.processWorkspace(workspace, opts, signal, commitSideEffects, reviewTriggerMode);
+            }, schedule);
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
@@ -174,14 +238,12 @@ class RatchetService extends EventEmitter {
         }
     }
     async setWorkspaceRatcheting(workspaceId, enabled) {
-        const workspace = await workspaceAccessor.findById(workspaceId);
+        const workspace = await workspaceDataService.findById(workspaceId);
         if (!workspace) {
             throw new Error(`Workspace not found: ${workspaceId}`);
         }
         if (enabled) {
-            await workspaceAccessor.update(workspaceId, {
-                ratchetEnabled: true,
-            });
+            await workspaceRatchetService.enable(workspaceId);
             this.emit(RATCHET_TOGGLED, {
                 workspaceId,
                 enabled: true,
@@ -189,25 +251,8 @@ class RatchetService extends EventEmitter {
             });
             return;
         }
-        const activeSessionId = workspace.ratchetActiveSessionId;
-        if (activeSessionId && this.session.isSessionRunning(activeSessionId)) {
-            try {
-                await this.session.stopSession(activeSessionId);
-            }
-            catch (error) {
-                logger.warn('Failed to stop active ratchet session while disabling ratchet', {
-                    workspaceId,
-                    sessionId: activeSessionId,
-                    error: error instanceof Error ? error.message : String(error),
-                });
-            }
-        }
-        await workspaceAccessor.update(workspaceId, {
-            ratchetEnabled: false,
-            ratchetState: RatchetState.IDLE,
-            ratchetActiveSessionId: null,
-            ratchetLastCiRunId: null,
-        });
+        await workspaceRatchetService.disable(workspaceId);
+        await this.stopActiveRatchetSessionsAfterDisable(workspaceId);
         if (workspace.ratchetState !== RatchetState.IDLE) {
             this.emit(RATCHET_STATE_CHANGED, {
                 workspaceId,
@@ -221,7 +266,9 @@ class RatchetService extends EventEmitter {
             ratchetState: RatchetState.IDLE,
         });
     }
-    async processWorkspace(workspace) {
+    async processWorkspace(workspace, opts, signal = new AbortController().signal, commitSideEffects = () => {
+    }, reviewTriggerMode) {
+        signal.throwIfAborted();
         if (this.isShuttingDown) {
             return {
                 workspaceId: workspace.id,
@@ -232,31 +279,41 @@ class RatchetService extends EventEmitter {
         }
         if (!workspace.ratchetEnabled) {
             const action = { type: 'DISABLED', reason: 'Workspace ratcheting disabled' };
+            const fromState = workspace.ratchetState;
             const newState = RatchetState.IDLE;
-            await workspaceAccessor.update(workspace.id, {
-                ratchetState: newState,
-                ratchetLastCheckedAt: new Date(),
-            });
-            if (workspace.ratchetState !== newState) {
+            signal.throwIfAborted();
+            assertValidRatchetTransition(workspace.id, fromState, newState);
+            const settled = await workspaceRatchetService.settleIdleWhileDisabled(workspace.id, fromState);
+            signal.throwIfAborted();
+            if (settled && fromState !== newState) {
                 this.emit(RATCHET_STATE_CHANGED, {
                     workspaceId: workspace.id,
-                    fromState: workspace.ratchetState,
+                    fromState,
                     toState: newState,
                 });
             }
-            this.logWorkspaceRatchetingDecision(workspace, workspace.ratchetState, newState, action, null);
+            const reportedState = settled ? newState : fromState;
+            this.logWorkspaceRatchetingDecision(workspace, fromState, reportedState, action, null);
             return {
                 workspaceId: workspace.id,
-                previousState: workspace.ratchetState,
-                newState,
+                previousState: fromState,
+                newState: reportedState,
                 action,
             };
         }
         try {
-            const authenticatedUsername = await this.getAuthenticatedUsernameCached();
-            const prStateInfo = await this.fetchPRState(workspace, authenticatedUsername);
-            if (!prStateInfo) {
-                const action = { type: 'ERROR', error: 'Failed to fetch PR state' };
+            signal.throwIfAborted();
+            const effectiveReviewTriggerMode = reviewTriggerMode ?? (await userSettingsService.get()).ratchetReviewTriggerMode;
+            signal.throwIfAborted();
+            const authenticatedUsername = await this.getAuthenticatedUsernameCached(signal);
+            signal.throwIfAborted();
+            const prStateResult = await this.fetchPRState(workspace, authenticatedUsername, {
+                bypassRecentFetchCooldown: opts?.bypassPrFetchCooldown,
+                reviewTriggerMode: effectiveReviewTriggerMode,
+            }, signal);
+            signal.throwIfAborted();
+            if (isPRStateFetchSkipped(prStateResult)) {
+                const action = { type: 'WAITING', reason: prStateResult.reason };
                 this.logWorkspaceRatchetingDecision(workspace, workspace.ratchetState, workspace.ratchetState, action, null);
                 return {
                     workspaceId: workspace.id,
@@ -265,39 +322,28 @@ class RatchetService extends EventEmitter {
                     action,
                 };
             }
-            const decisionContext = await this.buildRatchetDecisionContext(workspace, prStateInfo);
-            const decision = this.decideRatchetAction(decisionContext);
-            if (prStateInfo.prState === 'MERGED') {
-                this.reviewPollTrackers.delete(workspace.id);
-            }
-            else if (decisionContext.isCleanPrWithNoNewReviewActivity) {
-                const pollDispatch = await this.processReviewCommentPoll(workspace, prStateInfo, authenticatedUsername);
-                if (pollDispatch) {
-                    return pollDispatch;
-                }
-            }
-            else {
-                this.reviewPollTrackers.delete(workspace.id);
-            }
-            const action = await this.applyRatchetDecision(decisionContext, decision);
-            await this.updateWorkspaceAfterCheck(workspace, prStateInfo, action, decisionContext.finalState);
-            if (decisionContext.previousState !== decisionContext.finalState) {
-                this.emit(RATCHET_STATE_CHANGED, {
+            if (!prStateResult) {
+                const action = { type: 'ERROR', error: 'Failed to fetch PR state' };
+                this.logWorkspaceRatchetingDecision(workspace, workspace.ratchetState, workspace.ratchetState, action, null);
+                return {
                     workspaceId: workspace.id,
-                    fromState: decisionContext.previousState,
-                    toState: decisionContext.finalState,
-                    prCiStatus: prStateInfo.ciStatus,
-                });
+                    previousState: workspace.ratchetState,
+                    newState: workspace.ratchetState,
+                    action,
+                };
             }
-            this.logWorkspaceRatchetingDecision(workspace, decisionContext.previousState, decisionContext.finalState, action, prStateInfo, decisionContext);
-            return {
-                workspaceId: workspace.id,
-                previousState: decisionContext.previousState,
-                newState: decisionContext.finalState,
-                action,
-            };
+            const prStateInfo = prStateResult;
+            signal.throwIfAborted();
+            const decisionContext = await this.buildRatchetDecisionContext(workspace, prStateInfo, signal);
+            signal.throwIfAborted();
+            const decision = await this.decideRatchetAction(decisionContext, signal);
+            signal.throwIfAborted();
+            const action = await this.applyRatchetDecision(decisionContext, decision, signal, commitSideEffects);
+            signal.throwIfAborted();
+            return await this.finishRatchetCheck(workspace, prStateInfo, action, decisionContext, signal);
         }
         catch (error) {
+            signal.throwIfAborted();
             const errorMessage = error instanceof Error ? error.message : String(error);
             logger.error('Error processing workspace in ratchet', toError(error), {
                 workspaceId: workspace.id,
@@ -320,83 +366,36 @@ class RatchetService extends EventEmitter {
             action,
             prStateInfo,
             decisionContext,
-            logger,
         });
     }
-    buildRatchetingLogContext(workspace, previousState, newState, action, prStateInfo, prNumber, decisionContext) {
-        return buildRatchetingLogContextHelper({
-            workspace,
-            previousState,
-            newState,
-            action,
-            prStateInfo,
-            prNumber,
-            decisionContext,
-            logger,
-        });
-    }
-    async buildRatchetDecisionContext(workspace, prStateInfo) {
+    async buildRatchetDecisionContext(workspace, prStateInfo, signal = new AbortController().signal) {
         const previousState = workspace.ratchetState;
-        const newState = this.determineRatchetState(prStateInfo);
-        const finalState = workspace.ratchetEnabled ? newState : RatchetState.IDLE;
-        const hasNewReviewActivitySinceLastDispatch = this.hasNewReviewActivitySinceLastDispatch(workspace, prStateInfo);
+        const newState = determineRatchetStateHelper(prStateInfo);
+        const hasNewReviewActivitySinceLastDispatch = hasNewReviewActivitySinceLastDispatchHelper(workspace, prStateInfo);
         const hasStateChangedSinceLastDispatch = this.hasStateChangedSinceLastDispatch(workspace, prStateInfo);
-        const isCleanPrWithNoNewReviewActivity = this.shouldSkipCleanPR(workspace, prStateInfo);
-        const activityChecks = await this.collectRatchetingActivityChecks(workspace, prStateInfo, isCleanPrWithNoNewReviewActivity, hasStateChangedSinceLastDispatch);
+        const isCleanPrWithNoNewReviewActivity = shouldSkipCleanPRHelper(workspace, prStateInfo);
+        const activeFixerCheck = prStateInfo.prState === 'OPEN'
+            ? await this.checkActiveFixerSession(workspace, signal)
+            : { kind: 'none' };
+        signal.throwIfAborted();
+        const dispatchOutcome = activeFixerCheck.kind === 'settled'
+            ? activeFixerCheck.outcome
+            : workspace.ratchetDispatchOutcome;
         return {
             workspace,
             prStateInfo,
             previousState,
             newState,
-            finalState,
             hasNewReviewActivitySinceLastDispatch,
             hasStateChangedSinceLastDispatch,
             isCleanPrWithNoNewReviewActivity,
-            activeRatchetSession: activityChecks.activeRatchetSession,
-            hasOtherActiveSession: activityChecks.hasOtherActiveSession,
+            activeFixerCheck,
+            dispatchOutcome,
+            dispatchRetryCount: workspace.ratchetDispatchRetryCount,
         };
     }
-    async collectRatchetingActivityChecks(workspace, prStateInfo, isCleanPrWithNoNewReviewActivity, hasStateChangedSinceLastDispatch) {
-        if (!workspace.ratchetEnabled || prStateInfo.prState !== 'OPEN') {
-            return {
-                activeRatchetSession: null,
-                hasOtherActiveSession: false,
-            };
-        }
-        let activeRatchetSession = null;
-        if (workspace.ratchetActiveSessionId) {
-            activeRatchetSession = await this.getActiveRatchetSession(workspace);
-            if (activeRatchetSession) {
-                return {
-                    activeRatchetSession,
-                    hasOtherActiveSession: false,
-                };
-            }
-        }
-        if (isCleanPrWithNoNewReviewActivity) {
-            return {
-                activeRatchetSession: null,
-                hasOtherActiveSession: false,
-            };
-        }
-        if (!hasStateChangedSinceLastDispatch) {
-            return {
-                activeRatchetSession: null,
-                hasOtherActiveSession: false,
-            };
-        }
-        return {
-            activeRatchetSession: null,
-            hasOtherActiveSession: await this.hasActiveSession(workspace.id),
-        };
-    }
-    decideRatchetAction(context) {
-        if (!context.workspace.ratchetEnabled) {
-            return {
-                type: 'RETURN_ACTION',
-                action: { type: 'DISABLED', reason: 'Workspace ratcheting disabled' },
-            };
-        }
+    async decideRatchetAction(context, signal = new AbortController().signal) {
+        signal.throwIfAborted();
         if (context.prStateInfo.prState === 'MERGED') {
             return { type: 'RETURN_ACTION', action: { type: 'COMPLETED' } };
         }
@@ -414,8 +413,20 @@ class RatchetService extends EventEmitter {
                 action: { type: 'WAITING', reason: 'Waiting for CI to complete (not in terminal state)' },
             };
         }
-        if (context.activeRatchetSession) {
-            return { type: 'RETURN_ACTION', action: context.activeRatchetSession };
+        if (context.activeFixerCheck.kind === 'active') {
+            return { type: 'RETURN_ACTION', action: context.activeFixerCheck.action };
+        }
+        if (context.activeFixerCheck.kind === 'ended_concurrently') {
+            return {
+                type: 'RETURN_ACTION',
+                action: {
+                    type: 'WAITING',
+                    reason: 'Fixer session ended during this check; re-evaluating next cycle',
+                },
+            };
+        }
+        if (!context.hasStateChangedSinceLastDispatch && context.dispatchOutcome === 'DIED') {
+            return this.decideDiedFixerRetry(context, signal);
         }
         if (context.isCleanPrWithNoNewReviewActivity) {
             return {
@@ -435,7 +446,8 @@ class RatchetService extends EventEmitter {
                 action: { type: 'WAITING', reason: 'PR state unchanged since last ratchet dispatch' },
             };
         }
-        if (context.hasOtherActiveSession) {
+        signal.throwIfAborted();
+        if (await this.hasActiveSession(context.workspace.id, signal)) {
             return {
                 type: 'RETURN_ACTION',
                 action: {
@@ -444,13 +456,36 @@ class RatchetService extends EventEmitter {
                 },
             };
         }
-        return { type: 'TRIGGER_FIXER' };
+        return { type: 'TRIGGER_FIXER', retryCount: 0 };
     }
-    async applyRatchetDecision(context, decision) {
+    async decideDiedFixerRetry(context, signal = new AbortController().signal) {
+        if (context.dispatchRetryCount >= SERVICE_THRESHOLDS.ratchetDispatchMaxRetries) {
+            return {
+                type: 'RETURN_ACTION',
+                action: {
+                    type: 'WAITING',
+                    reason: `Fixer died ${context.dispatchRetryCount + 1} times for this PR state; waiting for PR state to change`,
+                },
+            };
+        }
+        signal.throwIfAborted();
+        if (await this.hasActiveSession(context.workspace.id, signal)) {
+            return {
+                type: 'RETURN_ACTION',
+                action: { type: 'WAITING', reason: 'Workspace has another working session' },
+            };
+        }
+        return { type: 'TRIGGER_FIXER', retryCount: context.dispatchRetryCount + 1 };
+    }
+    async applyRatchetDecision(context, decision, signal = new AbortController().signal, commitSideEffects = () => {
+    }) {
         if (decision.type === 'RETURN_ACTION') {
             return decision.action;
         }
-        return await this.triggerFixer(context.workspace, context.prStateInfo);
+        signal.throwIfAborted();
+        const action = await this.triggerFixer(context.workspace, context.prStateInfo, decision.retryCount, signal, commitSideEffects);
+        signal.throwIfAborted();
+        return action;
     }
     hasActionableFixTrigger(prStateInfo) {
         if (prStateInfo.ciStatus === CIStatus.FAILURE) {
@@ -459,140 +494,159 @@ class RatchetService extends EventEmitter {
         if (prStateInfo.hasMergeConflict) {
             return true;
         }
+        if (prStateInfo.hasChangesRequested) {
+            return true;
+        }
         return (prStateInfo.reviewComments?.length ?? 0) > 0;
     }
-    shouldSkipCleanPR(workspace, prStateInfo) {
-        return shouldSkipCleanPRHelper(workspace, prStateInfo, logger);
-    }
-    hasNewReviewActivitySinceLastDispatch(workspace, prStateInfo) {
-        return hasNewReviewActivitySinceLastDispatchHelper(workspace, prStateInfo, logger);
-    }
-    async processReviewCommentPoll(workspace, prStateInfo, authenticatedUsername) {
-        const pollResult = await this.handleReviewCommentPoll(workspace, prStateInfo, authenticatedUsername);
-        if (pollResult.action !== 'comments-found') {
-            return null;
+    async finishRatchetCheck(workspace, prStateInfo, action, decisionContext, signal = new AbortController().signal) {
+        signal.throwIfAborted();
+        const updateResult = await this.updateWorkspaceAfterCheck(workspace, prStateInfo, action, decisionContext.newState, signal);
+        signal.throwIfAborted();
+        if (updateResult === 'disabled') {
+            const disabledAction = {
+                type: 'DISABLED',
+                reason: 'Workspace ratcheting disabled',
+            };
+            this.logWorkspaceRatchetingDecision(workspace, decisionContext.previousState, RatchetState.IDLE, disabledAction, prStateInfo, decisionContext);
+            return {
+                workspaceId: workspace.id,
+                previousState: decisionContext.previousState,
+                newState: RatchetState.IDLE,
+                action: disabledAction,
+            };
+        }
+        if (updateResult === 'superseded') {
+            const supersededAction = {
+                type: 'WAITING',
+                reason: 'Ratchet state changed concurrently during this check; re-evaluating next cycle',
+            };
+            this.logWorkspaceRatchetingDecision(workspace, decisionContext.previousState, decisionContext.previousState, supersededAction, prStateInfo, decisionContext);
+            return {
+                workspaceId: workspace.id,
+                previousState: decisionContext.previousState,
+                newState: decisionContext.previousState,
+                action: supersededAction,
+            };
         }
-        const freshContext = await this.buildRatchetDecisionContext(workspace, pollResult.freshPrState);
-        const freshDecision = this.decideRatchetAction(freshContext);
-        const freshAction = await this.applyRatchetDecision(freshContext, freshDecision);
-        await this.updateWorkspaceAfterCheck(workspace, pollResult.freshPrState, freshAction, freshContext.finalState);
-        if (freshContext.previousState !== freshContext.finalState) {
+        if (decisionContext.previousState !== decisionContext.newState) {
             this.emit(RATCHET_STATE_CHANGED, {
                 workspaceId: workspace.id,
-                fromState: freshContext.previousState,
-                toState: freshContext.finalState,
-                prCiStatus: pollResult.freshPrState.ciStatus,
+                fromState: decisionContext.previousState,
+                toState: decisionContext.newState,
+                prCiStatus: prStateInfo.ciStatus,
             });
         }
-        this.logWorkspaceRatchetingDecision(workspace, freshContext.previousState, freshContext.finalState, freshAction, pollResult.freshPrState, freshContext);
+        this.logWorkspaceRatchetingDecision(workspace, decisionContext.previousState, decisionContext.newState, action, prStateInfo, decisionContext);
         return {
             workspaceId: workspace.id,
-            previousState: freshContext.previousState,
-            newState: freshContext.finalState,
-            action: freshAction,
+            previousState: decisionContext.previousState,
+            newState: decisionContext.newState,
+            action,
         };
     }
-    async handleReviewCommentPoll(workspace, prStateInfo, authenticatedUsername) {
-        return await handleReviewCommentPollHelper({
-            workspace,
-            prStateInfo,
-            authenticatedUsername,
-            reviewPollTrackers: this.reviewPollTrackers,
-            isShuttingDown: this.isShuttingDown,
-            fetchPRState: (workspaceArg, authenticatedUsernameArg) => this.fetchPRState(workspaceArg, authenticatedUsernameArg),
-            shouldSkipCleanPR: (workspaceArg, prStateInfoArg) => this.shouldSkipCleanPR(workspaceArg, prStateInfoArg),
-            logger,
-        });
-    }
     hasStateChangedSinceLastDispatch(workspace, prStateInfo) {
         return workspace.ratchetLastCiRunId !== prStateInfo.snapshotKey;
     }
-    async updateWorkspaceAfterCheck(workspace, prStateInfo, action, nextState) {
+    async updateWorkspaceAfterCheck(workspace, prStateInfo, action, nextState, signal = new AbortController().signal) {
         const now = new Date();
         const dispatched = action.type === 'TRIGGERED_FIXER' && action.promptSent;
-        await workspaceAccessor.update(workspace.id, {
+        signal.throwIfAborted();
+        assertValidRatchetTransition(workspace.id, workspace.ratchetState, nextState);
+        const updated = await workspaceRatchetService.transitionStateIfEnabled(workspace.id, workspace.ratchetState, {
             ratchetState: nextState,
             ratchetLastCheckedAt: now,
-            ...(dispatched
-                ? {
-                    ratchetLastCiRunId: prStateInfo.snapshotKey,
-                }
-                : {}),
         });
+        signal.throwIfAborted();
+        if (!updated) {
+            const fresh = await workspaceDataService.findById(workspace.id);
+            signal.throwIfAborted();
+            return fresh?.ratchetEnabled ? 'superseded' : 'disabled';
+        }
         if (dispatched) {
+            signal.throwIfAborted();
             await this.snapshot.recordReviewCheck(workspace.id, now);
+            signal.throwIfAborted();
         }
         if (prStateInfo.ciStatus !== workspace.prCiStatus) {
+            signal.throwIfAborted();
             await this.snapshot.recordCIObservation({
                 workspaceId: workspace.id,
                 ciStatus: prStateInfo.ciStatus,
                 observedAt: now,
             });
+            signal.throwIfAborted();
         }
+        return 'applied';
     }
-    async getActiveRatchetSession(workspace) {
-        return await getActiveRatchetSessionHelper({
+    async checkActiveFixerSession(workspace, signal = new AbortController().signal) {
+        return await checkActiveFixerSessionHelper({
             workspace,
             sessionBridge: this.session,
-            snapshotBridge: this.snapshot,
-            resetDispatchState: (workspaceId) => this.resetDispatchState(workspaceId),
-            clearActiveSession: (workspaceId) => this.clearActiveSession(workspaceId),
-            logger,
+            workspaceBridge: this.workspace,
+            signal,
+            onDispatchChanged: (event) => {
+                this.emit(RATCHET_DISPATCH_CHANGED, event);
+            },
         });
     }
-    async hasActiveSession(workspaceId) {
-        return await hasActiveSessionHelper(workspaceId, this.session);
+    async hasActiveSession(workspaceId, signal = new AbortController().signal) {
+        return await hasActiveSessionHelper(workspaceId, this.session, signal);
     }
-    async fetchPRState(workspace, authenticatedUsername) {
-        const result = await fetchPRStateHelper({
+    async fetchPRState(workspace, authenticatedUsername, opts, signal) {
+        return await fetchPRStateHelper({
             workspace,
             authenticatedUsername,
+            reviewTriggerMode: opts?.reviewTriggerMode ?? 'CHANGES_REQUESTED',
             github: this.github,
             backoff: this.backoff,
-            logger,
-            computeLatestReviewActivityAtMs: (prDetails, reviewComments, authenticatedUsernameArg) => this.computeLatestReviewActivityAtMs(prDetails, reviewComments, authenticatedUsernameArg),
-            computeDispatchSnapshotKey: (ciStatus, hasChangesRequested, latestReviewActivityAtMs, statusChecks, hasMergeConflict) => this.computeDispatchSnapshotKey(ciStatus, hasChangesRequested, latestReviewActivityAtMs, statusChecks, hasMergeConflict),
+            signal,
+            bypassRecentFetchCooldown: opts?.bypassRecentFetchCooldown,
         });
-        return result;
-    }
-    computeDispatchSnapshotKey(ciStatus, hasChangesRequested, latestReviewActivityAtMs, statusChecks, hasMergeConflict) {
-        return computeDispatchSnapshotKeyHelper(ciStatus, hasChangesRequested, latestReviewActivityAtMs, statusChecks, hasMergeConflict);
-    }
-    computeLatestReviewActivityAtMs(prDetails, reviewComments, authenticatedUsername) {
-        return computeLatestReviewActivityAtMsHelper(prDetails, reviewComments, authenticatedUsername);
     }
-    async getAuthenticatedUsernameCached() {
+    async getAuthenticatedUsernameCached(signal) {
         const { username, cache } = await getAuthenticatedUsernameCachedHelper({
             cachedValue: this.cachedAuthenticatedUsername,
             github: this.github,
+            signal,
         });
         this.cachedAuthenticatedUsername = cache;
         return username;
     }
-    determineRatchetState(pr) {
-        return determineRatchetStateHelper(pr);
-    }
-    async triggerFixer(workspace, prStateInfo) {
-        return await triggerRatchetFixer({
+    async triggerFixer(workspace, prStateInfo, retryCount, signal = new AbortController().signal, commitSideEffects = () => {
+    }) {
+        const action = await triggerRatchetFixer({
             workspace,
             prStateInfo,
+            retryCount,
             sessionBridge: this.session,
-            setActiveSession: (workspaceId, sessionId) => this.setActiveSession(workspaceId, sessionId),
-            clearActiveSession: (workspaceId) => this.clearActiveSession(workspaceId),
-            logger,
-        });
-    }
-    async setActiveSession(workspaceId, sessionId) {
-        await workspaceAccessor.update(workspaceId, { ratchetActiveSessionId: sessionId });
-    }
-    async clearActiveSession(workspaceId) {
-        await workspaceAccessor.update(workspaceId, { ratchetActiveSessionId: null });
-    }
-    async resetDispatchState(workspaceId) {
-        await workspaceAccessor.update(workspaceId, {
-            ratchetActiveSessionId: null,
-            ratchetLastCiRunId: null,
+            signal,
+            commitSideEffects,
+            onDispatchChanged: (event) => {
+                this.emit(RATCHET_DISPATCH_CHANGED, event);
+            },
         });
+        return action;
+    }
+    async stopActiveRatchetSessionsAfterDisable(workspaceId) {
+        const sessions = await this.session.findSessionsByWorkspaceId(workspaceId);
+        const activeRatchetSessions = sessions.filter((session) => session.workflow === 'ratchet' &&
+            (session.status === SessionStatus.RUNNING || session.status === SessionStatus.IDLE));
+        for (const session of activeRatchetSessions) {
+            if (!this.session.isSessionRunning(session.id)) {
+                continue;
+            }
+            try {
+                await this.session.stopSession(session.id);
+            }
+            catch (error) {
+                logger.warn('Failed to stop ratchet session after disabling ratchet', {
+                    workspaceId,
+                    sessionId: session.id,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
     }
 }
 export const ratchetService = new RatchetService();