@reticlehq/server 2.14.0 → 3.2.0

package/dist/command/setup/init/init-runtime.js

@@ -0,0 +1,168 @@
+/**
+ * What `init` does after the files are written, and how it decides whether to.
+ *
+ * Lives here rather than in cli.ts because it is a cohesive unit with its own reasons, and because
+ * cli.ts is a dispatcher: a command that grew a second half should not make the file that routes
+ * every command harder to read.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+import { confirmInstall, nodeConfirmDeps } from '../terminal/confirm.js';
+import { writeLicenseKey } from '../license-key.js';
+import { registerOtherAgents, runSetupCommand } from '../setup-command.js';
+import { bridgeOccupied } from '../bringup/bridge-port.js';
+import { relaunchDecision } from '../bringup/relaunch.js';
+import { claudeTranscriptExists, codexSessionFor } from '../terminal/transcripts.js';
+import { probePresence } from '../../daemon/binding/port-presence.js';
+import { probeDaemon } from '../../../surface/mcp/proxy/proxy-daemon-probe.js';
+import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
+import { collectEnv, DEFAULT_PHASE_TIMEOUT_MS } from '../setup-options.js';
+/** How often the runtime phases look again: fast enough not to be the wait, slow enough to be free. */
+const POLL_MS = 250;
+/** Registration is global MCP wiring, so both flags that disown it are read here. */
+function wantsAgents(parsed) {
+    return false !== parsed.agents && false !== parsed.mcp;
+}
+const licenseIo = {
+    exists: (path) => existsSync(path),
+    readFile: (path) => readFileSync(path, 'utf8'),
+    writeFile: (path, contents) => writeFileSync(path, contents),
+};
+/**
+ * Carry on from a finished `init`, or stop where it used to.
+ *
+ * `--files-only` is what init did before it learned to boot the app, and a dry run is a preview:
+ * both keep the old ending. Everyone else gets the rest, because writing files was never the same
+ * thing as an install working.
+ */
+function printRelaunch(parsed, io, cwd) {
+    if (true !== parsed.relaunch)
+        return;
+    io.print(relaunchDecision({
+        ...(undefined === process.env['CLAUDE_CODE_SESSION_ID']
+            ? {}
+            : { claudeSessionId: process.env['CLAUDE_CODE_SESSION_ID'] }),
+        ...(undefined === codexSessionFor(cwd) ? {} : { codexSessionId: codexSessionFor(cwd) }),
+        transcriptExists: claudeTranscriptExists,
+        cwd,
+    }).message);
+    io.print('');
+}
+export async function continueAfterInit(parsed, result, io, cwd) {
+    const port = parsed.port ?? RETICLE_DEFAULT_PORT;
+    // Before anything else: the key belongs in .env whichever way this run ends, and the CLI folds a
+    // project-local .env into the environment on every invocation.
+    if (undefined !== parsed.licenseKey) {
+        const written = writeLicenseKey(cwd, parsed.licenseKey, licenseIo);
+        io.print(written.message);
+    }
+    // Decided and printed before the `--files-only` return, not after it. The restart question is
+    // asked by whoever just installed, and `--files-only` is the mode an agent uses when the app is
+    // ALREADY running — so the one route that most needs the answer was the one route that could not
+    // reach it, and `--relaunch --files-only` accepted the flag and silently did nothing with it.
+    //
+    // Never performed: opening a terminal is not something a one-shot command should do behind a
+    // flag, and the half worth having is the refusal — `--resume` on an id with no transcript opens
+    // an EMPTY conversation that looks exactly like it worked. See relaunch.ts.
+    printRelaunch(parsed, io, cwd);
+    if (true === parsed.filesOnly || parsed.dryRun) {
+        // Registration and pre-approval still run here, and this is the ONLY route an existing user
+        // has: nothing reaches back into a machine that installed Reticle a version ago, so the
+        // upgrade path is re-running init, and the light form of init has to be enough to carry it.
+        // A dry run writes nothing anywhere, including here.
+        if (true === parsed.filesOnly && wantsAgents(parsed))
+            registerOtherAgents(io.print);
+        return confirmInstall(result, io, nodeConfirmDeps(port)).then(() => {
+            if (!result.ok)
+                process.exit(1);
+        });
+    }
+    const context = result.context;
+    if (context === undefined) {
+        // Nothing was established, so there is nothing to run against. init has already said why.
+        process.exit(1);
+    }
+    // A PENDING connect step is not a reason to skip the runtime phase, and treating it as one made
+    // `init` stop with "paste this snippet" while never looking at the app.
+    //
+    // `result.ok` is exactly `!connectPending`, so every project whose instrumentation needs a manual
+    // step — a plain-HTML app, anything with no recognised build config — exited here. The user was
+    // told to do something by hand and told nothing about whether their server was even up, whether
+    // the snippet had landed, or which url was checked. The runtime phase answers all three, and its
+    // answers are the actionable ones: "nothing is serving http://…", "the SDK is NOT in the page".
+    //
+    // The run still ends non-zero: the phase returns `ok: false` when no session appears, and a
+    // session appearing means the manual step WAS done and the app really did connect — which is a
+    // green worth reporting, not one to suppress.
+    // Before the connect wait, never after: a bridge held by a stranger makes a session impossible,
+    // so going ahead spends the entire budget and then reports what reads as an instrumentation
+    // problem — the one place that is fine. See bridge-port.ts.
+    const refusal = bridgeOccupied(await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }), port);
+    if (refusal !== undefined) {
+        io.print(refusal);
+        process.exit(1);
+    }
+    return runSetupCommand({
+        appDir: context.appDir,
+        invokedAt: cwd,
+        bridgePort: port,
+        env: collectEnv(parsed.env ?? []),
+        openBrowser: false !== parsed.open,
+        registerAgents: wantsAgents(parsed),
+        phaseTimeoutMs: undefined === parsed.timeoutSeconds
+            ? DEFAULT_PHASE_TIMEOUT_MS
+            : parsed.timeoutSeconds * 1000,
+        // Only when the caller actually said so — see connectBudgetMs. Omitted, the shape's policy
+        // keeps deciding, so nobody who passed nothing waits less than they used to.
+        ...(undefined === parsed.timeoutSeconds
+            ? {}
+            : { connectBudgetMs: parsed.timeoutSeconds * 1000 }),
+        pollMs: POLL_MS,
+        ...(undefined === context.devCommand ? {} : { devCommand: context.devCommand }),
+        ...(undefined === parsed.url ? {} : { suppliedUrl: parsed.url }),
+    }, (line) => io.print(line)).then((outcome) => {
+        // One object, so an agent reads a result instead of interpreting a report.
+        if (true === parsed.json) {
+            process.stdout.write(`${JSON.stringify(outcome, null, 2)}\n`);
+            if (!outcome.ok)
+                process.exit(1);
+            return;
+        }
+        io.print('');
+        // The precondition for everything the closing asks for, printed on the path that could not say
+        // it. An agent client reads its MCP server list when it STARTS and never re-reads it, so on the
+        // run that first registers Reticle the `reticle_*` tools are not in the session that just asked
+        // for them -- and this path closes by telling that session to call `reticle_act_and_wait`.
+        // `restartHint` has said this for a long time and is printed only when init stops at the files.
+        if (true === result.mcpNewlyRegistered) {
+            io.print('Reticle was registered with your agent by this run, and an agent reads its tool list only ' +
+                'when it starts: the `reticle_*` tools are NOT in this session yet. Restart it first — ' +
+                '`npx @reticlehq/server init --relaunch` prints the exact resume command for Claude Code ' +
+                'and Codex. Once per machine.');
+            io.print('');
+        }
+        if (outcome.ok && !outcome.flowSaved) {
+            // Success, and no flow. Saying "a flow was driven" here would replace a wrong exit code with
+            // a wrong sentence, which is the worse of the two: the exit code is read by CI and the
+            // sentence is read by a person deciding whether their app is verified. It is not.
+            io.print(`✓ ${outcome.url ?? 'the app'} is instrumented and connected — but NOT verified.`);
+            for (const [i, step] of outcome.fallback.entries())
+                io.print(`   ${String(i + 1)}. ${step}`);
+            return;
+        }
+        if (outcome.ok) {
+            io.print(`✓ setup complete — ${outcome.url ?? 'the app'} is instrumented and a flow was driven.`);
+            // A passing flow shows the mechanism working. What the run SAW is the part nobody can get for
+            // themselves, and it deserves a line of its own rather than a paragraph that gets skimmed.
+            io.print('  Read the FINDINGS above before moving on: a flow can pass with a failed request or a ' +
+                'console error behind it, and that is the app, not the check.');
+            return;
+        }
+        // A run that produced no verdict did not succeed, and the exit code is the one place a caller
+        // reads that without parsing anything.
+        io.print('⚠ setup did not finish. To carry on from here:');
+        for (const [i, step] of outcome.fallback.entries())
+            io.print(`   ${i + 1}. ${step}`);
+        process.exit(1);
+    });
+}

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

