@inixiative/hivemind 0.1.7 → 0.1.8

package/README.md

@@ -49,11 +49,11 @@ This info goes into Claude's system context (not printed to terminal). Claude kn
 
 ## How It Works
 
-Agents are tracked by **process ID (PID)**, not heartbeats:
-- SessionStart hook registers agent with Claude's PID
-- Coordinator monitors PIDs every 30 seconds
-- When Claude exits, coordinator detects dead PID and marks agent dead
-- No polling or heartbeats required
+Hivemind supports two lifecycle modes:
+- Local mode (stdio): agents are tracked by **PID** and the coordinator marks agents dead when their process exits.
+- Network mode (HTTP): agents are tracked by **lease heartbeat** (`last_seen_at`) and the coordinator marks agents dead when lease TTL expires.
+
+Session start registers the agent, then status/events/query/task/emit calls refresh liveness in network mode.
 
 See [ARCHITECTURE.md](ARCHITECTURE.md) for details.
 
@@ -70,11 +70,72 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for details.
 | `hivemind_worktree_cleanup` | Clean up stale worktrees | ✓ |
 | `hivemind_setup` | Initialize project | ✓ |
 | `hivemind_register` | Register this agent | ✓ |
-| `hivemind_emit` | Emit event to log | ✗ |
+| `hivemind_emit` | Emit event to log | ✓ |
 | `hivemind_reset` | Reset database | ✗ |
 
 Tools marked ✓ are auto-approved after `./setup.sh`. Tools marked ✗ require confirmation.
 
