@reticlehq/server 3.8.0 → 3.8.1

package/dist/telemetry/daemon-telemetry.d.ts

@@ -5,7 +5,7 @@
  * It lives apart from `cli.ts` because it has its own timers and its own failure rule — nothing here
  * may ever be able to fail a daemon start — and because `cli.ts` is a dispatcher.
  */
-import { type SessionSummary } from '@reticlehq/core/telemetry';
+import { DaemonSpawnMethod, type SessionSummary } from '@reticlehq/core/telemetry';
 /**
  * How often a running daemon rolls up its window.
  *
@@ -29,6 +29,8 @@ export declare const SESSION_FLUSH_MS: number;
  * costs nothing on a daemon that never serves a tool, because only a NON-EMPTY window emits.
  */
 export declare const FIRST_FLUSH_MS: number;
+/** How the parent started this daemon, from the env it set. Anything else reads as absent. */
+export declare function daemonSpawnMethod(env?: Readonly<Record<string, string | undefined>>): DaemonSpawnMethod | undefined;
 /** Stops the timers this installed. Called from the daemon's shutdown path. */
 interface DaemonTelemetry {
     /**

package/dist/telemetry/daemon-telemetry.js

@@ -5,7 +5,8 @@
  * It lives apart from `cli.ts` because it has its own timers and its own failure rule — nothing here
  * may ever be able to fail a daemon start — and because `cli.ts` is a dispatcher.
  */
-import { TelemetryEventKind } from '@reticlehq/core/telemetry';
+import { DaemonSpawnMethod, TelemetryEventKind, } from '@reticlehq/core/telemetry';
+import { ReticleEnv } from '@reticlehq/core';
 import { getTelemetry } from './telemetry.js';
 import { getSessionMetrics } from './session-metrics.js';
 import { profileProject } from './project-profile.js';
@@ -78,6 +79,11 @@ function withNudgeState(summary) {
         ...(nudge.offered === undefined ? {} : { updateOffered: nudge.offered }),
     };
 }
