@impeccable/reviews 0.1.1 → 0.1.3

package/dist/tools.js

@@ -7,12 +7,12 @@ import { request } from 'node:http';
 import { createServer } from 'node:net';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { defineTool } from '@earendil-works/pi-coding-agent';
-import { agreeToHostSetup, bindPreviewPullRequest, chooseHostTeam, classifyPreviewCommand, hostSetupAgreed, isSecretFile, observePreviewAttempts, parseCommand, previewRetryState, settleVercelFirstDeployment } from './fence.js';
+import { agreeToHostSetup, bindPreviewPullRequest, chooseHostTeam, classifyPreviewCommand, endHostSetup, hostSetupAgreed, isSecretFile, observePreviewAttempts, parseCommand, previewRetryState, settleVercelFirstDeployment } from './fence.js';
 import { requestJson } from './http.js';
 import { appsLeftOut, focusCheckup, focusInstructions, focusState, severalApps } from './focus.js';
 import { HOST_QUESTIONS, HOST_SCREENS } from './host-questions.js';
 import { netlifySiteOf, previewHostName, provePreview, readHostedPreviews } from './hosted.js';
-import { pagesProject, readCloudflarePreviews } from './cloudflare.js';
+import { cfRunner, pagesProject, readCloudflarePreviews } from './cloudflare.js';
 import { passCloudflareAccess } from './cloudflare-access.js';
 import { commandRunner, connectNetlifySite, netlifyStatus, netlifyTeams, readNetlifyPreviews, waitForNetlifyAccess } from './netlify.js';
 import { basicCredentials, PASSWORD_HEADER, passNetlifyLock } from './netlify-password.js';
