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

package/docs/reference/shepherd.md

@@ -22,22 +22,26 @@ There are two ways to run the shepherd, both under the single `forge shepherd`
 verb:
 
 - **`forge shepherd daemon` — the singleton reconcile daemon, the default
-  ownership model.** It acquires the machine-wide shepherd lease for this repo
+  coordinator.** It acquires the machine-wide election lease for this repo
   (exiting immediately as a clean no-op if a live daemon already owns it),
   heartbeats, and converges the *entire* PR world every ~60s: self-registering
-  hand-opened PRs, restarting killed watchers, reaping verified orphan watchers,
+  hand-opened PRs, recovering dead watcher generations, requesting cooperative
+  stops,
   converging CI check state into kernel verdicts, and retiring merged/closed PRs.
-  It **self-retires** — releases the lease, kills its verified children, exits —
-  once no PRs remain open. Forge wakes it automatically after a successful
+  It **self-retires** — releases the election lease and exits — once no PRs
+  remain open. Per-PR ownership is never stored in that lease. Forge wakes it
+  automatically after a successful
   supported session start, every successful push, and every successful
   non-dry-run ship. These are the only automatic firing seams; ordinary commands
   do not launch it. Once running, an agent does not poll: the daemon owns the
   convergence loop.
-- **`forge shepherd <pr>` — one bounded pass.** Reads one PR's state, takes at
-  most one Tier-A action, exits. The point-in-time surface for a single PR (see
-  *Bounded-pass model* below).
+- **`forge shepherd <pr>` — one bounded convergence pass.** Runs local review
+  preflight, reads one PR's state, takes at most one Tier-A action, persists
+  bounded deltas/receipts, and exits. The point-in-time surface for a single PR
+  (see *Bounded-pass model* below).
 - **`forge shepherd watch <pr>` / `watch --adopt`** — foreground streaming watch of
-  one PR, or (`--adopt`) adopt every currently-open PR into the watcher set.
+  one PR, or (`--adopt`) reserve owner rows and start watchers for every
+  currently-open PR.
 - **`forge shepherd events <pr> --since <seq>`** — the event deltas for a PR since a
   cursor; **`forge shepherd <pr> --pull --json` / `--bundle`** read the kernel verdict
   + rollup without taking any action.
@@ -48,6 +52,12 @@ bare CLI use falls back to a detached launch from the stable common repository
 root, never a disposable worktree cwd. No liveness check is needed first — the
 O_EXCL singleton lease makes a duplicate start a clean no-op.
 
