loreli 0.0.0 → 1.0.0

package/packages/hub/src/github.js

@@ -0,0 +1,1558 @@
+import { Octokit } from '@octokit/rest';
+import { BaseHub } from './base.js';
+import { logger } from 'loreli/log';
+import { mark, has, parse } from 'loreli/marker';
+
+const log = logger('hub');
+
+/**
+ * Default threshold (fraction) below which a rate limit warning is emitted.
+ * @type {number}
+ */
+const RATE_WARN_THRESHOLD = 0.2;
+
+/**
+ * Maximum retry attempts for rate-limited (429) responses.
+ * @type {number}
+ */
+const MAX_RETRIES = 3;
+
+/**
+ * Calculate exponential backoff with jitter.
+ *
+ * @param {number} attempt - Zero-based retry attempt number.
+ * @returns {number} Milliseconds to wait.
+ */
+function backoff(attempt) {
+  const base = Math.pow(2, attempt) * 1000;
+  const jitter = Math.random() * 500;
+  return base + jitter;
+}
+
+/**
+ * Parse the retry-after header from a 429 response.
+ * GitHub may send `retry-after` as seconds to wait.
+ *
+ * @param {object} [headers] - Response headers.
+ * @returns {number|null} Milliseconds to wait, or null if no header found.
+ */
+function parseRetryAfter(headers) {
+  const value = headers?.['retry-after'];
+  if (value == null) return null;
+  const seconds = parseInt(value, 10);
+  return Number.isNaN(seconds) ? null : seconds * 1000;
+}
+
+// ── Self-Review Fallback ────────────────────────────────
+
+/**
+ * Maps GitHub review event names to their resulting state values.
+ * Used when reconstructing the intended state from a COMMENT fallback.
+ *
+ * @type {Record<string, string>}
+ */
+const EVENT_TO_STATE = {
+  APPROVE: 'APPROVED',
+  REQUEST_CHANGES: 'CHANGES_REQUESTED'
+};
+
+/**
+ * Detect whether an Octokit error is a GitHub self-review rejection.
+ * GitHub returns 422 when a user tries to APPROVE or REQUEST_CHANGES
+ * on their own pull request.
+ *
+ * @param {Error} err - Error from Octokit.
+ * @param {string} event - Review event that was attempted.
+ * @returns {boolean} True if this is a self-review error.
+ */
+function isSelfReview(err, event) {
+  if (err.status !== 422) return false;
+  if (event !== 'APPROVE' && event !== 'REQUEST_CHANGES') return false;
+  const msg = err.message?.toLowerCase() ?? '';
+  return msg.includes('can not approve your own') || msg.includes('can not request changes on your own');
+}
+
+/**
+ * Post-process a normalized review to detect Loreli self-review markers.
+ * If the review is COMMENTED and contains a marker, patches the state
+ * to the intended verdict so downstream consumers see the correct state.
+ *
+ * @param {object} review - Normalized review object.
+ * @returns {object} Review with potentially patched state.
+ */
+function patchMarker(review) {
+  if (review.state !== 'COMMENTED') return review;
+
+  const data = parse(review.body, 'review-event');
+  if (data?.event) {
+    review.state = EVENT_TO_STATE[data.event] ?? review.state;
+  }
+
+  return review;
+}
+
+
+/**
+ * Normalization functions that convert GitHub API responses into
+ * provider-agnostic shapes. Exported as a static property on GitHubHub
+ * so tests can verify the normalization logic without making API calls.
+ */
+const normalize = {
+  /**
+   * Normalize a GitHub issue object.
+   *
+   * @param {object} raw - Raw GitHub issue API response.
+   * @returns {{id: number, number: number, title: string, body: string, state: string, author: string, url: string, labels: string[], created: string, updated: string}}
+   */
+  issue(raw) {
+    return {
+      id: raw.id,
+      number: raw.number,
+      title: raw.title,
+      body: raw.body ?? '',
+      state: raw.state,
+      author: raw.user?.login ?? '',
+      url: raw.html_url,
+      labels: (raw.labels ?? []).map(function extractName(l) {
+        return typeof l === 'string' ? l : l.name;
+      }),
+      created: raw.created_at,
+      updated: raw.updated_at
+    };
+  },
+
+  /**
+   * Normalize a GitHub pull request object.
+   *
+   * @param {object} raw - Raw GitHub PR API response.
+   * @returns {{number: number, title: string, body: string, state: string, head: string, headSha: string, base: string, author: string, url: string, labels: string[], merged: boolean, created: string, updated: string}}
+   */
+  pull(raw) {
+    return {
+      number: raw.number,
+      title: raw.title,
+      body: raw.body ?? '',
+      state: raw.state,
+      head: raw.head?.ref ?? '',
+      headSha: raw.head?.sha ?? '',
+      base: raw.base?.ref ?? '',
+      author: raw.user?.login ?? '',
+      url: raw.html_url,
+      labels: (raw.labels ?? []).map(function extractName(l) {
+        return typeof l === 'string' ? l : l.name;
+      }),
+      merged: raw.merged ?? false,
+      created: raw.created_at,
+      updated: raw.updated_at
+    };
+  },
+
+  /**
+   * Normalize a GitHub comment object.
+   *
+   * @param {object} raw - Raw GitHub comment API response.
+   * @returns {{id: number, body: string, author: string, created: string}}
+   */
+  comment(raw) {
+    return {
+      id: raw.id,
+      body: raw.body ?? '',
+      author: raw.user?.login ?? '',
+      created: raw.created_at
+    };
+  },
+
+  /**
+   * Normalize a GitHub review object.
+   *
+   * @param {object} raw - Raw GitHub review API response.
+   * @returns {{id: number, body: string, state: string, author: string, submitted: string, commitId: string|null}}
+   */
+  review(raw) {
+    return {
+      id: raw.id,
+      body: raw.body ?? '',
+      state: raw.state,
+      author: raw.user?.login ?? '',
+      submitted: raw.submitted_at,
+      commitId: raw.commit_id ?? null
+    };
+  }
+};
+
+/**
+ * GitHub implementation of the BaseHub interface.
+ * Uses @octokit/rest for all API interactions.
+ *
+ * @example
+ * ```js
+ * const h = new GitHubHub({ token: process.env.GITHUB_TOKEN });
+ * const issues = await h.issues('owner/repo', { state: 'open' });
+ * ```
+ */
+export class GitHubHub extends BaseHub {
+  /**
+   * Normalization functions for converting raw GitHub responses.
+   * Exposed as a static property so tests can verify shapes.
+   */
+  static normalize = normalize;
+
+  /**
+   * @param {object} opts
+   * @param {string} opts.token - GitHub personal access token.
+   */
+  constructor({ token }) {
+    super();
+
+    /**
+     * Current rate limit state, updated after every REST API call.
+     * GraphQL calls update via separate x-ratelimit headers.
+     *
+     * @type {{remaining: number|null, limit: number|null, reset: number|null, used: number|null}}
+     */
+    this.rateLimit = { remaining: null, limit: null, reset: null, used: null };
+
+    this.client = new Octokit({ auth: token });
+
+    const self = this;
+
+    /**
+     * Wrap every request to extract rate limit headers and retry on 429.
+     * Uses Octokit's hook.wrap API (before-after-hook).
+     */
+    this.client.hook.wrap('request', async function rateLimitHook(request, options) {
+      for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        let response;
+        try {
+          response = await request(options);
+        } catch (err) {
+          // Octokit throws on non-2xx; check for 429 (secondary rate limit)
+          if (err.status === 429 && attempt < MAX_RETRIES) {
+            const wait = parseRetryAfter(err.response?.headers) ?? backoff(attempt);
+            await new Promise(function delay(r) { setTimeout(r, wait); });
+            continue;
+          }
+          // Still extract rate limit info from error responses
+          if (err.response?.headers) {
+            self._updateRateLimit(err.response.headers);
+          }
+          throw err;
+        }
+
+        // Successful response — extract rate limit headers
+        if (response.headers) {
+          self._updateRateLimit(response.headers);
+        }
+
+        return response;
+      }
+    });
+  }
+
+  /**
+   * Parse rate limit headers from a GitHub API response and update internal state.
+   * Emits a warning when remaining requests drop below the configured threshold.
+   *
+   * @param {object} headers - Response headers object.
+   */
+  _updateRateLimit(headers) {
+    const remaining = parseInt(headers['x-ratelimit-remaining'], 10);
+    const limit = parseInt(headers['x-ratelimit-limit'], 10);
+    const reset = parseInt(headers['x-ratelimit-reset'], 10);
+    const used = parseInt(headers['x-ratelimit-used'], 10);
+
+    if (!Number.isNaN(remaining)) this.rateLimit.remaining = remaining;
+    if (!Number.isNaN(limit)) this.rateLimit.limit = limit;
+    if (!Number.isNaN(reset)) this.rateLimit.reset = reset;
+    if (!Number.isNaN(used)) this.rateLimit.used = used;
+
+    // Warn when below threshold — use callback if set, else log directly
+    if (this.rateLimit.remaining !== null && this.rateLimit.limit !== null && this.rateLimit.limit > 0) {
+      const ratio = this.rateLimit.remaining / this.rateLimit.limit;
+      if (ratio < RATE_WARN_THRESHOLD) {
+        const resetDate = this.rateLimit.reset ? new Date(this.rateLimit.reset * 1000).toISOString() : 'unknown';
+        if (this._onRateLimitWarning) {
+          this._onRateLimitWarning({
+            remaining: this.rateLimit.remaining,
+            limit: this.rateLimit.limit,
+            reset: resetDate,
+            ratio
+          });
+        } else {
+          log.warn(`rate limit low: ${this.rateLimit.remaining}/${this.rateLimit.limit} (${Math.round(ratio * 100)}%), resets ${resetDate}`);
+        }
+        // Early return to avoid the duplicate call below
+        return;
+      }
+    }
+  }
+
+  /**
+   * Wait for a mutation to settle in GitHub's eventually-consistent
+   * indices. After a write (issue create, file write, PR create, etc.)
+   * the corresponding list/get endpoint may not reflect the change
+   * immediately. This method retries a verification function until it
+   * returns truthy, using short exponential backoff.
+   *
+   * Applied automatically inside mutation methods so callers never
+   * need to add manual delays.
+   *
+   * @param {function} verify - Async function that returns truthy when settled.
+   * @param {string} label - Human-readable label for debug logging.
+   * @param {object} [opts] - Options.
+   * @param {number} [opts.retries=5] - Maximum retry attempts.
+   * @param {number} [opts.base=300] - Base delay in ms (doubles each attempt).
+   * @param {number} [opts.cap=5000] - Maximum delay per attempt in ms.
+   * @returns {Promise<void>}
+   */
+  async _settle(verify, label, { retries = 5, base = 300, cap = 5000 } = {}) {
+    for (let attempt = 0; attempt < retries; attempt++) {
+      try {
+        if (await verify()) return;
+      } catch { /* verification may throw before the resource is visible */ }
+
+      const wait = Math.min(base * Math.pow(2, attempt), cap);
+      log.debug(`settle(${label}): attempt ${attempt + 1}/${retries}, waiting ${wait}ms`);
+      await new Promise(function delay(r) { setTimeout(r, wait); });
+    }
+
+    // Final attempt — if this fails, log warning but don't throw.
+    // The resource was created; the index is just slow.
+    log.warn(`settle(${label}): gave up after ${retries} attempts — index may be stale`);
+  }
+
+  /**
+   * Get current rate limit information.
+   * Returns the last-observed rate limit state from GitHub API response headers.
+   *
+   * @returns {{remaining: number|null, limit: number|null, reset: string|null, used: number|null, ratio: number|null}}
+   */
+  rates() {
+    const { remaining, limit, reset, used } = this.rateLimit;
+    return {
+      remaining,
+      limit,
+      used,
+      reset: reset ? new Date(reset * 1000).toISOString() : null,
+      ratio: (remaining !== null && limit !== null && limit > 0)
+        ? Math.round((remaining / limit) * 100) / 100
+        : null
+    };
+  }
+
+  /**
+   * Register a callback invoked when rate limit drops below 20%.
+   * The callback receives `{ remaining, limit, reset, ratio }`.
+   *
+   * @param {function} fn - Warning handler.
+   */
+  set onRateLimitWarning(fn) {
+    this._onRateLimitWarning = fn;
+  }
+
+  /**
+   * Parse an "owner/repo" string into [owner, repo].
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {[string, string]} Tuple of [owner, repo].
+   */
+  parse(repo) {
+    const [owner, name] = repo.split('/');
+    return [owner, name];
+  }
+
+  /**
+   * Return a scoped hub that auto-appends the agent's signature to
+   * every content-producing GitHub call (comments, issues, PRs, drafts).
+   * Uses prototype delegation so no state leaks to the parent instance.
+   *
+   * @param {object} identity - Agent Identity instance with signature().
+   * @param {string} role - Agent role for the signature block.
+   * @returns {GitHubHub} Scoped hub.
+   */
+  as(identity, role) {
+    const scoped = Object.create(this);
+    scoped._identity = identity;
+    scoped._role = role;
+    return scoped;
+  }
+
+  /**
+   * Throw if a content-producing method is called on an unscoped hub.
+   * Every automated interaction must carry an identity for traceability.
+   *
+   * @param {string} method - Method name for the error message.
+   * @throws {Error} When the hub has not been scoped via as().
+   */
+  _guard(method) {
+    if (!this._identity) {
+      throw new Error(`hub.${method}() requires scoping — call hub.as(identity, role) first`);
+    }
+  }
+
+  /**
+   * Append the active agent signature to a body string.
+   * Injects a machine-readable agent marker before the visible signature
+   * so downstream tools can detect agent-authored content without
+   * parsing the visible markdown table.
+   *
+   * @param {string} body - Original content.
+   * @returns {string} Body with agent marker and signature appended.
+   */
+  _stamp(body) {
+    const sig = this._identity?.signature?.(this._role) ?? '';
+    if (!sig) return body;
+    const agentMarker = mark('agent', { name: this._identity.name, role: this._role, provider: this._identity.provider });
+    return `${body}\n${agentMarker}${sig}`;
+  }
+
+  /**
+   * Merge identity labels with explicitly-passed labels.
+   * When scoped, auto-includes the agent's identity labels (loreli,
+   * provider, model, role). Deduplicates the merged set.
+   *
+   * @param {string[]} [explicit] - Caller-supplied labels.
+   * @returns {string[]|undefined} Merged labels, or undefined when empty.
+   */
+  _labels(explicit) {
+    const auto = this._identity?.labels?.(this._role) ?? [];
+    if (!auto.length) return explicit ?? undefined;
+    return [...new Set([...auto, ...(explicit ?? [])])];
+  }
+
+  // --- Issues ---
+
+  /**
+   * List issues for a repository, excluding pull requests.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {object} [opts] - Filter options.
+   * @param {string} [opts.state='open'] - Issue state filter ('open', 'closed', 'all').
+   * @param {string[]} [opts.labels] - Filter by label names.
+   * @returns {Promise<Array<{number: number, title: string, body: string, state: string, author: string, url: string, labels: string[], created: string, updated: string}>>}
+   */
+  async issues(repo, opts = {}) {
+    log.debug(`issues: ${repo} state=${opts.state ?? 'open'}`);
+    const [owner, name] = this.parse(repo);
+    const data = await this.client.paginate(this.client.issues.listForRepo, {
+      owner, repo: name,
+      state: opts.state ?? 'open',
+      labels: opts.labels?.join(','),
+      per_page: 100
+    });
+    return data.filter(function notPR(i) { return !i.pull_request; }).map(normalize.issue);
+  }
+
+  /**
+   * Get a single issue by number.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Issue number.
+   * @returns {Promise<{number: number, title: string, body: string, state: string, author: string, url: string, labels: string[], created: string, updated: string}>}
+   */
+  async issue(repo, number) {
+    const [owner, name] = this.parse(repo);
+    const { data } = await this.client.issues.get({ owner, repo: name, issue_number: number });
+    return normalize.issue(data);
+  }
+
+  /**
+   * Create a new issue. Requires scoping via as(identity, role).
+   * Auto-appends signature and auto-applies identity labels.
+   * Waits for the issue to be indexed by GitHub before returning.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {object} opts - Issue options.
+   * @param {string} opts.title - Issue title.
+   * @param {string} [opts.body] - Issue body.
+   * @param {string[]} [opts.labels] - Additional label names to apply.
+   * @returns {Promise<{number: number, title: string, body: string, state: string, author: string, url: string, labels: string[], created: string, updated: string}>}
+   * @throws {Error} When hub is not scoped via as().
+   */
+  async open(repo, opts) {
+    this._guard('open');
+    log.debug(`open issue: ${repo} title="${opts.title}"`);
+    const [owner, name] = this.parse(repo);
+    const { data } = await this.client.issues.create({
+      owner, repo: name,
+      title: opts.title,
+      body: this._stamp(opts.body ?? ''),
+      labels: this._labels(opts.labels)
+    });
+
+    const result = normalize.issue(data);
+    const client = this.client;
+
+    // Verify the issue is indexed by the list endpoint before returning
+    await this._settle(async function visible() {
+      const { data: list } = await client.issues.listForRepo({
+        owner, repo: name, state: 'open', per_page: 100
+      });
+      return list.some(function match(i) { return i.number === result.number; });
+    }, `issue #${result.number}`);
+
+    return result;
+  }
+
+  /**
+   * Update an issue's fields (state, title, labels, etc.).
+   * Does NOT require scoping — this is an administrative operation
+   * used by circuit breakers and abandon logic.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Issue number.
+   * @param {object} fields - Fields to update (state, title, body, labels).
+   * @returns {Promise<{number: number, title: string, body: string, state: string, author: string, url: string, labels: string[], created: string, updated: string}>}
+   */
+  async update(repo, number, fields) {
+    log.debug(`update issue: ${repo}#${number}`);
+    const [owner, name] = this.parse(repo);
+    const { data } = await this.client.issues.update({
+      owner, repo: name, issue_number: number, ...fields
+    });
+    return normalize.issue(data);
+  }
+
+  /**
+   * Post a comment on an issue or PR. Requires scoping via as(identity, role).
+   * Auto-appends agent signature.
+   * Waits for the comment to be visible before returning.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Issue or PR number.
+   * @param {string} body - Comment body text.
+   * @returns {Promise<{id: number, body: string, author: string, created: string}>}
+   * @throws {Error} When hub is not scoped via as().
+   */
+  async comment(repo, number, body) {
+    this._guard('comment');
+    const [owner, name] = this.parse(repo);
+    const { data } = await this.client.issues.createComment({
+      owner, repo: name, issue_number: number, body: this._stamp(body)
+    });
+
+    const result = normalize.comment(data);
+    const client = this.client;
+
+    // Verify the comment is visible in the comments list
+    await this._settle(async function visible() {
+      const { data: list } = await client.issues.listComments({
+        owner, repo: name, issue_number: number
+      });
+      return list.some(function match(c) { return c.id === data.id; });
+    }, `comment #${data.id} on issue #${number}`);
+
+    return result;
+  }
+
+  /**
+   * List all comments on an issue or PR.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Issue or PR number.
+   * @returns {Promise<Array<{id: number, body: string, author: string, created: string}>>}
+   */
+  async comments(repo, number) {
+    const [owner, name] = this.parse(repo);
+    const data = await this.client.paginate(this.client.issues.listComments, {
+      owner, repo: name, issue_number: number, per_page: 100
+    });
+    return data.map(normalize.comment);
+  }
+
+  // --- Pull Requests ---
+
+  /**
+   * List pull requests for a repository.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {object} [opts] - Filter options.
+   * @param {string} [opts.state='open'] - PR state filter ('open', 'closed', 'all').
+   * @returns {Promise<Array<{number: number, title: string, body: string, state: string, head: string, base: string, author: string, url: string, labels: string[], merged: boolean, created: string, updated: string}>>}
+   */
+  async pulls(repo, opts = {}) {
+    const [owner, name] = this.parse(repo);
+    const data = await this.client.paginate(this.client.pulls.list, {
+      owner, repo: name,
+      state: opts.state ?? 'open',
+      per_page: 100
+    });
+    return data.map(normalize.pull);
+  }
+
+  /**
+   * Get a single pull request by number.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Pull request number.
+   * @returns {Promise<{number: number, title: string, body: string, state: string, head: string, base: string, author: string, url: string, labels: string[], merged: boolean, created: string, updated: string}>}
+   */
+  async pull(repo, number) {
+    const [owner, name] = this.parse(repo);
+    const { data } = await this.client.pulls.get({ owner, repo: name, pull_number: number });
+    return normalize.pull(data);
+  }
+
+  /**
+   * Create a new pull request. Requires scoping via as(identity, role).
+   * Auto-appends signature and auto-applies identity labels.
+   * Waits for the PR to be indexed before returning.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {object} opts - PR options.
+   * @param {string} opts.title - PR title.
+   * @param {string} [opts.body] - PR description.
+   * @param {string} opts.head - Source branch containing changes.
+   * @param {string} opts.base - Target branch to merge into (resolved by caller from merge.base config).
+   * @param {string[]} [opts.labels] - Additional label names to apply.
+   * @returns {Promise<{number: number, title: string, body: string, state: string, head: string, base: string, author: string, url: string, labels: string[], merged: boolean, created: string, updated: string}>}
+   * @throws {Error} When hub is not scoped via as().
+   */
+  async propose(repo, opts) {
+    this._guard('propose');
+    log.debug(`propose PR: ${repo} head=${opts.head} base=${opts.base}`);
+    const [owner, name] = this.parse(repo);
+    const { data } = await this.client.pulls.create({
+      owner, repo: name,
+      title: opts.title,
+      body: this._stamp(opts.body ?? ''),
+      head: opts.head,
+      base: opts.base
+    });
+
+    // Apply identity + explicit labels to the PR (PRs are issues in GitHub)
+    const merged = this._labels(opts.labels);
+    if (merged?.length) {
+      await this.label(repo, data.number, merged);
+    }
+
+    const result = normalize.pull(data);
+    const client = this.client;
+
+    // Verify the PR is indexed by the list endpoint before returning
+    await this._settle(async function visible() {
+      const { data: list } = await client.pulls.list({
+        owner, repo: name, state: 'open', per_page: 100
+      });
+      return list.some(function match(p) { return p.number === result.number; });
+    }, `PR #${result.number}`);
+
+    return result;
+  }
+
+  /**
+   * Merge a pull request.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Pull request number.
+   * @param {object} [opts] - Merge options.
+   * @param {string} [opts.method='squash'] - Merge method ('merge', 'squash', 'rebase').
+   * @returns {Promise<void>}
+   */
+  async merge(repo, number, opts = {}) {
+    const [owner, name] = this.parse(repo);
+    await this.client.pulls.merge({
+      owner, repo: name, pull_number: number,
+      merge_method: opts.method ?? 'squash'
+    });
+  }
+
+  /**
+   * Close a pull request without merging.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Pull request number.
+   * @returns {Promise<void>}
+   */
+  async closePull(repo, number) {
+    const [owner, name] = this.parse(repo);
+    await this.client.pulls.update({ owner, repo: name, pull_number: number, state: 'closed' });
+  }
+
+  /**
+   * List files changed in a pull request.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Pull request number.
+   * @returns {Promise<Array<{filename: string, status: string, additions: number, deletions: number}>>}
+   */
+  async files(repo, number) {
+    const [owner, name] = this.parse(repo);
+    const data = await this.client.paginate(this.client.pulls.listFiles, {
+      owner, repo: name, pull_number: number, per_page: 100
+    });
+    return data.map(function normalizeFile(f) {
+      return { filename: f.filename, status: f.status, additions: f.additions, deletions: f.deletions, patch: f.patch };
+    });
+  }
+
+  /**
+   * Fetch the unified diff for a pull request.
+   * Uses GitHub's content negotiation to return the diff as a string.
+   * Truncates to maxBytes to avoid blowing up LLM context windows.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Pull request number.
+   * @param {number} [maxBytes=102400] - Maximum diff size in bytes (default 100KB).
+   * @returns {Promise<string>} Unified diff content.
+   */
+  async diff(repo, number, maxBytes = 102400) {
+    const [owner, name] = this.parse(repo);
+    const { data } = await this.client.pulls.get({
+      owner, repo: name, pull_number: number,
+      mediaType: { format: 'diff' }
+    });
+    if (typeof data === 'string' && data.length > maxBytes) {
+      return data.slice(0, maxBytes) + '\n\n... [diff truncated at ' + maxBytes + ' bytes]';
+    }
+    return data;
+  }
+
+  // --- Reviews ---
+
+  /**
+   * Create a review on a pull request. Requires scoping via as(identity, role).
+   * Auto-appends agent signature to the review body.
+   *
+   * When the reviewer and PR author share the same token, GitHub rejects
+   * APPROVE and REQUEST_CHANGES with a 422. This method catches that
+   * error and falls back to a COMMENT review with a hidden HTML marker
+   * encoding the intended event. The marker is parsed by reviews() so
+   * downstream consumers (land, forward) see the correct state.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Pull request number.
+   * @param {object} opts - Review options.
+   * @param {string} [opts.body] - Review body text.
+   * @param {string} [opts.event='COMMENT'] - Review event ('APPROVE', 'REQUEST_CHANGES', 'COMMENT').
+   * @param {Array<{path: string, body: string, line: number}>} [opts.comments] - Inline review comments.
+   * @returns {Promise<{id: number, body: string, state: string, author: string, submitted: string}>}
+   * @throws {Error} When hub is not scoped via as().
+   */
+  async review(repo, number, opts) {
+    this._guard('review');
+    const [owner, name] = this.parse(repo);
+    const event = opts.event ?? 'COMMENT';
+    const body = this._stamp(opts.body ?? '');
+
+    try {
+      const { data } = await this.client.pulls.createReview({
+        owner, repo: name, pull_number: number,
+        body, event, comments: opts.comments
+      });
+      return normalize.review(data);
+    } catch (err) {
+      if (!isSelfReview(err, event)) throw err;
+
+      // GitHub blocks formal verdicts on your own PR. Fall back to
+      // COMMENT with a machine-readable marker so reviews() can
+      // reconstruct the intended state for downstream consumers.
+      log.info(`review: self-review detected on PR #${number}, falling back to COMMENT with marker`);
+      const marker = mark('review-event', { event });
+      const { data } = await this.client.pulls.createReview({
+        owner, repo: name, pull_number: number,
+        body: `${marker}\n${body}`,
+        event: 'COMMENT',
+        comments: opts.comments
+      });
+      const result = normalize.review(data);
+      result.state = EVENT_TO_STATE[event] ?? result.state;
+      return result;
+    }
+  }
+
+  /**
+   * List all reviews on a pull request. Post-processes COMMENTED
+   * reviews that contain the Loreli self-review marker, patching
+   * their state to the intended verdict.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Pull request number.
+   * @returns {Promise<Array<{id: number, body: string, state: string, author: string, submitted: string}>>}
+   */
+  async reviews(repo, number) {
+    const [owner, name] = this.parse(repo);
+    const data = await this.client.paginate(this.client.pulls.listReviews, {
+      owner, repo: name, pull_number: number, per_page: 100
+    });
+    return data.map(normalize.review).map(patchMarker);
+  }
+
+  /**
+   * Post an inline review comment on a specific file line in a pull request.
+   *
+   * **Reserved for future line-level review support.** Currently unused in
+   * production — the review workflow sends full-PR reviews via `review()`.
+   * Will be wired when the review workflow adds inline annotation support.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Pull request number.
+   * @param {object} opts - Annotation options.
+   * @param {string} opts.body - Comment text.
+   * @param {string} opts.path - Relative file path.
+   * @param {number} opts.line - Line number in the diff.
+   * @param {string} opts.commit - Commit SHA to attach the comment to.
+   * @returns {Promise<{id: number, body: string, author: string, created: string}>}
+   */
+  async annotate(repo, number, opts) {
+    const [owner, name] = this.parse(repo);
+    const { data } = await this.client.pulls.createReviewComment({
+      owner, repo: name, pull_number: number,
+      body: opts.body,
+      path: opts.path,
+      line: opts.line,
+      commit_id: opts.commit
+    });
+    return normalize.comment(data);
+  }
+
+  // --- Contents ---
+
+  /**
+   * Read a file or directory from a repository.
+   * Returns a single file object with decoded content, or an array
+   * of directory entries when the path is a directory.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {string} path - File or directory path within the repo.
+   * @param {object} [opts] - Read options.
+   * @param {string} [opts.ref] - Git ref (branch, tag, or SHA) to read from.
+   * @returns {Promise<{name: string, path: string, type: string, sha: string, content: string}|Array<{name: string, path: string, type: string, sha: string}>>}
+   */
+  async read(repo, path, opts = {}) {
+    const [owner, name] = this.parse(repo);
+    const { data } = await this.client.repos.getContent({
+      owner, repo: name, path, ref: opts.ref
+    });
+
+    if (Array.isArray(data)) {
+      return data.map(function normalizeEntry(e) {
+        return { name: e.name, path: e.path, type: e.type, sha: e.sha };
+      });
+    }
+
+    // Single file: decode content from base64
+    const content = data.content ? Buffer.from(data.content, 'base64').toString('utf8') : '';
+    return { name: data.name, path: data.path, type: data.type, sha: data.sha, content };
+  }
+
+  /**
+   * Create or update a file in a repository.
+   * Automatically detects whether the file exists (for SHA-based updates).
+   * Waits for the write to be readable before returning.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {string} path - File path within the repo.
+   * @param {object} opts - Write options.
+   * @param {string} opts.content - File content (UTF-8 string, base64-encoded internally).
+   * @param {string} [opts.message] - Commit message (defaults to "Update {path}").
+   * @param {string} [opts.branch] - Target branch.
+   * @returns {Promise<{path: string, sha: string}>}
+   */
+  async write(repo, path, opts) {
+    const [owner, name] = this.parse(repo);
+    const encoded = Buffer.from(opts.content).toString('base64');
+
+    // Check if file exists to get its SHA for updates
+    let sha;
+    try {
+      const existing = await this.read(repo, path, { ref: opts.branch });
+      sha = existing.sha;
+    } catch { /* file doesn't exist yet */ }
+
+    const { data } = await this.client.repos.createOrUpdateFileContents({
+      owner, repo: name, path,
+      message: opts.message ?? `Update ${path}`,
+      content: encoded,
+      branch: opts.branch,
+      sha
+    });
+
+    const result = { path: data.content.path, sha: data.content.sha };
+    const self = this;
+
+    // Verify the file is readable at its new SHA before returning
+    await this._settle(async function readable() {
+      const file = await self.read(repo, path, { ref: opts.branch });
+      return file.sha === result.sha;
+    }, `file ${path}`);
+
+    return result;
+  }
+
+  /**
+   * List contents of a directory in a repository.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {object} [opts] - Tree options.
+   * @param {string} [opts.path=''] - Directory path within the repo.
+   * @returns {Promise<Array<{name: string, path: string, type: string, sha: string}>>}
+   */
+  async tree(repo, opts = {}) {
+    const [owner, name] = this.parse(repo);
+    const { data } = await this.client.repos.getContent({
+      owner, repo: name, path: opts.path ?? ''
+    });
+    return (Array.isArray(data) ? data : [data]).map(function normalizeEntry(e) {
+      return { name: e.name, path: e.path, type: e.type, sha: e.sha };
+    });
+  }
+
+  // --- Repository ---
+
+  /**
+   * Get repository metadata.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @returns {Promise<{name: string, description: string, default_branch: string, private: boolean, url: string}>}
+   */
+  async repo(repo) {
+    const [owner, name] = this.parse(repo);
+    const { data } = await this.client.repos.get({ owner, repo: name });
+    return {
+      name: data.full_name,
+      description: data.description ?? '',
+      default_branch: data.default_branch,
+      private: data.private,
+      url: data.html_url
+    };
+  }
+
+  /**
+   * Get branch metadata.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {string} name - Branch name.
+   * @returns {Promise<{name: string, sha: string, protected: boolean}>}
+   */
+  async branch(repo, name) {
+    const [owner, repoName] = this.parse(repo);
+    const { data } = await this.client.repos.getBranch({ owner, repo: repoName, branch: name });
+    return { name: data.name, sha: data.commit.sha, protected: data.protected };
+  }
+
+  /**
+   * Create a new branch from an existing branch or the default branch.
+   * Waits for the branch to be visible via the API before returning.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {object} opts - Fork options.
+   * @param {string} opts.name - New branch name.
+   * @param {string} [opts.from] - Source branch name (defaults to repo's default branch).
+   * @returns {Promise<{name: string, sha: string}>}
+   */
+  async fork(repo, opts) {
+    const [owner, name] = this.parse(repo);
+    const sha = opts.from
+      ? (await this.branch(repo, opts.from)).sha
+      : (await this.branch(repo, (await this.repo(repo)).default_branch)).sha;
+
+    await this.client.git.createRef({
+      owner, repo: name,
+      ref: `refs/heads/${opts.name}`,
+      sha
+    });
+
+    const self = this;
+    const branchName = opts.name;
+
+    // Verify the branch is visible via the branches endpoint
+    await this._settle(async function visible() {
+      return self.branch(repo, branchName);
+    }, `branch ${branchName}`);
+
+    return { name: opts.name, sha };
+  }
+
+  // --- Labels ---
+
+  /**
+   * Add labels to an issue or pull request.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Issue or PR number.
+   * @param {string[]} labels - Label names to add.
+   * @returns {Promise<void>}
+   */
+  async label(repo, number, labels) {
+    const [owner, name] = this.parse(repo);
+    await this.client.issues.addLabels({
+      owner, repo: name, issue_number: number, labels
+    });
+  }
+
+  /**
+   * Remove a label from an issue or pull request.
+   * Silently succeeds if the label is not present (404 is swallowed).
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Issue or PR number.
+   * @param {string} name - Label name to remove.
+   * @returns {Promise<void>}
+   */
+  async unlabel(repo, number, name) {
+    const [owner, repoName] = this.parse(repo);
+    try {
+      await this.client.issues.removeLabel({
+        owner, repo: repoName, issue_number: number, name
+      });
+    } catch (err) {
+      // 404 = label not present — idempotent removal
+      if (err.status !== 404) throw err;
+    }
+  }
+
+  /**
+   * List all labels in a repository.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @returns {Promise<Array<{name: string, color: string, description: string}>>}
+   */
+  async labels(repo) {
+    const [owner, name] = this.parse(repo);
+    const { data } = await this.client.issues.listLabelsForRepo({
+      owner, repo: name, per_page: 100
+    });
+    return data.map(function norm(l) {
+      return { name: l.name, color: l.color, description: l.description ?? '' };
+    });
+  }
+
+  /**
+   * Ensure a set of labels exist in a repository, creating any that are missing.
+   * Idempotent — safe to call repeatedly with the same labels.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {Array<{name: string, color: string, description?: string}>} required - Labels to ensure.
+   * @returns {Promise<string[]>} Names of labels that were created.
+   */
+  async ensure(repo, required) {
+    log.debug(`ensure labels: ${repo} (${required.length} required)`);
+    const existing = await this.labels(repo);
+    const names = new Set(existing.map(function name(l) { return l.name; }));
+    const [owner, repoName] = this.parse(repo);
+    const created = [];
+
+    for (const entry of required) {
+      if (!names.has(entry.name)) {
+        try {
+          await this.client.issues.createLabel({
+            owner, repo: repoName,
+            name: entry.name,
+            color: (entry.color ?? 'ededed').replace('#', ''),
+            description: entry.description ?? ''
+          });
+          created.push(entry.name);
+        } catch (err) {
+          // Race condition: label was created between list and create calls
+          const isConflict = err.status === 422 &&
+            JSON.stringify(err.response?.data).includes('already_exists');
+          if (!isConflict) throw err;
+          log.debug(`ensure: label "${entry.name}" already exists (race)`);
+        }
+      }
+    }
+
+    return created;
+  }
+
+  // --- Discussions (GraphQL) ---
+
+  /**
+   * Find a discussion category by name in a repository.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {string} name - Category name (e.g. 'Loreli').
+   * @returns {Promise<{id: string, name: string, isAnswerable: boolean}>}
+   * @throws {Error} When the category is not found.
+   */
+  async category(repo, name) {
+    const [owner, repoName] = this.parse(repo);
+    const query = `query($owner: String!, $name: String!) {
+      repository(owner: $owner, name: $name) {
+        id
+        discussionCategories(first: 25) {
+          nodes { id name isAnswerable }
+        }
+      }
+    }`;
+
+    const result = await this.client.graphql(query, { owner, name: repoName });
+    const cats = result.repository?.discussionCategories?.nodes ?? [];
+    const match = cats.find(function byName(c) { return c.name === name; });
+    if (!match) {
+      throw new Error(
+        `Discussion category "${name}" not found in ${repo}. ` +
+        'Enable GitHub Discussions and create the category in repo settings.'
+      );
+    }
+    return { id: match.id, name: match.name, isAnswerable: match.isAnswerable, repositoryId: result.repository.id };
+  }
+
+  /**
+   * Create a discussion in a repository. Requires scoping via as(identity, role).
+   * Auto-appends agent signature to the body.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {object} opts - Discussion options.
+   * @param {string} opts.title - Discussion title.
+   * @param {string} [opts.body] - Discussion body.
+   * @param {string} opts.categoryId - Discussion category node ID.
+   * @param {string} opts.repositoryId - Repository node ID.
+   * @param {string[]} [opts.labels] - Label names to apply.
+   * @returns {Promise<{id: string, number: number, title: string, url: string}>}
+   * @throws {Error} When hub is not scoped via as().
+   */
+  async discuss(repo, opts) {
+    this._guard('discuss');
+    log.debug(`discuss: ${repo} title="${opts.title}"`);
+
+    const mutation = `mutation($repositoryId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
+      createDiscussion(input: { repositoryId: $repositoryId, categoryId: $categoryId, title: $title, body: $body }) {
+        discussion { id number title url }
+      }
+    }`;
+
+    const result = await this.client.graphql(mutation, {
+      repositoryId: opts.repositoryId,
+      categoryId: opts.categoryId,
+      title: opts.title,
+      body: this._stamp(opts.body ?? '')
+    });
+
+    const d = result.createDiscussion.discussion;
+    const created = { id: d.id, number: d.number, title: d.title, url: d.url };
+
+    // Apply labels if provided
+    if (opts.labels?.length) {
+      await this.applyDiscussionLabels(repo, created.id, opts.labels);
+    }
+
+    // Verify the discussion is visible via direct node lookup before returning.
+    // Uses node() instead of the list endpoint — list queries have severe
+    // eventual consistency under high API load.
+    const client = this.client;
+    await this._settle(async function visible() {
+      const check = await client.graphql(`query($id: ID!) { node(id: $id) { id } }`, { id: created.id });
+      return Boolean(check.node);
+    }, `discussion #${created.number}`);
+
+    return created;
+  }
+
+  /**
+   * List open discussions in a category.
+   * Includes labels for each discussion.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {string} categoryId - Discussion category node ID.
+   * @returns {Promise<Array<{id: string, number: number, title: string, body: string, author: string, url: string, labels: string[], closed: boolean}>>}
+   */
+  async discussions(repo, categoryId) {
+    const [owner, repoName] = this.parse(repo);
+    const query = `query($owner: String!, $name: String!, $categoryId: ID!) {
+      repository(owner: $owner, name: $name) {
+        discussions(first: 100, categoryId: $categoryId) {
+          nodes {
+            id number title body url closed
+            author { login }
+            labels(first: 20) { nodes { name } }
+          }
+        }
+      }
+    }`;
+
+    const result = await this.client.graphql(query, { owner, name: repoName, categoryId });
+    const nodes = result.repository?.discussions?.nodes ?? [];
+    return nodes.map(function norm(d) {
+      return {
+        id: d.id,
+        number: d.number,
+        title: d.title,
+        body: d.body ?? '',
+        author: d.author?.login ?? '',
+        url: d.url,
+        labels: (d.labels?.nodes ?? []).map(function n(l) { return l.name; }),
+        closed: d.closed ?? false
+      };
+    });
+  }
+
+  /**
+   * Get a single discussion by number, including comments and labels.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Discussion number.
+   * @returns {Promise<{id: string, number: number, title: string, body: string, author: string, url: string, labels: string[], closed: boolean, comments: Array<{id: string, body: string, author: string, created: string}>}>}
+   */
+  async discussion(repo, number) {
+    const [owner, repoName] = this.parse(repo);
+    const query = `query($owner: String!, $name: String!, $number: Int!) {
+      repository(owner: $owner, name: $name) {
+        discussion(number: $number) {
+          id number title body url closed
+          author { login }
+          labels(first: 20) { nodes { name } }
+          comments(first: 100) {
+            nodes {
+              id body createdAt
+              author { login }
+            }
+          }
+        }
+      }
+    }`;
+
+    const result = await this.client.graphql(query, { owner, name: repoName, number });
+    const d = result.repository?.discussion;
+    if (!d) throw new Error(`Discussion #${number} not found in ${repo}`);
+    return {
+      id: d.id,
+      number: d.number,
+      title: d.title,
+      body: d.body ?? '',
+      author: d.author?.login ?? '',
+      url: d.url,
+      labels: (d.labels?.nodes ?? []).map(function n(l) { return l.name; }),
+      closed: d.closed ?? false,
+      comments: (d.comments?.nodes ?? []).map(function normComment(c) {
+        return { id: c.id, body: c.body ?? '', author: c.author?.login ?? '', created: c.createdAt };
+      })
+    };
+  }
+
+  /**
+   * List comments on a discussion.
+   *
+   * @param {string} discussionId - Discussion node ID.
+   * @returns {Promise<Array<{id: string, body: string, author: string, created: string}>>}
+   */
+  async discussionComments(discussionId) {
+    const query = `query($id: ID!) {
+      node(id: $id) {
+        ... on Discussion {
+          comments(first: 100) {
+            nodes {
+              id body createdAt
+              author { login }
+            }
+          }
+        }
+      }
+    }`;
+
+    const result = await this.client.graphql(query, { id: discussionId });
+    const nodes = result.node?.comments?.nodes ?? [];
+    return nodes.map(function norm(c) {
+      return { id: c.id, body: c.body ?? '', author: c.author?.login ?? '', created: c.createdAt };
+    });
+  }
+
+  /**
+   * Post a comment on a discussion. Requires scoping via as(identity, role).
+   * Auto-appends agent signature to the body.
+   *
+   * @param {string} discussionId - Discussion node ID.
+   * @param {string} body - Comment body text.
+   * @returns {Promise<{id: string, body: string}>}
+   * @throws {Error} When hub is not scoped via as().
+   */
+  async discussionComment(discussionId, body) {
+    this._guard('discussionComment');
+    const mutation = `mutation($discussionId: ID!, $body: String!) {
+      addDiscussionComment(input: { discussionId: $discussionId, body: $body }) {
+        comment { id body }
+      }
+    }`;
+
+    const result = await this.client.graphql(mutation, {
+      discussionId,
+      body: this._stamp(body)
+    });
+
+    return {
+      id: result.addDiscussionComment.comment.id,
+      body: result.addDiscussionComment.comment.body
+    };
+  }
+
+  /**
+   * Update a discussion's title and/or body.
+   * Requires scoping via as(identity, role) when updating the body —
+   * auto-appends agent signature.
+   *
+   * @param {string} discussionId - Discussion node ID.
+   * @param {object} opts - Update options.
+   * @param {string} [opts.title] - New title.
+   * @param {string} [opts.body] - New body (will be stamped).
+   * @returns {Promise<{id: string, title: string}>}
+   */
+  async updateDiscussion(discussionId, opts) {
+    if (opts.body !== undefined) this._guard('updateDiscussion');
+
+    const input = { discussionId };
+    if (opts.title !== undefined) input.title = opts.title;
+    if (opts.body !== undefined) input.body = this._stamp(opts.body);
+
+    const mutation = `mutation($discussionId: ID!, $title: String, $body: String) {
+      updateDiscussion(input: { discussionId: $discussionId, title: $title, body: $body }) {
+        discussion { id title }
+      }
+    }`;
+
+    const result = await this.client.graphql(mutation, input);
+    return {
+      id: result.updateDiscussion.discussion.id,
+      title: result.updateDiscussion.discussion.title
+    };
+  }
+
+  /**
+   * Close and lock a discussion. Posts an optional closing comment first.
+   *
+   * @param {string} discussionId - Discussion node ID.
+   * @returns {Promise<void>}
+   */
+  async closeDiscussion(discussionId) {
+    const closeMutation = `mutation($id: ID!) {
+      closeDiscussion(input: { discussionId: $id }) {
+        discussion { id }
+      }
+    }`;
+    await this.client.graphql(closeMutation, { id: discussionId });
+
+    const lockMutation = `mutation($id: ID!) {
+      lockLockable(input: { lockableId: $id }) {
+        lockedRecord { locked }
+      }
+    }`;
+    await this.client.graphql(lockMutation, { id: discussionId });
+  }
+
+  /**
+   * Delete a discussion entirely.
+   *
+   * @param {string} discussionId - Discussion node ID.
+   * @returns {Promise<void>}
+   */
+  async deleteDiscussion(discussionId) {
+    const mutation = `mutation($id: ID!) {
+      deleteDiscussion(input: { id: $id }) {
+        discussion { id }
+      }
+    }`;
+    const result = await this.client.graphql(mutation, { id: discussionId });
+    const deletedId = result.deleteDiscussion?.discussion?.id;
+
+    // Verify the discussion is no longer fetchable by node ID
+    const self = this;
+    await this._settle(async function gone() {
+      try {
+        const check = await self.client.graphql(`query($id: ID!) { node(id: $id) { id } }`, { id: deletedId ?? discussionId });
+        return !check.node;
+      } catch {
+        // GraphQL error means the node is gone
+        return true;
+      }
+    }, `deleteDiscussion(${discussionId})`);
+  }
+
+  /**
+   * Apply labels to a discussion using the Labelable interface.
+   * Auto-creates any labels that do not yet exist in the repository
+   * via the REST API before applying them via GraphQL.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {string} discussionId - Discussion node ID (Labelable).
+   * @param {string[]} labelNames - Label names to apply.
+   * @returns {Promise<void>}
+   */
+  async applyDiscussionLabels(repo, discussionId, labelNames) {
+    if (!labelNames?.length) return;
+
+    const [owner, repoName] = this.parse(repo);
+
+    // Auto-create missing labels so the resolve never silently drops them
+    await this.ensure(repo, labelNames.map(function def(n) {
+      return { name: n, color: 'ededed' };
+    }));
+
+    // Resolve label names to node IDs via REST — REST reads are immediately
+    // consistent after REST writes, unlike GraphQL which may lag.
+    const { data: restLabels } = await this.client.issues.listLabelsForRepo({
+      owner, repo: repoName, per_page: 100
+    });
+
+    const labelIds = labelNames
+      .map(function resolve(n) { return restLabels.find(function m(l) { return l.name === n; }); })
+      .filter(Boolean)
+      .map(function id(l) { return l.node_id; });
+
+    if (!labelIds.length) {
+      log.warn(`applyDiscussionLabels: none of [${labelNames}] resolved after ensure — skipping`);
+      return;
+    }
+
+    const mutation = `mutation($labelableId: ID!, $labelIds: [ID!]!) {
+      addLabelsToLabelable(input: { labelableId: $labelableId, labelIds: $labelIds }) {
+        labelable { ... on Discussion { id } }
+      }
+    }`;
+    await this.client.graphql(mutation, { labelableId: discussionId, labelIds });
+  }
+
+  /**
+   * Remove labels from a discussion using the Labelable interface.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {string} discussionId - Discussion node ID (Labelable).
+   * @param {string[]} labelNames - Label names to remove.
+   * @returns {Promise<void>}
+   */
+  async removeDiscussionLabels(repo, discussionId, labelNames) {
+    if (!labelNames?.length) return;
+
+    const [owner, repoName] = this.parse(repo);
+
+    // Resolve via REST for immediate consistency with prior writes
+    const { data: restLabels } = await this.client.issues.listLabelsForRepo({
+      owner, repo: repoName, per_page: 100
+    });
+
+    const labelIds = labelNames
+      .map(function resolve(n) { return restLabels.find(function m(l) { return l.name === n; }); })
+      .filter(Boolean)
+      .map(function id(l) { return l.node_id; });
+
+    if (!labelIds.length) return;
+
+    const mutation = `mutation($labelableId: ID!, $labelIds: [ID!]!) {
+      removeLabelsFromLabelable(input: { labelableId: $labelableId, labelIds: $labelIds }) {
+        labelable { ... on Discussion { id } }
+      }
+    }`;
+    await this.client.graphql(mutation, { labelableId: discussionId, labelIds });
+  }
+
+  // --- Search & Commits ---
+
+  /**
+   * List pull requests associated with a commit SHA.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {string} sha - Full commit SHA.
+   * @returns {Promise<Array<{number: number, title: string, state: string}>>}
+   * @see https://docs.github.com/en/rest/commits/commits#list-pull-requests-associated-with-a-commit
+   */
+  async associatedPulls(repo, sha) {
+    const [owner, name] = this.parse(repo);
+    log.debug(`associatedPulls: ${sha.slice(0, 7)} in ${repo}`);
+    const { data } = await this.client.repos.listPullRequestsAssociatedWithCommit({
+      owner, repo: name, commit_sha: sha, per_page: 10
+    });
+    return data.map(function brief(pr) {
+      return { number: pr.number, title: pr.title, state: pr.state };
+    });
+  }
+
+  /**
+   * Search issues and pull requests in a repository.
+   * Uses GitHub Search API scoped to the repo.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {string} query - Search keywords.
+   * @returns {Promise<Array<{number: number, title: string, type: string, url: string}>>}
+   * @see https://docs.github.com/en/rest/search/search#search-issues-and-pull-requests
+   */
+  async searchIssues(repo, query) {
+    const [owner, name] = this.parse(repo);
+    const q = `${query} repo:${owner}/${name}`;
+    log.debug(`searchIssues: "${query}" in ${repo}`);
+    const { data } = await this.client.request('GET /search/issues', {
+      q, per_page: 20, sort: 'updated', order: 'desc'
+    });
+    return data.items.map(function brief(item) {
+      return {
+        number: item.number,
+        title: item.title,
+        type: item.pull_request ? 'pr' : 'issue',
+        url: item.html_url
+      };
+    });
+  }
+
+  // --- Sub-Issues ---
+
+  /**
+   * Add an existing issue as a sub-issue of a parent issue.
+   * Uses the GitHub sub-issues REST API.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} parent - Parent issue number.
+   * @param {number} childId - Database ID (`id`, not `number`) of the child issue.
+   * @returns {Promise<{id: number, number: number, title: string}>} The linked sub-issue.
+   * @see https://docs.github.com/en/rest/issues/sub-issues
+   */
+  async sub(repo, parent, childId) {
+    const [owner, name] = this.parse(repo);
+    log.debug(`sub: linking child id=${childId} to parent #${parent} in ${repo}`);
+    const { data } = await this.client.request(
+      'POST /repos/{owner}/{repo}/issues/{issue_number}/sub_issues',
+      { owner, repo: name, issue_number: parent, sub_issue_id: childId }
+    );
+    return { id: data.id, number: data.number, title: data.title };
+  }
+
+  /**
+   * List sub-issues of a parent issue.
+   * Uses the GitHub sub-issues REST API.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Parent issue number.
+   * @returns {Promise<Array<{id: number, number: number, title: string, state: string}>>}
+   * @see https://docs.github.com/en/rest/issues/sub-issues
+   */
+  async subs(repo, number) {
+    const [owner, name] = this.parse(repo);
+    const { data } = await this.client.request(
+      'GET /repos/{owner}/{repo}/issues/{issue_number}/sub_issues',
+      { owner, repo: name, issue_number: number, per_page: 100 }
+    );
+    return data.map(function brief(i) {
+      return { id: i.id, number: i.number, title: i.title, state: i.state };
+    });
+  }
+
+  // --- Human In The Loop (HITL) ---
+
+  /**
+   * Assign users to an issue or PR.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - Issue or PR number.
+   * @param {string[]} usernames - GitHub usernames to assign.
+   * @returns {Promise<void>}
+   */
+  async assign(repo, number, usernames) {
+    const [owner, name] = this.parse(repo);
+    await this.client.issues.addAssignees({
+      owner, repo: name, issue_number: number, assignees: usernames
+    });
+  }
+
+  /**
+   * Request reviews from users on a PR.
+   *
+   * @param {string} repo - "owner/name" repository.
+   * @param {number} number - PR number.
+   * @param {string[]} usernames - GitHub usernames to request review from.
+   * @returns {Promise<void>}
+   */
+  async request(repo, number, usernames) {
+    const [owner, name] = this.parse(repo);
+    await this.client.pulls.requestReviewers({
+      owner, repo: name, pull_number: number, reviewers: usernames
+    });
+  }
+
+}