@yemi33/minions 0.1.60 → 0.1.62

package/engine.js

@@ -106,15 +106,18 @@ function log(level, msg, meta = {}) {
   safeWrite(LOG_PATH, logData);
 }
 
-function mutateDispatch(mutator) {
-  const defaultDispatch = { pending: [], active: [], completed: [] };
-  return mutateJsonFileLocked(DISPATCH_PATH, (dispatch) => {
-    dispatch.pending = Array.isArray(dispatch.pending) ? dispatch.pending : [];
-    dispatch.active = Array.isArray(dispatch.active) ? dispatch.active : [];
-    dispatch.completed = Array.isArray(dispatch.completed) ? dispatch.completed : [];
-    return mutator(dispatch) || dispatch;
-  }, { defaultValue: defaultDispatch });
-}
+// ─── Dispatch Management (extracted to engine/dispatch.js) ───────────────────
+
+const { mutateDispatch, addToDispatch, isRetryableFailureReason, completeDispatch,
+  writeInboxAlert } = require('./engine/dispatch');
+
+// ─── Timeout / Steering / Idle (extracted to engine/timeout.js) ──────────────
+
+const { checkTimeouts, checkSteering, checkIdleThreshold } = require('./engine/timeout');
+
+// ─── Cleanup (extracted to engine/cleanup.js) ────────────────────────────────
+
+const { runCleanup } = require('./engine/cleanup');
 
 // ─── State Readers (delegated to engine/queries.js) ─────────────────────────
 
@@ -714,147 +717,9 @@ function spawnAgent(dispatchItem, config) {
   return proc;
 }
 
-// ─── Dispatch Management ────────────────────────────────────────────────────
+// addToDispatch, isRetryableFailureReason — now in engine/dispatch.js
 
