mandrel 1.57.0

package/.agents/scripts/providers/github/errors.js

@@ -0,0 +1,242 @@
+/**
+ * GitHub Provider — error classifier + sub-issues GraphQL shapes.
+ *
+ * `classifyGithubError` buckets `gh-exec`-thrown errors into 4 categories
+ * (`feature-disabled` / `permission` / `transient` / `permanent`) so the
+ * sub-issues fallback and the addSubIssue retry loop have a deterministic
+ * switch. Rate-limit detection wins over the 401/403 → permission rule
+ * because GitHub's secondary rate limit is delivered as HTTP 403 with a
+ * known message; if we bucketed it as 'permission' it would never be
+ * retried.
+ *
+ * `SUB_ISSUES_QUERY` / `ADD_SUB_ISSUE_MUTATION` / `REMOVE_SUB_ISSUE_MUTATION`
+ * are the three GraphQL shapes the sub-issues feature reads/writes.
+ *
+ * Extracted from `../github.js` in Story #1846 / Task #1857.
+ */
+
+const FEATURE_DISABLED_MESSAGES = [
+  'feature not available',
+  'feature is not enabled',
+  "field 'subissues'",
+  'field "subissues"',
+  'subissues is not available',
+  'sub-issues',
+  "doesn't exist on type",
+  'does not exist on type',
+  'unknown field',
+];
+
+const TRANSIENT_CODES = new Set([
+  'ECONNRESET',
+  'ETIMEDOUT',
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'ABORT_ERR',
+]);
+
+const TRANSIENT_MESSAGES = [
+  'rate limit',
+  'secondary rate limit',
+  'abuse detection',
+  'fetch failed',
+  'network',
+  'timeout',
+  'timed out',
+  'aborted',
+];
+
+const PERMISSION_MESSAGES = ['unauthorized', 'forbidden', 'permission'];
+
+function matchesAny(haystack, needles) {
+  for (const n of needles) if (haystack.includes(n)) return true;
+  return false;
+}
+
+/**
+ * Extract `{ lower, status, code }` from an error in the shape `gh-exec`
+ * throws. Pure — exported style for unit-testability without instantiating
+ * the provider. Defensive on shape: errors arrive as `Error` objects, plain
+ * `{message,status,code}` bags, or non-Errors stringified into `String(err)`.
+ */
+export function extractErrorFields(err) {
+  const message = typeof err.message === 'string' ? err.message : String(err);
+  return {
+    lower: message.toLowerCase(),
+    status: typeof err.status === 'number' ? err.status : undefined,
+    code: typeof err.code === 'string' ? err.code : undefined,
+  };
+}
+
+/** Pure predicate: HTTP status that signals "transient — retry-eligible". */
+export function isTransientStatus(status) {
+  if (status === 429) return true;
+  return typeof status === 'number' && status >= 500;
+}
+
+/** Pure predicate: error code/message signals "transient — retry-eligible". */
+export function isTransientByCodeOrMessage(code, lower) {
+  if (TRANSIENT_CODES.has(code)) return true;
+  return matchesAny(lower, TRANSIENT_MESSAGES);
+}
+
+/** Pure predicate: HTTP status / message signals "permission denied". */
+export function isPermissionSignal(status, lower) {
+  if (status === 401 || status === 403) return true;
+  return matchesAny(lower, PERMISSION_MESSAGES);
+}
+
+export function classifyGithubError(err) {
+  if (!err) return 'permanent';
+  // `GhExecTimeoutError` (from `lib/gh-exec.js`) carries a message of the
+  // shape `"gh-exec: gh <args> exceeded <N>ms"` — no transient keyword and
+  // no `.status` / `.code`. Match by `err.name` to avoid a circular import
+  // between this module and `lib/gh-exec.js`. Story #2860.
+  if (err.name === 'GhExecTimeoutError') return 'transient';
+  const { lower, status, code } = extractErrorFields(err);
+  if (matchesAny(lower, FEATURE_DISABLED_MESSAGES)) return 'feature-disabled';
+  if (isTransientStatus(status)) return 'transient';
+  if (isTransientByCodeOrMessage(code, lower)) return 'transient';
+  if (isPermissionSignal(status, lower)) return 'permission';
+  return 'permanent';
+}
+
+// ---------------------------------------------------------------------------
+// Transient-retry helper (Story #2852)
+// ---------------------------------------------------------------------------
+//
+// Mirrors the addSubIssue retry contract in `sub-issues.js` so read-path
+// callers (paginateRest, getTicket, getNativeSubIssues, …) absorb the same
+// jittered exponential backoff on transient GitHub errors instead of
+// bubbling a one-shot 502/429/ECONNRESET that kills a longer pipeline
+// (e.g. the /epic-deliver Phase E retro).
+
+export const TRANSIENT_RETRY_DEFAULTS = Object.freeze({
+  maxAttempts: 6,
+  baseDelayMs: 500,
+  capMs: 30_000,
+  jitterMs: 500,
+});
+
+/**
+ * Run `fn` with jittered exponential backoff on transient GitHub errors.
+ * `classify` (defaults to `classifyGithubError`) decides whether each
+ * failure is retry-eligible: only `'transient'` retries; every other
+ * bucket (`feature-disabled` / `permission` / `permanent`) bubbles on the
+ * first failure. The retry shape matches `addSubIssue` in
+ * `sub-issues.js:119-167`.
+ *
+ * `sleep` and `random` are injectable so tests can drive deterministic
+ * retry paths without real-world timing.
+ *
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @param {{
+ *   maxAttempts?: number,
+ *   baseDelayMs?: number,
+ *   capMs?: number,
+ *   jitterMs?: number,
+ *   classify?: (err: unknown) => string,
+ *   label?: string,
+ *   onRetry?: (info: {
+ *     attempt: number,
+ *     maxAttempts: number,
+ *     delay: number,
+ *     err: unknown,
+ *     label: string,
+ *   }) => void,
+ *   sleep?: (ms: number) => Promise<void>,
+ *   random?: () => number,
+ * }} [opts]
+ * @returns {Promise<T>}
+ */
+export async function withTransientRetry(fn, opts = {}) {
+  const {
+    maxAttempts = TRANSIENT_RETRY_DEFAULTS.maxAttempts,
+    baseDelayMs = TRANSIENT_RETRY_DEFAULTS.baseDelayMs,
+    capMs = TRANSIENT_RETRY_DEFAULTS.capMs,
+    jitterMs = TRANSIENT_RETRY_DEFAULTS.jitterMs,
+    classify = classifyGithubError,
+    label = 'gh-api',
+    onRetry,
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+    random = Math.random,
+  } = opts;
+
+  let lastErr;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      const category = classify(err);
+      const isFinal = attempt === maxAttempts - 1;
+      if (category !== 'transient' || isFinal) throw err;
+      const base = Math.min(capMs, baseDelayMs * 2 ** attempt);
+      const delay = base + Math.floor(random() * jitterMs);
+      if (typeof onRetry === 'function') {
+        onRetry({ attempt: attempt + 1, maxAttempts, delay, err, label });
+      }
+      await sleep(delay);
+    }
+  }
+  throw lastErr;
+}
+
+// ---------------------------------------------------------------------------
+// Sub-issues GraphQL shapes
+// ---------------------------------------------------------------------------
+export const SUB_ISSUES_QUERY = `query($id: ID!, $cursor: String) {
+  node(id: $id) {
+    ... on Issue {
+      subIssues(first: 100, after: $cursor) {
+        pageInfo { hasNextPage endCursor }
+        nodes {
+          number
+          databaseId
+          id
+          title
+          body
+          state
+          labels(first: 30) { nodes { name } }
+          assignees(first: 20) { nodes { login } }
+        }
+      }
+    }
+  }
+}`;
+
+export const ADD_SUB_ISSUE_MUTATION = `
+  mutation($parentId: ID!, $subIssueId: ID!, $replaceParent: Boolean) {
+    addSubIssue(input: { issueId: $parentId, subIssueId: $subIssueId, replaceParent: $replaceParent }) {
+      issue { number }
+      subIssue { number }
+    }
+  }`;
+
+export const REMOVE_SUB_ISSUE_MUTATION = `
+  mutation($parentId: ID!, $subIssueId: ID!) {
+    removeSubIssue(input: { issueId: $parentId, subIssueId: $subIssueId }) {
+      issue { number }
+      subIssue { number }
+    }
+  }`;
+
+// Story #2982 — native parent lookup for the cascade upward walk. The
+// inverse of `SUB_ISSUES_QUERY`: given a child Issue node, fetch the
+// `parent` field exposed by the Sub-Issues feature so `cascadeCompletion`
+// can resolve a parent even when the child body lacks the `parent: #N`
+// orchestrator footer.
+export const PARENT_ISSUE_QUERY = `query($id: ID!) {
+  node(id: $id) {
+    ... on Issue {
+      parent {
+        number
+        databaseId
+        id
+        title
+        state
+      }
+    }
+  }
+}`;

