@rmartz/pr-lifecycle 5.0.0 → 8.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 An **event-driven pull-request lifecycle reconciler** for GitHub Actions. On every
 relevant GitHub event it recomputes a PR's lifecycle state from the PR's current
-facts — draft status, Copilot review of the head, the latest verdict from a
+facts — draft status, pending bot review requests, the latest verdict from a
 trusted author and the head SHA it reviewed — converges the PR's labels to match,
 and **arms GitHub-native auto-merge when the PR reaches `approved`**. The
 consumer's branch ruleset (required checks) then decides when the merge lands.
@@ -48,8 +48,9 @@ pnpm run hygiene
 
 Versioned by [semantic-release](.releaserc.json): a push to `main` analyzes the
 Conventional-Commit history since the last `v*` tag and, when a release is
-warranted, publishes the package to GitHub Packages and creates the tag and
-GitHub Release.
+warranted, publishes the package to npmjs (public, via OIDC trusted publishing
+with provenance) and creates the tag and GitHub Release. Versions up to 5.0.0
+were published to GitHub Packages and stay there for existing pins.
 
 ## License
 

package/dist/bin/pr-lifecycle.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runCli
-} from "../chunk-RQEBRPZU.js";
+} from "../chunk-ENU2AAWK.js";
 
 // src/bin/pr-lifecycle.ts
 process.exitCode = await runCli(

package/dist/{chunk-RQEBRPZU.js → chunk-ENU2AAWK.js}

@@ -1,7 +1,66 @@
+// src/release-diff.ts
+var MANIFEST = ".release-please-manifest.json";
+var CHANGELOG = "CHANGELOG.md";
+var PACKAGE_JSON = "package.json";
+var RELEASE_STATUSES = /* @__PURE__ */ new Set(["added", "modified"]);
+var VERSION_LINE = /^[ \t]*"version"[ \t]*:[ \t]*"[^"\\\n]*"[,\t ]*$/;
+function basename(path) {
+  return path.slice(path.lastIndexOf("/") + 1);
+}
+function isVersionOnlyPatch(patch) {
+  let removed = 0;
+  let added = 0;
+  for (const line of patch.split("\n")) {
+    if (line.startsWith("@@") || line.startsWith("\\") || line.startsWith(" ") || line === "") {
+      continue;
+    }
+    const sign = line[0];
+    if (sign !== "+" && sign !== "-" || !VERSION_LINE.test(line.slice(1))) {
+      return false;
+    }
+    if (sign === "+") {
+      added += 1;
+    } else {
+      removed += 1;
+    }
+  }
+  return added === 1 && removed === 1;
+}
+function checkFile(file) {
+  if (!RELEASE_STATUSES.has(file.status)) {
+    return `${file.filename} was ${file.status}`;
+  }
+  const name = basename(file.filename);
+  if (file.filename === MANIFEST || name === CHANGELOG) {
+    return void 0;
+  }
+  if (name !== PACKAGE_JSON) {
+    return `${file.filename} is not a release file`;
+  }
+  if (file.patch === void 0) {
+    return `${file.filename} has no patch to verify`;
+  }
+  return isVersionOnlyPatch(file.patch) ? void 0 : `${file.filename} changes more than its version`;
+}
+function classifyReleaseDiff(files) {
+  if (files === void 0) {
+    return { release: false, reason: "changed files unavailable" };
+  }
+  if (files.length === 0) {
+    return { release: false, reason: "no changed files" };
+  }
+  for (const file of files) {
+    const problem = checkFile(file);
+    if (problem !== void 0) {
+      return { release: false, reason: problem };
+    }
+  }
+  return { release: true };
+}
+
 // src/bot-eligibility.ts
 var DEPENDABOT_LOGIN = "dependabot[bot]";
 var RELEASE_PLEASE_BRANCH_PREFIX = "release-please--";
