@reticlehq/server 2.8.0 → 2.10.0

package/dist/bridge/bridge.d.ts

@@ -15,7 +15,30 @@ type SessionReadyHandler = (session: Session) => void;
 export declare const WS_CLOSE_REASON: {
     readonly PROTOCOL_MISMATCH: "protocol version mismatch — upgrade @reticlehq/browser";
     readonly AUTH_FAILED: "authentication failed — reload the page to pick up the current pairing token";
+    /**
+     * The pool of half-open handshakes was full, so this dial was turned away before it could say
+     * anything. Every other refusal here records why and this one did not — it closed the socket and
+     * returned — so an app that was running, instrumented and actively dialling looked exactly like an
+     * app nobody had started, and the diagnosis went hunting a stopped dev server.
+     *
+     * Names the cause and the fact that it is transient, because the remedy differs from every other
+     * refusal on this path: nothing about the app is wrong and retrying is the correct response.
+     */
+    readonly HANDSHAKE_POOL_FULL: string;
 };
+/**
+ * A dial turned away at the ORIGIN gate, in words the reader can act on.
+ *
+ * This is the refusal that used to leave no trace anywhere. It happens before any HELLO, so it
+ * produced no `noteClosure`, no `session_disconnected`, nothing but an `origin_rejected` log line —
+ * and the daemon log is the file nobody opens until they have already lost the afternoon. Reported
+ * from a multi-tenant app resolving its tenant from the `Host` header: on a hosts-file alias every
+ * dial was refused here, `doctor` reported every check green, and the lease hint blamed the port.
+ *
+ * The origin is IN the message because it is the fix: it is either the alias to allow-list, or the
+ * proof that the page is not being served from where the developer thinks it is.
+ */
+export declare function originRejectedReason(origin: string | undefined): string;
 interface BridgeOptions {
     port: number;
     host?: string;

package/dist/bridge/bridge.js

@@ -1,5 +1,6 @@
 import * as http from 'node:http';
 import { authFailureReason } from './auth-failure-reason.js';
+import { impactSnapshot, recordImpact } from '../impact/impact-recorder.js';
 import { WebSocketServer } from 'ws';
 import { EventType, HumanControlKind, RETICLE_WS_PATH, ReticleMessageSchema, LOOPBACK_HOST, MessageKind, ReticleEnv, RETICLE_PROTOCOL_VERSION, TRANSPORT_LIMITS, isLocalPage, isLoopbackHostname, isOpaqueOrigin, OPAQUE_ORIGIN, isHighValueEvent, RATE_CAP_HIGH_VALUE_RESERVE_RATIO, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
 import { Session, SessionManager } from '../session/session.js';
@@ -38,7 +39,39 @@ function refreshIdentity(session, hello) {
 export const WS_CLOSE_REASON = {
     PROTOCOL_MISMATCH: 'protocol version mismatch — upgrade @reticlehq/browser',
     AUTH_FAILED: 'authentication failed — reload the page to pick up the current pairing token',
+    /**
+     * The pool of half-open handshakes was full, so this dial was turned away before it could say
+     * anything. Every other refusal here records why and this one did not — it closed the socket and
+     * returned — so an app that was running, instrumented and actively dialling looked exactly like an
+     * app nobody had started, and the diagnosis went hunting a stopped dev server.
+     *
+     * Names the cause and the fact that it is transient, because the remedy differs from every other
+     * refusal on this path: nothing about the app is wrong and retrying is the correct response.
+     */
+    HANDSHAKE_POOL_FULL: 'refused at the handshake pool — too many connections were mid-handshake on this daemon, so ' +
+        'this dial never got to identify itself. Nothing is wrong with the app; the pool drains on its ' +
+        'own and reloading the page reconnects. If it persists, something else on this machine is ' +
+        'opening sockets to this port.',
 };
+/**
+ * A dial turned away at the ORIGIN gate, in words the reader can act on.
+ *
+ * This is the refusal that used to leave no trace anywhere. It happens before any HELLO, so it
+ * produced no `noteClosure`, no `session_disconnected`, nothing but an `origin_rejected` log line —
+ * and the daemon log is the file nobody opens until they have already lost the afternoon. Reported
+ * from a multi-tenant app resolving its tenant from the `Host` header: on a hosts-file alias every
+ * dial was refused here, `doctor` reported every check green, and the lease hint blamed the port.
+ *
+ * The origin is IN the message because it is the fix: it is either the alias to allow-list, or the
+ * proof that the page is not being served from where the developer thinks it is.
+ */
+export function originRejectedReason(origin) {
+    const named = origin === undefined || 0 === origin.length ? 'a page sending no Origin' : origin;
+    return (`a browser dialled this daemon and was REFUSED at the origin gate: ${named} is not allowed. ` +
+        'Off localhost the SDK needs BOTH `allowNonLocalhost: true` AND a pairing token, and the ' +
+        'daemon needs that origin allow-listed (RETICLE_ALLOWED_ORIGINS). The app is running and ' +
+        'instrumented — it was turned away, so do not go looking for a stopped dev server.');
+}
 /** WS close codes + reasons the bridge sends to the SDK (1008 = policy violation, 1013 = try again later). */
 const WS_CLOSE = {
     TOO_MANY_HANDSHAKES: [1013, 'too many pending handshakes'],
@@ -135,6 +168,8 @@ export class Bridge {
      * authFailureReason.
      */
     #servedProjects = new Set();
+    /** Session ids already counted in the impact record - a reconnect is not a new session. */
+    #countedSessions = new Set();
     #allowedOrigins;
     #maxMessagesPerSecond;
     #maxSessions;
@@ -198,7 +233,7 @@ export class Bridge {
                 verifyClient: ({ origin }, done) => {
                     const allowed = this.#originAllowed(origin);
                     if (!allowed)
-                        log('origin_rejected', { origin: origin ?? 'missing' });
+                        this.#noteOriginRejected(origin);
                     done(allowed, 403, 'Forbidden');
                 },
             });
@@ -229,7 +264,7 @@ export class Bridge {
                 verifyClient: ({ origin }, done) => {
                     const allowed = this.#originAllowed(origin);
                     if (!allowed)
-                        log('origin_rejected', { origin: origin ?? 'missing' });
+                        this.#noteOriginRejected(origin);
                     done(allowed, 403, 'Forbidden');
                 },
             });
@@ -244,12 +279,27 @@ export class Bridge {
                 });
             });
         }