-function addToDispatch(item) {
-  item.id = item.id || `${item.agent}-${item.type}-${shared.uid()}`;
-  item.created_at = ts();
-  mutateDispatch((dispatch) => {
-    dispatch.pending.push(item);
-  });
-  log('info', `Queued dispatch: ${item.id} (${item.type} → ${item.agent})`);
-  return item.id;
-}
-
-function isRetryableFailureReason(reason = '') {
-  const r = String(reason || '').toLowerCase();
-  if (!r) return true; // unknown error from tool exit — keep retryable
-  const nonRetryable = [
-    'no playbook rendered',
-    'failed to render',
-    'no target project available',
-    'no plan files found',
-    'plan file not found',
-    'invalid filename',
-    'invalid file path',
-    'missing required',
-    'validation failed',
-  ];
-  return !nonRetryable.some(s => r.includes(s));
-}
-
-function completeDispatch(id, result = 'success', reason = '', resultSummary = '', opts = {}) {
-  const { processWorkItemFailure = true } = opts;
-  let item = null;
-
-  mutateDispatch((dispatch) => {
-    // Check active list first
-    let idx = dispatch.active.findIndex(d => d.id === id);
-    if (idx >= 0) {
-      item = dispatch.active.splice(idx, 1)[0];
-    } else {
-      // Also check pending list (e.g., worktree failure before spawn)
-      idx = dispatch.pending.findIndex(d => d.id === id);
-      if (idx >= 0) item = dispatch.pending.splice(idx, 1)[0];
-    }
-
-    if (!item) return;
-    item.completed_at = ts();
-    item.result = result;
-    if (reason) item.reason = reason;
-    if (resultSummary) item.resultSummary = resultSummary;
-    delete item.prompt;
-    if (dispatch.completed.length >= 100) {
-      dispatch.completed = dispatch.completed.slice(-99);
-    }
-    dispatch.completed.push(item);
-  });
-
-  if (item) {
-    log('info', `Completed dispatch: ${id} (${result}${reason ? ': ' + reason : ''})`);
-
-    // Update source work item status on failure + auto-retry with backoff
-    const retryableFailure = isRetryableFailureReason(reason);
-    if (result === 'error' && item.meta?.dispatchKey && retryableFailure) setCooldownFailure(item.meta.dispatchKey);
-
-    if (processWorkItemFailure && result === 'error' && item.meta?.item?.id) {
-      let retries = (item.meta.item._retryCount || 0);
-      try {
-        const wiPath = item.meta.source === 'central-work-item' || item.meta.source === 'central-work-item-fanout'
-          ? path.join(MINIONS_DIR, 'work-items.json')
-          : item.meta.project?.name ? projectWorkItemsPath({ name: item.meta.project.name, localPath: item.meta.project.localPath }) : null;
-        if (wiPath) {
-          const items = safeJson(wiPath) || [];
-          const wi = items.find(i => i.id === item.meta.item.id);
-          if (wi) retries = wi._retryCount || 0;
-        }
-      } catch (e) { log('warn', 'read retry count: ' + e.message); }
-      if (retryableFailure && retries < 3) {
-        log('info', `Dispatch error for ${item.meta.item.id} — auto-retry ${retries + 1}/3`);
-        updateWorkItemStatus(item.meta, 'pending', '');
-        // Remove this dispatch key from completed so dedupe doesn't block immediate redispatch.
-        if (item.meta?.dispatchKey) {
-          try {
-            mutateDispatch((dp) => {
-              dp.completed = Array.isArray(dp.completed) ? dp.completed.filter(d => d.meta?.dispatchKey !== item.meta.dispatchKey) : [];
-              return dp;
-            });
-          } catch (e) { log('warn', 'clear dispatch for retry: ' + e.message); }
-        }
-        // Increment retry counter on the source work item
-        try {
-          const wiPath = item.meta.source === 'central-work-item' || item.meta.source === 'central-work-item-fanout'
-            ? path.join(MINIONS_DIR, 'work-items.json')
-            : item.meta.project?.name ? projectWorkItemsPath({ name: item.meta.project.name, localPath: item.meta.project.localPath }) : null;
-          if (wiPath) {
-            const items = safeJson(wiPath) || [];
-            const wi = items.find(i => i.id === item.meta.item.id);
-            if (wi && wi.status !== 'paused') {
-              wi._retryCount = retries + 1;
-              wi.status = 'pending';
-              wi._lastRetryReason = reason || '';
-              wi._lastRetryAt = ts();
-              delete wi.failReason;
-              delete wi.failedAt;
-              delete wi.dispatched_at;
-              delete wi.dispatched_to;
-              safeWrite(wiPath, items);
-            }
-          }
-        } catch (e) { log('warn', 'increment retry counter: ' + e.message); }
-      } else {
-        const finalReason = !retryableFailure
-          ? `Non-retryable failure: ${reason || 'Unknown error'}`
-          : (reason || 'Failed after 3 retries');
-        updateWorkItemStatus(item.meta, 'failed', finalReason);
-        // Alert: find items blocked by this failure and write inbox note
-        try {
-          const config = getConfig();
-          const failedId = item.meta.item.id;
-          const blockedItems = [];
-          for (const p of getProjects(config)) {
-            const items = safeJson(projectWorkItemsPath(p)) || [];
-            items.filter(w => w.status === 'pending' && (w.depends_on || []).includes(failedId))
-              .forEach(w => blockedItems.push(`- \`${w.id}\` — ${w.title}`));
-          }
-          const centralItems = safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [];
-          centralItems.filter(w => w.status === 'pending' && (w.depends_on || []).includes(failedId))
-            .forEach(w => blockedItems.push(`- \`${w.id}\` — ${w.title}`));
-
-          writeInboxAlert(`failed-${failedId}`,
-            `# Work Item Failed — \`${failedId}\`\n\n` +
-            `**Item:** ${item.meta.item.title || failedId}\n` +
-            `**Reason:** ${finalReason}\n\n` +
-            (blockedItems.length > 0
-              ? `**Blocked dependents (${blockedItems.length}):**\n${blockedItems.join('\n')}\n\n` +
-                `These items cannot dispatch until \`${failedId}\` is fixed and reset to \`pending\`.\n`
-              : `No downstream items are blocked.\n`)
-          );
-        } catch (e) { log('warn', 'write failure alert: ' + e.message); }
-      }
-    }
-  }
-}
+// completeDispatch — now in engine/dispatch.js
 
 // ─── Dependency Gate ─────────────────────────────────────────────────────────
 // Returns: true (deps met), false (deps pending), 'failed' (dep failed — propagate)
@@ -910,18 +775,7 @@ function detectDependencyCycles(items) {
 }
 
 
-// ─── Shared helpers ───────────────────────────────────────────────────────────
-
-// Write a one-off alert note to notes/inbox so the user sees it on next consolidation
-function writeInboxAlert(slug, content) {
-  try {
-    const file = path.join(INBOX_DIR, `engine-alert-${slug}-${dateStamp()}.md`);
-    // Dedupe: don't write the same alert twice in the same day
-    const existing = safeReadDir(INBOX_DIR).find(f => f.startsWith(`engine-alert-${slug}-${dateStamp()}`));
-    if (existing) return;
-    safeWrite(file, content);
-  } catch (e) { log('warn', 'write inbox alert: ' + e.message); }
-}
+// writeInboxAlert — now in engine/dispatch.js
 
 // Reconciles work items against known PRs.
 // Primary linkage comes from prdItems in pull-requests.json; fallback linkage
@@ -993,599 +847,9 @@ function updateSnapshot(config) {
   safeWrite(path.join(IDENTITY_DIR, 'now.md'), snapshot);
 }
 
