factory-factory 0.3.21 → 0.4.1

package/dist/src/backend/services/workspace/resources/workspace.accessor.test.js

@@ -2,19 +2,25 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 const mockCreate = vi.fn();
 const mockFindMany = vi.fn();
 const mockFindUnique = vi.fn();
+const mockFindUniqueOrThrow = vi.fn();
 const mockFindFirst = vi.fn();
+const mockUpdate = vi.fn();
 const mockUpdateMany = vi.fn();
 const mockExecuteRaw = vi.fn();
+const mockTransaction = vi.fn();
 vi.mock('@/backend/db', () => ({
     prisma: {
         workspace: {
             create: (...args) => mockCreate(...args),
             findMany: (...args) => mockFindMany(...args),
             findUnique: (...args) => mockFindUnique(...args),
+            findUniqueOrThrow: (...args) => mockFindUniqueOrThrow(...args),
             findFirst: (...args) => mockFindFirst(...args),
+            update: (...args) => mockUpdate(...args),
             updateMany: (...args) => mockUpdateMany(...args),
         },
         $executeRaw: (...args) => mockExecuteRaw(...args),
+        $transaction: (...args) => mockTransaction(...args),
     },
 }));
 import { workspaceAccessor } from './workspace.accessor.js';
@@ -79,6 +85,160 @@ describe('workspaceAccessor', () => {
             include: { project: true },
         });
     });
