@yemi33/minions 0.1.2447 → 0.1.2449

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

@@ -31,7 +31,7 @@
  * Concurrency: every mutation goes through shared.mutateQaSessions, which
  * routes to small-state-store.applyQaSessionsMutation inside a SQLite
  * transaction (BEGIN IMMEDIATE). Callbacks are synchronous and never await. Slow filesystem work
- * (qa-tests/<id>/ scaffolding, dispatch enqueueing) runs OUTSIDE the lock.
+ * (qa-tests/<id>/ scaffolding, engine wakeup requests) runs OUTSIDE the lock.
  *
  * Path-traversal hardening: sessionId is generated by createSession() with a
  * uid suffix, but the module still treats every callsite as untrusted —
@@ -40,16 +40,18 @@
  * _isSafeId (PR #2694 review feedback).
  *
  * Persistence: SQLite (engine/state.db, `qa_sessions` table). Capped at
- * QA_SESSIONS_MAX_RECORDS via createSession-time rotation.
+ * QA_SESSIONS_MAX_RECORDS via createSession-time rotation. Records otherwise
+ * leave only through deleteSession(), which is terminal-only (W-msb4vgj500zbb008).
  */
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
+const shared = require('../core/shared');
+const visualJourney = require('./visual-journey');
 const { mutateQaSessions, uid, ts, log } = shared;
 
 function _readSessions() {
-  return require('./small-state-store').readQaSessions();
+  return require('../persistence/small-state-store').readQaSessions();
 }
 
 // Sessions cost more than runs (3 WIs, a
@@ -247,6 +249,70 @@ function _validateCapture(capture) {
   return errors;
 }
 
+/**
+ * The canonical project list a spec declares, in declaration order.
+ *
+ * `spec.projects` (multi) wins over the legacy single-string `spec.project`,
+ * matching createSession's normalization. Returns `[]` for a central session.
+ * Shared by validateSpec and createSession so "which projects does this spec
+ * name?" cannot drift between validation and persistence.
+ */
+function _specProjects(spec) {
+  if (Array.isArray(spec && spec.projects) && spec.projects.length > 0) {
+    return spec.projects.filter(_isNonEmptyString);
+  }
+  if (_isNonEmptyString(spec && spec.project)) return [spec.project];
+  return [];
+}
+
+/**
+ * W-msb9kgs402813a97-a — resolve which project owns DRAFT/EXECUTE.
+ *
+ * Explicit `spec.primaryProject` wins; otherwise the first declared project.
+ * Returns null for a central (project-less) session.
+ */
+function _resolvePrimaryProject(spec, projects) {
+  const list = Array.isArray(projects) ? projects : [];
+  if (_isNonEmptyString(spec && spec.primaryProject) && list.includes(spec.primaryProject)) {
+    return spec.primaryProject;
+  }
+  return list.length > 0 ? list[0] : null;
+}
+
+/**
+ * Keep only the projectTargets entries that name a declared project, so a
+ * persisted map can never route a work item to a project the session does not
+ * own. validateSpec already rejects unknown keys — this is the persistence-side
+ * belt to that suspenders.
+ */
+function _normalizeProjectTargets(spec, projects) {
+  const raw = spec && spec.projectTargets;
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const out = {};
+  for (const project of projects) {
+    if (Object.prototype.hasOwnProperty.call(raw, project) && raw[project]) {
+      out[project] = { ...raw[project] };
+    }
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+/**
+ * The QA target a given project's work item should be built against.
+ * `spec.projectTargets[project]` when declared, else the session-wide
+ * `spec.target`. Used by every work-item builder so a fanned-out SETUP no
+ * longer stamps the primary's target onto every co-service.
+ */
+function _targetForProject(session, project) {
+  const spec = (session && session.spec) || {};
+  const map = spec.projectTargets;
+  if (_isNonEmptyString(project) && map && typeof map === 'object' && !Array.isArray(map)
+      && map[project] && typeof map[project] === 'object') {
+    return map[project];
+  }
+  return spec.target;
+}
+
 /**
  * Validate a createSession spec. Returns { ok, errors }. Never throws.
  */
@@ -320,6 +386,45 @@ function validateSpec(spec) {
     }
   }
 
+  // W-msb9kgs402813a97-a — explicit primary + per-project targets. Both are
+  // validated against the SAME project list createSession normalizes to, so a
+  // spec can never persist a primary or a target keyed to a project the
+  // session does not own. Errors name the offending value AND the known
+  // projects — an operator hitting POST /api/qa/session gets a fix, not a
+  // shrug.
+  const declaredProjects = _specProjects(spec);
+  const knownProjects = declaredProjects.length ? declaredProjects.join(', ') : '(none)';
+
+  if (spec.primaryProject !== undefined && spec.primaryProject !== null) {
+    if (!_isNonEmptyString(spec.primaryProject)) {
+      errors.push('primaryProject must be a non-empty string when present');
+    } else if (spec.primaryProject.length > LIMITS.projectMax) {
+      errors.push(`primaryProject exceeds ${LIMITS.projectMax} chars`);
+    } else if (!declaredProjects.includes(spec.primaryProject)) {
+      errors.push(`primaryProject "${spec.primaryProject}" must be one of the session projects: ${knownProjects}`);
+    }
+  }
+
+  if (spec.projectTargets !== undefined && spec.projectTargets !== null) {
+    if (typeof spec.projectTargets !== 'object' || Array.isArray(spec.projectTargets)) {
+      errors.push('projectTargets must be a plain object keyed by project name');
+    } else {
+      const keys = Object.keys(spec.projectTargets);
+      if (keys.length > LIMITS.projectsMax) {
+        errors.push(`projectTargets exceeds ${LIMITS.projectsMax} entries`);
+      } else {
+        for (const key of keys) {
+          if (!declaredProjects.includes(key)) {
+            errors.push(`projectTargets["${key}"] must be one of the session projects: ${knownProjects}`);
+            continue;
+          }
+          errors.push(..._validateTarget(spec.projectTargets[key])
+            .map(e => `projectTargets["${key}"]: ${e}`));
+        }
+      }
+    }
+  }
+
   return { ok: errors.length === 0, errors };
 }
 
@@ -341,6 +446,11 @@ function validateSpec(spec) {
  * @param {object} [spec.capture] - { video?, screenshots?, logs? }
  * @param {string} [spec.runner] - explicit runner name, or null to auto-detect
  * @param {string} [spec.project] - project name (used to scope artifacts)
+ * @param {string[]} [spec.projects] - multi-project fan-out (≤ LIMITS.projectsMax)
+ * @param {string} [spec.primaryProject] - which of `projects` owns DRAFT/EXECUTE
+ *        and the unsuffixed managed-spawn name. Defaults to `projects[0]`.
+ * @param {object} [spec.projectTargets] - per-project `{ [projectName]: target }`
+ *        overrides. A project without an entry falls back to `spec.target`.
  * @param {string} [spec.createdBy] - operator identity for audit
  * @param {object} [spec.provenance] - P-c5a2f8b7. Optional "where this spec
  *        came from" audit slot (e.g. { source:'prd', prd, flowSource,
@@ -362,14 +472,14 @@ function createSession(spec) {
   // single canonical `projects: string[] | null` (null = central). When both
   // are present, `projects` wins. Empty string in legacy `project` is treated
   // as central (matches the dashboard input convention).
-  let projects = null;
-  if (Array.isArray(spec.projects) && spec.projects.length > 0) {
-    projects = spec.projects.slice();
-  } else if (typeof spec.project === 'string' && spec.project.length > 0) {
-    projects = [spec.project];
-  }
-  const primaryProject = projects && projects.length > 0 ? projects[0] : null;
-  const coServices = projects && projects.length > 1 ? projects.slice(1) : [];
+  const declaredProjects = _specProjects(spec);
+  const projects = declaredProjects.length > 0 ? declaredProjects.slice() : null;
+  // W-msb9kgs402813a97-a — the primary is DECLARED, not positional. coServices
+  // is therefore "every other project" rather than projects.slice(1), so a
+  // primary in the middle of the list still fans the rest out correctly.
+  const primaryProject = _resolvePrimaryProject(spec, declaredProjects);
+  const coServices = projects ? projects.filter(p => p !== primaryProject) : [];
+  const projectTargets = _normalizeProjectTargets(spec, declaredProjects);
 
   const id = 'qas-' + uid();
   const now = ts();
@@ -391,6 +501,10 @@ function createSession(spec) {
       // older lifecycle hooks); new code keys off `projects`.
       projects,
       project: primaryProject,
+      // Per-project target overrides. null (not {}) when the caller declared
+      // none, so `_targetForProject` short-circuits to spec.target and the
+      // record shape stays honest about "no per-project routing".
+      projectTargets,
     },
     // W-mpq6xqzj000606d0 — denormalized fast-path fields used by the dispatch
     // chain (queueSetup / handleSetupComplete) without re-deriving from
@@ -527,10 +641,56 @@ function getSessionTestFile(sessionId) {
   return { path: target, content, language, truncated: false, size: stat.size };
 }
 
+/**
+ * W-msb9kgs402813a97-d — bounded read-side projection of the qa-run a session
+ * spawned. Returns a Map of runId → { id, status, artifacts } for the ids
+ * asked about, built from ONE runs read.
+ *
+ * Deliberately NOT `runs.getRun(id)` per session: getRun re-reads and re-parses
+ * the whole qa_runs table on every call, so a 50-session list on a 3s poll
+ * would be a 50× full-table scan. One read + an id index is the same answer at
+ * 1/50th the cost.
+ *
+ * Lazy-required and fully try/catch'd — the sessions list must survive an
+ * unreadable runs store (it degrades to `linkedRun: null`, never a 500).
+ */
+function _projectLinkedRuns(runIds) {
+  const out = new Map();
+  if (!runIds || !runIds.size) return out;
+  let runs;
+  try {
+    const qaRuns = require('./runs');
+    runs = qaRuns.listRuns({});
+    if (!Array.isArray(runs)) return out;
+    for (const run of runs) {
+      if (!run || !runIds.has(run.id)) continue;
+      out.set(run.id, {
+        id: run.id,
+        status: run.status || null,
+        artifacts: qaRuns.selectPrimaryArtifacts(run.artifacts),
+      });
+    }
+  } catch (e) {
+    log('warn', `qa-sessions: linked-run projection unavailable: ${e.message}`);
+    return new Map();
+  }
+  return out;
+}
+
 /**
  * List sessions, newest first, optionally filtered by state, capped by limit.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.limit]
+ * @param {string} [opts.state]
+ * @param {boolean} [opts.includeLinkedRun] - attach a bounded `linkedRun`
+ *   projection ({ id, status, artifacts: [{type, path, label}] }, primary
+ *   artifacts only) for sessions carrying a qaRunId, else `linkedRun: null`.
+ *   Opt-in on purpose: the default read path (including
+ *   runs.js#_runSessionOwnership, called on every run delete) must not pay for
+ *   the join. The projection is attached to a COPY — it is never persisted.
  */
-function listSessions({ limit, state } = {}) {
+function listSessions({ limit, state, includeLinkedRun } = {}) {
   let sessions = _readSessions();
   if (!Array.isArray(sessions)) return [];
   if (state) {
@@ -545,7 +705,16 @@ function listSessions({ limit, state } = {}) {
   });
   const n = Number(limit);
   if (Number.isFinite(n) && n > 0) sessions = sessions.slice(0, Math.floor(n));
-  return sessions;
+  if (!includeLinkedRun) return sessions;
+  // Index once for the page, after limit/filter so we only join what we return.
+  const runIds = new Set();
+  for (const s of sessions) {
+    if (s && typeof s.qaRunId === 'string' && s.qaRunId) runIds.add(s.qaRunId);
+  }
+  const linked = _projectLinkedRuns(runIds);
+  return sessions.map(s => (
+    s ? { ...s, linkedRun: (s.qaRunId && linked.get(s.qaRunId)) || null } : s
+  ));
 }
 
 /**
@@ -642,7 +811,10 @@ function transitionSession(id, toState, patch = {}, options = {}) {
       // W-mpq6xqzj000606d0 — `setupStatus` and `primaryScope` let the
       // multi-project fan-in handler can stamp per-project completion state
       // through the same locked path used by every other mutation.
-      for (const field of ['summary', 'error', 'failureClass', 'testFile', 'qaRunId', 'managedSpawnHealth', 'setupStatus', 'primaryScope']) {
+      // W-msb9kgs402813a97-b — `visualJourneyManifest` is the accepted DRAFT
+      // manifest, persisted so EXECUTE can validate captured evidence against
+      // what DRAFT actually promised.
+      for (const field of ['summary', 'error', 'failureClass', 'testFile', 'qaRunId', 'managedSpawnHealth', 'setupStatus', 'primaryScope', 'visualJourneyManifest']) {
         if (Object.prototype.hasOwnProperty.call(patch, field)) {
           session[field] = patch[field];
         }
@@ -674,7 +846,7 @@ function markKilled(id, patch) { return transitionSession(id, QA_SESSION_STATE.K
 // timeout already marked the session failed. Before this guard, that late
 // completion fell straight into `transitionSession`, which throws on the
 // illegal `failed -> drafting` (etc.) transition; the throw was swallowed by
-// the caller's try/catch (engine/lifecycle.js) and logged as a bare warning,
+// the caller's try/catch (engine/orchestration/lifecycle.js) and logged as a bare warning,
 // silently discarding real completed work (e.g. a working managed-spawn
 // setup) with no trace for a human to act on. This guard intercepts BEFORE
 // the throw, logs loudly, and writes an inbox note so the orphaned success
@@ -693,19 +865,21 @@ function _guardAlreadyTerminal(sessionId, session, phase, opts) {
       : '');
   log('warn', detail);
   try {
-    // Lazy require (mirrors engine/live-checkout.js#_defaultWriteInboxNote) to
+    // Lazy require (mirrors engine/worktrees/live-checkout.js#_defaultWriteInboxNote) to
     // sidestep any require-cycle between dispatch.js and qa-sessions.js.
-    require('./dispatch').writeInboxAlert(`qa-session-late-completion-${sessionId}`, detail);
+    require('../orchestration/dispatch').writeInboxAlert(`qa-session-late-completion-${sessionId}`, detail);
   } catch (e) { log('warn', `qa-sessions: writeInboxAlert for late completion ${sessionId} failed: ${e.message}`); }
   return true;
 }
 
 // ── Work-item builders (pure) ──────────────────────────────────────────────
 //
-// Each builder returns a WI spec ready for mutateWorkItems().push + addToDispatch.
-// Keeping these pure lets the dashboard endpoints (PR4) reuse them without
-// pulling dispatch into the unit test path. They're also called by the
-// lifecycle chain helpers below to queue the next phase.
+// Each builder returns a WI spec ready for mutateWorkItems().push. Keeping
+// these pure lets the dashboard endpoints (PR4) reuse them without pulling
+// dispatch into the unit test path. They're also called by the lifecycle chain
+// helpers below to queue the next phase. `project` is a hint only —
+// _persistWorkItem binds the field to the scope the item is stored in
+// (W-ms9nq2pu00cd60f3).
 
 function _baseWorkItem(session, phase, { title, description, project, primary, coServices, primaryProject }) {
   const wiId = 'W-' + uid();
@@ -715,8 +889,13 @@ function _baseWorkItem(session, phase, { title, description, project, primary, c
   // coServices=[] so existing single-target prompts render unchanged.
   // DRAFT/EXECUTE always omit these (primary-only) — pass `primary:
   // undefined` to keep meta clean.
+  //
+  // W-msb9kgs402813a97-a — each WI is routed its OWN target. Before this,
+  // every fanned-out SETUP was stamped with the session-wide
+  // `spec.target`, so a co-service could only ever be checked out at the
+  // primary's branch/PR/commit.
   const qaMeta = {
-    target: session.spec.target,
+    target: _targetForProject(session, project),
     flowsRaw: session.spec.flowsRaw,
     mode: session.spec.mode,
     capture: session.spec.capture,
@@ -764,12 +943,13 @@ function _baseWorkItem(session, phase, { title, description, project, primary, c
 function buildSetupWorkItem(session, { project, primary, coServices, primaryProject } = {}) {
   const isPrimary = primary === undefined ? true : !!primary;
   const co = Array.isArray(coServices) ? coServices.slice() : [];
+  const target = _targetForProject(session, project);
   return _baseWorkItem(session, SESSION_PHASE.SETUP, {
-    title: `QA Session SETUP: ${_summarizeTarget(session.spec.target)}${isPrimary && co.length ? ` (primary +${co.length} co-services)` : (!isPrimary ? ' (co-service)' : '')}`,
+    title: `QA Session SETUP: ${_summarizeTarget(target)}${isPrimary && co.length ? ` (primary +${co.length} co-services)` : (!isPrimary ? ' (co-service)' : '')}`,
     description: [
       `QA Session ${session.id} — SETUP phase.`,
       '',
-      `Target: ${JSON.stringify(session.spec.target)}`,
+      `Target: ${JSON.stringify(target)}`,
       `Flows: ${session.spec.flowsRaw}`,
       isPrimary
         ? (co.length ? `Role: PRIMARY (co-services: ${co.join(', ')})` : 'Role: PRIMARY (single-project session)')
@@ -814,7 +994,7 @@ function buildDraftWorkItem(session, { project, feedback } = {}) {
     lines.push('', '## Reviewer feedback on previous draft', '', String(feedback));
   }
   return _baseWorkItem(session, SESSION_PHASE.DRAFT, {
-    title: `QA Session DRAFT: ${_summarizeTarget(session.spec.target)}`,
+    title: `QA Session DRAFT: ${_summarizeTarget(_targetForProject(session, project))}`,
     description: lines.join('\n'),
     project,
   });
@@ -823,7 +1003,7 @@ function buildDraftWorkItem(session, { project, feedback } = {}) {
 /**
  * Build the EXECUTE work item. The agent invokes the runner against the live
  * spawn, captures artifacts per `capture`, and writes the injected absolute
- * result sidecar. The qaRunId hook in engine/lifecycle.js ingests it; our own
+ * result sidecar. The qaRunId hook in engine/orchestration/lifecycle.js ingests it; our own
  * session hook below transitions done/failed based on the resulting qa-run
  * terminal status.
  *
@@ -837,7 +1017,7 @@ function buildExecuteWorkItem(session, { qaRunId, project } = {}) {
     throw new Error('qa-sessions: buildExecuteWorkItem requires qaRunId');
   }
   const wi = _baseWorkItem(session, SESSION_PHASE.EXECUTE, {
-    title: `QA Session EXECUTE: ${_summarizeTarget(session.spec.target)}`,
+    title: `QA Session EXECUTE: ${_summarizeTarget(_targetForProject(session, project))}`,
     description: [
       `QA Session ${session.id} — EXECUTE phase.`,
       '',
@@ -876,21 +1056,80 @@ function _summarizeTarget(target) {
 // endpoints call when an agent finishes or a user takes an action. Each one
 // validates the transition first (so an illegal call throws BEFORE side
 // effects like queueing the next WI), then applies the state change, then
-// queues the next phase via _queueWorkItem when appropriate.
+// persists the next phase's work item via _queueWorkItem.
 //
-// dispatch + work-items are lazy-required inside _queueWorkItem to keep
-// `require('./qa-sessions')` cycle-safe at the top of lifecycle.js.
-
-function _dispatchQueuedWorkItem(wi) {
-  const dispatch = require('./dispatch');
-  dispatch.addToDispatch({
-    type: wi.type,
-    agent: wi.agent || null,
-    meta: { item: wi, playbook: wi.meta.playbook },
-  });
+// Dispatch itself is owned by the engine's normal work-discovery pass
+// (engine.js#discoverFromWorkItems / #discoverCentralWorkItems) — see
+// _queueWorkItem. work-items is lazy-required inside shared.mutateWorkItems to
+// keep `require('./qa/sessions')` cycle-safe at the top of lifecycle.js.
+
+const CENTRAL_SCOPE = 'central';
+
+/**
+ * The project that owns a SQL work-item scope. `shared.resolveProjectSource`
+ * builds a scope as `project?.name || 'central'`, so a scope is either a
+ * configured project name or the central sentinel.
+ */
+function _scopeProject(scope) {
+  const value = _isNonEmptyString(scope) ? String(scope).trim() : '';
+  return value && value !== CENTRAL_SCOPE ? value : null;
+}
+
+/**
+ * W-ms9nq2pu00cd60f3 — a QA phase work item's project association is DERIVED
+ * from the scope it is stored in, never merely carried alongside it.
+ *
+ * `WORK_TYPE.TEST` is in shared.WORKTREE_REQUIRING_TYPES: engine.js resolves a
+ * worktree rootDir from the work item's project, and without one it falls back
+ * to MINIONS_DIR's parent — which collapses to a drive root on installs where
+ * MINIONS_DIR sits one level below it (`D:\squad-opg` → `D:\`) and fails
+ * non-retryably with FAILURE_CLASS.WORKTREE_PREFLIGHT. Because the builders
+ * take `project` as a separate argument with an `opts.project ||
+ * spec.project || null` fallback chain, a phase queued into a project scope
+ * could land with `project: null` whenever that chain came up empty (e.g. a
+ * session created with `projects: ['x']`, which canonicalizes to `spec.projects`
+ * and leaves `spec.project` unset). Binding to the scope makes the association
+ * structural instead of incidental.
+ *
+ * A project scope that is handed a DIFFERENT project name is an unambiguous
+ * caller bug — neither value can be trusted, so it throws rather than persist
+ * an item the engine can never place. A central scope is left alone: it has no
+ * owning project to bind, and a declared project there is how
+ * discoverCentralWorkItems still resolves a rootDir, so neither inventing nor
+ * stripping one would help.
+ */
+function _assertProjectMatchesScope(scope, project, label) {
+  const scopeProject = _scopeProject(scope);
+  const declared = _isNonEmptyString(project) ? String(project).trim() : null;
+  if (scopeProject && declared && declared !== scopeProject) {
+    throw new Error(
+      `qa-sessions: ${label} project "${declared}" does not match scope "${scope}" — ` +
+      'a QA phase work item must be owned by the project whose work-item scope stores it',
+    );
+  }
+  return scopeProject;
+}
+
+/**
+ * Wake the engine daemon so its 1s fast poll runs a tick immediately instead of
+ * waiting a full tick interval. Mirrors the dashboard's create/advance wakeups
+ * (dashboard.js `mutateControl(control => ({ ...control, _wakeupAt }))`).
+ * Best-effort: a missing/locked control.json must never fail the transition —
+ * the next scheduled tick still discovers the item.
+ */
+function _requestDispatchWakeup() {
+  try {
+    shared.mutateControl((control) => ({ ...control, _wakeupAt: Date.now() }));
+  } catch (e) {
+    log('warn', `qa-sessions: dispatch wakeup request failed: ${e.message}`);
+  }
 }
 
 function _persistWorkItem(wi, scope) {
+  const project = _assertProjectMatchesScope(scope, wi.project, `work item ${wi.id}`);
+  // Stamp BEFORE the store write: the item must never be visible to work
+  // discovery without the project field engine.js reads to place a worktree.
+  if (project) wi.project = project;
   shared.mutateWorkItems(scope, (items) => {
     if (!Array.isArray(items)) items = [];
     if (!items.some(item => item && item.id === wi.id)) items.push(wi);
@@ -898,9 +1137,22 @@ function _persistWorkItem(wi, scope) {
   });
 }
 
+/**
+ * Persist a phase work item as `pending` and wake the engine.
+ *
+ * QA phases deliberately do NOT enqueue their own dispatch record. Dispatch is
+ * built by engine.js#discoverFromWorkItems / #discoverCentralWorkItems, which
+ * is the only place that resolves `meta.project`, routes an agent, derives the
+ * branch, honours the branch mutex, and renders the phase playbook prompt.
+ * A hand-rolled `addToDispatch({ meta: { item, playbook } })` carried none of
+ * those, so it spawned project-less and forever-failed WORKTREE_PREFLIGHT while
+ * also blocking the correct dispatch via the meta.item.id dedup
+ * (W-ms9nq2pu00cd60f3). Matches the sibling qa-validate flow
+ * (dashboard.js#handleQaRunbookRun), which has always relied on discovery.
+ */
 function _queueWorkItem(wi, scope) {
   _persistWorkItem(wi, scope);
-  _dispatchQueuedWorkItem(wi);
+  _requestDispatchWakeup();
   return wi.id;
 }
 
@@ -909,8 +1161,9 @@ function _queueWorkItem(wi, scope) {
  * Validates pending → spawning, queues the SETUP WI(s), returns the queued
  * primary WI id (back-compat).
  *
- * W-mpq6xqzj000606d0 — multi-project fan-out. The first target drives
- * DRAFT/EXECUTE; the rest are co-services.
+ * W-mpq6xqzj000606d0 — multi-project fan-out. W-msb9kgs402813a97-a — the
+ * session's declared `primaryProject` drives DRAFT/EXECUTE (the targets are
+ * reordered so it leads); every other target is a co-service.
  *
  * @param {string} sessionId
  * @param {object} opts
@@ -931,6 +1184,9 @@ function queueSetup(sessionId, opts = {}) {
     if (!t || !_isNonEmptyString(t.scope)) {
       throw new Error('qa-sessions: queueSetup target missing scope');
     }
+    // Reject a project/scope disagreement BEFORE markSpawning, so a bad target
+    // can't leave the session stranded in `spawning` with no work item.
+    _assertProjectMatchesScope(t.scope, t.project, 'queueSetup target');
   }
   if (targets.length > LIMITS.projectsMax) {
     throw new Error(`qa-sessions: queueSetup target count exceeds ${LIMITS.projectsMax}`);
@@ -939,6 +1195,31 @@ function queueSetup(sessionId, opts = {}) {
   const session = getSession(sessionId);
   if (!session) throw new Error('qa-sessions: session not found: ' + sessionId);
 
+  // W-msb9kgs402813a97-a — the primary is the target whose project matches the
+  // session's DECLARED primaryProject, not whichever target the caller happened
+  // to list first. Reordering (rather than tracking an index) keeps the single
+  // "index 0 is primary" invariant the rest of this function and the fan-in
+  // handler rely on.
+  //
+  // A declared primary that no project-bound target can host is a genuine
+  // contract violation: the resolver and the session record disagree about what
+  // the session IS. Throw BEFORE markSpawning so the caller sees a 4xx instead
+  // of a session stranded in `spawning` with a mis-flagged fan-out. Callers
+  // that pass only project-less targets (the legacy `{ scope }` shape) are
+  // unaffected — there is nothing to contradict.
+  const declaredPrimary = _isNonEmptyString(session.primaryProject) ? session.primaryProject : null;
+  if (declaredPrimary) {
+    const primaryIndex = targets.findIndex(t => (t.project || null) === declaredPrimary);
+    if (primaryIndex > 0) {
+      targets.unshift(targets.splice(primaryIndex, 1)[0]);
+    } else if (primaryIndex < 0 && targets.some(t => _isNonEmptyString(t.project))) {
+      throw new Error(
+        `qa-sessions: queueSetup primaryProject "${declaredPrimary}" is not among the resolved `
+        + `targets (${targets.map(t => t.project || '(central)').join(', ')})`,
+      );
+    }
+  }
+
   const primaryTarget = targets[0];
   const coServiceProjects = targets.slice(1).map(t => t.project || null).filter(Boolean);
   const isMulti = targets.length > 1;
@@ -1153,7 +1434,7 @@ function handleSetupCompleteAfterManagedSpawn(sessionId, opts = {}) {
   if (!opts.success) return handleSetupComplete(sessionId, opts);
 
   const requirement = _setupManagedSpawnRequirement(session, opts.project || null);
-  const record = require('./managed-spawn').getManagedSpecByName(requirement.name);
+  const record = require('../processes/managed-spawn').getManagedSpecByName(requirement.name);
   const hasExpectedOwner = _isNonEmptyString(requirement.wiId);
   const ownerMatches = hasExpectedOwner && record?.owner_wi === requirement.wiId;
   if (!record || record.alive !== true || record.healthy !== true || !ownerMatches) {
@@ -1181,10 +1462,21 @@ function handleSetupCompleteAfterManagedSpawn(sessionId, opts = {}) {
  * awaiting-approval (confirm mode — user must call /approve) or auto-chain
  * EXECUTE (auto mode). The testFile path is captured for the EXECUTE prompt.
  *
+ * W-msb9kgs402813a97-b — a session that asked for screenshots or video must
+ * also produce a VISUAL-JOURNEY MANIFEST (the agent's
+ * `agents/<id>/qa-session-draft-result.json` sidecar, consumed by the
+ * lifecycle hook and handed in as `opts.manifest`). The gate runs BEFORE both
+ * exits — before `markAwaitingApproval` and before the auto-mode EXECUTE queue
+ * — so a draft that never opened a browser, skipped a project, or ignored a
+ * co-service origin fails here instead of producing a green qa-run with no
+ * visual evidence.
+ *
  * @param {string} sessionId
  * @param {object} opts
  * @param {boolean} opts.success
  * @param {string}  [opts.testFile] - relative path under qa-tests/<id>/, captured for EXECUTE
+ * @param {object}  [opts.manifest] - parsed visual-journey manifest from the DRAFT sidecar
+ * @param {Array}   [opts.services] - managed-spawn inventory override for the coverage check
  * @param {string}  [opts.scope]    - required when success=true and mode=auto
  * @param {string}  [opts.project]
  * @param {string}  [opts.qaRunId]  - required when success=true and mode=auto (caller creates the qa-runs record)
@@ -1205,15 +1497,46 @@ function handleDraftComplete(sessionId, opts = {}) {
     });
     return { nextState: QA_SESSION_STATE.FAILED, queuedExecuteWi: null };
   }
-  const testFilePatch = opts.testFile ? { testFile: opts.testFile } : {};
-  if (session.spec.mode === 'auto') {
+
+  // Caller-contract checks first: the chain helpers validate arguments BEFORE
+  // any side effect, so a missing scope/qaRunId still throws rather than
+  // half-applying a state change.
+  const isAuto = session.spec.mode === 'auto';
+  if (isAuto) {
     if (!_isNonEmptyString(opts.scope)) {
       throw new Error('qa-sessions: handleDraftComplete (auto) requires scope');
     }
     if (!_isNonEmptyString(opts.qaRunId)) {
       throw new Error('qa-sessions: handleDraftComplete (auto) requires qaRunId');
     }
-    markExecuting(sessionId, { ...testFilePatch, qaRunId: opts.qaRunId });
+  }
+
+  // Fail-closed visual-coverage gate. Deliberately BEFORE the mode branch: a
+  // rejection must not queue EXECUTE and must not park the session for human
+  // approval as if the draft were usable.
+  const gate = visualJourney.validateVisualJourneyManifest(
+    session,
+    opts.manifest === undefined ? null : opts.manifest,
+    { services: opts.services },
+  );
+  if (!gate.ok) {
+    markFailed(sessionId, {
+      failureClass: visualJourney.VISUAL_COVERAGE_FAILURE_CLASS,
+      error: gate.error,
+      summary: `DRAFT rejected: visual-journey coverage incomplete (${gate.errors.length} issue${gate.errors.length === 1 ? '' : 's'})`,
+    });
+    log('warn', `qa-session ${sessionId} DRAFT rejected by the visual-journey gate: ${gate.error}`);
+    return { nextState: QA_SESSION_STATE.FAILED, queuedExecuteWi: null };
+  }
+
+  const testFilePatch = opts.testFile ? { testFile: opts.testFile } : {};
+  // Only stamp a manifest when the draft actually declared one — a logs-only
+  // session keeps its historical record shape.
+  const draftPatch = gate.manifest
+    ? { ...testFilePatch, visualJourneyManifest: gate.manifest }
+    : testFilePatch;
+  if (isAuto) {
+    markExecuting(sessionId, { ...draftPatch, qaRunId: opts.qaRunId });
     const updated = getSession(sessionId);
     const wi = buildExecuteWorkItem(updated, {
       qaRunId: opts.qaRunId,
@@ -1224,20 +1547,72 @@ function handleDraftComplete(sessionId, opts = {}) {
     return { nextState: QA_SESSION_STATE.EXECUTING, queuedExecuteWi: wi.id };
   }
   // confirm mode (default)
-  markAwaitingApproval(sessionId, testFilePatch);
+  markAwaitingApproval(sessionId, draftPatch);
   return { nextState: QA_SESSION_STATE.AWAITING_APPROVAL, queuedExecuteWi: null };
 }
 
+/**
+ * Resolve the EXECUTE-side evidence verdict for a session about to be marked
+ * done (W-msb9kgs402813a97-c).
+ *
+ * Skipped entirely — `{ ok: true, required: false }` — when the session asked
+ * for neither screenshots nor video, or when no DRAFT visual-journey manifest
+ * was persisted (a legacy session predating the manifest). Otherwise the run
+ * record and its artifacts directory are resolved and handed to the validator.
+ *
+ * An internal failure FAILS CLOSED: a gate that cannot prove evidence must not
+ * wave the session through.
+ */
+function _evaluateExecuteEvidence(session, opts = {}) {
+  const manifest = session && session.visualJourneyManifest;
+  const hasManifest = !!manifest && typeof manifest === 'object' && !Array.isArray(manifest);
+  if (!visualJourney.isVisualCaptureRequested(session) || !hasManifest) {
+    return { ok: true, required: false };
+  }
+  try {
+    const qaRuns = require('./runs');
+    let run = opts.qaRun && typeof opts.qaRun === 'object' ? opts.qaRun : null;
+    const runId = (run && run.id) || session.qaRunId || null;
+    if (!run && _isNonEmptyString(runId)) {
+      try { run = qaRuns.getRun(runId); } catch { run = null; }
+    }
+    let artifactsDir = null;
+    if (_isNonEmptyString(runId)) {
+      try { artifactsDir = qaRuns.qaArtifactsDirForRun(runId); } catch { artifactsDir = null; }
+    }
+    return visualJourney.validateEvidenceCoverage({
+      session, manifest, run, artifactsDir, services: opts.services,
+    });
+  } catch (err) {
+    return {
+      ok: false,
+      required: true,
+      missing: { files: [], journeys: [], projects: [], services: [], evidenceTypes: [] },
+      errors: [err.message],
+      error: `evidence coverage could not be verified for session ${session.id}: ${err.message}`,
+    };
+  }
+}
+
 /**
  * Lifecycle hook: EXECUTE WI completed. The qa-runs record's terminal status
  * is the source of truth for done vs failed — the qaRunId hook at
- * engine/lifecycle.js:4340 has already written it. We just read that record
+ * engine/orchestration/lifecycle.js:4340 has already written it. We just read that record
  * (when provided) and transition the session accordingly.
  *
+ * W-msb9kgs402813a97-c — a green qa-run is necessary but NOT sufficient for a
+ * session that asked for screenshots or video. Before choosing DONE we run the
+ * evidence-coverage validator: a run whose registered artifacts do not exist
+ * on disk, whose evidence is missing a requested capture type, or whose passed
+ * journeys cover only one of the session's projects/services fails with
+ * `qa-session-evidence-incomplete` instead.
+ *
  * @param {string} sessionId
  * @param {object} opts
  * @param {boolean} opts.success - dispatch-level success (whether the agent exited 0)
  * @param {string}  [opts.qaRunStatus] - 'passed' | 'failed' | 'errored'  (from qa-runs record)
+ * @param {object}  [opts.qaRun] - the already-read qa-runs record (avoids a second lookup)
+ * @param {Array}   [opts.services] - managed-spawn inventory override for the coverage check
  * @param {string}  [opts.summary]
  * @param {string}  [opts.reason]
  */
@@ -1266,6 +1641,17 @@ function handleExecuteComplete(sessionId, opts = {}) {
     patch.failureClass = 'qa-session-execute-failed';
     patch.error = opts.reason || 'EXECUTE phase failed';
   }
+  // Fail-closed evidence gate — deliberately BEFORE the transition, and only
+  // on the DONE path so an already-failing run keeps its own failure class.
+  if (toState === QA_SESSION_STATE.DONE) {
+    const evidence = _evaluateExecuteEvidence(session, opts);
+    if (evidence.required && !evidence.ok) {
+      toState = QA_SESSION_STATE.FAILED;
+      patch.failureClass = visualJourney.EVIDENCE_COVERAGE_FAILURE_CLASS;
+      patch.error = evidence.error;
+      log('warn', `qa-session ${sessionId} EXECUTE rejected by the evidence-coverage gate: ${evidence.error}`);
+    }
+  }
   transitionSession(sessionId, toState, patch);
   return toState;
 }
@@ -1307,9 +1693,10 @@ function queueApprovedDraft(sessionId, { scope, qaRunId, project } = {}) {
     }
     session.workItems[SESSION_PHASE.EXECUTE] = wi.id;
     session.updatedAt = ts();
-    _dispatchQueuedWorkItem(wi);
     return sessions;
   });
+  // Outside the session lock — never take a second lock inside a mutator.
+  _requestDispatchWakeup();
   return wi.id;
 }
 
@@ -1383,6 +1770,163 @@ function dismissSession(sessionId, { summary } = {}) {
   });
 }
 
+// ── Deletion (operator-facing, terminal-only) ──────────────────────────────
+
+// W-msb4vgj500zbb008 — DELETE /api/qa/sessions/<id>. Sessions accumulate in
+// the dashboard's "Recent Sessions" list and, before this, the only way to
+// remove a failed record was hand-editing engine/state.db. Mirrors
+// engine/qa/runs.js#deleteQaRun: terminal-only, envelope-returning, the record
+// removed inside the SQL mutator (which emits the qa_sessions state event) and
+// every filesystem / cross-store side effect performed OUTSIDE the lock.
+//
+// Linked-resource ownership rules are deliberately conservative — a leaked
+// artifact costs nothing, a wrongly-deleted one destroys QA evidence:
+//
+//   engine/qa-tests/<id>/  Session-owned by construction (createSession makes
+//                          it; the directory name IS the session id) → removed
+//                          with the same resolve + prefix sandbox deleteQaRun
+//                          applies to artifact directories. Never the root.
+//   session.qaRunId        Cascaded through qaRuns.deleteQaRun ONLY when the
+//                          run still exists AND carries the synthetic
+//                          `qa-session-<id>` runbookId stamped by the approve
+//                          endpoint (dashboard.js#handleQaSessionApprove) and
+//                          the auto-mode chain (lifecycle.js). A run owned by a
+//                          real runbook, a run already deleted, and a run that
+//                          is still pending/running are each left in place and
+//                          named in `qaRun.reason`. deleteQaRun's own
+//                          terminal-only guard is the second line of defence.
+//   managed spawns         NEVER touched. A QA managed-spawn can outlive its
+//                          session, and killing a live process as a side
+//                          effect of deleting a history record would be a
+//                          surprise. Live names are reported instead so the
+//                          operator can call POST /api/managed-processes/kill
+//                          deliberately.
+//
+// Repeat deletes are safe: the second call returns `not_found`, and a linked
+// run that a previous call (or a manual DELETE /api/qa/runs/<id>) already
+// removed reports `qaRun.reason: 'not_found'` rather than failing the request.
+const QA_SESSION_RUNBOOK_PREFIX = 'qa-session-';
+
+function sessionOwnedRunbookId(sessionId) {
+  return QA_SESSION_RUNBOOK_PREFIX + sessionId;
+}
+
+function _removeSessionTestDir(sessionId) {
+  try {
+    const base = path.resolve(qaTestsDir());
+    const target = path.resolve(qaTestsDirForSession(sessionId));
+    if (!target.startsWith(base + path.sep)) return false;
+    if (!fs.existsSync(target)) return false;
+    fs.rmSync(target, { recursive: true, force: true });
+    return true;
+  } catch (e) {
+    log('warn', `qa-sessions: rm tests dir failed for ${sessionId}: ${e.message}`);
+    return false;
+  }
+}
+
+function _deleteLinkedQaRun(session) {
+  const runId = session && session.qaRunId;
+  if (!_isNonEmptyString(runId)) {
+    return { linked: false, id: null, deleted: false, reason: 'no_linked_run' };
+  }
+  let qaRuns;
+  let run;
+  try {
+    qaRuns = require('./runs');
+    run = qaRuns.getRun(runId);
+  } catch (e) {
+    log('warn', `qa-sessions: qa-run lookup failed for ${runId}: ${e.message}`);
+    return { linked: true, id: runId, deleted: false, reason: 'lookup_failed' };
+  }
+  if (!run) return { linked: true, id: runId, deleted: false, reason: 'not_found' };
+  if (run.runbookId !== sessionOwnedRunbookId(session.id)) {
+    return { linked: true, id: runId, deleted: false, reason: 'not_session_owned' };
+  }
+  let result;
+  try { result = qaRuns.deleteQaRun(runId); }
+  catch (e) {
+    log('warn', `qa-sessions: linked qa-run delete failed for ${runId}: ${e.message}`);
+    return { linked: true, id: runId, deleted: false, reason: 'delete_failed' };
+  }
+  if (result && result.ok) {
+    return {
+      linked: true,
+      id: runId,
+      deleted: true,
+      reason: null,
+      artifactsRemoved: !!result.artifactsRemoved,
+    };
+  }
+  const out = {
+    linked: true,
+    id: runId,
+    deleted: false,
+    reason: (result && result.error) || 'delete_failed',
+  };
+  if (result && result.currentStatus) out.currentStatus = result.currentStatus;
+  return out;
+}
+
+// Report — never kill. `known: false` means the managed-spawn store could not
+// be read, so the empty list must not be read as "no live spawns".
+function _liveManagedSpawnsForSession(session) {
+  try {
+    const managedSpawn = require('../processes/managed-spawn');
+    const live = [];
+    for (const name of managedSpawnNamesForSession(session)) {
+      if (managedSpawn.getManagedSpecByName(name)) live.push(name);
+    }
+    return { live, known: true };
+  } catch (e) {
+    log('warn', `qa-sessions: managed-spawn lookup failed for ${session && session.id}: ${e.message}`);
+    return { live: [], known: false };
+  }
+}
+
+/**
+ * Hard-delete a terminal QA session record and clean up the resources it
+ * provably owns.
+ *
+ *   { ok: true,  id, session, testDirRemoved, qaRun, managedSpawns }
+ *   { ok: false, error: 'invalid_id' | 'not_found' | 'not_terminal', currentState? }
+ *
+ * @param {string} id - session id (must pass _isSafeSessionId)
+ * @returns {object} envelope (see above)
+ */
+function deleteSession(id) {
+  if (!_isSafeSessionId(id)) return { ok: false, error: 'invalid_id' };
+
+  let captured = null;
+  let notFound = false;
+  let notTerminal = null;
+  mutateQaSessions( (sessions) => {
+    if (!Array.isArray(sessions)) return sessions;
+    const idx = sessions.findIndex(s => s && s.id === id);
+    if (idx < 0) { notFound = true; return sessions; }
+    const session = sessions[idx];
+    if (!TERMINAL_STATES.has(session.state)) {
+      notTerminal = session.state;
+      return sessions;
+    }
+    captured = session;
+    sessions.splice(idx, 1);
+    return sessions;
+  }, { defaultValue: [] });
+
+  if (notFound) return { ok: false, error: 'not_found' };
+  if (notTerminal !== null) return { ok: false, error: 'not_terminal', currentState: notTerminal };
+
+  return {
+    ok: true,
+    id,
+    session: captured,
+    testDirRemoved: _removeSessionTestDir(id),
+    qaRun: _deleteLinkedQaRun(captured),
+    managedSpawns: _liveManagedSpawnsForSession(captured),
+  };
+}
+
 // ── Status summary (cheap, for /api/status fast-state slice) ───────────────
 
 /**
@@ -1478,6 +2022,8 @@ module.exports = {
   cancelSession,
   killSession,
   dismissSession,
+  deleteSession,
+  sessionOwnedRunbookId,
   managedSpawnNamesForSession,
   // Status
   summarizeSessionsForStatus,