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

package/lib/commands/shepherd.js

@@ -3,11 +3,11 @@
 /**
  * shepherd command — one bounded monitor pass over a pull request.
  *
- * `forge shepherd <pr> [--auto-rebase]` reads PR/CI state, takes at most one
- * idempotent Tier-A action (rerun a flaky required check), and exits with a
- * terminal state. It NEVER merges and NEVER resolves review threads. A
- * `--watch` loop, if desired, lives in an external scheduler that re-invokes
- * this command on an interval — there is no in-process polling loop here.
+ * `forge shepherd <pr> [--auto-rebase]` runs one local review preflight, reads
+ * PR/CI state, takes at most one idempotent Tier-A action (rerun a flaky required
+ * check), persists bounded deltas/receipts, and exits. It NEVER merges and NEVER
+ * resolves review threads. Event-driven waiting belongs to the singleton/watch
+ * process; this command does not model-poll or loop in-process.
  *
  * `forge shepherd <pr> --bundle --json` instead prints the COMPLETE read-only
  * PR-state bundle (all unresolved threads, merge state, CI, divergence,
@@ -21,12 +21,13 @@
  * done IN CODE so an agent gets one payload instead of running those by hand. It
  * still NEVER merges and NEVER resolves threads.
  *
- * State persists via GitHub PR comments/labels and git only.
+ * Public Memory is durable authority; the local journal is compatibility delivery.
  *
  * @module commands/shepherd
  */
 
 const { execFileSync } = require('node:child_process');
+const crypto = require('node:crypto');
 
 const { runShepherdPass } = require('../pr-shepherd');
 const { gatherPrBundle } = require('../pr-bundle');
@@ -34,15 +35,26 @@ const { gatherPullSignal, renderPullSummary } = require('../pr-pull');
 const { PrStateAdapter } = require('../adapters/pr-state-adapter');
 const { validatePrStateAdapter } = require('../pr-state-validator');
 const { gatherMonitorSnapshot } = require('../pr-monitor/gather');
+const { privacySafeIdentity } = require('../pr-monitor/flow-monitor');
 const { pollEvents } = require('../pr-monitor/monitor');
 const { watchLoop } = require('../pr-monitor/watch');
-const { startPrWatcherDetached } = require('../pr-monitor/watch-lifecycle');
+const { startPrWatcherDetached, launchGateComplete } = require('../pr-monitor/watch-lifecycle');
+const watchOwner = require('../pr-monitor/watch-owner');
 const reconcileExecutor = require('../pr-monitor/reconcile-executor');
 const monitorJournal = require('../pr-monitor/journal');
+const brokerMod = require('../kernel/broker');
 const { EVENT_TYPES: T } = require('../pr-monitor/events');
 const { autoShepherdRailEnabled } = require('./ship');
+const { runLocalReviewPreflight } = require('../pr-monitor/review-preflight');
 
 const DEFAULT_RERUN_BUDGET = 3;
+const MAX_MONITOR_ID_LENGTH = 128;
+
+function rootMonitorId(owner, repo, pr) {
+  const raw = privacySafeIdentity(`pr:${privacySafeIdentity(`${owner}/${repo}`)}:${pr}`);
+  if (raw.length <= MAX_MONITOR_ID_LENGTH) return raw;
+  return `pr:${crypto.createHash('sha256').update(raw).digest('hex')}`;
+}
 
 // windowsHide: true on EVERY spawn here is load-bearing, not cosmetic. The
 // shepherd watcher runs detached in the background and re-polls every ~60s; on
@@ -51,14 +63,35 @@ const DEFAULT_RERUN_BUDGET = 3;
 // preferred home is the harness's managed shell (hidden + reaped); a
 // Forge-spawned detached watcher is the no-session fallback and must be
 // COMPLETELY silent — no console window, ever. See kernel issue 931e7924.
-const defaultGhRunner = (cmd, a) => execFileSync(cmd, a, { encoding: 'utf8', timeout: 30000, windowsHide: true });
+const defaultGhRunner = (cmd, a, options = {}) => execFileSync(cmd, a, {
+  encoding: 'utf8', timeout: 30000, windowsHide: true, ...options,
+});
+
+function githubRunner(deps, projectRoot) {
+  return deps.githubContext?.bound
+    ? (_cmd, args, options = {}) => deps.githubContext.runGh(args, {
+      encoding: 'utf8', timeout: 30000, windowsHide: true, cwd: projectRoot, ...options,
+    })
+    : (deps.gh || defaultGhRunner);
+}
+
+function resolveTargetRepository(gh = defaultGhRunner) {
+  const repoJson = gh('gh', ['repo', 'view', '--json', 'nameWithOwner,parent']);
+  const repoInfo = JSON.parse(repoJson || '{}');
+  const repository = repoInfo.parent?.nameWithOwner || repoInfo.nameWithOwner;
+  if (typeof repository !== 'string'
+    || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)) {
+    throw new Error('PR base repository is unavailable from the checkout');
+  }
+  return repository.toLowerCase();
+}
 
 /**
  * Resolve owner/repo and base branch for the shepherd pass.
  *
- * The base branch is read from the PR itself (`gh pr view <pr> --json
- * baseRefName`) rather than the current checkout's default branch, so PRs
- * targeting `release/*`/`develop` are evaluated against the correct branch.
+ * The exact base commit is read from the PR itself (`gh pr view <pr> --json
+ * baseRefOid`) rather than a local remote, so fork checkouts and PRs targeting
+ * `release/*`/`develop` are evaluated against the provider's reviewed base.
  * `owner`/`name` come from the repository the PR is queried in — that IS the
  * base repository. `cwd` (the worktree root) is threaded through so divergence
  * is computed against the right checkout.
@@ -66,21 +99,30 @@ const defaultGhRunner = (cmd, a) => execFileSync(cmd, a, { encoding: 'utf8', tim
  * @param {object} deps
  * @returns {Promise<{ pr: string, owner: string, repo: string, base: string, baseRef: string, cwd?: string }>}
  */
