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

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-summary.js

@@ -0,0 +1,196 @@
+'use strict';
+
+/**
+ * PR-monitor Actions-summary renderer. It turns one read-only
+ * `gatherPrBundle` result (lib/pr-bundle.js) into deterministic Markdown for
+ * the workflow's `GITHUB_STEP_SUMMARY` surface.
+ *
+ * This is presentation only: it displays the canonical verdict supplied by
+ * `forge shepherd <pr> --pull --json`, lists unresolved review threads and CI
+ * state, and never merges or resolves anything. The `pr-verdict:*` label is a
+ * cheap visibility projection of that same verdict, not merge authority.
+ *
+ * @module pr-monitor/render-summary
+ */
+
+/**
+ * Presentation-only headline for each canonical merge verdict (lib/pr-pull.js).
+ * The verdict is computed once by pr-pull and passed in; this map only decides
+ * how it is displayed, 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 headline for a canonical verdict, failing closed. */
+function verdictHeadline(verdict) {
+  return VERDICT_HEADLINE[String(verdict || '').toUpperCase()] || VERDICT_HEADLINE.UNKNOWN;
+}
+
+/**
+ * Render untrusted text as a Markdown code span without allowing its backticks
+ * or line breaks to change the surrounding summary structure.
+ *
+ * CommonMark permits a code span to use more than one backtick. Pick a fence
+ * longer than every run in the value, and flatten CR/LF so the summary stays
+ * one line per diagnostic.
+ */
+function mdCode(value) {
+  const text = String(value ?? '').replace(/[\r\n]+/g, ' ');
+  let longestRun = 0;
+  let currentRun = 0;
+  for (const character of text) {
+    if (character === '`') {
+      currentRun += 1;
+      longestRun = Math.max(longestRun, currentRun);
+    } else {
+      currentRun = 0;
+    }
+  }
+  const fence = '`'.repeat(longestRun + 1);
+  const content = text.startsWith('`') || text.endsWith('`') ? ` ${text} ` : text;
+  return `${fence}${content}${fence}`;
+}
+
+/** Cap threads listed per author so a noisy PR cannot produce an enormous summary. */
+const MAX_THREADS_PER_AUTHOR = 8;
+
+/** Group unresolved review-thread comments by author in deterministic order. */
+function groupByAuthor(comments) {
+  const byAuthor = new Map();
+  for (const comment of (Array.isArray(comments) ? comments : [])) {
+    const author = String(comment.author || 'unknown');
+    if (!byAuthor.has(author)) byAuthor.set(author, []);
+    byAuthor.get(author).push(comment);
+  }
+  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 its id. */
+function threadLocator(thread) {
+  if (thread.path) return thread.line != null ? `${thread.path}:${thread.line}` : thread.path;
+  return thread.threadId || '(thread)';
+}
+
+/** Render unresolved review threads, preserving fail-closed availability. */
+function renderThreads(bundle, lines) {
+  // Empty arrays are ambiguous when the adapter could not read comments. Only
+  // an explicit available:true read may report zero unresolved threads.
+  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 (${mdCode(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 thread of threads.slice(0, MAX_THREADS_PER_AUTHOR)) {
+      lines.push(`  - ${mdCode(threadLocator(thread))}`);
+    }
+    if (threads.length > MAX_THREADS_PER_AUTHOR) {
+      lines.push(`  - …and ${threads.length - MAX_THREADS_PER_AUTHOR} more`);
+    }
+  }
+  lines.push('');
+}
+
+/** Render failing and pending checks, preserving fail-closed availability. */
+function renderChecks(bundle, lines) {
+  // Only ciAvailable:true permits a clean-check claim. Missing or false means
+  // the read did not complete, so empty arrays must not look green.
+  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((check) => mdCode(check.name || '?')).join(', ')}`);
+    }
+    if (pending.length > 0) {
+      lines.push(`- ⏳ **Pending (${pending.length}):** ${pending.map((check) => mdCode(check.name || '?')).join(', ')}`);
+    }
+  }
+  lines.push('');
+}
+
+/**
+ * Render the PR monitor's Actions job summary.
+ *
+ * @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] - canonical `--pull` verdict
+ * @param {string[]} [opts.unreadable] - unreadable signal names from `--pull`
+ * @param {string|number} [opts.pr] - PR number for the CLI diagnostics hint
+ * @returns {{ body: string }}
+ */
+function renderSummary(bundle = {}, opts = {}) {
+  const now = opts.now instanceof Date ? opts.now : new Date();
+  const lines = ['## 🔭 Forge PR Monitor', ''];
+  const verdict = String(opts.verdict || '').toUpperCase();
+  const isUnknown = verdict === 'UNKNOWN' || !VERDICT_HEADLINE[verdict];
+  const unreadable = Array.isArray(opts.unreadable) ? opts.unreadable.filter(Boolean) : [];
+
+  lines.push(verdictHeadline(opts.verdict));
+  if (isUnknown && unreadable.length > 0) {
+    lines.push('');
+    lines.push(`> Unreadable signal(s): ${unreadable.map((signal) => mdCode(signal)).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);
+  renderChecks(bundle, lines);
+
+  const branch = bundle.branch || {};
+  if ((branch.behind || 0) > 0) {
+    lines.push(`> Branch is **${branch.behind}** commit(s) behind base.`);
+    lines.push('');
+  }
+
+  const pr = opts.pr || bundle.pr || '<pr>';
+  lines.push('---');
+  lines.push(`Detailed JSON: ${mdCode(`forge shepherd ${pr} --pull --json`)}`);
+  lines.push(`_Updated ${now.toISOString()} · summary-only monitor · labels state, never merges, never resolves threads._`);
+
+  return { body: lines.join('\n') };
+}
+
+module.exports = {
+  renderSummary,
+  verdictHeadline,
+  groupByAuthor,
+  threadLocator,
+  MAX_THREADS_PER_AUTHOR,
+};

package/lib/pr-monitor/shepherd-lease.js

@@ -0,0 +1,252 @@
+'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. */
+// Must exceed the longest synchronous daemon read (`gh pr list`, 30s) with
+// enough margin that a blocked event loop cannot be reclaimed mid-read.
+const STALE_MS = 90000;
+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 */
+  }
+}
+
+/** True only while this exact pid+token still owns the shared lease. */
+function owns(projectRoot, { gitCommonDir, token, pid = process.pid } = {}) {
+  const held = readLock(lockFilePath(projectRoot, { gitCommonDir }));
+  return Boolean(held && ownsLock(held, { token, pid }));
+}
+
+module.exports = {
+  STALE_MS,
+  lockFilePath,
+  pidAlive,
+  ownsLock,
+  acquire,
+  stamp,
+  startHeartbeat,
+  stopHeartbeat,
+  updateWatchers,
+  release,
+  owns,
+};

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

