factory-factory 0.2.7 → 0.3.0

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

@@ -1,5 +1,5 @@
-import { CIStatus, RatchetState, SessionStatus } from '../../../../prisma/generated/client.js';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { CIStatus, RatchetState, SessionStatus } from '@factory-factory/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { unsafeCoerce } from '../../../test-utils/unsafe-coerce.js';
 vi.mock('@/backend/resource_accessors/workspace.accessor', () => ({
     workspaceAccessor: {
@@ -8,12 +8,18 @@ vi.mock('@/backend/resource_accessors/workspace.accessor', () => ({
         update: vi.fn(),
     },
 }));
-vi.mock('@/backend/resource_accessors/claude-session.accessor', () => ({
-    claudeSessionAccessor: {
+vi.mock('@/backend/resource_accessors/agent-session.accessor', () => ({
+    agentSessionAccessor: {
         findById: vi.fn(),
         findByWorkspaceId: vi.fn(),
     },
 }));
+vi.mock('@/backend/resource_accessors/user-settings.accessor', () => ({
+    userSettingsAccessor: {
+        get: vi.fn(),
+        getDefaultSessionProvider: vi.fn(),
+    },
+}));
 vi.mock('./fixer-session.service', () => ({
     fixerSessionService: {
         acquireAndDispatch: vi.fn(),
@@ -27,16 +33,17 @@ vi.mock('@/backend/services/logger.service', () => ({
         error: vi.fn(),
     }),
 }));
-import { claudeSessionAccessor } from '../../../backend/resource_accessors/claude-session.accessor.js';
+import { agentSessionAccessor } from '../../../backend/resource_accessors/agent-session.accessor.js';
+import { userSettingsAccessor } from '../../../backend/resource_accessors/user-settings.accessor.js';
 import { workspaceAccessor } from '../../../backend/resource_accessors/workspace.accessor.js';
 import { fixerSessionService } from './fixer-session.service.js';
-import { ratchetService } from './ratchet.service.js';
+import { RATCHET_STATE_CHANGED, ratchetService, } from './ratchet.service.js';
 const mockSessionBridge = {
     isSessionRunning: vi.fn(),
     isSessionWorking: vi.fn(),
-    stopClaudeSession: vi.fn(),
-    startClaudeSession: vi.fn(),
-    getClient: vi.fn(),
+    stopSession: vi.fn(),
+    startSession: vi.fn(),
+    sendSessionMessage: vi.fn(),
     injectCommittedUserMessage: vi.fn(),
 };
 const mockGitHubBridge = {
@@ -47,13 +54,38 @@ const mockGitHubBridge = {
     getAuthenticatedUsername: vi.fn(),
     fetchAndComputePRState: vi.fn(),
 };
+const mockSnapshotBridge = {
+    recordCIObservation: vi.fn(),
+    recordCINotification: vi.fn(),
+    recordReviewCheck: vi.fn(),
+};
 describe('ratchet service (state-change + idle dispatch)', () => {
     beforeEach(() => {
         vi.clearAllMocks();
         unsafeCoerce(ratchetService).isShuttingDown = false;
-        ratchetService.configure({ session: mockSessionBridge, github: mockGitHubBridge });
+        unsafeCoerce(ratchetService).reviewPollTrackers.clear();
+        ratchetService.configure({
+            session: mockSessionBridge,
+            github: mockGitHubBridge,
+            snapshot: mockSnapshotBridge,
+        });
         vi.mocked(mockGitHubBridge.getAuthenticatedUsername).mockResolvedValue(null);
         vi.mocked(mockSessionBridge.isSessionWorking).mockReturnValue(false);
+        vi.mocked(userSettingsAccessor.get).mockResolvedValue({
+            id: 'settings-1',
+            userId: 'default',
+            preferredIde: 'cursor',
+            customIdeCommand: null,
+            playSoundOnComplete: true,
+            notificationSoundPath: null,
+            workspaceOrder: null,
+            cachedSlashCommands: null,
+            ratchetEnabled: false,
+            defaultSessionProvider: 'CLAUDE',
+            createdAt: new Date('2026-01-01T00:00:00.000Z'),
+            updatedAt: new Date('2026-01-01T00:00:00.000Z'),
+        });
+        vi.mocked(userSettingsAccessor.getDefaultSessionProvider).mockResolvedValue('CLAUDE');
     });
     it('checks workspaces and processes each', async () => {
         vi.mocked(workspaceAccessor.findWithPRsForRatchet).mockResolvedValue([
@@ -63,6 +95,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 prNumber: 1,
                 prState: 'OPEN',
                 prCiStatus: CIStatus.UNKNOWN,
+                defaultSessionProvider: 'WORKSPACE_DEFAULT',
+                ratchetSessionProvider: 'WORKSPACE_DEFAULT',
                 ratchetEnabled: true,
                 ratchetState: RatchetState.IDLE,
                 ratchetActiveSessionId: null,
@@ -126,7 +160,7 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             prNumber: 3,
         });
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        vi.mocked(claudeSessionAccessor.findByWorkspaceId).mockResolvedValue([
+        vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([
             {
                 id: 'chat-1',
                 workflow: 'default-followup',
@@ -165,7 +199,7 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             prNumber: 4,
         });
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        vi.mocked(claudeSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
         vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
             status: 'started',
             sessionId: 'ratchet-session',
@@ -177,7 +211,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
         });
         const finalUpdatePayload = vi.mocked(workspaceAccessor.update).mock.calls.at(-1)?.[1];
         expect(finalUpdatePayload.ratchetLastCiRunId).toBe('2026-01-02T00:00:00Z');
-        expect(finalUpdatePayload).toHaveProperty('prReviewLastCheckedAt');
+        expect(finalUpdatePayload).not.toHaveProperty('prReviewLastCheckedAt');
+        expect(mockSnapshotBridge.recordReviewCheck).toHaveBeenCalledWith('ws-change', expect.any(Date));
     });
     it('does dispatch when session is running but idle', async () => {
         const workspace = {
@@ -202,7 +237,7 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             prNumber: 44,
         });
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        vi.mocked(claudeSessionAccessor.findByWorkspaceId).mockResolvedValue([
+        vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([
             {
                 id: 'chat-idle-1',
                 workflow: 'default-followup',
@@ -243,7 +278,7 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             prNumber: 5,
         });
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        vi.mocked(claudeSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
         const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
         expect(result).toMatchObject({
             action: {
@@ -251,7 +286,8 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 reason: 'PR state unchanged since last ratchet dispatch',
             },
         });
-        expect(claudeSessionAccessor.findByWorkspaceId).not.toHaveBeenCalled();
+        expect(agentSessionAccessor.findByWorkspaceId).not.toHaveBeenCalled();
+        expect(mockSnapshotBridge.recordReviewCheck).not.toHaveBeenCalled();
     });
     it('does not dispatch repeatedly for unchanged CHANGES_REQUESTED state', async () => {
         const workspace = {
@@ -276,7 +312,7 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             prNumber: 55,
         });
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        vi.mocked(claudeSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
         const triggerSpy = vi.spyOn(unsafeCoerce(ratchetService), 'triggerFixer');
         const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
         expect(triggerSpy).not.toHaveBeenCalled();
@@ -286,7 +322,7 @@ describe('ratchet service (state-change + idle dispatch)', () => {
                 reason: 'PR state unchanged since last ratchet dispatch',
             },
         });
-        expect(claudeSessionAccessor.findByWorkspaceId).not.toHaveBeenCalled();
+        expect(agentSessionAccessor.findByWorkspaceId).not.toHaveBeenCalled();
     });
     it('treats closed PR as IDLE and does not dispatch', () => {
         const state = unsafeCoerce(ratchetService).determineRatchetState({
@@ -322,14 +358,14 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             prNumber: 7,
         });
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        vi.mocked(claudeSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
         vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
             status: 'started',
             sessionId: 'ratchet-session',
             promptSent: false,
         });
         vi.mocked(mockSessionBridge.isSessionRunning).mockReturnValue(true);
-        vi.mocked(mockSessionBridge.stopClaudeSession).mockResolvedValue();
+        vi.mocked(mockSessionBridge.stopSession).mockResolvedValue();
         const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
         expect(result).toMatchObject({
             action: { type: 'ERROR', error: 'Failed to deliver initial ratchet prompt' },
@@ -337,9 +373,10 @@ describe('ratchet service (state-change + idle dispatch)', () => {
         expect(workspaceAccessor.update).toHaveBeenCalledWith(workspace.id, {
             ratchetActiveSessionId: null,
         });
-        expect(mockSessionBridge.stopClaudeSession).toHaveBeenCalledWith('ratchet-session');
+        expect(mockSessionBridge.stopSession).toHaveBeenCalledWith('ratchet-session');
     });
     it('does not dispatch on a clean PR with no new review activity', async () => {
+        const recentCheck = new Date();
         const workspace = {
             id: 'ws-clean',
             prUrl: 'https://github.com/example/repo/pull/8',
@@ -350,19 +387,19 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             ratchetState: RatchetState.READY,
             ratchetActiveSessionId: null,
             ratchetLastCiRunId: '2026-01-01T00:00:00Z',
-            prReviewLastCheckedAt: new Date('2026-01-02T00:00:00Z'),
+            prReviewLastCheckedAt: recentCheck,
         };
         vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
             ciStatus: CIStatus.SUCCESS,
             snapshotKey: '2026-01-03T00:00:00Z',
             hasChangesRequested: false,
-            latestReviewActivityAtMs: new Date('2026-01-02T00:00:00Z').getTime(),
+            latestReviewActivityAtMs: recentCheck.getTime() - 1000,
             statusCheckRollup: null,
             prState: 'OPEN',
             prNumber: 8,
         });
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        vi.mocked(claudeSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
         const triggerSpy = vi.spyOn(unsafeCoerce(ratchetService), 'triggerFixer');
         const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
         expect(triggerSpy).not.toHaveBeenCalled();
@@ -373,7 +410,40 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             },
         });
     });
-    it('clears active ratchet session immediately when runtime is not running', async () => {
+    it('self-heals when review check timestamp is stale with no active session', async () => {
+        const staleCheckedAt = new Date(Date.now() - 15 * 60_000);
+        const workspace = {
+            id: 'ws-stale-check',
+            prUrl: 'https://github.com/example/repo/pull/13',
+            prNumber: 13,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
+            ratchetEnabled: true,
+            ratchetState: RatchetState.READY,
+            ratchetActiveSessionId: null,
+            ratchetLastCiRunId: '2026-01-01T00:00:00Z',
+            prReviewLastCheckedAt: staleCheckedAt,
+        };
+        vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
+            ciStatus: CIStatus.SUCCESS,
+            snapshotKey: '2026-01-03T00:00:00Z',
+            hasChangesRequested: false,
+            latestReviewActivityAtMs: staleCheckedAt.getTime() - 1000,
+            statusCheckRollup: null,
+            prState: 'OPEN',
+            prNumber: 13,
+        });
+        vi.mocked(workspaceAccessor.update).mockResolvedValue({});
+        vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        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)',
+            },
+        });
+    });
+    it('resets dispatch tracking when ratchet session process is not running', async () => {
         const workspace = {
             id: 'ws-stale-active',
             prUrl: 'https://github.com/example/repo/pull/9',
@@ -383,22 +453,50 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             ratchetEnabled: true,
             ratchetState: RatchetState.CI_FAILED,
             ratchetActiveSessionId: 'ratchet-session',
-            ratchetLastCiRunId: null,
-            prReviewLastCheckedAt: null,
+            ratchetLastCiRunId: 'previous-snapshot-key',
+            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
         };
-        vi.mocked(claudeSessionAccessor.findById).mockResolvedValue({
+        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, {
             ratchetActiveSessionId: null,
+            ratchetLastCiRunId: null,
         });
+        expect(mockSnapshotBridge.recordReviewCheck).toHaveBeenCalledWith(workspace.id, null);
     });
-    it('stops and clears active ratchet session when runtime is idle', async () => {
+    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,
+            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'),
+        };
+        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,
+        });
+        expect(mockSnapshotBridge.recordReviewCheck).toHaveBeenCalledWith(workspace.id, null);
+    });
+    it('does not reset dispatch tracking when ratchet session completed normally', async () => {
         const workspace = {
             id: 'ws-idle-active',
             prUrl: 'https://github.com/example/repo/pull/11',
@@ -408,23 +506,25 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             ratchetEnabled: true,
             ratchetState: RatchetState.CI_FAILED,
             ratchetActiveSessionId: 'ratchet-session',
-            ratchetLastCiRunId: null,
-            prReviewLastCheckedAt: null,
+            ratchetLastCiRunId: 'snapshot-key',
+            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
         };
-        vi.mocked(claudeSessionAccessor.findById).mockResolvedValue({
+        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.stopClaudeSession).mockResolvedValue();
+        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,
         });
-        expect(mockSessionBridge.stopClaudeSession).toHaveBeenCalledWith('ratchet-session');
+        expect(mockSessionBridge.stopSession).toHaveBeenCalledWith('ratchet-session');
+        expect(mockSnapshotBridge.recordReviewCheck).not.toHaveBeenCalled();
     });
     it('decides to trigger fixer when context is actionable', () => {
         const decision = unsafeCoerce(ratchetService).decideRatchetAction({
@@ -700,6 +800,22 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             expect(result).toEqual({ checked: 0, stateChanges: 0, actionsTriggered: 0, results: [] });
         });
     });
+    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;
@@ -769,9 +885,10 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             });
             expect(result).toBeNull();
         });
-        it('returns null and clears when session DB record is missing', async () => {
-            vi.mocked(claudeSessionAccessor.findById).mockResolvedValue(null);
+        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',
@@ -779,14 +896,18 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             expect(result).toBeNull();
             expect(workspaceAccessor.update).toHaveBeenCalledWith('ws-2', {
                 ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
             });
+            expect(mockSnapshotBridge.recordReviewCheck).toHaveBeenCalledWith('ws-2', null);
         });
-        it('returns null and clears when session is not RUNNING', async () => {
-            vi.mocked(claudeSessionAccessor.findById).mockResolvedValue({
+        it('returns null and resets dispatch tracking when session is not RUNNING', 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({
                 id: 'ws-3',
                 ratchetActiveSessionId: 'completed-session',
@@ -794,7 +915,196 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             expect(result).toBeNull();
             expect(workspaceAccessor.update).toHaveBeenCalledWith('ws-3', {
                 ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
             });
+            expect(mockSnapshotBridge.recordReviewCheck).toHaveBeenCalledWith('ws-3', null);
+        });
+    });
+    describe('review comment backoff 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,
+        };
+        const prStateWithComments = {
+            ...cleanPrState,
+            snapshotKey: 'snapshot-with-comments',
+            hasChangesRequested: true,
+            latestReviewActivityAtMs: new Date('2026-01-03T00:00:00Z').getTime(),
+        };
+        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('does not create tracker when state has not changed', 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(false);
+        });
+        it('skips re-poll when not enough time has elapsed', async () => {
+            getTrackers().set('ws-poll', {
+                snapshotKey: 'new-snapshot',
+                startedAt: 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',
+                startedAt: 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,
+            });
+            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',
+                startedAt: Date.now() - 3 * 60_000,
+                pollCount: 0,
+            });
+            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('stamps snapshot after exhausting all polls', async () => {
+            getTrackers().set('ws-poll', {
+                snapshotKey: 'new-snapshot',
+                startedAt: Date.now() - 130 * 60_000,
+                pollCount: 5,
+            });
+            vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue(cleanPrState);
+            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
+            vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+            await callProcessWorkspace(cleanWorkspace);
+            expect(getTrackers().has('ws-poll')).toBe(false);
+            expect(workspaceAccessor.update).toHaveBeenCalledWith('ws-poll', {
+                ratchetLastCiRunId: 'new-snapshot',
+            });
+        });
+        it('resets tracker when snapshotKey changes', async () => {
+            getTrackers().set('ws-poll', {
+                snapshotKey: 'different-snapshot',
+                startedAt: Date.now() - 10 * 60_000,
+                pollCount: 3,
+            });
+            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',
+                startedAt: 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,
+            });
+            await callProcessWorkspace(cleanWorkspace);
+            expect(getTrackers().has('ws-poll')).toBe(false);
+        });
+        it('continues to next cycle when fetchPRState returns null during re-poll', async () => {
+            getTrackers().set('ws-poll', {
+                snapshotKey: 'new-snapshot',
+                startedAt: Date.now() - 3 * 60_000,
+                pollCount: 0,
+            });
+            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',
+                startedAt: Date.now() - 3 * 60_000,
+                pollCount: 0,
+            });
+            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);
+            });
+            const result = await callProcessWorkspace(cleanWorkspace);
+            expect(result.action.type).toBe('WAITING');
+            expect(fetchSpy).toHaveBeenCalledTimes(1);
         });
     });
     describe('triggerFixer error handling', () => {
@@ -869,5 +1179,149 @@ describe('ratchet service (state-change + idle dispatch)', () => {
             });
         });
     });
