@ginkoai/cli 1.6.1 → 1.7.0

package/dist/lib/__tests__/task-timeout.test.js

@@ -0,0 +1,278 @@
+/**
+ * @fileType: test
+ * @status: current
+ * @updated: 2025-12-07
+ * @tags: [test, timeout, orchestrator, epic-004-sprint5, task-6]
+ * @related: [task-timeout.ts]
+ * @priority: high
+ * @complexity: medium
+ * @dependencies: [vitest, fs-extra]
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'fs-extra';
+import path from 'path';
+import { startTaskTimeout, checkTimeouts, clearTaskTimeout, getActiveTimeouts, getTaskTimeout, getAllTimeouts, cleanupOldTimeouts, handleTimeout, TimeoutMonitor } from '../task-timeout.js';
+// Mock dependencies
+vi.mock('../../utils/helpers.js', () => ({
+    getGinkoDir: vi.fn(async () => '/tmp/ginko-test/.ginko'),
+    getUserEmail: vi.fn(async () => 'test@example.com'),
+    getProjectRoot: vi.fn(async () => '/tmp/ginko-test')
+}));
+vi.mock('../checkpoint.js', () => ({
+    createCheckpoint: vi.fn(async (taskId, agentId, message) => ({
+        id: `cp_${Date.now()}_test`,
+        taskId,
+        agentId,
+        timestamp: new Date(),
+        gitCommit: 'abc123',
+        filesModified: [],
+        eventsSince: 'event_123',
+        metadata: {},
+        message
+    }))
+}));
+vi.mock('../event-logger.js', () => ({
+    logEvent: vi.fn(async (entry) => ({
+        id: `event_${Date.now()}_test`,
+        user_id: 'test@example.com',
+        organization_id: 'org_test',
+        project_id: 'proj_test',
+        timestamp: new Date().toISOString(),
+        ...entry
+    }))
+}));
+describe('task-timeout', () => {
+    const testDir = '/tmp/ginko-test/.ginko/timeouts';
+    beforeEach(async () => {
+        // Clean up test directory
+        await fs.remove(testDir);
+        await fs.ensureDir(testDir);
+    });
+    afterEach(async () => {
+        // Clean up after tests
+        await fs.remove(testDir);
+    });
+    describe('startTaskTimeout', () => {
+        it('should create a timeout with default configuration', async () => {
+            const timeout = await startTaskTimeout('TASK-1', 60000, // 60 seconds
+            'agent-123');
+            expect(timeout.taskId).toBe('TASK-1');
+            expect(timeout.agentId).toBe('agent-123');
+            expect(timeout.maxDuration).toBe(60000);
+            expect(timeout.status).toBe('active');
+            expect(timeout.startedAt).toBeInstanceOf(Date);
+            expect(timeout.timeoutAt).toBeInstanceOf(Date);
+            expect(timeout.warningAt).toBeInstanceOf(Date);
+            // Verify warning threshold (80%)
+            const expectedWarning = timeout.startedAt.getTime() + (60000 * 0.8);
+            expect(timeout.warningAt.getTime()).toBeCloseTo(expectedWarning, -1);
+            // Verify timeout time
+            const expectedTimeout = timeout.startedAt.getTime() + 60000;
+            expect(timeout.timeoutAt.getTime()).toBeCloseTo(expectedTimeout, -1);
+        });
+        it('should create a timeout with custom warning threshold', async () => {
+            const timeout = await startTaskTimeout('TASK-2', 60000, 'agent-456', { warningThreshold: 0.5 } // 50%
+            );
+            // Verify warning at 50%
+            const expectedWarning = timeout.startedAt.getTime() + (60000 * 0.5);
+            expect(timeout.warningAt.getTime()).toBeCloseTo(expectedWarning, -1);
+        });
+        it('should save timeout to file', async () => {
+            const timeout = await startTaskTimeout('TASK-3', 60000, 'agent-789');
+            const filePath = path.join(testDir, 'TASK-3.json');
+            const fileExists = await fs.pathExists(filePath);
+            expect(fileExists).toBe(true);
+            const savedData = await fs.readJSON(filePath);
+            expect(savedData.taskId).toBe('TASK-3');
+            expect(savedData.agentId).toBe('agent-789');
+        });
+    });
+    describe('getTaskTimeout', () => {
+        it('should retrieve timeout by task ID', async () => {
+            await startTaskTimeout('TASK-4', 60000, 'agent-111');
+            const timeout = await getTaskTimeout('TASK-4');
+            expect(timeout).not.toBeNull();
+            expect(timeout.taskId).toBe('TASK-4');
+            expect(timeout.agentId).toBe('agent-111');
+        });
+        it('should return null for non-existent timeout', async () => {
+            const timeout = await getTaskTimeout('TASK-NONEXISTENT');
+            expect(timeout).toBeNull();
+        });
+    });
+    describe('getActiveTimeouts', () => {
+        it('should return all active timeouts', async () => {
+            await startTaskTimeout('TASK-5', 60000, 'agent-222');
+            await startTaskTimeout('TASK-6', 60000, 'agent-333');
+            const activeTimeouts = await getActiveTimeouts();
+            expect(activeTimeouts).toHaveLength(2);
+            expect(activeTimeouts.map(t => t.taskId)).toContain('TASK-5');
+            expect(activeTimeouts.map(t => t.taskId)).toContain('TASK-6');
+        });
+        it('should not return completed timeouts', async () => {
+            await startTaskTimeout('TASK-7', 60000, 'agent-444');
+            await startTaskTimeout('TASK-8', 60000, 'agent-555');
+            // Complete one timeout
+            await clearTaskTimeout('TASK-7');
+            const activeTimeouts = await getActiveTimeouts();
+            expect(activeTimeouts).toHaveLength(1);
+            expect(activeTimeouts[0].taskId).toBe('TASK-8');
+        });
+    });
+    describe('clearTaskTimeout', () => {
+        it('should mark timeout as completed', async () => {
+            await startTaskTimeout('TASK-9', 60000, 'agent-666');
+            await clearTaskTimeout('TASK-9');
+            const timeout = await getTaskTimeout('TASK-9');
+            expect(timeout).not.toBeNull();
+            expect(timeout.status).toBe('completed');
+        });
+        it('should remove from active timeouts', async () => {
+            await startTaskTimeout('TASK-10', 60000, 'agent-777');
+            let activeTimeouts = await getActiveTimeouts();
+            expect(activeTimeouts).toHaveLength(1);
+            await clearTaskTimeout('TASK-10');
+            activeTimeouts = await getActiveTimeouts();
+            expect(activeTimeouts).toHaveLength(0);
+        });
+    });
+    describe('checkTimeouts', () => {
+        it('should detect timed out tasks', async () => {
+            // Create timeout with very short duration (100ms)
+            await startTaskTimeout('TASK-11', 100, 'agent-888');
+            // Wait for timeout to expire
+            await new Promise(resolve => setTimeout(resolve, 150));
+            const timedOutTasks = await checkTimeouts();
+            expect(timedOutTasks).toHaveLength(1);
+            expect(timedOutTasks[0].taskId).toBe('TASK-11');
+            expect(timedOutTasks[0].agentId).toBe('agent-888');
+            expect(timedOutTasks[0].checkpointId).toBeDefined();
+            expect(timedOutTasks[0].escalationEventId).toBeDefined();
+        });
+        it('should update status to warning at threshold', async () => {
+            // Create timeout with 100ms duration, warning at 50ms (50%)
+            await startTaskTimeout('TASK-12', 100, 'agent-999', { warningThreshold: 0.5 });
+            // Wait for warning threshold
+            await new Promise(resolve => setTimeout(resolve, 60));
+            await checkTimeouts();
+            const timeout = await getTaskTimeout('TASK-12');
+            expect(timeout).not.toBeNull();
+            expect(timeout.status).toBe('warning');
+        });
+        it('should not process already timed out tasks', async () => {
+            // Create and timeout a task
+            await startTaskTimeout('TASK-13', 100, 'agent-1010');
+            await new Promise(resolve => setTimeout(resolve, 150));
+            const firstCheck = await checkTimeouts();
+            expect(firstCheck).toHaveLength(1);
+            // Check again
+            const secondCheck = await checkTimeouts();
+            // Should not process again
+            expect(secondCheck).toHaveLength(0);
+        });
+    });
+    describe('handleTimeout', () => {
+        it('should create checkpoint and escalation event', async () => {
+            const { createCheckpoint } = await import('../checkpoint.js');
+            const { logEvent } = await import('../event-logger.js');
+            await startTaskTimeout('TASK-14', 100, 'agent-1111');
+            await new Promise(resolve => setTimeout(resolve, 150));
+            const result = await handleTimeout('TASK-14');
+            expect(result).not.toBeNull();
+            expect(result.taskId).toBe('TASK-14');
+            expect(result.checkpointId).toBeDefined();
+            expect(result.escalationEventId).toBeDefined();
+            // Verify checkpoint was created
+            expect(createCheckpoint).toHaveBeenCalledWith('TASK-14', 'agent-1111', expect.stringContaining('timeout'), expect.objectContaining({ reason: 'timeout' }));
+            // Verify escalation event was logged
+            expect(logEvent).toHaveBeenCalledWith(expect.objectContaining({
+                category: 'blocker',
+                description: expect.stringContaining('TASK-14 timed out'),
+                blocker_severity: 'high'
+            }));
+        });
+        it('should update timeout status to timed_out', async () => {
+            await startTaskTimeout('TASK-15', 100, 'agent-1212');
+            await new Promise(resolve => setTimeout(resolve, 150));
+            await handleTimeout('TASK-15');
+            const timeout = await getTaskTimeout('TASK-15');
+            expect(timeout).not.toBeNull();
+            expect(timeout.status).toBe('timed_out');
+            expect(timeout.checkpointId).toBeDefined();
+            expect(timeout.escalationEventId).toBeDefined();
+        });
+        it('should return null for non-existent timeout', async () => {
+            const result = await handleTimeout('TASK-NONEXISTENT');
+            expect(result).toBeNull();
+        });
+    });
+    describe('getAllTimeouts', () => {
+        it('should return all timeouts regardless of status', async () => {
+            await startTaskTimeout('TASK-16', 60000, 'agent-1313');
+            await startTaskTimeout('TASK-17', 100, 'agent-1414');
+            // Complete one
+            await clearTaskTimeout('TASK-16');
+            // Timeout another
+            await new Promise(resolve => setTimeout(resolve, 150));
+            await checkTimeouts();
+            const allTimeouts = await getAllTimeouts();
+            expect(allTimeouts).toHaveLength(2);
+            const statuses = allTimeouts.map(t => t.status).sort();
+            expect(statuses).toContain('completed');
+            expect(statuses).toContain('timed_out');
+        });
+    });
+    describe('cleanupOldTimeouts', () => {
+        it('should remove old completed timeouts', async () => {
+            await startTaskTimeout('TASK-18', 60000, 'agent-1515');
+            // Manually set old timestamp
+            const filePath = path.join(testDir, 'TASK-18.json');
+            const timeout = await fs.readJSON(filePath);
+            const oldDate = new Date(Date.now() - 8 * 24 * 60 * 60 * 1000); // 8 days ago
+            timeout.startedAt = oldDate.toISOString();
+            timeout.status = 'completed';
+            await fs.writeJSON(filePath, timeout);
+            // Clean up timeouts older than 7 days
+            const cleanedCount = await cleanupOldTimeouts(7 * 24 * 60 * 60 * 1000);
+            expect(cleanedCount).toBe(1);
+            const fileExists = await fs.pathExists(filePath);
+            expect(fileExists).toBe(false);
+        });
+        it('should not remove active timeouts', async () => {
+            await startTaskTimeout('TASK-19', 60000, 'agent-1616');
+            // Manually set old timestamp but keep active
+            const filePath = path.join(testDir, 'TASK-19.json');
+            const timeout = await fs.readJSON(filePath);
+            const oldDate = new Date(Date.now() - 8 * 24 * 60 * 60 * 1000);
+            timeout.startedAt = oldDate.toISOString();
+            // status remains 'active'
+            await fs.writeJSON(filePath, timeout);
+            const cleanedCount = await cleanupOldTimeouts(7 * 24 * 60 * 60 * 1000);
+            expect(cleanedCount).toBe(0);
+            const fileExists = await fs.pathExists(filePath);
+            expect(fileExists).toBe(true);
+        });
+    });
+    describe('TimeoutMonitor', () => {
+        it('should start and stop monitoring', () => {
+            const monitor = new TimeoutMonitor({ checkInterval: 1000 });
+            monitor.start();
+            let status = monitor.getStatus();
+            expect(status.isRunning).toBe(true);
+            expect(status.checkInterval).toBe(1000);
+            monitor.stop();
+            status = monitor.getStatus();
+            expect(status.isRunning).toBe(false);
+        });
+        it('should not start twice', () => {
+            const monitor = new TimeoutMonitor();
+            const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+            monitor.start();
+            monitor.start();
+            expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('already started'));
+            monitor.stop();
+            consoleSpy.mockRestore();
+        });
+    });
+});
+//# sourceMappingURL=task-timeout.test.js.map

package/dist/lib/__tests__/task-timeout.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-timeout.test.js","sourceRoot":"","sources":["../../../src/lib/__tests__/task-timeout.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC1B,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,cAAc,EAGf,MAAM,oBAAoB,CAAC;AAE5B,oBAAoB;AACpB,EAAE,CAAC,IAAI,CAAC,wBAAwB,EAAE,GAAG,EAAE,CAAC,CAAC;IACvC,WAAW,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,wBAAwB,CAAC;IACxD,YAAY,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,kBAAkB,CAAC;IACnD,cAAc,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,iBAAiB,CAAC;CACrD,CAAC,CAAC,CAAC;AAEJ,EAAE,CAAC,IAAI,CAAC,kBAAkB,EAAE,GAAG,EAAE,CAAC,CAAC;IACjC,gBAAgB,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,MAAc,EAAE,OAAe,EAAE,OAAe,EAAE,EAAE,CAAC,CAAC;QACnF,EAAE,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,OAAO;QAC3B,MAAM;QACN,OAAO;QACP,SAAS,EAAE,IAAI,IAAI,EAAE;QACrB,SAAS,EAAE,QAAQ;QACnB,aAAa,EAAE,EAAE;QACjB,WAAW,EAAE,WAAW;QACxB,QAAQ,EAAE,EAAE;QACZ,OAAO;KACR,CAAC,CAAC;CACJ,CAAC,CAAC,CAAC;AAEJ,EAAE,CAAC,IAAI,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAAC,CAAC;IACnC,QAAQ,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,KAAU,EAAE,EAAE,CAAC,CAAC;QACrC,EAAE,EAAE,SAAS,IAAI,CAAC,GAAG,EAAE,OAAO;QAC9B,OAAO,EAAE,kBAAkB;QAC3B,eAAe,EAAE,UAAU;QAC3B,UAAU,EAAE,WAAW;QACvB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,GAAG,KAAK;KACT,CAAC,CAAC;CACJ,CAAC,CAAC,CAAC;AAEJ,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;IAC5B,MAAM,OAAO,GAAG,iCAAiC,CAAC;IAElD,UAAU,CAAC,KAAK,IAAI,EAAE;QACpB,0BAA0B;QAC1B,MAAM,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACzB,MAAM,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,KAAK,IAAI,EAAE;QACnB,uBAAuB;QACvB,MAAM,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;QAChC,EAAE,CAAC,oDAAoD,EAAE,KAAK,IAAI,EAAE;YAClE,MAAM,OAAO,GAAG,MAAM,gBAAgB,CACpC,QAAQ,EACR,KAAK,EAAE,aAAa;YACpB,WAAW,CACZ,CAAC;YAEF,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACtC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAC1C,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACxC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACtC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;YAC/C,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;YAC/C,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;YAE/C,iCAAiC;YACjC,MAAM,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;YACpE,MAAM,CAAC,OAAO,CAAC,SAAU,CAAC,OAAO,EAAE,CAAC,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,CAAC;YAEtE,sBAAsB;YACtB,MAAM,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC;YAC5D,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,CAAC;QACvE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,uDAAuD,EAAE,KAAK,IAAI,EAAE;YACrE,MAAM,OAAO,GAAG,MAAM,gBAAgB,CACpC,QAAQ,EACR,KAAK,EACL,WAAW,EACX,EAAE,gBAAgB,EAAE,GAAG,EAAE,CAAC,MAAM;aACjC,CAAC;YAEF,wBAAwB;YACxB,MAAM,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;YACpE,MAAM,CAAC,OAAO,CAAC,SAAU,CAAC,OAAO,EAAE,CAAC,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,CAAC;QACxE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,6BAA6B,EAAE,KAAK,IAAI,EAAE;YAC3C,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;YAErE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;YACnD,MAAM,UAAU,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YAEjD,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAE9B,MAAM,SAAS,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC9C,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACxC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC9C,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;QAC9B,EAAE,CAAC,oCAAoC,EAAE,KAAK,IAAI,EAAE;YAClD,MAAM,gBAAgB,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC;YAE/C,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC/B,MAAM,CAAC,OAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACvC,MAAM,CAAC,OAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;YAC3D,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,kBAAkB,CAAC,CAAC;YAEzD,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC7B,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;QACjC,EAAE,CAAC,mCAAmC,EAAE,KAAK,IAAI,EAAE;YACjD,MAAM,gBAAgB,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;YACrD,MAAM,gBAAgB,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,cAAc,GAAG,MAAM,iBAAiB,EAAE,CAAC;YAEjD,MAAM,CAAC,cAAc,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;YACvC,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YAC9D,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,sCAAsC,EAAE,KAAK,IAAI,EAAE;YACpD,MAAM,gBAAgB,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;YACrD,MAAM,gBAAgB,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;YAErD,uBAAuB;YACvB,MAAM,gBAAgB,CAAC,QAAQ,CAAC,CAAC;YAEjC,MAAM,cAAc,GAAG,MAAM,iBAAiB,EAAE,CAAC;YAEjD,MAAM,CAAC,cAAc,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;YACvC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAClD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;QAChC,EAAE,CAAC,kCAAkC,EAAE,KAAK,IAAI,EAAE;YAChD,MAAM,gBAAgB,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,gBAAgB,CAAC,QAAQ,CAAC,CAAC;YAEjC,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC;YAE/C,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC/B,MAAM,CAAC,OAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,oCAAoC,EAAE,KAAK,IAAI,EAAE;YAClD,MAAM,gBAAgB,CAAC,SAAS,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;YAEtD,IAAI,cAAc,GAAG,MAAM,iBAAiB,EAAE,CAAC;YAC/C,MAAM,CAAC,cAAc,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;YAEvC,MAAM,gBAAgB,CAAC,SAAS,CAAC,CAAC;YAElC,cAAc,GAAG,MAAM,iBAAiB,EAAE,CAAC;YAC3C,MAAM,CAAC,cAAc,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;QAC7B,EAAE,CAAC,+BAA+B,EAAE,KAAK,IAAI,EAAE;YAC7C,kDAAkD;YAClD,MAAM,gBAAgB,CAAC,SAAS,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;YAEpD,6BAA6B;YAC7B,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;YAEvD,MAAM,aAAa,GAAG,MAAM,aAAa,EAAE,CAAC;YAE5C,MAAM,CAAC,aAAa,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;YACtC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAChD,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YACnD,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,CAAC;YACpD,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,WAAW,EAAE,CAAC;QAC3D,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,8CAA8C,EAAE,KAAK,IAAI,EAAE;YAC5D,4DAA4D;YAC5D,MAAM,gBAAgB,CAAC,SAAS,EAAE,GAAG,EAAE,WAAW,EAAE,EAAE,gBAAgB,EAAE,GAAG,EAAE,CAAC,CAAC;YAE/E,6BAA6B;YAC7B,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;YAEtD,MAAM,aAAa,EAAE,CAAC;YAEtB,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,SAAS,CAAC,CAAC;YAEhD,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC/B,MAAM,CAAC,OAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;YAC1D,4BAA4B;YAC5B,MAAM,gBAAgB,CAAC,SAAS,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC;YACrD,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;YACvD,MAAM,UAAU,GAAG,MAAM,aAAa,EAAE,CAAC;YAEzC,MAAM,CAAC,UAAU,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;YAEnC,cAAc;YACd,MAAM,WAAW,GAAG,MAAM,aAAa,EAAE,CAAC;YAE1C,2BAA2B;YAC3B,MAAM,CAAC,WAAW,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;QAC7B,EAAE,CAAC,+CAA+C,EAAE,KAAK,IAAI,EAAE;YAC7D,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;YAC9D,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;YAExD,MAAM,gBAAgB,CAAC,SAAS,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC;YACrD,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;YAEvD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,SAAS,CAAC,CAAC;YAE9C,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC9B,MAAM,CAAC,MAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACvC,MAAM,CAAC,MAAO,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,CAAC;YAC3C,MAAM,CAAC,MAAO,CAAC,iBAAiB,CAAC,CAAC,WAAW,EAAE,CAAC;YAEhD,gCAAgC;YAChC,MAAM,CAAC,gBAAgB,CAAC,CAAC,oBAAoB,CAC3C,SAAS,EACT,YAAY,EACZ,MAAM,CAAC,gBAAgB,CAAC,SAAS,CAAC,EAClC,MAAM,CAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAC/C,CAAC;YAEF,qCAAqC;YACrC,MAAM,CAAC,QAAQ,CAAC,CAAC,oBAAoB,CACnC,MAAM,CAAC,gBAAgB,CAAC;gBACtB,QAAQ,EAAE,SAAS;gBACnB,WAAW,EAAE,MAAM,CAAC,gBAAgB,CAAC,mBAAmB,CAAC;gBACzD,gBAAgB,EAAE,MAAM;aACzB,CAAC,CACH,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,2CAA2C,EAAE,KAAK,IAAI,EAAE;YACzD,MAAM,gBAAgB,CAAC,SAAS,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC;YACrD,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;YAEvD,MAAM,aAAa,CAAC,SAAS,CAAC,CAAC;YAE/B,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,SAAS,CAAC,CAAC;YAEhD,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC/B,MAAM,CAAC,OAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAC1C,MAAM,CAAC,OAAQ,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,CAAC;YAC5C,MAAM,CAAC,OAAQ,CAAC,iBAAiB,CAAC,CAAC,WAAW,EAAE,CAAC;QACnD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;YAC3D,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,kBAAkB,CAAC,CAAC;YAEvD,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC5B,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;QAC9B,EAAE,CAAC,iDAAiD,EAAE,KAAK,IAAI,EAAE;YAC/D,MAAM,gBAAgB,CAAC,SAAS,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;YACvD,MAAM,gBAAgB,CAAC,SAAS,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC;YAErD,eAAe;YACf,MAAM,gBAAgB,CAAC,SAAS,CAAC,CAAC;YAElC,kBAAkB;YAClB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;YACvD,MAAM,aAAa,EAAE,CAAC;YAEtB,MAAM,WAAW,GAAG,MAAM,cAAc,EAAE,CAAC;YAE3C,MAAM,CAAC,WAAW,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;YAEpC,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;YACvD,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;YACxC,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;QAClC,EAAE,CAAC,sCAAsC,EAAE,KAAK,IAAI,EAAE;YACpD,MAAM,gBAAgB,CAAC,SAAS,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;YAEvD,6BAA6B;YAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;YACpD,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC5C,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,aAAa;YAC7E,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;YAC1C,OAAO,CAAC,MAAM,GAAG,WAAW,CAAC;YAC7B,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAEtC,sCAAsC;YACtC,MAAM,YAAY,GAAG,MAAM,kBAAkB,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;YAEvE,MAAM,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAE7B,MAAM,UAAU,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YACjD,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,mCAAmC,EAAE,KAAK,IAAI,EAAE;YACjD,MAAM,gBAAgB,CAAC,SAAS,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;YAEvD,6CAA6C;YAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;YACpD,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC5C,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;YAC/D,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;YAC1C,0BAA0B;YAC1B,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAEtC,MAAM,YAAY,GAAG,MAAM,kBAAkB,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;YAEvE,MAAM,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAE7B,MAAM,UAAU,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YACjD,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;QAC9B,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;YAC1C,MAAM,OAAO,GAAG,IAAI,cAAc,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YAE5D,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,IAAI,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;YACjC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAExC,OAAO,CAAC,IAAI,EAAE,CAAC;YACf,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;YAC7B,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,wBAAwB,EAAE,GAAG,EAAE;YAChC,MAAM,OAAO,GAAG,IAAI,cAAc,EAAE,CAAC;YACrC,MAAM,UAAU,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAE1E,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,OAAO,CAAC,KAAK,EAAE,CAAC;YAEhB,MAAM,CAAC,UAAU,CAAC,CAAC,oBAAoB,CAAC,MAAM,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC,CAAC;YAEpF,OAAO,CAAC,IAAI,EAAE,CAAC;YACf,UAAU,CAAC,WAAW,EAAE,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/lib/agent-heartbeat.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-12-05
+ * @tags: [agent, heartbeat, epic-004, multi-agent]
+ * @related: [event-queue.ts, ../commands/graph/api-client.ts]
+ * @priority: high
+ * @complexity: low
+ * @dependencies: []
+ */
+/**
+ * Agent Heartbeat Manager
+ *
+ * Sends periodic heartbeat signals to dashboard API to maintain agent online status.
+ *
+ * Pattern:
+ * - Sends heartbeat every 30 seconds when active
+ * - Uses .unref() on timer to allow process to exit if no other work pending
+ * - Stale agents (no heartbeat for 5 min) marked offline by dashboard
+ * - Offline agents excluded from task assignment
+ *
+ * Usage:
+ * ```typescript
+ * const { startHeartbeat, stopHeartbeat } = require('./agent-heartbeat');
+ *
+ * // Start heartbeat when agent becomes active
+ * startHeartbeat('agent_123456_abc');
+ *
+ * // Stop heartbeat when agent deactivates
+ * stopHeartbeat();
+ * ```
+ */
+/**
+ * Heartbeat configuration
+ */
+interface HeartbeatConfig {
+    intervalMs: number;
+    dashboardUrl: string;
+}
+/**
+ * Start sending periodic heartbeats
+ *
+ * @param agentId - Agent ID to send heartbeats for
+ * @param config - Optional configuration overrides
+ */
+export declare function startHeartbeat(agentId: string, config?: Partial<HeartbeatConfig>): void;
+/**
+ * Stop sending heartbeats
+ */
+export declare function stopHeartbeat(): void;
+/**
+ * Graceful shutdown - send final heartbeat and stop
+ */
+export declare function shutdownHeartbeat(): Promise<void>;
+/**
+ * Check if heartbeat is currently running
+ *
+ * @returns True if heartbeat is active
+ */
+export declare function isHeartbeatRunning(): boolean;
+/**
+ * Get current agent ID (if heartbeat is running)
+ *
+ * @returns Current agent ID or null
+ */
+export declare function getCurrentAgentId(): string | null;
+export {};
+//# sourceMappingURL=agent-heartbeat.d.ts.map

