@yemi33/minions 0.1.59 → 0.1.61

package/engine.js

@@ -106,533 +106,37 @@ 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 });
-}
-
-// ─── State Readers (delegated to engine/queries.js) ─────────────────────────
-
-const { getConfig, getControl, getDispatch, getNotes,
-  getAgentStatus, getAgentCharter, getInboxFiles,
-  collectSkillFiles, getSkillIndex, getKnowledgeBaseIndex,
-  getPrs, SKILLS_DIR } = queries;
-
-function getRouting() {
-  return safeRead(ROUTING_PATH);
-}
-
-// ─── Routing Parser ─────────────────────────────────────────────────────────
-
-let _routingCache = null;
-let _routingCacheMtime = 0;
-
-function parseRoutingTable() {
-  const content = getRouting();
-  const routes = {};
-  const lines = content.split('\n');
-  let inTable = false;
-
-  for (const line of lines) {
-    if (line.startsWith('| Work Type')) { inTable = true; continue; }
-    if (line.startsWith('|---')) continue;
-    if (!inTable || !line.startsWith('|')) {
-      if (inTable && !line.startsWith('|')) inTable = false;
-      continue;
-    }
-    const cells = line.split('|').map(c => c.trim()).filter(Boolean);
-    if (cells.length >= 3) {
-      routes[cells[0].toLowerCase()] = {
-        preferred: cells[1].toLowerCase(),
-        fallback: cells[2].toLowerCase()
-      };
-    }
-  }
-  return routes;
-}
-
-function getRoutingTableCached() {
-  let mtime = 0;
-  try { mtime = fs.statSync(ROUTING_PATH).mtimeMs; } catch { /* optional */ }
-  if (_routingCache && _routingCacheMtime === mtime) return _routingCache;
-  _routingCache = parseRoutingTable();
-  _routingCacheMtime = mtime;
-  return _routingCache;
-}
-
-function getMonthlySpend(agentId) {
-  const metrics = safeJson(path.join(ENGINE_DIR, 'metrics.json')) || {};
-  const daily = metrics._daily || {};
-  const now = new Date();
-  const monthPrefix = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
-  let total = 0;
-  for (const [date, data] of Object.entries(daily)) {
-    if (date.startsWith(monthPrefix)) {
-      total += (data.perAgent?.[agentId]?.costUsd || 0);
-    }
-  }
-  // Fallback: if no per-agent daily data, use cumulative (less accurate for monthly)
-  if (total === 0 && metrics[agentId]?.totalCostUsd) {
-    // Can't distinguish monthly from cumulative — treat as monthly estimate
-    // This path is for backward compat before per-agent daily tracking was added
-  }
-  return total;
-}
-
-function getAgentErrorRate(agentId) {
-  const metricsPath = path.join(ENGINE_DIR, 'metrics.json');
-  const metrics = safeJson(metricsPath) || {};
-  const m = metrics[agentId];
-  if (!m) return 0;
-  const total = m.tasksCompleted + m.tasksErrored;
-  return total > 0 ? m.tasksErrored / total : 0;
-}
-
-function isAgentIdle(agentId) {
-  // Dispatch queue is the single source of truth for agent availability
-  const dispatch = safeJson(DISPATCH_PATH) || {};
-  return !(dispatch.active || []).some(d => d.agent === agentId);
-}
-
-// Track agents claimed during a single discovery pass to distribute work
-const _claimedAgents = new Set();
-function resetClaimedAgents() { _claimedAgents.clear(); }
-
-function resolveAgent(workType, config, authorAgent = null) {
-  const routes = getRoutingTableCached();
-  const route = routes[workType] || routes['implement'];
-  const agents = config.agents || {};
-
-  // Resolve _author_ token
-  let preferred = route.preferred === '_author_' ? authorAgent : route.preferred;
-  let fallback = route.fallback === '_author_' ? authorAgent : route.fallback;
-
-  const isAvailable = (id) => {
-    if (!agents[id] || !isAgentIdle(id) || _claimedAgents.has(id)) return false;
-    // Budget check — no budget means infinite (no limit)
-    const budget = agents[id].monthlyBudgetUsd;
-    if (budget && budget > 0) {
-      if (getMonthlySpend(id) >= budget) return false;
-    }
-    return true;
-  };
-
-  // Check preferred and fallback first (routing table order)
-  if (preferred && isAvailable(preferred)) { _claimedAgents.add(preferred); return preferred; }
-  if (fallback && isAvailable(fallback)) { _claimedAgents.add(fallback); return fallback; }
-
-  // Fall back to any idle agent, preferring lower error rates
-  const idle = Object.keys(agents)
-    .filter(id => id !== preferred && id !== fallback && isAvailable(id))
-    .sort((a, b) => getAgentErrorRate(a) - getAgentErrorRate(b));
-
-  if (idle[0]) { _claimedAgents.add(idle[0]); return idle[0]; }
-
-  // No idle configured agent — try temp agent if enabled
-  if (config.engine?.allowTempAgents) {
-    const tempId = `temp-${shared.uid()}`;
-    _claimedAgents.add(tempId);
-    tempAgents.set(tempId, { name: `Temp-${tempId.slice(5, 9)}`, role: 'Temporary Agent', createdAt: ts() });
-    log('info', `Spawning temp agent ${tempId} — all permanent agents busy`);
-    return tempId;
-  }
-
-  // No idle agent available — return null, item stays pending until next tick
-  return null;
-}
-
-// ─── Task Context Resolution ────────────────────────────────────────────────
-// Resolves implicit references in task descriptions (e.g., "ripley's plan",
-// "dallas's PR") to actual artifacts and injects their content.
-
-function resolveTaskContext(item, config) {
-  const title = (item.title || '').toLowerCase();
-  const desc = (item.description || '').toLowerCase();
-  const text = title + ' ' + desc;
-  const agentNames = Object.entries(config.agents || {}).map(([id, a]) => ({
-    id,
-    name: (a.name || id).toLowerCase(),
-  }));
-  const resolved = { additionalContext: '', referencedFiles: [] };
-
-  // Match agent references: "ripley's plan", "dallas's pr", "lambert's output", etc.
-  for (const agent of agentNames) {
-    const patterns = [
-      new RegExp(`${agent.name}(?:'s|s)?\\s+plan`, 'i'),
-      new RegExp(`${agent.id}(?:'s|s)?\\s+plan`, 'i'),
-      new RegExp(`plan\\s+(?:created|made|written|generated)\\s+by\\s+${agent.name}`, 'i'),
-      new RegExp(`plan\\s+(?:created|made|written|generated)\\s+by\\s+${agent.id}`, 'i'),
-    ];
-    const matchesPlan = patterns.some(p => p.test(text));
-    if (matchesPlan) {
-      // Find plans created by this agent (check work items for plan tasks dispatched to this agent)
-      try {
-        const plans = fs.readdirSync(path.join(MINIONS_DIR, 'plans')).filter(f => f.endsWith('.md') || f.endsWith('.json'));
-        // Check work-items to find which plan file this agent created
-        const workItems = safeJson(path.join(MINIONS_DIR, 'work-items.json')) || [];
-        const agentPlanItems = workItems.filter(w =>
-          w.type === 'plan' && w.dispatched_to === agent.id && w.status === 'done' && w._planFileName
-        ).sort((a, b) => (b.completedAt || '').localeCompare(a.completedAt || ''));
-
-        if (agentPlanItems.length > 0) {
-          const planFile = agentPlanItems[0]._planFileName;
-          const planPath = path.join(MINIONS_DIR, 'plans', planFile);
-          try {
-            const content = safeRead(planPath);
-            resolved.additionalContext += `\n\n## Referenced Plan: ${planFile} (created by ${agent.name})\n\n${content}`;
-            resolved.referencedFiles.push(planPath);
-            log('info', `Context resolution: found plan "${planFile}" by ${agent.name} for work item ${item.id}`);
-          } catch (e) { log('warn', 'resolve plan context: ' + e.message); }
-        } else if (plans.length > 0) {
-          // Fallback: try to find a plan file with the agent's name or ID in it
-          const match = plans.find(f => f.toLowerCase().includes(agent.id) || f.toLowerCase().includes(agent.name));
-          if (match) {
-            const planPath = path.join(MINIONS_DIR, 'plans', match);
-            try {
-              const content = safeRead(planPath);
-              resolved.additionalContext += `\n\n## Referenced Plan: ${match}\n\n${content}`;
-              resolved.referencedFiles.push(planPath);
-              log('info', `Context resolution: found plan "${match}" (name match) for work item ${item.id}`);
-            } catch (e) { log('warn', 'resolve plan fallback context: ' + e.message); }
-          }
-        }
-      } catch (e) { log('warn', 'resolve agent plan context: ' + e.message); }
-    }
-
-    // Match agent output/notes references
-    const outputPatterns = [
-      new RegExp(`${agent.name}(?:'s|s)?\\s+(?:output|findings|notes|results)`, 'i'),
-      new RegExp(`(?:output|findings|notes|results)\\s+(?:from|by)\\s+${agent.name}`, 'i'),
-    ];
-    if (outputPatterns.some(p => p.test(text))) {
-      // Find the agent's latest inbox notes
-      try {
-        const inboxDir = path.join(MINIONS_DIR, 'notes', 'inbox');
-        const files = fs.readdirSync(inboxDir)
-          .filter(f => f.startsWith(agent.id + '-'))
-          .sort().reverse();
-        if (files.length > 0) {
-          const content = safeRead(path.join(inboxDir, files[0]));
-          resolved.additionalContext += `\n\n## Referenced Notes by ${agent.name}: ${files[0]}\n\n${content.slice(0, 5000)}`;
-          resolved.referencedFiles.push(path.join(inboxDir, files[0]));
-          log('info', `Context resolution: found notes "${files[0]}" by ${agent.name} for work item ${item.id}`);
-        }
-      } catch (e) { log('warn', 'resolve plan context outer: ' + e.message); }
-    }
-  }
-
-  // If no specific reference was resolved but the text mentions "the plan" or "latest plan",
-  // find the most recent plan
-  if (!resolved.additionalContext && /\b(the|latest|last|recent)\s+plan\b/i.test(text)) {
-    try {
-      const plans = fs.readdirSync(path.join(MINIONS_DIR, 'plans'))
-        .filter(f => f.endsWith('.md') || f.endsWith('.json'))
-        .sort().reverse();
-      if (plans.length > 0) {
-        const planPath = path.join(MINIONS_DIR, 'plans', plans[0]);
-        const content = safeRead(planPath);
-        resolved.additionalContext += `\n\n## Referenced Plan (latest): ${plans[0]}\n\n${content}`;
-        resolved.referencedFiles.push(planPath);
-        log('info', `Context resolution: using latest plan "${plans[0]}" for work item ${item.id}`);
-      }
-    } catch (e) { log('warn', 'resolve latest plan context: ' + e.message); }
-  }
-
-  return resolved;
-}
-
-// ─── Playbook Renderer ──────────────────────────────────────────────────────
-
-function renderPlaybook(type, vars) {
-  const pbPath = path.join(PLAYBOOKS_DIR, `${type}.md`);
-  let content;
-  try { content = fs.readFileSync(pbPath, 'utf8'); } catch {
-    log('warn', `Playbook not found: ${type}`);
-    return null;
-  }
-
-  // Inject pinned context (always visible to agents) — capped at 4KB
-  let pinnedContent = '';
-  try { pinnedContent = fs.readFileSync(path.join(MINIONS_DIR, 'pinned.md'), 'utf8'); } catch { /* optional */ }
-  if (pinnedContent) {
-    if (pinnedContent.length > 4096) pinnedContent = pinnedContent.slice(0, 4096) + '\n\n_...pinned.md truncated (read full file if needed)_';
-    content += '\n\n---\n\n## Pinned Context (CRITICAL — READ FIRST)\n\n' + pinnedContent;
-  }
+// ─── Dispatch Management (extracted to engine/dispatch.js) ───────────────────
 
-  // Inject team notes (single injection point — not in buildAgentContext) — capped at 8KB
-  let notes = getNotes();
-  if (notes) {
-    if (notes.length > 8192) {
-      const sections = notes.split(/(?=^### )/m);
-      const recent = sections.slice(-10).join('');
-      notes = recent.length > 8192 ? recent.slice(0, 8192) + '\n\n_...notes truncated_' : recent;
-      notes += '\n\n_' + Math.max(0, sections.length - 10) + ' older entries in `notes.md` — Read if needed._';
-    }
-    content += '\n\n---\n\n## Team Notes (MUST READ)\n\n' + notes;
-  }
+const { mutateDispatch, addToDispatch, isRetryableFailureReason, completeDispatch,
+  writeInboxAlert } = require('./engine/dispatch');
 
-  // Inject KB guardrail
-  content += `\n\n---\n\n## Knowledge Base Rules\n\n`;
-  content += `**Never delete, move, or overwrite files in \`knowledge/\`.** The sweep (consolidation engine) is the only process that writes to \`knowledge/\`. If you think a KB file is wrong, note it in your learnings file — do not touch \`knowledge/\` directly.\n`;
-
-  // Inject learnings requirement
-  content += `\n\n---\n\n## REQUIRED: Write Learnings\n\n`;
-  content += `After completing your task, you MUST write a findings/learnings file to:\n`;
-  content += `\`${MINIONS_DIR}/notes/inbox/${vars.agent_id || 'agent'}-${dateStamp()}.md\`\n\n`;
-  content += `Include:\n`;
-  content += `- What you learned about the codebase\n`;
-  content += `- Patterns you discovered or established\n`;
-  content += `- Gotchas or warnings for future agents\n`;
-  content += `- Conventions to follow\n`;
-  content += `- **SOURCE REFERENCES for every finding** — file paths with line numbers, PR URLs, API endpoints, config keys. Format: \`(source: path/to/file.ts:42)\` or \`(source: PR-12345)\`. Without references, findings cannot be verified.\n\n`;
-  content += `### Skill Extraction (IMPORTANT)\n\n`;
-  content += `If during this task you discovered a **repeatable workflow** — a multi-step procedure, workaround, build process, or pattern that other agents should follow in similar situations — output it as a fenced skill block. The engine will automatically extract it.\n\n`;
-  content += `Format your skill as a fenced code block with the \`skill\` language tag:\n\n`;
-  content += '````\n```skill\n';
-  content += `---\nname: short-descriptive-name\ndescription: One-line description of what this skill does\nallowed-tools: Bash, Read, Edit\ntrigger: when should an agent use this\nscope: minions\nproject: any\n---\n\n# Skill Title\n\n## Steps\n1. ...\n2. ...\n\n## Notes\n...\n`;
-  content += '```\n````\n\n';
-  content += `- Set \`scope: minions\` for cross-project skills (engine writes to ~/.claude/skills/ automatically)\n`;
-  content += `- Set \`scope: project\` + \`project: <name>\` for repo-specific skills (engine queues a PR to <project>/.claude/skills/)\n`;
-  content += `- Only output a skill block if you genuinely discovered something reusable — don't force it\n`;
-
-  // Inject project-level variables from config
-  const config = getConfig();
-  const projects = getProjects(config);
-  // Find the specific project being dispatched (match by repo_id or repo_name from vars)
-  const dispatchProject = (vars.repo_id && projects.find(p => p.repositoryId === vars.repo_id))
-    || (vars.repo_name && projects.find(p => p.repoName === vars.repo_name))
-    || projects[0] || {};
-  const projectVars = {
-    project_name: dispatchProject.name || 'Unknown Project',
-    ado_org: dispatchProject.adoOrg || 'Unknown',
-    ado_project: dispatchProject.adoProject || 'Unknown',
-    repo_name: dispatchProject.repoName || 'Unknown',
-    pr_create_instructions: getPrCreateInstructions(dispatchProject),
-    pr_comment_instructions: getPrCommentInstructions(dispatchProject),
-    pr_fetch_instructions: getPrFetchInstructions(dispatchProject),
-    pr_vote_instructions: getPrVoteInstructions(dispatchProject),
-    repo_host_label: getRepoHostLabel(dispatchProject),
-  };
-  const allVars = { ...projectVars, ...vars };
-
-  // Substitute variables
-  for (const [key, val] of Object.entries(allVars)) {
-    content = content.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), String(val));
-  }
+// ─── Timeout / Steering / Idle (extracted to engine/timeout.js) ──────────────
 
-  return content;
-}
+const { checkTimeouts, checkSteering, checkIdleThreshold } = require('./engine/timeout');
 
