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

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

@@ -7,12 +7,11 @@
  * debounce guard. This module is the thin, side-effecting dispatcher over them:
  * it gathers the two state sets (GitHub via `gh`, kernel via the broker), runs the
  * actions `reconcile()` emits (spawn/stop/reap watchers, upsert/retire kernel_pr
- * rows), owns the SINGLETON DAEMON lease lifecycle, and provides the per-command
- * `fireAndForget()` trigger wired into `bin/forge.js`.
+ * rows), owns the SINGLETON DAEMON lease lifecycle, and provides the approved-seam
+ * `fireAndForget()` trigger used by session-start, push, and ship.
  *
  * The NON-BLOCKING / ERROR-SWALLOWING contract is paramount: `fireAndForget()`
- * MUST never throw and never affect the command that triggered it (it is called
- * from a `finally` in the dispatch chokepoint). Every spawn is modeled on
+ * MUST never throw and never affect the command that triggered it. Every spawn is modeled on
  * `watch-lifecycle.startPrWatcherDetached` (detached, `stdio:'ignore'`,
  * `windowsHide:true`, `.unref()`, no-op `'error'` listener) so a failed launch
  * degrades to "not started" rather than crashing.
@@ -39,10 +38,69 @@ const shepherdLease = require('./shepherd-lease');
 const journal = require('./journal');
 const { reconcile: defaultReconcile } = require('./reconcile');
 const { tick: defaultTick } = require('./reconcile-tick');
-const { startPrWatcherDetached, defaultResolveSlug, forgeBin } = require('./watch-lifecycle');
+const { startPrWatcherDetached, forgeBin } = require('./watch-lifecycle');
 const brokerMod = require('../kernel/broker');
 
 const { STALE_MS } = shepherdLease;
