@reticlehq/server 3.9.0 → 3.10.1

package/dist/command/daemon/daemon.js

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { homedir } from 'node:os';
+import { homedir, uptime } from 'node:os';
 import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, openSync, closeSync, readdirSync, statSync, renameSync, writeSync, } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { daemonRegistryFileName, DaemonSpawnMethod, ReticleEnv, } from '@reticlehq/core';
@@ -155,13 +155,42 @@ export function discoverDaemonPort() {
     }
     return found;
 }
+/**
+ * When the machine last booted, in epoch ms. A pidfile written before it names no daemon: every
+ * process from before the boot is gone, and its pid may now belong to anything.
+ */
+function lastBootMs() {
+    // The clock is read at this I/O boundary, as the other timestamps in this file are.
+    return Date.now() - uptime() * 1000;
+}
+/**
+ * Does this pidfile name a daemon that is still running?
+ *
+ * The pid must be alive AND the file must be newer than the last boot. A pid alone is not enough:
+ * the OS reuses pids, and after a reboot a pidfile named an unrelated Bluetooth service on Windows.
+ * The port was free, but serve skipped the start because that pid was alive, and the daemon never
+ * came up. A file whose age cannot be read is judged by its pid alone, as before.
+ */
+export function pidFileIsLive(path, pid, pidAlive, bootMs = lastBootMs) {
+    if (!pidAlive(pid)) {
+        return false;
+    }
+    let writtenMs;
+    try {
+        writtenMs = statSync(path).mtimeMs;
+    }
+    catch {
+        return true;
+    }
+    return writtenMs >= bootMs();
+}
 /**
  * Sweep ~/.reticle for daemon-<port>.pid files whose process is no longer alive and delete them, so a
  * crashed daemon never leaves a stale pidfile that confuses discovery or makes a port look "taken".
  * Returns the ports reclaimed. `home` and `pidAlive` are injectable for testing (default to the real
  * ~/.reticle and the process.kill(pid,0) liveness probe).
  */