-// ─── Repo Host Helpers ──────────────────────────────────────────────────────
+// ─── Cleanup (extracted to engine/cleanup.js) ────────────────────────────────
 
-function getRepoHost(project) {
-  return project?.repoHost || 'ado';
-}
-
-function getPrCreateInstructions(project) {
-  const host = getRepoHost(project);
-  const repoId = project?.repositoryId || '';
-  if (host === 'github') {
-    const org = project?.adoOrg || '';
-    const repo = project?.repoName || '';
-    const mainBranch = project?.mainBranch || 'main';
-    return `Use \`gh pr create\` to create a pull request:\n` +
-      `- \`gh pr create --base ${mainBranch} --head <your-branch> --title "PR title" --body "PR description" --repo ${org}/${repo}\`\n` +
-      `- Always set --base to \`${mainBranch}\` (the main branch)\n` +
-      `- Always set --repo to \`${org}/${repo}\` to target the correct repository\n` +
-      `- Use --head to specify your feature branch name\n` +
-      `- Include a meaningful --title and --body describing the changes`;
-  }
-  // Default: Azure DevOps
-  return `Use \`mcp__azure-ado__repo_create_pull_request\`:\n- repositoryId: \`${repoId}\``;
-}
-
-function getPrCommentInstructions(project) {
-  const host = getRepoHost(project);
-  const repoId = project?.repositoryId || '';
-  if (host === 'github') {
-    const org = project?.adoOrg || '';
-    const repo = project?.repoName || '';
-    return `Use \`gh pr comment\` to post a comment on the PR:\n` +
-      `- \`gh pr comment <number> --body "Your comment text" --repo ${org}/${repo}\`\n` +
-      `- Replace <number> with the PR number\n` +
-      `- Always set --repo to \`${org}/${repo}\` to target the correct repository\n` +
-      `- Use --body to provide the comment text (supports Markdown)`;
-  }
-  return `Use \`mcp__azure-ado__repo_create_pull_request_thread\`:\n- repositoryId: \`${repoId}\``;
-}
-
-function getPrFetchInstructions(project) {
-  const host = getRepoHost(project);
-  if (host === 'github') {
-    const org = project?.adoOrg || '';
-    const repo = project?.repoName || '';
-    const mainBranch = project?.mainBranch || 'main';
-    return `Use \`gh pr view\` to fetch PR status:\n` +
-      `- \`gh pr view <number> --json number,title,state,mergeable,reviewDecision,headRefName,baseRefName,statusCheckRollup --repo ${org}/${repo}\`\n` +
-      `- This returns JSON with PR state, mergeability, review decision, and check statuses\n` +
-      `- To fetch the PR branch locally:\n` +
-      `  1. \`git fetch origin <branch-name>\`\n` +
-      `  2. \`git checkout <branch-name>\`\n` +
-      `- Or use \`gh pr checkout <number> --repo ${org}/${repo}\` to fetch and checkout in one step\n` +
-      `- The base branch is \`${mainBranch}\``;
-  }
-  return `Use \`mcp__azure-ado__repo_get_pull_request_by_id\` to fetch PR status.`;
-}
-
-function getPrVoteInstructions(project) {
-  const host = getRepoHost(project);
-  const repoId = project?.repositoryId || '';
-  if (host === 'github') {
-    const org = project?.adoOrg || '';
-    const repo = project?.repoName || '';
-    return `Use \`gh pr review\` to submit a review on the PR:\n` +
-      `- Approve: \`gh pr review <number> --approve --body "Approval comment" --repo ${org}/${repo}\`\n` +
-      `- Request changes: \`gh pr review <number> --request-changes --body "What needs to change" --repo ${org}/${repo}\`\n` +
-      `- Comment only: \`gh pr review <number> --comment --body "Review comment" --repo ${org}/${repo}\`\n` +
-      `- Replace <number> with the PR number\n` +
-      `- Always set --repo to \`${org}/${repo}\` to target the correct repository\n` +
-      `- Use --body to provide a review summary (supports Markdown)`;
-  }
-  return `Use \`mcp__azure-ado__repo_update_pull_request_reviewers\`:\n- repositoryId: \`${repoId}\`\n- Set your reviewer vote on the PR (10=approve, 5=approve-with-suggestions, -10=reject)`;
-}
-
-function getRepoHostLabel(project) {
-  const host = getRepoHost(project);
-  if (host === 'github') return 'GitHub';
-  return 'Azure DevOps';
-}
-
-function getRepoHostToolRule(project) {
-  const host = getRepoHost(project);
-  if (host === 'github') return 'Use GitHub MCP tools or `gh` CLI for PR operations';
-  return 'Use Azure DevOps MCP tools (mcp__azure-ado__*) for PR operations — NEVER use gh CLI';
-}
-
-// ─── System Prompt Builder ──────────────────────────────────────────────────
-
-// Lean system prompt: agent identity + rules only (~2-4KB, never grows)
-function buildSystemPrompt(agentId, config, project) {
-  const agent = config.agents[agentId] || tempAgents.get(agentId) || { name: agentId, role: 'Temporary Agent', skills: [] };
-  const charter = getAgentCharter(agentId); // returns '' for temp agents (no charter file)
-  project = project || getProjects(config)[0] || {};
-
-  let prompt = '';
-
-  // Agent identity
-  prompt += `# You are ${agent.name} (${agent.role})\n\n`;
-  prompt += `Agent ID: ${agentId}\n`;
-  prompt += `Skills: ${(agent.skills || []).join(', ')}\n\n`;
-
-  // Charter (detailed instructions — typically 1-2KB)
-  if (charter) {
-    prompt += `## Your Charter\n\n${charter}\n\n`;
-  }
+const { runCleanup } = require('./engine/cleanup');
 
-  // Project context (fixed size)
-  prompt += `## Project: ${project.name || 'Unknown Project'}\n\n`;
-  prompt += `- Repo: ${project.repoName || 'Unknown'} (${project.adoOrg || 'Unknown'}/${project.adoProject || 'Unknown'})\n`;
-  prompt += `- Repo ID: ${project.repositoryId || ''}\n`;
-  prompt += `- Repo host: ${getRepoHostLabel(project)}\n`;
-  prompt += `- Main branch: ${project.mainBranch || 'main'}\n\n`;
-
-  // Critical rules (fixed size)
-  prompt += `## Critical Rules\n\n`;
-  prompt += `1. Use git worktrees — NEVER checkout on main working tree\n`;
-  prompt += `2. ${getRepoHostToolRule(project)}\n`;
-  prompt += `3. Follow the project conventions in CLAUDE.md if present\n`;
-  prompt += `4. Write learnings to: ${MINIONS_DIR}/notes/inbox/${agentId}-${dateStamp()}.md\n`;
-  prompt += `5. Agent status is managed by the engine via dispatch.json — agents do not need to track their own status\n`;
-  prompt += `6. If you discover a repeatable workflow, output it as a \\\`\\\`\\\`skill fenced block — the engine auto-extracts it to ~/.claude/skills/\n\n`;
-
-  return prompt;
-}
-
-// Bulk context: history, notes, conventions, skills — prepended to user/task prompt.
-// This is the content that grows over time and would bloat the system prompt.
-function buildAgentContext(agentId, config, project) {
-  project = project || getProjects(config)[0] || {};
-  let context = '';
-
-  // Agent history — last 5 tasks only (keeps it relevant, avoids 37KB dumps)
-  const history = safeRead(path.join(AGENTS_DIR, agentId, 'history.md'));
-  if (history && history.trim() !== '# Agent History') {
-    const entries = history.split(/(?=^### )/m);
-    const header = entries[0].startsWith('#') && !entries[0].startsWith('### ') ? entries.shift() : '';
-    const recent = entries.slice(-5);
-    const trimmed = (header ? header + '\n' : '') + recent.join('');
-    context += `## Your Recent History (last 5 tasks)\n\n${trimmed}\n\n`;
-  }
+// ─── State Readers (delegated to engine/queries.js) ─────────────────────────
 
-  // Project conventions (from CLAUDE.md) — always relevant for code quality
-  if (project.localPath) {
-    const claudeMd = safeRead(path.join(project.localPath, 'CLAUDE.md'));
-    if (claudeMd && claudeMd.trim()) {
-      const truncated = claudeMd.length > 8192 ? claudeMd.slice(0, 8192) + '\n\n...(truncated)' : claudeMd;
-      context += `## Project Conventions (from CLAUDE.md)\n\n${truncated}\n\n`;
-    }
-  }
+const { getConfig, getControl, getDispatch, getNotes,
+  getAgentStatus, getAgentCharter, getInboxFiles,
+  collectSkillFiles, getSkillIndex, getKnowledgeBaseIndex,
+  getPrs, SKILLS_DIR } = queries;
 
-  // KB and skills: NOT injected — agents can Glob/Read when needed
-  // This saves ~27KB per dispatch. Reference note so agents know they exist:
-  context += `## Reference Files\n\nKnowledge base entries are in \`knowledge/{category}/*.md\`. Skills are in \`skills/*.md\` and \`.claude/skills/\`. Use Glob/Read to browse when relevant.\n\n`;
+// ─── Routing (extracted to engine/routing.js) ───────────────────────────────
 
-  // Minions awareness: what's in flight, who's doing what
-  const dispatch = getDispatch();
-  const activeItems = (dispatch.active || []).map(d =>
-    `- **${d.agent}**: ${d.type} — ${(d.task || '').slice(0, 100)}${d.agent === agentId ? ' ← (you)' : ''}`
-  );
-  if (activeItems.length > 0) {
-    context += `## Active Agents\n\n${activeItems.join('\n')}\n\n`;
-  }
+const { getRouting, parseRoutingTable, getRoutingTableCached, getMonthlySpend,
+  getAgentErrorRate, isAgentIdle, resolveAgent, resetClaimedAgents,
+  tempAgents } = require('./engine/routing');
 
-  // Recent completions (last 5, not 10)
-  const recentCompleted = (dispatch.completed || []).slice(-5).reverse().map(d =>
-    `- **${d.agent}** ${d.result === 'success' ? 'completed' : 'failed'}: ${(d.task || '').slice(0, 80)}${d.resultSummary ? ' — ' + d.resultSummary.slice(0, 100) : ''}`
-  );
-  if (recentCompleted.length > 0) {
-    context += `## Recently Completed\n\n${recentCompleted.join('\n')}\n\n`;
-  }
+// ─── Playbook, system prompt, agent context (extracted to engine/playbook.js) ─
 
-  // Active + linked PRs across projects — coordination awareness
-  const projects = getProjects(config);
-  const allPrs = [];
-  for (const p of projects) {
-    const prs = getPrs(p).filter(pr => pr.status === 'active' || pr.status === 'linked');
-    for (const pr of prs) allPrs.push({ ...pr, _project: p.name });
-  }
-  // Also check central pull-requests.json
-  try {
-    const centralPrs = safeJson(path.join(MINIONS_DIR, 'pull-requests.json')) || [];
-    for (const pr of centralPrs.filter(pr => pr.status === 'active' || pr.status === 'linked')) {
-      if (!allPrs.some(p => p.id === pr.id)) allPrs.push({ ...pr, _project: 'central' });
-    }
-  } catch (e) { log('warn', 'read central pull-requests: ' + e.message); }
-  if (allPrs.length > 0) {
-    const prLines = allPrs.map(pr =>
-      `- **${pr.id}** (${pr._project}): ${(pr.title || '').slice(0, 80)} [${pr.status === 'linked' ? 'context-only' : (pr.reviewStatus || 'pending')}${pr.buildStatus === 'failing' ? ', BUILD FAILING' : ''}]${pr.branch ? ' branch: `' + pr.branch + '`' : ''}${pr._context ? ' — ' + pr._context.slice(0, 100) : ''}`
-    );
-    context += `## Active Pull Requests\n\n${prLines.join('\n')}\n\n`;
-  }
-
-  // Pending work items
-  const pendingItems = (dispatch.pending || []).slice(0, 10).map(d =>
-    `- ${d.type}: ${(d.task || '').slice(0, 80)}`
-  );
-  if (pendingItems.length > 0) {
-    context += `## Pending Work Queue (${(dispatch.pending || []).length} items)\n\n${pendingItems.join('\n')}${(dispatch.pending || []).length > 10 ? '\n- ... and ' + ((dispatch.pending || []).length - 10) + ' more' : ''}\n\n`;
-  }
-
-  // Team notes injected via renderPlaybook (single injection point, with truncation)
-  // Not duplicated here to avoid double-injection and token waste
-
-  return context;
-}
+const { renderPlaybook, buildSystemPrompt, buildAgentContext, selectPlaybook,
+  buildBaseVars, buildPrDispatch, resolveTaskContext,
+  getRepoHostLabel, getRepoHostToolRule } = require('./engine/playbook');
 
 // sanitizeBranch imported from shared.js
 
@@ -645,7 +149,7 @@ const { runPostCompletionHooks, updateWorkItemStatus, syncPrdItemStatus, handleP
 // ─── Agent Spawner ──────────────────────────────────────────────────────────
 
 const activeProcesses = new Map(); // dispatchId → { proc, agentId, startedAt }
-const tempAgents = new Map(); // tempAgentId → { name, role, createdAt }
+// tempAgents imported from engine/routing.js
 let engineRestartGraceUntil = 0; // timestamp — suppress orphan detection until this time
 
 // Resolve dependency plan item IDs to their PR branches
@@ -1213,147 +717,9 @@ function spawnAgent(dispatchItem, config) {
   return proc;
 }
 
-// ─── Dispatch Management ────────────────────────────────────────────────────
-
-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));
-}
+// addToDispatch, isRetryableFailureReason — now in engine/dispatch.js
 