+    describe('PR discovery scheduling', () => {
+        it('finds a bounded due set with GitHub metadata and reset candidates first', async () => {
+            const dueAt = new Date('2026-07-17T12:00:00.000Z');
+            mockFindMany.mockResolvedValue([]);
+            await workspaceAccessor.findNeedingPRDiscovery(25, dueAt);
+            expect(mockFindMany).toHaveBeenCalledWith({
+                where: {
+                    status: 'READY',
+                    prUrl: null,
+                    branchName: { not: null },
+                    project: {
+                        githubOwner: { not: null },
+                        githubRepo: { not: null },
+                    },
+                    OR: [{ prDiscoveryNextCheckAt: null }, { prDiscoveryNextCheckAt: { lte: dueAt } }],
+                },
+                include: { project: true },
+                orderBy: [{ prDiscoveryNextCheckAt: 'asc' }, { updatedAt: 'desc' }],
+                take: 25,
+            });
+        });
+        it('uses the current time as the default due threshold', async () => {
+            const now = new Date('2026-07-17T12:00:00.000Z');
+            vi.useFakeTimers();
+            vi.setSystemTime(now);
+            mockFindMany.mockResolvedValue([]);
+            try {
+                await workspaceAccessor.findNeedingPRDiscovery(10);
+            }
+            finally {
+                vi.useRealTimers();
+            }
+            expect(mockFindMany).toHaveBeenCalledWith(expect.objectContaining({
+                where: expect.objectContaining({
+                    OR: [{ prDiscoveryNextCheckAt: null }, { prDiscoveryNextCheckAt: { lte: now } }],
+                }),
+            }));
+        });
+        it('claims an attempt only while all observed eligibility values still match', async () => {
+            const expectedUpdatedAt = new Date('2026-07-17T11:59:00.000Z');
+            const expectedNextCheckAt = new Date('2026-07-17T11:58:00.000Z');
+            const checkedAt = new Date('2026-07-17T12:00:00.000Z');
+            const nextCheckAt = new Date('2026-07-17T12:06:00.000Z');
+            mockUpdateMany.mockResolvedValue({ count: 1 });
+            await expect(workspaceAccessor.claimPRDiscoveryAttempt('ws-1', {
+                branchName: 'feature/pr-discovery',
+                expectedUpdatedAt,
+                expectedRetryCount: 1,
+                expectedNextCheckAt,
+                checkedAt,
+                nextCheckAt,
+            })).resolves.toBe(true);
+            expect(mockUpdateMany).toHaveBeenCalledWith({
+                where: {
+                    id: 'ws-1',
+                    status: 'READY',
+                    prUrl: null,
+                    branchName: 'feature/pr-discovery',
+                    updatedAt: expectedUpdatedAt,
+                    prDiscoveryRetryCount: 1,
+                    prDiscoveryNextCheckAt: expectedNextCheckAt,
+                },
+                data: {
+                    prDiscoveryLastCheckedAt: checkedAt,
+                    prDiscoveryRetryCount: { increment: 1 },
+                    prDiscoveryNextCheckAt: nextCheckAt,
+                },
+            });
+        });
+        it('guards a claim whose observed next-check timestamp was null', async () => {
+            const expectedUpdatedAt = new Date('2026-07-17T11:59:00.000Z');
+            const checkedAt = new Date('2026-07-17T12:00:00.000Z');
+            const nextCheckAt = new Date('2026-07-17T12:03:00.000Z');
+            mockUpdateMany.mockResolvedValue({ count: 0 });
+            await expect(workspaceAccessor.claimPRDiscoveryAttempt('ws-1', {
+                branchName: 'feature/pr-discovery',
+                expectedUpdatedAt,
+                expectedRetryCount: 0,
+                expectedNextCheckAt: null,
+                checkedAt,
+                nextCheckAt,
+            })).resolves.toBe(false);
+            expect(mockUpdateMany).toHaveBeenCalledWith(expect.objectContaining({
+                where: expect.objectContaining({ prDiscoveryNextCheckAt: null }),
+            }));
+        });
+        it('attaches a discovered PR only while the exact discovery claim remains current', async () => {
+            const checkedAt = new Date('2026-07-17T12:00:00.000Z');
+            const nextCheckAt = new Date('2026-07-17T12:06:00.000Z');
+            const prUpdatedAt = new Date('2026-07-17T12:01:00.000Z');
+            mockUpdateMany.mockResolvedValue({ count: 1 });
+            await expect(workspaceAccessor.attachDiscoveredPRIfClaimMatches('ws-1', 'https://github.com/org/repo/pull/12', {
+                branchName: 'feature/pr-discovery',
+                checkedAt,
+                retryCount: 2,
+                nextCheckAt,
+            }, prUpdatedAt)).resolves.toBe(true);
+            expect(mockUpdateMany).toHaveBeenCalledWith({
+                where: {
+                    id: 'ws-1',
+                    status: 'READY',
+                    prUrl: null,
+                    branchName: 'feature/pr-discovery',
+                    prDiscoveryLastCheckedAt: checkedAt,
+                    prDiscoveryRetryCount: 2,
+                    prDiscoveryNextCheckAt: nextCheckAt,
+                },
+                data: {
+                    prUrl: 'https://github.com/org/repo/pull/12',
+                    prUpdatedAt,
+                },
+            });
+        });
+        it('updates a discovered PR snapshot only while its URL remains attached', async () => {
+            const prUpdatedAt = new Date('2026-07-17T12:02:00.000Z');
+            mockUpdateMany.mockResolvedValue({ count: 1 });
+            await expect(workspaceAccessor.updatePRSnapshotIfUrlMatches('ws-1', 'https://github.com/org/repo/pull/12', {
+                prNumber: 12,
+                prState: 'OPEN',
+                prReviewState: 'APPROVED',
+                prCiStatus: 'SUCCESS',
+            }, prUpdatedAt)).resolves.toBe(true);
+            expect(mockUpdateMany).toHaveBeenCalledWith({
+                where: {
+                    id: 'ws-1',
+                    prUrl: 'https://github.com/org/repo/pull/12',
+                },
+                data: {
+                    prNumber: 12,
+                    prState: 'OPEN',
+                    prReviewState: 'APPROVED',
+                    prCiStatus: 'SUCCESS',
+                    prUpdatedAt,
+                },
+            });
+        });
+        it('resets discovery backoff only while the workspace remains eligible', async () => {
+            mockUpdateMany.mockResolvedValue({ count: 1 });
+            await expect(workspaceAccessor.resetPRDiscoveryBackoff('ws-1')).resolves.toBe(true);
+            expect(mockUpdateMany).toHaveBeenCalledWith({
+                where: {
+                    id: 'ws-1',
+                    status: 'READY',
+                    prUrl: null,
+                    branchName: { not: null },
+                },
+                data: {
+                    prDiscoveryLastCheckedAt: null,
+                    prDiscoveryRetryCount: 0,
+                    prDiscoveryNextCheckAt: null,
+                },
+            });
+        });
+    });
     it('marks workspace as having had sessions with guarded updateMany', async () => {
         mockUpdateMany.mockResolvedValue({ count: 1 });
         await workspaceAccessor.markHasHadSessions('ws-1');
@@ -87,6 +247,445 @@ describe('workspaceAccessor', () => {
             data: { hasHadSessions: true },
         });
     });
