@yemi33/minions 0.1.2081 → 0.1.2083

package/engine/qa-sessions.js

@@ -138,6 +138,11 @@ const LIMITS = {
   targetFieldMax: 500,
   projectMax: 64,
   summaryMax: 2000,
+  // W-mpq6xqzj000606d0 — multi-project QA Session: cap on co-services per
+  // session. Each entry is a separate SETUP WI fan-out, so the cap doubles as
+  // a guardrail against an operator queueing dozens of parallel dev-up
+  // services from a single form submit.
+  projectsMax: 5,
 };
 
 // Mirrors engine/qa-runbooks.js _isSafeId — kebab-case ≤64 chars, no leading/
@@ -286,6 +291,37 @@ function validateSpec(spec) {
     }
   }
 
+  // W-mpq6xqzj000606d0 — multi-project mode. `spec.projects` is the canonical
+  // field; `spec.project` (legacy single-string) is still accepted above and
+  // normalized into `projects` by createSession. Both may legitimately be
+  // empty/null = "central work-items target", but if BOTH are supplied they
+  // must agree (the dashboard back-compat wrapper sends just one). We don't
+  // hard-fail on duplication here — createSession picks projects[] first.
+  if (spec.projects !== undefined && spec.projects !== null) {
+    if (!Array.isArray(spec.projects)) {
+      errors.push('projects must be an array of strings when present');
+    } else if (spec.projects.length > LIMITS.projectsMax) {
+      errors.push(`projects exceeds ${LIMITS.projectsMax} entries`);
+    } else {
+      const seen = new Set();
+      for (const p of spec.projects) {
+        if (typeof p !== 'string' || p.length === 0) {
+          errors.push('projects entries must be non-empty strings');
+          break;
+        }
+        if (p.length > LIMITS.projectMax) {
+          errors.push(`projects entry exceeds ${LIMITS.projectMax} chars`);
+          break;
+        }
+        if (seen.has(p)) {
+          errors.push(`projects contains duplicate entry: ${p}`);
+          break;
+        }
+        seen.add(p);
+      }
+    }
+  }
+
   return { ok: errors.length === 0, errors };
 }
 
@@ -318,6 +354,19 @@ function createSession(spec) {
     throw err;
   }
 
+  // W-mpq6xqzj000606d0 — normalize legacy `project` and new `projects` into a
+  // 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 id = 'qas-' + uid();
   const now = ts();
   const session = {
@@ -333,8 +382,25 @@ function createSession(spec) {
         logs: !!(spec.capture && spec.capture.logs),
       },
       runner: spec.runner || null,
-      project: spec.project || null,
+      // Canonical multi-project field. `project` (legacy single-string) is
+      // mirrored for back-compat readers (qa.js card render, /api/status,
+      // older lifecycle hooks); new code keys off `projects`.
+      projects,
+      project: primaryProject,
     },
+    // W-mpq6xqzj000606d0 — denormalized fast-path fields used by the dispatch
+    // chain (queueSetup / handleSetupComplete) without re-deriving from
+    // spec.projects on every call.
+    primaryProject,
+    coServices,
+    // Per-project SETUP completion map. Only populated when projects.length >
+    // 1 (multi-project fan-out). Single-project sessions skip this map and
+    // use session.state directly.
+    setupStatus: null,
+    // primaryWiPath is stamped at queueSetup time so handleSetupComplete can
+    // queue DRAFT on the right work-items file without re-resolving the
+    // project through dashboard config.
+    primaryWiPath: null,
     // Per-phase WI links — back-filled by setSessionWorkItem when the
     // dashboard endpoint or lifecycle hook queues the next phase.
     workItems: { setup: null, draft: null, execute: null },