-// ─── Idle Alert ─────────────────────────────────────────────────────────────
-
-let _lastActivityTime = Date.now();
-let _idleAlertSent = false;
-
-function checkIdleThreshold(config) {
-  const thresholdMs = (config.engine?.idleAlertMinutes || 15) * 60 * 1000;
-  const agents = Object.keys(config.agents || {});
-  const allIdle = agents.every(id => isAgentIdle(id));
-  const dispatch = getDispatch();
-  const hasPending = (dispatch.pending || []).length > 0;
-
-  if (!allIdle || hasPending) {
-    _lastActivityTime = Date.now();
-    _idleAlertSent = false;
-    return;
-  }
-
-  const idleMs = Date.now() - _lastActivityTime;
-  if (idleMs > thresholdMs && !_idleAlertSent) {
-    const mins = Math.round(idleMs / 60000);
-    log('warn', `All agents idle for ${mins} minutes — no work sources producing items`);
-    _idleAlertSent = true;
-  }
-}
-
-// ─── Steering Checker ────────────────────────────────────────────────────────
-
-function checkSteering(config) {
-  for (const [id, info] of activeProcesses) {
-    const steerPath = path.join(AGENTS_DIR, info.agentId, 'steer.md');
-    if (!fs.existsSync(steerPath)) continue;
-
-    const message = safeRead(steerPath);
-    try { fs.unlinkSync(steerPath); } catch { /* cleanup */ }
-    if (!message) continue;
-
-    const sessionId = info.sessionId;
-    if (!sessionId) {
-      log('warn', `Steering: no sessionId for ${info.agentId} — cannot resume. Message dropped.`);
-      continue;
-    }
-
-    log('info', `Steering: killing ${info.agentId} (${id}) for session resume with human message`);
-
-    // Kill current process
-    try { info.proc.kill('SIGTERM'); } catch { /* process may be dead */ }
-
-    // Store steering context for re-spawn on close
-    info._steeringMessage = message;
-    info._steeringSessionId = sessionId;
-  }
-}
-
-// ─── Timeout Checker ────────────────────────────────────────────────────────
-
-function checkTimeouts(config) {
-  const timeout = config.engine?.agentTimeout || DEFAULTS.agentTimeout;
-  const heartbeatTimeout = config.engine?.heartbeatTimeout || DEFAULTS.heartbeatTimeout;
-
-  // 1. Check tracked processes for hard timeout (supports per-item deadline from fan-out)
-  for (const [id, info] of activeProcesses.entries()) {
-    const itemTimeout = info.meta?.deadline ? Math.max(0, info.meta.deadline - new Date(info.startedAt).getTime()) : timeout;
-    const elapsed = Date.now() - new Date(info.startedAt).getTime();
-    if (elapsed > itemTimeout) {
-      log('warn', `Agent ${info.agentId} (${id}) hit hard timeout after ${Math.round(elapsed / 1000)}s — killing`);
-      try { info.proc.kill('SIGTERM'); } catch { /* process may be dead */ }
-      setTimeout(() => {
-        try { info.proc.kill('SIGKILL'); } catch { /* process may be dead */ }
-      }, 5000);
-    }
-  }
+// checkIdleThreshold, checkSteering, checkTimeouts — now in engine/timeout.js
 
-  // 2. Heartbeat check — for ALL active dispatch items (catches orphans after engine restart)
-  //    Uses live-output.log mtime as heartbeat. If no output for heartbeatTimeout, agent is dead.
-  const dispatch = getDispatch();
-  const deadItems = [];
-
-  for (const item of (dispatch.active || [])) {
-    if (!item.agent) continue;
-
-    const hasProcess = activeProcesses.has(item.id);
-    const liveLogPath = path.join(AGENTS_DIR, item.agent, 'live-output.log');
-    let lastActivity = item.started_at ? new Date(item.started_at).getTime() : 0;
-
-    // Check live-output.log mtime as heartbeat
-    try {
-      const stat = fs.statSync(liveLogPath);
-      lastActivity = Math.max(lastActivity, stat.mtimeMs);
-    } catch { /* optional */ }
-
-    const silentMs = Date.now() - lastActivity;
-    const silentSec = Math.round(silentMs / 1000);
-
-    // Check if the agent actually completed (result event in live output)
-    // Optimization: only read file if recent activity (avoids reading stale 1MB logs)
-    let completedViaOutput = false;
-    try {
-      if (silentMs > 600000) throw 'skip'; // No point reading a file silent for >10min
-      const liveLog = safeRead(liveLogPath);
-      if (liveLog && liveLog.includes('"type":"result"')) {
-        completedViaOutput = true;
-        const isSuccess = liveLog.includes('"subtype":"success"');
-        log('info', `Agent ${item.agent} (${item.id}) completed via output detection (${isSuccess ? 'success' : 'error'})`);
-
-        // Extract output text for the output.log
-        const outputLogPath = path.join(AGENTS_DIR, item.agent, 'output.log');
-        try {
-          const resultLine = liveLog.split('\n').find(l => l.includes('"type":"result"'));
-          if (resultLine) {
-            const result = JSON.parse(resultLine);
-            safeWrite(outputLogPath, `# Output for dispatch ${item.id}\n# Exit code: ${isSuccess ? 0 : 1}\n# Completed: ${ts()}\n# Detected via output scan\n\n## Result\n${result.result || '(no text)'}\n`);
-          }
-        } catch (e) { log('warn', 'parse output result: ' + e.message); }
-
-        completeDispatch(item.id, isSuccess ? 'success' : 'error', 'Completed (detected from output)');
-
-        // Run post-completion hooks via shared helper
-        runPostCompletionHooks(item, item.agent, isSuccess ? 0 : 1, liveLog, config);
-
-        if (hasProcess) {
-          try { activeProcesses.get(item.id)?.proc.kill('SIGTERM'); } catch { /* process may be dead */ }
-          activeProcesses.delete(item.id);
-        }
-        continue; // Skip orphan/hung detection — we handled it
-      }
-    } catch (e) { log('warn', 'output completion detection: ' + e.message); }
-
-    // Check if agent is in a blocking tool call (TaskOutput block:true, Bash with long timeout, etc.)
-    // These tools produce no stdout for extended periods — don't kill them prematurely
-    // Check for BOTH tracked and untracked processes (orphan case after engine restart)
-    let isBlocking = false;
-    let blockingTimeout = heartbeatTimeout;
-    if (silentMs > heartbeatTimeout) {
-      try {
-        const liveLog = safeRead(liveLogPath);
-        if (liveLog) {
-          // Find the last tool_use call in the output — check if it's a known blocking tool
-          const lines = liveLog.split('\n');
-          for (let i = lines.length - 1; i >= Math.max(0, lines.length - 30); i--) {
-            const line = lines[i];
-            if (!line.includes('"tool_use"')) continue;
-            try {
-              const parsed = JSON.parse(line);
-              const toolUse = parsed?.message?.content?.find?.(c => c.type === 'tool_use');
-              if (!toolUse) continue;
-              const input = toolUse.input || {};
-              const name = toolUse.name || '';
-              // TaskOutput with block:true — waiting for a background task
-              if (name === 'TaskOutput' && input.block === true) {
-                const taskTimeout = input.timeout || 600000; // default 10min
-                blockingTimeout = Math.max(heartbeatTimeout, taskTimeout + 60000); // task timeout + 1min grace
-                isBlocking = true;
-              }
-              // Bash with explicit long timeout (>5min)
-              if (name === 'Bash' && input.timeout && input.timeout > heartbeatTimeout) {
-                blockingTimeout = Math.max(heartbeatTimeout, input.timeout + 60000);
-                isBlocking = true;
-              }
-              break; // only check the most recent tool_use
-            } catch { /* JSON parse — line may not be valid JSON */ }
-          }
-          if (isBlocking) {
-            log('info', `Agent ${item.agent} (${item.id}) is in a blocking tool call — extended timeout to ${Math.round(blockingTimeout / 1000)}s (silent for ${silentSec}s)`);
-          }
-        }
-      } catch (e) { log('warn', 'blocking tool detection: ' + e.message); }
-    }
-
-    const effectiveTimeout = isBlocking ? blockingTimeout : heartbeatTimeout;
-
-    if (!hasProcess && silentMs > effectiveTimeout && Date.now() > engineRestartGraceUntil) {
-      // No tracked process AND no recent output past effective timeout AND grace period expired → orphaned
-      log('warn', `Orphan detected: ${item.agent} (${item.id}) — no process tracked, silent for ${silentSec}s${isBlocking ? ' (blocking timeout exceeded)' : ''}`);
-      deadItems.push({ item, reason: `Orphaned — no process, silent for ${silentSec}s` });
-    } else if (hasProcess && silentMs > effectiveTimeout) {
-      // Has process but no output past effective timeout → hung
-      log('warn', `Hung agent: ${item.agent} (${item.id}) — process exists but no output for ${silentSec}s${isBlocking ? ' (blocking timeout exceeded)' : ''}`);
-      const procInfo = activeProcesses.get(item.id);
-      if (procInfo) {
-        try { procInfo.proc.kill('SIGTERM'); } catch { /* process may be dead */ }
-        setTimeout(() => { try { procInfo.proc.kill('SIGKILL'); } catch { /* process may be dead */ } }, 5000);
-        activeProcesses.delete(item.id);
-      }
-      deadItems.push({ item, reason: `Hung — no output for ${silentSec}s` });
-    }
-    // If has process and recent output → healthy, let it run
-  }
-
-  // Clean up dead items
-  for (const { item, reason } of deadItems) {
-    completeDispatch(item.id, 'error', reason);
-  }
-
-  // Agent status is now derived from dispatch.json at read time (getAgentStatus).
-  // No reconcile sweep needed — dispatch IS the source of truth.
-
-  // Reconcile: find work items stuck in "dispatched" with no matching active dispatch
-  const activeKeys = new Set((dispatch.active || []).map(d => d.meta?.dispatchKey).filter(Boolean));
-  const allWiPaths = [path.join(MINIONS_DIR, 'work-items.json')];
-  for (const project of getProjects(config)) {
-    allWiPaths.push(projectWorkItemsPath(project));
-  }
-  for (const wiPath of allWiPaths) {
-    const items = safeJson(wiPath);
-    if (!items || !Array.isArray(items)) continue;
-    let changed = false;
-    for (const item of items) {
-      if (item.status !== 'dispatched') continue;
-      // Check if any active dispatch references this item
-      // Dispatch keys include project name: work-{project}-{id} or central-work-{id}
-      const projectNames = getProjects(config).map(p => p.name);
-      const possibleKeys = [
-        `central-work-${item.id}`,
-        ...projectNames.map(p => `work-${p}-${item.id}`),
-      ];
-      const isActive = possibleKeys.some(k => activeKeys.has(k)) ||
-        (dispatch.active || []).some(d => d.meta?.item?.id === item.id);
-      if (!isActive) {
-        const retries = (item._retryCount || 0);
-        if (retries < 3) {
-          log('info', `Reconcile: work item ${item.id} agent died — auto-retry ${retries + 1}/3`);
-          item.status = 'pending';
-          item._retryCount = retries + 1;
-          delete item.dispatched_at;
-          delete item.dispatched_to;
-        } else {
-          log('warn', `Reconcile: work item ${item.id} failed after ${retries} retries — marking as failed`);
-          item.status = 'failed';
-          item.failReason = 'Agent died or was killed (3 retries exhausted)';
-          item.failedAt = ts();
-        }
-        changed = true;
-      }
-    }
-    if (changed) safeWrite(wiPath, items);
-  }
-}
-
-// ─── Cleanup ─────────────────────────────────────────────────────────────────
-
-function runCleanup(config, verbose = false) {
-  const projects = getProjects(config);
-  let cleaned = { tempFiles: 0, liveOutputs: 0, worktrees: 0, zombies: 0 };
-
-  // 1. Clean stale temp prompt/sysprompt files (older than 1 hour)
-  const oneHourAgo = Date.now() - 3600000;
-  try {
-    const tmpDir = path.join(ENGINE_DIR, 'tmp');
-    const scanDirs = [ENGINE_DIR, ...(fs.existsSync(tmpDir) ? [tmpDir] : [])];
-    for (const dir of scanDirs) {
-      for (const f of fs.readdirSync(dir)) {
-        if (f.startsWith('prompt-') || f.startsWith('sysprompt-') || f.startsWith('tmp-sysprompt-')) {
-          const fp = path.join(dir, f);
-          try {
-            const stat = fs.statSync(fp);
-            if (stat.mtimeMs < oneHourAgo) {
-              fs.unlinkSync(fp);
-              cleaned.tempFiles++;
-            }
-          } catch { /* cleanup */ }
-        }
-      }
-    }
-  } catch (e) { log('warn', 'cleanup temp files: ' + e.message); }
-
-  // 2. Clean live-output.log for idle agents (not currently working)
-  for (const [agentId] of Object.entries(config.agents || {})) {
-    const status = getAgentStatus(agentId);
-    if (status.status !== 'working') {
-      const livePath = path.join(AGENTS_DIR, agentId, 'live-output.log');
-      if (fs.existsSync(livePath)) {
-        try {
-          const stat = fs.statSync(livePath);
-          if (stat.mtimeMs < oneHourAgo) {
-            fs.unlinkSync(livePath);
-            cleaned.liveOutputs++;
-          }
-        } catch { /* cleanup */ }
-      }
-    }
-  }
-
-  // 3. Clean git worktrees for merged/abandoned PRs
-  for (const project of projects) {
-    const root = project.localPath ? path.resolve(project.localPath) : null;
-    if (!root || !fs.existsSync(root)) continue;
-
-    const worktreeRoot = path.resolve(root, config.engine?.worktreeRoot || '../worktrees');
-    if (!fs.existsSync(worktreeRoot)) continue;
-
-    // Get PRs for this project
-    const prs = safeJson(projectPrPath(project)) || [];
-    const mergedBranches = new Set();
-    for (const pr of prs) {
-      if (pr.status === 'merged' || pr.status === 'abandoned' || pr.status === 'completed') {
-        if (pr.branch) mergedBranches.add(pr.branch);
-      }
-    }
-
-    // List worktrees — collect info for age-based + cap-based cleanup
-    const MAX_WORKTREES = 10;
-    try {
-      const dirs = fs.readdirSync(worktreeRoot);
-      const wtEntries = []; // { dir, wtPath, mtime, shouldClean, isProtected }
-      const dispatch = getDispatch();
-
-      for (const dir of dirs) {
-        const wtPath = path.join(worktreeRoot, dir);
-        try { if (!fs.statSync(wtPath).isDirectory()) continue; } catch { continue; }
-
-        let shouldClean = false;
-        let isProtected = false;
-
-        // Check if this worktree's branch is merged/abandoned
-        // Use sanitized exact match on the branch portion of the dir name (format: {slug}-{branch}-{suffix})
-        const dirLower = dir.toLowerCase();
-        for (const branch of mergedBranches) {
-          const branchSlug = sanitizeBranch(branch).toLowerCase();
-          if (dirLower === branchSlug || dirLower.includes(branchSlug + '-') || dirLower.endsWith('-' + branchSlug)) {
-            shouldClean = true;
-            break;
-          }
-        }
-
-        // Check if referenced by active/pending dispatch (use sanitized branch comparison)
-        const isReferenced = [...dispatch.pending, ...(dispatch.active || [])].some(d => {
-          if (!d.meta?.branch) return false;
-          const dispBranch = sanitizeBranch(d.meta.branch).toLowerCase();
-          return dirLower.includes(dispBranch);
-        });
-        if (isReferenced) isProtected = true;
-
-        // Also clean worktrees older than 2 hours with no active dispatch referencing them
-        let mtime = Date.now();
-        if (!shouldClean) {
-          try {
-            const stat = fs.statSync(wtPath);
-            mtime = stat.mtimeMs;
-            const ageMs = Date.now() - mtime;
-            if (ageMs > 7200000 && !isReferenced) { // 2 hours
-              shouldClean = true;
-            }
-          } catch { /* optional */ }
-        }
-
-        // Skip worktrees for active shared-branch plans (check both prd/ and plans/ for .json PRDs)
-        if (shouldClean || !isProtected) {
-          try {
-            for (const checkDir of [PRD_DIR, path.join(MINIONS_DIR, 'plans')]) {
-              if (!fs.existsSync(checkDir)) continue;
-              for (const pf of fs.readdirSync(checkDir).filter(f => f.endsWith('.json'))) {
-                const plan = safeJson(path.join(checkDir, pf));
-                if (plan?.branch_strategy === 'shared-branch' && plan?.feature_branch && plan?.status !== 'completed') {
-                  const planBranch = sanitizeBranch(plan.feature_branch).toLowerCase();
-                  if (dirLower.includes(planBranch)) {
-                    isProtected = true;
-                    if (shouldClean) {
-                      shouldClean = false;
-                      if (verbose) console.log(`  Skipping worktree ${dir}: active shared-branch plan`);
-                    }
-                    break;
-                  }
-                }
-              }
-              if (isProtected) break;
-            }
-          } catch (e) { log('warn', 'check shared-branch protection: ' + e.message); }
-        }
-
-        wtEntries.push({ dir, wtPath, mtime, shouldClean, isProtected });
-      }
-
-      // Enforce max worktree cap — if over limit, mark oldest unprotected for cleanup
-      const surviving = wtEntries.filter(e => !e.shouldClean && !e.isProtected);
-      if (surviving.length + wtEntries.filter(e => e.isProtected).length > MAX_WORKTREES) {
-        // Sort oldest first
-        surviving.sort((a, b) => a.mtime - b.mtime);
-        const excess = surviving.length + wtEntries.filter(e => e.isProtected).length - MAX_WORKTREES;
-        for (let i = 0; i < Math.min(excess, surviving.length); i++) {
-          surviving[i].shouldClean = true;
-          if (verbose) console.log(`  Marking worktree ${surviving[i].dir} for cap cleanup (${MAX_WORKTREES} max)`);
-        }
-      }
-
-      // Remove all marked worktrees
-      for (const entry of wtEntries) {
-        if (entry.shouldClean) {
-          try {
-            exec(`git worktree remove "${entry.wtPath}" --force`, { cwd: root, stdio: 'pipe' });
-            cleaned.worktrees++;
-            if (verbose) console.log(`  Removed worktree: ${entry.wtPath}`);
-          } catch (e) {
-            if (verbose) console.log(`  Failed to remove worktree ${entry.wtPath}: ${e.message}`);
-          }
-        }
-      }
-    } catch (e) { log('warn', 'cleanup worktrees: ' + e.message); }
-  }
-
-  // 4. Kill zombie claude processes not tracked by the engine
-  // List all node processes, check if any are running spawn-agent.js for our minions
-  try {
-    const dispatch = getDispatch();
-    const activePids = new Set();
-    for (const [, info] of activeProcesses.entries()) {
-      if (info.proc?.pid) activePids.add(info.proc.pid);
-    }
-
-    // Clean individual orphaned processes — no matching active dispatch
-    const activeIds = new Set((dispatch.active || []).map(d => d.id));
-    for (const [id, info] of activeProcesses.entries()) {
-      if (!activeIds.has(id)) {
-        try { if (info.proc) info.proc.kill('SIGTERM'); } catch { /* process may be dead */ }
-        activeProcesses.delete(id);
-        cleaned.zombies++;
-      }
-    }
-  } catch (e) { log('warn', 'cleanup zombie processes: ' + e.message); }
-
-  // 5. Clean spawn-debug.log
-  try { fs.unlinkSync(path.join(ENGINE_DIR, 'spawn-debug.log')); } catch { /* cleanup */ }
-
-  // 6. Prune old output archive files (keep last 30 per agent)
-  for (const agentId of Object.keys(config.agents || {})) {
-    const agentDir = path.join(MINIONS_DIR, 'agents', agentId);
-    if (!fs.existsSync(agentDir)) continue;
-    try {
-      const outputFiles = fs.readdirSync(agentDir)
-        .filter(f => f.startsWith('output-') && f.endsWith('.log') && f !== 'output.log')
-        .map(f => ({ name: f, mtime: fs.statSync(path.join(agentDir, f)).mtimeMs }))
-        .sort((a, b) => b.mtime - a.mtime);
-      for (const old of outputFiles.slice(30)) {
-        try { fs.unlinkSync(path.join(agentDir, old.name)); cleaned.files++; } catch { /* cleanup */ }
-      }
-    } catch (e) { log('warn', 'prune output archives: ' + e.message); }
-  }
-
-  // 7. Prune orphaned dispatch entries — items whose source work item no longer exists
-  cleaned.orphanedDispatches = 0;
-  try {
-    const dispatch = getDispatch();
-    // Collect all work item IDs across all sources
-    const allWiIds = new Set();
-    try {
-      const central = safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [];
-      central.forEach(w => allWiIds.add(w.id));
-    } catch (e) { log('warn', 'read central work items for orphan check: ' + e.message); }
-    for (const project of projects) {
-      try {
-        const projItems = safeJson(projectWorkItemsPath(project)) || [];
-        projItems.forEach(w => allWiIds.add(w.id));
-      } catch (e) { log('warn', 'read project work items for orphan check: ' + e.message); }
-    }
-
-    let changed = false;
-    for (const queue of ['pending', 'active']) {
-      if (!dispatch[queue]) continue;
-      const before = dispatch[queue].length;
-      dispatch[queue] = dispatch[queue].filter(d => {
-        const itemId = d.meta?.item?.id;
-        if (!itemId) return true; // keep entries without item tracking
-        return allWiIds.has(itemId);
-      });
-      const removed = before - dispatch[queue].length;
-      if (removed > 0) {
-        cleaned.orphanedDispatches += removed;
-        changed = true;
-      }
-    }
-    if (changed) {
-      mutateDispatch((dp) => {
-        for (const queue of ['pending', 'active']) {
-          if (!dp[queue]) continue;
-          dp[queue] = dp[queue].filter(d => {
-            const itemId = d.meta?.item?.id;
-            if (!itemId) return true;
-            return allWiIds.has(itemId);
-          });
-        }
-      });
-    }
-  } catch (e) { log('warn', 'prune orphaned dispatches: ' + e.message); }
-
-  if (cleaned.tempFiles + cleaned.liveOutputs + cleaned.worktrees + cleaned.zombies + (cleaned.files || 0) + cleaned.orphanedDispatches > 0) {
-    log('info', `Cleanup: ${cleaned.tempFiles} temp, ${cleaned.liveOutputs} live outputs, ${cleaned.worktrees} worktrees, ${cleaned.zombies} zombies, ${cleaned.files || 0} archives, ${cleaned.orphanedDispatches} orphaned dispatches`);
-  }
-
-  // 8. Clean swept KB files older than 7 days
-  try {
-    const sweptDir = path.join(MINIONS_DIR, 'knowledge', '_swept');
-    if (fs.existsSync(sweptDir)) {
-      const sevenDaysAgo = Date.now() - 7 * 86400000;
-      for (const f of fs.readdirSync(sweptDir)) {
-        try {
-          const fp = path.join(sweptDir, f);
-          if (fs.statSync(fp).mtimeMs < sevenDaysAgo) {
-            fs.unlinkSync(fp);
-            if (!cleaned.sweptKb) cleaned.sweptKb = 0;
-            cleaned.sweptKb++;
-          }
-        } catch { /* cleanup */ }
-      }
-    }
-  } catch (e) { log('warn', 'cleanup swept KB files: ' + e.message); }
-
-  // 9. KB watchdog — restore deleted KB files from git if count dropped vs checkpoint
-  try {
-    const checkpoint = safeJson(path.join(ENGINE_DIR, 'kb-checkpoint.json'));
-    if (checkpoint && checkpoint.count > 0) {
-      const { KB_CATEGORIES: cats } = shared;
-      const knowledgeDir = path.join(MINIONS_DIR, 'knowledge');
-      let current = 0;
-      for (const cat of cats) {
-        const d = path.join(knowledgeDir, cat);
-        if (fs.existsSync(d)) current += fs.readdirSync(d).length;
-      }
-      if (current < checkpoint.count) {
-        log('warn', `KB watchdog: file count dropped ${checkpoint.count} → ${current}, restoring from git`);
-        try {
-          const trackedCheck = execSilent('git ls-tree --name-only HEAD -- knowledge', { cwd: MINIONS_DIR }).toString().trim();
-          if (!trackedCheck) {
-            log('warn', 'KB watchdog: knowledge/ is not tracked in git HEAD — skipping restore');
-          } else {
-            execSilent('git checkout HEAD -- knowledge', { cwd: MINIONS_DIR });
-            log('info', 'KB watchdog: restored knowledge/ from git HEAD');
-          }
-        } catch (err) {
-          log('error', `KB watchdog: git restore failed — ${err.message}`);
-        }
-      }
-    }
-  } catch (e) { log('warn', 'KB watchdog check: ' + e.message); }
-
-  // 6. Migrate legacy work-item statuses to canonical values
-  // in-pr, implemented, complete → done (one-time correction per item)
-  const LEGACY_DONE_STATUSES = new Set(['in-pr', 'implemented', 'complete']);
-  for (const project of projects) {
-    try {
-      const wiPath = projectWorkItemsPath(project);
-      const items = safeJson(wiPath) || [];
-      let migrated = 0;
-      for (const item of items) {
-        if (LEGACY_DONE_STATUSES.has(item.status)) {
-          item.status = 'done';
-          migrated++;
-        }
-      }
-      if (migrated > 0) {
-        safeWrite(wiPath, items);
-        log('info', `Migrated ${migrated} legacy status(es) → done in ${project.name} work items`);
-      }
-    } catch (e) { log('warn', 'migrate legacy statuses: ' + e.message); }
-  }
-  // Central work items
-  try {
-    const centralPath = path.join(MINIONS_DIR, 'work-items.json');
-    const centralItems = safeJson(centralPath) || [];
-    let migrated = 0;
-    for (const item of centralItems) {
-      if (LEGACY_DONE_STATUSES.has(item.status)) {
-        item.status = 'done';
-        migrated++;
-      }
-    }
-    if (migrated > 0) {
-      safeWrite(centralPath, centralItems);
-      log('info', `Migrated ${migrated} legacy status(es) → done in central work items`);
-    }
-  } catch (e) { log('warn', 'migrate central legacy statuses: ' + e.message); }
-  // PRD items (missing_features[].status)
-  try {
-    const prdFiles = fs.readdirSync(PRD_DIR).filter(f => f.endsWith('.json'));
-    for (const pf of prdFiles) {
-      const prdPath = path.join(PRD_DIR, pf);
-      const prd = safeJson(prdPath);
-      if (!prd?.missing_features) continue;
-      let migrated = 0;
-      for (const feat of prd.missing_features) {
-        if (LEGACY_DONE_STATUSES.has(feat.status)) {
-          feat.status = 'done';
-          migrated++;
-        }
-      }
-      if (migrated > 0) {
-        safeWrite(prdPath, prd);
-        log('info', `Migrated ${migrated} legacy PRD item status(es) → done in ${pf}`);
-      }
-    }
-  } catch (e) { log('warn', 'migrate PRD legacy statuses: ' + e.message); }
-
-  return cleaned;
-}
+// runCleanup — now in engine/cleanup.js
 
 // ─── Cooldowns (extracted to engine/cooldown.js) ─────────────────────────────
 
