@yemi33/minions 0.1.1992 → 0.1.1994

package/dashboard/js/command-center.js

@@ -179,48 +179,130 @@ async function _ccDashboardHealth() {
   }
 }
 
+// Pure predicate — extracted so test/unit/dashboard-resilience.test.js can
+// behaviour-test the new-vs-old-instance decision without standing up a DOM.
+// Returns true only when newDashId is provably a NEW dashboard process:
+//   - When preRestartDashId is known, any difference proves a different process.
+//   - When preRestartDashId is unknown (page just loaded, _lastStatus empty),
+//     accept only if newDashId parses to a timestamp strictly AFTER the click.
+//     Guards against the still-alive OLD dashboard answering /api/status
+//     before its kill lands (~1s into the restart child's lifetime).
+function _ccIsNewDashboardInstance(preRestartDashId, newDashId, clickTimeMs) {
+  if (!newDashId) return false;
+  if (preRestartDashId) return newDashId !== preRestartDashId;
+  var parsed = Date.parse(newDashId);
+  return Number.isFinite(parsed) && parsed > clickTimeMs;
+}
+
 // Triggered by the CC "Restart Minions" recovery button when a stale dashboard
 // connection is killing CC streams with "Failed to fetch". Spawns the same
 // `minions restart` flow as the CLI command (kills + respawns engine AND
