@reticlehq/server 3.8.2 → 3.10.0

package/dist/command/setup/bringup/static-page-server.js

@@ -8,22 +8,29 @@
  * starts `npm run dev`, and the rest of setup (wait, open, prove the connect) runs unchanged.
  *
  * It is run as its own process (`node static-page-server.js --dir <app>`), not inside init, because it
- * has to outlive init exactly like any handed-over dev server. It imports nothing but Node, so the
- * built file runs on its own.
+ * has to outlive init exactly like any handed-over dev server. It imports only Node and
+ * `@reticlehq/init`, so the built file runs on its own.
+ *
+ * It adds the connect snippet to each HTML page it serves, so init does not edit the file the user
+ * hands over (#1544). The file on disk stays byte-identical.
  *
  * Loopback only, on both families: a page served to the LAN would publish the pairing token the
  * snippet carries.
  */
-import { existsSync, readFile, statSync } from 'node:fs';
+import { existsSync, readFile, readFileSync, statSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { extname, join, resolve, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { connectArg, projectIdOf, withStaticSnippet } from '@reticlehq/init';
 export const STATIC_PAGE_INDEX = 'index.html';
 /** Where the search for a free port starts when none is given — clear of Vite's 5173 run. */
 export const STATIC_PAGE_FIRST_PORT = 5500;
 const PORT_SEARCH_SPAN = 50;
 const DIR_FLAG = '--dir';
 const PORT_FLAG = '--port';
+const BRIDGE_PORT_FLAG = '--bridge-port';
+const PROJECT_CONFIG = '.reticle.json';
+const HTML_EXTENSION = '.html';
 const LOOPBACK_V4 = '127.0.0.1';
 const LOOPBACK_V6 = '::1';
 const ANNOUNCED_HOST = 'localhost';
@@ -54,8 +61,9 @@ function fileFor(root, rawUrl) {
         return null;
     }
     const target = resolve(root, `.${path}`);
-    if (target !== root && !target.startsWith(`${root}${sep}`))
+    if (target !== root && !target.startsWith(`${root}${sep}`)) {
         return null;
+    }
     const file = path.endsWith('/') ? join(target, STATIC_PAGE_INDEX) : target;
     try {
         return statSync(file).isFile() ? file : null;
@@ -64,6 +72,27 @@ function fileFor(root, rawUrl) {
         return null;
     }
 }
+/**
+ * The connect literal for the page in `root`: the bridge port, and the project id its `.reticle.json`
+ * names. The same literal init wrote into the page before #1544.
+ */
+export function staticPageConnect(root, bridgePort) {
+    let config;
+    try {
+        config = readFileSync(join(root, PROJECT_CONFIG), 'utf8');
+    }
+    catch {
+        config = null;
+    }
+    return connectArg(bridgePort, projectIdOf(config));
+}
+/** The body to send: an HTML page gets the connect snippet, unless it already connects. */
+function servedBody(file, body, connect) {
+    if (undefined === connect || HTML_EXTENSION !== extname(file).toLowerCase()) {
+        return body;
+    }
+    return withStaticSnippet(body.toString('utf8'), connect) ?? body;
+}
 function listen(server, port, host) {
     return new Promise((ok, fail) => {
         server.once('error', fail);
@@ -93,7 +122,7 @@ export async function startStaticPageServer(opts) {
                 'content-type': CONTENT_TYPES[extname(file).toLowerCase()] ?? FALLBACK_TYPE,
                 'cache-control': 'no-store',
             });
-            res.end(body);
+            res.end(servedBody(file, body, opts.connect));
         });
     };
     const v4 = createServer(handler);
@@ -121,8 +150,9 @@ export async function startStaticPageServer(opts) {
         url: `http://${ANNOUNCED_HOST}:${String(bound)}/`,
         close: async () => {
             await closeServer(v4);
-            if (hasV6)
+            if (hasV6) {
                 await closeServer(v6);
+            }
         },
     };
 }
@@ -131,10 +161,12 @@ export async function startStaticPageServer(opts) {
  * that page. Quoted so an app path with a space survives the shell.
  */
 export function staticPageDevCommand(opts) {
-    if (!opts.isStaticPage || !existsSync(join(opts.appDir, STATIC_PAGE_INDEX)))
+    if (!opts.isStaticPage || !existsSync(join(opts.appDir, STATIC_PAGE_INDEX))) {
         return undefined;
+    }
     const script = fileURLToPath(import.meta.url).replace(/\.ts$/, '.js');
-    return `"${process.execPath}" "${script}" ${DIR_FLAG} "${opts.appDir}"`;
+    const bridge = undefined === opts.bridgePort ? '' : ` ${BRIDGE_PORT_FLAG} ${String(opts.bridgePort)}`;
+    return `"${process.execPath}" "${script}" ${DIR_FLAG} "${opts.appDir}"${bridge}`;
 }
 function flag(argv, name) {
     const at = argv.indexOf(name);
@@ -144,7 +176,9 @@ function flag(argv, name) {
 if (undefined !== process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
     const dir = flag(process.argv, DIR_FLAG) ?? process.cwd();
     const port = Number(flag(process.argv, PORT_FLAG) ?? STATIC_PAGE_FIRST_PORT);
-    startStaticPageServer({ root: dir, port }).then((server) => process.stdout.write(`serving ${dir}\n  Local: ${server.url}\n`), (err) => {
+    const bridgePort = flag(process.argv, BRIDGE_PORT_FLAG);
+    const connect = undefined === bridgePort ? undefined : staticPageConnect(dir, Number(bridgePort));
+    startStaticPageServer({ root: dir, port, connect }).then((server) => process.stdout.write(`serving ${dir}\n  Local: ${server.url}\n`), (err) => {
         process.stderr.write(`static page server: ${String(err)}\n`);
         process.exit(1);
     });

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

@@ -1,6 +1,7 @@
 import { homedir } from 'node:os';
 import { spanSync } from '../../../trace.js';
 import { hookBinFor } from '../../cli/hook/hook-fast.js';
+import { mcpLauncher } from '../mcp-launcher.js';
 import { reportInitOutcome } from '../../../telemetry/init-telemetry.js';
 import { reportOnboardingStep } from '../../../telemetry/onboarding-funnel.js';
 import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../../portal/bridge/pairing-token.js';
@@ -44,6 +45,7 @@ export function serverInitHost() {
         hookBin() {
             return hookBinFor(homedir(), process.platform);
         },
+        mcpLauncher,
         insideClaudeCode() {
             return CLAUDE_CODE_MARKER_VALUE === process.env[CLAUDE_CODE_MARKER_ENV];
         },

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

@@ -53,7 +53,12 @@ interface InitRuntimeArgs {
 interface RuntimePrintIo {
     readonly print: (line: string) => void;
 }
+/**
+ * Print the "Your agents:" block, and return the bounded wait for the agents to connect. `mayWait`
+ * false: the wait is a no-op. The caller adds the terminal check. See `agentsBlock`.
+ */
+export type AgentsBlockPort = (print: (line: string) => void, mayWait: boolean) => () => Promise<void>;
 export declare function continueAfterInit(parsed: InitRuntimeArgs, result: InitResult, io: RuntimePrintIo, cwd: string, 
 /** init's ending once the connection is proved: coverage and the agent prompt. See `FirstFlowPort`. */
-firstFlow?: FirstFlowPort): Promise<void>;
+firstFlow?: FirstFlowPort, agentsBlock?: AgentsBlockPort): Promise<void>;
 export {};

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

@@ -7,7 +7,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+import { InitConfirmation, OnboardingPhase, OnboardingStop, RETICLE_DEFAULT_PORT, } from '@reticlehq/core';
 import { COMMUNITY_HINT, FEEDBACK_HINT, Framework, InitFailure, } from '@reticlehq/init';
 import { confirmInstall, nodeConfirmDeps } from '../terminal/confirm.js';
 import { writeLicenseKey } from '../license-key.js';
@@ -24,11 +24,14 @@ 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';
+import { reportOnboardingStop } from '../../../telemetry/onboarding-funnel.js';
 /** Claude Code marks every process it spawns with this variable set to this value. */
 const CLAUDE_CODE_ENV = 'CLAUDECODE';
 const CLAUDE_CODE_MARKER = '1';
 /** How often the runtime phases look again: fast enough not to be the wait, slow enough to be free. */
 const POLL_MS = 250;
+/** The step an agent without the `reticle_*` tools cannot take. */
+const FIRST_LOOK_STEP = 'first_look';
 /**
  * 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
@@ -47,8 +50,9 @@ const NEXT_APP_CONNECT = ['app', 'src/app'].flatMap((d) => ['tsx', 'jsx', 'js'].
  * names chunks, not modules, so it stays silent.
  */
 export function htmlCarriesSdk(framework, exists) {
-    if (HTML_CARRIES_SDK.has(framework))
+    if (HTML_CARRIES_SDK.has(framework)) {
         return true;
+    }
     return Framework.NEXT === framework && NEXT_APP_CONNECT.some(exists);
 }
 /** Registration is global MCP wiring, so both flags that disown it are read here. */
@@ -68,8 +72,9 @@ const licenseIo = {
  * thing as an install working.
  */
 function printRelaunch(parsed, io, cwd) {
-    if (true !== parsed.relaunch)
+    if (true !== parsed.relaunch) {
         return;
+    }
     io.print(relaunchDecision({
         ...(undefined === process.env['CLAUDE_CODE_SESSION_ID']
             ? {}
@@ -82,13 +87,15 @@ function printRelaunch(parsed, io, cwd) {
 }
 export async function continueAfterInit(parsed, result, io, cwd, 
 /** init's ending once the connection is proved: coverage and the agent prompt. See `FirstFlowPort`. */
-firstFlow) {
+firstFlow, agentsBlock) {
     const port = parsed.port ?? RETICLE_DEFAULT_PORT;
     const stop = () => {
-        if (true === parsed.keepGoing)
+        if (true === parsed.keepGoing) {
             process.exitCode = 1;
-        else
+        }
+        else {
             process.exit(1);
+        }
     };
     // 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.
@@ -114,16 +121,19 @@ firstFlow) {
             registerOtherAgents(io.print);
         }
         return confirmInstall(result, io, nodeConfirmDeps(port)).then(() => {
-            if (true === parsed.json)
+            if (true === parsed.json) {
                 process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-            if (!result.ok)
+            }
+            if (!result.ok) {
                 stop();
+            }
         });
     }
     // 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)
+        if (spaced) {
             io.print('');
+        }
         io.print(FEEDBACK_HINT);
     };
     // `init` deferred its outcome to this phase, so every exit below reports it, and only once: the
@@ -131,8 +141,9 @@ firstFlow) {
     // would double the funnel this event exists to measure.
     let outcomeReported = false;
     const reportOnce = (init) => {
-        if (outcomeReported)
+        if (outcomeReported) {
             return;
+        }
         outcomeReported = true;
         reportInitOutcome(init);
     };
@@ -140,11 +151,13 @@ firstFlow) {
     if (context === undefined) {
         // Nothing was established, so there is nothing to run against. init has already said why, and
         // the outcome it deferred (a failed dependency install, usually) is reported here or nowhere.
-        if (result.outcome !== undefined)
+        if (result.outcome !== undefined) {
             reportOnce(result.outcome);
+        }
         ask();
-        if (true === parsed.json)
+        if (true === parsed.json) {
             process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        }
         stop();
         return;
     }
@@ -188,6 +201,9 @@ firstFlow) {
     // A Ctrl-C during the wait ends the process with no `finally`, so the outcome is reported from the
     // signal itself. The send is detached, so it survives the exit that follows.
     const releaseInterrupt = reportOnInterrupt(() => reportFailure(InitFailure.INTERRUPTED));
+    // The wait for the agents runs last, after the interrupt handler is gone: a Ctrl+C that skips the
+    // wait is not a failed init.
+    let waitForAgents = () => Promise.resolve();
     return runSetupCommand({
         appDir: context.appDir,
         invokedAt: cwd,
@@ -217,19 +233,27 @@ firstFlow) {
         // 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".
         ...(() => {
-            if (undefined !== context.devCommand)
+            if (undefined !== context.devCommand) {
                 return { devCommand: context.devCommand };
-            if (undefined !== parsed.url)
+            }
+            if (undefined !== parsed.url) {
                 return {};
+            }
             const devCommand = staticPageDevCommand({
                 appDir: context.appDir,
                 isStaticPage: Framework.HTML === context.framework,
+                // The server adds the connect snippet to the page, so init left the file alone (#1544).
+                bridgePort: port,
             });
             return undefined === devCommand ? {} : { devCommand, devCommandIsStaticPage: true };
         })(),
         ...(undefined === parsed.url ? {} : { suppliedUrl: parsed.url }),
         // So setup can tell which port the dev server will take, before it starts one (#1377).
         framework: context.framework,
+        // So a dev-server stop names the Vite step init could not do (#1263).
+        ...(undefined === context.pendingViteConfig
+            ? {}
+            : { pendingViteConfig: context.pendingViteConfig }),
     }, (line) => io.print(line))
         .then(async (outcome) => {
         if (result.outcome !== undefined) {
@@ -249,16 +273,18 @@ firstFlow) {
                     outcome.reachedPhase === SetupPhase.DEV_SERVER
                         ? InitFailure.DEV_SERVER
                         : InitFailure.APP_CONNECTION;
-                if (outcome.stop !== undefined)
+                if (outcome.stop !== undefined) {
                     init.stop = outcome.stop;
+                }
             }
             reportOnce(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`);
-            if (!outcome.ok)
+            if (!outcome.ok) {
                 stop();
+            }
             return;
         }
         io.print('');
@@ -274,7 +300,18 @@ firstFlow) {
         });
         if (undefined !== restart) {
             io.print(restart);
+            // The same block and wait as `reticle setup mcp`. No wait for a failed setup, or inside
+            // `reticle connect`, which signs in next.
+            if (agentsBlock !== undefined) {
+                waitForAgents = agentsBlock(io.print, outcome.ok && true !== parsed.keepGoing);
+            }
             io.print('');
+            // The agent cannot take its first look until it restarts. Detached: init exits soon.
+            reportOnboardingStop({
+                phase: OnboardingPhase.ONBOARD,
+                step: FIRST_LOOK_STEP,
+                stop: OnboardingStop.AGENT_NOT_RESTARTED,
+            }, { detach: true });
         }
         if (outcome.ok && !outcome.flowSaved) {
             // Success, and no flow. Saying "a flow was driven" here would replace a wrong exit code with
@@ -282,8 +319,9 @@ firstFlow) {
             // sentence is read by a person deciding whether their app is verified. It is not.
             // 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())
+            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);
             io.print(COMMUNITY_HINT);
@@ -299,15 +337,17 @@ firstFlow) {
         // 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())
+        for (const [i, step] of outcome.fallback.entries()) {
             io.print(`   ${i + 1}. ${step}`);
+        }
         ask();
         stop();
     }, (error) => {
         reportFailure(InitFailure.RUNTIME_ERROR);
         throw error;
     })
-        .finally(releaseInterrupt);
+        .finally(releaseInterrupt)
+        .then(() => waitForAgents());
 }
 const INTERRUPT_SIGNALS = ['SIGINT', 'SIGTERM'];
 /** 128 + the signal number, which is what a shell reports. */
@@ -319,14 +359,16 @@ function reportOnInterrupt(report) {
             report();
             // Before setup installs its own handler ours may be the only one, and a listener present
             // means Node no longer exits on the signal by itself: without this, Ctrl-C would be ignored.
-            if (1 === process.listenerCount(signal))
+            if (1 === process.listenerCount(signal)) {
                 process.exit(INTERRUPT_EXIT_CODE[signal]);
+            }
         };
         process.on(signal, handler);
         return { signal, handler };
     });
     return () => {
-        for (const { signal, handler } of handlers)
+        for (const { signal, handler } of handlers) {
             process.off(signal, handler);
+        }
     };
 }

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

@@ -0,0 +1,3 @@
+/** `bin/reticle.js`, from `dist/command/setup/mcp-launcher.js`. The real path, not a symlink. */
+export declare const CLI_BIN: string;
+export declare function mcpLauncher(): string | undefined;

package/dist/command/setup/mcp-launcher.js

@@ -0,0 +1,11 @@
+/**
+ * The bin that agent configs start the MCP server from, when this CLI is an install that stays on
+ * disk. Undefined for npx's cache and other run-once copies: see `installedLauncher` in init.
+ */
+import { fileURLToPath } from 'node:url';
+import { installedLauncher } from '@reticlehq/init';
+/** `bin/reticle.js`, from `dist/command/setup/mcp-launcher.js`. The real path, not a symlink. */
+export const CLI_BIN = fileURLToPath(new URL('../../../bin/reticle.js', import.meta.url));
+export function mcpLauncher() {
+    return installedLauncher(CLI_BIN);
+}

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

@@ -56,9 +56,10 @@ export declare class OwnedDevServer {
      *
      * 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.
+     * next `init` attaches to this server rather than starting a second one beside it. `bridgePort`
+     * is recorded too, so the next `init` on another port restarts this server instead.
      */
-    handOver(url?: string): void;
+    handOver(url?: string, bridgePort?: number): void;
     stop(): void;
 }
 /** Run a command and return what it printed, or '' if it failed to finish within `timeoutMs`. */

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

@@ -175,14 +175,20 @@ export class OwnedDevServer {
      *
      * 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.
+     * next `init` attaches to this server rather than starting a second one beside it. `bridgePort`
+     * is recorded too, so the next `init` on another port restarts this server instead.
      */
-    handOver(url) {
+    handOver(url, bridgePort) {
         this.handedOver = true;
         this.child?.unref();
         const pid = this.child?.pid;
         if (undefined !== url && undefined !== pid && undefined !== this.cwd) {
-            recordHandOver(this.logDir, { pid, url, appDir: this.cwd });
+            recordHandOver(this.logDir, {
+                pid,
+                url,
+                appDir: this.cwd,
+                ...(undefined === bridgePort ? {} : { bridgePort }),
+            });
         }
     }
     stop() {

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

@@ -8,5 +8,13 @@ export interface Progress {
     readonly urlSuppliedByCaller: boolean;
     readonly url?: string | undefined;
     readonly devCommand?: string | undefined;
+    /** The Vite config that init could not patch and left as a manual step. */
+    readonly pendingViteConfig?: string | undefined;
 }
+/**
+ * Said when the dev server stops after init left the Vite config unpatched (#1263).
+ *
+ * The dev server loads that config, so the step init already reported is the first cause to check.
+ */
+export declare const pendingViteConfigCause: (config: string) => string;
 export declare function remainingSteps(p: Progress): string[];

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

@@ -6,6 +6,13 @@
  * worked — it should pick up at the step that did not. Ordered, and only ever the REMAINING steps.
  */
 import { FEEDBACK_KIND_CHOICES } from '@reticlehq/core';
+/**
+ * Said when the dev server stops after init left the Vite config unpatched (#1263).
+ *
+ * The dev server loads that config, so the step init already reported is the first cause to check.
+ */
+export const pendingViteConfigCause = (config) => `init could not patch ${config}, and its ⚠ Vite plugin step is not done. ` +
+    'The dev server loads that config, so that step is the likely cause. Do it first.';
 const DOCS_INDEX = 'https://docs.reticle.sh/llms.txt';
 /**
  * The shell form on purpose, not `reticle_session { action: "feedback" }`.
@@ -21,6 +28,9 @@ export function remainingSteps(p) {
     if (!p.initDone) {
         steps.push('Run `npx @reticlehq/server@latest init` here, and fix every ⚠ it reports.');
     }
+    if (undefined !== p.pendingViteConfig) {
+        steps.push(`Do the ⚠ Vite plugin step that init printed: add \`reticle()\` to the plugins in ${p.pendingViteConfig}, or to the config that the dev server loads.`);
+    }
     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.`);
     }

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

@@ -158,6 +158,8 @@ export interface SetupInput {
     readonly suppliedUrl?: string | undefined;
     /** The port the dev command will take, when it is known. See probe/dev-port.ts. */
     readonly devPort?: number | undefined;
+    /** The Vite config init left for a manual step. A dev-server stop names it (#1263). */
+    readonly pendingViteConfig?: string | undefined;
     /**
      * The caller's own budget for the connect wait, when they named one.
      *

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

@@ -26,7 +26,7 @@ const WINDOWS_QUIET_MEANS_HUNG_MS = 3 * 60_000;
 const WINDOWS_QUIET_MEANS_HUNG_MS_APPLIES = 'win32' === process.platform;
 import { liveSessionOfProject, pickSession } from './session-pick.js';
 import { readPage, describePage, findingBeforeOpen, PageFinding, } from './probe/page-probe.js';
-import { remainingSteps } from './remaining-steps.js';
+import { pendingViteConfigCause, remainingSteps } from './remaining-steps.js';
 import { splitDevPortNote } from './probe/dev-port.js';
 import { AppShape, isDesktop, policyFor } from './desktop-shape.js';
 import { InitStop } from '@reticlehq/core/telemetry';
@@ -82,6 +82,7 @@ const asProgress = (input, o) => ({
     urlSuppliedByCaller: undefined !== input.suppliedUrl,
     ...(undefined === o.url ? {} : { url: o.url }),
     ...(undefined === input.devCommand ? {} : { devCommand: input.devCommand }),
+    ...(undefined === input.pendingViteConfig ? {} : { pendingViteConfig: input.pendingViteConfig }),
 });
 /** The connect step a web page stopped at. A bundle-connect page's HTML never shows the SDK. */
 const connectStop = (finding, htmlCarriesSdk) => {
@@ -215,6 +216,10 @@ export async function runSetupPhases(input, fx) {
                 if (WaitVerdict.DEAD === verdict) {
                     const busy = portBusyMessage(fx.devServerOutput());
                     note(busy ?? devServerDiedMessage(fx.devServerOutput()));
+                    // A busy port is its own cause. Any other exit can come from the config init left alone.
+                    if (undefined === busy && undefined !== input.pendingViteConfig) {
+                        note(pendingViteConfigCause(input.pendingViteConfig));
+                    }
                     const step = undefined === busy ? InitStop.DEV_SERVER_EXITED : InitStop.PORT_BUSY;
                     return stop(input, SetupPhase.DEV_SERVER, { stop: step }, notes);
                 }
@@ -231,6 +236,9 @@ export async function runSetupPhases(input, fx) {
                             ? `The dev server did not become ready${within}. `
                             : `The dev server stopped making progress before ${watching} became ready. `) +
                         'Check its log, increase --timeout for a slow build, or pass --url with the address it serves.');
+                    if (undefined !== input.pendingViteConfig) {
+                        note(pendingViteConfigCause(input.pendingViteConfig));
+                    }
                     const step = undefined === watching ? InitStop.NO_URL : InitStop.NOT_READY;
                     return stop(input, SetupPhase.DEV_SERVER, { stop: step }, notes);
                 }