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

package/lib/pr-monitor/gather.js

@@ -17,6 +17,16 @@
 
 const { gatherPrSnapshot } = require('../pr-pull');
 const { isFailed, isGreen } = require('../pr-shepherd');
+const { classifyReviewActor, normalizeEvidenceText } = require('../review-adapter');
+
+const SNAPSHOT_LIMITS = Object.freeze({
+  maxChecks: 100,
+  maxThreads: 100,
+  maxReviews: 100,
+  maxComments: 100,
+  maxDegraded: 32,
+  maxTextChars: 256,
+});
 
 /** green | failed | pending — reuses the SAME predicates as the verdict core. */
 function classifyCheck(check) {
@@ -25,45 +35,200 @@ function classifyCheck(check) {
   return 'pending';
 }
 
-function normalizeChecks(checks) {
-  return (Array.isArray(checks) ? checks : []).map((c) => ({
-    name: c.name || '',
-    class: classifyCheck(c),
-  }));
+function compareBy(field) {
+  return (left, right) => {
+    const a = String(left[field] ?? '');
+    const b = String(right[field] ?? '');
+    if (a < b) return -1;
+    if (a > b) return 1;
+    return 0;
+  };
+}
+
+function evidenceText(value) {
+  return normalizeEvidenceText(value, { maxChars: SNAPSHOT_LIMITS.maxTextChars });
+}
+
+function identifiedSurface(value) {
+  if (typeof value === 'string' && value.trim()) return value;
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return value.source || value.surface || null;
+  }
+  return null;
+}
+
+function addIdentifiedSurface(value, add, error) {
+  const surface = identifiedSurface(value);
+  if (surface) add(surface, error);
+}
+
+function createEvidenceAdder(degraded, incompleteSurfaces) {
+  return (surface, error) => {
+    const safeSurface = evidenceText(surface) || 'unknown';
+    const safeError = evidenceText(error) || 'evidence unavailable';
+    incompleteSurfaces.add(safeSurface);
+    if (!degraded.some((item) => item.surface === safeSurface && item.error === safeError)
+      && degraded.length < SNAPSHOT_LIMITS.maxDegraded) {
+      degraded.push({ surface: safeSurface, error: safeError });
+    }
+  };
+}
+
+function trackDegradedItem(item, add) {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) {
+    add('degraded', 'degraded evidence item is malformed');
+    addIdentifiedSurface(item, add, 'degraded evidence metadata is malformed');
+    return;
+  }
+  add(item.source || item.surface || 'unknown', item.error || 'evidence unavailable');
+}
+
+function trackInitialDegraded(initialDegraded, add) {
+  if (!Array.isArray(initialDegraded)) {
+    add('degraded', 'degraded evidence is malformed');
+    addIdentifiedSurface(initialDegraded, add, 'degraded evidence metadata is malformed');
+    return;
+  }
+  for (const item of initialDegraded.slice(0, SNAPSHOT_LIMITS.maxDegraded)) {
+    trackDegradedItem(item, add);
+  }
+  if (initialDegraded.length > SNAPSHOT_LIMITS.maxDegraded) {
+    add('degraded', 'degraded evidence exceeded item limit');
+  }
 }
 
