forge-workflow 0.0.10 → 0.1.0-beta.3

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

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * PR-monitor gather — turn ONE `gatherPrSnapshot` read (the SAME shared read the
+ * `--pull` verdict uses) into the normalized snapshot the differ compares. Because
+ * the verdict and the monitor events both derive from this one read, they can
+ * never disagree (the frame in docs/work/2026-07-13-pr-monitor/plan.md).
+ *
+ * The normalized snapshot is the diff subject:
+ *   { repo, pr, headSha, prState, draft, verdict:{state,reason},
+ *     checks:[{name,class}], threads:[{threadId,isResolved,isOutdated,commentCount,actionable,path}],
+ *     reviews:[{author,state,commitOid,submittedAt}], comments:[{id,author}],
+ *     behind, conflicts:(true|false|null), degraded:[{surface,error}] }
+ *
+ * @module pr-monitor/gather
+ */
+
+const { gatherPrSnapshot } = require('../pr-pull');
+const { isFailed, isGreen } = require('../pr-shepherd');
+
+/** green | failed | pending — reuses the SAME predicates as the verdict core. */
+function classifyCheck(check) {
+  if (isFailed(check)) return 'failed';
+  if (isGreen(check)) return 'green';
+  return 'pending';
+}
+
+function normalizeChecks(checks) {
+  return (Array.isArray(checks) ? checks : []).map((c) => ({
+    name: c.name || '',
+    class: classifyCheck(c),
+  }));
+}
+
+function normalizeThreads(threads) {
+  return (Array.isArray(threads) ? threads : []).map((t) => ({
+    threadId: t.threadId || '',
+    isResolved: Boolean(t.isResolved),
+    isOutdated: Boolean(t.isOutdated),
+    commentCount: Array.isArray(t.comments) ? t.comments.length : 0,
+    actionable: !t.isResolved && !t.isOutdated,
+    path: t.path || null,
+  }));
+}
+
+function normalizeReviews(reviews) {
+  return (Array.isArray(reviews) ? reviews : []).map((r) => ({
+    author: r.author || '',
+    state: r.state || '',
+    commitOid: r.commitOid || null,
+    submittedAt: r.submittedAt || null,
+  }));
+}
+
+function normalizeComments(comments) {
+  return (Array.isArray(comments) ? comments : []).map((c) => ({
+    id: c.id || `${c.author || ''}:${c.createdAt || ''}`,
+    author: c.author || '',
+  }));
+}
+
+function normalizeDegraded(degraded) {
+  return (Array.isArray(degraded) ? degraded : []).map((d) => ({
+    surface: d.source || d.surface || 'unknown',
+    error: d.error || '',
+  }));
+}
+
+/**
+ * Conflict prediction → tri-state boolean: `true`/`false` when supported,
+ * `null` when unknown (unsupported git, unreadable ref) so the differ never
+ * emits a false conflict.appeared/cleared on missing data.
+ */
+function conflictBool(conflicts) {
+  if (conflicts?.supported === true) return Boolean(conflicts.conflicted);
+  return null;
+}
+
+/**
+ * Normalize a raw `gatherPrSnapshot` result into the monitor diff subject.
+ *
+ * @param {object} snap - gatherPrSnapshot result.
+ * @param {{ repo: string, pr: string|number }} ctx
+ * @returns {object}
+ */
+function normalizeSnapshot(snap, ctx) {
+  const state = snap.state || {};
+  return {
+    repo: ctx.repo,
+    pr: String(ctx.pr),
+    headSha: state.headSha || '',
+    prState: String(state.state || 'OPEN').toUpperCase(),
+    draft: Boolean(snap.draft),
+    verdict: { state: snap.verdict || 'UNKNOWN', reason: null },
+    checks: normalizeChecks(state.checks),
+    threads: normalizeThreads(snap.threads),
+    reviews: normalizeReviews(snap.reviews),
+    comments: normalizeComments(snap.issueComments),
+    behind: snap.behind || 0,
+    conflicts: conflictBool(snap.conflicts),
+    degraded: normalizeDegraded(snap.degraded),
+  };
+}
+
+/**
+ * Gather + normalize the monitor snapshot for a PR. `ctx.gatherSnapshot` is
+ * injectable for tests; production uses the shared `gatherPrSnapshot`.
+ *
+ * @param {object} ctx - the same ctx shape gatherPrSnapshot takes (pr, owner,
+ *   repo, base, baseRef, cwd, self, adapter, now, settleWindowMs).
+ * @returns {Promise<object>} normalized snapshot.
+ */
+async function gatherMonitorSnapshot(ctx) {
+  const gather = ctx.gatherSnapshot || gatherPrSnapshot;
+  const snap = await gather(ctx);
+  return normalizeSnapshot(snap, ctx);
+}
+
+module.exports = {
+  gatherMonitorSnapshot,
+  normalizeSnapshot,
+  classifyCheck,
+  conflictBool,
+};

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