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

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

@@ -147,6 +147,10 @@ function renderChecks(bundle, lines) {
  * @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] - the canonical `--pull` verdict.
+ * @param {string[]} [opts.unreadable] - unreadable signal names (from the `--pull`
+ *   evidence). Surfaced when the verdict is UNKNOWN so the sticky always says WHICH
+ *   signal could not be read, not just a bare `unknown`.
  * @returns {{ marker: string, body: string }}
  */
 function renderStickyComment(bundle = {}, opts = {}) {
@@ -163,6 +167,16 @@ function renderStickyComment(bundle = {}, opts = {}) {
   // by pr-pull). Surface only: it labels state; this monitor **does not merge**
   // and never resolves review threads.
   lines.push(verdictHeadline(opts.verdict));
+  // An `unknown` verdict is useless without the WHY — name the unreadable
+  // signal(s) so a human/agent knows what to fix (e.g. `requiredChecks` when both
+  // branch-protection AND the rollup fallback could not be read).
+  const verdictUpper = String(opts.verdict || '').toUpperCase();
+  const isUnknown = verdictUpper === 'UNKNOWN' || !VERDICT_HEADLINE[verdictUpper];
+  const unreadable = Array.isArray(opts.unreadable) ? opts.unreadable.filter(Boolean) : [];
+  if (isUnknown && unreadable.length > 0) {
+    lines.push('');
+    lines.push(`> Unreadable signal(s): ${unreadable.map((s) => `\`${s}\``).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('');

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

@@ -0,0 +1,243 @@
+'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. */
+const STALE_MS = 30000;
+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 */
+  }
+}
+
+module.exports = {
+  STALE_MS,
+  lockFilePath,
+  pidAlive,
+  ownsLock,
+  acquire,
+  stamp,
+  startHeartbeat,
+  stopHeartbeat,
+  updateWatchers,
+  release,
+};

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

@@ -88,7 +88,7 @@ async function upsertStickyComment({ marker }, client) {
 // 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
+  return execFileSync('gh', args, { encoding: 'utf8', windowsHide: true }); // NOSONAR S4036 - hardcoded CLI (gh), args array (no shell), developer-tool context. windowsHide: sticky upsert runs in the detached watcher (issue 931e7924).
 }
 
 /**

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

@@ -35,7 +35,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;

package/lib/pr-pull.js

@@ -28,7 +28,7 @@
  * @module pr-pull
  */
 
-const { isFailed, isGreen, runShepherdPass } = require('./pr-shepherd');
+const { isFailed, isGreen } = require('./pr-shepherd');
 const { fenceUntrusted } = require('./untrusted-content');
 
 /** Token caps that keep the payload bounded regardless of PR size. */
@@ -680,9 +680,12 @@ function buildPullPayload({
 
   return {
     ...prField(pr),
+    // DEPRECATED: `state` is the legacy decision-pass ladder, kept only for
+    // back-compat. It is now a PROJECTION of `verdict` (via verdictToLegacyState),
+    // never independently computed. Consumers MUST read `verdict` — the single,
+    // trustworthy, fail-closed merge vocabulary (never false-clean). Full removal
+    // of `state` is tracked as a follow-up kernel issue.
     state,
-    // `verdict` is the trustworthy, fail-closed merge signal (never false-clean);
-    // `state` remains the legacy decision-pass state for back-compat.
     ...(verdict ? { verdict } : {}),
     ...(evidence ? { evidence } : {}),
     summary,
@@ -993,6 +996,52 @@ function verdictLabel(verdict) {
 /** The full label reconcile set — one label per canonical verdict. */
 const VERDICT_LABELS = MERGE_VERDICTS.map((v) => `${VERDICT_LABEL_PREFIX}${v.toLowerCase()}`);
 
+/**
+ * The ONE place that maps the canonical 7-enum `verdict` onto the DEPRECATED
+ * legacy `runShepherdPass` ladder (`pr-shepherd.js:34`). `verdict` is the single
+ * consumer-facing vocabulary; the payload's `state` field is a back-compat
+ * PROJECTION of the verdict through this map — never independently computed — so
+ * the two can never disagree. Unknown/empty input fails closed to `UNKNOWN`.
+ *
+ * @param {string} verdict - a canonical MERGE_VERDICTS value.
+ * @returns {string} the deprecated legacy state.
+ */
+function verdictToLegacyState(verdict) {
+  const v = String(verdict || '').toUpperCase();
+  switch (v) {
+    case 'CLEAN-MERGEABLE': return 'MERGE_READY';
+    case 'REVIEW-PENDING': return 'NEEDS_REVIEW';
+    case 'BLOCKED-THREADS': return 'NEEDS_REVIEW';
+    case 'BLOCKED-CHECKS': return 'PENDING';
+    // BEHIND maps to ESCALATE, not PENDING: the legacy runShepherdPass escalated a
+    // behind head (handleBehindBase with --auto-rebase OFF, the default) so a human
+    // rebases or opts into auto-rebase. Mapping it to PENDING would tell a legacy
+    // `state` consumer to keep waiting on a PR that actually needs action.
+    case 'BEHIND': return 'ESCALATE';
+    case 'BLOCKED-CONFLICT': return 'ESCALATE';
+    default: return 'UNKNOWN';
+  }
+}
+
+/**
+ * The back-compat legacy `state` for the `--pull` payload. A terminal GitHub
+ * lifecycle (`MERGED`/`CLOSED`) wins over the merge verdict: the old dry-run
+ * `runShepherdPass` hit `lifecycleOutcome` first (`pr-shepherd.js:403`) and
+ * emitted `MERGED`/`CLOSED` so a legacy consumer stops polling / stops prompting a
+ * human to merge an already-landed PR. `computeVerdict`'s 7-enum has no terminal
+ * value, so we read the lifecycle (`adapter.readState().state`) here; only an open
+ * PR falls through to the verdict projection.
+ *
+ * @param {string} verdict - a canonical MERGE_VERDICTS value.
+ * @param {string} [prLifecycleState] - readState().state: OPEN | MERGED | CLOSED.
+ * @returns {string} the deprecated legacy state.
+ */
+function legacyStateFor(verdict, prLifecycleState) {
+  const lifecycle = String(prLifecycleState || '').toUpperCase();
+  if (lifecycle === 'MERGED' || lifecycle === 'CLOSED') return lifecycle;
+  return verdictToLegacyState(verdict);
+}
+
 /**
  * Run an optional read and SURFACE any failure instead of swallowing it: on
  * throw, record `{ source, error }` into `degraded` (and optionally mark `source`
@@ -1067,7 +1116,6 @@ function gatherFailureExcerpts(runGh, checks, requiredSet, { maxFailures, maxExc
  * @param {string} [ctx.self]  - shepherd's own login
  * @param {object} ctx.adapter - validated pr-state adapter
  * @param {(args: string[]) => string} ctx.runGh - injected `gh` runner (args → stdout)
- * @param {Function} [ctx.runPass] - decision pass (default runShepherdPass), injectable for tests
  * @param {number} [ctx.maxFailures]
  * @param {number} [ctx.maxThreads]
  * @param {number} [ctx.maxExcerptLines]
@@ -1093,7 +1141,9 @@ async function gatherPrSnapshot(ctx) {
   const state = await adapter.readState(pr);
   const requiredSet = await safeRead(
     'requiredChecks',
-    () => adapter.readRequiredChecks({ owner, repo, base }),
+    // `pr` lets the adapter fall back to the rollup `isRequired` set when branch
+    // protection is unreadable (the Actions token can't read protection).
+    () => adapter.readRequiredChecks({ owner, repo, base, pr }),
     { degraded, fallback: null },
   );
 
@@ -1195,6 +1245,11 @@ async function gatherPrSnapshot(ctx) {
     unreadable,
   });
 
+  // Record which source answered the required-checks read (`protection` |
+  // `rollup` | null) so the source is visible in the verdict evidence — the
+  // rollup source is the CI path where branch protection is unreadable.
+  evidence.requiredSource = adapter.lastRequiredSource || null;
+
   return {
     state, requiredSet, threads, behind, conflicts, issueComments,
     botStatusBlockers, requiredChecks, pendingChecks, draft, reviewDecision,
@@ -1207,7 +1262,6 @@ async function gatherPrSnapshot(ctx) {
 async function gatherPullSignal(ctx) {
   const {
     pr, self, adapter, runGh,
-    runPass = runShepherdPass,
     maxFailures = DEFAULT_MAX_FAILURES,
     maxThreads = DEFAULT_MAX_THREADS,
     maxExcerptLines = DEFAULT_MAX_EXCERPT_LINES,
@@ -1230,12 +1284,12 @@ async function gatherPullSignal(ctx) {
     requiredChecks, pendingChecks, draft, reviewDecision, verdict, evidence, degraded,
   } = snap;
 
-  // Legacy decision pass (READ-ONLY dryRun) for back-compat `state`. Shares the
-  // snapshot's `degraded` so a pass-read failure is still surfaced in the payload.
-  const pass = await safeRead('pass', () => runPass({ ...ctx, adapter, dryRun: true }), {
-    degraded,
-    fallback: { state: 'UNKNOWN', reason: 'Decision pass could not complete — a read failed; see verdict evidence.' },
-  });
+  // `verdict` is the SINGLE consumer-facing vocabulary. The back-compat `state`
+  // field is DERIVED from it (via legacyStateFor) — the read-only `--pull` payload
+  // no longer runs a second decision pass, so the two vocabularies can never
+  // disagree. A terminal lifecycle (MERGED/CLOSED) still wins over the verdict so
+  // legacy consumers see the landed outcome, matching the old dry-run pass.
+  const legacyState = legacyStateFor(verdict, state.state);
 
   const failures = gatherFailureExcerpts(runGh, state.checks, requiredSet, { maxFailures, maxExcerptLines, degraded });
   const reviewThreads = buildReviewThreads(threads, self, { maxThreads });
@@ -1254,7 +1308,7 @@ async function gatherPullSignal(ctx) {
   });
 
   const summary = summarize({
-    state: pass.state,
+    state: legacyState,
     failureCount: failures.length,
     threadCount: reviewThreads.length,
     blockers,
@@ -1262,11 +1316,10 @@ async function gatherPullSignal(ctx) {
 
   return buildPullPayload({
     pr,
-    state: pass.state,
+    state: legacyState,
     verdict,
     evidence,
     degraded,
-    reason: pass.reason,
     summary,
     mergeable: state.mergeable || 'UNKNOWN',
     mergeStateStatus: state.mergeStateStatus || 'UNKNOWN',
@@ -1299,6 +1352,8 @@ module.exports = {
   renderPullSummary,
   buildPullPayload,
   computeVerdict,
+  verdictToLegacyState,
+  legacyStateFor,
   MERGE_VERDICTS,
   VERDICT_LABELS,
   VERDICT_LABEL_PREFIX,

package/lib/project-memory.js

@@ -140,6 +140,13 @@ function searchRanked(projectRoot, query, limit, options = {}) {
   return resolveStore(projectRoot, options).searchMemoriesRanked(query, limit);
 }
 
+// Relevance-only BM25 recall that returns the raw bm25 `score` per entry, so a caller can
+// apply a relevance floor. A no-match/empty query returns [] (no recency fallback). The
+// per-turn memory-recall hook uses this to inject nothing unless a note clearly matches.
+function searchRankedScored(projectRoot, query, limit, options = {}) {
+  return resolveStore(projectRoot, options).searchMemoriesRankedScored(query, limit);
+}
+
 // Close and forget every cached default store. The CLI process is short-lived (the OS
 // closes the handle on exit), so this is mainly a lifecycle helper for long-lived hosts and
 // tests — it releases the SQLite/WAL handle before a temp dir is removed.
@@ -162,5 +169,6 @@ module.exports = {
   recent,
   count,
   searchRanked,
+  searchRankedScored,
   closeAll,
 };

package/lib/rules-sync.js

@@ -48,6 +48,10 @@ const CURSOR_RULE_FILES = {
   security: 'security-scanning.mdc',
   documentation: 'documentation.mdc',
   'kernel-tracking': 'kernel-tracking.mdc',
+  // The using-forge dispatch pointer as an always-apply Cursor rule — Cursor's native
+  // always-on carrier for the skill auto-trigger bootstrap (parallels the Claude SessionStart
+  // hook and the committed AGENTS.md for Codex). Thin pointer; full policy stays in the skill.
+  'using-forge': 'using-forge.mdc',
 };
 
 const CANONICAL_RULE_NAMES = Object.keys(CURSOR_RULE_FILES);