@yemi33/minions 0.1.2344 → 0.1.2346

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/shared.js

@@ -3193,6 +3193,24 @@ const ENGINE_DEFAULTS = {
     'build-reports': 14,
     'reviews': 30,
   },
+  // W-mr973knu — structural consolidation for the KB sweep (PRIMARY balloon
+  // fix; TTL above is the secondary safety net). The sweep groups boilerplate
+  // transient-category notes by (category, agent, kind, time-bucket) — where
+  // kind is the agent-failure `failureClass`, or a no-op / merge-conflict fix
+  // report — and rolls any group of at least `minGroupSize` notes into a single
+  // recoverable digest (`_digest-<agent>-<kind>-<period>.md`), archiving the
+  // originals to knowledge/_swept/. Unlike TTL expiry this collapses RECENT
+  // duplication too, so the KB shrinks continuously instead of only aging out.
+  // Only `categories` listed here are consolidated; durable categories
+  // (architecture, conventions) and per-agent memory are never touched.
+  // config.engine.kbConsolidation is merged over these defaults; set
+  // `enabled: false` or `categories: []` to disable.
+  kbConsolidation: {
+    enabled: true,
+    categories: ['project-notes', 'build-reports', 'reviews'],
+    minGroupSize: 5, // collapse a group only once it reaches this many near-duplicate notes
+    periodDays: 7,   // one digest per (agent, kind) per this many days
+  },
   // W-mqtvnnj1000357fa — fleet-wide fallback for live-checkout auto-stash. When
   // true, a dirty live-checkout tree is `git stash push --include-untracked`'d
   // before dispatch instead of failing with FAILURE_CLASS.LIVE_CHECKOUT_DIRTY,
@@ -4698,12 +4716,19 @@ function mutateWatches(mutator) {
 function mutateMetrics(mutator) {
   const metricsPath = path.join(MINIONS_DIR, 'engine', 'metrics.json');
   const store = require('./metrics-store');
+  // W-mradg74d000rfd45 — the JSON mirror is now written INSIDE
+  // applyMetricsMutation'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 newly committed SQL rows before the JSON file caught up
+  // and read stale/missing metrics off the sidecar. See
+  // metrics-store.js#applyMetricsMutation for the full rationale.
   const { wrote, result } = store.applyMetricsMutation((m) => {
     if (!m || typeof m !== 'object') m = {};
     return mutator(m) || m;
-  });
+  }, { mirrorPath: metricsPath });
   if (wrote) {
-    try { store._mirrorJsonFromSql(metricsPath); } catch { /* mirror best-effort */ }
     try { require('./db-events').emitStateEvent('metrics'); } catch { /* optional */ }
   }
   return result;
