@reticlehq/server 2.8.0 → 2.9.0

package/dist/mcp/server-instructions.js

@@ -0,0 +1,56 @@
+import { SHARED_PARAM_GUIDANCE } from './shared-params.js';
+/**
+ * What every connected agent is told, before it has asked anything.
+ *
+ * The MCP `instructions` string lands in the agent's context at the handshake — no skill file, no
+ * restart, no action from the user. For an agent that arrived through a plugin listing or a pasted
+ * config block rather than through the skill, it is the ONLY thing Reticle ever says unprompted.
+ *
+ * It used to open on tool grammar. That is the right thing to say to an agent that has an app to
+ * point the tools at, and the wrong thing to say to one that does not — and in the field the
+ * overwhelming majority of daemons never see an app connect, never run a command and never call a
+ * tool. Those sessions are not agents failing a hard step. They are agents that were never asked to
+ * take an easy one: the MCP server registers itself in a single line of config, so a user reaches
+ * "the tools are here" without ever reaching "the app is wired", and nothing in that state reads as
+ * unfinished. Registering the server is the cheapest part of the product and it is the only part
+ * many installs ever complete.
+ *
+ * So the lead is state-dependent. A project that has never had an app connect is told the one thing
+ * it needs; a project that has is not nagged about a step it already took. The verdict discipline
+ * and the feedback ask are constant, because they matter in both states.
+ */
+/** The tools, and the rule that only two of them decide anything. Constant across both states. */
+const VERDICT_DISCIPLINE = `Reticle verifies a running web app from the inside: look (reticle_snapshot / reticle_query), act and prove in one hop (reticle_act_and_wait), observe (reticle_state / reticle_network / reticle_console), assert (reticle_assert). Verify a user-facing change against the real app before you call it done, and never weaken a check to make it pass.
+
+Only reticle_act_and_wait and reticle_assert produce a verdict. reticle_act and everything else move or read the app and prove nothing, so a drive that ends without one of those two has no result however many tools it used. Prefer reticle_act_and_wait({ ref, action, until }) — it names the expected consequence BEFORE the action, which is the difference between a check and a rationalisation. A verdict of verified:"unknown" is not a pass: it means Reticle drove the app and could not tell what happened. Report it as unknown.`;
+/**
+ * The first move, for a project no app has ever connected to.
+ *
+ * Deliberately concrete: the command, what it does to the app, and the call that confirms it. A
+ * general instruction to "set Reticle up" is the state these agents are already in — they have the
+ * tools and no app, and nothing tells them that combination is incomplete. It also names the dev
+ * server restart, because a plugin added to a config the running server already read is the single
+ * most common way this step half-succeeds.
+ */
+const FIRST_MOVE = `FIRST: no app has ever connected to Reticle in this project, so nothing here can be verified yet. Having these tools is not the same as being set up — the tools reach a daemon, and the daemon has nothing to look at until the app itself is instrumented.
+
+Fix that before anything else: run \`npx @reticlehq/server init\` in the project, then RESTART the dev server (a plugin added to a config the running server already read is not in the bundle), then load the app in a browser. Confirm with reticle_sessions — a session listed there is the proof, and until one appears no other tool can tell you anything about this app.`;
+/** The feedback ask. Constant: an agent that cannot get set up is the report we most need. */
+const FEEDBACK_ASK = `Feedback is first-class here, not a courtesy. Reticle is built FOR agents, so your experience is the only signal that decides what gets built or fixed — and it disappears when your context does. Send it with \`reticle_feedback\` the moment you notice, then carry on with your task:
+- Reticle broke, lied, or could not see something you needed (\`bug\` / \`gap\` / \`ambiguity\`).
+- You wished it could do something, or something works but costs too many calls (\`feature_request\` / \`improvement\`).
+- The install, the wiring, or the setup itself gave you trouble — including anything you had to work around by hand.
+
+Nothing is too minor, and a report costs one call. If the tools are unreachable (setup unfinished, daemon down), file the same report from the shell instead: \`reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"\`. Report defects in RETICLE — a bug you find in the app under test is Reticle working, and belongs in your answer to the user.`;
+/** The instructions this daemon should advertise, given what it knows about the project. */
+/**
+ * Instructions are sent ONCE at initialize; the tool surface is re-sent every turn. Measured on this
+ * server: 621 tokens here against 5,480 per turn there, so anything true of every tool belongs in
+ * this block rather than repeated across sixteen parameter descriptions. See shared-params.ts.
+ */
+export function buildServerInstructions(state) {
+    const base = state.previouslyConnected
+        ? `${VERDICT_DISCIPLINE}\n\n${FEEDBACK_ASK}`
+        : `${FIRST_MOVE}\n\n${VERDICT_DISCIPLINE}\n\n${FEEDBACK_ASK}`;
+    return `${base}\n\n${SHARED_PARAM_GUIDANCE}`;
+}