@@ -0,0 +1,63 @@
+/**
+ * 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 type { CandidateSession } from './session-pick.js';
+import type { PageProbe } from './probe/page-probe.js';
+/** The dev server this process started, and the only one it will ever stop. */
+export declare class OwnedDevServer {
+    private child;
+    private buffer;
+    private lastOutputAt;
+    private handedOver;
+    start(command: string, cwd: string, env: Readonly<Record<string, string>>): void;
+    /** The process group leader, for a caller that has to clean up what it handed over. */
+    pid(): number | undefined;
+    output(): string;
+    exited(): boolean;
+    quietForMs(): number;
+    /** Ports anything in this server's process tree is listening on. */
+    listeningPorts(): number[];
+    /** 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(): void;
+    stop(): void;
+}
+/**
+ * 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.
+ *
+ * On loopback, the announced host is tried first and the other loopback families follow when it
+ * misses — so an IPv6-only Vite that printed `127.0.0.1` still counts as served (#884).
+ */
+export declare function probePage(url: string): Promise<PageProbe>;
+/** Sessions the daemon is holding, in the shape the picker reads. */
+export declare function listSessions(port: number): Promise<CandidateSession[]>;
+/** Whether this project has a saved flow, wherever the project keeps one. */
+export declare function flowsSaved(roots: readonly string[]): boolean;
+/** On PATH at all. The separate question of whether it RUNS is asked by chooseDriver. */
+export declare function binaryExists(bin: string): boolean;
+/** Whether a directory looks like a project setup has already wired. */
+export declare function alreadyWired(dir: string): boolean;

package/dist/command/setup/node-effects.js

@@ -0,0 +1,225 @@
+/**
+ * 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 '../daemon/binding/daemon-status-probe.js';
+import { descendants, parseLsofPorts, parseNetstatListeners, parseWmicProcesses, } from './terminal/listeners.js';
+import { loopbackProbeUrls } from './probe/loopback-probe-urls.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.
+ *
+ * On loopback, the announced host is tried first and the other loopback families follow when it
+ * misses — so an IPv6-only Vite that printed `127.0.0.1` still counts as served (#884).
+ */
+export async function probePage(url) {
+    const candidates = loopbackProbeUrls(url);
+    let sawTlsRefused = false;
+    for (const candidate of candidates) {
+        try {
+            const res = await fetch(candidate, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+            const body = await res.text();
+            const sdkInPage = /@reticlehq|@reticle-connect|reticle-dev/.test(body);
+            // Only stamp reachedUrl when we had to leave the announcement — callers that already have
+            // the working URL should not rewrite it for a no-op.
+            return candidate === url
+                ? { served: true, sdkInPage }
+                : { served: true, sdkInPage, reachedUrl: candidate };
+        }
+        catch (err) {
+            const message = String(err?.cause?.message ??
+                err?.message ??
+                '');
+            if (/certificate|SELF_SIGNED|DEPTH_ZERO|ERR_TLS|unable to verify/i.test(message)) {
+                sawTlsRefused = true;
+            }
+        }
+    }
+    return { served: false, sdkInPage: false, ...(sawTlsRefused ? { tlsRefused: true } : {}) };
+}
+/** 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/command/setup/probe/page-probe.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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;
+    /**
+     * The URL that actually answered, when the announced host missed and a loopback sibling did not.
+     * Callers that open a browser or wait on a session should prefer this over the announcement (#884).
+     */
+    readonly reachedUrl?: string | 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;
+/**
+ * What the page looks like once it has had its short chance to come up.
+ *
+ * The wait before opening a browser used to retry on `SDK_MISSING` and on nothing else, so a
+ * first probe of `NOT_SERVED` left the loop at once and the window was refused on ONE sample.
+ * That refusal is right for a url that will never answer and wrong for one that is still
+ * starting, and the two are identical at the first probe.
+ *
+ * Measured on the install gate's Nuxt scaffold: "nothing is serving" and "Not opening a
+ * browser", then two lines later "http://localhost:3000/ is served". The dev server came up
+ * during the phase, the window was never opened, no session could appear, and `init` exited 1
+ * on a correct install. Nothing about it is Nuxt-specific; it is the slowest scaffold here and
+ * any cold start slower than the first probe loses the same race.
+ *
+ * So both unfinished states wait: NOT_SERVED because the server may still be starting, and
+ * SDK_MISSING because the bundle may still be arriving. Whatever is true when the window closes
+ * is the answer, and a url that never answers is still refused -- by then it has been asked
+ * repeatedly rather than once.
+ *
+ * A function rather than a loop inside `runSetupPhases`, because the caller polls the same
+ * `probePage` 1,500 times before reaching this point and a test of the decision cannot get near
+ * it through that. Here it takes a probe and a clock and answers in three lines of setup.
+ */
+export declare function findingBeforeOpen(probe: () => Promise<PageProbe>, clock: {
+    readonly now: () => number;
+    readonly sleep: (ms: number) => Promise<void>;
+}, windowMs: number, pollMs: number): Promise<PageFinding>;

package/dist/command/setup/probe/page-probe.js

@@ -0,0 +1,89 @@
+/**
+ * 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:
+            // This used to end "so it loaded and returned early", which is a claim about a code path this
+            // check cannot see — and at least one real occurrence was the opposite. On a Windows install
+            // gate cell the page console read "could not open a websocket to ws://localhost:<port>, 3
+            // attempts, all failed": the SDK dialled three times and the socket failed, having returned
+            // early from nothing. What is knowable here is that the SDK is present and no session arrived.
+            return (`The SDK IS in the page at ${url} and never dialled the bridge: a localhost guard, a ` +
+                'production-only check, a bridge port that differs on the two sides, or `localhost` ' +
+                'resolving to IPv6 where the daemon is only on IPv4 — `npx @reticlehq/server doctor` names ' +
+                'that last one, and the page console names the first three.');
+    }
+}
+/**
+ * What the page looks like once it has had its short chance to come up.
+ *
+ * The wait before opening a browser used to retry on `SDK_MISSING` and on nothing else, so a
+ * first probe of `NOT_SERVED` left the loop at once and the window was refused on ONE sample.
+ * That refusal is right for a url that will never answer and wrong for one that is still
+ * starting, and the two are identical at the first probe.
+ *
+ * Measured on the install gate's Nuxt scaffold: "nothing is serving" and "Not opening a
+ * browser", then two lines later "http://localhost:3000/ is served". The dev server came up
+ * during the phase, the window was never opened, no session could appear, and `init` exited 1
+ * on a correct install. Nothing about it is Nuxt-specific; it is the slowest scaffold here and
+ * any cold start slower than the first probe loses the same race.
+ *
+ * So both unfinished states wait: NOT_SERVED because the server may still be starting, and
+ * SDK_MISSING because the bundle may still be arriving. Whatever is true when the window closes
+ * is the answer, and a url that never answers is still refused -- by then it has been asked
+ * repeatedly rather than once.
+ *
+ * A function rather than a loop inside `runSetupPhases`, because the caller polls the same
+ * `probePage` 1,500 times before reaching this point and a test of the decision cannot get near
+ * it through that. Here it takes a probe and a clock and answers in three lines of setup.
+ */
+export async function findingBeforeOpen(probe, clock, windowMs, pollMs) {
+    const readyBy = clock.now() + windowMs;
+    let finding = readPage(await probe());
+    while ((PageFinding.SDK_MISSING === finding || PageFinding.NOT_SERVED === finding) &&
+        clock.now() < readyBy) {
+        await clock.sleep(pollMs);
+        finding = readPage(await probe());
+    }
+    return finding;
+}