@@ -492,7 +558,10 @@ function transitionSession(id, toState, patch = {}) {
     if (patch && typeof patch === 'object' && !Array.isArray(patch)) {
       // Whitelist mutable fields to keep transitionSession from rewriting
       // immutable spec/createdAt fields by mistake.
-      for (const field of ['summary', 'error', 'failureClass', 'testFile', 'qaRunId', 'managedSpawnHealth']) {
+      // W-mpq6xqzj000606d0 — added `setupStatus` and `primaryWiPath` so 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', 'primaryWiPath']) {
         if (Object.prototype.hasOwnProperty.call(patch, field)) {
           session[field] = patch[field];
         }
@@ -524,8 +593,24 @@ function markKilled(id, patch) { return transitionSession(id, QA_SESSION_STATE.K
 // pulling dispatch into the unit test path. They're also called by the
 // lifecycle chain helpers below to queue the next phase.
 
-function _baseWorkItem(session, phase, { title, description, project }) {
+function _baseWorkItem(session, phase, { title, description, project, primary, coServices, primaryProject }) {
   const wiId = 'W-' + uid();
+  // W-mpq6xqzj000606d0 — multi-project fan-out: SETUP work items carry
+  // `primary: boolean` + `coServices: string[]` + `primaryProject: string` on
+  // meta.qaSession. Single-project sessions default to primary=true /
+  // coServices=[] so existing single-target prompts render unchanged.
+  // DRAFT/EXECUTE always omit these (primary-only) — pass `primary:
+  // undefined` to keep meta clean.
+  const qaMeta = {
+    target: session.spec.target,
+    flowsRaw: session.spec.flowsRaw,
+    mode: session.spec.mode,
+    capture: session.spec.capture,
+    runner: session.spec.runner,
+  };
+  if (primary !== undefined) qaMeta.primary = !!primary;
+  if (Array.isArray(coServices)) qaMeta.coServices = coServices.slice();
+  if (primaryProject) qaMeta.primaryProject = String(primaryProject);
   const wi = {
     id: wiId,
     title,
@@ -543,13 +628,7 @@ function _baseWorkItem(session, phase, { title, description, project }) {
     meta: {
       sessionId: session.id,
       sessionPhase: phase,
-      qaSession: {
-        target: session.spec.target,
-        flowsRaw: session.spec.flowsRaw,
-        mode: session.spec.mode,
-        capture: session.spec.capture,
-        runner: session.spec.runner,
-      },
+      qaSession: qaMeta,
       playbook: 'qa-session-' + phase,
     },
   };
@@ -562,21 +641,34 @@ function _baseWorkItem(session, phase, { title, description, project }) {
  * Build the SETUP work item. The agent resolves the target, sets up a
  * worktree, and writes a managed-spawn.json sidecar. Engine then spawns the
  * service and the healthcheck gate drives the next transition.
+ *
+ * W-mpq6xqzj000606d0 — When the session has multiple projects (fan-out),
+ * `primary` distinguishes the orchestrator WI (true; carries the full
+ * coServices list) from each co-service WI (false; coServices === []). The
+ * session's DRAFT phase keys off the primary's wiPath.
  */
-function buildSetupWorkItem(session, { project } = {}) {
+function buildSetupWorkItem(session, { project, primary, coServices, primaryProject } = {}) {
+  const isPrimary = primary === undefined ? true : !!primary;
+  const co = Array.isArray(coServices) ? coServices.slice() : [];
   return _baseWorkItem(session, SESSION_PHASE.SETUP, {
-    title: `QA Session SETUP: ${_summarizeTarget(session.spec.target)}`,
+    title: `QA Session SETUP: ${_summarizeTarget(session.spec.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)}`,
       `Flows: ${session.spec.flowsRaw}`,
+      isPrimary
+        ? (co.length ? `Role: PRIMARY (co-services: ${co.join(', ')})` : 'Role: PRIMARY (single-project session)')
+        : 'Role: CO-SERVICE (dev-up only; primary owns the test orchestration)',
       '',
       'Resolve the target to a worktree, inspect the codebase for the dev-up command,',
-      `and write \`agents/<your-id>/managed-spawn.json\` with name=\`${session.managedSpawnName}\`.`,
+      `and write \`agents/<your-id>/managed-spawn.json\` with name=\`${session.managedSpawnName}${isPrimary ? '' : '-' + project}\`.`,
       'See `playbooks/qa-session-setup.md` for the full contract.',
     ].join('\n'),
     project,
+    primary: isPrimary,
+    coServices: co,
+    primaryProject: primaryProject || (isPrimary ? project : undefined),
   });
 }
 
@@ -661,6 +753,23 @@ function _summarizeTarget(target) {
   }
 }
 
+/**
+ * W-mpq6xqzj000606d0 — Back-compat shim: return the canonical projects[]
+ * array for a session, regardless of whether the record was written under
+ * the legacy single-`project` schema or the new `projects[]` schema. Returns
+ * `[]` for "central" sessions (no project) so callers can simply check
+ * `length > 1` for multi-project mode.
+ */
+function _resolveSessionProjects(session) {
+  if (!session || typeof session !== 'object') return [];
+  const fromArr = session.spec && Array.isArray(session.spec.projects) ? session.spec.projects : null;
+  if (fromArr && fromArr.length > 0) return fromArr.slice();
+  const fromStr = session.spec && typeof session.spec.project === 'string' && session.spec.project.length > 0
+    ? session.spec.project
+    : null;
+  return fromStr ? [fromStr] : [];
+}
+
 // ── Cross-WI dispatch chain helpers ─────────────────────────────────────────
 //
 // These are the integration entry points the lifecycle hook + dashboard
@@ -693,26 +802,113 @@ function _queueWorkItem(wi, wiPath) {
 
 /**
  * Called by the POST /api/qa/session handler immediately after createSession.
- * Validates pending → spawning, queues the SETUP WI, returns the queued WI id.
+ * Validates pending → spawning, queues the SETUP WI(s), returns the queued
+ * primary WI id (back-compat).
+ *
+ * W-mpq6xqzj000606d0 — multi-project fan-out. Two calling shapes are
+ * accepted:
+ *   1. Legacy single-target: `{ wiPath, project }` (project may be null for
+ *      central). Builds and queues one SETUP WI exactly like before.
+ *   2. Multi-target: `{ resolvedTargets: [{ project, wiPath }, ...] }`. The
+ *      FIRST entry is treated as the primary (drives DRAFT/EXECUTE later);
+ *      the rest are co-services. One SETUP WI is queued per entry, and
+ *      `session.setupStatus` is initialized with a `pending` entry per
+ *      project so handleSetupComplete can fan-in.
  *
  * @param {string} sessionId
  * @param {object} opts
- * @param {string} opts.wiPath - resolved work-items path (central or per-project)
- * @param {string} [opts.project] - project name (set on the WI)
+ * @param {string} [opts.wiPath]            - legacy single-target wiPath
+ * @param {string} [opts.project]           - legacy single-target project name
+ * @param {Array<{project:?string, wiPath:string}>} [opts.resolvedTargets]
+ * @returns {string} the queued PRIMARY SETUP WI id
  */
-function queueSetup(sessionId, { wiPath, project } = {}) {
-  if (!_isNonEmptyString(wiPath)) throw new Error('qa-sessions: queueSetup requires wiPath');
+function queueSetup(sessionId, opts = {}) {
+  let targets = Array.isArray(opts.resolvedTargets) ? opts.resolvedTargets.slice() : null;
+  if (!targets || targets.length === 0) {
+    if (!_isNonEmptyString(opts.wiPath)) {
+      throw new Error('qa-sessions: queueSetup requires wiPath or resolvedTargets');
+    }
+    targets = [{ project: opts.project || null, wiPath: opts.wiPath }];
+  }
+  // Defensive: each target needs a wiPath. project may be null for central.
+  for (const t of targets) {
+    if (!t || !_isNonEmptyString(t.wiPath)) {
+      throw new Error('qa-sessions: queueSetup target missing wiPath');
+    }
+  }
+  if (targets.length > LIMITS.projectsMax) {
+    throw new Error(`qa-sessions: queueSetup target count exceeds ${LIMITS.projectsMax}`);
+  }
+
   const session = getSession(sessionId);
   if (!session) throw new Error('qa-sessions: session not found: ' + sessionId);
+
+  const primaryTarget = targets[0];
+  const coServiceProjects = targets.slice(1).map(t => t.project || null).filter(Boolean);
+  const isMulti = targets.length > 1;
+
+  // Initialize setupStatus + primaryWiPath BEFORE transitioning so the
+  // fan-in handler sees the full project list even on a racing completion.
+  // Single-project sessions skip the map to keep blast radius minimal.
+  const setupStatusPatch = isMulti
+    ? targets.reduce((acc, t) => {
+        const key = t.project || '__central__';
+        acc[key] = { state: 'pending', wiId: null, error: null, completedAt: null };
+        return acc;
+      }, {})
+    : null;
+
   // transitionSession enforces pending → spawning. If the session is already
   // past pending (createSession + queueSetup called twice), the throw bubbles
   // up to the dashboard handler and surfaces as a 409 — better than silently
   // double-queueing.
-  markSpawning(sessionId);
-  const wi = buildSetupWorkItem(session, { project: project || session.spec.project || null });
-  _queueWorkItem(wi, wiPath);
-  setSessionWorkItem(sessionId, SESSION_PHASE.SETUP, wi.id);
-  return wi.id;
+  markSpawning(sessionId, {
+    setupStatus: setupStatusPatch,
+    primaryWiPath: primaryTarget.wiPath,
+  });
+
+  // Build + queue one WI per target. Primary is index 0; coServices is the
+  // full list of OTHER project names. Each SETUP WI gets its own meta so
+  // the agent prompt clearly states its role.
+  let primaryWiId = null;
+  const builtWiIds = {};
+  for (let i = 0; i < targets.length; i++) {
+    const t = targets[i];
+    const isPrimary = i === 0;
+    const wi = buildSetupWorkItem(session, {
+      project: t.project || null,
+      primary: isPrimary,
+      coServices: isPrimary ? coServiceProjects : [],
+      primaryProject: primaryTarget.project || null,
+    });
+    _queueWorkItem(wi, t.wiPath);
+    builtWiIds[t.project || '__central__'] = wi.id;
+    if (isPrimary) primaryWiId = wi.id;
+  }
+  // Stamp the primary WI id into workItems.setup (back-compat: dashboard
+  // cards index off this single field).
+  setSessionWorkItem(sessionId, SESSION_PHASE.SETUP, primaryWiId);
+
+  // Back-fill each per-project setupStatus entry with its wiId for multi-
+  // project sessions.
+  if (isMulti) {
+    const updated = getSession(sessionId);
+    const nextStatus = { ...(updated.setupStatus || setupStatusPatch) };
+    for (const [key, wiId] of Object.entries(builtWiIds)) {
+      if (nextStatus[key]) nextStatus[key] = { ...nextStatus[key], wiId };
+    }
+    mutateJsonFileLocked(qaSessionsPath(), (sessions) => {
+      if (!Array.isArray(sessions)) sessions = [];
+      const s = sessions.find(x => x && x.id === sessionId);
+      if (s) {
+        s.setupStatus = nextStatus;
+        s.updatedAt = ts();
+      }
+      return sessions;
+    }, { defaultValue: [] });
+  }
+
+  return primaryWiId;
 }
 
 /**
@@ -721,36 +917,113 @@ function queueSetup(sessionId, { wiPath, project } = {}) {
  * marking the dispatch successful), so we advance to drafting and queue the
  * DRAFT WI. On failure we record the failureClass and mark the session failed.
  *
+ * W-mpq6xqzj000606d0 — fan-in for multi-project sessions. When
+ * `session.setupStatus` is populated (length > 1 targets queued), each
+ * completion updates one entry. The session only advances to drafting once
+ * ALL entries are `success`. Any failure marks the entire session failed
+ * with a per-project error map encoded into session.error.
+ *
  * @param {string} sessionId
  * @param {object} opts
  * @param {boolean} opts.success
- * @param {string}  [opts.wiPath] - required when success=true
- * @param {string}  [opts.project]
+ * @param {string}  [opts.wiPath]      - required when success=true (single-project) OR for the PRIMARY target on multi-project DRAFT queueing
+ * @param {string}  [opts.project]     - which project the completing WI was for (multi-project routing key)
  * @param {string}  [opts.failureClass]
  * @param {string}  [opts.reason]
- * @returns {string|null} the queued DRAFT WI id on success, null on failure
+ * @returns {string|null} the queued DRAFT WI id on success (single OR last-to-complete in multi), null otherwise
  */
 function handleSetupComplete(sessionId, opts = {}) {
   const session = getSession(sessionId);
   if (!session) throw new Error('qa-sessions: session not found: ' + sessionId);
-  if (opts.success) {
-    if (!_isNonEmptyString(opts.wiPath)) {
-      throw new Error('qa-sessions: handleSetupComplete success requires wiPath');
+
+  const isMulti = session.setupStatus && typeof session.setupStatus === 'object'
+    && Object.keys(session.setupStatus).length > 1;
+
+  // ── Single-project fast path: original behavior, untouched semantics ──
+  if (!isMulti) {
+    if (opts.success) {
+      if (!_isNonEmptyString(opts.wiPath)) {
+        throw new Error('qa-sessions: handleSetupComplete success requires wiPath');
+      }
+      markDrafting(sessionId, { managedSpawnHealth: 'healthy' });
+      const updated = getSession(sessionId);
+      const wi = buildDraftWorkItem(updated, { project: opts.project || updated.spec.project || null });
+      _queueWorkItem(wi, opts.wiPath);
+      setSessionWorkItem(sessionId, SESSION_PHASE.DRAFT, wi.id);
+      return wi.id;
     }
-    markDrafting(sessionId, { managedSpawnHealth: 'healthy' });
-    // Re-read to pick up the state change for the DRAFT WI builder.
-    const updated = getSession(sessionId);
-    const wi = buildDraftWorkItem(updated, { project: opts.project || updated.spec.project || null });
-    _queueWorkItem(wi, opts.wiPath);
-    setSessionWorkItem(sessionId, SESSION_PHASE.DRAFT, wi.id);
-    return wi.id;
+    markFailed(sessionId, {
+      failureClass: opts.failureClass || 'qa-session-setup-failed',
+      error: opts.reason || null,
+      summary: opts.reason || 'SETUP phase failed',
+    });
+    return null;
   }
-  markFailed(sessionId, {
-    failureClass: opts.failureClass || 'qa-session-setup-failed',
-    error: opts.reason || null,
-    summary: opts.reason || 'SETUP phase failed',
-  });
-  return null;
+
+  // ── Multi-project fan-in path ─────────────────────────────────────────
+  const project = opts.project || null;
+  const key = project || '__central__';
+
+  // Update this project's entry under lock. Capture the merged map so we
+  // can decide on a transition without re-reading.
+  let mergedStatus = null;
+  mutateJsonFileLocked(qaSessionsPath(), (sessions) => {
+    if (!Array.isArray(sessions)) sessions = [];
+    const s = sessions.find(x => x && x.id === sessionId);
+    if (!s || !s.setupStatus) return sessions;
+    if (!s.setupStatus[key]) {
+      // Unknown project — log via error rather than crashing the lifecycle
+      // hook. Treat as if the WI for that project failed so the session
+      // doesn't stall waiting for an entry that will never arrive.
+      s.setupStatus[key] = { state: 'pending', wiId: null, error: null, completedAt: null };
+    }
+    s.setupStatus[key] = {
+      ...s.setupStatus[key],
+      state: opts.success ? 'success' : 'failed',
+      error: opts.success ? null : (opts.reason || opts.failureClass || 'unknown'),
+      completedAt: ts(),
+    };
+    s.updatedAt = ts();
+    mergedStatus = JSON.parse(JSON.stringify(s.setupStatus));
+    return sessions;
+  }, { defaultValue: [] });
+
+  if (!mergedStatus) return null;
+
+  const entries = Object.entries(mergedStatus);
+  const stillPending = entries.some(([, v]) => v.state === 'pending');
+  const anyFailed = entries.some(([, v]) => v.state === 'failed');
+
+  if (stillPending) {
+    // Wait for sibling WIs to report in. No state transition yet.
+    return null;
+  }
+
+  if (anyFailed) {
+    const errors = entries
+      .filter(([, v]) => v.state === 'failed')
+      .map(([k, v]) => ({ project: k === '__central__' ? null : k, reason: v.error }));
+    markFailed(sessionId, {
+      failureClass: 'qa-session-setup-failed',
+      error: JSON.stringify(errors),
+      summary: `SETUP phase failed for ${errors.length}/${entries.length} project(s)`,
+    });
+    return null;
+  }
+
+  // All success → advance to drafting and queue DRAFT on the PRIMARY's
+  // wiPath (captured at queueSetup time).
+  const fresh = getSession(sessionId);
+  const draftWiPath = fresh && fresh.primaryWiPath;
+  if (!_isNonEmptyString(draftWiPath)) {
+    throw new Error('qa-sessions: handleSetupComplete multi-project missing session.primaryWiPath');
+  }
+  markDrafting(sessionId, { managedSpawnHealth: 'healthy' });
+  const updated = getSession(sessionId);
+  const wi = buildDraftWorkItem(updated, { project: updated.primaryProject || updated.spec.project || null });
+  _queueWorkItem(wi, draftWiPath);
+  setSessionWorkItem(sessionId, SESSION_PHASE.DRAFT, wi.id);
+  return wi.id;
 }
 
 /**
@@ -1005,4 +1278,5 @@ module.exports = {
   summarizeSessionsForStatus,
   // Internals (exposed for tests)
   _isSafeSessionId,
+  _resolveSessionProjects,
 };

package/engine.js

@@ -5200,6 +5200,23 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
           .join(',')
       : '',
     session_mode: (item.meta && item.meta.qaSession && item.meta.qaSession.mode) || '',
+    // W-mpq6xqzj000606d0 — Multi-project QA Session fan-out vars. SETUP fan-out
+    // queues one WI per project with meta.qaSession.primary boolean +
+    // coServices array (set by qa-sessions._baseWorkItem). Surface them here as
+    // template vars so the SETUP playbook can branch on {{role}} and so the
+    // primary's prompt sees the canonical primary_project + co_services_json
+    // it needs to poll each co-service's managed-spawn health before
+    // finalizing. Single-project sessions never set qaSession.primary, so all
+    // three vars resolve to empty strings (filtered via PLAYBOOK_OPTIONAL_VARS).
+    role: (item.meta && item.meta.qaSession && typeof item.meta.qaSession.primary === 'boolean'
+      ? (item.meta.qaSession.primary ? 'primary' : 'co-service')
+      : ''),
+    primary_project: (item.meta && item.meta.qaSession && item.meta.qaSession.primaryProject)
+      ? String(item.meta.qaSession.primaryProject)
+      : '',
+    co_services_json: (item.meta && item.meta.qaSession && Array.isArray(item.meta.qaSession.coServices)
+      ? JSON.stringify(item.meta.qaSession.coServices)
+      : ''),
     // P-f9a2e1b4 — Runner adapter briefs. The DRAFT playbook consumes
     // {{runner_brief}} (runner.generateBrief() output); EXECUTE consumes
     // {{runner_execute_brief}} (runner.executeBrief() output) plus

package/package.json

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

package/playbooks/qa-session-setup.md

@@ -24,9 +24,41 @@ A user asked Minions to QA the following target and flows:
 - **Runner hint (optional explicit runner):** `{{runner_hint}}`
 - **Capture:** `{{capture}}`
 - **Mode:** `{{session_mode}}`
+- **Role (multi-project fan-out):** `{{role}}` *(empty = single-project session, behave as if `primary`)*
+- **Primary project (multi-project fan-out):** `{{primary_project}}`
+- **Co-services JSON (multi-project fan-out):** `{{co_services_json}}`
 
 {{additional_context}}
 
+## Multi-project fan-out (W-mpq6xqzj000606d0)
+
+When the user picks **multiple projects** from the QA Session form, the engine
+queues one SETUP work item **per project** in parallel. Each WI sees the same
+target/flows/managed_spawn_name, but with a different `{{role}}` value:
+
+- **`{{role}} == "primary"`** *(or empty for single-project sessions)*: you are
+  the orchestrator. You own the canonical `{{managed_spawn_name}}` (no suffix)
+  and your work item's wiPath is the one that gets the DRAFT phase queued
+  on it once **all** SETUP WIs succeed. If `{{co_services_json}}` is non-empty
+  (e.g. `["api","worker"]`), the DRAFT and EXECUTE agents will poll each of
+  those co-services' managed-spawn health (name = `{{managed_spawn_name}}-<project>`)
+  via `/api/managed-processes/by-name` before treating the system as ready.
+- **`{{role}} == "co-service"`**: you are a supporting service (DB, API,
+  worker, etc.). Your managed-spawn `name` MUST be `{{managed_spawn_name}}-<your-project>`
+  (the engine appends `-<project>` automatically when computing the spec name).
+  You do **not** write tests, do not queue DRAFT — just stand up your service,
+  declare its healthcheck, and exit clean. The primary's DRAFT/EXECUTE will
+  reach you over the network (use a deterministic port; document it in
+  `managed-spawn.json` `ports[]`).
+
+Any co-service SETUP that fails (sidecar invalid, healthcheck miss, build
+error) **fails the entire session** with `failure_class: 'qa-session-setup-failed'`
+and a per-project error JSON in `session.error`. The primary's WI does NOT
+get the DRAFT phase queued in that case.
+
+For single-project sessions (`{{co_services_json}}` empty or `[]`), ignore
+this section — the original single-WI flow applies unchanged.
+
 ## What "qa-session-setup" means
 
 A `qa-session-setup` task is the **first** of three chained work items the

package/prompts/cc-system.md

@@ -186,25 +186,33 @@ When the user describes a UI/E2E flow they want validated against a *live, runni
 - `mode` — `"confirm"` (default — pauses at `awaiting-approval` so the user can review the drafted test before EXECUTE fires) or `"auto"` (chains straight from DRAFT to EXECUTE). Pick `"confirm"` unless the user said "just run it" / "no review needed" / "auto".
 - `capture` — optional `{ video?: bool, screenshots?: bool, logs?: bool }`. Default is everything false. Set what the user asked for.
 - `runner` — optional kebab-case name to force a specific runner (`"playwright"`, `"maestro"`, or a plugin). Omit to let the engine auto-detect (Maestro wins when the project has `.maestro/`; Playwright is the safe default).
-- `project` — REQUIRED when multiple projects are configured (mirrors `/api/work-items`). Omit for the central path.
+- `project` — REQUIRED (legacy single-project form) when multiple projects are configured (mirrors `/api/work-items`). Omit for the central path. **Multi-project form (W-mpq6xqzj000606d0):** pass `projects: string[]` (≤5) instead of `project` to QA across multiple services in parallel. The first entry is the **primary** (owns DRAFT/EXECUTE and the canonical managed-spawn name); the rest are **co-services** (each gets a SETUP work item that stands up its dev-up command, named `qa-session-<id>-<project>`). All co-services must pass first-healthcheck before DRAFT fires; any failure fails the whole session. Use this when the user says "QA the api+worker against PR #X" or "smoke test the full stack on `develop`".
 
-**Worked example — PR target, confirm mode (default):**
+**Worked example — PR target, confirm mode (default), single project:**
 ```
 curl -s -X POST http://localhost:{{dashboard_port}}/api/qa/session \
   -H 'Content-Type: application/json' \
   -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
-  -d '{"target":{"kind":"pr","prId":"github:yemi33/MyApp#1234"},"flowsRaw":"Open the homepage, click Login, enter test@example.com / hunter2, and verify the dashboard renders with the user'\''s name in the header.","mode":"confirm","capture":{"screenshots":true,"logs":true},"project":"MyApp"}'
+  -d '{"target":{"kind":"pr","prId":"github:yemi33/MyApp#1234"},"flowsRaw":"Open the homepage, click Login, enter test@example.com / hunter2, and verify the dashboard renders with the user'\''s name in the header.","mode":"confirm","capture":{"screenshots":true,"logs":true},"projects":["MyApp"]}'
 ```
 
-**Worked example — current worktree, auto mode, video capture:**
+**Worked example — current worktree, auto mode, video capture, single project:**
 ```
 curl -s -X POST http://localhost:{{dashboard_port}}/api/qa/session \
   -H 'Content-Type: application/json' \
   -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
-  -d '{"target":{"kind":"current"},"flowsRaw":"Add three items to the cart, go to checkout, complete the payment form with the Stripe test card, and verify the success page.","mode":"auto","capture":{"video":true,"screenshots":true},"project":"MyApp"}'
+  -d '{"target":{"kind":"current"},"flowsRaw":"Add three items to the cart, go to checkout, complete the payment form with the Stripe test card, and verify the success page.","mode":"auto","capture":{"video":true,"screenshots":true},"projects":["MyApp"]}'
 ```
 
-**Response:** `{ sessionId, state: "spawning", setupWorkItemId, managedSpawnName }`. Tell the user the session id so they can watch it at `/qa` and steer it via the `/approve` (run the drafted test), `/edit` (re-draft with feedback), `/dismiss` (accept the draft without running), `/cancel` (give up), or `/kill` (cancel + tear down the managed-spawn) endpoints listed in `GET /api/routes`.
+**Worked example — multi-project fan-out (primary + 2 co-services):**
+```
+curl -s -X POST http://localhost:{{dashboard_port}}/api/qa/session \
+  -H 'Content-Type: application/json' \
+  -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
+  -d '{"target":{"kind":"branch","branch":"develop"},"flowsRaw":"Place an order on the storefront and verify it shows up in the admin panel within 5 seconds.","mode":"confirm","capture":{"video":true,"logs":true},"projects":["storefront","api","worker"]}'
+```
+
+**Response:** `{ sessionId, state: "spawning", setupWorkItemId, managedSpawnName, projects? }`. `setupWorkItemId` is the **primary's** WI id; `projects` is the canonical array (single-project sessions omit it). Tell the user the session id so they can watch it at `/qa` and steer it via the `/approve` (run the drafted test), `/edit` (re-draft with feedback), `/dismiss` (accept the draft without running), `/cancel` (give up), or `/kill` (cancel + tear down the managed-spawn) endpoints listed in `GET /api/routes`.
 
 **Do not also dispatch a `/api/work-items` `implement` or `test` for the same QA request.** The QA Session pipeline owns its own SETUP → DRAFT → EXECUTE work items end-to-end; firing a parallel work-item is the same double-dispatch class that the "Never both" rule above forbids. If the user asks for both a QA pass AND a code change, do them as two separate, sequential calls — QA Session for the behavioural check, work-item for the fix.