+## Server Modes
+
+### Local mode (default, stdio)
+
+Use this for single-machine/local Claude sessions:
+
+```bash
+bun run mcp
+```
+
+This preserves the existing MCP stdio behavior and local PID-based lifecycle.
+
+### Network mode (shared MCP over HTTP)
+
+Use this when multiple containers/processes need to share one hivemind:
+
+```bash
+HIVEMIND_API_TOKEN=replace-me \
+PORT=8787 \
+bun run mcp:http
+```
+
+The HTTP endpoint is:
+
+```text
+http://0.0.0.0:$PORT/mcp
+```
+
+Network mode requires:
+- `Authorization: Bearer <HIVEMIND_API_TOKEN>` on MCP HTTP requests
+- Lease/heartbeat lifecycle (`last_seen_at`) with TTL sweeping (no PID liveness reliance)
+
+## Environment Variables
+
+- `HIVEMIND_API_TOKEN`: required for `bun run mcp:http`
+- `PORT`: HTTP port for network mode (default `8787`)
+- `HIVEMIND_REMOTE_URL`: when set in hook/agent environments, session-start register/status calls go to remote MCP instead of local DB logic
+- `HIVEMIND_AGENT_LEASE_TTL_SECONDS`: lease TTL for stale-agent sweep in network mode (default `180`)
+- `HIVEMIND_NETWORK_MODE`: liveness mode toggle (`1/true` enables lease-based mode). `mcp:http` enables this automatically.
+- `HIVEMIND_BASE`: base directory for project DB/state (defaults to `~/.hivemind`)
+
+## Container-to-Container Example
+
+Shared hivemind service container:
+
+```bash
+docker run --rm -p 8787:8787 \
+  -e HIVEMIND_API_TOKEN=supersecret \
+  ghcr.io/inixiative/hivemind:latest \
+  bun run mcp:http
+```
+
+Implementer/subject/oracle containers (each agent):
+
+```bash
+export HIVEMIND_REMOTE_URL=http://hivemind:8787/mcp
+export HIVEMIND_API_TOKEN=supersecret
+```
+
+With `HIVEMIND_REMOTE_URL` set, `src/hooks/sessionStart.ts` registers and fetches status through the remote service, enabling shared coordination across isolated containers.
+
 ## CLI
 
 ```bash

package/dist/agents/agents.test.js

@@ -4,10 +4,13 @@ import { buildAgent, buildTask } from '../test/factories';
 import { registerAgent } from './registerAgent';
 import { getAgent } from './getAgent';
 import { getActiveAgents } from './getActiveAgents';
+import { getAgentByPid } from './getAgentByPid';
+import { getAgentBySessionId } from './getAgentBySessionId';
 import { markAgentDead } from './markAgentDead';
 import { markAgentIdle } from './markAgentIdle';
 import { updateAgentContext } from './updateAgentContext';
 import { updateAgentTask } from './updateAgentTask';
+import { updateAgentSession } from './updateAgentSession';
 import { unregisterAgent } from './unregisterAgent';
 describe('Agents Module', () => {
     let testDb;
@@ -164,4 +167,80 @@ describe('Agents Module', () => {
             expect(retrieved).toBeNull();
         });
     });
+    describe('getAgentByPid', () => {
+        it('finds active agent by PID', () => {
+            const { agent } = buildAgent(testDb.db, { pid: 12345 });
+            const found = getAgentByPid(testDb.db, 12345);
+            expect(found).toBeDefined();
+            expect(found.id).toBe(agent.id);
+            expect(found.pid).toBe(12345);
+        });
+        it('returns null when PID not found', () => {
+            buildAgent(testDb.db, { pid: 12345 });
+            const found = getAgentByPid(testDb.db, 99999);
+            expect(found).toBeNull();
+        });
+        it('only returns active agents', () => {
+            const { agent } = buildAgent(testDb.db, { pid: 12345 });
+            markAgentDead(testDb.db, agent.id);
+            const found = getAgentByPid(testDb.db, 12345);
+            expect(found).toBeNull();
+        });
+        it('returns most recent agent when multiple have same PID', () => {
+            buildAgent(testDb.db, { pid: 12345, label: 'old' });
+            const { agent: newer } = buildAgent(testDb.db, { pid: 12345, label: 'new' });
+            const found = getAgentByPid(testDb.db, 12345);
+            expect(found.id).toBe(newer.id);
+        });
+    });
+    describe('getAgentBySessionId', () => {
+        it('finds agent by session ID', () => {
+            const { agent } = buildAgent(testDb.db, { session_id: 'session-abc-123' });
+            const found = getAgentBySessionId(testDb.db, 'session-abc-123');
+            expect(found).toBeDefined();
+            expect(found.id).toBe(agent.id);
+        });
+        it('returns null when session not found', () => {
+            buildAgent(testDb.db, { session_id: 'session-abc-123' });
+            const found = getAgentBySessionId(testDb.db, 'different-session');
+            expect(found).toBeNull();
+        });
+    });
+    describe('updateAgentSession', () => {
+        it('updates session ID for existing agent', () => {
+            const { agent } = buildAgent(testDb.db, { session_id: 'old-session' });
+            updateAgentSession(testDb.db, agent.id, 'new-session');
+            const retrieved = getAgent(testDb.db, agent.id);
+            expect(retrieved.session_id).toBe('new-session');
+        });
+        it('allows lookup by new session ID after update', () => {
+            const { agent } = buildAgent(testDb.db, { session_id: 'old-session' });
+            updateAgentSession(testDb.db, agent.id, 'new-session');
+            // Old session no longer works
+            expect(getAgentBySessionId(testDb.db, 'old-session')).toBeNull();
+            // New session works
+            const found = getAgentBySessionId(testDb.db, 'new-session');
+            expect(found).toBeDefined();
+            expect(found.id).toBe(agent.id);
+        });
+    });
+    describe('compaction resilience', () => {
+        it('supports reconnecting agent with new session ID via PID', () => {
+            // Agent registers with original session
+            const { agent } = buildAgent(testDb.db, {
+                pid: 54321,
+                session_id: 'original-session',
+            });
+            // Simulate compaction: lookup by PID, update session
+            const existingAgent = getAgentByPid(testDb.db, 54321);
+            expect(existingAgent).toBeDefined();
+            expect(existingAgent.id).toBe(agent.id);
+            // Update to new session ID
+            updateAgentSession(testDb.db, agent.id, 'compacted-session');
+            // Now agent can be found by new session
+            const found = getAgentBySessionId(testDb.db, 'compacted-session');
+            expect(found).toBeDefined();
+            expect(found.id).toBe(agent.id);
+        });
+    });
 });

package/dist/agents/getAgentByPid.d.ts

@@ -0,0 +1,7 @@
+import type { Database } from 'bun:sqlite';
+import type { Agent } from './types';
+/**
+ * Find an active agent by PID
+ * Used to reconnect agents after session changes (e.g., compaction)
+ */
+export declare function getAgentByPid(db: Database, pid: number): Agent | null;

package/dist/agents/getAgentByPid.js

@@ -0,0 +1,13 @@
+/**
+ * Find an active agent by PID
+ * Used to reconnect agents after session changes (e.g., compaction)
+ */
+export function getAgentByPid(db, pid) {
+    const stmt = db.prepare(`
+    SELECT * FROM agents
+    WHERE pid = ? AND status = 'active'
+    ORDER BY rowid DESC
+    LIMIT 1
+  `);
+    return stmt.get(pid);
+}

package/dist/agents/index.d.ts

@@ -3,8 +3,12 @@ export { registerAgent } from './registerAgent';
 export { unregisterAgent } from './unregisterAgent';
 export { getAgent } from './getAgent';
 export { getActiveAgents } from './getActiveAgents';
+export { getAgentByPid } from './getAgentByPid';
+export { getAgentBySessionId } from './getAgentBySessionId';
 export { updateAgentContext } from './updateAgentContext';
 export { updateAgentTask } from './updateAgentTask';
 export { updateAgentWorktree } from './updateAgentWorktree';
+export { updateAgentSession } from './updateAgentSession';
+export { touchAgent } from './touchAgent';
 export { markAgentDead } from './markAgentDead';
 export { markAgentIdle } from './markAgentIdle';

package/dist/agents/index.js

@@ -4,9 +4,13 @@ export { unregisterAgent } from './unregisterAgent';
 // Query
 export { getAgent } from './getAgent';
 export { getActiveAgents } from './getActiveAgents';
+export { getAgentByPid } from './getAgentByPid';
+export { getAgentBySessionId } from './getAgentBySessionId';
 // Updates
 export { updateAgentContext } from './updateAgentContext';
 export { updateAgentTask } from './updateAgentTask';
 export { updateAgentWorktree } from './updateAgentWorktree';
+export { updateAgentSession } from './updateAgentSession';
+export { touchAgent } from './touchAgent';
 export { markAgentDead } from './markAgentDead';
 export { markAgentIdle } from './markAgentIdle';

package/dist/agents/livenessMode.d.ts

@@ -0,0 +1,2 @@
+export declare function isNetworkLivenessMode(): boolean;
+export declare function getAgentLeaseTtlMs(): number;

package/dist/agents/livenessMode.js

@@ -0,0 +1,13 @@
+const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
+export function isNetworkLivenessMode() {
+    const value = process.env.HIVEMIND_NETWORK_MODE?.trim().toLowerCase();
+    return value ? TRUE_VALUES.has(value) : false;
+}
+export function getAgentLeaseTtlMs() {
+    const raw = process.env.HIVEMIND_AGENT_LEASE_TTL_SECONDS;
+    const seconds = raw ? Number(raw) : 180;
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        return 180_000;
+    }
+    return Math.floor(seconds * 1000);
+}

package/dist/agents/registerAgent.js

@@ -9,10 +9,10 @@ export function registerAgent(db, input = {}) {
     const parsed = parseId(id);
     const timestamp = now();
     const stmt = db.prepare(`
