@yemi33/minions 0.1.2344 → 0.1.2345

package/docs/managed-spawn.md

@@ -104,6 +104,33 @@ Runs the command with `child_process.exec` / `spawn`, asserts both exit code 0 A
 
 `tcp` and `log-match` healthcheck types are intentionally not implemented — see the plan's Rejected items for the reasoning.
 
+### Native app / emulator-backed targets (issue #712)
+
+Not every managed-spawn target is a TCP-bound HTTP dev server. Native mobile/desktop apps (e.g. an Android Gradle/Kotlin app) have no HTTP endpoint to probe. Use a `command` healthcheck instead of `http`, and declare the emulator/simulator/device **boot** — not the app itself — as the long-lived spec:
+
+1. Spawn only the long-lived environment dependency (emulator/simulator/device boot, or an already-running device-farm session) as the managed-spawn spec.
+2. Defer the one-shot build + install + launch (e.g. a 30-45 minute Gradle assemble/installDebug/am start) to the DRAFT/EXECUTE phase rather than declaring it as the spec's `cmd` — managed-spawn owns persistent processes, not one-shot commands.
+3. Poll the boot/ready signal with a `command` healthcheck. For Android, `adb shell getprop sys.boot_completed` matched against `^1$` is the canonical ready signal.
+
+```jsonc
+{
+  "name": "android-emulator",
+  "cmd": "emulator",
+  "args": ["-avd", "Pixel_6_API_34", "-no-snapshot", "-no-window"],
+  "healthcheck": {
+    "type": "command",
+    "cmd": "adb",
+    "args": ["shell", "getprop", "sys.boot_completed"],
+    "shell": false,
+    "expect_regex": "^1$",
+    "interval_s": 5,
+    "timeout_s": 180
+  }
+}
+```
+
+Known device-farm tooling: `adb` and `emulator` are both on the managed-spawn executable allowlist (device/emulator shell + install + logcat; `emulator -list-avds` discovers configured AVDs before picking one). `maestro` is a declarative mobile UI-flow runner already wired in as a built-in QA runner adapter (`engine/qa-runners.js`) for the DRAFT/EXECUTE phases — it is not itself on the managed-spawn `cmd`/healthcheck allowlist. The full worked example — including `ttl_minutes`, `attrs`, `written_by`/`wi_id` — is inlined in [`buildManagedSpawnHint`](../engine/managed-spawn.js).
+
 ### Non-PATH native launcher binaries (e.g. Android SDK's `emulator.exe` / `adb.exe`)
 
 `adb` and `emulator` are already on `executableAllowlist` (basename matching strips `.exe`/`.cmd`/`.bat`/`.ps1`/`.sh`, so `spec.cmd` can be a bare name resolved via PATH *or* a full absolute path — `path.basename()` matching doesn't care how deep the path is). This covers the common case directly; you do **not** need a `powershell -Command` wrapper just to launch a native SDK tool (issue #711).

package/engine/lifecycle.js

@@ -6789,6 +6789,16 @@ function autoDispatchLiveValidationWi(meta, config) {
   // "Validate: Validate: ..." cascade (W-mr9u39az000db5c2 / issue #708).
   if (item.meta && item.meta.liveValidationFor) return;
 
+  // Issue #716 — QA Session infrastructure WIs (SETUP/DRAFT/EXECUTE, tagged
+  // via meta.sessionId and always dispatched with skipPr:true) never own a
+  // real code diff, so there is nothing for a live-validation WI to validate.
+  // Without this guard, a QA Session WI whose type happens to be one of the
+  // configured liveValidation.type entries (qa-sessions uses WORK_TYPE.TEST
+  // for all three phases) spawns spurious "Validate: QA Session ..." WIs the
+  // moment any PR reference resolves against it (see the skipPr guard below
+  // resolveWorkItemPrRecord in engine.js for the matching pre-dispatch fix).
+  if (item.skipPr || (item.meta && item.meta.sessionId)) return;
+
   const projectName = meta?.project?.name;
   if (!projectName) return;
 

package/engine/managed-spawn.js

@@ -694,6 +694,45 @@ function buildManagedSpawnHint(opts) {
     '',
     'Equivalent flags for other runtimes: `pnpm --filter <pkg>`, `yarn workspace <pkg>`, `npm run -w <pkg>`, `lage run <task> --to <pkg>`. Keeping `cwd` at the root makes the spec portable across machines (no hard-coded package path) and avoids per-package `node_modules` resolution surprises.',
     '',
+    '### Native app / emulator-backed targets (W-mr9w1p8n000i08c0, issue #712)',
+    '',
+    'Not every target is a TCP-bound HTTP dev server. Native mobile/desktop apps (e.g. an Android Gradle/Kotlin app) have no HTTP endpoint to probe — do NOT force an `http` healthcheck onto them. Use a `command`-type healthcheck instead, and treat the emulator/simulator/device **boot** as the long-lived "service" you declare here, not the one-shot build+install+launch.',
+    '',
+    '**Pattern:**',
+    '1. Spawn only the long-lived environment dependency (emulator/simulator/device boot, or an already-running device-farm session) as the managed-spawn spec. It has no meaningful exit — it just needs to stay alive and reach a ready state.',
+    '2. Defer the actual one-shot build + install + launch (e.g. a 30-45 minute Gradle assemble/installDebug/am start) to the DRAFT/EXECUTE phase instead of declaring it as this spec\'s `cmd` — a one-shot command is not something managed-spawn should own as a persistent process.',
+    '3. Use a `command` healthcheck that polls the boot/ready signal and asserts on stdout via `expect_regex`, not an HTTP `expect_status`. For Android, `adb shell getprop sys.boot_completed` polled until it matches `^1$` is the canonical boot-ready signal.',
+    '',
+    'Example — Android emulator boot as the managed spec:',
+    '',
+    '```jsonc',
+    '{',
+    '  "specs": [',
+    '    {',
+    '      "name": "android-emulator",',
+    '      "cmd": "emulator",',
+    '      "args": ["-avd", "Pixel_6_API_34", "-no-snapshot", "-no-window"],',
+    '      "cwd": "' + minionsDir + '",',
+    '      "ttl_minutes": ' + ttl + ',',
+    '      "attrs": { "avd": "Pixel_6_API_34" },',
+    '      "healthcheck": {',
+    '        "type": "command",',
+    '        "cmd": "adb",',
+    '        "args": ["shell", "getprop", "sys.boot_completed"],',
+    '        "shell": false,',
+    '        "expect_regex": "^1$",',
+    '        "interval_s": 5,',
+    '        "timeout_s": 180',
+    '      }',
+    '    }',
+    '  ],',
+    '  "written_by": "' + agentId + '",',
+    '  "wi_id": "' + wiId + '"',
+    '}',
+    '```',
+    '',
+    'Known device-farm tooling to reach for instead of re-deriving a pattern from scratch: `adb` and `emulator` (both on the managed-spawn executable allowlist — device/emulator shell, install, logcat; `emulator -list-avds` discovers configured AVDs before you pick one for the spec), and `maestro` (declarative mobile UI-flow runner already wired in as a built-in QA runner adapter — see `engine/qa-runners.js` — for the DRAFT/EXECUTE phases, not for the managed-spawn `cmd`/healthcheck allowlist itself).',
+    '',
     '### Verify before exit',
     '',
     'After you write the file, query the engine to confirm acceptance:',

package/engine/qa-sessions.js

@@ -681,6 +681,39 @@ function markDone(id, patch) { return transitionSession(id, QA_SESSION_STATE.DON
 function markFailed(id, patch) { return transitionSession(id, QA_SESSION_STATE.FAILED, patch); }
 function markKilled(id, patch) { return transitionSession(id, QA_SESSION_STATE.KILLED, patch); }
 
+// Issue #716 — a lifecycle completion hook (handleSetupComplete/
+// handleDraftComplete/handleExecuteComplete) can race a human/engine action
+// that already pushed the session to a terminal state (failed/done/killed) —
+// e.g. a retried SETUP dispatch finally succeeds AFTER the first attempt's
+// 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,
+// 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
+// is visible instead of vanishing into engine logs.
+//
+// Returns true when the session is already terminal (caller must return
+// early without applying opts); false when the caller should proceed.
+function _guardAlreadyTerminal(sessionId, session, phase, opts) {
+  if (!session || !TERMINAL_STATES.has(session.state)) return false;
+  const detail = `qa-sessions: ${phase} completion for session ${sessionId} arrived after the ` +
+    `session was already terminal (state=${session.state}). opts.success=${!!opts.success}. ` +
+    'This completion is NOT applied — the session stays ' + session.state + '.' +
+    (opts.success
+      ? ' The underlying dispatch reported SUCCESS, so real completed work may now be orphaned' +
+        ' — a human should inspect and manually resume/requeue the session if needed.'
+      : '');
+  log('warn', detail);
+  try {
+    // Lazy require (mirrors engine/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);
+  } 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.
@@ -1014,6 +1047,7 @@ function queueSetup(sessionId, opts = {}) {
 function handleSetupComplete(sessionId, opts = {}) {
   const session = getSession(sessionId);
   if (!session) throw new Error('qa-sessions: session not found: ' + sessionId);
+  if (_guardAlreadyTerminal(sessionId, session, 'SETUP', opts)) return null;
 
   const isMulti = session.setupStatus && typeof session.setupStatus === 'object'
     && Object.keys(session.setupStatus).length > 1;
@@ -1123,6 +1157,9 @@ function handleSetupComplete(sessionId, opts = {}) {
 function handleDraftComplete(sessionId, opts = {}) {
   const session = getSession(sessionId);
   if (!session) throw new Error('qa-sessions: session not found: ' + sessionId);
+  if (_guardAlreadyTerminal(sessionId, session, 'DRAFT', opts)) {
+    return { nextState: session.state, queuedExecuteWi: null };
+  }
   if (!opts.success) {
     markFailed(sessionId, {
       failureClass: 'qa-session-draft-failed',
@@ -1170,6 +1207,7 @@ function handleDraftComplete(sessionId, opts = {}) {
 function handleExecuteComplete(sessionId, opts = {}) {
   const session = getSession(sessionId);
   if (!session) throw new Error('qa-sessions: session not found: ' + sessionId);
+  if (_guardAlreadyTerminal(sessionId, session, 'EXECUTE', opts)) return session.state;
   // qa-run terminal status (when known) trumps dispatch-level success — a
   // passing assertion run with an exit-1 wrapper still reports a passed
   // qa-run; we mark the session done. Conversely, a failed/errored qa-run

package/engine.js

@@ -7115,19 +7115,30 @@ async function discoverFromPrs(config, project) {
   const autoFixBuilds = !autoFixPaused && (config.engine?.autoFixBuilds ?? ENGINE_DEFAULTS.autoFixBuilds);
   const autoFixConflicts = !autoFixPaused && (config.engine?.autoFixConflicts ?? ENGINE_DEFAULTS.autoFixConflicts);
 
-  // Collect active PR dispatches to prevent simultaneous review+fix on same PR
+  // Collect active PR dispatches to prevent simultaneous review+fix on same PR.
+  // Issue #722: `meta.pr.id` alone is not proof the dispatch actually touches
+  // the PR's branch — a tracking-only dispatch (e.g. a follow-up work item
+  // whose `pr_followup.parent_pr_id` merely references the PR for context,
+  // engine.js `dispatchLinkedPr` ~line 8551) carries `meta.pr` while running
+  // on a completely unrelated `meta.branch`. Recording each dispatch's own
+  // branch here lets the loop below only trip the guard on real git-resource
+  // overlap instead of freezing all automation on the PR indefinitely.
   const dispatch = getDispatch();
-  const activePrIds = new Set(
-    (dispatch.active || [])
-      .filter(d => d.meta?.pr?.id)
-      .map(d => {
-        const dispatchProject = d.meta?.project?.name
-          ? (shared.resolveProjectSource(d.meta.project.name, shared.getProjects(config), { allowCentral: false }).project || d.meta.project)
-          : (d.meta?.project || null);
-        return shared.getCanonicalPrId(dispatchProject, d.meta.pr, d.meta.pr?.url || '');
-      })
-      .filter(Boolean)
-  );
+  const activePrDispatchBranches = new Map(); // canonicalPrId -> Set<normalized branch | null>
+  for (const d of (dispatch.active || [])) {
+    if (!d.meta?.pr?.id) continue;
+    const dispatchProject = d.meta?.project?.name
+      ? (shared.resolveProjectSource(d.meta.project.name, shared.getProjects(config), { allowCentral: false }).project || d.meta.project)
+      : (d.meta?.project || null);
+    const canonicalId = shared.getCanonicalPrId(dispatchProject, d.meta.pr, d.meta.pr?.url || '');
+    if (!canonicalId) continue;
+    if (!activePrDispatchBranches.has(canonicalId)) activePrDispatchBranches.set(canonicalId, new Set());
+    // `null` is a sentinel for "branch unknown" — legacy/defensive dispatches
+    // with no meta.branch fall back to the old conservative (always-skip)
+    // behavior rather than risk a false negative.
+    activePrDispatchBranches.get(canonicalId).add(d.meta?.branch ? normalizePrBranch(d.meta.branch) : null);
+  }
+  const activePrIds = new Set(activePrDispatchBranches.keys());
 
   for (const pr of prs) {
     if (pr.status !== PR_STATUS.ACTIVE) continue;
@@ -7140,8 +7151,21 @@ async function discoverFromPrs(config, project) {
     if (!shared.isPrCompatibleWithProject(project, pr, pr.url || '')) continue;
     const prDisplayId = shared.getPrDisplayId(pr);
     const prCanonicalId = shared.getCanonicalPrId(project, pr, pr.url || '');
-    if (activePrIds.has(prCanonicalId)) continue; // Skip PRs with active dispatch (prevent race)
     const prBranchForMutex = resolvePrBranch(pr);
+    if (activePrIds.has(prCanonicalId)) {
+      const dispatchBranches = activePrDispatchBranches.get(prCanonicalId);
+      const prOwnBranch = normalizePrBranch(prBranchForMutex);
+      // Guard trips (skip PR) when: any active dispatch's branch is unknown
+      // (conservative fallback), or the PR's own branch is unknown (can't
+      // prove non-overlap), or a dispatch's branch actually matches the PR's
+      // branch (real overlap). Otherwise every active dispatch referencing
+      // this PR id is tracking-only on a different branch — let discovery
+      // proceed.
+      const realOverlap = !prOwnBranch
+        || [...dispatchBranches].some(b => b === null || b === prOwnBranch);
+      if (realOverlap) continue; // Skip PRs with active dispatch (prevent race)
+      log('info', `Race-guard: PR ${prDisplayId} (${prCanonicalId}) referenced by ${dispatchBranches.size} active dispatch(es) tracking-only on unrelated branch(es) — not blocking automation`);
+    }
     // Branch mutex: skip if PR branch is locked by any active dispatch (cross-type collision)
     if (prBranchForMutex && isBranchActive(prBranchForMutex)) {
       log('info', `Branch mutex: skipping PR ${pr.id} dispatch — branch ${prBranchForMutex} locked by another agent`);
@@ -8455,7 +8479,17 @@ function discoverFromWorkItems(config, project) {
       shared.autoEnrollPrFromWorkItem(item, project, MINIONS_DIR);
     } catch (e) { log('warn', `auto-enroll PR for ${item.id}: ${e.message}`); }
 
-    const linkedPr = resolveWorkItemPrRecord(item, project);
+    // Issue #716 — `item.skipPr` marks work items that never own a PR (QA
+    // Session SETUP/DRAFT/EXECUTE WIs are the canonical example: `skipPr:
+    // true`, `oneShot: true`). Their descriptions legitimately embed the
+    // *target's* PR reference as prose/JSON (e.g. `Target: {"kind":"pr",
+    // "prId":"..."}`), which the LOOSE getWorkItemPrRef text-scan (used by
+    // resolveWorkItemPrRecord) misreads as "this work item is about that PR"
+    // — resolving/attaching an unrelated PR record, corrupting branchName
+    // resolution below, and (via stampWiPrRef/autoDispatchLiveValidationWi)
+    // mislabeling the WI's own `_pr` field. skipPr WIs must never enter PR
+    // context inference.
+    const linkedPr = item.skipPr ? null : resolveWorkItemPrRecord(item, project);
     const promptItem = linkedPr ? withWorkItemPrContext(item, linkedPr) : item;
     const prBranch = linkedPr?.branch || '';
     const isPrTargeted = !!(linkedPr && (workType === WORK_TYPE.FIX || workType === WORK_TYPE.REVIEW || workType === WORK_TYPE.TEST));

package/package.json

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

@@ -77,6 +77,14 @@ live instance:
    project README "Run locally / Getting Started" section, a `Makefile` `dev`
    target, or a docker-compose service that exposes an HTTP port. Pick the
    smallest command that brings the app up and binds to a TCP port.
+   - **Native app / emulator-backed target (no HTTP surface)?** — e.g. an
+     Android Gradle/Kotlin app, an iOS simulator target. Do not force an HTTP
+     healthcheck onto it. Spawn only the long-lived environment dependency
+     (emulator/simulator/device boot) here and defer the one-shot
+     build+install+launch to DRAFT/EXECUTE; use a `command` healthcheck (e.g.
+     `adb shell getprop sys.boot_completed` polled for `^1$`) as the readiness
+     signal. See the "Native app / emulator-backed targets" section of the
+     `managed_spawn` block below for the full worked example.
 3. **Write the managed-spawn sidecar** to
    `agents/{{agent_id}}/managed-spawn.json` (relative to the Minions root)
    with **exactly one** spec named **`{{managed_spawn_name}}`**. Use the JSON