@reticlehq/server 2.12.0 → 2.13.1

package/dist/setup/run-setup.js

@@ -0,0 +1,203 @@
+/**
+ * The half of setup that happens after the files are written.
+ *
+ * `init` wires a project; this gets the app running with the SDK inside it, proves a session
+ * connected, and drives one flow to a verdict. Measured against an agent doing the same steps by
+ * hand from SKILL.md across five real applications: 176 model turns, $9.92, forty minutes, and a
+ * verdict in two runs out of five — three ended by asking a human to restart their client, having
+ * shown them nothing.
+ *
+ * Every effect is injected. That is not ceremony: the sequence has five phases, each with its own
+ * way of going wrong, and the alternative to injecting them is a test that boots a real dev server
+ * and a real browser to find out what happens when neither works.
+ */
+import { judgeWait, QUIET_MEANS_HUNG_MS, urlToWatch, WaitVerdict } from './dev-server-wait.js';
+/**
+ * Windows gets longer to say something before silence counts as a wedge.
+ *
+ * A first `npm run dev` on a cold Windows runner optimises dependencies before the bundler prints a
+ * line, and 45s of quiet is inside that window. Measured on the install gate: the Vue scaffold was
+ * declared hung, `init` exited 1, and the gate then started the very same app and connected to it
+ * on the next line. Nothing was wrong with the app; the wait was too impatient for the platform.
+ *
+ * Only the QUIET budget moves. The ceiling is unchanged, and a launcher that exits is still dead
+ * immediately, so this buys patience for a starting server and never for a broken one.
+ */
+const WINDOWS_QUIET_MEANS_HUNG_MS = 3 * 60_000;
+const WINDOWS_QUIET_MEANS_HUNG_MS_APPLIES = 'win32' === process.platform;
+import { pickSession } from './session-pick.js';
+import { readPage, describePage } from './page-probe.js';
+import { remainingSteps } from './remaining-steps.js';
+import { AppShape, isDesktop, policyFor } from './desktop-shape.js';
+/** Where a run got to, and why it stopped if it did. */
+export const SetupPhase = {
+    DEV_SERVER: 'dev-server',
+    CONNECT: 'connect',
+    DRIVE: 'drive',
+    DONE: 'done',
+};
+const asProgress = (input, o) => ({
+    initDone: true,
+    devServerUp: undefined !== o.url,
+    sessionConnected: undefined !== o.sessionId,
+    flowSaved: true === o.flowSaved,
+    urlSuppliedByCaller: undefined !== input.suppliedUrl,
+    ...(undefined === o.url ? {} : { url: o.url }),
+    ...(undefined === input.devCommand ? {} : { devCommand: input.devCommand }),
+});
+const stop = (input, phase, partial, notes) => ({
+    ok: false,
+    reachedPhase: phase,
+    flowSaved: false,
+    ...partial,
+    notes,
+    fallback: remainingSteps(asProgress(input, partial)),
+});
+/**
+ * Run the phases. Stops at the first one that cannot continue, and always says what is left.
+ *
+ * A phase that fails is not an error to throw: the caller is usually an agent, and a thrown
+ * exception loses the four things it needs — how far this got, the url, the session, and what to do
+ * about it.
+ */
+export async function runSetupPhases(input, fx) {
+    const notes = [];
+    const note = (line) => {
+        notes.push(line);
+        fx.note(line);
+    };
+    // ── the app has to be running ────────────────────────────────────────────────────────────────
+    let url = input.suppliedUrl;
+    if (undefined === url) {
+        if (undefined === input.devCommand) {
+            note(
+            // "stop here rather than invent one" is the SKILL.md rule, and the words are the contract —
+            // inventing a dev command is how a setup script runs the wrong thing and reports success.
+            'No dev command: the project names no dev, start or serve script, and there is no --url. ' +
+                'Stopping here rather than invent one — pass --dev-cmd or --url to say what serves this app.');
+            return stop(input, SetupPhase.DEV_SERVER, {}, notes);
+        }
+        await fx.startDevServer(input.devCommand, input.appDir);
+        const startedAt = fx.now();
+        for (;;) {
+            const watching = urlToWatch(fx.devServerOutput(), fx.observedPorts());
+            const serving = undefined === watching ? false : (await fx.probePage(watching)).served;
+            const verdict = judgeWait({
+                output: fx.devServerOutput(),
+                launcherExited: fx.devServerExited(),
+                serving,
+                quietForMs: fx.devServerQuietForMs(),
+                elapsedMs: fx.now() - startedAt,
+                quietMeansHungMs: WINDOWS_QUIET_MEANS_HUNG_MS_APPLIES
+                    ? WINDOWS_QUIET_MEANS_HUNG_MS
+                    : QUIET_MEANS_HUNG_MS,
+            });
+            if (WaitVerdict.READY === verdict && undefined !== watching) {
+                url = watching;
+                break;
+            }
+            // A desktop shell serves its webview from inside the app, so there is no port to answer and
+            // nothing to be READY. Once it has announced a url, or bound one we can see, that is as far
+            // as this phase can get: the session it dials from its own window is the real signal.
+            if (isDesktop(input.shape) && undefined !== watching) {
+                url = watching;
+                break;
+            }
+            if (WaitVerdict.DEAD === verdict) {
+                note('The dev server exited without serving anything.');
+                return stop(input, SetupPhase.DEV_SERVER, {}, notes);
+            }
+            if (WaitVerdict.HUNG === verdict) {
+                // Says BOTH were checked. A server that prints nothing but IS listening is the CRA case and
+                // must not be failed, so a reader has to be able to tell "we looked at the log" from "we
+                // looked at the log AND the ports".
+                note('The dev server neither printed a URL nor bound a port, so setup has nothing to open. ' +
+                    'Check its log, or pass --url with the address it serves.');
+                return stop(input, SetupPhase.DEV_SERVER, {}, notes);
+            }
+            await fx.sleep(input.pollMs);
+        }
+    }
+    // ── and something has to connect from inside it ──────────────────────────────────────────────
+    const policy = policyFor(input.shape);
+    // Through `note`, not `fx.note`: a caller reading the result should see it too.
+    if (undefined !== policy.note)
+        note(policy.note);
+    const before = new Set((await fx.listSessions()).map((s) => s.sessionId));
+    // Never for a desktop app: its own window is the client, and a browser tab would be a SECOND
+    // session that is not the app.
+    if (input.openBrowser && policy.openBrowser)
+        await fx.openBrowser(url);
+    const deadline = fx.now() + (input.connectBudgetMs ?? Math.max(input.phaseTimeoutMs, policy.connectBudgetMs));
+    let session = null;
+    for (;;) {
+        // On a desktop app, only the desktop window counts. AppShape and the runtime a page reports use
+        // the same three names, so the shape IS the requirement — see session-pick.
+        session = pickSession(await fx.listSessions(), url, before, isDesktop(input.shape) ? input.shape : undefined);
+        if (null !== session)
+            break;
+        if (deadline <= fx.now())
+            break;
+        await fx.sleep(input.pollMs);
+    }
+    if (null === session) {
+        if (isDesktop(input.shape)) {
+            // Nothing outside the app can fetch its webview, so there is no page to describe. What is
+            // wrong here is desktop-shaped: the preload, the capture helper, or a CSP that blocks the
+            // bridge — all of which `reticle doctor` checks.
+            note('The app never dialled in. For a desktop shell that is usually the preload not being required, ' +
+                'the capture helper not installed, or a CSP that blocks the bridge: run `npx @reticlehq/server doctor`.');
+        }
+        else {
+            // What the page contains is the one thing the daemon cannot know, so it is worth one fetch.
+            note(describePage(readPage(await fx.probePage(url)), url));
+        }
+        return stop(input, SetupPhase.CONNECT, { url }, notes);
+    }
+    // ── and it has to be driven, or nothing has been proved ──────────────────────────────────────
+    if (!input.drive) {
+        return {
+            ok: true,
+            reachedPhase: SetupPhase.CONNECT,
+            url,
+            sessionId: session.sessionId,
+            flowSaved: false,
+            notes,
+            fallback: [],
+        };
+    }
+    // Nothing to drive WITH is not the same as driving and proving nothing, and only the second is a
+    // failure of this command. The app is installed, instrumented, booted and connected; the one step
+    // left needs a tool this machine does not have, so it is reported and handed to the caller.
+    if (!fx.driverAvailable()) {
+        note('Installed and connected, but no agent CLI is on this machine (claude, codex, opencode, ' +
+            'cursor-agent or gemini), so nothing drove the app and no verdict was produced.');
+        return {
+            ok: true,
+            reachedPhase: SetupPhase.CONNECT,
+            url,
+            sessionId: session.sessionId,
+            flowSaved: false,
+            notes,
+            fallback: remainingSteps(asProgress(input, { url, sessionId: session.sessionId, flowSaved: false })),
+        };
+    }
+    const verdict = await fx.drive(url, session);
+    const flowSaved = fx.flowsSaved();
+    if (null === verdict) {
+        note('No agent CLI could drive the app, so nothing was proved.');
+    }
+    if (!flowSaved) {
+        return stop(input, SetupPhase.DRIVE, { url, sessionId: session.sessionId, ...(null === verdict ? {} : { verdict }) }, notes);
+    }
+    return {
+        ok: true,
+        reachedPhase: SetupPhase.DONE,
+        url,
+        sessionId: session.sessionId,
+        ...(null === verdict ? {} : { verdict }),
+        flowSaved: true,
+        notes,
+        fallback: [],
+    };
+}

