@reticlehq/server 2.3.0 → 2.4.0

package/dist/init/snippets.js

@@ -37,8 +37,21 @@ export function nextConfigManual(configFile) {
 
   export default withReticle(nextConfig);`;
 }
-/** The dev-only client component that connects Reticle after hydration. */
-export function nextReticleDevFile(port, projectId) {
+/**
+ * The dev-only client component that connects Reticle after hydration.
+ *
+ * The token is not optional. The bridge requires a pairing token even on localhost, and unlike Vite
+ * (where the plugin injects it) a Next app has to carry it through `withReticle`, which publishes it
+ * 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 = []) {
+    const base = connectArg(port, projectId);
+    const fields = base === '' ? '' : `${base.slice(1, -1).trim()}, `;
+    const ids = testids.map((t) => `'${t}'`).join(', ');
+    const storeBlock = stores.length === 0
+        ? '      // 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 `'use client';
 import { useEffect } from 'react';
 
@@ -46,15 +59,131 @@ import { useEffect } from 'react';
 export function ReticleDev() {
   useEffect(() => {
     if (process.env.NODE_ENV !== 'development') return;
-    void import('@reticlehq/react').then(({ reticle, install }) => {
+    void import('@reticlehq/react').then(({ reticle, install, registerCapabilities }) => {
       install();
-      reticle.connect(${connectArg(port, projectId)});
+      // 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.
+      const token = process.env.NEXT_PUBLIC_RETICLE_TOKEN;
+      const root = process.env.NEXT_PUBLIC_RETICLE_ROOT;
+      reticle.connect({ ${fields}...(token ? { token } : {}), ...(root ? { root } : {}) });
+
+      // ── Start with ONE flow. ──────────────────────────────────────────────────────────────────
+      // Registering a store is the highest-value line here: it lets the agent check what the app
+      // BELIEVES, not just what it rendered. Pass the STORE, not \`() => store.getState()\` — the store
+      // form wires \`subscribe\` too, so every mutation emits a diff; the getter form is read-only.
+${storeBlock}
+      registerCapabilities({
+        testids: [${ids}],${testids.length === 0 ? ' // none found — add data-testid to your key elements' : ''}
+        signals: [], // names you pass to reticle.signal()
+        stores: [], // the keys you registered above
+      });
     });
   }, []);
   return null;
 }
 `;
 }
+/**
+ * Astro connect instructions.
+ *
+ * Astro is Vite-based but SSRs its own HTML, so the plugin's index.html injection never fires, and
+ * `vite` is not a direct dependency — so this used to fall through to the generic HTML advice, which
+ * tells you to add a connect to an "entry module" Astro does not have, or to bundle the SDK with
+ * esbuild. Both are wrong for Astro, and following either gets you nothing.
+ *
+ * Astro bundles a page `<script>`, so the bare import resolves there. The token has to be inlined by
+ * the config because there is no plugin in the page's path to inject it, and `build.target` has to be
+ * raised or Astro down-levels the modern SDK bundle and dies on a destructuring transform.
+ */
+export function astroManual(port, projectId) {
+    const extra = port !== undefined && port !== RETICLE_DEFAULT_PORT ? `\n          url: '${bridgeWsUrl(port)}',` : '';
+    const id = projectId !== undefined && projectId.length > 0 ? `\n          projectId: '${projectId}',` : '';
+    return `Astro renders its own HTML, so the connect goes in a page <script> and the pairing token is inlined by the config.
+
+1. In astro.config.mjs — inline the daemon's token and raise the build target:
+
+  import { readFileSync } from 'node:fs';
+  import { homedir } from 'node:os';
+  import { join } from 'node:path';
+
+  function reticleToken() {
+    const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
+    try { return readFileSync(join(dir, 'pairing-token'), 'utf8').trim(); } catch { return ''; }
+  }
+
+  export default defineConfig({
+    vite: {
+      // Astro's default target down-levels the modern SDK bundle and fails on a destructuring transform.
+      build: { target: 'es2022' },
+      optimizeDeps: { esbuildOptions: { target: 'es2022' } },
+      define: {
+        __RETICLE_TOKEN__: JSON.stringify(reticleToken()),
+        // Without this, source pointers come back as absolute paths from YOUR machine — useless in a
+        // report. Every other framework gets it from its build plugin; Astro owns its Vite instance.
+        __RETICLE_ROOT__: JSON.stringify(process.cwd()),
+      },
+    },
+  });
+
+2. In your layout (or the page you want instrumented), inside <body>:
+
+  <script>
+    if (import.meta.env.DEV) {
+      const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
+      const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
+      const { reticle, install } = await import('@reticlehq/react');
+      install();
+      reticle.connect({${id}${extra}
+          ...(token.length > 0 ? { token } : {}),
+          ...(root.length > 0 ? { root } : {}),
+      });
+    }
+  </script>
+
+Start the daemon BEFORE \`astro dev\`, so the token file exists when the config is read. Until it does the token is empty and the page reloads once the daemon is up.`;
+}
+/**
+ * The app-side dev module the Vite plugin imports by convention.
+ *
+ * `registerCapabilities` tells the agent what it can drive without guessing; `registerStore` is the
+ * one that matters most and the one we cannot write for you — detecting that an app depends on
+ * zustand is easy, knowing which module exports the store instance is not, and a wrong import here
+ * 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) {
+    const ids = testids.map((t) => `'${t}'`).join(', ');
+    const storeBlock = stores.length === 0
+        ? '  // 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.
+// Self-guards on import.meta.env.DEV, so it is a no-op in a production build.
+import { registerCapabilities } from '@reticlehq/react';
+
+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
+  // the store your most important flow reads, and list the testids that flow touches. Add more later,
+  // when a flow you actually replay needs them.
+  //
+  // Registering a store is the highest-value line in this file: it lets the agent check what the app
+  // BELIEVES, not just what it rendered — the class of bug a screenshot cannot see. Pass the STORE,
+  // not \`() => store.getState()\`: the store form wires \`subscribe\` too, so every mutation emits a
+  // state diff; the getter form is read-only and silently produces empty diffs.
+${storeBlock}
+
+  registerCapabilities({
+    testids: [${ids}],${testids.length === 0 ? ' // none found — add data-testid to your key elements' : ''}
+    signals: [], // names you pass to reticle.signal()
+    stores: [], // the keys you registered above
+  });
+}
+`;
+}
+/** Where that module goes. Matches @reticlehq/vite-plugin's convention list. */
+export const VITE_DEV_MODULE_PATH = 'src/reticle-dev.ts';
+/** Default root-layout path, used when no layout was found on disk (reporting only). */
+export const NEXT_LAYOUT_PATH = 'app/layout.tsx';
 /** Mount instruction for the root layout. */
 export const NEXT_LAYOUT_MANUAL = `Mount <ReticleDev /> in your root layout (app/layout.tsx), dev-only:
 
@@ -90,21 +219,38 @@ export const SVELTEKIT_HOOKS_PATH = 'src/hooks.client.ts';
  * Said to the user's face rather than discovered later. React, Next, Remix and Astro each have an
  * app and a CI gate; SvelteKit has neither, so "it generated some wiring" is not evidence it works.
  */
-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, Astro, and plain HTML. If the hook does not register a session, please open an issue.';
+/**
+ * Said out loud when the app does not render through React. The SDK is framework-agnostic — DOM,
+ * network, console and routing all still work — but `@reticlehq/react` is a React adapter, so
+ * component names and source mapping do not, and no CI gate covers this stack. Reporting all-green
+ * 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, but @reticlehq/react is a React adapter: component names and data-reticle-source file:line will be missing, and no CI gate covers ${library}. Gated today: 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.';
 /**
  * Dev-only client hook that connects Reticle in a SvelteKit app. SvelteKit renders through app.html and
  * 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) {
+    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();
-    reticle.connect(${connectArg(port, projectId)});
+    // 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.
+    const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
+    reticle.connect({ ${fields}...(token.length > 0 ? { token } : {}) });
   });
 }
+
+declare const __RETICLE_TOKEN__: string | undefined;
 `;
 }
 /**

package/dist/init/vite-config.d.ts

@@ -4,21 +4,15 @@
  * bails to a `manual` result so we never half-edit a build config (a broken config is worse than a
  * documented manual step).
  */
+import { PatchKind, type SourcePatch } from './patch-kind.js';
 export declare const VITE_IMPORT = "import { reticle } from '@reticlehq/vite-plugin';";
+/** Alias kept so existing call sites read in Vite terms; the vocabulary is shared (see patch-kind). */
 export declare const VitePatchKind: {
     readonly APPLY: "apply";
     readonly ALREADY: "already";
     readonly MANUAL: "manual";
 };
-export type VitePatchKind = (typeof VitePatchKind)[keyof typeof VitePatchKind];
-type VitePatch = {
-    kind: typeof VitePatchKind.APPLY;
-    code: string;
-} | {
-    kind: typeof VitePatchKind.ALREADY;
-} | {
-    kind: typeof VitePatchKind.MANUAL;
-    reason: string;
-};
+export type VitePatchKind = PatchKind;
+type VitePatch = SourcePatch;
 export declare function patchViteConfig(source: string, port?: number): VitePatch;
 export {};

package/dist/init/vite-config.js

@@ -4,6 +4,7 @@
  * bails to a `manual` result so we never half-edit a build config (a broken config is worse than a
  * documented manual step).
  */
+import { PatchKind } from './patch-kind.js';
 export const VITE_IMPORT = "import { reticle } from '@reticlehq/vite-plugin';";
 const RETICLE_MARKER = '@reticlehq/vite-plugin';
 /** The `reticle...)` call — carries the bridge port so the injected connect targets it. */
@@ -14,11 +15,8 @@ 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;
-export const VitePatchKind = {
-    APPLY: 'apply',
-    ALREADY: 'already',
-    MANUAL: 'manual',
-};
+/** 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";
 function insertImport(source) {
     const matches = [...source.matchAll(IMPORT_LINE)];
@@ -29,9 +27,19 @@ function insertImport(source) {
     const end = last.index + last[0].length;
     return `${source.slice(0, end)}\n${VITE_IMPORT}${source.slice(end)}`;
 }
+/**
+ * Insert right after the opening `[` of the plugins array, spaced the way the surrounding line is.
+ *
+ * A multi-line array puts a newline next, and `[reticle(), \n` leaves trailing whitespace — exactly
+ * what a formatter rewrites, turning a one-line install into a diff against the user's own style. A
+ * single-line array needs the space, or the result reads `[reticle(),react()]`.
+ */
 function insertPlugin(source, port) {
-    // Insert right after the opening `[` of the plugins array.
-    return source.replace(PLUGINS_ARRAY, (match) => `${match}${reticlePluginCall(port)}, `);
+    return source.replace(PLUGINS_ARRAY, (match, _g, offset) => {
+        const next = source[offset + match.length] ?? '';
+        const separator = next === '' || /\s/.test(next) ? '' : ' ';
+        return `${match}${reticlePluginCall(port)},${separator}`;
+    });
 }
 export function patchViteConfig(source, port) {
     if (source.includes(RETICLE_MARKER)) {

package/dist/input/driven-redaction.d.ts

@@ -0,0 +1,15 @@
+import { type RedactionPolicy } from '@reticlehq/core';
+/** Record what a session declared sensitive. Called when its hello lands. */
+export declare function declareDrivenRedactionKeys(sessionId: string, keys: readonly string[]): void;
+/** Drop a session's declarations when it disconnects, so a closed tab stops widening the union. */
+export declare function forgetDrivenRedactionKeys(sessionId: string): void;
+/** Every key declared by any connected session, sorted so the memo signature is stable. */
+export declare function drivenRedactionKeys(): string[];
+/**
+ * The rule in force for driven-path captures: the built-in rule plus every declared key. Identical
+ * to the built-in rule when no session declared anything, which is the overwhelmingly common case
+ * and the one that must stay byte-identical to before this feature existed.
+ */
+export declare function drivenRedactionPolicy(): RedactionPolicy;
+/** Test seam: drop every declaration. Not used in production — sessions unregister themselves. */
+export declare function resetDrivenRedaction(): void;

package/dist/input/driven-redaction.js

@@ -0,0 +1,76 @@
+import { buildRedactionPolicy } from '@reticlehq/core';
+/**
+ * The redaction rule the DRIVEN path uses — the one place in the daemon that redacts a payload the
+ * browser SDK never saw.
+ *
+ * ## Why this exists at all
+ *
+ * `connect({ redact: { keys } })` is configured in the page, and the SDK redacts everything it
+ * observes. But a driven session's request bodies and response headers are captured by the daemon
+ * straight from the network stack (`page.on('response')`), so they never pass through the SDK. An app
+ * that declared `licenceKey` sensitive would see it redacted everywhere the developer looked, and
+ * find it in cleartext in the on-disk journal — a leak on precisely the path they cannot inspect.
+ * So a session's declared keys are announced in its hello and land here.
+ *
+ * ## Why a daemon-wide UNION rather than a per-session rule
+ *
+ * A NET_DETAIL is redacted at capture time and only routed to a session afterwards, by `pageUrl`.
+ * At the moment of redaction there is no session in hand, and there is a real window in which there
+ * is no session at all yet. Resolving one first would mean either delaying redaction (holding a raw
+ * credential in memory until routing succeeds) or dropping the detail.
+ *
+ * The union sidesteps that, and is only safe because of an asymmetry that is enforced upstream:
+ * declared keys can ONLY add redaction. The worst case is that one local app's declared key
+ * over-redacts a same-named field in another local app on the same daemon — an inconvenience, in the
+ * safe direction, between two apps belonging to the same developer on the same machine. The
+ * dangerous direction is closed by construction: `allow` never crosses the bridge, so nothing a page
+ * sends can lower this floor below the built-in rule.
+ */
+/** Declared keys per session id, so a disconnect narrows the union back down. */
+const declaredBySession = new Map();
+/** Memoized policy + the key set it was built from, so the hot path does not rebuild per response. */
+let cached;
+function invalidate() {
+    cached = undefined;
+}
+/** Record what a session declared sensitive. Called when its hello lands. */
+export function declareDrivenRedactionKeys(sessionId, keys) {
+    if (keys.length === 0) {
+        if (declaredBySession.delete(sessionId))
+            invalidate();
+        return;
+    }
+    declaredBySession.set(sessionId, [...keys]);
+    invalidate();
+}
+/** Drop a session's declarations when it disconnects, so a closed tab stops widening the union. */
+export function forgetDrivenRedactionKeys(sessionId) {
+    if (declaredBySession.delete(sessionId))
+        invalidate();
+}
+/** Every key declared by any connected session, sorted so the memo signature is stable. */
+export function drivenRedactionKeys() {
+    const all = new Set();
+    for (const keys of declaredBySession.values())
+        for (const key of keys)
+            all.add(key);
+    return [...all].sort();
+}
+/**
+ * The rule in force for driven-path captures: the built-in rule plus every declared key. Identical
+ * to the built-in rule when no session declared anything, which is the overwhelmingly common case
+ * and the one that must stay byte-identical to before this feature existed.
+ */
+export function drivenRedactionPolicy() {
+    const keys = drivenRedactionKeys();
+    const signature = keys.join('\u0000');
+    if (cached?.signature !== signature) {
+        cached = { signature, policy: buildRedactionPolicy({ keys }) };
+    }
+    return cached.policy;
+}
+/** Test seam: drop every declaration. Not used in production — sessions unregister themselves. */
+export function resetDrivenRedaction() {
+    declaredBySession.clear();
+    invalidate();
+}

package/dist/input/network-detail.d.ts

@@ -1,4 +1,4 @@
-import { type ReticleEvent } from '@reticlehq/core';
+import { type RedactionPolicy, type ReticleEvent } from '@reticlehq/core';
 /**
  * CDP-authoritative network detail. Wherever the daemon has a CDP connection — whether it launched
  * the browser or attached to one someone else started — `page.on('response')` sees the FULL response:
@@ -34,7 +34,13 @@ export interface NetworkDetail {
      */
     pageUrl?: string;
 }
-/** Shape a raw authoritative response into a NET_DETAIL payload (lower-cased headers). */
+/**
+ * Shape a raw authoritative response into a NET_DETAIL payload (lower-cased headers).
+ *
+ * `policy` defaults to the built-in rule so this stays a PURE builder — the driven-path union is
+ * resolved by `attachNetworkDetail`, at the glue layer, where reading process state is not a lie
+ * about the function's inputs.
+ */
 export declare function buildNetworkDetail(raw: {
     url: string;
     method?: string;
@@ -43,7 +49,7 @@ export declare function buildNetworkDetail(raw: {
     resourceType?: string;
     requestBody?: string;
     pageUrl?: string;
-}): NetworkDetail;
+}, policy?: RedactionPolicy): NetworkDetail;
 /**
  * Fold each NET_DETAIL onto the matching in-page NET_REQUEST (by method+url), enriching it with the
  * authoritative headers/resourceType the page-side wrapper couldn't see — WITHOUT clobbering fields the

package/dist/input/network-detail.js

@@ -1,6 +1,16 @@
-import { EventType, REDACTED_VALUE, isSensitiveKey, scrubKnownSecrets, } from '@reticlehq/core';
+import { EventType, REDACTED_VALUE, defaultIsSensitiveKey, scrubKnownSecrets, } from '@reticlehq/core';
+import { drivenRedactionPolicy } from './driven-redaction.js';
 /** Bound on a captured wire body — matches the in-page capture so the two are comparable. */
 const MAX_WIRE_BODY_CHARS = 8192;
+/**
+ * The rule this module redacts by.
+ *
+ * `defaultIsSensitiveKey`, never the ambient `isSensitiveKey`: a daemon serves many sessions in one
+ * process, so an ambient policy here would let one app's config decide another app's redaction.
+ * Callers that have a session's declarations pass a policy explicitly; everything else gets the
+ * built-in floor, which is exactly what this module did before the rule became configurable.
+ */
+const DEFAULT_POLICY = { isSensitiveKey: defaultIsSensitiveKey };
 /**
  * Redact a sensitive key's value whatever its TYPE — string, number, array, or a nested object.
  *
@@ -8,19 +18,19 @@ const MAX_WIRE_BODY_CHARS = 8192;
  * SDK's sanitizer (Playwright hands it over raw), so its redaction has to be as strong as the SDK's,
  * which is key-based over a parsed object — not string-shaped.
  */
-function redactByKey(value) {
+function redactByKey(value, policy) {
     if (Array.isArray(value))
-        return value.map(redactByKey);
+        return value.map((v) => redactByKey(v, policy));
     if (value !== null && typeof value === 'object') {
         const out = {};
         for (const [k, v] of Object.entries(value)) {
-            out[k] = isSensitiveKey(k) ? REDACTED_VALUE : redactByKey(v);
+            out[k] = policy.isSensitiveKey(k) ? REDACTED_VALUE : redactByKey(v, policy);
         }
         return out;
     }
     return value;
 }
-function projectWireBody(raw) {
+function projectWireBody(raw, policy) {
     const bounded = raw.length > MAX_WIRE_BODY_CHARS ? raw.slice(0, MAX_WIRE_BODY_CHARS) : raw;
     const byShape = scrubKnownSecrets(bounded);
     // Prefer a STRUCTURAL pass. A sensitive key must be redacted regardless of its value type — a
@@ -29,7 +39,7 @@ function projectWireBody(raw) {
     // straight to the agent's context and the on-disk journal. Parsing and walking redacts them by key
     // whatever the shape.
     try {
-        return JSON.stringify(redactByKey(JSON.parse(byShape)));
+        return JSON.stringify(redactByKey(JSON.parse(byShape), policy));
     }
     catch {
         // Not JSON (a truncated capture, or a form-encoded body — the shape a login form actually POSTs).
@@ -37,8 +47,8 @@ function projectWireBody(raw) {
         // truncated body still contains, and the `key=value` pair of `application/x-www-form-urlencoded`,
         // which neither the JSON path nor the old regex ever touched — so `password=hunter2` leaked.
         return byShape
-            .replace(/"([^"]+)"\s*:\s*"([^"]*)"/g, (whole, key) => isSensitiveKey(key) ? `"${key}":"${REDACTED_VALUE}"` : whole)
-            .replace(/([^&?=\s]+)=([^&\s]*)/g, (whole, key) => isSensitiveKey(key) ? `${key}=${REDACTED_VALUE}` : whole);
+            .replace(/"([^"]+)"\s*:\s*"([^"]*)"/g, (whole, key) => policy.isSensitiveKey(key) ? `"${key}":"${REDACTED_VALUE}"` : whole)
+            .replace(/([^&?=\s]+)=([^&\s]*)/g, (whole, key) => policy.isSensitiveKey(key) ? `${key}=${REDACTED_VALUE}` : whole);
     }
 }
 /**
@@ -50,25 +60,31 @@ function projectWireBody(raw) {
  * credential HEADER is redacted whole by key; any other header value is still swept for known secret
  * SHAPES (a JWT echoed in a custom header), matching how request bodies are handled.
  */
-function projectHeaders(headers) {
+function projectHeaders(headers, policy) {
     const out = {};
     for (const [k, v] of Object.entries(headers)) {
         const key = k.toLowerCase();
-        out[key] = isSensitiveKey(key) ? REDACTED_VALUE : scrubKnownSecrets(v);
+        out[key] = policy.isSensitiveKey(key) ? REDACTED_VALUE : scrubKnownSecrets(v);
     }
     return out;
 }
-/** Shape a raw authoritative response into a NET_DETAIL payload (lower-cased headers). */
-export function buildNetworkDetail(raw) {
+/**
+ * Shape a raw authoritative response into a NET_DETAIL payload (lower-cased headers).
+ *
+ * `policy` defaults to the built-in rule so this stays a PURE builder — the driven-path union is
+ * resolved by `attachNetworkDetail`, at the glue layer, where reading process state is not a lie
+ * about the function's inputs.
+ */
+export function buildNetworkDetail(raw, policy = DEFAULT_POLICY) {
     return {
         url: raw.url,
         ...(raw.method === undefined ? {} : { method: raw.method }),
         status: raw.status,
-        headers: projectHeaders(raw.headers),
+        headers: projectHeaders(raw.headers, policy),
         ...(raw.resourceType === undefined ? {} : { resourceType: raw.resourceType }),
         ...(raw.requestBody === undefined || raw.requestBody.length === 0
             ? {}
-            : { requestBody: projectWireBody(raw.requestBody) }),
+            : { requestBody: projectWireBody(raw.requestBody, policy) }),
         ...(raw.pageUrl === undefined || raw.pageUrl.length === 0 ? {} : { pageUrl: raw.pageUrl }),
     };
 }
@@ -148,7 +164,11 @@ export function attachNetworkDetail(page, emit) {
                 ...(resourceType === undefined ? {} : { resourceType }),
                 ...(postData === null ? {} : { requestBody: postData }),
                 pageUrl: page.url(),
-            }));
+            }, 
+            // Resolved per response, not per attachment: a session declaring extra keys can connect
+            // after the listener is attached, and capturing the policy once would leave every
+            // already-driven page redacting by the rule that was in force before the app said so.
+            drivenRedactionPolicy()));
         });
         // `response.headers()` REJECTS when the page/CDP session is closing — precisely when responses race
         // teardown (navigation, tab close). Without this catch the rejection floats; on the daemon path a

