@reticlehq/server 2.14.0 → 3.2.0

package/dist/command/setup/remaining-steps.js

@@ -0,0 +1,53 @@
+/**
+ * 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';
+/**
+ * The shell form on purpose, not `reticle_session { action: "feedback" }`.
+ *
+ * Every list this module returns is printed because a run did NOT finish, and the most common
+ * reason it did not finish is that no session ever connected -- which is precisely the state where
+ * the tool surface is unreachable. Naming the tool here would ask the reader to file through the
+ * thing that is broken. The shell command needs no daemon and no session.
+ */
+const FEEDBACK_CMD = 'npx @reticlehq/server feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"';
+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_session { action: "list" }`. 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('Prove one flow, which is the first run and is yours to start. Drive it yourself with the ' +
+            '`reticle_*` tools, ending in `reticle_act_and_wait` or `reticle_assert` — those two are ' +
+            'what produce a verdict. Or hand the whole drive to Reticle with `reticle_verify { action: ' +
+            '"explore", persona: "<who does what>" }`, which records what it drove so later runs replay ' +
+            'with no model in the loop; that route needs ANTHROPIC_API_KEY.');
+    }
+    // Whether anything is actually outstanding, read BEFORE the docs pointer is added -- that line is
+    // an offer, not a task, and a run with nothing left still gets it.
+    const somethingIsOutstanding = 0 < steps.length;
+    steps.push(`The whole procedure, if you need it: \`curl ${DOCS_INDEX}\`.`);
+    // Asked only where something did not finish, which is the reader guaranteed to have something
+    // worth telling us. The ask used to be printed by `init` before the dev server even started, so
+    // it reached every reader EXCEPT the ones who hit a problem. Not asked on a clean run: a request
+    // for a defect report at the end of a run that worked is noise, and noise is how an ask stops
+    // being read at all.
+    if (somethingIsOutstanding) {
+        steps.push(`If any of that was Reticle's fault -- a step that did not match your project, a script that ` +
+            `broke, a message that sent you the wrong way -- tell us, and it gets fixed: ${FEEDBACK_CMD}`);
+    }
+    return steps;
+}

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

@@ -0,0 +1,123 @@
+/**
+ * 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 and proves a session
+ * connected. That is where ONBOARDING ends — the first run, which proves a flow, is a separate
+ * stage and a separate command.
+ *
+ * It does NOT drive a flow. `reticle_verify { action: "explore" }` does that, with a model inside
+ * the daemon that already holds the tools — so no client restart is needed and no second CLI has to
+ * exist on the machine.
+ *
+ * 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 './probe/page-probe.js';
+import { AppShape } from './desktop-shape.js';
+export declare const SetupPhase: {
+    readonly DEV_SERVER: "dev-server";
+    readonly CONNECT: "connect";
+    readonly DONE: "done";
+};
+export type SetupPhase = (typeof SetupPhase)[keyof typeof SetupPhase];
+export interface SetupOutcome {
+    /** True when the app is running, instrumented and connected. Writing files alone is not that. */
+    readonly ok: boolean;
+    readonly reachedPhase: SetupPhase;
+    readonly url?: string | undefined;
+    readonly sessionId?: string | undefined;
+    /**
+     * Always false here now, and kept because the callers that report progress still read it.
+     *
+     * Onboarding does not drive, so it cannot save a flow. The first run is what saves one.
+     */
+    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. */
+/**
+ * The daemon's reason for "no session", in the two lengths its two readers need.
+ *
+ * Same fact, not two facts: `full` is the lead plus the differential behind it, so a reader given
+ * only one of them is never given something the other contradicts.
+ */
+export interface DaemonReason {
+    /** One line, printed to the person watching the install. */
+    readonly lead: string;
+    /** The whole differential, recorded for the agent reading `--json`. Defaults to the lead. */
+    readonly full?: string;
+}
+export interface SetupEffects {
+    /** Start the dev server. Resolves once started; the caller owns stopping it. */
+    readonly startDevServer: (command: string, cwd: string) => Promise<void>;
+    /**
+     * A live server this project already announced, if any. Setup attaches to it rather than
+     * starting a second one on the next port.
+     */
+    readonly existingAppUrl?: () => Promise<string | undefined>;
+    /** 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>;
+    /**
+     * Ask for the app to be opened. Deliberately `void`: whether a window APPEARED is not knowable here.
+     *
+     * This returned a boolean for one commit, so that a launcher which failed could shorten the wait
+     * below instead of spending the whole connect budget on a session nothing could create. It was
+     * reverted because the premise is false. On the ubuntu CI runners `xdg-open` exits 3 -- the exit
+     * code this would have trusted -- and a browser STILL appears and dials in a little later, so
+     * four install-gate scaffolds that had passed for releases went red the moment the wait was cut
+     * short (`vite-react`, `vite-vue`, `next-app-router`, `monorepo-subdir`, run 35242186243 against
+     * 35232727716). A non-zero launcher exit means UNKNOWN, not "no browser": it reports whether the
+     * COMMAND succeeded, never whether a window opened. Do not shorten a wait on it.
+     */
+    readonly openBrowser: (url: string) => Promise<void>;
+    readonly listSessions: () => Promise<CandidateSession[]>;
+    /**
+     * The daemon's own account of why nothing connected, if it can be asked.
+     *
+     * The daemon is the only party that can see a hello it REFUSED, and a refusal is the one piece of
+     * positive evidence in the whole failure -- only an SDK dials the bridge, so a turned-away page
+     * proves the app is running, instrumented and pointed here. `page-probe.ts` has said since it was
+     * written that this sentence is the one to lead with and that the page finding merely adds the
+     * page-side fact; only the second half was wired.
+     *
+     * Optional, and allowed to fail: setup must still report what it saw when the daemon cannot be
+     * reached, which is itself one of the states this runs in.
+     */
+    readonly daemonWhy?: () => Promise<DaemonReason | undefined>;
+    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;
+    /** Web, Electron or Tauri. Desktop changes three things; see desktop-shape.ts. */
+    readonly shape: AppShape;
+    readonly phaseTimeoutMs: number;
+    readonly pollMs: number;
+}
+export declare function runSetupPhases(input: SetupInput, fx: SetupEffects): Promise<SetupOutcome>;