package/dist/setup/session-pick.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Which connected session to drive, out of everything the daemon is holding.
+ *
+ * This is a false-green guard, which is why it is its own module. Two ways to get it wrong, and
+ * both report a successful install for an app that was never verified:
+ *
+ * - Match "any session" and you pass on somebody else's tab. A daemon usually holds several, and
+ *   one of them being alive says nothing about whether THIS app connected.
+ * - Match "the first session on this url" and you drive whichever the daemon listed first, usually
+ *   the oldest: a tab whose dev server died yesterday. The HUD then plays to a window nobody is
+ *   watching, and the verdict describes a page the user cannot see.
+ */
+/** The fields of a daemon session this decision actually reads. */
+export interface CandidateSession {
+    readonly sessionId: string;
+    readonly url?: string;
+    readonly hidden?: boolean;
+    readonly throttled?: boolean;
+    readonly lastSeenMs?: number;
+    /** False when the capabilities file init scaffolded was never completed. */
+    readonly hasCapabilities?: boolean;
+    /** Which shell answered. Absent on an SDK too old to report one — see requiredRuntime below. */
+    readonly runtime?: string;
+}
+/**
+ * The session to drive, or null when nothing on this url qualifies.
+ *
+ * Preference order, strongest evidence first:
+ *   1. NEW since we opened the tab — definitely this run's, definitely alive
+ *   2. visible and not throttled  — the tab a human is actually looking at
+ *   3. least stale               — the best of a bad set
+ *
+ * `before` is the set of session ids that already existed when this run started; anything outside
+ * it belongs to us.
+ */
+export declare function pickSession(sessions: readonly CandidateSession[], url: string, before?: ReadonlySet<string>, 
+/**
+ * The runtime this project's app RUNS as, when it is a desktop one.
+ *
+ * A desktop shell serves its renderer from an ordinary dev server, so its window and a browser tab
+ * open on the same origin are indistinguishable by url. Driving the tab passes every check here —
+ * live, on the url, SDK present — while having none of the app's IPC and none of its commands, so
+ * the verdict describes a different program that happens to share an address.
+ *
+ * Undefined for a web project, where the runtime is not a distinction worth making.
+ */
+requiredRuntime?: string): CandidateSession | null;

