@davidvornholt/standards 0.17.2 → 0.17.3

package/README.md

@@ -35,7 +35,7 @@ standards poller --print-units --config <path>
 
 `structure` enforces the canonical monorepo structure contract: workspace scripts (`check-types`, `lint`, `lint:fix`, `test`), root gate scripts, filtered Turbo convenience aliases, internal `0.0.0`/`workspace:*` versioning, package `exports`, shared tsconfig inheritance, and browser a11y wiring. Only a workspace containing an explicit `*.a11y.ts` suite must provide a `test:a11y` script and direct `@axe-core/playwright` and `@playwright/test` dependencies. `check` includes `structure`, so these rules gate every consumer PR.
 
-`poller` runs one tick of the fix poller: host-level automation that turns maintainer-approved GitHub issues into verified draft PRs and maintainer-approved draft PRs into completed review-fix cycles, using headless Codex runs. All workflow state lives in GitHub labels, comments, and draft PRs (the labels are canonical declared settings — see `github --apply`), so ticks are stateless, re-runnable, and safe to schedule from any host. A tick claims work by label (`fix-in-progress` / `review-in-progress`), releases claims stale for longer than `staleClaimHours`, and fails loudly — a red tick means jobs stalled, never silence. A separate acknowledgement tick validates pending approvals and posts one deduplicated queued message per approval generation; it never claims or starts work, so it can keep giving maintainers prompt feedback while the worker is occupied. When a worker claims a request, it posts a concise start message. The exact approval and distributed claim records remain in hidden comment metadata, and losing claim contenders remove their duplicate comments. Trust is verified per event, not per configuration: the approval labels (`approved-for-fix`, `approved-for-review`) only count when the applying user holds the `admin` or `maintain` role, bind to the exact approved issue revision or PR head, and are revalidated before publication; only admin/maintain comments are treated as answers to agent questions. Approved Codex runs inherit the poller's GitHub token and use authenticated `gh` for relevant reads and comments; review runs also maintain the PR review ledger, apply authorized title or body edits, post fix threads, and file deferred findings directly. The run works in a throwaway git worktree, grants Codex write access to that worktree and its exact Git common directory so commits can update the linked repository metadata, and hands results back through a structured outcome file. The poller then verifies the approved head, commits, and protected paths before pushing or publishing; it replies to and resolves agent-posted fix threads only after the reviewed head is pushed, and it alone changes protocol labels, posts the final report, and flips a reviewed draft ready, while required CI remains the quality gate. Sealed review plans from the earlier protocol are rejected and their output branches are ignored, so the review reruns on a fresh protocol-versioned branch rather than silently dropping legacy deferred work. Host mutation is declarative-only: `--print-units` emits four correctly escaped systemd units for the polling host's infrastructure repository to adapt and deploy: the worker service and timer plus an independent lightweight acknowledgement service and timer. That repository owns the service identity, writable HOME, PATH, authenticated `gh`, lingering, and deployment. The worker service's tick budget (`TimeoutStartSec`) is derived from `maxJobsPerTick` × `runTimeoutMinutes` plus overhead, so re-render and redeploy the units after changing either value.
+`poller` runs one tick of the fix poller: host-level automation that turns maintainer-approved GitHub issues into verified draft PRs and maintainer-approved draft PRs into completed review-fix cycles, using headless Codex runs. All workflow state lives in GitHub labels, comments, and draft PRs (the labels are canonical declared settings — see `github --apply`), so ticks are stateless, re-runnable, and safe to schedule from any host. A tick claims work by label (`fix-in-progress` / `review-in-progress`), releases claims stale for longer than `staleClaimHours`, and fails loudly — a red tick means jobs stalled, never silence. A separate acknowledgement tick validates pending approvals and posts one deduplicated queued message per approval generation; it never claims or starts work, so it can keep giving maintainers prompt feedback while the worker is occupied. When a worker claims a request, it posts a concise start message. The exact approval and distributed claim records remain in hidden comment metadata, and losing claim contenders remove their duplicate comments. Trust is verified per event, not per configuration: the approval labels (`approved-for-fix`, `approved-for-review`) only count when the applying user holds the `admin` or `maintain` role, bind to the exact approved issue revision or PR head, and are revalidated before publication; only admin/maintain comments are treated as answers to agent questions. Approved Codex runs inherit the poller's GitHub token and use authenticated `gh` for relevant reads and comments; review runs also maintain the PR review ledger, apply authorized title or body edits, post fix threads, and file deferred findings directly. The run works in a throwaway git worktree, grants Codex write access to that worktree and its exact Git common directory so commits can update the linked repository metadata, and hands results back through a structured outcome file. The poller then verifies the approved head, commits, and protected paths before pushing or publishing; it replies to and resolves agent-posted fix threads only after the reviewed head is pushed, and it alone changes protocol labels, posts the final report, and flips a reviewed draft ready, while required CI remains the quality gate. If publishing a sealed fix or review result fails, the poller releases only its owned in-progress claim and keeps the approval and sealed output, so the next worker tick retries publication without another Codex run. Sealed review plans from the earlier protocol are rejected and their output branches are ignored, so the review reruns on a fresh protocol-versioned branch rather than silently dropping legacy deferred work. Host mutation is declarative-only: `--print-units` emits four correctly escaped systemd units for the polling host's infrastructure repository to adapt and deploy: the worker service and timer plus an independent lightweight acknowledgement service and timer. That repository owns the service identity, writable HOME, PATH, authenticated `gh`, lingering, and deployment. The worker service's tick budget (`TimeoutStartSec`) is derived from `maxJobsPerTick` × `runTimeoutMinutes` plus overhead, so re-render and redeploy the units after changing either value.
 
 `creds` is the credential broker: it mints scoped Cloudflare tokens, rotates and revokes those tokens, and places GitHub App credentials into SOPS-encrypted targets — secret values never touch stdout, argv, or an agent's context; commands print only metadata (token name, scopes, expiry, destination). Cloudflare reconciliation has exactly two sources of truth: the plaintext key structure of the SOPS files and the provider token list under the deterministic naming scheme `standards/<owner>/<repo>/<sops-target>/<dotted.key>`; there is no separate credential manifest. `plan` and `apply` reconcile Cloudflare only: each run uses the stored bootstrap credential to verify its current provider token ID, excludes that ID from reconciliation regardless of its current name, and aborts if the identity cannot be correlated with the complete account token list; a brokered token whose SOPS key was deleted is revoked, while one nearing expiry (30 days) is renewed by creating a fresh-expiry replacement with the live token's policy, durably writing and verifying the new value, and only then revoking the old token; secrets the broker did not mint are never touched. Without a manifest there is no desired-policy record, so live policy drift is not detected, and a repository rename or transfer changes the deterministic namespace and requires the visible old token to be re-minted under the new name and revoked. `add cloudflare` mints an account-owned API token (default TTL 90 days) scoped to the named permission groups (`permissions` lists the valid names) and writes it to `--dest <target>:<dotted.key>`, where `<target>` resolves like the canonical `just secrets` targets (`ci` → `secrets/ci.yaml`, `prod-1` → `infra/hosts/prod-1/secrets.yaml`); zone-scoped groups such as DNS Write are rejected because the current command supplies an account resource, not a zone resource. `--bucket <name>` switches the policy resource to a single R2 bucket; `--jurisdiction default|eu` selects the provider jurisdiction and defaults to `default`, producing `com.cloudflare.edge.r2.bucket.<account_id>_default_<bucket>` or `com.cloudflare.edge.r2.bucket.<account_id>_eu_<bucket>`. FedRAMP jurisdictions are not supported. Bucket destinations accept only bucket-scoped groups such as Workers R2 Storage Bucket Item Read/Write, and account-scoped groups are rejected. `--s3` requires `--bucket` and stores the S3-compatible credential pair Cloudflare derives from an API token — access key ID is the token ID, secret access key is the SHA-256 hex digest of the token value — as `<dotted.key>.access_key_id` and `<dotted.key>.secret_access_key` under the destination instead of the raw token value; the default endpoint is `https://<account_id>.r2.cloudflarestorage.com`, while EU uses `https://<account_id>.eu.r2.cloudflarestorage.com`. Reconciliation infers each destination's concrete write footprint from the plaintext SOPS key structure — a bearer owns the leaf at its key, while an S3 token owns both pair leaves — and aborts before mutation when managed footprints intersect. `plan` and `apply` renew and revoke S3 destinations like any other brokered token, but renewal first proves the stored access key ID matches the current provider token; an incomplete pair, unreadable value, or identity mismatch is surfaced as a finding and never mutated automatically. `add github` writes the broker GitHub App's `app_id` and `private_key` under the destination key; durable GitHub tokens cannot be created via API (PAT and OAuth-app creation are UI-only), so workflows mint short-lived installation tokens from the App at runtime (`actions/create-github-app-token`), scoped per repository and permission. The canonical weekly sync expects `bun standards creds add github --dest ci:ci.broker_app`, then mints a current-repository token with Contents read and Pull requests write; missing credentials or minting failures stop it without a fallback. Bootstrap is once per machine: `login github` runs the App manifest flow (a localhost page posts the pre-filled manifest; one "Create GitHub App" click; credentials return through the conversion endpoint — nothing is copied by hand) and opens the installation page, where the App must be bound to selected repositories rather than all repositories; `login cloudflare` guides the one dashboard paste Cloudflare requires for the first account token (named `standards-broker` to match the App, created from the "Create additional tokens" token template because its "Account API Tokens: Edit" permission is unavailable in the custom token builder, and holding that permission only), verifies that it is active, correlates its verified ID with the complete account token list and an active list record, and stores it; a bootstrap token named inside the minted `standards/` namespace is rejected before storage to keep its role unambiguous, while any other divergence from the recommended name only warns. `plan` and `apply` do not rotate GitHub App keys; create a replacement key on the App's settings page, atomically replace `github.private_key` in the protected machine-global broker store while preserving its `0600` mode, then update every intended SOPS destination, verify workflows can mint installation tokens, and revoke the old key manually. Root credentials live in the machine-global broker store (see Configuration); SOPS writes go through `sops edit` with a non-interactive editor, preserving comments and reusing the file's data key.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -84,6 +84,8 @@
     "src/poller-codex-stderr.ts",
     "src/poller-commands.ts",
     "src/poller-comment-metadata.ts",
