@cnrai/pave 0.3.35 → 0.3.51

package/lib/agent-registry.js

@@ -1,1037 +0,0 @@
-/**
- * Agent Registry - manages agent status files in ~/.pave/agents/
- *
- * Each running pave agent writes its state to ~/.pave/agents/<name>/status.json.
- * The `pave agents` command reads these to list all known agents.
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-/** Directory where agent status files are stored (overridable for testing) */
-let _agentsDir = path.join(os.homedir(), '.pave', 'agents');
-
-/** Get the current agents directory */
-function getAgentsDir() {
-  return _agentsDir;
-}
-
-/** Override agents directory (for testing) */
-function setAgentsDir(dir) {
-  _agentsDir = dir;
-}
-
-/** Reset agents directory to default */
-function resetAgentsDir() {
-  _agentsDir = path.join(os.homedir(), '.pave', 'agents');
-}
-
-/** Valid agent states */
-const STATES = {
-  STARTING: 'starting',
-  WORKING: 'working',
-  SLEEPING: 'sleeping',
-  STOPPED: 'stopped',
-  CRASHED: 'crashed',
-  ERROR: 'error',
-};
-
-/**
- * Sanitize agent name for filesystem safety.
- * Lowercase, replace spaces with hyphens, remove special chars.
- * @param {string} name - Raw agent name
- * @returns {string} Sanitized name
- */
-function sanitizeName(name) {
-  if (!name) return 'default';
-  return name
-    .toLowerCase()
-    .replace(/\s+/g, '-')
-    .replace(/[^a-z0-9_-]/g, '')
-    .replace(/-+/g, '-')
-    .replace(/^-|-$/g, '')
-    || 'default';
-}
-
-/**
- * Get the directory for a specific agent.
- * @param {string} name - Agent name (will be sanitized)
- * @returns {string} Path to agent directory
- */
-function getAgentDir(name) {
-  return path.join(getAgentsDir(), sanitizeName(name));
-}
-
-/**
- * Get the status file path for a specific agent.
- * @param {string} name - Agent name (will be sanitized)
- * @returns {string} Path to status.json
- */
-function getStatusPath(name) {
-  return path.join(getAgentDir(name), 'status.json');
-}
-
-/**
- * Check if a process with the given PID is alive.
- * @param {number} pid - Process ID
- * @returns {boolean} true if the process is running
- */
-function isProcessAlive(pid) {
-  // Guard: pid must be a positive finite integer (0 and negatives have special POSIX semantics)
-  if (!Number.isFinite(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (e) {
-    // EPERM means the process exists but we don't have permission to signal it
-    if (e.code === 'EPERM') return true;
-    // ESRCH means no such process
-    return false;
-  }
-}
-
-/**
- * Write agent status to disk.
- * Uses write-to-temp + rename for atomicity.
- * Creates directories with 0o700 and files with 0o600 to restrict access.
- * @param {string} name - Agent name
- * @param {object} status - Status object to write. All timestamps
- *   (startedAt, updatedAt) are in milliseconds since epoch (Date.now()).
- *   Note: the issue #198 schema example shows 10-digit Unix seconds, but
- *   this implementation uses 13-digit ms to match standard JS conventions.
- */
-function writeStatus(name, status) {
-  if (!status || typeof status !== 'object') {
-    console.error('[agent-registry] Invalid status object; skipping write');
-    return;
-  }
-
-  const dir = getAgentDir(name);
-  const statusPath = path.join(dir, 'status.json');
-  const tmpPath = statusPath + '.tmp';
-
-  try {
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  } catch (e) {
-    // Directory may already exist
-  }
-
-  status.updatedAt = Date.now();
-  const content = JSON.stringify(status, null, 2);
-
-  try {
-    fs.writeFileSync(tmpPath, content, { mode: 0o600 });
-    try {
-      fs.renameSync(tmpPath, statusPath);
-    } catch (renameErr) {
-      // On Windows, rename can fail with EEXIST/EPERM when destination exists.
-      // Only attempt the unlink+retry for those specific error codes.
-      if (renameErr.code === 'EEXIST' || renameErr.code === 'EPERM') {
-        try { fs.unlinkSync(statusPath); } catch (e3) {}
-        fs.renameSync(tmpPath, statusPath);
-      } else {
-        throw renameErr;
-      }
-    }
-  } catch (e) {
-    // Best-effort cleanup
-    try { fs.unlinkSync(tmpPath); } catch (e2) {}
-    // Don't throw - status write failure should not crash the agent
-    console.error('[agent-registry] Failed to write status: ' + e.message);
-  }
-}
-
-/**
- * Read agent status from disk.
- * @param {string} name - Agent name
- * @returns {object|null} Status object or null if not found
- */
-function readStatus(name) {
-  const statusPath = getStatusPath(name);
-  try {
-    const content = fs.readFileSync(statusPath, 'utf8');
-    return JSON.parse(content);
-  } catch (e) {
-    return null;
-  }
-}
-
-/**
- * Atomically claim an agent name. Creates a lock file with 'wx' (exclusive
- * create) so two concurrent starts with the same name will race on the
- * kernel's O_EXCL, and only one will succeed.
- *
- * The lock file contains the PID of the claiming process.
- *
- * @param {string} name - Agent name
- * @returns {{claimed: boolean, existingPid: number|null}} Result
- */
-function claimAgent(name) {
-  const dir = getAgentDir(name);
-  const lockPath = path.join(dir, 'lock');
-
-  try {
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  } catch (e) {
-    // Directory may already exist
-  }
-
-  // Try to read existing lock to check for stale/alive process
-  try {
-    const existingLock = fs.readFileSync(lockPath, 'utf8');
-    const existingPid = parseInt(existingLock.trim(), 10);
-    if (existingPid && isProcessAlive(existingPid)) {
-      return { claimed: false, existingPid };
-    }
-    // Stale lock (process dead) - remove and retry
-    try { fs.unlinkSync(lockPath); } catch (e) {}
-  } catch (e) {
-    // No lock file exists - proceed to claim
-  }
-
-  try {
-    fs.writeFileSync(lockPath, String(process.pid), { flag: 'wx', mode: 0o600 });
-    return { claimed: true, existingPid: null };
-  } catch (e) {
-    if (e.code === 'EEXIST') {
-      // Another process claimed between our read and write - re-read to get PID
-      try {
-        const pid = parseInt(fs.readFileSync(lockPath, 'utf8').trim(), 10);
-        return { claimed: false, existingPid: pid || null };
-      } catch (e2) {
-        return { claimed: false, existingPid: null };
-      }
-    }
-    console.error('[agent-registry] Failed to claim agent: ' + e.message);
-    return { claimed: false, existingPid: null };
-  }
-}
-
-/**
- * Release an agent lock (remove the lock file).
- * @param {string} name - Agent name
- */
-function releaseAgent(name) {
-  const lockPath = path.join(getAgentDir(name), 'lock');
-  try { fs.unlinkSync(lockPath); } catch (e) {}
-}
-
-/**
- * Check if an agent with the given name is already running.
- * @param {string} name - Agent name
- * @returns {{alive: boolean, status: object|null}} Result with liveness and status
- */
-function isAgentAlive(name) {
-  const status = readStatus(name);
-  if (!status) return { alive: false, status: null };
-  if (status.state === STATES.STOPPED) return { alive: false, status };
-  if (!status.pid) return { alive: false, status };
-  return { alive: isProcessAlive(status.pid), status };
-}
-
-/**
- * Get the server URL for a running agent.
- * Reads from status.json's serverUrl field. Returns null if agent is
- * not running or serverUrl is not available.
- * @param {string} name - Agent name
- * @returns {string|null} Server URL (e.g., 'http://localhost:1234') or null
- */
-function getAgentServerUrl(name) {
-  const { alive, status } = isAgentAlive(name);
-  if (!alive || !status || !status.serverUrl) return null;
-  return status.serverUrl;
-}
-
-/**
- * List all registered agents with their status and liveness.
- * @returns {Array<{name: string, status: object, alive: boolean}>}
- */
-function listAgents() {
-  const results = [];
-  let entries;
-
-  try {
-    entries = fs.readdirSync(getAgentsDir(), { withFileTypes: true });
-  } catch (e) {
-    // No agents directory yet
-    return results;
-  }
-
-  /** Strict safe pattern for agent directory names */
-  const SAFE_NAME_RE = /^[a-z0-9_-]+$/;
-
-  for (let i = 0; i < entries.length; i++) {
-    if (!entries[i].isDirectory()) continue;
-
-    const name = entries[i].name;
-    // Skip directories that don't match sanitized name pattern
-    // to prevent terminal escape injection from crafted directory names
-    if (!SAFE_NAME_RE.test(name)) continue;
-
-    const status = readStatus(name);
-    if (!status) continue;
-
-    let alive = false;
-    if (status.state !== STATES.STOPPED && status.pid) {
-      alive = isProcessAlive(status.pid);
-    }
-
-    // Detect crashed agents (skip STOPPED and ERROR since those are terminal states)
-    let displayState = status.state;
-    if (!alive && status.state !== STATES.STOPPED && status.state !== STATES.ERROR) {
-      displayState = STATES.CRASHED;
-    }
-
-    results.push({
-      name,
-      status: { ...status, state: displayState },
-      alive,
-    });
-  }
-
-  // Sort by most recently updated
-  results.sort((a, b) => {
-    return (b.status.updatedAt || 0) - (a.status.updatedAt || 0);
-  });
-
-  return results;
-}
-
-/**
- * Format uptime from a start timestamp.
- * @param {number} startedAt - Start timestamp in ms
- * @returns {string} Human-readable uptime (e.g., "2h 15m")
- */
-function formatUptime(startedAt) {
-  if (!startedAt) return '—';
-  const elapsed = Date.now() - startedAt;
-  if (elapsed < 0) return '—';
-
-  const seconds = Math.floor(elapsed / 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 ' + (hours % 24) + 'h';
-  if (hours > 0) return hours + 'h ' + (minutes % 60) + 'm';
-  if (minutes > 0) return minutes + 'm';
-  return seconds + 's';
-}
-
-/**
- * Resolve an agent name by prefix matching.
- * If the exact name matches, return it. Otherwise, try prefix matching
- * against all registered agents. Returns the match only if exactly one
- * agent matches the prefix.
- *
- * @param {string} nameOrPrefix - Agent name or prefix
- * @returns {{name: string|null, error: string|null, candidates: string[]}}
- */
-function resolveAgentName(nameOrPrefix) {
-  if (!nameOrPrefix) {
-    return { name: null, error: 'No agent name provided', candidates: [] };
-  }
-
-  const sanitized = sanitizeName(nameOrPrefix);
-
-  // Prevent garbage input (e.g. only spaces or punctuation) from silently
-  // resolving to the "default" agent via sanitization. Only allow "default"
-  // when the user explicitly requested it.
-  if (
-    sanitized === 'default' &&
-    typeof nameOrPrefix === 'string' &&
-    nameOrPrefix.trim().toLowerCase() !== 'default'
-  ) {
-    return { name: null, error: 'Invalid agent name provided', candidates: [] };
-  }
-
-  /** Strict safe pattern (same as listAgents) to prevent terminal injection */
-  const SAFE_NAME_RE = /^[a-z0-9_-]+$/;
-
-  // Try exact match first
-  const status = readStatus(sanitized);
-  if (status) {
-    return { name: sanitized, error: null, candidates: [sanitized] };
-  }
-
-  // Try prefix matching
-  let entries;
-  try {
-    entries = fs.readdirSync(getAgentsDir(), { withFileTypes: true });
-  } catch (e) {
-    // Distinguish "no agents directory" from other I/O/permission errors
-    if (e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')) {
-      return { name: null, error: 'No agents registered', candidates: [] };
-    }
-    const codeInfo = e && e.code ? ' (code: ' + e.code + ')' : '';
-    const msgInfo = e && e.message ? ': ' + e.message : '';
-    return { name: null, error: 'Failed to read agents directory' + codeInfo + msgInfo, candidates: [] };
-  }
-
-  const matches = [];
-  for (let i = 0; i < entries.length; i++) {
-    if (!entries[i].isDirectory()) continue;
-    const dirName = entries[i].name;
-    // Skip directories that don't match safe name pattern (terminal injection prevention)
-    if (!SAFE_NAME_RE.test(dirName)) continue;
-    if (dirName.indexOf(sanitized) === 0) {
-      // Only include if it has a status file
-      if (readStatus(dirName)) {
-        matches.push(dirName);
-      }
-    }
-  }
-
-  if (matches.length === 1) {
-    return { name: matches[0], error: null, candidates: matches };
-  } if (matches.length === 0) {
-    return { name: null, error: 'No agent found matching "' + sanitized + '"', candidates: [] };
-  }
-  return {
-    name: null,
-    error: 'Ambiguous agent name "' + sanitized + '". Matches: ' + matches.join(', '),
-    candidates: matches,
-  };
-}
-
-/**
- * Stop a running agent by sending SIGTERM, with SIGKILL fallback.
- *
- * @param {string} name - Resolved agent name (already sanitized)
- * @param {object} [opts] - Options
- * @param {number} [opts.timeout] - Milliseconds to wait before SIGKILL (default: 5000)
- * @returns {Promise<{success: boolean, error: string|null, killed: boolean}>}
- */
-function stopAgent(name, opts) {
-  const timeout = (opts && opts.timeout) || 5000;
-  const status = readStatus(name);
-
-  if (!status) {
-    return Promise.resolve({ success: false, error: 'Agent "' + name + '" not found', killed: false });
-  }
-
-  if (status.state === STATES.STOPPED) {
-    return Promise.resolve({ success: false, error: 'Agent "' + name + '" is already stopped', killed: false });
-  }
-
-  if (!status.pid) {
-    return Promise.resolve({ success: false, error: 'Agent "' + name + '" has no PID recorded', killed: false });
-  }
-
-  if (!isProcessAlive(status.pid)) {
-    // Process is dead but status wasn't updated.
-    // Re-read to guard against a restart race: if a new agent has already
-    // claimed the name with a different PID, leave its status alone.
-    const latestStatus = readStatus(name) || status;
-    const pidStillOurs = !latestStatus.pid || latestStatus.pid === status.pid;
-    if (pidStillOurs) {
-      writeStatus(name, { ...latestStatus, state: STATES.STOPPED, currentTask: 'stopped (stale)' });
-      // Don't call releaseAgent() here - a new agent may have already claimed
-      // the lock file (with its own PID) before writing status.json.
-      // claimAgent() handles stale locks on its own, so this is safe.
-    }
-    return Promise.resolve({ success: true, error: null, killed: false });
-  }
-
-  // Send SIGTERM
-  try {
-    process.kill(status.pid, 'SIGTERM');
-  } catch (e) {
-    // If the process exited between the liveness check and this kill call,
-    // Node will throw ESRCH. Treat as successful stop.
-    if (e && e.code === 'ESRCH') {
-      // Re-read status to guard against a restart race (same as stale path).
-      const latestStatus = readStatus(name) || status;
-      const pidStillOurs = !latestStatus.pid || latestStatus.pid === status.pid;
-      if (pidStillOurs) {
-        writeStatus(name, { ...latestStatus, state: STATES.STOPPED, currentTask: 'stopped (exited before SIGTERM)' });
-        // Don't releaseAgent() - a new agent may own the lock file already.
-        // claimAgent() handles stale locks on its own.
-      }
-      return Promise.resolve({ success: true, error: null, killed: false });
-    }
-    return Promise.resolve({ success: false, error: 'Failed to send SIGTERM: ' + e.message, killed: false });
-  }
-
-  // Wait for clean shutdown, then SIGKILL if needed
-  return new Promise((resolve) => {
-    let elapsed = 0;
-    const interval = 500;
-
-    const timer = setInterval(() => {
-      elapsed += interval;
-
-      // Check if the process has stopped
-      if (!isProcessAlive(status.pid)) {
-        clearInterval(timer);
-        // Re-read status to avoid overwriting state owned by a newly restarted agent.
-        // If a new agent claimed the name (different PID), leave its status alone.
-        const latestStatus = readStatus(name) || status;
-        const pidStillOurs = !latestStatus.pid || latestStatus.pid === status.pid;
-        if (pidStillOurs && (!latestStatus.state || latestStatus.state !== STATES.STOPPED)) {
-          writeStatus(name, { ...latestStatus, state: STATES.STOPPED, currentTask: 'stopped (SIGTERM)' });
-          // Don't releaseAgent() - claimAgent() handles stale locks on its own,
-          // and a new agent may already own the lock file.
-        }
-        resolve({ success: true, error: null, killed: false });
-        return;
-      }
-
-      // Timeout - send SIGKILL
-      if (elapsed >= timeout) {
-        clearInterval(timer);
-        let killedBySigkill = false;
-        try {
-          process.kill(status.pid, 'SIGKILL');
-          killedBySigkill = true;
-        } catch (e) {
-          if (e && e.code === 'ESRCH') {
-            // Process already exited between the last liveness check and
-            // the SIGKILL - it shut down cleanly at the timeout boundary.
-            killedBySigkill = false;
-          } else if (isProcessAlive(status.pid)) {
-            // Signal failed for another reason (EPERM) and process is alive
-            resolve({
-              success: false,
-              error: 'Failed to SIGKILL agent "' + name + '" (pid ' + status.pid + '): ' + (e && e.message ? e.message : 'unknown error'),
-              killed: false,
-            });
-            return;
-          }
-          // else: signal failed but process is dead - treat as clean stop
-        }
-
-        // Helper to finalize a successful stop/kill: re-read status to avoid
-        // overwriting state owned by a newly restarted agent, and only update
-        // status if the PID still matches this agent. Don't release the lock -
-        // claimAgent() handles stale locks on its own, and a new agent may
-        // have already claimed the lock file.
-        function finalizeStop(finalKilledBySigkill) {
-          const latestStatus = readStatus(name) || status;
-          const pidStillOurs = !latestStatus.pid || latestStatus.pid === status.pid;
-          if (pidStillOurs) {
-            const task = finalKilledBySigkill ? 'killed (SIGKILL)' : 'stopped (SIGTERM)';
-            writeStatus(name, { ...latestStatus, state: STATES.STOPPED, currentTask: task });
-          }
-          resolve({ success: true, error: null, killed: finalKilledBySigkill });
-        }
-
-        if (!killedBySigkill) {
-          // Either the process was already dead (ESRCH) or we otherwise treat it
-          // as cleanly stopped at the timeout boundary.
-          finalizeStop(false);
-          return;
-        }
-
-        // We sent SIGKILL, but the process may still be terminating. Poll for a
-        // short period to confirm exit before marking the agent as stopped and
-        // releasing the lock.
-        const sigkillWaitInterval = 100;
-        const sigkillMaxWait = 2000;
-        let sigkillWaited = 0;
-        const sigkillTimer = setInterval(() => {
-          if (!isProcessAlive(status.pid)) {
-            clearInterval(sigkillTimer);
-            finalizeStop(true);
-            return;
-          }
-          sigkillWaited += sigkillWaitInterval;
-          if (sigkillWaited >= sigkillMaxWait) {
-            clearInterval(sigkillTimer);
-            // Process did not exit within the grace period after SIGKILL.
-            // Do not mark it as stopped or release the lock; report failure.
-            resolve({
-              success: false,
-              error: 'Agent "' + name + '" (pid ' + status.pid + ') did not exit after SIGKILL',
-              killed: true,
-            });
-          }
-        }, sigkillWaitInterval);
-      }
-    }, interval);
-  });
-}
-
-/**
- * Get the log file path for an agent.
- * Resolves from the agent's status.json (cwd + config).
- *
- * @param {string} name - Resolved agent name
- * @returns {{path: string|null, error: string|null}}
- */
-function getAgentLogFile(name) {
-  const status = readStatus(name);
-  if (!status) {
-    return { path: null, error: 'Agent "' + name + '" not found' };
-  }
-
-  const cwd = status.cwd;
-  const config = status.config || '.pave';
-
-  if (!cwd) {
-    return { path: null, error: 'Agent "' + name + '" has no working directory recorded' };
-  }
-
-  const logFile = path.join(cwd, config, 'pave.log');
-  return { path: logFile, error: null };
-}
-
-// ─── Inbox Protocol (Phase 3) ──────────────────────────────────────────────
-
-/**
- * Get the inbox directory path for a specific agent.
- * @param {string} name - Agent name (will be sanitized)
- * @returns {string} Path to inbox directory
- */
-function getInboxDir(name) {
-  return path.join(getAgentDir(name), 'inbox');
-}
-
-/**
- * Determine the next sequence number for an inbox message.
- * Scans existing inbox files and returns max + 1.
- * @param {string} inboxDir - Path to inbox directory
- * @returns {number} Next sequence number (starts at 1)
- */
-function _nextSequence(inboxDir) {
-  let maxSeq = 0;
-  try {
-    const files = fs.readdirSync(inboxDir);
-    for (let i = 0; i < files.length; i++) {
-      const match = files[i].match(/^(\d+)-/);
-      if (match) {
-        const seq = parseInt(match[1], 10);
-        if (seq > maxSeq) maxSeq = seq;
-      }
-    }
-  } catch (e) {
-    // Directory may not exist yet
-  }
-  return maxSeq + 1;
-}
-
-/**
- * Write a message to an agent's inbox.
- * Uses write-to-temp + fs.renameSync for atomicity.
- * Filenames include PID + random suffix for concurrent-writer safety.
- * Timestamps are in milliseconds (Date.now()), consistent with writeStatus().
- *
- * @param {string} name - Agent name (will be sanitized)
- * @param {string} messageText - Message content
- * @param {object} [opts] - Options
- * @param {string} [opts.from] - Sender identifier (default: 'tui')
- * @param {string} [opts.priority] - 'normal' or 'high' (default: 'normal')
- * @returns {{success: boolean, error: string|null, file: string|null}}
- */
-function writeInboxMessage(name, messageText, opts) {
-  if (!messageText || typeof messageText !== 'string') {
-    return { success: false, error: 'Message must be a non-empty string', file: null };
-  }
-
-  const sanitized = sanitizeName(name);
-  const inboxDir = getInboxDir(sanitized);
-  const from = (opts && opts.from) || 'tui';
-  const priority = (opts && opts.priority) || 'normal';
-
-  // Validate priority
-  if (priority !== 'normal' && priority !== 'high') {
-    return { success: false, error: 'Invalid priority: must be "normal" or "high"', file: null };
-  }
-
-  // Ensure inbox directory exists
-  try {
-    fs.mkdirSync(inboxDir, { recursive: true, mode: 0o700 });
-  } catch (e) {
-    if (e && e.code !== 'EEXIST') {
-      return { success: false, error: 'Failed to create inbox directory: ' + e.message, file: null };
-    }
-  }
-
-  const seq = _nextSequence(inboxDir);
-  const timestamp = Date.now();
-  // Zero-pad sequence to 4 digits for proper FIFO ordering
-  const seqStr = String(seq).padStart(4, '0');
-  // Add PID + random suffix to avoid filename collisions across concurrent writers
-  const uniqueSuffix = process.pid + '-' + Math.random().toString(16).slice(2, 10);
-  const filename = seqStr + '-' + timestamp + '-' + uniqueSuffix + '.json';
-  const filePath = path.join(inboxDir, filename);
-  // Use unique temp path to avoid collisions between concurrent writers
-  const tmpPath = filePath + '.' + process.pid + '-' + Math.random().toString(16).slice(2, 8) + '.tmp';
-
-  const envelope = {
-    message: messageText,
-    from,
-    priority,
-    timestamp, // Milliseconds (consistent with writeStatus)
-  };
-
-  try {
-    fs.writeFileSync(tmpPath, JSON.stringify(envelope, null, 2), { mode: 0o600 });
-    try {
-      fs.renameSync(tmpPath, filePath);
-    } catch (renameErr) {
-      // On destination collision (extremely unlikely with unique suffix), retry with new name
-      if (renameErr.code === 'EEXIST' || renameErr.code === 'EPERM') {
-        const retrySuffix = process.pid + '-' + Math.random().toString(16).slice(2, 10);
-        const retryFilename = seqStr + '-' + timestamp + '-' + retrySuffix + '.json';
-        const retryPath = path.join(inboxDir, retryFilename);
-        fs.renameSync(tmpPath, retryPath);
-        return { success: true, error: null, file: retryFilename };
-      }
-      throw renameErr;
-    }
-    return { success: true, error: null, file: filename };
-  } catch (e) {
-    try { fs.unlinkSync(tmpPath); } catch (e2) {}
-    return { success: false, error: 'Failed to write inbox message: ' + e.message, file: null };
-  }
-}
-
-/**
- * Check if an agent's inbox has pending messages.
- * @param {string} name - Agent name (will be sanitized)
- * @returns {boolean} true if there are messages in the inbox
- */
-function inboxHasMessages(name) {
-  const inboxDir = getInboxDir(sanitizeName(name));
-  try {
-    const files = fs.readdirSync(inboxDir);
-    for (let i = 0; i < files.length; i++) {
-      if (files[i].endsWith('.json') && !files[i].endsWith('.tmp')) {
-        return true;
-      }
-    }
-  } catch (e) {
-    // No inbox directory
-  }
-  return false;
-}
-
-/**
- * Drain messages from an agent's inbox.
- * Reads up to `limit` messages in FIFO order (sorted by filename),
- * with high-priority messages sorted before normal within the batch.
- *
- * By default, inbox files are deleted after reading. When `opts.deleteFiles`
- * is false, files are left on disk and the caller must call
- * `deleteInboxFiles(result.files)` after confirming delivery. This enables
- * at-least-once delivery semantics: if the downstream send fails, messages
- * remain on disk and are retried on the next iteration. (#231)
- *
- * Malformed/unreadable files are always deleted immediately regardless of
- * the `deleteFiles` option, since they can never be delivered.
- *
- * @param {string} name - Agent name (will be sanitized)
- * @param {object} [opts] - Options
- * @param {number} [opts.limit] - Maximum messages to drain (default: 5)
- * @param {boolean} [opts.deleteFiles] - Delete files after read (default: true)
- * @returns {{messages: Array<object>, remaining: number, files: string[]}}
- *   - messages: parsed message envelopes (sorted by priority then FIFO)
- *   - remaining: count of unread messages still in inbox
- *   - files: absolute paths of successfully read files (for deferred deletion)
- */
-function drainInbox(name, opts) {
-  const limit = (opts && typeof opts.limit === 'number' && opts.limit > 0) ? opts.limit : 5;
-  const inboxDir = getInboxDir(sanitizeName(name));
-
-  let files;
-  try {
-    files = fs.readdirSync(inboxDir);
-  } catch (e) {
-    return { messages: [], remaining: 0, files: [] };
-  }
-
-  // Filter to valid message files and sort by parsed sequence number (then timestamp as tiebreaker)
-  // Numeric sort avoids issues with lexical sort when sequence exceeds zero-pad width
-  const messageFiles = files
-    .filter((f) => { return f.endsWith('.json') && !f.endsWith('.tmp'); })
-    .sort((a, b) => {
-      const seqA = parseInt(a.split('-')[0], 10) || 0;
-      const seqB = parseInt(b.split('-')[0], 10) || 0;
-      if (seqA !== seqB) return seqA - seqB;
-      // Tiebreaker: parse timestamp (second segment)
-      const tsA = parseInt(a.split('-')[1], 10) || 0;
-      const tsB = parseInt(b.split('-')[1], 10) || 0;
-      return tsA - tsB;
-    });
-
-  const messages = [];
-  const successFiles = []; // Files with valid messages (for deferred deletion)
-  const malformedFiles = []; // Malformed/unreadable files (always deleted immediately)
-
-  // Read up to limit messages
-  const readCount = Math.min(messageFiles.length, limit);
-  for (let i = 0; i < readCount; i++) {
-    const filePath = path.join(inboxDir, messageFiles[i]);
-    try {
-      const content = fs.readFileSync(filePath, 'utf8');
-      const envelope = JSON.parse(content);
-      // Validate required fields
-      if (envelope && typeof envelope.message === 'string') {
-        messages.push({
-          message: envelope.message,
-          from: envelope.from || 'unknown',
-          priority: envelope.priority || 'normal',
-          timestamp: envelope.timestamp || 0,
-          file: messageFiles[i],
-        });
-        successFiles.push(filePath);
-      } else {
-        // Malformed file - always delete immediately (can never be delivered)
-        console.error('[agent-registry] Malformed inbox file, deleting: ' + messageFiles[i]);
-        malformedFiles.push(filePath);
-      }
-    } catch (e) {
-      // Malformed/unreadable file - always delete immediately
-      console.error('[agent-registry] Error reading inbox file ' + messageFiles[i] + ': ' + e.message);
-      malformedFiles.push(filePath);
-    }
-  }
-
-  // Always delete malformed files immediately (they can never be delivered)
-  for (let i = 0; i < malformedFiles.length; i++) {
-    try { fs.unlinkSync(malformedFiles[i]); } catch (e) {}
-  }
-
-  // Sort within batch: high-priority first, then by original FIFO order (numeric)
-  messages.sort((a, b) => {
-    if (a.priority === 'high' && b.priority !== 'high') return -1;
-    if (a.priority !== 'high' && b.priority === 'high') return 1;
-    // Preserve FIFO order within same priority using numeric sequence + timestamp
-    const seqA = parseInt(a.file.split('-')[0], 10) || 0;
-    const seqB = parseInt(b.file.split('-')[0], 10) || 0;
-    if (seqA !== seqB) return seqA - seqB;
-    const tsA = parseInt(a.file.split('-')[1], 10) || 0;
-    const tsB = parseInt(b.file.split('-')[1], 10) || 0;
-    return tsA - tsB;
-  });
-
-  // Delete successfully-read files only if deleteFiles option is true (default: true for backward compat)
-  // When deleteFiles is false, caller is responsible for calling deleteInboxFiles() after
-  // confirming delivery. This prevents message loss if sendMessageAndStream fails. (#231)
-  const shouldDelete = !(opts && opts.deleteFiles === false);
-  if (shouldDelete) {
-    for (let i = 0; i < successFiles.length; i++) {
-      try { fs.unlinkSync(successFiles[i]); } catch (e) {}
-    }
-  }
-
-  const remaining = messageFiles.length - readCount;
-  return { messages, remaining, files: successFiles };
-}
-
-/**
- * Delete inbox files after confirming delivery.
- * Used with drainInbox({ deleteFiles: false }) for at-least-once delivery semantics. (#231)
- * @param {string[]} filePaths - Array of absolute file paths to delete
- */
-function deleteInboxFiles(filePaths) {
-  if (!Array.isArray(filePaths)) return;
-  for (let i = 0; i < filePaths.length; i++) {
-    try { fs.unlinkSync(filePaths[i]); } catch (e) {}
-  }
-}
-
-/**
- * Format inbox messages for inclusion in an LLM prompt.
- * @param {Array<object>} messages - Array of message objects from drainInbox
- * @param {number} [remaining] - Number of remaining messages (optional)
- * @returns {string} Formatted prompt string
- */
-function formatInboxMessages(messages, remaining) {
-  if (!messages || messages.length === 0) return '';
-
-  let result = 'You have received messages from users. Process them, then continue your normal work:\n';
-
-  for (let i = 0; i < messages.length; i++) {
-    const msg = messages[i];
-    const priorityTag = msg.priority === 'high' ? ', priority: high' : '';
-    result += '\n[' + (i + 1) + '] (from: ' + msg.from + priorityTag + ')\n';
-    result += msg.message + '\n';
-  }
-
-  if (remaining && remaining > 0) {
-    result += '\n(' + remaining + ' more messages remaining in inbox, will be delivered next iteration)\n';
-  }
-
-  return result;
-}
-
-// ============================================================
-// Urgent Interrupt Protocol (Phase 4, Issue #201)
-// ============================================================
-
-/**
- * Get the path to an agent's interrupt file.
- * @param {string} name - Agent name (will be sanitized)
- * @returns {string} Path to interrupt.json
- */
-function getInterruptPath(name) {
-  return path.join(getAgentDir(name), 'interrupt.json');
-}
-
-/**
- * Write an urgent interrupt to an agent.
- * Latest write wins — no queue. Urgency means "drop everything."
- * Uses atomic write (tmp + rename) for safety.
- *
- * @param {string} name - Agent name (will be sanitized)
- * @param {string} messageText - Interrupt message
- * @param {object} [opts] - Options
- * @param {string} [opts.from] - Sender identifier (default: 'tui')
- * @param {string} [opts.action] - 'abort' (default). 'divert' reserved for future use.
- * @returns {{success: boolean, error: string|null}}
- */
-function writeInterrupt(name, messageText, opts) {
-  const from = (opts && opts.from) || 'tui';
-  const action = (opts && opts.action) || 'abort';
-
-  if (!messageText || typeof messageText !== 'string') {
-    return { success: false, error: 'Interrupt message must be a non-empty string' };
-  }
-
-  const dir = getAgentDir(name);
-  const interruptPath = path.join(dir, 'interrupt.json');
-  const tmpPath = interruptPath + '.' + process.pid + '-' + Math.random().toString(16).slice(2, 8) + '.tmp';
-
-  const envelope = {
-    action,
-    message: messageText,
-    from,
-    timestamp: Date.now(),
-  };
-
-  try {
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  } catch (e) {
-    return { success: false, error: 'Failed to create agent directory: ' + e.message };
-  }
-
-  try {
-    fs.writeFileSync(tmpPath, JSON.stringify(envelope, null, 2), { mode: 0o600 });
-    try {
-      fs.renameSync(tmpPath, interruptPath);
-    } catch (renameErr) {
-      if (renameErr.code === 'EEXIST' || renameErr.code === 'EPERM') {
-        try { fs.unlinkSync(interruptPath); } catch (e2) {}
-        fs.renameSync(tmpPath, interruptPath);
-      } else {
-        throw renameErr;
-      }
-    }
-    return { success: true, error: null };
-  } catch (e) {
-    try { fs.unlinkSync(tmpPath); } catch (e2) {}
-    return { success: false, error: 'Failed to write interrupt: ' + e.message };
-  }
-}
-
-/**
- * Check if an agent has a pending interrupt, without reading/consuming it.
- * @param {string} name - Agent name
- * @returns {boolean}
- */
-function hasInterrupt(name) {
-  try {
-    fs.accessSync(getInterruptPath(name), fs.constants.F_OK);
-    return true;
-  } catch (e) {
-    return false;
-  }
-}
-
-/**
- * Read an agent's interrupt file. Does NOT delete it (caller must clearInterrupt).
- * @param {string} name - Agent name
- * @returns {object|null} Interrupt envelope or null if none/unreadable
- */
-function readInterrupt(name) {
-  const interruptPath = getInterruptPath(name);
-  try {
-    const data = fs.readFileSync(interruptPath, 'utf8');
-    const envelope = JSON.parse(data);
-    if (!envelope.message || typeof envelope.message !== 'string') {
-      return null;
-    }
-    return envelope;
-  } catch (e) {
-    return null;
-  }
-}
-
-/**
- * Delete an agent's interrupt file after it has been processed.
- * @param {string} name - Agent name
- */
-function clearInterrupt(name) {
-  try {
-    fs.unlinkSync(getInterruptPath(name));
-  } catch (e) {
-    // File may already be gone
-  }
-}
-
-/**
- * Remove an agent's registry entry and all associated files.
- * Removes the entire agent directory (status.json, lock, inbox/, interrupt.json).
- * Does NOT verify if the agent is running - caller should check.
- * @param {string} name - Agent name
- * @returns {{ removed: boolean, error: null }} Result object (error is always null on return)
- * @throws {Error} On filesystem errors other than ENOENT (e.g., EPERM, EBUSY)
- */
-function removeAgent(name) {
-  const sanitized = sanitizeName(name);
-  const agentDir = getAgentDir(sanitized);
-
-  // Remove the entire agent directory recursively (Node 14.14+).
-  // This cleans up status.json, lock, inbox/, interrupt.json, and any
-  // future artifacts under the agent directory.
-  // Using force:false so rmSync throws on real errors (EPERM, EBUSY).
-  // ENOENT is caught explicitly to handle races (dir removed externally).
-  try {
-    fs.rmSync(agentDir, { recursive: true });
-    return { removed: true, error: null };
-  } catch (e) {
-    // ENOENT means the directory was already gone — not an error
-    if (e && e.code === 'ENOENT') {
-      return { removed: false, error: null };
-    }
-    // Surface real errors (EPERM, EBUSY, etc.) to the caller
-    throw e;
-  }
-}
-
-module.exports = {
-  getAgentsDir,
-  setAgentsDir,
-  resetAgentsDir,
-  STATES,
-  sanitizeName,
-  getAgentDir,
-  getStatusPath,
-  isProcessAlive,
-  claimAgent,
-  releaseAgent,
-  writeStatus,
-  readStatus,
-  isAgentAlive,
-  getAgentServerUrl,
-  listAgents,
-  formatUptime,
-  resolveAgentName,
-  stopAgent,
-  removeAgent,
-  getAgentLogFile,
-  getInboxDir,
-  writeInboxMessage,
-  inboxHasMessages,
-  drainInbox,
-  deleteInboxFiles,
-  formatInboxMessages,
-  getInterruptPath,
-  writeInterrupt,
-  hasInterrupt,
-  readInterrupt,
-  clearInterrupt,
-};