chati-dev 3.2.5 → 3.3.0

package/src/terminal/spawner.js

@@ -11,6 +11,19 @@ import { spawn } from 'child_process';
 import { validateWriteScopes, buildIsolationEnv } from './isolation.js';
 import { getProvider } from './cli-registry.js';
 
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default maximum concurrent processes when spawning in parallel. */
+export const DEFAULT_CONCURRENCY = 3;
+
+/** Patterns that indicate a transient failure (worth retrying). */
+export const TRANSIENT_PATTERNS = [
+  /rate limit/i, /too many requests/i, /429/, /503/,
+  /timeout/i, /ECONNRESET/, /ECONNREFUSED/,
+];
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -150,6 +163,7 @@ export function buildSpawnCommand(config) {
   // Resolve CLI provider — defaults to claude for backwards compatibility
   const providerName = config.provider || 'claude';
   let command, args, prompt;
+  let providerFallback = null;
 
   try {
     const provider = getProvider(providerName);
@@ -159,6 +173,12 @@ export function buildSpawnCommand(config) {
     prompt = adapterResult.stdinPrompt;
   } catch (err) {
     // Fallback to claude if provider resolution fails (backwards compatibility)
+    providerFallback = {
+      requested: providerName,
+      actual: 'claude',
+      reason: err.message,
+      timestamp: new Date().toISOString(),
+    };
     console.error(`[chati] Provider "${providerName}" resolution failed: ${err.message}. Falling back to claude.`);
     command = 'claude';
     args = ['--print', '--dangerously-skip-permissions'];
@@ -170,7 +190,7 @@ export function buildSpawnCommand(config) {
     prompt = config.prompt || null;
   }
 
-  return { command, args, env, terminalId, prompt };
+  return { command, args, env, terminalId, prompt, providerFallback };
 }
 
 /**
@@ -180,7 +200,7 @@ export function buildSpawnCommand(config) {
  * @returns {TerminalHandle}
  */
 export function spawnTerminal(config) {
-  const { command, args, env, terminalId, prompt } = buildSpawnCommand(config);
+  const { command, args, env, terminalId, prompt, providerFallback } = buildSpawnCommand(config);
 
   const cwd = config.workingDir || process.cwd();
   const timeout = config.timeout || 300_000; // default 5 minutes
@@ -204,6 +224,8 @@ export function spawnTerminal(config) {
     agent: config.agent,
     taskId: config.taskId,
     model: config.model || 'unknown',
+    provider: config.provider || 'claude',
+    providerFallback,
     startedAt: new Date().toISOString(),
     status: 'running',
     exitCode: null,
@@ -285,6 +307,96 @@ export function spawnParallelGroup(configs) {
   };
 }
 
+/**
+ * Spawn a group of terminals with concurrency control (pool pattern).
+ *
+ * Unlike `spawnParallelGroup` which launches all at once, this function
+ * limits the number of simultaneously running processes. When one process
+ * exits, the next in the queue is spawned.
+ *
+ * @param {SpawnConfig[]} configs
+ * @param {{ maxConcurrency?: number }} [options={}]
+ * @returns {Promise<{ groupId: string, terminals: TerminalHandle[], startedAt: string }>}
+ * @throws {Error} When write scope conflicts are detected
+ */
+export async function spawnParallelGroupAsync(configs, options = {}) {
+  if (!Array.isArray(configs) || configs.length === 0) {
+    throw new Error('spawnParallelGroupAsync requires a non-empty array of configs');
+  }
+
+  const maxConcurrency = options.maxConcurrency || DEFAULT_CONCURRENCY;
+
+  const validation = validateWriteScopes(configs);
+  if (!validation.valid) {
+    const details = validation.conflicts
+      .map(c => `${c.agents.join(' vs ')} on ${c.path}`)
+      .join('; ');
+    throw new Error(`Write scope conflicts detected: ${details}`);
+  }
+
+  const groupId = `group-${Date.now()}`;
+  const startedAt = new Date().toISOString();
+
+  // If within concurrency limit, spawn all at once (fast path)
+  if (configs.length <= maxConcurrency) {
+    const terminals = configs.map(cfg => spawnTerminal(cfg));
+    return { groupId, terminals, startedAt };
+  }
+
+  // Pool pattern: spawn up to maxConcurrency, refill as processes exit
+  const terminals = [];
+  const queue = [...configs];
+  const active = new Set();
+
+  /**
+   * Wait for a terminal to exit. Returns a Promise that resolves
+   * when the terminal's process emits 'exit'.
+   */
+  function waitForExit(handle) {
+    if (handle.status !== 'running') {
+      return Promise.resolve();
+    }
+    return new Promise(resolve => {
+      if (!handle.process) {
+        resolve();
+        return;
+      }
+      handle.process.once('exit', () => resolve());
+    });
+  }
+
+  // Fill initial pool
+  while (queue.length > 0 && active.size < maxConcurrency) {
+    const cfg = queue.shift();
+    const handle = spawnTerminal(cfg);
+    terminals.push(handle);
+    active.add(handle);
+  }
+
+  // Process remaining queue as slots free up
+  while (queue.length > 0) {
+    // Wait for ANY active process to exit
+    await Promise.race([...active].map(h => waitForExit(h)));
+
+    // Remove exited processes from active set
+    for (const h of active) {
+      if (h.status !== 'running') {
+        active.delete(h);
+      }
+    }
+
+    // Fill freed slots
+    while (queue.length > 0 && active.size < maxConcurrency) {
+      const cfg = queue.shift();
+      const handle = spawnTerminal(cfg);
+      terminals.push(handle);
+      active.add(handle);
+    }
+  }
+
+  return { groupId, terminals, startedAt };
+}
+
 /**
  * Gracefully kill a spawned terminal.
  * Sends SIGTERM first; if the process is still alive after 5 seconds,
@@ -336,7 +448,7 @@ export function killTerminal(handle) {
  */
 export function getTerminalStatus(handle) {
   if (!handle) {
-    return { id: 'unknown', agent: 'unknown', model: 'unknown', status: 'unknown', elapsed: 0, exitCode: null };
+    return { id: 'unknown', agent: 'unknown', model: 'unknown', provider: 'unknown', status: 'unknown', elapsed: 0, exitCode: null, providerFallback: null };
   }
 
   const elapsed = Date.now() - new Date(handle.startedAt).getTime();
@@ -345,8 +457,74 @@ export function getTerminalStatus(handle) {
     id: handle.id,
     agent: handle.agent,
     model: handle.model || 'unknown',
+    provider: handle.provider || 'unknown',
     status: handle.status,
     elapsed,
     exitCode: handle.exitCode,
+    providerFallback: handle.providerFallback || null,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Retry / Backoff
+// ---------------------------------------------------------------------------
+
+/**
+ * Determine whether a terminal failure is transient (worth retrying).
+ *
+ * @param {number} exitCode - Process exit code
+ * @param {string[]|string} stderr - Captured stderr output
+ * @returns {boolean}
+ */
+export function isTransientFailure(exitCode, stderr) {
+  if (exitCode === 0) return false;
+  const str = Array.isArray(stderr) ? stderr.join('') : (stderr || '');
+  return TRANSIENT_PATTERNS.some(p => p.test(str));
+}
+
+/**
+ * Spawn a terminal with automatic retry on transient failures.
+ *
+ * Wraps `spawnTerminal()` with exponential backoff.
+ * Non-transient failures are returned immediately without retry.
+ *
+ * @param {SpawnConfig} config
+ * @param {{ maxRetries?: number, baseDelay?: number, shouldRetry?: function }} [retryOptions={}]
+ * @returns {Promise<TerminalHandle>}
+ */
+export async function spawnTerminalWithRetry(config, retryOptions = {}) {
+  const maxRetries = retryOptions.maxRetries ?? 2;
+  const baseDelay = retryOptions.baseDelay ?? 2000;
+  const shouldRetry = retryOptions.shouldRetry || isTransientFailure;
+
+  let lastHandle = null;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const handle = spawnTerminal(config);
+    lastHandle = handle;
+
+    // Wait for process to exit
+    await new Promise((resolve) => {
+      if (!handle.process) { resolve(); return; }
+      if (handle.status !== 'running') { resolve(); return; }
+      handle.process.once('exit', () => resolve());
+    });
+
+    // Success — return immediately
+    if (handle.exitCode === 0) {
+      return handle;
+    }
+
+    // Check if failure is transient and retries remain
+    if (attempt < maxRetries && shouldRetry(handle.exitCode, handle.stderr)) {
+      const delay = baseDelay * Math.pow(2, attempt);
+      await new Promise(resolve => setTimeout(resolve, delay));
+      continue;
+    }
+
+    // Non-transient or out of retries — return as-is
+    return handle;
+  }
+
+  return lastHandle;
+}

package/src/upgrade/migrator.js

@@ -149,8 +149,8 @@ export async function runMigrations(targetDir, fromVersion, toVersion) {
         for (const step of migration.rollback) {
           executeMigrationStep(targetDir, step);
         }
-      } catch {
-        // Rollback failed - return error
+      } catch (rollbackErr) {
+        console.error('[chati] migration rollback failed:', rollbackErr?.message);
       }
 
       return {

package/src/utils/event-bus.js

@@ -0,0 +1,126 @@
+/**
+ * @fileoverview Singleton event bus for the chati.dev framework.
+ *
+ * Provides a centralized EventEmitter for observing state changes
+ * across subsystems (build-loop, spawner, pipeline, safety-net).
+ */
+
+/**
+ * @deprecated Not currently imported by any production module.
+ * Retained for potential future integration. Remove if still unused by v4.0.
+ */
+
+import { EventEmitter } from 'node:events';
+
+// ---------------------------------------------------------------------------
+// Event Names
+// ---------------------------------------------------------------------------
+
+/**
+ * All framework event names, organized by subsystem.
+ */
+export const EVENTS = {
+  // Build loop
+  BUILD_STARTED: 'build:started',
+  BUILD_COMPLETED: 'build:completed',
+  BUILD_FAILED: 'build:failed',
+  TASK_STARTED: 'build:task:started',
+  TASK_COMPLETED: 'build:task:completed',
+  TASK_FAILED: 'build:task:failed',
+  TASK_EXHAUSTED: 'build:task:exhausted',
+
+  // Spawner
+  TERMINAL_SPAWNED: 'terminal:spawned',
+  TERMINAL_EXITED: 'terminal:exited',
+  TERMINAL_KILLED: 'terminal:killed',
+
+  // Pipeline
+  PHASE_ADVANCED: 'pipeline:phase:advanced',
+  AGENT_COMPLETED: 'pipeline:agent:completed',
+  QA_GATE_PASSED: 'pipeline:qa:passed',
+  QA_GATE_FAILED: 'pipeline:qa:failed',
+
+  // Safety
+  SAFETY_TRIGGERED: 'safety:triggered',
+
+  // Health
+  HEALTH_CHECK_COMPLETED: 'health:completed',
+
+  // Escalation
+  ESCALATION_TRIGGERED: 'escalation:triggered',
+  ESCALATION_PAUSED: 'escalation:paused',
+};
+
+// ---------------------------------------------------------------------------
+// Bus Instance
+// ---------------------------------------------------------------------------
+
+const bus = new EventEmitter();
+bus.setMaxListeners(50);
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Emit an event with data. Automatically adds a timestamp.
+ *
+ * @param {string} event - Event name from EVENTS
+ * @param {object} [data={}] - Event payload
+ */
+export function emit(event, data = {}) {
+  bus.emit(event, { ...data, timestamp: Date.now() });
+}
+
+/**
+ * Subscribe to an event.
+ *
+ * @param {string} event - Event name
+ * @param {function} handler - Event handler
+ */
+export function on(event, handler) {
+  bus.on(event, handler);
+}
+
+/**
+ * Subscribe to an event once.
+ *
+ * @param {string} event - Event name
+ * @param {function} handler - Event handler
+ */
+export function once(event, handler) {
+  bus.once(event, handler);
+}
+
+/**
+ * Unsubscribe from an event.
+ *
+ * @param {string} event - Event name
+ * @param {function} handler - Event handler to remove
+ */
+export function off(event, handler) {
+  bus.off(event, handler);
+}
+
+/**
+ * Remove all listeners for an event, or all events if no event specified.
+ *
+ * @param {string} [event] - Event name (optional)
+ */
+export function removeAllListeners(event) {
+  if (event) {
+    bus.removeAllListeners(event);
+  } else {
+    bus.removeAllListeners();
+  }
+}
+
+/**
+ * Get the count of listeners for an event.
+ *
+ * @param {string} event - Event name
+ * @returns {number}
+ */
+export function listenerCount(event) {
+  return bus.listenerCount(event);
+}

package/src/utils/file-lock.js

@@ -0,0 +1,291 @@
+/**
+ * @fileoverview Advisory file locking using .lock files + PID.
+ *
+ * Prevents concurrent writes to shared state files (session.yaml,
+ * build-state.json) during multi-terminal execution.
+ */
+
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default lock acquisition timeout in ms */
+export const DEFAULT_TIMEOUT = 5000;
+
+/** Default retry interval in ms */
+export const DEFAULT_RETRY_INTERVAL = 100;
+
+/** Default stale threshold in ms (30 seconds) */
+export const STALE_THRESHOLD_MS = 30_000;
+
+// ---------------------------------------------------------------------------
+// Lock Management
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the lock file path for a given file.
+ *
+ * @param {string} filePath
+ * @returns {string}
+ */
+function getLockPath(filePath) {
+  return `${filePath}.lock`;
+}
+
+/**
+ * Check if a process is still running.
+ *
+ * @param {number} pid
+ * @returns {boolean}
+ */
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read lock file contents.
+ *
+ * @param {string} lockPath
+ * @returns {{ pid: number, timestamp: number, hostname: string }|null}
+ */
+function readLockFile(lockPath) {
+  try {
+    const content = readFileSync(lockPath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write lock file with current process info.
+ *
+ * @param {string} lockPath
+ */
+function writeLockFile(lockPath) {
+  const dir = dirname(lockPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const lockData = {
+    pid: process.pid,
+    timestamp: Date.now(),
+    hostname: typeof globalThis !== 'undefined' ? (globalThis.process?.env?.HOSTNAME || 'localhost') : 'localhost',
+  };
+  writeFileSync(lockPath, JSON.stringify(lockData), 'utf-8');
+}
+
+/**
+ * Check if a lock is stale (owner process dead or lock too old).
+ *
+ * @param {string} lockPath
+ * @param {object} [options]
+ * @param {boolean} [options.stalePidCheck=true]
+ * @returns {boolean}
+ */
+function isLockStale(lockPath, options = {}) {
+  const { stalePidCheck = true } = options;
+  const lockData = readLockFile(lockPath);
+
+  if (!lockData) return true;
+
+  // Check if lock is too old
+  if (Date.now() - lockData.timestamp > STALE_THRESHOLD_MS) {
+    return true;
+  }
+
+  // Check if owner process is still alive
+  if (stalePidCheck && lockData.pid && !isProcessAlive(lockData.pid)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Acquire an advisory lock on a file.
+ *
+ * @param {string} filePath - Path to the file to lock
+ * @param {object} [options]
+ * @param {number} [options.timeout=5000] - Max time to wait for lock
+ * @param {number} [options.retryInterval=100] - Time between retries
+ * @param {boolean} [options.stalePidCheck=true] - Check if lock owner PID is alive
+ * @returns {{ acquired: boolean, lockPath: string, release: () => void }}
+ */
+export function acquireLock(filePath, options = {}) {
+  const {
+    timeout = DEFAULT_TIMEOUT,
+    retryInterval = DEFAULT_RETRY_INTERVAL,
+    stalePidCheck = true,
+  } = options;
+
+  const lockPath = getLockPath(filePath);
+  const startTime = Date.now();
+
+  while (true) {
+    // If lock file doesn't exist, acquire it
+    if (!existsSync(lockPath)) {
+      writeLockFile(lockPath);
+      return {
+        acquired: true,
+        lockPath,
+        release: () => releaseLock(lockPath),
+      };
+    }
+
+    // If lock is stale, remove and acquire
+    if (isLockStale(lockPath, { stalePidCheck })) {
+      try { unlinkSync(lockPath); } catch { /* ignore */ }
+      writeLockFile(lockPath);
+      return {
+        acquired: true,
+        lockPath,
+        release: () => releaseLock(lockPath),
+      };
+    }
+
+    // Check timeout
+    if (Date.now() - startTime >= timeout) {
+      return {
+        acquired: false,
+        lockPath,
+        release: () => {},
+      };
+    }
+
+    // Busy wait (synchronous - acceptable for short lock durations)
+    const waitUntil = Date.now() + retryInterval;
+    while (Date.now() < waitUntil) { /* spin */ }
+  }
+}
+
+/**
+ * Release an advisory lock.
+ *
+ * @param {string} lockPath - Path to the lock file
+ */
+export function releaseLock(lockPath) {
+  try {
+    if (existsSync(lockPath)) {
+      const lockData = readLockFile(lockPath);
+      // Only release if we own it
+      if (!lockData || lockData.pid === process.pid) {
+        unlinkSync(lockPath);
+      }
+    }
+  } catch {
+    // Lock may already be released — ignore
+  }
+}
+
+/**
+ * Check if a file is currently locked.
+ *
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isLocked(filePath) {
+  const lockPath = getLockPath(filePath);
+  if (!existsSync(lockPath)) return false;
+  return !isLockStale(lockPath);
+}
+
+/**
+ * Execute a function while holding a lock on a file.
+ *
+ * @param {string} filePath - File to lock
+ * @param {function(): T|Promise<T>} fn - Function to execute while holding lock
+ * @param {object} [options] - Lock options
+ * @returns {Promise<T>}
+ * @template T
+ */
+export async function withLock(filePath, fn, options = {}) {
+  const lock = acquireLock(filePath, options);
+
+  if (!lock.acquired) {
+    throw new Error(`Failed to acquire lock on ${filePath}`);
+  }
+
+  try {
+    return await fn();
+  } finally {
+    lock.release();
+  }
+}
+
+/**
+ * Acquire a user-aware lock on a file.
+ * Only the same userId can re-acquire an existing lock.
+ *
+ * @param {string} filePath - File to lock
+ * @param {string} userId - User identifier
+ * @param {object} [options] - Lock options
+ * @param {number} [options.timeout=5000] - Max time to wait
+ * @param {number} [options.retryInterval=100] - Time between retries
+ * @returns {{ acquired: boolean, lockPath: string, owner: string|null, release: () => void }}
+ */
+export function acquireUserLock(filePath, userId, options = {}) {
+  if (!userId) {
+    return {
+      acquired: false,
+      lockPath: `${filePath}.lock`,
+      owner: null,
+      release: () => {},
+    };
+  }
+
+  const lockPath = `${filePath}.lock`;
+
+  // Check if another user holds the lock
+  if (existsSync(lockPath)) {
+    const lockData = readLockFile(lockPath);
+
+    if (lockData && lockData.userId && lockData.userId !== userId) {
+      // Check if the lock is stale
+      if (!isLockStale(lockPath, options)) {
+        return {
+          acquired: false,
+          lockPath,
+          owner: lockData.userId,
+          release: () => {},
+        };
+      }
+      // Stale lock — remove and continue
+      try { unlinkSync(lockPath); } catch { /* ignore */ }
+    }
+  }
+
+  // Use standard lock acquisition
+  const lock = acquireLock(filePath, options);
+
+  if (lock.acquired) {
+    // Overwrite lock file with user info
+    const dir = dirname(lockPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    const lockData = {
+      pid: process.pid,
+      timestamp: Date.now(),
+      userId,
+      hostname: typeof globalThis !== 'undefined' ? (globalThis.process?.env?.HOSTNAME || 'localhost') : 'localhost',
+    };
+    writeFileSync(lockPath, JSON.stringify(lockData), 'utf-8');
+  }
+
+  return {
+    acquired: lock.acquired,
+    lockPath: lock.lockPath,
+    owner: userId,
+    release: lock.release,
+  };
+}