+        // A PERMANENT 'error' listener, on top of the one `ready` installs and then removes.
+        //
+        // `ws` re-emits every 'error' from the server it is attached to, and both `ready` branches above
+        // drop their listener the moment the port is bound. From then on the emitter is bare, and an
+        // EventEmitter that emits 'error' with no listener THROWS — which in the daemon is an
+        // uncaughtException, which is an exit, which takes every agent and every session on this port
+        // with it. Logging one is all it takes; the transport itself needs no other reaction.
+        this.#wss.on('error', (err) => {
+            log('bridge_ws_error', { error: err.message });
+        });
         this.#wss.on('connection', (socket) => {
             this.#onConnection(socket);
         });
     }
     #onConnection(socket) {
         if (this.#pendingConnections >= this.#maxPendingConnections) {
+            // On the channel the no-session diagnosis reads, not only into the log. This refusal happens
+            // before any HELLO, so without it the dial leaves no trace at all — the same hole the origin
+            // gate had, and the same fix.
+            this.sessions.noteClosure(WS_CLOSE_REASON.HANDSHAKE_POOL_FULL, this.#clock());
+            log('bridge_handshake_pool_full', { pending: this.#pendingConnections });
             socket.close(...WS_CLOSE.TOO_MANY_HANDSHAKES);
             return;
         }
@@ -362,6 +412,16 @@ export class Bridge {
                 if (parsed.projectId !== undefined)
                     this.#servedProjects.add(parsed.projectId);
                 this.#onSessionCreate?.(session); // attach the durable journal before any events stream in
+                // A tab that has just connected has no impact record yet, so the report would read "nothing
+                // recorded" over a file with a month of history in it. Push what is already on disk as soon
+                // as there is somewhere to push it to; a session is also a thing that HAPPENED, so it counts.
+                // A reconnecting tab keeps its id, so counting every connect made a page reload look like
+                // a fresh session - the number climbed while nothing new happened.
+                if (!this.#countedSessions.has(session.id)) {
+                    this.#countedSessions.add(session.id);
+                    recordImpact({ sessions: 1 });
+                }
+                session.pushImpact(impactSnapshot, true);
                 const replaced = this.sessions.add(session);
                 if (replaced !== undefined) {
                     // Name the newcomer. A field report had a live session vanish during `reticle_lease` and the
@@ -374,6 +434,10 @@ export class Bridge {
                         byUrl: session.url,
                         previousUrl: replaced.url,
                     });
+                    // Hand the displaced session its replacement BEFORE ending it, so a tool call still holding
+                    // the old handle can finish against the live connection instead of returning an error whose
+                    // only answer is to go and rediscover an id that has not changed. See Session.succeededBy.
+                    replaced.succeededBy(session);
                     replaced.disconnect(`session replaced by a newer connection claiming the same id (${session.id}) from ${session.url}`);
                 }
                 // The daemon is the single judge of skew, and HELLO is where the page announces itself.
@@ -448,6 +512,20 @@ export class Bridge {
             log('socket_error', { error: err.message });
         });
     }
+    /**
+     * Record a refused dial where something OTHER than the daemon log can read it.
+     *
+     * The log line stays — it is the forensic record — but a line in `~/.reticle/daemon-<port>.log` is
+     * invisible to the agent that is, at that exact moment, being told "no browser session connected"
+     * with no reason attached. `noteClosure` is the channel the no-session diagnosis already reads, so
+     * the refusal now travels the same route as an auth failure and a protocol mismatch, and the loop
+     * (the reason is only in the page console; the console needs a session; the refusal prevents one)
+     * is broken from the daemon side.
+     */
+    #noteOriginRejected(origin) {
+        log('origin_rejected', { origin: origin ?? 'missing' });
+        this.sessions.noteClosure(originRejectedReason(origin), this.#clock());
+    }
     #originAllowed(origin) {
         // A real browser SDK connection always carries an Origin. A missing Origin means a non-browser
         // local process (another app, a malicious npm postinstall, an extension's native host) — untrusted

package/dist/bridge/bridge.test-harness.d.ts

@@ -25,6 +25,11 @@ export declare class FakeBrowser {
         name: string;
         args: Record<string, unknown>;
     }[];
+    /** The snapshot tree to return. Mutable so tests can vary the page between calls. */
+    snapshotResult: {
+        tree: string;
+        status: Record<string, unknown>;
+    };
     constructor(port: number, sessionId: string, hasCapabilities?: boolean);
     open(): Promise<void>;
     /** Re-send the HELLO on the live socket, the way the SDK does when capabilities register late. */

package/dist/bridge/bridge.test-harness.js

@@ -32,6 +32,11 @@ export class FakeBrowser {
     queryResolves = true;
     /** Records every command the bridge sent (for replay assertions). */
     received = [];
+    /** The snapshot tree to return. Mutable so tests can vary the page between calls. */
+    snapshotResult = {
+        tree: '- button "Pay" (ref=e7)\n- dialog "Order confirmed" (ref=e12)',
+        status: { route: '/checkout' },
+    };
     constructor(port, sessionId, hasCapabilities = false) {
         this.sessionId = sessionId;
         this.hasCapabilities = hasCapabilities;
@@ -147,10 +152,7 @@ export class FakeBrowser {
             };
         }
         else if (name === ReticleCommand.SNAPSHOT) {
-            result = {
-                tree: '- button "Pay" (ref=e7)\n- dialog "Order confirmed" (ref=e12)',
-                status: { route: '/checkout' },
-            };
+            result = this.snapshotResult;
         }
         else if (name === ReticleCommand.CAPABILITIES) {
             if (!this.handlesCapabilities) {

package/dist/capsule/capsule-store.d.ts

@@ -31,19 +31,19 @@ export declare const CapsuleSchema: z.ZodObject<{
     /** Minimal steps to reproduce (prefix-trimmed). */
     steps: z.ZodArray<z.ZodType<FlowStep, z.ZodTypeDef, FlowStep>, "many">;
 }, "strip", z.ZodTypeAny, {
+    expected: string;
     origin: string;
     version: 1;
     id: string;
-    expected: string;
     observed: string;
     steps: FlowStep[];
     createdAt: number;
     flow?: string | undefined;
 }, {
+    expected: string;
     origin: string;
     version: 1;
     id: string;
-    expected: string;
     observed: string;
     steps: FlowStep[];
     createdAt: number;

package/dist/capsule/causal-summary.d.ts

@@ -65,6 +65,21 @@ export interface CausalSummary {
     signals: string[];
     layoutShift?: number;
     longTasks: number;
+    /**
+     * TRUE when no store was subscribed, so `statePathsChanged`/`stateDiffs` are empty because nothing
+     * was watching — not because the app changed nothing.
+     *
+     * The two readings are the same empty list, and the wrong one is the one an agent takes: "state
+     * did not change" is a claim about the app, and this codebase would rather say "I could not see"
+     * than say something confident and wrong. Present only when the channel is dark, so a wired app
+     * pays nothing and the field's PRESENCE is what carries the meaning — the same rule
+     * `stateSettleMs` and `elided` follow.
+     */
+    stateUnwatched?: true;
+}
+/** What only the SESSION knows — level facts the event window cannot contain. See `stateUnwatched`. */
+export interface SummaryContext {
+    stateUnwatched?: boolean;
 }
 /**
  * THE INVARIANT: every field of this summary has a bounded size that does not depend on how much the
@@ -80,5 +95,5 @@ export interface CausalSummary {
 export declare const MAX_SUMMARY_ENTRIES = 20;
 /** The lists that are capped, named so `elided` can say which one lost entries. */
 type CappedList = 'statePathsChanged' | 'storageKeysChanged' | 'stateDiffs' | 'storageDiffs' | 'signals';
-export declare function causalSummary(events: readonly ReticleEvent[]): CausalSummary;
+export declare function causalSummary(events: readonly ReticleEvent[], context?: SummaryContext): CausalSummary;
 export {};

package/dist/capsule/causal-summary.js

@@ -56,7 +56,7 @@ function stateSettle(diffs) {
     const spread = Math.max(...times) - Math.min(...times);
     return spread > 0 ? { stateSettleMs: spread } : {};
 }
-export function causalSummary(events) {
+export function causalSummary(events, context = {}) {
     let netTotal = 0;
     let netErrors = 0;
     let ignoredDevTooling = 0;
@@ -160,5 +160,6 @@ export function causalSummary(events) {
         ...(0 === Object.keys(elided).length ? {} : { elided }),
         ...(layoutShift === undefined ? {} : { layoutShift }),
         longTasks,
+        ...(true === context.stateUnwatched ? { stateUnwatched: true } : {}),
     };
 }

package/dist/cli/cli-doctor.js

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ReticleEnv } from '@reticlehq/core';
 import { readPid, reticleStateHome } from '../daemon/daemon.js';
@@ -6,13 +6,17 @@ import { PortPresence, probePresence } from '../daemon/port-presence.js';
 import { probeDaemon } from '../mcp/mcp-proxy.js';
 import { fetchStatus } from './cli-launch.js';
 import { daemonLine } from './doctor-daemon-line.js';
+import { projectWiringLine } from './doctor-project-line.js';
+import { hasProjectConnectedBefore } from '../session/connection-memory.js';
 import { sessionsLine } from './doctor-sessions-line.js';
 import { captureLookup, describeForeignHolder, findPortHolder } from './port-holder.js';
 import { chromiumHint, probeChromium } from './chromium-hint.js';
 import { SERVER_VERSION } from '../version/server-version.js';
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { diagnoseDesktop, isDesktopProject } from '../init/desktop-doctor.js';
-import { diagnosePortMismatch, readProjectPort } from './cli-port.js';
+import { diagnoseWebCsp } from '../init/csp-doctor.js';
+import { RETICLE_CONFIG_BASENAME, diagnosePortMismatch, readProjectId, readProjectPort, } from './cli-port.js';
+import { DoctorRow, doctorRow } from './doctor-rows.js';
 /**
  * `reticle doctor` — collapse the ~6 independent first-run failure modes into one command. Checks the
  * Chromium install (the #1 silent failure), whether a daemon is up on the resolved bridge port, and
@@ -41,11 +45,11 @@ export async function handleDoctor(port) {
         process.stdout.write(`${s}\n`);
     };
     line('reticle doctor');
-    line(`  node         ${process.version}`);
+    line(doctorRow(DoctorRow.NODE, process.version));
     // Filled in only on the daemon branch — there is nothing to ask when no daemon is answering, and
     // the branches below already say so in their own terms.
     let sessions;
-    line(`  chromium     ${chromiumHint(await probeChromium())}`);
+    line(doctorRow(DoctorRow.CHROMIUM, chromiumHint(await probeChromium())));
     // Ask the PORT, not just the pid file. "not running on :4400" has been printed about a port that
     // was demonstrably occupied, which sends the reader to start a daemon that cannot bind. The three
     // states are genuinely different problems with different fixes, so doctor names which one it is.
@@ -63,7 +67,7 @@ export async function handleDoctor(port) {
         });
         line(built.text);
         if (built.skew !== undefined)
-            line(`  version      ✗ ${built.skew}`);
+            line(doctorRow(DoctorRow.VERSION, `✗ ${built.skew}`));
         // The same payload already carries whether anything has CONNECTED, and doctor was reading
         // `version` off it and dropping the rest. Without this the command is silent on the one step the
         // funnel stalls on: wired correctly, daemon up, and no page has ever dialled in.
@@ -75,24 +79,35 @@ export async function handleDoctor(port) {
         // pipeline that also kills the agent's own MCP proxy.
         // `pid` is what our pid file recorded for this port. When it matches the process actually
         // holding it, this is our OWN daemon wedged, not a stranger — and the fix is different.
-        line(`  daemon       ✗ ${describeForeignHolder(port, findPortHolder(port, captureLookup), pid)}`);
+        line(doctorRow(DoctorRow.DAEMON, `✗ ${describeForeignHolder(port, findPortHolder(port, captureLookup), pid)}`));
     }
     else {
-        line(`  daemon       ✗ not running on :${port} — your agent runs \`reticle mcp\` (or \`reticle serve\`)`);
+        line(doctorRow(DoctorRow.DAEMON, `✗ not running on :${port} — your agent runs \`reticle mcp\` (or \`reticle serve\`)`));
     }
     if (sessions !== undefined)
         line(sessions.text);
-    line(`  bridge port  ${port}  (your app must dial THIS port, not your dev-server port)`);
+    line(doctorRow(DoctorRow.BRIDGE_PORT, `${port}  (your app must dial THIS port, not your dev-server port)`));
     const projectPort = readProjectPort(process.cwd());
     const mismatch = diagnosePortMismatch(port, projectPort);
     if (mismatch !== undefined)
-        line(`  port check   ✗ ${mismatch}`);
+        line(doctorRow(DoctorRow.PORT_CHECK, `✗ ${mismatch}`));
+    // The check this checklist was missing: is the APP wired, not just the tools. Everything above can
+    // be green in a project that has never been through `init`, and that combination is precisely the
+    // one `doctor` gets run to explain.
+    const projectId = readProjectId(process.cwd());
+    line(projectWiringLine({
+        projectId,
+        previouslyConnected: hasProjectConnectedBefore(reticleStateHome(), port, projectId),
+        // An absent config and a corrupt one both read back as "no id"; only this tells them apart,
+        // and telling somebody a file is missing while it sits in front of them is its own dead end.
+        configPresent: existsSync(join(process.cwd(), RETICLE_CONFIG_BASENAME)),
+    }));
     // Where to LOOK when something is wrong. The daemon has always written a structured log here and
     // nothing ever said so, so the first move in every investigation was reading source instead of
     // reading the log. `RETICLE_TRACE=1` turns the same stream into a per-stage trace — see
     // docs/debugging.md.
-    line(`  daemon log   ${join(reticleStateHome(), `daemon-${String(port)}.log`)}`);
-    line(`  tracing      ${ReticleEnv.TRACE}=1 on the daemon for per-stage timings in that log`);
+    line(doctorRow(DoctorRow.DAEMON_LOG, join(reticleStateHome(), `daemon-${String(port)}.log`)));
+    line(doctorRow(DoctorRow.TRACING, `${ReticleEnv.TRACE}=1 on the daemon for per-stage timings in that log`));
     // Below the checklist rather than inline: it is a paragraph, and a paragraph in the middle of a
     // column of one-line checks buries the checks under it. This is the daemon's own no-session
     // diagnosis, the same one an agent gets from an empty reticle_sessions.
@@ -112,10 +127,23 @@ export async function handleDoctor(port) {
             return undefined;
         }
     };
+    // The web sibling of the desktop findings below: a `connect-src` that excludes the bridge makes
+    // the browser refuse the WebSocket and report it in ITS console only, so every check above passes
+    // at an app that can never connect. Named, with the exact text to paste.
+    const csp = diagnoseWebCsp(readProjectFile, port);
+    if (csp.length > 0) {
+        line('');
+        line(`  csp          ✗ a Content-Security-Policy is blocking the Reticle bridge:`);
+        for (const finding of csp) {
+            line(`                 ${finding.file}`);
+            line(`                   ${finding.problem}`);
+            line(`                   fix: ${finding.fix}`);
+        }
+    }
     const desktop = diagnoseDesktop(readProjectFile, port);
     if (desktop.length > 0) {
         line('');
-        line(`  desktop      ✗ ${String(desktop.length)} issue(s) — the app will look fine and not work:`);
+        line(doctorRow(DoctorRow.DESKTOP, `✗ ${String(desktop.length)} issue(s) — the app will look fine and not work:`));
         for (const finding of desktop) {
             line(`                 ${finding.file}`);
             line(`                   ${finding.problem}`);
@@ -125,6 +153,6 @@ export async function handleDoctor(port) {
     else if (isDesktopProject(readProjectFile)) {
         // Say so explicitly. Silence would read as "not checked", which is the same ambiguity the
         // findings above exist to remove.
-        line('  desktop      ✓ desktop wiring looks right');
+        line(doctorRow(DoctorRow.DESKTOP, '✓ desktop wiring looks right'));
     }
 }

package/dist/cli/cli-flow-commands.js

@@ -19,7 +19,7 @@ import { formatBuddyStatus } from '../flows/buddy-status.js';
 import { CapsuleStore } from '../capsule/capsule-store.js';
 import { AssertionTiersStore } from '../flows/assertion-tiers-store.js';
 import { detectDowngrades } from '../flows/assertion-integrity.js';
-import { computeCoverage } from '../flows/coverage.js';
+import { computeCoverage, flowCoverageReport } from '../flows/coverage.js';
 import { createWatchBatcher } from '../flows/watch-batcher.js';
 import { watch } from 'node:fs';
 import { log } from '../log.js';
@@ -184,19 +184,19 @@ export async function handleGate(files, since) {
         const result = gateDecision({ affected, passing, flaky, downgraded, deleted });
         // Verified-surface coverage over flows: how much of the saved suite this run actually exercised.
         const coverage = computeCoverage({ testids: [], signals: [], flows: allFlows.map((f) => f.name) }, { testids: [], signals: [], flows: passing });
+        // A gate over an empty suite has not passed — it had nothing to check. Same rule the suite
+        // verdict already applies to `reticle verify`; see flowCoverageReport.
+        const flowCoverage = flowCoverageReport(coverage.flows);
+        const pass = result.pass && flowCoverage.outcome === undefined;
         log('reticle_gate', {
-            pass: result.pass,
+            pass,
             uncovered: result.uncovered,
             quarantined: result.quarantined,
             ...(result.downgraded.length > 0 ? { downgraded: result.downgraded } : {}),
             ...(result.deleted.length > 0 ? { deletedCoverage: result.deleted } : {}),
-            coverage: {
-                pct: coverage.flows.pct,
-                covered: coverage.flows.covered,
-                total: coverage.flows.total,
-            },
+            coverage: flowCoverage,
         });
-        if (!result.pass)
+        if (!pass)
             process.exitCode = 1;
     }
     catch (error) {

package/dist/cli/cli-launch.d.ts

@@ -1,4 +1,3 @@
-import { PortPresence } from '../daemon/port-presence.js';
 /**
  * CLI launch + status helpers — the daemon-introspection (`reticle status`) and the one-command
  * "show me the app" flow (`reticle open`). Split out of cli.ts so that file stays under the size cap.
@@ -30,22 +29,6 @@ export declare function summarizeStatus(payload: unknown): {
  * another agent's session on a version bump, which is worse than a loud line.
  */
 export declare function warnOnDaemonSkew(port: number): Promise<void>;
-/**
- * Why `reticle drive` cannot have the port, or undefined when it can. Pure.
- *
- * `drive` bound the port unconditionally, and a daemon already listening on it is the NORMAL state
- * once any MCP client has started one. The bind died with a raw `node:net` stack trace: the one
- * failure in this CLI that answered a user with a Node core dump rather than a structured Reticle
- * line naming the port. It is also the command Reticle itself recommends — `reticle_sessions`
- * returns "run `reticle drive <url>`" whenever a tab is throttled, and a throttled tab nearly always
- * coexists with the running daemon that makes the bind impossible.
- *
- * The `reticle_lease` suggestion is deliberately first: it needs no free port, it is what the
- * daemon's own no-session diagnostic already points at, and it works while the collision stands.
- */
-export declare function drivePortConflict(presence: PortPresence, port: number, holder?: {
-    ourPid: number | null;
-}): string | undefined;
 /** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
 export declare function fetchStatus(port: number): Promise<unknown>;
 /** What `reticle open` should do: reuse an already-connected tab, open a new one, or ask for a url. */

package/dist/cli/cli-launch.js

@@ -6,7 +6,6 @@ import { describeSkew, DAEMON_FIX } from '../version/version-skew.js';
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { SERVER_VERSION } from '../version/server-version.js';
 import { log } from '../log.js';
-import { PortPresence, describePresence } from '../daemon/port-presence.js';
 /**
  * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
  * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
@@ -65,33 +64,6 @@ export async function warnOnDaemonSkew(port) {
     if (skew !== undefined)
         log('reticle_daemon_skew', { port, warning: skew });
 }
-/**
- * Why `reticle drive` cannot have the port, or undefined when it can. Pure.
- *
- * `drive` bound the port unconditionally, and a daemon already listening on it is the NORMAL state
- * once any MCP client has started one. The bind died with a raw `node:net` stack trace: the one
- * failure in this CLI that answered a user with a Node core dump rather than a structured Reticle
- * line naming the port. It is also the command Reticle itself recommends — `reticle_sessions`
- * returns "run `reticle drive <url>`" whenever a tab is throttled, and a throttled tab nearly always
- * coexists with the running daemon that makes the bind impossible.
- *
- * The `reticle_lease` suggestion is deliberately first: it needs no free port, it is what the
- * daemon's own no-session diagnostic already points at, and it works while the collision stands.
- */
-export function drivePortConflict(presence, port, holder) {
-    if (presence !== PortPresence.DAEMON && presence !== PortPresence.FOREIGN)
-        return undefined;
-    if (PortPresence.FOREIGN === presence)
-        return describePresence(presence, port);
-    const pid = holder?.ourPid;
-    const who = pid !== null && pid !== undefined
-        ? `a Reticle daemon (pid ${String(pid)}) is already serving :${String(port)}`
-        : `a Reticle daemon is already serving :${String(port)}`;
-    return (`${who}, so \`drive\` cannot bind that port. Use the daemon that is already there — its ` +
-        '`reticle_lease` tool opens a browser Reticle drives itself and needs no free port — or stop ' +
-        'it with `reticle stop` and retry, or drive on another port with `RETICLE_PORT=N` (`drive` ' +
-        'takes the port from the environment or .reticle.json, not from a flag).');
-}
 /** How long the daemon /status probe waits before giving up — a local loopback call is near-instant. */
 const STATUS_PROBE_TIMEOUT_MS = 1000;
 /** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */

package/dist/cli/cli-parse.d.ts

@@ -13,7 +13,7 @@ export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from '.
  * telling readers to do exactly that on 110 lines before it was caught, so the invocation now leads
  * the usage block rather than being a footnote somewhere else.
  */
-export declare const CLI_USAGE = "usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)\n\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)\n                --app picks WHICH app in a monorepo, when several are found\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)\n  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)\n  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)\n  reticle status [--port N]\n  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode, for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't; prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle Cloud; runs/flows recorded on the dashboard):\n  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push                                          (send local run artifacts to the dashboard)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
+export declare const CLI_USAGE = "usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)\n\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)\n                --app picks WHICH app in a monorepo, when several are found\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)\n  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)\n  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)\n  reticle status [--port N]\n  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode, for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't; prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle Cloud; runs/flows recorded on the dashboard):\n  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push                                          (send local run artifacts to the dashboard)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export declare const TelemetryAction: {
     readonly STATUS: "status";

package/dist/cli/cli-parse.js

@@ -40,7 +40,7 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
   reticle license                                      (show enterprise license status: active | eval | missing)
   reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)
   reticle feedback [--rating 1-5] [--bug] "message"    (tell us what worked and what didn't; prints exactly what it sends)
-  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "message"
+  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> "message"
                                                        (agents: file from anywhere, including a setup that never finished)
   reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]
                                                        (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)

package/dist/cli/cli-port.d.ts

@@ -7,6 +7,21 @@
  * 3..reticle.json "port" field in the cwd ← per-project isolation
  * 4. RETICLE_DEFAULT_PORT (4400)
  */
+/** The project config `reticle init` writes. */
+export declare const RETICLE_CONFIG_BASENAME = ".reticle.json";
+/**
+ * Find the nearest `.reticle.json` at or above `cwd`, and return its parsed contents.
+ *
+ * Every reader below used to join the basename onto `cwd` and stop there, so a process whose
+ * working directory was one level away from the config behaved exactly like a project that had
+ * never been through `init`: no port, no projectId, no journal setting, and a diagnostic that told
+ * the user to run an install they had already run. That is the shape of several field reports at
+ * once — an app wired in a subdirectory, an agent running from a repo root, a worktree beside its
+ * main checkout — and they are all the same missing walk.
+ *
+ * Returns undefined when nothing is found, which keeps every caller's existing default intact.
+ */
+export declare function findProjectConfig(cwd: string): Record<string, unknown> | undefined;
 /**
  * Ports that belong to a DEV SERVER, not to Reticle's bridge. Next defaults to 3000, Vite to 5173,
  * Astro to 4321, and so on.
@@ -33,6 +48,15 @@ export declare function readProjectPort(cwd: string): number | undefined;
  * undefined if the file is absent/unreadable or has no non-empty string projectId.
  */
 export declare function readProjectId(cwd: string): string | undefined;
+/**
+ * The framework `reticle init` stamped into `.reticle.json`, when there is one.
+ *
+ * Read so the no-session diagnosis can RANK its causes instead of printing one static differential.
+ * Nuxt is the case that pays for this: it does not register a newly added plugin on HMR, so a dev
+ * server older than the wiring is its single most likely cause — `init` warns about it at install
+ * time and the hint the agent reads hours later never mentioned it.
+ */
+export declare function readProjectFramework(cwd: string): string | undefined;
 /**
  * Whether the durable causal journal is enabled. On by default (the journal IS the loop); off only via
  * explicit opt-out — `.reticle.json` `"journal": false`, or `RETICLE_JOURNAL` set to `0`/`false`. The env