forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/plugin-catalog.js

@@ -27,7 +27,6 @@ const STAGES = Object.freeze({
   VALIDATE: 'validate',
   SHIP: 'ship',
   REVIEW: 'review',
-  PREMERGE: 'premerge',
 });
 
 const BUDGET_MODES = Object.freeze({
@@ -326,12 +325,12 @@ const CATALOG = Object.freeze({
     install: { method: 'config', cmd: 'Self-hosted (qodo.ai)' },
   },
 
-  // ── Merge ──
+  // ── Release automation (ship-time) ──
   changesets: {
     name: 'Changesets',
     type: 'cli',
     tier: 'free',
-    stage: 'premerge',
+    stage: 'ship',
     description: 'Versioning and changelog management',
     detectWhen: ['file:package.json'],
     install: { method: 'npm', cmd: 'bun add -D @changesets/cli', dev: true },
@@ -340,7 +339,7 @@ const CATALOG = Object.freeze({
     name: 'Release Please',
     type: 'config',
     tier: 'free',
-    stage: 'premerge',
+    stage: 'ship',
     description: 'Automated release PRs by Google',
     detectWhen: [],
     install: { method: 'config', cmd: 'GitHub Action (google-github-actions/release-please-action)' },

package/lib/plugin-manager.js

@@ -30,12 +30,7 @@ const DEFAULT_SUPPORT_STATUS = 'supported';
 const SURFACE_BY_AGENT_ID = Object.freeze({
   claude: 'cli-first',
   codex: 'cli-first',
-  opencode: 'cli-first',
-  cline: 'editor-native',
   cursor: 'editor-native',
-  copilot: 'editor-native',
-  kilocode: 'editor-native',
-  roo: 'editor-native',
 });
 
 function isPlainObject(value) {

package/lib/pr-bundle.js

@@ -0,0 +1,186 @@
+'use strict';
+
+/**
+ * PR-state bundle — the "everything ready for the agent" gather half of the
+ * monitor (kernel 9b24257f, increment 1).
+ *
+ * `gatherPrBundle` aggregates the COMPLETE, read-only state of an open PR into
+ * one structured object a fixer-agent can act on WITHOUT fetching anything
+ * itself: every unresolved review thread (any author), the merge state, the
+ * full CI rollup (tagged with required-check membership), branch divergence, and
+ * predicted merge conflicts.
+ *
+ * This module is pure aggregation over a validated pr-state adapter. It makes NO
+ * decisions and takes NO actions — it never merges, never resolves threads,
+ * never writes code. The decision state machine stays in lib/pr-shepherd.js; the
+ * agent dispatch, the continuous loop, and close-on-merge that will consume this
+ * bundle are follow-ups, not part of this increment.
+ *
+ * @module pr-bundle
+ */
+
+const { isGreen, isFailed } = require('./pr-shepherd');
+
+/**
+ * Map an unresolved review thread to the agent-input comment shape. The named
+ * `author`/`body` come from the thread opener (the canonical anchor), but the
+ * FULL `comments` array is carried too — so a later human reply on a
+ * bot-opened thread is never hidden from the fixer-agent (which fetches
+ * nothing and acts only on this input). Tolerates adapters/payloads that don't
+ * surface every field.
+ *
+ * @param {object} thread
+ * @returns {{ author: string, path: string|null, line: number|null, body: string, threadId: string|null, comments: {author: string, body: string}[] }}
+ */
+function toUnresolvedComment(thread) {
+  const comments = (Array.isArray(thread.comments) ? thread.comments : []).map((c) => ({
+    author: String((c.author && c.author.login) || c.author || ''),
+    body: String(c.body || ''),
+  }));
+  const first = comments[0] || {};
+  return {
+    author: first.author || String(thread.author || ''),
+    path: thread.path || null,
+    line: typeof thread.line === 'number' ? thread.line : null,
+    body: first.body || String(thread.body || ''),
+    threadId: thread.threadId || thread.id || null,
+    comments,
+  };
+}
+
+/**
+ * Read ALL unresolved review threads (any author) and map them to the agent
+ * comment shape.
+ *
+ * Returns `{ comments, available, error }` — NOT a bare array — so a consumer can
+ * tell three states apart that a `[]`-on-everything collapse would conflate:
+ *   - capability absent  → available:false, error:null  (adapter has no readComments)
+ *   - read succeeded      → available:true,  error:null  (comments is authoritative)
+ *   - read THREW          → available:false, error:msg   (comments unreadable — NOT "none")
+ *
+ * The third case is the critical one: a monitor must never treat "GitHub comments
+ * were unreadable" as "this PR has no unresolved feedback" and silently skip work.
+ * A failed read still degrades gracefully (the rest of the bundle survives), but
+ * the failure is surfaced rather than swallowed.
+ *
+ * @returns {Promise<{ comments: object[], available: boolean, error: string|null }>}
+ */
+async function gatherUnresolvedComments(adapter, { owner, repo, pr }) {
+  if (typeof adapter.readComments !== 'function') {
+    return { comments: [], available: false, error: null };
+  }
+  try {
+    const threads = await adapter.readComments({ owner, repo, pr });
+    const comments = (Array.isArray(threads) ? threads : [])
+      .filter((t) => !(t.isResolved || t.resolved))
+      .map(toUnresolvedComment);
+    return { comments, available: true, error: null };
+  } catch (err) {
+    // A failed comment read must not sink the rest of the bundle, but it MUST be
+    // distinguishable from "no unresolved threads" — preserve the error signal.
+    return { comments: [], available: false, error: err.message || 'comment read failed' };
+  }
+}
+
+/**
+ * Predict merge conflicts. `detectConflicts` is optional on the adapter; when
+ * absent or failing, report it as unsupported rather than throwing.
+ */
+async function gatherConflicts(adapter, { baseRef, cwd }) {
+  if (typeof adapter.detectConflicts !== 'function') {
+    return { supported: false, reason: 'adapter has no detectConflicts capability' };
+  }
+  try {
+    return await adapter.detectConflicts({ baseRef, cwd });
+  } catch (error) {
+    return { supported: false, reason: error.message || 'conflict detection failed' };
+  }
+}
+
+/**
+ * Tag the CI rollup with required-check membership and split out failing/pending.
+ *
+ * `requiredSet` is the branch-protection required set (array), or `null` when it
+ * is unreadable — in which case `required` is left `null` per check rather than
+ * `false`, so the agent is never told "nothing is required" on bad data.
+ *
+ * @param {object[]} checks - Normalized rollup from `readState`.
+ * @param {string[]|null} requiredSet
+ * @returns {{ checks: object[], failing: object[], pending: object[] }}
+ */
+function buildCi(checks, requiredSet) {
+  const isRequired = (name) => (requiredSet === null ? null : requiredSet.includes(name));
+  const tagged = (Array.isArray(checks) ? checks : []).map((c) => ({
+    name: c.name || '',
+    status: c.status || '',
+    conclusion: c.conclusion || '',
+    required: isRequired(c.name || ''),
+    detailsUrl: c.detailsUrl || null,
+  }));
+  return {
+    checks: tagged,
+    failing: tagged.filter((c) => isFailed(c)),
+    pending: tagged.filter((c) => !isGreen(c) && !isFailed(c)),
+  };
+}
+
+/**
+ * Gather the complete read-only PR-state bundle for the monitor's fixer-agent.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.pr
+ * @param {string} ctx.owner
+ * @param {string} ctx.repo
+ * @param {string} ctx.base    - Base BRANCH name (for branch-protection lookup).
+ * @param {string} ctx.baseRef - Base REF for divergence/conflicts (e.g. `origin/master`).
+ * @param {string} [ctx.cwd]
+ * @param {object} ctx.adapter - A validated pr-state adapter.
+ * @returns {Promise<object>} the structured bundle.
+ */
+async function gatherPrBundle({ pr, owner, repo, base, baseRef, cwd, adapter }) {
+  if (!adapter || typeof adapter.readState !== 'function') {
+    throw new Error('gatherPrBundle requires a pr-state adapter with readState');
+  }
+
+  const state = await adapter.readState(pr);
+  // NOTE: required-check lookup needs the base BRANCH name (`base`), not the
+  // remote ref (`baseRef`); passing the ref builds a bad protection path and
+  // silently yields a null required set.
+  const requiredRaw = await adapter.readRequiredChecks({ owner, repo, base });
+  const divergence = await adapter.readDivergence({ baseRef, cwd });
+  const comments = await gatherUnresolvedComments(adapter, { owner, repo, pr });
+  const conflicts = await gatherConflicts(adapter, { baseRef, cwd });
+
+  const requiredSet = requiredRaw === undefined ? null : requiredRaw;
+
+  return {
+    pr: String(pr),
+    owner,
+    repo,
+    base,
+    baseRef,
+    unresolvedComments: comments.comments,
+    // Availability signal for the comment read: when false with a non-null error,
+    // the threads were UNREADABLE (not absent) — a monitor must not treat the empty
+    // unresolvedComments list as "no feedback" and skip work.
+    unresolvedCommentsAvailable: comments.available,
+    unresolvedCommentsError: comments.error,
+    mergeState: {
+      mergeable: state.mergeable || 'UNKNOWN',
+      mergeStateStatus: state.mergeStateStatus || 'UNKNOWN',
+      state: String(state.state || 'OPEN').toUpperCase(),
+    },
+    ci: buildCi(state.checks, requiredSet),
+    branch: {
+      ahead: divergence.ahead || 0,
+      behind: divergence.behind || 0,
+    },
+    conflicts,
+  };
+}
+
+module.exports = {
+  gatherPrBundle,
+  buildCi,
+  toUnresolvedComment,
+};

package/lib/pr-monitor/auto-actions.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * PR-monitor Tier-2 auto-actions — the SAFE, fail-closed *action* half of the
+ * shepherd (issue addf5297, epic c2d398e5). Tier-1 (lib/pr-pull.js computeVerdict
+ * + the pr-monitor workflow) LABELS a PR's state but takes no action, so PRs that
+ * only need "master merged in" sit untended until a human/agent nudges them.
+ *
+ * This module decides — PURELY, from the SAME `forge shepherd <pr> --pull --json`
+ * payload the monitor already computes — whether the monitor may take one of two
+ * surface-safe actions:
+ *   1. `updateBranch` — merge base into an OTHERWISE-CLEAN-but-BEHIND PR (the
+ *      "last mile" case). This is the highest-value, safest action: it clears the
+ *      BEHIND churn without ever touching a PR that has a real blocker.
+ *   2. `rerunFlaky`   — re-run a required check whose failure is INFRASTRUCTURAL
+ *      (cancelled / timed-out / stale / startup-failure), never a real test
+ *      FAILURE/ERROR.
+ *
+ * It NEVER merges, NEVER resolves review threads, NEVER force-pushes, NEVER edits
+ * code. It only decides; the workflow executes the `gh` calls (and owns
+ * per-head-SHA idempotency markers). Every gate below is fail-CLOSED: any missing
+ * field, degraded read, real failure, fork, draft, or unclassifiable signal
+ * yields `should:false`.
+ *
+ * @module pr-monitor/auto-actions
+ */
+
+/**
+ * Check conclusions that are INFRASTRUCTURAL flakes — a re-run may legitimately
+ * turn them green. Mirrors lib/pr-shepherd.js `isFailed`'s not-green terminal
+ * conclusions MINUS the genuinely-broken ones (FAILURE/ERROR/ACTION_REQUIRED).
+ */
+const INFRA_CONCLUSIONS = new Set(['CANCELLED', 'TIMED_OUT', 'STALE', 'STARTUP_FAILURE']);
+
+/** Conclusions that mean the code is genuinely broken — NEVER auto-rerun these. */
+const REAL_FAILURE_CONCLUSIONS = new Set(['FAILURE', 'ERROR', 'ACTION_REQUIRED']);
+
+/**
+ * Pull the numeric Actions run id from a job/run "details" URL
+ * (`.../actions/runs/<run>/job/<job>` or `.../actions/runs/<run>`). Returns null
+ * when absent — a null run id fails the rerun decision closed.
+ *
+ * @param {string} url
+ * @returns {string | null}
+ */
+function runIdFromUrl(url) {
+  const m = String(url || '').match(/\/runs\/(\d+)/);
+  return m ? m[1] : null;
+}
+
+/**
+ * A payload is DEGRADED (some verdict-relevant read failed or the head moved
+ * mid-gather) when its evidence lists unreadable sources or a torn read. Acting
+ * on a degraded gather could act on stale/false state, so both actions fail
+ * closed on it — even though `verdict==='BEHIND'` already implies a clean read,
+ * this stays an explicit, independent guard.
+ *
+ * @param {object} payload
+ * @returns {boolean}
+ */
+function isDegraded(payload) {
+  const ev = (payload && payload.evidence) || {};
+  const unreadable = Array.isArray(ev.unreadable) ? ev.unreadable : [];
+  return unreadable.length > 0 || ev.tornRead === true;
+}
+
+/**
+ * Decide whether to auto-update (merge base into) an otherwise-clean-but-BEHIND
+ * PR. Fires ONLY for the "last mile" case:
+ *   - verdict is exactly `BEHIND` (which itself guarantees rank-1 UNKNOWN and
+ *     rank-2 BLOCKED-CONFLICT did NOT fire — i.e. the read was clean and there is
+ *     no conflict);
+ *   - the PR is NOT a draft and NOT a fork (a base-repo token cannot push a fork
+ *     branch, and forks are out of scope);
+ *   - the read is not degraded;
+ *   - and the ONLY blocker is the behind-base one — every other blocker type
+ *     (failing/missing/skipped/pending required checks, bot-status gates,
+ *     unresolved threads, changes-requested / review-required, conflict) is
+ *     absent. `blockers[]` is computed independently of the verdict precedence,
+ *     so it still lists lower-precedence blockers that `BEHIND` masks — which is
+ *     exactly why we key on it rather than on the single verdict string.
+ *
+ * @param {object} payload - the `--pull --json` payload.
+ * @param {{ isFork?: boolean }} [opts]
+ * @returns {{ should: boolean, reason: string }}
+ */
+function decideUpdateBranch(payload, opts = {}) {
+  const skip = (reason) => ({ should: false, reason });
+  if (!payload || typeof payload !== 'object') return skip('no payload — fail closed');
+  if (opts.isFork) return skip('fork PR — a base-repo token cannot update a fork branch');
+  if (isDegraded(payload)) return skip('degraded/torn read — fail closed');
+  if (payload.verdict !== 'BEHIND') return skip(`verdict ${payload.verdict || 'UNKNOWN'} is not BEHIND`);
+  if (payload.draft === true) return skip('draft PR — not ready to advance');
+  if (!Array.isArray(payload.blockers)) return skip('blockers[] unavailable — fail closed');
+  const others = payload.blockers.filter((b) => b && b.type !== 'behind');
+  if (others.length > 0) {
+    return skip(`other blocker(s) present: ${others.map((b) => b.type).join(', ')}`);
+  }
+  return { should: true, reason: 'otherwise-clean-behind — only blocker is behind-base; merge base in' };
+}
+
+/**
+ * Decide whether to re-run flaky REQUIRED checks. Fires ONLY when EVERY failing
+ * required check is infrastructural (cancelled/timed-out/stale/startup-failure)
+ * with a derivable run id, and NONE is a real FAILURE/ERROR/ACTION_REQUIRED. A
+ * single real failure, an unclassifiable conclusion, a required-failing check
+ * with no matching `failures[]` entry, or a missing run id fails the WHOLE
+ * decision closed (never rerun a genuinely-broken PR, never loop on a real bug).
+ *
+ * @param {object} payload - the `--pull --json` payload.
+ * @returns {{ should: boolean, checks: Array<{name:string,conclusion:string,runId:string|null}>, runIds: string[], reason: string }}
+ */
+function decideRerun(payload) {
+  const empty = (reason) => ({ should: false, checks: [], runIds: [], reason });
+  if (!payload || typeof payload !== 'object') return empty('no payload — fail closed');
+  if (isDegraded(payload)) return empty('degraded/torn read — fail closed');
+
+  const rc = payload.requiredChecks || {};
+  const failingNames = Array.isArray(rc.failing) ? rc.failing : [];
+  if (failingNames.length === 0) return empty('no failing required checks');
+
+  const failures = Array.isArray(payload.failures) ? payload.failures : [];
+  const conclByName = new Map();
+  const urlByName = new Map();
+  for (const f of failures) {
+    if (!f || !f.name) continue;
+    if (!conclByName.has(f.name)) {
+      conclByName.set(f.name, String(f.conclusion || '').toUpperCase());
+      urlByName.set(f.name, f.jobUrl || f.detailsUrl || null);
+    }
+  }
+
+  const picked = [];
+  for (const name of failingNames) {
+    const concl = conclByName.get(name);
+    if (!concl) return empty(`required check "${name}" has no known conclusion — cannot confirm flaky, fail closed`);
+    if (REAL_FAILURE_CONCLUSIONS.has(concl)) return empty(`required check "${name}" is a real failure (${concl}) — never rerun`);
+    if (!INFRA_CONCLUSIONS.has(concl)) return empty(`required check "${name}" conclusion ${concl} is not classified infrastructural — fail closed`);
+    picked.push({ name, conclusion: concl, runId: runIdFromUrl(urlByName.get(name)) });
+  }
+
+  const runIds = [...new Set(picked.map((p) => p.runId).filter(Boolean))];
+  if (runIds.length === 0) return empty('no run id derivable from failure jobUrl — fail closed');
+  return {
+    should: true,
+    checks: picked,
+    runIds,
+    reason: `all ${picked.length} failing required check(s) are infrastructural (${picked.map((p) => p.conclusion).join(', ')})`,
+  };
+}
+
+/**
+ * Compute the full auto-action decision from a `--pull --json` payload. Pure and
+ * independently testable — no I/O, no `gh`, no side effects.
+ *
+ * @param {object} payload
+ * @param {{ isFork?: boolean }} [opts]
+ * @returns {{ updateBranch: object, rerunFlaky: object }}
+ */
+function decideAutoActions(payload, opts = {}) {
+  return {
+    updateBranch: decideUpdateBranch(payload, opts),
+    rerunFlaky: decideRerun(payload),
+  };
+}
+
+module.exports = {
+  decideAutoActions,
+  decideUpdateBranch,
+  decideRerun,
+  runIdFromUrl,
+  isDegraded,
+  INFRA_CONCLUSIONS,
+  REAL_FAILURE_CONCLUSIONS,
+};

package/lib/pr-monitor/differ.js

@@ -0,0 +1,195 @@
+'use strict';
+
+/**
+ * PR-monitor differ — the PURE heart of the monitor. `diffSnapshots(prev, next)`
+ * returns the ordered candidate events for the transition between two normalized
+ * snapshots (see lib/pr-monitor/gather.js for the shape). No I/O, no clock, no
+ * randomness — same inputs always yield the same events, which is what makes the
+ * monitor deterministic and duplicate-free across restarts.
+ *
+ * Each event carries a CONTENT key (head sha, threadId, check name+sha, comment
+ * id, review author+commit, surface) so the journal can dedup by identity.
+ *
+ * @module pr-monitor/differ
+ */
+
+const { EVENT_TYPES: T, makeEvent } = require('./events');
+
+/** Index an array of objects by a key field into a Map. */
+function indexBy(list, field) {
+  const map = new Map();
+  for (const item of (Array.isArray(list) ? list : [])) {
+    if (item?.[field] != null) map.set(String(item[field]), item);
+  }
+  return map;
+}
+
+/** True when every check is green (none failed, none pending). */
+function allGreen(checks) {
+  const list = Array.isArray(checks) ? checks : [];
+  return list.length > 0 && list.every((c) => c.class === 'green');
+}
+
+/** head.pushed — the PR's head sha advanced. */
+function diffHead(prev, next, out) {
+  if (next.headSha && prev.headSha !== next.headSha) {
+    out.push(makeEvent(T.HEAD_PUSHED, next.headSha, { from: prev.headSha || null, to: next.headSha }));
+  }
+}
+
+/** check.failed / check.recovered / checks.green — keyed by name+sha. */
+function diffChecks(prev, next, out) {
+  const prevByName = indexBy(prev.checks, 'name');
+  for (const c of (next.checks || [])) {
+    const before = prevByName.get(String(c.name));
+    const wasFailed = before?.class === 'failed';
+    if (c.class === 'failed' && !wasFailed) {
+      out.push(makeEvent(T.CHECK_FAILED, `${c.name}:${next.headSha}`, { name: c.name }));
+    } else if (c.class === 'green' && wasFailed) {
+      out.push(makeEvent(T.CHECK_RECOVERED, `${c.name}:${next.headSha}`, { name: c.name }));
+    }
+  }
+  if (allGreen(next.checks) && !allGreen(prev.checks)) {
+    out.push(makeEvent(T.CHECKS_GREEN, next.headSha, {}));
+  }
+}
+
+/** thread.opened / thread.reply / thread.resolved — keyed by threadId. */
+function diffThreads(prev, next, out) {
+  const prevById = indexBy(prev.threads, 'threadId');
+  for (const t of (next.threads || [])) {
+    const before = prevById.get(String(t.threadId));
+    if (!before) {
+      if (t.actionable) out.push(makeEvent(T.THREAD_OPENED, t.threadId, { path: t.path || null }));
+      continue;
+    }
+    if ((t.commentCount || 0) > (before.commentCount || 0)) {
+      out.push(makeEvent(T.THREAD_REPLY, `${t.threadId}:${t.commentCount}`, { threadId: t.threadId }));
+    }
+    if (t.isResolved && !before.isResolved) {
+      out.push(makeEvent(T.THREAD_RESOLVED, t.threadId, {}));
+    }
+  }
+}
+
+/** comment.posted — a new direct PR issue comment, keyed by comment id. */
+function diffComments(prev, next, out) {
+  const prevIds = indexBy(prev.comments, 'id');
+  for (const c of (next.comments || [])) {
+    if (!prevIds.has(String(c.id))) {
+      out.push(makeEvent(T.COMMENT_POSTED, c.id, { author: c.author || '' }));
+    }
+  }
+}
+
+/** review.submitted — a new/updated review per author (state or commit changed). */
+function diffReviews(prev, next, out) {
+  const prevByAuthor = indexBy(prev.reviews, 'author');
+  for (const r of (next.reviews || [])) {
+    const before = prevByAuthor.get(String(r.author));
+    const changed = !before
+      || before.submittedAt !== r.submittedAt
+      || before.commitOid !== r.commitOid;
+    if (changed) {
+      out.push(makeEvent(T.REVIEW_SUBMITTED, `${r.author}:${r.commitOid || r.submittedAt}`, {
+        author: r.author, verdict: r.state, commitOid: r.commitOid || null,
+      }));
+    }
+  }
+}
+
+/** conflict.appeared / conflict.cleared — keyed by head sha. */
+function diffConflict(prev, next, out) {
+  if (next.conflicts === true && prev.conflicts !== true) {
+    out.push(makeEvent(T.CONFLICT_APPEARED, next.headSha, {}));
+  } else if (next.conflicts === false && prev.conflicts === true) {
+    out.push(makeEvent(T.CONFLICT_CLEARED, next.headSha, {}));
+  }
+}
+
+/** branch.behind — the branch fell behind its base. */
+function diffBehind(prev, next, out) {
+  if ((next.behind || 0) > 0 && (prev.behind || 0) === 0) {
+    out.push(makeEvent(T.BRANCH_BEHIND, `${next.headSha}:${next.behind}`, { behind: next.behind }));
+  }
+}
+
+/** verdict.changed — the fail-closed merge verdict flipped. */
+function diffVerdict(prev, next, out) {
+  const from = prev.verdict ? prev.verdict.state : null;
+  const to = next.verdict ? next.verdict.state : null;
+  if (from !== to) {
+    out.push(makeEvent(T.VERDICT_CHANGED, `${from}->${to}:${next.headSha}`, {
+      from, to, reason: next.verdict ? next.verdict.reason || null : null,
+    }));
+  }
+}
+
+/** pr.merged / pr.closed — terminal transitions from an OPEN PR. */
+function diffPrState(prev, next, out) {
+  if (prev.prState === 'OPEN' && next.prState === 'MERGED') {
+    out.push(makeEvent(T.PR_MERGED, 'MERGED', {}));
+  } else if (prev.prState === 'OPEN' && next.prState === 'CLOSED') {
+    out.push(makeEvent(T.PR_CLOSED, 'CLOSED', {}));
+  }
+}
+
+/** monitor.degraded — a read surface newly became unreadable (fail-closed). */
+function diffDegraded(prev, next, out) {
+  const prevSurfaces = new Set((prev.degraded || []).map((d) => d.surface));
+  for (const d of (next.degraded || [])) {
+    if (!prevSurfaces.has(d.surface)) {
+      out.push(makeEvent(T.MONITOR_DEGRADED, d.surface, { surface: d.surface, error: d.error || '' }));
+    }
+  }
+}
+
+/**
+ * Baseline events for the FIRST pass (no prior snapshot): a single verdict
+ * baseline plus any already-terminal/degraded state — bounded, never a replay of
+ * every historical thread/check.
+ */
+function diffBaseline(next, out) {
+  out.push(makeEvent(T.VERDICT_CHANGED, `baseline:${next.headSha}`, {
+    from: null, to: next.verdict ? next.verdict.state : null,
+    reason: next.verdict ? next.verdict.reason || null : null,
+  }));
+  if (next.prState === 'MERGED') out.push(makeEvent(T.PR_MERGED, 'MERGED', {}));
+  if (next.prState === 'CLOSED') out.push(makeEvent(T.PR_CLOSED, 'CLOSED', {}));
+  for (const d of (next.degraded || [])) {
+    out.push(makeEvent(T.MONITOR_DEGRADED, d.surface, { surface: d.surface, error: d.error || '' }));
+  }
+}
+
+/**
+ * Diff two normalized snapshots into ordered candidate events. `prev === null`
+ * → first-pass baseline.
+ *
+ * @param {object|null} prev
+ * @param {object} next
+ * @returns {Array<{ type: string, key: string, data: object }>}
+ */
+function diffSnapshots(prev, next) {
+  const out = [];
+  if (!prev) {
+    diffBaseline(next, out);
+    return out;
+  }
+  diffHead(prev, next, out);
+  diffChecks(prev, next, out);
+  diffThreads(prev, next, out);
+  diffComments(prev, next, out);
+  diffReviews(prev, next, out);
+  diffConflict(prev, next, out);
+  diffBehind(prev, next, out);
+  diffVerdict(prev, next, out);
+  diffPrState(prev, next, out);
+  diffDegraded(prev, next, out);
+  return out;
+}
+
+module.exports = {
+  diffSnapshots,
+  allGreen,
+  indexBy,
+};