@@ -4877,6 +4902,7 @@ const FAILURE_CLASS = {
   LIVE_CHECKOUT_MID_OPERATION: 'live-checkout-mid-operation', // P-a7f3c1d9 (live-checkout dispatch mode): spawnAgent could not switch/create the target branch in project.localPath because the operator tree is mid-operation — an in-progress merge/rebase/cherry-pick/bisect or a detached HEAD. Distinct from LIVE_CHECKOUT_DIRTY (uncommitted changes): here the tree may be clean but the branch op cannot proceed. Engine refuses to spawn (it never runs `git reset`/`git clean`/`git rebase --abort` against the operator tree). Non-retryable — operator must finish or abort the in-progress operation, or checkout a branch, before re-dispatch.
   LIVE_CHECKOUT_BLOB_FETCH: 'live-checkout-blob-fetch', // PL-live-checkout-reliability-hardening (live-checkout dispatch mode): `git checkout <existing-branch>` in project.localPath failed because the tree could not be materialized — on a Scalar/GVFS-managed ADO partial (blobless) clone, switching onto a branch whose tree differs from HEAD hydrates the changed paths' blobs through the GVFS cache server (`*.gvfscache.dev.azure.com`), a different endpoint than the main git remote that receives NO auth in the headless engine shell, so the fetch fails DETERMINISTICALLY. Distinct from LIVE_CHECKOUT_FAILED (transient) because retrying reproduces it identically — surfaced once as an operator-actionable refusal instead of retry-storming to the cap. Non-retryable — the operator hydrates the branch once with their own credentials (`git checkout <branch>` interactively, or `scalar prefetch` / `git -C <repo> fetch`), then re-dispatches. The engine NEVER forces, resets, cleans, or stashes the operator tree, and best-effort switches HEAD back to the original ref so the tree is not stranded half-populated.
   LIVE_CHECKOUT_WORKTREE_CONFLICT: 'live-checkout-worktree-conflict', // W-mr28h2j2000y0de1 (live-checkout dispatch mode): `git checkout <existing-branch>` in project.localPath failed because that exact branch is ALSO checked out in a SECOND worktree elsewhere (a leftover from a prior isolated-worktree dispatch, a manually-created worktree, or a stale worktree left by a checkoutMode change). git refuses deterministically with `fatal: '<branch>' is already used by worktree at '<path>'`. Distinct from LIVE_CHECKOUT_FAILED (transient) because this is a STRUCTURAL conflict — it does NOT clear on retry, ever, until a human or the engine removes/reassigns the other worktree; retrying just reproduces it identically and burns maxRetries. Non-retryable — the operator either `git worktree remove <path>` (freeing the branch) if that worktree is stale, or finishes/commits/pushes from it directly if it holds real WIP. The engine NEVER forces, resets, cleans, or stashes the operator tree, and best-effort switches HEAD back to the original ref so the tree is not stranded.
+  LIVE_CHECKOUT_STALE_BASE: 'live-checkout-stale-base', // W-mr98op8w000ma4ad (live-checkout dispatch mode, STALE-BASE GUARD): spawnAgent was about to fork a NEW branch off the operator's current HEAD while HEAD sits on the project base ref (mainRef), but the LOCAL mainRef tip has DIVERGED from origin/<mainRef> with unpushed commit(s) (`git rev-list --count origin/<mainRef>..<mainRef>` > 0). Forking would silently inherit that COMMITTED contamination into the new branch and its PR — the exact scope-contamination class first seen on ADO PR 5411214 and recurring on AB#12016662 / ADO PR 5419146. Survives the dirty check (contamination is committed, not uncommitted) and cannot be caught by a headBranch !== mainRef check (headBranch IS mainRef here). Detected WITHOUT a fetch (issue #226) via the existing origin/<mainRef> remote-tracking ref. Distinct from LIVE_CHECKOUT_FAILED (transient) because the contaminated local base does NOT change on retry — it reproduces identically until a human reconciles the local base branch. Non-retryable — the engine NEVER resets/cleans the operator's local mainRef; the operator must reconcile it (push/reset/rebase their own way), then re-dispatch. The guard SKIPS (proceeds normally) when HEAD is not on mainRef, when no local origin/<mainRef> ref exists (local-only/no-remote repo), or when the divergence count cannot be computed.
   LIVE_CHECKOUT_WRONG_BASE: 'live-checkout-wrong-base', // W-mr3lunnq000o9f41 (live-checkout dispatch mode): a NEW-branch fork was requested but the operator's checkout HEAD is on an unrelated topic/feature branch, NOT the project base (mainRef), and prepareLiveCheckout could not switch to a LOCAL base ref (no `refs/heads/<mainRef>`, or the local checkout itself failed). Forking off the stale HEAD would silently bake every commit already on that branch into the new branch AND its PR — committed-history scope contamination that survives the dirty/mid-operation preflights (the ADO PR 5411214 incident: ~22 unrelated OCM files, author-disavowed). The engine never fetches origin/<mainRef> in live mode (issue #226) so it cannot self-heal a missing local base. Non-retryable — the operator must `git checkout <mainRef>` in the operator checkout before re-dispatch. Does NOT fire for PR-targeted fixes or shared-branch continuations (those pass allowNonMainBase, intentionally continuing a non-main branch), nor when HEAD is already on mainRef, nor when a local mainRef ref exists (the guard switches to it and forks cleanly). OPT-IN AUTO-RECOVERY (`liveCheckoutAutoBaseRepair`, per-project > fleet-wide, default OFF): when enabled AND a `refs/remotes/origin/<mainRef>` remote-tracking ref exists, the guard materializes a local `<mainRef>` branch from it (a LOCAL ref op — still no `git fetch`, issue #226 preserved; origin/<mainRef> IS the base so no contamination) and forks cleanly instead of failing — eliminating the manual `git checkout <mainRef>` step. Still fails closed when neither a local base nor an origin-tracking base ref exists, or when the base checkout itself fails/hangs.
   INVALID_WORKDIR: 'invalid-workdir',     // P-714ef144: dispatch carried a meta.workdir override that failed validation — non-string, absolute path, drive-letter prefix, null byte, ".." segment, or post-resolve containment escape against project.localPath / worktree root. Engine refuses to spawn (the subpath would either be unreachable on disk or point outside the operator's allowed surface). Non-retryable — operator must fix the WI's meta.workdir before re-dispatch. Inbox alert lists the offending value + the resolved-vs-base mismatch.
   MODEL_UNAVAILABLE: 'model-unavailable', // W-mpg6isvy000xca4d: requested model returned overloaded_error / 503 / service_unavailable. Retriable — engine swaps in the runtime-appropriate fallback model on next spawn (Claude leans on --fallback-model already plumbed; Copilot overrides --model with engine.copilotFallbackModel).

package/engine.js

@@ -2934,6 +2934,83 @@ async function spawnAgent(dispatchItem, config) {
       cleanupTempAgent(agentId);
       return null;
     }
+    // W-mr98op8w000ma4ad: STALE-BASE GUARD refusal. prepareLiveCheckout was about
+    // to fork a NEW branch off the operator's current HEAD while HEAD sits on the
+    // project base ref (mainRef), but the LOCAL mainRef tip has diverged from
+    // origin/<mainRef> with unpushed commit(s). Forking would silently bake that
+    // committed contamination into the new branch and its PR (the scope-leak class
+    // first seen on ADO PR 5411214, recurring on AB#12016662 / ADO PR 5419146).
+    // Deterministic — a contaminated local base reproduces identically on retry —
+    // so it gets its own non-retryable FAILURE_CLASS instead of LIVE_CHECKOUT_FAILED's
+    // bounded retry-storm. The engine NEVER resets/cleans the operator's local
+    // mainRef; the operator must reconcile it themselves, then re-dispatch.
+    if (_liveResult && _liveResult.ok === false && _liveResult.reason === 'stale-main') {
+      const _staleMainRef = typeof _liveResult.mainRef === 'string' && _liveResult.mainRef ? _liveResult.mainRef : 'main';
+      const _staleAhead = Number.isFinite(_liveResult.ahead) ? _liveResult.ahead : 0;
+      const _localSha = typeof _liveResult.localMainSha === 'string' && _liveResult.localMainSha ? _liveResult.localMainSha : '(unknown)';
+      const _originSha = typeof _liveResult.originMainSha === 'string' && _liveResult.originMainSha ? _liveResult.originMainSha : '(unknown)';
+      const _alertBody = [
+        '# Live-checkout blocked: local base branch has diverged (stale/contaminated base)',
+        '',
+        `**Project:** ${project.name || '(unknown)'}`,
+        `**Local path:** ${cwd}`,
+        `**New branch (refused):** ${branchName}`,
+        `**Base ref:** ${_staleMainRef}`,
+        `**Local ${_staleMainRef}:** ${_localSha}`,
+        `**origin/${_staleMainRef}:** ${_originSha}`,
+        `**Unpushed commits on local ${_staleMainRef}:** ${_staleAhead}`,
+        `**Work item:** ${_wiIdForAlert}`,
+        `**Dispatch:** ${id}`,
+        '',
+        `The engine refused to fork \`${branchName}\` off local \`${_staleMainRef}\` because your local \`${_staleMainRef}\` is **${_staleAhead} commit(s) ahead of \`origin/${_staleMainRef}\`**. Those commits were never pushed — forking a new branch (and its PR) off this base would silently inherit them, contaminating an otherwise-clean change with unrelated commits. The working tree was clean (no uncommitted changes), so the dirty check could not catch this: the contamination is COMMITTED. Your tree was left untouched — the engine never resets, cleans, or rebases your \`${_staleMainRef}\`.`,
+        '',
+        '## Recovery',
+        '',
+        `Reconcile your local \`${_staleMainRef}\` so it no longer carries unpushed commits, then re-dispatch. Pick ONE, depending on whether those commits are real work:`,
+        '',
+        `1. **If the extra commits are real work you want to keep** — move them onto their own branch, then reset \`${_staleMainRef}\` to the remote:`,
+        '',
+        '```',
+        `git -C "${cwd}" branch salvage-${_staleMainRef} ${_staleMainRef}`,
+        `git -C "${cwd}" checkout ${_staleMainRef}`,
+        `git -C "${cwd}" reset --hard origin/${_staleMainRef}`,
+        '```',
+        '',
+        `2. **If the extra commits are leftover junk** (e.g. a prior dispatch's abandoned WIP) — discard them by resetting \`${_staleMainRef}\` to the remote (this DISCARDS those commits):`,
+        '',
+        '```',
+        `git -C "${cwd}" checkout ${_staleMainRef}`,
+        `git -C "${cwd}" reset --hard origin/${_staleMainRef}`,
+        '```',
+        '',
+        `The salvage branch in option 1 keeps the commits recoverable; both leave \`${_staleMainRef}\` matching \`origin/${_staleMainRef}\` so the next dispatch forks off a clean base.`,
+      ].join('\n');
+      try { writeInboxAlert(`live-checkout-stale-base-${_wiIdForAlert}`, _alertBody); }
+      catch (e) { log('warn', `live-checkout: writeInboxAlert failed: ${e.message}`); }
+      try {
+        const _wiPath = resolveWorkItemPath(dispatchItem.meta);
+        if (_wiPath && dispatchItem.meta?.item?.id) {
+          mutateJsonFileLocked(_wiPath, (data) => {
+            if (!Array.isArray(data)) return data;
+            const wi = data.find(i => i && i.id === dispatchItem.meta.item.id);
+            if (wi) wi._pendingReason = 'live_checkout_stale_base';
+            return data;
+          });
+        }
+      } catch (e) { log('warn', `live-checkout: failed to stamp _pendingReason: ${e.message}`); }
+      const _shortMsg = `live-checkout blocked: local ${_staleMainRef} is ${_staleAhead} commit(s) ahead of origin/${_staleMainRef} (would contaminate ${branchName})`;
+      log('error', `spawnAgent: ${_shortMsg}`);
+      _cleanupPromptFiles();
+      completeDispatch(
+        id,
+        DISPATCH_RESULT.ERROR,
+        _shortMsg.slice(0, 800),
+        `Live-checkout STALE-BASE GUARD: forking ${branchName} off local ${_staleMainRef} would inherit ${_staleAhead} unpushed commit(s) not on origin/${_staleMainRef}. Deterministic — operator must reconcile the local base branch (the engine never resets it) before re-dispatch. Retrying is provably useless.`,
+        { failureClass: FAILURE_CLASS.LIVE_CHECKOUT_STALE_BASE, agentRetryable: false },
+      );
+      cleanupTempAgent(agentId);
+      return null;
+    }
     log('info', `live-checkout: ${_liveResult.created ? 'created' : 'switched to'} branch ${branchName} in ${cwd} (in-place; no worktree)`);
     // PL-live-checkout-reliability-hardening: a clean spawn clears the two-strike
     // dirty counter so a project that was transiently dirty once isn't treated as
@@ -7115,19 +7192,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 +7228,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 +8556,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.2346",
   "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