@framers/agentos-ext-github 0.6.0 → 0.8.0

package/README.md

@@ -351,7 +351,7 @@ 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.
+A repository is read by its id, at `/repositories/<id>/branches/<branch>`, `/repositories/<id>/git/trees/<sha>`, `/repositories/<id>/contents/<path>` and `/repositories/<id>/git/matching-refs/heads/<name>`, 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';
@@ -444,20 +444,26 @@ Every call runs under a deadline, 30 seconds by default (`GITHUB_TIMEOUT_MS`), i
 | `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 |
-| `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 |
+| `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. The listing is read a page at a time, and a repository added to or taken off the installation between two pages changes GitHub's `total_count` and can move another one past a page's end: a read whose pages disagree on that count is read again, up to three reads, and then `GitHubListingChanged` is thrown |
+| `repositoriesLost(credential, installationId, held)` | Which of the repositories `held` an installation no longer reaches: those missing from two listings, the second read only when the first misses one, since an addition and a removal between the same two pages leave the count as it was and can still move a repository past a page's end; in the order of `held`, each id once, with no request for an empty `held`; a refused listing, or `GitHubListingChanged`, is thrown. A limit: a repository is answered lost when, in each of the two listings, an addition and a removal between the same two pages moved it past a page's end |
+| `listInstallations`, `getInstallation`, `uninstallInstallation` | The app's installations, each with `suspendedAt` (GitHub's `suspended_at`, null while it is not suspended); one installation by its id (`GET /app/installations/{installation_id}`), with `suspendedAt`, or null on 404, any other refusal thrown; 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`; a rate limit ends it, with `retryAt` |
-| `GitHubDocumentsConnector` | An `AccountSourceConnector` of `@framers/agentos-ext-account-sources` over one installation's linked repositories |
+| `reconcileInstallations(credential, links, { since })` | Answers the linked installations GitHub no longer has (`gone`: missing from the listing and answered 404 at their own address, since an installation removed while the listing is read can move another past a page's end), those GitHub has suspended (`suspended`, whose repositories it does not read), 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, at each one's default branch or at the branch or commit a selection's `at` names; `resolveRef(repositoryId, refAndPath)` settles where a link's branch name ends |
+| `parseGitHubLink(text)` | The repository, folder or file a GitHub address names, read without a request; `refused` for any other address on GitHub's hosts, `null` for another host's |
 | `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 |
+| `planTree(blobs, options)`, `IMAGE_EXTENSIONS` | Every file of a tree with its outcome under `pathFilter`'s filter: a note, or skipped with the reason it is left out |
 | `GitHubApiError` | An answer outside 2xx; carries the status, `rateLimited` and `retryAt`, and nothing of the body |
+| `GitHubListingChanged` | An installation's repositories changed during each of three reads of their listing (its pages disagreed on `total_count`), so no read is whole; its message names nothing of the installation |
 | `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`.
+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`, `suspended`, `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.
+`suspended` is GitHub's word on each linked installation that is not gone: a linked installation in neither `gone` nor `suspended` is not suspended. GitHub blocks a suspended installation's API access and its webhook events, and its `suspend` and `unsuspend` deliveries can arrive out of order or be refused by a receiving route that is switched off, so a caller that keeps a link's suspension from those deliveries sets it from this list.
+
+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 and the suspended installations are always whole, since they are settled before any head is read; 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, or on a missing installation's own address, throws `GitHubApiError` with its `retryAt`, before anything is found, as any other refusal of those calls does (a 404 at an installation's own address apart, which answers it gone).
 
 The connector's filter, `new GitHubDocumentsConnector(credential, installationId, repositories, filter)`:
 
@@ -470,10 +476,38 @@ The connector's filter, `new GitHubDocumentsConnector(credential, installationId
 | `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. `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.
+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 one it follows 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.
 
+`list`, `changesSince` and `head` follow the default branch, or the branch or commit a selection's `at` names (`head(repositoryId, at, signal)`; `head(repositoryId, signal)` reads the default branch as before). A branch's head is read when the call is made; a commit, 40 hexadecimal characters in either case, is read as it is with no branch read, in lower case, and never changes. `list({ ids: [String(repositoryId)], at: 'release/1.0' })` lists one repository at that branch's head, each item's version `<blob>@<commit>` at it. `changesSince` compares at the followed branch's head when the call names no `after`, answers a push whose `ref` is not `refs/heads/<at>` with no change (the default branch's push included, while `at` names another branch), and answers any push with no change when `at` is a commit; without a push, an `after` naming another commit than `at`'s is a `TypeError`. An `at` that is neither a commit nor a branch name by [git's rules](https://git-scm.com/docs/git-check-ref-format) (no `..`, `@{`, space, control character, `~`, `^`, `:`, `?`, `*`, `[` or `\`; no part empty, starting with a dot or ending in `.lock`; not ending with a dot, not starting with a dash, neither `@` nor `HEAD`), and an `at` beside other than one repository in `list`, throw a `TypeError` before any request.
+
+`parseGitHubLink(text)` reads the GitHub address a person pastes, without a request:
+
+| Address | Answered as |
+| --- | --- |
+| `github.com/<owner>/<repo>`, with or without `.git`; `git@github.com:<owner>/<repo>.git` | `{ kind: 'github_repository', owner, repo }` |
+| `github.com/<owner>/<repo>/tree/<ref>/<path>`, and `/blob/<ref>` with no path, which GitHub shows as the folder | `{ kind: 'github_folder', owner, repo, refAndPath }` |
+| `github.com/<owner>/<repo>/blob/<ref>/<path>` and `/raw/<ref>/<path>`; `raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>` | `{ kind: 'github_file', owner, repo, refAndPath, raw }`, `raw` true for the two raw forms |
+| Any other address on `github.com`, `www.github.com`, `gist.github.com`, `api.github.com`, `codeload.github.com`, `uploads.github.com` or a host under `githubusercontent.com`: an account, an issue, a pull request, a wiki, a release, a commit, a tag (`refs/tags/`), a gist, GitHub's own pages, an address that carries credentials, with a scheme or without one (`<user>:<password>@github.com/...`, which a browser opens as an `https://` address) | `{ kind: 'refused' }` |
+| An address on any other host, an opaque address such as `mailto:someone@github.com`, and text that is no address | `null` |
+
+The scheme, or its absence, a port, the dots that end a host (`github.com.`, `github.com..`), a trailing slash, a query and a fragment are ignored; `www.github.com` is read as `github.com`, and GitHub's form of a branch by its full name, `refs/heads/<branch>`, as the branch. Each segment is decoded, and an address whose path has an empty segment, an escape that does not decode, or a `.` or `..` segment or a control character once decoded is refused. A folder's and a file's ref and path are one text, `refAndPath`, since a branch name may hold a slash. `connector.resolveRef(repositoryId, refAndPath)` settles it as `{ ref, path, commit }`: a first segment of 40 hexadecimal characters is a commit (`commit: true`, in lower case) and `HEAD` the default branch, with no request; otherwise one request to GitHub's [matching references](https://docs.github.com/en/rest/git/refs#list-matching-references), which answers every branch whose name starts with that segment, and the longest branch name that is the text or starts it at a slash is the ref, the rest the path (`''` for the ref's root). Git keeps no branch beside one under its name (`release` beside `release/1.0`), so at most one such branch exists. A first segment no branch has is answered as the ref all the same, and a listing at it throws GitHub's 404 as `GitHubApiError`; so does 409 for a repository with no commit. A `/blob/` address whose text has no slash (`/blob/main`) names its ref alone and is answered as the folder, since GitHub redirects it to `/tree/main`; one whose text has a slash is a file, and when `resolveRef` settles the whole text as the ref (`/blob/release/1.0` in a repository with a `release/1.0` branch), the path is `''`: the address names a ref and no file, which GitHub answers 404.
+
+```ts
+import { parseGitHubLink } from '@framers/agentos-ext-github/documents';
+
+const link = parseGitHubLink('https://github.com/acme-team/handbook/tree/release/1.0/docs');
+if (link?.kind === 'github_folder') {
+  // repositoryId: the linked repository whose full name is `${link.owner}/${link.repo}`.
+  const { ref, path } = await connector.resolveRef(repositoryId, link.refAndPath); // 'release/1.0' and 'docs'
+  const { items } = await connector.list({ ids: [String(repositoryId)], at: ref });
+  const inFolder = items.filter((item) => path === '' || item.title.startsWith(`${path}/`));
+}
+```
+
+`planTree(blobs, options)` answers every file of a tree (`readTree`'s blobs) in path order, each a new object with its `path`, `sha`, `size` and `outcome`: `'note'`, or `{ skipped }` with the first reason the file is left out. `folder` under a skipped folder; `kind` for a file that is neither documentation, code nor an image (data, configuration, a binary, a file with no extension); `image` for `IMAGE_EXTENSIONS`, or the `imageExtensions` given; `code` for code while `includeCode` is off; `generated` for code a tool wrote while `includeCode` is on; `size` past `maxFileBytes`, or past `maxCodeBytes` for a file of a code extension while `includeCode` is on, whatever `extensions` names (`maxFileBytes` when absent, a non-negative integer, else a `TypeError`); `count` past `maxFiles`, the documentation keeping its places first and the code taking the room left. The notes are exactly what `pathFilter` keeps under the same filter, a code file past `maxCodeBytes` aside, so a caller can show what is left out and why from one listing, and turn code on or off without reading the tree again. An extension the filter's `extensions` names is documentation, an image's included.
+
 ## License
 
 Apache-2.0

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, repositoriesOfInstallation, repositoriesOfUser, uninstallInstallation, userOfToken, verifyWebhookSignature, } from '../documents/index.js';
+import { appJwt, GITHUB_OAUTH_ENDPOINTS, GitHubApiError, GitHubAppCredential, GitHubAppUserFlow, GitHubListingChanged, GitHubNoAnswer, getInstallation, installationsOfUser, listInstallations, reconcileInstallations, repositoriesLost, repositoriesOfInstallation, repositoriesOfUser, uninstallInstallation, userOfToken, verifyWebhookSignature, } from '../documents/index.js';
 /** A fetch that answers from `route` and records every request. */
 function standIn(route) {
     const seen = [];
@@ -154,6 +154,7 @@ const RECONCILE_LINKS = [
 /** What a reconcile of {@link RECONCILE_LINKS} finds before its deliveries step. */
 const RECONCILED = {
     gone: [22],
+    suspended: [],
     moved: [{ installationId: 21, repositoryId: 7, head: HEAD_NOW }],
     unreadable: [{ installationId: 21, repositoryId: 9, status: 422 }],
 };
@@ -301,6 +302,98 @@ describe('the GitHub App', () => {
         expect(failure.status).toBe(404);
         expect(seen.map((request) => new URL(request.url).pathname)).toEqual(['/app/installations/21/access_tokens']);
     });
+    it('reads a listing again while its pages disagree on the count, and throws one that keeps changing', async () => {
+        // GitHub's pages of two: while a read is between its pages, a repository is taken off the installation, so the count
+        // the second page gives is one less and another repository has moved onto the first page, already read.
+        let reached = [5, 7, 9, 11, 13];
+        let firstPages = 0;
+        let removals = 1;
+        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') {
+                const page = Number(url.searchParams.get('page') ?? '1');
+                if (page === 1)
+                    firstPages += 1;
+                if (page === 2 && removals > 0) {
+                    removals -= 1;
+                    reached = reached.slice(1);
+                }
+                const pages = Math.ceil(reached.length / 2);
+                const next = `${BASE}/installation/repositories?per_page=100&page=${page + 1}`;
+                return json({
+                    total_count: reached.length,
+                    repository_selection: 'selected',
+                    repositories: reached.slice((page - 1) * 2, page * 2).map((id) => ({ id, full_name: `first-team/repository-${id}`, default_branch: 'main' })),
+                }, 200, page < pages ? { link: `<${next}>; rel="next"` } : {});
+            }
+            return json({ message: 'Not Found' }, 404);
+        });
+        const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
+        const at = { fetchImpl, apiBase: BASE };
+        // The first read lost 9 to the move and gave counts of 5 and 4; the second agrees with itself and is answered.
+        expect((await repositoriesOfInstallation(credential, 21, at)).map((repository) => repository.id)).toEqual([7, 9, 11, 13]);
+        expect(firstPages).toBe(2);
+        // A listing that changes during each of three reads is thrown, answering no repository.
+        reached = [5, 7, 9, 11, 13, 15, 17];
+        firstPages = 0;
+        removals = 3;
+        const failure = await repositoriesOfInstallation(credential, 21, at).catch((error) => error);
+        expect(failure).toBeInstanceOf(GitHubListingChanged);
+        expect(failure.message).not.toMatch(/\d/);
+        expect(firstPages).toBe(3);
+        expect(seen.filter((request) => request.method === 'POST')).toHaveLength(1);
+    });
+    it("answers a held repository lost only when two listings miss it, so one a change moved past a page's end is kept", async () => {
+        // GitHub's pages of two: while the first listing is between its pages, repository 5 is taken off the installation
+        // and 13 added to it, which leaves the count as it was, so 9 moves onto the first page, already read, and that
+        // listing misses it.
+        let reached = [5, 7, 9, 11];
+        let firstPages = 0;
+        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') {
+                const page = Number(url.searchParams.get('page') ?? '1');
+                if (page === 1)
+                    firstPages += 1;
+                if (page === 2 && firstPages === 1)
+                    reached = [...reached.filter((id) => id !== 5), 13];
+                const pages = Math.ceil(reached.length / 2);
+                const next = `${BASE}/installation/repositories?per_page=100&page=${page + 1}`;
+                return json({
+                    total_count: reached.length,
+                    repository_selection: 'selected',
+                    repositories: reached.slice((page - 1) * 2, page * 2).map((id) => ({ id, full_name: `first-team/repository-${id}`, default_branch: 'main' })),
+                }, 200, page < pages ? { link: `<${next}>; rel="next"` } : {});
+            }
+            return json({ message: 'Not Found' }, 404);
+        });
+        const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
+        const at = { fetchImpl, apiBase: BASE };
+        const listings = () => seen.filter((request) => new URL(request.url).pathname === '/installation/repositories').length;
+        // 9 is missing from the first listing alone and kept; 12 is missing from both and lost. 5, which the first listing
+        // still held, waits for the next run.
+        expect(await repositoriesLost(credential, 21, [5, 7, 9, 12, 12], at)).toEqual([12]);
+        expect(listings()).toBe(4);
+        expect(seen.filter((request) => request.method === 'POST')).toHaveLength(1);
+        // A listing that holds every held repository is read once, and an empty list asks GitHub for nothing.
+        const before = listings();
+        expect(await repositoriesLost(credential, 21, [7, 9, 11], at)).toEqual([]);
+        expect(listings() - before).toBe(2);
+        expect(await repositoriesLost(credential, 21, [], at)).toEqual([]);
+        expect(listings() - before).toBe(2);
+        // A refused listing throws, answering nothing lost.
+        const refusing = standIn(() => json({ message: 'Not Found' }, 404));
+        const refused = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, refusing.fetchImpl, BASE);
+        const failure = await repositoriesLost(refused, 21, [7], { fetchImpl: refusing.fetchImpl, apiBase: BASE }).catch((error) => error);
+        expect(failure).toBeInstanceOf(GitHubApiError);
+        expect(failure.status).toBe(404);
+    });
     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);
