@reticlehq/server 2.10.0 → 2.12.0

package/SKILL.md

@@ -14,6 +14,18 @@ This file is the whole critical path and nothing else. Everything it leaves out
 
 **Do not tell the user Reticle is set up until step 5 has produced a verdict.** The most common failure in the field is an agent that finishes step 1, reports success, and leaves a user with config files and no instrumented page.
 
+## Setup runs to the end without you
+
+**Do not stop, and do not ask the user anything, until their app is running with Reticle inside it and a session is connected.** Everything between here and that point is yours to do: run `init`, fix the wiring it could not, start the dev server, open the browser. Not one of those needs a human, and every one of them has been the place an onboarding turn died with nothing to show.
+
+Questions you must not ask, because the repo you are sitting in already answers them: which framework, which package manager, which port, which editor or MCP client, whether to start the dev server, whether to open the browser, whether to carry on. Decide, act, and say what you did in one line.
+
+There are exactly three places you may stop, and none is a question about a preference:
+
+1. **No recognisable dev script in `package.json`.** Say so; do not invent one.
+2. **Your host asks the human to approve a command.** That prompt belongs to the host. Never bypass or suppress it, and take a refusal as the answer.
+3. **On a first install only, the client restart that loads the MCP tools** (step 2). Even then, keep going until the app is running and connected, and stop for the restart last, with only the drive left.
+
 Setup requires a client restart, which ends your turn. This file was fetched into the context that just ended, so nothing carries it across unless you make it. **Before you trigger the restart, write the remaining steps into `RETICLE-SETUP.md` at the repo root**, one line each, with the step you stopped at marked. That file is what you re-read afterwards. Delete it once step 5 has produced a verdict.
 
 Better still, install the on-disk copy first. It survives the restart on its own, and it is the same content:
@@ -80,25 +92,29 @@ RETICLE_INSTALL_SOURCE=skill_file npx @reticlehq/server@latest init
 
 It detects the framework, package manager and UI library, registers the MCP server with the agents on the machine, installs the SDK, writes `.reticle.json` and the `/reticle` command, wires the build config, and scaffolds a capabilities file from the `data-testid` values it found.
 
-**Ask nothing:** not the framework, package manager, port, editor, or MCP client. Every one is answerable from the repo you are sitting in. In a monorepo run it at the root anyway; it finds the app under `apps/*` or `packages/*`.
+**Ask nothing:** not the framework, package manager, port, editor, or MCP client. Every one is answerable from the repo you are sitting in. In a monorepo run it at the root anyway. With one app under `apps/*` or `packages/*` it wires that app silently. With several it wires nothing, lists them, and names the flag: re-run with `--app <dir>` for the one the user is working in, the one their request named, or the one whose `package.json` has the dev script. **Pick it yourself and re-run.** Asking which app they meant is the most likely place this whole install stops, and the answer is almost always in the request you were already given.
 
 **Never ask about the port.** There are two, and conflating them is a top setup failure. The dev-server port (3000, 5173) belongs to the project's own dev script and the daemon never binds it. The bridge port (**4400**) is the daemon-to-SDK channel and defaults correctly.
 
 Read the report: `✓` applied, `·` already wired, `–` skipped, `ℹ` done but incomplete in a way that matters, `⚠` needs your edit. **`⚠` and `ℹ` both need you.** `ℹ` is the one people skim past: the step ran, and something about the result still stops a session appearing. Each line carries the exact snippet. A non-zero exit is a to-do list, not a failed install. Fix every `⚠` before moving on. Per-framework wiring is at `https://docs.reticle.sh/install-manual.md`.
 
