@renseiai/agentfactory 0.8.0

package/dist/src/governor/governor.test.js

@@ -0,0 +1,514 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { WorkflowGovernor } from './governor.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeIssue(overrides = {}) {
+    return {
+        id: 'issue-1',
+        identifier: 'SUP-100',
+        title: 'Test Issue',
+        description: undefined,
+        status: 'Backlog',
+        labels: [],
+        createdAt: Date.now() - 2 * 60 * 60 * 1000,
+        ...overrides,
+    };
+}
+/**
+ * Create mock GovernorDependencies with sensible defaults.
+ * All callbacks return "no blockers" so issues are actionable by default.
+ */
+function makeMockDeps(overrides = {}) {
+    return {
+        listIssues: vi.fn().mockResolvedValue([]),
+        hasActiveSession: vi.fn().mockResolvedValue(false),
+        isWithinCooldown: vi.fn().mockResolvedValue(false),
+        isParentIssue: vi.fn().mockResolvedValue(false),
+        isHeld: vi.fn().mockResolvedValue(false),
+        getOverridePriority: vi.fn().mockResolvedValue(null),
+        getWorkflowStrategy: vi.fn().mockResolvedValue(undefined),
+        isResearchCompleted: vi.fn().mockResolvedValue(false),
+        isBacklogCreationCompleted: vi.fn().mockResolvedValue(false),
+        getCompletedSessionCount: vi.fn().mockResolvedValue(0),
+        dispatchWork: vi.fn().mockResolvedValue(undefined),
+        ...overrides,
+    };
+}
+function makeConfig(overrides = {}) {
+    return {
+        projects: ['TestProject'],
+        scanIntervalMs: 60_000,
+        maxConcurrentDispatches: 3,
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// scanOnce — basic behavior
+// ---------------------------------------------------------------------------
+describe('WorkflowGovernor.scanOnce', () => {
+    it('scans all configured projects', async () => {
+        const deps = makeMockDeps();
+        const governor = new WorkflowGovernor(makeConfig({ projects: ['Project-A', 'Project-B'] }), deps);
+        const results = await governor.scanOnce();
+        expect(results).toHaveLength(2);
+        expect(results[0].project).toBe('Project-A');
+        expect(results[1].project).toBe('Project-B');
+        expect(deps.listIssues).toHaveBeenCalledWith('Project-A');
+        expect(deps.listIssues).toHaveBeenCalledWith('Project-B');
+    });
+    it('returns empty results for project with no issues', async () => {
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue([]),
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        const results = await governor.scanOnce();
+        expect(results).toHaveLength(1);
+        expect(results[0].scannedIssues).toBe(0);
+        expect(results[0].actionsDispatched).toBe(0);
+    });
+    it('dispatches development for Backlog issues', async () => {
+        const issue = makeIssue({ status: 'Backlog' });
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue([issue]),
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        const results = await governor.scanOnce();
+        expect(results[0].actionsDispatched).toBe(1);
+        expect(deps.dispatchWork).toHaveBeenCalledWith(expect.objectContaining({ id: 'issue-1' }), 'trigger-development');
+    });
+    it('dispatches QA for Finished issues', async () => {
+        const issue = makeIssue({ status: 'Finished' });
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue([issue]),
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        const results = await governor.scanOnce();
+        expect(results[0].actionsDispatched).toBe(1);
+        expect(deps.dispatchWork).toHaveBeenCalledWith(expect.objectContaining({ id: 'issue-1' }), 'trigger-qa');
+    });
+    it('dispatches acceptance for Delivered issues', async () => {
+        const issue = makeIssue({ status: 'Delivered' });
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue([issue]),
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        const results = await governor.scanOnce();
+        expect(results[0].actionsDispatched).toBe(1);
+        expect(deps.dispatchWork).toHaveBeenCalledWith(expect.objectContaining({ id: 'issue-1' }), 'trigger-acceptance');
+    });
+    it('dispatches refinement for Rejected issues', async () => {
+        const issue = makeIssue({ status: 'Rejected' });
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue([issue]),
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        const results = await governor.scanOnce();
+        expect(results[0].actionsDispatched).toBe(1);
+        expect(deps.dispatchWork).toHaveBeenCalledWith(expect.objectContaining({ id: 'issue-1' }), 'trigger-refinement');
+    });
+    it('skips issues with active sessions', async () => {
+        const issue = makeIssue({ status: 'Backlog' });
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue([issue]),
+            hasActiveSession: vi.fn().mockResolvedValue(true),
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        const results = await governor.scanOnce();
+        expect(results[0].actionsDispatched).toBe(0);
+        expect(results[0].skippedReasons.size).toBe(1);
+        expect(deps.dispatchWork).not.toHaveBeenCalled();
+    });
+    it('skips held issues', async () => {
+        const issue = makeIssue({ status: 'Backlog' });
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue([issue]),
+            isHeld: vi.fn().mockResolvedValue(true),
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        const results = await governor.scanOnce();
+        expect(results[0].actionsDispatched).toBe(0);
+        expect(deps.dispatchWork).not.toHaveBeenCalled();
+    });
+    it('skips issues within cooldown', async () => {
+        const issue = makeIssue({ status: 'Backlog' });
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue([issue]),
+            isWithinCooldown: vi.fn().mockResolvedValue(true),
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        const results = await governor.scanOnce();
+        expect(results[0].actionsDispatched).toBe(0);
+        expect(deps.dispatchWork).not.toHaveBeenCalled();
+    });
+});
+// ---------------------------------------------------------------------------
+// maxConcurrentDispatches limiting
+// ---------------------------------------------------------------------------
+describe('WorkflowGovernor.scanOnce — dispatch limit', () => {
+    it('respects maxConcurrentDispatches limit', async () => {
+        const issues = [
+            makeIssue({ id: 'issue-1', identifier: 'SUP-1', status: 'Backlog' }),
+            makeIssue({ id: 'issue-2', identifier: 'SUP-2', status: 'Backlog' }),
+            makeIssue({ id: 'issue-3', identifier: 'SUP-3', status: 'Backlog' }),
+            makeIssue({ id: 'issue-4', identifier: 'SUP-4', status: 'Backlog' }),
+            makeIssue({ id: 'issue-5', identifier: 'SUP-5', status: 'Backlog' }),
+        ];
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue(issues),
+        });
+        const governor = new WorkflowGovernor(makeConfig({ maxConcurrentDispatches: 2 }), deps);
+        const results = await governor.scanOnce();
+        expect(results[0].actionsDispatched).toBe(2);
+        expect(deps.dispatchWork).toHaveBeenCalledTimes(2);
+    });
+    it('dispatches all when under the limit', async () => {
+        const issues = [
+            makeIssue({ id: 'issue-1', identifier: 'SUP-1', status: 'Backlog' }),
+            makeIssue({ id: 'issue-2', identifier: 'SUP-2', status: 'Finished' }),
+        ];
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue(issues),
+        });
+        const governor = new WorkflowGovernor(makeConfig({ maxConcurrentDispatches: 5 }), deps);
+        const results = await governor.scanOnce();
+        expect(results[0].actionsDispatched).toBe(2);
+        expect(deps.dispatchWork).toHaveBeenCalledTimes(2);
+    });
+    it('counts skipped issues toward scanned but not dispatched', async () => {
+        const issues = [
+            makeIssue({ id: 'issue-1', identifier: 'SUP-1', status: 'Accepted' }), // terminal
+            makeIssue({ id: 'issue-2', identifier: 'SUP-2', status: 'Backlog' }), // actionable
+        ];
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue(issues),
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        const results = await governor.scanOnce();
+        expect(results[0].scannedIssues).toBe(2);
+        expect(results[0].actionsDispatched).toBe(1);
+        expect(results[0].skippedReasons.size).toBe(1);
+    });
+});
+// ---------------------------------------------------------------------------
+// Error handling
+// ---------------------------------------------------------------------------
+describe('WorkflowGovernor.scanOnce — error handling', () => {
+    it('records error when listIssues fails', async () => {
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockRejectedValue(new Error('API timeout')),
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        const results = await governor.scanOnce();
+        expect(results[0].errors).toHaveLength(1);
+        expect(results[0].errors[0].error).toContain('API timeout');
+    });
+    it('single issue failure does not stop scan of remaining issues', async () => {
+        const issues = [
+            makeIssue({ id: 'issue-1', identifier: 'SUP-1', status: 'Backlog' }),
+            makeIssue({ id: 'issue-2', identifier: 'SUP-2', status: 'Backlog' }),
+            makeIssue({ id: 'issue-3', identifier: 'SUP-3', status: 'Backlog' }),
+        ];
+        const dispatchWork = vi.fn()
+            .mockResolvedValueOnce(undefined) // issue-1 succeeds
+            .mockRejectedValueOnce(new Error('Dispatch failed')) // issue-2 fails
+            .mockResolvedValueOnce(undefined); // issue-3 succeeds
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue(issues),
+            dispatchWork,
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        const results = await governor.scanOnce();
+        // issue-1 and issue-3 dispatched, issue-2 errored
+        expect(results[0].actionsDispatched).toBe(2);
+        expect(results[0].errors).toHaveLength(1);
+        expect(results[0].errors[0].issueId).toBe('SUP-2');
+        expect(dispatchWork).toHaveBeenCalledTimes(3);
+    });
+    it('context gathering failure is caught and recorded', async () => {
+        const issue = makeIssue({ status: 'Backlog' });
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue([issue]),
+            hasActiveSession: vi.fn().mockRejectedValue(new Error('Redis down')),
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        const results = await governor.scanOnce();
+        expect(results[0].errors).toHaveLength(1);
+        expect(results[0].errors[0].error).toContain('Redis down');
+        expect(results[0].actionsDispatched).toBe(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// Gathers context in parallel
+// ---------------------------------------------------------------------------
+describe('WorkflowGovernor.scanOnce — context gathering', () => {
+    it('calls all dependency checks for each issue', async () => {
+        const issue = makeIssue({ id: 'issue-1', status: 'Backlog' });
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue([issue]),
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        await governor.scanOnce();
+        expect(deps.hasActiveSession).toHaveBeenCalledWith('issue-1');
+        expect(deps.isWithinCooldown).toHaveBeenCalledWith('issue-1');
+        expect(deps.isParentIssue).toHaveBeenCalledWith('issue-1');
+        expect(deps.isHeld).toHaveBeenCalledWith('issue-1');
+        expect(deps.getWorkflowStrategy).toHaveBeenCalledWith('issue-1');
+        expect(deps.isResearchCompleted).toHaveBeenCalledWith('issue-1');
+        expect(deps.isBacklogCreationCompleted).toHaveBeenCalledWith('issue-1');
+    });
+});
+// ---------------------------------------------------------------------------
+// start / stop lifecycle
+// ---------------------------------------------------------------------------
+describe('WorkflowGovernor — start/stop lifecycle', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('isRunning returns false before start', () => {
+        const deps = makeMockDeps();
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        expect(governor.isRunning()).toBe(false);
+    });
+    it('isRunning returns true after start', () => {
+        const deps = makeMockDeps();
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        governor.start();
+        expect(governor.isRunning()).toBe(true);
+        governor.stop();
+    });
+    it('isRunning returns false after stop', () => {
+        const deps = makeMockDeps();
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        governor.start();
+        governor.stop();
+        expect(governor.isRunning()).toBe(false);
+    });
+    it('start triggers an immediate scan', async () => {
+        const deps = makeMockDeps();
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        governor.start();
+        // Flush the fire-and-forget scanOnce by allowing the promise microtask to resolve
+        await vi.advanceTimersByTimeAsync(1);
+        expect(deps.listIssues).toHaveBeenCalledTimes(1);
+        governor.stop();
+    });
+    it('subsequent scans run on the configured interval', async () => {
+        const deps = makeMockDeps();
+        const governor = new WorkflowGovernor(makeConfig({ scanIntervalMs: 5000 }), deps);
+        governor.start();
+        // First immediate scan
+        await vi.advanceTimersByTimeAsync(1);
+        expect(deps.listIssues).toHaveBeenCalledTimes(1);
+        // Advance by one interval
+        await vi.advanceTimersByTimeAsync(5000);
+        expect(deps.listIssues).toHaveBeenCalledTimes(2);
+        // Advance by another interval
+        await vi.advanceTimersByTimeAsync(5000);
+        expect(deps.listIssues).toHaveBeenCalledTimes(3);
+        governor.stop();
+    });
+    it('stop prevents further scans', async () => {
+        const deps = makeMockDeps();
+        const governor = new WorkflowGovernor(makeConfig({ scanIntervalMs: 5000 }), deps);
+        governor.start();
+        await vi.advanceTimersByTimeAsync(1);
+        expect(deps.listIssues).toHaveBeenCalledTimes(1);
+        governor.stop();
+        await vi.advanceTimersByTimeAsync(10000);
+        // No additional calls after stop
+        expect(deps.listIssues).toHaveBeenCalledTimes(1);
+    });
+    it('calling start twice does not create duplicate intervals', async () => {
+        const deps = makeMockDeps();
+        const governor = new WorkflowGovernor(makeConfig({ scanIntervalMs: 5000 }), deps);
+        governor.start();
+        governor.start(); // second call should be a no-op
+        await vi.advanceTimersByTimeAsync(1);
+        expect(deps.listIssues).toHaveBeenCalledTimes(1);
+        await vi.advanceTimersByTimeAsync(5000);
+        // Only 1 interval fires, not 2
+        expect(deps.listIssues).toHaveBeenCalledTimes(2);
+        governor.stop();
+    });
+    it('calling stop when not running is safe', () => {
+        const deps = makeMockDeps();
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        // Should not throw
+        expect(() => governor.stop()).not.toThrow();
+    });
+});
+// ---------------------------------------------------------------------------
+// Multiple projects
+// ---------------------------------------------------------------------------
+describe('WorkflowGovernor.scanOnce — multiple projects', () => {
+    it('scans each project independently', async () => {
+        const projectAIssues = [
+            makeIssue({ id: 'a-1', identifier: 'A-1', status: 'Backlog', project: 'Project-A' }),
+        ];
+        const projectBIssues = [
+            makeIssue({ id: 'b-1', identifier: 'B-1', status: 'Finished', project: 'Project-B' }),
+            makeIssue({ id: 'b-2', identifier: 'B-2', status: 'Delivered', project: 'Project-B' }),
+        ];
+        const listIssues = vi.fn()
+            .mockImplementation((project) => {
+            if (project === 'Project-A')
+                return Promise.resolve(projectAIssues);
+            if (project === 'Project-B')
+                return Promise.resolve(projectBIssues);
+            return Promise.resolve([]);
+        });
+        const deps = makeMockDeps({ listIssues });
+        const governor = new WorkflowGovernor(makeConfig({ projects: ['Project-A', 'Project-B'] }), deps);
+        const results = await governor.scanOnce();
+        expect(results).toHaveLength(2);
+        expect(results[0].project).toBe('Project-A');
+        expect(results[0].actionsDispatched).toBe(1);
+        expect(results[1].project).toBe('Project-B');
+        expect(results[1].actionsDispatched).toBe(2);
+    });
+    it('dispatch limit is per-project', async () => {
+        const issues = [
+            makeIssue({ id: 'issue-1', identifier: 'SUP-1', status: 'Backlog' }),
+            makeIssue({ id: 'issue-2', identifier: 'SUP-2', status: 'Backlog' }),
+            makeIssue({ id: 'issue-3', identifier: 'SUP-3', status: 'Backlog' }),
+        ];
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue(issues),
+        });
+        const governor = new WorkflowGovernor(makeConfig({
+            projects: ['Project-A', 'Project-B'],
+            maxConcurrentDispatches: 1,
+        }), deps);
+        const results = await governor.scanOnce();
+        // Each project dispatches 1 (the limit), total 2
+        expect(results[0].actionsDispatched).toBe(1);
+        expect(results[1].actionsDispatched).toBe(1);
+        expect(deps.dispatchWork).toHaveBeenCalledTimes(2);
+    });
+});
+// ---------------------------------------------------------------------------
+// Mixed statuses in a single scan
+// ---------------------------------------------------------------------------
+describe('WorkflowGovernor.scanOnce — mixed statuses', () => {
+    it('handles a mix of actionable and non-actionable issues', async () => {
+        const issues = [
+            makeIssue({ id: 'i-1', identifier: 'SUP-1', status: 'Accepted' }), // terminal
+            makeIssue({ id: 'i-2', identifier: 'SUP-2', status: 'Backlog' }), // actionable
+            makeIssue({ id: 'i-3', identifier: 'SUP-3', status: 'Started' }), // not actionable (already working)
+            makeIssue({ id: 'i-4', identifier: 'SUP-4', status: 'Finished' }), // actionable
+            makeIssue({ id: 'i-5', identifier: 'SUP-5', status: 'Canceled' }), // terminal
+        ];
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue(issues),
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        const results = await governor.scanOnce();
+        expect(results[0].scannedIssues).toBe(5);
+        expect(results[0].actionsDispatched).toBe(2); // Backlog + Finished
+        expect(results[0].skippedReasons.size).toBe(3); // Accepted + Started + Canceled
+    });
+});
+// ---------------------------------------------------------------------------
+// PRIORITY override affects processing order
+// ---------------------------------------------------------------------------
+describe('WorkflowGovernor.scanOnce — PRIORITY override sorting', () => {
+    it('dispatches high-priority issues before low-priority ones', async () => {
+        const issues = [
+            makeIssue({ id: 'low-1', identifier: 'SUP-1', status: 'Backlog' }),
+            makeIssue({ id: 'high-1', identifier: 'SUP-2', status: 'Backlog' }),
+            makeIssue({ id: 'med-1', identifier: 'SUP-3', status: 'Backlog' }),
+        ];
+        const getOverridePriority = vi.fn().mockImplementation((issueId) => {
+            if (issueId === 'high-1')
+                return Promise.resolve('high');
+            if (issueId === 'med-1')
+                return Promise.resolve('medium');
+            if (issueId === 'low-1')
+                return Promise.resolve('low');
+            return Promise.resolve(null);
+        });
+        const dispatchWork = vi.fn().mockResolvedValue(undefined);
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue(issues),
+            getOverridePriority,
+            dispatchWork,
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        await governor.scanOnce();
+        expect(dispatchWork).toHaveBeenCalledTimes(3);
+        // high-1 dispatched first, then med-1, then low-1
+        expect(dispatchWork.mock.calls[0][0]).toEqual(expect.objectContaining({ id: 'high-1' }));
+        expect(dispatchWork.mock.calls[1][0]).toEqual(expect.objectContaining({ id: 'med-1' }));
+        expect(dispatchWork.mock.calls[2][0]).toEqual(expect.objectContaining({ id: 'low-1' }));
+    });
+    it('dispatches priority-overridden issues before non-overridden ones', async () => {
+        const issues = [
+            makeIssue({ id: 'none-1', identifier: 'SUP-1', status: 'Backlog' }),
+            makeIssue({ id: 'none-2', identifier: 'SUP-2', status: 'Backlog' }),
+            makeIssue({ id: 'high-1', identifier: 'SUP-3', status: 'Backlog' }),
+        ];
+        const getOverridePriority = vi.fn().mockImplementation((issueId) => {
+            if (issueId === 'high-1')
+                return Promise.resolve('high');
+            return Promise.resolve(null);
+        });
+        const dispatchWork = vi.fn().mockResolvedValue(undefined);
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue(issues),
+            getOverridePriority,
+            dispatchWork,
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        await governor.scanOnce();
+        expect(dispatchWork).toHaveBeenCalledTimes(3);
+        // high-1 dispatched first, regardless of list order
+        expect(dispatchWork.mock.calls[0][0]).toEqual(expect.objectContaining({ id: 'high-1' }));
+    });
+    it('priority sorting affects which issues get dispatched under the limit', async () => {
+        const issues = [
+            makeIssue({ id: 'none-1', identifier: 'SUP-1', status: 'Backlog' }),
+            makeIssue({ id: 'none-2', identifier: 'SUP-2', status: 'Backlog' }),
+            makeIssue({ id: 'high-1', identifier: 'SUP-3', status: 'Backlog' }),
+        ];
+        const getOverridePriority = vi.fn().mockImplementation((issueId) => {
+            if (issueId === 'high-1')
+                return Promise.resolve('high');
+            return Promise.resolve(null);
+        });
+        const dispatchWork = vi.fn().mockResolvedValue(undefined);
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue(issues),
+            getOverridePriority,
+            dispatchWork,
+        });
+        // Only dispatch 1 — the high-priority issue should win
+        const governor = new WorkflowGovernor(makeConfig({ maxConcurrentDispatches: 1 }), deps);
+        await governor.scanOnce();
+        expect(dispatchWork).toHaveBeenCalledTimes(1);
+        expect(dispatchWork.mock.calls[0][0]).toEqual(expect.objectContaining({ id: 'high-1' }));
+    });
+    it('issues with equal priority maintain stable order', async () => {
+        const issues = [
+            makeIssue({ id: 'a', identifier: 'SUP-1', status: 'Backlog' }),
+            makeIssue({ id: 'b', identifier: 'SUP-2', status: 'Backlog' }),
+            makeIssue({ id: 'c', identifier: 'SUP-3', status: 'Backlog' }),
+        ];
+        // All have no priority override
+        const dispatchWork = vi.fn().mockResolvedValue(undefined);
+        const deps = makeMockDeps({
+            listIssues: vi.fn().mockResolvedValue(issues),
+            dispatchWork,
+        });
+        const governor = new WorkflowGovernor(makeConfig(), deps);
+        await governor.scanOnce();
+        expect(dispatchWork).toHaveBeenCalledTimes(3);
+        // Original order preserved for equal priority
+        expect(dispatchWork.mock.calls[0][0]).toEqual(expect.objectContaining({ id: 'a' }));
+        expect(dispatchWork.mock.calls[1][0]).toEqual(expect.objectContaining({ id: 'b' }));
+        expect(dispatchWork.mock.calls[2][0]).toEqual(expect.objectContaining({ id: 'c' }));
+    });
+});