package/.agents/scripts/providers/github/issues.js

@@ -0,0 +1,242 @@
+/**
+ * GitHub Provider — IssuesGateway.
+ *
+ * Owns the remaining read-side surface that did not belong to any of the
+ * earlier six gateways: the raw GraphQL shim (`graphql` / `_ghGraphql`),
+ * epic enumeration (`getEpics`, `getEpic`), repository-wide label scans
+ * (`listIssuesByLabel`), branch existence probes (`branchExists`), and the
+ * three-strategy sub-ticket aggregator (`getSubTickets`).
+ *
+ * Extracted from `../github.js` in Story #2462 / Task #2481 — the final
+ * slice that brings `GitHubProvider` down to a thin composition root.
+ * Public surface on `GitHubProvider` is unchanged: every method here is
+ * exposed by a one-line delegating wrapper on the parent provider.
+ *
+ * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
+ */
+
+import { Logger } from '../../lib/Logger.js';
+import { TYPE_LABELS } from '../../lib/label-constants.js';
+import { concurrentMap } from '../../lib/util/concurrent-map.js';
+import { isNotFoundError } from './branch-protection.js';
+import { withTransientRetry } from './errors.js';
+import { issueToEpic, issueToEpicListItem } from './mappers.js';
+import {
+  defaultRetryWarn,
+  paginateRest,
+  parseApiJson,
+} from './request-helpers.js';
+
+/**
+ * Concurrency budget for the `getSubTickets` fan-out — preserved from
+ * the old `./github/issues.js` predecessor.
+ */
+export const SUBTICKET_HYDRATION_CONCURRENCY = 8;
+
+// Re-export so existing test consumers that previously imported
+// `paginateRest` from this module continue to work without an extra
+// migration step.
+export { paginateRest };
+
+export class IssuesGateway {
+  /**
+   * @param {{
+   *   gh: object,
+   *   owner: string,
+   *   repo: string,
+   *   hooks?: {
+   *     getTicket?: (id: number, opts?: object) => Promise<object>,
+   *     getTickets?: (parentId: number) => Promise<object[]>,
+   *     getNativeSubIssues?: (parentNodeId: string, parentId: number) => Promise<number[]>,
+   *     primeTicketCache?: (tickets: object[]) => void,
+   *   },
+   * }} deps
+   */
+  constructor({ gh, owner, repo, hooks = {} } = {}) {
+    this._gh = gh;
+    this.owner = owner;
+    this.repo = repo;
+    this._hooks = hooks;
+  }
+
+  /**
+   * Run a GraphQL query/mutation through `gh api graphql` (POST with a
+   * JSON `{ query, variables }` body on stdin). Returns the `data` field.
+   * Throws when the response contains a non-empty `errors[]`.
+   */
+  async ghGraphql(query, variables = {}, _opts = {}) {
+    const body = { query };
+    if (variables && Object.keys(variables).length > 0) {
+      body.variables = variables;
+    }
+    const result = await this._gh.api({
+      method: 'POST',
+      endpoint: 'graphql',
+      body,
+    });
+    const json = JSON.parse(result?.stdout ?? '{}');
+    if (Array.isArray(json.errors) && json.errors.length > 0) {
+      throw new Error(
+        `[GitHubProvider] GraphQL errors: ${JSON.stringify(json.errors)}`,
+      );
+    }
+    return json.data;
+  }
+
+  /**
+   * List every issue carrying `labels` (comma-separated string per GitHub
+   * REST). Used by the dispatcher / reconciler to scan for `agent::*`
+   * state.
+   *
+   * @field-manifest /repos/{owner}/{repo}/issues: number, title, body, labels,
+   *                 state, assignees, pull_request
+   */
+  async listIssuesByLabel({ state = 'open', labels: labelFilter } = {}) {
+    const params = new URLSearchParams({ state });
+    if (labelFilter) params.set('labels', labelFilter);
+    const endpoint = `/repos/${this.owner}/${this.repo}/issues?${params}`;
+    const issues = await paginateRest(this._gh, endpoint);
+    return issues.filter((issue) => !issue?.pull_request);
+  }
+
+  /**
+   * List Epic-typed issues. Filter shape preserved from the old code.
+   *
+   * @field-manifest /repos/{owner}/{repo}/issues?labels=type::epic: number,
+   *                 title, labels, state, state_reason, pull_request
+   */
+  /* node:coverage ignore next */
+  async getEpics(filters = {}) {
+    const params = new URLSearchParams({
+      state: filters.state ?? 'all',
+      labels: TYPE_LABELS.EPIC,
+    });
+    const endpoint = `/repos/${this.owner}/${this.repo}/issues?${params}`;
+    const issues = await paginateRest(this._gh, endpoint);
+    return issues
+      .filter((issue) => !issue.pull_request)
+      .map(issueToEpicListItem);
+  }
+
+  /**
+   * @field-manifest /repos/{owner}/{repo}/issues/{n}: number, id, node_id,
+   *                 title, body, labels, state
+   */
+  async getEpic(epicId) {
+    const result = await withTransientRetry(
+      () =>
+        this._gh.api({
+          method: 'GET',
+          endpoint: `/repos/${this.owner}/${this.repo}/issues/${epicId}`,
+        }),
+      { label: `getEpic #${epicId}`, onRetry: defaultRetryWarn },
+    );
+    return issueToEpic(parseApiJson(result));
+  }
+
+  /**
+   * Probe whether `branch` exists on the remote. Returns `true` when the
+   * branch resolves, `false` on 404, and propagates any other transport
+   * error so auth/scope failures don't masquerade as a missing branch.
+   *
+   * @field-manifest GET /repos/{owner}/{repo}/branches/{branch}: name
+   */
+  async branchExists(branch) {
+    const endpoint = `/repos/${this.owner}/${this.repo}/branches/${encodeURIComponent(branch)}`;
+    try {
+      await withTransientRetry(
+        () => this._gh.api({ method: 'GET', endpoint }),
+        { label: `branchExists ${branch}`, onRetry: defaultRetryWarn },
+      );
+      return true;
+    } catch (err) {
+      if (isNotFoundError(err)) return false;
+      throw err;
+    }
+  }
+
+  /** Strategy 2 — Markdown checklist links `- [ ] #N` / `- [x] #N`. */
+  _getChecklistChildren(parentBody) {
+    const re = /-\s*\[[ xX]\]\s+#(\d+)/g;
+    return [...(parentBody ?? '').matchAll(re)].map((m) =>
+      Number.parseInt(m[1], 10),
+    );
+  }
+
+  /**
+   * Strategy 3 — reverse-search for issues that reference the parent
+   * (`Epic: #N` / `parent: #N`). Non-fatal on error.
+   */
+  async _getReferencedChildren(parentId) {
+    const getTickets = this._hooks.getTickets;
+    const primeTicketCache = this._hooks.primeTicketCache;
+    try {
+      const issues = await getTickets(parentId);
+      if (typeof primeTicketCache === 'function') {
+        primeTicketCache(issues);
+      }
+      return issues.map((i) => i.id);
+    } catch (err) {
+      Logger.warn(
+        `[GitHubProvider] reverse dependency lookup (parent #${parentId}): ${err.message}`,
+      );
+      return [];
+    }
+  }
+
+  /**
+   * Aggregate sub-tickets via a priority-fallback strategy:
+   *   1. Native sub-issues (GraphQL) + checklist links in body — run in
+   *      parallel because checklist parsing is pure/synchronous.
+   *   2. Reverse-search (`_getReferencedChildren`) — a full-repo label
+   *      scan that is **only** executed when both strategy 1 sources
+   *      return empty. This avoids the unconditional full-repo scan that
+   *      fired on every call in the old `Promise.all` path.
+   *
+   * @param {number} parentId
+   * @param {{ fresh?: boolean }} [opts] - Pass `{ fresh: true }` to bypass
+   *   the per-instance ticket cache for every child hydration fetch. Used
+   *   by the cascade logic to skip a redundant second fan-out.
+   */
+  async getSubTickets(parentId, opts = {}) {
+    const getTicket = this._hooks.getTicket;
+    const getNativeSubIssues = this._hooks.getNativeSubIssues;
+    const parent = await getTicket(parentId);
+
+    // Strategy 1: native sub-issues (GraphQL) + checklist (synchronous).
+    const [nativeChildIds, checklistChildIds] = await Promise.all([
+      getNativeSubIssues(parent.nodeId, parentId),
+      Promise.resolve(this._getChecklistChildren(parent.body)),
+    ]);
+
+    // Strategy 2 (fallback): full-repo reverse-search — only when strategy
+    // 1 produced nothing, avoiding the unconditional scan on every call.
+    let referencedChildIds = [];
+    if (nativeChildIds.length === 0 && checklistChildIds.length === 0) {
+      referencedChildIds = await this._getReferencedChildren(parentId);
+    }
+
+    const allChildIds = [
+      ...new Set([
+        ...nativeChildIds,
+        ...checklistChildIds,
+        ...referencedChildIds,
+      ]),
+    ];
+
+    const ticketOpts = opts.fresh ? { fresh: true } : undefined;
+    const subTickets = await concurrentMap(
+      allChildIds,
+      (id) =>
+        getTicket(id, ticketOpts).catch((err) => {
+          const msg = err?.message ?? String(err);
+          Logger.warn(
+            `[GitHubProvider] getSubTickets: child #${id} fetch failed (parent #${parentId}): ${msg}`,
+          );
+          return null;
+        }),
+      { concurrency: SUBTICKET_HYDRATION_CONCURRENCY },
+    );
+    return subTickets.filter(Boolean);
+  }
+}

