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

package/lib/pr-monitor/watch.js

@@ -15,29 +15,23 @@
  * and only pushed if the next tick did not recover/green it — the JOURNAL still
  * records everything (authority), so `events --since` replay stays complete.
  *
- * Every external effect is injectable (emit/sleep/rng/now/gather/watcherRunning/
- * writePid/removePid, plus `maxPasses`/`signal`) so tests exercise the loop with a
- * fake clock and fake gh, never touching live GitHub or waiting 60s.
+ * Every external effect is injectable (emit/sleep/rng/now/gather/owner authority,
+ * plus `maxPasses`/`signal`) so tests exercise the loop with a fake clock and fake
+ * provider, never touching live GitHub or waiting 60s.
  *
  * @module pr-monitor/watch
  */
 
 const { runMonitorPass } = require('./monitor');
 const journal = require('./journal');
+const watchOwner = require('./watch-owner');
 const { EVENT_TYPES: T } = require('./events');
 
 const DEFAULT_INTERVAL_MS = 60000;
+const DEFAULT_OWNER_HEARTBEAT_MS = 60000;
 const JITTER_RATIO = 0.2;
 const TERMINAL_TYPES = new Set([T.PR_MERGED, T.PR_CLOSED]);
 
-// In-process ownership of the watcher slot, keyed by journal dir. The journal
-// PID file serializes claims ACROSS processes, but it cannot make claims within
-// ONE process idempotent: after writePid, `watcherRunning(dir)` returns false
-// because the PID equals process.pid, so a second same-process watchLoop() would
-// also claim, run in parallel, and (on either exit) remove the shared PID while
-// the other is still active. This Set closes that gap for the loop lifetime.
-const ACTIVE_DIRS = new Set();
-
 /** Default push sink: one NDJSON line per event to stdout. */
 function defaultEmit(event) {
   process.stdout.write(`${JSON.stringify(event)}\n`);
@@ -78,30 +72,6 @@ function isAborted(signal) {
   return Boolean(signal && signal.aborted);
 }
 
-/**
- * Atomically claim the watcher slot for this PR. The `watcherRunning` check and
- * the `writePid` write run TOGETHER inside the cross-process journal lock (so two
- * starts in DIFFERENT processes can never both pass), AND the in-process
- * `ACTIVE_DIRS` guard rejects a SECOND concurrent `watchLoop()` in the SAME
- * process (which the PID file alone misses, since our own PID reads as "not
- * running"). Returns true only when the slot was newly claimed; the caller must
- * release with `releaseClaim(dir)` on loop exit. The (possibly injected)
- * `watcherRunning`/`writePid` primitives are honored, so test injection works.
- */
-function defaultClaim(dir, { watcherRunning, writePid, lockOpts }) {
-  return journal.withJournalLock(dir, () => {
-    if (ACTIVE_DIRS.has(dir) || watcherRunning(dir)) return false;
-    writePid(dir);
-    ACTIVE_DIRS.add(dir);
-    return true;
-  }, lockOpts);
-}
-
-/** Release the in-process watcher claim for `dir` (idempotent). */
-function releaseClaim(dir) {
-  ACTIVE_DIRS.delete(dir);
-}
-
 /**
  * Split a pass's events into: held-candidate failures (by check name), terminal
  * events (pr.merged/closed), and everything else (emitted immediately).
@@ -144,6 +114,20 @@ function confirmHeld(pending, contra, emit) {
   }
 }
 
+function emitTerminalPass(state, events, emit) {
+  const { failures, terminal, others } = partition(events);
+  const contra = contradictions(events);
+  const heldNames = new Set(state.pending.keys());
+  confirmHeld(state.pending, contra, emit);
+  state.pending = new Map();
+  for (const event of others) {
+    if (event.type === T.CHECK_RECOVERED && heldNames.has(checkName(event))) continue;
+    emit(event);
+  }
+  for (const failure of failures.values()) emit(failure);
+  for (const event of terminal) emit(event);
+}
+
 /**
  * Run ONE watch tick: a bounded monitor pass, then stream its events with the
  * 2-pass flap debounce applied. Mutates `state.pending` (the held failures).
@@ -151,10 +135,18 @@ function confirmHeld(pending, contra, emit) {
  * @returns {Promise<{ terminal: boolean }>} terminal=true → stop the loop.
  */
 async function runWatchPass(state, ctx, emit) {
-  const { events } = await runMonitorPass({
-    dir: ctx.dir, gather: ctx.gather, now: ctx.now, enrich: ctx.enrich, lockOpts: ctx.lockOpts,
+  const monitorPass = ctx.runMonitorPass || runMonitorPass;
+  const { events: rawEvents, terminalReceiptId, journalCursor } = await monitorPass({
+    ...ctx, dir: ctx.dir, gather: ctx.gather, now: ctx.now, enrich: ctx.enrich, lockOpts: ctx.lockOpts,
   });
+  const events = ctx.dir && Number.isSafeInteger(journalCursor)
+    ? journal.readEventsSince(ctx.dir, journalCursor)
+    : rawEvents;
   const { failures, terminal, others } = partition(events);
+  if (terminalReceiptId) {
+    emitTerminalPass(state, events, emit);
+    return { terminal: true, terminalReceiptId };
+  }
   const contra = contradictions(events);
   const heldNames = new Set(state.pending.keys());
 
@@ -168,7 +160,7 @@ async function runWatchPass(state, ctx, emit) {
   if (terminal.length) {
     for (const failure of failures.values()) emit(failure);
     for (const t of terminal) emit(t);
-    return { terminal: true };
+    return { terminal: false, receiptUnavailable: true };
   }
   state.pending = failures;
   return { terminal: false };
@@ -192,51 +184,130 @@ async function runWatchPass(state, ctx, emit) {
  * @returns {Promise<{ started: boolean, passes: number, stopped: boolean, reason?: string }>}
  */
 async function watchLoop(ctx) {
-  const { dir } = ctx;
   const emit = ctx.emit || defaultEmit;
   const sleep = ctx.sleep || defaultSleep;
   const rng = ctx.rng || Math.random;
   const intervalMs = ctx.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const ownerHeartbeatMs = ctx.ownerHeartbeatMs ?? DEFAULT_OWNER_HEARTBEAT_MS;
   const maxPasses = ctx.maxPasses ?? Infinity;
-  const watcherRunning = ctx.watcherRunning || journal.watcherRunning;
-  const writePid = ctx.writePid || journal.writePid;
-  const removePid = ctx.removePid || journal.removePid;
-  const claim = ctx.claim || (() => defaultClaim(dir, { watcherRunning, writePid, lockOpts: ctx.lockOpts }));
-
-  // Atomic idempotent claim: a live OTHER watcher already owns this PR → no-op.
-  // The check+write are serialized under the journal lock so concurrent starts
-  // cannot both succeed (see defaultClaim).
-  const claimed = await claim(dir);
-  if (!claimed) {
-    return { started: false, passes: 0, stopped: false, reason: 'watcher-already-running' };
+  const owner = ctx.owner || watchOwner;
+  const ownerOptions = ctx.ownerOptions || {};
+  const identity = { repo: String(ctx.repo || '').toLowerCase(), pr: Number(ctx.pr) };
+  const generation = ctx.generation;
+  const controllerPid = Number(ctx.controllerPid);
+  const pid = Number(ctx.pid ?? process.pid);
+
+  // Exact generation binding makes a duplicate or stale child a clean no-op.
+  if (!Number.isSafeInteger(identity.pr) || identity.pr <= 0 || !identity.repo
+    || !generation || !Number.isSafeInteger(controllerPid) || controllerPid <= 0
+    || !Number.isSafeInteger(pid) || pid <= 0 || typeof owner.bindRunning !== 'function') {
+    return { started: false, passes: 0, stopped: false, reason: 'authority-unavailable' };
+  }
+  const bound = await owner.bindRunning(identity, { generation, controllerPid, pid }, ownerOptions);
+  if (!bound?.ok) {
+    return { started: false, passes: 0, stopped: false, reason: bound?.reason || 'bind-failed' };
   }
 
   const state = { pending: new Map() };
   let passes = 0;
   let stopped = false;
+  let terminalPending = false;
+  let reason;
+  let heartbeatFailure;
+  let heartbeatInFlight = null;
+  const checkpointOwner = () => {
+    if (heartbeatInFlight) return heartbeatInFlight;
+    heartbeatInFlight = (async () => {
+      try {
+        const checkpoint = await owner.heartbeat(identity, { generation, pid }, ownerOptions);
+        if (!checkpoint?.ok) heartbeatFailure = checkpoint?.reason || 'owner-lost';
+      } catch {
+        heartbeatFailure = 'owner-lost';
+      } finally {
+        heartbeatInFlight = null;
+      }
+    })();
+    return heartbeatInFlight;
+  };
+  const scheduleHeartbeat = ctx.setInterval || setInterval;
+  const cancelHeartbeat = ctx.clearInterval || clearInterval;
+  const heartbeatTimer = scheduleHeartbeat(() => { void checkpointOwner(); }, ownerHeartbeatMs);
+  heartbeatTimer?.unref?.();
   try {
     while (passes < maxPasses && !isAborted(ctx.signal)) {
+      if (heartbeatFailure) {
+        reason = heartbeatFailure;
+        break;
+      }
+      const current = await owner.readOwner(identity, ownerOptions);
+      if (!current?.ok || current.record?.generation !== generation || current.record?.watcherPid !== pid) {
+        reason = current?.reason || 'owner-lost';
+        break;
+      }
+      if (current.record.phase === 'stop_requested') {
+        stopped = true;
+        reason = 'stop-requested';
+        break;
+      }
+      if (current.record.phase === 'terminal_pending') {
+        stopped = true;
+        terminalPending = true;
+        reason = 'terminal-pending';
+        break;
+      }
+      if (current.record.phase !== 'running') {
+        reason = 'owner-not-running';
+        break;
+      }
       const result = await runWatchPass(state, ctx, emit);
       passes += 1;
-      if (result.terminal) { stopped = true; break; }
+      if (result.terminal) {
+        // Keep the exact running row for dead-owner receipt recovery if this write fails.
+        terminalPending = true;
+        const recorded = await owner.recordTerminal(identity, {
+          generation, pid, terminalReceiptId: result.terminalReceiptId,
+        }, ownerOptions);
+        if (recorded?.ok) {
+          stopped = true;
+          terminalPending = true;
+          reason = 'terminal-pending';
+          break;
+        }
+        reason = recorded?.reason || 'receipt-unavailable';
+      }
+      await checkpointOwner();
+      if (heartbeatFailure) {
+        reason = heartbeatFailure;
+        break;
+      }
       if (passes >= maxPasses || isAborted(ctx.signal)) break;
       await sleep(jitter(intervalMs, rng), ctx.signal);
     }
   } finally {
-    // Release BOTH claims: the in-process slot (for a same-process restart) and
-    // the cross-process PID file. Ordered so the in-process guard clears first.
-    releaseClaim(dir);
-    removePid(dir);
+    cancelHeartbeat(heartbeatTimer);
+    await heartbeatInFlight;
+    // Terminal ownership remains until a later dead-PID completion transaction;
+    // every other process exit releases its exact generation cooperatively.
+    if (!terminalPending) {
+      try {
+        const stopRequested = typeof owner.requestStop === 'function'
+          ? await owner.requestStop(identity, { generation, pid }, ownerOptions)
+          : { ok: true };
+        if (stopRequested?.ok) {
+          await owner.releaseNonterminal(identity, { generation, pid }, ownerOptions);
+        }
+      } catch {
+        // Preserve the owner row for a later dead-watcher recovery transaction.
+      }
+    }
   }
-  return { started: true, passes, stopped };
+  return { started: true, passes, stopped, ...(reason ? { reason } : {}) };
 }
 
 module.exports = {
   watchLoop,
   runWatchPass,
   defaultSleep,
-  defaultClaim,
-  releaseClaim,
   jitter,
   partition,
   contradictions,

package/lib/pr-shepherd.js

@@ -211,7 +211,7 @@ async function handleFailedRequired({
  * @returns {Promise<object>} decision envelope.
  */
 async function handleBehindBase({
-  behind, autoRebase, cleanTree, adapter, baseRef, headUnchanged, actions,
+  behind, autoRebase, cleanTree, adapter, baseRef, expectedHead, headUnchanged, actions,
 }) {
   if (!autoRebase) {
     return result('ESCALATE', {
@@ -240,10 +240,22 @@ async function handleBehindBase({
     });
   }
   try {
-    await adapter.rebaseOntoBase({ baseRef });
+    const rebaseResult = await adapter.rebaseOntoBase({ baseRef, expectedHead });
+    const verifiedHead = rebaseResult?.previousHead === expectedHead
+      && typeof rebaseResult?.headSha === 'string'
+      && /^[0-9a-f]{40}$/i.test(rebaseResult.headSha)
+      ? rebaseResult.headSha.toLowerCase()
+      : null;
+    if (!verifiedHead) {
+      return result('ESCALATE', {
+        actions,
+        reason: 'Rebase completed without a lease-bound post-action head; refusing convergence handoff.',
+      });
+    }
     actions.push({ type: 'rebase', baseRef });
     return result('PENDING', {
       actions,
+      expectedHead: verifiedHead,
       reason: 'Rebased onto base and force-pushed with lease. Awaiting CI on the next scheduled pass.',
     });
   } catch (error) {
@@ -478,7 +490,8 @@ async function runShepherdPass(ctx) {
   // never rebase — force autoRebase off so the branch-behind path only escalates. ---
   if (behind > 0) {
     return handleBehindBase({
-      behind, autoRebase: dryRun ? false : autoRebase, cleanTree, adapter, baseRef, headUnchanged, actions,
+      behind, autoRebase: dryRun ? false : autoRebase, cleanTree, adapter, baseRef,
+      expectedHead: startSha, headUnchanged, actions,
     });
   }
 
@@ -500,6 +513,7 @@ async function runShepherdPass(ctx) {
     }
     return result('MERGE_READY', {
       actions,
+      expectedHead: startSha,
       reason: 'All required checks are green and the branch is up to date. Handing off to the human to merge in the GitHub UI — the shepherd never merges.',
     });
   }

package/lib/project-memory.js

@@ -2,10 +2,13 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { createHash, randomUUID } = require('node:crypto');
+const { types: { isProxy } } = require('node:util');
 const { resolveKernelDatabasePath } = require('./kernel/cli-broker-factory');
 const { resolveGitCommonDir } = require('./kernel/broker');
 const { createBuiltinSQLiteDriver } = require('./kernel/sqlite-driver');
 const { normalizeRecallHit } = require('./memory-recall');
+const { createUsageEvidenceStore } = require('@forge/memory');
 
 // Project memory is a Forge read model persisted in the kernel store (kernel_memories),
 // written DIRECTLY rather than through the issue CAS/guarded-event path. The store seam
@@ -146,20 +149,28 @@ function list(projectRoot, options = {}) {
 // driver so recall never loads and re-sorts the whole table. `options.agents` (a
 // source_agent allow-list) scopes the read, e.g. to human `remember` notes only.
 function recent(projectRoot, limit, options = {}) {
-  return resolveStore(projectRoot, options).recentMemories(limit, { agents: options.agents });
+  return resolveStore(projectRoot, options).recentMemories(limit, {
+    agents: options.agents,
+    kind: options.kind,
+  });
 }
 
 // Total stored memories (optionally scoped by `options.agents`) — paired with `recent` so
 // recall can report "showing N of TOTAL".
 function count(projectRoot, options = {}) {
-  return resolveStore(projectRoot, options).countMemories({ agents: options.agents });
+  return resolveStore(projectRoot, options).countMemories({
+    agents: options.agents,
+    kind: options.kind,
+  });
 }
 
 // BM25 top-N recall over the FTS5 index (token-AND). Unlike `search` (the legacy LIKE
 // helper) this does not short-circuit an empty query — the driver falls back to recent so
 // recall stays capped either way.
 function searchRanked(projectRoot, query, limit, options = {}) {
-  return resolveStore(projectRoot, options).searchMemoriesRanked(query, limit);
+  return resolveStore(projectRoot, options).searchMemoriesRanked(query, limit, {
+    kind: options.kind,
+  });
 }
 
 // Relevance-only BM25 recall that returns the raw bm25 `score` per entry, so a caller can
@@ -178,6 +189,131 @@ function searchRankedScored(projectRoot, query, limit, options = {}) {
     .map(hit => normalizeRecallHit(hit, projectId));
 }
 
+function opaqueUsageIdentity(kind, value) {
+  return createHash('sha256').update(`${kind}\0${value}`).digest('hex');
+}
+
+function memoryUsageIdentity(key) {
+  return opaqueUsageIdentity('forge.memory.key.v1', key);
+}
+
+function ownDataValue(value, field) {
+  if (!value || typeof value !== 'object' || isProxy(value)) return undefined;
+  let descriptor;
+  try { descriptor = Object.getOwnPropertyDescriptor(value, field); } catch { return undefined; }
+  return descriptor && Object.hasOwn(descriptor, 'value') ? descriptor.value : undefined;
+}
+
+function usageResolutionOptions(options) {
+  const resolutionOptions = {};
+  for (const field of ['store', 'gitCommonDir', 'platform', 'realpath', 'databasePath']) {
+    const option = ownDataValue(options, field);
+    if (option !== undefined) resolutionOptions[field] = option;
+  }
+  return resolutionOptions;
+}
+
+function usageInvocationId(options) {
+  const value = ownDataValue(options, 'invocationId');
+  return typeof value === 'string' && value ? value : randomUUID();
+}
+
+function usageObservedAt(options) {
+  const invocationStartedAt = ownDataValue(options, 'invocationStartedAt');
+  if (typeof invocationStartedAt === 'string') return invocationStartedAt;
+  const now = ownDataValue(options, 'now');
+  if (typeof now === 'string') return now;
+  return new Date().toISOString();
+}
+
+function usageMemoryIdentities(notes) {
+  return notes
+    .map(note => ownDataValue(note, 'id'))
+    .filter(id => typeof id === 'string' && id.length > 0)
+    .map(memoryUsageIdentity);
+}
+
+function appendRecallUsage(store, identities, invocationId, scope, selectionDigest, observedAt) {
+  let appended = 0;
+  let failed = 0;
+  for (const memoryId of identities) {
+    try {
+      const result = store.append({
+        event_id: opaqueUsageIdentity('forge.memory.used.event.v1', `${invocationId}\0${memoryId}`),
+        memory_id: memoryId,
+        scope,
+        use_kind: 'cli-recall',
+        consumer_id: 'cli-recall',
+        selection_digest: selectionDigest,
+        observed_at: observedAt,
+        idempotency_key: opaqueUsageIdentity('forge.memory.used.idempotency.v1', `${invocationId}\0${memoryId}`),
+      });
+      if (result?.appended) appended += 1;
+    } catch {
+      // Evidence is advisory: a storage failure must never hide a useful recall.
+      failed += 1;
+    }
+  }
+  return { attempted: identities.length, appended, failed };
+}
+
+// Recall evidence deliberately accepts only the returned note identifiers. It hashes those
+// identifiers immediately, so neither a user path, query, nor note content can reach storage.
+function recordRecallUsage(projectRoot, selected, options = {}) {
+  const notes = Array.isArray(selected) ? selected : [];
+  if (notes.length === 0) return { attempted: 0, appended: 0, failed: 0 };
+  const usageStore = ownDataValue(options, 'usageStore');
+  const resolutionOptions = usageResolutionOptions(options);
+  const invocationId = usageInvocationId(options);
+  const observedAt = usageObservedAt(options);
+  const identities = usageMemoryIdentities(notes);
+  if (identities.length === 0) return { attempted: 0, appended: 0, failed: 0 };
+  let scope;
+  let selectionDigest;
+  let store;
+  try {
+    scope = opaqueUsageIdentity('forge.memory.scope.v1', resolveProjectId(projectRoot, resolutionOptions));
+    selectionDigest = opaqueUsageIdentity('forge.memory.selection.v1', identities.join('\0'));
+    store = createUsageEvidenceStore(usageStore || resolveStore(projectRoot, resolutionOptions));
+  } catch {
+    return { attempted: identities.length, appended: 0, failed: identities.length };
+  }
+  return appendRecallUsage(store, identities, invocationId, scope, selectionDigest, observedAt);
+}
+
+function usageProjection(projectRoot, key, options = {}) {
+  if (typeof key !== 'string' || !key) return null;
+  try {
+    const usageStore = ownDataValue(options, 'usageStore');
+    return createUsageEvidenceStore(usageStore || resolveStore(projectRoot, options))
+      .projection(opaqueUsageIdentity('forge.memory.key.v1', key));
+  } catch {
+    return null;
+  }
+}
+
+function usageProjectionStatus(projectRoot, keys, options = {}) {
+  if (!Array.isArray(keys) || keys.length === 0) return { available: true, projections: new Map() };
+  const rawKeys = [...new Set(keys.filter(key => typeof key === 'string' && key))].slice(0, 200);
+  if (rawKeys.length === 0) return { available: true, projections: new Map() };
+  const usageStore = ownDataValue(options, 'usageStore');
+  const identities = rawKeys.map(memoryUsageIdentity);
+  try {
+    const rows = createUsageEvidenceStore(usageStore || resolveStore(projectRoot, options)).projections(identities);
+    const keyByIdentity = new Map(rawKeys.map((key, index) => [identities[index], key]));
+    return {
+      available: true,
+      projections: new Map(rows.map(row => [keyByIdentity.get(row.memory_id), row]).filter(([key]) => key)),
+    };
+  } catch {
+    return { available: false, projections: new Map() };
+  }
+}
+
+function usageProjections(projectRoot, keys, options = {}) {
+  return usageProjectionStatus(projectRoot, keys, options).projections;
+}
+
 // Close and forget every cached default store. The CLI process is short-lived (the OS
 // closes the handle on exit), so this is mainly a lifecycle helper for long-lived hosts and
 // tests — it releases the SQLite/WAL handle before a temp dir is removed.
@@ -201,6 +337,12 @@ module.exports = {
   count,
   searchRanked,
   searchRankedScored,
+  recordRecallUsage,
+  usageProjection,
+  usageProjectionStatus,
+  usageProjections,
+  memoryUsageIdentity,
+  resolveStore,
   resolveProjectId,
   closeAll,
 };