@yemi33/minions 0.1.2082 → 0.1.2084

package/docs/keep-processes.md

@@ -0,0 +1,47 @@
+# `keep_processes` sidecar
+
+> Opt-in mechanism for agents that spawn detached children themselves and need to leave them running past their own exit. The companion to engine-owned [managed-spawn](managed-spawn.md).
+
+## When to use `keep_processes`
+
+| Need | Use this |
+|---|---|
+| Long-running dev server / emulator the engine should own across restarts | [managed-spawn](managed-spawn.md) |
+| Short-lived helper the *same* agent needs alive past exit (e.g. `gradle --daemon` for the next gradle invocation) | `meta.keep_processes` |
+| Executable outside the managed-spawn allowlist | `meta.keep_processes` |
+| Service with no healthcheck | `meta.keep_processes` |
+| One-shot script that exits on its own | Neither |
+
+Both can coexist on the same WI. There's no plan to deprecate `keep_processes`; a future cleanup PR can revisit if managed-spawn fully subsumes its use cases.
+
+## Sidecar contract
+
+Set `meta.keep_processes: true` on the WI; agent writes `agents/<id>/keep-pids.json` before exit:
+
+```jsonc
+{
+  "pids": [12345],                 // ≤5 entries
+  "purpose": "gradle daemon for follow-up test WI",
+  "cwd": "D:/repos/my-android-app", // MUST be a real git worktree
+  "ports": [8080],                  // advisory, engine doesn't bind
+  "expires_at": "2026-04-29T00:00:00Z", // TTL ≤1440 min; default 60
+  "written_by": "ripley",
+  "wi_id": "W-mpqtg16a0007f5bb"
+}
+```
+
+`buildKeepProcessesHint` bakes the Windows-correct detached-spawn pattern (`spawn(..., { detached: true, stdio: 'ignore' }).unref()` plus the `start /B` fallback on cmd-only shells) into the agent prompt automatically — agents should not hand-roll the detach call.
+
+## Lifecycle
+
+- **Validation:** sidecar shape + workdir checked in `onAgentClose`. Failure → non-retryable `failure_class: invalid-keep-processes-{workdir,schema}`.
+- **Sweep:** [`engine/keep-process-sweep.js`](../engine/keep-process-sweep.js) reaps at boot and every 30 ticks. Dead PIDs are pruned; expired TTL → process killed via `shared.killGracefully` then `killImmediate`.
+- **No healthcheck:** unlike managed-spawn, `keep_processes` does not gate WI completion on first-healthy. If the child crashes immediately the agent still succeeds — by design (ad-hoc helper semantics).
+
+## Caps
+
+- **PIDs:** ≤5 per sidecar.
+- **TTL:** ≤1440 min (24h). Default 60.
+- **Cwd:** must exist and resolve to inside a git worktree (`requireGitWorkdir: true`). Monorepo subdirs walk up to `gitWorktreeMaxParentDepth` (default 6).
+
+See also: [`CLAUDE.md`](../CLAUDE.md) → **Agent Spawn**, [managed-spawn.md](managed-spawn.md).

package/docs/qa-runbook-lifecycle.md

@@ -138,6 +138,26 @@ routing default):
    the session `spawning → drafting`. First-health failure → `failed` with
    `failure_class: qa-session-setup-failed`.
 
+   **Multi-project fan-out (W-mpq6xqzj000606d0):** when `spec.projects`
+   contains more than one project name, SETUP is fanned out — one work item
+   per project, queued in parallel into each project's own
+   `work-items.json`. The first project (`spec.projects[0]`) is the
+   **primary** (`meta.qaSession.primary === true`); the rest are
+   **co-services** (`primary === false`). Each WI's
+   `meta.qaSession.coServices` lists the co-service project names (only the
+   primary carries the full list; co-services see `[]`) and
+   `meta.qaSession.primaryProject` carries the canonical primary name.
+   The primary keeps the unsuffixed managed-spawn name; each co-service
+   gets `qa-session-<sessionId>-<project>`. The session tracks per-project
+   completion in `session.setupStatus[<project>]: { state, wiId, error,
+   completedAt }`, where `state ∈ {pending, success, failed}`. **All**
+   projects must succeed before `spawning → drafting`; any failure flips
+   the session to `failed` with `failure_class: qa-session-setup-failed`
+   and a JSON-encoded per-project error array in `session.error`. DRAFT
+   queues on `session.primaryWiPath` (stamped at queueSetup time).
+   Single-project sessions skip `setupStatus` entirely (fast path uses
+   `session.state` directly).
+
 2. **DRAFT** (`playbooks/qa-session-draft.md`) reads the live spawn
    metadata via `/api/managed-processes/by-name/qa-session-<id>`, calls the
    resolved runner's `generateBrief({target, flowsRaw, capture})` hook, and
