@reticlehq/server 3.8.1 → 3.9.0

package/dist/telemetry/session-metrics.js

@@ -15,12 +15,13 @@
  * URLs, no error messages — the accumulator has no way to hold them, which is a stronger guarantee
  * than a rule saying it shouldn't.
  */
-import { BrowserLaunchKind, } from '@reticlehq/core/telemetry';
+import { BrowserLaunchKind, ConnectFailure, OnboardingPhase, OnboardingStop, } from '@reticlehq/core/telemetry';
 import { errorSkeleton, fingerprintError } from './error-fingerprint.js';
 import { describeToolParams } from './argument-shape.js';
 import { machineSnapshot } from './machine-snapshot.js';
 import { classifyError } from './error-class.js';
 import { HudMetrics } from './hud-metrics.js';
+import { reportOnboardingStop } from './onboarding-funnel.js';
 import { releaseVersionOf } from '../command/update/version-seen.js';
 /** Cap the distinct error shapes held in memory — a pathological loop must not grow unbounded. */
 const MAX_ERROR_KINDS = 40;
@@ -58,6 +59,12 @@ const BREADCRUMB_LENGTH = 12;
  * never fires for the sessions that need it most.
  */
 const UNVERIFIED_ACTION_NUDGE_AT = 3;
+/** The launch failures that leave no browser to drive: a stop on the path to a first verdict. */
+const CHROMIUM_UNAVAILABLE = new Set([
+    ConnectFailure.CHROMIUM_MISSING,
+    ConnectFailure.PLAYWRIGHT_MISSING,
+]);
+const DRIVEN_STEP = 'driven';
 /**
  * Mutable counters for one daemon lifetime. A plain class, not a store: it is process-local, it never
  * persists, and it dies with the daemon.
@@ -187,10 +194,12 @@ export class SessionMetrics {
     }
     /** A tab went into the background (true) or came back (false): its HUD time pauses meanwhile. */
     setHudTabHidden(tab, hidden) {
-        if (hidden)
+        if (hidden) {
             this.#hud.hide(tab);
-        else
+        }
+        else {
             this.#hud.show(tab);
+        }
     }
     /** A tab went away: its HUD stops accruing time. */
     closeHudTab(tab) {
@@ -204,12 +213,14 @@ export class SessionMetrics {
     startToolCall(tool, args) {
         this.recordToolCall(tool, args);
         this.#concurrent += 1;
-        if (this.#concurrent > this.#peakConcurrent)
+        if (this.#concurrent > this.#peakConcurrent) {
             this.#peakConcurrent = this.#concurrent;
+        }
         let settled = false;
         return (durationMs) => {
-            if (settled)
-                return; // a double-settle would corrupt the concurrency count
+            if (settled) {
+                return;
+            } // a double-settle would corrupt the concurrency count
             settled = true;
             this.#concurrent = Math.max(0, this.#concurrent - 1);
             this.#busyMs += durationMs;
@@ -243,8 +254,9 @@ export class SessionMetrics {
      */
     recordUnknownTool(name) {
         this.#unknownToolCalls += 1;
-        if (name === undefined || 0 === name.length)
+        if (name === undefined || 0 === name.length) {
             return;
+        }
         const key = name.slice(0, 64);
         const seen = this.#unknownTools.get(key);
         if (seen !== undefined) {
@@ -253,8 +265,9 @@ export class SessionMetrics {
         }
         // Stop growing once full: a pathological loop must not balloon the payload. The head is what
         // gets built; the tail is noise.
-        if (this.#unknownTools.size >= MAX_ERROR_KINDS)
+        if (this.#unknownTools.size >= MAX_ERROR_KINDS) {
             return;
+        }
         this.#unknownTools.set(key, 1);
     }
     recordToolCall(tool, args) {
@@ -269,8 +282,9 @@ export class SessionMetrics {
         if (this.#currentRun > 1) {
             const best = this.#repeatRuns.get(tool) ?? 0;
             if (this.#currentRun > best &&
-                (this.#repeatRuns.has(tool) || this.#repeatRuns.size < MAX_REPEAT_TOOLS))
+                (this.#repeatRuns.has(tool) || this.#repeatRuns.size < MAX_REPEAT_TOOLS)) {
                 this.#repeatRuns.set(tool, this.#currentRun);
+            }
         }
         this.#toolCalls += 1;
         this.#lifetimeToolCalls += 1;
@@ -280,23 +294,27 @@ export class SessionMetrics {
         bump(this.#toolCounts, tool);
         this.#inFlight = tool;
         this.#breadcrumb.push(tool);
-        if (this.#breadcrumb.length > BREADCRUMB_LENGTH)
+        if (this.#breadcrumb.length > BREADCRUMB_LENGTH) {
             this.#breadcrumb.shift();
-        if (args === undefined)
+        }
+        if (args === undefined) {
             return;
+        }
         // Which PARAMETERS get used, per tool — names only (plus a short allowlist of our own enums).
         // Bounded by our own schemas: a tool has a fixed handful of declared parameters, so this map
         // cannot grow with traffic the way a value-carrying one would.
         let perTool = this.#toolParams.get(tool);
         if (perTool === undefined) {
-            if (this.#toolParams.size >= MAX_PARAM_TOOLS)
+            if (this.#toolParams.size >= MAX_PARAM_TOOLS) {
                 return;
+            }
             perTool = new Map();
             this.#toolParams.set(tool, perTool);
         }
         for (const param of describeToolParams(args)) {
-            if (perTool.size < MAX_PARAMS_PER_TOOL || perTool.has(param))
+            if (perTool.size < MAX_PARAMS_PER_TOOL || perTool.has(param)) {
                 bump(perTool, param);
+            }
         }
     }
     /**
@@ -310,8 +328,9 @@ export class SessionMetrics {
         // indistinguishable from the rest inside one `toolErrors` count.
         bump(this.#errorClasses, classifyError(message));
         this.#currentCallErrored = true;
-        if (NO_SESSION_ERROR.test(message))
+        if (NO_SESSION_ERROR.test(message)) {
             this.#noSessionErrors += 1;
+        }
         const fingerprint = fingerprintError(message);
         const existing = this.#errorKinds.get(fingerprint);
         if (existing !== undefined) {
@@ -319,8 +338,9 @@ export class SessionMetrics {
             return;
         }
         // Stop growing once the cap is hit; the tail is noise and the head is what gets fixed.
-        if (this.#errorKinds.size >= MAX_ERROR_KINDS)
+        if (this.#errorKinds.size >= MAX_ERROR_KINDS) {
             return;
+        }
         this.#errorKinds.set(fingerprint, {
             fingerprint,
             count: 1,
@@ -343,8 +363,9 @@ export class SessionMetrics {
             existing.count += 1;
             return;
         }
-        if (this.#sdkFailureKinds.size >= MAX_ERROR_KINDS)
+        if (this.#sdkFailureKinds.size >= MAX_ERROR_KINDS) {
             return;
+        }
         this.#sdkFailureKinds.set(fingerprint, {
             fingerprint,
             count: 1,
@@ -428,8 +449,9 @@ export class SessionMetrics {
     /** The 1-based occurrence of this finding in the session, or undefined past the cap. */
     recordBugOccurrence(fingerprint) {
         const seen = this.#bugOccurrences.get(fingerprint);
-        if (seen === undefined && this.#bugOccurrences.size >= MAX_BUG_FINGERPRINTS)
+        if (seen === undefined && this.#bugOccurrences.size >= MAX_BUG_FINGERPRINTS) {
             return undefined;
+        }
         const occurrence = (seen ?? 0) + 1;
         this.#bugOccurrences.set(fingerprint, occurrence);
         return occurrence;
@@ -437,8 +459,9 @@ export class SessionMetrics {
     recordBug(kind) {
         this.#bugsFound += 1;
         this.#lifetimeBugsFound += 1;
-        if (this.#bugKinds.size < MAX_ERROR_KINDS || this.#bugKinds.has(kind))
+        if (this.#bugKinds.size < MAX_ERROR_KINDS || this.#bugKinds.has(kind)) {
             bump(this.#bugKinds, kind);
+        }
         const first = !this.#seenBugKinds.has(kind);
         this.#seenBugKinds.add(kind);
         return first;
@@ -457,8 +480,9 @@ export class SessionMetrics {
         this.#connections.set(kind, stats);
         let settled = false;
         return (failure) => {
-            if (settled)
+            if (settled) {
                 return;
+            }
             settled = true;
             if (failure === undefined) {
                 stats.successes += 1;
@@ -466,12 +490,21 @@ export class SessionMetrics {
             }
             stats.failures ??= {};
             stats.failures[failure] = (stats.failures[failure] ?? 0) + 1;
+            if (CHROMIUM_UNAVAILABLE.has(failure)) {
+                reportOnboardingStop({
+                    phase: OnboardingPhase.FIRST_RUN,
+                    step: DRIVEN_STEP,
+                    reason: failure,
+                    stop: OnboardingStop.CHROMIUM_UNAVAILABLE,
+                });
+            }
         };
     }
     recordClient(name, version) {
         const key = name.slice(0, 64);
-        if (this.#clients.size < MAX_CLIENTS)
+        if (this.#clients.size < MAX_CLIENTS) {
             this.#clients.add(key);
+        }
         // The version was already in the handshake and was being dropped. A regression in agent
         // behaviour is usually a client version, and without this it is unattributable.
         if (version !== undefined && '' !== version && this.#clientVersions.size < MAX_CLIENTS) {
@@ -511,8 +544,9 @@ export class SessionMetrics {
     summarize(final, exit) {
         // The last call has no successor to resolve it, so resolve it here. Only on a FINAL summary:
         // a periodic flush is not the end of anything and would resolve a call still in flight.
-        if (final)
+        if (final) {
             this.#resolveRecovery();
+        }
         const machine = machineSnapshot();
         // EVERY event reports its own window, the final one included: summing a session's
         // `session_progress` + `daemon_stopped` rows is then its total. The final event used to swap in
@@ -612,10 +646,12 @@ export class SessionMetrics {
      */
     #resolveRecovery() {
         if (this.#priorCallErrored) {
-            if (this.#currentCallErrored)
+            if (this.#currentCallErrored) {
                 this.#errorsRepeated += 1;
-            else
+            }
+            else {
                 this.#errorsRecovered += 1;
+            }
         }
         this.#priorCallErrored = this.#currentCallErrored;
         this.#currentCallErrored = false;
@@ -625,14 +661,18 @@ export class SessionMetrics {
      * that left explains everything after it, and a verdict settles whatever preceded it.
      */
     #endReason() {
-        if (0 === this.#lifetimeToolCalls)
+        if (0 === this.#lifetimeToolCalls) {
             return 'never_used';
-        if (this.#clientLeft)
+        }
+        if (this.#clientLeft) {
             return 'client_left';
-        if (this.#unsettledActions > 0)
+        }
+        if (this.#unsettledActions > 0) {
             return 'abandoned';
-        if (this.#lifetimeVerifications > 0)
+        }
+        if (this.#lifetimeVerifications > 0) {
             return 'verified';
+        }
         return 'explored';
     }
     /**

package/dist/telemetry/telemetry.d.ts

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

package/dist/telemetry/telemetry.js

@@ -138,20 +138,24 @@ const Env = {
 };
 const isDisabled = (env, cwd = process.cwd()) => {
     const off = new Set(['0', 'false', 'off', 'no']);
-    if (off.has((env[Env.DISABLE] ?? '').toLowerCase()))
+    if (off.has((env[Env.DISABLE] ?? '').toLowerCase())) {
         return true;
+    }
     // Recording to a local file is not "phoning home", and the guards below exist to stop us phoning
     // home. Chief among them is the source-checkout rule — which is exactly where a release sweep is
     // driven from, so a sink that inherited it would record nothing and look like it had worked.
-    if ((env[Env.FILE] ?? '') !== '')
+    if ((env[Env.FILE] ?? '') !== '') {
         return false;
-    if (env[Env.VITEST] !== undefined)
-        return true; // a test run is not a user
+    }
+    if (env[Env.VITEST] !== undefined) {
+        return true;
+    } // a test run is not a user
     // Developing Reticle is not using Reticle. The `.env` carrying RETICLE_TELEMETRY=0 is gitignored,
     // so it only exists on the machine that made it — a fresh clone would phone home on a
     // contributor's first `reticle serve`. The repo marker is committed, so this guarantee travels.
-    if (isReticleSourceCheckout(cwd))
+    if (isReticleSourceCheckout(cwd)) {
         return true;
+    }
     const dnt = env[Env.DO_NOT_TRACK];
     return 'string' === typeof dnt && dnt !== '' && dnt !== '0';
 };
@@ -191,19 +195,22 @@ const readIdFile = (file) => {
 export const resolveIdentity = (file = ID_FILE) => {
     try {
         const existing = readIdFile(file);
-        if (existing !== undefined)
+        if (existing !== undefined) {
             return { anonymousId: existing, firstRun: false };
+        }
         const id = randomUUID();
         mkdirSync(dirname(file), { recursive: true });
         try {
             writeFileSync(file, id, { encoding: 'utf8', flag: 'wx' });
         }
         catch (error) {
-            if (!isAlreadyThere(error))
+            if (!isAlreadyThere(error)) {
                 throw error;
+            }
             const raced = readIdFile(file);
-            if (raced !== undefined)
+            if (raced !== undefined) {
                 return { anonymousId: raced, firstRun: false };
+            }
             // An empty file left by a crash: replace it, as the old code did.
             writeFileSync(file, id, 'utf8');
         }
@@ -235,30 +242,40 @@ export const projectFingerprint = (cwd) => {
     // stable across every directory inside one machine's checkout, a package.json root is the same for
     // a non-git project — and the raw cwd is stable across nothing, which is why it is last. See
     // `project-identity.test.ts` for what a wrong order costs.
-    const { key, source } = origin !== undefined
-        ? { key: origin, source: ProjectIdSource.GIT_ORIGIN }
-        : root !== undefined
-            ? { key: root, source: ProjectIdSource.GIT_ROOT }
-            : packageRoot(cwd) !== null
-                ? { key: packageRoot(cwd) ?? cwd, source: ProjectIdSource.PACKAGE_ROOT }
-                : { key: cwd, source: ProjectIdSource.CWD };
+    const { key, source } = projectKey(cwd, origin, root);
     return {
         projectId: createHash('sha256').update(key).digest('hex').slice(0, 32),
         // Reported alongside so the analytics knows whether this id is comparable to another machine's.
         source,
     };
 };
+/** The most stable key this directory has, and what it came from. */
+function projectKey(cwd, origin, root) {
+    if (origin !== undefined) {
+        return { key: origin, source: ProjectIdSource.GIT_ORIGIN };
+    }
+    if (root !== undefined) {
+        return { key: root, source: ProjectIdSource.GIT_ROOT };
+    }
+    const pkg = packageRoot(cwd);
+    if (pkg !== null) {
+        return { key: pkg, source: ProjectIdSource.PACKAGE_ROOT };
+    }
+    return { key: cwd, source: ProjectIdSource.CWD };
+}
 /** Nearest ancestor holding a package.json — the project boundary when there is no git. */
 const packageRoot = (cwd) => {
     let dir = cwd;
     // Same bound as the git walk: deep monorepos are well inside 20, and an unbounded loop on a
     // pathological path would hang the CLI's startup.
     for (let depth = 0; depth < 20; depth += 1) {
-        if (existsSync(join(dir, 'package.json')))
+        if (existsSync(join(dir, 'package.json'))) {
             return dir;
+        }
         const parent = dirname(dir);
-        if (parent === dir)
+        if (parent === dir) {
             return null;
+        }
         dir = parent;
     }
     return null;
@@ -329,18 +346,21 @@ export const createTelemetry = (opts) => {
     const cwd = opts.cwd ?? process.cwd();
     // A source checkout silences metrics but must not silence FEEDBACK — see onlyBlockedBySourceCheckout.
     const feedbackOnly = onlyBlockedBySourceCheckout(env, cwd);
-    if (isDisabled(env, cwd) && !feedbackOnly)
+    if (isDisabled(env, cwd) && !feedbackOnly) {
         return NOOP;
+    }
     try {
-        if (existsSync(join(reticleDir, OPT_OUT_FILE_NAME)))
-            return NOOP; // the persistent `reticle telemetry disable` opt-out
+        if (existsSync(join(reticleDir, OPT_OUT_FILE_NAME))) {
+            return NOOP;
+        } // the persistent `reticle telemetry disable` opt-out
     }
     catch {
         /* unreadable home dir — fall through; the env-var opt-outs above still apply */
     }
     const apiKey = env[Env.KEY] ?? POSTHOG_KEY;
-    if ('' === apiKey)
-        return NOOP; // no key baked in (dev/test build) — nowhere to send, stay silent
+    if ('' === apiKey) {
+        return NOOP;
+    } // no key baked in (dev/test build) — nowhere to send, stay silent
     const now = opts.now ?? (() => Date.now());
     const doFetch = opts.fetchImpl ?? fetch;
     const url = `${(env[Env.URL] ?? DEFAULT_URL).replace(/\/+$/, '')}${TELEMETRY_PATH}`;
@@ -375,8 +395,9 @@ export const createTelemetry = (opts) => {
     // How this process was launched: a property of the process, so read once. Only the bucket leaves.
     const launch = launchMethodOf(process.argv[1]);
     const home = opts.home ?? homedir();
-    if (!feedbackOnly)
+    if (!feedbackOnly) {
         showNoticeOnce(reticleDir);
+    }
     const spawnDetached = opts.spawnImpl ??
         ((command, args, input) => {
             const bodyFile = join(tmpdir(), `reticle-telemetry-${randomUUID()}.json`);
@@ -397,8 +418,9 @@ export const createTelemetry = (opts) => {
     const emit = async (kind, extra) => {
         // In a Reticle source checkout the emitter carries FEEDBACK and nothing else: somebody typed the
         // feedback, and no metric is worth phoning home from a contributor's clone.
-        if (feedbackOnly && TelemetryEventKind.FEEDBACK_SUBMITTED !== kind)
+        if (feedbackOnly && TelemetryEventKind.FEEDBACK_SUBMITTED !== kind) {
             return false;
+        }
         // One clock read for the whole event: `ts` and the licence check must agree, and two calls to
         // now() can straddle an expiry.
         const eventTs = now();
@@ -470,6 +492,7 @@ export const createTelemetry = (opts) => {
             ...(extra?.proxyExit !== undefined ? { proxyExit: extra.proxyExit } : {}),
             ...(extra?.daemonDeath !== undefined ? { daemonDeath: extra.daemonDeath } : {}),
             ...(extra?.wakeRefusal !== undefined ? { wakeRefusal: extra.wakeRefusal } : {}),
+            ...(extra?.gate !== undefined ? { gate: extra.gate } : {}),
             // A SCALAR: the event build and the wire schema, no `blocks` entry.
             ...(extra?.spawnMethod !== undefined ? { spawnMethod: extra.spawnMethod } : {}),
         };
@@ -484,7 +507,7 @@ export const createTelemetry = (opts) => {
         // PostHog filters and breakdowns operate on top-level properties, so a nested `feedback.stack`
         // would be invisible to the exact "which stacks report the most bugs" question this exists to
         // answer. One prefix keeps them grouped in the UI without a nested path.
-        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, onboarding, bug, refusal, outage, instrumentation, hud, link, harness, proxyExit, daemonDeath, wakeRefusal, ...rest } = event;
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, onboarding, bug, refusal, outage, instrumentation, hud, link, harness, proxyExit, daemonDeath, wakeRefusal, gate, ...rest } = event;
         // `$session_id` is PostHog's OWN session property, so sending ours under that name lights up
         // its built-in session views and funnels for free rather than requiring custom HogQL everywhere.
         // `sessionId` rides only on events that happened inside a daemon run. A one-shot CLI command
@@ -522,6 +545,7 @@ export const createTelemetry = (opts) => {
             proxyExit,
             daemonDeath,
             wakeRefusal,
+            gate,
         };
         for (const [prefix, block] of Object.entries(blocks)) {
             for (const [key, value] of Object.entries(block ?? {})) {
@@ -583,8 +607,9 @@ export const createTelemetry = (opts) => {
                     return response.ok !== false;
                 }
                 catch (error) {
-                    if (attempt === attempts - 1)
+                    if (attempt === attempts - 1) {
                         throw error;
+                    }
                 }
             }
             return false;
@@ -602,10 +627,17 @@ export const createTelemetry = (opts) => {
  */
 let invalidDropped = 0;
 export const droppedInvalidEvents = () => invalidDropped;
-/** `RETICLE_INTERNAL=1`, or the machine-wide marker file. Unreadable home → not internal. */
+/** The values of `RETICLE_INTERNAL` that mark a run, after trim and lower case. Anything else is not. */
+const INTERNAL_ON = new Set(['1', 'true', 'yes', 'on']);
+/**
+ * The one decision for the `internal` field on every event: `RETICLE_INTERNAL` set to an "on" value,
+ * or the machine-wide marker file. An explicit signal only, never read from a name, email or path.
+ * Unreadable home → not internal.
+ */
 const isInternal = (env, dir) => {
-    if ('1' === env[Env.INTERNAL] || 'true' === env[Env.INTERNAL])
+    if (INTERNAL_ON.has((env[Env.INTERNAL] ?? '').trim().toLowerCase())) {
         return true;
+    }
     try {
         return existsSync(join(dir, INTERNAL_MARKER_FILE));
     }

package/dist/telemetry/tool-refused.d.ts

@@ -15,7 +15,7 @@ import { RefusalReason, type NoSessionReason } from '@reticlehq/core/telemetry';
 export declare function notePendingNoSessionReason(reason: NoSessionReason | undefined): void;
 /** A call that was served. Breaks the retry chain: what follows it is not a retry of anything. */
 export declare function noteToolServed(): void;
-/** One refused call, reported with its cause and whether it was itself a retry. */
-export declare function reportToolRefused(tool: string, reason: RefusalReason): void;
+/** One refused call, reported with its cause, whether it was a retry, and the names of its arguments. */
+export declare function reportToolRefused(tool: string, reason: RefusalReason, args?: Record<string, unknown>): void;
 /** Tests only — the counters are process-lifetime, so each case has to start from zero. */
 export declare function resetToolRefusals(): void;

package/dist/telemetry/tool-refused.js

@@ -11,6 +11,7 @@
  * covered without anybody remembering to cover it.
  */
 import { RefusalReason, TelemetryActor, TelemetryEventKind, } from '@reticlehq/core/telemetry';
+import { describeToolParams } from './argument-shape.js';
 import { getTelemetry } from './telemetry.js';
 /**
  * Refusal events one daemon run will send.
@@ -54,8 +55,10 @@ export function notePendingNoSessionReason(reason) {
 export function noteToolServed() {
     lastRefusedTool = undefined;
 }
-/** One refused call, reported with its cause and whether it was itself a retry. */
-export function reportToolRefused(tool, reason) {
+/** How many argument names one refusal carries. A call with more is malformed in its own way. */
+const MAX_REFUSAL_PARAMS = 16;
+/** One refused call, reported with its cause, whether it was a retry, and the names of its arguments. */
+export function reportToolRefused(tool, reason, args = {}) {
     const retried = lastRefusedTool === tool;
     lastRefusedTool = tool;
     // Read and clear whatever the throw left, whether or not this refusal can use it: a reason left
@@ -71,6 +74,10 @@ export function reportToolRefused(tool, reason) {
             tool,
             reason,
             retried,
+            ...(() => {
+                const params = describeToolParams(args).slice(0, MAX_REFUSAL_PARAMS);
+                return 0 === params.length ? {} : { params };
+            })(),
             // Only where it means something. On any other refusal reason this field would be answering
             // a question nobody asked of it.
             ...(RefusalReason.NO_SESSION === reason && noSessionReason !== undefined

package/docs/architecture.md

@@ -115,14 +115,11 @@ This is plain, reviewable, version-controllable data, not a black box.
 
 ---
 
-## Open-core licensing (what's free, what's protected)
+## Licensing
 
-- The **protocol and the rules** (`open-verification`, `@reticlehq/core`, `@reticlehq/engine`) are **Apache-2.0**. The part that decides a verdict is the part a sceptical reader most wants to audit, so it is the part with no licence in the way.
-- The embeddable **SDK** (`@reticlehq/browser`, `@reticlehq/react` and the build adapters) is **Apache-2.0**, safe to ship inside your own app.
-- The **server / CLI** is under the **Functional Source License (FSL-1.1, Apache-2.0 future)**: source-available, converts to Apache-2.0 over time.
-- Enterprise-only features live behind a license gate and are clearly separated.
+Every npm package is **Apache-2.0**: the protocol and the rules (`open-verification`, `@reticlehq/core`, `@reticlehq/engine`), the embeddable SDK and its adapters, and the server, CLI, `init` and spec runner. The `reticle-tauri` crate is MIT.
 
-See [LICENSE](https://github.com/reticlehq/reticle/blob/main/LICENSE) and each package's own `LICENSE` file. The licensing _mechanism_ is open and inspectable; activation is offline (no phone-home).
+See [LICENSE](https://github.com/reticlehq/reticle/blob/main/LICENSE) and each package's own `LICENSE` file.
 
 ---
 

package/docs/cli/doctor.mdx

@@ -7,13 +7,14 @@ icon: stethoscope
 `reticle doctor` collapses the setup failure modes into one command. It is the first thing to run when something is wrong.
 
 ```bash
-npx @reticlehq/server doctor [--port N]
+npx @reticlehq/server doctor [--fix] [--port N]
 ```
 
 ## Flags
 
 | Flag | Type | Default | What it does |
 | --- | --- | --- | --- |
+| `--fix` | boolean | off | Repair what Reticle can repair safely, then run the checks again. See [Repair with --fix](#repair-with---fix) |
 | `--port N` | number | `RETICLE_PORT`, else the port in `.reticle.json`, else the daemon already serving this project, else `4400` | Which bridge port to diagnose |
 
 ## What it prints
@@ -50,10 +51,12 @@ When nothing has connected, the `sessions` line fails and the daemon's own diagn
 | Line | What it checks |
 | --- | --- |
 | `node` | The Node version running the CLI |
+| `mcp` | Which coding agents found on this machine have Reticle's MCP server registered. Fails when an agent is found without it, and names the agent and `reticle setup mcp` |
 | `chromium` | Whether the exact Chromium revision the bundled Playwright wants is on disk. The most common silent failure |
 | `daemon` | Whether the port holds a Reticle daemon, a foreign process (named where possible), or nothing. Adds a `version` line when the daemon's version or contract fingerprint disagrees with the CLI's |
 | `sessions` | Whether any page has actually connected. Zero is a FAILING check rather than a neutral note, because it is the state the setup most often stalls in: wired correctly, daemon up, nothing dialled in. When it is zero the daemon's own no-session diagnosis prints below the checklist |
 | `agent link` | Whether an MCP client has listed Reticle's tools on this port **and actually called one**. Every other row here checks a component; this one checks the hop between your agent and the daemon. It is possible for the SDK to be injected, a session to be live, and your client to show every tool enabled, while no request has ever crossed from the agent. That state passes every other check and is the one people lose hours to |
+| `launcher` | Only when an agent config starts Reticle from an installed copy (`node <path> mcp`) and that file does not exist, for example after `npm uninstall -g`. Names the agent, the path, and the command that writes a working entry |
 | `loopback` | Which of `localhost`'s two answers reaches the bridge. Printed **only when they disagree**. The daemon binds `127.0.0.1`, and a best-effort alias forwards `[::1]` to it so the name works everywhere. When that alias cannot open (IPv6 disabled, or something already holding `[::1]` on the port) the daemon serves IPv4 perfectly and a page told to dial `localhost` still cannot reach it, because Windows Chrome tries the IPv6 answer first. Every other row here goes green in that state |
 | `bridge port` | The port your app must dial, spelled out because mixing it up with the dev server port is the most common setup failure |
 | `port check` | Only when your project's configured port disagrees with the one the daemon is on. Prints the mismatch rather than leaving you to spot it across two lines |
@@ -113,9 +116,45 @@ The wanted revision and the root are both read back off the path Playwright itse
   before. That loop is why the line names the version to pin to.
 </Warning>
 
+## Repair with --fix
+
+When a row has a safe repair, a plain `doctor` run ends with one more line:
+
+```
+Run `reticle doctor --fix` to repair 2 of these.
+```
+
+`reticle doctor --fix` prints the checks, applies the safe repairs in a fixed order, runs the checks again, and prints one line for each repair and one for each row that still fails. A repair changes only Reticle's own state:
+
+| Order | Row | Repair | Done only when |
+| --- | --- | --- | --- |
+| 1 | `daemon` | Delete the pid file of a daemon that is not running | The process that the file names does not exist |
+| 2 | `daemon` | Stop a Reticle daemon that holds the port and does not answer, as `reticle restart` does | The holder's command line is a Reticle daemon, and it is still silent after a grace period. A different program and the agent's own `reticle mcp` proxy are never stopped |
+| 3 | `chromium` | Install the pinned Chromium of the bundled Playwright (a download) | No Chrome or Edge can stand in, and `RETICLE_CHROMIUM_PATH` is not set |
+| 4 | `launcher` | Run `reticle setup mcp`, which replaces Reticle's own entry | An agent config starts Reticle from an installed copy that does not exist. `setup mcp` keeps an existing Claude Code entry, so for Claude Code the step stays `claude mcp remove reticle -s user`, then `setup mcp` |
+| 5 | `mcp` | Run `reticle setup mcp` | An agent on this machine does not have Reticle registered |
+
+Each repair checks again before it acts, so a second `--fix` finds nothing to do and changes nothing.
+
+`--fix` never repairs a row that needs a change to your app, a process that Reticle cannot prove is its own daemon, or an action only you can do. For those rows it prints the step that the row names: for example `reticle init` for `project`, starting your agent for a stopped `daemon`, `reticle hook install` for `prompts`, a CSP or desktop change, or a version skew (restart the daemon when no other agent uses it).
+
+```
+reticle doctor --fix
+  daemon       pid file of a stopped daemon: fixed
+  daemon       a Reticle daemon that does not answer: nothing to do
+  chromium     Playwright's own Chromium: nothing to do
+  launcher     a registered launcher that does not exist: nothing to do
+  mcp          agent registrations: fixed
+  still needs: sync         ✗ off: this project is not linked: run `reticle connect`; no push yet
+```
+
+A registration takes effect when the agent reads its config again, so restart your agent after `mcp` is fixed.
+
 ## Exit codes
 
-Always `0`. `doctor` reports; it does not gate.
+A plain `doctor` always exits `0`. It reports; it does not gate.
+
+`doctor --fix` exits `0` only when no row fails after the repairs, and `1` otherwise.
 
 ## Worked example
 

package/docs/cli/help.mdx

@@ -33,7 +33,7 @@ Get started
   try         Watch Reticle drive a URL once and say which journeys work
 
 Check your app
-  verify      Check the saved flows against the running app; exit 0 means pass
+  verify      Check saved flows, or one claim with --expect, against the running app; exit 0 = pass
   gate        Fail unless passing checks cover the flows your changes touch
 
 Reticle on this machine
@@ -85,5 +85,7 @@ Two audiences, two channels: the structured line for logs and scripts, the plain
 | `1`  | Help was printed because something else was wrong |
 
 <Note>
-  A bare `reticle` with no arguments is **not** help. It is [`reticle serve`](/cli/serve).
+  A bare `reticle` with no arguments is **not** help. In a wired project it is [`reticle
+  serve`](/cli/serve). In a folder that Reticle has not wired, it gives a first verdict on the app:
+  see [the CLI reference](/cli).
 </Note>