@yemi33/minions 0.1.2143 → 0.1.2144

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/package.json

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