-export function reclaimStaleDaemons(home = reticleStateHome(), pidAlive = isAlive) {
+export function reclaimStaleDaemons(home = reticleStateHome(), pidAlive = isAlive, bootMs = lastBootMs) {
     const reclaimed = [];
     let files;
     try {
@@ -184,7 +213,7 @@ export function reclaimStaleDaemons(home = reticleStateHome(), pidAlive = isAliv
         catch {
             pid = null; // unreadable pidfile counts as stale
         }
-        if (null === pid || !pidAlive(pid)) {
+        if (null === pid || !pidFileIsLive(path, pid, pidAlive, bootMs)) {
             try {
                 unlinkSync(path);
                 removeDaemonRegistry(Number(match[1])); // drop the sidecar discovery entry too
@@ -287,8 +316,10 @@ export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpaw
     }
     catch {
         const existing = readPid(port, deps.home);
-        if (existing !== null && deps.pidAlive(existing))
+        if (existing !== null &&
+            pidFileIsLive(pidFilePath, existing, (pid) => deps.pidAlive(pid), deps.bootTimeMs)) {
             return false;
+        }
         // This branch IS the crash detection — its own comment has always said so ("a stale pidfile from
         // a crashed daemon is reclaimed"), it just never said it out loud. Captured before the unlink,
         // because after it there is no trace left that the previous daemon died at all.

package/dist/command/daemon/lifetime/death-cause.js

@@ -11,7 +11,7 @@
  * counts. Never a message, because a message can carry the user's paths.
  */
 import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
-import { DaemonEnd, NODE_ERROR_CODE } from '@reticlehq/core';
+import { DaemonEnd, DaemonStartupError, NODE_ERROR_CODE } from '@reticlehq/core';
 import { DAEMON_HEARTBEAT_EVENT, classifyDaemonLife } from './heartbeat.js';
 import { DAEMON_START_FAILED_EVENT } from './startup-failure.js';
 /**
@@ -45,6 +45,14 @@ function lastErrorCode(text) {
     const code = codes.filter((c) => c !== undefined && !NOT_A_CODE.has(c)).at(-1);
     return code !== undefined && NODE_ERROR_CODE.test(code) ? code : undefined;
 }
+/** The stage of a failed start, only when it is a member of the closed list. */
+function startupStage(v) {
+    return Object.values(DaemonStartupError).find((stage) => stage === v);
+}
+/** The code field of a failed start, only when it has the shape of a Node error code. */
+function codeField(v) {
+    return 'string' === typeof v && NODE_ERROR_CODE.test(v) ? v : undefined;
+}
 const count = (v) => 'number' === typeof v && Number.isInteger(v) && 0 <= v ? v : undefined;
 /**
  * Read the cause of death of the daemon that started at `startedMs`.
@@ -97,13 +105,24 @@ export function deathCauseFromLog(text, startedMs, nowMs) {
         }
     }
     const failed = ours.findLast((l) => l.event === DAEMON_START_FAILED_EVENT);
-    const error = ('string' === typeof failed?.['error'] ? lastErrorCode(failed['error']) : undefined) ??
+    const stage = startupStage(failed?.['stage']);
+    if (stage !== undefined) {
+        cause.startupError = stage;
+    }
+    const error = codeField(failed?.['code']) ??
+        ('string' === typeof failed?.['error'] ? lastErrorCode(failed['error']) : undefined) ??
         // Raw lines before this daemon's first line belong to the daemon before it, unless this one
         // wrote no line at all, which is a crash before its first log line.
         lastErrorCode((0 < ours.length ? rawInOurs : rawAfterLastLine).join('\n'));
     if (error !== undefined) {
         cause.error = error;
     }
+    // No line of its own, and a Node error after the last line of the daemon before it: Node stopped
+    // this daemon before its code could write anything, for example on a module that did not load.
+    if (0 === ours.length && error !== undefined) {
+        cause.end = DaemonEnd.START_FAILED;
+        cause.startupError = DaemonStartupError.BEFORE_LOG;
+    }
     return cause;
 }
 /** How much of the end of a daemon log the next start reads. The last beats and a stack fit. */

package/dist/command/daemon/lifetime/heartbeat.js

@@ -19,6 +19,7 @@
  */
 import { DaemonEnd } from '@reticlehq/core';
 import { DAEMON_LOG_TRUNCATED_EVENT, guardDaemonLog } from './log-cap.js';
+import { DAEMON_START_FAILED_EVENT } from './startup-failure.js';
 /** The event name a beat carries. One `grep` separates liveness from everything else in the file. */
 export const DAEMON_HEARTBEAT_EVENT = 'reticle_daemon_alive';
 /** Written by installExitTrace when the process exits through Node. */
@@ -132,8 +133,12 @@ export function classifyDaemonLife(lines, nowMs) {
             };
     }
     const last = beats.at(-1);
-    if (last === undefined)
-        return { end: DaemonEnd.UNKNOWN };
+    if (last === undefined) {
+        // A daemon that logged a failed start never beat. Without this branch its death was `unknown`,
+        // which said "no evidence" about a log that held the cause (#2043).
+        const failed = lines.some((l) => l.event === DAEMON_START_FAILED_EVENT);
+        return { end: failed ? DaemonEnd.START_FAILED : DaemonEnd.UNKNOWN };
+    }
     const everyMs = 'number' === typeof last.everyMs ? last.everyMs : DAEMON_HEARTBEAT_MS;
     const silentForMs = nowMs - last.t;
     return silentForMs > everyMs * MISSED_BEATS_TOLERATED

package/dist/command/daemon/lifetime/startup-failure.d.ts

@@ -1,5 +1,33 @@
+import { DaemonStartupError } from '@reticlehq/core';
 /** The structured log event emitted when the daemon child cannot start. */
 export declare const DAEMON_START_FAILED_EVENT = "reticle_daemon_start_failed";
+type LogFn = (event: string, fields: Record<string, unknown>) => void;
+/**
+ * Write a failed start to the daemon log, before the process exits (#2043).
+ *
+ * The line has three fields. `error` is the message, for the person who reads the log and for
+ * `readDaemonStartupCause`. `code` is the Node error code, read from the error and not from the
+ * message. `stage` is where the start failed: a failed bind is always `listen`, whatever the caller
+ * gave. The next start reads `code` and `stage` into `daemon_died_unclean`. The message stays here.
+ */
+export declare function recordStartupFailure(log: LogFn, error: unknown, stage: DaemonStartupError): void;
+/** The parts of `process` that the startup trap uses. */
+export interface StartupTrapTarget {
+    prependListener(event: 'uncaughtException' | 'unhandledRejection', handler: (value: unknown) => void): void;
+    off(event: 'uncaughtException' | 'unhandledRejection', handler: (value: unknown) => void): void;
+}
+/**
+ * Write a throw or a rejection that stops the start to the daemon log.
+ *
+ * Before the daemon is ready, the process crash guard owns these two events. It writes one sentence
+ * to stderr and exits, and that sentence has no event name and no code. So a daemon that died in
+ * its first 100 ms left a log that no reader could classify. This trap runs FIRST (it is prepended)
+ * and writes one structured line. It does not exit: the crash guard still does that.
+ *
+ * Returns a disposer. Call it when the daemon is ready, because from then on the daemon's own
+ * resilience handlers own these events, and a crash is no longer a failed start.
+ */
+export declare function installStartupTrap(proc: StartupTrapTarget, log: LogFn): () => void;
 /**
  * Return the most recent startup cause written by this launch attempt.
  *
@@ -9,3 +37,4 @@ export declare const DAEMON_START_FAILED_EVENT = "reticle_daemon_start_failed";
  * unavailable logs are best-effort misses; the caller still has its generic fallback diagnosis.
  */
 export declare function readDaemonStartupCause(path: string, sinceMs: number): string | undefined;
+export {};

package/dist/command/daemon/lifetime/startup-failure.js

@@ -1,6 +1,68 @@
 import { readFileSync } from 'node:fs';
+import { DaemonStartupError, NODE_ERROR_CODE } from '@reticlehq/core';
 /** The structured log event emitted when the daemon child cannot start. */
 export const DAEMON_START_FAILED_EVENT = 'reticle_daemon_start_failed';
+/** The `syscall` that Node puts on the error of a failed bind. */
+const LISTEN_SYSCALL = 'listen';
+/** The Node error code on `error`, or undefined. Only a value that has the shape of a code. */
+function nodeErrorCode(error) {
+    if ('object' !== typeof error || null === error) {
+        return undefined;
+    }
+    const code = error.code;
+    return 'string' === typeof code && NODE_ERROR_CODE.test(code) ? code : undefined;
+}
+function isListenError(error) {
+    if ('object' !== typeof error || null === error) {
+        return false;
+    }
+    return LISTEN_SYSCALL === error.syscall;
+}
+/**
+ * Write a failed start to the daemon log, before the process exits (#2043).
+ *
+ * The line has three fields. `error` is the message, for the person who reads the log and for
+ * `readDaemonStartupCause`. `code` is the Node error code, read from the error and not from the
+ * message. `stage` is where the start failed: a failed bind is always `listen`, whatever the caller
+ * gave. The next start reads `code` and `stage` into `daemon_died_unclean`. The message stays here.
+ */
+export function recordStartupFailure(log, error, stage) {
+    const code = nodeErrorCode(error);
+    log(DAEMON_START_FAILED_EVENT, {
+        stage: isListenError(error) ? DaemonStartupError.LISTEN : stage,
+        ...(code === undefined ? {} : { code }),
+        error: error instanceof Error ? error.message : String(error),
+    });
+}
+/**
+ * Write a throw or a rejection that stops the start to the daemon log.
+ *
+ * Before the daemon is ready, the process crash guard owns these two events. It writes one sentence
+ * to stderr and exits, and that sentence has no event name and no code. So a daemon that died in
+ * its first 100 ms left a log that no reader could classify. This trap runs FIRST (it is prepended)
+ * and writes one structured line. It does not exit: the crash guard still does that.
+ *
+ * Returns a disposer. Call it when the daemon is ready, because from then on the daemon's own
+ * resilience handlers own these events, and a crash is no longer a failed start.
+ */
+export function installStartupTrap(proc, log) {
+    let written = false;
+    const trap = (stage) => (value) => {
+        if (written) {
+            return;
+        }
+        written = true;
+        recordStartupFailure(log, value, stage);
+    };
+    const onException = trap(DaemonStartupError.UNCAUGHT_EXCEPTION);
+    const onRejection = trap(DaemonStartupError.UNHANDLED_REJECTION);
+    proc.prependListener('uncaughtException', onException);
+    proc.prependListener('unhandledRejection', onRejection);
+    return () => {
+        proc.off('uncaughtException', onException);
+        proc.off('unhandledRejection', onRejection);
+    };
+}
 /**
  * Return the most recent startup cause written by this launch attempt.
  *

package/dist/command/setup/bringup/dev-server-files.d.ts

@@ -13,6 +13,7 @@ declare const HandedOverSchema: z.ZodObject<{
     pid: z.ZodNumber;
     url: z.ZodString;
     appDir: z.ZodString;
+    bridgePort: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type HandedOver = z.infer<typeof HandedOverSchema>;
 /**
@@ -32,6 +33,14 @@ export declare function handedOverUrl(dir: string, appDir: string, deps: {
     alive: (pid: number) => boolean;
     answers: (url: string) => Promise<boolean>;
 }): Promise<string | undefined>;
+/**
+ * True when the live server `init` handed over for `appDir` was started for a daemon port other than
+ * `bridgePort`. Attaching to it leaves the page dialling the old port, even when no daemon on that
+ * port is left to retire. A record with no port gives false, as before.
+ */
+export declare function handedOverToOtherPort(dir: string, appDir: string, bridgePort: number, deps: {
+    alive: (pid: number) => boolean;
+}): boolean;
 /**
  * Stop the server `init` handed over for `appDir`, and forget it. True when one was stopped.
  *

package/dist/command/setup/bringup/dev-server-files.js

@@ -34,6 +34,11 @@ const HandedOverSchema = z.object({
     pid: z.number().int().positive(),
     url: z.string().min(1),
     appDir: z.string().min(1),
+    /**
+     * The daemon port the server was started for. Absent in a record from an older build. Reticle's
+     * static server adds a snippet that dials this port, so it cannot follow a port move.
+     */
+    bridgePort: z.number().int().positive().optional(),
 });
 /**
  * Written when `init` leaves a server running, so the next `init` can attach to it.
@@ -70,6 +75,18 @@ export async function handedOverUrl(dir, appDir, deps) {
         return undefined;
     return (await deps.answers(record.url)) ? record.url : undefined;
 }
+/**
+ * True when the live server `init` handed over for `appDir` was started for a daemon port other than
+ * `bridgePort`. Attaching to it leaves the page dialling the old port, even when no daemon on that
+ * port is left to retire. A record with no port gives false, as before.
+ */
+export function handedOverToOtherPort(dir, appDir, bridgePort, deps) {
+    const record = readRecord(join(dir, recordName(appDir)));
+    if (undefined === record || record.appDir !== appDir || !deps.alive(record.pid)) {
+        return false;
+    }
+    return undefined !== record.bridgePort && record.bridgePort !== bridgePort;
+}
 /**
  * Stop the server `init` handed over for `appDir`, and forget it. True when one was stopped.
  *

package/dist/command/setup/bringup/static-page-server.d.ts

@@ -8,8 +8,11 @@
  * 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.
@@ -21,9 +24,16 @@ export interface StaticPageServer {
     readonly url: string;
     close(): Promise<void>;
 }
+/**
+ * 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 declare function staticPageConnect(root: string, bridgePort: number): string;
 export declare function startStaticPageServer(opts: {
     root: string;
     port: number;
+    /** The connect literal to add to each HTML page. Absent: pages are served as written. */
+    connect?: string | undefined;
 }): Promise<StaticPageServer>;
 /**
  * The command setup runs for a page with no dev server of its own, or undefined when this is not
@@ -32,4 +42,6 @@ export declare function startStaticPageServer(opts: {
 export declare function staticPageDevCommand(opts: {
     appDir: string;
     isStaticPage: boolean;
+    /** The daemon port the added snippet dials. Absent: the page is served as written. */
+    bridgePort?: number | undefined;
 }): string | undefined;

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-runtime.js

