@loopover/miner 0.1.0

package/lib/calibration.js

@@ -0,0 +1,99 @@
+// Calibration report: join the miner's own predicted gate verdicts with the realized outcomes it later observed
+// (#4849). Read-only aggregation only — it never touches the live scoring/calibration logic that feeds the gate
+// (maintainer-owned). Builds on the types-only scaffolding in calibration-types.js.
+import {
+  isCalibrationReport,
+  isCalibrationRow,
+  isObservedOutcomeRecord,
+  isPredictedVerdictRecord,
+} from "./calibration-types.js";
+
+export { isCalibrationReport, isCalibrationRow, isObservedOutcomeRecord, isPredictedVerdictRecord };
+
+/** Normalize a decision string to the calibration vocabulary (`merge` / `close` / `hold`), or `""` when it is
+ *  unrecognized. `value` is always the already-validated non-empty string field of a record (the type guards run
+ *  first), so no non-string handling is needed here. Accepts both the predicted (`merge`/`close`/`hold`) and the
+ *  realized (`merged`/`closed`) forms. */
+function normalizeDecision(value) {
+  const decision = value.trim().toLowerCase();
+  if (decision === "merge" || decision === "merged") return "merge";
+  if (decision === "close" || decision === "closed") return "close";
+  if (decision === "hold") return "hold";
+  return "";
+}
+
+function emptyRow(project) {
+  return {
+    project,
+    wouldMerge: 0,
+    mergeConfirmed: 0,
+    mergeFalse: 0,
+    wouldClose: 0,
+    closeConfirmed: 0,
+    closeFalse: 0,
+    hold: 0,
+    decided: 0,
+    mergePrecision: null,
+    closePrecision: null,
+  };
+}
+
+// Key a record by its (project, targetId). Project and targetId are validated non-empty strings; the space
+// separator is fine for keying (collisions across different (project, targetId) pairs are astronomically
+// unlikely and would only merge two projects' tallies, never fabricate a false one).
+function recordKey(project, targetId) {
+  return `${project} ${targetId}`;
+}
+
+/**
+ * Join predicted-verdict records with realized-outcome records into a per-project calibration report. Pure and
+ * read-only. A prediction counts as "decided" only when a realized outcome for the SAME `(project, targetId)`
+ * exists AND resolves to a clear `merge` or `close`; a still-pending prediction (no outcome) or one whose outcome
+ * is unrecognized is skipped. Per project it tallies the confusion matrix (would-merge/close vs confirmed/false,
+ * plus holds) and derives merge/close precision (null below one relevant sample). Malformed records on either
+ * side are ignored. Rows are sorted by project for a stable render.
+ *
+ * @param {import("./calibration-types.js").PredictedVerdictRecord[]} predictions
+ * @param {import("./calibration-types.js").ObservedOutcomeRecord[]} outcomes
+ * @returns {import("./calibration-types.js").CalibrationReport}
+ */
+export function buildCalibrationReport(predictions, outcomes) {
+  const outcomeByKey = new Map();
+  for (const outcome of Array.isArray(outcomes) ? outcomes : []) {
+    if (!isObservedOutcomeRecord(outcome)) continue;
+    outcomeByKey.set(recordKey(outcome.project, outcome.targetId), normalizeDecision(outcome.outcomeDecision));
+  }
+
+  const byProject = new Map();
+  for (const prediction of Array.isArray(predictions) ? predictions : []) {
+    if (!isPredictedVerdictRecord(prediction)) continue;
+    const observed = outcomeByKey.get(recordKey(prediction.project, prediction.targetId));
+    if (observed !== "merge" && observed !== "close") continue; // pending or unclassifiable outcome
+    let row = byProject.get(prediction.project);
+    if (!row) {
+      row = emptyRow(prediction.project);
+      byProject.set(prediction.project, row);
+    }
+    row.decided += 1;
+    const predicted = normalizeDecision(prediction.predictedDecision);
+    if (predicted === "merge") {
+      row.wouldMerge += 1;
+      if (observed === "merge") row.mergeConfirmed += 1;
+      else row.mergeFalse += 1;
+    } else if (predicted === "close") {
+      row.wouldClose += 1;
+      if (observed === "close") row.closeConfirmed += 1;
+      else row.closeFalse += 1;
+    } else if (predicted === "hold") {
+      row.hold += 1;
+    }
+  }
+
+  const rows = [...byProject.values()].sort((a, b) => a.project.localeCompare(b.project));
+  for (const row of rows) {
+    row.mergePrecision = row.wouldMerge > 0 ? row.mergeConfirmed / row.wouldMerge : null;
+    row.closePrecision = row.wouldClose > 0 ? row.closeConfirmed / row.wouldClose : null;
+  }
+  // Signal exists once any project carries at least one decided (predicted-then-realized) sample.
+  return { hasSignal: rows.length > 0, rows };
+}

