@reticlehq/server 2.13.0 → 2.14.0

package/dist/setup/dev-server-wait.d.ts

@@ -25,6 +25,14 @@ export interface WaitFacts {
     readonly quietForMs: number;
     /** Milliseconds since the wait began. */
     readonly elapsedMs: number;
+    /**
+     * How long silence may mean "still starting" on THIS machine. Defaults to QUIET_MEANS_HUNG_MS.
+     *
+     * Passed in rather than read from the platform here, so this stays a pure decision and exactly one
+     * caller owns the platform check. 45s is generous on a laptop and tight on a cold Windows runner,
+     * where a first `npm run dev` optimises dependencies before Vite prints a line.
+     */
+    readonly quietMeansHungMs?: number;
 }
 export declare const WaitVerdict: {
     /** It is up. Carry on. */

package/dist/setup/dev-server-wait.js

@@ -41,7 +41,9 @@ export function judgeWait(facts) {
     if (facts.elapsedMs >= WAIT_CEILING_MS)
         return WaitVerdict.HUNG;
     // Output IS progress. Silence is what distinguishes a build from a wedge.
-    return facts.quietForMs >= QUIET_MEANS_HUNG_MS ? WaitVerdict.HUNG : WaitVerdict.WAITING;
+    return facts.quietForMs >= (facts.quietMeansHungMs ?? QUIET_MEANS_HUNG_MS)
+        ? WaitVerdict.HUNG
+        : WaitVerdict.WAITING;
 }
 /** A url the dev server announced, if it has announced one. Never composed, only read. */
 const URL_IN_OUTPUT = /https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]):\d+/;

package/dist/setup/drive-agent.d.ts

@@ -10,8 +10,6 @@
  * Two details here are not stylistic, and both cost a real run to learn.
  */
 import { type DriverSpec } from './drive-plan.js';