@@ -7,7 +7,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { InitConfirmation, OnboardingPhase, OnboardingStop, RETICLE_DEFAULT_PORT, } from '@reticlehq/core';
+import { InitConfirmation, InitStop, 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';
@@ -85,6 +85,11 @@ function printRelaunch(parsed, io, cwd) {
     }).message);
     io.print('');
 }
+/** The dev-server stops caused by the machine, not the app: the files init wrote are right. */
+const WIRED_WHEN_STOPPED_AT = new Set([
+    InitStop.PORT_BUSY,
+    InitStop.SPLIT_LOOPBACK,
+]);
 export async function continueAfterInit(parsed, result, io, cwd, 
 /** init's ending once the connection is proved: coverage and the agent prompt. See `FirstFlowPort`. */
 firstFlow, agentsBlock) {
@@ -242,14 +247,28 @@ firstFlow, agentsBlock) {
             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) => {
+        // The files are written before the app starts. When the app could not be reached for a reason
+        // of the machine, not of the app (its port was taken, or it answered on one loopback address
+        // and not the other), the project is wired and not confirmed yet: not a failed install.
+        // A dev server that exits, hangs or does not exist, and a failure to connect, still fail.
+        const wiredNotStarted = !outcome.ok &&
+            outcome.reachedPhase === SetupPhase.DEV_SERVER &&
+            undefined !== outcome.stop &&
+            WIRED_WHEN_STOPPED_AT.has(outcome.stop);
         if (result.outcome !== undefined) {
             const init = {
                 ...result.outcome,
@@ -259,6 +278,14 @@ firstFlow, agentsBlock) {
                 delete init.reason;
                 init.confirmation = InitConfirmation.CONNECTED;
             }
+            else if (wiredNotStarted) {
+                init.ok = true;
+                delete init.reason;
+                init.confirmation = InitConfirmation.DEV_SERVER_NOT_STARTED;
+                if (outcome.stop !== undefined) {
+                    init.stop = outcome.stop;
+                }
+            }
             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.
@@ -275,7 +302,11 @@ firstFlow, agentsBlock) {
         }
         // 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`);
+            const answer = wiredNotStarted ? { ...outcome, ok: true, confirmed: false } : outcome;
+            process.stdout.write(`${JSON.stringify(answer, null, 2)}\n`);
+            if (wiredNotStarted) {
+                return;
+            }
             if (!outcome.ok) {
                 stop();
             }
@@ -328,6 +359,16 @@ firstFlow, agentsBlock) {
             io.print(COMMUNITY_HINT);
             return;
         }
+        if (wiredNotStarted) {
+            io.print('✓ Reticle is wired into this app. Its dev server did not start, so the connection is not ' +
+                'confirmed yet. To confirm it:');
+            for (const [i, step] of outcome.fallback.entries()) {
+                io.print(`   ${String(i + 1)}. ${step}`);
+            }
+            io.print(`   ${String(outcome.fallback.length + 1)}. Run \`reticle status\`: it lists the app when it connects.`);
+            ask();
+            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:');

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.
      *