@reticlehq/server 2.11.0 → 2.12.0

package/SKILL.md

@@ -249,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:
@@ -270,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 },
@@ -285,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`);
     }

package/dist/cli/cloud-cli.js

@@ -16,7 +16,7 @@ import { z } from 'zod';
 import { createNodeFileSystem } from '../project/fs-port.js';
 import { RunStore } from '../runs/run-store.js';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
-import { syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { cloudFetch, syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 const DEFAULT_URL = 'http://localhost:8890';
 const RETICLE_DIR = '.reticle';
 const SESSION_FILE = 'session.json';
@@ -77,9 +77,15 @@ const readSession = async () => {
 };
 const baseUrl = (session) => {
     const env = process.env['RETICLE_CLOUD_URL'];
-    return env !== undefined && env.length > 0
-        ? env.replace(/\/+$/, '')
-        : (session?.url ?? DEFAULT_URL);
+    if (env !== undefined && env.length > 0)
+        return env.replace(/\/+$/, '');
+    if (null !== session && session.url.length > 0)
+        return session.url;
+    // Falling back to the local dev default WITHOUT being told to: say so on stderr, so a fresh
+    // `reticle login` never silently dials localhost. Humans read the hint; agents parse stdout
+    // JSON and ignore stderr, so stdout stays machine-readable either way.
+    hint(`no RETICLE_CLOUD_URL set — dialling the local dev default ${DEFAULT_URL} (set it for a real deployment)`);
+    return DEFAULT_URL;
 };
 /** Bearer for a command: an explicit api key (agent) wins, else the human login token. */
 const bearer = (session) => {
@@ -101,7 +107,7 @@ const api = async (method, url, token, body) => {
     };
     if (body !== undefined)
         init.body = JSON.stringify(body);
-    const res = await fetch(url, init);
+    const res = await cloudFetch(url, init);
     const text = await res.text();
     let json = null;
     if (text.length > 0) {
@@ -438,7 +444,7 @@ const cmdPush = async () => {
         const read = await store.read(id);
         if (!read.ok)
             continue;
-        const res = await syncRunToCloud(read.run, cloud.config, (u, init) => fetch(u, init));
+        const res = await syncRunToCloud(read.run, cloud.config, cloudFetch);
         if (res.outcome === SyncOutcome.SYNCED)
             pushed += 1;
         else if (res.outcome === SyncOutcome.FAILED)

package/dist/cli/config-discovery.d.ts

@@ -19,7 +19,7 @@
  * silently is how an agent ends up with a confident verdict about an app it never touched. Callers
  * are handed the list and must name it.
  */
-export interface FoundConfig {
+interface FoundConfig {
     /** Absolute path to the `.reticle.json`. */
     path: string;
     /** The directory it configures — what a reader needs in order to act. */
@@ -33,3 +33,4 @@ export interface ConfigDiscovery {
     searched: string[];
 }
 export declare function discoverProjectConfigs(cwd: string): ConfigDiscovery;
+export {};

package/dist/cli/doctor-rows.d.ts

@@ -18,7 +18,8 @@
  * row added and never documented.
  *
  * NOT every row prints on every run. `version` prints only on skew, `port check` only on a
- * mismatch, `desktop` only on a desktop project, and `sessions` only when a daemon answered. The
+ * mismatch, `sibling` only when a well-known Reticle port other than ours has a listener,
+ * `desktop` only on a desktop project, and `sessions` only when a daemon answered. The
  * vocabulary is therefore "what this command can print", not "what one run printed" — a guard built
  * by scraping a single invocation would silently stop covering the conditional rows, which are
  * exactly the ones a reader is least likely to have seen before.
@@ -32,6 +33,7 @@ export declare const DoctorRow: {
     readonly SESSIONS: "sessions";
     readonly BRIDGE_PORT: "bridge port";
     readonly PORT_CHECK: "port check";
+    readonly SIBLING: "sibling";
     readonly DAEMON_LOG: "daemon log";
     readonly TRACING: "tracing";
     readonly DESKTOP: "desktop";

package/dist/cli/doctor-rows.js

@@ -18,7 +18,8 @@
  * row added and never documented.
  *
  * NOT every row prints on every run. `version` prints only on skew, `port check` only on a
- * mismatch, `desktop` only on a desktop project, and `sessions` only when a daemon answered. The
+ * mismatch, `sibling` only when a well-known Reticle port other than ours has a listener,
+ * `desktop` only on a desktop project, and `sessions` only when a daemon answered. The
  * vocabulary is therefore "what this command can print", not "what one run printed" — a guard built
  * by scraping a single invocation would silently stop covering the conditional rows, which are
  * exactly the ones a reader is least likely to have seen before.
@@ -32,6 +33,7 @@ export const DoctorRow = {
     SESSIONS: 'sessions',
     BRIDGE_PORT: 'bridge port',
     PORT_CHECK: 'port check',
+    SIBLING: 'sibling',
     DAEMON_LOG: 'daemon log',
     TRACING: 'tracing',
     DESKTOP: 'desktop',