+The daemon never kills watcher PIDs. A stop is a generation-conditional
+`running -> stop_requested` transition in the Kernel; the matching watcher sees
+that state, exits its loop, and releases only its own generation. A dead watcher
+is recovered only after fresh PID and provider evidence is gathered outside the
+transaction and the exact owner-row snapshot still matches inside it.
+
 Embedding boundary:
 
 ```js
@@ -115,6 +125,16 @@ project's documented ergonomic — poll briefly, then stop and hand off. A pass
 that finds checks still pending returns `PENDING`; the next scheduled pass picks
 up from there.
 
+Before remote mutation, the plain pass consolidates a probed CodeRabbit CLI with
+strict lint, structural drift, Sonar parity, and affected tests. The result is
+returned as `localPreflight`; CodeRabbit absence/auth loss is explicitly
+`UNAVAILABLE`/`INCOMPLETE`, not green. Deterministic failure or actual local
+review findings makes the remote decision dry-run for that pass. A local
+checkout that is not the exact PR head is explicitly `NOT_APPLICABLE`. Output is
+bounded to 128 `deltas` plus receipt IDs and one outcome handoff: `review` for
+semantic feedback, explicit human-approved `merge` at `MERGE_READY`, or `verify`
+after merged evidence. Shepherd never resolves threads and never merges.
+
 `--watch`-style behavior, if desired, belongs in an external scheduler (cron, or
 a `/loop`) that re-invokes the bounded pass with a debounce of at least 60
 seconds and cancel-in-progress. The shepherd itself never waits in-process.
@@ -164,6 +184,7 @@ same verb (or `forge shepherd events`) on its own cadence.
 | `MERGE_READY` | Required checks are green and the branch is up to date. The shepherd hands off — **a human merges in the GitHub UI.** |
 | `ESCALATE`    | A Tier-C condition (conflict, unreadable required set, persistent failure, oscillation, budget exhaustion). Context is posted to the PR. |
 | `PENDING`     | A Tier-A action was taken, or checks are still pending. Exit and await the next scheduled pass. |
+| `INCOMPLETE`  | Exact-head local review or durable convergence evidence is unavailable. Fail closed and retry after evidence is restored. |
 | `HARD_STOP`   | A permanent auth/scope failure that retrying cannot fix. Escalate to a human to widen token scope. |
 
 ## Action ladder
@@ -189,6 +210,13 @@ same verb (or `forge shepherd events`) on its own cadence.
 - **HEAD-changed abort.** Before any mutating action it re-reads the head SHA; if
   HEAD moved during the pass, the action aborts. The `shepherd:active` marker is
   advisory only — it is not mutual exclusion.
+- **One per-PR authority.** `kernel_pr_watch_owners` is the sole watcher owner
+  record. The daemon lease elects one reconciler but contains no watcher list;
+  journals and legacy PID/marker files cannot authorize a transition.
+- **Fail-closed evidence.** Kernel unavailability, corrupt owner rows, stale
+  generations, changed provider/PID/receipt evidence, and an incomplete legacy
+  migration gate block mutation and are retried. No unlocked or filesystem
+  fallback becomes authority.
 - **Auth taxonomy.** 401 (expiry) pauses and surfaces; 403 insufficient-scope is
   a hard-stop; 403 with `Retry-After` honors the delay and resumes next pass.
 
@@ -248,8 +276,30 @@ neutral `forge/pr-monitor` check.
 
 ## State
 
-Progress is durable in the Actions job summary, the single verdict label, and
-`git`. The one local store is the constant monitor's per-PR journal under
-`.forge/pr-monitor/<repo>-<pr>/` (the append-only `events.ndjson` + snapshot and
-consumer cursors) — the delivery/replay surface for `forge shepherd watch` and
-`events --since`. The bounded shepherd pass itself keeps no separate local state.
+The shared Kernel database stores one versioned `kernel_pr_watch_owners` row per
+canonical `(repo, pr)`. Its generation-conditional phases are `starting`,
+`running`, `stop_requested`, `terminal_pending`, `complete`, and `blocked`.
+Starts reserve a store-minted generation before spawning; the child binds its
+PID to that exact generation; heartbeats, stop requests, terminal receipts,
+recovery, release, and reopen are narrow compare-and-swap transitions. Provider,
+PID, and receipt checks happen outside the short SQLite transaction, followed by
+an exact snapshot check inside it.
+
+Public Memory and the per-PR journal under
+`.forge/pr-monitor/<repo>-<pr>/` remain durable delivery and replay surfaces for
+monitor events, verdicts, `forge shepherd watch`, and `events --since`; neither
+is watcher ownership authority. A terminal receipt first moves the owner row to
+`terminal_pending`; a later transaction completes it only after the watcher PID
+is confirmed dead and the receipt/provider evidence still matches.
+
+Upgrade from the retired filesystem model is fenced by the repository-local
+`kernel_pr_watch_migration_gate`. The importer publishes `quarantined`, obtains
+two identical bounded snapshots of the old lease/PID/marker evidence, binds that
+snapshot hash before importing one PR per transaction, durably rereads the rows
+and source, and then completes the exact gate/hash. Corrupt, changed, live-PID,
+or unmappable evidence stays fail-closed as `blocked` or `conflict`. After the
+gate is complete, legacy evidence is cleanup-only and never regains authority.
+
+For 0.1, no receipt grants continuing lease authority. Consequential paths
+re-probe live ownership, while canonical LeaseReceipt epoch/scope and the
+same-actor/session release-reclaim ABA fix remain explicitly deferred.

package/lib/adapters/pr-state-adapter.js

@@ -102,6 +102,9 @@ function classifyAuthError(error) {
   if (status === 401 || /HTTP 401|bad credentials|token expired/i.test(text)) {
     return { class: 'expired' };
   }
+  if (status === 429 || /HTTP 429/i.test(text)) {
+    return { class: 'rate-limit', retryAfter };
+  }
   if (status === 403 || /HTTP 403/i.test(text)) {
     if (retryAfter || /rate limit|secondary rate/i.test(text)) {
       return { class: 'rate-limit', retryAfter };
@@ -116,6 +119,7 @@ class PrStateAdapter {
    * @param {object} [options]
    * @param {Function} [options.gh] - Runner for `gh` (cmd, args[]) → string.
    * @param {Function} [options.git] - Runner for `git` (cmd, args[]) → string.
+   * @param {string} [options.repository] - Exact owner/repo for numeric PR reads.
    */
   constructor(options = {}) {
     this.id = options.id || 'pr-state-adapter';
@@ -131,6 +135,7 @@ class PrStateAdapter {
     });
     this._gh = options.gh || defaultRunner;
     this._git = options.git || defaultRunner;
+    this._repository = options.repository || null;
     this.lastProtectionStatus = null;
   }
 
@@ -141,7 +146,11 @@ class PrStateAdapter {
    * @returns {Promise<{ headSha: string, mergeable: string, mergeStateStatus: string, checks: object[], threads: object[] }>}
    */
   async readState(pr) {
-    const raw = this._gh('gh', ['pr', 'view', String(pr), '--json', PR_VIEW_FIELDS]);
+    const raw = this._gh('gh', [
+      'pr', 'view', String(pr),
+      ...(this._repository ? ['--repo', this._repository] : []),
+      '--json', PR_VIEW_FIELDS,
+    ]);
     const data = JSON.parse(raw || '{}');
     const lifecycleReadable = typeof data.state === 'string'
       && ['OPEN', 'MERGED', 'CLOSED'].includes(data.state.toUpperCase())
@@ -732,7 +741,11 @@ class PrStateAdapter {
    * @returns {Promise<number|null>} epoch ms of the head commit, or null.
    */
   async readHeadCommitTime({ pr }) {
-    const raw = this._gh('gh', ['pr', 'view', String(pr), '--json', 'commits', '-q', '.commits[-1].committedDate']);
+    const raw = this._gh('gh', [
+      'pr', 'view', String(pr),
+      ...(this._repository ? ['--repo', this._repository] : []),
+      '--json', 'commits', '-q', '.commits[-1].committedDate',
+    ]);
     const t = Date.parse(String(raw || '').trim());
     return Number.isFinite(t) ? t : null;
   }

package/lib/base-remote.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+const BASE_REMOTE_CANDIDATES = ['upstream', 'origin'];
+const DEFAULT_BRANCH_CANDIDATES = ['main', 'master'];
+const GIT_PROBE_TIMEOUT_MS = 120000;
+
+/**
+ * Quiet git probe options. `stdio: 'pipe'` keeps failed probes from leaking to
+ * the terminal — these are speculative queries, not user-facing commands.
+ *
+ * @param {string} cwd - Working directory for the probe.
+ * @returns {object} execFileSync options.
+ */
+function getQuietProbeOptions(cwd) {
+	return { encoding: 'utf8', cwd, timeout: GIT_PROBE_TIMEOUT_MS, stdio: 'pipe' };
+}
+
+/**
+ * Resolve `refs/remotes/<remote>/HEAD` to the ref it points at, verifying the
+ * target actually exists.
+ *
+ * @param {Function} [exec] - Injected execFileSync.
+ * @param {string} [cwd] - Repository directory.
+ * @param {string} [remoteName] - Remote to probe.
+ * @returns {string|null} Fully-qualified ref, or null.
+ */
+function resolveRemoteHeadTarget(exec = execFileSync, cwd = process.cwd(), remoteName = undefined) {
+	if (!remoteName) {
+		return null;
+	}
+	try {
+		const symbolicRef = exec('git', ['symbolic-ref', `refs/remotes/${remoteName}/HEAD`], getQuietProbeOptions(cwd)).trim();
+		if (!symbolicRef) {
+			return null;
+		}
+		exec('git', ['rev-parse', '--verify', symbolicRef], getQuietProbeOptions(cwd));
+		return symbolicRef;
+	} catch (_error) { // NOSONAR S2486 - intentional: missing ref is the expected probe failure
+		void _error;
+		return null;
+	}
+}
+
+/**
+ * True when the remote has fetched tracking refs we can treat as a base:
+ * a recorded HEAD, or one of the conventional default branches.
+ *
+ * @param {Function} [exec] - Injected execFileSync.
+ * @param {string} [cwd] - Repository directory.
+ * @param {string} [remoteName] - Remote to probe.
+ * @returns {boolean} Whether a usable tracking base exists.
+ */
+function remoteHasTrackingBase(exec = execFileSync, cwd = process.cwd(), remoteName = undefined) {
+	if (!remoteName) {
+		return false;
+	}
+	if (resolveRemoteHeadTarget(exec, cwd, remoteName)) {
+		return true;
+	}
+
+	for (const candidate of DEFAULT_BRANCH_CANDIDATES) {
+		try {
+			exec('git', ['rev-parse', '--verify', `refs/remotes/${remoteName}/${candidate}`], getQuietProbeOptions(cwd));
+			return true;
+		} catch (_error) { // NOSONAR S2486 - intentional: speculative probe, try next candidate
+			void _error;
+			// Probe next candidate.
+		}
+	}
+
+	return false;
+}
+
+/**
+ * Resolve the remote that owns the integration base. `upstream` wins over
+ * `origin` so a fork-style checkout resolves the official repository rather
+ * than the contributor's fork.
+ *
+ * @param {Function} [exec] - Injected execFileSync.
+ * @param {string} [cwd] - Repository directory.
+ * @returns {string} Remote name ('origin' when nothing else qualifies).
+ */
+function resolveBaseRemote(exec = execFileSync, cwd = process.cwd()) {
+	for (const candidate of BASE_REMOTE_CANDIDATES) {
+		try {
+			exec('git', ['remote', 'get-url', candidate], getQuietProbeOptions(cwd));
+			if (remoteHasTrackingBase(exec, cwd, candidate)) {
+				return candidate;
+			}
+		} catch (_error) { // NOSONAR S2486 - intentional: speculative probe, try next candidate
+			void _error;
+			// Probe next candidate.
+		}
+	}
+
+	return 'origin';
+}
+
+/**
+ * Resolve the base remote's default branch name.
+ *
+ * @param {Function} [exec] - Injected execFileSync.
+ * @param {string} [cwd] - Repository directory.
+ * @param {string} [remoteName] - Remote to probe; defaults to the base remote.
+ * @returns {string} Branch name ('master' when nothing else resolves).
+ */
+function resolveBaseBranch(exec = execFileSync, cwd = process.cwd(), remoteName = resolveBaseRemote(exec, cwd)) {
+	const symbolicRef = resolveRemoteHeadTarget(exec, cwd, remoteName);
+	if (symbolicRef) {
+		const match = new RegExp(`^refs/remotes/${remoteName}/(.+)$`).exec(symbolicRef);
+		if (match?.[1]) {
+			return match[1];
+		}
+	}
+
+	for (const candidate of DEFAULT_BRANCH_CANDIDATES) {
+		try {
+			exec('git', ['rev-parse', '--verify', `refs/remotes/${remoteName}/${candidate}`], getQuietProbeOptions(cwd));
+			return candidate;
+		} catch (_error) { // NOSONAR S2486 - intentional: speculative probe, try next candidate
+			void _error;
+			// Probe next candidate.
+		}
+	}
+
+	return 'master';
+}
+
+module.exports = {
+	BASE_REMOTE_CANDIDATES,
+	DEFAULT_BRANCH_CANDIDATES,
+	resolveRemoteHeadTarget,
+	remoteHasTrackingBase,
+	resolveBaseRemote,
+	resolveBaseBranch,
+};