+const CANONICAL_REPOSITORY = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const GH_COMMAND_TIMEOUT_MS = 30_000;
+const LINKAGE_FIELDS = ['issue_id', 'worktree_id', 'journal_ptr'];
+
+function normalizeRepository(value) {
+	return typeof value === 'string' && CANONICAL_REPOSITORY.test(value.trim())
+		? value.trim().toLowerCase()
+		: null;
+}
+
+/** Resolve the GitHub identity used by merge binding, never a bare repo basename. */
+function resolveCanonicalRepository(runGh) {
+	try {
+		const raw = runGh(['repo', 'view', '--json', 'owner,name']);
+		const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+		const owner = parsed && parsed.owner && parsed.owner.login;
+		const name = parsed && parsed.name;
+		if (typeof owner !== 'string' || owner.trim() === '' || typeof name !== 'string' || name.trim() === '') return null;
+		return normalizeRepository(`${owner}/${name}`);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Persist the daemon's latest lifecycle outcome beside the lease. This status
+ * file is deliberately separate from `shepherd.reconcile`: that sentinel's
+ * mtime is the cold-trigger debounce clock and diagnostics must never move it.
+ */
+function writeDaemonDiagnostic(gitCommonDir, entry, opts = {}) {
+	try {
+		const file = path.join(gitCommonDir, 'forge', 'shepherd.status.json');
+		fs.mkdirSync(path.dirname(file), { recursive: true });
+		const now = opts.now || (() => Date.now());
+		const payload = {
+			...entry,
+			pid: opts.pid ?? process.pid,
+			at: new Date(now()).toISOString(),
+		};
+		fs.writeFileSync(file, `${JSON.stringify(payload)}\n`);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Record through an injected test seam or the separate durable status file. */
+function recordDaemonDiagnostic(opts, gitCommonDir, kind, detail) {
+	const entry = {
+		kind,
+		...(detail ? { detail: (detail && detail.message) || String(detail) } : {}),
+	};
+	try {
+		if (typeof opts.recordDiagnostic === 'function') opts.recordDiagnostic(entry);
+		else writeDaemonDiagnostic(gitCommonDir, entry, { now: opts.now });
+	} catch {
+		/* diagnostics must never affect a command or daemon lifecycle */
+	}
+}
 
 /** Normalize a lease watcher entry to the W-S4b `{pr, repo, pid, startedAt}` shape. */
 function normalizeWatcher(entry) {
@@ -65,10 +123,10 @@ function claimPath(dir) {
  * kill-time re-verification token — orphan reaping refuses to kill a pid unless
  * this marker still equals the watcher entry's `startedAt`.
  */
-function writeClaimMarker(projectRoot, repo, pr, startedAt) {
+function writeClaimMarker(projectRoot, repo, pr, startedAt, gitCommonDir) {
 	if (repo == null || pr == null || startedAt == null) return;
 	try {
-		const dir = journal.journalDir({ root: projectRoot, repo, pr });
+		const dir = journal.journalDir({ root: projectRoot, gitCommonDir, repo, pr });
 		fs.writeFileSync(claimPath(dir), String(startedAt));
 	} catch {
 		/* best-effort — a missing marker just means the pid is treated as unverifiable (never reaped) */
@@ -76,10 +134,10 @@ function writeClaimMarker(projectRoot, repo, pr, startedAt) {
 }
 
 /** Read the start-time marker for `(repo, pr)`, or null when absent/unreadable. */
-function readClaimMarker(projectRoot, repo, pr) {
+function readClaimMarker(projectRoot, repo, pr, gitCommonDir) {
 	if (repo == null || pr == null) return null;
 	try {
-		const dir = journal.journalDir({ root: projectRoot, repo, pr });
+		const dir = journal.journalDir({ root: projectRoot, gitCommonDir, repo, pr });
 		return fs.readFileSync(claimPath(dir), 'utf8').trim();
 	} catch {
 		return null;
@@ -91,10 +149,10 @@ function readClaimMarker(projectRoot, repo, pr) {
  * a future PID reuse can't match a STALE marker and get treated as the live watcher.
  * Best-effort; a missing marker is fine (an unverifiable pid is never reaped anyway).
  */
-function removeClaimMarker(projectRoot, repo, pr) {
+function removeClaimMarker(projectRoot, repo, pr, gitCommonDir) {
 	if (repo == null || pr == null) return;
 	try {
-		const dir = journal.journalDir({ root: projectRoot, repo, pr });
+		const dir = journal.journalDir({ root: projectRoot, gitCommonDir, repo, pr });
 		fs.rmSync(claimPath(dir), { force: true });
 	} catch {
 		/* best-effort marker cleanup */
@@ -110,14 +168,17 @@ function removeClaimMarker(projectRoot, repo, pr) {
  */
 async function gatherDesired(gitCommonDir, opts = {}) {
 	const runGh = opts.runGh || ((args) => require('node:child_process').execFileSync('gh', args, {
-		encoding: 'utf8', timeout: 30000, windowsHide: true,
+		cwd: opts.projectRoot || process.cwd(), encoding: 'utf8', timeout: GH_COMMAND_TIMEOUT_MS, windowsHide: true,
 	}));
 	// The broker is a live kernel handle from createLocalBroker (listOpenPrs/upsertPr/
 	// retirePr are INSTANCE methods) — the daemon threads one in. Never fall back to the
 	// broker MODULE namespace: those methods don't exist there and every call would
 	// silently no-op behind the catch (this exact bug shipped once — keep it gone).
 	const broker = opts.broker || null;
-	const repo = opts.repo || defaultResolveSlug({ cwd: opts.projectRoot || process.cwd() });
+	// Explicit repo injection remains a test/programmatic seam. Production resolves the
+	// owner/name pair from GitHub; a bare basename is never inferred from a failed lookup.
+	const suppliedRepo = typeof opts.repo === 'string' && opts.repo.trim() ? opts.repo.trim() : null;
+	const repo = suppliedRepo || resolveCanonicalRepository(runGh);
 
 	let ghPrs = [];
 	// `listingOk` distinguishes "GitHub says zero open PRs" from "the gh call failed"
@@ -135,22 +196,85 @@ async function gatherDesired(gitCommonDir, opts = {}) {
 		listingOk = false;
 	}
 
+	if (!repo) return { openPrs: [], gitCommonDir, listingOk: false, repositoryOk: false };
+
 	let prRows = [];
 	try {
 		if (broker) prRows = await broker.listOpenPrs(gitCommonDir);
 	} catch {
 		/* kernel unavailable → treat as no linkage; the GitHub-driven desired set still stands */
 	}
-	// Key by (repo, number) — matches reconcile.js `keyOf` — so a repo rename that
-	// leaves a same-number row under one git_common_dir can't attach the wrong repo's
-	// linkage to the desired PR.
-	const keyOf = (r, n) => `${r} ${n}`;
-	const rowByKey = new Map((Array.isArray(prRows) ? prRows : []).map((r) => [keyOf(r.repo, r.number), r]));
+	// Key by canonical (repo, number). A single bare-name row is accepted
+	// only as a one-way compatibility bridge; it is rewritten under the canonical key
+	// and retired by the same reconcile pass. The common-dir natural key plus an exact
+	// basename/number match preserves links across force-pushes; cross-repository,
+	// ambiguous, and other malformed rows never bind.
+	const canonicalRepo = normalizeRepository(repo);
+	const legacyRepo = canonicalRepo ? canonicalRepo.slice(canonicalRepo.lastIndexOf('/') + 1) : null;
+	const validPrNumber = (value) => (Number.isSafeInteger(value) && value > 0)
+		|| (typeof value === 'string' && /^[1-9][0-9]*$/.test(value));
+	const rows = Array.isArray(prRows) ? prRows : [];
+	if (canonicalRepo) {
+		const counts = new Map();
+		const conflicting = rows.some((row) => {
+			if (!row || !validPrNumber(row.number)) return true;
+			const rowRepo = normalizeRepository(row.repo);
+			const canonical = rowRepo === canonicalRepo;
+			const legacy = typeof row.repo === 'string' && row.repo.trim().toLowerCase() === legacyRepo;
+			if (!canonical && !legacy) return true;
+			const number = String(row.number);
+			const count = counts.get(number) || { canonical: 0, legacy: 0 };
+			if (canonical) count.canonical += 1;
+			else count.legacy += 1;
+			counts.set(number, count);
+			return count.canonical > 1 || count.legacy > 1;
+		});
+		if (conflicting) return { openPrs: [], gitCommonDir, listingOk: false, repositoryOk: false };
+	}
+	const exactRows = new Map();
+	const legacyRows = new Map();
+	const add = (map, number, row) => {
+		if (!validPrNumber(number)) return;
+		const list = map.get(String(number)) || [];
+		list.push(row);
+		map.set(String(number), list);
+	};
+	for (const row of rows) {
+		if (canonicalRepo && normalizeRepository(row && row.repo) === canonicalRepo) add(exactRows, row.number, row);
+		else if (legacyRepo && row && typeof row.repo === 'string' && row.repo.trim().toLowerCase() === legacyRepo) add(legacyRows, row.number, row);
+		else if (!canonicalRepo && row && row.repo === repo) add(exactRows, row.number, row);
+	}
+	const coalesceLinkage = (canonical, legacy) => {
+		if (!canonical || !legacy) return canonical || legacy || null;
+		const merged = { ...canonical };
+		for (const field of LINKAGE_FIELDS) {
+			const canonicalValue = canonical[field] ?? null;
+			const legacyValue = legacy[field] ?? null;
+			if (canonicalValue != null && legacyValue != null && canonicalValue !== legacyValue) return null;
+			if (canonicalValue == null && legacyValue != null) merged[field] = legacyValue;
+		}
+		return merged;
+	};
+	const mergedRows = new Map();
+	for (const number of new Set([...exactRows.keys(), ...legacyRows.keys()])) {
+		const exact = exactRows.get(number) || [];
+		const legacy = legacyRows.get(number) || [];
+		const merged = coalesceLinkage(exact[0], legacy[0]);
+		if (exact.length > 0 && legacy.length > 0 && !merged) {
+			return { openPrs: [], gitCommonDir, listingOk: false, repositoryOk: false };
+		}
+		if (merged) mergedRows.set(number, merged);
+	}
+	const rowForPr = (p) => {
+		if (canonicalRepo) return mergedRows.get(String(p.number)) || null;
+		const exact = exactRows.get(String(p.number)) || [];
+		return exact.length === 1 ? exact[0] : null;
+	};
 
 	const openPrs = ghPrs.map((p) => {
-		const row = rowByKey.get(keyOf(repo, p.number));
+		const row = rowForPr(p);
 		return {
-			repo,
+			repo: canonicalRepo || repo,
 			number: p.number,
 			branch: p.headRefName ?? null,
 			headSha: p.headRefOid ?? null,
@@ -169,7 +293,8 @@ async function gatherDesired(gitCommonDir, opts = {}) {
 async function gatherObserved(gitCommonDir, lock, opts = {}) {
 	const broker = opts.broker || null; // live kernel handle threaded by the daemon; never the module namespace
 	const isAlive = opts.isAlive || shepherdLease.pidAlive;
-	const readClaim = opts.readClaim || ((repo, pr) => readClaimMarker(opts.projectRoot, repo, pr));
+	const readClaim = opts.readClaim
+		|| ((repo, pr) => readClaimMarker(opts.projectRoot, repo, pr, gitCommonDir));
 	const now = (opts.now || (() => Date.now()))();
 
 	let prRows = [];
@@ -206,7 +331,8 @@ function verifiedKill(entry, ctx) {
 	if (!entry || entry.pid == null || entry.startedAt == null) return false;
 	const isAlive = ctx.isAlive || shepherdLease.pidAlive;
 	if (!isAlive(entry.pid)) return false;
-	const readClaim = ctx.readClaim || ((e) => readClaimMarker(ctx.projectRoot, e.repo, e.pr));
+	const readClaim = ctx.readClaim
+		|| ((e) => readClaimMarker(ctx.projectRoot, e.repo, e.pr, ctx.gitCommonDir));
 	const claim = readClaim(entry);
 	if (claim == null || String(claim) !== String(entry.startedAt)) return false;
 	try {
@@ -228,7 +354,9 @@ const ACTION_HANDLERS = {
 	startWatcher(action, s) {
 		const startedAt = new Date(s.now()).toISOString();
 		const repo = action.pr.repo ?? s.repo ?? null;
-		const res = s.spawnWatcher({ prNumber: action.pr.number, cwd: s.projectRoot });
+		const res = s.spawnWatcher({
+			prNumber: action.pr.number, cwd: s.projectRoot, gitCommonDir: s.gitCommonDir,
+		});
 		const pid = res && res.pid != null ? res.pid : null;
 		// A pid-less result means the watcher is already running (ship/push/adopt started it,
 		// startPrWatcherDetached → {started:false, reason:'already-running'}) or the spawn
@@ -254,9 +382,12 @@ const ACTION_HANDLERS = {
 	},
 	async upsertPrRow(action, s) {
 		try {
-			if (s.broker) await s.broker.upsertPr(action.row);
+			if (!s.broker) return true;
+			const result = await s.broker.upsertPr(action.row);
+			return result !== false && !(result && result.ok === false);
 		} catch {
 			/* derived reconcile state — a failed upsert retries on the next converge */
+			return false;
 		}
 	},
 	async retire(action, s) {
@@ -272,7 +403,8 @@ const ACTION_HANDLERS = {
 };
 
 /**
- * Dispatch a reconcile action set. Idempotent and order-free. Returns the updated
+ * Dispatch a reconcile action set in order. A failed kernel upsert stops the pass so
+ * dependent retire actions retry on the next converge. Returns the updated
  * watcher entry list (`{pr,repo,pid,startedAt}[]`) for the caller to publish via
  * `updateWatchers`. `ctx.watchers` seeds the current set (from observed state).
  */
@@ -280,8 +412,10 @@ async function execute(actions, ctx = {}) {
 	const s = {
 		broker: ctx.broker || null, // live kernel handle threaded by the daemon; never the module namespace
 		spawnWatcher: ctx.spawnWatcher || startPrWatcherDetached,
-		writeClaim: ctx.writeClaim || ((e) => writeClaimMarker(ctx.projectRoot, e.repo, e.pr, e.startedAt)),
-		removeClaim: ctx.removeClaim || ((e) => removeClaimMarker(ctx.projectRoot, e.repo, e.pr)),
+		writeClaim: ctx.writeClaim
+			|| ((e) => writeClaimMarker(ctx.projectRoot, e.repo, e.pr, e.startedAt, ctx.gitCommonDir)),
+		removeClaim: ctx.removeClaim
+			|| ((e) => removeClaimMarker(ctx.projectRoot, e.repo, e.pr, ctx.gitCommonDir)),
 		now: ctx.now || (() => Date.now()),
 		repo: ctx.repo,
 		projectRoot: ctx.projectRoot,
@@ -292,7 +426,7 @@ async function execute(actions, ctx = {}) {
 
 	for (const action of (Array.isArray(actions) ? actions : [])) {
 		const handler = ACTION_HANDLERS[action && action.type];
-		if (handler) await handler(action, s);
+		if (handler && (await handler(action, s)) === false) break;
 	}
 	return s.watchers;
 }
@@ -367,6 +501,10 @@ async function runDaemon(projectRoot, opts = {}) {
 	const release = opts.release || shepherdLease.release;
 	const converge = opts.convergeOnce || convergeOnce;
 	const now = opts.now || (() => Date.now());
+	// Tests that replace acquisition own the matching ownership seam as well.
+	// Production always verifies the real shared lock by exact pid+token.
+	const ownsLease = opts.ownsLease
+		|| (opts.acquire ? (() => true) : shepherdLease.owns);
 	// Injectable exit so a lifecycle test can assert the daemon actually exits
 	// (finding 4). `opts.exit === false` keeps the process alive (legacy test mode).
 	const exit = typeof opts.exit === 'function'
@@ -375,6 +513,7 @@ async function runDaemon(projectRoot, opts = {}) {
 
 	const res = acquire(projectRoot, { gitCommonDir });
 	if (!res.ok) {
+		exit(0);
 		// A live, fresh foreign daemon owns this repo — exit immediately, spawn nothing.
 		return { ok: false, reason: 'foreign-lease' };
 	}
@@ -413,7 +552,10 @@ async function runDaemon(projectRoot, opts = {}) {
 
 	if (opts.once) {
 		const conv = await converge(projectRoot, convergeArgs);
-		if (conv.desiredCount === 0) await retire();
+		if (conv.desiredCount === 0) {
+			recordDaemonDiagnostic(opts, gitCommonDir, 'retired-no-open-prs');
+			await retire();
+		}
 		return { ok: true, token, ...conv };
 	}
 
@@ -423,10 +565,30 @@ async function runDaemon(projectRoot, opts = {}) {
 	let lastWatchers = [];  // finding 2: thread the live watcher set across passes
 	let timer = null;
 
+	const retireForLeaseLoss = async () => {
+		stopped = true;
+		if (timer) clearInterval(timer);
+		recordDaemonDiagnostic(opts, gitCommonDir, 'lease-lost');
+		await retire();
+		exit(0);
+	};
+
+	const stillOwnsLease = () => {
+		try {
+			return ownsLease(projectRoot, { gitCommonDir, token });
+		} catch {
+			return false;
+		}
+	};
+
 	const runPass = async () => {
 		// A tick that fires while the previous pass is still in flight (converge slower
 		// than intervalMs) returns immediately, so passes never race on start/stop/reap.
 		if (stopped || inFlight) return;
+		if (!stillOwnsLease()) {
+			await retireForLeaseLoss();
+			return;
+		}
 		inFlight = true;
 		try {
 			// Thread the live watcher set + a fresh heartbeat stamp so gatherObserved
@@ -434,22 +596,26 @@ async function runDaemon(projectRoot, opts = {}) {
 			// saw lease:null every tick and re-started a watcher for every PR forever.
 			const passLock = { watchers: lastWatchers, heartbeatAt: new Date(now()).toISOString() };
 			const conv = await converge(projectRoot, { ...convergeArgs, lock: passLock });
+			if (!stillOwnsLease()) {
+				await retireForLeaseLoss();
+				return;
+			}
 			if (conv && Array.isArray(conv.watchers)) lastWatchers = conv.watchers;
 			// Superseded: a newer daemon reclaimed our stale lease. Stop and exit — retire()
 			// won't touch the foreign lock (release is token-guarded), so the new owner is
 			// left intact; we just stop spawning/reaping behind it.
 			if (conv && conv.leaseLost) {
-				stopped = true;
-				if (timer) clearInterval(timer);
-				await retire();
-				exit(0);
+				await retireForLeaseLoss();
 			} else if (conv && conv.desiredCount === 0) {
 				stopped = true;
 				if (timer) clearInterval(timer);
+				recordDaemonDiagnostic(opts, gitCommonDir, 'retired-no-open-prs');
 				await retire();
 				exit(0);
 			}
-		} catch {
+		} catch (error) {
+			recordDaemonDiagnostic(opts, gitCommonDir, 'converge-failed', error);
+			if (!stillOwnsLease()) await retireForLeaseLoss();
 			/* a bad converge pass never crashes the daemon — the next tick retries */
 		} finally {
 			inFlight = false;
@@ -478,9 +644,12 @@ async function runDaemon(projectRoot, opts = {}) {
  */
 function launchDaemon(ctx = {}) {
 	const harness = ctx.harness || {};
+	const commonRoot = path.basename(ctx.gitCommonDir || '').toLowerCase() === '.git'
+		? path.dirname(ctx.gitCommonDir)
+		: ctx.projectRoot;
 	if (harness.hasBgShell && typeof harness.runBgShell === 'function') {
 		try {
-			harness.runBgShell([forgeBin(), 'shepherd', 'daemon']);
+			harness.runBgShell([process.execPath, forgeBin(), 'shepherd', 'daemon'], { cwd: commonRoot });
 			return { launched: true, via: 'bg-shell' };
 		} catch {
 			/* fall through to the detached fail-safe */
@@ -491,12 +660,17 @@ function launchDaemon(ctx = {}) {
 		const child = spawnFn(
 			process.execPath,
 			[forgeBin(), 'shepherd', 'daemon'],
-			{ cwd: ctx.projectRoot, detached: true, stdio: 'ignore', windowsHide: true },
+			{ cwd: commonRoot, detached: true, stdio: 'ignore', windowsHide: true },
 		);
-		if (child && typeof child.on === 'function') child.on('error', () => {});
+		if (child && typeof child.on === 'function') {
+			child.on('error', (error) => {
+				recordDaemonDiagnostic(ctx, ctx.gitCommonDir, 'launch-failed', error);
+			});
+		}
 		if (child && typeof child.unref === 'function') child.unref();
 		return { launched: true, via: 'detached', pid: child && child.pid != null ? child.pid : null };
-	} catch {
+	} catch (error) {
+		recordDaemonDiagnostic(ctx, ctx.gitCommonDir, 'launch-failed', error);
 		return { launched: false };
 	}
 }
@@ -570,7 +744,7 @@ function emptyEnum(gitCommonDir) {
 }
 
 /**
- * The per-command / session-start trigger. Runs the `tick()` debounce; the hot
+ * The session-start / successful-push / successful-ship trigger. Runs the `tick()` debounce; the hot
  * path (a fresh daemon lease) short-circuits in-process with a single lock read
  * and no spawn. Only on the cold (G3) path does it ARBITRATE via the O_EXCL lease:
  * the acquire-winner launches the singleton daemon (which does the real
@@ -586,16 +760,24 @@ function emptyEnum(gitCommonDir) {
  */
 function fireAndForget(ctx = {}) {
 	try {
+		const env = ctx.env || process.env;
 		// Operator kill-switch (agent-agnostic): a set FORGE_SHEPHERD_DISABLE turns the
 		// autonomous trigger fully inert — no lease, no enumeration, no daemon spawn.
-		if (process.env.FORGE_SHEPHERD_DISABLE) return;
+		if (
+			env.FORGE_SHEPHERD_DISABLE
+			|| env.NODE_ENV === 'test'
+			|| env.BUN_ENV === 'test'
+			|| env.CI
+			|| env.GITHUB_ACTIONS
+			|| env.GITLAB_CI
+		) return;
 		const projectRoot = ctx.projectRoot;
 		if (!projectRoot) return;
 		// A dry-run must have ZERO side effects, and the trigger must CREATE NOTHING in an
 		// uninitialized / setup-or-init TARGET repo (no-lazy-create invariant, same as prime).
 		// Both guards run BEFORE any git/lock touch so `setup --dry-run` / `init` stay
 		// side-effect- AND output-clean (kernelInitialized is silent). Checked here, not the
-		// caller, so every trigger site (dispatch, session-start) is covered uniformly.
+		// caller, so every approved trigger site is covered uniformly.
 		if (ctx.dryRun) return;
 		if (!(ctx.kernelInitialized || kernelInitialized)(projectRoot)) return;
 		// Config kill-switch (same gate ship/push/adopt honor): a maintainer who ran
@@ -654,6 +836,7 @@ module.exports = {
 	convergeOnce,
 	runDaemon,
 	launchDaemon,
+	writeDaemonDiagnostic,
 	defaultBuildBroker,
 	fireAndForget,
 };

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