@@ -20,6 +20,7 @@ const path = require('node:path');
 const { spawn, execFileSync } = require('node:child_process');
 
 const journal = require('./journal');
+const brokerMod = require('../kernel/broker');
 
 /** Absolute path to the forge CLI entrypoint (this file is lib/pr-monitor/). */
 function forgeBin() {
@@ -35,7 +36,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;
@@ -66,7 +67,18 @@ function startPrWatcherDetached(opts = {}) {
 
     const slug = resolveSlug({ cwd, exec: opts.exec });
     if (slug) {
-      const dir = journalMod.journalDir({ root: cwd, repo: slug, pr: prNumber });
+      let gitCommonDir = opts.gitCommonDir;
+      if (!gitCommonDir) {
+        try {
+          const resolveGitCommonDir = opts.resolveGitCommonDir || brokerMod.resolveGitCommonDir;
+          gitCommonDir = resolveGitCommonDir(cwd, { warn: () => {} });
+        } catch {
+          /* unavailable common-dir keeps the legacy per-root journal fallback */
+        }
+      }
+      const dir = journalMod.journalDir({
+        root: cwd, gitCommonDir, repo: slug, pr: prNumber,
+      });
       if (journalMod.watcherRunning(dir)) return { started: false, reason: 'already-running' };
     }