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

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

@@ -1,570 +1,1177 @@
 'use strict';
 
 /**
- * The IMPURE half of the autonomous shepherd reconciler (W-S4b, design §3/§4).
- *
- * W-S4a shipped the pure `reconcile(desired, observed, now)` and the `tick()`
- * 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 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. 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.
- *
- * SAFETY INVARIANTS (guarded by tests):
- *   - Orphan reaping NEVER `process.kill`s on a PID match alone. It re-verifies at
- *     kill time: the pid must be alive AND the journal start-time marker for that
- *     PR must still exist AND equal the watcher entry's `startedAt`. A null/legacy
- *     startedAt, or an absent/mismatched marker, means "do not kill" (PID reuse
- *     fail-safe) — the stale entry is dropped silently.
- *   - The singleton is arbitrated by the O_EXCL shepherd lease: a daemon that loses
- *     `acquire` exits immediately and spawns nothing.
- *   - Watcher launch classification branches on CAPABILITY presence
- *     (`ctx.harness.hasBgShell`), NEVER on harness name; uncertain → detached.
+ * Side-effecting half of owner-row shepherd reconciliation. The filesystem
+ * lease elects one repository daemon; all per-PR lifecycle changes go through
+ * the narrow watch-owner APIs.
  *
  * @module pr-monitor/reconcile-executor
  */
 
 const fs = require('node:fs');
 const path = require('node:path');
+const crypto = require('node:crypto');
 const { spawn } = require('node:child_process');
 
 const shepherdLease = require('./shepherd-lease');
-const journal = require('./journal');
+const watchOwner = require('./watch-owner');
 const { reconcile: defaultReconcile } = require('./reconcile');
 const { tick: defaultTick } = require('./reconcile-tick');
-const { startPrWatcherDetached, forgeBin } = require('./watch-lifecycle');
+const { startPrWatcherDetached, forgeArgs, githubWorkerEnvironment } = require('./watch-lifecycle');
+const { privacySafeIdentity } = require('./flow-monitor');
+const { processIdentityAlive, defaultPidStartedAt } = require('./process-identity');
 const brokerMod = require('../kernel/broker');
+const { secureExecFileSync } = require('../shell-utils');
 
-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'];
+const MAX_OPEN_PRS = 1000;
+const MAX_ACTIONS_PER_PASS = 128;
+const MAX_LEGACY_SNAPSHOT_BYTES = 4 * 1024 * 1024;
+const MAX_MIGRATION_ATTEMPTS = 3;
+const MAX_MONITOR_ID_LENGTH = 128;
+const OWNER_HEARTBEAT_STALE_MS = 4 * 60_000;
 
 function normalizeRepository(value) {
-	return typeof value === 'string' && CANONICAL_REPOSITORY.test(value.trim())
-		? value.trim().toLowerCase()
-		: null;
+	if (typeof value !== 'string') return null;
+	const normalized = value.trim().toLowerCase();
+	return CANONICAL_REPOSITORY.test(normalized) ? normalized : null;
+}
+
+function legacyMonitorId(repo, pr) {
+	const raw = privacySafeIdentity(`pr:${privacySafeIdentity(repo)}:${pr}`);
+	return raw.length <= MAX_MONITOR_ID_LENGTH
+		? raw
+		: `pr:${crypto.createHash('sha256').update(raw).digest('hex')}`;
 }
 
-/** 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}`);
+		const raw = runGh(['repo', 'view', '--json', 'nameWithOwner,parent']);
+		const value = typeof raw === 'string' ? JSON.parse(raw) : raw;
+		return normalizeRepository(value?.parent?.nameWithOwner || value?.nameWithOwner);
 	} 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 githubRunner(opts = {}) {
+	return opts.runGh || ((args) => secureExecFileSync('gh', args, {
+		cwd: opts.projectRoot || process.cwd(), encoding: 'utf8', timeout: GH_COMMAND_TIMEOUT_MS, windowsHide: true,
+	}));
+}
+
 function writeDaemonDiagnostic(gitCommonDir, entry, opts = {}) {
+	if (!gitCommonDir) return false;
 	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`);
+		const dir = path.join(gitCommonDir, 'forge');
+		fs.mkdirSync(dir, { recursive: true });
+		fs.appendFileSync(path.join(dir, 'shepherd-daemon.ndjson'), `${JSON.stringify(entry)}\n`, {
+			encoding: 'utf8', mode: 0o600,
+		});
 		return true;
-	} catch {
+	} catch (error) {
+		try { opts.onDiagnosticError?.(error); } catch { /* diagnostics remain best effort */ }
 		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) } : {}),
+		at: new Date((opts.now || (() => Date.now()))()).toISOString(),
+		...(detail ? { detail: String(detail?.message || detail).slice(0, 500) } : {}),
 	};
 	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) {
-	if (typeof entry === 'number') return { pr: entry, repo: null, pid: null, startedAt: null };
-	return {
-		pr: entry.pr,
-		repo: entry.repo ?? null,
-		pid: entry.pid ?? null,
-		startedAt: entry.startedAt ?? null,
-	};
-}
-
-/** File that records a watcher's spawn-time ISO stamp for kill-time re-verification. */
-function claimPath(dir) {
-	return path.join(dir, 'watch.startedat');
-}
-
-/**
- * Write the start-time marker for `(repo, pr)` into its journal dir. This is the
- * 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, gitCommonDir) {
-	if (repo == null || pr == null || startedAt == null) return;
-	try {
-		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) */
-	}
-}
-
-/** Read the start-time marker for `(repo, pr)`, or null when absent/unreadable. */
-function readClaimMarker(projectRoot, repo, pr, gitCommonDir) {
-	if (repo == null || pr == null) return null;
-	try {
-		const dir = journal.journalDir({ root: projectRoot, gitCommonDir, repo, pr });
-		return fs.readFileSync(claimPath(dir), 'utf8').trim();
-	} catch {
-		return null;
-	}
-}
-
-/**
- * Remove the start-time marker for `(repo, pr)` when its watcher is stopped/reaped, so
- * 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, gitCommonDir) {
-	if (repo == null || pr == null) return;
-	try {
-		const dir = journal.journalDir({ root: projectRoot, gitCommonDir, repo, pr });
-		fs.rmSync(claimPath(dir), { force: true });
-	} catch {
-		/* best-effort marker cleanup */
-	}
+		(opts.writeDaemonDiagnostic || writeDaemonDiagnostic)(gitCommonDir, entry, opts);
+	} catch { /* diagnostics never affect daemon lifecycle */ }
 }
 
-/**
- * Gather the DESIRED open-PR set: GitHub's open PRs (`gh pr list`) enriched with
- * kernel linkage (issue/worktree/journal) where a `kernel_pr` row already exists.
- * A hand-opened PR with no kernel row is still included (issue_id/worktree_id
- * null) so the reconciler self-registers it — zero user invocation. External
- * fields (branch names) are stored raw and NEVER evaluated.
- */
 async function gatherDesired(gitCommonDir, opts = {}) {
-	const runGh = opts.runGh || ((args) => require('node:child_process').execFileSync('gh', args, {
-		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;
-	// 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 runGh = githubRunner(opts);
+	const suppliedRepo = normalizeRepository(opts.repo);
 	const repo = suppliedRepo || resolveCanonicalRepository(runGh);
+	if (!repo) return { openPrs: [], gitCommonDir, listingOk: false, repositoryOk: false };
 
-	let ghPrs = [];
-	// `listingOk` distinguishes "GitHub says zero open PRs" from "the gh call failed"
-	// (network/auth/rate-limit). A FAILED listing must be a no-op upstream, never a
-	// teardown of every watcher+row — the caller skips the reconcile pass when false.
-	let listingOk = true;
+	let ghPrs;
 	try {
-		// `--limit 1000` overrides gh's default 30-result cap so a repo with >30 open
-		// PRs is fully enumerated (otherwise the tail would go unwatched or get retired).
-		const raw = runGh(['pr', 'list', '--state', 'open', '--limit', '1000', '--json', 'number,headRefName,headRefOid']);
-		const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
-		if (Array.isArray(parsed)) ghPrs = parsed;
+		const raw = runGh(['pr', 'list', '--repo', repo, '--state', 'open', '--limit', String(MAX_OPEN_PRS + 1), '--json', 'number,headRefName,headRefOid']);
+		ghPrs = typeof raw === 'string' ? JSON.parse(raw) : raw;
+		if (!Array.isArray(ghPrs)) throw new TypeError('PR listing is not an array');
+		if (ghPrs.length > MAX_OPEN_PRS) throw new RangeError('PR listing exceeds safe reconciliation bound');
 	} catch {
-		ghPrs = [];
-		listingOk = false;
+		return { openPrs: [], gitCommonDir, listingOk: false, repositoryOk: true, repo };
 	}
 
-	if (!repo) return { openPrs: [], gitCommonDir, listingOk: false, repositoryOk: false };
-
 	let prRows = [];
 	try {
-		if (broker) prRows = await broker.listOpenPrs(gitCommonDir);
+		if (opts.broker) prRows = await opts.broker.listOpenPrs(gitCommonDir);
 	} catch {
-		/* kernel unavailable → treat as no linkage; the GitHub-driven desired set still stands */
-	}
-	// 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 };
+		return { openPrs: [], gitCommonDir, listingOk: false, repositoryOk: true, repo };
 	}
 	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);
+	for (const row of Array.isArray(prRows) ? prRows : []) {
+		const rowRepo = normalizeRepository(row?.repo);
+		const number = Number(row?.number);
+		if (rowRepo !== repo || !Number.isSafeInteger(number) || number <= 0) continue;
+		const current = exactRows.get(number);
+		if (current) return { openPrs: [], gitCommonDir, listingOk: false, repositoryOk: false, repo };
+		exactRows.set(number, row);
 	}
-	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 = rowForPr(p);
+	const openPrs = ghPrs.map((item) => {
+		const number = Number(item?.number);
+		const row = exactRows.get(number);
 		return {
-			repo: canonicalRepo || repo,
-			number: p.number,
-			branch: p.headRefName ?? null,
-			headSha: p.headRefOid ?? null,
+			repo,
+			number,
+			branch: item?.headRefName ?? null,
+			headSha: item?.headRefOid ?? null,
 			issueId: row?.issue_id ?? null,
 			worktreeId: row?.worktree_id ?? null,
 			journalPtr: row?.journal_ptr ?? null,
 		};
 	});
-	return { openPrs, gitCommonDir, listingOk };
+	if (openPrs.some(item => !Number.isSafeInteger(item.number) || item.number <= 0)) {
+		return { openPrs: [], gitCommonDir, listingOk: false, repositoryOk: false, repo };
+	}
+	return { openPrs, gitCommonDir, listingOk: true, repositoryOk: true, repo };
 }
 
-/**
- * Gather the OBSERVED state: kernel `kernel_pr` rows, the lease watcher set, and
- * which of those watcher pids are actually alive (probed via `pidAlive`).
- */
-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, gitCommonDir));
-	const now = (opts.now || (() => Date.now()))();
+function ownerOptions(ctx) {
+	const isPidAlive = ctx.ownerOptions?.isPidAlive || ctx.isAlive || shepherdLease.pidAlive;
+	// Both halves of an identity proof must describe the same process. A caller that
+	// supplies its own liveness answer (tests, cached legacy evidence) is answering for
+	// PIDs the built-in /proc probe knows nothing about, so pairing that answer with the
+	// built-in probe would compare a fabricated PID's liveness against a real process's
+	// start time and "prove" reuse. The built-in probe travels with the built-in
+	// liveness check only; otherwise identity stays unprovable.
+	const pidStartedAt = ctx.ownerOptions?.pidStartedAt || ctx.pidStartedAt
+		|| (isPidAlive === shepherdLease.pidAlive ? defaultPidStartedAt : null);
+	return {
+		...(ctx.ownerOptions || {}),
+		...(ctx.driver ? { driver: ctx.driver } : {}),
+		...(ctx.databaseConfig ? { databaseConfig: ctx.databaseConfig } : {}),
+		isPidAlive,
+		pidStartedAt,
+		verifyProviderEvidence: ctx.ownerOptions?.verifyProviderEvidence
+			|| (async (evidence, expected) => expected.states.includes(String(evidence?.state || '').toLowerCase())),
+		verifyTerminalReceipt: ctx.ownerOptions?.verifyTerminalReceipt
+			|| ctx.verifyTerminalReceipt
+			|| (async () => false),
+	};
+}
 
