factory-factory 0.3.21 → 0.4.0

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

@@ -8,6 +8,11 @@ vi.mock('@/backend/services/workspace', () => ({
         findWithPRsForRatchet: vi.fn(),
         findForRatchetById: vi.fn(),
         update: vi.fn(),
+        transitionRatchetStateIfEnabled: vi.fn(),
+        settleRatchetIdleWhileDisabled: vi.fn(),
+        recordRatchetDispatchIfEnabled: vi.fn(),
+        adoptRatchetActiveSessionIfEnabled: vi.fn(),
+        recordRatchetSessionEnd: vi.fn(),
     },
 }));
 vi.mock('@/backend/services/session', () => ({
@@ -40,11 +45,15 @@ import { userSettingsAccessor } from '../../../../backend/services/settings/inde
 import { workspaceAccessor } from '../../../../backend/services/workspace/index.js';
 import { fixerSessionService } from './fixer-session.service.js';
 import { RATCHET_STATE_CHANGED, RATCHET_TOGGLED, ratchetService, } from './ratchet.service.js';
+import { buildRatchetingLogContext } from './ratchet-decision-logging.helpers.js';
+import { computeDispatchSnapshotKey, computeLatestReviewActivityAtMs, determineRatchetState, } from './ratchet-pr-state.helpers.js';
 const mockSessionBridge = {
+    findSessionsByWorkspaceId: vi.fn(),
     isSessionRunning: vi.fn(),
     isSessionWorking: vi.fn(),
     stopSession: vi.fn(),
     startSession: vi.fn(),
+    restartSession: vi.fn(),
     sendSessionMessage: vi.fn(),
     injectCommittedUserMessage: vi.fn(),
 };
@@ -52,9 +61,12 @@ const mockGitHubBridge = {
     extractPRInfo: vi.fn(),
     getPRFullDetails: vi.fn(),
     getReviewComments: vi.fn(),
+    getResolvedReviewCommentIds: vi.fn(),
     computeCIStatus: vi.fn(),
     getAuthenticatedUsername: vi.fn(),
     fetchAndComputePRState: vi.fn(),
+    isRecentlyFetched: vi.fn(),
+    isFetchInFlight: vi.fn(),
     startFetch: vi.fn(),
     registerFetch: vi.fn(),
     cancelFetch: vi.fn(),
@@ -70,13 +82,20 @@ describe('ratchet service (state-change + idle dispatch)', () => {
         unsafeCoerce(ratchetService).isShuttingDown = false;
         unsafeCoerce(ratchetService).workspaceCheckTimeoutMs =
             SERVICE_TIMEOUT_MS.ratchetWorkspaceCheck;
-        unsafeCoerce(ratchetService).reviewPollTrackers.clear();
         ratchetService.configure({
             session: mockSessionBridge,
             github: mockGitHubBridge,
             snapshot: mockSnapshotBridge,
         });
+        vi.mocked(workspaceAccessor.transitionRatchetStateIfEnabled).mockResolvedValue(true);
+        vi.mocked(workspaceAccessor.settleRatchetIdleWhileDisabled).mockResolvedValue(true);
+        vi.mocked(workspaceAccessor.recordRatchetDispatchIfEnabled).mockResolvedValue(true);
+        vi.mocked(workspaceAccessor.adoptRatchetActiveSessionIfEnabled).mockResolvedValue(true);
+        vi.mocked(workspaceAccessor.recordRatchetSessionEnd).mockResolvedValue(true);
+        vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        vi.mocked(mockSessionBridge.findSessionsByWorkspaceId).mockResolvedValue([]);
         vi.mocked(mockGitHubBridge.getAuthenticatedUsername).mockResolvedValue(null);
+        vi.mocked(mockGitHubBridge.getResolvedReviewCommentIds).mockResolvedValue(new Set());
         vi.mocked(mockSessionBridge.isSessionWorking).mockReturnValue(false);
         vi.mocked(userSettingsAccessor.get).mockResolvedValue({
             id: 'settings-1',
@@ -101,6 +120,9 @@ describe('ratchet service (state-change + idle dispatch)', () => {
         });
         vi.mocked(userSettingsAccessor.getDefaultSessionProvider).mockResolvedValue('CLAUDE');
     });
+    afterEach(() => {
+        ratchetService.removeAllListeners();
+    });
     it('checks workspaces and processes each', async () => {
         vi.mocked(workspaceAccessor.findWithPRsForRatchet).mockResolvedValue([
             {
@@ -116,6 +138,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 ratchetActiveSessionId: null,
                 ratchetLastCiRunId: null,
                 prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
             },
         ]);
         vi.spyOn(unsafeCoerce(ratchetService), 'processWorkspace').mockResolvedValue({
@@ -139,6 +163,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             ratchetActiveSessionId: null,
             ratchetLastCiRunId: null,
             prReviewLastCheckedAt: null,
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
         };
         const fetchPRStateSpy = vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState');
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
@@ -150,6 +176,70 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             action: { type: 'DISABLED', reason: 'Workspace ratcheting disabled' },
             newState: RatchetState.IDLE,
         });
+        expect(workspaceAccessor.settleRatchetIdleWhileDisabled).toHaveBeenCalledWith('ws-disabled', RatchetState.IDLE);
+    });
+    it('settles a disabled workspace to IDLE via CAS and emits an accurate fromState', async () => {
+        const workspace = {
+            id: 'ws-disabled-settle',
+            prUrl: 'https://github.com/example/repo/pull/2',
+            prNumber: 2,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
+            ratchetEnabled: false,
+            ratchetState: RatchetState.CI_FAILED,
+            ratchetActiveSessionId: null,
+            ratchetLastCiRunId: null,
+            prReviewLastCheckedAt: null,
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
+        };
+        vi.mocked(workspaceAccessor.settleRatchetIdleWhileDisabled).mockResolvedValue(true);
+        const events = [];
+        ratchetService.on(RATCHET_STATE_CHANGED, (event) => {
+            events.push(event);
+        });
+        const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
+        expect(workspaceAccessor.settleRatchetIdleWhileDisabled).toHaveBeenCalledWith('ws-disabled-settle', RatchetState.CI_FAILED);
+        expect(result).toMatchObject({
+            previousState: RatchetState.CI_FAILED,
+            newState: RatchetState.IDLE,
+            action: { type: 'DISABLED' },
+        });
+        expect(events).toEqual([
+            {
+                workspaceId: 'ws-disabled-settle',
+                fromState: RatchetState.CI_FAILED,
+                toState: RatchetState.IDLE,
+            },
+        ]);
+    });
+    it('does not emit for a disabled workspace when the settle CAS loses', async () => {
+        const workspace = {
+            id: 'ws-disabled-settle-race',
+            prUrl: 'https://github.com/example/repo/pull/2',
+            prNumber: 2,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
+            ratchetEnabled: false,
+            ratchetState: RatchetState.CI_FAILED,
+            ratchetActiveSessionId: null,
+            ratchetLastCiRunId: null,
+            prReviewLastCheckedAt: null,
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
+        };
+        vi.mocked(workspaceAccessor.settleRatchetIdleWhileDisabled).mockResolvedValue(false);
+        const events = [];
+        ratchetService.on(RATCHET_STATE_CHANGED, (event) => {
+            events.push(event);
+        });
+        const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
+        expect(result).toMatchObject({
+            previousState: RatchetState.CI_FAILED,
+            newState: RatchetState.CI_FAILED,
+            action: { type: 'DISABLED' },
+        });
+        expect(events).toEqual([]);
     });
     it('does not dispatch when workspace is not idle', async () => {
         const workspace = {
@@ -163,6 +253,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             ratchetActiveSessionId: null,
             ratchetLastCiRunId: null,
             prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
         };
         vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
             ciStatus: CIStatus.SUCCESS,
@@ -212,6 +304,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             ratchetActiveSessionId: null,
             ratchetLastCiRunId: '2026-01-01T00:00:00Z',
             prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
         };
         vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
             ciStatus: CIStatus.FAILURE,
@@ -233,11 +327,64 @@ describe('ratchet service (state-change + idle dispatch)', () => {
         expect(result).toMatchObject({
             action: { type: 'TRIGGERED_FIXER' },
         });
-        const finalUpdatePayload = vi.mocked(workspaceAccessor.update).mock.calls.at(-1)?.[1];
-        expect(finalUpdatePayload.ratchetLastCiRunId).toBe('2026-01-02T00:00:00Z');
+        expect(workspaceAccessor.recordRatchetDispatchIfEnabled).toHaveBeenCalledWith('ws-change', {
+            sessionId: 'ratchet-session',
+            snapshotKey: '2026-01-02T00:00:00Z',
+            retryCount: 0,
+        });
+        const finalUpdatePayload = vi
+            .mocked(workspaceAccessor.transitionRatchetStateIfEnabled)
+            .mock.calls.at(-1)?.[2];
+        expect(finalUpdatePayload).not.toHaveProperty('ratchetLastCiRunId');
         expect(finalUpdatePayload).not.toHaveProperty('prReviewLastCheckedAt');
         expect(mockSnapshotBridge.recordReviewCheck).toHaveBeenCalledWith('ws-change', expect.any(Date));
     });
+    it('stops fixer and returns disabled when active-session recording loses disable race', async () => {
+        const workspace = {
+            id: 'ws-disable-race-dispatch',
+            prUrl: 'https://github.com/example/repo/pull/40',
+            prNumber: 40,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
+            ratchetEnabled: true,
+            ratchetState: RatchetState.IDLE,
+            ratchetActiveSessionId: null,
+            ratchetLastCiRunId: 'old-snapshot',
+            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
+        };
+        vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
+            ciStatus: CIStatus.FAILURE,
+            snapshotKey: 'new-snapshot',
+            hasChangesRequested: false,
+            latestReviewActivityAtMs: null,
+            statusCheckRollup: null,
+            prState: 'OPEN',
+            prNumber: 40,
+        });
+        vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
+            status: 'started',
+            sessionId: 'raced-session',
+            promptSent: true,
+        });
+        vi.mocked(workspaceAccessor.recordRatchetDispatchIfEnabled).mockResolvedValue(false);
+        vi.mocked(workspaceAccessor.transitionRatchetStateIfEnabled).mockResolvedValue(false);
+        vi.mocked(workspaceAccessor.findById).mockResolvedValue({
+            id: 'ws-disable-race-dispatch',
+            ratchetEnabled: false,
+        });
+        vi.mocked(mockSessionBridge.isSessionRunning).mockReturnValue(true);
+        const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
+        expect(result).toMatchObject({
+            newState: RatchetState.IDLE,
+            action: { type: 'DISABLED', reason: 'Workspace ratcheting disabled' },
+        });
+        expect(workspaceAccessor.recordRatchetDispatchIfEnabled).toHaveBeenCalledWith('ws-disable-race-dispatch', { sessionId: 'raced-session', snapshotKey: 'new-snapshot', retryCount: 0 });
+        expect(mockSessionBridge.stopSession).toHaveBeenCalledWith('raced-session');
+        expect(mockSnapshotBridge.recordReviewCheck).not.toHaveBeenCalled();
+    });
     it('dispatches when session is running but idle', async () => {
         const workspace = {
             id: 'ws-idle-session',
@@ -250,6 +397,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             ratchetActiveSessionId: null,
             ratchetLastCiRunId: '2026-01-01T00:00:00Z',
             prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
         };
         vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
             ciStatus: CIStatus.FAILURE,
@@ -294,6 +443,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             ratchetActiveSessionId: null,
             ratchetLastCiRunId: '2026-01-02T00:00:00Z',
             prReviewLastCheckedAt: new Date('2026-01-02T00:00:00Z'),
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
         };
         vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
             ciStatus: CIStatus.FAILURE,
@@ -328,6 +479,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             ratchetActiveSessionId: null,
             ratchetLastCiRunId: 'ci:SUCCESS|changes-requested:1735776000000',
             prReviewLastCheckedAt: new Date('2026-01-02T00:00:00Z'),
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
         };
         vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
             ciStatus: CIStatus.SUCCESS,
@@ -372,6 +525,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             ratchetActiveSessionId: null,
             ratchetLastCiRunId: 'ci:SUCCESS|changes-requested:old',
             prReviewLastCheckedAt: new Date('2026-01-02T00:00:00Z'),
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
         };
         vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
             ciStatus: CIStatus.SUCCESS,
@@ -407,6 +562,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             ratchetActiveSessionId: null,
             ratchetLastCiRunId: 'ci:SUCCESS|no-changes-requested:old|merge:clean',
             prReviewLastCheckedAt: new Date('2026-01-02T00:00:00Z'),
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
         };
         vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
             ciStatus: CIStatus.SUCCESS,
