@reticlehq/server 3.10.0 → 3.10.1

package/dist/command/setup/init/init-runtime.js

@@ -7,7 +7,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { InitConfirmation, OnboardingPhase, OnboardingStop, RETICLE_DEFAULT_PORT, } from '@reticlehq/core';
+import { InitConfirmation, InitStop, OnboardingPhase, OnboardingStop, RETICLE_DEFAULT_PORT, } from '@reticlehq/core';
 import { COMMUNITY_HINT, FEEDBACK_HINT, Framework, InitFailure, } from '@reticlehq/init';
 import { confirmInstall, nodeConfirmDeps } from '../terminal/confirm.js';
 import { writeLicenseKey } from '../license-key.js';
@@ -85,6 +85,11 @@ function printRelaunch(parsed, io, cwd) {
     }).message);
     io.print('');
 }
+/** The dev-server stops caused by the machine, not the app: the files init wrote are right. */
+const WIRED_WHEN_STOPPED_AT = new Set([
+    InitStop.PORT_BUSY,
+    InitStop.SPLIT_LOOPBACK,
+]);
 export async function continueAfterInit(parsed, result, io, cwd, 
 /** init's ending once the connection is proved: coverage and the agent prompt. See `FirstFlowPort`. */
 firstFlow, agentsBlock) {
@@ -256,6 +261,14 @@ firstFlow, agentsBlock) {
             : { pendingViteConfig: context.pendingViteConfig }),
     }, (line) => io.print(line))
         .then(async (outcome) => {
+        // The files are written before the app starts. When the app could not be reached for a reason
+        // of the machine, not of the app (its port was taken, or it answered on one loopback address
+        // and not the other), the project is wired and not confirmed yet: not a failed install.
+        // A dev server that exits, hangs or does not exist, and a failure to connect, still fail.
+        const wiredNotStarted = !outcome.ok &&
+            outcome.reachedPhase === SetupPhase.DEV_SERVER &&
+            undefined !== outcome.stop &&
+            WIRED_WHEN_STOPPED_AT.has(outcome.stop);
         if (result.outcome !== undefined) {
             const init = {
                 ...result.outcome,
@@ -265,6 +278,14 @@ firstFlow, agentsBlock) {
                 delete init.reason;
                 init.confirmation = InitConfirmation.CONNECTED;
             }
+            else if (wiredNotStarted) {
+                init.ok = true;
+                delete init.reason;
+                init.confirmation = InitConfirmation.DEV_SERVER_NOT_STARTED;
+                if (outcome.stop !== undefined) {
+                    init.stop = outcome.stop;
+                }
+            }
             else {
                 // A failed startup does not establish whether a daemon or instrumented page exists.
                 // Keep the watcher's no_daemon/no_session/no_page classifications for observed facts.
@@ -281,7 +302,11 @@ firstFlow, agentsBlock) {
         }
         // One object, so an agent reads a result instead of interpreting a report.
         if (true === parsed.json) {
-            process.stdout.write(`${JSON.stringify(outcome, null, 2)}\n`);
+            const answer = wiredNotStarted ? { ...outcome, ok: true, confirmed: false } : outcome;
+            process.stdout.write(`${JSON.stringify(answer, null, 2)}\n`);
+            if (wiredNotStarted) {
+                return;
+            }
             if (!outcome.ok) {
                 stop();
             }
@@ -334,6 +359,16 @@ firstFlow, agentsBlock) {
             io.print(COMMUNITY_HINT);
             return;
         }
+        if (wiredNotStarted) {
+            io.print('✓ Reticle is wired into this app. Its dev server did not start, so the connection is not ' +
+                'confirmed yet. To confirm it:');
+            for (const [i, step] of outcome.fallback.entries()) {
+                io.print(`   ${String(i + 1)}. ${step}`);
+            }
+            io.print(`   ${String(outcome.fallback.length + 1)}. Run \`reticle status\`: it lists the app when it connects.`);
+            ask();
+            return;
+        }
         // A run that produced no verdict did not succeed, and the exit code is the one place a caller
         // reads that without parsing anything.
         io.print('⚠ setup did not finish. To carry on from here:');

package/docs/cli/init.mdx

@@ -122,8 +122,8 @@ In the two captures above, the punctuation that separates the two halves of the
 
 | Code | Meaning |
 | --- | --- |
-| `0` | The app connected. Steps marked `⚠` still need a hand, and do not change the code |
-| `1` | No session connected, init failed, an unknown flag was passed, or several apps were found and none was chosen |
+| `0` | The app connected. Or the files are written and the machine kept the dev server from starting (its port was taken, or it answered on one loopback address only): init prints the steps to confirm the connection (`--json` answers `"confirmed": false`). Steps marked `⚠` still need a hand, and do not change the code |
+| `1` | The dev server exited, hung or does not exist, a running app did not connect, init failed, an unknown flag was passed, or several apps were found and none was chosen |
 
 An unknown flag is rejected by name: `reticle init --bogus` prints `unknown argument '--bogus'`, then the short usage (`reticle --help`), and exits `1`.
 

package/docs/deploy-checks.md

@@ -70,7 +70,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: reticlehq/reticle/action@v3.10.0
+      - uses: reticlehq/reticle/action@v3.10.1
         with:
           api-key: ${{ secrets.RETICLE_API_KEY }}
           # Only for a Vercel preview behind Deployment Protection.

package/docs/skill.md

@@ -3,7 +3,7 @@ name: reticle-docs
 description: Install, instrument and verify this running web app from the inside (DOM, network, routing, console and framework state) instead of screenshots or guessing. Drives one real flow end to end and returns a verdict with the file:line to fix. Use when the user asks to set up or install Reticle, when a user-facing change needs proving before you call it done, when a test passes but the UI is broken, or when the user types /reticle.
 license: Apache-2.0
 metadata:
-  version: 3.10.0
+  version: 3.10.1
   homepage: https://docs.reticle.sh
   repository: https://github.com/reticlehq/reticle
   internal: true

package/docs/troubleshooting.mdx

@@ -11,6 +11,35 @@ Reticle is a verification layer that runs a dev-only SDK inside your running web
 
 Most of these were hit while writing these docs. The diagnostics quoted are real output.
 
+## Quick fixes
+
+| What you see | Why | Fix |
+| --- | --- | --- |
+| Agent says the `reticle_*` tools do not exist | It read its tool list before Reticle was installed | Restart the agent once. Mid-conversation: `reticle init --relaunch` prints the resume command |
+| "no browser session connected" | The dev server was already running when `init` edited the build config, so it serves a bundle without the SDK | Restart the dev server and hard-reload the tab |
+| Browser console: `[Reticle] this page could not open a websocket to …` | The app and Reticle disagree on the port | `RETICLE_PORT=4400 npm run dev` (Vite plugin), `reticle({ port: 4400 })` in `vite.config`, or `reticle.connect({ url: 'ws://localhost:4400/reticle' })` by hand |
+| `init` stops with "Several apps found" | A monorepo | Rerun with the `reticle init --app <dir>` line it printed |
+| Codex does not see the tools | The `codex` command was not on PATH, so the installer could not run `codex mcp add` | `codex mcp add reticle -- npx @reticlehq/server mcp`, or add the block from [Manual install](/install-manual#codex-cli) to `~/.codex/config.toml` |
+| `reticle: command not found` | npm's global bin is not on your PATH | `export PATH="$(npm prefix -g)/bin:$PATH"`, or use `npx @reticlehq/server …` |
+| Anything else |  | `reticle doctor` checks the browser, the background service and the port in one go, and names the fix |
+
+Still stuck? `reticle feedback "what happened"` reaches us directly and prints exactly what it sends. Or ask in [Discord](https://discord.gg/BwAbzv9ZRz).
+
+<details>
+<summary><b>Installing with an AI agent? The rules it should follow</b></summary>
+
+<br />
+
+The full agent guide is [SKILL.md](https://github.com/reticlehq/reticle/blob/main/SKILL.md). These are the rules that matter most during install:
+
+- `init` changes the user's files. Run it only when the user asked to set up Reticle, or agreed when you offered. Run it in the app's folder. Use `reticle init --json`, so you read one object instead of parsing text. Add `--app <dir>` in a monorepo, and `--env KEY=VALUE` for anything the app needs to start.
+- If the dev server was already running when `init` ran, restart it and reload the tab. Until you do, the app serves a bundle without the SDK.
+- Run `reticle connect` only if the user asked for the dashboard. A person must approve the sign-in in a browser.
+- If the `reticle_*` tools are not in your client, ask the user to run the installer and restart the client. Then stop. If the tools were registered while you were running, `reticle init --relaunch` prints the command that resumes this conversation with them loaded.
+- A session listed means the SDK reached the page. Setup is finished when the first run returns a verdict.
+- `unknown` is not a pass. Report it as "cannot tell", with the reason Reticle gives.
+- Stuck? Run `reticle doctor` and report what it says. To report a problem with Reticle, run `reticle feedback --agent --kind bug "…"`.
+
 ## Start here
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/server",
-  "version": "3.10.0",
+  "version": "3.10.1",
   "mcpName": "io.github.reticlehq/reticle",
   "description": "Reticle CLI, bridge and MCP server: a coding agent drives your running web app from the inside and gets a verdict with evidence, for change verification, access control, accessibility, performance and SEO checks.",
   "type": "module",
@@ -23,11 +23,11 @@
     "@modelcontextprotocol/sdk": "^1.32.2",
     "ws": "^8.22.1",
     "zod": "^4.6.6",
-    "@reticlehq/browser": "3.10.0",
-    "@reticlehq/init": "3.10.0",
-    "@reticlehq/core": "3.10.0",
-    "@reticlehq/engine": "3.10.0",
-    "open-verification": "1.1.0"
+    "@reticlehq/browser": "3.10.1",
+    "@reticlehq/init": "3.10.1",
+    "open-verification": "1.1.0",
+    "@reticlehq/engine": "3.10.1",
+    "@reticlehq/core": "3.10.1"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",
@@ -65,11 +65,8 @@
     "cli"
   ],
   "reticle": {
-    "changelog": "3.10.0 checks every change against what worked before. reticle compare and verify --against list what users would see change between two builds, and reticle grade grades a finished run from the app's stored data. Several false verdicts are fixed, most of them text checks that answered no for text that was on the page. An agent in a Claude Code worktree now reaches its own tab. Update the CLI and the SDK in your app.",
-    "breakingChanges": [
-      "The commands kill, login, link, project, whoami, push, regression, share, issues and memory are removed. Each prints the command that replaces it and exits 1. See MIGRATION.md.",
-      "The MCP tools reticle_explore and reticle_replay left the tool surface. Use reticle_look { action: \"page\", mode: \"interactive\" } and reticle_record { action: \"replay\" }."
-    ]
+    "changelog": "3.10.1 fixes reticle init on a busy machine. When the dev server could not start because its port was taken, or the app answered on one loopback address only, init reported a failed install although the project was wired. Now it says Reticle is wired, prints the steps to confirm the connection, and exits 0.",
+    "breakingChanges": []
   },
   "publishConfig": {
     "access": "public"