+    "src/poller-comment-reconciliation.ts",
+    "src/poller-claim-reconciliation.ts",
     "src/poller-config.ts",
     "src/poller-fix-outcome.ts",
     "src/poller-fix-output.ts",

package/src/poller-claim-reconciliation.ts

@@ -0,0 +1,160 @@
+import { isRecord } from './github-settings-parse';
+import type { ApprovalBinding } from './poller-approval';
+import { parseHiddenCommentMetadata } from './poller-comment-metadata';
+import { retainEarliestComment } from './poller-comment-reconciliation';
+import {
+  collaboratorRole,
+  type IssueComment,
+  listIssueComments,
+} from './poller-github';
+import { CLAIM_METADATA_MARKER, isTrustedRole } from './poller-protocol';
+
+export type ClaimMarkerBinding = {
+  readonly approval: ApprovalBinding;
+  readonly claimLabel: string;
+  readonly claimEpoch: string;
+};
+
+type ClaimMarker = ClaimMarkerBinding & {
+  readonly nonce: string;
+};
+
+type ClaimContext = {
+  readonly token: string | null;
+  readonly repo: string;
+  readonly issueNumber: number;
+};
+
+const isApprovalBinding = (value: unknown): value is ApprovalBinding =>
+  isRecord(value) &&
+  typeof value.id === 'string' &&
+  typeof value.repo === 'string' &&
+  typeof value.issueNumber === 'number' &&
+  typeof value.eventId === 'number' &&
+  typeof value.label === 'string' &&
+  typeof value.actorLogin === 'string' &&
+  typeof value.approvedAt === 'string' &&
+  typeof value.target === 'string';
+
+const parseMarker = (comment: IssueComment): ClaimMarker | null => {
+  const payload = parseHiddenCommentMetadata(
+    comment.body,
+    CLAIM_METADATA_MARKER,
+  );
+  if (!isRecord(payload)) {
+    return null;
+  }
+  if (
+    typeof payload.claimLabel !== 'string' ||
+    typeof payload.claimEpoch !== 'string' ||
+    typeof payload.nonce !== 'string' ||
+    !isApprovalBinding(payload.approval)
+  ) {
+    return null;
+  }
+  return {
+    approval: payload.approval,
+    claimLabel: payload.claimLabel,
+    claimEpoch: payload.claimEpoch,
+    nonce: payload.nonce,
+  };
+};
+
+const trustedMarkers = async (
+  context: ClaimContext,
+  matches: (marker: ClaimMarker) => boolean,
+): Promise<
+  ReadonlyArray<{ readonly id: number; readonly marker: ClaimMarker }>
+> => {
+  const comments = await listIssueComments(
+    context.token,
+    context.repo,
+    context.issueNumber,
+  );
+  const markers: Array<{ readonly id: number; readonly marker: ClaimMarker }> =
+    [];
+  for (const comment of comments) {
+    const marker = parseMarker(comment);
+    if (marker !== null && matches(marker)) {
+      // biome-ignore lint/performance/noAwaitInLoops: claim authors must be checked against their current role; the usually-one-item list is deliberately fail-closed.
+      const role = await collaboratorRole(
+        context.token,
+        context.repo,
+        comment.authorLogin,
+      );
+      if (isTrustedRole(role)) {
+        markers.push({ id: comment.id, marker });
+      }
+    }
+  }
+  return markers;
+};
+
+const claimGroupKey = (approvalId: string, claimEpoch: string): string =>
+  JSON.stringify([approvalId, claimEpoch]);
+
+const reconcileTrustedClaimGroups = async (
+  context: ClaimContext,
+  claimLabel: string,
+): Promise<
+  ReadonlyMap<
+    string,
+    {
+      readonly markerIds: ReadonlyArray<number>;
+      readonly retainedId: number | null;
+    }
+  >
+> => {
+  const groups = new Map<string, Array<number>>();
+  const markers = await trustedMarkers(
+    context,
+    (marker) => marker.claimLabel === claimLabel,
+  );
+  for (const { id, marker } of markers) {
+    const key = claimGroupKey(marker.approval.id, marker.claimEpoch);
+    const ids = groups.get(key) ?? [];
+    ids.push(id);
+    groups.set(key, ids);
+  }
+  const reconciled = new Map<
+    string,
+    {
+      readonly markerIds: ReadonlyArray<number>;
+      readonly retainedId: number | null;
+    }
+  >();
+  for (const [key, ids] of groups) {
+    // biome-ignore lint/performance/noAwaitInLoops: each group contains GitHub mutations and groups are deliberately reconciled serially.
+    const retainedId = await retainEarliestComment(context, ids);
+    reconciled.set(key, { markerIds: ids, retainedId });
+  }
+  return reconciled;
+};
+
+export const reconcileTrustedClaimElection = async (
+  context: ClaimContext,
+  binding: ClaimMarkerBinding,
+): Promise<{
+  readonly markerIds: ReadonlyArray<number>;
+  readonly retainedId: number | null;
+}> => {
+  const markers = await trustedMarkers(
+    context,
+    (marker) =>
+      marker.approval.id === binding.approval.id &&
+      marker.claimLabel === binding.claimLabel &&
+      marker.claimEpoch === binding.claimEpoch,
+  );
+  const markerIds = markers.map(({ id }) => id);
+  return {
+    markerIds,
+    retainedId: await retainEarliestComment(context, markerIds),
+  };
+};
+
+export const reconcileTrustedClaimHistory = async (
+  context: ClaimContext,
+  claimLabel: string,
+): Promise<void> => {
+  await reconcileTrustedClaimGroups(context, claimLabel);
+};

