claude-mycelium 2.0.0 → 2.2.0

package/src/cli/status.ts

@@ -0,0 +1,218 @@
+/**
+ * Status CLI Command
+ *
+ * Display system overview
+ * Show agent count, recent activity
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { fileExists } from '../utils/file-utils.js';
+import { loadConfig } from '../utils/config.js';
+import type { TraceEvent } from '../types/index.js';
+
+const command = new Command()
+  .name('status')
+  .description('Show system status and recent activity')
+  .option('--json', 'Output as JSON')
+  .action(async (options: any) => {
+    try {
+      const status = await getSystemStatus();
+
+      if (options.json) {
+        console.log(JSON.stringify(status, null, 2));
+        return;
+      }
+
+      // Colorized output
+      console.log('');
+      console.log(chalk.bold('Claude Mycelium Status'));
+      console.log(chalk.dim('─'.repeat(60)));
+
+      console.log(chalk.bold('Configuration:'));
+      console.log(
+        `  Config version: ${status.config.version}`
+      );
+      console.log(
+        `  Created: ${new Date(status.config.created_at).toLocaleDateString()}`
+      );
+      console.log(
+        `  Error provider: ${status.config.error_provider}`
+      );
+
+      console.log(chalk.bold('Statistics:'));
+      console.log(`  Total spawns: ${status.spawn_count}`);
+      console.log(`  Last GC at spawn: ${status.last_gc_at_spawn}`);
+      console.log(
+        `  Spawns since GC: ${status.spawn_count - status.last_gc_at_spawn}`
+      );
+
+      console.log(chalk.bold('Storage:'));
+      console.log(`  Trace events: ${status.trace_event_count}`);
+      console.log(`  Quarantined files: ${status.quarantine_count}`);
+      console.log(`  Inhibitors: ${status.inhibitor_count}`);
+      console.log(
+        `  Errors logged: ${status.error_count}`
+      );
+
+      if (status.recent_activity.length > 0) {
+        console.log(chalk.bold('Recent Activity (last 5):'));
+        for (const activity of status.recent_activity.slice(0, 5)) {
+          const timeAgo = getTimeAgo(new Date(activity.timestamp));
+          const modeColor = getModeColor(activity.mode);
+          console.log(
+            `  ${chalk[modeColor](activity.mode.padEnd(18))} ${activity.file.substring(0, 35).padEnd(35)} ${timeAgo.padStart(10)}`
+          );
+        }
+      }
+
+      console.log(chalk.dim('─'.repeat(60)));
+      console.log('');
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      console.error(chalk.red(`Error: ${message}`));
+      process.exit(1);
+    }
+  });
+
+/**
+ * Get system status
+ */
+async function getSystemStatus() {
+  const config = loadConfig();
+  let traceEventCount = 0;
+  let quarantineCount = 0;
+  let inhibitorCount = 0;
+  let errorCount = 0;
+  const recentActivity: Array<{ timestamp: string; mode: string; file: string }> = [];
+
+  // Count trace events
+  const tracesDir = '.agent-meta/traces';
+  if (fileExists(tracesDir)) {
+    try {
+      const entries = await fs.readdir(tracesDir);
+      const traceFiles = entries.filter(f => f.endsWith('.ndjson'));
+
+      for (const file of traceFiles) {
+        const filePath = path.join(tracesDir, file);
+
+        try {
+          const content = await fs.readFile(filePath, 'utf-8');
+          const lines = content.split('\n').filter(Boolean);
+          traceEventCount += lines.length;
+
+          // Collect recent activity
+          for (const line of lines) {
+            try {
+              const event = JSON.parse(line) as TraceEvent;
+              recentActivity.push({
+                timestamp: event.timestamp,
+                mode: event.mode,
+                file: event.file_path,
+              });
+            } catch {
+              // Skip malformed lines
+            }
+          }
+        } catch {
+          // File read error
+        }
+      }
+    } catch {
+      // Directory read error
+    }
+  }
+
+  // Count quarantine entries
+  const quarantinePath = '.agent-meta/_quarantine.json';
+  if (fileExists(quarantinePath)) {
+    try {
+      const content = await fs.readFile(quarantinePath, 'utf-8');
+      const quarantine = JSON.parse(content);
+      quarantineCount = (quarantine.entries || []).length;
+    } catch {
+      // File read error
+    }
+  }
+
+  // Count inhibitors
+  const inhibitorsPath = '.agent-meta/_inhibitors.ndjson';
+  if (fileExists(inhibitorsPath)) {
+    try {
+      const content = await fs.readFile(inhibitorsPath, 'utf-8');
+      const lines = content.split('\n').filter(Boolean);
+      inhibitorCount = lines.length;
+    } catch {
+      // File read error
+    }
+  }
+
+  // Count errors
+  const errorsPath = '.agent-meta/_errors.json';
+  if (fileExists(errorsPath)) {
+    try {
+      const content = await fs.readFile(errorsPath, 'utf-8');
+      const errors = JSON.parse(content);
+      errorCount = (errors.errors || []).length;
+    } catch {
+      // File read error
+    }
+  }
+
+  // Sort recent activity by timestamp descending
+  recentActivity.sort(
+    (a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()
+  );
+
+  return {
+    config,
+    spawn_count: config.spawn_count,
+    last_gc_at_spawn: config.last_gc_at_spawn,
+    trace_event_count: traceEventCount,
+    quarantine_count: quarantineCount,
+    inhibitor_count: inhibitorCount,
+    error_count: errorCount,
+    recent_activity: recentActivity.slice(0, 10),
+  };
+}
+
+/**
+ * Get human-readable time ago
+ */
+function getTimeAgo(date: Date): string {
+  const now = new Date();
+  const diff = now.getTime() - date.getTime();
+  const seconds = Math.floor(diff / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) return `${days}d ago`;
+  if (hours > 0) return `${hours}h ago`;
+  if (minutes > 0) return `${minutes}m ago`;
+  return `${seconds}s ago`;
+}
+
+/**
+ * Get color for mode
+ */
+function getModeColor(mode: string): 'red' | 'yellow' | 'green' | 'blue' | 'magenta' | 'cyan' {
+  switch (mode) {
+    case 'error_reducer':
+      return 'red';
+    case 'complexity_reducer':
+      return 'yellow';
+    case 'debt_payer':
+      return 'magenta';
+    case 'stabilizer':
+      return 'green';
+    case 'explorer':
+      return 'cyan';
+    default:
+      return 'blue';
+  }
+}
+
+export default command;

package/src/coordination/file-locks.ts

@@ -0,0 +1,300 @@
+/**
+ * File-based locking for multi-agent coordination
+ * Uses atomic O_CREAT|O_EXCL flags via fs.open() for race-free lock acquisition
+ *
+ * Reference: ADR-004, second-spec §4.1
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import type { LockFile, Mode } from '../types/index.js';
+
+const LOCK_DIR = '.agent-meta/locks';
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Acquire an exclusive lock on a file
+ * Uses atomic O_CREAT|O_EXCL to prevent races
+ *
+ * @param filePath - File to lock (relative path)
+ * @param agentId - Agent requesting the lock
+ * @param mode - Mode of operation
+ * @param taskId - Optional task ID
+ * @returns true if lock acquired, false if already locked
+ */
+export async function acquireLock(
+  filePath: string,
+  agentId: string,
+  mode: Mode,
+  taskId?: string
+): Promise<boolean> {
+  await ensureLockDir();
+
+  const lockPath = getLockPath(filePath);
+  const now = new Date();
+  const expiresAt = new Date(now.getTime() + DEFAULT_TIMEOUT_MS);
+
+  const lockData: LockFile = {
+    agent_id: agentId,
+    file: filePath,
+    mode,
+    acquired_at: now.toISOString(),
+    expires_at: expiresAt.toISOString(),
+    pid: process.pid,
+    task_id: taskId,
+  };
+
+  try {
+    // Check for expired lock first and attempt takeover
+    const takenOver = await tryTakeoverExpiredLock(lockPath, lockData);
+    if (takenOver) {
+      return true;
+    }
+
+    // Atomic creation: wx = O_CREAT|O_EXCL
+    // Will fail if file already exists
+    const fd = await fs.open(lockPath, 'wx');
+    await fd.writeFile(JSON.stringify(lockData, null, 2));
+    await fd.close();
+
+    return true;
+  } catch (error: any) {
+    if (error.code === 'EEXIST') {
+      // Lock already exists, check if we can take it over
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Release a lock
+ *
+ * @param filePath - File to unlock
+ * @returns true if lock released, false if not locked by this process
+ */
+export async function releaseLock(filePath: string): Promise<boolean> {
+  const lockPath = getLockPath(filePath);
+
+  try {
+    // Verify we own the lock before releasing
+    const content = await fs.readFile(lockPath, 'utf-8');
+    const lock: LockFile = JSON.parse(content);
+
+    if (lock.pid !== process.pid) {
+      // Not our lock
+      return false;
+    }
+
+    await fs.unlink(lockPath);
+    return true;
+  } catch (error: any) {
+    if (error.code === 'ENOENT') {
+      // Lock doesn't exist
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Check if a file is locked
+ *
+ * @param filePath - File to check
+ * @returns LockFile if locked and valid, null otherwise
+ */
+export async function checkLock(filePath: string): Promise<LockFile | null> {
+  const lockPath = getLockPath(filePath);
+
+  try {
+    const content = await fs.readFile(lockPath, 'utf-8');
+    const lock: LockFile = JSON.parse(content);
+
+    // Check if lock is expired
+    if (isExpired(lock)) {
+      return null;
+    }
+
+    // Check if process is alive
+    if (!isProcessAlive(lock.pid)) {
+      return null;
+    }
+
+    return lock;
+  } catch (error: any) {
+    if (error.code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Try to take over an expired or dead process lock
+ *
+ * @param lockPath - Path to lock file
+ * @param newLock - New lock data
+ * @returns true if takeover successful
+ */
+async function tryTakeoverExpiredLock(
+  lockPath: string,
+  newLock: LockFile
+): Promise<boolean> {
+  try {
+    const content = await fs.readFile(lockPath, 'utf-8');
+    const oldLock: LockFile = JSON.parse(content);
+
+    // Check if lock is expired
+    if (isExpired(oldLock)) {
+      await fs.unlink(lockPath);
+      const fd = await fs.open(lockPath, 'wx');
+      await fd.writeFile(JSON.stringify(newLock, null, 2));
+      await fd.close();
+      return true;
+    }
+
+    // Check if process is dead
+    if (!isProcessAlive(oldLock.pid)) {
+      await fs.unlink(lockPath);
+      const fd = await fs.open(lockPath, 'wx');
+      await fd.writeFile(JSON.stringify(newLock, null, 2));
+      await fd.close();
+      return true;
+    }
+
+    return false;
+  } catch (error: any) {
+    if (error.code === 'ENOENT') {
+      // Lock doesn't exist, normal acquisition can proceed
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Check if a lock has expired (5-minute timeout)
+ */
+function isExpired(lock: LockFile): boolean {
+  const expiresAt = new Date(lock.expires_at);
+  return Date.now() > expiresAt.getTime();
+}
+
+/**
+ * Check if a process is alive
+ * Uses process.kill(pid, 0) which doesn't actually kill but checks existence
+ */
+function isProcessAlive(pid: number): boolean {
+  try {
+    // Signal 0 checks if process exists without killing it
+    process.kill(pid, 0);
+    return true;
+  } catch (error: any) {
+    if (error.code === 'ESRCH') {
+      // Process not found
+      return false;
+    }
+    if (error.code === 'EPERM') {
+      // Process exists but we don't have permission to signal it
+      // This means it's alive
+      return true;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Get the lock file path for a given file
+ */
+function getLockPath(filePath: string): string {
+  // Sanitize file path to create a unique lock filename
+  const sanitized = filePath.replace(/[^a-zA-Z0-9]/g, '_');
+  return path.join(LOCK_DIR, `${sanitized}.lock`);
+}
+
+/**
+ * Ensure lock directory exists
+ */
+async function ensureLockDir(): Promise<void> {
+  try {
+    await fs.mkdir(LOCK_DIR, { recursive: true });
+  } catch (error: any) {
+    if (error.code !== 'EEXIST') {
+      throw error;
+    }
+  }
+}
+
+/**
+ * List all active locks
+ */
+export async function listLocks(): Promise<LockFile[]> {
+  try {
+    await ensureLockDir();
+    const files = await fs.readdir(LOCK_DIR);
+    const locks: LockFile[] = [];
+
+    for (const file of files) {
+      if (!file.endsWith('.lock')) continue;
+
+      try {
+        const lockPath = path.join(LOCK_DIR, file);
+        const content = await fs.readFile(lockPath, 'utf-8');
+        const lock: LockFile = JSON.parse(content);
+
+        // Only include valid locks
+        if (!isExpired(lock) && isProcessAlive(lock.pid)) {
+          locks.push(lock);
+        }
+      } catch {
+        // Skip invalid lock files
+        continue;
+      }
+    }
+
+    return locks;
+  } catch (error: any) {
+    if (error.code === 'ENOENT') {
+      return [];
+    }
+    throw error;
+  }
+}
+
+/**
+ * Clean up expired and dead process locks
+ * Returns the number of locks cleaned up
+ */
+export async function cleanupStaleLocks(): Promise<number> {
+  try {
+    await ensureLockDir();
+    const files = await fs.readdir(LOCK_DIR);
+    let cleaned = 0;
+
+    for (const file of files) {
+      if (!file.endsWith('.lock')) continue;
+
+      try {
+        const lockPath = path.join(LOCK_DIR, file);
+        const content = await fs.readFile(lockPath, 'utf-8');
+        const lock: LockFile = JSON.parse(content);
+
+        // Remove if expired or process is dead
+        if (isExpired(lock) || !isProcessAlive(lock.pid)) {
+          await fs.unlink(lockPath);
+          cleaned++;
+        }
+      } catch {
+        // Skip files we can't process
+        continue;
+      }
+    }
+
+    return cleaned;
+  } catch (error: any) {
+    if (error.code === 'ENOENT') {
+      return 0;
+    }
+    throw error;
+  }
+}

package/src/coordination/index.ts

@@ -5,6 +5,10 @@
  * - Gradient caching
  * - File locks (Phase 3)
  * - Process management (Phase 3)
+ * - Inhibitor signals (Phase 4)
  */
 
 export * from './gradient-cache.js';
+export * from './file-locks.js';
+export * from './process-manager.js';
+export * from './inhibitors.js';