@codyswann/lisa 4.70.4 → 4.71.1

package/all/copy-overwrite/scripts/lisa-npm-updater.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+
+/**
+ * @file lisa-npm-updater.mjs
+ * @description Four phase entry points consume bounded data from a committed trusted host policy.
+ * @module npm-updater
+ */
+import { join, resolve } from "node:path";
+import { invokedAsScript } from "./lib/invoked-as-script.mjs";
+import {
+  required,
+  UpdaterError,
+  keys,
+  validatePolicy,
+  validateProposal,
+} from "./lib/npm-update-contract.mjs";
+import {
+  readJson,
+  writeJson,
+  runProcess,
+  phaseDirectory,
+} from "./lib/npm-update-process.mjs";
+import { prepareUpdate } from "./lib/npm-update-prepare.mjs";
+import { GitHub } from "./lib/npm-update-github.mjs";
+import { allocateLeaf } from "./lib/npm-update-allocate.mjs";
+import { publishProposal } from "./lib/npm-update-publish.mjs";
+import {
+  prepareAuthorization,
+  finalizeAuthorization,
+} from "./lib/npm-update-authorization.mjs";
+import { gateProposal } from "./lib/npm-update-gate.mjs";
+import { readGateProof } from "./lib/npm-update-gate-proof.mjs";
+import { sha256 } from "./lib/github-attestation-verifier.mjs";
+
+/** Only committed policy grants authority; ignored/local config cannot activate Actions. */
+async function configuration(cwd) {
+  const result = await runProcess("git", ["show", "HEAD:.lisa.config.json"], {
+    cwd,
+    env: { PATH: process.env.PATH, HOME: "/nonexistent" },
+    maximum: 1_048_576,
+  });
+  const config = JSON.parse(result.stdout.toString());
+  required(
+    config.automationProvenance?.enabled === true,
+    "automation provenance must be explicitly configured on committed main"
+  );
+  const policy = validatePolicy(config.npmUpdater, config);
+  required(
+    config.automationProvenance.repository === policy.repository,
+    "committed authority repository differs"
+  );
+  return { config, policy };
+}
+
+/** Allocation creates its canonical leaf before previewing any attributed commit. */
+async function allocatePhase(cwd, output, proposal, policy, config) {
+  const api = new GitHub(config.automationProvenance, process.env.GH_TOKEN);
+  const allocation = await allocateLeaf({
+    api,
+    proposal,
+    policy,
+    config,
+    cwd,
+  });
+  const result = await prepareAuthorization({
+    api,
+    cwd,
+    output,
+    proposal,
+    allocation,
+    policy,
+    config,
+  });
+  if (result.mode === "stale-outstanding")
+    writeJson(join(output, "authorization.json"), {
+      mode: result.mode,
+      workItem: allocation.workItem,
+    });
+  process.stdout.write(`${result.mode}\n`);
+}
+
+/** Publication consumes the fixed gated object and proof slots without changing authority order. */
+async function publishPhase(
+  cwd,
+  output,
+  proposal,
+  policy,
+  config,
+  allocation,
+  preview
+) {
+  const gated = readJson(join(output, "gated.json"));
+  keys(gated, ["raw", "receipt"]);
+  required(
+    typeof gated.raw === "string" && gated.raw.length <= 90_000,
+    "bounded raw commit envelope required"
+  );
+  const api = new GitHub(config.automationProvenance, process.env.GH_TOKEN);
+  const result = await publishProposal({
+    api,
+    cwd,
+    proposal,
+    policy,
+    config,
+    allocation,
+    descriptor: preview.descriptor,
+    proof: {
+      descriptor: join(output, "descriptor.json"),
+      bundle: join(output, "bundle.json"),
+      recovery: join(output, "recovery.json"),
+      recoveryBundle: join(output, "recovery-bundle.json"),
+    },
+    receipt: gated.receipt,
+    raw: Buffer.from(gated.raw, "base64"),
+  });
+  writeJson(join(output, "published.json"), result);
+  process.stdout.write(`${result.status} ${result.url}\n`);
+}
+
+/** Strict phase and fixed directory arguments are data, never a caller recipe. */
+export async function main(argv = process.argv.slice(2)) {
+  required(
+    argv.length === 3 &&
+      ["prepare", "allocate", "checkpoint", "gate", "publish"].includes(
+        argv[0]
+      ),
+    "usage: lisa-npm-updater.mjs <prepare|allocate|checkpoint|gate|publish> <owned-checkout> <private-phase-directory>"
+  );
+  const [phase, checkout, directory] = argv;
+  const cwd = resolve(checkout);
+  const output = resolve(directory);
+  const { config, policy } = await configuration(cwd);
+  phaseDirectory(output);
+  if (phase === "prepare") {
+    const result = await prepareUpdate({ cwd, policy, config });
+    writeJson(join(output, "prepare.json"), result);
+    if (result.status === "prepared")
+      writeJson(join(output, "proposal.json"), result.proposal);
+    process.stdout.write(`${result.status}\n`);
+    return;
+  }
+  const proposal = validateProposal(
+    readJson(join(output, "proposal.json")),
+    policy
+  );
+  if (phase === "allocate")
+    return allocatePhase(cwd, output, proposal, policy, config);
+  const allocation = readJson(join(output, "allocation.json"));
+  const preview = readJson(join(output, "preview.json"));
+  keys(preview, ["descriptor", "message", "epoch"]);
+  required(
+    sha256(preview.message) === preview.descriptor.messageSha256,
+    "preview final message differs"
+  );
+  if (phase === "checkpoint") {
+    const api = new GitHub(config.automationProvenance, process.env.GH_TOKEN);
+    const result = await finalizeAuthorization({
+      api,
+      output,
+      proposal,
+      allocation,
+      preview,
+      policy,
+      config,
+    });
+    process.stdout.write(`${result.mode} checkpoint complete\n`);
+    return;
+  }
+  if (phase === "gate") {
+    const result = await gateProposal({
+      cwd,
+      proposal,
+      policy,
+      allocation,
+      preview,
+      ...readGateProof(output),
+      token: process.env.GH_TOKEN,
+      config,
+    });
+    writeJson(join(output, "gated.json"), result);
+    process.stdout.write(`gated ${result.receipt.commit}\n`);
+    return;
+  }
+  return publishPhase(
+    cwd,
+    output,
+    proposal,
+    policy,
+    config,
+    allocation,
+    preview
+  );
+}
+
+if (invokedAsScript(import.meta.url))
+  main().catch(error => {
+    // Never print candidate/provider payloads or child output that may contain credentials.
+    process.stderr.write(
+      `${error instanceof UpdaterError ? error.message : "npm updater failed: required policy, authorization, installation, gate or exact publication evidence was unavailable"}\n`
+    );
+    process.exitCode = 1;
+  });