@@ -442,7 +599,7 @@ describe('ratchet service (state-change + idle dispatch)', () => {
         expect(fixerSessionService.acquireAndDispatch).toHaveBeenCalled();
     });
     it('treats closed PR as IDLE and does not dispatch', () => {
-        const state = unsafeCoerce(ratchetService).determineRatchetState({
+        const state = determineRatchetState({
             ciStatus: CIStatus.SUCCESS,
             snapshotKey: '2026-01-02T00:00:00Z',
             hasChangesRequested: false,
@@ -464,6 +621,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             ratchetActiveSessionId: null,
             ratchetLastCiRunId: null,
             prReviewLastCheckedAt: null,
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
         };
         vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
             ciStatus: CIStatus.SUCCESS,
@@ -501,6 +660,36 @@ describe('ratchet service (state-change + idle dispatch)', () => {
         });
         expect(mockSessionBridge.stopSession).toHaveBeenCalledWith('ratchet-session');
     });
+    it('routes an aborted prompt-failure path through orphan cleanup', async () => {
+        const controller = new AbortController();
+        const timeoutError = new Error('Workspace check timed out');
+        let finishPointerClear;
+        vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
+            status: 'started',
+            sessionId: 'aborted-prompt-session',
+            promptSent: false,
+        });
+        vi.mocked(workspaceAccessor.update).mockImplementation(() => new Promise((resolve) => {
+            finishPointerClear = () => resolve({});
+        }));
+        vi.mocked(mockSessionBridge.isSessionRunning).mockReturnValue(true);
+        const trigger = unsafeCoerce(ratchetService).triggerFixer({
+            id: 'ws-aborted-prompt',
+            prUrl: 'https://github.com/example/repo/pull/7',
+        }, {
+            ciStatus: CIStatus.FAILURE,
+            snapshotKey: 'failed:7',
+            prNumber: 7,
+            reviewComments: [],
+            hasMergeConflict: false,
+        }, 0, controller.signal);
+        await vi.waitFor(() => expect(workspaceAccessor.update).toHaveBeenCalled());
+        controller.abort(timeoutError);
+        finishPointerClear();
+        await expect(trigger).rejects.toBe(timeoutError);
+        expect(workspaceAccessor.recordRatchetSessionEnd).toHaveBeenCalledWith('ws-aborted-prompt', 'aborted-prompt-session', 'COMPLETED');
+        expect(mockSessionBridge.stopSession).toHaveBeenCalledWith('aborted-prompt-session');
+    });
     it('does not dispatch on a clean PR with no new review activity', async () => {
         const recentCheck = new Date();
         const workspace = {
@@ -514,6 +703,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             ratchetActiveSessionId: null,
             ratchetLastCiRunId: '2026-01-01T00:00:00Z',
             prReviewLastCheckedAt: recentCheck,
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
         };
         vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
             ciStatus: CIStatus.SUCCESS,
@@ -536,216 +727,473 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             },
         });
     });