-/** Ten minutes. Long, because the drive is a model working, and bounded, because it can wedge. */
-export declare const DRIVE_TIMEOUT_MS: number;
 export interface DriveRequest {
     readonly url: string;
     readonly sessionId: string;
@@ -24,7 +22,7 @@ export interface DriveRequest {
     readonly budgetUsd: number;
     readonly model?: string | undefined;
 }
-export interface DriveReport {
+interface DriveReport {
     /** The agent's own account, kept verbatim and never treated as a pass on its own. */
     readonly text: string;
     readonly grade?: string | undefined;
@@ -69,3 +67,4 @@ export declare function readDriveOutput(out: string): DriveReport;
 export declare function driveWith(driver: DriverSpec, req: DriveRequest, cwd: string): DriveReport;
 /** Everything that is not Claude Code reports prose, so the report IS its output. */
 export declare function readPlainOutput(out: string): DriveReport;
+export {};

package/dist/setup/drive-agent.js

@@ -12,7 +12,7 @@
 import { spawnSync } from 'node:child_process';
 import { ASSERTED, readAssertionsGrade } from './drive-plan.js';
 /** Ten minutes. Long, because the drive is a model working, and bounded, because it can wedge. */
-export const DRIVE_TIMEOUT_MS = 10 * 60_000;
+const DRIVE_TIMEOUT_MS = 10 * 60_000;
 /** Only the Reticle surface, unless the capabilities file has to be finished first. */
 const RETICLE_TOOLS = 'mcp__reticle';
 const CAPABILITY_TOOLS = 'mcp__reticle,Read,Edit,Write';

package/dist/setup/drive-plan.d.ts

@@ -6,7 +6,7 @@
  * they can be tested without spending anything.
  */
 /** What a driver needs to build its own invocation. */
-export interface DriveInvocation {
+interface DriveInvocation {
     /** The tools the drive may use, comma-separated, in Claude Code's spelling. */
     readonly tools: string;
     readonly budgetUsd: number;
@@ -49,7 +49,7 @@ export declare function chooseDriver(drivers: readonly DriverSpec[], probe: (bin
 export declare function readAssertionsGrade(text: string | undefined): string | undefined;
 /** The only grade that makes a saved flow worth replaying. */
 export declare const ASSERTED = "asserted";
-export interface EscalationInput {
+interface EscalationInput {
     readonly escalationEnabled: boolean;
     /** Set only when a faster model was chosen, since escalation means retrying without it. */
     readonly fasterModel: string | undefined;
@@ -66,3 +66,4 @@ export interface EscalationInput {
  * choose is worse than spending a second drive on it.
  */
 export declare function shouldEscalate(input: EscalationInput): boolean;
+export {};

package/dist/setup/ensure-daemon.d.ts

@@ -11,7 +11,7 @@
  * Idempotent by construction: an alive daemon for this project is adopted, and one belonging to
  * somebody else is refused rather than stolen, which is the same rule `reticle mcp` follows.
  */
-export interface EnsureDaemonDeps {
+interface EnsureDaemonDeps {
     readonly usable: (port: number) => Promise<boolean>;
     readonly spawn: (port: number) => boolean;
     readonly waitReady: (port: number) => Promise<unknown>;
@@ -27,3 +27,4 @@ export declare const EnsureDaemon: {
 export type EnsureDaemon = (typeof EnsureDaemon)[keyof typeof EnsureDaemon];
 export declare function ensureDaemon(port: number, deps: EnsureDaemonDeps): Promise<EnsureDaemon>;
 export declare function nodeEnsureDaemonDeps(): EnsureDaemonDeps;
+export {};

package/dist/setup/existing-app.d.ts

@@ -0,0 +1,12 @@
+import { type DevServerEntry } from '@reticlehq/core';
+/**
+ * The URL of a live dev server that belongs to THIS project, if one has announced itself.
+ *
+ * Setup used to ignore the registry and spawn `dev` anyway. Vite then bound the next port (5174)
+ * beside the one already serving (5173), and `reticle_sessions` listed three tabs with no way to
+ * pick. The registry is scoped on purpose: an unscoped read would attach to a sibling app.
+ */
+export declare function urlOfExistingApp(entries: readonly DevServerEntry[], scope: {
+    projectId?: string | undefined;
+    root?: string | undefined;
+}): string | undefined;

package/dist/setup/existing-app.js

@@ -0,0 +1,13 @@
+import { devServersForProject } from '@reticlehq/core';
+/**
+ * The URL of a live dev server that belongs to THIS project, if one has announced itself.
+ *
+ * Setup used to ignore the registry and spawn `dev` anyway. Vite then bound the next port (5174)
+ * beside the one already serving (5173), and `reticle_sessions` listed three tabs with no way to
+ * pick. The registry is scoped on purpose: an unscoped read would attach to a sibling app.
+ */
+export function urlOfExistingApp(entries, scope) {
+    const mine = devServersForProject(entries, scope);
+    const first = mine[0];
+    return first === undefined ? undefined : first.url;
+}

package/dist/setup/init-host.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The daemon half of `reticle init`.
+ *
+ * `@reticlehq/init` writes files and runs a package manager and knows nothing else — no tracer, no
+ * telemetry client, no bridge state directory. Those four capabilities are declared by `InitHost`
+ * and supplied here, which is the whole seam between the scaffolder and the daemon. Built in one
+ * place rather than at each call site so a caller cannot half-wire it: a missing reporter is a
+ * metric that is silently, permanently absent, which is the failure mode telemetry always has.
+ */
+import type { InitHost } from '@reticlehq/init';
+export declare function serverInitHost(): InitHost;

package/dist/setup/init-host.js

@@ -0,0 +1,26 @@
+import { spanSync } from '../trace.js';
+import { reportInitOutcome } from '../telemetry/init-telemetry.js';
+import { defaultPairingTokenDir, readOrCreatePairingTokenSync } from '../bridge/pairing-token.js';
+import { declaredInstallSource } from '../telemetry/install-source.js';
+export function serverInitHost() {
+    return {
+        span(name, fields, fn) {
+            return spanSync(name, fields, fn);
+        },
+        reportOutcome(outcome) {
+            reportInitOutcome(outcome);
+        },
+        /**
+         * Minted here if nothing has written it yet. `init` used to READ the file and return empty when
+         * the daemon had never started; the CDN snippet inlined that empty value permanently, and
+         * regenerating the token made the pasted literal stale. Same mint as the daemon
+         * (`readOrCreatePairingToken`), and it honours `RETICLE_PAIRING_TOKEN_DIR`.
+         */
+        pairingToken() {
+            return readOrCreatePairingTokenSync(defaultPairingTokenDir()) ?? '';
+        },
+        installSource() {
+            return declaredInstallSource();
+        },
+    };
+}

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

@@ -5,9 +5,9 @@
  * cli.ts is a dispatcher: a command that grew a second half should not make the file that routes
  * every command harder to read.
  */
-import type { InitResult } from '../init/run.js';
+import type { InitResult } from '@reticlehq/init';
 /** Just enough of the parsed command to decide and run. */
-export interface InitRuntimeArgs {
+interface InitRuntimeArgs {
     readonly port: number | undefined;
     readonly dryRun: boolean;
     readonly filesOnly?: boolean | undefined;
@@ -34,14 +34,8 @@ export interface InitRuntimeArgs {
     readonly driveModel?: string | undefined;
     readonly licenseKey?: string | undefined;
 }
-export interface RuntimePrintIo {
+interface RuntimePrintIo {
     readonly print: (line: string) => void;
 }
-/**
- * Carry on from a finished `init`, or stop where it used to.
- *
- * `--files-only` is what init did before it learned to boot the app, and a dry run is a preview:
- * both keep the old ending. Everyone else gets the rest, because writing files was never the same
- * thing as an install working.
- */
 export declare function continueAfterInit(parsed: InitRuntimeArgs, result: InitResult, io: RuntimePrintIo, cwd: string): Promise<void>;
+export {};

package/dist/setup/init-runtime.js

@@ -7,7 +7,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
-import { confirmInstall, nodeConfirmDeps } from '../init/confirm.js';
+import { confirmInstall, nodeConfirmDeps } from './confirm.js';
 import { writeLicenseKey } from './license-key.js';
 import { registerOtherAgents, runSetupCommand } from './setup-command.js';
 import { bridgeOccupied } from './bridge-port.js';
@@ -35,6 +35,19 @@ const licenseIo = {
  * both keep the old ending. Everyone else gets the rest, because writing files was never the same
  * thing as an install working.
  */
+function printRelaunch(parsed, io, cwd) {
+    if (true !== parsed.relaunch)
+        return;
+    io.print(relaunchDecision({
+        ...(undefined === process.env['CLAUDE_CODE_SESSION_ID']
+            ? {}
+            : { claudeSessionId: process.env['CLAUDE_CODE_SESSION_ID'] }),
+        ...(undefined === codexSessionFor(cwd) ? {} : { codexSessionId: codexSessionFor(cwd) }),
+        transcriptExists: claudeTranscriptExists,
+        cwd,
+    }).message);
+    io.print('');
+}
 export async function continueAfterInit(parsed, result, io, cwd) {
     const port = parsed.port ?? RETICLE_DEFAULT_PORT;
     // Before anything else: the key belongs in .env whichever way this run ends, and the CLI folds a
@@ -43,6 +56,15 @@ export async function continueAfterInit(parsed, result, io, cwd) {
         const written = writeLicenseKey(cwd, parsed.licenseKey, licenseIo);
         io.print(written.message);
     }
+    // Decided and printed before the `--files-only` return, not after it. The restart question is
+    // asked by whoever just installed, and `--files-only` is the mode an agent uses when the app is
+    // ALREADY running — so the one route that most needs the answer was the one route that could not
+    // reach it, and `--relaunch --files-only` accepted the flag and silently did nothing with it.
+    //
+    // Never performed: opening a terminal is not something a one-shot command should do behind a
+    // flag, and the half worth having is the refusal — `--resume` on an id with no transcript opens
+    // an EMPTY conversation that looks exactly like it worked. See relaunch.ts.
+    printRelaunch(parsed, io, cwd);
     if (true === parsed.filesOnly || parsed.dryRun) {
         // Registration and pre-approval still run here, and this is the ONLY route an existing user
         // has: nothing reaches back into a machine that installed Reticle a version ago, so the
@@ -72,21 +94,6 @@ export async function continueAfterInit(parsed, result, io, cwd) {
     // The run still ends non-zero: the phase returns `ok: false` when no session appears, and a
     // session appearing means the manual step WAS done and the app really did connect — which is a
     // green worth reporting, not one to suppress.
-    // What a restart should do, decided and printed. Never performed: opening a terminal is not
-    // something a one-shot command should do behind a flag, and the half worth having is the refusal —
-    // `--resume` on an id with no transcript opens an EMPTY conversation that looks exactly like it
-    // worked. See relaunch.ts.
-    if (true === parsed.relaunch) {
-        io.print(relaunchDecision({
-            ...(undefined === process.env['CLAUDE_CODE_SESSION_ID']
-                ? {}
-                : { claudeSessionId: process.env['CLAUDE_CODE_SESSION_ID'] }),
-            ...(undefined === codexSessionFor(cwd) ? {} : { codexSessionId: codexSessionFor(cwd) }),
-            transcriptExists: claudeTranscriptExists,
-            cwd,
-        }).message);
-        io.print('');
-    }
     // Before the connect wait, never after: a bridge held by a stranger makes a session impossible,
     // so going ahead spends the entire budget and then reports what reads as an instrumentation
     // problem — the one place that is fine. See bridge-port.ts.

package/dist/setup/license-key.d.ts

@@ -20,7 +20,7 @@ export declare const LicenseWrite: {
     readonly REPLACED: "replaced";
 };
 export type LicenseWrite = (typeof LicenseWrite)[keyof typeof LicenseWrite];
-export interface LicenseResult {
+interface LicenseResult {
     readonly action: LicenseWrite;
     /** True when `.gitignore` had to be changed so the key cannot be committed. */
     readonly gitignoreUpdated: boolean;
@@ -37,3 +37,4 @@ export declare function gitignoreCoversEnv(contents: string): boolean;
  * which that is.
  */
 export declare function writeLicenseKey(dir: string, key: string, io: LicenseIo): LicenseResult;
+export {};

package/dist/setup/listeners.d.ts

@@ -8,7 +8,7 @@
  * platform's most common React setup.
  */
 /** One LISTENING socket and the process that owns it. */
-export interface Listener {
+interface Listener {
     readonly port: number;
     readonly pid: number;
 }
@@ -35,3 +35,4 @@ export declare function parseWmicProcesses(out: string): ProcessPair[];
  * indistinguishable from "no server".
  */
 export declare function descendants(pairs: readonly ProcessPair[], root: number): number[];
+export {};

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

@@ -0,0 +1,18 @@
+/**
+ * Alternate loopback URLs to try when a readiness probe misses on the announced host.
+ *
+ * Vite (and friends) sometimes print `http://127.0.0.1:PORT` even when the process only accepted
+ * on `[::1]`. Node `fetch` of that announcement then fails forever while `http://localhost:PORT`
+ * and `http://[::1]:PORT` answer — which is how `init` sat in the wait loop until something killed
+ * it (#884). Asking by name hands the family to the OS; asking both literal loopbacks does not.
+ *
+ * Same "either family is enough" rule as `PROBE_HOSTS` in the no-session diagnostic — this is the
+ * setup wait's copy of that lesson, applied to a full URL rather than a bare port.
+ */
+/**
+ * URLs that mean the same loopback listener, for every family this machine might bind.
+ *
+ * Non-loopback URLs are returned unchanged (one candidate): a LAN or tunnel origin is not a
+ * family-split problem, and inventing alternates would probe the wrong machine.
+ */
+export declare function loopbackProbeUrls(url: string): string[];

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

@@ -0,0 +1,52 @@
+/**
+ * Alternate loopback URLs to try when a readiness probe misses on the announced host.
+ *
+ * Vite (and friends) sometimes print `http://127.0.0.1:PORT` even when the process only accepted
+ * on `[::1]`. Node `fetch` of that announcement then fails forever while `http://localhost:PORT`
+ * and `http://[::1]:PORT` answer — which is how `init` sat in the wait loop until something killed
+ * it (#884). Asking by name hands the family to the OS; asking both literal loopbacks does not.
+ *
+ * Same "either family is enough" rule as `PROBE_HOSTS` in the no-session diagnostic — this is the
+ * setup wait's copy of that lesson, applied to a full URL rather than a bare port.
+ */
+import { isLoopbackHostname } from '@reticlehq/core';
+/** Hosts to try, in order: keep the caller's first, then fill the gaps. */
+const LOOPBACK_HOSTS = ['127.0.0.1', 'localhost', '::1'];
+/**
+ * URLs that mean the same loopback listener, for every family this machine might bind.
+ *
+ * Non-loopback URLs are returned unchanged (one candidate): a LAN or tunnel origin is not a
+ * family-split problem, and inventing alternates would probe the wrong machine.
+ */
+export function loopbackProbeUrls(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return [url];
+    }
+    if (!isLoopbackHostname(parsed.hostname))
+        return [url];
+    const out = [];
+    const seen = new Set();
+    const push = (host) => {
+        const next = new URL(parsed.href);
+        // `URL.hostname = '::1'` is a silent no-op in Node — the IPv6 form has to go through `host`
+        // with brackets, or the candidate list collapses to IPv4-only and the whole fallback is dead.
+        const port = parsed.port;
+        next.host = host.includes(':')
+            ? `[${host}]${port.length > 0 ? `:${port}` : ''}`
+            : `${host}${port.length > 0 ? `:${port}` : ''}`;
+        const href = next.href;
+        if (seen.has(href))
+            return;
+        seen.add(href);
+        out.push(href);
+    };
+    // Caller's host first so a working announcement is not reordered for no reason.
+    push(parsed.hostname);
+    for (const host of LOOPBACK_HOSTS)
+        push(host);
+    return out;
+}

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

@@ -48,6 +48,9 @@ export declare class OwnedDevServer {
  * A refused certificate is reported separately because the server ANSWERED: a self-signed dev cert
  * is an ordinary local setup, and calling it "nothing is listening" sends somebody to start a
  * server that is already running.
+ *
+ * On loopback, the announced host is tried first and the other loopback families follow when it
+ * misses — so an IPv6-only Vite that printed `127.0.0.1` still counts as served (#884).
  */
 export declare function probePage(url: string): Promise<PageProbe>;
 /** Sessions the daemon is holding, in the shape the picker reads. */

package/dist/setup/node-effects.js

@@ -17,6 +17,7 @@ import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { fetchStatus } from '../cli/cli-launch.js';
 import { descendants, parseLsofPorts, parseNetstatListeners, parseWmicProcesses, } from './listeners.js';
+import { loopbackProbeUrls } from './loopback-probe-urls.js';
 const WINDOWS = 'win32' === process.platform;
 /** A page fetch that is slow is a page fetch that failed, for our purposes. */
 const PROBE_TIMEOUT_MS = 5_000;
@@ -161,20 +162,34 @@ function windowsProcessPairs() {
  * A refused certificate is reported separately because the server ANSWERED: a self-signed dev cert
  * is an ordinary local setup, and calling it "nothing is listening" sends somebody to start a
  * server that is already running.
+ *
+ * On loopback, the announced host is tried first and the other loopback families follow when it
+ * misses — so an IPv6-only Vite that printed `127.0.0.1` still counts as served (#884).
  */
 export async function probePage(url) {
-    try {
-        const res = await fetch(url, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
-        const body = await res.text();
-        return { served: true, sdkInPage: /@reticlehq|@reticle-connect|reticle-dev/.test(body) };
-    }
-    catch (err) {
-        const message = String(err?.cause?.message ??
-            err?.message ??
-            '');
-        const tlsRefused = /certificate|SELF_SIGNED|DEPTH_ZERO|ERR_TLS|unable to verify/i.test(message);
-        return { served: false, sdkInPage: false, tlsRefused };
+    const candidates = loopbackProbeUrls(url);
+    let sawTlsRefused = false;
+    for (const candidate of candidates) {
+        try {
+            const res = await fetch(candidate, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+            const body = await res.text();
+            const sdkInPage = /@reticlehq|@reticle-connect|reticle-dev/.test(body);
+            // Only stamp reachedUrl when we had to leave the announcement — callers that already have
+            // the working URL should not rewrite it for a no-op.
+            return candidate === url
+                ? { served: true, sdkInPage }
+                : { served: true, sdkInPage, reachedUrl: candidate };
+        }
+        catch (err) {
+            const message = String(err?.cause?.message ??
+                err?.message ??
+                '');
+            if (/certificate|SELF_SIGNED|DEPTH_ZERO|ERR_TLS|unable to verify/i.test(message)) {
+                sawTlsRefused = true;
+            }
+        }
     }
+    return { served: false, sdkInPage: false, ...(sawTlsRefused ? { tlsRefused: true } : {}) };
 }
 /** Sessions the daemon is holding, in the shape the picker reads. */
 export async function listSessions(port) {

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

@@ -22,6 +22,11 @@ export interface PageProbe {
      * already running.
      */
     readonly tlsRefused?: boolean | undefined;
+    /**
+     * The URL that actually answered, when the announced host missed and a loopback sibling did not.
+     * Callers that open a browser or wait on a session should prefer this over the announcement (#884).
+     */
+    readonly reachedUrl?: string | undefined;
 }
 export declare const PageFinding: {
     readonly NOT_SERVED: "not-served";

package/dist/setup/relaunch.d.ts

@@ -29,8 +29,9 @@ export interface RelaunchEnv {
     transcriptExists(sessionId: string): boolean;
     readonly cwd: string;
 }
-export interface RelaunchDecision {
+interface RelaunchDecision {
     readonly outcome: RelaunchOutcome;
     readonly message: string;
 }
 export declare function relaunchDecision(env: RelaunchEnv): RelaunchDecision;
+export {};

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

@@ -14,7 +14,6 @@
 import { type CandidateSession } from './session-pick.js';
 import { type PageProbe } from './page-probe.js';
 import { AppShape } from './desktop-shape.js';
-/** Where a run got to, and why it stopped if it did. */
 export declare const SetupPhase: {
     readonly DEV_SERVER: "dev-server";
     readonly CONNECT: "connect";
@@ -39,6 +38,11 @@ export interface SetupOutcome {
 export interface SetupEffects {
     /** Start the dev server. Resolves once started; the caller owns stopping it. */
     readonly startDevServer: (command: string, cwd: string) => Promise<void>;
+    /**
+     * A live server this project already announced, if any. Setup attaches to it rather than
+     * starting a second one on the next port.
+     */
+    readonly existingAppUrl?: () => Promise<string | undefined>;
     /** Everything the dev server has printed so far. */
     readonly devServerOutput: () => string;
     readonly devServerExited: () => boolean;