@reticlehq/server 2.12.0 → 2.13.0

package/dist/setup/node-effects.js

@@ -0,0 +1,210 @@
+/**
+ * The real world, bound to the injected shape `runSetupPhases` expects.
+ *
+ * Everything here is a thin binding to something that already exists — `openInBrowser`,
+ * `fetchStatus`, the driver table — with one exception: the dev server. Nothing else in the package
+ * owns a spawned process, and owning one properly is most of this file.
+ *
+ * The promise this makes about that process: setup leaves it running on success, because an
+ * instrumented app the user can watch IS the deliverable, and stops it on every other ending. A
+ * server nobody started, holding a port nobody can account for, surviving the terminal that spawned
+ * it, is the failure this file exists to avoid — measured, an interrupted run used to leave one
+ * listening indefinitely.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { Socket } from 'node:net';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fetchStatus } from '../cli/cli-launch.js';
+import { descendants, parseLsofPorts, parseNetstatListeners, parseWmicProcesses, } from './listeners.js';
+const WINDOWS = 'win32' === process.platform;
+/** A page fetch that is slow is a page fetch that failed, for our purposes. */
+const PROBE_TIMEOUT_MS = 5_000;
+/**
+ * Stop an inherited stdio pipe from holding the event loop open.
+ *
+ * A child's piped stdout is a Socket at runtime and a Readable in the types, which has no `unref`.
+ * Narrowing through Socket keeps that honest rather than asserting it.
+ */
+function releasePipe(stream) {
+    if (stream instanceof Socket)
+        stream.unref();
+}
+/** The dev server this process started, and the only one it will ever stop. */
+export class OwnedDevServer {
+    child;
+    buffer = '';
+    lastOutputAt = Date.now();
+    handedOver = false;
+    start(command, cwd, env) {
+        const child = spawn(command, {
+            cwd,
+            shell: true,
+            // Its own process group, so stopping it stops what it started rather than only the wrapper.
+            detached: !WINDOWS,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, ...env },
+        });
+        const collect = (chunk) => {
+            this.buffer += String(chunk);
+            this.lastOutputAt = Date.now();
+        };
+        child.stdout?.on('data', collect);
+        child.stderr?.on('data', collect);
+        this.child = child;
+    }
+    /** The process group leader, for a caller that has to clean up what it handed over. */
+    pid() {
+        return this.child?.pid;
+    }
+    output() {
+        return this.buffer;
+    }
+    exited() {
+        return undefined !== this.child && null !== this.child.exitCode;
+    }
+    quietForMs() {
+        return Date.now() - this.lastOutputAt;
+    }
+    /** Ports anything in this server's process tree is listening on. */
+    listeningPorts() {
+        const pid = this.child?.pid;
+        if (undefined === pid)
+            return [];
+        if (WINDOWS) {
+            const tree = new Set(descendants(windowsProcessPairs(), pid));
+            return [
+                ...new Set(parseNetstatListeners(run('netstat', ['-ano']))
+                    .filter((r) => tree.has(r.pid))
+                    .map((r) => r.port)),
+            ];
+        }
+        const pids = run('sh', ['-c', `ps -o pid= -g ${pid} 2>/dev/null | tr -d ' '`])
+            .split('\n')
+            .filter(Boolean);
+        if (0 === pids.length)
+            return [];
+        return parseLsofPorts(run('sh', [
+            '-c',
+            `lsof -a -p ${pids.join(',')} -iTCP -sTCP:LISTEN -P -n 2>/dev/null | awk 'NR>1{print $9}'`,
+        ]));
+    }
+    /** Hand the running server to the user. After this, `stop()` does nothing. */
+    /**
+     * Leave the server running and stop holding it.
+     *
+     * `unref` on the child is NOT enough: its stdout and stderr are pipes owned by this process, and
+     * an open pipe keeps the event loop alive on its own. So `init` printed "setup complete" and then
+     * hung until something killed it, turning a successful run into a non-zero exit — which is
+     * exactly what the install gate reported, on a run whose every other assertion passed.
+     *
+     * The streams are unref'd rather than destroyed: the server is still writing to them, and
+     * destroying the read end of a live pipe risks an EPIPE in somebody else's dev server.
+     */
+    handOver() {
+        this.handedOver = true;
+        const child = this.child;
+        releasePipe(child?.stdout);
+        releasePipe(child?.stderr);
+        child?.unref();
+    }
+    stop() {
+        const child = this.child;
+        if (this.handedOver || undefined === child?.pid)
+            return;
+        if (WINDOWS)
+            run('taskkill', ['/PID', String(child.pid), '/T', '/F']);
+        else {
+            try {
+                process.kill(-child.pid, 'SIGTERM');
+            }
+            catch {
+                try {
+                    child.kill();
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        }
+        this.child = undefined;
+    }
+}
+function run(file, args) {
+    const r = spawnSync(file, args, { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+    return r.stdout ?? '';
+}
+/**
+ * Every (pid, ppid) pair on a Windows machine — from `wmic` if it is there, PowerShell if not.
+ *
+ * `wmic` was the only source, and Microsoft has been removing it: deprecated since 21H1 and absent
+ * from current Windows images. When it is missing `run` returns '' — the honest answer for a tool
+ * that does not exist, and a catastrophic one here, because an empty process list means an empty
+ * process TREE, which means no observed ports, which means the dev server's url is never found.
+ * `init` then waits out the full quiet window and reports "the dev server stopped producing output
+ * without ever serving a page" about a Vite server that was serving perfectly the whole time.
+ *
+ * The fallback prints the same two-integers-per-line shape, so `parseWmicProcesses` reads either
+ * without knowing which produced it. Tried in this order because `wmic` is an order of magnitude
+ * faster to start than PowerShell, and on a machine that still has it nothing needs to change.
+ */
+const POWERSHELL_PAIRS = 'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ParentProcessId) $($_.ProcessId)" }';
+function windowsProcessPairs() {
+    const fromWmic = parseWmicProcesses(run('wmic', ['process', 'get', 'ParentProcessId,ProcessId']));
+    if (0 < fromWmic.length)
+        return fromWmic;
+    return parseWmicProcesses(run('powershell', ['-NoProfile', '-NonInteractive', '-Command', POWERSHELL_PAIRS]));
+}
+/**
+ * Fetch the page and say what came back.
+ *
+ * A refused certificate is reported separately because the server ANSWERED: a self-signed dev cert
+ * is an ordinary local setup, and calling it "nothing is listening" sends somebody to start a
+ * server that is already running.
+ */
+export async function probePage(url) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+        const body = await res.text();
+        return { served: true, sdkInPage: /@reticlehq|@reticle-connect|reticle-dev/.test(body) };
+    }
+    catch (err) {
+        const message = String(err?.cause?.message ??
+            err?.message ??
+            '');
+        const tlsRefused = /certificate|SELF_SIGNED|DEPTH_ZERO|ERR_TLS|unable to verify/i.test(message);
+        return { served: false, sdkInPage: false, tlsRefused };
+    }
+}
+/** Sessions the daemon is holding, in the shape the picker reads. */
+export async function listSessions(port) {
+    try {
+        const payload = await fetchStatus(port);
+        const sessions = payload.sessions;
+        return Array.isArray(sessions) ? sessions : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Whether this project has a saved flow, wherever the project keeps one. */
+export function flowsSaved(roots) {
+    for (const root of roots) {
+        try {
+            if (0 < readdirSync(join(root, '.reticle', 'flows')).length)
+                return true;
+        }
+        catch {
+            /* no flows kept there */
+        }
+    }
+    return false;
+}
+/** On PATH at all. The separate question of whether it RUNS is asked by chooseDriver. */
+export function binaryExists(bin) {
+    return 0 === spawnSync(WINDOWS ? 'where' : 'which', [bin], { stdio: 'ignore' }).status;
+}
+/** Whether a directory looks like a project setup has already wired. */
+export function alreadyWired(dir) {
+    return existsSync(join(dir, '.reticle.json'));
+}

package/dist/setup/page-probe.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The one thing the daemon cannot know: what the page actually contains.
+ *
+ * `diagnoseNoSession` in session/no-session-diagnosis.ts already tells the four daemon-side cases
+ * apart — a session that came and went, something listening that never dialled, a wired project on
+ * the wrong port, nothing listening at all — and its sentence is the one to lead with. None of that
+ * requires fetching anything, which is also its limit: the daemon never sees the HTML.
+ *
+ * So this adds only the page-side fact and nothing else. Whether the SDK is IN what the server
+ * returned splits the most common failure of all — a dev server still serving the bundle it built
+ * before the build config was edited — from a connect that ran and returned early.
+ */
+/** What a single fetch of the app's url established. */
+export interface PageProbe {
+    /** The server answered at all. */
+    readonly served: boolean;
+    /** The SDK appears in what it answered with. */
+    readonly sdkInPage: boolean;
+    /**
+     * The server ANSWERED and its certificate was refused. A self-signed dev cert is an ordinary
+     * local setup, so treating this as "nothing is listening" tells someone to start a server that is
+     * already running.
+     */
+    readonly tlsRefused?: boolean | undefined;
+}
+export declare const PageFinding: {
+    readonly NOT_SERVED: "not-served";
+    readonly TLS_REFUSED: "tls-refused";
+    readonly SDK_MISSING: "sdk-missing";
+    readonly SDK_PRESENT: "sdk-present";
+};
+export type PageFinding = (typeof PageFinding)[keyof typeof PageFinding];
+/** Pure, so the mapping is testable without a server or a browser. */
+export declare function readPage(probe: PageProbe): PageFinding;
+/**
+ * What the page adds to the daemon's account. Deliberately a sentence to APPEND, not a replacement:
+ * the daemon's diagnosis names the fix, and this says what the page looked like when we checked.
+ */
+export declare function describePage(finding: PageFinding, url: string): string;

package/dist/setup/page-probe.js

@@ -0,0 +1,49 @@
+/**
+ * The one thing the daemon cannot know: what the page actually contains.
+ *
+ * `diagnoseNoSession` in session/no-session-diagnosis.ts already tells the four daemon-side cases
+ * apart — a session that came and went, something listening that never dialled, a wired project on
+ * the wrong port, nothing listening at all — and its sentence is the one to lead with. None of that
+ * requires fetching anything, which is also its limit: the daemon never sees the HTML.
+ *
+ * So this adds only the page-side fact and nothing else. Whether the SDK is IN what the server
+ * returned splits the most common failure of all — a dev server still serving the bundle it built
+ * before the build config was edited — from a connect that ran and returned early.
+ */
+export const PageFinding = {
+    NOT_SERVED: 'not-served',
+    TLS_REFUSED: 'tls-refused',
+    SDK_MISSING: 'sdk-missing',
+    SDK_PRESENT: 'sdk-present',
+};
+/** Pure, so the mapping is testable without a server or a browser. */
+export function readPage(probe) {
+    if (true === probe.tlsRefused)
+        return PageFinding.TLS_REFUSED;
+    if (!probe.served)
+        return PageFinding.NOT_SERVED;
+    return probe.sdkInPage ? PageFinding.SDK_PRESENT : PageFinding.SDK_MISSING;
+}
+/**
+ * What the page adds to the daemon's account. Deliberately a sentence to APPEND, not a replacement:
+ * the daemon's diagnosis names the fix, and this says what the page looked like when we checked.
+ */
+export function describePage(finding, url) {
+    switch (finding) {
+        case PageFinding.NOT_SERVED:
+            // Leads with the cause. The break-matrix asserts this phrasing because it is what a reader
+            // greps for after a timeout, and "nothing answered" reads as an observation about the check
+            // rather than a statement about the machine.
+            return `nothing is serving ${url} — the dev server is not up, so the SDK was never given the chance to load.`;
+        case PageFinding.TLS_REFUSED:
+            return (`${url} answered over HTTPS with a certificate this process will not accept, so setup could ` +
+                'not read the page. The app itself may be perfectly fine; re-run with ' +
+                'NODE_TLS_REJECT_UNAUTHORIZED=0 if you trust this dev certificate, or use the http origin.');
+        case PageFinding.SDK_MISSING:
+            return (`${url} is served, and the SDK is NOT in the page. That is almost always a dev server still ` +
+                'serving the bundle it built before the build config was edited: restart it and hard-reload.');
+        case PageFinding.SDK_PRESENT:
+            return (`The SDK IS in the page at ${url} and never dialled the bridge, so it loaded and returned ` +
+                'early: a localhost guard, a production-only check, or a bridge port that differs on the two sides.');
+    }
+}

package/dist/setup/relaunch.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What restarting the calling client should do — decided, not performed.
+ *
+ * The dangerous case is the one this exists for: `--resume <id>` on an id with NO transcript opens
+ * an EMPTY conversation under that id, silently. Nothing errors, the client starts, the session
+ * looks real, and every tool the restart existed to load is missing. A restart that lands there is
+ * worse than no restart, because it is indistinguishable from success.
+ *
+ * The decision is pure and testable; opening a terminal is neither, and is left to the caller.
+ */
+/** What the caller should do, once the environment has been read. */
+export declare const RelaunchOutcome: {
+    /** Claude Code named its own session and a transcript backs it. */
+    readonly CLAUDE: "claude";
+    /** No claude session, but a codex rollout in this directory identifies one. */
+    readonly CODEX: "codex";
+    /** A session id with nothing behind it — the case that looks like success. */
+    readonly REFUSED: "refused";
+    /** The client tells a child process nothing about which conversation it is. */
+    readonly UNKNOWN_CLIENT: "unknown-client";
+};
+export type RelaunchOutcome = (typeof RelaunchOutcome)[keyof typeof RelaunchOutcome];
+export interface RelaunchEnv {
+    /** Claude Code puts its session id in the environment; nothing else does. */
+    readonly claudeSessionId?: string | undefined;
+    /** Codex is recognised from the rollout file it is writing, not from the environment. */
+    readonly codexSessionId?: string | undefined;
+    /** Does a transcript actually exist for this id. */
+    transcriptExists(sessionId: string): boolean;
+    readonly cwd: string;
+}
+export interface RelaunchDecision {
+    readonly outcome: RelaunchOutcome;
+    readonly message: string;
+}
+export declare function relaunchDecision(env: RelaunchEnv): RelaunchDecision;

package/dist/setup/relaunch.js

@@ -0,0 +1,57 @@
+/**
+ * What restarting the calling client should do — decided, not performed.
+ *
+ * The dangerous case is the one this exists for: `--resume <id>` on an id with NO transcript opens
+ * an EMPTY conversation under that id, silently. Nothing errors, the client starts, the session
+ * looks real, and every tool the restart existed to load is missing. A restart that lands there is
+ * worse than no restart, because it is indistinguishable from success.
+ *
+ * The decision is pure and testable; opening a terminal is neither, and is left to the caller.
+ */
+/** What the caller should do, once the environment has been read. */
+export const RelaunchOutcome = {
+    /** Claude Code named its own session and a transcript backs it. */
+    CLAUDE: 'claude',
+    /** No claude session, but a codex rollout in this directory identifies one. */
+    CODEX: 'codex',
+    /** A session id with nothing behind it — the case that looks like success. */
+    REFUSED: 'refused',
+    /** The client tells a child process nothing about which conversation it is. */
+    UNKNOWN_CLIENT: 'unknown-client',
+};
+/** The prompt a resumed session is handed, so the restart continues the work rather than idling. */
+const RESUME_PROMPT = 'Reticle is installed. Continue where we left off.';
+export function relaunchDecision(env) {
+    const { claudeSessionId, codexSessionId } = env;
+    // A claude id wins whenever there is one: that client named ITSELF, and a stale rollout file from
+    // an earlier codex run in the same directory must not redirect the restart.
+    if (claudeSessionId !== undefined && '' !== claudeSessionId) {
+        if (!env.transcriptExists(claudeSessionId)) {
+            return {
+                outcome: RelaunchOutcome.REFUSED,
+                message: `refusing to restart: no transcript exists yet for ${claudeSessionId}, and \`--resume\` ` +
+                    'on an id with no transcript opens an EMPTY conversation that looks exactly like it ' +
+                    'worked. Say something in this session first, then re-run with --relaunch.',
+            };
+        }
+        return {
+            outcome: RelaunchOutcome.CLAUDE,
+            message: 'restart this conversation with the tools loaded:\n  ' +
+                `cd ${JSON.stringify(env.cwd)} && claude --resume ${claudeSessionId} ` +
+                `${JSON.stringify(RESUME_PROMPT)}`,
+        };
+    }
+    if (codexSessionId !== undefined && '' !== codexSessionId) {
+        return {
+            outcome: RelaunchOutcome.CODEX,
+            message: 'restart this conversation with the tools loaded:\n  ' +
+                `cd ${JSON.stringify(env.cwd)} && codex resume ${codexSessionId} ` +
+                `${JSON.stringify(RESUME_PROMPT)}`,
+        };
+    }
+    return {
+        outcome: RelaunchOutcome.UNKNOWN_CLIENT,
+        message: 'this client does not tell a child process which conversation it is, so nothing here can ' +
+            'resume it. Restart it once and the reticle_* tools will be there.',
+    };
+}

package/dist/setup/remaining-steps.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What is left to do by hand, from wherever setup stopped.
+ *
+ * Naming a cause is not the same as being recoverable. Setup can misbehave, and when it does the
+ * caller should not have to re-read the whole procedure and work out for itself which parts already
+ * worked — it should pick up at the step that did not. Ordered, and only ever the REMAINING steps.
+ */
+/** How far a run got. Everything here is knowable from the result object setup already builds. */
+export interface Progress {
+    readonly initDone: boolean;
+    readonly devServerUp: boolean;
+    readonly sessionConnected: boolean;
+    readonly flowSaved: boolean;
+    /** Set when the caller supplied a url, so nobody is told to start a server they already run. */
+    readonly urlSuppliedByCaller: boolean;
+    readonly url?: string | undefined;
+    readonly devCommand?: string | undefined;
+}
+export declare function remainingSteps(p: Progress): string[];

package/dist/setup/remaining-steps.js

@@ -0,0 +1,31 @@
+/**
+ * What is left to do by hand, from wherever setup stopped.
+ *
+ * Naming a cause is not the same as being recoverable. Setup can misbehave, and when it does the
+ * caller should not have to re-read the whole procedure and work out for itself which parts already
+ * worked — it should pick up at the step that did not. Ordered, and only ever the REMAINING steps.
+ */
+const DOCS_INDEX = 'https://docs.reticle.sh/llms.txt';
+export function remainingSteps(p) {
+    const steps = [];
+    if (!p.initDone) {
+        steps.push('Run `npx @reticlehq/server@latest init` here, and fix every ⚠ it reports.');
+    }
+    if (!p.devServerUp && !p.urlSuppliedByCaller) {
+        steps.push(`Start the dev server yourself: ${p.devCommand ?? 'the dev script in package.json'}, then open the app in a browser.`);
+    }
+    if (!p.sessionConnected) {
+        steps.push('Confirm a session appears with `reticle_sessions`. If the list is empty, read its ' +
+            '`next_action`: the usual cause is a dev server that was already running when the build ' +
+            'config was edited, so restart it and hard-reload' +
+            (undefined === p.url ? '.' : ` ${p.url}.`));
+    }
+    if (!p.flowSaved) {
+        steps.push('Drive one flow and produce a verdict: `reticle_snapshot({mode:"interactive"})` once, ' +
+            '`reticle_act_sequence` for the setup steps, then ONE `reticle_act_and_wait({ref,action,until})`. ' +
+            'Wrap it in `reticle_record` start/stop and `reticle_flow_save`, and check the grade it ' +
+            'returns is `asserted` — anything else only acts, so it passes even when the feature breaks.');
+    }
+    steps.push(`The whole procedure, if you need it: \`curl ${DOCS_INDEX}\`.`);
+    return steps;
+}

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

@@ -0,0 +1,99 @@
+/**
+ * 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 { type CandidateSession } from './session-pick.js';
+import { type PageProbe } from './page-probe.js';
+import { AppShape } from './desktop-shape.js';
+/** Where a run got to, and why it stopped if it did. */
+export declare const SetupPhase: {
+    readonly DEV_SERVER: "dev-server";
+    readonly CONNECT: "connect";
+    readonly DRIVE: "drive";
+    readonly DONE: "done";
+};
+export type SetupPhase = (typeof SetupPhase)[keyof typeof SetupPhase];
+export interface SetupOutcome {
+    /** True only when a flow was driven AND saved. Writing files is not an install. */
+    readonly ok: boolean;
+    readonly reachedPhase: SetupPhase;
+    readonly url?: string | undefined;
+    readonly sessionId?: string | undefined;
+    /** The drive's own report, kept verbatim and never trusted as a pass on its own. */
+    readonly verdict?: string | undefined;
+    readonly flowSaved: boolean;
+    /** What the caller should do next, when this did not finish. */
+    readonly fallback: string[];
+    readonly notes: string[];
+}
+/** Everything the sequence needs from the world, so none of it is reached for directly. */
+export interface SetupEffects {
+    /** Start the dev server. Resolves once started; the caller owns stopping it. */
+    readonly startDevServer: (command: string, cwd: string) => Promise<void>;
+    /** Everything the dev server has printed so far. */
+    readonly devServerOutput: () => string;
+    readonly devServerExited: () => boolean;
+    /** Milliseconds since it last printed anything. */
+    readonly devServerQuietForMs: () => number;
+    /** Ports our own process group is listening on. */
+    readonly observedPorts: () => number[];
+    /** Fetch the url and report what came back. */
+    readonly probePage: (url: string) => Promise<PageProbe>;
+    readonly openBrowser: (url: string) => Promise<void>;
+    readonly listSessions: () => Promise<CandidateSession[]>;
+    /** Drive one flow. Returns the agent's report, or null when nobody could. */
+    readonly drive: (url: string, session: CandidateSession) => Promise<string | null>;
+    /**
+     * Whether this machine has an agent CLI at all.
+     *
+     * Separate from `drive` returning null, because those are different facts and only one of them is
+     * a failure. A drive that RAN and proved nothing is a result worth a non-zero exit. A drive that
+     * could not run is the absence of a tool on the machine, and reporting the install as failed for
+     * it told CI runners — where no agent CLI is ever installed — that a perfectly good install had
+     * not worked.
+     */
+    readonly driverAvailable: () => boolean;
+    readonly flowsSaved: () => boolean;
+    readonly now: () => number;
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly note: (line: string) => void;
+}
+export interface SetupInput {
+    readonly appDir: string;
+    readonly devCommand?: string | undefined;
+    /** The app is already served here, so nothing is started. */
+    readonly suppliedUrl?: string | undefined;
+    /**
+     * The caller's own budget for the connect wait, when they named one.
+     *
+     * Absent, the shape's policy decides — a desktop shell genuinely needs longer than a browser tab.
+     * Present, it WINS, including when it is shorter: the deadline used to be
+     * `max(phaseTimeoutMs, policy)`, so `--timeout 3` could only ever lengthen the wait. A timeout the
+     * tool ignores is a lie, and it left every hostile-environment check killed by its own harness
+     * before setup could say what was wrong.
+     */
+    readonly connectBudgetMs?: number | undefined;
+    readonly openBrowser: boolean;
+    readonly drive: boolean;
+    /** Web, Electron or Tauri. Desktop changes three things; see desktop-shape.ts. */
+    readonly shape: AppShape;
+    readonly phaseTimeoutMs: number;
+    readonly pollMs: number;
+}
+/**
+ * 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 declare function runSetupPhases(input: SetupInput, fx: SetupEffects): Promise<SetupOutcome>;