@reticlehq/server 2.10.0 → 2.12.0

package/dist/init/agent-rules.d.ts

@@ -36,6 +36,15 @@ export declare const AGENTS_MD_PATH = "AGENTS.md";
 export declare const RETICLE_MD_PATH = "RETICLE.md";
 /** Cursor project rule; the frontmatter `alwaysApply` keeps it in context on every turn. */
 export declare const CURSOR_RULE_PATH = ".cursor/rules/reticle.mdc";
+/**
+ * Does this file already carry the managed block?
+ *
+ * Exported so callers cannot invent their own looser test. The begin marker carries explanatory
+ * text inside the comment, so a substring check for `reticle:begin` matches files that
+ * `mergeMarkedInstruction` would treat as having NO block — and the two disagreeing means a refresh
+ * silently appends a second copy instead of updating the first.
+ */
+export declare function hasManagedBlock(text: string): boolean;
 /**
  * How the agent must INVOKE the CLI.
  *
@@ -67,6 +76,14 @@ export declare const CLI: string;
  * Exported because slash-command.ts renders the same rule; there must not be two versions of it.
  */
 export declare const DEV_SERVER_POLICY = "**If no dev server is listening, start one yourself.** Read the project's own dev script out of `package.json` (`dev`, `start`, whatever this project calls it), run it in the BACKGROUND, tell the user in one line that it is running and how to stop it, then carry on. Stopping to ask is how a verification turn ends with nothing verified.\n\nFive guards, none optional:\n\n1. **Never start a second one.** If something is already listening on the app's port, use it.\n2. **Never guess the command.** It comes from `package.json` scripts. If there is no recognisable dev script, say so and stop rather than inventing one.\n3. **Never kill anything.** Not a dev server, not a daemon, not a port holder \u2014 including one you started.\n4. **Background it, and say so.** The user must know a server is running and how to stop it. A dev server the human does not know about is the same failure one step later.\n5. **The permission prompt belongs to your host.** Never try to bypass, suppress or auto-approve it, and take a refusal as the answer.";
