@yemi33/minions 0.1.2448 → 0.1.2449

package/engine/{abandoned-pr-reconciliation.js → providers/abandoned-pr-reconciliation.js}

@@ -1,14 +1,24 @@
 /**
- * engine/abandoned-pr-reconciliation.js — One-shot startup reconciliation pass
+ * engine/providers/abandoned-pr-reconciliation.js — One-shot startup reconciliation pass
  * for `abandoned` PRs. Pairs with W-mp5trwh60008386d's forward-looking 404
- * hardening in engine/github.js: that fix prevents *future* false-flips, but
+ * hardening in engine/providers/github.js: that fix prevents *future* false-flips, but
  * does nothing for PRs already wrongly marked `abandoned` before it shipped
  * (e.g. the 16 PRs hit by the 2026-05-14 gh-auth-flip incident).
  *
- * `pollPrStatus` only iterates PRs in `PR_POLLABLE_STATUSES = {active, linked}`
- * (engine/shared.js), so once a PR is `abandoned` the regular poll loop never
+ * `pollPrStatus` only iterates `PR_POLLABLE_STATUSES = {active, linked}`
+ * (engine/core/shared.js), so once a PR is `abandoned` the regular poll loop never
  * visits it again. This module is the explicit one-time re-probe.
  *
+ * ## Scope after W-msav5edk00g81710
+ *
+ * That WI gave abandoned records a BOUNDED re-probe window in the normal status
+ * poll (`shared.isPrPollable` + `engine.abandonedPrRepollWindowMs`, default 7
+ * days), because `abandoned` is the one terminal status a PR can legitimately
+ * leave — a reopened PR was otherwise invisible to the pollers forever. That
+ * covers the recent case. This module still owns everything OUTSIDE the window:
+ * historical false-flips and records with no usable abandonment anchor, which
+ * the poller deliberately fails CLOSED on.
+ *
  * ## Why one-shot, not periodic?
  *
  * Periodic re-probing of terminal-status PRs has real costs:
@@ -33,11 +43,11 @@
  *
  * ## Boot wiring
  *
- * Called from engine/cli.js between the recovery sweep and the initial tick.
+ * Called from engine/operations/cli.js between the recovery sweep and the initial tick.
  * Errors here must NOT block boot — the catch in cli.js logs and continues.
  */
 
-const shared = require('./shared');
+const shared = require('../core/shared');
 
 const { ENGINE_DEFAULTS, log, mutateEngineState, readEngineState } = shared;
 
@@ -70,7 +80,7 @@ async function runStartupReconciliation(config, options = {}) {
   }
 
   const github = options.githubModule || require('./github');
-  const ado = options.adoModule || require('./ado');
+  const ado = options.adoModule || require('../ado');
 
   // Pre-count abandoned PRs (only those without the confirmed-404 marker) so
   // the start-of-pass log line is meaningful. Wrapped in try/catch — the

package/engine/{comment-classifier.js → providers/comment-classifier.js}

