@reticlehq/server 2.6.0 → 2.8.0

package/dist/init/snippets.js

@@ -3,6 +3,28 @@
  * so the runner never inlines free strings.
  */
 import { RETICLE_DEFAULT_PORT, bridgeWsUrl } from '@reticlehq/core';
+import { UiLibrary } from './detect.js';
+import { SERVER_VERSION } from '../version/server-version.js';
+/**
+ * The SDK as one import a plain page can actually resolve.
+ *
+ * `init` used to tell static-HTML users that a page with no build step could not load the SDK, and
+ * to go and stand up a bundler. That is true of a BARE specifier and false of a URL, and the
+ * difference was the whole road for every server-rendered app we hear from: FastAPI, Flask, Django,
+ * Streamlit, Rails. Proven end to end before this shipped, on a page served by `python3 -m
+ * http.server`: a session connected, a snapshot returned, and two act_and_wait calls came back
+ * `verified: "yes"`.
+ *
+ * jsDelivr rather than esm.sh, measured: a third of the requests and a third of the bytes for the
+ * same result. `/+esm` is what makes it work, and the bare package URL does NOT: every file in
+ * `dist` carries bare specifiers for `@reticlehq/core` and `@testing-library/dom`, so an unbundled
+ * entry point dies on the first import. That is also why adding `unpkg`/`jsdelivr` fields to
+ * package.json would not help.
+ *
+ * PINNED to this server's version on purpose. A floating import upgrades the page SDK underneath a
+ * daemon that did not move, which is `version_skew` arriving by a route nothing checks.
+ */
+const CDN_SDK_URL = `https://cdn.jsdelivr.net/npm/@reticlehq/browser@${SERVER_VERSION}/+esm`;
 /**
  * The connect argument literal: a non-default port adds a `url`, and a projectId is always passed
  * (so the app is identifiable across port changes). Empty string only when neither applies.
@@ -16,18 +38,76 @@ function connectArg(port, projectId) {
         parts.push(`projectId: '${projectId}'`);
     return parts.length > 0 ? `{ ${parts.join(', ')} }` : '';
 }
+/**
+ * The same literal, with the pairing token folded in.
+ *
+ * The token belongs INSIDE the call the user pastes. Every other stack has a build step to inline
+ * it (the Vite plugin's `define`, Next's NEXT_PUBLIC_*, Astro's config, CRA's .env); the hand-wired
+ * paths have none, so `init` inlines the literal it already read. Without it the bridge closes the
+ * socket with AUTH_FAILED and no session ever appears: see Bridge's hello handler.
+ *
+ * An empty token is omitted rather than emitted as `token: ''`. A daemon that could not write to
+ * $HOME runs without auth and trusts loopback, and an empty string would fail the comparison against
+ * one that does hold a token.
+ */
+export function connectArgWithToken(port, projectId, pairingToken) {
+    const base = connectArg(port, projectId);
+    if (pairingToken === undefined || 0 === pairingToken.length)
+        return base;
+    const inner = base.length > 0 ? base.slice(1, -1).trim() : '';
+    return `{ ${[inner, `token: '${pairingToken}'`].filter((p) => p.length > 0).join(', ')} }`;
+}
+/**
+ * Which SDK package the GENERATED code should import, and whether `install()` applies.
+ *
+ * This has to agree with `frameworkPackages`, and it did not. That function was changed so a Vue or
+ * Svelte app installs `@reticlehq/browser` instead of the React adapter — correctly — while every
+ * generated connect snippet still said `import('@reticlehq/react')`. A SvelteKit app would have
+ * installed the sensor and then run a hook importing a package that is not there.
+ *
+ * `install()` is the React adapter's, not the sensor's: `@reticlehq/browser` exports `reticle` and no
+ * `install`, so swapping the specifier alone would trade a missing module for a missing export.
+ */
+export function sdkImport(uiLibrary) {
+    const react = uiLibrary !== UiLibrary.VUE && uiLibrary !== UiLibrary.SVELTE;
+    return react
+        ? { specifier: '@reticlehq/react', usesInstall: true }
+        : { specifier: '@reticlehq/browser', usesInstall: false };
+}
+/**
+ * The framework plugin to show ALONGSIDE reticle() in the example, so the ordering is clear.
+ *
+ * It used to be `react()` unconditionally, which is what a Vue app was shown — a plugin it does not
+ * have, four lines after `init` had correctly detected Vue and said so. The example exists to show
+ * that `reticle()` goes last, not to tell anyone which UI framework they are using.
+ */
+function frameworkPluginExample(uiLibrary) {
+    switch (uiLibrary) {
+        case UiLibrary.VUE:
+            return 'vue()';
+        case UiLibrary.SVELTE:
+            return 'svelte()';
+        case UiLibrary.REACT:
+        case UiLibrary.PREACT:
+            return 'react()';
+        default:
+            // Nothing detected: name no plugin rather than invent one. The reader keeps whatever they have.
+            return '/* your existing plugins */';
+    }
+}
 /** The Vite-config snippet printed when we can't safely auto-patch the config. */
