@framers/agentos-ext-github 0.5.0 → 0.7.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
 
@@ -441,29 +441,36 @@ Every call runs under a deadline, 30 seconds by default (`GITHUB_TIMEOUT_MS`), i
 | 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 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` |
+| `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 |
-| `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; `TreeTooLarge` carries `reason`, `budget` or `truncated` |
+| `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 |
+| `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)`:
 
 | 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 |
 

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, 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 }],
 };
@@ -222,6 +223,177 @@ 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('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);
@@ -501,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 }],
@@ -621,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);
@@ -640,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: [],
@@ -700,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();