@impeccable/reviews 0.1.0

package/dist/tools.js

@@ -0,0 +1,2015 @@
+import { promisify } from 'node:util';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { execFile, spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { chmod, copyFile, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, symlink, unlink, writeFile } from 'node:fs/promises';
+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 } from './fence.js';
+import { requestJson } from './http.js';
+import { focusCheckup, focusState } from './focus.js';
+import { HOST_QUESTIONS, HOST_SCREENS } from './host-questions.js';
+import { previewHostName, provePreview, readHostedPreviews } from './hosted.js';
+import { commandRunner, connectNetlifySite, netlifyStatus, netlifyTeams, readNetlifyPreviews, waitForNetlifyAccess } from './netlify.js';
+import { connectVercelProject, vercelStatus, vercelTeams, waitForVercelAccess } from './vercel.js';
+import { BYPASS_HEADER, passVercelLogin, readLink } from './vercel-bypass.js';
+import { fitsTask, stagesOf } from './stages.js';
+import { redact } from './log.js';
+import { openBrowser } from './login.js';
+import { TASK_STATUSES } from './sync.js';
+import { askPerson, reportStatus, reportTasks, reportWait } from './ui/bridge.js';
+import { SEE_THE_REVIEW } from './ui/look.js';
+import { noteSensitiveAnswer } from './ui/sensitive.js';
+/** The first way `value` breaks `schema`, or null when it fits. */
+export function schemaError(schema, value, at = 'input') {
+    const types = schema.type === undefined ? [] : [schema.type].flat();
+    const kind = value === null ? 'null' : Array.isArray(value) ? 'array' : Number.isInteger(value) ? 'integer' : typeof value;
+    if (types.length && !types.some((t) => t === kind || (t === 'number' && kind === 'integer')))
+        return `${at} should be ${types.join(' or ')}`;
+    if (schema.enum && !schema.enum.includes(value))
+        return `${at} should be one of ${schema.enum.join(', ')}`;
+    if (typeof value === 'string' && schema.minLength !== undefined && value.trim().length < schema.minLength)
+        return `${at} should not be empty`;
+    if (typeof value === 'number' && schema.minimum !== undefined && value < schema.minimum)
+        return `${at} should be at least ${schema.minimum}`;
+    if (kind === 'array' && schema.items) {
+        for (const [i, item] of value.entries()) {
+            const error = schemaError(schema.items, item, `${at}[${i}]`);
+            if (error)
+                return error;
+        }
+    }
+    if (kind === 'object') {
+        const obj = value;
+        for (const key of schema.required ?? [])
+            if (obj[key] === undefined)
+                return `${at}.${key} is required`;
+        for (const [key, v] of Object.entries(obj)) {
+            const sub = schema.properties?.[key];
+            if (sub) {
+                const error = schemaError(sub, v, `${at}.${key}`);
+                if (error)
+                    return error;
+            }
+            else if (schema.additionalProperties === false)
+                return `${at}.${key} is not allowed`;
+        }
+    }
+    return null;
+}
+const MAX_ANSWER = 200_000;
+/** What the model reads back: the API's JSON, or a short error. */
+export function answerText(res) {
+    if (!res.ok)
+        return `Error${res.status ? ` ${res.status}` : ''}: ${res.error}`;
+    const text = typeof res.data === 'string' ? res.data : JSON.stringify(res.data, null, 2);
+    return text.length > MAX_ANSWER ? `${text.slice(0, MAX_ANSWER)}\n[cut at ${MAX_ANSWER} characters]` : text;
+}
+const endpointsOf = (instructions) => {
+    const endpoints = instructions?.endpoints;
+    return endpoints && typeof endpoints === 'object' ? endpoints : {};
+};
+/**
+ * The method and address for a write, from the instructions' own endpoints:
+ * only PUT and POST, only under /repos/{repo}/ for this repository. `path`
+ * can be the endpoint's tail ("preview"), its path, or its whole address.
+ */
+export function resolveWrite(instructions, setupApi, repo, path) {
+    const api = new URL(setupApi);
+    const base = `${api.pathname.replace(/\/$/, '')}/repos/${encodeURIComponent(repo)}/`;
+    let pathname;
+    try {
+        const url = new URL(/^(\/|https?:)/i.test(path) ? path : `${base}${path.replace(/^\.?\//, '')}`, api.origin);
+        if (url.origin !== api.origin)
+            return { error: `${path} is not on the setup API. Writes go to ${api.origin}${base}…` };
+        pathname = url.pathname;
+    }
+    catch {
+        return { error: `"${path}" is not a path.` };
+    }
+    if (!pathname.startsWith(base))
+        return { error: `Writes go under ${base}…, and ${pathname} is outside it.` };
+    for (const line of Object.values(endpointsOf(instructions))) {
+        const m = typeof line === 'string' ? /^(PUT|POST)\s+(\S+)$/.exec(line.trim()) : null;
+        if (!m)
+            continue;
+        const template = m[2].replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]+/i, '');
+        if (template.replaceAll('{repo}', encodeURIComponent(repo)) === pathname)
+            return { method: m[1], url: `${api.origin}${pathname}` };
+    }
+    return { error: `No PUT or POST in the instructions' "endpoints" matches ${pathname}. Pick one from there.` };
+}
+const NO_INPUT = { type: 'object', properties: {}, additionalProperties: false };
+/** The most a status line holds; longer text belongs in the report. */
+export const STATUS_MAX = 70;
+const STATUS_RULE = `Status lines are in the product voice: a present-tense verb phrase of at most ${STATUS_MAX} characters that says what is happening, such as "Running the build" or "Opening the setup pull request". No "I'm", "I am", "Let me", "I'll" or "trying to"; detail goes in the report. Nothing was saved: call impeccable_progress again with the status rephrased.`;
+/** Why a status line breaks the voice, with the rule to rephrase it by; null when it keeps it. The line is never rewritten here. */
+export function statusVoiceError(line) {
+    const text = line.trim();
+    const why = /^(i['’]m|i am|let me|i['’]ll)\b/i.test(text) || /\btrying to\b/i.test(text) ? 'it narrates like an assistant' : text.length > STATUS_MAX ? `it is ${text.length} characters long` : null;
+    return why ? `Refused: "${text}" does not fit the status line, because ${why}. ${STATUS_RULE}` : null;
+}
+/** Why the status line and the task list say different things, one task in progress at a time and the status its detail; null when they agree. */
+function stageError(status, tasks) {
+    const running = tasks.filter((t) => t.status === 'in_progress');
+    const again = 'Nothing was saved: call impeccable_progress again.';
+    if (running.length > 1)
+        return `Refused: ${running.map((t) => `"${t.title}"`).join(' and ')} are in progress at once. One task is in progress at a time. ${again}`;
+    const task = running[0];
+    if (!task || fitsTask(status, task.title))
+        return null;
+    return `Refused: the status "${status.trim()}" is about ${stagesOf(status).join(' and ')}, but the task in progress is "${task.title}". The status line is the detail of the task in progress: mark the task it is about in progress, or say what "${task.title}" is doing. ${again}`;
+}
+/** The line under the last screen's heading ("You're all set up", or "Settings saved" without a test drive), 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. */
+export function resultLine(report) {
+    const lead = !report.testPr ? 'No test drive: the report says why.' : 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;
+    return report.setupPr || !report.hostedBy ? lead : `${lead} ${nothingToMerge(report.hostedBy)}`;
+}
+/** Said once, here and in the report, when the host builds the previews and the repository needed no change. */
+export const nothingToMerge = (host) => `Nothing to merge: ${host} hosts your previews, so the repository needed no change.`;
+const PROGRESS = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['status', 'tasks'],
+    properties: {
+        status: { type: 'string', minLength: 1, description: 'The current [STATUS] line, without the tag.' },
+        tasks: {
+            type: 'array',
+            description: 'The whole task list, every time.',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['id', 'title', 'status'],
+                properties: { id: { type: 'string', minLength: 1 }, title: { type: 'string', minLength: 1 }, status: { type: 'string', enum: TASK_STATUSES } },
+            },
+        },
+    },
+};
+const REPORT = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['markdown'],
+    properties: {
+        markdown: { type: 'string', minLength: 1, description: 'The report, as the playbook\'s report section gives it.' },
+        left: {
+            type: 'array',
+            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 },
+        },
+    },
+};
+const WRITE = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['path', 'body'],
+    properties: {
+        path: { type: 'string', minLength: 1, description: 'The endpoint\'s path under /repos/{repo}/ in the instructions, such as "preview".' },
+        body: { type: 'object', description: 'The body the instructions\' writes give for that endpoint.' },
+    },
+};
+const PULL_REQUEST = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['number', 'url'],
+    properties: {
+        number: { type: 'integer', minimum: 1, description: 'The number gh pr create printed.' },
+        url: { type: 'string', minLength: 1, description: 'Its address, https://github.com/<owner>/<repo>/pull/<number>.' },
+    },
+};
+const TEST_PR = {
+    ...PULL_REQUEST,
+    properties: { ...PULL_REQUEST.properties, setup_pr: { ...PULL_REQUEST, description: 'The setup pull request, when there is one: this run\'s, or on a rerun the earlier run\'s.' } },
+};
+const HOSTED_PREVIEWS = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        branch: { type: 'string', minLength: 1, description: 'A branch of this run, once pushed and before its pull request exists, such as impeccable/test-drive: reads the deployments of its head only, and waits up to five minutes for one to finish building.' },
+    },
+};
+const NETLIFY_PREVIEWS = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        pull: { type: 'integer', minimum: 1, description: 'A pull request of this run, once pushed: reads its previews only, and waits up to five minutes for one to finish building.' },
+    },
+};
+const PROVE_PREVIEW = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['url', 'expect'],
+    properties: {
+        url: { type: 'string', minLength: 1, description: 'An address impeccable_hosted_previews or impeccable_netlify_previews listed, or a page on it.' },
+        expect: { type: 'string', minLength: 1, description: 'Words the page shows that a file of this checkout holds, such as the app\'s name in its title.' },
+    },
+};
+const ASK = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'prompt', 'kind'],
+    properties: {
+        id: { type: 'string', minLength: 1, description: 'A short id, such as "admin-password".' },
+        title: { type: 'string', minLength: 1, description: 'The dialog\'s title: the subject in a few words, such as "Admin account". A confirm\'s heading.' },
+        prompt: { type: 'string', minLength: 1, description: 'The question. A confirm\'s action line; an account\'s line under its title, such as "Reviews sign in with this account as admin."' },
+        hint: { type: 'string', minLength: 1, description: 'One line under the question that helps answer it. A confirm\'s text under its title, two or three short lines.' },
+        kind: {
+            type: 'string',
+            enum: ['text', 'single', 'multi', 'confirm', 'account'],
+            description: 'text: the person types the answer; single: they pick one option; multi: they pick any number; confirm: they go on or skip; account: one test account, its username and password on one screen, the password typed hidden.',
+        },
+        options: {
+            type: 'array',
+            description: 'single and multi: the choices, at least two.',
+            items: { type: 'object', additionalProperties: false, required: ['label', 'value'], properties: { label: { type: 'string', minLength: 1 }, value: { type: 'string', minLength: 1 } } },
+        },
+        prefill: { type: 'string', minLength: 1, description: 'text, not with sensitive, and account: what the (username) field holds when the dialog opens, such as the seed\'s username. The person can change it.' },
+        confirmLabel: { type: 'string', minLength: 1, description: 'confirm only: the way on, such as "Share test accounts".' },
+        skipLabel: { type: 'string', minLength: 1, description: 'confirm only: the other way, such as "Skip for now".' },
+        skippable: { type: 'boolean', description: 'Every question offers Skip, whatever this says.' },
+        sensitive: { type: 'boolean', description: 'text only: a password. The person types it hidden, and the answer\'s value is a reference ("secret:…") that impeccable_write turns back into what they typed.' },
+    },
+};
+const NETLIFY_CONNECT = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        command: { type: 'string', minLength: 1, description: "The build command Netlify runs, only where no netlify.toml sets one: the package's build script." },
+        publish: { type: 'string', minLength: 1, description: 'The folder the build writes the pages to, relative to the checkout, only where no netlify.toml sets one.' },
+    },
+};
+/** 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);
+    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)))
+        return 'input.prefill is for account questions and text questions that are not sensitive';
+    if ((q.confirmLabel ?? q.skipLabel) !== undefined && q.kind !== 'confirm')
+        return 'input.confirmLabel and input.skipLabel are for confirm only';
+    if (q.kind === 'text' || q.kind === 'confirm' || q.kind === 'account')
+        return q.options ? 'input.options is for single and multi only' : null;
+    if (values.length < 2)
+        return `input.options needs at least two choices for ${q.kind}`;
+    return new Set(values).size === values.length ? null : 'input.options has a value twice';
+}
+/** Why `url` is not pull request `number` of owner/repo on GitHub; null when it is. */
+function pullRequestError(url, number, owner, repo) {
+    const m = URL.canParse(url) ? /^\/([^/]+)\/([^/]+)\/pull\/(\d+)\/?$/.exec(new URL(url).pathname) : null;
+    const ok = m && new URL(url).origin === 'https://github.com' && m[1].toLowerCase() === owner.toLowerCase() && m[2].toLowerCase() === repo.toLowerCase() && Number(m[3]) === number;
+    return ok ? null : `${url} is not pull request #${number} of ${owner}/${repo} on GitHub`;
+}
+/** This run's open pull request from `branch`, its head in this repository rather than a fork, with that head's name; or why it is not. */
+async function runPullRequest(ctx, pr, branch, signal) {
+    const error = pullRequestError(pr.url, pr.number, ctx.owner, ctx.repo);
+    if (error)
+        return { problem: error };
+    const found = await ctx.viewPullRequest(pr.number);
+    if ('error' in found)
+        return { problem: `gh pr view ${pr.number} did not find it (${found.error})` };
+    if (!found.headRefName.startsWith(branch))
+        return { problem: `#${pr.number} comes from ${found.headRefName}, not from ${branch}` };
+    if (found.state !== 'OPEN')
+        return { problem: `#${pr.number} is ${found.state.toLowerCase()}, not open` };
+    // Impeccable reviews a draft only once it is marked ready, so the web page would follow a review that never starts.
+    if (found.isDraft)
+        return { problem: `#${pr.number} is still a draft: mark it ready (gh pr ready ${found.headRefName} --repo ${ctx.owner}/${ctx.repo}) once its preview is proven, then record it` };
+    if (!await (ctx.setupPullHeadReader ?? readSetupPullHead)(ctx.owner, ctx.repo, pr.number, found.headRefName, { signal })) {
+        return { problem: `the branch of #${pr.number} could not be verified in this repository; a fork's branch cannot be recorded` };
+    }
+    return { branch: found.headRefName };
+}
+const PREVIEW_COMMAND = { type: 'object', additionalProperties: false, required: ['command'], properties: {
+        command: { type: 'string', minLength: 1, description: 'A command of the repository\'s own scripts or tools, without cd.' },
+        directory: { type: 'string', minLength: 1, description: 'The folder it runs in, relative to the checkout; the root when left out.' },
+    } };
+const LOCAL_PREVIEW = {
+    type: 'object', additionalProperties: false, required: ['steps', 'start', 'port', 'paths', 'host'],
+    properties: {
+        steps: { type: 'array', description: 'The steps before the app starts, in order: install, prepare, build, seed for a server; install, prepare, seed, build for a static site. Repeat a phase for another folder.', items: { ...PREVIEW_COMMAND, required: ['phase', 'command'], properties: { ...PREVIEW_COMMAND.properties, phase: { type: 'string', enum: ['install', 'prepare', 'build', 'seed'] } } } },
+        start: { ...PREVIEW_COMMAND, description: 'Server: the command that starts the app.' },
+        port: { type: 'integer', minimum: 1024, description: 'Server: the port the app listens on.' },
+        paths: { type: 'array', description: 'Server: up to eight routes to request, / among them.', items: { type: 'string', minLength: 1 } },
+        host: { type: 'string', minLength: 1, description: 'Server: a host name like the tunnel\'s, such as t-crewline.impeccable.reviews; the app must answer it as well as localhost.' },
+        env: { type: 'object', description: 'Literal, non-secret variables. DATABASE_URL is a relative SQLite file (file:./preview.db), or comes from service.' },
+        service: { type: 'string', enum: ['postgres', 'mysql'], description: 'A throwaway database container; the steps get its DATABASE_URL.' },
+    },
+};
+const STATIC_OUTPUT = {
+    type: 'object', additionalProperties: false, required: ['directory'], description: 'Static site: where the build writes the pages.', properties: {
+        directory: { type: 'string', minLength: 1, description: 'The folder, relative to the checkout; "." for the root.' },
+        basePath: { type: 'string', description: 'The path the site is served under, such as /docs, when it is not /.' },
+        entries: { type: 'array', description: 'Pages besides index.html that must exist.', items: { type: 'string', minLength: 1 } },
+    },
+};
+const STATIC_PREVIEW = {
+    type: 'object', additionalProperties: false, required: ['steps', 'output'], properties: {
+        steps: LOCAL_PREVIEW.properties.steps, output: STATIC_OUTPUT,
+        env: LOCAL_PREVIEW.properties.env, service: LOCAL_PREVIEW.properties.service,
+    },
+};
+// The tool schema exposes both alternatives; the helper validates the selected strict shape.
+const PREVIEW_VERIFICATION = {
+    ...LOCAL_PREVIEW, required: ['steps'], properties: { ...LOCAL_PREVIEW.properties, output: STATIC_OUTPUT },
+};
+const contained = (path, root) => { const r = relative(root, path); return r !== '..' && !r.startsWith('../') && !isAbsolute(r); };
+/** Canonical relative file paths only; URL encoding and alternate separators are ambiguous here. */
+const staticRelativePath = (path) => path.length <= 400 && !/[\\%?#:\x00-\x1f\x7f]/.test(path) && path.split('/').every((part) => part.length > 0 && part !== '.' && part !== '..');
+function staticOutputLayout(output) {
+    if (schemaError(STATIC_OUTPUT, output) || (output.directory !== '.' && !staticRelativePath(output.directory)))
+        return null;
+    const base = output.basePath || '/';
+    if (base.length > 200 || (base !== '/' && (!base.startsWith('/') || !staticRelativePath(base.slice(1)))))
+        return null;
+    if ((output.entries?.length ?? 0) > 7 || output.entries?.some((entry) => !staticRelativePath(entry)))
+        return null;
+    const prefix = base === '/' ? '' : base.slice(1) + '/';
+    return { directory: output.directory, entries: [...new Set(['index.html', ...(output.entries ?? [])])].map((entry) => prefix + entry) };
+}
+/** Entry availability only: no HTML/body parsing, routing, rendering or upload claim. */
+export async function inspectStaticPreviewOutput(root, output) {
+    const fail = (reason) => ({ verified: false, reason, files: [] });
+    const layout = staticOutputLayout(output);
+    if (!layout)
+        return fail('Use canonical relative output and entry paths and a slash-prefixed base path.');
+    try {
+        root = await realpath(root);
+        const directory = resolve(root, layout.directory);
+        if (!contained(directory, root))
+            return fail('The static output leaves the isolated checkout.');
+        // Refuse every symlink along the selected paths: regular archive uploads need real entries.
+        const check = async (path, file) => {
+            const parts = relative(root, path).split('/').filter(Boolean);
+            let current = root;
+            for (const [index, part] of parts.entries()) {
+                if (!(await readdir(current)).includes(part))
+                    return null;
+                current = join(current, part);
+                const info = await lstat(current);
+                if (info.isSymbolicLink() || !contained(await realpath(current), root))
+                    return null;
+                if (index < parts.length - 1 || !file) {
+                    if (!info.isDirectory())
+                        return null;
+                }
+                else if (!info.isFile() || info.size === 0)
+                    return null;
+            }
+            return lstat(path);
+        };
+        if (!await check(directory, false))
+            return fail('The static output must be a directory without symlink components.');
+        const files = [];
+        for (const entry of layout.entries) {
+            const path = resolve(directory, entry), info = await check(path, true);
+            if (!info)
+                return fail('A required static entry is empty, unsupported or reached through a symlink.');
+            files.push({ path: relative(root, path), bytes: info.size });
+        }
+        return { verified: true, files };
+    }
+    catch {
+        return fail('The output directory or a required nonempty entry file is missing or unavailable at the selected base path.');
+    }
+}
+const previewExcluded = (path) => path.split('/').some((p) => isSecretFile(p) || p.startsWith('.dev.vars') || /^(?:\.git|node_modules|\.venv|venv|\.wrangler|\.bundle|\.npmrc|\.yarnrc|\.pypirc|\.netrc|\.ssh|\.aws|\.config)$/.test(p) || /(?:^credentials(?:\.|$)|^master\.key$|\.(?:pem|p12|pfx|key)$|\.(?:db|sqlite|sqlite3)(?:-(?:wal|shm|journal))?$)/i.test(p));
+const previewPhases = ['install', 'prepare', 'build', 'seed'];
+const usesLocalD1 = (command) => {
+    const calls = (parseCommand(command) ?? []).filter(({ words }) => words.some((w, i) => w === 'wrangler' && words[i + 1] === 'd1'));
+    return calls.length > 0 && calls.every(({ words }) => words.includes('--local') && !words.some((w) => w.startsWith('--local=')));
+};
+/** Stop only a process group this invocation created, including shell grandchildren. */
+async function stopPreviewChild(child) {
+    if (!child.pid)
+        return;
+    try {
+        process.kill(-child.pid, 'SIGTERM');
+    }
+    catch {
+        return;
+    }
+    await sleep(100);
+    try {
+        process.kill(-child.pid, 'SIGKILL');
+    }
+    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) {
+    const probes = [];
+    const fail = (stage, reason) => ({ verified: false, stage, reason, probes });
+    if (process.platform === 'win32')
+        return fail('environment', 'Local preview verification is unavailable on Windows.');
+    const staticInput = input && typeof input === 'object' && 'output' in input ? input : undefined;
+    if (schemaError(staticInput ? STATIC_PREVIEW : LOCAL_PREVIEW, input))
+        return fail('input', 'Invalid local preview input.');
+    const serverInput = staticInput ? undefined : input;
+    const layout = staticInput ? staticOutputLayout(staticInput.output) : undefined;
+    if (staticInput && !layout)
+        return fail('input', 'Use canonical relative output and entry paths and a slash-prefixed base path.');
+    const generatedOutput = layout && input.steps.some((step) => step.phase === 'build') ? layout.directory : undefined;
+    if (signal?.aborted)
+        return fail('environment', 'Verification was cancelled.');
+    if (serverInput && (serverInput.port > 65535 || !serverInput.paths.length || serverInput.paths.length > 8 || !serverInput.paths.includes('/') || serverInput.paths.some((p) => !/^\/(?!\/)[^\r\n?#]*$/.test(p)) || !/^(?!localhost$)[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?\.[a-z][a-z0-9.-]*$/i.test(serverInput.host)))
+        return fail('input', 'Use a valid local port, a foreign hostname and up to eight route paths including /.');
+    let last = -1;
+    if (input.steps.length > 16)
+        return fail('input', 'Use at most sixteen local verification steps.');
+    const phases = staticInput ? ['install', 'prepare', 'seed', 'build'] : previewPhases;
+    for (const step of input.steps) {
+        const next = phases.indexOf(step.phase);
+        if (next < last)
+            return fail('input', `Steps must follow ${phases.join(', ')} order.`);
+        last = next;
+    }
+    const supplied = input.env ?? {};
+    if (Object.keys(supplied).length > 64 || Object.entries(supplied).some(([key, value]) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || typeof value !== 'string' || value.length > 2048 || /\$\{|\$[A-Za-z_]|[\r\n\0]/.test(value) || /(?:TOKEN|PASSWORD|PASSWD|SECRET|API_KEY|MASTER_KEY|CREDENTIAL|AUTHORIZATION|COOKIE)/i.test(key) || /^(?:PATH|HOME|TMP|TEMP|TMPDIR|SHELL|ENV|BASH_ENV|NODE_OPTIONS|NODE_PATH|PYTHONPATH|PYTHONSTARTUP|RUBYOPT|RUBYLIB|LD_.*|DYLD_.*|XDG_.*|GIT_.*|BUNDLE_.*|NPM_CONFIG_.*|PIP_.*)$/i.test(key)))
+        return fail('environment', 'Only literal non-secret preview variables are supported; credentials and secret references cannot be used locally.');
+    if (Object.keys(supplied).some((k) => k !== 'DATABASE_URL' && /^(?:DB_|DATABASE_|PGHOST|PGPORT|PGDATABASE|PGUSER|MYSQL_)/i.test(k)))
+        return fail('database', 'Use the verifier-owned database through DATABASE_URL; other database overrides are unsupported.');
+    if (serverInput && supplied.PORT !== undefined && supplied.PORT !== String(serverInput.port))
+        return fail('environment', 'The PORT variable must match the port being verified.');
+    const sqlitePath = /^(?:file:|sqlite3:|sqlite:\/\/\/)((?!\/)[A-Za-z0-9_./-]+)$/.exec(supplied.DATABASE_URL ?? '')?.[1];
+    const localSqlite = Boolean(sqlitePath && !sqlitePath.split('/').includes('..'));
+    if (!input.service && supplied.DATABASE_URL && !localSqlite)
+        return fail('database', 'DATABASE_URL must name a relative SQLite file or a verifier-owned database service.');
+    let scratch;
+    let server;
+    let container;
+    let containerStarted = false;
+    const ownership = randomBytes(16).toString('hex');
+    let stage = 'snapshot';
+    let env = { PATH: process.env.PATH ?? '/usr/local/bin:/usr/bin:/bin', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8', CI: '1', NO_COLOR: '1', GIT_TERMINAL_PROMPT: '0' };
+    // Capture is reserved for filenames, package manifests and Docker metadata, never app logs.
+    const run = (command, args, cwd, capture = false, timeout = 120_000, cancellation = signal ?? null, processEnv = env) => new Promise((done) => {
+        if (cancellation?.aborted)
+            return done({ ok: false, output: '' });
+        let output = '', failed = false;
+        const child = spawn(command, args, { cwd, env: processEnv, detached: true, stdio: ['ignore', capture ? 'pipe' : 'ignore', 'ignore'] });
+        const cancel = () => { failed = true; void stopPreviewChild(child); };
+        const timer = setTimeout(cancel, timeout);
+        cancellation?.addEventListener('abort', cancel, { once: true });
+        child.stdout?.on('data', (chunk) => { if (output.length + chunk.length > 2_000_000)
+            cancel();
+        else
+            output += chunk.toString(); });
+        const finish = async (ok) => { clearTimeout(timer); cancellation?.removeEventListener('abort', cancel); await stopPreviewChild(child); done({ ok: ok && !failed, output }); };
+        child.once('error', () => { failed = true; });
+        child.once('close', (code) => void finish(code === 0));
+    });
+    const probe = (path, host) => new Promise((done) => {
+        const req = request({ hostname: '127.0.0.1', port: serverInput.port, path, headers: { host }, method: 'GET', timeout: 2000, signal }, (res) => { const status = res.statusCode ?? 0; res.destroy(); done(status); });
+        req.on('timeout', () => req.destroy());
+        req.on('error', () => done(0));
+        req.end();
+    });
+    try {
+        root = await realpath(root);
+        if (generatedOutput !== undefined) {
+            const output = resolve(root, generatedOutput);
+            // Remove only a separate output subtree from the copy, never source or a phase's cwd.
+            if (output === root)
+                return fail('output', 'A generated build needs a separate output directory.');
+            // Case-insensitive filesystems must not copy Dist as stale output for dist.
+            let parent = root;
+            for (const part of generatedOutput.split('/')) {
+                const names = await readdir(parent), next = join(parent, part);
+                const info = await lstat(next).catch((error) => { if (error.code === 'ENOENT')
+                    return null; throw error; });
+                if (!info)
+                    break; // No existing subtree below a genuinely absent component.
+                if (!names.includes(part) || info.isSymbolicLink() || !info.isDirectory())
+                    return fail('output', 'Use an output directory with exact on-disk spelling and no symlink components.');
+                parent = next;
+            }
+            for (const step of input.steps) {
+                const cwd = await realpath(resolve(root, step.directory ?? '.'));
+                if (!contained(cwd, root) || contained(cwd, output))
+                    return fail('output', 'The generated output overlaps a command directory or leaves the checkout.');
+            }
+        }
+        // Under /tmp, not the OS temp folder: the steps' temp folder is inside, and a socket there (tsx opens one) must fit the 103 bytes macOS allows.
+        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 })));
+        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);
+        if (!listing.ok)
+            return fail(stage, 'Could not list checkout files.');
+        const files = [...new Set(listing.output.split('\0').filter(Boolean))];
+        if (files.length > 10_000)
+            return fail(stage, 'The checkout is too large for bounded local verification.');
+        let scriptsChanged = false;
+        for (const file of files) {
+            if (previewExcluded(file) || (generatedOutput !== undefined && (file === generatedOutput || file.startsWith(generatedOutput + '/'))))
+                continue;
+            // An explicitly named SQLite file may have no extension. Never copy its prior data.
+            const databaseName = sqlitePath?.split('/').at(-1);
+            if (databaseName && [databaseName, `${databaseName}-wal`, `${databaseName}-shm`, `${databaseName}-journal`].includes(file.split('/').at(-1)))
+                continue;
+            const source = resolve(root, file), target = resolve(snapshot, file);
+            if (!contained(source, root) || !contained(target, snapshot))
+                return fail(stage, 'A checkout path leaves the repository.');
+            const info = await lstat(source).catch(() => null);
+            if (!info)
+                continue; // a tracked deletion is part of the working checkout
+            const actual = await realpath(source);
+            if (!contained(actual, root))
+                return fail(stage, 'A checkout symlink leaves the repository.');
+            if (previewExcluded(relative(root, actual)))
+                continue;
+            await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+            if (info.isSymbolicLink()) {
+                if (file.split('/').at(-1) === 'package.json')
+                    scriptsChanged = true;
+                await symlink(relative(dirname(target), resolve(snapshot, relative(root, actual))), target);
+                continue;
+            }
+            if (!info.isFile())
+                return fail(stage, 'The checkout contains an unsupported file.');
+            // Registry configuration can contain live credentials even when committed.
+            if (/^\.yarnrc\.ya?ml$/.test(file.split('/').at(-1)) && /(?:authToken|authIdent|password):/i.test(await readFile(source, 'utf8')))
+                continue;
+            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 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')));
+            }
+        }
+        const steps = [...input.steps, ...(serverInput ? [{ ...serverInput.start, phase: 'start' }] : [])];
+        const directories = [];
+        for (const step of steps) {
+            const cwd = await realpath(resolve(snapshot, step.directory ?? '.'));
+            if (!contained(cwd, snapshot))
+                return fail('commands', 'A command directory leaves the isolated checkout.');
+            directories.push(cwd);
+            if (classifyPreviewCommand(step.command, cwd, { scriptsChanged }).verdict !== 'allow')
+                return fail('commands', 'A preview command is outside the supported local verification commands.');
+            const segments = parseCommand(step.command) ?? [];
+            if (segments.some((s) => s.words[0] === 'cd'))
+                return fail('commands', 'Set each command directory explicitly instead of using cd inside commands.');
+            let localD1 = usesLocalD1(step.command);
+            const migration = /\b(?:migrate|migrations|db:prepare|db:push|db:migrate|db:seed|db push|db seed)\b/;
+            const djangoDatabase = (command) => (parseCommand(command) ?? []).some(({ words }) => {
+                const at = words.findIndex((w) => /(?:^|\/)manage\.py$/.test(w));
+                return at >= 0 && !['runserver', 'collectstatic', 'check'].includes(words[at + 1] ?? '');
+            });
+            let preparesDatabase = migration.test(step.command) || djangoDatabase(step.command);
+            for (const { words } of segments) {
+                if (!['npm', 'pnpm', 'yarn', 'bun'].includes(words[0] ?? ''))
+                    continue;
+                const names = words[1] === 'run' ? [`pre${words[2]}`, words[2], `post${words[2]}`] : ['install', 'ci'].includes(words[1] ?? '') ? ['preinstall', 'install', 'postinstall', 'prepare'] : [];
+                if (!names.length)
+                    continue;
+                const manifest = JSON.parse(await readFile(join(cwd, 'package.json'), 'utf8'));
+                const seen = new Set();
+                while (names.length) {
+                    const name = names.pop();
+                    if (seen.has(name))
+                        continue;
+                    seen.add(name);
+                    const script = manifest.scripts?.[name] ?? '';
+                    preparesDatabase ||= migration.test(script) || djangoDatabase(script);
+                    if (/--remote\b|\b(?:deploy|publish)\b/.test(script.replace(/\bprisma\s+migrate\s+deploy\b/g, 'prisma migrate')))
+                        return fail('commands', 'A selected package script deploys or touches a remote database.');
+                    if (/\bwrangler\s+d1\b/.test(script) && !usesLocalD1(script))
+                        return fail('commands', 'A selected D1 script must explicitly use --local.');
+                    if (usesLocalD1(script))
+                        localD1 = true;
+                    for (const m of script.matchAll(/\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?([\w:.-]+)/g))
+                        names.push(m[1]);
+                }
+            }
+            if ((step.phase === 'seed' || preparesDatabase) && !input.service && !localSqlite && !localD1)
+                return fail('database', 'Preparation and seed require an owned database service, a relative SQLite DATABASE_URL, or an explicit local D1 command.');
+        }
+        if (signal?.aborted)
+            return fail('environment', 'Verification was cancelled.');
+        const pythonDirectories = new Map();
+        for (const [index, step] of steps.entries()) {
+            const words = (parseCommand(step.command) ?? []).map((part) => part.words);
+            const calls = words.filter(([command]) => ['python', 'python3', '.venv/bin/python', '.venv/bin/python3', 'uvicorn'].includes(command ?? ''));
+            if (!calls.length)
+                continue;
+            const directory = directories[index], previous = pythonDirectories.get(directory);
+            const executable = calls.some(([command]) => command === 'python3') ? 'python3' : calls.some(([command]) => command === 'python') ? 'python' : undefined;
+            pythonDirectories.set(directory, {
+                executable: executable === 'python3' || (previous?.explicit && previous.executable === 'python3') ? 'python3' : executable ?? previous?.executable ?? 'python3',
+                explicit: Boolean(previous?.explicit || executable),
+            });
+        }
+        for (const [directory, python] of pythonDirectories) {
+            stage = 'environment';
+            let executable;
+            // A generic python alias may come from Python 3's venv; an explicit python3 stays explicit.
+            const candidates = !python.explicit ? ['python3', 'python'] : python.executable === 'python' ? ['python', 'python3'] : ['python3'];
+            for (const candidate of candidates) {
+                const found = await run('/bin/sh', ['-c', `command -v ${candidate}`], directory, true, 5000);
+                const path = found.output.trim();
+                if (found.ok && isAbsolute(path) && !/[\r\n\0]/.test(path)) {
+                    executable = path;
+                    break;
+                }
+            }
+            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)
+                return fail(stage, 'The required Python runtime or virtual environment is unavailable.');
+        }
+        const environmentFor = (directory) => {
+            if (!pythonDirectories.has(directory))
+                return env;
+            const venv = join(directory, '.venv');
+            return { ...env, VIRTUAL_ENV: venv, PATH: `${join(venv, 'bin')}:${env.PATH}` };
+        };
+        if (input.service) {
+            stage = 'database';
+            const postgres = input.service === 'postgres', port = postgres ? 5432 : 3306;
+            container = `impeccable-preview-${ownership}`;
+            const args = ['run', '--detach', '--rm', '--name', container, '--label', `impeccable.verifier=${ownership}`, '--publish', `127.0.0.1::${port}`, '--env', postgres ? 'POSTGRES_PASSWORD=postgres' : 'MYSQL_ROOT_PASSWORD=root', '--env', postgres ? 'POSTGRES_DB=preview' : 'MYSQL_DATABASE=preview', postgres ? 'postgres:16' : 'mysql:8'];
+            if (!(await run('docker', args, snapshot)).ok)
+                return fail(stage, 'A disposable database could not start; local Docker is required.');
+            containerStarted = true;
+            const mapped = await run('docker', ['port', container, `${port}/tcp`], snapshot, true, 10_000);
+            const match = /^127\.0\.0\.1:(\d+)\s*$/.exec(mapped.output);
+            if (!mapped.ok || !match)
+                return fail(stage, 'The disposable database did not publish a loopback port.');
+            env.DATABASE_URL = `${postgres ? 'postgresql://postgres:postgres' : 'mysql://root:root'}@127.0.0.1:${match[1]}/preview`;
+            let ready = false;
+            for (let i = 0; i < 30 && !signal?.aborted; i++) {
+                const check = postgres ? ['pg_isready', '-U', 'postgres', '-d', 'preview'] : ['mysqladmin', 'ping', '-h', '127.0.0.1', '-proot'];
+                if ((await run('docker', ['exec', container, ...check], snapshot, false, 5000)).ok) {
+                    ready = true;
+                    break;
+                }
+                await sleep(1000, undefined, { signal }).catch(() => { });
+            }
+            if (!ready)
+                return fail(stage, 'The disposable database was not ready; no preparation or seed ran.');
+        }
+        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)
+                return fail(stage, signal?.aborted ? 'Verification was cancelled.' : 'The local step failed or exceeded two minutes; its output was not retained.');
+        }
+        if (staticInput) {
+            stage = 'output';
+            if (signal?.aborted)
+                return fail(stage, 'Verification was cancelled.');
+            const inspected = await inspectStaticPreviewOutput(snapshot, staticInput.output);
+            if (signal?.aborted)
+                return fail(stage, 'Verification was cancelled.');
+            return { ...inspected, ...(inspected.verified ? {} : { stage }), probes };
+        }
+        stage = 'start';
+        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' });
+        let exited = false;
+        server.once('error', () => { exited = true; });
+        server.once('exit', () => { exited = true; });
+        let ready = false;
+        const deadline = Date.now() + 30_000;
+        while (!signal?.aborted && !exited && Date.now() < deadline) {
+            if (await probe('/', 'localhost')) {
+                ready = true;
+                break;
+            }
+            await sleep(250, undefined, { signal }).catch(() => { });
+        }
+        if (!ready || exited || signal?.aborted)
+            return fail(stage, signal?.aborted ? 'Verification was cancelled.' : 'The app did not become ready within thirty seconds.');
+        stage = 'probe';
+        for (const path of serverInput.paths)
+            for (const host of ['localhost', serverInput.host]) {
+                const status = await probe(path, host);
+                probes.push({ path, host, status });
+                if (signal?.aborted || exited)
+                    return fail(stage, 'The app stopped or verification was cancelled.');
+            }
+        if (probes.some((p) => p.status < 200 || p.status >= 300))
+            return fail(stage, 'A route or foreign-host check was not successful; redirects are not followed and sign-in is not verified.');
+        return { verified: true, reason: 'Local HTTP checks passed; browser behavior, signed-in access and CI runtime versions remain unverified.', probes };
+    }
+    catch {
+        return fail(stage, signal?.aborted ? 'Verification was cancelled.' : 'Local verification could not complete safely; no subprocess output was retained.');
+    }
+    finally {
+        let cleanupFailed = false;
+        if (server)
+            await stopPreviewChild(server);
+        if (container && scratch) {
+            const owner = await run('docker', ['inspect', '--format', '{{index .Config.Labels "impeccable.verifier"}}', container], scratch, true, 10_000, null);
+            const owned = owner.ok && owner.output.trim() === ownership;
+            if (owned)
+                cleanupFailed = !(await run('docker', ['rm', '--force', container], scratch, false, 10_000, null)).ok;
+            else
+                cleanupFailed = containerStarted || !owner.ok;
+            // --rm may already have removed an exited service. Failed inspect alone
+            // cannot distinguish that success from an unavailable Docker daemon.
+            if (!owner.ok || (owned && cleanupFailed)) {
+                const remaining = await run('docker', ['ps', '--all', '--filter', `name=^/${container}$`, '--format', '{{.Names}}'], scratch, true, 10_000, null);
+                // A daemon that does not answer says nothing about a container that never started and that inspect never saw: the answer already returned (Docker is required) stands.
+                cleanupFailed = remaining.output.trim() !== '' || (!remaining.ok && (containerStarted || owned));
+            }
+        }
+        if (scratch)
+            await rm(scratch, { recursive: true, force: true }).catch(() => { cleanupFailed = true; });
+        if (cleanupFailed)
+            return fail('cleanup', 'An owned preview resource could not be removed; local verification is incomplete.');
+    }
+}
+/** The setup tools check their input and answer with evidence or a short error; none throws. */
+const execFileAsync = promisify(execFile);
+/**
+ * Whether the setup branch lies under the test drive's branch, as their remote-tracking refs in this checkout
+ * show GitHub: a push moves its ref only when it lands, so a correction pushed after the test drive was
+ * branched makes this false, and a push that failed changes nothing. Null when either ref is missing.
+ */
+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 });
+        return true;
+    }
+    catch (err) {
+        return err.code === 1 ? false : null;
+    }
+}
+const LIMIT = 20;
+const WORKFLOW = '.github/workflows/impeccable-preview.yml';
+const STATUSES = ['queued', 'requested', 'waiting', 'pending', 'in_progress', 'completed'];
+const CONCLUSIONS = ['success', 'failure', 'cancelled', 'timed_out', 'action_required', 'neutral', 'skipped', 'stale', 'startup_failure'];
+const object = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+const positive = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v > 0;
+const sha = (v) => typeof v === 'string' && /^[0-9a-f]{40}$/.test(v);
+const date = (v) => typeof v === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?(?:Z|[+-]\d\d:\d\d)$/.test(v) && Number.isFinite(Date.parse(v)) ? new Date(v).toISOString() : null;
+const statusOf = (v) => STATUSES.find((s) => s === v);
+const conclusionOf = (v) => v === null ? null : CONCLUSIONS.find((s) => s === v);
+const setupBranch = (v) => /^impeccable\/setup(?:-[A-Za-z0-9][A-Za-z0-9._-]*)?$/.test(v) && !v.includes('..') && !v.endsWith('.') && !v.endsWith('.lock');
+const testDriveBranch = (v) => /^impeccable\/test-drive(?:-[A-Za-z0-9][A-Za-z0-9._-]*)?$/.test(v) && !v.includes('..') && !v.endsWith('.') && !v.endsWith('.lock');
+/** Verify head ownership before an immutable binding; never return raw GitHub output. */
+export async function readSetupPullHead(owner, repo, pr, branch, deps = {}) {
+    if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/.test(owner)
+        || !/^[A-Za-z0-9_.-]{1,100}$/.test(repo) || ['.', '..'].includes(repo)
+        || !positive(pr) || !(setupBranch(branch) || testDriveBranch(branch)) || deps.signal?.aborted)
+        return false;
+    try {
+        const args = ['api', '--hostname', 'github.com', '--method', 'GET', `/repos/${owner}/${repo}/pulls/${pr}`];
+        const raw = deps.runGh ? await deps.runGh(args) : (await execFileAsync('gh', args, {
+            encoding: 'utf8', timeout: 30_000, maxBuffer: 256 * 1024, signal: deps.signal,
+            env: { ...process.env, GH_PROMPT_DISABLED: '1' },
+        })).stdout;
+        if (deps.signal?.aborted || raw.length > 256 * 1024)
+            return false;
+        const pull = object(JSON.parse(raw)), head = object(pull?.head), base = object(pull?.base);
+        const sameRepo = (value) => {
+            const repository = object(value), fullName = `${owner}/${repo}`.toLowerCase();
+            return typeof repository?.full_name === 'string' && repository.full_name.toLowerCase() === fullName
+                && (repository.url === undefined || (typeof repository.url === 'string'
+                    && repository.url.toLowerCase() === `https://api.github.com/repos/${fullName}`));
+        };
+        return pull?.number === pr && pull.state === 'open' && head?.ref === branch && sha(head.sha)
+            && sameRepo(head.repo) && sameRepo(base?.repo);
+    }
+    catch {
+        return false;
+    }
+}
+/** Only generated, recognizable labels become a phase. Names never leave memory. */
+function stageOf(value) {
+    if (typeof value !== 'string')
+        return null;
+    const names = {
+        Prepare: 'prepare', 'Seed data': 'seed', 'Start the app': 'start',
+        'Upload to Impeccable': 'upload', 'Tunnel to Impeccable and wait for the review': 'tunnel',
+        'Choose pnpm version': 'setup', 'Install Zola': 'setup',
+    };
+    if (Object.hasOwn(names, value))
+        return names[value];
+    if (/^Run actions\/setup-(?:node|python|ruby|go|java|dotnet)@[^\s]+$/.test(value)
+        || /^Run (?:pnpm\/action-setup|oven-sh\/setup-bun|ruby\/setup-ruby)@[^\s]+$/.test(value))
+        return 'setup';
+    if (/^Run (?:npm|pnpm|yarn|bun) (?:install|ci)(?: |$)/.test(value))
+        return 'install';
+    if (/^Run (?:npm|pnpm|yarn|bun) run build(?: |$)/.test(value))
+        return 'build';
+    return null;
+}
+/**
+ * Safe bounded evidence, not a retry counter or a claim the preview rendered.
+ * Reads PR twice to detect head changes during collection. Never downloads logs.
+ * Historical runs without a provable PR association are omitted and flagged.
+ */
+export async function readPreviewRuns(owner, repo, pr, branch, deps) {
+    const out = { pull: null, runs: [], currentRunId: null,
+        coverage: { limit: LIMIT, truncated: false, unassociatedHistory: false, incomplete: false } };
+    if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/.test(owner)
+        || !/^[A-Za-z0-9_.-]{1,100}$/.test(repo) || ['.', '..'].includes(repo)
+        || !positive(pr) || !setupBranch(branch))
+        return { ...out, error: 'invalid-input' };
+    const fullName = `${owner}/${repo}`;
+    const base = `/repos/${owner}/${repo}`;
+    const apiRepo = `https://api.github.com${base}`;
+    const sameRepo = (v) => {
+        const r = object(v);
+        return !!r && (r.full_name === fullName || r.url === apiRepo)
+            && (r.full_name === undefined || r.full_name === fullName)
+            && (r.url === undefined || r.url === apiRepo);
+    };
+    const runGh = deps.runGh ?? (async (args) => {
+        const { stdout } = await execFileAsync('gh', args, { encoding: 'utf8', timeout: 30_000,
+            maxBuffer: 2 * 1024 * 1024, signal: deps.signal });
+        return stdout;
+    });
+    async function get(route) {
+        if (deps.signal?.aborted)
+            throw new Error();
+        const text = await runGh(['api', '--hostname', 'github.com', '--method', 'GET', route]);
+        if (deps.signal?.aborted || text.length > 2 * 1024 * 1024)
+            throw new Error();
+        const result = object(JSON.parse(text));
+        if (!result)
+            throw new Error();
+        return result;
+    }
+    function readPull(p) {
+        const head = object(p.head), baseRef = object(p.base);
+        return p.number === pr && p.state === 'open' && head?.ref === branch && sha(head.sha)
+            && sameRepo(head.repo) && sameRepo(baseRef?.repo) ? { number: pr, head: head.sha, branch } : null;
+    }
+    function collection(p, key) {
+        if (!Array.isArray(p[key]) || typeof p.total_count !== 'number' || !Number.isSafeInteger(p.total_count)
+            || p.total_count < p[key].length)
+            throw new Error();
+        if (p.total_count > LIMIT || p[key].length > LIMIT)
+            out.coverage.truncated = true;
+        return p[key].slice(0, LIMIT);
+    }
+    let workflowId;
+    function runOf(v) {
+        const invalid = () => { out.coverage.incomplete = true; return null; };
+        const r = object(v);
+        if (!r || !positive(r.id) || !positive(r.run_attempt) || !sha(r.head_sha)
+            || r.head_branch !== branch || r.event !== 'pull_request' || r.workflow_id !== workflowId
+            || typeof r.path !== 'string' || r.path.split('@')[0] !== WORKFLOW
+            || !sameRepo(r.repository) || !sameRepo(r.head_repository))
+            return invalid();
+        const status = statusOf(r.status), conclusion = conclusionOf(r.conclusion), updated = date(r.updated_at);
+        if (!status || conclusion === undefined || !updated)
+            return invalid();
+        const association = Array.isArray(r.pull_requests) ? r.pull_requests.map(object).find((p) => p?.number === pr
+            && object(p.head)?.ref === branch && sameRepo(object(p.head)?.repo) && sameRepo(object(p.base)?.repo)
+            && sha(object(p.head)?.sha)) : undefined;
+        // Empty arrays are normal for real runs. An explicit contradictory association is not.
+        if (!Array.isArray(r.pull_requests) || (r.pull_requests.length && !association)) {
+            out.coverage.unassociatedHistory = true;
+            return null;
+        }
+        const known = deps.knownRuns?.get(r.id);
+        if (known && known.workflowHead !== r.head_sha)
+            return invalid();
+        let head = known && sha(known.head) ? known.head
+            : r.head_sha === out.pull.head ? r.head_sha : undefined;
+        if (!head && association)
+            head = object(association.head).sha;
+        if (!head) {
+            out.coverage.unassociatedHistory = true;
+            return null;
+        }
+        return { id: r.id, attempt: r.run_attempt, head, workflowHead: r.head_sha, stage: null,
+            status, conclusion, url: `https://github.com/${fullName}/actions/runs/${r.id}`,
+            startedAt: date(r.run_started_at), updatedAt: updated };
+    }
+    try {
+        out.pull = readPull(await get(`${base}/pulls/${pr}`));
+        if (!out.pull)
+            return { ...out, error: 'pull-unavailable' };
+        const workflow = await get(`${base}/actions/workflows/impeccable-preview.yml`);
+        if (!positive(workflow.id) || workflow.path !== WORKFLOW)
+            throw new Error();
+        workflowId = workflow.id;
+        const listed = await get(`${base}/actions/workflows/${workflowId}/runs?branch=${encodeURIComponent(branch)}&event=pull_request&per_page=${LIMIT}`);
+        const unique = new Map();
+        for (const value of collection(listed, 'workflow_runs')) {
+            const r = runOf(value);
+            if (r && (!unique.has(r.id) || unique.get(r.id).attempt < r.attempt))
+                unique.set(r.id, r);
+        }
+        out.runs = [...unique.values()].sort((a, b) => b.id - a.id);
+        const current = out.runs.filter((r) => r.head === out.pull.head)
+            .sort((a, b) => Date.parse(b.startedAt ?? b.updatedAt) - Date.parse(a.startedAt ?? a.updatedAt) || b.id - a.id)[0];
+        if (current) {
+            out.currentRunId = current.id;
+            // Attempt-specific metadata prevents a previous attempt's timing from being used.
+            const detailed = runOf(await get(`${base}/actions/runs/${current.id}/attempts/${current.attempt}`));
+            if (!detailed || detailed.id !== current.id || detailed.attempt !== current.attempt
+                || detailed.head !== current.head || detailed.workflowHead !== current.workflowHead)
+                throw new Error();
+            Object.assign(current, detailed);
+            if (current.conclusion === 'failure' || current.conclusion === 'startup_failure') {
+                const jobs = await get(`${base}/actions/runs/${current.id}/attempts/${current.attempt}/jobs?per_page=${LIMIT}`);
+                const failed = collection(jobs, 'jobs').map(object).filter((j) => j?.conclusion === 'failure');
+                // Several app jobs must not assign one sibling's stage to the selected app.
+                if (failed.length === 1 && failed[0].run_id === current.id && failed[0].head_sha === current.workflowHead
+                    && Array.isArray(failed[0].steps) && failed[0].steps.length <= 100) {
+                    const stages = failed[0].steps.map(object).filter((s) => s?.conclusion === 'failure').map((s) => stageOf(s?.name));
+                    if (stages.length && stages.every((s) => s !== null && s === stages[0]))
+                        current.stage = stages[0];
+                }
+            }
+        }
+        const finalPull = readPull(await get(`${base}/pulls/${pr}`));
+        if (!finalPull || finalPull.head !== out.pull.head)
+            return { ...out, pull: finalPull,
+                runs: [], currentRunId: null, error: 'head-changed' };
+        return out;
+    }
+    catch {
+        // Retain no partial data with an unchecked final head; never echo gh exceptions.
+        return { ...out, pull: null, runs: [], currentRunId: null,
+            coverage: { ...out.coverage, incomplete: true }, error: 'evidence-unavailable' };
+    }
+}
+const previewMemories = new WeakMap();
+const PREVIEW_RUN = { type: 'object', additionalProperties: false,
+    properties: { appKey: { type: 'string', minLength: 1, description: 'The app\'s key from the state; needed only when the repository has several apps.' } } };
+const PREVIEW_FIELDS = new Set(['runtimeVersion', 'installCommand', 'prepareCommand', 'buildCommand', 'seedCommand', 'startCommand', 'outputDir', 'port', 'env', 'service', 'intendedMethod']);
+const PREVIEW_STAGES = ['setup', 'install', 'prepare', 'build', 'seed', 'start', 'tunnel', 'upload'];
+/** Map known failure signatures to fixed prose; arbitrary log text never leaves memory. */
+function previewReason(raw) {
+    if (typeof raw !== 'string')
+        return 'The detailed cause was not verified; inspect the linked run.';
+    if (/Entry page not found|Cannot open|No such file|ENOENT/i.test(raw))
+        return 'Expected output or an entry file was not found.';
+    if (/command not found|Cannot find module|Module not found/i.test(raw))
+        return 'A required command or module was not found.';
+    if (/lockfile|package.manager|corepack/i.test(raw))
+        return 'The package manager or lockfile could not be used.';
+    if (/ECONNREFUSED|did not answer/i.test(raw))
+        return 'The application did not answer its readiness check.';
+    if (/EADDRINUSE/i.test(raw))
+        return 'The configured port was already in use.';
+    if (/forbidden|blocked host|403/i.test(raw))
+        return 'The preview request was refused; check access and the forwarded host.';
+    return 'The detailed cause was not verified; inspect the linked run.';
+}
+// Workflow operations keep raw subprocess output in memory.
+/** Keep authentication available, but never redirect repository reads or persist transport traces. */
+export function workflowGitEnvironment() {
+    const env = { ...process.env };
+    for (const key of Object.keys(env))
+        if (/^GIT_TRACE/.test(key) || /^GIT_CONFIG_(?:COUNT|KEY_\d+|VALUE_\d+)$/.test(key)
+            || ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_NAMESPACE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY',
+                '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',
+        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' });
+}
+const record = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+export function workflowDefaultBranch(value) {
+    if (typeof value !== 'string' || !value || value.length > 255 || value === '@' || value.startsWith('-')
+        || /[\s~^:?*\[\\\x00-\x1f\x7f]/.test(value) || value.includes('..') || value.includes('@{'))
+        return null;
+    return value.split('/').every((part) => part && !part.startsWith('.') && !part.endsWith('.') && !part.endsWith('.lock')) ? value : null;
+}
+function scopeEvidence(value) {
+    if (typeof value !== 'string' || value.length > 2048 || !value.trim())
+        return 'unknown';
+    const scopes = value.split(',').map((part) => part.trim().replace(/^'([^']*)'$/, '$1'));
+    if (!scopes.length || scopes.some((scope) => !/^[a-z][a-z0-9_:-]*$/.test(scope)))
+        return 'unknown';
+    return scopes.includes('workflow') ? 'present' : 'missing';
+}
+export function workflowRemoteEvidence(raw, owner, repo) {
+    const lines = raw.trim().split(/\r?\n/);
+    if (!raw.trim() || lines.length > 16)
+        return { transport: 'unknown', originMatches: null };
+    const results = lines.map((line) => {
+        let path, transport;
+        const scp = /^git@github\.com:([^\s?#]+)$/.exec(line);
+        if (scp) {
+            path = scp[1];
+            transport = 'ssh';
+        }
+        else {
+            let url;
+            try {
+                url = new URL(line);
+            }
+            catch {
+                return { transport: 'unknown', matches: null };
+            }
+            if (!['https:', 'ssh:'].includes(url.protocol))
+                return { transport: 'unknown', matches: null };
+            transport = url.protocol === 'https:' ? 'https' : 'ssh';
+            if (url.hostname !== 'github.com' || url.search || url.hash
+                || (transport === 'https' && url.port && url.port !== '443')
+                || (transport === 'ssh' && (url.username !== 'git' || url.password || (url.port && url.port !== '22'))))
+                return { transport, matches: false };
+            path = url.pathname.replace(/^\//, '');
+        }
+        const normalized = path.replace(/\.git$/, '');
+        return { transport, matches: normalized.toLowerCase() === `${owner}/${repo}`.toLowerCase() };
+    });
+    const transports = new Set(results.map((r) => r.transport));
+    return { transport: transports.has('unknown') ? 'unknown' : transports.size > 1 ? 'mixed' : results[0].transport,
+        originMatches: results.some((r) => r.matches === false) ? false : results.some((r) => r.matches === null) ? null : true };
+}
+/** Read-only account/branch/transport evidence. Neither SSH nor gh authentication proves a workflow push is authorized. */
+export async function readWorkflowAccess(owner, repo, root, dependencies = {}) {
+    const out = { authenticated: null, defaultBranch: null, transport: 'unknown', originMatches: null,
+        workflowScope: 'unknown', scopeEvidence: 'github-cli', needsWorkflowScope: false,
+        gitIdentity: 'unverified', workflowWriteAccess: 'unverified', issues: [] };
+    if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/.test(owner)
+        || !/^[A-Za-z0-9_.-]{1,100}$/.test(repo) || ['.', '..'].includes(repo) || !isAbsolute(root))
+        return { ...out, issues: ['invalid-input'] };
+    if (dependencies.signal?.aborted)
+        return { ...out, issues: ['cancelled'] };
+    const run = dependencies.run ?? (async (binary, args, options) => {
+        const { stdout } = await execFileAsync(binary, args, { cwd: options.cwd, signal: options.signal,
+            timeout: 30_000, maxBuffer: 256 * 1024, encoding: 'utf8',
+            env: workflowGitEnvironment() });
+        return stdout;
+    });
+    async function read(binary, args) {
+        const text = await run(binary, args, { cwd: root, signal: dependencies.signal });
+        if (dependencies.signal?.aborted || typeof text !== 'string' || text.length > 256 * 1024)
+            throw new Error();
+        return text;
+    }
+    const [auth, branch, remote] = await Promise.allSettled([
+        read('gh', ['auth', 'status', '--active', '--hostname', 'github.com', '--json', 'hosts']),
+        read('gh', ['repo', 'view', `github.com/${owner}/${repo}`, '--json', 'defaultBranchRef']),
+        read('git', ['remote', 'get-url', '--push', '--all', 'origin']),
+    ]);
+    if (dependencies.signal?.aborted)
+        return { ...out, issues: ['cancelled'] };
+    try {
+        if (auth.status !== 'fulfilled')
+            throw new Error();
+        const hosts = record(record(JSON.parse(auth.value))?.hosts), accounts = hosts?.['github.com'];
+        if (!Array.isArray(accounts) || accounts.length > 100)
+            throw new Error();
+        const rows = accounts.map(record);
+        if (rows.some((account) => !account || typeof account.active !== 'boolean' || account.host !== 'github.com' || typeof account.state !== 'string'))
+            throw new Error();
+        const active = rows.filter((account) => account.active === true);
+        if (active.length === 0)
+            out.authenticated = false;
+        else if (active.length !== 1)
+            out.issues.push('authentication-ambiguous');
+        else if (active[0].state === 'success') {
+            out.authenticated = true;
+            out.workflowScope = scopeEvidence(active[0].scopes);
+        }
+        else if (active[0].state === 'failure' || active[0].state === 'error')
+            out.authenticated = false;
+        else
+            throw new Error();
+    }
+    catch {
+        out.issues.push('authentication-unavailable');
+    }
+    try {
+        if (branch.status !== 'fulfilled')
+            throw new Error();
+        out.defaultBranch = workflowDefaultBranch(record(record(JSON.parse(branch.value))?.defaultBranchRef)?.name);
+        if (!out.defaultBranch)
+            throw new Error();
+    }
+    catch {
+        out.issues.push('default-branch-unavailable');
+    }
+    if (remote.status === 'fulfilled') {
+        Object.assign(out, workflowRemoteEvidence(remote.value, owner, repo));
+        if (out.originMatches === false)
+            out.issues.push('push-remote-mismatch');
+        else if (out.originMatches === null)
+            out.issues.push('push-remote-unavailable');
+    }
+    else
+        out.issues.push('push-remote-unavailable');
+    out.needsWorkflowScope = out.authenticated === true && out.transport === 'https' && out.originMatches === true && out.workflowScope === 'missing';
+    return out;
+}
+/**
+ * Refresh only origin/<default>, after workflow_access proved its push target.
+ * Fetch URL is independently checked; redirects/config rewrites are not guessed.
+ * This does not checkout a branch or prove push/workflow-write authorization.
+ */
+export async function refreshWorkflowBase(owner, repo, defaultBranch, root, dependencies = {}) {
+    const branch = workflowDefaultBranch(defaultBranch);
+    const fail = (reason) => ({ status: 'unverified', branch, sha: null, reason });
+    if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/.test(owner)
+        || !/^[A-Za-z0-9_.-]{1,100}$/.test(repo) || ['.', '..'].includes(repo) || !branch || !isAbsolute(root))
+        return fail('invalid-input');
+    if (dependencies.signal?.aborted)
+        return fail('cancelled');
+    const env = workflowGitEnvironment();
+    const run = dependencies.run ?? (async (args, options) => {
+        const { stdout } = await execFileAsync('git', args, { ...options, encoding: 'utf8', timeout: 30_000, maxBuffer: 256 * 1024 });
+        return stdout;
+    });
+    async function read(args) {
+        if (dependencies.signal?.aborted)
+            throw new Error();
+        const text = await run(args, { cwd: root, signal: dependencies.signal, env });
+        if (dependencies.signal?.aborted || typeof text !== 'string' || text.length > 256 * 1024)
+            throw new Error();
+        return text;
+    }
+    let stage = 'fetch-remote-unverified';
+    try {
+        const urls = await read(['remote', 'get-url', '--all', 'origin']);
+        if (workflowRemoteEvidence(urls, owner, repo).originMatches !== true)
+            return fail(stage);
+        stage = 'fetch-unverified';
+        const destination = `refs/remotes/origin/${branch}`;
+        await read(['-c', 'credential.interactive=false', '-c', 'core.askPass=', 'fetch', '--quiet', '--no-tags',
+            '--no-prune', '--no-prune-tags', '--no-recurse-submodules', '--no-write-fetch-head',
+            '--no-auto-maintenance', '--no-write-commit-graph', '--refmap=', 'origin', `refs/heads/${branch}:${destination}`]);
+        stage = 'reference-unverified';
+        const sha = (await read(['rev-parse', '--verify', '--end-of-options', `${destination}^{commit}`])).trim();
+        if (!/^[0-9a-f]{40}$/.test(sha))
+            return fail(stage);
+        return { status: 'refreshed', branch, sha };
+    }
+    catch {
+        return fail(dependencies.signal?.aborted ? 'cancelled' : stage);
+    }
+}
+export function createWorkflowSynchronizer() {
+    const CURRENT = '.github/workflows/impeccable-preview.yml';
+    const RETIRED = '.github/workflows/pristine-preview.yml';
+    const MAX_BYTES = 1_000_000;
+    const standings = ['absent', 'current', 'out-of-date', 'older-generation', 'retired', 'unknown'];
+    const obj = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+    const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+    const equal = (a, b) => a === null || b === null ? a === b : a.equals(b);
+    class Refusal extends Error {
+    }
+    function refuse(message) { throw new Refusal(message); }
+    /** Every raw Git byte, including errors, stays in memory and is never logged. */
+    async function git(cwd, args, signal) {
+        return new Promise((resolve, reject) => {
+            execFile('git', ['-c', 'core.fsmonitor=false', ...args], {
+                cwd, signal, timeout: 10_000, maxBuffer: MAX_BYTES, encoding: 'buffer',
+                env: workflowGitEnvironment(),
+            }, (error, stdout) => error ? reject(new Refusal('The local workflow state could not be checked.')) : resolve(stdout));
+        });
+    }
+    /** Reject every existing symlink/directory mismatch; only these fixed paths enter. */
+    async function pathState(root, path) {
+        const segments = path.split('/');
+        let absolute = root;
+        for (let i = 0; i < segments.length; i++) {
+            absolute = join(absolute, segments[i]);
+            let stat;
+            try {
+                stat = await lstat(absolute);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return { bytes: null, mode: 0o644 };
+                throw error;
+            }
+            if (stat.isSymbolicLink())
+                refuse('A workflow path contains a symbolic link. Nothing was changed.');
+            if (i < segments.length - 1 && !stat.isDirectory())
+                refuse('A workflow parent is not a directory. Nothing was changed.');
+            if (i === segments.length - 1) {
+                if (!stat.isFile() || stat.size > MAX_BYTES)
+                    refuse('The local workflow is not a supported regular file. Nothing was changed.');
+                return { bytes: await readFile(absolute), mode: stat.mode & 0o777 };
+            }
+        }
+        throw new Error('Unreachable fixed workflow path');
+    }
+    async function snapshot(root, path, signal) {
+        const file = await pathState(root, path);
+        const [index, status] = await Promise.all([
+            git(root, ['ls-files', '--stage', '-z', '--', path], signal),
+            git(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all', '--no-renames', '--', path], signal),
+        ]);
+        const entries = index.toString('utf8').split('\0').filter(Boolean);
+        const entry = entries[0];
+        const match = entry ? /^(100644|100755) ([a-f0-9]{40}|[a-f0-9]{64}) 0\t(.+)$/.exec(entry) : null;
+        if (entries.length > 1 || (entry && (!match || match[3] !== path)))
+            refuse('The workflow index has an unsupported entry or unresolved conflict. Nothing was changed.');
+        return { ...file, index: entry ?? '', indexBytes: match ? await git(root, ['cat-file', 'blob', match[2]], signal) : null, dirty: status.length > 0 };
+    }
+    function checkOwnership(file, owned) {
+        if (!owned) {
+            // An ignored untracked file may have empty status; existence/index parity
+            // also prevents adopting it as an Impeccable-owned file.
+            if (file.dirty || !equal(file.bytes, file.indexBytes))
+                refuse('The workflow has local edits. Keep those edits and resolve them before syncing.');
+            return;
+        }
+        const ownIndex = equal(file.indexBytes, owned.bytes)
+            && (owned.bytes === null ? !file.index : file.index.startsWith(owned.mode & 0o111 ? '100755 ' : '100644 '));
+        if (!equal(file.bytes, owned.bytes) || (file.bytes && file.mode !== owned.mode)
+            || (file.index !== owned.baselineIndex && !ownIndex))
+            refuse('The workflow changed since this run wrote it. Keep those edits and resolve them before syncing.');
+    }
+    function offeredPreview(state, repoName) {
+        const repos = obj(state)?.repos;
+        const matches = Array.isArray(repos) ? repos.map(obj).filter((repo) => repo?.name === repoName) : [];
+        const preview = matches.length === 1 ? obj(obj(matches[0]?.items)?.preview) : null;
+        const standing = preview?.workflowStanding;
+        if (!preview || preview.status === 'not-selected' || preview.status === 'skipped'
+            || !standings.includes(standing))
+            refuse('The selected repository has no verified workflow state. Nothing was changed.');
+        if (standing === 'unknown')
+            refuse('The current workflow could not be read. Its drift is unknown; nothing was changed.');
+        return { preview, standing: standing };
+    }
+    function offeredBytes(preview) {
+        const file = obj(preview.file);
+        if (file?.path !== CURRENT || typeof file.content !== 'string' || !file.content.length)
+            refuse('State did not offer the canonical workflow. Nothing was invented or changed.');
+        const bytes = Buffer.from(file.content, 'utf8');
+        if (bytes.length > MAX_BYTES || bytes.toString('utf8') !== file.content)
+            refuse('The offered workflow is not supported UTF-8 content. Nothing was changed.');
+        const methods = [preview.intendedMethod, ...(Array.isArray(preview.apps) ? preview.apps.map((app) => obj(app)?.method) : [])];
+        const tunnel = methods.includes('ci-tunnel') || /cloudflared\s+tunnel|\/api\/tunnels(?:\/|\b)/.test(file.content);
+        if (/trycloudflare\\?\.com|cloudflared\s+tunnel\s+--url|audience=pristine\.style\b|https?:\/\/pristine\.style\/api\//i.test(file.content)
+            || (tunnel && (!file.content.includes('/api/tunnels/named') || !/cloudflared\s+tunnel\s+run\b/.test(file.content)))) {
+            refuse('State offered an unsupported or retired tunnel workflow. Nothing was changed.');
+        }
+        return bytes;
+    }
+    const owned = new Map();
+    let queue = Promise.resolve();
+    return (cwd, repo, readState, signal) => {
+        const run = async () => {
+            const actions = [];
+            let temporary;
+            try {
+                signal?.throwIfAborted();
+                const root = await realpath(cwd);
+                const topLevel = (await git(root, ['rev-parse', '--show-toplevel'], signal)).toString('utf8').trim();
+                if (await realpath(topLevel) !== root)
+                    refuse('Run workflow sync from the selected repository root. Nothing was changed.');
+                const { preview, standing } = offeredPreview(await readState(), repo);
+                const retired = preview.workflowRetiredPath;
+                if (retired != null && retired !== RETIRED && retired !== CURRENT)
+                    refuse('State named an unsupported retired workflow path. Nothing was changed.');
+                // Retired CURRENT is replaced in place, never deleted after replacement.
+                const removeLegacy = retired === RETIRED;
+                const desired = standing === 'current' ? null : offeredBytes(preview);
+                const paths = removeLegacy ? [CURRENT, RETIRED] : [CURRENT];
+                const before = new Map();
+                for (const path of paths) {
+                    const file = await snapshot(root, path, signal);
+                    checkOwnership(file, owned.get(`${root}/${path}`));
+                    before.set(path, file);
+                }
+                if (desired === null && before.get(CURRENT).bytes === null)
+                    refuse('State says current, but no canonical workflow is present locally. Refresh the default branch before continuing.');
+                // Validate both candidates before any mutation, then check again to
+                // catch ordinary edits made while the fresh state/Git reads ran.
+                for (const path of paths) {
+                    const now = await snapshot(root, path, signal), was = before.get(path);
+                    if (!equal(now.bytes, was.bytes) || now.mode !== was.mode || now.index !== was.index || now.dirty !== was.dirty)
+                        refuse('A workflow changed while it was being checked. Nothing was changed.');
+                }
+                signal?.throwIfAborted();
+                const current = before.get(CURRENT);
+                if (desired !== null && !equal(current.bytes, desired)) {
+                    const target = join(root, CURRENT);
+                    await mkdir(dirname(target), { recursive: true });
+                    await pathState(root, CURRENT);
+                    temporary = join(dirname(target), `.impeccable-${randomBytes(12).toString('hex')}.tmp`);
+                    await writeFile(temporary, desired, { flag: 'wx', mode: current.mode });
+                    await chmod(temporary, current.mode);
+                    await rename(temporary, target);
+                    temporary = undefined;
+                    owned.set(`${root}/${CURRENT}`, { bytes: desired, mode: current.mode, baselineIndex: current.index });
+                    actions.push({ path: CURRENT, action: 'written', bytes: desired.length, sha256: digest(desired) });
+                }
+                const legacy = before.get(RETIRED);
+                if (removeLegacy && legacy?.bytes !== null) {
+                    await unlink(join(root, RETIRED));
+                    owned.set(`${root}/${RETIRED}`, { bytes: null, mode: 0o644, baselineIndex: legacy.index });
+                    actions.push({ path: RETIRED, action: 'removed' });
+                }
+                let committedMatches = null;
+                if (desired !== null) {
+                    try {
+                        const entry = (await git(root, ['ls-tree', '-z', 'HEAD', '--', CURRENT], signal)).toString('utf8');
+                        if (!entry)
+                            committedMatches = false;
+                        else {
+                            const match = /^(?:100644|100755) blob ([a-f0-9]{40}|[a-f0-9]{64})\t\.github\/workflows\/impeccable-preview\.yml\0$/.exec(entry);
+                            if (match)
+                                committedMatches = equal(await git(root, ['cat-file', 'blob', match[1]], signal), desired);
+                        }
+                    }
+                    catch { /* local writes can succeed while commit evidence is unavailable */ }
+                }
+                let stagedMatches = desired === null ? null : equal(current.indexBytes, desired);
+                let retiredCommitted = null;
+                const retiredStaged = removeLegacy ? !legacy.index : null;
+                if (removeLegacy) {
+                    try {
+                        retiredCommitted = (await git(root, ['ls-tree', '-z', 'HEAD', '--', RETIRED], signal)).length === 0;
+                    }
+                    catch { /* Absence in the working tree does not prove a committed deletion. */ }
+                    if (stagedMatches === true)
+                        stagedMatches = retiredStaged;
+                    if (committedMatches === true)
+                        committedMatches = retiredCommitted;
+                }
+                return { ok: true, standing, actions, localOnly: true, stagedMatches, committedMatches,
+                    ...(removeLegacy ? { retiredRemoval: { path: RETIRED, staged: retiredStaged, committed: retiredCommitted } } : {}) };
+            }
+            catch (error) {
+                return { ok: false, actions, reason: error instanceof Refusal ? error.message : 'The workflow could not be synchronized. Inspect the local files before continuing.' };
+            }
+            finally {
+                if (temporary)
+                    await unlink(temporary).catch(() => { });
+            }
+        };
+        const result = queue.then(run, run);
+        queue = result.then(() => undefined, () => undefined);
+        return result;
+    };
+}
+export function createTools(ctx) {
+    const text = (t, terminate = false) => ({ content: [{ type: 'text', text: t }], details: undefined, ...(terminate ? { terminate } : {}) });
+    const retry = previewRetryState(ctx.log);
+    retry.repository ??= `${ctx.owner}/${ctx.repo}`;
+    /** The branches of the recorded test drive and setup pull request, as GitHub named them. */
+    let recordedBranches;
+    retry.recordedPr ??= ctx.sync.payload.setup_pr;
+    let memory = previewMemories.get(ctx.log);
+    if (!memory) {
+        memory = { active: false, knownRuns: new Map(), attempts: new Map(), changes: new Set() };
+        previewMemories.set(ctx.log, memory);
+    }
+    const previews = memory;
+    const attempts = () => [...previews.attempts.values()].sort((a, b) => a.runId - b.runId || a.attempt - b.attempt);
+    const budget = () => ({ used: retry.used, pushReservations: retry.pushReservations, remaining: Math.max(0, 3 - retry.used), historyKnown: retry.historyKnown });
+    const attemptTasks = () => attempts().map((a, i) => ({ id: `preview-attempt-${a.runId}-${a.attempt}`,
+        title: `Preview job attempt ${i + 1}`, status: a.status === 'success' ? 'completed' : a.status === 'running' ? 'in_progress' : 'failed' }));
+    const withAttempts = (tasks) => [...tasks.filter((t) => !t.id.startsWith('preview-attempt-')), ...attemptTasks()];
+    async function observe(signal) {
+        const pr = retry.pr;
+        const reservationsAtStart = retry.pushReservations;
+        let observation;
+        try {
+            observation = await (ctx.previewRunReader ?? readPreviewRuns)(ctx.owner, ctx.repo, pr.number, pr.branch, { signal, knownRuns: previews.knownRuns });
+        }
+        catch {
+            observation = { pull: null, runs: [], currentRunId: null,
+                coverage: { limit: 20, truncated: false, incomplete: true, unassociatedHistory: false }, error: 'evidence-unavailable' };
+        }
+        const complete = reservationsAtStart === retry.pushReservations && !observation.error && !observation.coverage.truncated && !observation.coverage.incomplete && !observation.coverage.unassociatedHistory;
+        observePreviewAttempts(retry, observation.runs.map((r) => ({ runId: r.id, attempt: r.attempt })), complete);
+        if (!observation.error)
+            for (const run of observation.runs) {
+                if (previews.knownRuns.size < LIMIT || previews.knownRuns.has(run.id))
+                    previews.knownRuns.set(run.id, { head: run.head, workflowHead: run.workflowHead });
+                else
+                    retry.historyKnown = false;
+            }
+        return observation;
+    }
+    /** What the person typed into sensitive questions, by the reference the model holds instead. */
+    const typed = new Map();
+    /** The origins of the successful Preview deployments of pull requests GitHub listed, and of the built deploy previews Netlify's evidence listed, which a proof may open; whether one answered with this app; and the address pattern a Netlify proof answered. */
+    const listedPreviews = new Set();
+    const netlifyListed = new Set();
+    let hostedPreviewProven = false;
+    let provenPattern;
+    /** The host whose preview a proof answered with this app, and the one whose previews impeccable_write then saved as the method. */
+    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.
+     */
+    async function awaitBuild(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 });
+        try {
+            for (const end = Date.now() + wait.totalMs; !built(evidence) && Date.now() < end; evidence = await read()) {
+                await sleep(wait.everyMs, undefined, { signal });
+            }
+        }
+        finally {
+            reportWait(null);
+        }
+        return evidence;
+    }
+    /** 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) => {
+        const found = await ctx.viewPullRequest(pull);
+        return 'headRefName' in found && testDriveBranch(found.headRefName) ? "the test drive's preview" : `the preview of #${pull}`;
+    };
+    /** Of the origins listed, those of deployments Vercel's own bot made: the only addresses a bypass secret is ever sent to, since a deployment anyone with write access can record names any address. */
+    const vercelMade = new Set();
+    /** The address impeccable_prove_preview met Vercel's login at, and the words it looked for there. */
+    let gated;
+    /** The bypass secret saved in this run, for the proof of a Vercel address to send; never for the model. It is one project's, so it goes only to the origins impeccable_vercel_bypass proved it on, never to another project's deployment of this repository. */
+    let bypassSecret;
+    const bypassOrigins = new Set();
+    /** What impeccable_vercel_bypass answered, less the secret: a skip is asked once, so that answer stands; the saved one is what an address the secret opens later gets. */
+    let bypassOutcome;
+    let bypassSaved;
+    // Keep ownership of files for this one run; never recreate it per call.
+    const workflowSynchronizer = ctx.workflowSynchronizer ?? createWorkflowSynchronizer();
+    const workflowRefusal = (reason) => ({ ok: false, reason, actions: [] });
+    const workflowReady = (access) => access.authenticated === true
+        && access.originMatches === true && access.defaultBranch !== null && !access.needsWorkflowScope;
+    async function workflowPreparation(pi, signal) {
+        signal?.throwIfAborted();
+        const access = await (ctx.workflowAccessReader ?? readWorkflowAccess)(ctx.owner, ctx.repo, pi.cwd, { signal });
+        signal?.throwIfAborted();
+        const base = workflowReady(access)
+            ? await (ctx.workflowBaseRefresher ?? refreshWorkflowBase)(ctx.owner, ctx.repo, access.defaultBranch, pi.cwd, { signal })
+            : null;
+        signal?.throwIfAborted();
+        return { ...access, base };
+    }
+    // This call deliberately omits requestJson's logger: its network-error catch
+    // logs raw exception text. Only fixed failures leave this owned boundary.
+    async function freshWorkflowState(pi, signal) {
+        try {
+            signal?.throwIfAborted();
+            const read = async (token) => {
+                signal?.throwIfAborted();
+                const result = await requestJson(`${ctx.setupApi}/state`, { token });
+                signal?.throwIfAborted();
+                return result;
+            };
+            let result = await read(await ctx.auth.token(pi));
+            if (result.status === 401)
+                result = await read(await ctx.auth.renew(pi));
+            if (!result.ok)
+                throw new Error();
+            return result.data;
+        }
+        catch {
+            throw new Error('The current workflow state could not be read. Nothing was synchronized.');
+        }
+    }
+    async function workflowAccessTool(pi, signal) {
+        try {
+            return JSON.stringify(await workflowPreparation(pi, signal));
+        }
+        catch {
+            return JSON.stringify(workflowRefusal(signal?.aborted
+                ? 'Workflow access was cancelled.' : 'Workflow access could not be checked. Nothing was synchronized.'));
+        }
+    }
+    /** A status line from a tool, on the screen and the web page as the model's own [STATUS] lines go. */
+    const said = (status) => {
+        ctx.sync.update({ status });
+        reportStatus(status);
+    };
+    /** A screen a tool puts up on its own: the web page shows the run waiting on it, as on the model's questions, until it is answered. */
+    const ask = async (screen) => {
+        ctx.sync.update({ phase: 'waiting', question: { id: screen.id, prompt: screen.prompt } });
+        const answer = await askPerson({ ...screen, skippable: true });
+        ctx.sync.update({ phase: 'running', question: null });
+        return answer;
+    };
+    /** Each host's sign-in this run: confirmed on its screen, or found signed in already, so the screen shows once; skipped, so nothing more is asked for that host. */
+    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();
+    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 });
+        const cli = runner();
+        if (host === 'vercel') {
+            return {
+                status: () => vercelStatus(cli),
+                login: () => runner(true)(['login']),
+                // The CLI's current scope is the team; one team is the team; several with none current are the person's pick.
+                team: async () => {
+                    const teams = await vercelTeams(cli);
+                    const one = teams.find((t) => t.current) ?? (teams.length === 1 ? teams[0] : undefined);
+                    return one ? { team: one.value, choices: [] } : { choices: teams.map(({ label, value }) => ({ label, value })) };
+                },
+            };
+        }
+        let teams = [];
+        return {
+            status: async () => { const status = await netlifyStatus(cli); teams = status.teams; return status; },
+            login: () => runner(true)(['login']),
+            // The CLI creates the site in the person's own current team; several teams are the person's pick, which the fence takes for `--account-slug`.
+            team: async () => ({ choices: teams.length > 1 ? await netlifyTeams(cli) : [] }),
+        };
+    };
+    /**
+     * A host's sign-in, on `impeccable_ask` with the id `<host>-setup`: a CLI signed in already opens the setup with no
+     * screen; else the sign-in screen once, and on its yes the CLI's login in the browser, checked with the CLI, a retry
+     * screen when it did not complete, and after two failed retries a skip. The fence opens on the sign-in found or
+     * completed (and on the yes for the CLI's install alone): never on anything the model writes.
+     */
+    async function hostSignIn(host, pi, signal) {
+        const cli = hostCli(host, pi, signal);
+        const signedIn = async () => {
+            agreeToHostSetup(ctx.log, `${host}-setup`);
+            hostSignIns.set(host, 'confirmed');
+            const { team, choices } = await cli.team();
+            if (team)
+                chooseHostTeam(ctx.log, `${host}-team`, team);
+            teamChoices.set(host, choices);
+            return { confirmed: true, signedIn: true, ...(team ? { team } : {}), ...(choices.length > 1 ? { teams: choices } : {}) };
+        };
+        if (hostSignIns.get(host) === 'skipped')
+            return { skipped: true };
+        let status = await cli.status();
+        if (status.cli === 'signed-in')
+            return signedIn();
+        if (!hostSignIns.has(host)) {
+            const answer = await ask({ id: `${host}-setup`, ...HOST_QUESTIONS[`${host}-setup`] });
+            if (answer.skipped) {
+                hostSignIns.set(host, 'skipped');
+                return { skipped: true };
+            }
+            hostSignIns.set(host, 'confirmed');
+        }
+        // The CLI is installed through the fence's package-manager rule, which this yes opens; then this is asked again.
+        if (status.cli === 'missing') {
+            agreeToHostSetup(ctx.log, `${host}-setup`);
+            return { confirmed: true, cli: 'missing' };
+        }
+        for (let attempt = 0;; attempt++) {
+            said(`Opening the browser for ${HOST_NAMES[host]}'s login`);
+            try {
+                await cli.login();
+            }
+            catch {
+                // What the status says decides.
+            }
+            status = await cli.status();
+            if (status.cli === 'signed-in')
+                return signedIn();
+            if (attempt === 2) {
+                hostSignIns.set(host, 'skipped');
+                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');
+                return { skipped: true };
+            }
+        }
+    }
+    /**
+     * The one-time access a host's GitHub app needs when it cannot reach the repository: a screen that opens the app's page
+     * on GitHub, a wait of up to five minutes for the host to reach it (`reaches`, tried again every so often), a retry
+     * screen, and after two failed retries the connection left to the person.
+     */
+    async function hostAccess(host, result, reaches, signal) {
+        const name = HOST_NAMES[host];
+        for (let retries = 0; result.access && !signal?.aborted; retries++) {
+            if ((await ask(HOST_SCREENS[retries ? `${host}-access-retry` : `${host}-access`])).skipped)
+                return { ...result, reason: `The person skipped giving ${name}'s GitHub app access to the repository.` };
+            (ctx.openBrowser ?? openBrowser)(result.access);
+            said(`Waiting for ${name} to reach the repository`);
+            result = await reaches();
+            if (signal?.aborted)
+                return { ...result, reason: `The run stopped while ${name} was waited for.` };
+            if (result.access && retries === 2)
+                return { ...result, reason: `${name}'s GitHub app still cannot reach the repository.` };
+        }
+        return result;
+    }
+    /** The connection of the linked Netlify site with this repository, through Netlify's site settings and its GitHub app, with the app's access asked when it cannot read the repository. */
+    async function netlifyConnect(pi, settings, signal) {
+        // The site's settings change on the host: only once the person opened the Netlify setup, as the fence holds for the CLI.
+        if (!hostSetupAgreed(ctx.log, 'netlify'))
+            return { connected: false, reason: 'The Netlify sign-in comes first: impeccable_ask with the id netlify-setup.' };
+        const netlify = (ctx.hostRunner ?? commandRunner)('netlify', pi.cwd, { signal });
+        const gh = (ctx.hostRunner ?? commandRunner)('gh', pi.cwd, { signal });
+        const clone = ctx.hostWait?.clone;
+        const result = await connectNetlifySite(ctx.owner, ctx.repo, pi.cwd, { netlify, gh, settings, signal, ...(clone ? { wait: clone } : {}) });
+        // A build every 30 s until one reads the repository: the person is giving the app access meanwhile.
+        return hostAccess('netlify', result, async () => (await waitForNetlifyAccess(result.site.id, { netlify, signal, wait: ctx.hostWait?.access ?? { totalMs: 300_000, everyMs: 30_000 }, ...(clone ? { clone } : {}) })
+            ? { connected: true, site: result.site, how: 'github-app' } : result), signal);
+    }
+    /** The connection of the linked Vercel project with this repository, `vercel git connect`, with the app's access asked when Vercel's GitHub app cannot reach the repository. */
+    async function vercelConnect(pi, signal) {
+        if (!hostSetupAgreed(ctx.log, 'vercel'))
+            return { connected: false, reason: 'The Vercel sign-in comes first: impeccable_ask with the id vercel-setup.' };
+        const vercel = (ctx.hostRunner ?? commandRunner)('vercel', pi.cwd, { signal });
+        const result = await connectVercelProject(vercel);
+        // Tried again every 20 s until the app reaches the repository: the person is giving it access meanwhile.
+        return hostAccess('vercel', result, () => waitForVercelAccess(vercel, { wait: ctx.hostWait?.access ?? { totalMs: 300_000, everyMs: 20_000 }, signal }), signal);
+    }
+    async function syncWorkflowTool(pi, signal) {
+        try {
+            const access = await workflowPreparation(pi, signal);
+            if (!workflowReady(access))
+                return JSON.stringify(workflowRefusal(access.needsWorkflowScope ? 'The active GitHub CLI account is missing workflow scope for HTTPS. Recheck access after updating it.'
+                    : 'Workflow access is not ready. Recheck authentication, origin and the default branch.'));
+            if (access.base?.status !== 'refreshed' || access.base.branch !== access.defaultBranch || !access.base.sha)
+                return JSON.stringify(workflowRefusal('The current default branch could not be refreshed. Nothing was synchronized.'));
+            signal?.throwIfAborted();
+            return JSON.stringify(await workflowSynchronizer(pi.cwd, ctx.repo, () => freshWorkflowState(pi, signal), signal));
+        }
+        catch {
+            return JSON.stringify(workflowRefusal(signal?.aborted
+                ? 'Workflow synchronization was cancelled.' : 'The workflow could not be synchronized. Inspect the local files before continuing.'));
+        }
+    }
+    function tool(name, label, description, schema, run) {
+        return defineTool({
+            name,
+            label,
+            description,
+            parameters: schema,
+            async execute(_id, params, signal, _onUpdate, pi) {
+                const error = schemaError(schema, params);
+                if (error)
+                    return text(`Invalid input: ${error}.`);
+                try {
+                    const out = await run(params, pi, signal);
+                    return typeof out === 'string' ? text(out) : text(out.text, out.terminate);
+                }
+                catch (err) {
+                    ctx.log.write(`${name} failed`, err instanceof Error ? err.message : String(err));
+                    return text(`Error: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            },
+        });
+    }
+    /** A setup API call with the current setup token, and once more after signing in again if the API refuses it. */
+    const call = async (pi, url, init = {}) => {
+        const res = await requestJson(url, { ...init, token: await ctx.auth.token(pi) }, ctx.log);
+        return res.status === 401 ? requestJson(url, { ...init, token: await ctx.auth.renew(pi) }, ctx.log) : res;
+    };
+    /** A read of the setup API, trimmed to this setup before the model sees it. */
+    const get = async (pi, path, focus) => {
+        const res = await call(pi, `${ctx.setupApi}${path}`);
+        return answerText(res.ok ? { ...res, data: focus(res.data) } : res);
+    };
+    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_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.';
+            if (p.appKey !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(p.appKey))
+                return 'Refused: use the app key from setup state.';
+            previews.active = true;
+            retry.requireHistory = true;
+            const observation = await observe(signal);
+            const state = await call(pi, `${ctx.setupApi}/state`);
+            const repos = object(state.data)?.repos;
+            const repo = Array.isArray(repos) ? repos.map(object).find((r) => r?.name === ctx.repo) : undefined;
+            const preview = object(object(repo?.items)?.preview);
+            const apps = Array.isArray(preview?.apps) ? preview.apps.map(object).filter((a) => a) : [];
+            const declarations = Array.isArray(repo?.apps) ? repo.apps.map(object).filter((a) => a?.enabled !== false) : [];
+            const selectedKey = p.appKey;
+            const onlyKey = apps.length === 1 && typeof apps[0]?.key === 'string' ? apps[0].key : typeof preview?.app === 'string' ? preview.app : declarations.length === 1 && typeof declarations[0]?.key === 'string' ? declarations[0].key : 'main';
+            const selected = apps.length ? (apps.length > 1 && !selectedKey ? undefined : apps.find((a) => a?.key === (selectedKey ?? onlyKey))) : !selectedKey || selectedKey === onlyKey ? preview : undefined;
+            if (!state.ok || !selected || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(selectedKey ?? onlyKey)
+                || (!apps.length && declarations.length > 1 && !preview?.app))
+                return JSON.stringify({ ...observation, attempts: attempts(), budget: budget(), diagnosis: 'The selected app state could not be verified.' });
+            const appKey = selectedKey ?? onlyKey;
+            previews.selectedApp = appKey;
+            let recordedChanges = false;
+            for (const run of observation.runs) {
+                // Never expand arbitrary external rerun counts into an unbounded UI.
+                const observedAttempts = Array.from({ length: Math.min(run.attempt, LIMIT - 1) }, (_, i) => i + 1);
+                if (run.attempt >= LIMIT)
+                    observedAttempts.push(run.attempt);
+                for (const attempt of observedAttempts) {
+                    const key = `${run.id}/${attempt}`, previous = previews.attempts.get(key);
+                    if (!previous && previews.attempts.size >= LIMIT) {
+                        retry.historyKnown = false;
+                        continue;
+                    }
+                    if (previous && (attempt !== run.attempt || run.id !== observation.currentRunId))
+                        continue;
+                    const current = attempt === run.attempt;
+                    const failed = current && run.status === 'completed' && run.conclusion !== 'success';
+                    let stage = apps.length < 2 && current ? run.stage : null;
+                    let reason = !current ? 'This earlier attempt was not observed.' : failed
+                        ? 'The detailed cause was not verified; inspect the linked run.'
+                        : run.status === 'completed' ? 'The job passed; preview access still needs verification.' : 'The preview job is still running.';
+                    if (current && run.id === observation.currentRunId) {
+                        const last = object(selected.lastRun);
+                        const at = typeof last?.at === 'string' ? Date.parse(/^\d{4}-\d\d-\d\d \d\d:\d\d:\d\d$/.test(last.at) ? last.at.replace(' ', 'T') + 'Z' : last.at) : NaN;
+                        if (last?.runUrl === run.url && run.startedAt && at >= Date.parse(run.startedAt)
+                            && at <= Date.parse(run.updatedAt) + 60_000 && at <= Date.now() + 60_000
+                            && PREVIEW_STAGES.includes(last.failedAt) && run.conclusion !== 'success') {
+                            stage = last.failedAt;
+                            reason = previewReason(last.reason);
+                        }
+                    }
+                    const diagnostic = { appKey, stage, reason };
+                    recordedChanges ||= !previous && current && run.id === observation.currentRunId;
+                    const entry = { runId: run.id, attempt, head: run.head, url: run.url,
+                        status: !current ? 'unverified' : failed ? 'failed' : run.status === 'completed' ? 'success' : 'running', stage, reason,
+                        changes: previous?.changes ?? (run.id === observation.currentRunId ? [...previews.changes] : []),
+                        diagnostics: [...(previous?.diagnostics ?? []).filter((d) => d.appKey !== appKey), diagnostic] };
+                    previews.attempts.set(key, entry);
+                }
+            }
+            if (recordedChanges)
+                previews.changes.clear();
+            const tasks = withAttempts(ctx.sync.payload.tasks);
+            ctx.sync.update({ tasks });
+            reportTasks(tasks);
+            return JSON.stringify({ ...observation, attempts: attempts(), budget: budget() });
+        }),
+        tool('impeccable_state', 'Setup state', 'Read the setup state again, trimmed to this setup: each repository\'s scan, preview and sign-in items, and the setup page\'s other cards in notPartOfThisSetup.', NO_INPUT, (_p, pi) => get(pi, '/state', focusState)),
+        tool('impeccable_checkup', 'Checkup', 'Run the checkup for this setup\'s items: it reads GitHub again and answers status (complete, waiting or incomplete), next (what to do, in order), forPerson (what only the person can do) and waitingFor (what needs time).', NO_INPUT, (_p, pi) => get(pi, '/checkup', focusCheckup)),
+        tool('impeccable_write', 'Write a setting', 'Write a setting through the setup API, at an endpoint the instructions list and with the method they give.', WRITE, async (p, pi, signal) => {
+            const target = resolveWrite(ctx.instructions, ctx.setupApi, ctx.repo, p.path);
+            if ('error' in target)
+                return `Refused: ${target.error}`;
+            if (/\/(preview-auth\/[^/]+|preview-protection)$/.test(target.url))
+                return 'Refused: a Vercel bypass secret is saved by impeccable_vercel_bypass, which opens the preview with it first, and never through this tool. 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.";
+            }
+            const saved = object(p.body);
+            if (target.url.endsWith('/preview') && saved && 'previewUrlPattern' in saved && (typeof saved.previewUrlPattern !== 'string' || saved.previewUrlPattern.trim() !== provenPattern)) {
+                return 'Refused: the only address pattern saved is the one impeccable_prove_preview answered for a Netlify preview. Nothing was saved.';
+            }
+            const testAccounts = target.url.endsWith('/test-accounts');
+            let body = p.body;
+            if (testAccounts) {
+                // Only what the person typed into a hidden question is ever sent as a password.
+                const list = object(body)?.accounts;
+                if (!Array.isArray(list) || !list.length)
+                    return 'Refused: "accounts" lists at least one account. When the person skipped every role, write nothing: an empty list would delete the saved ones.';
+                if (list.some((account) => !typed.has(String(object(account)?.password)))) {
+                    return 'Refused: each "password" is the reference impeccable_ask gave for a password the person typed, never a password read from a file, the seed or the chat.';
+                }
+                body = { ...object(body), accounts: list.map((account) => ({ ...object(account), password: typed.get(String(object(account)?.password)) })) };
+            }
+            const checkedHead = previews.active && target.url.endsWith('/latest-pull-check') ? await observe(signal) : undefined;
+            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)))
+                    retry.requireHistory = true;
+                if (object(p.body)?.intendedMethod === 'preview-deploy')
+                    savedHost = provenHost;
+                for (const key of Object.keys(object(p.body) ?? {}))
+                    if (PREVIEW_FIELDS.has(key) && keys?.[key] === 'stored')
+                        previews.changes.add(key);
+            }
+            if (previews.active && target.url.endsWith('/latest-pull-check')) {
+                if (response.status === 429)
+                    return JSON.stringify({ waiting: true, outcome: 'rate-limited', retryAfterSeconds: 30 });
+                if (response.status === 409 && object(response.data)?.outcome === 'no-preview-running')
+                    return JSON.stringify({ waiting: true, outcome: 'no-preview-running' });
+                const after = await observe(signal);
+                const check = object(object(response.data)?.check), pull = object(check?.pull);
+                const appKey = object(p.body)?.appKey;
+                if (!response.ok || checkedHead?.error || after.error || !after.pull || checkedHead?.pull?.head !== after.pull.head
+                    || !pull || pull.number !== retry.pr?.number || pull.headSha !== after.pull.head
+                    || (appKey !== undefined && check?.appKey !== appKey) || (previews.selectedApp && appKey !== previews.selectedApp))
+                    return JSON.stringify({ verified: false, reason: 'The preview check did not match the recorded pull request, current head and selected app.' });
+                const outcome = ['reached', 'sign-in', 'not-found', 'no-preview', 'timed-out', 'unreachable', 'unverified'].find((o) => o === check?.outcome);
+                return JSON.stringify({ verified: outcome === 'reached', outcome: outcome ?? 'unverified', pull: { number: pull.number, headSha: pull.headSha } });
+            }
+            // 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. 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.
+            const asked = p;
+            const host = /^(netlify|vercel)-(setup|team)$/.exec(asked.id);
+            if (host?.[2] === 'setup')
+                return JSON.stringify(await hostSignIn(host[1], pi, signal));
+            if (host && (teamChoices.get(host[1])?.length ?? 0) < 2)
+                return `Invalid input: ${asked.id} is asked only when the ${HOST_NAMES[host[1]]} sign-in answered teams to choose from.`;
+            const fixed = Object.hasOwn(HOST_QUESTIONS, asked.id) ? HOST_QUESTIONS[asked.id] : undefined;
+            // What the person reads in a fixed question's choice is what is recorded: an option's value is its label, whatever value the model gave it; a host's teams are the ones its sign-in offered, each read by its name and recorded by its slug.
+            const options = host ? teamChoices.get(host[1]) : asked.options?.map(({ label }) => ({ label, value: label }));
+            const q = { ...(fixed ? { id: asked.id, ...fixed, options } : asked), skippable: true };
+            const error = askError(q);
+            if (error)
+                return `Invalid input: ${error}.`;
+            const answer = await askPerson(q);
+            if (answer.skipped)
+                return JSON.stringify({ skipped: true });
+            if (q.kind === 'multi')
+                return JSON.stringify({ values: answer.values ?? [] });
+            if (q.kind === 'confirm') {
+                agreeToHostSetup(ctx.log, q.id);
+                return JSON.stringify({ confirmed: true });
+            }
+            if (q.kind === 'single')
+                chooseHostTeam(ctx.log, q.id, answer.value ?? '');
+            if (q.kind !== 'account' && !q.sensitive)
+                return JSON.stringify({ value: answer.value ?? '' });
+            // The model never holds what the person typed as a password: it gets a reference, which impeccable_write turns back.
+            const reference = `secret:${randomBytes(6).toString('hex')}`;
+            typed.set(reference, (q.kind === 'account' ? answer.password : answer.value) ?? '');
+            return JSON.stringify(q.kind === 'account' ? { username: answer.username ?? '', password: reference } : { value: reference });
+        }),
+        tool('impeccable_progress', 'Progress', 'Show the person where things stand, here and on the web page: the [STATUS] line and the whole task list. It refuses, saving nothing, a status line out of the playbook\'s voice, more than one task in progress, and a status line about another task than the one in progress.', PROGRESS, async (p) => {
+            const status = p.status.trim();
+            const tasks = withAttempts(p.tasks);
+            const voice = statusVoiceError(status) ?? stageError(status, p.tasks.filter((t) => !t.id.startsWith('preview-attempt-')));
+            if (voice)
+                return voice;
+            ctx.sync.update({ phase: 'running', status, tasks });
+            reportStatus(status);
+            reportTasks(tasks);
+            return 'Saved.';
+        }),
+        tool('impeccable_test_pr', 'Record the pull requests', 'Record the test drive as soon as it is open, so the web page follows its review, and again with setup_pr once the setup pull request is open. Each must be an open pull request from this repository\'s own impeccable/ branch; the setup pull request, once recorded, cannot change.', TEST_PR, async (p, _pi, signal) => {
+            const drive = { number: p.number, url: p.url.trim() };
+            const given = p.setup_pr;
+            const setup = given && { number: given.number, url: given.url.trim() };
+            if (setup?.number === drive.number)
+                return `Refused: #${drive.number} cannot be both the test drive and the setup pull request.`;
+            const found = await runPullRequest(ctx, drive, 'impeccable/test-drive', signal);
+            if ('problem' in found)
+                return `Refused: ${found.problem}.`;
+            let setupBranch = recordedBranches?.setup;
+            if (setup) {
+                // The setup pull request carries the preview attempts, so its binding cannot change.
+                const head = await runPullRequest(ctx, setup, 'impeccable/setup', signal);
+                if ('problem' in head)
+                    return `Refused: ${head.problem}.`;
+                const bound = bindPreviewPullRequest(retry, { ...setup, branch: head.branch });
+                if (bound.verdict !== 'allow')
+                    return `Refused: ${bound.reason}.`;
+                setupBranch = head.branch;
+            }
+            ctx.sync.update({ test_pr: drive, ...(setup ? { setup_pr: setup } : {}) });
+            recordedBranches = { drive: found.branch, setup: setupBranch };
+            const res = await ctx.sync.flush();
+            const what = `the test drive #${drive.number}${setup ? ` and the setup pull request #${setup.number}` : ''}`;
+            return res?.ok
+                ? `Recorded ${what}. The web page follows the test drive's review from now on.`
+                : `Recorded ${what} here, but the web page did not take it yet (${res?.error ?? 'no answer'}). The report links them too.`;
+        }),
+        tool('impeccable_report', 'Report', 'Finish the run: save the report, which the web page shows, and what is left for the person; the terminal then shows the outcome and the command exits.', REPORT, async (p, pi, signal) => {
+            const left = (p.left ?? []).map((line) => line.trim());
+            const long = left.find((line) => line.length > STATUS_MAX);
+            if (long)
+                return `Refused: "${long}" is longer than ${STATUS_MAX} characters. Each line of "left" is one short line the person can act on; the detail belongs in the report. Nothing was saved: call impeccable_report again.`;
+            // The web page keeps the task list as the report leaves it, so no task may still read as waiting or running (#83).
+            const open = ctx.sync.payload.tasks.filter((t) => !t.id.startsWith('preview-attempt-') && (t.status === 'pending' || t.status === 'in_progress'));
+            if (open.length)
+                return `Refused: the task list still shows ${open.map((t) => `"${t.title}" as ${t.status.replace('_', ' ')}`).join(', ')}. Call impeccable_progress with every task's final status (completed, skipped or failed), then impeccable_report again. Nothing was saved.`;
+            let markdown = p.markdown;
+            if (previews.active && retry.pr) {
+                await observe(signal);
+                const lines = attempts().map((a, i) => `${i + 1}. [Attempt ${i + 1}](${a.url}) (run attempt ${a.attempt}): ${a.status}. ${a.diagnostics.map((d) => `${d.appKey}: step ${d.stage ?? 'unverified'}. ${d.reason}`).join(' ')}${a.changes.length ? ` Changed settings: ${a.changes.join(', ')}.` : ''}`);
+                markdown += `\n\n## Preview attempts\n\n${lines.length ? lines.join('\n') : 'No workflow attempt could be verified.'}\n\n${retry.pushReservations} push reservation(s); at least ${retry.used} reserved or observed attempt(s). Failed or uncertain pushes retain their reservation.`;
+                // The run never waits for the review, so it cannot vouch for the current head's.
+                markdown += "\nThe current head's review was not verified.";
+                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 } = ctx.sync.payload;
+            // A test drive branched before the setup branch was corrected ran on the old head: it shows nothing about this one.
+            const covered = test_pr && recordedBranches?.setup
+                ? await (ctx.driveCoversSetup ?? driveCoversSetup)(pi.cwd, recordedBranches.setup, recordedBranches.drive) : null;
+            const drive = covered === false ? undefined : test_pr;
+            ctx.sync.update({ phase: 'completed', status: 'Setup finished', question: null, report_markdown: markdown, test_pr: drive });
+            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 });
+                return `Error: the report was refused (${res.status}: ${res.error}). Fix what it says and call impeccable_report again.`;
+            }
+            // Otherwise final: a completed write whose answer was lost may still have landed, so it is never taken back.
+            ctx.onReport({ markdown, left, testPr: drive, setupPr: ctx.sync.payload.setup_pr, ...(savedHost ? { hostedBy: savedHost } : {}) });
+            pi.shutdown();
+            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, whether Vercel made it and the pull requests whose commit it built. An error says nothing either way. 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 (a project\'s first deployment is called Production, whatever branch it builds, and counts). It changes nothing on the host and proves nothing about the page.', HOSTED_PREVIEWS, async (p, _pi, signal) => {
+            const branch = p.branch;
+            const read = () => (ctx.hostedPreviewReader ?? readHostedPreviews)(ctx.owner, ctx.repo, { signal, branch });
+            // With `branch` the evidence holds only the deployments of its head, and Vercel's is its preview 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 preview = (d) => (branch !== undefined ? d.vercel : /preview/i.test(d.environment ?? ''));
+            // A head's preview is still building until it has a final status.
+            const final = (evidence) => Boolean(evidence.error) || evidence.deployments.some((d) => preview(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();
+            listedPreviews.clear();
+            vercelMade.clear();
+            for (const d of evidence.deployments) {
+                if (d.state === 'success' && d.url && preview(d) && (d.pullRequests.length || branch !== undefined)) {
+                    const { origin } = new URL(d.url);
+                    listedPreviews.add(origin);
+                    if (d.vercel)
+                        vercelMade.add(origin);
+                }
+            }
+            return JSON.stringify(evidence);
+        }),
+        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, or the Netlify CLI on this machine when it is signed in (read only: it never signs in). 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. It changes nothing on Netlify and proves nothing about the page.", NETLIFY_PREVIEWS, async (p, pi, signal) => {
+            const pull = p.pull;
+            const read = () => (ctx.netlifyPreviewReader ?? readNetlifyPreviews)(ctx.owner, ctx.repo, pi.cwd, { signal, pull });
+            // 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();
+            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_prove_preview', 'Check a hosted preview', 'Open a preview address impeccable_hosted_previews or impeccable_netlify_previews listed for a pull request or a pushed branch (a successful Preview deployment, or a deploy preview that is ready), or a page on it, as a visitor signed in nowhere, and prove it: it answers, and the page shows words a file of this checkout holds. proven true lets impeccable_write save intendedMethod "preview-deploy"; for Netlify it answers the address pattern to save beside it. gate "vercel-protection" or "netlify-protection" means the host\'s protection stands in front of it. Nothing of the page comes back.', PROVE_PREVIEW, async (p, pi, signal) => {
+            const url = p.url;
+            if (!URL.canParse(url) || !(listedPreviews.has(new URL(url).origin) || netlifyListed.has(new URL(url).origin)))
+                return 'Refused: open the address of a preview that impeccable_hosted_previews or impeccable_netlify_previews listed for a pull request or a pushed branch, or a page on it.';
+            const proof = await provePreview(url, p.expect, pi.cwd, { fetch: ctx.previewFetch, signal, ...(bypassSecret && bypassOrigins.has(new URL(url).origin) ? { bypass: bypassSecret } : {}) });
+            hostedPreviewProven ||= proof.proven;
+            if (proof.proven)
+                provenHost = previewHostName(url) ?? provenHost;
+            if (proof.proven && proof.pattern)
+                provenPattern = proof.pattern;
+            if (proof.gate === 'vercel-protection')
+                gated = { url, expect: p.expect };
+            return JSON.stringify(proof);
+        }),
+        tool('impeccable_netlify_connect', 'Connect the repository to Netlify', "Connect the Netlify site this folder is linked to with this repository, through the site's settings and Netlify's GitHub app, so that pull requests build deploy previews. The run does it; when Netlify's app cannot read the repository, this asks the person once for its access on GitHub and waits. connected true means Netlify read the repository; how \"already\" means the site was built from it before. A connection left undone answers why, and the GitHub page for the person in access.", NETLIFY_CONNECT, async (p, pi, signal) => {
+            const command = p.command;
+            const publish = p.publish;
+            if (command !== undefined && (command.length > 200 || /[\r\n\0]/.test(command)))
+                return 'Refused: the build command is one line of at most 200 characters.';
+            if (publish !== undefined && publish !== '.' && !staticRelativePath(publish))
+                return 'Refused: publish is a folder relative to the checkout, such as "dist".';
+            return JSON.stringify(await netlifyConnect(pi, { command, publish }, 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. 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. connected true means the repository is connected, or was already. A connection left undone answers why, and the GitHub page for the person in access.", NO_INPUT, async (_p, pi, signal) => JSON.stringify(await vercelConnect(pi, signal))),
+        tool('impeccable_vercel_bypass', "Vercel's login", 'Get past the Vercel login that impeccable_prove_preview met (gate "vercel-protection") in front of a preview Vercel made, the way Vercel documents for tools: a bypass secret of the Vercel project, sent to it in a header. It does the rest with the Vercel CLI signed in as the person: it finds the project\'s secret labelled "Impeccable reviews", or shows one screen asking to create one, or, when the CLI cannot, one screen taking a pasted one; opens the preview with it; and saves it for reviews. Answers {"status": …}: saved (the preview is proven, so the method may be saved; secret says whether it was created, existing or typed, and project which Vercel project holds it), skipped (the person skipped the screen; reason says what came before), refused (no secret opened 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 secret ever comes back.', NO_INPUT, async (_p, pi, signal) => {
+            if (!gated || !vercelMade.has(new URL(gated.url).origin))
+                return 'Refused: this is for a preview that Vercel made, listed by impeccable_hosted_previews, which impeccable_prove_preview answered with gate "vercel-protection". Prove one first.';
+            if (bypassOutcome?.status === 'skipped')
+                return JSON.stringify(bypassOutcome);
+            const at = gated;
+            const origin = new URL(at.url).origin;
+            // A secret in hand already: an address of the same project opens with it, and no other project's does.
+            if (bypassSaved && bypassSecret && (await provePreview(at.url, at.expect, pi.cwd, { fetch: ctx.previewFetch, signal, bypass: bypassSecret })).proven) {
+                bypassOrigins.add(origin);
+                return JSON.stringify(bypassSaved);
+            }
+            /** The store took this attempt's secret: what was in hand no longer matches it, unless the setting followed. */
+            let stored = false;
+            const { value, ...told } = await passVercelLogin({
+                run: (ctx.hostRunner ?? commandRunner)('vercel', pi.cwd, { signal }),
+                link: () => readLink(pi.cwd),
+                consent: async () => !(await ask(HOST_SCREENS['vercel-bypass'])).skipped,
+                paste: async () => {
+                    const answer = await ask(HOST_SCREENS['vercel-bypass-key']);
+                    return answer.skipped ? undefined : answer.value?.trim();
+                },
+                prove: (secret) => provePreview(at.url, at.expect, pi.cwd, { fetch: ctx.previewFetch, signal, bypass: secret }),
+                save: async (secret) => {
+                    const base = `${ctx.setupApi}/repos/${encodeURIComponent(ctx.repo)}`;
+                    if (!(await call(pi, `${base}/preview-auth/protection-header`, { method: 'PUT', body: { value: secret } })).ok)
+                        return 'The setup API did not store the secret.';
+                    stored = true;
+                    if (!(await call(pi, `${base}/preview-protection`, { method: 'PUT', body: { method: 'header', headerName: BYPASS_HEADER } })).ok)
+                        return 'The setup API stored the secret, but not the setting that sends it: it is turned on under Deployment protection on the setup page.';
+                    return null;
+                },
+                remember: noteSensitiveAnswer,
+            });
+            bypassOutcome = { ...told, ...(told.status === 'saved' ? { proven: true } : {}) };
+            if (value) {
+                // What is in hand follows the store: a new secret is the one saved now, and the origins the last one opened no longer stand.
+                bypassSecret = value;
+                bypassOrigins.clear();
+                bypassOrigins.add(origin);
+                hostedPreviewProven = true;
+                provenHost = 'Vercel';
+                bypassSaved = bypassOutcome;
+            }
+            else if (told.status === 'save-failed' && stored) {
+                // The store holds the secret this attempt wrote without the setting that sends it: nothing in hand stands until a save goes through. A store the attempt never changed keeps the earlier one good.
+                bypassSecret = undefined;
+                bypassOrigins.clear();
+                bypassSaved = undefined;
+            }
+            return JSON.stringify(bypassOutcome);
+        }),
+    ];
+}