-export function viteManual(port) {
+export function viteManual(port, uiLibrary = UiLibrary.UNKNOWN) {
     const call = port === undefined ? 'reticle()' : `reticle({ port: ${String(port)} })`;
     return `Add the Reticle plugin to your Vite config:
 
   import { reticle } from '@reticlehq/vite-plugin';
 
   export default defineConfig({
-    plugins: [react(), ${call}],
+    plugins: [${frameworkPluginExample(uiLibrary)}, ${call}],
   });
 
-The plugin only applies during \`vite\` (dev) — it is dropped from \`vite build\`.`;
+Keep \`reticle()\` LAST so it sees the output of your other plugins. It only applies during \`vite\`
+(dev) — it is dropped from \`vite build\`.`;
 }
 /** Next.js config wrap — always printed (we never auto-rewrite next.config). */
 export function nextConfigManual(configFile) {
@@ -45,21 +125,27 @@ export function nextConfigManual(configFile) {
  * as `NEXT_PUBLIC_RETICLE_TOKEN`. This file used to connect with only a projectId, so every Next
  * setup ended at `bridge refused the connection: authentication failed` and no session ever appeared.
  */
-export function nextReticleDevFile(port, projectId, testids = [], stores = []) {
+export function nextReticleDevFile(port, projectId, testids = [], stores = [], found = []) {
     const base = connectArg(port, projectId);
     const fields = '' === base ? '' : `${base.slice(1, -1).trim()}, `;
     const ids = testids.map((t) => `'${t}'`).join(', ');
-    const storeBlock = 0 === stores.length
-        ? '      // No state library detected. If you add one, register it here — see docs/usage.md.'
-        : stores.map((h) => `      // import your store, then: ${h}`).join('\n');
+    // Same rule as the Vite module: a store we found is registered outright, and the commented hint
+    // survives only for the libraries we can name but not wire.
+    const storeImports = found.map((s) => `import { ${s.ident} } from '${s.importPath}';`).join('\n');
+    const storeBlock = found.length > 0
+        ? found.map((s) => `      registerStore('${s.key}', ${s.ident});`).join('\n')
+        : 0 === stores.length
+            ? '      // No state library detected. If you add one, register it here — see node_modules/@reticlehq/server/docs/usage.md.'
+            : stores.map((h) => `      // import your store, then: ${h}`).join('\n');
     return `'use client';
 import { useEffect } from 'react';
+${storeImports.length > 0 ? storeImports : ''}
 
 /** Dev-only: connect Reticle + install the React adapter, after hydration. */
 export function ReticleDev() {
   useEffect(() => {
     if (process.env.NODE_ENV !== 'development') return;
-    void import('@reticlehq/react').then(({ reticle, install, registerCapabilities }) => {
+    void import('@reticlehq/react').then(({ reticle, install, registerCapabilities${found.length > 0 ? ', registerStore' : ''} }) => {
       install();
       // Both provided by withReticle() in next.config. The bridge rejects a connect with no token;
       // the root makes source paths repo-relative instead of absolute.
@@ -73,9 +159,9 @@ export function ReticleDev() {
       // form wires \`subscribe\` too, so every mutation emits a diff; the getter form is read-only.
 ${storeBlock}
       registerCapabilities({
-        testids: [${ids}],${0 === testids.length ? ' // none found — add data-testid to your key elements' : ''}
+        testids: [${ids}],${0 === testids.length ? ' // none found; add data-testid to your key elements' : ''}
         signals: [], // names you pass to reticle.signal()
-        stores: [], // the keys you registered above
+        stores: [${found.map((s) => `'${s.key}'`).join(', ')}], // the keys you registered above
       });
     });
   }, []);
@@ -171,15 +257,29 @@ Start the daemon BEFORE \`astro dev\`, so the token file exists when the config
  * breaks the module everything else hangs off. So the store lines are generated COMMENTED, naming
  * the libraries actually found in package.json, with the exact call to uncomment.
  */
-export function viteDevModuleFile(testids, stores) {
+export function viteDevModuleFile(testids, stores, found = [], uiLibrary = UiLibrary.REACT) {
+    // The specifier has to be the package `frameworkPackages` installed. This file is the Vite path —
+    // the commonest install there is — and it was hardcoded to `@reticlehq/react` while a Vue or
+    // Svelte app was being given `@reticlehq/browser`, so the generated file imported something that
+    // was not there. Caught by running `init` against a pristine Vue app, not by any gate.
+    //
+    // The sensor exports `registerCapabilities` and `registerStore` (and the store adapters) just as
+    // the React kit does; the only thing it lacks is `install()`, which this file never called.
+    const sdk = sdkImport(uiLibrary);
     const ids = testids.map((t) => `'${t}'`).join(', ');
-    const storeBlock = 0 === stores.length
-        ? '  // No state library detected. If you add one, register it here — see docs/usage.md.'
-        : stores.map((h) => `  // import your store, then: ${h}`).join('\n');
-    return `// Dev-only. Imported automatically by @reticlehq/vite-plugin — you do not need to import it.
+    // A store we FOUND is imported and registered outright — the whole point of the file. The hints
+    // stay only for the libraries we can name but not wire (they need an argument we cannot infer).
+    const storeImports = found.map((s) => `import { ${s.ident} } from '${s.importPath}';`).join('\n');
+    const storeBlock = found.length > 0
+        ? found.map((s) => `  registerStore('${s.key}', ${s.ident});`).join('\n')
+        : 0 === stores.length
+            ? '  // No state library detected. If you add one, register it here — see node_modules/@reticlehq/server/docs/usage.md.'
+            : stores.map((h) => `  // import your store, then: ${h}`).join('\n');
+    const registerImport = found.length > 0 ? 'registerCapabilities, registerStore' : 'registerCapabilities';
+    return `// Dev-only. Imported automatically by @reticlehq/vite-plugin, so you do not need to import it.
 // Self-guards on import.meta.env.DEV, so it is a no-op in a production build.
-import { registerCapabilities } from '@reticlehq/react';
-
+import { ${registerImport} } from '${sdk.specifier}';
+${storeImports.length > 0 ? `${storeImports}\n` : ''}
 if (import.meta.env.DEV) {
   // ── Start with ONE flow. ─────────────────────────────────────────────────────────────────────
   // You do not need to describe the whole app to get value, and trying to is the slow path. Register
@@ -193,9 +293,9 @@ if (import.meta.env.DEV) {
 ${storeBlock}
 
   registerCapabilities({
-    testids: [${ids}],${0 === testids.length ? ' // none found — add data-testid to your key elements' : ''}
+    testids: [${ids}],${0 === testids.length ? ' // none found; add data-testid to your key elements' : ''}
     signals: [], // names you pass to reticle.signal()
-    stores: [], // the keys you registered above
+    stores: [${found.map((s) => `'${s.key}'`).join(', ')}], // the keys you registered above
   });
 }
 `;
@@ -216,23 +316,49 @@ export const NEXT_LAYOUT_MANUAL = `Mount <ReticleDev /> in your root layout (app
  * where a bare `@reticlehq/react` import resolves. A bare import in a plain index.html does NOT resolve in
  * the browser, so we never tell a bundled app to do that (the old advice silently failed for CRA).
  */
-export function htmlManual(port, projectId) {
-    const arg = connectArg(port, projectId);
+/**
+ * The whole install, for a page with no build step, as one block a person can paste.
+ *
+ * Extracted so the `no package.json` exit can print the SAME snippet `htmlManual` offers. That exit
+ * is the one every server-rendered app reaches (FastAPI, Flask, Django, Rails, Streamlit), it is
+ * where `init` stops, and until now it stopped with an explanation instead of an answer. A message
+ * that says "add the snippet below" and then prints no snippet is the same defect wearing the
+ * opposite sign, so the two share a builder rather than a copy.
+ */
+export function staticPageSnippet(connectArgLiteral) {
+    return `      <script type="module">
+        import { reticle } from '${CDN_SDK_URL}';
+        reticle.connect(${connectArgLiteral});
+      </script>`;
+}
+export function htmlManual(port, projectId, pairingToken) {
+    const withToken = connectArgWithToken(port, projectId, pairingToken);
+    const tokenNote = pairingToken === undefined || 0 === pairingToken.length
+        ? ''
+        : `\n\n  The \`token\` is this machine's pairing token, read from ~/.reticle/pairing-token. Keep it: the
+  bridge REJECTS a connect without it ("authentication failed") and no session appears. It is
+  per-machine and local-only, so do not commit it — a teammate's daemon mints their own.`;
     return `No Vite/Next plugin detected — wire the dev-only connect by hand. Pick the form for your setup:
 
   • Bundled app (Create React App, webpack, Parcel, Vue/Svelte CLI, etc.) — add to your ENTRY module
     (e.g. src/index.js or src/main.js), where '@reticlehq/react' resolves through your bundler:
 
-      if (window.location.hostname === 'localhost') {
+      if (process.env.NODE_ENV !== 'production') {
         void import('@reticlehq/react').then(({ reticle, install }) => {
           install();
-          reticle.connect(${arg});
+          reticle.connect(${withToken});
         });
-      }
+      }${tokenNote}
+
+  • Plain HTML with NO build step (FastAPI, Flask, Django, Rails, Streamlit, a hand-written page) —
+    paste this into the page, in a template you only serve in development. There is nothing to
+    install: no npm, no bundler, no package.json.
+
+${staticPageSnippet(withToken)}
 
-  • Plain static HTML with no build step — the browser can't resolve the bare '@reticlehq/react' import, so
-    bundle the SDK once (e.g. \`npx esbuild\`) and point a dev-only <script type="module"> at the output,
-    or serve the page through a dev server (Vite) that resolves bare imports.`;
+  Serving the app on something other than localhost (a hosts-file alias, a LAN IP, a container, a
+  tunnel)? Add \`allowNonLocalhost: true\` to the connect. Without it the SDK refuses to dial and says
+  so in the browser console only, so from here it looks exactly like nothing happened.`;
 }
 export const NEXT_RETICLE_DEV_PATH = 'app/reticle-dev.tsx';
 export const SVELTEKIT_HOOKS_PATH = 'src/hooks.client.ts';
@@ -247,7 +373,15 @@ export const SVELTEKIT_HOOKS_PATH = 'src/hooks.client.ts';
  * here is the one thing this project exists not to do.
  */
 export function unverifiedUiLibraryNote(library) {
-    return `Detected a ${library} app. Reticle's DOM, network, console and state tools work here, and source file:line does too — the build plugin stamps data-reticle-source regardless of UI library (measured on preact and svelte). What @reticlehq/react adds and you will NOT get is React component identity: component names and component stacks. No CI gate covers ${library}. Gated today: Vite + React, Next.js, Remix, Astro. If something doesn't work, please open an issue.`;
+    // Preact is not in the same position as Vue or Svelte and must not be told it is. The React
+    // adapter reaches Preact through `preact/compat`, which is what `docs/frameworks.mdx` has always
+    // said, so telling a Preact reader they get no component identity contradicts our own docs and
+    // talks them out of a package that is the right one for them. It is still ungated, which is the
+    // honest caveat, and #129 is the issue for closing that.
+    const identity = 'preact' === library
+        ? 'React component identity — component names and stacks — comes from `@reticlehq/react`, which reaches Preact through `preact/compat`. That path is not covered by a CI gate here, so treat it as expected-to-work rather than proven.'
+        : 'What `@reticlehq/react` adds and you will NOT get is React component identity: component names and component stacks.';
+    return `Detected a ${library} app. Reticle's DOM, network, console and state tools work here. ${'vue' === library ? 'Source `file:line` does NOT come through: the build plugin stamps JSX and, separately, Svelte components, and a Vue single-file component is neither — measured, a Svelte counter reports `src/lib/Counter.svelte:5` and the same drive on Vue reports no source at all.' : 'Source `file:line` does too — the build plugin stamps it for this library (measured on preact and svelte).'} ${identity} ${'vue' === library ? 'The install gate scaffolds a Vue app from scratch on every change, so this SETUP is proven; no gate drives a Vue app to a verdict, so the drive is not.' : `No CI gate covers ${library}.`} Driven on every change: Vite + React, Next.js, Remix, Astro. If something doesn't work, please open an issue.`;
 }
 export const UNVERIFIED_FRAMEWORK_NOTE = 'Reticle has no SvelteKit app and no CI gate for one, so this wiring is untested — it may work, but nothing proves it and nothing will tell us if it breaks. Supported and gated today: Vite + React, Next.js, Remix and Astro. If the hook does not register a session, please open an issue.';
 /**
@@ -255,14 +389,18 @@ export const UNVERIFIED_FRAMEWORK_NOTE = 'Reticle has no SvelteKit app and no CI
  * never triggers Vite's index.html injection (verified), so the standard plugin can't auto-connect —
  * a client hook is the reliable path. SvelteKit runs src/hooks.client.ts on the client at startup.
  */
-export function svelteKitHooksFile(port, projectId) {
+export function svelteKitHooksFile(port, projectId, uiLibrary = UiLibrary.SVELTE) {
+    // SvelteKit is Svelte, so this defaults to the sensor rather than the React adapter — and the
+    // import here MUST match what `frameworkPackages` installed, or the hook loads a package that is
+    // not in node_modules. See sdkImport.
+    const sdk = sdkImport(uiLibrary);
     const base = connectArg(port, projectId);
     const fields = '' === base ? '' : `${base.slice(1, -1).trim()}, `;
     return `// Dev-only: connect Reticle on the client. SvelteKit renders via app.html, so the Vite-plugin
 // index.html injection doesn't fire — connect from this client hook instead.
 if (import.meta.env.DEV) {
-  void import('@reticlehq/react').then(({ reticle, install }) => {
-    install();
+  void import('${sdk.specifier}').then(({ reticle${sdk.usesInstall ? ', install' : ''} }) => {
+    ${sdk.usesInstall ? 'install();' : '// No React adapter here: the sensor has no install() to call.'}
     // The bridge requires the pairing token even on localhost. Nothing in a browser can read the
     // file it lives in, so @reticlehq/vite-plugin inlines it here at build time. Without it the
     // console reads "bridge refused the connection: authentication failed" and no session appears.
@@ -282,6 +420,57 @@ declare const __RETICLE_ROOT__: string | undefined;
 declare const __RETICLE_SDK_VERSION__: string | undefined;
 `;
 }
+/** Where a Nuxt dev-only client plugin belongs. `.client` keeps it out of SSR; Nuxt auto-registers it. */
+export const NUXT_PLUGIN_PATH = 'app/plugins/reticle.client.ts';
+/**
+ * The Nuxt recipe, written out in full because every trap in it is one somebody actually hit.
+ *
+ * Reported from the field, in the order they were hit: `init` classified a Nuxt 4 app as `html`, so
+ * it installed a package named `@reticlehq/react` (with `react` in its peer dependencies) into a Vue
+ * codebase — the reporter only continued after auditing our dist to confirm there are no React
+ * imports at runtime, which most people will not do. It then handed over a snippet guarded on
+ * `window.location.hostname === 'localhost'`, which fails twice over in Nuxt: `window` does not
+ * exist during SSR, and the dev host here was a hosts-file alias (required for the backend's
+ * white-label origin detection), so the guard was false and the connect never ran — no error, no log
+ * line, nothing to debug. And nothing said a running dev server does not pick up a new plugin.
+ *
+ * So: `import.meta.dev` (build-time, host-independent) instead of a hostname check, `.client.ts`
+ * instead of an SSR guard, the framework-neutral sensor instead of the React kit, the non-localhost
+ * flag named up front, and the restart said out loud.
+ */
+export function nuxtManual(port, projectId) {
+    const base = connectArg(port, projectId);
+    const fields = '' === base ? '' : base.slice(1, -1).trim();
+    const connect = '' === fields ? 'reticle.connect()' : `reticle.connect({ ${fields} })`;
+    return `Nuxt owns its own Vite instance and renders its own HTML, so there is no vite.config to patch
+and no index.html to inject into. Wire it with a dev-only CLIENT plugin, which is Nuxt's own idiom:
+
+1. Create ${NUXT_PLUGIN_PATH}:
+
+     export default defineNuxtPlugin(() => {
+       // import.meta.dev is the correct guard: it is resolved at build time, so it does not care
+       // what hostname you develop on. Do NOT guard on window.location.hostname === 'localhost' —
+       // that is false on any hosts-file alias or LAN address, and window does not exist in SSR.
+       if (!import.meta.dev) return
+       void import('@reticlehq/browser').then(({ reticle }) => {
+         ${connect}
+       })
+     })
+
+   The .client.ts suffix is load-bearing: it is what keeps this out of the server bundle.
+
+2. Restart the dev server. A dev server that is already running does not pick up a new plugin —
+   it will not appear in .nuxt/plugins/client.mjs, and the app will come up with no SDK at all.
+
+3. If your dev host is anything other than localhost (a hosts-file alias, a LAN IP, a tunnel), add
+   allowNonLocalhost: true to that connect call. Without it the SDK loads and then refuses, and the
+   only sign is one line in the browser console.
+
+The package is @reticlehq/browser — the framework-neutral sensor. DOM, network, console, routing and
+source file:line all work in Vue. What you do not get is React component identity, which is the only
+thing the React adapter adds. There is no Nuxt app in this project's CI, so this path is UNVERIFIED:
+if something does not work, please open an issue.`;
+}
 /**
  * Root-level project config for Reticle. Written by `reticle init`; read by `reticle mcp` for the port
  * and by tooling for the stable projectId (the app's identity across port changes).

package/dist/init/vite-config.js

@@ -15,6 +15,16 @@ function reticlePluginCall(port) {
 const PLUGINS_ARRAY = /plugins\s*:\s*\[/;
 /** Matches an ES import statement (used to place our import after the last one). */
 const IMPORT_LINE = /^import\s.+from\s+['"][^'"]+['"];?\s*$/gm;
+/**
+ * The opening `{` of the exported config object — `defineConfig({`, or a bare `export default {`.
+ * Used only when there is no `plugins` array to extend: the object is right there, so adding the
+ * key is the same edit as extending the array, and bailing sent a user whose config merely set
+ * `server.port` to a manual paste for a change we can make correctly.
+ *
+ * A config built by a call (`defineConfig(buildOptions())`) has no literal to extend and still
+ * bails — the rule stays "only edit a shape we can see whole".
+ */
+const CONFIG_OBJECT = /(export\s+default\s+(?:defineConfig\s*\(\s*)?)\{/;
 /** Alias kept so existing call sites read in Vite terms; the vocabulary is shared (see patch-kind). */
 export const VitePatchKind = PatchKind;
 const NO_PLUGINS_REASON = "couldn't find a `plugins: [...]` array to extend";
@@ -41,12 +51,28 @@ function insertPlugin(source, port) {
         return `${match}${reticlePluginCall(port)},${separator}`;
     });
 }
+/**
+ * Add a whole `plugins: [reticle()]` key to a config object that has none, matching the layout of
+ * the object it lands in: a multi-line object gets its own indented line, a one-liner stays inline.
+ */
+function insertPluginsKey(source, port) {
+    return source.replace(CONFIG_OBJECT, (_match, prefix, offset) => {
+        const rest = source.slice(offset + _match.length);
+        const multiline = /^\s*\n/.test(rest);
+        const indent = /^\s*\n(\s*)\S/.exec(rest)?.[1] ?? '  ';
+        const key = `plugins: [${reticlePluginCall(port)}],`;
+        return multiline ? `${prefix}{\n${indent}${key}` : `${prefix}{ ${key}`;
+    });
+}
 export function patchViteConfig(source, port) {
     if (source.includes(RETICLE_MARKER)) {
         return { kind: VitePatchKind.ALREADY };
     }
-    if (!PLUGINS_ARRAY.test(source)) {
-        return { kind: VitePatchKind.MANUAL, reason: NO_PLUGINS_REASON };
+    if (PLUGINS_ARRAY.test(source)) {
+        return { kind: VitePatchKind.APPLY, code: insertImport(insertPlugin(source, port)) };
+    }
+    if (CONFIG_OBJECT.test(source)) {
+        return { kind: VitePatchKind.APPLY, code: insertImport(insertPluginsKey(source, port)) };
     }
-    return { kind: VitePatchKind.APPLY, code: insertImport(insertPlugin(source, port)) };
+    return { kind: VitePatchKind.MANUAL, reason: NO_PLUGINS_REASON };
 }

package/dist/input/network-mock-tools.d.ts

@@ -1,2 +1,21 @@
+import type { MockRule } from './network-mock.js';
 import type { ToolDef } from '../tools/tools.js';
+/**
+ * Narrow the validated tool args into MockRule[], omitting undefined keys (exactOptionalPropertyTypes).
+ *
+ * THROWS on a malformed rule rather than falling back to `[]`, because `[]` is not a neutral value
+ * here — it is the documented way to clear every active mock. A rule with a wrong field name used to
+ * produce exactly the call that turns mocking OFF, and the handler then reported `applied: true`
+ * with `count: 0`. For a tool whose entire job is forcing an error state, that means the agent
+ * checks the app's failure handling against the real backend, sees the happy path, and reports that
+ * the error state works.
+ *
+ * Same rule as the action arguments: an argument that could not be understood is refused by name,
+ * never reinterpreted into a destructive default. A valueless `fill` used to wipe the field and
+ * report ok; it throws now, for this reason.
+ *
+ * `undefined` and `[]` still mean "clear" — those are deliberate, documented requests, not failures
+ * to parse.
+ */
+export declare function toRules(value: unknown): MockRule[];
 export declare const NETWORK_MOCK_TOOLS: ToolDef[];

package/dist/input/network-mock-tools.js

@@ -26,11 +26,36 @@ const ruleShape = z.object({
         .optional()
         .describe('Simulate a network failure (offline) instead of a response.'),
 });
-/** Narrow the validated tool args into MockRule[], omitting undefined keys (exactOptionalPropertyTypes). */
-function toRules(value) {
-    const parsed = z.array(ruleShape).safeParse(value);
-    if (!parsed.success)
+/**
+ * Narrow the validated tool args into MockRule[], omitting undefined keys (exactOptionalPropertyTypes).
+ *
+ * THROWS on a malformed rule rather than falling back to `[]`, because `[]` is not a neutral value
+ * here — it is the documented way to clear every active mock. A rule with a wrong field name used to
+ * produce exactly the call that turns mocking OFF, and the handler then reported `applied: true`
+ * with `count: 0`. For a tool whose entire job is forcing an error state, that means the agent
+ * checks the app's failure handling against the real backend, sees the happy path, and reports that
+ * the error state works.
+ *
+ * Same rule as the action arguments: an argument that could not be understood is refused by name,
+ * never reinterpreted into a destructive default. A valueless `fill` used to wipe the field and
+ * report ok; it throws now, for this reason.
+ *
+ * `undefined` and `[]` still mean "clear" — those are deliberate, documented requests, not failures
+ * to parse.
+ */
+export function toRules(value) {
+    if (value === undefined)
         return [];
+    const parsed = z.array(ruleShape).safeParse(value);
+    if (!parsed.success) {
+        const problem = parsed.error.issues
+            .map((i) => `${0 === i.path.length ? 'mocks' : `mocks.${i.path.join('.')}`}: ${i.message}`)
+            .join('; ');
+        throw new Error(`reticle_network_mock could not read \`mocks\` (${problem}). Nothing was applied and mocking ` +
+            'was left unchanged — an unreadable rule is NOT treated as a request to clear. A rule is ' +
+            '{ urlContains, method?, status?, body?, contentType?, delayMs?, abort? }; pass `clear: true` ' +
+            'or an empty array if you meant to turn mocking off.');
+    }
     return parsed.data.map((r) => {
         const rule = { urlContains: r.urlContains };
         if (r.method !== undefined)

package/dist/license/license.js

@@ -161,7 +161,7 @@ export function describeLicense(now, env = process.env, baked = BAKED_ISSUER_PUB
             }
             : {
                 status: 'eval',
-                detail: 'evaluation mode — enterprise features run free (no issuer key configured)',
+                detail: 'evaluation mode: enterprise features run free (no issuer key configured)',
             };
     }
     const publicKey = loadPublicKey(pem);

package/dist/mcp/mcp-proxy.d.ts

@@ -7,6 +7,45 @@ export declare const MAX_RECONNECT_ATTEMPTS: number;
 export declare function reconnectDelayMs(attempt: number): number;
 /** JSON-RPC id the proxy uses for its own replayed `initialize` — never one the client could send. */
 export declare const RECONNECT_INITIALIZE_ID = "__reticle_proxy_reinit";
+/**
+ * How much the proxy may append between size checks.
+ *
+ * Statting the file on every line would be a syscall per log line on a process that logs from a
+ * reconnect loop. Counting what we wrote costs nothing and is exact enough, because this process is
+ * the only writer of its own log. Well under the cap, so the cap is a cap rather than a suggestion.
+ */
+export declare const PROXY_LOG_CHECK_BYTES: number;
+/**
+ * Keep the proxy log under the same cap as the daemon log, without a stat per write.
+ *
+ * Returns the new "bytes since the last check" counter, so the accounting is testable without a
+ * filesystem. Rotation itself is `rotateDaemonLog` — the proxy log had no cap at all while the
+ * daemon log on the SAME machine stayed small, which is the whole of this defect.
+ */
+export declare function accountProxyLogWrite(bytesSinceCheck: number, written: number, path: string, deps: {
+    fileSize(p: string): number;
+    renameFile(from: string, to: string): void;
+}): number;
+/**
+ * Reclaim a proxy log that a previous process already let run away. Returns the bytes reclaimed.
+ *
+ * Reported from the field: one machine's `proxy-4400.log` reached a third of a 460GB disk and broke
+ * builds, Docker and ordinary shell commands with ENOSPC. Nothing in Reticle degraded first, so the
+ * failure surfaced as the operating system refusing to write files. Files like that exist on real
+ * machines now, and the cap alone does not help them: the user should not have to find one with `du`.
+ *
+ * TRUNCATED IN PLACE, never renamed or unlinked. A rename moves the bytes without reclaiming a byte,
+ * and a file that a running process still holds open keeps its blocks allocated after an unlink
+ * until that handle closes — which is why the reporter recovered with `: > ~/.reticle/proxy-4400.log`
+ * and why that is the operation to copy here.
+ *
+ * Best-effort, in the same spirit as `rotateDaemonLog`: refusing to start the MCP server over
+ * housekeeping is strictly worse than a large file.
+ */
+export declare function recoverOversizedProxyLog(path: string, deps: {
+    fileSize(p: string): number;
+    truncateFile(p: string): void;
+}, max?: number): number;
 /** Name the proxy log after the port it serves. Called before anything can log. */
 export declare function setProxyLogPort(port: number): void;
 /** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
@@ -56,9 +95,36 @@ export declare class PendingRequests {
  * daemon under a live client left 20 of 20 concurrent calls hanging until the client's own timeout,
  * with the MCP server still perfectly alive. An agent cannot tell that apart from "still working".
  */
-export declare function streamLossReplies(pending: PendingRequests, reason: string): string[];
-/** The one shape every "the transport ate your call" answer takes, whichever leg died. */
-export declare function transportLossReply(id: unknown, reason: string): string;
+export declare function streamLossReplies(pending: PendingRequests, reason: string, nextStep?: string): string[];
+/**
+ * The one shape every "the transport ate your call" answer takes, whichever leg died.
+ *
+ * `nextStep` is appended when the caller knows one. Without it this reply describes a condition and
+ * stops there, which is all a first-run user got out of their first ever tool call.
+ */
+export declare function transportLossReply(id: unknown, reason: string, nextStep?: string): string;
+/**
+ * How long a request may sit in the queue, unsent, before the proxy answers it itself.
+ *
+ * The second population the stress test found. A request that was FORWARDED and lost is failed when
+ * the stream drops; one that never got forwarded — queued while dormant or reconnecting — was
+ * waiting for a session that, with a squatter holding the port, never arrives. It then hung until
+ * the client's own timeout, or forever if the client has none.
+ *
+ * Comfortably longer than a daemon restart (~1-2s) so a normal blip still flushes and succeeds, and
+ * well under the 60s an MCP client typically allows, so the answer comes from us with a reason
+ * rather than from their timer with none.
+ */
+export declare const QUEUE_WAIT_MS = 20000;
+/** Retry a first connect, or report it? Pure, so the window can be held against the queue's. */
+export declare function shouldRetryFirstConnect(error: unknown, elapsedMs: number): boolean;
+/**
+ * What to do about it, carried on the reply the queue expiry sends.
+ *
+ * A bare -32001 on the first call after an install says nothing a user can act on: not whether to
+ * wait, not whether to retry, not whether the install itself is broken.
+ */
+export declare function queueExpiryNextStep(port: number): string;
 /**
  * Makes a reconnect invisible to the client.
  *