@yemi33/minions 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.11 (2026-03-26)
+
+### Engine
+- engine.js
+- engine/lifecycle.js
+- engine/scheduler.js
+
+### Dashboard
+- dashboard.html
+- dashboard.js
+
+### Other
+- test/unit.test.js
+
 ## 0.1.9 (2026-03-26)
 
 ### Engine

package/dashboard.html

@@ -714,6 +714,13 @@
     <div id="mcp-list"><p class="empty">No MCP servers synced.</p></div>
   </section>
 
+  <section id="scheduled-section">
+    <h2>Scheduled Tasks <span class="count" id="scheduled-count">0</span>
+      <button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--green);border-color:var(--green);margin-left:8px" onclick="openCreateScheduleModal()">+ New</button>
+    </h2>
+    <div id="scheduled-content"><p class="empty">No scheduled tasks. Add one to automate recurring work.</p></div>
+  </section>
+
   <section>
     <h2>Dispatch Queue</h2>
     <div class="dispatch-stats" id="dispatch-stats"></div>
@@ -2380,6 +2387,7 @@ async function refresh() {
     renderWorkItems(data.workItems || []);
     renderSkills(data.skills || []);
     renderMcpServers(data.mcpServers || []);
+    renderSchedules(data.schedules || []);
     // Refresh KB and plans less frequently (every 3rd cycle = ~12s)
     if (!window._kbRefreshCount) window._kbRefreshCount = 0;
     if (window._kbRefreshCount++ % 3 === 0) { refreshKnowledgeBase(); refreshPlans(); }
@@ -2448,6 +2456,164 @@ function renderMcpServers(servers) {
   '<p style="font-size:10px;color:var(--muted);margin:0">Synced from <code style="color:var(--blue)">~/.claude.json</code> — add MCP servers there to make them available to all agents.</p>';
 }
 
+// -- Scheduled Tasks --
+function renderSchedules(schedules) {
+  const el = document.getElementById('scheduled-content');
+  const countEl = document.getElementById('scheduled-count');
+  countEl.textContent = schedules.length;
+  if (!schedules.length) {
+    el.innerHTML = '<p class="empty">No scheduled tasks. Add one to automate recurring work.</p>';
+    return;
+  }
+  let html = '<div class="pr-table-wrap"><table class="pr-table"><thead><tr><th>ID</th><th>Title</th><th>Cron</th><th>Type</th><th>Project</th><th>Agent</th><th>Enabled</th><th>Last Run</th><th></th></tr></thead><tbody>';
+  for (const s of schedules) {
+    const enabledBadge = s.enabled
+      ? '<span class="pr-badge approved">enabled</span>'
+      : '<span class="pr-badge rejected">disabled</span>';
+    const lastRun = s._lastRun ? timeAgo(s._lastRun) : 'never';
+    const typeBadge = '<span class="dispatch-type ' + escHtml(s.type || 'implement') + '">' + escHtml(s.type || 'implement') + '</span>';
+    html += '<tr>' +
+      '<td><span class="pr-id">' + escHtml(s.id || '') + '</span></td>' +
+      '<td style="max-width:200px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="' + escHtml(s.title || '') + '">' + escHtml(s.title || '') + '</td>' +
+      '<td><code style="font-size:10px;color:var(--blue)">' + escHtml(s.cron || '') + '</code></td>' +
+      '<td>' + typeBadge + '</td>' +
+      '<td><span style="font-size:10px;color:var(--muted)">' + escHtml(s.project || '') + '</span></td>' +
+      '<td><span class="pr-agent">' + escHtml(s.agent || 'auto') + '</span></td>' +
+      '<td>' + enabledBadge + '</td>' +
+      '<td><span class="pr-date">' + escHtml(lastRun) + '</span></td>' +
+      '<td style="white-space:nowrap">' +
+        '<button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:' + (s.enabled ? 'var(--yellow)' : 'var(--green)') + ';border-color:' + (s.enabled ? 'var(--yellow)' : 'var(--green)') + ';margin-right:4px" onclick="event.stopPropagation();toggleScheduleEnabled(\'' + escHtml(s.id) + '\',' + !s.enabled + ')" title="' + (s.enabled ? 'Disable' : 'Enable') + '">' + (s.enabled ? '&#x23F8;' : '&#x25B6;') + '</button>' +
+        '<button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--blue);border-color:var(--blue);margin-right:4px" onclick="event.stopPropagation();openEditScheduleModal(\'' + escHtml(s.id) + '\')" title="Edit">&#x270E;</button>' +
+        '<button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--red);border-color:var(--red)" onclick="event.stopPropagation();deleteSchedule(\'' + escHtml(s.id) + '\')" title="Delete">&#x2715;</button>' +
+      '</td>' +
+    '</tr>';
+  }
+  html += '</tbody></table></div>';
+  el.innerHTML = html;
+  window._lastSchedules = schedules;
+}
+
+function _scheduleFormHtml(sched, isEdit) {
+  const types = ['implement', 'test', 'explore', 'ask', 'review', 'fix'];
+  const priorities = ['high', 'medium', 'low'];
+  const typeOpts = types.map(t => '<option value="' + t + '"' + ((sched.type || 'implement') === t ? ' selected' : '') + '>' + t + '</option>').join('');
+  const priOpts = priorities.map(p => '<option value="' + p + '"' + ((sched.priority || 'medium') === p ? ' selected' : '') + '>' + p + '</option>').join('');
+  const projOpts = '<option value="">Any</option>' + cmdProjects.map(p => '<option value="' + escHtml(p.name) + '"' + (sched.project === p.name ? ' selected' : '') + '>' + escHtml(p.name) + '</option>').join('');
+  const agentOpts = '<option value="">Auto</option>' + cmdAgents.map(a => '<option value="' + escHtml(a.id) + '"' + (sched.agent === a.id ? ' selected' : '') + '>' + escHtml(a.name) + '</option>').join('');
+
+  const inputStyle = 'display:block;width:100%;margin-top:4px;padding:6px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);color:var(--text);font-size:var(--text-md);font-family:inherit';
+
+  return '<div style="display:flex;flex-direction:column;gap:12px;font-family:inherit">' +
+    (isEdit ? '' :
+      '<label style="color:var(--text);font-size:var(--text-md)">ID (unique slug)' +
+        '<input id="sched-edit-id" value="' + escHtml(sched.id || '') + '" placeholder="e.g. nightly-tests" style="' + inputStyle + '">' +
+      '</label>') +
+    '<label style="color:var(--text);font-size:var(--text-md)">Title' +
+      '<input id="sched-edit-title" value="' + escHtml(sched.title || '') + '" style="' + inputStyle + '">' +
+    '</label>' +
+    '<label style="color:var(--text);font-size:var(--text-md)">Cron <span style="font-size:10px;color:var(--muted)">(minute hour dayOfWeek)</span>' +
+      '<input id="sched-edit-cron" value="' + escHtml(sched.cron || '') + '" placeholder="0 2 *" style="' + inputStyle + '">' +
+    '</label>' +
+    '<div style="display:flex;gap:12px">' +
+      '<label style="color:var(--text);font-size:var(--text-md);flex:1">Type' +
+        '<select id="sched-edit-type" style="' + inputStyle + '">' + typeOpts + '</select>' +
+      '</label>' +
+      '<label style="color:var(--text);font-size:var(--text-md);flex:1">Priority' +
+        '<select id="sched-edit-priority" style="' + inputStyle + '">' + priOpts + '</select>' +
+      '</label>' +
+    '</div>' +
+    '<div style="display:flex;gap:12px">' +
+      '<label style="color:var(--text);font-size:var(--text-md);flex:1">Project' +
+        '<select id="sched-edit-project" style="' + inputStyle + '">' + projOpts + '</select>' +
+      '</label>' +
+      '<label style="color:var(--text);font-size:var(--text-md);flex:1">Agent' +
+        '<select id="sched-edit-agent" style="' + inputStyle + '">' + agentOpts + '</select>' +
+      '</label>' +
+    '</div>' +
+    '<label style="color:var(--text);font-size:var(--text-md)">Description' +
+      '<textarea id="sched-edit-desc" rows="3" style="' + inputStyle + ';resize:vertical">' + escHtml(sched.description || '') + '</textarea>' +
+    '</label>' +
+    '<div style="display:flex;justify-content:flex-end;gap:8px;margin-top:8px">' +
+      '<button onclick="closeModal()" class="pr-pager-btn" style="padding:6px 16px;font-size:var(--text-md)">Cancel</button>' +
+      '<button onclick="submitSchedule(' + isEdit + ')" style="padding:6px 16px;font-size:var(--text-md);background:var(--blue);color:#fff;border:none;border-radius:var(--radius-sm);cursor:pointer">' + (isEdit ? 'Save' : 'Create') + '</button>' +
+    '</div>' +
+  '</div>';
+}
+
+function openCreateScheduleModal() {
+  document.getElementById('modal-title').textContent = 'New Scheduled Task';
+  document.getElementById('modal-body').style.whiteSpace = 'normal';
+  document.getElementById('modal-body').style.fontFamily = '';
+  document.getElementById('modal-body').innerHTML = _scheduleFormHtml({}, false);
+  document.getElementById('modal').classList.add('open');
+}
+
+function openEditScheduleModal(id) {
+  const sched = (window._lastSchedules || []).find(s => s.id === id);
+  if (!sched) return;
+  document.getElementById('modal-title').textContent = 'Edit Schedule: ' + id;
+  document.getElementById('modal-body').style.whiteSpace = 'normal';
+  document.getElementById('modal-body').style.fontFamily = '';
+  document.getElementById('modal-body').innerHTML = _scheduleFormHtml(sched, true);
+  window._editScheduleId = id;
+  document.getElementById('modal').classList.add('open');
+}
+
+async function submitSchedule(isEdit) {
+  const title = document.getElementById('sched-edit-title').value.trim();
+  const cron = document.getElementById('sched-edit-cron').value.trim();
+  const type = document.getElementById('sched-edit-type').value;
+  const priority = document.getElementById('sched-edit-priority').value;
+  const project = document.getElementById('sched-edit-project').value;
+  const agent = document.getElementById('sched-edit-agent').value;
+  const description = document.getElementById('sched-edit-desc').value;
+  const id = isEdit ? window._editScheduleId : (document.getElementById('sched-edit-id') ? document.getElementById('sched-edit-id').value.trim() : '');
+
+  if (!id) { alert('ID is required'); return; }
+  if (!title) { alert('Title is required'); return; }
+  if (!cron) { alert('Cron expression is required'); return; }
+
+  const payload = { id, title, cron, type, priority, project: project || undefined, agent: agent || undefined, description: description || undefined, enabled: true };
+  const url = isEdit ? '/api/schedules/update' : '/api/schedules';
+  try {
+    const res = await fetch(url, {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload)
+    });
+    if (res.ok) { closeModal(); refresh(); showToast('cmd-toast', isEdit ? 'Schedule updated' : 'Schedule created', true); } else {
+      const d = await res.json().catch(() => ({}));
+      alert((isEdit ? 'Update' : 'Create') + ' failed: ' + (d.error || 'unknown'));
+    }
+  } catch (e) { alert('Error: ' + e.message); }
+}
+
+async function toggleScheduleEnabled(id, enabled) {
+  try {
+    const res = await fetch('/api/schedules/update', {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id, enabled })
+    });
+    if (res.ok) { refresh(); } else {
+      const d = await res.json().catch(() => ({}));
+      alert('Toggle failed: ' + (d.error || 'unknown'));
+    }
+  } catch (e) { alert('Toggle error: ' + e.message); }
+}
+
+async function deleteSchedule(id) {
+  if (!confirm('Delete scheduled task "' + id + '"?')) return;
+  try {
+    const res = await fetch('/api/schedules/delete', {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id })
+    });
+    if (res.ok) { refresh(); showToast('cmd-toast', 'Schedule deleted', true); } else {
+      const d = await res.json().catch(() => ({}));
+      alert('Delete failed: ' + (d.error || 'unknown'));
+    }
+  } catch (e) { alert('Delete error: ' + e.message); }
+}
+
 // -- Minions Skills --
 let _skillsTab = 'all';
 let _skillsPage = 0;