-    it('self-heals when review check timestamp is stale with no active session', async () => {
-        const staleCheckedAt = new Date(Date.now() - 15 * 60_000);
+    it('returns disabled when stale check-state update loses disable race', async () => {
+        const recentCheck = new Date();
         const workspace = {
-            id: 'ws-stale-check',
-            prUrl: 'https://github.com/example/repo/pull/13',
-            prNumber: 13,
+            id: 'ws-disable-race-state',
+            prUrl: 'https://github.com/example/repo/pull/41',
+            prNumber: 41,
             prState: 'OPEN',
             prCiStatus: CIStatus.UNKNOWN,
             ratchetEnabled: true,
             ratchetState: RatchetState.READY,
             ratchetActiveSessionId: null,
-            ratchetLastCiRunId: '2026-01-01T00:00:00Z',
-            prReviewLastCheckedAt: staleCheckedAt,
+            ratchetLastCiRunId: 'old-snapshot',
+            prReviewLastCheckedAt: recentCheck,
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
         };
         vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
             ciStatus: CIStatus.SUCCESS,
-            snapshotKey: '2026-01-03T00:00:00Z',
+            snapshotKey: 'new-snapshot',
             hasChangesRequested: false,
-            latestReviewActivityAtMs: staleCheckedAt.getTime() - 1000,
+            latestReviewActivityAtMs: recentCheck.getTime() - 1000,
             statusCheckRollup: null,
             prState: 'OPEN',
-            prNumber: 13,
+            prNumber: 41,
+        });
+        vi.mocked(workspaceAccessor.transitionRatchetStateIfEnabled).mockResolvedValue(false);
+        vi.mocked(workspaceAccessor.findById).mockResolvedValue({
+            id: 'ws-disable-race-state',
+            ratchetEnabled: false,
         });
-        vi.mocked(workspaceAccessor.update).mockResolvedValue({});
         vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        const events = [];
+        ratchetService.on(RATCHET_STATE_CHANGED, (event) => {
+            events.push(event);
+        });
         const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
-        expect(result).not.toMatchObject({
-            action: {
-                type: 'WAITING',
-                reason: 'PR is clean (green CI and no new review activity)',
-            },
+        expect(result).toMatchObject({
+            newState: RatchetState.IDLE,
+            action: { type: 'DISABLED', reason: 'Workspace ratcheting disabled' },
         });
+        expect(events).toHaveLength(0);
+        ratchetService.removeAllListeners();
     });
-    it('resets dispatch tracking when ratchet session process is not running', async () => {
+    it('reports a concurrent state change without emitting when the check loses the CAS while still enabled', async () => {
+        const recentCheck = new Date();
         const workspace = {
-            id: 'ws-stale-active',
-            prUrl: 'https://github.com/example/repo/pull/9',
-            prNumber: 9,
+            id: 'ws-superseded',
+            prUrl: 'https://github.com/example/repo/pull/42',
+            prNumber: 42,
             prState: 'OPEN',
             prCiStatus: CIStatus.UNKNOWN,
             ratchetEnabled: true,
-            ratchetState: RatchetState.CI_FAILED,
-            ratchetActiveSessionId: 'ratchet-session',
-            ratchetLastCiRunId: 'previous-snapshot-key',
-            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
-        };
-        vi.mocked(agentSessionAccessor.findById).mockResolvedValue({
-            id: 'ratchet-session',
-            provider: 'CLAUDE',
-            status: SessionStatus.RUNNING,
-        });
-        vi.mocked(mockSessionBridge.isSessionRunning).mockReturnValue(false);
-        vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        vi.mocked(mockSnapshotBridge.recordReviewCheck).mockResolvedValue();
-        const action = await unsafeCoerce(ratchetService).getActiveRatchetSession(workspace);
-        expect(action).toBeNull();
-        expect(workspaceAccessor.update).toHaveBeenCalledWith(workspace.id, {
+            ratchetState: RatchetState.CI_RUNNING,
             ratchetActiveSessionId: null,
-            ratchetLastCiRunId: null,
-        });
-        expect(mockSnapshotBridge.recordReviewCheck).toHaveBeenCalledWith(workspace.id, null);
-    });
-    it('resets dispatch tracking when ratchet session is not found in database', async () => {
-        const workspace = {
-            id: 'ws-missing-session',
-            prUrl: 'https://github.com/example/repo/pull/12',
-            prNumber: 12,
+            ratchetLastCiRunId: 'old-snapshot',
+            prReviewLastCheckedAt: recentCheck,
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
+        };
+        vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
+            ciStatus: CIStatus.SUCCESS,
+            snapshotKey: 'new-snapshot',
+            hasChangesRequested: false,
+            latestReviewActivityAtMs: recentCheck.getTime() - 1000,
+            statusCheckRollup: null,
             prState: 'OPEN',
-            prCiStatus: CIStatus.UNKNOWN,
+            prNumber: 42,
+        });
+        vi.mocked(workspaceAccessor.transitionRatchetStateIfEnabled).mockResolvedValue(false);
+        vi.mocked(workspaceAccessor.findById).mockResolvedValue({
+            id: 'ws-superseded',
             ratchetEnabled: true,
-            ratchetState: RatchetState.CI_FAILED,
-            ratchetActiveSessionId: 'deleted-session',
-            ratchetLastCiRunId: 'previous-snapshot-key',
-            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
-        };
-        vi.mocked(agentSessionAccessor.findById).mockResolvedValue(null);
-        vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        vi.mocked(mockSnapshotBridge.recordReviewCheck).mockResolvedValue();
-        const action = await unsafeCoerce(ratchetService).getActiveRatchetSession(workspace);
-        expect(action).toBeNull();
-        expect(workspaceAccessor.update).toHaveBeenCalledWith(workspace.id, {
-            ratchetActiveSessionId: null,
-            ratchetLastCiRunId: null,
+            ratchetState: RatchetState.IDLE,
+        });
+        vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        const events = [];
+        ratchetService.on(RATCHET_STATE_CHANGED, (event) => {
+            events.push(event);
+        });
+        const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
+        expect(workspaceAccessor.transitionRatchetStateIfEnabled).toHaveBeenCalledWith('ws-superseded', RatchetState.CI_RUNNING, expect.objectContaining({ ratchetState: RatchetState.READY }));
+        expect(result).toMatchObject({
+            previousState: RatchetState.CI_RUNNING,
+            newState: RatchetState.CI_RUNNING,
+            action: {
+                type: 'WAITING',
+                reason: 'Ratchet state changed concurrently during this check; re-evaluating next cycle',
+            },
         });
-        expect(mockSnapshotBridge.recordReviewCheck).toHaveBeenCalledWith(workspace.id, null);
+        expect(events).toHaveLength(0);
+        expect(mockSnapshotBridge.recordCIObservation).not.toHaveBeenCalled();
+        expect(mockSnapshotBridge.recordReviewCheck).not.toHaveBeenCalled();
     });
-    it('does not reset dispatch tracking when ratchet session completed normally', async () => {
+    it('redispatches with an incremented retry count when the previous fixer died', async () => {
         const workspace = {
-            id: 'ws-idle-active',
-            prUrl: 'https://github.com/example/repo/pull/11',
-            prNumber: 11,
+            id: 'ws-died-retry',
+            prUrl: 'https://github.com/example/repo/pull/13',
+            prNumber: 13,
             prState: 'OPEN',
-            prCiStatus: CIStatus.UNKNOWN,
+            prCiStatus: CIStatus.FAILURE,
             ratchetEnabled: true,
             ratchetState: RatchetState.CI_FAILED,
-            ratchetActiveSessionId: 'ratchet-session',
-            ratchetLastCiRunId: 'snapshot-key',
+            ratchetActiveSessionId: null,
+            ratchetLastCiRunId: 'same-snapshot',
             prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
+            ratchetDispatchOutcome: 'DIED',
+            ratchetDispatchRetryCount: 1,
         };
-        vi.mocked(agentSessionAccessor.findById).mockResolvedValue({
-            id: 'ratchet-session',
-            provider: 'CLAUDE',
-            status: SessionStatus.RUNNING,
+        vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
+            ciStatus: CIStatus.FAILURE,
+            snapshotKey: 'same-snapshot',
+            hasChangesRequested: false,
+            latestReviewActivityAtMs: null,
+            statusCheckRollup: null,
+            prState: 'OPEN',
+            prNumber: 13,
         });
-        vi.mocked(mockSessionBridge.isSessionRunning).mockReturnValue(true);
-        vi.mocked(mockSessionBridge.isSessionWorking).mockReturnValue(false);
-        vi.mocked(mockSessionBridge.stopSession).mockResolvedValue();
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        const action = await unsafeCoerce(ratchetService).getActiveRatchetSession(workspace);
-        expect(action).toBeNull();
-        expect(workspaceAccessor.update).toHaveBeenCalledWith(workspace.id, {
-            ratchetActiveSessionId: null,
+        vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
+            status: 'started',
+            sessionId: 'retry-session',
+            promptSent: true,
+        });
+        const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
+        expect(result).toMatchObject({
+            action: { type: 'TRIGGERED_FIXER' },
+        });
+        expect(workspaceAccessor.recordRatchetDispatchIfEnabled).toHaveBeenCalledWith('ws-died-retry', {
+            sessionId: 'retry-session',
+            snapshotKey: 'same-snapshot',
+            retryCount: 2,
         });
-        expect(mockSessionBridge.stopSession).toHaveBeenCalledWith('ratchet-session');
-        expect(mockSnapshotBridge.recordReviewCheck).not.toHaveBeenCalled();
     });
-    it('cleans up completed ratchet sessions before skipping clean PRs', async () => {
+    it('redispatches a died fixer even when the PR is otherwise clean', async () => {
+        const checkedAt = new Date('2026-01-02T00:00:00Z');
         const workspace = {
-            id: 'ws-clean-active',
-            prUrl: 'https://github.com/example/repo/pull/13',
-            prNumber: 13,
+            id: 'ws-died-clean',
+            prUrl: 'https://github.com/example/repo/pull/14',
+            prNumber: 14,
             prState: 'OPEN',
             prCiStatus: CIStatus.SUCCESS,
             ratchetEnabled: true,
             ratchetState: RatchetState.READY,
-            ratchetActiveSessionId: 'ratchet-session',
+            ratchetActiveSessionId: null,
             ratchetLastCiRunId: 'clean-snapshot',
-            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
+            prReviewLastCheckedAt: checkedAt,
+            ratchetDispatchOutcome: 'DIED',
+            ratchetDispatchRetryCount: 0,
         };
-        const prStateInfo = {
+        vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
             ciStatus: CIStatus.SUCCESS,
             snapshotKey: 'clean-snapshot',
             hasChangesRequested: false,
-            latestReviewActivityAtMs: null,
+            latestReviewActivityAtMs: checkedAt.getTime() - 1000,
             statusCheckRollup: null,
             prState: 'OPEN',
-            prNumber: 13,
+            prNumber: 14,
             reviewComments: [],
-        };
-        vi.mocked(agentSessionAccessor.findById).mockResolvedValue({
-            id: 'ratchet-session',
-            provider: 'CLAUDE',
-            status: SessionStatus.RUNNING,
         });
-        vi.mocked(mockSessionBridge.isSessionRunning).mockReturnValue(true);
-        vi.mocked(mockSessionBridge.isSessionWorking).mockReturnValue(false);
-        vi.mocked(mockSessionBridge.stopSession).mockResolvedValue();
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        const result = await unsafeCoerce(ratchetService).collectRatchetingActivityChecks(workspace, prStateInfo, true, false);
-        expect(result).toEqual({
-            activeRatchetSession: null,
-            hasOtherActiveSession: false,
-        });
-        expect(workspaceAccessor.update).toHaveBeenCalledWith(workspace.id, {
-            ratchetActiveSessionId: null,
-        });
-        expect(mockSessionBridge.stopSession).toHaveBeenCalledWith('ratchet-session');
-        expect(agentSessionAccessor.findByWorkspaceId).not.toHaveBeenCalled();
-    });
-    it('decides to trigger fixer when context is actionable', () => {
-        const decision = unsafeCoerce(ratchetService).decideRatchetAction({
-            workspace: { ratchetEnabled: true },
-            prStateInfo: { prState: 'OPEN', ciStatus: CIStatus.FAILURE },
-            isCleanPrWithNoNewReviewActivity: false,
-            activeRatchetSession: null,
-            hasStateChangedSinceLastDispatch: true,
-            hasOtherActiveSession: false,
-        });
-        expect(decision).toEqual({ type: 'TRIGGER_FIXER' });
-    });
-    it('waits when CI is not in terminal state (PENDING)', () => {
-        const decision = unsafeCoerce(ratchetService).decideRatchetAction({
-            workspace: { ratchetEnabled: true },
-            prStateInfo: { prState: 'OPEN', ciStatus: CIStatus.PENDING },
-            isCleanPrWithNoNewReviewActivity: false,
-            activeRatchetSession: null,
-            hasStateChangedSinceLastDispatch: true,
-            hasOtherActiveSession: false,
-        });
-        expect(decision).toEqual({
-            type: 'RETURN_ACTION',
-            action: { type: 'WAITING', reason: 'Waiting for CI to complete (not in terminal state)' },
+        vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
+            status: 'started',
+            sessionId: 'retry-session',
+            promptSent: true,
         });
-    });
-    it('waits when CI is not in terminal state (UNKNOWN)', () => {
-        const decision = unsafeCoerce(ratchetService).decideRatchetAction({
-            workspace: { ratchetEnabled: true },
-            prStateInfo: { prState: 'OPEN', ciStatus: CIStatus.UNKNOWN },
-            isCleanPrWithNoNewReviewActivity: false,
-            activeRatchetSession: null,
-            hasStateChangedSinceLastDispatch: true,
-            hasOtherActiveSession: false,
+        const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
+        expect(result).toMatchObject({
+            action: { type: 'TRIGGERED_FIXER' },
         });
-        expect(decision).toEqual({
-            type: 'RETURN_ACTION',
-            action: { type: 'WAITING', reason: 'Waiting for CI to complete (not in terminal state)' },
+        expect(workspaceAccessor.recordRatchetDispatchIfEnabled).toHaveBeenCalledWith('ws-died-clean', {
+            sessionId: 'retry-session',
+            snapshotKey: 'clean-snapshot',
+            retryCount: 1,
         });
     });
-    it('prefers precomputed review-activity diagnostics from decision context', () => {
+    it('stops retrying a died fixer once the retry budget is exhausted', async () => {
         const workspace = {
-            id: 'ws-log-diag',
-            prUrl: 'https://github.com/example/repo/pull/10',
-            prNumber: 10,
+            id: 'ws-died-exhausted',
+            prUrl: 'https://github.com/example/repo/pull/15',
+            prNumber: 15,
             prState: 'OPEN',
-            prCiStatus: CIStatus.UNKNOWN,
+            prCiStatus: CIStatus.FAILURE,
             ratchetEnabled: true,
-            ratchetState: RatchetState.READY,
+            ratchetState: RatchetState.CI_FAILED,
+            ratchetActiveSessionId: null,
+            ratchetLastCiRunId: 'same-snapshot',
+            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
+            ratchetDispatchOutcome: 'DIED',
+            ratchetDispatchRetryCount: 3,
+        };
+        vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
+            ciStatus: CIStatus.FAILURE,
+            snapshotKey: 'same-snapshot',
+            hasChangesRequested: false,
+            latestReviewActivityAtMs: null,
+            statusCheckRollup: null,
+            prState: 'OPEN',
+            prNumber: 15,
+        });
+        vi.mocked(workspaceAccessor.update).mockResolvedValue({});
+        const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
+        expect(result).toMatchObject({
+            action: {
+                type: 'WAITING',
+                reason: 'Fixer died 4 times for this PR state; waiting for PR state to change',
+            },
+        });
+        expect(fixerSessionService.acquireAndDispatch).not.toHaveBeenCalled();
+    });
+    it('resets the retry count when the PR state changes after a death', async () => {
+        const workspace = {
+            id: 'ws-died-changed',
+            prUrl: 'https://github.com/example/repo/pull/16',
+            prNumber: 16,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.FAILURE,
+            ratchetEnabled: true,
+            ratchetState: RatchetState.CI_FAILED,
+            ratchetActiveSessionId: null,
+            ratchetLastCiRunId: 'old-snapshot',
+            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
+            ratchetDispatchOutcome: 'DIED',
+            ratchetDispatchRetryCount: 3,
+        };
+        vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
+            ciStatus: CIStatus.FAILURE,
+            snapshotKey: 'new-snapshot',
+            hasChangesRequested: false,
+            latestReviewActivityAtMs: null,
+            statusCheckRollup: null,
+            prState: 'OPEN',
+            prNumber: 16,
+        });
+        vi.mocked(workspaceAccessor.update).mockResolvedValue({});
+        vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
+            status: 'started',
+            sessionId: 'fresh-session',
+            promptSent: true,
+        });
+        const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
+        expect(result).toMatchObject({
+            action: { type: 'TRIGGERED_FIXER' },
+        });
+        expect(workspaceAccessor.recordRatchetDispatchIfEnabled).toHaveBeenCalledWith('ws-died-changed', { sessionId: 'fresh-session', snapshotKey: 'new-snapshot', retryCount: 0 });
+    });
+    it('does not redispatch when the previous fixer completed and PR state is unchanged', async () => {
+        const workspace = {
+            id: 'ws-completed-unchanged',
+            prUrl: 'https://github.com/example/repo/pull/17',
+            prNumber: 17,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.FAILURE,
+            ratchetEnabled: true,
+            ratchetState: RatchetState.CI_FAILED,
+            ratchetActiveSessionId: null,
+            ratchetLastCiRunId: 'same-snapshot',
+            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
+            ratchetDispatchOutcome: 'COMPLETED',
+            ratchetDispatchRetryCount: 2,
+        };
+        vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
+            ciStatus: CIStatus.FAILURE,
+            snapshotKey: 'same-snapshot',
+            hasChangesRequested: false,
+            latestReviewActivityAtMs: null,
+            statusCheckRollup: null,
+            prState: 'OPEN',
+            prNumber: 17,
+        });
+        vi.mocked(workspaceAccessor.update).mockResolvedValue({});
+        const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
+        expect(result).toMatchObject({
+            action: {
+                type: 'WAITING',
+                reason: 'PR state unchanged since last ratchet dispatch',
+            },
+        });
+        expect(fixerSessionService.acquireAndDispatch).not.toHaveBeenCalled();
+    });
+    it('settles the dispatch as DIED when ratchet session process is not running', async () => {
+        const workspace = {
+            id: 'ws-stale-active',
+            prUrl: 'https://github.com/example/repo/pull/9',
+            prNumber: 9,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
+            ratchetEnabled: true,
+            ratchetState: RatchetState.CI_FAILED,
+            ratchetActiveSessionId: 'ratchet-session',
+            ratchetLastCiRunId: 'previous-snapshot-key',
+            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
+            ratchetDispatchOutcome: 'RUNNING',
+            ratchetDispatchRetryCount: 0,
+        };
+        vi.mocked(agentSessionAccessor.findById).mockResolvedValue({
+            id: 'ratchet-session',
+            provider: 'CLAUDE',
+            status: SessionStatus.RUNNING,
+        });
+        vi.mocked(mockSessionBridge.isSessionRunning).mockReturnValue(false);
+        const result = await unsafeCoerce(ratchetService).checkActiveFixerSession(workspace);
+        expect(result).toEqual({ kind: 'settled', outcome: 'DIED' });
+        expect(workspaceAccessor.recordRatchetSessionEnd).toHaveBeenCalledWith(workspace.id, 'ratchet-session', 'DIED');
+    });
+    it('settles the dispatch as DIED when ratchet session is not found in database', async () => {
+        const workspace = {
+            id: 'ws-missing-session',
+            prUrl: 'https://github.com/example/repo/pull/12',
+            prNumber: 12,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
+            ratchetEnabled: true,
+            ratchetState: RatchetState.CI_FAILED,
+            ratchetActiveSessionId: 'deleted-session',
+            ratchetLastCiRunId: 'previous-snapshot-key',
+            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
+            ratchetDispatchOutcome: 'RUNNING',
+            ratchetDispatchRetryCount: 0,
+        };
+        vi.mocked(agentSessionAccessor.findById).mockResolvedValue(null);
+        const result = await unsafeCoerce(ratchetService).checkActiveFixerSession(workspace);
+        expect(result).toEqual({ kind: 'settled', outcome: 'DIED' });
+        expect(workspaceAccessor.recordRatchetSessionEnd).toHaveBeenCalledWith(workspace.id, 'deleted-session', 'DIED');
+    });
+    it('reports a concurrent end when another path already settled the dispatch', async () => {
+        const workspace = {
+            id: 'ws-concurrent-end',
+            prUrl: 'https://github.com/example/repo/pull/12',
+            prNumber: 12,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
+            ratchetEnabled: true,
+            ratchetState: RatchetState.CI_FAILED,
+            ratchetActiveSessionId: 'finished-session',
+            ratchetLastCiRunId: 'previous-snapshot-key',
+            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
+            ratchetDispatchOutcome: 'RUNNING',
+            ratchetDispatchRetryCount: 0,
+        };
+        vi.mocked(agentSessionAccessor.findById).mockResolvedValue(null);
+        vi.mocked(workspaceAccessor.recordRatchetSessionEnd).mockResolvedValue(false);
+        const result = await unsafeCoerce(ratchetService).checkActiveFixerSession(workspace);
+        expect(result).toEqual({ kind: 'ended_concurrently' });
+    });
+    it('waits for the next cycle when the fixer ends concurrently mid-check', async () => {
+        const workspace = {
+            id: 'ws-concurrent-wait',
+            prUrl: 'https://github.com/example/repo/pull/12',
+            prNumber: 12,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
+            ratchetEnabled: true,
+            ratchetState: RatchetState.CI_FAILED,
+            ratchetActiveSessionId: 'finished-session',
+            ratchetLastCiRunId: 'previous-snapshot-key',
+            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
+            ratchetDispatchOutcome: 'RUNNING',
+            ratchetDispatchRetryCount: 0,
+        };
+        vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
+            ciStatus: CIStatus.FAILURE,
+            snapshotKey: 'new-snapshot',
+            hasChangesRequested: false,
+            latestReviewActivityAtMs: null,
+            statusCheckRollup: null,
+            prState: 'OPEN',
+            prNumber: 12,
+        });
+        vi.mocked(agentSessionAccessor.findById).mockResolvedValue(null);
+        vi.mocked(workspaceAccessor.recordRatchetSessionEnd).mockResolvedValue(false);
+        vi.mocked(workspaceAccessor.update).mockResolvedValue({});
+        const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
+        expect(result).toMatchObject({
+            action: {
+                type: 'WAITING',
+                reason: 'Fixer session ended during this check; re-evaluating next cycle',
+            },
+        });
+        expect(fixerSessionService.acquireAndDispatch).not.toHaveBeenCalled();
+    });
+    it('settles the dispatch as COMPLETED when ratchet session finished its work', async () => {
+        const workspace = {
+            id: 'ws-idle-active',
+            prUrl: 'https://github.com/example/repo/pull/11',
+            prNumber: 11,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
+            ratchetEnabled: true,
+            ratchetState: RatchetState.CI_FAILED,
+            ratchetActiveSessionId: 'ratchet-session',
+            ratchetLastCiRunId: 'snapshot-key',
+            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
+            ratchetDispatchOutcome: 'RUNNING',
+            ratchetDispatchRetryCount: 0,
+        };
+        vi.mocked(agentSessionAccessor.findById).mockResolvedValue({
+            id: 'ratchet-session',
+            provider: 'CLAUDE',
+            status: SessionStatus.RUNNING,
+        });
+        vi.mocked(mockSessionBridge.isSessionRunning).mockReturnValue(true);
+        vi.mocked(mockSessionBridge.isSessionWorking).mockReturnValue(false);
+        vi.mocked(mockSessionBridge.stopSession).mockResolvedValue();
+        const result = await unsafeCoerce(ratchetService).checkActiveFixerSession(workspace);
+        expect(result).toEqual({ kind: 'settled', outcome: 'COMPLETED' });
+        expect(workspaceAccessor.recordRatchetSessionEnd).toHaveBeenCalledWith(workspace.id, 'ratchet-session', 'COMPLETED');
+        expect(mockSessionBridge.stopSession).toHaveBeenCalledWith('ratchet-session');
+    });
+    it('decides to trigger fixer when context is actionable', async () => {
+        const decision = await unsafeCoerce(ratchetService).decideRatchetAction({
+            workspace: { id: 'ws-decide', ratchetEnabled: true },
+            prStateInfo: { prState: 'OPEN', ciStatus: CIStatus.FAILURE },
+            isCleanPrWithNoNewReviewActivity: false,
+            activeFixerCheck: { kind: 'none' },
+            dispatchOutcome: null,
+            dispatchRetryCount: 0,
+            hasStateChangedSinceLastDispatch: true,
+        });
+        expect(decision).toEqual({ type: 'TRIGGER_FIXER', retryCount: 0 });
+    });
+    it('waits when CI is not in terminal state (PENDING)', async () => {
+        const decision = await unsafeCoerce(ratchetService).decideRatchetAction({
+            workspace: { id: 'ws-decide', ratchetEnabled: true },
+            prStateInfo: { prState: 'OPEN', ciStatus: CIStatus.PENDING },
+            isCleanPrWithNoNewReviewActivity: false,
+            activeFixerCheck: { kind: 'none' },
+            dispatchOutcome: null,
+            dispatchRetryCount: 0,
+            hasStateChangedSinceLastDispatch: true,
+        });
+        expect(decision).toEqual({
+            type: 'RETURN_ACTION',
+            action: { type: 'WAITING', reason: 'Waiting for CI to complete (not in terminal state)' },
+        });
+    });
+    it('waits when CI is not in terminal state (UNKNOWN)', async () => {
+        const decision = await unsafeCoerce(ratchetService).decideRatchetAction({
+            workspace: { id: 'ws-decide', ratchetEnabled: true },
+            prStateInfo: { prState: 'OPEN', ciStatus: CIStatus.UNKNOWN },
+            isCleanPrWithNoNewReviewActivity: false,
+            activeFixerCheck: { kind: 'none' },
+            dispatchOutcome: null,
+            dispatchRetryCount: 0,
+            hasStateChangedSinceLastDispatch: true,
+        });
+        expect(decision).toEqual({
+            type: 'RETURN_ACTION',
+            action: { type: 'WAITING', reason: 'Waiting for CI to complete (not in terminal state)' },
+        });
+    });
+    it('prefers precomputed review-activity diagnostics from decision context', () => {
+        const workspace = {
+            id: 'ws-log-diag',
+            prUrl: 'https://github.com/example/repo/pull/10',
+            prNumber: 10,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
+            ratchetEnabled: true,
+            ratchetState: RatchetState.READY,
             ratchetActiveSessionId: null,
             ratchetLastCiRunId: 'prev-snapshot',
             prReviewLastCheckedAt: null,
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
         };
         const prStateInfo = {
             ciStatus: CIStatus.SUCCESS,
@@ -756,11 +1204,19 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             prState: 'OPEN',
             prNumber: 10,
         };
-        const logContext = unsafeCoerce(ratchetService).buildRatchetingLogContext(workspace, RatchetState.READY, RatchetState.READY, { type: 'WAITING', reason: 'noop' }, prStateInfo, 10, { hasNewReviewActivitySinceLastDispatch: true });
-        expect(logContext.reviewTimestampComparison.hasNewReviewActivitySinceLastDispatch).toBe(true);
+        const logContext = buildRatchetingLogContext({
+            workspace: workspace,
+            previousState: RatchetState.READY,
+            newState: RatchetState.READY,
+            action: { type: 'WAITING', reason: 'noop' },
+            prStateInfo: prStateInfo,
+            prNumber: 10,
+            decisionContext: { hasNewReviewActivitySinceLastDispatch: true },
+        });
+        expect(logContext.reviewTimestampComparison?.hasNewReviewActivitySinceLastDispatch).toBe(true);
     });
     it('ignores review activity authored by the authenticated user', () => {
-        const latestActivity = unsafeCoerce(ratchetService).computeLatestReviewActivityAtMs({
+        const latestActivity = computeLatestReviewActivityAtMs({
             reviews: [
                 { submittedAt: '2026-01-02T00:00:00Z', author: { login: 'ratchet-bot' } },
                 { submittedAt: '2026-01-01T00:00:00Z', author: { login: 'reviewer' } },
@@ -770,7 +1226,7 @@ describe('ratchet service (state-change + idle dispatch)', () => {
         expect(latestActivity).toBe(new Date('2026-01-01T02:00:00Z').getTime());
     });
     describe('determineRatchetState', () => {
-        const callDetermineRatchetState = (pr) => unsafeCoerce(ratchetService).determineRatchetState(pr);
+        const callDetermineRatchetState = (pr) => determineRatchetState(pr);
         it('returns MERGED for merged PR', () => {
             expect(callDetermineRatchetState({
                 ciStatus: CIStatus.SUCCESS,
@@ -829,7 +1285,7 @@ describe('ratchet service (state-change + idle dispatch)', () => {
         });
     });
     describe('computeDispatchSnapshotKey', () => {
-        const callComputeSnapshotKey = (ciStatus, hasChangesRequested, latestReviewActivityAtMs, statusChecks) => unsafeCoerce(ratchetService).computeDispatchSnapshotKey(ciStatus, hasChangesRequested, latestReviewActivityAtMs, statusChecks);
+        const callComputeSnapshotKey = (ciStatus, hasChangesRequested, latestReviewActivityAtMs, statusChecks) => computeDispatchSnapshotKey(ciStatus, hasChangesRequested, latestReviewActivityAtMs, statusChecks);
         it('includes CI status in key for non-failure states', () => {
             const key = callComputeSnapshotKey(CIStatus.SUCCESS, false, null, null);
             expect(key).toContain('ci:SUCCESS');
@@ -873,7 +1329,7 @@ describe('ratchet service (state-change + idle dispatch)', () => {
         });
     });
     describe('computeLatestReviewActivityAtMs edge cases', () => {
-        const callCompute = (prDetails, reviewComments, authenticatedUsername) => unsafeCoerce(ratchetService).computeLatestReviewActivityAtMs(prDetails, reviewComments, authenticatedUsername);
+        const callCompute = (prDetails, reviewComments, authenticatedUsername) => computeLatestReviewActivityAtMs(prDetails, reviewComments, authenticatedUsername);
         it('returns null when there are no reviews or comments', () => {
             expect(callCompute({ reviews: [], comments: [] }, [], null)).toBeNull();
         });
@@ -916,6 +1372,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 ratchetActiveSessionId: null,
                 ratchetLastCiRunId: null,
                 prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
             };
             vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue(null);
             vi.mocked(workspaceAccessor.update).mockResolvedValue({});
@@ -925,6 +1383,27 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 newState: RatchetState.IDLE,
             });
         });
+        it('returns WAITING action when fetchPRState skips a recent fetch', async () => {
+            const workspace = {
+                id: 'ws-recent-fetch',
+                prUrl: 'https://github.com/example/repo/pull/99',
+                prNumber: 99,
+                ratchetEnabled: true,
+                ratchetState: RatchetState.IDLE,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
+                prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
+            };
+            vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({ skipped: true, reason: 'recently_fetched' });
+            const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
+            expect(result).toMatchObject({
+                action: { type: 'WAITING', reason: 'recently_fetched' },
+                newState: RatchetState.IDLE,
+            });
+            expect(workspaceAccessor.update).not.toHaveBeenCalled();
+        });
         it('returns WAITING when shutting down', async () => {
             unsafeCoerce(ratchetService).isShuttingDown = true;
             const workspace = {
@@ -936,6 +1415,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 ratchetActiveSessionId: null,
                 ratchetLastCiRunId: null,
                 prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
             };
             const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
             expect(result).toMatchObject({
@@ -954,6 +1435,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 ratchetActiveSessionId: null,
                 ratchetLastCiRunId: null,
                 prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
             };
             vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockRejectedValue(new Error('Unexpected explosion'));
             const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
@@ -991,6 +1474,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                     ratchetActiveSessionId: null,
                     ratchetLastCiRunId: null,
                     prReviewLastCheckedAt: null,
+                    ratchetDispatchOutcome: null,
+                    ratchetDispatchRetryCount: 0,
                 },
                 {
                     id: 'ws-fast',
@@ -1005,11 +1490,14 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                     ratchetActiveSessionId: null,
                     ratchetLastCiRunId: null,
                     prReviewLastCheckedAt: null,
+                    ratchetDispatchOutcome: null,
+                    ratchetDispatchRetryCount: 0,
                 },
             ]);
-            vi.spyOn(unsafeCoerce(ratchetService), 'processWorkspace').mockImplementation((workspace) => {
+            vi.spyOn(unsafeCoerce(ratchetService), 'processWorkspace').mockImplementation((workspace, _opts, signal) => {
                 if (workspace.id === 'ws-timeout') {
-                    return new Promise(() => {
+                    return new Promise((_resolve, reject) => {
+                        signal.addEventListener('abort', () => reject(signal.reason), { once: true });
                     });
                 }
                 return Promise.resolve({
@@ -1035,41 +1523,12 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 }),
             ]));
         });
-    });
-    describe('shutdown behavior', () => {
-        it('stops immediately while monitor loop is sleeping', async () => {
-            vi.useFakeTimers();
-            vi.spyOn(ratchetService, 'checkAllWorkspaces').mockResolvedValue({
-                checked: 0,
-                stateChanges: 0,
-                actionsTriggered: 0,
-                results: [],
-            });
-            ratchetService.start();
-            await Promise.resolve();
-            await Promise.resolve();
-            await expect(ratchetService.stop()).resolves.toBeUndefined();
-            vi.useRealTimers();
-        });
-    });
-    describe('checkWorkspaceById', () => {
-        it('returns null when shutting down', async () => {
-            unsafeCoerce(ratchetService).isShuttingDown = true;
-            const result = await ratchetService.checkWorkspaceById('ws-1');
-            expect(result).toBeNull();
-        });
-        it('returns null when workspace not found', async () => {
-            unsafeCoerce(ratchetService).isShuttingDown = false;
-            vi.mocked(workspaceAccessor.findForRatchetById).mockResolvedValue(null);
-            const result = await ratchetService.checkWorkspaceById('ws-nonexistent');
-            expect(result).toBeNull();
-        });
-        it('deduplicates concurrent checks for the same workspace', async () => {
-            unsafeCoerce(ratchetService).isShuttingDown = false;
-            const workspace = {
-                id: 'ws-1',
-                prUrl: 'https://github.com/example/repo/pull/1',
-                prNumber: 1,
+        it('does not count concurrency queue wait toward the workspace timeout', async () => {
+            unsafeCoerce(ratchetService).workspaceCheckTimeoutMs = 5;
+            const workspaces = Array.from({ length: 4 }, (_, index) => ({
+                id: `ws-queued-timeout-${index}`,
+                prUrl: `https://github.com/example/repo/pull/${index + 1}`,
+                prNumber: index + 1,
                 prState: 'OPEN',
                 prCiStatus: CIStatus.UNKNOWN,
                 defaultSessionProvider: 'WORKSPACE_DEFAULT',
@@ -1079,13 +1538,442 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 ratchetActiveSessionId: null,
                 ratchetLastCiRunId: null,
                 prReviewLastCheckedAt: null,
-            };
-            vi.mocked(workspaceAccessor.findForRatchetById).mockResolvedValue(workspace);
-            let releaseCheck;
-            const checkBarrier = new Promise((resolve) => {
-                releaseCheck = () => resolve();
-            });
-            const result = {
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
+            }));
+            vi.mocked(workspaceAccessor.findWithPRsForRatchet).mockResolvedValue(workspaces);
+            const processWorkspaceSpy = vi.spyOn(unsafeCoerce(ratchetService), 'processWorkspace');
+            processWorkspaceSpy.mockImplementation((workspace, _opts, signal) => {
+                if (workspace.id !== 'ws-queued-timeout-3') {
+                    return new Promise((_resolve, reject) => {
+                        signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+                    });
+                }
+                return Promise.resolve({
+                    workspaceId: workspace.id,
+                    previousState: RatchetState.IDLE,
+                    newState: RatchetState.IDLE,
+                    action: { type: 'WAITING', reason: 'ran after queue' },
+                });
+            });
+            const result = await ratchetService.checkAllWorkspaces();
+            expect(processWorkspaceSpy).toHaveBeenCalledWith(expect.objectContaining({ id: 'ws-queued-timeout-3' }), undefined, expect.any(AbortSignal), expect.any(Function));
+            expect(result.results[3]).toMatchObject({
+                workspaceId: 'ws-queued-timeout-3',
+                action: { type: 'WAITING', reason: 'ran after queue' },
+            });
+        });
+        it('lets a committed dispatch finish instead of reporting a timeout error', async () => {
+            unsafeCoerce(ratchetService).workspaceCheckTimeoutMs = 5;
+            const workspace = {
+                id: 'ws-committed-dispatch',
+                prUrl: 'https://github.com/example/repo/pull/1',
+                prNumber: 1,
+                ratchetEnabled: true,
+                ratchetState: RatchetState.IDLE,
+            };
+            vi.mocked(workspaceAccessor.findWithPRsForRatchet).mockResolvedValue([workspace]);
+            let finishCommit;
+            const commitBarrier = new Promise((resolve) => {
+                finishCommit = resolve;
+            });
+            vi.spyOn(unsafeCoerce(ratchetService), 'processWorkspace').mockImplementation(async (workspaceArg, _opts, signal, commitSideEffects) => {
+                commitSideEffects();
+                await commitBarrier;
+                signal.throwIfAborted();
+                return {
+                    workspaceId: workspaceArg.id,
+                    previousState: RatchetState.IDLE,
+                    newState: RatchetState.IDLE,
+                    action: { type: 'TRIGGERED_FIXER', sessionId: 'session-1', promptSent: true },
+                };
+            });
+            const resultPromise = ratchetService.checkAllWorkspaces();
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            finishCommit();
+            const result = await resultPromise;
+            expect(result.results[0]).toMatchObject({
+                workspaceId: workspace.id,
+                action: { type: 'TRIGGERED_FIXER', sessionId: 'session-1' },
+            });
+        });
+        it('runs at most three workspace checks concurrently', async () => {
+            const workspaces = Array.from({ length: 7 }, (_, index) => ({
+                id: `ws-${index}`,
+                prUrl: `https://github.com/example/repo/pull/${index + 1}`,
+                prNumber: index + 1,
+                prState: 'OPEN',
+                prCiStatus: CIStatus.UNKNOWN,
+                defaultSessionProvider: 'WORKSPACE_DEFAULT',
+                ratchetSessionProvider: 'WORKSPACE_DEFAULT',
+                ratchetEnabled: true,
+                ratchetState: RatchetState.IDLE,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
+                prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
+            }));
+            vi.mocked(workspaceAccessor.findWithPRsForRatchet).mockResolvedValue(workspaces);
+            let active = 0;
+            let maximumActive = 0;
+            let releaseChecks;
+            const checkBarrier = new Promise((resolve) => {
+                releaseChecks = resolve;
+            });
+            vi.spyOn(unsafeCoerce(ratchetService), 'processWorkspace').mockImplementation(async (workspace) => {
+                active += 1;
+                maximumActive = Math.max(maximumActive, active);
+                await checkBarrier;
+                active -= 1;
+                return {
+                    workspaceId: workspace.id,
+                    previousState: RatchetState.IDLE,
+                    newState: RatchetState.IDLE,
+                    action: { type: 'WAITING', reason: 'noop' },
+                };
+            });
+            const resultPromise = ratchetService.checkAllWorkspaces();
+            await vi.waitFor(() => expect(active).toBe(3));
+            expect(maximumActive).toBe(3);
+            releaseChecks();
+            const result = await resultPromise;
+            expect(maximumActive).toBe(3);
+            expect(result.checked).toBe(7);
+            expect(result.results).toHaveLength(7);
+        });
+    });
+    describe('shutdown behavior', () => {
+        it('stops immediately while monitor loop is sleeping', async () => {
+            vi.useFakeTimers();
+            vi.spyOn(ratchetService, 'checkAllWorkspaces').mockResolvedValue({
+                checked: 0,
+                stateChanges: 0,
+                actionsTriggered: 0,
+                results: [],
+            });
+            ratchetService.start();
+            await Promise.resolve();
+            await Promise.resolve();
+            await expect(ratchetService.stop()).resolves.toBeUndefined();
+            vi.useRealTimers();
+        });
+    });
+    describe('markPrClosed', () => {
+        afterEach(() => {
+            ratchetService.removeAllListeners();
+        });
+        it('resets ratchet state to IDLE via CAS on fromState and emits a state change', async () => {
+            vi.mocked(workspaceAccessor.findById).mockResolvedValue({
+                id: 'ws-closed',
+                ratchetEnabled: true,
+                ratchetState: RatchetState.CI_FAILED,
+            });
+            vi.mocked(workspaceAccessor.transitionRatchetStateIfEnabled).mockResolvedValue(true);
+            const stateEvents = [];
+            ratchetService.on(RATCHET_STATE_CHANGED, (event) => {
+                stateEvents.push(event);
+            });
+            await ratchetService.markPrClosed('ws-closed');
+            expect(workspaceAccessor.transitionRatchetStateIfEnabled).toHaveBeenCalledWith('ws-closed', RatchetState.CI_FAILED, {
+                ratchetState: RatchetState.IDLE,
+                ratchetLastCheckedAt: expect.any(Date),
+            });
+            expect(stateEvents).toEqual([
+                {
+                    workspaceId: 'ws-closed',
+                    fromState: RatchetState.CI_FAILED,
+                    toState: RatchetState.IDLE,
+                },
+            ]);
+        });
+        it('emits the fromState that actually won the compare-and-swap after losing a race', async () => {
+            vi.mocked(workspaceAccessor.findById)
+                .mockResolvedValueOnce({
+                id: 'ws-closed',
+                ratchetEnabled: true,
+                ratchetState: RatchetState.CI_FAILED,
+            })
+                .mockResolvedValueOnce({
+                id: 'ws-closed',
+                ratchetEnabled: true,
+                ratchetState: RatchetState.CI_RUNNING,
+            });
+            vi.mocked(workspaceAccessor.transitionRatchetStateIfEnabled)
+                .mockResolvedValueOnce(false)
+                .mockResolvedValueOnce(true);
+            const stateEvents = [];
+            ratchetService.on(RATCHET_STATE_CHANGED, (event) => {
+                stateEvents.push(event);
+            });
+            await ratchetService.markPrClosed('ws-closed');
+            expect(workspaceAccessor.transitionRatchetStateIfEnabled).toHaveBeenNthCalledWith(1, 'ws-closed', RatchetState.CI_FAILED, expect.objectContaining({ ratchetState: RatchetState.IDLE }));
+            expect(workspaceAccessor.transitionRatchetStateIfEnabled).toHaveBeenNthCalledWith(2, 'ws-closed', RatchetState.CI_RUNNING, expect.objectContaining({ ratchetState: RatchetState.IDLE }));
+            expect(stateEvents).toEqual([
+                {
+                    workspaceId: 'ws-closed',
+                    fromState: RatchetState.CI_RUNNING,
+                    toState: RatchetState.IDLE,
+                },
+            ]);
+        });
+        it('is a no-op when ratchet state is already IDLE', async () => {
+            vi.mocked(workspaceAccessor.findById).mockResolvedValue({
+                id: 'ws-closed',
+                ratchetEnabled: true,
+                ratchetState: RatchetState.IDLE,
+            });
+            await ratchetService.markPrClosed('ws-closed');
+            expect(workspaceAccessor.transitionRatchetStateIfEnabled).not.toHaveBeenCalled();
+        });
+        it('does not emit when ratcheting was disabled concurrently', async () => {
+            vi.mocked(workspaceAccessor.findById)
+                .mockResolvedValueOnce({
+                id: 'ws-closed',
+                ratchetEnabled: true,
+                ratchetState: RatchetState.CI_FAILED,
+            })
+                .mockResolvedValueOnce({
+                id: 'ws-closed',
+                ratchetEnabled: false,
+                ratchetState: RatchetState.IDLE,
+            });
+            vi.mocked(workspaceAccessor.transitionRatchetStateIfEnabled).mockResolvedValue(false);
+            const stateEvents = [];
+            ratchetService.on(RATCHET_STATE_CHANGED, (event) => {
+                stateEvents.push(event);
+            });
+            await ratchetService.markPrClosed('ws-closed');
+            expect(stateEvents).toEqual([]);
+        });
+        it('is a no-op when workspace is not found', async () => {
+            vi.mocked(workspaceAccessor.findById).mockResolvedValue(null);
+            await ratchetService.markPrClosed('ws-missing');
+            expect(workspaceAccessor.transitionRatchetStateIfEnabled).not.toHaveBeenCalled();
+        });
+        it('does not continue to side effects after a timed-out await completes', async () => {
+            unsafeCoerce(ratchetService).workspaceCheckTimeoutMs = 5;
+            const workspace = {
+                id: 'ws-zombie',
+                prUrl: 'https://github.com/example/repo/pull/1',
+                prNumber: 1,
+                prState: 'OPEN',
+                prCiStatus: CIStatus.FAILURE,
+                defaultSessionProvider: 'WORKSPACE_DEFAULT',
+                ratchetSessionProvider: 'WORKSPACE_DEFAULT',
+                ratchetEnabled: true,
+                ratchetState: RatchetState.IDLE,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
+                prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
+            };
+            vi.mocked(workspaceAccessor.findWithPRsForRatchet).mockResolvedValue([workspace]);
+            let releaseFetch;
+            const fetchBarrier = new Promise((resolve) => {
+                releaseFetch = resolve;
+            });
+            const finishSpy = vi.spyOn(unsafeCoerce(ratchetService), 'finishRatchetCheck');
+            vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockImplementation(async () => {
+                await fetchBarrier;
+                return {
+                    ciStatus: CIStatus.FAILURE,
+                    snapshotKey: 'failed:1',
+                    hasChangesRequested: false,
+                    hasMergeConflict: false,
+                    latestReviewActivityAtMs: null,
+                    statusCheckRollup: [],
+                    prState: 'OPEN',
+                    prNumber: 1,
+                    reviewComments: [],
+                };
+            });
+            const result = await ratchetService.checkAllWorkspaces();
+            expect(result.results[0]?.action.type).toBe('ERROR');
+            releaseFetch();
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            expect(finishSpy).not.toHaveBeenCalled();
+            expect(workspaceAccessor.transitionRatchetStateIfEnabled).not.toHaveBeenCalled();
+        });
+    });
+    describe('checkWorkspaceById', () => {
+        it('returns null when shutting down', async () => {
+            unsafeCoerce(ratchetService).isShuttingDown = true;
+            const result = await ratchetService.checkWorkspaceById('ws-1');
+            expect(result).toBeNull();
+        });
+        it('returns null when workspace not found', async () => {
+            unsafeCoerce(ratchetService).isShuttingDown = false;
+            vi.mocked(workspaceAccessor.findForRatchetById).mockResolvedValue(null);
+            const result = await ratchetService.checkWorkspaceById('ws-nonexistent');
+            expect(result).toBeNull();
+        });
+        it('skips the PR fetch when the workspace was recently fetched', async () => {
+            const workspace = {
+                id: 'ws-cooldown',
+                prUrl: 'https://github.com/example/repo/pull/9',
+                prNumber: 9,
+                prState: 'OPEN',
+                prCiStatus: CIStatus.UNKNOWN,
+                ratchetEnabled: true,
+                ratchetState: RatchetState.CI_RUNNING,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
+                prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
+            };
+            vi.mocked(workspaceAccessor.findForRatchetById).mockResolvedValue(workspace);
+            vi.mocked(mockGitHubBridge.extractPRInfo).mockReturnValue({
+                owner: 'example',
+                repo: 'repo',
+                number: 9,
+            });
+            vi.mocked(mockGitHubBridge.isRecentlyFetched).mockReturnValue(true);
+            const result = await ratchetService.checkWorkspaceById('ws-cooldown');
+            expect(result?.action).toEqual({ type: 'WAITING', reason: 'recently_fetched' });
+            expect(mockGitHubBridge.getPRFullDetails).not.toHaveBeenCalled();
+        });
+        it('bypasses the PR fetch cooldown when requested by an event-driven check', async () => {
+            const workspace = {
+                id: 'ws-bypass',
+                prUrl: 'https://github.com/example/repo/pull/9',
+                prNumber: 9,
+                prState: 'OPEN',
+                prCiStatus: CIStatus.UNKNOWN,
+                defaultSessionProvider: 'WORKSPACE_DEFAULT',
+                ratchetSessionProvider: 'WORKSPACE_DEFAULT',
+                ratchetEnabled: true,
+                ratchetState: RatchetState.CI_RUNNING,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
+                prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
+            };
+            vi.mocked(workspaceAccessor.findForRatchetById).mockResolvedValue(workspace);
+            vi.mocked(mockGitHubBridge.extractPRInfo).mockReturnValue({
+                owner: 'example',
+                repo: 'repo',
+                number: 9,
+            });
+            vi.mocked(mockGitHubBridge.isRecentlyFetched).mockReturnValue(true);
+            vi.mocked(mockGitHubBridge.getPRFullDetails).mockResolvedValue({
+                state: 'OPEN',
+                number: 9,
+                url: 'https://github.com/example/repo/pull/9',
+                reviewDecision: null,
+                mergeStateStatus: 'CLEAN',
+                reviews: [],
+                comments: [],
+                statusCheckRollup: null,
+            });
+            vi.mocked(mockGitHubBridge.getReviewComments).mockResolvedValue([]);
+            vi.mocked(mockGitHubBridge.computeCIStatus).mockReturnValue(CIStatus.SUCCESS);
+            const result = await ratchetService.checkWorkspaceById('ws-bypass', {
+                bypassPrFetchCooldown: true,
+            });
+            expect(mockGitHubBridge.getPRFullDetails).toHaveBeenCalledWith('example/repo', 9, expect.any(AbortSignal));
+            expect(result?.newState).toBe(RatchetState.READY);
+            expect(result?.action).not.toEqual({ type: 'WAITING', reason: 'recently_fetched' });
+        });
+        it('reruns a bypassed check once when the first attempt was dedup-skipped', async () => {
+            const workspace = {
+                id: 'ws-rerun',
+                prUrl: 'https://github.com/example/repo/pull/9',
+                prNumber: 9,
+                prState: 'OPEN',
+                prCiStatus: CIStatus.UNKNOWN,
+                defaultSessionProvider: 'WORKSPACE_DEFAULT',
+                ratchetSessionProvider: 'WORKSPACE_DEFAULT',
+                ratchetEnabled: true,
+                ratchetState: RatchetState.CI_RUNNING,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
+                prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
+            };
+            vi.mocked(workspaceAccessor.findForRatchetById).mockResolvedValue(workspace);
+            vi.mocked(mockGitHubBridge.extractPRInfo).mockReturnValue({
+                owner: 'example',
+                repo: 'repo',
+                number: 9,
+            });
+            vi.mocked(mockGitHubBridge.isFetchInFlight).mockReturnValueOnce(true).mockReturnValue(false);
+            vi.mocked(mockGitHubBridge.getPRFullDetails).mockResolvedValue({
+                state: 'OPEN',
+                number: 9,
+                url: 'https://github.com/example/repo/pull/9',
+                reviewDecision: null,
+                mergeStateStatus: 'CLEAN',
+                reviews: [],
+                comments: [],
+                statusCheckRollup: null,
+            });
+            vi.mocked(mockGitHubBridge.getReviewComments).mockResolvedValue([]);
+            vi.mocked(mockGitHubBridge.computeCIStatus).mockReturnValue(CIStatus.SUCCESS);
+            const result = await ratchetService.checkWorkspaceById('ws-rerun', {
+                bypassPrFetchCooldown: true,
+            });
+            expect(mockGitHubBridge.getPRFullDetails).toHaveBeenCalledTimes(1);
+            expect(result?.newState).toBe(RatchetState.READY);
+            expect(result?.action).not.toEqual({ type: 'WAITING', reason: 'recently_fetched' });
+        });
+        it('does not rerun a bypassed check more than once', async () => {
+            const workspace = {
+                id: 'ws-rerun-cap',
+                prUrl: 'https://github.com/example/repo/pull/9',
+                prNumber: 9,
+                prState: 'OPEN',
+                prCiStatus: CIStatus.UNKNOWN,
+                ratchetEnabled: true,
+                ratchetState: RatchetState.CI_RUNNING,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
+                prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
+            };
+            vi.mocked(workspaceAccessor.findForRatchetById).mockResolvedValue(workspace);
+            vi.mocked(mockGitHubBridge.extractPRInfo).mockReturnValue({
+                owner: 'example',
+                repo: 'repo',
+                number: 9,
+            });
+            vi.mocked(mockGitHubBridge.isFetchInFlight).mockReturnValue(true);
+            const result = await ratchetService.checkWorkspaceById('ws-rerun-cap', {
+                bypassPrFetchCooldown: true,
+            });
+            expect(result?.action).toEqual({ type: 'WAITING', reason: 'recently_fetched' });
+            expect(mockGitHubBridge.isFetchInFlight).toHaveBeenCalledTimes(2);
+            expect(mockGitHubBridge.getPRFullDetails).not.toHaveBeenCalled();
+        });
+        it('deduplicates concurrent checks for the same workspace', async () => {
+            unsafeCoerce(ratchetService).isShuttingDown = false;
+            const workspace = {
+                id: 'ws-1',
+                prUrl: 'https://github.com/example/repo/pull/1',
+                prNumber: 1,
+                prState: 'OPEN',
+                prCiStatus: CIStatus.UNKNOWN,
+                defaultSessionProvider: 'WORKSPACE_DEFAULT',
+                ratchetSessionProvider: 'WORKSPACE_DEFAULT',
+                ratchetEnabled: true,
+                ratchetState: RatchetState.IDLE,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
+                prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
+            };
+            vi.mocked(workspaceAccessor.findForRatchetById).mockResolvedValue(workspace);
+            let releaseCheck;
+            const checkBarrier = new Promise((resolve) => {
+                releaseCheck = () => resolve();
+            });
+            const result = {
                 workspaceId: 'ws-1',
                 previousState: RatchetState.IDLE,
                 newState: RatchetState.IDLE,
@@ -1099,7 +1987,7 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             });
             const first = ratchetService.checkWorkspaceById('ws-1');
             const second = ratchetService.checkWorkspaceById('ws-1');
-            await Promise.resolve();
+            await vi.waitFor(() => expect(processWorkspaceSpy).toHaveBeenCalledTimes(1));
             expect(processWorkspaceSpy).toHaveBeenCalledTimes(1);
             releaseCheck();
             const [firstResult, secondResult] = await Promise.all([first, second]);
@@ -1107,311 +1995,416 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             expect(secondResult).toEqual(result);
             expect(processWorkspaceSpy).toHaveBeenCalledTimes(1);
         });
+        it('deduplicates a same-workspace check before it enters the concurrency queue', async () => {
+            const makeWorkspace = (id) => ({
+                id,
+                prUrl: `https://github.com/example/repo/pull/${id}`,
+                prNumber: 1,
+                ratchetEnabled: true,
+                ratchetState: RatchetState.IDLE,
+            });
+            const workspaces = [
+                makeWorkspace('blocker-1'),
+                makeWorkspace('blocker-2'),
+                makeWorkspace('blocker-3'),
+                makeWorkspace('queued-target'),
+            ];
+            vi.mocked(workspaceAccessor.findWithPRsForRatchet).mockResolvedValue(workspaces);
+            vi.mocked(workspaceAccessor.findForRatchetById).mockResolvedValue(workspaces[3]);
+            let releaseBlockers;
+            const blockerBarrier = new Promise((resolve) => {
+                releaseBlockers = resolve;
+            });
+            let activeBlockers = 0;
+            let targetRuns = 0;
+            vi.spyOn(unsafeCoerce(ratchetService), 'processWorkspace').mockImplementation(async (workspace) => {
+                if (workspace.id.startsWith('blocker-')) {
+                    activeBlockers += 1;
+                    await blockerBarrier;
+                }
+                else {
+                    targetRuns += 1;
+                }
+                return {
+                    workspaceId: workspace.id,
+                    previousState: RatchetState.IDLE,
+                    newState: RatchetState.IDLE,
+                    action: { type: 'WAITING', reason: 'noop' },
+                };
+            });
+            const batch = ratchetService.checkAllWorkspaces();
+            await vi.waitFor(() => expect(activeBlockers).toBe(3));
+            const direct = ratchetService.checkWorkspaceById('queued-target');
+            await Promise.resolve();
+            expect(targetRuns).toBe(0);
+            releaseBlockers();
+            const [batchResult, directResult] = await Promise.all([batch, direct]);
+            expect(targetRuns).toBe(1);
+            expect(directResult).toEqual(batchResult.results[3]);
+        });
+        it('keeps a limiter slot occupied until a timed-out runner finishes cleanup', async () => {
+            unsafeCoerce(ratchetService).workspaceCheckTimeoutMs = 5;
+            const makeWorkspace = (id) => ({
+                id,
+                prUrl: `https://github.com/example/repo/pull/${id}`,
+                prNumber: 1,
+                ratchetEnabled: true,
+                ratchetState: RatchetState.IDLE,
+            });
+            const workspaces = [
+                makeWorkspace('timed-out-1'),
+                makeWorkspace('timed-out-2'),
+                makeWorkspace('timed-out-3'),
+                makeWorkspace('after-timeouts'),
+            ];
+            vi.mocked(workspaceAccessor.findWithPRsForRatchet).mockResolvedValue(workspaces);
+            let finishCleanup;
+            const cleanupBarrier = new Promise((resolve) => {
+                finishCleanup = resolve;
+            });
+            let activeTimedOutChecks = 0;
+            let targetRuns = 0;
+            vi.spyOn(unsafeCoerce(ratchetService), 'processWorkspace').mockImplementation(async (workspace, _opts, signal) => {
+                if (workspace.id.startsWith('timed-out-')) {
+                    activeTimedOutChecks += 1;
+                    await new Promise((resolve) => {
+                        signal.addEventListener('abort', () => resolve(), { once: true });
+                    });
+                    await cleanupBarrier;
+                    signal.throwIfAborted();
+                }
+                targetRuns += workspace.id === 'after-timeouts' ? 1 : 0;
+                return {
+                    workspaceId: workspace.id,
+                    previousState: RatchetState.IDLE,
+                    newState: RatchetState.IDLE,
+                    action: { type: 'WAITING', reason: 'noop' },
+                };
+            });
+            const batch = ratchetService.checkAllWorkspaces();
+            await vi.waitFor(() => expect(activeTimedOutChecks).toBe(3));
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            expect(targetRuns).toBe(0);
+            finishCleanup();
+            await batch;
+            expect(targetRuns).toBe(1);
+        });
+        it('runs a direct workspace check without waiting for the batch limiter', async () => {
+            const makeWorkspace = (id) => ({
+                id,
+                prUrl: `https://github.com/example/repo/pull/${id}`,
+                prNumber: 1,
+                ratchetEnabled: true,
+                ratchetState: RatchetState.IDLE,
+            });
+            const batchWorkspaces = [
+                makeWorkspace('batch-blocker-1'),
+                makeWorkspace('batch-blocker-2'),
+                makeWorkspace('batch-blocker-3'),
+            ];
+            const directWorkspace = makeWorkspace('direct-target');
+            vi.mocked(workspaceAccessor.findWithPRsForRatchet).mockResolvedValue(batchWorkspaces);
+            vi.mocked(workspaceAccessor.findForRatchetById).mockResolvedValue(directWorkspace);
+            let releaseBatch;
+            const batchBarrier = new Promise((resolve) => {
+                releaseBatch = resolve;
+            });
+            let activeBatchChecks = 0;
+            let directRuns = 0;
+            vi.spyOn(unsafeCoerce(ratchetService), 'processWorkspace').mockImplementation(async (workspace) => {
+                if (workspace.id.startsWith('batch-blocker-')) {
+                    activeBatchChecks += 1;
+                    await batchBarrier;
+                }
+                else {
+                    directRuns += 1;
+                }
+                return {
+                    workspaceId: workspace.id,
+                    previousState: RatchetState.IDLE,
+                    newState: RatchetState.IDLE,
+                    action: { type: 'WAITING', reason: 'noop' },
+                };
+            });
+            const batch = ratchetService.checkAllWorkspaces();
+            await vi.waitFor(() => expect(activeBatchChecks).toBe(3));
+            const directResult = await ratchetService.checkWorkspaceById(directWorkspace.id);
+            expect(directRuns).toBe(1);
+            expect(directResult?.workspaceId).toBe(directWorkspace.id);
+            releaseBatch();
+            await batch;
+        });
     });
     describe('decideRatchetAction edge cases', () => {
         const callDecide = (context) => unsafeCoerce(ratchetService).decideRatchetAction(context);
-        it('returns COMPLETED for merged PR', () => {
-            expect(callDecide({
-                workspace: { ratchetEnabled: true },
+        const arrangeOtherWorkingSession = () => {
+            vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([
+                { id: 'other-session' },
+            ]);
+            vi.mocked(mockSessionBridge.isSessionWorking).mockReturnValue(true);
+        };
+        it('returns COMPLETED for merged PR', async () => {
+            expect(await callDecide({
+                workspace: { id: 'ws-decide', ratchetEnabled: true },
                 prStateInfo: { prState: 'MERGED', ciStatus: CIStatus.SUCCESS },
                 isCleanPrWithNoNewReviewActivity: false,
-                activeRatchetSession: null,
+                activeFixerCheck: { kind: 'none' },
+                dispatchOutcome: null,
+                dispatchRetryCount: 0,
                 hasStateChangedSinceLastDispatch: true,
-                hasOtherActiveSession: false,
             })).toEqual({ type: 'RETURN_ACTION', action: { type: 'COMPLETED' } });
         });
-        it('returns WAITING for non-open PR', () => {
-            const result = callDecide({
-                workspace: { ratchetEnabled: true },
+        it('returns WAITING for non-open PR', async () => {
+            const result = (await callDecide({
+                workspace: { id: 'ws-decide', ratchetEnabled: true },
                 prStateInfo: { prState: 'CLOSED', ciStatus: CIStatus.SUCCESS },
                 isCleanPrWithNoNewReviewActivity: false,
-                activeRatchetSession: null,
+                activeFixerCheck: { kind: 'none' },
+                dispatchOutcome: null,
+                dispatchRetryCount: 0,
                 hasStateChangedSinceLastDispatch: true,
-                hasOtherActiveSession: false,
-            });
+            }));
             expect(result.action?.reason).toBe('PR is not open');
         });
-        it('returns active session when one exists', () => {
+        it('returns active session when one exists', async () => {
             const activeSession = { type: 'FIXER_ACTIVE', sessionId: 's-1' };
-            const result = callDecide({
-                workspace: { ratchetEnabled: true },
+            const result = (await callDecide({
+                workspace: { id: 'ws-decide', ratchetEnabled: true },
                 prStateInfo: { prState: 'OPEN', ciStatus: CIStatus.FAILURE },
                 isCleanPrWithNoNewReviewActivity: false,
-                activeRatchetSession: activeSession,
+                activeFixerCheck: { kind: 'active', action: activeSession },
+                dispatchOutcome: 'RUNNING',
+                dispatchRetryCount: 0,
                 hasStateChangedSinceLastDispatch: true,
-                hasOtherActiveSession: false,
-            });
+            }));
             expect(result.action).toEqual(activeSession);
         });
-        it('returns WAITING when other active session blocks dispatch', () => {
-            const result = callDecide({
-                workspace: { ratchetEnabled: true },
+        it('returns WAITING when other active session blocks dispatch', async () => {
+            arrangeOtherWorkingSession();
+            const result = (await callDecide({
+                workspace: { id: 'ws-decide', ratchetEnabled: true },
                 prStateInfo: { prState: 'OPEN', ciStatus: CIStatus.FAILURE },
                 isCleanPrWithNoNewReviewActivity: false,
-                activeRatchetSession: null,
+                activeFixerCheck: { kind: 'none' },
+                dispatchOutcome: null,
+                dispatchRetryCount: 0,
                 hasStateChangedSinceLastDispatch: true,
-                hasOtherActiveSession: true,
-            });
+            }));
             expect(result.action?.reason).toBe('Workspace has another working session');
         });
-        it('returns WAITING when there are no CI failures or PR review comments', () => {
-            const result = callDecide({
-                workspace: { ratchetEnabled: true },
+        it('returns WAITING when there are no CI failures or PR review comments', async () => {
+            const result = (await callDecide({
+                workspace: { id: 'ws-decide', ratchetEnabled: true },
                 prStateInfo: {
                     prState: 'OPEN',
                     ciStatus: CIStatus.SUCCESS,
                     reviewComments: [],
                 },
                 isCleanPrWithNoNewReviewActivity: false,
-                activeRatchetSession: null,
+                activeFixerCheck: { kind: 'none' },
+                dispatchOutcome: null,
+                dispatchRetryCount: 0,
                 hasStateChangedSinceLastDispatch: true,
-                hasOtherActiveSession: false,
-            });
+            }));
             expect(result.action?.reason).toBe('No CI failures or PR review comments to address');
         });
-    });
-    describe('getActiveRatchetSession edge cases', () => {
-        const callGetActiveRatchetSession = (workspace) => unsafeCoerce(ratchetService).getActiveRatchetSession(workspace);
-        it('returns null when ratchetActiveSessionId is null', async () => {
-            const result = await callGetActiveRatchetSession({
-                id: 'ws-1',
-                ratchetActiveSessionId: null,
+        it('waits when the fixer ended concurrently during the check', async () => {
+            const result = (await callDecide({
+                workspace: { id: 'ws-decide', ratchetEnabled: true },
+                prStateInfo: { prState: 'OPEN', ciStatus: CIStatus.FAILURE },
+                isCleanPrWithNoNewReviewActivity: false,
+                activeFixerCheck: { kind: 'ended_concurrently' },
+                dispatchOutcome: 'COMPLETED',
+                dispatchRetryCount: 0,
+                hasStateChangedSinceLastDispatch: false,
+            }));
+            expect(result.action?.reason).toBe('Fixer session ended during this check; re-evaluating next cycle');
+        });
+        it('retries a died fixer ahead of the unchanged-state gate', async () => {
+            const result = await callDecide({
+                workspace: { id: 'ws-decide', ratchetEnabled: true },
+                prStateInfo: { prState: 'OPEN', ciStatus: CIStatus.FAILURE },
+                isCleanPrWithNoNewReviewActivity: false,
+                activeFixerCheck: { kind: 'settled', outcome: 'DIED' },
+                dispatchOutcome: 'DIED',
+                dispatchRetryCount: 2,
+                hasStateChangedSinceLastDispatch: false,
             });
-            expect(result).toBeNull();
+            expect(result).toEqual({ type: 'TRIGGER_FIXER', retryCount: 3 });
         });
-        it('returns null and resets dispatch tracking when session DB record is missing', async () => {
-            vi.mocked(agentSessionAccessor.findById).mockResolvedValue(null);
-            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-            vi.mocked(mockSnapshotBridge.recordReviewCheck).mockResolvedValue();
-            const result = await callGetActiveRatchetSession({
-                id: 'ws-2',
-                ratchetActiveSessionId: 'gone-session',
-            });
-            expect(result).toBeNull();
-            expect(workspaceAccessor.update).toHaveBeenCalledWith('ws-2', {
+        it('does not retry a died fixer while another session is working', async () => {
+            arrangeOtherWorkingSession();
+            const result = (await callDecide({
+                workspace: { id: 'ws-decide', ratchetEnabled: true },
+                prStateInfo: { prState: 'OPEN', ciStatus: CIStatus.FAILURE },
+                isCleanPrWithNoNewReviewActivity: false,
+                activeFixerCheck: { kind: 'settled', outcome: 'DIED' },
+                dispatchOutcome: 'DIED',
+                dispatchRetryCount: 0,
+                hasStateChangedSinceLastDispatch: false,
+            }));
+            expect(result.action?.reason).toBe('Workspace has another working session');
+        });
+        it('gives up on a died fixer once the retry budget is spent', async () => {
+            const result = (await callDecide({
+                workspace: { id: 'ws-decide', ratchetEnabled: true },
+                prStateInfo: { prState: 'OPEN', ciStatus: CIStatus.FAILURE },
+                isCleanPrWithNoNewReviewActivity: false,
+                activeFixerCheck: { kind: 'none' },
+                dispatchOutcome: 'DIED',
+                dispatchRetryCount: 3,
+                hasStateChangedSinceLastDispatch: false,
+            }));
+            expect(result.action?.reason).toBe('Fixer died 4 times for this PR state; waiting for PR state to change');
+        });
+    });
+    describe('checkActiveFixerSession edge cases', () => {
+        const callCheckActiveFixerSession = (workspace) => unsafeCoerce(ratchetService).checkActiveFixerSession(workspace);
+        it('returns none when ratchetActiveSessionId is null', async () => {
+            const result = await callCheckActiveFixerSession({
+                id: 'ws-1',
                 ratchetActiveSessionId: null,
-                ratchetLastCiRunId: null,
             });
-            expect(mockSnapshotBridge.recordReviewCheck).toHaveBeenCalledWith('ws-2', null);
+            expect(result).toEqual({ kind: 'none' });
         });
-        it('returns null and resets dispatch tracking when session is not RUNNING', async () => {
+        it('settles a non-RUNNING session as COMPLETED when its status is not FAILED', async () => {
             vi.mocked(agentSessionAccessor.findById).mockResolvedValue({
                 id: 'completed-session',
                 provider: 'CLAUDE',
                 status: SessionStatus.IDLE,
             });
-            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-            vi.mocked(mockSnapshotBridge.recordReviewCheck).mockResolvedValue();
-            const result = await callGetActiveRatchetSession({
+            const result = await callCheckActiveFixerSession({
                 id: 'ws-3',
                 ratchetActiveSessionId: 'completed-session',
             });
-            expect(result).toBeNull();
-            expect(workspaceAccessor.update).toHaveBeenCalledWith('ws-3', {
-                ratchetActiveSessionId: null,
-                ratchetLastCiRunId: null,
-            });
-            expect(mockSnapshotBridge.recordReviewCheck).toHaveBeenCalledWith('ws-3', null);
+            expect(result).toEqual({ kind: 'settled', outcome: 'COMPLETED' });
+            expect(workspaceAccessor.recordRatchetSessionEnd).toHaveBeenCalledWith('ws-3', 'completed-session', 'COMPLETED');
         });
-    });
-    describe('review comment polling', () => {
-        const cleanWorkspace = {
-            id: 'ws-poll',
-            prUrl: 'https://github.com/example/repo/pull/100',
-            prNumber: 100,
-            prState: 'OPEN',
-            prCiStatus: CIStatus.UNKNOWN,
-            ratchetEnabled: true,
-            ratchetState: RatchetState.READY,
-            ratchetActiveSessionId: null,
-            ratchetLastCiRunId: 'old-snapshot',
-            prReviewLastCheckedAt: new Date(),
-        };
-        const cleanPrState = {
-            ciStatus: CIStatus.SUCCESS,
-            snapshotKey: 'new-snapshot',
-            hasChangesRequested: false,
-            latestReviewActivityAtMs: new Date('2026-01-01T00:00:00Z').getTime(),
-            statusCheckRollup: null,
-            prState: 'OPEN',
-            prNumber: 100,
-            reviewComments: [],
-        };
-        const prStateWithComments = {
-            ...cleanPrState,
-            snapshotKey: 'snapshot-with-comments',
-            hasChangesRequested: true,
-            latestReviewActivityAtMs: new Date('2026-01-03T00:00:00Z').getTime(),
-            reviewComments: [
-                {
-                    author: 'reviewer',
-                    body: 'Please update this line',
-                    path: 'src/file.ts',
-                    line: 21,
-                    url: 'https://github.com/example/repo/pull/100#discussion_r2',
-                },
-            ],
-        };
-        const getTrackers = () => unsafeCoerce(ratchetService).reviewPollTrackers;
-        const callProcessWorkspace = (workspace) => unsafeCoerce(ratchetService).processWorkspace(workspace);
-        it('creates tracker when PR is first seen as clean with state change', async () => {
-            vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue(cleanPrState);
-            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-            vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
-            const result = await callProcessWorkspace(cleanWorkspace);
-            expect(result.action.type).toBe('WAITING');
-            expect(getTrackers().has('ws-poll')).toBe(true);
-            expect(getTrackers().get('ws-poll')?.snapshotKey).toBe('new-snapshot');
-            expect(getTrackers().get('ws-poll')?.pollCount).toBe(0);
-        });
-        it('creates tracker even when state has not changed (continuous polling)', async () => {
-            const workspace = { ...cleanWorkspace, ratchetLastCiRunId: 'new-snapshot' };
-            vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue(cleanPrState);
-            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-            vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
-            await callProcessWorkspace(workspace);
-            expect(getTrackers().has('ws-poll')).toBe(true);
-            expect(getTrackers().get('ws-poll')?.pollCount).toBe(0);
-        });
-        it('skips re-poll when not enough time has elapsed', async () => {
-            getTrackers().set('ws-poll', {
-                snapshotKey: 'new-snapshot',
-                lastPolledAt: Date.now(),
-                pollCount: 0,
-            });
-            const fetchSpy = vi
-                .spyOn(unsafeCoerce(ratchetService), 'fetchPRState')
-                .mockResolvedValue(cleanPrState);
-            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-            vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
-            await callProcessWorkspace(cleanWorkspace);
-            expect(fetchSpy).toHaveBeenCalledTimes(1);
-            expect(getTrackers().get('ws-poll')?.pollCount).toBe(0);
-        });
-        it('re-polls and finds comments when time has elapsed', async () => {
-            getTrackers().set('ws-poll', {
-                snapshotKey: 'new-snapshot',
-                lastPolledAt: Date.now() - 3 * 60_000,
-                pollCount: 0,
-            });
-            const fetchSpy = vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState');
-            fetchSpy.mockResolvedValueOnce(cleanPrState);
-            fetchSpy.mockResolvedValueOnce(prStateWithComments);
-            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-            vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
-            vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
-                status: 'started',
-                sessionId: 'ratchet-poll-session',
-                promptSent: true,
+        it('settles a FAILED session as DIED', async () => {
+            vi.mocked(agentSessionAccessor.findById).mockResolvedValue({
+                id: 'failed-session',
+                provider: 'CLAUDE',
+                status: SessionStatus.FAILED,
             });
-            const result = await callProcessWorkspace(cleanWorkspace);
-            expect(fetchSpy).toHaveBeenCalledTimes(2);
-            expect(result.action.type).toBe('TRIGGERED_FIXER');
-            expect(getTrackers().has('ws-poll')).toBe(false);
-        });
-        it('increments pollCount when re-poll still finds clean PR', async () => {
-            getTrackers().set('ws-poll', {
-                snapshotKey: 'new-snapshot',
-                lastPolledAt: Date.now() - 3 * 60_000,
-                pollCount: 0,
+            const result = await callCheckActiveFixerSession({
+                id: 'ws-4',
+                ratchetActiveSessionId: 'failed-session',
             });
-            const fetchSpy = vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState');
-            fetchSpy.mockResolvedValue(cleanPrState);
-            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-            vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
-            await callProcessWorkspace(cleanWorkspace);
-            expect(fetchSpy).toHaveBeenCalledTimes(2);
-            expect(getTrackers().get('ws-poll')?.pollCount).toBe(1);
-        });
-        it('continues polling after many cycles without exhausting', async () => {
-            getTrackers().set('ws-poll', {
-                snapshotKey: 'new-snapshot',
-                lastPolledAt: Date.now() - 3 * 60_000,
-                pollCount: 50,
-            });
-            const fetchSpy = vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState');
-            fetchSpy.mockResolvedValue(cleanPrState);
-            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-            vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
-            await callProcessWorkspace(cleanWorkspace);
-            expect(fetchSpy).toHaveBeenCalledTimes(2);
-            expect(getTrackers().get('ws-poll')?.pollCount).toBe(51);
+            expect(result).toEqual({ kind: 'settled', outcome: 'DIED' });
+            expect(workspaceAccessor.recordRatchetSessionEnd).toHaveBeenCalledWith('ws-4', 'failed-session', 'DIED');
         });
-        it('resets tracker when snapshotKey changes', async () => {
-            getTrackers().set('ws-poll', {
-                snapshotKey: 'different-snapshot',
-                lastPolledAt: Date.now() - 10 * 60_000,
-                pollCount: 3,
+        it('settles a provider-mismatched session as DIED and stops it', async () => {
+            vi.mocked(agentSessionAccessor.findById).mockResolvedValue({
+                id: 'codex-session',
+                provider: 'CODEX',
+                status: SessionStatus.RUNNING,
             });
-            vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue(cleanPrState);
-            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-            vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
-            await callProcessWorkspace(cleanWorkspace);
-            const tracker = getTrackers().get('ws-poll');
-            expect(tracker?.snapshotKey).toBe('new-snapshot');
-            expect(tracker?.pollCount).toBe(0);
-        });
-        it('cleans up tracker when decision is not clean PR', async () => {
-            getTrackers().set('ws-poll', {
-                snapshotKey: 'new-snapshot',
-                lastPolledAt: Date.now(),
-                pollCount: 1,
-            });
-            const failedPrState = {
-                ...cleanPrState,
-                ciStatus: CIStatus.FAILURE,
-                snapshotKey: 'failed-snapshot',
-            };
-            vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue(failedPrState);
-            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-            vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
-            vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
-                status: 'started',
-                sessionId: 'fixer',
-                promptSent: true,
+            vi.mocked(mockSessionBridge.stopSession).mockResolvedValue();
+            const result = await callCheckActiveFixerSession({
+                id: 'ws-5',
+                ratchetActiveSessionId: 'codex-session',
+                defaultSessionProvider: 'WORKSPACE_DEFAULT',
+                ratchetSessionProvider: 'WORKSPACE_DEFAULT',
             });
-            await callProcessWorkspace(cleanWorkspace);
-            expect(getTrackers().has('ws-poll')).toBe(false);
+            expect(result).toEqual({ kind: 'settled', outcome: 'DIED' });
+            expect(workspaceAccessor.recordRatchetSessionEnd).toHaveBeenCalledWith('ws-5', 'codex-session', 'DIED');
+            expect(mockSessionBridge.stopSession).toHaveBeenCalledWith('codex-session');
         });
-        it('continues to next cycle when fetchPRState returns null during re-poll', async () => {
-            getTrackers().set('ws-poll', {
-                snapshotKey: 'new-snapshot',
-                lastPolledAt: Date.now() - 3 * 60_000,
-                pollCount: 0,
+        it('returns the active fixer when the session is working', async () => {
+            vi.mocked(agentSessionAccessor.findById).mockResolvedValue({
+                id: 'working-session',
+                provider: 'CLAUDE',
+                status: SessionStatus.RUNNING,
             });
-            const fetchSpy = vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState');
-            fetchSpy.mockResolvedValueOnce(cleanPrState);
-            fetchSpy.mockResolvedValueOnce(null);
-            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-            vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
-            const result = await callProcessWorkspace(cleanWorkspace);
-            expect(result.action.type).toBe('WAITING');
-            expect(getTrackers().get('ws-poll')?.pollCount).toBe(0);
-        });
-        it('skips re-poll when shutting down', async () => {
-            getTrackers().set('ws-poll', {
-                snapshotKey: 'new-snapshot',
-                lastPolledAt: Date.now() - 3 * 60_000,
-                pollCount: 0,
+            vi.mocked(mockSessionBridge.isSessionRunning).mockReturnValue(true);
+            vi.mocked(mockSessionBridge.isSessionWorking).mockReturnValue(true);
+            const result = await callCheckActiveFixerSession({
+                id: 'ws-6',
+                ratchetActiveSessionId: 'working-session',
             });
-            unsafeCoerce(ratchetService).isShuttingDown = false;
-            const fetchSpy = vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState');
-            fetchSpy.mockResolvedValueOnce(cleanPrState);
-            fetchSpy.mockResolvedValueOnce(cleanPrState);
-            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-            vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
-            const handlePollSpy = vi.spyOn(unsafeCoerce(ratchetService), 'handleReviewCommentPoll');
-            handlePollSpy.mockImplementationOnce(async (...args) => {
-                unsafeCoerce(ratchetService).isShuttingDown = true;
-                handlePollSpy.mockRestore();
-                return await unsafeCoerce(ratchetService).handleReviewCommentPoll(...args);
+            expect(result).toEqual({
+                kind: 'active',
+                action: { type: 'FIXER_ACTIVE', sessionId: 'working-session' },
             });
-            const result = await callProcessWorkspace(cleanWorkspace);
-            expect(result.action.type).toBe('WAITING');
-            expect(fetchSpy).toHaveBeenCalledTimes(1);
+            expect(workspaceAccessor.recordRatchetSessionEnd).not.toHaveBeenCalled();
+        });
+        it('does not settle or stop a fixer after cancellation during session lookup', async () => {
+            const controller = new AbortController();
+            const timeoutError = new Error('Workspace check timed out');
+            let finishLookup;
+            vi.mocked(agentSessionAccessor.findById).mockImplementation(() => new Promise((resolve) => {
+                finishLookup = resolve;
+            }));
+            const check = unsafeCoerce(ratchetService).checkActiveFixerSession({
+                id: 'ws-cancelled-active-check',
+                ratchetActiveSessionId: 'session-1',
+            }, controller.signal);
+            await vi.waitFor(() => expect(agentSessionAccessor.findById).toHaveBeenCalled());
+            controller.abort(timeoutError);
+            finishLookup(null);
+            await expect(check).rejects.toBe(timeoutError);
+            expect(workspaceAccessor.recordRatchetSessionEnd).not.toHaveBeenCalled();
+            expect(mockSessionBridge.stopSession).not.toHaveBeenCalled();
         });
     });
     describe('triggerFixer error handling', () => {
+        it('does not clean up a fixer after its dispatch record is persisted', async () => {
+            const controller = new AbortController();
+            const timeoutError = new Error('Workspace check timed out');
+            let finishRecord;
+            vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
+                status: 'started',
+                sessionId: 'cancelled-session',
+                promptSent: true,
+            });
+            vi.mocked(workspaceAccessor.recordRatchetDispatchIfEnabled).mockImplementation(() => new Promise((resolve) => {
+                finishRecord = resolve;
+            }));
+            vi.mocked(mockSessionBridge.isSessionRunning).mockReturnValue(true);
+            const commitSideEffects = vi.fn();
+            const trigger = unsafeCoerce(ratchetService).triggerFixer({
+                id: 'ws-cancelled-dispatch',
+                prUrl: 'https://github.com/example/repo/pull/20',
+            }, {
+                ciStatus: CIStatus.FAILURE,
+                snapshotKey: 'failed:20',
+                prNumber: 20,
+                reviewComments: [],
+                hasMergeConflict: false,
+            }, 0, controller.signal, commitSideEffects);
+            await vi.waitFor(() => expect(workspaceAccessor.recordRatchetDispatchIfEnabled).toHaveBeenCalled());
+            controller.abort(timeoutError);
+            finishRecord(true);
+            await expect(trigger).rejects.toBe(timeoutError);
+            expect(commitSideEffects).toHaveBeenCalledTimes(1);
+            expect(workspaceAccessor.recordRatchetSessionEnd).not.toHaveBeenCalled();
+            expect(mockSessionBridge.stopSession).not.toHaveBeenCalled();
+        });
+        it('cleans up a started fixer when dispatch persistence fails', async () => {
+            vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
+                status: 'started',
+                sessionId: 'unrecorded-session',
+                promptSent: true,
+            });
+            vi.mocked(workspaceAccessor.recordRatchetDispatchIfEnabled).mockRejectedValue(new Error('dispatch record write failed'));
+            vi.mocked(workspaceAccessor.recordRatchetSessionEnd).mockRejectedValue(new Error('dispatch cleanup write failed'));
+            vi.mocked(mockSessionBridge.isSessionRunning).mockReturnValue(true);
+            const commitSideEffects = vi.fn();
+            const result = await unsafeCoerce(ratchetService).triggerFixer({
+                id: 'ws-unrecorded-dispatch',
+                prUrl: 'https://github.com/example/repo/pull/20',
+            }, {
+                ciStatus: CIStatus.FAILURE,
+                snapshotKey: 'failed:20',
+                prNumber: 20,
+                reviewComments: [],
+                hasMergeConflict: false,
+            }, 0, new AbortController().signal, commitSideEffects);
+            expect(result).toMatchObject({ type: 'ERROR', error: 'dispatch record write failed' });
+            expect(commitSideEffects).toHaveBeenCalledTimes(1);
+            expect(workspaceAccessor.recordRatchetSessionEnd).toHaveBeenCalledWith('ws-unrecorded-dispatch', 'unrecorded-session', 'COMPLETED');
+            expect(mockSessionBridge.stopSession).toHaveBeenCalledWith('unrecorded-session');
+        });
         it('handles acquireAndDispatch throwing an error', async () => {
             const workspace = {
                 id: 'ws-trigger-fail',
@@ -1422,12 +2415,14 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 ratchetActiveSessionId: null,
                 ratchetLastCiRunId: null,
                 prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
             };
             vi.mocked(fixerSessionService.acquireAndDispatch).mockRejectedValue(new Error('Session creation failed'));
             const result = await unsafeCoerce(ratchetService).triggerFixer(workspace, {
                 ciStatus: CIStatus.FAILURE,
                 prNumber: 20,
-            });
+            }, 0);
             expect(result).toMatchObject({
                 type: 'ERROR',
                 error: 'Session creation failed',
@@ -1443,6 +2438,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 ratchetActiveSessionId: null,
                 ratchetLastCiRunId: null,
                 prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
             };
             vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
                 status: 'already_active',
@@ -1452,11 +2449,42 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             const result = await unsafeCoerce(ratchetService).triggerFixer(workspace, {
                 ciStatus: CIStatus.FAILURE,
                 prNumber: 21,
-            });
+            }, 0);
             expect(result).toMatchObject({
                 type: 'FIXER_ACTIVE',
                 sessionId: 'existing-session',
             });
+            expect(workspaceAccessor.adoptRatchetActiveSessionIfEnabled).toHaveBeenCalledWith('ws-already-active', 'existing-session');
+            expect(workspaceAccessor.recordRatchetDispatchIfEnabled).not.toHaveBeenCalled();
+        });
+        it('stops already-active fixer when active-session recording loses disable race', async () => {
+            const workspace = {
+                id: 'ws-already-active-disabled',
+                prUrl: 'https://github.com/example/repo/pull/24',
+                prNumber: 24,
+                ratchetEnabled: true,
+                ratchetState: RatchetState.CI_FAILED,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
+                prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
+            };
+            vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
+                status: 'already_active',
+                sessionId: 'existing-session',
+            });
+            vi.mocked(workspaceAccessor.adoptRatchetActiveSessionIfEnabled).mockResolvedValue(false);
+            vi.mocked(mockSessionBridge.isSessionRunning).mockReturnValue(true);
+            const result = await unsafeCoerce(ratchetService).triggerFixer(workspace, {
+                ciStatus: CIStatus.FAILURE,
+                prNumber: 24,
+            }, 0);
+            expect(result).toMatchObject({
+                type: 'DISABLED',
+                reason: 'Workspace ratcheting disabled',
+            });
+            expect(mockSessionBridge.stopSession).toHaveBeenCalledWith('existing-session');
         });
         it('handles skipped result from acquireAndDispatch', async () => {
             const workspace = {
@@ -1468,6 +2496,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 ratchetActiveSessionId: null,
                 ratchetLastCiRunId: null,
                 prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
             };
             vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
                 status: 'skipped',
@@ -1476,7 +2506,7 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             const result = await unsafeCoerce(ratchetService).triggerFixer(workspace, {
                 ciStatus: CIStatus.FAILURE,
                 prNumber: 22,
-            });
+            }, 0);
             expect(result).toMatchObject({
                 type: 'ERROR',
                 error: 'No worktree path',
@@ -1534,6 +2564,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 ratchetState: RatchetState.IDLE,
                 ratchetActiveSessionId: null,
                 ratchetLastCiRunId: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
             });
             expect(stateEvents).toEqual([
                 {
@@ -1550,6 +2582,31 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 },
             ]);
         });
+        it('stops ratchet workflow sessions found after disabling workspace', async () => {
+            vi.mocked(workspaceAccessor.findById).mockResolvedValue({
+                id: 'ws-disable-raced-session',
+                ratchetState: RatchetState.CI_RUNNING,
+                ratchetActiveSessionId: null,
+            });
+            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
+            vi.mocked(mockSessionBridge.findSessionsByWorkspaceId).mockResolvedValue([
+                {
+                    id: 'raced-ratchet-session',
+                    workflow: 'ratchet',
+                    status: SessionStatus.RUNNING,
+                },
+                {
+                    id: 'manual-session',
+                    workflow: 'default',
+                    status: SessionStatus.RUNNING,
+                },
+            ]);
+            vi.mocked(mockSessionBridge.isSessionRunning).mockImplementation((sessionId) => sessionId === 'raced-ratchet-session');
+            await ratchetService.setWorkspaceRatcheting('ws-disable-raced-session', false);
+            expect(mockSessionBridge.findSessionsByWorkspaceId).toHaveBeenCalledWith('ws-disable-raced-session');
+            expect(mockSessionBridge.stopSession).toHaveBeenCalledTimes(1);
+            expect(mockSessionBridge.stopSession).toHaveBeenCalledWith('raced-ratchet-session');
+        });
     });
     describe('event emission', () => {
         afterEach(() => {
@@ -1565,6 +2622,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 ratchetActiveSessionId: null,
                 ratchetLastCiRunId: null,
                 prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
             };
             vi.mocked(workspaceAccessor.update).mockResolvedValue({});
             const events = [];
@@ -1589,6 +2648,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 ratchetActiveSessionId: null,
                 ratchetLastCiRunId: null,
                 prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
             };
             vi.mocked(workspaceAccessor.update).mockResolvedValue({});
             const events = [];
@@ -1608,6 +2669,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 ratchetActiveSessionId: null,
                 ratchetLastCiRunId: null,
                 prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
             };
             vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
                 ciStatus: CIStatus.FAILURE,
@@ -1648,6 +2711,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 ratchetActiveSessionId: null,
                 ratchetLastCiRunId: null,
                 prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
             };
             vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
                 ciStatus: CIStatus.FAILURE,
@@ -1682,6 +2747,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 ratchetActiveSessionId: null,
                 ratchetLastCiRunId: null,
                 prReviewLastCheckedAt: null,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
             };
             vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue(null);
             vi.mocked(workspaceAccessor.update).mockResolvedValue({});