@the-open-engine/zeroshot 5.4.0

package/src/lib/gc.js

@@ -0,0 +1,232 @@
+/**
+ * Garbage collection for orphaned zeroshot worktrees and database files.
+ *
+ * Standalone module with ZERO dependencies on Orchestrator or IsolationManager.
+ * All operations are synchronous so it can be called from any context
+ * (CLI, createWorktree pre-flight, etc.) without async concerns.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DEFAULT_STORAGE_DIR = path.join(os.homedir(), '.zeroshot');
+
+/** Cluster ID pattern: adjective-noun-number (e.g., "flying-jungle-51") */
+const CLUSTER_ID_PATTERN = /^[a-z]+-[a-z]+-\d+$/;
+
+function isClusterDir(entry) {
+  return entry.isDirectory() && CLUSTER_ID_PATTERN.test(entry.name);
+}
+
+function resolveActiveClusterIdFromEnv() {
+  const clusterId = process.env.ZEROSHOT_CLUSTER_ID;
+  if (typeof clusterId !== 'string' || clusterId.trim().length === 0) {
+    return null;
+  }
+  const normalized = clusterId.trim();
+  return CLUSTER_ID_PATTERN.test(normalized) ? normalized : null;
+}
+
+/**
+ * Read known cluster IDs from clusters.json (synchronous, no locking).
+ * @param {string} storageDir
+ * @returns {Set<string>}
+ */
+function readKnownClusterIds(storageDir) {
+  const ids = new Set();
+  const clustersFile = path.join(storageDir, 'clusters.json');
+  try {
+    if (!fs.existsSync(clustersFile)) return ids;
+    const raw = JSON.parse(fs.readFileSync(clustersFile, 'utf8'));
+    for (const id of Object.keys(raw)) ids.add(id);
+  } catch {
+    // Corrupt/missing — treat as empty (safe: nothing deleted incorrectly)
+  }
+  return ids;
+}
+
+function resolveStorageAndKnownIds(storageDirOrOptions = DEFAULT_STORAGE_DIR) {
+  const options =
+    typeof storageDirOrOptions === 'string'
+      ? { storageDir: storageDirOrOptions }
+      : storageDirOrOptions || {};
+  const storageDir = options.storageDir || DEFAULT_STORAGE_DIR;
+  const knownIds = readKnownClusterIds(storageDir);
+  const activeClusterId = resolveActiveClusterIdFromEnv();
+  if (activeClusterId) {
+    knownIds.add(activeClusterId);
+  }
+  if (options.extraKnownIds) {
+    for (const id of options.extraKnownIds) knownIds.add(id);
+  }
+  return { storageDir, knownIds };
+}
+
+/**
+ * Count orphaned worktree directories (for error messages).
+ * @param {string|{storageDir?: string, extraKnownIds?: Set<string>}} [storageDirOrOptions]
+ */
+function countOrphanedWorktrees(storageDirOrOptions = DEFAULT_STORAGE_DIR) {
+  const { storageDir, knownIds } = resolveStorageAndKnownIds(storageDirOrOptions);
+  const worktreeDir = path.join(storageDir, 'worktrees');
+  if (!fs.existsSync(worktreeDir)) return 0;
+  try {
+    return fs
+      .readdirSync(worktreeDir, { withFileTypes: true })
+      .filter((e) => isClusterDir(e) && !knownIds.has(e.name)).length;
+  } catch {
+    return 0;
+  }
+}
+
+/** Try to remove a single file. Returns error string or null. */
+function tryUnlink(filePath) {
+  try {
+    fs.unlinkSync(filePath);
+    return null;
+  } catch (err) {
+    return err.message;
+  }
+}
+
+/** Try to remove a directory tree. Returns error string or null. */
+function tryRmdir(dirPath) {
+  try {
+    fs.rmSync(dirPath, { recursive: true, force: true });
+    return null;
+  } catch (err) {
+    return err.message;
+  }
+}
+
+/** Find repo root from a worktree's .git file (gitdir pointer). */
+function findRepoRootFromWorktree(worktreeDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(worktreeDir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dotGit = path.join(worktreeDir, entry.name, '.git');
+    try {
+      const content = fs.readFileSync(dotGit, 'utf8').trim();
+      const match = content.match(/^gitdir:\s*(.+)/);
+      if (!match) continue;
+      // gitdir: /repo/.git/worktrees/<name> → resolve to /repo
+      const repoRoot = path.resolve(match[1].trim(), '..', '..', '..');
+      if (fs.existsSync(path.join(repoRoot, '.git'))) return repoRoot;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/** Best-effort git worktree prune. */
+function pruneGitWorktrees(worktreeDir) {
+  const repoRoot = findRepoRootFromWorktree(worktreeDir);
+  if (!repoRoot) return;
+  try {
+    require('child_process').execSync('git worktree prune', {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: 'pipe',
+      timeout: 10000,
+    });
+  } catch {
+    // Best effort
+  }
+}
+
+/**
+ * Garbage-collect orphaned worktree directories and database files.
+ *
+ * @param {object} [options]
+ * @param {string} [options.storageDir]
+ * @param {Set<string>} [options.extraKnownIds]
+ * @param {boolean} [options.dryRun=false]
+ * @param {boolean} [options.removeDbFiles] - Defaults to false when ZEROSHOT_CLUSTER_ID is set, else true
+ * @returns {{ orphanedWorktrees: string[], orphanedDbs: string[], errors: string[] }}
+ */
+function gcOrphanedWorktrees(options = {}) {
+  const storageDir = options.storageDir || DEFAULT_STORAGE_DIR;
+  const dryRun = options.dryRun || false;
+  const activeClusterId = resolveActiveClusterIdFromEnv();
+  const removeDbFiles =
+    typeof options.removeDbFiles === 'boolean' ? options.removeDbFiles : activeClusterId === null;
+  const worktreeDir = path.join(storageDir, 'worktrees');
+  const result = { orphanedWorktrees: [], orphanedDbs: [], errors: [] };
+
+  const { knownIds } = resolveStorageAndKnownIds({
+    storageDir,
+    extraKnownIds: options.extraKnownIds,
+  });
+
+  collectOrphanedWorktrees(worktreeDir, knownIds, dryRun, result);
+  if (removeDbFiles) {
+    collectOrphanedDbFiles(storageDir, knownIds, dryRun, result);
+  }
+
+  if (!dryRun && result.orphanedWorktrees.length > 0) {
+    pruneGitWorktrees(worktreeDir);
+  }
+
+  return result;
+}
+
+function collectOrphanedWorktrees(worktreeDir, knownIds, dryRun, result) {
+  if (!fs.existsSync(worktreeDir)) return;
+  let entries;
+  try {
+    entries = fs.readdirSync(worktreeDir, { withFileTypes: true });
+  } catch (err) {
+    result.errors.push(`Failed to read worktree dir: ${err.message}`);
+    return;
+  }
+  for (const entry of entries) {
+    if (!isClusterDir(entry) || knownIds.has(entry.name)) continue;
+    result.orphanedWorktrees.push(entry.name);
+    if (dryRun) continue;
+    const err = tryRmdir(path.join(worktreeDir, entry.name));
+    if (err) result.errors.push(`Failed to remove worktree ${entry.name}: ${err}`);
+  }
+}
+
+function collectOrphanedDbFiles(storageDir, knownIds, dryRun, result) {
+  let entries;
+  try {
+    entries = fs.readdirSync(storageDir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const match = entry.match(/^(.+)\.(db|db-wal|db-shm)$/);
+    if (!match || knownIds.has(match[1])) continue;
+    result.orphanedDbs.push(entry);
+    if (dryRun) continue;
+    const err = tryUnlink(path.join(storageDir, entry));
+    if (err) result.errors.push(`Failed to remove db file ${entry}: ${err}`);
+  }
+}
+
+/**
+ * Get disk space info for a path.
+ * @param {string} dirPath
+ * @returns {{ available: number, total: number, usagePercent: number } | null}
+ */
+function getDiskSpace(dirPath) {
+  try {
+    const stats = fs.statfsSync(dirPath);
+    const available = stats.bavail * stats.bsize;
+    const total = stats.blocks * stats.bsize;
+    const usagePercent = total > 0 ? ((total - available) / total) * 100 : 0;
+    return { available, total, usagePercent };
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { gcOrphanedWorktrees, countOrphanedWorktrees, getDiskSpace, CLUSTER_ID_PATTERN };

package/src/lib/safe-exec.js

@@ -0,0 +1,88 @@
+/**
+ * Safe subprocess execution with mandatory timeouts.
+ *
+ * NEVER use child_process.exec() or execSync() directly.
+ * These wrappers enforce timeouts to prevent infinite hangs.
+ */
+
+const { exec: nodeExec, execSync: nodeExecSync } = require('child_process');
+
+/** Default timeout: 30 seconds */
+const DEFAULT_TIMEOUT_MS = 30000;
+
+/**
+ * Execute command with mandatory timeout.
+ * Supports both Promise and callback styles for gradual migration.
+ *
+ * @param {string} command - Command to execute
+ * @param {object} [options] - Options (timeout uses default if not specified)
+ * @param {function} [callback] - Optional callback(error, stdout, stderr)
+ * @returns {Promise<{stdout: string, stderr: string}>|void} Promise if no callback, void if callback
+ *
+ * @example
+ * // Promise style (preferred)
+ * const { stdout } = await exec('ls -la', { timeout: 5000 });
+ *
+ * @example
+ * // Callback style (for legacy code migration)
+ * exec('ls -la', { timeout: 5000 }, (error, stdout) => { ... });
+ */
+function exec(command, optionsOrCallback = {}, callbackArg = null) {
+  // Handle overloaded signature: exec(cmd, callback)
+  const callback = typeof optionsOrCallback === 'function' ? optionsOrCallback : callbackArg;
+  const options = typeof optionsOrCallback === 'function' ? {} : optionsOrCallback;
+
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+
+  if (timeout <= 0) {
+    const err = new Error('exec() timeout must be > 0. Infinite waits are forbidden.');
+    if (callback) {
+      callback(err);
+      return;
+    }
+    return Promise.reject(err);
+  }
+
+  // Callback style
+  if (callback) {
+    nodeExec(command, { ...options, timeout }, (error, stdout, stderr) => {
+      if (error && error.killed && error.signal === 'SIGTERM') {
+        error.message = `Command timed out after ${timeout}ms: ${command}`;
+      }
+      callback(error, stdout, stderr);
+    });
+    return;
+  }
+
+  // Promise style
+  return new Promise((resolve, reject) => {
+    nodeExec(command, { ...options, timeout }, (error, stdout, stderr) => {
+      if (error) {
+        if (error.killed && error.signal === 'SIGTERM') {
+          error.message = `Command timed out after ${timeout}ms: ${command}`;
+        }
+        reject(error);
+      } else {
+        resolve({ stdout, stderr });
+      }
+    });
+  });
+}
+
+/**
+ * Execute command with mandatory timeout (sync)
+ * @param {string} command - Command to execute
+ * @param {object} [options] - Options (timeout required or uses default)
+ * @returns {string} stdout
+ */
+function execSync(command, options = {}) {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+
+  if (timeout <= 0) {
+    throw new Error('execSync() timeout must be > 0. Infinite waits are forbidden.');
+  }
+
+  return nodeExecSync(command, { ...options, timeout });
+}
+
+module.exports = { exec, execSync, DEFAULT_TIMEOUT_MS };

package/src/logic-engine.js

@@ -0,0 +1,201 @@
+/**
+ * LogicEngine - JavaScript sandbox for agent decision logic
+ *
+ * Provides:
+ * - Isolated VM for executing agent trigger logic
+ * - Timeout enforcement (1 second)
+ * - Ledger API access for queries
+ * - Helper functions for common patterns
+ * - Sandbox security (no fs, network, child_process)
+ */
+
+const vm = require('vm');
+
+function buildLedgerAPI(messageBus, clusterId) {
+  return {
+    query: (criteria) => {
+      return messageBus.query({ ...criteria, cluster_id: clusterId });
+    },
+
+    findLast: (criteria) => {
+      return messageBus.findLast({ ...criteria, cluster_id: clusterId });
+    },
+
+    count: (criteria) => {
+      return messageBus.count({ ...criteria, cluster_id: clusterId });
+    },
+
+    since: (timestamp) => {
+      return messageBus.since({ cluster_id: clusterId, timestamp });
+    },
+  };
+}
+
+function buildHelpers(ledgerAPI) {
+  return {
+    allResponded: (agents, topic, since) => {
+      const responses = ledgerAPI.query({ topic, since });
+      const responders = new Set(responses.map((r) => r.sender));
+      return agents.every((a) => responders.has(a.id || a));
+    },
+
+    hasConsensus: (topic, since) => {
+      const responses = ledgerAPI.query({ topic, since });
+      if (responses.length === 0) return false;
+      return responses.every((r) => r.content?.data?.approved === true);
+    },
+
+    timeSinceLastMessage: (topic) => {
+      const last = ledgerAPI.findLast({ topic });
+      if (!last) return Infinity;
+      return Date.now() - last.timestamp;
+    },
+
+    hasMessagesSince: (topic, since) => {
+      const count = ledgerAPI.count({ topic, since });
+      return count > 0;
+    },
+
+    getConfig: require('./config-router').getConfig,
+  };
+}
+
+function buildClusterAPI(cluster, clusterId) {
+  const getAgents = () => (cluster ? cluster.agents || [] : []);
+
+  return {
+    id: clusterId,
+    getAgents,
+    getAgentsByRole: (role) => getAgents().filter((a) => a.role === role),
+    getAgent: (id) => getAgents().find((a) => a.id === id) || null,
+  };
+}
+
+function buildAgentContext(agent) {
+  return {
+    id: agent.id,
+    role: agent.role,
+    iteration: agent.iteration || 0,
+    requiredQualityGates: Array.isArray(agent.requiredQualityGates)
+      ? agent.requiredQualityGates
+      : [],
+  };
+}
+
+function getSafeBuiltins() {
+  return { Set, Map, Array, Object, String, Number, Boolean, Math, Date, JSON };
+}
+
+function getQuietConsole() {
+  return {
+    log: () => {},
+    error: () => {},
+    warn: () => {},
+    info: () => {},
+  };
+}
+
+class LogicEngine {
+  constructor(messageBus, cluster) {
+    this.messageBus = messageBus;
+    this.cluster = cluster;
+    this.timeout = 1000; // 1 second
+  }
+
+  /**
+   * Evaluate a trigger logic script
+   * @param {String} script - JavaScript code to evaluate
+   * @param {Object} agent - Agent context
+   * @param {Object} message - Triggering message
+   * @returns {Boolean} Whether agent should wake up
+   */
+  evaluate(script, agent, message) {
+    try {
+      // Build sandbox context
+      const context = this._buildContext(agent, message);
+
+      // Create isolated context with frozen prototypes
+      // This prevents prototype pollution attacks
+      const isolatedContext = {};
+
+      // Freeze Object, Array, Function prototypes in the sandbox
+      isolatedContext.Object = Object.freeze({ ...Object });
+      isolatedContext.Array = Array;
+      isolatedContext.Function = Function;
+
+      // Copy safe context properties
+      Object.assign(isolatedContext, context);
+
+      // Wrap script to prevent prototype access
+      const wrappedScript = `(function() {
+        'use strict';
+        // Prevent prototype pollution
+        const frozenObject = Object;
+        const frozenArray = Array;
+        Object.freeze(frozenObject.prototype);
+        Object.freeze(frozenArray.prototype);
+
+        ${script}
+      })()`;
+
+      // Create and run in context
+      vm.createContext(isolatedContext);
+      const result = vm.runInContext(wrappedScript, isolatedContext, {
+        timeout: this.timeout,
+        displayErrors: true,
+      });
+
+      // Coerce to boolean
+      return Boolean(result);
+    } catch (error) {
+      console.error(`Logic evaluation error for agent ${agent.id}:`, error.message);
+      return false; // Default to false on error
+    }
+  }
+
+  /**
+   * Build sandbox context with APIs and helpers
+   * @private
+   */
+  _buildContext(agent, message) {
+    const clusterId = agent.cluster_id;
+    const ledgerAPI = buildLedgerAPI(this.messageBus, clusterId);
+
+    // Build context
+    return {
+      agent: buildAgentContext(agent),
+      message: message || null,
+      ledger: ledgerAPI,
+      cluster: buildClusterAPI(this.cluster, clusterId),
+      helpers: buildHelpers(ledgerAPI),
+      ...getSafeBuiltins(),
+      console: getQuietConsole(),
+    };
+  }
+
+  /**
+   * Validate script syntax without executing
+   * @param {String} script - JavaScript code
+   * @returns {Object} { valid: Boolean, error: String }
+   */
+  validateScript(script) {
+    try {
+      // Wrap in function like evaluate() does
+      const wrappedScript = `(function() { ${script} })()`;
+      new vm.Script(wrappedScript);
+      return { valid: true, error: null };
+    } catch (error) {
+      return { valid: false, error: error.message };
+    }
+  }
+
+  /**
+   * Set timeout for script execution
+   * @param {Number} ms - Timeout in milliseconds
+   */
+  setTimeout(ms) {
+    this.timeout = ms;
+  }
+}
+
+module.exports = LogicEngine;

package/src/message-buffer.js

@@ -0,0 +1,81 @@
+/**
+ * Message buffering helper
+ *
+ * Ensures trigger-matching messages are never dropped just because an agent/subcluster is busy.
+ * Dropped workflow signals (e.g. VALIDATION_RESULT) can wedge clusters in "running" state.
+ */
+
+function bufferMessage(target, message, options = {}) {
+  const maxBuffered = options.maxBuffered ?? 200;
+
+  if (!target._bufferedMessages) {
+    target._bufferedMessages = [];
+  }
+
+  if (target._bufferedMessages.length >= maxBuffered) {
+    target._bufferedMessages.shift();
+  }
+
+  target._bufferedMessages.push(message);
+}
+
+function scheduleDrain(target, drainFn, options = {}) {
+  if (target._bufferDrainScheduled) {
+    return;
+  }
+
+  target._bufferDrainScheduled = true;
+
+  const label = options.label || 'MessageBuffer';
+  const id = target.id || 'unknown';
+
+  const run = () => {
+    target._bufferDrainScheduled = false;
+    drainFn().catch((error) => {
+      console.error(`\n${'='.repeat(80)}`);
+      console.error(`🔴 FATAL: ${label} drain crashed (${id})`);
+      console.error(`${'='.repeat(80)}`);
+      console.error(`Error: ${error.message}`);
+      console.error(`Stack: ${error.stack}`);
+      console.error(`${'='.repeat(80)}\n`);
+      setImmediate(() => {
+        throw error;
+      });
+    });
+  };
+
+  const current = target._currentExecution;
+  if (current && typeof current.finally === 'function') {
+    current.finally(() => setImmediate(run));
+    return;
+  }
+
+  setImmediate(run);
+}
+
+async function drainBufferedMessages(target, handleFn, options = {}) {
+  if (!target.running) {
+    return;
+  }
+
+  const buffer = target._bufferedMessages;
+  if (!buffer || buffer.length === 0) {
+    return;
+  }
+
+  if (target.state !== 'idle') {
+    scheduleDrain(target, () => drainBufferedMessages(target, handleFn, options), options);
+    return;
+  }
+
+  while (target.running && target.state === 'idle' && buffer.length > 0) {
+    const next = buffer.shift();
+    await handleFn(next);
+  }
+}
+
+module.exports = {
+  bufferMessage,
+  scheduleDrain,
+  drainBufferedMessages,
+};