forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/pr-monitor/journal.js

@@ -0,0 +1,299 @@
+'use strict';
+
+/**
+ * PR-monitor journal — per-PR append-only NDJSON event log plus an atomic
+ * snapshot fingerprint, under `.forge/pr-monitor/<repo>-<pr>/`. The journal is
+ * the CURSOR AUTHORITY: it survives crashes and is shared across processes and
+ * worktrees, and works with no kernel configured. A consumer keeps its own `seq`
+ * cursor and reads new events with `readEventsSince`.
+ *
+ * Ordering contract (exactly-once): a monitor pass APPENDS events, THEN writes
+ * the snapshot together with an `appliedSeq` cursor (the highest seq that
+ * snapshot accounts for). If a crash lands between the append and the snapshot
+ * write, the persisted `appliedSeq` still points BEFORE the just-appended tail,
+ * so the next pass re-diffs the old snapshot, recomputes the same `(type,key)`
+ * events, and `seenIdentities(dir, appliedSeq)` filters exactly that pending tail
+ * — no duplicate is ever journaled. Crucially the dedup is scoped to that
+ * pending/crash-recovery window, NOT the whole journal history: a value that
+ * flips back to a prior state (fail → green → fail on the same sha) legitimately
+ * re-emits, because the earlier identity sits at/below `appliedSeq`.
+ *
+ * Concurrency: multiple processes/worktrees can poll the same PR. The
+ * read→diff→dedup→append→snapshot critical section is serialized across
+ * processes by `withJournalLock` (a crash-recoverable lock-directory), so
+ * concurrent passes can never interleave appends or reuse a sequence number.
+ *
+ * @module pr-monitor/journal
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { eventIdentity } = require('./events');
+
+/** Sanitize a repo slug for a filesystem directory name. */
+function sanitize(part) {
+  return String(part || '').replace(/[^A-Za-z0-9._-]+/g, '-');
+}
+
+/**
+ * Resolve (and create) the per-PR journal directory.
+ *
+ * @param {{ root: string, repo: string, pr: string|number }} ctx
+ * @returns {string} absolute directory path
+ */
+function journalDir({ root, repo, pr }) {
+  const dir = path.join(root, '.forge', 'pr-monitor', `${sanitize(repo)}-${sanitize(pr)}`);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function journalPath(dir) { return path.join(dir, 'events.ndjson'); }
+function snapshotPath(dir) { return path.join(dir, 'snapshot.json'); }
+function pidPath(dir) { return path.join(dir, 'watch.pid'); }
+function lockPath(dir) { return path.join(dir, 'journal.lock'); }
+
+/**
+ * Read all journal records (NDJSON), skipping any unparseable line so one
+ * corrupt tail line never blinds the cursor.
+ *
+ * @param {string} dir
+ * @returns {object[]}
+ */
+function readAllEvents(dir) {
+  const file = journalPath(dir);
+  if (!fs.existsSync(file)) return [];
+  const out = [];
+  for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try { out.push(JSON.parse(trimmed)); } catch { /* skip corrupt line */ }
+  }
+  return out;
+}
+
+/** Records with `seq > sinceSeq`, in journal order. */
+function readEventsSince(dir, sinceSeq) {
+  const since = Number(sinceSeq) || 0;
+  return readAllEvents(dir).filter((e) => Number(e.seq) > since);
+}
+
+/** Highest `seq` recorded so far (0 when empty). */
+function lastSeq(dir) {
+  let max = 0;
+  for (const e of readAllEvents(dir)) {
+    const s = Number(e.seq) || 0;
+    if (s > max) max = s;
+  }
+  return max;
+}
+
+/**
+ * Set of `(type,key)` identities journaled with `seq > sinceSeq` — the dedup
+ * guard, SCOPED to the crash-recovery/pending window above the snapshot cursor.
+ *
+ * With `sinceSeq = 0` (no snapshot, or an explicit full scan) it covers the
+ * whole history, which is the correct behaviour during crash recovery when the
+ * snapshot is missing. With `sinceSeq = appliedSeq` it covers only the events
+ * the current snapshot has NOT yet accounted for, so an identity that recurs
+ * after a full round-trip (e.g. fail → green → fail) is NOT suppressed forever.
+ *
+ * @param {string} dir
+ * @param {number} [sinceSeq=0]
+ * @returns {Set<string>}
+ */
+function seenIdentities(dir, sinceSeq = 0) {
+  const since = Number(sinceSeq) || 0;
+  const set = new Set();
+  for (const e of readAllEvents(dir)) {
+    if ((Number(e.seq) || 0) > since) set.add(eventIdentity(e));
+  }
+  return set;
+}
+
+/** Append finalized records as NDJSON lines (atomic per-line append). */
+function appendEvents(dir, records) {
+  if (!records?.length) return;
+  const payload = records.map((r) => JSON.stringify(r)).join('\n') + '\n';
+  fs.appendFileSync(journalPath(dir), payload);
+}
+
+/**
+ * Read the persisted snapshot + fingerprint + `appliedSeq`, or null when
+ * absent/unreadable. `appliedSeq` is the highest journal seq this snapshot
+ * accounts for (0 for legacy snapshots written before the cursor existed); it
+ * bounds the dedup window in `seenIdentities`.
+ *
+ * @param {string} dir
+ * @returns {{ snapshot: object, fingerprint: string, appliedSeq: number }|null}
+ */
+function readSnapshot(dir) {
+  const file = snapshotPath(dir);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return {
+      snapshot: data.snapshot || null,
+      fingerprint: data.fingerprint || null,
+      appliedSeq: Number(data.appliedSeq) || 0,
+    };
+  } catch { return null; }
+}
+
+/**
+ * Atomically persist the snapshot + fingerprint + `appliedSeq` (write temp, then
+ * rename). The rename is atomic on the same filesystem, so a reader never sees a
+ * half-write.
+ *
+ * @param {string} dir
+ * @param {{ snapshot: object, fingerprint: string, appliedSeq?: number }} payload
+ */
+function writeSnapshot(dir, { snapshot, fingerprint, appliedSeq = 0 }) {
+  const tmp = path.join(dir, `.snapshot.${process.pid}.${Date.now()}.tmp`);
+  fs.writeFileSync(tmp, JSON.stringify({ snapshot, fingerprint, appliedSeq: Number(appliedSeq) || 0 }));
+  fs.renameSync(tmp, snapshotPath(dir));
+}
+
+/** Non-blocking sleep for the lock retry loop. */
+function delay(ms) { return new Promise((resolve) => { setTimeout(resolve, ms); }); }
+
+/**
+ * Is the held lock stale? A lock is stale when its owner process is dead, or
+ * when it has out-lived `staleMs` (guards against a reused pid or a crash that
+ * left no readable owner file). Either way it is safe to steal.
+ */
+function lockIsStale(lock, staleMs) {
+  let ownerPid = null;
+  let stampedAt = null;
+  try {
+    const [pidStr, tsStr] = fs.readFileSync(path.join(lock, 'owner'), 'utf8').split(':');
+    ownerPid = Number.parseInt(pidStr, 10);
+    stampedAt = Number.parseInt(tsStr, 10);
+  } catch { /* owner file missing/unreadable → fall through to age check */ }
+  if (ownerPid && !pidAlive(ownerPid)) return true;
+  let ageBase = stampedAt;
+  if (!Number.isFinite(ageBase)) {
+    try { ageBase = fs.statSync(lock).mtimeMs; } catch { return true; }
+  }
+  return Date.now() - ageBase > staleMs;
+}
+
+/** Remove a lock directory (owner file + dir), best-effort. */
+function releaseLock(lock) {
+  try { fs.rmSync(lock, { recursive: true, force: true }); } catch { /* already gone */ }
+}
+
+/**
+ * Run `fn` while holding the per-PR journal lock, serializing the
+ * read→diff→dedup→append→snapshot critical section across processes and
+ * worktrees. The lock is a directory created with an atomic `mkdir` (fails with
+ * EEXIST when held); a crash-recoverable staleness check lets a later caller
+ * steal a lock whose owner died or that out-lived `staleMs`. The lock is always
+ * released in a `finally`, on success or throw.
+ *
+ * A heartbeat refreshes the owner timestamp for the whole duration of the
+ * awaited `fn()`, at `staleMs / 3` intervals. Without this, `lockIsStale()`
+ * only looks at the ONE timestamp written at acquisition time — a live but
+ * slow pass (close to or past `staleMs`) would look stale to a competing
+ * caller purely on age, even though its owner PID is alive, and get its lock
+ * stolen mid-flight, letting two passes interleave journal appends and reuse a
+ * sequence number. The heartbeat is stopped in the existing `finally` cleanup
+ * alongside the lock release.
+ *
+ * @param {string} dir - journal directory.
+ * @param {() => Promise<T>|T} fn - critical section.
+ * @param {{ staleMs?: number, retries?: number, waitMs?: number, heartbeatMs?: number }} [opts]
+ *   `heartbeatMs` defaults to `staleMs / 3` (floor 10ms) and is exposed mainly
+ *   so tests can exercise the heartbeat without waiting out a full-size
+ *   `staleMs` window.
+ * @returns {Promise<T>}
+ * @template T
+ */
+async function withJournalLock(dir, fn, opts = {}) {
+  const { staleMs = 30000, retries = 600, waitMs = 25 } = opts;
+  const heartbeatMs = opts.heartbeatMs ?? Math.max(10, Math.floor(staleMs / 3));
+  const lock = lockPath(dir);
+  let acquired = false;
+  for (let i = 0; i < retries && !acquired; i += 1) {
+    try {
+      fs.mkdirSync(lock);
+      acquired = true;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      if (lockIsStale(lock, staleMs)) { releaseLock(lock); continue; }
+      await delay(waitMs);
+    }
+  }
+  if (!acquired) throw new Error(`journal lock busy after ${retries} tries: ${lock}`);
+  const ownerFile = path.join(lock, 'owner');
+  const stampOwner = () => {
+    try { fs.writeFileSync(ownerFile, `${process.pid}:${Date.now()}`); } catch { /* lock released/stolen underneath us */ }
+  };
+  stampOwner();
+  const heartbeat = setInterval(stampOwner, heartbeatMs);
+  if (typeof heartbeat.unref === 'function') heartbeat.unref();
+  try {
+    return await fn();
+  } finally {
+    clearInterval(heartbeat);
+    releaseLock(lock);
+  }
+}
+
+/** Write the watcher pid file. */
+function writePid(dir, pid) {
+  fs.writeFileSync(pidPath(dir), String(pid == null ? process.pid : pid));
+}
+
+/** Read the watcher pid (number) or null. */
+function readPid(dir) {
+  const file = pidPath(dir);
+  if (!fs.existsSync(file)) return null;
+  const n = Number.parseInt(fs.readFileSync(file, 'utf8').trim(), 10);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** Remove the watcher pid file (best-effort). */
+function removePid(dir) {
+  try { fs.unlinkSync(pidPath(dir)); } catch { /* already gone */ }
+}
+
+/** Is `pid` a live process? `process.kill(pid, 0)` probes without signaling. */
+function pidAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch (err) { return err?.code === 'EPERM'; }
+}
+
+/**
+ * A watcher is "running" when the pid file names a live process that is NOT us.
+ * Stale pid files (dead process) return false so a poll falls back to an inline
+ * pass.
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function watcherRunning(dir) {
+  const pid = readPid(dir);
+  return pidAlive(pid) && pid !== process.pid;
+}
+
+module.exports = {
+  sanitize,
+  journalDir,
+  journalPath,
+  snapshotPath,
+  pidPath,
+  lockPath,
+  withJournalLock,
+  readAllEvents,
+  readEventsSince,
+  lastSeq,
+  seenIdentities,
+  appendEvents,
+  readSnapshot,
+  writeSnapshot,
+  writePid,
+  readPid,
+  removePid,
+  pidAlive,
+  watcherRunning,
+};

package/lib/pr-monitor/monitor.js

@@ -0,0 +1,146 @@
+'use strict';
+
+/**
+ * PR-monitor orchestration — one bounded pass (gather → diff → dedup → append →
+ * persist) and the `events --since` poll surface. The watch streaming loop and
+ * the ship lifecycle hook land in a follow-up (Tier-1 PR-B).
+ *
+ * @module pr-monitor/monitor
+ */
+
+const { finalizeEvent, eventIdentity, fingerprint } = require('./events');
+const { diffSnapshots } = require('./differ');
+const journal = require('./journal');
+
+/** ISO-8601 timestamp; injectable via ctx.now for deterministic tests. */
+function defaultNow() { return new Date().toISOString(); }
+
+/**
+ * Filter candidate events down to those whose `(type,key)` identity has NOT
+ * already been journaled — the crash-safety dedup guard.
+ */
+function dedupeAgainstJournal(candidates, seen) {
+  return candidates.filter((c) => !seen.has(eventIdentity(c)));
+}
+
+/**
+ * Envelope filtered candidates into journal records with monotonic seq + ts.
+ */
+function finalizeRecords(candidates, { baseSeq, ts, snapshot }) {
+  return candidates.map((c, i) => finalizeEvent(c, {
+    seq: baseSeq + i + 1,
+    ts,
+    repo: snapshot.repo,
+    pr: snapshot.pr,
+    headSha: snapshot.headSha,
+    verdict: snapshot.verdict,
+  }));
+}
+
+/**
+ * The read→diff→dedup→sequence→append→snapshot critical section of a single
+ * pass. Runs ONLY while holding the journal lock (see `runMonitorPass`), so it
+ * may assume no concurrent writer.
+ *
+ * Dedup is SCOPED to the snapshot's `appliedSeq` cursor: only identities the
+ * current snapshot has not yet accounted for filter a candidate. When the
+ * snapshot is missing (crash recovery) `appliedSeq` is 0, so the guard falls
+ * back to the full history and no duplicate survives a crash between append and
+ * snapshot write. When the snapshot is current, the window is empty, so a state
+ * that flips back to a prior value (fail → green → fail on the same sha) emits a
+ * fresh event instead of being suppressed forever.
+ */
+async function runMonitorPassLocked(ctx) {
+  const { dir, gather, now = defaultNow, enrich } = ctx;
+  const next = await gather();
+  const prevRecord = journal.readSnapshot(dir);
+  const prev = prevRecord ? prevRecord.snapshot : null;
+  const appliedSeq = prevRecord ? prevRecord.appliedSeq || 0 : 0;
+  const fp = fingerprint(next);
+
+  const candidates = diffSnapshots(prev, next);
+  const filtered = dedupeAgainstJournal(candidates, journal.seenIdentities(dir, appliedSeq));
+
+  if (!filtered.length) {
+    // Backpressure: only rewrite the snapshot when the fingerprint actually moved.
+    const changed = prevRecord?.fingerprint !== fp;
+    // Even with no new events, advance the cursor to the current tail so the
+    // dedup window stays anchored at the snapshot (prevents unbounded scans).
+    if (changed) {
+      journal.writeSnapshot(dir, { snapshot: next, fingerprint: fp, appliedSeq: journal.lastSeq(dir) });
+    }
+    return { events: [], changed, fingerprint: fp };
+  }
+
+  const baseSeq = journal.lastSeq(dir);
+  const records = finalizeRecords(filtered, {
+    baseSeq,
+    ts: now(),
+    snapshot: next,
+  });
+  if (typeof enrich === 'function') await enrich(records);
+
+  journal.appendEvents(dir, records);
+  // appliedSeq = the new tail, so the next pass's dedup window starts empty and
+  // only a crash BEFORE this write leaves the tail inside the recovery window.
+  journal.writeSnapshot(dir, { snapshot: next, fingerprint: fp, appliedSeq: baseSeq + records.length });
+  return { events: records, changed: true, fingerprint: fp };
+}
+
+/**
+ * Run ONE bounded monitor pass: gather the current snapshot, diff it against the
+ * persisted one, dedup by content identity, APPEND new events, THEN persist the
+ * snapshot (this order is what makes a crash between the two idempotent). The
+ * whole critical section — including the gather and the no-events snapshot
+ * update path — runs under a cross-process journal lock so concurrent passes
+ * from other processes/worktrees can never interleave appends or reuse a seq.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.dir - journal directory (from journal.journalDir).
+ * @param {() => Promise<object>} ctx.gather - returns a normalized snapshot.
+ * @param {() => string} [ctx.now] - timestamp source (test injection).
+ * @param {(records: object[]) => Promise<void>|void} [ctx.enrich] - optional hook
+ *   to enrich records (e.g. attach log excerpts to check.failed) before append.
+ * @param {object} [ctx.lockOpts] - override lock staleMs/retries/waitMs (tests).
+ * @returns {Promise<{ events: object[], changed: boolean, fingerprint: string }>}
+ */
+async function runMonitorPass(ctx) {
+  return journal.withJournalLock(ctx.dir, () => runMonitorPassLocked(ctx), ctx.lockOpts);
+}
+
+/**
+ * `forge shepherd events <pr> --since <seq>` core: run one inline pass when no
+ * watcher owns this PR, then return every journaled event with `seq > since`.
+ * This is the agent-agnostic PULL surface — stdout NDJSON, nothing under .claude.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.dir
+ * @param {() => Promise<object>} ctx.gather
+ * @param {number} [ctx.since]
+ * @param {() => string} [ctx.now]
+ * @param {(dir: string) => boolean} [ctx.watcherRunning]
+ * @param {(records: object[]) => Promise<void>|void} [ctx.enrich]
+ * @returns {Promise<{ events: object[], since: number, ranPass: boolean }>}
+ */
+async function pollEvents(ctx) {
+  const { dir, gather, since = 0 } = ctx;
+  const isRunning = (ctx.watcherRunning || journal.watcherRunning)(dir);
+  let ranPass = false;
+  if (!isRunning) {
+    await runMonitorPass({ dir, gather, now: ctx.now, enrich: ctx.enrich });
+    ranPass = true;
+  }
+  return {
+    events: journal.readEventsSince(dir, since),
+    since: Number(since) || 0,
+    ranPass,
+  };
+}
+
+module.exports = {
+  runMonitorPass,
+  pollEvents,
+  dedupeAgainstJournal,
+  finalizeRecords,
+  defaultNow,
+};

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

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * PR-monitor sticky-comment renderer — turn ONE read-only `gatherPrBundle`
+ * 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.
+ *
+ * Pure and deterministic: same bundle + same injected clock → same body, which
+ * is what lets the workflow rewrite the sticky comment in place without churn.
+ *
+ * @module pr-monitor/render-sticky
+ */
+
+/** 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 -->';
+
+/** Cap threads listed per author so a noisy PR can't produce an enormous body. */
+const MAX_THREADS_PER_AUTHOR = 8;
+
+/** Group unresolved review-thread comments by author → ordered [author, threads]. */
+function groupByAuthor(comments) {
+  const byAuthor = new Map();
+  for (const c of (Array.isArray(comments) ? comments : [])) {
+    const author = String(c.author || 'unknown');
+    if (!byAuthor.has(author)) byAuthor.set(author, []);
+    byAuthor.get(author).push(c);
+  }
+  // Sort authors by descending thread count, then name — stable + deterministic.
+  return [...byAuthor.entries()].sort((a, b) => (b[1].length - a[1].length) || a[0].localeCompare(b[0]));
+}
+
+/** One-line locator for a thread: `path:line` when known, else the threadId. */
+function threadLocator(t) {
+  if (t.path) return t.line != null ? `${t.path}:${t.line}` : t.path;
+  return t.threadId || '(thread)';
+}
+
+/** Render the unresolved-review-threads section (author-agnostic + fail-closed). */
+function renderThreads(bundle, lines) {
+  // Fail-closed: if the thread read was not available for ANY reason — it threw
+  // (error set) OR the adapter cannot read comments at all (capability absent,
+  // error null) — NEVER render "zero / clean". Only a genuine available:true read
+  // may report "no unresolved threads". Guard on `!== true` (not `=== false`) so a
+  // producer that omits the flag is also treated as unread, never as clean.
+  if (bundle.unresolvedCommentsAvailable !== true) {
+    const why = bundle.unresolvedCommentsError || 'thread read unavailable (capability absent)';
+    lines.push('### Review threads');
+    lines.push(`⚠️ Review threads were **unreadable** this pass (\`${why}\`) — not treated as zero. Re-run once the read recovers.`);
+    lines.push('');
+    return;
+  }
+
+  const comments = Array.isArray(bundle.unresolvedComments) ? bundle.unresolvedComments : [];
+  if (comments.length === 0) {
+    lines.push('### Review threads');
+    lines.push('✅ No unresolved review threads.');
+    lines.push('');
+    return;
+  }
+
+  const groups = groupByAuthor(comments);
+  lines.push(`### Unresolved review threads (${comments.length})`);
+  lines.push('');
+  for (const [author, threads] of groups) {
+    lines.push(`- **${author}** — ${threads.length}`);
+    for (const t of threads.slice(0, MAX_THREADS_PER_AUTHOR)) {
+      lines.push(`  - \`${threadLocator(t)}\``);
+    }
+    if (threads.length > MAX_THREADS_PER_AUTHOR) {
+      lines.push(`  - …and ${threads.length - MAX_THREADS_PER_AUTHOR} more`);
+    }
+  }
+  lines.push('');
+}
+
+/** Render the failing / pending check sections (author-agnostic + fail-closed). */
+function renderChecks(bundle, lines) {
+  // Fail-closed, mirroring renderThreads: empty ci arrays are AMBIGUOUS — they
+  // mean either "read, genuinely all-clear" or "never read (gather outage)". Only
+  // an explicit ciAvailable === true lets us render the summary; anything else
+  // ("!== true": false or missing) surfaces as unreadable, so the monitor never
+  // prints a false "no failing checks" for CI it did not actually read.
+  if (bundle.ciAvailable !== true) {
+    lines.push('### Checks');
+    lines.push('⚠️ Checks were **unreadable** this pass — not treated as green. Re-run once the read recovers.');
+    lines.push('');
+    return;
+  }
+
+  const ci = bundle.ci || {};
+  const failing = Array.isArray(ci.failing) ? ci.failing : [];
+  const pending = Array.isArray(ci.pending) ? ci.pending : [];
+
+  lines.push('### Checks');
+  if (failing.length === 0 && pending.length === 0) {
+    lines.push('✅ No failing or pending checks.');
+  } else {
+    if (failing.length > 0) {
+      lines.push(`- ❌ **Failing (${failing.length}):** ${failing.map((c) => `\`${c.name || '?'}\``).join(', ')}`);
+    }
+    if (pending.length > 0) {
+      lines.push(`- ⏳ **Pending (${pending.length}):** ${pending.map((c) => `\`${c.name || '?'}\``).join(', ')}`);
+    }
+  }
+  lines.push('');
+}
+
+/**
+ * Render the sticky monitor comment for a PR-state bundle.
+ *
+ * @param {object} bundle - a `gatherPrBundle` result (lib/pr-bundle.js).
+ * @param {object} [opts]
+ * @param {Date}   [opts.now] - injected clock for deterministic output.
+ * @returns {{ marker: string, body: string }}
+ */
+function renderStickyComment(bundle = {}, opts = {}) {
+  const now = opts.now instanceof Date ? opts.now : new Date();
+  const lines = [];
+
+  // The marker MUST be the very first bytes so the workflow's substring match
+  // finds the prior comment regardless of any rendering below it.
+  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._');
+  lines.push('');
+
+  renderThreads(bundle, lines);
+  renderChecks(bundle, lines);
+
+  const branch = bundle.branch || {};
+  if ((branch.behind || 0) > 0) {
+    lines.push(`> Branch is **${branch.behind}** commit(s) behind base.`);
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push(`<sub>Updated ${now.toISOString()} · surface-only monitor · never merges, never verdicts.</sub>`);
+
+  return { marker: STICKY_MARKER, body: lines.join('\n') };
+}
+
+module.exports = {
+  renderStickyComment,
+  groupByAuthor,
+  threadLocator,
+  STICKY_MARKER,
+  MAX_THREADS_PER_AUTHOR,
+};

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

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * PR-monitor lifecycle — auto-start the watch loop, detached and idempotent, on
+ * `forge ship` success. This is what makes the monitor CONSTANT without an agent
+ * having to remember to run it: the moment a PR exists, a background
+ * `forge shepherd watch <pr>` begins keeping the journal warm, and any harness
+ * re-attaches later with `forge shepherd events <pr> --since <seq>`.
+ *
+ * Contract (all guaranteed here): NEVER throws, NEVER blocks, NEVER fails ship.
+ * The detached child is `unref`'d so it cannot keep the ship process alive, and
+ * every branch is wrapped so a spawn/gh failure degrades to "not started" rather
+ * than surfacing to the caller. Stop-on-merge belongs to the watch loop's
+ * terminal pass, not here.
+ *
+ * @module pr-monitor/watch-lifecycle
+ */
+
+const path = require('node:path');
+const { spawn, execFileSync } = require('node:child_process');
+
+const journal = require('./journal');
+
+/** Absolute path to the forge CLI entrypoint (this file is lib/pr-monitor/). */
+function forgeBin() {
+  return path.join(__dirname, '..', '..', 'bin', 'forge.js');
+}
+
+/**
+ * Best-effort repo slug (the bare repo NAME, matching the shepherd's `ctx.repo`)
+ * from `git remote get-url origin`, so the idempotency check hits the same
+ * journal dir the watcher itself uses. Returns null on any failure — the caller
+ * then falls through to spawn and relies on the watch loop's own de-dup.
+ */
+function defaultResolveSlug({ cwd, exec = execFileSync }) {
+  try {
+    const url = exec('git', ['remote', 'get-url', 'origin'], {
+      cwd, encoding: 'utf8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    const match = /[/:][^/]+\/([^/]+?)(?:\.git)?$/.exec(url);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Start (or no-op) a detached `forge shepherd watch <pr>`.
+ *
+ * @param {object} opts
+ * @param {string|number} opts.prNumber - the PR to watch.
+ * @param {string} [opts.cwd] - repo root (default process.cwd()).
+ * @param {Function} [opts.spawn] - child spawner (test injection).
+ * @param {Function} [opts.exec] - git runner for slug resolution (test injection).
+ * @param {object} [opts.journal] - journal module (test injection).
+ * @param {Function} [opts.resolveSlug] - slug resolver (test injection).
+ * @returns {{ started: boolean, pid?: number|null, reason?: string }} — never throws.
+ */
+function startPrWatcherDetached(opts = {}) {
+  const { prNumber, cwd = process.cwd() } = opts;
+  const spawnFn = opts.spawn || spawn;
+  const journalMod = opts.journal || journal;
+  const resolveSlug = opts.resolveSlug || defaultResolveSlug;
+  try {
+    if (!prNumber) return { started: false, reason: 'no-pr' };
+
+    const slug = resolveSlug({ cwd, exec: opts.exec });
+    if (slug) {
+      const dir = journalMod.journalDir({ root: cwd, repo: slug, pr: prNumber });
+      if (journalMod.watcherRunning(dir)) return { started: false, reason: 'already-running' };
+    }
+
+    const child = spawnFn(
+      process.execPath,
+      [forgeBin(), 'shepherd', 'watch', String(prNumber)],
+      { cwd, detached: true, stdio: 'ignore', windowsHide: true },
+    );
+    // spawn can emit an ASYNC 'error' (ENOENT/EACCES) AFTER returning; with no
+    // listener that becomes an unhandled exception that could crash ship. A no-op
+    // handler keeps a failed detached start best-effort (the watch loop's own
+    // journal claim is the authoritative de-dup anyway).
+    if (child && typeof child.on === 'function') child.on('error', () => {});
+    if (child && typeof child.unref === 'function') child.unref();
+    return { started: true, pid: child?.pid ?? null };
+  } catch (err) {
+    // Lifecycle auto-start must never fail ship — degrade to "not started".
+    return { started: false, reason: err.message };
+  }
+}
+
+module.exports = {
+  startPrWatcherDetached,
+  defaultResolveSlug,
+  forgeBin,
+};