package/dist/setup/session-pick.js

@@ -0,0 +1,51 @@
+/**
+ * Which connected session to drive, out of everything the daemon is holding.
+ *
+ * This is a false-green guard, which is why it is its own module. Two ways to get it wrong, and
+ * both report a successful install for an app that was never verified:
+ *
+ * - Match "any session" and you pass on somebody else's tab. A daemon usually holds several, and
+ *   one of them being alive says nothing about whether THIS app connected.
+ * - Match "the first session on this url" and you drive whichever the daemon listed first, usually
+ *   the oldest: a tab whose dev server died yesterday. The HUD then plays to a window nobody is
+ *   watching, and the verdict describes a page the user cannot see.
+ */
+/** Sorts a hidden tab after a visible one; among equals, the least stale first. */
+const isLive = (s) => true !== s.hidden && true !== s.throttled;
+const staleness = (s) => s.lastSeenMs ?? Number.POSITIVE_INFINITY;
+/**
+ * The session to drive, or null when nothing on this url qualifies.
+ *
+ * Preference order, strongest evidence first:
+ *   1. NEW since we opened the tab — definitely this run's, definitely alive
+ *   2. visible and not throttled  — the tab a human is actually looking at
+ *   3. least stale               — the best of a bad set
+ *
+ * `before` is the set of session ids that already existed when this run started; anything outside
+ * it belongs to us.
+ */
+export function pickSession(sessions, url, before = new Set(), 
+/**
+ * The runtime this project's app RUNS as, when it is a desktop one.
+ *
+ * A desktop shell serves its renderer from an ordinary dev server, so its window and a browser tab
+ * open on the same origin are indistinguishable by url. Driving the tab passes every check here —
+ * live, on the url, SDK present — while having none of the app's IPC and none of its commands, so
+ * the verdict describes a different program that happens to share an address.
+ *
+ * Undefined for a web project, where the runtime is not a distinction worth making.
+ */
+requiredRuntime) {
+    const wanted = String(url).replace(/\/$/, '');
+    const onUrl = sessions
+        .filter((s) => (s?.url ?? '').startsWith(wanted))
+        // An SDK too old to report a runtime is ACCEPTED rather than excluded: re-running init is the
+        // only upgrade path an existing user has, and refusing them their own install to enforce a
+        // field their SDK cannot send would break the one route out.
+        .filter((s) => undefined === requiredRuntime || undefined === s.runtime || requiredRuntime === s.runtime);
+    if (0 === onUrl.length)
+        return null;
+    const fresh = onUrl.filter((s) => !before.has(s.sessionId));
+    const pool = 0 < fresh.length ? fresh : onUrl;
+    return pool.find(isLive) ?? [...pool].sort((a, b) => staleness(a) - staleness(b))[0] ?? null;
+}

