@inixiative/hivemind 0.1.0

package/dist/coordinator/coordinator.test.js

@@ -0,0 +1,171 @@
+import { describe, it, expect, beforeEach, afterEach, afterAll } from 'bun:test';
+import { createTestDb, cleanupAllTestDbs } from '../test/setup';
+import { buildAgent } from '../test/factories';
+import { getAgent } from '../agents/getAgent';
+import { getActiveAgents } from '../agents/getActiveAgents';
+import * as fs from 'fs';
+import * as path from 'path';
+import { mkdirSync, rmSync, existsSync } from 'fs';
+// Test directory for coordinator files
+const TEST_COORD_DIR = path.join(__dirname, '../../.test-coordinator');
+function createTestCoordinatorDir() {
+    const dataDir = path.join(TEST_COORD_DIR, `coord-${Date.now()}`);
+    mkdirSync(dataDir, { recursive: true });
+    return {
+        dataDir,
+        cleanup: () => {
+            if (existsSync(dataDir)) {
+                rmSync(dataDir, { recursive: true, force: true });
+            }
+        },
+    };
+}
+function cleanupAllCoordinatorDirs() {
+    if (existsSync(TEST_COORD_DIR)) {
+        rmSync(TEST_COORD_DIR, { recursive: true, force: true });
+    }
+}
+describe('Coordinator', () => {
+    let testDb;
+    let testCoord;
+    beforeEach(() => {
+        testDb = createTestDb();
+        testCoord = createTestCoordinatorDir();
+    });
+    afterEach(() => {
+        testDb.cleanup();
+        testCoord.cleanup();
+    });
+    afterAll(() => {
+        cleanupAllTestDbs();
+        cleanupAllCoordinatorDirs();
+    });
+    describe('Lock acquisition', () => {
+        it('creates pid file when acquiring lock', async () => {
+            const pidPath = path.join(testCoord.dataDir, 'coordinator.pid');
+            // Simulate acquiring lock
+            fs.writeFileSync(pidPath, process.pid.toString());
+            expect(existsSync(pidPath)).toBe(true);
+            const content = fs.readFileSync(pidPath, 'utf-8');
+            expect(parseInt(content, 10)).toBe(process.pid);
+        });
+        it('detects stale pid file for dead process', () => {
+            const pidPath = path.join(testCoord.dataDir, 'coordinator.pid');
+            // Write a PID that doesn't exist (use a very high number)
+            fs.writeFileSync(pidPath, '999999999');
+            // Check if process exists
+            let processExists = true;
+            try {
+                process.kill(999999999, 0);
+            }
+            catch {
+                processExists = false;
+            }
+            expect(processExists).toBe(false);
+        });
+    });
+    describe('PID-based agent detection', () => {
+        it('can detect if a PID is alive', () => {
+            // Current process is alive
+            let alive = true;
+            try {
+                process.kill(process.pid, 0);
+            }
+            catch {
+                alive = false;
+            }
+            expect(alive).toBe(true);
+            // Non-existent PID is dead
+            let deadAlive = true;
+            try {
+                process.kill(999999999, 0);
+            }
+            catch {
+                deadAlive = false;
+            }
+            expect(deadAlive).toBe(false);
+        });
+        it('agents store PID for lifecycle tracking', () => {
+            const { agent } = buildAgent(testDb.db, { pid: process.pid });
+            expect(agent.pid).toBe(process.pid);
+        });
+    });
+    describe('Agent cleanup', () => {
+        it('marks stale agent as dead and releases tasks', () => {
+            const { agent } = buildAgent(testDb.db);
+            // Create a claimed task
+            testDb.db
+                .prepare(`
+        INSERT INTO plans (id, hex, title, status, created_at)
+        VALUES ('pln_test', 'abcdef', 'Test Plan', 'active', datetime('now'))
+      `)
+                .run();
+            testDb.db
+                .prepare(`
+        INSERT INTO tasks (id, plan_hex, seq, plan_id, title, status, claimed_by)
+        VALUES ('tsk_test', 'abcdef', '001', 'pln_test', 'Test task', 'claimed', ?)
+      `)
+                .run(agent.id);
+            // Mark agent dead (simulating coordinator action)
+            testDb.db.prepare(`UPDATE agents SET status = 'dead' WHERE id = ?`).run(agent.id);
+            testDb.db
+                .prepare(`UPDATE tasks SET status = 'pending', claimed_by = NULL WHERE claimed_by = ?`)
+                .run(agent.id);
+            // Verify
+            const updatedAgent = getAgent(testDb.db, agent.id);
+            expect(updatedAgent.status).toBe('dead');
+            const task = testDb.db.prepare(`SELECT * FROM tasks WHERE id = 'tsk_test'`).get();
+            expect(task.status).toBe('pending');
+            expect(task.claimed_by).toBeNull();
+        });
+    });
+    describe('Singleton behavior', () => {
+        it('prevents multiple coordinators via pid file', () => {
+            const pidPath = path.join(testCoord.dataDir, 'coordinator.pid');
+            // First "coordinator" writes its PID
+            fs.writeFileSync(pidPath, process.pid.toString());
+            // Second coordinator should detect existing process
+            const existingPid = parseInt(fs.readFileSync(pidPath, 'utf-8'), 10);
+            let canAcquire = false;
+            try {
+                process.kill(existingPid, 0); // Check if alive
+                canAcquire = false; // Process alive, can't acquire
+            }
+            catch {
+                canAcquire = true; // Process dead, can acquire
+            }
+            expect(canAcquire).toBe(false);
+        });
+        it('allows new coordinator when previous is dead', () => {
+            const pidPath = path.join(testCoord.dataDir, 'coordinator.pid');
+            // Write a dead PID
+            fs.writeFileSync(pidPath, '999999999');
+            // Check if can acquire
+            const existingPid = parseInt(fs.readFileSync(pidPath, 'utf-8'), 10);
+            let canAcquire = false;
+            try {
+                process.kill(existingPid, 0);
+                canAcquire = false;
+            }
+            catch {
+                canAcquire = true;
+            }
+            expect(canAcquire).toBe(true);
+        });
+    });
+    describe('Coordinator lifecycle', () => {
+        it('coordinator runs indefinitely (no exit on empty)', () => {
+            // No agents registered
+            const active = getActiveAgents(testDb.db);
+            expect(active.length).toBe(0);
+            // Coordinator should NOT exit - it runs forever per project
+            const shouldExit = false; // Changed from heartbeat-based logic
+            expect(shouldExit).toBe(false);
+        });
+        it('coordinator monitors all active agents', () => {
+            buildAgent(testDb.db);
+            const active = getActiveAgents(testDb.db);
+            expect(active.length).toBe(1);
+        });
+    });
+});

