forge-workflow 0.0.10 → 0.1.0-beta.3

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,192 @@
+'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 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.
+ *
+ * @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 -->';
+
+/** 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('');
+  // 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);
+  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 · labels state, never merges, never resolves threads.</sub>`);
+
+  return { marker: STICKY_MARKER, body: lines.join('\n') };
+}
+
+module.exports = {
+  renderStickyComment,
+  verdictHeadline,
+  groupByAuthor,
+  threadLocator,
+  STICKY_MARKER,
+  MAX_THREADS_PER_AUTHOR,
+};

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,
+};

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,
+};