@yemi33/minions 0.1.1901 → 0.1.1903

package/engine/github.js

@@ -88,6 +88,85 @@ function _isNonActionableComment(c, config = {}) {
   return false;
 }
 
+// W-mp2h696g000a7bc0 — Detect agent self-review-declined no-op comments.
+//
+// Per the documented contract (memory `subject: self-review`, docs/completion-reports.md:83-105):
+// when an agent is dispatched to review a PR they implemented, they post a `gh pr comment`
+// (no `VERDICT:` line) explaining the recusal and complete with `noop:true, verdict:null,
+// needs_rerun:true`. Because `gh` authenticates as the shared PAT user (`yemi33`), the
+// classifier can't tell the noop comment from a real human comment by author alone.
+//
+// Detection requires a stronger signal than author identity. Returns true only when BOTH:
+//   1. Body has NO `VERDICT:` line (we never want to swallow a real verdict comment), AND
+//   2. EITHER the body contains the canonical "Self-review declined" phrase AND references
+//      a dispatch id matching `<agent>-<type>-<uid>` that resolves to a same-agent
+//      review/implement dispatch in the completed history,
+//      OR the most recent review dispatch on this PR was assigned to the same agent as the
+//      PR author and completed with the noop:true / verdict:null / needs_rerun:true contract.
+//
+// This is a narrow allowlist for the noop pattern — generic PAT-user comments still flow
+// through `_isNonActionableComment` and trigger `humanFeedback.pendingFix=true` as before.
+function _isAgentSelfReviewDeclinedComment(c, { pr, dispatch } = {}) {
+  if (!c || !pr) return false;
+  const body = String(c.body || '');
+  if (!body) return false;
+  if (_hasMinionsReviewVerdict(body)) return false;
+
+  const prAuthorAgent = String(pr.agent || '').toLowerCase();
+  if (!prAuthorAgent) return false;
+
+  const completed = (dispatch && Array.isArray(dispatch.completed)) ? dispatch.completed : [];
+  const isNoopContract = (sc) => {
+    if (!sc || typeof sc !== 'object') return false;
+    if (sc.noop !== true && sc.noop !== 'true') return false;
+    if (sc.verdict !== null && sc.verdict !== undefined && sc.verdict !== '') return false;
+    if (sc.needs_rerun !== true && sc.needsRerun !== true) return false;
+    return true;
+  };
+
+  // Signal A — explicit "Self-review declined" phrase + verifiable dispatch id pointing
+  // at a same-agent review/implement/fix dispatch in the completed history.
+  const phraseMatch = /self[\s\-_]+review\s+declined/i.test(body);
+  if (phraseMatch) {
+    const dispatchIdMatches = body.match(/\b[a-z][a-z0-9]*-[a-z][a-z0-9]*-[a-z0-9]{8,}\b/g) || [];
+    for (const id of dispatchIdMatches) {
+      const entry = completed.find(d => d && d.id === id);
+      if (!entry) continue;
+      const agent = String(entry.agent || '').toLowerCase();
+      const t = String(entry.type || '').toLowerCase();
+      if (agent !== prAuthorAgent) continue;
+      if (t === 'review' || t === 'implement' || t === 'implement-large' || t === 'fix') {
+        return true;
+      }
+    }
+  }
+
+  // Signal B — most recent review dispatch on this PR was assigned to the PR author
+  // and completed with the documented noop contract. Catches the case where the agent
+  // forgot the canonical phrase but the completion-report contract still flags a noop.
+  const prId = String(pr.id || '');
+  const prNumberRaw = pr.prNumber;
+  const prNumber = prNumberRaw == null ? null : Number(prNumberRaw);
+  const reviewDispatches = completed.filter(d => {
+    if (!d || String(d.type || '').toLowerCase() !== 'review') return false;
+    const dpr = d.meta && d.meta.pr;
+    if (!dpr) return false;
+    if (prId && String(dpr.id || '') === prId) return true;
+    if (prNumber != null && Number(dpr.prNumber) === prNumber) return true;
+    return false;
+  });
+  if (reviewDispatches.length === 0) return false;
+  reviewDispatches.sort((a, b) => {
+    const ta = String(a.completed_at || a.created_at || '');
+    const tb = String(b.completed_at || b.created_at || '');
+    return tb.localeCompare(ta);
+  });
+  const latest = reviewDispatches[0];
+  if (!latest) return false;
+  if (String(latest.agent || '').toLowerCase() !== prAuthorAgent) return false;
+  return isNoopContract(latest.structuredCompletion);
+}
+
 // ─── Per-Repo Poll Backoff ──────────────────────────────────────────────────
 // Tracks consecutive poll failures per repo slug to avoid spamming logs when
 // a repo is inaccessible. Backoff doubles each failure: 2min, 4min, 8min, 16min, max 30min.