package/dashboard.js

@@ -118,6 +118,11 @@ function getStatus() {
     workItems: getWorkItems(),
     skills: getSkills(),
     mcpServers: getMcpServers(),
+    schedules: (() => {
+      const scheds = CONFIG.schedules || [];
+      const runs = shared.safeJson(path.join(MINIONS_DIR, 'engine', 'schedule-runs.json')) || {};
+      return scheds.map(s => ({ ...s, _lastRun: runs[s.id] || null }));
+    })(),
     projects: PROJECTS.map(p => ({ name: p.name, path: p.localPath, description: p.description || '' })),
     initialized: !!(CONFIG.agents && Object.keys(CONFIG.agents).length > 0),
     installId: safeRead(path.join(MINIONS_DIR, '.install-id')).trim() || null,
@@ -270,6 +275,11 @@ function buildCCStatePreamble() {
 
   const planFiles = [...safeReadDir(PLANS_DIR), ...safeReadDir(PRD_DIR)].filter(f => f.endsWith('.md') || f.endsWith('.json'));
 
+  const schedules = CONFIG.schedules || [];
+  const schedSummary = schedules.length > 0
+    ? schedules.map(s => `- ${s.id}: "${s.title}" (cron: ${s.cron}, type: ${s.type || 'implement'}, ${s.enabled === false ? 'disabled' : 'enabled'})`).join('\n')
+    : '(none configured)';
+
   return `### Agents
 ${agents}
 
@@ -278,11 +288,16 @@ ${active}
 Pending: ${pending}
 
 ### Quick Counts
-PRs: ${prCount} | Work items: ${wiCount} | Plans/PRDs on disk: ${planFiles.length}
+PRs: ${prCount} | Work items: ${wiCount} | Plans/PRDs on disk: ${planFiles.length} | Schedules: ${schedules.length}
 
 ### Projects
 ${projects}
 
+### Scheduled Tasks
+${schedSummary}
+
+To discover all available dashboard APIs, fetch GET http://localhost:7331/api/routes — it returns every endpoint with method, path, description, and accepted parameters.
+
 For details on any of the above, use your tools to read files under \`${MINIONS_DIR}\`.`;
 }
 
@@ -609,8 +624,9 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
-  // POST /api/plans/trigger-verify — manually trigger verification for a completed plan
-  if (req.method === 'POST' && req.url === '/api/plans/trigger-verify') {
+  // ── Route Handler Functions ───────────────────────────────────────────────
+
+  async function handlePlansTriggerVerify(req, res) {
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
@@ -656,8 +672,7 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 500, { error: e.message }); }
   }
 