package/dist/coordinator/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Hivemind Coordinator - singleton background process (one per project)
+ *
+ * Responsibilities:
+ * - Periodically check if agent PIDs are still alive
+ * - Mark dead agents
+ * - Clean up resources
+ *
+ * Runs indefinitely until killed. Started by first agent join.
+ */
+type CoordinatorConfig = {
+    project: string;
+    dataDir: string;
+};
+export declare function runCoordinator(config: CoordinatorConfig): void;
+export {};

package/dist/coordinator/index.js

@@ -0,0 +1,166 @@
+/**
+ * Hivemind Coordinator - singleton background process (one per project)
+ *
+ * Responsibilities:
+ * - Periodically check if agent PIDs are still alive
+ * - Mark dead agents
+ * - Clean up resources
+ *
+ * Runs indefinitely until killed. Started by first agent join.
+ */
+import { getConnection } from '../db/getConnection';
+import { getActiveAgents } from '../agents/getActiveAgents';
+import { markAgentDead } from '../agents/markAgentDead';
+import { startPlanWatcher } from '../watcher/planWatcher';
+import { emit } from '../events/emit';
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseDatetime } from '../datetime/parseDatetime';
+const SWEEP_INTERVAL_MS = 30_000; // 30 seconds
+const MIN_AGE_MS = 60_000; // Only kill agents older than 1 minute (grace period)
+/**
+ * Check if a process is alive
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0); // Signal 0 = check existence
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if an agent is old enough to be considered for cleanup
+ */
+function isOldEnough(createdAt) {
+    const created = parseDatetime(createdAt);
+    if (!created)
+        return false;
+    return Date.now() - created.getTime() > MIN_AGE_MS;
+}
+function getLockPath(config) {
+    return path.join(config.dataDir, 'coordinator.lock');
+}
+function getPidPath(config) {
+    return path.join(config.dataDir, 'coordinator.pid');
+}
+function acquireLock(config) {
+    const lockPath = getLockPath(config);
+    const pidPath = getPidPath(config);
+    try {
+        // Check if another coordinator is running
+        if (fs.existsSync(pidPath)) {
+            const existingPid = parseInt(fs.readFileSync(pidPath, 'utf-8').trim(), 10);
+            // Check if process is still alive
+            try {
+                process.kill(existingPid, 0); // Signal 0 = check if process exists
+                // Process exists, can't acquire lock
+                return false;
+            }
+            catch {
+                // Process doesn't exist, stale PID file
+                fs.unlinkSync(pidPath);
+            }
+        }
+        // Write our PID
+        fs.writeFileSync(pidPath, process.pid.toString());
+        // Create lock file
+        fs.writeFileSync(lockPath, new Date().toISOString());
+        return true;
+    }
+    catch (error) {
+        console.error('Failed to acquire lock:', error);
+        return false;
+    }
+}
+function releaseLock(config) {
+    try {
+        const lockPath = getLockPath(config);
+        const pidPath = getPidPath(config);
+        if (fs.existsSync(lockPath))
+            fs.unlinkSync(lockPath);
+        if (fs.existsSync(pidPath))
+            fs.unlinkSync(pidPath);
+    }
+    catch {
+        // Ignore cleanup errors
+    }
+}
+function sweep(config) {
+    const db = getConnection(config.project);
+    // Get all active agents and check if their PIDs are alive
+    const activeAgents = getActiveAgents(db);
+    let marked = 0;
+    for (const agent of activeAgents) {
+        // Skip agents that are too new (grace period)
+        if (!isOldEnough(agent.created_at)) {
+            continue;
+        }
+        // If agent has a PID, check if it's still alive
+        if (agent.pid && !isProcessAlive(agent.pid)) {
+            markAgentDead(db, agent.id);
+            // Emit agent:dead system event
+            emit(db, {
+                type: 'agent:dead',
+                agent_id: agent.id,
+                worktree_id: agent.worktree_id ?? undefined,
+                content: `Agent ${agent.id} died (PID ${agent.pid} no longer running)`,
+                metadata: {
+                    pid: agent.pid,
+                    label: agent.label,
+                    current_task_id: agent.current_task_id,
+                    current_plan_id: agent.current_plan_id,
+                },
+            });
+            marked++;
+        }
+        // Agents without PIDs are left alone (legacy or manual registration)
+    }
+    return marked;
+}
+export function runCoordinator(config) {
+    // Try to acquire lock
+    if (!acquireLock(config)) {
+        // Another coordinator is running
+        process.exit(0);
+    }
+    console.log(`[coordinator] Started for ${config.project} (pid: ${process.pid})`);
+    // Start the plans watcher (syncs Claude's plan mode files to hivemind)
+    const watcher = startPlanWatcher({ project: config.project });
+    // Handle shutdown gracefully
+    const shutdown = () => {
+        console.log('[coordinator] Shutting down...');
+        watcher.stop();
+        releaseLock(config);
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    // Main loop
+    const tick = () => {
+        try {
+            const marked = sweep(config);
+            if (marked > 0) {
+                console.log(`[coordinator] Marked ${marked} dead agent(s) (PID gone)`);
+            }
+        }
+        catch (error) {
+            console.error('[coordinator] Sweep error:', error);
+        }
+        // Schedule next tick
+        setTimeout(tick, SWEEP_INTERVAL_MS);
+    };
+    // Start the loop
+    tick();
+}
+// CLI entry point
+if (import.meta.main) {
+    const project = process.argv[2];
+    const dataDir = process.argv[3];
+    if (!project || !dataDir) {
+        console.error('Usage: coordinator <project> <dataDir>');
+        process.exit(1);
+    }
+    runCoordinator({ project, dataDir });
+}

package/dist/coordinator/spawn.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Spawn coordinator as a singleton - only starts if not already running
+ */
+type SpawnConfig = {
+    project: string;
+    dataDir: string;
+};
+/**
+ * Upsert coordinator singleton - spawns if not running, no-op if already running
+ */
+export declare function ensureCoordinator(config: SpawnConfig): {
+    spawned: boolean;
+    pid?: number;
+};
+/**
+ * Get coordinator status
+ */
+export declare function getCoordinatorStatus(config: SpawnConfig): {
+    running: boolean;
+    pid?: number;
+};
+export {};

package/dist/coordinator/spawn.js

@@ -0,0 +1,66 @@
+/**
+ * Spawn coordinator as a singleton - only starts if not already running
+ */
+import { spawn } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+function isCoordinatorRunning(config) {
+    const pidPath = path.join(config.dataDir, 'coordinator.pid');
+    if (!fs.existsSync(pidPath)) {
+        return false;
+    }
+    try {
+        const pid = parseInt(fs.readFileSync(pidPath, 'utf-8').trim(), 10);
+        process.kill(pid, 0); // Signal 0 = check existence
+        return true;
+    }
+    catch {
+        // Process doesn't exist or can't be signaled
+        // Clean up stale PID file
+        try {
+            fs.unlinkSync(pidPath);
+        }
+        catch {
+            // Ignore
+        }
+        return false;
+    }
+}
+/**
+ * Upsert coordinator singleton - spawns if not running, no-op if already running
+ */
+export function ensureCoordinator(config) {
+    // Check if already running
+    if (isCoordinatorRunning(config)) {
+        const pidPath = path.join(config.dataDir, 'coordinator.pid');
+        const pid = parseInt(fs.readFileSync(pidPath, 'utf-8').trim(), 10);
+        return { spawned: false, pid };
+    }
+    // Spawn coordinator as detached background process
+    const coordinatorPath = path.join(__dirname, 'index.ts');
+    const child = spawn('bun', ['run', coordinatorPath, config.project, config.dataDir], {
+        detached: true,
+        stdio: 'ignore',
+        env: { ...process.env },
+    });
+    // Detach from parent
+    child.unref();
+    return { spawned: true, pid: child.pid };
+}
+/**
+ * Get coordinator status
+ */
+export function getCoordinatorStatus(config) {
+    const pidPath = path.join(config.dataDir, 'coordinator.pid');
+    if (!fs.existsSync(pidPath)) {
+        return { running: false };
+    }
+    try {
+        const pid = parseInt(fs.readFileSync(pidPath, 'utf-8').trim(), 10);
+        process.kill(pid, 0);
+        return { running: true, pid };
+    }
+    catch {
+        return { running: false };
+    }
+}

package/dist/datetime/datetime.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/datetime/datetime.test.js

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'bun:test';
+import { formatDate } from './formatDate';
+import { formatTime } from './formatTime';
+import { formatDatetime } from './formatDatetime';
+import { now } from './now';
+import { parseDatetime } from './parseDatetime';
+import { isStale } from './isStale';
+describe('formatDate', () => {
+    it('formats date as yyyy/mm/dd', () => {
+        const date = new Date('2024-03-15T10:30:00Z');
+        const formatted = formatDate(date);
+        expect(formatted).toMatch(/^\d{4}\/\d{2}\/\d{2}$/);
+    });
+});
+describe('formatTime', () => {
+    it('formats time as hh:mm:ss', () => {
+        const date = new Date('2024-03-15T10:30:45Z');
+        const formatted = formatTime(date);
+        expect(formatted).toMatch(/^\d{2}:\d{2}:\d{2}$/);
+    });
+});
+describe('formatDatetime', () => {
+    it('formats datetime with timezone', () => {
+        const date = new Date('2024-03-15T10:30:45Z');
+        const formatted = formatDatetime(date);
+        expect(formatted).toMatch(/^\d{4}\/\d{2}\/\d{2} \d{2}:\d{2}:\d{2} [A-Z]{2,4}$/);
+    });
+});
+describe('now', () => {
+    it('returns current datetime string', () => {
+        const current = now();
+        expect(current).toMatch(/^\d{4}\/\d{2}\/\d{2} \d{2}:\d{2}:\d{2} [A-Z]{2,4}$/);
+    });
+});
+describe('parseDatetime', () => {
+    it('parses formatted datetime string', () => {
+        const original = new Date();
+        const formatted = formatDatetime(original);
+        const parsed = parseDatetime(formatted);
+        expect(parsed).toBeInstanceOf(Date);
+        // Allow 1 second tolerance due to milliseconds being lost
+        expect(Math.abs(parsed.getTime() - original.getTime())).toBeLessThan(1000);
+    });
+    it('returns null for invalid string', () => {
+        expect(parseDatetime('invalid')).toBeNull();
+        expect(parseDatetime('')).toBeNull();
+    });
+});
+describe('isStale', () => {
+    it('returns true for old timestamps', () => {
+        const oldDate = new Date(Date.now() - 120000); // 2 minutes ago
+        const formatted = formatDatetime(oldDate);
+        expect(isStale(formatted, 60000)).toBe(true); // 1 minute threshold
+    });
+    it('returns false for recent timestamps', () => {
+        const recent = now();
+        expect(isStale(recent, 60000)).toBe(false);
+    });
+    it('returns true for null/undefined', () => {
+        expect(isStale(null, 60000)).toBe(true);
+        expect(isStale(undefined, 60000)).toBe(true);
+    });
+});

package/dist/datetime/formatDate.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Format a Date as yyyy/mm/dd
+ *
+ * Example: 2025/01/15
+ */
+export declare function formatDate(date?: Date): string;

package/dist/datetime/formatDate.js

@@ -0,0 +1,11 @@
+/**
+ * Format a Date as yyyy/mm/dd
+ *
+ * Example: 2025/01/15
+ */
+export function formatDate(date = new Date()) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}/${month}/${day}`;
+}

package/dist/datetime/formatDatetime.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Format a Date as yyyy/mm/dd hh:mm:ss TZ
+ *
+ * Example: 2025/01/15 09:14:32 PST
+ */
+export declare function formatDatetime(date?: Date): string;

package/dist/datetime/formatDatetime.js

@@ -0,0 +1,12 @@
+import { formatDate } from './formatDate';
+import { formatTime } from './formatTime';
+/**
+ * Format a Date as yyyy/mm/dd hh:mm:ss TZ
+ *
+ * Example: 2025/01/15 09:14:32 PST
+ */
+export function formatDatetime(date = new Date()) {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    const tzAbbrev = date.toLocaleTimeString('en-US', { timeZoneName: 'short' }).split(' ').pop();
+    return `${formatDate(date)} ${formatTime(date)} ${tzAbbrev}`;
+}

package/dist/datetime/formatTime.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Format a Date as hh:mm:ss
+ *
+ * Example: 09:14:32
+ */
+export declare function formatTime(date?: Date): string;

package/dist/datetime/formatTime.js

@@ -0,0 +1,11 @@
+/**
+ * Format a Date as hh:mm:ss
+ *
+ * Example: 09:14:32
+ */
+export function formatTime(date = new Date()) {
+    const hours = String(date.getHours()).padStart(2, '0');
+    const minutes = String(date.getMinutes()).padStart(2, '0');
+    const seconds = String(date.getSeconds()).padStart(2, '0');
+    return `${hours}:${minutes}:${seconds}`;
+}

package/dist/datetime/index.d.ts

@@ -0,0 +1,4 @@
+export { formatDatetime } from './formatDatetime';
+export { parseDatetime } from './parseDatetime';
+export { now } from './now';
+export { isStale } from './isStale';

package/dist/datetime/index.js

@@ -0,0 +1,7 @@
+// Formatting
+export { formatDatetime } from './formatDatetime';
+// Parsing
+export { parseDatetime } from './parseDatetime';
+// Helpers
+export { now } from './now';
+export { isStale } from './isStale';

package/dist/datetime/isStale.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Check if a timestamp is older than threshold
+ *
+ * Used for agent liveness checks
+ *
+ * @param timestamp - Datetime string (2025/01/15 09:14:32 PST) or null
+ * @param thresholdMs - Stale threshold in milliseconds (default 30 seconds)
+ * @returns true if stale, including when timestamp is null/undefined
+ */
+export declare function isStale(timestamp: string | null | undefined, thresholdMs?: number): boolean;

package/dist/datetime/isStale.js

@@ -0,0 +1,18 @@
+import { parseDatetime } from './parseDatetime';
+/**
+ * Check if a timestamp is older than threshold
+ *
+ * Used for agent liveness checks
+ *
+ * @param timestamp - Datetime string (2025/01/15 09:14:32 PST) or null
+ * @param thresholdMs - Stale threshold in milliseconds (default 30 seconds)
+ * @returns true if stale, including when timestamp is null/undefined
+ */
+export function isStale(timestamp, thresholdMs = 30000) {
+    const then = parseDatetime(timestamp);
+    if (!then) {
+        return true;
+    }
+    const now = new Date();
+    return now.getTime() - then.getTime() > thresholdMs;
+}

package/dist/datetime/now.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Get current timestamp
+ *
+ * Example: 2025/01/15 09:14:32 PST
+ */
+export declare function now(): string;

package/dist/datetime/now.js

@@ -0,0 +1,9 @@
+import { formatDatetime } from './formatDatetime';
+/**
+ * Get current timestamp
+ *
+ * Example: 2025/01/15 09:14:32 PST
+ */
+export function now() {
+    return formatDatetime(new Date());
+}

package/dist/datetime/parseDatetime.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Parse a datetime string to Date
+ *
+ * Input: 2025/01/15 09:14:32 PST
+ * Returns: Date object or null if invalid
+ */
+export declare function parseDatetime(datetimeStr: string | null | undefined): Date | null;

package/dist/datetime/parseDatetime.js

@@ -0,0 +1,28 @@
+/**
+ * Parse a datetime string to Date
+ *
+ * Input: 2025/01/15 09:14:32 PST
+ * Returns: Date object or null if invalid
+ */
+export function parseDatetime(datetimeStr) {
+    if (!datetimeStr) {
+        return null;
+    }
+    try {
+        // Remove timezone abbreviation for parsing
+        const withoutTz = datetimeStr.replace(/\s+[A-Z]{3,4}$/, '');
+        const [datePart, timePart] = withoutTz.split(' ');
+        if (!datePart || !timePart) {
+            return null;
+        }
+        const [year, month, day] = datePart.split('/').map(Number);
+        const [hours, minutes, seconds] = timePart.split(':').map(Number);
+        if (isNaN(year) || isNaN(month) || isNaN(day)) {
+            return null;
+        }
+        return new Date(year, month - 1, day, hours, minutes, seconds);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/db/constants.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Base hivemind directory: ~/.hivemind
+ */
+export declare const HIVEMIND_BASE: string;