package/dist/command/setup/run-setup.js

@@ -0,0 +1,316 @@
+/**
+ * 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 and proves a session
+ * connected. That is where ONBOARDING ends — the first run, which proves a flow, is a separate
+ * stage and a separate command.
+ *
+ * It does NOT drive a flow. `reticle_verify { action: "explore" }` does that, with a model inside
+ * the daemon that already holds the tools — so no client restart is needed and no second CLI has to
+ * exist on the machine.
+ *
+ * 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, portBusyMessage, QUIET_MEANS_HUNG_MS, urlToWatch, WaitVerdict, } from './bringup/dev-server-wait.js';
+import { waitProgressLine } from './terminal/wait-progress.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, findingBeforeOpen, PageFinding, } from './probe/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. */
+/**
+ * How long to keep asking whether the SDK has reached the page before giving up on opening a window.
+ * Bounded by the connect budget, so a short budget is never overrun by the readiness check.
+ */
+const SDK_READY_WINDOW_MS = 15_000;
+/** The wait left when no browser was opened: only a tab that is ALREADY loaded can still appear. */
+const NO_BROWSER_GRACE_MS = 3_000;
+export const SetupPhase = {
+    DEV_SERVER: 'dev-server',
+    CONNECT: 'connect',
+    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.
+ */
+/**
+ * Ask the daemon why, and treat every failure as "it did not say".
+ *
+ * A daemon that cannot be reached is one of the states this runs in, so an error here is data, not
+ * an exception: the page finding below still prints and the run still ends with its own verdict.
+ */
+async function daemonWhy(fx) {
+    if (undefined === fx.daemonWhy)
+        return undefined;
+    try {
+        const why = await fx.daemonWhy();
+        return undefined === why || 0 === why.lead.length ? undefined : why;
+    }
+    catch {
+        return undefined;
+    }
+}
+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;
+    let attachedToExisting = false;
+    if (undefined === url) {
+        const announced = undefined === fx.existingAppUrl ? undefined : await fx.existingAppUrl();
+        if (undefined !== announced && 0 < announced.length) {
+            // The plugin already announced a live server for THIS project. Starting `dev` beside it is
+            // how Vite binds 5174, a second tab opens, and `reticle_sessions` lists three with no way
+            // to pick. The registry is scoped; an unscoped listen would attach to a sibling app.
+            url = announced;
+            attachedToExisting = true;
+            note(`This project is already running at ${announced} — attaching instead of starting a second server.`);
+        }
+        else 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 — start the app yourself and pass --url to say ' +
+                'where it is serving, or add a dev/start/serve script to package.json and re-run.');
+            return stop(input, SetupPhase.DEV_SERVER, {}, notes);
+        }
+        else {
+            await fx.startDevServer(input.devCommand, input.appDir);
+            const startedAt = fx.now();
+            // This loop used to poll in complete silence. Reported as thirty minutes of nothing ending in a
+            // SIGKILL — and whatever made that wait long, a user who cannot tell "still starting" from
+            // "wedged" has been given no way to act. See wait-progress.ts.
+            let spokeAtMs;
+            for (;;) {
+                const watching = urlToWatch(fx.devServerOutput(), fx.observedPorts());
+                const waitedMs = fx.now() - startedAt;
+                const progress = waitProgressLine(waitedMs, watching, spokeAtMs);
+                if (progress !== undefined) {
+                    note(progress);
+                    spokeAtMs = waitedMs;
+                }
+                const probe = undefined === watching
+                    ? { served: false, sdkInPage: false }
+                    : await fx.probePage(watching);
+                const serving = probe.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) {
+                    // Prefer the URL that answered when the announcement was the wrong family (#884).
+                    url = probe.reachedUrl ?? 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(portBusyMessage(fx.devServerOutput()) ??
+                        '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 listed = await fx.listSessions();
+    const requiredRuntime = isDesktop(input.shape) ? input.shape : undefined;
+    // A tab already on this URL is the answer. Opening another is how three sessions appear.
+    // `before` is empty so pickSession will take that tab rather than waiting for a new one.
+    const alreadyConnected = attachedToExisting
+        ? pickSession(listed, url, new Set(), requiredRuntime)
+        : null;
+    const before = new Set(listed.map((s) => s.sessionId));
+    // Do not put a window in front of somebody until the page behind it can actually do something.
+    //
+    // The probe that says whether the SDK is even IN the page used to run only in the failure branch
+    // below, AFTER the browser was already open. So a mis-wired app opened a real window onto a page
+    // that was never going to connect, and the person watching it saw a browser appear and then
+    // nothing happen for the whole connect budget — which reads as "Reticle is broken" rather than
+    // "the bundle predates the config edit". One fetch, before the window, turns that into a sentence.
+    //
+    // Only the browser is gated. The wait below still runs: something else may connect (an already
+    // open tab, a desktop window), and the probe is a statement about one fetch of the document, not
+    // proof that nothing can ever dial in.
+    const budgetMs = input.connectBudgetMs ?? Math.max(input.phaseTimeoutMs, policy.connectBudgetMs);
+    let openedBrowser = false;
+    if (null === alreadyConnected && input.openBrowser && policy.openBrowser) {
+        // SERVED is the precondition, not SDK_PRESENT: a url that answers nothing is the only state
+        // where a window is certainly useless. Whether the SDK is in the served HTML is a DIFFERENT
+        // question — Vite injects a marker, while Nuxt, React Router, Astro, SvelteKit and CRA deliver
+        // the connect in the JS BUNDLE, so their HTML never carries it. Gating on presence failed five
+        // of ten scaffolds in the install gate: no window, so no bundle, so no session, so exit 1 on a
+        // correct install. page-probe.ts says it is a diagnostic for a connect that already failed; the
+        // same signal as a precondition deadlocks every case it is wrong about.
+        //
+        // So presence decides only WHEN: open the moment it appears (the fast path for the frameworks
+        // that inline it), otherwise once the short readiness window is out.
+        const finding = await findingBeforeOpen(() => fx.probePage(url), { now: () => fx.now(), sleep: (ms) => fx.sleep(ms) }, Math.min(SDK_READY_WINDOW_MS, budgetMs), input.pollMs);
+        if (PageFinding.NOT_SERVED === finding || PageFinding.TLS_REFUSED === finding) {
+            note(describePage(finding, url));
+            note('Not opening a browser: nothing answered that url, so the window could only show an error ' +
+                'page. Fix the line above and re-run — `init` is idempotent.');
+        }
+        else {
+            // Said BEFORE the window appears, so somebody watching a page that stays inert has already
+            // been told which of the two it is.
+            if (PageFinding.SDK_MISSING === finding)
+                note(describePage(finding, url));
+            // `= true` means ATTEMPTED, which is the most that is knowable — see openBrowser above for
+            // why the launcher's own exit code must not be read as "no window appeared".
+            await fx.openBrowser(url);
+            openedBrowser = true;
+        }
+    }
+    // Waiting the full budget for a session when nothing was opened to create one is dead time, and
+    // it used to be over two minutes of it: the browser is the session source on web, so declining to
+    // open it and then waiting as if we had is a promise to the reader that cannot be kept. Something
+    // else may still dial in — a tab the user already has open, a desktop window — and the existing
+    // diagnosis says such a session "will appear within a second of the page loading", so a short
+    // grace is the honest wait. A run that DID open a browser keeps the whole budget.
+    const deadline = fx.now() +
+        (openedBrowser || !(input.openBrowser && policy.openBrowser)
+            ? budgetMs
+            : Math.min(NO_BROWSER_GRACE_MS, budgetMs));
+    let session = alreadyConnected;
+    while (null === session) {
+        // 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, requiredRuntime);
+        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 {
+            // The daemon first, when it has something to say: it is the only party that can see a hello it
+            // refused, and that outranks anything inferred from an absence. Then the page, which is the
+            // one thing the daemon cannot know, and worth one fetch.
+            const why = await daemonWhy(fx);
+            if (undefined !== why) {
+                // Two readers, two lengths, one fetch.
+                //
+                // The person watching an install gets the LEAD — that is what trimming this diagnosis was
+                // for. The agent reads `notes` out of `--json`, and what it acts on is the differential:
+                // which ports were actually scanned (so an empty result is not proof), why a missing
+                // `.reticle.json` is expected in a monorepo, and the lease that opens a URL on a box with
+                // no browser at all.
+                //
+                // Printing only the lead put BOTH readers on the lead, which silently emptied the agent
+                // surface: `init --json` stopped mentioning the lease, and `break/break-matrix.mjs`
+                // (`no-browser-to-open`) went red for exactly that reason.
+                fx.note(why.lead);
+                notes.push(why.full ?? why.lead);
+            }
+            note(describePage(readPage(await fx.probePage(url)), url));
+        }
+        return stop(input, SetupPhase.CONNECT, { url }, notes);
+    }
+    // ── connected, which is where ONBOARDING ends ────────────────────────────────────────────────
+    //
+    // Getting started is three stages — installation puts the CLI on the machine, onboarding wires
+    // the project, the first run proves a flow — and this command owns the middle one. A connected
+    // session is the whole proof that onboarding worked: the SDK is in the page, the bridge paired,
+    // and the tools now have something to talk to.
+    //
+    // `<url>` stays a placeholder in this string on purpose: `guidance-commands-run` feeds every
+    // command we print to the real parser, and an interpolated value reads there as a missing operand.
+    // The live url is named in the sentence instead, where a reader needs it anyway.
+    // Both routes, because `explore` needs a model: without ANTHROPIC_API_KEY it answers "No model
+    // configured to drive the app". Naming only that one hands the reader a dead end on any machine
+    // without a key, which is the same defect this release spent its time removing everywhere else.
+    // Three short lines rather than one paragraph, and each says who it is for.
+    //
+    // This was a single 524-character note, measured on a real first run: eighty-three words, no
+    // break, naming `reticle_*` tools at a reader who had just typed `reticle init` in a terminal and
+    // has no such tools to call. The facts were right and the shape made them unreadable, which on
+    // the last line of onboarding is the same as not saying them.
+    note(`Connected. ${url} is instrumented. Onboarding is done; nothing is verified yet.`);
+    note('Agent: drive one flow and end it with `reticle_act_and_wait` or `reticle_assert`. Those two ' +
+        'produce a verdict; nothing else does.');
+    note('Or hand over the whole drive: `reticle_verify { action: "explore", persona: "<who does ' +
+        'what>" }` records what it drove, so later runs replay with no model in the loop. Needs ' +
+        'ANTHROPIC_API_KEY.');
+    return {
+        ok: true,
+        reachedPhase: SetupPhase.CONNECT,
+        url,
+        sessionId: session.sessionId,
+        flowSaved: false,
+        notes,
+        fallback: [],
+    };
+}

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

@@ -0,0 +1,48 @@
+/**
+ * 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';
+/** Stop the dev server setup started, if it is still running. Safe to call when there is none. */
+export declare function stopRunningDevServer(): void;
+/**
+ * Catch our own faults for the whole process, and take the dev server with them.
+ *
+ * Here rather than in `cli/`, where it started: the handler it installs lives in `terminal/`, and
+ * `cli` is not allowed to reach that directory. `directory-reach` was right to refuse it — the
+ * installer stops the dev server THIS file owns, so this is where it belonged all along.
+ *
+ * Installed at the CLI entry rather than inside the phase below, because a fault can fire in any
+ * phase: the first attempt sat inside the runtime phase and caught nothing in two different
+ * environments, because init had already returned by the time the handler existed.
+ */
+export declare function installCrashGuard(): () => void;
+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>>;
+    /** 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;
+type SetupCommandResult = SetupOutcome;
+/**
+ * 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>;
+export {};