package/src/poller-claim.ts

@@ -1,34 +1,33 @@
 import { randomUUID } from 'node:crypto';
 import { hasLabel } from './github-label-identity';
-import { isRecord } from './github-settings-parse';
 import { type ApprovalBinding, readApprovalBinding } from './poller-approval';
 import {
-  hiddenCommentMetadata,
-  parseHiddenCommentMetadata,
-} from './poller-comment-metadata';
+  type ClaimMarkerBinding,
+  reconcileTrustedClaimElection,
+  reconcileTrustedClaimHistory,
+} from './poller-claim-reconciliation';
+import { hiddenCommentMetadata } from './poller-comment-metadata';
+import { getIssue, lastLabelEvent } from './poller-github';
 import {
-  collaboratorRole,
-  getIssue,
-  type IssueComment,
-  lastLabelEvent,
-  listIssueComments,
-} from './poller-github';
-import { createComment, deleteComment } from './poller-github-write';
+  addLabels,
+  createComment,
+  deleteComment,
+  removeLabel,
+} from './poller-github-write';
+import type { JobDeps } from './poller-job-shared';
 import {
   CLAIM_METADATA_MARKER,
   FIX_IN_PROGRESS,
-  isTrustedRole,
   REVIEW_IN_PROGRESS,
 } from './poller-protocol';
