@davidvornholt/standards 0.17.0 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {

package/src/poller-acknowledgements.ts

@@ -91,9 +91,8 @@ const acknowledgeItems = async (options: {
       // biome-ignore lint/performance/noAwaitInLoops: acknowledgement writes are deliberately serialized to avoid GitHub secondary rate limits.
       const approval = await approvalFor(deps, item, kind);
       if (
-        approval !== null &&
-        typeof approval !== 'string' &&
-        (await acknowledgeQueuedJob(deps, item.number, approval, kind))
+        approval?.kind === 'approved' &&
+        (await acknowledgeQueuedJob(deps, item.number, approval.approval, kind))
       ) {
         lines.push(
           `${deps.repo} ${kind === 'fix' ? `#${item.number}` : `PR #${item.number}`}: acknowledged as queued`,

package/src/poller-approval.ts

@@ -19,15 +19,45 @@ export type ApprovalBinding = {
   readonly target: string;
 };
 
+export type ApprovalBindingResult =
+  | {
+      readonly kind: 'approved';
+      readonly approval: ApprovalBinding;
+    }
+  | {
+      readonly kind: 'absent';
+    }
+  | {
+      readonly kind: 'rejected';
+      readonly generationId: string;
+      readonly reason: string;
+    };
+
 type ApprovalContext = {
   readonly token: string | null;
   readonly repo: string;
   readonly issueNumber: number;
 };
 
+export type ApprovalTargetReader = () => Promise<string | null>;
+
 const stableDigest = (value: unknown): string =>
   createHash('sha256').update(JSON.stringify(value)).digest('hex');
 
+const rejectionGenerationId = (
+  context: ApprovalContext,
+  label: string,
+  target: string,
+  event: Awaited<ReturnType<typeof lastLabelEvent>>,
+): string =>
+  stableDigest({
+    repo: context.repo,
+    issueNumber: context.issueNumber,
+    label,
+    target,
+    event,
+  });
+
 export const issueRevision = (issue: IssueItem): string =>
   `issue:${stableDigest({ title: issue.title, body: issue.body })}`;
 
@@ -41,14 +71,14 @@ export const readApprovalBinding = async (
   context: ApprovalContext,
   label: string,
   target: string,
-): Promise<ApprovalBinding | string> => {
+): Promise<ApprovalBindingResult> => {
   const issue = await getIssue(
     context.token,
     context.repo,
     context.issueNumber,
   );
   if (!hasLabel(issue.labels, label)) {
-    return `"${label}" is not currently present on ${context.repo}#${context.issueNumber}`;
+    return { kind: 'absent' };
   }
   const event = await lastLabelEvent(
     context.token,
@@ -57,7 +87,11 @@ export const readApprovalBinding = async (
     label,
   );
   if (event === null) {
-    return `no "${label}" label event found on ${context.repo}#${context.issueNumber}`;
+    return {
+      kind: 'rejected',
+      generationId: rejectionGenerationId(context, label, target, event),
+      reason: `no "${label}" label event found on ${context.repo}#${context.issueNumber}`,
+    };
   }
   const role = await collaboratorRole(
     context.token,
@@ -65,7 +99,11 @@ export const readApprovalBinding = async (
     event.actorLogin,
   );
   if (!isTrustedRole(role)) {
-    return `"${label}" on ${context.repo}#${context.issueNumber} was applied by ${event.actorLogin} (role: ${role}); only admin or maintain roles may approve automation`;
+    return {
+      kind: 'rejected',
+      generationId: rejectionGenerationId(context, label, target, event),
+      reason: `"${label}" on ${context.repo}#${context.issueNumber} was applied by ${event.actorLogin} (role: ${role}); only admin or maintain roles may approve automation`,
+    };
   }
   const fields = {
     repo: context.repo,
@@ -76,5 +114,24 @@ export const readApprovalBinding = async (
     approvedAt: event.createdAt,
     target,
   };
-  return { id: stableDigest(fields), ...fields };
+  return {
+    kind: 'approved',
+    approval: { id: stableDigest(fields), ...fields },
+  };
+};
+
+export const approvalIsCurrent = async (
+  context: ApprovalContext,
+  approval: ApprovalBinding,
+  readTarget: ApprovalTargetReader,
+): Promise<boolean> => {
+  const current = await readApprovalBinding(
+    context,
+    approval.label,
+    approval.target,
+  );
+  if (current.kind !== 'approved' || current.approval.id !== approval.id) {
+    return false;
+  }
+  return (await readTarget()) === approval.target;
 };

package/src/poller-claim.ts

@@ -165,10 +165,13 @@ export const validateClaim = async (
     claim.approval.label,
     currentTarget,
   );
-  if (typeof current === 'string') {
-    return current;
+  if (current.kind === 'absent') {
+    return `"${claim.approval.label}" is not currently present`;
   }
-  if (current.id !== claim.approval.id) {
+  if (current.kind === 'rejected') {
+    return current.reason;
+  }
+  if (current.approval.id !== claim.approval.id) {
     return 'approval no longer matches the exact approved revision/head';
   }
   const issue = await getIssue(

package/src/poller-fix-run.ts

@@ -1,9 +1,8 @@
-// One fix job: a maintainer-approved issue becomes a verified draft PR, a
-// precise question, or an explicit failure — never silence. Every transition
-// is written back to GitHub so the next tick (or a human) resumes from there.
+// A maintainer-approved issue becomes a verified draft PR, question, or failure.
 
 import { join } from 'node:path';
-import { issueRevision } from './poller-approval';
+import { hasLabel } from './github-label-identity';
+import { approvalIsCurrent, issueRevision } from './poller-approval';
 import { acquireClaim } from './poller-claim';
 import { runCodex } from './poller-codex';
 import { handleNonFixedOutcome } from './poller-fix-outcome';
@@ -55,29 +54,49 @@ const hasInvalidLocalOutput = (
   branch: string,
 ): boolean => sealed === null && localBranchExists(cloneDir, branch);
 
+const result = (issueNumber: number, message: string): JobResult => ({
+  lines: [`#${issueNumber}: ${message}`],
+  ranCodex: false,
+});
+
+const assertSealedOwnership = (
+  sealed: NonNullable<ReturnType<typeof readSealedFixOutput>>,
+  issueNumber: number,
+  approvalId: string,
+  branch: string,
+): void => {
+  if (sealed.issueNumber !== issueNumber || sealed.approvalId !== approvalId) {
+    throw new Error(`sealed output on ${branch} has invalid ownership`);
+  }
+};
+
 export const runFixJob = async (
   deps: JobDeps,
   issue: IssueItem,
-  defaultBranch: string,
+  resolveDefaultBranch: () => Promise<string>,
   allowCodex = true,
 ): Promise<JobResult> => {
   const { config, token, repo } = deps;
   const currentIssue = await getIssue(token, repo, issue.number);
-  const preamble = await jobPreamble(
-    deps,
-    currentIssue,
-    FIX_LABELS,
-    issueRevision(currentIssue),
-  );
+  if (!hasLabel(currentIssue.labels, APPROVED_FOR_FIX)) {
+    return result(issue.number, 'approval no longer present; skipped');
+  }
+  const readTarget = async (): Promise<string> =>
+    issueRevision(await getIssue(token, repo, issue.number));
+  const preamble = await jobPreamble(deps, currentIssue, FIX_LABELS, {
+    approved: issueRevision(currentIssue),
+    readCurrent: readTarget,
+  });
+  if (preamble.kind === 'stale') {
+    return result(issue.number, 'approval no longer present; skipped');
+  }
   if (preamble.kind === 'rejected') {
-    return { lines: [`#${issue.number}: approval rejected`], ranCodex: false };
+    return result(issue.number, 'approval rejected');
   }
   if (preamble.kind === 'waiting') {
-    return {
-      lines: [`#${issue.number}: waiting on an answer`],
-      ranCodex: false,
-    };
+    return result(issue.number, 'waiting on an answer');
   }
+  const defaultBranch = await resolveDefaultBranch();
   const cacheClone = ensureCacheClone(config.cacheDir, repo, token);
   const branch = branchNameForIssue(issue.number, preamble.approval.id);
   const sealed = readSealedFixOutput(cacheClone, branch);
@@ -86,12 +105,18 @@ export const runFixJob = async (
       `refusing to overwrite ${branch}: it is not valid sealed output for this approval`,
     );
   }
+  if (
+    !(await approvalIsCurrent(
+      { token, repo, issueNumber: issue.number },
+      preamble.approval,
+      readTarget,
+    ))
+  ) {
+    return result(issue.number, 'approval generation changed; skipped');
+  }
   if (sealed === null && !allowCodex) {
     await acknowledgeQueuedJob(deps, issue.number, preamble.approval, 'fix');
-    return {
-      lines: [`#${issue.number}: waiting for run capacity`],
-      ranCodex: false,
-    };
+    return result(issue.number, 'waiting for run capacity');
   }
   await addLabels(token, repo, issue.number, [FIX_IN_PROGRESS]);
   const claim = await acquireClaim(
@@ -100,10 +125,7 @@ export const runFixJob = async (
     FIX_IN_PROGRESS,
   );
   if (claim === null) {
-    return {
-      lines: [`#${issue.number}: another poller owns the claim`],
-      ranCodex: false,
-    };
+    return result(issue.number, 'another poller owns the claim');
   }
   const resumableJob = {
     deps,
@@ -114,12 +136,7 @@ export const runFixJob = async (
     cloneDir: cacheClone,
   };
   if (sealed !== null) {
-    if (
-      sealed.issueNumber !== issue.number ||
-      sealed.approvalId !== claim.approval.id
-    ) {
-      throw new Error(`sealed output on ${branch} has invalid ownership`);
-    }
+    assertSealedOwnership(sealed, issue.number, claim.approval.id, branch);
     return {
       lines: [await publishFixedOutput(resumableJob, FIX_LABELS, sealed, null)],
       ranCodex: false,

package/src/poller-github.ts

@@ -1,11 +1,7 @@
-// Read-side GitHub helpers for the poller. Every function either returns a
-// narrow parsed shape or throws with the failing endpoint in the message; the
-// tick converts per-job throws into reported problems. Lists are always read
-// exhaustively (see github-paginate.ts) — the trust anchor is "the latest
-// label event", which a truncated page would silently falsify.
+// Read-side GitHub helpers return narrow parsed shapes or throw.
 
 import { apiError, HTTP_OK, request } from './github-api';
-import { labelIdentity } from './github-label-identity';
+import { hasLabel, labelIdentity } from './github-label-identity';
 import { listAllPages } from './github-paginate';
 import { isNonEmptyString, isRecord } from './github-settings-parse';
 
@@ -34,23 +30,32 @@ export type LabelEvent = {
 const asString = (value: unknown): string =>
   typeof value === 'string' ? value : '';
 
-const labelNames = (raw: unknown): ReadonlyArray<string> =>
-  Array.isArray(raw)
-    ? raw
-        .map((label) => (isRecord(label) ? asString(label.name) : ''))
-        .filter((name) => name.length > 0)
-    : [];
+const labelNames = (raw: unknown): ReadonlyArray<string> | null => {
+  if (
+    !(
+      Array.isArray(raw) &&
+      raw.every((label) => isRecord(label) && isNonEmptyString(label.name))
+    )
+  ) {
+    return null;
+  }
+  return raw.map((label) => (label as { readonly name: string }).name);
+};
 
 export const parseIssue = (raw: unknown): IssueItem | null => {
   if (!(isRecord(raw) && typeof raw.number === 'number')) {
     return null;
   }
+  const labels = labelNames(raw.labels);
+  if (labels === null) {
+    return null;
+  }
   return {
     number: raw.number,
     title: asString(raw.title),
     body: asString(raw.body),
     isPullRequest: isRecord(raw.pull_request),
-    labels: labelNames(raw.labels),
+    labels,
     authorLogin: isRecord(raw.user) ? asString(raw.user.login) : '',
   };
 };
@@ -82,9 +87,15 @@ export const listOpenIssuesWithLabel = async (
     `/repos/${repo}/issues?state=open&labels=${encodeURIComponent(label)}`,
     `list ${repo} issues labeled ${label}`,
   );
-  return items
-    .map(parseIssue)
-    .filter((issue): issue is IssueItem => issue !== null);
+  return items.flatMap((raw, index) => {
+    const issue = parseIssue(raw);
+    if (issue === null) {
+      throw new Error(
+        `list ${repo} issues labeled ${label}: invalid issue at index ${index}`,
+      );
+    }
+    return hasLabel(issue.labels, label) ? [issue] : [];
+  });
 };
 
 export const listIssueComments = async (
@@ -151,9 +162,7 @@ export const lastLabelEvent = async (
   return latest;
 };
 
-// role_name distinguishes maintain from write; the legacy `permission` field
-// collapses both to "write" and cannot express the trust boundary. A 404
-// means "not a collaborator" — an untrusted answer, not an API failure.
+// role_name preserves the maintain/write trust boundary. A 404 is untrusted.
 export const collaboratorRole = async (
   token: string | null,
   repo: string,

package/src/poller-job-shared.ts

@@ -3,7 +3,12 @@
 // approval/progress/failure labels the job family uses.
 
 import { hasLabel } from './github-label-identity';
-import { type ApprovalBinding, readApprovalBinding } from './poller-approval';
+import {
+  type ApprovalBinding,
+  type ApprovalTargetReader,
+  approvalIsCurrent,
+  readApprovalBinding,
+} from './poller-approval';
 import type { PollerConfig } from './poller-config';
 import { addLabels, createComment, removeLabel } from './poller-github-write';
 import {
@@ -31,11 +36,17 @@ export type JobLabels = {
   readonly failed: string;
 };
 
+type JobTarget = {
+  readonly approved: string;
+  readonly readCurrent: ApprovalTargetReader;
+};
+
 // Must exceed runCodex's failure string at its longest (its stderr snippet
 // plus the exit-cause prefix), so the diagnostic tail is never cut off.
 const FAILURE_SNIPPET_LIMIT = 4000;
 
 export type JobPreamble =
+  | { readonly kind: 'stale' }
   | { readonly kind: 'rejected' }
   | { readonly kind: 'waiting' }
   | {
@@ -51,7 +62,7 @@ export const jobPreamble = async (
   deps: JobDeps,
   item: { readonly number: number; readonly labels: ReadonlyArray<string> },
   labels: JobLabels,
-  target: string,
+  target: JobTarget,
 ): Promise<JobPreamble> => {
   const trust = {
     token: deps.token,
@@ -59,18 +70,44 @@ export const jobPreamble = async (
     issueNumber: item.number,
     roleCache: deps.roleCache,
   };
-  const approval = await readApprovalBinding(trust, labels.approved, target);
-  if (typeof approval === 'string') {
+  const approval = await readApprovalBinding(
+    trust,
+    labels.approved,
+    target.approved,
+  );
+  if (approval.kind === 'absent') {
+    return { kind: 'stale' };
+  }
+  if (approval.kind === 'rejected') {
+    const current = await readApprovalBinding(
+      trust,
+      labels.approved,
+      target.approved,
+    );
+    if (
+      current.kind !== 'rejected' ||
+      current.generationId !== approval.generationId
+    ) {
+      return { kind: 'stale' };
+    }
+    if ((await target.readCurrent()) !== target.approved) {
+      return { kind: 'stale' };
+    }
     await removeLabel(deps.token, deps.repo, item.number, labels.approved);
     await createComment(
       deps.token,
       deps.repo,
       item.number,
-      `${FAILURE_MARKER}\nApproval not honored: ${approval}`,
+      `${FAILURE_MARKER}\nApproval not honored: ${approval.reason}`,
     );
     return { kind: 'rejected' };
   }
   const answers = await answerState(trust);
+  if (
+    !(await approvalIsCurrent(trust, approval.approval, target.readCurrent))
+  ) {
+    return { kind: 'stale' };
+  }
   if (answers.waiting) {
     if (!hasLabel(item.labels, NEEDS_CLARIFICATION)) {
       await addLabels(deps.token, deps.repo, item.number, [
@@ -83,7 +120,11 @@ export const jobPreamble = async (
   if (hasLabel(item.labels, NEEDS_CLARIFICATION)) {
     await removeLabel(deps.token, deps.repo, item.number, NEEDS_CLARIFICATION);
   }
-  return { kind: 'go', answers: answers.answers, approval };
+  return {
+    kind: 'go',
+    answers: answers.answers,
+    approval: approval.approval,
+  };
 };
 
 export const failJob = async (

package/src/poller-review-run.ts

@@ -4,7 +4,8 @@
 // verifies and pushes those commits, posts the final report, and flips the PR
 // ready.
 
-import { prRevision } from './poller-approval';
+import { hasLabel } from './github-label-identity';
+import { approvalIsCurrent, prRevision } from './poller-approval';
 import { acquireClaim } from './poller-claim';
 import { runCodex } from './poller-codex';
 import { getIssue, type IssueItem } from './poller-github';
@@ -49,6 +50,27 @@ const hasInvalidLocalOutput = (
 ): boolean =>
   plan === null && sealed === null && localBranchExists(cloneDir, branch);
 
+const currentReviewTarget = async (
+  token: string | null,
+  repo: string,
+  prNumber: number,
+  plan: Awaited<ReturnType<typeof readReviewPlan>>,
+): Promise<string | null> => {
+  const current = await getPullRequest(token, repo, prNumber);
+  if (
+    plan !== null &&
+    current.headSha !== plan.approvedHead &&
+    current.headSha !== plan.publishedHead
+  ) {
+    return null;
+  }
+  return prRevision(
+    current.baseRef,
+    current.baseSha,
+    plan === null ? current.headSha : plan.approvedHead,
+  );
+};
+
 export const runReviewJob = async (
   deps: JobDeps,
   prItem: IssueItem,
@@ -56,15 +78,30 @@ export const runReviewJob = async (
   runAgent: typeof runCodex = runCodex,
 ): Promise<JobResult> => {
   const { config, token, repo } = deps;
+  const currentItem = await getIssue(token, repo, prItem.number);
+  if (!hasLabel(currentItem.labels, APPROVED_FOR_REVIEW)) {
+    return {
+      lines: [`PR #${prItem.number}: approval no longer present; skipped`],
+      ranCodex: false,
+    };
+  }
   const pr = await getPullRequest(token, repo, prItem.number);
   let plan = await currentReviewPlan(deps, pr);
-  const currentItem = await getIssue(token, repo, prItem.number);
-  const preamble = await jobPreamble(
-    deps,
-    currentItem,
-    REVIEW_LABELS,
-    prRevision(pr.baseRef, pr.baseSha, plan?.approvedHead ?? pr.headSha),
-  );
+  const readTarget = () => currentReviewTarget(token, repo, pr.number, plan);
+  const preamble = await jobPreamble(deps, currentItem, REVIEW_LABELS, {
+    approved: prRevision(
+      pr.baseRef,
+      pr.baseSha,
+      plan?.approvedHead ?? pr.headSha,
+    ),
+    readCurrent: readTarget,
+  });
+  if (preamble.kind === 'stale') {
+    return {
+      lines: [`PR #${prItem.number}: approval no longer present; skipped`],
+      ranCodex: false,
+    };
+  }
   if (preamble.kind === 'rejected') {
     return {
       lines: [`PR #${prItem.number}: approval rejected`],
@@ -101,6 +138,18 @@ export const runReviewJob = async (
   if (hasInvalidLocalOutput(plan, sealed, cacheClone, outputBranch)) {
     throw new Error(`sealed output on ${outputBranch} is invalid`);
   }
+  if (
+    !(await approvalIsCurrent(
+      { token, repo, issueNumber: pr.number },
+      preamble.approval,
+      readTarget,
+    ))
+  ) {
+    return {
+      lines: [`PR #${pr.number}: approval generation changed; skipped`],
+      ranCodex: false,
+    };
+  }
   if (plan === null && sealed === null && !allowCodex) {
     await acknowledgeQueuedJob(deps, pr.number, preamble.approval, 'review');
     return {

package/src/poller-review-state.ts

@@ -43,7 +43,10 @@ export const readReviewPlan = async (
           APPROVED_FOR_REVIEW,
           prRevision(plan.baseRef, plan.baseSha, plan.approvedHead),
         );
-        if (typeof binding !== 'string' && binding.id === plan.approvalId) {
+        if (
+          binding.kind === 'approved' &&
+          binding.approval.id === plan.approvalId
+        ) {
           currentPlans.push(plan);
         }
       }

package/src/poller-status.ts

@@ -74,7 +74,8 @@ const isStillQueueable = async (
     target,
   );
   return (
-    typeof currentApproval !== 'string' && currentApproval.id === approval.id
+    currentApproval.kind === 'approved' &&
+    currentApproval.approval.id === approval.id
   );
 };
 
@@ -87,6 +88,7 @@ export const acknowledgeQueuedJob = async (
   const expected = queueMarkerFor(approval, kind);
   const current = await getIssue(deps.token, deps.repo, issueNumber);
   if (
+    !hasLabel(current.labels, approvalLabelFor(kind)) ||
     hasLabel(current.labels, inProgressLabelFor(kind)) ||
     hasLabel(current.labels, NEEDS_CLARIFICATION)
   ) {

package/src/poller-tick.ts

@@ -77,15 +77,17 @@ const runQueue = async (options: {
         // biome-ignore lint/performance/noAwaitInLoops: jobs are heavyweight Codex runs and the shared run budget is the concurrency cap.
         result = await runners.review(job.deps, job.item, allowCodex);
       } else {
-        let defaultBranch = defaultBranches.get(job.deps.repo);
-        if (defaultBranch === undefined) {
-          defaultBranch = await repoDefaultBranch(token, job.deps.repo);
-          defaultBranches.set(job.deps.repo, defaultBranch);
-        }
         result = await runners.fix(
           job.deps,
           job.item,
-          defaultBranch,
+          async () => {
+            let branch = defaultBranches.get(job.deps.repo);
+            if (branch === undefined) {
+              branch = await repoDefaultBranch(token, job.deps.repo);
+              defaultBranches.set(job.deps.repo, branch);
+            }
+            return branch;
+          },
           allowCodex,
         );
       }