@yemi33/minions 0.1.2343 → 0.1.2345

package/dashboard/js/refresh.js

@@ -421,6 +421,13 @@ function _refreshSidebarCounterSummaries() {
     .then(function (r) { return r.ok ? r.json() : null; })
     .then(function (s) { if (s && typeof s === 'object') window._lastQaRunsSummary = s; })
     .catch(function () { /* sidebar counter degrades to /api/status fallback */ });
+  // QA nav badge count (issue #717) — non-terminal session count, distinct
+  // from the qa-runs-summary activity dot above (that one tracks qa RUNS,
+  // this tracks in-flight qa SESSIONS).
+  fetch('/api/qa-sessions-summary')
+    .then(function (r) { return r.ok ? r.json() : null; })
+    .then(function (s) { if (s && typeof s === 'object') window._lastQaSessionsSummary = s; })
+    .catch(function () { /* sidebar badge degrades to empty */ });
   fetch('/api/meetings-total')
     .then(function (r) { return r.ok ? r.json() : null; })
     .then(function (s) { if (s && typeof s.total === 'number') window._lastMeetingsTotal = s.total; })
@@ -1012,6 +1019,10 @@ function _processStatusUpdate(data, opts) {
   if (swi) swi.textContent = (window._lastWorkItems || []).length || '';
   const spr = document.getElementById('sidebar-pr');
   if (spr) spr.textContent = (window._lastPullRequests || []).length || '';
+  // QA nav badge — count of non-terminal sessions (issue #717). Populated
+  // from the /api/qa-sessions-summary fetch in _refreshSidebarCounterSummaries.
+  const sqa = document.getElementById('sidebar-qa');
+  if (sqa) sqa.textContent = (window._lastQaSessionsSummary && window._lastQaSessionsSummary.active) || '';
   // Refresh KB and plans every status cycle (~4s) so plan status flips
   // (approve/archive/complete) and KB additions surface within the SPA's
   // 4s poll target. Server-side caches keep this cheap:

package/dashboard/layout.html

@@ -104,7 +104,7 @@
     <a class="sidebar-link" data-page="work" href="/work">Work Items <span class="sidebar-count" id="sidebar-wi"></span></a>
     <a class="sidebar-link" data-page="plans" href="/plans">Plans & PRD</a>
     <a class="sidebar-link" data-page="prs" href="/prs">Pull Requests <span class="sidebar-count" id="sidebar-pr"></span></a>
-    <a class="sidebar-link" data-page="qa" href="/qa" title="QA — live processes + validation runbooks (managed-spawn + keep-processes)">QA</a>
+    <a class="sidebar-link" data-page="qa" href="/qa" title="QA — live processes + validation runbooks (managed-spawn + keep-processes)">QA <span class="sidebar-count" id="sidebar-qa"></span></a>
     <a class="sidebar-link" data-page="inbox" href="/inbox">Notes & KB</a>
     <a class="sidebar-link" data-page="tools" href="/tools">Skills & MCP</a>
     <a class="sidebar-link" data-page="schedule" href="/schedule" title="Cron-based recurring tasks (single task per schedule)">Schedules</a>

package/dashboard.js

@@ -48,6 +48,7 @@ const issues = require('./engine/issues');
 const watchesMod = require('./engine/watches');
 const meetingMod = require('./engine/meeting');
 const qaRunsMod = require('./engine/qa-runs');
+const qaSessionsMod = require('./engine/qa-sessions');
 const routing = require('./engine/routing');
 const playbook = require('./engine/playbook');
 const dispatchMod = require('./engine/dispatch');
@@ -13399,6 +13400,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         builder: () => qaRunsMod.summarizeRunsForStatus(),
       });
     }},