+import { inProgressLabelFor, type PollerJobKind } from './poller-queue-marker';
+import { reconcileExistingQueuedJob } from './poller-status';
 
-export type ClaimBinding = {
-  readonly approval: ApprovalBinding;
-  readonly claimLabel: string;
-  readonly claimEpoch: string;
+export type ClaimBinding = ClaimMarkerBinding & {
   readonly markerId: number;
 };
 
-type ClaimMarker = Omit<ClaimBinding, 'markerId'> & {
+type ClaimMarker = ClaimMarkerBinding & {
   readonly nonce: string;
 };
 
@@ -54,73 +53,6 @@ const markerBody = (marker: ClaimMarker): string =>
     marker,
   )}`;
 
-const isApprovalBinding = (value: unknown): value is ApprovalBinding =>
-  isRecord(value) &&
-  typeof value.id === 'string' &&
-  typeof value.repo === 'string' &&
-  typeof value.issueNumber === 'number' &&
-  typeof value.eventId === 'number' &&
-  typeof value.label === 'string' &&
-  typeof value.actorLogin === 'string' &&
-  typeof value.approvedAt === 'string' &&
-  typeof value.target === 'string';
-
-const parseMarker = (comment: IssueComment): ClaimMarker | null => {
-  const payload = parseHiddenCommentMetadata(
-    comment.body,
-    CLAIM_METADATA_MARKER,
-  );
-  if (!isRecord(payload)) {
-    return null;
-  }
-  const raw = payload;
-  if (
-    typeof raw.claimLabel !== 'string' ||
-    typeof raw.claimEpoch !== 'string' ||
-    typeof raw.nonce !== 'string' ||
-    !isApprovalBinding(raw.approval)
-  ) {
-    return null;
-  }
-  return {
-    approval: raw.approval,
-    claimLabel: raw.claimLabel,
-    claimEpoch: raw.claimEpoch,
-    nonce: raw.nonce,
-  };
-};
-
-const winningMarkerId = async (
-  context: ClaimContext,
-  binding: Omit<ClaimBinding, 'markerId'>,
-): Promise<number | null> => {
-  const comments = await listIssueComments(
-    context.token,
-    context.repo,
-    context.issueNumber,
-  );
-  let winner: number | null = null;
-  for (const comment of comments) {
-    const marker = parseMarker(comment);
-    const differs =
-      marker?.approval.id !== binding.approval.id ||
-      marker.claimLabel !== binding.claimLabel ||
-      marker.claimEpoch !== binding.claimEpoch;
-    if (!differs) {
-      // biome-ignore lint/performance/noAwaitInLoops: claim authors must be checked against their current role; the usually-one-item list is deliberately fail-closed.
-      const role = await collaboratorRole(
-        context.token,
-        context.repo,
-        comment.authorLogin,
-      );
-      if (isTrustedRole(role) && (winner === null || comment.id < winner)) {
-        winner = comment.id;
-      }
-    }
-  }
-  return winner;
-};
-
 export const acquireClaim = async (
   context: ClaimContext,
   approval: ApprovalBinding,
@@ -147,14 +79,36 @@ export const acquireClaim = async (
     context.issueNumber,
     markerBody({ ...provisional, nonce }),
   );
-  const winner = await winningMarkerId(context, provisional);
-  if (winner !== markerId) {
-    await deleteComment(context.token, context.repo, markerId);
+  const election = await reconcileTrustedClaimElection(context, provisional);
+  if (election.retainedId !== markerId) {
+    if (!election.markerIds.includes(markerId)) {
+      await deleteComment(context.token, context.repo, markerId);
+    }
     return null;
   }
   return { ...provisional, markerId };
 };
 
+export const startClaim = async (
+  deps: JobDeps,
+  issueNumber: number,
+  approval: ApprovalBinding,
+  kind: PollerJobKind,
+): Promise<ClaimBinding | null> => {
+  await reconcileExistingQueuedJob(deps, issueNumber, approval, kind);
+  const claimLabel = inProgressLabelFor(kind);
+  await reconcileTrustedClaimHistory(
+    { token: deps.token, repo: deps.repo, issueNumber },
+    claimLabel,
+  );
+  await addLabels(deps.token, deps.repo, issueNumber, [claimLabel]);
+  return acquireClaim(
+    { token: deps.token, repo: deps.repo, issueNumber },
+    approval,
+    claimLabel,
+  );
+};
+
 export const validateClaim = async (
   context: ClaimContext,
   claim: ClaimBinding,
@@ -182,8 +136,57 @@ export const validateClaim = async (
   if (!hasLabel(issue.labels, claim.claimLabel)) {
     return `"${claim.claimLabel}" is no longer present`;
   }
-  const winner = await winningMarkerId(context, claim);
-  return winner === claim.markerId
+  const election = await reconcileTrustedClaimElection(context, claim);
+  return election.retainedId === claim.markerId
     ? null
     : 'claim ownership changed or could not be proven';
 };
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const releaseOwnedClaim = async (
+  deps: JobDeps,
+  issueNumber: number,
+  claim: ClaimBinding,
+): Promise<void> => {
+  const context = { token: deps.token, repo: deps.repo, issueNumber };
+  const election = await reconcileTrustedClaimElection(context, claim);
+  const issue = await getIssue(deps.token, deps.repo, issueNumber);
+  const event = await lastLabelEvent(
+    deps.token,
+    deps.repo,
+    issueNumber,
+    claim.claimLabel,
+  );
+  if (
+    election.retainedId === claim.markerId &&
+    hasLabel(issue.labels, claim.claimLabel) &&
+    String(event?.id) === claim.claimEpoch
+  ) {
+    await removeLabel(deps.token, deps.repo, issueNumber, claim.claimLabel);
+  }
+};
+
+export const withClaimReleasedOnFailure = async <Result>(
+  deps: JobDeps,
+  issueNumber: number,
+  claim: ClaimBinding,
+  operation: () => Promise<Result>,
+): Promise<Result> => {
+  try {
+    return await operation();
+  } catch (operationError) {
+    try {
+      await releaseOwnedClaim(deps, issueNumber, claim);
+    } catch (releaseError) {
+      throw new Error(
+        `${errorMessage(operationError)}; releasing the claim for an automatic retry also failed: ${errorMessage(releaseError)}`,
+        {
+          cause: releaseError,
+        },
+      );
+    }
+    throw operationError;
+  }
+};

package/src/poller-comment-reconciliation.ts

@@ -0,0 +1,29 @@
+import { deleteComment } from './poller-github-write';
+
+type CommentContext = {
+  readonly token: string | null;
+  readonly repo: string;
+};
+
+export const earliestCommentId = (
+  commentIds: ReadonlyArray<number>,
+): number | null =>
+  commentIds.reduce<number | null>(
+    (earliest, commentId) =>
+      earliest === null || commentId < earliest ? commentId : earliest,
+    null,
+  );
+
+export const retainEarliestComment = async (
+  context: CommentContext,
+  commentIds: ReadonlyArray<number>,
+): Promise<number | null> => {
+  const retainedId = earliestCommentId(commentIds);
+  for (const commentId of commentIds) {
+    if (commentId !== retainedId) {
+      // biome-ignore lint/performance/noAwaitInLoops: GitHub mutations are deliberately serialized to avoid secondary rate limits.
+      await deleteComment(context.token, context.repo, commentId);
+    }
+  }
+  return retainedId;
+};

package/src/poller-fix-run.ts

@@ -3,7 +3,7 @@
 import { join } from 'node:path';
 import { hasLabel } from './github-label-identity';
 import { approvalIsCurrent, issueRevision } from './poller-approval';
-import { acquireClaim } from './poller-claim';
+import { startClaim, withClaimReleasedOnFailure } from './poller-claim';
 import { runCodex } from './poller-codex';
 import { handleNonFixedOutcome } from './poller-fix-outcome';
 import { readSealedFixOutput } from './poller-fix-output';
@@ -14,7 +14,6 @@ import {
   validateFixClaim,
 } from './poller-fix-publication';
 import { getIssue, type IssueItem } from './poller-github';
-import { addLabels } from './poller-github-write';
 import {
   failJob,
   type JobDeps,
@@ -118,12 +117,7 @@ export const runFixJob = async (
     await acknowledgeQueuedJob(deps, issue.number, preamble.approval, 'fix');
     return result(issue.number, 'waiting for run capacity');
   }
-  await addLabels(token, repo, issue.number, [FIX_IN_PROGRESS]);
-  const claim = await acquireClaim(
-    { token, repo, issueNumber: issue.number },
-    preamble.approval,
-    FIX_IN_PROGRESS,
-  );
+  const claim = await startClaim(deps, issue.number, preamble.approval, 'fix');
   if (claim === null) {
     return result(issue.number, 'another poller owns the claim');
   }
@@ -138,7 +132,11 @@ export const runFixJob = async (
   if (sealed !== null) {
     assertSealedOwnership(sealed, issue.number, claim.approval.id, branch);
     return {
-      lines: [await publishFixedOutput(resumableJob, FIX_LABELS, sealed, null)],
+      lines: [
+        await withClaimReleasedOnFailure(deps, issue.number, claim, () =>
+          publishFixedOutput(resumableJob, FIX_LABELS, sealed, null),
+        ),
+      ],
       ranCodex: false,
     };
   }
@@ -186,8 +184,13 @@ export const runFixJob = async (
       };
     }
     const nonFixed = await handleNonFixedOutcome(job, FIX_LABELS, outcome);
+    const message =
+      nonFixed ??
+      (await withClaimReleasedOnFailure(deps, issue.number, claim, () =>
+        finishFixedJob(job, FIX_LABELS, outcome),
+      ));
     return {
-      lines: [nonFixed ?? (await finishFixedJob(job, FIX_LABELS, outcome))],
+      lines: [message],
       ranCodex: true,
     };
   } finally {

package/src/poller-queue-marker.ts

@@ -182,13 +182,14 @@ export const inspectQueuedAcknowledgement = async (options: {
     item.number,
     expectedLabel,
   );
-  return (
-    event !== null &&
-    checkpoints.some(
-      (checkpoint) =>
-        checkpoint.eventId === event.id &&
-        checkpoint.actorLogin === event.actorLogin &&
-        checkpoint.approvedAt === event.createdAt,
-    )
-  );
+  if (event === null) {
+    return false;
+  }
+  const currentCheckpointCount = checkpoints.filter(
+    (checkpoint) =>
+      checkpoint.eventId === event.id &&
+      checkpoint.actorLogin === event.actorLogin &&
+      checkpoint.approvedAt === event.createdAt,
+  ).length;
+  return currentCheckpointCount === 1;
 };

package/src/poller-review-execution.ts

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import type { ClaimBinding } from './poller-claim';
+import { type ClaimBinding, withClaimReleasedOnFailure } from './poller-claim';
 import type { runCodex } from './poller-codex';
 import type { PullRequest } from './poller-github-pulls';
 import {
@@ -95,14 +95,16 @@ export const executeReviewJob = async (options: {
     }
     return {
       lines: [
-        await finishReviewedJob({
-          deps,
-          labels,
-          pr,
-          claim,
-          workDir: workspace.dir,
-          outcome,
-        }),
+        await withClaimReleasedOnFailure(deps, pr.number, claim, () =>
+          finishReviewedJob({
+            deps,
+            labels,
+            pr,
+            claim,
+            workDir: workspace.dir,
+            outcome,
+          }),
+        ),
       ],
       ranCodex: true,
     };

package/src/poller-review-run.ts

@@ -6,11 +6,10 @@
 
 import { hasLabel } from './github-label-identity';
 import { approvalIsCurrent, prRevision } from './poller-approval';
-import { acquireClaim } from './poller-claim';
+import { startClaim, withClaimReleasedOnFailure } from './poller-claim';
 import { runCodex } from './poller-codex';
 import { getIssue, type IssueItem } from './poller-github';
 import { getPullRequest } from './poller-github-pulls';
-import { addLabels } from './poller-github-write';
 import {
   failJob,
   type JobDeps,
@@ -86,7 +85,7 @@ export const runReviewJob = async (
     };
   }
   const pr = await getPullRequest(token, repo, prItem.number);
-  let plan = await currentReviewPlan(deps, pr);
+  const plan = await currentReviewPlan(deps, pr);
   const readTarget = () => currentReviewTarget(token, repo, pr.number, plan);
   const preamble = await jobPreamble(deps, currentItem, REVIEW_LABELS, {
     approved: prRevision(
@@ -157,32 +156,29 @@ export const runReviewJob = async (
       ranCodex: false,
     };
   }
-  await addLabels(token, repo, prItem.number, [REVIEW_IN_PROGRESS]);
-  const claim = await acquireClaim(
-    { token, repo, issueNumber: pr.number },
-    preamble.approval,
-    REVIEW_IN_PROGRESS,
-  );
+  const claim = await startClaim(deps, pr.number, preamble.approval, 'review');
   if (claim === null) {
     return {
       lines: [`PR #${pr.number}: another poller owns the claim`],
       ranCodex: false,
     };
   }
