forge-workflow 0.1.0-beta.2 → 0.1.0-beta.3

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/digest.js

@@ -0,0 +1,206 @@
+'use strict';
+
+/**
+ * PR-shepherd digest — the thin CONSUMER half of the constant monitor (epic
+ * c2d398e5, 33e1bbd3). The constant watch loop is the PRODUCER: it writes the
+ * per-PR NDJSON journals under `.forge/pr-monitor/<repo>-<pr>/` (the `forge
+ * shepherd events` pull surface reads those same records back). Nothing, though,
+ * surfaced those events to a working agent. This module is a pure READER: it
+ * reads the NEW budget events across all PR journals since a persisted per-PR
+ * CONSUMER cursor, renders a COMPACT capped summary, and advances the cursor —
+ * the exact payload a harness hook (Claude UserPromptSubmit) injects each turn.
+ *
+ * The CORE (events/journal/watch/monitor) is untouched: this only READS the
+ * journal via `journal.readEventsSince` and keeps its OWN `consumer.cursor`
+ * (distinct from the watcher's snapshot), so consumption never disturbs
+ * production. Every function is fail-open — a bad journal degrades to skipped,
+ * never throws — because it feeds a hook that must never block a prompt.
+ *
+ * @module pr-monitor/digest
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const journalMod = require('./journal');
+
+/**
+ * The event types worth surfacing on each turn — the ACTIONABLE transitions
+ * (verdict flip, a failed check, a new review thread, terminal merge/close).
+ * Everything else (head pushes, green checks, degraded notices) stays in the
+ * journal for `forge shepherd events` but is NOT pushed, to keep the injected
+ * context tiny.
+ */
+const BUDGET_TYPES = Object.freeze(new Set([
+  'verdict.changed', 'check.failed', 'thread.opened', 'pr.merged', 'pr.closed',
+]));
+
+const DEFAULT_CAP = 8;
+const CONSUMER_CURSOR_FILE = 'consumer.cursor';
+
+/** Absolute `.forge/pr-monitor` root for a project. */
+function monitorRoot(root) {
+  return path.join(root, '.forge', 'pr-monitor');
+}
+
+/** The per-PR consumer cursor path (distinct from the watcher's snapshot/pid). */
+function cursorPath(dir) {
+  return path.join(dir, CONSUMER_CURSOR_FILE);
+}
+
+/**
+ * List absolute PR journal dirs (those containing an events.ndjson). Fail-open:
+ * a missing monitor root or unreadable dir yields []. Injectable fs for tests.
+ *
+ * @param {string} root
+ * @param {{ readdirSync?: Function, existsSync?: Function }} [deps]
+ * @returns {string[]}
+ */
+function discoverPrDirs(root, deps = {}) {
+  const readdir = deps.readdirSync || fs.readdirSync;
+  const exists = deps.existsSync || fs.existsSync;
+  try {
+    return readdir(monitorRoot(root), { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => path.join(monitorRoot(root), e.name))
+      .filter((dir) => exists(path.join(dir, 'events.ndjson')));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read a PR's consumer cursor (the last consumed seq). Fail-open → 0 (no cursor,
+ * unreadable, or malformed all mean "start from the beginning").
+ *
+ * @param {string} dir
+ * @param {{ readFileSync?: Function }} [deps]
+ * @returns {number}
+ */
+function readConsumerCursor(dir, deps = {}) {
+  const readFile = deps.readFileSync || fs.readFileSync;
+  try {
+    const obj = JSON.parse(readFile(cursorPath(dir), 'utf8'));
+    const seq = Number(obj && obj.seq);
+    return Number.isFinite(seq) && seq >= 0 ? seq : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Persist a PR's consumer cursor. Fail-open: an unwritable cursor returns false
+ * (next turn re-reads the same events — a duplicate nudge, never a crash).
+ *
+ * @param {string} dir
+ * @param {number} seq
+ * @param {{ writeFileSync?: Function }} [deps]
+ * @returns {boolean}
+ */
+function writeConsumerCursor(dir, seq, deps = {}) {
+  const writeFile = deps.writeFileSync || fs.writeFileSync;
+  try {
+    writeFile(cursorPath(dir), `${JSON.stringify({ seq: Number(seq) || 0 })}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A compact one-line label for a budget event. PURE. Bounded so injected context
+ * stays tiny; the full record is always available via `forge shepherd events`.
+ *
+ * @param {object} e - a journal event.
+ * @returns {string}
+ */
+function renderEventLine(e) {
+  const pr = e.pr != null ? `#${e.pr}` : '#?';
+  const d = e.data || {};
+  let detail;
+  switch (e.type) {
+    case 'verdict.changed': detail = (e.verdict && (e.verdict.verdict || e.verdict.state)) || d.verdict || d.to || ''; break;
+    case 'check.failed': detail = d.name || d.check || ''; break;
+    case 'thread.opened': detail = d.author ? `by ${d.author}` : (d.path || ''); break;
+    case 'pr.merged': detail = 'merged'; break;
+    case 'pr.closed': detail = 'closed'; break;
+    default: detail = '';
+  }
+  const suffix = detail ? `: ${String(detail).slice(0, 60)}` : '';
+  return `- PR ${pr} ${e.type}${suffix}`;
+}
+
+/**
+ * PURE: filter events to the budget types, cap the count, and render lines.
+ *
+ * @param {object[]} events
+ * @param {{ cap?: number }} [opts]
+ * @returns {{ lines: string[], total: number }}
+ */
+function renderDigestLines(events, { cap = DEFAULT_CAP } = {}) {
+  const budget = (Array.isArray(events) ? events : []).filter((e) => e && BUDGET_TYPES.has(e.type));
+  const lines = budget.map(renderEventLine);
+  return { lines: lines.slice(0, cap), total: lines.length };
+}
+
+/**
+ * Format the compact injected block (a header + capped lines + an overflow
+ * pointer), or '' when there is nothing to surface. PURE.
+ */
+function formatBlock(lines, total, cap, prs) {
+  if (lines.length === 0) return '';
+  const on = prs.length ? ` on PR(s) ${prs.join(', ')}` : '';
+  const more = total > cap ? `\n(+${total - cap} more — see \`forge shepherd events <pr> --since <seq>\`)` : '';
+  return `[forge PR shepherd] ${total} new event(s)${on}:\n${lines.join('\n')}${more}`;
+}
+
+/**
+ * Collect a compact digest of NEW budget events across every PR journal since the
+ * per-PR consumer cursor, advancing each cursor past EVERYTHING read (budget and
+ * non-budget alike, so skipped types never re-surface). Fail-open throughout.
+ *
+ * @param {object} args
+ * @param {string} args.root - project root.
+ * @param {object} [args.journal] - journal module (test injection).
+ * @param {number} [args.cap] - max lines in the block.
+ * @param {object} [args.fsDeps] - injectable fs for discovery + cursor I/O.
+ * @returns {{ text: string, total: number, prs: string[] }}
+ */
+function collectDigest({ root, journal = journalMod, cap = DEFAULT_CAP, fsDeps = {} } = {}) {
+  const dirs = discoverPrDirs(root, fsDeps);
+  const allLines = [];
+  const prs = new Set();
+  for (const dir of dirs) {
+    const cursor = readConsumerCursor(dir, fsDeps);
+    let evs;
+    try {
+      evs = journal.readEventsSince(dir, cursor);
+    } catch {
+      evs = [];
+    }
+    if (!Array.isArray(evs) || evs.length === 0) continue;
+    const maxSeq = evs.reduce((m, e) => Math.max(m, Number(e.seq) || 0), cursor);
+    for (const e of evs) {
+      if (!e || !BUDGET_TYPES.has(e.type)) continue;
+      allLines.push(renderEventLine(e));
+      if (e.pr != null) prs.add(String(e.pr));
+    }
+    writeConsumerCursor(dir, maxSeq, fsDeps);
+  }
+  const capped = allLines.slice(0, cap);
+  return { text: formatBlock(capped, allLines.length, cap, [...prs]), total: allLines.length, prs: [...prs] };
+}
+
+module.exports = {
+  BUDGET_TYPES,
+  DEFAULT_CAP,
+  monitorRoot,
+  cursorPath,
+  discoverPrDirs,
+  readConsumerCursor,
+  writeConsumerCursor,
+  renderEventLine,
+  renderDigestLines,
+  formatBlock,
+  collectDigest,
+};

package/lib/pr-monitor/render-sticky.js

@@ -5,12 +5,13 @@
  * result (lib/pr-bundle.js) into the Markdown body of the single sticky PR
  * comment the pr-monitor GitHub workflow keeps up to date.
  *
- * This is the SURFACE half of the monitor: it lists the unresolved review
- * threads (grouped by author, ANY author) plus the failing and pending checks
- * so async review-bot / human feedback in a window nobody is watching cannot
- * rot. It is deliberately NOT a merge decision — it never emits a pass/fail
- * verdict and never claims a PR is ready to merge. That belongs to the
- * trustworthy-shepherd redesign, not here.
+ * This is the SURFACE half of the monitor: it leads with the one-line actionable
+ * verdict (mirroring the `pr-verdict:*` label the workflow lands), then lists the
+ * unresolved review threads (grouped by author, ANY author) plus the failing and
+ * pending checks so async review-bot / human feedback in a window nobody is
+ * watching cannot rot. The verdict LABELS state (check-failed / threads-open /
+ * mergeable / …); it is NOT a merge action — it never merges, never resolves
+ * threads, never blocks, and is fail-closed (`unknown` on unreadable signals).
  *
  * Pure and deterministic: same bundle + same injected clock → same body, which
  * is what lets the workflow rewrite the sticky comment in place without churn.
@@ -18,6 +19,33 @@
  * @module pr-monitor/render-sticky
  */
 
+/**
+ * Presentation-only headline for each canonical merge verdict (lib/pr-pull.js).
+ * The verdict VALUE is computed once by pr-pull (`forge shepherd --pull --json`)
+ * and passed in — this map only decides how to DISPLAY it, so there is no second
+ * verdict ladder to drift.
+ */
+const VERDICT_HEADLINE = {
+  UNKNOWN: '⚪ **Verdict: `unknown`** — a signal was unreadable; state unconfirmed (fail-closed).',
+  'BLOCKED-CONFLICT': '🔀 **Verdict: `blocked-conflict`** — branch conflicts with base; rebase/merge and resolve.',
+  BEHIND: '⬇️ **Verdict: `behind`** — branch is behind base; update/rebase (protection requires up-to-date).',
+  'BLOCKED-CHECKS': '🔴 **Verdict: `blocked-checks`** — a required check is failing/missing; fix it.',
+  'BLOCKED-THREADS': '🟠 **Verdict: `blocked-threads`** — unresolved review threads need addressing.',
+  'REVIEW-PENDING': '🟡 **Verdict: `review-pending`** — awaiting review / settle window; not ready yet.',
+  'CLEAN-MERGEABLE': '🟢 **Verdict: `clean-mergeable`** — green + zero unresolved threads; ready for a human to merge.',
+};
+
+/**
+ * Render the one-line verdict headline for a canonical verdict string. Unknown or
+ * missing input falls closed to the `unknown` headline.
+ *
+ * @param {string} verdict
+ * @returns {string}
+ */
+function verdictHeadline(verdict) {
+  return VERDICT_HEADLINE[String(verdict || '').toUpperCase()] || VERDICT_HEADLINE.UNKNOWN;
+}
+
 /** Hidden HTML marker: the workflow finds its prior comment by this string and
  * UPDATES it in place, so the monitor never spams a PR with new comments. */
 const STICKY_MARKER = '<!-- forge-pr-monitor -->';
@@ -130,7 +158,13 @@ function renderStickyComment(bundle = {}, opts = {}) {
   lines.push(STICKY_MARKER);
   lines.push('## 🔭 Forge PR Monitor');
   lines.push('');
-  lines.push('_Surfaces open review + check state so async feedback never rots. This monitor **does not merge** and does not post a pass/fail verdict._');
+  // Lead with the actionable verdict — the SAME value as the pr-verdict:* label
+  // and `forge shepherd --pull --json` (passed in via opts.verdict, computed once
+  // by pr-pull). Surface only: it labels state; this monitor **does not merge**
+  // and never resolves review threads.
+  lines.push(verdictHeadline(opts.verdict));
+  lines.push('');
+  lines.push('_Surfaces open review + check state so async feedback never rots. This monitor **does not merge** and never resolves review threads — a human merges in the GitHub UI._');
   lines.push('');
 
   renderThreads(bundle, lines);
@@ -143,13 +177,14 @@ function renderStickyComment(bundle = {}, opts = {}) {
   }
 
   lines.push('---');
-  lines.push(`<sub>Updated ${now.toISOString()} · surface-only monitor · never merges, never verdicts.</sub>`);
+  lines.push(`<sub>Updated ${now.toISOString()} · surface-only monitor · labels state, never merges, never resolves threads.</sub>`);
 
   return { marker: STICKY_MARKER, body: lines.join('\n') };
 }
 
 module.exports = {
   renderStickyComment,
+  verdictHeadline,
   groupByAuthor,
   threadLocator,
   STICKY_MARKER,

package/lib/pr-monitor/upsert-sticky.js

@@ -0,0 +1,169 @@
+'use strict';
+
+/**
+ * PR-monitor sticky-comment upsert — race-safe, converges to EXACTLY ONE sticky
+ * comment per PR even under a concurrent burst of workflow runs.
+ *
+ * Why this exists: the pr-monitor workflow deliberately has NO `concurrency:`
+ * group. A per-PR group does not help — GitHub's queue replacement cancels the
+ * previously-PENDING run in a group UNCONDITIONALLY (independent of
+ * cancel-in-progress), and this workflow's triggers (check_suite:completed fires
+ * ~10+ times per push, plus reviews/comments) burst hard, so a group left a trail
+ * of CANCELLED runs that render as red/non-SUCCESS checks and tripped merge-gate
+ * tooling (kernel issue 97e6a146). Dropping the group removes the cancellations,
+ * but then two concurrent first-runs on a PR with no sticky yet would BOTH find
+ * nothing and BOTH create one → duplicate sticky comments. This module closes
+ * that race deterministically instead.
+ *
+ * Reconcile-to-one algorithm:
+ *   1. List marker comments. If none, create one, then RE-LIST (a concurrent run
+ *      may have created its own in the same burst).
+ *   2. Pick the deterministic survivor: the LOWEST comment id (oldest). Every
+ *      concurrent run picks the SAME survivor, so they never fight.
+ *   3. Update the survivor with the latest body; delete every other marker
+ *      comment. Deletes are idempotent (a 404 means a peer already removed it).
+ *
+ * A create that lands AFTER a run's re-list is self-healed by the next event:
+ * every run reconciles to one, and events keep arriving, so the PR converges to a
+ * single sticky comment.
+ *
+ * @module pr-monitor/upsert-sticky
+ */
+
+const { execFileSync } = require('node:child_process');
+
+/** Ids of comments whose body carries the sticky marker. */
+function markerCommentIds(comments, marker) {
+  return (Array.isArray(comments) ? comments : [])
+    .filter((comment) => typeof comment.body === 'string' && comment.body.includes(marker))
+    .map((comment) => comment.id);
+}
+
+/** Ascending by numeric id, so the survivor (index 0) is the oldest comment. */
+function sortIdsAscending(ids) {
+  return [...ids].sort((left, right) => Number(left) - Number(right));
+}
+
+/**
+ * Drive a client to exactly one sticky comment. `client` abstracts the GitHub
+ * calls so the reconcile logic is unit-testable without the network:
+ *   - list()        → array of { id, body }
+ *   - create()      → create a new sticky comment (body supplied by the client)
+ *   - update(id)    → overwrite comment `id` with the latest body
+ *   - remove(id)    → delete comment `id` (must tolerate an already-deleted 404)
+ *
+ * @returns {Promise<{ survivor: (number|string|null), deleted: Array<number|string> }>}
+ */
+async function upsertStickyComment({ marker }, client) {
+  let ids = markerCommentIds(await client.list(), marker);
+
+  if (ids.length === 0) {
+    await client.create();
+    // Re-list: a concurrent run may have created its own sticky in this burst.
+    ids = markerCommentIds(await client.list(), marker);
+  }
+
+  if (ids.length === 0) {
+    // The just-created comment is not visible yet (eventual consistency); its
+    // body is already correct, and the next event will reconcile if a peer raced.
+    return { survivor: null, deleted: [] };
+  }
+
+  ids = sortIdsAscending(ids);
+  const survivor = ids[0];
+  await client.update(survivor);
+
+  const deleted = [];
+  for (const id of ids.slice(1)) {
+    await client.remove(id);
+    deleted.push(id);
+  }
+
+  return { survivor, deleted };
+}
+
+// Single choke point for the `gh` CLI, matching lib/commands/merge.js. `gh` is a
+// hardcoded literal (never user input) and args are an array (no shell), so the
+// S4036 PATH-search finding is a false positive in this developer-tool context;
+// one annotation here covers every call site. `encoding: 'utf8'` also pipes
+// stderr onto the thrown error, so isAlreadyGone() below can classify failures.
+function runGh(args) {
+  return execFileSync('gh', args, { encoding: 'utf8' }); // NOSONAR S4036 - hardcoded CLI (gh), args array (no shell), developer-tool context
+}
+
+/**
+ * True only when a `gh api` failure means the target comment is already absent
+ * (HTTP 404 / 410) — the benign "a peer got there first" case. Auth failures,
+ * rate limits (403), and every other error return false so they propagate and
+ * surface a diagnostic instead of silently breaking the exactly-one invariant.
+ */
+function isAlreadyGone(error) {
+  const text = `${error && error.stderr ? error.stderr : ''} ${error && error.message ? error.message : ''}`;
+  return /HTTP 404|HTTP 410|\bNot Found\b|\bGone\b/i.test(text);
+}
+
+/**
+ * GitHub-backed client (shells to `gh api`, like lib/pr-monitor/gather.js). The
+ * reconcile logic above is unit-tested; the error-tolerance in update/remove is
+ * too, via an injectable `run`. create/update both send the same pre-rendered
+ * payload file the render step wrote, so the body is identical.
+ */
+function ghStickyClient({ repo, pr, payloadFile, run = runGh }) {
+  return {
+    async list() {
+      const out = run(['api', `repos/${repo}/issues/${pr}/comments`, '--paginate']);
+      return out && out.trim() ? JSON.parse(out) : [];
+    },
+    async create() {
+      run(['api', '-X', 'POST', `repos/${repo}/issues/${pr}/comments`, '--input', payloadFile]);
+    },
+    async update(id) {
+      try {
+        run(['api', '-X', 'PATCH', `repos/${repo}/issues/comments/${id}`, '--input', payloadFile]);
+      } catch (error) {
+        if (!isAlreadyGone(error)) {
+          throw error;
+        }
+        // Our chosen survivor was deleted by a peer whose survivor had a lower id:
+        // the peer's sticky wins, exactly-one still holds, so we are done.
+      }
+    },
+    async remove(id) {
+      try {
+        run(['api', '-X', 'DELETE', `repos/${repo}/issues/comments/${id}`]);
+      } catch (error) {
+        if (!isAlreadyGone(error)) {
+          throw error;
+        }
+        // Already gone (a concurrent run deleted it first) — the goal state holds.
+      }
+    },
+  };
+}
+
+async function main() {
+  const repo = process.env.GH_REPO;
+  const pr = process.env.PR;
+  const payloadFile = process.env.STICKY_PAYLOAD_FILE || 'monitor-payload.json';
+  const { STICKY_MARKER } = require('./render-sticky');
+
+  const client = ghStickyClient({ repo, pr, payloadFile });
+  const { survivor, deleted } = await upsertStickyComment({ marker: STICKY_MARKER }, client);
+  const survivorLabel = survivor === null ? 'created (not yet visible)' : survivor;
+  console.log(`Sticky comment reconciled to one: survivor=${survivorLabel}, deleted=${deleted.length}`);
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  upsertStickyComment,
+  markerCommentIds,
+  sortIdsAscending,
+  isAlreadyGone,
+  ghStickyClient,
+};