@reticlehq/server 2.11.0 → 2.13.0

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>;

package/dist/setup/run-setup.js

@@ -0,0 +1,187 @@
+/**
+ * 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, urlToWatch, WaitVerdict } from './dev-server-wait.js';
+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,
+            });
+            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>;