loreli 0.0.0 → 2.0.0

package/packages/review/src/index.js

@@ -0,0 +1,1403 @@
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Workflow } from 'loreli/workflow';
+import { output } from 'loreli/agent';
+import { checkout, pathFor } from 'loreli/workspace';
+import { side, capability } from 'loreli/identity';
+import { logger } from 'loreli/log';
+import { mark, has, parse, excise } from 'loreli/marker';
+import { classify } from 'loreli/knowledge';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const log = logger('review');
+const CLOSE_RE = /(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)/gi;
+
+/**
+ * Build workspace context used to regenerate MCP scaffolding after checkout.
+ *
+ * @param {object} orchestrator - Orchestrator instance.
+ * @param {string} repo - Repository in "owner/name" format.
+ * @param {string} agent - Agent identity name.
+ * @returns {object}
+ */
+function workspaceContext(orchestrator, repo, agent) {
+  const context = {
+    session: orchestrator.sessionId,
+    agent,
+    repo,
+    home: orchestrator.storage?.home,
+    denied: orchestrator.cfg?.get?.('agents.disallowedTools') ?? []
+  };
+
+  if (process.env.GITHUB_TOKEN) context.token = process.env.GITHUB_TOKEN;
+
+  return context;
+}
+
+/**
+ * Build checkout options that preserve workspace scaffolding.
+ *
+ * @param {object} orchestrator - Orchestrator instance.
+ * @param {string} repo - Repository in "owner/name" format.
+ * @param {string} agent - Agent identity name.
+ * @returns {{context: object, descriptors: object[]}}
+ */
+function workspaceOptions(orchestrator, repo, agent) {
+  const context = workspaceContext(orchestrator, repo, agent);
+  const descriptors = orchestrator.backendRegistry?.scaffoldAll?.(context) ?? [];
+  return { context, descriptors };
+}
+
+/**
+ * Path to the action prompt template. Used for cross-role rendering
+ * when forwarding review feedback to the action agent.
+ *
+ * @type {string}
+ */
+const ACTION_TEMPLATE = join(__dirname, '..', '..', 'action', 'prompts', 'action.md');
+
+/**
+ * Review workflow for Loreli's orchestration pipeline.
+ *
+ * Manages reviewer agents — PR scanning, review dispatch, feedback
+ * forwarding, merge landing, Human In The Loop (HITL), stalemate escalation, and
+ * the signoff protocol.
+ *
+ * @extends Workflow
+ */
+export class ReviewWorkflow extends Workflow {
+  /** @type {string} Agent role this workflow manages. */
+  static role = 'reviewer';
+
+  /** @type {string} Mustache template path for reviewer prompts. */
+  static template = join(__dirname, '..', 'prompts', 'reviewer.md');
+
+  /**
+   * Tracked PRs undergoing review.
+   * Keys are PR numbers, values are { agent, reviewer, rounds }.
+   *
+   * @type {Map<number, {agent: string, reviewer: string, rounds: number}>}
+   */
+  _watched = new Map();
+
+  /**
+   * PRs that have been fully processed (merged, failed, or escalated).
+   * Prevents scan() from re-adding PRs after land() removes them.
+   * Entries are `{ addedAt: number }` for TTL-based pruning.
+   *
+   * @type {Map<number, number>}
+   */
+  _completed = new Map();
+
+  /**
+   * Preserved round counts for evicted PRs. When a reviewer is evicted
+   * (stalled or killed) and scan() re-adds the PR with a new reviewer,
+   * the round count must carry over so the escalation threshold
+   * (maxRounds) is eventually reached. Without this, evict → scan
+   * cycles reset rounds to 0 indefinitely.
+   * Entries are `{ rounds, addedAt }` for TTL-based pruning.
+   *
+   * @type {Map<number, {rounds: number, addedAt: number}>}
+   */
+  _evictedRounds = new Map();
+
+  /**
+   * TTL for completed/evicted entries (1 hour). Entries older than
+   * this are pruned during hydrate() to prevent unbounded growth.
+   * @type {number}
+   */
+  static PRUNE_TTL = 3_600_000;
+
+  /**
+   * Extract linked issue numbers from a PR body using GitHub closing
+   * keywords (`Closes #N`, `Fixes #N`, `Resolves #N`).
+   *
+   * @param {string} body - Pull request body text.
+   * @returns {number[]} Unique linked issue numbers.
+   */
+  links(body) {
+    if (!body) return [];
+    const found = new Set();
+    CLOSE_RE.lastIndex = 0;
+
+    let match;
+    while ((match = CLOSE_RE.exec(body)) !== null) {
+      const number = Number.parseInt(match[1], 10);
+      if (Number.isInteger(number)) found.add(number);
+    }
+
+    return [...found];
+  }
+
+  /**
+   * Reconcile linked issue closure for non-default merge targets.
+   *
+   * GitHub only auto-closes linked issues for merges to the default
+   * branch. When Loreli targets a non-default merge base, merged PRs
+   * can leave linked issues open and trigger duplicate work cycles.
+   * This closes still-open linked issues after merge, but only when
+   * base != default branch.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} prNum - Pull request number.
+   * @returns {Promise<void>}
+   */
+  async reconcile(repo, prNum) {
+    if (!this.hub?.pull || !this.hub?.repo || !this.hub?.issue || !this.hub?.update) return;
+
+    let pr;
+    try {
+      pr = await this.hub.pull(repo, prNum);
+    } catch (err) {
+      log.warn(`reconcile: failed to read PR #${prNum}: ${err.message}`);
+      return;
+    }
+
+    let info;
+    try {
+      info = await this.hub.repo(repo);
+    } catch (err) {
+      log.warn(`reconcile: failed to read repo metadata for ${repo}: ${err.message}`);
+      return;
+    }
+
+    const base = pr?.base;
+    const main = info?.default_branch ?? 'main';
+    if (!base || base === main) return;
+
+    const linked = this.links(pr?.body);
+    for (const number of linked) {
+      try {
+        const issue = await this.hub.issue(repo, number);
+        if (issue?.state !== 'open') continue;
+
+        await this.hub.update(repo, number, { state: 'closed' });
+        log.info(`reconcile: closed linked issue #${number} after merge of PR #${prNum} (base=${base}, default=${main})`);
+      } catch (err) {
+        log.warn(`reconcile: failed to close linked issue #${number} for PR #${prNum}: ${err.message}`);
+      }
+    }
+  }
+
+  /**
+   * Evaluate a foreign reviewer assignment through the proof-of-life protocol.
+   *
+   * Same logic as ActionWorkflow._checkForeignClaim but operates on PRs.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} prNum - PR number.
+   * @param {string} reviewer - Reviewer agent name being released.
+   * @param {string} reason - Human-readable eviction reason.
+   * @returns {Promise<void>}
+   */
+  async _releaseReviewer(repo, prNum, reviewer, reason) {
+    const identity = this.orchestrator.clientIdentity;
+    if (!identity || !this.hub) return;
+    try {
+      const body = mark('review-release', { agent: reviewer });
+      await this.hub.as(identity, 'orchestrator')
+        .comment(repo, prNum, `${reason}\n\n${body}`);
+    } catch (err) {
+      log.warn(`scan: release comment failed for PR #${prNum}: ${err.message}`);
+    }
+  }
+
+  /**
+   * Check whether a foreign reviewer (not in this orchestrator's agent
+   * map) is still alive via the proof-of-life comment protocol.
+   *
+   * Delegates to the base Workflow `check()` method which implements
+   * the unified, status-aware PoL gate.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} prNum - PR number.
+   * @param {object} tracking - Watched PR tracking object.
+   * @returns {Promise<string>} 'active'|'requested'|'pending'|'release'.
+   */
+  async _checkForeignReviewer(repo, prNum, tracking) {
+    return this.check(repo, prNum, tracking.reviewer);
+  }
+
+  /**
+   * Report reviewer demand: how many PRs need a reviewer vs how many
+   * reviewers are active. Uses hydrated state so no extra API calls.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<{workload: number, supply: number, deficit: number}>}
+   */
+  async demand(repo) {
+    const prs = await this.hub.pulls(repo, { state: 'open' });
+    const skipRisk = this.orchestrator.cfg?.get?.('workflows.risk.skip') ?? false;
+    let allowSameSide = false;
+
+    try {
+      await this.orchestrator.backendRegistry?.discover?.();
+      const providers = this.orchestrator.backendRegistry?.providers?.() ?? [];
+      allowSameSide = capability(providers).mode === 'single';
+    } catch { /* non-fatal: keep strict pairing */ }
+
+    let workload = 0;
+    const actionProviders = new Set();
+    for (const pr of prs) {
+      if (this._watched.has(pr.number)) continue;
+      if (this._completed.has(pr.number)) continue;
+
+      // Same filter as scan() — only count PRs that pass the label gate
+      if (!skipRisk) {
+        const hasRiskLabel = pr.labels?.some(function isRisk(l) {
+          const name = l.name ?? l;
+          return (name.endsWith('-risk') || name === 'loreli:risk-unassessed') && name.startsWith('loreli:');
+        });
+        if (!hasRiskLabel) continue;
+
+        const isCritical = pr.labels?.some(function isCrit(l) {
+          return (l.name ?? l) === 'loreli:critical-risk';
+        });
+        if (isCritical) continue;
+
+        const isUnassessed = pr.labels?.some(function isUn(l) {
+          return (l.name ?? l) === 'loreli:risk-unassessed';
+        });
+        if (isUnassessed) continue;
+      }
+
+      // Collect action providers from PR labels so scale() can spawn
+      // the correct opposing-side reviewer even when no live action
+      // agent exists.
+      const providerLabel = pr.labels?.find(function isProvider(l) {
+        const name = l.name ?? l;
+        return name === 'loreli:anthropic' || name === 'loreli:openai' ||
+               name === 'loreli:cursor-anthropic' || name === 'loreli:cursor-openai';
+      });
+      if (providerLabel) actionProviders.add((providerLabel.name ?? providerLabel).replace('loreli:', ''));
+
+      workload++;
+    }
+
+    // Only count reviewers that can actually be paired with an action
+    // agent. A same-side reviewer (e.g. openai reviewer for an openai
+    // action agent) passes the role filter but pair() will reject it,
+    // creating a false "fully staffed" signal that suppresses scaling.
+    //
+    // When no live action agent exists (dead/foreign), fall back to
+    // PR label metadata to determine which side the action was on.
+    const actions = [...this.orchestrator.agents.values()]
+      .filter(function isAction(a) { return a.role === 'action'; });
+
+    const actionSides = actions.length
+      ? new Set(actions.map(function toSide(a) { return side(a.identity?.provider); }))
+      : new Set([...actionProviders].map(function toSide(p) { return side(p); }));
+
+    const assigned = new Set(
+      [...this._watched.values()].map(function name(t) { return t.reviewer; })
+    );
+
+    const supply = [...this.orchestrator.agents.values()]
+      .filter(function isPairable(a) {
+        if (a.role !== 'reviewer' || a.state === 'dormant') return false;
+        if (assigned.has(a.identity?.name)) return false;
+        if (allowSameSide) return true;
+        const reviewerSide = side(a.identity?.provider);
+        return actionSides.size === 0 || [...actionSides].some(function opposes(s) { return s !== reviewerSide; });
+      }).length;
+
+    return {
+      workload,
+      supply,
+      deficit: Math.max(0, workload - supply),
+      actionProviders: [...actionProviders]
+    };
+  }
+
+  /**
+   * Register reactor handlers for the orchestrator's tick loop.
+   * Hydrate → Scan → Forward → Land runs sequentially on each tick.
+   *
+   * @returns {Record<string, function>} Handler map.
+   */
+  reactor() {
+    const self = this;
+    return {
+      async 'review-hydrate'(repo) { await self.hydrate(repo); },
+      async scan(repo) { await self.scan(repo); },
+      async forward(repo) { await self.forward(repo); },
+      async land(repo) { await self.land(repo); },
+      async 'review-reap'(repo) { await self.reap(repo); }
+    };
+  }
+
+  /**
+   * Rehydrate in-memory review state from GitHub artifacts.
+   *
+   * Called at the start of each reactor tick so that PRs dispatched
+   * by other participants (or lost to a process restart) are visible
+   * to forward() and land(). Without this, only the process that
+   * originally called scan() would track the PR.
+   *
+   * Derives state from:
+   * - `review-claim` marker comments → PR is being reviewed
+   * - PR branch prefix → action agent name
+   * - CHANGES_REQUESTED reviews → round count
+   * - Terminal labels (needs-attention, escalated, merge-failed) → completed
+   * - Closed/merged PR state → completed
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<void>}
+   */
+  async hydrate(repo) {
+    if (!this.hub) return;
+
+    const prs = await this.hub.pulls(repo, { state: 'open' });
+
+    for (const pr of prs) {
+      if (this._watched.has(pr.number) || this._completed.has(pr.number)) continue;
+
+      // Terminal labels → mark completed
+      const isTerminal = pr.labels?.some(function isEnd(l) {
+        const name = l.name ?? l;
+        return name === 'loreli:needs-attention' ||
+               name === 'loreli:escalated' ||
+               name === 'loreli:merge-failed';
+      });
+      if (isTerminal) {
+        this._completed.set(pr.number, Date.now());
+        continue;
+      }
+
+      const comments = await this.hub.comments(repo, pr.number);
+      const claim = comments.find(function isClaim(c) { return has(c.body, 'review-claim'); });
+      if (!claim) continue;
+
+      const reviewerName = parse(claim.body, 'review-claim')?.agent;
+      if (!reviewerName) continue;
+
+      const released = comments.some(function isRelease(c) {
+        if (!has(c.body, 'review-release')) return false;
+        const data = parse(c.body, 'review-release');
+        return data?.agent === reviewerName;
+      });
+      if (released) continue;
+
+      // Agent name from branch prefix
+      const slash = pr.head?.indexOf('/');
+      const agentName = slash > 0 ? pr.head.slice(0, slash) : null;
+
+      // Round count from CHANGES_REQUESTED reviews
+      const reviews = await this.hub.reviews(repo, pr.number);
+      const crReviews = reviews.filter(function isCR(r) {
+        return r.state === 'CHANGES_REQUESTED';
+      });
+      const rounds = crReviews.length;
+
+      // Restore lastReviewId by finding the latest feedback marker
+      // and matching it to the CHANGES_REQUESTED review that triggered it.
+      let lastReviewId = null;
+      const feedbackMarker = [...comments].reverse().find(function isFeedback(c) {
+        return has(c.body, 'feedback');
+      });
+      if (feedbackMarker && crReviews.length) {
+        const markerTime = new Date(feedbackMarker.created).getTime();
+        const processed = crReviews.filter(function before(r) {
+          return new Date(r.submitted).getTime() <= markerTime;
+        }).at(-1);
+        lastReviewId = processed?.id ?? null;
+      }
+
+      this._watched.set(pr.number, {
+        agent: agentName,
+        reviewer: reviewerName,
+        rounds,
+        lastReviewId,
+        dispatchedAt: new Date(claim.created ?? claim.created_at).getTime()
+      });
+    }
+
+    // Move PRs that closed/merged between ticks from _watched to _completed.
+    // Only open PRs appear in the pulls() result above, so any _watched
+    // PR not present was resolved since the last tick.
+    for (const prNum of this._watched.keys()) {
+      if (!prs.some(function match(p) { return p.number === prNum; })) {
+        this._watched.delete(prNum);
+        this._completed.set(prNum, Date.now());
+      }
+    }
+
+    // Prune stale entries to prevent unbounded growth in long-running sessions
+    const ttl = ReviewWorkflow.PRUNE_TTL;
+    const now = Date.now();
+    for (const [prNum, addedAt] of this._completed) {
+      if (now - addedAt > ttl) this._completed.delete(prNum);
+    }
+    for (const [prNum, entry] of this._evictedRounds) {
+      if (now - entry.addedAt > ttl) this._evictedRounds.delete(prNum);
+    }
+  }
+
+  // ── Signoff Protocol ──────────────────────────────────
+
+  /**
+   * Post an approval comment using the hub's scoped identity.
+   * Embeds a machine-readable signoff marker so downstream tools can
+   * detect approvals without parsing visible text.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue or PR number.
+   * @param {object} identity - Agent identity with name.
+   * @param {string} role - Agent role for hub scoping.
+   * @returns {Promise<void>}
+   */
+  async signoff(repo, number, identity, role) {
+    const scoped = this.hub.as(identity, role);
+    const marker = mark('signoff', { agent: identity.name });
+    const visible = identity.approval?.() ?? `Approved by **${identity.name}**`;
+    await scoped.comment(repo, number, `${marker}\n${visible}`);
+  }
+
+  // ── Scan ──────────────────────────────────────────────
+
+  /**
+   * Scan for new PRs created by action agents and dispatch
+   * opposing-provider reviewers.
+   *
+   * Uses branch naming convention (`{agentName}/issue-{number}`)
+   * to match PRs to agents. Auto-enlists opposing reviewer when
+   * none is available.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<Array<{pr: number, reviewer: string}>>}
+   */
+  async scan(repo) {
+    // Evict tracked PRs whose reviewer is no longer useful.
+    //
+    // Two cases:
+    //  1. Reviewer killed — stall detection (tier 3) removed it from the
+    //     agents map. Without eviction the PR stays in _watched forever.
+    //  2. Reviewer stalled — the reviewer is alive but idle beyond the
+    //     stall timeout. Waiting for tier 3 kill (3x) would exceed
+    //     typical review timeouts. Proactive eviction lets scan()
+    //     assign a replacement sooner.
+    //
+    // In both cases forward() dedup skips the stale review and land()
+    // finds no APPROVE — a deadlock unless we evict here.
+    const stallTimeout = this.orchestrator.stallTimeout;
+    const now = Date.now();
+    for (const [prNum, tracking] of this._watched) {
+      const reviewer = this.orchestrator.agents.get(tracking.reviewer);
+      if (!reviewer) {
+        // Locally removed agents (killed by our stall detection) can
+        // be evicted immediately — no proof-of-life needed.
+        if (this.orchestrator._removed?.has(tracking.reviewer)) {
+          log.info(`scan: evicting PR #${prNum} — reviewer ${tracking.reviewer} was locally removed`);
+          this._evictedRounds.set(prNum, { rounds: tracking.rounds, addedAt: Date.now() });
+          this._watched.delete(prNum);
+          await this._releaseReviewer(repo, prNum, tracking.reviewer,
+            `Review claim released — reviewer \`${tracking.reviewer}\` is no longer active.`);
+          continue;
+        }
+
+        // Foreign reviewer — use proof-of-life protocol before evicting
+        const verdict = await this._checkForeignReviewer(repo, prNum, tracking);
+        if (verdict !== 'release') {
+          log.debug(`scan: foreign reviewer ${tracking.reviewer} on PR #${prNum} — ${verdict}`);
+          continue;
+        }
+        log.info(`scan: evicting PR #${prNum} — reviewer ${tracking.reviewer} proof-of-life expired`);
+        this._evictedRounds.set(prNum, { rounds: tracking.rounds, addedAt: Date.now() });
+        this._watched.delete(prNum);
+        await this._releaseReviewer(repo, prNum, tracking.reviewer,
+          `Review claim released — no proof of life from \`${tracking.reviewer}\`.`);
+        continue;
+      }
+
+      // Fast eviction for dormant reviewers — crash recovery when
+      // the orchestrator's stall detection may not catch it for
+      // minutes. Checking state here on every tick gives sub-second
+      // recovery.
+      if (reviewer.state === 'dormant') {
+        log.info(`scan: evicting PR #${prNum} — reviewer ${tracking.reviewer} is dormant`);
+        this._evictedRounds.set(prNum, { rounds: tracking.rounds, addedAt: Date.now() });
+        this._watched.delete(prNum);
+        await this._releaseReviewer(repo, prNum, tracking.reviewer,
+          `Review claim released — reviewer \`${tracking.reviewer}\` is dormant.`);
+        continue;
+      }
+
+      // Evict reviewers whose dispatch exceeded the stall timeout
+      // without submitting any review. This catches reviewers that
+      // appear active (MCP calls) but are stuck (corrupted workspace,
+      // missing task file, confused agent loop).
+      if (tracking.dispatchedAt) {
+        const elapsed = now - tracking.dispatchedAt;
+        if (elapsed > stallTimeout) {
+          const reviews = await this.hub.reviews(repo, prNum);
+          // All agents share a single GitHub token — check for ANY
+          // review submitted after the dispatch timestamp, not by
+          // specific user/agent name.
+          const submitted = reviews.some(function afterDispatch(r) {
+            return new Date(r.submitted).getTime() > tracking.dispatchedAt;
+          });
+          if (!submitted) {
+            log.warn(`scan: evicting PR #${prNum} — reviewer ${tracking.reviewer} dispatched ${Math.round(elapsed / 1000)}s ago with no review`);
+            this._evictedRounds.set(prNum, { rounds: tracking.rounds, addedAt: Date.now() });
+            this._watched.delete(prNum);
+            await this._releaseReviewer(repo, prNum, tracking.reviewer,
+              `Review claim released — reviewer \`${tracking.reviewer}\` stalled (${Math.round(elapsed / 1000)}s, no review submitted).`);
+            continue;
+          }
+        }
+      }
+
+      const last = this.orchestrator._lastActivity.get(tracking.reviewer);
+      const idle = last ? now - new Date(last).getTime() : 0;
+      if (idle > stallTimeout) {
+        const verdict = await this.check(repo, prNum, tracking.reviewer);
+        if (verdict !== 'release') {
+          log.debug(`scan: reviewer ${tracking.reviewer} on PR #${prNum} idle but PoL: ${verdict}`);
+          continue;
+        }
+        log.info(`scan: evicting PR #${prNum} — reviewer ${tracking.reviewer} confirmed stalled via PoL`);
+        this._evictedRounds.set(prNum, { rounds: tracking.rounds, addedAt: Date.now() });
+        this._watched.delete(prNum);
+        await this._releaseReviewer(repo, prNum, tracking.reviewer,
+          `Review claim released — reviewer \`${tracking.reviewer}\` confirmed stalled.`);
+      }
+    }
+
+    const dispatched = [];
+    const prs = await this.hub.pulls(repo, { state: 'open' });
+
+    // Piggyback: record agent names discovered from PR branch prefixes
+    // in the orchestrator's taken set. Zero API cost — pulls() was
+    // already needed for review scanning.
+    for (const pr of prs) {
+      const slash = pr.head?.indexOf('/');
+      if (slash > 0) this.orchestrator.takenNames?.add(pr.head.slice(0, slash));
+    }
+
+    const actions = [...this.orchestrator.agents.values()]
+      .filter(function isAction(a) { return a.role === 'action'; });
+
+    const skipRisk = this.orchestrator.cfg?.get?.('workflows.risk.skip') ?? false;
+    let allowSameSide = false;
+
+    try {
+      await this.orchestrator.backendRegistry?.discover?.();
+      const providers = this.orchestrator.backendRegistry?.providers?.() ?? [];
+      allowSameSide = capability(providers).mode === 'single';
+    } catch { /* non-fatal: keep strict pairing */ }
+
+    for (const pr of prs) {
+      if (this._watched.has(pr.number)) continue;
+      if (this._completed.has(pr.number)) continue;
+
+      // Derive author name from branch prefix convention: {agent}/issue-{N}
+      const slash = pr.head?.indexOf('/');
+      const authorName = slash > 0 ? pr.head.slice(0, slash) : null;
+      if (!authorName) continue;
+
+      // Check for existing review-claim marker — another participant
+      // may have already claimed this PR for review. Skip this check
+      // for PRs we just evicted (reviewer dead or stalled) — we need
+      // to allow re-claim so a replacement reviewer can be dispatched.
+      //
+      // Also allow re-claim when the claim has a matching review-release
+      // marker — the previous reviewer was evicted (possibly by a
+      // different orchestrator session) and the PR is available.
+      // `wasReleased` tracks this so claimFirst is also skipped — the
+      // old claim comment still exists and would win the race otherwise.
+      const wasEvicted = this._evictedRounds.has(pr.number);
+      let wasReleased = false;
+      if (!wasEvicted) {
+        const prComments = await this.hub.comments(repo, pr.number);
+        const claim = prComments.find(function isClaimed(c) { return has(c.body, 'review-claim'); });
+        if (claim) {
+          const claimedAgent = parse(claim.body, 'review-claim')?.agent;
+          const released = claimedAgent && prComments.some(function isRelease(c) {
+            if (!has(c.body, 'review-release')) return false;
+            return parse(c.body, 'review-release')?.agent === claimedAgent;
+          });
+          if (!released) {
+            log.debug(`scan: PR #${pr.number} already claimed by ${claimedAgent} — skipping`);
+            continue;
+          }
+          log.info(`scan: PR #${pr.number} claim by ${claimedAgent} was released — allowing re-claim`);
+          wasReleased = true;
+        }
+      }
+
+      // Prefer live action agent for full identity context; fall back
+      // to PR-derived metadata when the original agent was reaped,
+      // belongs to another orchestrator, or is from a previous session.
+      const agent = actions.find(function owns(a) {
+        return pr.head.startsWith(a.identity.name + '/');
+      });
+
+      // Derive provider from PR labels when no live agent exists.
+      // PRs from dead/reaped agents still carry loreli:anthropic or
+      // loreli:openai labels applied at claim time.
+      const providerLabel = pr.labels?.find(function isProvider(l) {
+        const name = l.name ?? l;
+        return name === 'loreli:anthropic' || name === 'loreli:openai' ||
+               name === 'loreli:cursor-anthropic' || name === 'loreli:cursor-openai';
+      });
+
+      // Require either a live agent match or recognizable loreli labels.
+      // Prevents dispatching reviewers for non-Loreli PRs.
+      if (!agent && !providerLabel) continue;
+
+      const authorProvider = agent?.identity?.provider
+        ?? (providerLabel?.name ?? providerLabel)?.replace('loreli:', '')
+        ?? 'unknown';
+
+      // Label gate: only dispatch reviewer for PRs that have been
+      // risk-assessed (carry a loreli:*-risk label) or flagged as
+      // unassessed, or when risk assessment is disabled. RiskWorkflow
+      // runs first in the reactor chain and applies labels before
+      // this handler fires.
+      if (!skipRisk) {
+        const hasRiskLabel = pr.labels?.some(function isRisk(l) {
+          const name = l.name ?? l;
+          return (name.endsWith('-risk') || name === 'loreli:risk-unassessed') && name.startsWith('loreli:');
+        });
+        if (!hasRiskLabel) continue;
+
+        // CRITICAL PRs must be escalated to HITL — never assign a reviewer.
+        // The label was applied by RiskWorkflow; scan() performs the escalation.
+        const isCritical = pr.labels?.some(function isCrit(l) {
+          return (l.name ?? l) === 'loreli:critical-risk';
+        });
+        if (isCritical) {
+          try {
+            await this.hitl(repo, pr.number);
+          } catch (err) {
+            log.warn(`scan: HITL failed for CRITICAL PR #${pr.number}: ${err.message}`);
+          }
+          this._completed.set(pr.number, Date.now());
+          log.info(`scan: PR #${pr.number} escalated to HITL — risk verdict CRITICAL`);
+          continue;
+        }
+
+        // Unassessed PRs (risk agent crashed, timed out, or failed to
+        // dispatch) carry risk-unassessed and must escalate to HITL.
+        // Fail-safe: never let unassessed changes through to automated review.
+        const isUnassessed = pr.labels?.some(function isUn(l) {
+          return (l.name ?? l) === 'loreli:risk-unassessed';
+        });
+        if (isUnassessed) {
+          try {
+            await this.hitl(repo, pr.number);
+          } catch (err) {
+            log.warn(`scan: HITL failed for unassessed PR #${pr.number}: ${err.message}`);
+          }
+          this._completed.set(pr.number, Date.now());
+          log.info(`scan: PR #${pr.number} escalated to HITL — risk assessment failed`);
+          continue;
+        }
+      }
+
+      // Attach risk context for MEDIUM PRs so the reviewer sees the warning
+      let riskContext = null;
+      const isMedium = pr.labels?.some(function isMed(l) {
+        return (l.name ?? l) === 'loreli:medium-risk';
+      });
+      if (isMedium) {
+        const comments = await this.hub.comments(repo, pr.number);
+        const riskComment = comments.find(function hasRisk(c) { return has(c.body, 'risk'); });
+        if (riskComment) riskContext = { assessment: riskComment.body };
+      }
+
+      const assigned = new Set(
+        [...this._watched.values()].map(function name(t) { return t.reviewer; })
+      );
+      const reviewers = [...this.orchestrator.agents.values()]
+        .filter(function isAvailable(a) {
+          if (a.role !== 'reviewer') return false;
+          return !assigned.has(a.identity?.name);
+        });
+
+      // Verify a reviewer is available BEFORE claiming. Claiming
+      // without an available reviewer creates a deadlock: the next tick
+      // sees the review-claim, skips the PR, but no reviewer was
+      // dispatched so the PR is stuck forever.
+      const pairIdentity = agent?.identity ?? { provider: authorProvider };
+      let reviewer = this.pair(pairIdentity, reviewers);
+      if (!reviewer && allowSameSide && reviewers.length) {
+        reviewer = reviewers[0];
+      }
+      if (!reviewer) {
+        log.debug(`scan: no reviewer available for PR #${pr.number} — waiting for scale()`);
+        continue;
+      }
+
+      // Optimistic claim: post a review-claim marker on the PR,
+      // then verify this agent was first. Prevents two reactors
+      // from both dispatching reviewers for the same PR.
+      // Skip for evicted PRs and released claims — the old claim
+      // comment still exists on GitHub and would win the first-
+      // comment race. We already verified the claim is dead above.
+      const claimIdentity = reviewer.identity ?? this.orchestrator.clientIdentity;
+      if (claimIdentity && !wasEvicted && !wasReleased) {
+        const visible = reviewer.identity?.claim?.() ?? `Claimed by **${claimIdentity.name}**`;
+        const won = await this.claimFirst(repo, pr.number, 'review-claim', claimIdentity, 'reviewer', visible);
+        if (!won) {
+          log.info(`scan: lost review-claim race for PR #${pr.number} — skipping`);
+          continue;
+        }
+      }
+
+      const home = this.orchestrator.storage?.home;
+      const wsRoot = home ? `${home}/workspaces` : undefined;
+      const reviewerCwd = reviewer.cwd ?? pathFor(reviewer.identity.name, wsRoot);
+      const base = this.orchestrator.cfg?.get?.('merge.base') ?? 'main';
+      const options = workspaceOptions(this.orchestrator, repo, reviewer.identity.name);
+      try {
+        await checkout(reviewerCwd, pr.head, base, options);
+        log.info(`scan: checked out ${pr.head} in ${reviewer.identity.name}'s workspace`);
+      } catch (err) {
+        log.warn(`scan: branch checkout failed for ${reviewer.identity.name}: ${err.message} — skipping PR`);
+        continue;
+      }
+
+      const files = await this.hub.files(repo, pr.number);
+
+      await this.saveTask(reviewer.identity.name, {
+        type: 'review_pr',
+        pr: pr.number
+      });
+
+      const templateVars = {
+        name: reviewer.identity.name,
+        repo,
+        faction: reviewer.identity.faction,
+        provider: reviewer.identity.provider,
+        model: reviewer.identity.model,
+        labels: reviewer.identity.labels?.('reviewer'),
+        pullRequest: {
+          number: pr.number,
+          title: pr.title,
+          head: pr.head,
+          base: pr.base,
+          issue: excise(pr.body, 'trace') ?? pr.body,
+          author: agent?.identity?.name ?? authorName,
+          authorProvider: agent?.identity?.provider ?? authorProvider,
+          files
+        }
+      };
+      if (riskContext) templateVars.riskContext = riskContext;
+
+      await this.dispatch(reviewer, templateVars);
+      this.orchestrator.activity(reviewer.identity.name);
+
+      const restored = this._evictedRounds.get(pr.number)?.rounds ?? 0;
+      this._evictedRounds.delete(pr.number);
+
+      this._watched.set(pr.number, {
+        agent: agent?.identity?.name ?? authorName,
+        reviewer: reviewer.identity.name,
+        rounds: restored,
+        dispatchedAt: Date.now()
+      });
+
+      dispatched.push({ pr: pr.number, reviewer: reviewer.identity.name });
+      log.info(`scan: dispatched ${reviewer.identity.name} to review PR #${pr.number}`);
+    }
+
+    return dispatched;
+  }
+
+  // ── Restart ─────────────────────────────────────────
+
+  /**
+   * Close a stale PR and release its linked issue when the action
+   * agent is dead. Posts a themed comment on the PR, closes it via
+   * hub.closePull(), posts a `restart` marker on the linked issue
+   * (resets the circuit breaker counter), removes blocking labels,
+   * and kills the assigned reviewer.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} prNum - Pull request number.
+   * @param {object} tracking - Tracked PR state from _watched.
+   * @returns {Promise<void>}
+   */
+  async _restartAction(repo, prNum, tracking) {
+    const identity = this.orchestrator.clientIdentity;
+
+    // Derive the linked issue number from the PR branch name.
+    // Convention: {agent}/issue-{N}
+    let issueNum = null;
+    try {
+      const pr = await this.hub.pull(repo, prNum);
+      const match = pr.head?.match(/\/issue-(\d+)$/);
+      if (match) issueNum = Number(match[1]);
+    } catch (err) {
+      log.warn(`_restartAction: failed to fetch PR #${prNum}: ${err.message}`);
+    }
+
+    // Post a themed comment on the PR before closing.
+    if (identity) {
+      try {
+        await this.hub.as(identity, 'orchestrator')
+          .comment(repo, prNum,
+            `**Restarting** — action agent \`${tracking.agent}\` is no longer available. ` +
+            'Closing this PR and releasing the linked issue for re-dispatch.');
+      } catch (err) {
+        log.warn(`_restartAction: comment failed on PR #${prNum}: ${err.message}`);
+      }
+    }
+
+    try {
+      await this.hub.closePull(repo, prNum);
+    } catch (err) {
+      log.warn(`_restartAction: closePull failed for PR #${prNum}: ${err.message}`);
+    }
+
+    // Post restart marker on the linked issue — claimant() treats
+    // this as a release, and the circuit breaker uses it as a high-
+    // water mark (releases before this point are ignored).
+    if (issueNum && identity) {
+      try {
+        const restartMarker = mark('restart', { agent: tracking.agent });
+        await this.hub.as(identity, 'orchestrator')
+          .comment(repo, issueNum, `${restartMarker}\nAction restarted — previous agent \`${tracking.agent}\` was unavailable.`);
+      } catch (err) {
+        log.warn(`_restartAction: restart marker failed on issue #${issueNum}: ${err.message}`);
+      }
+
+      // Remove blocking labels so dispatch can pick up the issue.
+      try {
+        await this.hub.unlabel(repo, issueNum, 'loreli:blocked');
+        await this.hub.unlabel(repo, issueNum, 'loreli:needs-attention');
+      } catch (err) {
+        log.warn(`_restartAction: unlabel failed on issue #${issueNum}: ${err.message}`);
+      }
+    }
+
+    this._watched.delete(prNum);
+    this._completed.set(prNum, Date.now());
+
+    // Kill the reviewer — the PR is closed, no review needed.
+    if (tracking.reviewer && this.orchestrator.agents.has(tracking.reviewer)) {
+      try {
+        await this.orchestrator.kill(tracking.reviewer);
+      } catch (err) {
+        log.warn(`_restartAction: kill reviewer ${tracking.reviewer} failed: ${err.message}`);
+      }
+    }
+
+    log.info(`forward: restarted PR #${prNum} — action agent ${tracking.agent} is dead` +
+      (issueNum ? `, issue #${issueNum} released for re-dispatch` : ''));
+  }
+
+  // ── Forward ───────────────────────────────────────────
+
+  /**
+   * Poll for new reviews on tracked PRs. If REQUEST_CHANGES, relay
+   * feedback to the action agent. Enforces maxRounds escalation.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<Array<{pr: number, action: string}>>}
+   */
+  async forward(repo) {
+    if (!this._watched.size) return [];
+
+    const maxRounds = this.orchestrator.cfg?.get?.('watch.maxRounds') ?? 7;
+    const forwarded = [];
+
+    for (const [prNum, tracking] of this._watched) {
+      const reviews = await this.hub.reviews(repo, prNum);
+
+      const latest = reviews
+        .filter(function fromReviewer(r) { return r.author === tracking.reviewer || r.state === 'CHANGES_REQUESTED'; })
+        .at(-1);
+
+      if (!latest || latest.state === 'APPROVED') continue;
+      if (latest.state !== 'CHANGES_REQUESTED') continue;
+
+      // Deduplicate: skip if this exact review was already relayed.
+      if (tracking.lastReviewId === latest.id) {
+        // Check if the action agent has pushed new commits since the
+        // review. If so, re-dispatch the reviewer.
+        const agent = this.orchestrator.agents.get(tracking.agent);
+        if (agent && latest.commitId) {
+          const pr = await this.hub.pull(repo, prNum);
+          const headSha = pr?.headSha ?? pr?.head;
+          if (headSha && headSha !== latest.commitId && !tracking.reviewerDispatched) {
+            await this._redispatch(repo, prNum, tracking, agent);
+          }
+        }
+        continue;
+      }
+
+      tracking.rounds++;
+      if (tracking.rounds >= maxRounds) {
+        log.warn(`forward: PR #${prNum} exceeded ${maxRounds} review rounds — escalating`);
+        await this._escalate(repo, prNum, tracking);
+        continue;
+      }
+
+      const agent = this.orchestrator.agents.get(tracking.agent);
+      if (!agent) {
+        await this._restartAction(repo, prNum, tracking);
+        continue;
+      }
+
+      const prompt = await this.renderFrom(ACTION_TEMPLATE, {
+        name: agent.identity.name,
+        repo,
+        faction: agent.identity.faction,
+        provider: agent.identity.provider,
+        model: agent.identity.model,
+        labels: agent.identity.labels?.('action'),
+        reviewFeedback: {
+          number: prNum,
+          reviewer: tracking.reviewer,
+          reviewerProvider: this.orchestrator.agents.get(tracking.reviewer)?.identity?.provider ?? 'unknown',
+          comments: [{ body: latest.body }]
+        }
+      }, { role: 'action' });
+
+      // Respawn the agent if it crashed or was evicted since the last tick.
+      if (agent.state === 'dormant') await agent.spawn();
+
+      await agent.send(prompt);
+      this.orchestrator.activity(agent.identity.name);
+      tracking.lastReviewId = latest.id;
+
+      const feedbackEnabled = this.orchestrator.cfg?.get?.('feedback.enabled') ?? true;
+      if (feedbackEnabled && latest.body) {
+        try {
+          const { category, confidence } = await classify(latest.body, {
+            backends: this.orchestrator.backendRegistry,
+            config: this.orchestrator.cfg
+          });
+          if (confidence > 0) {
+            const identity = this.orchestrator.clientIdentity;
+            const provider = this.orchestrator.agents.get(tracking.reviewer)?.identity?.provider ?? 'unknown';
+            const marker = mark('feedback', { category, confidence: confidence.toFixed(2), provider });
+            const visible = `Feedback routing note: classified latest review as **${category}** (${confidence.toFixed(2)} confidence).`;
+            try {
+              if (identity) await this.hub.as(identity, 'orchestrator').comment(repo, prNum, `${marker}\n${visible}`);
+              log.debug(`forward: classified feedback on PR #${prNum} as ${category} (${confidence.toFixed(2)})`);
+            } catch (err) { log.debug(`forward: feedback marker failed: ${err.message}`); }
+          }
+        } catch (err) { log.debug(`forward: feedback classification unavailable, skipping marker: ${err.message}`); }
+      }
+
+      // Reset so _redispatch can fire again when the action agent
+      // pushes another round of changes.
+      tracking.reviewerDispatched = false;
+
+      forwarded.push({ pr: prNum, action: tracking.agent });
+
+      log.info(`forward: relayed feedback on PR #${prNum} to ${tracking.agent} (round ${tracking.rounds})`);
+    }
+
+    // ── Conflict nudge ──────────────────────────────────
+    // Check watched PRs for merge conflicts and nudge the action agent
+    // to rebase. GitHub computes mergeable asynchronously on single-PR
+    // fetches — null means pending, skip until next tick.
+    for (const [prNum, tracking] of this._watched) {
+      const agent = this.orchestrator.agents.get(tracking.agent);
+      if (!agent) continue;
+
+      let pr;
+      try {
+        pr = await this.hub.pull(repo, prNum);
+      } catch (err) {
+        log.debug(`forward: conflict check skipped for PR #${prNum}: ${err.message}`);
+        continue;
+      }
+      if (pr.mergeable == null) continue;
+
+      if (pr.mergeable) {
+        if (tracking.conflictNotifiedSha) {
+          log.info(`forward: PR #${prNum} conflict resolved`);
+          tracking.conflictNotifiedSha = null;
+        }
+        continue;
+      }
+
+      if (tracking.conflictNotifiedSha === pr.headSha) continue;
+
+      if (agent.state === 'dormant') await agent.spawn();
+
+      const base = pr.base || 'main';
+      await agent.send(
+        `Your pull request #${prNum} has merge conflicts with \`${base}\`. ` +
+        `Rebase your branch onto \`origin/${base}\`, resolve the conflicts, ` +
+        `and force-push to update the PR.`
+      );
+      this.orchestrator.activity(agent.identity.name);
+      tracking.conflictNotifiedSha = pr.headSha;
+
+      log.info(`forward: nudged ${tracking.agent} to resolve conflict on PR #${prNum}`);
+    }
+
+    return forwarded;
+  }
+
+  // ── Land ──────────────────────────────────────────────
+
+  /**
+ * Detect approved reviews on tracked PRs. Requires cross-provider
+ * approval. Auto-merges or triggers Human In The Loop (HITL).
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<Array<{pr: number, merged: boolean, gated: boolean, agent: string}>>}
+   */
+  async land(repo) {
+    if (!this._watched.size) return [];
+
+    const method = this.orchestrator.cfg?.get?.('merge.method') ?? 'squash';
+    const globalHitl = this.orchestrator.cfg?.get?.('merge.hitl') ?? false;
+    const feedbackHitl = this.orchestrator.cfg?.get?.('feedback.hitl') ?? false;
+    const humanReviewers = this.orchestrator.cfg?.get?.('reviewers') ?? [];
+    let dualSide = true;
+
+    try {
+      await this.orchestrator.backendRegistry?.discover?.();
+      const providers = this.orchestrator.backendRegistry?.providers?.() ?? [];
+      dualSide = capability(providers).hasDual;
+    } catch { /* non-fatal: keep strict gate */ }
+
+    const landed = [];
+
+    for (const [prNum, tracking] of this._watched) {
+      const reviews = await this.hub.reviews(repo, prNum);
+      const approval = reviews.find(function approved(r) {
+        return r.state === 'APPROVED';
+      });
+
+      if (!approval) continue;
+
+      // Verify cross-provider
+      const agent = this.orchestrator.agents.get(tracking.agent);
+      const reviewer = this.orchestrator.agents.get(tracking.reviewer);
+      if (tracking.agent === tracking.reviewer) {
+        log.warn(`land: PR #${prNum} approved by same identity — not sufficient`);
+        continue;
+      }
+
+      if (dualSide && agent && reviewer && side(agent.identity.provider) === side(reviewer.identity.provider)) {
+        log.warn(`land: PR #${prNum} approved by same-side reviewer in dual-side mode — not sufficient`);
+        continue;
+      }
+
+      // Post audit trail comment before merging or gating — mandatory
+      // so every merged PR has a Loreli-signed approval record.
+      if (reviewer) {
+        await this.signoff(repo, prNum, reviewer.identity, reviewer.role ?? 'reviewer');
+      }
+
+      let needsHitl = globalHitl;
+
+      if (!needsHitl && feedbackHitl !== false) {
+        const prData = await this.hub.read(repo, prNum);
+        const closesMatch = prData.body?.match(/Closes #(\d+)/);
+        if (closesMatch) {
+          try {
+            const issueData = await this.hub.read(repo, Number(closesMatch[1]));
+            const fbLabel = (issueData.labels ?? []).find(function isFeedback(l) {
+              const name = typeof l === 'string' ? l : l.name;
+              return name?.startsWith('loreli:feedback:');
+            });
+            if (fbLabel) {
+              const category = (typeof fbLabel === 'string' ? fbLabel : fbLabel.name)
+                .replace('loreli:feedback:', '');
+              needsHitl = feedbackHitl === true || feedbackHitl.includes(category);
+            }
+          } catch (err) {
+            log.warn(`land: feedback HITL check failed for PR #${prNum}: ${err.message}`);
+          }
+        }
+      }
+
+      if (needsHitl && humanReviewers.length) {
+        await this.hitl(repo, prNum);
+        this._watched.delete(prNum);
+        this._completed.set(prNum, Date.now());
+        landed.push({ pr: prNum, merged: false, gated: true, agent: tracking.agent });
+        log.info(`land: PR #${prNum} escalated to HITL`);
+      } else {
+        try {
+          await this.hub.merge(repo, prNum, { method });
+          await this.reconcile(repo, prNum);
+          this._watched.delete(prNum);
+          this._completed.set(prNum, Date.now());
+          landed.push({ pr: prNum, merged: true, gated: false, agent: tracking.agent });
+          log.info(`land: PR #${prNum} merged via ${method}`);
+        } catch (err) {
+          // Merge failure escalation: alert humans instead of silently
+          // abandoning. 405 = not mergeable, 409 = merge conflict.
+          this._watched.delete(prNum);
+          this._completed.set(prNum, Date.now());
+          landed.push({ pr: prNum, merged: false, gated: false, agent: tracking.agent });
+
+          try {
+            const signer = this.agents()[0]?.identity ?? this.orchestrator.clientIdentity;
+            const body = `${mark('hitl')}\n**Merge failed — needs human attention**\n\n` +
+              `Auto-merge failed: \`${err.message}\`\n\n` +
+              `Please resolve the issue and merge manually.`;
+            if (signer) {
+              await this.hub.as(signer, 'reviewer').comment(repo, prNum, body);
+            } else {
+              await this.hub.comment(repo, prNum, body);
+            }
+            await this.hub.label(repo, prNum, ['loreli:needs-attention', 'loreli:merge-failed']);
+          } catch (labelErr) {
+            log.warn(`land: failed to label merge-failure on PR #${prNum}: ${labelErr.message}`);
+          }
+
+          log.warn(`land: merge failed for PR #${prNum}: ${err.message}`);
+        }
+      }
+
+      // Kill the reviewer immediately — the PR is done (merged, gated,
+      // or failed). Waiting for the reap sweep would leave interactive
+      // reviewers stuck in 'working' state for up to a full tick cycle.
+      if (tracking.reviewer && this.orchestrator.agents.has(tracking.reviewer)) {
+        try {
+          await this.orchestrator.kill(tracking.reviewer);
+          log.info(`land: stopped reviewer ${tracking.reviewer} — PR #${prNum} finalized`);
+        } catch (err) {
+          log.warn(`land: failed to stop reviewer ${tracking.reviewer}: ${err.message}`);
+        }
+      }
+    }
+
+    // Kill action agents whose PRs were finalized (merged, gated, or
+    // failed). Only targets agents that owned a landed PR — unrelated
+    // action agents working on other issues are left untouched.
+    const landedAgents = new Set(landed.map(function agent(l) { return l.agent; }));
+    for (const name of landedAgents) {
+      if (!name || !this.orchestrator.agents.has(name)) continue;
+      try {
+        await this.orchestrator.kill(name);
+        log.info(`land: stopped action agent ${name} — PR finalized`);
+      } catch (err) {
+        log.warn(`land: failed to stop action agent ${name}: ${err.message}`);
+      }
+    }
+
+    return landed;
+  }
+
+  // ── Reap (HITL Timeout) ───────────────────────────────
+
+  /**
+   * Scan for stale HITL items that have timed out without human response.
+   * Applies loreli:stale label and re-pings configured reviewers.
+   * Idempotent — items already labeled loreli:stale are skipped.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<void>}
+   */
+  async reap(repo) {
+    const timeout = this.orchestrator.cfg?.get?.('hitl.timeout');
+    if (timeout == null) return;
+
+    const items = await this.hub.pulls(repo, { state: 'open' });
+    const needsAttention = [];
+    for (const pr of items) {
+      if (!pr.labels?.some(function isNeedsAttention(l) { return (l.name ?? l) === 'loreli:needs-attention'; })) continue;
+      if (pr.labels?.some(function isStale(l) { return (l.name ?? l) === 'loreli:stale'; })) continue;
+      needsAttention.push(pr);
+    }
+
+    if (!needsAttention.length) return;
+
+    const now = Date.now();
+    const reviewers = this.orchestrator.cfg?.get?.('reviewers') ?? [];
+
+    for (const pr of needsAttention) {
+      const comments = await this.hub.comments(repo, pr.number);
+      const hitlComment = comments.find(function isHitl(c) { return has(c.body, 'hitl'); });
+      if (!hitlComment) continue;
+
+      const elapsed = now - new Date(hitlComment.created ?? hitlComment.created_at).getTime();
+      if (elapsed < timeout) continue;
+
+      const mentions = reviewers.length
+        ? reviewers.map(function mention(r) { return `@${r}`; }).join(', ')
+        : '';
+
+      const signer = this.agents()[0]?.identity ?? this.orchestrator.clientIdentity;
+      if (signer) {
+        try {
+          const scoped = this.hub.as(signer, 'reviewer');
+          const msg = mentions
+            ? `**HITL reminder** — ${mentions}\n\nThis PR has been awaiting human attention for over ${Math.round(elapsed / 3600000)} hours.`
+            : `**HITL reminder**\n\nThis PR has been awaiting human attention for over ${Math.round(elapsed / 3600000)} hours.`;
+          await scoped.comment(repo, pr.number, msg);
+        } catch (err) {
+          log.warn(`reap: failed to post reminder on PR #${pr.number}: ${err.message}`);
+        }
+      }
+
+      try {
+        await this.hub.label(repo, pr.number, ['loreli:stale']);
+      } catch (err) {
+        log.warn(`reap: failed to label PR #${pr.number} as stale: ${err.message}`);
+      }
+
+      log.warn(`reap: PR #${pr.number} marked stale — HITL timeout exceeded (${Math.round(elapsed / 3600000)}h)`);
+    }
+  }
+
+  // ── HITL ──────────────────────────────────────────────
+
+  /**
+   * Activate Human In The Loop (HITL) for a PR.
+   *
+   * Requests review from configured human reviewers, posts a summary
+   * comment, and kills active agents to conserve resources.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} pr - Pull request number.
+   * @returns {Promise<{hitlAt: string, reviewers: string[]}>}
+   * @throws {Error} When no human reviewers are configured.
+   */
+  async hitl(repo, pr) {
+    log.info(`hitl PR #${pr} on ${repo}`);
+    const reviewers = this.orchestrator.cfg?.get?.('reviewers') ?? [];
+    if (!reviewers.length) throw new Error('No reviewers configured for HITL');
+
+    await this.hub.request(repo, pr, reviewers);
+    await this.hub.assign(repo, pr, reviewers);
+
+    // Post summary comment tagging reviewers with themed HITL message
+    const mentions = reviewers.map(function mention(r) { return `@${r}`; }).join(', ');
+
+    // Use first reviewer agent's identity for the signature,
+    // fall back to orchestrator's client identity
+    const reviewerAgent = this.agents()[0];
+    const signer = reviewerAgent?.identity ?? this.orchestrator.clientIdentity;
+    if (!signer) throw new Error('hitl() requires at least one reviewer agent or a client identity');
+
+    const hitlMarker = mark('hitl');
+    const visible = signer.hitl?.(mentions) ?? `**Human review required**\n\nAgent review is complete. ${mentions} — please review and merge when satisfied.`;
+    const body = `${hitlMarker}\n${visible}`;
+
+    const scoped = this.hub.as(signer, reviewerAgent?.role ?? 'reviewer');
+    await scoped.comment(repo, pr, body);
+
+    // Kill all active agents for this session
+    const names = [...this.orchestrator.agents.keys()];
+    for (const name of names) {
+      await this.orchestrator.kill(name);
+    }
+
+    const hitlAt = new Date().toISOString();
+    return { hitlAt, reviewers };
+  }
+
+  // ── Re-dispatch ─────────────────────────────────────────
+
+  /**
+   * Re-dispatch the reviewer for re-review after an action agent has
+   * pushed new commits.
+   *
+   * Also removes the stale `loreli:changes-requested` label — the
+   * action agent addressed the feedback, so the label no longer
+   * reflects the current PR state.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} prNum - Pull request number.
+   * @param {object} tracking - Tracked PR state from _watched.
+   * @param {object} agent - The action agent.
+   * @returns {Promise<void>}
+   */
+  async _redispatch(repo, prNum, tracking, agent) {
+    // Remove stale changes-requested label — the action agent has
+    // pushed new commits addressing the feedback.
+    try {
+      await this.hub.unlabel(repo, prNum, 'loreli:changes-requested');
+    } catch (err) { log.debug(`_redispatch: unlabel failed: ${err.message}`); }
+
+    const reviewer = this.orchestrator.agents.get(tracking.reviewer);
+    if (!reviewer) {
+      log.warn(`_redispatch: reviewer ${tracking.reviewer} not found — cannot re-dispatch`);
+      return;
+    }
+
+    try {
+      const [files, prDetails] = await Promise.all([
+        this.hub.files(repo, prNum),
+        this.hub.pull(repo, prNum)
+      ]);
+      const prompt = await this.render({
+        name: reviewer.identity.name,
+        repo,
+        faction: reviewer.identity.faction,
+        provider: reviewer.identity.provider,
+        model: reviewer.identity.model,
+        labels: reviewer.identity.labels?.('reviewer'),
+        pullRequest: {
+          number: prNum,
+          title: prDetails?.title ?? `Re-review PR #${prNum}`,
+          head: prDetails?.head ?? `${agent.identity.name}/work`,
+          base: prDetails?.base ?? this.orchestrator.cfg?.get?.('merge.base') ?? 'main',
+          issue: 'Re-review after feedback was addressed.',
+          author: agent.identity.name,
+          authorProvider: agent.identity.provider,
+          files
+        }
+      });
+
+      await reviewer.send(prompt);
+      this.orchestrator.activity(reviewer.identity.name);
+      tracking.reviewerDispatched = true;
+      log.info(`_redispatch: re-dispatched ${reviewer.identity.name} for re-review of PR #${prNum}`);
+    } catch (err) {
+      log.warn(`_redispatch: re-dispatch failed for PR #${prNum}: ${err.message}`);
+    }
+  }
+
+  // ── Escalation ────────────────────────────────────────
+
+  /**
+   * Escalate a stalemate when maxRounds is exceeded.
+   *
+   * If human reviewers are configured, triggers HITL.
+   * Otherwise, creates a discussion in the Loreli category describing
+   * the stalemate and labels the PR for attention.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} prNum - Pull request number.
+   * @param {object} tracking - Tracked PR state.
+   * @returns {Promise<void>}
+   */
+  async _escalate(repo, prNum, tracking) {
+    const humanReviewers = this.orchestrator.cfg?.get?.('reviewers') ?? [];
+
+    if (humanReviewers.length) {
+      await this.hitl(repo, prNum);
+      this._watched.delete(prNum);
+      this._completed.set(prNum, Date.now());
+      log.info(`escalate: PR #${prNum} handed to human reviewers after ${tracking.rounds} rounds`);
+      return;
+    }
+
+    // No human reviewers — escalation is terminal and blocking.
+    // The PR stays open with loreli:needs-attention + loreli:escalated
+    // until a human intervenes. Auto-approval is never performed.
+    const signer = this.orchestrator.agents.get(tracking.reviewer)?.identity
+      ?? this.orchestrator.clientIdentity;
+
+    if (signer) {
+      try {
+        const scoped = this.hub.as(signer, 'reviewer');
+        await scoped.comment(repo, prNum,
+          `${mark('hitl')}\n**Escalation — needs human attention**\n\n` +
+          `This PR exceeded ${tracking.rounds} review rounds without convergence. ` +
+          'A human must review and decide whether to merge, close, or provide direction.');
+      } catch (err) {
+        log.warn(`escalate: comment failed for PR #${prNum}: ${err.message}`);
+      }
+    }
+
+    try {
+      await this.hub.label(repo, prNum, ['loreli:needs-attention', 'loreli:escalated']);
+    } catch (err) { log.warn(`escalate: labeling failed for PR #${prNum}: ${err.message}`); }
+  }
+}