+async function gatherObserved(gitCommonDir, _lock, opts = {}) {
 	let prRows = [];
 	try {
-		if (broker) prRows = await broker.listOpenPrs(gitCommonDir);
+		if (opts.broker) prRows = await opts.broker.listOpenPrs(gitCommonDir);
 	} catch {
-		/* kernel unavailable → observe an empty kernel set; reconcile still converges watchers */
+		return { prRows: [], ownerRows: [], ownerRowsOk: false, migrationGate: null };
 	}
+	const authority = opts.authority || watchOwner;
+	const options = ownerOptions(opts);
+	const listed = await authority.enumerateOwners({}, options);
+	const gate = typeof authority.readMigrationGate === 'function'
+		? await authority.readMigrationGate({}, options)
+		: { ok: false, reason: 'authority_unavailable' };
+	if (!listed?.ok || !Array.isArray(listed.records) || !gate?.ok || !gate.gate) {
+		return {
+			prRows: Array.isArray(prRows) ? prRows : [], ownerRows: [], ownerRowsOk: false,
+			migrationGate: gate?.gate || null,
+		};
+	}
+	const isAlive = options.isPidAlive;
+	const pidStartedAt = options.pidStartedAt;
+	const observedAt = Number((opts.now || (() => Date.now()))());
+	const heartbeatStaleMs = opts.ownerHeartbeatStaleMs ?? OWNER_HEARTBEAT_STALE_MS;
+	const ownerRows = [];
+	for (const record of listed.records) {
+		const next = { ...record };
+		if (record.controllerPid != null) {
+			// The controller itself wrote this row at `updatedAt`, so it was running then.
+			// A process holding the same number that booted afterwards is a different
+			// process: the controller is gone and the PID was reused. Recovery must not
+			// defer to it, and the proof travels with the row so the authority
+			// transaction can accept recovery instead of rejecting on a bare live PID.
+			const controllerState = await processIdentityAlive({
+				pid: record.controllerPid, startedAt: record.updatedAt, isPidAlive: isAlive, pidStartedAt,
+			});
+			next.controllerAlive = controllerState === 'alive';
+			if (controllerState === 'reused') next.controllerPidReuseProven = true;
+		}
+		if (record.watcherPid != null) {
+			// The watcher stamps `heartbeatAt` itself, making it the tightest honest
+			// marker for watcher identity. Blocked legacy rows never beat — the schema
+			// forbids it — so their marker is the legacy `startedAt` the import retained.
+			// Without it a legacy watcher that exited and had its PID inherited reads as
+			// alive forever, recheckLegacyBlocked never fires, and the PR stays unwatched.
+			const watcherMarker = record.phase === 'blocked' ? record.startedAt : record.heartbeatAt;
+			const watcherState = await processIdentityAlive({
+				pid: record.watcherPid, startedAt: watcherMarker, isPidAlive: isAlive, pidStartedAt,
+			});
+			if (watcherState === 'reused') next.watcherPidReuseProven = true;
+			const pidAlive = watcherState === 'alive';
+			const heartbeatRequired = record.phase === 'running'
+				|| record.phase === 'stop_requested'
+				|| record.phase === 'terminal_pending';
+			const heartbeatAt = Date.parse(record.heartbeatAt);
+			const heartbeatFresh = Number.isFinite(heartbeatAt)
+				&& Number.isFinite(observedAt)
+				&& observedAt >= heartbeatAt
+				&& observedAt - heartbeatAt <= heartbeatStaleMs;
+			next.watcherAlive = pidAlive && (!heartbeatRequired || heartbeatFresh);
+		}
+		ownerRows.push(next);
+	}
+	return {
+		prRows: Array.isArray(prRows) ? prRows : [], ownerRows, ownerRowsOk: true,
+		migrationGate: gate.gate,
+	};
+}
 
-	const watchers = (lock && Array.isArray(lock.watchers) ? lock.watchers : []).map(normalizeWatcher);
-	// A pid is "live" ONLY when it is alive AND its journal start-time marker still
-	// equals the entry's startedAt — the SAME check verifiedKill makes at kill time.
-	// A reused PID (alive, but a mismatched/absent marker) must NOT be reported live,
-	// or reconcile would suppress the startWatcher and leave the PR unmonitored.
-	const liveWatcherPids = watchers
-		.filter((w) => {
-			if (w.pid == null || !isAlive(w.pid)) return false;
-			const marker = readClaim(w.repo, w.pr);
-			return marker != null && String(marker) === String(w.startedAt);
-		})
-		.map((w) => ({ pid: w.pid, startedAt: w.startedAt ?? null }));
-
-	const beat = lock ? Date.parse(lock.heartbeatAt) : NaN;
-	const leaseFresh = Number.isFinite(beat) && (now - beat) < STALE_MS;
+function identity(recordOrPr) {
+	return { repo: recordOrPr.repo, pr: Number(recordOrPr.pr ?? recordOrPr.number) };
+}
 
-	return { lease: lock || null, leaseFresh, prRows: Array.isArray(prRows) ? prRows : [], liveWatcherPids };
+function operationInput(record) {
+	return { generation: record.generation, pid: record.watcherPid };
 }
 
-/**
- * Kill a watcher pid ONLY after re-verifying start-time (design risk #4). Returns
- * true iff the kill actually happened. Never kills on a PID match alone.
- */
-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, ctx.gitCommonDir));
-	const claim = readClaim(entry);
-	if (claim == null || String(claim) !== String(entry.startedAt)) return false;
+async function bindSpawned(reservation, pr, s) {
+	if (!reservation?.ok || !reservation.record) return reservation || { ok: false, reason: 'reservation_failed' };
+	const record = reservation.record;
+	let spawned;
 	try {
-		(ctx.kill || process.kill)(entry.pid);
+		spawned = await s.spawnWatcher({
+			prNumber: pr.number,
+			repository: pr.repo,
+			reservation,
+			controllerPid: s.controllerPid,
+			cwd: s.projectRoot,
+			gitCommonDir: s.gitCommonDir,
+			owner: s.authority,
+			ownerOptions: s.options,
+		});
 	} catch {
-		return false;
+		spawned = null;
+	}
+	const pid = Number(spawned?.pid);
+	if (!Number.isSafeInteger(pid) || pid <= 0) {
+		return s.authority.abortStarting(identity(pr), {
+			generation: record.generation, controllerPid: s.controllerPid,
+		}, s.options);
 	}
-	return true;
+	return s.authority.bindRunning(identity(pr), {
+		generation: record.generation, controllerPid: s.controllerPid, pid,
+	}, s.options);
+}
+
+// Re-reads the on-disk legacy evidence for one blocked legacy row and returns the
+// terminal receipt the legacy watcher wrote after the migration snapshot was taken.
+// Ambiguous or unreadable evidence returns null so the caller fails closed.
+async function recoverLegacyTerminalReceipt(owner, s) {
+	let snapshot;
+	try { snapshot = await s.readLegacySnapshot(); } catch { return null; }
+	if (!snapshot || snapshot.corrupt === true) return null;
+	const repo = normalizeRepository(owner?.repo);
+	const pr = Number(owner?.pr);
+	if (!repo || !Number.isSafeInteger(pr) || pr <= 0) return null;
+	const receipts = new Set();
+	for (const entry of Array.isArray(snapshot.entries) ? snapshot.entries : []) {
+		if (normalizeRepository(entry?.repo) !== repo || Number(entry?.pr) !== pr) continue;
+		if (entry?.terminalReceiptId) receipts.add(String(entry.terminalReceiptId));
+	}
+	return receipts.size === 1 ? [...receipts][0] : null;
 }
 
-/**
- * Per-action-type handlers, keyed by `action.type`. Extracted from `execute` so
- * each is small and independently testable and the dispatcher stays a flat loop
- * (keeps `execute`'s cognitive complexity under the SonarCloud gate). Each handler
- * mutates the shared `s` state (`s.watchers` is reassigned by stop/reap) and the
- * behavior is identical to the former if/else-if chain.
- */
 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, 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
-		// failed. Do NOT record a {pid:null} entry: gatherObserved never counts it live, so
-		// each interval would re-emit startWatcher and append another null entry forever.
-		if (pid == null) return;
-		const entry = { pr: action.pr.number, repo, pid, startedAt };
-		s.watchers.push(entry);
-		s.writeClaim(entry);
+	async reserveWatcher(action, s) {
+		const result = await s.authority.reserveStarting(identity(action.pr), {
+			controllerPid: s.controllerPid,
+		}, s.options);
+		return bindSpawned(result, action.pr, s);
+	},
+	async recoverStarting(action, s) {
+		const result = await s.authority.recoverDeadStarting(identity(action.owner), {
+			generation: action.owner.generation,
+			controllerPid: action.owner.controllerPid,
+			recoveryControllerPid: s.controllerPid,
+			pidReuseProven: action.owner.controllerPidReuseProven === true,
+		}, s.options);
+		return bindSpawned(result, action.pr || { repo: action.owner.repo, number: action.owner.pr }, s);
 	},