-function normalizeThreads(threads) {
-  return (Array.isArray(threads) ? threads : []).map((t) => ({
-    threadId: t.threadId || '',
-    isResolved: Boolean(t.isResolved),
-    isOutdated: Boolean(t.isOutdated),
-    commentCount: Array.isArray(t.comments) ? t.comments.length : 0,
-    actionable: !t.isResolved && !t.isOutdated,
-    path: t.path || null,
-  }));
+function createEvidenceTracker(initialDegraded) {
+  const degraded = [];
+  const incompleteSurfaces = new Set();
+  const add = createEvidenceAdder(degraded, incompleteSurfaces);
+  trackInitialDegraded(initialDegraded, add);
+  return { add, degraded, incompleteSurfaces };
 }
 
-function normalizeReviews(reviews) {
-  return (Array.isArray(reviews) ? reviews : []).map((r) => ({
-    author: r.author || '',
-    state: r.state || '',
-    commitOid: r.commitOid || null,
-    submittedAt: r.submittedAt || null,
-  }));
+function trackUnreadable(value, tracker) {
+  if (!Array.isArray(value)) {
+    tracker.add('unreadable', 'unreadable evidence is malformed');
+    const surface = identifiedSurface(value);
+    if (surface) tracker.add(surface, 'unreadable evidence metadata is malformed');
+    return;
+  }
+  for (const item of value) {
+    if (typeof item === 'string' && item.trim()) {
+      tracker.add(item, 'provider read was incomplete');
+    } else {
+      tracker.add('unreadable', 'unreadable evidence item is malformed');
+      const surface = identifiedSurface(item);
+      if (surface) tracker.add(surface, 'unreadable evidence metadata is malformed');
+    }
+  }
 }
 
-function normalizeComments(comments) {
-  return (Array.isArray(comments) ? comments : []).map((c) => ({
-    id: c.id || `${c.author || ''}:${c.createdAt || ''}`,
-    author: c.author || '',
-  }));
+function boundedNormalize(value, { surface, limit, normalize, tracker, sortField }) {
+  if (!Array.isArray(value)) {
+    tracker.add(surface, `${surface} evidence is missing or malformed`);
+    return [];
+  }
+  if (value.length > limit) tracker.add(surface, `${surface} evidence exceeded ${limit} item limit`);
+  const output = [];
+  for (const item of value.slice(0, limit)) {
+    try {
+      output.push(normalize(item));
+    } catch (_error) {
+      tracker.add(surface, `${surface} evidence item is malformed`);
+    }
+  }
+  return output.sort(compareBy(sortField));
 }
 
-function normalizeDegraded(degraded) {
-  return (Array.isArray(degraded) ? degraded : []).map((d) => ({
-    surface: d.source || d.surface || 'unknown',
-    error: d.error || '',
-  }));
+function normalizeChecks(checks, tracker) {
+  return boundedNormalize(checks, {
+    surface: 'checks',
+    limit: SNAPSHOT_LIMITS.maxChecks,
+    tracker,
+    sortField: 'name',
+    normalize: (check) => {
+      if (!check || typeof check !== 'object' || Array.isArray(check)
+        || typeof check.name !== 'string' || !check.name.trim()
+        || (typeof check.status !== 'string' && typeof check.conclusion !== 'string')) {
+        throw new TypeError('malformed check');
+      }
+      return { name: evidenceText(check.name), class: classifyCheck(check) };
+    },
+  });
+}
+
+function normalizeActor(value) {
+  const author = evidenceText(value.author);
+  const actorKind = classifyReviewActor(value);
+  if (!author || actorKind === 'unknown') throw new TypeError('malformed actor');
+  return { author, actorKind };
+}
+
+function normalizeThreads(threads, tracker) {
+  return boundedNormalize(threads, {
+    surface: 'threads',
+    limit: SNAPSHOT_LIMITS.maxThreads,
+    tracker,
+    sortField: 'threadId',
+    normalize: (thread) => {
+      if (!thread || typeof thread !== 'object' || Array.isArray(thread)
+        || typeof thread.threadId !== 'string' || !thread.threadId
+        || typeof thread.isResolved !== 'boolean'
+        || typeof thread.isOutdated !== 'boolean'
+        || !Array.isArray(thread.comments) || thread.comments.length === 0
+        || (thread.path !== null && thread.path !== undefined && typeof thread.path !== 'string')) {
+        throw new TypeError('malformed thread');
+      }
+      const actor = normalizeActor(thread.comments[0]);
+      return {
+        threadId: evidenceText(thread.threadId),
+        isResolved: thread.isResolved,
+        isOutdated: thread.isOutdated,
+        commentCount: thread.comments.length,
+        actionable: !thread.isResolved && !thread.isOutdated,
+        path: thread.path ? evidenceText(thread.path) : null,
+        ...actor,
+      };
+    },
+  });
+}
+
+function normalizeReviews(reviews, tracker) {
+  return boundedNormalize(reviews, {
+    surface: 'reviews',
+    limit: SNAPSHOT_LIMITS.maxReviews,
+    tracker,
+    sortField: 'author',
+    normalize: (review) => {
+      if (!review || typeof review !== 'object' || Array.isArray(review)
+        || typeof review.state !== 'string' || !review.state) {
+        throw new TypeError('malformed review');
+      }
+      const actor = normalizeActor(review);
+      return {
+        ...actor,
+        state: evidenceText(review.state),
+        commitOid: review.commitOid == null ? null : evidenceText(review.commitOid),
+        submittedAt: review.submittedAt == null ? null : evidenceText(review.submittedAt),
+      };
+    },
+  });
+}
+
+function normalizeComments(comments, tracker) {
+  return boundedNormalize(comments, {
+    surface: 'comments',
+    limit: SNAPSHOT_LIMITS.maxComments,
+    tracker,
+    sortField: 'id',
+    normalize: (comment) => {
+      if (!comment || typeof comment !== 'object' || Array.isArray(comment)
+        || typeof comment.id !== 'string' || !comment.id) {
+        throw new TypeError('malformed comment');
+      }
+      return { id: evidenceText(comment.id), ...normalizeActor(comment) };
+    },
+  });
 }
 
 /**
@@ -76,6 +241,30 @@ function conflictBool(conflicts) {
   return null;
 }
 
+function objectOrEmpty(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function createSnapshotTracker(source, state) {
+  const tracker = createEvidenceTracker(Object.hasOwn(source, 'degraded') ? source.degraded : []);
+  if (state !== source.state) tracker.add('state', 'PR state evidence is missing or malformed');
+  if (Object.hasOwn(source, 'unreadable')) trackUnreadable(source.unreadable, tracker);
+  return tracker;
+}
+
+function normalizeBehind(source, tracker) {
+  const behind = Number.isSafeInteger(source.behind) && source.behind >= 0 ? source.behind : 0;
+  if (behind !== source.behind && source.behind !== undefined) {
+    tracker.add('branch', 'branch divergence evidence is malformed');
+  }
+  return behind;
+}
+
+function deriveThreadState(tracker, openThreadCount) {
+  if (tracker.incompleteSurfaces.has('threads')) return 'INCOMPLETE';
+  return openThreadCount > 0 ? 'OPEN' : 'ZERO';
+}
+
 /**
  * Normalize a raw `gatherPrSnapshot` result into the monitor diff subject.
  *
@@ -84,21 +273,38 @@ function conflictBool(conflicts) {
  * @returns {object}
  */
 function normalizeSnapshot(snap, ctx) {
-  const state = snap.state || {};
+  const source = objectOrEmpty(snap);
+  const state = objectOrEmpty(source.state);
+  const tracker = createSnapshotTracker(source, state);
+  const checks = normalizeChecks(state.checks, tracker);
+  const threads = normalizeThreads(source.threads, tracker);
+  const reviews = normalizeReviews(source.reviews, tracker);
+  const comments = normalizeComments(source.issueComments, tracker);
+  const behind = normalizeBehind(source, tracker);
+  const openThreadCount = threads.filter((thread) => thread.actionable).length;
+  const evidenceStatus = tracker.degraded.length === 0 ? 'COMPLETE' : 'INCOMPLETE';
+  const threadState = deriveThreadState(tracker, openThreadCount);
+  const degraded = [...tracker.degraded].sort(compareBy('surface'));
   return {
-    repo: ctx.repo,
-    pr: String(ctx.pr),
-    headSha: state.headSha || '',
+    repo: evidenceText(ctx?.repo),
+    pr: evidenceText(ctx?.pr),
+    headSha: evidenceText(state.headSha),
     prState: String(state.state || 'OPEN').toUpperCase(),
-    draft: Boolean(snap.draft),
-    verdict: { state: snap.verdict || 'UNKNOWN', reason: null },
-    checks: normalizeChecks(state.checks),
-    threads: normalizeThreads(snap.threads),
-    reviews: normalizeReviews(snap.reviews),
-    comments: normalizeComments(snap.issueComments),
-    behind: snap.behind || 0,
-    conflicts: conflictBool(snap.conflicts),
-    degraded: normalizeDegraded(snap.degraded),
+    draft: Boolean(source.draft),
+    verdict: {
+      state: evidenceStatus === 'COMPLETE' ? (source.verdict || 'UNKNOWN') : 'UNKNOWN',
+      reason: evidenceStatus === 'COMPLETE' ? null : 'review evidence incomplete',
+    },
+    evidenceStatus,
+    threadState,
+    openThreadCount,
+    checks,
+    threads,
+    reviews,
+    comments,
+    behind,
+    conflicts: conflictBool(source.conflicts),
+    degraded,
   };
 }
 
@@ -117,6 +323,7 @@ async function gatherMonitorSnapshot(ctx) {
 }
 
 module.exports = {
+  SNAPSHOT_LIMITS,
   gatherMonitorSnapshot,
   normalizeSnapshot,
   classifyCheck,

package/lib/pr-monitor/journal.js

@@ -35,21 +35,35 @@ function sanitize(part) {
   return String(part || '').replace(/[^A-Za-z0-9._-]+/g, '-');
 }
 
+/**
+ * Resolve the one journal authority shared by every worktree. Standard repos
+ * use `<main-root>/.forge/pr-monitor`; a nonstandard common dir centralizes
+ * beneath that shared metadata directory. No common dir preserves legacy use.
+ */
+function resolveJournalRoot({ root, gitCommonDir }) {
+  const fallbackRoot = path.resolve(root);
+  if (!gitCommonDir) return path.join(fallbackRoot, '.forge', 'pr-monitor');
+  const commonDir = path.resolve(gitCommonDir);
+  if (path.basename(commonDir).toLowerCase() === '.git') {
+    return path.join(path.dirname(commonDir), '.forge', 'pr-monitor');
+  }
+  return path.join(commonDir, 'forge', 'pr-monitor');
+}
+
 /**
  * Resolve (and create) the per-PR journal directory.
  *
  * @param {{ root: string, repo: string, pr: string|number }} ctx
  * @returns {string} absolute directory path
  */
-function journalDir({ root, repo, pr }) {
-  const dir = path.join(root, '.forge', 'pr-monitor', `${sanitize(repo)}-${sanitize(pr)}`);
+function journalDir({ root, gitCommonDir, repo, pr }) {
+  const dir = path.join(resolveJournalRoot({ root, gitCommonDir }), `${sanitize(repo)}-${sanitize(pr)}`);
   fs.mkdirSync(dir, { recursive: true });
   return dir;
 }
 
 function journalPath(dir) { return path.join(dir, 'events.ndjson'); }
 function snapshotPath(dir) { return path.join(dir, 'snapshot.json'); }
-function pidPath(dir) { return path.join(dir, 'watch.pid'); }
 function lockPath(dir) { return path.join(dir, 'journal.lock'); }
 
 /**
@@ -239,49 +253,18 @@ async function withJournalLock(dir, fn, opts = {}) {
   }
 }
 
-/** Write the watcher pid file. */
-function writePid(dir, pid) {
-  fs.writeFileSync(pidPath(dir), String(pid == null ? process.pid : pid));
-}
-
-/** Read the watcher pid (number) or null. */
-function readPid(dir) {
-  const file = pidPath(dir);
-  if (!fs.existsSync(file)) return null;
-  const n = Number.parseInt(fs.readFileSync(file, 'utf8').trim(), 10);
-  return Number.isFinite(n) ? n : null;
-}
-
-/** Remove the watcher pid file (best-effort). */
-function removePid(dir) {
-  try { fs.unlinkSync(pidPath(dir)); } catch { /* already gone */ }
-}
-
 /** Is `pid` a live process? `process.kill(pid, 0)` probes without signaling. */
 function pidAlive(pid) {
   if (!pid) return false;
   try { process.kill(pid, 0); return true; } catch (err) { return err?.code === 'EPERM'; }
 }
 
-/**
- * A watcher is "running" when the pid file names a live process that is NOT us.
- * Stale pid files (dead process) return false so a poll falls back to an inline
- * pass.
- *
- * @param {string} dir
- * @returns {boolean}
- */
-function watcherRunning(dir) {
-  const pid = readPid(dir);
-  return pidAlive(pid) && pid !== process.pid;
-}
-
 module.exports = {
   sanitize,
+  resolveJournalRoot,
   journalDir,
   journalPath,
   snapshotPath,
-  pidPath,
   lockPath,
   withJournalLock,
   readAllEvents,
@@ -291,9 +274,5 @@ module.exports = {
   appendEvents,
   readSnapshot,
   writeSnapshot,
-  writePid,
-  readPid,
-  removePid,
   pidAlive,
-  watcherRunning,
 };

package/lib/pr-monitor/monitor.js

@@ -11,6 +11,10 @@
 const { finalizeEvent, eventIdentity, fingerprint } = require('./events');
 const { diffSnapshots } = require('./differ');
 const journal = require('./journal');
+const { launchGateComplete } = require('./watch-lifecycle');
+
+const MAX_EVENT_DELTAS = 128;
+const ACTIVE_OWNER_PHASES = new Set(['starting', 'running', 'stop_requested', 'terminal_pending']);
 
 /** ISO-8601 timestamp; injectable via ctx.now for deterministic tests. */
 function defaultNow() { return new Date().toISOString(); }
@@ -37,6 +41,35 @@ function finalizeRecords(candidates, { baseSeq, ts, snapshot }) {
   }));
 }
 
+function createCompatibilityAppender(dir) {
+  const deliveredIds = new Set(journal.readAllEvents(dir)
+    .map(event => event.memoryEventId).filter(Boolean));
+  const snapshotRecord = journal.readSnapshot(dir);
+  const appliedSeq = snapshotRecord?.appliedSeq || 0;
+  const seen = journal.seenIdentities(dir, appliedSeq);
+  const journalCursor = journal.lastSeq(dir);
+  let nextSeq = journalCursor;
+  return {
+    journalCursor,
+    append(record, memoryEventId) {
+      const identity = eventIdentity(record);
+      if ((memoryEventId && deliveredIds.has(memoryEventId)) || seen.has(identity)) return;
+      nextSeq += 1;
+      journal.appendEvents(dir, [{ ...record, seq: nextSeq, ...(memoryEventId ? { memoryEventId } : {}) }]);
+      if (memoryEventId) deliveredIds.add(memoryEventId);
+      seen.add(identity);
+    },
+    finish(snapshot) {
+      if (!snapshot) return;
+      journal.writeSnapshot(dir, {
+        snapshot,
+        fingerprint: fingerprint(snapshot),
+        appliedSeq: nextSeq,
+      });
+    },
+  };
+}
+
 /**
  * The read→diff→dedup→sequence→append→snapshot critical section of a single
  * pass. Runs ONLY while holding the journal lock (see `runMonitorPass`), so it
@@ -105,12 +138,40 @@ async function runMonitorPassLocked(ctx) {
  * @returns {Promise<{ events: object[], changed: boolean, fingerprint: string }>}
  */
 async function runMonitorPass(ctx) {
-  return journal.withJournalLock(ctx.dir, () => runMonitorPassLocked(ctx), ctx.lockOpts);
+  if (ctx.store) {
+    const { runFlowMonitorPass } = require('./flow-monitor');
+    return journal.withJournalLock(ctx.dir, async () => {
+      let latestSnapshot;
+      const compatibility = createCompatibilityAppender(ctx.dir);
+      const deliverLegacy = ctx.deliverLegacy || (async (record, memoryEventId) => {
+        compatibility.append(record, memoryEventId);
+      });
+      const result = await runFlowMonitorPass({
+        ...ctx,
+        gather: async () => {
+          const snapshot = await ctx.gather();
+          latestSnapshot = snapshot;
+          return snapshot;
+        },
+        deliverLegacy,
+      });
+      if (!ctx.deliverLegacy) compatibility.finish(latestSnapshot);
+      return { ...result, journalCursor: compatibility.journalCursor };
+    }, ctx.lockOpts);
+  }
+  return journal.withJournalLock(ctx.dir, async () => {
+    const journalCursor = journal.lastSeq(ctx.dir);
+    const result = await runMonitorPassLocked(ctx);
+    return { ...result, journalCursor };
+  }, ctx.lockOpts);
 }
 
 /**
- * `forge shepherd events <pr> --since <seq>` core: run one inline pass when no
- * watcher owns this PR, then return every journaled event with `seq > since`.
+ * `forge shepherd events <pr> --since <seq>` core: run one inline pass when the
+ * Kernel owner row proves no watcher owns this PR AND the shared migration gate
+ * proves EXACTLY complete, then return every journaled
+ * event with `seq > since`. PID files are compatibility evidence only and are
+ * never consulted for this decision.
  * This is the agent-agnostic PULL surface — stdout NDJSON, nothing under .claude.
  *
  * @param {object} ctx
@@ -118,22 +179,67 @@ async function runMonitorPass(ctx) {
  * @param {() => Promise<object>} ctx.gather
  * @param {number} [ctx.since]
  * @param {() => string} [ctx.now]
- * @param {(dir: string) => boolean} [ctx.watcherRunning]
  * @param {(records: object[]) => Promise<void>|void} [ctx.enrich]
- * @returns {Promise<{ events: object[], since: number, ranPass: boolean }>}
+ * @returns {Promise<{ events: object[], since: number, ranPass: boolean,
+ *   migrationGateIncomplete?: boolean }>}
  */
 async function pollEvents(ctx) {
   const { dir, gather, since = 0 } = ctx;
-  const isRunning = (ctx.watcherRunning || journal.watcherRunning)(dir);
+  const checkOwner = typeof ctx.isOwnerRunning === 'function'
+    ? ctx.isOwnerRunning
+    : (ctx.owner && typeof ctx.owner.readOwner === 'function' && ctx.repo && Number(ctx.pr) > 0
+      ? async () => {
+        const result = await ctx.owner.readOwner(
+          { repo: ctx.repo, pr: Number(ctx.pr) },
+          ctx.ownerOptions || {},
+        );
+        if (!result?.ok) return { ok: false, reason: result?.reason || 'authority_unavailable' };
+        const record = result.record;
+		return record != null && (ACTIVE_OWNER_PHASES.has(record.phase) || record.phase === 'blocked');
+      }
+      : null);
+  let authorityUnavailable = typeof checkOwner !== 'function';
+  let isRunning = true;
+  if (!authorityUnavailable) {
+    try {
+      const result = await checkOwner();
+      authorityUnavailable = result && typeof result === 'object' && result.ok === false;
+      isRunning = authorityUnavailable ? true : result === true || result?.running === true;
+    } catch {
+      authorityUnavailable = true;
+      isRunning = true;
+    }
+  }
   let ranPass = false;
-  if (!isRunning) {
-    await runMonitorPass({ dir, gather, now: ctx.now, enrich: ctx.enrich });
-    ranPass = true;
+  let pass = null;
+  // An idle owner row is necessary but NOT sufficient: until the lease/owner
+  // migration gate is EXACTLY `complete`, legacy watchers may still be running
+  // outside Kernel authority, so an inline pass could duplicate one. Reuse the
+  // one shared predicate every launcher uses (`launchGateComplete`) rather than
+  // re-deriving "not blocked" here — partial, unknown and unreadable all fail closed.
+  let migrationGateIncomplete = false;
+  if (!authorityUnavailable && !isRunning) {
+    if (await launchGateComplete(ctx.owner || undefined, ctx.ownerOptions || {})) {
+      pass = await runMonitorPass({ ...ctx, dir, gather, now: ctx.now, enrich: ctx.enrich });
+      ranPass = true;
+    } else {
+      migrationGateIncomplete = true;
+    }
   }
+  const readEventsSince = ctx.readEventsSince || journal.readEventsSince;
+  const available = readEventsSince(dir, since);
+  const overflow = available.length > MAX_EVENT_DELTAS;
+  const events = overflow ? available.slice(-MAX_EVENT_DELTAS) : available;
   return {
-    events: journal.readEventsSince(dir, since),
+    events,
     since: Number(since) || 0,
     ranPass,
+    ...(authorityUnavailable ? { authorityUnavailable: true } : {}),
+    ...(migrationGateIncomplete ? { migrationGateIncomplete: true } : {}),
+    overflow,
+    receiptIds: Array.isArray(pass?.receiptIds) ? pass.receiptIds.slice(0, MAX_EVENT_DELTAS) : [],
+    continuationPending: pass?.continuationPending === true,
+    ...(pass?.terminalReceiptId ? { terminalReceiptId: pass.terminalReceiptId } : {}),
   };
 }
 
@@ -143,4 +249,5 @@ module.exports = {
   dedupeAgainstJournal,
   finalizeRecords,
   defaultNow,
+  MAX_EVENT_DELTAS,
 };