package/lib/ci-poller.d.ts

@@ -0,0 +1,33 @@
+export type CheckRunConclusion = "pending" | "success" | "failure" | "neutral";
+
+export type NormalizedCheckRun = {
+  name: string;
+  status: string;
+  conclusion: CheckRunConclusion;
+  detailsUrl: string | null;
+  startedAt: string | null;
+  completedAt: string | null;
+};
+
+export type PollCheckRunsResult = {
+  conclusion: CheckRunConclusion;
+  checks: NormalizedCheckRun[];
+  headSha: string;
+  attempts: number;
+};
+
+export type PollCheckRunsOptions = {
+  apiBaseUrl?: string;
+  fetchFn?: typeof fetch;
+  githubToken?: string;
+  maxAttempts?: number;
+  minIntervalMs?: number;
+  maxIntervalMs?: number;
+  sleepFn?: (delayMs: number) => Promise<unknown>;
+};
+
+export function pollCheckRuns(
+  repoFullName: string,
+  prNumber: number,
+  options?: PollCheckRunsOptions,
+): Promise<PollCheckRunsResult>;

package/lib/ci-poller.js

@@ -0,0 +1,234 @@
+import { fetchWithRetry } from "./http-retry.js";
+
+const defaultApiBaseUrl = "https://api.github.com";
+const defaultMinIntervalMs = 60_000;
+const defaultMaxIntervalMs = 5 * 60_000;
+const defaultMaxAttempts = 1;
+const githubApiVersion = "2022-11-28";
+
+function normalizeApiBaseUrl(value) {
+  if (value === undefined) return defaultApiBaseUrl;
+  if (typeof value !== "string" || !value.trim()) return defaultApiBaseUrl;
+  let parsed;
+  try {
+    parsed = new URL(value.trim());
+  } catch {
+    throw new Error("invalid_api_base_url");
+  }
+  if (parsed.protocol !== "https:" || parsed.hostname !== "api.github.com") {
+    throw new Error("invalid_api_base_url");
+  }
+  parsed.pathname = parsed.pathname.replace(/\/+$/, "");
+  parsed.search = "";
+  parsed.hash = "";
+  return parsed.toString().replace(/\/+$/, "");
+}
+
+function normalizePositiveInt(value, fallback, min, max) {
+  if (!Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(value)));
+}
+
+function normalizeOptions(options = {}) {
+  return {
+    apiBaseUrl: normalizeApiBaseUrl(options.apiBaseUrl),
+    fetchFn: options.fetchFn ?? fetch,
+    githubToken: typeof options.githubToken === "string" ? options.githubToken.trim() : "",
+    maxAttempts: normalizePositiveInt(options.maxAttempts, defaultMaxAttempts, 1, 20),
+    minIntervalMs: normalizePositiveInt(options.minIntervalMs, defaultMinIntervalMs, 1, 60 * 60_000),
+    maxIntervalMs: normalizePositiveInt(options.maxIntervalMs, defaultMaxIntervalMs, 1, 60 * 60_000),
+    sleepFn:
+      options.sleepFn ??
+      ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs))),
+  };
+}
+
+function parseRepoFullName(repoFullName) {
+  if (typeof repoFullName !== "string") throw new Error("invalid_repo_full_name");
+  const [owner, repo, extra] = repoFullName.split("/");
+  if (!owner?.trim() || !repo?.trim() || extra !== undefined) {
+    throw new Error("invalid_repo_full_name");
+  }
+  return { owner: owner.trim(), repo: repo.trim() };
+}
+
+function normalizePullNumber(value) {
+  if (!Number.isInteger(value) || value <= 0) throw new Error("invalid_pr_number");
+  return value;
+}
+
+function githubHeaders(githubToken) {
+  const headers = {
+    accept: "application/vnd.github+json",
+    "user-agent": "loopover-miner",
+    "x-github-api-version": githubApiVersion,
+  };
+  if (githubToken) headers.authorization = `Bearer ${githubToken}`;
+  return headers;
+}
+
+function repoPath(target, suffix) {
+  return `/repos/${encodeURIComponent(target.owner)}/${encodeURIComponent(target.repo)}${suffix}`;
+}
+
+function apiUrl(apiBaseUrl, path, query = "") {
+  return `${apiBaseUrl}${path}${query}`;
+}
+
+function githubError(response, payload) {
+  const code = `github_${response.status}`;
+  const githubMessage =
+    typeof payload?.message === "string" && payload.message.trim() ? payload.message : null;
+  const message = githubMessage ? `${code}: ${githubMessage}` : code;
+  return Object.assign(new Error(message), { code, githubMessage });
+}
+
+async function githubGetJsonResponse(url, options) {
+  // Retry transient network errors / 5xx around this single call (#4829), distinct from the poller's own
+  // pending-retry loop; the poller's injected sleepFn keeps tests instant.
+  const response = await fetchWithRetry(
+    options.fetchFn,
+    url,
+    { method: "GET", headers: githubHeaders(options.githubToken) },
+    { sleepFn: options.sleepFn },
+  );
+  const payload = await response.json().catch(() => null);
+  if (!response.ok) {
+    throw githubError(response, payload);
+  }
+  return { payload, response };
+}
+
+async function githubGetJson(url, options) {
+  const { payload } = await githubGetJsonResponse(url, options);
+  return payload;
+}
+
+function hasNextLink(response) {
+  return /<[^>]+>;\s*rel="next"/.test(response.headers.get("link") ?? "");
+}
+
+function payloadTotalCount(payload) {
+  const totalCount = Number(payload?.total_count);
+  return Number.isInteger(totalCount) && totalCount >= 0 ? totalCount : null;
+}
+
+function normalizeConclusion(checkRun) {
+  if (!checkRun || typeof checkRun !== "object") return "pending";
+  if (checkRun.status !== "completed") return "pending";
+  switch (checkRun.conclusion) {
+    case "success":
+    case "skipped":
+      return "success";
+    case "neutral":
+      return "neutral";
+    case "failure":
+    case "cancelled":
+    case "timed_out":
+    case "action_required":
+    case "stale":
+    case "startup_failure":
+      return "failure";
+    default:
+      return "pending";
+  }
+}
+
+function normalizeCheckRun(checkRun) {
+  return {
+    name: typeof checkRun?.name === "string" ? checkRun.name : "",
+    status: typeof checkRun?.status === "string" ? checkRun.status : "unknown",
+    conclusion: normalizeConclusion(checkRun),
+    detailsUrl: typeof checkRun?.details_url === "string" ? checkRun.details_url : null,
+    startedAt: typeof checkRun?.started_at === "string" ? checkRun.started_at : null,
+    completedAt: typeof checkRun?.completed_at === "string" ? checkRun.completed_at : null,
+  };
+}
+
+function aggregateConclusion(checks) {
+  if (checks.length === 0) return "pending";
+  if (checks.some((check) => check.conclusion === "failure")) return "failure";
+  if (checks.some((check) => check.conclusion === "pending")) return "pending";
+  if (checks.every((check) => check.conclusion === "success")) return "success";
+  return "neutral";
+}
+
+function backoffDelayMs(attemptIndex, options) {
+  const exponent = Math.min(10, Math.max(0, attemptIndex));
+  return Math.min(options.maxIntervalMs, options.minIntervalMs * 2 ** exponent);
+}
+
+async function fetchHeadSha(target, prNumber, options) {
+  const payload = await githubGetJson(
+    apiUrl(options.apiBaseUrl, repoPath(target, `/pulls/${prNumber}`)),
+    options,
+  );
+  const headSha = payload?.head?.sha;
+  if (typeof headSha !== "string" || !headSha) throw new Error("github_pr_head_sha_missing");
+  return headSha;
+}
+
+async function fetchCheckRuns(target, headSha, options) {
+  const checks = [];
+  let page = 1;
+  let expectedTotalCount = null;
+  while (true) {
+    const { payload, response } = await githubGetJsonResponse(
+      apiUrl(
+        options.apiBaseUrl,
+        repoPath(target, `/commits/${encodeURIComponent(headSha)}/check-runs`),
+        `?per_page=100&page=${page}`,
+      ),
+      options,
+    );
+    if (!Array.isArray(payload?.check_runs)) {
+      throw new Error("github_check_runs_malformed");
+    }
+    const pageChecks = payload.check_runs.map(normalizeCheckRun);
+    checks.push(...pageChecks);
+    expectedTotalCount = payloadTotalCount(payload) ?? expectedTotalCount;
+    if (!hasNextLink(response) && (expectedTotalCount === null || checks.length >= expectedTotalCount)) {
+      return checks;
+    }
+    if (pageChecks.length === 0) {
+      throw new Error("github_check_runs_pagination_incomplete");
+    }
+    page += 1;
+  }
+}
+
+export async function pollCheckRuns(repoFullName, prNumber, options = {}) {
+  const target = parseRepoFullName(repoFullName);
+  const normalizedPrNumber = normalizePullNumber(prNumber);
+  const normalizedOptions = normalizeOptions(options);
+
+  let latest = { conclusion: "pending", checks: [], headSha: "", attempts: 0 };
+  for (let attempt = 0; attempt < normalizedOptions.maxAttempts; attempt += 1) {
+    const headSha = await fetchHeadSha(target, normalizedPrNumber, normalizedOptions);
+    const checks = await fetchCheckRuns(target, headSha, normalizedOptions);
+    latest = {
+      conclusion: aggregateConclusion(checks),
+      checks,
+      headSha,
+      attempts: attempt + 1,
+    };
+    if (latest.conclusion !== "pending") {
+      const currentHeadSha = await fetchHeadSha(target, normalizedPrNumber, normalizedOptions);
+      if (currentHeadSha === headSha) {
+        return latest;
+      }
+      latest = {
+        conclusion: "pending",
+        checks: [],
+        headSha: currentHeadSha,
+        attempts: attempt + 1,
+      };
+    }
+    if (attempt === normalizedOptions.maxAttempts - 1) {
+      return latest;
+    }
+    await normalizedOptions.sleepFn(backoffDelayMs(attempt, normalizedOptions));
+  }
+
+  return latest;
+}

