@reticlehq/server 3.4.0 → 3.5.0

package/dist/memory/project/artifact-root-resolver.js

@@ -34,30 +34,57 @@ function daemonSitsInAProject(daemonRoot) {
         return false;
     }
 }
+/**
+ * Every project this machine knows the directory of: discovered `.reticle.json` files first, then
+ * the user-level registry. Read on each call, since `init` can run in another terminal while the
+ * daemon is up.
+ */
+function knownProjectCandidates() {
+    let registry = emptyProjectRegistry();
+    try {
+        const path = join(homedir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
+        registry = existsSync(path)
+            ? parseProjectRegistry(JSON.parse(readFileSync(path, 'utf8')))
+            : registry;
+    }
+    catch {
+        // A cache that cannot be read is an empty cache, never an error: the daemon still resolves
+        // through discovery, and falls back to its own root exactly as it did before this existed.
+    }
+    let discovery = { found: [], searched: [] };
+    try {
+        discovery = discoverProjectConfigs(process.cwd());
+    }
+    catch {
+        // Same reasoning: a diagnostic search that throws must not take a tool call with it.
+    }
+    return projectCandidatesFrom(discovery, registry);
+}
+/**
+ * The directory of the project a page announced, or undefined when this machine does not know it.
+ *
+ * A daemon is shared: started from `$HOME`, a monorepo root, or another project's MCP client, its
+ * cwd is often not the app that sent the HELLO. The version-skew remedy read `package.json` from
+ * cwd anyway, so it fell back to the generic sensor package and told a Next.js project to install
+ * `@reticlehq/browser` (#1135). This is the same lookup the artifact root uses, keyed by the page's
+ * own project id.
+ */
+export function projectDirectoryFor(projectId) {
+    if (projectId === undefined)
+        return undefined;
+    const directories = new Set(knownProjectCandidates()
+        .filter((candidate) => candidate.projectId === projectId)
+        .map((candidate) => candidate.directory));
+    // Two checkouts declaring one id are refused, as the artifact root refuses them: naming one of
+    // them would read the wrong app's package.json and prescribe its packages to the other.
+    return 1 === directories.size ? [...directories][0] : undefined;
+}
 export function artifactRootResolver(daemonRoot) {
     const daemonIsProject = daemonSitsInAProject(daemonRoot);
     return (projectId, origin) => {
-        let registry = emptyProjectRegistry();
-        try {
-            const path = join(homedir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
-            registry = existsSync(path)
-                ? parseProjectRegistry(JSON.parse(readFileSync(path, 'utf8')))
-                : registry;
-        }
-        catch {
-            // A cache that cannot be read is an empty cache, never an error: the daemon still resolves
-            // through discovery, and falls back to its own root exactly as it did before this existed.
-        }
-        let discovery = { found: [], searched: [] };
-        try {
-            discovery = discoverProjectConfigs(process.cwd());
-        }
-        catch {
-            // Same reasoning: a diagnostic search that throws must not take a tool call with it.
-        }
         const resolved = resolveArtifactRoot({
             projectId,
-            candidates: projectCandidatesFrom(discovery, registry),
+            candidates: knownProjectCandidates(),
             daemonRoot,
         });
         if (resolved.reason === ArtifactRootReason.MATCHED_PROJECT)

package/dist/portal/bridge/bridge.d.ts

@@ -66,10 +66,11 @@ interface BridgeOptions {
      */
     server?: http.Server;
     /**
-     * The SDK-upgrade sentence to attach when a HELLO is skewed. Injected so the daemon can name
-     * this project's packages and package manager; tests that omit it get the no-project fallback.
+     * The SDK-upgrade sentence to attach when a HELLO is skewed, for the project that HELLO named.
+     * Injected so the daemon can name that project's packages and package manager; tests that omit
+     * it get the no-project fallback.
      */
-    sdkFix?: () => string;
+    sdkFix?: (projectId?: string) => string;
 }
 /**
  * The browser-facing half of the relay: a localhost WebSocket server. Each connection

package/dist/portal/bridge/bridge.js

@@ -608,6 +608,9 @@ export class Bridge {
                     // The daemon is the single judge of skew, and HELLO is where the page announces itself.
                     // Reported on the session (reticle_sessions) AND queued for the next tool result, because an
                     // agent driving a flow never calls reticle_sessions and would never learn.
+                    // Read only if the page IS skewed: the fix reads the project's package.json and lockfile,
+                    // and a compatible page (nearly every HELLO) should not pay for that on connect.
+                    const fixForThisProject = () => this.#sdkFix(parsed.projectId);
                     const skew = describeSkew({
                         what: 'the page',
                         version: parsed.sdkVersion,
@@ -618,7 +621,9 @@ export class Bridge {
                         ...(parsed.contractParts === undefined
                             ? {}
                             : { contractParts: parsed.contractParts }),
-                        fix: this.#sdkFix(),
+                        get fix() {
+                            return fixForThisProject();
+                        },
                     }, {
                         version: SERVER_VERSION,
                         contract: CONTRACT_FINGERPRINT,

package/dist/portal/input/viewport-tools.js

@@ -34,8 +34,8 @@ export const VIEWPORT_TOOLS = [
             recommendation: z.string().optional(),
         },
         handler: async (deps, args) => {
-            const width = clampDim(args['width']);
-            const height = clampDim(args['height']);
+            const width = clampDim('width', args['width']);
+            const height = clampDim('height', args['height']);
             const session = deps.sessions.resolve(asString(args['sessionId']));
             const provider = viewportProvider(deps);
             if (provider !== undefined) {
@@ -65,8 +65,18 @@ export const VIEWPORT_TOOLS = [
         },
     },
 ];
-/** Clamp a requested dimension into [MIN_DIM, MAX_DIM]; a missing/NaN value falls back to MIN_DIM. */
-function clampDim(value) {
-    const n = 'number' === typeof value && Number.isFinite(value) ? Math.round(value) : MIN_DIM;
-    return Math.max(MIN_DIM, Math.min(n, MAX_DIM));
+/**
+ * Clamp a requested dimension into [MIN_DIM, MAX_DIM]; a missing value falls back to MIN_DIM.
+ *
+ * A value that is PRESENT but not a finite number is refused, not read as missing: a client that
+ * sent `"1440"` meant 1440, and answering with a 64px page it never asked for made every later
+ * snapshot, click and screenshot on that page read as broken (#1118).
+ */
+function clampDim(key, value) {
+    if (value === undefined)
+        return MIN_DIM;
+    if ('number' !== typeof value || !Number.isFinite(value)) {
+        throw new Error(`${ReticleTool.VIEWPORT}: \`${key}\` must be a number of CSS px, got ${JSON.stringify(value)} — NOT applied`);
+    }
+    return Math.max(MIN_DIM, Math.min(Math.round(value), MAX_DIM));
 }

package/dist/portal/session/session.d.ts

@@ -216,16 +216,13 @@ export declare class Session implements HandshakeFacts {
         total: number;
         dropped: number;
     };
+    /** Did the event store lose scarce evidence from a window opened at `cursor`? See `windowLost`. */
+    lostSince(cursor: number): boolean;
     /**
-     * Did the EVENT STORE lose scarce evidence from a window opened at `cursor`? The input to whether a
-     * verdict's capture was clean — see `RingBuffer.lostSince`, and never the raw drop counter, which
-     * moves for the age and churn evictions that every live page produces continuously. The journal is
-     * the other half of that store, so a durable read that could not reach back to `cursor` lost
-     * exactly what an eviction would have. Both boundaries are INCLUSIVE (`t` is a millisecond many
-     * records share) and an absent `lostThroughT` impeaches every window rather than none — the
-     * conservative direction, both times.
+     * Hold events at/after `cursor` against count-cap eviction until the returned function runs, so a
+     * predicate's own match cannot be dropped inside the window it is graded on (#668).
      */
-    lostSince(cursor: number): boolean;
+    protectWindow(cursor: number): () => void;
     onEvent(listener: (event: ReticleEvent) => void): () => void;
     onDisconnect(listener: () => void): () => void;
     /** Send a command to the browser and await its reply (or time out). */

package/dist/portal/session/session.js

@@ -14,7 +14,7 @@ import { span } from '../../trace.js';
 import { keepCallerContextInDaemon, noteToDaemonLog } from './daemon-answers.js';
 import { isKnownRealm, EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, HudUseDataSchema, ReticleCommand, MessageKind, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
 import { RingBuffer } from '@reticlehq/engine/window/ring-buffer.js';
-import { readJournalWriteLoss, readQueryEvents, } from '../../memory/journal/journal-query.js';
+import { readJournalWriteLoss, readQueryEvents, windowLost, } from '../../memory/journal/journal-query.js';
 import {} from '@reticlehq/engine/window/ambient.js';
 import { ObservedState, controlLabelsOf } from './facts/observed-state.js';
 import { recordBrowserLatency, recordHudUse, recordSdkFailure, } from '../../telemetry/session-metrics.js';
@@ -528,20 +528,16 @@ export class Session {
     bufferHealth() {
         return this.#buffer.bufferHealth();
     }
+    /** Did the event store lose scarce evidence from a window opened at `cursor`? See `windowLost`. */
+    lostSince(cursor) {
+        return windowLost(this.#journalReader, this.#buffer, cursor);
+    }
     /**
-     * Did the EVENT STORE lose scarce evidence from a window opened at `cursor`? The input to whether a
-     * verdict's capture was clean — see `RingBuffer.lostSince`, and never the raw drop counter, which
-     * moves for the age and churn evictions that every live page produces continuously. The journal is
-     * the other half of that store, so a durable read that could not reach back to `cursor` lost
-     * exactly what an eviction would have. Both boundaries are INCLUSIVE (`t` is a millisecond many
-     * records share) and an absent `lostThroughT` impeaches every window rather than none — the
-     * conservative direction, both times.
+     * Hold events at/after `cursor` against count-cap eviction until the returned function runs, so a
+     * predicate's own match cannot be dropped inside the window it is graded on (#668).
      */
-    lostSince(cursor) {
-        if (this.#buffer.lostSince(cursor))
-            return true;
-        const lost = this.#journalReader?.readLoss?.();
-        return lost !== undefined && (lost.lostThroughT === undefined || lost.lostThroughT >= cursor);
+    protectWindow(cursor) {
+        return this.#buffer.protect(cursor);
     }
     onEvent(listener) {
         this.#listeners.add(listener);

package/dist/surface/http-server.d.ts

@@ -8,7 +8,7 @@ export interface SharedServer {
      * so each concurrent Claude Code client needs its own McpServer.
      * Must be called before listen.
      */
-    attachMcp(factory: () => McpServer): void;
+    attachMcp(factory: (peerSkew?: string) => McpServer): void;
     /** Register the JSON the daemon returns from GET /status (live sessions + health for `reticle status`). */
     /** `held`: the request carried STATUS_HOLD_QUERY — a setup run is waiting on this daemon. */
     attachStatus(provider: (held: boolean) => unknown): void;

package/dist/surface/http-server.js

@@ -2,7 +2,7 @@ import * as http from 'node:http';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { MCP_SSE_PATH, MCP_MESSAGE_PATH, MCP_SHUTDOWN_EVENT, STATUS_PATH, STATUS_HOLD_QUERY, DRIVE_PATH, } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
-import { noteAgentPeer, PEER_VERSION_PARAM, PEER_CONTRACT_PARAM, } from '../command/version/peer-announce.js';
+import { agentPeerSkew, PEER_VERSION_PARAM, PEER_CONTRACT_PARAM, } from '../command/version/peer-announce.js';
 import { log } from '../log.js';
 import { isLoopbackHost, isLocalWebOrigin, isLoopbackPeer, requestToken, tokensMatch, } from '../portal/bridge/token-auth.js';
 import { LOOPBACK_IDLE_MS } from './loopback-agent.js';
@@ -141,7 +141,7 @@ export function createSharedServer(options = {}) {
             // own check (a stderr line no agent reads), a nudge queued here rides out on the agent's next
             // tool result. That is the pair the user hits after `npm update`: a cached npx MCP package
             // talking to a daemon from a different build.
-            noteAgentPeer(url.searchParams.get(PEER_VERSION_PARAM), url.searchParams.get(PEER_CONTRACT_PARAM));
+            const peerSkew = agentPeerSkew(url.searchParams.get(PEER_VERSION_PARAM), url.searchParams.get(PEER_CONTRACT_PARAM));
             if (mcpFactory === undefined) {
                 res.writeHead(503, { 'Content-Type': 'text/plain' });
                 res.end('MCP server not ready');
@@ -150,7 +150,8 @@ export function createSharedServer(options = {}) {
             // Fresh McpServer per connection: the MCP SDK's Protocol layer only supports
             // one active transport per Server instance, so concurrent clients each need
             // their own instance backed by the same shared ToolDeps.
-            const mcpServer = mcpFactory();
+            // Handed to THIS connection's server only: the skew is about this agent, not the daemon (#1136).
+            const mcpServer = mcpFactory(peerSkew);
             const transport = new SSEServerTransport(MCP_MESSAGE_PATH, res);
             const sid = transport.sessionId;
             transports.set(sid, transport);

package/dist/surface/mcp/mcp.js

@@ -662,7 +662,7 @@ tools = tableForSurface(profile)) {
                     content: [
                         {
                             type: 'text',
-                            text: JSON.stringify(liveCallValues(takeVersionSkewOnto(buildErrorPayload(message)), advertisedNames)),
+                            text: JSON.stringify(liveCallValues(takeVersionSkewOnto(buildErrorPayload(message), deps.peerSkew), advertisedNames)),
                         },
                     ],
                 };

package/dist/surface/mcp/proxy/proxy-log.js

@@ -6,11 +6,9 @@
  * keep that file from becoming the largest thing on the user's disk.
  */
 import { appendFileSync, mkdirSync, renameSync, statSync, truncateSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { ReticleDir } from '@reticlehq/core';
 import { log } from '../../../log.js';
-import { MAX_DAEMON_LOG_BYTES, recoverOversizedLog, rotateDaemonLog, } from '../../../command/daemon/daemon.js';
+import { MAX_DAEMON_LOG_BYTES, recoverOversizedLog, rotateDaemonLog, reticleStateHome, } from '../../../command/daemon/daemon.js';
 /**
  * Which port this proxy serves, for the log file name. Set once at startup.
  *
@@ -79,7 +77,7 @@ export function setProxyLogPort(port) {
 /** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
 export function proxyLogPath(port = logPort) {
     const name = port === undefined ? 'mcp-proxy.log' : `proxy-${String(port)}.log`;
-    return join(homedir(), ReticleDir.ROOT, name);
+    return join(reticleStateHome(), name);
 }
 /**
  * Log to stderr (which the agent host usually swallows) AND to ~/.reticle/proxy-<port>.log, which it
@@ -96,7 +94,7 @@ export function proxyLogPath(port = logPort) {
 export function proxyLog(event, fields = {}) {
     log(event, fields);
     try {
-        const dir = join(homedir(), ReticleDir.ROOT);
+        const dir = reticleStateHome();
         mkdirSync(dir, { recursive: true });
         // WITH A TIMESTAMP. This file is the only record of an outage that survives the session, and
         // without one it cannot answer the two questions anyone brings to it: when did this happen, and

package/dist/surface/tools/act-tools.js

@@ -62,8 +62,8 @@ import { readAlreadyTrue } from './act/already-true.js';
 /**
  * The action vocabulary, derived from ActionType — never retyped.
  *
- * The description used to list thirteen actions while ActionType had seventeen: blur, upload, drag
- * and webmcp were real, callable, and undocumented, because a hand-copied list drifts the moment
+ * The description used to omit callable actions such as blur, upload and drag,
+ * because a hand-copied list drifts the moment
  * someone adds an arm. Deriving both the schema and the prose from the enum makes that impossible.
  *
  * The handler already refused an unknown action with a good message; the schema now refuses it

package/dist/surface/tools/dynamic-tools.js

@@ -29,6 +29,17 @@ function unknownParamsError(toolName, unknown) {
 const TOOLS_LIST_ACTION = 'list';
 /** What to write instead — the one parameter reticle_tools declares, and the no-argument form. */
 const TOOLS_ARG_HINT = 'name the tools you want in `names`: reticle_tools { names: ["reticle_act_and_wait"] } — or call it with no arguments for the full catalog';
+/**
+ * The refusal for arguments of the wrong type, naming each offending key and what it declared.
+ * `path` is joined for a nested value (`intents.0.id`); a missing required key reads as the key.
+ */
+function invalidParamsError(toolName, issues) {
+    const named = issues.map((issue) => {
+        const where = 0 === issue.path.length ? '(arguments)' : issue.path.join('.');
+        return `${where} (${issue.message})`;
+    });
+    return `invalid ${1 === named.length ? 'parameter' : 'parameters'} for ${toolName}: ${named.join('; ')} — NOT applied, so any result would be an answer to a different question`;
+}
 /** The keys not declared by `shape`, in call order. */
 function unknownKeys(args, shape) {
     const declared = new Set(Object.keys(shape));
@@ -263,8 +274,24 @@ callable) {
                     hint: 'fix the arguments and call reticle_run again',
                 };
             }
+            // Keys are not enough: the TYPES are the other half of what a direct call's SDK validation
+            // refuses. Unchecked here, `reticle_viewport { width: "1440" }` from a client that stringifies
+            // numbers reached the handler, which read a non-number as missing and set the page to 64x64,
+            // and `reticle_intent { action: "declare", intents: "[...]" }` stored nothing and answered
+            // `{ intents: [] }` (#1118). The parsed value goes on, as it does on the direct path, so a
+            // schema's defaults and transforms apply the same way through either door.
+            const typed = z.object(target.inputSchema).safeParse(callArgs);
+            if (!typed.success) {
+                return {
+                    error: invalidParamsError(name, typed.error.issues),
+                    tool: name,
+                    params: paramInfo(target.inputSchema),
+                    ...(target.example === undefined ? {} : { example: target.example }),
+                    hint: 'fix the arguments and call reticle_run again',
+                };
+            }
             try {
-                return await runTool(target, deps, callArgs);
+                return await runTool(target, deps, typed.data);
             }
             catch (error) {
                 // The SAME payload the direct tool path builds — recovery included. Answering every failure
@@ -272,7 +299,7 @@ callable) {
                 // is reached through here: a stale ref, a paused session, a missing pairing token all came
                 // back as the agent's arguments being wrong, which is advice that spends the retry.
                 const message = error instanceof Error ? error.message : String(error);
-                return { ...takeVersionSkewOnto(buildErrorPayload(message)), tool: name };
+                return { ...takeVersionSkewOnto(buildErrorPayload(message), deps.peerSkew), tool: name };
             }
         },
     };

package/dist/surface/tools/error-recovery.js

@@ -293,8 +293,7 @@ const RULES = [
     { match: /contenteditable/i, hint: RECOVERY.UNSUPPORTED_SURFACE },
     { match: /cannot hover without a real pointer/i, hint: RECOVERY.HOVER_NEEDS_POINTER },
     { match: /cannot \w+ a (disabled|readonly) </i, hint: RECOVERY.NOT_EDITABLE },
-    // Three spellings ship — "action", "native action", "WebMCP tool" — and the rule matched one, so
-    // two thirds of the same deliberate refusal still read as a possible defect.
+    // Both "action" and "native action" refusals need the same confirmation guidance.
     {
         match: /potentially destructive (?:\w+ )*(?:action|tool) blocked/i,
         hint: RECOVERY.CONFIRM_DANGEROUS,

package/dist/surface/tools/harness-explore.js

@@ -18,7 +18,7 @@ import { buildDomainModel } from '../../judgement/domain/domain-model.js';
 import { readContract } from '../../memory/project/dir/reticle-dir.js';
 import { sessionRoot } from '../../memory/project/session-root.js';
 import { buildHarnessPlan, planAsText } from './harness-plan.js';
-import { openAiDriver, openAiOptionsFromEnv } from '../../features/harness/openai-driver.js';
+import { openAiDriver, openAiOptionsFromEnv, } from '../../features/harness/openai-driver.js';
 import { fetchPlatformConfig } from '../../features/harness/platform-config.js';
 import { DEFAULT_MAX_STEPS, runHarness, } from '../../features/harness/harness.js';
 import { reticleToolset } from './harness-toolset.js';
@@ -414,6 +414,10 @@ function buildDriver(env, maxSteps, plan, requested, fills) {
         fillValue: fillValues({
             secret: (label) => env[secretEnvKey(label)],
             ...(fills === undefined ? {} : { cache: fills }),
+            // GPT first: a linked machine reaches it through the platform with no key of its own.
+            ...(openAiOptionsFromEnv(env) === undefined
+                ? {}
+                : { openai: openAiOptionsFromEnv(env) }),
             ...(harnessOptionsFromEnv(env) === undefined
                 ? {}
                 : { generator: harnessOptionsFromEnv(env) }),

package/dist/surface/tools/invoke-tool.js

@@ -351,9 +351,6 @@ export async function runTool(tool, deps, args) {
     // closure carries this call's own identity, which is also what makes peak-concurrency measurable.
     // A daemon that has served even one tool call is doing a job for somebody; see daemon-usefulness.
     noteToolCall();
-    // The ONBOARD firsts, at the chokepoint every call already passes through — so a second dispatch
-    // path cannot quietly stop reporting them the way an extra listener would.
-    noteOnboardingFirst(tool.name);
     // The impact record needs the project's own `.reticle` root, and this is the first place every
     // call knows it. Idempotent: the first root wins for the daemon's lifetime.
     initImpact({ reticleRoot: deps.reticleRoot });
@@ -385,10 +382,6 @@ export async function runTool(tool, deps, args) {
     // page and then wandered off" becomes a number instead of an impression.
     if (ACTION_TOOLS.has(tool.name)) {
         getSessionMetrics().recordAction();
-        // The two funnel rungs this branch is the authority on: the first action of the run, and the
-        // fact that this install has been driven at all. Reported from the set that already decides
-        // what "drove the page" means, so a fourth driving tool inherits both.
-        noteActed(args);
     }
     const settleTiming = getSessionMetrics().startToolCall(tool.name, args);
     const startedAt = Date.now();
@@ -533,6 +526,17 @@ export async function runTool(tool, deps, args) {
         // concurrency slot and peakConcurrentTools would climb forever on an unhealthy session.
         settleTiming(Date.now() - startedAt);
     }
+    // Milestones describe work that ran. Refusals and paused calls must not consume the firsts.
+    // Record action before verdict: act_and_wait can complete both in this same call.
+    if (isPlainObject(raw) && !resultIsError(raw) && raw['paused'] !== true && raw['ok'] !== false) {
+        noteOnboardingFirst(tool.name);
+        const effect = raw['effect'];
+        const acted = raw['dispatched'] !== false &&
+            (!isPlainObject(effect) || effect['dispatched'] !== false) &&
+            (tool.name !== ReticleTool.ACT_AND_WAIT || isPlainObject(effect));
+        if (ACTION_TOOLS.has(tool.name) && acted)
+            noteActed(args);
+    }
     // The human-feedback ask rides out on the first VERIFICATION that completes — the one moment the
     // experience is fresh and there is something concrete to react to. It is spliced BEFORE the
     // session-bound early return, because two of the four verification tools (flow_verify,
@@ -584,7 +588,7 @@ export async function runTool(tool, deps, args) {
     // reticle_sessions.versionSkew and a CLI log line — two places an agent driving a flow never
     // looks — so it could work a whole session against a mismatched pair and never learn the one fact
     // that explains the behaviour. It rides out here on whatever tool it happens to be calling.
-    const skew = isPlainObject(raw) ? takeVersionSkew() : undefined;
+    const skew = isPlainObject(raw) ? takeVersionSkew(deps.peerSkew) : undefined;
     // A feedback report that was accepted and then failed to send. Same one-shot channel, because the
     // reporter is the only person who can act on it and they are not reading the daemon log — and a
     // report announced as accepted and then silently lost is the failure the awaited send existed to

package/dist/surface/tools/tool-kit.d.ts

@@ -59,6 +59,16 @@ export interface ToolDeps<Ext = unknown> {
      * `tools.ts`, which keeps every existing `ToolDeps` construction working unchanged.
      */
     snapshots?: SnapshotCache;
+    /**
+     * The skew between THIS client's MCP server and the daemon, told once to this connection only.
+     *
+     * Per attach for the same reason as `snapshots`: one daemon serves every agent on the machine, and
+     * a daemon-wide queue handed one agent's "restart your MCP server" to whichever agent called next,
+     * whose server matched (#1136). Absent ⇒ this connection's server matched, or it did not announce.
+     */
+    peerSkew?: {
+        take(): string | undefined;
+    };
     /** cross-run outcome memory (.reticle/project.json). */
     project: ProjectStore;
     /** optional native-input provider. undefined ⇒ everything stays synthetic. */

package/dist/telemetry/argument-shape.js

@@ -27,7 +27,7 @@ import { ActionType, FeedbackKind, QueryBy, SnapshotMode } from '@reticlehq/core
 const SAFE_ENUM_PARAMS = new Map([
     // Every entry DERIVED from the enum core already owns, never hand-listed. The first version listed
     // them literally and was wrong on the day it shipped, not merely at risk: `action` was missing
-    // `fill`, `dblclick`, `submit`, `scrollIntoView`, `drag` and `webmcp` — so `fill`, one of the most
+    // `fill`, `dblclick`, `submit`, `scrollIntoView` and `drag` — so `fill`, one of the most
     // common actions there is, silently reported as `other` — while carrying a `scroll` that
     // `ActionType` does not define. `mode` mixed SnapshotMode with unrelated session-lifecycle values.
     // Deriving is not tidiness here; it is the difference between the data being right and being wrong.

package/dist/telemetry/onboarding-firsts.d.ts

@@ -1,9 +1,9 @@
-/** A tool call the daemon just ran. Called from the dispatch chokepoint, which sees every one. */
+/** A successful page read. The dispatcher calls this after excluding refusals and pauses. */
 export declare function noteOnboardingFirst(toolName: string): void;
 /**
  * The first ACTION of this run, and the fact that this install has been driven at all.
  *
- * Called from the dispatch chokepoint's own action branch rather than matched on a tool name here.
+ * Called after the dispatcher observes a dispatched action, rather than on an attempted call.
  * The name test was `toolName === ReticleTool.ACT`, on the worry that `act_and_wait` would report
  * one call as two different firsts — and the worry was backwards: this server's instructions tell
  * every agent to PREFER `act_and_wait`, so the step measured the tool we ask agents not to use and

package/dist/telemetry/onboarding-firsts.js

@@ -15,7 +15,7 @@ import { reportOnboardingStep } from './onboarding-funnel.js';
  * drives in another has still only crossed each of these once.
  */
 const seen = { look: false, act: false, verdict: false, driven: false };
-/** A tool call the daemon just ran. Called from the dispatch chokepoint, which sees every one. */
+/** A successful page read. The dispatcher calls this after excluding refusals and pauses. */
 export function noteOnboardingFirst(toolName) {
     if (!seen.look && LOOK_TOOLS.has(toolName)) {
         seen.look = true;
@@ -29,7 +29,7 @@ export function noteOnboardingFirst(toolName) {
 /**
  * The first ACTION of this run, and the fact that this install has been driven at all.
  *
- * Called from the dispatch chokepoint's own action branch rather than matched on a tool name here.
+ * Called after the dispatcher observes a dispatched action, rather than on an attempted call.
  * The name test was `toolName === ReticleTool.ACT`, on the worry that `act_and_wait` would report
  * one call as two different firsts — and the worry was backwards: this server's instructions tell
  * every agent to PREFER `act_and_wait`, so the step measured the tool we ask agents not to use and

package/docs/actions.mdx

@@ -5,7 +5,7 @@ description: Every action reticle_act and reticle_act_and_wait can perform, with
 icon: hand-pointer
 ---
 
-Every action Reticle can perform takes the same shape: a `ref` from [`reticle_look { action: "page" }`](/tools/snapshot) or [`reticle_look { action: "find" }`](/tools/query), an `action` name, and an optional `args` object. The same seventeen actions are available on [`reticle_act`](/tools/act), which proves nothing, and on [`reticle_act_and_wait`](/tools/act-and-wait), which returns a verdict.
+Every action Reticle can perform takes the same shape: a `ref` from [`reticle_look { action: "page" }`](/tools/snapshot) or [`reticle_look { action: "find" }`](/tools/query), an `action` name, and an optional `args` object. The same actions are available on [`reticle_act`](/tools/act), which proves nothing, and on [`reticle_act_and_wait`](/tools/act-and-wait), which returns a verdict.
 
 ```json
 { "ref": "e104", "action": "fill", "args": { "value": "reticle" } }
@@ -26,7 +26,6 @@ Every action Reticle can perform takes the same shape: a `ref` from [`reticle_lo
 | `scrollIntoView` | none |  |
 | `upload` | `{ content?, name?, type?, path? }` | Sets a file on `<input type="file">`. Inline bytes default to `"reticle test file"` / `"file.txt"` / `"text/plain"`. `path` reads a file from disk, scoped to the project root plus any opt-in directories listed in `.reticle.json` as `"uploadRoots": ["~/Downloads", "/Volumes/fixtures"]`. A refusal names every allowed root. |
 | `drag` | `{ toRef }` | Pointer-based drag (dnd-kit, react-beautiful-dnd) plus HTML5 DnD. `target` is an alias |
-| `webmcp` | `{ tool, params }` | Calls a `navigator.modelContext` tool, if the site exposes one |
 
 ### Arguments that are not actions
 

package/docs/cli/cloud.mdx

@@ -1,16 +1,18 @@
 ---
 title: reticle cloud commands
-description: Sign in, link a repository, and read runs and regressions from Reticle Cloud.
+description: Connect a project in one command, then read runs and regressions from Reticle Cloud.
 icon: cloud
 ---
 
-Ten subcommands bind this repository to Reticle Cloud so runs and flows land on a dashboard. They dispatch before the local parser, so `reticle login` is one tool, not a second binary.
+From your app directory, `reticle connect --project "My App"` wires the app, opens browser sign-in approval if needed, links the named cloud project, and syncs the local history already on this machine. Run the [installer](/quickstart) once on the machine first. The commands below remain available when you need to sign in or link separately.
 
 ```bash
-npx @reticlehq/server <login|logout|whoami|link|project|config|push|runs|regression|share>
+npx @reticlehq/server connect --project "My App"
 ```
 
-These are thin clients over the `/v1` API. The logic is server-side; these verbs surface it.
+Use `--url https://your-cloud-origin` for a self-hosted cloud. `connect` checks a saved sign-in against that exact host before reuse; if it has expired, the browser approval opens again. It mints or reuses a project-scoped key, so there is no key to paste. A newly wired app may have no run to sync yet: ask your agent to verify one flow and the linked daemon will sync the result. Run `reticle whoami` to check the binding and `reticle push` to send anything still pending.
+
+The other cloud commands are thin clients over the `/v1` API. Their logic is server-side.
 
 ## Where credentials live
 

package/docs/cli.mdx

@@ -13,13 +13,9 @@ npx @reticlehq/server <command>
 ```
 
 <Warning>
-  **Always invoke it as `npx @reticlehq/server <command>`.** The tables below name the commands as
-  `reticle <command>`, because `reticle` is the bin this package installs and that is what the CLI
-  prints about itself. It is **not** a package on npm: the bare name `reticle` belongs to an
-  unrelated author, so putting `npx` in front of it downloads and runs their code instead of ours.
-  Once
-  `@reticlehq/server` is a dependency of your project, `reticle <command>` works from an npm script
-  or with the bin on your PATH.
+  If you used the installer, run `reticle <command>`: it put that bin on your PATH. Otherwise use
+  `npx @reticlehq/server <command>`. Do not put `npx` before the bare `reticle` bin name: the npm
+  package with that name belongs to an unrelated author.
 </Warning>
 
 <Note>
@@ -30,6 +26,16 @@ npx @reticlehq/server <command>
 
 ## Setup and diagnosis
 
+### `reticle connect`
+
+From an app directory, one command wires an unwired app, proves a browser session, signs in through browser approval if needed, links the chosen cloud project, and syncs existing local history. A saved sign-in is reused only after the intended cloud host accepts it. Run `reticle init` instead for local-only verification.
+
+```bash
+npx @reticlehq/server connect --project "My App"
+```
+
+For a self-hosted cloud, add `--url <cloud origin>`. If the app was already wired, `connect` keeps its local setup and refreshes the cloud link. A fresh app has no run to send until you verify a flow with your agent.
+
 ### `reticle init`
 
 Wires Reticle into the project in the current directory, then boots the app and proves a session connected. It exits non-zero if nothing connected, and prints what is left to do. It does not drive: proving a flow is the FIRST RUN, `reticle verify <url> --explore --persona "<who does what>"`.

package/docs/desktop.mdx

@@ -216,7 +216,7 @@ Alternatively, since an Electron renderer _is_ Chromium, `--remote-debugging-por
 
 ```toml
 [dependencies]
-reticle-tauri = "3.4"
+reticle-tauri = "3.5"
 ```
 
 ```rust