@yemi33/minions 0.1.2143 → 0.1.2145

package/engine/lifecycle.js

@@ -987,6 +987,258 @@ function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
   return added;
 }
 
+// ─── Post-hoc PR enrollment (W-mq5uzmc6001d708f) ─────────────────────────────
+//
+// When a work item has `_pr` set (e.g. via reconcileItemsWithPrs stamping from
+// pr-links, or via an old commit referencing the PR URL) but the `pull_requests`
+// SQL table has no matching row, the dashboard's PRD-progress synthesis falls
+// back to PR_STATUS.ACTIVE forever — the PR rings blue ○ even after it's
+// merged. This happens to PRs that were created AND merged inside one open-PR
+// poller gap (the engine never observed them as `open`, so it never enrolled
+// them).
+//
+// `enrollPrFromCanonicalId` is the write-side fix: given a canonical PR id and
+// the owning project, fetch live state from GitHub (or ADO, best-effort) and
+// insert a `_contextOnly: true` row into the project's `pull-requests.json`.
+// Idempotent — no-op if a record already exists. Always marks the record as
+// context-only so the engine doesn't try to re-dispatch fix/review loops on
+// an already-merged PR (matches the #1772 enrollment-flag semantics).
+
+let _enrollmentGhRunner = null;
+function _setEnrollmentGhRunnerForTest(fn) {
+  _enrollmentGhRunner = (typeof fn === 'function') ? fn : null;
+}
+
+async function _fetchGitHubPrStateForEnrollment(slug, prNumber) {
+  if (_enrollmentGhRunner) {
+    try {
+      return await _enrollmentGhRunner(slug, prNumber);
+    } catch (err) {
+      log('warn', `enrollPrFromCanonicalId: test runner failed for ${slug}#${prNumber}: ${err.message}`);
+      return null;
+    }
+  }
+  let token = null;
+  try {
+    const ghToken = require('./gh-token');
+    if (typeof ghToken.resolveTokenForSlug === 'function') {
+      token = ghToken.resolveTokenForSlug(slug);
+    }
+  } catch { /* gh-token optional in some test contexts */ }
+  const env = token ? { ...process.env, GH_TOKEN: token } : undefined;
+  try {
+    const validatedSlug = shared.validateGhSlug(slug);
+    const args = ['pr', 'view', String(prNumber),
+      '--repo', validatedSlug,
+      '--json', 'state,mergedAt,closedAt,title,headRefName,baseRefName,url,number,isDraft'];
+    const stdout = await shared.shellSafeGh(args, { timeout: 15000, env });
+    if (!stdout || !stdout.trim()) return null;
+    return JSON.parse(stdout);
+  } catch (err) {
+    log('warn', `enrollPrFromCanonicalId: gh pr view ${slug}#${prNumber} failed: ${err.message}`);
+    return null;
+  }
+}
+
+function _liveGitHubStateToPrStatus(liveState) {
+  if (!liveState) return PR_STATUS.ACTIVE;
+  const state = String(liveState.state || '').toUpperCase();
+  if (state === 'MERGED' || liveState.mergedAt) return PR_STATUS.MERGED;
+  if (state === 'CLOSED') return PR_STATUS.ABANDONED;
+  return PR_STATUS.ACTIVE;
+}
+
+function _existingPrRecordForCanonicalId(canonicalPrId) {
+  try {
+    const store = require('./pull-requests-store');
+    if (typeof store.readAllPullRequests !== 'function') return null;
+    const all = store.readAllPullRequests() || [];
+    return all.find(pr => pr && pr.id === canonicalPrId) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Enroll a PR (identified by canonical id, e.g. `github:owner/repo#123`) into
+ * the engine's pull-requests tracker if no record exists yet. Used to back-fill
+ * orphan `wi._pr` pointers from the legacy / pre-tracker era so the dashboard
+ * can render the real merged/abandoned status instead of a perpetual blue ○.
+ *
+ * Idempotent: returns `{ enrolled: false, reason: 'already_tracked' }` if a row
+ * already exists. Marks new records with `_contextOnly: true` so the engine
+ * doesn't try to manage them (no re-dispatch of fix/review loops). Live state
+ * is fetched via `gh pr view` for GitHub; ADO enrollment is best-effort with
+ * a conservative ACTIVE default.
+ *
+ * @param {string} canonicalPrId - canonical id like `github:owner/repo#42`
+ * @param {object|null} project - resolved project config; null routes to central
+ * @param {object} [opts]
+ * @param {string} [opts.itemId] - work-item id to link to the enrolled record
+ * @returns {Promise<{enrolled: boolean, status?: string, reason?: string, record?: object}>}
+ */
+async function enrollPrFromCanonicalId(canonicalPrId, project, opts = {}) {
+  if (!canonicalPrId || typeof canonicalPrId !== 'string') {
+    return { enrolled: false, reason: 'no_id' };
+  }
+  // Allow callers to pass a bare display id (e.g. `PR-3082`) plus project; the
+  // upsert helper will re-derive a canonical id from project + display id.
+  let parsed = shared.parseCanonicalPrId(canonicalPrId);
+  let scope;
+  let prNumber;
+  if (parsed) {
+    scope = parsed.scope;
+    prNumber = parsed.prNumber;
+  } else {
+    prNumber = shared.getPrNumber(canonicalPrId);
+    if (prNumber == null) return { enrolled: false, reason: 'unparseable_id' };
+    scope = shared.getProjectPrScope(project);
+    if (!scope) return { enrolled: false, reason: 'no_scope' };
+  }
+  // Normalize canonical id so an inbound `pr-3082` + project resolves to
+  // `github:owner/repo#3082` for the existence check below.
+  const normalizedCanonicalId = `${scope}#${prNumber}`;
+
+  const existing = _existingPrRecordForCanonicalId(normalizedCanonicalId);
+  if (existing) {
+    // Even when already tracked, opportunistically link the work item so
+    // pr-links stays consistent (#779 pattern).
+    if (opts.itemId && Array.isArray(existing.prdItems) && !existing.prdItems.includes(opts.itemId)) {
+      try {
+        const targetPath = project ? shared.projectPrPath(project) : path.join(MINIONS_DIR, 'pull-requests.json');
+        shared.upsertPullRequestRecord(targetPath, {
+          id: normalizedCanonicalId,
+          prNumber,
+          url: existing.url || '',
+          title: existing.title || '',
+          agent: existing.agent || 'engine',
+          status: existing.status || PR_STATUS.ACTIVE,
+        }, { project, itemId: opts.itemId });
+      } catch { /* best-effort link */ }
+    }
+    return { enrolled: false, reason: 'already_tracked', status: existing.status, record: existing };
+  }
+
+  let liveState = null;
+  let url = '';
+  let title = '';
+  let branch = '';
+  let baseBranch = '';
+  let status = PR_STATUS.ACTIVE;
+  let isDraft = false;
+
+  if (scope.startsWith('github:')) {
+    const slug = scope.slice('github:'.length);
+    liveState = await _fetchGitHubPrStateForEnrollment(slug, prNumber);
+    if (liveState) {
+      url = liveState.url || '';
+      title = String(liveState.title || '').slice(0, 200);
+      branch = liveState.headRefName || '';
+      baseBranch = liveState.baseRefName || '';
+      isDraft = !!liveState.isDraft;
+      status = _liveGitHubStateToPrStatus(liveState);
+    }
+    if (!url) {
+      url = `https://github.com/${slug}/pull/${prNumber}`;
+    }
+  } else if (scope.startsWith('ado:')) {
+    // ADO best-effort: fetchAdoPrMetadata returns title/branch but not status.
+    // Record the canonical id so the next ADO poll cycle can refresh status.
+    try {
+      const adoParts = scope.slice('ado:'.length).split('/');
+      if (adoParts.length === 3) {
+        const ado = require('./ado');
+        if (typeof ado.fetchAdoPrMetadata === 'function') {
+          const meta = await ado.fetchAdoPrMetadata(prNumber, adoParts[0], adoParts[1], adoParts[2]);
+          if (meta) {
+            title = String(meta.title || '').slice(0, 200);
+            branch = meta.branch || '';
+          }
+        }
+      }
+    } catch (err) {
+      log('warn', `enrollPrFromCanonicalId: ADO metadata fetch for ${normalizedCanonicalId} failed: ${err.message}`);
+    }
+    if (!url && project && project.prUrlBase) url = String(project.prUrlBase) + prNumber;
+  } else {
+    return { enrolled: false, reason: 'unsupported_scope' };
+  }
+
+  const prPath = project ? shared.projectPrPath(project) : path.join(MINIONS_DIR, 'pull-requests.json');
+  if (!prPath) return { enrolled: false, reason: 'no_pr_path' };
+
+  const entry = {
+    id: normalizedCanonicalId,
+    prNumber,
+    title: title || `PR #${prNumber}`,
+    agent: 'engine',
+    branch,
+    baseBranch,
+    reviewStatus: REVIEW_STATUS.PENDING,
+    status,
+    isDraft,
+    url,
+    prdItems: opts.itemId ? [opts.itemId] : [],
+    _attachedAt: ts(),
+    _contextOnly: true,
+    _enrolledBy: 'enrollPrFromCanonicalId',
+  };
+  if (liveState && liveState.mergedAt) entry.mergedAt = liveState.mergedAt;
+  if (liveState && liveState.closedAt && !liveState.mergedAt) entry.closedAt = liveState.closedAt;
+
+  try {
+    const result = shared.upsertPullRequestRecord(prPath, entry, {
+      project,
+      itemId: opts.itemId || null,
+    });
+    if (result.created) {
+      log('info', `enrollPrFromCanonicalId: enrolled ${normalizedCanonicalId} (status=${status}) into ${project?.name || 'central'}/pull-requests.json`);
+    }
+    return {
+      enrolled: !!(result.created || result.linked),
+      status,
+      reason: result.created ? 'created' : (result.linked ? 'linked' : 'noop'),
+      record: result.record,
+    };
+  } catch (err) {
+    log('warn', `enrollPrFromCanonicalId: upsert failed for ${normalizedCanonicalId}: ${err.message}`);
+    return { enrolled: false, reason: 'upsert_failed', error: err.message };
+  }
+}
+
+// Internal helper: after `syncPrsFromOutput` finishes the regex-evidence pass,
+// some work items still have `meta.item._pr` set without a tracker row (e.g.
+// the agent attached the PR via the structured-completion sidecar before the
+// poller could observe it as `open`, then it merged seconds later). Run a
+// best-effort enrollment so the PRD progress view sees the real status.
+async function _ensurePrEnrollmentForCompletedItem(meta, config) {
+  const itemPr = meta && meta.item && meta.item._pr;
+  if (!itemPr || typeof itemPr !== 'string') return null;
+  let project = null;
+  try {
+    const projectsList = (config && Array.isArray(config.projects)) ? config.projects : shared.getProjects(config);
+    const resolutionSource = meta.project?.name || meta.item?.project || meta.item?._source;
+    if (resolutionSource && Array.isArray(projectsList)) {
+      const resolution = shared.resolveProjectSource(resolutionSource, projectsList, { allowCentral: true });
+      project = resolution?.project || null;
+    }
+  } catch (err) {
+    log('warn', `_ensurePrEnrollmentForCompletedItem: project resolution failed: ${err.message}`);
+  }
+  let canonicalPrId = itemPr;
+  if (!shared.parseCanonicalPrId(itemPr) && project) {
+    canonicalPrId = shared.getCanonicalPrId(project, itemPr) || itemPr;
+  }
+  if (!shared.parseCanonicalPrId(canonicalPrId)) return null;
+  if (_existingPrRecordForCanonicalId(canonicalPrId)) return null;
+  try {
+    return await enrollPrFromCanonicalId(canonicalPrId, project, { itemId: meta.item.id });
+  } catch (err) {
+    log('warn', `_ensurePrEnrollmentForCompletedItem: enrollment failed for ${canonicalPrId}: ${err.message}`);
+    return null;
+  }
+}
+
 function isPrAttachmentRequired(type, item, meta = {}) {
   if (!item?.id || item.skipPr) return false;
   // SETUP (W-mpbi6f2q00104957) is implicitly PR-exempt — the type itself
@@ -4393,6 +4645,17 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     prsCreatedCount = syncPrsFromOutput(stdout, agentId, meta, config, { structuredCompletion }) || 0;
   } catch (err) { log('warn', `PR sync from output: ${err.message}`); }
 
+  // W-mq5uzmc6001d708f — back-fill enrollment for orphan `_pr` pointers.
+  // syncPrsFromOutput only enrolls PRs whose URL appeared in this dispatch's
+  // output. When meta.item._pr was stamped from an earlier dispatch (e.g. via
+  // reconcileItemsWithPrs against pr-links) but the canonical row never made
+  // it into pull-requests.json, the dashboard's PRD-progress synthesis
+  // defaults to ACTIVE forever. This catches those cases at the end of every
+  // post-completion run.
+  try {
+    await _ensurePrEnrollmentForCompletedItem(meta, config);
+  } catch (err) { log('warn', `PR enrollment back-fill: ${err.message}`); }
+
   // Structured completion may report PR even when regex didn't find it
   const scHasPr = structuredCompletion && structuredCompletion.pr && structuredCompletion.pr !== 'N/A';
   if (scHasPr && prsCreatedCount === 0) {
@@ -5311,4 +5574,7 @@ module.exports = {
   // Issue #2969 — exported for direct unit testing of the pause-flip alert
   // path without going through updatePrAfterFix's many guards.
   recordPrNoOpFixAttempt,
+  // W-mq5uzmc6001d708f — post-hoc PR enrollment for orphan `_pr` pointers.
+  enrollPrFromCanonicalId,
+  _setEnrollmentGhRunnerForTest,
 };

package/engine/queries.js

@@ -15,6 +15,63 @@ const { safeRead, safeReadDir, safeJson, safeWrite, getProjects, mutateJsonFileL
   projectWorkItemsPath, projectPrPath, parseSkillFrontmatter, KB_CATEGORIES,
   WI_STATUS, DONE_STATUSES, PRD_ITEM_STATUS, PR_STATUS, ENGINE_DEFAULTS, DEFAULT_AGENT_METRICS } = shared;
 
+// ─── Defensive PR enrichment cache (W-mq5uzmc6001d708f) ──────────────────────
+//
+// buildPrdProgress runs on every /api/status poll. When a work item carries
+// `_pr` but no canonical row exists in pull-requests.json, the synthesis
+// fallback below used to default to PR_STATUS.ACTIVE forever (blue ○). Now
+// we cache the resolved status per canonical id and kick off a best-effort
+// fire-and-forget enrollment so the next poll cycle sees the real status.
+// Lifecycle is lazy-required to avoid the circular dep (lifecycle.js requires
+// queries at top-level).
+
+const PR_ENRICHMENT_TTL_MS = 5 * 60 * 1000;
+const _prEnrichmentCache = new Map(); // canonicalId -> { status, expiresAt }
+const _prEnrichmentInFlight = new Set();
+let _lifecycleModule = null;
+function _lifecycle() {
+  if (!_lifecycleModule) {
+    try { _lifecycleModule = require('./lifecycle'); }
+    catch { _lifecycleModule = null; }
+  }
+  return _lifecycleModule;
+}
+function _getCachedPrEnrichment(id) {
+  if (!id) return null;
+  const cached = _prEnrichmentCache.get(id);
+  if (!cached) return null;
+  if (Date.now() > cached.expiresAt) {
+    _prEnrichmentCache.delete(id);
+    return null;
+  }
+  return cached.status;
+}
+function _setCachedPrEnrichment(id, status) {
+  if (!id || !status) return;
+  _prEnrichmentCache.set(id, { status, expiresAt: Date.now() + PR_ENRICHMENT_TTL_MS });
+}
+function _scheduleAsyncPrEnrollment(canonicalPrId, project, itemId) {
+  if (!canonicalPrId) return;
+  if (_prEnrichmentInFlight.has(canonicalPrId)) return;
+  const lc = _lifecycle();
+  if (!lc || typeof lc.enrollPrFromCanonicalId !== 'function') return;
+  _prEnrichmentInFlight.add(canonicalPrId);
+  setImmediate(() => {
+    Promise.resolve()
+      .then(() => lc.enrollPrFromCanonicalId(canonicalPrId, project, { itemId }))
+      .then((result) => {
+        if (result && result.status) _setCachedPrEnrichment(canonicalPrId, result.status);
+      })
+      .catch(() => { /* best-effort enrollment — caller is the dashboard hot path */ })
+      .then(() => { _prEnrichmentInFlight.delete(canonicalPrId); });
+  });
+}
+// Exposed for tests so suites that toggle PR-enrollment state can reset.
+function _resetPrEnrichmentCacheForTest() {
+  _prEnrichmentCache.clear();
+  _prEnrichmentInFlight.clear();
+}
+
 /**
  * Read the first `bytes` and last `bytes` of a file efficiently using byte offsets.
  * For files <= 2*bytes, reads the whole file. Returns { head, tail } strings.
@@ -1625,7 +1682,21 @@ function getPrdInfo(config) {
     const displayMatches = exactPr ? [] : Object.values(prById).filter(candidate => shared.getPrDisplayId(candidate) === shared.getPrDisplayId(wi._pr));
     const pr = exactPr || (displayMatches.length === 1 ? displayMatches[0] : null);
     const url = buildPrUrlFromId(canonicalPrId || wi._pr, pr, projects);
-    prdToPr[wi.id] = [{ id: pr?.id || canonicalPrId || wi._pr, url, title: pr?.title || '', status: pr?.status || PR_STATUS.ACTIVE, _project: project?.name || '' }];
+    // W-mq5uzmc6001d708f — read-side defensive enrichment. When no record
+    // exists (orphan _pr pointer), use a cached status from a prior async
+    // enrollment if available, else synthesize ACTIVE and schedule a
+    // fire-and-forget enrollment so the next status poll renders correctly.
+    let synthesizedStatus = pr?.status;
+    if (!pr && canonicalPrId) {
+      const cachedStatus = _getCachedPrEnrichment(canonicalPrId);
+      if (cachedStatus) {
+        synthesizedStatus = cachedStatus;
+      } else {
+        synthesizedStatus = PR_STATUS.ACTIVE;
+        _scheduleAsyncPrEnrollment(canonicalPrId, project, wi.id);
+      }
+    }
+    prdToPr[wi.id] = [{ id: pr?.id || canonicalPrId || wi._pr, url, title: pr?.title || '', status: synthesizedStatus || PR_STATUS.ACTIVE, _project: project?.name || '' }];
   }
   // Aggregate sub-task PRs to decomposed parent (sub-tasks aren't PRD items but their PRs should show)
   for (const pr of allPrs) {
@@ -2501,4 +2572,7 @@ module.exports = {
 
   // Work items & PRD
   getWorkItems, invalidateWorkItemsCache, getPrdInfo,
+
+  // W-mq5uzmc6001d708f — test hooks for the defensive PR enrichment cache.
+  _resetPrEnrichmentCacheForTest,
 };

package/engine/shared.js

@@ -2906,6 +2906,51 @@ function _resetLegacyCcModelMigrationFlag() {
   _legacyCcModelMigrationLogged = false;
 }
 
+/**
+ * One-time force-on for the CC worker pool.
+ *
+ * The pool has been the resolved default for copilot CC since PR #2492
+ * (`resolveCcUseWorkerPool` returns true when the config has no explicit
+ * value). But configs that carried an explicit `ccUseWorkerPool: false` —
+ * set before the default flipped, or copied from an old template — stay
+ * opted out forever. This migration flips those explicit-false opt-outs to
+ * `true` ONCE, on both surfaces the value lives in (`engine.ccUseWorkerPool`
+ * which the resolver reads, and `features.ccUseWorkerPool` which drives the
+ * Settings toggle / `isFeatureOn`), so the two stay consistent.
+ *
+ * Idempotency: records `engine._ccPoolForcedOnV1` after running. Once that
+ * marker is set the migration never touches the value again — so an operator
+ * who *deliberately* turns the pool off afterward is never re-forced. The
+ * marker is persisted even when nothing needed flipping, which is what lets a
+ * later opt-out be distinguished from a never-migrated config.
+ *
+ * Pure + idempotent: safe to call in-memory then re-apply to the on-disk copy
+ * under a lock (mirrors backfillProjectWorkSourceDefaults). Returns
+ * `{ changed, flipped }` — `changed` true means the config was mutated (marker
+ * set and/or values flipped) and should be persisted; `flipped` lists which
+ * surfaces ('engine'/'features') were actually turned on.
+ */
+function applyCcWorkerPoolForceOnMigration(config) {
+  const result = { changed: false, flipped: [] };
+  if (!config || typeof config !== 'object') return result;
+  const engine = (config.engine && typeof config.engine === 'object') ? config.engine : null;
+  if (!engine) return result; // no engine section — retry next start, harmless
+  if (engine._ccPoolForcedOnV1) return result; // already forced once; respect later opt-out
+
+  if (engine.ccUseWorkerPool === false) {
+    engine.ccUseWorkerPool = true;
+    result.flipped.push('engine');
+  }
+  const features = (config.features && typeof config.features === 'object') ? config.features : null;
+  if (features && features.ccUseWorkerPool === false) {
+    features.ccUseWorkerPool = true;
+    result.flipped.push('features');
+  }
+  engine._ccPoolForcedOnV1 = true; // marker — never force again
+  result.changed = true; // marker always needs persisting on first run
+  return result;
+}
+
 // ─── Runtime Config Preflight Warnings ──────────────────────────────────────
 //
 // Emit non-fatal warnings about runtime/CLI configuration drift. Consumed by
@@ -5547,39 +5592,17 @@ function normalizePrLinkItems(value) {
   return [...new Set(items.filter(item => typeof item === 'string' && item))];
 }
 
-/**
- * Single source of truth for "should the engine dispatch review/fix for this PR?"
- *
- * Used by `discoverFromPrs` in engine.js to gate review + fix dispatch, and by
- * `upsertPullRequestRecord` to decide whether to preserve auto-managed metadata
- * on merge. Dispatch-loop callers MUST go through this helper — do NOT inline
- * variants like `knownAgents.has(pr.agent) || pr.prdItems?.length || pr._manual`
- * because they silently drop the `_autoObserve` case (PR linked with
- * autoObserve=true but no prdItems and no configured-agent author) and the
- * sourcePlan/itemType cases. See W-mq5rs2eq000da8a9 for the bug repro.
- *
- * A PR is auto-managed when ANY of the following hold (and `_contextOnly` is
- * not explicitly true — context-only always wins):
- *   - It carries one or more `prdItems` (linked to work items)
- *   - It was explicitly opted-in via `_autoObserve: true` (manual link with
- *     autoObserve, or per-row toggle via POST /api/pull-requests/observe)
- *   - It was created from a plan or has an itemType (`sourcePlan`/`itemType`)
- *   - It has a non-empty agent author other than the literal string `'human'`
- *     (the helper deliberately does NOT require the agent be in
- *     `config.agents` — once `_autoObserve` is the explicit opt-in for
- *     non-agent authors, the loosened agent-string check has no operational
- *     downside for managed flows and avoids the silent-skip bug.)
- *
- * @param {object} pr Pull request record
- * @returns {boolean} true when the engine should drive review/fix for this PR
- */
+// W-mq5s5ttx000j7ab8-a — canonical `contextOnly` gate. The 6-clause legacy
+// body (prdItems / _autoObserve / sourcePlan / itemType / agent-heuristic) is
+// replaced by a single read of the canonical field. The one-shot boot
+// migration (migratePrGateFlags) projects the legacy signals onto
+// `contextOnly` so every on-disk record has the canonical value before any
+// tick fires. Anything new written via upsertPullRequestRecord (and the
+// dashboard link/observe paths consolidated in PR #3137 / `-c`) also lands
+// on `contextOnly` directly. See W-mq5rs2eq000da8a9 for the bug repro that
+// motivated consolidating onto a single helper.
 function isAutoManagedPrRecord(pr) {
-  if (!pr || typeof pr !== 'object' || pr._contextOnly === true) return false;
-  if (normalizePrLinkItems(pr.prdItems).length > 0) return true;
-  if (pr._autoObserve === true) return true;
-  if (pr.sourcePlan || pr.itemType) return true;
-  const agent = String(pr.agent || '').trim().toLowerCase();
-  return !!agent && agent !== 'human';
+  return !!pr && typeof pr === 'object' && pr.contextOnly !== true;
 }
 
 function mergePrLinkItems(links, prId, itemIds) {
@@ -5757,12 +5780,24 @@ function upsertPullRequestRecord(prPath, entry, { project = null, itemId = null,
           target[key] = normalizedEntry[key];
         }
       }
-      for (const key of ['_manual', '_autoObserve', '_context', '_projectResolution']) {
+      // W-mq5s5ttx000j7ab8-a — `_manual` and `_autoObserve` are no longer
+      // copied through; the engine reads gate state from the canonical
+      // `contextOnly` field (see isAutoManagedPrRecord above + the boot
+      // migration migratePrGateFlags). `_context`/`_projectResolution` are
+      // unrelated breadcrumbs and stay.
+      for (const key of ['_context', '_projectResolution']) {
         if (normalizedEntry[key] != null) target[key] = normalizedEntry[key];
       }
-      if (normalizedEntry._contextOnly != null) {
-        const wouldDemoteManagedPr = normalizedEntry._contextOnly === true && targetWasAutoManaged;
-        if (!wouldDemoteManagedPr) target._contextOnly = normalizedEntry._contextOnly;
+      // Accept either the canonical `contextOnly` (preferred) or the legacy
+      // `_contextOnly` from callers that haven't been migrated yet
+      // (dashboard.js manual-link path, lifecycle.js oneShot tagging — items
+      // (b)/(c) of the decomposition). Persist as canonical `contextOnly`.
+      const incomingContextOnly = normalizedEntry.contextOnly != null
+        ? normalizedEntry.contextOnly
+        : normalizedEntry._contextOnly;
+      if (incomingContextOnly != null) {
+        const wouldDemoteManagedPr = incomingContextOnly === true && targetWasAutoManaged;
+        if (!wouldDemoteManagedPr) target.contextOnly = incomingContextOnly === true;
       }
     }
     target.prdItems = normalizePrLinkItems(target.prdItems || []);
@@ -5785,6 +5820,105 @@ function upsertPullRequestRecord(prPath, entry, { project = null, itemId = null,
   return { id: canonicalId, prNumber, created, linked, skipped, record };
 }
 
+// ─── PR Gate Migration (W-mq5s5ttx000j7ab8-a) ───────────────────────────────
+//
+// One-shot boot migration that projects the legacy gate signals
+// (`_contextOnly`, `_autoObserve`, `_manual`) onto the canonical
+// `contextOnly` field on every `projects/<name>/pull-requests.json` record.
+// Wired from `engine/cli.js#start()` before the first tick fires so the new
+// `isAutoManagedPrRecord` (which only reads `contextOnly`) returns the same
+// verdict as the legacy 6-clause helper for pre-existing data.
+//
+// Per-record decision:
+//   1. contextOnly := (_contextOnly === true)
+//   2. legacyManaged := prdItems.length > 0 || _autoObserve === true ||
+//                       sourcePlan || itemType || (agent is a Minions persona)
+//      "Minions persona" = non-empty kebab-case identifier other than 'human'.
+//      Anything with whitespace (human display names like "yemi shin", which
+//      github poller writes into `agent` from `prData.user.login`) is treated
+//      as a human author, not a managed agent.
+//   3. If !contextOnly && !legacyManaged, set contextOnly = true and stamp
+//      `_migrationNote: 'auto-set-contextOnly-by-pr-gate-simplification'`.
+//   4. Persist `contextOnly`; delete `_autoObserve`, `_manual`, `_contextOnly`.
+//
+// Idempotent: records that already have `contextOnly` and none of the legacy
+// keys are skipped (no rewrite, no log line, JSON mtime unchanged).
+const _PR_GATE_MIGRATION_NOTE = 'auto-set-contextOnly-by-pr-gate-simplification';
+const _AGENT_PERSONA_RE = /^[a-z0-9_-]+$/;
+
+function _prRecordHasLegacyGateKey(record) {
+  return Object.prototype.hasOwnProperty.call(record, '_contextOnly')
+    || Object.prototype.hasOwnProperty.call(record, '_autoObserve')
+    || Object.prototype.hasOwnProperty.call(record, '_manual');
+}
+
+function _prRecordIsLegacyManaged(record) {
+  const prdItemsCount = Array.isArray(record.prdItems) ? record.prdItems.length : 0;
+  if (prdItemsCount > 0) return true;
+  if (record._autoObserve === true) return true;
+  if (record.sourcePlan) return true;
+  if (record.itemType) return true;
+  if (typeof record.agent === 'string') {
+    const agent = record.agent.trim().toLowerCase();
+    if (agent && agent !== 'human' && _AGENT_PERSONA_RE.test(agent)) return true;
+  }
+  return false;
+}
+
+function migratePrGateFlags(projectsRoot) {
+  const summary = { projectsScanned: 0, projectsMigrated: 0, totalRecords: 0, totalMigrated: 0 };
+  if (!projectsRoot || typeof projectsRoot !== 'string') return summary;
+  let entries;
+  try {
+    entries = fs.readdirSync(projectsRoot, { withFileTypes: true });
+  } catch {
+    return summary;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const projectName = entry.name;
+    const prPath = path.join(projectsRoot, projectName, 'pull-requests.json');
+    if (!fs.existsSync(prPath)) continue;
+    summary.projectsScanned++;
+
+    let migrated = 0;
+    let stamped = 0;
+    let alreadyMigrated = 0;
+
+    mutatePullRequests(prPath, (prs) => {
+      if (!Array.isArray(prs)) return prs;
+      for (const record of prs) {
+        if (!record || typeof record !== 'object') continue;
+        const hasLegacy = _prRecordHasLegacyGateKey(record);
+        const hasCanonical = Object.prototype.hasOwnProperty.call(record, 'contextOnly');
+        if (hasCanonical && !hasLegacy) { alreadyMigrated++; continue; }
+
+        let contextOnly = (record._contextOnly === true);
+        if (!contextOnly && !_prRecordIsLegacyManaged(record)) {
+          contextOnly = true;
+          record._migrationNote = _PR_GATE_MIGRATION_NOTE;
+          stamped++;
+        }
+        record.contextOnly = contextOnly;
+        delete record._autoObserve;
+        delete record._manual;
+        delete record._contextOnly;
+        migrated++;
+      }
+      return prs;
+    });
+
+    summary.totalRecords += (migrated + alreadyMigrated);
+    summary.totalMigrated += migrated;
+    if (migrated > 0) {
+      summary.projectsMigrated++;
+      // One line per project that actually moved. Keep idempotent runs silent.
+      console.log(`[pr-gate-migration] ${projectName}: migrated ${migrated} records (${stamped} stamped contextOnly, ${alreadyMigrated} already-migrated)`);
+    }
+  }
+  return summary;
+}
+
 // ─── Cross-Platform Process Kill Helpers ─────────────────────────────────────
 
 function normalizeKillPid(proc) {
@@ -6772,6 +6906,7 @@ module.exports = {
   resolveAgentCli, resolveCcCli, resolveCcUseWorkerPool, resolveAgentModel, resolveCcModel,
   resolveAgentMaxBudget, resolveAgentBareMode,
   applyLegacyCcModelMigration, _resetLegacyCcModelMigrationFlag,
+  applyCcWorkerPoolForceOnMigration,
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
   backfillProjectWorkSourceDefaults,
@@ -6841,6 +6976,8 @@ module.exports = {
   mergePrLinkItems, // exported for testing
   isAutoManagedPrRecord,
   upsertPullRequestRecord,
+  isAutoManagedPrRecord, // W-mq5s5ttx000j7ab8-a — exported for engine + watch-plugin gate consolidation
+  migratePrGateFlags, // W-mq5s5ttx000j7ab8-a — boot migration wired from engine/cli.js
   nextWorkItemId,
   getProjectOrg,
   getAdoOrgBase,