@@ -417,6 +496,74 @@ async function pollPrStatus(config) {
       updated = true;
     }
 
+    // P-w1a3f9b2 — Phase 1.1: plumb mergeable / isDraft / mergeStateStatus /
+    // headRefOid onto the PR object so watches captureState (engine/watches.js)
+    // and future predicates (Phase 2.1: head-commit-change, mergeable-flipped,
+    // ready-for-merge, draft-flipped) can read them. We mirror GitHub's
+    // tri-state contract for `mergeable` (true|false|null — see
+    // checkLiveBuildAndConflict comments above):
+    //   - true  → GitHub computed: mergeable
+    //   - false → GitHub computed: conflicts
+    //   - null  → GitHub still computing — preserve null verbatim, do NOT
+    //             substitute the cached value (predicates treat null as "no
+    //             signal" and won't fire transitions involving null).
+    // `headRefOid` is an alias of `headSha` for spec parity (GitHub's GraphQL
+    // schema and many tools name it `headRefOid`); both stay in sync.
+    if (prData.head?.sha && pr.headRefOid !== prData.head.sha) {
+      pr.headRefOid = prData.head.sha;
+      updated = true;
+    }
+    const newMergeable = prData.mergeable === true ? true
+      : prData.mergeable === false ? false
+      : null;
+    if (pr.mergeable !== newMergeable) {
+      pr.mergeable = newMergeable;
+      updated = true;
+    }
+    const newIsDraft = prData.draft === true;
+    if (pr.isDraft !== newIsDraft) {
+      pr.isDraft = newIsDraft;
+      updated = true;
+    }
+    const newMergeStateStatus = typeof prData.mergeable_state === 'string' && prData.mergeable_state
+      ? prData.mergeable_state
+      : null;
+    if ((pr.mergeStateStatus || null) !== newMergeStateStatus) {
+      pr.mergeStateStatus = newMergeStateStatus;
+      updated = true;
+    }
+
+    // P-w3a7b9c4 — Phase 1.3: optional gated `behindBy` field via GitHub
+    // /compare/{base}...{head} API. Each call costs one extra GitHub
+    // request, so it's gated behind the opt-in
+    // `config.engine.watchesIncludeBehindBy` flag. The natural per-tick
+    // budget IS the prPollStatusEvery cadence (default ~12 ticks) — by
+    // living inside pollPrStatus this fetch inherits that gate without
+    // needing a separate counter. When skipped (flag off, PR closed,
+    // missing refs, cross-repo fork, or compare-API error), behindBy is
+    // explicitly set to null so the `behind-master` predicate
+    // (engine/watches.js BEHIND_MASTER) treats it as "no signal" and does
+    // not over-fire on legacy / stale state. ADO PRs are handled in
+    // engine/ado.js with the same null contract.
+    const includeBehindBy = config.engine?.watchesIncludeBehindBy === true;
+    let newBehindBy = null;
+    if (includeBehindBy && prData.state === 'open' && prData.base?.ref && prData.head?.sha) {
+      // Same-repo PRs only — cross-repo (forked) compare needs `owner:branch`
+      // syntax which we don't normalize here. Treat fork PRs as "no signal".
+      const baseRepo = prData.base?.repo?.full_name || '';
+      const headRepo = prData.head?.repo?.full_name || '';
+      if (baseRepo && headRepo && baseRepo === headRepo) {
+        const cmp = await ghApi(`/compare/${encodeURIComponent(prData.base.ref)}...${encodeURIComponent(prData.head.sha)}`, slug);
+        if (cmp && cmp !== GH_NOT_FOUND && typeof cmp.behind_by === 'number') {
+          newBehindBy = cmp.behind_by;
+        }
+      }
+    }
+    if ((pr.behindBy ?? null) !== newBehindBy) {
+      pr.behindBy = newBehindBy;
+      updated = true;
+    }
+
     if (pr.status !== newStatus) {
       log('info', `PR ${pr.id} status: ${pr.status} → ${newStatus}`);
       pr.status = newStatus;
@@ -628,6 +775,14 @@ async function pollPrStatus(config) {
 // ─── Poll Human Comments on PRs ─────────────────────────────────────────────
 
 async function pollPrHumanComments(config) {
+  // Load dispatch state once per poll cycle (cached for ~2s by queries.getDispatch).
+  // Used by `_isAgentSelfReviewDeclinedComment` to verify dispatch ids referenced in
+  // candidate noop comments belong to the PR author.
+  const queries = require('./queries');
+  const dispatch = (() => {
+    try { return queries.getDispatch(); }
+    catch { return { pending: [], active: [], completed: [] }; }
+  })();
   const totalUpdated = await forEachActiveGhPr(config, async (project, pr, prNum, slug) => {
     // Get issue comments (general PR comments)
     const comments = await ghApi(`/issues/${prNum}/comments`, slug);
@@ -653,7 +808,12 @@ async function pollPrHumanComments(config) {
     for (const c of allComments) {
       const date = c.created_at || c.updated_at || '';
       const dateMs = date ? new Date(date).getTime() : 0;
-      const isNonActionable = _isNonActionableComment(c, config);
+      // W-mp2h696g000a7bc0 — agent self-review-declined no-op comments are posted via
+      // `gh pr comment` and authenticate as the shared PAT user, so author identity alone
+      // can't distinguish them from real human feedback. The narrow allowlist check uses
+      // the comment body + dispatch history to identify the documented noop pattern.
+      const isNonActionable = _isNonActionableComment(c, config)
+        || _isAgentSelfReviewDeclinedComment(c, { pr, dispatch });
       if (dateMs) allCommentDates.push(date);
       if (isNonActionable) continue;
       const entry = {
@@ -975,5 +1135,6 @@ module.exports = {
   _hasMinionsReviewVerdict, // exported for testing
   _isAgentComment, // exported for testing
   _isNonActionableComment, // exported for testing
+  _isAgentSelfReviewDeclinedComment, // exported for testing
   _isPreviewStatusComment, // exported for testing
 };

package/engine/queries.js

@@ -553,6 +553,9 @@ function getAgents(config) {
     return {
       ...a, runtime, status: s.status, lastAction,
       currentTask: (s.task || '').slice(0, 200),
+      // P-w2c8d1e7 — Phase 1.2: surface the active dispatch id so watch
+      // captureState can snapshot it for currentDispatchId-aware predicates.
+      currentDispatchId: s.dispatch_id || null,
       resultSummary: (s.resultSummary || '').slice(0, 500),
       started_at: s.started_at || null,
       completed_at: s.completed_at || null,

package/engine/safe-expr.js

@@ -0,0 +1,350 @@
+/**
+ * engine/safe-expr.js — Hand-rolled recursive-descent expression evaluator.
+ *
+ * Phase 3.1 of feat/plan-resilient-watches (P-w6f4a3e8). Used by watch action
+ * guards (P-w7c5d8b3) and predicate-based watches (Phase 2.x) to evaluate
+ * user-supplied boolean expressions against a runtime context such as
+ * `{ target, newState, previousState, condition, ... }`.
+ *
+ * Hard rules — DO NOT REGRESS:
+ *   1. Never use `eval()` or `new Function()`. Both are RCE vectors. The unit
+ *      test suite greps the source of this module to enforce this.
+ *   2. Never throw out of `evaluate()`. Watches must keep ticking even if a
+ *      user types a malformed predicate. On any parse or evaluation error,
+ *      log a warn tagged `[safe-expr]` and return `false`.
+ *   3. Identifier resolution does an own-property walk only. Reaching
+ *      `Object.prototype` (`toString`, `constructor`, `__proto__`, ...) is a
+ *      sandbox-escape vector for an attacker who controls a watch expression.
+ *
+ * Grammar (lowest to highest precedence):
+ *   expression  -> or
+ *   or          -> and ('||' and)*
+ *   and         -> equality ('&&' equality)*
+ *   equality    -> comparison (('==='|'=='|'!=='|'!=') comparison)*
+ *   comparison  -> unary (('<='|'<'|'>='|'>') unary)*
+ *   unary       -> '!' unary | primary
+ *   primary     -> NUMBER | STRING | true | false | null | undefined
+ *                | IDENT ('.' IDENT)* | '(' expression ')'
+ *
+ * Top-level result is coerced via `Boolean(...)` so callers always see a
+ * boolean (the canonical guard contract: truthy = run, falsy = skip).
+ */
+
+'use strict';
+
+// ── Lexer ────────────────────────────────────────────────────────────────────
+
+const TOK = {
+  NUMBER: 'NUMBER',
+  STRING: 'STRING',
+  IDENT: 'IDENT',
+  BOOLEAN: 'BOOLEAN',
+  NULL: 'NULL',
+  UNDEFINED: 'UNDEFINED',
+  DOT: 'DOT',
+  LPAREN: 'LPAREN',
+  RPAREN: 'RPAREN',
+  EQ_STRICT: 'EQ_STRICT',
+  NEQ_STRICT: 'NEQ_STRICT',
+  EQ_LOOSE: 'EQ_LOOSE',
+  NEQ_LOOSE: 'NEQ_LOOSE',
+  LT: 'LT',
+  LTE: 'LTE',
+  GT: 'GT',
+  GTE: 'GTE',
+  AND: 'AND',
+  OR: 'OR',
+  NOT: 'NOT',
+  MINUS: 'MINUS',
+  EOF: 'EOF',
+};
+
+function _isDigit(c) { return c >= '0' && c <= '9'; }
+function _isIdentStart(c) {
+  return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || c === '_' || c === '$';
+}
+function _isIdentBody(c) { return _isIdentStart(c) || _isDigit(c); }
+
+function tokenize(src) {
+  const tokens = [];
+  const len = src.length;
+  let i = 0;
+
+  while (i < len) {
+    const c = src[i];
+
+    // Whitespace
+    if (c === ' ' || c === '\t' || c === '\n' || c === '\r') { i++; continue; }
+
+    // String literals (single or double quoted, with basic backslash escapes)
+    if (c === '"' || c === "'") {
+      const quote = c;
+      let j = i + 1;
+      let val = '';
+      while (j < len && src[j] !== quote) {
+        if (src[j] === '\\' && j + 1 < len) {
+          const next = src[j + 1];
+          if (next === 'n') val += '\n';
+          else if (next === 't') val += '\t';
+          else if (next === 'r') val += '\r';
+          else if (next === '\\') val += '\\';
+          else if (next === quote) val += quote;
+          else val += next;
+          j += 2;
+        } else {
+          val += src[j];
+          j++;
+        }
+      }
+      if (j >= len) throw new Error(`Unterminated string literal starting at ${i}`);
+      tokens.push({ type: TOK.STRING, value: val });
+      i = j + 1;
+      continue;
+    }
+
+    // Number literals (positive only — unary minus handled in parsePrimary)
+    if (_isDigit(c)) {
+      let j = i;
+      let sawDot = false;
+      while (j < len) {
+        const ch = src[j];
+        if (_isDigit(ch)) { j++; continue; }
+        if (ch === '.' && !sawDot) { sawDot = true; j++; continue; }
+        break;
+      }
+      const numStr = src.slice(i, j);
+      const num = Number(numStr);
+      if (Number.isNaN(num)) throw new Error(`Invalid number "${numStr}" at ${i}`);
+      tokens.push({ type: TOK.NUMBER, value: num });
+      i = j;
+      continue;
+    }
+
+    // Identifiers and keywords
+    if (_isIdentStart(c)) {
+      let j = i;
+      while (j < len && _isIdentBody(src[j])) j++;
+      const word = src.slice(i, j);
+      if (word === 'true') tokens.push({ type: TOK.BOOLEAN, value: true });
+      else if (word === 'false') tokens.push({ type: TOK.BOOLEAN, value: false });
+      else if (word === 'null') tokens.push({ type: TOK.NULL, value: null });
+      else if (word === 'undefined') tokens.push({ type: TOK.UNDEFINED, value: undefined });
+      else tokens.push({ type: TOK.IDENT, value: word });
+      i = j;
+      continue;
+    }
+
+    // Multi-char operators (longest match first)
+    if (c === '=' && src[i + 1] === '=' && src[i + 2] === '=') { tokens.push({ type: TOK.EQ_STRICT }); i += 3; continue; }
+    if (c === '!' && src[i + 1] === '=' && src[i + 2] === '=') { tokens.push({ type: TOK.NEQ_STRICT }); i += 3; continue; }
+    if (c === '=' && src[i + 1] === '=') { tokens.push({ type: TOK.EQ_LOOSE }); i += 2; continue; }
+    if (c === '!' && src[i + 1] === '=') { tokens.push({ type: TOK.NEQ_LOOSE }); i += 2; continue; }
+    if (c === '<' && src[i + 1] === '=') { tokens.push({ type: TOK.LTE }); i += 2; continue; }
+    if (c === '>' && src[i + 1] === '=') { tokens.push({ type: TOK.GTE }); i += 2; continue; }
+    if (c === '&' && src[i + 1] === '&') { tokens.push({ type: TOK.AND }); i += 2; continue; }
+    if (c === '|' && src[i + 1] === '|') { tokens.push({ type: TOK.OR }); i += 2; continue; }
+
+    // Single-char operators
+    if (c === '<') { tokens.push({ type: TOK.LT }); i++; continue; }
+    if (c === '>') { tokens.push({ type: TOK.GT }); i++; continue; }
+    if (c === '!') { tokens.push({ type: TOK.NOT }); i++; continue; }
+    if (c === '(') { tokens.push({ type: TOK.LPAREN }); i++; continue; }
+    if (c === ')') { tokens.push({ type: TOK.RPAREN }); i++; continue; }
+    if (c === '.') { tokens.push({ type: TOK.DOT }); i++; continue; }
+    if (c === '-') { tokens.push({ type: TOK.MINUS }); i++; continue; }
+
+    throw new Error(`Unexpected character '${c}' at ${i}`);
+  }
+
+  tokens.push({ type: TOK.EOF });
+  return tokens;
+}
+
+// ── Parser (recursive descent) ───────────────────────────────────────────────
+
+function parse(tokens) {
+  let pos = 0;
+  const peek = () => tokens[pos];
+  const match = (...types) => types.includes(tokens[pos].type);
+
+  function parseOr() {
+    let left = parseAnd();
+    while (match(TOK.OR)) {
+      pos++;
+      const right = parseAnd();
+      left = { kind: 'logical', op: '||', left, right };
+    }
+    return left;
+  }
+
+  function parseAnd() {
+    let left = parseEquality();
+    while (match(TOK.AND)) {
+      pos++;
+      const right = parseEquality();
+      left = { kind: 'logical', op: '&&', left, right };
+    }
+    return left;
+  }
+
+  function parseEquality() {
+    let left = parseComparison();
+    while (match(TOK.EQ_STRICT, TOK.NEQ_STRICT, TOK.EQ_LOOSE, TOK.NEQ_LOOSE)) {
+      const op = tokens[pos++].type;
+      const right = parseComparison();
+      left = { kind: 'binary', op, left, right };
+    }
+    return left;
+  }
+
+  function parseComparison() {
+    let left = parseUnary();
+    while (match(TOK.LT, TOK.LTE, TOK.GT, TOK.GTE)) {
+      const op = tokens[pos++].type;
+      const right = parseUnary();
+      left = { kind: 'binary', op, left, right };
+    }
+    return left;
+  }
+
+  function parseUnary() {
+    if (match(TOK.NOT)) {
+      pos++;
+      return { kind: 'not', expr: parseUnary() };
+    }
+    return parsePrimary();
+  }
+
+  function parsePrimary() {
+    const tok = peek();
+
+    // Unary minus is only supported as a prefix on a numeric literal — we have
+    // no arithmetic operators, so '-' anywhere else is a parse error.
+    if (tok.type === TOK.MINUS) {
+      pos++;
+      const next = peek();
+      if (next.type !== TOK.NUMBER) throw new Error(`Expected number after '-'`);
+      pos++;
+      return { kind: 'literal', value: -next.value };
+    }
+
+    if (
+      tok.type === TOK.NUMBER ||
+      tok.type === TOK.STRING ||
+      tok.type === TOK.BOOLEAN ||
+      tok.type === TOK.NULL ||
+      tok.type === TOK.UNDEFINED
+    ) {
+      pos++;
+      return { kind: 'literal', value: tok.value };
+    }
+
+    if (tok.type === TOK.IDENT) {
+      pos++;
+      const segments = [tok.value];
+      while (match(TOK.DOT)) {
+        pos++;
+        const next = peek();
+        if (next.type !== TOK.IDENT) throw new Error(`Expected identifier after '.'`);
+        pos++;
+        segments.push(next.value);
+      }
+      return { kind: 'path', segments };
+    }
+
+    if (tok.type === TOK.LPAREN) {
+      pos++;
+      const expr = parseOr();
+      if (peek().type !== TOK.RPAREN) throw new Error(`Expected ')'`);
+      pos++;
+      return expr;
+    }
+
+    throw new Error(`Unexpected token ${tok.type}`);
+  }
+
+  const ast = parseOr();
+  if (peek().type !== TOK.EOF) {
+    throw new Error(`Unexpected trailing token ${peek().type}`);
+  }
+  return ast;
+}
+
+// ── Evaluator ────────────────────────────────────────────────────────────────
+
+function _resolvePath(segments, ctx) {
+  let cur = ctx;
+  for (const seg of segments) {
+    if (cur == null) return undefined;
+    // Own-property walk only. Reaching Object.prototype (toString,
+    // constructor, __proto__, ...) is a sandbox-escape vector for any
+    // attacker who controls the expression string.
+    if (!Object.prototype.hasOwnProperty.call(cur, seg)) return undefined;
+    cur = cur[seg];
+  }
+  return cur;
+}
+
+function _evalNode(node, ctx) {
+  switch (node.kind) {
+    case 'literal':
+      return node.value;
+    case 'path':
+      return _resolvePath(node.segments, ctx);
+    case 'not':
+      return !_evalNode(node.expr, ctx);
+    case 'logical': {
+      const left = _evalNode(node.left, ctx);
+      if (node.op === '&&') return left ? _evalNode(node.right, ctx) : left;
+      if (node.op === '||') return left ? left : _evalNode(node.right, ctx);
+      return false;
+    }
+    case 'binary': {
+      const l = _evalNode(node.left, ctx);
+      const r = _evalNode(node.right, ctx);
+      switch (node.op) {
+        case TOK.EQ_STRICT: return l === r;
+        case TOK.NEQ_STRICT: return l !== r;
+        case TOK.EQ_LOOSE: return l == r;   // intentional loose equality
+        case TOK.NEQ_LOOSE: return l != r;  // intentional loose equality
+        case TOK.LT: return l < r;
+        case TOK.LTE: return l <= r;
+        case TOK.GT: return l > r;
+        case TOK.GTE: return l >= r;
+        default: return false;
+      }
+    }
+    default:
+      return false;
+  }
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+function evaluate(exprString, context) {
+  if (typeof exprString !== 'string' || exprString.trim() === '') {
+    console.warn(`[safe-expr] invalid expression (expected non-empty string): ${JSON.stringify(exprString)}`);
+    return false;
+  }
+
+  let ast;
+  try {
+    const tokens = tokenize(exprString);
+    ast = parse(tokens);
+  } catch (err) {
+    console.warn(`[safe-expr] parse error in "${exprString}": ${err.message}`);
+    return false;
+  }
+
+  let result;
+  try {
+    result = _evalNode(ast, context == null ? {} : context);
+  } catch (err) {
+    console.warn(`[safe-expr] evaluation error in "${exprString}": ${err.message}`);
+    return false;
+  }
+
+  return Boolean(result);
+}
+
+module.exports = { evaluate };

package/engine/shared.js

@@ -1095,6 +1095,7 @@ const ENGINE_DEFAULTS = {
   ghPollEnabled: true, // poll GitHub PR status, comments, and reconciliation on each tick cycle
   prPollStatusEvery: 12,   // poll PR build/review/merge status every N ticks for both ADO and GitHub (~12 min at default interval)
   prPollCommentsEvery: 12, // poll PR human comments every N ticks for both ADO and GitHub (~12 min at default interval)
+  watchesIncludeBehindBy: false, // opt-in: when true, GitHub PR poll calls /compare/{base}...{head} once per pr per pollPrStatusEvery cadence to populate pr.behindBy (powers the `behind-master` watch predicate). Off by default to avoid the extra API call. ADO PRs always get null (no commit-graph walk yet).
   autoCompletePrs: false, // auto-merge PRs when builds green + review approved (opt-in)
   prMergeMethod: 'squash', // merge method: squash, merge, rebase
   ignoredCommentAuthors: [], // comments from these authors are auto-closed and never trigger fixes
@@ -1589,13 +1590,50 @@ const WATCH_CONDITION = {
   ENABLED: 'enabled',               // schedule enabled
   DISABLED: 'disabled',             // schedule disabled
   ACTIVITY_CHANGE: 'activity-change', // agent transitioned status (e.g. idle → working)
+  // ── P-w4e2f6a1 — Phase 2.1: PR predicate conditions ──────────────────────
+  // See engine/watches.js PR target type for trigger semantics.
+  HEAD_COMMIT_CHANGE: 'head-commit-change', // PR headRefOid advanced (new push)
+  MERGEABLE_FLIPPED: 'mergeable-flipped',   // mergeable transitioned between true↔false (NOT involving null)
+  READY_FOR_MERGE: 'ready-for-merge',       // canonical compound: active+approved+passing+mergeable+!draft
+  BEHIND_MASTER: 'behind-master',           // pr.behindBy > 0 (treats null/undefined as not-behind)
+  DRAFT_FLIPPED: 'draft-flipped',           // isDraft transitioned between true↔false
+  // ── P-w5b8d2c9 — Phase 2.2: work-item / plan / pipeline predicates ───────
+  // See engine/watches.js for trigger semantics. Counters (_unchangedTicks,
+  // _stuckStageTicks) are computed inside captureState by comparing the
+  // freshly-captured snapshot against prevState — see _captureState which
+  // now passes prevState as the 2nd arg.
+  STALLED: 'stalled',                       // work-item: no captureState change for N ticks (default WATCH_STALLED_DEFAULT_TICKS)
+  RETRY_LIMIT_REACHED: 'retry-limit-reached', // work-item: _retryCount >= ENGINE_DEFAULTS.maxRetries
+  DEPENDENCY_MET: 'dependency-met',         // work-item: _pendingReason transitioned away from 'dependency_unmet'
+  ALL_ITEMS_DONE: 'all-items-done',         // plan: items_done === items_total && items_total > 0
+  ITEM_FAILED_N_TIMES: 'item-failed-n-times', // plan: any missing_features[*]._retryCount >= ENGINE_DEFAULTS.maxRetries
+  STAGE_ADVANCED: 'stage-advanced',         // pipeline: current_stage_id changed within same runId
+  STUCK_IN_STAGE: 'stuck-in-stage',         // pipeline: current_stage_id unchanged for N ticks (default WATCH_STUCK_STAGE_DEFAULT_TICKS)
 };
+// ── P-w5b8d2c9 — Phase 2.2: tick thresholds ────────────────────────────────
+// Default check interval is 5min (DEFAULT_WATCH_INTERVAL); 12 unchanged checks
+// ≈ 60 minutes. Spec: Math.ceil(60 / 5) = 12 tick-equivalents. Hard-coded
+// today; per-watch override may follow in a later phase.
+const WATCH_STALLED_DEFAULT_TICKS = 12;
+const WATCH_STUCK_STAGE_DEFAULT_TICKS = 12;
 // Absolute conditions auto-expire on first trigger when stopAfter=0 (fire-once semantics).
 // Change-based conditions (status-change, any, *-change) run forever when stopAfter=0.
 const WATCH_ABSOLUTE_CONDITIONS = new Set([
   WATCH_CONDITION.MERGED, WATCH_CONDITION.BUILD_FAIL, WATCH_CONDITION.BUILD_PASS,
   WATCH_CONDITION.COMPLETED, WATCH_CONDITION.FAILED,
   WATCH_CONDITION.CONCLUDED, WATCH_CONDITION.APPROVED, WATCH_CONDITION.REJECTED,
+  // ready-for-merge is a compound state assertion (true at moment of check) —
+  // fire-once when stopAfter=0 so the watch doesn't re-fire each tick while
+  // the PR sits idle in the ready state.
+  WATCH_CONDITION.READY_FOR_MERGE,
+  // ── P-w5b8d2c9 — Phase 2.2: state-assertion conditions that should
+  // fire-once when stopAfter=0. retry-limit-reached / all-items-done /
+  // item-failed-n-times are compound state assertions ("this is true right
+  // now"); without auto-expiry they would re-fire every tick while the
+  // condition holds.
+  WATCH_CONDITION.RETRY_LIMIT_REACHED,
+  WATCH_CONDITION.ALL_ITEMS_DONE,
+  WATCH_CONDITION.ITEM_FAILED_N_TIMES,
 ]);
 // Built-in follow-up action types invoked by the engine when a watch fires.
 // The action registry in engine/watch-actions.js is the source of truth; these
@@ -1607,6 +1645,7 @@ const WATCH_ACTION_TYPE = {
   DISPATCH_WORK_ITEM: 'dispatch-work-item',
   RUN_SKILL: 'run-skill',
   WEBHOOK: 'webhook',
+  MINIONS_API: 'minions-api',
   CANCEL_WORK_ITEM: 'cancel-work-item',
   TRIGGER_PIPELINE: 'trigger-pipeline',
   ARCHIVE_PLAN: 'archive-plan',
@@ -3561,6 +3600,7 @@ module.exports = {
   backfillProjectWorkSourceDefaults,
   WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, DISPATCH_RESULT, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS, WATCH_ACTION_TYPE,
+  WATCH_STALLED_DEFAULT_TICKS, WATCH_STUCK_STAGE_DEFAULT_TICKS,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,
   FAILURE_CLASS, ESCALATION_POLICY, COMPLETION_FIELDS,
   DEFAULT_AGENT_METRICS,