loreli 0.0.0 → 1.0.0

package/packages/planner/src/index.js

@@ -0,0 +1,1166 @@
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Workflow } from 'loreli/workflow';
+import { Identity, capability } from 'loreli/identity';
+import { mark, has, parse } from 'loreli/marker';
+import { classifyRefs, extractRefs } from 'loreli/knowledge';
+import { logger } from 'loreli/log';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const log = logger('planner');
+
+/**
+ * Path to the plan-reviewer prompt template. Used for rendering the
+ * adversarial plan review prompt via cross-role rendering.
+ *
+ * @type {string}
+ */
+const PLAN_REVIEWER_TEMPLATE = join(__dirname, '..', 'prompts', 'plan-reviewer.md');
+
+/**
+ * Path to the tiebreaker-reviewer prompt template. Used when a discussion
+ * has exhausted maxRounds of revision and needs pragmatic evaluation.
+ *
+ * @type {string}
+ */
+const TIEBREAKER_TEMPLATE = join(__dirname, '..', 'prompts', 'tiebreaker-reviewer.md');
+
+/**
+ * Planning workflow for Loreli's orchestration pipeline.
+ *
+ * Uses GitHub Discussions as the planning primitive. The planner creates
+ * discussions in a "Loreli" category, an adversarial reviewer applies
+ * labels to approve or request changes, and approved discussions are
+ * promoted to real issues for action agents.
+ *
+ * Labels act as a state machine:
+ * - No review label → needs review (dispatched to reviewer)
+ * - `loreli:changes-requested` → needs revision (dispatched to planner)
+ * - `loreli:blocked` → parked until dependency resolves
+ * - `loreli:approved` → ready for promotion (creates issue, closes discussion)
+ *
+ * @extends Workflow
+ */
+export class PlannerWorkflow extends Workflow {
+  /** @type {string} Agent role this workflow manages. */
+  static role = 'planner';
+
+  /** @type {string} Mustache template path for planner prompts. */
+  static template = join(__dirname, '..', 'prompts', 'planner.md');
+
+  /**
+   * Discussion category ID for the current planning session.
+   * Set by plan() and used across tick cycles.
+   *
+   * @type {string|null}
+   */
+  categoryId = null;
+
+  /**
+   * Set of discussion numbers currently in-flight for review.
+   * Prevents the reactor from re-dispatching the same discussion
+   * every tick while a reviewer is still working on it.
+   *
+   * @type {Set<number>}
+   */
+  _inflight = new Set();
+
+  /**
+   * Discussion number the reviewer is locked to for the current
+   * review/revision cycle. Keeps the reviewer focused on one
+   * discussion through its full review cycle (review → revision →
+   * re-review → approved) before moving to the next.
+   *
+   * @type {number|null}
+   */
+  _reviewing = null;
+
+  /**
+   * Name of the reviewer agent assigned to `_reviewing`. Used to
+   * detect when the committed reviewer has been killed or gone dormant,
+   * which means the in-flight entry is stale and should be cleared.
+   *
+   * @type {string|null}
+   */
+  _reviewerName = null;
+
+  /**
+   * Set of discussion numbers currently in-flight for revision.
+   * Prevents the reactor from re-dispatching revise prompts every
+   * tick while the planner is still processing a revision. Keeps
+   * the planner focused on one discussion through its full revision
+   * cycle before moving to the next.
+   *
+   * Entries self-clear when the discussion label changes (the planner
+   * calls `plan revise` which removes `loreli:changes-requested`).
+   *
+   * @type {Set<number>}
+   */
+  _revising = new Set();
+
+  /**
+   * Name of the reviewer agent dispatched for discussion review.
+   * Tracked so promote() only kills this agent — not PR reviewers
+   * managed by ReviewWorkflow sharing the same role.
+   *
+   * @type {string|null}
+   */
+  _discussionReviewer = null;
+
+  /**
+   * Revision round counter per discussion. Incremented each time
+   * revise() processes a non-blocked `loreli:changes-requested` discussion.
+   * At maxRounds, a tiebreaker revision is dispatched. Beyond maxRounds,
+   * HITL escalation blocks until a human intervenes.
+   *
+   * @type {Map<number, number>}
+   */
+  _revisionRounds = new Map();
+
+  /**
+   * Discussion numbers whose reviewer died during revision. Persists
+   * across ticks so the claim check can be skipped when the discussion
+   * finally exits the `changes-requested` state. Cleared after a
+   * successful re-dispatch.
+   *
+   * @type {Set<number>}
+   */
+  _cleared = new Set();
+
+  /**
+   * Blocked discussions awaiting dependency resolution.
+   * Keys are discussion numbers, values contain the discussion node ID
+   * and the open issue numbers that are blocking progress.
+   *
+   * @type {Map<number, { id: string, blockers: number[] }>}
+   */
+  _blocked = new Map();
+
+  /**
+   * Repository node ID needed for createDiscussion mutation.
+   * Stored alongside categoryId during plan().
+   *
+   * @type {string|null}
+   */
+  repositoryId = null;
+
+  /**
+   * Planning objective text. Stored by plan() so the link() reactor
+   * handler can use it as the parent tracking issue title.
+   *
+   * @type {string|null}
+   */
+  objective = null;
+
+  /**
+   * Names of planner agents that have already received the objective.
+   * Used by recover() to avoid re-dispatching to planners that were
+   * already sent the prompt (whether they completed it or not).
+   *
+   * @type {Set<string>}
+   */
+  _dispatched = new Set();
+
+  /**
+   * Report planner demand: how many open discussions need a planner
+   * agent. Planner demand is typically low — one planner handles the
+   * entire discussion lifecycle. Uses hydrated state.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<{workload: number, supply: number, deficit: number}>}
+   */
+  async demand(repo) {
+    if (!this.categoryId) return { workload: 0, supply: 0, deficit: 0 };
+
+    const all = await this.hub.discussions(repo, this.categoryId);
+    const open = all.filter(function isOpen(d) { return !d.closed; });
+
+    // Objective dispatched but planner died before creating any
+    // discussion → treat as pending workload so scale() spawns
+    // a replacement planner.
+    const pending = this.objective && all.length === 0;
+    const workload = open.length > 0 || pending ? 1 : 0;
+    const supply = this.agents().filter(function active(a) {
+      return a.state !== 'dormant';
+    }).length;
+
+    return { workload, supply, deficit: Math.max(0, workload - supply) };
+  }
+
+  /**
+   * Register reactor handlers for the orchestrator's tick loop.
+   *
+   * Tick order: hydrate → unblock → revise → review → promote → link
+   * Hydrate runs first to recover distributed state from GitHub.
+   * unblock runs next so freshly unblocked discussions can enter
+   * review on the same tick. revise runs before review so a just-revised
+   * discussion can be reviewed immediately. link runs last to create
+   * parent tracking issues and wire sub-issue relationships after
+   * promote has created the child issues.
+   *
+   * @returns {Record<string, function>} Handler map.
+   */
+  reactor() {
+    const self = this;
+    return {
+      async 'planner-hydrate'(repo) { await self.hydrate(repo); },
+      async 'planner-recover'(repo) { await self.recover(repo); },
+      async unblock(repo) { await self.unblock(repo); },
+      async revise(repo) { await self.revise(repo); },
+      async review(repo) { await self.review(repo); },
+      async promote(repo) { await self.promote(repo); },
+      async link(repo) { await self.link(repo); },
+      async 'planner-reap'(repo) { await self.reap(repo); }
+    };
+  }
+
+  /**
+   * Rehydrate in-memory planner state from GitHub artifacts.
+   *
+   * Called at the start of each reactor tick so that discussions
+   * tracked by other participants (or lost to a process restart)
+   * are visible to revise(), review(), and promote().
+   *
+   * Derives state from:
+   * - `loreli:blocked` label → blocked discussions
+   * - `review-claim` marker comments → discussions in-flight for review
+   * - `loreli:changes-requested` label → discussions needing revision
+   * - Comment history → revision round counts
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<void>}
+   */
+  async hydrate(repo) {
+    if (!this.hub || !this.categoryId) return;
+
+    const all = await this.hub.discussions(repo, this.categoryId);
+
+    for (const d of all) {
+      if (d.closed) continue;
+
+      // Blocked: derive from loreli:blocked label
+      if (d.labels.includes('loreli:blocked') && !this._blocked.has(d.number)) {
+        const full = await this.hub.discussion(repo, d.number);
+        const blockComment = full.comments?.find(function isBlock(c) {
+          return c.body.includes('Blocked by open items');
+        });
+        const blockers = [];
+        if (blockComment) {
+          for (const m of blockComment.body.matchAll(/#(\d+)/g)) {
+            blockers.push(Number(m[1]));
+          }
+        }
+        this._blocked.set(d.number, { id: d.id, blockers });
+        continue;
+      }
+
+      // Already tracked locally
+      if (this._inflight.has(d.number)) continue;
+
+      // In-flight for review: has review-claim marker, no terminal label.
+      // Skip the committed discussion — review() handles re-dispatch
+      // via its commitment check, and re-adding it here after revise()
+      // clears it would create a deadlock (review-claim marker persists
+      // across revision cycles).
+      if (d.number === this._reviewing) continue;
+
+      if (!d.labels.includes('loreli:approved') &&
+          !d.labels.includes('loreli:changes-requested') &&
+          !d.labels.includes('loreli:blocked')) {
+        const full = await this.hub.discussion(repo, d.number);
+        const claimComment = full.comments?.find(function isClaim(c) {
+          return has(c.body, 'review-claim');
+        });
+        if (claimComment) {
+          this._inflight.add(d.number);
+          const parsed = parse(claimComment.body, 'review-claim');
+          if (parsed?.agent) this._reviewerName = parsed.agent;
+        }
+      }
+
+      // Revision rounds: count loreli:changes-requested → revision cycles.
+      // Each cycle is a reviewer requesting changes + planner revising.
+      // The count is derived from the number of review-claim markers
+      // (each review cycle starts with a new claim or re-claim).
+      if (d.labels.includes('loreli:changes-requested') &&
+          !this._revisionRounds.has(d.number)) {
+        const full = await this.hub.discussion(repo, d.number);
+        const claimCount = full.comments?.filter(function isClaim(c) {
+          return has(c.body, 'review-claim');
+        }).length ?? 0;
+        if (claimCount > 0) this._revisionRounds.set(d.number, claimCount);
+      }
+    }
+  }
+
+  /**
+   * Dispatch the planning workflow to planner agents.
+   *
+   * Finds the "Loreli" discussion category, renders the planner
+   * prompt with the given objective, and sends it to every planner
+   * agent. Returns the dispatched agent names and category ID.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {string} objective - What should be planned.
+   * @returns {Promise<{planners: string[], categoryId: string}>}
+   * @throws {Error} When no planner agents are available.
+   */
+  async plan(repo, objective) {
+    log.info(`planning: ${repo} — objective: ${objective}`);
+    const planners = this.agents();
+
+    if (!planners.length) throw new Error('No planner agents available');
+
+    this.objective = objective;
+
+    const cat = await this.hub.category(repo, 'Loreli');
+    this.categoryId = cat.id;
+    this.repositoryId = cat.repositoryId;
+    const dispatched = [];
+
+    for (const agent of planners) {
+      await this.dispatch(agent, {
+        name: agent.identity.name,
+        repo,
+        faction: agent.identity.faction,
+        provider: agent.identity.provider,
+        model: agent.identity.model,
+        objective,
+        labels: agent.identity.labels?.('planner'),
+        plan: true,
+        categoryId: cat.id,
+        repositoryId: cat.repositoryId
+      });
+
+      this.orchestrator.activity(agent.identity.name);
+      this._dispatched.add(agent.identity.name);
+      dispatched.push(agent.identity.name);
+    }
+
+    log.info(`planning dispatched to ${dispatched.length} planners`);
+    return { planners: dispatched, categoryId: cat.id };
+  }
+
+  /**
+   * Re-dispatch the planning objective to newly spawned planners.
+   *
+   * When a planner dies before creating any discussions (e.g. budget
+   * exhaustion), scale() spawns a replacement. This handler detects
+   * the new planner and sends it the original objective so planning
+   * can resume without external intervention.
+   *
+   * Runs on every reactor tick. No-ops when:
+   * - No objective is pending
+   * - Discussions already exist (original planner succeeded)
+   * - No new (undispatched, non-dormant) planners are available
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<void>}
+   */
+  async recover(repo) {
+    if (!this.objective || !this.categoryId) return;
+
+    const all = await this.hub.discussions(repo, this.categoryId);
+    if (all.length > 0) return;
+
+    const planners = this.agents().filter(function eligible(a) {
+      return a.state !== 'dormant';
+    });
+
+    for (const agent of planners) {
+      if (this._dispatched.has(agent.identity.name)) continue;
+
+      log.info(`recover: re-dispatching objective to ${agent.identity.name}`);
+      await this.dispatch(agent, {
+        name: agent.identity.name,
+        repo,
+        faction: agent.identity.faction,
+        provider: agent.identity.provider,
+        model: agent.identity.model,
+        objective: this.objective,
+        labels: agent.identity.labels?.('planner'),
+        plan: true,
+        categoryId: this.categoryId,
+        repositoryId: this.repositoryId
+      });
+
+      this.orchestrator.activity(agent.identity.name);
+      this._dispatched.add(agent.identity.name);
+    }
+  }
+
+  /**
+   * Check blocked discussions for resolved dependencies.
+   *
+   * Runs FIRST in the tick pipeline (before revise). For each discussion
+   * in the `_blocked` map, verifies whether all blocking issues/PRs have
+   * been closed or merged. When resolved, removes both `loreli:blocked`
+   * and `loreli:changes-requested` labels so the discussion re-enters
+   * the review pipeline fresh.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<void>}
+   */
+  async unblock(repo) {
+    if (!this._blocked.size) return;
+
+    for (const [num, entry] of this._blocked) {
+      const open = [];
+      for (const ref of entry.blockers) {
+        try {
+          const item = await this.hub.issue(repo, ref);
+          if (item.state === 'open') open.push(ref);
+        } catch {
+          // Reference may not exist as an issue — skip
+        }
+      }
+
+      if (!open.length) {
+        try {
+          await this.hub.removeDiscussionLabels(repo, entry.id,
+            ['loreli:blocked', 'loreli:changes-requested']);
+        } catch (err) { log.warn(`unblock: label removal failed for #${num}: ${err.message}`); }
+
+        // discussionComment requires scoping — use planner identity or client fallback
+        const signer = this.agents()[0]?.identity ?? this.orchestrator?.clientIdentity;
+        if (signer) {
+          try {
+            const scoped = this.hub.as(signer, 'planner');
+            await scoped.discussionComment(entry.id,
+              `Blockers resolved (${entry.blockers.map(function hash(n) { return '#' + n; }).join(', ')}). Restarting review.`);
+          } catch (err) { log.warn(`unblock: comment failed for #${num}: ${err.message}`); }
+        }
+
+        this._blocked.delete(num);
+        log.info(`unblock: discussion #${num} unblocked — blockers resolved`);
+      }
+    }
+  }
+
+  /**
+   * Handle discussions with `loreli:changes-requested` label.
+   *
+   * Runs SECOND in the tick pipeline (after unblock). For each discussion
+   * with changes requested:
+   *
+   * 1. Blocker detection: parse comments for issue refs, classify via LLM,
+   *    park if open blockers found
+   * 2. Round tracking: increment `_revisionRounds`
+   * 3. HITL escalation: if rounds > maxRounds, escalate to human (no auto-approve)
+   * 4. Tiebreaker: if rounds === maxRounds, dispatch with tiebreaker prompt
+   * 5. Normal: dispatch planner for standard revision
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<Array<{number: number, planner: string}>>}
+   */
+  async revise(repo) {
+    if (!this.categoryId) return [];
+
+    const all = await this.hub.discussions(repo, this.categoryId);
+    const self = this;
+
+    // Self-clear _revising for discussions whose label changed (planner
+    // successfully revised and the `loreli:changes-requested` was removed).
+    const currentCR = new Set(
+      all.filter(function hasCR(d) { return d.labels.includes('loreli:changes-requested'); })
+        .map(function num(d) { return d.number; })
+    );
+    for (const num of this._revising) {
+      if (!currentCR.has(num)) this._revising.delete(num);
+    }
+
+    const needsRevision = all.filter(function changesRequested(d) {
+      return !d.closed &&
+        d.labels.includes('loreli:changes-requested') &&
+        !d.labels.includes('loreli:rejected') &&
+        !self._blocked.has(d.number) &&
+        !self._revising.has(d.number);
+    });
+
+    // Clear in-flight tracking for discussions that now have labels —
+    // the reviewer completed their work.
+    for (const d of needsRevision) this._inflight.delete(d.number);
+
+    if (!needsRevision.length) return [];
+
+    const planner = this.agents()[0];
+    if (!planner) {
+      log.info('revise: no planner agent available — skipping');
+      return [];
+    }
+
+    const maxRounds = this.orchestrator.cfg?.get?.('watch.maxRounds') ?? 7;
+    const revised = [];
+
+    for (const disc of needsRevision) {
+      const full = await this.hub.discussion(repo, disc.number);
+
+      // ── Blocker detection via heuristic classification ──
+      const refs = extractRefs(full.comments);
+      if (refs.length) {
+        const classified = classifyRefs(full.comments, refs);
+
+        if (classified.blockers.length) {
+          // Verify classified blockers are actually open issues
+          const open = [];
+          for (const ref of classified.blockers) {
+            try {
+              const item = await this.hub.issue(repo, ref);
+              if (item.state === 'open') open.push(ref);
+            } catch {
+              // Not an issue — skip
+            }
+          }
+
+          if (open.length) {
+            try {
+              await this.hub.applyDiscussionLabels(repo, disc.id, ['loreli:blocked']);
+            } catch (err) { log.warn(`revise: label failed for #${disc.number}: ${err.message}`); }
+
+            try {
+              await this.hub.discussionComment(disc.id,
+                `Blocked by open items: ${open.map(function hash(n) { return '#' + n; }).join(', ')}. Will resume review when resolved.`);
+            } catch (err) { log.warn(`revise: comment failed for #${disc.number}: ${err.message}`); }
+
+            this._blocked.set(disc.number, { id: disc.id, blockers: open });
+            log.info(`revise: discussion #${disc.number} blocked by ${open.join(', ')}`);
+            continue;
+          }
+        }
+      }
+
+      // ── Round tracking and tiebreaker/safety-net ──
+      const rounds = (this._revisionRounds.get(disc.number) ?? 0) + 1;
+      this._revisionRounds.set(disc.number, rounds);
+
+      if (rounds > maxRounds) {
+        // HITL escalation: do NOT auto-approve. Tag humans and block.
+        try {
+          await this.hub.applyDiscussionLabels(repo, disc.id, ['loreli:needs-attention']);
+
+          const reviewers = this.orchestrator.cfg?.get?.('reviewers') ?? [];
+          const mentions = reviewers.length
+            ? reviewers.map(function mention(r) { return `@${r}`; }).join(', ')
+            : '';
+
+          const signer = planner?.identity ?? this.orchestrator?.clientIdentity;
+          if (signer) {
+            const scoped = this.hub.as(signer, planner?.role ?? 'planner');
+            const msg = mentions
+              ? `**Needs human attention** — ${mentions}\n\n` +
+                `This discussion exceeded ${rounds} revision rounds without convergence. ` +
+                'A human must review and decide how to proceed.'
+              : `**Needs human attention**\n\n` +
+                `This discussion exceeded ${rounds} revision rounds without convergence. ` +
+                'A human must review and decide how to proceed.';
+            await scoped.discussionComment(disc.id, `${mark('hitl')}\n${msg}`);
+          }
+        } catch (err) { log.warn(`revise: HITL escalation failed for #${disc.number}: ${err.message}`); }
+
+        this._inflight.delete(disc.number);
+        log.warn(`revise: HITL escalation for discussion #${disc.number} after ${rounds} rounds`);
+        continue;
+      }
+
+      const isTiebreaker = rounds === maxRounds;
+
+      // Write task context for the agent's MCP tools
+      await this.saveTask(planner.identity.name, {
+        type: 'revise_discussion',
+        discussion: full.number,
+        discussionId: full.id
+      });
+
+      await this.dispatch(planner, {
+        name: planner.identity.name,
+        repo,
+        faction: planner.identity.faction,
+        provider: planner.identity.provider,
+        model: planner.identity.model,
+        labels: planner.identity.labels?.('planner'),
+        revise: {
+          discussionId: full.id,
+          number: full.number,
+          title: full.title,
+          body: full.body,
+          comments: full.comments,
+          tiebreaker: isTiebreaker,
+          rounds,
+          maxRounds
+        },
+        categoryId: this.categoryId,
+        repositoryId: this.repositoryId
+      });
+
+      this._revising.add(disc.number);
+      this.orchestrator.activity(planner.identity.name);
+      revised.push({ number: disc.number, planner: planner.identity.name });
+      log.info(`revise: dispatched ${planner.identity.name} for discussion #${disc.number}${isTiebreaker ? ' (TIEBREAKER)' : ''}`);
+    }
+
+    return revised;
+  }
+
+  /**
+   * Dispatch discussions without review labels to a reviewer agent.
+   *
+   * Runs THIRD in the tick pipeline (after unblock and revise). Selects
+   * the appropriate reviewer template based on the discussion's revision
+   * round count:
+   * - Normal: `plan-reviewer.md` for standard adversarial review
+   * - Tiebreaker: `tiebreaker-reviewer.md` when rounds >= maxRounds
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<{reviewer: string|null, discussions: number}>}
+   */
+  async review(repo) {
+    if (!this.categoryId) return { reviewer: null, discussions: 0 };
+
+    // Clear stale in-flight entries when no productive reviewer exists.
+    // An active reviewer must be in a working state (spawned/running) —
+    // dormant agents finished their work, dead agents crashed, and
+    // stalled agents may never produce output.
+    const reviewers = [...this.orchestrator.agents.values()]
+      .filter(function isReviewer(a) { return a.role === 'reviewer'; });
+    const productive = reviewers.filter(function working(a) {
+      return a.state === 'spawned' || a.state === 'running';
+    });
+
+    if (!productive.length && this._inflight.size) {
+      for (const n of this._inflight) this._cleared.add(n);
+      log.info(`review: clearing ${this._inflight.size} stale in-flight entries — no productive reviewer (${reviewers.length} registered, 0 working)`);
+      this._inflight.clear();
+      this._reviewing = null;
+      this._reviewerName = null;
+    }
+
+    const all = await this.hub.discussions(repo, this.categoryId);
+    const self = this;
+
+    // ── Commitment check ────────────────────────────────────
+    // Lock the reviewer to a discussion's full review/revision cycle.
+    // Keeps the reviewer focused on one discussion through its full
+    // review cycle before moving to the next.
+    if (this._reviewing !== null) {
+      const committed = all.find(function locked(d) { return d.number === self._reviewing; });
+
+      if (!committed || committed.closed || committed.labels.includes('loreli:approved')) {
+        // Discussion resolved or disappeared — unlock
+        this._reviewing = null;
+        this._reviewerName = null;
+      } else if (committed.labels.includes('loreli:changes-requested') ||
+                 committed.labels.includes('loreli:blocked')) {
+        // In revision or blocked — wait for the cycle to complete
+        log.debug(`review: discussion #${this._reviewing} in revision — reviewer waiting`);
+        return { reviewer: null, discussions: 0 };
+      } else if (this._inflight.has(this._reviewing)) {
+        // Verify the committed reviewer agent is still registered and
+        // productive. A reviewer can become dormant (completed other work)
+        // or dead (killed by stall detection) while the in-flight entry
+        // lingers — without this check, the system deadlocks.
+        const assignee = this._reviewerName
+          ? this.orchestrator.agents.get(this._reviewerName)
+          : null;
+        const alive = assignee && (assignee.state === 'spawned' || assignee.state === 'running' || assignee.state === 'working');
+        if (alive) {
+          log.debug(`review: reviewer ${this._reviewerName} still working on #${this._reviewing} — waiting`);
+          return { reviewer: null, discussions: 0 };
+        }
+        // Committed reviewer is gone or dormant — clear stale state
+        log.info(`review: clearing stale commitment to #${this._reviewing} — reviewer ${this._reviewerName ?? 'unknown'} no longer active`);
+        this._cleared.add(this._reviewing);
+        this._inflight.delete(this._reviewing);
+        this._reviewing = null;
+        this._reviewerName = null;
+      }
+      // else: no label, not in _inflight → revised and needs re-review
+    }
+
+    // Pre-check: fetch discussion details for review-claim markers
+    // to avoid dispatching reviewers for discussions already claimed
+    // by another participant. Only fetch for discussions that pass
+    // the basic label filter to minimize API calls.
+    const candidates = all.filter(function unlabeled(d) {
+      if (self._reviewing !== null && d.number !== self._reviewing) return false;
+      return !d.closed &&
+        !d.labels.includes('loreli:approved') &&
+        !d.labels.includes('loreli:changes-requested') &&
+        !d.labels.includes('loreli:blocked') &&
+        !self._inflight.has(d.number);
+    });
+
+    const needsReview = [];
+    for (const d of candidates) {
+      const full = await this.hub.discussion(repo, d.number);
+      const claimed = full.comments?.some(function isClaimed(c) { return has(c.body, 'review-claim'); });
+      // Re-review: when committed to this discussion, our prior claim is from us — allow re-dispatch
+      // Stale clear: discussions we just cleared from _inflight (reviewer died) need re-dispatch
+      if (!claimed || self._reviewing === d.number || self._cleared.has(d.number)) needsReview.push(d);
+    }
+
+    log.debug(`review: ${all.length} total, ${needsReview.length} need review, ${this._inflight.size} in-flight`);
+
+    if (!needsReview.length) return { reviewer: null, discussions: 0 };
+
+    // Find the first planner to determine opposing provider
+    const planner = this.agents()[0];
+    let providers = [];
+    let mode = 'none';
+
+    try {
+      await this.orchestrator.backendRegistry?.discover?.();
+      providers = this.orchestrator.backendRegistry?.providers?.() ?? [];
+      mode = capability(providers).mode;
+    } catch { /* non-fatal: enlist fallback uses planner provider */ }
+
+    // Cross-provider pairing: find a reviewer from the opposing provider.
+    // Reuses the `reviewers` list computed above for stale in-flight detection.
+    let reviewer;
+    if (planner) {
+      reviewer = this.pair(planner.identity, reviewers);
+
+      // Prefer cross-provider review in dual-side environments.
+      // In single-side environments, fall back to any available provider.
+      if (!reviewer) {
+        if (mode === 'dual') {
+          const opposing = this.orchestrator.identityRegistry.opposite(planner.identity);
+          reviewer = await this.enlist(opposing.provider, 'reviewer');
+        } else {
+          const fallbackProvider = providers[0] ?? planner.identity.provider;
+          reviewer = await this.enlist(fallbackProvider, 'reviewer');
+        }
+      }
+    } else {
+      // Planner died (budget, crash) — infer the planner's side from
+      // the discussion body's agent stamp to maintain adversarial pairing.
+      const prefetch = await this.hub.discussion(repo, needsReview[0].number);
+      const stamp = parse(prefetch?.body, 'agent');
+      if (stamp?.provider) {
+        reviewer = this.pair({ provider: stamp.provider }, reviewers);
+      }
+      if (!reviewer) reviewer = reviewers[0] ?? null;
+    }
+
+    if (!reviewer) {
+      log.info('review: no reviewer available — skipping');
+      return { reviewer: null, discussions: 0 };
+    }
+
+    // Dispatch ONE discussion per tick. Sequential dispatch ensures each
+    // discussion gets full attention. Remaining discussions are picked
+    // up on the next tick when this method runs again.
+    const disc = needsReview[0];
+
+    const full = await this.hub.discussion(repo, disc.number);
+
+    // Optimistic claim: post a review-claim marker on the discussion,
+    // then verify this agent was first. Prevents two reactors from
+    // both dispatching reviewers for the same discussion.
+    // Skip claim when re-dispatching for a cleared discussion — the prior
+    // claim was from a dead reviewer; we are forcibly re-assigning.
+    const claimIdentity = reviewer?.identity ?? planner?.identity ?? this.orchestrator.clientIdentity;
+    if (claimIdentity && !this._cleared.has(disc.number)) {
+      const visible = reviewer?.identity?.claim?.() ?? claimIdentity.claim?.() ?? `Claimed by **${claimIdentity.name}**`;
+      const won = await this.claimFirstDiscussion(repo, disc.number, full.id, 'review-claim', claimIdentity, 'reviewer', visible);
+      if (!won) {
+        log.info(`review: lost review-claim race for discussion #${disc.number} — skipping`);
+        return { reviewer: null, discussions: 0 };
+      }
+    }
+
+    this._inflight.add(disc.number);
+    this._cleared.delete(disc.number);
+    this._reviewing = disc.number;
+    this._reviewerName = reviewer.identity.name;
+
+    await this.saveTask(reviewer.identity.name, {
+      type: 'review_discussion',
+      discussion: full.number,
+      discussionId: full.id
+    });
+
+    // Select reviewer template based on revision history
+    const maxRounds = this.orchestrator.cfg?.get?.('watch.maxRounds') ?? 7;
+    const rounds = this._revisionRounds.get(disc.number) ?? 0;
+    const template = rounds >= maxRounds ? TIEBREAKER_TEMPLATE : PLAN_REVIEWER_TEMPLATE;
+
+    const prompt = await this.renderFrom(template, {
+      name: reviewer.identity.name,
+      repo,
+      faction: reviewer.identity.faction,
+      provider: reviewer.identity.provider,
+      model: reviewer.identity.model,
+      labels: reviewer.identity.labels?.('reviewer'),
+      planReview: {
+        discussionId: full.id,
+        number: full.number,
+        title: full.title,
+        body: full.body,
+        comments: full.comments,
+        rounds,
+        maxRounds
+      }
+    }, { role: 'reviewer' });
+
+    await reviewer.send(prompt);
+    this.orchestrator.activity(reviewer.identity.name);
+    this._discussionReviewer = reviewer.identity.name;
+
+    const reviewMode = rounds >= maxRounds ? 'TIEBREAKER' : 'normal';
+    log.info(`review: dispatched ${reviewer.identity.name} for 1 discussion (#${disc.number}, ${reviewMode})`);
+    return { reviewer: reviewer.identity.name, discussions: 1 };
+  }
+
+  /**
+   * Promote approved discussions to real issues.
+   *
+   * Runs LAST in the tick pipeline. For each discussion with the
+   * `loreli:approved` label, creates a real issue, posts a closing
+   * comment linking to the issue, and closes/locks the discussion.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<Array<{number: number, title: string}>>}
+   */
+  async promote(repo) {
+    if (!this.categoryId) return [];
+
+    const all = await this.hub.discussions(repo, this.categoryId);
+    const approved = all.filter(function isApproved(d) {
+      return !d.closed && d.labels.includes('loreli:approved');
+    });
+
+    // Clear tracking state for approved discussions
+    for (const d of approved) {
+      this._inflight.delete(d.number);
+      this._revisionRounds.delete(d.number);
+      this._blocked.delete(d.number);
+      this._revising.delete(d.number);
+    }
+
+    if (!approved.length) return [];
+
+    // Get a signer for the promotion — prefer planner, fall back to any agent
+    const planner = this.agents()[0];
+    const signer = planner?.identity ?? this.orchestrator.clientIdentity;
+    if (!signer) {
+      log.warn('promote: no identity available for signing — skipping');
+      return [];
+    }
+
+    const scoped = this.hub.as(signer, planner?.role ?? 'planner');
+    const promoted = [];
+
+    for (const disc of approved) {
+      try {
+        // Strip the discussion's existing signature so open() applies
+        // exactly one fresh stamp — prevents double-signature on promoted issues.
+        const issue = await scoped.open(repo, {
+          title: disc.title,
+          body: Identity.strip(disc.body)
+        });
+
+        // Post themed closing comment linking to the new issue.
+        // GitHub auto-links #N references, so only the number is needed.
+        const visible = signer.promote?.(issue.number)
+          ?? `Promoted to issue #${issue.number}`;
+        await scoped.discussionComment(disc.id, visible);
+
+        // Close and lock the discussion
+        await this.hub.closeDiscussion(disc.id);
+
+        promoted.push({ number: issue.number, title: issue.title });
+        log.info(`promote: discussion #${disc.number} → issue #${issue.number}`);
+      } catch (err) {
+        log.warn(`promote: failed for discussion #${disc.number}: ${err.message}`);
+      }
+    }
+
+    // Signal link() to defer parent creation by one tick. Creating
+    // the parent on the same tick as promotion causes a race: the
+    // parent appears in hub.issues() queries alongside the children,
+    // inflating issue counts for consumers that poll open issues.
+    if (promoted.length) this._justPromoted = true;
+
+    // Only shut down agents when ALL discussions are resolved (approved+promoted
+    // or closed). If any open discussion still needs revision or review, the
+    // planner and reviewer must stay alive to handle it.
+    const remaining = all.filter(function unresolved(d) {
+      return !d.closed && !d.labels.includes('loreli:approved');
+    });
+
+    if (remaining.length === 0) {
+      // Clear dispatch state — planning phase is complete
+      this._reviewing = null;
+      this._reviewerName = null;
+      this._inflight.clear();
+      this._revising.clear();
+
+      const planners = this.agents();
+      for (const p of planners) {
+        try {
+          await this.orchestrator.kill(p.identity.name);
+          log.info(`promote: killed planner ${p.identity.name} — all discussions resolved`);
+        } catch (err) {
+          log.warn(`promote: failed to kill ${p.identity.name}: ${err.message}`);
+        }
+      }
+
+      // Kill only the discussion reviewer — PR reviewers share the same
+      // role but are managed by ReviewWorkflow and must not be disrupted.
+      if (this._discussionReviewer) {
+        try {
+          await this.orchestrator.kill(this._discussionReviewer);
+          log.info(`promote: killed reviewer ${this._discussionReviewer} — all discussions resolved`);
+        } catch (err) {
+          log.warn(`promote: failed to kill ${this._discussionReviewer}: ${err.message}`);
+        }
+        this._discussionReviewer = null;
+      }
+    } else {
+      log.info(`promote: ${remaining.length} discussion(s) still open — planners stay alive`);
+    }
+
+    return promoted;
+  }
+
+  /**
+   * Link promoted child issues to a parent tracking issue using GitHub
+   * sub-issues. Runs on every reactor tick after promote().
+   *
+   * All state is derived from GitHub (labels + markers), so this handler
+   * is fully idempotent and distributed-safe across multiple machines.
+   *
+   * Flow:
+   * 1. Scan for existing parent issue (loreli:parent label + marker)
+   * 2. Deduplicate racing parents (keep lowest issue number)
+   * 3. Discover unlinked child issues (loreli-labeled, agent-stamped, not parent)
+   * 4. Create parent if >= 2 children and no parent exists
+   * 5. Link unlinked children via sub-issues API
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<void>}
+   */
+  async link(repo) {
+    // Defer parent creation by one tick after any promotion. This
+    // prevents the parent from appearing in the same hub.issues()
+    // result set as the newly promoted children.
+    if (this._justPromoted) {
+      this._justPromoted = false;
+      return;
+    }
+
+    // Find existing parent issues via label scan
+    const candidates = await this.hub.issues(repo, {
+      state: 'open', labels: ['loreli:parent']
+    });
+
+    // Confirm via marker — guards against accidental manual labeling
+    const parents = candidates.filter(function confirmed(i) {
+      return has(i.body, 'parent');
+    });
+
+    let parent = null;
+
+    // Deduplicate racing parents: keep lowest number, close others
+    if (parents.length > 1) {
+      parents.sort(function byNumber(a, b) { return a.number - b.number; });
+      parent = parents[0];
+
+      for (let i = 1; i < parents.length; i++) {
+        try {
+          const signer = this.agents()[0]?.identity ?? this.orchestrator?.clientIdentity;
+          if (signer) {
+            const scoped = this.hub.as(signer, 'planner');
+            await scoped.comment(repo, parents[i].number,
+              `Duplicate parent detected. Keeping #${parent.number} as canonical parent.`);
+          }
+          // Close via direct Octokit — hub doesn't expose issue update yet
+          const [owner, name] = this.hub.parse(repo);
+          await this.hub.client.issues.update({
+            owner, repo: name, issue_number: parents[i].number, state: 'closed'
+          });
+          log.info(`link: closed duplicate parent #${parents[i].number} — keeping #${parent.number}`);
+        } catch (err) {
+          log.warn(`link: failed to close duplicate parent #${parents[i].number}: ${err.message}`);
+        }
+      }
+    } else if (parents.length === 1) {
+      parent = parents[0];
+    }
+
+    // Discover child issues: agent-stamped loreli issues that are NOT the parent.
+    // The agent marker guards against human-created issues being linked as
+    // sub-issues — only issues promoted from plans carry the stamp.
+    const all = await this.hub.issues(repo, { state: 'open', labels: ['loreli'] });
+    const children = all.filter(function isChild(i) {
+      return has(i.body, 'agent') && !has(i.body, 'parent') && i.number !== parent?.number;
+    });
+
+    if (children.length < 2 && !parent) {
+      // Not enough children for a parent hierarchy yet
+      if (children.length > 0) {
+        log.debug(`link: ${children.length} child issue(s) — waiting for more before creating parent`);
+      }
+      return;
+    }
+
+    // Create parent if needed
+    if (!parent && children.length >= 2) {
+      const signer = this.agents()[0]?.identity ?? this.orchestrator?.clientIdentity;
+      if (!signer) {
+        log.warn('link: no identity available for creating parent issue');
+        return;
+      }
+
+      const objective = this.objective ?? 'Planning objective';
+      const title = objective.split('\n')[0].slice(0, 128);
+      const taskList = children
+        .map(function line(c) { return `- [ ] #${c.number} — ${c.title}`; })
+        .join('\n');
+
+      const body = [
+        '## Objective\n',
+        objective,
+        '\n### Work Items\n',
+        taskList,
+        '\n',
+        mark('parent', { objective })
+      ].join('\n');
+
+      const scoped = this.hub.as(signer, 'planner');
+      const created = await scoped.open(repo, {
+        title,
+        body,
+        labels: ['loreli:parent']
+      });
+
+      parent = created;
+      log.info(`link: created parent issue #${parent.number} for objective: ${objective}`);
+    }
+
+    if (!parent) return;
+
+    // Get already-linked sub-issues for idempotency
+    let linked;
+    try {
+      linked = await this.hub.subs(repo, parent.number);
+    } catch {
+      // Sub-issues API may not be available — log and bail
+      log.warn('link: sub-issues API unavailable — skipping linking');
+      return;
+    }
+
+    const linkedIds = new Set(linked.map(function id(s) { return s.id; }));
+
+    // Link unlinked children
+    for (const child of children) {
+      if (linkedIds.has(child.id)) continue;
+
+      try {
+        await this.hub.sub(repo, parent.number, child.id);
+        log.info(`link: linked #${child.number} as sub-issue of #${parent.number}`);
+      } catch (err) {
+        log.warn(`link: failed to link #${child.number} to #${parent.number}: ${err.message}`);
+      }
+    }
+  }
+
+  /**
+   * Scan for stale HITL discussions that have timed out without human response.
+   * Applies loreli:stale label and re-pings configured reviewers.
+   * Idempotent — discussions 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;
+
+    if (!this.categoryId) return;
+
+    const all = await this.hub.discussions(repo, this.categoryId);
+    const needsAttention = all.filter(function hasNeedsAttention(d) {
+      return !d.closed &&
+        d.labels.includes('loreli:needs-attention') &&
+        !d.labels.includes('loreli:stale');
+    });
+
+    if (!needsAttention.length) return;
+
+    const now = Date.now();
+    const reviewers = this.orchestrator.cfg?.get?.('reviewers') ?? [];
+
+    for (const disc of needsAttention) {
+      const full = await this.hub.discussion(repo, disc.number);
+      const hitlComment = full.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, 'planner');
+          const msg = mentions
+            ? `**HITL reminder** — ${mentions}\n\nThis discussion has been awaiting human attention for over ${Math.round(elapsed / 3600000)} hours.`
+            : `**HITL reminder**\n\nThis discussion has been awaiting human attention for over ${Math.round(elapsed / 3600000)} hours.`;
+          await scoped.discussionComment(disc.id, `${mark('hitl')}\n${msg}`);
+        } catch (err) {
+          log.warn(`reap: failed to post reminder on discussion #${disc.number}: ${err.message}`);
+        }
+      }
+
+      try {
+        await this.hub.applyDiscussionLabels(repo, disc.id, ['loreli:stale']);
+      } catch (err) {
+        log.warn(`reap: failed to label discussion #${disc.number} as stale: ${err.message}`);
+      }
+
+      log.warn(`reap: discussion #${disc.number} marked stale — HITL timeout exceeded (${Math.round(elapsed / 3600000)}h)`);
+    }
+  }
+
+  /**
+   * Signal a concern or feature idea to the Loreli discussion category.
+   *
+   * Creates a discussion for adversarial review, rather than directly
+   * creating an issue. The discussion goes through the standard
+   * review → revise → approve → promote pipeline.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {string} title - Brief title for the escalation.
+   * @param {string} body - Detailed description of the concern.
+   * @param {object} [fallbackIdentity] - Identity to use when no planner agents exist.
+   * @returns {Promise<{discussionId: string, categoryId: string}>}
+   * @throws {Error} When no identity is available for signing.
+   */
+  async escalate(repo, title, body, fallbackIdentity) {
+    // Ensure category is resolved
+    if (!this.categoryId) {
+      const cat = await this.hub.category(repo, 'Loreli');
+      this.categoryId = cat.id;
+      this.repositoryId = cat.repositoryId;
+    }
+
+    const planner = this.agents()[0];
+    const signer = planner?.identity ?? fallbackIdentity;
+    if (!signer) throw new Error('Cannot escalate without an identity');
+
+    const scoped = this.hub.as(signer, planner?.role ?? 'planner');
+    const disc = await scoped.discuss(repo, {
+      title,
+      body,
+      categoryId: this.categoryId,
+      repositoryId: this.repositoryId
+    });
+
+    log.info(`escalated: "${title}" → discussion #${disc.number}`);
+    return { discussionId: disc.id, categoryId: this.categoryId };
+  }
+}