package/dist/mcp-proxy.d.ts

@@ -1,3 +1,32 @@
+/**
+ * How many consecutive failed reconnects before the proxy gives up and exits. At the capped backoff
+ * this is a few minutes — long enough to ride out a daemon restart, short enough that a genuinely
+ * dead daemon lets the agent host respawn the proxy (which spawns a fresh daemon) instead of hanging.
+ */
+export declare const MAX_RECONNECT_ATTEMPTS = 60;
+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";
+/** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
+export declare function proxyLogPath(): string;
+/**
+ * Makes a reconnect invisible to the client.
+ *
+ * The daemon builds a FRESH `McpServer` per SSE connection, so a reconnected session has never seen
+ * the client's `initialize` — every subsequent `tools/call` would hit an uninitialized server. The
+ * proxy therefore remembers the handshake the client sent once and replays it into each new session.
+ * The replay is re-issued under a reserved id so the daemon's response to it can be dropped rather
+ * than reaching the client's stdout, where a duplicate JSON-RPC id would be a protocol violation.
+ */
+export declare class HandshakeReplay {
+    #private;
+    /** Record one outbound client line. Cheap enough to call for every stdin message. */
+    observeOutbound(line: string): void;
+    /** Lines to POST into a freshly-established session, before any queued client traffic. */
+    replayLines(): string[];
+    /** True when this inbound daemon line is the echo of our replayed handshake and must not be forwarded. */
+    shouldSuppressInbound(line: string): boolean;
+}
 /** One parsed Server-Sent-Events frame: the event name (defaulted to "message") and its data. */
 export interface SseFrame {
     event: string;
@@ -28,8 +57,11 @@ export declare function waitForDaemon(port: number): Promise<void>;
 export declare function buildSessionUrl(rawData: string, port: number): string;
 /**
  * Bridge stdio ↔ SSE: connects to the running daemon's MCP endpoint and forwards
- * Claude Code's stdin/stdout JSON-RPC through it. Never resolves — runs until
- * stdin closes or the SSE stream ends (at which point the process exits so
- * Claude Code restarts the proxy fresh).
+ * Claude Code's stdin/stdout JSON-RPC through it. Never resolves — runs until stdin closes.
+ *
+ * A dropped SSE stream used to exit the process, which is what made the agent's `reticle_*` tools
+ * vanish mid-session with no message and no way for the agent to get them back — only a human running
+ * `/mcp` could. The daemon demonstrably stays up across these drops, so the stream ending is a
+ * transport event, not a shutdown: reconnect to it and replay the handshake instead of dying.
  */
 export declare function startMcpProxy(port: number): Promise<never>;