package/dist/setup/setup-command.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The wire: everything init established, plus the world, plus the phases.
+ *
+ * Kept apart from cli.ts so the assembly is readable in one place and so `handleInit` stays the
+ * three lines it was. The only decision here is which effects to hand over; the sequencing lives in
+ * run-setup.ts and the pieces it calls.
+ */
+import { type SetupInput, type SetupOutcome } from './run-setup.js';
+export interface SetupCommandInput extends Omit<SetupInput, 'shape'> {
+    /** Where setup was invoked, which is not the app directory in a monorepo. */
+    readonly invokedAt: string;
+    readonly bridgePort: number;
+    readonly env: Readonly<Record<string, string>>;
+    readonly flow?: string | undefined;
+    readonly driveBudgetUsd: number;
+    readonly driveModel?: string | undefined;
+    readonly escalateWeakFlow: boolean;
+    /** Register the MCP server with the coding agents init does not itself reach. */
+    readonly registerAgents: boolean;
+}
+/**
+ * Register with the agents `init` does not reach, and leave the skill where one loads skills from.
+ *
+ * init covers eight clients and only where it finds them installed, which leaves VS Code's USER
+ * scope unwritten — it exists on machines today, and init only ever writes the project-scope file,
+ * so a VS Code user has no tools outside the directory they ran init in.
+ */
+export declare function registerOtherAgents(print: (line: string) => void): void;
+export interface SetupCommandResult extends SetupOutcome {
+    /** Set when a weak flow was re-recorded with the stronger model. */
+    readonly escalated?: {
+        readonly from: string;
+        readonly to: string;
+    } | undefined;
+    readonly driveTurns?: number | undefined;
+    readonly driveCostUsd?: number | undefined;
+}
+/**
+ * Run the phases against the real world.
+ *
+ * The dev server is stopped on every ending except success, where it is handed to the user: an
+ * instrumented app they can watch is the deliverable, and killing it would leave them with config
+ * files and a dead tab.
+ */
+export declare function runSetupCommand(input: SetupCommandInput, print: (line: string) => void): Promise<SetupCommandResult>;

package/dist/setup/setup-command.js