@@ -168,7 +188,7 @@ Documented in `dashboard.js`; routes are visible at `GET /api/routes`.
 
 | Method | Path                                       | Behavior                                                                                                                  |
 |--------|--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
-| POST   | `/api/qa/session`                          | Create session; validates spec, calls `createSession` + `queueSetup` (`pending → spawning`). Returns `sessionId`, `setupWorkItemId`, `managedSpawnName`. |
+| POST   | `/api/qa/session`                          | Create session; validates spec, calls `createSession` + `queueSetup` (`pending → spawning`). Body accepts `project: string` (single) OR `projects: string[]` (multi, ≤5; first is primary, rest are co-services). Returns `sessionId`, `setupWorkItemId` (primary's WI), `managedSpawnName`, and (multi only) `projects: string[]`. |
 | GET    | `/api/qa/sessions`                         | List sessions newest-first. Optional `?limit=N` and `?state=pending\|spawning\|drafting\|awaiting-approval\|executing\|done\|failed\|killed`. |
 | GET    | `/api/qa/sessions/<id>`                    | Fetch a single session record by id.                                                                                      |
 | POST   | `/api/qa/sessions/<id>/approve`            | `awaiting-approval → executing`. Server-side creates the linked `qa-runs` record (synthetic `runbookId='qa-session-<id>'`), queues EXECUTE WI, stamps `qaRunId` on the session. |

package/engine/features.js

@@ -51,14 +51,19 @@ const FEATURES = {
   // is the canonical predicate every dashboard.js call site uses. Explicit
   // `engine.ccUseWorkerPool` true/false in config wins ONLY when CC runtime
   // is copilot; otherwise the helper forces `false`. PR #2492 flipped the
-  // copilot default ON; see that PR for the cold-spawn measurements.
+  // copilot resolver default ON; W-mpqf3ybq000455f2 flipped this registry
+  // default ON to match the resolved behavior (so the Settings/`/api/features`
+  // surface reports the same default the runtime actually uses). The pool
+  // has been stable since PR #2492's cold-spawn measurements; opt-out via
+  // `config.features.ccUseWorkerPool: false` or `engine.ccUseWorkerPool: false`
+  // still works.
   //
   // `requiredCcRuntime: 'copilot'` here is a UX hint — the Settings panel
   // greys out the toggle when the resolved CC runtime mismatches so users
   // see the constraint instead of toggling a no-op.
   'ccUseWorkerPool': {
     description: 'Route Command Center / doc-chat through a persistent `copilot --acp` worker per tab instead of spawning a fresh CLI per turn (~14s cold-start savings). Copilot-only — has no effect when the CC runtime is Claude.',
-    default: false,
+    default: true,
     addedIn: '0.1.1916',
     requiredCcRuntime: 'copilot',
   },

package/engine/playbook.js

@@ -325,6 +325,14 @@ const PLAYBOOK_OPTIONAL_VARS = new Set([
   'runner_brief',          // generateBrief() output — used by qa-session-draft
   'runner_execute_brief',  // executeBrief() output — used by qa-session-execute
   'test_file',             // session.testFile — set after DRAFT, used by EXECUTE
+  // W-mpq6xqzj000606d0 — Multi-project QA Session fan-out. SETUP playbook
+  // gets one work item per project; these vars distinguish the "primary"
+  // (which owns DRAFT/EXECUTE handoff and the canonical managed-spawn name)
+  // from N "co-service" WIs (which just declare their own managed-spawn and
+  // exit). Optional because single-project sessions never set them.
+  'role',                  // 'primary' | 'co-service'
+  'primary_project',       // canonical primary project name; empty on single-project sessions
+  'co_services_json',      // JSON-encoded co-service project names (e.g. ["api","worker"]); empty when none
 ]);
 
 const PLAYBOOK_REQUIRED_VARS = {

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.2082",
+  "version": "0.1.2084",
   "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"