@yemi33/minions 0.1.2448 → 0.1.2449

package/engine/{qa-runs.js → qa/runs.js}

@@ -28,7 +28,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
+const shared = require('../core/shared');
 const { mutateQaRuns, uid, ts, log } = shared;
 
 // Cap qa_runs so the table doesn't grow unboundedly
@@ -42,6 +42,13 @@ const QA_ARTIFACT_PATH_MAX = 2048;
 const QA_ARTIFACT_SEGMENT_MAX = 255;
 const QA_RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 
+// W-msb9kgs402813a97-c — journey coverage reported by the EXECUTE agent in its
+// qa-run-result sidecar. Caps mirror the artifact segment cap so a runaway
+// agent cannot inflate the run's `data` blob.
+const QA_JOURNEY_COVERAGE_MAX = 50;
+const QA_JOURNEY_COVERAGE_LIST_MAX = 50;
+const QA_JOURNEY_COVERAGE_STATUSES = Object.freeze(new Set(['passed', 'failed', 'skipped']));
+
 const QA_RUN_STATUS = Object.freeze({
   PENDING: 'pending',
   RUNNING: 'running',
@@ -59,7 +66,7 @@ const TERMINAL_STATUSES = new Set([
 // Allowed forward transitions. Anything not enumerated here is rejected.
 //
 // PR #2697 review fix (W-mpeiwz6k0005bf34-c — Ripley): the lifecycle hook in
-// engine/lifecycle.js parses the agent's qa-run-result.json sidecar and calls
+// engine/orchestration/lifecycle.js parses the agent's qa-run-result.json sidecar and calls
 // completeRun({status: 'passed'|'failed'|'errored'}) directly. It never calls
 // markRunning, because the agent may crash before writing the sidecar (in
 // which case the hook still needs to mark the run errored from `pending`).
@@ -183,17 +190,133 @@ function validateTransition(from, to) {
   }
 }
 
+/**
+ * Normalize one artifact record from the agent's qa-run-result sidecar.
+ *
+ * `journeyId` and `project` (W-msb9kgs402813a97-c) are OPTIONAL and only
+ * persisted when the agent actually declared them, so legacy qa-validate runs
+ * keep their historical record shape instead of gaining empty keys.
+ */
 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 {
+  const out = {
     type,
     path: p,
     label: typeof a.label === 'string' ? a.label : '',
     capturedAt: typeof a.capturedAt === 'string' && a.capturedAt ? a.capturedAt : ts(),
   };
+  const journeyId = _normalizeCoverageName(a.journeyId);
+  if (journeyId) out.journeyId = journeyId;
+  const project = _normalizeCoverageName(a.project);
+  if (project) out.project = project;
+  return out;
+}
+
+function _normalizeCoverageName(value) {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > QA_ARTIFACT_SEGMENT_MAX) return '';
+  return trimmed;
+}
+
+function _normalizeCoverageList(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const entry of value) {
+    const name = _normalizeCoverageName(entry);
+    if (name && !out.includes(name)) out.push(name);
+    if (out.length >= QA_JOURNEY_COVERAGE_LIST_MAX) break;
+  }
+  return out;
+}
+
+/**
+ * Normalize the sidecar's `journeyCoverage` array — what the run actually
+ * exercised, per journey declared by the DRAFT visual-journey manifest.
+ * Malformed entries are DROPPED rather than repaired: a coverage claim the
+ * engine cannot read is not a coverage claim, and the EXECUTE evidence gate
+ * (engine/qa/visual-journey.js#validateEvidenceCoverage) then fails closed on
+ * the journey it can no longer prove.
+ *
+ * @param {Array} entries
+ * @returns {Array<{journeyId:string,status:string,projects:string[],services:string[]}>}
+ */
+function normalizeJourneyCoverage(entries) {
+  if (!Array.isArray(entries)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const entry of entries) {
+    if (out.length >= QA_JOURNEY_COVERAGE_MAX) break;
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+    const journeyId = _normalizeCoverageName(entry.journeyId);
+    if (!journeyId || seen.has(journeyId)) continue;
+    const status = typeof entry.status === 'string' ? entry.status : '';
+    if (!QA_JOURNEY_COVERAGE_STATUSES.has(status)) continue;
+    seen.add(journeyId);
+    out.push({
+      journeyId,
+      status,
+      projects: _normalizeCoverageList(entry.projects),
+      services: _normalizeCoverageList(entry.services),
+    });
+  }
+  return out;
+}
+
+// W-msb9kgs402813a97-d — "primary" artifacts are the ones that ARE the visible
+// result of a QA run: screenshots and video. Everything else (logs, json, md,
+// traces) is supporting material. This classifier lives here because runs.js
+// owns the artifact contract (see normalizeArtifact above); the /qa Recent Runs
+// strip applies the same partition client-side in
+// dashboard/js/qa.js#_qaRenderArtifactPreviews — keep the two extension lists
+// in sync, same convention as _qaIsTerminalStatus ↔ TERMINAL_STATUSES.
+const PRIMARY_IMAGE_EXTS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg']);
+const PRIMARY_VIDEO_EXTS = new Set(['mp4', 'webm', 'ogg', 'mov']);
+
+// A session card is a summary, not a gallery — a handful of previews is enough
+// to answer "did this run capture anything?" without turning a 50-session poll
+// response into a payload problem.
+const QA_PRIMARY_ARTIFACT_DEFAULT_MAX = 4;
+
+function isPrimaryArtifact(a) {
+  if (!a || typeof a !== 'object') return false;
+  const p = typeof a.path === 'string' ? a.path : '';
+  if (!p) return false;
+  const type = String(a.type || '').toLowerCase();
+  if (type === 'screenshot' || type === 'image' || type === 'video') return true;
+  const ext = (p.match(/\.([a-z0-9]+)$/i) || ['', ''])[1].toLowerCase();
+  return PRIMARY_IMAGE_EXTS.has(ext) || PRIMARY_VIDEO_EXTS.has(ext);
+}
+
+/**
+ * Project a run's artifacts down to the bounded primary set a summary surface
+ * can render. Order is preserved; the return shape is exactly
+ * { type, path, label } so no internal bookkeeping (capturedAt) leaks into an
+ * API payload. Never throws on hostile input.
+ *
+ * @param {Array<object>} artifacts
+ * @param {number} [limit=QA_PRIMARY_ARTIFACT_DEFAULT_MAX]
+ * @returns {Array<{type: string, path: string, label: string}>}
+ */
+function selectPrimaryArtifacts(artifacts, limit = QA_PRIMARY_ARTIFACT_DEFAULT_MAX) {
+  if (!Array.isArray(artifacts)) return [];
+  const cap = Number.isFinite(limit) && limit > 0
+    ? Math.floor(limit)
+    : QA_PRIMARY_ARTIFACT_DEFAULT_MAX;
+  const out = [];
+  for (const a of artifacts) {
+    if (out.length >= cap) break;
+    if (!isPrimaryArtifact(a)) continue;
+    out.push({
+      type: typeof a.type === 'string' ? a.type : '',
+      path: a.path,
+      label: typeof a.label === 'string' ? a.label : '',
+    });
+  }
+  return out;
 }
 
 function createRunId() {
@@ -303,10 +426,13 @@ function markRunning(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?}
+ * @param {Array<object>} [opts.artifacts] - artifact records {type, path, label?, capturedAt?, journeyId?, project?}
+ * @param {Array<object>} [opts.journeyCoverage] - per-journey outcome records
+ *   {journeyId, status, projects[], services[]}. Omit entirely for legacy
+ *   qa-validate runs — the field is only stamped when the caller supplies it.
  * @returns {object} updated run
  */
-function completeRun(id, { status, summary, artifacts } = {}) {
+function completeRun(id, { status, summary, artifacts, journeyCoverage } = {}) {
   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(', ')}`);
@@ -314,6 +440,9 @@ function completeRun(id, { status, summary, artifacts } = {}) {
   const normalized = Array.isArray(artifacts)
     ? artifacts.map(normalizeArtifact).filter(Boolean)
     : [];
+  const normalizedCoverage = Array.isArray(journeyCoverage)
+    ? normalizeJourneyCoverage(journeyCoverage)
+    : null;
 
   let captured = null;
   let transitionError = null;
@@ -330,6 +459,7 @@ function completeRun(id, { status, summary, artifacts } = {}) {
       if (!Array.isArray(run.artifacts)) run.artifacts = [];
       run.artifacts.push(...normalized);
     }
+    if (normalizedCoverage) run.journeyCoverage = normalizedCoverage;
     captured = run;
     return runs;
   });
@@ -350,7 +480,7 @@ function getRun(id) {
 }
 
 function _readRuns() {
-  return require('./small-state-store').readQaRuns();
+  return require('../persistence/small-state-store').readQaRuns();
 }
 
 /**
@@ -436,36 +566,169 @@ function _isSafeRunId(id) {
   return QA_RUN_ID_RE.test(id);
 }
 
+// W-msaklqb701jy584d — evidence-based cleanup for abandoned pending runs.
+//
+// deleteQaRun is terminal-only by design so an operator can't vacuum a live QA
+// agent out from under itself. That left one class of record permanently
+// undeletable through the API: a `pending` run created by a stray process,
+// never dispatched, owning nothing, whose runbook and managed target don't
+// exist. `evaluateOrphanedPendingRun` is the narrow escape hatch — EVERY
+// condition below must be independently provable before
+// deleteQaRun(id, { allowOrphanedPending: true }) will remove the record. Any
+// unreadable ownership source fails CLOSED (not orphaned), because leaving a
+// stale row costs nothing while deleting an owned one loses QA history.
+const QA_ORPHAN_MIN_AGE_MS = 24 * 60 * 60 * 1000;
+
+function _parseTsMs(value) {
+  if (typeof value !== 'string' || !value) return NaN;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : NaN;
+}
+
+// { known } is false when the source could not be read at all — the caller
+// must then refuse the delete rather than assume "no owner".
+function _runSessionOwnership(id) {
+  try {
+    const sessions = require('./sessions').listSessions({});
+    if (!Array.isArray(sessions)) return { known: false, owned: false };
+    return { known: true, owned: sessions.some(s => s && s.qaRunId === id) };
+  } catch (_e) {
+    return { known: false, owned: false };
+  }
+}
+
+function _runWorkItemOwnership(id) {
+  try {
+    const items = require('../planning/work-items-store').readAllWorkItems();
+    if (!Array.isArray(items)) return { known: false, owned: false };
+    return {
+      known: true,
+      owned: items.some(wi => wi && wi.meta && wi.meta.qaRunId === id),
+    };
+  } catch (_e) {
+    return { known: false, owned: false };
+  }
+}
+
+/**
+ * Decide whether a run is a provably-orphaned abandoned pending record.
+ *
+ * @param {string} id - run id
+ * @param {object} [opts]
+ * @param {number} [opts.now] - epoch ms, injectable for tests
+ * @param {number} [opts.minAgeMs] - minimum age before a pending run qualifies
+ * @returns {{id: string, exists: boolean, status: string|null, orphaned: boolean,
+ *            reason: string|null, ageMs?: number}}
+ *   `reason` names the first condition that failed, and is null when orphaned.
+ */
+function evaluateOrphanedPendingRun(id, { now = Date.now(), minAgeMs = QA_ORPHAN_MIN_AGE_MS } = {}) {
+  const result = { id, exists: false, status: null, orphaned: false, reason: null };
+  if (!_isSafeRunId(id)) { result.reason = 'invalid_id'; return result; }
+
+  const run = getRun(id);
+  if (!run) { result.reason = 'not_found'; return result; }
+  result.exists = true;
+  result.status = run.status;
+
+  // Never touch an active run: `running` is live, and any pending run that
+  // already started, completed, captured artifacts, or carries a work item is
+  // owned, not abandoned.
+  if (run.status !== QA_RUN_STATUS.PENDING) { result.reason = 'status_not_pending'; return result; }
+  if (run.startedAt) { result.reason = 'already_started'; return result; }
+  if (run.completedAt) { result.reason = 'already_completed'; return result; }
+  if (Array.isArray(run.artifacts) && run.artifacts.length) { result.reason = 'has_artifacts'; return result; }
+  if (run.workItemId) { result.reason = 'work_item_owned'; return result; }
+
+  // Age gate: covers the window where a dispatch created the run and is still
+  // about to back-fill its work item / session linkage.
+  const createdMs = _parseTsMs(run.createdAt);
+  if (!Number.isFinite(createdMs)) { result.reason = 'unknown_age'; return result; }
+  result.ageMs = now - createdMs;
+  if (result.ageMs < minAgeMs) { result.reason = 'too_recent'; return result; }
+
+  const session = _runSessionOwnership(id);
+  if (!session.known) { result.reason = 'session_ownership_unknown'; return result; }
+  if (session.owned) { result.reason = 'session_owned'; return result; }
+
+  const workItem = _runWorkItemOwnership(id);
+  if (!workItem.known) { result.reason = 'work_item_ownership_unknown'; return result; }
+  if (workItem.owned) { result.reason = 'work_item_owned'; return result; }
+
+  let runbook;
+  try { runbook = require('./runbooks').getRunbook(run.runbookId); }
+  catch (_e) { result.reason = 'runbook_lookup_failed'; return result; }
+  if (runbook) { result.reason = 'runbook_exists'; return result; }
+
+  let target;
+  try { target = require('../processes/managed-spawn').getManagedSpecByName(run.targetName); }
+  catch (_e) { result.reason = 'target_lookup_failed'; return result; }
+  if (target) { result.reason = 'target_exists'; return result; }
+
+  result.orphaned = true;
+  return result;
+}
+
 /**
  * Hard-delete a terminal-status run record and best-effort remove its
  * artifact directory. Result envelope (matches PR #3008 shape so the
  * dashboard DELETE /api/qa/runs/<id> handler stays generic):
  *
- *   { ok: true,  id, artifactsRemoved: bool }
- *   { ok: false, error: 'invalid_id' | 'not_found' | 'not_terminal',
- *     currentStatus?: string }
+ *   { ok: true,  id, artifactsRemoved: bool, deletedAs: 'terminal' | 'orphaned-pending' }
+ *   { ok: false, error: 'invalid_id' | 'not_found' | 'not_terminal' | 'not_orphaned',
+ *     currentStatus?: string, reason?: string }
  *
  * Caller must cancel/complete the run via the lifecycle helpers before
  * deletion — running/pending runs are refused so an operator can't vacuum a
- * live QA agent out from under itself. The artifact rmSync runs OUTSIDE
- * the lock, with a path.resolve + startsWith() belt-and-braces sandbox.
+ * live QA agent out from under itself. `allowOrphanedPending` opts into the
+ * single narrow exception documented on evaluateOrphanedPendingRun; a pending
+ * run that fails ANY of its conditions is still refused, with `not_orphaned`
+ * naming the failed condition. The artifact rmSync runs OUTSIDE the lock, with
+ * a path.resolve + startsWith() belt-and-braces sandbox.
  *
  * @param {string} id - run id (must pass _isSafeRunId)
+ * @param {object} [opts]
+ * @param {boolean} [opts.allowOrphanedPending] - allow provably-orphaned pending runs
  * @returns {object} envelope (see above)
  */
-function deleteQaRun(id) {
+function deleteQaRun(id, { allowOrphanedPending = false } = {}) {
   if (!_isSafeRunId(id)) return { ok: false, error: 'invalid_id' };
+
+  // Orphan evidence gathering reads QA sessions, work items, runbook files and
+  // managed specs — none of that may run inside a mutateQaRuns callback. So
+  // evaluate first, then re-assert the cheap in-record invariants inside the
+  // transaction: a concurrent markRunning() between the two still wins.
+  let orphanEval = null;
+  if (allowOrphanedPending) {
+    orphanEval = evaluateOrphanedPendingRun(id);
+    if (orphanEval.exists && !orphanEval.orphaned && !TERMINAL_STATUSES.has(orphanEval.status)) {
+      return {
+        ok: false,
+        error: 'not_orphaned',
+        currentStatus: orphanEval.status,
+        reason: orphanEval.reason,
+      };
+    }
+  }
+
   let captured = null;
   let notFound = false;
   let notTerminal = null;
+  let deletedAs = 'terminal';
   mutateQaRuns((runs) => {
     if (!Array.isArray(runs)) return runs;
     const idx = runs.findIndex(r => r && r.id === id);
     if (idx < 0) { notFound = true; return runs; }
     const run = runs[idx];
     if (!TERMINAL_STATUSES.has(run.status)) {
-      notTerminal = run.status;
-      return runs;
+      const orphanCleanup = allowOrphanedPending
+        && !!orphanEval && orphanEval.orphaned
+        && run.status === QA_RUN_STATUS.PENDING
+        && !run.startedAt && !run.completedAt && !run.workItemId;
+      if (!orphanCleanup) {
+        notTerminal = run.status;
+        return runs;
+      }
+      deletedAs = 'orphaned-pending';
     }
     captured = run;
     runs.splice(idx, 1);
@@ -488,7 +751,7 @@ function deleteQaRun(id) {
   } catch (e) {
     log('warn', `qa-runs: rm artifacts dir failed for ${id}: ${e.message}`);
   }
-  return { ok: true, id, artifactsRemoved, run: captured };
+  return { ok: true, id, artifactsRemoved, deletedAs, run: captured };
 }
 
 /**
@@ -527,16 +790,24 @@ module.exports = {
   completeRun,
   setRunWorkItemId,
   deleteQaRun,
+  evaluateOrphanedPendingRun,
+  QA_ORPHAN_MIN_AGE_MS,
   _isSafeRunId,
   getRun,
   listRuns,
   getRunsForWorkItem,
   summarizeRunsForStatus,
+  isPrimaryArtifact,
+  selectPrimaryArtifacts,
+  QA_PRIMARY_ARTIFACT_DEFAULT_MAX,
   // Exposed for tests:
   validateTransition,
   isValidStatus,
+  normalizeArtifact, normalizeJourneyCoverage, // exported for testing
   QA_RUNS_MAX_RECORDS,
   QA_RUN_ID_MAX,
   QA_ARTIFACT_PATH_MAX,
   QA_ARTIFACT_SEGMENT_MAX,
+  QA_JOURNEY_COVERAGE_MAX,
+  QA_JOURNEY_COVERAGE_STATUSES,
 };