+    describe('event emission', () => {
+        afterEach(() => {
+            ratchetService.removeAllListeners();
+        });
+        it('emits ratchet_state_changed when disabled workspace state changes', async () => {
+            const workspace = {
+                id: 'ws-disabled-change',
+                prUrl: 'https://github.com/example/repo/pull/30',
+                prNumber: 30,
+                ratchetEnabled: false,
+                ratchetState: RatchetState.CI_FAILED,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
+                prReviewLastCheckedAt: null,
+            };
+            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
+            const events = [];
+            ratchetService.on(RATCHET_STATE_CHANGED, (event) => {
+                events.push(event);
+            });
+            await unsafeCoerce(ratchetService).processWorkspace(workspace);
+            expect(events).toHaveLength(1);
+            expect(events[0]).toEqual({
+                workspaceId: 'ws-disabled-change',
+                fromState: RatchetState.CI_FAILED,
+                toState: RatchetState.IDLE,
+            });
+        });
+        it('does NOT emit when disabled workspace state is already IDLE', async () => {
+            const workspace = {
+                id: 'ws-disabled-idle',
+                prUrl: 'https://github.com/example/repo/pull/31',
+                prNumber: 31,
+                ratchetEnabled: false,
+                ratchetState: RatchetState.IDLE,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
+                prReviewLastCheckedAt: null,
+            };
+            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
+            const events = [];
+            ratchetService.on(RATCHET_STATE_CHANGED, (event) => {
+                events.push(event);
+            });
+            await unsafeCoerce(ratchetService).processWorkspace(workspace);
+            expect(events).toHaveLength(0);
+        });
+        it('emits ratchet_state_changed on main path when state changes', async () => {
+            const workspace = {
+                id: 'ws-state-change',
+                prUrl: 'https://github.com/example/repo/pull/32',
+                prNumber: 32,
+                ratchetEnabled: true,
+                ratchetState: RatchetState.IDLE,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
+                prReviewLastCheckedAt: null,
+            };
+            vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
+                ciStatus: CIStatus.FAILURE,
+                snapshotKey: 'new-snapshot-key',
+                hasChangesRequested: false,
+                latestReviewActivityAtMs: null,
+                statusCheckRollup: null,
+                prState: 'OPEN',
+                prNumber: 32,
+            });
+            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
+            vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+            vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
+                status: 'started',
+                sessionId: 'ratchet-session-32',
+                promptSent: true,
+            });
+            const events = [];
+            ratchetService.on(RATCHET_STATE_CHANGED, (event) => {
+                events.push(event);
+            });
+            await unsafeCoerce(ratchetService).processWorkspace(workspace);
+            expect(events).toHaveLength(1);
+            expect(events[0]).toEqual({
+                workspaceId: 'ws-state-change',
+                fromState: RatchetState.IDLE,
+                toState: RatchetState.CI_FAILED,
+            });
+        });
+        it('does NOT emit when main path state unchanged', async () => {
+            const workspace = {
+                id: 'ws-no-change',
+                prUrl: 'https://github.com/example/repo/pull/33',
+                prNumber: 33,
+                ratchetEnabled: true,
+                ratchetState: RatchetState.CI_FAILED,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
+                prReviewLastCheckedAt: null,
+            };
+            vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue({
+                ciStatus: CIStatus.FAILURE,
+                snapshotKey: 'new-snapshot-key',
+                hasChangesRequested: false,
+                latestReviewActivityAtMs: null,
+                statusCheckRollup: null,
+                prState: 'OPEN',
+                prNumber: 33,
+            });
+            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
+            vi.mocked(agentSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+            vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
+                status: 'started',
+                sessionId: 'ratchet-session-33',
+                promptSent: true,
+            });
+            const events = [];
+            ratchetService.on(RATCHET_STATE_CHANGED, (event) => {
+                events.push(event);
+            });
+            await unsafeCoerce(ratchetService).processWorkspace(workspace);
+            expect(events).toHaveLength(0);
+        });
+        it('does NOT emit on error path', async () => {
+            const workspace = {
+                id: 'ws-error',
+                prUrl: 'https://github.com/example/repo/pull/34',
+                prNumber: 34,
+                ratchetEnabled: true,
+                ratchetState: RatchetState.CI_FAILED,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: null,
+                prReviewLastCheckedAt: null,
+            };
+            vi.spyOn(unsafeCoerce(ratchetService), 'fetchPRState').mockResolvedValue(null);
+            vi.mocked(workspaceAccessor.update).mockResolvedValue({});
+            const events = [];
+            ratchetService.on(RATCHET_STATE_CHANGED, (event) => {
+                events.push(event);
+            });
+            const result = await unsafeCoerce(ratchetService).processWorkspace(workspace);
+            expect(result).toMatchObject({
+                action: { type: 'ERROR' },
+            });
+            expect(events).toHaveLength(0);
+        });
+    });
 });
 //# sourceMappingURL=ratchet.service.test.js.map