-// dashboard). Then polls /api/health until the new dashboard is online before
-// reloading — fixed timers either fired too early (reload hits dead port) or
-// fired after the fetch threw (dashboard killed mid-response → 500ms reload
-// to nothing).
+// dashboard) and reloads once the NEW dashboard is up.
+//
+// W-mpehvbed0018e27d: previous version polled /api/health which returns 200
+// from EITHER the still-alive OLD dashboard (before the spawned restart child
+// finished its kill sequence) OR the NEW one. Reloading on the OLD instance
+// landed the page on a dying port; reloading on the NEW instance with a cold
+// status cache hung the freshly-reloaded page on its first /api/status fetch.
+// Both produced the "click does nothing / page still broken" symptoms.
+//
+// Fix:
+//   1. Capture pre-restart dashboardStartedAt before POSTing the restart
+//      (so we can detect the NEW instance vs the still-alive OLD one).
+//   2. Poll /api/status (not /api/health) — a 200 response proves the status
+//      cache has been built once, so the post-reload first request is warm.
+//   3. Only reload when _ccIsNewDashboardInstance() confirms a different
+//      dashboardStartedAt, with per-poll AbortController so a hanging cold
+//      rebuild can't starve the global deadline.
+//   4. Cache-bust the reload (?cb=) so an updated dashboard JS bundle is not
+//      served from the browser disk cache. location.replace() so the broken
+//      pre-restart URL doesn't pollute history.
 async function ccRestartMinions(btn) {
   if (btn) { try { btn.disabled = true; btn.textContent = 'Restarting...'; } catch {} }
-  // Fire and forget the POST. We do NOT await it — the dashboard often kills
-  // its own process before the response is flushed, so the fetch throws even
-  // though the restart child is happily running. Whatever the POST does, the
-  // next step (wait-for-healthy) is the truth.
+  var clickTimeMs = Date.now();
+
+  // Capture pre-restart dashboard instance ID BEFORE the POST so the polling
+  // step has a baseline to compare against. _lastStatus is populated by
+  // refresh.js's 4s poll; on a freshly-opened page it may still be null, so
+  // we fall back to a bounded /api/status fetch, then to clickTime-based
+  // detection inside _ccIsNewDashboardInstance.
+  var preRestartDashId = (window._lastStatus && window._lastStatus.version)
+    ? window._lastStatus.version.dashboardStartedAt : null;
+  if (!preRestartDashId) {
+    try {
+      var preCtl = new AbortController();
+      var preTimer = setTimeout(function() { preCtl.abort(); }, 2000);
+      try {
+        var preRes = await fetch('/api/status', { cache: 'no-store', signal: preCtl.signal });
+        if (preRes && preRes.ok) {
+          var preData = await preRes.json().catch(function() { return null; });
+          if (preData && preData.version) preRestartDashId = preData.version.dashboardStartedAt || null;
+        }
+      } finally { clearTimeout(preTimer); }
+    } catch { /* best-effort — clickTime fallback inside helper still covers us */ }
+  }
+
+  // Fire-and-forget the restart POST. We do NOT await it — the dashboard often
+  // kills its own process before the response is flushed, so the fetch throws
+  // even though the restart child (a detached `minions restart`) is happily
+  // running. The polling loop is the source of truth for completion.
   try {
     fetch('/api/dashboard/restart', { method: 'POST', headers: { 'Content-Type': 'application/json' } })
       .catch(function() { /* dashboard process likely killed mid-response — expected */ });
   } catch { /* network layer threw before fetch even queued — also expected */ }
   if (btn) { try { btn.textContent = 'Restarting Minions — waiting for new dashboard...'; } catch {} }
+
   var startedAt = Date.now();
-  var DEADLINE_MS = 60000;
+  var DEADLINE_MS = 90000; // generous: cold Windows AV + status rebuild can eat 30s
   var INTERVAL_MS = 500;
-  function pollHealth() {
-    fetch('/api/health', { cache: 'no-store' }).then(function(res) {
-      if (res && res.ok) {
-        if (btn) { try { btn.textContent = 'Dashboard online — reloading...'; } catch {} }
-        try { location.reload(); } catch {}
-        return;
+  var POLL_TIMEOUT_MS = 5000;
+
+  function reloadWithCacheBust(label) {
+    if (btn) { try { btn.textContent = label; } catch {} }
+    try {
+      var url = new URL(location.href);
+      url.searchParams.set('cb', String(Date.now()));
+      location.replace(url.toString());
+    } catch {
+      try { location.reload(); } catch {}
+    }
+  }
+
+  async function pollStatus() {
+    var ctl = new AbortController();
+    var pollTimer = setTimeout(function() { ctl.abort(); }, POLL_TIMEOUT_MS);
+    var shouldRetry = false;
+    try {
+      var res = await fetch('/api/status', { cache: 'no-store', signal: ctl.signal });
+      if (!res || !res.ok) { shouldRetry = true; }
+      else {
+        var data = await res.json().catch(function() { return null; });
+        var newDashId = (data && data.version) ? data.version.dashboardStartedAt : null;
+        if (_ccIsNewDashboardInstance(preRestartDashId, newDashId, clickTimeMs)) {
+          reloadWithCacheBust('Dashboard online — reloading...');
+          return;
+        }
+        // Same instance (or unparseable) — old dashboard still answering or
+        // new dashboard ID hasn't advanced past clickTime yet. Keep polling.
+        shouldRetry = true;
       }
-      throw new Error('not ok');
-    }).catch(function() {
+    } catch { shouldRetry = true; }
+    finally { clearTimeout(pollTimer); }
+    if (shouldRetry) {
       if (Date.now() - startedAt > DEADLINE_MS) {
-        if (btn) { try { btn.textContent = 'Restart timed out — reloading...'; } catch {} }
-        try { location.reload(); } catch {}
+        // Last-ditch reload. refresh.js's auto-detection (4s poll on
+        // dashboardStartedAt change) will pick up the new instance once it
+        // does come up.
+        reloadWithCacheBust('Restart timed out — reloading anyway...');
         return;
       }
-      setTimeout(pollHealth, INTERVAL_MS);
-    });
+      setTimeout(pollStatus, INTERVAL_MS);
+    }
   }
-  // Don't poll immediately — give the restart child a moment to actually kill
-  // the old dashboard. If we polled at t=0 we'd hit the OLD (dying) dashboard
-  // and prematurely reload before the new one is up.
-  setTimeout(pollHealth, 2000);
+
+  // Give the restart child a moment to actually kill the old dashboard before
+  // we start polling. Polling at t=0 risks confirming the dying old instance.
+  setTimeout(pollStatus, 2000);
 }
 
 function _ccIsReconnectableStreamError(err) {

package/dashboard.js

@@ -8427,6 +8427,141 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     return;
   }
 
+  // ── QA runs + artifact serving (W-mpeiwz6k0005bf34-b) ──────────────────────
+  // Lifecycle for QA validation runs lives in engine/qa-runs.js. These three
+  // handlers expose: list (with optional ?limit= + ?status= filters), single-
+  // record fetch, and a tightly-sandboxed artifact serving endpoint rooted at
+  // engine/qa-artifacts/.
+
+  // Extension → Content-Type for served artifacts. Anything not listed gets
+  // application/octet-stream (the SPA still renders unknown attachments via
+  // the artifact download link).
+  const _QA_ARTIFACT_MIME = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.gif': 'image/gif',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.log': 'text/plain; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+  };
+
+  function _qaArtifactContentType(filename) {
+    const ext = path.extname(filename || '').toLowerCase();
+    return _QA_ARTIFACT_MIME[ext] || 'application/octet-stream';
+  }
+
+  // Safe-segment validator for runId / file. URL segments must not contain
+  // path separators, traversal markers, null bytes, or look like an absolute
+  // path. Rejecting at the segment level (before any path.join) closes the
+  // traversal hole before resolution can normalize ".." away.
+  function _qaIsSafeSegment(s) {
+    if (typeof s !== 'string') return false;
+    if (!s || s.length > 255) return false;
+    if (s.includes('\0')) return false;
+    if (s.includes('/') || s.includes('\\')) return false;
+    if (s === '.' || s === '..') return false;
+    if (s.includes('..')) return false;
+    if (path.isAbsolute(s)) return false;
+    if (/^[a-zA-Z]:/.test(s)) return false;
+    return true;
+  }
+
+  function handleQaRunsList(req, res) {
+    try {
+      const qa = require('./engine/qa-runs');
+      const u = new URL(req.url, 'http://x');
+      const limitRaw = u.searchParams.get('limit');
+      const statusRaw = u.searchParams.get('status');
+      const opts = {};
+      if (limitRaw != null && limitRaw !== '') {
+        const n = Number(limitRaw);
+        if (!Number.isFinite(n) || n <= 0) {
+          return jsonReply(res, 400, { error: 'limit must be a positive number' }, req);
+        }
+        opts.limit = Math.floor(n);
+      }
+      if (statusRaw) {
+        if (!qa.isValidStatus(statusRaw)) {
+          return jsonReply(res, 400, {
+            error: `status must be one of ${Object.values(qa.QA_RUN_STATUS).join(', ')}`,
+          }, req);
+        }
+        opts.status = statusRaw;
+      }
+      const runs = qa.listRuns(opts);
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      return jsonReply(res, 200, { runs, generatedAt: new Date().toISOString() }, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
+  function handleQaRunsById(req, res, match) {
+    try {
+      const qa = require('./engine/qa-runs');
+      const id = decodeURIComponent(match[1] || '');
+      if (!_qaIsSafeSegment(id)) {
+        return jsonReply(res, 400, { error: 'invalid run id' }, req);
+      }
+      const run = qa.getRun(id);
+      if (!run) return jsonReply(res, 404, { error: 'qa run not found' }, req);
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      return jsonReply(res, 200, { run }, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
+  function handleQaArtifact(req, res, match) {
+    try {
+      const qa = require('./engine/qa-runs');
+      const runId = decodeURIComponent(match[1] || '');
+      const file = decodeURIComponent(match[2] || '');
+      // Per-segment validation rejects ../, absolute, and any embedded
+      // separator before path.join — 403 (traversal attempt) vs 404 (miss).
+      if (!_qaIsSafeSegment(runId) || !_qaIsSafeSegment(file)) {
+        return jsonReply(res, 403, { error: 'invalid artifact path (traversal attempt)' }, req);
+      }
+      const base = path.resolve(qa.qaArtifactsDir());
+      const target = path.resolve(base, runId, file);
+      // Belt-and-braces: ensure the resolved absolute path is still under
+      // base. Adding the trailing separator avoids the "/qa-artifacts2/"
+      // prefix-equality bug if a sibling directory ever shares the same
+      // leading characters.
+      const baseWithSep = base.endsWith(path.sep) ? base : base + path.sep;
+      if (target !== base && !target.startsWith(baseWithSep)) {
+        return jsonReply(res, 403, { error: 'invalid artifact path (escapes qa-artifacts root)' }, req);
+      }
+      let real;
+      try { real = fs.realpathSync(target); }
+      catch (e) {
+        if (e && e.code === 'ENOENT') return jsonReply(res, 404, { error: 'artifact not found' }, req);
+        throw e;
+      }
+      // Symlinks: realpath must still land under qa-artifacts (after resolving
+      // base symlinks too, so a legitimate symlinked base dir works).
+      const realBase = (() => { try { return fs.realpathSync(base); } catch { return base; } })();
+      const realBaseWithSep = realBase.endsWith(path.sep) ? realBase : realBase + path.sep;
+      if (real !== realBase && !real.startsWith(realBaseWithSep)) {
+        return jsonReply(res, 403, { error: 'artifact symlink points outside qa-artifacts root' }, req);
+      }
+      const stat = fs.statSync(real);
+      if (!stat.isFile()) return jsonReply(res, 404, { error: 'artifact not found' }, req);
+      res.setHeader('Content-Type', _qaArtifactContentType(file));
+      res.setHeader('Content-Length', String(stat.size));
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.statusCode = 200;
+      fs.createReadStream(real).pipe(res);
+      return;
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
   // ── Route Registry ──────────────────────────────────────────────────────────
   // Order matters: specific routes before general ones (e.g., /api/plans/approve before /api/plans/:file)
 
@@ -8497,6 +8632,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     // 64KB initial tail, fs.watchFile poll for appends, auto-close when
     // the spec is removed from state.
     { method: 'GET', path: /^\/api\/managed-processes\/log-stream\/([^?]+)$/, template: '/api/managed-processes/log-stream/<name>', desc: 'SSE tail-and-stream of <log_path> for a managed spec (managed-spawn). Optional ?tail=N initial-tail-bytes (default 65536).', handler: handleManagedProcessesLogStream },
+    // QA runs + artifact serving (W-mpeiwz6k0005bf34-b). Run-record lifecycle
+    // lives in engine/qa-runs.js. Artifact serving is sandboxed to
+    // engine/qa-artifacts/ via per-segment validation + realpath check;
+    // traversal attempts return 403, missing files return 404.
+    { method: 'GET', path: '/api/qa/runs', desc: 'List QA validation runs (newest first). Optional ?limit=N and ?status=pending|running|passed|failed|errored filters.', handler: handleQaRunsList },
+    { method: 'GET', path: /^\/api\/qa\/runs\/([^/?]+)$/, template: '/api/qa/runs/<id>', desc: 'Fetch a single QA run record by id.', handler: handleQaRunsById },
+    { method: 'GET', path: /^\/api\/qa\/artifacts\/([^/?]+)\/([^?]+)$/, template: '/api/qa/artifacts/<runId>/<file>', desc: 'Serve a QA artifact file (image/video/log). Sandboxed to engine/qa-artifacts/; rejects path traversal with 403.', handler: handleQaArtifact },
     { method: 'GET', path: '/api/hot-reload', desc: 'SSE stream for dashboard hot-reload notifications', handler: (req, res) => {
       res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive' });
       res.write('data: connected\n\n');
@@ -9379,6 +9521,17 @@ if (require.main === module) {
       } catch { /* warm-up is best-effort */ }
     });
 
+    // Pre-warm /api/status cache (W-mpehvbed0018e27d). The CC "Restart Minions"
+    // recovery button polls /api/status and only reloads once the new dashboard
+    // reports a NEW dashboardStartedAt. Without warming, the first /api/status
+    // request (from the button OR from refresh.js OR from the post-reload page
+    // load) triggers a cold getStatus() rebuild that takes 2-5s on Windows+AV
+    // and stalls the freshly-reloaded page in a spinner. Warming on listen
+    // means the first request hits the cached buffer.
+    setImmediate(() => {
+      try { getStatusJson(); } catch { /* warm-up is best-effort */ }
+    });
+
     // ─── Engine Watchdog ─────────────────────────────────────────────────────
     // Every 30s, check if engine PID is alive. If dead but control.json says
     // running, auto-restart it. Prevents silent engine death.

package/engine/cooldown.js

@@ -44,6 +44,8 @@ function loadCooldowns() {
   if (!saved) return;
   const now = Date.now();
   for (const [k, v] of Object.entries(saved)) {
+    // Skip malformed entries (null, primitives, missing timestamp)
+    if (!v || typeof v !== 'object' || typeof v.timestamp !== 'number') continue;
     // Prune entries older than 24 hours
     if (now - v.timestamp < 24 * 60 * 60 * 1000) {
       dispatchCooldowns.set(k, v);

package/engine/qa-runs.js

@@ -0,0 +1,278 @@
+/**
+ * engine/qa-runs.js — Lifecycle + persistence for QA validation runs.
+ *
+ * One run record represents a single dispatch of a validation runbook against
+ * a managed target. Records carry status, timing, work-item linkage, and an
+ * artifacts array (screenshots, logs, videos captured during the run).
+ *
+ * State file: engine/qa-runs.json (single file, all runs across all projects).
+ * Artifacts live on disk under engine/qa-artifacts/<runId>/ — the run record
+ * stores relative paths (`type`, `path`, `label`, `capturedAt`), and the
+ * dashboard exposes them through GET /api/qa/artifacts/<runId>/<file>.
+ *
+ * Concurrency: every mutation goes through mutateJsonFileLocked per
+ * CLAUDE.md best-practice; callbacks are synchronous and never await.
+ *
+ * Status state machine:
+ *
+ *   pending ──▶ running ──▶ passed
+ *                       ╲──▶ failed
+ *                       ╲──▶ errored
+ *
+ * Illegal transitions throw with a descriptive error. Terminal statuses
+ * (passed / failed / errored) cannot transition further.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const shared = require('./shared');
+const { mutateJsonFileLocked, uid, ts, log } = shared;
+
+const QA_RUN_STATUS = Object.freeze({
+  PENDING: 'pending',
+  RUNNING: 'running',
+  PASSED: 'passed',
+  FAILED: 'failed',
+  ERRORED: 'errored',
+});
+
+const TERMINAL_STATUSES = new Set([
+  QA_RUN_STATUS.PASSED,
+  QA_RUN_STATUS.FAILED,
+  QA_RUN_STATUS.ERRORED,
+]);
+
+// Allowed forward transitions. Anything not enumerated here is rejected.
+const ALLOWED_TRANSITIONS = {
+  [QA_RUN_STATUS.PENDING]: new Set([QA_RUN_STATUS.RUNNING]),
+  [QA_RUN_STATUS.RUNNING]: new Set([
+    QA_RUN_STATUS.PASSED,
+    QA_RUN_STATUS.FAILED,
+    QA_RUN_STATUS.ERRORED,
+  ]),
+  [QA_RUN_STATUS.PASSED]: new Set(),
+  [QA_RUN_STATUS.FAILED]: new Set(),
+  [QA_RUN_STATUS.ERRORED]: new Set(),
+};
+
+// Dynamic paths — respect MINIONS_TEST_DIR for test isolation.
+function qaRunsPath() {
+  return path.join(shared.MINIONS_DIR, 'engine', 'qa-runs.json');
+}
+
+function qaArtifactsDir() {
+  return path.join(shared.MINIONS_DIR, 'engine', 'qa-artifacts');
+}
+
+function qaArtifactsDirForRun(runId) {
+  return path.join(qaArtifactsDir(), runId);
+}
+
+function isValidStatus(status) {
+  return Object.values(QA_RUN_STATUS).includes(status);
+}
+
+function validateTransition(from, to) {
+  if (!isValidStatus(from)) throw new Error(`qa-runs: invalid source status "${from}"`);
+  if (!isValidStatus(to)) throw new Error(`qa-runs: invalid target status "${to}"`);
+  const allowed = ALLOWED_TRANSITIONS[from];
+  if (!allowed.has(to)) {
+    throw new Error(`qa-runs: illegal status transition ${from} -> ${to}`);
+  }
+}
+
+function normalizeArtifact(a) {
+  if (!a || typeof a !== 'object') return null;
+  const type = typeof a.type === 'string' ? a.type : '';
+  const p = typeof a.path === 'string' ? a.path : '';
+  if (!type || !p) return null;
+  return {
+    type,
+    path: p,
+    label: typeof a.label === 'string' ? a.label : '',
+    capturedAt: typeof a.capturedAt === 'string' && a.capturedAt ? a.capturedAt : ts(),
+  };
+}
+
+/**
+ * Create a new run record in 'pending' status. Also pre-creates the per-run
+ * artifact directory so the agent can drop files into it.
+ *
+ * @param {object} opts
+ * @param {string} opts.runbookId - id of the runbook being executed
+ * @param {string} opts.targetName - managed-spawn target name being validated
+ * @param {string} [opts.project] - project name (optional)
+ * @param {string} [opts.workItemId] - originating work-item id (optional)
+ * @returns {object} the created run record
+ */
+function createRun({ runbookId, targetName, project, workItemId } = {}) {
+  if (!runbookId || typeof runbookId !== 'string') throw new Error('qa-runs: runbookId is required');
+  if (!targetName || typeof targetName !== 'string') throw new Error('qa-runs: targetName is required');
+
+  const run = {
+    id: 'qarun-' + uid(),
+    runbookId,
+    targetName,
+    project: project || null,
+    workItemId: workItemId || null,
+    status: QA_RUN_STATUS.PENDING,
+    startedAt: null,
+    completedAt: null,
+    artifacts: [],
+    summary: null,
+    createdAt: ts(),
+  };
+
+  mutateJsonFileLocked(qaRunsPath(), (runs) => {
+    if (!Array.isArray(runs)) runs = [];
+    runs.push(run);
+    return runs;
+  }, { defaultValue: [] });
+
+  // Pre-create the artifact directory outside the lock — directory creation
+  // is idempotent and slow file I/O must never run while holding the lock.
+  try { fs.mkdirSync(qaArtifactsDirForRun(run.id), { recursive: true }); } catch (e) {
+    log('warn', `qa-runs: mkdir artifacts dir failed for ${run.id}: ${e.message}`);
+  }
+
+  return run;
+}
+
+/**
+ * Transition pending -> running. Stamps startedAt. Throws on illegal source state.
+ * @param {string} id
+ * @returns {object} updated run
+ */
+function markRunning(id) {
+  if (!id) throw new Error('qa-runs: id is required');
+  let captured = null;
+  let transitionError = null;
+  mutateJsonFileLocked(qaRunsPath(), (runs) => {
+    if (!Array.isArray(runs)) runs = [];
+    const run = runs.find(r => r && r.id === id);
+    if (!run) { transitionError = new Error(`qa-runs: run not found: ${id}`); return runs; }
+    try { validateTransition(run.status, QA_RUN_STATUS.RUNNING); }
+    catch (e) { transitionError = e; return runs; }
+    run.status = QA_RUN_STATUS.RUNNING;
+    run.startedAt = ts();
+    captured = run;
+    return runs;
+  }, { defaultValue: [] });
+  if (transitionError) throw transitionError;
+  return captured;
+}
+
+/**
+ * Transition running -> passed|failed|errored. Stamps completedAt, records
+ * summary, appends artifacts. Throws on illegal source state.
+ *
+ * @param {string} id
+ * @param {object} opts
+ * @param {string} opts.status - 'passed' | 'failed' | 'errored'
+ * @param {string} [opts.summary] - human-readable summary
+ * @param {Array<object>} [opts.artifacts] - artifact records {type, path, label?, capturedAt?}
+ * @returns {object} updated run
+ */
+function completeRun(id, { status, summary, artifacts } = {}) {
+  if (!id) throw new Error('qa-runs: id is required');
+  if (!TERMINAL_STATUSES.has(status)) {
+    throw new Error(`qa-runs: completeRun status must be one of ${[...TERMINAL_STATUSES].join(', ')}`);
+  }
+  const normalized = Array.isArray(artifacts)
+    ? artifacts.map(normalizeArtifact).filter(Boolean)
+    : [];
+
+  let captured = null;
+  let transitionError = null;
+  mutateJsonFileLocked(qaRunsPath(), (runs) => {
+    if (!Array.isArray(runs)) runs = [];
+    const run = runs.find(r => r && r.id === id);
+    if (!run) { transitionError = new Error(`qa-runs: run not found: ${id}`); return runs; }
+    try { validateTransition(run.status, status); }
+    catch (e) { transitionError = e; return runs; }
+    run.status = status;
+    run.completedAt = ts();
+    if (typeof summary === 'string') run.summary = summary;
+    if (normalized.length) {
+      if (!Array.isArray(run.artifacts)) run.artifacts = [];
+      run.artifacts.push(...normalized);
+    }
+    captured = run;
+    return runs;
+  }, { defaultValue: [] });
+  if (transitionError) throw transitionError;
+  return captured;
+}
+
+/**
+ * Lookup a single run by id.
+ * @param {string} id
+ * @returns {object|null}
+ */
+function getRun(id) {
+  if (!id) return null;
+  const runs = shared.safeJsonArr(qaRunsPath());
+  const run = runs.find(r => r && r.id === id);
+  return run || null;
+}
+
+/**
+ * List runs, newest first, optionally filtered by status, capped by limit.
+ * @param {object} [opts]
+ * @param {number} [opts.limit] - max records to return (no cap when omitted)
+ * @param {string} [opts.status] - filter by status
+ * @returns {Array<object>}
+ */
+function listRuns({ limit, status } = {}) {
+  let runs = shared.safeJsonArr(qaRunsPath());
+  if (!Array.isArray(runs)) return [];
+  if (status) {
+    if (!isValidStatus(status)) return [];
+    runs = runs.filter(r => r && r.status === status);
+  }
+  // Newest first by createdAt (fallback to id for ties — uid() is monotonic).
+  runs = runs.slice().sort((a, b) => {
+    const ac = (a && a.createdAt) || '';
+    const bc = (b && b.createdAt) || '';
+    if (ac === bc) return ((b && b.id) || '').localeCompare((a && a.id) || '');
+    return ac < bc ? 1 : -1;
+  });
+  const n = Number(limit);
+  if (Number.isFinite(n) && n > 0) runs = runs.slice(0, Math.floor(n));
+  return runs;
+}
+
+/**
+ * All runs linked to a work item, newest first.
+ * @param {string} wi - work-item id
+ * @returns {Array<object>}
+ */
+function getRunsForWorkItem(wi) {
+  if (!wi) return [];
+  const runs = shared.safeJsonArr(qaRunsPath());
+  return runs
+    .filter(r => r && r.workItemId === wi)
+    .sort((a, b) => {
+      const ac = a.createdAt || '';
+      const bc = b.createdAt || '';
+      return ac < bc ? 1 : -1;
+    });
+}
+
+module.exports = {
+  QA_RUN_STATUS,
+  TERMINAL_STATUSES,
+  ALLOWED_TRANSITIONS,
+  qaRunsPath,
+  qaArtifactsDir,
+  qaArtifactsDirForRun,
+  createRun,
+  markRunning,
+  completeRun,
+  getRun,
+  listRuns,
+  getRunsForWorkItem,
+  // Exposed for tests:
+  validateTransition,
+  isValidStatus,
+};

package/package.json

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