factory-factory 0.2.4 → 0.2.6

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

@@ -1,27 +1,16 @@
 import { CIStatus, RatchetState, SessionStatus } from '../../../prisma/generated/client.js';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-vi.mock('../db', () => ({
-    prisma: {
-        $transaction: vi.fn(),
-    },
-}));
-vi.mock('../resource_accessors/user-settings.accessor', () => ({
-    userSettingsAccessor: {
-        get: vi.fn(),
-    },
-}));
 vi.mock('../resource_accessors/workspace.accessor', () => ({
     workspaceAccessor: {
         findWithPRsForRatchet: vi.fn(),
         findForRatchetById: vi.fn(),
-        findById: vi.fn(),
         update: vi.fn(),
     },
 }));
 vi.mock('../resource_accessors/claude-session.accessor', () => ({
     claudeSessionAccessor: {
-        create: vi.fn(),
         findById: vi.fn(),
+        findByWorkspaceId: vi.fn(),
     },
 }));
 vi.mock('./github-cli.service', () => ({
@@ -30,27 +19,26 @@ vi.mock('./github-cli.service', () => ({
         getPRFullDetails: vi.fn(),
         getReviewComments: vi.fn(),
         computeCIStatus: vi.fn(),
-        mergePR: vi.fn(),
+        getAuthenticatedUsername: vi.fn(),
+    },
+}));
+vi.mock('./fixer-session.service', () => ({
+    fixerSessionService: {
+        acquireAndDispatch: vi.fn(),
     },
 }));
 vi.mock('./session.service', () => ({
     sessionService: {
-        getClient: vi.fn(),
-        isSessionActive: vi.fn(),
-        startClaudeSession: vi.fn(),
+        isSessionRunning: vi.fn(),
+        isSessionWorking: vi.fn(),
+        stopClaudeSession: vi.fn(),
     },
 }));
-vi.mock('./message-state.service', () => ({
-    messageStateService: {
-        getRecentUserAndAgentMessages: vi.fn(),
+vi.mock('./session-store.service', () => ({
+    sessionStoreService: {
         injectCommittedUserMessage: vi.fn(),
     },
 }));
-vi.mock('./config.service', () => ({
-    configService: {
-        getMaxSessionsPerWorkspace: vi.fn(() => 5),
-    },
-}));
 vi.mock('./logger.service', () => ({
     createLogger: () => ({
         debug: vi.fn(),
@@ -60,525 +48,441 @@ vi.mock('./logger.service', () => ({
     }),
 }));
 import { claudeSessionAccessor } from '../resource_accessors/claude-session.accessor.js';
-import { userSettingsAccessor } from '../resource_accessors/user-settings.accessor.js';
 import { workspaceAccessor } from '../resource_accessors/workspace.accessor.js';
+import { fixerSessionService } from './fixer-session.service.js';
+import { githubCLIService } from './github-cli.service.js';
 import { ratchetService } from './ratchet.service.js';
 import { sessionService } from './session.service.js';
-describe('ratchet service', () => {
+describe('ratchet service (state-change + idle dispatch)', () => {
     beforeEach(() => {
         vi.clearAllMocks();
         ratchetService.isShuttingDown = false;
+        vi.mocked(githubCLIService.getAuthenticatedUsername).mockResolvedValue(null);
+        vi.mocked(sessionService.isSessionWorking).mockReturnValue(false);
     });
-    it('checks workspaces even when global ratchet default is off', async () => {
-        vi.mocked(userSettingsAccessor.get).mockResolvedValue({
-            ratchetEnabled: false,
-            ratchetAutoFixCi: true,
-            ratchetAutoFixReviews: true,
-            ratchetAutoMerge: false,
-            ratchetAllowedReviewers: null,
-        });
+    it('checks workspaces and processes each', async () => {
         vi.mocked(workspaceAccessor.findWithPRsForRatchet).mockResolvedValue([
             {
                 id: 'ws-1',
                 prUrl: 'https://github.com/example/repo/pull/1',
                 prNumber: 1,
+                prState: 'OPEN',
+                prCiStatus: CIStatus.UNKNOWN,
                 ratchetEnabled: true,
                 ratchetState: RatchetState.IDLE,
                 ratchetActiveSessionId: null,
                 ratchetLastCiRunId: null,
-                ratchetLastNotifiedState: null,
                 prReviewLastCheckedAt: null,
             },
         ]);
-        const processWorkspaceSpy = vi
-            .spyOn(ratchetService, 'processWorkspace')
-            .mockResolvedValue({
+        vi.spyOn(ratchetService, 'processWorkspace').mockResolvedValue({
             workspaceId: 'ws-1',
             previousState: RatchetState.IDLE,
             newState: RatchetState.IDLE,
             action: { type: 'WAITING', reason: 'noop' },
         });
         const result = await ratchetService.checkAllWorkspaces();
-        expect(processWorkspaceSpy).toHaveBeenCalledTimes(1);
         expect(result.checked).toBe(1);
     });
-    it('does not execute ratchet actions when workspace ratcheting is off', async () => {
+    it('does not dispatch when workspace ratcheting is disabled', async () => {
         const workspace = {
-            id: 'ws-2',
+            id: 'ws-disabled',
             prUrl: 'https://github.com/example/repo/pull/2',
             prNumber: 2,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
             ratchetEnabled: false,
             ratchetState: RatchetState.IDLE,
             ratchetActiveSessionId: null,
             ratchetLastCiRunId: null,
-            ratchetLastNotifiedState: null,
             prReviewLastCheckedAt: null,
         };
-        const prStateInfo = {
-            ciStatus: 'FAILURE',
-            mergeStateStatus: 'CLEAN',
+        vi.spyOn(ratchetService, 'fetchPRState').mockResolvedValue({
+            ciStatus: CIStatus.FAILURE,
+            snapshotKey: '2026-01-02T00:00:00Z',
             hasChangesRequested: false,
-            hasNewReviewComments: false,
-            failedChecks: [],
-            ciRunId: '1001',
-            reviews: [],
-            comments: [],
-            reviewComments: [],
-            newReviewComments: [],
-            newPRComments: [],
+            latestReviewActivityAtMs: null,
+            statusCheckRollup: null,
             prState: 'OPEN',
             prNumber: 2,
-        };
-        vi.spyOn(ratchetService, 'fetchPRState').mockResolvedValue(prStateInfo);
-        vi.spyOn(ratchetService, 'determineRatchetState').mockReturnValue(RatchetState.CI_FAILED);
-        const executeRatchetActionSpy = vi.spyOn(ratchetService, 'executeRatchetAction');
-        vi.mocked(workspaceAccessor.findById).mockResolvedValue({
-            ratchetEnabled: false,
         });
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        const result = await ratchetService.processWorkspace(workspace, {
-            autoFixCi: true,
-            autoFixReviews: true,
-            autoMerge: false,
-            allowedReviewers: [],
-        });
-        expect(executeRatchetActionSpy).not.toHaveBeenCalled();
+        const triggerSpy = vi.spyOn(ratchetService, 'triggerFixer');
+        const result = await ratchetService.processWorkspace(workspace);
+        expect(triggerSpy).not.toHaveBeenCalled();
         expect(result).toMatchObject({
             action: { type: 'DISABLED', reason: 'Workspace ratcheting disabled' },
-            previousState: RatchetState.IDLE,
             newState: RatchetState.IDLE,
         });
-        expect(workspaceAccessor.update).toHaveBeenCalledWith(workspace.id, expect.objectContaining({ ratchetState: RatchetState.IDLE }));
     });
-    it('does not execute ratchet actions when ratcheting is disabled mid-check', async () => {
+    it('does not dispatch when workspace is not idle', async () => {
         const workspace = {
-            id: 'ws-3',
+            id: 'ws-busy',
             prUrl: 'https://github.com/example/repo/pull/3',
             prNumber: 3,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
             ratchetEnabled: true,
             ratchetState: RatchetState.IDLE,
             ratchetActiveSessionId: null,
             ratchetLastCiRunId: null,
-            ratchetLastNotifiedState: null,
-            prReviewLastCheckedAt: null,
+            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
         };
-        const prStateInfo = {
-            ciStatus: 'FAILURE',
-            mergeStateStatus: 'CLEAN',
+        vi.spyOn(ratchetService, 'fetchPRState').mockResolvedValue({
+            ciStatus: CIStatus.SUCCESS,
+            snapshotKey: '2026-01-02T00:00:00Z',
             hasChangesRequested: false,
-            hasNewReviewComments: false,
-            failedChecks: [],
-            ciRunId: '1002',
-            reviews: [],
-            comments: [],
-            reviewComments: [],
-            newReviewComments: [],
-            newPRComments: [],
+            latestReviewActivityAtMs: new Date('2026-01-02T00:00:00Z').getTime(),
+            statusCheckRollup: null,
             prState: 'OPEN',
             prNumber: 3,
-        };
-        vi.spyOn(ratchetService, 'fetchPRState').mockResolvedValue(prStateInfo);
-        vi.spyOn(ratchetService, 'determineRatchetState').mockReturnValue(RatchetState.CI_FAILED);
-        const executeRatchetActionSpy = vi.spyOn(ratchetService, 'executeRatchetAction');
-        vi.mocked(workspaceAccessor.findById).mockResolvedValue({
-            ratchetEnabled: false,
         });
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        const result = await ratchetService.processWorkspace(workspace, {
-            autoFixCi: true,
-            autoFixReviews: true,
-            autoMerge: false,
-            allowedReviewers: [],
-        });
-        expect(executeRatchetActionSpy).not.toHaveBeenCalled();
+        vi.mocked(claudeSessionAccessor.findByWorkspaceId).mockResolvedValue([
+            {
+                id: 'chat-1',
+                workflow: 'default-followup',
+                status: 'RUNNING',
+            },
+        ]);
+        vi.mocked(sessionService.isSessionWorking).mockReturnValue(true);
+        const result = await ratchetService.processWorkspace(workspace);
         expect(result).toMatchObject({
-            action: { type: 'DISABLED', reason: 'Workspace ratcheting disabled' },
-            newState: RatchetState.IDLE,
-        });
-        expect(workspaceAccessor.update).toHaveBeenCalledWith(workspace.id, expect.objectContaining({ ratchetState: RatchetState.IDLE }));
-    });
-});
-describe('Ratchet CI regression behavior', () => {
-    beforeEach(() => {
-        vi.clearAllMocks();
-    });
-    it('treats CI UNKNOWN as CI_RUNNING', () => {
-        const state = ratchetService.determineRatchetState({
-            ciStatus: CIStatus.UNKNOWN,
-            mergeStateStatus: 'CLEAN',
-            hasChangesRequested: false,
-            hasNewReviewComments: false,
-            failedChecks: [],
-            ciRunId: null,
-            reviews: [],
-            comments: [],
-            reviewComments: [],
-            newReviewComments: [],
-            newPRComments: [],
-            prState: 'OPEN',
-            prNumber: 12,
+            action: {
+                type: 'WAITING',
+                reason: 'Workspace is not idle (active non-ratchet chat session)',
+            },
         });
-        expect(state).toBe(RatchetState.CI_RUNNING);
     });
-    it('re-triggers fixer when active session is unreachable and CI fails', async () => {
+    it('dispatches when PR state changed since last ratchet', async () => {
         const workspace = {
-            id: 'ws-unreachable',
-            prUrl: 'https://github.com/example/repo/pull/55',
-            prNumber: 55,
+            id: 'ws-change',
+            prUrl: 'https://github.com/example/repo/pull/4',
+            prNumber: 4,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
             ratchetEnabled: true,
-            ratchetState: RatchetState.REVIEW_PENDING,
-            ratchetActiveSessionId: 'session-stale',
-            ratchetLastCiRunId: '2001',
-            ratchetLastNotifiedState: RatchetState.CI_FAILED,
-            prReviewLastCheckedAt: null,
+            ratchetState: RatchetState.IDLE,
+            ratchetActiveSessionId: null,
+            ratchetLastCiRunId: '2026-01-01T00:00:00Z',
+            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
         };
-        vi.mocked(claudeSessionAccessor.findById).mockResolvedValue({
-            id: 'session-stale',
-            status: SessionStatus.RUNNING,
+        vi.spyOn(ratchetService, 'fetchPRState').mockResolvedValue({
+            ciStatus: CIStatus.FAILURE,
+            snapshotKey: '2026-01-02T00:00:00Z',
+            hasChangesRequested: false,
+            latestReviewActivityAtMs: null,
+            statusCheckRollup: null,
+            prState: 'OPEN',
+            prNumber: 4,
         });
-        vi.mocked(sessionService.getClient).mockReturnValue(undefined);
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        const triggerFixerSpy = vi
-            .spyOn(ratchetService, 'triggerFixer')
-            .mockResolvedValue({
-            type: 'TRIGGERED_FIXER',
-            sessionId: 'new-fixer',
-            fixerType: 'ci',
+        vi.mocked(claudeSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
+            status: 'started',
+            sessionId: 'ratchet-session',
             promptSent: true,
         });
-        const result = await ratchetService.executeRatchetAction(workspace, RatchetState.CI_FAILED, {
+        const result = await ratchetService.processWorkspace(workspace);
+        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(finalUpdatePayload).toHaveProperty('prReviewLastCheckedAt');
+    });
+    it('does dispatch when non-ratchet session is running but idle', async () => {
+        const workspace = {
+            id: 'ws-idle-session',
+            prUrl: 'https://github.com/example/repo/pull/44',
+            prNumber: 44,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
+            ratchetEnabled: true,
+            ratchetState: RatchetState.IDLE,
+            ratchetActiveSessionId: null,
+            ratchetLastCiRunId: '2026-01-01T00:00:00Z',
+            prReviewLastCheckedAt: new Date('2026-01-01T00:00:00Z'),
+        };
+        vi.spyOn(ratchetService, 'fetchPRState').mockResolvedValue({
             ciStatus: CIStatus.FAILURE,
-            mergeStateStatus: 'CLEAN',
+            snapshotKey: '2026-01-02T00:00:00Z',
             hasChangesRequested: false,
-            hasNewReviewComments: false,
-            failedChecks: [],
-            ciRunId: '3001',
-            reviews: [],
-            comments: [],
-            reviewComments: [],
-            newReviewComments: [],
-            newPRComments: [],
+            latestReviewActivityAtMs: null,
+            statusCheckRollup: null,
             prState: 'OPEN',
-            prNumber: 55,
-        }, {
-            autoFixCi: true,
-            autoFixReviews: true,
-            autoMerge: false,
-            allowedReviewers: [],
+            prNumber: 44,
         });
-        expect(triggerFixerSpy).toHaveBeenCalledTimes(1);
-        expect(workspaceAccessor.update).toHaveBeenCalledWith(workspace.id, {
-            ratchetActiveSessionId: null,
-        });
-        expect(result).toEqual({
-            type: 'TRIGGERED_FIXER',
-            sessionId: 'new-fixer',
-            fixerType: 'ci',
+        vi.mocked(workspaceAccessor.update).mockResolvedValue({});
+        vi.mocked(claudeSessionAccessor.findByWorkspaceId).mockResolvedValue([
+            {
+                id: 'chat-idle-1',
+                workflow: 'default-followup',
+                status: 'RUNNING',
+            },
+        ]);
+        vi.mocked(sessionService.isSessionWorking).mockReturnValue(false);
+        vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
+            status: 'started',
+            sessionId: 'ratchet-session-idle-ok',
             promptSent: true,
         });
+        const result = await ratchetService.processWorkspace(workspace);
+        expect(result).toMatchObject({
+            action: { type: 'TRIGGERED_FIXER', sessionId: 'ratchet-session-idle-ok' },
+        });
     });
-    it('skips CI fixer dispatch when ciRunId matches ratchetLastCiRunId', async () => {
+    it('does not dispatch when PR state unchanged since last dispatch', async () => {
         const workspace = {
-            id: 'ws-stale-ci',
-            prUrl: 'https://github.com/example/repo/pull/99',
-            prNumber: 99,
+            id: 'ws-unchanged',
+            prUrl: 'https://github.com/example/repo/pull/5',
+            prNumber: 5,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
             ratchetEnabled: true,
-            ratchetState: RatchetState.CI_FAILED,
+            ratchetState: RatchetState.READY,
             ratchetActiveSessionId: null,
-            ratchetLastCiRunId: 'run-already-handled',
-            ratchetLastNotifiedState: null,
-            prReviewLastCheckedAt: null,
+            ratchetLastCiRunId: '2026-01-02T00:00:00Z',
+            prReviewLastCheckedAt: new Date('2026-01-02T00:00:00Z'),
         };
-        vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        const triggerFixerSpy = vi.spyOn(ratchetService, 'triggerFixer');
-        const result = await ratchetService.executeRatchetAction(workspace, RatchetState.CI_FAILED, {
+        vi.spyOn(ratchetService, 'fetchPRState').mockResolvedValue({
             ciStatus: CIStatus.FAILURE,
-            mergeStateStatus: 'CLEAN',
+            snapshotKey: '2026-01-02T00:00:00Z',
             hasChangesRequested: false,
-            hasNewReviewComments: false,
-            failedChecks: [],
-            ciRunId: 'run-already-handled',
-            reviews: [],
-            comments: [],
-            reviewComments: [],
-            newReviewComments: [],
-            newPRComments: [],
+            latestReviewActivityAtMs: null,
+            statusCheckRollup: null,
             prState: 'OPEN',
-            prNumber: 99,
-        }, {
-            autoFixCi: true,
-            autoFixReviews: true,
-            autoMerge: false,
-            allowedReviewers: [],
+            prNumber: 5,
         });
-        expect(triggerFixerSpy).not.toHaveBeenCalled();
-        expect(result).toEqual({
-            type: 'WAITING',
-            reason: 'Already dispatched fixer for this CI run; waiting for new run',
+        vi.mocked(workspaceAccessor.update).mockResolvedValue({});
+        vi.mocked(claudeSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        const result = await ratchetService.processWorkspace(workspace);
+        expect(result).toMatchObject({
+            action: {
+                type: 'WAITING',
+                reason: 'PR state unchanged since last ratchet dispatch',
+            },
         });
+        expect(claudeSessionAccessor.findByWorkspaceId).not.toHaveBeenCalled();
     });
-    it('dispatches CI fixer when ciRunId differs from ratchetLastCiRunId', async () => {
+    it('does not dispatch repeatedly for unchanged CHANGES_REQUESTED state', async () => {
         const workspace = {
-            id: 'ws-new-ci',
-            prUrl: 'https://github.com/example/repo/pull/100',
-            prNumber: 100,
+            id: 'ws-review-unchanged',
+            prUrl: 'https://github.com/example/repo/pull/55',
+            prNumber: 55,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
             ratchetEnabled: true,
-            ratchetState: RatchetState.CI_FAILED,
+            ratchetState: RatchetState.REVIEW_PENDING,
             ratchetActiveSessionId: null,
-            ratchetLastCiRunId: 'run-old',
-            ratchetLastNotifiedState: null,
-            prReviewLastCheckedAt: null,
+            ratchetLastCiRunId: 'ci:SUCCESS|changes-requested:1735776000000',
+            prReviewLastCheckedAt: new Date('2026-01-02T00:00:00Z'),
         };
+        vi.spyOn(ratchetService, 'fetchPRState').mockResolvedValue({
+            ciStatus: CIStatus.SUCCESS,
+            snapshotKey: 'ci:SUCCESS|changes-requested:1735776000000',
+            hasChangesRequested: true,
+            latestReviewActivityAtMs: new Date('2026-01-02T00:00:00Z').getTime(),
+            statusCheckRollup: null,
+            prState: 'OPEN',
+            prNumber: 55,
+        });
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        const triggerFixerSpy = vi
-            .spyOn(ratchetService, 'triggerFixer')
-            .mockResolvedValue({
-            type: 'TRIGGERED_FIXER',
-            sessionId: 'new-fixer',
-            fixerType: 'ci',
-            promptSent: true,
+        vi.mocked(claudeSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        const triggerSpy = vi.spyOn(ratchetService, 'triggerFixer');
+        const result = await ratchetService.processWorkspace(workspace);
+        expect(triggerSpy).not.toHaveBeenCalled();
+        expect(result).toMatchObject({
+            action: {
+                type: 'WAITING',
+                reason: 'PR state unchanged since last ratchet dispatch',
+            },
         });
-        await ratchetService.executeRatchetAction(workspace, RatchetState.CI_FAILED, {
-            ciStatus: CIStatus.FAILURE,
-            mergeStateStatus: 'CLEAN',
+        expect(claudeSessionAccessor.findByWorkspaceId).not.toHaveBeenCalled();
+    });
+    it('treats closed PR as IDLE and does not dispatch', () => {
+        const state = ratchetService.determineRatchetState({
+            ciStatus: CIStatus.SUCCESS,
+            snapshotKey: '2026-01-02T00:00:00Z',
             hasChangesRequested: false,
-            hasNewReviewComments: false,
-            failedChecks: [],
-            ciRunId: 'run-new',
-            reviews: [],
-            comments: [],
-            reviewComments: [],
-            newReviewComments: [],
-            newPRComments: [],
-            prState: 'OPEN',
-            prNumber: 100,
-        }, {
-            autoFixCi: true,
-            autoFixReviews: true,
-            autoMerge: false,
-            allowedReviewers: [],
+            latestReviewActivityAtMs: null,
+            prState: 'CLOSED',
+            prNumber: 6,
         });
-        expect(triggerFixerSpy).toHaveBeenCalledTimes(1);
+        expect(state).toBe(RatchetState.IDLE);
     });
-    it('notifies on a new CI run even when state is already CI_FAILED', () => {
-        const shouldNotify = ratchetService.shouldNotifyActiveFixer(RatchetState.CI_FAILED, RatchetState.CI_FAILED, '4002', '4001');
-        expect(shouldNotify).toBe(true);
-    });
-    it('does not consume CI run id when ratcheting is disabled', async () => {
+    it('handles prompt delivery failure by clearing active session and stopping runner', async () => {
         const workspace = {
-            id: 'ws-disabled',
-            prUrl: 'https://github.com/example/repo/pull/77',
-            prNumber: 77,
+            id: 'ws-prompt-fail',
+            prUrl: 'https://github.com/example/repo/pull/7',
+            prNumber: 7,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
             ratchetEnabled: true,
             ratchetState: RatchetState.IDLE,
             ratchetActiveSessionId: null,
             ratchetLastCiRunId: null,
-            ratchetLastNotifiedState: null,
             prReviewLastCheckedAt: null,
         };
         vi.spyOn(ratchetService, 'fetchPRState').mockResolvedValue({
-            ciStatus: CIStatus.FAILURE,
-            mergeStateStatus: 'CLEAN',
-            hasChangesRequested: false,
-            hasNewReviewComments: false,
-            failedChecks: [],
-            ciRunId: '5001',
-            reviews: [],
-            comments: [],
-            reviewComments: [],
-            newReviewComments: [],
-            newPRComments: [],
+            ciStatus: CIStatus.SUCCESS,
+            snapshotKey: '2026-01-02T00:00:00Z',
+            hasChangesRequested: true,
+            latestReviewActivityAtMs: new Date('2026-01-02T00:00:00Z').getTime(),
+            statusCheckRollup: null,
             prState: 'OPEN',
-            prNumber: 77,
+            prNumber: 7,
         });
-        vi.spyOn(ratchetService, 'determineRatchetState').mockReturnValue(RatchetState.CI_FAILED);
-        vi.mocked(workspaceAccessor.findById).mockResolvedValue({ ratchetEnabled: false });
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        await ratchetService.processWorkspace(workspace, {
-            autoFixCi: true,
-            autoFixReviews: true,
-            autoMerge: false,
-            allowedReviewers: [],
+        vi.mocked(claudeSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        vi.mocked(fixerSessionService.acquireAndDispatch).mockResolvedValue({
+            status: 'started',
+            sessionId: 'ratchet-session',
+            promptSent: false,
         });
-        const updateCalls = vi.mocked(workspaceAccessor.update).mock.calls;
-        const finalUpdatePayload = updateCalls[updateCalls.length - 1]?.[1];
-        expect(finalUpdatePayload).not.toHaveProperty('ratchetLastCiRunId');
+        vi.mocked(sessionService.isSessionRunning).mockReturnValue(true);
+        vi.mocked(sessionService.stopClaudeSession).mockResolvedValue();
+        const result = await ratchetService.processWorkspace(workspace);
+        expect(result).toMatchObject({
+            action: { type: 'ERROR', error: 'Failed to deliver initial ratchet prompt' },
+        });
+        expect(workspaceAccessor.update).toHaveBeenCalledWith(workspace.id, {
+            ratchetActiveSessionId: null,
+        });
+        expect(sessionService.stopClaudeSession).toHaveBeenCalledWith('ratchet-session');
     });
-    it('returns run id "0" when parsed from details url', () => {
-        const signature = ratchetService.extractFailedCiSignature([
-            {
-                name: 'unit-tests',
-                conclusion: 'FAILURE',
-                detailsUrl: 'https://github.com/acme/repo/actions/runs/0',
-            },
-            {
-                name: 'lint',
-                conclusion: 'FAILURE',
-                detailsUrl: 'https://github.com/acme/repo/actions/runs/42',
+    it('does not dispatch on a clean PR with no new review activity', async () => {
+        const workspace = {
+            id: 'ws-clean',
+            prUrl: 'https://github.com/example/repo/pull/8',
+            prNumber: 8,
+            prState: 'OPEN',
+            prCiStatus: CIStatus.UNKNOWN,
+            ratchetEnabled: true,
+            ratchetState: RatchetState.READY,
+            ratchetActiveSessionId: null,
+            ratchetLastCiRunId: '2026-01-01T00:00:00Z',
+            prReviewLastCheckedAt: new Date('2026-01-02T00:00:00Z'),
+        };
+        vi.spyOn(ratchetService, 'fetchPRState').mockResolvedValue({
+            ciStatus: CIStatus.SUCCESS,
+            snapshotKey: '2026-01-03T00:00:00Z',
+            hasChangesRequested: false,
+            latestReviewActivityAtMs: new Date('2026-01-02T00:00:00Z').getTime(),
+            statusCheckRollup: null,
+            prState: 'OPEN',
+            prNumber: 8,
+        });
+        vi.mocked(workspaceAccessor.update).mockResolvedValue({});
+        vi.mocked(claudeSessionAccessor.findByWorkspaceId).mockResolvedValue([]);
+        const triggerSpy = vi.spyOn(ratchetService, 'triggerFixer');
+        const result = await ratchetService.processWorkspace(workspace);
+        expect(triggerSpy).not.toHaveBeenCalled();
+        expect(result).toMatchObject({
+            action: {
+                type: 'WAITING',
+                reason: 'PR is clean (green CI and no new review activity)',
             },
-        ]);
-        expect(signature).toBe('lint:42|unit-tests:0');
+        });
     });
-    it('clears stale active session linkage when IDLE session has no client', async () => {
+    it('clears active ratchet session immediately when runtime is not running', async () => {
         const workspace = {
-            id: 'ws-idle',
-            prUrl: 'https://github.com/example/repo/pull/88',
-            prNumber: 88,
+            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: 'session-idle',
-            ratchetLastCiRunId: 'sig-old',
-            ratchetLastNotifiedState: RatchetState.CI_FAILED,
+            ratchetActiveSessionId: 'ratchet-session',
+            ratchetLastCiRunId: null,
             prReviewLastCheckedAt: null,
         };
         vi.mocked(claudeSessionAccessor.findById).mockResolvedValue({
-            id: 'session-idle',
-            status: SessionStatus.IDLE,
+            id: 'ratchet-session',
+            status: SessionStatus.RUNNING,
         });
-        vi.mocked(sessionService.getClient).mockReturnValue(undefined);
+        vi.mocked(sessionService.isSessionRunning).mockReturnValue(false);
         vi.mocked(workspaceAccessor.update).mockResolvedValue({});
-        const triggerFixerSpy = vi
-            .spyOn(ratchetService, 'triggerFixer')
-            .mockResolvedValue({
-            type: 'TRIGGERED_FIXER',
-            sessionId: 'session-idle',
-            fixerType: 'ci',
-            promptSent: true,
-        });
-        await ratchetService.executeRatchetAction(workspace, RatchetState.CI_FAILED, {
-            ciStatus: CIStatus.FAILURE,
-            mergeStateStatus: 'CLEAN',
-            hasChangesRequested: false,
-            hasNewReviewComments: false,
-            failedChecks: [],
-            ciRunId: 'sig-new',
-            reviews: [],
-            comments: [],
-            reviewComments: [],
-            newReviewComments: [],
-            newPRComments: [],
-            prState: 'OPEN',
-            prNumber: 88,
-        }, {
-            autoFixCi: true,
-            autoFixReviews: true,
-            autoMerge: false,
-            allowedReviewers: [],
-        });
-        expect(triggerFixerSpy).toHaveBeenCalledTimes(1);
+        const action = await ratchetService.getActiveRatchetSession(workspace);
+        expect(action).toBeNull();
         expect(workspaceAccessor.update).toHaveBeenCalledWith(workspace.id, {
             ratchetActiveSessionId: null,
         });
     });
-});
-describe('Ratchet Comment Detection', () => {
-    const lastCheckedAt = new Date('2024-01-01T12:00:00Z').getTime();
-    describe('New comment detection', () => {
-        it('should detect comments created after lastCheckedAt', () => {
-            const comment = {
-                id: '1',
-                author: { login: 'reviewer1' },
-                body: 'New comment',
-                createdAt: '2024-01-01T13:00:00Z',
-                updatedAt: '2024-01-01T13:00:00Z',
-                url: 'https://github.com/test/pr/1',
-            };
-            const createdTime = new Date(comment.createdAt).getTime();
-            const updatedTime = new Date(comment.updatedAt).getTime();
-            const isNewOrEdited = createdTime > lastCheckedAt || updatedTime > lastCheckedAt;
-            expect(isNewOrEdited).toBe(true);
-        });
-        it('should not detect comments created before lastCheckedAt', () => {
-            const comment = {
-                id: '1',
-                author: { login: 'reviewer1' },
-                body: 'Old comment',
-                createdAt: '2024-01-01T11:00:00Z',
-                updatedAt: '2024-01-01T11:00:00Z',
-                url: 'https://github.com/test/pr/1',
-            };
-            const createdTime = new Date(comment.createdAt).getTime();
-            const updatedTime = new Date(comment.updatedAt).getTime();
-            const isNewOrEdited = createdTime > lastCheckedAt || updatedTime > lastCheckedAt;
-            expect(isNewOrEdited).toBe(false);
+    it('decides to trigger fixer when context is actionable', () => {
+        const decision = 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' });
     });
-    describe('Edited comment detection', () => {
-        it('should detect comments edited after lastCheckedAt', () => {
-            const comment = {
-                id: '1',
-                author: { login: 'reviewer1' },
-                body: 'Edited comment',
-                createdAt: '2024-01-01T11:00:00Z',
-                updatedAt: '2024-01-01T13:00:00Z',
-                url: 'https://github.com/test/pr/1',
-            };
-            const createdTime = new Date(comment.createdAt).getTime();
-            const updatedTime = new Date(comment.updatedAt).getTime();
-            const isNewOrEdited = createdTime > lastCheckedAt || updatedTime > lastCheckedAt;
-            expect(isNewOrEdited).toBe(true);
-        });
-        it('should detect comments with updatedAt exactly equal to lastCheckedAt as not new', () => {
-            const comment = {
-                id: '1',
-                author: { login: 'reviewer1' },
-                body: 'Comment at boundary',
-                createdAt: '2024-01-01T11:00:00Z',
-                updatedAt: '2024-01-01T12:00:00Z',
-                url: 'https://github.com/test/pr/1',
-            };
-            const createdTime = new Date(comment.createdAt).getTime();
-            const updatedTime = new Date(comment.updatedAt).getTime();
-            const isNewOrEdited = createdTime > lastCheckedAt || updatedTime > lastCheckedAt;
-            expect(isNewOrEdited).toBe(false);
+    it('waits when CI is not in terminal state (PENDING)', () => {
+        const decision = ratchetService.decideRatchetAction({
+            workspace: { ratchetEnabled: true },
+            prStateInfo: { prState: 'OPEN', ciStatus: CIStatus.PENDING },
+            isCleanPrWithNoNewReviewActivity: false,
+            activeRatchetSession: null,
+            hasStateChangedSinceLastDispatch: true,
+            hasOtherActiveSession: false,
         });
-        it('should not detect old unedited comments', () => {
-            const comment = {
-                id: '1',
-                author: { login: 'reviewer1' },
-                body: 'Old unedited comment',
-                createdAt: '2024-01-01T10:00:00Z',
-                updatedAt: '2024-01-01T10:00:00Z',
-                url: 'https://github.com/test/pr/1',
-            };
-            const createdTime = new Date(comment.createdAt).getTime();
-            const updatedTime = new Date(comment.updatedAt).getTime();
-            const isNewOrEdited = createdTime > lastCheckedAt || updatedTime > lastCheckedAt;
-            expect(isNewOrEdited).toBe(false);
+        expect(decision).toEqual({
+            type: 'RETURN_ACTION',
+            action: { type: 'WAITING', reason: 'Waiting for CI to complete (not in terminal state)' },
         });
     });
-    describe('Reviewer filtering with edited comments', () => {
-        it('should apply reviewer filter to edited comments', () => {
-            const allowedReviewers = ['reviewer1', 'reviewer2'];
-            const filterByReviewer = allowedReviewers.length > 0;
-            const comments = [
-                {
-                    id: '1',
-                    author: { login: 'reviewer1' },
-                    body: 'Allowed reviewer edit',
-                    createdAt: '2024-01-01T11:00:00Z',
-                    updatedAt: '2024-01-01T13:00:00Z',
-                    url: 'https://github.com/test/pr/1',
-                },
-                {
-                    id: '2',
-                    author: { login: 'reviewer3' },
-                    body: 'Disallowed reviewer edit',
-                    createdAt: '2024-01-01T11:00:00Z',
-                    updatedAt: '2024-01-01T13:00:00Z',
-                    url: 'https://github.com/test/pr/2',
-                },
-            ];
-            const filteredComments = comments.filter((comment) => {
-                const createdTime = new Date(comment.createdAt).getTime();
-                const updatedTime = new Date(comment.updatedAt).getTime();
-                const isNewOrEdited = createdTime > lastCheckedAt || updatedTime > lastCheckedAt;
-                const isAllowedReviewer = !filterByReviewer || allowedReviewers.includes(comment.author.login);
-                return isNewOrEdited && isAllowedReviewer;
-            });
-            expect(filteredComments).toHaveLength(1);
-            expect(filteredComments[0].author.login).toBe('reviewer1');
+    it('waits when CI is not in terminal state (UNKNOWN)', () => {
+        const decision = ratchetService.decideRatchetAction({
+            workspace: { ratchetEnabled: true },
+            prStateInfo: { prState: 'OPEN', ciStatus: CIStatus.UNKNOWN },
+            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)' },
+        });
+    });
+    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,
+        };
+        const prStateInfo = {
+            ciStatus: CIStatus.SUCCESS,
+            snapshotKey: 'next-snapshot',
+            hasChangesRequested: false,
+            latestReviewActivityAtMs: null,
+            statusCheckRollup: null,
+            prState: 'OPEN',
+            prNumber: 10,
+        };
+        const logContext = ratchetService.buildRatchetingLogContext(workspace, RatchetState.READY, RatchetState.READY, { type: 'WAITING', reason: 'noop' }, prStateInfo, 10, { hasNewReviewActivitySinceLastDispatch: true });
+        expect(logContext.reviewTimestampComparison.hasNewReviewActivitySinceLastDispatch).toBe(true);
+    });
+    it('ignores review activity authored by the authenticated user', () => {
+        const latestActivity = ratchetService.computeLatestReviewActivityAtMs({
+            reviews: [
+                { submittedAt: '2026-01-02T00:00:00Z', author: { login: 'ratchet-bot' } },
+                { submittedAt: '2026-01-01T00:00:00Z', author: { login: 'reviewer' } },
+            ],
+            comments: [{ updatedAt: '2026-01-02T01:00:00Z', author: { login: 'ratchet-bot' } }],
+        }, [{ updatedAt: '2026-01-01T02:00:00Z', author: { login: 'reviewer2' } }], 'ratchet-bot');
+        expect(latestActivity).toBe(new Date('2026-01-01T02:00:00Z').getTime());
     });
 });
 //# sourceMappingURL=ratchet.service.test.js.map