package/.agents/scripts/providers/github/labels.js

@@ -0,0 +1,179 @@
+/**
+ * GitHub Provider — LabelGateway.
+ *
+ * Owns `ensureLabels` (idempotent label create) plus the live-set
+ * reconciliation helper (`_reconcileLabelsPresence` /
+ * `_normalizeLabelListResult`). `gh label create` is the canonical CLI
+ * surface for label creation; this gateway swallows the "already exists"
+ * signal across all three surfaces (CLI stderr, API 422 body, legacy test
+ * mock) so re-runs are idempotent.
+ *
+ * Extracted from `../github.js` in Story #2462 / Task #2478. Public
+ * surface on `GitHubProvider` is unchanged — `ensureLabels`,
+ * `_reconcileLabelsPresence`, and `_normalizeLabelListResult` all
+ * delegate here.
+ *
+ * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
+ */
+
+import { withTransientRetry } from './transient-retry.js';
+
+/**
+ * Detect the "label already exists" signal across the surfaces `gh label
+ * create` can emit it on. The CLI prints
+ *
+ *   `! Label "<name>" already exists`
+ *
+ * to stderr and exits non-zero; the underlying API surfaces a 422 with
+ * `errors[].code === 'already_exists'`. The test mock throws
+ * `Error('... code 422')`. Match all three — but require the patterns to
+ * be **anchored to the label-create lexicon** so unrelated stderr lines
+ * that happen to mention "already exists" don't get misclassified as
+ * idempotent skips and let real creation failures look successful.
+ *
+ * Story #2018 (Bug 2) tightened the regexes after a fresh-repo bootstrap
+ * counted 23 labels as "skipped" when none were actually created.
+ */
+export function isLabelAlreadyExistsError(err) {
+  if (!err) return false;
+  const message = err?.message ?? '';
+  const stderr = err?.stderr ?? '';
+  // CLI shapes (vary by gh version):
+  //   `! Label "<name>" already exists`
+  //   `label with name "<name>" already exists; use ` + '`--force`' + ` ...`
+  // Require both the "label" lexicon and the "already exists" signal (with
+  // anything in between) so unrelated errors are not misclassified as skips.
+  if (/label\b[\s\S]*?already exists/i.test(stderr)) return true;
+  if (/label\b[\s\S]*?already exists/i.test(message)) return true;
+  // REST API shape: 422 + `already_exists` code in the error body.
+  if (/already_exists/i.test(stderr) || /already_exists/i.test(message)) {
+    return true;
+  }
+  // Test-mock legacy shape: `Error('... code 422 ...')` combined with the
+  // word "already exists" anywhere in the message.
+  if (
+    /\bcode\s+422\b/i.test(message) &&
+    /already exists/i.test(message + stderr)
+  ) {
+    return true;
+  }
+  return false;
+}
+
+export class LabelGateway {
+  /**
+   * @param {{ gh: object, owner: string, repo: string }} deps
+   */
+  constructor({ gh, owner, repo } = {}) {
+    this._gh = gh;
+    this.owner = owner;
+    this.repo = repo;
+  }
+
+  /**
+   * Idempotent label creation. For each labelDef, attempt `gh label create
+   * <name> --color <hex> --description <text>`. The CLI prints
+   * "label already exists" (or the API surfaces a 422 "already_exists"
+   * error) when the name is taken; we swallow that and count it as
+   * `skipped`. Any other error propagates so transport faults stay loud.
+   *
+   * After the per-def loop, **reconcile against the live label set** by
+   * listing the labels actually present on the remote. Anything counted
+   * in `created` or `skipped` that isn't actually present is moved to a
+   * `missing[]` envelope — the bootstrap caller surfaces this loudly so a
+   * silent classification miss (Story #2018, Bug 2) can't pretend success.
+   * Verification failures (rate-limit, scope) are best-effort: they leave
+   * `missing` empty rather than aborting the bootstrap.
+   *
+   * Returns `{ created: string[], skipped: string[], missing: string[] }`.
+   */
+  async ensureLabels(labelDefs) {
+    const created = [];
+    const skipped = [];
+    for (const def of labelDefs) {
+      const color = (def.color ?? '').replace(/^#/, '');
+      try {
+        await withTransientRetry(() =>
+          this._gh.label.create(def.name, [
+            '--color',
+            color,
+            '--description',
+            def.description ?? '',
+          ]),
+        );
+        created.push(def.name);
+      } catch (err) {
+        if (isLabelAlreadyExistsError(err)) {
+          skipped.push(def.name);
+          continue;
+        }
+        throw err;
+      }
+    }
+
+    const missing = await this._reconcileLabelsPresence(labelDefs);
+    if (missing.length === 0) {
+      return { created, skipped, missing };
+    }
+    // Anything we believed we created/skipped that isn't actually on the
+    // remote is by definition a silent failure — drop it from those lists
+    // so the consumer's `created.length + skipped.length` math stays
+    // honest. The full label name survives in `missing[]`.
+    const missingSet = new Set(missing);
+    return {
+      created: created.filter((n) => !missingSet.has(n)),
+      skipped: skipped.filter((n) => !missingSet.has(n)),
+      missing,
+    };
+  }
+
+  /**
+   * Best-effort post-loop reconcile for `ensureLabels`. Lists the live
+   * label set and returns the names from `labelDefs` that are absent.
+   * Internal helper — production callers go through `ensureLabels`.
+   *
+   * Accepts either the real `gh-exec` --json shape (returns an `Array`
+   * directly) or the legacy/test shape (`{stdout: '<json>', ...}`) so
+   * the verification path stays harness-agnostic.
+   */
+  async _reconcileLabelsPresence(labelDefs) {
+    let result;
+    try {
+      result = await this._gh.label.list(['--limit', '500'], ['name']);
+    } catch {
+      return [];
+    }
+    const liveLabels = this._normalizeLabelListResult(result);
+    if (!Array.isArray(liveLabels) || liveLabels.length === 0) {
+      // Listing returned nothing parseable. Treat as "verification
+      // unavailable" rather than "every label is missing" — false
+      // positives on this path would derail an otherwise-clean bootstrap.
+      return [];
+    }
+    const liveNames = new Set();
+    for (const row of liveLabels) {
+      if (row && typeof row.name === 'string') liveNames.add(row.name);
+    }
+    if (liveNames.size === 0) return [];
+    const missing = [];
+    for (const def of labelDefs) {
+      if (def?.name && !liveNames.has(def.name)) missing.push(def.name);
+    }
+    return missing;
+  }
+
+  _normalizeLabelListResult(result) {
+    if (Array.isArray(result)) return result;
+    if (result && typeof result.stdout === 'string') {
+      const trimmed = result.stdout.trim();
+      if (!trimmed) return [];
+      try {
+        const parsed = JSON.parse(trimmed);
+        return Array.isArray(parsed) ? parsed : [];
+      } catch {
+        return [];
+      }
+    }
+    return [];
+  }
+}