@reticlehq/server 3.3.0 → 3.5.0

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

@@ -6,19 +6,30 @@
  * every command harder to read.
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+import { FEEDBACK_HINT, Framework, InitFailure } from '@reticlehq/init';
 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 { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../../portal/bridge/pairing-token.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';
+import { staticPageDevCommand } from '../bringup/static-page-server.js';
+import { SetupPhase } from '../run-setup.js';
+import { reportInitOutcome } from '../../../telemetry/init-telemetry.js';
 /** How often the runtime phases look again: fast enough not to be the wait, slow enough to be free. */
 const POLL_MS = 250;
+/**
+ * The shapes whose served HTML carries the SDK marker: Vite injects it into index.html, and a plain
+ * HTML page has the snippet pasted in. Everything else connects from the JS bundle, where a fetch
+ * of the document can never see it. See `htmlCarriesSdk` in run-setup.ts.
+ */
+const HTML_CARRIES_SDK = new Set([Framework.VITE, Framework.HTML]);
 /** Registration is global MCP wiring, so both flags that disown it are read here. */
 function wantsAgents(parsed) {
     return false !== parsed.agents && false !== parsed.mcp;
@@ -50,9 +61,9 @@ function printRelaunch(parsed, io, cwd) {
 }
 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) {
+    // Real installs persist the key whichever way setup ends. A preview must leave .env and
+    // .gitignore untouched, just as it leaves project wiring and agent configuration untouched.
+    if (!parsed.dryRun && undefined !== parsed.licenseKey) {
         const written = writeLicenseKey(cwd, parsed.licenseKey, licenseIo);
         io.print(written.message);
     }
@@ -70,18 +81,35 @@ export async function continueAfterInit(parsed, result, io, cwd) {
         // 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))
+        if (!parsed.dryRun && true === parsed.filesOnly && wantsAgents(parsed)) {
             registerOtherAgents(io.print);
+        }
         return confirmInstall(result, io, nodeConfirmDeps(port)).then(() => {
+            if (true === parsed.json)
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
             if (!result.ok)
                 process.exit(1);
         });
     }
+    // From here on init left the ask to us, so it is the last thing on every exit below.
+    const ask = (spaced = true) => {
+        if (spaced)
+            io.print('');
+        io.print(FEEDBACK_HINT);
+    };
     const context = result.context;
     if (context === undefined) {
         // Nothing was established, so there is nothing to run against. init has already said why.
+        ask();
+        if (true === parsed.json)
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
         process.exit(1);
     }
+    const reportFailure = (reason) => {
+        if (result.outcome !== undefined) {
+            reportInitOutcome({ ...result.outcome, ok: false, reason });
+        }
+    };
     // 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.
     //
@@ -97,15 +125,26 @@ export async function continueAfterInit(parsed, result, io, cwd) {
     // 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);
+    const refusal = bridgeOccupied(await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }).catch((error) => {
+        reportFailure(InitFailure.RUNTIME_ERROR);
+        throw error;
+    }), port);
     if (refusal !== undefined) {
+        reportFailure(InitFailure.BRIDGE_OCCUPIED);
         io.print(refusal);
+        ask();
+        if (true === parsed.json) {
+            process.stdout.write(`${JSON.stringify({ ok: false, reason: InitFailure.BRIDGE_OCCUPIED }, null, 2)}\n`);
+        }
         process.exit(1);
     }
     return runSetupCommand({
         appDir: context.appDir,
         invokedAt: cwd,
         bridgePort: port,
+        // Read here because this is the layer that already owns the bridge: setup opens a lease over
+        // the daemon's MCP transport for `--no-open`, and that transport is gated on this token.
+        pairingToken: readOrCreatePairingTokenSync(defaultPairingTokenDir()),
         env: collectEnv(parsed.env ?? []),
         openBrowser: false !== parsed.open,
         registerAgents: wantsAgents(parsed),
@@ -116,11 +155,46 @@ export async function continueAfterInit(parsed, result, io, cwd) {
         // keeps deciding, so nobody who passed nothing waits less than they used to.
         ...(undefined === parsed.timeoutSeconds
             ? {}
-            : { connectBudgetMs: parsed.timeoutSeconds * 1000 }),
+            : {
+                connectBudgetMs: parsed.timeoutSeconds * 1000,
+                startupBudgetMs: parsed.timeoutSeconds * 1000,
+            }),
         pollMs: POLL_MS,
-        ...(undefined === context.devCommand ? {} : { devCommand: context.devCommand }),
+        htmlCarriesSdk: HTML_CARRIES_SDK.has(context.framework),
+        // A plain page with no dev script gets Reticle's own static server, so the page is actually
+        // served and the connect can be proved, instead of stopping at "start the app yourself".
+        ...(() => {
+            const devCommand = context.devCommand ??
+                (undefined === parsed.url
+                    ? staticPageDevCommand({
+                        appDir: context.appDir,
+                        isStaticPage: Framework.HTML === context.framework,
+                    })
+                    : undefined);
+            return undefined === devCommand ? {} : { devCommand };
+        })(),
         ...(undefined === parsed.url ? {} : { suppliedUrl: parsed.url }),
     }, (line) => io.print(line)).then((outcome) => {
+        if (result.outcome !== undefined) {
+            const init = {
+                ...result.outcome,
+                ok: outcome.ok,
+            };
+            if (outcome.ok) {
+                delete init.reason;
+                init.confirmation = InitConfirmation.CONNECTED;
+            }
+            else {
+                // A failed startup does not establish whether a daemon or instrumented page exists.
+                // Keep the watcher's no_daemon/no_session/no_page classifications for observed facts.
+                delete init.confirmation;
+                init.reason =
+                    outcome.reachedPhase === SetupPhase.DEV_SERVER
+                        ? InitFailure.DEV_SERVER
+                        : InitFailure.APP_CONNECTION;
+            }
+            reportInitOutcome(init);
+        }
         // 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`);
@@ -145,9 +219,12 @@ export async function continueAfterInit(parsed, result, io, cwd) {
             // 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.`);
+            // The connect already said "connected, nothing verified yet" and listed what to do next;
+            // repeating it here was the same sentence twice, three lines apart.
             for (const [i, step] of outcome.fallback.entries())
                 io.print(`   ${String(i + 1)}. ${step}`);
+            // Already spaced by the blank line above when nothing was listed.
+            ask(0 < outcome.fallback.length);
             return;
         }
         if (outcome.ok) {
@@ -156,6 +233,7 @@ export async function continueAfterInit(parsed, result, io, cwd) {
             // 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.');
+            ask();
             return;
         }
         // A run that produced no verdict did not succeed, and the exit code is the one place a caller
@@ -163,6 +241,10 @@ export async function continueAfterInit(parsed, result, io, cwd) {
         io.print('⚠ setup did not finish. To carry on from here:');
         for (const [i, step] of outcome.fallback.entries())
             io.print(`   ${i + 1}. ${step}`);
+        ask();
         process.exit(1);
+    }, (error) => {
+        reportFailure(InitFailure.RUNTIME_ERROR);
+        throw error;
     });
 }

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

@@ -15,31 +15,42 @@ 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 readonly logDir;
     private child;
-    private buffer;
-    private lastOutputAt;
+    private log;
+    private cwd;
+    private startedAt;
     private handedOver;
+    constructor(logDir?: string);
+    /**
+     * Start it with its output going to a bounded log, through a supervisor that outlives `init`.
+     *
+     * Not a pipe into THIS process. A pipe's read end belonged to `init`; once it exited nobody held
+     * it, and the server's next write (a compile error, an HMR line, SvelteKit's first warning) was an
+     * EPIPE that killed it: "it connected, then the app went away". And not a bare file either, which
+     * has no ceiling: an upstream echo loop grew one to 2.9 GB in five minutes. The supervisor reads
+     * the server's pipes for as long as they are open and rotates the file past a cap — see
+     * dev-server-log-cap.ts. It is the process group leader, so `pid()` and `stop()` cover both.
+     */
     start(command: string, cwd: string, env: Readonly<Record<string, string>>): void;
+    /** Where the server's output goes, for the line that hands it over. */
+    logPath(): string | undefined;
     /** The process group leader, for a caller that has to clean up what it handed over. */
     pid(): number | undefined;
     output(): string;
     exited(): boolean;
+    /** Since the log last grew, which is since the server last printed anything. */
     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.
+     * Leave the server running and stop holding it. After this, `stop()` does nothing.
      *
-     * 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.
+     * Only `unref` is needed: the output is the supervisor's, so no pipe of ours holds the event loop
+     * (`init` once printed "setup complete" and hung on one). `url` is recorded beside the log, so the
+     * next `init` attaches to this server rather than starting a second one beside it.
      */
-    handOver(): void;
+    handOver(url?: string): void;
     stop(): void;
 }
 /**
@@ -50,9 +61,11 @@ export declare class OwnedDevServer {
  * 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).
+ * is REFUSED — so an IPv6-only Vite that printed `127.0.0.1` still counts as served (#884). Only
+ * refused: a timeout means the right server is slow, and the caller polls again on the same host.
+ * See `isAddressMiss` for the Next 16 first run that hopping on a timeout broke.
  */
-export declare function probePage(url: string): Promise<PageProbe>;
+export declare function probePage(url: string, timeoutMs?: number): 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. */

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

@@ -12,60 +12,101 @@
  * listening indefinitely.
  */
 import { spawn, spawnSync } from 'node:child_process';
-import { Socket } from 'node:net';
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isAlive } from '../daemon/daemon.js';
+import { DEV_SERVER_LOG_CAP_BYTES, ROTATED_SUFFIX } from './bringup/dev-server-log-cap.js';
+import { devServerLogName, recordHandOver, sweepDeadDevServers, } from './bringup/dev-server-files.js';
 import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { reticleStateHome } from '../daemon/daemon.js';
 import { descendants, parseLsofPorts, parseNetstatListeners, parseWmicProcesses, } from './terminal/listeners.js';