-  // POST /api/work-items/retry — reset a failed/dispatched item to pending
-  if (req.method === 'POST' && req.url === '/api/work-items/retry') {
+  async function handleWorkItemsRetry(req, res) {
     try {
       const body = await readBody(req);
       const { id, source } = body;
@@ -715,8 +730,7 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/work-items/delete — remove a work item, kill agent, clear dispatch
-  if (req.method === 'POST' && req.url === '/api/work-items/delete') {
+  async function handleWorkItemsDelete(req, res) {
     try {
       const body = await readBody(req);
       const { id, source } = body;
@@ -757,8 +771,7 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/work-items/archive — move a completed/failed work item to archive
-  if (req.method === 'POST' && req.url === '/api/work-items/archive') {
+  async function handleWorkItemsArchive(req, res) {
     try {
       const body = await readBody(req);
       const { id, source } = body;
@@ -802,8 +815,7 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // GET /api/work-items/archive — list archived work items
-  if (req.method === 'GET' && req.url === '/api/work-items/archive') {
+  async function handleWorkItemsArchiveList(req, res) {
     try {
       let allArchived = [];
       // Central archive
@@ -820,8 +832,7 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { console.error('Archive fetch error:', e.message); return jsonReply(res, 500, { error: e.message }); }
   }
 
-  // POST /api/work-items
-  if (req.method === 'POST' && req.url === '/api/work-items') {
+  async function handleWorkItemsCreate(req, res) {
     try {
       const body = await readBody(req);
       if (!body.title || !body.title.trim()) return jsonReply(res, 400, { error: 'title is required' });
@@ -852,8 +863,7 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/work-items/update — edit a pending/failed work item
-  if (req.method === 'POST' && req.url === '/api/work-items/update') {
+  async function handleWorkItemsUpdate(req, res) {
     try {
       const body = await readBody(req);
       const { id, source, title, description, type, priority, agent } = body;
@@ -890,8 +900,7 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/notes — write to inbox so it flows through normal consolidation
-  if (req.method === 'POST' && req.url === '/api/notes') {
+  async function handleNotesCreate(req, res) {
     try {
       const body = await readBody(req);
       if (!body.title || !body.title.trim()) return jsonReply(res, 400, { error: 'title is required' });
@@ -907,8 +916,7 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/plan — create a plan work item that chains to PRD on completion
-  if (req.method === 'POST' && req.url === '/api/plan') {
+  async function handlePlanCreate(req, res) {
     try {
       const body = await readBody(req);
       if (!body.title || !body.title.trim()) return jsonReply(res, 400, { error: 'title is required' });
@@ -932,8 +940,7 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/prd-items — create a PRD item as a plan file in prd/ (auto-approved)
-  if (req.method === 'POST' && req.url === '/api/prd-items') {
+  async function handlePrdItemsCreate(req, res) {
     try {
       const body = await readBody(req);
       if (!body.name || !body.name.trim()) return jsonReply(res, 400, { error: 'name is required' });
@@ -963,8 +970,7 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/prd-items/update — edit a PRD item in its source plan JSON
-  if (req.method === 'POST' && req.url === '/api/prd-items/update') {
+  async function handlePrdItemsUpdate(req, res) {
     try {
       const body = await readBody(req);
       if (!body.source || !body.itemId) return jsonReply(res, 400, { error: 'source and itemId required' });
@@ -1020,8 +1026,7 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/prd-items/remove — remove a PRD item from plan + cancel materialized work item
-  if (req.method === 'POST' && req.url === '/api/prd-items/remove') {
+  async function handlePrdItemsRemove(req, res) {
     try {
       const body = await readBody(req);
       if (!body.source || !body.itemId) return jsonReply(res, 400, { error: 'source and itemId required' });
@@ -1066,8 +1071,7 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/agents/cancel — cancel an active agent by ID or task substring
-  if (req.method === 'POST' && req.url === '/api/agents/cancel') {
+  async function handleAgentsCancel(req, res) {
     try {
       const body = await readBody(req);
       const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
@@ -1114,11 +1118,19 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // GET /api/agent/:id/live-stream — SSE real-time live output streaming
-  const liveStreamMatch = req.url.match(/^\/api\/agent\/([\w-]+)\/live-stream(?:\?.*)?$/);
-  if (liveStreamMatch && req.method === 'GET') {
-    const agentId = liveStreamMatch[1];
-    const liveLogPath = path.join(MINIONS_DIR, 'agents', agentId, 'live-output.log');
+  async function handleAgentLiveStream(req, res, match) {
+    const agentId = match[1];
+    const agentDir = path.join(MINIONS_DIR, 'agents', agentId);
+    const liveLogPath = path.join(agentDir, 'live-output.log');
+
+    // Check if agent directory exists — avoid dangling watchers on nonexistent paths
+    if (!fs.existsSync(agentDir)) {
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' });
+      res.write(`data: ${JSON.stringify('Agent not found: ' + agentId)}\n\n`);
+      res.write(`event: done\ndata: not-found\n\n`);
+      res.end();
+      return;
+    }
 
     res.writeHead(200, {
       'Content-Type': 'text/event-stream',
@@ -1177,10 +1189,8 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
-  // GET /api/agent/:id/live — tail live output for a working agent
-  const liveMatch = req.url.match(/^\/api\/agent\/([\w-]+)\/live(?:\?.*)?$/);
-  if (liveMatch && req.method === 'GET') {
-    const agentId = liveMatch[1];
+  async function handleAgentLive(req, res, match) {
+    const agentId = match[1];
     const livePath = path.join(MINIONS_DIR, 'agents', agentId, 'live-output.log');
     const content = safeRead(livePath);
     res.setHeader('Content-Type', 'text/plain; charset=utf-8');
@@ -1196,10 +1206,8 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
-  // GET /api/agent/:id/output — fetch final output.log for an agent
-  const outputMatch = req.url.match(/^\/api\/agent\/([\w-]+)\/output(?:\?.*)?$/);
-  if (outputMatch && req.method === 'GET') {
-    const agentId = outputMatch[1];
+  async function handleAgentOutput(req, res, match) {
+    const agentId = match[1];
     const outputPath = path.join(MINIONS_DIR, 'agents', agentId, 'output.log');
     const content = safeRead(outputPath);
     res.setHeader('Content-Type', 'text/plain; charset=utf-8');
@@ -1208,8 +1216,7 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
-  // GET /api/notes-full — return full notes.md content
-  if (req.method === 'GET' && req.url === '/api/notes-full') {
+  async function handleNotesFull(req, res) {
     const content = safeRead(path.join(MINIONS_DIR, 'notes.md'));
     res.setHeader('Content-Type', 'text/plain; charset=utf-8');
     res.setHeader('Access-Control-Allow-Origin', '*');
@@ -1217,8 +1224,7 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
-  // POST /api/notes-save — save edited notes.md content
-  if (req.method === 'POST' && req.url === '/api/notes-save') {
+  async function handleNotesSave(req, res) {
     try {
       const body = await readBody(req);
       if (!body.content && body.content !== '') return jsonReply(res, 400, { error: 'content required' });
@@ -1230,8 +1236,7 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // GET /api/knowledge — list all knowledge base entries grouped by category
-  if (req.method === 'GET' && req.url === '/api/knowledge') {
+  async function handleKnowledgeList(req, res) {
     const entries = getKnowledgeBaseEntries();
     const result = {};
     for (const cat of shared.KB_CATEGORIES) result[cat] = [];
@@ -1244,11 +1249,9 @@ const server = http.createServer(async (req, res) => {
     return jsonReply(res, 200, result);
   }
 
-  // GET /api/knowledge/:category/:file — read a specific knowledge base entry
-  const kbMatch = req.url.match(/^\/api\/knowledge\/([^/]+)\/([^?]+)/);
-  if (kbMatch && req.method === 'GET') {
-    const cat = kbMatch[1];
-    const file = decodeURIComponent(kbMatch[2]);
+  async function handleKnowledgeRead(req, res, match) {
+    const cat = match[1];
+    const file = decodeURIComponent(match[2]);
     // Prevent path traversal
     if (file.includes('..') || file.includes('/') || file.includes('\\')) {
       return jsonReply(res, 400, { error: 'invalid file name' });
@@ -1261,8 +1264,7 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
-  // POST /api/knowledge/sweep — deduplicate, consolidate, and reorganize knowledge base
-  if (req.method === 'POST' && req.url === '/api/knowledge/sweep') {
+  async function handleKnowledgeSweep(req, res) {
     if (global._kbSweepInFlight) return jsonReply(res, 409, { error: 'sweep already in progress' });
     global._kbSweepInFlight = true;
     try {
@@ -1409,8 +1411,7 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
     } catch (e) { return jsonReply(res, 500, { error: e.message }); } finally { global._kbSweepInFlight = false; }
   }
 
-  // GET /api/plans — list plan files (.md drafts from plans/ + .json PRDs from prd/)
-  if (req.method === 'GET' && req.url === '/api/plans') {
+  async function handlePlansList(req, res) {
     const dirs = [
       { dir: PLANS_DIR, archived: false },
       { dir: path.join(PLANS_DIR, 'archive'), archived: true },
@@ -1481,10 +1482,8 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
     return jsonReply(res, 200, plans);
   }
 
-  // GET /api/plans/archive/:file — read archived plan (checks prd/archive/ and plans/archive/)
-  const archiveFileMatch = req.url.match(/^\/api\/plans\/archive\/([^?]+)$/);
-  if (archiveFileMatch && req.method === 'GET') {
-    const file = decodeURIComponent(archiveFileMatch[1]);
+  async function handlePlansArchiveRead(req, res, match) {
+    const file = decodeURIComponent(match[1]);
     if (file.includes('..')) return jsonReply(res, 400, { error: 'invalid' });
     // Check prd/archive/ first for .json, then plans/archive/ for .md
     const archiveDir = file.endsWith('.json') ? path.join(PRD_DIR, 'archive') : path.join(PLANS_DIR, 'archive');
@@ -1499,10 +1498,8 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
     return;
   }
 
-  // GET /api/plans/:file — read full plan (JSON from prd/ or markdown from plans/)
-  const planFileMatch = req.url.match(/^\/api\/plans\/([^?]+)$/);
-  if (planFileMatch && req.method === 'GET') {
-    const file = decodeURIComponent(planFileMatch[1]);
+  async function handlePlansRead(req, res, match) {
+    const file = decodeURIComponent(match[1]);
     if (file.includes('..') || file.includes('/') || file.includes('\\')) return jsonReply(res, 400, { error: 'invalid' });
     let content = safeRead(resolvePlanPath(file));
     // Fallback: check all directories (prd/, plans/, guides/, archives)
@@ -1523,8 +1520,7 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
     return;
   }
 
-  // POST /api/plans/approve — approve a plan for execution
-  if (req.method === 'POST' && req.url === '/api/plans/approve') {
+  async function handlePlansApprove(req, res) {
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
@@ -1578,8 +1574,7 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/plans/pause — pause a plan (stops new item materialization + resets active items to pending)
-  if (req.method === 'POST' && req.url === '/api/plans/pause') {
+  async function handlePlansPause(req, res) {
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
@@ -1668,8 +1663,7 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/prd/regenerate — regenerate PRD from revised source plan
-  if (req.method === 'POST' && req.url === '/api/prd/regenerate') {
+  async function handlePrdRegenerate(req, res) {
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file is required' });
@@ -1736,8 +1730,7 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
     } catch (e) { return jsonReply(res, 500, { error: e.message }); }
   }
 
-  // POST /api/plans/execute — queue plan-to-prd conversion for a .md plan
-  if (req.method === 'POST' && req.url === '/api/plans/execute') {
+  async function handlePlansExecute(req, res) {
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
@@ -1766,8 +1759,7 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/plans/reject — reject a plan
-  if (req.method === 'POST' && req.url === '/api/plans/reject') {
+  async function handlePlansReject(req, res) {
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
@@ -1782,8 +1774,7 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/plans/regenerate — reset pending/failed work items for a plan so they re-materialize
-  if (req.method === 'POST' && req.url === '/api/plans/regenerate') {
+  async function handlePlansRegenerate(req, res) {
     try {
       const body = await readBody(req);
       if (!body.source) return jsonReply(res, 400, { error: 'source required' });
@@ -1846,8 +1837,7 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/plans/delete — delete a plan file
-  if (req.method === 'POST' && req.url === '/api/plans/delete') {
+  async function handlePlansDelete(req, res) {
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
@@ -1909,8 +1899,7 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/plans/revise — request revision with feedback, dispatches agent to revise
-  if (req.method === 'POST' && req.url === '/api/plans/revise') {
+  async function handlePlansRevise(req, res) {
     try {
       const body = await readBody(req);
       if (!body.file || !body.feedback) return jsonReply(res, 400, { error: 'file and feedback required' });
@@ -1943,7 +1932,7 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
 
   // POST /api/plans/revise-and-regenerate — REMOVED: plan versioning now handled by /api/doc-chat
   // The "Replace old PRD" flow uses qaReplacePrd (frontend) which calls /api/plans/pause + /api/plans/regenerate + planExecute
-  if (false && req.method === 'POST' && req.url === '/api/plans/revise-and-regenerate') {
+  async function handlePlansReviseAndRegenerate(req, res) {
     try {
       const body = await readBody(req);
       if (!body.source || !body.instruction) return jsonReply(res, 400, { error: 'source and instruction required' });
@@ -2083,8 +2072,7 @@ If nothing to do, return: { "duplicates": [], "reclassify": [], "remove": [] }`;
     } catch (e) { return jsonReply(res, 500, { error: e.message }); }
   }
 
-  // POST /api/plans/discuss — generate a plan discussion session script
-  if (req.method === 'POST' && req.url === '/api/plans/discuss') {
+  async function handlePlansDiscuss(req, res) {
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
@@ -2179,8 +2167,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/doc-chat — routes through CC session for minions-aware doc Q&A + editing
-  if (req.method === 'POST' && req.url === '/api/doc-chat') {
+  async function handleDocChat(req, res) {
     try {
       const body = await readBody(req);
       if (!body.message) return jsonReply(res, 400, { error: 'message required' });
@@ -2219,8 +2206,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, 500, { error: e.message }); }
   }
 
-  // POST /api/inbox/persist — promote an inbox item to team notes
-  if (req.method === 'POST' && req.url === '/api/inbox/persist') {
+  async function handleInboxPersist(req, res) {
     try {
       const body = await readBody(req);
       const { name } = body;
@@ -2259,8 +2245,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/inbox/promote-kb — promote an inbox item to the knowledge base
-  if (req.method === 'POST' && req.url === '/api/inbox/promote-kb') {
+  async function handleInboxPromoteKb(req, res) {
     try {
       const body = await readBody(req);
       const { name, category } = body;
@@ -2297,8 +2282,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/inbox/open — open inbox file in Windows explorer
-  if (req.method === 'POST' && req.url === '/api/inbox/open') {
+  async function handleInboxOpen(req, res) {
     try {
       const body = await readBody(req);
       const { name } = body;
@@ -2324,8 +2308,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/inbox/delete — delete an inbox note
-  if (req.method === 'POST' && req.url === '/api/inbox/delete') {
+  async function handleInboxDelete(req, res) {
     try {
       const body = await readBody(req);
       const { name } = body;
@@ -2339,8 +2322,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // GET /api/skill?file=<name>&source=claude-code|project:<name>&dir=<path>
-  if (req.method === 'GET' && req.url.startsWith('/api/skill?')) {
+  async function handleSkillRead(req, res) {
     const params = new URL(req.url, 'http://localhost').searchParams;
     const file = params.get('file');
     const dir = params.get('dir');
@@ -2371,8 +2353,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     return;
   }
 
-  // POST /api/projects/browse — open folder picker dialog, return selected path
-  if (req.method === 'POST' && req.url === '/api/projects/browse') {
+  async function handleProjectsBrowse(req, res) {
     try {
       const { execSync } = require('child_process');
       let selectedPath = '';
@@ -2390,8 +2371,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, 500, { error: e.message }); }
   }
 
-  // POST /api/projects/add — auto-discover and add a project to config
-  if (req.method === 'POST' && req.url === '/api/projects/add') {
+  async function handleProjectsAdd(req, res) {
     try {
       const body = await readBody(req);
       if (!body.path) return jsonReply(res, 400, { error: 'path required' });
@@ -2475,18 +2455,14 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // ── Command Center: persistent multi-turn session ──────────────────────────
-
-  // POST /api/command-center/new-session — clear active CC session
-  if (req.method === 'POST' && req.url === '/api/command-center/new-session') {
+  async function handleCommandCenterNewSession(req, res) {
     ccSession = { sessionId: null, createdAt: null, lastActiveAt: null, turnCount: 0 };
     ccInFlight = false; // Reset concurrency guard so a stuck request doesn't block new sessions
     safeWrite(path.join(ENGINE_DIR, 'cc-session.json'), ccSession);
     return jsonReply(res, 200, { ok: true });
   }
 
-  // POST /api/command-center — conversational command center with full minions context
-  if (req.method === 'POST' && req.url === '/api/command-center') {
+  async function handleCommandCenter(req, res) {
     try {
       const body = await readBody(req);
       if (!body.message) return jsonReply(res, 400, { error: 'message required' });
@@ -2529,16 +2505,83 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { ccInFlight = false; return jsonReply(res, 500, { error: e.message }); }
   }
 
-  // POST /api/engine/restart — force-kill engine and restart immediately
-  if (req.method === 'POST' && req.url === '/api/engine/restart') {
+  async function handleSchedulesList(req, res) {
+    reloadConfig();
+    const schedules = CONFIG.schedules || [];
+    const runs = shared.safeJson(path.join(MINIONS_DIR, 'engine', 'schedule-runs.json')) || {};
+    const result = schedules.map(s => ({ ...s, _lastRun: runs[s.id] || null }));
+    return jsonReply(res, 200, { schedules: result });
+  }
+
+  async function handleSchedulesCreate(req, res) {
+    const body = await readBody(req);
+    const { id, cron, title, type, project, agent, description, priority, enabled } = body;
+    if (!id || !cron || !title) return jsonReply(res, 400, { error: 'id, cron, and title are required' });
+
+    reloadConfig();
+    if (!CONFIG.schedules) CONFIG.schedules = [];
+    if (CONFIG.schedules.some(s => s.id === id)) return jsonReply(res, 400, { error: 'Schedule ID already exists' });
+
+    const sched = { id, cron, title, type: type || 'implement', enabled: enabled !== false };
+    if (project) sched.project = project;
+    if (agent) sched.agent = agent;
+    if (description) sched.description = description;
+    if (priority) sched.priority = priority;
+
+    CONFIG.schedules.push(sched);
+    safeWrite(path.join(MINIONS_DIR, 'config.json'), CONFIG);
+    invalidateStatusCache();
+    return jsonReply(res, 200, { ok: true, schedule: sched });
+  }
+
+  async function handleSchedulesUpdate(req, res) {
+    const body = await readBody(req);
+    const { id, cron, title, type, project, agent, description, priority, enabled } = body;
+    if (!id) return jsonReply(res, 400, { error: 'id required' });
+
+    reloadConfig();
+    if (!CONFIG.schedules) return jsonReply(res, 404, { error: 'No schedules configured' });
+    const sched = CONFIG.schedules.find(s => s.id === id);
+    if (!sched) return jsonReply(res, 404, { error: 'Schedule not found' });
+
+    if (cron !== undefined) sched.cron = cron;
+    if (title !== undefined) sched.title = title;
+    if (type !== undefined) sched.type = type;
+    if (project !== undefined) sched.project = project || null;
+    if (agent !== undefined) sched.agent = agent || null;
+    if (description !== undefined) sched.description = description;
+    if (priority !== undefined) sched.priority = priority;
+    if (enabled !== undefined) sched.enabled = enabled;
+
+    safeWrite(path.join(MINIONS_DIR, 'config.json'), CONFIG);
+    invalidateStatusCache();
+    return jsonReply(res, 200, { ok: true, schedule: sched });
+  }
+
+  async function handleSchedulesDelete(req, res) {
+    const body = await readBody(req);
+    const { id } = body;
+    if (!id) return jsonReply(res, 400, { error: 'id required' });
+
+    reloadConfig();
+    if (!CONFIG.schedules) return jsonReply(res, 404, { error: 'No schedules configured' });
+    const idx = CONFIG.schedules.findIndex(s => s.id === id);
+    if (idx < 0) return jsonReply(res, 404, { error: 'Schedule not found' });
+
+    CONFIG.schedules.splice(idx, 1);
+    safeWrite(path.join(MINIONS_DIR, 'config.json'), CONFIG);
+    invalidateStatusCache();
+    return jsonReply(res, 200, { ok: true });
+  }
+
+  async function handleEngineRestart(req, res) {
     try {
       const newPid = restartEngine();
       return jsonReply(res, 200, { ok: true, pid: newPid });
     } catch (e) { return jsonReply(res, 500, { error: e.message }); }
   }
 
-  // GET /api/settings — return current engine + claude + routing config
-  if (req.method === 'GET' && req.url === '/api/settings') {
+  async function handleSettingsRead(req, res) {
     try {
       const config = queries.getConfig();
       const routing = safeRead(path.join(MINIONS_DIR, 'routing.md')) || '';
@@ -2551,8 +2594,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, 500, { error: e.message }); }
   }
 
-  // POST /api/settings — update engine + claude + agent config
-  if (req.method === 'POST' && req.url === '/api/settings') {
+  async function handleSettingsUpdate(req, res) {
     try {
       const body = await readBody(req);
       const configPath = path.join(MINIONS_DIR, 'config.json');
@@ -2590,8 +2632,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, 500, { error: e.message }); }
   }
 
-  // POST /api/settings/routing — update routing.md
-  if (req.method === 'POST' && req.url === '/api/settings/routing') {
+  async function handleSettingsRouting(req, res) {
     try {
       const body = await readBody(req);
       if (!body.content) return jsonReply(res, 400, { error: 'content required' });
@@ -2600,8 +2641,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, 500, { error: e.message }); }
   }
 
-  // GET /api/health — lightweight health check for monitoring
-  if (req.method === 'GET' && req.url === '/api/health') {
+  async function handleHealth(req, res) {
     const engine = getEngineState();
     const agents = getAgents();
     const health = {
@@ -2615,12 +2655,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     return jsonReply(res, 200, health);
   }
 
-  const agentMatch = req.url.match(/^\/api\/agent\/([\w-]+)$/);
-  if (agentMatch) {
+  async function handleAgentDetail(req, res, match) {
     res.setHeader('Content-Type', 'application/json');
     res.setHeader('Access-Control-Allow-Origin', '*');
     try {
-      res.end(JSON.stringify(getAgentDetail(agentMatch[1])));
+      res.end(JSON.stringify(getAgentDetail(match[1])));
     } catch (e) {
       res.statusCode = 500;
       res.end(JSON.stringify({ error: e.message }));
@@ -2628,7 +2667,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     return;
   }
 
-  if (req.url === '/api/status') {
+  async function handleStatus(req, res) {
     try {
       return jsonReply(res, 200, getStatus(), req);
     } catch (e) {
@@ -2636,7 +2675,123 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     }
   }
 
-  // (duplicate /api/health removed — first handler above is the canonical one)
+  // ── Route Registry ──────────────────────────────────────────────────────────
+  // Order matters: specific routes before general ones (e.g., /api/plans/approve before /api/plans/:file)
+
+  const ROUTES = [
+    // Routes endpoint (self-describing API)
+    { method: 'GET', path: '/api/routes', desc: 'List all available API endpoints', handler: (req, res) => {
+      const list = ROUTES.map(r => ({
+        method: r.method,
+        path: typeof r.path === 'string' ? r.path : r.path.toString(),
+        description: r.desc,
+        params: r.params || null
+      }));
+      return jsonReply(res, 200, { routes: list });
+    }},
+
+    // Status & health
+    { method: 'GET', path: '/api/status', desc: 'Full dashboard status snapshot (agents, PRDs, work items, dispatch, etc.)', handler: handleStatus },
+    { method: 'GET', path: '/api/health', desc: 'Lightweight health check for monitoring', handler: handleHealth },
+
+    // Work items
+    { method: 'POST', path: '/api/work-items', desc: 'Create a new work item', params: 'title, type?, description?, priority?, project?, agent?, agents?, scope?', handler: handleWorkItemsCreate },
+    { method: 'POST', path: '/api/work-items/update', desc: 'Edit a pending/failed work item', params: 'id, source?, title?, description?, type?, priority?, agent?', handler: handleWorkItemsUpdate },
+    { method: 'POST', path: '/api/work-items/retry', desc: 'Reset a failed/dispatched item to pending', params: 'id, source?', handler: handleWorkItemsRetry },
+    { method: 'POST', path: '/api/work-items/delete', desc: 'Remove a work item, kill agent, clear dispatch', params: 'id, source?', handler: handleWorkItemsDelete },
+    { method: 'POST', path: '/api/work-items/archive', desc: 'Move a completed/failed work item to archive', params: 'id, source?', handler: handleWorkItemsArchive },
+    { method: 'GET', path: '/api/work-items/archive', desc: 'List archived work items', handler: handleWorkItemsArchiveList },
+
+    // Notes
+    { method: 'POST', path: '/api/notes', desc: 'Write a note to inbox for consolidation', params: 'title, what, why?, author?', handler: handleNotesCreate },
+    { method: 'GET', path: '/api/notes-full', desc: 'Return full notes.md content', handler: handleNotesFull },
+    { method: 'POST', path: '/api/notes-save', desc: 'Save edited notes.md content', params: 'content, file?', handler: handleNotesSave },
+
+    // Plans
+    { method: 'POST', path: '/api/plan', desc: 'Create a plan work item that chains to PRD on completion', params: 'title, description?, priority?, project?, agent?, branch_strategy?', handler: handlePlanCreate },
+    { method: 'GET', path: '/api/plans', desc: 'List plan files (.md drafts + .json PRDs)', handler: handlePlansList },
+    { method: 'POST', path: '/api/plans/trigger-verify', desc: 'Manually trigger verification for a completed plan', params: 'file', handler: handlePlansTriggerVerify },
+    { method: 'POST', path: '/api/plans/approve', desc: 'Approve a plan for execution', params: 'file, approvedBy?', handler: handlePlansApprove },
+    { method: 'POST', path: '/api/plans/pause', desc: 'Pause a plan (stops materialization + resets active items)', params: 'file', handler: handlePlansPause },
+    { method: 'POST', path: '/api/plans/execute', desc: 'Queue plan-to-prd conversion for a .md plan', params: 'file, project?', handler: handlePlansExecute },
+    { method: 'POST', path: '/api/plans/reject', desc: 'Reject a plan', params: 'file, rejectedBy?, reason?', handler: handlePlansReject },
+    { method: 'POST', path: '/api/plans/regenerate', desc: 'Reset pending/failed work items for a plan so they re-materialize', params: 'source', handler: handlePlansRegenerate },
+    { method: 'POST', path: '/api/plans/delete', desc: 'Delete a plan file and clean up work items', params: 'file', handler: handlePlansDelete },
+    { method: 'POST', path: '/api/plans/revise', desc: 'Request revision with feedback, dispatches agent to revise', params: 'file, feedback, requestedBy?', handler: handlePlansRevise },
+    { method: 'POST', path: '/api/plans/discuss', desc: 'Generate a plan discussion session script for Claude CLI', params: 'file', handler: handlePlansDiscuss },
+    { method: 'GET', path: /^\/api\/plans\/archive\/([^?]+)$/, desc: 'Read an archived plan file', handler: handlePlansArchiveRead },
+    { method: 'GET', path: /^\/api\/plans\/([^?]+)$/, desc: 'Read a full plan (JSON from prd/ or markdown from plans/)', handler: handlePlansRead },
+
+    // PRD items
+    { method: 'POST', path: '/api/prd-items', desc: 'Create a PRD item as a plan file in prd/ (auto-approved)', params: 'name, description?, priority?, estimated_complexity?, project?, id?', handler: handlePrdItemsCreate },
+    { method: 'POST', path: '/api/prd-items/update', desc: 'Edit a PRD item in its source plan JSON', params: 'source, itemId, name?, description?, priority?, estimated_complexity?, status?', handler: handlePrdItemsUpdate },
+    { method: 'POST', path: '/api/prd-items/remove', desc: 'Remove a PRD item from plan + cancel materialized work item', params: 'source, itemId', handler: handlePrdItemsRemove },
+    { method: 'POST', path: '/api/prd/regenerate', desc: 'Regenerate PRD from revised source plan', params: 'file', handler: handlePrdRegenerate },
+
+    // Agents
+    { method: 'POST', path: '/api/agents/cancel', desc: 'Cancel an active agent by ID or task substring', params: 'agent?, task?', handler: handleAgentsCancel },
+    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/live-stream(?:\?.*)?$/, desc: 'SSE real-time live output streaming', handler: handleAgentLiveStream },
+    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/live(?:\?.*)?$/, desc: 'Tail live output for a working agent', params: 'tail? (bytes, default 8192)', handler: handleAgentLive },
+    { method: 'GET', path: /^\/api\/agent\/([\w-]+)\/output(?:\?.*)?$/, desc: 'Fetch final output.log for an agent', handler: handleAgentOutput },
+    { method: 'GET', path: /^\/api\/agent\/([\w-]+)$/, desc: 'Get detailed agent info', handler: handleAgentDetail },
+
+    // Knowledge base
+    { method: 'GET', path: '/api/knowledge', desc: 'List all knowledge base entries grouped by category', handler: handleKnowledgeList },
+    { method: 'POST', path: '/api/knowledge/sweep', desc: 'Deduplicate, consolidate, and reorganize knowledge base', handler: handleKnowledgeSweep },
+    { method: 'GET', path: /^\/api\/knowledge\/([^/]+)\/([^?]+)/, desc: 'Read a specific knowledge base entry', handler: handleKnowledgeRead },
+
+    // Doc chat
+    { method: 'POST', path: '/api/doc-chat', desc: 'Minions-aware doc Q&A + editing via CC session', params: 'message, document, title?, filePath?, selection?', handler: handleDocChat },
+
+    // Inbox
+    { method: 'POST', path: '/api/inbox/persist', desc: 'Promote an inbox item to team notes', params: 'name', handler: handleInboxPersist },
+    { method: 'POST', path: '/api/inbox/promote-kb', desc: 'Promote an inbox item to the knowledge base', params: 'name, category', handler: handleInboxPromoteKb },
+    { method: 'POST', path: '/api/inbox/open', desc: 'Open inbox file in file manager', params: 'name', handler: handleInboxOpen },
+    { method: 'POST', path: '/api/inbox/delete', desc: 'Delete an inbox note', params: 'name', handler: handleInboxDelete },
+
+    // Skills
+    { method: 'GET', path: '/api/skill', desc: 'Read a skill file', params: 'file, source?, dir?', handler: handleSkillRead },
+
+    // Projects
+    { method: 'POST', path: '/api/projects/browse', desc: 'Open folder picker dialog, return selected path', handler: handleProjectsBrowse },
+    { method: 'POST', path: '/api/projects/add', desc: 'Auto-discover and add a project to config', params: 'path, name?', handler: handleProjectsAdd },
+
+    // Command Center
+    { method: 'POST', path: '/api/command-center/new-session', desc: 'Clear active CC session', handler: handleCommandCenterNewSession },
+    { method: 'POST', path: '/api/command-center', desc: 'Conversational command center with full minions context', params: 'message, sessionId?', handler: handleCommandCenter },
+
+    // Schedules
+    { method: 'GET', path: '/api/schedules', desc: 'Return schedules from config + last-run times', handler: handleSchedulesList },
+    { method: 'POST', path: '/api/schedules', desc: 'Create a new schedule', params: 'id, cron, title, type?, project?, agent?, description?, priority?, enabled?', handler: handleSchedulesCreate },
+    { method: 'POST', path: '/api/schedules/update', desc: 'Update an existing schedule', params: 'id, cron?, title?, type?, project?, agent?, description?, priority?, enabled?', handler: handleSchedulesUpdate },
+    { method: 'POST', path: '/api/schedules/delete', desc: 'Delete a schedule', params: 'id', handler: handleSchedulesDelete },
+
+    // Engine
+    { method: 'POST', path: '/api/engine/restart', desc: 'Force-kill engine and restart immediately', handler: handleEngineRestart },
+
+    // Settings
+    { method: 'GET', path: '/api/settings', desc: 'Return current engine + claude + routing config', handler: handleSettingsRead },
+    { method: 'POST', path: '/api/settings', desc: 'Update engine + claude + agent config', params: 'engine?, claude?, agents?', handler: handleSettingsUpdate },
+    { method: 'POST', path: '/api/settings/routing', desc: 'Update routing.md', params: 'content', handler: handleSettingsRouting },
+  ];
+
+  // ── Route Dispatcher ────────────────────────────────────────────────────────
+
+  const pathname = req.url.split('?')[0];
+  for (const route of ROUTES) {
+    if (route.method !== req.method) continue;
+    if (typeof route.path === 'string') {
+      // For /api/skill, match with query string prefix since it has no fixed path variant
+      if (route.path === '/api/skill') {
+        if (!req.url.startsWith('/api/skill?') && req.url !== '/api/skill') continue;
+        return await route.handler(req, res, {});
+      }
+      if (pathname !== route.path) continue;
+      return await route.handler(req, res, {});
+    }
+    const m = pathname.match(route.path);
+    if (m) return await route.handler(req, res, m);
+  }
 
   // Serve dashboard HTML with gzip + caching
   res.setHeader('Content-Type', 'text/html; charset=utf-8');

package/engine/lifecycle.js

@@ -1021,16 +1021,14 @@ function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config) {
   const { resultSummary, taskUsage } = parseAgentOutput(stdout);
 
   // Handle decomposition results — create sub-items from decompose agent output
+  let skipDoneStatus = false;
   if (type === 'decompose' && isSuccess && meta?.item?.id) {
     const subCount = handleDecompositionResult(stdout, meta, config);
-    if (subCount > 0) {
-      // Parent is marked 'decomposed' by handler — don't overwrite with 'done'
-      return { resultSummary: `Decomposed into ${subCount} sub-items`, taskUsage };
-    }
-    // Fallback: if decomposition produced nothing, mark parent as done to avoid stuck state
+    if (subCount > 0) skipDoneStatus = true; // parent already marked 'decomposed' by handler
+    // If decomposition produced nothing, fall through to mark parent as done
   }
 
-  if (isSuccess && meta?.item?.id) updateWorkItemStatus(meta, 'done', '');
+  if (isSuccess && meta?.item?.id && !skipDoneStatus) updateWorkItemStatus(meta, 'done', '');
   if (!isSuccess && meta?.item?.id) {
     // Auto-retry: read fresh _retryCount from file (not stale dispatch-time snapshot)
     let retries = (meta.item._retryCount || 0);
@@ -1055,12 +1053,29 @@ function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config) {
         if (wiPath) {
           const items = safeJson(wiPath) || [];
           const wi = items.find(i => i.id === meta.item.id);
-          if (wi) { wi._retryCount = retries + 1; wi.status = 'pending'; delete wi.dispatched_at; delete wi.dispatched_to; shared.safeWrite(wiPath, items); }
+          if (wi) {
+            wi._retryCount = retries + 1; wi.status = 'pending'; delete wi.dispatched_at; delete wi.dispatched_to;
+            if (type === 'decompose') delete wi._decomposing; // clear so item can retry decomposition
+            shared.safeWrite(wiPath, items);
+          }
         }
       } catch {}
     } else {
       updateWorkItemStatus(meta, 'failed', 'Agent failed (3 retries exhausted)');
     }
+    // Clear _decomposing flag on failure so item doesn't get permanently stuck
+    if (type === 'decompose') {
+      try {
+        const wiPath = meta.source === 'central-work-item' || meta.source === 'central-work-item-fanout'
+          ? path.join(MINIONS_DIR, 'work-items.json')
+          : meta.project?.name ? path.join(MINIONS_DIR, 'projects', meta.project.name, 'work-items.json') : null;
+        if (wiPath) {
+          const items = safeJson(wiPath) || [];
+          const wi = items.find(i => i.id === meta.item.id);
+          if (wi) { delete wi._decomposing; shared.safeWrite(wiPath, items); }
+        }
+      } catch {}
+    }
   }
   // Plan chaining removed — user must explicitly execute plan-to-prd after reviewing the plan
   if (isSuccess && meta?.item?.sourcePlan) checkPlanCompletion(meta, config);

package/engine/scheduler.js

@@ -96,16 +96,11 @@ function shouldRunNow(schedule, lastRunAt) {
   const now = new Date();
   if (!cron.matches(now)) return false;
 
-  // Don't fire again if already ran in this minute window
+  // Don't fire again if already ran within the last 55 seconds
+  // (uses elapsed time instead of field comparison to handle DST/clock adjustments)
   if (lastRunAt) {
     const last = new Date(lastRunAt);
-    if (last.getFullYear() === now.getFullYear() &&
-        last.getMonth() === now.getMonth() &&
-        last.getDate() === now.getDate() &&
-        last.getHours() === now.getHours() &&
-        last.getMinutes() === now.getMinutes()) {
-      return false; // already fired this minute
-    }
+    if (Date.now() - last.getTime() < 55000) return false;
   }
 
   return true;
@@ -120,38 +115,34 @@ function discoverScheduledWork(config) {
   const schedules = config.schedules;
   if (!Array.isArray(schedules) || schedules.length === 0) return [];
 
-  const runs = safeJson(SCHEDULE_RUNS_PATH) || {};
+  // Use file-locked mutation to prevent race conditions on rapid calls
   const work = [];
-
-  for (const sched of schedules) {
-    if (!sched.id || !sched.cron || !sched.title) continue;
-    if (sched.enabled === false) continue;
-
-    const lastRun = runs[sched.id] || null;
-    if (!shouldRunNow(sched, lastRun)) continue;
-
-    work.push({
-      id: `sched-${sched.id}-${Date.now()}`,
-      title: sched.title,
-      type: sched.type || 'implement',
-      priority: sched.priority || 'medium',
-      description: sched.description || sched.title,
-      status: 'pending',
-      created: new Date().toISOString(),
-      createdBy: 'scheduler',
-      agent: sched.agent || null,
-      project: sched.project || null,
-      _scheduleId: sched.id,
-    });
-
-    // Record run time
-    runs[sched.id] = new Date().toISOString();
-  }
-
-  // Persist run times if any schedules fired
-  if (work.length > 0) {
-    safeWrite(SCHEDULE_RUNS_PATH, runs);
-  }
+  mutateJsonFileLocked(SCHEDULE_RUNS_PATH, (runs) => {
+    for (const sched of schedules) {
+      if (!sched.id || !sched.cron || !sched.title) continue;
+      if (sched.enabled === false) continue;
+
+      const lastRun = runs[sched.id] || null;
+      if (!shouldRunNow(sched, lastRun)) continue;
+
+      work.push({
+        id: `sched-${sched.id}-${Date.now()}`,
+        title: sched.title,
+        type: sched.type || 'implement',
+        priority: sched.priority || 'medium',
+        description: sched.description || sched.title,
+        status: 'pending',
+        created: new Date().toISOString(),
+        createdBy: 'scheduler',
+        agent: sched.agent || null,
+        project: sched.project || null,
+        _scheduleId: sched.id,
+      });
+
+      // Record run time inside the lock
+      runs[sched.id] = new Date().toISOString();
+    }
+  }, { defaultValue: {} });
 
   return work;
 }

package/engine.js

@@ -2626,8 +2626,8 @@ function discoverFromWorkItems(config, project) {
     newWork.push({
       type: workType,
       agent: agentId,
-      agentName: config.agents[agentId]?.name,
-      agentRole: config.agents[agentId]?.role,
+      agentName: config.agents[agentId]?.name || tempAgents.get(agentId)?.name || agentId,
+      agentRole: config.agents[agentId]?.role || tempAgents.get(agentId)?.role || 'Agent',
       task: `[${project?.name || 'project'}] ${item.title || item.description?.slice(0, 80) || item.id}`,
       prompt,
       meta: { dispatchKey: key, source: 'work-item', branch: branchName, branchStrategy: item.branchStrategy || 'parallel', useExistingBranch: !!(item.branchStrategy === 'shared-branch' && item.featureBranch), item, project: { name: project?.name, localPath: project?.localPath } }
@@ -3064,16 +3064,18 @@ function discoverWork(config) {
   try {
     const { discoverScheduledWork } = require('./engine/scheduler');
     const scheduledWork = discoverScheduledWork(config);
-    for (const item of scheduledWork) {
-      // Write scheduled items to central work-items.json so they persist across ticks
+    if (scheduledWork.length > 0) {
       const centralPath = path.join(MINIONS_DIR, 'work-items.json');
       const items = safeJson(centralPath) || [];
-      // Dedupe: don't re-create if same schedule already has a pending/dispatched item
-      if (!items.some(i => i._scheduleId === item._scheduleId && i.status !== 'done' && i.status !== 'failed')) {
-        items.push(item);
-        safeWrite(centralPath, items);
-        log('info', `Scheduled task fired: ${item._scheduleId} → ${item.title}`);
+      let added = 0;
+      for (const item of scheduledWork) {
+        if (!items.some(i => i._scheduleId === item._scheduleId && i.status !== 'done' && i.status !== 'failed')) {
+          items.push(item);
+          added++;
+          log('info', `Scheduled task fired: ${item._scheduleId} → ${item.title}`);
+        }
       }
+      if (added > 0) safeWrite(centralPath, items);
     }
   } catch {}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"