-var RELEASE_PLEASE_PENDING_LABEL = "autorelease: pending";
 var DEPENDABOT_UPDATE_TYPES = [
   "version-update:semver-patch",
   "version-update:semver-minor",
@@ -72,8 +131,13 @@ function classifyBotPr(facts) {
   if (facts.authorLogin === DEPENDABOT_LOGIN) {
     return classifyDependabot(facts.commits);
   }
-  if (facts.headRef.startsWith(RELEASE_PLEASE_BRANCH_PREFIX) || facts.labels.includes(RELEASE_PLEASE_PENDING_LABEL)) {
-    return result(true, "release-please release PR \u2014 eligible", "release-please");
+  if (facts.headRef.startsWith(RELEASE_PLEASE_BRANCH_PREFIX)) {
+    const diff = classifyReleaseDiff(facts.changedFiles);
+    return diff.release ? result(true, "release-please release PR \u2014 eligible", "release-please") : result(
+      false,
+      `release-please branch, but not a pure release (${diff.reason}) \u2014 held for review`,
+      "release-please"
+    );
   }
   return result(false, "not a recognized bot PR");
 }
@@ -90,6 +154,7 @@ function parseList(value) {
 function parseReconcile(args) {
   const values = {};
   let armAutoMerge = false;
+  let autoUpdate = false;
   let skipCopilotReview = false;
   let dryRun = false;
   let json = false;
@@ -100,6 +165,9 @@ function parseReconcile(args) {
       case "--arm-auto-merge":
         armAutoMerge = true;
         break;
+      case "--auto-update":
+        autoUpdate = true;
+        break;
       case "--skip-copilot-review":
         skipCopilotReview = true;
         break;
@@ -151,6 +219,7 @@ function parseReconcile(args) {
     pr: Number(prArg),
     policy: {
       armAutoMerge,
+      autoUpdate,
       skipCopilotReview,
       ...trustedAuthors === void 0 ? {} : { trustedAuthors },
       ...holdChecks === void 0 ? {} : { holdChecks },
@@ -181,7 +250,7 @@ function parseArgs(argv) {
 // src/cli/output.ts
 var SCHEMA_VERSION = 1;
 function toReconcileJson(target, result2) {
-  const { plan, botEligibility, lineage, skippedAutoMerge } = result2;
+  const { plan, botEligibility, lineage, skippedAutoMerge, skippedUpdate } = result2;
   return {
     schemaVersion: SCHEMA_VERSION,
     repo: `${target.owner}/${target.repo}`,
@@ -199,7 +268,9 @@ function toReconcileJson(target, result2) {
     },
     carryOver: lineage === void 0 ? null : { cleanAncestors: lineage.cleanAncestors, stoppedBecause: lineage.stoppedBecause },
     // The CLI makes release actions unavailable only for a missing token.
-    autoMergeSkipped: skippedAutoMerge === void 0 ? null : { action: skippedAutoMerge, reason: "token-missing" }
+    autoMergeSkipped: skippedAutoMerge === void 0 ? null : { action: skippedAutoMerge, reason: "token-missing" },
+    update: plan.update,
+    updateSkipped: skippedUpdate === void 0 ? null : { action: skippedUpdate, reason: "token-missing" }
   };
 }
 function formatSummary(target, result2) {
@@ -208,7 +279,9 @@ function formatSummary(target, result2) {
     ...plan.addLabels.map((label) => `+${label}`),
     ...plan.removeLabels.map((label) => `-${label}`),
     ...plan.autoMerge === "none" ? [] : [`auto-merge ${plan.autoMerge}`],
-    ...result2.skippedAutoMerge === void 0 ? [] : [`auto-merge ${result2.skippedAutoMerge} skipped (no release token)`]
+    ...result2.skippedAutoMerge === void 0 ? [] : [`auto-merge ${result2.skippedAutoMerge} skipped (no release token)`],
+    ...plan.update === "none" ? [] : [`update ${plan.update}`],
+    ...result2.skippedUpdate === void 0 ? [] : [`update ${result2.skippedUpdate} skipped (no release token)`]
   ];
   const prefix = target.dryRun ? "[dry-run] " : "";
   const body = changes.length === 0 ? "no changes" : changes.join(", ");
@@ -239,38 +312,11 @@ var REVIEW_STATES = [
   "PENDING"
 ];
 var PR_STATUSES = ["closed", "merged", "open"];
+var BRANCH_UPDATERS = ["dependabot", "github"];
 
-// src/github/rest-payloads.ts
-function toReviewState(state) {
-  return REVIEW_STATES.find((known) => known === state) ?? "DISMISSED";
-}
-function toActorType(type) {
-  return type === "User" ? "User" : "Bot";
-}
-function toReviewData(review) {
-  return {
-    id: review.id,
-    login: review.user?.login,
-    type: review.user === null ? "User" : toActorType(review.user.type),
-    commitSha: review.commit_id,
-    state: toReviewState(review.state),
-    body: review.body ?? "",
-    submittedAt: review.submitted_at ?? void 0
-  };
-}
-
-// src/github/http-client.ts
+// src/github/http-transport.ts
 var PAGE_SIZE = 100;
-var ENABLE_AUTO_MERGE = `mutation($id: ID!, $head: GitObjectID!) {
-  enablePullRequestAutoMerge(input: { pullRequestId: $id, mergeMethod: SQUASH, expectedHeadOid: $head }) { clientMutationId }
-}`;
-var MERGE_PULL_REQUEST = `mutation($id: ID!, $head: GitObjectID!) {
-  mergePullRequest(input: { pullRequestId: $id, mergeMethod: SQUASH, expectedHeadOid: $head }) { clientMutationId }
-}`;
-var DISABLE_AUTO_MERGE = `mutation($id: ID!) {
-  disablePullRequestAutoMerge(input: { pullRequestId: $id }) { clientMutationId }
-}`;
-function createHttpClient(options) {
+function createTransport(options) {
   let apiUrl = options.apiUrl ?? "https://api.github.com";
   while (apiUrl.endsWith("/")) {
     apiUrl = apiUrl.slice(0, -1);
@@ -315,7 +361,79 @@ function createHttpClient(options) {
       throw new GitHubApiError(200, `GraphQL error: ${messages}`);
     }
   }
+  return { repoPath, request, paginate, graphql };
+}
+
+// src/github/http-checks.ts
+function createCheckMethods({ repoPath, request, paginate }) {
+  return {
+    async getRequiredStatusChecks(branch) {
+      const rules = await paginate(
+        `${repoPath}/rules/branches/${encodeURIComponent(branch)}`
+      );
+      const contexts = rules.filter((rule) => rule.type === "required_status_checks").flatMap((rule) => rule.parameters?.required_status_checks ?? []).map((check) => check.context);
+      return [...new Set(contexts)];
+    },
+    async listCheckRuns(sha) {
+      const runs = [];
+      for (let page = 1; ; page += 1) {
+        const batch = await request(
+          "GET",
+          `${repoPath}/commits/${sha}/check-runs?per_page=${PAGE_SIZE}&page=${page}`
+        );
+        runs.push(...batch.check_runs);
+        if (batch.check_runs.length < PAGE_SIZE) {
+          break;
+        }
+      }
+      return runs.map((run) => ({
+        name: run.name,
+        status: run.status,
+        conclusion: run.conclusion,
+        completedAt: run.completed_at
+      }));
+    },
+    async listCommitStatuses(sha) {
+      const combined = await request("GET", `${repoPath}/commits/${sha}/status`);
+      return combined.statuses.map((status) => ({ context: status.context, state: status.state }));
+    }
+  };
+}
+
+// src/github/rest-payloads.ts
+function toReviewState(state) {
+  return REVIEW_STATES.find((known) => known === state) ?? "DISMISSED";
+}
+function toActorType(type) {
+  return type === "User" ? "User" : "Bot";
+}
+function toReviewData(review) {
+  return {
+    id: review.id,
+    login: review.user?.login,
+    type: review.user === null ? "User" : toActorType(review.user.type),
+    commitSha: review.commit_id,
+    state: toReviewState(review.state),
+    body: review.body ?? "",
+    submittedAt: review.submitted_at ?? void 0
+  };
+}
+
+// src/github/http-client.ts
+var ENABLE_AUTO_MERGE = `mutation($id: ID!, $head: GitObjectID!) {
+  enablePullRequestAutoMerge(input: { pullRequestId: $id, mergeMethod: SQUASH, expectedHeadOid: $head }) { clientMutationId }
+}`;
+var MERGE_PULL_REQUEST = `mutation($id: ID!, $head: GitObjectID!) {
+  mergePullRequest(input: { pullRequestId: $id, mergeMethod: SQUASH, expectedHeadOid: $head }) { clientMutationId }
+}`;
+var DISABLE_AUTO_MERGE = `mutation($id: ID!) {
+  disablePullRequestAutoMerge(input: { pullRequestId: $id }) { clientMutationId }
+}`;
+function createHttpClient(options) {
+  const transport = createTransport(options);
+  const { repoPath, request, paginate, graphql } = transport;
   return {
+    ...createCheckMethods(transport),
     async getPullRequest(pr) {
       const pull = await request("GET", `${repoPath}/pulls/${pr}`);
       return {
@@ -324,6 +442,7 @@ function createHttpClient(options) {
         merged: pull.merged,
         draft: pull.draft === true,
         title: pull.title,
+        body: pull.body ?? "",
         headSha: pull.head.sha,
         labels: pull.labels.map((label) => label.name),
         autoMergeEnabled: pull.auto_merge !== null && pull.auto_merge !== void 0,
@@ -335,16 +454,12 @@ function createHttpClient(options) {
         // repo is treated as a fork, so it can never look like a trusted branch.
         isCrossRepository: pull.head.repo?.id !== pull.base.repo.id,
         mergeable: pull.mergeable ?? void 0,
-        mergeState: pull.mergeable_state
+        mergeState: pull.mergeable_state,
+        changedFileCount: pull.changed_files,
+        createdAt: pull.created_at,
+        requestedBotReviewers: (pull.requested_reviewers ?? []).filter((reviewer) => reviewer.type === "Bot").map((reviewer) => reviewer.login)
       };
     },
-    async getRequiredStatusChecks(branch) {
-      const rules = await paginate(
-        `${repoPath}/rules/branches/${encodeURIComponent(branch)}`
-      );
-      const contexts = rules.filter((rule) => rule.type === "required_status_checks").flatMap((rule) => rule.parameters?.required_status_checks ?? []).map((check) => check.context);
-      return [...new Set(contexts)];
-    },
     async getBranchHeadSha(branch) {
       const result2 = await request(
         "GET",
@@ -352,25 +467,6 @@ function createHttpClient(options) {
       );
       return result2.commit.sha;
     },
-    async listCheckRuns(sha) {
-      const runs = [];
-      for (let page = 1; ; page += 1) {
-        const batch = await request(
-          "GET",
-          `${repoPath}/commits/${sha}/check-runs?per_page=${PAGE_SIZE}&page=${page}`
-        );
-        runs.push(...batch.check_runs);
-        if (batch.check_runs.length < PAGE_SIZE) {
-          break;
-        }
-      }
-      return runs.map((run) => ({
-        name: run.name,
-        status: run.status,
-        conclusion: run.conclusion,
-        completedAt: run.completed_at
-      }));
-    },
     async getCommit(sha) {
       const commit = await request("GET", `${repoPath}/git/commits/${sha}`);
       return { treeSha: commit.tree.sha, parents: commit.parents.map((parent) => parent.sha) };
@@ -379,9 +475,13 @@ function createHttpClient(options) {
       const result2 = await request("GET", `${repoPath}/compare/${base}...${head}?per_page=1`);
       return { status: result2.status, mergeBaseSha: result2.merge_base_commit.sha };
     },
-    async listCommitStatuses(sha) {
-      const combined = await request("GET", `${repoPath}/commits/${sha}/status`);
-      return combined.statuses.map((status) => ({ context: status.context, state: status.state }));
+    async listPullRequestFiles(pr) {
+      const files = await paginate(`${repoPath}/pulls/${pr}/files`);
+      return files.map((file) => ({
+        filename: file.filename,
+        status: file.status,
+        patch: file.patch
+      }));
     },
     async listCommits(pr) {
       const commits = await paginate(`${repoPath}/pulls/${pr}/commits`);
@@ -414,6 +514,10 @@ function createHttpClient(options) {
     async removeLabel(pr, name) {
       await request("DELETE", `${repoPath}/issues/${pr}/labels/${encodeURIComponent(name)}`);
     },
+    async getLastReadyForReviewAt(pr) {
+      const events = await paginate(`${repoPath}/issues/${pr}/events`);
+      return events.filter((event) => event.event === "ready_for_review").at(-1)?.created_at;
+    },
     async listIssueComments(pr) {
       const comments = await paginate(`${repoPath}/issues/${pr}/comments`);
       return comments.map((comment) => comment.body ?? "");
@@ -427,6 +531,11 @@ function createHttpClient(options) {
     async mergePullRequest(pullRequestNodeId, expectedHeadOid) {
       await graphql(MERGE_PULL_REQUEST, { id: pullRequestNodeId, head: expectedHeadOid });
     },
+    async updateBranch(pr, expectedHeadSha) {
+      await request("PUT", `${repoPath}/pulls/${pr}/update-branch`, {
+        expected_head_sha: expectedHeadSha
+      });
+    },
     async disableAutoMerge(pullRequestNodeId) {
       await graphql(DISABLE_AUTO_MERGE, { id: pullRequestNodeId });
     }
@@ -518,8 +627,8 @@ function currentVerdict(facts, policy) {
 // src/state.ts
 var LIFECYCLE_STATES = [
   "approved",
+  "awaiting-bot-review",
   "awaiting-ci",
-  "awaiting-copilot",
   "blocked-base-red",
   "changes-requested",
   "ci-failing",
@@ -529,7 +638,6 @@ var LIFECYCLE_STATES = [
   "fix-required",
   "review-requested"
 ];
-var COPILOT_REVIEWER_LOGIN = "copilot-pull-request-reviewer[bot]";
 var WIP_PATTERN = /\[wip\]/i;
 function computeState(facts, policy) {
   if (facts.status !== "open") {
@@ -554,14 +662,10 @@ function computeState(facts, policy) {
   if (facts.ciStatus === "pending") {
     return "awaiting-ci";
   }
-  if (policy.skipCopilotReview === true) {
-    return "review-requested";
+  if (facts.pendingBotReviewers.length > 0 && policy.skipCopilotReview !== true) {
+    return "awaiting-bot-review";
   }
-  const reviewedCommits = countingCommits(facts);
-  const copilotReviewedHead = facts.reviews.some(
-    (review) => review.author.login === COPILOT_REVIEWER_LOGIN && reviewedCommits.has(review.commitSha)
-  );
-  return copilotReviewedHead ? "review-requested" : "awaiting-copilot";
+  return "review-requested";
 }
 
 // src/plan.ts
@@ -574,6 +678,7 @@ var LIFECYCLE_LABELS = [
   "review requested"
 ];
 var AUTO_MERGE_LABEL = "auto-merge enabled";
+var UPDATE_REQUIRED_LABEL = "update required";
 function lifecycleLabels(state) {
   switch (state) {
     case "approved":
@@ -588,18 +693,35 @@ function lifecycleLabels(state) {
       return ["fix required", "ci failing"];
     case "review-requested":
       return ["review requested"];
+    case "awaiting-bot-review":
     case "awaiting-ci":
-    case "awaiting-copilot":
     case "blocked-base-red":
     case "closed":
     case "draft":
       return [];
   }
 }
+function updateFor(updater, rebasePending) {
+  switch (updater) {
+    case "dependabot":
+      return rebasePending ? "none" : "dependabot-rebase";
+    case "github":
+      return "update-branch";
+  }
+}
+function planUpdate(facts, policy, state, autoMerge) {
+  if (policy.autoUpdate !== true || state !== "approved" || autoMerge === "merge") {
+    return "none";
+  }
+  if (!facts.labels.includes(UPDATE_REQUIRED_LABEL)) {
+    return "none";
+  }
+  return updateFor(facts.updater, facts.rebasePending);
+}
 function planReconcile(facts, policy) {
   const state = computeState(facts, policy);
   if (state === "closed") {
-    return { state, addLabels: [], removeLabels: [], autoMerge: "none" };
+    return { state, addLabels: [], removeLabels: [], autoMerge: "none", update: "none" };
   }
   const arming = policy.armAutoMerge === true;
   const shouldArm = arming && state === "approved";
@@ -624,20 +746,39 @@ function planReconcile(facts, policy) {
     state,
     addLabels: [...desired].filter((name) => !present.has(name)),
     removeLabels: owned.filter((name) => present.has(name) && !desired.has(name)),
-    autoMerge
+    autoMerge,
+    update: planUpdate(facts, policy, state, autoMerge)
   };
 }
-function withoutArming(plan) {
-  if (plan.autoMerge !== "arm" && plan.autoMerge !== "merge") {
-    return plan;
-  }
+function withoutReleaseActions(plan) {
+  const arming = plan.autoMerge === "arm" || plan.autoMerge === "merge";
   return {
     ...plan,
-    addLabels: plan.addLabels.filter((name) => name !== AUTO_MERGE_LABEL),
-    autoMerge: "none"
+    addLabels: arming ? plan.addLabels.filter((name) => name !== AUTO_MERGE_LABEL) : plan.addLabels,
+    autoMerge: arming ? "none" : plan.autoMerge,
+    update: "none"
   };
 }
 
+// src/github/dependabot-rebase.ts
+var DEPENDABOT_REBASE_COMMAND = "@dependabot rebase";
+var DEPENDABOT_REBASING_NOTICE = "Dependabot is rebasing this PR";
+function rebaseRequestMarker(headSha) {
+  return `<!-- pr-lifecycle:dependabot-rebase head=${headSha} -->`;
+}
+function buildRebaseRequestBody(headSha) {
+  return `${DEPENDABOT_REBASE_COMMAND}
+
+${rebaseRequestMarker(headSha)}`;
+}
+function isRebasePending(prBody, comments, headSha) {
+  if (prBody.includes(DEPENDABOT_REBASING_NOTICE)) {
+    return true;
+  }
+  const marker = rebaseRequestMarker(headSha);
+  return comments.some((comment) => comment.includes(marker));
+}
+
 // src/github/label-roster.ts
 var OWNED_LABEL_DEFINITIONS = {
   approved: {
@@ -734,6 +875,25 @@ async function executePlan(client, target, plan, release = client) {
   if (plan.autoMerge === "merge") {
     await release.mergePullRequest(target.nodeId, target.headSha);
   }
+  switch (plan.update) {
+    case "update-branch":
+      await updateBranch(release, target);
+      break;
+    case "dependabot-rebase":
+      await release.createIssueComment(target.pr, buildRebaseRequestBody(target.headSha));
+      break;
+    case "none":
+      break;
+  }
+}
+async function updateBranch(release, target) {
+  try {
+    await release.updateBranch(target.pr, target.headSha);
+  } catch (error) {
+    if (!isApiStatus(error, 422)) {
+      throw error;
+    }
+  }
 }
 
 // src/lineage/git.ts
@@ -858,7 +1018,7 @@ var MAX_CHAIN_STEPS = 20;
 function reviewedAncestors(input) {
   return new Set(
     input.reviews.filter((review) => review.commitSha !== input.headSha).filter(
-      (review) => review.login === COPILOT_REVIEWER_LOGIN || review.state === "APPROVED" || review.state === "CHANGES_REQUESTED" || review.body.includes("skill-meta")
+      (review) => review.state === "APPROVED" || review.state === "CHANGES_REQUESTED" || review.body.includes("skill-meta")
     ).map((review) => review.commitSha)
   );
 }
@@ -917,6 +1077,28 @@ async function gatherLineage(client, git, input) {
   }
 }
 
+// src/github/bot-facts.ts
+async function listAllChangedFiles(client, pr, pull) {
+  const files = await client.listPullRequestFiles(pr);
+  return files.length === pull.changedFileCount ? files : void 0;
+}
+async function gatherBotEligibility(client, pr, pull) {
+  const sameRepo = !pull.isCrossRepository;
+  const isDependabot = pull.authorLogin === DEPENDABOT_LOGIN;
+  const isReleaseBranch = !isDependabot && pull.headRef.startsWith(RELEASE_PLEASE_BRANCH_PREFIX);
+  const [commits, changedFiles] = await Promise.all([
+    sameRepo && isDependabot ? client.listCommits(pr) : [],
+    sameRepo && isReleaseBranch ? listAllChangedFiles(client, pr, pull) : void 0
+  ]);
+  return classifyBotPr({
+    authorLogin: pull.authorLogin ?? "ghost",
+    headRef: pull.headRef,
+    isCrossRepository: pull.isCrossRepository,
+    commits,
+    changedFiles
+  });
+}
+
 // src/ci.ts
 var DEFAULT_HOLD_CHECKS = ["pr-policy"];
 var DEFAULT_IGNORED_CHECKS = ["merge-safety"];
@@ -1010,16 +1192,6 @@ async function gatherCiFacts(client, pull, policy) {
 }
 
 // src/github/gather.ts
-async function gatherBotEligibility(client, pr, pull) {
-  const needsCommits = pull.authorLogin === DEPENDABOT_LOGIN && !pull.isCrossRepository;
-  return classifyBotPr({
-    authorLogin: pull.authorLogin ?? "ghost",
-    headRef: pull.headRef,
-    isCrossRepository: pull.isCrossRepository,
-    labels: pull.labels,
-    commits: needsCommits ? await client.listCommits(pr) : []
-  });
-}
 function isRepoPermission(value) {
   return REPO_PERMISSIONS.some((permission) => permission === value);
 }
@@ -1084,19 +1256,35 @@ async function gatherLineageFor(client, pull, reviews, options) {
     return { cleanAncestors: [], stoppedBecause: `verification failed: ${message}` };
   }
 }
+async function gatherRebasePending(client, pr, pull, updater, policy) {
+  if (updater !== "dependabot") {
+    return false;
+  }
+  if (pull.body.includes(DEPENDABOT_REBASING_NOTICE)) {
+    return true;
+  }
+  const couldUpdate = policy.autoUpdate === true && pull.state === "open" && pull.labels.includes(UPDATE_REQUIRED_LABEL);
+  if (!couldUpdate) {
+    return false;
+  }
+  return isRebasePending(pull.body, await client.listIssueComments(pr), pull.headSha);
+}
 var IMMEDIATE_MERGE_STATES = /* @__PURE__ */ new Set(["clean", "has_hooks", "unstable"]);
 async function gatherFacts(client, pr, policy = {}, options = {}) {
   const [pull, reviews] = await Promise.all([client.getPullRequest(pr), client.listReviews(pr)]);
-  const [permissions, botEligibility, ci, lineage] = await Promise.all([
+  const updater = pull.authorLogin === DEPENDABOT_LOGIN ? "dependabot" : "github";
+  const [permissions, botEligibility, ci, lineage, rebasePending] = await Promise.all([
     lookupPermissions(client, reviews),
     gatherBotEligibility(client, pr, pull),
     gatherCiFacts(client, pull, policy),
-    gatherLineageFor(client, pull, reviews, options)
+    gatherLineageFor(client, pull, reviews, options),
+    gatherRebasePending(client, pr, pull, updater, policy)
   ]);
   return {
     nodeId: pull.nodeId,
     botEligibility,
     lineage,
+    createdAt: pull.createdAt,
     facts: {
       status: pull.merged ? "merged" : pull.state,
       isDraft: pull.draft,
@@ -1110,28 +1298,75 @@ async function gatherFacts(client, pr, policy = {}, options = {}) {
       ciStatus: ci.ciStatus,
       baseCiFailing: ci.baseCiFailing,
       cleanAncestors: lineage?.cleanAncestors ?? [],
-      reviews: reviews.map((review) => toReviewFact(review, permissions))
+      updater,
+      rebasePending,
+      reviews: reviews.map((review) => toReviewFact(review, permissions)),
+      pendingBotReviewers: pull.requestedBotReviewers
     }
   };
 }
 
+// src/github/settle.ts
+var DEFAULT_SETTLE_MS = 3e4;
+function realSleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+async function settleDelay(client, pr, gathered, policy, settleMs, now) {
+  const { facts } = gathered;
+  if (policy.skipCopilotReview === true || computeState(facts, policy) !== "review-requested") {
+    return 0;
+  }
+  if (facts.labels.includes("review requested")) {
+    return 0;
+  }
+  const readyAt = await client.getLastReadyForReviewAt(pr);
+  const reviewableSince = Math.max(
+    Date.parse(gathered.createdAt),
+    readyAt === void 0 ? 0 : Date.parse(readyAt)
+  );
+  const elapsed = now - reviewableSince;
+  if (!Number.isFinite(elapsed)) {
+    return settleMs;
+  }
+  return Math.min(settleMs, Math.max(0, settleMs - elapsed));
+}
+function resolveSettle(options = {}) {
+  return {
+    settleMs: options.settleMs ?? DEFAULT_SETTLE_MS,
+    now: options.now ?? Date.now,
+    sleep: options.sleep ?? realSleep
+  };
+}
+
 // src/github/reconcile.ts
 var REFUSE_RELEASE = {
+  createIssueComment: () => Promise.reject(new Error("rebase requests need a release token")),
   enableAutoMerge: () => Promise.reject(new Error("arming needs a release token")),
-  mergePullRequest: () => Promise.reject(new Error("merging needs a release token"))
+  mergePullRequest: () => Promise.reject(new Error("merging needs a release token")),
+  updateBranch: () => Promise.reject(new Error("updating needs a release token"))
 };
 async function reconcilePullRequest(client, pr, policy, options = {}) {
-  const { facts, nodeId, botEligibility, lineage } = await gatherFacts(client, pr, policy, options);
+  const settle = resolveSettle(options.settle);
+  let gathered = await gatherFacts(client, pr, policy, options);
+  const settledMs = await settleDelay(client, pr, gathered, policy, settle.settleMs, settle.now());
+  if (settledMs > 0) {
+    await settle.sleep(settledMs);
+    gathered = await gatherFacts(client, pr, policy, options);
+  }
+  const { facts, nodeId, botEligibility, lineage } = gathered;
   const planned = planReconcile(facts, policy);
   const unavailable = options.release === "unavailable";
-  const plan = unavailable ? withoutArming(planned) : planned;
+  const plan = unavailable ? withoutReleaseActions(planned) : planned;
   if (options.dryRun !== true) {
     const release = options.release === "unavailable" ? REFUSE_RELEASE : options.release ?? client;
     await executePlan(client, { pr, nodeId, headSha: facts.headSha }, plan, release);
   }
   const wanted = planned.autoMerge;
   const skippedAutoMerge = unavailable && (wanted === "arm" || wanted === "merge") ? wanted : void 0;
-  return { plan, botEligibility, lineage, skippedAutoMerge };
+  const skippedUpdate = unavailable && planned.update !== "none" ? planned.update : void 0;
+  return { plan, botEligibility, lineage, skippedAutoMerge, skippedUpdate, settledMs };
 }
 
 // src/github/token-advisory.ts
@@ -1168,8 +1403,10 @@ reconcile options:
   --repo <owner/repo>       Repository (required)
   --pr <number>             Pull request number (required)
   --arm-auto-merge          Arm/disarm native auto-merge from the state
+  --auto-update             Update approved PRs merge-safety flags 'update required'
+                            (Dependabot PRs are asked to rebase, never updated)
   --trusted-authors <a,b>   Only these logins (with write access) may cast verdicts
-  --skip-copilot-review     Don't wait for a Copilot review
+  --skip-copilot-review     Don't wait for requested bot reviewers (deprecated)
   --hold-checks <a,b>       Required checks whose pending is a hold (default: pr-policy)
   --ignore-checks <a,b>     Required checks CI never counts (default: merge-safety)
   --dry-run                 Compute the plan without writing anything
@@ -1179,8 +1416,8 @@ reconcile options:
 Environment:
   GITHUB_TOKEN              Token for reads and writes (required)
   PR_LIFECYCLE_TOKEN
-                            Real-actor token for arming and merging; without it,
-                            --arm-auto-merge keeps labels but skips arm/merge
+                            Real-actor token for arming, merging, and updating;
+                            without it, labels are kept but those are skipped
   GITHUB_API_URL            API base URL (GitHub Enterprise Server)`;
 async function runCli(argv, io, deps) {
   const args = parseArgs(argv);
@@ -1216,8 +1453,8 @@ async function runCli(argv, io, deps) {
     const result2 = await reconcilePullRequest(client, args.pr, args.policy, {
       dryRun: args.dryRun,
       lineage: { git: deps.git ?? createGitRunner(), token },
-      // Only arming and merging use the release token (never reads). Without one
-      // they are skipped, not done with GITHUB_TOKEN; see docs/cli.md.
+      // Only arming, merging, and updating use the release token (never reads).
+      // Without one they are skipped, not done with GITHUB_TOKEN; see docs/cli.md.
       release: hasReleaseToken ? clientFor(releaseToken) : "unavailable"
     });
     if (result2.skippedAutoMerge !== void 0) {
@@ -1228,6 +1465,11 @@ async function runCli(argv, io, deps) {
         await adviseMissingToken(client, args.pr, result2.skippedAutoMerge, io);
       }
     }
+    if (result2.skippedUpdate !== void 0) {
+      io.stderr(
+        `warning: ${args.owner}/${args.repo}#${args.pr} needs an update, but ${result2.skippedUpdate} was skipped: PR_LIFECYCLE_TOKEN is not set`
+      );
+    }
     if (args.json) {
       io.stdout(JSON.stringify(toReconcileJson(target, result2)));
     } else {
@@ -1250,9 +1492,10 @@ async function adviseMissingToken(client, pr, skipped, io) {
 }
 
 export {
+  isVersionOnlyPatch,
+  classifyReleaseDiff,
   DEPENDABOT_LOGIN,
   RELEASE_PLEASE_BRANCH_PREFIX,
-  RELEASE_PLEASE_PENDING_LABEL,
   DEPENDABOT_UPDATE_TYPES,
   parseDependabotUpdateType,
   classifyBotPr,
@@ -1266,18 +1509,24 @@ export {
   ACTOR_TYPES,
   REVIEW_STATES,
   PR_STATUSES,
+  BRANCH_UPDATERS,
   createHttpClient,
   VERDICTS,
   parseVerdict,
   isTrustedAuthor,
   currentVerdict,
   LIFECYCLE_STATES,
-  COPILOT_REVIEWER_LOGIN,
   computeState,
   LIFECYCLE_LABELS,
   AUTO_MERGE_LABEL,
+  UPDATE_REQUIRED_LABEL,
   planReconcile,
-  withoutArming,
+  withoutReleaseActions,
+  DEPENDABOT_REBASE_COMMAND,
+  DEPENDABOT_REBASING_NOTICE,
+  rebaseRequestMarker,
+  buildRebaseRequestBody,
+  isRebasePending,
   OWNED_LABEL_DEFINITIONS,
   executePlan,
   createGitRunner,
@@ -1286,6 +1535,7 @@ export {
   MAX_CHAIN_STEPS,
   gatherLineage,
   gatherFacts,
+  DEFAULT_SETTLE_MS,
   reconcilePullRequest,
   TOKEN_ADVISORY_MARKER,
   RELEASE_TOKEN_DOCS_URL,

package/dist/index.d.ts

@@ -1,14 +1,53 @@
+/**
+ * Is a release-please PR's diff a pure release: only the files release-please
+ * writes, with `package.json` changed in its `version` line and nowhere else?
+ * The branch name alone can't say (any write user can push a `release-please--`
+ * branch with arbitrary code), and release-please commits as whoever owns its
+ * token, so its commit authors can't either. See docs/bot-eligibility.md.
+ *
+ * FAIL-SAFE: a file outside the release set, a status other than added or
+ * modified, a missing patch, or any doubt about a `package.json` line means the
+ * diff is not a release.
+ */
+/** One changed file, as the PR files API reports it. */
+interface ChangedFile {
+    /** Repository-relative path. */
+    filename: string;
+    /** `added`, `modified`, `removed`, `renamed`, `copied`, `changed`, or `unchanged`. */
+    status: string;
+    /** The unified-diff hunk text; undefined when GitHub omits it (e.g. a large diff). */
+    patch: string | undefined;
+}
+type ReleaseDiffVerdict = {
+    release: true;
+} | {
+    release: false;
+    reason: string;
+};
+/**
+ * Whether a `package.json` patch changes exactly one line, its `version`: one
+ * removed and one added line, both a bare `"version"` member. Context lines,
+ * hunk headers, and the no-newline marker are ignored.
+ */
+declare function isVersionOnlyPatch(patch: string): boolean;
+/**
+ * The verdict over a PR's changed files. `undefined` means the list couldn't be
+ * read in full (truncated or not fetched), which is never a release.
+ */
+declare function classifyReleaseDiff(files: readonly ChangedFile[] | undefined): ReleaseDiffVerdict;
+
 /**
  * Bot-PR eligibility: is this a bot PR trusted enough to count as `approved`
  * without a review (state priority 7 in docs/reconciler-design.md)? Ported from
- * @rmartz/bot-automerge's classifier, with one deliberate tightening: the head
- * branch must live in the base repository. See docs/bot-eligibility.md.
+ * @rmartz/bot-automerge's classifier, with deliberate tightenings: the head
+ * branch must live in the base repository, and a release-please PR is recognized
+ * by its branch and a release-only diff, never by a label. See
+ * docs/bot-eligibility.md.
  *
  * FAIL-SAFE: every uncertain or unrecognized case is not eligible.
  */
 declare const DEPENDABOT_LOGIN = "dependabot[bot]";
 declare const RELEASE_PLEASE_BRANCH_PREFIX = "release-please--";
-declare const RELEASE_PLEASE_PENDING_LABEL = "autorelease: pending";
 /** Dependabot's semver update types, lowest to highest risk. */
 declare const DEPENDABOT_UPDATE_TYPES: readonly ["version-update:semver-patch", "version-update:semver-minor", "version-update:semver-major"];
 type DependabotUpdateType = (typeof DEPENDABOT_UPDATE_TYPES)[number];
@@ -23,9 +62,13 @@ interface BotPrFacts {
     headRef: string;
     /** True when the head branch lives in a fork, not the base repository. */
     isCrossRepository: boolean;
-    labels: readonly string[];
     /** The PR's commits; only consulted for Dependabot PRs. */
     commits: readonly BotPrCommit[];
+    /**
+     * The PR's changed files; only consulted for release-please PRs. Undefined when
+     * not fetched or not read in full, which is never eligible.
+     */
+    changedFiles: readonly ChangedFile[] | undefined;
 }
 interface BotEligibility {
     eligible: boolean;
@@ -73,6 +116,12 @@ type ActorType = (typeof ACTOR_TYPES)[number];
 declare const REVIEW_STATES: readonly ["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED", "PENDING"];
 type ReviewState = (typeof REVIEW_STATES)[number];
 declare const PR_STATUSES: readonly ["closed", "merged", "open"];
+/**
+ * Who brings a PR's branch up to date with its base. Dependabot owns its branches
+ * and rebases them itself when asked; anything else uses GitHub's update-branch.
+ */
+declare const BRANCH_UPDATERS: readonly ["dependabot", "github"];
+type BranchUpdater = (typeof BRANCH_UPDATERS)[number];
 type PullRequestStatus = (typeof PR_STATUSES)[number];
 interface ReviewAuthor {
     login: string;
@@ -120,7 +169,21 @@ interface PullRequestFacts {
      * docs/reconciler-design.md §Approval carry-over). Verified at the edge.
      */
     cleanAncestors: readonly string[];
+    /** Who updates the branch (see `BranchUpdater`). */
+    updater: BranchUpdater;
+    /**
+     * For a Dependabot PR: a rebase is running (the PR body says so) or was already
+     * requested for this head, so asking again would only add noise. A request is
+     * made at most once per head, whether Dependabot then rebases or replies with an
+     * error. Always `false` for other PRs.
+     */
+    rebasePending: boolean;
     reviews: readonly ReviewFact[];
+    /**
+     * Logins of the bots (e.g. Copilot) whose review is requested and not yet
+     * submitted. Users and teams are left out: the lifecycle never waits on people.
+     */
+    pendingBotReviewers: readonly string[];
 }
 interface ReconcilePolicy {
     /**
@@ -132,8 +195,16 @@ interface ReconcilePolicy {
     /** Arm/disarm native auto-merge from the lifecycle state. Off by default. */
     armAutoMerge?: boolean;
     /**
-     * Don't wait for a Copilot review before `review-requested`, for repos without
-     * Copilot code review (where the wait would never end). Off by default.
+     * Bring an approved PR up to date when merge-safety labels it `update required`:
+     * `update-branch` for most PRs, a `@dependabot rebase` request for Dependabot's.
+     * Off by default.
+     */
+    autoUpdate?: boolean;
+    /**
+     * Don't wait for requested bot reviewers (e.g. Copilot) before
+     * `review-requested`. Rarely needed: a bot that won't review is never requested.
+     * Off by default. Deprecated: the wait now ends on its own; kept so existing
+     * callers keep working.
      */
     skipCopilotReview?: boolean;
     /**
@@ -159,6 +230,8 @@ interface PullRequestData {
     merged: boolean;
     draft: boolean;
     title: string;
+    /** The PR description (empty when none); Dependabot reports a running rebase here. */
+    body: string;
     headSha: string;
     labels: string[];
     autoMergeEnabled: boolean;
@@ -175,6 +248,12 @@ interface PullRequestData {
     mergeable: boolean | undefined;
     /** GitHub's merge state (`clean`, `blocked`, `behind`, …); undefined while computing. */
     mergeState: string | undefined;
+    /** How many files the PR changes (`changed_files`), to tell a full file list from a truncated one. */
+    changedFileCount: number;
+    /** ISO-8601 time the PR was opened. */
+    createdAt: string;
+    /** Logins of requested reviewers that are bots (users and teams left out). */
+    requestedBotReviewers: string[];
 }
 /** A check-run on a commit (the latest run per name). */
 interface CheckRunData {
@@ -231,6 +310,8 @@ interface GitHubClient {
     getPullRequest(pr: number): Promise<PullRequestData>;
     listReviews(pr: number): Promise<ReviewData[]>;
     listCommits(pr: number): Promise<CommitData[]>;
+    /** The PR's changed files. GitHub lists at most 3,000, so compare with `changedFileCount`. */
+    listPullRequestFiles(pr: number): Promise<ChangedFile[]>;
     /** The contexts the branch's rulesets require (empty when none are configured). */
     getRequiredStatusChecks(branch: string): Promise<string[]>;
     getBranchHeadSha(branch: string): Promise<string>;
@@ -246,6 +327,8 @@ interface GitHubClient {
     addLabels(pr: number, names: readonly string[]): Promise<void>;
     /** Throws a GitHubApiError with status 404 when the label is not on the PR. */
     removeLabel(pr: number, name: string): Promise<void>;
+    /** When the PR was last marked ready for review (ISO-8601), if ever. */
+    getLastReadyForReviewAt(pr: number): Promise<string | undefined>;
     /** Bodies of the PR's conversation comments, oldest first. */
     listIssueComments(pr: number): Promise<string[]>;
     createIssueComment(pr: number, body: string): Promise<void>;
@@ -257,13 +340,19 @@ interface GitHubClient {
     /** Squash-merge now, bound to `expectedHeadOid` like `enableAutoMerge`. */
     mergePullRequest(pullRequestNodeId: string, expectedHeadOid: string): Promise<void>;
     disableAutoMerge(pullRequestNodeId: string): Promise<void>;
+    /**
+     * Merge the base into the PR branch, bound to `expectedHeadSha`. Throws a
+     * GitHubApiError with status 422 when the head moved or there is nothing to merge.
+     */
+    updateBranch(pr: number, expectedHeadSha: string): Promise<void>;
 }
 /**
- * The writes that must come from a real actor, so the merge they cause re-triggers
- * `on: push` workflows (a `GITHUB_TOKEN` merge triggers nothing). Kept to these two
- * calls so the release token is never used for anything else, reads included.
+ * The writes that must come from a real actor: a merge or branch update made with
+ * `GITHUB_TOKEN` triggers no workflows (so no release, and no CI on the new head),
+ * and Dependabot only takes commands from people. Kept to these calls so the
+ * release token is never used for anything else, reads included.
  */
-type ReleaseActions = Pick<GitHubClient, 'enableAutoMerge' | 'mergePullRequest'>;
+type ReleaseActions = Pick<GitHubClient, 'createIssueComment' | 'enableAutoMerge' | 'mergePullRequest' | 'updateBranch'>;
 declare class GitHubApiError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
@@ -271,10 +360,9 @@ declare class GitHubApiError extends Error {
 declare function isApiStatus(error: unknown, status: number): boolean;
 
 /**
- * The real GitHubClient: REST for reads and labels, GraphQL for the auto-merge
- * mutations (REST has no endpoint for them). Deliberately thin — it maps requests
- * and responses and throws GitHubApiError on failure; every decision lives in
- * gather.ts / execute.ts. `fetch` is injectable so tests use a fake transport.
+ * The HTTP transport under the real GitHubClient: authenticated REST requests,
+ * pagination, and GraphQL, each throwing GitHubApiError on failure. Split out of
+ * http-client.ts so the client modules only map requests and responses.
  */
 interface HttpClientOptions {
     token: string;
@@ -284,6 +372,7 @@ interface HttpClientOptions {
     apiUrl?: string;
     fetch?: typeof fetch;
 }
+
 declare function createHttpClient(options: HttpClientOptions): GitHubClient;
 
 /**
@@ -324,7 +413,7 @@ interface CliDeps {
     /** Runs git for approval carry-over; tests inject one. Defaults to the real binary. */
     git?: GitRunner;
 }
-declare const USAGE = "Usage: ai-pr-lifecycle <command> [options]\n\nCommands:\n  reconcile   Recompute a PR's lifecycle state and converge its labels\n  help        Show this message\n\nreconcile options:\n  --repo <owner/repo>       Repository (required)\n  --pr <number>             Pull request number (required)\n  --arm-auto-merge          Arm/disarm native auto-merge from the state\n  --trusted-authors <a,b>   Only these logins (with write access) may cast verdicts\n  --skip-copilot-review     Don't wait for a Copilot review\n  --hold-checks <a,b>       Required checks whose pending is a hold (default: pr-policy)\n  --ignore-checks <a,b>     Required checks CI never counts (default: merge-safety)\n  --dry-run                 Compute the plan without writing anything\n  --json                    Print one JSON object (schemaVersion 1) on stdout\n  --no-token-advisory       Don't comment on the PR when arming lacks a release token\n\nEnvironment:\n  GITHUB_TOKEN              Token for reads and writes (required)\n  PR_LIFECYCLE_TOKEN\n                            Real-actor token for arming and merging; without it,\n                            --arm-auto-merge keeps labels but skips arm/merge\n  GITHUB_API_URL            API base URL (GitHub Enterprise Server)";
+declare const USAGE = "Usage: ai-pr-lifecycle <command> [options]\n\nCommands:\n  reconcile   Recompute a PR's lifecycle state and converge its labels\n  help        Show this message\n\nreconcile options:\n  --repo <owner/repo>       Repository (required)\n  --pr <number>             Pull request number (required)\n  --arm-auto-merge          Arm/disarm native auto-merge from the state\n  --auto-update             Update approved PRs merge-safety flags 'update required'\n                            (Dependabot PRs are asked to rebase, never updated)\n  --trusted-authors <a,b>   Only these logins (with write access) may cast verdicts\n  --skip-copilot-review     Don't wait for requested bot reviewers (deprecated)\n  --hold-checks <a,b>       Required checks whose pending is a hold (default: pr-policy)\n  --ignore-checks <a,b>     Required checks CI never counts (default: merge-safety)\n  --dry-run                 Compute the plan without writing anything\n  --json                    Print one JSON object (schemaVersion 1) on stdout\n  --no-token-advisory       Don't comment on the PR when arming lacks a release token\n\nEnvironment:\n  GITHUB_TOKEN              Token for reads and writes (required)\n  PR_LIFECYCLE_TOKEN\n                            Real-actor token for arming, merging, and updating;\n                            without it, labels are kept but those are skipped\n  GITHUB_API_URL            API base URL (GitHub Enterprise Server)";
 declare function runCli(argv: readonly string[], io: CliIo, deps: CliDeps): Promise<number>;
 
 /**
@@ -355,9 +444,8 @@ declare function parseArgs(argv: readonly string[]): ParsedArgs;
  * Lifecycle state, computed from facts in a fixed priority order. See
  * docs/reconciler-design.md §State.
  */
-declare const LIFECYCLE_STATES: readonly ["approved", "awaiting-ci", "awaiting-copilot", "blocked-base-red", "changes-requested", "ci-failing", "closed", "draft", "escalation-needed", "fix-required", "review-requested"];
+declare const LIFECYCLE_STATES: readonly ["approved", "awaiting-bot-review", "awaiting-ci", "blocked-base-red", "changes-requested", "ci-failing", "closed", "draft", "escalation-needed", "fix-required", "review-requested"];
 type LifecycleState = (typeof LIFECYCLE_STATES)[number];
-declare const COPILOT_REVIEWER_LOGIN = "copilot-pull-request-reviewer[bot]";
 declare function computeState(facts: PullRequestFacts, policy: ReconcilePolicy): LifecycleState;
 
 /**
@@ -369,24 +457,33 @@ declare function computeState(facts: PullRequestFacts, policy: ReconcilePolicy):
 declare const LIFECYCLE_LABELS: readonly ["approved", "changes requested", "escalation needed", "fix required", "ci failing", "review requested"];
 type LifecycleLabel = (typeof LIFECYCLE_LABELS)[number];
 declare const AUTO_MERGE_LABEL = "auto-merge enabled";
+/** merge-safety's label for a PR whose base moved in a way that matters. Read, never written. */
+declare const UPDATE_REQUIRED_LABEL = "update required";
 /**
  * `merge` is arming's twin for a PR GitHub would already merge: auto-merge can't
  * be armed then, so it is merged directly (see `immediatelyMergeable`).
  */
 type AutoMergeAction = 'arm' | 'disarm' | 'merge' | 'none';
+/**
+ * How an approved PR flagged `update required` is brought up to date. A Dependabot
+ * PR is never updated directly — a foreign commit on its branch permanently breaks
+ * its own rebasing — so it is only ever asked to rebase itself.
+ */
+type UpdateAction = 'dependabot-rebase' | 'none' | 'update-branch';
 interface ReconcilePlan {
     state: LifecycleState;
     addLabels: string[];
     removeLabels: string[];
     autoMerge: AutoMergeAction;
+    update: UpdateAction;
 }
 declare function planReconcile(facts: PullRequestFacts, policy: ReconcilePolicy): ReconcilePlan;
 /**
- * The plan with arming and merging taken out, for when no real-actor token is
- * available to perform them (docs/cli.md §Release token). Disarming stays: it is
- * safety, and any token may do it. Pure, like the planner.
+ * The plan with arming, merging, and updating taken out, for when no real-actor
+ * token is available to perform them (docs/cli.md §Release token). Disarming
+ * stays: it is safety, and any token may do it. Pure, like the planner.
  */
-declare function withoutArming(plan: ReconcilePlan): ReconcilePlan;
+declare function withoutReleaseActions(plan: ReconcilePlan): ReconcilePlan;
 
 interface MergeStep {
     /** The merge base of the two parents. */
@@ -451,6 +548,8 @@ interface GatheredPullRequest {
     botEligibility: BotEligibility;
     /** How far approval carry-over verified, for reporting (absent when off). */
     lineage: Lineage | undefined;
+    /** When the PR was opened (ISO-8601), for the settle wait (settle.ts). */
+    createdAt: string;
 }
 interface GatherOptions {
     /**
@@ -465,13 +564,34 @@ interface GatherOptions {
 }
 declare function gatherFacts(client: GitHubClient, pr: number, policy?: ReconcilePolicy, options?: GatherOptions): Promise<GatheredPullRequest>;
 
+/**
+ * The settle wait: a PR that just became reviewable isn't moved to
+ * `review-requested` until bot reviewers have had time to be requested. Copilot's
+ * auto-review request lands a few seconds after the PR opens (observed: up to 5s),
+ * so a run that reads the PR sooner would see no request and skip the wait. The
+ * wait happens inside the run, never as "stay put and wait for the next event":
+ * when no bot is coming, no further event may ever fire. See
+ * docs/reconciler-design.md §Waiting for bot reviewers.
+ */
+/** Long enough to cover the observed request delay several times over. */
+declare const DEFAULT_SETTLE_MS = 30000;
+interface SettleOptions {
+    /** How long after a PR becomes reviewable to wait for bot requests. */
+    settleMs?: number;
+    /** Clock and timer, injectable for tests. */
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+
 interface ReconcileOptions extends GatherOptions {
+    /** The settle wait for a PR that just became reviewable (settle.ts). */
+    settle?: SettleOptions;
     /** Compute and return the plan without writing anything. */
     dryRun?: boolean;
     /**
-     * Who arms and merges. Defaults to `client`, right when its token is a real
-     * actor. `'unavailable'` (no real-actor token configured) skips arming and
-     * merging rather than doing them with a token whose merge triggers no workflows.
+     * Who arms, merges, and updates. Defaults to `client`, right when its token is a
+     * real actor. `'unavailable'` (no real-actor token configured) skips them rather
+     * than doing them with a token whose pushes and merges trigger no workflows.
      */
     release?: ReleaseActions | 'unavailable';
 }
@@ -483,10 +603,14 @@ interface ReconcileResult {
     lineage: Lineage | undefined;
     /** The arm or merge the plan wanted but skipped because `release` was unavailable. */
     skippedAutoMerge: 'arm' | 'merge' | undefined;
+    /** The branch update the plan wanted but skipped because `release` was unavailable. */
+    skippedUpdate: Exclude<UpdateAction, 'none'> | undefined;
+    /** How long the run waited for bot review requests before gathering again (ms). */
+    settledMs: number;
 }
 /**
- * One full reconcile pass for a PR: gather its facts, plan, and (unless dry-run)
- * execute. Returns the plan, the bot-eligibility verdict, and the carry-over
+ * One full reconcile pass for a PR: gather its facts (waiting to settle first if it
+ * just became reviewable), plan, and (unless dry-run) execute. Returns the plan, the bot-eligibility verdict, and the carry-over
  * result so callers can report what changed and why.
  */
 declare function reconcilePullRequest(client: GitHubClient, pr: number, policy: ReconcilePolicy, options?: ReconcileOptions): Promise<ReconcileResult>;
@@ -530,16 +654,45 @@ interface ReconcileJson {
         action: 'arm' | 'merge';
         reason: 'token-missing';
     } | null;
+    /** The branch update performed: `none`, `update-branch`, or `dependabot-rebase`. */
+    update: string;
+    /** A branch update the plan wanted but skipped; `null` when nothing was skipped. */
+    updateSkipped: {
+        action: 'dependabot-rebase' | 'update-branch';
+        reason: 'token-missing';
+    } | null;
 }
 declare function toReconcileJson(target: ReconcileTarget, result: ReconcileResult): ReconcileJson;
 /** One human-readable line, e.g. `rmartz/x#7 → approved: +approved, auto-merge arm`. */
 declare function formatSummary(target: ReconcileTarget, result: ReconcileResult): string;
 
+/**
+ * Asking Dependabot to rebase its own PR — the only way a Dependabot PR is ever
+ * brought up to date. The request is made at most once per head: after asking,
+ * the reconciler waits for Dependabot to either rebase (a new head, which may be
+ * asked again) or reply with an error (the head is unchanged, so it stays quiet
+ * and leaves the PR to a person). See docs/github-edge-layer.md §Auto-update.
+ */
+declare const DEPENDABOT_REBASE_COMMAND = "@dependabot rebase";
+/** Dependabot puts this in the PR body while a rebase runs, and removes it after. */
+declare const DEPENDABOT_REBASING_NOTICE = "Dependabot is rebasing this PR";
+/** Hidden marker recording which head a request was made for. */
+declare function rebaseRequestMarker(headSha: string): string;
+/** The command on its own first line, as Dependabot parses it, then the marker. */
+declare function buildRebaseRequestBody(headSha: string): string;
+/**
+ * Whether asking again would only add noise: a rebase is already running, or one
+ * was already requested for this head. A forged marker can only suppress a
+ * request, never cause one, so the comment author doesn't matter.
+ */
+declare function isRebasePending(prBody: string, comments: readonly string[], headSha: string): boolean;
+
 /**
  * Executes a reconcile plan against GitHub. Writes happen in a fail-safe order —
- * disarm, remove labels, add labels, arm — so a run that dies midway never leaves
- * auto-merge armed on a PR that is not approved. Arming and merging go through
- * `release` (a real-actor token) and are bound to the planned head. See
+ * disarm, remove labels, add labels, arm, update — so a run that dies midway never
+ * leaves auto-merge armed on a PR that is not approved, and an update (which moves
+ * the head) comes last. Arming, merging, and updating go through `release` (a
+ * real-actor token) and are bound to the planned head. See
  * docs/github-edge-layer.md.
  */
 interface PlanTarget {
@@ -591,6 +744,7 @@ interface ParsedVerdict {
 declare function parseVerdict(review: ReviewFact): ParsedVerdict | undefined;
 /** Whether an author may cast a counting verdict under the policy. */
 declare function isTrustedAuthor(author: ReviewAuthor, policy: ReconcilePolicy): boolean;
+/** The latest verdict that counts for the PR's current head, if any. */
 declare function currentVerdict(facts: PullRequestFacts, policy: ReconcilePolicy): Verdict | undefined;
 
-export { ACTOR_TYPES, AUTO_MERGE_LABEL, type ActorType, type AutoMergeAction, type BotEligibility, type BotPrCommit, type BotPrFacts, type BotPrType, COPILOT_REVIEWER_LOGIN, type CliDeps, type CliIo, type CollaboratorPermission, type CommitData, DEPENDABOT_LOGIN, DEPENDABOT_UPDATE_TYPES, type DependabotUpdateType, type GatherOptions, type GatheredPullRequest, GitHubApiError, type GitHubClient, type GitResult, type GitRunner, type HttpClientOptions, LIFECYCLE_LABELS, LIFECYCLE_STATES, type LabelDefinition, type LifecycleLabel, type LifecycleState, type Lineage, type LineageInput, MAX_CHAIN_STEPS, type MergeStep, type MergeVerifier, OWNED_LABEL_DEFINITIONS, PR_STATUSES, type ParsedArgs, type ParsedVerdict, type PlanTarget, type PullRequestData, type PullRequestFacts, type PullRequestStatus, RELEASE_PLEASE_BRANCH_PREFIX, RELEASE_PLEASE_PENDING_LABEL, RELEASE_TOKEN_DOCS_URL, REPO_PERMISSIONS, REVIEW_STATES, type ReconcileArgs, type ReconcileJson, type ReconcileOptions, type ReconcilePlan, type ReconcilePolicy, type ReconcileResult, type ReconcileTarget, type ReleaseActions, type RepoPermission, type RepoSource, type ReviewAuthor, type ReviewData, type ReviewFact, type ReviewState, SCHEMA_VERSION, TOKEN_ADVISORY_MARKER, USAGE, VERDICTS, type Verdict, buildTokenAdvisoryBody, classifyBotPr, computeState, createGitRunner, createHttpClient, createMergeVerifier, currentVerdict, executePlan, formatSummary, gatherFacts, gatherLineage, isApiStatus, isTrustedAuthor, parseArgs, parseDependabotUpdateType, parseGitVersion, parseVerdict, planReconcile, postTokenAdvisory, reconcilePullRequest, runCli, toReconcileJson, withoutArming };
+export { ACTOR_TYPES, AUTO_MERGE_LABEL, type ActorType, type AutoMergeAction, BRANCH_UPDATERS, type BotEligibility, type BotPrCommit, type BotPrFacts, type BotPrType, type BranchUpdater, type ChangedFile, type CliDeps, type CliIo, type CollaboratorPermission, type CommitData, DEFAULT_SETTLE_MS, DEPENDABOT_LOGIN, DEPENDABOT_REBASE_COMMAND, DEPENDABOT_REBASING_NOTICE, DEPENDABOT_UPDATE_TYPES, type DependabotUpdateType, type GatherOptions, type GatheredPullRequest, GitHubApiError, type GitHubClient, type GitResult, type GitRunner, type HttpClientOptions, LIFECYCLE_LABELS, LIFECYCLE_STATES, type LabelDefinition, type LifecycleLabel, type LifecycleState, type Lineage, type LineageInput, MAX_CHAIN_STEPS, type MergeStep, type MergeVerifier, OWNED_LABEL_DEFINITIONS, PR_STATUSES, type ParsedArgs, type ParsedVerdict, type PlanTarget, type PullRequestData, type PullRequestFacts, type PullRequestStatus, RELEASE_PLEASE_BRANCH_PREFIX, RELEASE_TOKEN_DOCS_URL, REPO_PERMISSIONS, REVIEW_STATES, type ReconcileArgs, type ReconcileJson, type ReconcileOptions, type ReconcilePlan, type ReconcilePolicy, type ReconcileResult, type ReconcileTarget, type ReleaseActions, type ReleaseDiffVerdict, type RepoPermission, type RepoSource, type ReviewAuthor, type ReviewData, type ReviewFact, type ReviewState, SCHEMA_VERSION, type SettleOptions, TOKEN_ADVISORY_MARKER, UPDATE_REQUIRED_LABEL, USAGE, type UpdateAction, VERDICTS, type Verdict, buildRebaseRequestBody, buildTokenAdvisoryBody, classifyBotPr, classifyReleaseDiff, computeState, createGitRunner, createHttpClient, createMergeVerifier, currentVerdict, executePlan, formatSummary, gatherFacts, gatherLineage, isApiStatus, isRebasePending, isTrustedAuthor, isVersionOnlyPatch, parseArgs, parseDependabotUpdateType, parseGitVersion, parseVerdict, planReconcile, postTokenAdvisory, rebaseRequestMarker, reconcilePullRequest, runCli, toReconcileJson, withoutReleaseActions };

package/dist/index.js

@@ -1,8 +1,11 @@
 import {
   ACTOR_TYPES,
   AUTO_MERGE_LABEL,
-  COPILOT_REVIEWER_LOGIN,
+  BRANCH_UPDATERS,
+  DEFAULT_SETTLE_MS,
   DEPENDABOT_LOGIN,
+  DEPENDABOT_REBASE_COMMAND,
+  DEPENDABOT_REBASING_NOTICE,
   DEPENDABOT_UPDATE_TYPES,
   GitHubApiError,
   LIFECYCLE_LABELS,
@@ -11,16 +14,18 @@ import {
   OWNED_LABEL_DEFINITIONS,
   PR_STATUSES,
   RELEASE_PLEASE_BRANCH_PREFIX,
-  RELEASE_PLEASE_PENDING_LABEL,
   RELEASE_TOKEN_DOCS_URL,
   REPO_PERMISSIONS,
   REVIEW_STATES,
   SCHEMA_VERSION,
   TOKEN_ADVISORY_MARKER,
+  UPDATE_REQUIRED_LABEL,
   USAGE,
   VERDICTS,
+  buildRebaseRequestBody,
   buildTokenAdvisoryBody,
   classifyBotPr,
+  classifyReleaseDiff,
   computeState,
   createGitRunner,
   createHttpClient,
@@ -31,23 +36,29 @@ import {
   gatherFacts,
   gatherLineage,
   isApiStatus,
+  isRebasePending,
   isTrustedAuthor,
+  isVersionOnlyPatch,
   parseArgs,
   parseDependabotUpdateType,
   parseGitVersion,
   parseVerdict,
   planReconcile,
   postTokenAdvisory,
+  rebaseRequestMarker,
   reconcilePullRequest,
   runCli,
   toReconcileJson,
-  withoutArming
-} from "./chunk-RQEBRPZU.js";
+  withoutReleaseActions
+} from "./chunk-ENU2AAWK.js";
 export {
   ACTOR_TYPES,
   AUTO_MERGE_LABEL,
-  COPILOT_REVIEWER_LOGIN,
+  BRANCH_UPDATERS,
+  DEFAULT_SETTLE_MS,
   DEPENDABOT_LOGIN,
+  DEPENDABOT_REBASE_COMMAND,
+  DEPENDABOT_REBASING_NOTICE,
   DEPENDABOT_UPDATE_TYPES,
   GitHubApiError,
   LIFECYCLE_LABELS,
@@ -56,16 +67,18 @@ export {
   OWNED_LABEL_DEFINITIONS,
   PR_STATUSES,
   RELEASE_PLEASE_BRANCH_PREFIX,
-  RELEASE_PLEASE_PENDING_LABEL,
   RELEASE_TOKEN_DOCS_URL,
   REPO_PERMISSIONS,
   REVIEW_STATES,
   SCHEMA_VERSION,
   TOKEN_ADVISORY_MARKER,
+  UPDATE_REQUIRED_LABEL,
   USAGE,
   VERDICTS,
+  buildRebaseRequestBody,
   buildTokenAdvisoryBody,
   classifyBotPr,
+  classifyReleaseDiff,
   computeState,
   createGitRunner,
   createHttpClient,
@@ -76,15 +89,18 @@ export {
   gatherFacts,
   gatherLineage,
   isApiStatus,
+  isRebasePending,
   isTrustedAuthor,
+  isVersionOnlyPatch,
   parseArgs,
   parseDependabotUpdateType,
   parseGitVersion,
   parseVerdict,
   planReconcile,
   postTokenAdvisory,
+  rebaseRequestMarker,
   reconcilePullRequest,
   runCli,
   toReconcileJson,
-  withoutArming
+  withoutReleaseActions
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmartz/pr-lifecycle",
-  "version": "5.0.0",
+  "version": "8.0.0",
   "description": "Event-driven PR lifecycle reconciler: recomputes a pull request's lifecycle labels from its current facts on every GitHub event and arms native auto-merge on approval.",
   "keywords": [
     "ci",