@reticlehq/server 2.7.0 → 2.9.0

package/dist/init/confirm.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The step `init` never took: stay and watch for an app to connect.
+ *
+ * The install has two halves. Registering the MCP server gives the agent the tools; getting the SDK
+ * into a running page gives it something to look at. Almost everyone finishes the first, and nothing
+ * joined "init finished" to "an app connected" — so `init` exited 0 having written files, and the
+ * person left with a config file and no instrumented page was never told (#269).
+ *
+ * The capability existed in three places and was used together by none of them: the poll behind
+ * `reticle open`, the install gate (which calls this exact check "the only step that proves the
+ * install works"), and the event that measures whether it ever happened.
+ *
+ * WHY NO FLAG, and no dev-server management:
+ *
+ *  - No flag, because the people this is for are the ones who do not know to ask. `--verify` would
+ *    be typed by the users who already run `status` afterwards, which is exactly the cohort that is
+ *    not being lost. The gate instead is whether a HUMAN IS AT THE TERMINAL: `init` waits when
+ *    stdout is a TTY and skips the wait entirely otherwise, so a scripted or agent-driven `init`
+ *    keeps today's cost and today's exit behaviour, and blocking never happens where blocking is
+ *    wrong. The signal is the standard "am I being piped" one and needs no argument parsing, which
+ *    also keeps `init`'s documented flag surface where it is.
+ *  - It never starts anything. A dev server started by a long-lived daemon is invisible to the
+ *    person whose machine it runs on and orphans when the daemon exits, so the daemon stays out of
+ *    it — the AGENT starts one, under the guards in agent-rules.ts, because it is attributable and
+ *    stoppable there. So the honest shape here is: confirm the app if it connects, otherwise name
+ *    the ONE command that is outstanding and the one that proves it worked.
+ */
+import { InitConfirmation } from '@reticlehq/core';
+import type { InitOutcome } from '@reticlehq/core';
+/**
+ * How long a human is asked to wait.
+ *
+ * Long enough for a page that is already loading to finish dialling, short enough that somebody who
+ * has not restarted their dev server yet is not held hostage by a wait that cannot succeed — they
+ * have not typed the command that would make it succeed, and the message tells them which one.
+ */
+export declare const CONFIRM_WINDOW_MS = 12000;
+export declare const CONFIRM_POLL_MS = 500;
+export interface ConfirmDeps {
+    /** Session ids connected right now, or null when nothing is listening on the bridge port. */
+    listSessionIds: () => Promise<readonly string[] | null>;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    windowMs?: number;
+    pollMs?: number;
+}
+/** The narrow slice of the init IO this needs — it prints, and nothing else. */
+interface PrintIo {
+    print: (line: string) => void;
+}
+/** What `runInit` hands back; `outcome` is present only on a real (non-dry) run. */
+interface ConfirmableResult {
+    ok: boolean;
+    applied: number;
+    manual: number;
+    outcome?: InitOutcome;
+}
+/**
+ * Poll until an app connects or the window runs out.
+ *
+ * A session that was ALREADY there when the wait began does not count, and this is the whole reason
+ * the check reads ids rather than a count. A daemon is shared across every project on the machine,
+ * so "a session exists" is satisfied by another app, by a stray tab, by yesterday's work — and
+ * confirming this install on somebody else's session is a false green in the one message a user
+ * reads to decide whether they are done. `reticle open` refuses the same way, for the same reason.
+ *
+ * The conservative direction is deliberate: an app that reconnects under an id it already held is
+ * reported as not-yet-connected, and the message it gets sends them to `status`, which shows it. A
+ * missed confirmation costs one command; a false one costs the whole point of confirming.
+ */
+export declare function confirmAppConnected(deps: ConfirmDeps): Promise<InitConfirmation>;
+/**
+ * What the user reads, in the marks the rest of the report already uses: `⚠` means work left to do
+ * and nothing else, `ℹ` is worth reading but is not work, `✓` happened.
+ *
+ * Only NO_SESSION earns a `⚠`, and it earns it honestly: the app is wired and has not connected, so
+ * there is a command outstanding. A missing daemon is not a defect in the install — the daemon comes
+ * up when the agent loads the tools — so it is a notice.
+ */
+export declare function confirmationMessage(confirmation: InitConfirmation, port: number): string;
+/**
+ * What a non-TTY run says instead of waiting.
+ *
+ * `init` deliberately does not block when nobody is at the terminal — a 12-second wait in a script
+ * is wrong, and an agent driving `init` through a shell is never a TTY. But silence was the wrong
+ * other half of that decision: the agent path IS the prescribed path (every skill and every README
+ * block tells an agent to run exactly this command), so the one message joining "init finished" to
+ * "an app connected" was withheld from most of the people who run it. They were left with files on
+ * disk, an exit code of 0, and nothing saying the page half had not happened.
+ *
+ * It claims nothing it did not check. It did not look for a session, so it does not say whether one
+ * exists — a one-shot look would be worse than none, because a daemon is shared across every project
+ * on the machine and "a session exists" is satisfied by somebody else's app, which is the false
+ * green `confirmAppConnected` refuses by design.
+ */
+export declare function unwatchedMessage(port: number): string;
+/**
+ * Finish `init` on evidence rather than on a write.
+ *
+ * The telemetry report happens HERE rather than inside `runInit`, so the one `init_completed` event
+ * carries what was seen. Emitting inside `runInit` and again after the wait would double-count the
+ * funnel it exists to measure, and a second event kind for the same command would need joining back
+ * to the first before anybody could read either.
+ */
+export declare function confirmInstall(result: ConfirmableResult, io: PrintIo, deps: ConfirmDeps & {
+    interactive: boolean;
+    port: number;
+}, report?: (outcome: InitOutcome) => void): Promise<void>;
+/** The real deps: the daemon's own status endpoint, and whether a human is watching. */
+export declare function nodeConfirmDeps(port?: number): ConfirmDeps & {
+    interactive: boolean;
+    port: number;
+};
+export {};

package/dist/init/confirm.js

@@ -0,0 +1,165 @@
+/**
+ * The step `init` never took: stay and watch for an app to connect.
+ *
+ * The install has two halves. Registering the MCP server gives the agent the tools; getting the SDK
+ * into a running page gives it something to look at. Almost everyone finishes the first, and nothing
+ * joined "init finished" to "an app connected" — so `init` exited 0 having written files, and the
+ * person left with a config file and no instrumented page was never told (#269).
+ *
+ * The capability existed in three places and was used together by none of them: the poll behind
+ * `reticle open`, the install gate (which calls this exact check "the only step that proves the
+ * install works"), and the event that measures whether it ever happened.
+ *
+ * WHY NO FLAG, and no dev-server management:
+ *
+ *  - No flag, because the people this is for are the ones who do not know to ask. `--verify` would
+ *    be typed by the users who already run `status` afterwards, which is exactly the cohort that is
+ *    not being lost. The gate instead is whether a HUMAN IS AT THE TERMINAL: `init` waits when
+ *    stdout is a TTY and skips the wait entirely otherwise, so a scripted or agent-driven `init`
+ *    keeps today's cost and today's exit behaviour, and blocking never happens where blocking is
+ *    wrong. The signal is the standard "am I being piped" one and needs no argument parsing, which
+ *    also keeps `init`'s documented flag surface where it is.
+ *  - It never starts anything. A dev server started by a long-lived daemon is invisible to the
+ *    person whose machine it runs on and orphans when the daemon exits, so the daemon stays out of
+ *    it — the AGENT starts one, under the guards in agent-rules.ts, because it is attributable and
+ *    stoppable there. So the honest shape here is: confirm the app if it connects, otherwise name
+ *    the ONE command that is outstanding and the one that proves it worked.
+ */
+import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+import { fetchStatus, summarizeStatus } from '../cli/cli-launch.js';
+import { reportInitOutcome } from '../telemetry/init-telemetry.js';
+/**
+ * How long a human is asked to wait.
+ *
+ * Long enough for a page that is already loading to finish dialling, short enough that somebody who
+ * has not restarted their dev server yet is not held hostage by a wait that cannot succeed — they
+ * have not typed the command that would make it succeed, and the message tells them which one.
+ */
+export const CONFIRM_WINDOW_MS = 12_000;
+export const CONFIRM_POLL_MS = 500;
+/**
+ * Poll until an app connects or the window runs out.
+ *
+ * A session that was ALREADY there when the wait began does not count, and this is the whole reason
+ * the check reads ids rather than a count. A daemon is shared across every project on the machine,
+ * so "a session exists" is satisfied by another app, by a stray tab, by yesterday's work — and
+ * confirming this install on somebody else's session is a false green in the one message a user
+ * reads to decide whether they are done. `reticle open` refuses the same way, for the same reason.
+ *
+ * The conservative direction is deliberate: an app that reconnects under an id it already held is
+ * reported as not-yet-connected, and the message it gets sends them to `status`, which shows it. A
+ * missed confirmation costs one command; a false one costs the whole point of confirming.
+ */
+export async function confirmAppConnected(deps) {
+    const deadline = deps.now() + (deps.windowMs ?? CONFIRM_WINDOW_MS);
+    let before;
+    for (;;) {
+        const ids = await deps.listSessionIds();
+        // A port nobody is listening on cannot receive a session, and no amount of waiting changes that.
+        // One look settles it; polling on would spend the whole window to re-learn the first answer.
+        if (null === ids)
+            return InitConfirmation.NO_DAEMON;
+        const baseline = before;
+        if (baseline === undefined)
+            before = new Set(ids);
+        else if (ids.some((id) => !baseline.has(id)))
+            return InitConfirmation.CONNECTED;
+        if (deadline <= deps.now())
+            return InitConfirmation.NO_SESSION;
+        await deps.sleep(deps.pollMs ?? CONFIRM_POLL_MS);
+    }
+}
+const PROVE_COMMAND = '`npx @reticlehq/server status`';
+/**
+ * What the user reads, in the marks the rest of the report already uses: `⚠` means work left to do
+ * and nothing else, `ℹ` is worth reading but is not work, `✓` happened.
+ *
+ * Only NO_SESSION earns a `⚠`, and it earns it honestly: the app is wired and has not connected, so
+ * there is a command outstanding. A missing daemon is not a defect in the install — the daemon comes
+ * up when the agent loads the tools — so it is a notice.
+ */
+export function confirmationMessage(confirmation, port) {
+    if (confirmation === InitConfirmation.CONNECTED) {
+        return ('  [✓] an app is connected — that is the install finished, not just written.\n' +
+            '      Ask your agent to drive a flow.');
+    }
+    if (confirmation === InitConfirmation.NO_DAEMON) {
+        return (`  [ℹ] nothing is listening on port ${String(port)} yet, so no app could have connected and ` +
+            'this run did not wait for one.\n' +
+            '      The daemon starts on its own when your agent loads the Reticle tools. After that, ' +
+            `${PROVE_COMMAND} confirms the app.`);
+    }
+    return ('  [⚠] no app has connected yet — the files are written, the page half of the install is not ' +
+        'done.\n' +
+        '      Restart your dev server and load the app in a browser — or ask your agent to, which it is ' +
+        'now told to do for you, in the background and with the command from your own scripts.\n' +
+        `      ${PROVE_COMMAND} then confirms it, or says exactly why it has not connected.`);
+}
+/**
+ * What a non-TTY run says instead of waiting.
+ *
+ * `init` deliberately does not block when nobody is at the terminal — a 12-second wait in a script
+ * is wrong, and an agent driving `init` through a shell is never a TTY. But silence was the wrong
+ * other half of that decision: the agent path IS the prescribed path (every skill and every README
+ * block tells an agent to run exactly this command), so the one message joining "init finished" to
+ * "an app connected" was withheld from most of the people who run it. They were left with files on
+ * disk, an exit code of 0, and nothing saying the page half had not happened.
+ *
+ * It claims nothing it did not check. It did not look for a session, so it does not say whether one
+ * exists — a one-shot look would be worse than none, because a daemon is shared across every project
+ * on the machine and "a session exists" is satisfied by somebody else's app, which is the false
+ * green `confirmAppConnected` refuses by design.
+ */
+export function unwatchedMessage(port) {
+    return ('  [ℹ] the files are written. An app CONNECTING is what finishes the install, and this run did ' +
+        'not wait to see one.\n' +
+        '      Start the dev server, load the app in a browser, then ' +
+        `${PROVE_COMMAND} — it confirms the app, or says exactly why it has not connected.\n` +
+        `      Bridge port ${String(port)}.`);
+}
+const WATCHING = (windowMs) => `  watching for an app to connect (up to ${String(Math.round(windowMs / 1000))}s) — Ctrl-C is safe, ` +
+    'everything above is already written.';
+/**
+ * Finish `init` on evidence rather than on a write.
+ *
+ * The telemetry report happens HERE rather than inside `runInit`, so the one `init_completed` event
+ * carries what was seen. Emitting inside `runInit` and again after the wait would double-count the
+ * funnel it exists to measure, and a second event kind for the same command would need joining back
+ * to the first before anybody could read either.
+ */
+export async function confirmInstall(result, io, deps, report = reportInitOutcome) {
+    const outcome = result.outcome;
+    // No outcome means a dry run or an exit that already reported for itself (no package.json). A
+    // preview is not an install and must not land in the funnel as either a success or a failure.
+    if (outcome === undefined)
+        return;
+    if (!deps.interactive) {
+        // Still no waiting — see unwatchedMessage for why it speaks anyway.
+        io.print('');
+        io.print(unwatchedMessage(deps.port));
+        report(outcome);
+        return;
+    }
+    io.print('');
+    io.print(WATCHING(deps.windowMs ?? CONFIRM_WINDOW_MS));
+    const confirmation = await confirmAppConnected(deps);
+    io.print(confirmationMessage(confirmation, deps.port));
+    report({ ...outcome, confirmation });
+}
+/** The real deps: the daemon's own status endpoint, and whether a human is watching. */
+export function nodeConfirmDeps(port = RETICLE_DEFAULT_PORT) {
+    return {
+        listSessionIds: async () => {
+            const payload = await fetchStatus(port);
+            // `fetchStatus` resolves undefined when nothing answered, which is precisely the "no daemon"
+            // case — a zero-session daemon and an absent one need opposite messages.
+            if (payload === undefined)
+                return null;
+            return summarizeStatus(payload).sessions.map((s) => s.sessionId);
+        },
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        interactive: true === process.stdout.isTTY,
+        port,
+    };
+}

package/dist/init/connect-steps.d.ts

@@ -0,0 +1,2 @@
+/** True when this step is what makes the app dial the daemon. */
+export declare function isConnectStep(title: string): boolean;

package/dist/init/connect-steps.js

@@ -0,0 +1,50 @@
+/**
+ * Which `init` steps decide whether the app can dial the daemon.
+ *
+ * Lifted out of `plan.ts` when that file reached the size backstop. A cohesive unit on its own
+ * terms: one question, asked of a step title, with one consequence — a manual step in this set makes
+ * `init` exit non-zero instead of reporting a success over an app that can never connect.
+ *
+ * Matched on TITLES, which is the fragile part and worth stating: renaming a step in
+ * `plan-framework.ts` silently drops it out of this set and nothing goes red. `connect-steps.test.ts`
+ * pins the membership for exactly that reason.
+ */
+/**
+ * Titles of the steps WITHOUT which no session ever appears.
+ *
+ * A ⚠ on one of these is not a warning, it is a guaranteed failure: nothing performs the manual step,
+ * so the app will not connect and every Reticle tool will answer "no browser session connected".
+ * Reported from a field sweep, where the ⚠ count and "did it connect" were treated as independent
+ * signals and are not.
+ */
+const CONNECT_STEP_TITLES = new Set([
+    'Connect snippet',
+    'Connect snippet (CRA)',
+    'Connect snippet (Astro)',
+    'Connect snippet (Nuxt)',
+    'Reticle client hook',
+    'Reticle connect module',
+    'ReticleDev component',
+    // Writing the component and MOUNTING it are two steps, and only the write was here. A root layout
+    // whose shape `init` does not recognise leaves the component on disk and never rendered: the SDK
+    // is in the project, nothing imports it, and `init` exited 0 over an app that could not connect.
+    'Mount ReticleDev',
+    // NOT here, and the reason is worth keeping: 'Pairing token'.
+    //
+    // It is a genuine connect step — CRA inlines only REACT_APP_*, so without the token in the env
+    // file the bridge refuses every connection and the app boots, looks correct, and never pairs. But
+    // it goes MANUAL in exactly one situation: no daemon has ever run on this machine, so there is no
+    // token to inline. That is the FIRST CRA install on a fresh machine, i.e. the first-time user —
+    // and making that exit non-zero reports a broken install to the one person least able to tell
+    // that it is not.
+    //
+    // The real fix is for `init` to mint the token rather than only read it, which is what both the
+    // daemon and the Vite plugin already do. `runInit` is synchronous and the existing helpers are
+    // not, and `gate:install` scaffolds no CRA app, so that change would ship with no coverage of the
+    // path it changes. It is worth doing, and worth doing with a scaffold behind it.
+    'Vite plugin',
+]);
+/** True when this step is what makes the app dial the daemon. */
+export function isConnectStep(title) {
+    return CONNECT_STEP_TITLES.has(title);
+}

package/dist/init/cra.js

@@ -12,6 +12,7 @@
  * `REACT_APP_`. So it travels through `.env.development.local`, which is CRA's own documented
  * mechanism and is gitignored by CRA's own template.
  */
+import { CLI } from './agent-rules.js';
 /** The line added to `src/index.tsx`. Side-effect import: the module guards itself on NODE_ENV. */
 export const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
 export const CRA_DEV_MODULE_PATH = 'src/reticle-dev.ts';
@@ -30,7 +31,7 @@ export const TOKEN_VAR = 'REACT_APP_RETICLE_TOKEN';
  */
 export const CRA_TOKEN_MISSING_NOTE = `${TOKEN_VAR} is not set, so Reticle cannot pair with the daemon. ` +
     `The pairing token is per-machine and ${CRA_ENV_PATH} is gitignored by CRA's template, ` +
-    'so it does not survive a clone. Run `npx reticle init` in this project to write it for this machine.';
+    `so it does not survive a clone. Run \`${CLI} init\` in this project to write it for this machine.`;
 /**
  * Said as its own NOTICE line, beside the write — not inside it.
  *
@@ -46,7 +47,7 @@ export const CRA_TOKEN_MISSING_NOTE = `${TOKEN_VAR} is not set, so Reticle canno
 export const CRA_TOKEN_PER_MACHINE_NOTICE = `${CRA_ENV_PATH} is in CRA's own .gitignore, so the token just written does not travel. ` +
     'It works on THIS machine and nowhere else: a teammate cloning the repo, CI, or a container ' +
     'gets an app that boots, never pairs, and reports it only in the browser console. ' +
-    'Each developer runs `npx reticle init` once locally.';
+    `Each developer runs \`${CLI} init\` once locally.`;
 /** Add the import after the last existing one, or null when it is already present. */
 export function craImportPatch(source) {
     if (source.includes(CRA_DEV_MODULE_IMPORT))

package/dist/init/csp-check.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Does this app's Content-Security-Policy let the browser reach the Reticle bridge?
+ *
+ * Two independent field reports, both Next: `init` reported every step successful, the SDK mounted,
+ * the dial URL was correct, and the app never connected because a strict `connect-src` excluded
+ * `ws://localhost:<port>`. The browser blocks the WebSocket and says so in its own console, which
+ * nothing on the Reticle side reads — so `status` and `doctor` reported perfect health at an app
+ * that could not connect at all, forever. A setup step that exits 0 while leaving the user broken is
+ * the worst failure mode this repo has.
+ *
+ * A TEXT SCAN, deliberately. `headers()` is a function; `init` cannot execute a user's Next config
+ * without importing their whole app, and the thing worth finding is the policy string a developer
+ * typed — in `next.config.*`, in middleware, or in a `<meta http-equiv>` tag. The scan finds the
+ * string wherever it is written.
+ *
+ * NARROW on purpose: it fires only when a `connect-src` exists AND does not admit the bridge. No
+ * CSP, or one that already covers us, produces nothing. A warning that fires on a working setup
+ * costs precisely what a green check on a broken one costs, and this file exists because of the
+ * second kind.
+ */
+/**
+ * The problem with this app's `connect-src`, or undefined if there is not one.
+ *
+ * `https:` counts as a wildcard here only in the sense that a policy written that loosely will not
+ * be the thing blocking a dev WebSocket; the check stays quiet rather than arguing about it.
+ */
+export declare function cspConnectSrcProblem(text: string, port: number): string | undefined;
+/** The exact addition to paste. Text to copy, not advice to interpret. */
+export declare function devCspAddition(port: number): string;
+/** The step title, named here so `doctor` and the plan cannot drift apart on what this check is called. */
+export declare const CSP_STEP_TITLE = "Content-Security-Policy";
+/**
+ * The first blocking policy among the sources `init` already has in hand, or undefined.
+ *
+ * At most one finding: a second copy of the same policy in a second file is the same problem, and
+ * two identical notices read as two problems.
+ */
+export declare function cspPlanProblem(sources: readonly (string | null | undefined)[], port: number): string | undefined;

package/dist/init/csp-check.js

@@ -0,0 +1,92 @@
+/**
+ * Does this app's Content-Security-Policy let the browser reach the Reticle bridge?
+ *
+ * Two independent field reports, both Next: `init` reported every step successful, the SDK mounted,
+ * the dial URL was correct, and the app never connected because a strict `connect-src` excluded
+ * `ws://localhost:<port>`. The browser blocks the WebSocket and says so in its own console, which
+ * nothing on the Reticle side reads — so `status` and `doctor` reported perfect health at an app
+ * that could not connect at all, forever. A setup step that exits 0 while leaving the user broken is
+ * the worst failure mode this repo has.
+ *
+ * A TEXT SCAN, deliberately. `headers()` is a function; `init` cannot execute a user's Next config
+ * without importing their whole app, and the thing worth finding is the policy string a developer
+ * typed — in `next.config.*`, in middleware, or in a `<meta http-equiv>` tag. The scan finds the
+ * string wherever it is written.
+ *
+ * NARROW on purpose: it fires only when a `connect-src` exists AND does not admit the bridge. No
+ * CSP, or one that already covers us, produces nothing. A warning that fires on a working setup
+ * costs precisely what a green check on a broken one costs, and this file exists because of the
+ * second kind.
+ */
+/** Sources that admit any ws origin, so the bridge is already reachable. */
+const WILDCARDS = ['*', 'ws:', 'wss:', 'ws://*', 'https:'];
+/** The two hosts the SDK may dial. `localhost` and the IPv4 loopback are different CSP sources. */
+function bridgeOrigins(port) {
+    return [`ws://localhost:${String(port)}`, `ws://127.0.0.1:${String(port)}`];
+}
+/**
+ * The `connect-src` directive's source list, or undefined when the text declares none.
+ *
+ * Matches to the end of the directive (`;`) or the end of the enclosing quoted string, which is how
+ * these are written in both a Next `headers()` value and a `<meta content="...">`.
+ */
+function connectSrcSources(text) {
+    // Stops at the directive separator or the closing double quote of the enclosing string. Single
+    // quotes are NOT terminators: `'self'` is a source, not the end of the list.
+    const match = /connect-src([^;"]*)/i.exec(text);
+    const list = match?.[1];
+    if (list === undefined)
+        return undefined;
+    return list
+        .split(/\s+/)
+        .map((source) => source.trim())
+        .filter((source) => source.length > 0);
+}
+/**
+ * The problem with this app's `connect-src`, or undefined if there is not one.
+ *
+ * `https:` counts as a wildcard here only in the sense that a policy written that loosely will not
+ * be the thing blocking a dev WebSocket; the check stays quiet rather than arguing about it.
+ */
+export function cspConnectSrcProblem(text, port) {
+    const sources = connectSrcSources(text);
+    if (sources === undefined || 0 === sources.length)
+        return undefined;
+    if (sources.some((source) => WILDCARDS.includes(source)))
+        return undefined;
+    const wanted = bridgeOrigins(port);
+    // BOTH, not either: the SDK picks its host from how the page was served, and a policy that admits
+    // one is a coin flip. A coin flip that fails is indistinguishable from every other silent
+    // non-connect, which is the whole cost being avoided here.
+    if (wanted.every((origin) => sources.includes(origin)))
+        return undefined;
+    const missing = wanted.filter((origin) => !sources.includes(origin));
+    return (`this app declares a Content-Security-Policy whose \`connect-src\` does not admit the Reticle ` +
+        `bridge: ${missing.join(' and ')} ${1 === missing.length ? 'is' : 'are'} missing. The browser ` +
+        `will block the WebSocket and report it in ITS console only — every check on the Reticle side ` +
+        `will pass while the app never connects. ${devCspAddition(port)}`);
+}
+/** The exact addition to paste. Text to copy, not advice to interpret. */
+export function devCspAddition(port) {
+    return (`Add to \`connect-src\` in development only (e.g. behind ` +
+        `\`process.env.NODE_ENV === 'development'\`): ` +
+        `${bridgeOrigins(port).join(' ')}`);
+}
+/** The step title, named here so `doctor` and the plan cannot drift apart on what this check is called. */
+export const CSP_STEP_TITLE = 'Content-Security-Policy';
+/**
+ * The first blocking policy among the sources `init` already has in hand, or undefined.
+ *
+ * At most one finding: a second copy of the same policy in a second file is the same problem, and
+ * two identical notices read as two problems.
+ */
+export function cspPlanProblem(sources, port) {
+    for (const source of sources) {
+        if ('string' !== typeof source)
+            continue;
+        const problem = cspConnectSrcProblem(source, port);
+        if (problem !== undefined)
+            return problem;
+    }
+    return undefined;
+}

package/dist/init/csp-doctor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `doctor`'s web CSP check — the sibling of the desktop one next door.
+ *
+ * The desktop findings exist because a Tauri app with the default CSP runs perfectly and never
+ * connects. The WEB version of that failure had no check at all, and it arrived twice in one batch
+ * of field reports: two Next apps where `init` printed success for every step, the SDK mounted, the
+ * dial URL was right, and the browser silently refused the WebSocket because `connect-src` excluded
+ * the bridge. The violation is reported in the browser's console and nowhere else, so every check on
+ * this side stayed green while the app was permanently unreachable.
+ *
+ * Reads the files a CSP is actually written in, by name — a full source scan would be slower and
+ * would find policy strings in test fixtures and documentation.
+ */
+/** Read a project-relative file, or undefined when it is absent/unreadable. */
+type ReadFile = (relative: string) => string | undefined;
+export interface CspDiagnosis {
+    /** Which file to look at. */
+    file: string;
+    /** What is wrong, in one line. */
+    problem: string;
+    /** Exactly what to add — copy-pasteable, with the port actually in use. */
+    fix: string;
+}
+export declare function diagnoseWebCsp(read: ReadFile, port: number): CspDiagnosis[];
+export {};

package/dist/init/csp-doctor.js

@@ -0,0 +1,49 @@
+/**
+ * `doctor`'s web CSP check — the sibling of the desktop one next door.
+ *
+ * The desktop findings exist because a Tauri app with the default CSP runs perfectly and never
+ * connects. The WEB version of that failure had no check at all, and it arrived twice in one batch
+ * of field reports: two Next apps where `init` printed success for every step, the SDK mounted, the
+ * dial URL was right, and the browser silently refused the WebSocket because `connect-src` excluded
+ * the bridge. The violation is reported in the browser's console and nowhere else, so every check on
+ * this side stayed green while the app was permanently unreachable.
+ *
+ * Reads the files a CSP is actually written in, by name — a full source scan would be slower and
+ * would find policy strings in test fixtures and documentation.
+ */
+import { cspConnectSrcProblem, devCspAddition } from './csp-check.js';
+/**
+ * The places a Content-Security-Policy gets written in a JS app.
+ *
+ * Next config and middleware cover `headers()` and the edge-middleware style; the layouts and the
+ * plain `index.html` cover the `<meta http-equiv>` style. Both reported cases were in this list.
+ */
+const CSP_FILES = [
+    'next.config.js',
+    'next.config.mjs',
+    'next.config.ts',
+    'middleware.ts',
+    'middleware.js',
+    'src/middleware.ts',
+    'app/layout.tsx',
+    'app/layout.js',
+    'pages/_document.tsx',
+    'pages/_document.js',
+    'index.html',
+    'public/index.html',
+    'vercel.json',
+    'netlify.toml',
+];
+export function diagnoseWebCsp(read, port) {
+    const findings = [];
+    for (const file of CSP_FILES) {
+        const source = read(file);
+        if (source === undefined)
+            continue;
+        const problem = cspConnectSrcProblem(source, port);
+        if (problem === undefined)
+            continue;
+        findings.push({ file, problem, fix: devCspAddition(port) });
+    }
+    return findings;
+}

package/dist/init/cursor.js

@@ -4,8 +4,7 @@
  * We add the `reticle` server once at this global path so every project picks it up. Unparseable
  * (jsonc/comment) files bail to manual rather than being rewritten.
  */
-import { NPX, MCP_SERVER_NAME, npxServerArgs } from './mcp.js';
-import { RETICLE_NPM_PACKAGE } from '../version/server-version.js';
+import { NPX, MCP_SERVER_NAME, npxServerArgs, isReticleRegistration } from './mcp.js';
 /** Path of Cursor's global MCP config, relative to the user's home directory. */
 export const CURSOR_MCP_RELPATH = '.cursor/mcp.json';
 /** The directory whose presence signals Cursor is installed for this user. */
@@ -46,19 +45,17 @@ function parseConfig(existing) {
  *
  * What IS repaired is a stale entry of our own shape — an old pin, a command that has moved — which
  * presence-only idempotency reported as "already registered" and never fixed, so an upgrade could
- * not repair the thing an upgrade exists to repair.
+ * not repair the thing an upgrade exists to repair. A WRONG entry counts as ours to repair too:
+ * `["@reticlehq/core","mcp"]` was reported from the field, and `core` has no MCP server in it.
  */
 function leaveEntryAlone(existing) {
     if (JSON.stringify(existing) === JSON.stringify(cursorServerEntry()))
         return true;
     if (typeof existing !== 'object' || null === existing)
         return true;
-    const command = existing.command;
-    const args = existing.args;
-    const ours = command === NPX &&
-        Array.isArray(args) &&
-        args.some((arg) => 'string' === typeof arg && arg.includes(RETICLE_NPM_PACKAGE));
-    return !ours;
+    const record = existing;
+    const tokens = [record.command, record.args].flat().filter((v) => 'string' === typeof v);
+    return !isReticleRegistration(tokens);
 }
 export function mergeCursorConfig(existing) {
     const parsed = parseConfig(existing);

package/dist/init/detect.d.ts

@@ -84,5 +84,13 @@ interface InstallCommand {
 }
 /** Build a dev-dependency install command for one or more packages (e.g. the kit + its build plugin). */
 export declare function installCommandParts(pm: PackageManager, pkgs: string | readonly string[]): InstallCommand;
+/**
+ * The install command as a human reads it — and deliberately NOT `installCommandParts` joined.
+ *
+ * This string is what the plan prints and what a user retypes when running the step by hand, so it
+ * must not carry the flags we add only to quieten our own child process. Built from `INSTALL_ARGS`
+ * directly for that reason; routing it through the parts would put `--no-audit --no-fund` in front of
+ * every reader and teach them our noise-suppression as if it were part of installing Reticle.
+ */
 export declare function installCommand(pm: PackageManager, pkgs: string | readonly string[]): string;
 export {};