@reticlehq/server 3.7.0 → 3.8.1

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

@@ -439,3 +439,48 @@ export function filterTools(tools, surface) {
     // every other MCP server the user has connected. surface-sizes.test.ts enforces it.
     return tools.filter((t) => CORE_TOOL_NAMES.has(t.name) || EXTENDED_TOOL_NAMES.has(t.name));
 }
+/**
+ * The MCP annotations of each Reticle tool: whether it changes anything, and whether it reaches
+ * past this machine. A client can decide approval from them: Codex's `writes` mode asks only
+ * for the tools that are not read-only.
+ *
+ * Read-only means that the tool changes neither the app nor the project's files. A tool that is
+ * not in the list is treated as a write, which is the safe side. No Reticle tool deletes data
+ * the user owns, so `destructiveHint` is always false.
+ */
+const READ_ONLY = new Set([
+    ReticleTool.SESSIONS,
+    ReticleTool.LOOK,
+    ReticleTool.SNAPSHOT,
+    ReticleTool.QUERY,
+    ReticleTool.INSPECT,
+    ReticleTool.OBSERVE,
+    ReticleTool.LINEAGE,
+    ReticleTool.WAIT_FOR,
+    ReticleTool.NETWORK,
+    ReticleTool.CONSOLE,
+    ReticleTool.ANIMATIONS,
+    ReticleTool.ASSERT,
+    ReticleTool.STATE,
+    ReticleTool.CAPABILITIES,
+    ReticleTool.CONTEXT,
+    ReticleTool.MAP,
+    ReticleTool.MEMORY,
+    ReticleTool.TOOLS,
+]);
+/** Tools that can send data off this machine or open any URL. */
+const OPEN_WORLD = new Set([
+    ReticleTool.NAVIGATE,
+    ReticleTool.SESSION,
+    ReticleTool.VERIFY,
+    ReticleTool.EXPLORE,
+    ReticleTool.FEEDBACK,
+    ReticleTool.RUN,
+]);
+export function toolAnnotations(name) {
+    return {
+        readOnlyHint: READ_ONLY.has(name),
+        destructiveHint: false,
+        openWorldHint: OPEN_WORLD.has(name),
+    };
+}

package/dist/surface/tools/tools.js

@@ -1,14 +1,16 @@
 import { TESTID_FOUND_UNDER_SCHEMA } from './query-hint-schema.js';
 import { z } from 'zod';