@@ -0,0 +1,199 @@
+/**
+ * The wire: everything init established, plus the world, plus the phases.
+ *
+ * Kept apart from cli.ts so the assembly is readable in one place and so `handleInit` stays the
+ * three lines it was. The only decision here is which effects to hand over; the sequencing lives in
+ * run-setup.ts and the pieces it calls.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { planAgentConfigs } from './agent-configs.js';
+import { AppShape, readShape } from './desktop-shape.js';
+import { stopOnInterrupt } from './interrupt.js';
+import { applyAgentPlan, applyAgentSkills } from './agent-writer.js';
+import { ApprovalOutcome, grantAutoApproval } from './auto-approve.js';
+import { agentIo } from './agent-io.js';
+import { EnsureDaemon, ensureDaemon, nodeEnsureDaemonDeps } from './ensure-daemon.js';
+import { openInBrowser } from '../cli/cli-launch.js';
+import { chooseDriver, DRIVERS, shouldEscalate } from './drive-plan.js';
+import { driveWith } from './drive-agent.js';
+import { binaryExists, flowsSaved, listSessions, OwnedDevServer, probePage, } from './node-effects.js';
+import { runSetupPhases, } from './run-setup.js';
+/** The capabilities file init scaffolds, in the order a project is likely to have it. */
+const CAPABILITY_FILES = ['reticle-dev.tsx', 'reticle-dev.ts', 'reticle-dev.jsx', 'reticle-dev.js'];
+/** `electron` in either dependency list, read the same way init's desktop doctor reads it. */
+function hasElectronDependency(dir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        if ('object' !== typeof pkg || null === pkg)
+            return false;
+        const p = pkg;
+        return undefined !== { ...p.dependencies, ...p.devDependencies }['electron'];
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Register with the agents `init` does not reach, and leave the skill where one loads skills from.
+ *
+ * init covers eight clients and only where it finds them installed, which leaves VS Code's USER
+ * scope unwritten — it exists on machines today, and init only ever writes the project-scope file,
+ * so a VS Code user has no tools outside the directory they ran init in.
+ */
+export function registerOtherAgents(print) {
+    const platform = process.platform;
+    const home = homedir();
+    const results = applyAgentPlan(planAgentConfigs({ home, platform, exists: agentIo.exists, readFile: agentIo.readFile }), agentIo);
+    const wrote = results.filter((r) => 'created' === r.action || 'merged' === r.action);
+    if (0 < wrote.length) {
+        print(`registered the MCP server with ${wrote.length} more agent(s): ${wrote.map((r) => r.name).join(', ')}`);
+    }
+    // A format we will not rewrite is somebody's to edit, so it has to be said rather than skipped.
+    for (const manual of results.filter((r) => 'manual' === r.action)) {
+        print(`${manual.name}: ${manual.why} — add the reticle entry to ${manual.file} by hand.`);
+    }
+    const skills = applyAgentSkills(agentIo, { home, platform });
+    if (0 < skills.length)
+        print(`wrote the /reticle skill for ${skills.length} agent(s)`);
+    // Registration alone still leaves an Accept dialog in front of every call, and a verification run
+    // makes dozens of them: the loop is only autonomous once the tools are pre-approved.
+    const approvals = grantAutoApproval(agentIo, { home, platform });
+    const granted = approvals.filter((a) => ApprovalOutcome.GRANTED === a.outcome);
+    if (0 < granted.length) {
+        print(`pre-approved the reticle tools in ${granted.map((a) => a.name).join(', ')} — no Accept prompt per call`);
+    }
+    for (const noted of approvals.filter((a) => undefined !== a.warn)) {
+        print(`${noted.name}: ${String(noted.warn)}`);
+    }
+}
+/**
+ * Run the phases against the real world.
+ *
+ * The dev server is stopped on every ending except success, where it is handed to the user: an
+ * instrumented app they can watch is the deliverable, and killing it would leave them with config
+ * files and a dead tab.
+ */
+export async function runSetupCommand(input, print) {
+    if (input.registerAgents)
+        registerOtherAgents(print);
+    // Before the app is booted, because the app's whole job from here is to dial this port. Without
+    // it the phases wait out their budget and then report the SDK as the thing that failed.
+    const daemon = await ensureDaemon(input.bridgePort, nodeEnsureDaemonDeps());
+    if (EnsureDaemon.UNAVAILABLE === daemon) {
+        print(`could not start the Reticle daemon on port ${String(input.bridgePort)}, so nothing is listening for the app to connect to. Run \`npx @reticlehq/server serve --port ${String(input.bridgePort)}\` and try again.`);
+    }
+    // Which shell this is decides three things the phases would otherwise get wrong: opening a
+    // browser (harmful for desktop, where the app's own window is the client), waiting for an HTTP
+    // port (a Tauri webview has none), and how long the app gets to appear (a cold `tauri dev` builds
+    // Rust first). The same evidence init's desktop doctor reads.
+    const shape = readShape({
+        hasTauriConf: existsSync(join(input.appDir, 'src-tauri', 'tauri.conf.json')),
+        hasElectronDep: hasElectronDependency(input.appDir),
+    });
+    if (AppShape.WEB !== shape)
+        print(`detected a ${shape} app`);
+    const server = new OwnedDevServer();
+    // Both roots, because in a monorepo `.reticle/` sits at the app root rather than where setup ran.
+    const flowRoots = [input.invokedAt, input.appDir];
+    let lastDrive;
+    let escalated;
+    const effects = {
+        startDevServer: (command, cwd) => {
+            print(`starting: ${command}`);
+            server.start(command, cwd, input.env);
+            return Promise.resolve();
+        },
+        devServerOutput: () => server.output(),
+        devServerExited: () => server.exited(),
+        devServerQuietForMs: () => server.quietForMs(),
+        observedPorts: () => server.listeningPorts(),
+        probePage,
+        openBrowser: async (url) => {
+            const failure = await openInBrowser(url);
+            if (null !== failure) {
+                print(`could not open a browser (${failure}). On a machine with none — CI, a container, an SSH ` +
+                    'session — take a tab Reticle owns instead: reticle_run({ tool: "reticle_lease", args: ' +
+                    `{ action: "acquire", url: "${url}" } }).`);
+            }
+        },
+        listSessions: () => listSessions(input.bridgePort),
+        // Asked before the drive rather than inferred from its result: "nothing to drive with" and
+        // "drove and proved nothing" are different answers and only the second is a failure.
+        driverAvailable: () => null !==
+            chooseDriver(DRIVERS, (bin) => ({ present: binaryExists(bin), runs: binaryExists(bin) })),
+        drive: (url, session) => {
+            const driver = chooseDriver(DRIVERS, (bin) => ({
+                present: binaryExists(bin),
+                // Present is not enough: a CLI that does not run produces an empty session that looks
+                // exactly like success.
+                runs: binaryExists(bin),
+            }));
+            if (null === driver)
+                return Promise.resolve(null);
+            // Only when the SESSION says they were never finished. init fills this file for a
+            // conventional app — it detects a state library and the testids — so opening it otherwise
+            // spends a turn on work already done, and grants write access nobody needed.
+            const capabilitiesFile = false === session.hasCapabilities
+                ? CAPABILITY_FILES.map((f) => join(input.appDir, 'src', f)).find((p) => existsSync(p))
+                : undefined;
+            print('');
+            print(`  ▸ WATCH ${url} NOW — the HUD is on, and you are about to see Reticle drive your app.`);
+            print('');
+            const request = {
+                url,
+                sessionId: session.sessionId,
+                tabThrottled: false,
+                budgetUsd: input.driveBudgetUsd,
+                ...(undefined === input.flow ? {} : { flow: input.flow }),
+                ...(undefined === input.driveModel ? {} : { model: input.driveModel }),
+                ...(undefined === capabilitiesFile ? {} : { unfinishedCapabilitiesFile: capabilitiesFile }),
+            };
+            lastDrive = driveWith(driver, request, input.appDir);
+            // A weak flow only ACTS, so it passes when the feature is broken — and setup replays saved
+            // flows, which turns one weak recording into a permanent green. Re-record it rather than
+            // hand the trade to the user.
+            if (shouldEscalate({
+                escalationEnabled: input.escalateWeakFlow,
+                fasterModel: input.driveModel,
+                flowSaved: flowsSaved(flowRoots),
+                ...(undefined === lastDrive.grade ? { grade: undefined } : { grade: lastDrive.grade }),
+            })) {
+                print(`the saved flow graded \`${lastDrive.grade ?? 'unknown'}\` — re-recording with the default model`);
+                const stronger = driveWith(driver, { ...request, model: undefined }, input.appDir);
+                escalated = { from: lastDrive.grade ?? 'unknown', to: stronger.grade ?? 'unknown' };
+                if (undefined !== stronger.grade)
+                    lastDrive = stronger;
+            }
+            if (undefined !== lastDrive.incomplete) {
+                print(`the drive did not finish, and ${lastDrive.incomplete}`);
+            }
+            return Promise.resolve('' === lastDrive.text ? null : lastDrive.text);
+        },
+        flowsSaved: () => flowsSaved(flowRoots),
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        note: print,
+    };
+    // A `finally` does not run on SIGINT, and this phase owns a detached dev server — see interrupt.ts.
+    const releaseSignals = stopOnInterrupt(() => {
+        server.stop();
+    }, process);
+    try {
+        const outcome = await runSetupPhases({ ...input, shape }, effects);
+        // The app stays up only when there is something worth watching.
+        if (outcome.ok)
+            server.handOver();
+        return {
+            ...outcome,
+            ...(undefined === escalated ? {} : { escalated }),
+            ...(undefined === lastDrive?.turns ? {} : { driveTurns: lastDrive.turns }),
+            ...(undefined === lastDrive?.costUsd ? {} : { driveCostUsd: lastDrive.costUsd }),
+        };
+    }
+    finally {
+        releaseSignals();
+        server.stop();
+    }
+}

package/dist/setup/setup-options.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The contract between the agent and the script.
+ *
+ * Everything setup does is deterministic except for the handful of things that require reading a
+ * repository and a human's request and understanding both. Those are exactly what an agent is good
+ * at and code is not, so they arrive here as ARGUMENTS rather than as steps somebody walks through:
+ * the agent decides, the script executes, and neither does the other's job.
+ *
+ * What only an agent can know, and therefore what belongs in this type:
+ *
+ *   --flow      which journey proves the thing the user cares about. Code can enumerate buttons; it
+ *               cannot know that checkout matters and the theme toggle does not. Measured, naming
+ *               it took one app's drive from a ten-minute timeout to 138 seconds, because the turns
+ *               go into FINDING a flow and naming one removes that search.
+ *   --app       which app in a monorepo the user meant. init can find the ones that are servable;
+ *               only the request says which of them is being worked on.
+ *   --env       what the app needs to get past its own front door. A key in .env.example, a mock
+ *               backend named in the README, the variable that skips an auth wall: all readable by
+ *               an agent, none inferable by a script. Without this a real app sits on a login
+ *               screen and there is no flow to drive at all.
+ *   --dev-cmd   the command, when the project's own scripts do not say it plainly.
+ *   --url       the app is already running here, so do not start anything.
+ *
+ * Everything else on this type is an operator's dial, not an agent's judgement.
+ */
+/** The bridge port. NOT the dev server's, and conflating them is a documented setup failure. */
+export declare const DEFAULT_BRIDGE_PORT = 4400;
+/** Per-phase budget. The drive gets its own, much larger one. */
+export declare const DEFAULT_PHASE_TIMEOUT_MS = 120000;
+/** What the drive may spend before it is stopped. */
+export declare const DEFAULT_DRIVE_BUDGET_USD = 3;
+export interface SetupOptions {
+    /** The journey to drive, in the caller's own words. */
+    readonly flow?: string | undefined;
+    /** Which app in a monorepo. */
+    readonly app?: string | undefined;
+    /** Environment the app needs in order to reach a usable state. */
+    readonly env?: Readonly<Record<string, string>> | undefined;
+    /** The dev command, when the project's scripts do not say it plainly. */
+    readonly devCommand?: string | undefined;
+    /** The app is already served here. */
+    readonly url?: string | undefined;
+    readonly bridgePort: number;
+    readonly phaseTimeoutMs: number;
+    readonly driveBudgetUsd: number;
+    readonly driveModel?: string | undefined;
+    /** Register the MCP with the other coding agents on this machine. */
+    readonly registerAgents: boolean;
+    /** Open a browser. False for CI, a headless box, or a tab the user already has. */
+    readonly openBrowser: boolean;
+    /** Drive a flow. False leaves step five to the caller, and is the only honest way to skip it. */
+    readonly drive: boolean;
+    /** Re-record with the stronger model when the saved flow is graded weaker than `asserted`. */
+    readonly escalateWeakFlow: boolean;
+    /** Restart a dev server whose bundle predates the build-config edit. */
+    readonly restartStaleDevServer: boolean;
+    /** Write files and stop, which is what `init` did before it grew the runtime phases. */
+    readonly filesOnly: boolean;
+    /** A license key, written to .env and never echoed. */
+    readonly licenseKey?: string | undefined;
+}
+export declare const DEFAULT_SETUP_OPTIONS: SetupOptions;
+/** One `KEY=VALUE`, as an agent would pass it. Everything after the first `=` is the value. */
+export declare function parseEnvAssignment(pair: string): {
+    key: string;
+    value: string;
+} | null;
+/**
+ * Fold repeated `--env KEY=VALUE` into one map, ignoring what cannot be a variable.
+ *
+ * A malformed pair is dropped rather than guessed at: an agent that meant `--env` and typed
+ * something else should see its variable missing, not see setup invent one.
+ */
+export declare function collectEnv(pairs: readonly string[]): Record<string, string>;