@@ -580,6 +673,7 @@ describe('the GitHub App', () => {
         ], { since: new Date(now - 86_400_000), fetchImpl, apiBase: BASE });
         expect(outcome).toEqual({
             gone: [22],
+            suspended: [],
             moved: [{ installationId: 21, repositoryId: 7, head: headNow }],
             redelivered: [9001],
             unreadable: [{ installationId: 21, repositoryId: 9, status: 422 }],
@@ -700,6 +794,8 @@ describe('the GitHub App', () => {
             if (url.pathname === '/app/hook/deliveries') {
                 return json([{ id: 9001, guid: 'guid-1', delivered_at: new Date(now - 600_000).toISOString(), status_code: 500 }]);
             }
+            if (url.pathname === '/app/installations/22')
+                return json({ message: 'Not Found' }, 404);
             return new Response(null, { status: 202 });
         });
         const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
@@ -719,6 +815,7 @@ describe('the GitHub App', () => {
         // 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],
+            suspended: [],
             moved: [{ installationId: 21, repositoryId: 7, head: HEAD_NOW }],
             redelivered: [],
             unreadable: [],
@@ -779,6 +876,126 @@ describe('the GitHub App', () => {
         expect(failure.reason).toBe('timeout');
         expect(Date.now() - started).toBeLessThan(5_000);
     });
+    it('answers a linked installation gone only once its own address answers 404, and reads one the listing missed', async () => {
+        const now = Date.now();
+        const { fetchImpl, seen } = standIn((request) => {
+            const url = new URL(request.url);
+            // Installation 23 still exists: an installation removed while the listing was read moved it past a page's end.
+            if (url.pathname === '/app/installations')
+                return json([{ id: 21, account: { login: 'first-team', id: 901 }, suspended_at: null }]);
+            if (url.pathname === '/app/installations/23')
+                return json({ id: 23, account: { login: 'third-team', id: 903 }, suspended_at: null });
+            const tokenFor = /^\/app\/installations\/(\d+)\/access_tokens$/.exec(url.pathname);
+            if (tokenFor !== null)
+                return json({ token: `ghs_installation${tokenFor[1]}`, 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 } });
+            if (url.pathname === '/repositories/40/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 }] },
+            { installationId: 22, repositories: [{ id: 30, fullName: 'gone-team/docs', defaultBranch: 'main', headCommit: HEAD_BEFORE }] },
+            { installationId: 23, repositories: [{ id: 40, fullName: 'third-team/notes', defaultBranch: 'main', headCommit: HEAD_BEFORE }] },
+            { installationId: 22, repositories: [] },
+        ], { since: new Date(now - 86_400_000), fetchImpl, apiBase: BASE });
+        expect(outcome).toEqual({
+            gone: [22],
+            suspended: [],
+            moved: [{ installationId: 23, repositoryId: 40, head: HEAD_NOW }],
+            redelivered: [],
+            unreadable: [],
+            deliveries: { listingStatus: null, refused: [] },
+            retryAt: null,
+        });
+        // Each installation the listing missed was asked for once, at its own address with the app's JWT, and no token was
+        // asked for the gone one.
+        const ownAddresses = seen.filter((request) => /^\/app\/installations\/\d+$/.test(new URL(request.url).pathname));
+        expect(ownAddresses.map((request) => `${request.method} ${new URL(request.url).pathname}`)).toEqual(['GET /app/installations/22', 'GET /app/installations/23']);
+        expect(ownAddresses.every((request) => appClaims(request.headers.get('authorization')) !== null)).toBe(true);
+        expect(seen.some((request) => request.url.includes('/app/installations/22/'))).toBe(false);
+    });
+    it('answers the linked installations GitHub suspended, reading none of their repositories, and their time in the listing', 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 }, suspended_at: '2026-10-20T10:00:00Z', suspended_by: { login: 'first-owner', id: 911 } },
+                    { id: 24, account: { login: 'fourth-team', id: 904 }, suspended_at: null, suspended_by: null },
+                ]);
+            }
+            // Installation 25 was moved past the listing's page end, and is suspended too.
+            if (url.pathname === '/app/installations/25')
+                return json({ id: 25, account: { login: 'fifth-team', id: 905 }, suspended_at: '2026-10-21T08:00:00Z' });
+            const tokenFor = /^\/app\/installations\/(\d+)\/access_tokens$/.exec(url.pathname);
+            if (tokenFor !== null)
+                return json({ token: `ghs_installation${tokenFor[1]}`, expires_at: new Date(now + 3_600_000).toISOString() }, 201);
+            if (url.pathname === '/repositories/50/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 at = { fetchImpl, apiBase: BASE };
+        const outcome = await reconcileInstallations(credential, [
+            { installationId: 21, repositories: [{ id: 7, fullName: 'first-team/handbook', defaultBranch: 'main', headCommit: HEAD_BEFORE }] },
+            { installationId: 24, repositories: [{ id: 50, fullName: 'fourth-team/docs', defaultBranch: 'main', headCommit: HEAD_BEFORE }] },
+            { installationId: 25, repositories: [{ id: 60, fullName: 'fifth-team/docs', defaultBranch: 'main', headCommit: HEAD_BEFORE }] },
+        ], { since: new Date(now - 86_400_000), ...at });
+        expect(outcome).toEqual({
+            gone: [],
+            suspended: [21, 25],
+            moved: [{ installationId: 24, repositoryId: 50, head: HEAD_NOW }],
+            redelivered: [],
+            unreadable: [],
+            deliveries: { listingStatus: null, refused: [] },
+            retryAt: null,
+        });
+        // No token was asked for a suspended installation, and none of their repositories was read.
+        expect(seen.filter((request) => request.url.endsWith('/access_tokens')).map((request) => new URL(request.url).pathname)).toEqual(['/app/installations/24/access_tokens']);
+        expect(seen.some((request) => /\/repositories\/(7|60)\//.test(new URL(request.url).pathname))).toBe(false);
+        // The app's own calls answer each installation with when it was suspended, and one GitHub no longer has as null.
+        expect(await listInstallations(credential, at)).toEqual([
+            { id: 21, account: { login: 'first-team', id: 901 }, suspendedAt: '2026-10-20T10:00:00Z' },
+            { id: 24, account: { login: 'fourth-team', id: 904 }, suspendedAt: null },
+        ]);
+        expect(await getInstallation(credential, 25, at)).toEqual({ id: 25, account: { login: 'fifth-team', id: 905 }, suspendedAt: '2026-10-21T08:00:00Z' });
+        expect(await getInstallation(credential, 26, at)).toBeNull();
+    });
+    it("throws, answering nothing gone, when GitHub refuses an installation's own address with a status other than 404", async () => {
+        const now = Date.now();
+        const refusals = [
+            { status: 502, headers: {} },
+            { status: 429, headers: { 'retry-after': '120' } },
+        ];
+        for (const { status, headers } of refusals) {
+            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/22')
+                    return json({ message: 'refused' }, status, headers);
+                return json({ name: 'main', commit: { sha: HEAD_NOW } });
+            });
+            const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
+            const started = Date.now();
+            const failure = await reconcileInstallations(credential, RECONCILE_LINKS, { since: new Date(now - 86_400_000), fetchImpl, apiBase: BASE }).catch((error) => error);
+            expect(failure).toBeInstanceOf(GitHubApiError);
+            expect(failure.status).toBe(status);
+            if (status === 429) {
+                expect(failure.rateLimited).toBe(true);
+                expect(failure.retryAt).toBeGreaterThanOrEqual(started + 120_000);
+            }
+            // Nothing was read after the refusal: no token, no head, no deliveries.
+            expect(seen.map((request) => new URL(request.url).pathname)).toEqual(['/app/installations', '/app/installations/22']);
+        }
+    });
     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();