+/**
+ * The operative rules, carried by every file that loads on every turn.
+ *
+ * Short on purpose. This is the text that has to CHANGE BEHAVIOUR, so it states when to verify, when
+ * NOT to, how, and the guards against calling something proven when it is not. Everything an agent
+ * needs only at the moment it hits a specific situation lives in RETICLE.md, named at the end.
+ */
+export declare const RULE_BODY: string;
 /** The full-rules file, written verbatim (no markers: `init` owns this file entirely). */
 export declare function reticleMdFile(): string;
 export declare const AgentRuleStatus: {

package/dist/init/agent-rules.js

@@ -41,6 +41,17 @@ export const CURSOR_RULE_PATH = '.cursor/rules/reticle.mdc';
 /** Markers delimiting the managed block so a re-run is idempotent and the block stays updatable. */
 const RULE_BEGIN = '<!-- reticle:begin (managed by `reticle init` — edit outside these markers) -->';
 const RULE_END = '<!-- reticle:end -->';
+/**
+ * Does this file already carry the managed block?
+ *
+ * Exported so callers cannot invent their own looser test. The begin marker carries explanatory
+ * text inside the comment, so a substring check for `reticle:begin` matches files that
+ * `mergeMarkedInstruction` would treat as having NO block — and the two disagreeing means a refresh
+ * silently appends a second copy instead of updating the first.
+ */
+export function hasManagedBlock(text) {
+    return text.includes(RULE_BEGIN);
+}
 /**
  * How the agent must INVOKE the CLI.
  *
@@ -87,7 +98,7 @@ Five guards, none optional:
  * NOT to, how, and the guards against calling something proven when it is not. Everything an agent
  * needs only at the moment it hits a specific situation lives in RETICLE.md, named at the end.
  */
-const RULE_BODY = `## Verifying with Reticle
+export const RULE_BODY = `## Verifying with Reticle
 
 This app is instrumented by **Reticle**, an in-app verification layer exposed as \`reticle_*\` MCP tools and the \`${CLI}\` CLI (always through npx: Reticle's server is not installed into this project). Verifying is part of "done", not an optional extra.
 
@@ -103,21 +114,40 @@ This app is instrumented by **Reticle**, an in-app verification layer exposed as
 - **Only \`reticle_act_and_wait\` and \`reticle_assert\` produce a verdict.** \`reticle_act\` and everything else move or read the app and prove nothing, so a session ending without one of those two has no result however many tools it used.
 - Covered flows: \`${CLI} gate\` reports which recorded flows the changed files affect and whether they still pass.
 
+**Setting Reticle up, or just restarted? You are mid-sequence — do not stop until a verdict exists.**
+The whole of it is: instrument the app → get a dev server running → open the app in a browser →
+drive one flow → report the verdict. Every step is yours to do, and none of them needs the user.
+The ONE legitimate pause is a client restart, because a client reads its server list at startup;
+when you come back, you are not finished, you are on the next step — resume it without being asked.
+Stopping anywhere else leaves an app that looks installed and can verify nothing, which is the
+single commonest way this goes wrong. \`/reticle\` carries the full recovery ladder when a step
+does not work; use it rather than guessing, and never report the install as finished without a
+verdict to point at.
+
 **Nothing connected? Get the app running.**
 
 ${DEV_SERVER_POLICY}
 
 A dev server that is already running does not pick up an edited build config or a newly created plugin file — restart it and hard-reload the tab. And if a server IS listening and still nothing connects, the cause is the SDK not loading in the page, not a missing dev server; do not tell the user to start one they are already running.
 
+**Finish \`src/reticle-dev.ts\` before you claim setup is done.** \`init\` writes it and cannot always fill it in: a store that needs an argument only reading the code supplies (Jotai atoms, an XState actor, a TanStack \`queryClient\`) is left as a commented \`registerStore\` line. A file that registers nothing looks exactly like a finished one, and \`reticle_state\` then returns empty forever — which is indistinguishable from an app that has nothing to report, so it reads as success. Uncomment the line, complete it, and prove it by driving one flow and seeing your keys come back. If \`init\` told you to restart your client, this is the job waiting for you on the other side of that restart.
+
+**Verify each feature as you finish it, not all of them at the end.** Asked for four, build one, drive it, get a verdict, then start the second. A red verdict after four builds has four suspects; after one it has none.
+
+**Capture what a change is FOR while you are building it, not afterwards.** \`reticle_intent\` records the business outcome a change is meant to produce, and the only moment anybody knows it is while the change is being made. Pass \`intent\` when you save a flow, so the saved flow carries the reason it exists. A flow without one replays for months and then reports "step 3 failed" instead of what stopped being true for a user.
+
 **Honesty, which is the whole point:**
 
 - **\`verified: "unknown"\` is not a pass.** It means Reticle drove the app and could not tell what happened; \`verifiedReason\` says which clause decided that. Report it as unknown, never as working.
+- **\`verified: "no-fault"\` is not a pass either.** It means nothing was DECLARED to prove: the page settled and no channel complained, but you asserted nothing, so there is no verification. You get it whenever \`until\` is omitted. Name a consequence the action changes — a signal, a request, a route, or store state — and call again.
 - **Never weaken a check to make it green.** Downgrading, skipping or deleting an assertion is a finding, not a fix.
 - **If Reticle cannot run** (no daemon, or this is not a running web app), say so. Do not skip verification silently.
 - **Setup is not finished until one real flow has been driven and produced a verdict.** \`init\` exiting 0, the tools appearing, and a session being listed are all things that happen before anything has been verified.
 
 **The \`/reticle\` skill runs this whole loop for you** — detect, connect, drive one flow, report. If your client does not have it, install it once: \`/plugin marketplace add reticlehq/reticle\` then \`/plugin install reticle@reticlehq\` in Claude Code, or \`npx skills add reticlehq/reticle\` anywhere the skills CLI works.
 
+**A tool you need is missing? It exists.** The default surface advertises a subset; reach any other by name with \`reticle_run { tool, args }\`, and list them with \`reticle_tools\`. Two worth knowing: \`reticle_context\` returns this run's own memory — what is established, what is proven, what is still unverified — which is what you want after a compaction or when picking up work you did not start; \`reticle_intent\` records what a change was MEANT to do, while somebody still knows.
+
 **Report Reticle's own defects with \`reticle_feedback\` the moment you notice**, then carry on with your task. You are the user Reticle is built for and the only one who can say what it cost you, and that knowledge is gone when your context is.
 
 📄 **The rest is in [RETICLE.md](./${RETICLE_MD_PATH}): what to do when the tools are missing, when a result carries \`version_skew\` or \`update_available\`, when \`reticle_state\` comes back empty, and how to write a feedback report that can be acted on. Read it when you hit one of those, not before.**`;

package/dist/init/capabilities.d.ts

@@ -24,8 +24,6 @@ export interface FoundStore {
     /** Module specifier relative to `src/reticle-dev.ts`. */
     importPath: string;
 }
-/** Where the generated dev module lives, for Vite. Next passes its own. */
-export declare const DEFAULT_DEV_MODULE_DIR = "src";
 /**
  * Store instances declared in the app's own source, ready to import and register.
  *

package/dist/init/capabilities.js

@@ -102,7 +102,7 @@ function importPathFor(storePath, fromDir) {
     return rel.startsWith('.') ? rel : `./${rel}`;
 }
 /** Where the generated dev module lives, for Vite. Next passes its own. */
-export const DEFAULT_DEV_MODULE_DIR = 'src';
+const DEFAULT_DEV_MODULE_DIR = 'src';
 /**
  * Store instances declared in the app's own source, ready to import and register.
  *

package/dist/init/closing-hint.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The last thing `init` prints, and the only part of it a user is asked to act on.
+ *
+ * Split out of `run.ts` because that file sits exactly at the 1000-line cohesion cap, and because
+ * this IS a separate concern: everything else in `run.ts` decides what to write, and this decides
+ * what to say afterwards. The two failure modes are different too — a wrong write breaks an
+ * install, a wrong sentence loses a user quietly.
+ */
+import { Framework } from './detect.js';
+import { StepStatus } from './plan.js';
+/**
+ * The standing ask, printed at the end of every `init`.
+ *
+ * Addressed to the agent as much as the human: whichever of them just ran this command is the one
+ * holding the experience, and neither has a Reticle tool surface to file through at this point.
+ *
+ * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
+ * the workspace redirect is kept from asking twice.
+ */
+export declare const FEEDBACK_HINT: string;
+/**
+ * The last two lines a user reads, and the order matters.
+ *
+ * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
+ * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
+ * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
+ * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
+ * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
+ * failed.
+ *
+ * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
+ * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
+ */
+export declare function restartHint(framework: Framework, mcpStatus: StepStatus | undefined, 
+/** The project's own dev command, when package.json named one. */
+devCommand?: string): string;

package/dist/init/closing-hint.js

@@ -0,0 +1,120 @@
+/**
+ * The last thing `init` prints, and the only part of it a user is asked to act on.
+ *
+ * Split out of `run.ts` because that file sits exactly at the 1000-line cohesion cap, and because
+ * this IS a separate concern: everything else in `run.ts` decides what to write, and this decides
+ * what to say afterwards. The two failure modes are different too — a wrong write breaks an
+ * install, a wrong sentence loses a user quietly.
+ */
+import { Framework } from './detect.js';
+import { StepStatus } from './plan.js';
+import { wasMcpRegistered } from './mcp-registered.js';
+import { CLI } from './agent-rules.js';
+/**
+ * The standing ask, printed at the end of every `init`.
+ *
+ * Addressed to the agent as much as the human: whichever of them just ran this command is the one
+ * holding the experience, and neither has a Reticle tool surface to file through at this point.
+ *
+ * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
+ * the workspace redirect is kept from asking twice.
+ */
+export const FEEDBACK_HINT = 'Anything wrong, missing, or awkward — in this setup or in Reticle itself? Tell us; it is the ' +
+    'one thing that decides what gets fixed:\n' +
+    `  ${CLI} feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"   (agents)\n` +
+    `  ${CLI} feedback "what worked, what didn't"   (humans)`;
+/**
+ * What to say about the dev server.
+ *
+ * Names the project's own script when `package.json` has a recognisable one, and otherwise says the
+ * THING rather than guessing the command.
+ *
+ * The guesses that used to live here — `vite`, `next dev`, `astro dev` — were wrong often enough to
+ * be worth deleting. Measured on a real app: rowy has no `dev` script at all, so "Restart `vite`"
+ * sent the reader to work out what was meant instead of starting a server. Nobody needs the guess:
+ * an agent reading this can open package.json, and a human already knows how they start their own
+ * app. A wrong command costs more than a missing one.
+ */
+function devServerRestart(_framework, devCommand) {
+    return devCommand === undefined
+        ? 'Restart your dev server'
+        : `Restart your dev server (\`${devCommand}\`)`;
+}
+/**
+ * The last two lines a user reads, and the order matters.
+ *
+ * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
+ * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
+ * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
+ * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
+ * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
+ * failed.
+ *
+ * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
+ * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
+ */
+export function restartHint(framework, mcpStatus, 
+/** The project's own dev command, when package.json named one. */
+devCommand) {
+    const dev = `${devServerRestart(framework, devCommand)}.`;
+    // NAME THE COMMAND THAT PROVES IT, not one that merely asks.
+    //
+    // `init` writes files and stops; the install is not finished until an app carrying the SDK has
+    // actually dialled the daemon, and nothing here confirmed that. The field shape is unambiguous:
+    // people complete the agent half, never complete the app half, and keep a daemon running for
+    // weeks with nothing to drive — so this is the last instruction most of them read.
+    //
+    // "Ask your agent: List Reticle sessions" asks a question whose failure is a dead end. `reticle
+    // status` ANSWERS it: as of 2.7.0 it reports the session, or says why there is none — no app
+    // running, an app running that never dialled us, a tab that closed — with the fix for each.
+    // The one thing that works BEFORE the restart, so it goes before it.
+    //
+    // What comes after the restart, named as a JOB rather than as a capability.
+    //
+    // This used to point at a `reticle demo` command that opened its own browser and drove one
+    // control. It was cut: a demo command is a side show. The thing a user needs to see is THEIR app,
+    // instrumented in THEIR codebase, driven by THEIR agent through the tools they just installed —
+    // because that is the workflow they are deciding whether to adopt, and a bespoke demo path proves
+    // nothing about it.
+    //
+    // So the close hands the agent the sequence instead. It is deliberately one drive of one real
+    // flow ending in a verdict, because an install that ends in "the tools are available" is an
+    // install that ends in nothing.
+    const demo = 'Then drive one real flow of your app end to end and report the verdict — that is the install ' +
+        "proving itself, and it is the agent's job, not a separate command.";
+    const prove = 'Then run `npx @reticlehq/server status` — it confirms the app connected, or says exactly why ' +
+        'it has not.';
+    // Nothing registered this run (`--no-mcp`, or a client that needs a manual edit): a restart picks
+    // up nothing, so advice about one would be advice about something we did not do.
+    if (!wasMcpRegistered(mcpStatus))
+        return `${dev}\n${demo}\n${prove}`;
+    // ALREADY: the tools are reachable RIGHT NOW, and this is the branch that used to lie.
+    //
+    // `wasMcpRegistered` is true for both APPLY and ALREADY, which is correct for the funnel field it
+    // was written for and wrong here, because the two cases have opposite answers to "must anybody
+    // restart". Every second project on a machine, and every Claude Code plugin install, took the
+    // APPLY text: "restart your agent — the tools only appear after that". An agent reads this AFTER
+    // whatever its skill file said, and it describes the output in front of it, so it wins. The agent
+    // stops with the project wired and nothing driven, which is the exact failure the install path
+    // exists to prevent, caused by the install path itself.
+    if (mcpStatus === StepStatus.ALREADY) {
+        return (`${dev}\n` +
+            `${demo}\n` +
+            'The Reticle MCP server was already registered on this machine, so there is no restart to do ' +
+            'and the tools are available now.\n' +
+            `${prove}\n` +
+            'Once it shows a session, drive a flow — that is the install finished. Carry straight on; ' +
+            'nothing here is waiting on a human.');
+    }
+    return (`${dev}\n` +
+        `${demo}\n` +
+        'Then restart your agent so it picks up the new MCP server — restart Claude Code, reload the ' +
+        'window in Cursor, or hit Start in `.vscode/mcp.json` in VS Code.\n' +
+        'The tools only appear after that: your agent read its server list before Reticle existed, ' +
+        'and no slash command re-reads it (`/mcp` manages servers already loaded, so it cannot pick ' +
+        'up a new one). This is once per machine — Reticle is registered globally, so every later ' +
+        'project starts with the tools already there.\n' +
+        `${prove}\n` +
+        'Once it shows a session, drive one flow and report the verdict — that is the install ' +
+        'finished. Do it now; nothing here is waiting on a human.');
+}

package/dist/init/confirm.d.ts

@@ -27,15 +27,6 @@
  */
 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>;
@@ -78,22 +69,6 @@ export declare function confirmAppConnected(deps: ConfirmDeps): Promise<InitConf
  * 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.
  *

package/dist/init/confirm.js

@@ -35,8 +35,8 @@ import { reportInitOutcome } from '../telemetry/init-telemetry.js';
  * 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;
+const CONFIRM_WINDOW_MS = 12_000;
+const CONFIRM_POLL_MS = 500;
 /**
  * Poll until an app connects or the window runs out.
  *
@@ -110,7 +110,7 @@ export function confirmationMessage(confirmation, port) {
  * 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) {
+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 ' +

package/dist/init/cra.d.ts

@@ -17,6 +17,19 @@ export declare const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
 export declare const CRA_DEV_MODULE_PATH = "src/reticle-dev.ts";
 export declare const CRA_ENV_PATH = ".env.development.local";
 export declare const TOKEN_VAR = "REACT_APP_RETICLE_TOKEN";
+/**
+ * The bridge URL, carried through the same channel as the token.
+ *
+ * CRA is the one supported stack with no build-time hook of ours: no plugin, no config wrapper, no
+ * `define`. Vite and Astro re-resolve the daemon every dev-server start and Next does it through
+ * `withReticle`; CRA has nowhere to run that code. So the URL goes where the token already goes, and
+ * is refreshed by the same `init` step that refreshes the token.
+ *
+ * That makes `reticle init` the heal rather than the dev server, which is weaker and is stated
+ * plainly in the step's own detail. It is still strictly better than a URL frozen into a source file
+ * the owner has to hand-edit, and `.env.development.local` is already the per-machine file.
+ */
+export declare const URL_VAR = "REACT_APP_RETICLE_URL";
 /**
  * What the app itself says when the token is not there.
  *
@@ -45,6 +58,6 @@ export declare const CRA_TOKEN_PER_MACHINE_NOTICE: string;
 /** Add the import after the last existing one, or null when it is already present. */
 export declare function craImportPatch(source: string): string | null;
 /** Set the token variable, or null when nothing needs to change. */
-export declare function craEnvPatch(existing: string | null, token: string): string | null;
+export declare function craEnvPatch(existing: string | null, token: string, url?: string): string | null;
 /** The dev-only connect module imported from `src/index.tsx`. */
 export declare function craDevModuleFile(port: number | undefined, projectId?: string): string;

package/dist/init/cra.js

@@ -12,12 +12,26 @@
  * `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 { bridgeWsUrl } from '@reticlehq/core';
 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';
 export const CRA_ENV_PATH = '.env.development.local';
 export const TOKEN_VAR = 'REACT_APP_RETICLE_TOKEN';
+/**
+ * The bridge URL, carried through the same channel as the token.
+ *
+ * CRA is the one supported stack with no build-time hook of ours: no plugin, no config wrapper, no
+ * `define`. Vite and Astro re-resolve the daemon every dev-server start and Next does it through
+ * `withReticle`; CRA has nowhere to run that code. So the URL goes where the token already goes, and
+ * is refreshed by the same `init` step that refreshes the token.
+ *
+ * That makes `reticle init` the heal rather than the dev server, which is weaker and is stated
+ * plainly in the step's own detail. It is still strictly better than a URL frozen into a source file
+ * the owner has to hand-edit, and `.env.development.local` is already the per-machine file.
+ */
+export const URL_VAR = 'REACT_APP_RETICLE_URL';
 /**
  * What the app itself says when the token is not there.
  *
@@ -64,25 +78,38 @@ export function craImportPatch(source) {
     return lines.join('\n');
 }
 /** Set the token variable, or null when nothing needs to change. */
-export function craEnvPatch(existing, token) {
+export function craEnvPatch(existing, token, url) {
     if ('' === token)
         return null;
-    const line = `${TOKEN_VAR}=${token}`;
-    if (null === existing || '' === existing.trim())
-        return `${line}\n`;
-    if (existing.includes(line))
-        return null;
-    // Replace rather than append: two assignments of one variable is a silent coin flip on which wins.
-    if (new RegExp(`^${TOKEN_VAR}=`, 'm').test(existing)) {
-        return existing.replace(new RegExp(`^${TOKEN_VAR}=.*$`, 'm'), line);
+    const pairs = [
+        [TOKEN_VAR, token],
+        ...(url !== undefined && url.length > 0 ? [[URL_VAR, url]] : []),
+    ];
+    let next = null === existing || '' === existing.trim() ? '' : existing;
+    for (const [name, value] of pairs) {
+        const line = `${name}=${value}`;
+        if (next.includes(line))
+            continue;
+        // Replace rather than append: two assignments of one variable is a silent coin flip on which
+        // wins, and for the URL that coin decides which daemon the app talks to.
+        if (new RegExp(`^${name}=`, 'm').test(next)) {
+            next = next.replace(new RegExp(`^${name}=.*$`, 'm'), line);
+        }
+        else {
+            next = `${'' === next || next.endsWith('\n') ? next : `${next}\n`}${line}\n`;
+        }
     }
-    return `${existing.endsWith('\n') ? existing : `${existing}\n`}${line}\n`;
+    return next === (existing ?? '') ? null : next;
 }
 /** The dev-only connect module imported from `src/index.tsx`. */
 export function craDevModuleFile(port, projectId) {
     const fields = [];
+    // `bridgeWsUrl`, not a hand-written string. This was the only client URL in the product spelling
+    // the host as `127.0.0.1` while every other generator said `localhost` — same endpoint, but a
+    // difference with no reason behind it is the kind that becomes a real one after somebody edits half
+    // of it.
     if (port !== undefined)
-        fields.push(`url: 'ws://127.0.0.1:${String(port)}/reticle'`);
+        fields.push(`url: '${bridgeWsUrl(port)}'`);
     if (projectId !== undefined && projectId.length > 0)
         fields.push(`projectId: '${projectId}'`);
     const inline = fields.length > 0 ? `${fields.join(', ')}, ` : '';
@@ -95,10 +122,14 @@ if (process.env.NODE_ENV === 'development') {
   void import('@reticlehq/react').then(({ reticle, install }) => {
     install();
     const token = process.env.${TOKEN_VAR} ?? '';
+    // Written by \`reticle init\` from the daemon that was live when it ran, and refreshed by
+    // re-running it. CRA gives us no hook to resolve this at dev-server start, so if the daemon
+    // moves, re-run \`reticle init\` rather than editing the url below.
+    const url = process.env.${URL_VAR} ?? '';
     // Loud on purpose: without this the only symptom is the bridge's generic auth failure.
     if (token.length === 0) console.error(${JSON.stringify(`[reticle] ${CRA_TOKEN_MISSING_NOTE}`)});
     // Still attempt it — a bridge running without a token pairs fine.
-    reticle.connect({ ${inline}...(token.length > 0 ? { token } : {}) });
+    reticle.connect({ ${inline}...(url.length > 0 ? { url } : {}), ...(token.length > 0 ? { token } : {}) });
   });
 }
 

package/dist/init/dev-script.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Which command starts this project, and should we start it ourselves?
+ *
+ * `init` finishes by telling the human to start or restart their dev server, in a closing
+ * paragraph, in a terminal that is about to be cleared by the client restart it also asks for.
+ * That is the second unmarked hand-off in the install, after the capabilities file, and it lands
+ * on the same surface: prose nobody re-reads.
+ *
+ * Every fact needed to remove it is already in the project. `package.json` names the script; the
+ * framework tells us the conventional port; a probe tells us whether something already answers
+ * there. Nothing here needs a human.
+ *
+ * Kept as a PURE decision, separate from spawning, because the interesting part is the judgement —
+ * which script, and whether to touch anything at all — and that is what wants testing. Spawning a
+ * process is not.
+ */
+export declare const DevScriptChoice: {
+    /** Something already answers on the port. Use it; never replace a server the user is running. */
+    readonly ALREADY_SERVING: "already-serving";
+    /** We know the command and nothing is listening. Start it. */
+    readonly START: "start";
+    /** No script we recognise. Say so rather than guess a command. */
+    readonly NO_SCRIPT: "no-script";
+};
+export type DevScriptChoice = (typeof DevScriptChoice)[keyof typeof DevScriptChoice];
+export interface DevScriptPlan {
+    choice: DevScriptChoice;
+    /** The npm script name, when there is one. */
+    script?: string;
+    /** What a human would type, for the line we print. */
+    command?: string;
+}
+/**
+ * Pick the script and decide whether to run it.
+ *
+ * `serving` is the probe result, passed in rather than measured here so the decision stays pure.
+ * When something is already answering we do not care which script exists: the rule is never to
+ * start a second server, because the one that is running may be the user's, with their state in it.
+ */
+export declare function planDevScript(scripts: Readonly<Record<string, string>>, packageManager: string, serving: boolean): DevScriptPlan;
+/**
+ * The command to print for this project, straight from its `package.json`.
+ *
+ * Lives here rather than in `run.ts` because it is the same judgement as `planDevScript` with the
+ * parsing attached, and `run.ts` is at its cohesion limit. Returns undefined for anything it cannot
+ * read: this phrasing decides nothing, so it must never be able to break an install.
+ */
+export declare function devCommandFrom(pkgRaw: string, packageManager: string): string | undefined;

package/dist/init/dev-script.js

@@ -0,0 +1,63 @@
+/**
+ * Which command starts this project, and should we start it ourselves?
+ *
+ * `init` finishes by telling the human to start or restart their dev server, in a closing
+ * paragraph, in a terminal that is about to be cleared by the client restart it also asks for.
+ * That is the second unmarked hand-off in the install, after the capabilities file, and it lands
+ * on the same surface: prose nobody re-reads.
+ *
+ * Every fact needed to remove it is already in the project. `package.json` names the script; the
+ * framework tells us the conventional port; a probe tells us whether something already answers
+ * there. Nothing here needs a human.
+ *
+ * Kept as a PURE decision, separate from spawning, because the interesting part is the judgement —
+ * which script, and whether to touch anything at all — and that is what wants testing. Spawning a
+ * process is not.
+ */
+/** Script names a JS project uses to run itself, in the order we would pick them. */
+const CANDIDATES = ['dev', 'start', 'serve'];
+export const DevScriptChoice = {
+    /** Something already answers on the port. Use it; never replace a server the user is running. */
+    ALREADY_SERVING: 'already-serving',
+    /** We know the command and nothing is listening. Start it. */
+    START: 'start',
+    /** No script we recognise. Say so rather than guess a command. */
+    NO_SCRIPT: 'no-script',
+};
+/**
+ * Pick the script and decide whether to run it.
+ *
+ * `serving` is the probe result, passed in rather than measured here so the decision stays pure.
+ * When something is already answering we do not care which script exists: the rule is never to
+ * start a second server, because the one that is running may be the user's, with their state in it.
+ */
+export function planDevScript(scripts, packageManager, serving) {
+    if (serving)
+        return { choice: DevScriptChoice.ALREADY_SERVING };
+    const name = CANDIDATES.find((c) => 'string' === typeof scripts[c] && scripts[c] !== '');
+    if (name === undefined)
+        return { choice: DevScriptChoice.NO_SCRIPT };
+    // `npm` needs `run`; the others take the script name directly. Getting this wrong prints a
+    // command that fails, which is worse than printing nothing.
+    const command = 'npm' === packageManager ? `npm run ${name}` : `${packageManager} ${name}`;
+    return { choice: DevScriptChoice.START, script: name, command };
+}
+/**
+ * The command to print for this project, straight from its `package.json`.
+ *
+ * Lives here rather than in `run.ts` because it is the same judgement as `planDevScript` with the
+ * parsing attached, and `run.ts` is at its cohesion limit. Returns undefined for anything it cannot
+ * read: this phrasing decides nothing, so it must never be able to break an install.
+ */
+export function devCommandFrom(pkgRaw, packageManager) {
+    try {
+        const parsed = JSON.parse(pkgRaw);
+        const scripts = 'object' === typeof parsed && null !== parsed
+            ? (parsed.scripts ?? {})
+            : {};
+        return planDevScript(scripts, packageManager, false).command;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/init/mcp.d.ts

@@ -15,11 +15,16 @@ export { MCP_SERVER_NAME } from '@reticlehq/core';
 /**
  * The registered command is STILL bare `npx` on every platform, deliberately.
  *
- * Windows is 66% of Reticle's users (65 of 99 in a day of telemetry) and has NO CI, no fixture, and
- * nothing in this repo has ever run there. Switching the majority platform to a launch command
- * nobody can test — where `.cmd` also has its own spawn caveats in some hosts — risks breaking the
- * users it is meant to help. So the fallback is DOCUMENTED (see mcpManual) rather than defaulted,
- * until somebody can run it on Windows.
+ * Windows is most of Reticle's users and, when this was written, had no CI. There is Windows CI
+ * now, so the `cmd /c` fallback is testable. Defaulting the majority platform to that launch
+ * command is still the riskier change: `.cmd` has spawn caveats in some hosts, and a registration
+ * that works on the machines we can test can still fail in the hosts we cannot. So the fallback
+ * stays documented rather than defaulted.
+ *
+ * What DID change is when it is printed. `mcpManual` used to run only when the `claude` CLI was
+ * absent. The reported Windows install had `claude mcp add` succeed, so the one paragraph that
+ * would have unblocked zero tools never appeared. `mcpWindowsNote` is that paragraph, and init
+ * prints it on every Windows run — including the ones that look like a clean registration.
  */
 export declare const NPX = "npx";
 /**
@@ -74,5 +79,11 @@ export declare function claudeAvailableProbe(): {
     command: string;
     args: string[];
 };
+/**
+ * The Windows `cmd /c npx` registration. Printed on every Windows init, not only when the `claude`
+ * CLI is missing — a successful `claude mcp add` of bare `npx` is exactly the failure that reported
+ * as a clean install with zero tools.
+ */
+export declare function mcpWindowsNote(): string;
 /** Printed when the `claude` CLI isn't available — register Reticle globally once, by hand. */
 export declare function mcpManual(): string;