package/dist/mcp/shared-params.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Parameters that mean the same thing on every tool, documented ONCE instead of every turn.
+ *
+ * The advertised surface is re-sent on every turn; the MCP `instructions` block is sent once at
+ * initialize. Measured on this server: instructions cost 621 tokens total, the surface costs 5,480
+ * PER TURN — 87,672 over a 16-turn run. So a byte of prose moved from a parameter description into
+ * instructions is roughly 16x cheaper, and nothing is lost, because the text still reaches the model.
+ *
+ * `sessionId` is the clearest case: identical boilerplate on 16 tools, 2,076 bytes of the surface,
+ * re-explained on every turn to say the same thing it said last turn.
+ *
+ * This is deliberately NOT the `verify` experiment. That one removed the observation tools and
+ * measured what it cost: detection held but false alarms tripled, because evidence got expensive.
+ * This removes REPETITION, not evidence — every tool stays advertised and every observation stays
+ * one call away. Cost goes down; what the model can see does not change.
+ *
+ * The trade being made, stated: schema prose is expensive but sits adjacent to the call, while
+ * instructions are cheap but distant, and a client that drops `instructions` loses this text
+ * entirely. So the short forms below still have to be usable on their own — each one names the
+ * parameter's PURPOSE, and only the guidance moves.
+ */
+/** The short form left in the per-turn schema. Must still make sense with no instructions at all. */
+export declare const SHARED_PARAM_SHORT: Readonly<Record<string, string>>;
+/** The full text, sent once at initialize. Everything trimmed above is restated here. */
+export declare const SHARED_PARAM_GUIDANCE: string;
+/** Is this a parameter whose guidance now lives in the instructions block? */
+export declare function isSharedParam(name: string): boolean;

package/dist/mcp/shared-params.js

@@ -0,0 +1,36 @@
+/**
+ * Parameters that mean the same thing on every tool, documented ONCE instead of every turn.
+ *
+ * The advertised surface is re-sent on every turn; the MCP `instructions` block is sent once at
+ * initialize. Measured on this server: instructions cost 621 tokens total, the surface costs 5,480
+ * PER TURN — 87,672 over a 16-turn run. So a byte of prose moved from a parameter description into
+ * instructions is roughly 16x cheaper, and nothing is lost, because the text still reaches the model.
+ *
+ * `sessionId` is the clearest case: identical boilerplate on 16 tools, 2,076 bytes of the surface,
+ * re-explained on every turn to say the same thing it said last turn.
+ *
+ * This is deliberately NOT the `verify` experiment. That one removed the observation tools and
+ * measured what it cost: detection held but false alarms tripled, because evidence got expensive.
+ * This removes REPETITION, not evidence — every tool stays advertised and every observation stays
+ * one call away. Cost goes down; what the model can see does not change.
+ *
+ * The trade being made, stated: schema prose is expensive but sits adjacent to the call, while
+ * instructions are cheap but distant, and a client that drops `instructions` loses this text
+ * entirely. So the short forms below still have to be usable on their own — each one names the
+ * parameter's PURPOSE, and only the guidance moves.
+ */
+/** The short form left in the per-turn schema. Must still make sense with no instructions at all. */
+export const SHARED_PARAM_SHORT = {
+    sessionId: 'Target a specific tab. Omit unless you mean one — see instructions.',
+    since: 'Cursor from a prior reticle_act/reticle_observe.',
+    limit: 'Cap descriptors to the first N.',
+};
+/** The full text, sent once at initialize. Everything trimmed above is restated here. */
+export const SHARED_PARAM_GUIDANCE = 'Arguments that mean the same thing on every tool: `sessionId` — omit unless you mean a specific ' +
+    'tab; Reticle scopes to your project, prefers the active one, and refuses rather than guesses when ' +
+    'ambiguous. `since` — a cursor from a prior act/observe, bounding an observation to what came ' +
+    'after it. `limit` — caps returned descriptors, cutting tokens on broad queries.';
+/** Is this a parameter whose guidance now lives in the instructions block? */
+export function isSharedParam(name) {
+    return Object.hasOwn(SHARED_PARAM_SHORT, name);
+}