-async function defaultBuildContext({ pr, gh, git, projectRoot }) {
-  const prJson = gh('gh', ['pr', 'view', String(pr), '--json', 'baseRefName']);
+async function defaultBuildContext({ pr, gh, git, projectRoot, repository }) {
+  const targetRepository = repository || resolveTargetRepository(gh);
+  const prJson = gh('gh', [
+    'pr', 'view', String(pr), '--repo', targetRepository,
+    '--json', 'baseRefName,baseRefOid,headRefOid,state',
+  ]);
   const prInfo = JSON.parse(prJson || '{}');
   const base = prInfo.baseRefName || 'master';
+  if (typeof prInfo.baseRefOid !== 'string' || !/^[0-9a-f]{40}$/i.test(prInfo.baseRefOid)) {
+    throw new Error('PR base commit is unavailable from the provider');
+  }
+  const baseRef = prInfo.baseRefOid.toLowerCase();
+  const headSha = typeof prInfo.headRefOid === 'string' && /^[0-9a-f]{40}$/i.test(prInfo.headRefOid)
+    ? prInfo.headRefOid.toLowerCase()
+    : null;
 
-  const repoJson = gh('gh', ['repo', 'view', '--json', 'owner,name']);
-  const repo = JSON.parse(repoJson || '{}');
-  const owner = repo.owner?.login || '';
-  const name = repo.name || '';
+  const [owner, name] = targetRepository.split('/');
 
-  let baseRemote;
+  let localHead = null;
   try {
-    baseRemote = git('git', ['remote']).split(/\s+/).filter(Boolean)[0] || 'origin';
-  } catch (_err) {
-    baseRemote = 'origin';
+    const candidate = git('git', ['rev-parse', 'HEAD']).trim();
+    if (/^[0-9a-f]{40}$/i.test(candidate)) localHead = candidate.toLowerCase();
+  } catch {
+    /* a missing local checkout makes local review preflight not applicable */
   }
 
   return {
@@ -88,7 +130,10 @@ async function defaultBuildContext({ pr, gh, git, projectRoot }) {
     owner,
     repo: name,
     base,
-    baseRef: `${baseRemote}/${base}`,
+    baseRef,
+    headSha,
+    prState: typeof prInfo.state === 'string' ? prInfo.state.toUpperCase() : null,
+    localHead,
     ...(projectRoot ? { cwd: projectRoot } : {}),
   };
 }
@@ -121,6 +166,14 @@ function formatAction(action) {
   }
 }
 
+function writePassSummary(pr, state, reason, actions) {
+  const passActions = Array.isArray(actions) ? actions : [];
+  const reasonSuffix = reason ? ` — ${reason}` : '';
+  process.stdout.write(`Shepherd pass — PR #${pr}: ${state}${reasonSuffix}\n`);
+  for (const action of passActions) process.stdout.write(`  • ${formatAction(action)}\n`);
+  if (!passActions.length) process.stdout.write('  • no actions this pass\n');
+}
+
 /**
  * Build the DEFAULT `check.failed` enrichment hook for the events pull surface.
  *
@@ -138,6 +191,14 @@ function formatAction(action) {
  * @param {object} pullCtx - ctx forwarded to `gatherPull` (owner/repo/base/adapter/runGh/self).
  * @returns {(records: object[]) => Promise<void>}
  */
+const UNSAFE_MONITOR_EXCERPT = /(?:gh[pousr]_[a-z0-9]{20,}|github_pat_[a-z0-9_]{20,}|sk_(?:live|test)_[a-z0-9]{16,}|sk-[a-z0-9]{16,}|AKIA[0-9A-Z]{16}|(?:api[_-]?key|token|secret|password)\s*[:=]\s*\S{8,}|(?:^|[\\/])(?:users|home|root)[\\/]\S+)/i;
+
+function safeMonitorExcerpt(value) {
+  return typeof value === 'string' && value.length <= 16_384 && !UNSAFE_MONITOR_EXCERPT.test(value)
+    ? value
+    : null;
+}
+
 function makeCheckFailureEnricher(pullCtx) {
   const gatherPull = pullCtx.gatherPull || gatherPullSignal;
   return async (records) => {
@@ -156,7 +217,8 @@ function makeCheckFailureEnricher(pullCtx) {
       if (r.type !== T.CHECK_FAILED) continue;
       const f = byName.get(r.data?.name);
       if (!f) continue;
-      if (f.excerpt) r.data.excerpt = f.excerpt;
+      const excerpt = safeMonitorExcerpt(f.excerpt);
+      if (excerpt) r.data.excerpt = excerpt;
       if (f.jobUrl) r.data.jobUrl = f.jobUrl;
     }
   };
@@ -169,6 +231,20 @@ function parseSince(args) {
   return 0;
 }
 
+function booleanOwnerRunningProbe(probe) {
+  if (typeof probe !== 'function') return undefined;
+  return async () => {
+    const result = await probe();
+    if (result && typeof result === 'object' && result.ok === false) {
+      const error = new Error('Watcher authority is unavailable');
+      error.code = typeof result.reason === 'string' ? result.reason : 'authority_unavailable';
+      error.cause = result;
+      throw error;
+    }
+    return result === true;
+  };
+}
+
 /**
  * Build the shared monitor context — journal `dir`, bounded `gather`, and the
  * default `check.failed` enricher — that BOTH the `events` pull surface and the
@@ -183,21 +259,48 @@ function parseSince(args) {
 async function buildMonitorContext(pr, projectRoot, deps) {
   let dir = deps.dir;
   let gather = deps.gather;
+  let repository = typeof deps.repository === 'string' ? deps.repository.toLowerCase() : null;
+  let prState = deps.prState || null;
+  let ownerAuthority = {
+    owner: deps.owner || watchOwner,
+    ownerOptions: deps.ownerOptions,
+  };
+  let authority = deps.store ? {
+    store: deps.store,
+    monitorId: deps.monitorId,
+    ownerRunId: deps.ownerRunId,
+    packetId: deps.packetId,
+    subjectId: deps.subjectId,
+    close: deps.close || (async () => {}),
+  } : {};
   // enrich decorates newly-failed checks with log excerpts before the journal
   // append. The caller MUST supply the default (not just forward an injected
   // one), or a plain `forge shepherd events`/`watch` emits bare check.failed events.
   let enrich = deps.enrich;
   if (!gather || !dir) {
-    const gh = deps.gh || defaultGhRunner;
-    const git = deps.git || gh;
+    const gh = githubRunner(deps, projectRoot);
+    const git = deps.git || defaultGhRunner;
     const buildContext = deps.buildContext || defaultBuildContext;
-    const ctx = await buildContext({ pr, gh, git, projectRoot });
-    const adapter = deps.adapter || new PrStateAdapter({ gh, git });
+    const ctx = await buildContext({ pr, gh, git, projectRoot, repository });
+    repository = `${ctx.owner}/${ctx.repo}`.toLowerCase();
+    prState = ctx.prState;
+    const adapter = deps.adapter || new PrStateAdapter({ gh, git, repository });
     const validation = validatePrStateAdapter(adapter);
     if (!validation.valid) {
       return { error: `Invalid pr-state adapter: ${validation.errors.join('; ')}` };
     }
-    dir = dir || monitorJournal.journalDir({ root: projectRoot || process.cwd(), repo: ctx.repo, pr: ctx.pr });
+    let gitCommonDir = deps.gitCommonDir;
+    if (!gitCommonDir) {
+      try {
+        const resolveGitCommonDir = deps.resolveGitCommonDir || brokerMod.resolveGitCommonDir;
+        gitCommonDir = resolveGitCommonDir(projectRoot || process.cwd(), { warn: () => {} });
+      } catch {
+        /* unavailable common-dir keeps the legacy per-root journal fallback */
+      }
+    }
+    dir = dir || monitorJournal.journalDir({
+      root: projectRoot || process.cwd(), gitCommonDir, repo: ctx.repo, pr: ctx.pr,
+    });
     gather = gather || (() => gatherMonitorSnapshot({ ...ctx, adapter, self: deps.self }));
     enrich = enrich || makeCheckFailureEnricher({
       ...ctx,
@@ -206,6 +309,45 @@ async function buildMonitorContext(pr, projectRoot, deps) {
       runGh: (ghArgs) => gh('gh', ghArgs),
       gatherPull: deps.gatherPull,
     });
+    if (!deps.store) {
+      const buildKernelDeps = deps.buildKernelDeps
+        || require('../kernel/cli-broker-factory').buildMigratedKernelIssueDeps;
+      const createMonitorStore = deps.createMonitorStore
+        || require('../../packages/memory').createMonitorStore;
+      let kernel;
+      try {
+        kernel = await buildKernelDeps({ projectRoot: projectRoot || process.cwd(), gitCommonDir });
+        const repositoryIdentity = privacySafeIdentity(`${ctx.owner}/${ctx.repo}`);
+        authority = {
+          store: createMonitorStore(kernel.kernelDriver),
+          monitorId: rootMonitorId(ctx.owner, ctx.repo, ctx.pr),
+          ownerRunId: privacySafeIdentity(`shepherd:${repositoryIdentity}:${ctx.pr}`),
+          packetId: privacySafeIdentity(`shepherd-packet:${repositoryIdentity}:${ctx.pr}`),
+          subjectId: privacySafeIdentity(`${repositoryIdentity}#${ctx.pr}`),
+          close: async () => kernel.kernelBroker?.close?.(),
+        };
+        ownerAuthority = {
+          owner: deps.owner || watchOwner,
+          ownerOptions: {
+            driver: kernel.kernelDriver,
+            verifyProviderEvidence: async (evidence, expected) => (
+              typeof evidence?.state === 'string'
+              && expected.states.includes(evidence.state.toLowerCase())
+            ),
+            verifyTerminalReceipt: async (receiptId) => {
+              const state = await authority.store.readDeliveryState(authority.monitorId);
+              return state?.terminal_receipt?.object_id === receiptId;
+            },
+          },
+        };
+      } catch (error) {
+        try { await kernel?.kernelBroker?.close?.(); } catch { /* fallback must remain available */ }
+        if (deps.forceAuthority) {
+          return { error: `Durable monitor authority is unavailable: ${error.message}` };
+        }
+        authority = {};
+      }
+    }
   } else if (!enrich && deps.gatherPull) {
     // Injected gather (tests / programmatic callers) still gets the default
     // enrichment when a pull-signal source is supplied.
@@ -213,7 +355,19 @@ async function buildMonitorContext(pr, projectRoot, deps) {
       pr, adapter: deps.adapter, self: deps.self, runGh: deps.runGh, gatherPull: deps.gatherPull,
     });
   }