-import { EMPTY_SESSION_LIST_OUTPUT, emptySessionList, wireCallerBesideLiveSessions, } from './empty-session-list.js';
-import { AttrNamesSchema, EventType, QueryBy, ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { EMPTY_SESSION_LIST_OUTPUT, emptySessionList, nextStepBesideLiveSessions, } from './empty-session-list.js';
+import { AttrNamesSchema, QueryBy, ReticleCommand, SnapshotMode } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { withSizeCost } from '../../portal/session/output-budget.js';
 import { applySnapshotDelta, SnapshotCache } from './read/snapshot-delta.js';
+import { noteUnmountedRoot } from './read/snapshot-unmounted-note.js';
 import { asNumber, asRecord, asString } from '@reticlehq/core';
 import { countSchema } from './args/numeric-bounds.js';
-import { normalizeQueryArgs } from './read/query-shape.js';
+import { emptyQueryRefusal, normalizeQueryArgs } from './read/query-shape.js';
 import { shapeQueryResult } from './read/query-windowed.js';
+import { withUnsettledFind } from './act/unsettled-find.js';
 /**
  * The query strategies, derived from the enum in core — never retyped.
  *
@@ -28,6 +30,7 @@ import { BROWSER_TOOLS } from './browser-tools.js';
 import { FLOW_TOOLS } from '../../language/flows/flow-tools.js';
 import { INTENT_TOOLS } from '../../memory/intent/intent-tools.js';
 import { CONTEXT_TOOLS } from '../../judgement/runs/context-tools.js';
+import { MAP_TOOLS } from './map-tools.js';
 import { PROJECT_TOOLS } from '../../memory/project/project-tools.js';
 import { MEMORY_TOOLS } from '../../memory/recall/memory-tools.js';
 import { RUN_TOOLS } from '../../judgement/runs/run-tools.js';
@@ -75,6 +78,10 @@ export const RAW_TOOLS = withCompactEnvelope([
                 sessionId: z.string(),
                 url: z.string(),
                 projectId: z.string().optional(),
+                worktree: z
+                    .string()
+                    .optional()
+                    .describe('The linked git worktree, and its branch, whose dev server served this tab. Absent for the main checkout. A tab of another worktree runs other code: drive the one your change is in.'),
                 title: z.string().optional(),
                 adapters: z.array(z.string()),
                 hasCapabilities: z.boolean(),
@@ -86,6 +93,11 @@ export const RAW_TOOLS = withCompactEnvelope([
                     .string()
                     .optional()
                     .describe("Present only when this page's SDK version differs from the daemon's. A skewed pair connects and then disagrees about tool behaviour — usually surfacing as a bare -32000. Fix it before trusting any verdict from this session."),
+                sdkVersion: z.string().optional().describe("The page's SDK version, when it said."),
+                sdkBehind: z
+                    .string()
+                    .optional()
+                    .describe('Present only when the page SDK is a minor release or more behind the daemon. The page connects, but newer commands and fixes are not in it. Says how to update it.'),
                 window: z.string().optional().describe('Desktop window label (Tauri: main, setup…).'),
                 documentStatus: z
                     .number()
@@ -136,10 +148,8 @@ export const RAW_TOOLS = withCompactEnvelope([
             if (0 === sessions.length)
                 return emptySessionList(deps, sessions);
             // Another project's tab is up. This caller's project may still never have been wired.
-            const wired = await wireCallerBesideLiveSessions(deps, sessions);
-            if (wired === undefined)
-                return { sessions };
-            return { sessions: await list(), wired };
+            const nextStep = nextStepBesideLiveSessions(deps, sessions);
+            return nextStep === undefined ? { sessions } : { sessions, next_step: nextStep };
         },
     },
     {
@@ -159,6 +169,14 @@ export const RAW_TOOLS = withCompactEnvelope([
                 .boolean()
                 .optional()
                 .describe('Return only what changed since your last snapshot of the same scope/mode (mode:delta|unchanged). First call (or after a route change) still returns the full tree.'),
+            ids: z
+                .boolean()
+                .optional()
+                .describe('Add [testid=…] to each control that carries one: a stable identity for a harness mapping the app. Off by default; it costs tokens.'),
+            audit: z
+                .boolean()
+                .optional()
+                .describe('Also measure the page for what a person would see broken: text cut off with no ellipsis, controls drawn over each other, text under WCAG contrast. Returns `audit: [{ kind, ref, what, detail }]`. Off by default; it forces layout.'),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -216,7 +234,7 @@ export const RAW_TOOLS = withCompactEnvelope([
             note: z
                 .string()
                 .optional()
-                .describe('Why this result is not what it looks like. Four causes, all of which otherwise read as "the page is empty": a diff computed over a capped tree ("unchanged" is then partial); an interactive-mode tree emptied by leanness; a page whose elements all computed hidden; and an UNMOUNTED app, where the DOM under the scope holds almost nothing — that last one will not improve by waiting, so read reticle_console for an uncaught error instead.'),
+                .describe('Why this result is not what it looks like. Four causes, all of which otherwise read as "the page is empty": a diff computed over a capped tree ("unchanged" is then partial); an interactive-mode tree emptied by leanness; a page whose elements all computed hidden; and, on an unscoped snapshot, an UNMOUNTED app whose DOM holds almost nothing — that last one will not improve by waiting, so read reticle_console for an uncaught error instead.'),
             scopeMissing: z
                 .boolean()
                 .optional()
@@ -239,12 +257,14 @@ export const RAW_TOOLS = withCompactEnvelope([
             return commandOrThrow(deps, resolved.id, ReticleCommand.SNAPSHOT, {
                 scope: args['scope'],
                 mode,
+                ...(true === args['ids'] ? { ids: true } : {}),
+                ...(true === args['audit'] ? { audit: true } : {}),
             }).then((raw) => withSizeCost(noteUnmountedRoot(noteHiddenPage(noteEmptyLeanTree(applySnapshotDelta(raw, {
                 sessionId: resolved.id,
                 scope: asString(args['scope']) ?? '',
                 mode,
                 diff: true === args['diff'],
-            }, deps.snapshots ?? SNAPSHOT_CACHE), mode), mode), mode, resolved)));
+            }, deps.snapshots ?? SNAPSHOT_CACHE), mode), mode), mode, resolved, asString(args['scope']))));
         },
     },
     {
@@ -304,7 +324,7 @@ export const RAW_TOOLS = withCompactEnvelope([
                 states: z.array(z.string()),
                 visible: z.boolean(),
                 attrs: z
-                    .record(z.string())
+                    .record(z.string(), z.string())
                     .optional()
                     .describe('Present only for attributes requested via `attrs` and found on the element.'),
                 source: z
@@ -361,18 +381,18 @@ export const RAW_TOOLS = withCompactEnvelope([
                 splitText: z
                     .object({
                     ref: z.string().optional(),
+                    selector: z.string().optional(),
                     role: z.string().optional(),
                     name: z.string().optional(),
                 })
                     .passthrough()
                     .optional()
-                    .describe("Present when a TEXT search missed but the string IS on the page, split across this container's children. Retry as { scope: <ref>, self: true } — no text query can match a string no single element owns."),
+                    .describe("Present when a TEXT search missed but the string IS on the page, split across this container's children. Retry as { scope: <selector or ref>, self: true } — no text query can match a string no single element owns. The selector is present when the container carries a testid or an id, and can be written before the action runs."),
                 caseMiss: z
                     .string()
                     .optional()
                     .describe('Present when a case-exact TEXT check missed and the page shows the text in another case: what it shows. Retry with ignoreCase: true if the case does not matter.'),
-                // Declared here for the same reason presentRegions had to be: the browser emits it, and an
-                // undeclared field is stripped from structuredContent without a word.
+                // The browser emits this; undeclared, it would be stripped from structuredContent without a word.
                 nameNearMiss: z
                     .array(z.string())
                     .optional()
@@ -385,6 +405,14 @@ export const RAW_TOOLS = withCompactEnvelope([
                 .object({ bytes: z.number(), tokens: z.number() })
                 .optional()
                 .describe('Estimated size of this result — narrow with `name`/`scope`/`limit` if large.'),
+            unsettled: z
+                .object({
+                reason: z.string(),
+                inFlight: z.array(z.string()).optional(),
+                lastDomChangeMsAgo: z.number().optional(),
+            })
+                .optional()
+                .describe('Present only on zero matches read while the last act was still landing (a request it started still in flight, or the DOM changed under 500 ms ago). The 0 may only mean not rendered yet: wait instead of concluding it is absent.'),
             scopeMissing: z
                 .boolean()
                 .optional()
@@ -393,6 +421,10 @@ export const RAW_TOOLS = withCompactEnvelope([
         handler: (deps, rawArgs) => {
             // Accept the predicate's named-field spelling too — see query-shape.ts.
             const args = normalizeQueryArgs(rawArgs);
+            const empty = emptyQueryRefusal(args);
+            if (empty !== undefined)
+                return Promise.reject(empty);
+            const session = deps.sessions.resolve(asString(args['sessionId']));
             return commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.QUERY, {
                 by: args['by'],
                 value: args['value'],
@@ -408,7 +440,7 @@ export const RAW_TOOLS = withCompactEnvelope([
                 // now asserts the payload, because a comment is not a guard.
                 attrs: args['attrs'],
                 self: args['self'],
-            }).then((result) => withSizeCost(shapeQueryResult(result, args)));
+            }).then((result) => withSizeCost(withUnsettledFind(session, shapeQueryResult(result, args))));
         },
     },
     // reticle_inspect: one element in full detail. See inspect-tool.ts.
@@ -418,6 +450,7 @@ export const RAW_TOOLS = withCompactEnvelope([
     ...CONTRACT_TOOLS,
     ...INTENT_TOOLS,
     ...CONTEXT_TOOLS,
+    ...MAP_TOOLS,
     ...DOMAIN_TOOLS,
     // reticle_flow_save / reticle_flow_list / reticle_flow_load. See flow-tools.ts.
     ...FLOW_TOOLS,
@@ -519,7 +552,7 @@ export const MERGE_PLANS = [
     },
     {
         name: ReticleTool.VERIFY,
-        description: 'What is proved, and what is not — by action. Start from a change: { action: "affected" } names which saved flows must re-verify for the files you edited (pass `files`, and/or `since` for a git ref), and "change" goes further and actually replays them, answering with one `verified` plus `because`. `unknown` there is the honest answer when NO saved flow covers the change: nothing ran, so nothing was proved, and it is never reported as green. Without a change to start from: "flows" replays every saved flow for one consolidated suite verdict (deterministic, no LLM per flow), and "coverage" lists the interactive controls you have and have NOT driven this session — an untouched list still holding the controls your change affects means you are not done. "crawl" is the no-script option: it drives every reachable control itself and reports single-channel faults (console errors, failed requests, dead controls) and CONTRADICTIONS, two channels disagreeing about the same click — the false greens a human cannot see, because a human watches the screen and the screen looks correct. "explore" is the one to reach for on a project with NO saved flows: the Reticle Harness drives the app for you on the platform — pass a `persona` and it completes that whole journey — and RECORDS what it drove, so the next run replays it with no model in the loop and none of the driving costs your context. "mutate" grades the FLOW rather than the app: it breaks the endpoint a saved flow declared it depends on and replays it, and a flow that stays GREEN through a broken subject is a click sequence, not a test. "heal" repairs a flow whose LOCATOR drifted (a renamed testid), re-asserting the saved consequence before it writes and refusing when that stops firing — it heals a locator, never an intent. DESTRUCTIVE: crawl and explore really click, and may navigate or mutate state; "mutate" really fails a request on a driven page, and always puts it back.',
+        description: 'The Reticle Harness is { action: "explore" }: when the user asks for the Harness, or asks Reticle to drive and verify the app for you, call it and do not drive the app yourself. Every other action says what is proved, and what is not. Start from a change: { action: "affected" } names which saved flows must re-verify for the files you edited (pass `files`, and/or `since` for a git ref), and "change" goes further and actually replays them, answering with one `verified` plus `because`. `unknown` there is the honest answer when NO saved flow covers the change: nothing ran, so nothing was proved, and it is never reported as green. Without a change to start from: "flows" replays every saved flow for one consolidated suite verdict (deterministic, no LLM per flow), and "coverage" lists the interactive controls you have and have NOT driven this session — an untouched list still holding the controls your change affects means you are not done. "crawl" is the no-script option: it drives every reachable control itself and reports single-channel faults (console errors, failed requests, dead controls) and CONTRADICTIONS, two channels disagreeing about the same click — the false greens a human cannot see, because a human watches the screen and the screen looks correct. "explore" is the Reticle Harness: it drives the app for you on the platform — pass a `persona` and it completes that whole journey — and RECORDS what it drove, so the next run replays it with no model in the loop and none of the driving costs your context. "mutate" grades the FLOW rather than the app: it breaks the endpoint a saved flow declared it depends on and replays it, and a flow that stays GREEN through a broken subject is a click sequence, not a test. "heal" repairs a flow whose LOCATOR drifted (a renamed testid), re-asserting the saved consequence before it writes and refusing when that stops firing — it heals a locator, never an intent. DESTRUCTIVE: crawl and explore really click, and may navigate or mutate state; "mutate" really fails a request on a driven page, and always puts it back.',
         members: {
             change: ReticleTool.VERIFY_CHANGE,
             flows: ReticleTool.FLOW_VERIFY,
@@ -601,77 +634,6 @@ function noteEmptyLeanTree(result, mode) {
  * cannot know why, and a note that guessed would be the same kind of overconfident answer as the
  * empty tree it replaces.
  */
-/**
- * How much DOM there is under the mount container, when the tree is empty and nothing was skipped.
- *
- * A handful of elements is a container with nothing in it. React's own root div counts as one, and a
- * wrapper or two is ordinary, so this is deliberately not `=== 0`.
- */
-const UNMOUNTED_ROOT_MAX_ELEMENTS = 3;
-function crashEvidence(session) {
-    const since = asRecord(session)['eventsSince'];
-    if ('function' !== typeof since)
-        return undefined;
-    let events;
-    try {
-        events = since.call(session, 0);
-    }
-    catch {
-        return undefined;
-    }
-    if (!Array.isArray(events))
-        return undefined;
-    const errors = events.filter((e) => {
-        const type = asString(asRecord(e)['type']);
-        return EventType.CONSOLE_ERROR === type || EventType.ERROR_UNCAUGHT === type;
-    });
-    if (0 === errors.length)
-        return undefined;
-    const first = errors
-        .map((e) => asString(asRecord(asRecord(e)['data'])['message']))
-        .find((m) => undefined !== m && '' !== m);
-    return { count: errors.length, first: first ?? '' };
-}
-function noteUnmountedRoot(result, mode, session) {
-    if (SnapshotMode.STATUS === mode)
-        return result;
-    const row = asRecord(result);
-    if (0 !== asNumber(row['nodes']))
-        return result;
-    if (row['note'] !== undefined)
-        return result;
-    const elements = asNumber(row['domElements']);
-    if (elements === undefined || elements > UNMOUNTED_ROOT_MAX_ELEMENTS)
-        return result;
-    const mount = `the tree is empty because there is almost nothing in the DOM: ${String(elements)} ` +
-        `element(s) under this scope. That is a mount container with nothing rendered into it, not a ` +
-        `page whose contents were skipped — so the app is UNMOUNTED rather than slow, and waiting ` +
-        `will not change it. `;
-    // An uncaught error beside an empty mount container is the difference between "has not started"
-    // and "started and died", which are the two readings of this count and want opposite next moves.
-    // Nothing here is framework-specific, and deliberately so: the condition is a known mount
-    // container that holds nothing with an uncaught error beside it, which is as true of a Vue or
-    // Svelte root as a React one.
-    const crash = crashEvidence(session);
-    if (crash !== undefined) {
-        return {
-            ...row,
-            note: mount +
-                `The app did not merely fail to start — it CRASHED: ${String(crash.count)} uncaught ` +
-                `error(s) were logged in this session` +
-                ('' === crash.first ? '' : `, the first: "${crash.first}"`) +
-                `. Read reticle_console for the rest, and check anything that runs inside a framework ` +
-                `commit phase. Loading the app again will reproduce it rather than fix it.`,
-        };
-    }
-    return {
-        ...row,
-        note: mount +
-            `An app that was rendering and then stopped has usually thrown: read ` +
-            `reticle_console for an uncaught error, and check anything that runs inside a framework ` +
-            `commit phase. If the app has genuinely not started yet, load it and snapshot again.`,
-    };
-}
 function noteHiddenPage(result, mode) {
     if (SnapshotMode.STATUS === mode)
         return result;
@@ -787,7 +749,7 @@ export const MERGED_SURFACE_PLANS = [
             // lifecycle, where no member is the obvious bare meaning.
             defaultAction: 'list',
             description: 'By action: "list" (the default) shows connected tabs; "yield" is MANDATORY before you stop; "tune" hides or moves the HUD; "feedback" reports a problem. ' +
-                'In full: "list" is the first call to make, and on a project that has never connected it wires the app and names the files it changed under `wired`; "yield" hands control back to the human (mode: waiting|ask); "tune" takes `hud` (hidden, shown, removed until reload, or a corner) for when the HUD covers a control you must test, and `idleEndMs`; "feedback" files a report; "end", "resume", "messages", "review" and "narrate" manage the session and the human channel.',
+                'In full: "list" is the first call to make, and on a project that has never connected it changes no file: `next_step` names the zero-install lease and the consent question for wiring; "yield" hands control back to the human (mode: waiting|ask); "tune" takes `hud` (hidden, shown, removed until reload, or a corner) for when the HUD covers a control you must test, and `idleEndMs`; "feedback" files a report; "end", "resume", "messages", "review" and "narrate" manage the session and the human channel.',
         }
         : plan),
     ...SURFACE_MERGE_PLANS,

package/dist/telemetry/automation-hint.d.ts

@@ -12,6 +12,11 @@ interface AutomationInput {
  * here follows.
  */
 export declare function resolveAutomationHint(input: AutomationInput): AutomationHint | undefined;
+/**
+ * A CI runner: `CI` itself or a vendor's own variable. The one place a command line decides whether
+ * it is a pipeline or a person, so a run is credited to somebody whenever nothing says CI.
+ */
+export declare function isCiEnv(env: NodeJS.ProcessEnv): boolean;
 /** The real reading, taken once per process. */
 export declare function currentAutomationHint(env: NodeJS.ProcessEnv): AutomationHint | undefined;
 export {};

package/dist/telemetry/automation-hint.js

@@ -80,6 +80,13 @@ export function resolveAutomationHint(input) {
         return AutomationHint.HOSTED_WORKSPACE;
     return undefined;
 }
+/**
+ * A CI runner: `CI` itself or a vendor's own variable. The one place a command line decides whether
+ * it is a pipeline or a person, so a run is credited to somebody whenever nothing says CI.
+ */
+export function isCiEnv(env) {
+    return declared(env, ['CI', ...CI_VENDOR_ENV]);
+}
 /** The real reading, taken once per process. */
 export function currentAutomationHint(env) {
     return resolveAutomationHint({

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

@@ -1,3 +1,25 @@
+/**
+ * The one telemetry event a human directly causes: they typed a `reticle` command.
+ *
+ * Lives in its own module so `cli.ts` stays a dispatcher, and so the `_daemon` exclusion below sits
+ * next to the explanation of why it exists rather than buried in a startup function.
+ */
+import { TelemetryActor } from '@reticlehq/core/telemetry';
 /** True when this command represents a person typing something. Exported for the gate. */
 export declare function isHumanCliCommand(command: string): boolean;
+/**
+ * Who ran the command. A coding agent runs `reticle gate`, `init` and `verify` through a shell, and
+ * it marks the processes it spawns (see `envAgentClient`). Without the marker it is a person.
+ */
+export declare function cliActorOf(env: NodeJS.ProcessEnv): TelemetryActor;
+/**
+ * True when this command reports `reticle_installed`. Exported for its test.
+ *
+ * A probe (`--version`, `--help`, `telemetry`) on a new machine does not report the install. It
+ * leaves a pending file, and the first real command after it claims the report by deleting that
+ * file. So the report reads the install source that the machine state holds by then, and a probe
+ * with no marker cannot make it `unknown`. A machine with no pending file and no first run has
+ * reported its install already.
+ */
+export declare function claimInstallReport(command: string, firstRun: boolean, stateDir: string): boolean;
 export declare function reportCliRun(argv: readonly string[]): void;

package/dist/telemetry/cli-telemetry.js

@@ -4,10 +4,11 @@
  * Lives in its own module so `cli.ts` stays a dispatcher, and so the `_daemon` exclusion below sits
  * next to the explanation of why it exists rather than buried in a startup function.
  */
-import { TelemetryEventKind } from '@reticlehq/core/telemetry';
-import { DAEMON_INNER_COMMAND, knownCommand } from '../command/cli/cli-parse.js';
+import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core/telemetry';
+import { DAEMON_INNER_COMMAND, PROBE_COMMANDS, knownCommand } from '../command/cli/cli-parse.js';
 import { getTelemetry } from './telemetry.js';
 import { drainInstallTrace } from './install-trace.js';
+import { mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 /** Where the installer left its breadcrumbs. Same directory the telemetry id and opt-out live in. */
@@ -15,6 +16,10 @@ const RETICLE_STATE_DIR = process.env['RETICLE_STATE_DIR'] ?? join(homedir(), '.
 import { describeCliFlags } from './argument-shape.js';
 import { rememberInstallSource, resolveInstallSource } from './install-source.js';
 import { installPlatformLinkTelemetry } from './platform-linked.js';
+import { envAgentClient } from './agent-client.js';
+import { noteRunningVersion } from '../command/update/version-seen.js';
+import { wasNudged } from '../command/update/nudge-credit.js';
+import { SERVER_VERSION } from '../command/version/identity/server-version.js';
 /**
  * Report that a person ran a `reticle` subcommand.
  *
@@ -40,6 +45,67 @@ const AGENT_TRANSPORT_COMMAND = 'mcp';
 export function isHumanCliCommand(command) {
     return command !== AGENT_TRANSPORT_COMMAND && command !== DAEMON_INNER_COMMAND;
 }
+/**
+ * Who ran the command. A coding agent runs `reticle gate`, `init` and `verify` through a shell, and
+ * it marks the processes it spawns (see `envAgentClient`). Without the marker it is a person.
+ */
+export function cliActorOf(env) {
+    return envAgentClient(env) === undefined ? TelemetryActor.HUMAN : TelemetryActor.AGENT;
+}
+/** Set by a probe on a new machine: the install is not reported yet. */
+const INSTALL_PENDING_FILE = 'install-pending';
+/**
+ * True when this command reports `reticle_installed`. Exported for its test.
+ *
+ * A probe (`--version`, `--help`, `telemetry`) on a new machine does not report the install. It
+ * leaves a pending file, and the first real command after it claims the report by deleting that
+ * file. So the report reads the install source that the machine state holds by then, and a probe
+ * with no marker cannot make it `unknown`. A machine with no pending file and no first run has
+ * reported its install already.
+ */
+export function claimInstallReport(command, firstRun, stateDir) {
+    const pending = join(stateDir, INSTALL_PENDING_FILE);
+    if (PROBE_COMMANDS.has(command)) {
+        if (firstRun) {
+            try {
+                mkdirSync(stateDir, { recursive: true });
+                writeFileSync(pending, '');
+            }
+            catch {
+                /* an unwritable home: the install is not reported, as with an ephemeral id */
+            }
+        }
+        return false;
+    }
+    if (firstRun) {
+        return true;
+    }
+    try {
+        unlinkSync(pending);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Send `version_changed` when this start runs a different version from the last start on this
+ * machine. Every start does this, the daemon too: an upgrade through `npx @reticlehq/server@latest`
+ * never runs `reticle update`, so the updater alone saw almost no version move.
+ */
+function reportVersionMove() {
+    const moved = noteRunningVersion(SERVER_VERSION, RETICLE_STATE_DIR);
+    if (moved === undefined) {
+        return;
+    }
+    void getTelemetry().emit(TelemetryEventKind.VERSION_CHANGED, {
+        detach: true,
+        versionChange: {
+            ...moved,
+            ...(wasNudged(moved.to, RETICLE_STATE_DIR) ? { nudged: true } : {}),
+        },
+    });
+}
 export function reportCliRun(argv) {
     const firstArg = argv[0];
     /*
@@ -59,29 +125,32 @@ export function reportCliRun(argv) {
     drainInstallTrace(RETICLE_STATE_DIR);
     // Before anything reads it: a channel declared on THIS command outlives it.
     rememberInstallSource(process.env, RETICLE_STATE_DIR);
-    if (firstArg === DAEMON_INNER_COMMAND)
+    reportVersionMove();
+    if (firstArg === DAEMON_INNER_COMMAND) {
         return;
+    }
     const command = knownCommand(firstArg);
     const telemetry = getTelemetry();
-    // FIRST — before the human-command filter. The install happened whichever command ran, and on most
-    // machines the very first contact is the agent spawning `reticle mcp`, which that filter excludes.
+    // FIRST — before the human-command filter. The install happened whichever real command ran, and on
+    // most machines the very first contact is the agent spawning `reticle mcp`, which that filter excludes.
     // Behind the filter this event never fires at all on an install that only ever runs `reticle mcp`.
     // `detach` so a quick command (`version`/`gate`) exits immediately instead of waiting out the POST.
-    if (telemetry.firstRun)
+    if (claimInstallReport(command, telemetry.firstRun, RETICLE_STATE_DIR)) {
         void telemetry.emit(TelemetryEventKind.RETICLE_INSTALLED, {
             detach: true,
             // WHICH published route brought this machine in. Self-declared by the channel, never inferred
             // — see install-source.ts for which of the four routes can actually carry the marker.
             installSource: resolveInstallSource(process.env, RETICLE_STATE_DIR),
         });
-    if (!isHumanCliCommand(command))
+    }
+    if (!isHumanCliCommand(command)) {
         return;
+    }
     void telemetry.emit(TelemetryEventKind.CLI_COMMAND_RUN, {
         detach: true,
-        // No `actor`: with the agent's transport excluded, this event is human BY DEFINITION, so the
-        // field would be constant here — zero information. `actor` stays where it earns its place:
-        // verification_completed and bug_found, where it splits the agent's own loop from a human or
-        // CI-triggered run.
+        // The agent's transport (`mcp`) is excluded above, but an agent also runs commands through a
+        // shell. `actor` splits those from a command a person typed.
+        actor: cliActorOf(process.env),
         // A fixed, low-cardinality vocabulary WE define, so it is safe to send whole and it is the closest
         // honest read we have on intent: `verify` and `gate` mean something very different from `status`.
         // An unrecognized first arg reports as `unknown` rather than being echoed — an echo would put

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

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

package/dist/telemetry/daemon-telemetry.js

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

package/dist/telemetry/feedback-cli.d.ts

@@ -14,7 +14,7 @@ import { TelemetryAction } from '../command/cli/cli-parse.js';
  * What is sent is PRINTED before it goes, every time. A channel that carries free text and does not
  * show you the payload is asking for trust it has not earned.
  */
-export declare function handleFeedback(text: string, rating: number | undefined, bug: boolean, feedbackKind?: string, agent?: boolean): Promise<void>;
+export declare function handleFeedback(text: string, rating: number | undefined, bug: boolean, feedbackKind?: string, agent?: boolean, contact?: string): Promise<void>;
 /**
  * `reticle telemetry [status|enable|disable]` — the user-facing control for anonymous usage metrics.
  * `disable` persists a machine-wide opt-out (survives shells, unlike RETICLE_TELEMETRY=0); `status`

package/dist/telemetry/feedback-cli.js

@@ -1,5 +1,5 @@
 import { FeedbackKind, FeedbackSource } from '@reticlehq/core/telemetry';
-import { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from '../command/cli/cli-parse.js';
+import { AGENT_FLAG, BUG_FLAG, CONTACT_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from '../command/cli/cli-parse.js';
 import { describeFeedbackPayload, submitFeedback } from './feedback.js';
 import { describeTelemetry, setTelemetryEnabled } from './telemetry.js';
 import { TelemetryAction } from '../command/cli/cli-parse.js';
@@ -18,14 +18,15 @@ import { TelemetryAction } from '../command/cli/cli-parse.js';
  * What is sent is PRINTED before it goes, every time. A channel that carries free text and does not
  * show you the payload is asking for trust it has not earned.
  */
-export async function handleFeedback(text, rating, bug, feedbackKind, agent = false) {
+export async function handleFeedback(text, rating, bug, feedbackKind, agent = false, contact) {
     const line = (s) => {
         process.stdout.write(`${s}\n`);
     };
     if ('' === text && rating === undefined) {
-        line(`usage: reticle feedback [${RATING_FLAG} 1-5] [${BUG_FLAG}] "what worked, what didn't"`);
+        line(`usage: reticle feedback [${RATING_FLAG} 1-5] [${BUG_FLAG}] [${CONTACT_FLAG} you@example.com] "what worked, what didn't"`);
         line(`       agents: reticle feedback ${AGENT_FLAG} ${KIND_FLAG} <${FEEDBACK_KINDS.join('|')}> "what happened"`);
         line('       your words go to the maintainers; nothing from your app is ever included.');
+        line(`       ${CONTACT_FLAG} adds an address for a reply. It is sent only when you give it.`);
         process.exitCode = 1;
         return;
     }
@@ -40,8 +41,12 @@ export async function handleFeedback(text, rating, bug, feedbackKind, agent = fa
         // A rating with no words is a real report, but the schema wants text — say what the rating means.
         text: '' === text ? `rated ${String(rating)}/5 with no comment` : text,
         ...(rating !== undefined ? { rating } : {}),
+        ...(contact !== undefined ? { contact } : {}),
     });
     line(`sending      ${JSON.stringify(describeFeedbackPayload(receipt.context))}`);
+    if (contact !== undefined) {
+        line(`contact      ${contact} (sent so that the maintainers can answer you)`);
+    }
     if (receipt.redacted.length > 0) {
         line(`redacted     ${receipt.redacted.join(', ')} (removed before sending)`);
     }

package/dist/telemetry/feedback.d.ts

@@ -44,7 +44,7 @@ export declare function summarizeTrace(trace: string): string;
 /** True when the feedback channel is switched off on its own (the emitter's switches apply as well). */
 export declare function feedbackDisabled(env?: NodeJS.ProcessEnv): boolean;
 /** What the author supplies; the environment context is detected, never asked for. */
-type FeedbackInput = Pick<Feedback, 'source' | 'kind' | 'text' | 'trace' | 'rating' | 'need' | 'impact' | 'currentApproach' | 'model'>;
+type FeedbackInput = Pick<Feedback, 'source' | 'kind' | 'text' | 'trace' | 'rating' | 'need' | 'impact' | 'currentApproach' | 'model' | 'contact'>;
 interface FeedbackReceipt {
     /**
      * DELIVERY confirmed. Only ever true when the send was awaited and the endpoint accepted it —