@nickysagan/issue-orchestrator 0.1.0

package/src/labels.mjs

@@ -0,0 +1,68 @@
+// Label vocabulary for the managed workflow. `agent-running` is the durable
+// ownership marker; exactly one phase label is active alongside it.
+export const READY = "agent-ready";
+export const RUNNING = "agent-running";
+export const REVIEW = "agent-review";
+export const BLOCKED = "agent-blocked";
+export const MERGE_REVIEW = "user-merge-review";
+
+// Declaration order is also precedence order for `phaseOf`: a repository that
+// somehow carries two phase labels resolves to the earliest one, so the
+// supervisor keeps reconciling rather than oscillating.
+export const PHASE_LABELS = [REVIEW, BLOCKED, MERGE_REVIEW];
+export const MANAGED_LABELS = [READY, RUNNING, ...PHASE_LABELS];
+
+export const REQUIRED_LABELS = [
+  { name: READY, color: "0e8a16", description: "Ready for issue-orchestrator claim" },
+  { name: RUNNING, color: "1d76db", description: "Managed by issue-orchestrator" },
+  { name: REVIEW, color: "5319e7", description: "Waiting for or undergoing automated review" },
+  { name: BLOCKED, color: "d73a4a", description: "Automated workflow blocked; findings posted" },
+  { name: MERGE_REVIEW, color: "fbca04", description: "Automated review passed; waiting for owner review and merge" },
+];
+
+export function phaseOf(labelNames) {
+  const present = new Set((labelNames || []).map((name) => String(name)));
+  return PHASE_LABELS.find((label) => present.has(label)) || null;
+}
+
+function alreadyExists(message) {
+  return /already exists/i.test(message);
+}
+
+// Idempotent bootstrap: list once, create only what is missing, never modify
+// an existing label. A permission/authentication failure rejects, which is
+// fatal at startup; whatever was created before the failure is kept, so the
+// next startup retries only the remainder.
+export async function ensureLabels({ listLabels, createLabel, log = () => {} }) {
+  let existingLabels;
+  try {
+    existingLabels = await listLabels();
+  } catch (err) {
+    throw new Error(`label bootstrap failed: ${err.message}`);
+  }
+  // GitHub label names are case-insensitive for uniqueness, so a repository
+  // that already has `Agent-Ready` must not get a second `agent-ready`.
+  const byName = new Map(
+    (existingLabels || []).map((label) => [String(label.name).toLowerCase(), label.name]),
+  );
+
+  const created = [];
+  const existing = [];
+  for (const label of REQUIRED_LABELS) {
+    const match = byName.get(label.name.toLowerCase());
+    if (match !== undefined) {
+      existing.push(match);
+      continue;
+    }
+    try {
+      await createLabel(label);
+    } catch (err) {
+      if (!alreadyExists(err.message)) {
+        throw new Error(`label bootstrap failed: ${err.message}`);
+      }
+    }
+    created.push(label.name);
+  }
+  if (created.length > 0) log(`Created missing labels: ${created.join(", ")}`);
+  return { created, existing };
+}

package/src/managedContainer.mjs