@@ -1,12 +1,12 @@
 /**
- * engine/comment-classifier.js — P-f23classifier (F2 + F3)
+ * engine/providers/comment-classifier.js — P-f23classifier (F2 + F3)
  *
- * Host-agnostic PR-comment body classifiers shared by engine/github.js and
- * engine/ado.js pollers. Three pure body-only predicates:
+ * Host-agnostic PR-comment body classifiers shared by engine/providers/github.js and
+ * engine/ado/index.js pollers. Three pure body-only predicates:
  *
  *   isPreviewStatusBody(body) — Firebase / Appetize / Deploy / Preview bot
  *     signatures + Coverage/Build/Test/Deploy/Pipeline report headings +
- *     shields.io-style badge images. Ported from engine/github.js
+ *     shields.io-style badge images. Ported from engine/providers/github.js
  *     `_isPreviewStatusComment` body checks. ADO has no `user.type === 'bot'`
  *     equivalent, so only the narrower `_isPreviewStatusComment` helper keeps
  *     a GH-side bot-author gate; both pollers consume this body match directly.
@@ -35,24 +35,42 @@
  * so a copied marker cannot suppress actionable feedback.
  *
  * IMPORTANT — author identity is intentionally NOT consulted by the three
- * body-only predicates above. Callers MUST combine Minions marker matches with
- * their own identity gates before treating a comment as agent-authored:
+ * body-only predicates above. Callers resolve marker authorship through
+ * `classifyMarkerAuthorship()`, which combines `hasMinionsMarker()` with the
+ * caller's own host-specific identity signal:
  *
- *   GitHub: `comment.viewerDidAuthor === true`, backfilled via `gh api user`
- *           by engine/github.js `_backfillViewerDidAuthor`. The combined
- *           gate (`viewerDidAuthor && hasMinionsMarker`) is what makes the
- *           marker non-spoofable on GH.
+ *   GitHub: `comment.viewerDidAuthor`, backfilled via `gh api user` by
+ *           engine/providers/github.js `_backfillViewerDidAuthor`. Available
+ *           when the field is a strict boolean.
  *
  *   ADO:    `comment.author.uniqueName` (or displayName / id / descriptor)
  *           matched case-insensitively against
- *           `config.engine.minionsAdoIdentities`. ADO has no
- *           `viewerDidAuthor` equivalent, so a human pasting our marker
- *           would otherwise be misclassified as agent-authored. The combined
- *           gate (`isMinionsAdoAuthor && hasMinionsMarker`) is the
- *           structural complement that prevents marker spoofing.
+ *           `config.engine.minionsAdoIdentities`. ADO has no `viewerDidAuthor`
+ *           equivalent. Available only when that allowlist is non-empty.
  *
- * Marker-presence ALONE never classifies a comment as agent on either
- * platform — that contract is enforced at the caller, not here.
+ * W-msbf1kf6033f46cb — the identity gate distinguishes "identity says this is
+ * someone else" from "there is no identity signal at all", and those two must
+ * NOT collapse to the same answer:
+ *
+ *   - MISMATCH    → not agent-authored. This is the spoof guard at full
+ *                   strength: a human who pasted our marker keeps their
+ *                   feedback actionable.
+ *   - UNAVAILABLE → agent-authored (fail-SAFE). Previously this collapsed
+ *                   into "not agent-authored", which on ADO (where the
+ *                   allowlist is empty by default) gave the marker ZERO
+ *                   filtering power: every agent fix-summary was reclassified
+ *                   as new human feedback and re-triggered a fix dispatch on
+ *                   the same PR. Observed on ADO PR 5530936 as ten
+ *                   consecutive zero-change dispatches.
+ *
+ * The fail-safe direction is chosen on cost asymmetry. Failing open produced
+ * an unbounded, self-sustaining dispatch loop that burns agent capacity and
+ * is triggered by the engine's own traffic. Failing safe can at worst drop a
+ * human comment whose FIRST line is a verbatim copy of our HTML marker — a
+ * body shape `hasMinionsMarker` already restricts hard (own first line, no
+ * blockquote, no trailing content) and that carries no independent feedback
+ * signal. Callers that fail safe should say so out loud (see the ADO
+ * poller's one-time spoof-guard warning).
  */
 
 const { MINIONS_COMMENT_MARKER_RE } = require('./gh-comment');
@@ -210,10 +228,60 @@ function hasVerdictPrefix(body) {
   return _VERDICT_PREFIX_RE.test(String(body || ''));
 }
 
+// ── Marker authorship (marker + host identity signal) ──────────────────────
+//
+// W-msbf1kf6033f46cb — the single seam both pollers use to answer "did a
+// Minions agent author this comment?". Kept here rather than duplicated in
+// each poller so the ADO and GitHub answers cannot drift (see the
+// mirror-ado-github-poll-fix convention).
+const MARKER_AUTHORSHIP = Object.freeze({
+  // No engine-owned marker on the body's own first line.
+  NOT_MARKED: 'not-marked',
+  // Marker + the host identity signal confirms our own identity.
+  IDENTITY_CONFIRMED: 'identity-confirmed',
+  // Marker + the host identity signal names someone else → spoof guard.
+  IDENTITY_MISMATCH: 'identity-mismatch',
+  // Marker + no usable identity signal → fail-safe, trust the marker.
+  IDENTITY_UNAVAILABLE: 'identity-unavailable',
+});
+
+const _MARKER_AUTHORED_STATES = new Set([
+  MARKER_AUTHORSHIP.IDENTITY_CONFIRMED,
+  MARKER_AUTHORSHIP.IDENTITY_UNAVAILABLE,
+]);
+
+/**
+ * Resolve marker authorship for one comment.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.body               Raw comment body.
+ * @param {boolean} opts.identityAvailable  Whether the caller has a usable
+ *   identity signal at all (GH: viewerDidAuthor is a strict boolean;
+ *   ADO: config.engine.minionsAdoIdentities is non-empty).
+ * @param {boolean} opts.identityMatches    Whether that signal names us.
+ *   Ignored when `identityAvailable` is false.
+ * @returns {string} one of MARKER_AUTHORSHIP.
+ */
+function classifyMarkerAuthorship({ body, identityAvailable, identityMatches } = {}) {
+  if (!hasMinionsMarker(body)) return MARKER_AUTHORSHIP.NOT_MARKED;
+  if (identityAvailable !== true) return MARKER_AUTHORSHIP.IDENTITY_UNAVAILABLE;
+  return identityMatches === true
+    ? MARKER_AUTHORSHIP.IDENTITY_CONFIRMED
+    : MARKER_AUTHORSHIP.IDENTITY_MISMATCH;
+}
+
+/** True only for the two states that mean "a Minions agent wrote this". */
+function isMarkerAuthored(state) {
+  return _MARKER_AUTHORED_STATES.has(state);
+}
+
 module.exports = {
   isPreviewStatusBody,
   hasMinionsMarker,
   hasVerdictPrefix,
+  classifyMarkerAuthorship,
+  isMarkerAuthored,
+  MARKER_AUTHORSHIP,
   classifyNonActionableAutomationComment,
   NON_ACTIONABLE_AUTOMATION_REASONS,
 };

