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

package/lib/pr-monitor/render-summary.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { normalizeEvidenceText } = require('../review-adapter');
+
 /**
  * PR-monitor Actions-summary renderer. It turns one read-only
  * `gatherPrBundle` result (lib/pr-bundle.js) into deterministic Markdown for
@@ -19,6 +21,7 @@
  * how it is displayed, so there is no second verdict ladder to drift.
  */
 const VERDICT_HEADLINE = {
+  INCOMPLETE: '⚪ **Verdict: `INCOMPLETE`** — bounded review/check evidence is incomplete; merge readiness blocked (fail-closed).',
   UNKNOWN: '⚪ **Verdict: `unknown`** — a signal was unreadable; state unconfirmed (fail-closed).',
   'BLOCKED-CONFLICT': '🔀 **Verdict: `blocked-conflict`** — branch conflicts with base; rebase/merge and resolve.',
   BEHIND: '⬇️ **Verdict: `behind`** — branch is behind base; update/rebase (protection requires up-to-date).',
@@ -28,6 +31,13 @@ const VERDICT_HEADLINE = {
   'CLEAN-MERGEABLE': '🟢 **Verdict: `clean-mergeable`** — green + zero unresolved threads; ready for a human to merge.',
 };
 
+const MAX_SUMMARY_THREADS = 64;
+const MAX_SUMMARY_CHECKS = 20;
+const MAX_SUMMARY_AUTHORS = 12;
+const MAX_SUMMARY_TEXT_CHARS = 256;
+const MAX_SUMMARY_SIGNALS = 16;
+const MAX_SUMMARY_CHARS = 32768;
+
 /** Render the one-line headline for a canonical verdict, failing closed. */
 function verdictHeadline(verdict) {
   return VERDICT_HEADLINE[String(verdict || '').toUpperCase()] || VERDICT_HEADLINE.UNKNOWN;
@@ -42,7 +52,7 @@ function verdictHeadline(verdict) {
  * one line per diagnostic.
  */
 function mdCode(value) {
-  const text = String(value ?? '').replace(/[\r\n]+/g, ' ');
+  const text = normalizeEvidenceText(value, { maxChars: MAX_SUMMARY_TEXT_CHARS });
   let longestRun = 0;
   let currentRun = 0;
   for (const character of text) {
@@ -65,19 +75,38 @@ const MAX_THREADS_PER_AUTHOR = 8;
 function groupByAuthor(comments) {
   const byAuthor = new Map();
   for (const comment of (Array.isArray(comments) ? comments : [])) {
-    const author = String(comment.author || 'unknown');
+    const author = normalizeEvidenceText(comment.author || 'unknown', { maxChars: MAX_SUMMARY_TEXT_CHARS });
     if (!byAuthor.has(author)) byAuthor.set(author, []);
     byAuthor.get(author).push(comment);
   }
-  return [...byAuthor.entries()].sort(
-    (a, b) => (b[1].length - a[1].length) || a[0].localeCompare(b[0]),
-  );
+  return [...byAuthor.entries()].sort((a, b) => {
+    if (b[1].length !== a[1].length) return b[1].length - a[1].length;
+    if (a[0] < b[0]) return -1;
+    if (a[0] > b[0]) return 1;
+    return 0;
+  });
 }
 
 /** One-line locator for a thread: `path:line` when known, else its id. */
 function threadLocator(thread) {
-  if (thread.path) return thread.line != null ? `${thread.path}:${thread.line}` : thread.path;
-  return thread.threadId || '(thread)';
+  if (thread.path) {
+    const path = normalizeEvidenceText(thread.path, { maxChars: MAX_SUMMARY_TEXT_CHARS });
+    return thread.line != null ? `${path}:${thread.line}` : path;
+  }
+  return normalizeEvidenceText(thread.threadId || '(thread)', { maxChars: MAX_SUMMARY_TEXT_CHARS });
+}
+
+function validThread(thread) {
+  if (!thread || typeof thread !== 'object' || Array.isArray(thread)
+    || typeof thread.author !== 'string' || !thread.author.trim()) return false;
+  const hasPath = typeof thread.path === 'string' && thread.path.trim();
+  const hasId = typeof thread.threadId === 'string' && thread.threadId.trim();
+  return Boolean(hasPath || hasId);
+}
+
+function validCheck(check) {
+  return Boolean(check && typeof check === 'object' && !Array.isArray(check)
+    && typeof check.name === 'string' && check.name.trim());
 }
 
 /** Render unresolved review threads, preserving fail-closed availability. */
@@ -89,22 +118,34 @@ function renderThreads(bundle, lines) {
     lines.push('### Review threads');
     lines.push(`⚠️ Review threads were **unreadable** this pass (${mdCode(why)}) — not treated as zero. Re-run once the read recovers.`);
     lines.push('');
-    return;
+    return 'INCOMPLETE';
   }
 
-  const comments = Array.isArray(bundle.unresolvedComments) ? bundle.unresolvedComments : [];
+  if (!Array.isArray(bundle.unresolvedComments)
+    || bundle.unresolvedComments.slice(0, MAX_SUMMARY_THREADS + 1).some((thread) => !validThread(thread))) {
+    lines.push(
+      '### Review threads',
+      '⚠️ Review thread evidence was **malformed** this pass — not treated as zero.',
+      ''
+    );
+    return 'INCOMPLETE';
+  }
+
+  const comments = bundle.unresolvedComments;
+  const incomplete = comments.length > MAX_SUMMARY_THREADS;
   if (comments.length === 0) {
     lines.push('### Review threads');
     lines.push('✅ No unresolved review threads.');
     lines.push('');
-    return;
+    return 'ZERO';
   }
 
-  const groups = groupByAuthor(comments);
+  const boundedComments = comments.slice(0, MAX_SUMMARY_THREADS);
+  const groups = groupByAuthor(boundedComments).slice(0, MAX_SUMMARY_AUTHORS);
   lines.push(`### Unresolved review threads (${comments.length})`);
   lines.push('');
   for (const [author, threads] of groups) {
-    lines.push(`- **${author}** — ${threads.length}`);
+    lines.push(`- **${mdCode(author)}** — ${threads.length}`);
     for (const thread of threads.slice(0, MAX_THREADS_PER_AUTHOR)) {
       lines.push(`  - ${mdCode(threadLocator(thread))}`);
     }
@@ -112,7 +153,15 @@ function renderThreads(bundle, lines) {
       lines.push(`  - …and ${threads.length - MAX_THREADS_PER_AUTHOR} more`);
     }
   }
+  if (comments.length > boundedComments.length) {
+    lines.push(`- …and ${comments.length - boundedComments.length} more thread(s) omitted by the bounded summary`);
+  }
+  const representedThreads = groups.reduce((total, [, threads]) => total + threads.length, 0);
+  if (representedThreads < boundedComments.length) {
+    lines.push(`- …and ${boundedComments.length - representedThreads} thread(s) from additional authors`);
+  }
   lines.push('');
+  return incomplete ? 'INCOMPLETE' : 'OPEN';
 }
 
 /** Render failing and pending checks, preserving fail-closed availability. */
@@ -123,24 +172,43 @@ function renderChecks(bundle, lines) {
     lines.push('### Checks');
     lines.push('⚠️ Checks were **unreadable** this pass — not treated as green. Re-run once the read recovers.');
     lines.push('');
-    return;
+    return false;
   }
 
   const ci = bundle.ci || {};
-  const failing = Array.isArray(ci.failing) ? ci.failing : [];
-  const pending = Array.isArray(ci.pending) ? ci.pending : [];
+  const checkArrays = [ci.checks, ci.failing, ci.pending];
+  if (checkArrays.some((checks) => !Array.isArray(checks))
+    || checkArrays.some((checks) => checks.slice(0, MAX_SUMMARY_CHECKS + 1)
+      .some((check) => !validCheck(check)))) {
+    lines.push(
+      '### Checks',
+      '⚠️ Check evidence was **malformed** this pass — not treated as green.',
+      ''
+    );
+    return false;
+  }
+  const failing = ci.failing;
+  const pending = ci.pending;
+  const incomplete = checkArrays.some((checks) => checks.length > MAX_SUMMARY_CHECKS);
   lines.push('### Checks');
   if (failing.length === 0 && pending.length === 0) {
     lines.push('✅ No failing or pending checks.');
   } else {
     if (failing.length > 0) {
-      lines.push(`- ❌ **Failing (${failing.length}):** ${failing.map((check) => mdCode(check.name || '?')).join(', ')}`);
+      lines.push(`- ❌ **Failing (${failing.length}):** ${failing.slice(0, MAX_SUMMARY_CHECKS).map((check) => mdCode(check.name || '?')).join(', ')}`);
+      if (failing.length > MAX_SUMMARY_CHECKS) {
+        lines.push(`  - …and ${failing.length - MAX_SUMMARY_CHECKS} more failing check(s)`);
+      }
     }
     if (pending.length > 0) {
-      lines.push(`- ⏳ **Pending (${pending.length}):** ${pending.map((check) => mdCode(check.name || '?')).join(', ')}`);
+      lines.push(`- ⏳ **Pending (${pending.length}):** ${pending.slice(0, MAX_SUMMARY_CHECKS).map((check) => mdCode(check.name || '?')).join(', ')}`);
+      if (pending.length > MAX_SUMMARY_CHECKS) {
+        lines.push(`  - …and ${pending.length - MAX_SUMMARY_CHECKS} more pending check(s)`);
+      }
     }
   }
   lines.push('');
+  return !incomplete;
 }
 
 /**
@@ -159,8 +227,11 @@ function renderSummary(bundle = {}, opts = {}) {
   const lines = ['## 🔭 Forge PR Monitor', ''];
   const verdict = String(opts.verdict || '').toUpperCase();
   const isUnknown = verdict === 'UNKNOWN' || !VERDICT_HEADLINE[verdict];
-  const unreadable = Array.isArray(opts.unreadable) ? opts.unreadable.filter(Boolean) : [];
+  const unreadable = Array.isArray(opts.unreadable)
+    ? opts.unreadable.filter(Boolean).slice(0, MAX_SUMMARY_SIGNALS)
+    : [];
 
+  const headlineIndex = lines.length;
   lines.push(verdictHeadline(opts.verdict));
   if (isUnknown && unreadable.length > 0) {
     lines.push('');
@@ -170,8 +241,8 @@ function renderSummary(bundle = {}, opts = {}) {
   lines.push('_Surfaces open review + check state so async feedback never rots. This monitor **does not merge** and never resolves review threads — a human merges in the GitHub UI._');
   lines.push('');
 
-  renderThreads(bundle, lines);
-  renderChecks(bundle, lines);
+  let threadState = renderThreads(bundle, lines);
+  const checksComplete = renderChecks(bundle, lines);
 
   const branch = bundle.branch || {};
   if ((branch.behind || 0) > 0) {
@@ -180,14 +251,40 @@ function renderSummary(bundle = {}, opts = {}) {
   }
 
   const pr = opts.pr || bundle.pr || '<pr>';
-  lines.push('---');
-  lines.push(`Detailed JSON: ${mdCode(`forge shepherd ${pr} --pull --json`)}`);
-  lines.push(`_Updated ${now.toISOString()} · summary-only monitor · labels state, never merges, never resolves threads._`);
+  const detailCommand = mdCode(`forge shepherd ${pr} --pull --json`);
+  lines.push(
+    '---',
+    `Detailed JSON: ${detailCommand}`,
+    `_Updated ${now.toISOString()} · summary-only monitor · labels state, never merges, never resolves threads._`
+  );
+
+  let evidenceStatus = threadState === 'INCOMPLETE' || !checksComplete ? 'INCOMPLETE' : 'COMPLETE';
+  if (evidenceStatus === 'INCOMPLETE') lines[headlineIndex] = verdictHeadline('INCOMPLETE');
+  let body = lines.join('\n');
+  if (body.length > MAX_SUMMARY_CHARS) {
+    threadState = 'INCOMPLETE';
+    evidenceStatus = 'INCOMPLETE';
+    body = [
+      '## 🔭 Forge PR Monitor',
+      '',
+      verdictHeadline('INCOMPLETE'),
+      '',
+      '⚠️ Summary evidence exceeded the bounded rendering limit; inspect the detailed JSON.',
+      '',
+      '_This monitor does not merge and never resolves review threads._',
+      '',
+      `Detailed JSON: ${detailCommand}`,
+      `_Updated ${now.toISOString()} · summary-only monitor · labels state, never merges, never resolves threads._`,
+    ].join('\n');
+  }
 
-  return { body: lines.join('\n') };
+  return { body, evidenceStatus, threadState };
 }
 
 module.exports = {
+  MAX_SUMMARY_CHARS,
+  MAX_SUMMARY_CHECKS,
+  MAX_SUMMARY_THREADS,
   renderSummary,
   verdictHeadline,
   groupByAuthor,

package/lib/pr-monitor/review-preflight.js

@@ -0,0 +1,269 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+const preflightCommand = require('../commands/preflight');
+
+const MAX_FINDINGS = 20;
+const MAX_FINDING_CHARS = 500;
+
+function boundedLines(value) {
+  return String(value || '')
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(Boolean)
+    .slice(0, MAX_FINDINGS)
+    .map(line => line.slice(0, MAX_FINDING_CHARS));
+}
+
+async function defaultProbeCodeRabbit({ projectRoot }, exec = execFileSync) {
+  try {
+    exec('coderabbit', ['--version'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      timeout: 10_000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    return { available: true };
+  } catch (error) {
+    const reason = error?.code === 'ENOENT' ? 'CLI not installed' : 'CLI unavailable or unauthenticated';
+    return { available: false, reason };
+  }
+}
+
+function parseCodeRabbitEvents(output) {
+  const rawLines = String(output || '').split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+  const events = [];
+  let malformed = rawLines.length === 0;
+  for (const line of rawLines) {
+    try {
+      const event = JSON.parse(line);
+      if (!event || typeof event !== 'object' || Array.isArray(event)) malformed = true;
+      else events.push(event);
+    } catch {
+      malformed = true;
+    }
+  }
+  return { events, malformed };
+}
+
+async function defaultRunCodeRabbit({ projectRoot, base, baseCommit }, exec = execFileSync) {
+  try {
+    const output = exec('coderabbit', ['review', '--agent', '--base', baseCommit || base], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      timeout: 180_000,
+      maxBuffer: 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    const { events, malformed } = parseCodeRabbitEvents(output);
+    const terminal = events.at(-1);
+    const terminalValid = terminal?.type === 'complete'
+      && ['review_completed', 'review_skipped'].includes(terminal.status)
+      && Number.isSafeInteger(terminal.findings) && terminal.findings >= 0;
+    const findingEvents = events.filter(event => event.type === 'finding');
+    const errorEvents = events.filter(event => event.type === 'error');
+    const clean = !malformed && terminalValid && terminal.findings === 0
+      && findingEvents.length === 0 && errorEvents.length === 0;
+    const findings = findingEvents.slice(0, MAX_FINDINGS).map(event => String(
+      event.codegenInstructions || event.message || 'CodeRabbit finding',
+    ).slice(0, MAX_FINDING_CHARS));
+    if (!clean && findings.length === 0) {
+      let detail = `CodeRabbit reported ${terminal?.findings || errorEvents.length} finding(s)`;
+      if (malformed || !terminalValid) {
+        detail = 'CodeRabbit agent output was malformed or incomplete';
+      }
+      findings.push(detail);
+    }
+    return {
+      ok: clean,
+      summary: clean ? 'local review completed with no findings' : `${findings.length} local review finding(s)`,
+      findings: clean ? [] : findings,
+    };
+  } catch (error) {
+    const output = `${error?.stdout || ''}\n${error?.stderr || ''}`;
+    const findings = boundedLines(output);
+    if (/unauthori[sz]ed|authentication|not authenticated|log in|login required/i.test(output)) {
+      return { ok: false, unavailable: true, summary: 'CLI authentication unavailable', findings: [] };
+    }
+    return {
+      ok: false,
+      summary: findings[0] || 'local review failed',
+      findings,
+    };
+  }
+}
+
+async function defaultRunDeterministic({ projectRoot, base, baseCommit, baseRef: resolvedBaseRef }, exec = execFileSync) {
+  const baseRef = baseCommit || resolvedBaseRef || (String(base || '').startsWith('origin/')
+    ? String(base)
+    : `origin/${String(base || '')}`);
+  return preflightCommand.handler([], {}, projectRoot, {
+    log: () => {},
+    resolveChangeSet: ({ runAll }) => preflightCommand.resolveChangeSet(exec, { runAll, baseRef }),
+  });
+}
+
+async function defaultResolveBaseCommit({ projectRoot, base, baseRef }, exec = execFileSync) {
+  const ref = baseRef || (String(base || '').startsWith('origin/')
+    ? String(base)
+    : `origin/${String(base || '')}`);
+  const resolved = String(exec('git', ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], {
+    cwd: projectRoot,
+    encoding: 'utf8',
+    timeout: 10_000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+  }) || '').trim().toLowerCase();
+  if (!/^[0-9a-f]{40}$/.test(resolved)) throw new Error(`PR base commit is unavailable for ${ref}`);
+  return resolved;
+}
+
+function providerResult(status, ok, summary, findings = []) {
+  return { status, ok, summary, findings: findings.slice(0, MAX_FINDINGS) };
+}
+
+function deterministicFindings(results) {
+  return (Array.isArray(results) ? results : [])
+    .filter(result => result?.ok === false && !result.skipped)
+    .slice(0, MAX_FINDINGS)
+    .map(result => ({
+      provider: String(result.name || 'deterministic-gate').slice(0, 80),
+      detail: String(result.summary || 'gate failed').slice(0, MAX_FINDING_CHARS),
+    }));
+}
+
+function notApplicableResult(context) {
+  const expectedHead = typeof context.expectedHead === 'string'
+    && /^[0-9a-f]{40}$/i.test(context.expectedHead) ? context.expectedHead.toLowerCase() : null;
+  const localHead = typeof context.localHead === 'string' ? context.localHead.toLowerCase() : null;
+  const exactHeadAvailable = expectedHead !== null;
+  const exactHeadCheckedOut = exactHeadAvailable && localHead === expectedHead;
+  if (exactHeadCheckedOut && context.cleanTree === true) return null;
+  const dirtyCheckout = exactHeadCheckedOut && context.cleanTree !== true;
+  const summary = dirtyCheckout
+    ? 'local checkout has uncommitted changes'
+    : (exactHeadAvailable ? 'local checkout is not the PR head' : 'PR head is unavailable');
+  return {
+    status: 'INCOMPLETE',
+    blocking: true,
+    providers: {
+      coderabbit: providerResult(
+        'NOT_APPLICABLE',
+        false,
+        summary,
+      ),
+      deterministic: { status: 'NOT_APPLICABLE', ok: false, results: [] },
+    },
+    findings: [{ provider: 'local-preflight', detail: summary }],
+  };
+}
+
+async function codeRabbitResult(context, probeCodeRabbit, runCodeRabbit) {
+  const probe = await probeCodeRabbit(context);
+  if (probe?.available !== true) {
+    return providerResult('UNAVAILABLE', false, probe?.reason || 'CLI unavailable');
+  }
+  const review = await runCodeRabbit(context);
+  if (review?.unavailable === true) {
+    return providerResult('UNAVAILABLE', false, review.summary || 'CLI unavailable');
+  }
+  return providerResult(
+    review?.ok === true ? 'PASS' : 'FAIL',
+    review?.ok === true,
+    review?.summary || 'local review completed',
+    Array.isArray(review?.findings) ? review.findings : [],
+  );
+}
+
+async function deterministicResult(context, runDeterministic) {
+  try {
+    return await runDeterministic(context);
+  } catch (error) {
+    return { success: false, results: [], reason: error?.message || String(error) };
+  }
+}
+
+async function runLocalReviewPreflight(context, deps = {}) {
+  const probeCodeRabbit = deps.probeCodeRabbit || defaultProbeCodeRabbit;
+  const runCodeRabbit = deps.runCodeRabbit || defaultRunCodeRabbit;
+  const runDeterministic = deps.runDeterministic || defaultRunDeterministic;
+
+  const notApplicable = notApplicableResult(context);
+  if (notApplicable) return notApplicable;
+
+  let reviewContext = context;
+  const suppliedBaseCommit = typeof context.baseCommit === 'string'
+    && /^[0-9a-f]{40}$/i.test(context.baseCommit);
+  const shouldResolveBase = deps.resolveBaseCommit !== false && !suppliedBaseCommit;
+  if (shouldResolveBase) {
+    const resolveBaseCommit = typeof deps.resolveBaseCommit === 'function'
+      ? deps.resolveBaseCommit
+      : defaultResolveBaseCommit;
+    try {
+      const baseCommit = String(await resolveBaseCommit(context) || '').trim().toLowerCase();
+      if (!/^[0-9a-f]{40}$/.test(baseCommit)) throw new Error('PR base commit resolver returned an invalid commit');
+      reviewContext = { ...context, baseCommit };
+    } catch (error) {
+      const detail = error?.message || String(error);
+      return {
+        status: 'INCOMPLETE',
+        blocking: true,
+        providers: {
+          coderabbit: providerResult('NOT_APPLICABLE', false, detail),
+          deterministic: { status: 'NOT_APPLICABLE', ok: false, results: [] },
+        },
+        findings: [{ provider: 'local-preflight', detail }],
+      };
+    }
+  } else if (suppliedBaseCommit) {
+    reviewContext = { ...context, baseCommit: context.baseCommit.toLowerCase() };
+  }
+
+  const coderabbit = await codeRabbitResult(reviewContext, probeCodeRabbit, runCodeRabbit);
+  const deterministic = await deterministicResult(reviewContext, runDeterministic);
+  const gateResults = Array.isArray(deterministic?.results) ? deterministic.results : [];
+  const deterministicOk = deterministic?.success === true;
+  const findings = [
+    ...coderabbit.findings.map(detail => ({ provider: 'coderabbit', detail })),
+    ...deterministicFindings(gateResults),
+  ].slice(0, MAX_FINDINGS);
+  if (!deterministicOk && findings.length === 0) {
+    findings.push({
+      provider: 'deterministic-gates',
+      detail: String(deterministic?.reason || 'preflight failed').slice(0, MAX_FINDING_CHARS),
+    });
+  }
+
+  const failed = !deterministicOk || coderabbit.status === 'FAIL';
+  const incomplete = coderabbit.status === 'UNAVAILABLE';
+  const blocking = failed || incomplete;
+  let status = 'PASS';
+  if (failed) status = 'FAIL';
+  else if (incomplete) status = 'INCOMPLETE';
+  return {
+    status,
+    blocking,
+    providers: {
+      coderabbit,
+      deterministic: {
+        status: deterministicOk ? 'PASS' : 'FAIL',
+        ok: deterministicOk,
+        results: gateResults,
+      },
+    },
+    findings,
+  };
+}
+
+module.exports = {
+  MAX_FINDINGS,
+  boundedLines,
+  defaultProbeCodeRabbit,
+  defaultResolveBaseCommit,
+  defaultRunCodeRabbit,
+  defaultRunDeterministic,
+  runLocalReviewPreflight,
+};

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

@@ -16,11 +16,12 @@
  * one lock. This module is the lease PRIMITIVE only: pure fs + I/O, no spawned
  * process and no reconcile loop (the daemon wires those up later).
  *
- * Payload JSON: `{ pid, token, startedAt, heartbeatAt, watchers: [prNumbers] }`.
+ * Payload JSON: `{ pid, token, startedAt, heartbeatAt }`.
+ * Per-PR watcher authority lives only in Kernel owner rows.
  *
  * ## Ownership is by TOKEN, not pid
  * Each successful `acquire` mints a unique `token`. Every mutating op
- * (`stamp`/`updateWatchers`/`release`) verifies that token against the on-disk
+ * (`stamp`/`release`) verifies that token against the on-disk
  * lock before writing. A pid can be reused after a crash/reboot, and a wedged
  * owner can revive after its lease was reclaimed — in both cases the token no
  * longer matches, so the superseded holder can never resurrect or mutate a lease
@@ -128,6 +129,9 @@ function tryExclusiveCreate(file, payload) {
  *   -> { ok:true, file, token, reclaimed }   stale lock (dead/wedged owner) reclaimed
  *   -> { ok:false, held }                    a LIVE, FRESH foreign owner holds it
  *   -> { ok:false, held }                    we lost the atomic takeover race
+ *   -> { ok:false, held:null, legacyMigrationPending:true, reason:'legacy-lease-unreadable' }
+ *                                            the lock exists but cannot be parsed —
+ *                                            never reclaimed, never deleted here
  *
  * `pid`/`isAlive`/`now`/`token` are injectable for testing. `onBeforeTakeover` is
  * a test seam invoked AFTER the stale lock is removed and BEFORE our exclusive
@@ -141,11 +145,12 @@ function acquire(projectRoot, {
   now = () => Date.now(),
   token = crypto.randomUUID(),
   onBeforeTakeover = null,
+  preserveLegacy = false,
 } = {}) {
   const file = lockFilePath(projectRoot, { gitCommonDir });
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const iso = new Date(now()).toISOString();
-  const payload = { pid, token, startedAt: iso, heartbeatAt: iso, watchers: [] };
+  const payload = { pid, token, startedAt: iso, heartbeatAt: iso };
 
   // Fast path: atomic exclusive create. Only ONE caller can win O_EXCL.
   if (tryExclusiveCreate(file, payload)) {
@@ -158,15 +163,33 @@ function acquire(projectRoot, {
     return { ok: false, held };
   }
 
+  // NO caller may discard an unreadable lease: its bytes may be the only
+  // evidence of legacy watchers, and the daemon acquires HERE but migrates
+  // LATER — so an opt-in guard would still delete that evidence before
+  // migration could read it. This is unconditional at the shared acquisition
+  // boundary: fail closed, leave the bytes exactly as found, and surface a
+  // reason a caller can act on. Recovery belongs to migration, never to
+  // acquisition.
+  if (fs.existsSync(file) && !held) {
+    return {
+      ok: false, held: null, legacyMigrationPending: true, reason: 'legacy-lease-unreadable',
+    };
+  }
+
+  if (preserveLegacy && Array.isArray(held?.watchers)) {
+    return { ok: false, held, legacyMigrationPending: true };
+  }
+
   // Stale (dead/wedged owner, unreadable, or already ours). Take over ATOMICALLY:
   // remove the stale lock, then re-create it with O_EXCL. If a competitor
   // recreated it first, our exclusive create fails (EEXIST) and we back off — so
   // two racers reclaiming the same stale lock can NEVER both win. A wedged owner
   // that revives after we delete its lock is stopped by the per-lease `token`
-  // guard on stamp()/updateWatchers()/release(), never able to resurrect it here.
+  // guard on stamp()/release(), never able to resurrect it here.
   fs.rmSync(file, { force: true });
   if (typeof onBeforeTakeover === 'function') onBeforeTakeover();
-  if (!tryExclusiveCreate(file, payload)) {
+  const takeoverPayload = Array.isArray(held?.watchers) ? { ...payload, watchers: held.watchers } : payload;
+  if (!tryExclusiveCreate(file, takeoverPayload)) {
     return { ok: false, held: readLock(file) };
   }
   return { ok: true, file, token, reclaimed: true };
@@ -203,19 +226,6 @@ function stopHeartbeat(timer) {
   if (timer) clearInterval(timer);
 }
 
-/**
- * Rewrite the `watchers[]` array on OUR lock. Returns false when the lock is
- * missing or NOT ours by `token`.
- */
-function updateWatchers(projectRoot, prNumbers, { gitCommonDir, token, pid = process.pid } = {}) {
-  const file = lockFilePath(projectRoot, { gitCommonDir });
-  const held = readLock(file);
-  if (!held || !ownsLock(held, { token, pid })) return false;
-  held.watchers = Array.isArray(prNumbers) ? prNumbers : [];
-  writeLock(file, held);
-  return true;
-}
-
 /**
  * Release the lease — delete the lock ONLY when it is ours by `token`, so a
  * foreign or already-reclaimed lock is never removed out from under its owner
@@ -246,7 +256,6 @@ module.exports = {
   stamp,
   startHeartbeat,
   stopHeartbeat,
-  updateWatchers,
   release,
   owns,
 };