@impeccable/reviews 0.1.34 → 0.1.36

package/dist/host-previews.js

@@ -9,7 +9,9 @@ import { readSiteCall } from './netlify-password.js';
  * setting is ever changed: a project whose builds are stopped altogether
  * (Netlify `stop_builds`, Cloudflare `deployments_enabled` false) is reported
  * and left as it is. Vercel builds every branch once Git is connected, so its
- * fact is read from vercel.json and the project (vercel.ts) and never written.
+ * fact is read from vercel.json and the project (vercel.ts), and the one
+ * setting written is the project's deployment_status Events, without which
+ * Vercel records none of its deployments on GitHub.
  */
 /** The branch the test drive pushes, whose build is the preview the setting must allow. */
 export const TEST_DRIVE_BRANCH = 'impeccable/test-drive';

package/dist/host-questions.js

@@ -1,3 +1,4 @@
+import { basename } from 'node:path';
 /** The ids the model may name, each worded here whatever else it writes for that id. */
 export const HOST_QUESTIONS = {
     'vercel-setup': {
@@ -45,6 +46,25 @@ export const HOST_SIGNED_IN = {
         confirmLabel: 'Set up',
     },
 };
+/**
+ * The Vercel setup screen with its CLI signed in already as `user`: it names that account, the new project (`project`,
+ * where its name is known) and where it goes, the team the run takes (`team`), the one the person picks next (`pick`) or,
+ * with no team, the account itself, so the yes is to that account, project and team (REN-1250).
+ */
+export function vercelSignedIn(user, where) {
+    const into = where.team ? `in the team ${where.team}` : where.pick ? 'in the team you pick next' : 'of that account';
+    const project = where.project ? `a new project, ${where.project}, ` : 'a new project ';
+    return { ...HOST_SIGNED_IN['vercel-setup'], hint: `Impeccable reviews each pull request on a preview. Vercel can host those previews: the run sets them up with the Vercel CLI on this machine, signed in as ${user}, in ${project}${into}. What is live stays as it is.` };
+}
+/**
+ * The project the Vercel setup makes, named as `vercel link --yes` finds it in the checkout's root (`root`): the folder's
+ * own name, which the playbook's `vercel project add` gives it. None where that name is not one Vercel takes as it is
+ * (lowercase letters, digits, `.`, `_` and `-`, at most 100, never `---`), since the CLI would change it (REN-1250).
+ */
+export function vercelProjectName(root) {
+    const name = basename(root);
+    return /^[a-z0-9._-]{1,100}$/.test(name) && !name.includes('---') ? name : undefined;
+}
 /**
  * A host's CLI that is not on this machine (#396), asked before anything installs it: the package, the version and the
  * global install with npm. There is no Skip, since the host's setup cannot go on without its CLI: Esc is the person's own install.
@@ -137,6 +157,25 @@ export const HOST_SCREENS = {
     ...buildWait('render', 'Render', 'set Pull Request Previews to Automatic under the service\'s Previews settings'),
     ...previewsOff('netlify', 'Netlify', 'turn Deploy Previews on under Branches and deploy contexts → Configure'),
     ...previewsOff('cloudflare', 'Cloudflare', 'set Preview branch control to All non-Production branches under Builds & deployments'),
+    // Vercel builds the pushes and the pull requests, but with deployment_status Events off it tells GitHub nothing of them, and GitHub's record is where Impeccable finds them (REN-1248): the one consent to turning it on as the person, for a project this run did not create (the tool names the project in the prompt).
+    'vercel-previews': {
+        id: 'vercel-previews',
+        kind: 'confirm',
+        title: 'Vercel, but GitHub never hears of the previews',
+        hint: "Vercel builds this repository's pull requests, but the project's deployment_status Events setting is off, so GitHub gets no record of the previews, and that record is where Impeccable finds them. The run turns it on as you; nothing else on the project changes.",
+        prompt: 'Turn on deployment_status Events?',
+        confirmLabel: 'Turn on',
+        skipLabel: 'Skip',
+    },
+    'vercel-previews-retry': {
+        id: 'vercel-previews-retry',
+        kind: 'confirm',
+        title: 'Vercel, but GitHub never hears of the previews',
+        hint: 'deployment_status Events is still off. On the page that opened, turn it on under Git.',
+        prompt: 'Changed it?',
+        confirmLabel: 'Try again',
+        skipLabel: 'Skip',
+    },
     // Render's consent is its one screen (renderConfirm): only the retry is its own.
     'render-previews-retry': previewsOff('render', 'Render', "set Pull Request Previews to Automatic under the service's Previews settings")['render-previews-retry'],
     // No Pages project builds the repository's pull requests: the one consent to connecting the repository to the project the checkout names, or to creating one for it where Cloudflare builds a Worker instead (the tool names the project in the prompt), and the sign-in cf needs for either.

package/dist/hosted.js

@@ -15,6 +15,24 @@ const execFileAsync = promisify(execFile);
 /** How many deployments, and how many pull requests, the evidence reads: the newest. */
 const LIMIT = 20;
 const STATES = ['error', 'failure', 'inactive', 'in_progress', 'queued', 'pending', 'success'];
+/** Vercel's commit statuses on a commit, the newest of each context its bot posted. */
+function vercelStatusesOf(statuses, sha) {
+    const newest = new Map();
+    // GitHub lists a commit's statuses newest first.
+    for (const s of statuses.map(record)) {
+        const context = s?.context;
+        if (typeof context !== 'string' || !/^Vercel(?: – [A-Za-z0-9._-]{1,100})?$/.test(context) || record(s.creator)?.login !== 'vercel[bot]' || newest.has(context))
+            continue;
+        const said = typeof s.description === 'string' ? s.description.trim() : '';
+        // As pristine reads them: a skip says so ("Skipped", "Canceled by Ignored Build Step"); any other success is a completed build.
+        const state = s.state === 'pending' ? 'building' : s.state === 'failure' || s.state === 'error' ? 'failed' : s.state === 'success' && /^(Skipped|Canceled by Ignored Build Step)\b/i.test(said) ? 'skipped' : s.state === 'success' ? 'built' : null;
+        if (!state)
+            continue;
+        const target = typeof s.target_url === 'string' && /^https:\/\/vercel\.com\/[^\s?#]{1,300}$/.test(s.target_url) ? s.target_url : null;
+        newest.set(context, { sha, context, state, targetUrl: target });
+    }
+    return [...newest.values()];
+}
 const record = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined);
 const positive = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
 /** An https address without credentials, a query or a fragment, as origin and path; null for anything else. */
@@ -40,11 +58,11 @@ export async function readHostedPreviews(owner, repo, deps = {}) {
     const runGh = deps.runGh ?? (async (args) => (await execFileAsync('gh', args, {
         encoding: 'utf8', timeout: 30_000, maxBuffer: 2 * 1024 * 1024, signal: deps.signal, env: { ...process.env, GH_PROMPT_DISABLED: '1' },
     })).stdout);
-    const list = async (route) => {
+    const list = async (route, limit = LIMIT) => {
         const data = JSON.parse(await runGh(['api', '--hostname', 'github.com', '--method', 'GET', route]));
         if (!Array.isArray(data))
             throw new Error(`${route} is not a list`);
-        return data.slice(0, LIMIT);
+        return data.slice(0, limit);
     };
     const base = `/repos/${owner}/${repo}`;
     try {
@@ -75,7 +93,10 @@ export async function readHostedPreviews(owner, repo, deps = {}) {
                 pullRequests = numbers(await list(`${base}/commits/${d.sha}/pulls`).catch(() => ((unsaid = true), [])));
             return { sha: d.sha, environment, state, url, vercel: record(d.creator)?.login === 'vercel[bot]', pullRequests };
         }));
-        return { deployments: read.filter((d) => d !== null), ...(unsaid ? { error: 'GitHub could not say which pull requests some previews belong to: read again.' } : {}) };
+        const kept = read.filter((d) => d !== null);
+        // A project with its deployments on GitHub turned off still posts its commit status: read for every branch, since another project's deployment of the head says nothing of this one's, and the wait keeps the project's own.
+        const statuses = typeof head === 'string' ? vercelStatusesOf(await list(`${base}/commits/${head}/statuses?per_page=100`, 100).catch(() => []), head) : [];
+        return { deployments: kept, ...(statuses.length ? { vercelStatuses: statuses } : {}), ...(unsaid ? { error: 'GitHub could not say which pull requests some previews belong to: read again.' } : {}) };
     }
     catch {
         return unread;

package/dist/main.js

@@ -13,7 +13,7 @@ import { copyText, letTabsHear, openBrowser, progressPage, screenPrompt, setupAu
 import { checkoutJournal } from './leftovers.js';
 import { createLog, UserError } from './log.js';
 import { firstMessage, playbook, setupContext } from './playbook.js';
-import { backToStartBranch, checkoutFrontEnd, currentBranch, onOrigin, parseFlags, readCheckout, skipWorkingFolderForCommands, stateSaysNoFrontEnd, USAGE } from './preflight.js';
+import { backToStartBranch, checkoutFrontEnd, currentBranch, dropEmptyRunBranches, localBranches, onOrigin, parseFlags, readCheckout, skipWorkingFolderForCommands, stateSaysNoFrontEnd, USAGE } from './preflight.js';
 import { startSandbox } from './sandbox.js';
 import { scanRecorder } from './scan.js';
 import { createReporter, reportingOff } from './report.js';
@@ -129,12 +129,16 @@ export async function main(argv) {
         const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
         const slug = `${checkout.owner}/${checkout.repo}`;
         const startBranch = currentBranch(checkout.root);
+        // The branches the person had, which the end never removes (REN-1245).
+        const startBranches = localBranches(checkout.root);
         // What the run's write and edit tools change, from before the agent's first step: the end takes back what no commit carries (#421).
         const journal = checkoutJournal(checkout.root);
         backToStart = () => {
             const kept = journal.undo();
             const branch = backToStartBranch(checkout.root, startBranch);
-            return [...kept, ...(branch ? [branch] : []), ...journal.appeared(startBranch)];
+            // A branch the run made and left empty goes too, whoever took the checkout back to its branch.
+            const empty = dropEmptyRunBranches(checkout.root, startBranch, startBranches);
+            return [...kept, ...(branch ? [branch] : []), ...empty, ...journal.appeared(startBranch)];
         };
         // From the checkout's top, where the sandbox lays its own protections of a checkout.
         process.chdir(checkout.root);
@@ -317,6 +321,9 @@ export async function main(argv) {
                 const end = ending(report);
                 // The person's no left no app with a preview Impeccable can open: the screen says why alone, with Close, and the report follows it here (#413).
                 const ended = Boolean(report.ended);
+                // The run's own words for why stay off that screen, here and in the report (REN-1245).
+                if (ended && report.reason)
+                    log.write('setup ended', { reason: report.reason });
                 // One pull request a screen, each opened in the browser as its screen appears: the test drive (each app's, on a repository with several), then the setup pull request. Only the last of them goes on the clipboard, which would keep no other (#418); the others offer Copy link [C].
                 const hand = { open: openBrowser, copy: copyText };
                 const last = !ended && setupPr ? -1 : (drives?.length ?? 1) - 1;

package/dist/playbook/cases/vercel-previews.md

@@ -14,7 +14,8 @@ It applies as well **before the first pull request**: Vercel deploys the reposit
 - **The live app**: with the checkout linked to the project (`.vercel/project.json`) and a production deployment of it on GitHub's record, the evidence answers the project's own domain as `production`; live-app-address says how it becomes the before, in step 2's write. Unlinked, GitHub's record names no address of it that is open.
 - **The aim** holds here: the CLI does the work, and the person is asked only what the playbook's aim allows.
 - **Behind Vercel's login** (`gate: "vercel-protection"`): Deployment Protection stands in front of the previews. Get past it as preview-protection says, which proves the preview, and go on with step 2; when nothing got past it, that case says how the run ends.
-- **`pullRequestPreviews` in impeccable_hosted_previews' answer**: what vercel.json and the linked project say of the test drive's branch, read with the evidence and never changed by the run, since the setting is the repository's own or has no command (impeccable_enable_previews takes no Vercel). `enabled: false` (`git.deploymentEnabled` in vercel.json turns the branch off, or Vercel records no deployments on GitHub, where Impeccable finds its previews): push no test drive on Vercel. Set the preview up as server-previews says, and say in one line under "What was skipped, and why" that Vercel builds no preview of the pull requests, with the `reason`, and the exact change for the person: the vercel.json rule to lift, or Vercel GitHub deployments under the project's Settings → Git. `enabled: 'unknown'` (an Ignored Build Step decides commit by commit, or the CLI could not read the project): go on, and say so in one line under "What is not verified".
+- **`pullRequestPreviews` in impeccable_hosted_previews' answer**: what vercel.json and the linked project say of the test drive's branch, read with the evidence. `enabled: false` from vercel.json (`git.deploymentEnabled` turns the branch off, the repository's own setting): push no test drive on Vercel. Set the preview up as server-previews says, and say in one line under "What was skipped, and why" that Vercel builds no preview of the pull requests, with the `reason` and the vercel.json rule to lift. `enabled: false` with `cause: "previews"` (deployment_status Events off: Vercel builds the pushes but records no deployment on GitHub, where Impeccable finds its previews): before the test drive's push, impeccable_enable_previews (`host: "vercel"`) asks the person on one screen and turns it on. `enabled`, go on; `skipped` is a no that ends the setup, as the playbook says; `refused`, go on, since the wait finds Vercel's build by its commit status, and put "Turn on deployment_status Events under the Vercel project's Settings → Git" in `left`. `enabled: 'unknown'` (an Ignored Build Step decides commit by commit, or the CLI could not read the project): go on, and say so in one line under "What is not verified".
+- **`githubDeployments: false` in the answer of the wait for a pushed branch**: as vercel-setup's "No preview for the pushed test drive" says.
 - **Another app, or no answer from any of the three**: Vercel's previews do not show this app. Set the preview up as server-previews says instead, and say under "What is not verified" what the Vercel address answered.
 - **The pull requests**: no setup pull request; the test drive branches from the default branch, and Vercel builds its preview from the push, which pull-requests' step 4 waits for and proves the test drive's page on before the pull request opens. In place of pull-requests' step 3, build the test drive branch once with the install and build Vercel runs (`vercel.json`'s `installCommand` and `buildCommand`, else the package's), as plain commands (`pnpm install`, then `pnpm run build`) and not with impeccable_verify_preview, which is for a preview Impeccable starts itself, so a page that does not build is never pushed.
 - The evidence is GitHub's: link, deploy and change nothing on Vercel, and save no address pattern, since Vercel reports each preview's address to GitHub itself.

package/dist/playbook/cases/vercel-setup.md

@@ -11,7 +11,7 @@ The checkout is set up for Vercel (`vercel.json`, `.vercel/project.json`, a `ver
    - **Skip**: a no that ends the setup, as the playbook says: say under "What was skipped, and why" that Vercel was found and the sign-in was skipped. The steps below do not apply.
 2. **Create the project, then link it** (run each Vercel command plain, on its own: its answer is short, a pipe to `tail` is refused, and a command chained after it leaves the project unrecorded): `vercel project add <the folder's name> --team <the team>` creates the project in that team, under the name `vercel link` gives a project (the checkout folder's name, lowercase); then `vercel link --yes --team <the team>`, in the checkout's root (never with `--cwd` or after a `cd`), links the folder to the project of that name, which is now the run's. The CLI names no team on its own without a terminal, so the option is given whenever there is a team. Done when the link prints the linked project.
    - **`vercel project add` fails** (the name is in use: the project is the person's, not this run's): run no link; the Vercel setup ends there, and with the checkout linked to no project its CLI stops and the hold on pushes goes. Go on as "A step fails before the test drive is pushed" says, naming the project under "What was skipped, and why". When `.vercel/project.json` was in the checkout before the run, that link is not this run's, and the hold on pushes stays, by design: no test drive, as "No preview for the pushed test drive" says, and the report says under "What was skipped, and why" that the person removes `.vercel/project.json` or links the project themselves and runs the setup again.
-3. **Connect the repository, and lock the project before its first deployment**, with impeccable_vercel_connect: it runs the connection on the linked project, when that project is the one step 2 created or one connected to this repository already, asks the person for Vercel's GitHub app's access when the app cannot reach the repository, and then, on a project with no production deployment, puts Vercel's login in front of every address of the project, its own included. Vercel makes a new project's first deployment Production whatever branch it builds and serves it at the project's own address, and the test drive's push is that first deployment. When Vercel refuses the lock, the tool asks the person on one screen to turn it on in the project's settings and waits for it. Done when it answered `connected: true` with `production: "exists"` or `locked: true`; a project connected by the link already is, and it says so.
+3. **Connect the repository, and lock the project before its first deployment**, with impeccable_vercel_connect: it runs the connection on the linked project, when that project is the one step 2 created or one connected to this repository already, asks the person for Vercel's GitHub app's access when the app cannot reach the repository, and then, on a project with no production deployment, puts Vercel's login in front of every address of the project, its own included. Vercel makes a new project's first deployment Production whatever branch it builds and serves it at the project's own address, and the test drive's push is that first deployment. When Vercel refuses the lock, the tool asks the person on one screen to turn it on in the project's settings and waits for it. It also turns on the project's deployment_status Events where it is off: Vercel records its deployments on GitHub only with it on, a project the CLI creates starts with it off, and GitHub's record is where the wait finds the test drive's preview. The tool turns it on at once for the project step 2 created, and after one screen for any other (`deploymentEvents` in the answer). Done when it answered `connected: true` with `production: "exists"` or `locked: true`, and no `deploymentEvents` skipped; a project connected by the link already is, and it says so.
 4. **Build and push the test drive** (the Test drive task) as pull-requests' steps 2 to 4 say (on a repository with several apps, where the run sets up more than one, that app's own test drive, on `impeccable/test-drive-<appKey>` with its page in that app alone, as the monorepo case's step 6 says), with the changes vercel-previews' reference gives: from the default branch, no setup pull request, built once with plain commands. Stage the new page and the page that links to it by name: `vercel link` writes `.vercel/` and a `.env.local` that holds a Vercel token, and may add `.vercel` to `.gitignore`, and none of that goes into the pull request. Its push starts the project's first deployment. Done when `git push -u origin impeccable/test-drive` (the app's own branch, where it has one) succeeded.
 5. **Its preview, proven and saved, then its pull request** as pull-requests' step 4 (Vercel) and step 5 say: the wait for the pushed head's deployment, the test drive's page proven on the address it lists (past Vercel's login as preview-protection says), impeccable_write to `preview` as vercel-previews' step 2 says, then the pull request and its recording. The playbook's step 6 then has no pull request left to open: go on with the playbook's step 4. Done when impeccable_test_pr answered "Recorded".
 
@@ -20,13 +20,15 @@ The checkout is set up for Vercel (`vercel.json`, `.vercel/project.json`, a `ver
 - **The live app**: a project created here has none yet, which the report says; one that deploys production already (`production: "exists"`) answers its address as `productionUrl`, and live-app-address says how it becomes the before.
 - **The aim** holds here: the CLI does the work, and the person is asked only what the playbook's aim allows.
 - **A step fails before the test drive is pushed** (the sign-in not completed, the project not created, the repository not connected, or step 3 answering that the linked project is not this run's: `vercel link` linked one of the person's projects, named like the folder, which is left as it is): the Vercel setup ends there. Set the preview up as server-previews says, say under "What was skipped, and why" what stopped it, and put the person's step in `left` when there is one, such as "Give Vercel's GitHub app access to the repository", with the `access` page in the report. The sign-in, the team or the GitHub app's access skipped is a no that ends the setup, as the playbook says.
-- **`pullRequestPreviews` in impeccable_hosted_previews' answer**: what vercel.json and the linked project say of the test drive's branch, read with the evidence and never changed by the run, since the setting is the repository's own or has no command (impeccable_enable_previews takes no Vercel). `enabled: false` (`git.deploymentEnabled` in vercel.json turns the branch off, or Vercel records no deployments on GitHub, where Impeccable finds its previews): the Vercel setup ends before step 4, as "A step fails before the test drive is pushed" says, and say in one line under "What was skipped, and why" that Vercel builds no preview of the pull requests, with the `reason`, and the exact change for the person: the vercel.json rule to lift, or Vercel GitHub deployments under the project's Settings → Git. `enabled: 'unknown'` (an Ignored Build Step decides commit by commit, or the CLI could not read the project): go on, and say so in one line under "What is not verified".
+- **`pullRequestPreviews` in impeccable_hosted_previews' answer**: what vercel.json and the linked project say of the test drive's branch, read with the evidence. `enabled: false` from vercel.json (`git.deploymentEnabled` turns the branch off, the repository's own setting): the Vercel setup ends before step 4, as "A step fails before the test drive is pushed" says, and say in one line under "What was skipped, and why" that Vercel builds no preview of the pull requests, with the `reason` and the vercel.json rule to lift. `enabled: false` with `cause: "previews"` (deployment_status Events off) is step 3's to turn on. `enabled: 'unknown'` (an Ignored Build Step decides commit by commit, or the CLI could not read the project): go on, and say so in one line under "What is not verified".
+- **`deploymentEvents` from step 3**: `enabled`, go on. `skipped` is a no that ends the setup, as the playbook says: push nothing. `refused` (Vercel kept the run and the person from changing it): go on with step 4, since the wait finds Vercel's build by its commit status, and put "Turn on deployment_status Events under the Vercel project's Settings → Git" in `left`, since Impeccable's reviews find each later preview on GitHub's record.
 - **A push before step 3** is refused, since a connected project builds every push: run impeccable_vercel_connect first.
 - **On a repository with several apps**, the project step 2 creates builds the repository's root: impeccable_vercel_connect connects and locks it only where an app this run sets up is the root's, and otherwise answers so, and the Vercel setup ends there for that app, as "A step fails before the test drive is pushed" says.
 - **`locked: false`** from step 3, with `production` not "exists" (the person skipped the tool's screen, or the lock was still off after its retries): push nothing, and set up no other preview either, since the connected project would build that push as its first deployment, public at its own address. Mark the Test drive task failed, and say under "What was skipped, and why" what stopped the lock (the answer's `reason`). The screen skipped is a no that ends the setup, as the playbook says.
 - **No preview for the pushed test drive**: save no method, set up no other preview and open no pull request, as pull-requests' "No preview, no test drive" says; the project and the connection stay, and the report names them.
   - **The build failed** (`state` is `failure` or `error`): `vercel deploy --yes` builds this checkout on Vercel and prints why it failed. When the cause is in the test drive's own change, correct it, commit, push once more and wait for that build; else the report names the cause.
-  - **No deployment within five minutes**: the wait's own screen opens the project's Git settings and waits again on the person's yes. When they skip it, or none came after its retries, say under "What is not verified" that Vercel built no push here, and that the project's Git connection is the thing to check.
+  - **No deployment within five minutes**: the wait's own screen opens the project's Git settings and waits again on the person's yes. When they skip it, or none came after its retries, that is the end of the wait (a second call reads once and waits no more): say under "What is not verified" that Vercel built no push here, and that the project's Git connection is the thing to check.
+  - **`githubDeployments: false` in the wait's answer**: Vercel's commit status on the head settled it, and GitHub records no deployment of it; `reason` says, in Vercel's words, whether it built, failed or skipped the branch. A deployment listed is the test drive's build: prove it as usual. Whatever came of it, the report's reason and `left` say what Vercel did and name deployment_status Events under the project's Settings → Git as the one change, and say Vercel built the branch whenever `reason` does. "No preview was built" is the wording of a branch with no deployment and no commit status of Vercel's.
   - **Behind Vercel's login** (`gate: "vercel-protection"`) with nothing getting past it: preview-protection says what the report names.
 - **The first deployment** of a new project is called Production, whatever branch it builds. Locked in step 3, and still so when its deployment is read, it is the test drive's preview: impeccable_hosted_previews lists it, and the proof opens it past Vercel's login as preview-protection says. Unlocked by then, or another project's, the evidence lists no address for it and the proof refuses it: no test drive, as "No preview for the pushed test drive" says, and the report says under "What is not verified" that Vercel serves the test drive's build at the project's own address (`vercel project ls` prints it) without a login until the default branch deploys, and that Vercel Authentication for All Deployments, under the project's Settings → Deployment Protection, puts its login back in front. A project that deployed production before the run (`production: "exists"`) builds the push as a Preview, and keeps its addresses as they were.
 - **Behind Vercel's login** (`gate: "vercel-protection"`): a project the CLI creates starts with Vercel Authentication on, and step 3 locks it at every address, so expect it, and go on as the preview-protection case says.

package/dist/preflight.js

@@ -1,5 +1,5 @@
 import { execFileSync } from 'node:child_process';
-import { closeSync, constants, existsSync, fstatSync, openSync, readFileSync, statSync } from 'node:fs';
+import { closeSync, constants, existsSync, fstatSync, openSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { folderOf } from './host-previews.js';
@@ -314,22 +314,100 @@ export function currentBranch(root) {
         return '';
     }
 }
+/** A branch the run makes its pull requests on: impeccable/setup, impeccable/test-drive or an app's impeccable/test-drive-<app key>, with -2, -3 where an earlier run took it. */
+const RUN_BRANCH = /^impeccable\/(?:setup(?:-\d+)?|test-drive(?:-[A-Za-z0-9][A-Za-z0-9._-]*)?)$/;
+/** The checkout's local branches; null when git cannot say. */
+export function localBranches(root) {
+    try {
+        return new Set(execFileSync('git', ['for-each-ref', '--format=%(refname:short)', 'refs/heads'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000, env: gitEnvironment() }).split('\n').filter(Boolean));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Once the checkout is back on `start`: each of the run's branches that was not in the checkout at its start (`before`),
+ * is on no remote, and holds no commit of its own (its tip is `start`'s), as a branch made before a no that ended the
+ * setup is (REN-1245), is removed, so the checkout ends as it started. A branch the person had is never touched: with
+ * `before` unread (null), none is removed. The done screen's lines for the ones git would not remove.
+ */
+export function dropEmptyRunBranches(root, start, before) {
+    if (!before || !start || currentBranch(root) !== start)
+        return [];
+    const git = (args) => execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000, env: gitEnvironment() }).trim();
+    const lines = [];
+    let tip;
+    try {
+        tip = git(['rev-parse', '--verify', '-q', `refs/heads/${start}`]);
+    }
+    catch {
+        return [];
+    }
+    for (const branch of localBranches(root) ?? []) {
+        if (before.has(branch) || !RUN_BRANCH.test(branch) || onOrigin(root, branch))
+            continue;
+        try {
+            if (git(['rev-parse', '--verify', '-q', `refs/heads/${branch}`]) !== tip)
+                continue;
+            // -d, never -D: git removes it only as merged into the checkout's branch.
+            git(['branch', '-d', branch]);
+        }
+        catch {
+            lines.push(`${branch}, a branch the setup made, is still in your checkout: git branch -d ${branch} removes it.`);
+        }
+    }
+    return lines;
+}
+/** What `vercel link` appends to the root .gitignore: each of its lines the file lacks, after a line break where the file ended without one. */
+const LINK_LINES = /^(?:\r?\n)?(?:(?:\.vercel|\.env\*)\r?\n)+$/;
+/**
+ * The root .gitignore taken back to the start branch's (`HEAD`, nothing staged) where all that changed is the lines
+ * `vercel link` appends, and only where git then shows no untracked file it hides now: a start branch that does not
+ * ignore the link's token file, .env.local, keeps the lines. Any other change is the person's, and stays (REN-1250).
+ * Whether it was taken back.
+ */
+function restoreLinkLines(root, git) {
+    const path = join(root, '.gitignore');
+    const now = readFileSync(path, 'utf8');
+    const before = git(['cat-file', 'blob', 'HEAD:.gitignore']);
+    if (git(['cat-file', 'blob', ':.gitignore']) !== before || !now.startsWith(before) || !LINK_LINES.test(now.slice(before.length)))
+        return false;
+    // File by file, so a file the lines hide inside a folder git shows already counts too.
+    const shown = () => git(['status', '--porcelain=v1', '-z', '--untracked-files=all']).split('\0').filter((line) => line.startsWith('?? '));
+    const visible = new Set(shown());
+    writeFileSync(path, before);
+    let restored = false;
+    try {
+        restored = shown().every((line) => visible.has(line));
+    }
+    finally {
+        // Whatever stopped the check, the link's lines go back, so nothing they hide is shown to git add.
+        if (!restored)
+            writeFileSync(path, now);
+    }
+    return restored;
+}
 /**
  * The run makes its pull requests on branches of its own, and git leaves the checkout on the last it made: the end goes back
  * to the branch the run started on (`start`), so what the person commits next does not land on the test drive. Only from one
- * of the run's branches, and only with no change to a tracked file, which would go along; git refuses where an untracked
- * file would be overwritten. The run's own files no commit carries are taken back before this (checkoutJournal). Null when the checkout is back, or never left; else the line the done screen shows.
+ * of the run's branches, and only with no change to a tracked file, which would go along, but to a .gitignore the two
+ * branches hold alike, which goes along named, or goes back where it holds only `vercel link`'s lines (restoreLinkLines);
+ * git refuses where an untracked file would be overwritten. The run's own files no commit carries are taken back before
+ * this (checkoutJournal). Null when the checkout is back with nothing carried, or never left; else the line the done
+ * screen shows.
  */
 export function backToStartBranch(root, start) {
     const now = currentBranch(root);
-    if (now === start || !/^impeccable\/(?:setup(?:-\d+)?|test-drive(?:-[A-Za-z0-9][A-Za-z0-9._-]*)?)$/.test(now))
+    if (now === start || !RUN_BRANCH.test(now))
         return null;
     if (!start)
         return `Your checkout is on ${now}, the branch the setup made.`;
     const git = (args, input) => execFileSync('git', args, { cwd: root, encoding: 'utf8', input, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'ignore'], timeout: 10_000, maxBuffer: 64 * 1024 * 1024, env: gitEnvironment() });
     try {
         // A content filter is a program git runs outside the sandbox as it reads or writes a file, from settings that may name a script in the checkout a sandboxed command could have changed: a checkout with any file a filter takes, here or on the start branch, is left to the person. Neither read runs one.
-        const paths = [...new Set([...git(['ls-files', '-z']).split('\0'), ...git(['diff', '--name-only', '-z', '--no-ext-diff', '--no-textconv', 'HEAD', start, '--']).split('\0')].filter(Boolean))].map((path) => `${path}\0`).join('');
+        // The files the run's branch and the start branch hold differently.
+        const differ = git(['diff', '--name-only', '-z', '--no-ext-diff', '--no-textconv', 'HEAD', start, '--']).split('\0').filter(Boolean);
+        const paths = [...new Set([...git(['ls-files', '-z']).split('\0'), ...differ].filter(Boolean))].map((path) => `${path}\0`).join('');
         const listed = git(['check-attr', '--stdin', '-z', 'filter'], paths).split('\0');
         // path, attribute, value, ...
         for (let i = 2; i < listed.length; i += 3)
@@ -341,12 +419,23 @@ export function backToStartBranch(root, start) {
             throw new Error('a content filter on the start branch');
         // Named, so the done screen says which files keep the checkout here (#421).
         const changed = git(['status', '--porcelain=v1', '-z', '--untracked-files=no', '--no-renames']).split('\0').filter(Boolean).map((line) => line.slice(3));
-        if (changed.length)
-            return `Your checkout is still on ${now}, since ${listPaths(changed)} changed there: git checkout ${start} takes it back to the branch you started on.`;
+        // A .gitignore both branches hold alike, which a host's link changed (vercel link adds .vercel and .env*, before the test drive's branch is made), goes along to the start branch, where the root's goes back as it was when the link's lines are all that changed and hide nothing the start branch's lines do not; else it stays as it is, named (REN-1250), since taking the lines back would show the link's token file, .env.local, to git add. Any other change keeps the checkout here.
+        const carried = changed.filter((path) => (path === '.gitignore' || path.endsWith('/.gitignore')) && !differ.includes(path));
+        const held = changed.filter((path) => !carried.includes(path));
+        if (held.length)
+            return `Your checkout is still on ${now}, since ${listPaths(held)} changed there: git checkout ${start} takes it back to the branch you started on.`;
         // The closing -- makes git read the name as the branch, never as a path.
         // An ignored file of the person's where the start branch tracks a file of that name stops the checkout, rather than being overwritten.
         git(['-c', 'submodule.recurse=false', 'checkout', '-q', '--no-overwrite-ignore', start, '--']);
-        return null;
+        let restored = false;
+        try {
+            restored = carried.includes('.gitignore') && restoreLinkLines(root, git);
+        }
+        catch {
+            // Left as it is, and named.
+        }
+        const left = restored ? carried.filter((path) => path !== '.gitignore') : carried;
+        return left.length ? `${listPaths(left)} changed during the setup, from a command it ran or from you, and ${left.length === 1 ? 'stays' : 'stay'} uncommitted on ${start} as ${left.length === 1 ? 'it is' : 'they are'}.` : null;
     }
     catch {
         return `Your checkout is still on ${now}: git checkout ${start} takes it back to the branch you started on.`;

package/dist/tools.js

@@ -10,7 +10,7 @@ import { defineTool } from '@earendil-works/pi-coding-agent';
 import { agreeToCliInstall, agreeToHostSetup, bindPreviewPullRequest, chooseHostTeam, chosenHostTeam, classifyPreviewCommand, endAppSetup, endHostSetup, HOST_CLI_VERSIONS, hostCliInstallArgs, hostCliInstallCommand, hostSetupAgreed, isSecretFile, linkedByRun, observePreviewAttempts, parseCommand, previewRetryState, settleVercelFirstDeployment, vercelProjectsAdded } from './fence.js';
 import { requestJson } from './http.js';
 import { appsLeftOut, focusCheckup, focusInstructions, focusState, severalApps } from './focus.js';
-import { APPS_QUESTION, cliInstallScreen, cliManualScreen, cloudflareAccessConsent, cloudflareAccessPaste, cloudflareAccessReusable, HOST_QUESTIONS, HOST_SCREENS, HOST_SIGNED_IN, namedAppQuestion, NETLIFY_PASSWORD_WHERE, netlifyPasswordReplace, renderConfirm, sentTo, startedIn, vercelBypassConsent, vercelBypassPaste } from './host-questions.js';
+import { APPS_QUESTION, cliInstallScreen, cliManualScreen, cloudflareAccessConsent, cloudflareAccessPaste, cloudflareAccessReusable, HOST_QUESTIONS, HOST_SCREENS, HOST_SIGNED_IN, namedAppQuestion, NETLIFY_PASSWORD_WHERE, netlifyPasswordReplace, renderConfirm, sentTo, startedIn, vercelBypassConsent, vercelBypassPaste, vercelProjectName, vercelSignedIn } from './host-questions.js';
 import { enableNetlifyPreviews, folderOf } from './host-previews.js';
 import { checkoutNames, liveShaped, netlifySiteOf, previewHostName, provePreview, readHostedPreviews, readmeNamesApp, renderSiteOf, vercelDeploymentOf } from './hosted.js';
 import { closedPulls, deploymentsOf, hostingApp, hostingRead, liveHostOf, renderSitesOf } from './hosting.js';
@@ -19,7 +19,7 @@ import { cloudflareFromHosting, cfRunner, cfStatus, CLOUDFLARE_APP_PAGE, connect
 import { passCloudflareAccess, TOKEN_NAME } from './cloudflare-access.js';
 import { netlifyFromHosting, commandRunner, connectNetlifySite, liveSite, netlifyStatus, netlifyTeams, readNetlifyPreviews, waitForNetlifyAccess } from './netlify.js';
 import { netlifyToken, passNetlifyLock, setSitePassword } from './netlify-password.js';
-import { connectVercelProject, lockedDeploymentHosts, prepareFirstDeployment, projectMadeDeployment, readLinkedProject, readOwnProject, vercelDashboardScope, vercelPreviewsFact, vercelProjectFor, vercelProjectPage, vercelRepoProject, vercelStatus, vercelTeams, waitForVercelAccess, waitForVercelLock } from './vercel.js';
+import { connectVercelProject, DEPLOYMENT_EVENTS, DEPLOYMENTS_OFF, deploymentOfStatus, enableGithubDeployments, lockedDeploymentHosts, prepareFirstDeployment, projectMadeDeployment, readLinkedProject, readOwnProject, vercelDashboardScope, vercelPreviewsFact, vercelProjectFor, vercelProjectPage, vercelRepoProject, vercelStatus, vercelTeams, waitForVercelAccess, waitForVercelLock } from './vercel.js';
 import { BYPASS_HEADER, passVercelLogin, readLink } from './vercel-bypass.js';
 import { fitsTask, stagesOf, workStarted } from './stages.js';
 import { commandLine, redact } from './log.js';
@@ -165,10 +165,11 @@ function stageError(status, tasks) {
 }
 /** The line under the last screen's heading, about the pull request that screen ends on: the setup pull request when there is one, else the test drive; and, where a host builds the previews and so no setup pull request was needed, one line saying so. Without a test drive, what stopped it, from what the run saved and met (#321). */
 export function resultLine(report) {
+    // A setup the person's no ended shows its own line alone: the run's words for why stay in the report (#413, REN-1245).
+    if (report.ended)
+        return SETUP_ENDS[report.ended].line;
     // The run's own words for why no method was saved, where it gave them (REN-1108).
     const why = report.reason && !report.methodSaved ? ` Why: ${report.reason.replace(/[.\s]+$/, '')}.` : '';
-    if (report.ended)
-        return `${SETUP_ENDS[report.ended].line}${why}`;
     const lead = report.walled ? `Impeccable's own check of the preview met a wall (${report.walled}), so the test drive's review can't see its pages yet. The report, printed here when this screen closes, says what the run found.`
         : !report.testPr ? `${report.unhonoured ?? noTestDrive(report)}${why} The report, printed here when this screen closes, says what the run found.` : report.setupPr ? 'The setup pull request adds the workflow that lets Impeccable run on your previews. Merge it when you are ready.' : SEE_THE_REVIEW;
     // --signed-in-test-drive left an app without a test drive: said beside another app's drive or a wall too (#410).
@@ -282,7 +283,7 @@ const REPORT = {
             description: `What waits on the person besides merging the setup pull request and closing the test drive: one line each, at most ${STATUS_MAX} characters, such as "Add the admin test account on the setup page". The terminal counts them. Leave it out when nothing does.`,
             items: { type: 'string', minLength: 1 },
         },
-        reason: { type: 'string', minLength: 1, description: 'On a repository of one app where no preview method was saved: why, in plain words of at most 200 characters, such as "Render\'s pull request previews are off, and the person skipped turning them on". The last screen shows it. Names only, never an address or a key.' },
+        reason: { type: 'string', minLength: 1, description: 'On a repository of one app where no preview method was saved: why, in plain words of at most 200 characters, such as "Render\'s pull request previews are off, and the person skipped turning them on". The last screen shows it, unless the person\'s no ended the setup. Names only, never an address or a key.' },
         apps: {
             type: 'array',
             description: 'On a repository with several apps: for each picked app whose preview was not proven or keyed, why, in plain words of at most 200 characters, such as "not checked: the person stopped after the first app". The last screen shows it on that app\'s line. Names only, never an address or a key.',
@@ -406,6 +407,19 @@ const namesCredential = (q) => {
     const text = [q.title, q.prompt, q.hint].filter(Boolean).join('\n');
     return CREDENTIAL.test(text) || CREDENTIAL.test(text.replace(/_|(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/g, ' '));
 };
+/** What Vercel's commit statuses on a pushed branch's head say, where GitHub records no deployment of Vercel's for it (REN-1249): the cause in Vercel's own words; none while it is still building. */
+function statusReason(branch, statuses, listed) {
+    const said = (state) => statuses.some((s) => s.state === state);
+    if (said('built'))
+        return listed
+            ? `Vercel built ${branch}; the deployment its commit status names is listed, as Vercel reads it. ${DEPLOYMENTS_OFF}`
+            : `Vercel built ${branch}, as its commit status says, but the Vercel CLI could not read which deployment that was, so it has no address here. ${DEPLOYMENTS_OFF}`;
+    if (said('failed'))
+        return `Vercel's build of ${branch} failed, as its commit status says. ${DEPLOYMENTS_OFF}`;
+    if (said('skipped'))
+        return `Vercel skipped ${branch}, as its commit status says: an Ignored Build Step or a branch rule kept it from building.`;
+    return undefined;
+}
 /** Under the field of every text question typed in the open, where the model reads the answer. */
 const NEVER_A_CREDENTIAL = 'Never enter a password, a token or a key here.';
 /** The app a screen is for, on a repository with several apps: the person's no on it ends the setup for that app alone (#413). */
@@ -414,7 +428,7 @@ const ENABLE_PREVIEWS = {
     type: 'object',
     additionalProperties: false,
     required: ['host'],
-    properties: { host: { type: 'string', enum: ['netlify', 'cloudflare'], description: "The host whose pullRequestPreviews said enabled false in this run." }, appKey: FOR_APP },
+    properties: { host: { type: 'string', enum: ['netlify', 'cloudflare', 'vercel'], description: "The host whose pullRequestPreviews said enabled false in this run." }, appKey: FOR_APP },
 };
 const CLOUDFLARE_CONNECT = {
     type: 'object',
@@ -439,6 +453,9 @@ const ASKS_ADDRESS = /\b(urls?|domains?|(web|site|live|production|preview|app's)
 /** What schemaError cannot say about a question: options belong to single and multi, at least two, each value once, and each other field to its kinds. */
 function askError(q) {
     const values = (q.options ?? []).map((o) => o.value);
+    // A prompt the person cannot read as a question, such as "x", never reaches the screen, where Skip would read as their no (REN-1255).
+    if ((q.prompt.match(/\p{L}[\p{L}\p{N}'’-]*/gu) ?? []).length < 2)
+        return `input.prompt ${JSON.stringify(q.prompt.trim())} is not a question the person can answer, so nothing was shown. Ask only when the run needs the person's answer, with a prompt that says what they answer or agree to; with nothing to ask, go on`;
     if (q.sensitive && q.kind !== 'text')
         return 'input.sensitive is for text questions only';
     if (q.prefill !== undefined && !(q.kind === 'account' || (q.kind === 'text' && !q.sensitive)))
@@ -1738,36 +1755,43 @@ export function createTools(ctx) {
     const accountOf = new Map();
     /** The Vercel project the bypass tool read for each address its secret opened, and its team where that is not the CLI's current scope. */
     const vercelNamed = new Map();
-    /** What the last screen says the run used on each host, from the previews it opened. */
-    const hostsUsed = () => [...usedPreviews].flatMap((url) => {
-        const origin = new URL(url).origin;
-        const label = pagesProject(origin);
-        if (label)
-            return [{ host: 'Cloudflare', project: label, ...(accountOf.has(`cloudflare ${label}`) ? { account: accountOf.get(`cloudflare ${label}`) } : {}) }];
-        const worker = /^https:\/\/\{branch\}-([^.]+)\./.exec(workerPatterns.get(origin) ?? '')?.[1];
-        if (worker)
-            return [{ host: 'Cloudflare', project: worker }];
-        const site = netlifySiteOf(url);
-        if (site)
-            return [{ host: 'Netlify', project: site, ...(accountOf.has(`netlify ${site}`) ? { account: accountOf.get(`netlify ${site}`) } : {}) }];
-        const render = renderSiteOf(url);
-        if (render)
-            return [{ host: 'Render', project: render.site }];
-        const read = vercelNamed.get(origin);
-        const named = read?.project ?? listedApps.get(origin)?.name;
-        const vercel = vercelDeploymentOf(url, named);
-        const team = vercel?.team ?? read?.team;
-        const project = vercel?.project ?? named;
-        return project ? [{ host: 'Vercel', project, ...(team ? { account: team } : {}) }] : [];
-    });
+    /** The Vercel projects impeccable_vercel_connect took as this run's, by name, each with its team ('' for the personal scope): the last screen names them however the run ended, as the report does (REN-1250). */
+    const vercelSetUp = new Map();
+    /** What the last screen says the run used on each host: the Vercel projects it set up, and the previews it opened. */
+    const hostsUsed = () => [...[...vercelSetUp].map(([project, team]) => ({ host: 'Vercel', project, ...(team ? { account: team } : {}) })), ...[...usedPreviews].flatMap((url) => {
+            const origin = new URL(url).origin;
+            const label = pagesProject(origin);
+            if (label)
+                return [{ host: 'Cloudflare', project: label, ...(accountOf.has(`cloudflare ${label}`) ? { account: accountOf.get(`cloudflare ${label}`) } : {}) }];
+            const worker = /^https:\/\/\{branch\}-([^.]+)\./.exec(workerPatterns.get(origin) ?? '')?.[1];
+            if (worker)
+                return [{ host: 'Cloudflare', project: worker }];
+            const site = netlifySiteOf(url);
+            if (site)
+                return [{ host: 'Netlify', project: site, ...(accountOf.has(`netlify ${site}`) ? { account: accountOf.get(`netlify ${site}`) } : {}) }];
+            const render = renderSiteOf(url);
+            if (render)
+                return [{ host: 'Render', project: render.site }];
+            const read = vercelNamed.get(origin);
+            const named = read?.project ?? listedApps.get(origin)?.name;
+            const vercel = vercelDeploymentOf(url, named);
+            const team = vercel?.team ?? read?.team;
+            const project = vercel?.project ?? named;
+            return project ? [{ host: 'Vercel', project, ...(team ? { account: team } : {}) }] : [];
+        })];
+    /** The builds, by what was waited for (`key`), whose wait ran out after its retries or that the person stopped waiting for: read again, never waited for again (REN-1250). */
+    const buildsGivenUp = new Set();
     /**
      * A host's build, waited for on the screen as the task in progress, naming `host`, with the time so far: `read` again
      * every so often until `built` says the evidence is final, or the wait runs out. The status line names the host and what it builds.
+     * A build whose wait (`key`) ran out or was skipped earlier in the run is read once and not waited for again.
      */
-    async function awaitBuild(host, status, read, built, page, signal, access) {
+    async function awaitBuild(host, key, status, read, built, page, signal, access) {
         const first = await read();
         if (built(first))
             return first;
+        if (buildsGivenUp.has(key))
+            return { ...first, reason: `No second wait: ${host}'s build was waited for already in this run, until its retries ran out or the person skipped them, and it is still not built. There is no preview of it, as "No preview, no test drive" says.` };
         const wait = ctx.previewWait ?? { totalMs: 300_000, everyMs: 15_000 };
         const waited = async (evidence) => {
             said(status);
@@ -1784,19 +1808,21 @@ export function createTools(ctx) {
         };
         // No build in the time: the host's page where a build is turned on, and the wait again on the person's yes. Where the host's settings build every
         // branch and still none came, its GitHub app cannot see the repository: the app's installation page instead, at once when the app is not installed at all.
-        if (access) {
-            return onHostPage(`${host.toLowerCase()}-app-access`, () => access.page, (e) => !built(e), access.now ? first : await waited(first), async () => waited(await read()), {
+        const given = access
+            ? await onHostPage(`${host.toLowerCase()}-app-access`, () => access.page, (e) => !built(e), access.now ? first : await waited(first), async () => waited(await read()), {
                 skipped: `The person skipped giving ${host}'s GitHub app access to the repository.`,
                 declines: { app: access.app },
                 still: `${host}'s GitHub app still cannot see the repository: no build came.`,
                 stopped: `The run stopped while ${host}'s build was waited for.`,
+            }, signal)
+            : await onHostPage(`${host.toLowerCase()}-build`, page, (e) => !built(e), await waited(first), async () => waited(await read()), {
+                skipped: `The person stopped waiting for ${host}'s build.`,
+                still: `${host} built no preview in the time.`,
+                stopped: `The run stopped while ${host}'s build was waited for.`,
             }, signal);
-        }
-        return onHostPage(`${host.toLowerCase()}-build`, page, (e) => !built(e), await waited(first), async () => waited(await read()), {
-            skipped: `The person stopped waiting for ${host}'s build.`,
-            still: `${host} built no preview in the time.`,
-            stopped: `The run stopped while ${host}'s build was waited for.`,
-        }, signal);
+        if (!built(given) && !signal?.aborted)
+            buildsGivenUp.add(key);
+        return given;
     }
     /** What a wait for a pull request's build is for: the test drive's preview, or another pull request's. */
     const subjectOf = async (pull) => {
@@ -1922,7 +1948,7 @@ export function createTools(ctx) {
      * it back (`turnOn`); where the host kept it, the person changes it on the host's page and the run reads again, twice at most.
      */
     const turnOnPreviews = async (host, turnOn, signal) => {
-        said(`Turning on pull-request previews on ${{ netlify: 'Netlify', cloudflare: 'Cloudflare Pages', render: 'Render' }[host]}`);
+        said(host === 'vercel' ? `Turning on ${DEPLOYMENT_EVENTS} on Vercel` : `Turning on pull-request previews on ${{ netlify: 'Netlify', cloudflare: 'Cloudflare Pages', render: 'Render' }[host]}`);
         for (let tries = 0;; tries++) {
             const outcome = await turnOn();
             if (outcome.fact.enabled === true) {
@@ -2123,9 +2149,11 @@ export function createTools(ctx) {
      */
     async function hostSignIn(host, pi, signal) {
         const cli = hostCli(host, pi, signal);
+        /** The team, read once the CLI is signed in: before the setup screen, which names it, where it was signed in already. */
+        let teamRead;
         const signedIn = async () => {
             agreeToHostSetup(ctx.log, `${host}-setup`);
-            const { team, choices } = await cli.team();
+            const { team, choices } = await (teamRead ?? cli.team());
             if (team)
                 chooseHostTeam(ctx.log, `${host}-team`, team);
             teamChoices.set(host, choices);
@@ -2135,7 +2163,13 @@ export function createTools(ctx) {
             return { skipped: true };
         let status = await cli.status();
         if (!hostSignIns.has(host)) {
-            const answer = await ask({ id: `${host}-setup`, ...HOST_QUESTIONS[`${host}-setup`], ...(status.cli === 'signed-in' ? HOST_SIGNED_IN[`${host}-setup`] : {}) });
+            // Signed in already, Vercel's screen names the account, the new project and the team it goes into, which the yes is to (REN-1250).
+            let words = status.cli === 'signed-in' ? HOST_SIGNED_IN[`${host}-setup`] : undefined;
+            if (status.cli === 'signed-in' && host === 'vercel' && status.user) {
+                const { team, choices } = await (teamRead = cli.team());
+                words = vercelSignedIn(status.user, { team, pick: choices.length > 1, project: vercelProjectName(pi.cwd) });
+            }
+            const answer = await ask({ id: `${host}-setup`, ...HOST_QUESTIONS[`${host}-setup`], ...words });
             if (answer.skipped) {
                 endSetup(host);
                 return { skipped: true };
@@ -2280,6 +2314,8 @@ export function createTools(ctx) {
                 return { connected: false, reason: `The linked project${project.name ? ` ${project.name}` : ''} is not this run's: ${foreign}. It stays as it is, and nothing was connected. The Vercel setup ends here.` };
             }
         }
+        if (project.name)
+            vercelSetUp.set(project.name, own.team);
         // Tried again every 20 s until the app reaches the repository: the person is giving it access meanwhile.
         const result = await hostAccess('vercel', await connectVercelProject(vercel), () => waitForVercelAccess(vercel, { wait: ctx.hostWait?.access ?? { totalMs: 300_000, everyMs: 20_000 }, signal }), signal, connectedApp);
         // The fence holds pushes and deploys from the sign-in until the linked project's first deployment is settled: Vercel's app cannot reach the repository (a push builds nothing), production is deployed already, or the project is locked at every address.
@@ -2288,6 +2324,12 @@ export function createTools(ctx) {
                 settleVercelFirstDeployment(ctx.log, { projectId: link.projectId, how: 'connection' });
             return result;
         }
+        // Vercel records its deployments on GitHub, where the wait finds the test drive's, only with deployment_status Events on, and a project the CLI creates starts with it off (REN-1248).
+        const created = Boolean(project.name && vercelProjectsAdded(ctx.log).has(`${own.team}/${project.name.toLowerCase()}`));
+        const events = project.githubDeployments ? undefined : await vercelDeploymentsOn(vercel, link, project.name, !created, connectedApp, signal);
+        // The person's no ends the setup: nothing is pushed, so the hold stays and nothing more changes on the project.
+        if (events?.status === 'skipped')
+            return { ...result, deploymentEvents: events };
         let first = await prepareFirstDeployment(vercel, link, repository);
         vercelProject = first.project ?? vercelProject;
         // Vercel refused the lock: the person turns it on in the project's settings, in this run, and the read sees it.
@@ -2303,7 +2345,36 @@ export function createTools(ctx) {
         }
         if (first.production === 'exists' || first.locked === true)
             settleVercelFirstDeployment(ctx.log, { projectId: link.projectId, how: 'project' });
-        return { ...result, ...first };
+        return { ...result, ...first, ...(events ? { deploymentEvents: events } : {}) };
+    }
+    /** What impeccable_hosted_previews last read of each app's Vercel project ('' for a repository of one app): the fact impeccable_enable_previews acts on for that app. */
+    const vercelFacts = new Map();
+    /** What turning on deployment_status Events answered, by Vercel project: asked once, so that answer stands. */
+    const deploymentEventsOutcomes = new Map();
+    /**
+     * The project's deployment_status Events, turned on as the person through the CLI where they are off: at once for a
+     * project this run created, after the one consent screen (`consent`) for any other. Where Vercel refuses the run, the
+     * person turns it on on the project's Settings → Git and the run reads again. A skip is a no that ends the setup.
+     */
+    async function vercelDeploymentsOn(vercel, link, project, consent, app, signal) {
+        const standing = deploymentEventsOutcomes.get(link.projectId);
+        if (standing?.status === 'skipped')
+            decline('no-previews', app);
+        if (standing)
+            return standing;
+        const answer = (status, more) => {
+            const told = { status, ...(project ? { project } : {}), ...more };
+            deploymentEventsOutcomes.set(link.projectId, told);
+            if (status === 'skipped')
+                decline('no-previews', app);
+            return told;
+        };
+        const screen = HOST_SCREENS['vercel-previews'];
+        if (consent && (await ask({ ...screen, prompt: `Turn on ${DEPLOYMENT_EVENTS} for ${project ?? 'the Vercel project'}?` })).skipped)
+            return answer('skipped', { reason: `The person skipped turning on ${DEPLOYMENT_EVENTS}.` });
+        const page = await vercelPageFor(vercel, link, 'settings/git', project);
+        const { status, ...more } = await turnOnPreviews('vercel', () => enableGithubDeployments(vercel, link, repository, page), signal);
+        return answer(status, more);
     }
     async function syncWorkflowTool(pi, signal) {
         try {
@@ -2899,7 +2970,7 @@ export function createTools(ctx) {
             // A test account never comes back to the model, even if the API echoed it.
             return testAccounts ? redact(answerText(response), typed.values()) : answerText(response);
         }),
-        tool('impeccable_ask', 'Ask the person', 'Ask the person one question in a dialog, and wait for the answer; the web page shows the run waiting meanwhile. Answers {"value": "…"} for text and single, {"values": […]} for multi, {"confirmed": true} for confirm, {"username": "…", "password": "secret:…"} for account, or {"skipped": true}. A host\'s setup question (id "vercel-setup", "vercel-team", "netlify-setup" or "netlify-team") is worded by this tool: give it that id and its kind. So is the apps question on a repository with several apps (id "apps", kind "multi"), which lists the state\'s apps itself, has no Skip, and answers {"values": […]} (at least one app) or {"values": [key], "named": true} when the command was started for that app (it shows one confirm screen naming the app instead of the list, and the list when the person asks for other apps there); where no answer comes, nothing is written and the run ends. netlify-setup and vercel-setup are the host\'s sign-in: it shows its screen only when that CLI is signed out, signs the person in through the browser with a retry, and answers {"confirmed": true, "signedIn": true}, with "team" (the one the project goes into) or "teams" to choose from when the person has several, {"confirmed": true, "cli": "missing"} when the CLI is to be installed first and this asked again, or {"skipped": true}.', ASK, async (p, pi, signal) => {
+        tool('impeccable_ask', 'Ask the person', 'Ask the person one question in a dialog, and wait for the answer; the web page shows the run waiting meanwhile. Ask only when the run needs their answer, with a prompt that says what they answer or agree to: it refuses one of fewer than two words. Answers {"value": "…"} for text and single, {"values": […]} for multi, {"confirmed": true} for confirm, {"username": "…", "password": "secret:…"} for account, or {"skipped": true}. A host\'s setup question (id "vercel-setup", "vercel-team", "netlify-setup" or "netlify-team") is worded by this tool: give it that id and its kind. So is the apps question on a repository with several apps (id "apps", kind "multi"), which lists the state\'s apps itself, has no Skip, and answers {"values": […]} (at least one app) or {"values": [key], "named": true} when the command was started for that app (it shows one confirm screen naming the app instead of the list, and the list when the person asks for other apps there); where no answer comes, nothing is written and the run ends. netlify-setup and vercel-setup are the host\'s sign-in: it shows its screen only when that CLI is signed out, signs the person in through the browser with a retry, and answers {"confirmed": true, "signedIn": true}, with "team" (the one the project goes into) or "teams" to choose from when the person has several, {"confirmed": true, "cli": "missing"} when the CLI is to be installed first and this asked again, or {"skipped": true}.', ASK, async (p, pi, signal) => {
             // A skip never stops the run, so every question offers one, but the apps question, which needs at least one app (#405).
             const { appKey: forApp, ...asked } = p;
             if (asked.id === APPS_QUESTION.id && appsRepo)
@@ -3145,7 +3216,7 @@ export function createTools(ctx) {
                 if (!left.includes('Watch the review on the test drive'))
                     left.push('Watch the review on the test drive');
             }
-            const { phase, status, question, report_markdown, test_pr, test_prs, left: leftBefore } = ctx.sync.payload;
+            const { phase, status, question, report_markdown, test_pr, test_prs, left: leftBefore, ended: endedBefore } = ctx.sync.payload;
             // Why an app was not proven or keyed goes with its summary only as plain words, with no address (a scheme, or a host with a path or query) and nothing shaped like a secret; anything else is dropped.
             const appsBefore = new Map(appSummaries);
             // Each app whose setup ended on the person's no says so on the web page, unless the report gives its own words below.
@@ -3170,11 +3241,11 @@ export function createTools(ctx) {
             // The list as the run left the apps: a Preview method done for some apps only says whose (REN-1108).
             const tasks = taskOrder.sort(labelled(ctx.sync.payload.tasks));
             reportTasks(tasks);
-            ctx.sync.update({ tasks, phase: 'completed', status: ended ? SETUP_ENDS[ended].title : 'Setup finished', question: null, report_markdown: markdown, test_pr: drive, ...(several ? { test_prs: Object.fromEntries(kept) } : {}), left: left.slice(0, 20) });
+            ctx.sync.update({ tasks, phase: 'completed', status: ended ? SETUP_ENDS[ended].title : 'Setup finished', question: null, report_markdown: markdown, test_pr: drive, ...(several ? { test_prs: Object.fromEntries(kept) } : {}), left: left.slice(0, 20), ended });
             const res = await ctx.sync.flush();
             if (res && res.status >= 400 && res.status < 500) {
                 // A definite no: the run is still open on the server, so the session goes back to what it was and the agent can send the report again.
-                ctx.sync.update({ phase, status, question, report_markdown, test_pr, test_prs, left: leftBefore });
+                ctx.sync.update({ phase, status, question, report_markdown, test_pr, test_prs, left: leftBefore, ended: endedBefore });
                 // Its reasons go with it: the report sent again gives its own.
                 if (appsBefore.size) {
                     for (const [key, was] of appsBefore)
@@ -3190,7 +3261,7 @@ export function createTools(ctx) {
             const saved = res?.ok ? 'Saved.' : `The web page did not take it (${res?.error ?? 'no answer'}).`;
             return { text: `${saved} The terminal shows the summary and the command exits.`, terminate: true };
         }),
-        tool('impeccable_hosted_previews', 'Hosted previews', 'Read the deployments GitHub has on record for this repository: the 20 newest, each with its latest status, its address, its environment, whether Vercel made it and the pull requests whose commit it built. An error says nothing either way. Without branch, where GitHub records a production deployment Vercel made and this folder is linked to the project (.vercel/project.json) the Vercel CLI reads as this repository\'s, production is the live app\'s address, the project\'s own domain, for the before. With branch (a branch of this run, pushed, before its pull request exists), only its head\'s, waiting up to five minutes for Vercel\'s deployment of it to finish building, under a status line with its timer, and again on the person\'s yes when the time ran out. A Production deployment of that branch (a project\'s first is, whatever branch it builds) is listed as its preview only while the project this folder is linked to is locked at every address (impeccable_vercel_connect locks it) and made it, read from Vercel at that moment, since a production deployment is otherwise served at the project\'s own address without a login; then no proof opens it. It changes nothing on the host and proves nothing about the page.', HOSTED_PREVIEWS, async (p, pi, signal) => {
+        tool('impeccable_hosted_previews', 'Hosted previews', 'Read the deployments GitHub has on record for this repository: the 20 newest, each with its latest status, its address, its environment, whether Vercel made it and the pull requests whose commit it built. An error says nothing either way. Without branch, where GitHub records a production deployment Vercel made and this folder is linked to the project (.vercel/project.json) the Vercel CLI reads as this repository\'s, production is the live app\'s address, the project\'s own domain, for the before. With branch (a branch of this run, pushed, before its pull request exists), only its head\'s, waiting up to five minutes for Vercel\'s deployment of it to finish building, under a status line with its timer, and again on the person\'s yes when the time ran out, three times at most; once those ran out or the person skipped, another call for it reads once and waits no more. A Production deployment of that branch (a project\'s first is, whatever branch it builds) is listed as its preview only while the project this folder is linked to is locked at every address (impeccable_vercel_connect locks it) and made it, read from Vercel at that moment, since a production deployment is otherwise served at the project\'s own address without a login; then no proof opens it. Where GitHub records no deployment of Vercel\'s for that head (the project\'s deployment_status Events off), Vercel\'s commit status on it ends the wait at once: the deployment it names is listed, read from Vercel, and githubDeployments false with reason says what Vercel did (built, failed or skipped). It changes nothing on the host and proves nothing about the page.', HOSTED_PREVIEWS, async (p, pi, signal) => {
             const branch = p.branch;
             const refused = appRefusal(p.appKey, 'read') ?? lockRefusal(p.appKey, 'read');
             if (refused)
@@ -3227,21 +3298,44 @@ export function createTools(ctx) {
                 return named !== undefined ? named === app.name : projectMadeDeployment(vercel, app.link, app.project, new URL(d.url).host);
             };
             const read = async () => {
-                const evidence = await raw();
-                if (!app)
-                    return evidence;
-                const kept = await Promise.all(evidence.deployments.map(owned));
-                return { ...evidence, deployments: evidence.deployments.filter((_, i) => kept[i]) };
+                const { vercelStatuses, ...evidence } = await raw();
+                const kept = app ? await Promise.all(evidence.deployments.map(owned)) : [];
+                const mine = app ? evidence.deployments.filter((_, i) => kept[i]) : evidence.deployments;
+                // Vercel reported the head's build only as its commit status, as it does with deployment_status Events off (REN-1248), where GitHub lists no deployment of
+                // Vercel's of this project: the deployment the status names, read from Vercel as the person, stands for the one GitHub never got.
+                if (branch === undefined || !vercelStatuses?.length || mine.some((d) => d.vercel))
+                    return { ...evidence, deployments: mine };
+                const linked = app ? app.link : await readLink(pi.cwd);
+                const own = !app && linked ? await readOwnProject(vercel, linked, repository) : null;
+                const name = app?.name ?? (own && !('reason' in own) ? own.name : undefined) ?? vercelProject;
+                const statuses = [];
+                const made = [];
+                for (const s of vercelStatuses) {
+                    // A context names its project; the one plain "Vercel" status may be any project's, and the deployment it names tells.
+                    if (s.context !== 'Vercel' && (!name || s.context !== `Vercel – ${name}`))
+                        continue;
+                    const d = linked && s.targetUrl && (s.state === 'built' || s.state === 'failed') ? await deploymentOfStatus(vercel, linked, s.targetUrl, s.sha) : null;
+                    if (d === 'other')
+                        continue;
+                    // Unread, the plain one is this project's only where its page in Vercel's dashboard, vercel.com/<scope>/<project>/<id>, names this project.
+                    if (!d && s.context === 'Vercel' && (!name || s.targetUrl?.split('/')[4] !== name))
+                        continue;
+                    statuses.push(s);
+                    if (d)
+                        made.push({ sha: s.sha, environment: `${d.production ? 'Production' : 'Preview'} – ${d.name || name || ''}`, state: s.state === 'built' ? 'success' : 'failure', url: d.url, vercel: true, pullRequests: [] });
+                }
+                return { ...evidence, deployments: [...mine, ...made], ...(statuses.length ? { vercelStatuses: statuses } : {}) };
             };
             // With `branch` the evidence holds only the deployments of its head, and Vercel's is its build whatever environment it is called: the first deployment of a
             // project is its Production one, even from a branch. Another integration's deployment of the same commit says nothing about it. Without it a preview is a Preview.
             const isPreview = (d) => /preview/i.test(d.environment ?? '');
             const ofBranch = (d) => (branch !== undefined ? d.vercel : isPreview(d));
             // A head's build is still building until it has a final status.
-            const final = (evidence) => Boolean(evidence.error) || evidence.deployments.some((d) => ofBranch(d) && (d.state === 'success' || d.state === 'failure' || d.state === 'error'));
+            // Vercel's commit status settles it too, so a build GitHub will never record a deployment of ends the wait at once.
+            const final = (evidence) => Boolean(evidence.error) || evidence.deployments.some((d) => ofBranch(d) && (d.state === 'success' || d.state === 'failure' || d.state === 'error')) || Boolean(evidence.vercelStatuses?.some((s) => s.state !== 'building'));
             // The project's Git settings, for the screen a build that never comes opens: the app's project's own page, else the linked project's.
             const gitPage = branch !== undefined ? await vercelPageFor(vercel, app ? app.link : await readLink(pi.cwd), 'settings/git', app?.name ?? vercelProject) : '';
-            const evidence = branch !== undefined ? await awaitBuild('Vercel', `Waiting for Vercel to build ${testDriveBranch(branch) ? "the test drive's preview" : `the preview of ${branch}`}`, read, final, () => gitPage, signal) : await read();
+            const evidence = branch !== undefined ? await awaitBuild('Vercel', `vercel ${appKey ?? ''} ${branch}`, `Waiting for Vercel to build ${testDriveBranch(branch) ? "the test drive's preview" : `the preview of ${branch}`}`, read, final, () => gitPage, signal) : await read();
             /** The project the evidence is of: the app's, else the one this folder is linked to. */
             const link = async () => (app ? app.link : readLink(pi.cwd));
             /** The hosts of the linked project's deployments while it is locked at every address, read from Vercel once a Production deployment turns up, and once per call. */
@@ -3279,6 +3373,7 @@ export function createTools(ctx) {
                 const fact = await (ctx.vercelPreviewsReader ?? vercelPreviewsFact)(pi.cwd, `${ctx.owner}/${ctx.repo}`, () => vercel, app ? { directory: app.folder, link: app.link } : undefined);
                 if (fact) {
                     previewFacts.set('vercel', fact);
+                    vercelFacts.set(appKey ?? '', fact);
                     evidence.pullRequestPreviews = fact;
                 }
             }
@@ -3295,9 +3390,12 @@ export function createTools(ctx) {
             }
             if (app?.name)
                 noteApp(appKey, { host_project: app.name });
-            return JSON.stringify({ ...(appKey !== undefined ? { appKey, project: app.name } : {}), ...evidence, ...(production ? { production } : {}) });
+            // What Vercel's commit status says, where GitHub records no deployment of Vercel's for the head: the cause in Vercel's own words, never "no build".
+            const told = branch !== undefined && evidence.vercelStatuses?.length ? statusReason(branch, evidence.vercelStatuses, evidence.deployments.some((d) => d.vercel && d.state === 'success' && d.url)) : undefined;
+            const { vercelStatuses: _statuses, ...shown } = evidence;
+            return JSON.stringify({ ...(appKey !== undefined ? { appKey, project: app.name } : {}), ...shown, ...(production ? { production } : {}), ...(told ? { githubDeployments: false, reason: told } : {}) });
         }),
-        tool('impeccable_netlify_previews', 'Netlify previews', "Read whether this repository's pull requests get Netlify deploy previews: the 10 newest, each with its site, its address, its state and where that was read: GitHub's commit status or Netlify's bot comment on the pull request (from the setup state's hosting record where it lists them or carries readAt, else read from GitHub here), or the Netlify CLI on this machine when it is signed in (read only: it never signs in). production is the live site's own address, for the before. cli says whether that CLI is missing, signed out, signed in or did not answer. An error says something could not be read, which is unknown rather than absent. With pull (a pull request of this run, a draft included: Netlify builds a deploy preview only for a pull request), only that pull request's, waiting up to five minutes for one to finish building, under a status line with its timer, and again on the person's yes when the time ran out. It changes nothing on Netlify and proves nothing about the page.", NETLIFY_PREVIEWS, async (p, pi, signal) => {
+        tool('impeccable_netlify_previews', 'Netlify previews', "Read whether this repository's pull requests get Netlify deploy previews: the 10 newest, each with its site, its address, its state and where that was read: GitHub's commit status or Netlify's bot comment on the pull request (from the setup state's hosting record where it lists them or carries readAt, else read from GitHub here), or the Netlify CLI on this machine when it is signed in (read only: it never signs in). production is the live site's own address, for the before. cli says whether that CLI is missing, signed out, signed in or did not answer. An error says something could not be read, which is unknown rather than absent. With pull (a pull request of this run, a draft included: Netlify builds a deploy preview only for a pull request), only that pull request's, waiting up to five minutes for one to finish building, under a status line with its timer, and again on the person's yes when the time ran out, three times at most; once those ran out or the person skipped, another call for it reads once and waits no more. It changes nothing on Netlify and proves nothing about the page.", NETLIFY_PREVIEWS, async (p, pi, signal) => {
             const pull = p.pull;
             const refused = appRefusal(p.appKey, 'read') ?? lockRefusal(p.appKey, 'read');
             if (refused)
@@ -3316,7 +3414,7 @@ export function createTools(ctx) {
             // A pull request's preview is still building until Netlify's deploy of it is built or has failed.
             const states = ['success', 'ready', 'failure', 'error'];
             const final = (evidence) => Boolean(evidence.error) || evidence.previews.some((preview) => states.includes(preview.state ?? ''));
-            const evidence = pull !== undefined ? await awaitBuild('Netlify', `Waiting for Netlify to build ${await subjectOf(pull)}`, read, final, (e) => {
+            const evidence = pull !== undefined ? await awaitBuild('Netlify', `netlify ${appKey ?? ''} #${pull}`, `Waiting for Netlify to build ${await subjectOf(pull)}`, read, final, (e) => {
                 // The waited pull request's own site; else the one site known, so another app's site never opens.
                 const known = new Set([...e.sites, ...(netlifySite ? [netlifySite] : [])]);
                 const site = e.previews.find((preview) => preview.pullRequest === pull)?.site ?? (known.size === 1 ? [...known][0] : undefined);
@@ -3349,7 +3447,7 @@ export function createTools(ctx) {
                 noteApp(appKey, { host_project: site });
             return JSON.stringify(appKey !== undefined ? { appKey, ...evidence } : evidence);
         }),
-        tool('impeccable_cloudflare_previews', 'Cloudflare Pages previews', "Read whether this repository's pull requests get Cloudflare Pages previews: the 10 newest, each with its address, the branch's alias (https://<branch>.<project>.pages.dev, which follows the branch's latest build), its state and where that was read: the check run or the pull request comment Cloudflare's GitHub app posts (from the setup state's hosting record where it lists them or carries readAt, else read from GitHub here), or cf, Cloudflare's CLI, on this machine when it is signed in (read only: it never signs in; where cf is not installed here, the person is asked to install it first, on its own screen). production is the project's own address, https://<project>.pages.dev, the live app, for the before. cli says whether cf is missing, signed out, signed in or did not answer. An error says something could not be read, which is unknown rather than absent, and unread says whose: GitHub or cf. pullRequestPreviews says whether the Pages project built from this repository builds previews of pull requests at all (enabled false, with the cause: source, deployments or previews); worker says Cloudflare builds a Worker from the repository (Workers Builds); where its branch builds make previews, they are listed too, on workers.dev (the alias https://<branch>-<worker>.<subdomain>.workers.dev, with the pattern it stands for), and with no Pages project production is the Worker's own address; githubApp says what gh reads of Cloudflare's GitHub app on the owner, and the page where it gets access. With pull (a pull request of this run) or branch (a branch of this run, pushed, before its pull request exists), only that one's, waiting up to five minutes for its build to finish, under a status line with its timer, and again on the person's yes when the time ran out; where the project's settings build every branch and no build came, the wait's screen opens the GitHub page where Cloudflare's app gets access to the repository instead, and waits again. It changes nothing on Cloudflare and proves nothing about the page.", CLOUDFLARE_PREVIEWS, async (p, pi, signal) => {
+        tool('impeccable_cloudflare_previews', 'Cloudflare Pages previews', "Read whether this repository's pull requests get Cloudflare Pages previews: the 10 newest, each with its address, the branch's alias (https://<branch>.<project>.pages.dev, which follows the branch's latest build), its state and where that was read: the check run or the pull request comment Cloudflare's GitHub app posts (from the setup state's hosting record where it lists them or carries readAt, else read from GitHub here), or cf, Cloudflare's CLI, on this machine when it is signed in (read only: it never signs in; where cf is not installed here, the person is asked to install it first, on its own screen). production is the project's own address, https://<project>.pages.dev, the live app, for the before. cli says whether cf is missing, signed out, signed in or did not answer. An error says something could not be read, which is unknown rather than absent, and unread says whose: GitHub or cf. pullRequestPreviews says whether the Pages project built from this repository builds previews of pull requests at all (enabled false, with the cause: source, deployments or previews); worker says Cloudflare builds a Worker from the repository (Workers Builds); where its branch builds make previews, they are listed too, on workers.dev (the alias https://<branch>-<worker>.<subdomain>.workers.dev, with the pattern it stands for), and with no Pages project production is the Worker's own address; githubApp says what gh reads of Cloudflare's GitHub app on the owner, and the page where it gets access. With pull (a pull request of this run) or branch (a branch of this run, pushed, before its pull request exists), only that one's, waiting up to five minutes for its build to finish, under a status line with its timer, and again on the person's yes when the time ran out, three times at most; once those ran out or the person skipped, another call for it reads once and waits no more; where the project's settings build every branch and no build came, the wait's screen opens the GitHub page where Cloudflare's app gets access to the repository instead, and waits again. It changes nothing on Cloudflare and proves nothing about the page.", CLOUDFLARE_PREVIEWS, async (p, pi, signal) => {
             const pull = p.pull;
             const branch = p.branch;
             if (pull !== undefined && branch !== undefined)
@@ -3385,7 +3483,7 @@ export function createTools(ctx) {
             // unless it covers them all, or Cloudflare built a preview of the repository already, which it could not without the app.
             const app = cloudflareEvidence?.githubApp;
             const access = branch !== undefined && previewFacts.get('cloudflare')?.enabled === true && app?.repositories !== 'all' && !cloudflareEvidence?.previews.length ? { page: app?.page ?? CLOUDFLARE_APP_PAGE, now: app?.installed === false, ...(typeof p.appKey === 'string' ? { app: p.appKey } : {}) } : undefined;
-            let waited = subject ? await awaitBuild('Cloudflare', `Waiting for Cloudflare ${pattern ? 'Workers' : 'Pages'} to build ${subject}`, read, final, () => 'https://dash.cloudflare.com/?to=/:account/workers-and-pages', signal, access) : await read();
+            let waited = subject ? await awaitBuild('Cloudflare', `cloudflare ${typeof p.appKey === 'string' ? p.appKey : ''} ${branch ?? `#${pull}`}`, `Waiting for Cloudflare ${pattern ? 'Workers' : 'Pages'} to build ${subject}`, read, final, () => 'https://dash.cloudflare.com/?to=/:account/workers-and-pages', signal, access) : await read();
             // cf not on this machine (#396): its install is asked before anything installs it, and the evidence read again with it.
             if (!subject && waited.cli === 'missing') {
                 await installCf(pi, signal);
@@ -3521,7 +3619,7 @@ export function createTools(ctx) {
                 return JSON.stringify({ ...proof, appKey: app.appKey });
             return JSON.stringify(proof);
         }),
-        tool('impeccable_render_previews', 'Render previews', "Read whether Render builds this repository's pull requests, on a repository with several apps for the app's own folder (appKey): the Render site, from the render CLI signed in on this machine (the service built from this repository, in the app's folder by its Root Directory), else the one site the setup state's hosting record names for the app (Render's deployments, its live address), else the one Render's deployments on GitHub and the checkout's files name (on a repository with several apps, a file in the app's own folder, or a line of the root README naming that app and no other); its previews as GitHub records them (from the state's record where it lists them or carries readAt, else read from GitHub here), each with its pull request, its address and its state (a closed pull request's address too, read from its earlier successful status, though Render took that preview down; pullState closed marks one the record knows is closed, and impeccable_prove_preview refuses it); production, the site's own address, for the before; pattern, the address every pull request's preview has; and pullRequestPreviews (enabled false, with the cause, where the service's previews are off or manual; 'unknown' without the CLI's answer). cli says whether the render CLI answered (signed-in), is missing, could not list the services (unread, with the reason), or lists none of this repository's (none). Once a site is found, it shows the person one screen naming Render, with the site's address to click, asked once for each app: confirmed true, or false when the person skipped it, which is a no that ends the setup for that app. Where the CLI says the previews are off, that screen is also the consent to turning them on, and on the yes the CLI turns them on and reads them back, with a retry screen on Render's page where it could not: turnedOn in the answer says how that ended (enabled, by run or person; skipped; refused, with the reason and the page). With pull (a pull request of this run, a draft included: Render builds the preview as soon as a pull request opens), only that pull request's preview of the site the plain read found, waiting up to five minutes for it to finish building, under a status line with its timer, and again on the person's yes when the time ran out. Never asks for an address.", RENDER_PREVIEWS, async (p, pi, signal) => {
+        tool('impeccable_render_previews', 'Render previews', "Read whether Render builds this repository's pull requests, on a repository with several apps for the app's own folder (appKey): the Render site, from the render CLI signed in on this machine (the service built from this repository, in the app's folder by its Root Directory), else the one site the setup state's hosting record names for the app (Render's deployments, its live address), else the one Render's deployments on GitHub and the checkout's files name (on a repository with several apps, a file in the app's own folder, or a line of the root README naming that app and no other); its previews as GitHub records them (from the state's record where it lists them or carries readAt, else read from GitHub here), each with its pull request, its address and its state (a closed pull request's address too, read from its earlier successful status, though Render took that preview down; pullState closed marks one the record knows is closed, and impeccable_prove_preview refuses it); production, the site's own address, for the before; pattern, the address every pull request's preview has; and pullRequestPreviews (enabled false, with the cause, where the service's previews are off or manual; 'unknown' without the CLI's answer). cli says whether the render CLI answered (signed-in), is missing, could not list the services (unread, with the reason), or lists none of this repository's (none). Once a site is found, it shows the person one screen naming Render, with the site's address to click, asked once for each app: confirmed true, or false when the person skipped it, which is a no that ends the setup for that app. Where the CLI says the previews are off, that screen is also the consent to turning them on, and on the yes the CLI turns them on and reads them back, with a retry screen on Render's page where it could not: turnedOn in the answer says how that ended (enabled, by run or person; skipped; refused, with the reason and the page). With pull (a pull request of this run, a draft included: Render builds the preview as soon as a pull request opens), only that pull request's preview of the site the plain read found, waiting up to five minutes for it to finish building, under a status line with its timer, and again on the person's yes when the time ran out, three times at most; once those ran out or the person skipped, another call for it reads once and waits no more. Never asks for an address.", RENDER_PREVIEWS, async (p, pi, signal) => {
             const pull = p.pull;
             const refused = appRefusal(p.appKey, 'read') ?? lockRefusal(p.appKey, 'read');
             if (refused)
@@ -3564,7 +3662,7 @@ export function createTools(ctx) {
                     return { previews: previewsOf(evidence, known.site), ...(evidence.error ? { error: evidence.error } : {}) };
                 };
                 const final = (e) => Boolean(e.error) || e.previews.some((preview) => preview.state === 'success' || preview.state === 'failure' || preview.state === 'error');
-                const waited = await awaitBuild('Render', `Waiting for Render to build ${await subjectOf(pull)}`, read, final, () => known.page, signal);
+                const waited = await awaitBuild('Render', `render ${appKey ?? ''} #${pull}`, `Waiting for Render to build ${await subjectOf(pull)}`, read, final, () => known.page, signal);
                 list(waited.previews);
                 for (const origin of renderListed)
                     renderBuilt.add(origin);
@@ -3654,7 +3752,26 @@ export function createTools(ctx) {
                 noteApp(appKey, { host_project: result.site.name });
             return JSON.stringify(appKey !== undefined ? { appKey, ...result } : result);
         }),
-        tool('impeccable_enable_previews', 'Pull-request previews', "Turn on previews of pull requests on the host that builds this repository but not its pull requests, as pullRequestPreviews in the answer of impeccable_netlify_previews, impeccable_netlify_connect or impeccable_cloudflare_previews said (enabled false). It does the rest as the person: one screen asking to turn them on, then the host's CLI changes that one setting (Netlify: Deploy Previews on; Cloudflare Pages: preview branch control set to every non-production branch, or the test drive's branch added to the custom includes) and reads it back; where the CLI cannot (the role, a cf sign-in without pages:write, builds stopped altogether), it opens the host's settings page and asks the person to try again once they changed it there. Answers {\"status\": …}: enabled (pull-request previews are on now; by says whether the run or the person turned them on, and project which project or site), skipped (the person skipped a screen; reason says what came before) or refused (still off after the retries; reason says why, and page where it is changed). Vercel builds every branch once Git is connected, so its fact is reported and never changed here.", ENABLE_PREVIEWS, async (p, pi, signal) => {
+        tool('impeccable_enable_previews', 'Pull-request previews', "Turn on previews of pull requests on the host that builds this repository but not its pull requests, as pullRequestPreviews in the answer of impeccable_netlify_previews, impeccable_netlify_connect, impeccable_cloudflare_previews or impeccable_hosted_previews said (enabled false). It does the rest as the person: one screen asking to turn them on, then the host's CLI changes that one setting (Netlify: Deploy Previews on; Cloudflare Pages: preview branch control set to every non-production branch, or the test drive's branch added to the custom includes; Vercel, with cause previews: deployment_status Events, which records Vercel's deployments on GitHub, where Impeccable finds them) and reads it back; where the CLI cannot (the role, a cf sign-in without pages:write, builds stopped altogether), it opens the host's settings page and asks the person to try again once they changed it there. Answers {\"status\": …}: enabled (pull-request previews are on now; by says whether the run or the person turned them on, and project which project or site), skipped (the person skipped a screen; reason says what came before) or refused (still off after the retries; reason says why, and page where it is changed). A vercel.json rule that turns Vercel's builds off is the repository's own, and is never changed here.", ENABLE_PREVIEWS, async (p, pi, signal) => {
+            if (p.host === 'vercel') {
+                // The project the fact was read of: the app's own on a repository with several apps, else the one this folder is linked to.
+                const fact = vercelFacts.get(appsRepo ? p.appKey : '');
+                const off = fact?.enabled === false && fact.cause === 'previews';
+                const unread = `Refused: this is for a Vercel project whose pullRequestPreviews said enabled false with cause previews (${DEPLOYMENT_EVENTS} off) in this run. Read impeccable_hosted_previews first; a vercel.json rule is the repository's own to change.`;
+                if (!off && !deploymentEventsOutcomes.size)
+                    return unread;
+                const vercel = hostRunner('vercel', pi.cwd, { signal });
+                const app = appsRepo ? await vercelApp(pi, p.appKey, vercel) : null;
+                if (app && 'reason' in app)
+                    return JSON.stringify({ appKey: p.appKey, status: 'refused', reason: app.reason });
+                const link = app ? app.link : await readLink(pi.cwd);
+                if (!link)
+                    return 'Refused: this folder is linked to no Vercel project (.vercel/project.json), so which project to change cannot be told.';
+                // The answer stands for the project, as before.
+                if (!off && !deploymentEventsOutcomes.has(link.projectId))
+                    return unread;
+                return JSON.stringify(await vercelDeploymentsOn(vercel, link, app ? app.name : fact?.project || undefined, true, p.appKey, signal));
+            }
             const host = p.host;
             const standing = enableOutcomes.get(host);
             // The answer stands for the run, as before; its no ends the setup only of an app on the project it was for.
@@ -3755,7 +3872,7 @@ export function createTools(ctx) {
             cloudflareEvidence = { ...evidence, project, ...(outcome.fact ? { pullRequestPreviews: outcome.fact } : {}) };
             return answer('connected', { created: outcome.created, ...(outcome.subdomain ? { subdomain: outcome.subdomain } : {}), ...(outcome.productionBranch ? { productionBranch: outcome.productionBranch } : {}) });
         }),
-        tool('impeccable_vercel_connect', 'Connect the repository to Vercel', "Connect the Vercel project this folder is linked to with this repository (vercel git connect), so that pull requests get preview deployments, and lock a project that has no production deployment yet. Only a project this run made with vercel project add and linked with vercel link, or one connected to this repository already, is connected: a project that existed before the run (vercel link links an existing project of the folder's name) is left as it is, with the reason, and the Vercel setup ends there. Vercel makes a new project's first deployment Production, whatever branch it builds, and serves it at the project's own address, so this puts Vercel's login in front of every address of the project (Deployment Protection on All Deployments) before anything is pushed; the fence holds every push until this settled the first deployment. The run does it; when Vercel's GitHub app cannot reach the repository, this asks the person once for its access on GitHub and waits, and when Vercel refuses the lock, it asks the person once to turn it on in the project's settings and waits. connected true means the repository is connected, or was already; production \"exists\" means the project deploys production already, so a push of another branch is a Preview; locked true means every address of the project is behind Vercel's login, so its first deployment is no public build; locked false, with reason, means push nothing; with production \"exists\", productionUrl is the live app's address, for the before. A connection left undone answers why, and the GitHub page for the person in access.", NO_INPUT, async (_p, pi, signal) => {
+        tool('impeccable_vercel_connect', 'Connect the repository to Vercel', "Connect the Vercel project this folder is linked to with this repository (vercel git connect), so that pull requests get preview deployments, and lock a project that has no production deployment yet. Only a project this run made with vercel project add and linked with vercel link, or one connected to this repository already, is connected: a project that existed before the run (vercel link links an existing project of the folder's name) is left as it is, with the reason, and the Vercel setup ends there. Vercel makes a new project's first deployment Production, whatever branch it builds, and serves it at the project's own address, so this puts Vercel's login in front of every address of the project (Deployment Protection on All Deployments) before anything is pushed; the fence holds every push until this settled the first deployment. The run does it; when Vercel's GitHub app cannot reach the repository, this asks the person once for its access on GitHub and waits, and when Vercel refuses the lock, it asks the person once to turn it on in the project's settings and waits. connected true means the repository is connected, or was already; production \"exists\" means the project deploys production already, so a push of another branch is a Preview; locked true means every address of the project is behind Vercel's login, so its first deployment is no public build; locked false, with reason, means push nothing; deploymentEvents, present where the project's deployment_status Events was off (Vercel then records no deployment on GitHub, where Impeccable finds its previews), says how turning it on as the person ended: at once for a project this run created, after one screen for any other; status enabled, skipped (the person's no, which ends the setup: push nothing) or refused (reason, and page where the person turns it on); with production \"exists\", productionUrl is the live app's address, for the before. A connection left undone answers why, and the GitHub page for the person in access.", NO_INPUT, async (_p, pi, signal) => {
             const refused = appRefusal(undefined, 'connected', false);
             if (refused)
                 return refused;
@@ -3891,6 +4008,15 @@ export function createTools(ctx) {
                     bypassConsented.add(`${store}/${link.projectId}`);
                     return JSON.stringify({ ...of, protected: true, consent: 'given' });
                 }
+                // No proof will meet the login now, so the web page learns it from here, as a proof's would tell it (#365): at one of the project's own deployments, which the login covers (REN-1246).
+                const deployed = [...project.deploymentHosts][0];
+                if (deployed) {
+                    const met = { gate: 'vercel-protection', preview_host: deployed };
+                    if (app)
+                        noteApp(app.appKey, { ...met, preview_proven: false });
+                    else if (!appsRepo)
+                        ctx.sync.update({ preview_gate: met });
+                }
                 const outcome = noAccess({ status: 'skipped', ...of, protected: true, reason: `The person skipped creating a bypass secret before the test drive's push. Vercel's login stands in front of the previews of ${project.name ? `the Vercel project ${project.name}` : 'the Vercel project'}, so a test drive pushed now could not be reviewed. A secret made in the project's Settings → Deployment Protection → Protection Bypass for Automation, named "Impeccable reviews", and saved on the setup page lets reviews in.` });
                 bypassOutcomes.set(store, outcome);
                 return JSON.stringify(outcome);

package/dist/ui/look.js

@@ -1,5 +1,5 @@
 import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
-import { fitsTask, taskInProgress, workStarted } from '../stages.js';
+import { fitsTask, stagesOf, taskInProgress, workStarted } from '../stages.js';
 /**
  * How the wizard's screens look, drawn as lines from what they show and the
  * terminal's size, with no terminal behind them: the smoke renders every
@@ -270,12 +270,17 @@ function runPage(scene, f, inner, st) {
                             : '○';
         const ink = t.status === 'in_progress' || t.status === 'failed' ? st.full : t.status === 'skipped' ? st.faint : st.soft;
         const row = (detail) => `${mark} ${t.title}${detail ? ` · ${detail}` : ''}`;
-        return { ink, row, line: t.status === 'skipped' || t.status === 'failed' ? row(t.status) : row() };
+        // Preview method back to pending while Test drive runs waits for the test drive's preview, which proves the method, as the playbook's Tasks rule says: its row says so, so its work never reads as undone (REN-1255).
+        const proving = t.started && t.status === 'pending' && running >= 0 && stagesOf(t.title).includes('Preview method') && stagesOf(scene.tasks[running].title).includes('Pull requests');
+        return { ink, row, line: t.status === 'skipped' || t.status === 'failed' ? row(t.status) : row(), proving };
     });
-    // The list's left edge is set by the rows without the wait's words, so it stays put while a wait comes and goes (#390).
+    // The list's left edge is set by the rows without the wait's words or the method's, so it stays put while they come and go (#390).
     const widest = Math.max(...rows.map(({ line }) => visibleWidth(line)));
     const room = inner - Math.max(0, Math.floor((inner - Math.min(widest, inner)) / 2));
-    const lines = rows.map(({ ink, row, line }, i) => {
+    const lines = rows.map(({ ink, row, line, proving }, i) => {
+        // The words that fit from the list's edge, shorter at a narrow width, and none where even those would be cut.
+        if (proving)
+            return ink(['finishes with the test drive', 'with the test drive'].map(row).find((words) => visibleWidth(words) <= room) ?? line);
         if (i !== running || !scene.wait)
             return ink(line);
         // The task in progress says what the run waits for and the time so far, never how long it may wait, so a screen

package/dist/vercel.js

@@ -103,6 +103,63 @@ export const readDeploymentApi = (link, host) => ['api', `/v13/deployments/${enc
  * (https://vercel.com/docs/deployment-protection/methods-to-protect-deployments/vercel-authentication#how-to-manage-vercel-authentication-with-the-api).
  */
 export const lockProjectApi = (link) => projectApi(link, ['--field', 'ssoProtection={"deploymentType":"all"}']);
+/**
+ * Vercel's deployments recorded on GitHub, which is where Impeccable finds Vercel's previews: Settings → Git →
+ * "deployment_status Events" in the dashboard, `gitProviderOptions.createDeployments` to the API. A project the CLI or
+ * the API creates starts with it disabled.
+ */
+export const githubDeploymentsApi = (link) => projectApi(link, ['--field', 'gitProviderOptions={"createDeployments":"enabled"}']);
+/** The dashboard's label for that setting, as a screen or a report names it. */
+export const DEPLOYMENT_EVENTS = 'deployment_status Events';
+/** Why Impeccable sees none of a project's previews while that setting is off. */
+export const DEPLOYMENTS_OFF = `Vercel builds the project's pushes but records no deployment of them on GitHub, where Impeccable finds Vercel's previews: ${DEPLOYMENT_EVENTS} is off under the project's Settings → Git.`;
+/**
+ * Turns on the project's deployments on GitHub through the CLI signed in as the person, where they are off, and reads the
+ * project back: enabled only once Vercel says so. The project counts only as this repository's (readOwnProject). `page`
+ * is the project's Settings → Git, where the person turns it on when Vercel refused the run.
+ */
+export async function enableGithubDeployments(vercel, link, repository, page) {
+    const fact = (project) => 'reason' in project
+        ? { project: '', enabled: 'unknown', reason: project.reason }
+        : { project: project.name ?? '', enabled: project.githubDeployments, ...(project.githubDeployments ? {} : { cause: 'previews', reason: DEPLOYMENTS_OFF }) };
+    const before = await readOwnProject(vercel, link, repository);
+    if ('reason' in before || before.githubDeployments)
+        return { fact: fact(before), page, changed: false, ...('reason' in before ? { reason: before.reason } : {}) };
+    try {
+        await vercel(githubDeploymentsApi(link));
+    }
+    catch {
+        return { fact: fact(before), page, changed: false, reason: `Vercel refused to turn on ${DEPLOYMENT_EVENTS} for the project: that takes the Member role or Project Administrator.` };
+    }
+    const after = await readOwnProject(vercel, link, repository);
+    return { fact: fact(after), page, changed: !('reason' in after) && after.githubDeployments };
+}
+/**
+ * The deployment a commit status of Vercel's names, read through the CLI: its `target_url` is the deployment's page in
+ * Vercel's dashboard, `https://vercel.com/<scope>/<project>/<id>`, whose last part is the deployment's id less `dpl_`.
+ * Only a deployment of the linked project, of the commit `sha`, counts: `other` for another project's or commit's, null
+ * where it could not be read.
+ */
+export async function deploymentOfStatus(vercel, link, targetUrl, sha) {
+    const id = /^https:\/\/vercel\.com\/[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+\/([A-Za-z0-9]{8,64})$/.exec(targetUrl)?.[1];
+    if (!id)
+        return null;
+    try {
+        const d = await printedProject(vercel, readDeploymentApi(link, `dpl_${id}`));
+        const host = typeof d?.url === 'string' && /^[a-z0-9.-]{1,253}$/i.test(d.url) ? d.url.toLowerCase() : undefined;
+        if (!d)
+            return null;
+        // Vercel named another project's deployment, or one of another commit: a status that is not this build's.
+        if (d.projectId !== link.projectId || record(d.meta)?.githubCommitSha !== sha)
+            return 'other';
+        if (!host)
+            return null;
+        return { url: `https://${host}`, name: typeof d.name === 'string' ? d.name : '', production: d.target === 'production' };
+    }
+    catch {
+        return null;
+    }
+}
 const record = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined);
 const printedProject = async (vercel, args) => {
     const printed = await vercel(args);
@@ -268,7 +325,7 @@ export async function vercelPreviewsFact(cwd, repository, vercel, app) {
     if (own && 'reason' in own)
         return { ...fact, enabled: 'unknown', reason: own.reason };
     if (project && !project.githubDeployments)
-        return { ...fact, enabled: false, reason: 'The project records no deployments on GitHub (Vercel GitHub deployments are off), and GitHub\'s record is where Impeccable finds Vercel\'s previews.' };
+        return { ...fact, enabled: false, cause: 'previews', reason: DEPLOYMENTS_OFF };
     if (project?.ignoredBuildStep)
         return { ...fact, enabled: 'unknown', reason: 'An Ignored Build Step is set on the project (Settings → Git), which decides commit by commit whether a push builds.' };
     return fact;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impeccable/reviews",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "Set up a repository for Impeccable for PRs from your terminal.",
   "license": "SEE LICENSE IN LICENSE",
   "private": false,