package/engine/{comment-format.js → providers/comment-format.js}

@@ -1,5 +1,5 @@
 /**
- * engine/comment-format.js — platform-neutral PR-comment body fragments.
+ * engine/providers/comment-format.js — platform-neutral PR-comment body fragments.
  *
  * Owns the platform-neutral Minions marker and brand-link formatting shared by
  * GitHub and Azure DevOps comment transports.
@@ -41,8 +41,8 @@ function linkifyBrandTrailer(text) {
 // ── Minions marker + neutral comment-body builder ───────────────────────────
 //
 // The hidden HTML-comment marker and the body composition (marker + harness
-// brand link) are platform-NEUTRAL: GitHub (engine/gh-comment.js) and
-// Azure DevOps (engine/ado-comment.js) both post the byte-identical body built
+// brand link) are platform-NEUTRAL: GitHub (engine/providers/gh-comment.js) and
+// Azure DevOps (engine/ado/comment.js) both post the byte-identical body built
 // here, so there is one builder and no drift. The host modules own only the
 // transport (gh CLI vs ADO REST) and host-specific validation (repo slug vs
 // org/project/repoId).
@@ -57,7 +57,7 @@ function linkifyBrandTrailer(text) {
 //   - model       concrete runtime execution model (optional)
 //   - no field may contain `--` (would close the HTML comment early)
 
-const { normalizeExecutionModel, UNKNOWN_MODEL } = require('./execution-model');
+const { normalizeExecutionModel, UNKNOWN_MODEL } = require('../core/execution-model');
 
 const AGENT_ID_RE = /^[a-z][a-z0-9-]{0,30}$/;
 const KIND_RE = /^[a-z][a-z0-9-]{0,30}$/;
@@ -218,7 +218,7 @@ module.exports = {
   linkifyBrandTrailer,
   stampExecutionModel,
   MINIONS_BRAND_URL,
-  // Neutral marker + body builder (consumed by gh-comment.js and ado-comment.js).
+  // Neutral marker + body builder (consumed by gh-comment.js and engine/ado/comment.js).
   buildMinionsCommentBody,
   parseMinionsMarker,
   MINIONS_COMMENT_MARKER,

package/engine/{gh-comment.js → providers/gh-comment.js}

@@ -1,6 +1,6 @@
 /**
- * engine/gh-comment.js — wraps `gh pr comment` / `gh pr review` with a hidden
- * HTML-comment marker so downstream classifiers (engine/github.js) can identify
+ * engine/providers/gh-comment.js — wraps `gh pr comment` / `gh pr review` with a hidden
+ * HTML-comment marker so downstream classifiers (engine/providers/github.js) can identify
  * minions-authored PR comments by structure rather than by body shape.
  *
  * Marker format (single line, ASCII):
@@ -28,7 +28,7 @@
  * backticks, or `$(…)`. Temp files are cleaned up in `finally`.
  *
  * Per-slug PAT routing (P-bfa2a): each public function resolves a per-slug
- * GitHub token via `engine/gh-token.js#resolveTokenForSlug(repo)` and threads
+ * GitHub token via `engine/providers/gh-token.js#resolveTokenForSlug(repo)` and threads
  * it into the spawned `gh` process via `env.GH_TOKEN`. When the slug has no
  * mapping in `engine.ghAccounts`, we fall back to the ambient `gh` identity
  * (inherited via `process.env`) and emit a one-shot `console.warn` per slug
@@ -46,15 +46,15 @@ const {
   linkifyBrandTrailer,
   MINIONS_BRAND_URL,
   // Neutral marker + body builder now lives in comment-format.js so the GitHub
-  // (this module) and ADO (engine/ado-comment.js) posters share one builder.
-  buildMinionsCommentBody, // re-export of engine/comment-format.js (neutral builder)
-  parseMinionsMarker, // re-export of engine/comment-format.js
-  MINIONS_COMMENT_MARKER, // re-export of engine/comment-format.js
-  MINIONS_COMMENT_MARKER_RE, // re-export of engine/comment-format.js
-  AGENT_ID_RE, // re-export of engine/comment-format.js
-  KIND_RE, // re-export of engine/comment-format.js
-  WORK_ITEM_ID_RE, // re-export of engine/comment-format.js
-  _buildMarker, // re-export of engine/comment-format.js
+  // (this module) and ADO (engine/ado/comment.js) posters share one builder.
+  buildMinionsCommentBody, // re-export of engine/providers/comment-format.js (neutral builder)
+  parseMinionsMarker, // re-export of engine/providers/comment-format.js
+  MINIONS_COMMENT_MARKER, // re-export of engine/providers/comment-format.js
+  MINIONS_COMMENT_MARKER_RE, // re-export of engine/providers/comment-format.js
+  AGENT_ID_RE, // re-export of engine/providers/comment-format.js
+  KIND_RE, // re-export of engine/providers/comment-format.js
+  WORK_ITEM_ID_RE, // re-export of engine/providers/comment-format.js
+  _buildMarker, // re-export of engine/providers/comment-format.js
 } = require('./comment-format');
 
 // Module-level dedupe set so the "no token mapping for <slug>" warning fires
@@ -65,7 +65,7 @@ const _warnedUnresolvedSlugs = new Set();
 
 // ── Validation (GitHub-specific) ─────────────────────────────────────────────
 // The marker field validators + neutral body builder now live in
-// engine/comment-format.js (shared with engine/ado-comment.js). Only the
+// engine/providers/comment-format.js (shared with engine/ado/comment.js). Only the
 // GitHub repo-slug + PR-number validators remain host-specific here.
 
 const REPO_SLUG_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
@@ -210,8 +210,8 @@ function postPrReviewComment({
 module.exports = {
   // Builders / parsers (pure functions — usable from anywhere)
   buildMinionsCommentBody,
-  linkifyBrandTrailer, // re-export of engine/comment-format.js for comment callers
-  MINIONS_BRAND_URL, // re-export of engine/comment-format.js for comment callers
+  linkifyBrandTrailer, // re-export of engine/providers/comment-format.js for comment callers
+  MINIONS_BRAND_URL, // re-export of engine/providers/comment-format.js for comment callers
   parseMinionsMarker,
   MINIONS_COMMENT_MARKER,
   MINIONS_COMMENT_MARKER_RE,

package/engine/{gh-token.js → providers/gh-token.js}

@@ -1,5 +1,5 @@
 /**
- * engine/gh-token.js — Per-slug GitHub PAT resolution.
+ * engine/providers/gh-token.js — Per-slug GitHub PAT resolution.
  *
  * Resolves the PAT for a given owner/repo slug by consulting
  * `config.engine.ghAccounts` and shelling out to `gh auth token --user <account>
@@ -13,14 +13,14 @@
  *   4. null → caller falls back to the ambient `gh` identity, preserving
  *      legacy behavior for unmapped slugs.
  *
- * Mirrors the shape of `engine/ado-token.js` (separate sync token acquisition
+ * Mirrors the shape of `engine/ado/token.js` (separate sync token acquisition
  * helper, in-memory cache, narrow exec timeout). Tests can prime the cache
  * via `_setTokenForTest(slug, token)` and clear it via `_clearTokenCache()`.
  */
 
 const { execFileSync } = require('child_process');
 const path = require('path');
-const shared = require('./shared');
+const shared = require('../core/shared');
 const { safeJsonObj, MINIONS_DIR, log } = shared;
 
 const TOKEN_TTL_MS = 30 * 60 * 1000; // 30 minutes
@@ -112,7 +112,7 @@ function resolveTokenForSlug(slug, opts = {}) {
 /**
  * Resolve a GitHub PAT for a named account directly (bypassing slug→account
  * mapping). Used by the projectless PR resolver's unknown-slug fallback
- * (engine/pr-resolve.js) to try each authed account in turn WITHOUT touching
+ * (engine/providers/pr-resolve.js) to try each authed account in turn WITHOUT touching
  * the global active `gh auth` profile. Returns the token string or null.
  */
 function tokenForAccount(account, opts = {}) {