-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)
@@ -1409,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
@@ -1492,690 +847,15 @@ 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);
-    }
-  }
-
-  // 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();
+// checkIdleThreshold, checkSteering, checkTimeouts — now in engine/timeout.js
 
-      for (const dir of dirs) {
-        const wtPath = path.join(worktreeRoot, dir);
-        try { if (!fs.statSync(wtPath).isDirectory()) continue; } catch { continue; }
+// runCleanup — now in engine/cleanup.js
 
-        let shouldClean = false;
-        let isProtected = false;
+// ─── Cooldowns (extracted to engine/cooldown.js) ─────────────────────────────
 
-        // 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;
-}
-
-// ─── Work Discovery ─────────────────────────────────────────────────────────
-
-const COOLDOWN_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
-const dispatchCooldowns = new Map(); // key → { timestamp, failures }
-
-function loadCooldowns() {
-  const saved = safeJson(COOLDOWN_PATH);
-  if (!saved) return;
-  const now = Date.now();
-  for (const [k, v] of Object.entries(saved)) {
-    // Prune entries older than 24 hours
-    if (now - v.timestamp < 24 * 60 * 60 * 1000) {
-      dispatchCooldowns.set(k, v);
-    }
-  }
-  log('info', `Loaded ${dispatchCooldowns.size} cooldowns from disk`);
-}
-
-let _cooldownWriteTimer = null;
-function saveCooldowns() {
-  // Debounce: reset timer on each call so latest state is always written
-  if (_cooldownWriteTimer) clearTimeout(_cooldownWriteTimer);
-  _cooldownWriteTimer = setTimeout(() => {
-    _cooldownWriteTimer = null;
-    // Prune expired entries (>24h) before saving
-    const now = Date.now();
-    for (const [k, v] of dispatchCooldowns) {
-      if (now - v.timestamp > 24 * 60 * 60 * 1000) dispatchCooldowns.delete(k);
-    }
-    const obj = Object.fromEntries(dispatchCooldowns);
-    safeWrite(COOLDOWN_PATH, obj);
-  }, 1000); // debounce — write at most once per second
-}
-
-function isOnCooldown(key, cooldownMs) {
-  const entry = dispatchCooldowns.get(key);
-  if (!entry) return false;
-  const backoff = Math.min(Math.pow(2, entry.failures || 0), 8);
-  return (Date.now() - entry.timestamp) < (cooldownMs * backoff);
-}
-
-function setCooldown(key) {
-  const existing = dispatchCooldowns.get(key);
-  dispatchCooldowns.set(key, { timestamp: Date.now(), failures: existing?.failures || 0 });
-  saveCooldowns();
-}
-
-function setCooldownWithContext(key, context) {
-  const existing = dispatchCooldowns.get(key);
-  const pendingContexts = existing?.pendingContexts || [];
-  if (context) pendingContexts.push(context);
-  dispatchCooldowns.set(key, {
-    timestamp: Date.now(),
-    failures: existing?.failures || 0,
-    pendingContexts
-  });
-  saveCooldowns();
-}
-
-function getCoalescedContexts(key) {
-  const entry = dispatchCooldowns.get(key);
-  const contexts = entry?.pendingContexts || [];
-  if (contexts.length > 0 && entry) {
-    entry.pendingContexts = []; // Clear after retrieval
-  }
-  return contexts;
-}
-
-function setCooldownFailure(key) {
-  const existing = dispatchCooldowns.get(key);
-  const failures = (existing?.failures || 0) + 1;
-  dispatchCooldowns.set(key, { timestamp: Date.now(), failures });
-  if (failures >= 3) {
-    log('warn', `${key} has failed ${failures} times — cooldown is now ${Math.min(Math.pow(2, failures), 8)}x`);
-  }
-  saveCooldowns();
-}
-
-function isAlreadyDispatched(key) {
-  const dispatch = getDispatch();
-  // Check pending and active
-  const inFlight = [...dispatch.pending, ...(dispatch.active || [])];
-  if (inFlight.some(d => d.meta?.dispatchKey === key)) return true;
-  // Also check recently completed (last hour) to prevent re-dispatch
-  const oneHourAgo = Date.now() - 3600000;
-  const recentCompleted = (dispatch.completed || []).filter(d =>
-    d.completed_at && new Date(d.completed_at).getTime() > oneHourAgo
-  );
-  return recentCompleted.some(d => d.meta?.dispatchKey === key);
-}
+const { COOLDOWN_PATH, dispatchCooldowns, loadCooldowns, saveCooldowns,
+  isOnCooldown, setCooldown, setCooldownWithContext, getCoalescedContexts,
+  setCooldownFailure, isAlreadyDispatched } = require('./engine/cooldown');
 
 
 