-## 2. Register the MCP server, then restart the client.
+**If the user gave you a license key**, along with the install request or at any later point, see [License key](#license-key) below and do it before moving on.
 
-Call `reticle_sessions`. If the tool exists, skip to step 3.
+## 2. Check for the tools. Do not stop for them.
 
-If it does not: your client read its server list at startup and has not re-read it. No retry loads it. `init` registers globally once per machine, so this bites on the first install only.
+Call `reticle_sessions`. If the tool exists, go to step 3 and never mention a restart.
 
-Say this once and then stop:
+If it does not: your client read its server list at startup and has not re-read it. No retry, config edit or slash command loads it into the process you are already in. `init` registers globally once per machine, so this bites on the first install only.
 
-> "Reticle is installed. Restart your client so it picks up the new MCP server, then say **'continue Reticle setup'**. Three steps are left, and your app is not instrumented until they are done."
+**This is not a reason to stop.** Steps 3 and 4 need no MCP tools at all: they are a build config, a dev server and a browser tab, and every one of them is yours to do from the shell. An install that halts here leaves the user with config files, an uninstrumented page, and a question to answer; that is the single most common failure in the field, and it is this paragraph's fault when it happens.
+
+So carry straight on through steps 3 and 4. Ask for the restart **once, at the end**, when a session is connected and the only thing left is the drive:
+
+> "Reticle is installed and your app is connected. Restart your client so it picks up the MCP server, then say **'continue Reticle setup'**. One step is left: driving a flow."
 
 Claude Code: restart (`/mcp` does not re-read the config). VS Code: press Start in `.vscode/mcp.json`. Cursor, Windsurf, Zed: reload the window.
 
-**Do not report setup as finished here.** When the tools return, resume at step 3.
+**Do not report setup as finished at that point either.** When the tools return, resume at step 5.
 
 ## 3. Wire the SDK into the app, and start the dev server.
 
@@ -132,7 +148,17 @@ Five guards, none optional:
 4. **Background it, and say so.** A dev server the human does not know about is the same failure one step later.
 5. **The permission prompt belongs to your host.** Never bypass, suppress or auto-approve it, and take a refusal as the answer.
 
-Then ask the user to open the app in their browser.
+Then open the app yourself. Do not ask the user to do it. A setup turn that ends on "now open your browser" ends with nothing verified:
+
+```bash
+npx @reticlehq/server open <the url the dev server is serving>
+```
+
+That reuses an already-connected tab or opens a new one, and waits for the page to register. On a headless machine with no browser to open, take a tab Reticle owns instead, once the tools are reachable:
+
+```
+reticle_run({ tool: "reticle_lease", args: { action: "acquire", url: "<the same url>" } })
+```
 
 ## 4. Prove a page is connected. This is a gate.
 
@@ -159,7 +185,7 @@ Drive it in as few calls as you can. Every call is a full model turn, and in a c
 3. `reticle_act_and_wait({ ref, action, until })` for the final step only. This is the call that produces the verdict, and `until` names the expected consequence before the action fires.
 4. `reticle_state()` once at the end.
 
-Four calls for a login, not fourteen. If `reticle_state` comes back empty or `hasCapabilities` is false, the generated capabilities file registered no store. Say so in one line and offer to finish it. Never report a clean install over an empty state read.
+Four calls for a login, not fourteen. If `reticle_state` comes back empty or `hasCapabilities` is false, the capabilities file `init` generated registered nothing, which is what its `ℹ AGENT: finish the capabilities file` line was telling you. **Finish it yourself, before you drive**: open `src/reticle-dev.*`, register the app's store if it has one, and list the `testids` the flow you picked actually touches. Do not offer, and do not ask; it is a few lines in a file `init` already wrote for you. Never report a clean install over an empty state read.
 
 **Then save what you just drove.** Two calls, and they are what make every future check a single call instead of a repeat of this one. Wrap the drive above in a recording:
 
@@ -190,6 +216,18 @@ Stop here. Do not continue into VERIFY.
 
 ---
 
+# License key
+
+Enterprise features are unlocked by a signed key, verified locally with Ed25519 and **no network call**. If the user hands you one, during setup or at any later point:
+
+1. Append `RETICLE_LICENSE_KEY=<key>` to the project's `.env`, creating the file if it is not there. The CLI folds a project-local `.env` into the environment on every invocation, so nothing else has to change.
+2. Make sure `.env` is in `.gitignore`. A license key in git is a leaked credential, so check before you write and add the line if it is missing.
+3. Confirm with `npx @reticlehq/server license`, which prints `active`, `eval`, `missing` or `expired`.
+
+Never echo the key back in your reply, and never put it in a commit, a code comment, or a feedback report. The rest: `curl https://docs.reticle.sh/enterprise.md`.
+
+---
+
 # VERIFY
 
 **Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** Everything else (`act`, `snapshot`, `query`, `navigate`, `observe`, `network`, `console`) moves or reads the app and proves nothing. A drive that ends without one of those two has no result, however many tools it used.
@@ -211,6 +249,30 @@ Work down this list and stop at the first row that fits. Do not hand-drive a flo
 
 `reticle_verify {action:"change"}` answers `unknown` when no saved flow covers the files you changed. That is the honest answer and not a failure. Nothing ran, so nothing was proved. It is also the signal to record one. Never read it as a pass.
 
+## Two more you have to be told about
+
+Same story as `reticle_verify`: extended surface, so they are not in the tool list you were handed, and reached through `reticle_run`.
+
+**Context compacted, a turn starting, or a sub-agent taking over?** Ask what this run already established, instead of re-snapshotting to rediscover what you already knew:
+
+```
+reticle_run({ tool: "reticle_context", args: {} })
+```
+
+**About to change something?** Declare what the change is SUPPOSED to make true, in prose, while you still know. A verdict with nothing declared can only be checked against itself:
+
+```
+reticle_run({ tool: "reticle_intent", args: { action: "declare", intents: [{ id: "checkin", statement: "clicking Send check-in makes the badge read 'checked in'" }] } })
+```
+
+Or say it on the verdict itself and skip the round trip. `reticle_act_and_wait` and `reticle_assert` both take an optional `intent`, writing the same ledger:
+
+```
+reticle_act_and_wait({ ref: "e42", action: "click", until: { kind: "signal", name: "checkin:sent" }, intent: "clicking Send check-in makes the badge read 'checked in'" })
+```
+
+The verdict that passes is the one that proves it. Already declared it? Pass the intent's **id** there instead of the prose, and several verdicts can answer to one statement.
+
 ## Record once, replay cheaply
 
 The first drive of a journey is expensive. The rest should not be. After you drive something worth keeping:
@@ -232,7 +294,7 @@ Five calls, and the last one is the only one that counts:
 
 ```
 reticle_sessions()                                   // connected? if empty, read `why` — it names the fix
-reticle_capabilities({ sessionId })                  // the app's whole testable surface, ~1 KB
+reticle_run({ tool: "reticle_capabilities", args: { sessionId } })  // the app's whole testable surface, ~1 KB
 reticle_snapshot({ sessionId, mode: "interactive" }) // just the controls, with refs
 reticle_act_and_wait({ sessionId, ref, action: "click", until: { kind: "allOf", predicates: [
   { kind: "net",     urlContains: "/api/...", status: 200 },
@@ -247,7 +309,7 @@ A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app
 
 Then report what you drove, what it produced, and the `file:line` for anything broken.
 
-The surface is deliberately small: `default` 18, `all` 28. Editors budget tools across every MCP server you have connected (Cursor allows 40 in total), so the count is capped rather than allowed to grow. `reticle_tools` loads the argument grammar for the rest on demand, and `reticle_run` invokes any of them by name. Nothing is unreachable; the cold tail just costs one discovery hop.
+The surface is deliberately small: `default` 18, `all` 30. Editors budget tools across every MCP server you have connected (Cursor allows 40 in total), so the count is capped rather than allowed to grow. `reticle_tools` loads the argument grammar for the rest on demand, and `reticle_run` invokes any of them by name. Nothing is unreachable; the cold tail just costs one discovery hop.
 
 - Batching, regression suites, reading a verdict: `https://docs.reticle.sh/agent-cheatsheet.md`
 - Every predicate and action: `https://docs.reticle.sh/predicates.md`, `https://docs.reticle.sh/actions.md`

package/dist/bridge/bridge.d.ts

@@ -26,19 +26,6 @@ export declare const WS_CLOSE_REASON: {
      */
     readonly HANDSHAKE_POOL_FULL: string;
 };
-/**
- * A dial turned away at the ORIGIN gate, in words the reader can act on.
- *
- * This is the refusal that used to leave no trace anywhere. It happens before any HELLO, so it
- * produced no `noteClosure`, no `session_disconnected`, nothing but an `origin_rejected` log line —
- * and the daemon log is the file nobody opens until they have already lost the afternoon. Reported
- * from a multi-tenant app resolving its tenant from the `Host` header: on a hosts-file alias every
- * dial was refused here, `doctor` reported every check green, and the lease hint blamed the port.
- *
- * The origin is IN the message because it is the fix: it is either the alias to allow-list, or the
- * proof that the page is not being served from where the developer thinks it is.
- */
-export declare function originRejectedReason(origin: string | undefined): string;
 interface BridgeOptions {
     port: number;
     host?: string;

package/dist/bridge/bridge.js

@@ -65,7 +65,7 @@ export const WS_CLOSE_REASON = {
  * The origin is IN the message because it is the fix: it is either the alias to allow-list, or the
  * proof that the page is not being served from where the developer thinks it is.
  */
-export function originRejectedReason(origin) {
+function originRejectedReason(origin) {
     const named = origin === undefined || 0 === origin.length ? 'a page sending no Origin' : origin;
     return (`a browser dialled this daemon and was REFUSED at the origin gate: ${named} is not allowed. ` +
         'Off localhost the SDK needs BOTH `allowNonLocalhost: true` AND a pairing token, and the ' +

package/dist/bridge/bridge.test-harness.d.ts

@@ -16,6 +16,8 @@ export declare class FakeBrowser {
         file: string;
         line: number;
     } | undefined;
+    /** DOM mutations the browser counted inside the acted element; undefined = it counted none. */
+    actMutatedWithin: number | undefined;
     /** when false, ACT reports settled:false + settleReason:'timeout' (throttled-tab path). */
     actSettled: boolean;
     /** When false, QUERY by testid returns no match (testid not in current DOM at replay). */

package/dist/bridge/bridge.test-harness.js

@@ -26,6 +26,8 @@ export class FakeBrowser {
     actHasTestid = true;
     /** Provenance the real browser captures alongside the anchor; undefined = app built without it. */
     actSource = undefined;
+    /** DOM mutations the browser counted inside the acted element; undefined = it counted none. */
+    actMutatedWithin = undefined;
     /** when false, ACT reports settled:false + settleReason:'timeout' (throttled-tab path). */
     actSettled = true;
     /** When false, QUERY by testid returns no match (testid not in current DOM at replay). */
@@ -101,7 +103,12 @@ export class FakeBrowser {
                 dispatched: true,
                 settled: this.actSettled,
                 settleReason: this.actSettled ? null : 'timeout',
-                effect: { dispatched: true },
+                effect: {
+                    dispatched: true,
+                    ...(this.actMutatedWithin === undefined
+                        ? {}
+                        : { domMutatedWithin: this.actMutatedWithin }),
+                },
                 ...(this.actHasTestid ? { testid: 'pay-btn' } : {}),
                 ...(this.actSource === undefined ? {} : { source: this.actSource }),
             };

package/dist/capsule/capsule-store.d.ts

@@ -16,7 +16,7 @@ import type { FileSystemPort } from '../project/fs-port.js';
  * in the schema literal, and in act-capsule's writer — with the named one used by nobody.
  */
 export declare const CAPSULE_VERSION = 1;
-export declare const CapsuleSchema: z.ZodObject<{
+declare const CapsuleSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     id: z.ZodString;
     /** The flow the failure happened in, when it came from one (a bare assert has no flow). */
@@ -68,3 +68,4 @@ export declare class CapsuleStore {
 export declare function capsuleId(now: number, label: string): string;
 /** The minimal reproduction: the steps up to and including the one that failed (prefix trim). */
 export declare function minimalSteps(steps: readonly FlowStep[], failedIndex: number): FlowStep[];
+export {};

package/dist/capsule/capsule-store.js

@@ -17,7 +17,7 @@ import { reticleDirPaths } from '../project/reticle-dir.js';
  * in the schema literal, and in act-capsule's writer — with the named one used by nobody.
  */
 export const CAPSULE_VERSION = 1;
-export const CapsuleSchema = z.object({
+const CapsuleSchema = z.object({
     version: z.literal(CAPSULE_VERSION),
     id: z.string(),
     /** The flow the failure happened in, when it came from one (a bare assert has no flow). */

package/dist/capsule/causal-summary.d.ts

@@ -4,7 +4,7 @@ import { type ReticleEvent } from '@reticlehq/core';
  * app did in the act's window, as counts + a headline, not a raw event dump. Diffs come from the
  * storage/state events; attribution from. Pure composition over the attributed event window.
  */
-export interface StateDiff {
+interface StateDiff {
     path: string;
     from: unknown;
     to: unknown;
@@ -20,7 +20,7 @@ export interface StateDiff {
      */
     atMs: number;
 }
-export interface StorageDiff {
+interface StorageDiff {
     key: string;
     from?: unknown;
     to?: unknown;

package/dist/chromium-launch-options.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The launch options every Reticle-driven Chromium gets, in one place.
+ *
+ * A pooled browser serves several lease contexts while only one page is ever the visible one, and a
+ * driven page can sit in a window the host does not treat as visible. For everyone else Chromium
+ * throttles timers, suspends rAF, and deprioritizes the renderer, which is exactly the state a
+ * session reports as `throttled: true`: WebSocket- and timer-driven DOM updates land seconds late,
+ * asserts time out on content that appears right after the timeout, with no refetch, because the
+ * app was fine and the browser was parked. The three switches below are the documented opt-outs,
+ * shared by both launch sites so the pooled path (`playwright-launcher`) and the drive path
+ * (`real-input`) cannot drift apart.
+ */
+/**
+ * Chromium switches that keep background pages running at full speed. Named individually rather
+ * than as one free string per call site, so a typo is a test failure instead of a silently ignored
+ * argument.
+ */
+export declare const CHROMIUM_ANTI_THROTTLING_ARGS: readonly ["--disable-background-timer-throttling", "--disable-backgrounding-occluded-windows", "--disable-renderer-backgrounding"];
+/** The options object handed to `chromium.launch` at both launch sites. */
+export interface ChromiumLaunchOptions {
+    headless: boolean;
+    args: string[];
+}
+/**
+ * Build the launch options for a headless or headed Chromium. Pure; returns a fresh mutable array
+ * each call so no caller can mutate the constant behind everyone else's back.
+ */
+export declare function chromiumLaunchOptions(headless: boolean): ChromiumLaunchOptions;

package/dist/chromium-launch-options.js

@@ -0,0 +1,29 @@
+/**
+ * The launch options every Reticle-driven Chromium gets, in one place.
+ *
+ * A pooled browser serves several lease contexts while only one page is ever the visible one, and a
+ * driven page can sit in a window the host does not treat as visible. For everyone else Chromium
+ * throttles timers, suspends rAF, and deprioritizes the renderer, which is exactly the state a
+ * session reports as `throttled: true`: WebSocket- and timer-driven DOM updates land seconds late,
+ * asserts time out on content that appears right after the timeout, with no refetch, because the
+ * app was fine and the browser was parked. The three switches below are the documented opt-outs,
+ * shared by both launch sites so the pooled path (`playwright-launcher`) and the drive path
+ * (`real-input`) cannot drift apart.
+ */
+/**
+ * Chromium switches that keep background pages running at full speed. Named individually rather
+ * than as one free string per call site, so a typo is a test failure instead of a silently ignored
+ * argument.
+ */
+export const CHROMIUM_ANTI_THROTTLING_ARGS = [
+    '--disable-background-timer-throttling',
+    '--disable-backgrounding-occluded-windows',
+    '--disable-renderer-backgrounding',
+];
+/**
+ * Build the launch options for a headless or headed Chromium. Pure; returns a fresh mutable array
+ * each call so no caller can mutate the constant behind everyone else's back.
+ */
+export function chromiumLaunchOptions(headless) {
+    return { headless, args: [...CHROMIUM_ANTI_THROTTLING_ARGS] };
+}

package/dist/cli/cli-doctor.js

@@ -17,6 +17,7 @@ import { diagnoseDesktop, isDesktopProject } from '../init/desktop-doctor.js';
 import { diagnoseWebCsp } from '../init/csp-doctor.js';
 import { RETICLE_CONFIG_BASENAME, diagnosePortMismatch, readProjectId, readProjectPort, } from './cli-port.js';
 import { DoctorRow, doctorRow } from './doctor-rows.js';
+import { findOccupiedSiblings, siblingListenerNote } from './sibling-ports.js';
 /**
  * `reticle doctor` — collapse the ~6 independent first-run failure modes into one command. Checks the
  * Chromium install (the #1 silent failure), whether a daemon is up on the resolved bridge port, and
@@ -91,6 +92,13 @@ export async function handleDoctor(port) {
     const mismatch = diagnosePortMismatch(port, projectPort);
     if (mismatch !== undefined)
         line(doctorRow(DoctorRow.PORT_CHECK, `✗ ${mismatch}`));
+    // Remaining half of #261. The SDK dialling a port we are not on is invisible as a refused inbound,
+    // but a listener on a well-known Reticle port is visible. Report the observation; do not conclude
+    // it is the daemon this app wants — somebody else's daemon looks the same from here.
+    const occupiedSiblings = await findOccupiedSiblings(port, probeDaemon);
+    const siblingNote = siblingListenerNote(port, occupiedSiblings);
+    if (siblingNote !== undefined)
+        line(doctorRow(DoctorRow.SIBLING, siblingNote));
     // The check this checklist was missing: is the APP wired, not just the tools. Everything above can
     // be green in a project that has never been through `init`, and that combination is precisely the
     // one `doctor` gets run to explain.

package/dist/cli/cli-flow-commands.d.ts

@@ -27,4 +27,6 @@ export declare function handleCapsules(): Promise<void>;
  * changed files. Flaky flows are quarantined (surfaced, not blocking). The environment-side enforcement
  * that makes verification unavoidable. Never throws; a fault fails closed (exit 1).
  */
-export declare function handleGate(files: string[], since: string | undefined): Promise<void>;
+export declare function handleGate(files: string[], since: string | undefined, 
+/** Hook mode: prose for a human, and silence when there was simply nothing to check. */
+hook?: boolean): Promise<void>;

package/dist/cli/cli-flow-commands.js

@@ -5,6 +5,8 @@
  * opens first. These five functions form one cohesive group: they all read the flow store and report on
  * verification state, and none of them touch daemon lifecycle, which is what the rest of cli.ts does.
  */
+import { GateExit } from './gate-exit.js';
+import { gateHookMessage, GATE_SKIP_ENV } from './gate-hook-message.js';
 import { readProjectId } from './cli-port.js';
 import { changedFilesSince } from '../flows/git-changed.js';
 import { join } from 'node:path';
@@ -143,7 +145,9 @@ export async function handleCapsules() {
  * changed files. Flaky flows are quarantined (surfaced, not blocking). The environment-side enforcement
  * that makes verification unavoidable. Never throws; a fault fails closed (exit 1).
  */
-export async function handleGate(files, since) {
+export async function handleGate(files, since, 
+/** Hook mode: prose for a human, and silence when there was simply nothing to check. */
+hook = false) {
     try {
         const fs = createNodeFileSystem();
         const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
@@ -196,11 +200,37 @@ export async function handleGate(files, since) {
             ...(result.deleted.length > 0 ? { deletedCoverage: result.deleted } : {}),
             coverage: flowCoverage,
         });
-        if (!pass)
-            process.exitCode = 1;
+        // Two non-zero codes, because two callers want opposite things from the same run. CI wants any
+        // problem to fail. A Stop hook wants to block a real regression and NOT block a project that
+        // has simply not recorded a flow yet — which is every project on its first day, and measured
+        // before this change as an exit 1 that would have blocked every stop. See GateExit.
+        if (!pass) {
+            const code = result.pass && flowCoverage.outcome !== undefined
+                ? GateExit.NOTHING_TO_CHECK
+                : GateExit.FAIL;
+            process.exitCode = code;
+            if (hook) {
+                // An honest escape hatch, because the alternative to one is not compliance — it is somebody
+                // deleting the hook, and a deleted gate protects nothing. Recorded either way.
+                if (process.env[GATE_SKIP_ENV] !== undefined) {
+                    process.stderr.write(`Reticle: gate skipped via ${GATE_SKIP_ENV}. This change is unverified.\n`);
+                    process.exitCode = GateExit.PASS;
+                    return;
+                }
+                const message = gateHookMessage(code, {
+                    uncovered: result.uncovered,
+                    quarantined: result.quarantined,
+                    // A downgrade is reported per flow with its step indices; the hook names the flow.
+                    downgraded: result.downgraded.map((d) => d.flow),
+                    deleted: result.deleted,
+                });
+                if (message !== undefined)
+                    process.stderr.write(`${message}\n`);
+            }
+        }
     }
     catch (error) {
         log('reticle_gate_failed', { error: error instanceof Error ? error.message : String(error) });
-        process.exitCode = 1;
+        process.exitCode = GateExit.FAIL;
     }
 }

package/dist/cli/cli-kill.d.ts

@@ -25,7 +25,7 @@ export declare const KillAction: {
     readonly REFUSE: "refuse";
 };
 export type KillAction = (typeof KillAction)[keyof typeof KillAction];
-export interface KillPlan {
+interface KillPlan {
     action: KillAction;
     /** The single pid to signal. Present only for `kill`. */
     pid?: number;
@@ -56,3 +56,4 @@ export declare function planKill(input: {
 }): KillPlan;
 /** `reticle kill` — free the port. Resolves to whether the port is now free. */
 export declare function runKill(port: number, force: boolean): Promise<boolean>;
+export {};

package/dist/cli/cli-parse.d.ts

@@ -13,7 +13,7 @@ export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from '.
  * telling readers to do exactly that on 110 lines before it was caught, so the invocation now leads
  * the usage block rather than being a footnote somewhere else.
  */
-export declare const CLI_USAGE = "usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)\n\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)\n                --app picks WHICH app in a monorepo, when several are found\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)\n  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)\n  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)\n  reticle status [--port N]\n  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode, for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't; prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle Cloud; runs/flows recorded on the dashboard):\n  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push                                          (send local run artifacts to the dashboard)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
+export declare const CLI_USAGE = "usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)\n\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)\n                --app picks WHICH app in a monorepo, when several are found\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)\n  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)\n  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)\n  reticle status [--port N]\n  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode, for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't; prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle Cloud; runs/flows recorded on the dashboard):\n  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push                                          (send local run artifacts to the dashboard)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export declare const TelemetryAction: {
     readonly STATUS: "status";
@@ -111,6 +111,7 @@ export type CliResult = {
     kind: 'verify';
     url: string;
     headless: boolean;
+    port: number;
     timeoutMs?: number;
     storageState?: string;
 } | {
@@ -126,6 +127,7 @@ export type CliResult = {
     kind: 'gate';
     files: string[];
     since?: string;
+    hook?: boolean;
 } | {
     kind: 'watch';
     url?: string;

package/dist/cli/cli-parse.js

@@ -29,7 +29,7 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
   reticle status [--port N]
   reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)
   reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)
-  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)
+  reticle verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)
   reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)
   reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)
   reticle watch [url]                                  (on save, report which saved flows must re-verify)
@@ -69,6 +69,8 @@ const AFFECTED_COMMAND = 'affected';
 const HUNT_COMMAND = 'hunt';
 const CAPSULES_COMMAND = 'capsules';
 const GATE_COMMAND = 'gate';
+/** Hook mode: prose a human can read, and silence when there was simply nothing to check. */
+const HOOK_FLAG = '--hook';
 const WATCH_COMMAND = 'watch';
 const UPDATE_COMMAND = 'update';
 const ROLLBACK_COMMAND = 'rollback';
@@ -288,14 +290,15 @@ function parseDriveSuffix(args, port, defaultHeadless) {
     return { kind: 'ok', port, driveUrl, headless };
 }
 /**
- * Parse `verify <url> [--headed] [--timeout N] [--storage-state <file>]`. The first non-flag token is
- * the preview URL.
+ * Parse `verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>]`. The first
+ * non-flag token is the preview URL. `defaultPort` is already env + `.reticle.json` + 4400.
  */
-function parseVerifySuffix(args) {
+function parseVerifySuffix(args, defaultPort) {
     let headless = true;
     let url;
     let timeoutMs;
     let storageState;
+    let port = defaultPort;
     let i = 0;
     while (i < args.length) {
         const arg = args[i];
@@ -304,6 +307,16 @@ function parseVerifySuffix(args) {
         if (arg === HEADED_FLAG) {
             headless = false;
         }
+        else if (arg === PORT_FLAG) {
+            i++;
+            const n = args[i];
+            if (n === undefined)
+                return missingValue(PORT_FLAG);
+            const parsed = parseInt(n, 10);
+            if (isNaN(parsed))
+                return notANumber(PORT_FLAG, n);
+            port = parsed;
+        }
         else if (arg === TIMEOUT_FLAG) {
             i++;
             const n = args[i];
@@ -338,6 +351,7 @@ function parseVerifySuffix(args) {
         kind: 'ok',
         url,
         headless,
+        port,
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
         ...(storageState !== undefined ? { storageState } : {}),
     };
@@ -550,13 +564,14 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             };
         }
         case VERIFY_COMMAND: {
-            const r = parseVerifySuffix(rest);
+            const r = parseVerifySuffix(rest, defaultPort);
             if ('error' === r.kind)
                 return r;
             return {
                 kind: 'verify',
                 url: r.url,
                 headless: r.headless,
+                port: r.port,
                 ...(r.timeoutMs !== undefined ? { timeoutMs: r.timeoutMs } : {}),
                 ...(r.storageState !== undefined ? { storageState: r.storageState } : {}),
             };
@@ -575,9 +590,16 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             return { kind: 'affected', files: t.files, ...(since === undefined ? {} : { since }) };
         }
         case GATE_COMMAND: {
-            const t = parseTargetArgs(rest);
+            // `--hook` is stripped before target parsing, which would reject it as an unknown flag.
+            const hook = rest.includes(HOOK_FLAG);
+            const t = parseTargetArgs(rest.filter((a) => a !== HOOK_FLAG));
             const since = t.since ?? implicitSince(t.files);
-            return { kind: 'gate', files: t.files, ...(since === undefined ? {} : { since }) };
+            return {
+                kind: 'gate',
+                files: t.files,
+                ...(since === undefined ? {} : { since }),
+                ...(hook ? { hook: true } : {}),
+            };
         }
         case WATCH_COMMAND: {
             // `reticle watch [url]` — on file save, report which saved flows must re-verify.

package/dist/cli/cli-update-commands.js

@@ -8,9 +8,10 @@
 import { checkForUpdate } from '../update/update-checker.js';
 import { updateTarget } from '../update/update-nudge.js';
 import { applyUpdate, rollback } from '../update/updater.js';
+import { refreshAgentRules } from '../init/refresh-rules.js';
 import { SERVER_VERSION } from '../version/server-version.js';
 import { log } from '../log.js';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { reticleDepsOf, sdkSyncCommand } from '../update/sdk-sync.js';
 import { detectPackageManager } from '../init/detect.js';
@@ -64,6 +65,24 @@ export async function handleUpdate() {
             return;
         }
         log('reticle_update', { ok: true, from: SERVER_VERSION, to: target });
+        // Bring this project's agent rules up with the version.
+        //
+        // The managed block has always been updatable — marker-delimited, idempotent by comparing
+        // content — and nothing called it after the first install. `mergeMarkedInstruction` is reachable
+        // from `buildPlan` alone, so a project set up on an older release kept that release's
+        // instructions forever and every improvement to them reached new projects only.
+        //
+        // That is backwards: the people who most need better instructions are the ones already
+        // installed and not getting value, and this is the moment they are touching the install anyway.
+        // Only files that ALREADY carry the block are touched, and only inside the markers.
+        const refreshed = refreshAgentRules(process.cwd(), {
+            read: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null),
+            write: (path, content) => {
+                writeFileSync(path, content, 'utf8');
+            },
+        });
+        if (0 !== refreshed.updated.length)
+            log('reticle_rules_refreshed', { files: refreshed.updated, to: target });
         // The app's SDK FIRST, then the CLI. `reticle update` used to swap only the CLI, so the command
         // whose job is keeping an install current was itself a way to produce a version-skewed pair —
         // and the skew message told people to run it to fix an outdated SDK, which it could not do.

package/dist/cli/cli-verify.d.ts

@@ -63,6 +63,6 @@ export declare function handleVerify(parsed: {
     timeoutMs?: number;
     storageState?: string;
     /** Bridge port — parseCliArgs already resolves --port / RETICLE_PORT / .reticle.json into this. */
-    port?: number;
+    port: number;
 }): void;
 export {};

package/dist/cli/cli-verify.js

@@ -16,7 +16,7 @@ import { start } from '../index.js';
 import { probePresence, PortPresence } from '../daemon/port-presence.js';
 import { probeDaemon } from '../mcp/mcp-proxy.js';
 import { fetchStatus } from './cli-launch.js';
-import { resolveCloudConfig, syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { cloudFetch, resolveCloudConfig, syncRunToCloud, SyncOutcome, } from '../cloud/cloud-sync.js';
 import { ReticleRunner } from '../runs/reticle-runner.js';
 import { createRunnerPort } from '../runs/runner-port.js';
 import { RunStore } from '../runs/run-store.js';
@@ -94,7 +94,7 @@ async function pushRunToCloud(run, ports) {
     const config = resolveCloudConfig(process.env);
     if (null === config)
         return;
-    const result = await syncRunToCloud(run, config, (url, init) => fetch(url, init));
+    const result = await syncRunToCloud(run, config, cloudFetch);
     if (result.outcome === SyncOutcome.SYNCED) {
         ports.out(`↑ run ${run.runId} recorded on the Reticle Cloud dashboard`);
     }