package/lib/claim-adjudication.d.ts

@@ -0,0 +1,21 @@
+/** An observed claim on an issue: a PR/claimant number plus when it claimed the linked issue (if known). */
+export type ObservedClaim = {
+  number: number;
+  claimedAt?: string | null | undefined;
+};
+
+/** The engine `DuplicateClaimMember` shape this module bridges an {@link ObservedClaim} to. */
+export type ClaimMember = {
+  number: number;
+  linkedIssueClaimedAt: string | null;
+};
+
+/** The adjudication result: the go/no-go `isWinner`, plus a DISPLAY-only `winnerNumber` (null when not determinable). */
+export type ClaimAdjudication = {
+  isWinner: boolean;
+  winnerNumber: number | null;
+};
+
+export function toClaimMember(claim: ObservedClaim): ClaimMember;
+
+export function adjudicateSoftClaim(self: ObservedClaim, competing?: readonly ObservedClaim[]): ClaimAdjudication;

package/lib/claim-adjudication.js

@@ -0,0 +1,36 @@
+// Soft-claim adjudication (#4291). Decides which of several miners claiming the same issue proceeds, by REUSING the
+// maintainer-side duplicate-cluster election (`isDuplicateClusterWinnerByClaim` from @loopover/engine)
+// rather than reimplementing it — so the miner and the maintainer gate agree on exactly one winner by construction.
+//
+// The local claim ledger is 100% client-side and cannot see other miners' claims, so the competing-claim signal
+// must come from something publicly observable: the OPEN PRs that link the same issue (an issue with several open
+// PRs linking it IS the public signal of a contested claim). The caller assembles that set — exactly like the
+// maintainer-side callers in src/ do — and passes it here.
+import { isDuplicateClusterWinnerByClaim, resolveDuplicateClusterWinnerNumber } from "@loopover/engine";
+
+/**
+ * Map an observed claim record to the engine's `DuplicateClaimMember`. The field names deliberately DIFFER — the
+ * local ledger / observed data expose `claimedAt`, the engine election reads `linkedIssueClaimedAt` — so the bridge
+ * is explicit (they are not interchangeable by accident of naming). `createdAt` is intentionally omitted: the
+ * election ignores it (an older PR can claim a linked issue later by editing its body). Pure.
+ */
+export function toClaimMember(claim) {
+  return { number: claim.number, linkedIssueClaimedAt: claim.claimedAt ?? null };
+}
+
+/**
+ * Adjudicate whether THIS miner's soft-claim wins a contested issue. `self` is this miner's claim and `competing`
+ * is the publicly-observable set of OTHER open PRs linking the same issue; each entry is `{ number, claimedAt }`.
+ * Returns the go/no-go `isWinner` (driven ONLY by `isDuplicateClusterWinnerByClaim`) plus a DISPLAY-only
+ * `winnerNumber` (from `resolveDuplicateClusterWinnerNumber`, for surfacing "you lost this claim to PR #N" to the
+ * operator — never for the decision). Pure — no IO. Fail-closed: a missing/sparse claim time loses; the winner is
+ * `null` when the ordering is too sparse to be sure (it never guesses). An empty `competing` list ⇒ trivial winner.
+ */
+export function adjudicateSoftClaim(self, competing = []) {
+  const selfMember = toClaimMember(self);
+  const siblings = competing.map(toClaimMember);
+  return {
+    isWinner: isDuplicateClusterWinnerByClaim(selfMember, siblings),
+    winnerNumber: resolveDuplicateClusterWinnerNumber(selfMember, siblings),
+  };
+}