@@ -2507,50 +1187,7 @@ function materializePlansAsWorkItems(config) {
   }
 }
 
-// ─── Work Discovery Helpers ──────────────────────────────────────────────────
-
-function buildBaseVars(agentId, config, project) {
-  return {
-    agent_id: agentId,
-    agent_name: config.agents[agentId]?.name || agentId,
-    agent_role: config.agents[agentId]?.role || 'Agent',
-    team_root: MINIONS_DIR,
-    repo_id: project?.repositoryId || '',
-    project_name: project?.name || 'Unknown Project',
-    ado_org: project?.adoOrg || 'Unknown',
-    ado_project: project?.adoProject || 'Unknown',
-    repo_name: project?.repoName || 'Unknown',
-    main_branch: project?.mainBranch || 'main',
-    date: dateStamp(),
-  };
-}
-
-function selectPlaybook(workType, item) {
-  if (item?.branchStrategy === 'shared-branch' && (workType === 'implement' || workType === 'implement:large')) {
-    return 'implement-shared';
-  }
-  if (workType === 'review' && !item?._pr && !item?.pr_id) {
-    return 'work-item';
-  }
-  const typeSpecificPlaybooks = ['explore', 'review', 'test', 'plan-to-prd', 'plan', 'ask', 'verify', 'decompose'];
-  return typeSpecificPlaybooks.includes(workType) ? workType : 'work-item';
-}
-
-function buildPrDispatch(agentId, config, project, pr, type, extraVars, taskLabel, meta) {
-  const vars = { ...buildBaseVars(agentId, config, project), ...extraVars };
-  const playbookName = type === 'test' ? 'build-and-test' : (type === 'review' ? 'review' : 'fix');
-  const prompt = renderPlaybook(playbookName, vars);
-  if (!prompt) return null;
-  return {
-    type,
-    agent: agentId,
-    agentName: config.agents[agentId]?.name,
-    agentRole: config.agents[agentId]?.role,
-    task: `[${project?.name || 'project'}] ${taskLabel}`,
-    prompt,
-    meta,
-  };
-}
+// buildBaseVars, selectPlaybook, buildPrDispatch extracted to engine/playbook.js
 
 function clearPendingHumanFeedbackFlag(projectMeta, prId) {
   if (!prId) return;
@@ -3619,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; },
 
@@ -3632,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,