+/** How the parent started this daemon, from the env it set. Anything else reads as absent. */
+export function daemonSpawnMethod(env = process.env) {
+    const value = env[ReticleEnv.SPAWN_METHOD];
+    return Object.values(DaemonSpawnMethod).find((method) => method === value);
+}
 /**
  * Report the daemon as started, profile the project once, and keep the session counters flushing.
  * Every timer is `unref`'d so telemetry can never be the reason a daemon refuses to exit.
@@ -91,7 +97,8 @@ export function installDaemonTelemetry(cwd, now = () => Date.now(),
  */
 port) {
     const metrics = getSessionMetrics(now);
-    void getTelemetry().emit(TelemetryEventKind.DAEMON_STARTED);
+    const spawnMethod = daemonSpawnMethod();
+    void getTelemetry().emit(TelemetryEventKind.DAEMON_STARTED, spawnMethod === undefined ? undefined : { spawnMethod });
     // Reports a past send could not deliver. Off the boot path, and never able to throw into it.
     void drainFeedbackOutbox().catch(() => undefined);
     // Ask npm whether a newer Reticle exists, so the agent can tell the human. Nothing checked before

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,4 @@
-import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type OnboardingStep, type InstallSource, type McpConnection, type McpOutage, type DaemonDeath, type ProxyExit, type WakeRefusal, type ToolRefusal, type AppInstrumentation, type HarnessRun, type HudEvent, type PlatformLink, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core/telemetry';
+import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type OnboardingStep, type InstallSource, type McpConnection, type McpOutage, type DaemonDeath, type ProxyExit, type WakeRefusal, type DaemonSpawnMethod, type ToolRefusal, type AppInstrumentation, type HarnessRun, type HudEvent, type PlatformLink, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core/telemetry';
 /**
  * Presence of this file marks the MACHINE as the Reticle team's own: every event carries
  * `internal: true`. The persistent twin of `RETICLE_INTERNAL=1`, for a dev machine where setting a
@@ -113,6 +113,8 @@ export interface TelemetryExtra {
     daemonDeath?: DaemonDeath;
     /** `wake_refused`: what held the port. */
     wakeRefusal?: WakeRefusal;
+    /** `daemon_started`: how the parent started the daemon. */
+    spawnMethod?: DaemonSpawnMethod;
     /**
      * `platform_linked`: the workspace just linked. Overrides the envelope's own reading, which looks
      * at the daemon's working directory and not at the project the HUD linked.

package/dist/telemetry/telemetry.js

@@ -470,6 +470,8 @@ export const createTelemetry = (opts) => {
             ...(extra?.proxyExit !== undefined ? { proxyExit: extra.proxyExit } : {}),
             ...(extra?.daemonDeath !== undefined ? { daemonDeath: extra.daemonDeath } : {}),
             ...(extra?.wakeRefusal !== undefined ? { wakeRefusal: extra.wakeRefusal } : {}),
+            // A SCALAR: the event build and the wire schema, no `blocks` entry.
+            ...(extra?.spawnMethod !== undefined ? { spawnMethod: extra.spawnMethod } : {}),
         };
         // The wire schema's caps are only real if something applies them. An event that fails is
         // DROPPED, never sent and never repaired: the payload is exactly what the caps exist to stop.

package/docs/agent-cheatsheet.md

@@ -48,6 +48,7 @@ Two consequences worth knowing:
 
 - **You can assert what a field contains.** Do not read the value with `reticle_look { action: "find" }` and compare it in prose: that produces no verdict and does not count as verification.
 - **`{ role, text }` checks the text,** so it does not match every button with that role.
+- **A `text` predicate reads rendered text, not a field's value.** Text typed into an `<input>` or a `<textarea>` is not on the page as text, so `{ kind: "text", contains }` does not see it. Assert it with `value` on an `element` predicate, as above.
 
 Fields that nothing can check are refused rather than ignored: `by` without a `value`, and `label`, `placeholder`, `testid` or `component` when a higher-precedence field already selected the element. `alt` is the one that can still be checked beside another locator: on an image it is compared with the image's `alt` attribute (so `alt: ""` passes on a decorative image but not on one missing its alt), and on anything that is not an image it is refused, with a hint to use `name`. An element query is a first-match dispatch, not a conjunction.
 
@@ -164,6 +165,17 @@ Recent additions, each of which answers a question agents were previously asking
 2. `reticle_run({ tool: "reticle_domain", args: {} })` learns the app BEFORE testing: the saved flows, what each asserts, and the **gaps** (declared signals/testids that no flow verifies, i.e. untested intent). Tells you what to test and where the real risk is without crawling the whole app. Falls back to `reticle_run({ tool: "reticle_capabilities", args: {} })` for the raw testable surface (`testids`, `signals`, `stores`, `flows`).
 3. Run the loop: **look → act → observe → assert**, cross-checking the 4 layers on anything that matters.
 
+## No MCP tools in this host
+
+A cloud agent or a worker can have a shell and no MCP tools. Use the CLI. `verify --expect` asks a running daemon and never starts one, so start it first:
+
+```bash
+npx @reticlehq/server serve --headless
+npx @reticlehq/server verify http://localhost:5173/ --expect '{"kind":"text","contains":"Welcome"}'
+```
+
+It exits `0` only on `verified: "yes"`. `--expect-file <path>` reads the predicate from a file, and `--timeout N` sets how long it waits (default `4000` ms). To move a connected tab to another page first, run `npx @reticlehq/server open <url> --navigate`. For an action that `--expect` cannot do, use the [HTTP MCP transport](/http-transport).
+
 ## Token note
 
 - **Keep observation cheap.** Prefer `reticle_look { action: "find" }` / scoped or `interactive` `reticle_look { action: "page" }` / `reticle_assert` over dumping the full tree. A full verify loop is ~100 tokens; see [Token efficiency](/token-efficiency) (~73× leaner than full-tree snapshots).

package/docs/cli/gate.mdx

@@ -49,7 +49,7 @@ One `reticle_gate` line. Real capture from this repository, with the flow lists
 }
 ```
 
-`downgraded`, `deletedCoverage`, `unflowed`, `coverageRegressed`, `unexecuted`, `coverageStale` and `coverageAccepted` appear only when they are non-empty, and none was present in that run. The coverage categories need a coverage ledger, which a project gets from `reticle_verify { action: "crawl", exhaustive: true }` or `reticle_verify { action: "coverage", app: true }`; without one they never fire. The CLI prints this as a single line of JSON; it is pretty-printed here to be readable.
+`downgraded`, `deletedCoverage`, `unflowed`, `coverageRegressed`, `unexecuted`, `coverageStale` and `coverageAccepted` appear only when they are non-empty, `flowsWithoutSources` only when it is `true`, and none was present in that run. The coverage categories need a coverage ledger, which a project gets from `reticle_verify { action: "crawl", exhaustive: true }` or `reticle_verify { action: "coverage", app: true }`; without one they never fire. The CLI prints this as a single line of JSON; it is pretty-printed here to be readable.
 
 ## Exit codes
 

package/docs/cli/verify.mdx

@@ -7,7 +7,7 @@ icon: circle-check
 `reticle verify` is the CI command: no model in the loop, no MCP. On a free port it boots the engine in drive mode, waits for the in-page SDK to dial back, replays every saved flow, renders the verdict, and exits. When a Reticle daemon already owns the port, it asks that daemon to replay the flows instead.
 
 ```bash
-npx @reticlehq/server verify <url> [--headed] [--timeout N] [--storage-state <file>]
+npx @reticlehq/server verify <url> [--headed] [--timeout N] [--storage-state <file>] [--expect <json> | --expect-file <path>]
 ```
 
 It uses the same runner and the same verdict as the MCP and HTTP paths, so a platform agent that can only run a shell command gets a byte-identical artifact.
@@ -28,6 +28,13 @@ It uses the same runner and the same verdict as the MCP and HTTP paths, so a pla
 | `--explore` / `--persona "<who does what>"` | boolean / string | off | No saved flows yet? The Harness drives the app and records them. `--persona` implies `--explore`. Needs a linked project (`reticle connect`, or `RETICLE_API_KEY` in CI). It runs at any instrumentation score |
 | `--confirm-dangerous` | boolean | off | Let this run press the controls the replay guard holds as destructive, such as a "Place order" or "Delete" button in a saved flow. Without it such a step is refused, so a checkout flow cannot pass. It covers this run only and is never saved into a flow. |
 
+On Windows PowerShell, write the predicate to a file and pass `--expect-file` so the JSON never goes through shell quoting:
+
+```powershell
+'{"kind":"text","contains":"Saved"}' | Set-Content expect.json
+npx @reticlehq/server verify http://localhost:3000 --expect-file expect.json
+```
+
 ## What it prints
 
 The rendered run report on stdout. On failure it names the cause on stderr instead, and there are two refusals worth knowing:

package/docs/first-drive.md

@@ -72,6 +72,13 @@ node server/dist/command/cli.js verify http://localhost:4310/ --port 4400 \
   --expect '{"kind":"text","contains":"definitely not on this page"}'
 ```
 
+On Windows PowerShell, `npx.cmd` re-parses `--expect '{...}'` and strips the inner quotes. Prefer `--expect-file`:
+
+```powershell
+'{"kind":"text","contains":"Saved"}' | Set-Content expect.json
+npx @reticlehq/server verify http://localhost:3000 --expect-file expect.json
+```
+
 ## 3. Drive it properly, with the tools
 
 If your editor has the Reticle MCP server, the same app is now drivable. The four calls worth knowing, in the order you actually use them:

package/docs/multi-agent-testing.md

@@ -36,6 +36,8 @@ reticle_run { tool: "reticle_lease", args: { action: "release", sessionId } }
 
 `reticle_run { tool: "reticle_lease", args: { action: "acquire" } }` opens a fresh isolated headless context against your **already-running** app, stamps the lease identity into the URL so the app's own SDK registers under a sessionId you can target, and waits until that tab has connected (`ready: true`) before returning, so the sessionId is usable immediately. Release when the flow finishes.
 
+**Lease the exact host that the dev server binds.** `http://localhost:3000` and `http://127.0.0.1:3000` are two origins, and they are not the same address. A dev server that binds only `::1` (Vite can do this for `localhost`) refuses a lease on `127.0.0.1`, and a server that binds only `127.0.0.1` does not answer on `::1`. The two origins also have their own cookies and storage, and a lease is reused for each origin. Copy the url that the dev server prints, host and port included.
+
 ## Permissions
 
 A lease starts with every permission undecided. Pass `permissions` to grant some on the app's origin before the first navigation, so the first render already sees them:

package/docs/predicates.mdx

@@ -73,6 +73,12 @@ Add `"absent": true` to assert something is **gone**. The predicate for a remova
 
 `contains` is the field the published schema declares. `value`, `text` and `query` are accepted as aliases and rewritten to it. The match is case-sensitive. `ignoreCase: true` relaxes that. Curly quotes (`‘ ’ “ ”`), the en dash and the em dash match their plain forms. So `It's saved - done` matches a page that shows `It’s saved – done`. Text that Reticle reports back keeps the page's own characters. `absent: true` asserts the text is not present, and `visible: true` requires it to be on screen rather than merely in the DOM.
 
+`text` reads the text that the page renders. It does not read what is typed into an `<input>` or a `<textarea>`, because that is the field's value, not text on the page. `value` on a `text` predicate is only an alias for `contains`, so it also reads rendered text. To assert what a field holds, use an `element` predicate with `value`:
+
+```json
+{ "kind": "element", "query": { "role": "textbox", "name": "Notes", "value": "Ship on Friday" } }
+```
+
 Use `scope` to restrict the search to a CSS selector or element ref. If Reticle reports that the text is split across the scope's children, retry its generated predicate with `"self": true`; that checks the scope root's combined subtree text while still enforcing `contains`.
 
 `satisfies` asserts a PROPERTY of the rendered text instead of its exact bytes: the same shape and the same properties [`state` accepts](#satisfies-asserting-a-property-instead-of-exact-bytes), applied where the user actually reads the value:

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.8.0
+  version: 3.8.1
   homepage: https://docs.reticle.sh
   repository: https://github.com/reticlehq/reticle
   internal: true
@@ -149,7 +149,7 @@ Stop at the first row that fits. Replaying a saved journey costs a few hundred t
 | "Did my edit break anything?" | `reticle_verify { action: "change", files: ["src/App.tsx"] }` |
 | "Does every saved journey still work?" | `reticle_verify { action: "flows" }` |
 | "Does this new behaviour work?" | `reticle_act_and_wait` on the step that ENDS the journey |
-| No MCP at all | `npx @reticlehq/server verify <url> --expect '<predicate JSON>'` |
+| No MCP tools (a cloud agent, a worker) | `npx @reticlehq/server serve`, then `npx @reticlehq/server verify <url> --expect '<predicate JSON>'`. `open <url> --navigate` moves a connected tab to `<url>` |
 
 `change` answers `unknown` when no saved flow covers your files: nothing ran, so drive it yourself and never read it as a pass. A locator that was renamed rather than broken: `reticle_verify { action: "heal", flowName }` proposes the rebind, and `apply: true` writes it after it proves the saved consequence again.
 
@@ -172,7 +172,7 @@ A journey in one call: `reticle_act { steps: [{ target, action, args?, expect? }
 | ref no longer resolves | the DOM re-rendered: target by `testid` or `role`+`name` |
 | predicate did not parse | it names the field: fix the shape against the table above |
 | destructive action blocked | `args.confirmDangerous: true`, only if the user wants that press |
-| version skew | `npx @reticlehq/server stop`, then retry |
+| version skew | update the CLI and the app SDK (`npx @reticlehq/server update` in the app's folder), then restart the MCP host |
 | port held by a non-Reticle process | stop that process, or run Reticle on another `--port` |
 | tab served from another worktree | start the dev server in your own worktree; keep the port |
 

package/docs/troubleshooting.mdx

@@ -240,6 +240,16 @@ A dev server on `https://` with a self-signed or mkcert certificate makes `retic
 
 It is off by default. When it is on, certificate checks are skipped for every site opened in that lease's browser context, including resources loaded from other sites. Other leases keep their checks. A context cannot change the setting once it is made, so acquiring again with the other value replaces the lease instead of reusing it.
 
+## The page never connects under a strict CSP
+
+A build that sends a strict Content-Security-Policy blocks the bridge socket. A production build that you run locally (`next start`, `vite preview`) often sends one. The app runs, and the SDK never connects, with no error in the app. Add the bridge to `connect-src`, with your bridge port if it is not `4400`:
+
+```text
+connect-src 'self' ws://localhost:4400 ws://127.0.0.1:4400
+```
+
+Add it only in the builds that Reticle drives, never in the policy that you deploy. If the policy also blocks inline scripts, `script-src` stops a pasted connect snippet before it runs: serve that snippet as an external module. `reticle doctor` reads the policy that the page serves and names the line to add, and a lease result says the same. For [production mode](/production-mode), add the `wss://` bridge from the ticket instead. Desktop apps have their own note in [Desktop](/desktop).
+
 ## `ERESOLVE` installing next to a prerelease
 
 `@reticlehq/next` declares `peer next >=13` and `@reticlehq/react` declares `peer react >=18`. On a Next canary or React RC, npm refuses. See [the prerelease notes](/getting-started#installing-alongside-a-next-js-or-react-prerelease).

package/docs/usage.md

@@ -387,7 +387,7 @@ A **predicate** declares what should be true. `reticle_assert` / `reticle_assert
 { "kind": "state", "store": "app", "path": "deployments.0.status", "equals": "live" }
 ```
 
-`visible` excludes elements whose boxes are fully clipped by an ancestor's `overflow:hidden` or `overflow:clip`; a partly clipped element stays visible. Expanding a clamped card can therefore prove that its previously hidden paragraph became visible. `overflow:auto` and `overflow:scroll` keep their existing visibility semantics, including content beyond the scrollport. Ordinary document content outside the window remains visible; `inViewport` checks the window intersection after any hidden/clip ancestor clipping, without introducing scrollport clipping.
+`visible` excludes elements whose boxes are fully clipped by an ancestor's `overflow:hidden` or `overflow:clip`; a partly clipped element stays visible. It also excludes screen-reader-only text: a positioned box with a `clip: rect()` of no area, a `clip-path: inset()` whose edges meet, or a 1×1 box that clips its own overflow. That text stays `present` and still names its control. Expanding a clamped card can therefore prove that its previously hidden paragraph became visible. `overflow:auto` and `overflow:scroll` keep their existing visibility semantics, including content beyond the scrollport. Ordinary document content outside the window remains visible; `inViewport` checks the window intersection after any hidden/clip ancestor clipping, without introducing scrollport clipping.
 
 A `state` assertion is graded as a **consequence** (a wrong element or stale render cannot fake it), and is usable the same three ways anywhere predicates flow: ad-hoc (`reticle_assert` / `reticle_act_and_wait` `until`), as a flow step invariant (`reticle_annotate { kind: "assert-state", statePath, store?, equals? }`), and as a flow's golden end-condition (`reticle_annotate { kind: "success-state", statePath, … }`). On a miss it names the real store value and the keys that were available: legible, not a blind fail.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/server",
-  "version": "3.8.0",
+  "version": "3.8.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",
@@ -22,13 +22,12 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.31.0",
     "ws": "^8.21.3",
-    "zod": "^3.24.1",
-    "zod-to-json-schema": "^3.24.0",
-    "@reticlehq/browser": "3.8.0",
-    "@reticlehq/init": "3.8.0",
-    "@reticlehq/core": "3.8.0",
-    "@reticlehq/engine": "3.8.0",
-    "open-verification": "1.0.0"
+    "zod": "^4.6.6",
+    "@reticlehq/engine": "3.8.1",
+    "@reticlehq/core": "3.8.1",
+    "@reticlehq/init": "3.8.1",
+    "open-verification": "1.0.0",
+    "@reticlehq/browser": "3.8.1"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",
@@ -65,7 +64,7 @@
     "cli"
   ],
   "reticle": {
-    "changelog": "Reticle works in git worktrees: each agent reaches only the tabs its own worktree serves, and each run names its branch. reticle init now installs a prompt hook for the agents it finds: each prompt is kept, redacted, in .reticle/, and a linked project sends it with its runs unless \"shareRequests\": false. Background sync sends a linked project while you are signed in, or with RETICLE_API_KEY in CI. See MIGRATION.md (3.7 to 3.8).",
+    "changelog": "On Windows, the daemon now keeps running when the agent process that started it ends. A collapsed Next.js \"1 Issue\" badge no longer turns every check into unknown. Reticle moves to zod 4 for a high-severity memory advisory. reticle_lease can omit url and lease the project's own dev server. reticle doctor checks that the daemon answers, and streamed SSE response bodies can be captured. Replay waits for a start page that is still loading, a re-acquired lease moves to the page asked for, and a guarded app driven by fast clicks is no longer accused of applying a stale response. Update the SDK in your app as well as the CLI.",
     "breakingChanges": []
   },
   "publishConfig": {