package/lib/claim-conflict-resolver.d.ts

@@ -0,0 +1,29 @@
+import type { LiveIssueSnapshot } from "./submission-freshness-check.js";
+import type { ObservedClaim } from "./claim-adjudication.js";
+import type { LocalWriteActionSpec } from "@loopover/engine";
+
+export function assembleCompetingClaims(
+  snapshot: LiveIssueSnapshot | null | undefined,
+  selfPrNumber: number,
+  minerLogin: string,
+): ObservedClaim[];
+
+export type ClaimConflictInput = {
+  repoFullName: string;
+  issueNumber: number;
+  selfPrNumber: number;
+  selfClaimedAt: string | null;
+  minerLogin: string;
+};
+
+export type ClaimConflictDeps = {
+  fetchLiveIssueSnapshot: (repoFullName: string, issueNumber: number) => Promise<LiveIssueSnapshot | null>;
+  executeLocalWrite: (spec: LocalWriteActionSpec) => Promise<unknown>;
+};
+
+export type ClaimConflictResult =
+  | { checked: false; reason: "live_state_unavailable" }
+  | { checked: true; isWinner: true; winnerNumber: number | null; competingCount: number }
+  | { checked: true; isWinner: false; winnerNumber: number | null; competingCount: number; closeResult: unknown };
+
+export function resolveClaimConflict(input: ClaimConflictInput, deps: ClaimConflictDeps): Promise<ClaimConflictResult>;