+    { method: 'GET', path: '/api/qa-sessions-summary', desc: 'Sidebar-counter summary {active, sig} for non-terminal QA sessions (drives the QA nav badge — issue #717)', handler: (req, res) => {
+      return serveFreshJson(req, res, {
+        tag: 'qa-sessions-summary',
+        inputs: [qaSessionsMod.qaSessionsPath()],
+        builder: () => qaSessionsMod.summarizeActiveSessionsForStatus(),
+      });
+    }},
     { method: 'GET', path: '/api/meetings-total', desc: 'Total meeting count (sidebar activity-dot signal — cheaper than fetching /api/meetings)', handler: (req, res) => {
       return serveFreshJson(req, res, {
         tag: 'meetings-total',

package/docs/managed-spawn.md

@@ -104,6 +104,52 @@ 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).
+
+The one case that needs quoting is a `command`-type healthcheck, because its `cmd` is a single shell-style string combining the executable and its args (unlike `spec.cmd`, which keeps `args` separate). If the binary isn't on PATH and lives under a space-containing install dir (`C:\Program Files (x86)\Android\Sdk\emulator\emulator.exe`, `C:\Users\<user with spaces>\AppData\Local\Android\Sdk\platform-tools\adb.exe`), quote the whole path — the validator extracts the full quoted token (not just up to the first internal space) before checking it against the allowlist:
+
+```jsonc
+"healthcheck": {
+  "type": "command",
+  "cmd": "\"C:/Program Files (x86)/Android/Sdk/platform-tools/adb.exe\" shell getprop sys.boot_completed",
+  "shell": true,
+  "expect_regex": "^1$",
+  "interval_s": 2,
+  "timeout_s": 120
+}
+```
+
+Single quotes (`'…'`) work the same way. No `powershell -Command "& '<path>' <args>"` wrapping is needed or sanctioned — wrap only if you genuinely need PowerShell-specific behavior (e.g. the call operator for a script, not just a native `.exe`).
+
 ## Lifecycle
 
 ```
@@ -219,7 +265,7 @@ All knobs live under `engine.managedSpawn` in `engine/shared.js` (`ENGINE_DEFAUL
 | `promptContextMaxBytes` | `2048` | Auto-injected `## Live managed processes` block cap. |
 | `requireGitWorkdir` | `true` | Reject specs whose `cwd` isn't inside a git worktree (root or any ancestor up to `gitWorktreeMaxParentDepth`). |
 | `gitWorktreeMaxParentDepth` | `6` | How many parent directories `shared.isValidGitWorktree` walks when probing for `.git`. Lets monorepo specs pin a per-package `cwd` (`<root>/packages/<pkg>/...`); set to `0` to disable the walk. |
-| `executableAllowlist` | `[node, bun, npm, …]` | Single global. Applies to `spec.cmd` AND `command` healthcheck `cmd`. |
+| `executableAllowlist` | `[node, bun, npm, python, docker, adb, emulator, gradle, mvn, pwsh, powershell, bash, sh, curl, wget, git, …]` | Single global. Applies to `spec.cmd` AND `command` healthcheck `cmd`, matched against `path.basename()` with `.exe`/`.cmd`/`.bat`/`.ps1`/`.sh` stripped — bare PATH names and full absolute paths both work. See [Non-PATH native launcher binaries](#non-path-native-launcher-binaries-eg-android-sdks-emulatorexe--adbexe) for quoting a `command` healthcheck's combined executable+args string. |
 | `envKeyDenyPatterns` | `[^AWS_, ^AZURE_, _SECRET, _TOKEN, _API_KEY, …]` | Regex source strings, matched case-insensitively. Keys matching ANY pattern are rejected unless exact-listed in `envKeyDenyOverrides`. Threat model: credential leakage, not env-key enumeration — plain project vars (`CONSTELLATION_SERVER`, `DATABASE_URL`, …) pass with no config. |
 | `envKeyDenyOverrides` | `[AWS_REGION, AWS_DEFAULT_REGION, AZURE_REGION, GCP_REGION, AWS_PROFILE]` | Exact-match exemptions for known-safe keys that would otherwise be caught by a broad prefix pattern. Case-sensitive. |
 

package/engine/lifecycle.js

@@ -6747,17 +6747,28 @@ function collapseAllDuplicatePrRecords(config) {
 // a coding WI (not one of the validation types itself). Skips if the coding WI
 // has no PR.
 //
+// Files exactly ONE validation WI per coding-WI completion (W-mrhybval0001).
+// `liveValidation.type` still governs CHECKOUT ROUTING — the set of work-item
+// types that run in-place on the live checkout (see resolveCheckoutMode's
+// membership check) — but auto-validation no longer fans that array out into
+// one validation WI per type. That earlier behavior (W-mr2m1ute000a9c01)
+// conflated "which types run live" with "how many validation tasks to file";
+// a multi-select routing config would silently spawn N validation WIs after
+// every coding completion. Validation is a single downstream step, so we
+// collapse to one WI.
+//
 // liveValidation.type may be a single string (legacy / back-compat) or an
-// array of strings (W-mr2m1ute000a9c01 — multi-select hybrid types). When an
-// array, ONE validation WI is dispatched per configured type (each validation
-// WI still carries a single canonical `type` field so downstream routing —
-// playbooks, agent resolution, resolveCheckoutMode's membership check — keeps
-// working per-type).
+// array of strings (multi-select hybrid types). We choose ONE validation type
+// for the single WI. It MUST be a member of lvTypes, otherwise resolveCheckoutMode
+// would route the validation WI to a worktree instead of the live checkout
+// (defeating hybrid validation). Preference order: the canonical `test` type
+// when configured, else the first configured live type. The completing item's
+// own type is excluded so a validation-type WI can't recursively validate
+// itself (anti-loop).
 //
-// Deduplicates per (codingWiId, validationType) pair: a non-terminal WI with
-// meta.liveValidationFor === codingWiId AND meta.liveValidationType === type
-// blocks a second dispatch of that specific type, so multiple configured
-// types don't collide or skip each other.
+// Deduplicates per codingWiId: any non-terminal WI with
+// meta.liveValidationFor === codingWiId blocks a second dispatch, so only one
+// validation task is ever in flight per coding completion.
 //
 // W-mr9u39az000db5c2 — guard against a self-referential recursive cascade.
 // When liveValidation.type overlaps with a coding WI's own type set (e.g.
@@ -6778,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;
 
@@ -6791,10 +6812,18 @@ function autoDispatchLiveValidationWi(meta, config) {
 
   const lvTypes = Array.isArray(lv.type) ? lv.type : [lv.type];
 
-  // Only auto-dispatch for coding WIs — skip types that ARE one of the
-  // configured validation types (avoid an infinite validate-the-validation loop).
-  const typesToDispatch = lvTypes.filter(t => t !== item.type);
-  if (typesToDispatch.length === 0) return;
+  // Candidate validation types = configured live types minus the completing
+  // item's own type (avoid an infinite validate-the-validation loop).
+  const candidates = lvTypes.filter(t => t && t !== item.type);
+  if (candidates.length === 0) return;
+
+  // Collapse to a SINGLE validation type: prefer the canonical `test` type when
+  // it is a configured live type, else the first configured live type. Either
+  // way the chosen type is a member of lvTypes, so the validation WI routes to
+  // the live checkout (not a worktree).
+  const validationType = candidates.includes(WORK_TYPE.TEST)
+    ? WORK_TYPE.TEST
+    : candidates[0];
 
   // Resolve PR reference: prefer the canonical stamped _pr field (set by
   // stampWiPrRef which runs earlier in runPostCompletionHooks), then fall
@@ -6817,51 +6846,48 @@ function autoDispatchLiveValidationWi(meta, config) {
     mutateWorkItems(wiPath, items => {
       if (!Array.isArray(items)) return items;
 
-      for (const validationType of typesToDispatch) {
-        // Dedup: skip if a non-terminal WI already tracks this (coding WI, type)
-        // pair. Falls back to the WI's own `type` field when meta.liveValidationType
-        // is absent (back-compat with validation WIs created before this field
-        // existed, e.g. single-type configs from before W-mr2m1ute000a9c01).
-        const existing = items.find(i =>
-          i &&
-          i.meta &&
-          i.meta.liveValidationFor === codingWiId &&
-          (i.meta.liveValidationType === validationType ||
-            (!i.meta.liveValidationType && i.type === validationType)) &&
-          !PLAN_TERMINAL_STATUSES.has(i.status)
-        );
-        if (existing) {
-          log('info', `liveValidation: dedup — non-terminal validation WI ${existing.id} (type=${validationType}) already exists for ${codingWiId}`);
-          continue;
-        }
+      // Dedup: only one validation WI in flight per coding WI. Any non-terminal
+      // WI already tracking this coding WI (meta.liveValidationFor) blocks a
+      // second dispatch, regardless of its validation type. (Back-compat: WIs
+      // created before meta.liveValidationType existed are matched too, since
+      // we key solely on liveValidationFor.)
+      const existing = items.find(i =>
+        i &&
+        i.meta &&
+        i.meta.liveValidationFor === codingWiId &&
+        !PLAN_TERMINAL_STATUSES.has(i.status)
+      );
+      if (existing) {
+        log('info', `liveValidation: dedup — non-terminal validation WI ${existing.id} already exists for ${codingWiId}`);
+        return items;
+      }
 
-        const proposedTitle = 'Validate: ' + (item.title || codingWiId);
-        // Defense-in-depth (belt-and-suspenders alongside the meta.liveValidationFor
-        // guard above): never create a doubly-nested "Validate: Validate: ..."
-        // title even if some future caller manages to invoke this function
-        // directly on an already-validation-tagged item.
-        if (/^Validate:\s*Validate:/.test(proposedTitle)) {
-          log('warn', `liveValidation: refusing to create nested "Validate: Validate:" WI for ${codingWiId} (type=${validationType})`);
-          continue;
-        }
+      const proposedTitle = 'Validate: ' + (item.title || codingWiId);
+      // Defense-in-depth (belt-and-suspenders alongside the meta.liveValidationFor
+      // guard above): never create a doubly-nested "Validate: Validate: ..."
+      // title even if some future caller manages to invoke this function
+      // directly on an already-validation-tagged item.
+      if (/^Validate:\s*Validate:/.test(proposedTitle)) {
+        log('warn', `liveValidation: refusing to create nested "Validate: Validate:" WI for ${codingWiId} (type=${validationType})`);
+        return items;
+      }
 
-        const validationWi = {
-          id: 'W-' + shared.uid(),
-          title: proposedTitle,
-          type: validationType,
-          status: WI_STATUS.PENDING,
-          depends_on: [codingWiId],
-          references: [prRef],
-          meta: { liveValidationFor: codingWiId, liveValidationType: validationType },
-          project: projectName,
-          priority: item.priority || 'medium',
-          created: ts(),
-          createdBy: 'lifecycle:live-validation-auto-dispatch',
-        };
+      const validationWi = {
+        id: 'W-' + shared.uid(),
+        title: proposedTitle,
+        type: validationType,
+        status: WI_STATUS.PENDING,
+        depends_on: [codingWiId],
+        references: [prRef],
+        meta: { liveValidationFor: codingWiId, liveValidationType: validationType },
+        project: projectName,
+        priority: item.priority || 'medium',
+        created: ts(),
+        createdBy: 'lifecycle:live-validation-auto-dispatch',
+      };
 
-        items.push(validationWi);
-        log('info', `liveValidation: auto-dispatched validation WI ${validationWi.id} (type=${validationType}) for coding WI ${codingWiId}`);
-      }
+      items.push(validationWi);
+      log('info', `liveValidation: auto-dispatched validation WI ${validationWi.id} (type=${validationType}) for coding WI ${codingWiId}`);
       return items;
     });
   } catch (err) {

package/engine/managed-spawn.js

@@ -142,11 +142,29 @@ function _resolveProjectForCwd(cwd, projects) {
 // string so it can be checked against the executable allowlist. Strips
 // surrounding quotes and any leading path. Returns '' when no candidate
 // found.
+//
+// W-mr9v7h2u0009ca67 (issue #711): native launcher binaries that don't sit
+// on PATH (e.g. the Android SDK's `emulator.exe` / `adb.exe`) are commonly
+// installed under a space-containing directory (`C:\Program Files
+// (x86)\Android\Sdk\...`, `C:\Users\<user with spaces>\AppData\Local\...`).
+// A `command`-type healthcheck naturally quotes such a path — but a naive
+// "split at first whitespace" tokenizer truncates the quoted path at its
+// first internal space, so the extracted token never matches the allowlist
+// and agents were forced into an undocumented `powershell -Command "&
+// '<path>' <args>"` wrapper just to pass validation. When `cmd` starts with
+// a quote character, walk to the matching closing quote instead of the
+// first whitespace so the full quoted path is treated as one token.
 function _firstExecutable(cmd) {
   if (typeof cmd !== 'string') return '';
   const trimmed = cmd.trim();
   if (trimmed.length === 0) return '';
-  const m = trimmed.match(/^["']?([^\s"']+)["']?/);
+  const quote = trimmed[0];
+  if (quote === '"' || quote === '\'') {
+    const closeIdx = trimmed.indexOf(quote, 1);
+    if (closeIdx > 0) return trimmed.slice(1, closeIdx);
+    // Unterminated quote — fall through to the unquoted split below.
+  }
+  const m = trimmed.match(/^([^\s]+)/);
   if (!m) return '';
   return m[1];
 }
@@ -602,7 +620,7 @@ function buildManagedSpawnHint(opts) {
     '',
     '- Specs per file: ≤ ' + maxSpecs,
     '- Name: kebab-case, ≤ 64 chars, unique within file',
-    '- Executable (`cmd` and any `command` healthcheck cmd): on the engine\'s allowlist (node, bun, npm, npx, python, docker, adb, gradle, mvn, pwsh, …)',
+    '- Executable (`cmd` and any `command` healthcheck cmd): on the engine\'s allowlist (node, bun, npm, npx, python, docker, adb, emulator, gradle, mvn, pwsh, …). Matching strips the `.exe`/`.cmd`/`.bat`/`.ps1`/`.sh` extension and ignores any leading directory, so a full absolute path to an allowlisted binary works — you do NOT need a `powershell -Command "& \'<path>\' <args>"` wrapper. For a `command`-type healthcheck, if the binary isn\'t on PATH and its path contains spaces, just quote the whole path (`"C:/Program Files (x86)/Android/Sdk/emulator/emulator.exe" -version`) — the validator extracts the full quoted token, not just up to the first space.',
     '- Env keys: any well-formed POSIX identifier (`/^[A-Za-z_][A-Za-z0-9_]*$/`) is accepted EXCEPT keys matching credential-shaped deny patterns (`*_SECRET`, `*_TOKEN`, `*_API_KEY`, `*_PASSWORD`, `*_PRIVATE_KEY`, `*_CREDENTIALS`, `*_AUTH`, `*_PAT`, `AWS_*`, `AZURE_*`, `GCP_*`, `GH_TOKEN`, `GITHUB_TOKEN`, `OPENAI_*`, `ANTHROPIC_*`, `COPILOT_*`, `DOCKER_AUTH*`, `NPM_TOKEN`). Region/profile names (`AWS_REGION`, `AWS_PROFILE`, …) are exempt. If your service genuinely needs a credential-looking var, rename it (e.g. `DATABASE_URL` not `DB_API_KEY`) or stash the value in `attrs` and have the child read it from there. **The engine forwards env values verbatim — the deny shape is a tripwire, not a scrubber. Do not put real credentials in env even if the key passes.** Projects may tighten by adding patterns to `config.projects[N].managedSpawnExtraDenyPatterns`; projects cannot loosen.',
     '- Ports: 1024–65535, ≤ 20 per spec',
     '- TTL: ≤ ' + maxTtl + ' minutes (hard cap), defaults to ' + defaultTtl + ' if omitted',
@@ -676,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:',
@@ -711,9 +768,9 @@ function buildManagedSpawnHint(opts) {
 //      ctx)                          close-handler call site spawns each
 //                                    then persists them together).
 //   5. removeManagedSpec(name)     → locked unlink of the entry; best-effort
-//                                    process.kill of the recorded PID
-//                                    OUTSIDE the lock callback. No-op when
-//                                    the entry is missing.
+//                                    full-process-tree kill (shared.killImmediate)
+//                                    of the recorded PID OUTSIDE the lock
+//                                    callback. No-op when the entry is missing.
 //   6. listManagedSpecs({project}) → reads the state file, optionally
 //                                    filters by owner_project. Used later
 //                                    by item 4 (dashboard) + item 6
@@ -897,8 +954,14 @@ function removeManagedSpec(name) {
   }, { defaultValue: _initialStateShape() });
   // Kill OUTSIDE the lock — never run process ops inside a lock callback
   // (copilot-instructions.md "Keep lock callbacks synchronous and fast").
+  // Use killImmediate (full process-tree kill: `taskkill /PID <pid> /F /T` on
+  // Windows, recursive pgrep-based descendant walk on Unix) rather than
+  // killByPidImmediate (single-PID only). Managed specs are frequently
+  // launcher-style processes (e.g. Android emulator.exe spawning a detached
+  // qemu-system-x86_64 child) whose descendants survive a single-PID kill and
+  // leak indefinitely (opg-microsoft/minions#710).
   if (killPid != null) {
-    try { shared.killByPidImmediate(killPid); }
+    try { shared.killImmediate({ pid: killPid }); }
     catch (e) { log('warn', 'managed-spawn removeManagedSpec: kill ' + killPid + ' failed: ' + e.message); }
   }
 }
@@ -1246,8 +1309,11 @@ function restartManagedSpec(name) {
     healthcheck: existing.healthcheck || null,
   };
   // Kill the old PID before respawn (best-effort; outside of any lock).
+  // Full process-tree kill (see removeManagedSpec above) — a single-PID kill
+  // here would leave launcher descendants (e.g. qemu-system-x86_64 under an
+  // Android emulator.exe) running after "restart" respawns a fresh launcher.
   if (Number.isInteger(existing.pid) && existing.pid > 0) {
-    try { shared.killByPidImmediate(existing.pid); }
+    try { shared.killImmediate({ pid: existing.pid }); }
     catch (e) { log('warn', 'restartManagedSpec: kill of old PID ' + existing.pid + ' failed: ' + e.message); }
   }
   const ctx = {

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
@@ -1305,6 +1343,29 @@ function summarizeSessionsForStatus() {
   return { total: sessions.length, sig };
 }
 
+/**
+ * Cheap summary of non-terminal ("active") sessions for the QA nav sidebar
+ * badge (issue opg-microsoft/minions#717 — QA nav has no visibility signal).
+ * Mirrors summarizeSessionsForStatus but excludes TERMINAL_STATES so the
+ * count matches what a user cares about: sessions still in flight
+ * (pending/spawning/drafting/awaiting-approval/executing), not the full
+ * history of done/failed/killed records.
+ *
+ * @returns {{ active: number, sig: string }}
+ */
+function summarizeActiveSessionsForStatus() {
+  const sessions = _readSessions();
+  if (!Array.isArray(sessions) || sessions.length === 0) return { active: 0, sig: '' };
+  let active = 0;
+  let sig = '';
+  for (const s of sessions) {
+    if (!s || TERMINAL_STATES.has(s.state)) continue;
+    active++;
+    sig += (s.id || '') + ':' + (s.state || '') + ',';
+  }
+  return { active, sig };
+}
+
 module.exports = {
   // Constants
   QA_SESSION_STATE,
@@ -1356,6 +1417,7 @@ module.exports = {
   dismissSession,
   // Status
   summarizeSessionsForStatus,
+  summarizeActiveSessionsForStatus,
   // Internals (exposed for tests)
   _isSafeSessionId,
 };

package/engine/shared.js

@@ -3058,9 +3058,12 @@ function validateLiveValidation(value, opts) {
   } else {
     throw _httpError(400, typeErrorMsg);
   }
-  // autoDispatch (optional): when true, lifecycle auto-creates a validation WI
-  // per configured `type` after each coding WI completes with a PR
-  // (engine/lifecycle.js autoDispatchLiveValidationWi). Coerce to a strict
+  // autoDispatch (optional): when true, lifecycle auto-creates a SINGLE
+  // validation WI after each coding WI completes with a PR
+  // (engine/lifecycle.js autoDispatchLiveValidationWi). Even when `type` is a
+  // multi-entry array (which drives checkout ROUTING — the types that run live),
+  // exactly one validation WI is filed, of the canonical `test` type when
+  // configured else the first configured live type. Coerce to a strict
   // boolean; absent leaves it off so the operator opts in explicitly.
   if (Object.prototype.hasOwnProperty.call(value, 'autoDispatch')) {
     out.autoDispatch = !!value.autoDispatch;
@@ -8538,12 +8541,20 @@ function mutateWorkItems(filePath, mutator) {
   if (insideMinionsDir) {
     const store = require('./work-items-store');
     const scope = store.scopeForFilePath(filePath);
+    // W-mr9vcxvy000cdb4e — the JSON mirror is now written INSIDE
+    // applyWorkItemsMutation's SQL transaction (before commit), not here
+    // after the fact. Mirroring post-commit left a cross-process window
+    // where a sibling process (dashboard vs. engine — separate Node
+    // processes, each with its own in-memory mirror-hash cache) could
+    // observe the new SQL row before the JSON file caught up and
+    // destructively rehydrate the scope from that stale file, dropping
+    // the just-created row (the "phantom work item" dispatch race). See
+    // work-items-store.js#applyWorkItemsMutation for the full rationale.
     const { wrote, result } = store.applyWorkItemsMutation(scope, (items) => {
       if (!Array.isArray(items)) items = [];
       return mutator(items) || items;
-    });
+    }, { mirrorPath: filePath });
     if (wrote) {
-      try { store._mirrorJsonFromSql(scope, filePath); } catch { /* mirror best-effort */ }
       try { require('./db-events').emitStateEvent('work_items'); } catch { /* optional */ }
       try { require('./queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
     }
@@ -8810,6 +8821,14 @@ function prFixEvidenceFingerprint(pr, cause = PR_FIX_CAUSE.UNKNOWN) {
   if (cause === PR_FIX_CAUSE.HUMAN_FEEDBACK) {
     evidence.lastProcessedCommentDate = feedback.lastProcessedCommentDate || '';
     evidence.feedbackContent = feedback.feedbackContent || '';
+    // #714 — same rationale as BUILD_FAILURE / MERGE_CONFLICT / REVIEW_FEEDBACK:
+    // without a head-SHA salt, a genuine new push that doesn't otherwise change
+    // lastProcessedCommentDate/feedbackContent (e.g. comment-thread bookkeeping
+    // races/dedup) can leave the human-feedback no-op pause stuck even though
+    // real new work landed. Adding head SHA + lastPushedAt gives HUMAN_FEEDBACK
+    // the same natural-unsticking property the other three causes already have.
+    evidence.headRefOid = _prHeadSha(pr);
+    evidence.lastPushedAt = pr?.lastPushedAt || '';
   } else if (cause === PR_FIX_CAUSE.BUILD_FAILURE) {
     evidence.buildStatus = pr?.buildStatus || '';
     evidence.buildFailReason = pr?.buildFailReason || '';

package/engine/work-items-store.js

@@ -320,7 +320,7 @@ function _hydrateScopeFromJson(db, scope) {
   }
 }
 
-function applyWorkItemsMutation(scope, mutator) {
+function applyWorkItemsMutation(scope, mutator, options = {}) {
   const { getDb, withTransaction } = require('./db');
   const db = getDb();
 
@@ -344,6 +344,27 @@ function applyWorkItemsMutation(scope, mutator) {
       : (Array.isArray(next) ? next : before);
     const diff = _computeWorkItemsDiff(scope, beforeSnapshot, after);
     const wrote = _applyWorkItemsDiff(db, diff);
+    // W-mr9vcxvy000cdb4e — phantom-WI race fix: mirror the JSON sidecar
+    // INSIDE this same SQL write transaction, BEFORE it commits, instead
+    // of after (as the caller used to do post-return). SQLite only allows
+    // one writer transaction at a time (BEGIN IMMEDIATE holds an
+    // exclusive writer lock), so mirroring here guarantees the on-disk
+    // JSON file is fully up to date by the time this commit becomes
+    // visible to any other reader/writer — dashboard and engine are
+    // SEPARATE Node processes, each with its own in-memory
+    // `_lastMirrorHashByScope` cache, so without this ordering a sibling
+    // process could observe a freshly committed SQL row before the mirror
+    // file caught up, decide (via its own stale hash) that the JSON file
+    // was "externally edited", and call `_hydrateScopeFromJson` — which
+    // DELETEs + reinserts the whole scope from that stale file, silently
+    // dropping the row a POST /api/work-items caller had just been told
+    // was created successfully (visible to the engine's dispatch loop
+    // one moment, gone from work_items the next). Mirroring pre-commit
+    // means "SQL says the row exists" and "JSON mirror has the row" can
+    // never observably disagree across processes.
+    if (wrote) {
+      try { _mirrorJsonFromSql(scope, options.mirrorPath); } catch { /* best-effort — mirror failure must not block the SQL write */ }
+    }
     return { wrote, result: after };
   });
 }

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.2343",
+  "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