@@ -0,0 +1,120 @@
+import { readFile } from "node:fs/promises";
+
+const DEFAULT_URL = "http://usage-sentinel:4317";
+const DEFAULT_TIMEOUT_MS = 5000;
+const CONTAINER_ID = /^[0-9a-f]{64}$/;
+// Docker bind-mounts /etc/{resolv.conf,hostname,hosts} out of the container's
+// own state directory, so mountinfo carries the full 64-hex ID that the lease
+// API requires. `hostname` is only the 12-character short form, which Sentinel
+// rejects, and cgroup v2 reports `0::/` with no ID at all.
+const MOUNT_CONTAINER_ID = /\/containers\/([0-9a-f]{64})\//g;
+
+export async function resolveContainerId({ readFileImpl = readFile } = {}) {
+  const raw = await readFileImpl("/proc/self/mountinfo", "utf8");
+  const ids = new Set(Array.from(String(raw).matchAll(MOUNT_CONTAINER_ID), (match) => match[1]));
+  if (ids.size === 1) return [...ids][0];
+  if (ids.size === 0) {
+    throw new Error("cannot resolve the current Docker container ID from /proc/self/mountinfo");
+  }
+  throw new Error(`ambiguous Docker container IDs in /proc/self/mountinfo: ${[...ids].join(", ")}`);
+}
+
+// Sentinel's `/managed-containers` API is a lease, not admission control: it
+// never allows or denies a start, so neither operation here returns anything a
+// caller could read as a decision. Any non-lease status is a local or transport
+// fault to report, never a refusal to run.
+export function createManagedContainerClient({
+  url = DEFAULT_URL,
+  fetchImpl = fetch,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  const baseUrl = url.replace(/\/$/, "");
+
+  // One deadline for the whole exchange — headers *and* body. Sentinel can send
+  // headers and then stall mid-body; awaiting that without a deadline would hang
+  // the supervisor's poll loop. The timer is deliberately ref'd (unlike
+  // `AbortSignal.timeout`, whose unref'd timer never fires when nothing else
+  // keeps the loop alive) and is cleared only once the caller is done reading.
+  function startDeadline() {
+    const controller = new AbortController();
+    const timer = setTimeout(
+      () => controller.abort(new Error(`exceeded ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+    return { signal: controller.signal, done: () => clearTimeout(timer) };
+  }
+
+  // The race does not trust the awaited promise to honour the signal itself.
+  function withDeadline(promise, signal) {
+    if (signal.aborted) return Promise.reject(signal.reason);
+    return Promise.race([
+      promise,
+      new Promise((_resolve, reject) => {
+        signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+      }),
+    ]);
+  }
+
+  function transportError(error, signal) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const prefix = signal.aborted ? "sentinel request timed out" : "sentinel unreachable";
+    return new Error(`${prefix}: ${detail}`);
+  }
+
+  async function request(containerId, method) {
+    if (typeof containerId !== "string" || !CONTAINER_ID.test(containerId)) {
+      throw new Error(`invalid container ID: ${containerId}`);
+    }
+    const { signal, done } = startDeadline();
+    const path = `/managed-containers/${encodeURIComponent(containerId)}`;
+    let response;
+    try {
+      response = await withDeadline(fetchImpl(`${baseUrl}${path}`, { method, signal }), signal);
+      if (!response || !Number.isInteger(response.status)) {
+        throw new Error("sentinel returned no response");
+      }
+    } catch (error) {
+      done();
+      if (error.message === "sentinel returned no response") throw error;
+      throw transportError(error, signal);
+    }
+    // The deadline stays armed for whatever the caller still reads off this
+    // response; `done` disarms it.
+    return { response, signal, done };
+  }
+
+  async function register(containerId) {
+    const { response, signal, done } = await request(containerId, "PUT");
+    try {
+      // 201 creates the lease; a repeat PUT is its heartbeat and returns 200.
+      const expected = { 201: "registered", 200: "refreshed" }[response.status];
+      if (!expected) {
+        throw new Error(`unexpected managed-container registration status ${response.status}`);
+      }
+      let body;
+      try {
+        body = await withDeadline(response.json(), signal);
+      } catch (error) {
+        if (signal.aborted) throw transportError(error, signal);
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`invalid managed-container registration response: ${detail}`);
+      }
+      if (body?.status !== expected) {
+        throw new Error(`invalid managed-container registration response: status ${body?.status}`);
+      }
+      return { status: expected };
+    } finally {
+      done();
+    }
+  }
+
+  async function unregister(containerId) {
+    const { response, done } = await request(containerId, "DELETE");
+    done();
+    if (response.status !== 204) {
+      throw new Error(`unexpected managed-container deletion status ${response.status}`);
+    }
+  }
+
+  return { register, unregister };
+}

package/src/reviewGate.mjs

@@ -0,0 +1,308 @@
+import { BLOCKED, MANAGED_LABELS, MERGE_REVIEW, REVIEW, phaseOf } from "./labels.mjs";
+
+const BRANCH_PREFIX = /^agent\/(\d+)-/;
+
+function branchIssue(pr) {
+  const match = BRANCH_PREFIX.exec(String(pr.headRefName || ""));
+  return match ? Number(match[1]) : null;
+}
+
+function closingIssues(pr) {
+  const refs = Array.isArray(pr.closingIssuesReferences) ? pr.closingIssuesReferences : [];
+  return refs.map((ref) => Number(ref?.number)).filter((n) => Number.isInteger(n));
+}
+
+// Pair each `agent-running` issue with the single open PR that closes it.
+// Closing references are authoritative; the `agent/<n>-` branch prefix is only
+// a fallback for a PR that declares no closing reference at all. A PR whose
+// branch names a different issue than its closing reference is a conflict, not
+// a match, and fails closed. PRs that match no managed issue — manual
+// `/github-issue` PRs, unrelated `agent/*` branches — are ignored entirely.
+export function resolveManagedPrs(issues, prs) {
+  const managed = [];
+  const problems = [];
+  const ordered = [...(issues || [])].sort((a, b) => a.number - b.number);
+
+  for (const issue of ordered) {
+    const phase = phaseOf(issue.labels);
+    const candidates = [];
+    for (const pr of prs || []) {
+      const closes = closingIssues(pr);
+      const branch = branchIssue(pr);
+      if (closes.includes(issue.number)) {
+        if (branch !== null && branch !== issue.number) {
+          problems.push({
+            issue,
+            pr,
+            reason: "conflicting-linkage",
+            message: `PR #${pr.number} closes #${issue.number} but its branch \`${pr.headRefName}\` names #${branch}.`,
+          });
+          continue;
+        }
+        candidates.push(pr);
+      } else if (closes.length === 0 && branch === issue.number) {
+        candidates.push(pr);
+      }
+    }
+
+    if (candidates.length === 1) {
+      managed.push({ issue, pr: candidates[0] });
+    } else if (candidates.length > 1) {
+      problems.push({
+        issue,
+        pr: null,
+        reason: "duplicate-linkage",
+        message: `Issue #${issue.number} is closed by more than one open PR: ${candidates.map((p) => `#${p.number}`).join(", ")}.`,
+      });
+    } else if (phase === REVIEW) {
+      // Only a review-phase issue *must* have a PR. An issue still being
+      // implemented legitimately has none yet, and a terminal issue's PR may
+      // already be closed.
+      problems.push({
+        issue,
+        pr: null,
+        reason: "missing-linkage",
+        message: `Issue #${issue.number} is labelled \`${REVIEW}\` but no open PR closes it.`,
+      });
+    }
+  }
+  return { managed, problems };
+}
+
+const GREEN_CONCLUSIONS = new Set(["SUCCESS", "NEUTRAL", "SKIPPED"]);
+const FAILING_CONCLUSIONS = new Set([
+  "FAILURE", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE", "STALE",
+]);
+const PENDING_STATUSES = new Set(["QUEUED", "IN_PROGRESS", "WAITING", "PENDING", "REQUESTED"]);
+const STUCK_CHECK_MS = 6 * 60 * 60 * 1000;
+
+function checkName(entry) {
+  return entry.name ?? entry.context ?? "(unnamed check)";
+}
+function checkUrl(entry) {
+  return entry.detailsUrl ?? entry.targetUrl ?? null;
+}
+
+// Normalise one rollup entry. GitHub reports modern CheckRuns (status +
+// conclusion) and legacy StatusContexts (state) in the same array.
+function checkState(entry) {
+  if (!entry || typeof entry !== "object") return "unknown";
+  if (typeof entry.state === "string") {
+    if (entry.state === "SUCCESS") return "green";
+    if (entry.state === "PENDING" || entry.state === "EXPECTED") return "pending";
+    if (entry.state === "FAILURE" || entry.state === "ERROR") return "failing";
+    return "unknown";
+  }
+  if (typeof entry.status !== "string") return "unknown";
+  if (PENDING_STATUSES.has(entry.status)) return "pending";
+  if (entry.status !== "COMPLETED") return "unknown";
+  if (GREEN_CONCLUSIONS.has(entry.conclusion)) return "green";
+  if (FAILING_CONCLUSIONS.has(entry.conclusion)) return "failing";
+  return "unknown";
+}
+
+function pendingElapsedMs(entry, now) {
+  const timestamp = typeof entry.state === "string" ? entry.createdAt : entry.startedAt;
+  if (typeof timestamp !== "string") return null;
+  const started = Date.parse(timestamp);
+  const elapsed = now - started;
+  return Number.isFinite(started) && Number.isFinite(elapsed) && elapsed >= 0 ? elapsed : null;
+}
+
+function timedCheckState(entry, now) {
+  const state = checkState(entry);
+  if (state !== "pending") return state;
+  const elapsed = pendingElapsedMs(entry, now);
+  if (elapsed === null) return "unknown";
+  return elapsed > STUCK_CHECK_MS ? "stuck" : "pending";
+}
+
+// Every check GitHub reports is treated as required: reading branch-protection
+// required-check names needs an extra admin-scoped call and could only ever
+// make this gate more permissive.
+//
+// An empty array means "no checks configured" and counts as green. Absent or
+// unreadable data is `unknown`, which transitions nothing — the two must never
+// be conflated, or a failed fetch would silently promote an unverified PR.
+export function classifyChecks(rollup, now = Date.now()) {
+  if (!Array.isArray(rollup)) return "unknown";
+  const states = rollup.map((entry) => timedCheckState(entry, now));
+  if (states.includes("failing")) return "failing";
+  if (states.includes("unknown")) return "unknown";
+  if (states.includes("stuck")) return "stuck";
+  if (states.includes("pending")) return "pending";
+  return "green";
+}
+
+export function failingChecks(rollup) {
+  if (!Array.isArray(rollup)) return [];
+  return rollup
+    .filter((entry) => checkState(entry) === "failing")
+    .map((entry) => ({ name: checkName(entry), url: checkUrl(entry) }));
+}
+
+export function stuckChecks(rollup, now = Date.now()) {
+  if (!Array.isArray(rollup)) return [];
+  return rollup
+    .filter((entry) => timedCheckState(entry, now) === "stuck")
+    .map((entry) => ({
+      name: checkName(entry),
+      url: checkUrl(entry),
+      elapsedMs: pendingElapsedMs(entry, now),
+    }));
+}
+
+// One action per PR per poll.
+//
+// A clean verdict marks a draft PR ready and stops there ("open"): checks were
+// read before the PR opened, so a repository whose CI triggers on
+// `ready_for_review` would still report an empty rollup and be promoted
+// without ever running. The next poll evaluates the checks for real.
+// Verdicts are the producer's exact literals (review-pr:v1). Anything else —
+// including the old lowercase spellings — is a contract violation and fails
+// closed rather than being re-reviewed forever.
+export function planVerdict({ marker, checks, isDraft }) {
+  if (!marker) return { action: "review" };
+  if (marker.verdict === "BLOCKING") return { action: "block", reason: "blocking-verdict" };
+  if (marker.verdict !== "PASS") return { action: "block", reason: "unrecognised-verdict" };
+  if (isDraft) return { action: "open" };
+  if (checks === "green") return { action: "pass" };
+  if (checks === "pending") return { action: "wait" };
+  if (checks === "failing") return { action: "fail-checks" };
+  if (checks === "stuck") return { action: "stuck-checks" };
+  return { action: "retry" };
+}
+
+// PR labels mirror the canonical issue labels, restricted to the managed
+// vocabulary so a reviewer's own labels are never disturbed. Returning empty
+// lists lets the caller skip the API call entirely when nothing differs.
+export function planLabelMirror(issueLabels, prLabels) {
+  const managed = new Set(MANAGED_LABELS);
+  const desired = (issueLabels || []).filter((name) => managed.has(name));
+  const current = new Set((prLabels || []).filter((name) => managed.has(name)));
+  const wanted = new Set(desired);
+  return {
+    add: desired.filter((name) => !current.has(name)),
+    remove: [...current].filter((name) => !wanted.has(name)),
+  };
+}
+
+// Swap the issue's phase label and mirror it onto the PR. `agent-running` is
+// never removed here — it is durable until Phase 7.
+async function setPhase({ gh, issue, pr, phase }) {
+  const current = phaseOf(issue.labels);
+  if (current === phase) return;
+  const delta = { add: [phase], remove: current ? [current] : [] };
+  await gh.setIssueLabels(issue.number, delta);
+  if (pr) await gh.setPrLabels(pr.number, delta);
+}
+
+export async function mirrorLabels({ gh, issue, pr }) {
+  if (!pr) return;
+  const delta = planLabelMirror(issue.labels, pr.labels);
+  if (delta.add.length === 0 && delta.remove.length === 0) return;
+  await gh.setPrLabels(pr.number, delta);
+}
+
+function failingChecksComment(rollup) {
+  const lines = failingChecks(rollup).map(
+    (check) => `- \`${check.name}\`${check.url ? ` — ${check.url}` : ""}`,
+  );
+  return [
+    "Automated review passed, but required checks failed.",
+    "",
+    ...lines,
+    "",
+    `Returned to draft and labelled \`${BLOCKED}\`. This workflow does not repair failures.`,
+  ].join("\n");
+}
+
+function elapsedDuration(elapsedMs) {
+  const hours = Math.floor(elapsedMs / (60 * 60 * 1000));
+  if (hours >= 1) return `${hours} ${hours === 1 ? "hour" : "hours"}`;
+  const minutes = Math.max(1, Math.floor(elapsedMs / (60 * 1000)));
+  return `${minutes} ${minutes === 1 ? "minute" : "minutes"}`;
+}
+
+function stuckChecksComment(rollup, now) {
+  const lines = stuckChecks(rollup, now).map(
+    (check) => `- \`${check.name}\` — stuck for ${elapsedDuration(check.elapsedMs)}${check.url ? ` — ${check.url}` : ""}`,
+  );
+  return [
+    "Automated review passed, but required checks appear stuck.",
+    "",
+    ...lines,
+    "",
+    `Returned to draft and labelled \`${BLOCKED}\` for owner attention.`,
+  ].join("\n");
+}
+
+// Execute exactly one planned action. Returns the phase the issue now carries
+// so the caller can decide whether the supervisor may exit.
+export async function applyReviewPlan({ gh, issue, pr, plan, rollup, now = Date.now(), log = () => {} }) {
+  switch (plan.action) {
+    case "open":
+      await gh.markPrReady(pr.number);
+      log(`#${issue.number}: review clean — PR #${pr.number} marked ready; checks evaluated next poll`);
+      return { phase: REVIEW };
+
+    case "pass":
+      await setPhase({ gh, issue, pr, phase: MERGE_REVIEW });
+      log(`#${issue.number}: checks green — PR #${pr.number} awaiting owner review`);
+      return { phase: MERGE_REVIEW };
+
+    case "wait":
+      log(`#${issue.number}: PR #${pr.number} checks pending — reviewer slot free`);
+      return { phase: REVIEW };
+
+    case "retry":
+      log(`#${issue.number}: PR #${pr.number} check data unreadable — retrying next poll`);
+      return { phase: REVIEW };
+
+    case "block": {
+      if (plan.reason === "unrecognised-verdict") {
+        await gh.commentPr(
+          pr.number,
+          "The review marker for this PR's current content carries an unrecognised verdict, so this PR cannot be gated automatically. Blocking for owner attention.",
+        );
+      }
+      if (pr.isDraft === false) await gh.markPrDraft(pr.number);
+      await setPhase({ gh, issue, pr, phase: BLOCKED });
+      log(`#${issue.number}: PR #${pr.number} blocked (${plan.reason})`);
+      return { phase: BLOCKED };
+    }
+
+    case "fail-checks": {
+      await gh.commentPr(pr.number, failingChecksComment(rollup));
+      if (pr.isDraft === false) await gh.markPrDraft(pr.number);
+      await setPhase({ gh, issue, pr, phase: BLOCKED });
+      log(`#${issue.number}: PR #${pr.number} blocked on failing checks`);
+      return { phase: BLOCKED };
+    }
+
+    case "stuck-checks": {
+      await gh.commentPr(pr.number, stuckChecksComment(rollup, now));
+      if (pr.isDraft === false) await gh.markPrDraft(pr.number);
+      await setPhase({ gh, issue, pr, phase: BLOCKED });
+      log(`#${issue.number}: PR #${pr.number} blocked on stuck checks`);
+      return { phase: BLOCKED };
+    }
+
+    default:
+      return { phase: phaseOf(issue.labels) };
+  }
+}
+
+// Every linkage or lifecycle ambiguity ends here: an actionable comment plus
+// `agent-blocked`. Already-blocked issues short-circuit so a persistent
+// problem is reported once, not every poll.
+export async function failClosed({ gh, issue, pr, message, log = () => {} }) {
+  if (phaseOf(issue.labels) === BLOCKED) return;
+  await gh.commentIssue(
+    issue.number,
+    `${message}\n\nissue-orchestrator cannot proceed automatically and has labelled this \`${BLOCKED}\`.`,
+  );
+  if (pr && pr.isDraft === false) await gh.markPrDraft(pr.number);
+  await setPhase({ gh, issue, pr, phase: BLOCKED });
+  log(`#${issue.number}: blocked — ${message}`);
+}

package/src/reviewMarker.mjs

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+
+// The contract between the reviewer skill (Sadotu/agent-skills#22) and this
+// supervisor. This repo is purely a consumer: the shipped
+// `review-pr/scripts/publish-review.sh` is canonical and nothing here ever
+// produces a marker.
+//
+// The producer emits exactly one line per pass:
+//   <!-- review-pr:v1 {"fingerprint":…,"head":…,…,"verdict":"PASS"} -->
+export const MARKER_TAG = "review-pr:v1";
+
+const MARKER = /^<!-- review-pr:v1 (\{.*\}) -->$/gm;
+const TEXT_FIELDS = ["fingerprint", "head", "base", "issueUpdatedAt", "prUpdatedAt"];
+const NUMBER_FIELDS = ["issue", "pr", "pass"];
+const SEPARATOR = "\x1e";
+
+// The producer captures bodies as `body="$(… | jq -r .body)"`; command
+// substitution strips trailing newlines before they reach sha256. Replicate
+// that and nothing else — any further normalisation (trimming, CRLF folding)
+// yields a different digest and would reject every real marker.
+function hashedBody(text) {
+  return String(text ?? "").replace(/\n+$/, "");
+}
+
+// sha256 of head, base, issue body and PR body joined by the ASCII record
+// separator, byte-identical to the producer's `compute_fingerprint`. Bodies —
+// not updatedAt — decide freshness, so a label edit or a new comment cannot
+// stale a review, while a real content change always does.
+export function computeFingerprint({ head, base, issueBody, prBody }) {
+  const parts = [String(head ?? ""), String(base ?? ""), hashedBody(issueBody), hashedBody(prBody)];
+  return createHash("sha256").update(parts.join(SEPARATOR), "utf8").digest("hex");
+}
+
+// Fail closed: an unsupported tag, malformed JSON, or a missing/ill-typed
+// field yields no marker at all, so it can never become an applicable review.
+// An unrecognised *verdict* is deliberately kept — the caller blocks on it
+// rather than relaunching a reviewer forever on input that will never parse.
+export function parseReviewMarkers(body) {
+  const markers = [];
+  // A web-UI edit can rewrite the comment with CRLF endings; strip CR first so
+  // the line-anchored match still sees the producer's exact line.
+  const text = String(body || "").replaceAll("\r", "");
+  for (const [, payload] of text.matchAll(MARKER)) {
+    let parsed;
+    try {
+      parsed = JSON.parse(payload);
+    } catch {
+      continue;
+    }
+    if (!parsed || typeof parsed !== "object") continue;
+    if (!TEXT_FIELDS.every((f) => typeof parsed[f] === "string" && parsed[f].length > 0)) continue;
+    if (!NUMBER_FIELDS.every((f) => Number.isInteger(parsed[f]))) continue;
+    if (typeof parsed.verdict !== "string") continue;
+    markers.push({
+      ...Object.fromEntries(TEXT_FIELDS.map((f) => [f, parsed[f]])),
+      ...Object.fromEntries(NUMBER_FIELDS.map((f) => [f, parsed[f]])),
+      verdict: parsed.verdict,
+    });
+  }
+  return markers;
+}
+
+// A marker counts only if the reviewing App identity authored it
+// (`viewerDidAuthor`), it names this exact issue/PR pair, and the state it
+// says it reviewed still equals live state. Every fingerprint input is public,
+// so without the author check any commenter could forge a PASS. Comparing
+// against live state needs no persistence, so a marker survives a supervisor
+// restart or a crash between the reviewer's comment and the label transition.
+export function selectApplicableMarker(comments, live) {
+  const want = computeFingerprint(live);
+  let found = null;
+  for (const comment of comments || []) {
+    if (comment?.viewerDidAuthor !== true) continue;
+    for (const marker of parseReviewMarkers(comment.body)) {
+      if (marker.issue !== live.issue || marker.pr !== live.pr) continue;
+      if (marker.fingerprint === want) found = marker;
+    }
+  }
+  return found;
+}