@yemi33/minions 0.1.2447 → 0.1.2449

package/engine/{ado.js → ado/index.js}

@@ -1,39 +1,41 @@
 /**
- * engine/ado.js — Azure DevOps integration for Minions engine.
+ * engine/ado/index.js — Azure DevOps integration for Minions engine.
  * Extracted from engine.js: ADO token management, PR status polling, human comment polling.
  */
 
 const path = require('path');
 const childProcess = require('child_process');
-const shared = require('./shared');
+const shared = require('../core/shared');
 const { exec, execAsync, getAdoOrgBase, log, ts, dateStamp, PR_STATUS, BUILD_STATUS, REVIEW_STATUS, FETCH_TIMEOUT_MS, ADO_TOKEN_REFRESH_MAX_RETRIES, createThrottleTracker, createBackoffTracker, writeToInbox } = shared;
-const { getPrs } = require('./queries');
+const { getPrs } = require('../core/queries');
 const { mutateJsonFileLocked } = shared;
-const { acquireAdoToken } = require('./ado-token');
+const { acquireAdoToken } = require('./token');
 const {
-  hasMinionsMarker,
   hasVerdictPrefix,
+  classifyMarkerAuthorship,
+  isMarkerAuthored,
+  MARKER_AUTHORSHIP,
   classifyNonActionableAutomationComment,
-} = require('./comment-classifier');
-const { wrapUntrusted, buildSource } = require('./untrusted-fence');
-const reviewLearning = require('./review-learning');
+} = require('../providers/comment-classifier');
+const { wrapUntrusted, buildSource } = require('../core/untrusted-fence');
+const reviewLearning = require('../memory/review-learning');
 
 // Lazy require to avoid circular dependency — only needed for engine().handlePostMerge
 let _engine = null;
 function engine() {
-  if (!_engine) _engine = require('../engine');
+  if (!_engine) _engine = require('../../engine');
   return _engine;
 }
 
 // Lazy require for dispatch module (avoids circular dependency via engine)
 let _dispatch = null;
-function dispatchModule() { if (!_dispatch) _dispatch = require('./dispatch'); return _dispatch; }
+function dispatchModule() { if (!_dispatch) _dispatch = require('../orchestration/dispatch'); return _dispatch; }
 
 // Lazy require for lifecycle module — only needed for the stale-noopfix sweep
-// in pollPrStatus (W-mpx44p05000ze8d8). lifecycle.js lazy-requires ado.js back,
+// in pollPrStatus (W-mpx44p05000ze8d8). lifecycle.js lazy-requires ado/ back,
 // so this MUST stay lazy to avoid a circular import at module-load time.
 let _lifecycle = null;