@@ -2992,8 +2256,8 @@ module.exports = {
   getAgentStatus, getAgentCharter, getInboxFiles, getPrs,
   validateConfig,
 
-  // Dispatch management
-  addToDispatch, completeDispatch,
+  // Dispatch management (re-exported from engine/dispatch.js)
+  mutateDispatch, addToDispatch, isRetryableFailureReason, completeDispatch, writeInboxAlert,
   activeProcesses, get engineRestartGraceUntil() { return engineRestartGraceUntil; },
   set engineRestartGraceUntil(v) { engineRestartGraceUntil = v; },
 
@@ -3005,13 +2269,19 @@ module.exports = {
   materializePlansAsWorkItems,
 
   // Shared helpers (used by lifecycle.js and tests)
-  reconcileItemsWithPrs, writeInboxAlert, detectDependencyCycles,
+  reconcileItemsWithPrs, detectDependencyCycles,
 
   // Playbooks
   renderPlaybook,
 
+  // Timeout / Steering / Idle (re-exported from engine/timeout.js)
+  checkTimeouts, checkSteering, checkIdleThreshold,
+
+  // Cleanup (re-exported from engine/cleanup.js)
+  runCleanup,
+
   // Post-completion / lifecycle
-  updateWorkItemStatus, runCleanup, handlePostMerge,
+  updateWorkItemStatus, handlePostMerge,
 
   // Cooldowns
   loadCooldowns, setCooldownWithContext, getCoalescedContexts,