+    it('records ratchet dispatch only when ratchet is enabled', async () => {
+        mockUpdateMany.mockResolvedValue({ count: 1 });
+        await expect(workspaceAccessor.recordRatchetDispatchIfEnabled('ws-1', {
+            sessionId: 'session-1',
+            snapshotKey: 'snapshot-1',
+            retryCount: 2,
+        })).resolves.toBe(true);
+        expect(mockUpdateMany).toHaveBeenCalledWith({
+            where: { id: 'ws-1', ratchetEnabled: true },
+            data: {
+                ratchetActiveSessionId: 'session-1',
+                ratchetLastCiRunId: 'snapshot-1',
+                ratchetDispatchOutcome: 'RUNNING',
+                ratchetDispatchRetryCount: 2,
+            },
+        });
+    });
+    it('returns false when ratchet dispatch conditional update affects no rows', async () => {
+        mockUpdateMany.mockResolvedValue({ count: 0 });
+        await expect(workspaceAccessor.recordRatchetDispatchIfEnabled('ws-1', {
+            sessionId: 'session-1',
+            snapshotKey: 'snapshot-1',
+            retryCount: 0,
+        })).resolves.toBe(false);
+    });
+    it('adopts an already-running fixer session without touching the dispatch snapshot', async () => {
+        mockUpdateMany.mockResolvedValue({ count: 1 });
+        await expect(workspaceAccessor.adoptRatchetActiveSessionIfEnabled('ws-1', 'session-1')).resolves.toBe(true);
+        expect(mockUpdateMany).toHaveBeenCalledWith({
+            where: { id: 'ws-1', ratchetEnabled: true },
+            data: { ratchetActiveSessionId: 'session-1', ratchetDispatchOutcome: 'RUNNING' },
+        });
+    });
+    it('settles ratchet session end only when the pointer still matches', async () => {
+        mockUpdateMany.mockResolvedValue({ count: 1 });
+        await expect(workspaceAccessor.recordRatchetSessionEnd('ws-1', 'session-1', 'DIED')).resolves.toBe(true);
+        expect(mockUpdateMany).toHaveBeenCalledWith({
+            where: { id: 'ws-1', ratchetActiveSessionId: 'session-1' },
+            data: { ratchetActiveSessionId: null, ratchetDispatchOutcome: 'DIED' },
+        });
+    });
+    it('atomically persists a changed PR aggregate with settled dispatch reset', async () => {
+        const currentUpdatedAt = new Date('2026-07-17T11:59:00.000Z');
+        const prUpdatedAt = new Date('2026-07-17T12:00:00.000Z');
+        mockFindUnique.mockResolvedValue({
+            prUrl: null,
+            prNumber: 41,
+            prState: 'CHANGES_REQUESTED',
+            prCiStatus: 'FAILURE',
+            prReviewState: 'CHANGES_REQUESTED',
+            prUpdatedAt: currentUpdatedAt,
+            ratchetActiveSessionId: null,
+            ratchetLastCiRunId: 'failed:41',
+            ratchetDispatchOutcome: 'DIED',
+            ratchetDispatchRetryCount: 3,
+        });
+        mockUpdateMany.mockResolvedValue({ count: 1 });
+        mockTransaction.mockImplementation(async (callback) => callback({
+            workspace: {
+                findUniqueOrThrow: mockFindUnique,
+                update: mockUpdate,
+                updateMany: mockUpdateMany,
+            },
+        }));
+        await expect(workspaceAccessor.applyPrSnapshotWithDispatchReset('ws-1', {
+            prNumber: 42,
+            prState: 'OPEN',
+            prCiStatus: 'PENDING',
+            prReviewState: 'CHANGES_REQUESTED',
+            prUpdatedAt,
+        })).resolves.toEqual({ applied: true, dispatchReset: true });
+        expect(mockUpdateMany).toHaveBeenCalledWith({
+            where: {
+                id: 'ws-1',
+                prUrl: null,
+                prNumber: 41,
+                prState: 'CHANGES_REQUESTED',
+                prReviewState: 'CHANGES_REQUESTED',
+                prCiStatus: 'FAILURE',
+                prUpdatedAt: currentUpdatedAt,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: 'failed:41',
+                ratchetDispatchOutcome: 'DIED',
+                ratchetDispatchRetryCount: 3,
+            },
+            data: {
+                prNumber: 42,
+                prState: 'OPEN',
+                prCiStatus: 'PENDING',
+                prReviewState: 'CHANGES_REQUESTED',
+                prUpdatedAt,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
+            },
+        });
+        expect(mockUpdate).not.toHaveBeenCalled();
+    });
+    it('preserves a RUNNING dispatch that wins the reset compare-and-swap', async () => {
+        const currentUpdatedAt = new Date('2026-07-17T11:59:00.000Z');
+        const prUpdatedAt = new Date('2026-07-17T12:00:00.000Z');
+        mockFindUnique.mockResolvedValue({
+            prUrl: null,
+            prNumber: 41,
+            prState: 'CHANGES_REQUESTED',
+            prCiStatus: 'FAILURE',
+            prReviewState: 'CHANGES_REQUESTED',
+            prUpdatedAt: currentUpdatedAt,
+            ratchetActiveSessionId: null,
+            ratchetLastCiRunId: 'old-snapshot',
+            ratchetDispatchOutcome: 'DIED',
+            ratchetDispatchRetryCount: 3,
+        });
+        mockUpdateMany.mockResolvedValueOnce({ count: 0 }).mockResolvedValueOnce({ count: 1 });
+        mockTransaction.mockImplementation(async (callback) => callback({
+            workspace: {
+                findUniqueOrThrow: mockFindUnique,
+                update: mockUpdate,
+                updateMany: mockUpdateMany,
+            },
+        }));
+        await expect(workspaceAccessor.applyPrSnapshotWithDispatchReset('ws-1', {
+            prNumber: 42,
+            prState: 'OPEN',
+            prCiStatus: 'PENDING',
+            prReviewState: 'CHANGES_REQUESTED',
+            prUpdatedAt,
+        })).resolves.toEqual({ applied: true, dispatchReset: false });
+        expect(mockUpdateMany).toHaveBeenCalledWith({
+            where: {
+                id: 'ws-1',
+                prUrl: null,
+                prNumber: 41,
+                prState: 'CHANGES_REQUESTED',
+                prReviewState: 'CHANGES_REQUESTED',
+                prCiStatus: 'FAILURE',
+                prUpdatedAt: currentUpdatedAt,
+                ratchetActiveSessionId: null,
+                ratchetLastCiRunId: 'old-snapshot',
+                ratchetDispatchOutcome: 'DIED',
+                ratchetDispatchRetryCount: 3,
+            },
+            data: expect.objectContaining({
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
+            }),
+        });
+        expect(mockUpdateMany).toHaveBeenLastCalledWith({
+            where: {
+                id: 'ws-1',
+                prUrl: null,
+                prNumber: 41,
+                prState: 'CHANGES_REQUESTED',
+                prReviewState: 'CHANGES_REQUESTED',
+                prCiStatus: 'FAILURE',
+                prUpdatedAt: currentUpdatedAt,
+            },
+            data: {
+                prNumber: 42,
+                prState: 'OPEN',
+                prCiStatus: 'PENDING',
+                prReviewState: 'CHANGES_REQUESTED',
+                prUpdatedAt,
+            },
+        });
+        expect(mockUpdate).not.toHaveBeenCalled();
+    });
+    it('does not overwrite a newer PR aggregate when the reset and fallback guards lose', async () => {
+        const currentUpdatedAt = new Date('2026-07-17T12:00:00.000Z');
+        const observationUpdatedAt = new Date('2026-07-17T12:01:00.000Z');
+        mockFindUnique.mockResolvedValue({
+            prUrl: 'https://github.com/org/repo/pull/41',
+            prNumber: 41,
+            prState: 'CHANGES_REQUESTED',
+            prCiStatus: 'FAILURE',
+            prReviewState: 'CHANGES_REQUESTED',
+            prUpdatedAt: currentUpdatedAt,
+            ratchetActiveSessionId: null,
+            ratchetLastCiRunId: 'old-snapshot',
+            ratchetDispatchOutcome: 'DIED',
+            ratchetDispatchRetryCount: 3,
+        });
+        mockUpdateMany.mockResolvedValue({ count: 0 });
+        mockTransaction.mockImplementation(async (callback) => callback({
+            workspace: {
+                findUniqueOrThrow: mockFindUnique,
+                update: mockUpdate,
+                updateMany: mockUpdateMany,
+            },
+        }));
+        await expect(workspaceAccessor.applyPrSnapshotWithDispatchReset('ws-1', {
+            prNumber: 42,
+            prState: 'OPEN',
+            prCiStatus: 'PENDING',
+            prReviewState: null,
+            prUpdatedAt: observationUpdatedAt,
+        })).resolves.toEqual({ applied: false, dispatchReset: false });
+        expect(mockUpdateMany).toHaveBeenCalledTimes(2);
+        expect(mockUpdateMany).toHaveBeenLastCalledWith({
+            where: {
+                id: 'ws-1',
+                prUrl: 'https://github.com/org/repo/pull/41',
+                prNumber: 41,
+                prState: 'CHANGES_REQUESTED',
+                prReviewState: 'CHANGES_REQUESTED',
+                prCiStatus: 'FAILURE',
+                prUpdatedAt: currentUpdatedAt,
+            },
+            data: {
+                prNumber: 42,
+                prState: 'OPEN',
+                prCiStatus: 'PENDING',
+                prReviewState: null,
+                prUpdatedAt: observationUpdatedAt,
+            },
+        });
+        expect(mockUpdate).not.toHaveBeenCalled();
+    });
+    it('resets settled ownership for a changed direct CI observation', async () => {
+        const currentUpdatedAt = new Date('2026-07-17T11:59:00.000Z');
+        const observedAt = new Date('2026-07-17T12:00:00.000Z');
+        mockFindUnique.mockResolvedValue({
+            prUrl: 'https://github.com/org/repo/pull/42',
+            prNumber: 42,
+            prState: 'OPEN',
+            prCiStatus: 'FAILURE',
+            prReviewState: null,
+            prUpdatedAt: currentUpdatedAt,
+            ratchetActiveSessionId: null,
+            ratchetLastCiRunId: 'failure:42',
+            ratchetDispatchOutcome: 'DIED',
+            ratchetDispatchRetryCount: 3,
+        });
+        mockUpdateMany.mockResolvedValue({ count: 1 });
+        mockTransaction.mockImplementation(async (callback) => callback({
+            workspace: {
+                findUniqueOrThrow: mockFindUnique,
+                update: mockUpdate,
+                updateMany: mockUpdateMany,
+            },
+        }));
+        await expect(workspaceAccessor.applyCIObservationWithDispatchReset('ws-1', {
+            prCiStatus: 'PENDING',
+            prUpdatedAt: observedAt,
+        })).resolves.toEqual({ applied: true, dispatchReset: true });
+        expect(mockUpdateMany).toHaveBeenCalledWith({
+            where: expect.objectContaining({
+                id: 'ws-1',
+                ratchetDispatchOutcome: 'DIED',
+                ratchetDispatchRetryCount: 3,
+            }),
+            data: {
+                prCiStatus: 'PENDING',
+                prUpdatedAt: observedAt,
+                ratchetDispatchOutcome: null,
+                ratchetDispatchRetryCount: 0,
+            },
+        });
+    });
+    it('conditionally writes a cached column against the ownership tuple', async () => {
+        mockUpdateMany.mockResolvedValue({ count: 0 });
+        const prUpdatedAt = new Date('2026-07-17T12:00:00.000Z');
+        await expect(workspaceAccessor.updateCachedKanbanColumnIfOwnershipMatches('ws-1', {
+            status: 'READY',
+            prUrl: 'https://github.com/org/repo/pull/42',
+            prState: 'OPEN',
+            prCiStatus: 'PENDING',
+            prUpdatedAt,
+            ratchetEnabled: true,
+            ratchetState: 'CI_RUNNING',
+            ratchetDispatchOutcome: null,
+            ratchetDispatchRetryCount: 0,
+            cachedKanbanColumn: 'WORKING',
+        }, { cachedKanbanColumn: 'WAITING' })).resolves.toBe(false);
+        expect(mockUpdateMany).toHaveBeenCalledWith({
+            where: expect.objectContaining({ status: 'READY', prUpdatedAt }),
+            data: { cachedKanbanColumn: 'WAITING' },
+        });
+    });
+    it('persists an identical PR aggregate without clearing settled dispatch metadata', async () => {
+        const currentUpdatedAt = new Date('2026-07-17T11:59:00.000Z');
+        const prUpdatedAt = new Date('2026-07-17T12:00:00.000Z');
+        mockFindUnique.mockResolvedValue({
+            prUrl: 'https://github.com/org/repo/pull/42',
+            prNumber: 42,
+            prState: 'OPEN',
+            prCiStatus: 'FAILURE',
+            prReviewState: null,
+            prUpdatedAt: currentUpdatedAt,
+            ratchetDispatchOutcome: 'DIED',
+        });
+        mockUpdateMany.mockResolvedValue({ count: 1 });
+        mockTransaction.mockImplementation(async (callback) => callback({
+            workspace: {
+                findUniqueOrThrow: mockFindUnique,
+                update: mockUpdate,
+                updateMany: mockUpdateMany,
+            },
+        }));
+        await workspaceAccessor.applyPrSnapshotWithDispatchReset('ws-1', {
+            prUrl: 'https://github.com/org/repo/pull/42',
+            prNumber: 42,
+            prState: 'OPEN',
+            prCiStatus: 'FAILURE',
+            prReviewState: null,
+            prUpdatedAt,
+        });
+        expect(mockUpdateMany).toHaveBeenCalledWith({
+            where: {
+                id: 'ws-1',
+                prUrl: 'https://github.com/org/repo/pull/42',
+                prNumber: 42,
+                prState: 'OPEN',
+                prReviewState: null,
+                prCiStatus: 'FAILURE',
+                prUpdatedAt: currentUpdatedAt,
+            },
+            data: {
+                prUrl: 'https://github.com/org/repo/pull/42',
+                prNumber: 42,
+                prState: 'OPEN',
+                prCiStatus: 'FAILURE',
+                prReviewState: null,
+                prUpdatedAt,
+            },
+        });
+        expect(mockUpdate).not.toHaveBeenCalled();
+    });
+    it('finishes auto-iteration only when the session pointer still matches', async () => {
+        mockUpdateMany.mockResolvedValue({ count: 1 });
+        await expect(workspaceAccessor.finishAutoIterationIfSessionMatches('ws-1', 'session-1', 'STOPPED')).resolves.toBe(true);
+        expect(mockUpdateMany).toHaveBeenCalledWith({
+            where: { id: 'ws-1', autoIterationSessionId: 'session-1' },
+            data: {
+                autoIterationStatus: 'STOPPED',
+                autoIterationSessionId: null,
+            },
+        });
+    });
+    it('clears auto-iteration session only when the expected pointer still matches', async () => {
+        mockUpdateMany.mockResolvedValue({ count: 0 });
+        await expect(workspaceAccessor.clearAutoIterationSessionIfMatches('ws-1', 'session-1')).resolves.toBe(false);
+        expect(mockUpdateMany).toHaveBeenCalledWith({
+            where: { id: 'ws-1', autoIterationSessionId: 'session-1' },
+            data: { autoIterationSessionId: null },
+        });
+    });
+    it('selects only the auto-iteration execution context', async () => {
+        mockFindUnique.mockResolvedValue({
+            worktreePath: '/tmp/worktree',
+            autoIterationSessionId: 'session-1',
+        });
+        await expect(workspaceAccessor.findAutoIterationExecutionContext('ws-1')).resolves.toEqual({
+            worktreePath: '/tmp/worktree',
+            autoIterationSessionId: 'session-1',
+        });
+        expect(mockFindUnique).toHaveBeenCalledWith({
+            where: { id: 'ws-1' },
+            select: { worktreePath: true, autoIterationSessionId: true },
+        });
+    });
+    it('selects only run-script execution state', async () => {
+        const state = {
+            runScriptStatus: 'RUNNING',
+            runScriptPid: 123,
+            runScriptPort: 3000,
+            runScriptStartedAt: new Date('2026-01-01T00:00:00.000Z'),
+        };
+        mockFindUnique.mockResolvedValue(state);
+        await expect(workspaceAccessor.findRunScriptExecutionState('ws-1')).resolves.toEqual(state);
+        expect(mockFindUnique).toHaveBeenCalledWith({
+            where: { id: 'ws-1' },
+            select: {
+                runScriptStatus: true,
+                runScriptPid: true,
+                runScriptPort: true,
+                runScriptStartedAt: true,
+            },
+        });
+    });
+    it('selects only run-script execution state when requiring a result', async () => {
+        const state = {
+            runScriptStatus: 'RUNNING',
+            runScriptPid: 123,
+            runScriptPort: 3000,
+            runScriptStartedAt: new Date('2026-01-01T00:00:00.000Z'),
+        };
+        mockFindUniqueOrThrow.mockResolvedValue(state);
+        await expect(workspaceAccessor.findRunScriptExecutionStateOrThrow('ws-1')).resolves.toEqual(state);
+        expect(mockFindUniqueOrThrow).toHaveBeenCalledWith({
+            where: { id: 'ws-1' },
+            select: {
+                runScriptStatus: true,
+                runScriptPid: true,
+                runScriptPort: true,
+                runScriptStartedAt: true,
+            },
+        });
+    });
+    it('returns false when ratchet session end conditional update affects no rows', async () => {
+        mockUpdateMany.mockResolvedValue({ count: 0 });
+        await expect(workspaceAccessor.recordRatchetSessionEnd('ws-1', 'session-1', 'COMPLETED')).resolves.toBe(false);
+    });
+    it('transitions ratchet state only when enabled and fromState still matches', async () => {
+        const checkedAt = new Date('2026-01-01T00:00:00.000Z');
+        mockUpdateMany.mockResolvedValue({ count: 1 });
+        await expect(workspaceAccessor.transitionRatchetStateIfEnabled('ws-1', 'CI_RUNNING', {
+            ratchetState: 'CI_FAILED',
+            ratchetLastCheckedAt: checkedAt,
+        })).resolves.toBe(true);
+        expect(mockUpdateMany).toHaveBeenCalledWith({
+            where: { id: 'ws-1', ratchetEnabled: true, ratchetState: 'CI_RUNNING' },
+            data: {
+                ratchetState: 'CI_FAILED',
+                ratchetLastCheckedAt: checkedAt,
+            },
+        });
+    });
+    it('returns false when ratchet state transition loses the compare-and-swap', async () => {
+        mockUpdateMany.mockResolvedValue({ count: 0 });
+        await expect(workspaceAccessor.transitionRatchetStateIfEnabled('ws-1', 'CI_RUNNING', {
+            ratchetState: 'READY',
+            ratchetLastCheckedAt: new Date('2026-01-01T00:00:00.000Z'),
+        })).resolves.toBe(false);
+    });
+    it('settles ratchet state to IDLE only while disabled and fromState still matches', async () => {
+        mockUpdateMany.mockResolvedValue({ count: 1 });
+        await expect(workspaceAccessor.settleRatchetIdleWhileDisabled('ws-1', 'CI_FAILED')).resolves.toBe(true);
+        expect(mockUpdateMany).toHaveBeenCalledWith({
+            where: { id: 'ws-1', ratchetEnabled: false, ratchetState: 'CI_FAILED' },
+            data: {
+                ratchetState: 'IDLE',
+                ratchetLastCheckedAt: expect.any(Date),
+            },
+        });
+    });
+    it('returns false when the disabled-settle compare-and-swap affects no rows', async () => {
+        mockUpdateMany.mockResolvedValue({ count: 0 });
+        await expect(workspaceAccessor.settleRatchetIdleWhileDisabled('ws-1', 'CI_FAILED')).resolves.toBe(false);
+    });
     it('appends init output and skips existence check when update succeeds', async () => {
         mockExecuteRaw.mockResolvedValue(1);
         await workspaceAccessor.appendInitOutput('ws-1', 'hello output', 256);
@@ -198,6 +797,8 @@ describe('workspaceAccessor', () => {
                 ratchetState: true,
                 ratchetActiveSessionId: true,
                 ratchetLastCiRunId: true,
+                ratchetDispatchOutcome: true,
+                ratchetDispatchRetryCount: true,
                 prReviewLastCheckedAt: true,
             },
         });