-  return { dir, gather, enrich };
+  if (deps.forceAuthority && !authority.store) {
+    return { error: 'Durable monitor authority is unavailable.' };
+  }
+  return {
+    dir,
+    gather,
+    enrich,
+    repo: repository,
+    pr: Number(pr),
+    prState,
+    ...authority,
+    ...ownerAuthority,
+  };
 }
 
 /**
@@ -238,15 +392,31 @@ async function handleEvents(args, projectRoot, deps = {}) {
 
   const built = await buildMonitorContext(pr, projectRoot, deps);
   if (built.error) return { success: false, error: built.error };
-  const { dir, gather, enrich } = built;
-
   const poll = deps.pollEvents || pollEvents;
-  const result = await poll({ dir, gather, since, now: deps.now, watcherRunning: deps.watcherRunning, enrich });
+  let result;
+  try {
+    result = await poll({
+      ...built,
+      since,
+      now: deps.now,
+      isOwnerRunning: booleanOwnerRunningProbe(deps.isOwnerRunning),
+    });
+  } finally {
+    await built.close?.();
+  }
   // `output` is the agent-agnostic pull surface: NDJSON, one event per line. The
   // registry CLI dispatch prints `result.output` (same contract as --pull/--bundle),
   // so this handler does NOT write to stdout itself (that would double-print).
-  const output = result.events.map((e) => JSON.stringify(e)).join('\n');
-  return { success: true, events: result.events, since: result.since, output };
+  const overflow = result.overflow === true;
+  const overflowRecord = overflow ? {
+    type: 'monitor.overflow',
+    since: result.since,
+    firstAvailableSeq: result.events[0]?.seq ?? null,
+    action: 'restart-from-checkpoint',
+  } : null;
+  const outputRecords = overflowRecord ? [overflowRecord, ...result.events] : result.events;
+  const output = outputRecords.map((event) => JSON.stringify(event)).join('\n');
+  return { success: true, events: result.events, since: result.since, overflow, output };
 }
 
 /**
@@ -287,9 +457,11 @@ function wireSignals() {
  * @param {Function} [exec] - gh runner (test injection).
  * @returns {number[]}
  */