-import { loopbackProbeUrls } from './probe/loopback-probe-urls.js';
+import { isAddressMiss, loopbackProbeUrls } from './probe/loopback-probe-urls.js';
 const WINDOWS = 'win32' === process.platform;
+/** Astro otherwise daemonizes automatically when it detects an agent terminal. */
+const ASTRO_DEV_BACKGROUND_ENV = 'ASTRO_DEV_BACKGROUND';
 /** 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 supervisor that owns the server's output and keeps its log bounded. */
+const LOG_CAP_SCRIPT = fileURLToPath(new URL('./bringup/dev-server-log-cap.js', import.meta.url));
 /** The dev server this process started, and the only one it will ever stop. */
 export class OwnedDevServer {
+    logDir;
     child;
-    buffer = '';
-    lastOutputAt = Date.now();
+    log;
+    cwd;
+    startedAt = Date.now();
     handedOver = false;
+    constructor(logDir = reticleStateHome()) {
+        this.logDir = logDir;
+    }
+    /**
+     * Start it with its output going to a bounded log, through a supervisor that outlives `init`.
+     *
+     * Not a pipe into THIS process. A pipe's read end belonged to `init`; once it exited nobody held
+     * it, and the server's next write (a compile error, an HMR line, SvelteKit's first warning) was an
+     * EPIPE that killed it: "it connected, then the app went away". And not a bare file either, which
+     * has no ceiling: an upstream echo loop grew one to 2.9 GB in five minutes. The supervisor reads
+     * the server's pipes for as long as they are open and rotates the file past a cap — see
+     * dev-server-log-cap.ts. It is the process group leader, so `pid()` and `stop()` cover both.
+     */
     start(command, cwd, env) {
-        const child = spawn(command, {
+        mkdirSync(this.logDir, { recursive: true });
+        // Logs of servers that are gone, from every project, so the state home stops growing a file
+        // per app ever started. This one's are replaced below anyway.
+        sweepDeadDevServers(this.logDir, { alive: isAlive, now: Date.now(), keep: cwd });
+        const log = join(this.logDir, devServerLogName(cwd));
+        // Unlinked rather than truncated: a previous server for this project may still hold the old
+        // file open, and truncating under it would interleave its lines into this run's output.
+        rmSync(log, { force: true });
+        rmSync(`${log}${ROTATED_SUFFIX}`, { force: true });
+        this.child = spawn(process.execPath, [LOG_CAP_SCRIPT, log, String(DEV_SERVER_LOG_CAP_BYTES), 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 },
+            // Nothing of ours: the supervisor holds the server's pipes, and init holds none of its.
+            stdio: 'ignore',
+            // Reticle already provides the detached supervisor. Astro's agent auto-backgrounding
+            // would escape its process group and leave the recorded handover PID pointing at a dead
+            // launcher, so re-init and cleanup could no longer find or stop the actual server.
+            env: { ...process.env, ...env, [ASTRO_DEV_BACKGROUND_ENV]: '1' },
         });
-        const collect = (chunk) => {
-            this.buffer += String(chunk);
-            this.lastOutputAt = Date.now();
-        };
-        child.stdout?.on('data', collect);
-        child.stderr?.on('data', collect);
-        this.child = child;
+        this.log = log;
+        this.cwd = cwd;
+        this.startedAt = Date.now();
+    }
+    /** Where the server's output goes, for the line that hands it over. */
+    logPath() {
+        return this.log;
     }
     /** 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;
+        if (undefined === this.log)
+            return '';
+        try {
+            return readFileSync(this.log, 'utf8');
+        }
+        catch {
+            return '';
+        }
     }
     exited() {
         return undefined !== this.child && null !== this.child.exitCode;
     }
+    /** Since the log last grew, which is since the server last printed anything. */
     quietForMs() {
-        return Date.now() - this.lastOutputAt;
+        let lastOutputAt = this.startedAt;
+        try {
+            if (undefined !== this.log)
+                lastOutputAt = Math.max(lastOutputAt, statSync(this.log).mtimeMs);
+        }
+        catch {
+            /* not written yet */
+        }
+        return Date.now() - lastOutputAt;
     }
     /** Ports anything in this server's process tree is listening on. */
     listeningPorts() {
@@ -90,24 +131,20 @@ export class OwnedDevServer {
             `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.
+     * Leave the server running and stop holding it. After this, `stop()` does nothing.
      *
-     * 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.
+     * Only `unref` is needed: the output is the supervisor's, so no pipe of ours holds the event loop
+     * (`init` once printed "setup complete" and hung on one). `url` is recorded beside the log, so the
+     * next `init` attaches to this server rather than starting a second one beside it.
      */
-    handOver() {
+    handOver(url) {
         this.handedOver = true;
-        const child = this.child;
-        releasePipe(child?.stdout);
-        releasePipe(child?.stderr);
-        child?.unref();
+        this.child?.unref();
+        const pid = this.child?.pid;
+        if (undefined !== url && undefined !== pid && undefined !== this.cwd) {
+            recordHandOver(this.logDir, { pid, url, appDir: this.cwd });
+        }
     }
     stop() {
         const child = this.child;
@@ -164,14 +201,16 @@ function windowsProcessPairs() {
  * 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).
+ * is REFUSED — so an IPv6-only Vite that printed `127.0.0.1` still counts as served (#884). Only
+ * refused: a timeout means the right server is slow, and the caller polls again on the same host.
+ * See `isAddressMiss` for the Next 16 first run that hopping on a timeout broke.
  */
-export async function probePage(url) {
+export async function probePage(url, timeoutMs = PROBE_TIMEOUT_MS) {
     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 res = await fetch(candidate, { signal: AbortSignal.timeout(timeoutMs) });
             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
@@ -187,6 +226,8 @@ export async function probePage(url) {
             if (/certificate|SELF_SIGNED|DEPTH_ZERO|ERR_TLS|unable to verify/i.test(message)) {
                 sawTlsRefused = true;
             }
+            if (!isAddressMiss(err))
+                break;
         }
     }
     return { served: false, sdkInPage: false, ...(sawTlsRefused ? { tlsRefused: true } : {}) };

package/dist/command/setup/probe/loopback-probe-urls.d.ts

@@ -16,3 +16,10 @@
  * family-split problem, and inventing alternates would probe the wrong machine.
  */
 export declare function loopbackProbeUrls(url: string): string[];
+/**
+ * Whether a failed fetch was refused at the connection level on this address.
+ *
+ * `fetch` wraps the socket error as `cause`; with happy-eyeballs that cause is an AggregateError of
+ * one error per address tried, and it is a miss only when every one of them was.
+ */
+export declare function isAddressMiss(err: unknown): boolean;

package/dist/command/setup/probe/loopback-probe-urls.js

@@ -50,3 +50,43 @@ export function loopbackProbeUrls(url) {
         push(host);
     return out;
 }
+/**
+ * Errors that mean "nothing is listening at THIS address", so another loopback family may be.
+ *
+ * Anything else, a timeout above all, means the address was right and the server is slow. A cold
+ * Next 16 first compile takes long enough to time a probe out, and treating that as a family miss
+ * walked on to `127.0.0.1`/`[::1]`, which answered first, became the app url, and is an origin Next
+ * refuses its dev resources to: no hydration, so the SDK never ran and init blamed the page.
+ */
+const ADDRESS_MISS_CODES = new Set([
+    'ECONNREFUSED',
+    'EADDRNOTAVAIL',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'ENETUNREACH',
+    'EHOSTUNREACH',
+    'EAFNOSUPPORT',
+]);
+function field(value, key) {
+    return 'object' === typeof value && null !== value ? Reflect.get(value, key) : undefined;
+}
+const codeOf = (value) => {
+    const code = field(value, 'code');
+    return 'string' === typeof code ? code : undefined;
+};
+/**
+ * Whether a failed fetch was refused at the connection level on this address.
+ *
+ * `fetch` wraps the socket error as `cause`; with happy-eyeballs that cause is an AggregateError of
+ * one error per address tried, and it is a miss only when every one of them was.
+ */
+export function isAddressMiss(err) {
+    const cause = field(err, 'cause');
+    const direct = codeOf(cause);
+    if (undefined !== direct)
+        return ADDRESS_MISS_CODES.has(direct);
+    const errors = field(cause, 'errors');
+    if (!Array.isArray(errors) || 0 === errors.length)
+        return false;
+    return errors.every((e) => ADDRESS_MISS_CODES.has(codeOf(e) ?? ''));
+}

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

@@ -40,8 +40,13 @@ 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.
+ *
+ * `daemonSpoke`: the daemon already gave its account. Whether the page dialled is ITS fact (it
+ * sees every hello, including one it refused), so the SDK_PRESENT sentence then states only the
+ * page fact. Saying "never dialled the bridge" under "this daemon REFUSED the last page" contradicted
+ * the one piece of positive evidence in the run.
  */
-export declare function describePage(finding: PageFinding, url: string): string;
+export declare function describePage(finding: PageFinding, url: string, daemonSpoke?: boolean): string;
 /**
  * What the page looks like once it has had its short chance to come up.
  *
@@ -68,4 +73,10 @@ export declare function describePage(finding: PageFinding, url: string): string;
 export declare function findingBeforeOpen(probe: () => Promise<PageProbe>, clock: {
     readonly now: () => number;
     readonly sleep: (ms: number) => Promise<void>;
-}, windowMs: number, pollMs: number): Promise<PageFinding>;
+}, windowMs: number, pollMs: number, 
+/**
+ * The served HTML carries the SDK marker on this shape. When it does not (the connect is in the
+ * JS bundle), SDK_MISSING is the permanent state of a healthy page, and waiting for it to change
+ * only delays the window that would load the bundle.
+ */
+htmlCarriesSdk?: boolean): Promise<PageFinding>;

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

@@ -27,8 +27,16 @@ export function readPage(probe) {
 /**
  * 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.
+ *
+ * `daemonSpoke`: the daemon already gave its account. Whether the page dialled is ITS fact (it
+ * sees every hello, including one it refused), so the SDK_PRESENT sentence then states only the
+ * page fact. Saying "never dialled the bridge" under "this daemon REFUSED the last page" contradicted
+ * the one piece of positive evidence in the run.
  */
-export function describePage(finding, url) {
+export function describePage(finding, url, daemonSpoke = false) {
+    if (PageFinding.SDK_PRESENT === finding && daemonSpoke) {
+        return `The SDK IS in the page at ${url}; the daemon's account above says what became of it.`;
+    }
     switch (finding) {
         case PageFinding.NOT_SERVED:
             // Leads with the cause. The break-matrix asserts this phrasing because it is what a reader
@@ -77,10 +85,17 @@ export function describePage(finding, url) {
  * `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) {
+export async function findingBeforeOpen(probe, clock, windowMs, pollMs, 
+/**
+ * The served HTML carries the SDK marker on this shape. When it does not (the connect is in the
+ * JS bundle), SDK_MISSING is the permanent state of a healthy page, and waiting for it to change
+ * only delays the window that would load the bundle.
+ */
+htmlCarriesSdk = true) {
     const readyBy = clock.now() + windowMs;
     let finding = readPage(await probe());
-    while ((PageFinding.SDK_MISSING === finding || PageFinding.NOT_SERVED === finding) &&
+    while (((htmlCarriesSdk && PageFinding.SDK_MISSING === finding) ||
+        PageFinding.NOT_SERVED === finding) &&
         clock.now() < readyBy) {
         await clock.sleep(pollMs);
         finding = readPage(await probe());

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

@@ -51,6 +51,11 @@ export interface DaemonReason {
     /** The whole differential, recorded for the agent reading `--json`. Defaults to the lead. */
     readonly full?: string;
 }
+/** A lease this run opened for its connect proof, and the way to hand it back. */
+export interface OwnedBrowser {
+    readonly sessionId: string;
+    readonly release: () => Promise<void>;
+}
 export interface SetupEffects {
     /** Start the dev server. Resolves once started; the caller owns stopping it. */
     readonly startDevServer: (command: string, cwd: string) => Promise<void>;
@@ -79,8 +84,19 @@ export interface SetupEffects {
      * 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.
+     *
+     * It may resolve with the launcher's own failure, and that is used for exactly one thing: to ALSO
+     * open a Reticle-owned browser, so the proof does not depend on a window that may never appear.
+     * Adding a second source of a session is safe on a false alarm; cutting the wait was not.
+     */
+    readonly openBrowser: (url: string) => Promise<string | void>;
+    /**
+     * Open the url in a browser Reticle owns (a pooled lease), for a run with no system browser to
+     * lean on: `--no-open`, CI, a container, an agent. Optional: absent means no lease is attempted.
      */
-    readonly openBrowser: (url: string) => Promise<void>;
+    readonly openLease?: (url: string) => Promise<OwnedBrowser | {
+        readonly failed: string;
+    }>;
     readonly listSessions: () => Promise<CandidateSession[]>;
     /**
      * The daemon's own account of why nothing connected, if it can be asked.
@@ -101,6 +117,8 @@ export interface SetupEffects {
 }
 export interface SetupInput {
     readonly appDir: string;
+    /** This project's id, so a live tab of it can be told from another app's on the same url. */
+    readonly projectId?: string | undefined;
     readonly devCommand?: string | undefined;
     /** The app is already served here, so nothing is started. */
     readonly suppliedUrl?: string | undefined;
@@ -114,9 +132,18 @@ export interface SetupInput {
      * before setup could say what was wrong.
      */
     readonly connectBudgetMs?: number | undefined;
+    /** Explicit --timeout for startup; absent preserves the adaptive build wait. */
+    readonly startupBudgetMs?: number | undefined;
     readonly openBrowser: boolean;
     /** Web, Electron or Tauri. Desktop changes three things; see desktop-shape.ts. */
     readonly shape: AppShape;
+    /**
+     * The served HTML carries the SDK marker on this shape: Vite's index.html injection, or a plain
+     * HTML page with the snippet pasted in. Every other framework delivers the connect in the JS
+     * bundle, so "the SDK is NOT in the page" is the permanent state of a healthy page there, and
+     * saying it sent people to restart a dev server that was fine.
+     */
+    readonly htmlCarriesSdk: boolean;
     readonly phaseTimeoutMs: number;
     readonly pollMs: number;
 }