@yemi33/minions 0.1.1902 → 0.1.1903

package/engine/watches.js

@@ -34,6 +34,13 @@ function _watchesPath() { return path.join(shared.MINIONS_DIR, 'engine', 'watche
 // so watches are checked every N ticks where N = ceil(interval / tickInterval).
 const DEFAULT_WATCH_INTERVAL = 300000;
 
+// P-w12d8f3a — Phase 6.2: per-watch evaluation history is capped at 25
+// entries (oldest-first). Bounded to keep watches.json compact:
+// 25 entries × ~200 bytes × 100 watches ≈ 500 KB ceiling. History entries
+// never contain full state snapshots — only the trigger reason — per the
+// "history is small and bounded" design principle.
+const WATCH_HISTORY_MAX = 25;
+
 /** Find a PR by target (prNumber, canonical ID, or display ID). */
 function findPrByTarget(pullRequests, target) {
   const t = String(target);
@@ -100,7 +107,7 @@ function getWatches() {
  * @param {object} opts - Watch definition
  * @returns {object} - Created watch
  */
-function createWatch({ target, targetType, condition, interval, owner, description, project, notify, stopAfter, onNotMet, action }) {
+function createWatch({ target, targetType, condition, interval, owner, description, project, notify, stopAfter, onNotMet, action, requires }) {
   if (!target) throw new Error('target is required');
   if (!targetType || !TARGET_TYPES[targetType]) {
     throw new Error(`targetType must be one of: ${Object.keys(TARGET_TYPES).sort().join(', ')}`);
@@ -113,6 +120,11 @@ function createWatch({ target, targetType, condition, interval, owner, descripti
     const actionErr = watchActions.validateAction(action);
     if (actionErr) throw new Error(actionErr);
   }
+  // P-w10b6e2d — Phase 5: validate optional requires[] cross-target join.
+  if (requires !== undefined && requires !== null) {
+    const reqErr = _validateRequires(requires);
+    if (reqErr) throw new Error(reqErr);
+  }
 
   const watch = {
     id: 'watch-' + uid(),
@@ -128,10 +140,20 @@ function createWatch({ target, targetType, condition, interval, owner, descripti
     stopAfter: Number(stopAfter) || 0,   // 0 = run forever; N = expire after N triggers
     onNotMet: onNotMet || null,          // null | 'notify' — action per poll when condition not met
     action: action || null,              // optional follow-up action — see engine/watch-actions.js
+    // P-w10b6e2d — Phase 5: optional requires[] — when present every entry
+    // must also evaluate truthy for the watch to fire. See evaluateWatch.
+    requires: Array.isArray(requires) ? requires.map(r => ({
+      target: r.target, targetType: r.targetType, condition: r.condition,
+    })) : null,
     triggerCount: 0,
     created_at: ts(),
     last_checked: null,
     last_triggered: null,
+    // P-w12d8f3a — Phase 6.2: bounded evaluation history (last
+    // WATCH_HISTORY_MAX=25 checks, oldest-first). Appended in checkWatches
+    // on every poll (fired AND not-fired). Powers GET /api/watches/:id/history
+    // (P-w13c2b6f) without needing a separate file.
+    _history: [],
   };
 
   mutateJsonFileLocked(_watchesPath(), (watches) => {
@@ -161,13 +183,19 @@ function updateWatch(id, updates) {
     const actionErr = watchActions.validateAction(updates.action);
     if (actionErr) throw new Error(actionErr);
   }
+  // P-w10b6e2d — Phase 5: validate requires[] before entering the lock so a
+  // bad shape never lands on disk. `[]` is allowed (clears the join).
+  if (updates.requires !== undefined && updates.requires !== null) {
+    const reqErr = _validateRequires(updates.requires);
+    if (reqErr) throw new Error(reqErr);
+  }
   let found = null;
   mutateJsonFileLocked(_watchesPath(), (watches) => {
     if (!Array.isArray(watches)) return watches;
     const watch = watches.find(w => w.id === id);
     if (!watch) return watches;
     // Only allow safe field updates
-    const allowed = ['status', 'interval', 'description', 'notify', 'stopAfter', 'onNotMet', 'condition', 'action'];
+    const allowed = ['status', 'interval', 'description', 'notify', 'stopAfter', 'onNotMet', 'condition', 'action', 'requires'];
     for (const key of allowed) {
       if (updates[key] !== undefined) watch[key] = updates[key];
     }
@@ -204,6 +232,14 @@ function deleteWatch(id) {
  * @param {object} watch - The watch object
  * @param {object} state - { pullRequests, workItems, meetings?, plans?, schedules?, scheduleRuns?, pipelineRuns?, dispatch?, agents?, config? }
  * @returns {{ triggered: boolean, message: string }}
+ *
+ * P-w10b6e2d — Phase 5: when `watch.requires[]` is present, every entry
+ * must also evaluate truthy or the watch does not fire. Requirements are
+ * evaluated against the same `state` object via a recursive call into
+ * evaluateWatch with a synthetic mini-watch (no _lastState). The depth
+ * cap is 1 — `_validateRequires` rejects requirement entries that
+ * themselves declare a `requires` field at create/update time, so the
+ * recursion can never go past one level here.
  */
 function evaluateWatch(watch, state) {
   const { target, targetType, condition } = watch;
@@ -215,12 +251,71 @@ function evaluateWatch(watch, state) {
   if (!entity) return { triggered: false, message: `${tt.label} ${target} not found` };
 
   const prevState = watch._lastState || {};
+  let primary;
   try {
-    return tt.evaluate(condition, entity, prevState, target) || { triggered: false, message: '' };
+    primary = tt.evaluate(condition, entity, prevState, target) || { triggered: false, message: '' };
   } catch (err) {
     log('warn', `evaluateWatch ${targetType}/${condition}: ${err.message}`);
     return { triggered: false, message: `evaluator error: ${err.message}` };
   }
+  // Short-circuit when primary is not truthy — requires only constrain
+  // an already-firing primary; an un-fired primary stays un-fired.
+  if (!primary.triggered) return primary;
+
+  // P-w10b6e2d — Phase 5: AND-join with each requires[] entry.
+  if (Array.isArray(watch.requires) && watch.requires.length > 0) {
+    for (let i = 0; i < watch.requires.length; i++) {
+      const req = watch.requires[i];
+      // Synthetic mini-watch — no _lastState, no nested requires (depth cap
+      // enforced at create/update time). evaluateWatch handles missing
+      // entity / unknown type / unknown condition the same way it does
+      // for a top-level watch.
+      const reqResult = evaluateWatch({
+        target: req.target, targetType: req.targetType, condition: req.condition,
+      }, state);
+      if (!reqResult.triggered) {
+        return {
+          triggered: false,
+          message: `${primary.message || 'primary truthy'} BUT requires[${i}] (${req.targetType}/${req.target}/${req.condition}) not met: ${reqResult.message || 'condition not met'}`,
+        };
+      }
+    }
+  }
+
+  return primary;
+}
+
+/**
+ * Validate a `watch.requires` array. Returns an error message string when
+ * invalid, or null when valid. Enforces the Phase 5 contract:
+ *   - must be an array (use `[]` to clear; null/undefined to omit entirely)
+ *   - each entry must be a plain object with a non-empty target, a
+ *     targetType registered in TARGET_TYPES, and a condition listed in
+ *     that target type's `conditions` array
+ *   - depth cap of 1: requirement entries MUST NOT themselves declare a
+ *     `requires` field (otherwise we'd need cycle detection)
+ */
+function _validateRequires(requires) {
+  if (!Array.isArray(requires)) return 'requires must be an array of {target, targetType, condition}';
+  for (let i = 0; i < requires.length; i++) {
+    const r = requires[i];
+    if (!r || typeof r !== 'object' || Array.isArray(r)) {
+      return `requires[${i}] must be a {target, targetType, condition} object`;
+    }
+    if (!r.target || typeof r.target !== 'string') {
+      return `requires[${i}].target is required (non-empty string)`;
+    }
+    if (!r.targetType || !TARGET_TYPES[r.targetType]) {
+      return `requires[${i}].targetType must be one of: ${Object.keys(TARGET_TYPES).sort().join(', ')}`;
+    }
+    if (!r.condition || !TARGET_TYPES[r.targetType].conditions.includes(r.condition)) {
+      return `requires[${i}].condition must be one of: ${TARGET_TYPES[r.targetType].conditions.join(', ')} (for targetType ${r.targetType})`;
+    }
+    if (r.requires !== undefined) {
+      return `requires[${i}] must not contain a nested 'requires' field (depth cap is 1)`;
+    }
+  }
+  return null;
 }
 
 /**
@@ -273,25 +368,48 @@ function checkWatches(config, state) {
           watch._lastTriggerMessage = result.message;
           const newState = _captureState(watch, state);
 
-          // Queue trigger notification — unique key per trigger to avoid overwriting previous messages
-          if (watch.notify === 'inbox' && watch.owner) {
-            notifications.push({
-              type: 'trigger', owner: watch.owner,
-              slug: `watch-${watch.id}-${watch.triggerCount}`,
-              body: `## Watch Triggered: ${watch.description}\n\n${result.message}\n\nWatch ID: ${watch.id} | Target: ${watch.target} | Condition: ${watch.condition}`,
-            });
-          }
           log('info', `Watch triggered: ${watch.id} — ${result.message}`);
 
           // Queue follow-up action for after-lock invocation. We snapshot the
           // watch + entity here so the async handler can run with the same
           // state that triggered the watch even if the live state changes.
-          if (watch.action && typeof watch.action === 'object' && watch.action.type) {
+          //
+          // P-w8e9b1f4 — Phase 4: action may be either a single object
+          // (`{type, ...}`) or an array-form chain (`[{type,...}, ...]`).
+          //
+          // P-w11a4c9e — Phase 6.1: NOTIFY is no longer a special case.
+          // When `watch.notify === 'inbox'` (and the watch has an owner),
+          // an implicit `{type:'notify'}` step is prepended to the chain
+          // here so the legacy inbox alert and any explicit follow-up
+          // action both run through the registered action surface.
+          //
+          // When there is NO implicit notify to prepend, the original
+          // action shape is preserved (single-object stays single-object,
+          // array stays array) so back-compat _lastActionResult shape
+          // (`type: 'webhook'`, `dispatchedItemId`, …) is unchanged.
+          const _explicitAction = watch.action;
+          const _wantImplicitNotify = (watch.notify === 'inbox' && watch.owner);
+          const _hasExplicitArray = Array.isArray(_explicitAction) && _explicitAction.length > 0;
+          const _hasExplicitObject = _explicitAction && typeof _explicitAction === 'object'
+            && !Array.isArray(_explicitAction) && _explicitAction.type;
+          let _effectiveAction = null;
+          if (_wantImplicitNotify && _hasExplicitArray) {
+            _effectiveAction = [{ type: 'notify' }].concat(_explicitAction);
+          } else if (_wantImplicitNotify && _hasExplicitObject) {
+            _effectiveAction = [{ type: 'notify' }, _explicitAction];
+          } else if (_wantImplicitNotify) {
+            _effectiveAction = [{ type: 'notify' }];
+          } else if (_hasExplicitArray || _hasExplicitObject) {
+            _effectiveAction = _explicitAction;
+          }
+          if (_effectiveAction) {
             const tt = TARGET_TYPES[watch.targetType];
             const entity = tt ? tt.fetchEntity(watch.target, state || {}) : null;
+            const snapshot = JSON.parse(JSON.stringify(watch));
+            snapshot.action = _effectiveAction;
             actionsToRun.push({
               watchId: watch.id,
-              snapshot: JSON.parse(JSON.stringify(watch)),
+              snapshot,
               previousState,
               newState,
               entity: entity ? JSON.parse(JSON.stringify(entity)) : null,
@@ -319,6 +437,21 @@ function checkWatches(config, state) {
 
         // Capture state for change detection on next check
         watch._lastState = _captureState(watch, state);
+
+        // P-w12d8f3a — Phase 6.2: append a bounded evaluation history
+        // entry on EVERY check (fired AND not-fired). Trim oldest first
+        // when the buffer exceeds WATCH_HISTORY_MAX. action_results is
+        // populated post-lock by _runActionTask once the action runs.
+        if (!Array.isArray(watch._history)) watch._history = [];
+        watch._history.push({
+          checked_at: watch.last_checked,
+          fired: !!result.triggered,
+          reason: result.message || '',
+          condition: watch.condition,
+        });
+        if (watch._history.length > WATCH_HISTORY_MAX) {
+          watch._history.splice(0, watch._history.length - WATCH_HISTORY_MAX);
+        }
       } catch (err) {
         log('warn', `Watch check error (${watch.id}): ${err.message}`);
       }
@@ -353,21 +486,64 @@ async function _runActionTask(task) {
     message: task.message,
   });
   const result = await watchActions.runWatchAction(task.snapshot, ctx);
+  const isChain = Array.isArray(task.snapshot.action);
+  const actionLabel = isChain
+    ? `chain[${task.snapshot.action.length}]`
+    : (task.snapshot.action?.type || '?');
   log(result.ok ? 'info' : 'warn',
-    `Watch ${task.watchId} action ${task.snapshot.action?.type || '?'}: ${result.summary || (result.ok ? 'ok' : 'failed')}`);
+    `Watch ${task.watchId} action ${actionLabel}: ${result.summary || (result.ok ? 'ok' : 'failed')}`);
   // Persist back onto the watch (best-effort).
+  // P-w8e9b1f4 — Phase 4: array-form actions persist a `steps[]` array
+  // alongside the aggregate {ok, summary} so dashboards / downstream readers
+  // can inspect each step's result. Single-action watches keep the legacy
+  // `dispatchedItemId` shortcut for back-compat.
   try {
     mutateJsonFileLocked(_watchesPath(), (watches) => {
       if (!Array.isArray(watches)) return watches;
       const w = watches.find(x => x.id === task.watchId);
       if (w) {
-        w._lastActionResult = {
-          type: task.snapshot.action?.type || null,
-          ok: !!result.ok,
-          summary: result.summary || '',
-          dispatchedItemId: result.dispatchedItemId || null,
-          at: ts(),
-        };
+        if (isChain) {
+          w._lastActionResult = {
+            type: 'chain',
+            ok: !!result.ok,
+            summary: result.summary || '',
+            aborted: !!result.aborted,
+            steps: Array.isArray(result.steps) ? result.steps.map(s => ({
+              type: s.type || null,
+              ok: !!s.ok,
+              skipped: !!s.skipped,
+              summary: s.summary || '',
+              dispatchedItemId: (s.result && s.result.dispatchedItemId) || null,
+            })) : [],
+            at: ts(),
+          };
+        } else {
+          w._lastActionResult = {
+            type: task.snapshot.action?.type || null,
+            ok: !!result.ok,
+            summary: result.summary || '',
+            dispatchedItemId: result.dispatchedItemId || null,
+            at: ts(),
+          };
+        }
+
+        // P-w12d8f3a — Phase 6.2: backfill action_results onto the most
+        // recent (fired) history entry. The history append already
+        // happened inside the checkWatches lock; here we attach a small
+        // bounded summary so the GET /api/watches/:id/history surface
+        // (P-w13c2b6f) can show whether the action succeeded. Step-level
+        // detail stays on _lastActionResult — history keeps only the
+        // aggregate to honor the "small + bounded" contract.
+        if (Array.isArray(w._history) && w._history.length > 0) {
+          const last = w._history[w._history.length - 1];
+          if (last && last.fired) {
+            last.action_results = {
+              type: w._lastActionResult.type,
+              ok: w._lastActionResult.ok,
+              summary: w._lastActionResult.summary || '',
+            };
+          }
+        }
       }
       return watches;
     }, { defaultValue: [] });
@@ -386,7 +562,11 @@ function _captureState(watch, state) {
   const entity = tt.fetchEntity(watch.target, state || {});
   if (!entity) return {};
   try {
-    return tt.captureState(entity) || {};
+    // P-w5b8d2c9 — Phase 2.2: pass prevState so captureState can carry
+    // forward unchanged-tick counters (e.g. _unchangedTicks for work-item
+    // stalled, _stuckStageTicks for pipeline stuck-in-stage). Existing
+    // captureState fns that take only 1 arg ignore this — backward-compat.
+    return tt.captureState(entity, watch._lastState || {}) || {};
   } catch (err) {
     log('warn', `_captureState ${watch.targetType}: ${err.message}`);
     return {};
@@ -403,11 +583,28 @@ registerTargetType(WATCH_TARGET_TYPE.PR, {
     WATCH_CONDITION.MERGED, WATCH_CONDITION.BUILD_FAIL, WATCH_CONDITION.BUILD_PASS,
     WATCH_CONDITION.STATUS_CHANGE, WATCH_CONDITION.ANY,
     WATCH_CONDITION.NEW_COMMENTS, WATCH_CONDITION.VOTE_CHANGE,
+    // P-w4e2f6a1 — Phase 2.1: head/mergeability/draft/behind predicates.
+    // Backed by Phase 1.1 captureState plumbing (headRefOid, mergeable,
+    // isDraft, mergeStateStatus) and Phase 1.3 behindBy (read at fire-time
+    // so this list is safe to advertise even before behindBy lands).
+    WATCH_CONDITION.HEAD_COMMIT_CHANGE, WATCH_CONDITION.MERGEABLE_FLIPPED,
+    WATCH_CONDITION.READY_FOR_MERGE, WATCH_CONDITION.BEHIND_MASTER,
+    WATCH_CONDITION.DRAFT_FLIPPED,
   ],
   fetchEntity: (target, state) => findPrByTarget(state.pullRequests, target),
   captureState: (pr) => ({
     status: pr.status, buildStatus: pr.buildStatus, reviewStatus: pr.reviewStatus,
     lastCommentDate: pr.humanFeedback?.lastProcessedCommentDate || null,
+    // P-w1a3f9b2 — Phase 1.1: plumb head-commit / mergeability / draft / merge-state
+    // so future predicates (Phase 2.1: head-commit-change, mergeable-flipped,
+    // ready-for-merge, draft-flipped) can read them. Values are passed through
+    // verbatim — including `undefined` for legacy PR objects that haven't been
+    // re-polled yet — so symmetric prevState/newState comparisons stay false on
+    // the first post-upgrade tick instead of synthesizing a phantom change.
+    headRefOid: pr.headRefOid,
+    mergeable: pr.mergeable,
+    isDraft: pr.isDraft,
+    mergeStateStatus: pr.mergeStateStatus,
   }),
   evaluate: (condition, pr, prevState, target) => {
     switch (condition) {
@@ -439,6 +636,59 @@ registerTargetType(WATCH_TARGET_TYPE.PR, {
         const changed = prevState.reviewStatus !== undefined && prevState.reviewStatus !== pr.reviewStatus;
         return { triggered: changed, message: changed ? `PR ${target} vote changed: ${prevState.reviewStatus} → ${pr.reviewStatus}` : '' };
       }
+      // ── P-w4e2f6a1 — Phase 2.1 PR predicates ──────────────────────────
+      case WATCH_CONDITION.HEAD_COMMIT_CHANGE: {
+        // Fire only when both sides are defined, non-null SHAs that differ.
+        // Suppresses post-upgrade phantom triggers when prevState is missing
+        // headRefOid (legacy `_lastState`) or the poller hasn't populated it
+        // yet on this tick.
+        const prev = prevState.headRefOid;
+        const cur = pr.headRefOid;
+        const changed = !!(prev && cur && prev !== cur);
+        return { triggered: changed, message: changed ? `PR ${target} head commit changed: ${prev} → ${cur}` : '' };
+      }
+      case WATCH_CONDITION.MERGEABLE_FLIPPED: {
+        // engine/github.js:902-923 documents that mergeable=null means
+        // "GitHub still computing" — NOT a positive signal. Only fire on
+        // transitions between defined boolean values (true↔false). Any
+        // transition involving null or undefined is ignored.
+        const prev = prevState.mergeable;
+        const cur = pr.mergeable;
+        const isBool = (v) => v === true || v === false;
+        const flipped = isBool(prev) && isBool(cur) && prev !== cur;
+        return { triggered: flipped, message: flipped ? `PR ${target} mergeable flipped: ${prev} → ${cur}` : '' };
+      }
+      case WATCH_CONDITION.READY_FOR_MERGE: {
+        // Compound predicate — fires when ALL gating signals line up.
+        // Registered as an absolute condition (engine/shared.js
+        // WATCH_ABSOLUTE_CONDITIONS) so it auto-expires on first trigger
+        // when stopAfter=0. Treat isDraft !== true (catches null/undefined
+        // legacy PRs that don't expose the field).
+        const ready = pr.status === 'active'
+          && pr.reviewStatus === 'approved'
+          && pr.buildStatus === 'passing'
+          && pr.mergeable === true
+          && pr.isDraft !== true;
+        return { triggered: ready, message: ready ? `PR ${target} is ready for merge` : '' };
+      }
+      case WATCH_CONDITION.BEHIND_MASTER: {
+        // Phase 1.3 will plumb pr.behindBy. Until then, this stays dormant
+        // (typeof check rejects null/undefined). Treat null as not-behind
+        // per the PRD spec — only a numeric > 0 fires.
+        const b = pr.behindBy;
+        const behind = typeof b === 'number' && b > 0;
+        return { triggered: behind, message: behind ? `PR ${target} is behind master by ${b} commit${b === 1 ? '' : 's'}` : '' };
+      }
+      case WATCH_CONDITION.DRAFT_FLIPPED: {
+        // Symmetric to mergeable-flipped: only fire on true↔false transitions
+        // between defined boolean values. Suppresses post-upgrade phantom
+        // triggers when isDraft was previously undefined.
+        const prev = prevState.isDraft;
+        const cur = pr.isDraft;
+        const isBool = (v) => v === true || v === false;
+        const flipped = isBool(prev) && isBool(cur) && prev !== cur;
+        return { triggered: flipped, message: flipped ? `PR ${target} draft flipped: ${prev} → ${cur}` : '' };
+      }
       default:
         return { triggered: false, message: `Unknown condition: ${condition}` };
     }
@@ -452,9 +702,36 @@ registerTargetType(WATCH_TARGET_TYPE.WORK_ITEM, {
   conditions: [
     WATCH_CONDITION.COMPLETED, WATCH_CONDITION.FAILED,
     WATCH_CONDITION.STATUS_CHANGE, WATCH_CONDITION.ANY,
+    // P-w5b8d2c9 — Phase 2.2: stalled / retry-limit / dependency predicates.
+    // Backed by Phase 1.2 captureState plumbing (retries, _pendingReason)
+    // plus a Phase 2.2 _unchangedTicks counter computed inside captureState.
+    WATCH_CONDITION.STALLED, WATCH_CONDITION.RETRY_LIMIT_REACHED,
+    WATCH_CONDITION.DEPENDENCY_MET,
   ],
   fetchEntity: (target, state) => (state.workItems || []).find(w => w.id === target) || null,
-  captureState: (wi) => ({ status: wi.status }),
+  // P-w2c8d1e7 — Phase 1.2: surface retry count, pending-reason, and branch
+  // for upcoming stalled / branch-aware predicates. `retries` aliases the
+  // private `_retryCount` so guards can read a stable field name.
+  // P-w5b8d2c9 — Phase 2.2: also carry forward `_unchangedTicks`, an
+  // unbounded counter incremented each tick that the observable fields
+  // (status / retries / _pendingReason / branch) all match prevState. Reset
+  // to 0 on any change. Drives the `stalled` predicate.
+  captureState: (wi, prev) => {
+    const status = wi.status;
+    const retries = wi._retryCount || 0;
+    const pendingReason = wi._pendingReason || null;
+    const branch = wi.branch || null;
+    const unchanged = !!prev
+      && prev.status === status
+      && (prev.retries || 0) === retries
+      && (prev._pendingReason || null) === pendingReason
+      && (prev.branch || null) === branch;
+    const unchangedTicks = unchanged ? ((prev._unchangedTicks || 0) + 1) : 0;
+    return {
+      status, retries, _pendingReason: pendingReason, branch,
+      _unchangedTicks: unchangedTicks,
+    };
+  },
   evaluate: (condition, wi, prevState, target) => {
     switch (condition) {
       case WATCH_CONDITION.COMPLETED: {
@@ -473,6 +750,41 @@ registerTargetType(WATCH_TARGET_TYPE.WORK_ITEM, {
         const anyChanged = prevState.status !== undefined && prevState.status !== wi.status;
         return { triggered: anyChanged, message: anyChanged ? `Work item ${target} changed (${wi.status})` : '' };
       }
+      // ── P-w5b8d2c9 — Phase 2.2 work-item predicates ──────────────────
+      case WATCH_CONDITION.STALLED: {
+        // Suppress on terminal items — a done/failed work item is not
+        // "stalled", it's finished. Otherwise fire when the carried-forward
+        // _unchangedTicks counter has crossed the threshold.
+        const isTerminal = shared.DONE_STATUSES.has(wi.status)
+          || wi.status === shared.WI_STATUS.FAILED
+          || wi.status === shared.WI_STATUS.CANCELLED;
+        if (isTerminal) return { triggered: false, message: '' };
+        const ticks = prevState._unchangedTicks || 0;
+        const threshold = shared.WATCH_STALLED_DEFAULT_TICKS;
+        const stalled = ticks >= threshold;
+        return { triggered: stalled, message: stalled ? `Work item ${target} stalled (${wi.status}, no change for ${ticks} checks)` : '' };
+      }
+      case WATCH_CONDITION.RETRY_LIMIT_REACHED: {
+        // Compound state assertion — registered as absolute so it auto-expires
+        // after the first fire when stopAfter=0 (otherwise it would re-fire
+        // every tick while the work item sits at maxRetries).
+        const retries = wi._retryCount || 0;
+        const limit = shared.ENGINE_DEFAULTS.maxRetries;
+        const reached = retries >= limit;
+        return { triggered: reached, message: reached ? `Work item ${target} hit retry limit (${retries} >= ${limit})` : '' };
+      }
+      case WATCH_CONDITION.DEPENDENCY_MET: {
+        // Transition predicate: prevState had _pendingReason='dependency_unmet'
+        // and current does not. Restrict to pending/dispatched statuses so
+        // we don't confuse "dependency met" with "item terminated for other
+        // reasons" (e.g. cancelled while waiting on a dep).
+        const wasUnmet = prevState._pendingReason === 'dependency_unmet';
+        const nowMet = (wi._pendingReason || null) !== 'dependency_unmet';
+        const validStatus = wi.status === shared.WI_STATUS.PENDING
+          || wi.status === shared.WI_STATUS.DISPATCHED;
+        const fired = wasUnmet && nowMet && validStatus;
+        return { triggered: fired, message: fired ? `Work item ${target} dependency met (status=${wi.status}, reason=${wi._pendingReason || 'none'})` : '' };
+      }
       default:
         return { triggered: false, message: `Unknown condition: ${condition}` };
     }
@@ -518,15 +830,56 @@ function _findPlan(target, state) {
     return false;
   }) || null;
 }
+// P-w2c8d1e7 — Phase 1.2: derive item progress from the PRD's
+// missing_features array. Returns 0 when the array is missing/empty so
+// guards can compare numerically without null-checks.
+function _planItemsTotal(p) {
+  return Array.isArray(p?.missing_features) ? p.missing_features.length : 0;
+}
+function _planItemsDone(p) {
+  if (!Array.isArray(p?.missing_features)) return 0;
+  let n = 0;
+  for (const item of p.missing_features) {
+    if (item && shared.DONE_STATUSES.has(item.status)) n += 1;
+  }
+  return n;
+}
+// P-w5b8d2c9 — Phase 2.2: max retry count across plan items, drives the
+// `item-failed-n-times` predicate. Treats null/undefined retries as 0 so
+// the predicate stays dormant for plans that have no retry data.
+function _planMaxItemRetries(p) {
+  if (!Array.isArray(p?.missing_features)) return 0;
+  let max = 0;
+  for (const item of p.missing_features) {
+    const rc = (item && item._retryCount) || 0;
+    if (rc > max) max = rc;
+  }
+  return max;
+}
 registerTargetType(WATCH_TARGET_TYPE.PLAN, {
   label: 'Plan / PRD',
   description: 'Watch a plan/PRD for approval, rejection, completion, or status changes',
   conditions: [
     WATCH_CONDITION.APPROVED, WATCH_CONDITION.REJECTED, WATCH_CONDITION.COMPLETED,
     WATCH_CONDITION.STATUS_CHANGE, WATCH_CONDITION.ANY,
+    // P-w5b8d2c9 — Phase 2.2: progress / failure-rate predicates derived
+    // from the PRD's missing_features array.
+    WATCH_CONDITION.ALL_ITEMS_DONE, WATCH_CONDITION.ITEM_FAILED_N_TIMES,
   ],
   fetchEntity: _findPlan,
-  captureState: (p) => ({ status: p.status, planStale: !!p.planStale }),
+  // P-w2c8d1e7 — Phase 1.2: surface item progress derived from the PRD's
+  // missing_features array so plan-level predicates (e.g. all-items-done)
+  // can read it directly from _lastState.
+  // P-w5b8d2c9 — Phase 2.2: also surface max_item_retries for the
+  // item-failed-n-times predicate. All values default to 0 so legacy
+  // `_lastState` shapes don't break.
+  captureState: (p) => ({
+    status: p.status,
+    planStale: !!p.planStale,
+    items_done: _planItemsDone(p),
+    items_total: _planItemsTotal(p),
+    max_item_retries: _planMaxItemRetries(p),
+  }),
   evaluate: (condition, p, prevState, target) => {
     const status = String(p.status || '').toLowerCase();
     switch (condition) {
@@ -545,6 +898,26 @@ registerTargetType(WATCH_TARGET_TYPE.PLAN, {
           (prevState.status !== p.status || prevState.planStale !== !!p.planStale);
         return { triggered: anyChanged, message: anyChanged ? `Plan ${target} changed (${p.status})` : '' };
       }
+      // ── P-w5b8d2c9 — Phase 2.2 plan predicates ───────────────────────
+      case WATCH_CONDITION.ALL_ITEMS_DONE: {
+        // Compound state assertion — registered as absolute so it auto-expires
+        // after first fire when stopAfter=0 (otherwise a fully-complete
+        // plan would re-fire every tick). Requires items_total > 0 so an
+        // empty PRD doesn't trigger the predicate vacuously.
+        const total = _planItemsTotal(p);
+        const done = _planItemsDone(p);
+        const allDone = total > 0 && done === total;
+        return { triggered: allDone, message: allDone ? `Plan ${target} all items done (${done}/${total})` : '' };
+      }
+      case WATCH_CONDITION.ITEM_FAILED_N_TIMES: {
+        // Compound state assertion — fires when ANY missing_feature has a
+        // _retryCount at or beyond ENGINE_DEFAULTS.maxRetries. Absolute so
+        // the alert fires once when the threshold is reached.
+        const maxRc = _planMaxItemRetries(p);
+        const limit = shared.ENGINE_DEFAULTS.maxRetries;
+        const fired = maxRc >= limit;
+        return { triggered: fired, message: fired ? `Plan ${target} has item retried ${maxRc} times (>= ${limit})` : '' };
+      }
       default:
         return { triggered: false, message: `Unknown condition: ${condition}` };
     }
@@ -569,7 +942,15 @@ registerTargetType(WATCH_TARGET_TYPE.SCHEDULE, {
     WATCH_CONDITION.STATUS_CHANGE, WATCH_CONDITION.ANY,
   ],
   fetchEntity: _findSchedule,
-  captureState: (s) => ({ lastRun: s._lastRun || null, enabled: s.enabled !== false }),
+  // P-w2c8d1e7 — Phase 1.2: surface next_run as null. Cron parsing in
+  // engine/scheduler.js exposes parseCronExpr/.matches() but not a
+  // next-fire calculator, so the snapshot field is reserved (always null
+  // today) for forward-compat with future predicates that gain a helper.
+  captureState: (s) => ({
+    lastRun: s._lastRun || null,
+    enabled: s.enabled !== false,
+    next_run: null,
+  }),
   evaluate: (condition, s, prevState, target) => {
     const enabled = s.enabled !== false;
     const lastRun = s._lastRun || null;
@@ -619,18 +1000,53 @@ function _completedStageCount(run) {
   }
   return n;
 }
+// P-w2c8d1e7 — Phase 1.2: report the id of the first non-terminal stage
+// in run.stages iteration order. run.stages is built from pipeline.stages
+// in declaration order (engine/pipeline.js startRun ~line 84) so the first
+// non-terminal entry is the currently-executing or next-pending stage.
+const _PIPELINE_TERMINAL = new Set(['completed', 'failed', 'stopped']);
+function _currentPipelineStageId(run) {
+  if (!run || !run.stages || typeof run.stages !== 'object') return null;
+  for (const [stageId, st] of Object.entries(run.stages)) {
+    const s = String((st && st.status) || '').toLowerCase();
+    if (!_PIPELINE_TERMINAL.has(s)) return stageId;
+  }
+  return null;
+}
 registerTargetType(WATCH_TARGET_TYPE.PIPELINE, {
   label: 'Pipeline',
   description: 'Watch the latest run of a pipeline for completion, failure, or stage progress',
   conditions: [
     WATCH_CONDITION.COMPLETED, WATCH_CONDITION.FAILED, WATCH_CONDITION.STAGE_COMPLETE,
     WATCH_CONDITION.STATUS_CHANGE, WATCH_CONDITION.ANY,
+    // P-w5b8d2c9 — Phase 2.2: stage-targeted predicates derived from the
+    // current_stage_id snapshot field plus a Phase 2.2 _stuckStageTicks
+    // counter computed inside captureState.
+    WATCH_CONDITION.STAGE_ADVANCED, WATCH_CONDITION.STUCK_IN_STAGE,
   ],
   fetchEntity: _findPipelineLatestRun,
-  captureState: (run) => ({
-    runId: run.runId || null, status: run.status || null,
-    completedStages: _completedStageCount(run),
-  }),
+  // P-w2c8d1e7 — Phase 1.2: surface current_stage_id (first non-terminal
+  // stage in declaration order) for stage-targeted predicates.
+  // P-w5b8d2c9 — Phase 2.2: also carry forward `_stuckStageTicks`, an
+  // unbounded counter that increments each tick the same non-null
+  // current_stage_id persists. Reset to 0 when the stage advances or when
+  // current_stage_id is null (run has no live stage). Drives the
+  // `stuck-in-stage` predicate.
+  captureState: (run, prev) => {
+    const runId = run.runId || null;
+    const status = run.status || null;
+    const completedStages = _completedStageCount(run);
+    const currentStageId = _currentPipelineStageId(run);
+    const sameStage = !!prev
+      && currentStageId !== null
+      && prev.current_stage_id === currentStageId
+      && prev.runId === runId;
+    const stuckStageTicks = sameStage ? ((prev._stuckStageTicks || 0) + 1) : 0;
+    return {
+      runId, status, completedStages, current_stage_id: currentStageId,
+      _stuckStageTicks: stuckStageTicks,
+    };
+  },
   evaluate: (condition, run, prevState, target) => {
     switch (condition) {
       case WATCH_CONDITION.COMPLETED: {
@@ -657,6 +1073,26 @@ registerTargetType(WATCH_TARGET_TYPE.PIPELINE, {
             (prevState.completedStages || 0) !== _completedStageCount(run));
         return { triggered: anyChanged, message: anyChanged ? `Pipeline ${target} changed (${run.status})` : '' };
       }
+      // ── P-w5b8d2c9 — Phase 2.2 pipeline predicates ───────────────────
+      case WATCH_CONDITION.STAGE_ADVANCED: {
+        // Triggers when current_stage_id changes within the same run.
+        // Different runId means a new run started — handled by status-change
+        // semantics, not by stage-advanced. Suppresses the
+        // undefined-prev → defined-cur transition (post-upgrade phantom).
+        const cur = _currentPipelineStageId(run);
+        const prev = prevState.current_stage_id;
+        const advanced = prev !== undefined && prev !== cur && prevState.runId === run.runId;
+        return { triggered: advanced, message: advanced ? `Pipeline ${target} advanced stage: ${prev} → ${cur}` : '' };
+      }
+      case WATCH_CONDITION.STUCK_IN_STAGE: {
+        // Fires when the carried-forward _stuckStageTicks counter has
+        // crossed the threshold. Implicitly requires current_stage_id !==
+        // null (counter resets to 0 when null per captureState).
+        const ticks = prevState._stuckStageTicks || 0;
+        const threshold = shared.WATCH_STUCK_STAGE_DEFAULT_TICKS;
+        const stuck = ticks >= threshold;
+        return { triggered: stuck, message: stuck ? `Pipeline ${target} stuck in stage ${prevState.current_stage_id} for ${ticks} checks` : '' };
+      }
       default:
         return { triggered: false, message: `Unknown condition: ${condition}` };
     }
@@ -722,7 +1158,14 @@ registerTargetType(WATCH_TARGET_TYPE.AGENT, {
     WATCH_CONDITION.ACTIVITY_CHANGE, WATCH_CONDITION.STATUS_CHANGE, WATCH_CONDITION.ANY,
   ],
   fetchEntity: _findAgent,
-  captureState: (a) => ({ status: a.status || null }),
+  // P-w2c8d1e7 — Phase 1.2: surface currentDispatchId so predicates can
+  // distinguish "agent now working on a different dispatch" from a plain
+  // status flip. Sourced from queries.getAgents() which derives it from
+  // dispatch.json (active list) via getAgentStatus.dispatch_id.
+  captureState: (a) => ({
+    status: a.status || null,
+    currentDispatchId: a.currentDispatchId || null,
+  }),
   evaluate: (condition, a, prevState, target) => {
     const cur = a.status || null;
     switch (condition) {
@@ -765,6 +1208,7 @@ module.exports = {
   getActionType: watchActions.getActionType,
   listActionTypes: watchActions.listActionTypes,
   runWatchAction: watchActions.runWatchAction,
+  runWatchActionChain: watchActions.runWatchActionChain,
   validateAction: watchActions.validateAction,
   _captureState,  // exported for testing
   _watchesPath,   // exported for testing — dynamic, respects MINIONS_TEST_DIR