package/all/copy-overwrite/scripts/lisa-run-gates.mjs

@@ -41,15 +41,7 @@
  * @module lisa-run-gates
  */
 
-import {
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
-import { tmpdir } from "node:os";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -323,20 +315,21 @@ function formatLine(state, gate, detail) {
 /**
  * Read an executor's answer, whichever of the two shapes it returned.
  *
- * An executor may answer with a bare exit code or with `{code, output}`. Both
- * are supported on purpose: the exit code is the whole verdict, and the output
- * is only ever used to EXPLAIN a verdict already reached. An executor that
+ * An executor may answer with a bare exit code or with `{code, output}` and an
+ * optional OS-observed signal. Both retain the actual exit status; output and
+ * signal identity only EXPLAIN a verdict already reached. An executor that
  * cannot capture output — a stub, a Windows shell, a run with capture switched
  * off — therefore loses the diagnosis and nothing else.
- * @param {number|null|undefined|{code: number|null, output: string|null}} raw
+ * @param {number|null|undefined|{code: number|null, output: string|null, signal?: string}} raw
  *   Whatever the executor returned.
- * @returns {{code: number|null, output: string|null}} The normalised answer.
+ * @returns {{code: number|null, output: string|null, signal?: string}} The normalised answer.
  */
 function normaliseExec(raw) {
   if (raw !== null && typeof raw === "object") {
     return {
       code: typeof raw.code === "number" ? raw.code : null,
       output: typeof raw.output === "string" ? raw.output : null,
+      ...(typeof raw.signal === "string" ? { signal: raw.signal } : {}),
     };
   }
   return { code: typeof raw === "number" ? raw : null, output: null };
@@ -440,7 +433,7 @@ function stateFor(kind) {
 }
 
 function execute(gate, exec, declarations) {
-  const { code, output } = normaliseExec(exec(gate.command, gate));
+  const { code, output, signal } = normaliseExec(exec(gate.command, gate));
   if (code === 0) {
     // Exit 0 is ADJACENT to "the property holds"; it is not the observation.
     // A command that exited 0 while its own output says it collected zero
@@ -472,14 +465,14 @@ function execute(gate, exec, declarations) {
     };
   }
   const shown = typeof code === "number" ? code : "terminated";
-  // The code goes in as well as the output, and it is the half that matters
-  // most: a kill is legible ONLY in the exit code. `exit 143` is `128 + 15`,
-  // and on a saturated box it arrives carrying a truncated transcript that
+  // The actual status and signal go in as well as the output: a native kill
+  // retains null status, while a shell's `exit 143` is `128 + 15`. Either can
+  // arrive carrying a truncated transcript that
   // reads exactly like a real gate failure — which is how one `exit 1` came to
   // have three distinct causes with re-running a rational response to all of
   // them (CodySwannGT/lisa#2897).
   const diagnosis = withDeclarations(
-    diagnoseFailure(output, code),
+    diagnoseFailure(output, code, undefined, undefined, undefined, signal),
     output,
     declarations
   );
@@ -1141,12 +1134,6 @@ function readPackageScripts(cwd) {
   }
 }
 
-/**
- * How much of a gate's output is kept for diagnosis. A suite of 14,000 tests
- * prints megabytes; the signatures that matter are all near the end.
- */
-const CAPTURE_TAIL_BYTES = 512 * 1024;
-
 /**
  * Hang-detector deadline for one gate command, in milliseconds.
  *
@@ -1218,7 +1205,7 @@ function runInterruption() {
  */
 function runProcessTree(command, options = {}) {
   const timeout = options.timeout ?? GATE_COMMAND_BUDGET_MS;
-  const { shell: _shell, ...childOptions } = options;
+  const { shell: _shell, capture = false, ...childOptions } = options;
   // The supervisor already ends itself when THIS process dies; naming the
   // process above it is what covers the measured incident, where the hook was
   // killed and the runner — not the supervisor — was the orphan that kept the
@@ -1228,7 +1215,14 @@ function runProcessTree(command, options = {}) {
     : [];
   return boundedSpawnSync(
     process.execPath,
-    [PROCESS_TREE_RUNNER, `--timeout-ms=${timeout}`, ...watch, "--", command],
+    [
+      PROCESS_TREE_RUNNER,
+      `--timeout-ms=${timeout}`,
+      ...watch,
+      ...(capture ? ["--capture-fd=3"] : []),
+      "--",
+      command,
+    ],
     {
       ...childOptions,
       timeout: timeout + PROCESS_TREE_REAP_BUDGET_MS,
@@ -1260,7 +1254,7 @@ function killedOrRethrow(error) {
  * everything about capture is additive: if capture is unavailable or refused,
  * the exit code is produced by exactly the code path that produced it before.
  * @param {string} command The command line to run.
- * @returns {{code: number|null, output: null}} Exit code; null when killed.
+ * @returns {{code: number|null, output: null, signal?: string}} Exit code; null when killed.
  */
 function plainExec(command) {
   try {
@@ -1271,117 +1265,48 @@ function plainExec(command) {
     // Still reachable: a non-timeout `spawnSync` failure arrives on the result,
     // and it means nothing ran, which is the same "no verdict" answer.
     if (child.error) return { code: null, output: null };
-    return { code: child.status, output: null };
+    return {
+      code: child.status,
+      output: null,
+      ...(child.signal ? { signal: child.signal } : {}),
+    };
   } catch (error) {
     return killedOrRethrow(error);
   }
 }
 
 /**
- * Whether this machine can tee a gate's output without changing its verdict.
- *
- * Probed rather than assumed: on a shell without `tee` — Windows `cmd`, a
- * stripped container — the wrapper below would produce no status file, and the
- * runner would report every gate as terminated. A capability the runner cannot
- * confirm is one it does not use.
- * @returns {boolean} Whether to take the capturing path.
- */
-function captureAvailable() {
-  if (process.env.LISA_GATES_CAPTURE === "0") return false;
-  // The one child in this file that is NOT a project gate command, so it takes
-  // the shared default rather than the two-hour ceiling: `command -v tee`
-  // answers immediately or the shell is broken.
-  try {
-    const probe = boundedSpawnSync("sh", ["-c", "command -v tee"], {
-      stdio: "ignore",
-    });
-    return !probe.error && probe.status === 0;
-  } catch (error) {
-    // A probe killed at its deadline has not confirmed anything, and this
-    // function's whole contract is that an unconfirmed capability goes unused.
-    // Letting the throw escape would convert "cannot tell" into a crash, and
-    // the fallback path it guards answers the question perfectly well.
-    if (isChildTimeout(error)) return false;
-    throw error;
-  }
-}
-
-/**
- * Read back what the wrapper recorded, keeping only the tail of the log.
- * @param {string} statusPath File the wrapper wrote the exit code into.
- * @param {string} logPath File the wrapper tee'd the output into.
- * @returns {{code: number|null, output: string|null}} The recorded answer.
- */
-function readCaptured(statusPath, logPath) {
-  let output = null;
-  try {
-    output = readFileSync(logPath, "utf8").slice(-CAPTURE_TAIL_BYTES);
-  } catch {
-    output = null;
-  }
-  try {
-    const code = Number.parseInt(readFileSync(statusPath, "utf8").trim(), 10);
-    // Fail closed. An unreadable status is not a zero: the one thing this
-    // runner may never do is turn "I do not know" into "it passed".
-    return { code: Number.isInteger(code) ? code : null, output };
-  } catch {
-    return { code: null, output };
-  }
-}
-
-/**
- * The default executor: run the command in a shell, streaming AND recording.
- *
- * stdio is inherited so a failing gate's own output reaches the operator
- * unaltered and as it happens — a push gate runs for minutes and an operator
- * needs to watch it, not receive it in a lump at the end. `tee` is what lets
- * both be true: the operator sees the stream, and the runner keeps a copy to
- * say WHICH failure it was rather than only that there was one.
- *
- * The price is that the command's stdout is a pipe rather than a terminal, so
- * tools that colourise or animate for a TTY print their plain form. That is a
- * deliberate trade: a plain, diagnosable failure beats a coloured, mute one.
- * `LISA_GATES_CAPTURE=0` buys the colour back at the cost of the diagnosis.
- *
- * The exit code comes from a status file written INSIDE the pipeline, never
- * from the pipeline itself — a pipeline reports `tee`'s status, which is
- * almost always zero, and reading it would report every failing gate as
- * passing. That is the single most dangerous mistake available here.
- * @param {string} command The command line to run.
- * @returns {{code: number|null, output: string|null}} Exit code and output.
+ * Run a gate with live output and a supervisor-owned diagnostic tail.
+ *
+ * The extra pipe belongs only to the supervisor and its caller: the command
+ * inherits stdin and two output pipes, never the diagnostic descriptor. No
+ * child-writable status record participates in the verdict. Capture failures
+ * retain the supervised OS result and never execute the command a second time.
+ * Windows retains its existing native-job/plain route. Capture remains opt-out
+ * for commands that require inherited terminal handles.
+ * @param {string} command Shell source to run once.
+ * @returns {{code: number|null, output: string|null, signal?: string}} OS status and diagnostic tail.
  */
 export function spawnExec(command) {
-  if (!captureAvailable()) return plainExec(command);
-  let dir;
-  try {
-    dir = mkdtempSync(join(tmpdir(), "lisa-gate-run-"));
-  } catch {
+  if (process.env.LISA_GATES_CAPTURE === "0" || process.platform === "win32") {
     return plainExec(command);
   }
-  const logPath = join(dir, "output.log");
-  const statusPath = join(dir, "status");
-  // Newline-separated inside a group, so a command ending in a trailing
-  // comment or redirection still has `echo` run as its own statement.
-  // Paths travel as data, never as shell source. A TMPDIR containing a quote,
-  // newline, dollar sign, or command substitution must not be able to break
-  // this wrapper or execute content merely because mkdtemp inherited it.
-  const script = `{\n${command}\necho $? > "$LISA_GATE_STATUS_PATH"\n} 2>&1 | tee "$LISA_GATE_LOG_PATH"\n`;
   try {
-    const child = runProcessTree(script, {
-      env: {
-        ...process.env,
-        LISA_GATE_LOG_PATH: logPath,
-        LISA_GATE_STATUS_PATH: statusPath,
-      },
-      stdio: "inherit",
+    const child = runProcessTree(command, {
+      capture: true,
+      stdio: ["inherit", "inherit", "inherit", "pipe"],
       timeout: GATE_COMMAND_BUDGET_MS,
     });
     if (child.error) return { code: null, output: null };
-    return readCaptured(statusPath, logPath);
+    const captured = child.output?.[3];
+    return {
+      code: child.status,
+      ...(child.signal ? { signal: child.signal } : {}),
+      output:
+        captured === null || captured === undefined ? null : String(captured),
+    };
   } catch (error) {
     return killedOrRethrow(error);
-  } finally {
-    rmSync(dir, { force: true, recursive: true });
   }
 }
 

package/all/copy-overwrite/scripts/lisa-work-item.mjs

@@ -1016,7 +1016,7 @@ export function deployBranchEnvironments(config) {
   return new Map([[branch, PRODUCTION]]);
 }
 
-function trackerContract(config = readConfig()) {
+export function trackerContract(config = readConfig()) {
   const provider = requireString(config.tracker, "tracker").toLowerCase();
   const identityRepo = currentRepoIdentity(config);
   if (provider === "github") {
@@ -1483,6 +1483,38 @@ export function soleWorkItem(text, contract, subject) {
   return refs[0];
 }
 
+/**
+ * Resolve a required binding through the authoritative tracker contract.
+ * Consumers supplying trusted committed configuration avoid reparsing trailers
+ * or treating raw `current` output as a checked branch/queue identity.
+ * This does not change ordinary offline/live validation semantics.
+ * @param {string} message Complete final commit message.
+ * @param {object} [options] Trusted configuration and strict live requirement.
+ * @returns {object} Canonical identity and optional actual provider evidence.
+ */
+export function resolveWorkItemContext(message, options = {}) {
+  const contract = trackerContract(options.config ?? readConfig());
+  const state = readState(false);
+  const ref = soleWorkItem(message, contract, COMMIT_SUBJECT);
+  assertStateBranch(state);
+  assertStateMatches(ref, contract);
+  if (options.requireLive && contract.provider !== "github") {
+    throw new TrackingError("Automation provenance requires GitHub tracking");
+  }
+  const issue = options.requireLive
+    ? githubIssue(ref, contract, options.execute ?? run)
+    : undefined;
+  return {
+    ref,
+    provider: contract.provider,
+    repository: contract.repository,
+    identityRepo: contract.identityRepo,
+    branch: state.branch,
+    lifecycle: contract.lifecycle,
+    issue,
+  };
+}
+
 /**
  * The one work item a COMMIT message names.
  * @param {string} message Commit message.
@@ -1843,28 +1875,34 @@ function typeFromLabels(labels) {
  * @param {string|number} number GitHub issue number.
  * @returns {string[]} State of every sub-issue.
  */
-function githubHierarchy(ref, contract, number) {
+/** Literal typed GraphQL fields are shared by the canonical reader and closed native transport. */
+export function githubHierarchyArgs(contract, number, after) {
   const [owner, repo] = contract.repository.split("/");
   const query =
     "query($owner:String!,$repo:String!,$number:Int!,$after:String){repository(owner:$owner,name:$repo){issue(number:$number){subIssues(first:100,after:$after){nodes{state}pageInfo{hasNextPage endCursor}}}}}";
+  const args = [
+    "api",
+    "graphql",
+    "-f",
+    `query=${query}`,
+    "-F",
+    `owner=${owner}`,
+    "-F",
+    `repo=${repo}`,
+    "-F",
+    `number=${number}`,
+  ];
+  if (after) args.push("-F", `after=${after}`);
+  return args;
+}
+
+function githubHierarchy(ref, contract, number, execute = run) {
   const states = [];
   const cursor = { after: null };
 
   do {
-    const args = [
-      "api",
-      "graphql",
-      "-f",
-      `query=${query}`,
-      "-F",
-      `owner=${owner}`,
-      "-F",
-      `repo=${repo}`,
-      "-F",
-      `number=${number}`,
-    ];
-    if (cursor.after) args.push("-F", `after=${cursor.after}`);
-    const result = run("gh", args, { allowFailure: true });
+    const args = githubHierarchyArgs(contract, number, cursor.after);
+    const result = execute("gh", args, { allowFailure: true });
     if (result.status !== 0) throw githubFailure(result, ref);
 
     const response = safeJson(result.stdout, `GitHub issue ${ref} hierarchy`);
@@ -1952,20 +1990,25 @@ export function resetGhVersionCheck() {
   ghVersionChecked = false;
 }
 
-function githubIssue(ref, contract) {
-  assertGhVersion();
+/** The body is required by recovery; all ordinary canonical validation fields remain present. */
+export function githubIssueViewArgs(repository, number) {
+  return [
+    "issue",
+    "view",
+    number,
+    "--repo",
+    repository,
+    "--json",
+    "number,url,state,body,labels,comments,closedByPullRequestsReferences",
+  ];
+}
+
+function githubIssue(ref, contract, execute = run) {
+  assertGhVersion(execute);
   const number = ref.slice(ref.lastIndexOf("#") + 1);
-  const result = run(
+  const result = execute(
     "gh",
-    [
-      "issue",
-      "view",
-      number,
-      "--repo",
-      contract.repository,
-      "--json",
-      "number,url,state,labels,comments,closedByPullRequestsReferences",
-    ],
+    githubIssueViewArgs(contract.repository, number),
     {
       allowFailure: true,
     }
@@ -1985,7 +2028,7 @@ function githubIssue(ref, contract) {
   assertLeaf(
     ref,
     typeFromLabels(issue.labels),
-    githubHierarchy(ref, contract, number)
+    githubHierarchy(ref, contract, number, execute)
   );
   return issue;
 }
@@ -2410,7 +2453,7 @@ export function textContainsBacklink(value, prUrl) {
  * @param {string} prUrl Pull request URL.
  * @returns {string} The comment body.
  */
-function backlinkBody(prUrl) {
+export function backlinkBody(prUrl) {
   return `${MARKER} ${prUrl}`;
 }
 
@@ -2502,7 +2545,7 @@ function managedBacklinkTarget(body) {
  * @returns {{mine: unknown, others: number}} This PR's comment, and how many
  *   managed comments belong to OTHER pull requests.
  */
-function partitionBacklinks(comments, prUrl, bodyOf) {
+export function partitionBacklinks(comments, prUrl, bodyOf) {
   const mine = [];
   let others = 0;
   for (const comment of comments) {
@@ -2538,6 +2581,33 @@ export function backlinkReport(outcome, ref, prUrl) {
   );
 }
 
+/** Complete canonical pagination is shared by the writer and its scoped controller. */
+export function githubBacklinkListArgs(repository, number) {
+  if (
+    !/^[\w.-]+\/[\w.-]+$/.test(repository) ||
+    !/^[1-9]\d*$/.test(String(number))
+  )
+    throw new Error("invalid canonical GitHub backlink repository/issue");
+  return [
+    "api",
+    "--paginate",
+    "--slurp",
+    `repos/${repository}/issues/${number}/comments?per_page=100`,
+  ];
+}
+
+/** Complete slurped pages remain bounded and are shared by the canonical writer and controller grant. */
+export function githubBacklinkComments(pages) {
+  if (
+    !Array.isArray(pages) ||
+    pages.length < 1 ||
+    pages.length > 100 ||
+    pages.some(page => !Array.isArray(page) || page.length > 100)
+  )
+    throw new Error("invalid or over-bound GitHub backlink pages");
+  return pages.flat();
+}
+
 /**
  * Establish the backlink on a GitHub issue.
  * @param {string} ref Canonical `owner/repo#number` reference.
@@ -2547,17 +2617,13 @@ export function backlinkReport(outcome, ref, prUrl) {
  */
 function githubBacklink(ref, prUrl) {
   const [repository, number] = ref.split("#");
-  const listing = run(
-    "gh",
-    [
-      "api",
-      "--paginate",
-      `repos/${repository}/issues/${number}/comments?per_page=100`,
-    ],
-    { allowFailure: true }
-  );
+  const listing = run("gh", githubBacklinkListArgs(repository, number), {
+    allowFailure: true,
+  });
   if (listing.status !== 0) throw githubFailure(listing, ref);
-  const comments = safeJson(listing.stdout, `GitHub comments on ${ref}`);
+  const comments = githubBacklinkComments(
+    safeJson(listing.stdout, `GitHub comments on ${ref}`)
+  );
   // This listing is the read-before-write, and it is fetched here rather than
   // passed in for exactly that reason: the version you last wrote is not the
   // version that is live on a surface other agents also comment on.