-function lifecycleModule() { if (!_lifecycle) _lifecycle = require('./lifecycle'); return _lifecycle; }
+function lifecycleModule() { if (!_lifecycle) _lifecycle = require('../orchestration/lifecycle'); return _lifecycle; }
 
 const stripRefsHeads = s => (s || '').replace('refs/heads/', '');
 const getAdoPrUrl = (project, prNumber) => {
@@ -408,10 +410,17 @@ function applyAdoPrMetadata(pr, prData) {
     updated = true;
   }
 
-  const author = String(prData.createdBy?.displayName || '').trim();
-  if (author && pr.agent === 'human') {
-    pr.agent = author;
-    updated = true;
+  // Populate the real author identity from the ADO PR creator. Never overwrite
+  // pr.agent (the Minions author-agent) with a human display name.
+  {
+    const adoAuthor = shared.buildAdoAuthorIdentity(prData.createdBy);
+    if (adoAuthor) {
+      const mergedAuthor = shared.mergePrAuthorIdentity(pr.author, adoAuthor);
+      if (JSON.stringify(mergedAuthor) !== JSON.stringify(pr.author || null)) {
+        pr.author = mergedAuthor;
+        updated = true;
+      }
+    }
   }
 
   // W-mpej044m00076d63 / W-mrezh0yb0007f733: keep `pr.created` aligned with
@@ -462,26 +471,103 @@ function classifyBuildStatus(prBuilds) {
   return BUILD_STATUS.NONE;
 }
 
+/**
+ * Recency ordering key for one ADO build record, compared as a tuple so a
+ * weaker signal never outranks a stronger one:
+ *   queueTime (→ startTime → finishTime) → numeric build id → response order.
+ * ADO always stamps `queueTime` and returns builds newest-first, but neither
+ * is guaranteed by the API contract, so the key degrades instead of picking an
+ * arbitrary generation.
+ */
+function buildRecencyKey(build, index) {
+  const time = Date.parse(build?.queueTime || build?.startTime || build?.finishTime || '');
+  const id = Number(build?.id);
+  return [
+    Number.isFinite(time) ? time : -Infinity,
+    Number.isFinite(id) ? id : -Infinity,
+    -index,
+  ];
+}
+
+function compareBuildRecency(a, b) {
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] > b[i]) return 1;
+    if (a[i] < b[i]) return -1;
+  }
+  return 0;
+}
+
+/**
+ * Narrow a stale build set to the NEWEST merge commit it covers
+ * (W-msaux21y00g79c48).
+ *
+ * `refs/pull/<n>/merge` accumulates builds for EVERY push to the PR and the
+ * poller reads `$top=25` of them, so classifying that whole list ORs a single
+ * historical failure across the PR's entire life: once any build failed, every
+ * later stale evaluation reported 'failing' forever, even after the newest
+ * merge commit built green and the failures had been fixed on-branch. Group by
+ * `sourceVersion` and keep only the most recently built generation, so the
+ * stale classification says "the most recent thing CI actually told us about
+ * this PR" instead of OR-ing across already-superseded history.
+ *
+ * Draft PRs feel this hardest: ADO does not auto-run branch policies on drafts
+ * (see queueDraftPrValidationBuilds), so a draft spends most of its life on an
+ * unbuilt merge commit — i.e. inside this stale path.
+ */
+function selectNewestMergeCommitBuilds(allBuilds) {
+  const builds = Array.isArray(allBuilds) ? allBuilds : [];
+  if (builds.length < 2) return builds.slice();
+  const generations = new Map(); // sourceVersion → { key, builds }
+  builds.forEach((build, index) => {
+    const sourceVersion = String(build?.sourceVersion ?? '');
+    const key = buildRecencyKey(build, index);
+    const generation = generations.get(sourceVersion);
+    if (!generation) {
+      generations.set(sourceVersion, { key, builds: [build] });
+      return;
+    }
+    generation.builds.push(build);
+    if (compareBuildRecency(key, generation.key) > 0) generation.key = key;
+  });
+  if (generations.size < 2) return builds.slice();
+  let newest = null;
+  for (const generation of generations.values()) {
+    if (!newest || compareBuildRecency(generation.key, newest.key) > 0) newest = generation;
+  }
+  return newest.builds;
+}
+
 /**
  * Stale merge-commit fallback classifier (Issue #2747). When ADO returns
  * builds on a PR's merge ref but none target the current merge commit
  * (ADO recomputed merge-commit after a target-branch advance / rebase
- * without re-queueing), classify the stale set:
+ * without re-queueing), classify the NEWEST merge commit in that stale set
+ * (W-msaux21y00g79c48 — older generations are superseded history):
  *   - Stale-failing → 'failing' + buildStaleMergeCommit:true. A stale
  *     failing signal is strictly more actionable than 'none'; a fix WI
  *     either does real work (failure still in the branch) or verifies
  *     green via push (rebase resolved it).
+ *   - Stale-succeeded that contradicts a cached 'failing' → 'none' +
+ *     supersededCachedFailure:true. The current merge commit is unbuilt, so
+ *     the cached failure can only have come from an OLDER signal than the
+ *     green one we just read; re-asserting it pins the PR to 'failing'
+ *     forever and keeps dispatching build fixes against a green branch.
+ *     'none' (unknown) is the honest answer — 'passing' would be false
+ *     confidence about a merge commit nothing has built.
  *   - Stale-succeeded/other → preserve cached pr.buildStatus (or 'none')
  *     and do NOT set the stale-merge flag. Succeeded-on-pre-rebase is
  *     ambiguous and could be false confidence.
- * Returns { buildStatus, buildStaleMergeCommit }.
+ * Returns { buildStatus, buildStaleMergeCommit, supersededCachedFailure }.
  */
 function classifyStaleBuilds(allBuilds, cachedBuildStatus) {
-  const staleStatus = classifyBuildStatus(allBuilds);
+  const staleStatus = classifyBuildStatus(selectNewestMergeCommitBuilds(allBuilds));
   if (staleStatus === BUILD_STATUS.FAILING) {
-    return { buildStatus: BUILD_STATUS.FAILING, buildStaleMergeCommit: true };
+    return { buildStatus: BUILD_STATUS.FAILING, buildStaleMergeCommit: true, supersededCachedFailure: false };
+  }
+  if (staleStatus === BUILD_STATUS.PASSING && cachedBuildStatus === BUILD_STATUS.FAILING) {
+    return { buildStatus: BUILD_STATUS.NONE, buildStaleMergeCommit: false, supersededCachedFailure: true };
   }
-  return { buildStatus: cachedBuildStatus || BUILD_STATUS.NONE, buildStaleMergeCommit: false };
+  return { buildStatus: cachedBuildStatus || BUILD_STATUS.NONE, buildStaleMergeCommit: false, supersededCachedFailure: false };
 }
 
 /**
@@ -526,6 +612,130 @@ async function queueFreshAdoBuild({ orgBase, project, prNumber, definitionId, to
   return adoFetch(url, token, { method: 'POST', body });
 }
 
+// ─── Draft-PR branch-policy build queueing (W-ms7kklp8002zad24) ───────────────
+//
+// On Azure DevOps, branch build policies do NOT run automatically while a PR is
+// a draft — the required policy builds sit un-queued, so a Minions-managed draft
+// PR never gets a build status and the existing build-fix loop has nothing to
+// act on. GitHub already fires CI on drafts, so this whole path is ADO-only.
+//
+// For a draft PR with buildStatus === NONE there are NO existing builds to read
+// `build.definition.id` from, so the stale-requeue path cannot supply a
+// definitionId. We instead DISCOVER the required build definition(s) from the
+// target branch's ADO branch-policy configurations.
+
+// ADO "Build" policy type id — every branch build policy carries this type.id.
+const ADO_BUILD_POLICY_TYPE_ID = '0609b952-1397-4640-95ec-e00a01b2c241';
+
+/**
+ * Does an ADO policy `settings.scope[]` entry apply to this PR's target branch
+ * (and repo)? ADO scope entries carry `{ repositoryId, refName, matchKind }`:
+ *   - `repositoryId` null/empty → the policy applies to every repo in the
+ *     project; a concrete GUID must match this PR's repo (case-insensitive).
+ *   - `matchKind` 'Exact' (default) → target refName must equal the scope
+ *     refName; 'Prefix' → target refName must start with the scope refName
+ *     (ADO's prefix branch policies, e.g. scope `refs/heads/release/` covering
+ *     `refs/heads/release/x`).
+ */
+function adoPolicyScopeMatches(scopeEntry, targetRefName, repositoryId) {
+  if (!scopeEntry || typeof scopeEntry !== 'object') return false;
+  const scopeRepo = String(scopeEntry.repositoryId || '').trim();
+  if (scopeRepo) {
+    const prRepo = String(repositoryId || '').trim();
+    if (!prRepo || scopeRepo.toLowerCase() !== prRepo.toLowerCase()) return false;
+  }
+  const scopeRef = String(scopeEntry.refName || '').trim();
+  if (!scopeRef) return false; // no branch scope → not a branch-targeted policy we can match
+  const target = String(targetRefName || '').trim();
+  if (!target) return false;
+  const matchKind = String(scopeEntry.matchKind || 'exact').toLowerCase();
+  if (matchKind === 'prefix') return target === scopeRef || target.startsWith(scopeRef);
+  return target === scopeRef; // Exact (default)
+}
+
+/**
+ * Parse an ADO policy/configurations `value[]` into the DISTINCT set of required
+ * build definition ids that apply to `targetRefName` on `repositoryId`. Only
+ * enabled + blocking (required) Build policies whose scope matches the target
+ * branch + repo are considered. Pure/testable — no network. Returns number[].
+ */
+function extractDraftPrBuildDefinitionIds(policyConfigs, targetRefName, repositoryId) {
+  const ids = [];
+  const seen = new Set();
+  if (!Array.isArray(policyConfigs)) return ids;
+  for (const cfg of policyConfigs) {
+    if (!cfg || typeof cfg !== 'object') continue;
+    if (String(cfg?.type?.id || '').toLowerCase() !== ADO_BUILD_POLICY_TYPE_ID) continue;
+    if (cfg.isEnabled !== true || cfg.isBlocking !== true) continue;
+    const settings = cfg.settings || {};
+    const rawDefId = settings.buildDefinitionId;
+    if (rawDefId == null || rawDefId === '') continue;
+    if (typeof rawDefId !== 'number' && typeof rawDefId !== 'string') continue;
+    // ADO normally serializes buildDefinitionId as a number, but a string id
+    // would silently defeat a raw Set dedupe (1234 !== '1234') and queue the
+    // SAME pipeline twice. Normalize before comparing and before emitting.
+    const defId = Number(rawDefId);
+    if (!Number.isFinite(defId)) continue;
+    const scopes = Array.isArray(settings.scope) ? settings.scope : [];
+    if (!scopes.some(s => adoPolicyScopeMatches(s, targetRefName, repositoryId))) continue;
+    if (seen.has(defId)) continue;
+    seen.add(defId);
+    ids.push(defId);
+  }
+  return ids;
+}
+
+/**
+ * Discover the required branch-policy build definitions for a draft PR's target
+ * branch and queue a fresh validation build for each distinct definition against
+ * refs/pull/<prNumber>/merge. Non-fatal: the policy-config fetch and every queue
+ * POST are wrapped so a failure logs a warn and returns without throwing (mirrors
+ * queueFreshAdoBuild's non-fatal contract).
+ *
+ * Returns `{ queued, discovered }`:
+ *   - `queued`     — how many builds were actually POSTed.
+ *   - `discovered` — whether policy discovery COMPLETED and produced a definitive
+ *     answer for this branch. True even when zero definitions matched, because
+ *     "this branch has no required Build policies" is a stable result: the caller
+ *     uses it to close the 30-min rate-limit window so it stops re-GETting
+ *     policy/configurations on every single poll. False only when we short-circuit
+ *     on a malformed PR or the policy fetch itself failed (transient — the caller
+ *     leaves the window open and retries on the next poll).
+ */
+async function queueDraftPrValidationBuilds(pr, project, token, orgBase) {
+  const prNumber = pr?.prNumber;
+  const targetRefName = pr?.targetRefName;
+  if (!prNumber || !targetRefName) return { queued: 0, discovered: false };
+  const repositoryId = getConfiguredAdoRepositoryGuid(project) || getAdoRepositoryId(project);
+
+  let defIds = [];
+  try {
+    const url = `${orgBase}/${project.adoProject}/_apis/policy/configurations?api-version=7.1`;
+    const data = await adoFetch(url, token);
+    defIds = extractDraftPrBuildDefinitionIds(data?.value || [], targetRefName, repositoryId);
+  } catch (e) {
+    log('warn', `PR ${pr.id} draft-build: failed to fetch policy configurations: ${e.message}`);
+    return { queued: 0, discovered: false };
+  }
+
+  if (defIds.length === 0) {
+    log('info', `PR ${pr.id} draft-build: no required Build policies matched target ${targetRefName}; nothing to queue`);
+    return { queued: 0, discovered: true };
+  }
+
+  let queued = 0;
+  for (const definitionId of defIds) {
+    try {
+      await queueFreshAdoBuild({ orgBase, project, prNumber, definitionId, token });
+      queued++;
+      log('info', `PR ${pr.id} draft-build: queued validation build for definition id=${definitionId} on refs/pull/${prNumber}/merge (draft PR — ADO does not auto-trigger policy builds)`);
+    } catch (e) {
+      log('warn', `PR ${pr.id} draft-build: failed to queue validation build for definition id=${definitionId}: ${e.message}`);
+    }
+  }
+  return { queued, discovered: true };
+}
+
 /** Map ADO reviewer vote array to a review status string. */
 function votesToReviewStatus(votes) {
   if (votes.some(v => v === -10)) return REVIEW_STATUS.CHANGES_REQUESTED;
@@ -589,8 +799,8 @@ function _voteSnapshotsPath() {
   // Resolve lazily so tests that swap MINIONS_DIR via createTestMinionsDir()
   // see the fresh value. shared.MINIONS_DIR is reassigned when MINIONS_TEST_DIR
   // is set, but only when shared is re-required — which the helper does via
-  // `require('./shared').MINIONS_DIR`.
-  return path.join(require('./shared').MINIONS_DIR, 'engine', VOTE_SNAPSHOT_FILE);
+  // `require('../core/shared').MINIONS_DIR`.
+  return path.join(require('../core/shared').MINIONS_DIR, 'engine', VOTE_SNAPSHOT_FILE);
 }
 
 function _normalizeSnapshotKey(prId, reviewerId) {
@@ -760,7 +970,7 @@ function _scanStuckVote({ pr, reviewerId, vote, sourceCommit, snapshot, now }) {
 function _hasPendingReReviewWi(pr) {
   if (!pr?.id) return false;
   try {
-    const dispatchData = require('./queries').getDispatch();
+    const dispatchData = require('../core/queries').getDispatch();
     const all = [...(dispatchData?.pending || []), ...(dispatchData?.active || [])];
     return all.some(d => {
       if (d?.type !== 'review') return false;
@@ -1203,16 +1413,26 @@ async function fetchAdoBuildErrorLog(orgBase, project, failedStatus, token, pr,
 /**
  * Iterate active PRs across all projects. Calls `callback(project, pr, prNum, orgBase, adoRepositoryId)`
  * for each active PR. If callback returns truthy, the PR file is saved after the project loop.
+ *
+ * @param {object} [options]
+ * @param {number} [options.abandonedRepollWindowMs] — W-msav5edk00g81710. Mirror of
+ *   engine/providers/github.js:forEachActiveGhPr. Opt-in bounded re-probe of
+ *   recently-abandoned records so a reopened PR can leave the terminal stamp.
+ *   Defaults to 0 (strict PR_POLLABLE_STATUSES) — only the status poll opts in.
  */
-async function forEachActivePr(config, token, callback) {
+async function forEachActivePr(config, token, callback, options = {}) {
   const projects = shared.getProjects(config);
   let totalUpdated = 0;
+  const pollOpts = {
+    windowMs: Number(options.abandonedRepollWindowMs) || 0,
+    now: Date.now(),
+  };
 
   for (const project of projects) {
     if (isGitHubProject(project)) continue;
     // W-mp625n27000m6e78 — Honor per-project workSources.pullRequests.enabled.
     // Default-ON: only skip when explicitly disabled (=== false). Same gate as
-    // engine/github.js:forEachActiveGhPr — without this, disabling PR polling
+    // engine/providers/github.js:forEachActiveGhPr — without this, disabling PR polling
     // for an ADO project via the dashboard Settings UI was cosmetic.
     const src = project?.workSources?.pullRequests || config?.workSources?.pullRequests;
     if (src && src.enabled === false) continue;
@@ -1221,7 +1441,7 @@ async function forEachActivePr(config, token, callback) {
     if (!project.adoOrg || !project.adoProject) continue;
 
     const prs = getPrs(project);
-    const activePrs = prs.filter(pr => shared.PR_POLLABLE_STATUSES.has(pr.status)
+    const activePrs = prs.filter(pr => shared.isPrPollable(pr, pollOpts)
       && shared.isPrCompatibleWithProject(project, pr, pr.url || ''));
     if (activePrs.length === 0) continue;
 
@@ -1309,13 +1529,13 @@ async function forEachActivePr(config, token, callback) {
   }
 
   // BUG-C2 — Also poll manually linked ADO PRs from the central PR store.
-  // Mirror of engine/github.js:540-633. Without this block, any ADO PR enrolled
+  // Mirror of engine/providers/github.js:540-633. Without this block, any ADO PR enrolled
   // into the central PR store via the dashboard attach UI or
   // lifecycle.enrollPrFromCanonicalId is never polled (status, build, review,
   // comments, abandoned-reconciliation all freeze permanently).
   //
   // MIRROR-SYMMETRY CONTRACT: any future divergence between
-  // engine/github.js:540-633 and this branch is itself a bug class. The
+  // engine/providers/github.js:540-633 and this branch is itself a bug class. The
   // canonical 'mirror-ado-github-poll-fix' skill applies. Keep filter, gating,
   // per-PR iteration, and merge-back semantics symmetric.
   //
@@ -1340,7 +1560,7 @@ async function forEachActivePr(config, token, callback) {
   const configuredAdoProjects = projects.filter(p => !isGitHubProject(p) && p.adoOrg && p.adoProject);
 
   const activeCentral = centralPrs.filter(pr => {
-    if (!shared.PR_POLLABLE_STATUSES.has(pr.status)) return false;
+    if (!shared.isPrPollable(pr, pollOpts)) return false;
     if (String(pr.repoHost || 'ado').toLowerCase() !== 'ado') return false;
     if (!parseCanonicalAdoPrId(pr.id, 'central ADO PR poll')) return false;
     // Only defer to the project loop when the PR is ACTUALLY present in that
@@ -1473,13 +1693,13 @@ async function pollPrStatus(config) {
 
     let newStatus = pr.status;
     // W-mp5trwh60008386d: ADO does NOT need the `prAbandonConfirmCount` confirmation logic
-    // that engine/github.js uses. ADO only flips a PR to `abandoned` when a *successful*
+    // that engine/providers/github.js uses. ADO only flips a PR to `abandoned` when a *successful*
     // adoFetch returns `prData.status === 'abandoned'` (below). On 404/auth failure adoFetch
     // throws, the throw propagates to forEachActivePr's `Promise.allSettled`, and the PR
     // record is left untouched — equivalent to "infinite confirmations required". The shared
-    // ENGINE_DEFAULTS.prAbandonConfirmCount constant lives in engine/shared.js so a future
+    // ENGINE_DEFAULTS.prAbandonConfirmCount constant lives in engine/core/shared.js so a future
     // ADO change can adopt the same semantics if the failure model ever maps 404 to
-    // abandonment directly. See engine/github.js pollPrStatus for the GitHub implementation.
+    // abandonment directly. See engine/providers/github.js pollPrStatus for the GitHub implementation.
     if (prData.status === 'completed') newStatus = PR_STATUS.MERGED;
     else if (prData.status === 'abandoned') newStatus = PR_STATUS.ABANDONED;
     else if (prData.status === 'active') newStatus = PR_STATUS.ACTIVE;
@@ -1501,6 +1721,12 @@ async function pollPrStatus(config) {
       if ((newStatus === PR_STATUS.ABANDONED || newStatus === PR_STATUS.CLOSED) && !pr.closedAt) {
         pr.closedAt = prData.closedDate || ts();
       }
+      // W-msav5edk00g81710: anchor the bounded re-probe window (mirror of
+      // engine/providers/github.js). ADO abandonment is fully reversible via
+      // "Reactivate", so the record must stay observable for a bounded window.
+      if (newStatus === PR_STATUS.ABANDONED) {
+        shared.stampPrAbandonedAt(pr, prData.closedDate || pr.closedAt || ts());
+      }
 
       if (newStatus === PR_STATUS.MERGED || newStatus === PR_STATUS.ABANDONED) {
         if (pr.reviewStatus === REVIEW_STATUS.WAITING) {
@@ -1537,7 +1763,7 @@ async function pollPrStatus(config) {
       // references it. Invariant #14 ('approved is permanent terminal') is
       // preserved: we keep reviewStatus when it was 'approved' rather than
       // carving a wasReopened exception into the 8+ guard sites in
-      // engine/lifecycle.js, engine.js, engine/github.js, and engine/ado.js.
+      // engine/orchestration/lifecycle.js, engine.js, engine/providers/github.js, and engine/ado/index.js.
       // Re-review safety on new commits is handled by the pre-existing
       // pr.lastPushedAt > pr.lastReviewedAt path (engine.js alreadyReviewed
       // gate) plus the changes-requested override in lifecycle.js.
@@ -1550,6 +1776,10 @@ async function pollPrStatus(config) {
         // F6 not yet shipped (field absent).
         delete pr.humanFeedback.editsSeen;
         pr.fixDispatched = false;
+        // W-msav5edk00g81710: record left `abandoned` — drop the re-probe
+        // anchor and the stale close timestamp it falls back to.
+        shared.clearPrAbandonedAt(pr);
+        delete pr.closedAt;
         if (pr.reviewStatus !== REVIEW_STATUS.APPROVED) pr.reviewStatus = REVIEW_STATUS.PENDING;
         log('info', `PR ${pr.id} reopened — reset transient state (reviewStatus=${pr.reviewStatus})`);
       }
@@ -1578,7 +1808,7 @@ async function pollPrStatus(config) {
     }
 
     // P-w1a3f9b2 — Phase 1.1: plumb mergeable / isDraft / mergeStatus /
-    // headRefOid onto the PR object so watches captureState (engine/watches.js)
+    // headRefOid onto the PR object so watches captureState (engine/watches/index.js)
     // and future predicates (Phase 2.1: head-commit-change, mergeable-flipped,
     // ready-for-merge, draft-flipped) can read them.
     //
@@ -1787,15 +2017,21 @@ async function pollPrStatus(config) {
             // builds for this PR's merge ref but none target the current
             // `mergeCommitId` — most likely the target branch moved (rebase
             // or push), ADO recomputed the merge commit, but no new
-            // source-side changes triggered a rebuild. Classify the stale
-            // set: stale-failing flips to 'failing' + buildStaleMergeCommit
-            // (strictly more actionable than 'none'); stale-succeeded/other
-            // preserves cached state (no false confidence).
+            // source-side changes triggered a rebuild. Classify the NEWEST
+            // merge commit in that stale set (W-msaux21y00g79c48): stale-
+            // failing flips to 'failing' + buildStaleMergeCommit (strictly
+            // more actionable than 'none'); stale-succeeded/other preserves
+            // cached state (no false confidence) unless it contradicts a
+            // cached failure, which it then drops.
             const stale = classifyStaleBuilds(allBuilds, pr.buildStatus);
             buildStatus = stale.buildStatus;
             buildStaleMergeCommit = stale.buildStaleMergeCommit;
+            // Same narrowing classifyStaleBuilds applies, so the reported
+            // reason and the re-queued definitions describe the generation we
+            // actually classified rather than a superseded one.
+            const newestStaleBuilds = selectNewestMergeCommitBuilds(allBuilds);
             if (buildStaleMergeCommit) {
-              const failed = allBuilds.find(b => b.result === 'failed') || allBuilds.find(b => b.result === 'canceled');
+              const failed = newestStaleBuilds.find(b => b.result === 'failed') || newestStaleBuilds.find(b => b.result === 'canceled');
               buildFailReason = failed?.definition?.name || 'Build failed (stale merge commit)';
               buildFailureSignature = shared.safeSlugComponent([
                 failed?.definition?.name,
@@ -1805,7 +2041,7 @@ async function pollPrStatus(config) {
               ].filter(Boolean).join('\n') || buildFailReason, 80);
               // Collect PR-validation definitions with failures for fresh-build queue.
               const seenDefIds = new Set();
-              for (const b of allBuilds) {
+              for (const b of newestStaleBuilds) {
                 if ((b.result === 'failed' || b.result === 'canceled') && isPrValidationBuild(b)) {
                   const defId = b?.definition?.id;
                   if (defId != null && !seenDefIds.has(defId)) {
@@ -1817,8 +2053,8 @@ async function pollPrStatus(config) {
             } else if (pr.buildFailReason && buildStatus === pr.buildStatus) {
               buildFailReason = pr.buildFailReason;
             }
-            const sampleSv = (allBuilds[0]?.sourceVersion || '').slice(0, 8);
-            log('warn', `PR ${pr.id} build: merge-commit mismatch — ${allBuilds.length} build(s) on merge ref, none target current merge commit ${String(mergeCommitId).slice(0, 8)} (sample sourceVersion ${sampleSv}); classified '${buildStatus}' from stale set${buildStaleMergeCommit ? ' (stale failing — will queue fresh build if rate limit allows)' : ''}`);
+            const sampleSv = (newestStaleBuilds[0]?.sourceVersion || '').slice(0, 8);
+            log('warn', `PR ${pr.id} build: merge-commit mismatch — ${allBuilds.length} build(s) on merge ref, none target current merge commit ${String(mergeCommitId).slice(0, 8)} (newest built merge commit ${sampleSv}, ${newestStaleBuilds.length} build(s)); classified '${buildStatus}' from that generation${buildStaleMergeCommit ? ' (stale failing — will queue fresh build if rate limit allows)' : ''}${stale.supersededCachedFailure ? ` (dropped cached '${BUILD_STATUS.FAILING}' — superseded by the newer green build)` : ''}`);
           }
         } catch (e) {
           buildStatusResolved = false;
@@ -1930,6 +2166,43 @@ async function pollPrStatus(config) {
       }
     }
 
+    // Draft-PR branch-policy build queueing (W-ms7kklp8002zad24). ADO does NOT
+    // auto-trigger branch build policies while a PR is a draft, so an
+    // auto-managed draft PR sits at buildStatus === NONE forever and the
+    // build-fix loop has nothing to act on. Discover the required Build
+    // policies from the target branch and queue a fresh build per distinct
+    // definition against refs/pull/<n>/merge; the next poll then picks up
+    // RUNNING/FAILING/PASSING via the existing classifyBuildStatus path and the
+    // existing auto-fix loop iterates. Gated by engine.adoQueueDraftPrBuilds
+    // (default true). Rate-limited via the shared _lastBuildRequeueAt window and
+    // restricted to auto-managed (non-context-only) PRs. Non-fatal by contract.
+    const adoQueueDraftPrBuilds = config?.engine?.adoQueueDraftPrBuilds ?? shared.ENGINE_DEFAULTS.adoQueueDraftPrBuilds;
+    if (adoQueueDraftPrBuilds && buildStatusResolved && buildStatus === BUILD_STATUS.NONE
+      && pr.isDraft === true && shared.isAutoManagedPrRecord(pr)) {
+      if (shouldRequeueStaleBuild(pr)) {
+        try {
+          const { queued, discovered } = await queueDraftPrValidationBuilds(pr, project, token, orgBase);
+          // Close the shared rate-limit window whenever policy discovery
+          // COMPLETED — including the zero-match case. A target branch with no
+          // required Build policies is a stable answer, so stamping only on
+          // queued > 0 left every subsequent poll re-GETting
+          // policy/configurations for that PR forever (PR #1099 review). A
+          // transient policy-fetch failure reports discovered:false and
+          // deliberately leaves the window open so the next poll retries.
+          if (discovered) {
+            pr._lastBuildRequeueAt = Date.now();
+            updated = true; // persist the stamp, otherwise the back-off is lost
+          }
+        } catch (e) {
+          log('warn', `PR ${pr.id} draft-build: queueDraftPrValidationBuilds threw unexpectedly: ${e.message}`);
+        }
+      } else {
+        const lastAt = Number(pr._lastBuildRequeueAt) || 0;
+        const ageMin = Math.floor((Date.now() - lastAt) / 60000);
+        log('info', `PR ${pr.id} draft-build: buildStatus none on draft PR but skipping queue — last requeue ${ageMin}m ago (rate limit: 30 min)`);
+      }
+    }
+
     // Auto-complete: set auto-complete on PR when builds green + review approved
     if (pr.status === PR_STATUS.ACTIVE && pr.reviewStatus === REVIEW_STATUS.APPROVED && pr.buildStatus === BUILD_STATUS.PASSING && !pr._autoCompleted) {
       const autoComplete = config.engine?.autoCompletePrs === true; // opt-in
@@ -1995,6 +2268,11 @@ async function pollPrStatus(config) {
       }
       throw err; // re-throw non-auth errors for forEachActivePr to handle
     }
+  }, {
+    // W-msav5edk00g81710 — only the STATUS poll re-probes recently-abandoned
+    // records (mirror of engine/providers/github.js#pollPrStatus). ADO's
+    // "Reactivate" is the exact analogue of a GitHub reopen.
+    abandonedRepollWindowMs: shared.resolveAbandonedPrRepollWindowMs(config),
   });
 
   if (totalUpdated > 0) {
@@ -2004,6 +2282,32 @@ async function pollPrStatus(config) {
 
 // ─── Poll Human Comments on PRs ──────────────────────────────────────────────
 
+// W-msbf1kf6033f46cb — acceptance criterion 2: an unconfigured
+// `config.engine.minionsAdoIdentities` leaves the marker spoof guard inactive
+// (marker-presence alone then classifies as agent-authored). That is the safe
+// default, but it must not be SILENT — an operator who assumed the spoof guard
+// was live deserves to be told it is not. Latched once per process because
+// pollPrHumanComments runs every `prPollCommentsEvery` ticks over every active
+// ADO PR; warning per comment would bury the engine log.
+let _adoMarkerSpoofGuardWarned = false;
+
+function _warnAdoMarkerSpoofGuardInactiveOnce() {
+  if (_adoMarkerSpoofGuardWarned) return;
+  _adoMarkerSpoofGuardWarned = true;
+  log('warn',
+    'ADO comment classifier: config.engine.minionsAdoIdentities is empty — the Minions marker '
+    + 'spoof guard is INACTIVE. Marker-bearing comments are trusted as agent-authored without an '
+    + 'author cross-check (fail-safe: prevents agent fix-summaries from re-triggering fix '
+    + 'dispatches). Populate engine.minionsAdoIdentities with the ADO identities Minions posts '
+    + 'under to re-enable the cross-check.');
+}
+
+// Test hook: clears the once-per-process latch so a test can assert the
+// warning fires exactly once.
+function _resetAdoMarkerSpoofGuardWarningForTest() {
+  _adoMarkerSpoofGuardWarned = false;
+}
+
 async function pollPrHumanComments(config) {
   // #3758 — inert when no project actually uses ADO.
   if (!hasAdoProjectConfigured(config)) return;
@@ -2024,7 +2328,7 @@ async function pollPrHumanComments(config) {
     // including bot/CI bodies and explicitly-ignored authors that get filtered
     // out before reaching `allHumanComments`. We need their dates so the
     // cutoff can advance past them on every successful poll, mirroring the
-    // GitHub poller convention (engine/github.js: `allCommentDates`). Without
+    // GitHub poller convention (engine/providers/github.js: `allCommentDates`). Without
     // this, ignored/CI comments are re-fetched and re-filtered every tick.
     const allHumanComments = [];
     const newHumanComments = [];
@@ -2042,20 +2346,28 @@ async function pollPrHumanComments(config) {
     // P-f23classifier (F3, security note): ADO has no `viewerDidAuthor`
     // equivalent. A human pasting our `<!-- minions:agent=... -->` marker
     // (e.g. by copy-paste from a fix-summary) would otherwise be
-    // misclassified as agent-authored. Cross-check marker-presence against
-    // the configured Minions identity (uniqueName / displayName / id /
-    // descriptor) so marker-presence alone NEVER suffices on ADO. When
-    // `minionsAdoIdentities` is empty (default), marker-presence is ignored
-    // entirely on ADO — the body still has to match one of the legacy
-    // regexes (Minions(...), by Minions, [minions], VERDICT:) to classify
-    // as agent-authored.
+    // misclassified as agent-authored. `config.engine.minionsAdoIdentities`
+    // (uniqueName / displayName / id / descriptor) is the ADO stand-in for
+    // that identity signal.
+    //
+    // W-msbf1kf6033f46cb: an EMPTY allowlist means the identity signal is
+    // UNAVAILABLE, not that the author is someone else. Those two used to
+    // collapse to the same answer here, so with the default empty allowlist
+    // `markerAuthored` was ALWAYS false and the hidden marker had zero
+    // filtering power on ADO. Every agent fix-summary was then reclassified
+    // as new human feedback and re-triggered a fix dispatch on the same PR
+    // (ADO PR 5530936: ten consecutive zero-change dispatches). Resolution
+    // now runs through the shared `classifyMarkerAuthorship` seam, which
+    // fails SAFE on an unavailable signal while keeping the spoof guard at
+    // full strength on a real mismatch. See the module header of
+    // engine/providers/comment-classifier.js for the cost asymmetry.
     const minionsAdoIdentities = new Set(
       (Array.isArray(config.engine?.minionsAdoIdentities) ? config.engine.minionsAdoIdentities : [])
         .map(s => String(s || '').toLowerCase())
         .filter(Boolean)
     );
+    const adoIdentityAvailable = minionsAdoIdentities.size > 0;
     const isAdoMinionsAuthor = (comment) => {
-      if (minionsAdoIdentities.size === 0) return false;
       const author = comment?.author || {};
       const candidates = [author.uniqueName, author.displayName, author.id, author.descriptor];
       for (const cand of candidates) {
@@ -2071,7 +2383,7 @@ async function pollPrHumanComments(config) {
       // fresh human replies (humans do reply on resolved threads after a
       // teammate marks them done). Classification below — ignoredAuthors,
       // CI/coverage report regex, agent (Minions) detection — runs on every
-      // collected comment, mirroring engine/github.js pollPrHumanComments
+      // collected comment, mirroring engine/providers/github.js pollPrHumanComments
       // which has never filtered by thread state.
       for (const comment of (thread.comments || [])) {
         if (!comment.content || comment.commentType === 'system') continue;
@@ -2110,13 +2422,28 @@ async function pollPrHumanComments(config) {
         if (automationReason) continue;
         // P-f23classifier (F3): detect agent comments (included in context
         // but don't trigger fix). Structurally symmetric to
-        // engine/github.js _isAgentComment + _isMinionsAuthoredComment:
-        //   - marker-presence + ADO identity cross-check (spoof guard), OR
+        // engine/providers/github.js _isAgentComment + _isMinionsAuthoredComment:
+        //   - marker authorship via the shared classifyMarkerAuthorship seam
+        //     (marker + ADO identity signal, fail-safe when unconfigured), OR
         //   - legacy body patterns (Minions(...), by Minions, [minions]), OR
         //   - hasVerdictPrefix(content) — engine-owned structured-output
         //     contract emitted by playbooks/review.md.
-        const markerAuthored = hasMinionsMarker(content) && isAdoMinionsAuthor(comment);
-        const isAgent = markerAuthored
+        //
+        // W-msbf1kf6033f46cb: the legacy patterns are a weak fallback, not a
+        // safety net. `/\bMinions\s*\(/i` does NOT match `[Minions](url)` and
+        // `/\bby\s+Minions\b/i` does NOT match `by [Minions]` (the bracket
+        // intervenes), so on ADO only a literal `[Minions]` ever fires. An
+        // agent posting through the raw `az`/REST fallback omits that brand
+        // sign-off entirely — the marker is what has to carry the weight.
+        const markerAuthorship = classifyMarkerAuthorship({
+          body: content,
+          identityAvailable: adoIdentityAvailable,
+          identityMatches: adoIdentityAvailable && isAdoMinionsAuthor(comment),
+        });
+        if (markerAuthorship === MARKER_AUTHORSHIP.IDENTITY_UNAVAILABLE) {
+          _warnAdoMarkerSpoofGuardInactiveOnce();
+        }
+        const isAgent = isMarkerAuthored(markerAuthorship)
           || /\bMinions\s*\(/i.test(content)
           || /\bby\s+Minions\b/i.test(content)
           || /\[minions\]/i.test(content)
@@ -2359,7 +2686,8 @@ async function reconcilePrs(config) {
             id: prId,
             prNumber: adoPr.pullRequestId,
             title: (adoPr.title || `PR #${adoPr.pullRequestId}`).slice(0, 120),
-            agent: (linkedItem?.dispatched_to || adoPr.createdBy?.displayName || 'unknown').toLowerCase(),
+            agent: (linkedItem?.dispatched_to || shared.PR_AGENT_HUMAN).toLowerCase(),
+            author: shared.buildAdoAuthorIdentity(adoPr.createdBy),
             branch,
             reviewStatus: REVIEW_STATUS.PENDING,
             status: PR_STATUS.ACTIVE,
@@ -2403,7 +2731,8 @@ async function reconcilePrs(config) {
         id: prId,
         prNumber: adoPr.pullRequestId,
         title: (adoPr.title || `PR #${adoPr.pullRequestId}`).slice(0, 120),
-        agent: (linkedItem?.dispatched_to || adoPr.createdBy?.displayName || 'unknown').toLowerCase(),
+        agent: (linkedItem?.dispatched_to || shared.PR_AGENT_HUMAN).toLowerCase(),
+        author: shared.buildAdoAuthorIdentity(adoPr.createdBy),
         branch,
         reviewStatus: REVIEW_STATUS.PENDING,
         status: PR_STATUS.ACTIVE,
@@ -2502,7 +2831,7 @@ async function checkLiveReviewStatus(pr, project) {
  *
  * Ensures the *authenticated reviewer's own* vote is positive (+10) when an agent
  * flips their verdict from request_changes → approved on a re-review. Mirrors the
- * existing target-branch re-approval pattern at engine/ado.js:837-852 (PUT
+ * existing target-branch re-approval pattern in engine/ado/index.js (PUT
  * reviewers/{myId} {vote:10}). Covers both:
  *   - prior negative vote (-5 wait-for-author, -10 rejected) → cleared to +10, and
  *   - prior neutral vote (0 — never cast, or reset by another path and never
@@ -2604,7 +2933,10 @@ async function resetReviewerNegativeVote(pr, project) {
  * buildStatus" semantics from issue #1233; the caller must trust the cached
  * value). When the stale set IS failing, buildStatus flips to 'failing' and
  * `buildStaleMergeCommit: true` is returned (Issue #2747) — a stale failing
- * signal is strictly more actionable than cache fallback.
+ * signal is strictly more actionable than cache fallback. When the newest built
+ * merge commit PASSED but the cached status is 'failing', buildStatus is 'none'
+ * (W-msaux21y00g79c48): the cached failure is provably older than that green
+ * build, so the caller must skip the build-fix instead of falling back to it.
  */
 async function checkLiveBuildAndConflict(pr, project) {
   try {
@@ -2668,6 +3000,14 @@ async function checkLiveBuildAndConflict(pr, project) {
               if (stale.buildStaleMergeCommit) {
                 buildStatus = stale.buildStatus;
                 buildStaleMergeCommit = true;
+              } else if (stale.supersededCachedFailure) {
+                // W-msaux21y00g79c48: the newest built merge commit passed, so
+                // the cached 'failing' the caller would otherwise fall back to
+                // is a superseded signal. Report 'none' (not null) so the
+                // pre-dispatch gate skips the build-fix and clears the cache
+                // instead of re-dispatching against a green branch. Not
+                // 'passing' — the current merge commit still has no build.
+                buildStatus = stale.buildStatus;
               }
               // else: leave buildStatus null — caller falls back to cached state (issue #1233).
             }
@@ -2710,6 +3050,9 @@ async function fetchAdoPrMetadata(prNum, adoOrg, adoProj, adoRepo, project) {
     description: pr.description || '',
     branch: stripRefsHeads(pr.sourceRefName),
     author: pr.createdBy?.displayName || '',
+    // Structured author identity (provider/id/descriptor/login/displayName/url)
+    // for callers that persist pr.author separately from pr.agent.
+    authorIdentity: shared.buildAdoAuthorIdentity(pr.createdBy),
     // W-mrezh0yb0007f733 — surface ADO's real creationDate so manual-link paths
     // can seed `pr.created` with the true value instead of link-time now().
     created: pr.creationDate || '',
@@ -2771,7 +3114,7 @@ async function getPrChangedFiles(project, prNumber) {
 
 /**
  * Fetch live PR and build status for a single PR number.
- * Used by engine/ado-status.js so agents can check CI without raw curl calls.
+ * Used by engine/ado/status.js so agents can check CI without raw curl calls.
  * Returns { prNumber, title, branch, status, reviewStatus, buildStatus,
  *           buildStatusStale?, buildStatusDetail?, buildErrorLog?,
  *           mergeConflict, url, project } or null on auth failure.
@@ -2988,7 +3331,7 @@ function _setAdoTokenAuthNoteWriterForTest(fn) {
 
 // ─── One-Shot Startup Reconciliation for Abandoned PRs (W-mp60tw0u000j3931) ───
 //
-// ADO equivalent of engine/github.js reconcileAbandonedPrs. Same shape:
+// ADO equivalent of engine/providers/github.js reconcileAbandonedPrs. Same shape:
 // per-(org, project, repo) base probe, cached for the duration of the pass;
 // then per-PR re-probe via adoFetch. ADO PRs use `prData.status` directly
 // ('active' | 'abandoned' | 'completed'), which we map back to PR_STATUS.
@@ -3126,6 +3469,9 @@ async function reconcileAbandonedPrs(config) {
             delete pr._consecutive404s;
             delete pr._404Count;
             delete pr._404FirstAt;
+            // W-msav5edk00g81710: the record left `abandoned` — drop the
+            // bounded-re-probe anchor with it.
+            if (upd.newStatus !== shared.PR_STATUS.ABANDONED) shared.clearPrAbandonedAt(pr);
             pr._reconciledAt = reconciledAt;
             pr._reconciledFrom = 'startup-pass';
           } else if (upd.action === 'confirm404') {
@@ -3177,6 +3523,7 @@ module.exports = {
   _resetAdoThrottle, // exported for testing
   _setAdoThrottleForTest, // exported for testing
   _setAdoTokenForTest, // exported for testing
+  _resetAdoMarkerSpoofGuardWarningForTest, // exported for testing
   _setAdoFetchForTest, // exported for testing
   _resetAdoFetchForTest, // exported for testing
   // Exported for unit tests — engine code MUST go through pollPrStatus / reconcilePrs.
@@ -3203,9 +3550,16 @@ module.exports = {
   // Issue #2747 — stale merge-commit classifier + auto-queue helpers, exported for unit tests.
   classifyBuildStatus,
   classifyStaleBuilds,
+  // W-msaux21y00g79c48 — newest-merge-commit narrowing for stale build sets.
+  selectNewestMergeCommitBuilds,
   isPrValidationBuild,
   shouldRequeueStaleBuild,
   PR_BUILD_REQUEUE_INTERVAL_MS,
+  // W-ms7kklp8002zad24 — draft-PR branch-policy build queueing, exported for unit tests.
+  extractDraftPrBuildDefinitionIds,
+  adoPolicyScopeMatches,
+  queueDraftPrValidationBuilds,
+  ADO_BUILD_POLICY_TYPE_ID,
   // #3758 — exported for unit tests of GitHub-only-config inertness.
   isGitHubProject,
   hasAdoProjectConfigured,