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

package/lib/pr-monitor/reconcile-tick.js

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * The debounce / cost guard for the autonomous shepherd (W-S4 design §2).
+ *
+ * `tick()` is the cheap-path-first gate that fires from an arbitrary `forge`
+ * command (W-S4b wires the call site). Its whole job is to make the HOT path — a
+ * live daemon already converging — cost ~one `readFileSync` and return, so a
+ * per-command trigger never regresses into a `gh` call per command.
+ *
+ * Three gates:
+ *   G1  A fresh lease (heartbeat < STALE_MS) means a live daemon is converging —
+ *       do NOTHING (no stat, no enumerate, no spawn).
+ *   G2  The enumeration window (RECONCILE_MIN_INTERVAL) has not elapsed since the
+ *       last cold tick — skip enumeration.
+ *   G3  Cold tick: bump the sentinel mtime FIRST (throttle even if gh is slow),
+ *       then run the INJECTED enumerate()+reconcile()+execute().
+ *
+ * The sentinel file `<gitCommonDir>/forge/shepherd.reconcile` is the throttle
+ * stamp — its **mtime IS `last_enumerated_at`** (no content, no parse). It is a
+ * SEPARATE file from the token-guarded lease payload precisely because a tick
+ * fired by an arbitrary command does NOT hold the lease token and so cannot write
+ * the lease (design correction #3) — but any process may bump this sentinel.
+ *
+ * This module does NOT spawn — `enumerate`/`execute`/`reconcile` are injected, so
+ * the guard is fully testable with a fake clock + temp dir and 0 real I/O beyond
+ * the lock read and sentinel stat/bump. The daemon executor + spawn wiring are
+ * W-S4b.
+ *
+ * @module pr-monitor/reconcile-tick
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { STALE_MS } = require('./shepherd-lease');
+const { reconcile: defaultReconcile } = require('./reconcile');
+
+/** Default minimum interval between cold enumerations, per repo (ms). */
+const RECONCILE_MIN_INTERVAL = 60000;
+
+/** Resolve the enumeration window, honoring the env override at call time (tests). */
+function resolveMinInterval() {
+	const override = Number(process.env.FORGE_RECONCILE_MIN_INTERVAL);
+	return Number.isFinite(override) && override > 0 ? override : RECONCILE_MIN_INTERVAL;
+}
+
+function forgeDir(gitCommonDir) {
+	return path.join(gitCommonDir, 'forge');
+}
+function lockPath(gitCommonDir) {
+	return path.join(forgeDir(gitCommonDir), 'shepherd.lock');
+}
+function sentinelPath(gitCommonDir) {
+	return path.join(forgeDir(gitCommonDir), 'shepherd.reconcile');
+}
+
+/** Read + parse the lock payload, or null when missing/unreadable/corrupt. */
+function readLock(gitCommonDir) {
+	try {
+		return JSON.parse(fs.readFileSync(lockPath(gitCommonDir), 'utf8'));
+	} catch {
+		return null;
+	}
+}
+
+/** Stat the sentinel, or null when it does not exist yet. */
+function statSentinel(gitCommonDir) {
+	try {
+		return fs.statSync(sentinelPath(gitCommonDir));
+	} catch {
+		return null;
+	}
+}
+
+/** Bump the sentinel mtime to `t` (create it if absent). mtime IS last_enumerated_at. */
+function bumpSentinel(gitCommonDir, t) {
+	const file = sentinelPath(gitCommonDir);
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	if (!fs.existsSync(file)) fs.writeFileSync(file, '', { mode: 0o600 });
+	const secs = t / 1000;
+	fs.utimesSync(file, secs, secs);
+}
+
+/**
+ * Run one debounce tick. Returns `{ path: 'G1'|'G2'|'G3', actions? }` describing
+ * which gate fired (the `actions` are the reconcile output on the G3 cold path).
+ *
+ * Injected seams (all keep the guard hermetic — no gh/spawn/clock of its own):
+ *   now         () => ms          — clock (default Date.now)
+ *   enumerate   () => {desired, observed}   — the expensive gh∩kernel gather (G3 only)
+ *   execute     (actions) => void  — the action dispatcher (G3 only)
+ *   reconcile   (desired, observed, now) => {actions}  — pure core (default: the real one)
+ *   minInterval ms                 — enumeration window (default: env-or-60000)
+ */
+function tick({
+	gitCommonDir,
+	now = () => Date.now(),
+	enumerate,
+	execute,
+	reconcile = defaultReconcile,
+	minInterval = resolveMinInterval(),
+} = {}) {
+	const t = now();
+
+	// G1 — a fresh lease means a live daemon is converging. Do NOTHING (hot path:
+	// one readFileSync + JSON.parse, then return; no stat, no enumerate, no spawn).
+	const lock = readLock(gitCommonDir);
+	if (lock) {
+		const beat = Date.parse(lock.heartbeatAt);
+		if (Number.isFinite(beat) && (t - beat) < STALE_MS) {
+			return { path: 'G1' };
+		}
+	}
+
+	// G2 — the enumeration window has not elapsed since the last cold tick. Trust the
+	// last enumeration; skip the expensive gather. (Daemon revive on this path is W-S4b.)
+	const sentinelStat = statSentinel(gitCommonDir);
+	if (sentinelStat && (t - sentinelStat.mtimeMs) < minInterval) {
+		return { path: 'G2' };
+	}
+
+	// G3 — cold tick: no fresh lease AND the window elapsed. Bump the sentinel mtime
+	// FIRST so the throttle holds even if the enumerate() gh call is slow, THEN run the
+	// injected enumerate → reconcile → execute.
+	bumpSentinel(gitCommonDir, t);
+	const { desired, observed } = enumerate();
+	const { actions } = reconcile(desired, observed, t);
+	execute(actions);
+	return { path: 'G3', actions };
+}
+
+module.exports = {
+	tick,
+	RECONCILE_MIN_INTERVAL,
+	resolveMinInterval,
+	lockPath,
+	sentinelPath,
+};

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 -->';
@@ -119,6 +147,10 @@ function renderChecks(bundle, lines) {
  * @param {object} bundle - a `gatherPrBundle` result (lib/pr-bundle.js).
  * @param {object} [opts]
  * @param {Date}   [opts.now] - injected clock for deterministic output.
+ * @param {string} [opts.verdict] - the canonical `--pull` verdict.
+ * @param {string[]} [opts.unreadable] - unreadable signal names (from the `--pull`
+ *   evidence). Surfaced when the verdict is UNKNOWN so the sticky always says WHICH
+ *   signal could not be read, not just a bare `unknown`.
  * @returns {{ marker: string, body: string }}
  */
 function renderStickyComment(bundle = {}, opts = {}) {
@@ -130,7 +162,23 @@ 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));
+  // An `unknown` verdict is useless without the WHY — name the unreadable
+  // signal(s) so a human/agent knows what to fix (e.g. `requiredChecks` when both
+  // branch-protection AND the rollup fallback could not be read).
+  const verdictUpper = String(opts.verdict || '').toUpperCase();
+  const isUnknown = verdictUpper === 'UNKNOWN' || !VERDICT_HEADLINE[verdictUpper];
+  const unreadable = Array.isArray(opts.unreadable) ? opts.unreadable.filter(Boolean) : [];
+  if (isUnknown && unreadable.length > 0) {
+    lines.push('');
+    lines.push(`> Unreadable signal(s): ${unreadable.map((s) => `\`${s}\``).join(', ')}.`);
+  }
+  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 +191,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/shepherd-lease.js

@@ -0,0 +1,243 @@
+'use strict';
+
+/**
+ * Shepherd singleton lease — a machine-wide "one watcher-set" guard for the PR
+ * shepherd, fusing two existing precedents:
+ *
+ *   - `serve.lock`'s exclusive-create + foreign-PID block + stale reclaim
+ *     (`lib/commands/_serve-security.js`), so a live foreign owner is never
+ *     stolen but a dead/wedged one is reclaimed.
+ *   - the journal lock's heartbeat + TTL staleness
+ *     (`lib/pr-monitor/journal.js`), so a slow-but-alive owner refreshes its
+ *     timestamp and a crashed owner ages out.
+ *
+ * The lock lives at `<gitCommonDir>/forge/shepherd.lock`, keyed by the SAME
+ * `resolveGitCommonDir` the kernel DB uses — so every worktree of a repo shares
+ * one lock. This module is the lease PRIMITIVE only: pure fs + I/O, no spawned
+ * process and no reconcile loop (the daemon wires those up later).
+ *
+ * Payload JSON: `{ pid, token, startedAt, heartbeatAt, watchers: [prNumbers] }`.
+ *
+ * ## Ownership is by TOKEN, not pid
+ * Each successful `acquire` mints a unique `token`. Every mutating op
+ * (`stamp`/`updateWatchers`/`release`) verifies that token against the on-disk
+ * lock before writing. A pid can be reused after a crash/reboot, and a wedged
+ * owner can revive after its lease was reclaimed — in both cases the token no
+ * longer matches, so the superseded holder can never resurrect or mutate a lease
+ * it no longer owns. Takeover of a stale lock is made atomic by an O_EXCL create
+ * (only one racer can win it), so two processes reclaiming the same stale lock
+ * can never both succeed.
+ *
+ * @module pr-monitor/shepherd-lease
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { resolveGitCommonDir } = require('../kernel/broker');
+
+/** A wedged owner whose heartbeat is older than this (ms) is reclaimable. */
+const STALE_MS = 30000;
+const LOCK_FILE_MODE = 0o600;
+
+/**
+ * Resolve the shared lock path. `gitCommonDir` may be injected (tests, or a
+ * caller that already resolved it); otherwise it is resolved from `projectRoot`
+ * with the same resolver the kernel broker uses.
+ */
+function lockFilePath(projectRoot, opts = {}) {
+  const gitCommonDir = opts.gitCommonDir
+    ? path.resolve(opts.gitCommonDir)
+    : resolveGitCommonDir(projectRoot, opts);
+  return path.join(gitCommonDir, 'forge', 'shepherd.lock');
+}
+
+/** Parse the lock payload, or null when missing/unreadable/corrupt. */
+function readLock(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Is `pid` a live process? `process.kill(pid, 0)` sends no signal but throws
+// ESRCH when the pid is gone. EPERM means it exists but isn't ours — still live.
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+/** Is a held lock stale (dead owner, or heartbeat older than STALE_MS)? */
+function isHeldStale(held, { isAlive, now }) {
+  if (!isAlive(held.pid)) return true;
+  const beat = Date.parse(held.heartbeatAt);
+  if (!Number.isFinite(beat)) return true;
+  return now() - beat >= STALE_MS;
+}
+
+/**
+ * A lock is "ours" iff its unique lease `token` matches the one `acquire`
+ * returned. Token is authoritative: a pid can be reused after a crash/reboot and
+ * a wedged owner can revive after being reclaimed, so a pid match alone is NOT
+ * proof of ownership. Only a hypothetical legacy lock with no `token` field falls
+ * back to pid comparison.
+ */
+function ownsLock(held, { token, pid }) {
+  if (held.token) return token !== undefined && held.token === token;
+  return held.pid === pid;
+}
+
+function writeLock(file, payload) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(payload), { mode: LOCK_FILE_MODE });
+}
+
+/**
+ * Atomically create the lock with O_EXCL and write `payload`. Returns true when
+ * we won the create, false on EEXIST (a concurrent contender holds it); other
+ * errors rethrow. The O_EXCL create is the single atomic arbiter — of N racers
+ * attempting it against the same absent path, exactly one succeeds.
+ */
+function tryExclusiveCreate(file, payload) {
+  let fd;
+  try {
+    fd = fs.openSync(file, 'wx', LOCK_FILE_MODE);
+  } catch (err) {
+    if (err.code === 'EEXIST') return false;
+    throw err;
+  }
+  try {
+    fs.writeSync(fd, JSON.stringify(payload));
+  } finally {
+    fs.closeSync(fd);
+  }
+  return true;
+}
+
+/**
+ * Try to claim the singleton lease.
+ *   -> { ok:true, file, token }              first claim
+ *   -> { ok:true, file, token, reclaimed }   stale lock (dead/wedged owner) reclaimed
+ *   -> { ok:false, held }                    a LIVE, FRESH foreign owner holds it
+ *   -> { ok:false, held }                    we lost the atomic takeover race
+ *
+ * `pid`/`isAlive`/`now`/`token` are injectable for testing. `onBeforeTakeover` is
+ * a test seam invoked AFTER the stale lock is removed and BEFORE our exclusive
+ * re-create, so a test can simulate a competitor winning the O_EXCL create first
+ * (making our takeover lose).
+ */
+function acquire(projectRoot, {
+  gitCommonDir,
+  pid = process.pid,
+  isAlive = pidAlive,
+  now = () => Date.now(),
+  token = crypto.randomUUID(),
+  onBeforeTakeover = null,
+} = {}) {
+  const file = lockFilePath(projectRoot, { gitCommonDir });
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const iso = new Date(now()).toISOString();
+  const payload = { pid, token, startedAt: iso, heartbeatAt: iso, watchers: [] };
+
+  // Fast path: atomic exclusive create. Only ONE caller can win O_EXCL.
+  if (tryExclusiveCreate(file, payload)) {
+    return { ok: true, file, token };
+  }
+
+  // A lock exists. A DIFFERENT, live, fresh owner blocks us.
+  const held = readLock(file);
+  if (held && held.pid !== pid && !isHeldStale(held, { isAlive, now })) {
+    return { ok: false, held };
+  }
+
+  // Stale (dead/wedged owner, unreadable, or already ours). Take over ATOMICALLY:
+  // remove the stale lock, then re-create it with O_EXCL. If a competitor
+  // recreated it first, our exclusive create fails (EEXIST) and we back off — so
+  // two racers reclaiming the same stale lock can NEVER both win. A wedged owner
+  // that revives after we delete its lock is stopped by the per-lease `token`
+  // guard on stamp()/updateWatchers()/release(), never able to resurrect it here.
+  fs.rmSync(file, { force: true });
+  if (typeof onBeforeTakeover === 'function') onBeforeTakeover();
+  if (!tryExclusiveCreate(file, payload)) {
+    return { ok: false, held: readLock(file) };
+  }
+  return { ok: true, file, token, reclaimed: true };
+}
+
+/**
+ * Refresh `heartbeatAt` on OUR lock. Returns false (a no-op) when the lock is
+ * missing or NOT ours by `token` — we never stamp a lease we no longer own, so a
+ * revived wedged owner cannot resurrect a reclaimed lease.
+ */
+function stamp(projectRoot, { gitCommonDir, token, pid = process.pid, now = () => Date.now() } = {}) {
+  const file = lockFilePath(projectRoot, { gitCommonDir });
+  const held = readLock(file);
+  if (!held || !ownsLock(held, { token, pid })) return false;
+  held.heartbeatAt = new Date(now()).toISOString();
+  writeLock(file, held);
+  return true;
+}
+
+/**
+ * Start a heartbeat timer that stamps `heartbeatAt` every STALE_MS/3. The timer
+ * is `.unref()`ed so it never keeps the process alive. `opts` MUST carry the
+ * `token` returned by `acquire` (threaded straight through to `stamp`). Returns
+ * the handle for `stopHeartbeat`.
+ */
+function startHeartbeat(projectRoot, opts = {}) {
+  const timer = setInterval(() => stamp(projectRoot, opts), Math.max(1, Math.floor(STALE_MS / 3)));
+  if (typeof timer.unref === 'function') timer.unref();
+  return timer;
+}
+
+/** Stop a heartbeat timer started by `startHeartbeat`. */
+function stopHeartbeat(timer) {
+  if (timer) clearInterval(timer);
+}
+
+/**
+ * Rewrite the `watchers[]` array on OUR lock. Returns false when the lock is
+ * missing or NOT ours by `token`.
+ */
+function updateWatchers(projectRoot, prNumbers, { gitCommonDir, token, pid = process.pid } = {}) {
+  const file = lockFilePath(projectRoot, { gitCommonDir });
+  const held = readLock(file);
+  if (!held || !ownsLock(held, { token, pid })) return false;
+  held.watchers = Array.isArray(prNumbers) ? prNumbers : [];
+  writeLock(file, held);
+  return true;
+}
+
+/**
+ * Release the lease — delete the lock ONLY when it is ours by `token`, so a
+ * foreign or already-reclaimed lock is never removed out from under its owner
+ * (and a reused pid can never delete someone else's lease).
+ */
+function release(projectRoot, { gitCommonDir, token, pid = process.pid } = {}) {
+  const file = lockFilePath(projectRoot, { gitCommonDir });
+  try {
+    const held = readLock(file);
+    if (held && ownsLock(held, { token, pid })) fs.rmSync(file, { force: true });
+  } catch {
+    /* best effort — a failed release just leaves a stale lock to be reclaimed */
+  }
+}
+
+module.exports = {
+  STALE_MS,
+  lockFilePath,
+  pidAlive,
+  ownsLock,
+  acquire,
+  stamp,
+  startHeartbeat,
+  stopHeartbeat,
+  updateWatchers,
+  release,
+};

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', windowsHide: true }); // NOSONAR S4036 - hardcoded CLI (gh), args array (no shell), developer-tool context. windowsHide: sticky upsert runs in the detached watcher (issue 931e7924).
+}
+
+/**
+ * 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,
+};

package/lib/pr-monitor/watch-lifecycle.js

@@ -35,7 +35,7 @@ function forgeBin() {
 function defaultResolveSlug({ cwd, exec = execFileSync }) {
   try {
     const url = exec('git', ['remote', 'get-url', 'origin'], {
-      cwd, encoding: 'utf8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'],
+      cwd, encoding: 'utf8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true,
     }).trim();
     const match = /[/:][^/]+\/([^/]+?)(?:\.git)?$/.exec(url);
     return match ? match[1] : null;