package/lib/claim-conflict-resolver.js

@@ -0,0 +1,101 @@
+// Real claim-conflict resolution (#4848): the missing piece over claim-adjudication.js's own adjudicator,
+// which is correct and well-tested in isolation but has no caller that assembles a REAL competing-claims set.
+// checkSubmissionFreshness (submission-freshness-check.js) already catches the common case pre-submission --
+// aborting before open_pr if another author's PR already references the issue -- but that check can only see
+// what's PUBLIC at the moment it runs. Two miners racing closely enough that BOTH pass their own freshness
+// check before either's PR exists yet is a genuine TOCTOU window freshness cannot close. This module is the
+// POST-submission reconciliation for exactly that window: once THIS miner's PR is real and public, check
+// whether ANOTHER open PR also claims the same issue and, if this miner's claim loses the election, close its
+// own just-opened PR (never anyone else's) -- the write action the contributor-vs-maintainer safety framework
+// keeps maintainer-only (#4833's own scope note), since it means the autonomous loop acts on a race-resolution
+// decision with no human review.
+//
+// CLAIM-TIME ASYMMETRY (documented, not accidental): `self`'s claimedAt is the miner's OWN real local
+// claim-ledger timestamp (claim-ledger.js, recorded before work even started). A competing PR's claimedAt uses
+// its real GitHub `createdAt` instead -- the maintainer gate's own duplicate-winner election uses gittensory
+// server's "first observed this PR's linked-issue set" timestamp, but that requires a continuous, persistent
+// observation history this stateless client-side tool does not have for a PR it doesn't own. `createdAt` is
+// the best real, publicly-observable proxy available for someone else's PR -- live-issue-snapshot.js's own
+// comment on `createdAt` explains this in more detail.
+//
+// EVENTUAL CONSISTENCY: this checks GitHub's live state immediately after submission. A competing PR that
+// exists but hasn't yet propagated through GitHub's own search/GraphQL indexing in that instant would be
+// invisible to this one-shot check -- there is no retry/backoff here, which would be its own separate scope.
+
+import { adjudicateSoftClaim } from "./claim-adjudication.js";
+import { buildClosePrSpec } from "@loopover/engine";
+
+/**
+ * Assemble the real competing-claims set from a fetched LiveIssueSnapshot: every OTHER open PR referencing
+ * the issue, excluding `selfPrNumber` and any PR authored by `minerLogin` itself (case-insensitive, mirrors
+ * checkSubmissionFreshness's own author comparison -- a login can be echoed back with different casing).
+ * Excluding same-author PRs is deliberate, not an edge case slipping through: a miner never competes against
+ * its own work, so if this login somehow has ANOTHER open PR on the same issue (e.g. a retry after a crash
+ * left a stale one behind), that PR is never treated as a competing claim to lose against -- only a genuinely
+ * different claimant's PR can trigger a real close.
+ * Pure given its inputs.
+ *
+ * @param {import("./submission-freshness-check.js").LiveIssueSnapshot | null | undefined} snapshot
+ * @param {number} selfPrNumber
+ * @param {string} minerLogin
+ * @returns {import("./claim-adjudication.js").ObservedClaim[]}
+ */
+export function assembleCompetingClaims(snapshot, selfPrNumber, minerLogin) {
+  const minerLoginKey = minerLogin.trim().toLowerCase();
+  const referencingPrs = Array.isArray(snapshot?.referencingPrs) ? snapshot.referencingPrs : [];
+  return referencingPrs
+    .filter((pr) => pr.state === "open" && pr.number !== selfPrNumber)
+    .filter((pr) => typeof pr.authorLogin !== "string" || pr.authorLogin.trim().toLowerCase() !== minerLoginKey)
+    .map((pr) => ({ number: pr.number, claimedAt: pr.createdAt ?? null }));
+}
+
+/**
+ * Resolve a real claim conflict for an already-submitted PR. Fails OPEN (never closes anything) when the live
+ * snapshot can't be fetched -- an unavailable check is not evidence of a lost claim.
+ *
+ * @param {{ repoFullName: string, issueNumber: number, selfPrNumber: number, selfClaimedAt: string | null, minerLogin: string }} input
+ * @param {{
+ *   fetchLiveIssueSnapshot: (repoFullName: string, issueNumber: number) => Promise<import("./submission-freshness-check.js").LiveIssueSnapshot | null>,
+ *   executeLocalWrite: (spec: import("@loopover/engine").LocalWriteActionSpec) => Promise<unknown>,
+ * }} deps
+ * @returns {Promise<{
+ *   checked: boolean,
+ *   reason?: "live_state_unavailable",
+ *   isWinner?: boolean,
+ *   winnerNumber?: number | null,
+ *   competingCount?: number,
+ *   closeResult?: unknown,
+ * }>}
+ */
+export async function resolveClaimConflict(input, deps) {
+  let snapshot;
+  try {
+    snapshot = await deps.fetchLiveIssueSnapshot(input.repoFullName, input.issueNumber);
+  } catch {
+    snapshot = null;
+  }
+  if (!snapshot || typeof snapshot !== "object") {
+    return { checked: false, reason: "live_state_unavailable" };
+  }
+
+  const competing = assembleCompetingClaims(snapshot, input.selfPrNumber, input.minerLogin);
+  const adjudication = adjudicateSoftClaim({ number: input.selfPrNumber, claimedAt: input.selfClaimedAt }, competing);
+
+  if (adjudication.isWinner) {
+    return { checked: true, isWinner: true, winnerNumber: adjudication.winnerNumber, competingCount: competing.length };
+  }
+
+  const comment = adjudication.winnerNumber
+    ? `Closing this PR: pull request #${adjudication.winnerNumber} claimed this issue first. This is an automated soft-claim conflict resolution -- no action needed from you.`
+    : `Closing this PR: another open pull request already claims this issue. This is an automated soft-claim conflict resolution -- no action needed from you.`;
+  const spec = buildClosePrSpec({ repoFullName: input.repoFullName, number: input.selfPrNumber, comment });
+  const closeResult = await deps.executeLocalWrite(spec);
+
+  return {
+    checked: true,
+    isWinner: false,
+    winnerNumber: adjudication.winnerNumber,
+    competingCount: competing.length,
+    closeResult,
+  };
+}