-    INSERT INTO agents (id, hex, label, status, pid, session_id, worktree_id, context_summary, created_at)
-    VALUES (?, ?, ?, 'active', ?, ?, ?, ?, ?)
+    INSERT INTO agents (id, hex, label, status, pid, session_id, last_seen_at, worktree_id, context_summary, created_at)
+    VALUES (?, ?, ?, 'active', ?, ?, ?, ?, ?, ?)
   `);
-    stmt.run(id, parsed.hex, parsed.label ?? null, input.pid ?? null, input.session_id ?? null, input.worktree_id ?? null, input.context_summary ?? null, timestamp);
+    stmt.run(id, parsed.hex, parsed.label ?? null, input.pid ?? null, input.session_id ?? null, timestamp, input.worktree_id ?? null, input.context_summary ?? null, timestamp);
     return {
         id,
         hex: parsed.hex,
@@ -20,6 +20,7 @@ export function registerAgent(db, input = {}) {
         status: 'active',
         pid: input.pid ?? null,
         session_id: input.session_id ?? null,
+        last_seen_at: timestamp,
         current_plan_id: null,
         current_task_id: null,
         worktree_id: input.worktree_id ?? null,

package/dist/agents/touchAgent.d.ts

@@ -0,0 +1,5 @@
+import type { Database } from 'bun:sqlite';
+/**
+ * Heartbeat/lease update for an active agent.
+ */
+export declare function touchAgent(db: Database, agentId: string): boolean;

package/dist/agents/touchAgent.js

@@ -0,0 +1,13 @@
+import { now } from '../datetime/now';
+/**
+ * Heartbeat/lease update for an active agent.
+ */
+export function touchAgent(db, agentId) {
+    const stmt = db.prepare(`
+    UPDATE agents
+    SET last_seen_at = ?, status = 'active'
+    WHERE id = ? AND status != 'dead'
+  `);
+    const result = stmt.run(now(), agentId);
+    return result.changes > 0;
+}

package/dist/agents/types.d.ts

@@ -12,6 +12,7 @@ export type Agent = {
     status: AgentStatus;
     pid: number | null;
     session_id: string | null;
+    last_seen_at: string | null;
     current_plan_id: string | null;
     current_task_id: string | null;
     worktree_id: string | null;

package/dist/agents/updateAgentSession.d.ts

@@ -0,0 +1,6 @@
+import type { Database } from 'bun:sqlite';
+/**
+ * Update an agent's session ID
+ * Called when conversation compacts and gets a new session ID
+ */
+export declare function updateAgentSession(db: Database, agentId: string, sessionId: string): void;

package/dist/agents/updateAgentSession.js

@@ -0,0 +1,12 @@
+import { now } from '../datetime/now';
+/**
+ * Update an agent's session ID
+ * Called when conversation compacts and gets a new session ID
+ */
+export function updateAgentSession(db, agentId, sessionId) {
+    const timestamp = now();
+    const stmt = db.prepare(`
+    UPDATE agents SET session_id = ?, last_seen_at = ? WHERE id = ?
+  `);
+    stmt.run(sessionId, timestamp, agentId);
+}

package/dist/cli/init.js

@@ -12,6 +12,7 @@ import { getGitInfo } from '../git/getGitInfo';
 import { initializeDb } from '../db/initializeDb';
 import { getProjectPaths } from '../db/getProjectPaths';
 import { initClaudeConfig } from '../init/claudeConfig';
+import { isMcpRegistered } from './registerMcp';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const HIVEMIND_ROOT = join(__dirname, '../..');
 export async function initCommand(options) {
@@ -61,11 +62,18 @@ export async function initCommand(options) {
     else {
         console.log('\n[2/2] Claude Config (skipped)');
     }
+    // Check if MCP is set up globally
+    const mcpReady = await isMcpRegistered();
     // Success
     console.log('\n---');
-    console.log('Project registered! Restart Claude Code to activate.');
-    console.log('\nNext session will:');
-    console.log('  - Auto-register as a hivemind agent');
-    console.log('  - Have hivemind MCP tools available');
-    console.log('  - Follow 001-style task numbering');
+    if (mcpReady) {
+        console.log('Project registered! Restart Claude Code to activate.');
+        console.log('\nNext session will:');
+        console.log('  - Auto-register as a hivemind agent');
+        console.log('  - Have hivemind MCP tools available');
+    }
+    else {
+        console.log('Project registered, but MCP not set up globally.');
+        console.log('\nRun `hivemind install` first to set up MCP tools.');
+    }
 }

package/dist/cli/install.d.ts

@@ -4,5 +4,6 @@
  * Run from hivemind directory to:
  * 1. Install dependencies
  * 2. Register MCP server globally
+ * 3. Configure permissions
  */
 export declare function installCommand(): Promise<void>;

package/dist/cli/install.js

@@ -4,6 +4,7 @@
  * Run from hivemind directory to:
  * 1. Install dependencies
  * 2. Register MCP server globally
+ * 3. Configure permissions
  */
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
@@ -11,6 +12,7 @@ import { $ } from 'bun';
 import { registerMcpServer, configurePermissions } from './registerMcp';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const HIVEMIND_ROOT = join(__dirname, '../..');
+const CLI_ENTRY = join(HIVEMIND_ROOT, 'src/cli.ts');
 export async function installCommand() {
     console.log('hivemind install\n');
     // 1. Install dependencies
@@ -35,13 +37,15 @@ export async function installCommand() {
     const permResult = configurePermissions();
     console.log(`  ${permResult.message}`);
     if (permResult.added.length > 0) {
-        console.log('  auto-approved: status, events, query, claim/start/complete task');
-        console.log('  requires approval: emit (ad-hoc messages)');
+        console.log('  auto-approved: status, events, query, emit, claim/start/complete task');
+        console.log('  requires approval: reset (destructive)');
     }
     // Success
     console.log('\n---');
-    console.log('Hivemind installed globally!');
-    console.log('\nNext steps:');
+    console.log('Hivemind installed!');
+    console.log('\nAdd this to your shell profile (~/.zshrc or ~/.bashrc):');
+    console.log(`\n  alias hivemind='bun run ${CLI_ENTRY}'`);
+    console.log('\nThen:');
     console.log('  cd <your-project>');
-    console.log('  bun run /path/to/hivemind init');
+    console.log('  hivemind init');
 }

package/dist/cli/registerMcp.js

@@ -17,6 +17,8 @@ const AUTO_APPROVED_TOOLS = [
     'mcp__hivemind__hivemind_status',
     'mcp__hivemind__hivemind_events',
     'mcp__hivemind__hivemind_query',
+    // Event logging
+    'mcp__hivemind__hivemind_emit',
     // Task management (structured operations)
     'mcp__hivemind__hivemind_claim_task',
     'mcp__hivemind__hivemind_start_task',
@@ -25,7 +27,6 @@ const AUTO_APPROVED_TOOLS = [
     'mcp__hivemind__hivemind_worktree_cleanup',
 ];
 // NOT auto-approved (require human oversight):
-// - hivemind_emit: allows arbitrary messages to other agents
 // - hivemind_reset: destructive operation that wipes the database
 /**
  * Register the hivemind MCP server using `claude mcp add`
@@ -43,8 +44,8 @@ export async function registerMcpServer(hivemindRoot) {
                 alreadyRegistered: true,
             };
         }
-        // Register the MCP server
-        await $ `claude mcp add --transport stdio hivemind -- ${command}`.quiet();
+        // Register the MCP server globally (user scope = available in all projects)
+        await $ `claude mcp add --transport stdio --scope user hivemind -- bun run ${serverPath}`.quiet();
         return {
             success: true,
             message: `registered: hivemind -> ${command}`,

package/dist/coordinator/index.js

@@ -13,6 +13,7 @@ import { getActiveAgents } from '../agents/getActiveAgents';
 import { markAgentDead } from '../agents/markAgentDead';
 import { startPlanWatcher } from '../watcher/planWatcher';
 import { emit } from '../events/emit';
+import { getAgentLeaseTtlMs, isNetworkLivenessMode } from '../agents/livenessMode';
 import * as fs from 'fs';
 import * as path from 'path';
 import { parseDatetime } from '../datetime/parseDatetime';
@@ -39,6 +40,13 @@ function isOldEnough(createdAt) {
         return false;
     return Date.now() - created.getTime() > MIN_AGE_MS;
 }
+function isLeaseExpired(lastSeenAt, createdAt, ttlMs) {
+    const source = lastSeenAt ?? createdAt;
+    const seen = parseDatetime(source);
+    if (!seen)
+        return false;
+    return Date.now() - seen.getTime() > ttlMs;
+}
 function getLockPath(config) {
     return path.join(config.dataDir, 'coordinator.lock');
 }
@@ -89,10 +97,34 @@ function releaseLock(config) {
 }
 function sweep(config) {
     const db = getConnection(config.project);
+    const networkMode = isNetworkLivenessMode();
+    const leaseTtlMs = getAgentLeaseTtlMs();
     // Get all active agents and check if their PIDs are alive
     const activeAgents = getActiveAgents(db);
     let marked = 0;
     for (const agent of activeAgents) {
+        if (networkMode) {
+            if (!isLeaseExpired(agent.last_seen_at, agent.created_at, leaseTtlMs)) {
+                continue;
+            }
+            markAgentDead(db, agent.id);
+            emit(db, {
+                type: 'agent:dead',
+                agent_id: agent.id,
+                worktree_id: agent.worktree_id ?? undefined,
+                content: `Agent ${agent.id} lease expired`,
+                metadata: {
+                    reason: 'lease_expired',
+                    last_seen_at: agent.last_seen_at,
+                    lease_ttl_ms: leaseTtlMs,
+                    label: agent.label,
+                    current_task_id: agent.current_task_id,
+                    current_plan_id: agent.current_plan_id,
+                },
+            });
+            marked++;
+            continue;
+        }
         // Skip agents that are too new (grace period)
         if (!isOldEnough(agent.created_at)) {
             continue;

package/dist/db/db.test.js

@@ -33,10 +33,11 @@ describe('SQLite Database', () => {
             expect(indexes.length).toBeGreaterThan(0);
         });
     });
-    describe('WAL mode', () => {
-        it('uses WAL journal mode', () => {
+    describe('journal mode', () => {
+        it('uses memory journal mode for in-memory test db', () => {
             const result = testDb.db.query('PRAGMA journal_mode').get();
-            expect(result.journal_mode).toBe('wal');
+            // In-memory databases use 'memory' journal mode
+            expect(result.journal_mode).toBe('memory');
         });
     });
     describe('basic CRUD operations', () => {

package/dist/db/getConnection.js

@@ -2,6 +2,7 @@ import { Database } from 'bun:sqlite';
 import { existsSync } from 'fs';
 import { getProjectPaths } from './getProjectPaths';
 import { initializeDb } from './initializeDb';
+import { migrateDb } from './migrateDb';
 const connections = new Map();
 /**
  * Get database connection for a project
@@ -17,6 +18,7 @@ export function getConnection(projectName) {
     if (existsSync(paths.dbPath)) {
         db = new Database(paths.dbPath);
         db.exec('PRAGMA journal_mode = WAL');
+        migrateDb(db);
     }
     else {
         db = initializeDb(projectName);

package/dist/db/initializeDb.js

@@ -4,6 +4,7 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { getProjectPaths } from './getProjectPaths';
 import { ensureProjectDirs } from './ensureProjectDirs';
+import { migrateDb } from './migrateDb';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /**
  * Initialize the database for a project
@@ -19,5 +20,6 @@ export function initializeDb(projectName) {
     // Run schema
     const schema = readFileSync(join(__dirname, 'schema.sql'), 'utf-8');
     db.exec(schema);
+    migrateDb(db);
     return db;
 }

package/dist/db/migrateDb.d.ts

@@ -0,0 +1,6 @@
+import type { Database } from 'bun:sqlite';
+/**
+ * Lightweight compatibility migrations for existing project databases.
+ * Keep this idempotent and safe to run on every connection open.
+ */
+export declare function migrateDb(db: Database): void;

package/dist/db/migrateDb.js

@@ -0,0 +1,14 @@
+function hasColumn(db, table, column) {
+    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+    return rows.some((row) => row.name === column);
+}
+/**
+ * Lightweight compatibility migrations for existing project databases.
+ * Keep this idempotent and safe to run on every connection open.
+ */
+export function migrateDb(db) {
+    if (!hasColumn(db, 'agents', 'last_seen_at')) {
+        db.exec('ALTER TABLE agents ADD COLUMN last_seen_at TEXT');
+    }
+    db.exec('CREATE INDEX IF NOT EXISTS idx_agents_last_seen ON agents(last_seen_at)');
+}