package/dist/lib/agent-heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-heartbeat.d.ts","sourceRoot":"","sources":["../../src/lib/agent-heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;GAEG;AACH,UAAU,eAAe;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAqCD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CA0BvF;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAOpC;AAED;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAiBvD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAEjD"}

package/dist/lib/agent-heartbeat.js

@@ -0,0 +1,117 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-12-05
+ * @tags: [agent, heartbeat, epic-004, multi-agent]
+ * @related: [event-queue.ts, ../commands/graph/api-client.ts]
+ * @priority: high
+ * @complexity: low
+ * @dependencies: []
+ */
+const DEFAULT_CONFIG = {
+    intervalMs: 30 * 1000, // 30 seconds
+    dashboardUrl: process.env.GINKO_DASHBOARD_URL || 'https://app.ginkoai.com',
+};
+/**
+ * Global heartbeat state
+ */
+let heartbeatTimer = null;
+let currentAgentId = null;
+let isShuttingDown = false;
+/**
+ * Send heartbeat to dashboard API
+ *
+ * @param agentId - Agent ID to send heartbeat for
+ * @returns Promise that resolves when heartbeat is sent
+ */
+async function sendHeartbeat(agentId) {
+    if (isShuttingDown) {
+        return;
+    }
+    try {
+        // Import graph API client lazily
+        const { sendAgentHeartbeat } = await import('../commands/graph/api-client.js');
+        // Send heartbeat via API client
+        await sendAgentHeartbeat(agentId);
+    }
+    catch (error) {
+        // Log but don't throw - heartbeat failures shouldn't crash the CLI
+        console.warn('[AgentHeartbeat] Failed to send heartbeat:', error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * Start sending periodic heartbeats
+ *
+ * @param agentId - Agent ID to send heartbeats for
+ * @param config - Optional configuration overrides
+ */
+export function startHeartbeat(agentId, config) {
+    if (heartbeatTimer) {
+        console.warn('[AgentHeartbeat] Heartbeat already running, stopping previous instance');
+        stopHeartbeat();
+    }
+    const finalConfig = { ...DEFAULT_CONFIG, ...config };
+    currentAgentId = agentId;
+    console.log(`[AgentHeartbeat] Starting heartbeat for agent ${agentId} (interval: ${finalConfig.intervalMs / 1000}s)`);
+    // Send initial heartbeat immediately
+    sendHeartbeat(agentId).catch(error => {
+        console.warn('[AgentHeartbeat] Initial heartbeat failed:', error instanceof Error ? error.message : String(error));
+    });
+    // Schedule periodic heartbeats
+    // Use unref() to allow process to exit if no other work pending
+    heartbeatTimer = setInterval(() => {
+        sendHeartbeat(agentId).catch(error => {
+            console.warn('[AgentHeartbeat] Scheduled heartbeat failed:', error instanceof Error ? error.message : String(error));
+        });
+    }, finalConfig.intervalMs);
+    // Don't keep process alive just for this timer
+    heartbeatTimer.unref();
+}
+/**
+ * Stop sending heartbeats
+ */
+export function stopHeartbeat() {
+    if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+        console.log('[AgentHeartbeat] Heartbeat stopped');
+    }
+    currentAgentId = null;
+}
+/**
+ * Graceful shutdown - send final heartbeat and stop
+ */
+export async function shutdownHeartbeat() {
+    console.log('[AgentHeartbeat] Initiating graceful shutdown...');
+    isShuttingDown = true;
+    // Send final heartbeat if we have an agent ID
+    if (currentAgentId) {
+        try {
+            await sendHeartbeat(currentAgentId);
+            console.log('[AgentHeartbeat] Final heartbeat sent');
+        }
+        catch (error) {
+            console.warn('[AgentHeartbeat] Final heartbeat failed:', error instanceof Error ? error.message : String(error));
+        }
+    }
+    // Stop timer
+    stopHeartbeat();
+    console.log('[AgentHeartbeat] Shutdown complete');
+}
+/**
+ * Check if heartbeat is currently running
+ *
+ * @returns True if heartbeat is active
+ */
+export function isHeartbeatRunning() {
+    return heartbeatTimer !== null;
+}
+/**
+ * Get current agent ID (if heartbeat is running)
+ *
+ * @returns Current agent ID or null
+ */
+export function getCurrentAgentId() {
+    return currentAgentId;
+}
+//# sourceMappingURL=agent-heartbeat.js.map

package/dist/lib/agent-heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-heartbeat.js","sourceRoot":"","sources":["../../src/lib/agent-heartbeat.ts"],"names":[],"mappings":"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"}

package/dist/lib/checkpoint.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-12-07
+ * @tags: [checkpoint, resilience, rollback, epic-004-sprint5, task-1]
+ * @related: [rollback.ts, event-logger.ts, orchestrator-state.ts]
+ * @priority: high
+ * @complexity: medium
+ * @dependencies: [fs-extra, uuid, simple-git]
+ */
+/**
+ * Checkpoint interface (EPIC-004 Sprint 5 TASK-1)
+ *
+ * Checkpoints are lightweight references to work state, not full snapshots.
+ * They capture git commit, modified files, and event stream position.
+ * Actual rollback uses git operations, not stored copies.
+ */
+export interface Checkpoint {
+    id: string;
+    taskId: string;
+    agentId: string;
+    timestamp: Date;
+    gitCommit: string;
+    filesModified: string[];
+    eventsSince: string;
+    metadata: Record<string, any>;
+    message?: string;
+}
+/**
+ * Create a checkpoint
+ *
+ * Captures current work state:
+ * - Git commit hash
+ * - Modified files since task start
+ * - Last event ID from event stream
+ * - Optional message and metadata
+ *
+ * @param taskId - Task ID this checkpoint belongs to
+ * @param agentId - Agent creating checkpoint (optional, auto-detected)
+ * @param message - Optional description
+ * @param metadata - Optional additional data
+ */
+export declare function createCheckpoint(taskId: string, agentId?: string, message?: string, metadata?: Record<string, any>): Promise<Checkpoint>;
+/**
+ * Get a specific checkpoint by ID
+ *
+ * @param checkpointId - Checkpoint ID
+ * @returns Checkpoint object or null if not found
+ */
+export declare function getCheckpoint(checkpointId: string): Promise<Checkpoint | null>;
+/**
+ * List checkpoints, optionally filtered by task ID
+ *
+ * @param taskId - Optional task ID to filter by
+ * @returns Array of checkpoints, sorted by timestamp (newest first)
+ */
+export declare function listCheckpoints(taskId?: string): Promise<Checkpoint[]>;
+/**
+ * Delete a checkpoint
+ *
+ * @param checkpointId - Checkpoint ID to delete
+ */
+export declare function deleteCheckpoint(checkpointId: string): Promise<void>;
+/**
+ * Get checkpoints for a specific task, grouped by day
+ * Useful for displaying checkpoint history
+ */
+export declare function getCheckpointsByTask(taskId: string): Promise<Map<string, Checkpoint[]>>;
+/**
+ * Get the most recent checkpoint for a task
+ */
+export declare function getLatestCheckpoint(taskId: string): Promise<Checkpoint | null>;
+/**
+ * Check if a checkpoint exists
+ */
+export declare function checkpointExists(checkpointId: string): Promise<boolean>;
+/**
+ * Export checkpoint data for backup or transfer
+ */
+export declare function exportCheckpoint(checkpointId: string): Promise<string>;
+/**
+ * Import checkpoint data from backup
+ */
+export declare function importCheckpoint(checkpointData: string): Promise<Checkpoint>;
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/lib/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../src/lib/checkpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA+ID;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,OAAO,CAAC,UAAU,CAAC,CAqCrB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAkBpF;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAoC5E;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAc1E;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,CAe7F;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAGpF;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG7E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ5E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAmBlF"}