@impeccable/reviews 0.1.0

package/dist/login.js

@@ -0,0 +1,276 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { requestJson } from './http.js';
+import { UserError } from './log.js';
+import { askPerson } from './ui/bridge.js';
+/** The callback ports, in the order the contract lists them; the Worker accepts no other. */
+export const CALLBACK_PORTS = [8239, 8238, 8240, 8237, 8236, 8235];
+const LOGIN_TIMEOUT_MS = 30 * 60_000;
+export function challengeFor(verifier) {
+    return createHash('sha256').update(verifier).digest('base64url');
+}
+export function pkcePair() {
+    const verifier = randomBytes(32).toString('base64url');
+    return { verifier, challenge: challengeFor(verifier) };
+}
+/** The web page that mirrors the run: the token's `page` when it is on `host`, else the one for the repository on `host`. */
+export function progressPage(host, t) {
+    if (typeof t.page === 'string' && URL.canParse(t.page) && new URL(t.page).origin === host)
+        return t.page;
+    return `${host}/app/${encodeURIComponent(t.repository.workspace || t.repository.owner)}/onboard?repo=${encodeURIComponent(t.repository.name)}`;
+}
+/** How long the server keeps answering a tab once it has somewhere to go: long enough for its next look, or a click on its link. */
+const LANDED_MS = 60_000;
+/** How long an exiting command waits for its waiting tabs to hear where to go. */
+const HEAR_MS = 2000;
+/** The waiting tabs that have not heard where to go yet, each settling once it has, or once its server stops. */
+const untold = new Set();
+/** Gives the tabs waiting on a sign-in a moment to hear where to go, since the command exiting takes their answer with it. */
+export async function letTabsHear() {
+    await Promise.race([Promise.all(untold), new Promise((r) => setTimeout(r, HEAR_MS))]);
+}
+const escapeHtml = (text) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+function page(res, status, message, more = '') {
+    const body = `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Impeccable for PRs</title>
+<style>body{font:17px/1.5 system-ui,sans-serif;margin:0;min-height:100vh;display:grid;place-items:center;color:#1a1a1a;background:#fafafa}a{color:inherit}@media (prefers-color-scheme:dark){body{color:#eee;background:#161616}}</style>
+<main><p id="said" role="status" aria-live="polite">${escapeHtml(message)}</p>${more}</main></html>`;
+    res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', connection: 'close' }).end(body);
+}
+/**
+ * The page the tab shows once the code has come: it asks the command every
+ * half second where to go next, and goes there (the progress page), or says
+ * what went wrong; without scripts, a link does the asking.
+ */
+function waitingPage(res, state) {
+    const script = `<script>(function(){var said=document.getElementById('said'),next='/next?state='+encodeURIComponent(new URLSearchParams(location.search).get('state')||'');function ask(){fetch(next,{cache:'no-store'}).then(function(r){return r.json()}).then(function(a){if(a.page&&/^https?:/.test(a.page))location.replace(a.page);else if(a.error)said.textContent=a.error;else setTimeout(ask,500)},function(){said.textContent='Back to your terminal.'})}ask()})()</script>`;
+    page(res, 200, 'Signed in. One moment…', `<noscript><p><a href="/go?state=${escapeHtml(encodeURIComponent(state))}">Go on to the progress page</a></p></noscript>${script}`);
+}
+/**
+ * Listens on the first free port of `ports` for `/callback?code=&state=`. A
+ * wrong state gets a 400 and the wait goes on; the right one hands over the
+ * code and answers at once with a page that asks `/next` where to go, which
+ * says "not yet" until `land` knows (a JSON `wait`), then the page or what
+ * went wrong. `/go` is the same for a tab without scripts: a redirect, or
+ * the waiting page again.
+ */
+export async function startCallbackServer(state, ports = CALLBACK_PORTS) {
+    let resolve;
+    let reject;
+    const code = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    /** A tab brought the code, and waits to hear where to go. */
+    let visited = false;
+    let landing;
+    let heard = () => { };
+    const told = new Promise((r) => (heard = r)).finally(() => untold.delete(told));
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const route = req.method === 'GET' ? url.pathname : '';
+        if (!['/callback', '/next', '/go'].includes(route))
+            return void res.writeHead(404, { connection: 'close' }).end();
+        if (url.searchParams.get('state') !== state)
+            return page(res, 400, 'This sign-in is not the one your terminal started. Run impeccable-reviews again.');
+        // Heard once the answer that says where to go has left for the tab.
+        if (route !== '/callback' && landing)
+            res.once('finish', heard);
+        if (route === '/next')
+            return void res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store', connection: 'close' }).end(JSON.stringify(landing ?? { wait: true }));
+        if (route === '/go') {
+            if (landing && 'page' in landing)
+                return void res.writeHead(302, { location: landing.page, 'cache-control': 'no-store', connection: 'close' }).end();
+            return landing ? page(res, 400, landing.error) : waitingPage(res, state);
+        }
+        const got = url.searchParams.get('code');
+        const error = url.searchParams.get('error');
+        if (!got || error) {
+            page(res, 400, 'Sign-in did not finish. Back to your terminal.');
+            return reject(new UserError(`Sign-in did not finish${error ? ` (${error})` : ''}. Run impeccable-reviews again.`));
+        }
+        if (!visited)
+            untold.add(told);
+        visited = true;
+        resolve(got);
+        waitingPage(res, state);
+    });
+    const shut = () => {
+        heard();
+        server.close();
+        server.closeIdleConnections();
+    };
+    let closing = false;
+    const shutLater = () => void setTimeout(shut, LANDED_MS).unref();
+    for (const port of ports) {
+        const listening = await new Promise((done, fail) => {
+            const onError = (err) => (err.code === 'EADDRINUSE' || err.code === 'EACCES' ? done(false) : fail(err));
+            server.once('error', onError);
+            server.listen(port, '127.0.0.1', () => {
+                server.off('error', onError);
+                done(true);
+            });
+        });
+        if (!listening)
+            continue;
+        const actual = server.address().port;
+        return {
+            redirectUri: `http://localhost:${actual}/callback`,
+            code,
+            land: (next) => void next.then((url) => void (landing ??= { page: url }), (err) => void (landing ??= { error: err instanceof UserError ? err.message : 'Sign-in did not finish. Back to your terminal.' })).then(() => closing && shutLater()),
+            close: () => {
+                // The tab asks again every half second; it is never a reason for the command to stay.
+                server.unref();
+                if (!visited)
+                    return shut();
+                // It stops a while after the tab has somewhere to go, however long that takes to know.
+                closing = true;
+                if (landing)
+                    shutLater();
+            },
+        };
+    }
+    throw new UserError(`Ports ${ports.join(', ')} are all taken on this machine, and sign-in needs one. Close what uses one of them and run it again.`);
+}
+/** The code from what the person pasted: the whole callback address, or the code alone. Null when it is neither, or from another sign-in. */
+export function parsePasted(text, state) {
+    const trimmed = text.trim();
+    if (trimmed.includes('code=')) {
+        let url;
+        try {
+            url = new URL(trimmed.includes('://') ? trimmed : `http://localhost/?${trimmed.split('?').pop()}`);
+        }
+        catch {
+            return null;
+        }
+        const pastedState = url.searchParams.get('state');
+        if (pastedState !== null && pastedState !== state)
+            return null;
+        return url.searchParams.get('code') || null;
+    }
+    return /^[A-Za-z0-9._~-]{8,}$/.test(trimmed) ? trimmed : null;
+}
+/** Opens the address in the default browser; a failure is fine because the address is printed too. BROWSER=none skips it. */
+export function openBrowser(url) {
+    if (process.env.BROWSER === 'none')
+        return;
+    const [command, args, verbatim] = process.platform === 'darwin' ? ['open', [url], false]
+        : process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', `"${url}"`], true]
+            : ['xdg-open', [url], false];
+    try {
+        const child = spawn(command, args, { stdio: 'ignore', detached: true, windowsVerbatimArguments: verbatim });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        // The address is on screen.
+    }
+}
+/** Puts text on the clipboard with the platform's own command, and says whether it got there; a failure is fine because the text is on screen. */
+export function copyText(text) {
+    const [command, args] = process.platform === 'darwin' ? ['pbcopy', []] : process.platform === 'win32' ? ['clip', []] : ['xclip', ['-selection', 'clipboard']];
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(command, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+            child.on('error', () => resolve(false));
+            child.on('close', (code) => resolve(code === 0));
+            child.stdin.on('error', () => { });
+            child.stdin.end(text);
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+/** On the UI's sign-in screen instead of printed lines: the pasted code comes through a question in its place. */
+export function screenPrompt(showSignIn) {
+    let link = '';
+    return {
+        show: (url) => void (link = url),
+        listen(state, onCode, onCancel) {
+            const screen = showSignIn(link, {
+                onCancel,
+                onCopy: () => copyText(link),
+                async onPaste() {
+                    const pasted = await askPerson({ id: 'sign-in-code', title: 'Sign-in code', prompt: 'Paste the code, or the whole address the browser ended on.', kind: 'text', skippable: true });
+                    const code = pasted.skipped ? null : parsePasted(pasted.value ?? '', state);
+                    if (code)
+                        onCode(code);
+                    return code;
+                },
+            });
+            return () => screen.close();
+        },
+    };
+}
+export async function exchangeCode(host, input, log) {
+    const res = await requestJson(`${host}/app/cli/token`, { method: 'POST', body: { code: input.code, code_verifier: input.verifier, redirect_uri: input.redirectUri } }, log);
+    if (!res.ok)
+        throw new UserError(`Sign-in failed: ${res.error}. Run impeccable-reviews again.`);
+    const t = res.data;
+    if (!t || typeof t.access_token !== 'string' || !t.repository || typeof t.repository.name !== 'string' || typeof t.setup_api !== 'string' || typeof t.cli_api !== 'string') {
+        throw new UserError('Sign-in answered with something this version does not understand. Update impeccable-reviews and run it again.');
+    }
+    return t;
+}
+/**
+ * The browser sign-in: callback server, PKCE and state, the paste fallback,
+ * then the token exchange, once per code. `check` stops a token the command
+ * cannot use; otherwise the tab that brought the code goes on to the page
+ * `landing` resolves to (the web page that mirrors the run, once the command
+ * has what it needs to show a run there), or says why it will not.
+ */
+export async function signIn(host, log, prompt, check = (t) => t, landing = async (t) => progressPage(host, t)) {
+    const state = randomBytes(24).toString('base64url');
+    const { verifier, challenge } = pkcePair();
+    log.secret(verifier);
+    const server = await startCallbackServer(state);
+    const authorize = new URL(`${host}/app/cli/authorize`);
+    authorize.search = new URLSearchParams({ redirect_uri: server.redirectUri, state, code_challenge: challenge, code_challenge_method: 'S256' }).toString();
+    log.write(`callback server at ${server.redirectUri}`);
+    prompt.show(authorize.href);
+    openBrowser(authorize.href);
+    let stopPaste = () => { };
+    let timer;
+    try {
+        const code = await new Promise((resolve, reject) => {
+            server.code.then(resolve, reject);
+            stopPaste = prompt.listen(state, resolve, () => reject(new UserError('Sign-in cancelled.')));
+            timer = setTimeout(() => reject(new UserError('Sign-in timed out after 30 minutes. Run impeccable-reviews again.')), LOGIN_TIMEOUT_MS);
+        });
+        log.secret(code);
+        const token = check(await exchangeCode(host, { code, verifier, redirectUri: server.redirectUri }, log));
+        server.land(landing(token));
+        return token;
+    }
+    catch (err) {
+        server.land(Promise.reject(err));
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+        stopPaste();
+        server.close();
+    }
+}
+/**
+ * The setup token lasts an hour and cannot be extended, so a run that outlives
+ * it signs the person in again, once for all the tools that need it.
+ */
+export function setupAuth(first, signInAgain, now = Date.now) {
+    const until = (t) => now() + (Number.isFinite(t.expires_in) ? t.expires_in : 3600) * 1000;
+    let current = { token: first.access_token, expiresAt: until(first) };
+    let pending;
+    const renew = (pi) => (pending ??= signInAgain(pi)
+        .then((t) => {
+        current = { token: t.access_token, expiresAt: until(t) };
+        return t.access_token;
+    })
+        .finally(() => {
+        pending = undefined;
+    }));
+    return {
+        token: (pi) => (now() < current.expiresAt - 60_000 ? Promise.resolve(current.token) : renew(pi)),
+        renew,
+    };
+}

package/dist/main.js

@@ -0,0 +1,252 @@
+import { execFile } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { runAgent } from './agent.js';
+import { fenceExtension } from './fence.js';
+import { focusInstructions, focusState } from './focus.js';
+import { requestJson } from './http.js';
+import { copyText, letTabsHear, openBrowser, progressPage, screenPrompt, setupAuth, signIn } from './login.js';
+import { createLog, UserError } from './log.js';
+import { firstMessage, playbook, setupContext } from './playbook.js';
+import { checkoutFrontEnd, parseFlags, readCheckout, stateSaysNoFrontEnd, USAGE } from './preflight.js';
+import { createSessionSync, syncExtension } from './sync.js';
+import { createTools, resultLine } from './tools.js';
+import { atExit, closeScreens, helpMark, recordFrames, showIntro, showOutro, showPullRequest, showRun, showSignIn } from './ui/screens.js';
+const say = (line = '') => console.log(line);
+const execFileAsync = promisify(execFile);
+/** How a run on a repository with no web front end ends, here and on the web page. */
+export const NO_FRONT_END = 'Impeccable reviews web front ends, and this repository does not have one. Nothing was set up.';
+/** How a run on a repository Impeccable skipped ends when this checkout has a web front end: the setup state lists it with nothing to set up until the person adds it. */
+const SKIPPED = 'Impeccable skipped this repository because its scan found no web front end, but this checkout has one. Choose Add anyway on the setup page, then run this again.';
+/** A pull request of owner/repo as gh sees it: its branch, its state and whether it is still a draft, or why gh could not say. */
+async function viewPullRequest(slug, number) {
+    try {
+        const { stdout } = await execFileAsync('gh', ['pr', 'view', String(number), '--repo', slug, '--json', 'headRefName,state,isDraft'], { timeout: 30_000 });
+        const pr = JSON.parse(stdout);
+        return typeof pr.headRefName === 'string' && typeof pr.state === 'string' ? { headRefName: pr.headRefName, state: pr.state, isDraft: pr.isDraft === true } : { error: 'gh answered something else' };
+    }
+    catch (err) {
+        const { stderr, message } = err;
+        return { error: (stderr || message || 'gh failed').trim().split('\n')[0] };
+    }
+}
+const settle = (p, ms) => Promise.race([p, new Promise((r) => setTimeout(() => r(undefined), ms).unref())]);
+/** How long a host's build of a pushed branch or a pull request is waited for: the tools' five minutes, unless IMPECCABLE_PREVIEW_WAIT_MS shortens it, which the smoke does, its fake host never building. */
+function previewWait() {
+    const totalMs = Number(process.env.IMPECCABLE_PREVIEW_WAIT_MS);
+    return Number.isFinite(totalMs) && totalMs > 0 ? { totalMs, everyMs: Math.min(15_000, Math.max(50, Math.floor(totalMs / 5))) } : undefined;
+}
+/** The end of a run with nothing to set up, before the agent: the web page says why too, and the command exits 2. */
+async function nothingToSetUp(sync, title, result, links) {
+    sync.update({ phase: 'error', status: result, question: null });
+    const saved = await settle(sync.flush(), 5000);
+    await showOutro({
+        outcome: 'stopped',
+        title,
+        result,
+        links,
+        todo: [],
+        warnings: saved?.ok ? [] : [`The web page missed this (${saved?.error ?? 'no answer'}), so it may still show the run as going.`],
+    });
+    await letTabsHear();
+    process.exit(2);
+}
+export async function main(argv) {
+    let log = createLog(false);
+    let sync;
+    // The tab the person approved in goes on to the web page once the run is minted, so the page has a run to show; a stop before then is what it says instead.
+    let land = () => { };
+    const landing = new Promise((resolve, reject) => (land = (outcome) => (typeof outcome === 'string' ? resolve(outcome) : reject(outcome))));
+    landing.catch(() => { });
+    try {
+        const flags = parseFlags(argv);
+        if (flags.help)
+            return say(`${helpMark().join('\n').trimEnd()}\n\n${USAGE}`);
+        log = createLog(flags.debug);
+        // Printed as the command exits, after the screen has gone, so it stays in the scrollback.
+        if (log.path)
+            atExit(() => [`Debug log: ${log.path}`]);
+        log.write('start', { host: flags.host, model: flags.model, effort: flags.effort, yes: flags.yes, node: process.versions.node });
+        if (flags.frames)
+            recordFrames(flags.frames);
+        const checkout = readCheckout(process.cwd());
+        const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+        const slug = `${checkout.owner}/${checkout.repo}`;
+        if (!(await showIntro()))
+            return;
+        const onHost = (url) => URL.canParse(url) && new URL(url).origin === flags.host;
+        /** The sign-in's answer, when it is for this checkout and points at --host only. */
+        const accept = (t) => {
+            log.secret(t.access_token);
+            const approved = `${t.repository.owner}/${t.repository.name}`;
+            if (approved.toLowerCase() !== slug.toLowerCase()) {
+                throw new UserError(`You approved ${approved}, but this checkout is ${slug}. Run it again and pick ${slug} on the consent page.`);
+            }
+            if (!onHost(t.setup_api) || !onHost(t.cli_api)) {
+                throw new UserError(`Impeccable answered with addresses off ${flags.host}, so the command stopped before sending anything there.`);
+            }
+            return t;
+        };
+        const token = await signIn(flags.host, log, screenPrompt(showSignIn), accept, () => landing);
+        const setupApi = token.setup_api.replace(/\/$/, '');
+        const cliApi = token.cli_api.replace(/\/$/, '');
+        const page = progressPage(flags.host, token);
+        // The run screen opens at once, with its placeholder, while the run starts. Stopping before the agent takes over
+        // stops the command, and a run already started shows as stopped on the web page.
+        let stopping = false;
+        const stopEarly = async () => {
+            if (stopping)
+                return;
+            stopping = true;
+            const why = 'Impeccable stopped before the setup started.';
+            if (sync) {
+                sync.update({ phase: 'error', status: why, question: null });
+                await settle(sync.flush(), 5000);
+            }
+            land(new UserError(why));
+            await closeScreens();
+            console.error(why);
+            await letTabsHear();
+            process.exit(130);
+        };
+        showRun({ onCancel: () => void stopEarly() });
+        const started = await requestJson(`${cliApi}/run`, { method: 'POST', token: token.access_token, body: {} }, log);
+        const run = started.data;
+        if (!started.ok)
+            throw new UserError(`Impeccable could not start a run: ${started.error}.`);
+        if (!run || typeof run.run_id !== 'string' || typeof run.run_token !== 'string' || typeof run.gateway_url !== 'string' || typeof run.model !== 'string') {
+            throw new UserError('Impeccable started a run this version does not understand. Update impeccable-reviews and run it again.');
+        }
+        log.secret(run.run_token);
+        if (!onHost(run.gateway_url))
+            throw new UserError(`Impeccable answered with a model gateway off ${flags.host}, so the command stopped before sending anything there.`);
+        land(page);
+        const runToken = run.run_token;
+        const sessionUrl = `${cliApi}/sessions/${encodeURIComponent(run.run_id)}`;
+        const liveSync = createSessionSync((payload) => requestJson(sessionUrl, { method: 'PUT', token: runToken, body: payload }, log));
+        sync = liveSync;
+        log.write('run started', { run_id: run.run_id, cap_usd: run.cap_usd, expires_at: run.expires_at });
+        // Impeccable reviews web front ends: a checkout without one stops here, before the state is read or anything runs.
+        const frontEnd = checkoutFrontEnd(checkout.root);
+        log.write('front end', frontEnd);
+        const webPage = { label: 'Web page', url: page };
+        if (frontEnd === 'none')
+            await nothingToSetUp(liveSync, 'No web front end', NO_FRONT_END, [webPage]);
+        const [instructions, state] = await Promise.all([
+            requestJson(`${setupApi}/instructions`, { token: token.access_token }, log),
+            requestJson(`${setupApi}/state`, { token: token.access_token }, log),
+        ]);
+        if (!instructions.ok || !state.ok)
+            throw new UserError(`Impeccable's setup API did not answer: ${instructions.error ?? state.error}.`);
+        // When the checkout cannot tell, the setup state's own verdict decides. When it has a web front end Impeccable skipped, the person adds it first.
+        if (stateSaysNoFrontEnd(state.data, token.repository.name)) {
+            if (frontEnd === 'unknown')
+                await nothingToSetUp(liveSync, 'No web front end', NO_FRONT_END, [webPage]);
+            const setupPage = state.data.account?.setupPage;
+            await nothingToSetUp(liveSync, 'Repository skipped', SKIPPED, [...(typeof setupPage === 'string' && onHost(setupPage) ? [{ label: 'Setup page', url: setupPage }] : []), webPage]);
+        }
+        if (!interactive)
+            say('Signed in.\n');
+        // Scratch output (a server's log, a build's output) goes here and never into the checkout.
+        const scratch = mkdtempSync(join(tmpdir(), 'impeccable-reviews-scratch-'));
+        process.on('exit', () => rmSync(scratch, { recursive: true, force: true }));
+        // The model reads the instructions and the state trimmed to this setup, and writes only what it read.
+        const focused = focusInstructions(instructions.data);
+        let report;
+        let fatal;
+        let cancelled = false;
+        const finish = async () => {
+            if (report) {
+                const saved = await settle(liveSync.flush(), 5000);
+                const { testPr, setupPr } = report;
+                // One pull request a screen, each opened in the browser and put on the clipboard as its screen appears: the test drive, then the setup pull request.
+                const hand = { open: openBrowser, copy: copyText };
+                if (testPr && setupPr)
+                    await showPullRequest(testPr.url, hand);
+                await showOutro({
+                    outcome: testPr ? 'done' : 'partial',
+                    title: testPr ? "You're all set up" : 'Settings saved',
+                    result: resultLine(report),
+                    link: (setupPr ?? testPr)?.url,
+                    links: [
+                        ...(testPr ? [{ label: 'Test drive, watch the review there', url: testPr.url }] : []),
+                        // Without a current test drive the setup pull request is not ready to merge; the report says why.
+                        ...(setupPr ? [{ label: testPr ? 'Setup pull request, merge this' : 'Setup pull request', url: setupPr.url }] : []),
+                        { label: 'Web page', url: page },
+                    ],
+                    todo: report.left,
+                    warnings: saved && !saved.ok ? [`The web page missed the last update (${saved.error}), so it may lag behind this.`] : [],
+                }, hand);
+                // The web page has the report; when it missed it, the report stays here instead.
+                if (!saved?.ok)
+                    say(`\n${report.markdown.trim()}`);
+                process.exit(0);
+            }
+            const waiting = liveSync.payload.phase === 'waiting' ? liveSync.payload.question?.prompt : undefined;
+            const why = fatal ? `Impeccable stopped: ${fatal}` : waiting ? `Impeccable stopped while waiting for an answer: ${waiting}` : 'Impeccable stopped before the setup finished.';
+            liveSync.update({ phase: 'error', status: why, question: null });
+            const saved = await settle(liveSync.flush(), 5000);
+            const missed = saved?.ok ? [] : [`The web page missed this (${saved?.error ?? 'no answer'}), so it may still show the run as going.`];
+            const { test_pr: drive, setup_pr: setup } = liveSync.payload;
+            await showOutro({
+                outcome: 'stopped',
+                title: cancelled && !fatal ? 'Setup cancelled' : 'Setup failed',
+                result: why,
+                links: [...(drive ? [{ label: 'Test drive', url: drive.url }] : []), ...(setup ? [{ label: 'Setup pull request', url: setup.url }] : []), { label: 'Web page', url: page }],
+                todo: ['Run impeccable-reviews again to carry on. What was saved stays saved; the web page has the details.'],
+                warnings: missed,
+            });
+            process.exit(1);
+        };
+        await runAgent({
+            cwd: checkout.root,
+            // The service hands out the model; --model overrides it.
+            model: flags.model ?? run.model,
+            effort: flags.effort,
+            gatewayUrl: run.gateway_url,
+            runToken,
+            systemPrompt: playbook({ owner: checkout.owner, name: token.repository.name, scratch }),
+            firstMessage: firstMessage({ owner: checkout.owner, name: token.repository.name }),
+            firstContext: setupContext(focused, focusState(state.data)),
+            tools: createTools({
+                setupApi,
+                auth: setupAuth(token, () => signIn(flags.host, log, screenPrompt(showSignIn), accept)),
+                owner: token.repository.owner,
+                repo: token.repository.name,
+                instructions: focused,
+                sync: liveSync,
+                viewPullRequest: (n) => viewPullRequest(`${token.repository.owner}/${token.repository.name}`, n),
+                onReport: (r) => void (report = r),
+                log,
+                previewWait: previewWait(),
+            }),
+            extensions: [
+                fenceExtension(checkout.root, log, checkout.protectedBranches, scratch),
+                syncExtension(liveSync, { onFatal: (message) => void (fatal = message), onQuit: finish }),
+            ],
+            interactive,
+            runId: run.run_id,
+            transcript: flags.transcript,
+            print: say,
+            log,
+            onCancel: () => void (cancelled = true),
+        });
+        // Without a terminal the run ends here; session_shutdown has already finished it.
+        await finish();
+    }
+    catch (err) {
+        const message = err instanceof UserError ? err.message : `Impeccable stopped: ${err instanceof Error ? err.message : String(err)}`;
+        land(new UserError(message));
+        log.write('fatal', err instanceof Error ? (err.stack ?? err.message) : String(err));
+        if (sync) {
+            sync.update({ phase: 'error', status: message, question: null });
+            await settle(sync.flush(), 5000);
+        }
+        await closeScreens();
+        console.error(message);
+        await letTabsHear();
+        process.exit(1);
+    }
+}