package/dist/project/reticle-dir.d.ts

@@ -13,6 +13,8 @@ export interface ReticleDirPaths {
     baselines: string;
     /**.../.reticle/project.json (cross-run outcome memory) */
     project: string;
+    /**.../.reticle/impact.json (what Reticle has done for this user, local only) */
+    impact: string;
     /**.../.reticle/visual (PNG baselines + diffs) */
     visual: string;
     /**.../.reticle/runs (verification-run artifacts) */

package/dist/project/reticle-dir.js

@@ -7,6 +7,7 @@ export function reticleDirPaths(root) {
         flows: join(root, ReticleDir.FLOWS_SUBDIR),
         baselines: join(root, ReticleDir.BASELINES_SUBDIR),
         project: join(root, ReticleDir.PROJECT_FILE),
+        impact: join(root, ReticleDir.IMPACT_FILE),
         visual: join(root, ReticleDir.VISUAL_SUBDIR),
         runs: join(root, ReticleDir.RUNS_SUBDIR),
         sessions: join(root, ReticleDir.SESSIONS_SUBDIR),

package/dist/session/connection-memory.d.ts

@@ -0,0 +1,59 @@
+/**
+ * One durable bit: has an app ever connected to Reticle on this port, for this project?
+ *
+ * `SessionManager.everConnected()` answers a narrower question than every reader of it assumed — it
+ * is scoped to the CURRENT PROCESS. Daemons are short-lived by design (they idle out and respawn),
+ * so a diagnosis built on that boolean tells a user whose app connected a minute ago that this
+ * install has never worked, and sends them looking for a missing config file that was always there.
+ * Reported repeatedly, and the confident phrasing is what made it expensive: "never seen one" reads
+ * as evidence about the install, not as a fact about a process that booted four seconds ago.
+ *
+ * Deliberately tiny: one JSON file per port under the daemon's state home, holding the set of
+ * projectIds that have connected. It is a HINT, so every failure mode here degrades to "we do not
+ * know" rather than throwing — a diagnostic that can crash the tool it is diagnosing is worse than
+ * no diagnostic at all.
+ */
+/**
+ * Record that a session connected. Best-effort — a daemon must never fail to serve a session
+ * because it could not write a hint about it.
+ */
+export declare function rememberConnected(stateDir: string, port: number, projectId: string | undefined): void;
+/**
+ * Whether an app has connected on this port before, for this project.
+ *
+ * An absent `projectId` asks the weaker question — "has ANY app connected on this port" — because
+ * that is the honest reading when the caller cannot name a project: the alternative is to answer
+ * "no" for a daemon that plainly has served apps, which is the same over-confident claim this file
+ * exists to remove.
+ */
+export declare function hasConnectedBefore(stateDir: string, port: number, projectId: string | undefined): boolean;
+/**
+ * Has an app connected before FOR THIS PROJECT — the question the first-move instructions ask.
+ *
+ * Separate from `hasConnectedBefore` because they are genuinely different questions and only one of
+ * them tolerates the untagged fallback. The no-session diagnosis wants "has this daemon ever served
+ * an app", and answering "no" there when it plainly has is the over-confident claim this file
+ * exists to remove. The first-move block claims something narrower and says so in its own first
+ * sentence: "no app has ever connected to Reticle IN THIS PROJECT".
+ *
+ * Deciding that narrower claim with the weaker question inverted it for exactly the population it
+ * was written for. An unwired project has no `.reticle.json`, so no projectId, so it fell into the
+ * untagged branch — which is true as soon as any app has ever connected on this port. On any
+ * machine where the default port has served anything at all, the guidance was suppressed and the
+ * agent was told the setup was done.
+ *
+ * So an absent projectId answers `false` here: a project with no Reticle identity has nothing
+ * recorded under another project's name that could be evidence about it. The cost of being wrong in
+ * this direction is one guidance block, read once at handshake, by a setup that is already working.
+ *
+ * KNOWN LIMIT, and the reason it is accepted rather than worked around. The WRITE side records the
+ * id the SDK supplied, while the read side asks `.reticle.json` — and the Vite plugin derives an id
+ * without writing that file. So a project wired by hand with the plugin and no `init` records a real
+ * id on every connect and reads `undefined` here forever, and is told at each handshake that nothing
+ * has connected. Two things make that tolerable: the block's own advice is to run `init`, which
+ * writes the file and heals the detection, so it is actionable rather than merely wrong; and the
+ * alternative — answering from the port — is the leak this function exists to close, which is the
+ * larger error by a wide margin. `no-session-watch` had already made exactly this call for its own
+ * diagnosis, which is why it now shares this function instead of keeping a second copy of the rule.
+ */
+export declare function hasProjectConnectedBefore(stateDir: string, port: number, projectId: string | undefined): boolean;

package/dist/session/connection-memory.js

@@ -0,0 +1,108 @@
+/**
+ * One durable bit: has an app ever connected to Reticle on this port, for this project?
+ *
+ * `SessionManager.everConnected()` answers a narrower question than every reader of it assumed — it
+ * is scoped to the CURRENT PROCESS. Daemons are short-lived by design (they idle out and respawn),
+ * so a diagnosis built on that boolean tells a user whose app connected a minute ago that this
+ * install has never worked, and sends them looking for a missing config file that was always there.
+ * Reported repeatedly, and the confident phrasing is what made it expensive: "never seen one" reads
+ * as evidence about the install, not as a fact about a process that booted four seconds ago.
+ *
+ * Deliberately tiny: one JSON file per port under the daemon's state home, holding the set of
+ * projectIds that have connected. It is a HINT, so every failure mode here degrades to "we do not
+ * know" rather than throwing — a diagnostic that can crash the tool it is diagnosing is worse than
+ * no diagnostic at all.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Sessions from an SDK old enough not to stamp a projectId still count, under this key. */
+const UNTAGGED = '(untagged)';
+/**
+ * Cap on remembered projects per port.
+ *
+ * A shared 4400 on a busy machine sees many projects over a week and this file is never garbage
+ * collected, so the set is bounded and oldest-out. The bit it answers is only ever used to soften a
+ * diagnosis, so losing the tail costs nothing.
+ */
+const MAX_REMEMBERED_PROJECTS = 32;
+function memoryPath(stateDir, port) {
+    return join(stateDir, `connected-${String(port)}.json`);
+}
+/** The remembered project ids for a port. Empty on absent, unreadable, or malformed state. */
+function read(stateDir, port) {
+    try {
+        const parsed = JSON.parse(readFileSync(memoryPath(stateDir, port), 'utf8'));
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((entry) => 'string' === typeof entry);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Record that a session connected. Best-effort — a daemon must never fail to serve a session
+ * because it could not write a hint about it.
+ */
+export function rememberConnected(stateDir, port, projectId) {
+    const key = projectId ?? UNTAGGED;
+    const known = read(stateDir, port);
+    if (known.includes(key))
+        return;
+    const next = [...known, key].slice(-MAX_REMEMBERED_PROJECTS);
+    try {
+        mkdirSync(stateDir, { recursive: true });
+        writeFileSync(memoryPath(stateDir, port), JSON.stringify(next), 'utf8');
+    }
+    catch {
+        // An unwritable state home is already reported elsewhere; it must not break the session path.
+    }
+}
+/**
+ * Whether an app has connected on this port before, for this project.
+ *
+ * An absent `projectId` asks the weaker question — "has ANY app connected on this port" — because
+ * that is the honest reading when the caller cannot name a project: the alternative is to answer
+ * "no" for a daemon that plainly has served apps, which is the same over-confident claim this file
+ * exists to remove.
+ */
+export function hasConnectedBefore(stateDir, port, projectId) {
+    const known = read(stateDir, port);
+    if (projectId === undefined)
+        return known.length > 0;
+    return known.includes(projectId);
+}
+/**
+ * Has an app connected before FOR THIS PROJECT — the question the first-move instructions ask.
+ *
+ * Separate from `hasConnectedBefore` because they are genuinely different questions and only one of
+ * them tolerates the untagged fallback. The no-session diagnosis wants "has this daemon ever served
+ * an app", and answering "no" there when it plainly has is the over-confident claim this file
+ * exists to remove. The first-move block claims something narrower and says so in its own first
+ * sentence: "no app has ever connected to Reticle IN THIS PROJECT".
+ *
+ * Deciding that narrower claim with the weaker question inverted it for exactly the population it
+ * was written for. An unwired project has no `.reticle.json`, so no projectId, so it fell into the
+ * untagged branch — which is true as soon as any app has ever connected on this port. On any
+ * machine where the default port has served anything at all, the guidance was suppressed and the
+ * agent was told the setup was done.
+ *
+ * So an absent projectId answers `false` here: a project with no Reticle identity has nothing
+ * recorded under another project's name that could be evidence about it. The cost of being wrong in
+ * this direction is one guidance block, read once at handshake, by a setup that is already working.
+ *
+ * KNOWN LIMIT, and the reason it is accepted rather than worked around. The WRITE side records the
+ * id the SDK supplied, while the read side asks `.reticle.json` — and the Vite plugin derives an id
+ * without writing that file. So a project wired by hand with the plugin and no `init` records a real
+ * id on every connect and reads `undefined` here forever, and is told at each handshake that nothing
+ * has connected. Two things make that tolerable: the block's own advice is to run `init`, which
+ * writes the file and heals the detection, so it is actionable rather than merely wrong; and the
+ * alternative — answering from the port — is the leak this function exists to close, which is the
+ * larger error by a wide margin. `no-session-watch` had already made exactly this call for its own
+ * diagnosis, which is why it now shares this function instead of keeping a second copy of the rule.
+ */
+export function hasProjectConnectedBefore(stateDir, port, projectId) {
+    if (projectId === undefined)
+        return false;
+    return hasConnectedBefore(stateDir, port, projectId);
+}

package/dist/session/dev-command.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The literal command that starts THIS project's dev server, read from the project's own scripts.
+ *
+ * The no-session diagnosis has always said "ask the human to start it (`npm run dev`)". That is a
+ * guess on two axes — the script name and the package manager — and a guessed command is worse than
+ * none: the agent runs it, gets an error about a missing script, and concludes the app is broken
+ * rather than that Reticle was wrong. So this reads, and returns nothing when it cannot read.
+ *
+ * Pure apart from one injected reader, so every case is a unit test rather than a temp directory.
+ */
+/** A dev script, as something an agent can actually run. */
+export interface DevCommand {
+    /** The literal shell command, e.g. `pnpm run dev`. */
+    command: string;
+    /** The package.json script it runs. */
+    script: string;
+    /** The port the script PINS, when it pins one. Absent means the tool picks — never a guess. */
+    port?: number;
+}
+/**
+ * The dev command for the project in `directory`, or undefined when there is not one to be sure of.
+ *
+ * `read` is injected so the whole decision is testable without a filesystem; the daemon uses the
+ * default disk reader.
+ */
+export declare function detectDevCommand(directory: string, read?: (path: string) => string | undefined): DevCommand | undefined;

package/dist/session/dev-command.js

@@ -0,0 +1,89 @@
+/**
+ * The literal command that starts THIS project's dev server, read from the project's own scripts.
+ *
+ * The no-session diagnosis has always said "ask the human to start it (`npm run dev`)". That is a
+ * guess on two axes — the script name and the package manager — and a guessed command is worse than
+ * none: the agent runs it, gets an error about a missing script, and concludes the app is broken
+ * rather than that Reticle was wrong. So this reads, and returns nothing when it cannot read.
+ *
+ * Pure apart from one injected reader, so every case is a unit test rather than a temp directory.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Script names checked, in order.
+ *
+ * `start` is last on purpose: in a Next or CRA app it is the PRODUCTION server, which serves a build
+ * with no dev-only SDK in it, so starting it would look like success and connect nothing. It is only
+ * reached when the project offers nothing better.
+ */
+const DEV_SCRIPTS = ['dev', 'develop', 'start'];
+/** Lockfile → package manager, in precedence order. Anything else is npm. */
+const LOCKFILES = [
+    { file: 'pnpm-lock.yaml', manager: 'pnpm' },
+    { file: 'yarn.lock', manager: 'yarn' },
+];
+const DEFAULT_PACKAGE_MANAGER = 'npm';
+const PACKAGE_JSON = 'package.json';
+/** `--port 4311` / `--port=4311`, the flag every dev server in this list accepts. */
+const PORT_FLAG = /--port[= ]\s*(\d+)/;
+/** `PORT=8080 remix dev` — the other half of how a project pins its port. */
+const PORT_ENV = /(?:^|\s)PORT=(\d+)/;
+/** Reads a file, or undefined if it is not there / not readable. */
+function readTextFile(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The port the script pins, when it pins one at all. */
+function pinnedPort(script) {
+    const match = PORT_FLAG.exec(script) ?? PORT_ENV.exec(script);
+    const digits = match?.[1];
+    if (digits === undefined)
+        return undefined;
+    const port = Number.parseInt(digits, 10);
+    return Number.isSafeInteger(port) ? port : undefined;
+}
+/** The scripts block of a package.json, or an empty one for anything unreadable/unparseable. */
+function readScripts(raw) {
+    if (raw === undefined)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (null === parsed || 'object' !== typeof parsed)
+            return {};
+        const scripts = parsed.scripts;
+        if (null === scripts || 'object' !== typeof scripts)
+            return {};
+        return scripts;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The dev command for the project in `directory`, or undefined when there is not one to be sure of.
+ *
+ * `read` is injected so the whole decision is testable without a filesystem; the daemon uses the
+ * default disk reader.
+ */
+export function detectDevCommand(directory, read = readTextFile) {
+    const scripts = readScripts(read(join(directory, PACKAGE_JSON)));
+    const manager = LOCKFILES.find(({ file }) => read(join(directory, file)) !== undefined)?.manager ??
+        DEFAULT_PACKAGE_MANAGER;
+    for (const script of DEV_SCRIPTS) {
+        const body = scripts[script];
+        if ('string' !== typeof body || 0 === body.trim().length)
+            continue;
+        const port = pinnedPort(body);
+        return {
+            command: `${manager} run ${script}`,
+            script,
+            ...(port === undefined ? {} : { port }),
+        };
+    }
+    return undefined;
+}

package/dist/session/dev-server-probe.d.ts

@@ -9,5 +9,73 @@
  * the probe refreshes in the background and the resolve path reads a cached answer. A stale answer
  * is fine here — it is a hint in an error message, not a decision.
  */
+/**
+ * What the probe actually learned about a port. Three states, because two cannot express this.
+ *
+ * A bare TCP connect is not enough (macOS AirPlay Receiver holds 5000 on every Mac and would read as
+ * the user's dev server), and a document check alone is not enough either (a compiling SSR server
+ * reads as absent). The thing in between — accepted the connection, said nothing in time — is a
+ * listener we cannot classify, and reporting that honestly is the point.
+ */
+export declare const PortState: {
+    /** Nothing accepted a connection on either loopback family. */
+    readonly CLOSED: "closed";
+    /** Accepted a connection, then answered nothing within the budget. Something IS there. */
+    readonly CONNECTED_NO_ANSWER: "connected-no-answer";
+    /** Answered with a document: a dev server serving an app. */
+    readonly SERVES_DOCUMENT: "serves-document";
+};
+export type PortState = (typeof PortState)[keyof typeof PortState];
+/** The probe's answer for one port, however it was obtained. */
+export declare function classifyPort(port: number, probe: (port: number) => Promise<PortState>): Promise<PortState>;
+/**
+ * `localhost`, not `127.0.0.1` — so BOTH address families are tried.
+ *
+ * Measured: a plain `vite --port 4311` on this machine listens on `[::1]` only, and a probe pinned to
+ * the IPv4 loopback cannot see it. The old TCP probe had the same blind spot, which meant the
+ * diagnostic could miss the very dev server it exists to find while still reporting an unrelated
+ * service that happens to bind both stacks (macOS AirPlay does).
+ */
+/**
+ * Both loopback addresses, BY ADDRESS — never by the name `localhost`.
+ *
+ * A dev server started with `--host` binds the wildcards `0.0.0.0` and `[::]` rather than the
+ * loopbacks, and a wildcard bind serves only the family it belongs to. Asking for `localhost` hands
+ * the choice of family to the resolver: on Windows it prefers `::1`, so a `0.0.0.0` listener is
+ * invisible and the scan reports "nothing is listening" about a dev server that is plainly running.
+ * Reported from the field on exactly that setup.
+ *
+ * `[::1]` is also how a `[::]` bind is reached, and on most stacks a `[::]` bind additionally
+ * accepts v4-mapped connections — so between the two, every ordinary bind is covered.
+ */
+export declare const PROBE_HOSTS: readonly string[];
+/**
+ * Is anything serving a document on this port, on EITHER loopback family?
+ *
+ * "Either" and not "both": one answer is enough, and requiring both would make the wildcard binds
+ * this exists to see fail the check again. A family that errors (no IPv6 stack at all) is an
+ * absence, never a rejection — a diagnostic must not throw at the tool it is diagnosing.
+ */
+export declare function anyFamilyServes(port: number, probe?: (port: number, host: string) => Promise<boolean>): Promise<boolean>;
+/**
+ * Every candidate port, split by what the probe could actually establish.
+ *
+ * `slow` is the set that accepted a connection and then said nothing inside the budget. Those ports
+ * are NOT dev servers as far as this check knows, and they are emphatically not absent — an SSR
+ * framework compiling its first route lands here every time. Reported separately so the diagnosis
+ * can stop telling people to start a server that is already running.
+ */
+export declare function probeDevServerStates(ports?: readonly number[], probe?: (port: number) => Promise<PortState>): Promise<{
+    serving: number[];
+    slow: number[];
+}>;
+/**
+ * The strongest state either loopback family reports.
+ *
+ * Serving a document beats a bare connection beats nothing, so a server bound to only one family is
+ * still seen at its best — the same "either, not both" rule `anyFamilyServes` follows, extended to
+ * three states.
+ */
+export declare function anyFamilyState(port: number, probe?: (port: number, host: string) => Promise<PortState>): Promise<PortState>;
 /** Every candidate port serving a document, in ascending order. Never rejects. */
 export declare function probeDevServers(ports?: readonly number[], probe?: (port: number) => Promise<boolean>): Promise<number[]>;

package/dist/session/dev-server-probe.js

@@ -12,8 +12,37 @@
 import { request } from 'node:http';
 import { DEV_SERVER_PORTS } from '../cli/cli-port.js';
 import { looksLikeDevServer } from './looks-like-dev-server.js';
-/** Give up fast: an HTTP answer from localhost either lands quickly or nothing is there. */
+/**
+ * Give up fast, but do not call giving up an absence.
+ *
+ * This budget suits Vite handing back a static index.html. It does NOT suit an SSR framework
+ * compiling a route on the first request: Nuxt and Next routinely take seconds cold, and treating
+ * that as "nothing is there" told a reporter to start a dev server that was already serving 57KB of
+ * HTML — advice that would have hit their dev lock with a second `nuxt dev`.
+ *
+ * So the budget stays short and the TIMEOUT changed meaning instead. See PortState.
+ */
 const HTTP_PROBE_TIMEOUT_MS = 400;
+/**
+ * What the probe actually learned about a port. Three states, because two cannot express this.
+ *
+ * A bare TCP connect is not enough (macOS AirPlay Receiver holds 5000 on every Mac and would read as
+ * the user's dev server), and a document check alone is not enough either (a compiling SSR server
+ * reads as absent). The thing in between — accepted the connection, said nothing in time — is a
+ * listener we cannot classify, and reporting that honestly is the point.
+ */
+export const PortState = {
+    /** Nothing accepted a connection on either loopback family. */
+    CLOSED: 'closed',
+    /** Accepted a connection, then answered nothing within the budget. Something IS there. */
+    CONNECTED_NO_ANSWER: 'connected-no-answer',
+    /** Answered with a document: a dev server serving an app. */
+    SERVES_DOCUMENT: 'serves-document',
+};
+/** The probe's answer for one port, however it was obtained. */
+export function classifyPort(port, probe) {
+    return probe(port).catch(() => PortState.CLOSED);
+}
 /**
  * `localhost`, not `127.0.0.1` — so BOTH address families are tried.
  *
@@ -22,7 +51,19 @@ const HTTP_PROBE_TIMEOUT_MS = 400;
  * diagnostic could miss the very dev server it exists to find while still reporting an unrelated
  * service that happens to bind both stacks (macOS AirPlay does).
  */
-const PROBE_HOST = 'localhost';
+/**
+ * Both loopback addresses, BY ADDRESS — never by the name `localhost`.
+ *
+ * A dev server started with `--host` binds the wildcards `0.0.0.0` and `[::]` rather than the
+ * loopbacks, and a wildcard bind serves only the family it belongs to. Asking for `localhost` hands
+ * the choice of family to the resolver: on Windows it prefers `::1`, so a `0.0.0.0` listener is
+ * invisible and the scan reports "nothing is listening" about a dev server that is plainly running.
+ * Reported from the field on exactly that setup.
+ *
+ * `[::1]` is also how a `[::]` bind is reached, and on most stacks a `[::]` bind additionally
+ * accepts v4-mapped connections — so between the two, every ordinary bind is covered.
+ */
+export const PROBE_HOSTS = ['127.0.0.1', '::1'];
 /**
  * Does this port serve a DOCUMENT — i.e. is it a dev server rather than merely something listening?
  *
@@ -30,23 +71,77 @@ const PROBE_HOST = 'localhost';
  * port 5000) as the user's dev server. See looks-like-dev-server for what it actually answers and
  * why "a socket accepted" is the wrong question.
  */
-function servesDocument(port, host = PROBE_HOST) {
+function probeState(port, host) {
     return new Promise((resolve) => {
+        // Whether the SOCKET came up is tracked separately from whether a response did, because that is
+        // the whole difference between "nothing is there" and "something is there and still compiling".
+        let connected = false;
         const req = request({ host, port, path: '/', method: 'GET', timeout: HTTP_PROBE_TIMEOUT_MS }, (res) => {
             const answer = looksLikeDevServer(res.statusCode ?? 0, res.headers['content-type']);
             res.resume(); // drain, so the socket closes rather than lingering
-            resolve(answer);
+            resolve(answer ? PortState.SERVES_DOCUMENT : PortState.CLOSED);
+        });
+        req.once('socket', (socket) => {
+            socket.once('connect', () => {
+                connected = true;
+            });
         });
         req.once('timeout', () => {
             req.destroy();
-            resolve(false);
+            resolve(connected ? PortState.CONNECTED_NO_ANSWER : PortState.CLOSED);
         });
-        req.once('error', () => resolve(false));
+        req.once('error', () => resolve(PortState.CLOSED));
         req.end();
     });
 }
+/** Kept for callers that only need the yes/no. A slow listener is NOT a dev server, but it is not absent. */
+function servesDocument(port, host) {
+    return probeState(port, host).then((state) => state === PortState.SERVES_DOCUMENT);
+}
+/**
+ * Is anything serving a document on this port, on EITHER loopback family?
+ *
+ * "Either" and not "both": one answer is enough, and requiring both would make the wildcard binds
+ * this exists to see fail the check again. A family that errors (no IPv6 stack at all) is an
+ * absence, never a rejection — a diagnostic must not throw at the tool it is diagnosing.
+ */
+export async function anyFamilyServes(port, probe = servesDocument) {
+    const answers = await Promise.all(PROBE_HOSTS.map((host) => probe(port, host).catch(() => false)));
+    return answers.some((up) => up);
+}
+/**
+ * Every candidate port, split by what the probe could actually establish.
+ *
+ * `slow` is the set that accepted a connection and then said nothing inside the budget. Those ports
+ * are NOT dev servers as far as this check knows, and they are emphatically not absent — an SSR
+ * framework compiling its first route lands here every time. Reported separately so the diagnosis
+ * can stop telling people to start a server that is already running.
+ */
+export async function probeDevServerStates(ports = [...DEV_SERVER_PORTS], probe = (p) => anyFamilyState(p)) {
+    const states = await Promise.all(ports.map((p) => classifyPort(p, probe).then((state) => ({ port: p, state }))));
+    const pick = (want) => states
+        .filter((s) => s.state === want)
+        .map((s) => s.port)
+        .sort((a, b) => a - b);
+    return { serving: pick(PortState.SERVES_DOCUMENT), slow: pick(PortState.CONNECTED_NO_ANSWER) };
+}
+/**
+ * The strongest state either loopback family reports.
+ *
+ * Serving a document beats a bare connection beats nothing, so a server bound to only one family is
+ * still seen at its best — the same "either, not both" rule `anyFamilyServes` follows, extended to
+ * three states.
+ */
+export async function anyFamilyState(port, probe = probeState) {
+    const answers = await Promise.all(PROBE_HOSTS.map((host) => probe(port, host).catch(() => PortState.CLOSED)));
+    if (answers.includes(PortState.SERVES_DOCUMENT))
+        return PortState.SERVES_DOCUMENT;
+    if (answers.includes(PortState.CONNECTED_NO_ANSWER))
+        return PortState.CONNECTED_NO_ANSWER;
+    return PortState.CLOSED;
+}
 /** Every candidate port serving a document, in ascending order. Never rejects. */
-export async function probeDevServers(ports = [...DEV_SERVER_PORTS], probe = (p) => servesDocument(p)) {
+export async function probeDevServers(ports = [...DEV_SERVER_PORTS], probe = (p) => anyFamilyServes(p)) {
     const results = await Promise.all(ports.map((p) => probe(p).then((up) => (up ? p : null))));
     return results.filter((p) => p !== null).sort((a, b) => a - b);
 }