package/dist/src/governor/human-touchpoints.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Human Touchpoint Manager
+ *
+ * Manages human override state and generates review request notifications.
+ * Uses a storage adapter pattern so that packages/core does not depend on
+ * packages/server (Redis) directly.
+ */
+import type { OverrideDirective, OverridePriority } from './override-parser.js';
+/**
+ * Persisted override state for an issue
+ */
+export interface OverrideState {
+    issueId: string;
+    directive: OverrideDirective;
+    isActive: boolean;
+    expiresAt?: number;
+}
+/**
+ * Configuration for touchpoint timeouts
+ */
+export interface TouchpointConfig {
+    /** Timeout for review requests (default: 4 hours) */
+    reviewRequestTimeoutMs: number;
+    /** Timeout for decomposition proposals (default: 2 hours) */
+    decompositionProposalTimeoutMs: number;
+    /** Timeout for escalation alerts (default: Infinity — requires human response) */
+    escalationTimeoutMs: number;
+}
+/**
+ * Default touchpoint configuration
+ */
+export declare const DEFAULT_TOUCHPOINT_CONFIG: TouchpointConfig;
+/**
+ * Types of human touchpoint notifications
+ */
+export type TouchpointType = 'review-request' | 'decomposition-proposal' | 'escalation-alert';
+/**
+ * A notification posted to an issue requesting human attention
+ */
+export interface TouchpointNotification {
+    type: TouchpointType;
+    issueId: string;
+    body: string;
+    postedAt: number;
+    timeoutMs: number;
+    respondedAt?: number;
+}
+/**
+ * Storage adapter for override state persistence.
+ * Implementations can back this with Redis, in-memory maps, etc.
+ */
+export interface OverrideStorage {
+    get(issueId: string): Promise<OverrideState | null>;
+    set(issueId: string, state: OverrideState): Promise<void>;
+    clear(issueId: string): Promise<void>;
+}
+/**
+ * In-memory override storage for testing and local development
+ */
+export declare class InMemoryOverrideStorage implements OverrideStorage {
+    private store;
+    get(issueId: string): Promise<OverrideState | null>;
+    set(issueId: string, state: OverrideState): Promise<void>;
+    clear(issueId: string): Promise<void>;
+}
+/**
+ * Initialize the touchpoint manager with a storage adapter.
+ * Must be called before using state management functions.
+ */
+export declare function initTouchpointStorage(storage: OverrideStorage): void;
+/**
+ * Get the current override state for an issue
+ */
+export declare function getOverrideState(issueId: string): Promise<OverrideState | null>;
+/**
+ * Set an override directive for an issue
+ */
+export declare function setOverrideState(issueId: string, directive: OverrideDirective): Promise<void>;
+/**
+ * Clear the override state for an issue (e.g., on RESUME)
+ */
+export declare function clearOverrideState(issueId: string): Promise<void>;
+/**
+ * Check if an issue is currently held (HOLD directive active)
+ */
+export declare function isHeld(issueId: string): Promise<boolean>;
+/**
+ * Get the PRIORITY override for an issue, if one is active.
+ * Returns the priority level ('high' | 'medium' | 'low') or null if no priority override.
+ */
+export declare function getOverridePriority(issueId: string): Promise<OverridePriority | null>;
+/**
+ * Generate a review request notification.
+ * Typically posted at cycle 2 when the context-enriched strategy kicks in.
+ */
+export declare function generateReviewRequest(context: {
+    issueIdentifier: string;
+    cycleCount: number;
+    failureSummary: string;
+    strategy: string;
+    totalCostUsd?: number;
+}, config?: TouchpointConfig): TouchpointNotification;
+/**
+ * Generate a decomposition proposal notification.
+ * Typically posted at cycle 3 when the decompose strategy kicks in.
+ */
+export declare function generateDecompositionProposal(context: {
+    issueIdentifier: string;
+    cycleCount: number;
+    failureSummary: string;
+    totalCostUsd?: number;
+}, config?: TouchpointConfig): TouchpointNotification;
+/**
+ * Generate an escalation alert notification.
+ * Posted at cycle 4+ when human intervention is required.
+ */
+export declare function generateEscalationAlert(context: {
+    issueIdentifier: string;
+    cycleCount: number;
+    failureSummary: string;
+    totalCostUsd?: number;
+    blockerIdentifier?: string;
+}, config?: TouchpointConfig): TouchpointNotification;
+/**
+ * Check if a touchpoint notification has timed out (human did not respond in time).
+ *
+ * A touchpoint with Infinity timeout never times out (always returns false).
+ * A touchpoint that has been responded to (respondedAt is set) never times out.
+ */
+export declare function hasTouchpointTimedOut(notification: TouchpointNotification): boolean;
+//# sourceMappingURL=human-touchpoints.d.ts.map

package/dist/src/governor/human-touchpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-touchpoints.d.ts","sourceRoot":"","sources":["../../../src/governor/human-touchpoints.ts"],"names":[],"mappings":"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"}