-  if (plan === null && sealed !== null) {
-    await publishReviewPlan(deps, pr, claim, sealed);
-    plan = sealed;
-  }
-  if (plan !== null) {
+  const resumablePlan = plan ?? sealed;
+  if (resumablePlan !== null) {
     return {
       lines: [
-        await resumeReviewedJob({
-          deps,
-          labels: REVIEW_LABELS,
-          pr,
-          claim,
-          plan,
-          cloneDir: cacheClone,
+        await withClaimReleasedOnFailure(deps, pr.number, claim, async () => {
+          if (plan === null) {
+            await publishReviewPlan(deps, pr, claim, resumablePlan);
+          }
+          return resumeReviewedJob({
+            deps,
+            labels: REVIEW_LABELS,
+            pr,
+            claim,
+            plan: resumablePlan,
+            cloneDir: cacheClone,
+          });
         }),
       ],
       ranCodex: false,

package/src/poller-schedule.ts

@@ -1,4 +1,5 @@
 import { hasLabel } from './github-label-identity';
+import { reconcileTrustedClaimHistory } from './poller-claim-reconciliation';
 import {
   type IssueItem,
   lastLabelEvent,
@@ -47,6 +48,10 @@ const sweepStaleClaims = async (
         ? Number.POSITIVE_INFINITY
         : now - Date.parse(event.createdAt);
     if (ageMs > config.staleClaimHours * MS_PER_HOUR) {
+      await reconcileTrustedClaimHistory(
+        { token, repo, issueNumber: item.number },
+        claimLabel,
+      );
       await removeLabel(token, repo, item.number, claimLabel);
       await createComment(
         token,

package/src/poller-status.ts

@@ -6,6 +6,7 @@ import {
   readApprovalBinding,
 } from './poller-approval';
 import { hiddenCommentMetadata } from './poller-comment-metadata';
+import { retainEarliestComment } from './poller-comment-reconciliation';
 import { getIssue } from './poller-github';
 import { getPullRequest } from './poller-github-pulls';
 import { createComment, deleteComment } from './poller-github-write';
@@ -94,16 +95,14 @@ export const acknowledgeQueuedJob = async (
   ) {
     return false;
   }
-  if (
-    (
-      await matchingTrustedQueueCommentIds(
-        deps,
-        issueNumber,
-        expected.approvalId,
-        kind,
-      )
-    ).length > 0
-  ) {
+  const existingMarkerIds = await matchingTrustedQueueCommentIds(
+    deps,
+    issueNumber,
+    expected.approvalId,
+    kind,
+  );
+  if (existingMarkerIds.length > 0) {
+    await retainEarliestComment(deps, existingMarkerIds);
     return false;
   }
   const markerId = await createComment(
@@ -115,16 +114,17 @@ export const acknowledgeQueuedJob = async (
       expected,
     )}`,
   );
-  const [winner] = [
-    ...(await matchingTrustedQueueCommentIds(
-      deps,
-      issueNumber,
-      expected.approvalId,
-      kind,
-    )),
-  ].sort((left, right) => left - right);
+  const markerIds = await matchingTrustedQueueCommentIds(
+    deps,
+    issueNumber,
+    expected.approvalId,
+    kind,
+  );
+  const winner = await retainEarliestComment(deps, markerIds);
   if (winner !== markerId) {
-    await deleteComment(deps.token, deps.repo, markerId);
+    if (!markerIds.includes(markerId)) {
+      await deleteComment(deps.token, deps.repo, markerId);
+    }
     return false;
   }
   if (!(await isStillQueueable(deps, issueNumber, approval, kind))) {
@@ -133,3 +133,18 @@ export const acknowledgeQueuedJob = async (
   }
   return true;
 };
+
+export const reconcileExistingQueuedJob = async (
+  deps: JobDeps,
+  issueNumber: number,
+  approval: ApprovalBinding,
+  kind: PollerJobKind,
+): Promise<void> => {
+  const markerIds = await matchingTrustedQueueCommentIds(
+    deps,
+    issueNumber,
+    approval.id,
+    kind,
+  );
+  await retainEarliestComment(deps, markerIds);
+};