@@ -20,6 +20,7 @@ import { connectVercelProject, lockedDeploymentHosts, prepareFirstDeployment, ve
 import { BYPASS_HEADER, passVercelLogin, readLink } from './vercel-bypass.js';
 import { fitsTask, stagesOf } from './stages.js';
 import { redact } from './log.js';
+import { gitEnvironment } from './sandbox.js';
 import { openBrowser } from './login.js';
 import { TASK_STATUSES } from './sync.js';
 import { askPerson, reportStatus, reportTasks, reportWait } from './ui/bridge.js';
@@ -409,7 +410,7 @@ async function stopPreviewChild(child) {
     catch { /* already stopped */ }
 }
 /** Local reproduction only: no credentials, external database, response body or process output leaves this helper. */
-export async function verifyLocalPreview(input, root, signal) {
+export async function verifyLocalPreview(input, root, signal, sandbox) {
     const probes = [];
     const fail = (stage, reason) => ({ verified: false, stage, reason, probes });
     if (process.platform === 'win32')
@@ -506,8 +507,11 @@ export async function verifyLocalPreview(input, root, signal) {
         scratch = await realpath(await mkdtemp(join('/tmp', 'impeccable-preview-')));
         const snapshot = join(scratch, 'checkout'), home = join(scratch, 'home'), temp = join(scratch, 'tmp');
         await Promise.all([snapshot, home, temp].map((p) => mkdir(p, { mode: 0o700 })));
+        // The app's own commands run in a sandbox of their own, writing only in this folder; the check's git and Docker run outside it.
+        const inSandbox = sandbox?.preview(scratch);
+        const confined = (command, processEnv) => inSandbox?.(command, processEnv) ?? { file: '/bin/sh', args: ['-c', command], env: processEnv };
         env = { ...env, ...supplied, ...(serverInput ? { PORT: String(serverInput.port) } : {}), HOME: home, TMPDIR: temp, TMP: temp, TEMP: temp, XDG_CONFIG_HOME: join(home, '.config'), npm_config_cache: join(scratch, 'npm'), npm_config_userconfig: join(home, '.npmrc'), npm_config_globalconfig: join(scratch, 'global-npmrc'), PIP_CONFIG_FILE: '/dev/null', PIP_NO_INPUT: '1', PIP_DISABLE_PIP_VERSION_CHECK: '1', PIP_REQUIRE_VIRTUALENV: 'true', BUNDLE_PATH: join(scratch, 'bundle'), BUNDLE_APP_CONFIG: join(scratch, 'bundle-config') };
-        const listing = await run('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z'], root, true);
+        const listing = await run('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z'], root, true, 120_000, signal ?? null, gitEnvironment(env));
         if (!listing.ok)
             return fail(stage, 'Could not list checkout files.');
         const files = [...new Set(listing.output.split('\0').filter(Boolean))];
@@ -547,7 +551,7 @@ export async function verifyLocalPreview(input, root, signal) {
             await copyFile(source, target);
             await chmod(target, info.mode & 0o777);
             if (file.split('/').at(-1) === 'package.json') {
-                const baseline = await run('git', ['show', `HEAD:${file}`], root, true);
+                const baseline = await run('git', ['show', `HEAD:${file}`], root, true, 120_000, signal ?? null, gitEnvironment(env));
                 const scripts = (value) => Object.entries(JSON.parse(value).scripts ?? {}).sort(([a], [b]) => a.localeCompare(b));
                 scriptsChanged ||= !baseline.ok || JSON.stringify(scripts(baseline.output)) !== JSON.stringify(scripts(await readFile(source, 'utf8')));
             }
@@ -629,8 +633,9 @@ export async function verifyLocalPreview(input, root, signal) {
             }
             if (!executable)
                 return fail(stage, 'The required Python runtime or virtual environment is unavailable.');
-            // Precreate even for explicit bootstrap steps so every command in a compound step uses it.
-            if (!(await run(executable, ['-m', 'venv', '.venv'], directory)).ok)
+            // Precreate even for explicit bootstrap steps so every command in a compound step uses it. `-m` imports from the folder, the checkout's code, so it runs in the sandbox too.
+            const venv = confined(`'${executable.replace(/'/g, `'\\''`)}' -m venv .venv`, env);
+            if (!(await run(venv.file, venv.args, directory, false, 120_000, signal ?? null, venv.env)).ok)
                 return fail(stage, 'The required Python runtime or virtual environment is unavailable.');
         }
         const environmentFor = (directory) => {
@@ -666,7 +671,8 @@ export async function verifyLocalPreview(input, root, signal) {
         }
         for (const [index, step] of input.steps.entries()) {
             stage = step.phase;
-            if (!(await run('/bin/sh', ['-c', step.command], directories[index], false, 120_000, signal ?? null, environmentFor(directories[index]))).ok)
+            const command = confined(step.command, environmentFor(directories[index]));
+            if (!(await run(command.file, command.args, directories[index], false, 120_000, signal ?? null, command.env)).ok)
                 return fail(stage, signal?.aborted ? 'Verification was cancelled.' : 'The local step failed or exceeded two minutes; its output was not retained.');
         }
         if (staticInput) {
@@ -682,7 +688,8 @@ export async function verifyLocalPreview(input, root, signal) {
         const free = await new Promise((done) => { const check = createServer(); check.once('error', () => done(false)); check.listen(serverInput.port, '127.0.0.1', () => check.close(() => done(true))); });
         if (!free)
             return fail(stage, 'The preview port is already in use; an existing service was not probed.');
-        server = spawn('/bin/sh', ['-c', serverInput.start.command], { cwd: directories.at(-1), env: environmentFor(directories.at(-1)), detached: true, stdio: 'ignore' });
+        const start = confined(serverInput.start.command, environmentFor(directories.at(-1)));
+        server = spawn(start.file, start.args, { cwd: directories.at(-1), env: start.env, detached: true, stdio: 'ignore' });
         let exited = false;
         server.once('error', () => { exited = true; });
         server.once('exit', () => { exited = true; });
@@ -746,7 +753,7 @@ const execFileAsync = promisify(execFile);
  */
 export async function driveCoversSetup(cwd, setupBranch, driveBranch) {
     try {
-        await execFileAsync('git', ['merge-base', '--is-ancestor', `refs/remotes/origin/${setupBranch}`, `refs/remotes/origin/${driveBranch}`], { cwd, timeout: 10_000 });
+        await execFileAsync('git', ['merge-base', '--is-ancestor', `refs/remotes/origin/${setupBranch}`, `refs/remotes/origin/${driveBranch}`], { cwd, timeout: 10_000, env: gitEnvironment() });
         return true;
     }
     catch (err) {
@@ -981,11 +988,11 @@ export function workflowGitEnvironment() {
                 'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_CURL_VERBOSE', 'GIT_CONFIG_PARAMETERS', 'GIT_CONFIG',
                 'GIT_CEILING_DIRECTORIES', 'GIT_DISCOVERY_ACROSS_FILESYSTEM', 'GIT_PREFIX', 'GIT_ASKPASS', 'SSH_ASKPASS'].includes(key))
             delete env[key];
-    return Object.assign(env, { GIT_TERMINAL_PROMPT: '0', GH_PROMPT_DISABLED: '1', GCM_INTERACTIVE: 'never',
+    return gitEnvironment(Object.assign(env, { GIT_TERMINAL_PROMPT: '0', GH_PROMPT_DISABLED: '1', GCM_INTERACTIVE: 'never',
         GIT_ASKPASS: '', SSH_ASKPASS: '', SSH_ASKPASS_REQUIRE: 'never', GIT_SSH_VARIANT: 'ssh',
         GIT_SSH_COMMAND: 'ssh -o BatchMode=yes -o StrictHostKeyChecking=yes',
         // Removing the variables alone still permits globally configured trace2 targets.
-        GIT_TRACE2: '0', GIT_TRACE2_EVENT: '0', GIT_TRACE2_PERF: '0' });
+        GIT_TRACE2: '0', GIT_TRACE2_EVENT: '0', GIT_TRACE2_PERF: '0' }));
 }
 const record = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
 export function workflowDefaultBranch(value) {
@@ -1413,16 +1420,16 @@ export function createTools(ctx) {
     let provenHost;
     let savedHost;
     /**
-     * A host's build, waited for on the screen as the task in progress with its timer: `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 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.
      */
-    async function awaitBuild(status, read, built, signal) {
+    async function awaitBuild(host, status, read, built, signal) {
         let evidence = await read();
         if (built(evidence))
             return evidence;
         const wait = ctx.previewWait ?? { totalMs: 300_000, everyMs: 15_000 };
         said(status);
-        reportWait({ since: Date.now(), limitMs: wait.totalMs });
+        reportWait({ since: Date.now(), host });
         try {
             for (const end = Date.now() + wait.totalMs; !built(evidence) && Date.now() < end; evidence = await read()) {
                 await sleep(wait.everyMs, undefined, { signal });
@@ -1528,6 +1535,12 @@ export function createTools(ctx) {
     const hostSignIns = new Map();
     /** The teams a host's sign-in offered, each by name and slug: the choices a `<host>-team` question shows, whatever the model lists, so the pick the fence takes is a slug. */
     const teamChoices = new Map();
+    /** A host's setup ended before anything was set up on the host: nothing more is asked for it, and the fence lets its CLI and its hold on pushes go. */
+    const endSetup = (host) => {
+        hostSignIns.set(host, 'skipped');
+        teamChoices.delete(host);
+        endHostSetup(ctx.log, host);
+    };
     const HOST_NAMES = { netlify: 'Netlify', vercel: 'Vercel' };
     const hostCli = (host, pi, signal) => {
         const runner = (browser = false) => (ctx.hostRunner ?? commandRunner)(host, pi.cwd, { signal, browser, timeoutMs: browser ? 300_000 : 30_000 });
@@ -1577,7 +1590,7 @@ export function createTools(ctx) {
         if (!hostSignIns.has(host)) {
             const answer = await ask({ id: `${host}-setup`, ...HOST_QUESTIONS[`${host}-setup`] });
             if (answer.skipped) {
-                hostSignIns.set(host, 'skipped');
+                endSetup(host);
                 return { skipped: true };
             }
             hostSignIns.set(host, 'confirmed');
@@ -1599,11 +1612,11 @@ export function createTools(ctx) {
             if (status.cli === 'signed-in')
                 return signedIn();
             if (attempt === 2) {
-                hostSignIns.set(host, 'skipped');
+                endSetup(host);
                 return { skipped: true, reason: `The ${HOST_NAMES[host]} sign-in did not complete.` };
             }
             if ((await ask(HOST_SCREENS[`${host}-signin-retry`])).skipped) {
-                hostSignIns.set(host, 'skipped');
+                endSetup(host);
                 return { skipped: true };
             }
         }
@@ -1742,7 +1755,7 @@ export function createTools(ctx) {
     return [
         tool('impeccable_workflow_access', 'Check workflow access', 'Check that the setup pull request can carry the workflow: reads the active GitHub CLI account and its scopes, the origin remote and the default branch, and refreshes origin/<defaultBranch>. Call it before branching. needsWorkflowScope true means the account lacks workflow access over HTTPS; base.status "refreshed" means origin/<defaultBranch> is current. Only the push itself proves Git may push.', NO_INPUT, (_p, pi, signal) => workflowAccessTool(pi, signal)),
         tool('impeccable_sync_workflow', 'Update the preview workflow', 'Write the state\'s workflow to .github/workflows/impeccable-preview.yml byte for byte and remove the retired workflow the state names, after checking access as impeccable_workflow_access does. Call it once the settings are saved, and again after committing: stagedMatches and committedMatches true (and retiredRemoval staged and committed) prove the commit holds the exact bytes; null means nothing was compared. It refuses, changing nothing, when the file has the person\'s local edits. It never branches, stages, commits or pushes.', NO_INPUT, (_p, pi, signal) => syncWorkflowTool(pi, signal)),
-        tool('impeccable_verify_preview', 'Check the local preview', 'Prove the preview on this machine before saving it: runs the steps in a throwaway copy of the checkout, with a throwaway database, and removes everything afterwards. For a server give start, port, paths and host: it starts the app and requests each path as localhost and as the tunnel host. For a static site give output: it checks the build wrote the entry pages. verified covers HTTP answers and files only, never rendering, sign-in or the CI runtime; a failure names its stage.', PREVIEW_VERIFICATION, async (p, pi, signal) => JSON.stringify(await verifyLocalPreview(p, pi.cwd, signal))),
+        tool('impeccable_verify_preview', 'Check the local preview', 'Prove the preview on this machine before saving it: runs the steps in a throwaway copy of the checkout, with a throwaway database, and removes everything afterwards. For a server already on Impeccable\'s tunnel give start, port, paths and host: it starts the app and requests each path as localhost and as the tunnel host. For a static site give output: it checks the build wrote the entry pages. verified covers HTTP answers and files only, never rendering, sign-in or the CI runtime; a failure names its stage.', PREVIEW_VERIFICATION, async (p, pi, signal) => JSON.stringify(await verifyLocalPreview(p, pi.cwd, signal, ctx.sandbox))),
         tool('impeccable_preview_run', 'Read the preview attempt', 'On a rerun, once impeccable_test_pr recorded the setup pull request: read its preview workflow\'s runs. Answers each attempt with its failed stage and a fixed reason (never log text), the three-attempt budget (used, remaining, historyKnown), and adds the attempts to the task list. Reading is free.', PREVIEW_RUN, async (p, pi, signal) => {
             if (!retry.pr)
                 return 'Refused: record the setup pull request with impeccable_test_pr first.';
@@ -1819,6 +1832,9 @@ export function createTools(ctx) {
                 return `Refused: ${target.error}`;
             if (/\/(preview-auth\/[^/]+|preview-protection)$/.test(target.url))
                 return "Refused: a host's key is saved by impeccable_vercel_bypass (a Vercel bypass secret), impeccable_netlify_password (a Netlify site password) or impeccable_cloudflare_access (a Cloudflare Access service token), which opens the preview with it first, and never through this tool. Nothing was saved.";
+            if (target.url.endsWith('/preview') && object(p.body)?.intendedMethod === 'ci-tunnel') {
+                return "Refused: Impeccable no longer runs a server in CI for a new setup, so ci-tunnel is never saved. Pages that need a server get their host's pull request previews, as the server-previews case says. Nothing was saved.";
+            }
             if (target.url.endsWith('/preview') && object(p.body)?.intendedMethod === 'preview-deploy' && !hostedPreviewProven) {
                 return "Refused: prove a preview address with impeccable_prove_preview first: the host's previews become the method only once one answered with this app. Nothing was saved.";
             }
@@ -1842,7 +1858,7 @@ export function createTools(ctx) {
             const response = await call(pi, target.url, { method: target.method, body });
             if (target.url.endsWith('/preview') && response.ok) {
                 const keys = object(object(response.data)?.keys);
-                if (keys?.intendedMethod === 'stored' && ['ci-tunnel', 'static-upload'].includes(String(object(p.body)?.intendedMethod)))
+                if (keys?.intendedMethod === 'stored' && object(p.body)?.intendedMethod === 'static-upload')
                     retry.requireHistory = true;
                 if (object(p.body)?.intendedMethod === 'preview-deploy')
                     savedHost = provenHost;
@@ -1884,8 +1900,12 @@ export function createTools(ctx) {
             if (error)
                 return `Invalid input: ${error}.`;
             const answer = await askPerson(q);
-            if (answer.skipped)
+            if (answer.skipped) {
+                // Without a terminal the Vercel CLI names no team on its own, so a skipped team ends the Vercel setup.
+                if (host?.[1] === 'vercel')
+                    endSetup('vercel');
                 return JSON.stringify({ skipped: true });
+            }
             if (q.kind === 'multi')
                 return JSON.stringify({ values: answer.values ?? [] });
             if (q.kind === 'confirm') {
@@ -1986,7 +2006,7 @@ export function createTools(ctx) {
             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'));
-            const evidence = branch !== undefined ? await awaitBuild(`Waiting for Vercel to build ${testDriveBranch(branch) ? "the test drive's preview" : `the preview of ${branch}`}`, read, final, signal) : await read();
+            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, signal) : await read();
             listedPreviews.clear();
             vercelMade.clear();
             publicProduction.clear();
@@ -2019,24 +2039,24 @@ 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(`Waiting for Netlify to build ${await subjectOf(pull)}`, read, final, signal) : await read();
+            const evidence = pull !== undefined ? await awaitBuild('Netlify', `Waiting for Netlify to build ${await subjectOf(pull)}`, read, final, signal) : await read();
             netlifyListed.clear();
             for (const p of evidence.previews)
                 if (p.state === 'success' || p.state === 'ready')
                     netlifyListed.add(new URL(p.url).origin);
             return JSON.stringify(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, or wrangler on this machine when it is signed in (read only: it never signs in). cli says whether wrangler 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 wrangler. 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. 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, or cf, Cloudflare's CLI, on this machine when it is signed in (read only: it never signs in). 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. 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. 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)
                 return 'Invalid input: give pull or branch, not both.';
             const read = () => (ctx.cloudflarePreviewReader ?? readCloudflarePreviews)(ctx.owner, ctx.repo, pi.cwd, { signal, pull, branch });
-            // Cloudflare posts its check run once the build ended: until then the head lists nothing, or wrangler's row says it is building.
-            // GitHub's record unread ends the wait; wrangler's alone does not, since the check run still says when the build ends.
+            // Cloudflare posts its check run once the build ended: until then the head lists nothing, or cf's row says it is building.
+            // GitHub's record unread ends the wait; cf's alone does not, since the check run still says when the build ends.
             const final = (evidence) => Boolean(evidence.unread?.includes('GitHub')) || evidence.previews.some((preview) => preview.state !== 'building');
             const subject = branch !== undefined ? (testDriveBranch(branch) ? "the test drive's preview" : `the preview of ${branch}`) : pull !== undefined ? await subjectOf(pull) : '';
-            const evidence = subject ? await awaitBuild(`Waiting for Cloudflare Pages to build ${subject}`, read, final, signal) : await read();
+            const evidence = subject ? await awaitBuild('Cloudflare', `Waiting for Cloudflare Pages to build ${subject}`, read, final, signal) : await read();
             cloudflareListed.clear();
             for (const preview of evidence.previews) {
                 if (preview.state !== 'success')
@@ -2142,15 +2162,14 @@ export function createTools(ctx) {
             const at = gated;
             /** The address pattern the proof with the password answers, saved as the method once the password is. */
             let pattern;
-            const prove = async (password) => {
-                const proof = await provePreview(at.url, at.expect, pi.cwd, { fetch: ctx.previewFetch, signal, password });
+            const prove = async (password, form = false) => {
+                const proof = await provePreview(at.url, at.expect, pi.cwd, { fetch: ctx.previewFetch, signal, password, form });
                 if (proof.proven && proof.pattern)
                     pattern = proof.pattern;
                 return proof;
             };
-            // A password in hand already: another deploy preview of the same site opens with it.
-            if (passwordSaved && sitePassword && (await prove(sitePassword)).proven) {
-                passwordSites.add(site);
+            // A password in hand already: another deploy preview of the same site opens with it. Another site's lock is read for that site.
+            if (passwordSaved && sitePassword && passwordSites.has(site) && (await prove(sitePassword)).proven) {
                 provenPattern = pattern ?? provenPattern;
                 return JSON.stringify(passwordSaved);
             }
@@ -2197,7 +2216,7 @@ export function createTools(ctx) {
             }
             return JSON.stringify(passwordOutcome);
         }),
-        tool('impeccable_cloudflare_access', 'Cloudflare Access', 'Get past the Cloudflare Access login that impeccable_prove_preview met (gate "cloudflare-access") in front of a Cloudflare Pages preview, the way Cloudflare documents for tools: a service token, sent in two headers, that a Service Auth policy of the Access application allows. It does the rest as the person: one screen asking to create the token and one taking the Cloudflare API token that creating it takes, then the token named "Impeccable reviews" created and allowed in the policy of the application in front of the preview; on a skip, or where that cannot be done, one screen taking a pasted client id and secret. It opens the preview with the token and saves it for reviews. Answers {"status": …}: saved (the preview is proven, and pattern is the address pattern to save with the method; token says whether it was created or typed, application which Access application allows it, expires when a created one runs out), skipped (nothing was saved; reason says what stopped it), refused (the typed token did not open the preview; reason says what the address answered) or save-failed (the setup API did not take it all; reason says how far it got: call it once more). No token ever comes back.', NO_INPUT, async (_p, pi, signal) => {
+        tool('impeccable_cloudflare_access', 'Cloudflare Access', 'Get past the Cloudflare Access login that impeccable_prove_preview met (gate "cloudflare-access") in front of a Cloudflare Pages preview, the way Cloudflare documents for tools: a service token, sent in two headers, that a Service Auth policy of the Access application allows. It does the rest as the person: one screen asking to create the token, Cloudflare\'s sign-in in the browser where cf, Cloudflare\'s CLI, is not signed in here with Access (with a retry), then the token named "Impeccable reviews" created through cf and allowed in the policy of the application in front of the preview; one screen taking a Cloudflare API token only where that sign-in cannot create it; on a skip, or where that cannot be done, one screen taking a pasted client id and secret. It opens the preview with the token and saves it for reviews. Answers {"status": …}: saved (the preview is proven, and pattern is the address pattern to save with the method; token says whether it was created or typed, application which Access application allows it, expires when a created one runs out, apiToken true when the person\'s Cloudflare API token created it), skipped (nothing was saved; reason says what stopped it), refused (the typed token did not open the preview; reason says what the address answered) or save-failed (the setup API did not take it all; reason says how far it got: call it once more). No token ever comes back.', NO_INPUT, async (_p, pi, signal) => {
             if (!accessGated)
                 return 'Refused: this is for a Cloudflare Pages preview impeccable_cloudflare_previews listed, which impeccable_prove_preview answered with gate "cloudflare-access". Prove one first.';
             if (accessOutcome?.status === 'skipped')
@@ -2228,6 +2247,10 @@ export function createTools(ctx) {
                 answer = await passCloudflareAccess({
                     url: at.url,
                     consent: async () => !(await ask(HOST_SCREENS['cloudflare-access'])).skipped,
+                    cf: cfRunner({}, ctx.hostRunner),
+                    login: cfRunner({ browser: true, timeoutMs: 300_000 }, ctx.hostRunner),
+                    retry: async () => !(await ask(HOST_SCREENS['cloudflare-signin-retry'])).skipped,
+                    status: said,
                     apiToken: async () => {
                         const typed = await ask(HOST_SCREENS['cloudflare-access-api']);
                         return typed.skipped ? undefined : typed.value;
@@ -2250,7 +2273,7 @@ export function createTools(ctx) {
                     accessProjects.clear();
                 accessToken = value;
                 accessStored = told.status === 'saved';
-                accessMade = { ...(told.token ? { token: told.token } : {}), ...(told.application ? { application: told.application } : {}), ...(told.expires ? { expires: told.expires } : {}) };
+                accessMade = { ...(told.token ? { token: told.token } : {}), ...(told.application ? { application: told.application } : {}), ...(told.expires ? { expires: told.expires } : {}), ...(told.apiToken ? { apiToken: told.apiToken } : {}) };
                 const project = pagesProject(new URL(at.url).origin);
                 if (project)
                     accessProjects.add(project);

package/dist/ui/look.js

@@ -230,9 +230,15 @@ function runPage(scene, f, inner, st) {
                     : t.status === 'skipped' ? '–'
                         : '○';
         const ink = t.status === 'in_progress' || t.status === 'failed' ? st.full : t.status === 'skipped' ? st.faint : st.soft;
-        // The task in progress carries the wait's timer, so a screen waiting on a host's build is never still.
-        const detail = t.status === 'skipped' || t.status === 'failed' ? t.status : i === running && scene.wait ? scene.wait : undefined;
-        return ink(`${mark} ${t.title}${detail ? ` · ${detail}` : ''}`);
+        const row = (detail) => `${mark} ${t.title}${detail ? ` · ${detail}` : ''}`;
+        if (t.status === 'skipped' || t.status === 'failed')
+            return ink(row(t.status));
+        if (i !== running || !scene.wait)
+            return ink(row());
+        // The task in progress says what the run waits for and the time so far, never how long it may wait, so a screen
+        // waiting on a host's build is never still; the time alone where the words would push it off the row.
+        const waiting = row(`waiting for ${scene.wait.host ? `${scene.wait.host}'s preview` : 'the preview'} · ${scene.wait.timer}`);
+        return ink(visibleWidth(waiting) <= inner ? waiting : row(scene.wait.timer));
     });
     const counted = scene.tasks.filter((t) => t.status !== 'skipped');
     const skipped = scene.tasks.length - counted.length;
@@ -277,8 +283,10 @@ function pageOf(f, inner) {
     switch (scene.kind) {
         case 'wait':
             return { heading: START.heading, text: said(START.text, inner, st), rule: divider(inner, st), action: [center(st.faint('One moment…'), inner)] };
-        case 'intro':
-            return { heading: START.heading, text: said(START.text, inner, st), rule: divider(inner, st), action: [center(st.full("Let's start with login"), inner)], ways: [['Continue', 'Enter']] };
+        case 'intro': {
+            const note = scene.note ? ['', ...block(hang(scene.note, Math.min(TEXT_WIDTH, inner), '! ').map(st.soft), inner)] : [];
+            return { heading: START.heading, text: said(START.text, inner, st), rule: divider(inner, st), action: [center(st.full("Let's start with login"), inner), ...note], ways: [['Continue', 'Enter']] };
+        }
         case 'signin': {
             // P still takes a pasted code on a remote shell; --help says so, the screen does not.
             const under = scene.note ?? (scene.copied ? 'Copied to clipboard!' : '');

package/dist/ui/run-state.js

@@ -24,7 +24,7 @@ export class RunState {
     tasks = [];
     previous;
     current;
-    /** A bounded wait under way: the current line carries its timer, counting up to the limit. */
+    /** A bounded wait under way: the current line carries its timer, counting up. */
     waiting;
     /** When something last changed on screen: a status, the task list, an answered question. */
     changedAt;
@@ -51,12 +51,12 @@ export class RunState {
         this.touch();
     }
     /**
-     * The wait's timer, "1:05 of 5:00", while one is under way: the task in progress carries it on the tasks screen.
-     * `live` false gives the wait's start, "0:00 of 5:00", the same on every tick: a drawing that changes only when
-     * a wait begins or ends, so the frames record the wait once rather than once a second.
+     * The wait under way, which the task in progress carries on the tasks screen: the host whose preview it is and the
+     * time so far, "1:05". `live` false gives the wait's start, "0:00", the same on every tick: a drawing that changes
+     * only when a wait begins or ends, so the frames record the wait once rather than once a second.
      */
     timer(live = true) {
-        return this.waiting ? `${timer(live ? this.now() - this.waiting.since : 0)} of ${timer(this.waiting.limitMs)}` : undefined;
+        return this.waiting && { host: this.waiting.host, timer: timer(live ? this.now() - this.waiting.since : 0) };
     }
     setTasks(tasks) {
         this.tasks = tasks.map((t) => ({ ...t }));
@@ -70,14 +70,14 @@ export class RunState {
      * The band's two lines as they read now: after a minute with nothing new the
      * last line moves up, dimmed, under "Still working…" and the time since.
      * `quiet` is false while the person is being asked. During a bounded wait
-     * the current line carries the timer, "1:05 of 5:00", so the screen never
+     * the current line carries the timer, "1:05", so the screen never
      * looks stalled; `live` false holds the timer at the wait's start, for a
      * drawing that changes only when the words do.
      */
     band(quiet = true, live = true) {
-        if (this.waiting && this.current) {
-            return { previous: this.previous, current: `${this.current} · ${this.timer(live)}` };
-        }
+        const wait = this.timer(live);
+        if (wait && this.current)
+            return { previous: this.previous, current: `${this.current} · ${wait.timer}` };
         const silence = this.now() - this.changedAt;
         if (quiet && silence >= SILENCE_MS)
             return { previous: this.current, current: `Still working… ${elapsed(silence)}` };

package/dist/ui/screens.js

@@ -1,13 +1,17 @@
 import { readFileSync } from 'node:fs';
 import { format } from 'node:util';
 import { CURSOR_MARKER, getCapabilities, Input, KeybindingsManager, matchesKey, ProcessTerminal, setKeybindings, TUI_KEYBINDINGS, TuiAltScreen } from '@earendil-works/pi-tui';
-import { readCheckout } from '../preflight.js';
 import { copyText } from '../login.js';
 import { workStarted } from '../stages.js';
 import { mountUi } from './bridge.js';
 import { createFrameWriter, frameState } from './frames.js';
 import { drawFrame, OUTCOME, PRODUCT, palette } from './look.js';
 import { RunState } from './run-state.js';
+/** What the command does before a screen ends it at once (Ctrl+C before a run, or a signal): report the stop (main.ts), briefly. */
+let beforeExit = async () => { };
+export function onScreenExit(fn) {
+    beforeExit = fn;
+}
 /** How often what moves on screen moves: the loader, the spinner. */
 const TICK_MS = 80;
 /** The run screen's first line, before the agent has said anything. */
@@ -44,7 +48,7 @@ class Wizard {
     onExit = () => this.stop();
     onSignal = (signal) => {
         this.stop();
-        process.kill(process.pid, signal);
+        void beforeExit('terminated').finally(() => process.kill(process.pid, signal));
     };
     constructor() {
         // The alternate screen's own scrolling and search keys stay off: the wizard draws every row, and a typed answer keeps Home and End.
@@ -228,7 +232,8 @@ class Wizard {
         const run = this.views.find((v) => v.kind === 'run');
         if (!run) {
             this.stop();
-            process.exit(130);
+            void beforeExit('ctrl_c').finally(() => process.exit(130));
+            return;
         }
         this.stopAsked = 0;
         for (const question of this.questions.splice(0))
@@ -330,7 +335,7 @@ class Wizard {
         if (!view)
             return { kind: 'wait' };
         if (view.kind === 'intro')
-            return { kind: 'intro' };
+            return { kind: 'intro', note: view.note };
         if (view.kind === 'signin')
             return { kind: 'signin', link: view.link, copied: view.copied, again: view.again, note: view.pasting ? undefined : view.note };
         if (view.kind === 'pull')
@@ -401,30 +406,24 @@ function host() {
     wizard ??= new Wizard();
     return wizard;
 }
-function repository() {
-    try {
-        const checkout = readCheckout(process.cwd());
-        return `${checkout.owner}/${checkout.repo}`;
-    }
-    catch {
-        return undefined;
-    }
-}
 /** Writes every screen into `dir` as it changes (--frames), for the eval. */
 export function recordFrames(dir) {
     frames = createFrameWriter(dir);
 }
-/** The first screen: what the command does, and the way on. Resolves true to go on, false to cancel. */
-export function showIntro() {
+/** The first screen: what the command does, a warning to read before anything runs (`note`), and the way on; without a terminal, a line naming `repository`, the owner/name being set up. Resolves true to go on, false to cancel. */
+export function showIntro(repository, note) {
     const screen = host();
     if (!screen) {
-        console.log(`${PRODUCT}: setting up ${repository() ?? 'this repository'}.`);
+        console.log(`${PRODUCT}: setting up ${repository}.`);
+        if (note)
+            console.log(`! ${note}`);
         console.log();
         return Promise.resolve(true);
     }
     return new Promise((resolve) => {
         const view = {
             kind: 'intro',
+            note,
             done: (ok) => {
                 screen.remove(view);
                 if (ok)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impeccable/reviews",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Set up a repository for Impeccable for PRs from your terminal.",
   "license": "SEE LICENSE IN LICENSE",
   "private": false,
@@ -24,6 +24,7 @@
     "eval": "npm run build && node dist/eval/main.js"
   },
   "dependencies": {
+    "@anthropic-ai/sandbox-runtime": "0.0.78",
     "@earendil-works/pi-coding-agent": "~0.87.1",
     "@earendil-works/pi-tui": "~0.87.1"
   },

package/dist/playbook/cases/ci-tunnel.md

@@ -1,21 +0,0 @@
-### When this applies
-
-The pages need a server from this repository: SSR, API routes, or a backend the front end calls. A front end whose bundle builds on its own still needs its backend here.
-
-### Steps
-
-1. **Work out the commands** in the workflow's order: install, prepare, build, seed and start, each with the folder it runs in. Done when each has a command, or none, and a folder.
-2. **Prove them** with impeccable_verify_preview in server mode. Done when it answers `verified: true`; a failure names its `stage`, which the report explains, and pull-requests' "No preview, no test drive" says how the run goes on without a proof.
-3. **Save them** with impeccable_write to `preview`: `intendedMethod: "ci-tunnel"` and the settings you proved, from the keys `buildSettings` lists. Done when the answer's `keys` show each key stored or unchanged.
-
-### Reference
-
-- **Seed and migrate only a throwaway database**, never a shared or production one:
-  - **SQLite**: a relative file URL in `env` (`DATABASE_URL=file:./preview.db`), and the repository's schema setup as the prepare or seed step.
-  - **Postgres or MySQL**: `service`, which gives the steps their own `DATABASE_URL`.
-  - **Cloudflare D1**: `--local` migrations and seeds.
-- **The tunnel host refused** (localhost answers, the tunnel host gets a 403): allow the preview host in the framework's host check (Rails `config.hosts`, Django `ALLOWED_HOSTS` and `CSRF_TRUSTED_ORIGINS`, Vite `preview.allowedHosts`) for previews only, in the setup pull request; keep the check on.
-- **Readiness**: the job waits for `/` to answer. When only a base path answers, report it as a blocker: no setting points it elsewhere.
-- **Runtime**: compare `node --version` (or python, ruby, pnpm) with the repository's pins; the job sets its runtime from `runtimeVersion`, so a mismatch goes under "What is not verified".
-- **Env**: literal, non-secret values. A secret the app needs is `${{ secrets.NAME }}` in the saved `env`, and "Add the NAME repository secret" in `left`. A demo or test-login flag belongs in the preview's env only.
-- A verified result covers HTTP answers only: rendering and the CI runtime go under "What is not verified".