@framers/agentos-ext-github 0.4.2 → 0.6.0

package/README.md

@@ -10,7 +10,7 @@ Its second entry, `@framers/agentos-ext-github/documents`, is for a server that
 npm install @framers/agentos-ext-github @framers/agentos @framers/agentos-ext-account-sources
 ```
 
-Peer dependencies: `@framers/agentos` with range `>=0.13.144`, whose auth module's `RedirectOAuthFlow` refuses a token answer that is JSON but not an object, and `@framers/agentos-ext-account-sources` with range `>=0.7.0`, whose connector types, capped reads and retry timing the `./documents` entry uses. A host keeps one copy of each; only the `./documents` entry loads `@framers/agentos-ext-account-sources`.
+Peer dependencies: `@framers/agentos` with range `>=0.13.144`, whose auth module's `RedirectOAuthFlow` refuses a token answer that is JSON but not an object, and `@framers/agentos-ext-account-sources`, whose connector types, capped reads and retry timing the `./documents` entry uses, at or above the floor this package's `peerDependencies` names; `npm view @framers/agentos-ext-github peerDependencies` prints the latest release's. A host keeps one copy of each; only the `./documents` entry loads `@framers/agentos-ext-account-sources`.
 
 ## Usage
 
@@ -351,6 +351,8 @@ Top-level pull request comments use the issues API. `github_pr_comment_list` ret
 
 The `./documents` entry reads repositories through a GitHub App instead of one personal token. Every call goes to GitHub's REST API over the `fetch` you pass (the global `fetch` by default) with `X-GitHub-Api-Version: 2026-03-10`, so tests point it at a stand-in with `{ fetchImpl, apiBase }`.
 
+A repository is read by its id, at `/repositories/<id>/branches/<branch>`, `/repositories/<id>/git/trees/<sha>` and `/repositories/<id>/contents/<path>`, the address GitHub's own redirects for a renamed or moved repository lead to, and never by its name. A name can come to mean another repository: a renamed repository's old name can be taken again, and an account's old login claimed by another account, which ends GitHub's redirects to it; and GitHub answers a public repository's branch, tree and files to any token, an installation token narrowed to other repositories included. The full name builds a read's attribution link and nothing else.
+
 ```ts
 import { readFileSync } from 'node:fs';
 import {
@@ -432,38 +434,43 @@ const changes = await connector.changesSince(cursor, { ids: [String(repositoryId
 | `ping` | `{ kind: 'ping' }` |
 | anything else | `{ kind: 'other' }`, as is a payload without the fields above; `delivery.name` holds the event's name |
 
-A delivery is refused with `WebhookDeliveryRefused`, checked in this order: `too_large` past `maxBytes` (25 MiB by default; the request's stream is cancelled at the cap, and a `Content-Length` past it is refused unread), `signature` when `X-Hub-Signature-256` does not hold under the secret, `delivery` without a usable `X-GitHub-Delivery`, `body` for a signed body that is not a JSON object. An empty secret throws a `TypeError`. `readWebhookDelivery({ headers, body }, secret, options)` does the same for a body already read. No error quotes a payload.
+A delivery is refused with `WebhookDeliveryRefused`, checked in this order: `too_large` past `maxBytes` (25 MiB by default; the request's stream is cancelled at the cap, and a `Content-Length` past it is refused unread), `signature` when `X-Hub-Signature-256` does not hold under the secret, `delivery` without a usable `X-GitHub-Delivery`, `body` for a signed body that is not a JSON object. An empty secret throws a `TypeError` before any of these, whatever the delivery, before its size is measured or a byte of its body read. `readWebhookDelivery({ headers, body }, secret, options)` does the same for a body already read. No error quotes a payload.
 
 Every call runs under a deadline, 30 seconds by default (`GITHUB_TIMEOUT_MS`), its answer's body included, joined with the caller's signal where a method takes one. The functions that take `{ fetchImpl, apiBase }` take `timeoutMs` beside them, `GitHubAppUserFlow` takes `{ timeoutMs, apiBase }` as its fourth argument, for the code exchange and `revoke`, and `installationToken(installationId, repositoryIds, { signal, timeoutMs })` takes both: the connector's calls pass their signal on to the token request, and `reconcileInstallations` its `timeoutMs`; the connector's own calls keep the default deadline. A call that gets no answer throws `GitHubNoAnswer` with its `reason`: `timeout`, `cancelled` or `network`, and so does a refused call whose body stops while it is read to tell a rate limit. The deadline and the cancel hold whatever the injected `fetch` does with the signal it is handed: a fetch that leaves its request or its answer's body open past that signal still ends the call on time, and an answer it gives after the deadline has its body released unread. A body still being read when its call ends is cancelled there, so nothing more of it is read, and a body the pack lets go (a refusal told by its status and headers, the answer to an uninstall, a redelivery or a revocation) is released without waiting on its cancel. A JSON answer is read under 16 MiB (`GITHUB_MAX_ANSWER_BYTES`). An answer outside 2xx throws `GitHubApiError` with `status`, `rateLimited` and `retryAt`, following GitHub's [rules for a refused call](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api#exceeding-the-rate-limit): a 429, or a 403 with `retry-after`, `x-ratelimit-remaining: 0` or a body naming a rate limit, is a rate limit, and `retryAt` (epoch milliseconds) is `retry-after` first, then `x-ratelimit-reset` when the remaining count is 0, else a minute on. Do not call again before `retryAt`: GitHub may ban an integration that keeps calling while rate limited. A 5xx's `retry-after` sets `retryAt` too.
 
 | Export | What it does |
 | --- | --- |
 | `appJwt(identity, nowSeconds?)` | The app's JWT: RS256, `iat` 60 seconds back, `exp` nine minutes ahead, `iss` the client id |
-| `GitHubAppCredential` | Mints installation tokens narrowed to the repositories asked for (`repository_ids`), each request under the caller's `signal` and `timeoutMs`, and holds each token until five minutes before its hour ends; an empty list throws a `TypeError`, since GitHub answers it with a token for every repository of the installation |
+| `GitHubAppCredential` | Mints installation tokens narrowed to the repositories asked for (`repository_ids`), each request under the caller's `signal` and `timeoutMs`, and holds each token until five minutes before its hour ends; an empty list throws a `TypeError`, since GitHub answers it with a token for every repository of the installation. `metadataToken(installationId, { signal, timeoutMs })` mints, and holds the same way, a token for every repository of the installation that reads their metadata alone (`permissions: { metadata: 'read' }`): enough to list them, never to read a file. `forget(installationId)` drops the tokens held for an installation, so the next call mints again |
 | `GitHubAppUserFlow` | The user's web flow on the auth module's `RedirectOAuthFlow`: GitHub's authorize address with `state` and PKCE and no `scope`, and the code exchange under a deadline (`new GitHubAppUserFlow(client, fetchImpl, endpoints, { timeoutMs, apiBase })`), which never follows a redirect from the token address: the redirect is refused with `OAuthGrantRefused` and its status, so the code and the client secret reach that address alone; it has no store, so the user token is used once; `revoke(token)` deletes it at GitHub with the app's client id and secret (`DELETE /applications/{client_id}/token`, Basic authentication), throwing `OAuthGrantRefused` (reason `revoke`, its status) for any answer but 204, another 2xx included, and refusing a redirect unfollowed; the answer is told by its status alone, its body released unread however large or slow |
 | `userOfToken`, `installationsOfUser`, `repositoriesOfUser` | The person a user token belongs to, the app's installations they can access, and the repositories of an installation they can read, across every page |
-| `listInstallations`, `uninstallInstallation` | The app's installations, and its uninstall, which takes 202 (GitHub removes it in the background), 204 and 404 as done |
+| `repositoriesOfInstallation(credential, installationId)` | Every repository an installation reaches (`GET /installation/repositories`), across every page, read with the credential's metadata token: the whole of what the app may read through the installation, whoever asks, so a repository its owner took off the app is missing from it. When an installation goes from all repositories to a selection, GitHub's `installation_repositories` delivery lists none of the repositories that left; this listing finds them. A held token GitHub refuses (401) is dropped and one new token asked for, once; a refused token request throws `GitHubApiError` (404 for an installation GitHub no longer has), so a lost installation never reads as one that reaches no repository |
+| `listInstallations`, `uninstallInstallation` | The app's installations, and its uninstall, which takes a 2xx (202 at the pinned API version, where GitHub removes it in the background; 204 at earlier versions) and 404 as done |
 | `verifyWebhookSignature(body, header, secret)` | Checks `X-Hub-Signature-256` against the HMAC SHA-256 of the raw body in constant time; an empty or missing secret throws a `TypeError`, since anyone can sign a delivery under an empty key |
 | `readWebhookRequest(request, secret, { maxBytes })`, `readWebhookDelivery({ headers, body }, secret, { maxBytes })` | Read a delivery under a cap, check its signature and id, and answer it as a typed event, or throw `WebhookDeliveryRefused` with its reason |
-| `reconcileInstallations(credential, links, { since })` | Answers the linked installations GitHub no longer lists, the repositories whose default branch moved past the head last read, the repositories it could not read, and asks again for each event since `since` that no delivery attempt delivered, reporting GitHub's refusals of that step in `deliveries` |
+| `reconcileInstallations(credential, links, { since })` | Answers the linked installations GitHub no longer lists, the repositories whose default branch moved past the head last read, the repositories it could not read, and asks again for each event since `since` that no delivery attempt delivered, reporting GitHub's refusals of that step in `deliveries`; a rate limit ends it, with `retryAt` |
 | `GitHubDocumentsConnector` | An `AccountSourceConnector` of `@framers/agentos-ext-account-sources` over one installation's linked repositories |
-| `readTree`, `pathFilter`, `TreeTooLarge` | A tree at a commit within a request budget, and the filter that keeps documentation |
+| `readTree`, `pathFilter`, `TreeTooLarge` | A tree at a commit within a request budget, `readTree(fetchImpl, token, repositoryId, commit)` reading the repository by its id (a full name is taken too, and reads whatever repository holds that name; a number that is not a positive integer is a `TypeError` before any request), and the filter that keeps documentation, and code when asked (`includeCode`); `TreeTooLarge` carries `reason`, `budget` or `truncated` |
+| `CODE_EXTENSIONS`, `GENERATED_CODE_ENDINGS`, `isGeneratedCode(path)` | The source files a filter that includes code keeps, and the endings of the code files a tool writes (minified and bundled files, generated Protocol Buffers and Dart files), which it leaves out |
 | `GitHubApiError` | An answer outside 2xx; carries the status, `rateLimited` and `retryAt`, and nothing of the body |
 | `GitHubNoAnswer` | A call that got no answer, by its `reason`: `timeout`, `cancelled` or `network` |
 
 The reconcile leaves failed a delivery whose newest attempt the receiving route answered with a 4xx other than 408 and 429, such as a 413 for a body past the route's size cap: that refusal answers the same on every attempt. A 408, a 429, a 5xx or any other failed attempt is asked for again. When GitHub answers the deliveries listing outside 2xx, `deliveries.listingStatus` holds its status and no delivery is asked for again, since a delivery's other attempts may lie on the pages not read; a redelivery GitHub refuses is listed in `deliveries.refused` with its status, and the others are still asked for. Either way the outcome carries `gone`, `moved` and `unreadable`.
 
+A call GitHub refuses for a rate limit ends the reconcile: it makes no call after that one, sets `retryAt` (epoch milliseconds) to the time GitHub gave, and answers what it found before the refusal. The gone installations are always whole, since they need no call past the installations listing; the repository whose head read was refused is not counted unreadable, and the repositories and the deliveries step it had not reached wait for the next run, which starts no sooner than `retryAt`. A refused redelivery is still listed in `deliveries.refused`. `retryAt` is null when no call was rate limited. A rate limit on the installations listing itself throws `GitHubApiError` with its `retryAt`, before anything is found.
+
 The connector's filter, `new GitHubDocumentsConnector(credential, installationId, repositories, filter)`:
 
 | Field | Default |
 | --- | --- |
 | `extensions` | `.md`, `.markdown`, `.txt`, `.rst`, `.html`, `.htm`, `.pdf`, `.docx` |
+| `includeCode` | `false`: when true, the source files of `CODE_EXTENSIONS` are kept beside `extensions` under the same bounds and skipped folders, each read as UTF-8 text, and a code file a tool wrote is left out (`isGeneratedCode`: a name ending in `.min.js`, `.min.css`, `.bundle.js`, `.bundle.css`, `.pb.go`, `_pb2.py` and the like), under an extension `extensions` names too. Data and configuration files (JSON, YAML, XML, CSV) are not code here; name their extensions in `extensions` to keep them |
 | `skipFolders` | `node_modules`, `vendor`, `dist`, `build`, `.git`, `third_party`, at any depth |
-| `maxFiles` | `2000`, in path order: a listing keeps the first `maxFiles` documentation paths, so when a new path sorts before them, the last one kept leaves the listing and `changesSince` answers it gone |
+| `maxFiles` | `2000`, in path order: a listing keeps the first `maxFiles` documentation paths, so when a new path sorts before them, the last one kept leaves the listing and `changesSince` answers it gone. With `includeCode`, the documentation keeps its places first and the code paths, in path order, take the room left, so turning code on drops no document |
 | `maxFileBytes` | `10485760` (10 MiB): larger files are left out of a listing, and a read past it is answered gone |
 | `maxTreeRequests` | `50` tree requests to list one commit |
 
-An item's id is `<repositoryId>:<path>` and its version `<blob>@<commit>`. A tree is asked for recursively; when GitHub answers it truncated (past 100,000 entries or 7 MB), its top level is read and each subtree is asked for the same way, never walking a skipped folder, and `TreeTooLarge` is thrown rather than pass `maxTreeRequests`. Files are read through the contents endpoint's raw media type as a stream cut at `maxFileBytes`: PDF, Word and HTML as bytes with their media type, the rest as UTF-8 text, each with a `github` source reference whose `url` is the file at the commit. An item whose version names no commit (none, or no `@<commit>` part) is read at the default branch, and its reference names the branch. `changesSince` takes the cursor it answered last (each documentation path's blob), never reads a push's commit list, so a force push is read like any other, and answers a push to another branch than the default with no change. `listing(repositoryId, commit)` lets a caller keep a commit's listing and pass it to `changesSince` as `listing`, with that commit as `after`; it then reads no tree. A cursor `changesSince` did not answer throws a `TypeError` that quotes none of it, whatever the push's branch. A file read GitHub refuses for a rate limit throws `GitHubApiError` with its `retryAt`, never an answer that the file is gone, and so does a refused installation token (404 for an installation GitHub no longer has): only the contents read's own 404 answers a file `removed`, so a lost installation never reads as every file gone.
+An item's id is `<repositoryId>:<path>` and its version `<blob>@<commit>`. A tree is asked for recursively; when GitHub answers it truncated (past 100,000 entries or 7 MB), its top level is read and each subtree is asked for the same way, never walking a skipped folder. `TreeTooLarge` is thrown rather than pass `maxTreeRequests` (`reason: 'budget'`), and at a level GitHub answers truncated when it is asked for alone as well (`reason: 'truncated'`), before any folder under it is asked for: no part of a tree is answered, since the files it left out would read as removed. Files are read through the contents endpoint's raw media type as a stream cut at `maxFileBytes`: PDF, Word and HTML as bytes with their media type, the rest as UTF-8 text, each with a `github` source reference whose `url` is the file at the commit, the commit or branch encoded segment by segment as the path is, so a branch named `docs#1` links as `docs%231`. An item whose version names no commit (none, or no `@<commit>` part) is read at the default branch, and its reference names the branch. `changesSince` takes the cursor it answered last (each documentation path's blob), never reads a push's commit list, so a force push is read like any other, and answers a push to another branch than the default with no change. `listing(repositoryId, commit)` lets a caller keep a commit's listing and pass it to `changesSince` as `listing`, with that commit as `after`; it then reads no tree. A cursor `changesSince` did not answer throws a `TypeError` that quotes none of it, whatever the push's branch. A file read GitHub refuses for a rate limit throws `GitHubApiError` with its `retryAt`, never an answer that the file is gone, and so does a refused installation token (404 for an installation GitHub no longer has): only the contents read's own 404 answers a file `removed`, so a lost installation never reads as every file gone.
 
 The connector refuses, before any request, what it cannot answer whole, and no refusal quotes a cursor, an item id or a path. A repository id, in a selection or in an item id, is a positive integer in decimal (`77`; never `077`, `0x4d` or ` 77`), else a `TypeError`. `list` checks every id of its selection before it reads any repository, so a selection is listed whole or not at all: a repository named twice is a `TypeError`, and one outside the link an `Error` naming its number. `read` throws a `TypeError` for an item id that names no file: one without a path, or whose path has an empty, `.` or `..` segment. `changesSince` compares one repository a call: a selection of none or several, an empty `after`, or a `listing` without the `after` commit it was read at is a `TypeError`, so call it once per repository, each with that repository's own cursor. A call whose signal is already aborted throws `GitHubNoAnswer` (`cancelled`) before it checks anything else, so every aborted call answers alike, whatever its inputs.
 

package/dist/__tests__/app.test.js

@@ -6,7 +6,7 @@
 import { createHash, createHmac, createVerify, generateKeyPairSync } from 'node:crypto';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { githubFetch } from '../app/http.js';
-import { appJwt, GITHUB_OAUTH_ENDPOINTS, GitHubApiError, GitHubAppCredential, GitHubAppUserFlow, GitHubNoAnswer, installationsOfUser, reconcileInstallations, repositoriesOfUser, uninstallInstallation, userOfToken, verifyWebhookSignature, } from '../documents/index.js';
+import { appJwt, GITHUB_OAUTH_ENDPOINTS, GitHubApiError, GitHubAppCredential, GitHubAppUserFlow, GitHubNoAnswer, installationsOfUser, reconcileInstallations, repositoriesOfInstallation, repositoriesOfUser, uninstallInstallation, userOfToken, verifyWebhookSignature, } from '../documents/index.js';
 /** A fetch that answers from `route` and records every request. */
 function standIn(route) {
     const seen = [];
@@ -173,7 +173,7 @@ function reconcileStandIn(hooks) {
                 return json({ message: 'There is at least one repository that does not exist' }, 422);
             return json({ token: `ghs_repo${ids.join('_')}`, expires_at: new Date(Date.now() + 3_600_000).toISOString() }, 201);
         }
-        if (url.pathname === '/repos/first-team/handbook/branches/main')
+        if (url.pathname === '/repositories/7/branches/main')
             return json({ name: 'main', commit: { sha: HEAD_NOW } });
         if (url.pathname.startsWith('/app/hook/'))
             return hooks(request, url);
@@ -222,6 +222,85 @@ describe('the GitHub App', () => {
         await expect(credential.installationToken(42, [])).rejects.toThrow(TypeError);
         expect(seen).toHaveLength(0);
     });
+    it("lists every repository an installation reaches across pages, with a token that reads their metadata alone and is held", async () => {
+        const { fetchImpl, seen } = standIn((request) => {
+            const url = new URL(request.url);
+            if (url.pathname === '/app/installations/21/access_tokens') {
+                return json({ token: 'ghs_metadata', expires_at: new Date(Date.now() + 3_600_000).toISOString() }, 201);
+            }
+            if (url.pathname === '/installation/repositories' && url.searchParams.get('page') === '2') {
+                return json({ total_count: 2, repository_selection: 'selected', repositories: [{ id: 9, full_name: 'first-team/plans', default_branch: 'trunk', private: true }] });
+            }
+            if (url.pathname === '/installation/repositories') {
+                const next = `${BASE}/installation/repositories?per_page=100&page=2`;
+                return json({ total_count: 2, repository_selection: 'selected', repositories: [{ id: 7, full_name: 'first-team/handbook', default_branch: 'main', private: true }] }, 200, { link: `<${next}>; rel="next", <${next}>; rel="last"` });
+            }
+            return json({ message: 'Not Found' }, 404);
+        });
+        const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
+        const at = { fetchImpl, apiBase: BASE };
+        expect(await repositoriesOfInstallation(credential, 21, at)).toEqual([
+            { id: 7, fullName: 'first-team/handbook', defaultBranch: 'main' },
+            { id: 9, fullName: 'first-team/plans', defaultBranch: 'trunk' },
+        ]);
+        expect(seen.map((request) => `${request.method} ${new URL(request.url).pathname}`)).toEqual([
+            'POST /app/installations/21/access_tokens',
+            'GET /installation/repositories',
+            'GET /installation/repositories',
+        ]);
+        // No repository named, so the token reaches every repository of the installation, and their metadata alone.
+        expect(JSON.parse(seen[0].body ?? '')).toEqual({ permissions: { metadata: 'read' } });
+        expect(appClaims(seen[0].headers.get('authorization'))).toMatchObject({ iss: CLIENT_ID });
+        expect(seen.slice(1).every((request) => request.headers.get('authorization') === 'Bearer ghs_metadata')).toBe(true);
+        expect(seen.slice(1).every((request) => request.headers.get('x-github-api-version') === '2026-03-10')).toBe(true);
+        // The token is held as an installation token is, apart from the tokens narrowed to repositories.
+        await repositoriesOfInstallation(credential, 21, at);
+        expect(seen.filter((request) => request.method === 'POST')).toHaveLength(1);
+        await credential.installationToken(21, [7]);
+        expect(seen.filter((request) => request.method === 'POST').map((request) => JSON.parse(request.body ?? ''))).toEqual([
+            { permissions: { metadata: 'read' } },
+            { repository_ids: [7] },
+        ]);
+    });
+    it('mints the metadata token again when GitHub refuses the held one, so an installation removed since reads as gone (404), not as a refused token', async () => {
+        let removed = false;
+        const { fetchImpl, seen } = standIn((request) => {
+            const url = new URL(request.url);
+            if (url.pathname === '/app/installations/21/access_tokens') {
+                if (removed)
+                    return json({ message: 'Not Found' }, 404);
+                return json({ token: 'ghs_metadata', expires_at: new Date(Date.now() + 3_600_000).toISOString() }, 201);
+            }
+            if (url.pathname === '/installation/repositories') {
+                if (removed)
+                    return json({ message: 'Bad credentials' }, 401);
+                return json({ total_count: 1, repository_selection: 'selected', repositories: [{ id: 7, full_name: 'first-team/handbook', default_branch: 'main' }] });
+            }
+            return json({ message: 'Not Found' }, 404);
+        });
+        const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
+        const at = { fetchImpl, apiBase: BASE };
+        expect(await repositoriesOfInstallation(credential, 21, at)).toHaveLength(1);
+        // GitHub removes the installation: the held token is refused, and a new one cannot be minted.
+        removed = true;
+        const failure = await repositoriesOfInstallation(credential, 21, at).catch((error) => error);
+        expect(failure).toBeInstanceOf(GitHubApiError);
+        expect(failure.status).toBe(404);
+        expect(seen.map((request) => `${request.method} ${new URL(request.url).pathname}`)).toEqual([
+            'POST /app/installations/21/access_tokens',
+            'GET /installation/repositories',
+            'GET /installation/repositories',
+            'POST /app/installations/21/access_tokens',
+        ]);
+    });
+    it('throws a listing whose metadata token GitHub refuses, so a lost installation never reads as one that reaches no repository', async () => {
+        const { fetchImpl, seen } = standIn(() => json({ message: 'Not Found' }, 404));
+        const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
+        const failure = await repositoriesOfInstallation(credential, 21, { fetchImpl, apiBase: BASE }).catch((error) => error);
+        expect(failure).toBeInstanceOf(GitHubApiError);
+        expect(failure.status).toBe(404);
+        expect(seen.map((request) => new URL(request.url).pathname)).toEqual(['/app/installations/21/access_tokens']);
+    });
     it("begins the user's web flow with state and PKCE and no scope, and completes it into a token it never stores", async () => {
         const { fetchImpl, seen } = standIn(() => json({ access_token: 'ghu_testuser', expires_in: 28_800, refresh_token: 'ghr_testuser', refresh_token_expires_in: 15_897_600, scope: '', token_type: 'bearer' }));
         const flow = new GitHubAppUserFlow({ clientId: CLIENT_ID, clientSecret: 'test-client-secret' }, fetchImpl);
@@ -462,9 +541,9 @@ describe('the GitHub App', () => {
                     return json({ message: 'There is at least one repository that does not exist' }, 422);
                 return json({ token: `ghs_repo${ids.join('_')}`, expires_at: new Date(now + 3_600_000).toISOString() }, 201);
             }
-            if (url.pathname === '/repos/first-team/handbook/branches/main')
+            if (url.pathname === '/repositories/7/branches/main')
                 return json({ name: 'main', commit: { sha: headNow } });
-            if (url.pathname === '/repos/first-team/notes/branches/trunk')
+            if (url.pathname === '/repositories/8/branches/trunk')
                 return json({ name: 'trunk', commit: { sha: headSame } });
             if (url.pathname === '/app/hook/deliveries') {
                 const cursor = url.searchParams.get('cursor');
@@ -505,8 +584,9 @@ describe('the GitHub App', () => {
             redelivered: [9001],
             unreadable: [{ installationId: 21, repositoryId: 9, status: 422 }],
             deliveries: { listingStatus: null, refused: [] },
+            retryAt: null,
         });
-        const branchRead = seen.find((request) => request.url === `${BASE}/repos/first-team/handbook/branches/main`);
+        const branchRead = seen.find((request) => request.url === `${BASE}/repositories/7/branches/main`);
         expect(branchRead?.headers.get('authorization')).toBe('Bearer ghs_repo7');
         expect(seen.some((request) => request.url.includes('/app/installations/22/'))).toBe(false);
         expect(seen.some((request) => request.url.includes('cursor=page3'))).toBe(false);
@@ -528,7 +608,7 @@ describe('the GitHub App', () => {
         });
         const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
         const outcome = await reconcileInstallations(credential, RECONCILE_LINKS, { since: new Date(now - 86_400_000), fetchImpl, apiBase: BASE });
-        expect(outcome).toEqual({ ...RECONCILED, redelivered: [], deliveries: { listingStatus: 500, refused: [] } });
+        expect(outcome).toEqual({ ...RECONCILED, redelivered: [], deliveries: { listingStatus: 500, refused: [] }, retryAt: null });
         expect(seen.some((request) => request.url.endsWith('/attempts'))).toBe(false);
     });
     it('goes on past a redelivery GitHub refuses with 403, reporting it beside the lists it computed', async () => {
@@ -546,7 +626,7 @@ describe('the GitHub App', () => {
         });
         const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
         const outcome = await reconcileInstallations(credential, RECONCILE_LINKS, { since: new Date(now - 86_400_000), fetchImpl, apiBase: BASE });
-        expect(outcome).toEqual({ ...RECONCILED, redelivered: [9002], deliveries: { listingStatus: null, refused: [{ id: 9001, status: 403 }] } });
+        expect(outcome).toEqual({ ...RECONCILED, redelivered: [9002], deliveries: { listingStatus: null, refused: [{ id: 9001, status: 403 }] }, retryAt: null });
         expect(seen.filter((request) => request.url.endsWith('/attempts')).map((request) => new URL(request.url).pathname)).toEqual([
             '/app/hook/deliveries/9001/attempts',
             '/app/hook/deliveries/9002/attempts',
@@ -577,6 +657,115 @@ describe('the GitHub App', () => {
         expect(outcome.redelivered).toEqual([9106, 9109, 9103, 9104]);
         expect(seen.filter((request) => request.method === 'POST').map((request) => new URL(request.url).pathname)).toEqual([9106, 9109, 9103, 9104].map((id) => `/app/hook/deliveries/${id}/attempts`));
     });
+    it("reads each repository's head by its id, never through a name another repository has taken since the link was made", async () => {
+        const now = Date.now();
+        const { fetchImpl, seen } = standIn((request) => {
+            const url = new URL(request.url);
+            if (url.pathname === '/app/installations')
+                return json([{ id: 21, account: { login: 'first-team', id: 901 } }]);
+            if (url.pathname === '/app/installations/21/access_tokens')
+                return json({ token: 'ghs_repo7', expires_at: new Date(now + 3_600_000).toISOString() }, 201);
+            if (url.pathname === '/repositories/7/branches/main')
+                return json({ name: 'main', commit: { sha: HEAD_BEFORE } });
+            // Another account's public repository holds the old name now, at another head.
+            if (url.pathname === '/repos/first-team/handbook/branches/main')
+                return json({ name: 'main', commit: { sha: HEAD_NOW } });
+            if (url.pathname === '/app/hook/deliveries')
+                return json([]);
+            return json({ message: 'Not Found' }, 404);
+        });
+        const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
+        const outcome = await reconcileInstallations(credential, [{ installationId: 21, repositories: [{ id: 7, fullName: 'first-team/handbook', defaultBranch: 'main', headCommit: HEAD_BEFORE }] }], { since: new Date(now - 86_400_000), fetchImpl, apiBase: BASE });
+        expect(outcome.moved).toEqual([]);
+        expect(outcome.unreadable).toEqual([]);
+        expect(seen.map((request) => new URL(request.url).pathname)).toContain('/repositories/7/branches/main');
+        expect(seen.some((request) => new URL(request.url).pathname.startsWith('/repos/'))).toBe(false);
+    });
+    it('stops at a rate limit, making no request after it, and keeps what it found beside the time to run again', async () => {
+        const now = Date.now();
+        const { fetchImpl, seen } = standIn((request) => {
+            const url = new URL(request.url);
+            if (url.pathname === '/app/installations')
+                return json([{ id: 21, account: { login: 'first-team', id: 901 } }]);
+            if (url.pathname === '/app/installations/21/access_tokens') {
+                const ids = JSON.parse(request.body ?? '{}').repository_ids;
+                return json({ token: `ghs_repo${ids.join('_')}`, expires_at: new Date(now + 3_600_000).toISOString() }, 201);
+            }
+            if (url.pathname === '/repositories/7/branches/main')
+                return json({ name: 'main', commit: { sha: HEAD_NOW } });
+            if (url.pathname === '/repositories/8/branches/main')
+                return json({ message: 'You have exceeded a secondary rate limit.' }, 429, { 'retry-after': '120' });
+            if (url.pathname === '/repositories/9/branches/main')
+                return json({ name: 'main', commit: { sha: HEAD_NOW } });
+            if (url.pathname === '/app/hook/deliveries') {
+                return json([{ id: 9001, guid: 'guid-1', delivered_at: new Date(now - 600_000).toISOString(), status_code: 500 }]);
+            }
+            return new Response(null, { status: 202 });
+        });
+        const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
+        const started = Date.now();
+        const outcome = await reconcileInstallations(credential, [
+            {
+                installationId: 21,
+                repositories: [
+                    { id: 7, fullName: 'first-team/handbook', defaultBranch: 'main', headCommit: HEAD_BEFORE },
+                    { id: 8, fullName: 'first-team/notes', defaultBranch: 'main', headCommit: HEAD_BEFORE },
+                    { id: 9, fullName: 'first-team/wiki', defaultBranch: 'main', headCommit: HEAD_BEFORE },
+                ],
+            },
+            { installationId: 22, repositories: [{ id: 30, fullName: 'gone-team/docs', defaultBranch: 'main', headCommit: HEAD_BEFORE }] },
+        ], { since: new Date(now - 86_400_000), fetchImpl, apiBase: BASE });
+        const { retryAt, ...found } = outcome;
+        // What it found before the refusal is kept, the gone installation among it; repository 8 was refused, not found unreadable.
+        expect(found).toEqual({
+            gone: [22],
+            moved: [{ installationId: 21, repositoryId: 7, head: HEAD_NOW }],
+            redelivered: [],
+            unreadable: [],
+            deliveries: { listingStatus: null, refused: [] },
+        });
+        expect(retryAt).toBeGreaterThanOrEqual(started + 120_000);
+        expect(retryAt).toBeLessThanOrEqual(Date.now() + 120_000);
+        // The refused read was the last request: not repository 9, not the deliveries, not a redelivery.
+        expect(seen[seen.length - 1]?.url).toBe(`${BASE}/repositories/8/branches/main`);
+    });
+    it('ends the deliveries step at a rate limit, asking for no delivery after it, and answers the time to run again', async () => {
+        const now = Date.now();
+        const reset = Math.floor(now / 1000) + 900;
+        const listing = reconcileStandIn((_request, url) => {
+            if (url.pathname === '/app/hook/deliveries') {
+                return json({ message: 'API rate limit exceeded' }, 403, { 'x-ratelimit-remaining': '0', 'x-ratelimit-reset': String(reset) });
+            }
+            return new Response(null, { status: 202 });
+        });
+        const listingCredential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, listing.fetchImpl, BASE);
+        const listingOutcome = await reconcileInstallations(listingCredential, RECONCILE_LINKS, { since: new Date(now - 86_400_000), fetchImpl: listing.fetchImpl, apiBase: BASE });
+        expect(listingOutcome).toEqual({ ...RECONCILED, redelivered: [], deliveries: { listingStatus: 403, refused: [] }, retryAt: reset * 1000 });
+        const redelivery = reconcileStandIn((_request, url) => {
+            if (url.pathname === '/app/hook/deliveries') {
+                return json([
+                    { id: 9001, guid: 'guid-1', delivered_at: new Date(now - 600_000).toISOString(), status_code: 500 },
+                    { id: 9002, guid: 'guid-2', delivered_at: new Date(now - 1_200_000).toISOString(), status_code: 502 },
+                ]);
+            }
+            if (url.pathname === '/app/hook/deliveries/9001/attempts')
+                return json({ message: 'You have exceeded a secondary rate limit.' }, 429, { 'retry-after': '60' });
+            return new Response(null, { status: 202 });
+        });
+        const redeliveryCredential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, redelivery.fetchImpl, BASE);
+        const started = Date.now();
+        const redeliveryOutcome = await reconcileInstallations(redeliveryCredential, RECONCILE_LINKS, {
+            since: new Date(now - 86_400_000),
+            fetchImpl: redelivery.fetchImpl,
+            apiBase: BASE,
+        });
+        const { retryAt, ...found } = redeliveryOutcome;
+        expect(found).toEqual({ ...RECONCILED, redelivered: [], deliveries: { listingStatus: null, refused: [{ id: 9001, status: 429 }] } });
+        expect(retryAt).toBeGreaterThanOrEqual(started + 60_000);
+        expect(redelivery.seen.filter((request) => request.url.endsWith('/attempts')).map((request) => new URL(request.url).pathname)).toEqual([
+            '/app/hook/deliveries/9001/attempts',
+        ]);
+    });
     it("ends a repository's installation token request at the reconcile's deadline", async () => {
         const { fetchImpl: answering } = reconcileStandIn(() => json([]));
         const fetchImpl = async (input, init) => {
@@ -590,7 +779,7 @@ describe('the GitHub App', () => {
         expect(failure.reason).toBe('timeout');
         expect(Date.now() - started).toBeLessThan(5_000);
     });
-    it('uninstalls with the JWT, taking 202, 204 and 404 as done and throwing other answers without their body', async () => {
+    it('uninstalls with the JWT, taking a 2xx (202, 204) and 404 as done and throwing other answers without their body', async () => {
         const { fetchImpl, seen } = standIn((request) => {
             const id = new URL(request.url).pathname.split('/').pop();
             if (id === '31')
@@ -599,6 +788,8 @@ describe('the GitHub App', () => {
                 return new Response(null, { status: 204 });
             if (id === '33')
                 return json({ message: 'Not Found' }, 404);
+            if (id === '35')
+                return json({}, 200);
             return json({ message: 'internal detail of the failure' }, 500);
         });
         const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
@@ -610,7 +801,9 @@ describe('the GitHub App', () => {
         expect(failure).toBeInstanceOf(GitHubApiError);
         expect(failure.status).toBe(500);
         expect(failure.message).not.toContain('internal detail');
-        expect(seen.map((request) => `${request.method} ${request.url}`)).toEqual([31, 32, 33, 34].map((id) => `DELETE ${BASE}/app/installations/${id}`));
+        // Any 2xx is GitHub taking the removal, whatever the API version answers it with.
+        await expect(uninstallInstallation(credential, 35, at)).resolves.toBeUndefined();
+        expect(seen.map((request) => `${request.method} ${request.url}`)).toEqual([31, 32, 33, 34, 35].map((id) => `DELETE ${BASE}/app/installations/${id}`));
         expect(seen.every((request) => appClaims(request.headers.get('authorization')) !== null)).toBe(true);
     });
     it("takes an uninstall and a redelivery as done at once, never waiting on an answer's body whose cancel does not settle", async () => {