-function defaultListOpenPrs(exec = execFileSync) {
+function defaultListOpenPrs(repository, exec = execFileSync) {
   try {
-    const out = exec('gh', ['pr', 'list', '--state', 'open', '--json', 'number', '-q', '.[].number'], {
+    const out = exec('gh', [
+      'pr', 'list', '--repo', repository, '--state', 'open', '--json', 'number', '-q', '.[].number',
+    ], {
       encoding: 'utf8', timeout: 20000, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true,
     });
     return String(out)
@@ -313,7 +485,7 @@ function defaultListOpenPrs(exec = execFileSync) {
  * @param {object} [deps]
  * @returns {{ success: true, adopted: number[], total: number, reason?: string }}
  */
-function handleAdopt(projectRoot, deps = {}) {
+async function handleAdopt(projectRoot, deps = {}) {
   const railEnabled = deps.railEnabled || autoShepherdRailEnabled;
   // Gate BEFORE listing PRs / spawning watchers: a disabled rail must not spawn
   // detached watchers. No-op result mirrors the fail-open (empty) adoption shape.
@@ -321,48 +493,145 @@ function handleAdopt(projectRoot, deps = {}) {
     return { success: true, adopted: [], total: 0, reason: 'rail.auto_shepherd disabled' };
   }
   const listOpenPrs = deps.listOpenPrs || defaultListOpenPrs;
+  const gh = githubRunner(deps, projectRoot);
   const startWatcher = deps.startWatcher || startPrWatcherDetached;
+  const resolveRepository = deps.resolveRepository
+    || (() => resolveTargetRepository(gh));
   let prs;
+  let repository;
+  let kernel;
+  let ownerOptions = deps.ownerOptions;
   try {
-    prs = listOpenPrs();
+    repository = resolveRepository();
+    if (!ownerOptions) {
+      const buildKernelDeps = deps.buildKernelDeps
+        || require('../kernel/cli-broker-factory').buildMigratedKernelIssueDeps;
+      kernel = await buildKernelDeps({ projectRoot: projectRoot || process.cwd() });
+      ownerOptions = {
+        driver: kernel.kernelDriver,
+        verifyProviderEvidence: async (evidence, expected) => (
+          evidence?.state === 'OPEN' && expected.states.includes('open')
+        ),
+      };
+    }
+    prs = listOpenPrs(repository, gh);
   } catch {
     prs = [];
   }
   if (!Array.isArray(prs)) prs = [];
   const adopted = [];
-  for (const pr of prs) {
-    try {
-      const res = startWatcher({ prNumber: pr, cwd: projectRoot });
-      if (res?.started) adopted.push(pr);
-    } catch { /* fail-open per PR: one bad arm never blocks the rest */ }
+  try {
+    for (const pr of prs) {
+      try {
+        const owner = deps.owner || watchOwner;
+        if (!await launchGateComplete(owner, ownerOptions)) continue;
+        const res = await startWatcher({
+          prNumber: pr,
+          cwd: projectRoot,
+          repository,
+          owner,
+          ownerOptions,
+          providerEvidence: { state: 'OPEN', repository, pr },
+        });
+        if (res?.started) adopted.push(pr);
+      } catch { /* fail-open per PR: one bad arm never blocks the rest */ }
+    }
+  } finally {
+    try { await kernel?.kernelBroker?.close?.(); } catch { /* best-effort handle cleanup */ }
   }
   return { success: true, adopted, total: prs.length };
 }
 
+function watchOption(args, name) {
+  const index = args.indexOf(name);
+  return index < 0 ? null : args[index + 1];
+}
+
 async function handleWatch(args, projectRoot, deps = {}) {
   const rawArgs = args || [];
   // `--adopt` (no PR arg): arm a detached watcher for every open PR.
   if (rawArgs.includes('--adopt')) {
     return handleAdopt(projectRoot, deps);
   }
-  const pr = rawArgs.find((a) => !String(a).startsWith('--') && a !== 'watch');
+  const optionIndexes = new Set();
+  for (const name of ['--repo', '--generation', '--controller-pid', '--started-at']) {
+    const index = rawArgs.indexOf(name);
+    if (index >= 0) optionIndexes.add(index + 1);
+  }
+  const pr = rawArgs.find((a, index) => !String(a).startsWith('--') && a !== 'watch' && !optionIndexes.has(index));
   if (!pr) {
     return { success: false, error: 'Usage: forge shepherd watch <pr> | forge shepherd watch --adopt' };
   }
 
-  const built = await buildMonitorContext(pr, projectRoot, deps);
+  const repository = watchOption(rawArgs, '--repo');
+  const suppliedGeneration = watchOption(rawArgs, '--generation');
+  const suppliedControllerPid = Number(watchOption(rawArgs, '--controller-pid'));
+  const built = await buildMonitorContext(pr, projectRoot, { ...deps, repository: repository || deps.repository });
   if (built.error) return { success: false, error: built.error };
-  const { dir, gather, enrich } = built;
-
+  const identity = { repo: built.repo, pr: Number(pr) };
+  const owner = built.owner || deps.owner || watchOwner;
+  const ownerOptions = built.ownerOptions || deps.ownerOptions || {};
+  let generation = suppliedGeneration;
+  let controllerPid = suppliedGeneration ? suppliedControllerPid : process.pid;
+  let reservedHere = false;
+  if (suppliedGeneration && (!Number.isSafeInteger(suppliedControllerPid) || suppliedControllerPid <= 0)) {
+    await built.close?.();
+    return { success: false, error: 'Watcher controller identity is invalid' };
+  }
+  if (!generation) {
+    if (!await launchGateComplete(owner, ownerOptions)) {
+      await built.close?.();
+      return {
+        success: true, started: false, passes: 0, stopped: false,
+        reason: 'migration-gate-incomplete',
+      };
+    }
+    let reserved = await owner.reserveStarting(identity, { controllerPid }, ownerOptions);
+    if (!reserved?.ok && reserved?.record?.phase === 'complete' && built.prState === 'OPEN') {
+      reserved = await owner.reserveReopened(identity, {
+        generation: reserved.record.generation,
+        expectedReceiptId: reserved.record.terminalReceiptId,
+        controllerPid,
+        providerEvidence: { state: built.prState },
+      }, ownerOptions);
+    }
+    if (!reserved?.ok || !reserved.record) {
+      await built.close?.();
+      return {
+        success: true,
+        started: false,
+        passes: 0,
+        stopped: false,
+        reason: reserved?.reason || 'authority-unavailable',
+      };
+    }
+    generation = reserved.record.generation;
+    reservedHere = true;
+  }
+  if (!await launchGateComplete(owner, ownerOptions)) {
+    if (reservedHere) {
+      await owner.abortStarting(identity, { generation, controllerPid }, ownerOptions);
+    }
+    await built.close?.();
+    return {
+      success: true, started: false, passes: 0, stopped: false,
+      reason: 'migration-gate-incomplete',
+    };
+  }
   const loop = deps.watchLoop || watchLoop;
   // Injected signal (tests) suppresses real process handlers; otherwise wire them.
   const wired = deps.signal ? { signal: deps.signal, cleanup: () => {} } : wireSignals();
   let result;
   try {
     result = await loop({
-      dir,
-      gather,
-      enrich,
+      ...built,
+      repo: identity.repo,
+      pr: identity.pr,
+      generation,
+      controllerPid,
+      pid: process.pid,
+      owner,
+      ownerOptions,
       now: deps.now,
       emit: deps.emit,
       sleep: deps.sleep,
@@ -371,12 +640,10 @@ async function handleWatch(args, projectRoot, deps = {}) {
       maxPasses: deps.maxPasses,
       lockOpts: deps.lockOpts,
       signal: wired.signal,
-      watcherRunning: deps.watcherRunning,
-      writePid: deps.writePid,
-      removePid: deps.removePid,
     });
   } finally {
     wired.cleanup();
+    await built.close?.();
   }
 
   return {
@@ -402,7 +669,12 @@ async function handleWatch(args, projectRoot, deps = {}) {
  * @returns {Promise<object>} result envelope.
  */
 async function handleDaemon(projectRoot, deps = {}) {
-  const res = await reconcileExecutor.runDaemon(projectRoot, { ...deps });
+  const res = await reconcileExecutor.runDaemon(projectRoot, {
+    ...deps,
+    ...(deps.githubContext?.bound ? {
+      runGh: args => deps.githubContext.runGh(args, { cwd: projectRoot, timeout: 30000 }),
+    } : {}),
+  });
   if (!res.ok) {
     // A live foreign daemon owns the lease — this invocation is a clean no-op.
     return { success: true, started: false, reason: res.reason || 'foreign-lease' };
@@ -410,6 +682,78 @@ async function handleDaemon(projectRoot, deps = {}) {
   return { success: true, started: true };
 }
 
+async function collectConvergenceEvidence({ args, pr, projectRoot, context, adapter, deps }) {
+  const built = await buildMonitorContext(pr, projectRoot, {
+    ...deps,
+    adapter,
+    buildContext: async () => context,
+    forceAuthority: true,
+  });
+  if (built.error) throw new Error(built.error);
+  try {
+    const polled = await (deps.pollEvents || pollEvents)({
+      ...built,
+      since: parseSince(args),
+      now: deps.now,
+      isOwnerRunning: async () => false,
+    });
+    const current = await adapter.readState(pr);
+    const exactHead = typeof current?.headSha === 'string' && /^[0-9a-f]{40}$/i.test(current.headSha)
+      ? current.headSha.toLowerCase()
+      : null;
+    const expectedHead = typeof context.headSha === 'string' && /^[0-9a-f]{40}$/i.test(context.headSha)
+      ? context.headSha.toLowerCase()
+      : null;
+    if (!exactHead || exactHead !== expectedHead) {
+      throw new Error('PR head changed after the shepherd pass; rerun convergence on the current head');
+    }
+    // The inline pass is FORCED here precisely because this evidence gates a
+    // MERGE_READY handoff. When the migration gate is quarantined/conflicting or
+    // the authority is unreadable, pollEvents deliberately suppresses that pass and
+    // reports `ranPass: false`; the journal deltas it still returns are stale by
+    // construction. Treating them as convergence evidence would hand off a merge
+    // that was never authoritatively converged, so fail closed with the reason.
+    if (polled.ranPass !== true) {
+      throw new Error(`the authoritative convergence pass did not run (${
+        polled.migrationGateIncomplete === true
+          ? 'watcher migration gate incomplete'
+          : (polled.authorityUnavailable === true ? 'watcher authority unavailable' : 'pass suppressed')
+      })`);
+    }
+    return {
+      deltas: Array.isArray(polled.events) ? polled.events : [],
+      deltaOverflow: polled.overflow === true,
+      receiptIds: Array.isArray(polled.receiptIds) ? polled.receiptIds : [],
+      continuationPending: polled.continuationPending === true,
+      ...(polled.terminalReceiptId ? { terminalReceiptId: polled.terminalReceiptId } : {}),
+      exactHead,
+    };
+  } finally {
+    await built.close?.();
+  }
+}
+
+function convergenceHandoff(state, pr, evidence) {
+  if (state === 'MERGE_READY') {
+    return {
+      next: 'merge',
+      command: `forge merge --auto ${pr} --expect-head ${evidence.exactHead || '<exact-head>'} --issue <issue-id>`,
+      humanApprovalRequired: true,
+    };
+  }
+  if (state === 'MERGED') {
+    return {
+      next: 'verify',
+      command: 'forge verify',
+      terminalReceiptId: evidence.terminalReceiptId || null,
+    };
+  }
+  if (state === 'NEEDS_REVIEW') {
+    return { next: 'review', command: 'forge review', resolvesThreads: false };
+  }
+  return null;
+}
+
 /**
  * Command handler.
  *
@@ -441,8 +785,8 @@ async function handler(args, _flags, projectRoot, deps = {}) {
     return { success: false, error: 'Usage: forge shepherd <pr> [--auto-rebase] [--bundle --json] [--pull --json]' };
   }
 
-  const gh = deps.gh || ((cmd, a) => execFileSync(cmd, a, { encoding: 'utf8', timeout: 30000, windowsHide: true }));
-  const git = deps.git || gh;
+  const gh = githubRunner(deps, projectRoot);
+  const git = deps.git || defaultGhRunner;
   const buildContext = deps.buildContext || defaultBuildContext;
   const runPass = deps.runPass || runShepherdPass;
   const gatherBundle = deps.gatherBundle || gatherPrBundle;
@@ -455,7 +799,11 @@ async function handler(args, _flags, projectRoot, deps = {}) {
 
   const ctx = await buildContext({ pr, gh, git, projectRoot });
 
-  const adapter = deps.adapter || new PrStateAdapter({ gh, git });
+  const adapter = deps.adapter || new PrStateAdapter({
+    gh,
+    git,
+    repository: `${ctx.owner}/${ctx.repo}`,
+  });
   const validation = validatePrStateAdapter(adapter);
   if (!validation.valid) {
     return { success: false, error: `Invalid pr-state adapter: ${validation.errors.join('; ')}` };
@@ -488,39 +836,206 @@ async function handler(args, _flags, projectRoot, deps = {}) {
     return { success: true, bundle, output: JSON.stringify(bundle, null, 2) };
   }
 
+  const runPreflight = deps.runLocalPreflight || runLocalReviewPreflight;
+  const preflightHead = ctx.headSha;
+  const cleanTree = isWorkingTreeClean(git);
+  let localPreflight;
+  try {
+    localPreflight = await runPreflight({
+      projectRoot: projectRoot || process.cwd(),
+      base: ctx.base,
+      baseRef: ctx.baseRef,
+      pr: String(pr),
+      expectedHead: ctx.headSha,
+      localHead: ctx.localHead,
+      cleanTree,
+    });
+  } catch (error) {
+    localPreflight = {
+      status: 'FAIL',
+      blocking: true,
+      providers: {},
+      findings: [{ provider: 'local-preflight', detail: error?.message || String(error) }],
+    };
+  }
+
+  if (localPreflight.blocking !== true) {
+    let postPreflightHead = null;
+    try {
+      const candidate = git('git', ['rev-parse', 'HEAD']).trim();
+      if (/^[0-9a-f]{40}$/i.test(candidate)) postPreflightHead = candidate.toLowerCase();
+    } catch {
+      /* unreadable mutable checkout fails the fence below */
+    }
+    const expectedLocalHead = typeof ctx.localHead === 'string' ? ctx.localHead.toLowerCase() : null;
+    if (!postPreflightHead || postPreflightHead !== expectedLocalHead || !isWorkingTreeClean(git)) {
+      localPreflight = {
+        ...localPreflight,
+        status: 'INCOMPLETE',
+        blocking: true,
+        findings: [
+          ...(Array.isArray(localPreflight.findings) ? localPreflight.findings : []),
+          { provider: 'local-preflight', detail: 'Local checkout changed during local review; rerun on the exact clean PR head.' },
+        ],
+      };
+    }
+  }
+
   const result = await runPass({
     ...ctx,
     adapter,
     autoRebase,
-    cleanTree: autoRebase ? isWorkingTreeClean(git) : false,
+    cleanTree: autoRebase ? cleanTree : false,
     rerunBudget: deps.rerunBudget || DEFAULT_RERUN_BUDGET,
     rerunsUsed: deps.rerunsUsed || 0,
+    dryRun: localPreflight.blocking === true,
   });
 
-  // Surface the pass outcome so the monitor is legible when run interactively or
-  // tailed by a scheduler (the bounded state machine is otherwise silent).
-  const passActions = Array.isArray(result.actions) ? result.actions : [];
-  const reasonSuffix = result.reason ? ` — ${result.reason}` : '';
-  process.stdout.write(`Shepherd pass — PR #${pr}: ${result.state}${reasonSuffix}\n`);
-  for (const action of passActions) {
-    process.stdout.write(`  • ${formatAction(action)}\n`);
+  const collectEvidence = deps.collectConvergenceEvidence || collectConvergenceEvidence;
+  let evidence;
+  try {
+    const evidenceContext = result.expectedHead ? { ...ctx, headSha: result.expectedHead } : ctx;
+    evidence = await collectEvidence({ args, pr, projectRoot, context: evidenceContext, adapter, deps });
+  } catch (error) {
+    const reason = `Durable convergence evidence is unavailable: ${error.message}`;
+    writePassSummary(pr, 'INCOMPLETE', reason, result.actions);
+    return {
+      success: false,
+      state: 'INCOMPLETE',
+      remoteState: result.state,
+      reason,
+      actions: result.actions || [],
+      localPreflight,
+      deltas: [],
+      deltaOverflow: false,
+      receiptIds: [],
+    };
   }
-  if (!passActions.length) {
-    process.stdout.write('  • no actions this pass\n');
+
+  const normalizedPreflightHead = typeof preflightHead === 'string' ? preflightHead.toLowerCase() : null;
+  const normalizedResultHead = typeof result.expectedHead === 'string' ? result.expectedHead.toLowerCase() : null;
+  if (localPreflight.blocking !== true && result.state === 'MERGE_READY'
+    && normalizedPreflightHead && normalizedResultHead && normalizedResultHead !== normalizedPreflightHead) {
+    return {
+      success: false,
+      state: 'INCOMPLETE',
+      remoteState: result.state,
+      reason: 'Local preflight head changed; rerun convergence on the current head',
+      actions: result.actions || [],
+      localPreflight,
+      deltas: evidence.deltas,
+      deltaOverflow: evidence.deltaOverflow,
+      receiptIds: evidence.receiptIds,
+    };
   }
 
+  let confirmedResult = result;
+  if (localPreflight.blocking !== true && result.state === 'MERGE_READY'
+    && evidence.continuationPending !== true) {
+    const confirmation = await runPass({
+      ...ctx,
+      adapter,
+      autoRebase: false,
+      cleanTree: false,
+      rerunBudget: deps.rerunBudget || DEFAULT_RERUN_BUDGET,
+      rerunsUsed: deps.rerunsUsed || 0,
+      dryRun: true,
+    });
+    confirmedResult = {
+      ...confirmation,
+      actions: [...(result.actions || []), ...(confirmation.actions || [])],
+    };
+    const confirmedHead = typeof confirmedResult.expectedHead === 'string'
+      ? confirmedResult.expectedHead.toLowerCase()
+      : null;
+    if (confirmedResult.state === 'MERGE_READY' && confirmedHead !== evidence.exactHead) {
+      return {
+        success: false,
+        state: 'INCOMPLETE',
+        remoteState: confirmedResult.state,
+        reason: 'PR head changed while confirming mutable merge-readiness evidence; rerun convergence on the current head',
+        actions: confirmedResult.actions,
+        localPreflight,
+        deltas: evidence.deltas,
+        deltaOverflow: evidence.deltaOverflow,
+        receiptIds: evidence.receiptIds,
+      };
+    }
+    if (confirmedResult.state !== result.state) {
+      try {
+        const evidenceContext = confirmedResult.expectedHead
+          ? { ...ctx, headSha: confirmedResult.expectedHead }
+          : ctx;
+        evidence = await collectEvidence({ args, pr, projectRoot, context: evidenceContext, adapter, deps });
+      } catch (error) {
+        return {
+          success: false,
+          state: 'INCOMPLETE',
+          remoteState: confirmedResult.state,
+          reason: `Confirmed convergence evidence is unavailable: ${error.message}`,
+          actions: confirmedResult.actions,
+          localPreflight,
+          deltas: evidence.deltas,
+          deltaOverflow: evidence.deltaOverflow,
+          receiptIds: evidence.receiptIds,
+        };
+      }
+      if (confirmedResult.state === 'MERGED' && !evidence.terminalReceiptId) {
+        return {
+          success: false,
+          state: 'INCOMPLETE',
+          remoteState: confirmedResult.state,
+          reason: 'Confirmed merged state has no durable terminal receipt',
+          actions: confirmedResult.actions,
+          localPreflight,
+          deltas: evidence.deltas,
+          deltaOverflow: evidence.deltaOverflow,
+          receiptIds: evidence.receiptIds,
+        };
+      }
+    }
+  }
+
+  const effectiveState = evidence.continuationPending === true
+    ? 'PENDING'
+    : localPreflight.blocking === true && confirmedResult.state === 'MERGE_READY'
+      ? (localPreflight.status === 'INCOMPLETE' ? 'INCOMPLETE' : 'PENDING')
+      : confirmedResult.state;
+  const effectiveReason = effectiveState !== confirmedResult.state
+    ? (evidence.continuationPending === true
+      ? 'Durable convergence work remains; run another bounded shepherd pass.'
+      : effectiveState === 'INCOMPLETE'
+        ? 'Local review preflight is incomplete; merge readiness is not established.'
+        : 'Local review preflight is blocking merge readiness.')
+    : confirmedResult.reason;
+
+  // Surface the pass outcome so the monitor is legible when run interactively or
+  // tailed by a scheduler (the bounded state machine is otherwise silent).
+  writePassSummary(pr, effectiveState, effectiveReason, confirmedResult.actions);
+
   return {
-    success: result.state !== 'HARD_STOP',
-    state: result.state,
-    reason: result.reason,
-    actions: result.actions || [],
-    ...(result.authClass ? { authClass: result.authClass } : {}),
-    ...(result.retryAfter ? { retryAfter: result.retryAfter } : {}),
+    success: effectiveState !== 'HARD_STOP' && effectiveState !== 'INCOMPLETE',
+    state: effectiveState,
+    ...(effectiveState !== confirmedResult.state ? { remoteState: confirmedResult.state } : {}),
+    reason: effectiveReason,
+    actions: confirmedResult.actions || [],
+    localPreflight,
+    deltas: evidence.deltas,
+    deltaOverflow: evidence.deltaOverflow,
+    receiptIds: evidence.receiptIds,
+    continuationPending: evidence.continuationPending === true,
+    ...(evidence.terminalReceiptId ? { terminalReceiptId: evidence.terminalReceiptId } : {}),
+    ...(convergenceHandoff(effectiveState, pr, evidence)
+      ? { handoff: convergenceHandoff(effectiveState, pr, evidence) }
+      : {}),
+    ...(confirmedResult.authClass ? { authClass: confirmedResult.authClass } : {}),
+    ...(confirmedResult.retryAfter ? { retryAfter: confirmedResult.retryAfter } : {}),
   };
 }
 
 module.exports = {
   name: 'shepherd',
+  githubAuth: true,
   description: 'Run one bounded monitor pass over a PR (rerun flaky checks, escalate, hand off — never merges)',
   usage: 'Usage: forge shepherd <pr> [--auto-rebase] [--bundle --json] [--pull --json] | forge shepherd events <pr> --since <seq> [--json] | forge shepherd watch <pr> | forge shepherd watch --adopt',
   handler,
@@ -529,6 +1044,9 @@ module.exports = {
   buildMonitorContext,
   makeCheckFailureEnricher,
   parseSince,
+  collectConvergenceEvidence,
+  convergenceHandoff,
   defaultBuildContext,
+  defaultListOpenPrs,
   isWorkingTreeClean,
 };