@yemi33/minions 0.1.1813 → 0.1.1815

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.1815 (2026-05-09)
+
+### Features
+- verify restart health (#2258)
+
+## 0.1.1814 (2026-05-09)
+
+### Features
+- harden PRD and playbook paths (#2247)
+
 ## 0.1.1813 (2026-05-09)
 
 ### Features

package/bin/minions.js

@@ -40,6 +40,7 @@ const { spawn, spawnSync, execSync } = require('child_process');
 
 const PKG_ROOT = path.resolve(__dirname, '..');
 const shared = require(path.join(PKG_ROOT, 'engine', 'shared'));
+const { waitForRestartHealth, formatRestartHealthError } = require(path.join(PKG_ROOT, 'engine', 'restart-health'));
 const DASH_PORT = 7331;
 const DASHBOARD_BROWSER_PRESENCE_MAX_AGE_MS = 45000;
 
@@ -708,7 +709,22 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   console.log(`\n  Engine started (PID: ${engineProc.pid})`);
   const dashProc = spawnDashboard(suppressDashboardOpen);
   console.log(`  Dashboard started (PID: ${dashProc.pid})`);
-  console.log(`  Dashboard: http://localhost:${DASH_PORT}\n`);
+  console.log(`  Dashboard: http://localhost:${DASH_PORT}`);
+  console.log('  Verifying restart health...');
+  void (async () => {
+    const result = await waitForRestartHealth({
+      minionsHome: MINIONS_HOME,
+      dashboardUrl: `http://127.0.0.1:${DASH_PORT}/api/health`,
+    });
+    if (!result.ok) {
+      console.error(formatRestartHealthError(result));
+      process.exit(1);
+    }
+    console.log(`  Restart verified: engine PID ${result.engine.pid}; dashboard healthy.\n`);
+  })().catch(err => {
+    console.error(`\n  ERROR: Restart verification failed: ${err.message}\n`);
+    process.exit(1);
+  });
 } else if (cmd === 'nuke') {
   ensureInstalled();
   if (!rest.includes('--confirm')) {

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-09T09:32:10.535Z"
+  "cachedAt": "2026-05-09T15:24:57.566Z"
 }

package/engine/pipeline.js

@@ -390,11 +390,10 @@ function executeTaskStage(stage, stageState, run, config, pipeline = {}) {
       touchedProjects.push(project?.name || null);
     }
   }
-  const projects = [...new Set(touchedProjects)];
-  return {
-    status: PIPELINE_STATUS.RUNNING,
-    artifacts: { workItems: [...new Set(createdIds)], projects },
-  };
+  const artifacts = { workItems: [...new Set(createdIds)] };
+  const projectArtifacts = [...new Set(touchedProjects.filter(Boolean))];
+  if (projectArtifacts.length > 0) artifacts.projects = projectArtifacts;
+  return { status: PIPELINE_STATUS.RUNNING, artifacts };
 }
 
 function executeTaskStageLegacy(stage, stageState, run, config) {

package/engine/playbook.js

@@ -342,21 +342,41 @@ function isSafeProjectPlaybookName(projectName) {
     !/^[a-zA-Z]:/.test(name);
 }
 
+function isSafePlaybookType(playbookType) {
+  const name = String(playbookType || '').trim();
+  return !!name &&
+    !name.includes('\0') &&
+    !name.includes('..') &&
+    !/[\\/]/.test(name) &&
+    !path.isAbsolute(name) &&
+    !/^[a-zA-Z]:/.test(name);
+}
+
 function resolvePlaybookPath(projectName, playbookType) {
+  const playbookTypeName = String(playbookType || '').trim();
+  if (!isSafePlaybookType(playbookTypeName)) {
+    log('warn', `Skipping unsafe playbook type lookup: ${playbookTypeName.replace(/\0/g, '')}`);
+    return path.join(PLAYBOOKS_DIR, '__invalid__.md');
+  }
   if (projectName) {
     const projectDirName = String(projectName).trim();
     if (isSafeProjectPlaybookName(projectDirName)) {
-      const localPath = path.join(MINIONS_DIR, 'projects', projectDirName, 'playbooks', `${playbookType}.md`);
+      const projectsDir = path.join(MINIONS_DIR, 'projects');
+      const localPath = path.resolve(projectsDir, projectDirName, 'playbooks', `${playbookTypeName}.md`);
+      if (!shared.isPathInside(localPath, projectsDir)) {
+        log('warn', `Skipping project-local playbook outside projects/: ${projectDirName}`);
+        return path.join(PLAYBOOKS_DIR, `${playbookTypeName}.md`);
+      }
       try {
         fs.accessSync(localPath, fs.constants.R_OK);
-        log('info', `Using project-local playbook: projects/${projectDirName}/playbooks/${playbookType}.md`);
+        log('info', `Using project-local playbook: projects/${projectDirName}/playbooks/${playbookTypeName}.md`);
         return localPath;
       } catch { /* no local override — fall through to global */ }
     } else {
       log('warn', `Skipping project-local playbook lookup for unsafe project name: ${projectDirName}`);
     }
   }
-  return path.join(PLAYBOOKS_DIR, `${playbookType}.md`);
+  return path.join(PLAYBOOKS_DIR, `${playbookTypeName}.md`);
 }
 
 

package/engine/projects.js

@@ -11,13 +11,84 @@ const shared = require('./shared');
 const dispatch = require('./dispatch');
 const { MINIONS_DIR } = shared;
 
-/**
- * @param {object} d - dispatch entry
- * @returns {string} project name from any of the three meta shapes the engine
- *   uses (item.project, project.name, project string)
- */
-function _dispatchProjectName(d) {
-  return d?.meta?.item?.project || d?.meta?.project?.name || d?.meta?.project || '';
+function _sameProjectName(a, b) {
+  return String(a || '').toLowerCase() === String(b || '').toLowerCase();
+}
+
+function _projectRefMatches(projectRef, removedProject, projects) {
+  if (!projectRef) return false;
+  const refs = (projectRef && typeof projectRef === 'object')
+    ? [projectRef.name, projectRef.localPath]
+    : [projectRef];
+  return refs.some(ref => {
+    if (!ref) return false;
+    const result = shared.resolveConfiguredProject(ref, projects);
+    return !!(result.project && _sameProjectName(result.project.name, removedProject.name));
+  });
+}
+
+function _workItemMatchesProject(item, removedProject, projects) {
+  const refs = [
+    item?.project,
+    item?._project,
+    item?.planProject,
+    item?._planProject,
+    item?._declaredPlanProject,
+  ];
+  return refs.some(ref => _projectRefMatches(ref, removedProject, projects));
+}
+
+function _isCentralDispatchSource(source) {
+  return source === 'central-work-item' || source === 'central-work-item-fanout';
+}
+
+function _dispatchMatchesProject(d, removedProject, projects) {
+  const meta = d?.meta || {};
+  if (_isCentralDispatchSource(meta.source)) {
+    return _workItemMatchesProject(meta.item, removedProject, projects) ||
+      _projectRefMatches(meta.project, removedProject, projects);
+  }
+  return _workItemMatchesProject(meta.item, removedProject, projects) ||
+    _projectRefMatches(meta.project, removedProject, projects);
+}
+
+function _centralDispatchDefaultedToProject(d, removedProject, projects) {
+  const meta = d?.meta || {};
+  return _isCentralDispatchSource(meta.source) &&
+    meta.item?.id &&
+    !_workItemMatchesProject(meta.item, removedProject, projects) &&
+    _projectRefMatches(meta.project, removedProject, projects);
+}
+
+function _collectProjectlessCentralDispatchItemIds(removedProject, projects) {
+  const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
+  const ids = new Set();
+  const state = shared.safeJson(dispatchPath) || {};
+  for (const queue of ['pending', 'active']) {
+    for (const d of Array.isArray(state?.[queue]) ? state[queue] : []) {
+      if (_centralDispatchDefaultedToProject(d, removedProject, projects)) ids.add(d.meta.item.id);
+    }
+  }
+  return ids;
+}
+
+function _requeueProjectlessCentralWorkItems(itemIds) {
+  if (!itemIds || itemIds.size === 0) return 0;
+  const wiPath = path.join(MINIONS_DIR, 'work-items.json');
+  if (!fs.existsSync(wiPath)) return 0;
+  let requeued = 0;
+  shared.mutateWorkItems(wiPath, items => {
+    if (!Array.isArray(items)) return items;
+    for (const w of items) {
+      if (!itemIds.has(w?.id) || w.status !== shared.WI_STATUS.DISPATCHED) continue;
+      w.status = shared.WI_STATUS.PENDING;
+      delete w.dispatched_at;
+      delete w.dispatched_to;
+      requeued++;
+    }
+    return items;
+  });
+  return requeued;
 }
 
 /**
@@ -56,9 +127,10 @@ function removeProject(target, options = {}) {
   try { config = JSON.parse(fs.readFileSync(configPath, 'utf8')); }
   catch (e) { return { ...summary, error: 'Failed to read config: ' + e.message }; }
 
-  const project = shared.findProjectByNameOrPath(config.projects || [], target);
+  const projects = shared.getProjects(config);
+  const project = shared.resolveConfiguredProject(target, projects).project;
   if (!project) {
-    const available = (config.projects || []).map(p => p.name).join(', ') || '(none)';
+    const available = projects.map(p => p.name).join(', ') || '(none)';
     return { ...summary, error: `No project linked matching: ${target}. Available: ${available}` };
   }
   summary.project = { name: project.name, localPath: project.localPath };
@@ -72,15 +144,17 @@ function removeProject(target, options = {}) {
   );
   summary.cancelledItems += dispatch.cancelPendingWorkItems(
     path.join(MINIONS_DIR, 'work-items.json'),
-    w => String(w.project || '').toLowerCase() === String(project.name || '').toLowerCase(),
+    w => _workItemMatchesProject(w, project, projects),
     'project-removed',
   );
 
   // 2. Drain dispatch — also kills active agent processes and unlinks pid +
   //    prompt sidecars in engine/tmp/, matching what plan delete does.
+  const projectlessCentralItemIds = _collectProjectlessCentralDispatchItemIds(project, projects);
   summary.drainedDispatches = dispatch.cleanDispatchEntries(
-    d => String(_dispatchProjectName(d) || '').toLowerCase() === String(project.name || '').toLowerCase(),
+    d => _dispatchMatchesProject(d, project, projects),
   );
+  _requeueProjectlessCentralWorkItems(projectlessCentralItemIds);
 
   // 3. Clean up worktrees under this project's worktree root, honoring
   //    config.engine.worktreeRoot (mirrors lifecycle.js cleanupPlanWorktrees).
@@ -103,7 +177,7 @@ function removeProject(target, options = {}) {
   //    specifically. Don't touch schedules with project='any' or unset.
   if (Array.isArray(config.schedules)) {
     for (const s of config.schedules) {
-      if (shared.resolveProjectSource(s.project, [project], { allowCentral: false }).project && s.enabled !== false) {
+      if (_projectRefMatches(s.project, project, projects) && s.enabled !== false) {
         s.enabled = false;
         summary.disabledSchedules++;
       }
@@ -129,7 +203,7 @@ function removeProject(target, options = {}) {
       for (const f of fs.readdirSync(prdDir).filter(f => f.endsWith('.json'))) {
         try {
           const prd = JSON.parse(fs.readFileSync(path.join(prdDir, f), 'utf8'));
-          if (prd?.project !== project.name) continue;
+          if (!_projectRefMatches(prd?.project, project, projects)) continue;
           archivePlan(f, prd, [project], config);
           summary.archivedPlans.push('prd/' + f);
           if (prd.source_plan) archivedSourcePlans.add(prd.source_plan);
@@ -164,14 +238,17 @@ function removeProject(target, options = {}) {
         ...(p.monitoredResources || []),
         ...((p.stages || []).flatMap(s => s.monitoredResources || [])),
       ];
-      if (refs.some(r => r && shared.resolveProjectSource(r.project || r._project, [project], { allowCentral: false }).project)) {
+      if (refs.some(r => r && (
+        _projectRefMatches(r.project, project, projects) ||
+        _projectRefMatches(r._project, project, projects)
+      ))) {
         summary.pipelineRefs.push(p.id);
       }
     }
   } catch { /* pipelines optional */ }
 
   // 7. Remove from config.json (and persist any schedule disables)
-  config.projects = (config.projects || []).filter(p => !shared.resolveProjectSource(p, [project], { allowCentral: false }).project);
+  config.projects = (config.projects || []).filter(p => !_sameProjectName(p?.name, project.name));
   try { fs.writeFileSync(configPath, JSON.stringify(config, null, 2)); }
   catch (e) { return { ...summary, error: 'Failed to write config: ' + e.message }; }
 

package/engine/restart-health.js

@@ -0,0 +1,169 @@
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const https = require('https');
+const { execSync } = require('child_process');
+
+const DEFAULT_RESTART_HEALTH_TIMEOUT_MS = 15000;
+const DEFAULT_RESTART_HEALTH_INTERVAL_MS = 250;
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function readEngineControl(minionsHome) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(minionsHome, 'engine', 'control.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function normalizePid(pid) {
+  const n = Number(pid);
+  return Number.isInteger(n) && n > 0 ? n : null;
+}
+
+function isProcessAlive(pid) {
+  const n = normalizePid(pid);
+  if (!n || n === process.pid) return false;
+  try {
+    if (process.platform === 'win32') {
+      const out = execSync(`tasklist /FI "PID eq ${n}" /NH`, {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: 3000,
+      });
+      return new RegExp(`\\b${n}\\b`).test(out) && out.toLowerCase().includes('node');
+    }
+    process.kill(n, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function httpGetJson(url, timeoutMs = 1000) {
+  return new Promise(resolve => {
+    let settled = false;
+    const parsed = new URL(url);
+    const client = parsed.protocol === 'https:' ? https : http;
+    const req = client.get(parsed, { timeout: timeoutMs }, res => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', chunk => { body += chunk; });
+      res.on('end', () => {
+        if (settled) return;
+        settled = true;
+        let json = null;
+        try { json = body ? JSON.parse(body) : null; }
+        catch (err) {
+          resolve({ ok: false, statusCode: res.statusCode, error: err, body });
+          return;
+        }
+        resolve({ ok: res.statusCode >= 200 && res.statusCode < 300, statusCode: res.statusCode, json, body });
+      });
+    });
+    req.on('timeout', () => {
+      if (settled) return;
+      settled = true;
+      req.destroy();
+      resolve({ ok: false, error: new Error(`timed out after ${timeoutMs}ms`) });
+    });
+    req.on('error', err => {
+      if (settled) return;
+      settled = true;
+      resolve({ ok: false, error: err });
+    });
+  });
+}
+
+async function checkRestartHealth(options = {}) {
+  const {
+    minionsHome,
+    dashboardUrl = 'http://127.0.0.1:7331/api/health',
+    readControl = readEngineControl,
+    isProcessAlive: isAlive = isProcessAlive,
+    httpGetJson: getJson = httpGetJson,
+  } = options;
+
+  const control = readControl(minionsHome);
+  const pid = normalizePid(control && control.pid);
+  const engineAlive = pid ? isAlive(pid) : false;
+  const engineOk = control && control.state === 'running' && engineAlive;
+
+  const dashboard = await getJson(dashboardUrl, 1000);
+  const dashboardStatus = dashboard && dashboard.json && dashboard.json.status;
+  const dashboardOk = !!(dashboard && dashboard.ok && dashboardStatus === 'healthy');
+
+  const errors = [];
+  if (!engineOk) {
+    const state = control && control.state ? control.state : 'unknown';
+    const pidLabel = pid || 'none';
+    errors.push(`Engine is not healthy (state=${state}, pid=${pidLabel}, alive=${engineAlive ? 'yes' : 'no'})`);
+  }
+  if (!dashboardOk) {
+    const detail = dashboard && dashboard.error
+      ? dashboard.error.message
+      : dashboard && dashboard.statusCode
+        ? `HTTP ${dashboard.statusCode}${dashboardStatus ? `, status=${dashboardStatus}` : ''}`
+        : 'no response';
+    errors.push(`Dashboard failed health check at ${dashboardUrl} (${detail})`);
+  }
+
+  return {
+    ok: engineOk && dashboardOk,
+    engine: { state: control && control.state, pid, alive: engineAlive },
+    dashboard: { url: dashboardUrl, ok: !!(dashboard && dashboard.ok), statusCode: dashboard && dashboard.statusCode, status: dashboardStatus },
+    errors,
+  };
+}
+
+async function waitForRestartHealth(options = {}) {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_RESTART_HEALTH_TIMEOUT_MS;
+  const intervalMs = options.intervalMs ?? DEFAULT_RESTART_HEALTH_INTERVAL_MS;
+  const maxAttempts = normalizePid(options.maxAttempts);
+  const started = Date.now();
+  let attempts = 0;
+  let last = null;
+
+  while (true) {
+    attempts++;
+    last = await checkRestartHealth(options);
+    last.attempts = attempts;
+    last.elapsedMs = Date.now() - started;
+    if (last.ok) return last;
+    if (maxAttempts && attempts >= maxAttempts) break;
+    const remainingMs = timeoutMs - (Date.now() - started);
+    if (!maxAttempts && remainingMs <= 0) break;
+    await sleep(maxAttempts ? intervalMs : Math.min(intervalMs, remainingMs));
+  }
+
+  return last || {
+    ok: false,
+    attempts,
+    elapsedMs: Date.now() - started,
+    errors: ['Restart health check did not run'],
+  };
+}
+
+function formatRestartHealthError(result) {
+  const elapsed = typeof result.elapsedMs === 'number' ? `${result.elapsedMs}ms` : 'unknown time';
+  const attempts = result.attempts || 0;
+  const details = (result.errors || ['Unknown restart verification failure']).map(err => `  - ${err}`).join('\n');
+  return `\n  ERROR: Restart verification failed after ${elapsed} (${attempts} attempt${attempts === 1 ? '' : 's'}).\n${details}\n`;
+}
+
+module.exports = {
+  DEFAULT_RESTART_HEALTH_TIMEOUT_MS,
+  DEFAULT_RESTART_HEALTH_INTERVAL_MS,
+  checkRestartHealth,
+  waitForRestartHealth,
+  formatRestartHealthError,
+  _private: {
+    httpGetJson,
+    isProcessAlive,
+    readEngineControl,
+    normalizePid,
+  },
+};

package/engine/shared.js

@@ -2209,7 +2209,8 @@ function sanitizePath(file, baseDir) {
   if (path.isAbsolute(file) || /^[a-zA-Z]:/.test(file)) throw new Error('invalid file path: absolute path not allowed');
   const resolved = path.resolve(baseDir, file);
   const normalizedBase = path.resolve(baseDir);
-  if (!resolved.startsWith(normalizedBase + path.sep) && resolved !== normalizedBase) {
+  const rel = path.relative(normalizedBase, resolved);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
     throw new Error('invalid file path: outside allowed directory');
   }
   return resolved;

package/engine.js

@@ -2015,8 +2015,11 @@ function safePrdProjectSlug(projectName) {
 
 function safePrdFilenameForProject(projectName, suffix) {
   const fileName = `${safePrdProjectSlug(projectName)}-${suffix}.json`;
-  shared.sanitizePath(fileName, PRD_DIR);
-  return fileName;
+  const resolved = shared.sanitizePath(fileName, PRD_DIR);
+  if (path.dirname(resolved) !== path.resolve(PRD_DIR)) {
+    throw new Error('invalid PRD filename: nested paths are not allowed');
+  }
+  return path.basename(resolved);
 }
 
 function materializePlansAsWorkItems(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1813",
+  "version": "0.1.1815",
   "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"