-	stopWatcher(action, s) {
-		for (const entry of s.watchers.filter((w) => w.pr === action.pr.number)) {
-			verifiedKill(entry, s.ctx);
-			s.removeClaim(entry); // clear the start-time marker so a reused PID can't match it later
+	async retryStarting(action, s) {
+		const released = await s.authority.abortStarting(identity(action.owner), {
+			generation: action.owner.generation, controllerPid: s.controllerPid,
+		}, s.options);
+		if (!released?.ok || released.changed !== true) {
+			return released || { ok: false, reason: 'starting_release_failed' };
 		}
-		s.watchers = s.watchers.filter((w) => w.pr !== action.pr.number);
+		const pr = action.pr || { repo: action.owner.repo, number: action.owner.pr };
+		const reservation = await s.authority.reserveStarting(identity(pr), {
+			controllerPid: s.controllerPid,
+		}, s.options);
+		return bindSpawned(reservation, pr, s);
 	},
-	reapOrphan(action, s) {
-		const entry = s.watchers.find((w) => w.pid === action.pid && w.startedAt === action.startedAt);
-		verifiedKill(entry, s.ctx);
-		if (entry) s.removeClaim(entry);
-		s.watchers = s.watchers.filter((w) => !(w.pid === action.pid && w.startedAt === action.startedAt));
+	async recoverWatcher(action, s) {
+		const result = await s.authority.recoverDeadWatcher(identity(action.owner), {
+			...operationInput(action.owner),
+			recoveryControllerPid: s.controllerPid,
+			pidReuseProven: action.owner.watcherPidReuseProven === true,
+			providerEvidence: { state: action.providerState },
+		}, s.options);
+		return bindSpawned(result, action.pr || { repo: action.owner.repo, number: action.owner.pr }, s);
+	},
+	async reopenWatcher(action, s) {
+		const result = await s.authority.reserveReopened(identity(action.owner), {
+			generation: action.owner.generation,
+			expectedReceiptId: action.owner.terminalReceiptId,
+			controllerPid: s.controllerPid,
+			providerEvidence: { state: 'open' },
+		}, s.options);
+		return bindSpawned(result, action.pr, s);
+	},
+	async requestStop(action, s) {
+		return s.authority.requestStop(identity(action.owner), operationInput(action.owner), s.options);
+	},
+	async completeTerminal(action, s) {
+		return s.authority.completeTerminal(identity(action.owner), {
+			...operationInput(action.owner),
+			pidReuseProven: action.owner.watcherPidReuseProven === true,
+			terminalReceiptId: action.owner.terminalReceiptId,
+		}, s.options);
+	},
+	async recheckLegacyBlocked(action, s) {
+		const terminal = action.providerState === 'terminal';
+		// A legacy watcher imported while its PR was still open carries no terminal
+		// receipt. If the PR later reaches a terminal state and the legacy process
+		// exits, releasing the row plainly drops the terminal receipt on the floor:
+		// the PR is already absent from the open-PR listing, so no replacement watcher
+		// will ever record it. Recover the receipt the exiting legacy watcher wrote and
+		// complete instead; fail closed (leave the row blocked for the next pass) when
+		// no single unambiguous receipt can be recovered.
+		let terminalReceiptId = terminal ? action.owner.terminalReceiptId || null : null;
+		if (terminal && !terminalReceiptId) {
+			terminalReceiptId = await recoverLegacyTerminalReceipt(action.owner, s);
+			if (!terminalReceiptId) return { ok: false, reason: 'terminal_receipt_unrecovered' };
+		}
+		const complete = terminal && Boolean(terminalReceiptId);
+		return s.authority.recheckLegacyBlocked(identity(action.owner), {
+			generation: action.owner.generation,
+			legacyEvidenceHash: action.owner.legacyEvidenceHash,
+			pid: action.owner.watcherPid,
+			pidReuseProven: action.owner.watcherPidReuseProven === true,
+			action: complete ? 'complete' : 'release',
+			...(complete ? { terminalReceiptId } : {}),
+		}, s.options);
 	},
 	async upsertPrRow(action, s) {
+		if (!s.broker) return { ok: false, reason: 'kernel_unavailable' };
 		try {
-			if (!s.broker) return true;
 			const result = await s.broker.upsertPr(action.row);
-			return result !== false && !(result && result.ok === false);
+			return result === false || result?.ok === false
+				? { ok: false, reason: 'kernel_write_failed' }
+				: { ok: true, changed: true };
 		} catch {
-			/* derived reconcile state — a failed upsert retries on the next converge */
-			return false;
+			return { ok: false, reason: 'kernel_write_failed' };
 		}
 	},
 	async retire(action, s) {
+		if (!s.broker) return { ok: false, reason: 'kernel_unavailable' };
 		try {
-			if (s.broker) await s.broker.retirePr(
+			await s.broker.retirePr(
 				{ git_common_dir: s.gitCommonDir, repo: action.pr.repo, number: action.pr.number },
 				{ state: 'closed', retired_at: new Date(s.now()).toISOString() },
 			);
+			return { ok: true, changed: true };
 		} catch {
-			/* retried on the next converge */
+			return { ok: false, reason: 'kernel_write_failed' };
 		}
 	},
 };
 
-/**
- * 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).
- */
 async function execute(actions, ctx = {}) {
+	if (!Array.isArray(actions)) {
+		const error = new TypeError('Reconcile actions must be an array');
+		error.code = 'INVALID_ACTIONS';
+		throw error;
+	}
+	const authority = ctx.authority || watchOwner;
 	const s = {
-		broker: ctx.broker || null, // live kernel handle threaded by the daemon; never the module namespace
+		authority,
+		options: ownerOptions(ctx),
+		controllerPid: Number.isSafeInteger(ctx.controllerPid) && ctx.controllerPid > 0 ? ctx.controllerPid : process.pid,
 		spawnWatcher: ctx.spawnWatcher || startPrWatcherDetached,
-		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,
+		broker: ctx.broker || null,
 		projectRoot: ctx.projectRoot,
 		gitCommonDir: ctx.gitCommonDir,
-		watchers: Array.isArray(ctx.watchers) ? ctx.watchers.map(normalizeWatcher) : [],
-		ctx, // verifiedKill reads isAlive/readClaim/kill/projectRoot off the original ctx
+		readLegacySnapshot: ctx.readLegacySnapshot || (() => defaultReadLegacySnapshot(ctx.projectRoot, ctx)),
+		now: ctx.now || (() => Date.now()),
 	};
-
-	for (const action of (Array.isArray(actions) ? actions : [])) {
-		const handler = ACTION_HANDLERS[action && action.type];
-		if (handler && (await handler(action, s)) === false) break;
+	let changed = false;
+	const results = [];
+	for (const action of actions.slice(0, MAX_ACTIONS_PER_PASS)) {
+		const handler = ACTION_HANDLERS[action?.type];
+		if (!handler) continue;
+		const result = await handler(action, s);
+		results.push({ type: action.type, result });
+		changed ||= result?.changed === true;
+		if (result?.ok === false && (action.type === 'upsertPrRow' || result.reason === 'authority_unavailable')) break;
 	}
-	return s.watchers;
+	return { ok: results.every(item => item.result?.ok !== false), changed, results };
+}
+
+function activeOwnerCount(records) {
+	return records.filter(record => record.phase !== 'complete').length;
 }
 
-/**
- * One converge pass: gather → reconcile → execute → publish watchers. Used by the
- * daemon loop and directly unit-testable with injected gather/reconcile/execute.
- * Returns `{ actions, watchers, desiredCount }`.
- */
 async function convergeOnce(projectRoot, opts = {}) {
 	const gitCommonDir = opts.gitCommonDir;
-	const reconcile = opts.reconcile || defaultReconcile;
-	const now = opts.now || (() => Date.now());
-	const lock = opts.lock !== undefined ? opts.lock : null; // daemon threads the live lock in; default null
-
 	const desired = opts.gatherDesired
 		? await opts.gatherDesired()
 		: await gatherDesired(gitCommonDir, { ...opts, projectRoot });
-
-	// A FAILED gh listing (listingOk === false) is a transient outage, not "zero open
-	// PRs". Skipping the reconcile+execute pass entirely makes it a true no-op — no
-	// observe, no retire/stopWatcher teardown of every row+watcher. desiredCount is
-	// left non-zero (null) so the daemon does NOT read it as "no PRs → self-retire".
-	if (desired && desired.listingOk === false) {
-		const keep = (lock && Array.isArray(lock.watchers)) ? lock.watchers : (opts.watchers || []);
-		return { actions: [], watchers: keep, desiredCount: null, listingOk: false };
+	if (!desired || desired.listingOk === false || desired.repositoryOk === false) {
+		return { actions: [], desiredCount: null, authorityOk: false, activeOwnerCount: null, listingOk: false };
 	}
-
 	const observed = opts.gatherObserved
 		? await opts.gatherObserved()
-		: await gatherObserved(gitCommonDir, lock, { ...opts, now, projectRoot });
-
-	const { actions } = reconcile(desired, observed, now());
-	const seedWatchers = observed.lease && Array.isArray(observed.lease.watchers)
-		? observed.lease.watchers
-		: (opts.watchers || []);
-	const watchers = await execute(actions, {
-		...opts,
-		projectRoot,
-		gitCommonDir,
-		watchers: seedWatchers,
-		now,
+		: await gatherObserved(gitCommonDir, null, { ...opts, projectRoot });
+	const controllerPid = Number.isSafeInteger(opts.controllerPid) && opts.controllerPid > 0
+		? opts.controllerPid
+		: process.pid;
+	const decision = (opts.reconcile || defaultReconcile)(
+		{ ...desired, controllerPid }, observed, (opts.now || (() => Date.now()))(),
+	);
+	const actions = Array.isArray(decision?.actions) ? decision.actions : [];
+	const execution = await (opts.execute || execute)(actions, { ...opts, projectRoot, gitCommonDir });
+
+	const authority = opts.authority || watchOwner;
+	const listed = await authority.enumerateOwners({}, ownerOptions(opts));
+	const authorityOk = listed?.ok === true && Array.isArray(listed.records);
+	return {
+		actions,
+		desiredCount: desired.openPrs.length,
+		authorityOk,
+		activeOwnerCount: authorityOk ? activeOwnerCount(listed.records) : null,
+		executionOk: execution?.ok === true,
+	};
+}
+
+function daemonCanRetire(convergence) {
+	return convergence?.desiredCount === 0
+		&& convergence.authorityOk === true
+		&& convergence.activeOwnerCount === 0
+		&& convergence.executionOk !== false;
+}
+
+function stableJson(value) {
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+	if (value && typeof value === 'object') {
+		return `{${Object.keys(value).sort((left, right) => left.localeCompare(right)).map(key => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+	}
+	return JSON.stringify(value);
+}
+
+const LEGACY_HASH_ENTRY_FIELDS = [
+	'repo', 'pr', 'pid', 'startedAt', 'terminalReceiptId', 'providerState', 'legacyPhase',
+	'generation', 'controllerPid', 'blockReason',
+	'lifecycleConflict', 'legacyEvidence',
+];
+
+function projectLegacyHashEntry(entry) {
+	const projected = {};
+	for (const field of LEGACY_HASH_ENTRY_FIELDS) {
+		if (Object.hasOwn(entry || {}, field)) projected[field] = entry[field];
+	}
+	return projected;
+}
+
+function hashLegacyEntry(entry) {
+	return crypto.createHash('sha256').update(stableJson(projectLegacyHashEntry(entry))).digest('hex');
+}
+
+// Legacy discovery labels each root by how the *invoking* checkout reached it, so the same
+// shared marker is recorded as `.forge/pr-monitor/...` from the primary checkout and
+// `git-common-root/.forge/pr-monitor/...` from a linked worktree. Hash a checkout-independent
+// identity instead, or an interrupted cutover resumed from another checkout self-conflicts.
+const LEGACY_ROOT_LABELS = [
+	'git-common-root/.forge/pr-monitor',
+	'git-common/forge/pr-monitor',
+	'.forge/pr-monitor',
+];
+
+function canonicalMarkerPath(rawPath) {
+	let value = String(rawPath ?? '').replace(/\\/g, '/').replace(/^\.\//, '');
+	for (const label of LEGACY_ROOT_LABELS) {
+		if (value === label || value.startsWith(`${label}/`)) {
+			value = value.slice(label.length).replace(/^\/+/, '');
+			break;
+		}
+	}
+	return process.platform === 'win32' ? value.toLowerCase() : value;
+}
+
+function canonicalMarkers(sources) {
+	const unique = new Map();
+	for (const source of sources) {
+		const marker = { path: canonicalMarkerPath(source?.path), content: source?.content };
+		unique.set(stableJson(marker), marker);
+	}
+	return [...unique.values()].sort((left, right) => stableJson(left).localeCompare(stableJson(right)));
+}
+
+function hashLegacySnapshot(snapshot) {
+	const canonical = snapshot && typeof snapshot === 'object' && !Array.isArray(snapshot)
+		? {
+			corrupt: snapshot.corrupt === true,
+			unmappable: snapshot.unmappable === true,
+			entries: (Array.isArray(snapshot.entries) ? snapshot.entries : [])
+				.map(projectLegacyHashEntry)
+				.sort((left, right) => stableJson(left).localeCompare(stableJson(right))),
+			markers: canonicalMarkers((Array.isArray(snapshot.sources) ? snapshot.sources : [])
+				.filter(source => /generation|cleanup/i.test(path.basename(String(source?.path || ''))))),
+		}
+		: snapshot;
+	const encoded = stableJson(canonical);
+	if (Buffer.byteLength(encoded, 'utf8') > MAX_LEGACY_SNAPSHOT_BYTES) {
+		const error = new Error('Legacy watcher snapshot exceeds the migration bound');
+		error.code = 'LEGACY_SNAPSHOT_TOO_LARGE';
+		throw error;
+	}
+	return crypto.createHash('sha256').update(encoded).digest('hex');
+}
+
+const LEGACY_LIFECYCLE_FIELDS = [
+	'pid', 'startedAt', 'terminalReceiptId', 'providerState', 'legacyPhase',
+	'generation', 'controllerPid', 'blockReason',
+];
+
+function consolidateLegacyEntries(rawEntries) {
+	const grouped = new Map();
+	let unmappable = false;
+	for (const raw of Array.isArray(rawEntries) ? rawEntries : []) {
+		const repo = normalizeRepository(raw?.repo);
+		const pr = Number(raw?.pr);
+		if (!repo || !Number.isSafeInteger(pr) || pr <= 0) {
+			unmappable = true;
+			continue;
+		}
+		const key = `${repo}#${pr}`;
+		let group = grouped.get(key);
+		if (!group) {
+			group = { repo, pr, values: {}, evidence: new Map(), lifecycleConflict: false };
+			grouped.set(key, group);
+		}
+		const normalized = { repo, pr };
+		for (const field of LEGACY_LIFECYCLE_FIELDS) {
+			const value = raw?.[field] == null ? null : raw[field];
+			normalized[field] = value;
+			if (value == null) continue;
+			if (group.values[field] != null && stableJson(group.values[field]) !== stableJson(value)) {
+				group.lifecycleConflict = true;
+			} else {
+				group.values[field] = value;
+			}
+		}
+		group.evidence.set(stableJson(normalized), normalized);
+	}
+	const entries = [...grouped.values()].map(group => ({
+		repo: group.repo,
+		pr: group.pr,
+		...group.values,
+		lifecycleConflict: group.lifecycleConflict,
+		legacyEvidence: [...group.evidence.values()].sort((left, right) => stableJson(left).localeCompare(stableJson(right))),
+	})).sort((left, right) => left.repo.localeCompare(right.repo) || left.pr - right.pr);
+	return { entries, unmappable };
+}
+
+const OWNER_REREAD_FIELDS = [
+	'version', 'repo', 'pr', 'generation', 'phase', 'controllerPid', 'watcherPid',
+	'startedAt', 'updatedAt', 'heartbeatAt', 'terminalReceiptId', 'blockReason', 'legacyEvidenceHash',
+];
+
+function ownerRereadProjection(record, fields = OWNER_REREAD_FIELDS) {
+	const projected = {};
+	for (const field of fields) {
+		if (Object.hasOwn(record || {}, field)) projected[field] = record[field];
+	}
+	return projected;
+}
+
+function ownerRowsMatch(expectedRows, actualRows) {
+	if (expectedRows.length !== actualRows.length) return false;
+	const actualByKey = new Map();
+	for (const row of actualRows) {
+		const key = `${row?.repo}#${row?.pr}`;
+		if (actualByKey.has(key)) return false;
+		actualByKey.set(key, row);
+	}
+	return expectedRows.every((expected) => {
+		const actual = actualByKey.get(`${expected.repo}#${expected.pr}`);
+		if (!actual) return false;
+		const fields = OWNER_REREAD_FIELDS.filter(field => Object.hasOwn(expected, field));
+		return stableJson(ownerRereadProjection(actual, fields)) === stableJson(ownerRereadProjection(expected, fields));
 	});
+}
+
+function readOptionalFile(file) {
+	try { return fs.readFileSync(file, 'utf8'); } catch (error) {
+		if (error?.code === 'ENOENT') return null;
+		throw error;
+	}
+}
 
-	let leaseLost = false;
-	const updateWatchers = opts.updateWatchers || shepherdLease.updateWatchers;
-	if (opts.token) {
+function defaultReadLegacySnapshot(projectRoot, opts = {}) {
+	const gitCommonDir = opts.gitCommonDir || brokerMod.resolveGitCommonDir(projectRoot);
+	const repo = normalizeRepository(opts.repo);
+	const readDirectory = opts.readDirectory || fs.readdirSync;
+	const sources = [];
+	const entries = [];
+	let unmappable = false;
+	const commonRoot = path.basename(gitCommonDir).toLowerCase() === '.git'
+		? path.dirname(gitCommonDir) : projectRoot;
+	const leaseFile = path.join(gitCommonDir, 'forge', 'shepherd.lock');
+	const leaseRaw = readOptionalFile(leaseFile);
+	if (leaseRaw != null) {
+		let lease;
+		try { lease = JSON.parse(leaseRaw); } catch { return { entries, sources, corrupt: true, unmappable: false }; }
+		const legacyWatchers = Array.isArray(lease.watchers) ? lease.watchers : [];
+		sources.push({ path: 'shepherd.lock#watchers', content: stableJson(legacyWatchers) });
+		for (const watcher of legacyWatchers) {
+			const value = typeof watcher === 'number' ? { pr: watcher } : watcher;
+			const pr = Number(value?.pr);
+			const identityRepo = normalizeRepository(value?.repo) || repo;
+			if (!identityRepo || !Number.isSafeInteger(pr) || pr <= 0) { unmappable = true; continue; }
+			entries.push({ repo: identityRepo, pr, pid: Number(value?.pid) || null, startedAt: value?.startedAt || null });
+		}
+	}
+	const roots = [
+		{ dir: path.join(projectRoot, '.forge', 'pr-monitor'), label: '.forge/pr-monitor' },
+		{ dir: path.join(commonRoot, '.forge', 'pr-monitor'), label: 'git-common-root/.forge/pr-monitor' },
+		{ dir: path.join(gitCommonDir, 'forge', 'pr-monitor'), label: 'git-common/forge/pr-monitor' },
+	];
+	const seenRoots = new Set();
+	for (const candidate of roots) {
+		const resolved = path.resolve(candidate.dir).toLowerCase();
+		if (seenRoots.has(resolved)) continue;
+		seenRoots.add(resolved);
+		let directories = [];
 		try {
-			// updateWatchers returns false when the lock is gone or owned by a DIFFERENT
-			// token — i.e. THIS daemon was superseded (its stale lease reclaimed by a newer
-			// one). Signal the caller to stop: a superseded daemon must not keep spawning/
-			// reaping watchers behind the live owner's back.
-			const published = updateWatchers(projectRoot, watchers, { gitCommonDir, token: opts.token });
-			if (published === false) leaseLost = true;
-		} catch {
-			/* publishing the watcher set is best-effort — the next pass re-derives it */
+			directories = readDirectory(candidate.dir, { withFileTypes: true })
+				.filter(item => item.isDirectory()).sort((left, right) => left.name.localeCompare(right.name));
+		}
+		catch (error) { if (error?.code !== 'ENOENT') return { entries, sources, corrupt: true, unmappable }; }
+		for (const directory of directories) {
+			if (directory.name === 'owners') continue;
+			const dir = path.join(candidate.dir, directory.name);
+			const snapshotRaw = readOptionalFile(path.join(dir, 'snapshot.json'));
+			const pidRaw = readOptionalFile(path.join(dir, 'watch.pid'));
+			const startedAtRaw = readOptionalFile(path.join(dir, 'watch.startedat'));
+			// Discover generation/cleanup markers BEFORE the emptiness check. An
+			// interrupted legacy cleanup can leave a directory holding nothing but a
+			// marker; skipping it would keep that marker out of the snapshot and its
+			// hash, letting the gate complete as if no legacy lifecycle authority
+			// existed and a new owner generation start beside an unresolved legacy one.
+			let markerFiles = [];
+			try {
+				markerFiles = readDirectory(dir, { withFileTypes: true })
+					.filter(item => item.isFile() && /(?:generation|cleanup)/i.test(item.name))
+					.sort((left, right) => left.name.localeCompare(right.name));
+			} catch (error) {
+				if (error?.code !== 'ENOENT') return { entries, sources, corrupt: true, unmappable };
+			}
+			if (snapshotRaw == null && pidRaw == null && startedAtRaw == null && markerFiles.length === 0) continue;
+			const sourcePrefix = `${candidate.label}/${directory.name}`;
+			sources.push({ path: `${sourcePrefix}/snapshot.json`, content: snapshotRaw });
+			sources.push({ path: `${sourcePrefix}/watch.pid`, content: pidRaw });
+			sources.push({ path: `${sourcePrefix}/watch.startedat`, content: startedAtRaw });
+			for (const marker of markerFiles) {
+				sources.push({ path: `${sourcePrefix}/${marker.name}`, content: readOptionalFile(path.join(dir, marker.name)) });
+			}
+			let record;
+			try { record = snapshotRaw == null ? null : JSON.parse(snapshotRaw); }
+			catch { return { entries, sources, corrupt: true, unmappable }; }
+			const snapshot = record?.snapshot || record;
+			const terminalReceiptId = record?.terminalReceiptId || snapshot?.terminalReceiptId || null;
+			const hasLifecycleAuthority = pidRaw != null || startedAtRaw != null || markerFiles.length > 0
+				|| terminalReceiptId != null || record?.startedAt != null || snapshot?.startedAt != null;
+			const identityRepo = normalizeRepository(snapshot?.repo) || repo;
+			const pr = Number(snapshot?.pr);
+			if (!identityRepo || !Number.isSafeInteger(pr) || pr <= 0) { unmappable = true; continue; }
+			if (!hasLifecycleAuthority) continue;
+			entries.push({
+				repo: identityRepo,
+				pr,
+				pid: pidRaw == null ? null : Number(pidRaw.trim()),
+				startedAt: snapshot?.startedAt || startedAtRaw?.trim() || null,
+				terminalReceiptId,
+				providerState: snapshot?.state || null,
+			});
+		}
+		const ownersRoot = path.join(candidate.dir, 'owners');
+		let ownerDirectories = [];
+		try {
+			ownerDirectories = readDirectory(ownersRoot, { withFileTypes: true })
+				.filter(item => item.isDirectory()).sort((left, right) => left.name.localeCompare(right.name));
+		}
+		catch (error) { if (error?.code !== 'ENOENT') return { entries, sources, corrupt: true, unmappable }; }
+		for (const directory of ownerDirectories) {
+			const relative = `${candidate.label}/owners/${directory.name}/watch.owner.json`;
+			const raw = readOptionalFile(path.join(ownersRoot, directory.name, 'watch.owner.json'));
+			if (raw == null) continue;
+			sources.push({ path: relative, content: raw });
+			let record;
+			try { record = JSON.parse(raw); } catch { return { entries, sources, corrupt: true, unmappable }; }
+			const identityRepo = normalizeRepository(record?.repo);
+			const pr = Number(record?.pr);
+			if (!identityRepo || !Number.isSafeInteger(pr) || pr <= 0) { unmappable = true; continue; }
+			entries.push({
+				repo: identityRepo,
+				pr,
+				pid: record.pid == null ? null : Number(record.pid),
+				startedAt: record.startedAt || null,
+				terminalReceiptId: record.terminalReceiptId || null,
+				legacyPhase: record.phase || null,
+				generation: record.generation || null,
+				controllerPid: record.controllerPid == null ? null : Number(record.controllerPid),
+				blockReason: record.blockReason || null,
+			});
 		}
 	}
-	return { actions, watchers, desiredCount: desired.openPrs.length, leaseLost };
+	entries.sort((left, right) => stableJson(left).localeCompare(stableJson(right)));
+	sources.sort((left, right) => stableJson(left).localeCompare(stableJson(right)));
+	return { entries, sources, corrupt: false, unmappable };
+}
+
+async function defaultReadProviderState(entry, opts = {}) {
+	const runGh = githubRunner(opts);
+	try {
+		const raw = runGh(['pr', 'view', String(entry.pr), '--repo', entry.repo, '--json', 'state']);
+		const value = typeof raw === 'string' ? JSON.parse(raw) : raw;
+		return typeof value?.state === 'string' ? value.state.toLowerCase() : null;
+	} catch {
+		return null;
+	}
+}
+
+async function collectLegacyEntryEvidence(entry, options, opts, projectRoot) {
+	const ctx = identity(entry);
+	const pid = Number(entry.pid);
+	let hasPid = Number.isSafeInteger(pid) && pid > 0;
+	let pidState = false;
+	let pidReused = false;
+	// A bare `isPidAlive` hit is not proof the LEGACY watcher is alive: an unrelated
+	// long-lived process may have inherited the number. Importing that as
+	// blocked/legacy_live_pid is unrecoverable, because every later recheck sees the
+	// same live PID and the PR stays unwatched forever. Compare the process start time
+	// against the legacy start marker; a process that booted materially AFTER the
+	// marker cannot be the watcher that wrote it, so its PID evidence is discarded.
+	// An unknown start time changes nothing (fail closed on the live PID).
+	if (hasPid) {
+		let identityState;
+		try {
+			identityState = await processIdentityAlive({
+				pid,
+				startedAt: entry.startedAt,
+				isPidAlive: options.isPidAlive,
+				pidStartedAt: options.pidStartedAt,
+			});
+		} catch { identityState = 'unknown'; }
+		if (identityState === 'alive') pidState = true;
+		else if (identityState === 'unknown') pidState = null;
+		else pidState = false;
+		if (identityState === 'reused') {
+			hasPid = false;
+			pidReused = true;
+		}
+	}
+	let conflictingPidUnsafe = false;
+	if (entry.lifecycleConflict) {
+		const conflictPids = [...new Set((entry.legacyEvidence || [])
+			.map(value => Number(value?.pid)).filter(value => Number.isSafeInteger(value) && value > 0))];
+		for (const conflictPid of conflictPids) {
+			try {
+				if (await options.isPidAlive(conflictPid) !== false) conflictingPidUnsafe = true;
+			} catch { conflictingPidUnsafe = true; }
+		}
+	}
+	let providerState = '';
+	let providerReadable;
+	try {
+		providerState = String(
+			await (opts.readProviderState || defaultReadProviderState)(entry, { ...opts, projectRoot }) || '',
+		).toLowerCase();
+		providerReadable = providerState.length > 0;
+	} catch { providerReadable = false; }
+	const providerTerminal = ['closed', 'merged', 'terminal'].includes(providerState);
+	let providerVerified = false;
+	if ((hasPid || pidReused) && providerState === 'open' && typeof options.verifyProviderEvidence === 'function') {
+		try {
+			providerVerified = await options.verifyProviderEvidence(
+				{ state: providerState }, { ...ctx, states: ['open'] },
+			) === true;
+		} catch { providerVerified = false; }
+	}
+	let receiptVerified = false;
+	if (entry.terminalReceiptId && providerTerminal && typeof options.verifyTerminalReceipt === 'function') {
+		try { receiptVerified = await options.verifyTerminalReceipt(entry.terminalReceiptId, ctx) === true; }
+		catch { receiptVerified = false; }
+	}
+	return {
+		entry,
+		entryHash: hashLegacyEntry(entry),
+		ctx,
+		pid,
+		hasPid,
+		pidState,
+		providerState,
+		providerReadable,
+		providerTerminal,
+		providerVerified,
+		receiptVerified,
+		conflictingPidUnsafe,
+		pidReused,
+	};
+}
+
+function cachedLegacyEvidenceOptions(options, evidence) {
+	const sameIdentity = value => value?.repo === evidence.ctx.repo && value?.pr === evidence.ctx.pr;
+	return {
+		...options,
+		isPidAlive: async pid => (pid === evidence.pid ? evidence.pidState : null),
+		// Cached liveness has no start-time counterpart; identity was already settled
+		// while the evidence was collected.
+		pidStartedAt: null,
+		verifyProviderEvidence: async (providerEvidence, expected) => evidence.providerVerified
+			&& sameIdentity(expected)
+			&& String(providerEvidence?.state || '').toLowerCase() === evidence.providerState
+			&& Array.isArray(expected?.states)
+			&& expected.states.includes(evidence.providerState),
+		verifyTerminalReceipt: async (receipt, ownerIdentity) => evidence.receiptVerified
+			&& sameIdentity(ownerIdentity)
+			&& receipt === evidence.entry.terminalReceiptId,
+	};
+}
+
+async function migrateLegacyAuthority(projectRoot, opts = {}) {
+	const authority = opts.authority || watchOwner;
+	const options = ownerOptions(opts);
+	const now = new Date((opts.now || (() => Date.now()))()).toISOString();
+	const readSnapshot = opts.readLegacySnapshot || (() => defaultReadLegacySnapshot(projectRoot, opts));
+	// Legacy verification calls the SYNCHRONOUS provider runner once per entry, so the
+	// heartbeat timer started by the daemon cannot fire while a read is in flight. A
+	// handful of reads near the 30s command timeout would otherwise age the lease past
+	// its 90s TTL, let a concurrent trigger reclaim it, and leave two controllers
+	// mutating the same cutover gate. Stamp the lease around every entry, and re-verify
+	// ownership by token before any mutation that commits migration results.
+	const leaseGuarded = opts.token !== undefined && opts.token !== null;
+	const stampLease = opts.stampLease || (opts.acquire ? () => true : shepherdLease.stamp);
+	const ownsLease = opts.ownsLease || (opts.acquire ? () => true : shepherdLease.owns);
+	const leaseArgs = { gitCommonDir: opts.gitCommonDir, token: opts.token };
+	const heartbeatLease = () => {
+		if (!leaseGuarded) return;
+		try { stampLease(projectRoot, leaseArgs); } catch { /* best effort — ownership is rechecked below */ }
+	};
+	const holdsLease = () => {
+		if (!leaseGuarded) return true;
+		try { return ownsLease(projectRoot, leaseArgs) === true; } catch { return false; }
+	};
+	const initialGate = await authority.readMigrationGate({}, options);
+	if (initialGate?.ok && initialGate.gate?.state === 'complete') {
+		const completedSnapshot = await readSnapshot();
+		const completedHash = hashLegacySnapshot(completedSnapshot);
+		if (completedSnapshot?.corrupt || completedHash !== initialGate.gate.snapshot_hash) {
+			return {
+				ok: true, state: 'complete', snapshotHash: initialGate.gate.snapshot_hash,
+				cleanupPending: true, reason: 'legacy_source_changed',
+			};
+		}
+		try { await opts.cleanupLegacyEvidence?.(completedSnapshot); } catch {
+			return { ok: true, state: 'complete', snapshotHash: completedHash, cleanupPending: true };
+		}
+		return { ok: true, state: 'complete', snapshotHash: completedHash };
+	}
+	if (initialGate?.ok && initialGate.gate?.state === 'conflict') {
+		return { ok: false, state: 'conflict', reason: initialGate.gate.conflict_code || 'legacy_owner_conflict' };
+	}
+	if (!initialGate?.ok && initialGate?.reason !== 'absent') {
+		return { ok: false, state: 'quarantined', reason: initialGate?.reason || 'authority_unavailable' };
+	}
+	const quarantined = initialGate?.ok
+		? initialGate
+		: await authority.publishMigrationQuarantine({ updatedAt: now }, options);
+	if (!quarantined?.ok || quarantined.gate?.state !== 'quarantined') {
+		return { ok: false, state: 'quarantined', reason: quarantined?.reason || 'authority_unavailable' };
+	}
+	const migrationStartedAt = quarantined.gate?.updated_at || now;
+	// This process is the migrating controller; it owns rows whose legacy controller
+	// PID proved reused and therefore cannot be trusted.
+	const migrationControllerPid = Number.isSafeInteger(Number(opts.controllerPid)) && Number(opts.controllerPid) > 0
+		? Number(opts.controllerPid)
+		: process.pid;
+	let snapshot;
+	let snapshotHash;
+	let verifiedEntries;
+	for (let attempt = 0; attempt < MAX_MIGRATION_ATTEMPTS; attempt += 1) {
+		const first = await readSnapshot();
+		const firstHash = hashLegacySnapshot(first);
+		const consolidated = first && !first.corrupt
+			? consolidateLegacyEntries(first.entries)
+			: null;
+		const evidence = [];
+		if (consolidated && !first.unmappable && !consolidated.unmappable) {
+			for (const entry of consolidated.entries) {
+				heartbeatLease();
+				evidence.push(await collectLegacyEntryEvidence(entry, options, opts, projectRoot));
+				heartbeatLease();
+			}
+		}
+		if (!holdsLease()) return { ok: false, state: 'quarantined', reason: 'lease_lost' };
+		const second = await readSnapshot();
+		const secondHash = hashLegacySnapshot(second);
+		if (firstHash === secondHash) {
+			snapshot = second;
+			snapshotHash = secondHash;
+			if (consolidated && (first.unmappable || consolidated.unmappable)) {
+				await authority.publishMigrationConflict({
+					snapshotHash, conflictCode: 'legacy_identity_unmappable', updatedAt: now,
+				}, options);
+				return { ok: false, state: 'conflict', reason: 'legacy_identity_unmappable' };
+			}
+			verifiedEntries = consolidated ? evidence : null;
+			break;
+		}
+		if (attempt === MAX_MIGRATION_ATTEMPTS - 1) {
+			await authority.publishMigrationConflict({
+				snapshotHash: secondHash, conflictCode: 'legacy_snapshot_changed', updatedAt: now,
+			}, options);
+			return { ok: false, state: 'conflict', reason: 'legacy_snapshot_changed' };
+		}
+	}
+	if (!snapshot || snapshot.corrupt) {
+		await authority.publishMigrationConflict({
+			snapshotHash, conflictCode: 'legacy_owner_conflict', updatedAt: now,
+		}, options);
+		return { ok: false, state: 'conflict', reason: 'legacy_owner_conflict' };
+	}
+	if (verifiedEntries?.some(entry => entry.conflictingPidUnsafe)) {
+		await authority.publishMigrationConflict({
+			snapshotHash, conflictCode: 'legacy_owner_conflict', updatedAt: now,
+		}, options);
+		return { ok: false, state: 'conflict', reason: 'legacy_owner_conflict' };
+	}
+	// Ownership is rechecked BEFORE every mutation, not only after: a lease reclaimed
+	// during the preceding await must not be able to bind a snapshot or write a single
+	// owner row on the way to reporting lease_lost.
+	if (!holdsLease()) return { ok: false, state: 'quarantined', reason: 'lease_lost' };
+	const bound = await authority.bindMigrationSnapshot({ snapshotHash, updatedAt: now }, options);
+	if (!bound?.ok) return { ok: false, state: 'conflict', reason: bound?.reason || 'snapshot_mismatch' };
+	if (verifiedEntries?.some(entry => !entry.providerReadable)) {
+		return { ok: false, state: 'quarantined', reason: 'legacy_provider_unreadable' };
+	}
+
+	const expectedRows = [];
+	for (const evidence of verifiedEntries || []) {
+		const {
+			entry, entryHash, ctx, pid, hasPid, pidState, providerState, providerReadable,
+			providerTerminal, providerVerified, receiptVerified, pidReused,
+		} = evidence;
+		if (!holdsLease()) return { ok: false, state: 'quarantined', reason: 'lease_lost' };
+		const operationOptions = cachedLegacyEvidenceOptions(options, evidence);
+		let result;
+		if (entry.lifecycleConflict) {
+			result = await authority.markLegacyBlocked(ctx, {
+				blockReason: 'legacy_conflict', snapshotHash, legacyEvidenceHash: entryHash,
+				startedAt: entry.startedAt || migrationStartedAt,
+			}, operationOptions);
+		} else if (pidState == null) {
+			result = await authority.markLegacyBlocked(ctx, {
+				blockReason: 'legacy_unreadable', snapshotHash, legacyEvidenceHash: entryHash,
+				startedAt: entry.startedAt || migrationStartedAt,
+			}, operationOptions);
+		} else if (pidState === true) {
+			result = await authority.markLegacyBlocked(ctx, {
+				blockReason: 'legacy_live_pid', pid, snapshotHash, legacyEvidenceHash: entryHash,
+				...(providerTerminal && receiptVerified ? { terminalReceiptId: entry.terminalReceiptId } : {}),
+				startedAt: entry.startedAt || migrationStartedAt,
+			}, operationOptions);
+		} else if (entry.terminalReceiptId && providerTerminal && receiptVerified) {
+			result = await authority.importLegacyComplete(ctx, {
+				snapshotHash, legacyEvidenceHash: entryHash, legacyPid: hasPid ? pid : null,
+				terminalReceiptId: entry.terminalReceiptId, startedAt: entry.startedAt || migrationStartedAt,
+			}, operationOptions);
+		} else if (entry.terminalReceiptId && providerTerminal) {
+			result = await authority.markLegacyBlocked(ctx, {
+				blockReason: 'legacy_receipt_unverified', terminalReceiptId: entry.terminalReceiptId,
+				snapshotHash, legacyEvidenceHash: entryHash, startedAt: entry.startedAt || migrationStartedAt,
+			}, operationOptions);
+		} else if (!providerReadable) {
+			result = await authority.markLegacyBlocked(ctx, {
+				blockReason: 'legacy_unreadable', snapshotHash, legacyEvidenceHash: entryHash,
+				startedAt: entry.startedAt || migrationStartedAt,
+			}, operationOptions);
+		} else if ((hasPid || pidReused) && providerState === 'open' && providerVerified
+			&& typeof authority.importLegacyStarting === 'function') {
+			// A proven-reused PID is proof the legacy watcher is DEAD, so an open PR must
+			// import as a recoverable starting row rather than falling through to the
+			// permanent blocked/legacy_lossy branch below (only legacy_live_pid blocks are
+			// ever rechecked, and any blocked row suppresses inline passes). The reused
+			// number must not become the controller — that would defer recovery to an
+			// unrelated live process — so this migrating controller adopts the row.
+			result = await authority.importLegacyStarting(ctx, {
+				snapshotHash, legacyEvidenceHash: entryHash, legacyPid: pid,
+				controllerPid: pidReused ? migrationControllerPid : pid,
+				providerEvidence: { state: 'open' }, startedAt: entry.startedAt || migrationStartedAt,
+			}, operationOptions);
+		} else if (providerState === 'open') {
+			result = await authority.markLegacyBlocked(ctx, {
+				blockReason: hasPid ? 'legacy_unreadable' : 'legacy_lossy',
+				snapshotHash, legacyEvidenceHash: entryHash, startedAt: entry.startedAt || migrationStartedAt,
+			}, operationOptions);
+		} else {
+			result = await authority.markLegacyBlocked(ctx, {
+				blockReason: providerState ? 'legacy_receipt_unverified' : 'legacy_lossy',
+				snapshotHash, legacyEvidenceHash: entryHash, startedAt: entry.startedAt || migrationStartedAt,
+			}, operationOptions);
+		}
+		// A migration that crashed mid-import leaves durable rows it already wrote. If
+		// the PR's provider state has since drifted (an open PR that has closed), the
+		// resumed pass legitimately selects a DIFFERENT decision and the authority
+		// rejects it against the surviving row as `owner_conflict`. That is ordinary
+		// drift, not two writers disagreeing: the durable row carries THIS entry's
+		// legacy evidence hash, so it is our own prior import. Adopt it rather than
+		// escalating to a repo-wide migration conflict that would disable every
+		// watcher launch and inline pass. Only a row whose legacy evidence hash
+		// differs is genuinely divergent.
+		const priorImport = !result?.ok && result?.reason === 'owner_conflict'
+			&& result.record && result.record.legacyEvidenceHash === entryHash
+			? result.record
+			: null;
+		if (priorImport) {
+			expectedRows.push(ownerRereadProjection(priorImport));
+			continue;
+		}
+		if (!result?.ok || !result.record) {
+			await authority.publishMigrationConflict({
+				snapshotHash, conflictCode: 'legacy_owner_conflict', updatedAt: now,
+			}, options);
+			return { ok: false, state: 'conflict', reason: 'legacy_owner_conflict' };
+		}
+		expectedRows.push(ownerRereadProjection(result.record));
+	}
+
+	const rereadSnapshot = await readSnapshot();
+	const rows = await authority.enumerateOwners({}, options);
+	const gate = await authority.readMigrationGate({}, options);
+	const exact = hashLegacySnapshot(rereadSnapshot) === snapshotHash
+		&& rows?.ok === true
+		&& gate?.ok === true
+		&& gate.gate?.state === 'quarantined'
+		&& gate.gate?.snapshot_hash === snapshotHash
+		&& ownerRowsMatch(expectedRows, rows.records);
+	if (!exact) return { ok: false, state: 'quarantined', reason: 'legacy_reread_mismatch' };
+	if (!holdsLease()) return { ok: false, state: 'quarantined', reason: 'lease_lost' };
+	const completed = await authority.completeMigrationGate({ snapshotHash, updatedAt: now }, options);
+	if (!completed?.ok) return { ok: false, state: 'quarantined', reason: completed?.reason || 'gate_mismatch' };
+	try { await opts.cleanupLegacyEvidence?.(snapshot); } catch {
+		return { ok: true, state: 'complete', snapshotHash, cleanupPending: true };
+	}
+	return { ok: true, state: 'complete', snapshotHash };
+}
+
+async function defaultBuildBroker({ projectRoot, gitCommonDir }) {
+	const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
+	const { createMonitorStore } = require('@forge/memory');
+	const deps = await buildMigratedKernelIssueDeps({ projectRoot, gitCommonDir });
+	const store = createMonitorStore(deps.kernelDriver);
+	return {
+		broker: deps.kernelBroker,
+		driver: deps.kernelDriver,
+		databaseConfig: { databasePath: deps.kernelDatabasePath },
+		verifyTerminalReceipt: async (receiptId, ownerIdentity) => {
+			const state = await store.readDeliveryState(legacyMonitorId(ownerIdentity.repo, ownerIdentity.pr));
+			return state?.terminal_receipt?.object_id === receiptId;
+		},
+	};
 }
 
-/**
- * The singleton daemon: acquire the lease (exit if a live foreign owner holds it),
- * heartbeat, converge on a cadence, self-retire when no PRs remain. `opts.once`
- * runs a single converge (for tests); otherwise an interval loop + signal handlers.
- */
 async function runDaemon(projectRoot, opts = {}) {
 	const gitCommonDir = opts.gitCommonDir || brokerMod.resolveGitCommonDir(projectRoot);
 	const acquire = opts.acquire || shepherdLease.acquire;
+	const release = opts.release || shepherdLease.release;
 	const startHeartbeat = opts.startHeartbeat || shepherdLease.startHeartbeat;
 	const stopHeartbeat = opts.stopHeartbeat || shepherdLease.stopHeartbeat;
-	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'
-		? opts.exit
-		: (opts.exit === false ? () => {} : (code) => process.exit(code));
-
-	const res = acquire(projectRoot, { gitCommonDir });
-	if (!res.ok) {
+	const ownsLease = opts.ownsLease || (opts.acquire ? (() => true) : shepherdLease.owns);
+	const exit = typeof opts.exit === 'function' ? opts.exit : (opts.exit === false ? () => {} : code => process.exit(code));
+	const held = acquire(projectRoot, { gitCommonDir });
+	if (!held.ok) {
+		// Distinguish "someone else legitimately owns the lease" from "the lease
+		// file is unreadable and its bytes were deliberately left in place" — the
+		// latter needs an operator, not a retry, and migration has NOT run yet.
+		const reason = held.legacyMigrationPending === true
+			? (held.reason || 'legacy-lease-unreadable')
+			: 'foreign-lease';
+		if (reason !== 'foreign-lease') recordDaemonDiagnostic(opts, gitCommonDir, reason);
 		exit(0);
-		// A live, fresh foreign daemon owns this repo — exit immediately, spawn nothing.
-		return { ok: false, reason: 'foreign-lease' };
+		return { ok: false, reason };
 	}
-	const token = res.token;
+	const token = held.token;
 	const heartbeat = startHeartbeat(projectRoot, { gitCommonDir, token });
-
-	// Build ONE real kernel broker for the daemon's lifetime — createLocalBroker-backed,
-	// because listOpenPrs/upsertPr/retirePr are INSTANCE methods (the module namespace has
-	// none). Injectable for tests via opts.broker/opts.buildBroker. `ownedDriver` is closed
-	// on retire ONLY when we created it (Windows EBUSY guard — a leaked handle wedges the
-	// sqlite file). A genuine build failure degrades to the watcher half (broker stays null).
-	let broker = opts.broker || null;
-	let ownedDriver = null;
-	if (!broker) {
-		try {
-			const built = await (opts.buildBroker || defaultBuildBroker)({ projectRoot, gitCommonDir });
-			broker = built.broker;
-			ownedDriver = built.driver;
-		} catch {
-			/* kernel genuinely unavailable → run degraded (watcher convergence only) */
-		}
+	const ownsBroker = !opts.broker;
+	let built = null;
+	try {
+		built = opts.broker
+			? { broker: opts.broker, driver: opts.driver, databaseConfig: opts.databaseConfig }
+			: await (opts.buildBroker || defaultBuildBroker)({ projectRoot, gitCommonDir });
+	} catch {
+		built = null;
 	}
-
-	const convergeArgs = { ...opts, gitCommonDir, token, broker };
-
-	// retire() must NEVER throw: a release / stopHeartbeat / driver.close error must
-	// not leave the daemon un-exited (finding 4). Each teardown step swallows its own
-	// error so the caller's exit(0) always runs — no un-retired zombie.
 	const retire = async () => {
-		try { release(projectRoot, { gitCommonDir, token }); } catch { /* best effort */ }
+		try { release(projectRoot, { gitCommonDir, token }); } catch { /* token-guarded best effort */ }
 		try { stopHeartbeat(heartbeat); } catch { /* best effort */ }
-		if (ownedDriver && typeof ownedDriver.close === 'function') {
-			try { ownedDriver.close(); } catch { /* best effort */ }
+		if (ownsBroker) {
+			try { await built?.broker?.close?.(); } catch { /* best effort */ }
 		}
 	};
-
+	if (!built?.driver) {
+		await retire();
+		return { ok: false, reason: 'authority-unavailable' };
+	}
+	const runGh = githubRunner({ ...opts, projectRoot });
+	const repo = normalizeRepository(opts.repo) || resolveCanonicalRepository(runGh);
+	if (!repo) {
+		await retire();
+		return { ok: false, reason: 'repository-unavailable' };
+	}
+	const args = {
+		...opts, gitCommonDir, broker: built.broker, driver: built.driver, repo, runGh,
+		databaseConfig: built.databaseConfig,
+		verifyTerminalReceipt: opts.verifyTerminalReceipt || built.verifyTerminalReceipt,
+		token,
+	};
+	let migration;
+	try {
+		migration = await (opts.migrateLegacyAuthority || migrateLegacyAuthority)(projectRoot, args);
+	} catch (error) {
+		recordDaemonDiagnostic(opts, gitCommonDir, 'migration-failed', error);
+		await retire();
+		return { ok: false, reason: 'migration-failed' };
+	}
+	if (!migration?.ok) {
+		recordDaemonDiagnostic(opts, gitCommonDir, 'migration-blocked', migration?.reason);
+		await retire();
+		return { ok: false, reason: migration?.reason || 'migration-blocked' };
+	}
+	const converge = opts.convergeOnce || convergeOnce;
 	if (opts.once) {
-		const conv = await converge(projectRoot, convergeArgs);
-		if (conv.desiredCount === 0) {
-			recordDaemonDiagnostic(opts, gitCommonDir, 'retired-no-open-prs');
-			await retire();
-		}
-		return { ok: true, token, ...conv };
+		const result = await converge(projectRoot, args);
+		if (daemonCanRetire(result)) await retire();
+		return { ok: true, token, ...result };
 	}
 
-	const intervalMs = opts.intervalMs || 60000;
 	let stopped = false;
-	let inFlight = false;   // finding 5: re-entrancy guard — never run two passes at once
-	let lastWatchers = [];  // finding 2: thread the live watcher set across passes
+	let inFlight = false;
 	let timer = null;
-
 	const retireForLeaseLoss = async () => {
 		stopped = true;
 		if (timer) clearInterval(timer);
@@ -572,271 +1179,140 @@ async function runDaemon(projectRoot, opts = {}) {
 		await retire();
 		exit(0);
 	};
-
-	const stillOwnsLease = () => {
-		try {
-			return ownsLease(projectRoot, { gitCommonDir, token });
-		} catch {
-			return false;
-		}
+	const stillOwns = () => {
+		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;
-		}
+		if (!stillOwns()) { await retireForLeaseLoss(); return; }
 		inFlight = true;
 		try {
-			// Thread the live watcher set + a fresh heartbeat stamp so gatherObserved
-			// observes the REAL live set each pass (finding 2) — without this the daemon
-			// 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) {
-				await retireForLeaseLoss();
-			} else if (conv && conv.desiredCount === 0) {
+			const result = await converge(projectRoot, args);
+			if (!stillOwns()) { await retireForLeaseLoss(); return; }
+			if (daemonCanRetire(result)) {
 				stopped = true;
 				if (timer) clearInterval(timer);
-				recordDaemonDiagnostic(opts, gitCommonDir, 'retired-no-open-prs');
 				await retire();
 				exit(0);
 			}
 		} catch (error) {
 			recordDaemonDiagnostic(opts, gitCommonDir, 'converge-failed', error);
-			if (!stillOwnsLease()) await retireForLeaseLoss();
-			/* a bad converge pass never crashes the daemon — the next tick retries */
+			if (!stillOwns()) await retireForLeaseLoss();
 		} finally {
 			inFlight = false;
 		}
 	};
-
-	// finding 3: converge IMMEDIATELY on cold start — don't idle for up to intervalMs.
 	await runPass();
 	if (stopped) return { ok: true, token, retired: true };
-
-	timer = setInterval(runPass, intervalMs);
-	// The converge timer is intentionally left REF'd so it keeps the daemon process
-	// alive between passes (the heartbeat timer is unref'd inside startHeartbeat).
-
+	timer = setInterval(runPass, opts.intervalMs || 60_000);
 	const onSignal = async () => { await retire(); exit(0); };
 	process.on('SIGINT', onSignal);
 	process.on('SIGTERM', onSignal);
-
 	return { ok: true, token, heartbeat, timer };
 }
 
-/**
- * Launch the singleton daemon. Classify the execution home by CAPABILITY presence
- * (`ctx.harness.hasBgShell`), NEVER by harness name; uncertain → detached spawn
- * modeled on `startPrWatcherDetached`. Never throws.
- */
 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') {
+		? path.dirname(ctx.gitCommonDir) : ctx.projectRoot;
+	let argv;
+	let environment;
+	try {
+		argv = forgeArgs(['shepherd', 'daemon'], ctx);
+		const env = githubWorkerEnvironment(commonRoot, ctx);
+		environment = env ? { env } : {};
+	} catch {
+		recordDaemonDiagnostic(ctx, ctx.gitCommonDir, 'launch-failed');
+		return { launched: false };
+	}
+	if (ctx.harness?.hasBgShell && typeof ctx.harness.runBgShell === 'function') {
 		try {
-			harness.runBgShell([process.execPath, forgeBin(), 'shepherd', 'daemon'], { cwd: commonRoot });
+			ctx.harness.runBgShell([process.execPath, ...argv], { cwd: commonRoot, ...environment });
 			return { launched: true, via: 'bg-shell' };
-		} catch {
-			/* fall through to the detached fail-safe */
-		}
+		} catch { /* detached fallback */ }
 	}
-	const spawnFn = ctx.spawnProcess || spawn;
 	try {
-		const child = spawnFn(
-			process.execPath,
-			[forgeBin(), 'shepherd', 'daemon'],
-			{ cwd: commonRoot, detached: true, stdio: 'ignore', windowsHide: true },
-		);
-		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 (error) {
-		recordDaemonDiagnostic(ctx, ctx.gitCommonDir, 'launch-failed', error);
+		const child = (ctx.spawnProcess || spawn)(process.execPath, argv, {
+			cwd: commonRoot, detached: true, stdio: 'ignore', windowsHide: true, ...environment,
+		});
+		child?.on?.('error', () => recordDaemonDiagnostic(ctx, ctx.gitCommonDir, 'launch-failed'));
+		child?.unref?.();
+		return { launched: true, via: 'detached', pid: child?.pid ?? null };
+	} catch {
+		recordDaemonDiagnostic(ctx, ctx.gitCommonDir, 'launch-failed');
 		return { launched: false };
 	}
 }
 
-/**
- * Build a live, migrated kernel broker (+ its owned driver) for the daemon. Uses the
- * same createLocalBroker-backed factory the CLI uses, so listOpenPrs/upsertPr/retirePr
- * are the real instance methods. The caller closes `driver` on retire.
- */
-async function defaultBuildBroker({ projectRoot, gitCommonDir }) {
-	const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
-	const deps = await buildMigratedKernelIssueDeps({ projectRoot, gitCommonDir });
-	return { broker: deps.kernelBroker, driver: deps.kernelDriver };
-}
-
-/**
- * Whether the default-ON `rail.auto_shepherd` gate permits the autonomous trigger.
- * Reuses ship.js's `autoShepherdRailEnabled` — the SAME resolver `forge push`,
- * `forge ship`, and `forge shepherd adopt` honor — so one `forge gate disable
- * rail.auto_shepherd` turns the whole autonomous surface off. Lazy-required to keep
- * the per-command trigger cheap and avoid an eager/circular load; FAIL-OPEN (returns
- * enabled) if the resolver can't be read, and never throws.
- */
 function railAutoShepherdEnabled(projectRoot) {
-	try {
-		return require('../commands/ship').autoShepherdRailEnabled(projectRoot);
-	} catch {
-		return true; // config unreadable → fail open (default-ON), never block the trigger's own path
-	}
+	try { return require('../commands/ship').autoShepherdRailEnabled(projectRoot); }
+	catch { return true; }
 }
 
-/**
- * True iff a kernel DB already exists for `projectRoot` — the SAME no-lazy-create
- * invariant `forge prime` honors (orientation.hasExistingKernelDb). The trigger must
- * CREATE NOTHING in an uninitialized or setup/init TARGET repo (else `setup --dry-run`
- * and `init` would sprout a shepherd.lock and pollute output). SILENT: a no-op `warn`
- * suppresses resolveGitCommonDir's fallback message on a non-git dir. Never throws.
- */
 function kernelInitialized(projectRoot) {
 	try {
-		// Resolve the git-common-dir with a FAST, SUBPROCESS-FREE read — NEVER `git
-		// rev-parse` (its 30s timeout would block every registry command on the dispatch
-		// finally, and a git subprocess pollutes bare-repo command tests). Common checkout:
-		// <root>/.git is a dir. Linked worktree: <root>/.git is a file `gitdir: …/worktrees/x`
-		// whose common dir is the part before `/worktrees/`.
 		const gitPath = path.join(projectRoot, '.git');
-		const st = fs.statSync(gitPath); // throws if absent → not a repo → false
-		let commonDir;
-		if (st.isDirectory()) {
-			commonDir = gitPath;
-		} else {
-			const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(gitPath, 'utf8'));
-			if (!m) return false;
-			const wtGitDir = path.resolve(projectRoot, m[1].trim());
+		const stat = fs.statSync(gitPath);
+		let commonDir = gitPath;
+		if (!stat.isDirectory()) {
+			const match = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(gitPath, 'utf8'));
+			if (!match) return false;
+			const worktreeGitDir = path.resolve(projectRoot, match[1].trim());
 			const marker = `${path.sep}worktrees${path.sep}`;
-			const idx = wtGitDir.lastIndexOf(marker);
-			commonDir = idx >= 0 ? wtGitDir.slice(0, idx) : wtGitDir;
+			const index = worktreeGitDir.lastIndexOf(marker);
+			commonDir = index >= 0 ? worktreeGitDir.slice(0, index) : worktreeGitDir;
 		}
 		return fs.existsSync(path.join(commonDir, 'forge', 'kernel.sqlite'));
-	} catch {
-		return false;
-	}
-}
-
-/** Empty enumeration for a cold-tick loser that lost the lease race (backs off). */
-function emptyEnum(gitCommonDir) {
-	return {
-		desired: { openPrs: [], gitCommonDir },
-		observed: { lease: null, leaseFresh: false, prRows: [], liveWatcherPids: [] },
-	};
+	} catch { return false; }
 }
 
-/**
- * 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
- * `gh pr list` enumeration + converge), and a loser backs off — no spawn. The
- * arbitration lease is released immediately after launch so the spawned daemon can
- * take sole ownership; the daemon's own `acquire` is the final singleton authority,
- * so even a race that double-launches still yields exactly one live daemon.
- *
- * The gh enumeration deliberately lives in the DAEMON, not here, so this trigger
- * NEVER runs a blocking subprocess on the command's critical path.
- *
- * CONTRACT: never throws, never blocks (no await), never affects the command.
- */
 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 (
-			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 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
-		// `forge gate disable rail.auto_shepherd` gets a fully inert trigger — no lease,
-		// no enumeration, no daemon spawn. Cheap + fail-open, inside the dispatch try.
-		const railEnabled = ctx.railEnabled || railAutoShepherdEnabled;
-		if (!railEnabled(projectRoot)) return;
-		let gitCommonDir = ctx.gitCommonDir;
-		if (!gitCommonDir) {
-			try {
-				gitCommonDir = brokerMod.resolveGitCommonDir(projectRoot, { warn: () => {} });
-			} catch {
-				return;
-			}
-		}
+		if (env.FORGE_SHEPHERD_DISABLE || env.NODE_ENV === 'test' || env.BUN_ENV === 'test'
+			|| env.CI || env.GITHUB_ACTIONS || env.GITLAB_CI || ctx.dryRun || !ctx.projectRoot) return;
+		if (!(ctx.kernelInitialized || kernelInitialized)(ctx.projectRoot)) return;
+		if (!(ctx.railEnabled || railAutoShepherdEnabled)(ctx.projectRoot)) return;
+		const gitCommonDir = ctx.gitCommonDir
+			|| brokerMod.resolveGitCommonDir(ctx.projectRoot, { warn: () => {} });
 		const acquire = ctx.acquire || shepherdLease.acquire;
 		const release = ctx.release || shepherdLease.release;
-		const launch = ctx.launch || launchDaemon;
-		const tickFn = ctx.tick || defaultTick;
-
 		let token = null;
+		let legacyMigrationPending = false;
 		const enumerate = () => {
-			// COLD path only: arbitrate the singleton. The O_EXCL acquire is the atomic
-			// arbiter — exactly one concurrent trigger wins; the rest get {ok:false}.
-			const res = acquire(projectRoot, { gitCommonDir });
-			if (res.ok) token = res.token;
-			return emptyEnum(gitCommonDir);
+			const result = acquire(ctx.projectRoot, { gitCommonDir, preserveLegacy: true });
+			if (result.ok) token = result.token;
+			legacyMigrationPending = result.legacyMigrationPending === true;
+			return { desired: { openPrs: [], gitCommonDir }, observed: { ownerRows: [], ownerRowsOk: false, prRows: [] } };
 		};
-		const execute = () => {
-			if (token == null) return; // loser: no daemon launch
-			// RELEASE the arbitration lease BEFORE launching so the spawned daemon can
-			// acquire it. Holding it during launch races the child's runDaemon().acquire():
-			// the child would see a fresh foreign owner and exit, and after we then release,
-			// the bumped cold-tick sentinel suppresses re-launch until the next throttle
-			// window — leaving NO daemon running.
+		const executeTick = () => {
+			if (token == null && !legacyMigrationPending) return;
 			const held = token;
 			token = null;
-			try { release(projectRoot, { gitCommonDir, token: held }); } catch { /* best effort */ }
-			try { launch({ ...ctx, projectRoot, gitCommonDir }); } catch { /* best effort */ }
+			legacyMigrationPending = false;
+			if (held != null) {
+				try { release(ctx.projectRoot, { gitCommonDir, token: held }); } catch { /* best effort */ }
+			}
+			try { (ctx.launch || launchDaemon)({ ...ctx, gitCommonDir }); } catch { /* best effort */ }
 		};
-
-		tickFn({ gitCommonDir, now: ctx.now, enumerate, execute, minInterval: ctx.minInterval });
-	} catch {
-		/* NEVER affect the command result or exit code */
-	}
+		(ctx.tick || defaultTick)({
+			gitCommonDir, now: ctx.now, enumerate, execute: executeTick, minInterval: ctx.minInterval,
+		});
+	} catch { /* never affect triggering command */ }
 }
 
 module.exports = {
-	normalizeWatcher,
-	writeClaimMarker,
-	readClaimMarker,
+	normalizeRepository,
 	gatherDesired,
 	gatherObserved,
-	verifiedKill,
 	execute,
 	convergeOnce,
 	runDaemon,
 	launchDaemon,
 	writeDaemonDiagnostic,
 	defaultBuildBroker,
+	migrateLegacyAuthority,
+	defaultReadLegacySnapshot,
+	defaultReadProviderState,
+	hashLegacySnapshot,
 	fireAndForget,
 };