package/lib/claim-ledger-cli.d.ts

@@ -0,0 +1,59 @@
+import type { ClaimEntry, ClaimLedger, ClaimStatus } from "./claim-ledger.js";
+
+export type ParsedClaimClaimArgs =
+  | {
+      repoFullName: string;
+      issueNumber: number;
+      note: string | undefined;
+      dryRun: boolean;
+      json: boolean;
+      apiBaseUrl: string | undefined;
+    }
+  | { error: string };
+
+export type ParsedClaimReleaseArgs =
+  | {
+      repoFullName: string;
+      issueNumber: number;
+      dryRun: boolean;
+      json: boolean;
+      apiBaseUrl: string | undefined;
+    }
+  | { error: string };
+
+export type ParsedClaimListArgs =
+  | {
+      json: boolean;
+      repoFullName: string | null;
+      status: ClaimStatus | null;
+    }
+  | { error: string };
+
+export function parseClaimClaimArgs(args: string[]): ParsedClaimClaimArgs;
+
+export function parseClaimReleaseArgs(args: string[]): ParsedClaimReleaseArgs;
+
+export function parseClaimListArgs(args: string[]): ParsedClaimListArgs;
+
+export function renderClaimsTable(entries: ClaimEntry[]): string;
+
+export function runClaimClaim(
+  args: string[],
+  options?: { openClaimLedger?: () => ClaimLedger },
+): number;
+
+export function runClaimRelease(
+  args: string[],
+  options?: { openClaimLedger?: () => ClaimLedger },
+): number;
+
+export function runClaimList(
+  args: string[],
+  options?: { openClaimLedger?: () => ClaimLedger },
+): number;
+
+export function runClaimCli(
+  subcommand: string | undefined,
+  args: string[],
+  options?: { openClaimLedger?: () => ClaimLedger },
+): number;